@4399ywkf/editor 0.2.0 → 0.3.0

package/dist/docx.d.ts

@@ -1,9 +1,5 @@
 import { Node, Extension, JSONContent } from '@tiptap/core';
 
-declare const DocxField: Node<any, any>;
-
-declare const DocxInk: Node<any, any>;
-
 /**
  * OOXML → tiptap JSONContent。
  *
@@ -43,6 +39,59 @@ interface ParseDocxOptions {
     prosemirrorMarks?: Record<string, string>;
     /** 抽取文档默认样式为 CSS 字符串，对齐官方 `cssStyles` */
     cssStyles?: boolean;
+    /**
+     * 宿主正文列的宽度（px），用来把表格列宽从「Word 页面」换算到「编辑器版心」。
+     *
+     * Word 的列宽虽然是绝对磅值，但它是**相对页面文本宽度**定出来的：本文档的
+     * 表格 tblW=9026dxa，而页面文本宽度（pgSz − 左右 pgMar）也正好是 9026dxa ——
+     * 在 Word 里它铺满一行。照搬绝对值塞进更宽的编辑器版心，就成了缩在左边的窄表。
+     * 给了这个值就按比例重新落位：满宽的表继续满宽，半宽的表继续占一半。
+     * 不给则保持 Word 的绝对磅值（Node 侧无从测量时的默认）。
+     */
+    contentWidthPx?: number;
+    /**
+     * 宿主表格扩展的 `cellMinWidth`（px）。
+     *
+     * tiptap 渲染列宽时会做 `Math.max(colwidth, cellMinWidth)`，但表格总宽仍按
+     * 原始 colwidth 算 —— 于是窄列被顶宽、表格撑破、列比例还变了形。
+     * 告诉我们这个下限，就能提前把宽度摊匀，不让读端去顶。
+     */
+    minColumnWidthPx?: number;
+}
+interface DocxSectionRef {
+    kind: 'header' | 'footer';
+    /** `default` | `first` | `even` */
+    type: string;
+    /** 原 sectPr 里的 r:id */
+    rid: string;
+    /** 包内路径，如 `word/header1.xml` */
+    path: string;
+}
+/**
+ * 节属性（页眉页脚 + 页面几何），**原样**带出来。
+ *
+ * 为什么不解析成 JSONContent 再写回：编辑器没有页眉页脚这个概念，解析→重建
+ * 只会把我们看不懂的东西（域、图片、制表位、边框…）在往返中磨掉。这里存的是
+ * 原始字节和原始 XML，导出时塞回包里即可，磨不掉 —— 和 `docxInk` 存
+ * `strokesXml` 是同一个思路。
+ */
+interface DocxSection {
+    /**
+     * 原始 `<w:sectPr>` XML。导出时除了重写页眉页脚的 r:id，其余原样写回 ——
+     * 页面尺寸、页边距、页码格式、文档网格、首页不同都在里面。
+     */
+    sectPrXml: string | null;
+    refs: DocxSectionRef[];
+    /** 页眉页脚部件本身 + 各自的 .rels + 它们引用到的媒体，键是包内路径 */
+    files: Record<string, Uint8Array>;
+    /**
+     * 原始 `word/settings.xml`。
+     *
+     * 和页眉直接相关：`evenAndOddHeaders` 决定奇偶页是否用不同页眉，丢了它
+     * 奇偶页眉就失效。另外 `compatSetting compatibilityMode` 缺失会让 Word
+     * 按兼容模式打开文档（标题栏挂「兼容模式」，排版规则也退回旧版）。
+     */
+    settingsXml: string | null;
 }
 interface ParseDocxResult {
     doc: Record<string, unknown>;
@@ -51,9 +100,19 @@ interface ParseDocxResult {
     warnings: string[];
     /** `cssStyles: true` 时给出的文档默认样式 */
     css?: string;
+    /** 默认页眉的结构化内容（供宿主展示；往返靠的是 `section`，不是它） */
+    header: Record<string, unknown> | null;
+    /** 默认页脚的结构化内容，同上 */
+    footer: Record<string, unknown> | null;
+    /** 节属性原件，交给导出侧原样写回 */
+    section: DocxSection;
 }
 declare function parseDocx(entries: DocxEntries, opts: ParseDocxOptions): ParseDocxResult;
 
+declare const DocxField: Node<any, any>;
+
+declare const DocxInk: Node<any, any>;
+
 /**
  * tiptap JSONContent → .docx（OOXML）。
  *
@@ -64,6 +123,7 @@ declare function parseDocx(entries: DocxEntries, opts: ParseDocxOptions): ParseD
  * `docxInk` 写回 `w14:contentPart` + 位图回退 —— 这两样在导入时被保住，
  * 导出时才有东西可写。
  */
+
 interface SerializeOptions {
     /** 把图片 src 换成字节。返回 null 则该图片跳过并记警告 */
     resolveImage?: (src: string) => Uint8Array | null;
@@ -74,6 +134,25 @@ interface SerializeOptions {
     };
     /** 逐段落覆盖，对齐官方 paragraphOverrides */
     paragraphOverrides?: (node: Node_) => Record<string, string> | undefined;
+    /**
+     * 导入时带出来的节属性（`ParseDocxResult.section`），原样写回。
+     *
+     * 编辑器渲染不了页眉页脚，但只要把原始部件塞回包里，一趟往返就不会丢 ——
+     * 连同页面尺寸、页边距、页码格式、文档网格这些 sectPr 上的东西一起。
+     * 不给则退回默认的 A4 + 2.54cm 页边距，且没有页眉页脚。
+     */
+    section?: DocxSection;
+    /**
+     * 列宽所依据的编辑器版心宽度（px）—— 导入侧 `contentWidthPx` 的**逆变换**。
+     *
+     * 导入把 Word 的列宽按「占页面文本宽度的比例」重新落到了版心上，导出必须按
+     * 同样的比例还回去。只做单向的后果：708px 的表格被当成 708×15 = 10620 dxa 写出去，
+     * 而 A4 的页面文本宽度只有 9026 —— 表格在 Word 里冲出右边距、最后一列被切掉。
+     *
+     * 不给的话按 96dpi 直译（1px = 15dxa），但会**兜底裁到页面文本宽度以内**，
+     * 保证再怎么样也不会溢出页面。
+     */
+    contentWidthPx?: number;
 }
 interface SerializeResult {
     /** docx 包内的所有条目，交给 zip 打包 */
@@ -85,8 +164,20 @@ type Node_ = Record<string, any>;
 declare function serializeDocx(doc: Node_, opts?: SerializeOptions): SerializeResult;
 
 type ExportType = 'blob' | 'buffer' | 'string';
+/** 导出的伴随信息。官方回调只给结果本身，统计和警告拿不到 —— 这里作为第二个参数补上 */
+interface ExportDocxMeta {
+    stats: Record<string, number>;
+    warnings: string[];
+    /** 未压缩的字节数 */
+    bytes: number;
+}
 interface ExportDocxOptions extends SerializeOptions {
-    onCompleteExport: ((result: Blob | Uint8Array | string) => void) | null;
+    /**
+     * 导出完成回调。第一个参数的形状由 `exportType` 决定，对齐官方。
+     * 第二个参数是本扩展多给的统计与警告 —— 官方回调只给结果，
+     * 调用方拿不到「导出时丢了什么」，而那恰恰是最该看的。
+     */
+    onCompleteExport: ((result: Blob | Uint8Array | string, meta: ExportDocxMeta) => void) | null;
     exportType: ExportType;
     /** 诊断级别，同导入侧 */
     verbose: number;
@@ -146,6 +237,19 @@ interface ImportDocxOptions {
     preserveUnsupported: boolean;
     /** 是否注入浮动定位所需样式，默认 true */
     injectStyles: boolean;
+    /**
+     * 表格列宽的换算基准。
+     *
+     * Word 的列宽是相对**页面文本宽度**定的：铺满一行的表格，其 tblW 就等于
+     * 页宽减左右页边距。照搬这个绝对值塞进编辑器版心（往往更宽），表格就缩在
+     * 左边不铺满 —— 也就是「Word 里是自适应的，导进来却不是」。
+     *
+     * - `'auto'`（默认）：导入时量一下编辑器正文列的实际宽度，按比例重新落位。
+     *   满宽的表继续满宽，半宽的表继续占一半。
+     * - 数字：直接用这个宽度（px）当基准，SSR / 测试等量不到 DOM 的场景用。
+     * - `null`：不换算，保留 Word 的绝对磅值。
+     */
+    tableWidthBasis: number | 'auto' | null;
 }
 /** onImport 回调拿到的上下文，字段对齐官方 */
 interface ImportDocxContext {
@@ -159,8 +263,19 @@ interface ImportDocxContext {
     warnings: string[];
     /** cssStyles:true 时的文档默认样式 */
     css?: string;
+    /** 默认页眉的结构化内容。供宿主展示 —— 往返靠的是 `section`，不是它 */
     header: JSONContent | null;
+    /** 默认页脚的结构化内容，同上 */
     footer: JSONContent | null;
+    /**
+     * 节属性原件（页眉页脚部件 + 页面几何）。
+     *
+     * 编辑器渲染不了页眉页脚，所以它不进文档树；导出时把它交回
+     * `serializeDocx({ section })` 就能原样写回。同一个 editor 上同时挂了
+     * `ImportDocx` 和 `ExportDocx` 的话不用管 —— 导出侧会自动接上（见下）。
+     * 但它只活在内存里：刷新页面 / 换设备就没了，要跨会话往返得自己存。
+     */
+    section: DocxSection;
     footnotes: Record<string, JSONContent>;
     endnotes: Record<string, JSONContent>;
 }
@@ -181,4 +296,4 @@ declare module '@tiptap/core' {
 }
 declare const ImportDocx: Extension<ImportDocxOptions, any>;
 
-export { type DocxEntries, DocxField, DocxInk, ExportDocx, type ExportDocxOptions, type ExportType, type ImageUploadConfig, ImportDocx, type ImportDocxCommandArgs, type ImportDocxContext, type ImportDocxOptions, type ParseDocxOptions, type ParseDocxResult, type SerializeOptions, type SerializeResult, docxFromJSON, downloadDocx, parseDocx, serializeDocx };
+export { type DocxEntries, DocxField, DocxInk, type DocxSection, type DocxSectionRef, ExportDocx, type ExportDocxOptions, type ExportType, type ImageUploadConfig, ImportDocx, type ImportDocxCommandArgs, type ImportDocxContext, type ImportDocxOptions, type ParseDocxOptions, type ParseDocxResult, type SerializeOptions, type SerializeResult, docxFromJSON, downloadDocx, parseDocx, serializeDocx };