[comment]: # ({7074b2d8-be6356d8})
# 2 时钟

[comment]: # ({/7074b2d8-be6356d8})

[comment]: # ({4044e835-9d7a8838})
### 描述

这些参数及对应仪表板小组件字段objects的可选属性值，可用于配置`dashboard.create`和`dashboard.update`方法中的[*Clock*](/manual/web_interface/frontend_sections/dashboards/widgets/clock)小组件。

::: noteimportant
仪表板创建或update过程中不会验证`fields`小组件的属性。  
这允许用户修改[built-in widgets](/manual/web_interface/frontend_sections/dashboards/widgets)和create[custom widgets](/devel/modules/tutorials/widget)，但也存在错误创建或更新小组件的风险。  
为确保成功创建或update*时钟*小组件，请参考下文表格中列出的参数行为规范。

:::

[comment]: # ({/4044e835-9d7a8838})

[comment]: # ({ec52e598-28857267})
### 参数

*时钟* 小部件支持以下参数。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Refresh interval* | 0 | rf_rate | 0 - 无刷新；<br>10 - 10 秒；<br>30 - 30 秒；<br>60 - 1 分钟；<br>120 - 2 分钟；<br>600 - 10 分钟；<br>900 - *（默认）* 15 分钟。
| *Time type* | 0 | time_type | 0 - *(默认)* 本地时间；<br>1 - 服务器时间；<br>2 - 主机 时间。 |
| *Clock type* | 0 | clock_type | 0 - *(默认)* 模拟量；<br>1 - 数字量。 |
如果将 *时间类型* 设定为 "主机 时间"，则支持以下参数。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Item* | 4 | itemid.0 | [Item](/manual/api/reference/item/get) ID.<br><br>[参数行为](/manual/api/reference_commentary#参数行为):<br>- *required* |
如果将*时钟类型（Clock type）*设置为“Digital”，则支持以下参数。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Show* | 0 | show.0 | 1 - 日期；<br>2 - *(默认)* 时间；<br>3 - 时区。<br><br>注意：要配置多个值，请为每个值使用递增的属性名称编号，在仪表板 widget 字段 object 中create 置。 |

[comment]: # ({/ec52e598-28857267})

[comment]: # ({7cfdce97-ab3ddf88})
#### 高级配置

如果将*时钟类型*设置为“数字”，则支持以下高级配置参数。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Background color* | 1 | bg_color | 十六进制颜色代码（例如：FF0000）。<br><br>默认值：""（空）。 |

[comment]: # ({/7cfdce97-ab3ddf88})

[comment]: # ({557d1498-9f05ef41})
##### 日期

如果 *时钟类型* 设置为 "Digital"，并且 *显示* 设置为 "日期"，则支持以下高级配置参数。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Bold* | 0 | date_bold | 0 - *(默认)* 禁用;<br>1 - 启用。 |
| *Color* | 1 | date_color | 十六进制颜色代码（例如 `FF0000`）。<br><br>默认值: `""`（空）。 |

[comment]: # ({/557d1498-9f05ef41})

[comment]: # ({d2ce0251-76db53db})
##### 时间

以下高级配置参数在将 *时钟类型* 设置为 "数字" 且 *显示* 设置为 "时间" 时可用。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Bold* | 0 | time_bold | 0 - *(默认)* 已禁用；<br>1 - 已启用。 |
| *Color* | 1 | time_color | 十六进制颜色代码（例如 `FF0000`）。<br><br>默认值： `""`（空）。 |
| *Seconds* | 0 | time_sec | 0 - 已禁用；<br>1 - *(默认)* 已启用。 |
| *Format* | 0 | time_format | 0 - *(默认)* 24 小时制；<br>1 - 12 小时制。 |

[comment]: # ({/d2ce0251-76db53db})

[comment]: # ({53435cd2-b6649dee})
##### 时区

如果将 *时钟类型* 设置为 "数字"，并将 *显示* 设置为 "时区"，则支持以下高级配置参数。

| 参数 | [仪表板小部件字段](/manual/api/reference/dashboard/object#仪表板小部件字段) | 名称 | 值 |
|-----|-|-----|-------------------|
| *Bold* | 0 | tzone_bold | 0 - *(默认)* 禁用;<br>1 - 启用。 |
| *Color* | 1 | tzone_color | 十六进制颜色代码（例如 `FF0000`）。<br><br>默认值: `""`（空）。 |
| *Time zone* | 1 | tzone_timezone | 有效的时区 string（例如 `Europe/Riga`、`system`、`UTC` 等）。有关支持的时区完整列表，请参阅 [PHP documentation](https://www.php.net/manual/en/timezones.php)。<br><br>默认值: `local`。<br><br>[参数行为](/manual/api/reference_commentary#参数行为):<br>- 如果 *时间类型* 设置为 "本地时间" 或 "服务器时间"，则为 *支持* |
| *Format* | 0 | tzone_format | 0 - *(默认)* 简短;<br>1 - 完整。<br><br>[参数行为](/manual/api/reference_commentary#参数行为):<br>- 如果 *时间类型* 设置为 "本地时间" 或 "服务器时间"，则为 *支持* |

[comment]: # ({/53435cd2-b6649dee})

[comment]: # ({7b4615c3-3b5604a0})
### 示例

以下示例仅用于描述为*时钟*小部件配置仪表板 widget 字段 objects 的过程。
有关配置仪表板的更多信息，请参见 [`dashboard.create`](/manual/api/reference/dashboard/create)。

[comment]: # ({/7b4615c3-3b5604a0})

[comment]: # ({31efb49f-4be326f4})
#### 配置*时钟*部件

配置一个*时钟*小部件get，以自定义的数字时钟形式显示本地日期、时间和时区。

[执行请求](/manual/api#执行请求):


```json
{
    "jsonrpc": "2.0",
    "method": "dashboard.create",
    "params": {
        "name": "My dashboard",
        "display_period": 30,
        "auto_start": 1,
        "pages": [
            {
                "widgets": [
                    {
                        "type": "clock",
                        "name": "Clock",
                        "x": 0,
                        "y": 0,
                        "width": 12,
                        "height": 3,
                        "view_mode": 0,
                        "fields": [
                            {
                                "type": 0,
                                "name": "clock_type",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "show.0",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "show.1",
                                "value": 2
                            },
                            {
                                "type": 0,
                                "name": "show.2",
                                "value": 3
                            },
                            {
                                "type": 1,
                                "name": "date_color",
                                "value": "E1E1E1"
                            },
                            {
                                "type": 0,
                                "name": "time_bold",
                                "value": 1
                            },
                            {
                                "type": 1,
                                "name": "tzone_color",
                                "value": "E1E1E1"
                            },
                            {
                                "type": 1,
                                "name": "tzone_timezone",
                                "value": "Europe/Riga"
                            },
                            {
                                "type": 0,
                                "name": "tzone_format",
                                "value": 1
                            }
                        ]
                    }
                ]
            }
        ],
        "userGroups": [
            {
                "usrgrpid": 7,
                "permission": 2
            }
        ],
        "users": [
            {
                "userid": 1,
                "permission": 3
            }
        ]
    },
    "id": 1
}
```
响应：


```json
{
    "jsonrpc": "2.0",
    "result": {
        "dashboardids": [
            "3"
        ]
    },
    "id": 1
}
```

[comment]: # ({/31efb49f-4be326f4})

[comment]: # ({e9d30322-c9d720b7})
### 另请参阅

-   [Dashboard widget field](/manual/api/reference/dashboard/object#dashboard-widget-field)
-   [`dashboard.create`](/manual/api/reference/dashboard/create)
-   [`dashboard.update`](/manual/api/reference/dashboard/update)

[comment]: # ({/e9d30322-c9d720b7})