@gct-paas/word 0.1.15 → 0.1.17

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.
Files changed (35) hide show
  1. package/README.md +274 -15
  2. package/dist/base/divider/src/divider.vue.d.ts +1 -1
  3. package/dist/base/select/src/basic-select.vue.d.ts +2 -1
  4. package/dist/core/command/commands/Delete2DTable.d.ts +1 -1
  5. package/dist/core/command/commands/MergeCells.d.ts +6 -1
  6. package/dist/core/command/commands/UnmergeCells.d.ts +6 -1
  7. package/dist/core/command/types.d.ts +1 -0
  8. package/dist/core/model/document/Wbackground.d.ts +22 -0
  9. package/dist/core/model/document/Wdocument.d.ts +5 -1
  10. package/dist/core/model/document/Wp.d.ts +6 -0
  11. package/dist/core/model/document/WrImage.d.ts +2 -0
  12. package/dist/core/model/document/WrText.d.ts +4 -0
  13. package/dist/core/model/document/WsecPr.d.ts +5 -0
  14. package/dist/core/model/document/Wtbl/Calculation.d.ts +2 -2
  15. package/dist/core/model/document/Wtbl/Serialization.d.ts +12 -0
  16. package/dist/core/model/document/Wtbl.d.ts +8 -0
  17. package/dist/core/model/document/Wtc.d.ts +46 -4
  18. package/dist/core/model/document/WtrPr.d.ts +1 -0
  19. package/dist/core/model/document/index.d.ts +1 -0
  20. package/dist/core/model/logic/CheckTableRegion.d.ts +1 -1
  21. package/dist/core/model/logic/_2DTableRegion.d.ts +1 -1
  22. package/dist/core/model/templates/paragraph.template.d.ts +46 -0
  23. package/dist/core/model/templates/trPr.template.d.ts +19 -0
  24. package/dist/core/utils/expand.d.ts +2 -1
  25. package/dist/core/view/Section.d.ts +5 -0
  26. package/dist/core/view/Table.d.ts +9 -0
  27. package/dist/core/view/TableCell.d.ts +3 -1
  28. package/dist/index.es.js +1502 -1030
  29. package/dist/runtime/canvas/inline-image/resize-box.vue.d.ts +8 -3
  30. package/dist/sdk/doc-runtime/factories/runtime-json-builder.d.ts +17 -0
  31. package/dist/sdk/doc-runtime/useWord.d.ts +4 -0
  32. package/dist/sdk/types/index.d.ts +45 -10
  33. package/dist/suites/shared/panel/modules/field-formula-module/field-formula-module.vue.d.ts +13 -0
  34. package/dist/word.css +124 -124
  35. package/package.json +1 -1
package/README.md CHANGED
@@ -1,35 +1,294 @@
1
1
  # @gct-paas/word
2
2
 
3
- GCT 在线 Word 文档编辑器组件库。
3
+ GCT 在线 Word 文档引擎与 Vue 组件 SDK,用于在业务系统中接入文档设计、渲染与表单填报能力。
4
+
5
+ ## 适用场景
6
+
7
+ - 需要在 Vue 3 项目中嵌入在线文档设计器/预览器
8
+ - 需要统一接入文档实例、模板、填报数据能力
9
+ - 需要通过插件机制扩展套件能力(如 `edhr`)
10
+
11
+ ## 环境要求
12
+
13
+ - Node.js >= 18
14
+ - Vue 3
4
15
 
5
16
  ## 安装
6
17
 
7
18
  ```bash
8
- npm install @gct-paas/word
9
- # 或
10
19
  pnpm add @gct-paas/word
11
20
  ```
12
21
 
13
- ## 使用
22
+ 或:
23
+
24
+ ```bash
25
+ npm install @gct-paas/word
26
+ ```
27
+
28
+ 或:
29
+
30
+ ```bash
31
+ yarn add @gct-paas/word
32
+ ```
33
+
34
+ ## 依赖与样式
35
+
36
+ 请在宿主项目中安装/确保以下 peer dependencies 可用(以 `package.json` 为准),包括但不限于:
37
+
38
+ - `vue`
39
+ - `floating-vue`
40
+ - `vue-konva`
41
+ - `konva`
42
+ - `vxe-table`
43
+ - `vuedraggable`
44
+ - `sortablejs`
45
+ - `crypto-js`
46
+ - `jspdf`
47
+ - `qrcode`
48
+ - `jsbarcode`
49
+ - `exifr`
50
+
51
+ 同时引入样式文件:
52
+
53
+ ```ts
54
+ import '@gct-paas/word/style.css';
55
+ ```
56
+
57
+ ## 快速开始
58
+
59
+ 下面示例展示从初始化宿主适配器,到创建运行时,再到挂载渲染组件的完整流程。
14
60
 
15
- ```typescript
16
- import { GctPaasWord } from '@gct-paas/word';
61
+ ```ts
62
+ import { createApp, defineComponent } from 'vue';
63
+ import {
64
+ setupPlatformAdapters,
65
+ setupVueRuntime,
66
+ useWord,
67
+ DocRenderLayout,
68
+ edhrSuitePlugin,
69
+ } from '@gct-paas/word';
17
70
  import '@gct-paas/word/style.css';
18
71
 
19
- // 在你的应用中使用该组件
72
+ // 1) 应用全局初始化(整个应用生命周期调用一次)
73
+ setupPlatformAdapters({
74
+ interceptors: {
75
+ requestInterceptors: (config: any) => config,
76
+ requestInterceptorsCatch: (error: any) => Promise.reject(error),
77
+ responseInterceptors: (response: any) => response,
78
+ responseInterceptorsCatch: (error: any) => Promise.reject(error),
79
+ },
80
+ getAppInfo: async () => ({}),
81
+ parseFile: async (file: File) => file,
82
+ uploadFile: async (file: File) => ({ url: '', name: file.name }),
83
+ formulaIdentify: async () => [],
84
+ formulaCalculate: async () => ({}),
85
+ triggerHandler: async () => void 0,
86
+ plugins: [edhrSuitePlugin],
87
+ });
88
+
89
+ const Root = defineComponent({
90
+ name: 'WordDemo',
91
+ components: { DocRenderLayout },
92
+ setup() {
93
+ // 2) 创建文档运行时
94
+ const { controller, docInfo } = useWord(
95
+ {
96
+ requestId: 'your-request-id',
97
+ materialNo: 'optional-material-no',
98
+ requestQuery: {},
99
+ },
100
+ {
101
+ factoryType: 'instance', // 'template' | 'instance'
102
+ modelKey: 'fm_your_model_key',
103
+ suiteKey: 'edhr',
104
+ isPreview: true,
105
+ },
106
+ );
107
+
108
+ return { controller, docInfo };
109
+ },
110
+ template: `
111
+ <div style="height: 100vh;">
112
+ <DocRenderLayout />
113
+ </div>
114
+ `,
115
+ });
116
+
117
+ const app = createApp(Root);
118
+
119
+ // 3) Vue 运行时初始化(createApp 后调用)
120
+ setupVueRuntime({ app });
121
+ app.mount('#app');
122
+ ```
123
+
124
+ ## 初始化 API
125
+
126
+ ### `setupPlatformAdapters(options)`
127
+
128
+ 平台适配器注册函数。用于将宿主系统能力注入 SDK,全局只需调用一次。
129
+
130
+ `options` 关键字段:
131
+
132
+ - `interceptors`:HTTP 请求拦截器配置
133
+ - `getAppInfo`:获取应用信息/默认上下文
134
+ - `parseFile`:文件解析方法
135
+ - `uploadFile`:文件上传方法
136
+ - `formulaIdentify?`:公式变量识别(可选)
137
+ - `formulaCalculate?`:公式计算(可选)
138
+ - `triggerHandler?`:触发主工程交互(可选)
139
+ - `plugins?`:要安装的 suite 插件列表(如 `edhrSuitePlugin`)
140
+
141
+ ### `setupVueRuntime({ app })`
142
+
143
+ Vue 运行时注册函数。建议在 `createApp` 后、`mount` 前调用。
144
+
145
+ 作用:
146
+
147
+ - 注册 `FloatingVue`
148
+ - 注册 `VueKonva`
149
+ - 注册 SDK 所需全局指令
150
+
151
+ ## 核心运行时 API
152
+
153
+ ### `useWord(props, options)`
154
+
155
+ 文档运行时主入口,返回 `WordRuntime`。
156
+
157
+ - `props.requestId`:文档实例 ID 或模板 ID(支持函数形式)
158
+ - `options.factoryType`:`'template' | 'instance'`
159
+ - `options.modelKey`:主模型 key
160
+ - `options.suiteKey?`:套件 key(默认常用 `edhr`)
161
+ - `options.isPreview?` / `options.isDetailPage?` / `options.renderModeType?`:运行模式控制
162
+
163
+ 返回值:
164
+
165
+ - `controller`:`ShallowRef<DocController | null>`
166
+ - `docInfo`:`Ref<DocInfo>`
167
+
168
+ ### `DocController`(对外 API 清单)
169
+
170
+ `controller.value` 可用后,主要分为 4 类能力:
171
+
172
+ 1) 状态字段(响应式):
173
+
174
+ - `id: string`:当前文档实例 id
175
+ - `mode`:当前渲染模式
176
+ - `modeLabel`:渲染模式文案
177
+ - `updateTick`:布局刷新计数
178
+ - `pages`:当前页面数组
179
+ - `docRuntimeMeta`:运行时元信息(接口返回 + 业务拼接)
180
+
181
+ 2) 查询 API(只读):
182
+
183
+ - `query.getWidgetByModelId(modelId)`:按模型字段 id 定位组件节点
184
+ - `query.getPaperBySecRefId(id)`:按分节 refId 定位页面
185
+
186
+ 3) 编辑/控制 API:
187
+
188
+ - `execute(command, payload?)`:执行内置命令(高级)
189
+ - `undo()` / `redo()`:撤销与重做
190
+ - `setMode(mode)`:切换渲染模式
191
+ - `setModel(model)`:替换当前文档模型
192
+ - `rawData()`:获取原始填报数据
193
+ - `reload()`:手动触发文档重载
194
+
195
+ 4) 数据处理 API:
196
+
197
+ - `validate()`:校验字段,返回错误映射或 `null`
198
+ - `exportModel()`:导出 XmlJson 模型数据
199
+ - `getDocumentAttachmentPaths(types?)`:提取附件路径列表
200
+ - `enterBaseline(uniqueId)`:记录基线并进入填报模式
201
+ - `computeBaselineChanges(ctx)`:计算与基线差异
202
+ - `setAnnotation(ids, list)`:设置批注
203
+
204
+ 示例:
205
+
206
+ ```ts
207
+ const c = controller.value;
208
+ if (!c) return;
209
+
210
+ const errors = await c.validate();
211
+ if (!errors) {
212
+ const model = c.exportModel();
213
+ const data = c.rawData();
214
+ const files = c.getDocumentAttachmentPaths();
215
+ console.log(model, data, files);
216
+ }
217
+ ```
218
+
219
+ ## 对外导出(主入口)
220
+
221
+ 当前包主入口为 `@gct-paas/word`,可直接使用以下能力:
222
+
223
+ - 初始化 API:`setupPlatformAdapters`、`setupVueRuntime`
224
+ - 引擎/类型:`useWord`、`DocModeTypeConst`、`PageSizeEnumConst`、`BuiltinComponentTypeConst`、`WordRuntime`、`DocController` 等
225
+ - Vue 组件:`DocDesignLayout`、`DocRenderLayout`、`GctLayout`
226
+ - 插件能力:`registerSuite`、`WordSuitePlugin`、`edhrSuitePlugin`
227
+
228
+ ## 插件扩展
229
+
230
+ ### 方式一:在 `setupPlatformAdapters` 里批量注册(推荐)
231
+
232
+ ```ts
233
+ import { setupPlatformAdapters, edhrSuitePlugin } from '@gct-paas/word';
234
+
235
+ setupPlatformAdapters({
236
+ interceptors,
237
+ getAppInfo,
238
+ parseFile,
239
+ uploadFile,
240
+ plugins: [edhrSuitePlugin],
241
+ });
242
+ ```
243
+
244
+ ### 方式二:手动调用 `registerSuite`
245
+
246
+ ```ts
247
+ import { registerSuite, edhrSuitePlugin } from '@gct-paas/word';
248
+
249
+ registerSuite(edhrSuitePlugin);
20
250
  ```
21
251
 
22
- ## 功能特性
252
+ ### 自定义插件协议
253
+
254
+ ```ts
255
+ import type { WordSuitePlugin } from '@gct-paas/word';
256
+
257
+ const customPlugin: WordSuitePlugin = {
258
+ key: 'custom-suite',
259
+ install() {
260
+ // 在这里注册你的 suite 能力
261
+ },
262
+ };
263
+ ```
264
+
265
+ ## 最佳实践
266
+
267
+ - `setupPlatformAdapters` 只在应用启动时调用一次,避免重复注册全局能力。
268
+ - 在 `createApp` 之后立即执行 `setupVueRuntime`,再调用 `mount`。
269
+ - `uploadFile`、`parseFile`、`getAppInfo` 建议提供稳定兜底实现,避免运行时空函数导致异常。
270
+ - 通过 `controller` 调用业务动作前,先判断 `controller.value` 是否已就绪。
271
+
272
+ ## 常见问题
273
+
274
+ ### 1) 组件渲染空白
275
+
276
+ - 检查是否已引入 `@gct-paas/word/style.css`
277
+ - 检查是否调用了 `setupVueRuntime({ app })`
278
+ - 检查容器是否有明确高度(例如 `height: 100vh`)
279
+
280
+ ### 2) 数据加载失败
23
281
 
24
- - 基于 Vue 3 的在线文档编辑器
25
- - 支持表格、图片等多种内容
26
- - 完整的布局和渲染系统
27
- - 可扩展的组件架构
282
+ - 检查 `requestId`、`factoryType`、`modelKey` 是否匹配当前业务接口
283
+ - 检查 `interceptors` 与鉴权逻辑是否正确透传
284
+ - 检查 `getAppInfo`、`requestQuery` 是否包含业务必需上下文
28
285
 
29
- ## 文档
286
+ ### 3) 插件能力未生效
30
287
 
31
- 详见 [docs](./docs) 目录
288
+ - 检查插件是否执行了 `install()`
289
+ - 检查是否在 `setupPlatformAdapters` 初始化阶段完成注册
290
+ - 检查 `suiteKey` 与已注册插件 `key` 是否一致
32
291
 
33
- ## 许可证
292
+ ## License
34
293
 
35
294
  MIT
@@ -7,8 +7,8 @@ declare function __VLS_template(): {
7
7
  };
8
8
  type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
9
9
  declare const __VLS_component: import('vue').DefineComponent<IDividerProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<IDividerProps> & Readonly<{}>, {
10
- color: string;
11
10
  vertical: boolean;
11
+ color: string;
12
12
  }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
13
13
  declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
14
14
  export default _default;
@@ -48,6 +48,7 @@ declare function __VLS_template(): {
48
48
  M: {};
49
49
  Defaults: {};
50
50
  }, Record<string, any> & {}, {}, {}, {}, {}, {}> | null;
51
+ triggerRef: HTMLDivElement;
51
52
  };
52
53
  rootEl: HTMLDivElement;
53
54
  };
@@ -65,7 +66,6 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {
65
66
  }>, {
66
67
  options: DropdownOption[];
67
68
  placeholder: string;
68
- popperWidth: number;
69
69
  }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
70
70
  dropdownRef: import('vue').CreateComponentPublicInstanceWithMixins<Record<string, any> & {}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, import('vue').PublicProps, {}, false, {}, {}, {}, {}, string, {}, any, import('vue').ComponentProvideOptions, {
71
71
  P: {};
@@ -75,6 +75,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {
75
75
  M: {};
76
76
  Defaults: {};
77
77
  }, Record<string, any> & {}, {}, {}, {}, {}, {}> | null;
78
+ triggerRef: HTMLDivElement;
78
79
  }, HTMLDivElement>;
79
80
  declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
80
81
  export default _default;
@@ -4,7 +4,7 @@ import { CommandBase, PostCommandContext } from '../base/CommandBase';
4
4
  /**
5
5
  * 删除二维表命令
6
6
  *
7
- * 删除指定的 _2DTable 区域
7
+ * 删除指定的 2d-table 区域
8
8
  */
9
9
  export declare class Delete2DTable extends CommandBase<'delete2DTable'> {
10
10
  constructor(doc: Doc, payload?: CommandPayloadMap['delete2DTable']);
@@ -1,7 +1,12 @@
1
1
  import { CommandBase } from '../base/CommandBase';
2
2
  import { Doc } from '../../view/Doc';
3
+ import { WrText } from '../../model/document';
3
4
  import { CommandPayloadMap } from '../types';
4
5
  export declare class MergeCells extends CommandBase<'mergeCells'> {
5
6
  constructor(doc: Doc, payload?: CommandPayloadMap['mergeCells']);
6
- protected execute(): Promise<null>;
7
+ protected execute(): Promise<{
8
+ wr: WrText | undefined;
9
+ pos: number;
10
+ side: string;
11
+ } | null>;
7
12
  }
@@ -1,7 +1,12 @@
1
1
  import { CommandBase } from '../base/CommandBase';
2
2
  import { Doc } from '../../view/Doc';
3
+ import { WrText } from '../../model/document';
3
4
  import { CommandPayloadMap } from '../types';
4
5
  export declare class UnmergeCells extends CommandBase<'unmergeCells'> {
5
6
  constructor(doc: Doc, payload?: CommandPayloadMap['unmergeCells']);
6
- protected execute(): Promise<null | undefined>;
7
+ protected execute(): Promise<{
8
+ wr: WrText | undefined;
9
+ pos: number;
10
+ side: string;
11
+ } | null | undefined>;
7
12
  }
@@ -108,6 +108,7 @@ export type CommandPayloadMap = {
108
108
  enter: CommandPayload & Record<string, never>;
109
109
  setOrient: CommandPayload & {
110
110
  orient: VOrientationType;
111
+ serRefId: string;
111
112
  };
112
113
  setPadding: CommandPayload & {
113
114
  padding: [number, number, number, number];
@@ -0,0 +1,22 @@
1
+ import { RawElement } from '../types/raw';
2
+ import { ModelNode, ModelNodeOptions } from '../base';
3
+ export declare class Wbackground extends ModelNode {
4
+ /** 节点名称 */
5
+ name: 'w:background';
6
+ /** 节点类型 */
7
+ type: "element";
8
+ constructor(options: ModelNodeOptions);
9
+ /**
10
+ * 从原始 XML JSON 转换为 Wbackground 实例
11
+ *
12
+ * @param json - 原始 XML JSON 数据
13
+ * @returns Wbackground 实例
14
+ */
15
+ static fromXmlJson(json: RawElement): Wbackground;
16
+ /**
17
+ * 将 Wbackground 实例转换为原始 XML JSON
18
+ *
19
+ * @returns RawElement 格式的 XML JSON
20
+ */
21
+ toXmlJson(): RawElement;
22
+ }
@@ -1,5 +1,6 @@
1
1
  import { RawElement } from '../types/raw';
2
2
  import { Wbody } from './Wbody';
3
+ import { Wbackground } from './Wbackground';
3
4
  import { ModelGroup, ModelGroupOptions } from '../base';
4
5
  import { DocModel } from '../DocModel';
5
6
  /**
@@ -15,10 +16,13 @@ export declare class Wdocument extends ModelGroup<Wbody> {
15
16
  name: 'w:document';
16
17
  /** 节点类型 */
17
18
  type: "element";
19
+ background?: Wbackground;
18
20
  /** 配置对象 */
19
21
  config?: Record<string, any>;
20
22
  parent?: DocModel;
21
- constructor(options: ModelGroupOptions<Wbody>);
23
+ constructor(options: ModelGroupOptions<Wbody> & {
24
+ background?: Wbackground;
25
+ });
22
26
  get body(): Wbody;
23
27
  /**
24
28
  * 从原始 XML JSON 转换为 Wdocument 实例
@@ -61,4 +61,10 @@ export declare class Wp extends ModelGroup {
61
61
  * wp.setAlignment('center');
62
62
  */
63
63
  setAlignment(alignment: string): void;
64
+ /**
65
+ * 从模板创建段落
66
+ * @param width 单元格宽度(DXA/缇)
67
+ * @returns Wtc 实例
68
+ */
69
+ static fromTemplate(): Wp;
64
70
  }
@@ -48,6 +48,8 @@ export declare class WrImage extends ModelNode {
48
48
  * // before: null,after: this(图片作为整体保留)
49
49
  */
50
50
  splitAt(index: number): [WrImage | null, WrImage | null];
51
+ /** 需要进行拼接成运行时的 modelId */
52
+ cloneWithSuffix(suffix: string, index: string | undefined): WrImage;
51
53
  /**
52
54
  * 从原始 XML JSON 转换为 WrImage 实例
53
55
  * @param json w:r XML JSON 对象
@@ -106,6 +106,10 @@ export declare class WrText extends ModelNode {
106
106
  * // n 为 null,all 为 this(无分割)
107
107
  */
108
108
  splitAt(index: number): [WrText | null, WrText | null];
109
+ /** 需要使用运行时的 modelId */
110
+ cloneWithId(id: string): WrText;
111
+ /** 需要进行拼接成运行时的 modelId */
112
+ cloneWithSuffix(suffix: string, index: string | undefined): WrText;
109
113
  /**
110
114
  * 从原始 XML JSON 转换为 WrText 实例
111
115
  * @param json w:r XML JSON 对象
@@ -119,6 +119,11 @@ export declare class WsecPr extends ModelNode {
119
119
  * 重新计算浮层引用,并写回 raw
120
120
  */
121
121
  normalizeOverlayRefs(refs: string[], secIds: string[]): void;
122
+ /**
123
+ * 获取当前页面方向
124
+ * @returns 'portrait' | 'landscape' | null
125
+ */
126
+ getOrient(): 'portrait' | 'landscape' | null;
122
127
  setOrient(val: 'portrait' | 'landscape'): void;
123
128
  /**
124
129
  * 设置为横向(宽 > 高)
@@ -13,7 +13,7 @@ export declare class WtblCalculation {
13
13
  */
14
14
  private static processRepeating;
15
15
  /**
16
- * 处理 _2DTable 数据
16
+ * 处理 2d-table 数据
17
17
  */
18
18
  private static process2DTable;
19
19
  /**
@@ -25,7 +25,7 @@ export declare class WtblCalculation {
25
25
  */
26
26
  private static processBoundedItem;
27
27
  /**
28
- * 处理 checkTable 数据
28
+ * 处理 check-table 数据
29
29
  */
30
30
  private static processCheckTable;
31
31
  /**
@@ -1,5 +1,7 @@
1
1
  import { RawElement } from '../../types/raw';
2
+ import { Wtr } from '../Wtr';
2
3
  import { Wtbl } from '../Wtbl';
4
+ import { Wtc } from '../Wtc';
3
5
  /**
4
6
  * 表格序列化功能类
5
7
  * 提供 XML 转换、快照序列化等功能
@@ -17,4 +19,14 @@ export declare class WtblSerialization {
17
19
  * 在指定行索引处断开表格
18
20
  */
19
21
  static splitAt(table: Wtbl, index: number): [Wtbl | null, Wtbl | null];
22
+ static getCell(rows: Wtr[], rowIndex: number, col: number): Wtc | undefined;
23
+ static findCellById(rows: Wtr[], cellId: string): Wtc | null;
24
+ /**
25
+ * 给起始单元格设置 rowspan
26
+ */
27
+ static applyRowspan(rows: Wtr[], rowIndex: number, col: number, rowspan: number): void;
28
+ /**
29
+ * 获取最大列数
30
+ */
31
+ static getMaxCols(rows: Wtr[]): number;
20
32
  }
@@ -14,6 +14,8 @@ export declare class Wtbl extends ModelGroup {
14
14
  parent?: Wbody;
15
15
  children: Wtr[];
16
16
  private pendingRecalculate;
17
+ private mutationDepth;
18
+ private mutationNeedsRecalculate;
17
19
  constructor(options: ModelGroupOptions & {
18
20
  tblPr?: WtblPr;
19
21
  colWidths?: number[];
@@ -38,6 +40,12 @@ export declare class Wtbl extends ModelGroup {
38
40
  * 在微任务队列中安排一次重算,同一事件循环内的多次操作会自动合并
39
41
  */
40
42
  scheduleRecalculate(): void;
43
+ runConsistencyMutation(options: {
44
+ validate?: () => void;
45
+ mutate: () => void;
46
+ syncRefs?: () => void;
47
+ finalize?: () => void;
48
+ }): void;
41
49
  static fromXmlJson(json: RawElement): Wtbl;
42
50
  toXmlJson(): RawElement;
43
51
  /**
@@ -3,6 +3,7 @@ import { Wtr } from './Wtr';
3
3
  import { Wp } from './Wp';
4
4
  import { ModelGroup, ModelGroupOptions } from '../base';
5
5
  import { Wtbl } from './Wtbl';
6
+ export declare const WTC_REF_KEYS: string[];
6
7
  /**
7
8
  * w:tc 表格单元格
8
9
  */
@@ -13,6 +14,7 @@ export declare class Wtc extends ModelGroup {
13
14
  tcPrRaw?: RawElement;
14
15
  colspan?: number;
15
16
  rowspan?: number;
17
+ backgroundColor?: string;
16
18
  mergeFromId?: string;
17
19
  mergeId?: string;
18
20
  repeatingId?: string;
@@ -23,6 +25,7 @@ export declare class Wtc extends ModelGroup {
23
25
  dataGroup2DId?: string;
24
26
  headerId?: string;
25
27
  vMergeType?: 'restart' | 'continue';
28
+ tempMergeId?: string;
26
29
  constructor(options: ModelGroupOptions & {
27
30
  tcPrRaw?: RawElement;
28
31
  colspan?: number;
@@ -36,13 +39,46 @@ export declare class Wtc extends ModelGroup {
36
39
  checkTableId?: string;
37
40
  dataGroup2DId?: string;
38
41
  headerId?: string;
42
+ backgroundColor?: string;
39
43
  vMergeType?: 'restart' | 'continue';
44
+ tempMergeId?: string;
40
45
  });
41
46
  get table(): Wtbl;
42
- get isMerged(): boolean;
47
+ /** 是否是被合并单元格 */
48
+ get isMergeSlave(): boolean;
49
+ /** 是否是合并起始单元格 */
50
+ get isMergeStart(): boolean;
43
51
  get contents(): Wp[];
44
52
  get firstContent(): Wp | undefined;
45
53
  get lastContent(): Wp | undefined;
54
+ get cellMergeInfo(): {
55
+ /** 是否属于合并单元格(不包括起点的) */
56
+ isMerged: boolean;
57
+ /** 合并方向 */
58
+ direction: 'horizontal' | 'vertical' | null;
59
+ /** 当前单元格在 XML 生成时是否需要跳过 */
60
+ skip: boolean;
61
+ /** 合并来源位置(左上角) */
62
+ from: null | {
63
+ row: number;
64
+ col: number;
65
+ };
66
+ /** 合并区域尺寸 */
67
+ span: null | {
68
+ rows: number;
69
+ cols: number;
70
+ };
71
+ /**
72
+ * 当前单元格是否是“某一行的起点”
73
+ * 用于决定是否输出 w:gridSpan
74
+ */
75
+ isRowStart: boolean;
76
+ /**
77
+ * 当前单元格是否是“整个合并区域的起点(左上角)”
78
+ * 用于决定 vMerge restart
79
+ */
80
+ isRoot: boolean;
81
+ };
46
82
  /**
47
83
  * 查找当前单元格对应的区域
48
84
  * @returns
@@ -63,7 +99,9 @@ export declare class Wtc extends ModelGroup {
63
99
  * ├── w:tcPr(如果存在)
64
100
  * └── w:p(所有段落子元素)
65
101
  */
66
- toXmlJson(): RawElement;
102
+ toXmlJson(): RawElement | null;
103
+ private buildTcPr;
104
+ private static normalizeWordColor;
67
105
  /**
68
106
  * 从模板创建单元格
69
107
  * @param width 单元格宽度(DXA/缇)
@@ -95,7 +133,9 @@ export declare class Wtc extends ModelGroup {
95
133
  * // 支持链式调用
96
134
  * cell.merge(2, 3).merge(1, 2);
97
135
  */
98
- merge(rowSpan: number, colSpan: number): this;
136
+ merge(rowSpan: number, colSpan: number, options?: {
137
+ skipConsistency?: boolean;
138
+ }): this;
99
139
  /**
100
140
  * 取消当前单元格的合并状态
101
141
  *
@@ -117,5 +157,7 @@ export declare class Wtc extends ModelGroup {
117
157
  * const cell = table.rows[1].cells[0]; // rowspan=2, colspan=2
118
158
  * cell.unmerge(); // 覆盖范围内的所有单元格恢复为独立状态
119
159
  */
120
- unmerge(): void;
160
+ unmerge(options?: {
161
+ skipConsistency?: boolean;
162
+ }): void;
121
163
  }
@@ -51,4 +51,5 @@ export declare class WtrPr extends ModelNode {
51
51
  * wpPr.removeElement('w:keepNext');
52
52
  */
53
53
  removeElement(name: string): boolean;
54
+ static fromTemplate(): WtrPr;
54
55
  }
@@ -1,5 +1,6 @@
1
1
  export { Wdocument } from './Wdocument';
2
2
  export { Wbody } from './Wbody';
3
+ export { Wbackground } from './Wbackground';
3
4
  export { Wp } from './Wp';
4
5
  export type { Wr } from './Wp';
5
6
  export { WrText } from './WrText';
@@ -25,7 +25,7 @@ export type CheckTableRegionJson = RegionJson & {
25
25
  itemRegion?: any;
26
26
  };
27
27
  export declare class CheckTableRegion extends Region {
28
- type: "checkTable";
28
+ type: "check-table";
29
29
  name: string;
30
30
  valuePath: string;
31
31
  widgetMeta: CheckTableWidgetMeta;
@@ -25,7 +25,7 @@ export type _2DTableRegionJson = RegionJson & {
25
25
  itemRegion?: any;
26
26
  };
27
27
  export declare class _2DTableRegion extends Region {
28
- type: "_2DTable";
28
+ type: "2d-table";
29
29
  name: string;
30
30
  valuePath: string;
31
31
  widgetMeta: _2DTableWidgetMeta;