LabelStudio 编辑器集成完整总结

项目背景

在标注平台项目中集成 LabelStudio 编辑器，用于实现数据标注功能。

遇到的问题

问题 1：橙色到粉色的渐变遮罩

症状：整个标注界面被一个橙色渐变覆盖，无法交互

根本原因：

relations-overlay 是 LabelStudio 的关系标注覆盖层（SVG 元素）
默认有一个背景色，导致遮挡了整个界面

解决方案：在组件样式中添加透明背景：

:global(.relations-overlay) {
  background: transparent !important;
  fill: none !important;
}

:global(.lsf-container) {
  background: transparent !important;
}

修改的文件：

web/apps/lq_label/src/views/editor-test/editor-test.module.scss
web/apps/lq_label/src/views/annotation-view/annotation-view.module.scss

问题 2：编辑器样式完全不显示（核心问题）

症状：

标签按钮没有颜色
按钮没有边框和背景
面板和侧边栏样式缺失
整体看起来像是没有加载 CSS

根本原因： LabelStudio 使用 CSS 模块和 BEM 命名约定，所有 CSS 类名需要添加 lsf- 前缀：

HTML 元素：<div class="lsf-label">...</div>
CSS 文件：.label { ... } → 需要转换为 .lsf-label { ... }
我们的 webpack 配置缺少这个转换逻辑

技术细节：

根目录的 web/webpack.config.js 有特殊的 CSS 模块配置
它会给所有非 .module.scss 的 SCSS 文件添加 lsf- 前缀

配置代码：

cssLoader.options.modules = {
localIdentName: `${css_prefix}[local]`, // css_prefix = "lsf-"
getLocalIdent(_ctx, _ident, className) {
if (className.includes("ant")) return className;
},
};

解决方案：在 web/apps/lq_label/webpack.config.js 中添加相同的配置：

const css_prefix = 'lsf-';

// 1. 定义 CSS_PREFIX 环境变量
config.plugins = [
  ...config.plugins,
  new webpack.DefinePlugin({
    'process.env.CSS_PREFIX': JSON.stringify(css_prefix),
  }),
];

// 2. 配置 CSS 模块添加 lsf- 前缀
config.module.rules.forEach((rule) => {
  const testString = rule.test?.toString() || '';
  
  if (rule.test?.toString().match(/scss|sass/) && !testString.includes('.module')) {
    const r = rule.oneOf?.filter((r) => {
      if (!r.use) return false;
      const testString = r.test?.toString() || '';
      if (testString.match(/module|raw|antd/)) return false;
      return testString.match(/scss|sass/) && 
             r.use.some((u) => u.loader && u.loader.includes('css-loader'));
    });

    r?.forEach((_r) => {
      const cssLoader = _r.use.find((use) => 
        use.loader && use.loader.includes('css-loader')
      );
      
      if (!cssLoader) return;

      const isSASS = _r.use.some((use) => 
        use.loader && use.loader.match(/sass|scss/)
      );
      
      if (isSASS) _r.exclude = /node_modules/;

      if (cssLoader.options) {
        cssLoader.options.modules = {
          localIdentName: `${css_prefix}[local]`,
          getLocalIdent(_ctx, _ident, className) {
            if (className.includes('ant')) return className;
          },
        };
      }
    });
  }
});

修改的文件：

web/apps/lq_label/webpack.config.js

重要提示：

修改 webpack 配置后必须重启开发服务器
浏览器需要硬刷新（Ctrl+Shift+R）

调试过程

1. 初步探索

参考了 playground 和 labelstudio 应用的实现
发现它们只导入 UI 库样式，不静态导入 editor 样式
修改了 main.tsx 的样式导入顺序

2. 发现橙色遮罩

使用浏览器开发者工具检查元素
找到了 relations-overlay 和 lsf-container 类名
搜索源代码找到对应的组件
添加透明背景修复

3. 样式不显示的深入调查

检查 Network 标签，确认 CSS 文件已加载
检查 CSS 文件内容，发现没有 lsf- 前缀的类名
检查 HTML 元素，发现有 lsf- 前缀的类名
意识到是 CSS 模块转换的问题

4. 找到根本原因

阅读根目录的 webpack.config.js
发现 CSS 模块的 localIdentName 配置
理解了 lsf- 前缀的转换逻辑
在我们的应用中复制了这个配置

5. 验证修复

重启开发服务器
硬刷新浏览器
检查 HTML 和 CSS 的类名匹配
确认样式正确显示

创建的文件

测试页面

web/apps/lq_label/src/views/editor-test/editor-test.tsx - 测试页面组件
web/apps/lq_label/src/views/editor-test/editor-test.module.scss - 样式文件
web/apps/lq_label/src/views/editor-test/index.ts - 导出文件

文档

web/apps/lq_label/EDITOR_TEST.md - 测试页面说明
web/apps/lq_label/RELATIONS_OVERLAY_FIX.md - 橙色遮罩修复文档
web/apps/lq_label/CSS_PREFIX_FIX.md - CSS 前缀问题修复文档
web/apps/lq_label/LABELSTUDIO_INTEGRATION_SUMMARY.md - 本文档

规范

.kiro/steering/labelstudio-集成规范.md - 完整的集成规范
.kiro/steering/README.md - 规范索引

关键经验

1. 参考成功案例

不要从零开始，先看看其他应用是怎么做的
playground 应用是最好的参考
根目录的 webpack.config.js 包含关键配置

2. 使用浏览器开发者工具

Elements 标签：检查 HTML 元素和类名
Network 标签：检查 CSS 文件是否加载
Console 标签：查看错误和日志
Styles 面板：检查样式是否被应用

3. 理解 CSS 模块

CSS 模块会转换类名
localIdentName 配置决定转换规则
LabelStudio 依赖特定的前缀

4. 搜索源代码

使用类名搜索找到对应的组件
理解组件的用途和实现
找到样式文件和配置

5. 创建测试页面

隔离问题，简化调试
添加调试面板显示状态
使用简单的配置和数据

最终效果

✅ 橙色遮罩消失 ✅ 所有样式正确显示 ✅ 标签按钮有颜色和边框 ✅ 悬停和选中效果正常 ✅ 侧边栏和面板样式正确 ✅ 编辑器完全可用

访问测试页面

启动开发服务器：
```
cd web
yarn nx serve lq_label
```
访问测试页面：
首页：http://localhost:4200/
点击 "🧪 编辑器测试" 按钮
或直接访问：http://localhost:4200/editor-test
访问标注页面：
创建项目和任务
访问：http://localhost:4200/tasks/:id/annotate

后续工作

完善标注保存功能
添加更多的编辑器配置选项
实现标注历史记录
添加标注质量检查
优化编辑器性能

致谢

感谢 LabelStudio 团队提供的优秀编辑器！感谢 playground 和 labelstudio 应用提供的参考实现！

文档创建时间：2026-01-13 最后更新时间：2026-01-13 维护者：项目开发团队

LABELSTUDIO_INTEGRATION_SUMMARY.md 6.7 KB Istoric Crud