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

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

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

各个仪表盘组件字段对象中的这些参数和可用属性值允许在`dashboard.create` 和 `dashboard.update` 方法中配置[*时钟*](/manual/web_interface/frontend_sections/dashboards/widgets/clock)组件

::: noteimportant
在创建或更新仪表盘期间不会验证组件的 `fields` 属性。
这个方法允许用户修改[内置组件](/manual/web_interface/frontend_sections/dashboards/widgets)和创建[自定义组件](/devel/modules/tutorials/widget)，但也会导致存在错误创建或更新组件的风险。
为确保成功创建或更新*时钟*组件，请参阅下表中概述的参数行为。
:::

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

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

*时钟*组件支持以下参数：

|参数|[类型](/manual/api/reference/dashboard/object#仪表盘组件字段)|参数名称|参数值或参数说明|
|-----|-|-----|-------------------|
|*刷新频率*|0|rf_rate|0 - 不刷新；<br>10 - 10 秒；<br>30 - 30 秒；<br>60 - 1 分钟；<br>120 - 2 分钟；<br>600 - 10 分钟；<br>900 - *(默认)* 15 分钟。|
|*时间类型*|0|time_type|0 - *(默认)* 本地时间；<br>1 - 服务器时间；<br>2 - 主机时间。|
|*时钟类型*|0|clock_type|0 - *(默认)* 模拟时钟；<br>1 - 数字时钟。|

当 *时间类型* 设置为 "主机时间" 时，以下参数可用：

|参数|[类型](/manual/api/reference/dashboard/object#仪表盘组件字段)|参数名称|参数值或参数说明|
|-----|-|-----|-------------------|
|*监控项*|4|itemid.0|[监控项](/manual/api/reference/item/get) ID。<br><br>[参数行为](/manual/api/reference_commentary#参数行为)：<br>- *必需的*。|

当 *时钟类型* 设置为 "数字时钟" 时，以下参数可用：

|参数|[类型](/manual/api/reference/dashboard/object#仪表盘组件字段)|参数名称|参数值或参数说明|
|-----|-|-----|-------------------|
|*显示*|0|show.0|1 - 日期；<br>2 - *(默认)* 时间；<br>3 - 时区。<br><br>注意：如果需要配置多个值，则需要给每个值创建一个仪表盘组件字段对象，参数名称 `show.0` 中的数字按照顺序进行递增。|

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

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

当 *时钟类型* 设置为 "数字时钟" 时，以下参数可用：

|参数|[类型](/manual/api/reference/dashboard/object#仪表盘组件字段)|参数名称|参数值或参数说明|
|-----|-|-----|-------------------|
|*背景颜色*|1|bg_color|十六进制颜色代码(例如：`FF0000`)。<br><br>默认值： `""` (空)。|

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

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

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

|参数|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*粗体*|0|date_bold|0 - *(默认)* 禁用；<br>1 - 启用。|
|*颜色*|1|date_color|十六进制颜色代码（例如 `FF0000`）。<br><br>默认值：`""`（空）。|

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

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

如果 *Clock type* 设置为“Digital”，且 *Show* 设置为“Time”，则支持以下高级配置参数。

|参数|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*粗体*|0|time_bold|0 - *(默认)* 禁用；<br>1 - 启用。|
|*颜色*|1|time_color|十六进制颜色代码（例如 `FF0000`）。<br><br>默认值：`""`（空）。|
|*秒*|0|time_sec|0 - 禁用；<br>1 - *(默认)* 启用。|
|*格式*|0|time_format|0 - *(默认)* 24 小时制；<br>1 - 12 小时制。|

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

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

如果 *Clock type* 设置为“Digital”，且 *Show* 设置为“Time zone”，则支持以下高级配置参数。

|参数|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*Bold*|0|tzone_bold|0 - *(默认)* 禁用；<br>1 - 启用。|
|*Color*|1|tzone_color|十六进制颜色代码（例如 `FF0000`）。<br><br>默认值：`""`（空）。|
|*Time zone*|1|tzone_timezone|有效的时区字符串（例如 `Europe/Riga`、`system`、`UTC` 等）。有关支持的时区完整列表，请参见 [PHP documentation](https://www.php.net/manual/en/timezones.php)。<br><br>默认值：`local`。<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior)：<br>- 如果 *Time type* 设置为“Local time”或“Server time”，则 *supported*|
|*Format*|0|tzone_format|0 - *(默认)* 短格式；<br>1 - 完整。<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior)：<br>- 如果 *Time type* 设置为“Local time”或“Server time”，则 *supported*|

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

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

以下示例仅用于介绍如何在仪表盘组件字段对象中配置*时钟*组件。
更多信息，请参考[创建仪表盘](/manual/api/reference/dashboard/create)。

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

[comment]: # ({31efb49f-4be326f4})
#### 配置 *Clock* 小组件

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

[请求](/manual/api#performing-requests)：

```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})
### 参考

-   [仪表盘组件字段](/manual/api/reference/dashboard/object#仪表盘组件字段)
-   [创建仪表盘](/manual/api/reference/dashboard/create)
-   [更新仪表盘](/manual/api/reference/dashboard/update)

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