@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.22
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/LICENSE +202 -0
- package/NOTICE +9 -0
- package/README.md +48 -2
- package/package.json +145 -4
- package/src/action-designer.ts +267 -0
- package/src/attachment-open.ts +574 -0
- package/src/attachment-url.ts +235 -0
- package/src/auth/index.ts +6 -0
- package/src/auth/qrcode.ts +519 -0
- package/src/auth/types.ts +261 -0
- package/src/display-style.ts +532 -0
- package/src/editor-frame.ts +625 -0
- package/src/editor-session.ts +1214 -0
- package/src/editor-testing.ts +838 -0
- package/src/editor.ts +1720 -0
- package/src/frame-transport.ts +516 -0
- package/src/frontend-routes.ts +99 -0
- package/src/hooks.ts +48 -0
- package/src/host-caps.ts +93 -0
- package/src/i18n.ts +238 -0
- package/src/im-panel.ts +132 -0
- package/src/image-tools.ts +91 -0
- package/src/index.ts +125 -0
- package/src/interactive-session.ts +94 -0
- package/src/nahida-im.ts +391 -0
- package/src/nahida-ws.ts +23 -0
- package/src/org-directory.ts +78 -0
- package/src/oz-realtime.ts +144 -0
- package/src/page.ts +591 -0
- package/src/print.ts +393 -0
- package/src/surface.ts +310 -0
- package/src/theme-mocks.ts +140 -0
- package/src/theme.ts +125 -0
- package/src/ui-fixtures/attachment.ts +24 -0
- package/src/ui-fixtures/confirm.ts +16 -0
- package/src/ui-fixtures/entity-picker.ts +24 -0
- package/src/ui-fixtures/expression-editor.ts +52 -0
- package/src/ui-fixtures/image-cropper.ts +23 -0
- package/src/ui-fixtures/index.ts +17 -0
- package/src/ui-fixtures/org-tri-picker.ts +19 -0
- package/src/ui-fixtures/prompt.ts +19 -0
- package/src/ui-fixtures/record-picker.ts +17 -0
- package/src/ui-fixtures/template-picker.ts +13 -0
- package/src/ui-mocks.ts +264 -0
- package/src/ui.ts +491 -0
- package/src/workflow-designer.ts +475 -0
package/src/surface.ts
ADDED
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
// 通用 surface 类型契约——插件前端通过 definePluginSurface 声明挂载工厂。
|
|
2
|
+
// 宿主按 surfaceType 精确命中并调用;editor 插件可同时导出 createEditor(旧)+ createSurface(新),
|
|
3
|
+
// 宿主优先调用 createSurface,缺失时降级 createEditor(向后兼容)。
|
|
4
|
+
//
|
|
5
|
+
// 挂载档:同一份 createSurface 在两种档下都能用——同源档由宿主直接调用;
|
|
6
|
+
// 沙箱档(第三方插件一律如此)由 definePluginSurface 自动启动框架运行时(frame-transport.ts)在 iframe 里调用。
|
|
7
|
+
|
|
8
|
+
import { isKimpoFrameContext, registerFrameSurfaceFactory } from './frame-transport';
|
|
9
|
+
|
|
10
|
+
/** 平台支持的挂载点类型枚举(前后端对齐,见 Go SurfaceDecl.Type)。 */
|
|
11
|
+
export type SurfaceType =
|
|
12
|
+
| 'designer'
|
|
13
|
+
| 'runtime'
|
|
14
|
+
| 'action-config'
|
|
15
|
+
| 'login-form'
|
|
16
|
+
| 'page-slot'
|
|
17
|
+
| 'config-form'
|
|
18
|
+
// 流程引擎目前只有 'workflow-designer' 这一个设计器 surface(页面级挂载点)。早期版本的
|
|
19
|
+
// 'workflow-binding-config' / 'workflow-form-runtime' / 'workflow-task-center' /
|
|
20
|
+
// 'workflow-task-detail-actions' / 'workflow-progress' / 'workflow-admin' 等挂载点已移除,
|
|
21
|
+
// 填报态与任务中心由宿主自身承担。
|
|
22
|
+
| 'workflow-designer'
|
|
23
|
+
// IM 前端(消息引擎前端插件)悬浮窗容器。宿主经 resolvePluginSurfaces
|
|
24
|
+
// 命中并挂载,窗口显隐由宿主 v-show 控制(不销毁组件、不断 WS)。
|
|
25
|
+
| 'im-panel'
|
|
26
|
+
// 动作设计器整面 surface:宿主在模板设计器与定时任务设计里挂载(契约见 action-designer.ts)。
|
|
27
|
+
| 'action-designer'
|
|
28
|
+
// KimpoAI 产品对话面悬浮窗容器:宿主经 resolvePluginSurfaces 按 priority 最高单提供者
|
|
29
|
+
// 命中并挂在页面根级,窗口显隐由宿主单例控制(同 im-panel 范式)。
|
|
30
|
+
| 'kimpoai-panel'
|
|
31
|
+
// 附件插件(1.1.0-tp.21 起):宿主附件外壳按 manifest capabilities.attachment_open.accepts 路由并挂载,
|
|
32
|
+
// 组件以 prop `ctx: AttachmentOpenContext` 收上下文(契约见 attachment-open.ts)。1.1.0-tp.22 起沙箱档也支持。
|
|
33
|
+
| 'attachment.open';
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* surface 挂载档(manifest capabilities.frontend.surfaces[].mount)。
|
|
37
|
+
* - `iframe`:沙箱档,第三方插件的缺省与唯一选择;
|
|
38
|
+
* - `same-origin`:同源档,只允许官方签名包;第三方包声明它会在安装检查时被阻断
|
|
39
|
+
* (blocked_reason = third_party_same_origin_mount)。
|
|
40
|
+
*/
|
|
41
|
+
export type SurfaceMount = 'iframe' | 'same-origin';
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* 本阶段支持沙箱档的 surface(与宿主 plugin.IframeMountSupported 同口径):page-slot 的 template.records / auth.login、
|
|
45
|
+
* action-config、print-mode(打印方案 B 档隐藏框架),1.1.0-tp.5 起的 im-panel(IM 浮窗)与 action-designer(动作设计器),
|
|
46
|
+
* 1.1.0-tp.14 起的编辑器 designer / runtime(入口见 './editor-frame' 的 defineEditorSurface,需支持编辑器解耦的宿主),
|
|
47
|
+
* 以及 1.1.0-tp.22 起的附件插件 attachment.open(跨帧桥见 './attachment-open',需同阶段宿主)。
|
|
48
|
+
* 流程设计器(workflow-designer)尚不支持。
|
|
49
|
+
*/
|
|
50
|
+
export function isIframeMountSupported(surfaceType: string, slot?: string): boolean {
|
|
51
|
+
if (
|
|
52
|
+
surfaceType === 'action-config' ||
|
|
53
|
+
surfaceType === 'im-panel' ||
|
|
54
|
+
surfaceType === 'action-designer' ||
|
|
55
|
+
// 打印方案 B 档的隐藏框架(与 Go plugin.IframeMountSupported、宿主同口径)。
|
|
56
|
+
surfaceType === 'print-mode' ||
|
|
57
|
+
surfaceType === 'designer' ||
|
|
58
|
+
surfaceType === 'runtime' ||
|
|
59
|
+
// 附件插件:宿主附件外壳在沙箱档经跨帧桥下发 ctx。
|
|
60
|
+
surfaceType === 'attachment.open'
|
|
61
|
+
) {
|
|
62
|
+
return true;
|
|
63
|
+
}
|
|
64
|
+
return surfaceType === 'page-slot' && (slot === 'template.records' || slot === 'auth.login');
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* 插件自检:第三方包的 surfaces 不得声明 same-origin,且沙箱档只能用于已支持的 surface。
|
|
69
|
+
* 返回错误说明列表(空数组即通过);宿主安装检查是权威实现。
|
|
70
|
+
*/
|
|
71
|
+
export function validateSurfaceMounts(
|
|
72
|
+
surfaces: ReadonlyArray<{ type?: string; slot?: string; mount?: string }>,
|
|
73
|
+
options: { official?: boolean } = {}
|
|
74
|
+
): string[] {
|
|
75
|
+
const errors: string[] = [];
|
|
76
|
+
surfaces.forEach((surface, i) => {
|
|
77
|
+
const mount = surface.mount ?? '';
|
|
78
|
+
if (mount !== '' && mount !== 'iframe' && mount !== 'same-origin') {
|
|
79
|
+
errors.push(`surfaces[${i}].mount "${mount}" must be "iframe" or "same-origin"`);
|
|
80
|
+
return;
|
|
81
|
+
}
|
|
82
|
+
const effective = options.official ? (mount === 'iframe' ? 'iframe' : 'same-origin') : 'iframe';
|
|
83
|
+
if (!options.official && mount === 'same-origin') {
|
|
84
|
+
errors.push(`surfaces[${i}]: third-party packages must not declare mount "same-origin" (inspect blocks it)`);
|
|
85
|
+
}
|
|
86
|
+
if (effective === 'iframe' && !isIframeMountSupported(String(surface.type ?? ''), surface.slot)) {
|
|
87
|
+
errors.push(`surfaces[${i}]: surface "${surface.type ?? ''}${surface.slot ? `:${surface.slot}` : ''}" is not supported in the iframe mount yet`);
|
|
88
|
+
}
|
|
89
|
+
});
|
|
90
|
+
return errors;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
// ── 前端域自检(frontend.surface 加载期校验)──
|
|
94
|
+
//
|
|
95
|
+
// 三道闸同表同码的第三道:沙箱框架里宿主在 init 时随 input 下发宿主前端域代际表(hostSchemaGenerations),
|
|
96
|
+
// definePluginSurface 在调用插件工厂前比对「本 SDK 构建对齐的代际」,不满足即抛错,由框架运行时回 mount-error
|
|
97
|
+
// (复用沙箱框架已有的 mount-error 消息类型)。需求表与宿主安装闸、宿主前端加载闸同口径,改一处须同步三处。
|
|
98
|
+
|
|
99
|
+
/** 本 SDK 对齐的 frontend.surface 代际。 */
|
|
100
|
+
export const FRONTEND_SURFACE_GENERATION = 1;
|
|
101
|
+
/** 本 SDK 对齐的 frontend.interactive-session 代际。 */
|
|
102
|
+
export const FRONTEND_INTERACTIVE_SESSION_GENERATION = 1;
|
|
103
|
+
|
|
104
|
+
/** 加载期错误码(与宿主同名)。 */
|
|
105
|
+
export const SURFACE_DOMAIN_MISSING = 'plugin_surface_domain_missing';
|
|
106
|
+
export const SURFACE_DOMAIN_TOO_NEW = 'plugin_surface_domain_too_new';
|
|
107
|
+
export const SURFACE_DOMAIN_TOO_OLD = 'plugin_surface_domain_too_old';
|
|
108
|
+
|
|
109
|
+
/** 宿主下发的单个域代际(线上形态,与宿主活跃插件元数据 host_schema_generations 一致)。 */
|
|
110
|
+
export interface HostSchemaGenerationWire {
|
|
111
|
+
current: number;
|
|
112
|
+
min_supported: number;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** 会话型 surface(另需 frontend.interactive-session)。 */
|
|
116
|
+
const INTERACTIVE_SESSION_SURFACE_TYPES = new Set(['designer', 'runtime', 'action-designer', 'action-config', 'workflow-designer']);
|
|
117
|
+
|
|
118
|
+
/** 某 surface 类型必需的前端域及本 SDK 对齐的代际。 */
|
|
119
|
+
export function requiredSurfaceDomainGenerations(surfaceType: string): Record<string, number> {
|
|
120
|
+
const out: Record<string, number> = { 'frontend.surface': FRONTEND_SURFACE_GENERATION };
|
|
121
|
+
if (INTERACTIVE_SESSION_SURFACE_TYPES.has(surfaceType)) {
|
|
122
|
+
out['frontend.interactive-session'] = FRONTEND_INTERACTIVE_SESSION_GENERATION;
|
|
123
|
+
}
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** 域自检失败(code 为上面三个错误码之一)。 */
|
|
128
|
+
export class SurfaceDomainCheckError extends Error {
|
|
129
|
+
code: string;
|
|
130
|
+
constructor(code: string, message: string) {
|
|
131
|
+
super(`${code}: ${message}`);
|
|
132
|
+
this.name = 'SurfaceDomainCheckError';
|
|
133
|
+
this.code = code;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* 比对宿主下发的代际表:返回 null 表示通过,否则返回错误。
|
|
139
|
+
* 宿主未下发代际表(undefined,不支持前端域闸的旧宿主)时不判定——这类宿主自身也不做域闸,SDK 无从比对。
|
|
140
|
+
*/
|
|
141
|
+
export function checkHostSurfaceGenerations(
|
|
142
|
+
surfaceType: string,
|
|
143
|
+
hostGenerations: Record<string, HostSchemaGenerationWire> | undefined,
|
|
144
|
+
/** 本 SDK 对齐的代际(缺省按需求表;测试注入点)。 */
|
|
145
|
+
sdkGenerations: Record<string, number> = requiredSurfaceDomainGenerations(surfaceType)
|
|
146
|
+
): SurfaceDomainCheckError | null {
|
|
147
|
+
if (hostGenerations === undefined) return null;
|
|
148
|
+
for (const [domain, sdkGeneration] of Object.entries(sdkGenerations)) {
|
|
149
|
+
const host = hostGenerations?.[domain];
|
|
150
|
+
const current = Number(host?.current);
|
|
151
|
+
if (!host || !Number.isInteger(current) || current < 1) {
|
|
152
|
+
return new SurfaceDomainCheckError(SURFACE_DOMAIN_MISSING, `host does not provide ${domain} (surface=${surfaceType})`);
|
|
153
|
+
}
|
|
154
|
+
if (sdkGeneration > current) {
|
|
155
|
+
return new SurfaceDomainCheckError(
|
|
156
|
+
SURFACE_DOMAIN_TOO_NEW,
|
|
157
|
+
`${domain} sdk=${sdkGeneration} host_current=${current} (surface=${surfaceType}); upgrade the host`
|
|
158
|
+
);
|
|
159
|
+
}
|
|
160
|
+
const minSupported = Number(host.min_supported);
|
|
161
|
+
if (Number.isInteger(minSupported) && minSupported > 0 && sdkGeneration < minSupported) {
|
|
162
|
+
return new SurfaceDomainCheckError(
|
|
163
|
+
SURFACE_DOMAIN_TOO_OLD,
|
|
164
|
+
`${domain} sdk=${sdkGeneration} host_min_supported=${minSupported} (surface=${surfaceType}); rebuild with a newer SDK`
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* 按数据动作种类回落的 action-config 绑定前缀(`bind: "operation_kind:<kind>"`)。
|
|
173
|
+
* 动作设计器先找 `bind == 动作名` 的面板,找不到且动作带 `operation_kind` 时再找本前缀的面板。
|
|
174
|
+
* **只对官方保留命名空间插件生效**(官方标准取数 / 写配置面板据此服务所有同种类动作),第三方声明时宿主忽略、
|
|
175
|
+
* manifest 预检告警;第三方数据动作不需要也不能自带取数 / 写配置面板。
|
|
176
|
+
*/
|
|
177
|
+
export const OPERATION_KIND_BIND_PREFIX = 'operation_kind:';
|
|
178
|
+
|
|
179
|
+
/** 宿主调用 createSurface 时传入的上下文。 */
|
|
180
|
+
export interface SurfaceCreateInput {
|
|
181
|
+
/** 本次挂载的 surface 类型。 */
|
|
182
|
+
surfaceType: SurfaceType;
|
|
183
|
+
/** action-config 类 surface 的绑定标识:动作名,或官方面板的 `operation_kind:<kind>`(见 OPERATION_KIND_BIND_PREFIX)。 */
|
|
184
|
+
bind?: string;
|
|
185
|
+
/** 多槽 surface 的槽标识。 */
|
|
186
|
+
slot?: string;
|
|
187
|
+
/**
|
|
188
|
+
* 宿主按白名单裁剪后注入的宿主能力键列表(surface manifest 声明的 host_caps 与宿主白名单取交集)。
|
|
189
|
+
* 插件仅能使用此列表内的能力,宿主不保证列表外的键存在于 hostBridge 上。
|
|
190
|
+
*/
|
|
191
|
+
hostCaps: string[];
|
|
192
|
+
/** 宿主透传的上下文(DesignerHostContext 等,插件端按实际类型断言)。 */
|
|
193
|
+
hostContext: unknown;
|
|
194
|
+
/** 宿主运行时实例上下文(仅 editor 类 surface 有效)。 */
|
|
195
|
+
runtime: unknown;
|
|
196
|
+
/** 宿主建议的初始 props(不含插件自行计算的 props)。 */
|
|
197
|
+
props: Record<string, unknown>;
|
|
198
|
+
/**
|
|
199
|
+
* 宿主桥接对象(与 EditorHostBridge 同结构,但类型为 unknown 避免反向依赖)。
|
|
200
|
+
* 其上的 `theme`(宿主设计数值)常驻可见:不需要在 hostCaps 声明,
|
|
201
|
+
* 读取请用 `readHostTheme(hostBridge)`(from './theme'),老宿主缺失时得 null。
|
|
202
|
+
*/
|
|
203
|
+
hostBridge: unknown;
|
|
204
|
+
/**
|
|
205
|
+
* 宿主前端域代际表(沙箱档由宿主在 init 时下发;同源档宿主可不传)。
|
|
206
|
+
* definePluginSurface 在框架里据此自检,插件一般无需读取。
|
|
207
|
+
*/
|
|
208
|
+
hostSchemaGenerations?: Record<string, HostSchemaGenerationWire>;
|
|
209
|
+
/**
|
|
210
|
+
* 插件前端入口所在目录的地址(以 / 结尾,如 `/api/v1/plugins/<id>/assets/frontend/`),随包资源
|
|
211
|
+
* (pdf.js 的 CMap / 字体 / wasm、按需加载的引擎包等)按相对路径拼在它后面取用,见 resolvePluginAssetUrl。
|
|
212
|
+
* 宿主以已验证字节经 blob: 地址执行插件包,插件里 document.currentScript.src 取不到真实地址,所以由宿主显式给出;
|
|
213
|
+
* 老宿主缺此键时插件可退回自身脚本地址(只在本地调试页有效)。
|
|
214
|
+
*/
|
|
215
|
+
assetBaseUrl?: string;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* 把随包资源的相对路径拼到宿主给的 assetBaseUrl 上。
|
|
220
|
+
* 取不到可用基地址(老宿主缺键、不是 http(s))或相对路径非法(空、绝对、含 ..)时返回空串,由调用方决定退路。
|
|
221
|
+
*/
|
|
222
|
+
export function resolvePluginAssetUrl(input: Pick<SurfaceCreateInput, 'assetBaseUrl'> | null | undefined, relativePath: string): string {
|
|
223
|
+
const base = input?.assetBaseUrl?.trim() ?? '';
|
|
224
|
+
const rel = relativePath.trim();
|
|
225
|
+
if (!base || !rel || rel.startsWith('/') || rel.split('/').includes('..') || /^[a-z][a-z0-9+.-]*:/i.test(rel)) return '';
|
|
226
|
+
try {
|
|
227
|
+
const url = new URL(rel, base.endsWith('/') ? base : `${base}/`);
|
|
228
|
+
return url.protocol === 'http:' || url.protocol === 'https:' ? url.href : '';
|
|
229
|
+
} catch {
|
|
230
|
+
return '';
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** createSurface 工厂的返回值,宿主据此挂载 Vue 组件。 */
|
|
235
|
+
export interface SurfaceMountResult {
|
|
236
|
+
/** 要渲染的 Vue 组件(宿主通过 markRaw + <component :is> 挂载)。 */
|
|
237
|
+
component: unknown;
|
|
238
|
+
/** 额外的 props 覆盖(合并在 input.props 之后)。 */
|
|
239
|
+
props?: Record<string, unknown>;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* 给挂载工厂包一层前端域自检(definePluginSurface 在沙箱框架里自动使用;不走 definePluginSurface 的 bundle 可手动包)。
|
|
244
|
+
* 自检不通过时抛 SurfaceDomainCheckError,由框架运行时转成 mount-error。
|
|
245
|
+
*/
|
|
246
|
+
export function withSurfaceDomainCheck<T extends SurfaceCreateInput>(
|
|
247
|
+
factory: (input: T) => SurfaceMountResult
|
|
248
|
+
): (input: T) => SurfaceMountResult {
|
|
249
|
+
return (input: T): SurfaceMountResult => {
|
|
250
|
+
const error = checkHostSurfaceGenerations(String(input?.surfaceType ?? ''), input?.hostSchemaGenerations);
|
|
251
|
+
if (error) throw error;
|
|
252
|
+
return factory(input);
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* definePluginSurface —— 声明挂载工厂,给插件作者提供类型推导。
|
|
258
|
+
* 同源档里是 identity;在宿主沙箱框架里还会登记工厂并启动框架运行时,
|
|
259
|
+
* 插件作者无需感知两种挂载档的差异(见 frame-transport.ts 顶部说明)。
|
|
260
|
+
*
|
|
261
|
+
* @example
|
|
262
|
+
* ```ts
|
|
263
|
+
* export const createSurface = definePluginSurface((input) => {
|
|
264
|
+
* return { component: MyConfigPanel, props: { bind: input.bind } };
|
|
265
|
+
* });
|
|
266
|
+
* ```
|
|
267
|
+
*/
|
|
268
|
+
export function definePluginSurface<T extends SurfaceCreateInput>(
|
|
269
|
+
factory: (input: T) => SurfaceMountResult
|
|
270
|
+
): (input: T) => SurfaceMountResult {
|
|
271
|
+
if (isKimpoFrameContext()) {
|
|
272
|
+
// 沙箱框架里先做前端域自检:不满足即抛错,框架运行时据此回 mount-error,插件工厂不会被调用。
|
|
273
|
+
const guarded = withSurfaceDomainCheck(factory);
|
|
274
|
+
registerFrameSurfaceFactory(guarded as unknown as (input: SurfaceCreateInput) => SurfaceMountResult);
|
|
275
|
+
return guarded;
|
|
276
|
+
}
|
|
277
|
+
return factory;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* 动作配置面板(surfaceType='action-config')的通用参数契约。
|
|
282
|
+
*
|
|
283
|
+
* 宿主动作设计器在用户编辑一个**非取数/写动作**的节点时,若该动作名有插件声明的 action-config
|
|
284
|
+
* surface(`bind` = 动作名),挂载组件并以组件 prop `input` 传入 `ActionConfigSurfaceInput`:
|
|
285
|
+
* - `input.props.params`:当前节点的动作参数对象(副本);
|
|
286
|
+
* - `input.props.onUpdateParams(next)`:整体回写参数(宿主随后按动作的 params_schema 与插件
|
|
287
|
+
* ValidateParams 在保存时校验,面板不必自己保存);
|
|
288
|
+
* - `input.props.readonly`:只读打开时为 true,面板应禁用编辑;
|
|
289
|
+
* - `input.props.paramsSchema`:动作在 GetActions 中声明的参数 schema,便于面板渲染默认值。
|
|
290
|
+
*
|
|
291
|
+
* 取数 / 写动作(params_schema 顶层 `x-editor` 为 `extract-v4` / `write-v4`)走宿主内置的表达式
|
|
292
|
+
* 配置面,props 为另一套 V4 表达式模型(modelValue / onUpdateModel),不在本契约范围。
|
|
293
|
+
*/
|
|
294
|
+
export interface ActionConfigSurfaceProps {
|
|
295
|
+
params: Record<string, unknown>;
|
|
296
|
+
onUpdateParams(next: Record<string, unknown>): void;
|
|
297
|
+
readonly: boolean;
|
|
298
|
+
paramsSchema?: Record<string, unknown>;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/** action-config 面板组件收到的 `input` prop。 */
|
|
302
|
+
export interface ActionConfigSurfaceInput {
|
|
303
|
+
surfaceType: 'action-config';
|
|
304
|
+
/** 绑定的动作名(与 GetActions 中的动作 name 一致)。 */
|
|
305
|
+
bind?: string;
|
|
306
|
+
hostContext: { appId: string; templateId: string; actionName: string };
|
|
307
|
+
props: ActionConfigSurfaceProps;
|
|
308
|
+
/** 按 manifest host_caps 裁剪后的宿主桥(含 log / i18n 等)。 */
|
|
309
|
+
hostBridge: Record<string, unknown>;
|
|
310
|
+
}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
// theme-mocks.ts —— 宿主 theme 能力的 mock 工厂,供插件在自己的 playground / 单测里
|
|
2
|
+
// 不启动宿主也能验证「读主题 → 订阅变化 → 重绘」这条链路。
|
|
3
|
+
//
|
|
4
|
+
// 组织风格与 ui-mocks.ts 一致:扁平文件、"theme-" 前缀 = 领域名、不含任何真实网络 / DOM。
|
|
5
|
+
// 【重要】本文件里的数值全部是明显的测试值,**仅测试用,非宿主真实数值**——
|
|
6
|
+
// 它们不得被业务代码当作回退值引用(设计数值唯一出处是宿主主题)。
|
|
7
|
+
import type { HostTheme, HostThemeTokens, RGB } from './theme';
|
|
8
|
+
|
|
9
|
+
/** 可手动触发变化的 mock 主题:在 HostTheme 之上附带测试辅助方法。 */
|
|
10
|
+
export interface MockHostTheme extends HostTheme {
|
|
11
|
+
/** 切换明暗:换出对应测试色板,version +1 并通知订阅者。 */
|
|
12
|
+
setScheme(scheme: 'light' | 'dark'): void;
|
|
13
|
+
/** 局部覆盖 tokens(浅合并到各分组):version +1 并通知订阅者。 */
|
|
14
|
+
update(patch: MockHostThemeTokensPatch): void;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** update / overrides 可传的 tokens 局部补丁(每个分组可只写部分键)。 */
|
|
18
|
+
export type MockHostThemeTokensPatch = {
|
|
19
|
+
[K in keyof HostThemeTokens]?: HostThemeTokens[K] extends object ? Partial<HostThemeTokens[K]> : HostThemeTokens[K];
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
/** createMockHostTheme 的入参。 */
|
|
23
|
+
export interface MockHostThemeOptions {
|
|
24
|
+
/** 初始明暗,缺省 light。 */
|
|
25
|
+
scheme?: 'light' | 'dark';
|
|
26
|
+
/** 初始 tokens 局部覆盖。 */
|
|
27
|
+
tokens?: MockHostThemeTokensPatch;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
// 以下为测试占位值(仅测试用,非宿主真实数值):用易辨认的整数,便于断言。
|
|
31
|
+
const TEST_GRAY = (n: number): RGB => [n, n, n];
|
|
32
|
+
const TEST_PALETTE_KEYS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'] as const;
|
|
33
|
+
|
|
34
|
+
/** 生成某一明暗下的测试 tokens(仅测试用,非宿主真实数值)。 */
|
|
35
|
+
function buildTestTokens(scheme: 'light' | 'dark'): HostThemeTokens {
|
|
36
|
+
const dark = scheme === 'dark';
|
|
37
|
+
const palette = {} as HostThemeTokens['color']['primaryPalette'];
|
|
38
|
+
TEST_PALETTE_KEYS.forEach((key, i) => {
|
|
39
|
+
palette[key] = [10 + i, 20 + i, 30 + i];
|
|
40
|
+
});
|
|
41
|
+
return {
|
|
42
|
+
color: {
|
|
43
|
+
primary: [1, 2, 3],
|
|
44
|
+
info: [4, 5, 6],
|
|
45
|
+
success: [7, 8, 9],
|
|
46
|
+
warning: [10, 11, 12],
|
|
47
|
+
error: [13, 14, 15],
|
|
48
|
+
onPrimary: [250, 250, 250],
|
|
49
|
+
primaryPalette: palette,
|
|
50
|
+
container: TEST_GRAY(dark ? 20 : 240),
|
|
51
|
+
layout: TEST_GRAY(dark ? 10 : 230),
|
|
52
|
+
inverted: TEST_GRAY(dark ? 230 : 10),
|
|
53
|
+
text: TEST_GRAY(dark ? 220 : 30),
|
|
54
|
+
textSecondary: TEST_GRAY(dark ? 180 : 70),
|
|
55
|
+
textHint: TEST_GRAY(dark ? 140 : 110),
|
|
56
|
+
fill: TEST_GRAY(dark ? 60 : 200),
|
|
57
|
+
fillLightest: TEST_GRAY(dark ? 40 : 220),
|
|
58
|
+
fillLight: TEST_GRAY(dark ? 50 : 210),
|
|
59
|
+
fillLighter: TEST_GRAY(dark ? 45 : 215),
|
|
60
|
+
border: TEST_GRAY(dark ? 70 : 190),
|
|
61
|
+
borderLight: TEST_GRAY(dark ? 65 : 195),
|
|
62
|
+
borderLighter: TEST_GRAY(dark ? 55 : 205),
|
|
63
|
+
borderDark: TEST_GRAY(dark ? 90 : 170),
|
|
64
|
+
borderDeep: TEST_GRAY(dark ? 100 : 160),
|
|
65
|
+
borderLightest: TEST_GRAY(dark ? 35 : 225)
|
|
66
|
+
},
|
|
67
|
+
radius: { control: 1, card: 2, block: 3, pill: 99 },
|
|
68
|
+
control: {
|
|
69
|
+
height: { small: 21, medium: 22, large: 23 },
|
|
70
|
+
fontSize: { small: 11, medium: 12, large: 13 }
|
|
71
|
+
},
|
|
72
|
+
fontSize: { mini: 1, caption: 2, body: 3, subtitle: 4, title: 5, display: 6 },
|
|
73
|
+
space: { 1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6 },
|
|
74
|
+
shadow: { popup: 'test-popup', dialog: `test-dialog-${scheme}`, drawer: `test-drawer-${scheme}` },
|
|
75
|
+
z: { shell: 1, dropdown: 2, dialog: 3, guide: 4, message: 5 },
|
|
76
|
+
fontFamily: 'test-font',
|
|
77
|
+
uiScale: 1
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** 把补丁浅合并到 tokens 的各分组上,返回新对象(不改入参)。 */
|
|
82
|
+
function applyPatch(base: HostThemeTokens, patch: MockHostThemeTokensPatch | undefined): HostThemeTokens {
|
|
83
|
+
if (!patch) return base;
|
|
84
|
+
const next: Record<string, unknown> = { ...base };
|
|
85
|
+
for (const key of Object.keys(patch) as (keyof HostThemeTokens)[]) {
|
|
86
|
+
const value = patch[key];
|
|
87
|
+
if (value === undefined) continue;
|
|
88
|
+
const current = base[key];
|
|
89
|
+
next[key] = typeof current === 'object' && current !== null ? { ...current, ...(value as object) } : value;
|
|
90
|
+
}
|
|
91
|
+
return next as unknown as HostThemeTokens;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* createMockHostTheme —— 造一个可手动触发变化的 HostTheme。
|
|
96
|
+
*
|
|
97
|
+
* 返回对象的 scheme / version / tokens 是 getter,始终反映最新状态;setScheme / update 会让
|
|
98
|
+
* version +1 并同步通知全部订阅者;subscribe 返回的取消函数可重复调用。
|
|
99
|
+
* 用法:`createMockHostTheme({ scheme: 'dark' })`,再放进 `{ theme }` 作为 hostBridge 传给被测插件。
|
|
100
|
+
*/
|
|
101
|
+
export function createMockHostTheme(options: MockHostThemeOptions = {}): MockHostTheme {
|
|
102
|
+
let scheme: 'light' | 'dark' = options.scheme ?? 'light';
|
|
103
|
+
let version = 1;
|
|
104
|
+
let tokens = applyPatch(buildTestTokens(scheme), options.tokens);
|
|
105
|
+
const listeners = new Set<(theme: HostTheme) => void>();
|
|
106
|
+
|
|
107
|
+
const notify = (): void => {
|
|
108
|
+
version += 1;
|
|
109
|
+
// 复制一份再遍历,避免回调里取消订阅影响本轮遍历
|
|
110
|
+
for (const cb of [...listeners]) cb(theme);
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
const theme: MockHostTheme = {
|
|
114
|
+
get scheme() {
|
|
115
|
+
return scheme;
|
|
116
|
+
},
|
|
117
|
+
get version() {
|
|
118
|
+
return version;
|
|
119
|
+
},
|
|
120
|
+
get tokens() {
|
|
121
|
+
return tokens;
|
|
122
|
+
},
|
|
123
|
+
subscribe(cb) {
|
|
124
|
+
listeners.add(cb);
|
|
125
|
+
return () => {
|
|
126
|
+
listeners.delete(cb);
|
|
127
|
+
};
|
|
128
|
+
},
|
|
129
|
+
setScheme(next) {
|
|
130
|
+
scheme = next;
|
|
131
|
+
tokens = buildTestTokens(next);
|
|
132
|
+
notify();
|
|
133
|
+
},
|
|
134
|
+
update(patch) {
|
|
135
|
+
tokens = applyPatch(tokens, patch);
|
|
136
|
+
notify();
|
|
137
|
+
}
|
|
138
|
+
};
|
|
139
|
+
return theme;
|
|
140
|
+
}
|
package/src/theme.ts
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
// theme.ts —— 宿主设计数值(theme 能力)的 SDK 契约面:只有类型与读取函数,没有任何数值常量。
|
|
2
|
+
//
|
|
3
|
+
// 约定:
|
|
4
|
+
// - 数值唯一出处是宿主主题(宿主设计系统预设 + 用户主题色 + 明暗 + 界面缩放),由宿主经
|
|
5
|
+
// hostBridge.theme 以只读方式提供;写样式的地方优先用宿主 CSS 变量,读不到 CSS 的地方
|
|
6
|
+
// (画布、X6 等非 CSS 渲染面)才读本能力并订阅变化重绘。
|
|
7
|
+
// - SDK 不得放置设计数值常量——本包经 `file:` 拷贝打进各插件包后,常量会随宿主改版
|
|
8
|
+
// 而过期;缺少 theme 能力的老宿主由插件自行使用自己的回退值(readHostTheme 返回 null)。
|
|
9
|
+
// - tokens 为纯数据;subscribe 的回调是插件自己的函数,不跨边界传给宿主序列化。
|
|
10
|
+
//
|
|
11
|
+
// 下列类型与宿主前端的设计数值类型保持一致(逐字段同形),两边改动须同步。
|
|
12
|
+
|
|
13
|
+
/** 颜色三元组 [r, g, b],每个分量 0-255;使用方经 toCss 转成 CSS 颜色字符串。 */
|
|
14
|
+
export type RGB = readonly [number, number, number];
|
|
15
|
+
|
|
16
|
+
/** 主色色阶的 11 个档位键。 */
|
|
17
|
+
export type HostThemePaletteKey = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | '950';
|
|
18
|
+
|
|
19
|
+
/** 宿主设计数值快照(随明暗、主题色、界面缩放变化;每次变化宿主会换出新的快照并递增 version)。 */
|
|
20
|
+
export interface HostThemeTokens {
|
|
21
|
+
color: {
|
|
22
|
+
primary: RGB;
|
|
23
|
+
info: RGB;
|
|
24
|
+
success: RGB;
|
|
25
|
+
warning: RGB;
|
|
26
|
+
error: RGB;
|
|
27
|
+
/** 主色之上的文字色。 */
|
|
28
|
+
onPrimary: RGB;
|
|
29
|
+
/** 主色色阶 50~950。 */
|
|
30
|
+
primaryPalette: Record<HostThemePaletteKey, RGB>;
|
|
31
|
+
container: RGB;
|
|
32
|
+
layout: RGB;
|
|
33
|
+
inverted: RGB;
|
|
34
|
+
text: RGB;
|
|
35
|
+
textSecondary: RGB;
|
|
36
|
+
textHint: RGB;
|
|
37
|
+
fill: RGB;
|
|
38
|
+
fillLightest: RGB;
|
|
39
|
+
fillLight: RGB;
|
|
40
|
+
fillLighter: RGB;
|
|
41
|
+
border: RGB;
|
|
42
|
+
borderLight: RGB;
|
|
43
|
+
borderLighter: RGB;
|
|
44
|
+
borderDark: RGB;
|
|
45
|
+
borderDeep: RGB;
|
|
46
|
+
borderLightest: RGB;
|
|
47
|
+
};
|
|
48
|
+
/** 圆角,单位 px。 */
|
|
49
|
+
radius: { control: number; card: number; block: number; pill: number };
|
|
50
|
+
/** 控件高度与字号(按 small / medium / large 三档),单位 px。 */
|
|
51
|
+
control: {
|
|
52
|
+
height: { small: number; medium: number; large: number };
|
|
53
|
+
fontSize: { small: number; medium: number; large: number };
|
|
54
|
+
};
|
|
55
|
+
/** 文字字号,单位 px,已乘界面缩放。 */
|
|
56
|
+
fontSize: { mini: number; caption: number; body: number; subtitle: number; title: number; display: number };
|
|
57
|
+
/** 间距档,单位 px。 */
|
|
58
|
+
space: { 1: number; 2: number; 3: number; 4: number; 5: number; 6: number };
|
|
59
|
+
/** 阴影(CSS box-shadow 字符串,随明暗变化)。 */
|
|
60
|
+
shadow: { popup: string; dialog: string; drawer: string };
|
|
61
|
+
/** 静态层级(动态弹层由宿主层级栈分配)。 */
|
|
62
|
+
z: { shell: number; dropdown: number; dialog: number; guide: number; message: number };
|
|
63
|
+
/** 宿主字体栈。 */
|
|
64
|
+
fontFamily: string;
|
|
65
|
+
/** 界面缩放系数。 */
|
|
66
|
+
uiScale: number;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* HostTheme —— 宿主在 hostBridge.theme 上提供的只读主题能力。
|
|
71
|
+
* 常驻可见:不需要在 manifest 声明,也不受 hostCaps 裁剪。
|
|
72
|
+
*/
|
|
73
|
+
export interface HostTheme {
|
|
74
|
+
/** 当前明暗。 */
|
|
75
|
+
readonly scheme: 'light' | 'dark';
|
|
76
|
+
/** 每次变化(明暗 / 主题色 / 缩放)递增,便于画布类渲染面做缓存失效判断。 */
|
|
77
|
+
readonly version: number;
|
|
78
|
+
/** 当前设计数值快照。 */
|
|
79
|
+
readonly tokens: HostThemeTokens;
|
|
80
|
+
/** 订阅变化;回调收到变化后的主题,返回取消订阅函数(插件卸载时必须调用,防泄漏)。 */
|
|
81
|
+
subscribe(cb: (theme: HostTheme) => void): () => void;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** 判断是否为 [r,g,b] 三个有限数。 */
|
|
85
|
+
function isRgb(value: unknown): value is RGB {
|
|
86
|
+
return Array.isArray(value) && value.length === 3 && value.every((n) => typeof n === 'number' && Number.isFinite(n));
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* readHostTheme —— 从 hostBridge 读取 theme 能力。
|
|
91
|
+
*
|
|
92
|
+
* 缺少 theme 能力(老宿主)、bridge 不是对象、或 theme 形状不合法时返回 null,绝不抛错;
|
|
93
|
+
* 插件在拿到 null 时用自己的回退值。只做必要的形状校验(scheme / version / tokens 主干 /
|
|
94
|
+
* subscribe),不逐字段深校验——深层缺失属宿主实现缺陷,不在此兜底。
|
|
95
|
+
*/
|
|
96
|
+
export function readHostTheme(bridge: unknown): HostTheme | null {
|
|
97
|
+
try {
|
|
98
|
+
if (bridge === null || typeof bridge !== 'object') return null;
|
|
99
|
+
const candidate = (bridge as { theme?: unknown }).theme;
|
|
100
|
+
if (candidate === null || typeof candidate !== 'object') return null;
|
|
101
|
+
const theme = candidate as Partial<HostTheme>;
|
|
102
|
+
if (theme.scheme !== 'light' && theme.scheme !== 'dark') return null;
|
|
103
|
+
if (typeof theme.version !== 'number' || !Number.isFinite(theme.version)) return null;
|
|
104
|
+
if (typeof theme.subscribe !== 'function') return null;
|
|
105
|
+
const tokens = theme.tokens as HostThemeTokens | undefined;
|
|
106
|
+
if (tokens === null || typeof tokens !== 'object') return null;
|
|
107
|
+
if (tokens.color === null || typeof tokens.color !== 'object' || !isRgb(tokens.color.primary)) return null;
|
|
108
|
+
for (const key of ['radius', 'control', 'fontSize', 'space', 'shadow', 'z'] as const) {
|
|
109
|
+
if (tokens[key] === null || typeof tokens[key] !== 'object') return null;
|
|
110
|
+
}
|
|
111
|
+
return theme as HostTheme;
|
|
112
|
+
} catch {
|
|
113
|
+
// 被裁剪 Proxy 或异常 getter 抛错时同样视为「没有该能力」
|
|
114
|
+
return null;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* toCss —— 把 RGB 三元组转成 CSS 颜色字符串(空格语法,与宿主 `rgb(var(--x) / α)` 写法一致)。
|
|
120
|
+
* 不传 alpha 得 `rgb(r g b)`,传入得 `rgb(r g b / a)`。
|
|
121
|
+
*/
|
|
122
|
+
export function toCss(rgb: RGB, alpha?: number): string {
|
|
123
|
+
const [r, g, b] = rgb;
|
|
124
|
+
return alpha === undefined ? `rgb(${r} ${g} ${b})` : `rgb(${r} ${g} ${b} / ${alpha})`;
|
|
125
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// 附件打开服务(attachment)的请求/结果夹具。
|
|
2
|
+
import type { OpenAttachmentRequest, OpenAttachmentResult } from '../attachment-open';
|
|
3
|
+
|
|
4
|
+
/** 典型请求:同一附件字段的两条条目,从第一条打开,带修改态单据上下文。 */
|
|
5
|
+
export const uiAttachmentRequestFixture: OpenAttachmentRequest = {
|
|
6
|
+
items: [
|
|
7
|
+
{ assetId: 'ast_fixture_contract', name: '合同.pdf', contentType: 'application/pdf', byteSize: 102400 },
|
|
8
|
+
{ assetId: 'ast_fixture_notes', name: '说明.txt', contentType: 'text/plain', byteSize: 2048 }
|
|
9
|
+
],
|
|
10
|
+
index: 0,
|
|
11
|
+
recordContext: {
|
|
12
|
+
appId: 'app_fixture',
|
|
13
|
+
templateId: 'tpl_fixture',
|
|
14
|
+
dataTableId: 'tbl_fixture_main',
|
|
15
|
+
fieldId: 'fld_fixture_attachment',
|
|
16
|
+
recordId: 'rec_fixture_1',
|
|
17
|
+
formMode: 'edit'
|
|
18
|
+
}
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
/** 对应的结果夹具:用户在本次打开期间保存过一次编辑。 */
|
|
22
|
+
export const uiAttachmentResultFixture: OpenAttachmentResult = {
|
|
23
|
+
edited: true
|
|
24
|
+
};
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// 确认框服务(confirm)的请求/结果夹具。
|
|
2
|
+
import type { OpenConfirmRequest, OpenConfirmResult } from '../ui';
|
|
3
|
+
|
|
4
|
+
/** 典型请求:删除类不可恢复操作,用 error 档并带换行正文。 */
|
|
5
|
+
export const uiConfirmRequestFixture: OpenConfirmRequest = {
|
|
6
|
+
title: '删除确认',
|
|
7
|
+
content: '确定删除该条记录吗?\n删除后不可恢复。',
|
|
8
|
+
type: 'error',
|
|
9
|
+
positiveText: '删除',
|
|
10
|
+
negativeText: '再想想'
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
/** 与上面请求对应的一份"用户点了确认"结果夹具。 */
|
|
14
|
+
export const uiConfirmResultFixture: OpenConfirmResult = {
|
|
15
|
+
confirmed: true
|
|
16
|
+
};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// 通讯录选人器服务(entityPicker)的请求/结果夹具。
|
|
2
|
+
//
|
|
3
|
+
// EntityPickerKind 支持 'user' 与 'dept',OpenEntityPickerResult 为 {confirmed, users, depts} 两数组
|
|
4
|
+
// 形态。本夹具只示范 'user' 档(典型消费方流程引擎只选人不选部门),depts
|
|
5
|
+
// 恒为空数组——与"未选的那档恒为空"的类型注释口径一致。
|
|
6
|
+
import type { OpenEntityPickerRequest, OpenEntityPickerResult } from '../ui';
|
|
7
|
+
|
|
8
|
+
/** 典型请求:多选、限 10 人。 */
|
|
9
|
+
export const uiEntityPickerRequestFixture: OpenEntityPickerRequest = {
|
|
10
|
+
kinds: ['user'],
|
|
11
|
+
multiple: true,
|
|
12
|
+
max: 10,
|
|
13
|
+
title: '选择通知对象'
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
/** 与上面请求对应的一份"用户已确认,选中两人"结果夹具。 */
|
|
17
|
+
export const uiEntityPickerResultFixture: OpenEntityPickerResult = {
|
|
18
|
+
confirmed: true,
|
|
19
|
+
users: [
|
|
20
|
+
{ user_id: 'fixture-user-1', login_name: 'fixture.user1', display_name: '夹具用户一', status_code: 'active' },
|
|
21
|
+
{ user_id: 'fixture-user-2', login_name: 'fixture.user2', display_name: '夹具用户二', status_code: 'active' }
|
|
22
|
+
],
|
|
23
|
+
depts: []
|
|
24
|
+
};
|