如何在 Office 编程中使用命名参数和可选参数

2025-07-16

命名参数和可选参数增强了 C# 编程中的便利性、灵活性和可读性。此外，这些功能极大地促进了对 COM 接口（如 Microsoft Office 自动化 API）的访问。

重要

VSTO （Visual Studio Tools for Office）依赖于 .NET Framework。还可以使用 .NET Framework 编写 COM 加载项。无法使用 .NET Core 和 .NET 5+（最新版本的 .NET）创建 Office 加载项。这是因为 .NET Core/.NET 5+ 无法在同一进程中与 .NET Framework 协同工作，并可能导致加载项加载失败。可以继续使用 .NET Framework 编写适用于 Office 的 VSTO 和 COM 加载项。 Microsoft不会更新 VSTO 或 COM 加载项平台以使用 .NET Core 或 .NET 5+。可以利用 .NET Core 和 .NET 5+（包括 ASP.NET Core）来创建 Office Web 外接程序的服务器端。

在以下示例中， ConvertToTable 方法具有 16 个参数，这些参数表示表格的特征，例如列数和行数、格式设置、边框、字体和颜色。所有 16 个参数都是可选的，因为大多数时候都不想为所有参数指定特定值。但是，如果没有命名参数和可选参数，则必须提供值或占位符值。使用命名参数和可选参数，只需为项目所需的参数指定值。

必须在计算机上安装Microsoft Office Word 才能完成这些过程。

注释

计算机可能会在以下说明中显示某些 Visual Studio 用户界面元素的不同名称或位置。你拥有的 Visual Studio 版本以及所使用的设置决定了这些元素。有关更多信息，请参阅自定义 IDE。

创建新的控制台应用程序

启动 Visual Studio。在 “文件” 菜单上，指向 “新建”，然后选择 “项目”。在“ 模板类别 ”窗格中，展开 C#，然后选择 “Windows”。在 “模板 ”窗格顶部查看，确保 .NET Framework 4 显示在 “目标框架 ”框中。在“ 模板 ”窗格中，选择 “控制台应用程序”。在“ 名称” 字段中键入项目的名称。选择“确定”。新项目将显示在 解决方案资源管理器中。

添加引用

在 解决方案资源管理器中，右键单击项目的名称，然后选择“ 添加引用”。此时将显示“添加引用”对话框。在 .NET 页上，选择组件名称列表中的 Microsoft.Office.Interop.Word。选择“确定”。

添加必要的 using 指令

在 解决方案资源管理器中，右键单击 Program.cs 文件，然后选择“ 查看代码”。将以下 using 指令添加到代码文件的顶部：

using Word = Microsoft.Office.Interop.Word;

在 Word 文档中显示文本

Program在 Program.cs 中的类中，添加以下方法来创建 Word 应用程序和 Word 文档。 Add 方法有四个可选参数。此示例使用其默认值。因此，调用语句中不需要任何参数。

注释

为了避免导致异常的 COM 线程和计时问题，例如“消息筛选器指示应用程序正忙”（HRESULT 0x8001010A），Word 应用程序在作过程中保持不可见，并且仅在所有作完成后才可见。

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    // Keep Word invisible during operations to avoid COM threading issues
    wordApp.Visible = false;
    // docs is a collection of all the Document objects currently
    // open in Word.
    Word.Documents docs = wordApp.Documents;

    // Add a document to the collection and name it doc.
    Word.Document doc = docs.Add();
    
    // Make Word visible after operations are complete
    wordApp.Visible = true;
}

在方法末尾添加以下代码，以定义在文档中显示文本的位置以及要显示的文本：

// Define a range, a contiguous area in the document, by specifying
// a starting and ending character position. Currently, the document
// is empty.
Word.Range range = doc.Range(0, 0);

// Use the InsertAfter method to insert a string at the end of the
// current range.
range.InsertAfter("Testing, testing, testing. . .");

运行应用程序

将以下语句添加到 Main：

DisplayInWord();

按 Ctrl+F5 运行项目。将显示包含指定文本的 Word 文档。

将文本更改为表格

ConvertToTable使用该方法将文本括在表中。该方法有 16 个可选参数。 IntelliSense 将可选参数括在括号中，如下图所示。 Type.Missing 的默认值是 System.Type.Missing 的简单名称。

ConvertToTable 方法的参数列表

命名参数和可选参数使你只能为要更改的参数指定值。将以下代码添加到方法 DisplayInWord 末尾以创建表。参数指定 range 文本字符串中的逗号用于分隔表格的单元格。

// Convert to a simple table. The table will have a single row with
// three columns.
range.ConvertToTable(Separator: ",");

按 Ctrl+F5 运行项目。

试验其他参数

更改表，使其具有一列和三行，将最后一行 DisplayInWord 替换为以下语句，然后键入 CTRL+F5。

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

指定表的预定义格式，将最后一行 DisplayInWord 替换为以下语句，然后键入 CTRL+F5。格式可以是 WdTableFormat 常量中的任意一个。

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
    Format: Word.WdTableFormat.wdTableFormatElegant);

示例：

以下代码包括完整示例：

using System;
using Word = Microsoft.Office.Interop.Word;

namespace OfficeHowTo
{
    class WordProgram
    {
        static void Main(string[] args)
        {
            DisplayInWord();
        }

        static void DisplayInWord()
        {
            var wordApp = new Word.Application();
            // Keep Word invisible during operations to avoid COM threading issues
            wordApp.Visible = false;
            // docs is a collection of all the Document objects currently
            // open in Word.
            Word.Documents docs = wordApp.Documents;

            // Add a document to the collection and name it doc.
            Word.Document doc = docs.Add();

            // Define a range, a contiguous area in the document, by specifying
            // a starting and ending character position. Currently, the document
            // is empty.
            Word.Range range = doc.Range(0, 0);

            // Use the InsertAfter method to insert a string at the end of the
            // current range.
            range.InsertAfter("Testing, testing, testing. . .");

            // You can comment out any or all of the following statements to
            // see the effect of each one in the Word document.

            // Next, use the ConvertToTable method to put the text into a table.
            // The method has 16 optional parameters. You only have to specify
            // values for those you want to change.

            // Convert to a simple table. The table will have a single row with
            // three columns.
            range.ConvertToTable(Separator: ",");

            // Change to a single column with three rows..
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

            // Format the table.
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
                Format: Word.WdTableFormat.wdTableFormatElegant);

            // Make Word visible after all operations are complete
            wordApp.Visible = true;
        }
    }
}