深入解析dolanmiu/docx中的Document对象使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00410/article/details/148508155

深入解析dolanmiu/docx中的Document对象使用指南

docx Easily generate and modify .docx files with JS/TS with a nice declarative API. Works for Node and on the Browser. 项目地址: https://gitcode.com/gh_mirrors/do/docx

什么是Document对象

在dolanmiu/docx库中，Document对象是创建Word文档的起点和核心容器。它相当于一个空白的Word文档，你可以向其中添加各种内容元素，如段落(Paragraphs)、表格(Tables)等，最终导出为.docx文件。

创建Document对象

创建一个新的Document对象非常简单：

const doc = new docx.Document();

这行代码就初始化了一个全新的Word文档对象，准备好接收各种内容。

文档属性设置

Document对象支持丰富的属性配置，这些属性会影响最终生成的Word文档的元数据和基础设置：

const doc = new docx.Document({
    creator: "文档作者",
    description: "这是一个示例文档",
    title: "我的文档",
});

完整属性列表

| 属性名称 | 类型 | 说明 | |------------------------------|----------------------------|--------------| | sections | ISectionOptions[] | 文档章节设置 | | title | string | 文档标题 | | subject | string | 文档主题 | | creator | string | 创建者 | | keywords | string | 关键词 | | description | string | 描述 | | lastModifiedBy | string | 最后修改者 | | revision | number | 修订版本号 | | externalStyles | string | 外部样式 | | styles | IStylesOptions | 样式设置 | | numbering | INumberingOptions | 编号设置 | | comments | ICommentsOptions | 批注设置 | | footnotes | Record<string, {...}> | 脚注设置 | | background | IDocumentBackgroundOptions | 背景设置 | | features | {...} | 功能特性 | | compatabilityModeVersion | number | 兼容模式版本 | | compatibility | ICompatibilityOptions | 兼容性设置 | | customProperties | ICustomPropertyOptions[]| 自定义属性 | | evenAndOddHeaderAndFooters | boolean | 奇偶页眉脚 | | defaultTabStop | number | 默认制表位 | | fonts | FontOptions[] | 字体设置 | | hyphenation | IHyphenationOptions | 断字设置 |

实用功能详解

设置文档背景色

你可以轻松地为整个文档设置背景颜色：

const doc = new docx.Document({
    background: {
        color: "FF0000", // 红色背景
    },
});

颜色值使用标准的十六进制格式，不需要前导的"#"符号。

单位系统说明

在设置位置相关的属性时，dolanmiu/docx使用的是"二十分之一磅"作为基本单位，这是Office Open XML(OOXML)规范中定义的标准单位。

1磅 = 20个单位
1英寸 = 72磅 = 1440个单位
1厘米 ≈ 567个单位

这种单位系统确保了在不同设备和分辨率下都能保持一致的显示效果。

兼容性设置详解

兼容性设置用于确保文档在不同版本的Word中能够保持一致的显示效果。dolanmiu/docx提供了丰富的兼容性选项：

const doc = new docx.Document({
    compatibility: {
        version: 15,  // 对应Word 2013
        doNotExpandShiftReturn: true,
    },
});

主要兼容性选项

| 选项名称 | 类型 | 说明 | |----------------------------------------|-----------|--------------------------------| | version | number | Word版本(15=2013,16=2016等) | | doNotExpandShiftReturn | boolean | 是否不扩展Shift+Enter换行 | | useSingleBorderforContiguousCells | boolean | 相邻单元格使用单一边框 | | wordPerfectJustification | boolean | 使用WordPerfect对齐方式 | | printColorsBlack | boolean | 打印时将所有颜色转为黑白 | | useWord97LineBreakRules | boolean | 使用Word 97的换行规则 | | growAutofit | boolean | 允许表格自动调整大小 |

这些选项可以精细控制文档在不同Word版本中的显示行为，确保文档的跨版本兼容性。