@kimposoft/plugin-sdk 1.1.0-tp.20 → 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.
@@ -12,9 +12,13 @@
12
12
  // - 嵌套数组拍平;同一 assetId 只保留第一次出现(与表达式引擎 SUM / `+` 的去重口径一致)。
13
13
  //
14
14
  // 地址口径:
15
- // - 图片资产(`img_` 前缀):原图 `/api/v1/sheet/images/assets/{id}/bytes`,缩略图追加 `variant=thumb`;
15
+ // - 图片资产(`img_` 前缀):原图 `/api/v1/sheet/images/assets/{id}/bytes`,缩略图追加 `variant=thumb`,
16
+ // 下载地址追加 `download=1`(宿主按「下载」裁决并以附件形式返回;老宿主忽略该参数,行为同原图);
16
17
  // - 附件资产(`ast_` 前缀):只有下载端点 `/api/v1/sheet/assets/{id}/download`,**不给 bytes 地址**
17
- // (bytes 端点只认图片资产);即便是图片类型的附件资产,原图 / 缩略图也都落下载端点;
18
+ // (bytes 端点只认图片资产);图片类型的附件资产原图落下载端点,缩略图追加 `variant=thumb`
19
+ // (宿主为图片附件生成的缩略图,没有缩略图时宿主回退原图);
20
+ // - 预览地址(只有图片条目才有):按「查看」裁决的大图——附件资产为下载端点追加 `variant=preview`
21
+ // (宿主内联返回原图),图片资产即原图地址;不带 variant 的附件下载地址按「下载」裁决,仅可查看的用户取不到;
18
22
  // - 宿主随查询结果下发 `asset_tickets: { assetId: 票据 }`(查询上下文读票据):
19
23
  // 有票据的条目在地址上追加 `qt=<票据>`,无票据时地址不带参数、由图片端点按派生裁决判权。
20
24
 
@@ -28,6 +32,22 @@ export interface AttachmentItem {
28
32
  contentType?: string;
29
33
  /** 字节数(值里带了才有)。 */
30
34
  byteSize?: number;
35
+ /**
36
+ * 单元格图片显示方式(值里带了合法档位才有):`contain` 适应 / `cover` 填充 / `stretch` 拉伸。
37
+ * 栈级属性按条目存:同一格的图片条目写同一个值,读取方取第一个有值的条目;缺省 = 沿用模板设置。
38
+ * 旧版 SDK 解析时丢弃此键,改写附件值时请保留原条目上的其他键。
39
+ */
40
+ fit?: AttachmentImageFit;
41
+ }
42
+
43
+ /** 单元格图片显示方式档位。 */
44
+ export type AttachmentImageFit = 'contain' | 'cover' | 'stretch';
45
+
46
+ /** 归一显示方式档位:只认三档(大小写、首尾空白不敏感),其余返回 undefined。 */
47
+ export function normalizeAttachmentImageFit(value: unknown): AttachmentImageFit | undefined {
48
+ if (typeof value !== 'string') return undefined;
49
+ const v = value.trim().toLowerCase();
50
+ return v === 'contain' || v === 'cover' || v === 'stretch' ? v : undefined;
31
51
  }
32
52
 
33
53
  /** 单条条目的地址集合。 */
@@ -38,6 +58,11 @@ export interface AttachmentItemUrls {
38
58
  thumbUrl?: string;
39
59
  /** 原图 / 打开地址;非图片条目等于 downloadUrl。 */
40
60
  url: string;
61
+ /**
62
+ * 图片预览地址:宿主按「查看」裁决并内联返回的大图,只有图片条目才有。仅可查看、不可下载的用户
63
+ * 也取得到。字段可选:旧版 SDK 没有它,消费方缺省时自行回落旧拼法。
64
+ */
65
+ previewUrl?: string;
41
66
  /** 下载地址。 */
42
67
  downloadUrl: string;
43
68
  }
@@ -147,6 +172,9 @@ export function parseAttachmentItems(value: unknown): AttachmentItem[] {
147
172
  if (contentType) item.contentType = contentType;
148
173
  const byteSize = pickNumber(raw, ['byteSize', 'byte_size']);
149
174
  if (byteSize !== undefined) item.byteSize = byteSize;
175
+ // 显示方式随条目保留(非法值丢弃,交给读取方按模板 / 缺省处理)。
176
+ const fit = normalizeAttachmentImageFit(raw.fit);
177
+ if (fit) item.fit = fit;
150
178
  items.push(item);
151
179
  }
152
180
  return items;
@@ -175,16 +203,28 @@ export function attachmentItemUrls(
175
203
  const isImage = isImageItem(item);
176
204
  // 附件资产(ast_)只有下载端点;其余(img_ 及历史未知前缀)走图片端点取原图。
177
205
  const isAttachmentAsset = item.assetId.startsWith('ast_');
178
- const downloadUrl = withTicket(
179
- isAttachmentAsset ? `${base}/api/v1/sheet/assets/${id}/download` : `${base}/api/v1/sheet/images/assets/${id}/bytes`
180
- );
181
- if (!isImage) return { isImage: false, url: downloadUrl, downloadUrl };
182
- if (isAttachmentAsset) return { isImage: true, thumbUrl: downloadUrl, url: downloadUrl, downloadUrl };
206
+ if (isAttachmentAsset) {
207
+ const download = `${base}/api/v1/sheet/assets/${id}/download`;
208
+ const downloadUrl = withTicket(download);
209
+ if (!isImage) return { isImage: false, url: downloadUrl, downloadUrl };
210
+ return {
211
+ isImage: true,
212
+ thumbUrl: withTicket(`${download}?variant=thumb`),
213
+ url: downloadUrl,
214
+ previewUrl: withTicket(`${download}?variant=preview`),
215
+ downloadUrl,
216
+ };
217
+ }
183
218
  const bytes = `${base}/api/v1/sheet/images/assets/${id}/bytes`;
219
+ // 图片字节端点的下载用途要显式带 download=1(不带时按「查看」裁决、内联返回)。
220
+ const downloadUrl = withTicket(`${bytes}?download=1`);
221
+ if (!isImage) return { isImage: false, url: downloadUrl, downloadUrl };
222
+ const url = withTicket(bytes);
184
223
  return {
185
224
  isImage: true,
186
225
  thumbUrl: withTicket(`${bytes}?variant=thumb`),
187
- url: withTicket(bytes),
226
+ url,
227
+ previewUrl: url,
188
228
  downloadUrl,
189
229
  };
190
230
  }
@@ -13,6 +13,236 @@
13
13
  // - 额外接受带毫秒与时区后缀(Z / ±hh:mm)的 ISO 串,按字面墙钟分量取数、不做换算
14
14
  // (与候选值格式化同一口径)。
15
15
  // - 不接受 Excel 序列数与纯时间串(表格编辑器单元格存储形态,记录接口不会下发),返回 null 交调用方回退。
16
+ //
17
+ // 「自定义」日期时间样式(440)没有固定写法,格式串由调用方从字段 format_rule_json 读出
18
+ // (readDatetimePattern)后经 options.datetimePattern 传入;格式串的解析 / 渲染 / 粒度 / Excel 换算
19
+ // 见下方「自定义格式串」一节。放在同一文件而不另拆模块:本文件会被个别消费方单独编译成 JS
20
+ // 供 node 测试直接加载,单文件零相对导入才不受 ESM 扩展名解析影响。
21
+
22
+ // ── 自定义格式串(展示样式 440)────────────────────────────────────────────────
23
+ //
24
+ // 格式串的解析、校验、渲染、填报选择器粒度推断与 Excel numFmt 换算,从根入口导出。
25
+ // 平台各侧(宿主后端、表格编辑器、本 SDK)各有一份同口径实现,靠同一组用例做一致性测试——改口径须各侧同步。
26
+ //
27
+ // 约定:
28
+ // - 展示样式码 CUSTOM_DATETIME_DISPLAY_STYLE('440')表示「自定义」,只对 datetime 字段有意义;
29
+ // 格式串存在字段 format_rule_json 的 `datetime_pattern` 键,写入时保留其他键。
30
+ // - 记号(最长匹配优先):yyyy yy MM M dd d HH H mm m ss s;大写 M 是月、小写 m 是分。
31
+ // 单引号内为原样文字('' 表示一个单引号);其他字符原样输出。
32
+ // - 合法格式串:去首尾空白后 1~64 个字符,且至少含一个记号;非法时渲染返回 null,调用方回退原值显示。
33
+ // - 值一律按墙上时间(存储串 `yyyy-MM-dd HH:mm:ss` 的各分量)渲染,不做时区换算。
34
+
35
+ /** 「自定义」日期时间展示样式码。 */
36
+ export const CUSTOM_DATETIME_DISPLAY_STYLE = '440';
37
+ /** 格式串最大长度(按字符计,去首尾空白后)。 */
38
+ export const DATETIME_PATTERN_MAX_LENGTH = 64;
39
+ /** format_rule_json 中存放格式串的键。 */
40
+ export const DATETIME_PATTERN_KEY = 'datetime_pattern';
41
+
42
+ /** 格式串记号。 */
43
+ export type DatetimePatternToken = 'yyyy' | 'yy' | 'MM' | 'M' | 'dd' | 'd' | 'HH' | 'H' | 'mm' | 'm' | 'ss' | 's';
44
+ /** 格式串片段:记号或原样文字。 */
45
+ export type DatetimePatternPart = { kind: 'token'; token: DatetimePatternToken } | { kind: 'text'; text: string };
46
+ /** 填报选择器粒度(对齐现行五档:年 / 年月 / 日期 / 日期时间 / 时间)。 */
47
+ export type DatetimePatternGrain = 'year' | 'year-month' | 'date' | 'datetime' | 'time';
48
+ /** 格式串校验错误:空 / 超长 / 不含任何记号。 */
49
+ export type DatetimePatternError = 'empty' | 'too_long' | 'no_token';
50
+
51
+ // 最长匹配优先:同一字母的双写记号排在单写前面。
52
+ const TOKENS: DatetimePatternToken[] = ['yyyy', 'yy', 'MM', 'M', 'dd', 'd', 'HH', 'H', 'mm', 'm', 'ss', 's'];
53
+
54
+ /** 把格式串切成记号与原样文字两类片段(相邻文字合并)。 */
55
+ export function parseDatetimePattern(pattern: string): DatetimePatternPart[] {
56
+ const parts: DatetimePatternPart[] = [];
57
+ const pushText = (text: string): void => {
58
+ if (!text) return;
59
+ const last = parts[parts.length - 1];
60
+ if (last && last.kind === 'text') last.text += text;
61
+ else parts.push({ kind: 'text', text });
62
+ };
63
+ let i = 0;
64
+ while (i < pattern.length) {
65
+ const ch = pattern[i];
66
+ if (ch === "'") {
67
+ // '' → 一个单引号;'abc' → 原样文字(未闭合时读到结尾)
68
+ if (pattern[i + 1] === "'") {
69
+ pushText("'");
70
+ i += 2;
71
+ continue;
72
+ }
73
+ let j = i + 1;
74
+ let text = '';
75
+ while (j < pattern.length) {
76
+ if (pattern[j] === "'") {
77
+ if (pattern[j + 1] === "'") {
78
+ text += "'";
79
+ j += 2;
80
+ continue;
81
+ }
82
+ break;
83
+ }
84
+ text += pattern[j];
85
+ j += 1;
86
+ }
87
+ pushText(text);
88
+ i = j + 1;
89
+ continue;
90
+ }
91
+ const token = TOKENS.find((t) => pattern.startsWith(t, i));
92
+ if (token) {
93
+ parts.push({ kind: 'token', token });
94
+ i += token.length;
95
+ continue;
96
+ }
97
+ pushText(ch!);
98
+ i += 1;
99
+ }
100
+ return parts;
101
+ }
102
+
103
+ /** 校验格式串;合法返回 null。 */
104
+ export function validateDatetimePattern(pattern: string | null | undefined): DatetimePatternError | null {
105
+ const text = (pattern ?? '').trim();
106
+ if (!text) return 'empty';
107
+ if ([...text].length > DATETIME_PATTERN_MAX_LENGTH) return 'too_long';
108
+ if (!parseDatetimePattern(text).some((part) => part.kind === 'token')) return 'no_token';
109
+ return null;
110
+ }
111
+
112
+ /** 墙上时间分量(月份 1~12)。 */
113
+ export interface DatetimePatternWallClock {
114
+ year: number;
115
+ month: number;
116
+ day: number;
117
+ hour: number;
118
+ minute: number;
119
+ second: number;
120
+ }
121
+
122
+ /** 取 Date 在浏览器本地时区下的墙上时间分量(调用方自己决定 Date 的来源时区)。 */
123
+ function wallClockFromDate(date: Date): DatetimePatternWallClock {
124
+ return {
125
+ year: date.getFullYear(),
126
+ month: date.getMonth() + 1,
127
+ day: date.getDate(),
128
+ hour: date.getHours(),
129
+ minute: date.getMinutes(),
130
+ second: date.getSeconds(),
131
+ };
132
+ }
133
+
134
+ function tokenText(token: DatetimePatternToken, v: DatetimePatternWallClock): string {
135
+ switch (token) {
136
+ case 'yyyy': return String(v.year);
137
+ case 'yy': return pad2(v.year % 100);
138
+ case 'MM': return pad2(v.month);
139
+ case 'M': return String(v.month);
140
+ case 'dd': return pad2(v.day);
141
+ case 'd': return String(v.day);
142
+ case 'HH': return pad2(v.hour);
143
+ case 'H': return String(v.hour);
144
+ case 'mm': return pad2(v.minute);
145
+ case 'm': return String(v.minute);
146
+ case 'ss': return pad2(v.second);
147
+ case 's': return String(v.second);
148
+ }
149
+ }
150
+
151
+ /** 按格式串渲染墙上时间;格式串非法时返回 null(调用方回退原值显示)。 */
152
+ export function renderDatetimePattern(
153
+ pattern: string | null | undefined,
154
+ value: DatetimePatternWallClock | Date,
155
+ ): string | null {
156
+ if (validateDatetimePattern(pattern) !== null) return null;
157
+ const v = value instanceof Date ? wallClockFromDate(value) : value;
158
+ return parseDatetimePattern((pattern ?? '').trim())
159
+ .map((part) => (part.kind === 'token' ? tokenText(part.token, v) : part.text))
160
+ .join('');
161
+ }
162
+
163
+ /** 按格式串里出现的记号推断填报选择器粒度(对齐现行五档);非法格式串按「日期 + 时间」处理。 */
164
+ export function datetimePatternGrain(pattern: string | null | undefined): DatetimePatternGrain {
165
+ if (validateDatetimePattern(pattern) !== null) return 'datetime';
166
+ const letters = new Set(
167
+ parseDatetimePattern((pattern ?? '').trim())
168
+ .filter((p): p is { kind: 'token'; token: DatetimePatternToken } => p.kind === 'token')
169
+ .map((p) => p.token[0]),
170
+ );
171
+ const hasDate = letters.has('y') || letters.has('M') || letters.has('d');
172
+ const hasTime = letters.has('H') || letters.has('m') || letters.has('s');
173
+ if (hasDate && hasTime) return 'datetime';
174
+ if (hasTime) return 'time';
175
+ if (letters.has('d')) return 'date';
176
+ if (letters.has('M')) return 'year-month';
177
+ return 'year';
178
+ }
179
+
180
+ const EXCEL_TOKEN: Record<DatetimePatternToken, string> = {
181
+ yyyy: 'yyyy', yy: 'yy', MM: 'mm', M: 'm', dd: 'dd', d: 'd', HH: 'hh', H: 'h', mm: 'mm', m: 'm', ss: 'ss', s: 's',
182
+ };
183
+
184
+ function excelLiteral(text: string): string {
185
+ // Excel numFmt:双引号内为原样文字,双引号本身用 \" 在引号外输出。
186
+ return text
187
+ .split('"')
188
+ .map((seg) => (seg ? `"${seg}"` : ''))
189
+ .join('\\"');
190
+ }
191
+
192
+ /**
193
+ * 换算为 Excel numFmt;Excel 会把「前一个记号是时或后一个记号是秒」的 m 判为分钟、其余判为月份,
194
+ * 若格式串里的月 / 分与 Excel 的判定不一致(如单独的「mm分」),返回空串,调用方改按格式化后的文本导出。
195
+ */
196
+ export function datetimePatternToExcelNumFmt(pattern: string | null | undefined): string {
197
+ if (validateDatetimePattern(pattern) !== null) return '';
198
+ const parts = parseDatetimePattern((pattern ?? '').trim());
199
+ const tokens = parts
200
+ .filter((p): p is { kind: 'token'; token: DatetimePatternToken } => p.kind === 'token')
201
+ .map((p) => p.token);
202
+ for (let i = 0; i < tokens.length; i += 1) {
203
+ const t = tokens[i]!;
204
+ if (t[0] !== 'M' && t[0] !== 'm') continue;
205
+ const prev = tokens[i - 1];
206
+ const next = tokens[i + 1];
207
+ const excelMinute = (prev !== undefined && prev[0] === 'H') || (next !== undefined && next[0] === 's');
208
+ if (excelMinute !== (t[0] === 'm')) return '';
209
+ }
210
+ return parts.map((p) => (p.kind === 'token' ? EXCEL_TOKEN[p.token] : excelLiteral(p.text))).join('');
211
+ }
212
+
213
+ /** 从 format_rule_json(对象或 JSON 串)读格式串;没有则返回空串。 */
214
+ export function readDatetimePattern(formatRule: unknown): string {
215
+ let obj: unknown = formatRule;
216
+ if (typeof formatRule === 'string') {
217
+ if (!formatRule.trim()) return '';
218
+ try {
219
+ obj = JSON.parse(formatRule);
220
+ } catch {
221
+ return '';
222
+ }
223
+ }
224
+ if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return '';
225
+ const value = (obj as Record<string, unknown>)[DATETIME_PATTERN_KEY];
226
+ return typeof value === 'string' ? value : '';
227
+ }
228
+
229
+ /** 写入格式串并保留 format_rule_json 的其他键;pattern 为空时移除该键。返回新对象。 */
230
+ export function writeDatetimePattern(formatRule: unknown, pattern: string): Record<string, unknown> {
231
+ let base: Record<string, unknown> = {};
232
+ let obj: unknown = formatRule;
233
+ if (typeof formatRule === 'string' && formatRule.trim()) {
234
+ try {
235
+ obj = JSON.parse(formatRule);
236
+ } catch {
237
+ obj = null;
238
+ }
239
+ }
240
+ if (obj && typeof obj === 'object' && !Array.isArray(obj)) base = { ...(obj as Record<string, unknown>) };
241
+ const text = pattern.trim();
242
+ if (text) base[DATETIME_PATTERN_KEY] = text;
243
+ else delete base[DATETIME_PATTERN_KEY];
244
+ return base;
245
+ }
16
246
 
17
247
  /** 日期时间大类(目录大类「4」)叶子码。 */
18
248
  const DATE_TIME_DISPLAY_STYLES = new Set<string>([
@@ -20,8 +250,19 @@ const DATE_TIME_DISPLAY_STYLES = new Set<string>([
20
250
  '406', '424', '407', '425', '408', '426', '413', '427', '414', '428', '415', '429',
21
251
  '409', '430', '410', '431', '411', '432',
22
252
  '416', '417', '418', '419',
253
+ // 「自定义」:按字段自己的格式串渲染
254
+ CUSTOM_DATETIME_DISPLAY_STYLE,
23
255
  ]);
24
256
 
257
+ /** formatDisplayStyleValue / formatDisplayStyleBucketLabel 的可选参数。 */
258
+ export interface DisplayStyleFormatOptions {
259
+ /**
260
+ * 「自定义」日期时间样式(440)的格式串,取自字段 format_rule_json.datetime_pattern
261
+ * (用 readDatetimePattern 读)。其他样式码忽略本参数;440 缺格式串或格式串非法时返回 null。
262
+ */
263
+ datetimePattern?: string | null;
264
+ }
265
+
25
266
  /** 数值样式渲染参数:小数位 / 千分位 / 前缀(货币符号)/ 是否百分比(值 ×100 加 %)。 */
26
267
  interface NumericDisplayStyleSpec {
27
268
  decimals: number;
@@ -59,12 +300,19 @@ export function isNumericDisplayStyle(displayStyle: string | null | undefined):
59
300
  * 返回 null 表示「该样式没有格式化规则」(文本/图片/附件大类、未知码、空码)或「值解析不了」,
60
301
  * 调用方应回退到自己原有的显示方式,不要把 null 当空文本呈现。
61
302
  */
62
- export function formatDisplayStyleValue(value: unknown, displayStyle: string | null | undefined): string | null {
303
+ export function formatDisplayStyleValue(
304
+ value: unknown,
305
+ displayStyle: string | null | undefined,
306
+ options?: DisplayStyleFormatOptions,
307
+ ): string | null {
63
308
  if (value === null || value === undefined || value === '') return null;
64
309
  if (!displayStyle) return null;
65
310
  if (DATE_TIME_DISPLAY_STYLES.has(displayStyle)) {
66
311
  const parts = parseWallClockParts(value);
67
- return parts ? formatDateTimeParts(displayStyle, parts) : null;
312
+ if (!parts) return null;
313
+ // 440 按墙钟分量套格式串;格式串缺失或非法时 renderDatetimePattern 返回 null,交调用方回退
314
+ if (displayStyle === CUSTOM_DATETIME_DISPLAY_STYLE) return renderDatetimePattern(options?.datetimePattern, parts);
315
+ return formatDateTimeParts(displayStyle, parts);
68
316
  }
69
317
  const spec = NUMERIC_DISPLAY_STYLE_SPECS[displayStyle];
70
318
  if (spec) {
@@ -202,6 +450,7 @@ export type DisplayStyleBucket =
202
450
  export function formatDisplayStyleBucketLabel(
203
451
  bucket: DisplayStyleBucket,
204
452
  displayStyle: string | null | undefined,
453
+ options?: DisplayStyleFormatOptions,
205
454
  ): string | null {
206
455
  if (bucket.kind === 'range') {
207
456
  if (!Number.isFinite(bucket.start) || !Number.isFinite(bucket.end)) return null;
@@ -212,10 +461,13 @@ export function formatDisplayStyleBucketLabel(
212
461
  if (!displayStyle || !DATE_TIME_DISPLAY_STYLES.has(displayStyle)) return null;
213
462
  const parts = parseWallClockParts(bucket.start);
214
463
  if (!parts) return null;
215
- const sep = dateSeparatorOf(displayStyle);
464
+ const custom = displayStyle === CUSTOM_DATETIME_DISPLAY_STYLE ? customDateBucketStyle(options?.datetimePattern) : null;
465
+ if (displayStyle === CUSTOM_DATETIME_DISPLAY_STYLE && !custom) return null;
466
+ const sep = custom ? custom.sep : dateSeparatorOf(displayStyle);
216
467
  if (!sep) return null;
217
- // 补零口径跟随样式本身:421~432 族补零,401~411 族不补零(对齐 formatDateTimeParts)
218
- const padded = PADDED_DATE_STYLES.has(displayStyle);
468
+ // 补零口径跟随样式本身:421~432 族补零,401~411 族不补零(对齐 formatDateTimeParts);
469
+ // 440 看格式串里月 / 日用的是双写(MM、dd)还是单写
470
+ const padded = custom ? custom.padded : PADDED_DATE_STYLES.has(displayStyle);
219
471
  const mm = padded ? pad2(parts.month) : String(parts.month);
220
472
  const dd = padded ? pad2(parts.day) : String(parts.day);
221
473
  if (sep === 'cn') {
@@ -228,6 +480,36 @@ export function formatDisplayStyleBucketLabel(
228
480
  return `${parts.year}${sep}${mm}${sep}${dd}`;
229
481
  }
230
482
 
483
+ /**
484
+ * 「自定义」格式串 → 分组桶标签的写法。分组桶要求标签无歧义、跨桶可比,所以不逐字套用格式串
485
+ * (格式串可能缺年份、用两位年、把日放在月前),而是按格式串推断与固定日期样式同一套的写法:
486
+ * - 写法:格式串的原样文字里出现「年」→ 中文年月日;否则取第一个夹在两个日期记号(y/M/d)之间的
487
+ * 分隔文字,是 `/` 或 `.` 就用它,其余一律按短横线;
488
+ * - 补零:格式串里出现 MM 或 dd 双写记号即补零;
489
+ * - 年份一律四位、年在前,按所选粒度截断(与固定日期样式的桶标签同口径)。
490
+ * 格式串缺失 / 非法 / 不含任何日期记号(纯时间格式)→ null,调用方回退到自己的显示方式。
491
+ */
492
+ function customDateBucketStyle(
493
+ pattern: string | null | undefined,
494
+ ): { sep: '-' | '/' | '.' | 'cn'; padded: boolean } | null {
495
+ if (validateDatetimePattern(pattern) !== null) return null;
496
+ const parts = parseDatetimePattern((pattern ?? '').trim());
497
+ const isDateToken = (p: (typeof parts)[number] | undefined): boolean =>
498
+ !!p && p.kind === 'token' && (p.token[0] === 'y' || p.token[0] === 'M' || p.token[0] === 'd');
499
+ if (!parts.some((p) => isDateToken(p))) return null;
500
+ const padded = parts.some((p) => p.kind === 'token' && (p.token === 'MM' || p.token === 'dd'));
501
+ if (parts.some((p) => p.kind === 'text' && p.text.includes('年'))) return { sep: 'cn', padded };
502
+ let sep: '-' | '/' | '.' = '-';
503
+ for (let i = 1; i < parts.length - 1; i += 1) {
504
+ const part = parts[i]!;
505
+ if (part.kind !== 'text' || !isDateToken(parts[i - 1]) || !isDateToken(parts[i + 1])) continue;
506
+ const text = part.text.trim();
507
+ if (text === '/' || text === '.') sep = text;
508
+ break;
509
+ }
510
+ return { sep, padded };
511
+ }
512
+
231
513
  /** 月/日补零的日期样式码(421~432 族);其余日期码(401~411)不补零。 */
232
514
  const PADDED_DATE_STYLES = new Set<string>(['421', '422', '423', '424', '425', '426', '430', '431', '432']);
233
515
 
@@ -123,7 +123,9 @@ export const EDITOR_FRAME_EXPOSED_METHODS = [
123
123
  'setTaskFieldPolicy',
124
124
  'validateTaskRequired',
125
125
  // 任务工作台附件上传(File 可结构化克隆,宿主把文件交给编辑器、回执是纯数据)。
126
- 'uploadTaskAttachment'
126
+ 'uploadTaskAttachment',
127
+ // 填报态就地切换形态(入参是纯数据,回执为空)。
128
+ 'switchFormMode'
127
129
  ] as const;
128
130
 
129
131
  export type EditorFrameExposedMethod = (typeof EDITOR_FRAME_EXPOSED_METHODS)[number];
package/src/editor.ts CHANGED
@@ -647,6 +647,11 @@ export interface HostNavigationClient {
647
647
  openFormFill?(input: {
648
648
  templateId: string;
649
649
  prefill?: Array<{ fieldId: string; text: string }>;
650
+ /**
651
+ * 宿主签发的「填报表单」预填票据号(form.open-create 效果的 args.prefill_ticket):
652
+ * 预填值由宿主持有,宿主打开新单时凭它取值;编辑器原样转交,不解释。新宿主不再在效果里下发 prefill 明文。
653
+ */
654
+ prefillTicket?: string;
650
655
  autoCloseOnSave?: boolean;
651
656
  writeback?: {
652
657
  enabled: boolean;
@@ -654,6 +659,11 @@ export interface HostNavigationClient {
654
659
  } | null;
655
660
  bindingId?: string;
656
661
  nodeId?: string;
662
+ /**
663
+ * 新建表单的打开方式(form.open-create 效果的 args.presentation):'tab'=宿主以新页签打开,
664
+ * 其余或缺省=弹窗。编辑器原样转交,不解释;宿主做不到新页签时(如内嵌弹窗里的表单)按弹窗打开。
665
+ */
666
+ presentation?: 'dialog' | 'tab';
657
667
  }): void | Promise<{ saved: boolean; recordId?: string } | void>;
658
668
  /**
659
669
  * 宿主代选记录:宿主按当前用户数据权限查目标模板记录、弹出既有记录选择器,只把用户选中的
@@ -882,6 +892,24 @@ export interface EditorActionCapabilities {
882
892
  triggers: ActionTriggerEventKey[];
883
893
  }
884
894
 
895
+ /**
896
+ * 填报态三态就地切换的入参(查看 ↔ 修改、保存后转查看、保存后继续新建)。
897
+ * 宿主已完成交互会话转态(后端端点)并把 formMode / recordId / readonly / hostContext 等 props
898
+ * 换成目标态之后,才以本入参调用 {@link EditorPluginExposedApi.switchFormMode}。
899
+ */
900
+ export interface EditorFormModeSwitchInput {
901
+ /** 目标填报形态:'view' | 'edit' | 'create'(create = 保存后继续新建,同一会话就地重建为空白新单)。 */
902
+ formMode: EditorFormMode;
903
+ /** 目标单据 id(查看 / 修改态必有;create 时为宿主占位值,编辑器按空单据处理)。 */
904
+ recordId: string;
905
+ /** 目标态是否只读(查看态恒为 true)。 */
906
+ readonly: boolean;
907
+ /** 宿主端点应答里的单据版本号;编辑器优先以会话 meta 中的版本号为准,缺席时才用它。 */
908
+ recordVersionNo?: number;
909
+ /** 保存/提交后被动转查看:true 时不触发 view-time 打开锚点 */
910
+ suppressOpenLifecycleTrigger?: boolean;
911
+ }
912
+
885
913
  /** Imperative API the editor exposes (via Vue defineExpose) for the host to push results in. */
886
914
  export interface EditorPluginExposedApi {
887
915
  applyEffectEnvelope(envelope: EditorEffectEnvelope): Promise<{ failedEffectId?: string; error?: string } | void>;
@@ -902,7 +930,12 @@ export interface EditorPluginExposedApi {
902
930
  ): Promise<{ blob: Blob; pageCount: number }>;
903
931
  /** Read current changes from the live runtime Mirror. Available only in form-runtime task mode. */
904
932
  getTaskDraftChanges?(): Promise<TaskWorkbenchChanges>;
905
- /** Restore a typed draft into the live runtime without using DOM inputs. */
933
+ /**
934
+ * Restore a typed draft into the live runtime without using DOM inputs.
935
+ *
936
+ * @deprecated 新版宿主不再调用:该链路是「外部草稿值 → 编辑器写格 → 编辑器投影回 Mirror」,
937
+ * 违反填报态业务数据经 Mirror。新编辑器不必实现;已实现的保留无害,下个主版本从契约中移除。
938
+ */
906
939
  applyTaskDraftChanges?(changes: TaskWorkbenchChanges): Promise<void>;
907
940
  /** Replace the Host policy after workspace refresh/revoke. */
908
941
  setTaskFieldPolicy?(config: TaskWorkbenchConfig): void;
@@ -910,6 +943,18 @@ export interface EditorPluginExposedApi {
910
943
  validateTaskRequired?(): Promise<TaskWorkbenchValidationResult>;
911
944
  /** Upload a task-level attachment through the same authorised asset client as form attachments. */
912
945
  uploadTaskAttachment?(file: File): Promise<{ assetId: string; fileName: string; mediaType: string; sizeBytes: number }>;
946
+ /**
947
+ * 填报态就地切换形态:同一编辑器会话不卸载、不重开,只复位插件侧与单据状态相关的
948
+ * 本地状态(单据 id / 版本号 / 保存与提交状态 / 错误提示),并按目标态触发 create-time / edit-time / view-time
949
+ * 打开锚点(入参 suppressOpenLifecycleTrigger 为真时不触发)。create 的打开锚点在编辑器收到会话重建为新单的
950
+ * 元信息后(或等待超时后)才触发,不阻塞本方法返回。
951
+ *
952
+ * 调用时机:宿主已完成交互会话转态端点调用、并把 formMode / recordId / readonly / hostContext 等 props
953
+ * 换成新对象之后再调用;编辑器据 props 计算的只读门控此时已翻转。
954
+ *
955
+ * 可选:老插件不实现,或本方法抛错(如会话尚未打开)时,宿主回落为整面重开。
956
+ */
957
+ switchFormMode?(input: EditorFormModeSwitchInput): Promise<void>;
913
958
  }
914
959
 
915
960
  /**
@@ -1051,6 +1096,34 @@ export const EDITOR_PROFILES = [
1051
1096
 
1052
1097
  export type EditorProfile = (typeof EDITOR_PROFILES)[number];
1053
1098
 
1099
+ /**
1100
+ * 无会话导出(档案 `export.headless`)产物格式闭集(`capabilities.editor.export_formats` 取值,1.1.0-tp.21 起)。
1101
+ * `export_formats` 不写 = 全部支持;宿主据此决定记录页「导出表单」菜单项显隐,建任务时格式不在声明内回 501。
1102
+ */
1103
+ export const EDITOR_EXPORT_FORMATS = ['xlsx', 'pdf'] as const;
1104
+
1105
+ export type EditorExportFormat = (typeof EDITOR_EXPORT_FORMATS)[number];
1106
+
1107
+ /**
1108
+ * 平台单元格录入控件类型闭集(`capabilities.editor.supported_controls` 取值,与宿主控件枚举逐项一致,1.1.0-tp.21 起)。
1109
+ * 'member' / 'department' 是存量读兼容控件:声明合法,但宿主不把它们作为字段面板可选项。
1110
+ */
1111
+ export const EDITOR_PLATFORM_CONTROL_TYPES = [
1112
+ 'radio',
1113
+ 'checkbox',
1114
+ 'select',
1115
+ 'list',
1116
+ 'cascader',
1117
+ 'datetime',
1118
+ 'switch',
1119
+ 'rate',
1120
+ 'slider',
1121
+ 'member',
1122
+ 'department'
1123
+ ] as const;
1124
+
1125
+ export type EditorPlatformControlType = (typeof EDITOR_PLATFORM_CONTROL_TYPES)[number];
1126
+
1054
1127
  /**
1055
1128
  * 打印方案 spec 内容语义版本(档案 `print.spec` 配套):官方表格编辑器现语义。
1056
1129
  * manifest `print_modes[].print_spec` 缺省即此值;编辑器在 `capabilities.editor.print_specs` 声明自己能解释的语义,
@@ -1156,6 +1229,12 @@ export interface EditorCapabilitiesDecl {
1156
1229
  profiles?: EditorProfile[];
1157
1230
  /** 能解释的打印方案 spec 语义版本(`<语义名>@<主版本>`,如 'paimon-fragment@1');非空须同时声明档案 'print.spec'。 */
1158
1231
  print_specs?: string[];
1232
+ /**
1233
+ * 无会话导出支持的格式(可选,只能随档案 'export.headless';不重复、写了不能为空)。不写 = 'xlsx' 与 'pdf' 都支持。tp.21 起。
1234
+ */
1235
+ export_formats?: EditorExportFormat[];
1236
+ /** 本编辑器能渲染的录入控件类型(可选,不重复);不写 = 不提供录入控件。tp.21 起。 */
1237
+ supported_controls?: EditorPlatformControlType[];
1159
1238
  /** sidecar 会话模式的帧类型 → 宿主转发 RPC 映射(可选,只能随 sidecar;留空项取缺省表,见 DEFAULT_EDITOR_SIDECAR_FRAMES)。tp.15 起。 */
1160
1239
  sidecar_frames?: EditorSidecarFramesDecl;
1161
1240
  }
@@ -21,6 +21,9 @@
21
21
  // 协议 v1(端口上的消息,与宿主沙箱框架宿主侧实现同口径):
22
22
  // 宿主 → 框架:init / props / result / cb / event / expose / destroy
23
23
  // 框架 → 宿主:call / mounted / mount-error / expose-result / resize / log
24
+ // log:{t:'log', level, message, stack?}——stack 为可选的错误调用栈(1.1.0-tp.21 起,框架内未捕获异常、
25
+ // 渲染错误、回调异常时附带,截断到 FRAME_LOG_STACK_MAX_LENGTH);脱敏由宿主在写入日志中心前统一做,
26
+ // 与宿主自身前端错误上报同口径。老宿主忽略该字段,老 SDK 不带,双向兼容。
24
27
  // 编码标记:{__kimpoFn:id, snap?}(宿主函数句柄 / 同步快照)、{__kimpoI18n:{…}}(宿主语言能力,可带 messages 词条快照)、
25
28
  // {__kimpoCb:id}(框架回调,作为调用参数传给宿主)。
26
29
  // 事件:{t:'event', kind:'i18n.locale', locale, messages?}(切语言,附新语言的词条快照)、
@@ -33,6 +36,21 @@ import type { SurfaceCreateInput, SurfaceMountResult } from './surface';
33
36
  /** 协议版本。 */
34
37
  export const FRAME_PROTOCOL_VERSION = 1;
35
38
 
39
+ /** 框架 log 消息里错误调用栈的长度上限(字符),与宿主前端错误上报的堆栈截断量一致。 */
40
+ const FRAME_LOG_STACK_MAX_LENGTH = 4000;
41
+
42
+ /** 取错误对象的调用栈(有字符串 stack 时),超长截断;取不到返回 undefined。按形状判断,不依赖 instanceof。 */
43
+ function frameErrorStack(error: unknown): string | undefined {
44
+ const stack = isRecord(error) ? error.stack : undefined;
45
+ if (typeof stack !== 'string' || !stack) return undefined;
46
+ return stack.length > FRAME_LOG_STACK_MAX_LENGTH ? stack.slice(0, FRAME_LOG_STACK_MAX_LENGTH) : stack;
47
+ }
48
+
49
+ /** 构造框架 → 宿主的 log 消息;没有调用栈时不带 stack 字段(与老版本消息形状一致)。 */
50
+ function frameLogMessage(level: 'info' | 'warn' | 'error', message: string, stack?: string): Record<string, unknown> {
51
+ return stack ? { t: 'log', level, message, stack } : { t: 'log', level, message };
52
+ }
53
+
36
54
  /** 框架文档 <meta name="kimpo-frame"> 携带的引导信息(宿主 frame 端点写入)。 */
37
55
  export interface KimpoFrameMeta {
38
56
  v: number;
@@ -274,7 +292,7 @@ export function createFrameClient(port: MessagePort) {
274
292
  try {
275
293
  fn(...((Array.isArray(msg.args) ? msg.args : []).map(arg => decode(arg))));
276
294
  } catch (error) {
277
- port.postMessage({ t: 'log', level: 'error', message: `callback failed: ${String(error)}` });
295
+ port.postMessage(frameLogMessage('error', `callback failed: ${String(error)}`, frameErrorStack(error)));
278
296
  }
279
297
  }
280
298
  return;
@@ -415,9 +433,16 @@ export function startKimpoFrameRuntime(options: FrameRuntimeOptions = {}): boole
415
433
 
416
434
  function bootOnPort(port: MessagePort, meta: KimpoFrameMeta, options: FrameRuntimeOptions, win: Window, doc: Document): void {
417
435
  const client = createFrameClient(port);
418
- const log = (level: 'info' | 'warn' | 'error', message: string) => client.post({ t: 'log', level, message });
419
- win.addEventListener('error', event => log('error', String((event as ErrorEvent).message ?? event)));
420
- win.addEventListener('unhandledrejection', event => log('error', `unhandled rejection: ${String((event as PromiseRejectionEvent).reason)}`));
436
+ // 框架内异常一律带调用栈上报宿主(宿主脱敏后写入日志中心,按插件归类)。
437
+ const log = (level: 'info' | 'warn' | 'error', message: string, stack?: string) => client.post(frameLogMessage(level, message, stack));
438
+ win.addEventListener('error', event => {
439
+ const errorEvent = event as ErrorEvent;
440
+ log('error', String(errorEvent.message ?? event), frameErrorStack(errorEvent.error));
441
+ });
442
+ win.addEventListener('unhandledrejection', event => {
443
+ const reason = (event as PromiseRejectionEvent).reason;
444
+ log('error', `unhandled rejection: ${String(reason)}`, frameErrorStack(reason));
445
+ });
421
446
 
422
447
  let app: ReturnType<FrameVueRuntime['createApp']> | undefined;
423
448
  let hostPropsState: { value: Record<string, unknown> } | undefined;
@@ -447,7 +472,7 @@ function bootOnPort(port: MessagePort, meta: KimpoFrameMeta, options: FrameRunti
447
472
  }
448
473
  };
449
474
  app = vue.createApp(Root);
450
- app.config.errorHandler = (error: unknown) => log('error', `render error: ${String(error)}`);
475
+ app.config.errorHandler = (error: unknown) => log('error', `render error: ${String(error)}`, frameErrorStack(error));
451
476
  app.mount(options.root ?? doc.getElementById('kimpo-frame-root') ?? doc.body);
452
477
  client.post({ t: 'mounted' });
453
478
  observeHeight(doc, win, height => client.post({ t: 'resize', height }));