@printine/pod-editor 0.1.14 → 0.1.16
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.
- package/README.md +27 -45
- package/dist/api/asset-client.d.ts +1 -1
- package/dist/components/context.d.ts +2 -2
- package/dist/components/design.d.ts +2 -2
- package/dist/components/preview/index.d.ts +2 -2
- package/dist/components/semi-renderer.d.ts +3 -1
- package/dist/components/upload-types.d.ts +20 -0
- package/dist/{design-C_TmcalT.js → design-CpQzcaGG.js} +5589 -5595
- package/dist/full-designer.js +2 -3
- package/dist/index.d.ts +1 -3
- package/dist/index.js +134 -146
- package/dist/lib/base-plate.d.ts +3 -0
- package/dist/{pixel-map-dSys7UAx.js → pixel-map-BLlgu5Ix.js} +3 -3
- package/dist/renderer/pixel-map.d.ts +3 -0
- package/dist/renderer/render-layer-output.d.ts +1 -0
- package/dist/{semi-interact-editor-DfzphWy3.js → semi-interact-editor-BVPJX2-9.js} +358 -350
- package/dist/semi-renderer.js +1 -1
- package/dist/style.css +1 -1
- package/dist/types.d.ts +3 -29
- package/docs/HOST_DATA_CONTRACT.md +77 -69
- package/docs/INTEGRATION_API.md +25 -27
- package/docs/SEMI_RENDERER.md +7 -2
- package/package.json +2 -11
- package/dist/api/client.d.ts +0 -8
- package/dist/api/client.js +0 -82
- package/dist/api/common-endpoints.d.ts +0 -12
- package/dist/api/design-endpoints.d.ts +0 -4
- package/dist/api/endpoints.d.ts +0 -23
- package/dist/api/endpoints.js +0 -33
- package/dist/api/files-endpoints.d.ts +0 -1
- package/dist/components/menus/ai.d.ts +0 -5
- package/dist/hooks/use-oss-upload.d.ts +0 -36
|
@@ -1,37 +1,28 @@
|
|
|
1
1
|
# 宿主数据接口契约
|
|
2
2
|
|
|
3
|
-
本文档描述 `@printine/pod-editor` 0.1.
|
|
3
|
+
本文档描述 `@printine/pod-editor` 0.1.14 当前完整编辑器使用的宿主商品展示、设计恢复、底板和素材数据。接入步骤、适配器与保存流程见 [第三方接入文档](./INTEGRATION_API.md)。
|
|
4
4
|
|
|
5
5
|
## 1. 调用规则
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
底板由宿主直接传入;字体、图形、剪贴画可使用商家素材代理或宿主适配器。
|
|
8
8
|
|
|
9
9
|
| 数据 | 属性 | 默认服务域名 | 包内固定前缀 |
|
|
10
10
|
| --- | --- | --- | --- |
|
|
11
|
-
|
|
|
11
|
+
| 底板 | `basePlate`(必填) | 宿主提供完整对象,无 SDK 请求 | 无 |
|
|
12
12
|
| 字体、图形、剪贴画 | `assetBaseUrl` | 当前宿主页 origin | `/api/v1/editor/` |
|
|
13
13
|
| 预设色板 | `adapters.library.colors.list` | 宿主提供,无默认网络请求 | 无远端设置接口 |
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
`assetBaseUrl` 只传**服务域名**,例如 `https://shop.example.com/`。末尾是否带 `/` 都可以;不要把 `/api/v1/editor/` 拼入属性值,包会自行拼接。素材浏览器默认值为 `/`;服务端使用低层素材 client 时须提供绝对 origin。
|
|
16
16
|
|
|
17
17
|
```tsx
|
|
18
18
|
<PrintineDesigner
|
|
19
19
|
productId="variant_123"
|
|
20
|
-
|
|
21
|
-
apiBaseUrl="https://shop-api.printine.com"
|
|
20
|
+
basePlate={basePlate}
|
|
22
21
|
assetBaseUrl="https://shop.example.com"
|
|
23
22
|
/>
|
|
24
23
|
```
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
```json
|
|
29
|
-
{
|
|
30
|
-
"ret": true,
|
|
31
|
-
"data": {}
|
|
32
|
-
}
|
|
33
|
-
```
|
|
34
|
-
|
|
25
|
+
宿主先加载完整底板,再将对象直接传入 `basePlate`,不要传 `{ ret, data }` 等接口响应包装。底板未就绪时不要挂载编辑器。
|
|
35
26
|
|
|
36
27
|
商家素材代理接口的成功响应必须满足:
|
|
37
28
|
|
|
@@ -48,12 +39,12 @@
|
|
|
48
39
|
|
|
49
40
|
### 商品展示:`productInfo`
|
|
50
41
|
|
|
51
|
-
当前 `<PrintineDesigner />`
|
|
42
|
+
当前 `<PrintineDesigner />` **不会自动请求商品详情**。宿主从自己的业务接口读取商品信息,再通过 `productInfo` 传入:
|
|
52
43
|
|
|
53
44
|
```tsx
|
|
54
45
|
<PrintineDesigner
|
|
55
46
|
productId="variant_123"
|
|
56
|
-
|
|
47
|
+
basePlate={basePlate}
|
|
57
48
|
productInfo={{
|
|
58
49
|
title: 'Classic T-shirt',
|
|
59
50
|
imageUrl: 'https://cdn.example.com/product-cover.png',
|
|
@@ -72,7 +63,7 @@
|
|
|
72
63
|
| `currency` | `string \| null` | 币种,例如 `USD` |
|
|
73
64
|
| `variantTitle` | `string \| null` | 变体说明 |
|
|
74
65
|
|
|
75
|
-
|
|
66
|
+
以上字段均可选,仅影响展示。未传时不自动读取商品详情作为回退,全部为空时隐藏商品信息区。包不提供商品详情请求接口。
|
|
76
67
|
|
|
77
68
|
### 已保存设计:`initialDesignData`
|
|
78
69
|
|
|
@@ -122,71 +113,88 @@ interface SemiCustomBackground {
|
|
|
122
113
|
|
|
123
114
|
## 3. 底板详情
|
|
124
115
|
|
|
125
|
-
### `
|
|
116
|
+
### 必传的 `basePlate` 对象
|
|
126
117
|
|
|
127
|
-
|
|
118
|
+
底板数据完全由宿主加载,包内没有底板请求或默认服务地址。对象必须包含 `id` 和至少一个 `areas` 设计面;在编辑过程中保持对象引用稳定。
|
|
128
119
|
|
|
129
|
-
|
|
120
|
+
完整的 2D 底板对象示例:
|
|
130
121
|
|
|
131
122
|
```json
|
|
132
123
|
{
|
|
133
|
-
"
|
|
134
|
-
"
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
"
|
|
124
|
+
"id": 456,
|
|
125
|
+
"areas": [
|
|
126
|
+
{
|
|
127
|
+
"id": "front-area",
|
|
128
|
+
"name": "front",
|
|
129
|
+
"image": "https://cdn.example.com/base-plates/front-overlay.svg",
|
|
130
|
+
"is_default": 1
|
|
131
|
+
}
|
|
132
|
+
],
|
|
133
|
+
"renders": [
|
|
134
|
+
{
|
|
135
|
+
"id": 1,
|
|
136
|
+
"render_areas": [
|
|
137
|
+
{
|
|
138
|
+
"id": 10,
|
|
139
|
+
"name": "bg",
|
|
140
|
+
"image": "https://cdn.example.com/renders/front.png",
|
|
141
|
+
"design": 0,
|
|
142
|
+
"width": 2000,
|
|
143
|
+
"height": 2000,
|
|
144
|
+
"x": 0,
|
|
145
|
+
"y": 0,
|
|
146
|
+
"texture": "",
|
|
147
|
+
"area": {
|
|
148
|
+
"id": "front-area",
|
|
149
|
+
"name": "front",
|
|
150
|
+
"image": "https://cdn.example.com/base-plates/front-overlay.svg",
|
|
151
|
+
"is_default": 1
|
|
152
|
+
}
|
|
153
|
+
},
|
|
154
|
+
{
|
|
155
|
+
"id": 11,
|
|
156
|
+
"name": "front-design",
|
|
157
|
+
"image": "https://cdn.example.com/renders/front-mask.png",
|
|
158
|
+
"design": 1,
|
|
159
|
+
"width": 900,
|
|
160
|
+
"height": 1200,
|
|
161
|
+
"x": 550,
|
|
162
|
+
"y": 350,
|
|
163
|
+
"texture": "https://cdn.example.com/renders/front-texture.png",
|
|
164
|
+
"area": {
|
|
165
|
+
"id": "front-area",
|
|
166
|
+
"name": "front",
|
|
167
|
+
"image": "https://cdn.example.com/base-plates/front-overlay.svg",
|
|
168
|
+
"is_default": 1
|
|
158
169
|
},
|
|
159
|
-
{
|
|
160
|
-
"
|
|
161
|
-
"name": "front-design",
|
|
162
|
-
"image": "https://cdn.example.com/renders/front-mask.png",
|
|
163
|
-
"design": 1,
|
|
164
|
-
"width": 900,
|
|
165
|
-
"height": 1200,
|
|
166
|
-
"x": 550,
|
|
167
|
-
"y": 350,
|
|
168
|
-
"texture": "https://cdn.example.com/renders/front-texture.png",
|
|
169
|
-
"area": { "name": "front" },
|
|
170
|
-
"texture_transform": { "blendMode": "normal" }
|
|
170
|
+
"texture_transform": {
|
|
171
|
+
"blendMode": "normal"
|
|
171
172
|
}
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
173
|
+
}
|
|
174
|
+
],
|
|
175
|
+
"image": "https://cdn.example.com/renders/front.png"
|
|
176
|
+
}
|
|
177
|
+
],
|
|
178
|
+
"td_renders": [],
|
|
179
|
+
"colors": [],
|
|
180
|
+
"preview_img01": "",
|
|
181
|
+
"preview_img02": "",
|
|
182
|
+
"custom_color": 0,
|
|
183
|
+
"custom_shape": 0,
|
|
184
|
+
"render_list": []
|
|
177
185
|
}
|
|
178
186
|
```
|
|
179
187
|
|
|
180
|
-
|
|
188
|
+
通过 `basePlate` Props 传入时应使用包导出的 `BasePlate` 类型。无 2D/3D 预览时仍应提供空数组;兼容字段也应保留。
|
|
181
189
|
|
|
182
|
-
### `
|
|
190
|
+
### `basePlate` 字段
|
|
183
191
|
|
|
184
192
|
| 字段 | 类型 | 必填 | 包内用途 |
|
|
185
193
|
| --- | --- | --- | --- |
|
|
186
|
-
| `id` | `string \| number` | 是 |
|
|
194
|
+
| `id` | `string \| number` | 是 | 底板标识;预览参数使用,宿主保存时可自行补充。 |
|
|
187
195
|
| `areas` | `Mockup[]` | 是 | 设计面列表;第一项作为初始设计面。 |
|
|
188
|
-
| `renders` | `Render[]` |
|
|
189
|
-
| `td_renders` | `TDRender[]` |
|
|
196
|
+
| `renders` | `Render[]` | 是 | 2D 实时预览。无 2D 预览可传 `[]`。 |
|
|
197
|
+
| `td_renders` | `TDRender[]` | 是 | 3D 实时预览。无 3D 预览可传 `[]`。若同时提供,包优先展示 3D。 |
|
|
190
198
|
|
|
191
199
|
包目前不读取 `colors`、`preview_img01`、`preview_img02`、`custom_color`、`custom_shape`、`render_list` 等其他底板字段。
|
|
192
200
|
|
|
@@ -311,7 +319,7 @@ return [
|
|
|
311
319
|
|
|
312
320
|
## 5. 商家素材代理和宿主色板
|
|
313
321
|
|
|
314
|
-
这些接口通过商家后端代理调用 Printine Gateway,包只附带同源会话,不持有长期 App Key
|
|
322
|
+
这些接口通过商家后端代理调用 Printine Gateway,包只附带同源会话,不持有长期 App Key。`assetBaseUrl` 不传时使用当前宿主页 origin。列表和文件均使用 `/api/v1/editor/*`,没有旧路径兼容、旧素材域回退或第二层 editor 前缀。商家须校验编辑访问、使用带 `assets:read` 的后端 Key,并把列表中的文件 URL 映射到受保护的商家代理,保留后缀及 `v`。
|
|
315
323
|
|
|
316
324
|
### `GET /api/v1/editor/fonts`
|
|
317
325
|
|
package/docs/INTEGRATION_API.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
适用对象:在自有 React 项目中接入商品在线设计器的前端和后端开发者。
|
|
4
4
|
|
|
5
|
-
本文依据 `@printine/pod-editor` **0.1.
|
|
5
|
+
本文依据 `@printine/pod-editor` **0.1.14 的当前源码**编写,更新日期:2026-10-21。安装包导出的 TypeScript 类型是字段类型的最终依据。文中的 `example.com`、商品/底板 ID 和 `/api/designer/*` 均为示例,需替换为实际配置;`/api/designer/*` 不是 SDK 内置接口。
|
|
6
6
|
|
|
7
7
|
## 目录
|
|
8
8
|
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
|
|
26
26
|
| 能力 | 设计器负责 | 宿主负责 |
|
|
27
27
|
| --- | --- | --- |
|
|
28
|
-
| 初始化 | 按底板创建画布和预览 | 提供商品变体 ID
|
|
28
|
+
| 初始化 | 按底板创建画布和预览 | 提供商品变体 ID 和完整的 `basePlate` 对象 |
|
|
29
29
|
| 商品信息 | 展示标题、图片、价格等 | 通过 `productInfo` 提供展示信息;当前不自动请求商品详情 |
|
|
30
30
|
| 用户与权限 | 调用宿主适配器 | 登录、会话、访问权限与数据归属校验 |
|
|
31
31
|
| 图片上传 | 提供文件、用途及可选元信息 | 上传、缩略图、用户素材登记、返回完整 URL |
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
|
|
42
42
|
- 使用 React 和 React DOM 18 或 19,项目支持 ESM 和 CSS 导入。
|
|
43
43
|
- 在浏览器中加载组件;设计器依赖 DOM、Canvas、Worker 等能力,3D 预览还需相应的图形能力。
|
|
44
|
-
- 准备匹配的 `productId`(商品变体 ID
|
|
44
|
+
- 准备匹配的 `productId`(商品变体 ID)和完整 `basePlate` 对象,两者必传。底板由宿主加载,SDK 不请求底板数据;异步加载完成后再挂载组件。
|
|
45
45
|
- 底板至少有一个设计面,并提供可访问的 SVG 设计面文件及所需 2D/3D 资源。
|
|
46
46
|
- 图片、SVG、字体、模型和纹理 URL 应持续可访问。跨域资源须允许宿主页面读取;仅能在 `<img>` 中显示,不能保证画布可以导出。
|
|
47
47
|
|
|
@@ -49,20 +49,19 @@
|
|
|
49
49
|
|
|
50
50
|
| 用途 | 默认请求 | 说明 |
|
|
51
51
|
| --- | --- | --- |
|
|
52
|
-
| 底板 |
|
|
53
|
-
| 游客 token | `GET /api/client/get-guest-token`,位于 `apiBaseUrl` 的 origin | Printine API 返回业务码 `445` 时获取 token,以 `X-Guest-Token` 重试原请求一次 |
|
|
52
|
+
| 底板 | 无 SDK 请求 | 必须通过 `basePlate` 提供完整数据 |
|
|
54
53
|
| 字体 | `GET /api/v1/editor/fonts` | 默认当前宿主页 origin,或通过 `library.fonts.list` 提供 |
|
|
55
54
|
| 图形 | `GET /api/v1/editor/shapes?page=1&limit=30` | 默认当前宿主页 origin,按需分页,或通过 `library.shapes.list` 提供 |
|
|
56
55
|
| 剪贴画 | `GET /api/v1/editor/clipart-categories` | 默认当前宿主页 origin,或通过 `library.clipart.listCategories` 提供 |
|
|
57
56
|
| 上传、用户素材、用户模板、最终保存 | 宿主自定义 | 通过适配器/回调实现,无固定宿主路由 |
|
|
58
57
|
|
|
59
|
-
`
|
|
58
|
+
`assetBaseUrl` 只传 origin,例如 `https://shop.example.com`,SDK 添加 API 前缀。`assetBaseUrl` 是素材服务地址,不是图片 CDN 前缀。
|
|
60
59
|
|
|
61
60
|
SDK 没有顶层 `token`、`appKey` 或自定义请求头 Props。用户业务接口的鉴权由宿主请求实现。使用 Printine 素材网关时,带 `assets:read` 权限的 App Key 保留在宿主后端,由后端代理请求,不放入前端代码。
|
|
62
61
|
|
|
63
|
-
素材列表请求固定使用 `credentials: 'same-origin'
|
|
62
|
+
素材列表请求固定使用 `credentials: 'same-origin'`。推荐同源代理;指定跨 origin 的 `assetBaseUrl` 不会自动携带该 origin 的 Cookie。需要其他鉴权方式时实现 `adapters.library`。代理应校验编辑访问权限,将网关文件地址映射为浏览器可访问的商家文件 URL,并保留文件后缀及版本参数 `v`。
|
|
64
63
|
|
|
65
|
-
|
|
64
|
+
底板对象与素材响应格式见 [宿主数据接口契约](./HOST_DATA_CONTRACT.md)。
|
|
66
65
|
|
|
67
66
|
## 3. 快速接入
|
|
68
67
|
|
|
@@ -72,17 +71,17 @@ SDK 没有顶层 `token`、`appKey` 或自定义请求头 Props。用户业务
|
|
|
72
71
|
npm install @printine/pod-editor
|
|
73
72
|
```
|
|
74
73
|
|
|
75
|
-
请锁定经过联调的版本。本文记录的源码版本为 0.1.
|
|
74
|
+
请锁定经过联调的版本。本文记录的源码版本为 0.1.14,不代表 npm 当前最新版本。
|
|
76
75
|
|
|
77
76
|
```tsx
|
|
78
|
-
import { PrintineDesigner } from '@printine/pod-editor';
|
|
77
|
+
import { PrintineDesigner, type BasePlate } from '@printine/pod-editor';
|
|
79
78
|
import '@printine/pod-editor/styles.css';
|
|
80
79
|
|
|
81
|
-
export function DesignerPage() {
|
|
80
|
+
export function DesignerPage({ basePlate }: { basePlate: BasePlate }) {
|
|
82
81
|
return (
|
|
83
82
|
<PrintineDesigner
|
|
84
83
|
productId="your-variant-id"
|
|
85
|
-
|
|
84
|
+
basePlate={basePlate}
|
|
86
85
|
locale="en-US"
|
|
87
86
|
productInfo={{ title: 'Classic T-shirt', price: 19.9, currency: 'USD' }}
|
|
88
87
|
onClose={() => window.history.back()}
|
|
@@ -91,7 +90,7 @@ export function DesignerPage() {
|
|
|
91
90
|
}
|
|
92
91
|
```
|
|
93
92
|
|
|
94
|
-
|
|
93
|
+
该示例使用宿主传入的完整底板与同源素材代理。通常还需实现下节的上传和保存能力。设计器按整页布局实现,含固定定位工具栏和全屏预览,建议放在独立路由中。当前存在共享状态和模块级 API 配置,同页同时挂载多个完整设计器不适合作为接入方案。
|
|
95
94
|
|
|
96
95
|
### 3.2 带上传与保存的完整示例
|
|
97
96
|
|
|
@@ -108,6 +107,7 @@ export function DesignerPage() {
|
|
|
108
107
|
import { useCallback, useMemo, useState } from 'react';
|
|
109
108
|
import {
|
|
110
109
|
PrintineDesigner,
|
|
110
|
+
type BasePlate,
|
|
111
111
|
type DesignerAdapters,
|
|
112
112
|
type DesignerError,
|
|
113
113
|
type DesignerImageUploadResult,
|
|
@@ -126,7 +126,7 @@ async function requestHost<T>(url: string, init?: RequestInit): Promise<T> {
|
|
|
126
126
|
return body.data;
|
|
127
127
|
}
|
|
128
128
|
|
|
129
|
-
export function ProductDesignerPage() {
|
|
129
|
+
export function ProductDesignerPage({ basePlate }: { basePlate: BasePlate }) {
|
|
130
130
|
const [errorMessage, setErrorMessage] = useState('');
|
|
131
131
|
const [savedId, setSavedId] = useState('');
|
|
132
132
|
const showError = useCallback((error: unknown) => {
|
|
@@ -180,7 +180,7 @@ export function ProductDesignerPage() {
|
|
|
180
180
|
<>
|
|
181
181
|
<PrintineDesigner
|
|
182
182
|
productId="your-variant-id"
|
|
183
|
-
|
|
183
|
+
basePlate={basePlate}
|
|
184
184
|
locale="en-US"
|
|
185
185
|
productInfo={{ title: 'Classic T-shirt', price: 19.9, currency: 'USD' }}
|
|
186
186
|
adapters={adapters}
|
|
@@ -200,7 +200,7 @@ export function ProductDesignerPage() {
|
|
|
200
200
|
}
|
|
201
201
|
```
|
|
202
202
|
|
|
203
|
-
|
|
203
|
+
保持 `basePlate`、回调和适配器引用稳定,尤其是 `onError`、`onEvent` 和字体/色板 loader;这些引用变化可能重新触发初始化 effect。
|
|
204
204
|
|
|
205
205
|
### 3.3 使用 SSR 框架
|
|
206
206
|
|
|
@@ -210,6 +210,7 @@ export function ProductDesignerPage() {
|
|
|
210
210
|
'use client';
|
|
211
211
|
|
|
212
212
|
import dynamic from 'next/dynamic';
|
|
213
|
+
import type { BasePlate } from '@printine/pod-editor';
|
|
213
214
|
import '@printine/pod-editor/styles.css';
|
|
214
215
|
|
|
215
216
|
const BrowserDesigner = dynamic(
|
|
@@ -217,8 +218,8 @@ const BrowserDesigner = dynamic(
|
|
|
217
218
|
{ ssr: false },
|
|
218
219
|
);
|
|
219
220
|
|
|
220
|
-
export default function DesignerRoute() {
|
|
221
|
-
return <BrowserDesigner productId="your-variant-id"
|
|
221
|
+
export default function DesignerRoute({ basePlate }: { basePlate: BasePlate }) {
|
|
222
|
+
return <BrowserDesigner productId="your-variant-id" basePlate={basePlate} />;
|
|
222
223
|
}
|
|
223
224
|
```
|
|
224
225
|
|
|
@@ -229,10 +230,8 @@ export default function DesignerRoute() {
|
|
|
229
230
|
| 参数 | 类型 | 必填/默认 | 说明 |
|
|
230
231
|
| --- | --- | --- | --- |
|
|
231
232
|
| `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
233
|
| `assetBaseUrl` | `string` | `/`,当前页面 origin | 商家素材代理 origin,SDK 添加 `/api/v1/editor/` |
|
|
235
|
-
| `basePlate` | `BasePlate
|
|
234
|
+
| `basePlate` | `BasePlate` | 必填 | 宿主加载的完整底板对象,SDK 不请求底板数据 |
|
|
236
235
|
| `productInfo` | `DesignerProductInfo` | 可选 | 商品展示信息,不决定画布结构或保存数据 |
|
|
237
236
|
| `initialDesignData` | `Record<string, Record<string, unknown>>` | 可选 | 恢复的 Fabric JSON,按设计面 `name` 分组 |
|
|
238
237
|
| `initialBackgroundCustomized` | `SemiCustomBackground` | 可选 | 恢复半定制背景配置,与设计 JSON 分开传递 |
|
|
@@ -350,22 +349,21 @@ SDK 在调用前处理需持久化的临时图片、过滤空文本并合并半
|
|
|
350
349
|
从宿主记录读取设计,传回 `initialDesignData`,不要把整个保存输入传给该属性:
|
|
351
350
|
|
|
352
351
|
```tsx
|
|
353
|
-
import { PrintineDesigner, type SemiCustomBackground } from '@printine/pod-editor';
|
|
352
|
+
import { PrintineDesigner, type BasePlate, type SemiCustomBackground } from '@printine/pod-editor';
|
|
354
353
|
|
|
355
354
|
type SavedDesign = {
|
|
356
355
|
id: string;
|
|
357
356
|
variantId: string;
|
|
358
|
-
basePlateId: string | number;
|
|
359
357
|
designData: Record<string, Record<string, unknown>>;
|
|
360
358
|
backgroundCustomized?: SemiCustomBackground;
|
|
361
359
|
};
|
|
362
360
|
|
|
363
|
-
export function RestoreDesigner({ record }: { record: SavedDesign }) {
|
|
361
|
+
export function RestoreDesigner({ record, basePlate }: { record: SavedDesign; basePlate: BasePlate }) {
|
|
364
362
|
return (
|
|
365
363
|
<PrintineDesigner
|
|
366
|
-
key={`${record.id}:${record.variantId}:${
|
|
364
|
+
key={`${record.id}:${record.variantId}:${basePlate.id}`}
|
|
367
365
|
productId={record.variantId}
|
|
368
|
-
|
|
366
|
+
basePlate={basePlate}
|
|
369
367
|
initialDesignData={record.designData}
|
|
370
368
|
initialBackgroundCustomized={record.backgroundCustomized}
|
|
371
369
|
/>
|
|
@@ -373,7 +371,7 @@ export function RestoreDesigner({ record }: { record: SavedDesign }) {
|
|
|
373
371
|
}
|
|
374
372
|
```
|
|
375
373
|
|
|
376
|
-
示例仅展示恢复参数,实际需合入上传与保存等能力。设计面键推荐使用 `areas[].name`,兼容旧数据以 `areas[].id` 字符串为键。切换商品、底板或不同保存记录时建议修改组件 `key
|
|
374
|
+
示例仅展示恢复参数,实际需合入上传与保存等能力。设计面键推荐使用 `areas[].name`,兼容旧数据以 `areas[].id` 字符串为键。切换商品、底板或不同保存记录时建议修改组件 `key`,避免复用初始化状态。底板尚未加载时不要挂载组件;底板已就绪但草稿仍在加载时可传 `loading={true}`,准备好再初始化;初始数据入口不是受控画布状态。
|
|
377
375
|
|
|
378
376
|
`initialBackgroundCustomized` 的结构为 `{ enable: boolean; palette: boolean; colors: string[] }`。当前有历史 `sessionStorage.designData` 恢复逻辑,但它不是第三方草稿协议;离开/刷新不能代替宿主持久化,需要恢复的记录应由宿主明确保存和加载。
|
|
379
377
|
|
package/docs/SEMI_RENDERER.md
CHANGED
|
@@ -52,7 +52,7 @@ Worker、`OffscreenCanvas` 或 `ImageBitmap` 时自动回退到 Pixi。
|
|
|
52
52
|
真实视角(不是空视角),`preloadDesignData` 可传未经 debounce 的最新设计文档。
|
|
53
53
|
当前视角的图层、底板 SVG 和 Fabric 图片先加载,完成后才启动其他视角的后台预加载。
|
|
54
54
|
默认 pixel-map 路径中,没有设计对象且没有生效背景色的印刷 mask 不参与预加载、解码或合成;静态 bg、cover
|
|
55
|
-
|
|
55
|
+
始终保留。默认 `colorMode="global"` 保留已有语义:按印刷层顺序取第一个字符串类型的文档 `color`,包括空字符串,作为整个视角的底色。需要逐部件颜色的 Full Custom 预览应显式传 `colorMode="placement"`;此时每个设计面只使用自己 `designData[designKey || area.name].color` 的颜色,调整层顺序或切换视角不改变颜色归属。其他无色空面跳过,清色后不复用该面旧纹理。
|
|
56
56
|
此判定使用 `preloadDesignData ?? designData`,因此暂停合成和等待 debounce 快照时也能
|
|
57
57
|
预热当前原始设计。只需当前视角时可省略 `preloadSources`,避免下载尚未选中的视角。
|
|
58
58
|
旧 Pixi 回退保留原先完整图层行为。
|
|
@@ -113,7 +113,12 @@ Worker 解码都使用这些本地 URL,不再各自请求远程图片。宿主
|
|
|
113
113
|
}
|
|
114
114
|
```
|
|
115
115
|
|
|
116
|
-
背景是否允许用户修改、哪些元素能修改以及输入控件的显示方式,都由宿主根据自己的 `customConfig`
|
|
116
|
+
背景是否允许用户修改、哪些元素能修改以及输入控件的显示方式,都由宿主根据自己的 `customConfig` 和业务规则处理。
|
|
117
|
+
|
|
118
|
+
- 省略 `colorMode` 或传 `"global"`:保留旧版首个印刷面颜色推导、合成底色和逐文档纹理导出语义;已有 Easy 调用无需修改。`backgroundColor`(包括空字符串)优先于推导的全局底色,但不会改写已有的文档纹理颜色。
|
|
119
|
+
- 传 `colorMode="placement"`:各面可以分别为红、黑或透明,透明图案下方不继承另一面的底色。PixelMap 的纯色面直接逐层填色,无需额外 Fabric 导出;Pixi 回退利用该面 `area` 信息把局部色烘入对应纹理。显式 `backgroundColor` 覆盖各印刷面的底色,空字符串清除这些底色。
|
|
120
|
+
|
|
121
|
+
两种模式都保持静态背景和 cover 的原图。模式切换会重新校验当前视角的预加载资源和纹理缓存;不会修改 `designData`,也不改变 Full Designer 实时编辑链路。
|
|
117
122
|
|
|
118
123
|
## Ref 方法
|
|
119
124
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@printine/pod-editor",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.16",
|
|
4
4
|
"description": "React online product designer with Fabric canvas and host-owned commerce integrations.",
|
|
5
5
|
"private": false,
|
|
6
6
|
"keywords": [
|
|
@@ -20,18 +20,10 @@
|
|
|
20
20
|
"types": "./dist/index.d.ts",
|
|
21
21
|
"import": "./dist/index.js"
|
|
22
22
|
},
|
|
23
|
-
"./api/client": {
|
|
24
|
-
"types": "./dist/api/client.d.ts",
|
|
25
|
-
"import": "./dist/api/client.js"
|
|
26
|
-
},
|
|
27
23
|
"./api/asset-client": {
|
|
28
24
|
"types": "./dist/api/asset-client.d.ts",
|
|
29
25
|
"import": "./dist/api/asset-client.js"
|
|
30
26
|
},
|
|
31
|
-
"./api/endpoints": {
|
|
32
|
-
"types": "./dist/api/endpoints.d.ts",
|
|
33
|
-
"import": "./dist/api/endpoints.js"
|
|
34
|
-
},
|
|
35
27
|
"./full-designer": {
|
|
36
28
|
"types": "./dist/components/design.d.ts",
|
|
37
29
|
"import": "./dist/full-designer.js"
|
|
@@ -146,7 +138,7 @@
|
|
|
146
138
|
"scripts": {
|
|
147
139
|
"build": "vite build && tsc -p tsconfig.build.json && node ./scripts/copy-declarations.mjs",
|
|
148
140
|
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
149
|
-
"test:api": "node ./tests/api-client.smoke.mjs && node --test ./tests/editor-assets.smoke.mjs",
|
|
141
|
+
"test:api": "node ./tests/api-client.smoke.mjs && node --test ./tests/editor-assets.smoke.mjs && node ./tests/base-plate.smoke.mjs",
|
|
150
142
|
"test:preview-assets": "node ./tests/preview-assets.smoke.mjs",
|
|
151
143
|
"test:workspace-pattern": "node ./tests/workspace-pattern.smoke.mjs",
|
|
152
144
|
"test:render-preload": "node ./tests/render-preload.smoke.mjs",
|
|
@@ -160,7 +152,6 @@
|
|
|
160
152
|
"react-dom": ">=18 <20"
|
|
161
153
|
},
|
|
162
154
|
"dependencies": {
|
|
163
|
-
"@aws-sdk/client-s3": "^3.975.0",
|
|
164
155
|
"@dnd-kit/core": "^6.3.1",
|
|
165
156
|
"@dnd-kit/modifiers": "^9.0.0",
|
|
166
157
|
"@dnd-kit/sortable": "^10.0.0",
|
package/dist/api/client.d.ts
DELETED
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
import type { DesignerApiClient, DesignerApiClientOptions } from '../types';
|
|
2
|
-
/** Production API used by the complete <PrintineDesigner /> entry point. */
|
|
3
|
-
export declare const DEFAULT_PRINTINE_API_BASE_URL = "https://shop-api.printine.com";
|
|
4
|
-
/**
|
|
5
|
-
* API client for the existing Printine endpoints. It deliberately owns no host
|
|
6
|
-
* state and receives only the API location from the embedding site.
|
|
7
|
-
*/
|
|
8
|
-
export declare function createDesignerApiClient(options: DesignerApiClientOptions): DesignerApiClient;
|
package/dist/api/client.js
DELETED
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
const h = "api/client/", g = "https://shop-api.printine.com";
|
|
2
|
-
function l(e, t) {
|
|
3
|
-
const s = /^https?:\/\//i.test(e) ? new URL(e) : typeof window < "u" ? new URL(e, window.location.origin) : null;
|
|
4
|
-
if (!s)
|
|
5
|
-
throw new Error("An absolute apiBaseUrl domain is required for SSR.");
|
|
6
|
-
const o = new URL(h, s.origin);
|
|
7
|
-
return new URL(t.replace(/^\//, ""), o);
|
|
8
|
-
}
|
|
9
|
-
async function f(e, t = !1, s) {
|
|
10
|
-
const o = new Headers();
|
|
11
|
-
return t && o.set("Content-Type", "application/json"), e.locale && o.set("Accept-Language", e.locale), s && o.set("X-Guest-Token", s), o;
|
|
12
|
-
}
|
|
13
|
-
async function p(e) {
|
|
14
|
-
return (await e.clone().json().catch(() => null))?.code === 445;
|
|
15
|
-
}
|
|
16
|
-
async function w(e) {
|
|
17
|
-
const t = await e.json().catch(() => null);
|
|
18
|
-
if (!e.ok)
|
|
19
|
-
throw new Error(t?.message || `Designer API request failed (${e.status})`);
|
|
20
|
-
if (!t) throw new Error("Designer API returned an empty or invalid JSON response");
|
|
21
|
-
if (t.ret === !1 || t.ret === 0)
|
|
22
|
-
throw new Error(t.message || t.msg || "Designer API request was rejected");
|
|
23
|
-
return t;
|
|
24
|
-
}
|
|
25
|
-
function A(e) {
|
|
26
|
-
let t, s = null;
|
|
27
|
-
const o = async () => t || s || (s = (async () => {
|
|
28
|
-
const n = new Headers();
|
|
29
|
-
e.locale && n.set("Accept-Language", e.locale);
|
|
30
|
-
const a = await (await fetch(l(e.apiBaseUrl, "get-guest-token"), { headers: n })).json().catch(() => null), c = a?.ret !== !1 && a?.ret !== 0 && typeof a?.data?.token == "string" ? a.data.token : void 0;
|
|
31
|
-
return t = c, c;
|
|
32
|
-
})().finally(() => {
|
|
33
|
-
s = null;
|
|
34
|
-
}), s), u = async (n) => {
|
|
35
|
-
let r = await n(t);
|
|
36
|
-
if (await p(r)) {
|
|
37
|
-
const a = await o();
|
|
38
|
-
a && (r = await n(a));
|
|
39
|
-
}
|
|
40
|
-
return r;
|
|
41
|
-
}, d = async (n, r, a) => {
|
|
42
|
-
const c = await u(
|
|
43
|
-
async (i) => fetch(l(e.apiBaseUrl, r), {
|
|
44
|
-
method: n,
|
|
45
|
-
headers: await f(e, !0, i),
|
|
46
|
-
body: a === void 0 ? void 0 : JSON.stringify(a)
|
|
47
|
-
})
|
|
48
|
-
);
|
|
49
|
-
return w(c);
|
|
50
|
-
};
|
|
51
|
-
return {
|
|
52
|
-
async get(n, r) {
|
|
53
|
-
const a = l(e.apiBaseUrl, n);
|
|
54
|
-
for (const [i, y] of Object.entries(r ?? {}))
|
|
55
|
-
y !== void 0 && a.searchParams.set(i, String(y));
|
|
56
|
-
const c = await u(
|
|
57
|
-
async (i) => fetch(a, { headers: await f(e, !1, i) })
|
|
58
|
-
);
|
|
59
|
-
return w(c);
|
|
60
|
-
},
|
|
61
|
-
async post(n, r) {
|
|
62
|
-
return d("POST", n, r);
|
|
63
|
-
},
|
|
64
|
-
async delete(n, r) {
|
|
65
|
-
return d("DELETE", n, r);
|
|
66
|
-
},
|
|
67
|
-
async postForm(n, r) {
|
|
68
|
-
const a = await u(
|
|
69
|
-
async (c) => fetch(l(e.apiBaseUrl, n), {
|
|
70
|
-
method: "POST",
|
|
71
|
-
headers: await f(e, !1, c),
|
|
72
|
-
body: r
|
|
73
|
-
})
|
|
74
|
-
);
|
|
75
|
-
return w(a);
|
|
76
|
-
}
|
|
77
|
-
};
|
|
78
|
-
}
|
|
79
|
-
export {
|
|
80
|
-
g as DEFAULT_PRINTINE_API_BASE_URL,
|
|
81
|
-
A as createDesignerApiClient
|
|
82
|
-
};
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
export declare const uploadImage: (formData: FormData) => Promise<import("./endpoints").ApiResponse<any>>;
|
|
2
|
-
export declare const getUploadKey: () => Promise<import("./endpoints").ApiResponse<{
|
|
3
|
-
base_path: string;
|
|
4
|
-
bucket: string;
|
|
5
|
-
region: string;
|
|
6
|
-
configs: {
|
|
7
|
-
AccessKeyId: string;
|
|
8
|
-
SecretAccessKey: string;
|
|
9
|
-
Expiration: string;
|
|
10
|
-
SessionToken: string;
|
|
11
|
-
};
|
|
12
|
-
}>>;
|
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
/** Named endpoint helpers, mirroring the host module the editor UI imported. */
|
|
2
|
-
export declare const getProduct: (id: string) => Promise<import("./endpoints").ApiResponse<import("..").Product>>;
|
|
3
|
-
export declare const getDesign: (id: string) => Promise<import("./endpoints").ApiResponse<import("..").BasePlate>>;
|
|
4
|
-
export declare const onGenerateImage: (data: Record<string, any>) => Promise<import("./endpoints").ApiResponse<any>>;
|
package/dist/api/endpoints.d.ts
DELETED
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
import type { BasePlate, Product } from '../contracts/api-design';
|
|
2
|
-
import type { ApiResponse, DesignerApiClient } from '../types';
|
|
3
|
-
export declare function setDesignerApiClient(next: DesignerApiClient | null): void;
|
|
4
|
-
export declare const DesignApi: {
|
|
5
|
-
getProduct: (id: string) => Promise<ApiResponse<Product>>;
|
|
6
|
-
getDesign: (id: string) => Promise<ApiResponse<BasePlate>>;
|
|
7
|
-
onGenerateImage: (data: Record<string, any>) => Promise<ApiResponse<any>>;
|
|
8
|
-
};
|
|
9
|
-
export declare const CommonApi: {
|
|
10
|
-
uploadImage: (formData: FormData) => Promise<ApiResponse<any>>;
|
|
11
|
-
getUploadKey: () => Promise<ApiResponse<{
|
|
12
|
-
base_path: string;
|
|
13
|
-
bucket: string;
|
|
14
|
-
region: string;
|
|
15
|
-
configs: {
|
|
16
|
-
AccessKeyId: string;
|
|
17
|
-
SecretAccessKey: string;
|
|
18
|
-
Expiration: string;
|
|
19
|
-
SessionToken: string;
|
|
20
|
-
};
|
|
21
|
-
}>>;
|
|
22
|
-
};
|
|
23
|
-
export type { ApiResponse };
|
package/dist/api/endpoints.js
DELETED
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
let n = null;
|
|
2
|
-
function a(e) {
|
|
3
|
-
n = e;
|
|
4
|
-
}
|
|
5
|
-
function i() {
|
|
6
|
-
if (!n)
|
|
7
|
-
throw new Error("[printine-designer] API client is not ready. Render <PrintineDesigner /> before calling the API.");
|
|
8
|
-
return n;
|
|
9
|
-
}
|
|
10
|
-
const o = (e, t) => i().get(e, t), r = (e, t) => i().post(e, t), s = (e, t) => i().postForm(e, t), g = {
|
|
11
|
-
// Public template catalog is temporarily disabled. Template persistence and
|
|
12
|
-
// listing are provided by the host through `adapters.templates` instead.
|
|
13
|
-
// getTemplateList: (params: Params) => get<any>('template-categories', params),
|
|
14
|
-
getProduct: (e) => o(`products/variant/${e}`),
|
|
15
|
-
getDesign: (e) => o(`base-plates/${e}`),
|
|
16
|
-
onGenerateImage: (e) => r("ai-images/generate", e)
|
|
17
|
-
// Legacy package-owned save method (kept for reference only). The package
|
|
18
|
-
// now delegates this to the host's `onSave` callback.
|
|
19
|
-
// saveDesign: (data: Record<string, any>) => post<any>(API_URLS.SAVE_DESIGN, data),
|
|
20
|
-
// Legacy package-owned user-template methods (kept for reference only):
|
|
21
|
-
// saveTemplate: (data: Record<string, any>) => post<any>(API_URLS.USER_TEMPLATES, data),
|
|
22
|
-
// getUserTemplates: () => get<any>(API_URLS.USER_TEMPLATES),
|
|
23
|
-
// getUserTemplteDetail: (id: string) => get<any>(`${API_URLS.USER_TEMPLATES}/${id}`),
|
|
24
|
-
// deleteUserTemplate: (id: string) => del<any>(`${API_URLS.USER_TEMPLATES}/${id}`),
|
|
25
|
-
}, p = {
|
|
26
|
-
uploadImage: (e) => s("uploads/image", e),
|
|
27
|
-
getUploadKey: () => r("uploads/get-temp-access")
|
|
28
|
-
};
|
|
29
|
-
export {
|
|
30
|
-
p as CommonApi,
|
|
31
|
-
g as DesignApi,
|
|
32
|
-
a as setDesignerApiClient
|
|
33
|
-
};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|