Label Studio DateTime 标签详解：为标注界面添加日期、时间与年份选择

Label Studio DateTime 标签详解：为标注界面添加日期、时间与年份选择

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

导读

DateTime是 Label Studio 标注配置（XML Label Config）中的核心控制标签之一，用于在标注界面中为任务添加日期、时间戳、月份或年份的选取控件。它可配合文本、图片、音视频、HTML、时间序列等几乎所有数据类型使用，并将选择结果以标准化格式写入标注结果（annotation result），供模型训练或数据校验使用。阅读本文后，你将掌握DateTime的完整参数体系、only/format/min/max的组合用法、区域级与条目级标注模式，以及其底层实现与验证机制。

DateTime 标签简介

在 Label Studio 中，DateTime标签向标注界面添加日期和时间选择能力。它的典型应用包括：

• 为新闻、合同、病历等文本片段标注事件发生日期；
• 为图像或视频帧标注拍摄时间；
• 为时间序列数据标注异常发生的时刻；
• 为结构化数据补充年份、月份等粒度的时间信息。

官方文档说明其适用于以下数据类型：audio（音频）、image（图像）、HTML、paragraph（段落）、text（文本）、time series（时间序列）、video（视频）。

基础用法与完整示例

最简单的基础配置如下（与 datetime.md 文档中的示例一致）：

<View> <Text name="txt" value="$text" /> <DateTime name="datetime" toName="txt" only="date" /> </View>

<Text>标签提供了待标注的文本对象，<DateTime>通过toName="txt"关联该对象，only="date"表示界面只展示日期选择控件（不展示时间）。

仓库中还提供了一个更完整的实战示例 config.xml，同时覆盖了全局标注、必填校验、自定义格式以及按区域（perRegion）标注：

<View> <Header>Global date+time, required, stored as dd.mm.yyyy HH:MM</Header> <DateTime name="full" toName="text" required="true" min="2021-11-10" format="%d.%m.%Y %H:%M"/> <Header>Select text to see related smaller DateTime controls for every region</Header> <Labels name="label" toName="text"> <Label value="birth" background="green"/> <Label value="death" background="red"/> <Label value="event" background="orange"/> </Labels> <Text name="text" value="$text"/> <View visibleWhen="region-selected"> <Header>Date in this fragment, required, stored as ISO date</Header> <DateTime name="date" toName="text" perRegion="true" only="date" required="true" format="%Y-%m-%d"/> <Header>Year this happened, but stored also as ISO date</Header> <DateTime name="year" toName="text" perRegion="true" only="year" format="%Y-%m-%d"/> </View> </View>

该示例演示了三种典型的DateTime形态：完整日期+时间、仅日期、仅年份，并结合perRegion="true"与visibleWhen="region-selected"实现"选中文本区域后才显示对应时间控件"的交互。

参数详解

DateTime支持以下参数（依据 datetime.md 与 includes/tags/datetime.md，方括号[]表示可选）：

only 参数的取值逻辑

only控制界面展示哪些时间部件，其判断逻辑在 DateTime.jsx 的视图（views）中实现：

• only="date"：仅展示日期输入框；
• only="time"：仅展示时间输入框（24 小时制、前导零格式，如14:05）；
• only="month,year"：展示月份与年份两个下拉选择框（此时不再展示日期与时间输入框）；
• only="year"：仅展示年份下拉选择框；
• 不设置only：默认同时展示日期与时间。

源码中的判定视图如下：showDate在未设置only或包含"date"时为真；showMonth仅在包含"month"且不包含"date"时为真；showYear在包含"year"时为真。这印证了文档中"date 与 month/year 不可混用、date 优先"的规则——一旦包含date，月份选择即被隐藏。

format 参数的默认行为与规则

format使用 strftime 格式描述符（如%Y-%m-%d、%H:%M、%d.%m.%Y %H:%M）。文档与源码共同规定的默认行为如下：

• 内部始终以 ISO 存储，format仅决定界面上的输入/输出展示格式；
• 同时展示日期和时间时，默认显示 ISO 格式并使用"T"作为分隔符，即%Y-%m-%dT%H:%M（源码常量FORMAT_FULL）；
• 仅展示日期时，默认显示 ISO 日期%Y-%m-%d（源码常量FORMAT_DATE）；
• 仅展示时间时，默认显示 24 小时制、带前导零的时间%H:%M（源码常量FORMAT_TIME）。

从 DateTime.jsx 的 volatile 状态初始化可以看到实际的格式选择逻辑：only=time时不做格式化（直接使用字符串）；设置了format时以自定义格式为准；未显示时间时回退到FORMAT_DATE；否则使用FORMAT_FULL。底层通过d3.timeFormat与d3.timeParse完成格式化与解析。

min / max 约束

• 当only=date时，min/max使用 ISO 日期格式（如min="2021-11-10"）；
• 当only=year时，min/max表示年份（如min="2000"）；
• 当同时展示日期与时间时，时间部分也可从min/max中提取并应用到时间输入框的min/max属性（见 DateTime.jsx 中minTime/maxTime的正则提取逻辑）。

在月份/年份模式下，年份下拉框的范围正是由min/max推导的：源码中minYear默认取2000，maxYear默认取当前年份，下拉选项从最大年份向下递减排列；月份的选项名使用d3.timeFormat("%B")生成完整的英文月份名。

required 与 requiredMessage

required="true"时，标注者必须填写日期时间才能提交标注。校验失败时默认弹出提示：DateTime "名称" is required.，可通过requiredMessage自定义提示文本。测试用例 DateTime.test.jsx 验证了requiredModal()会调用InfoModal.warning，且优先使用requiredMessage自定义文案。

perRegion 与 perItem

• perRegion="true"：将日期时间标注绑定到具体区域（如选中的文本片段、图像上的检测框），适合对同一对象内的多个区域分别记录时间，常与visibleWhen="region-selected"配合使用；
• perItem：对对象内部的条目进行标注，其混入（mixin）由特性开关FF_LSDV_4583控制是否启用（见 DateTime.jsx 的模型组合部分）。

从源码看，DateTimeModel由ControlBase、ClassificationBase、RequiredMixin、ReadOnlyControlMixin、PerRegionMixin、AnnotationMixin等组合而成，因此它同时具备分类控件的通用能力（必填校验、只读、区域标注）与日期时间特有的解析/格式化逻辑。

标注结果的数据格式

DateTime属于分类型控制标签，其标注结果以type: "datetime"写入 annotation result。集成测试数据 from-prediction.ts 给出了标准的结果结构示例：

{ "from_name": "datetime", "to_name": "text", "type": "datetime", "value": { "datetime": "2000-01-01T00:00:00.000Z" } }

要点：

• value.datetime中存储的是格式化后的展示值（受format影响），而校验时使用 ISO 形式；
• 源码中的getISODate(value)方法负责把结果中的格式化值重新转换为 ISO 日期用于min/max校验，且特意避免使用toISOString()，防止时区偏移导致日期跨天（代码注释明确说明"we can't use toISOString() because it may shift timezone and return different day"）；
• validateValue()校验流程为：先交由父类校验必填性，再转换出 ISO 日期，分别与min/max比较，越界时弹出包含具体日期与边界值的警告框（如Date "2019-06-15" is not valid: min date is 2020-01-01.）。

底层实现与验证机制

组件结构

DateTime的实现位于 web/libs/editor/src/tags/control/DateTime.jsx，通过Registry.addTag("datetime", DateTimeModel, HtxDateTime)注册为可识别的标签类型。界面组件HtxDateTime按需渲染：

• 月份下拉框（showMonth为真时），占位文本 "Month..."；
• 年份下拉框（showYear为真时），占位文本 "Year..."；
• 日期输入框（showDate为真时），类型为原生input[type="date"]，并透传min/max；
• 时间输入框（showTime为真时），类型为input[type="time"]，并从min/max中提取时间范围。

界面细节还包括：值为空且未聚焦时展示占位符；校验失败（isValid为 false）时输入框边框显示为红色；只读模式下输入框带readOnly属性并禁用变更事件。这些行为均有对应的单元测试覆盖（见 DateTime.test.jsx 的HtxDateTime view测试组）。

测试覆盖的行为契约

单元测试验证了以下关键行为，可作为配置时的行为预期参考：

• 未设置only时，showDate与showTime均为 true（默认同时展示日期与时间）；
• only="time"时showDate为 false、showTime为 true；
• only="month,year"时展示月份与年份选择框且不展示日期；
• setDateTime("2024-07-20T14:30")能正确解析出 day=20、month=7、year=2024、time="14:30"；
• 传入无法解析的值（如"garbage"）时自动清空全部字段；
• isValid与validateValue均能正确判定日期是否落在min/max区间内，越界时弹出警告；
• validDateFormat只接受形如YYYY-MM-DD且年份在 1000~9999 之间的合法日期，"2024-13-01"（13 月）与"99-01-01"（两位数年份）都会被判为非法。

常用配置组合速查

注意事项

1. date 与 month/year 互斥：only中不要同时包含date与month/year，date 会覆盖 month/year 的展示。
2. min/max 格式随 only 变化：only=date时用完整 ISO 日期；only=year时仅用四位数年份；同时展示日期与时间时，min/max中的时间部分会被提取用于时间输入框的上下限。
3. 存储与展示分离：结果中存的是格式化值，内部校验始终基于 ISO 日期，时区转换可能影响跨天判定，需要精确到天时建议配置format="%Y-%m-%d"。
4. readOnly 环境：处于只读/评审模式时，日期、时间、月份、年份控件均不可编辑，界面会保持只读状态。

延伸阅读

• 标签完整文档：datetime.md、参数说明
• 源码实现：DateTime.jsx
• 单元测试：DateTime.test.jsx
• 实战示例配置：config.xml
• 结果格式参考：from-prediction.ts
• 标注配置入门：get_started.md

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio