演练:创建您的第一个 Word 文档级自定义项Walkthrough: Create your first document-level customization for Word

本介绍性演练演示了如何创建 Microsoft Office Word 的文档级自定义项。This introductory walkthrough shows you how to create a document-level customization for Microsoft Office Word. 仅在特定文档处于打开状态时,才可提供你在这种解决方案中创建的功能。The features that you create in this kind of solution are available only when a specific document is open. 不能使用文档级自定义项进行应用程序范围的更改,例如在任何文档处于打开状态时显示新“功能区”选项卡。You cannot use a document-level customization to make application-wide changes, for example, displaying a new Ribbon tab when any document is open.

适用于: 本主题中的信息适用于文档-Word 级别项目。Applies to: The information in this topic applies to document-level projects for Word. 有关详细信息,请参阅按 Office 应用程序和项目类型提供的功能For more information, see Features available by Office application and project type.

本演练阐释了以下任务:This walkthrough illustrates the following tasks:

  • 创建 Word 文档项目。Creating a Word document project.

  • 将文本添加到 Visual Studio 设计器中托管的文档。Adding text to the document that is hosted in the Visual Studio designer.

  • 编写代码,使用 Word 对象模型在自定义文档时打开时向其中添加文本。Writing code that uses the object model of Word to add text to the customized document when it is opened.

  • 生成并运行项目,以对其进行测试。Building and running the project to test it.

  • 清理项目,以便从开发计算机删除不必要的生成文件和安全设置。Cleaning up the project to remove unnecessary build files and security settings from your development computer.

    Note

    以下说明中的某些 Visual Studio 用户界面元素在计算机上出现的名称或位置可能会不同。Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. 这些元素取决于你所使用的 Visual Studio 版本和你所使用的设置。The Visual Studio edition that you have and the settings that you use determine these elements. 有关详细信息,请参阅个性化设置 IDEFor more information, see Personalize the IDE.

先决条件Prerequisites

你需要以下组件来完成本演练:You need the following components to complete this walkthrough:

创建项目Create the project

在 Visual Studio 中创建新的 Word 文档项目To create a new Word document project in Visual Studio

  1. 启动Visual StudioVisual StudioStart Visual StudioVisual Studio.

  2. “文件” 菜单上,指向 “新建” ,然后单击 “项目”On the File menu, point to New, and then click Project.

  1. 在模板窗格中,展开 “Visual C#”“Visual Basic” ,然后展开 “Office/SharePoint”In the templates pane, expand Visual C# or Visual Basic, and then expand Office/SharePoint.

  2. 在展开的 " Office/SharePoint " 节点下,选择 " VSTO 外接程序" 节点。Under the expanded Office/SharePoint node, select the VSTO Add-ins node.

  3. 在项目模板列表中,选择 "Word VSTO 文档" 项目。In the list of project templates, select a Word VSTO document project.

  4. 在 "名称" 框中,键入FirstDocumentCustomizationIn the Name box, type FirstDocumentCustomization.

  5. 单击“确定”。Click OK.

  6. 从 " Visual Studio Tools for Office 项目向导" 中选择 "创建新文档",然后单击 "确定"Select Create a new document from the Visual Studio Tools for Office Project Wizard, and click OK.

  1. 在 "创建新项目" 对话框中,选择 " Word VSTO 文档" 项目。On the Create a New Project dialog select the Word VSTO Document project.

    Note

    还可以通过在 "创建新项目" 对话框顶部的 "搜索" 文本框中键入 Office 产品的名称来搜索模板。You can also search for templates by typing the name of the Office product in the Search text box at the top of the Create a New Project dialog. 例如,键入excel将显示 excel 的所有项目模板。For example, typing Excel will show you all of the project templates for Excel. 还可以通过在 "项目类型" 下拉框中选择 " office ",来筛选模板列表以仅显示 office 模板。You can also filter the list of templates to show only the templates for Office by selecting Office in the Project type dropdown box. 有关详细信息,请参阅在 Visual Studio 中创建新项目For more information see Create a new project in Visual Studio.

  2. 单击 “下一步”Click Next.

  3. 在 "配置新项目" 对话框的 "名称" 框中键入FirstWorkbookCustomization ,然后单击 "创建"。Type FirstWorkbookCustomization in the Name box on the Configure your new project dialog and click Create.

  4. 从 " Visual Studio Tools for Office 项目向导" 中选择 "创建新文档",然后单击 "确定"Select Create a new document from the Visual Studio Tools for Office Project Wizard, and click OK.

  • Visual StudioVisual Studio 创建FirstDocumentCustomization项目,并将FirstDocumentCustomization文档和 ThisDocument 代码文件添加到项目。creates the FirstDocumentCustomization project, and adds the FirstDocumentCustomization document and ThisDocument code file to the project. FirstDocumentCustomization文档会在设计器中自动打开。The FirstDocumentCustomization document is opened automatically in the designer.

在设计器中关闭并重新打开文档Close and reopen the document in the designer

如果开发项目时有意或无意关闭了设计器中的文档,则可以重新打开它。If you deliberately or accidentally close the document in the designer while you are developing your project, you can reopen it.

若要关闭并重新打开设计器中的文档To close and reopen the document in the designer

  1. 通过单击设计器窗口的 "关闭" 按钮(X)来关闭文档。Close the document by clicking the Close button (X) for the designer window.

  2. 解决方案资源管理器中,右键单击ThisDocument代码文件,然后单击 "查看设计器"。In Solution Explorer, right-click the ThisDocument code file, and click View Designer.

    - 或 -- or -

    解决方案资源管理器中,双击 " ThisDocument " 代码文件。In Solution Explorer, double-click the ThisDocument code file.

在设计器中向文档添加文本Add text to the document in the designer

可以通过修改在设计器中打开的文档来设计自定义的用户界面 (UI)。You can design the user interface (UI) of your customization by modifying the document that is open in the designer. 例如,可以添加文本、表格或 Word 控件。For example, you can add text, tables, or Word controls. 有关如何使用设计器的详细信息,请参阅Visual Studio 环境中的 Office 项目For more information about how to use the designer, see Office projects in the Visual Studio environment.

使用设计器将文本添加到文档To add text to your document by using the designer

  1. 在已在设计器中打开的文档中键入以下文本。In the document that is open in the designer, type the following text.

    此文本是使用设计器添加的。This text was added by using the designer.

以编程方式向文档中添加文本Add text to the document programmatically

接下来,将代码添加到 ThisDocument 代码文件。Next, add code to the ThisDocument code file. 新代码使用 Word 对象模型向文档添加文本的第二个段落。The new code uses the object model of Word to add a second paragraph of text to the document. 默认情况下,ThisDocument 代码文件包含以下生成的代码:By default, the ThisDocument code file contains the following generated code:

  • ThisDocument 类的部分定义,用于表示文档的编程模型,并提供对 Word 对象模型的访问权限。A partial definition of the ThisDocument class, which represents the programming model of the document and provides access to the object model of Word. 有关详细信息,请参阅文档主机项Word 对象模型概述For more information, see Document host item and Word object model overview. ThisDocument 类的其余部分是在隐藏代码文件中定义的,不应修改该代码文件。The remainder of the ThisDocument class is defined in a hidden code file that you should not modify.

  • ThisDocument_StartupThisDocument_Shutdown 事件处理程序。The ThisDocument_Startup and ThisDocument_Shutdown event handlers. 将在打开或关闭文档时调用这些事件处理程序。These event handlers are called when the document is opened and closed. 使用这些事件处理程序,可在打开文档时对其进行初始化,并在关闭文档时清理自定义项所使用的资源。Use these event handlers to initialize your customization when the document is opened, and to clean up resources used by your customization when the document is closed. 有关详细信息,请参阅Office 项目中的事件For more information, see Events in Office projects.

若要使用代码向文档添加文本的第二个段落To add a second paragraph of text to the document by using code

  1. 解决方案资源管理器中,右键单击ThisDocument,然后单击 "查看代码"。In Solution Explorer, right-click ThisDocument, and then click View Code.

    将在 Visual Studio 中打开代码文件。The code file opens in Visual Studio.

  2. ThisDocument_Startup 事件处理程序替换为以下代码。Replace the ThisDocument_Startup event handler with the following code. 当打开文档时,此代码会将文本第二个段落添加到文档中。When the document is opened, this code adds a second paragraph of text to the document.

    Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
        Me.Paragraphs(1).Range.InsertParagraphAfter()
        Me.Paragraphs(2).Range.Text = "This text was added by using code."
    End Sub
    
    private void ThisDocument_Startup(object sender, System.EventArgs e)
    {
        this.Paragraphs[1].Range.InsertParagraphAfter();
        this.Paragraphs[2].Range.Text = "This text was added by using code.";
    }
    

    Note

    此代码使用索引值 1 来访问 Paragraphs 属性的第一个段落。This code uses the index value 1 to access the first paragraph in the Paragraphs property. 尽管 Visual Basic 和 Visual C# 使用从 0 开始的数组,但 Word 对象模型中大多数集合的数组下限都是 1。Although Visual Basic and Visual C# use 0-based arrays, the lower array bounds of most collections in the Word object model is 1. 有关详细信息,请参阅在 Office 解决方案中编写代码For more information, see Write code in Office solutions.

测试项目Test the project

测试文档To test your document

  1. F5 生成并运行项目。Press F5 to build and run your project.

    生成项目时,会将代码编译到与该文档相关联的程序集中。When you build the project, the code is compiled into an assembly that is associated with the document. Visual Studio 将该文档和程序集的副本放入项目的生成输出文件夹中,并将开发计算机上的安全设置配置为允许自定义项运行。Visual Studio puts a copy of the document and the assembly in the build output folder for the project, and it configures the security settings on the development computer to enable the customization to run. 有关详细信息,请参阅生成 Office 解决方案For more information, see Build Office solutions.

  2. 验证文档中具有以下文本。In the document, verify that you see the following text.

    此文本是使用设计器添加的。This text was added by using the designer.

    This text was added by using code.This text was added by using code.

  3. 关闭文档。Close the document.

清理项目Clean up the project

完成项目开发后,应删除生成输出文件夹中的文件和由生成过程创建的安全设置。When you finish developing a project, you should remove the files in the build output folder and the security settings created by the build process.

在开发计算机上清理已完成的项目To clean up the completed project on your development computer

  1. 在 Visual Studio 中,在 “生成” 菜单上,单击 “清理解决方案”In Visual Studio, on the Build menu, click Clean Solution.

后续步骤Next steps

既然你已经创建了一个基本的 Word 文档级自定义项,你就可以从下面这些主题中了解有关如何开发自定义项的详细信息:Now that you have created a basic document-level customization for Word, you can learn more about how to develop customizations from these topics:

另请参阅See also