feat: upgrade iflow-engine-base to v1.0.5, add pause/resume rendering API
- Update iflow-engine-base from 1.0.1 to 1.0.5 - Change default engine version from v1 to v2 - Add pauseRendering() and resumeRendering() methods - Add switch model feature in demos - Update model URLs in demos - Add new documentation files
This commit is contained in:
yuding
402
docs/MODULES/services.md
Normal file
402
docs/MODULES/services.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# Services 模块文档
|
||||
|
||||
## 模块概述
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **模块名** | services |
|
||||
| **职责** | 提供全局状态管理服务：国际化和主题系统 |
|
||||
| **公开 API** | 2 个管理器类 + 辅助函数 |
|
||||
| **状态** | ✅ 稳定 |
|
||||
|
||||
## 代码地图
|
||||
|
||||
```
|
||||
src/
|
||||
├── services/
|
||||
│ ├── locale.ts # 国际化服务
|
||||
│ └── theme.ts # 主题服务
|
||||
├── locales/
|
||||
│ ├── types.ts # 翻译类型定义
|
||||
│ ├── zh-CN.ts # 中文翻译
|
||||
│ └── en-US.ts # 英文翻译
|
||||
└── themes/
|
||||
├── types.ts # 主题类型定义
|
||||
└── presets.ts # 内置主题预设
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## LocaleManager（国际化服务）
|
||||
|
||||
### 概述
|
||||
|
||||
管理应用语言、翻译文本，支持实时订阅。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class LocaleManager {
|
||||
getLocale(): LocaleType;
|
||||
setLocale(locale: LocaleType): void;
|
||||
t(key: string): string;
|
||||
subscribe(listener: (locale: LocaleType) => void): () => void;
|
||||
}
|
||||
|
||||
type LocaleType = 'zh-CN' | 'en-US';
|
||||
|
||||
// 单例导出
|
||||
export const localeManager: LocaleManager;
|
||||
|
||||
// 便捷函数
|
||||
export function t(key: string): string;
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
import { localeManager, t } from 'iflow-engine';
|
||||
|
||||
// 获取当前语言
|
||||
const locale = localeManager.getLocale(); // 'zh-CN'
|
||||
|
||||
// 切换语言
|
||||
localeManager.setLocale('en-US');
|
||||
|
||||
// 翻译
|
||||
console.log(t('toolbar.home')); // 'Home'
|
||||
console.log(t('measure.modes.distance')); // 'Distance'
|
||||
|
||||
// 订阅语言变更
|
||||
const unsubscribe = localeManager.subscribe((locale) => {
|
||||
console.log('Language changed:', locale);
|
||||
});
|
||||
```
|
||||
|
||||
### 翻译键结构
|
||||
|
||||
| 域 | 说明 | 示例 |
|
||||
|---|------|------|
|
||||
| `common` | 通用文本 | `common.title` |
|
||||
| `toolbar` | 工具栏按钮 | `toolbar.home`, `toolbar.measure` |
|
||||
| `dialog` | 对话框 | `dialog.testTitle` |
|
||||
| `menu` | 菜单项 | `menu.info` |
|
||||
| `tree` | 树形控件 | `tree.searchPlaceholder` |
|
||||
| `measure` | 测量工具 | `measure.modes.distance`, `measure.units.m` |
|
||||
| `sectionPlane` | 平面剖切 | `sectionPlane.dialogTitle` |
|
||||
| `sectionAxis` | 轴向剖切 | `sectionAxis.dialogTitle` |
|
||||
| `sectionBox` | 剖切盒 | `sectionBox.dialogTitle` |
|
||||
| `walkControl` | 漫游控制 | `walkControl.speed` |
|
||||
| `map` | 地图 | `map.dialogTitle` |
|
||||
|
||||
### 扩展新语言
|
||||
|
||||
1. 创建翻译文件 `src/locales/ja-JP.ts`
|
||||
2. 更新类型 `src/locales/types.ts`
|
||||
3. 注册到 LocaleManager
|
||||
|
||||
```typescript
|
||||
// src/locales/ja-JP.ts
|
||||
export const jaJP: TranslationDictionary = {
|
||||
common: { title: 'BimEngine' },
|
||||
toolbar: { home: 'ホーム', measure: '測定' },
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ThemeManager（主题服务）
|
||||
|
||||
### 概述
|
||||
|
||||
管理应用主题、颜色方案，支持实时订阅。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ThemeManager {
|
||||
getTheme(): ThemeConfig;
|
||||
setTheme(themeName: 'dark' | 'light'): void;
|
||||
setCustomTheme(theme: ThemeConfig): void;
|
||||
subscribe(listener: (theme: ThemeConfig) => void): () => void;
|
||||
}
|
||||
|
||||
// 单例导出
|
||||
export const themeManager: ThemeManager;
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
import { themeManager } from 'iflow-engine';
|
||||
|
||||
// 获取当前主题
|
||||
const theme = themeManager.getTheme();
|
||||
console.log(theme.primary); // '#2563eb'
|
||||
|
||||
// 切换预设主题
|
||||
themeManager.setTheme('dark');
|
||||
|
||||
// 自定义主题
|
||||
themeManager.setCustomTheme({
|
||||
name: 'custom',
|
||||
primary: '#ff6b6b',
|
||||
// ...
|
||||
});
|
||||
|
||||
// 订阅主题变更
|
||||
const unsubscribe = themeManager.subscribe((theme) => {
|
||||
console.log('Theme changed:', theme.name);
|
||||
});
|
||||
```
|
||||
|
||||
### 预设主题
|
||||
|
||||
#### 亮色主题 (`lightTheme`)
|
||||
|
||||
| 属性 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| `primary` | `#2563eb` | 主色 |
|
||||
| `bgBase` | `#f8fafc` | 页面背景 |
|
||||
| `bgElevated` | `#ffffff` | 卡片背景 |
|
||||
| `textPrimary` | `#0f172a` | 主文本 |
|
||||
| `textSecondary` | `#475569` | 次要文本 |
|
||||
|
||||
#### 暗色主题 (`darkTheme`)
|
||||
|
||||
| 属性 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| `primary` | `#3b82f6` | 主色 |
|
||||
| `bgBase` | `#152232` | 页面背景 |
|
||||
| `bgElevated` | `#1f2d3e` | 卡片背景 |
|
||||
| `textPrimary` | `#ffffff` | 主文本 |
|
||||
| `textSecondary` | `#94a3b8` | 次要文本 |
|
||||
|
||||
### ThemeConfig 结构
|
||||
|
||||
```typescript
|
||||
interface ThemeConfig {
|
||||
name: string;
|
||||
|
||||
// 品牌色
|
||||
primary: string;
|
||||
primaryHover: string;
|
||||
primaryActive: string;
|
||||
primarySubtle: string;
|
||||
|
||||
// 状态色
|
||||
success: string;
|
||||
warning: string;
|
||||
danger: string;
|
||||
info: string;
|
||||
|
||||
// 背景色
|
||||
bgBase: string;
|
||||
bgElevated: string;
|
||||
bgOverlay: string;
|
||||
bgInset: string;
|
||||
bgGlass: string;
|
||||
bgGlassBlur: string;
|
||||
|
||||
// 文字色
|
||||
textPrimary: string;
|
||||
textSecondary: string;
|
||||
textTertiary: string;
|
||||
textDisabled: string;
|
||||
textInverse: string;
|
||||
textLink: string;
|
||||
|
||||
// 图标色
|
||||
iconDefault: string;
|
||||
iconHover: string;
|
||||
iconActive: string;
|
||||
iconDisabled: string;
|
||||
|
||||
// 边框色
|
||||
borderDefault: string;
|
||||
borderSubtle: string;
|
||||
borderStrong: string;
|
||||
divider: string;
|
||||
|
||||
// 组件状态
|
||||
componentBg: string;
|
||||
componentBgHover: string;
|
||||
componentBgActive: string;
|
||||
componentBgSelected: string;
|
||||
|
||||
// 焦点
|
||||
focusRing: string;
|
||||
selectionBg: string;
|
||||
|
||||
// 阴影
|
||||
shadowSm: string;
|
||||
shadowMd: string;
|
||||
shadowLg: string;
|
||||
shadowGlow: string;
|
||||
|
||||
// 浮动层
|
||||
floatingBg: string;
|
||||
floatingBorder: string;
|
||||
floatingBtnBg: string;
|
||||
floatingBtnBgHover: string;
|
||||
floatingIconColor: string;
|
||||
|
||||
// 面板
|
||||
panelBg: string;
|
||||
panelBorder: string;
|
||||
panelHeaderBg: string;
|
||||
panelRadius: string;
|
||||
|
||||
// 选项卡
|
||||
tabBg: string;
|
||||
tabItemBg: string;
|
||||
tabItemBgActive: string;
|
||||
tabItemTextActive: string;
|
||||
|
||||
// 组件覆盖（可选）
|
||||
overrides?: {
|
||||
dialog?: { headerBg?: string };
|
||||
toolbar?: { bg?: string; buttonBg?: string };
|
||||
input?: { bg?: string; placeholder?: string };
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 创建自定义主题
|
||||
|
||||
```typescript
|
||||
import { createThemeFromPartial, lightTheme } from 'iflow-engine';
|
||||
|
||||
// 基于预设创建（推荐）
|
||||
const customTheme = createThemeFromPartial(lightTheme, {
|
||||
name: 'coral',
|
||||
primary: '#ff6b6b',
|
||||
primaryHover: '#ff5252',
|
||||
primaryActive: '#ff4757',
|
||||
});
|
||||
|
||||
themeManager.setCustomTheme(customTheme);
|
||||
```
|
||||
|
||||
### CSS 变量映射
|
||||
|
||||
主题颜色自动映射到 CSS 变量：
|
||||
|
||||
```css
|
||||
.my-component {
|
||||
background-color: var(--bim-bg-elevated);
|
||||
color: var(--bim-text-primary);
|
||||
border: 1px solid var(--bim-border-default);
|
||||
}
|
||||
|
||||
.my-button {
|
||||
background-color: var(--bim-primary);
|
||||
color: var(--bim-text-inverse);
|
||||
}
|
||||
|
||||
.my-button:hover {
|
||||
background-color: var(--bim-primary-hover);
|
||||
}
|
||||
```
|
||||
|
||||
常用 CSS 变量：
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
| `--bim-primary` | 主色 |
|
||||
| `--bim-bg-base` | 页面背景 |
|
||||
| `--bim-bg-elevated` | 卡片背景 |
|
||||
| `--bim-text-primary` | 主文本 |
|
||||
| `--bim-border-default` | 边框 |
|
||||
| `--bim-shadow-sm` | 小阴影 |
|
||||
|
||||
---
|
||||
|
||||
## React 集成
|
||||
|
||||
```typescript
|
||||
import { useEffect, useState } from 'react';
|
||||
import { localeManager, themeManager } from 'iflow-engine';
|
||||
|
||||
// 语言 Hook
|
||||
export function useLocale() {
|
||||
const [locale, setLocale] = useState(() => localeManager.getLocale());
|
||||
|
||||
useEffect(() => {
|
||||
return localeManager.subscribe(setLocale);
|
||||
}, []);
|
||||
|
||||
return { locale, setLocale: localeManager.setLocale.bind(localeManager) };
|
||||
}
|
||||
|
||||
// 主题 Hook
|
||||
export function useTheme() {
|
||||
const [theme, setTheme] = useState(() => themeManager.getTheme());
|
||||
|
||||
useEffect(() => {
|
||||
return themeManager.subscribe(setTheme);
|
||||
}, []);
|
||||
|
||||
return { theme, setTheme: themeManager.setTheme.bind(themeManager) };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 单例模式
|
||||
|
||||
两个服务都采用单例模式：
|
||||
|
||||
```typescript
|
||||
export const localeManager = new LocaleManager();
|
||||
export const themeManager = new ThemeManager();
|
||||
```
|
||||
|
||||
### 观察者模式
|
||||
|
||||
支持订阅状态变更：
|
||||
|
||||
```typescript
|
||||
// 订阅
|
||||
const unsubscribe = themeManager.subscribe((theme) => {
|
||||
// 更新 UI
|
||||
});
|
||||
|
||||
// 取消订阅
|
||||
unsubscribe();
|
||||
```
|
||||
|
||||
### 与 BimEngine 集成
|
||||
|
||||
```typescript
|
||||
const engine = new BimEngine('container', {
|
||||
locale: 'zh-CN',
|
||||
theme: 'dark'
|
||||
});
|
||||
|
||||
// 动态切换
|
||||
engine.setLocale('en-US');
|
||||
engine.setTheme('light');
|
||||
engine.setCustomTheme(customTheme);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```
|
||||
BimEngine
|
||||
↓
|
||||
LocaleManager ←→ locales/*.ts
|
||||
↓
|
||||
ThemeManager ←→ themes/*.ts
|
||||
```
|
||||
|
||||
Services 模块无外部依赖，完全自包含。
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
Reference in New Issue
Block a user