@jieyin/editor-sdk 1.1.181 → 1.1.183

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 (5) hide show
  1. package/dist/editor-sdk.es.js +5075 -5030
  2. package/dist/renderWorker.js +2396 -2393
  3. package/dist/style.css +1 -1
  4. package/package.json +1 -1
  5. package/README.md +0 -283
package/README.md DELETED
@@ -1,283 +0,0 @@
1
- # @jieyin/editor-sdk 使用文档
2
-
3
- 基于 **Vue 3** + **Fabric.js** 的可视化设计编辑器 SDK：产品选型、刀版/变形模板、图层编辑、预览渲染、设计保存与还原、可选图库与 License。
4
-
5
- npm 包名以仓库内 `package.json` 的 `name` 字段为准（当前为 `@jieyin/editor-sdk`）。若你们私有源使用其它名称，请将下文导入路径替换为实际包名。
6
-
7
- ---
8
-
9
- ## 目录
10
-
11
- - [安装与对等依赖](#安装与对等依赖)
12
- - [样式](#样式)
13
- - [快速开始](#快速开始)
14
- - [Editor 组件](#editor-组件)
15
- - [组件实例方法（defineExpose）](#组件实例方法defineexpose)
16
- - [国际化与主题](#国际化与主题)
17
- - [类型定义](#类型定义)
18
- - [工具与服务](#工具与服务)
19
- - [部署：Worker 与 WASM 静态资源](#部署worker-与-wasm-静态资源)
20
- - [进阶：Composables](#进阶composables)
21
- - [相关文档](#相关文档)
22
-
23
- ---
24
-
25
- ## 安装与对等依赖
26
-
27
- ```bash
28
- pnpm add @jieyin/editor-sdk
29
- # 或 npm / yarn
30
- ```
31
-
32
- ### 对等依赖（须在业务项目中安装）
33
-
34
- 与 `sdk/package.json` 中 `peerDependencies` 保持一致：
35
-
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
- ---
44
-
45
- ## 样式
46
-
47
- ```ts
48
- import '@jieyin/editor-sdk/style.css'
49
- ```
50
-
51
- ---
52
-
53
- ## 快速开始
54
-
55
- ### 全局注册
56
-
57
- ```ts
58
- // main.ts
59
- import { createApp } from 'vue'
60
- import App from './App.vue'
61
- import { install } from '@jieyin/editor-sdk'
62
- import '@jieyin/editor-sdk/style.css'
63
-
64
- const app = createApp(App)
65
- app.use(install) // 注册全局组件名 Editor
66
- app.mount('#app')
67
- ```
68
-
69
- ### 按需引入组件（推荐）
70
-
71
- ```vue
72
- <template>
73
- <Editor
74
- ref="editorRef"
75
- :product="product"
76
- :basic-info="basicInfo"
77
- :diecut-data="diecutData"
78
- :deformation-data="deformationData"
79
- :license-config="licenseConfig"
80
- :file-token="fileToken"
81
- :on-save-design="onSaveDesign"
82
- />
83
- </template>
84
-
85
- <script setup lang="ts">
86
- import { ref } from 'vue'
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'
96
-
97
- const editorRef = ref<InstanceType<typeof Editor> | null>(null)
98
- const product = ref<ProductItem | null>(null)
99
- const basicInfo = ref<BasicInfo | null>(null)
100
- const diecutData = ref<DiecutResponse | null>(null)
101
- const deformationData = ref<DeformationResponse | null>(null)
102
- const fileToken = ref<string | null>(null)
103
- const licenseConfig: LicenseConfig = {
104
- licenseKey: 'YOUR_LICENSE_KEY',
105
- apiBaseUrl: 'https://your-license-api.com',
106
- }
107
-
108
- async function onSaveDesign() {
109
- const result = editorRef.value?.getDiecutStateMap?.()
110
- // 调用业务保存接口，上传 result 等
111
- }
112
- </script>
113
- ```
114
-
115
- ---
116
-
117
- ## Editor 组件
118
-
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（常用字段）
156
-
157
- ```ts
158
- interface EditorOptions {
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
176
- }
177
- ```
178
-
179
- 更完整的字段说明以 `sdk/src/types.ts` 中 `EditorOptions` 注释为准。
180
-
181
- ---
182
-
183
- ## 组件实例方法（defineExpose）
184
-
185
- 通过 `ref` 获取 `Editor` 实例后可调用：
186
-
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 上传完成后也可调用） |
200
-
201
- **入参 / 出参细节**（尤其 `getDiecutStateMap`、`renderAllTemplates`、`loadDesignStateMap`）见仓库内 [`docs/API-对接文档.md`](./docs/API-对接文档.md)。
202
-
203
- ---
204
-
205
- ## 国际化与主题
206
-
207
- ### 语言
208
-
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` 用于与运行时选择器联动。
220
-
221
- ---
222
-
223
- ## 类型定义
224
-
225
- 从包入口导出（节选）：
226
-
227
- - 产品与接口：`ProductItem`、`BasicInfo`、`DiecutResponse`、`DeformationResponse`、`ProductListApi`、`ProductDetailApi`、`GalleryApi`、`GalleryMaterialItem` 等
228
- - 编辑器：`EditorOptions`、`EditorProps`、`DiecutStateMapResult`、`CustomSidebarTabDef`、`EditorSidebarContext`、`EDITOR_SIDEBAR_CONTEXT_KEY`
229
- - License：`LicenseConfig` 及 `utils/license` 导出项
230
-
231
- ```ts
232
- import type {
233
- ProductItem,
234
- BasicInfo,
235
- DiecutResponse,
236
- DeformationResponse,
237
- EditorOptions,
238
- LicenseConfig,
239
- } from '@jieyin/editor-sdk'
240
- ```
241
-
242
- 完整列表见 `sdk/src/types.ts` 与 `sdk/src/index.ts`。
243
-
244
- ---
245
-
246
- ## 工具与服务
247
-
248
- ### 文件 Token（`fileToken`）
249
-
250
- 导出包含：`setExternalFileToken`、`getFileToken`、`clearFileToken`、`ensureFileToken`、`appendFileTokenToUrl`、`withFileToken`、`fetchWithFileToken`、`setFileTokenFetchers`、`isFileTokenExpired` 等（以 `src/utils/fileToken.ts` 为准）。
251
-
252
- - 传入 Editor 的 `file-token` 或与 `setExternalFileToken` 配合，用于带鉴权的资源 URL。
253
-
254
- ### JSON 缓存（可选）
255
-
256
- `fetchJsonWithFileTokenCached`、`clearJsonFileCache`。
257
-
258
- ### License
259
-
260
- `LicenseAPI`、`LicenseManager`、`setLicenseInfo`、`getLicenseInfo`、`clearLicenseInfo`、`TokenRefresher`、`withRetry` 等。
261
-
262
- ### 渲染服务 `renderService`
263
-
264
- 用于按 JSON 做蒙版、混合、变形、Worker 调度等（预览/导出链路）。类型如 `IRenderByJson`；具体 API 见 `sdk/src/utils/renderService/`。
265
-
266
- ### 其它工具
267
-
268
- `StorageUtil`、`Environment`、`UrlUtil`、`appendOssResize`、`HttpClient`、`ErrorHandler`、`WorkerManager`、`resolveBasicInfoColorLabel` 等由 `src/index.ts` 导出。
269
-
270
- ---
271
-
272
- ## 部署：Worker 与 WASM 静态资源
273
-
274
- 生产环境下，SDK 通过**固定绝对路径**加载资源（见 `src/utils/workerLoader.ts`、`wasm/perspectiveLoader.ts`）。宿主应用需要将下列文件部署到站点根路径对应目录（或自行配置反向代理到等价 URL）：
275
-
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 运行时脚本 |
281
-
282
- 开发时若使用本地 Vite，通常将上述文件放在宿主项目的 `public/` 下即可。
283
-