Label Studio 前端LSF集成参考初始化选项、事件系统与标注 API 回调完全指南【免费下载链接】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 前端Label Studio Frontend简称 LSF为核心系统讲解如何将其嵌入自定义标注后端、如何通过初始化选项控制标注界面、如何利用内置事件系统监听标注生命周期以及如何使用已被事件系统取代的历史回调 API。读完本文你将掌握new LabelStudio()的完整选项清单、任务/用户数据结构、全部可用事件及参数签名并能在自己的数据科学或机器学习工作流中直接落地集成。注意自 Label Studio 1.11.0 起LSF 已不再作为独立分发包对外提供如需在 Label Studio 内使用前端库可参阅仓库内的 web/libs/editor/README.md。本文所述 API 均基于当前仓库 web/libs/editor 中前端源码的实现。LSF 是什么驱动整个标注流程的前端模块LSF 是 Label Studio 生态中的核心前端模块它既提供标注界面UI也内置了统一标注格式的数据层。根据 web/libs/editor/README.md 的说明Label Studio 中的每一次人工标注都是由 LSF 完成的因此理解 LSF 的集成方式就等于理解了 Label Studio 标注能力的底层机制。在仓库中LSF 的源码位于 web/libs/editor/src核心入口类LabelStudio定义于 LabelStudio.tsx。从源码可以看出该类构造函数接收rootDOM 元素或元素 id和userOptions并将默认选项与用户选项合并根据instanceOptions.reactVersion自动选择 React 17createAppV17或 React 18createAppV18渲染路径通过configureStore(this.options, this.events)创建 MobX 状态树store这也是 LSF.init.md 中提到的初始化主流程LabelStudio - constructor - createApp - configureStore - initializeStore提供on()/off()方法用于事件订阅与退订其底层基于EventInvoker类实现见 web/libs/editor/src/utils/events.ts。本地开发与测试如果你想在本仓库中运行、调试 LSF需在web目录或其子目录下执行以下脚本来自 web/libs/editor/README.md命令用途bun run lsf:watch持续构建 LSF开发时可实时观察改动在 Label Studio 环境中的效果bun run lsf:serve以独立模式运行 LSF访问 http://localhost:3000 使用独立版应用bun run lsf:integration运行 Cypress 集成测试需先启动bun run lsf:servebun run lsf:integration:ui以 UI 模式运行集成测试便于可视化调试bun run lsf:unit运行 LSF 单元测试初始化 LSF在页面中初始化 LSF 只需一行代码var labelStudio new LabelStudio(editor, options);其中editor是挂载元素或元素 idoptions是初始化选项对象。以下列出 LSF 1.0.0 版本识别并支持的全部初始化选项。初始化选项详解config默认值null类型string标注界面的 XML 配置它决定了标注界面上显示哪些控件、标签类型以及标签与任务data字段之间的绑定关系。配置依赖任务对象中的data字段。该配置本质上是 Label Studio 的自定义标签体系如Text、Choices、RectangleLabels、Image等仓库中的标签文档见 docs/source/tags。interfaces默认值见 web/libs/editor/src/defaultOptions.js即下列列表全部启用类型array需要展示的 UI 元素集合用于按需裁剪标注界面。可用值如下接口名作用panel为当前任务启用导航面板含撤销undo、重做redo和重置reset按钮update提交后显示更新当前任务按钮submit显示提交或更新当前标注的按钮skip显示跳过当前任务的按钮controls启用包含submit、update、skip的控制面板infobar信息按钮topbar显示 Label Studio UI 顶层条目的标注界面instruction打开说明的按钮side-column在 UI 左侧或右侧显示一列annotations:history标注历史按钮annotations:tabs标注标签页按钮annotations:menu标注菜单按钮annotations:current当前标注按钮annotations:add-new新增标注按钮annotations:delete删除当前标注按钮annotations:view-all查看全部标注按钮predictions:tabs显示预测标签页predictions:menu显示预测菜单auto-annotation显示自动标注edit-history显示编辑历史源码佐证默认选项在 defaultOptions.js 中定义除了文档列出的全部接口外还额外包含predictions:delete。这些选项最终作为AppStore的初始值传入参见 LabelStudio.tsx 中LSFOptions类型定义。messages默认值null类型object不同操作对应的界面消息文案{ DONE: Done!, NO_COMP_LEFT: No more annotations, NO_NEXT_TASK: No more data available for labeling, NO_ACCESS: You dont have access to this task }DONE任务提交到服务器后显示NO_COMP_LEFT没有更多标注时显示NO_NEXT_TASK没有下一个可加载任务时显示NO_ACCESS无法访问给定任务时显示description默认值No description类型string当前任务的描述文本对应界面中的说明instructions入口。从 LSF.init.md 中可以看到官方在待改进清单里提出过将description选项重命名为instructions的计划说明它本质上是任务标注说明。task默认值null类型object任务数据结构如下{ id: 1, data: { text: Labeling text... }, annotations: [], predictions: [] }字段说明id整数类型默认null任务唯一标识。data任务原始数据即标注界面读取并展示的数据源与config中的 XML 标签绑定。annotations数组类型任务的标注列表。具体结构参见导出文档中的原始 JSON 格式Label Studio JSON format of annotated tasks一节result数组内是区域/结果对象。predictions数组类型预测列表结构与标注annotations相似。用于预标注pre-labeling场景相关内容可参考 docs/source/guide/predictions.md。源码佐证AppStore初始化时会遍历任务的每个预测调用addPrediction、selectPrediction、deserializeResults遍历每个标注调用addAnnotation、selectAnnotation等最终setInitialValues、setHistory并触发storageInitialized参见 LSF.init.md 的initializeStore小节以及 AppStore.js 中对应实现。user默认值null类型object当前用户数据{ pk: 1, firstName: Stanley, lastName: Kubrick }字段说明pk数字类型用户主键。firstName字符串类型名。lastName字符串类型姓。此外从 LabelStudio.tsx 的类型定义可知options还支持keymap自定义快捷键映射通过Hotkey.setKeymap生效、users用户数组以及settings.forceBottomPanel等扩展选项。LSF 事件系统LSF 内置了事件系统允许你随时监听事件并触发自定义动作。实例初始化完成后即可订阅或退订事件。事件订阅与退订订阅事件const callback () { console.log(Event triggered); }; labelStudio.on(event, callback);退订事件const callback () { console.log(Event triggered); }; labelStudio.off(event, callback);注意要成功退订必须向off方法传入与订阅时相同的回调函数引用。若调用off(eventName)而不传回调则会移除该事件的所有监听器见 LabelStudio.tsx。事件系统底层实现从源码看事件系统的核心是EventInvoker类web/libs/editor/src/utils/events.ts内部使用Mapstring, SetCallback存储事件名到回调集合的映射同一事件可挂多个回调重复添加同一回调会被去重invoke(eventName, ...args)会并发执行该事件的全部回调Promise.allinvokeFirst只执行第一个注册的回调removeAll清空某事件的全部监听器。LabelStudio实例的on/off方法正是委托给EventInvoker实现的。另外源码还通过supportLegacyEvents()将onSubmitAnnotation这类历史回调自动转换并注册为同名事件camelCase(key.replace(/^on/, ))这就是新旧两套 API 能共存的底层机制见 LabelStudio.tsx。可用事件全览顶层事件顶层事件不关联 LSF 的任何内部实体。labelStudioLoadLabel Studio 实例加载完成时触发。警告该事件在插件中不生效。事件处理器参数参数类型描述labelStudioObjectLabel Studio 实例storageInitialized内部存储初始化完成时触发。警告该事件在插件中不生效。事件处理器参数参数类型描述labelStudioObjectLabel Studio 实例源码佐证AppStore#initializeStore是 LSF 的核心初始化方法它在完成预测/标注的反序列化、历史初始化后设置initialized true并触发storageInitialized参见 LSF.init.md。任务事件skipTask用户点击Skip跳过按钮时触发。事件处理器参数参数类型描述labelStudioObjectLabel Studio 实例payloadObject跳过动作时发送的附加数据unskipTask用户点击Cancel Skip取消跳过按钮时触发。参数类型描述labelStudioObjectLabel Studio 实例nextTask用户点击Next右箭头按钮时触发。参数类型描述labelStudioObjectLabel Studio 实例taskIdNumber?历史中下一个任务的 IDannotationIdNumber?要选中的任务内标注 IDprevTask用户点击Previous左箭头按钮时触发。参数类型描述labelStudioObjectLabel Studio 实例taskIdNumber?历史中上一个任务的 IDannotationIdNumber?要选中的任务内标注 IDsubmitDraft草稿被发送到服务器时触发。参数类型描述labelStudioObjectLabel Studio 实例annotationObject当前标注paramsObject?随草稿发送的额外参数标注事件beforeSaveAnnotation标注即将因submit或update动作而被保存时触发。若该事件的回调返回false将阻止标注保存。参数类型描述labelStudioObjectLabel Studio 实例annotationObject当前标注payloadObject附加信息payload.eventstring指示即将执行的事件名如submitAnnotation、updateAnnotation等submitAnnotation标注被提交时触发。参数类型描述labelStudioObjectLabel Studio 实例annotationObject当前标注updateAnnotation标注被更新时触发。参数类型描述labelStudioObjectLabel Studio 实例annotationObject当前标注selectAnnotation标注被选中时触发。参数类型描述annotationObject当前标注previousAnnotationObject之前的标注payloadObject?附加信息payload.fromViewAllboolean若 ViewAll 刚刚被关闭则为truedeleteAnnotation标注被删除时触发。参数类型描述labelStudioObjectLabel Studio 实例annotationObject当前标注groundTruth标注被设为 Ground Truth点击星标按钮时触发。参数类型描述storeObjectLabel Studio 实例labelStudioObjectLabel Studio 实例paramsObject附加参数params.isDirtyBoolean标注若被修改过则为trueparams.entityObject当前标注selectHistory在标注历史中选择某一步时触发。参数类型描述labelStudioObjectLabel Studio 实例annotationObject当前标注historyItemObject当前历史项区域Region事件区域是分割类任务如图像分割、音频分割中的特殊实体。entityCreate区域被创建时触发。参数类型描述regionObject新创建的区域entityDelete区域被删除时触发。参数类型描述regionObject被删除的区域区域事件的回调参数只有region与任务/标注事件不同不包含labelStudio实例参数。回调 API已弃用回调Callbacks可用于基于用户与界面的交互执行动作例如 label-studio 服务器使用回调与 API 通信。将回调与其他选项一起在初始化实例时传入。它们已由上述事件系统取代但在历史版本中承担了与事件相同的职责。源码佐证历史回调清单定义于 web/libs/editor/src/core/External.js除文档列出的回调外还包括onDeletePrediction、onUnskipTask、onTaskLoad、onSelectAnnotation、onAcceptAnnotation、onRejectAnnotation、onStorageInitialized、onSubmitDraft、onNextTask、onPrevTask等。如上文所述这些回调在实例化时会被自动转换为同名事件注册。onSubmitAnnotation类型function点击submit按钮时调用。ls是 label studio 实例annotation是当前标注的值。onSubmitAnnotation: function(ls, annotation) { console.log(annotation) }onUpdateAnnotation类型function点击update按钮时调用。ls是 label studio 实例annotation是当前标注的值。onUpdateAnnotation: function(ls, annotation) { console.log(result) }onDeleteAnnotation类型function点击delete按钮时调用。ls是 label studio 实例annotation是当前标注的值。onDeleteAnnotation: function(ls, annotation) { console.log(result) }onEntityCreate类型function新区域被标注时调用例如创建了一个新的 bbox。region是被创建的对象。onEntityCreate: function(region) { console.log(region) }onEntityDelete类型function已有区域被删除时调用。region是被删除的对象本身。onEntityDelete: function(region) { console.log(region) }onSkipTask类型function点击skip按钮时调用。ls是 label studio 实例。onSkipTask: function(ls) { console.log(result) }onLabelStudioLoad类型functionLabel Studio 完全加载并准备好标注时调用。ls是 label studio 实例。onLabelStudioLoad: function(ls) { console.log(result) }LSF 1.0.0 的破坏性变更LSF 1.0.0 与更早版本不兼容。如果使用 LSF 搭配自定义后端必须按以下映射关系修改使用的 API 回调0.9.1 及更早版本的回调1.0.0 中的重命名回调onSubmitCompletiononSubmitAnnotationonUpdateCompletiononUpdateAnnotationonDeleteCompletiononDeleteAnnotation同时如果你依赖 Label Studio 已完成任务的特定格式其标注格式原始 JSON 格式也随 1.0.0 更新。更新后的格式以annotations/predictions数组及result结果对象为核心结构相关说明见导出文档中的Label Studio JSON format of annotated tasks一节docs/source/guide/export.md。实战集成示例结合以上内容一个完整的集成片段如下const options { config: View Text nametext value$text/ Choices namelabel toNametext choicesingle Choice valuePositive/ Choice valueNegative/ /Choices /View , interfaces: [panel, update, submit, skip, controls, topbar], task: { id: 1, data: { text: Labeling text... }, annotations: [], predictions: [], }, user: { pk: 1, firstName: Stanley, lastName: Kubrick }, }; const labelStudio new LabelStudio(editor, options); // 事件订阅保存前校验 labelStudio.on(beforeSaveAnnotation, (ls, annotation, payload) { if (!annotation.regions?.length) { alert(请至少标注一个区域后再提交); return false; // 阻止保存 } }); // 事件订阅提交后与后端同步 labelStudio.on(submitAnnotation, (ls, annotation) { syncWithBackend(annotation); });该示例演示了通过config定义基于任务data字段的 XML 标注配置通过interfaces裁剪 UI通过task传入任务与空标注/预测列表通过user记录操作者最后利用beforeSaveAnnotation做保存前校验返回false拦截、利用submitAnnotation做提交后同步。若需与历史版本兼容也可改用onSubmitAnnotation: function(ls, annotation) {...}形式的回调二者在实例化时会映射到同一套事件机制。【免费下载链接】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），仅供参考