Jak używać argumentów nazwanych i opcjonalnych w programowaniu pakietu Office

Argumenty nazwane i opcjonalne argumenty zwiększają wygodę, elastyczność i czytelność w programowaniu w języku C#. Ponadto te funkcje znacznie ułatwiają dostęp do interfejsów COM, takich jak interfejsy API automatyzacji pakietu Microsoft Office.

Ważne

Program VSTO (Visual Studio Tools for Office) korzysta z programu .NET Framework. Dodatki COM można również napisać za pomocą programu .NET Framework. Nie można utworzyć dodatków pakietu Office z platformami .NET Core i .NET 5+, najnowszymi wersjami platformy .NET. Dzieje się tak, ponieważ program .NET Core/.NET 5+ nie może współpracować z programem .NET Framework w tym samym procesie i może prowadzić do błędów ładowania dodatków. Możesz nadal używać programu .NET Framework do pisania dodatków VSTO i COM dla pakietu Office. Firma Microsoft nie zaktualizuje programu VSTO ani platformy dodatku COM w celu korzystania z platformy .NET Core lub .NET 5+. Możesz korzystać z platform .NET Core i .NET 5+, w tym ASP.NET Core, aby utworzyć część serwerową dodatków internetowych pakietu Office.

W poniższym przykładzie metoda ConvertToTable ma 16 parametrów reprezentujących cechy tabeli, takie jak liczba kolumn i wierszy, formatowanie, obramowania, czcionki i kolory. Wszystkie 16 parametrów są opcjonalne, ponieważ przez większość czasu nie chcesz określać określonych wartości dla wszystkich z nich. Jednak bez argumentów nazwanych i opcjonalnych należy podać wartość lub wartość zastępczą. W przypadku argumentów nazwanych i opcjonalnych można określić wartości tylko dla parametrów wymaganych dla projektu.

Aby wykonać te procedury, na komputerze musi być zainstalowany program Microsoft Office Word.

Uwaga / Notatka

Na komputerze mogą być wyświetlane różne nazwy lub lokalizacje niektórych elementów interfejsu użytkownika programu Visual Studio w poniższych instrukcjach. Wersja programu Visual Studio i ustawienia, których używasz, określają te elementy. Aby uzyskać więcej informacji, zobacz Personalizowanie środowiska IDE.

Tworzenie nowej aplikacji konsolowej

Uruchom program Visual Studio. W menu Plik wskaż polecenie Nowy, a następnie kliknij opcję Projekt. W okienku Kategorie szablonów rozwiń C#, a następnie wybierz Windows. Spójrz w górnej części okienka Szablony , aby upewnić się, że program .NET Framework 4 jest wyświetlany w polu Platforma docelowa . W okienku Szablony wybierz pozycję Aplikacja konsolowa. Wpisz nazwę projektu w polu Nazwa . Kliknij przycisk OK. Nowy projekt zostanie wyświetlony w Eksploratorze rozwiązań.

Dodawanie odwołania

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy nazwę projektu, a następnie wybierz pozycję Dodaj odwołanie. Zostanie wyświetlone okno dialogowe Dodawanie odwołania . Na stronie .NET wybierz pozycję Microsoft.Office.Interop.Word na liście Nazwa składnika . Kliknij przycisk OK.

Dodawanie niezbędnych dyrektyw using

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy plik Program.cs , a następnie wybierz polecenie Wyświetl kod. Dodaj następujące using dyrektywy na początku pliku kodu:

using Word = Microsoft.Office.Interop.Word;

Wyświetlanie tekstu w dokumencie programu Word

Program W klasie w Program.cs dodaj następującą metodę, aby utworzyć aplikację programu Word i dokument programu Word. Metoda Add ma cztery parametry opcjonalne. W tym przykładzie użyto ich wartości domyślnych. W związku z tym w instrukcji wywołującej nie są konieczne żadne argumenty.

Uwaga / Notatka

Aby uniknąć problemów z wątkami i synchronizacją COM, które mogą powodować wyjątki, takie jak "Filtr komunikatu wskazuje, że aplikacja jest zajęta" (HRESULT 0x8001010A), aplikacja Word jest utrzymywana w trybie niewidocznym podczas operacji i staje się widoczna dopiero po zakończeniu wszystkich operacji.

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;
}

Dodaj następujący kod na końcu metody, aby zdefiniować miejsce wyświetlania tekstu w dokumencie oraz tekst do wyświetlenia:

// 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. . .");

Uruchamianie aplikacji

Dodaj następującą instrukcję do Main:

DisplayInWord();

Naciśnij CTRL+F5 , aby uruchomić projekt. Zostanie wyświetlony dokument programu Word zawierający określony tekst.

Zmienianie tekstu na tabelę

ConvertToTable Użyj metody , aby ująć tekst w tabeli. Metoda ma 16 parametrów opcjonalnych. IntelliSense zawiera opcjonalne parametry w nawiasach kwadratowych, jak pokazano na poniższej ilustracji. Domyślne wartości Type.Missing są prostą nazwą dla System.Type.Missing.

Argumenty nazwane i opcjonalne umożliwiają określenie wartości tylko dla parametrów, które chcesz zmienić. Dodaj następujący kod na końcu metody DisplayInWord , aby utworzyć tabelę. Argument określa, że przecinki w ciągu tekstowym range służą do oddzielania komórek tabeli.

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

Naciśnij CTRL+F5 , aby uruchomić projekt.

Eksperymentowanie z innymi parametrami

Zmień tabelę tak, aby zawierała jedną kolumnę i trzy wiersze, zastąp ostatni wiersz DisplayInWord następującą instrukcją, a następnie wpisz CTRL+F5.

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

Określ wstępnie zdefiniowany format tabeli, zastąp ostatni wiersz DisplayInWord następującą instrukcją, a następnie wpisz CTRL+F5. Format może być dowolną stałą WdTableFormat.

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

Przykład

Poniższy kod zawiera pełny przykład:

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;
        }
    }
}