jackiedo/timezonelist

用于在Laravel中创建时区列表框的小型包

维护者

详细信息

github.com/JackieDo/Timezone-List

源代码

问题

安装次数: 300,661

依赖项: 1

建议者: 0

安全性: 0

星标: 92

关注者: 3

分叉: 20

开放问题: 2

5.1.3 2022-03-17 15:10 UTC

Requires

MIT f1c64d0159b4401a78c7ab536505175238c38837

  • Jackie Do <anhvudo.woop@gmail.com>

laraveltimezonetimezonestimezonelist

This package is auto-updated.

Last update: 2024-09-17 20:43:09 UTC

README

Fix coding standards Latest Stable Version Total Downloads License

概览

功能

  • 在 Laravel 中渲染时区列表框（选择元素）
  • 在 Laravel 中渲染时区数组

版本和兼容性

目前，Timezone-List的一些分支与以下版本的Laravel框架兼容

本文档适用于5.x分支

文档

安装

您可以通过以下步骤通过Composer安装此包

步骤 1 - 需求包

在应用程序目录的根目录下，运行以下命令（在任何终端客户端中）

$ composer require jackiedo/timezonelist

注意：由于Laravel 5.5，服务提供者和别名是自动注册的。但是，如果您使用的是Laravel 5.4及更早版本，则必须手动注册服务提供者和外观。执行以下步骤

步骤 2 - 注册服务提供者

打开 config/app.php，并在提供者部分添加新行

...
Jackiedo\Timezonelist\TimezonelistServiceProvider::class,

步骤 3 - 注册外观别名

在文件 config/app.php 的别名部分添加以下行

'Timezonelist' => Jackiedo\Timezonelist\Facades\Timezonelist::class,

用法

使用外观操作

Laravel Timezone List有一个外观，其完全限定名称为Jackiedo\Timezonelist\Facades\Timezonelist。您可以通过此外观执行所有操作。

示例

<?php

namespace Your\Namespace;

use Jackiedo\Timezonelist\Facades\Timezonelist;

class YourClass
{
    public function yourMethod()
    {
        $return = Timezonelist::doSomething();
    }
}

注意：如果在安装步骤中已注册外观别名，那么在不使用命名空间的区域（例如视图...），您可以完全使用该外观别名代替完全限定外观命名空间。

示例： (用于 resources/views/demo.blade.php 文件)

<div class="form-group">
    {!! Timezonelist::doSomething() !!}
</div>

作为常规类使用

您可以通过 Jackiedo\Timezonelist\Timezonelist 类像使用常规对象类一样使用该包。

示例

namespace Your\Namespace;

use Jackiedo\Timezonelist\Timezonelist;

class YourClass
{
    public function yourMethod()
    {
        $timezoneList = new Timezonelist;

        $return = $timezoneList->doSomething();
    }
}

可用方法

渲染时区列表框

语法

/**
 * Create a select box of timezones.
 *
 * @param string            $name       The name of the select tag
 * @param null|string       $selected   The selected value
 * @param null|array|string $attr       The HTML attributes of select thag
 * @param bool              $htmlencode Use HTML entities for values of select tag
 *
 * @return string
 */
public function toSelectBox($name, $selected = null, $attr = null, $htmlencode = true);

/**
 * Alias of the `toSelectBox()` method.
 *
 * @deprecated 6.0.0 This method name no longer matches the semantics
 */
public function create($name, $selected = null, $attr = null, $htmlencode = true);

注意：在6.x版本中，将移除create()方法

示例

echo Timezonelist::toSelectBox('timezone');

这将输出以下HTML代码

<select name="timezone">
    <optgroup label="General">
        <option value="GMT">GMT timezone</option>
        <option value="UTC">UTC timezone</option>
    </optgroup>
    <optgroup label="Africa">
        <option value="Africa/Abidjan">(GMT/UTC + 00:00) Abidjan</option>
        <option value="Africa/Accra">(GMT/UTC + 00:00) Accra</option>
        <option value="Africa/Addis_Ababa">(GMT/UTC + 03:00) Addis Ababa</option>
        <option value="Africa/Algiers">(GMT/UTC + 01:00) Algiers</option>
        <option value="Africa/Asmara">(GMT/UTC + 03:00) Asmara</option>
        <option value="Africa/Bamako">(GMT/UTC + 00:00) Bamako</option>
        <option value="Africa/Bangui">(GMT/UTC + 01:00) Bangui</option>
        <option value="Africa/Banjul">(GMT/UTC + 00:00) Banjul</option>
        <option value="Africa/Bissau">(GMT/UTC + 00:00) Bissau</option>

        ...
    </optgroup>
    <optgroup label="America">
        <option value="America/Adak">(GMT/UTC - 10:00) Adak</option>
        <option value="America/Anchorage">(GMT/UTC - 09:00) Anchorage</option>
        <option value="America/Anguilla">(GMT/UTC - 04:00) Anguilla</option>
        <option value="America/Antigua">(GMT/UTC - 04:00) Antigua</option>
        <option value="America/Araguaina">(GMT/UTC - 03:00) Araguaina</option>
        <option value="America/Argentina/Buenos_Aires">(GMT/UTC - 03:00) Argentina/Buenos Aires</option>
        <option value="America/Argentina/Catamarca">(GMT/UTC - 03:00) Argentina/Catamarca</option>
        <option value="America/Argentina/Cordoba">(GMT/UTC - 03:00) Argentina/Cordoba</option>
        <option value="America/Argentina/Jujuy">(GMT/UTC - 03:00) Argentina/Jujuy</option>

        ...
    </optgroup>

    ...
</select>

Timezonelist::toSelectBox() 方法有四个参数

  • 第一个参数是必需的，它是渲染选择标签的name属性
  • 第二个参数用于设置列表框的选中值
  • 第三个参数用于设置选择标签的HTML属性
  • 第四个参数允许在渲染的选择标签中使用一些HTML实体。其目的是使元素看起来更好。

示例

// Render a select tag with the name `timezone` and the `Africa/Asmara` option preselected
Timezonelist::toSelectBox('timezone', 'Africa/Asmara');

// Render tag with some HTML attributes
Timezonelist::toSelectBox('timezone', null, [
    'id'    => 'timezone',
    'class' => 'styled',
    ...
]);

// Or with other method
Timezonelist::toSelectBox('timezone', null, 'id="timezone" class="styled"');

第四个参数的示例差异

Example-render-select-tag

渲染时区数组

语法

/**
 * Create a timezone array.
 *
 * @param bool $htmlencode Use HTML entities for items
 *
 * @return mixed
 */
public function toArray($htmlencode = true);

示例

$timezoneList = Timezonelist::toArray(false);

// The returned list will be
// [
//     "General" => [
//         "GMT" => "(GMT/UTC + 00:00) GMT",
//         "UTC" => "(GMT/UTC + 00:00) UTC",
//     ],
//     "Africa" => [
//         "Africa/Abidjan "    => "(GMT/UTC + 00:00) Abidjan",
//         "Africa/Accra"       => "(GMT/UTC + 00:00) Accra",
//         "Africa/Addis_Ababa" => "(GMT/UTC + 03:00) AddisAbaba",
//         "Africa/Algiers"     => "(GMT/UTC + 01:00) Algiers",
//         "Africa/Asmara"      => "(GMT/UTC + 03:00) Asmara",
//         ...
//     ],
//     "America" => [
//         "America/Adak"      => "(GMT/UTC - 09:00) Adak",
//         "America/Anchorage" => "(GMT/UTC - 08:00) Anchorage",
//         "America/Anguilla"  => "(GMT/UTC - 04:00) Anguilla",
//         "America/Antigua"   => "(GMT/UTC - 04:00) Antigua",
//         "America/Araguaina" => "(GMT/UTC - 03:00) Araguaina",
//         ...
//     ],
//     ...
// ]

筛选返回列表

默认情况下，toSelectBox、toArray... 方法将返回由11个组组成的时区列表（一个通用组和10个对应于大洲的组）

  • 一般
  • 非洲
  • 美洲
  • 南极洲
  • 北极
  • 亚洲
  • 大西洋
  • 澳大利亚
  • 欧洲
  • 印度洋
  • 太平洋

在某些情况下，我们不想在列表中包含一些指定的组，我们可以通过以下方法之一来完成

获取一些指定的组

语法

/**
 * Set the filter of the groups want to get.
 *
 * @param array $groups
 *
 * @return $this
 */
public function onlyGroups($groups = []);

示例

...
$return = Timezonelist::onlyGroups(['Asia', 'America'])->toSelectBox('timezone');

排除一些指定的组

语法

/**
 * Set the filter of the groups do not want to get.
 *
 * @param array $groups
 *
 * @return $this
 */
public function excludeGroups($groups = []);

示例

...
$return = Timezonelist::excludeGroups(['General'])->toArray();

更改返回列表的布局

在某些情况下，我们需要改变我们将要接收的列表形式，我们可以通过以下方法之一来完成

决定是否拆分组

语法

/**
 * Decide whether to split group or not.
 *
 * @param bool $status
 *
 * @return $this
 */
public function splitGroup($status = true);

示例

$return = Timezonelist::splitGroup(false)->excludeGroups(['General'])->toSelectBox('timezone');

决定是否显示时区偏移量

语法

/**
 * Decide whether to show the offset or not.
 *
 * @param bool $status
 *
 * @return $this
 */
public function showOffset($status = true);

示例

$return = Timezonelist::showOffset(false)->excludeGroups(['General'])->toSelectBox('timezone');

重置所有配置并返回新列表

始终记住，如果我们通过外观（Facade）使用包方法，我们实际上是在使用一个 静态 接口到类。这意味着过滤器和布局设置将始终为下一次调用保存。如果我们不想重用这些设置，我们必须在下次调用中执行以下方法

语法

/**
 * Return new static to reset all config.
 *
 * @return $this
 */
public function reset();

示例

// Genrate one select box, exclude two groups of timezones, Asia and Africa
$selectBox = Timezonelist::excludeGroups(['Asia', 'Africa'])->toSelectBox('timezone');

$list1 = Timezonelist::toArray();         // Two groups, Asia and Africa, will not be loaded into the result
$list2 = Timezonelist::reset()->toArray() // All groups will be loaded

贡献者

这个项目之所以存在，是因为所有它的 贡献者。

许可证

MIT © Jackie Do