docs: 文档中文化重命名并添加规范文档
- 将所有英文文档重命名为中文格式 - 新增 AI代码规范模板.md（通用开发规范） - 新增 国际化实现指南.md（i18n 规范） - 重复文档移至 .recycle 目录
This commit is contained in:
yuding
2024
docs/AI代码规范模板.md
Normal file
2024
docs/AI代码规范模板.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -1,95 +0,0 @@
|
||||
# 弹窗组件 (Dialog)
|
||||
|
||||
BimEngine SDK 提供了可拖拽、可缩放的通用弹窗组件 `DialogManager` (底层基于 `BimDialog`)，支持自定义内容和高度定制的样式。
|
||||
|
||||
## 1. 组件作用
|
||||
|
||||
* 提供浮动的交互窗口。
|
||||
* 支持任意 HTML 内容挂载。
|
||||
* 内置拖拽移动和拖拽缩放功能。
|
||||
* 支持丰富的样式定制接口。
|
||||
|
||||
## 2. 初始化与使用
|
||||
|
||||
通过 `BimEngine` 实例访问：
|
||||
|
||||
```typescript
|
||||
const engine = new BimEngine('container-id');
|
||||
// engine.dialog 即为 DialogManager 实例
|
||||
```
|
||||
|
||||
## 3. 配置项 (DialogOptions)
|
||||
|
||||
`engine.dialog.create(options)` 方法接受以下配置：
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `title` | `string` | `'Dialog'` | 弹窗标题 |
|
||||
| `content` | `string \| HTMLElement` | - | 弹窗内容 |
|
||||
| `width` | `number \| string` | `300` | 宽度 |
|
||||
| `height` | `number \| string` | `'auto'` | 高度 |
|
||||
| `position` | `DialogPosition` | `'center'` | 初始位置 (支持 'center', 'top-left' 等或坐标对象) |
|
||||
| `draggable` | `boolean` | `true` | 是否可拖拽 |
|
||||
| `resizable` | `boolean` | `false` | 是否可调整大小 |
|
||||
| `minWidth` | `number` | `200` | 最小宽度 |
|
||||
| `minHeight` | `number` | `100` | 最小高度 |
|
||||
| `onClose` | `Function` | - | 关闭时的回调 |
|
||||
| `backgroundColor` | `string` | `rgba(17, 17, 17, 0.95)` | 窗体背景色 |
|
||||
| `headerBackgroundColor` | `string` | `#2a2a2a` | 标题栏背景色 |
|
||||
| `titleColor` | `string` | `#fff` | 标题文字颜色 |
|
||||
| `textColor` | `string` | `#ccc` | 内容默认文字颜色 |
|
||||
| `borderColor` | `string` | `#444` | 边框颜色 |
|
||||
|
||||
## 4. 使用案例
|
||||
|
||||
### 案例 1: 创建基本弹窗
|
||||
|
||||
```typescript
|
||||
engine.dialog.create({
|
||||
title: '欢迎',
|
||||
content: 'Hello World!',
|
||||
width: 400
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 2: 创建包含复杂 DOM 的弹窗
|
||||
|
||||
```typescript
|
||||
const div = document.createElement('div');
|
||||
div.innerHTML = '<button>Click Me</button>';
|
||||
div.querySelector('button').onclick = () => alert('Clicked');
|
||||
|
||||
engine.dialog.create({
|
||||
title: '交互组件',
|
||||
content: div,
|
||||
resizable: true
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 3: 定制样式 (红色主题)
|
||||
|
||||
```typescript
|
||||
engine.dialog.create({
|
||||
title: '警告',
|
||||
content: '这是一个红色主题的警告弹窗。',
|
||||
backgroundColor: 'rgba(100, 0, 0, 0.9)', // 深红背景
|
||||
headerBackgroundColor: '#ff0000', // 鲜红标题栏
|
||||
titleColor: '#ffffff',
|
||||
borderColor: '#ff4444'
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 4: 监听关闭事件
|
||||
|
||||
```typescript
|
||||
const dlg = engine.dialog.create({
|
||||
title: '任务',
|
||||
content: '处理中...',
|
||||
onClose: () => {
|
||||
console.log('弹窗已关闭');
|
||||
}
|
||||
});
|
||||
|
||||
// 手动关闭
|
||||
// dlg.close();
|
||||
```
|
||||
@@ -1,160 +0,0 @@
|
||||
# OptBtnGroups 组件使用文档
|
||||
|
||||
## 📋 组件简介
|
||||
|
||||
`OptBtnGroups` 是一个纯 TypeScript 实现的操作按钮组组件，使用原生 DOM API 开发，无任何框架依赖。
|
||||
|
||||
## 🎯 核心特性
|
||||
|
||||
- ✅ 纯 TypeScript + 原生 DOM API
|
||||
- ✅ 多组分隔，独立背景块
|
||||
- ✅ 二级下拉菜单
|
||||
- ✅ 多选激活状态
|
||||
- ✅ 可控的标签显示
|
||||
- ✅ 按钮显隐控制
|
||||
- ✅ SVG 图标支持
|
||||
- ✅ 响应式横向滚动
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 安装/引入
|
||||
|
||||
```html
|
||||
<!-- UMD 方式 -->
|
||||
<script src="./dist/bim-engine-sdk.umd.js"></script>
|
||||
|
||||
<script>
|
||||
const { OptBtnGroups } = window.BimEngineSDK;
|
||||
</script>
|
||||
```
|
||||
|
||||
```typescript
|
||||
// ES Module 方式
|
||||
import { OptBtnGroups } from 'bim-engine-sdk';
|
||||
```
|
||||
|
||||
### 2. 基础使用
|
||||
|
||||
```typescript
|
||||
const optBtnGroups = new OptBtnGroups({
|
||||
container: 'btn-container', // 容器 ID 或 HTMLElement
|
||||
showLabel: true, // 显示文字标签
|
||||
onClick: (payload) => {
|
||||
console.log('点击了按钮:', payload.button.label);
|
||||
console.log('操作类型:', payload.action);
|
||||
if (payload.isActive !== undefined) {
|
||||
console.log('激活状态:', payload.isActive);
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 3. 控制显隐
|
||||
|
||||
```typescript
|
||||
new OptBtnGroups({
|
||||
container: 'btn-container',
|
||||
visibility: {
|
||||
'1-1': true, // 显示
|
||||
'3-2-1': false // 隐藏
|
||||
},
|
||||
onClick: (payload) => console.log(payload)
|
||||
});
|
||||
```
|
||||
|
||||
## 📝 API 文档
|
||||
|
||||
### 构造函数参数
|
||||
|
||||
```typescript
|
||||
interface OptBtnGroupsOptions {
|
||||
container: HTMLElement | string; // 必需：容器
|
||||
showLabel?: boolean; // 可选：显示标签（默认 true）
|
||||
visibility?: Record<string, boolean>; // 可选：显隐控制
|
||||
onClick?: (payload: ClickPayload) => void; // 可选：点击回调
|
||||
}
|
||||
```
|
||||
|
||||
### 点击事件载荷
|
||||
|
||||
```typescript
|
||||
interface ClickPayload {
|
||||
button: OptButton; // 被点击的按钮
|
||||
action: 'trigger' | 'activate' | 'deactivate'; // 操作类型
|
||||
isActive?: boolean; // 激活状态（仅 keepActive 按钮有值）
|
||||
}
|
||||
```
|
||||
|
||||
- `trigger`: 触发型操作（无状态保持）
|
||||
- `activate`: 激活按钮
|
||||
- `deactivate`: 取消激活
|
||||
|
||||
### 方法
|
||||
|
||||
```typescript
|
||||
// 销毁组件
|
||||
optBtnGroups.destroy();
|
||||
```
|
||||
|
||||
## 🛠️ 二次开发
|
||||
|
||||
### 修改内置按钮
|
||||
|
||||
编辑 `src/OptBtnGroups.ts` 中的 `defaultGroups`:
|
||||
|
||||
```typescript
|
||||
private readonly defaultGroups: ButtonGroup[] = [
|
||||
{
|
||||
id: 'my-group',
|
||||
buttons: [
|
||||
{
|
||||
id: 'home',
|
||||
label: '首页',
|
||||
icon: '<svg viewBox="0 0 24 24">...</svg>',
|
||||
keepActive: true
|
||||
}
|
||||
]
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
### 修改样式
|
||||
|
||||
编辑 `src/OptBtnGroups.css`:
|
||||
|
||||
```css
|
||||
.opt-btn {
|
||||
width: 50px; /* 按钮宽度 */
|
||||
min-height: 50px; /* 最小高度 */
|
||||
}
|
||||
|
||||
.opt-btn.active {
|
||||
background-color: rgba(255, 255, 255, 0.15); /* 激活背景 */
|
||||
border-bottom: 2px solid #fff; /* 底部指示条 */
|
||||
}
|
||||
```
|
||||
|
||||
## 📦 构建
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 开发模式
|
||||
npm run dev
|
||||
|
||||
# 构建生产版本
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 🎨 示例
|
||||
|
||||
查看 `demo-optbtn.html` 获取完整示例。
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
修改组件时请遵循：
|
||||
1. 保持中文注释
|
||||
2. 使用原生 DOM API（无框架依赖）
|
||||
3. TypeScript 严格模式
|
||||
4. 测试多种使用场景
|
||||
130
docs/Toolbar.md
130
docs/Toolbar.md
@@ -1,130 +0,0 @@
|
||||
# 工具栏组件 (Toolbar)
|
||||
|
||||
BimEngine SDK 提供了功能强大的工具栏组件 `ToolbarManager` (底层基于 `OptBtnGroups`)，支持多级菜单、按钮分组、动态显隐和样式高度定制。
|
||||
|
||||
## 1. 组件作用
|
||||
|
||||
* 提供一个统一的底部操作栏。
|
||||
* 支持按钮分组管理。
|
||||
* 支持层级下拉菜单。
|
||||
* 提供标准的交互反馈（Hover、Active、Disabled）。
|
||||
* 支持完全的样式定制（背景色、图标色、文字色等）。
|
||||
|
||||
## 2. 初始化与使用
|
||||
|
||||
通常通过 `BimEngine` 实例访问：
|
||||
|
||||
```typescript
|
||||
const engine = new BimEngine('container-id');
|
||||
// engine.toolbar 即为 ToolbarManager 实例
|
||||
```
|
||||
|
||||
或者单独使用（不推荐，除非只需工具栏）：
|
||||
|
||||
```typescript
|
||||
import { ToolbarManager } from 'bim-engine-sdk';
|
||||
const toolbar = new ToolbarManager(document.getElementById('toolbar-container'));
|
||||
```
|
||||
|
||||
## 3. 配置项
|
||||
|
||||
`ToolbarManager` 没有直接的配置项，但它管理着底层的 `OptBtnGroups`。主要配置在于添加按钮时的 `ButtonConfig` 和样式设置。
|
||||
|
||||
### ButtonConfig (按钮配置)
|
||||
|
||||
| 属性 | 类型 | 说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| `id` | `string` | 按钮唯一标识 |
|
||||
| `type` | `'button' \| 'menu'` | 按钮类型 |
|
||||
| `label` | `string` | 按钮显示文字 |
|
||||
| `icon` | `string` | SVG 图标字符串 |
|
||||
| `groupId` | `string` | 所属组 ID (必需) |
|
||||
| `parentId` | `string` | 父按钮 ID (可选，用于子菜单) |
|
||||
| `keepActive` | `boolean` | 是否保持激活状态 (Toggle 模式) |
|
||||
| `disabled` | `boolean` | 是否禁用 |
|
||||
| `onClick` | `Function` | 点击回调 |
|
||||
| `children` | `ButtonConfig[]` | 子按钮数组 |
|
||||
|
||||
### ToolbarColors (颜色配置)
|
||||
|
||||
用于 `setColors` 方法。
|
||||
|
||||
| 属性 | 说明 | 默认值 |
|
||||
| :--- | :--- | :--- |
|
||||
| `backgroundColor` | 工具栏背景色 | `rgba(17, 17, 17, 0.88)` |
|
||||
| `btnBackgroundColor` | 按钮默认背景 | `transparent` |
|
||||
| `btnHoverColor` | 按钮 Hover 背景 | `#444` |
|
||||
| `btnActiveColor` | 按钮激活背景 | `rgba(255, 255, 255, 0.15)` |
|
||||
| `iconColor` | 图标默认颜色 | `#ccc` |
|
||||
| `iconActiveColor` | 图标激活颜色 | `#fff` |
|
||||
| `textColor` | 文字默认颜色 | `#ccc` |
|
||||
| `textActiveColor` | 文字激活颜色 | `#fff` |
|
||||
|
||||
## 4. 使用案例
|
||||
|
||||
### 案例 1: 添加自定义按钮组和按钮
|
||||
|
||||
```typescript
|
||||
// 1. 添加一个新组
|
||||
engine.toolbar.addGroup('my-group');
|
||||
|
||||
// 2. 在该组添加按钮
|
||||
engine.toolbar.addButton({
|
||||
id: 'my-btn',
|
||||
groupId: 'my-group',
|
||||
type: 'button',
|
||||
label: '自定义功能',
|
||||
icon: '<svg>...</svg>', // 填入 SVG 内容
|
||||
onClick: (btn) => {
|
||||
console.log('Clicked!', btn);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 2: 添加带下拉菜单的按钮
|
||||
|
||||
```typescript
|
||||
engine.toolbar.addButton({
|
||||
id: 'menu-btn',
|
||||
groupId: 'my-group',
|
||||
type: 'menu',
|
||||
label: '更多选项',
|
||||
children: [
|
||||
{
|
||||
id: 'sub-1',
|
||||
type: 'button',
|
||||
label: '选项 A',
|
||||
onClick: () => console.log('A')
|
||||
},
|
||||
{
|
||||
id: 'sub-2',
|
||||
type: 'button',
|
||||
label: '选项 B',
|
||||
onClick: () => console.log('B')
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 3: 修改工具栏样式
|
||||
|
||||
```typescript
|
||||
engine.toolbar.setColors({
|
||||
backgroundColor: 'rgba(0, 122, 255, 0.9)', // 蓝色背景
|
||||
iconColor: '#ffffff', // 白色图标
|
||||
btnHoverColor: 'rgba(255, 255, 255, 0.2)'
|
||||
});
|
||||
```
|
||||
|
||||
### 案例 4: 控制显隐
|
||||
|
||||
```typescript
|
||||
// 隐藏整个工具栏
|
||||
engine.toolbar.setVisible(false);
|
||||
|
||||
// 隐藏特定按钮
|
||||
engine.toolbar.setButtonVisibility('my-btn', false);
|
||||
|
||||
// 隐藏文字标签
|
||||
engine.toolbar.setShowLabel(false);
|
||||
```
|
||||
548
docs/国际化实现指南.md
Normal file
548
docs/国际化实现指南.md
Normal file
@@ -0,0 +1,548 @@
|
||||
# 国际化实现指南
|
||||
|
||||
> 本文档详细描述项目的国际化（i18n）实现规范，包括翻译键定义、组件实现、语言切换等。
|
||||
|
||||
---
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [国际化的重要性](#1-国际化的重要性)
|
||||
2. [项目国际化架构](#2-项目国际化架构)
|
||||
3. [实现步骤](#3-实现步骤)
|
||||
4. [组件中的国际化实现](#4-组件中的国际化实现)
|
||||
5. [注意事项](#5-注意事项)
|
||||
6. [最佳实践](#6-最佳实践)
|
||||
7. [添加新语言](#7-添加新语言)
|
||||
8. [检查清单](#8-检查清单)
|
||||
|
||||
---
|
||||
|
||||
## 1. 国际化的重要性
|
||||
|
||||
**所有用户可见的文本都必须支持国际化，这是强制要求。**
|
||||
|
||||
- 项目支持多语言（目前：中文 `zh-CN`、英文 `en-US`）
|
||||
- 所有 UI 文本必须通过翻译函数获取
|
||||
- **严禁在代码中硬编码任何语言的文本**
|
||||
|
||||
---
|
||||
|
||||
## 2. 项目国际化架构
|
||||
|
||||
### 2.1 相关文件
|
||||
|
||||
| 文件路径 | 作用 |
|
||||
|---------|------|
|
||||
| `src/locales/types.ts` | 翻译键类型定义 |
|
||||
| `src/locales/zh-CN.ts` | 中文翻译字典 |
|
||||
| `src/locales/en-US.ts` | 英文翻译字典 |
|
||||
| `src/services/locale.ts` | 语言管理服务（单例） |
|
||||
|
||||
### 2.2 核心 API
|
||||
|
||||
```typescript
|
||||
// 导入语言服务
|
||||
import { t, localeManager } from '../../services/locale';
|
||||
|
||||
// 获取翻译文本
|
||||
const text = t('toolbar.home'); // 返回 "首页" 或 "Home"
|
||||
|
||||
// 订阅语言变更
|
||||
const unsubscribe = localeManager.subscribe(() => {
|
||||
// 语言变更时的回调
|
||||
this.setLocales();
|
||||
});
|
||||
|
||||
// 取消订阅（在组件销毁时调用）
|
||||
unsubscribe();
|
||||
|
||||
// 切换语言
|
||||
localeManager.setLocale('en-US');
|
||||
|
||||
// 获取当前语言
|
||||
const currentLocale = localeManager.getLocale();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现步骤
|
||||
|
||||
### 步骤 1：在类型文件中定义翻译键
|
||||
|
||||
**文件：`src/locales/types.ts`**
|
||||
|
||||
```typescript
|
||||
export interface TranslationDictionary {
|
||||
// ... 现有键
|
||||
myComponent: {
|
||||
title: string;
|
||||
description: string;
|
||||
buttons: {
|
||||
save: string;
|
||||
cancel: string;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 步骤 2：添加中文翻译
|
||||
|
||||
**文件：`src/locales/zh-CN.ts`**
|
||||
|
||||
```typescript
|
||||
export const zhCN: TranslationDictionary = {
|
||||
// ... 现有内容
|
||||
myComponent: {
|
||||
title: '我的组件',
|
||||
description: '这是组件描述',
|
||||
buttons: {
|
||||
save: '保存',
|
||||
cancel: '取消',
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 步骤 3：添加英文翻译
|
||||
|
||||
**文件：`src/locales/en-US.ts`**
|
||||
|
||||
```typescript
|
||||
export const enUS: TranslationDictionary = {
|
||||
// ... 现有内容
|
||||
myComponent: {
|
||||
title: 'My Component',
|
||||
description: 'This is component description',
|
||||
buttons: {
|
||||
save: 'Save',
|
||||
cancel: 'Cancel',
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 步骤 4：在代码中使用翻译函数
|
||||
|
||||
```typescript
|
||||
import { t } from '../../services/locale';
|
||||
|
||||
// 获取翻译文本
|
||||
const title = t('myComponent.title');
|
||||
|
||||
// 在 DOM 中使用
|
||||
const titleEl = document.createElement('div');
|
||||
titleEl.textContent = t('myComponent.title');
|
||||
|
||||
// 在 HTML 字符串中使用
|
||||
const html = `<div>${t('myComponent.description')}</div>`;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 组件中的国际化实现
|
||||
|
||||
### 4.1 完整实现示例
|
||||
|
||||
```typescript
|
||||
import { t, localeManager } from '../../services/locale';
|
||||
import { IBimComponent } from '../../types/component';
|
||||
import { ThemeConfig } from '../../themes/types';
|
||||
|
||||
export class MyComponent implements IBimComponent {
|
||||
private element: HTMLElement;
|
||||
private unsubscribeLocale: (() => void) | null = null;
|
||||
private unsubscribeTheme: (() => void) | null = null;
|
||||
|
||||
constructor(container: HTMLElement) {
|
||||
this.element = this.createDOM();
|
||||
container.appendChild(this.element);
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 DOM 结构
|
||||
*/
|
||||
private createDOM(): HTMLElement {
|
||||
const root = document.createElement('div');
|
||||
root.className = 'my-component';
|
||||
root.innerHTML = `
|
||||
<div class="my-component-title"></div>
|
||||
<div class="my-component-content"></div>
|
||||
<div class="my-component-actions">
|
||||
<button class="btn-save"></button>
|
||||
<button class="btn-cancel"></button>
|
||||
</div>
|
||||
`;
|
||||
return root;
|
||||
}
|
||||
|
||||
/**
|
||||
* 初始化组件
|
||||
*/
|
||||
public init(): void {
|
||||
// 订阅语言变更
|
||||
this.unsubscribeLocale = localeManager.subscribe(() => {
|
||||
this.setLocales();
|
||||
});
|
||||
|
||||
// 初始设置语言
|
||||
this.setLocales();
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置/更新所有文本（语言变更时调用）
|
||||
*/
|
||||
public setLocales(): void {
|
||||
// 更新标题
|
||||
const titleEl = this.element.querySelector('.my-component-title');
|
||||
if (titleEl) {
|
||||
titleEl.textContent = t('myComponent.title');
|
||||
}
|
||||
|
||||
// 更新内容
|
||||
const contentEl = this.element.querySelector('.my-component-content');
|
||||
if (contentEl) {
|
||||
contentEl.textContent = t('myComponent.description');
|
||||
}
|
||||
|
||||
// 更新按钮
|
||||
const saveBtn = this.element.querySelector('.btn-save');
|
||||
if (saveBtn) {
|
||||
saveBtn.textContent = t('myComponent.buttons.save');
|
||||
}
|
||||
|
||||
const cancelBtn = this.element.querySelector('.btn-cancel');
|
||||
if (cancelBtn) {
|
||||
cancelBtn.textContent = t('myComponent.buttons.cancel');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置主题
|
||||
*/
|
||||
public setTheme(theme: ThemeConfig): void {
|
||||
// 主题设置逻辑
|
||||
}
|
||||
|
||||
/**
|
||||
* 销毁组件
|
||||
*/
|
||||
public destroy(): void {
|
||||
// 取消语言订阅
|
||||
if (this.unsubscribeLocale) {
|
||||
this.unsubscribeLocale();
|
||||
this.unsubscribeLocale = null;
|
||||
}
|
||||
|
||||
// 取消主题订阅
|
||||
if (this.unsubscribeTheme) {
|
||||
this.unsubscribeTheme();
|
||||
this.unsubscribeTheme = null;
|
||||
}
|
||||
|
||||
// 移除 DOM
|
||||
this.element.remove();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 关键点说明
|
||||
|
||||
1. **在 `init()` 中订阅语言变更**
|
||||
2. **实现 `setLocales()` 方法更新所有文本**
|
||||
3. **在 `destroy()` 中取消订阅**
|
||||
4. **使用 `t('key.path')` 获取翻译文本**
|
||||
|
||||
---
|
||||
|
||||
## 5. 注意事项
|
||||
|
||||
### 5.1 ✅ 必须做的
|
||||
|
||||
#### 所有用户可见文本使用 `t(key)`
|
||||
|
||||
```typescript
|
||||
// ✅ 正确
|
||||
button.textContent = t('toolbar.home');
|
||||
|
||||
// ❌ 错误
|
||||
button.textContent = '首页';
|
||||
button.textContent = 'Home';
|
||||
```
|
||||
|
||||
#### 翻译键使用有意义的路径
|
||||
|
||||
```typescript
|
||||
// ✅ 正确：按功能模块组织
|
||||
t('toolbar.home')
|
||||
t('dialog.title')
|
||||
t('button.save')
|
||||
t('message.success')
|
||||
|
||||
// ❌ 错误：键名不清晰
|
||||
t('text1')
|
||||
t('label')
|
||||
t('str')
|
||||
```
|
||||
|
||||
#### 在所有语言文件中添加翻译
|
||||
|
||||
- 添加新键时，必须同时更新 `zh-CN.ts` 和 `en-US.ts`
|
||||
- 确保所有语言文件的结构一致
|
||||
|
||||
#### 实现 `setLocales()` 方法
|
||||
|
||||
- 所有组件必须实现 `setLocales()` 方法
|
||||
- 在方法中更新所有用户可见的文本
|
||||
|
||||
#### 订阅语言变更
|
||||
|
||||
- 组件初始化时订阅 `localeManager.subscribe()`
|
||||
- 组件销毁时取消订阅
|
||||
|
||||
### 5.2 ❌ 禁止做的
|
||||
|
||||
#### 禁止硬编码文本
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：硬编码中文
|
||||
const title = '首页';
|
||||
|
||||
// ❌ 错误：硬编码英文
|
||||
const title = 'Home';
|
||||
|
||||
// ✅ 正确：使用翻译函数
|
||||
const title = t('toolbar.home');
|
||||
```
|
||||
|
||||
#### 禁止在翻译键中使用变量
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：动态拼接键名（难以追踪和维护）
|
||||
t(`toolbar.${buttonId}`);
|
||||
|
||||
// ✅ 正确：使用完整的键名
|
||||
t('toolbar.home');
|
||||
t('toolbar.settings');
|
||||
```
|
||||
|
||||
#### 禁止忽略语言变更
|
||||
|
||||
- 组件必须响应语言切换
|
||||
- 不能只在初始化时设置文本
|
||||
|
||||
---
|
||||
|
||||
## 6. 最佳实践
|
||||
|
||||
### 6.1 翻译键的组织结构
|
||||
|
||||
```typescript
|
||||
// 按功能模块组织
|
||||
interface TranslationDictionary {
|
||||
// 工具栏相关
|
||||
toolbar: {
|
||||
home: string;
|
||||
settings: string;
|
||||
measure: string;
|
||||
};
|
||||
|
||||
// 弹窗相关
|
||||
dialog: {
|
||||
title: string;
|
||||
content: string;
|
||||
close: string;
|
||||
};
|
||||
|
||||
// 按钮相关
|
||||
button: {
|
||||
save: string;
|
||||
cancel: string;
|
||||
confirm: string;
|
||||
delete: string;
|
||||
};
|
||||
|
||||
// 消息相关
|
||||
message: {
|
||||
success: string;
|
||||
error: string;
|
||||
warning: string;
|
||||
loading: string;
|
||||
};
|
||||
|
||||
// 表单相关
|
||||
form: {
|
||||
required: string;
|
||||
invalid: string;
|
||||
placeholder: {
|
||||
name: string;
|
||||
email: string;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 嵌套键的使用
|
||||
|
||||
对于复杂组件，可以使用嵌套结构：
|
||||
|
||||
```typescript
|
||||
// 类型定义
|
||||
measurePanel: {
|
||||
modes: {
|
||||
distance: string;
|
||||
angle: string;
|
||||
area: string;
|
||||
};
|
||||
labels: {
|
||||
currentMode: string;
|
||||
result: string;
|
||||
};
|
||||
actions: {
|
||||
clear: string;
|
||||
settings: string;
|
||||
};
|
||||
};
|
||||
|
||||
// 使用
|
||||
t('measurePanel.modes.distance') // "距离"
|
||||
t('measurePanel.labels.result') // "结果"
|
||||
```
|
||||
|
||||
### 6.3 处理动态内容
|
||||
|
||||
如果需要在翻译中插入动态内容，建议：
|
||||
|
||||
```typescript
|
||||
// 方案 1：翻译后拼接（简单场景）
|
||||
const message = t('file.selected') + `: ${fileName}`;
|
||||
|
||||
// 方案 2：使用模板（需要扩展 LocaleManager）
|
||||
// 翻译字典: "已选择 {count} 个文件"
|
||||
const message = t('file.selectedCount', { count: 5 });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 添加新语言
|
||||
|
||||
### 步骤 1：扩展语言类型
|
||||
|
||||
**文件：`src/locales/types.ts`**
|
||||
|
||||
```typescript
|
||||
export type LocaleType = 'zh-CN' | 'en-US' | 'ja-JP'; // 添加日语
|
||||
```
|
||||
|
||||
### 步骤 2：创建翻译文件
|
||||
|
||||
**文件：`src/locales/ja-JP.ts`**
|
||||
|
||||
```typescript
|
||||
import { TranslationDictionary } from './types';
|
||||
|
||||
export const jaJP: TranslationDictionary = {
|
||||
toolbar: {
|
||||
home: 'ホーム',
|
||||
settings: '設定',
|
||||
// ... 所有翻译
|
||||
},
|
||||
// ... 完整的翻译字典
|
||||
};
|
||||
```
|
||||
|
||||
### 步骤 3：注册新语言
|
||||
|
||||
**文件：`src/services/locale.ts`**
|
||||
|
||||
```typescript
|
||||
import { jaJP } from '../locales/ja-JP';
|
||||
|
||||
class LocaleManager {
|
||||
private messages: Record<LocaleType, TranslationDictionary> = {
|
||||
'zh-CN': zhCN,
|
||||
'en-US': enUS,
|
||||
'ja-JP': jaJP, // 添加新语言
|
||||
};
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 检查清单
|
||||
|
||||
在开发新功能时，确保完成以下检查：
|
||||
|
||||
### 8.1 翻译键
|
||||
|
||||
- [ ] 在 `types.ts` 中定义了新的翻译键类型
|
||||
- [ ] 在 `zh-CN.ts` 中添加了中文翻译
|
||||
- [ ] 在 `en-US.ts` 中添加了英文翻译
|
||||
- [ ] 翻译键名清晰、有意义
|
||||
- [ ] 翻译键结构与类型定义一致
|
||||
|
||||
### 8.2 组件实现
|
||||
|
||||
- [ ] 所有用户可见的文本都使用 `t(key)` 函数
|
||||
- [ ] 组件实现了 `setLocales()` 方法
|
||||
- [ ] 组件在 `init()` 中订阅了语言变更事件
|
||||
- [ ] 组件在 `destroy()` 中取消了语言订阅
|
||||
|
||||
### 8.3 代码质量
|
||||
|
||||
- [ ] 没有硬编码任何语言的文本
|
||||
- [ ] 没有使用动态拼接的翻译键
|
||||
- [ ] 翻译文本语法正确、表达清晰
|
||||
|
||||
### 8.4 测试验证
|
||||
|
||||
- [ ] 在中文环境下测试文本显示正确
|
||||
- [ ] 在英文环境下测试文本显示正确
|
||||
- [ ] 切换语言后所有文本正确更新
|
||||
- [ ] 没有遗漏的未翻译文本
|
||||
|
||||
---
|
||||
|
||||
## 附录：现有翻译键参考
|
||||
|
||||
### 工具栏 (toolbar)
|
||||
|
||||
```typescript
|
||||
toolbar: {
|
||||
home: '首页' | 'Home',
|
||||
settings: '设置' | 'Settings',
|
||||
info: '信息' | 'Info',
|
||||
location: '定位' | 'Location',
|
||||
measure: '测量' | 'Measure',
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 弹窗 (dialog)
|
||||
|
||||
```typescript
|
||||
dialog: {
|
||||
title: '弹窗标题' | 'Dialog Title',
|
||||
close: '关闭' | 'Close',
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 测量面板 (measure)
|
||||
|
||||
```typescript
|
||||
measure: {
|
||||
modes: {
|
||||
distance: '距离' | 'Distance',
|
||||
angle: '角度' | 'Angle',
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v1.0
|
||||
**最后更新**：2026-01-21
|
||||
Reference in New Issue
Block a user