Word 结构化原生生成

fsys.openXml.docx.builder 将普通 aardio 内容模型生成可编辑的 DOCX。它不解析 HTML，不调用 Office、MSXML 或 .NET；通过公共 fsys.openXml.writer 写包、检查写入结果并原子提交。

适合程序组织报告、段落、编号和简单表格。Markdown 仍使用 string.markdown.toDocx：Markdown → 有限 HTML → 本生成器。不是完整 Word 排版引擎，也不是已有 Word 文档的编辑器。

最小示例

import fsys.openXml.docx.builder;
var document = {
    blocks = [
        {style="Heading1";text="工作报告"},
        {runs=[{text="结论：";bold=true},{text="正文与格式分开组织。"}]},
        {kind="table";rows=[["项目","数值"],["计数",0],["完成",false]]}
    ]
};
var path,err,report = fsys.openXml.docx.builder.write("/report.docx",document,{
    title = "工作报告";
    author = "aardio";
});
if(!path) return null,err;
return path,report;

write(path,document,options)：成功返回完整路径、null、report；失败返回 null、err，已经完成构建时第三返回值仍保留报告。扩展名必须是 .docx。
buildParts(document,options)：返回 {name,data} 部件数组、null、report；不进行文件 IO。可直接交给公共 writer。与 HTML 转换器旧接口返回的“部件名→XML”表不同。
normalizeOptions(options)：返回合并并检查后的新表，不修改输入或 defaults，供适配层复用公共纸张/字体规则。
已导入 fsys.openXml.docx 时，也可用 .write 便捷入口；只做生成时独立导入 builder，避免加载读取器。

document 只包含 blocks 和可选的 numbering。内容数组必须连续，空数组使用 []，不要用 null 作为占位元素。未知内容字段、未知块/运行类型、无效编号/书签引用会返回错误，不静默丢弃。

段落与文字

blocks 的普通字符串、数值、布尔值简写为一个段落；表对象省略 kind 时也表示段落。显式写法为 {kind="paragraph";...}。

字段	含义
`text` / `runs`	二选一。text 是字符串/数值/布尔值；runs 是格式化片段数组。未指定时为空段落
`style`	Normal、Heading1…Heading6、CodeBlock。标题是带大纲级别的真实 Word 样式
`align`	left、center、right、justify（兼容 Word 的 both）
`left/hanging`	左缩进/悬挂量，非负整数，单位 twips
`spaceBefore/spaceAfter`	段前/段后间距，twips；0 保留
`lineSpacing`	自动行距倍数
`keepNext/keepLines`	与下段同页/段中不分页，布尔值
`quote/rule`	简单左侧引用线/底部分隔线，使用公共边框颜色；同时设置时采用底线
`numId`	引用 document.numbering 的 1 基索引；不是直接填写显示的编号
`list`	无编号续段的紧凑段后间距；编号段落也自动采用紧凑间距

文字中的空格原样保留，不经过 HTML 实体解码。一个 text 内的 CRLF、LF、CR 转为软换行，TAB 转为制表符；要生成多个段落，使用多个 blocks。

0、false、空字符串分别生成 0、false 和空文字。XML 1.0 禁止的控制字符及 U+FFFE/U+FFFF 替换为 U+FFFD；非法 UTF-8 返回错误。标题和作者沿用 XML 文本的换行归一化规则。

格式化运行

import fsys.openXml.docx.builder;
var document = {blocks=[
    {runs=[
        {text="普通 "},
        {text="加粗";bold=true;color=0x0969DA},
        {text=" 标记";background=0xFFF8C5},
        {kind="tab"},
        {text="下一列"},
        {kind="break"},
        {text="软换行后的文字"}
    ]},
    {runs=[{kind="break";breakType="page"}]},
    {style="Heading1";text="新的一页"}
]};
return fsys.openXml.docx.builder.buildParts(document);

运行的 kind 默认为 text，另支持 tab、break、bookmark。breakType 默认为 line，也可为 page；不分页计算，只写入显式分页符。

文字运行可设置：

font/eastAsia：字体名；eastAsia 必须与 font 一起指定，省略则使用相同字体。不嵌入字体。
fontSize：磅，0.5～1638，输出到半磅精度。
bold/italic/strike/underline/noProof：布尔值；false 显式取消对应格式，不被假值兜底吞掉。
color/background：0xRRGGBB；黑色 0 合法，background=false 不写底色。
vert：superscript、subscript、baseline。
style：目前只支持 Hyperlink；设置 hyperlink 时默认采用此字符样式。
hyperlink：见下文。

编号、书签与超链接

import fsys.openXml.docx.builder;
var document = {
    numbering = [
        {kind="decimal";start=3;left=480},
        {kind="bullet";marker="•";left=960}
    ];
    blocks = [
        {style="Heading1";runs=[{kind="bookmark";name="Intro";id=1},{text="目录目标"}]},
        {text="第三步";numId=1},
        {text="第四步";numId=1},
        {text="子项";numId=2},
        {runs=[
            {text="返回标题";hyperlink={anchor="Intro"}},
            {text=" aardio";hyperlink="https://www.aardio.com/"}
        ]}
    ]
};
return fsys.openXml.docx.builder.buildParts(document);

每个编号定义是独立的单级列表。kind 为 decimal 或 bullet，start 默认 1，范围为 0～2147483647 的整数；不接受负起点。left 默认 480 twips，marker 默认 %1. 或 •；可用 font 指定编号字体。
同一 numId 的段落按序连续编号。重新起号需再建一个定义；嵌套层级用独立定义与不同缩进表示，不模拟完整多级章节编号。
编号段落缺省使用定义的 left、240 twips 的 hanging。显式填写可覆盖，0 也保留。
bookmark 是零长度书签；id 为 0～2147483647 的整数，name 是至多 40 个字母/数字/下划线组成、不能以数字开头的名称。同一文档中 id 和 name 均须唯一。
内部链接支持前向引用，但目标必须实际存在。外链仅允许 http、https、mailto；同一地址复用关系，不访问 URL、不下载文件、不执行脚本。地址中的保留字符建议按 URI 规则编码。

表格

import fsys.openXml.docx.builder;
var document = {blocks=[{
    kind="table";
    widths=[3000,5000];
    cellMargins={left=120;right=120;top=80;bottom=80};
    rows=[
        {header=true;cells=[
            {background=0xF6F8FA;blocks=[{runs=[{text="项目";bold=true}]}]},
            {background=0xF6F8FA;blocks=[{runs=[{text="说明";bold=true}]}]}
        ]},
        ["数值",0],
        ["状态",false],
        ["详情",{blocks=[{text="第一段"},{text="第二段";align="right"}]}]
    ]
}]};
return fsys.openXml.docx.builder.buildParts(document);

rows 至少一行，1～63 列。每行可为单元格数组，或 {header=true;cells=[...]}；header 写入跨页重复表头标记，不自动设置粗体/底色。
单元格可为字符串/数值/布尔值，或 {blocks=[...];background=...}；blocks 支持嵌套表格。生成器保证每个单元格以段落结束。
不齐行按最大列数补空单元格。数组内部不能留 null 洞；要留空请用空字符串或 {blocks=[]}。
widths 为正整数列宽数组，单位 twips；省略则均分当前可用宽度。显式宽度总和不能超出页面或父单元格；不自动计算文字排版或按内容撑开列。
left 指定整个表格的左缩进；cellMargins 默认四边 80 twips，可单独覆盖，0 合法。左右边距之和必须小于列宽。
borderColor 默认使用 options.colors.border，边框为简单 0.5 磅实线。
本入口暂不支持跨行/跨列合并。HTML 转换器继续按原策略将合并或过宽表格展开为文字，不把这一降级策略放进 Word 内核。

公共选项与保存

字体：font=Microsoft YaHei、monoFont=Consolas、symbolFont=Segoe UI Symbol；fontSize=11、codeFontSize=10（磅）。
行距：lineSpacing/codeLineSpacing=1.15；正文默认段后 160 twips，表格/列表默认段后 60 twips。
纸张：pageWidth=11906、pageHeight=16838（A4，twips）；margins 四边 1440；landscape=true 时将纵向宽高交换。
1 磅 = 20 twips。页宽、页高、页边距不是屏幕像素，不随显示器 DPI 改变。
colors 包含 text、muted、link、border、codeBackground、codeText、inlineCode、inlineCodeBackground、tableHeaderBackground、mark，颜色均为 0xRRGGBB。inlineCodeBackground=false 可关闭 HTML 适配器的行内代码底色。
title/author 为核心属性。overwrite 默认 false；true 仅表示明确允许替换目标，不会把旧文件先清空。
writer 的 level、maxEntries、maxPartBytes、maxWriteBytes、protectPaths 可透传。默认每部件 16 MiB、总写入 128 MiB；失败不留下半成品目标。buildParts 只构建内存部件，写包限额由 write 阶段检查。

defaults 可修改，但与 string.html.toDocx 的默认表独立；后者与 string.markdown.toDocx 仍共用同一个表。

边界

当前只生成一个正文节、预定义样式与上述内容。没有页眉页脚、图片嵌入、跨格合并、浮动图形、修订、自动目录、公式/域计算、字体嵌入或既有 DOCX 编辑。内容模型拒绝这些未支持字段；不会通过 altChunk 把 HTML 留给 Word 临时转换。

report 包含 paragraphCount、tableCount、listCount、warnings。段落统计包括内核自动补充的必需空段落，listCount 是编号定义数，warnings 当前为空；不是页数/分页预检。HTML 包装继续返回它原来的计数和降级报告，不混用两种统计口径。

文档嵌套最多 128 层，内容节点最多 200000；这不是完整的解析内存上限。实际字体、换行和分页由阅读软件决定。需要修改已有文档或高保真渲染时，可继续使用 Office/WPS COM。

Markdown 格式