cat > README.md << EOF

yui-image-editor 图片编辑器组件

yui-image-editor 是基于 `tui-image-editor` 封装的 Vue3 + TypeScript 图片编辑器组件，扩展了专题图编辑专属功能（标题、时间戳、附图标签、对比拉框、标定目标等），支持自定义配置、多语言、主题定制及 A4 尺寸快速切换等能力。

一、组件使用指南

1. 安装依赖

确保项目中安装核心依赖： ```bash npm install tui-image-editor

若需类型提示，安装对应的类型包（如无官方类型，可自定义）

npm install -D @types/tui-image-editor ```

2. 基础使用

2.1 2.1 全局引入并注册

```ts // 局部引入（推荐） import { ImageEditor } from 'yui-image-editor'; import 'yui-image-editor/dist/yui-image-editor.css'; const app = createApp(App); app.component('ImageEditor', ImageEditor); app.mount('#app') ```

2.2 局部引入组件

```ts import ImageEditor from '@/components/yui-image-editor/index.vue'; ```

2.3 快速集成

```vue

```

3. Props 说明

| 名称 | 类型 | 默认值 | 说明 | |--------------|--------------|--------------|--------------------------| | editorConfig | `EditorConfig` | 见核心配置部分 | 编辑器自定义配置，深度合并覆盖默认配置 |

4. 事件说明

| 事件名 | 回调参数类型 | 说明 | |-----------------|------------------------------------------------------------------------------|--------------------------| | statusChange | `{ message: string; type: 'success' | 'error' | 'info' }` | 编辑器操作状态变更（成功/失败/提示） | | canvasSizeChange | `{ width: number; height: number }` | 画布尺寸变更时触发 | | init | `TuiImageEditor`（编辑器核心实例） | 编辑器初始化完成时触发 |

5. 暴露的方法（通过 ref 调用）

| 方法名 | 参数 | 返回值 | 说明 | |---------------------|---------------------------------------|-------------------------------------|--------------------------| | loadImageFromURL | `imageUrl: string, imageName?: string` | `Promise<{ success: boolean; message: string }>` | 加载指定URL的图片 | | getCoreEditor | - | `TuiImageEditor | null` | 获取编辑器核心实例 | | addTitle | `title?: string`（默认：专题图标题） | `Promise` | 添加标题 | | addTimestamp | - | `Promise` | 添加时间戳 | | addFigureLabel | `title?: string`（默认：附图） | `Promise` | 添加附图标签 | | addComparisonBox | - | `Promise` | 添加对比拉框 | | addCalibrationTarget | - | `Promise` | 添加标定目标 | | destroy | - | `void` | 销毁编辑器（组件卸载时自动调用） |

二、组件核心内容

1. 核心架构

组件采用 Vue3 + TypeScript 组合式 API 开发，核心分为 5 个模块： ``` ├── 配置层：默认配置 + 外部传入配置深度合并 ├── 实例层：tui-image-editor 核心实例 + 专题图工具实例 ├── 扩展层：自定义菜单（文本/形状/A4尺寸）+ DOM 操作 ├── 交互层：鼠标监听 + 状态反馈 + 事件派发 ├── 生命周期：挂载初始化 + 卸载销毁 ```

2. 默认配置（可通过 props 覆盖）

```ts const defaultConfig: EditorConfig = { includeUI: { loadImage: { path: mapOverlay, // 初始默认图片 name: 'DefaultImage' }, initMenu: 'icon', // 初始激活菜单 menuBarPosition: 'left', // 菜单栏位置 locale: zhLocale, // 中文语言包 theme: customTheme, // 自定义主题 uiSize: { width: '100%', height: '100%' } // 编辑器尺寸 }, selectionStyle: { // 选中元素样式 cornerSize: 20, rotatingPointOffset: 70 }, usageStatistics: true, // 统计开关 cssMaxHeight: document.documentElement.clientWidth, // 最大高度 cssMaxWidth: document.documentElement.clientHeight // 最大宽度 }; ```

3. 关键扩展功能

3.1 自定义菜单扩展

• 文本菜单：新增「标题」「时间」「附图」按钮，绑定对应添加方法；
• 形状菜单：新增「对比拉框」「标定目标」按钮，实现专题图专属形状；
• 尺寸菜单：新增「A4-横版」开关，一键切换画布为 A4 横版尺寸（1754*1240）。

3.2 专题图工具（SpecialMapTool）

封装 `SpecialMapTool` 类，基于 tui-image-editor 核心 API 实现专题图专属元素的添加/管理，核心方法：

• `addTitle`：添加带样式的专题图标题；
• `addTimestamp`：添加格式化时间戳；
• `addFigureLabel`：添加附图标签；
• `addComparisonBox`：添加可拖拽/缩放的对比拉框；
• `addCalibrationTarget`：添加标定目标图形。

3.3 图片加载封装

将原生回调式的 `loadImageFromURL` 封装为 Promise 风格，增加前置校验（编辑器实例、URL 非空）和错误分类（跨域/无效URL），便于异步调用和错误处理。

3.4 生命周期管理

• 挂载（onMounted）：初始化编辑器实例 → 初始化专题图工具 → 扩展菜单 → 绑定鼠标监听 → 派发初始化事件；
• 卸载（onUnmounted）：销毁编辑器实例 → 移除事件监听 → 清空工具实例，避免内存泄漏。

4. 类型定义（TypeScript）

核心类型约束，保证类型安全：

• `EditorConfig`：编辑器配置类型；
• `TuiImageEditor`：编辑器核心实例类型；
• `EditorOperationStatus`：操作状态类型；
• `ImageEditorEmits`：组件派发事件类型；
• 暴露方法的参数/返回值类型全覆盖。

5. 样式与适配

• 编辑器容器自适应父元素尺寸（宽高 100%）；
• 监听窗口 resize 事件，自动调整编辑器尺寸；
• 选中元素样式自定义（角标大小、旋转点偏移）；
• 自定义主题（customTheme）覆盖默认样式，适配业务视觉风格。

三、注意事项

1. 图片加载需注意跨域问题：若加载远程图片，需确保图片服务器配置 CORS；
2. 组件卸载时会自动调用 `destroy` 方法，手动销毁需通过 ref 调用；
3. 自定义配置采用深度合并（deepMerge），可精准覆盖默认配置的任意层级；
4. 专题图工具（SpecialMapTool）需依赖 tui-image-editor 实例，初始化失败时会触发 error 状态提示。 EOF