# Date Time Picker Component
The date time picker component is an interactive component used to provide options for both time and date selection. This document describes the JSON structure and related properties of the date time picker component.
## Notes
- The date time picker component supports the Feishu client version 3.11.0 and above. In Feishu clients lower than this version, the content of the form container will be displayed as "The current version does not support viewing this message".
- When using the date time picker, you need to remind users to select the time zone information corresponding to the current scenario. For example, in the scenario of booking overseas hotels, the time zone of the hotel location is generally used; in the scheduling scenario, the time zone of the user's current location is generally used. The open platform will return the user's current time zone as a reference, but it does not mean that the user has selected that time zone.
- In the card JSON code, if the date time picker component is directly located at the root node of the card, rather than nested within other components, you need to configure its JSON data in the `actions` field of the [interaction module](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/component-list/common-components-and-elements) (`"tag": "action"`).
## Nesting Rules
The date time picker component supports nesting in columns, form containers, collapsible panels, and loop containers.
## Component Properties
### JSON Structure
The JSON structure of the date time picker component is as follows:
```json
{
"tag": "picker_datetime", // The tag of the date time picker component.
"name": "picker_datetime1", // The unique identifier of the date time picker component. When the component is embedded within a form container, this field takes effect and is required. It is used to identify which component the submitted data belongs to.
"required": false, // Whether the date time is required. Default value is false. This property is available when the date time picker is embedded within a form container. In other cases, it will either cause an error or not take effect.
"disabled": false, // Whether this date time picker component is disabled. Default value is false.
"width": "default", // The width of the date time picker.
"initial_datetime": "2024-01-01 11:30", // Initial value of the date time. Default is empty.
"placeholder": {
// Placeholder text inside the date time picker component.
"tag": "plain_text",
"content": "Please select"
},
"value": {
// Return data
"key_1": "value_1"
},
"confirm": {
// Configuration of the confirmation popup
"title": {
"tag": "plain_text",
"content": "title"
},
"text": {
"tag": "plain_text",
"content": "content"
}
}
}
```
### Field Descriptions
The field descriptions of the date time picker component are shown in the following table.
Field | Required | Type | Default Value | Description
---|---|---|---|---
tag | Yes | String | / | The tag of the component. For the date time picker component, it has a fixed value of `picker_datetime`.
name | No | String | Empty | The unique identifier of the date time picker component. This field takes effect when the date time picker is embedded within a form container and is used to identify which component the submitted data belongs to.
**Note**: When the date time picker component is nested within a form container, this field is required and must be unique within the global card.
required | No | Boolean | false | Whether the date time is required. This property is available when the component is embedded within a form container. Otherwise, it will either cause an error or not take effect. Possible values:
- true: The date time is required. When the user clicks "Submit" in the form container without filling in the date time, a frontend prompt "Some required items are not filled in" will be displayed, and no callback request will be sent to the developer's server.
- false: The date time is optional. When the user clicks "Submit" in the form container without filling in the date time, the data in the form container is still submitted.
disabled | No | Boolean | false | Whether to disable the date time picker. This property is only supported in Feishu client version 7.4 and above. Possible values:
- true: Disable the date time picker component.
- false: Keep the date time picker component enabled.
initial_datetime | No | String | Empty | The initial selection value of the date time picker component. The format is `yyyy-MM-dd HH:mm`. This configuration will override the placeholder text configured in `placeholder`.
placeholder | No | Object | / | Placeholder text inside the date time picker component.
**Note**:
- When the `initial_datetime` field is not configured to set the initial selection value, this field is required.
- When the `initial_datetime` field is configured to set the initial selection value, this field will no longer take effect.
└ tag | Yes | String | plain_text | Placeholder tag. It has a fixed value of plain_text.
└ content | No | String | / | Content of the placeholder text, supporting up to 100 characters.
width | No | String | default | Width of the date time picker component. Supports the following enumeration values:
- default: Default width
- fill: Maximum supported width of the card
- [100,∞)px: Custom width. When exceeding the width of the card, it will be displayed according to the maximum supported width.
value | Yes | JSON | / | Set the return data for interaction. When the user clicks an option in the interactive component, the value will be returned to the server receiving the callback data. Later, you can process business logic based on the received value from the server.
This field only supports key-value JSON structure, and the key is of type String.
confirm | No | Struct | This property does not take effect by default. | Configuration for the confirmation popup. It prompts the user with a confirmation popup when submitting. Only when the user clicks confirm, the input content will be submitted. This field defaults to providing confirm and cancel buttons, and you only need to configure the title and content of the popup.
**Note**: The confirm field will only trigger the confirmation popup when the button containing the submit attribute is clicked.
confirm.title | Yes | Struct | / | The title of the confirmation popup.
confirm.title.tag | Yes | String | plain_text | The tag for the title text of the confirmation popup. It has a fixed value of `plain_text`.
confirm.title.content | Yes | String | / | The content of the title of the confirmation popup.
confirm.text | Yes | Struct | / | The text content of the confirmation popup.
confirm.text.tag | Yes | String | plain_text | The tag for the text content of the confirmation popup. It has a fixed value of `plain_text`.
confirm.text.content | Yes | String | / | The specific content of the text in the confirmation popup.
## Callback Structure
After successfully configuring interactions for the component, when users interact with the component, the request address configured in the developer console will receive callback data.
- If you have added the new version of the card callback interaction (`card.action.trigger`), you can refer to [Card Callback Interaction](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication) for the callback structure.
- If you have added the old version of the card callback interaction (`card.action.trigger_v1`), you can refer to [Message Card Callback Interaction (Old)](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure) for the callback structure.
## Sample Code
The following JSON sample code can achieve the card effect as shown in the image below:
```json
{
"i18n_elements": {
"zh_cn": [
{
"tag": "action",
"actions": [
{
"tag": "picker_datetime",
"placeholder": {
"tag": "plain_text",
"content": "请选择"
},
"width": "default"
}
]
},
{
"tag": "action",
"actions": [
{
"tag": "picker_datetime",
"placeholder": {
"tag": "plain_text",
"content": "请选择"
},
"width": "default",
"initial_datetime": "2024-01-01 08:00"
}
]
}
]
},
"i18n_header": {}
}
```