如何在 Office 程式設計中使用具名和選擇性引數

具名引數和選擇性引數，可加強 C# 程式設計的便利性、彈性和可讀性。 此外，這些功能還可大幅加速對 COM 介面 (例如 Microsoft Office Automation API) 的存取。

重要

VSTO (Visual Studio Tools for Office) 需依賴 .NET Framework。 COM 增益集也可以使用 .NET Framework 撰寫。 無法使用 .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 版本以及使用的設定會決定這些項目。 如需詳細資訊，請參閱將 Visual Studio IDE 個人化。

建立新的主控台應用程式

啟動 Visual Studio。 在 [檔案] 功能表上，指向 [新增]，然後選取 [專案]。 在 [範本類別] 窗格中，展開 [C#]，然後選取 [Windows]。 查看 [範本] 窗格頂端，確定 [.NET Framework 4] 出現在 [目標 Framework] 方塊中。 在 [範本] 窗格中，選取 [主控台應用程式]。 在 [名稱] 欄位中鍵入專案的名稱。 選取 [確定]。 新的專案隨即會出現在方案總管中。

加入參考

在 [方案總管] 中，於專案名稱上按一下滑鼠右鍵，然後選取 [新增參考]。 [新增參考] 對話方塊隨即出現。 在 [.NET] 頁面上，選取 [元件名稱] 清單中的 [Microsoft.Office.Interop.Word]。 選取 [確定]。

加入必要的 using 指示詞

在 [方案總管] 中，以滑鼠右鍵按一下 Program.cs 檔案，然後選取 [檢視程式碼]。 將下列 using 指示詞加入程式碼檔案頂端：

using Word = Microsoft.Office.Interop.Word;

在 Word 文件中顯示文字

在 Program.cs 的 Program 類別中，新增下列方法以建立 Word 應用程式和 Word 文件。 Add 方法有四個選擇性參數。 此範例會使用其預設值。 因此，呼叫陳述式中不需要引數。

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    wordApp.Visible = true;
    // 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. . .");

執行應用程式

將下列陳述式新增至「主要」：

DisplayInWord();

按 CTRL+F5 執行專案。 隨即會出現含有指定文字的 Word 文件。

將文字變更為表格

使用 ConvertToTable 方法將文字放在表格中。 方法有 16 個選擇性參數。 IntelliSense 會以方括號括住選擇性參數，如下圖所示。

具名和選擇性引數可讓您只針對要變更的參數指定值。 將下列程式碼新增至 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();
            wordApp.Visible = true;
            // 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);
        }
    }
}