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 nametxt value$text / DateTime namedatetime toNametxt onlydate / /ViewText标签提供了待标注的文本对象DateTime通过toNametxt关联该对象onlydate表示界面只展示日期选择控件不展示时间。仓库中还提供了一个更完整的实战示例 config.xml同时覆盖了全局标注、必填校验、自定义格式以及按区域perRegion标注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/ 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该示例演示了三种典型的DateTime形态完整日期时间、仅日期、仅年份并结合perRegiontrue与visibleWhenregion-selected实现选中文本区域后才显示对应时间控件的交互。参数详解DateTime支持以下参数依据 datetime.md 与 includes/tags/datetime.md方括号[]表示可选参数类型默认值说明namestring—元素名称必填作为标注结果中from_name的标识toNamestring—需要标注的目标元素名称必填onlystring—逗号分隔的要展示的部分date、time、month、year。注意date 不能与 month/year 同时使用date 优先级更高formatstring—日期时间的输入/输出 strftime 格式内部始终以 ISO 存储。详见下文格式规则[min]string—最小日期时间值onlydate时用 ISO 格式onlyyear时是最小年份[max]string—最大日期时间值onlydate时用 ISO 格式onlyyear时是最大年份[required]booleanfalse是否必填[requiredMessage]string—校验失败时展示的提示消息[perRegion]boolean—对区域region而非整个对象进行标注[perItem]boolean—对对象内部的条目item进行标注only 参数的取值逻辑only控制界面展示哪些时间部件其判断逻辑在 DateTime.jsx 的视图views中实现onlydate仅展示日期输入框onlytime仅展示时间输入框24 小时制、前导零格式如14:05onlymonth,year展示月份与年份两个下拉选择框此时不再展示日期与时间输入框onlyyear仅展示年份下拉选择框不设置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 状态初始化可以看到实际的格式选择逻辑onlytime时不做格式化直接使用字符串设置了format时以自定义格式为准未显示时间时回退到FORMAT_DATE否则使用FORMAT_FULL。底层通过d3.timeFormat与d3.timeParse完成格式化与解析。min / max 约束当onlydate时min/max使用 ISO 日期格式如min2021-11-10当onlyyear时min/max表示年份如min2000当同时展示日期与时间时时间部分也可从min/max中提取并应用到时间输入框的min/max属性见 DateTime.jsx 中minTime/maxTime的正则提取逻辑。在月份/年份模式下年份下拉框的范围正是由min/max推导的源码中minYear默认取2000maxYear默认取当前年份下拉选项从最大年份向下递减排列月份的选项名使用d3.timeFormat(%B)生成完整的英文月份名。required 与 requiredMessagerequiredtrue时标注者必须填写日期时间才能提交标注。校验失败时默认弹出提示DateTime 名称 is required.可通过requiredMessage自定义提示文本。测试用例 DateTime.test.jsx 验证了requiredModal()会调用InfoModal.warning且优先使用requiredMessage自定义文案。perRegion 与 perItemperRegiontrue将日期时间标注绑定到具体区域如选中的文本片段、图像上的检测框适合对同一对象内的多个区域分别记录时间常与visibleWhenregion-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 cant use toISOString() because it may shift timezone and return different dayvalidateValue()校验流程为先交由父类校验必填性再转换出 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[typedate]并透传min/max时间输入框showTime为真时类型为input[typetime]并从min/max中提取时间范围。界面细节还包括值为空且未聚焦时展示占位符校验失败isValid为 false时输入框边框显示为红色只读模式下输入框带readOnly属性并禁用变更事件。这些行为均有对应的单元测试覆盖见 DateTime.test.jsx 的HtxDateTime view测试组。测试覆盖的行为契约单元测试验证了以下关键行为可作为配置时的行为预期参考未设置only时showDate与showTime均为 true默认同时展示日期与时间onlytime时showDate为 false、showTime为 trueonlymonth,year时展示月份与年份选择框且不展示日期setDateTime(2024-07-20T14:30)能正确解析出 day20、month7、year2024、time14:30传入无法解析的值如garbage时自动清空全部字段isValid与validateValue均能正确判定日期是否落在min/max区间内越界时弹出警告validDateFormat只接受形如YYYY-MM-DD且年份在 1000~9999 之间的合法日期2024-13-0113 月与99-01-01两位数年份都会被判为非法。常用配置组合速查需求配置仅选择日期ISO 存储DateTime named toNametext onlydate /日期时间DateTime namedt toNametext /仅选择时间DateTime namet toNametext onlytime /选择月份与年份DateTime namemy toNametext onlymonth,year /仅选择年份DateTime namey toNametext onlyyear /限定日期范围DateTime named toNametext onlydate min2020-01-01 max2025-12-31 /必填并自定义提示DateTime named toNametext requiredtrue requiredMessage请选择日期 /自定义输出格式DateTime namedt toNametext format%d.%m.%Y %H:%M /按区域标注DateTime named toNametext perRegiontrue onlydate /注意事项date 与 month/year 互斥only中不要同时包含date与month/yeardate 会覆盖 month/year 的展示。min/max 格式随 only 变化onlydate时用完整 ISO 日期onlyyear时仅用四位数年份同时展示日期与时间时min/max中的时间部分会被提取用于时间输入框的上下限。存储与展示分离结果中存的是格式化值内部校验始终基于 ISO 日期时区转换可能影响跨天判定需要精确到天时建议配置format%Y-%m-%d。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考