@printine/pod-editor 0.0.0-stage → 0.1.14

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 (222) hide show
  1. package/README.md +242 -2
  2. package/dist/DesignerRuntimeContext.d.ts +3 -0
  3. package/dist/PrintineDesigner.d.ts +9 -0
  4. package/dist/api/asset-client.d.ts +8 -0
  5. package/dist/api/asset-client.js +40 -0
  6. package/dist/api/asset-endpoints.d.ts +36 -0
  7. package/dist/api/client.d.ts +8 -0
  8. package/dist/api/client.js +82 -0
  9. package/dist/api/common-endpoints.d.ts +12 -0
  10. package/dist/api/design-endpoints.d.ts +4 -0
  11. package/dist/api/endpoints.d.ts +23 -0
  12. package/dist/api/endpoints.js +33 -0
  13. package/dist/api/files-endpoints.d.ts +1 -0
  14. package/dist/assets/icons/aspect_ratio.d.ts +3 -0
  15. package/dist/assets/icons/delete.d.ts +3 -0
  16. package/dist/assets/icons/fit_screen.d.ts +3 -0
  17. package/dist/assets/icons/index.d.ts +11 -0
  18. package/dist/assets/icons/loading_1.d.ts +3 -0
  19. package/dist/assets/icons/loading_2.d.ts +3 -0
  20. package/dist/assets/icons/loading_3.d.ts +3 -0
  21. package/dist/assets/icons/pan.d.ts +3 -0
  22. package/dist/assets/icons/setting.d.ts +3 -0
  23. package/dist/assets/icons/text_color.d.ts +3 -0
  24. package/dist/assets/icons/text_h.d.ts +3 -0
  25. package/dist/assets/icons/text_v.d.ts +3 -0
  26. package/dist/bundled-assets.d.ts +4 -0
  27. package/dist/components/add-design.d.ts +8 -0
  28. package/dist/components/assets-dialog.d.ts +24 -0
  29. package/dist/components/canvas-context-menu.d.ts +6 -0
  30. package/dist/components/color-picker/index.d.ts +11 -0
  31. package/dist/components/context.d.ts +24 -0
  32. package/dist/components/design.d.ts +9 -0
  33. package/dist/components/fonts.d.ts +26 -0
  34. package/dist/components/image-crop.d.ts +5 -0
  35. package/dist/components/image-edit.d.ts +1 -0
  36. package/dist/components/layout/aside.d.ts +4 -0
  37. package/dist/components/layout/bottom-nav/element-menu-sheet.d.ts +11 -0
  38. package/dist/components/layout/bottom-nav/element-sheet.d.ts +11 -0
  39. package/dist/components/layout/bottom-nav/index.d.ts +1 -0
  40. package/dist/components/layout/header.d.ts +1 -0
  41. package/dist/components/loading.d.ts +3 -0
  42. package/dist/components/menus/ai.d.ts +5 -0
  43. package/dist/components/menus/background.d.ts +6 -0
  44. package/dist/components/menus/clipart.d.ts +6 -0
  45. package/dist/components/menus/files.d.ts +7 -0
  46. package/dist/components/menus/image.d.ts +8 -0
  47. package/dist/components/menus/index.d.ts +13 -0
  48. package/dist/components/menus/layer.d.ts +5 -0
  49. package/dist/components/menus/product.d.ts +3 -0
  50. package/dist/components/menus/sca.d.ts +5 -0
  51. package/dist/components/menus/shapes.d.ts +6 -0
  52. package/dist/components/menus/templates.d.ts +6 -0
  53. package/dist/components/menus/text-effects.d.ts +5 -0
  54. package/dist/components/menus/text.d.ts +6 -0
  55. package/dist/components/placement-tab.d.ts +7 -0
  56. package/dist/components/preview/3d.d.ts +8 -0
  57. package/dist/components/preview/graphic.d.ts +15 -0
  58. package/dist/components/preview/index.d.ts +20 -0
  59. package/dist/components/preview/open.d.ts +7 -0
  60. package/dist/components/preview/real-time/3d.d.ts +12 -0
  61. package/dist/components/preview/real-time/graphic.d.ts +31 -0
  62. package/dist/components/preview/real-time/index.d.ts +12 -0
  63. package/dist/components/scale-tools.d.ts +7 -0
  64. package/dist/components/semi-deisgn-config.d.ts +13 -0
  65. package/dist/components/semi-design-link.d.ts +9 -0
  66. package/dist/components/semi-interact-editor.d.ts +27 -0
  67. package/dist/components/semi-renderer.d.ts +74 -0
  68. package/dist/components/store.d.ts +1 -0
  69. package/dist/components/toolbar.d.ts +2 -0
  70. package/dist/config-D2qm60gf.js +16 -0
  71. package/dist/contracts/api-design.d.ts +180 -0
  72. package/dist/contracts/design.d.ts +86 -0
  73. package/dist/design-C_TmcalT.js +21449 -0
  74. package/dist/designer-store-Da9fICz8.js +153 -0
  75. package/dist/engine/canvas-designer.d.ts +101 -0
  76. package/dist/engine/canvas-designer.js +313 -0
  77. package/dist/engine/constants.d.ts +26 -0
  78. package/dist/engine/constants.js +147 -0
  79. package/dist/engine/editor.d.ts +199 -0
  80. package/dist/engine/editor.js +801 -0
  81. package/dist/engine/events.d.ts +35 -0
  82. package/dist/engine/events.js +7 -0
  83. package/dist/engine/extensions/curved-text.d.ts +59 -0
  84. package/dist/engine/fabric.d.ts +4 -0
  85. package/dist/engine/fabric.js +187 -0
  86. package/dist/engine/history.d.ts +27 -0
  87. package/dist/engine/history.js +56 -0
  88. package/dist/engine/managers/event.d.ts +101 -0
  89. package/dist/engine/managers/event.js +410 -0
  90. package/dist/engine/managers/resize.d.ts +26 -0
  91. package/dist/engine/managers/resize.js +64 -0
  92. package/dist/engine/managers/snapline.d.ts +70 -0
  93. package/dist/engine/managers/snapline.js +124 -0
  94. package/dist/engine/managers/workspace.d.ts +29 -0
  95. package/dist/engine/managers/workspace.js +75 -0
  96. package/dist/engine/processors/image.d.ts +88 -0
  97. package/dist/engine/processors/image.js +473 -0
  98. package/dist/engine/processors/template.d.ts +45 -0
  99. package/dist/engine/processors/template.js +314 -0
  100. package/dist/engine/processors/text.d.ts +74 -0
  101. package/dist/engine/processors/text.js +215 -0
  102. package/dist/engine/semi-export-editor.d.ts +215 -0
  103. package/dist/engine/types.d.ts +28 -0
  104. package/dist/engine/utils/common.d.ts +25 -0
  105. package/dist/engine/utils/common.js +68 -0
  106. package/dist/engine/utils/dialog.d.ts +25 -0
  107. package/dist/engine/utils/font.d.ts +5 -0
  108. package/dist/engine/utils/font.js +39 -0
  109. package/dist/engine/utils/image.d.ts +8 -0
  110. package/dist/engine/utils/image.js +50 -0
  111. package/dist/engine/utils/loading.d.ts +17 -0
  112. package/dist/engine/utils/loading.js +71 -0
  113. package/dist/engine/utils/measure.d.ts +6 -0
  114. package/dist/engine/utils/measure.js +6 -0
  115. package/dist/engine/utils/mockup.d.ts +59 -0
  116. package/dist/engine/utils/setting.d.ts +4 -0
  117. package/dist/engine/utils/setting.js +73 -0
  118. package/dist/fabric-types.d.ts +59 -0
  119. package/dist/full-designer.js +14 -0
  120. package/dist/hooks/pagination.d.ts +19 -0
  121. package/dist/hooks/use-adobe-express.d.ts +50 -0
  122. package/dist/hooks/use-before-unload.d.ts +1 -0
  123. package/dist/hooks/use-image-drop.d.ts +18 -0
  124. package/dist/hooks/use-oss-upload.d.ts +36 -0
  125. package/dist/hooks/use-preview-assets.d.ts +2 -0
  126. package/dist/hooks/use-screen.d.ts +1 -0
  127. package/dist/i18n/index.d.ts +12 -0
  128. package/dist/images/design/asset_empty.png +0 -0
  129. package/dist/images/design/design/background.svg +3 -0
  130. package/dist/images/design/design/color-picker.svg +15 -0
  131. package/dist/images/design/design/computer.svg +1 -0
  132. package/dist/images/design/design/copy.svg +1 -0
  133. package/dist/images/design/design/image.svg +10 -0
  134. package/dist/images/design/design/line.svg +1 -0
  135. package/dist/images/design/design/text.svg +1 -0
  136. package/dist/images/design/design/title.svg +1 -0
  137. package/dist/images/design/empty.png +0 -0
  138. package/dist/images/design/layer_empty.png +0 -0
  139. package/dist/images/design/menu/ai.svg +1 -0
  140. package/dist/images/design/menu/back.svg +4 -0
  141. package/dist/images/design/menu/background.svg +6 -0
  142. package/dist/images/design/menu/clipart.svg +6 -0
  143. package/dist/images/design/menu/file.svg +4 -0
  144. package/dist/images/design/menu/fill.svg +1 -0
  145. package/dist/images/design/menu/image.svg +7 -0
  146. package/dist/images/design/menu/layer.svg +6 -0
  147. package/dist/images/design/menu/product.svg +3 -0
  148. package/dist/images/design/menu/sca.svg +5 -0
  149. package/dist/images/design/menu/shapes.svg +5 -0
  150. package/dist/images/design/menu/templates.svg +6 -0
  151. package/dist/images/design/menu/text.svg +6 -0
  152. package/dist/images/design/menu/uploads.svg +7 -0
  153. package/dist/images/design/spinner.svg +3 -0
  154. package/dist/images/design/spinners.svg +17 -0
  155. package/dist/images/design/transparent_pattern.svg +5 -0
  156. package/dist/index.d.ts +51 -0
  157. package/dist/index.js +168 -0
  158. package/dist/lib/analytics.d.ts +17 -0
  159. package/dist/lib/cn.d.ts +3 -0
  160. package/dist/lib/common.d.ts +16 -0
  161. package/dist/lib/config.d.ts +14 -0
  162. package/dist/lib/navigation.d.ts +2 -0
  163. package/dist/pixel-map-dSys7UAx.js +137 -0
  164. package/dist/renderer/ThreeDPreview.d.ts +14 -0
  165. package/dist/renderer/latest-task-queue.d.ts +17 -0
  166. package/dist/renderer/pixel-map.d.ts +37 -0
  167. package/dist/renderer/preview-asset-cache.d.ts +4 -0
  168. package/dist/renderer/render-layer-output.d.ts +5 -0
  169. package/dist/renderer/semi-resource-cache.d.ts +28 -0
  170. package/dist/renderer/sticker.d.ts +34 -0
  171. package/dist/renderer/sticker.js +1837 -0
  172. package/dist/renderer/three-d-preview.js +32 -0
  173. package/dist/semi-interact-editor-DfzphWy3.js +1409 -0
  174. package/dist/semi-renderer.d.ts +7 -0
  175. package/dist/semi-renderer.js +5 -0
  176. package/dist/state/designer-store.d.ts +43 -0
  177. package/dist/state/designer-store.js +8 -0
  178. package/dist/style.css +1 -0
  179. package/dist/types.d.ts +305 -0
  180. package/dist/ui/accordion.d.ts +7 -0
  181. package/dist/ui/button-group.d.ts +11 -0
  182. package/dist/ui/button.d.ts +10 -0
  183. package/dist/ui/checkbox.d.ts +4 -0
  184. package/dist/ui/command.d.ts +18 -0
  185. package/dist/ui/confirm-dialog.d.ts +15 -0
  186. package/dist/ui/context-menu.d.ts +25 -0
  187. package/dist/ui/dialog.d.ts +15 -0
  188. package/dist/ui/drawer.d.ts +15 -0
  189. package/dist/ui/editable-combobox.d.ts +11 -0
  190. package/dist/ui/hint.d.ts +8 -0
  191. package/dist/ui/image.d.ts +24 -0
  192. package/dist/ui/input-group.d.ts +16 -0
  193. package/dist/ui/input-with-addon.d.ts +17 -0
  194. package/dist/ui/input.d.ts +3 -0
  195. package/dist/ui/label.d.ts +4 -0
  196. package/dist/ui/loading-button.d.ts +15 -0
  197. package/dist/ui/popover.d.ts +9 -0
  198. package/dist/ui/scroll-area.d.ts +5 -0
  199. package/dist/ui/select.d.ts +22 -0
  200. package/dist/ui/separator.d.ts +4 -0
  201. package/dist/ui/shared-loading-button.d.ts +20 -0
  202. package/dist/ui/simple-dialog.d.ts +19 -0
  203. package/dist/ui/simple-popover.d.ts +13 -0
  204. package/dist/ui/simple-select.d.ts +20 -0
  205. package/dist/ui/skeleton.d.ts +2 -0
  206. package/dist/ui/slider.d.ts +4 -0
  207. package/dist/ui/spinner-box.d.ts +12 -0
  208. package/dist/ui/spinner.d.ts +2 -0
  209. package/dist/ui/switch.d.ts +6 -0
  210. package/dist/ui/tab/index.d.ts +15 -0
  211. package/dist/ui/textarea.d.ts +3 -0
  212. package/dist/ui/tooltip.d.ts +7 -0
  213. package/dist/workers/image-resize.worker.d.ts +1 -0
  214. package/dist/workers/mockup.worker.d.ts +5 -0
  215. package/dist/workers/pixel-map.worker.d.ts +1 -0
  216. package/dist/workers/render-asset-cache.d.ts +18 -0
  217. package/dist/workers/render.worker.d.ts +1 -0
  218. package/docs/HOST_DATA_CONTRACT.md +426 -0
  219. package/docs/INTEGRATION_API.md +549 -0
  220. package/docs/SEMI_RENDERER.md +141 -0
  221. package/docs/auth-api.md +3 -0
  222. package/package.json +208 -4
@@ -0,0 +1,549 @@
1
+ # Printine Designer 第三方接入文档(React)
2
+
3
+ 适用对象:在自有 React 项目中接入商品在线设计器的前端和后端开发者。
4
+
5
+ 本文依据 `@printine/pod-editor` **0.1.13 的当前源码**编写,更新日期:2026-10-16。安装包导出的 TypeScript 类型是字段类型的最终依据。文中的 `example.com`、商品/底板 ID 和 `/api/designer/*` 均为示例,需替换为实际配置;`/api/designer/*` 不是 SDK 内置接口。
6
+
7
+ ## 目录
8
+
9
+ - [1. 接入方式与职责](#1-接入方式与职责)
10
+ - [2. 接入前准备](#2-接入前准备)
11
+ - [3. 快速接入](#3-快速接入)
12
+ - [4. 组件参数](#4-组件参数)
13
+ - [5. 图片上传与我的图片](#5-图片上传与我的图片)
14
+ - [6. 保存设计与恢复编辑](#6-保存设计与恢复编辑)
15
+ - [7. 我的设计模板](#7-我的设计模板)
16
+ - [8. 字体、图形、剪贴画与色板](#8-字体图形剪贴画与色板)
17
+ - [9. 预览与服务端渲染](#9-预览与服务端渲染)
18
+ - [10. 事件与错误处理](#10-事件与错误处理)
19
+ - [11. 语言与主题](#11-语言与主题)
20
+ - [12. 联调验收与常见问题](#12-联调验收与常见问题)
21
+
22
+ ## 1. 接入方式与职责
23
+
24
+ 通过 npm 包将 `<PrintineDesigner />` 挂载到浏览器中的 React 页面。设计器提供画布、文字/图片编辑、多设计面、撤销重做和 2D/3D 预览;接入方(下称“宿主”)通过 Props、`adapters` 和回调连接自己的业务系统。
25
+
26
+ | 能力 | 设计器负责 | 宿主负责 |
27
+ | --- | --- | --- |
28
+ | 初始化 | 按底板创建画布和预览 | 提供商品变体 ID、底板 ID;可预取底板 |
29
+ | 商品信息 | 展示标题、图片、价格等 | 通过 `productInfo` 提供展示信息;当前不自动请求商品详情 |
30
+ | 用户与权限 | 调用宿主适配器 | 登录、会话、访问权限与数据归属校验 |
31
+ | 图片上传 | 提供文件、用途及可选元信息 | 上传、缩略图、用户素材登记、返回完整 URL |
32
+ | 我的图片/设计 | 展示、选择与触发操作 | 列表、详情、保存及删除 |
33
+ | 字体/图形/剪贴画 | 默认读取商家素材代理,也支持适配器 | 建立代理或提供标准化数据 |
34
+ | 保存最终设计 | 整理全部设计面的 JSON,调用 `onSave` | 持久化、业务校验、错误提示、埋点及跳转 |
35
+
36
+ 本文介绍 npm/React 接入。当前未提供第三方 iframe 或 `postMessage` 接入协议。公共模板分类目录暂未启用;模板复用通过 `adapters.templates` 提供。
37
+
38
+ ## 2. 接入前准备
39
+
40
+ ### 2.1 环境与资源
41
+
42
+ - 使用 React 和 React DOM 18 或 19,项目支持 ESM 和 CSS 导入。
43
+ - 在浏览器中加载组件;设计器依赖 DOM、Canvas、Worker 等能力,3D 预览还需相应的图形能力。
44
+ - 准备匹配的 `productId`(商品变体 ID)和 `basePlateId`(底板 ID)。即使传入了 `basePlate`,这两个参数也必填。
45
+ - 底板至少有一个设计面,并提供可访问的 SVG 设计面文件及所需 2D/3D 资源。
46
+ - 图片、SVG、字体、模型和纹理 URL 应持续可访问。跨域资源须允许宿主页面读取;仅能在 `<img>` 中显示,不能保证画布可以导出。
47
+
48
+ ### 2.2 默认请求与鉴权
49
+
50
+ | 用途 | 默认请求 | 说明 |
51
+ | --- | --- | --- |
52
+ | 底板 | `GET https://shop-api.printine.com/api/client/base-plates/:basePlateId` | 有效 `basePlate` 可跳过请求 |
53
+ | 游客 token | `GET /api/client/get-guest-token`,位于 `apiBaseUrl` 的 origin | Printine API 返回业务码 `445` 时获取 token,以 `X-Guest-Token` 重试原请求一次 |
54
+ | 字体 | `GET /api/v1/editor/fonts` | 默认当前宿主页 origin,或通过 `library.fonts.list` 提供 |
55
+ | 图形 | `GET /api/v1/editor/shapes?page=1&limit=30` | 默认当前宿主页 origin,按需分页,或通过 `library.shapes.list` 提供 |
56
+ | 剪贴画 | `GET /api/v1/editor/clipart-categories` | 默认当前宿主页 origin,或通过 `library.clipart.listCategories` 提供 |
57
+ | 上传、用户素材、用户模板、最终保存 | 宿主自定义 | 通过适配器/回调实现,无固定宿主路由 |
58
+
59
+ `apiBaseUrl`、`assetBaseUrl` 只传 origin,例如 `https://shop.example.com`,SDK 添加 API 前缀。`assetBaseUrl` 是素材服务地址,不是图片 CDN 前缀。
60
+
61
+ SDK 没有顶层 `token`、`appKey` 或自定义请求头 Props。用户业务接口的鉴权由宿主请求实现。使用 Printine 素材网关时,带 `assets:read` 权限的 App Key 保留在宿主后端,由后端代理请求,不放入前端代码。
62
+
63
+ 素材列表请求固定使用 `credentials: 'same-origin'`,不走 `445` 重试。推荐同源代理;指定跨 origin 的 `assetBaseUrl` 不会自动携带该 origin 的 Cookie。需要其他鉴权方式时实现 `adapters.library`。代理应校验编辑访问权限,将网关文件地址映射为浏览器可访问的商家文件 URL,并保留文件后缀及版本参数 `v`。
64
+
65
+ 默认底板与素材响应格式见 [宿主数据接口契约](./HOST_DATA_CONTRACT.md)。
66
+
67
+ ## 3. 快速接入
68
+
69
+ ### 3.1 安装与最小挂载
70
+
71
+ ```bash
72
+ npm install @printine/pod-editor
73
+ ```
74
+
75
+ 请锁定经过联调的版本。本文记录的源码版本为 0.1.13,不代表 npm 当前最新版本。
76
+
77
+ ```tsx
78
+ import { PrintineDesigner } from '@printine/pod-editor';
79
+ import '@printine/pod-editor/styles.css';
80
+
81
+ export function DesignerPage() {
82
+ return (
83
+ <PrintineDesigner
84
+ productId="your-variant-id"
85
+ basePlateId="your-base-plate-id"
86
+ locale="en-US"
87
+ productInfo={{ title: 'Classic T-shirt', price: 19.9, currency: 'USD' }}
88
+ onClose={() => window.history.back()}
89
+ />
90
+ );
91
+ }
92
+ ```
93
+
94
+ 该示例使用默认底板服务与同源素材代理。通常还需实现下节的上传和保存能力。设计器按整页布局实现,含固定定位工具栏和全屏预览,建议放在独立路由中。当前存在共享状态和模块级 API 配置,同页同时挂载多个完整设计器不适合作为接入方案。
95
+
96
+ ### 3.2 带上传与保存的完整示例
97
+
98
+ 以下示例使用宿主自定义的 `{ success, data, message? }` 响应格式:
99
+
100
+ | 示例宿主接口 | 请求 | 成功时的 `data` |
101
+ | --- | --- | --- |
102
+ | `POST /api/designer/uploads` | FormData:`file`、`purpose`、可选 JSON 字符串 `metadata` | `DesignerImageUploadResult` |
103
+ | `POST /api/designer/designs` | JSON:保存数据,不含 `previewBlob` | `{ id: string }` |
104
+
105
+ 上传接口在 `purpose === 'asset'` 时须完成素材登记。这两个路由及响应包装仅用于演示,可以改为宿主现有接口。示例只保存设计 JSON,预览图保存见第 6 节。
106
+
107
+ ```tsx
108
+ import { useCallback, useMemo, useState } from 'react';
109
+ import {
110
+ PrintineDesigner,
111
+ type DesignerAdapters,
112
+ type DesignerError,
113
+ type DesignerImageUploadResult,
114
+ type DesignerSaveInput,
115
+ } from '@printine/pod-editor';
116
+ import '@printine/pod-editor/styles.css';
117
+
118
+ type HostResponse<T> = { success: boolean; data: T; message?: string };
119
+
120
+ async function requestHost<T>(url: string, init?: RequestInit): Promise<T> {
121
+ const response = await fetch(url, { ...init, credentials: 'same-origin' });
122
+ const body = (await response.json()) as HostResponse<T>;
123
+ if (!response.ok || body.success !== true) {
124
+ throw new Error(body.message || `请求失败(${response.status})`);
125
+ }
126
+ return body.data;
127
+ }
128
+
129
+ export function ProductDesignerPage() {
130
+ const [errorMessage, setErrorMessage] = useState('');
131
+ const [savedId, setSavedId] = useState('');
132
+ const showError = useCallback((error: unknown) => {
133
+ setErrorMessage(error instanceof Error ? error.message : '操作失败,请重试');
134
+ }, []);
135
+
136
+ const adapters = useMemo<DesignerAdapters>(() => ({
137
+ uploadImage: async ({ file, purpose, metadata }) => {
138
+ setErrorMessage('');
139
+ try {
140
+ const form = new FormData();
141
+ form.append('file', file);
142
+ form.append('purpose', purpose);
143
+ if (metadata) form.append('metadata', JSON.stringify(metadata));
144
+ const result = await requestHost<DesignerImageUploadResult>(
145
+ '/api/designer/uploads', { method: 'POST', body: form },
146
+ );
147
+ if (!result.url) throw new Error('上传接口未返回图片 URL');
148
+ return result;
149
+ } catch (error) {
150
+ showError(error);
151
+ throw error;
152
+ }
153
+ },
154
+ }), [showError]);
155
+
156
+ const handleSave = useCallback(async (input: DesignerSaveInput) => {
157
+ setErrorMessage('');
158
+ try {
159
+ // Blob 应单独上传,不要直接 JSON.stringify(input)。
160
+ const { previewBlob, ...designPayload } = input;
161
+ const saved = await requestHost<{ id: string }>('/api/designer/designs', {
162
+ method: 'POST',
163
+ headers: { 'Content-Type': 'application/json' },
164
+ body: JSON.stringify(designPayload),
165
+ });
166
+ setSavedId(saved.id);
167
+ // 需要跳转或关闭设计页时,在这里调用宿主路由。
168
+ } catch (error) {
169
+ showError(error);
170
+ throw error;
171
+ }
172
+ }, [showError]);
173
+
174
+ const handleError = useCallback((error: DesignerError) => {
175
+ console.error('[Printine Designer]', error.code, error.cause);
176
+ showError(error);
177
+ }, [showError]);
178
+
179
+ return (
180
+ <>
181
+ <PrintineDesigner
182
+ productId="your-variant-id"
183
+ basePlateId="your-base-plate-id"
184
+ locale="en-US"
185
+ productInfo={{ title: 'Classic T-shirt', price: 19.9, currency: 'USD' }}
186
+ adapters={adapters}
187
+ onSave={handleSave}
188
+ onClose={() => window.history.back()}
189
+ onError={handleError}
190
+ />
191
+ <div
192
+ aria-live="polite"
193
+ style={{ position: 'fixed', bottom: 16, left: 16, zIndex: 10000 }}
194
+ >
195
+ {errorMessage && <p role="alert">{errorMessage}</p>}
196
+ {savedId && <p>设计已保存:{savedId}</p>}
197
+ </div>
198
+ </>
199
+ );
200
+ }
201
+ ```
202
+
203
+ 保持回调和适配器引用稳定,尤其是 `onError`、`onEvent` 和字体/色板 loader;这些引用变化可能重新触发初始化 effect。
204
+
205
+ ### 3.3 使用 SSR 框架
206
+
207
+ 应作为浏览器组件加载。Next.js App Router 中可在 Client Component 内动态导入并关闭 SSR:
208
+
209
+ ```tsx
210
+ 'use client';
211
+
212
+ import dynamic from 'next/dynamic';
213
+ import '@printine/pod-editor/styles.css';
214
+
215
+ const BrowserDesigner = dynamic(
216
+ () => import('@printine/pod-editor').then((module) => module.PrintineDesigner),
217
+ { ssr: false },
218
+ );
219
+
220
+ export default function DesignerRoute() {
221
+ return <BrowserDesigner productId="your-variant-id" basePlateId="your-base-plate-id" />;
222
+ }
223
+ ```
224
+
225
+ ## 4. 组件参数
226
+
227
+ 完整类型可通过 `import type { PrintineDesignerProps } from '@printine/pod-editor'` 获取。
228
+
229
+ | 参数 | 类型 | 必填/默认 | 说明 |
230
+ | --- | --- | --- | --- |
231
+ | `productId` | `string` | 必填 | 商品变体 ID,保存时为 `variant_id` |
232
+ | `basePlateId` | `string \| number` | 必填 | 底板 ID,与传入底板的 `id` 保持一致 |
233
+ | `apiBaseUrl` | `string` | `https://shop-api.printine.com` | Printine API origin,SDK 添加 `/api/client/` |
234
+ | `assetBaseUrl` | `string` | `/`,当前页面 origin | 商家素材代理 origin,SDK 添加 `/api/v1/editor/` |
235
+ | `basePlate` | `BasePlate \| null` | 可选 | 预取底板,避免 SDK 再次请求 |
236
+ | `productInfo` | `DesignerProductInfo` | 可选 | 商品展示信息,不决定画布结构或保存数据 |
237
+ | `initialDesignData` | `Record<string, Record<string, unknown>>` | 可选 | 恢复的 Fabric JSON,按设计面 `name` 分组 |
238
+ | `initialBackgroundCustomized` | `SemiCustomBackground` | 可选 | 恢复半定制背景配置,与设计 JSON 分开传递 |
239
+ | `loading` | `boolean` | `false` | 为 `true` 时暂不初始化默认编辑器,显示加载界面 |
240
+ | `semiDesignPermission` | `boolean` | `false` | 显示半定制配置入口,业务授权由宿主校验 |
241
+ | `adapters` | `DesignerAdapters` | 可选 | 上传、用户图片、模板、素材库能力,见下文 |
242
+ | `onSave` | `(input: DesignerSaveInput) => void \| Promise<void>` | 可选 | 最终保存;未提供时预览页隐藏 Done |
243
+ | `onRenderPreview` | `(input: DesignerRenderPreviewInput) => Promise<string[]>` | 可选 | 全屏 2D 预览服务端渲染 |
244
+ | `onClose` | `() => void` | 可选 | 关闭/返回,缺省回退到浏览器后退 |
245
+ | `onError` | `(error: DesignerError) => void` | 可选 | 包内错误;不代替宿主适配器错误提示 |
246
+ | `onEvent` | `(event: DesignerEvent) => void` | 可选 | 生命周期事件 |
247
+ | `onAnalytics` | `(event: 'preview_design', payload: Record<string, unknown>) => void` | 可选 | 预览埋点,保存埋点由宿主处理 |
248
+ | `locale` | `string` | 英文 | 内置英文/西班牙文;用于 Printine API 的 `Accept-Language` |
249
+ | `messages` | `Record<string, Record<string, string>>` | 可选 | 按命名空间和原文案覆盖文本 |
250
+ | `threeDEnvironmentUrl` | `string` | 可选 | 全屏 3D 预览的 Babylon 环境贴图 URL |
251
+ | `imageBaseUrl` | `string` | 可选 | 兼容存量图片对象 key 的域名前缀;上传适配器应返回完整 URL |
252
+ | `className` | `string` | 可选 | 外层附加 class |
253
+ | `children` | `ReactNode` | 可选 | 替换默认编辑器内容,常规接入无需传入 |
254
+
255
+ `productInfo` 支持 `title`、`imageUrl`、`price`、`currency`、`variantTitle`。字符串字段可为 `null`;价格可为数字、字符串或 `null`,数字 `0` 可正常显示。数字价格可结合 ISO 4217 币种(如 `USD`)格式化;信息全为空时隐藏商品信息区。
256
+
257
+ ## 5. 图片上传与我的图片
258
+
259
+ ### 5.1 `adapters.uploadImage`
260
+
261
+ 输入:`{ file: File; purpose: DesignerImageUploadPurpose; metadata?: DesignerImageMetadata }`。
262
+
263
+ | `purpose` | 触发场景 | 宿主动作 |
264
+ | --- | --- | --- |
265
+ | `asset` | 用户上传设计素材 | 上传、可选缩略图处理、创建宿主素材记录后 resolve |
266
+ | `design-data` | 持久化设计中的临时图片等 | 返回图片 URL,无需自动登记到“我的图片” |
267
+ | `template-preview` | 保存“我的设计”的预览图 | 上传预览文件,返回 URL |
268
+
269
+ `metadata` 仅在普通用户素材上传(`asset`)时提供,含 `name`、`size`(字节)、`width`、`height`、`mimeType`。其他用途不能要求必须携带它。
270
+
271
+ 成功返回 `Promise<DesignerImageUploadResult>`:
272
+
273
+ ```ts
274
+ type UploadResult = {
275
+ id?: string;
276
+ url: string;
277
+ thumbnailUrl?: string;
278
+ canvasThumbnailUrl?: string;
279
+ thumbnailScale?: number;
280
+ };
281
+ ```
282
+
283
+ 所有 URL 必须完整且可由浏览器加载。`url` 是原图;`thumbnailUrl` 用于列表;`canvasThumbnailUrl` 用于画布,未传时兼容使用 `thumbnailUrl`。缩略图保持原图比例,`thumbnailScale` 为画布实际使用图像尺寸 ÷ 原图尺寸,例如原图宽 2000、画布图宽 1000,则为 `0.5`。不制作缩略图时只返回 `url` 即可。
284
+
285
+ 同时返回素材 `id` 可让设计器直接将新素材加入当前列表。SDK 不会调用宿主素材登记接口。普通上传入口有 20 MB 大小限制,各入口接受的类型以文件选择器为准;宿主后端仍执行自身的类型、大小与权限校验。
286
+
287
+ 失败时宿主先提示,再抛异常/reject;SDK 恢复自身 Loading,不重复提示。
288
+
289
+ ### 5.2 `adapters.assets`
290
+
291
+ ```ts
292
+ import type { DesignerAssetsAdapter } from '@printine/pod-editor';
293
+
294
+ // 标准化数据示例;实际接入时替换为宿主接口调用并处理失败。
295
+ const assets: DesignerAssetsAdapter = {
296
+ list: async ({ page, pageSize }) => ({
297
+ items: [{
298
+ id: 'asset-1',
299
+ name: 'logo.png',
300
+ url: 'https://cdn.example.com/original/logo.png',
301
+ thumbnailUrl: 'https://cdn.example.com/thumb/logo.png',
302
+ canvasThumbnailUrl: 'https://cdn.example.com/canvas/logo.png',
303
+ thumbnailScale: 0.5,
304
+ width: 2000,
305
+ height: 1000,
306
+ }],
307
+ page, pageSize, total: 1,
308
+ }),
309
+ };
310
+ ```
311
+
312
+ `list({ page, pageSize })` 返回 `Promise<DesignerPage<DesignerAsset>>`;页码从 1 开始,`total` 为全部记录数,`width/height` 为原图尺寸。`remove({ id })` 可选,成功返回 `Promise<void>`,不传则隐藏删除按钮。将该对象合入 `adapters.assets` 后生效。
313
+
314
+ 未提供 `assets.list` 时隐藏“我的图片”列表,不影响已配置的上传能力。宿主处理列表、删除的请求与业务错误。
315
+
316
+ ## 6. 保存设计与恢复编辑
317
+
318
+ ### 6.1 最终保存
319
+
320
+ 用户从编辑器进入预览,点击 Done 后,SDK 整理设计数据并调用 `onSave`:
321
+
322
+ ```ts
323
+ interface SaveInput {
324
+ variant_id: string;
325
+ design_data: Record<string, unknown>;
326
+ previewBlob?: Blob;
327
+ background_customized?: unknown;
328
+ is_partially_customized?: 1;
329
+ }
330
+ ```
331
+
332
+ | 字段 | 说明 |
333
+ | --- | --- |
334
+ | `variant_id` | 对应 `productId` |
335
+ | `design_data` | 各设计面 Fabric JSON,通常按 `areas[].name` 分组,含对象、颜色及可能的 `workspaceMetadata` 等 |
336
+ | `previewBlob` | 可选商品预览,当前尝试取第一个 2D 预览;不能保证每种状态都有,3D 保存不能依赖它 |
337
+ | `background_customized` | 半定制背景开启时携带 |
338
+ | `is_partially_customized` | 含元素/背景半定制配置时为 `1` |
339
+
340
+ SDK 在调用前处理需持久化的临时图片、过滤空文本并合并半定制配置。请原样保存 JSON 字段,尤其是 `src`、`originSrc`、字体、自定义配置、变换参数和 `workspaceMetadata`。
341
+
342
+ `previewBlob` 不能作为普通 JSON 传输,应先取出单独上传,或按宿主协议将其与设计 JSON 放入 FormData。不存在时可仅保存设计数据,或由宿主渲染服务生成预览;预览上传的失败处理与保存事务由宿主决定。
343
+
344
+ `onSave` 不要求返回保存记录。需要跳转时由宿主消费后端响应并操作路由。持久化成功后才 resolve;HTTP/业务失败必须 reject,不能提示失败后正常返回,否则 SDK 会发出 `save-complete`。SDK 不会自动提交购物车、创建订单或跳转。
345
+
346
+ `base_plate_id` 不在保存输入中。宿主保存接口如需要底板 ID、记录 ID 等字段,可从页面状态补充。
347
+
348
+ ### 6.2 恢复编辑
349
+
350
+ 从宿主记录读取设计,传回 `initialDesignData`,不要把整个保存输入传给该属性:
351
+
352
+ ```tsx
353
+ import { PrintineDesigner, type SemiCustomBackground } from '@printine/pod-editor';
354
+
355
+ type SavedDesign = {
356
+ id: string;
357
+ variantId: string;
358
+ basePlateId: string | number;
359
+ designData: Record<string, Record<string, unknown>>;
360
+ backgroundCustomized?: SemiCustomBackground;
361
+ };
362
+
363
+ export function RestoreDesigner({ record }: { record: SavedDesign }) {
364
+ return (
365
+ <PrintineDesigner
366
+ key={`${record.id}:${record.variantId}:${record.basePlateId}`}
367
+ productId={record.variantId}
368
+ basePlateId={record.basePlateId}
369
+ initialDesignData={record.designData}
370
+ initialBackgroundCustomized={record.backgroundCustomized}
371
+ />
372
+ );
373
+ }
374
+ ```
375
+
376
+ 示例仅展示恢复参数,实际需合入上传与保存等能力。设计面键推荐使用 `areas[].name`,兼容旧数据以 `areas[].id` 字符串为键。切换商品、底板或不同保存记录时建议修改组件 `key`,避免复用初始化状态。异步加载记录时先传 `loading={true}`,准备好再初始化;初始数据入口不是受控画布状态。
377
+
378
+ `initialBackgroundCustomized` 的结构为 `{ enable: boolean; palette: boolean; colors: string[] }`。当前有历史 `sessionStorage.designData` 恢复逻辑,但它不是第三方草稿协议;离开/刷新不能代替宿主持久化,需要恢复的记录应由宿主明确保存和加载。
379
+
380
+ ## 7. 我的设计模板
381
+
382
+ “保存为设计”保存可复用模板,与最终商品设计的 `onSave` 分开。保存模板需要同时提供 `adapters.templates` 和 `adapters.uploadImage`。
383
+
384
+ | 方法 | 参数 | 成功返回 |
385
+ | --- | --- | --- |
386
+ | `create` | `{ name: string; preview: string; content: TemplateData }` | `Promise<void>` |
387
+ | `list` | 无 | `Promise<DesignerUserTemplate[]>` |
388
+ | `get` | `{ id: string }` | `Promise<{ content: TemplateBaseInfo }>` |
389
+ | `remove` | `{ id: string }` | `Promise<void>`,可选,省略隐藏删除按钮 |
390
+
391
+ 列表项 `DesignerUserTemplate` 为 `{ id: string; name: string; preview: string; content?: TemplateBaseInfo }`,`preview` 是完整图片 URL。列表可省略 `content`,用户选择时再调用 `get`;即使列表含内容,适配器类型仍要求实现 `get`。
392
+
393
+ 模板主要结构为 `{ areaWidth, areaHeight, elements }`,`TemplateData` 另含 `urlPreview` 等字段。原样保存 `create` 收到的内容,并在 `get` 中返回。模板结构与多设计面的 Fabric `design_data` 不同,不能混用。相关类型均可从包主入口导入。
394
+
395
+ 保存顺序:生成模板预览 → `uploadImage({ purpose: 'template-preview', file })` → `templates.create({ name, preview: uploaded.url, content })` → 刷新模板列表。所有请求鉴权与失败提示由宿主处理。未提供 `templates` 时隐藏“我的设计”和“保存为设计”;当前也不请求公共模板目录。
396
+
397
+ ## 8. 字体、图形、剪贴画与色板
398
+
399
+ 可使用同源素材代理,也可按类别实现 `adapters.library`。某类别未提供适配器时,仅该类别使用默认代理。适配器直接返回标准化成功数据,无需再包 `{ data }` 或 `{ success }`。
400
+
401
+ ```ts
402
+ import type { DesignerLibraryAdapters } from '@printine/pod-editor';
403
+
404
+ // 静态数据演示,也可改为调用宿主接口。
405
+ const library: DesignerLibraryAdapters = {
406
+ colors: { list: async () => ['#FFFFFF', '#111827', '#E11D48'] },
407
+ fonts: {
408
+ list: async () => [{
409
+ family: 'Acme Sans',
410
+ variants: ['400', '700italic'],
411
+ files: [
412
+ { weight: 400, style: 'normal', variant: '400', url: 'https://cdn.example.com/acme-400.woff2' },
413
+ { weight: 700, style: 'italic', variant: '700italic', url: 'https://cdn.example.com/acme-700-italic.woff2' },
414
+ ],
415
+ }],
416
+ },
417
+ shapes: {
418
+ list: async ({ page, pageSize }) => ({
419
+ items: [{ id: 'circle', name: 'Circle', url: 'https://cdn.example.com/circle.svg' }],
420
+ page, pageSize, total: 1,
421
+ }),
422
+ },
423
+ clipart: {
424
+ listCategories: async () => [{
425
+ id: 'animals', name: 'Animals',
426
+ cliparts: [{ id: 'cat', name: 'Cat', url: 'https://cdn.example.com/cat.svg' }],
427
+ }],
428
+ },
429
+ };
430
+ ```
431
+
432
+ 合入 `adapters.library` 后生效。默认代理的字体字段是 `name/variants`,图形/剪贴画 URL 字段是 `asset_url`;适配器使用上例的 `family/files`、`url`,两套结构不要混用。代理格式见 [宿主数据接口契约](./HOST_DATA_CONTRACT.md#5-商家素材代理和宿主色板)。
433
+
434
+ 预设色板只由 `colors.list(): Promise<string[]>` 提供,未配置时预设为空,不请求设置接口,普通自选颜色仍可用。已保存文字依赖原字体可访问,更换字体服务时应保留历史设计引用的字体。
435
+
436
+ ## 9. 预览与服务端渲染
437
+
438
+ 底板 `renders` 提供实时 2D 预览,`td_renders` 提供 3D 预览,两者都有时优先 3D。设计面、2D 图层与 3D 材质的关联见 [底板详情](./HOST_DATA_CONTRACT.md#3-底板详情)。
439
+
440
+ `onRenderPreview` 用于全屏 2D 预览需要服务端渲染的路径,不用于右侧实时 2D 或 3D 预览。已有可用实时图时无需调用;SDK 不直接请求旧固定渲染接口。
441
+
442
+ 输入类型是 `Record<string, unknown>`,当前内容示例:
443
+
444
+ ```json
445
+ {
446
+ "base_plate_id": "your-base-plate-id",
447
+ "mask": { "color": "", "opacity": 0 },
448
+ "design_data": { "front": { "objects": [], "color": "#FFFFFF" } }
449
+ }
450
+ ```
451
+
452
+ `base_plate_id` 保留底板 ID 类型(字符串或数字)。`mask` 是默认背景遮罩;当前商品展示属性不设置默认背景色,各设计面的颜色在 `design_data` 中。此路径会先处理需上传的临时图片。
453
+
454
+ 宿主调用渲染服务后直接返回 `Promise<string[]>`,如 `['https://cdn.example.com/front.png']`,不能直接返回后端包装对象。数组顺序为展示顺序,各 URL 必须可由浏览器加载。缺少可用实时图且未提供回调时,上报 `DESIGN_RENDER_UNAVAILABLE`。
455
+
456
+ 只需独立渲染已保存设计时,另见 [半定制本地效果图渲染](./SEMI_RENDERER.md)。
457
+
458
+ ## 10. 事件与错误处理
459
+
460
+ ### 10.1 生命周期
461
+
462
+ `onEvent` 接收 `{ name, productId }`:
463
+
464
+ | `name` | 含义 |
465
+ | --- | --- |
466
+ | `ready` | 外层组件已挂载,不代表画布和资源全部就绪 |
467
+ | `load-start` | 开始初始化 |
468
+ | `load-complete` | 引擎/底板加载并启动配置加载,字体、图片和预览仍可能异步准备中 |
469
+ | `save-start` | 保存数据整理到相应阶段,准备继续处理预览并调用宿主保存 |
470
+ | `save-complete` | 宿主 `onSave` 正常返回/resolve |
471
+
472
+ 事件用于日志或埋点,不代替宿主后端的持久化结果。Strict Mode 的开发环境可能重复挂载生命周期,宿主埋点自行去重。`onAnalytics` 当前输出 `preview_design`,第二个参数是业务上下文。
473
+
474
+ ### 10.2 错误职责
475
+
476
+ `onError` 输入为 `{ code: string; message: string; cause?: unknown }`。
477
+
478
+ | 当前主要错误码 | 排查方向 |
479
+ | --- | --- |
480
+ | `DESIGNER_BOOTSTRAP_FAILED` | 底板获取、引擎或数据加载 |
481
+ | `DESIGN_CANVAS_INIT_FAILED` | 设计面 SVG、画布初始化 |
482
+ | `DESIGN_PREVIEW_LAYER_FAILED` | 预览图层生成 |
483
+ | `DESIGN_PREVIEW_PREPARE_FAILED` | 全屏预览数据准备 |
484
+ | `DESIGN_RENDER_UNAVAILABLE` | 当前 2D 路径缺少宿主渲染回调 |
485
+ | `DESIGN_RENDER_FAILED` | 宿主预览回调抛错等渲染失败 |
486
+ | `DESIGN_SAVE_FAILED` | 包内保存数据处理或预览处理失败 |
487
+
488
+ 错误码类型为 `string`,应保留未知码的通用处理。上传、我的图片、我的设计及最终保存的宿主请求失败,由宿主提示并 reject,不统一转交 `onError`。服务端预览渲染失败会转交 `onError`,应避免重复提示。
489
+
490
+ ## 11. 语言与主题
491
+
492
+ 内置 `en`/`en-US`、`es`/`es-ES`,其他语言回退英文。`locale="zh-CN"` 不会自动生成中文翻译,可通过 `messages` 传入覆盖表,例如 `{ design: { Next: '下一步', Preview: '预览', Done: '完成' } }`;未覆盖文案使用回退文本。
493
+
494
+ 主题 CSS 在 `@printine/pod-editor/styles.css` 之后加载:
495
+
496
+ ```css
497
+ :root {
498
+ --printine-primary: #3540a5;
499
+ --printine-primary-foreground: #ffffff;
500
+ --printine-background: #f3f5f6;
501
+ --printine-foreground: #1c1c1e;
502
+ --printine-border: #e0e0e5;
503
+ --printine-radius: 0.625rem;
504
+ }
505
+ ```
506
+
507
+ 包自带图标、空状态和样式,无需宿主配置 Tailwind 内容扫描。Dialog、Select、Popover 等浮层使用 Portal,主题变量建议覆盖在全局 `:root`。更多变量分组:
508
+
509
+ | 分组 | 变量 |
510
+ | --- | --- |
511
+ | 表面 | `--printine-card`、`--printine-card-foreground`、`--printine-popover`、`--printine-popover-foreground`、`--printine-input`、`--printine-ring` |
512
+ | 辅助 | `--printine-secondary`、`--printine-secondary-foreground`、`--printine-muted`、`--printine-muted-foreground`、`--printine-accent`、`--printine-accent-foreground` |
513
+ | 状态 | `--printine-destructive`、`--printine-yellow`、`--printine-success`、`--printine-error` |
514
+ | 骨架屏 | `--printine-skeleton-bg`、`--printine-skeleton-highlight` |
515
+
516
+ Tooltip 使用固定深色样式。可使用 `--printine-designer-font` 设置界面字体。
517
+
518
+ ## 12. 联调验收与常见问题
519
+
520
+ ### 12.1 验收步骤
521
+
522
+ 1. 使用真实 ID 打开设计路由,确认底板、全部设计面和商品展示信息正确。
523
+ 2. 添加图片、文字、图形、剪贴画,检查设计面切换及撤销重做。
524
+ 3. 上传后确认素材已登记、列表可重载、缩略图插入尺寸正确。
525
+ 4. 打开 2D/3D 预览,检查设计面映射、颜色及纹理;需要宿主渲染的路径能返回图片。
526
+ 5. 点击 Done,确认宿主持久化成功;有 Blob 时可单独上传,无 Blob 时按业务策略保存。
527
+ 6. 从保存记录重新进入,确认图片、字体、位置、背景及半定制配置恢复。
528
+ 7. 验证上传、列表、模板、保存失败会显示宿主错误并恢复 Loading,保存失败不执行成功跳转。
529
+ 8. 按启用能力验证删除权限、模板复用、移动端操作和离开页面行为。
530
+
531
+ ### 12.2 常见问题
532
+
533
+ | 现象 | 检查项 |
534
+ | --- | --- |
535
+ | 页面空白/初始化失败 | 浏览器加载方式、两个 ID、底板响应、`areas` 非空、SVG 可读、`onError` |
536
+ | 商品名称/价格不显示 | 当前不自动请求商品详情,需传 `productInfo` |
537
+ | 字体/图形/剪贴画 404 | 同源 `/api/v1/editor/*` 代理是否存在,或提供对应 `library` 方法 |
538
+ | 素材代理跨域后 401 | 默认不发送跨 origin Cookie;使用同源代理或自定义适配器 |
539
+ | 图片可见但预览/导出失败 | 文件 CORS、权限与有效期,Canvas 导出需要读取权限 |
540
+ | 上传按钮/Done 不显示 | 分别检查 `adapters.uploadImage` 与 `onSave` |
541
+ | 我的图片为空 | `assets.list`、素材登记、标准化分页返回值 |
542
+ | 缩略图尺寸不对 | 原图 `width/height`、画布实际缩略图对应的 `thumbnailScale` |
543
+ | 保存后无预览图 | `previewBlob` 可选,需宿主缺省策略或自行渲染 |
544
+ | 保存失败无 SDK 提示 | 宿主回调自行提示并 reject,SDK 不重复提示 |
545
+ | 重新进入设计丢失 | 宿主保存/加载、`initialDesignData`、设计面键匹配 |
546
+ | 新设计参数未生效 | 初始数据不是受控状态;加载好后挂载或切换 `key` |
547
+ | 初始化反复执行 | 检查回调与 loader 的引用是否稳定 |
548
+
549
+ 联调反馈建议附包版本、浏览器版本、商品/底板 ID、步骤、`onError.code`、失败请求状态与脱敏响应。不要附用户 token 或后端 App Key。