@printine/pod-editor 0.0.0-stage → 0.1.15
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 +224 -2
- package/dist/DesignerRuntimeContext.d.ts +3 -0
- package/dist/PrintineDesigner.d.ts +9 -0
- package/dist/api/asset-client.d.ts +8 -0
- package/dist/api/asset-client.js +40 -0
- package/dist/api/asset-endpoints.d.ts +36 -0
- package/dist/assets/icons/aspect_ratio.d.ts +3 -0
- package/dist/assets/icons/delete.d.ts +3 -0
- package/dist/assets/icons/fit_screen.d.ts +3 -0
- package/dist/assets/icons/index.d.ts +11 -0
- package/dist/assets/icons/loading_1.d.ts +3 -0
- package/dist/assets/icons/loading_2.d.ts +3 -0
- package/dist/assets/icons/loading_3.d.ts +3 -0
- package/dist/assets/icons/pan.d.ts +3 -0
- package/dist/assets/icons/setting.d.ts +3 -0
- package/dist/assets/icons/text_color.d.ts +3 -0
- package/dist/assets/icons/text_h.d.ts +3 -0
- package/dist/assets/icons/text_v.d.ts +3 -0
- package/dist/bundled-assets.d.ts +4 -0
- package/dist/components/add-design.d.ts +8 -0
- package/dist/components/assets-dialog.d.ts +24 -0
- package/dist/components/canvas-context-menu.d.ts +6 -0
- package/dist/components/color-picker/index.d.ts +11 -0
- package/dist/components/context.d.ts +24 -0
- package/dist/components/design.d.ts +9 -0
- package/dist/components/fonts.d.ts +26 -0
- package/dist/components/image-crop.d.ts +5 -0
- package/dist/components/image-edit.d.ts +1 -0
- package/dist/components/layout/aside.d.ts +4 -0
- package/dist/components/layout/bottom-nav/element-menu-sheet.d.ts +11 -0
- package/dist/components/layout/bottom-nav/element-sheet.d.ts +11 -0
- package/dist/components/layout/bottom-nav/index.d.ts +1 -0
- package/dist/components/layout/header.d.ts +1 -0
- package/dist/components/loading.d.ts +3 -0
- package/dist/components/menus/background.d.ts +6 -0
- package/dist/components/menus/clipart.d.ts +6 -0
- package/dist/components/menus/files.d.ts +7 -0
- package/dist/components/menus/image.d.ts +8 -0
- package/dist/components/menus/index.d.ts +13 -0
- package/dist/components/menus/layer.d.ts +5 -0
- package/dist/components/menus/product.d.ts +3 -0
- package/dist/components/menus/sca.d.ts +5 -0
- package/dist/components/menus/shapes.d.ts +6 -0
- package/dist/components/menus/templates.d.ts +6 -0
- package/dist/components/menus/text-effects.d.ts +5 -0
- package/dist/components/menus/text.d.ts +6 -0
- package/dist/components/placement-tab.d.ts +7 -0
- package/dist/components/preview/3d.d.ts +8 -0
- package/dist/components/preview/graphic.d.ts +15 -0
- package/dist/components/preview/index.d.ts +20 -0
- package/dist/components/preview/open.d.ts +7 -0
- package/dist/components/preview/real-time/3d.d.ts +12 -0
- package/dist/components/preview/real-time/graphic.d.ts +31 -0
- package/dist/components/preview/real-time/index.d.ts +12 -0
- package/dist/components/scale-tools.d.ts +7 -0
- package/dist/components/semi-deisgn-config.d.ts +13 -0
- package/dist/components/semi-design-link.d.ts +9 -0
- package/dist/components/semi-interact-editor.d.ts +27 -0
- package/dist/components/semi-renderer.d.ts +74 -0
- package/dist/components/store.d.ts +1 -0
- package/dist/components/toolbar.d.ts +2 -0
- package/dist/components/upload-types.d.ts +20 -0
- package/dist/config-D2qm60gf.js +16 -0
- package/dist/contracts/api-design.d.ts +180 -0
- package/dist/contracts/design.d.ts +86 -0
- package/dist/design-CZvEVkwi.js +21443 -0
- package/dist/designer-store-Da9fICz8.js +153 -0
- package/dist/engine/canvas-designer.d.ts +101 -0
- package/dist/engine/canvas-designer.js +313 -0
- package/dist/engine/constants.d.ts +26 -0
- package/dist/engine/constants.js +147 -0
- package/dist/engine/editor.d.ts +199 -0
- package/dist/engine/editor.js +801 -0
- package/dist/engine/events.d.ts +35 -0
- package/dist/engine/events.js +7 -0
- package/dist/engine/extensions/curved-text.d.ts +59 -0
- package/dist/engine/fabric.d.ts +4 -0
- package/dist/engine/fabric.js +187 -0
- package/dist/engine/history.d.ts +27 -0
- package/dist/engine/history.js +56 -0
- package/dist/engine/managers/event.d.ts +101 -0
- package/dist/engine/managers/event.js +410 -0
- package/dist/engine/managers/resize.d.ts +26 -0
- package/dist/engine/managers/resize.js +64 -0
- package/dist/engine/managers/snapline.d.ts +70 -0
- package/dist/engine/managers/snapline.js +124 -0
- package/dist/engine/managers/workspace.d.ts +29 -0
- package/dist/engine/managers/workspace.js +75 -0
- package/dist/engine/processors/image.d.ts +88 -0
- package/dist/engine/processors/image.js +473 -0
- package/dist/engine/processors/template.d.ts +45 -0
- package/dist/engine/processors/template.js +314 -0
- package/dist/engine/processors/text.d.ts +74 -0
- package/dist/engine/processors/text.js +215 -0
- package/dist/engine/semi-export-editor.d.ts +215 -0
- package/dist/engine/types.d.ts +28 -0
- package/dist/engine/utils/common.d.ts +25 -0
- package/dist/engine/utils/common.js +68 -0
- package/dist/engine/utils/dialog.d.ts +25 -0
- package/dist/engine/utils/font.d.ts +5 -0
- package/dist/engine/utils/font.js +39 -0
- package/dist/engine/utils/image.d.ts +8 -0
- package/dist/engine/utils/image.js +50 -0
- package/dist/engine/utils/loading.d.ts +17 -0
- package/dist/engine/utils/loading.js +71 -0
- package/dist/engine/utils/measure.d.ts +6 -0
- package/dist/engine/utils/measure.js +6 -0
- package/dist/engine/utils/mockup.d.ts +59 -0
- package/dist/engine/utils/setting.d.ts +4 -0
- package/dist/engine/utils/setting.js +73 -0
- package/dist/fabric-types.d.ts +59 -0
- package/dist/full-designer.js +13 -0
- package/dist/hooks/pagination.d.ts +19 -0
- package/dist/hooks/use-adobe-express.d.ts +50 -0
- package/dist/hooks/use-before-unload.d.ts +1 -0
- package/dist/hooks/use-image-drop.d.ts +18 -0
- package/dist/hooks/use-preview-assets.d.ts +2 -0
- package/dist/hooks/use-screen.d.ts +1 -0
- package/dist/i18n/index.d.ts +12 -0
- package/dist/images/design/asset_empty.png +0 -0
- package/dist/images/design/design/background.svg +3 -0
- package/dist/images/design/design/color-picker.svg +15 -0
- package/dist/images/design/design/computer.svg +1 -0
- package/dist/images/design/design/copy.svg +1 -0
- package/dist/images/design/design/image.svg +10 -0
- package/dist/images/design/design/line.svg +1 -0
- package/dist/images/design/design/text.svg +1 -0
- package/dist/images/design/design/title.svg +1 -0
- package/dist/images/design/empty.png +0 -0
- package/dist/images/design/layer_empty.png +0 -0
- package/dist/images/design/menu/ai.svg +1 -0
- package/dist/images/design/menu/back.svg +4 -0
- package/dist/images/design/menu/background.svg +6 -0
- package/dist/images/design/menu/clipart.svg +6 -0
- package/dist/images/design/menu/file.svg +4 -0
- package/dist/images/design/menu/fill.svg +1 -0
- package/dist/images/design/menu/image.svg +7 -0
- package/dist/images/design/menu/layer.svg +6 -0
- package/dist/images/design/menu/product.svg +3 -0
- package/dist/images/design/menu/sca.svg +5 -0
- package/dist/images/design/menu/shapes.svg +5 -0
- package/dist/images/design/menu/templates.svg +6 -0
- package/dist/images/design/menu/text.svg +6 -0
- package/dist/images/design/menu/uploads.svg +7 -0
- package/dist/images/design/spinner.svg +3 -0
- package/dist/images/design/spinners.svg +17 -0
- package/dist/images/design/transparent_pattern.svg +5 -0
- package/dist/index.d.ts +49 -0
- package/dist/index.js +156 -0
- package/dist/lib/analytics.d.ts +17 -0
- package/dist/lib/base-plate.d.ts +3 -0
- package/dist/lib/cn.d.ts +3 -0
- package/dist/lib/common.d.ts +16 -0
- package/dist/lib/config.d.ts +14 -0
- package/dist/lib/navigation.d.ts +2 -0
- package/dist/pixel-map-dSys7UAx.js +137 -0
- package/dist/renderer/ThreeDPreview.d.ts +14 -0
- package/dist/renderer/latest-task-queue.d.ts +17 -0
- package/dist/renderer/pixel-map.d.ts +37 -0
- package/dist/renderer/preview-asset-cache.d.ts +4 -0
- package/dist/renderer/render-layer-output.d.ts +5 -0
- package/dist/renderer/semi-resource-cache.d.ts +28 -0
- package/dist/renderer/sticker.d.ts +34 -0
- package/dist/renderer/sticker.js +1837 -0
- package/dist/renderer/three-d-preview.js +32 -0
- package/dist/semi-interact-editor-DfzphWy3.js +1409 -0
- package/dist/semi-renderer.d.ts +7 -0
- package/dist/semi-renderer.js +5 -0
- package/dist/state/designer-store.d.ts +43 -0
- package/dist/state/designer-store.js +8 -0
- package/dist/style.css +1 -0
- package/dist/types.d.ts +279 -0
- package/dist/ui/accordion.d.ts +7 -0
- package/dist/ui/button-group.d.ts +11 -0
- package/dist/ui/button.d.ts +10 -0
- package/dist/ui/checkbox.d.ts +4 -0
- package/dist/ui/command.d.ts +18 -0
- package/dist/ui/confirm-dialog.d.ts +15 -0
- package/dist/ui/context-menu.d.ts +25 -0
- package/dist/ui/dialog.d.ts +15 -0
- package/dist/ui/drawer.d.ts +15 -0
- package/dist/ui/editable-combobox.d.ts +11 -0
- package/dist/ui/hint.d.ts +8 -0
- package/dist/ui/image.d.ts +24 -0
- package/dist/ui/input-group.d.ts +16 -0
- package/dist/ui/input-with-addon.d.ts +17 -0
- package/dist/ui/input.d.ts +3 -0
- package/dist/ui/label.d.ts +4 -0
- package/dist/ui/loading-button.d.ts +15 -0
- package/dist/ui/popover.d.ts +9 -0
- package/dist/ui/scroll-area.d.ts +5 -0
- package/dist/ui/select.d.ts +22 -0
- package/dist/ui/separator.d.ts +4 -0
- package/dist/ui/shared-loading-button.d.ts +20 -0
- package/dist/ui/simple-dialog.d.ts +19 -0
- package/dist/ui/simple-popover.d.ts +13 -0
- package/dist/ui/simple-select.d.ts +20 -0
- package/dist/ui/skeleton.d.ts +2 -0
- package/dist/ui/slider.d.ts +4 -0
- package/dist/ui/spinner-box.d.ts +12 -0
- package/dist/ui/spinner.d.ts +2 -0
- package/dist/ui/switch.d.ts +6 -0
- package/dist/ui/tab/index.d.ts +15 -0
- package/dist/ui/textarea.d.ts +3 -0
- package/dist/ui/tooltip.d.ts +7 -0
- package/dist/workers/image-resize.worker.d.ts +1 -0
- package/dist/workers/mockup.worker.d.ts +5 -0
- package/dist/workers/pixel-map.worker.d.ts +1 -0
- package/dist/workers/render-asset-cache.d.ts +18 -0
- package/dist/workers/render.worker.d.ts +1 -0
- package/docs/HOST_DATA_CONTRACT.md +434 -0
- package/docs/INTEGRATION_API.md +547 -0
- package/docs/SEMI_RENDERER.md +141 -0
- package/docs/auth-api.md +3 -0
- package/package.json +199 -4
|
@@ -0,0 +1,434 @@
|
|
|
1
|
+
# 宿主数据接口契约
|
|
2
|
+
|
|
3
|
+
本文档描述 `@printine/pod-editor` 0.1.14 当前完整编辑器使用的宿主商品展示、设计恢复、底板和素材数据。接入步骤、适配器与保存流程见 [第三方接入文档](./INTEGRATION_API.md)。
|
|
4
|
+
|
|
5
|
+
## 1. 调用规则
|
|
6
|
+
|
|
7
|
+
底板由宿主直接传入;字体、图形、剪贴画可使用商家素材代理或宿主适配器。
|
|
8
|
+
|
|
9
|
+
| 数据 | 属性 | 默认服务域名 | 包内固定前缀 |
|
|
10
|
+
| --- | --- | --- | --- |
|
|
11
|
+
| 底板 | `basePlate`(必填) | 宿主提供完整对象,无 SDK 请求 | 无 |
|
|
12
|
+
| 字体、图形、剪贴画 | `assetBaseUrl` | 当前宿主页 origin | `/api/v1/editor/` |
|
|
13
|
+
| 预设色板 | `adapters.library.colors.list` | 宿主提供,无默认网络请求 | 无远端设置接口 |
|
|
14
|
+
|
|
15
|
+
`assetBaseUrl` 只传**服务域名**,例如 `https://shop.example.com/`。末尾是否带 `/` 都可以;不要把 `/api/v1/editor/` 拼入属性值,包会自行拼接。素材浏览器默认值为 `/`;服务端使用低层素材 client 时须提供绝对 origin。
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
<PrintineDesigner
|
|
19
|
+
productId="variant_123"
|
|
20
|
+
basePlate={basePlate}
|
|
21
|
+
assetBaseUrl="https://shop.example.com"
|
|
22
|
+
/>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
宿主先加载完整底板,再将对象直接传入 `basePlate`,不要传 `{ ret, data }` 等接口响应包装。底板未就绪时不要挂载编辑器。
|
|
26
|
+
|
|
27
|
+
商家素材代理接口的成功响应必须满足:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"success": true,
|
|
32
|
+
"data": []
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
所有供浏览器加载的图片、SVG、字体、2D 渲染图和 3D 文件 URL 都必须是可访问的完整 URL,并允许宿主页面跨域读取(至少返回正确的 `Access-Control-Allow-Origin`)。否则 Fabric/Pixi 无法导出或合成预览。
|
|
37
|
+
|
|
38
|
+
## 2. 宿主商品信息与已保存设计
|
|
39
|
+
|
|
40
|
+
### 商品展示:`productInfo`
|
|
41
|
+
|
|
42
|
+
当前 `<PrintineDesigner />` **不会自动请求商品详情**。宿主从自己的业务接口读取商品信息,再通过 `productInfo` 传入:
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
<PrintineDesigner
|
|
46
|
+
productId="variant_123"
|
|
47
|
+
basePlate={basePlate}
|
|
48
|
+
productInfo={{
|
|
49
|
+
title: 'Classic T-shirt',
|
|
50
|
+
imageUrl: 'https://cdn.example.com/product-cover.png',
|
|
51
|
+
price: 19.99,
|
|
52
|
+
currency: 'USD',
|
|
53
|
+
variantTitle: 'White / M',
|
|
54
|
+
}}
|
|
55
|
+
/>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| 字段 | 类型 | 说明 |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| `title` | `string \| null` | 商品名称 |
|
|
61
|
+
| `imageUrl` | `string \| null` | 完整商品图片 URL |
|
|
62
|
+
| `price` | `number \| string \| null` | 展示价格;数字 `0` 有效 |
|
|
63
|
+
| `currency` | `string \| null` | 币种,例如 `USD` |
|
|
64
|
+
| `variantTitle` | `string \| null` | 变体说明 |
|
|
65
|
+
|
|
66
|
+
以上字段均可选,仅影响展示。未传时不自动读取商品详情作为回退,全部为空时隐藏商品信息区。包不提供商品详情请求接口。
|
|
67
|
+
|
|
68
|
+
### 已保存设计:`initialDesignData`
|
|
69
|
+
|
|
70
|
+
宿主自行读取保存记录,把其 `design_data` 作为 `initialDesignData` 传入,半定制背景配置作为 `initialBackgroundCustomized` 单独传入。异步加载记录时,先使用 `loading={true}` 等待记录准备好,再初始化编辑器。
|
|
71
|
+
|
|
72
|
+
`initialDesignData` 的结构为 `Record<string, FabricCanvasState>`。键推荐使用底板 `areas[].name`,也兼容 `areas[].id` 的字符串形式。初始化数据不是受控画布状态;切换保存记录或底板时建议重新挂载组件。
|
|
73
|
+
|
|
74
|
+
`FabricCanvasState` 是 Fabric 序列化对象。包直接交给 Fabric 恢复,因此宿主应原样保存并返回包的 `onSave` 数据,不应自行删改对象字段。包直接依赖的最小结构如下:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
interface FabricCanvasState {
|
|
78
|
+
objects: FabricObject[];
|
|
79
|
+
/** 当前设计面选中的背景色;可省略。 */
|
|
80
|
+
color?: string;
|
|
81
|
+
/** 包导出时产生;用于不同画布尺寸下恢复对象比例。 */
|
|
82
|
+
workspaceMetadata?: {
|
|
83
|
+
width: number;
|
|
84
|
+
height: number;
|
|
85
|
+
centerX: number;
|
|
86
|
+
centerY: number;
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
interface FabricObject {
|
|
91
|
+
id?: string;
|
|
92
|
+
type: string;
|
|
93
|
+
selectable?: boolean;
|
|
94
|
+
/** 图片对象使用;建议与 src 一起完整保存。 */
|
|
95
|
+
src?: string;
|
|
96
|
+
originSrc?: string;
|
|
97
|
+
/** `semiDesignPermission` 场景下的元素半定制定义。 */
|
|
98
|
+
customConfig?: Record<string, unknown>;
|
|
99
|
+
/** 其余 Fabric 原生序列化字段,例如 left、top、scaleX、scaleY、angle、text、fill 等。 */
|
|
100
|
+
[key: string]: unknown;
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
interface SemiCustomBackground {
|
|
106
|
+
enable: boolean;
|
|
107
|
+
palette: boolean;
|
|
108
|
+
colors: string[];
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
说明:普通 `i-text`/`advanced-i-text` 对象必须保留 `text`;空文本对象会被包过滤。弧形文字对象的 `type`、`radius`、`spacing` 以及其他 Fabric 字段也必须原样保留。
|
|
113
|
+
|
|
114
|
+
## 3. 底板详情
|
|
115
|
+
|
|
116
|
+
### 必传的 `basePlate` 对象
|
|
117
|
+
|
|
118
|
+
底板数据完全由宿主加载,包内没有底板请求或默认服务地址。对象必须包含 `id` 和至少一个 `areas` 设计面;在编辑过程中保持对象引用稳定。
|
|
119
|
+
|
|
120
|
+
完整的 2D 底板对象示例:
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
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
|
|
169
|
+
},
|
|
170
|
+
"texture_transform": {
|
|
171
|
+
"blendMode": "normal"
|
|
172
|
+
}
|
|
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": []
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
通过 `basePlate` Props 传入时应使用包导出的 `BasePlate` 类型。无 2D/3D 预览时仍应提供空数组;兼容字段也应保留。
|
|
189
|
+
|
|
190
|
+
### `basePlate` 字段
|
|
191
|
+
|
|
192
|
+
| 字段 | 类型 | 必填 | 包内用途 |
|
|
193
|
+
| --- | --- | --- | --- |
|
|
194
|
+
| `id` | `string \| number` | 是 | 底板标识;预览参数使用,宿主保存时可自行补充。 |
|
|
195
|
+
| `areas` | `Mockup[]` | 是 | 设计面列表;第一项作为初始设计面。 |
|
|
196
|
+
| `renders` | `Render[]` | 是 | 2D 实时预览。无 2D 预览可传 `[]`。 |
|
|
197
|
+
| `td_renders` | `TDRender[]` | 是 | 3D 实时预览。无 3D 预览可传 `[]`。若同时提供,包优先展示 3D。 |
|
|
198
|
+
|
|
199
|
+
包目前不读取 `colors`、`preview_img01`、`preview_img02`、`custom_color`、`custom_shape`、`render_list` 等其他底板字段。
|
|
200
|
+
|
|
201
|
+
### 设计面:`Mockup`
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
interface Mockup {
|
|
205
|
+
id: string | number;
|
|
206
|
+
/** 唯一、稳定的设计面键;用于 areas、design_data 和 render area 的关联。 */
|
|
207
|
+
name: string;
|
|
208
|
+
/** 面向用户展示的名称(例如 Front);不传时展示 name。 */
|
|
209
|
+
display_name?: string;
|
|
210
|
+
/** SVG 叠层图。其 id="bg" 的元素会被当作可绘制区域的裁剪形状。 */
|
|
211
|
+
image: string;
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`width`、`height` 可以额外返回,但当前包不读取它们。`areas[].name` 必须与保存的 `design_data` 键、`renders[].render_areas[].area.name` 对应;`display_name` 只用于设计面提示和图片替代文本。
|
|
216
|
+
|
|
217
|
+
### 2D 渲染:`Render` 与 `RenderArea`
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
interface Render {
|
|
221
|
+
id: number;
|
|
222
|
+
render_areas: RenderArea[];
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
interface RenderArea {
|
|
226
|
+
id: number;
|
|
227
|
+
name: string;
|
|
228
|
+
/** 图层或遮罩的资源 URL。 */
|
|
229
|
+
image: string;
|
|
230
|
+
/** 1 表示设计图层;0 表示固定图层。 */
|
|
231
|
+
design: 0 | 1;
|
|
232
|
+
width: number;
|
|
233
|
+
height: number;
|
|
234
|
+
x: number;
|
|
235
|
+
y: number;
|
|
236
|
+
/** 可用于贴图的基础纹理 URL;不需要时传空字符串。 */
|
|
237
|
+
texture: string;
|
|
238
|
+
/** 必须对应某个 areas[].name。 */
|
|
239
|
+
area?: { name: string };
|
|
240
|
+
texture_transform?: Record<string, unknown>;
|
|
241
|
+
export?: {
|
|
242
|
+
blend: string;
|
|
243
|
+
opacity: number;
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
对于实时 2D 合成,`image`、`texture`、坐标尺寸和 `area.name` 都应返回。`name === "bg"` 的 `image` 也会在合成尚未完成时作为预览回退图。
|
|
249
|
+
|
|
250
|
+
### 3D 渲染:`TDRender` 与 `TDRenderArea`
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
interface TDRender {
|
|
254
|
+
id: number;
|
|
255
|
+
/** 3D 模型资源 URL。 */
|
|
256
|
+
image: string;
|
|
257
|
+
render3_d_areas: TDRenderArea[];
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
interface TDRenderArea {
|
|
261
|
+
/** 对应 areas[].id;包用它找到该设计面的生成纹理。 */
|
|
262
|
+
base_plate_area_id: string | number;
|
|
263
|
+
/** 3D 模型中的材质或网格名称。 */
|
|
264
|
+
name: string;
|
|
265
|
+
/** 1 时才会替换对应材质。 */
|
|
266
|
+
render_replace: 0 | 1;
|
|
267
|
+
/** 初始材质纹理 URL。 */
|
|
268
|
+
texture: string;
|
|
269
|
+
texture_transform: Record<string, unknown>;
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## 4. 2D 服务端渲染
|
|
274
|
+
|
|
275
|
+
包不再直接请求固定渲染接口。宿主可通过顶层 `onRenderPreview(input)` 接收下列数据,使用自身的任意渲染接口并返回预览图片 URL 数组。该回调只在用户打开 **2D 全屏预览**、且包没有可直接使用的实时预览图片时调用;它不用于编辑器右侧的实时 2D 预览,也不用于 3D 预览。
|
|
276
|
+
|
|
277
|
+
回调参数由包生成:
|
|
278
|
+
|
|
279
|
+
```json
|
|
280
|
+
{
|
|
281
|
+
"base_plate_id": 456,
|
|
282
|
+
"mask": {
|
|
283
|
+
"color": "",
|
|
284
|
+
"opacity": 0
|
|
285
|
+
},
|
|
286
|
+
"design_data": {
|
|
287
|
+
"front": {
|
|
288
|
+
"objects": [],
|
|
289
|
+
"color": "#FFFFFF",
|
|
290
|
+
"workspaceMetadata": {
|
|
291
|
+
"width": 900,
|
|
292
|
+
"height": 1200,
|
|
293
|
+
"centerX": 450,
|
|
294
|
+
"centerY": 600
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
| 字段 | 类型 | 说明 |
|
|
302
|
+
| --- | --- | --- |
|
|
303
|
+
| `base_plate_id` | `string \| number` | 当前底板的 `data.id`。 |
|
|
304
|
+
| `mask.color` | `string` | 默认背景遮罩色;当前商品展示属性不设置默认背景色,通常为空字符串。设计面颜色在 `design_data` 中。 |
|
|
305
|
+
| `mask.opacity` | `0 \| 1` | 有背景色时为 `1`,否则为 `0`。 |
|
|
306
|
+
| `design_data` | `Record<string, FabricCanvasState>` | 当前全部设计面的 Fabric JSON,结构见“已保存设计”。包会先将本地 blob 图片上传为宿主返回的完整 URL,再发起该请求。 |
|
|
307
|
+
|
|
308
|
+
宿主回调成功时**直接返回字符串数组**,不返回接口包装对象:
|
|
309
|
+
|
|
310
|
+
```ts
|
|
311
|
+
// onRenderPreview 的返回值
|
|
312
|
+
return [
|
|
313
|
+
'https://cdn.example.com/rendered/front.png',
|
|
314
|
+
'https://cdn.example.com/rendered/back.png',
|
|
315
|
+
];
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
如果宿主渲染接口返回 `{ ret: true, data: [...] }`,宿主应先校验 HTTP/业务成功,再返回其中的 `data`。包按数组顺序显示可切换的效果图,每项必须是浏览器可访问的完整图片 URL。
|
|
319
|
+
|
|
320
|
+
## 5. 商家素材代理和宿主色板
|
|
321
|
+
|
|
322
|
+
这些接口通过商家后端代理调用 Printine Gateway,包只附带同源会话,不持有长期 App Key。`assetBaseUrl` 不传时使用当前宿主页 origin。列表和文件均使用 `/api/v1/editor/*`,没有旧路径兼容、旧素材域回退或第二层 editor 前缀。商家须校验编辑访问、使用带 `assets:read` 的后端 Key,并把列表中的文件 URL 映射到受保护的商家代理,保留后缀及 `v`。
|
|
323
|
+
|
|
324
|
+
### `GET /api/v1/editor/fonts`
|
|
325
|
+
|
|
326
|
+
页面初始化时请求,用于文字菜单与恢复已保存文字时的字体加载。
|
|
327
|
+
|
|
328
|
+
```json
|
|
329
|
+
{
|
|
330
|
+
"success": true,
|
|
331
|
+
"data": [
|
|
332
|
+
{
|
|
333
|
+
"name": "Poppins",
|
|
334
|
+
"variants": [
|
|
335
|
+
{
|
|
336
|
+
"weight": 400,
|
|
337
|
+
"style": "normal",
|
|
338
|
+
"url": "https://cdn.example.com/fonts/poppins-400.woff2"
|
|
339
|
+
},
|
|
340
|
+
{
|
|
341
|
+
"weight": 700,
|
|
342
|
+
"style": "italic",
|
|
343
|
+
"url": "https://cdn.example.com/fonts/poppins-700-italic.woff2"
|
|
344
|
+
}
|
|
345
|
+
]
|
|
346
|
+
}
|
|
347
|
+
]
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
| 字段 | 类型 | 必填 |
|
|
352
|
+
| --- | --- | --- |
|
|
353
|
+
| `name` | `string` | 是 |
|
|
354
|
+
| `variants[].weight` | `number` | 是 |
|
|
355
|
+
| `variants[].style` | `"normal" \| "italic"` | 是 |
|
|
356
|
+
| `variants[].url` | `string` | 是 |
|
|
357
|
+
|
|
358
|
+
没有有效 `name` 或 `url` 的字体/字重会被忽略。
|
|
359
|
+
|
|
360
|
+
### 宿主可选的预设色板
|
|
361
|
+
|
|
362
|
+
色板不是 Gateway 素材接口。初始化时只有明确提供 `adapters.library.colors.list` 才调用宿主 loader;未提供时不发请求,显示空预设列表,普通自选颜色能力保持可用。
|
|
363
|
+
|
|
364
|
+
```ts
|
|
365
|
+
adapters: {
|
|
366
|
+
library: {
|
|
367
|
+
colors: { list: async () => ["#FFFFFF", "#111827", "#E11D48"] },
|
|
368
|
+
},
|
|
369
|
+
}
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
宿主返回真实配置的字符串颜色数组;不支持用设置路由兜底。loader 失败时清空预设列表,旧会话的迟到结果不会覆盖新的色板或已卸载状态。
|
|
373
|
+
|
|
374
|
+
### `GET /api/v1/editor/shapes?page=:page&limit=:limit`
|
|
375
|
+
|
|
376
|
+
首次打开 Shapes Tab 时请求。包将其自己的分页参数 `size` 转成接口参数 `limit`,默认 `page=1`、`limit=30`。
|
|
377
|
+
|
|
378
|
+
```json
|
|
379
|
+
{
|
|
380
|
+
"success": true,
|
|
381
|
+
"data": [
|
|
382
|
+
{
|
|
383
|
+
"id": "shape_001",
|
|
384
|
+
"name": "Circle",
|
|
385
|
+
"asset_url": "https://cdn.example.com/shapes/circle.svg"
|
|
386
|
+
}
|
|
387
|
+
],
|
|
388
|
+
"pagination": {
|
|
389
|
+
"page": 1,
|
|
390
|
+
"total_pages": 3,
|
|
391
|
+
"total": 63
|
|
392
|
+
}
|
|
393
|
+
}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
| 字段 | 类型 | 必填 | 包内用途 |
|
|
397
|
+
| --- | --- | --- | --- |
|
|
398
|
+
| `data[].id` | `string` | 是 | 列表 key。 |
|
|
399
|
+
| `data[].asset_url` | `string` | 是 | Shape SVG 的展示与插入画布。 |
|
|
400
|
+
| `pagination.page` | `number` | 否 | 分页状态。 |
|
|
401
|
+
| `pagination.total_pages` | `number` | 否 | 是否还有下一页。 |
|
|
402
|
+
| `pagination.total` | `number` | 否 | 总数。 |
|
|
403
|
+
|
|
404
|
+
### `GET /api/v1/editor/clipart-categories`
|
|
405
|
+
|
|
406
|
+
首次打开 Clipart Tab 时请求。该接口一次返回分类与分类内剪贴画,包不会再逐个请求分类详情。
|
|
407
|
+
|
|
408
|
+
```json
|
|
409
|
+
{
|
|
410
|
+
"success": true,
|
|
411
|
+
"data": [
|
|
412
|
+
{
|
|
413
|
+
"id": "animals",
|
|
414
|
+
"name": "Animals",
|
|
415
|
+
"cliparts": [
|
|
416
|
+
{
|
|
417
|
+
"id": "clipart_cat",
|
|
418
|
+
"name": "Cat",
|
|
419
|
+
"asset_url": "https://cdn.example.com/cliparts/cat.svg"
|
|
420
|
+
}
|
|
421
|
+
]
|
|
422
|
+
}
|
|
423
|
+
]
|
|
424
|
+
}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
| 字段 | 类型 | 必填 | 包内用途 |
|
|
428
|
+
| --- | --- | --- | --- |
|
|
429
|
+
| `data[].id` | `string` | 是 | 分类 key。 |
|
|
430
|
+
| `data[].name` | `string` | 否 | 分类标题。 |
|
|
431
|
+
| `data[].cliparts` | `array` | 否 | 分类下素材;省略时按空数组处理。 |
|
|
432
|
+
| `cliparts[].id` | `string` | 是 | 素材 key。 |
|
|
433
|
+
| `cliparts[].asset_url` | `string` | 是 | 素材展示与插入画布。 |
|
|
434
|
+
| `cliparts[].name` | `string` | 否 | 插入对象名称与图片 `alt`。 |
|