企业官网建设流程全解析

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

导读

本文档以 Label Studio 的DateTime 控制标签（<DateTime>）为核心，系统讲解如何在标注界面中为任务数据添加日期、时间、时间戳、月份或年份标注。文章完整覆盖该标签的全部参数（name、toName、only、format、min、max、required、requiredMessage、perRegion、perItem），并结合前端编辑器源码（DateTime.jsx）、官方示例（config.xml）与单元测试（DateTime.test.jsx）深入讲解其底层实现与结果格式。读完本文，你将能够独立编写面向日期、时间戳、月份、年份等场景的标注配置，并理解 DateTime 在标注结果中的存储规则。

DateTime 标签是什么

<DateTime>是 Label Studio 中的控制标签（Control Tag），负责在标注界面中提供日期和时间选择能力，用来给一条标注添加日期、时间戳、月份或年份等结构化信息。它属于控制标签中的分类（Classification）类控件，因此可以：

• 作为一个独立分类作用于整个对象（例如对整个文本、图片或音频打上一个"发布时间"日期）；
• 结合perRegion或perItem作用于对象内部的某个区域或某个条目（例如对文本中标注的每一个实体分别记录其发生年份）。

官方文档明确声明该标签支持以下数据类型：audio、image、HTML、paragraph、text、time series、video（见 tags/datetime.md）。也就是说，凡是这些对象标签渲染出来的数据，都可以用 DateTime 附加时间属性。

从源码看，DateTime在 web/libs/editor/src/tags/control/index.js 中被注册为datetime标签，其核心模型定义在 DateTime.jsx，由多个 mixin 组合而成：ControlBase、ClassificationBase、RequiredMixin、ReadOnlyControlMixin、PerRegionMixin，并在特定 feature flag 下启用PerItemMixin与AnnotationMixin。这正是它同时支持"必填校验、只读、按区域、按条目"等多种行为的底层原因。

参数总览

以下是 DateTime 标签的全部参数（来源：datetime.md）：

说明：源码TagAttrs模型中还额外定义了step、defaultvalue、hotkey三个属性槽位（见 DateTime.jsx），当前版本未在渲染层直接使用，文档层面不承诺其行为，读者如使用需自行验证。

核心参数详解

name 与 toName：把控件连到数据上

与 Label Studio 中所有控制标签一致，name是控件的唯一标识，toName必须与某个对象标签的name完全一致，表示"这个日期控件标注的是哪个对象"。关于标签连接的通用规则，可参考 tags/index.md 中的 "Connecting elements" 一节。

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

上述配置中，DateTime通过toName="txt"连接Text对象，即对文本内容做整体日期分类标注。

only：决定界面显示哪些部件

only用逗号分隔，可取date、time、month、year的任意组合。源码中的显示逻辑（见 DateTime.jsx）如下：

• showDate：未设置only，或only包含date时为true；
• showTime：未设置only，或only包含time时为true；
• showMonth：only包含month且不包含date时为true；
• showYear：only包含year时为true；
• onlyTime：only === "time"时为true。

需要特别注意的是date与month/year不能同时使用，且date优先级更高。当only同时包含date时，月份下拉框会被隐藏。

界面渲染也与此一一对应（DateTime.jsx）：

• showMonth渲染"Month..."下拉选择器，月份名称由d3.timeFormat("%B")生成（January~December）；
• showYear渲染"Year..."下拉选择器，年份范围由min/max推导（默认从 2000 到当前年份，倒序排列，见 DateTime.jsx）；
• showDate渲染原生input[type="date"]；
• showTime渲染原生input[type="time"]。

典型配置示例：

<!-- 仅日期 --> <DateTime name="date" toName="txt" only="date" /> <!-- 仅时间（24 小时制） --> <DateTime name="time" toName="txt" only="time" /> <!-- 月份 + 年份 --> <DateTime name="monthYear" toName="txt" only="month,year" /> <!-- 仅年份 --> <DateTime name="year" toName="txt" only="year" />

format：strftime 输入输出格式

format使用strftime 风格的占位符来定义日期时间的显示与存储格式（例如%Y表示四位年份、%m表示两位月份、%d表示两位日期、%H:%M表示 24 小时制时分）。文档特别强调：

• 内部始终使用 ISO 格式，format只影响输入/输出的展示层；
• 同时显示日期和时间时，默认输出 ISO 格式并以T分隔（如2026-09-12T14:30）；
• 仅显示日期时，默认输出 ISO 日期（如2026-09-12）；
• 仅显示时间时，默认输出带前导零的 24 小时制时间（如14:30）。

源码中的默认格式常量印证了这一点（DateTime.jsx）：

const FORMAT_FULL = "%Y-%m-%dT%H:%M"; // 日期+时间 const FORMAT_DATE = "%Y-%m-%d"; // 仅日期 const FORMAT_TIME = "%H:%M"; // 仅时间

格式化与解析通过 d3 的d3.timeFormat/d3.timeParse实现（DateTime.jsx）。一个自定义格式的完整示例：

<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"/> <Text name="text" value="$text"/> </View>

该示例来自官方演示配置 web/libs/editor/src/examples/datetime/config.xml：界面按%d.%m.%Y %H:%M展示（如24.06.2022 17:01），但内部校验仍转换为 ISO 日期。getISODate方法（DateTime.jsx）负责把已格式化的结果值还原成YYYY-MM-DD用于 min/max 校验，并注释说明"不能直接使用toISOString()，因为它可能因时区偏移而返回不同的日期"——这是实现中一个值得注意的细节。

min 与 max：取值边界

min/max的语义取决于only：

• only=date（或同时包含 date）时，按ISO 日期格式（YYYY-MM-DD）设置最小/最大日期；
• only=year时，设置最小/最大年份（4 位数字，如1900）；
• 未设置时年份下拉框默认从2000到当前年份。

源码中的取值范围推导（DateTime.jsx）：

const minYear = getYear(self.min ?? "2000"); const maxYear = getYear(self.max ?? "current"); for (let y = maxYear; y >= minYear; y--) { years.push(y); }

即：年份下拉框从 maxYear 到 minYear 倒序生成；min缺省为 2000，max缺省为当前年份；若传入 ISO 日期，则取其年份作为边界。

校验逻辑体现在两个层面（DateTime.jsx 与 DateTime.jsx）：

1. 渲染层：isValid视图判断date < min或date > max，非法时给输入框加红色边框（borderColor: "red"）；
2. 结果层：validateValue将格式化值转 ISO 后与 min/max 比较，越界时弹出提示Date "..." is not valid: min date is .../max date is ...，并拒绝该结果。

单元测试对这两种行为都有覆盖（DateTime.test.jsx、DateTime.test.jsx），例如min="2020-01-01" max="2025-12-31"时2023-06-01合法、2019-06-01与2026-01-01非法。

<!-- 限定在 2020-01-01 到 2025-12-31 之间的日期 --> <DateTime name="dt" toName="t" only="date" min="2020-01-01" max="2025-12-31" />

required 与 requiredMessage：必填校验

required="true"时该控件必须有值，否则标注无法提交。当校验失败时，弹出提示消息；默认消息为DateTime "<name>" is required.，可通过requiredMessage自定义（DateTime.jsx）：

requiredModal() { InfoModal.warning(self.requiredmessage || `DateTime "${self.name}" is required.`); }

测试确认（DateTime.test.jsx）：

<!-- 默认提示：DateTime "dt" is required. --> <DateTime name="dt" toName="t" required="true" /> <!-- 自定义提示 --> <DateTime name="dt" toName="t" requiredMessage="Please pick a date" />

注意validateValue对空值返回true（DateTime.test.jsx），必填约束由RequiredMixin在提交阶段统一触发requiredModal。

perRegion 与 perItem：把日期挂到区域或条目上

• perRegion="true"：控件从"整个对象"变为"对象内的每个区域（region）"，即每个标注区域可以附带各自的日期值。典型场景是 NER 中给每个实体记录其对应的时间信息。
• perItem="true"：作用于对象内部的条目（item），语义上用于按条目粒度的日期标注。

官方示例 config.xml 展示了 perRegion 的典型组合：

<View> <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>

该示例中的Labels负责框选文本片段（如"14 March 1879"、"18 April 1955"、"1921 Nobel Prize in Physics"），选中区域后（visibleWhen="region-selected"）显示对应的 DateTime 控件，为每个实体分别记录日期与年份。对应标注结果可在示例任务数据 examples/datetime/index.js 中查看：每个区域的结果包含start/end位置、原文文本与datetime值（如"datetime": "1879-03-14"）。

标注结果格式

DateTime 作为控制标签，其标注结果遵循 Label Studio 统一的 result 格式（详见 includes/result_format.md）：结果存于annotation.result数组中，每条包含id、from_name、to_name、type与value字段，type固定为datetime。

整体对象级 DateTime 的结果示例（来自 examples/datetime/index.js）：

{ "value": { "datetime": "24.06.2022 17:01" }, "id": "xiMzVHO9fw", "from_name": "full", "to_name": "text", "type": "datetime" }

perRegion 模式下的区域级结果示例（同一文件 examples/datetime/index.js）——它与同区域的 labels 结果共享id，通过id关联：

{ "value": { "start": 83, "end": 96, "text": "14 March 1879", "datetime": "1879-03-14" }, "id": "NLn3WDm6w2", "from_name": "date", "to_name": "text", "type": "datetime" }

从datetimegetter（DateTime.jsx）可以看出存储值的组装规则：

• only=time时直接存储时间字符串（如"09:45"）；
• 仅选择年份时存储年份值；
• 日期+时间组合时先拼成YYYY-MM-DDT HH:MM的 ISO 中间态，再按format（或默认FORMAT_FULL）格式化后存储。

因此，value.datetime中保存的是经过 format 处理的展示格式，而校验阶段始终换算回 ISO（getISODate），这也是为什么示例中only="year" format="%Y-%m-%d"可以做到"界面只选年份、结果仍存 ISO 日期"。

实战：完整标注配置示例

结合以上所有参数，下面给出一个可直接使用的综合配置，同时演示对象级与区域级两种用法：

<View> <!-- 对象级：对整个文本记录发布时间的日期+时间，必填，自定义格式 --> <Header>Article published at (required)</Header> <DateTime name="published" toName="text" required="true" min="2000-01-01" max="2030-12-31" format="%Y-%m-%d %H:%M" /> <!-- 区域级：为文本中每个实体记录发生年份 --> <Header>Select entities, then set the year for each</Header> <Labels name="eventLabel" toName="text"> <Label value="event" background="#ffa500"/> <Label value="person" background="#90ee90"/> </Labels> <View visibleWhen="region-selected"> <DateTime name="eventYear" toName="text" perRegion="true" only="year" min="1800" max="2100"/> <DateTime name="eventDate" toName="text" perRegion="true" only="date" format="%d.%m.%Y"/> </View> <Text name="text" value="$text"/> </View>

使用要点归纳：

1. 必填项：name与toName缺一不可，toName必须指向对象标签的name；
2. 选择部件：only按需取date/time/month/year，牢记date与month/year互斥、date优先；
3. 显示格式：format只改展示层，内部校验始终走 ISO，时区敏感场景建议直接用默认 ISO 格式；
4. 取值边界：min/max在only=date时填 ISO 日期、在only=year时填年份数字；
5. 粒度控制：整对象用默认模式，区域粒度用perRegion="true"，条目粒度用perItem="true"；
6. 校验兜底：required="true"配合requiredMessage提供可读的错误提示。

延伸阅读

• 标签体系总览与连接规则：tags/index.md
• 标注结果统一格式说明：includes/result_format.md
• DateTime 源码实现：web/libs/editor/src/tags/control/DateTime.jsx
• 官方演示配置与示例数据：web/libs/editor/src/examples/datetime/config.xml、web/libs/editor/src/examples/datetime/index.js
• 单元测试（参数行为、min/max 校验、渲染逻辑）：web/libs/editor/src/tags/control/tests/DateTime.test.jsx
• 其他时间/文本相关标签可参考 docs/source/tags 目录下的datetime.md、date、time等文档

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