Word 加载项教程

在本教程中，将创建 Word 任务窗格加载项，该加载项将：

提示

如果已完成了创建首个 Word 任务窗格加载项快速入门，并希望使用该项目作为本教程的起点，请直接转到插入文本区域以开始此教程。

如果需要本教程的完整版本，请转到 GitHub 上的 Office 外接程序示例存储库。

Node.js（最新LTS 版本）。 访问 Node.js 站点 ，下载并安装适合你的操作系统的版本。

最新版本的 Yeoman 和适用于 Office 加载项的 Yeoman 生成器。若要全局安装这些工具，请从命令提示符处运行以下命令。

注意

即便先前已安装了 Yeoman 生成器，我们还是建议你通过 npm 将包更新为最新版本。

已连接到 Microsoft 365 订阅的 Office (包括 Office 网页版)。

注意

如果你还没有 Office，你可能有资格通过 Microsoft 365 开发人员计划获得Microsoft 365 E5开发人员订阅;有关详细信息，请参阅常见问题解答。 或者，可以 注册 1 个月的免费试用版 或 购买 Microsoft 365 计划。

已连接到 Microsoft 365 订阅的 Office (包括 Office 网页版)。

注意

如果你还没有 Office，你可能有资格通过 Microsoft 365 开发人员计划获得用于开发的Microsoft 365 E5开发人员订阅;有关详细信息，请参阅常见问题解答。 或者，可以 注册 1 个月的免费试用版 或 购买 Microsoft 365 计划。

运行以下命令，使用 Yeoman 生成器创建加载项项目。 包含项目的文件夹将添加到当前目录。

注意

运行该yo office命令时，可能会收到有关 Yeoman 和 Office 加载项 CLI 工具的数据收集策略的提示。 根据你的需要，使用提供的信息来响应提示。

出现提示时，请提供以下信息以创建加载项项目。

完成此向导后，生成器会创建项目，并安装支持的 Node 组件。

注意

如果使用 Node.js 20.0.0 或更高版本，则当生成器运行安装时，可能会看到一条警告，指出你的引擎不受支持。 我们正在努力解决此问题。 同时，警告不会影响生成的生成器或项目，因此可以忽略它。

提示

创建加载项项目后，可忽略 Yeoman 生成器提供的后续步骤指南。 本文中的分步说明提供了完成本教程所需的全部指南。

本教程的这一步是，先以编程方式测试加载项是否支持用户的当前版本 Word，再在文档中插入段落。

在代码编辑器中打开项目。

打开 ./src/taskpane/taskpane.html 文件。 此文件含有任务窗格的 HTML 标记。

找到 元素并删除在开始 标记后和关闭 标记前出现的所有行。

打开 标记后立即添加下列标记：

打开 ./src/taskpane/taskpane.js 文件。 此文件包含用于加快任务窗格与 Office 客户端应用程序之间的交互的 Office JavaScript API 代码。

执行以下操作，删除对 run 按钮和 run() 函数的所有引用：

查找并删除行 document.getElementById("run").onclick = run;。

查找并删除整个 run() 函数。

在 Office.onReady 函数调用中，找到行 if (info.host === Office.HostType.Word) { 并紧跟该行添加下列代码。 注意：

将以下函数添加到文件末尾。 注意：

Word.js 业务逻辑将添加到传递给 的 Word.run函数中。 此逻辑不立即执行。 相反，它会添加到挂起的命令队列中。

context.sync 方法将所有已排入队列的命令都发送到 Word 以供执行。

通过 tryCatch 任务窗格与工作簿交互的所有函数都将使用该函数。 以这种方式捕获 Office JavaScript 错误是一种通用处理未捕获的错误的便捷方法。

在 insertParagraph() 函数中，将 TODO1 替换为以下代码。 注意：

insertParagraph 方法的第一个参数是新段落的文本。

第二个参数是应在正文中的什么位置插入段落。 如果父对象为正文，其他段落插入选项包括“End”和“Replace”。

保存对项目所做的所有更改。

完成以下步骤，以启动本地 Web 服务器并旁加载你的加载项。

注意

即使在开发过程中，Office 外接程序也应使用 HTTPS，而不是 HTTP。 如果在运行以下命令之一后系统提示安装证书，请接受安装 Yeoman 生成器提供的证书的提示。 你可能还必须以管理员身份运行命令提示符或终端才能进行更改。

提示

如果在 Mac 上测试加载项，请先运行项目根目录中的以下命令，然后再继续。 运行此命令时，本地 Web 服务器将启动。

若要在 Word 中测试加载项，请在项目的根目录中运行以下命令。 如果本地 Web 服务器尚未运行) ，则会启动本地 Web 服务器 (，并在加载加载项时打开Word。

若要在 Word 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将“{url}”替换为你有权访问的 OneDrive 或 SharePoint 库中 Word 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

在 Word中，如果“我的 Office 外接程序”任务窗格尚未打开，请选择“开始”选项卡，然后选择功能区上的“显示任务窗格”按钮以打开外接程序任务窗格。

在任务窗格中，选择“插入段落”按钮。

在段落中进行一些更改。

再次选择“插入段落”按钮。 观察新段落是否位于上一段落之上，因为 insertParagraph 方法要在文档正文的“开头”插入内容。

在本教程的此步骤中，你将向文本应用嵌入样式、向文本应用自定义样式并更改文本字体。

打开 ./src/taskpane/taskpane.html 文件。

查找insert-paragraph按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 insert-paragraph 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 applyStyle() 函数中，将 TODO1 替换为以下代码。 请注意，此代码向段落应用样式，但也可以向文本区域应用样式。

打开 ./src/taskpane/taskpane.html 文件。

查找apply-style按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 apply-style 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 applyCustomStyle() 函数中，将 TODO1 替换为以下代码。 请注意，此代码应用的自定义样式尚不存在。 将在测试加载项步骤中创建 MyCustomStyle 样式。

保存对项目所做的所有更改。

打开 ./src/taskpane/taskpane.html 文件。

查找apply-custom-style按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 apply-custom-style 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 changeFont() 函数中，将 TODO1 替换为以下代码。 请注意，此代码使用链接到 Paragraph.getNext 方法的 ParagraphCollection.getFirst 方法，获取对第二个段落的引用。

保存对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Word 中，则继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项。

若要在 Word 中测试加载项，请在项目的根目录中运行以下命令。 如果本地 Web 服务器尚未运行) ，则会启动本地 Web 服务器 (，并在加载加载项时打开Word。

若要在 Word 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将“{url}”替换为你有权访问的 OneDrive 或 SharePoint 库中 Word 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在Word中打开，请转到“开始”选项卡，然后选择功能区上的“显示任务窗格”按钮将其打开。

请确保文档中至少有三个段落。 可以选择“插入段落”按钮三次。 仔细检查文档末尾是否没有空白段落。 如果有，请将其删除。

在 Word 中，创建自定义样式“MyCustomStyle”。 其中可以包含所需的任何格式。

选择“应用样式”按钮。 第一个段落将采用嵌入样式“明显参考”。

选择“应用自定义样式”按钮。 最后一个段落将采用自定义样式。 (如果似乎未发生任何操作，则最后一段可能为空。如果是这样，请向其添加一些文本。)

选择“更改字体”按钮。 第二个段落的字体更改为 18 磅的粗体 Courier New。

本教程的这一步是，在选定文本区域内外添加文本，并替换选定区域的文本。

打开 ./src/taskpane/taskpane.html 文件。

查找change-font按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 change-font 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 insertTextIntoRange() 函数中，将 TODO1 替换为以下代码。 注意：

函数旨在将缩写 [“ (M365) ”] 插入到其文本为“Microsoft 365”的范围的末尾。 它做了一个简化假设，即存在字符串，且用户已选择它。

Range.insertText 方法的第一个参数是要插入到 Range 对象的字符串。

第二个参数指定了应在区域中的什么位置插入其他文本。 除了“End”外，其他可用选项包括“Start”、“Before”、“After”和“Replace”。

“End”和“After”的区别在于，“End”在现有区域末尾插入新文本，而“After”则是新建包含字符串的区域，并在现有区域后面插入新区域。 同样，“Start”是在现有区域的开头位置插入文本，而“Before”插入的是新区域。 “Replace”将现有区域文本替换为第一个参数中的字符串。

在本教程 insert* 的早期阶段，你看到正文对象的方法没有“Before”和“After”选项。 这是因为不能将内容置于文档正文外。

在下一部分前，将跳过 TODO2。 在 insertTextIntoRange() 函数中，将 TODO3 替换为以下代码。 此代码类似于在本教程第一阶段中创建的代码，区别在于现在是要在文档末尾（而不是开头）插入新段落。 这一新段落将说明，新文本现属于原始区域。

在本教程之前的所有函数中，你已将命令排队以 写入 Office 文档。 每个函数结束时都会调用 context.sync() 方法，从而将排入队列的命令发送到文档，以供执行。 不过，在上一步中添加的代码调用的是 originalRange.text 属性，这与之前编写的函数明显不同，因为 originalRange 对象只是任务窗格脚本中的代理对象。 由于它并不了解文档中区域的实际文本，因此它的 text 属性无法有实值。 有必要先从文档中提取区域的文本值，再用它设置 originalRange.text 的值。 只有这样才能调用 originalRange.text，而又不会导致异常抛出。 此获取过程分为三步：

将命令排入队列，以加载 (即提取) 代码需要读取的属性。

调用上下文对象的 sync方法，从而向文档发送已排入队列的命令以供执行，并返回请求获取的信息。

由于 sync 是异步方法，因此请先确保它已完成，然后代码才能调用已提取的属性。

每当代码需要从 Office 文档中 读取 信息时，都必须完成以下步骤。

在 insertTextIntoRange() 函数中，将 TODO2 替换为以下代码。

完成后，整个函数应如下所示：

打开 ./src/taskpane/taskpane.html 文件。

查找insert-text-into-range按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 insert-text-into-range 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 insertTextBeforeRange() 函数中，将 TODO1 替换为以下代码。 注意：

此函数用于带有文本“Microsoft 365”的区域前添加文本为“Office 2019”的区域。 它假设字符串存在，并且用户已选择该字符串。

Range.insertText 方法的第一个参数是要添加的字符串。

第二个参数指定了应在区域中的什么位置插入其他文本。 若要详细了解位置选项，请参阅前面介绍的 insertTextIntoRange 函数。

在 insertTextBeforeRange() 函数中，将 TODO2 替换为以下代码。

将 TODO3 替换为以下代码。 此新段落将演示新文本 不属于 原始选定范围这一事实。 原始区域中的文本仍与用户选择它时一样。

将 TODO4 替换为下面的代码。

打开 ./src/taskpane/taskpane.html 文件。

查找insert-text-outside-range按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 insert-text-outside-range 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 replaceText() 函数中，将 TODO1 替换为以下代码。 请注意，此函数用于将字符串“几个”替换为字符串“许多”。 它做了一个简化假设，即存在字符串，且用户已选择它。

保存对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Word 中，则继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项。

若要在 Word 中测试加载项，请在项目的根目录中运行以下命令。 如果本地 Web 服务器尚未运行) ，则会启动本地 Web 服务器 (，并在加载加载项时打开Word。

若要在 Word 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将“{url}”替换为你有权访问的 OneDrive 或 SharePoint 库中 Word 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在Word中打开，请转到“开始”选项卡，然后选择功能区上的“显示任务窗格”按钮将其打开。

在任务窗格中，选择“ 插入段落 ”按钮，确保文档开头有一个段落。

在文档中，选择短语“Microsoft 365 订阅”。 请注意不要包含选定区域前的空格和其后的逗号。

选择“插入缩写”按钮。 请注意，添加了“ (M365) ”。 此外，还请观察，文档底部是否添加了包含整个扩展文本的新段落，因为新字符串已添加到现有区域中。

在文档中，选择短语“Microsoft 365”。 请注意不要包含选定区域前后的空格。

选择“添加版本信息”按钮。 观察是否已在“Office 2016”和“Microsoft 365”之间插入“Office 2019”。 此外，还请观察，文档底部是否添加了仅包含最初选定文本的新段落，因为新字符串已变成新区域，而不是添加到原始区域中。

在文档中，选择“几个”一词。 请注意，不要在选定区域的前后添加空格。

选择“更改数量术语”按钮。 观察选定文本是否替换为“多个”。

本教程的这一步是，了解如何在文档中插入图像、HTML 和表格。

完成以下步骤，定义要在本教程的下一部分插入到文档中的图像。

在项目的根目录中，创建一个名为 base64Image.js 的新文件。

打开文件 base64Image.js 并添加以下代码以指定表示图像的 Base64 编码字符串。

打开 ./src/taskpane/taskpane.html 文件。

查找replace-text按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在文件顶部附近找到 Office.onReady 函数调用，然后在该行之前添加以下代码。 此代码将导入你先前在文件 /base64Image.js 中定义的变量。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 replace-text 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 insertImage() 函数中，将 TODO1 替换为以下代码。 请注意，此行在文档末尾插入 Base64 编码的图像。 (对象 Paragraph 还具有 insertInlinePictureFromBase64 方法和其他 insert* 方法。有关 example，请参阅以下“插入 HTML”部分。)

打开 ./src/taskpane/taskpane.html 文件。

查找insert-image按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 insert-image 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 insertHTML() 函数中，将 TODO1 替换为以下代码。 注意：

第一行代码在文档末尾添加空白段落。

第二行在段落末尾插入 HTML 字符串;特别是两个段落，一个使用 Verdana 字体设置格式，另一个段落采用Word文档的默认样式。 （如前面的 insertImage 方法一样，context.document.body 对象还包含 insert* 方法。）

Inserted HTML.

Another paragraph

打开 ./src/taskpane/taskpane.html 文件。

查找insert-html按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 insert-html 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 insertTable() 函数中，将 TODO1 替换为以下代码。 请注意，此行使用 ParagraphCollection.getFirst 方法获取对第一段的引用，然后使用 Paragraph.getNext 方法获取对第二段的引用。

在 insertTable() 函数中，将 TODO2 替换为以下代码。 注意：

insertTable 方法的前两个参数指定行数和列数。

第三个参数指定要在哪里插入表格（在此示例中，是在段落后面插入）。

第四个参数是用于设置表格单元格值的二维数组。

虽然表格采用普通的默认样式，但 insertTable 方法返回的 Table 对象包含多个成员，其中部分成员用于设置表格样式。

保存对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Word 中，则继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项。

若要在 Word 中测试加载项，请在项目的根目录中运行以下命令。 如果本地 Web 服务器尚未运行) ，则会启动本地 Web 服务器 (，并在加载加载项时打开Word。

若要在 Word 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将“{url}”替换为你有权访问的 OneDrive 或 SharePoint 库中 Word 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在Word中打开，请转到“开始”选项卡，然后选择功能区上的“显示任务窗格”按钮将其打开。

在任务窗格中，至少选择“插入段落”按钮三次，以确保文档中有多个段落。

选择“插入图像”按钮，观察图像是否插入在文档末尾。

选择“ 插入 HTML ”按钮，请注意，文档末尾插入了两个段落，第一个段落具有 Verdana 字体。

选择“插入表格”按钮，观察是否在第二个段落后面插入了表格。

本教程的这一步是，了解如何在文档中创建格式文本内容控件，以及如何插入和替换控件的内容。

注意

开始执行本教程的这一步之前，建议通过 Word UI 创建和控制格式文本内容控件，以便熟悉此类控件及其属性。 有关详细信息，请参阅在 Word 中创建用户填写或打印的表单。

打开 ./src/taskpane/taskpane.html 文件。

查找insert-table按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 insert-table 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 createContentControl() 函数中，将 TODO1 替换为以下代码。 注意：

此代码旨在将短语“Microsoft 365”包装在内容控件中。 它做了一个简化假设，即存在字符串，且用户已选择它。

ContentControl.title 属性指定内容控件的可见标题。

ContentControl.tag 属性指定标记，可用于通过 ContentControlCollection.getByTag 方法获取对内容控件的引用，将用于稍后出现的函数。

ContentControl.appearance 属性指定控件的外观。 使用值“Tags”表示，控件包装在开始标记和结束标记中，且开始标记包含内容控件标题。 其他可取值包括“BoundingBox”和“None”。

ContentControl.color 属性指定标记颜色或边界框的边框。

打开 ./src/taskpane/taskpane.html 文件。

查找create-content-control按钮的元素，并在行后添加下列标记。

打开 ./src/taskpane/taskpane.js 文件。

在 Office.onReady 函数调用中，定位将单击处理程序分配到 create-content-control 按钮的行，并在该行后添加以下代码。

将以下函数添加到文件结尾。

在 replaceContentInControl() 函数中，将 TODO1 替换为以下代码。 注意：

保存对项目所做的所有更改。

如果本地 Web 服务器已在运行，并且加载项已加载到 Word 中，则继续执行步骤 2。 否则，启动本地 Web 服务器并旁加载你的加载项。

若要在 Word 中测试加载项，请在项目的根目录中运行以下命令。 如果本地 Web 服务器尚未运行) ，则会启动本地 Web 服务器 (，并在加载加载项时打开Word。

若要在 Word 网页版中测试加载项，请在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动。 将“{url}”替换为你有权访问的 OneDrive 或 SharePoint 库中 Word 文档的 URL。

注意

如果在 Mac 上进行开发，请将 括 {url} 在单引号中。 请勿在 Windows 上执行此操作。

示例如下。

如果外接程序未在文档中旁加载，请按照手动旁加载加载项中的说明手动旁加载到Office web 版。

如果加载项任务窗格尚未在Word中打开，请转到“开始”选项卡，然后选择功能区上的“显示任务窗格”按钮将其打开。

在任务窗格中，选择“ 插入段落 ”按钮，确保文档顶部有一个带有“Microsoft 365”的段落。

在文档中，选择文本“Microsoft 365”，然后选择“创建内容控件”按钮。 观察此短语是否包装在标签为“服务名称”的标记中。

选择“重命名服务”按钮，并观察内容控件的文本是否变成“Fabrikam Online Productivity Suite”。

在本教程中，你已创建 Word 任务窗格加载项，用于在 Word 文档中插入和替换文本、图像和其他内容。 若要了解有关构建 Word 加载项的详细信息，请继续阅读以下文章。

Word 加载项概述