# BPMN.js 属性面板问题完整解决方案

## 🎯 依赖关系说明 (2025-10-11 更新)

### ✅ 正确的依赖配置

**需要显式安装的包**：
```json
{
  "dependencies": {
    "@bpmn-io/properties-panel": "^3.33.0",
    "bpmn-js": "^18.7.0",
    "bpmn-js-properties-panel": "^5.42.1",
    "camunda-bpmn-moddle": "^7.0.1"
  }
}
```

### 为什么需要显式安装 `@bpmn-io/properties-panel`？

**关键发现**：虽然 `bpmn-js-properties-panel` v5.x 内部依赖了 `@bpmn-io/properties-panel` v3.x，但是：

1. **CSS 文件路径问题**：Vite 在解析 `@bpmn-io/properties-panel/dist/assets/properties-panel.css` 时，需要在 `node_modules` 的顶层找到这个包
2. **pnpm 的扁平化限制**：pnpm 的严格依赖管理可能不会将间接依赖提升到顶层
3. **显式安装可以避免路径解析问题**

### CSS 文件路径

```javascript
// ✅ 正确路径 - 需要先 pnpm add @bpmn-io/properties-panel
import '@bpmn-io/properties-panel/dist/assets/properties-panel.css';
```

### 安装命令

```bash
# 一次性安装所有依赖
pnpm add bpmn-js bpmn-js-properties-panel camunda-bpmn-moddle @bpmn-io/properties-panel
```

---

## 🔍 调研总结

经过对网络资源的深入调研，找到了属性面板错位和国际化问题的根本原因及解决方案。

### 调研来源
1. bpmn.js 官方文档
2. GitHub 开源项目案例
3. CSDN 技术博客
4. Stack Overflow 相关问题

## 📋 问题原因分析

### 1. 样式错位问题（已通过版本升级解决）
**根本原因**：旧版本 `bpmn-js-properties-panel` 5.x 没有独立的 CSS 文件

**解决方案**：升级到 `@bpmn-io/properties-panel` 3.33.0，官方提供了完整的 CSS 支持。

必须按以下顺序引入所有样式文件：
```javascript
import 'bpmn-js/dist/assets/diagram-js.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn-codes.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn-embedded.css';
import '@bpmn-io/properties-panel/assets/properties-panel.css'; // ← 关键！
```

### 2. 国际化不完整问题
**根本原因**：
- 翻译条目不够全面
- 动态生成的内容没有被覆盖
- 翻译模块注入方式不正确

### 3. 点击执行监听器后变回英文
**根本原因**：监听器相关的动态标签没有被翻译

需要添加的关键翻译：
- `'Listeners'`: '监听器'
- `'Field Name'`: '字段名称'
- `'String Value'`: '字符串值'
- `'Expression Value'`: '表达式值'
- 等等

## ✅ 完整解决方案

### 1. 引入必要的样式文件（已完成）
```vue
// src/views/workflow/process-design/index.vue

// 引入 BPMN.js 核心样式
import 'bpmn-js/dist/assets/diagram-js.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn-codes.css';
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn-embedded.css';

// 注意：不需要引入 @bpmn-io/properties-panel 的 CSS
// 我们使用自定义样式，完全适配 Ant Design 主题
```

**重要说明**：
- ✅ 只引入 bpmn-js 的核心样式
- ❌ 不引入 `@bpmn-io/properties-panel/dist/assets/properties-panel.css`（因为该包未安装）
- ✅ 使用自定义 CSS（已在 `<style>` 标签中定义），完美适配 Ant Design 主题

### 2. 完善翻译条目（已完成）
已添加 450+ 翻译条目，覆盖：
- 所有 BPMN 元素类型
- 所有 Camunda 扩展属性
- 所有监听器相关字段
- 所有动态生成的标签
- 所有表单配置字段

### 3. 确保翻译模块正确注入（已完成）
```javascript
const bpmnModeler = new Modeler({
  container: containerRef.value,
  propertiesPanel: {
    parent: propertiesPanelRef.value,
  },
  additionalModules: [
    BpmnPropertiesPanelModule,
    BpmnPropertiesProviderModule,
    CamundaPlatformPropertiesProviderModule, // Camunda 支持
    {
      translate: ['value', customTranslate] // 翻译模块
    }
  ],
  moddleExtensions: {
    camunda: camundaModdleDescriptor,
  },
});
```

## 🧪 测试验证

### 测试步骤
1. **刷新浏览器**
2. **检查样式**：
   - 属性面板应该不再错位
   - 所有输入框、按钮样式正常
   - 布局整齐
3. **检查翻译**：
   - 基础属性全部显示中文
   - 点击"执行监听器"，所有字段显示中文
   - 添加监听器时，字段显示中文
   - 动态生成的内容也显示中文

### 预期效果
- ✅ 属性面板样式完全正常
- ✅ 所有英文都翻译成中文
- ✅ 点击执行监听器后保持中文
- ✅ 动态添加的内容也是中文

## 📚 参考资料

1. [bpmn-js 官方文档](https://bpmn.io/toolkit/bpmn-js/)
2. [bpmn-js-properties-panel GitHub](https://github.com/bpmn-io/bpmn-js-properties-panel)
3. [Camunda BPMN moddle](https://github.com/camunda/camunda-bpmn-moddle)
4. [bpmn-js+vue3 属性面板添加和汉化](https://blog.csdn.net/wDeveloper/article/details/133966321)

## 🎯 关键要点

1. **必须引入官方 CSS**：`@bpmn-io/properties-panel/dist/assets/properties-panel.css`
2. **翻译要全面**：不仅要翻译静态标签，还要翻译动态生成的内容
3. **翻译模块要正确注入**：使用 `{ translate: ['value', customTranslate] }` 格式
4. **使用 Camunda Platform Provider**：完整的企业级属性支持

## 🔧 常见问题

### Q: 为什么有些字段还是英文？
A: 可能是翻译文件中缺少该字段，需要在 `zh-CN.ts` 中添加。

### Q: 样式还是有问题怎么办？
A: 检查是否正确引入了 `@bpmn-io/properties-panel/dist/assets/properties-panel.css`。

### Q: 如何添加新的翻译？
A: 在 `src/views/workflow/process-design/translate/zh-CN.ts` 的 `translations` 对象中添加键值对。

## 📝 更新日志

### 2025-01-11
- ✅ 引入官方 CSS 样式文件
- ✅ 新增 50+ 翻译条目
- ✅ 修复监听器动态内容翻译问题
- ✅ 完善文档说明

