@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
|
@@ -0,0 +1,574 @@
|
|
|
1
|
+
// attachment-open.ts —— 附件插件(surface `attachment.open`)前端契约(SDK 1.1.0-tp.21 起)。
|
|
2
|
+
//
|
|
3
|
+
// 链路:kimpo 宿主 · 填报态(新增 / 修改 / 查看历史单据)与历史记录页、宿主内置记录列表打开一个附件 →
|
|
4
|
+
// 宿主按 manifest `capabilities.attachment_open.accepts` 路由到插件(同类型多个插件时让用户选「打开方式」)→
|
|
5
|
+
// 宿主打开外壳、叠水印 → 挂载插件的 `attachment.open` surface,把 AttachmentOpenContext 作为组件 prop `ctx` 传入。
|
|
6
|
+
//
|
|
7
|
+
// 职责边界(务必遵守):
|
|
8
|
+
// - 宿主管:路由与打开方式、权限判定与下发、编辑锁、下载(插件拿不到下载地址)、水印、保存后经表单数据权威层
|
|
9
|
+
// 改附件字段值、日志汇总;
|
|
10
|
+
// - 插件管:显示与编辑。插件不碰字段值、不写编辑器、绕不过权限 / 锁 / 下载 / 水印;`permissions` 只用来决定
|
|
11
|
+
// 按钮显隐,真正的裁决在宿主后端,保存时宿主重判。
|
|
12
|
+
//
|
|
13
|
+
// 本文件只有类型与纯函数,SDK 不 import 宿主代码。
|
|
14
|
+
//
|
|
15
|
+
// 两种挂载档写法一致(SDK 1.1.0-tp.22 起沙箱档开放):
|
|
16
|
+
// - 同源档(官方签名包):宿主直接把 AttachmentOpenContext 作为 prop `ctx` 传入,函数同步可调(返回 Promise 的照旧);
|
|
17
|
+
// - 沙箱档(iframe,第三方插件一律如此):宿主把 ctx 换成跨帧线上形状 {@link AttachmentOpenFrameBridge} 经 MessageChannel
|
|
18
|
+
// 下发,defineAttachmentOpenSurface 在调用插件工厂前用 {@link createAttachmentOpenFrameContext} 还原成同形的
|
|
19
|
+
// AttachmentOpenContext——readSource 的字节以 ArrayBuffer 结构化克隆传递、beginEdit / save / end 经消息往返、
|
|
20
|
+
// onSaveRequest / onModeChange / onSourceChanged 由宿主经回调句柄下发。插件代码不用区分两档;差异只有:
|
|
21
|
+
// setDirty / setStatus / log 在沙箱档是发完即忘(不等宿主确认),`ctx.mode` 在沙箱档由 onModeChange 事件维护。
|
|
22
|
+
// 框架内没有网络(CSP connect-src 'none'),随包资源(resolvePluginAssetUrl)在沙箱档只能以 <script> / 新窗口链接
|
|
23
|
+
// 方式使用,不能 fetch;需要字节的资源请打进 bundle 或经 readSource 取。
|
|
24
|
+
//
|
|
25
|
+
// @example 最小附件插件(只读查看 + 可选编辑;完整工程见 SDK 脚手架 templates/attachment)
|
|
26
|
+
// ```ts
|
|
27
|
+
// // src/index.ts
|
|
28
|
+
// import { defineAttachmentOpenSurface } from '@kimposoft/plugin-sdk/attachment-open';
|
|
29
|
+
// import { resolvePluginAssetUrl } from '@kimposoft/plugin-sdk/surface';
|
|
30
|
+
// import NotesStage from './NotesStage.vue';
|
|
31
|
+
// export const createSurface = defineAttachmentOpenSurface(input => ({
|
|
32
|
+
// component: NotesStage,
|
|
33
|
+
// // 随包资源基地址由宿主给出;老宿主缺键时得空串,组件按「无示例资源」处理
|
|
34
|
+
// props: { hostBridge: input.hostBridge, sampleUrl: resolvePluginAssetUrl(input, 'assets/sample.svg') }
|
|
35
|
+
// }));
|
|
36
|
+
//
|
|
37
|
+
// // NotesStage.vue <script setup>(节选)
|
|
38
|
+
// const props = defineProps<{ ctx: AttachmentOpenContext }>();
|
|
39
|
+
// const { bytes } = await props.ctx.readSource({ maxBytes: 2 * 1024 * 1024 }); // 读原文件(宿主「查看」通道)
|
|
40
|
+
// text.value = new TextDecoder().decode(bytes);
|
|
41
|
+
// props.ctx.onModeChange(async mode => { // 外壳「编辑」/「结束编辑」
|
|
42
|
+
// if (mode !== 'edit') return;
|
|
43
|
+
// session = await props.ctx.beginEdit(); // 取附件编辑锁(EDIT_LOCKED 时 reject)
|
|
44
|
+
// offSave = props.ctx.onSaveRequest(async () => { // 外壳标题栏「保存」回到插件
|
|
45
|
+
// await session.save(new Blob([text.value], { type: 'text/plain' })); // 宿主存新附件并经表单数据权威层写回字段
|
|
46
|
+
// props.ctx.setDirty(false);
|
|
47
|
+
// return true;
|
|
48
|
+
// });
|
|
49
|
+
// });
|
|
50
|
+
// ```
|
|
51
|
+
|
|
52
|
+
import type { SurfaceCreateInput, SurfaceMountResult } from './surface';
|
|
53
|
+
import { definePluginSurface } from './surface';
|
|
54
|
+
|
|
55
|
+
/** 本契约的 surface 类型字面量(与 SurfaceType 闭集、Go SurfaceDecl.Type 对齐)。 */
|
|
56
|
+
export const ATTACHMENT_OPEN_SURFACE_TYPE = 'attachment.open' as const;
|
|
57
|
+
|
|
58
|
+
/** manifest 里声明块的键名:capabilities.attachment_open。 */
|
|
59
|
+
export const ATTACHMENT_OPEN_CAPABILITY_KEY = 'attachment_open' as const;
|
|
60
|
+
|
|
61
|
+
/** 打开模式:查看 / 编辑。插件在 manifest `modes` 里声明支持哪些;宿主只会以插件声明过的模式挂载。 */
|
|
62
|
+
export type AttachmentOpenMode = 'view' | 'edit';
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* manifest `capabilities.attachment_open.accepts`:插件能处理的附件类型。
|
|
66
|
+
* mime 允许 `type/subtype` 或 `type/*`;ext 为不带点的小写扩展名。宿主匹配规则见 matchesAttachmentOpenAccepts。
|
|
67
|
+
*/
|
|
68
|
+
export interface AttachmentOpenAccepts {
|
|
69
|
+
mime?: string[];
|
|
70
|
+
ext?: string[];
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** manifest `capabilities.attachment_open` 声明块(宿主 Go AttachmentOpenDecl 与 manifestlint 同形)。 */
|
|
74
|
+
export interface AttachmentOpenDecl {
|
|
75
|
+
accepts: AttachmentOpenAccepts;
|
|
76
|
+
/** 缺省 ['view']。 */
|
|
77
|
+
modes?: AttachmentOpenMode[];
|
|
78
|
+
/** 同类型多个插件时的列表排序与默认项(数字越小越靠前);**不**用来自动决定用谁,用谁由用户选。缺省 100。 */
|
|
79
|
+
priority?: number;
|
|
80
|
+
/** 原文件可读上限(字节),超过时 readSource 拒绝、外壳提示「文件过大」。缺省由宿主定。 */
|
|
81
|
+
max_source_bytes?: number;
|
|
82
|
+
/** 单次保存上限(字节);宿主另有附件硬上限,取两者较小。缺省由宿主定。 */
|
|
83
|
+
max_save_bytes?: number;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** 一条附件(与 attachment-url.ts 的 AttachmentItem 同源,这里要求四项齐全)。 */
|
|
87
|
+
export interface AttachmentOpenItem {
|
|
88
|
+
/** 资产标识:`ast_…`(附件资产)或 `img_…`(图片资产)。 */
|
|
89
|
+
assetId: string;
|
|
90
|
+
name: string;
|
|
91
|
+
contentType: string;
|
|
92
|
+
byteSize: number;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** 填报态表单模式(与宿主 FormMode 同口径):查看历史单据 = 'view',一律不可编辑。 */
|
|
96
|
+
export type AttachmentRecordFormMode = 'create' | 'edit' | 'view';
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* 附件所在的单据与字段定位。调用方(表格编辑器、历史记录页等)经 ui.openAttachment 传入,
|
|
100
|
+
* 宿主据此算编辑权限、找单据编辑租约、保存后写回字段值。缺席时宿主按「只读、无单据上下文」处理。
|
|
101
|
+
*/
|
|
102
|
+
export interface AttachmentRecordContext {
|
|
103
|
+
appId: string;
|
|
104
|
+
templateId: string;
|
|
105
|
+
dataTableId: string;
|
|
106
|
+
fieldId: string;
|
|
107
|
+
/** 新增单据尚无单据 ID 时为 null。 */
|
|
108
|
+
recordId: string | null;
|
|
109
|
+
/** 明细表行键;主表附件缺省。 */
|
|
110
|
+
rowKey?: string;
|
|
111
|
+
/**
|
|
112
|
+
* 明细表行序(0 起,按表单当前显示顺序):调用方拿不到表单数据行键时传它,宿主经表单会话反解成行键。
|
|
113
|
+
* 与 rowKey 同时给时以 rowKey 为准;主表附件缺省。
|
|
114
|
+
*/
|
|
115
|
+
rowOrdinal?: number;
|
|
116
|
+
formMode: AttachmentRecordFormMode;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** 不能编辑的原因(宿主算好下发,插件可据此给出更具体的提示文案;不要求插件处理)。 */
|
|
120
|
+
export type AttachmentEditDeniedReason =
|
|
121
|
+
/** 授权未开「在线编辑」(缺省不允许)。 */
|
|
122
|
+
| 'no_permission'
|
|
123
|
+
/** 字段隐藏 / 只读,或流程节点把字段置为只读。 */
|
|
124
|
+
| 'readonly_field'
|
|
125
|
+
/** 单据被锁定(手动 / 自动 / 流程锁)或编辑租约不在本会话。 */
|
|
126
|
+
| 'record_locked'
|
|
127
|
+
/** 查看历史单据(formMode=view)或没有单据上下文。 */
|
|
128
|
+
| 'view_mode'
|
|
129
|
+
/** 当前插件没有声明 edit 模式。 */
|
|
130
|
+
| 'plugin_view_only'
|
|
131
|
+
/** 文件超过保存上限。 */
|
|
132
|
+
| 'too_large';
|
|
133
|
+
|
|
134
|
+
/** 宿主算好的权限位。canView 恒为 true:没有查看权限的附件宿主根本不会挂载插件。 */
|
|
135
|
+
export interface AttachmentOpenPermissions {
|
|
136
|
+
canView: true;
|
|
137
|
+
canDownload: boolean;
|
|
138
|
+
canEdit: boolean;
|
|
139
|
+
editDeniedReason?: AttachmentEditDeniedReason;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** 环境:语言、主题与用户时区(时间显示一律按它折算;宿主存的是 UTC)。 */
|
|
143
|
+
export interface AttachmentOpenEnv {
|
|
144
|
+
locale: string;
|
|
145
|
+
theme: 'light' | 'dark';
|
|
146
|
+
timezone: string;
|
|
147
|
+
/** 当前用户显示名(与宿主水印署名同源):文档插件批注 / 修订署名用;老宿主缺键时插件自定回落。 */
|
|
148
|
+
userDisplayName?: string;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
export interface AttachmentSourceReadOptions {
|
|
152
|
+
/** 只读前 maxBytes 字节(文本类大文件截断显示);缺省读全部,超过声明的 max_source_bytes 则拒绝。 */
|
|
153
|
+
maxBytes?: number;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export interface AttachmentSourceReadResult {
|
|
157
|
+
bytes: ArrayBuffer;
|
|
158
|
+
contentType: string;
|
|
159
|
+
/** true 表示因 maxBytes 被截断(截断点可能落在多字节字符中间,由插件解码时处理)。 */
|
|
160
|
+
truncated: boolean;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** 插件向宿主报告的显示状态;外壳据此显示加载 / 错误提示,不影响插件自己的界面。 */
|
|
164
|
+
export interface AttachmentOpenStatus {
|
|
165
|
+
state: 'loading' | 'ready' | 'error';
|
|
166
|
+
message?: string;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export type AttachmentOpenLogLevel = 'info' | 'warn' | 'error';
|
|
170
|
+
|
|
171
|
+
/** 编辑锁被占用时宿主回传的占用者信息(时间为 UTC ISO 字符串,显示时按 env.timezone 折算)。 */
|
|
172
|
+
export interface AttachmentEditLockHolder {
|
|
173
|
+
displayName: string;
|
|
174
|
+
since: string;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** 本契约所有 reject 的错误码(error.code)。 */
|
|
178
|
+
export type AttachmentOpenErrorCode =
|
|
179
|
+
/** 编辑锁被他人(或同一用户的另一个窗口)占用;error.data.lockedBy 有占用者。 */
|
|
180
|
+
| 'EDIT_LOCKED'
|
|
181
|
+
/** 编辑期间失去锁(超时、管理员释放、单据租约失效);保存被拒,插件应保留未保存内容。 */
|
|
182
|
+
| 'EDIT_LOCK_LOST'
|
|
183
|
+
/** 无编辑权限(宿主重判不通过)。 */
|
|
184
|
+
| 'EDIT_FORBIDDEN'
|
|
185
|
+
/** 保存内容超过上限。 */
|
|
186
|
+
| 'SAVE_TOO_LARGE'
|
|
187
|
+
/** 保存内容的类型不在字段允许范围内。 */
|
|
188
|
+
| 'SAVE_TYPE_NOT_ALLOWED'
|
|
189
|
+
/** 原文件超过声明的 max_source_bytes。 */
|
|
190
|
+
| 'SOURCE_TOO_LARGE'
|
|
191
|
+
/** 无下载权限。 */
|
|
192
|
+
| 'DOWNLOAD_FORBIDDEN'
|
|
193
|
+
/** 附件已被别处换掉,当前会话作废。 */
|
|
194
|
+
| 'SOURCE_CHANGED';
|
|
195
|
+
|
|
196
|
+
/** 宿主 reject 时抛出的错误形状(插件按 code 判断,不要解析 message)。 */
|
|
197
|
+
export interface AttachmentOpenError extends Error {
|
|
198
|
+
code: AttachmentOpenErrorCode;
|
|
199
|
+
data?: { lockedBy?: AttachmentEditLockHolder };
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export interface AttachmentSaveOptions {
|
|
203
|
+
/** 保存产物的类型;缺省沿用原文件类型。 */
|
|
204
|
+
contentType?: string;
|
|
205
|
+
/** 保存产物的文件名;缺省沿用原文件名。 */
|
|
206
|
+
name?: string;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
export interface AttachmentSaveResult {
|
|
210
|
+
/** 新附件 ID(原文件按内容寻址、不可变,保存必然得到新 ID)。 */
|
|
211
|
+
assetId: string;
|
|
212
|
+
byteSize: number;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* 一次编辑会话(由 ctx.beginEdit 取得)。持有附件编辑锁,外壳负责心跳续期;
|
|
217
|
+
* 保存 = 宿主存新附件 → 经表单数据权威层把字段值里的这一条换成新 ID;保存只标记单据有改动,保存单据才提交。
|
|
218
|
+
*/
|
|
219
|
+
export interface AttachmentEditSession {
|
|
220
|
+
id: string;
|
|
221
|
+
/** 当前锁到期时间(UTC ISO),外壳会续期,插件一般无需关心。 */
|
|
222
|
+
expiresAt: string;
|
|
223
|
+
save(content: Blob, options?: AttachmentSaveOptions): Promise<AttachmentSaveResult>;
|
|
224
|
+
/** 结束编辑并释放锁;discard=true 表示放弃未保存内容(外壳已向用户确认过)。 */
|
|
225
|
+
end(options?: { discard?: boolean }): Promise<void>;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** 宿主传给插件的上下文(组件 prop `ctx`)。 */
|
|
229
|
+
export interface AttachmentOpenContext {
|
|
230
|
+
attachment: AttachmentOpenItem;
|
|
231
|
+
env: AttachmentOpenEnv;
|
|
232
|
+
permissions: AttachmentOpenPermissions;
|
|
233
|
+
/** 当前模式;外壳切换时经 onModeChange 通知。 */
|
|
234
|
+
mode: AttachmentOpenMode;
|
|
235
|
+
/** 读原文件。底层走宿主「查看」通道(带预览请求头、no-store),插件不自己拼地址。 */
|
|
236
|
+
readSource(options?: AttachmentSourceReadOptions): Promise<AttachmentSourceReadResult>;
|
|
237
|
+
/** 请宿主下载原文件:宿主重判权限、换一次性签名地址并自行触发;canDownload=false 时 reject DOWNLOAD_FORBIDDEN。 */
|
|
238
|
+
download(): Promise<void>;
|
|
239
|
+
/** 进入编辑:取附件编辑锁。被占用时 reject EDIT_LOCKED(data.lockedBy 为占用者)。 */
|
|
240
|
+
beginEdit(): Promise<AttachmentEditSession>;
|
|
241
|
+
/**
|
|
242
|
+
* 有无未保存修改;外壳据此在关闭 / 切换附件 / 切换打开方式 / 刷新页面前确认,并点亮标题栏的「保存」
|
|
243
|
+
* (「保存」按下后经 onSaveRequest 回到插件)。
|
|
244
|
+
*/
|
|
245
|
+
setDirty(dirty: boolean): void;
|
|
246
|
+
setStatus(status: AttachmentOpenStatus): void;
|
|
247
|
+
/** 该附件条目在编辑期间被别处换掉(表单数据推送)时回调;返回取消订阅函数。 */
|
|
248
|
+
onSourceChanged(callback: () => void): () => void;
|
|
249
|
+
/** 外壳切换查看 / 编辑模式时回调;返回取消订阅函数。 */
|
|
250
|
+
onModeChange(callback: (mode: AttachmentOpenMode) => void): () => void;
|
|
251
|
+
/**
|
|
252
|
+
* 宿主请插件保存(外壳标题栏的「保存」「保存并关闭」、结束编辑前的确认):插件在回调里把当前内容经
|
|
253
|
+
* `session.save` 写出,resolve true = 已保存,false = 用户取消或无可保存内容;reject = 保存失败(外壳按
|
|
254
|
+
* error.code 提示,插件保留内容)。插件进入编辑态后必须登记一次;未登记时外壳不渲染自己的保存按钮,
|
|
255
|
+
* 只能靠插件工具栏自己的保存。返回取消订阅函数。
|
|
256
|
+
*/
|
|
257
|
+
onSaveRequest(callback: () => Promise<boolean>): () => void;
|
|
258
|
+
/** 上报日志到宿主日志体系;关键位置必须上报。 */
|
|
259
|
+
log(level: AttachmentOpenLogLevel, message: string, data?: Record<string, unknown>): void;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/** 插件 surface 组件收到的 props。 */
|
|
263
|
+
export interface AttachmentOpenSurfaceProps {
|
|
264
|
+
ctx: AttachmentOpenContext;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** 宿主调用 createSurface 时的输入(surfaceType 固定为 attachment.open,props 为 AttachmentOpenSurfaceProps)。 */
|
|
268
|
+
export interface AttachmentOpenSurfaceInput extends SurfaceCreateInput {
|
|
269
|
+
surfaceType: typeof ATTACHMENT_OPEN_SURFACE_TYPE;
|
|
270
|
+
props: AttachmentOpenSurfaceProps & Record<string, unknown>;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
// ---------------------------------------------------------------------------
|
|
274
|
+
// 沙箱档(iframe)跨帧桥:宿主 → 框架的线上形状与框架侧还原
|
|
275
|
+
// ---------------------------------------------------------------------------
|
|
276
|
+
//
|
|
277
|
+
// 为什么不能直接把 AttachmentOpenContext 扔过 MessageChannel:沙箱桥只把**顶层**函数编码成可调句柄,调用结果里嵌套的函数
|
|
278
|
+
// 会被剥离——beginEdit() 返回的会话对象上的 save / end 到了框架就没了;宿主请插件保存(onSaveRequest)需要拿到插件回调的
|
|
279
|
+
// 结果,而桥的回调投递是单向的。所以线上形状把会话拍平成 beginEdit / saveEdit / endEdit 三个顶层函数,保存请求拆成
|
|
280
|
+
// 「宿主发 requestId → 插件处理完调 completeSaveRequest 回报」一问一答。宿主侧按本形状组装(宿主 attachment-open/frameBridge.ts),
|
|
281
|
+
// 框架侧由 createAttachmentOpenFrameContext 还原成插件熟悉的 ctx。
|
|
282
|
+
|
|
283
|
+
/** 跨帧线上形状的标记键:宿主在沙箱档把 props.ctx 换成带此键的对象,defineAttachmentOpenSurface 据此识别并还原。 */
|
|
284
|
+
export const ATTACHMENT_OPEN_FRAME_BRIDGE_MARK = '__kimpoAttachmentFrame' as const;
|
|
285
|
+
/** 线上形状版本(宿主与 SDK 两侧改形状时同步递增;版本不符时 SDK 不还原、原样交给插件并记 warn)。 */
|
|
286
|
+
export const ATTACHMENT_OPEN_FRAME_BRIDGE_VERSION = 1 as const;
|
|
287
|
+
|
|
288
|
+
/** beginEdit 经桥返回的会话快照(纯数据;save / end 走 saveEdit / endEdit)。 */
|
|
289
|
+
export interface AttachmentEditSessionSnapshot {
|
|
290
|
+
id: string;
|
|
291
|
+
expiresAt: string;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** 插件处理完宿主的保存请求后回报的结果。失败时 code 取 AttachmentOpenErrorCode(或插件自定义码),lockedBy 随 EDIT_LOCKED 带回。 */
|
|
295
|
+
export type AttachmentFrameSaveOutcome =
|
|
296
|
+
| { ok: true; saved: boolean }
|
|
297
|
+
| { ok: false; code: string; message?: string; lockedBy?: AttachmentEditLockHolder };
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* 沙箱档宿主 → 框架的线上形状。宿主侧的函数可同步可异步;经 MessageChannel 后在框架里一律返回 Promise
|
|
301
|
+
* (订阅类返回 `Promise<() => void>`,用 disposerOf 统一)。数据字段(attachment / env / permissions / mode)是挂载时快照。
|
|
302
|
+
*/
|
|
303
|
+
export interface AttachmentOpenFrameBridge {
|
|
304
|
+
[ATTACHMENT_OPEN_FRAME_BRIDGE_MARK]: typeof ATTACHMENT_OPEN_FRAME_BRIDGE_VERSION;
|
|
305
|
+
attachment: AttachmentOpenItem;
|
|
306
|
+
env: AttachmentOpenEnv;
|
|
307
|
+
permissions: AttachmentOpenPermissions;
|
|
308
|
+
/** 挂载时的模式快照;之后的切换经 onModeChange 下发。 */
|
|
309
|
+
mode: AttachmentOpenMode;
|
|
310
|
+
readSource(options?: AttachmentSourceReadOptions): Promise<AttachmentSourceReadResult>;
|
|
311
|
+
download(): Promise<void>;
|
|
312
|
+
/** 取锁(幂等);返回会话快照。 */
|
|
313
|
+
beginEdit(): Promise<AttachmentEditSessionSnapshot>;
|
|
314
|
+
/** 当前会话保存(Blob 可结构化克隆)。没有会话时 reject EDIT_FORBIDDEN。 */
|
|
315
|
+
saveEdit(content: Blob, options?: AttachmentSaveOptions): Promise<AttachmentSaveResult>;
|
|
316
|
+
/** 结束当前会话并释放锁。 */
|
|
317
|
+
endEdit(options?: { discard?: boolean }): Promise<void>;
|
|
318
|
+
setDirty(dirty: boolean): void | Promise<void>;
|
|
319
|
+
setStatus(status: AttachmentOpenStatus): void | Promise<void>;
|
|
320
|
+
log(level: AttachmentOpenLogLevel, message: string, data?: Record<string, unknown>): void | Promise<void>;
|
|
321
|
+
onSourceChanged(callback: () => void): (() => void) | Promise<() => void>;
|
|
322
|
+
onModeChange(callback: (mode: AttachmentOpenMode) => void): (() => void) | Promise<() => void>;
|
|
323
|
+
/** 宿主请插件保存:以 requestId 调回调,插件处理完经 completeSaveRequest 回报。 */
|
|
324
|
+
onSaveRequest(callback: (requestId: string) => void): (() => void) | Promise<() => void>;
|
|
325
|
+
completeSaveRequest(requestId: string, outcome: AttachmentFrameSaveOutcome): void | Promise<void>;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** 判断 props.ctx 是否为宿主下发的跨帧线上形状(带标记键且版本一致)。 */
|
|
329
|
+
export function isAttachmentOpenFrameBridge(value: unknown): value is AttachmentOpenFrameBridge {
|
|
330
|
+
if (!value || typeof value !== 'object') return false;
|
|
331
|
+
const record = value as Record<string, unknown>;
|
|
332
|
+
return record[ATTACHMENT_OPEN_FRAME_BRIDGE_MARK] === ATTACHMENT_OPEN_FRAME_BRIDGE_VERSION && typeof record.readSource === 'function';
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
const ATTACHMENT_OPEN_ERROR_CODES: ReadonlySet<string> = new Set<AttachmentOpenErrorCode>([
|
|
336
|
+
'EDIT_LOCKED',
|
|
337
|
+
'EDIT_LOCK_LOST',
|
|
338
|
+
'EDIT_FORBIDDEN',
|
|
339
|
+
'SAVE_TOO_LARGE',
|
|
340
|
+
'SAVE_TYPE_NOT_ALLOWED',
|
|
341
|
+
'SOURCE_TOO_LARGE',
|
|
342
|
+
'DOWNLOAD_FORBIDDEN',
|
|
343
|
+
'SOURCE_CHANGED'
|
|
344
|
+
]);
|
|
345
|
+
|
|
346
|
+
/** 本契约错误码闭集判定。 */
|
|
347
|
+
export function isAttachmentOpenErrorCode(code: unknown): code is AttachmentOpenErrorCode {
|
|
348
|
+
return typeof code === 'string' && ATTACHMENT_OPEN_ERROR_CODES.has(code);
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
/** 构造带 code 的契约错误(框架侧还原与插件测试替身共用)。 */
|
|
352
|
+
export function attachmentOpenError(
|
|
353
|
+
code: AttachmentOpenErrorCode | string,
|
|
354
|
+
message?: string,
|
|
355
|
+
data?: { lockedBy?: AttachmentEditLockHolder }
|
|
356
|
+
): AttachmentOpenError {
|
|
357
|
+
const error = new Error(message || code) as AttachmentOpenError;
|
|
358
|
+
error.name = 'AttachmentOpenError';
|
|
359
|
+
error.code = code as AttachmentOpenErrorCode;
|
|
360
|
+
if (data) error.data = data;
|
|
361
|
+
return error;
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/**
|
|
365
|
+
* 把桥调用失败(框架侧 HostBridgeCallError:code / message / params)还原为契约错误:
|
|
366
|
+
* code 原样(宿主侧 frameBridge 已把契约码放进 code),params.lockedBy 回到 data.lockedBy。
|
|
367
|
+
*/
|
|
368
|
+
export function attachmentOpenErrorFromBridge(error: unknown): AttachmentOpenError {
|
|
369
|
+
const err = (error ?? {}) as { code?: unknown; message?: unknown; params?: { lockedBy?: unknown }; data?: { lockedBy?: unknown } };
|
|
370
|
+
const code = typeof err.code === 'string' && err.code ? err.code : 'EDIT_FORBIDDEN';
|
|
371
|
+
const message = typeof err.message === 'string' ? err.message : String(error);
|
|
372
|
+
const lockedBy = (err.params?.lockedBy ?? err.data?.lockedBy) as AttachmentEditLockHolder | undefined;
|
|
373
|
+
return attachmentOpenError(code, message, lockedBy ? { lockedBy } : undefined);
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/** 把订阅类桥方法的返回值统一成同步退订函数(与 frame-transport 的 disposerOf 同语义,这里避免反向依赖再抄一份极简版)。 */
|
|
377
|
+
function toDisposer(value: unknown): () => void {
|
|
378
|
+
if (typeof value === 'function') return value as () => void;
|
|
379
|
+
if (value && typeof (value as PromiseLike<unknown>).then === 'function') {
|
|
380
|
+
let disposed = false;
|
|
381
|
+
let real: (() => void) | undefined;
|
|
382
|
+
(value as PromiseLike<unknown>).then(
|
|
383
|
+
resolved => {
|
|
384
|
+
if (typeof resolved !== 'function') return;
|
|
385
|
+
real = resolved as () => void;
|
|
386
|
+
if (disposed) real();
|
|
387
|
+
},
|
|
388
|
+
() => undefined
|
|
389
|
+
);
|
|
390
|
+
return () => {
|
|
391
|
+
if (disposed) return;
|
|
392
|
+
disposed = true;
|
|
393
|
+
real?.();
|
|
394
|
+
};
|
|
395
|
+
}
|
|
396
|
+
return () => undefined;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/**
|
|
400
|
+
* 框架侧:把宿主下发的跨帧线上形状还原为 AttachmentOpenContext(纯函数,不依赖 DOM / 框架运行时,可在单测里用假桥驱动)。
|
|
401
|
+
* - `mode` 用宿主快照起步、随 onModeChange 事件维护,插件读到的始终是当前值;
|
|
402
|
+
* - beginEdit 返回的会话对象 save / end 委托给 saveEdit / endEdit(宿主只认当前会话,重新取锁后会话 ID 由宿主换);
|
|
403
|
+
* - onSaveRequest:收到宿主的 requestId → 调插件回调 → 成功 / 失败都经 completeSaveRequest 回报(失败带 code 与 lockedBy);
|
|
404
|
+
* - 桥调用失败一律还原为带 code 的 AttachmentOpenError,插件按 code 分支的写法与同源档一致。
|
|
405
|
+
*/
|
|
406
|
+
export function createAttachmentOpenFrameContext(remote: AttachmentOpenFrameBridge): AttachmentOpenContext {
|
|
407
|
+
let mode: AttachmentOpenMode = remote.mode === 'edit' ? 'edit' : 'view';
|
|
408
|
+
const modeListeners = new Set<(mode: AttachmentOpenMode) => void>();
|
|
409
|
+
const rethrow = (error: unknown): never => {
|
|
410
|
+
throw attachmentOpenErrorFromBridge(error);
|
|
411
|
+
};
|
|
412
|
+
// 发完即忘的通知类调用:宿主侧异常不反向打断插件。
|
|
413
|
+
const fire = (run: () => void | Promise<void>) => {
|
|
414
|
+
try {
|
|
415
|
+
const result = run();
|
|
416
|
+
if (result && typeof (result as Promise<void>).catch === 'function') (result as Promise<void>).catch(() => undefined);
|
|
417
|
+
} catch {
|
|
418
|
+
// 同上
|
|
419
|
+
}
|
|
420
|
+
};
|
|
421
|
+
// 模式跟随:宿主切换查看 / 编辑时先更新本地快照,再通知插件登记的监听器。
|
|
422
|
+
toDisposer(
|
|
423
|
+
remote.onModeChange(next => {
|
|
424
|
+
mode = next === 'edit' ? 'edit' : 'view';
|
|
425
|
+
for (const listener of [...modeListeners]) {
|
|
426
|
+
try {
|
|
427
|
+
listener(mode);
|
|
428
|
+
} catch (error) {
|
|
429
|
+
fire(() => remote.log('warn', 'attachment.frame.mode_listener_failed', { message: error instanceof Error ? error.message : String(error) }));
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
})
|
|
433
|
+
);
|
|
434
|
+
const buildSession = (snapshot: AttachmentEditSessionSnapshot): AttachmentEditSession => ({
|
|
435
|
+
id: snapshot.id,
|
|
436
|
+
expiresAt: snapshot.expiresAt,
|
|
437
|
+
save: (content, options) => Promise.resolve(remote.saveEdit(content, options)).catch(rethrow),
|
|
438
|
+
end: options => Promise.resolve(remote.endEdit(options)).catch(rethrow)
|
|
439
|
+
});
|
|
440
|
+
return {
|
|
441
|
+
attachment: { ...remote.attachment },
|
|
442
|
+
env: { ...remote.env },
|
|
443
|
+
permissions: { ...remote.permissions },
|
|
444
|
+
get mode() {
|
|
445
|
+
return mode;
|
|
446
|
+
},
|
|
447
|
+
readSource: options => Promise.resolve(remote.readSource(options)).catch(rethrow),
|
|
448
|
+
download: () => Promise.resolve(remote.download()).catch(rethrow),
|
|
449
|
+
beginEdit: () => Promise.resolve(remote.beginEdit()).then(buildSession, rethrow),
|
|
450
|
+
setDirty: dirty => fire(() => remote.setDirty(Boolean(dirty))),
|
|
451
|
+
setStatus: status => fire(() => remote.setStatus(status)),
|
|
452
|
+
onSourceChanged: callback => toDisposer(remote.onSourceChanged(callback)),
|
|
453
|
+
onModeChange(callback) {
|
|
454
|
+
modeListeners.add(callback);
|
|
455
|
+
return () => {
|
|
456
|
+
modeListeners.delete(callback);
|
|
457
|
+
};
|
|
458
|
+
},
|
|
459
|
+
onSaveRequest(callback) {
|
|
460
|
+
const off = toDisposer(
|
|
461
|
+
remote.onSaveRequest(async requestId => {
|
|
462
|
+
let outcome: AttachmentFrameSaveOutcome;
|
|
463
|
+
try {
|
|
464
|
+
outcome = { ok: true, saved: (await callback()) === true };
|
|
465
|
+
} catch (error) {
|
|
466
|
+
const err = (error ?? {}) as Partial<AttachmentOpenError>;
|
|
467
|
+
outcome = {
|
|
468
|
+
ok: false,
|
|
469
|
+
code: typeof err.code === 'string' && err.code ? err.code : 'EDIT_FORBIDDEN',
|
|
470
|
+
message: err.message,
|
|
471
|
+
lockedBy: err.data?.lockedBy
|
|
472
|
+
};
|
|
473
|
+
}
|
|
474
|
+
fire(() => remote.completeSaveRequest(requestId, outcome));
|
|
475
|
+
})
|
|
476
|
+
);
|
|
477
|
+
return off;
|
|
478
|
+
},
|
|
479
|
+
log: (level, message, data) => fire(() => remote.log(level, message, data))
|
|
480
|
+
};
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
/**
|
|
484
|
+
* 声明附件插件的挂载工厂(definePluginSurface 的类型窄化版)。
|
|
485
|
+
* 沙箱档里宿主下发的 props.ctx 是跨帧线上形状,这里先还原成 AttachmentOpenContext 再交给插件工厂,
|
|
486
|
+
* 并把还原后的 ctx 放进返回的 props(插件 props 覆盖宿主 props,组件拿到的就是它);同源档原样透传。
|
|
487
|
+
*
|
|
488
|
+
* @example
|
|
489
|
+
* ```ts
|
|
490
|
+
* export const createSurface = defineAttachmentOpenSurface(() => ({ component: PdfStage }));
|
|
491
|
+
* // PdfStage 组件以 prop `ctx: AttachmentOpenContext` 收上下文,两种挂载档写法一样。
|
|
492
|
+
* ```
|
|
493
|
+
*/
|
|
494
|
+
export function defineAttachmentOpenSurface(
|
|
495
|
+
factory: (input: AttachmentOpenSurfaceInput) => SurfaceMountResult
|
|
496
|
+
): (input: AttachmentOpenSurfaceInput) => SurfaceMountResult {
|
|
497
|
+
return definePluginSurface((input: AttachmentOpenSurfaceInput) => {
|
|
498
|
+
const raw = input?.props?.ctx;
|
|
499
|
+
if (!isAttachmentOpenFrameBridge(raw)) return factory(input);
|
|
500
|
+
const ctx = createAttachmentOpenFrameContext(raw);
|
|
501
|
+
const mounted = factory({ ...input, props: { ...input.props, ctx } });
|
|
502
|
+
return { ...mounted, props: { ...(mounted?.props ?? {}), ctx } };
|
|
503
|
+
});
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
// ---------------------------------------------------------------------------
|
|
507
|
+
// ui.openAttachment 服务(调用方入口)的请求 / 结果
|
|
508
|
+
// ---------------------------------------------------------------------------
|
|
509
|
+
|
|
510
|
+
/**
|
|
511
|
+
* 调用方(表格编辑器、历史记录页、宿主内置列表、视图设计器预览)统一经 `createHostUi(hostBridge).openAttachment(req)`
|
|
512
|
+
* 打开附件;不再自带查看器。宿主能力键 `ui.attachment`。
|
|
513
|
+
*/
|
|
514
|
+
export interface OpenAttachmentRequest {
|
|
515
|
+
/** 同一字段里的全部条目,外壳在它们之间左右切换(不同条目可能路由到不同插件)。 */
|
|
516
|
+
items: AttachmentOpenItem[];
|
|
517
|
+
/** 初始显示第几条,缺省 0。 */
|
|
518
|
+
index?: number;
|
|
519
|
+
/** 单据与字段定位;缺席 = 只读、无编辑入口。 */
|
|
520
|
+
recordContext?: AttachmentRecordContext;
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
export interface OpenAttachmentResult {
|
|
524
|
+
/** 本次打开期间是否有保存成功的编辑(调用方可据此刷新自己的展示)。 */
|
|
525
|
+
edited: boolean;
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
// ---------------------------------------------------------------------------
|
|
529
|
+
// 纯函数:类型匹配(宿主路由与插件自检共用同一份判据)
|
|
530
|
+
// ---------------------------------------------------------------------------
|
|
531
|
+
|
|
532
|
+
/** 从文件名取不带点的小写扩展名;没有扩展名得空串。 */
|
|
533
|
+
export function attachmentExtensionOf(name: string): string {
|
|
534
|
+
const base = (name ?? '').trim();
|
|
535
|
+
const dot = base.lastIndexOf('.');
|
|
536
|
+
return dot < 0 || dot === base.length - 1 ? '' : base.slice(dot + 1).toLowerCase();
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
/** 规范化 MIME:去参数、去空白、小写;解析不出得空串。 */
|
|
540
|
+
export function normalizeAttachmentMime(contentType: string | undefined): string {
|
|
541
|
+
return (contentType ?? '').split(';')[0]!.trim().toLowerCase();
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
/**
|
|
545
|
+
* 条目是否落在声明的 accepts 里。
|
|
546
|
+
*
|
|
547
|
+
* 规则(宿主路由表与 manifestlint 同口径,改一处须同步):
|
|
548
|
+
* 1. 登记类型非空且不是通用二进制(application/octet-stream)时按 mime 匹配:精确相等,或 `type/*` 通配;
|
|
549
|
+
* 2. mime 不匹配、或登记类型缺失 / 为通用二进制时,再按扩展名匹配 ext(历史数据的 contentType 可能不准)。
|
|
550
|
+
*/
|
|
551
|
+
export function matchesAttachmentOpenAccepts(
|
|
552
|
+
accepts: AttachmentOpenAccepts | undefined,
|
|
553
|
+
item: Pick<AttachmentOpenItem, 'name' | 'contentType'>
|
|
554
|
+
): boolean {
|
|
555
|
+
if (!accepts) return false;
|
|
556
|
+
const mime = normalizeAttachmentMime(item.contentType);
|
|
557
|
+
if (mime && mime !== 'application/octet-stream') {
|
|
558
|
+
for (const pattern of accepts.mime ?? []) {
|
|
559
|
+
const p = pattern.trim().toLowerCase();
|
|
560
|
+
if (!p) continue;
|
|
561
|
+
if (p === mime) return true;
|
|
562
|
+
if (p.endsWith('/*') && mime.startsWith(p.slice(0, -1))) return true;
|
|
563
|
+
}
|
|
564
|
+
}
|
|
565
|
+
const ext = attachmentExtensionOf(item.name);
|
|
566
|
+
if (!ext) return false;
|
|
567
|
+
return (accepts.ext ?? []).some(e => e.trim().toLowerCase().replace(/^\./, '') === ext);
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
/** 声明是否支持某模式(modes 缺省只有 view)。 */
|
|
571
|
+
export function attachmentOpenSupportsMode(decl: Pick<AttachmentOpenDecl, 'modes'> | undefined, mode: AttachmentOpenMode): boolean {
|
|
572
|
+
const modes = decl?.modes && decl.modes.length > 0 ? decl.modes : ['view'];
|
|
573
|
+
return modes.includes(mode);
|
|
574
|
+
}
|