Label Studio List 标签详解轻量展示列表数据并与 Ranker 组合实现排序标注【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioList是 Label Studio 中用于展示同类条目如文章、搜索结果、图片列表的对象型标签相比用多个Text标签手动拼接它更轻量、性能更好。本文将围绕 List 标签官方文档 的参数定义、数据格式与配置示例展开并结合 List.jsx 与 Ranker.jsx 源码讲解它与Ranker标签组合实现排序、分组的完整工作方式帮助你直接落地可运行的标注配置。一、List 标签是什么定位与适用场景List标签用于显示一组同类型的相似条目典型场景包括文章列表标题 摘要正文搜索引擎结果页结果标题 摘要 链接图片或富媒体条目列表通过html字段嵌入任意 HTML 内容。在 Label Studio 的标签体系中List属于对象object型标签其核心定位在 tags/list.md 中写得很明确当任务数据本身已经是一个数组时用List展示比把Text等标签逐个分组拼接要轻量得多同时它还可以挂接分类classification控件为整份列表补充额外标注信息。从源码注册方式看List通过Registry.addTag(list, ListModel, HtxList)与Registry.addObjectType(ListModel)注册为对象标签见 List.jsx因此它可以作为Ranker、Labels等控制标签的toName目标。二、参数说明以下是 includes/tags/list.md 中定义的三个参数参数类型说明namestring元素名称用于在结果中标识该对象也是其他控制标签通过toName连接它的依据valuestring数据字段名对应任务数据中一个包含对象数组的 JSON 字段用于展示待排序/待标注的条目titlestring可选列表的标题会在界面上作为列标题显示对照 List.jsx 的 MST 模型定义可以看到实现细节const Model types .model({ type: list, value: types.maybeNull(types.string), _value: types.frozen([]), title: types.optional(types.string, ), })value保存配置中写的字段名如$items中的items_value是运行时解析后的条目数组内部状态frozen类型保证不可变title默认值为空字符串。value的解析发生在updateValueaction 中通过parseValue(self.value, store.task.dataObj)从任务数据里取出对应字段若解析结果不是数组则直接忽略解析成功后会对每个条目执行id: String(item.id)把 id 统一强制转换为字符串以保证后续按 id 索引、排序时类型一致见 List.jsx。三、任务数据格式value 字段的要求List要求value指向的字段是一个对象数组每个对象需包含以下字段字段说明id条目标识源码中会强制转为字符串作为排序结果中的索引键title条目标题显示在列表项标题位置body条目的正文/摘要文本html可选任意 HTML 片段用于富媒体展示如内嵌图片3.1 文本型列表数据官方文档给出的第一个数据示例对应 tags/list.md 中的示例数据{ items: [ { id: blog, title: 10 tips to write a better function, body: There is nothing worse than being left in the lurch when it comes to writing a function! }, { id: mdn, title: Arrow function expressions, body: An arrow function expression is a compact alternative to a traditional function }, { id: wiki, title: Arrow (computer science), body: In computer science, arrows or bolts are a type class... } ] }3.2 HTML 型列表数据当列表项需要展示图片等富媒体内容时使用html字段{ items: [ { id: blog, title: Image 1, html: img srchttp://example.com/1.jpg }, { id: mdn, title: Image 2, html: img srchttp://example.com/2.jpg } ] }从实现角度看List对条目的处理是透传式的updateValue只负责取数组并规范id类型条目的title、body、html等字段全部原样保留在_value中随后由items视图构建{ id: item }的索引映射见 List.jsx渲染阶段再按需读取。四、完整配置示例List Style 样式定制List标签可以与Style标签配合通过两个预定义类名自定义外观.htx-ranker-column列/容器背景和.htx-ranker-item条目背景。官方文档中的可运行示例View Style .htx-ranker-column { background: cornflowerblue; } .htx-ranker-item { background: lightgoldenrodyellow; } /Style List nameresults value$items titleSearch Results / /View这里$items是任务数据中items字段的引用写法value参数在配置中写作$items运行时由parseValue解析titleSearch Results会作为列标题展示。界面交互层面Ranker.tsx 中渲染的看板由一列或多列组成每列通过Column组件展示条目并支持折叠collapsible默认开启。五、源码实现List 在编辑器中的工作原理List的核心渲染逻辑位于 List.jsxconst HtxList inject(store)( observer(({ item }) { const data item.dataSource; if (!data) return null; // Ranker tag will display all items in interactive mode if (item.ranker) return null; return ( React.StrictMode Ranker inputData{data} readonly / /React.StrictMode ); }), );这里有三个关键行为值得注意数据源组装dataSource视图把内部状态组装为{ items, columns, itemIds }结构——items是按 id 索引的条目映射columns是[{ id: name, title }]默认单列列 id 即标签名itemIds是{ name: [所有条目 id] }见 List.jsx。只读渲染单独的List标签通过Ranker inputData{data} readonly /以只读看板形式展示注意这里 import 的是组件层的Ranker与同名的控制标签不同因此没有Ranker控制标签时列表仅用于展示。交互让位当通过toName连接了Ranker控制标签时item.ranker非空HtxList直接返回null把交互展示完全交给Ranker标签——这就是ListRanker组合后列表变为可交互的底层原因。ranker视图通过self.annotation.toNames.get(self.name)反查所有连接到本列表的ranker类型标签见 List.jsx。六、与 Ranker 标签组合排序、挑选与分组Ranker是List最核心的搭档两者组合可实现三种模式详见 Ranker.jsx 的注释与defaultBucket视图模式配置方式行为排序rank模式仅ListRanker无Bucket子标签标注者通过拖拽调整条目顺序挑选pick模式Ranker内嵌套多个Bucket不带default将条目拖入各桶分组未入桶的条目留在原始列表内部以_列记录分组group模式某个Bucket设置defaulttrue所有条目默认落在该桶中导出结果始终覆盖全部条目6.1 简单排序模式官方文档示例View Style .htx-ranker-column { background: cornflowerblue; } .htx-ranker-item { background: lightgoldenrodyellow; } /Style List nameresults value$items titleSearch Results / Ranker namerank toNameresults / /View此模式下Ranker的rankOnly为真列集合即[{ id: name, title: list.title }]单列看板支持拖拽重排。对应生成的结果value是键为标签名的字典值为新顺序下的 id 数组{ from_name: rank, to_name: results, type: ranker, value: { ranker: { rank: [mdn, wiki, blog] } } }6.2 桶Bucket分组模式用Bucket子标签定义分组列View List nameresults value$items titleSearch Results / Ranker namerank toNameresults Bucket namebest titleBest results / Bucket nameads titlePaid results / /Ranker /View此时结果以桶名为键{ from_name: rank, to_name: results, type: ranker, value: { ranker: { best: [mdn], ads: [blog] } } }Bucket子标签的参数见 Ranker.jsx参数类型说明namestring列名同时作为导出结果中的键titlestring可选列标题展示在看板列头defaultboolean可选默认false设为true后所有条目默认放入该桶6.3 default 参数与结果一致性关于default参数源码注释给出两条关键语义不带default时未拖入任何桶的条目会留在原始列表内部以_命名的列记录ORIGINAL_ITEMS_KEY _见 Ranker.jsx这部分是内部值后续版本可能调整导出结果中可能不包含未被分组的条目。带defaulttrue时所有条目默认位于该桶导出结果永远包含列表全部条目并按桶分组适合需要全量分组的强制标注场景。defaultBucket视图的逻辑是有桶时取default true的桶名否则在 rank 模式下回退为标签自身name见 Ranker.jsx。另外beforeSendaction 会在提交时兜底创建结果若标注者未做任何拖拽也会为每个列生成空数组并把全部条目 id 放入默认列保证结果结构完整见 Ranker.jsx。七、拖拽交互的底层实现排序与分组的交互由组件层 Ranker.tsx 完成它基于react-beautiful-dnd的DragDropContext构建多列看板同列重排handleDragEnd在startCol endCol时对itemIds数组执行splice移动并调用handleChange(newItemIds)写回结果跨列移动先从源列splice移除再插入目标列的对应索引同样触发handleChange折叠能力折叠状态以CollapsedMap独立维护不直接改动条目数据collapsible属性由Ranker标签的collapsible参数默认true透传控制数据同步useEffect监听inputData变化并重置看板状态保证任务切换时展示与结果一致。对应的单元测试位于 Ranker.test.ts覆盖了 rank 模式、bucket 分组、default 桶以及结果结构等行为可作为理解语义的补充参考。八、样式定制小结List及其搭配的Ranker/Bucket暴露的样式类名汇总如下类名作用.htx-ranker-column看板列容器背景.htx-ranker-item列表条目背景类名通过 Style 标签 声明后即可生效例如本文第四节中的示例。条目级样式可用于高亮特定结果列级样式则用于区分不同分组。九、注意事项与实践建议id 必须唯一且最终为字符串源码会强制String(item.id)重复或缺失 id 会导致索引映射错乱建议在任务数据中保证 id 唯一。value 字段必须是数组updateValue对非数组数据直接忽略列表将为空。List 与 Ranker 是一对一的关系Ranker通过toName找到目标List标签list.type list才生效见 Ranker.jsxList也可以同时挂接分类控件为整份列表补充标注。导出结果的键是标签 name / 桶 name排序模式的键是Ranker的name分组模式的键是各Bucket的name解析导出数据时需按此定位。关于_内部列不带default的桶模式会把未分组条目记在内部_列当前版本导出结果中可能出现属于已知的内部行为不应依赖其稳定性。至此从参数定义、数据格式、配置示例到源码级实现List标签的完整用法已经覆盖。将其与Ranker、Bucket组合即可在 Label Studio 中快速搭建搜索结果排序相关性挑选内容分组等典型标注任务且整个交互无需编写任何前端代码。【免费下载链接】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），仅供参考 Label Studio List 标签详解：轻量展示列表数据并与 Ranker 组合实现排序标注
Label Studio List 标签详解轻量展示列表数据并与 Ranker 组合实现排序标注【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioList是 Label Studio 中用于展示同类条目如文章、搜索结果、图片列表的对象型标签相比用多个Text标签手动拼接它更轻量、性能更好。本文将围绕 List 标签官方文档 的参数定义、数据格式与配置示例展开并结合 List.jsx 与 Ranker.jsx 源码讲解它与Ranker标签组合实现排序、分组的完整工作方式帮助你直接落地可运行的标注配置。一、List 标签是什么定位与适用场景List标签用于显示一组同类型的相似条目典型场景包括文章列表标题 摘要正文搜索引擎结果页结果标题 摘要 链接图片或富媒体条目列表通过html字段嵌入任意 HTML 内容。在 Label Studio 的标签体系中List属于对象object型标签其核心定位在 tags/list.md 中写得很明确当任务数据本身已经是一个数组时用List展示比把Text等标签逐个分组拼接要轻量得多同时它还可以挂接分类classification控件为整份列表补充额外标注信息。从源码注册方式看List通过Registry.addTag(list, ListModel, HtxList)与Registry.addObjectType(ListModel)注册为对象标签见 List.jsx因此它可以作为Ranker、Labels等控制标签的toName目标。二、参数说明以下是 includes/tags/list.md 中定义的三个参数参数类型说明namestring元素名称用于在结果中标识该对象也是其他控制标签通过toName连接它的依据valuestring数据字段名对应任务数据中一个包含对象数组的 JSON 字段用于展示待排序/待标注的条目titlestring可选列表的标题会在界面上作为列标题显示对照 List.jsx 的 MST 模型定义可以看到实现细节const Model types .model({ type: list, value: types.maybeNull(types.string), _value: types.frozen([]), title: types.optional(types.string, ), })value保存配置中写的字段名如$items中的items_value是运行时解析后的条目数组内部状态frozen类型保证不可变title默认值为空字符串。value的解析发生在updateValueaction 中通过parseValue(self.value, store.task.dataObj)从任务数据里取出对应字段若解析结果不是数组则直接忽略解析成功后会对每个条目执行id: String(item.id)把 id 统一强制转换为字符串以保证后续按 id 索引、排序时类型一致见 List.jsx。三、任务数据格式value 字段的要求List要求value指向的字段是一个对象数组每个对象需包含以下字段字段说明id条目标识源码中会强制转为字符串作为排序结果中的索引键title条目标题显示在列表项标题位置body条目的正文/摘要文本html可选任意 HTML 片段用于富媒体展示如内嵌图片3.1 文本型列表数据官方文档给出的第一个数据示例对应 tags/list.md 中的示例数据{ items: [ { id: blog, title: 10 tips to write a better function, body: There is nothing worse than being left in the lurch when it comes to writing a function! }, { id: mdn, title: Arrow function expressions, body: An arrow function expression is a compact alternative to a traditional function }, { id: wiki, title: Arrow (computer science), body: In computer science, arrows or bolts are a type class... } ] }3.2 HTML 型列表数据当列表项需要展示图片等富媒体内容时使用html字段{ items: [ { id: blog, title: Image 1, html: img srchttp://example.com/1.jpg }, { id: mdn, title: Image 2, html: img srchttp://example.com/2.jpg } ] }从实现角度看List对条目的处理是透传式的updateValue只负责取数组并规范id类型条目的title、body、html等字段全部原样保留在_value中随后由items视图构建{ id: item }的索引映射见 List.jsx渲染阶段再按需读取。四、完整配置示例List Style 样式定制List标签可以与Style标签配合通过两个预定义类名自定义外观.htx-ranker-column列/容器背景和.htx-ranker-item条目背景。官方文档中的可运行示例View Style .htx-ranker-column { background: cornflowerblue; } .htx-ranker-item { background: lightgoldenrodyellow; } /Style List nameresults value$items titleSearch Results / /View这里$items是任务数据中items字段的引用写法value参数在配置中写作$items运行时由parseValue解析titleSearch Results会作为列标题展示。界面交互层面Ranker.tsx 中渲染的看板由一列或多列组成每列通过Column组件展示条目并支持折叠collapsible默认开启。五、源码实现List 在编辑器中的工作原理List的核心渲染逻辑位于 List.jsxconst HtxList inject(store)( observer(({ item }) { const data item.dataSource; if (!data) return null; // Ranker tag will display all items in interactive mode if (item.ranker) return null; return ( React.StrictMode Ranker inputData{data} readonly / /React.StrictMode ); }), );这里有三个关键行为值得注意数据源组装dataSource视图把内部状态组装为{ items, columns, itemIds }结构——items是按 id 索引的条目映射columns是[{ id: name, title }]默认单列列 id 即标签名itemIds是{ name: [所有条目 id] }见 List.jsx。只读渲染单独的List标签通过Ranker inputData{data} readonly /以只读看板形式展示注意这里 import 的是组件层的Ranker与同名的控制标签不同因此没有Ranker控制标签时列表仅用于展示。交互让位当通过toName连接了Ranker控制标签时item.ranker非空HtxList直接返回null把交互展示完全交给Ranker标签——这就是ListRanker组合后列表变为可交互的底层原因。ranker视图通过self.annotation.toNames.get(self.name)反查所有连接到本列表的ranker类型标签见 List.jsx。六、与 Ranker 标签组合排序、挑选与分组Ranker是List最核心的搭档两者组合可实现三种模式详见 Ranker.jsx 的注释与defaultBucket视图模式配置方式行为排序rank模式仅ListRanker无Bucket子标签标注者通过拖拽调整条目顺序挑选pick模式Ranker内嵌套多个Bucket不带default将条目拖入各桶分组未入桶的条目留在原始列表内部以_列记录分组group模式某个Bucket设置defaulttrue所有条目默认落在该桶中导出结果始终覆盖全部条目6.1 简单排序模式官方文档示例View Style .htx-ranker-column { background: cornflowerblue; } .htx-ranker-item { background: lightgoldenrodyellow; } /Style List nameresults value$items titleSearch Results / Ranker namerank toNameresults / /View此模式下Ranker的rankOnly为真列集合即[{ id: name, title: list.title }]单列看板支持拖拽重排。对应生成的结果value是键为标签名的字典值为新顺序下的 id 数组{ from_name: rank, to_name: results, type: ranker, value: { ranker: { rank: [mdn, wiki, blog] } } }6.2 桶Bucket分组模式用Bucket子标签定义分组列View List nameresults value$items titleSearch Results / Ranker namerank toNameresults Bucket namebest titleBest results / Bucket nameads titlePaid results / /Ranker /View此时结果以桶名为键{ from_name: rank, to_name: results, type: ranker, value: { ranker: { best: [mdn], ads: [blog] } } }Bucket子标签的参数见 Ranker.jsx参数类型说明namestring列名同时作为导出结果中的键titlestring可选列标题展示在看板列头defaultboolean可选默认false设为true后所有条目默认放入该桶6.3 default 参数与结果一致性关于default参数源码注释给出两条关键语义不带default时未拖入任何桶的条目会留在原始列表内部以_命名的列记录ORIGINAL_ITEMS_KEY _见 Ranker.jsx这部分是内部值后续版本可能调整导出结果中可能不包含未被分组的条目。带defaulttrue时所有条目默认位于该桶导出结果永远包含列表全部条目并按桶分组适合需要全量分组的强制标注场景。defaultBucket视图的逻辑是有桶时取default true的桶名否则在 rank 模式下回退为标签自身name见 Ranker.jsx。另外beforeSendaction 会在提交时兜底创建结果若标注者未做任何拖拽也会为每个列生成空数组并把全部条目 id 放入默认列保证结果结构完整见 Ranker.jsx。七、拖拽交互的底层实现排序与分组的交互由组件层 Ranker.tsx 完成它基于react-beautiful-dnd的DragDropContext构建多列看板同列重排handleDragEnd在startCol endCol时对itemIds数组执行splice移动并调用handleChange(newItemIds)写回结果跨列移动先从源列splice移除再插入目标列的对应索引同样触发handleChange折叠能力折叠状态以CollapsedMap独立维护不直接改动条目数据collapsible属性由Ranker标签的collapsible参数默认true透传控制数据同步useEffect监听inputData变化并重置看板状态保证任务切换时展示与结果一致。对应的单元测试位于 Ranker.test.ts覆盖了 rank 模式、bucket 分组、default 桶以及结果结构等行为可作为理解语义的补充参考。八、样式定制小结List及其搭配的Ranker/Bucket暴露的样式类名汇总如下类名作用.htx-ranker-column看板列容器背景.htx-ranker-item列表条目背景类名通过 Style 标签 声明后即可生效例如本文第四节中的示例。条目级样式可用于高亮特定结果列级样式则用于区分不同分组。九、注意事项与实践建议id 必须唯一且最终为字符串源码会强制String(item.id)重复或缺失 id 会导致索引映射错乱建议在任务数据中保证 id 唯一。value 字段必须是数组updateValue对非数组数据直接忽略列表将为空。List 与 Ranker 是一对一的关系Ranker通过toName找到目标List标签list.type list才生效见 Ranker.jsxList也可以同时挂接分类控件为整份列表补充标注。导出结果的键是标签 name / 桶 name排序模式的键是Ranker的name分组模式的键是各Bucket的name解析导出数据时需按此定位。关于_内部列不带default的桶模式会把未分组条目记在内部_列当前版本导出结果中可能出现属于已知的内部行为不应依赖其稳定性。至此从参数定义、数据格式、配置示例到源码级实现List标签的完整用法已经覆盖。将其与Ranker、Bucket组合即可在 Label Studio 中快速搭建搜索结果排序相关性挑选内容分组等典型标注任务且整个交互无需编写任何前端代码。【免费下载链接】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），仅供参考