yui-image-editor 1.0.4 → 1.0.6

package/README.md

@@ -1,73 +1,188 @@
-# tui-image-editor-demo
-
-This template should help get you started developing with Vue 3 in Vite.
-
-## Recommended IDE Setup
-
-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
-
-## Recommended Browser Setup
-
-- Chromium-based browsers (Chrome, Edge, Brave, etc.):
-  - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
-  - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
-- Firefox:
-  - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
-  - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
-
-## Type Support for `.vue` Imports in TS
-
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
-
-## Customize configuration
-
-See [Vite Configuration Reference](https://vite.dev/config/).
-
-## Project Setup
-
-```sh
-npm install
-```
-
-### Compile and Hot-Reload for Development
-
-```sh
-npm run dev
-```
-
-### Type-Check, Compile and Minify for Production
-
-```sh
-npm run build
-```
-
-### Run Unit Tests with [Vitest](https://vitest.dev/)
-
-```sh
-npm run test:unit
-```
-
-### Run End-to-End Tests with [Playwright](https://playwright.dev)
-
-```sh
-# Install browsers for the first run
-npx playwright install
-
-# When testing on CI, must build the project first
-npm run build
-
-# Runs the end-to-end tests
-npm run test:e2e
-# Runs the tests only on Chromium
-npm run test:e2e -- --project=chromium
-# Runs the tests of a specific file
-npm run test:e2e -- tests/example.spec.ts
-# Runs the tests in debug mode
-npm run test:e2e -- --debug
-```
-
-### Lint with [ESLint](https://eslint.org/)
-
-```sh
-npm run lint
-```
+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
+<template>
+  <div class="container">
+    <ImageEditor ref="yuiImageEditor" :editorConfig="editorConfig"></ImageEditor>
+    <div @click="updateImage">更换图片</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import type { EditorConfig, TuiImageEditor } from "yui-image-editor";
+import mapOverlay from './assets/map-overlay.png';
+import map02Png from './assets/map02.png';
+const yuiImageEditor = ref()  //组件实例和方法
+let yuiInstance:  TuiImageEditor | null = null  // 编辑器内部函数和方法
+const editorConfig: EditorConfig = {
+  includeUI: {
+    loadImage: {
+      path: mapOverlay, // 优先用传入的url
+      name: 'mapoverlay'
+    },
+    initMenu: 'text',
+    menuBarPosition: 'left',
+    uiSize: {
+      width: '100%',
+      height: '100%'
+    }
+  },
+  selectionStyle: {
+    cornerSize: 20,
+    rotatingPointOffset: 70
+  },
+  usageStatistics: false,
+  cssMaxHeight: document.documentElement.clientWidth,
+  cssMaxWidth: document.documentElement.clientHeight
+};
+onMounted(async()=>{
+  yuiInstance = yuiImageEditor.value.getCoreEditor();
+  console.log(yuiImageEditor.value, '===组件实例和方法===')
+  console.log(yuiInstance,'===编辑器实例和方法===')
+})
+
+const updateImage = async()=>{
+  // 修改图片
+  const loadImageRes = await yuiImageEditor.value.loadImageFromURL(map02Png,'map02Png')
+  console.log(loadImageRes,'===loadImageRes')
+}
+</script>
+
+<style scoped>
+  .container{
+    width: 100%;
+    height: 80vh;
+    position: relative;
+  }
+</style>
+\`\`\`
+
+### 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<void>\`                     | 添加标题                 |
+| addTimestamp        | -                                     | \`Promise<void>\`                     | 添加时间戳               |
+| addFigureLabel      | \`title?: string\`（默认：附图）        | \`Promise<void>\`                     | 添加附图标签             |
+| addComparisonBox    | -                                     | \`Promise<void>\`                     | 添加对比拉框             |
+| addCalibrationTarget | -                                     | \`Promise<void>\`                     | 添加标定目标             |
+| 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

package/dist/types/index.d.ts

@@ -1,60 +1,15 @@
 import { default as YuiImageEditor } from './components/ImageEditor/index';
 import { YuiImageEditorProps } from './types/component';
 import { App } from 'vue';
-import type * as TuiEditorTypes from '@/types/index';
+export type * from './types/index';
 declare const ImageEditorComponent: {
     new (): {
         $props: YuiImageEditorProps;
     } & typeof YuiImageEditor;
 };
-export { ImageEditorComponent as ImageEditor, YuiImageEditor };
-export type { TuiEditorTypes, YuiImageEditorProps };
+export { ImageEditorComponent as ImageEditor };
 declare const _default: {
     install: (app: App) => void;
-    YuiImageEditor: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
-        editorConfig: {
-            type: import('vue').PropType<TuiEditorTypes.EditorConfig>;
-            default: () => {};
-        };
-    }>, {
-        showStatus: (message: string, type?: "success" | "error" | "info") => void;
-        updateCanvasSize: () => void;
-        addTitle: (title?: string) => Promise<void>;
-        addTimestamp: () => Promise<void>;
-        addFigureLabel: (title?: string) => Promise<void>;
-        addComparisonBox: () => Promise<void>;
-        addCalibrationTarget: () => Promise<void>;
-        getCoreEditor: () => TuiEditorTypes.TuiImageEditor | null;
-        loadImageFromURL: (imageUrl: string, imageName?: string) => Promise<{
-            success: boolean;
-            message: string;
-        }>;
-        destroy: () => void;
-    }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-        init: (editor: TuiEditorTypes.TuiImageEditor) => any;
-        statusChange: (status: import('./components/ImageEditor/editor.types').EditorOperationStatus | null) => any;
-        canvasSizeChange: (size: {
-            width: number;
-            height: number;
-        }) => any;
-    }, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
-        editorConfig: {
-            type: import('vue').PropType<TuiEditorTypes.EditorConfig>;
-            default: () => {};
-        };
-    }>> & Readonly<{
-        onInit?: ((editor: TuiEditorTypes.TuiImageEditor) => any) | undefined;
-        onStatusChange?: ((status: import('./components/ImageEditor/editor.types').EditorOperationStatus | null) => any) | undefined;
-        onCanvasSizeChange?: ((size: {
-            width: number;
-            height: number;
-        }) => any) | undefined;
-    }>, {
-        editorConfig: TuiEditorTypes.EditorConfig;
-    }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {
-        editorContainer: HTMLDivElement;
-        editorRef: HTMLDivElement;
-    }, HTMLDivElement>;
     ImageEditor: new () => {
         $props: YuiImageEditorProps;
     } & typeof YuiImageEditor;