@jieyin/editor-sdk 1.1.140 → 1.1.181

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +154 -267
  2. package/dist/deform.worker.js +141 -141
  3. package/dist/editor-sdk.es.js +15755 -8740
  4. package/dist/renderWorker.js +36112 -1964
  5. package/dist/style.css +1 -1
  6. package/package.json +51 -48
package/README.md CHANGED
@@ -1,38 +1,48 @@
1
1
  # @jieyin/editor-sdk 使用文档
2
2
 
3
- 基于 Vue 3 + Fabric.js 的可视化设计编辑器 SDK，支持产品选型、刀版/变形模板、图层编辑、预览渲染与设计保存/还原。
3
+ 基于 **Vue 3** + **Fabric.js** 的可视化设计编辑器 SDK：产品选型、刀版/变形模板、图层编辑、预览渲染、设计保存与还原、可选图库与 License。
4
+
5
+ npm 包名以仓库内 `package.json` 的 `name` 字段为准（当前为 `@jieyin/editor-sdk`）。若你们私有源使用其它名称，请将下文导入路径替换为实际包名。
4
6
 
5
7
  ---
6
8
 
7
9
  ## 目录
8
10
 
9
- - [安装与依赖](#安装与依赖)
11
+ - [安装与对等依赖](#安装与对等依赖)
12
+ - [样式](#样式)
10
13
  - [快速开始](#快速开始)
11
14
  - [Editor 组件](#editor-组件)
15
+ - [组件实例方法（defineExpose）](#组件实例方法defineexpose)
16
+ - [国际化与主题](#国际化与主题)
12
17
  - [类型定义](#类型定义)
13
18
  - [工具与服务](#工具与服务)
19
+ - [部署：Worker 与 WASM 静态资源](#部署worker-与-wasm-静态资源)
14
20
  - [进阶：Composables](#进阶composables)
15
- - [常见场景示例](#常见场景示例)
21
+ - [相关文档](#相关文档)
16
22
 
17
23
  ---
18
24
 
19
- ## 安装与依赖
25
+ ## 安装与对等依赖
20
26
 
21
27
  ```bash
22
- npm install @jieyin/editor-sdk
23
- # 或
24
28
  pnpm add @jieyin/editor-sdk
25
- # 或
26
- yarn add @jieyin/editor-sdk
29
+ # 或 npm / yarn
27
30
  ```
28
31
 
29
- ### 对等依赖（需在业务项目中安装）
32
+ ### 对等依赖（须在业务项目中安装）
33
+
34
+ 与 `sdk/package.json` 中 `peerDependencies` 保持一致：
30
35
 
31
- | 依赖 | 版本 |
32
- | --- | ------ |
33
- | vue | ^3.5.0 |
36
+ | 依赖 | 版本范围 |
37
+ | ------------- | ---------- |
38
+ | vue | ^3.5.0 |
39
+ | fabric | ^7.1.0 |
40
+ | pinia | ^3.0.0 |
41
+ | element-plus | ^2.13.0 |
42
+
43
+ ---
34
44
 
35
- ### 引入样式
45
+ ## 样式
36
46
 
37
47
  ```ts
38
48
  import '@jieyin/editor-sdk/style.css'
@@ -42,7 +52,7 @@ import '@jieyin/editor-sdk/style.css'
42
52
 
43
53
  ## 快速开始
44
54
 
45
- ### 方式一：全局注册
55
+ ### 全局注册
46
56
 
47
57
  ```ts
48
58
  // main.ts
@@ -52,27 +62,39 @@ import { install } from '@jieyin/editor-sdk'
52
62
  import '@jieyin/editor-sdk/style.css'
53
63
 
54
64
  const app = createApp(App)
55
- app.use(install)
65
+ app.use(install) // 注册全局组件名 Editor
56
66
  app.mount('#app')
57
67
  ```
58
68
 
69
+ ### 按需引入组件（推荐）
70
+
59
71
  ```vue
60
72
  <template>
61
73
  <Editor
74
+ ref="editorRef"
62
75
  :product="product"
63
76
  :basic-info="basicInfo"
64
77
  :diecut-data="diecutData"
65
78
  :deformation-data="deformationData"
66
79
  :license-config="licenseConfig"
67
80
  :file-token="fileToken"
68
- @save-design="onSaveDesign"
81
+ :on-save-design="onSaveDesign"
69
82
  />
70
83
  </template>
71
84
 
72
85
  <script setup lang="ts">
73
86
  import { ref } from 'vue'
74
- import type { ProductItem, BasicInfo, DiecutResponse, DeformationResponse, LicenseConfig } from '@jieyin/editor-sdk'
87
+ import {
88
+ Editor,
89
+ type ProductItem,
90
+ type BasicInfo,
91
+ type DiecutResponse,
92
+ type DeformationResponse,
93
+ type LicenseConfig,
94
+ } from '@jieyin/editor-sdk'
95
+ import '@jieyin/editor-sdk/style.css'
75
96
 
97
+ const editorRef = ref<InstanceType<typeof Editor> | null>(null)
76
98
  const product = ref<ProductItem | null>(null)
77
99
  const basicInfo = ref<BasicInfo | null>(null)
78
100
  const diecutData = ref<DiecutResponse | null>(null)
@@ -80,128 +102,131 @@ const deformationData = ref<DeformationResponse | null>(null)
80
102
  const fileToken = ref<string | null>(null)
81
103
  const licenseConfig: LicenseConfig = {
82
104
  licenseKey: 'YOUR_LICENSE_KEY',
83
- apiBaseUrl: 'https://your-license-api.com'
105
+ apiBaseUrl: 'https://your-license-api.com',
84
106
  }
85
107
 
86
- function onSaveDesign() {
87
- // 调用业务保存接口
108
+ async function onSaveDesign() {
109
+ const result = editorRef.value?.getDiecutStateMap?.()
110
+ // 调用业务保存接口，上传 result 等
88
111
  }
89
112
  </script>
90
113
  ```
91
114
 
92
- ### 方式二：按需引入组件
93
-
94
- ```vue
95
- <template>
96
- <Editor
97
- :product="product"
98
- :basic-info="basicInfo"
99
- :diecut-data="diecutData"
100
- :deformation-data="deformationData"
101
- :options="{ showTopbar: true, showSidebar: true, showPreview: true }"
102
- :license-config="licenseConfig"
103
- :file-token="fileToken"
104
- :on-save-design="onSaveDesign"
105
- :on-object-modified="onObjectModified"
106
- />
107
- </template>
108
-
109
- <script setup lang="ts">
110
- import { Editor, type LicenseConfig, type ProductItem, type BasicInfo, type DiecutResponse, type DeformationResponse } from '@jieyin/editor-sdk'
111
- import '@jieyin/editor-sdk/style.css'
112
-
113
- // ... 同上
114
- </script>
115
- ```
116
-
117
115
  ---
118
116
 
119
117
  ## Editor 组件
120
118
 
121
- ### Props
122
-
123
- | 属性 | 类型 | 默认值 | 说明 |
124
- | ------------------------ | ------------------------------------------------------------ | ------ | ------------------------------------------- |
125
- | `product` | `ProductItem \| null` | `null` | 当前选中的产品（单产品模式直接传入） |
126
- | `basicInfo` | `BasicInfo \| null` | `null` | 产品基础信息（名称、尺码、颜色等） |
127
- | `diecutData` | `DiecutResponse \| null` | `null` | 刀版数据（含 jsonURL、resources 等） |
128
- | `deformationData` | `DeformationResponse \| null` | `null` | 变形/模板数据 |
129
- | `options` | `EditorOptions` | 见下 | 界面与行为配置 |
130
- | `productListApi` | `ProductListApi` | - | 产品列表接口（列表模式必传） |
131
- | `productDetailApi` | `ProductDetailApi` | - | 产品详情接口（列表模式必传） |
132
- | `productListPageSize` | `number` | - | 产品列表每页条数 |
133
- | `productListInitialPage` | `number` | - | 产品列表初始页码 |
134
- | `initialProductId` | `string \| number` | - | 进入时默认选中的产品 ID；不在第一页时也会按 ID 加载详情并展示 |
135
- | `fileBaseUrl` | `string` | - | 文件资源基础 URL（用于代理/拼接） |
136
- | `licenseConfig` | `LicenseConfig` | - | License 配置（不传则不做 License 校验） |
137
- | `fileToken` | `string \| null` | `null` | 文件访问 Token（用于带鉴权的图片/资源） |
138
- | `onObjectModified` | `(getDiecutStateMap: () => DiecutStateMapResult) => void` | - | 画布内容变更回调，调用 `getDiecutStateMap()` 可得 `{ stateMap, selectedColor, selectedSize, selectedMode, designCanvasSize }` |
139
- | `onRenderAllTemplates` | `(renderMethod) => Promise<...>` | - | 自定义「渲染所有模板」逻辑（如上传到服务器） |
140
- | `onSaveDesign` | `() => void \| Promise<void>` | - | 保存设计（传入则在 Topbar 显示保存按钮） |
141
- | `onGoHome` | `() => void` | - | 返回首页（传入则在 Topbar 显示返回按钮） |
142
- | `onTemplateReady` | `() => void` | - | 首次模板加载完成后调用（可用于从 completeJsonUrl 还原设计） |
143
-
144
- #### EditorOptions
119
+ ### Props（摘要）
120
+
121
+ | 属性 | 类型 | 说明 |
122
+ | --- | --- | --- |
123
+ | `product` | `ProductItem \| null` | 当前产品（单产品模式） |
124
+ | `basicInfo` | `BasicInfo \| null` | 名称、尺码、颜色等 |
125
+ | `diecutData` | `DiecutResponse \| null` | 刀版数据（含 `jsonURL`、`resources` 等） |
126
+ | `deformationData` | `DeformationResponse \| null` | 变形/模板数据 |
127
+ | `options` | `EditorOptions` | 界面与行为，见下表 |
128
+ | `productListApi` | `ProductListApi` | 产品列表（列表模式） |
129
+ | `productDetailApi` | `ProductDetailApi` | 产品详情（列表模式） |
130
+ | `productListPageSize` | `number` | 列表每页条数 |
131
+ | `productListInitialPage` | `number` | 列表初始页 |
132
+ | `initialProductId` | `string \| number` | 进入时默认选中的产品 ID（若在第一页列表中） |
133
+ | `fileBaseUrl` | `string` | 文件资源基础 URL |
134
+ | `licenseConfig` | `LicenseConfig` | License；不传则不做校验 |
135
+ | `fileToken` | `string \| null` | 文件访问 Token |
136
+ | `galleryApi` | `GalleryApi \| null` | 注入后显示「图库」侧栏 Tab |
137
+ | `locale` | `string` | 界面语言，见 [国际化](#国际化与主题) |
138
+ | `messages` | `Record<string, string>` | 覆盖内置文案 |
139
+ | `customSidebarTabs` | `CustomSidebarTabDef[]` | 自定义侧栏 Tab |
140
+ | `onObjectModified` | `(getDiecutStateMap) => void` | 画布变更；调用 getter 得到 `DiecutStateMapResult` |
141
+ | `onRenderAllTemplates` | `(renderMethod) => Promise<...>` | 自定义批量渲染逻辑 |
142
+ | `onSaveDesign` | `() => void \| Promise<void>` | 传入则顶栏显示保存 |
143
+ | `onAddToCart` | `() => void \| Promise<void>` | 传入则顶栏显示加购（未使用内置 `options.addToCart` 时） |
144
+ | `onAddToCartSuccess` / `onAddToCartError` | 回调 | 仅在使用内置加购弹窗 `options.addToCart` 时由 SDK 调用 |
145
+ | `onGoHome` | `() => void` | 返回按钮 |
146
+ | `onTemplateReady` | `() => void \| Promise<void>` | 首次模板加载完成（适合在此 `loadDesignStateMap` 还原） |
147
+
148
+ ### 事件（emit）
149
+
150
+ | 事件 | 载荷 | 说明 |
151
+ | --- | --- | --- |
152
+ | `update:locale` | `EditorLocale` | 顶栏切换语言时 |
153
+ | `update:uiTheme` | `EditorUiTheme` | `options.showUiThemeSelect === true` 时切换主题 |
154
+
155
+ ### EditorOptions（常用字段）
145
156
 
146
157
  ```ts
147
158
  interface EditorOptions {
148
- showTopbar?: boolean // 是否显示顶栏，默认 true
149
- showSidebar?: boolean // 是否显示左侧栏，默认 true
150
- showPreview?: boolean // 是否显示预览面板，默认 true
151
- enableGrid?: boolean // 是否启用网格，默认 true
152
- usePreviewEffect?: boolean // 是否使用预览效果组件，默认 true
159
+ showTopbar?: boolean
160
+ showSidebar?: boolean
161
+ showPreview?: boolean
162
+ enableGrid?: boolean
163
+ usePreviewEffect?: boolean
164
+ showPreviewDownload?: boolean
165
+ showImageButton?: boolean
166
+ topbarImageSkipGallery?: boolean
167
+ initialSidebarTab?: string
168
+ readOnly?: boolean
169
+ /** 省略或未设为 `'default'` 时与 theme1 一致（粉主色）；仅显式 `'default'` 为靛蓝主题 */
170
+ uiTheme?: 'default' | 'theme1'
171
+ showUiThemeSelect?: boolean
172
+ onTheme1UploadLocalFiles?: (file: File) => void | Promise<void>
173
+ addToCart?: EditorAddToCartAdapter
174
+ addToCartEditMeta?: { psTaskId?: string }
175
+ currencySymbol?: string
153
176
  }
154
177
  ```
155
178
 
156
- ### 暴露方法（ref 调用）
179
+ 更完整的字段说明以 `sdk/src/types.ts` 中 `EditorOptions` 注释为准。
157
180
 
158
- > **详细入参/出参说明**：见 [API 对接文档](./docs/API-对接文档.md)，含 `getDiecutStateMap`、`renderAllTemplates` 等核心方法的入参、出参及对接示例。
181
+ ---
159
182
 
160
- 通过 `ref` 获取组件实例后，可调用以下方法：
183
+ ## 组件实例方法（defineExpose）
161
184
 
162
- | 方法 | 说明 |
163
- | -------------------------------- | ------------------------------------------------------------------------------- |
164
- | `renderAllTemplates()` | 渲染当前产品下所有模板，返回 `Promise<Array<{ index: number; bitmap: ImageBitmap \| null }>>` |
165
- | `triggerRenderAllTemplates()` | 触发一次「渲染所有模板」（会走 `onRenderAllTemplates` 若已传） |
166
- | `getDiecutStateMap()` | 获取带元数据的设计状态：`{ stateMap, selectedColor, selectedSize, selectedMode, designCanvasSize }`（用于保存设计） |
167
- | `getCurrentProductName()` | 获取当前产品名称 |
168
- | `loadCanvasJson(diecutId, json)` | 按刀版 ID 加载一份画布 JSON |
169
- | `loadDesignStateMap(payload)` | 还原设计：支持 `{ stateMap, selectedColor?, selectedSize? }` 或旧格式 `Record<diecutId, fabricJson>` |
185
+ 通过 `ref` 获取 `Editor` 实例后可调用：
170
186
 
171
- 示例：
187
+ | 方法 | 说明 |
188
+ | --- | --- |
189
+ | `renderAllTemplates()` | 渲染当前产品下所有模板图，`Promise<Array<{ index; bitmap; blob? }>>` |
190
+ | `triggerRenderAllTemplates()` | 触发一次批量渲染（若配置了 `onRenderAllTemplates` 会走宿主逻辑） |
191
+ | `getDiecutStateMap()` | 保存设计用：`{ stateMap, selectedColor, selectedSize, selectedMode, designCanvasSize }` |
192
+ | `getCurrentProductName()` | 当前产品名称 |
193
+ | `getCurrentProductId()` | 当前产品 ID |
194
+ | `getHasDualTemplateModes()` | 当前尺码是否同时存在单片/多片两种模板 |
195
+ | `setSelectedColor` / `setSelectedSize` / `setSelectedMode` | 程序化切换颜色、尺码、模板模式 |
196
+ | `loadCanvasJson(diecutId, json)` | 按刀版 ID 加载一份画布 JSON |
197
+ | `loadDesignStateMap(payload)` | 还原设计：支持带元数据对象或旧版 `Record<diecutId, fabricJson>` |
198
+ | `getCurrentPreviewImageBlob(opts?)` | 当前预览图 Blob（可加 `renderSize`） |
199
+ | `addImageFromUrl(url)` | 按 URL 向画布加图（与图库选图一致；theme1 上传完成后也可调用） |
172
200
 
173
- ```vue
174
- <template>
175
- <Editor ref="editorRef" ... />
176
- </template>
201
+ **入参 / 出参细节**（尤其 `getDiecutStateMap`、`renderAllTemplates`、`loadDesignStateMap`）见仓库内 [`docs/API-对接文档.md`](./docs/API-对接文档.md)。
177
202
 
178
- <script setup lang="ts">
179
- import { ref } from 'vue'
180
- import { Editor } from '@jieyin/editor-sdk'
203
+ ---
181
204
 
182
- const editorRef = ref<InstanceType<typeof Editor> | null>(null)
205
+ ## 国际化与主题
183
206
 
184
- async function save() {
185
- const result = editorRef.value?.getDiecutStateMap?.()
186
- const name = editorRef.value?.getCurrentProductName?.()
187
- // result 为 { stateMap, selectedColor, selectedSize, selectedMode, designCanvasSize }，上传到后端...
188
- }
207
+ ### 语言
189
208
 
190
- async function restore(payload: { stateMap: Record<string, unknown>; selectedColor?: string; selectedSize?: string } | Record<string, unknown>) {
191
- editorRef.value?.loadDesignStateMap?.(payload)
192
- }
193
- </script>
194
- ```
209
+ - Props：`locale`，支持 `zh-CN`、`en-US`、`ja-JP`、`ko-KR`、`vi-VN`；兼容旧值 `zh` / `en`。
210
+ - 也可从包中导入：`EDITOR_SUPPORTED_LOCALES`、`EDITOR_FALLBACK_LOCALE`、`normalizeEditorLocaleParam`、`isEditorLocale`。
211
+ - 顶栏切换语言时会 `emit('update:locale', ...)`，宿主可写回自己的 i18n。
212
+
213
+ ### 文案覆盖
214
+
215
+ `messages` 的 key 与 SDK 内置 locales 一致，用于增量覆盖。
216
+
217
+ ### UI 主题
218
+
219
+ `options.uiTheme`：`default` 与 `theme1` 含义见 `EditorOptions` 注释；`resolveEditorUiTheme` 用于与运行时选择器联动。
195
220
 
196
221
  ---
197
222
 
198
223
  ## 类型定义
199
224
 
200
- 从 `@jieyin/editor-sdk` 可导出以下常用类型（详见 `src/types.ts`）：
225
+ 从包入口导出（节选）：
201
226
 
202
- - **产品与配置**：`ProductItem`、`BasicInfo`、`EditorOptions`、`EditorProps`、`LicenseConfig`
203
- - **刀版与变形**：`DiecutResource`、`DiecutItem`、`DiecutResponse`、`DeformationInfo`、`DeformationGroup`、`DeformationResponse`、`DeformationSizeGroup`、`DeformationColorGroup`
204
- - **接口约定**：`ProductListApi`、`ProductDetailApi`、`ProductListResult`、`ProductDetailResult`
227
+ - 产品与接口：`ProductItem`、`BasicInfo`、`DiecutResponse`、`DeformationResponse`、`ProductListApi`、`ProductDetailApi`、`GalleryApi`、`GalleryMaterialItem` 等
228
+ - 编辑器：`EditorOptions`、`EditorProps`、`DiecutStateMapResult`、`CustomSidebarTabDef`、`EditorSidebarContext`、`EDITOR_SIDEBAR_CONTEXT_KEY`
229
+ - License：`LicenseConfig` 及 `utils/license` 导出项
205
230
 
206
231
  ```ts
207
232
  import type {
@@ -211,186 +236,48 @@ import type {
211
236
  DeformationResponse,
212
237
  EditorOptions,
213
238
  LicenseConfig,
214
- ProductListApi,
215
- ProductDetailApi
216
239
  } from '@jieyin/editor-sdk'
217
240
  ```
218
241
 
242
+ 完整列表见 `sdk/src/types.ts` 与 `sdk/src/index.ts`。
243
+
219
244
  ---
220
245
 
221
246
  ## 工具与服务
222
247
 
223
- ### 文件 Token（fileToken）
224
-
225
- 用于带鉴权的文件 URL（如图片、刀版资源）。支持「外部注入」或「内部拉取 + 自动附加」。
226
-
227
- ```ts
228
- import {
229
- setExternalFileToken,
230
- getFileToken,
231
- clearFileToken,
232
- ensureFileToken,
233
- appendFileTokenToUrl,
234
- appendFileTokenIfPresent,
235
- withFileToken,
236
- fetchWithFileToken,
237
- setFileTokenFetchers,
238
- isFileTokenExpired
239
- } from '@jieyin/editor-sdk'
240
- ```
241
-
242
- - **外部注入**：业务侧维护 Token，通过 `setExternalFileToken(token)` 注入；Editor 内部请求文件时会自动用该 Token 拼到 URL。
243
- - **内部拉取**：`setFileTokenFetchers({ fetchFileToken, fetchFileTokenRefresh })` 后，`ensureFileToken()` / `fetchWithFileToken(url)` 会负责获取/刷新并附加 Token。
244
-
245
- ### License
246
-
247
- ```ts
248
- import {
249
- LicenseAPI,
250
- LicenseManager,
251
- setLicenseInfo,
252
- getLicenseInfo,
253
- clearLicenseInfo,
254
- TokenRefresher,
255
- withRetry
256
- } from '@jieyin/editor-sdk'
257
- ```
248
+ ### 文件 Token（`fileToken`）
258
249
 
259
- - 在 Editor 上通过 `licenseConfig` 传入即可完成校验与刷新；也可在非 Editor 场景下单独使用 `LicenseManager` / `LicenseAPI`。
250
+ 导出包含：`setExternalFileToken`、`getFileToken`、`clearFileToken`、`ensureFileToken`、`appendFileTokenToUrl`、`withFileToken`、`fetchWithFileToken`、`setFileTokenFetchers`、`isFileTokenExpired` 等（以 `src/utils/fileToken.ts` 为准）。
260
251
 
261
- ### 渲染服务（renderService）
252
+ - 传入 Editor 的 `file-token` 或与 `setExternalFileToken` 配合，用于带鉴权的资源 URL。
262
253
 
263
- 用于按 JSON 渲染位图、蒙版、混合等（多用于预览与导出）：
254
+ ### JSON 缓存（可选）
264
255
 
265
- ```ts
266
- import type { IRenderByJson } from '@jieyin/editor-sdk'
267
- // 以及 renderService 下具体方法按需使用
268
- ```
256
+ `fetchJsonWithFileTokenCached`、`clearJsonFileCache`。
269
257
 
270
- ---
258
+ ### License
271
259
 
272
- ## 进阶：Composables
260
+ `LicenseAPI`、`LicenseManager`、`setLicenseInfo`、`getLicenseInfo`、`clearLicenseInfo`、`TokenRefresher`、`withRetry` 等。
273
261
 
274
- Editor 内部由多个 composable 组成（产品数据、模板、刀版、画布、图层、工具状态等）。若你需要在自定义页面中复用某一块能力，可直接从 SDK 引入对应 composable（注：部分依赖 Editor 内部上下文，建议以「使用 Editor 组件」为主，按需再抽 composable）。
262
+ ### 渲染服务 `renderService`
275
263
 
276
- 导出列表见 `sdk/src/components/Editor/composables/index.ts`，例如：
264
+ 用于按 JSON 做蒙版、混合、变形、Worker 调度等（预览/导出链路）。类型如 `IRenderByJson`；具体 API 见 `sdk/src/utils/renderService/`。
277
265
 
278
- - `useLicense`、`useProductData`、`useToolState`、`useTemplateManager`
279
- - `useCanvasManager`、`useLayerManager`、`useDiecutManager`
280
- - `useImageHandler`、`useTextHandler`、`useLayerOperations`、`useObjectAdder`
281
- - `usePreviewManager`、`usePreviewRenderer`、`usePreviewUpdateQueue`
282
- - `useTemplateLoader`、`useCanvasStateByDiecut`、`useCanvasViewport`
283
- - `useEditorWatchers`、`useCopyToDiecuts`、`useClearCanvas`、`useEditorReset`、`useDownloadPng`
284
- - 以及相关类型：`TemplateItem`、`Layer`、`DiecutOption`、`UseTemplateLoaderOptions` 等
266
+ ### 其它工具
285
267
 
286
- 更细的 composable 说明见：`sdk/src/components/Editor/README.md`。
268
+ `StorageUtil`、`Environment`、`UrlUtil`、`appendOssResize`、`HttpClient`、`ErrorHandler`、`WorkerManager`、`resolveBasicInfoColorLabel` 等由 `src/index.ts` 导出。
287
269
 
288
270
  ---
289
271
 
290
- ## 常见场景示例
291
-
292
- ### 单产品模式（直接传产品与详情数据）
293
-
294
- ```vue
295
- <Editor
296
- :product="product"
297
- :basic-info="basicInfo"
298
- :diecut-data="diecutData"
299
- :deformation-data="deformationData"
300
- :file-token="fileToken"
301
- :license-config="licenseConfig"
302
- :on-save-design="onSaveDesign"
303
- />
304
- ```
305
-
306
- 数据由业务侧请求产品详情接口得到后，赋给 `basicInfo`、`diecutData`、`deformationData` 即可。
307
-
308
- ### 产品列表模式（分页 + 选产品拉详情）
309
-
310
- ```vue
311
- <Editor
312
- :product-list-api="productListApi"
313
- :product-detail-api="productDetailApi"
314
- :product-list-page-size="12"
315
- :product-list-initial-page="1"
316
- :initial-product-id="initialProductId"
317
- :file-token="fileToken"
318
- :license-config="licenseConfig"
319
- :on-save-design="onSaveDesign"
320
- />
321
- ```
322
-
323
- - `productListApi(page, pageSize)` 返回 `{ rows: ProductItem[], total?: number }`
324
- - `productDetailApi(productId)` 返回 `{ basicInfo, diecutData, deformationData }`
325
- - `initialProductId` 若落在第一页列表中，进入后会默认选中该产品。
326
-
327
- ### 保存设计（拿状态 Map + 调用业务接口）
328
-
329
- ```ts
330
- const editorRef = ref<InstanceType<typeof Editor> | null>(null)
331
-
332
- async function onSaveDesign() {
333
- const result = editorRef.value?.getDiecutStateMap?.()
334
- const productName = editorRef.value?.getCurrentProductName?.()
335
- if (!result?.stateMap) return
336
- await saveDesignTask({ productName, ...result })
337
- }
338
- ```
339
-
340
- ### 从已保存设计还原（如编辑我的设计）
341
-
342
- 1. 拉取设计详情，拿到 `completeJsonUrl` 或按刀版分组的 `stateMap`。
343
-
344
- 2. 若用 `stateMap`：先让 Editor 完成模板加载（产品、刀版、变形数据就绪），在 `onTemplateReady` 中调用：
345
-
346
- ```ts
347
- editorRef.value?.loadDesignStateMap?.(payload)
348
- ```
349
-
350
- 3. 若用 `completeJsonUrl`：在 `onTemplateReady` 中 fetch 该 JSON，解析成 `{ stateMap, selectedColor?, selectedSize? }` 或旧格式的 stateMap，再调用 `loadDesignStateMap(payload)`。
351
-
352
- ### License 配置
353
-
354
- ```ts
355
- const licenseConfig: LicenseConfig = {
356
- licenseKey: 'YOUR_LICENSE_KEY',
357
- apiBaseUrl: 'https://your-license-api.com',
358
- timeout: 10000,
359
- enableAutoRefresh: true,
360
- refreshThreshold: 0.3,
361
- onError: (err) => console.error('License Error:', err),
362
- onSuccess: () => console.log('License OK'),
363
- onTokenRefresh: (token) => { /* 可选：同步到业务 */ }
364
- }
365
- ```
366
-
367
- 不传 `licenseConfig` 时，Editor 不进行 License 校验，直接进入编辑界面。
368
-
369
- ### 文件 Token（外部注入，如登录后从业务接口拿）
370
-
371
- ```ts
372
- const fileToken = ref<string | null>(null)
272
+ ## 部署：Worker 与 WASM 静态资源
373
273
 
374
- onMounted(async () => {
375
- const res = await yourAuthApi.getFileToken()
376
- fileToken.value = res.file_token
377
- // 可选：同步给 SDK 内部使用
378
- setExternalFileToken(res.file_token)
379
- })
380
- ```
381
-
382
- ```vue
383
- <Editor :file-token="fileToken" ... />
384
- ```
385
-
386
- 业务侧负责 Token 刷新时，保持 `fileToken` 或 `setExternalFileToken` 更新即可。
387
-
388
- ---
274
+ 生产环境下，SDK 通过**固定绝对路径**加载资源（见 `src/utils/workerLoader.ts`、`wasm/perspectiveLoader.ts`）。宿主应用需要将下列文件部署到站点根路径对应目录（或自行配置反向代理到等价 URL）：
389
275
 
390
- ## 版本与构建
276
+ | 路径 | 说明 |
277
+ | --- | --- |
278
+ | `/sdk-workers/*.js` | `renderWorker.js`、`maskWorker.js`、`deform.worker.js`、`copyDiecuts.worker.js` 等；构建产物或仓库 `public/sdk-workers` 示例可供参考 |
279
+ | `/assets/perspective.wasm` | 透视相关 WASM（若使用对应能力） |
280
+ | `/assets/wasm_exec.js` | Go WASM 运行时脚本 |
391
281
 
392
- - 当前包名：`@jieyin/editor-sdk`，版本见 `package.json`。
393
- - 构建：`npm run build`（会先执行 wasm 构建再打 SDK 包）。
394
- - 产物：`dist/editor-sdk.es.js`、`dist/style.css`、`dist/index.d.ts`。
282
+ 开发时若使用本地 Vite，通常将上述文件放在宿主项目的 `public/` 下即可。
395
283
 
396
- 如有问题或需要定制，请联系维护团队。