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.mdParamTypeDefaultDescriptionnamestring—元素的名称必填toNamestring—要标注的目标元素名称必填需与对象标签的name一致onlystring—逗号分隔的显示部件列表date, time, month, yeardate与month/year不能同时使用date优先级更高formatstring—日期时间的输入/输出 strftime 格式内部始终为 ISO同时显示 date 与 time 时默认显示带T分隔符的 ISO仅显示 date 时默认显示 ISO 日期仅显示 time 时默认显示带前导零的 24 小时制时间[min]string—当onlydate时设置 ISO 格式的最小日期值当onlyyear时设置最小年份[max]string—当onlydate时设置 ISO 格式的最大日期值当onlyyear时设置最大年份[required]booleanfalse日期时间是否为必填[requiredMessage]string—校验失败时显示的消息[perRegion]boolean—用于标注区域region而非整个对象[perItem]boolean—用于标注对象内部的条目item而非整个对象说明源码TagAttrs模型中还额外定义了step、defaultvalue、hotkey三个属性槽位见 DateTime.jsx当前版本未在渲染层直接使用文档层面不承诺其行为读者如使用需自行验证。核心参数详解name 与 toName把控件连到数据上与 Label Studio 中所有控制标签一致name是控件的唯一标识toName必须与某个对象标签的name完全一致表示这个日期控件标注的是哪个对象。关于标签连接的通用规则可参考 tags/index.md 中的 Connecting elements 一节。View Text nametxt value$text / DateTime namedatetime toNametxt onlydate / /View上述配置中DateTime通过toNametxt连接Text对象即对文本内容做整体日期分类标注。only决定界面显示哪些部件only用逗号分隔可取date、time、month、year的任意组合。源码中的显示逻辑见 DateTime.jsx如下showDate未设置only或only包含date时为trueshowTime未设置only或only包含time时为trueshowMonthonly包含month且不包含date时为trueshowYearonly包含year时为trueonlyTimeonly time时为true。需要特别注意的是date与month/year不能同时使用且date优先级更高。当only同时包含date时月份下拉框会被隐藏。界面渲染也与此一一对应DateTime.jsxshowMonth渲染Month...下拉选择器月份名称由d3.timeFormat(%B)生成January~DecembershowYear渲染Year...下拉选择器年份范围由min/max推导默认从 2000 到当前年份倒序排列见 DateTime.jsxshowDate渲染原生input[typedate]showTime渲染原生input[typetime]。典型配置示例!-- 仅日期 -- DateTime namedate toNametxt onlydate / !-- 仅时间24 小时制 -- DateTime nametime toNametxt onlytime / !-- 月份 年份 -- DateTime namemonthYear toNametxt onlymonth,year / !-- 仅年份 -- DateTime nameyear toNametxt onlyyear /formatstrftime 输入输出格式format使用strftime 风格的占位符来定义日期时间的显示与存储格式例如%Y表示四位年份、%m表示两位月份、%d表示两位日期、%H:%M表示 24 小时制时分。文档特别强调内部始终使用 ISO 格式format只影响输入/输出的展示层同时显示日期和时间时默认输出 ISO 格式并以T分隔如2026-09-12T14:30仅显示日期时默认输出 ISO 日期如2026-09-12仅显示时间时默认输出带前导零的 24 小时制时间如14:30。源码中的默认格式常量印证了这一点DateTime.jsxconst 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 HeaderGlobal datetime, required, stored as dd.mm.yyyy HH:MM/Header DateTime namefull toNametext requiredtrue min2021-11-10 format%d.%m.%Y %H:%M/ Text nametext 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的语义取决于onlyonlydate或同时包含 date时按ISO 日期格式YYYY-MM-DD设置最小/最大日期onlyyear时设置最小/最大年份4 位数字如1900未设置时年份下拉框默认从2000到当前年份。源码中的取值范围推导DateTime.jsxconst minYear getYear(self.min ?? 2000); const maxYear getYear(self.max ?? current); for (let y maxYear; y minYear; y--) { years.push(y); }即年份下拉框从 maxYear 到 minYear 倒序生成min缺省为 2000max缺省为当前年份若传入 ISO 日期则取其年份作为边界。校验逻辑体现在两个层面DateTime.jsx 与 DateTime.jsx渲染层isValid视图判断date min或date max非法时给输入框加红色边框borderColor: red结果层validateValue将格式化值转 ISO 后与 min/max 比较越界时弹出提示Date ... is not valid: min date is .../max date is ...并拒绝该结果。单元测试对这两种行为都有覆盖DateTime.test.jsx、DateTime.test.jsx例如min2020-01-01 max2025-12-31时2023-06-01合法、2019-06-01与2026-01-01非法。!-- 限定在 2020-01-01 到 2025-12-31 之间的日期 -- DateTime namedt toNamet onlydate min2020-01-01 max2025-12-31 /required 与 requiredMessage必填校验requiredtrue时该控件必须有值否则标注无法提交。当校验失败时弹出提示消息默认消息为DateTime name is required.可通过requiredMessage自定义DateTime.jsxrequiredModal() { InfoModal.warning(self.requiredmessage || DateTime ${self.name} is required.); }测试确认DateTime.test.jsx!-- 默认提示DateTime dt is required. -- DateTime namedt toNamet requiredtrue / !-- 自定义提示 -- DateTime namedt toNamet requiredMessagePlease pick a date /注意validateValue对空值返回trueDateTime.test.jsx必填约束由RequiredMixin在提交阶段统一触发requiredModal。perRegion 与 perItem把日期挂到区域或条目上perRegiontrue控件从整个对象变为对象内的每个区域region即每个标注区域可以附带各自的日期值。典型场景是 NER 中给每个实体记录其对应的时间信息。perItemtrue作用于对象内部的条目item语义上用于按条目粒度的日期标注。官方示例 config.xml 展示了 perRegion 的典型组合View HeaderSelect text to see related smaller DateTime controls for every region/Header Labels namelabel toNametext Label valuebirth backgroundgreen/ Label valuedeath backgroundred/ Label valueevent backgroundorange/ /Labels Text nametext value$text/ View visibleWhenregion-selected HeaderDate in this fragment, required, stored as ISO date/Header DateTime namedate toNametext perRegiontrue onlydate requiredtrue format%Y-%m-%d/ HeaderYear this happened, but stored also as ISO date/Header DateTime nameyear toNametext perRegiontrue onlyyear format%Y-%m-%d/ /View /View该示例中的Labels负责框选文本片段如14 March 1879、18 April 1955、1921 Nobel Prize in Physics选中区域后visibleWhenregion-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 }从datetimegetterDateTime.jsx可以看出存储值的组装规则onlytime时直接存储时间字符串如09:45仅选择年份时存储年份值日期时间组合时先拼成YYYY-MM-DDT HH:MM的 ISO 中间态再按format或默认FORMAT_FULL格式化后存储。因此value.datetime中保存的是经过 format 处理的展示格式而校验阶段始终换算回 ISOgetISODate这也是为什么示例中onlyyear format%Y-%m-%d可以做到界面只选年份、结果仍存 ISO 日期。实战完整标注配置示例结合以上所有参数下面给出一个可直接使用的综合配置同时演示对象级与区域级两种用法View !-- 对象级对整个文本记录发布时间的日期时间必填自定义格式 -- HeaderArticle published at (required)/Header DateTime namepublished toNametext requiredtrue min2000-01-01 max2030-12-31 format%Y-%m-%d %H:%M / !-- 区域级为文本中每个实体记录发生年份 -- HeaderSelect entities, then set the year for each/Header Labels nameeventLabel toNametext Label valueevent background#ffa500/ Label valueperson background#90ee90/ /Labels View visibleWhenregion-selected DateTime nameeventYear toNametext perRegiontrue onlyyear min1800 max2100/ DateTime nameeventDate toNametext perRegiontrue onlydate format%d.%m.%Y/ /View Text nametext value$text/ /View使用要点归纳必填项name与toName缺一不可toName必须指向对象标签的name选择部件only按需取date/time/month/year牢记date与month/year互斥、date优先显示格式format只改展示层内部校验始终走 ISO时区敏感场景建议直接用默认 ISO 格式取值边界min/max在onlydate时填 ISO 日期、在onlyyear时填年份数字粒度控制整对象用默认模式区域粒度用perRegiontrue条目粒度用perItemtrue校验兜底requiredtrue配合requiredMessage提供可读的错误提示。延伸阅读标签体系总览与连接规则tags/index.md标注结果统一格式说明includes/result_format.mdDateTime 源码实现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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考