Freigeben über

Verwenden von Feldern in Ihrem Word-Add-In

Ein Feld in einem Word Dokument ist ein Platzhalter. Es ermöglicht Ihnen, Anweisungen für den Inhalt anstelle des Inhalts selbst bereitzustellen. Sie können Felder verwenden, um eine Word Vorlage zu erstellen und zu formatieren. Word Dokumente unterstützen eine Reihe von Feldtypen, viele mit zugeordneten Parametern zum Konfigurieren des Felds. Word im Web unterstützt jedoch in der Regel das Hinzufügen oder Bearbeiten von Feldern über die Benutzeroberfläche nicht. Weitere Informationen finden Sie unter Feldfunktionen in Word für das Web.

Ab dem WordApi 1.5-Anforderungssatz können Sie Word JavaScript-APIs Felder in Ihrem Word-Add-In verwalten. Auf allen Plattformen können Sie vorhandene Felder abrufen. Sie können Felder auf Plattformen einfügen, aktualisieren und löschen, die diese Funktionen unterstützen.

In den folgenden Abschnitten werden einige der am häufigsten verwendeten Feldtypen erläutert: Addin, Date, Hyperlink und TOC (Inhaltsverzeichnis).

Addin-Feld

Das Addin-Feld dient zum Speichern von Add-In-Daten, die auf der Word Benutzeroberfläche ausgeblendet sind, unabhängig davon, ob felder im Dokument so festgelegt sind, dass der Inhalt angezeigt oder ausgeblendet wird. Das Feld Addin ist im Dialogfeld Feld der Word Benutzeroberfläche nicht verfügbar. Verwenden Sie die API, um den Addin-Feldtyp einzufügen und die Daten des Felds festzulegen.

Im folgenden Codebeispiel wird gezeigt, wie Sie ein Addin-Feld vor der Cursorposition oder Ihrer Auswahl im Word Dokument einfügen.

// Inserts an Addin field before selection.
async function rangeInsertAddinField() {
  await Word.run(async (context) => {
    let range = context.document.getSelection().getRange();
    const field = range.insertField(Word.InsertLocation.before, Word.FieldType.addin);
    field.load("result,code");
    await context.sync();

    if (field.isNullObject) {
      console.log("There are no fields in this document.");
    } else {
      console.log("Code of the field: " + field.code);
      console.log("Result of the field: " + JSON.stringify(field.result));
    }
  });
}

Das folgende Codebeispiel zeigt, wie Sie das erste Addin-Feld in einem Dokument abrufen und dann die Dateneigenschaft dieses Felds festlegen.

// Gets the first Addin field in the document and sets its data.
async function getFirstAddinFieldAndSetData() {
  await Word.run(async (context) => {
    let myFieldTypes = new Array();
    myFieldTypes[0] = Word.FieldType.addin;
    const addinFields = context.document.body.fields.getByTypes(myFieldTypes);
    let fields = addinFields.load("items");
    await context.sync();

    if (fields.items.length === 0) {
      console.log("No Addin fields in this document.");
    } else {
      fields.load();
      await context.sync();

      const firstAddinField = fields.items[0];
      firstAddinField.load("code,result,data");
      await context.sync();

      console.log("The data of the Addin field before being set:", firstAddinField.data);
      const data = "Insert your data here";
      //const data = $("#input-reference").val(); // Or get user data from your add-in's UI.
      firstAddinField.data = data;
      firstAddinField.load("data");
      await context.sync();

      console.log("The data of the Addin field after being set:", firstAddinField.data);
    }
  });
}

Datumsfeld

Das Feld Datum fügt das aktuelle Datum entsprechend dem von Ihnen angegebenen Format ein. Sie können zwischen der Anzeige des Datums oder der Feldfunktion wechseln, indem Sie die showCodes Field-Eigenschaft auf false bzw true . festlegen.

Im folgenden Codebeispiel wird gezeigt, wie Sie ein Datumsfeld vor der Cursorposition oder Ihrer Auswahl im Word Dokument einfügen.

// Inserts a Date field before selection.
async function rangeInsertDateField() {
  await Word.run(async (context) => {
    let range = context.document.getSelection().getRange();
    const field = range.insertField(
      Word.InsertLocation.before,
      Word.FieldType.date,
     '\\@ "M/d/yyyy h:mm am/pm"',
     true
    );
    field.load("result,code");
    await context.sync();

    if (field.isNullObject) {
      console.warn("The field wasn't inserted as expected.");
    } else {
      console.log("Code of the field: " + field.code);
      console.log("Result of the field: " + JSON.stringify(field.result));
    }
  });
}

Weitere Lektüre

Das Feld Hyperlink fügt die Adresse einer Position im selben Dokument oder einer externen Position wie einer Webseite ein. Wenn der Benutzer es auswählt, wird er zum angegebenen Speicherort navigiert. Sie können zwischen der Anzeige der Hyperlinkadresse oder der Feldfunktion wechseln, indem Sie die showCodes Field-Eigenschaft auf false bzw true . festlegen.

Das folgende Codebeispiel zeigt, wie Sie ein Hyperlinkfeld vor der Cursorposition oder Ihrer Auswahl im Word Dokument einfügen.

// Inserts a Hyperlink field before selection.
async function rangeInsertHyperlinkField() {
  await Word.run(async (context) => {
    let range = context.document.getSelection().getRange();
    const field = range.insertField(
      Word.InsertLocation.before,
      Word.FieldType.hyperlink,
      "https://bing.com",
      true
    );
    field.load("result,code");
    await context.sync();

    if (field.isNullObject) {
      console.warn("The field wasn't inserted as expected.");
    } else {
      console.log("Code of the field: " + field.code);
      console.log("Result of the field: " + JSON.stringify(field.result));
    }
  });
}

Weitere Lektüre

Inhaltsverzeichnisfeld

Das Inhaltsverzeichnisfeld fügt ein Inhaltsverzeichnis ein, in dem bestimmte Bereiche eines Dokuments aufgeführt sind, z. B. Überschriften. Sie können zwischen dem Anzeigen des Inhaltsverzeichnisses oder der Feldfunktion wechseln, indem Sie die showCodes Field-Eigenschaft auf false bzw true . festlegen.

Im folgenden Codebeispiel wird gezeigt, wie Sie ein Inhaltsverzeichnisfeld an der Cursorposition einfügen oder Ihre aktuelle Auswahl im Word Dokument ersetzen.

/**
 1. Run setup.
 2. Select "[To place table of contents]" paragraph.
 3. Run rangeInsertTOCField.
 */

// Inserts a TOC (table of contents) field replacing selection.
async function rangeInsertTOCField() {
  await Word.run(async (context) => {
    let range = context.document.getSelection().getRange();
    const field = range.insertField(
      Word.InsertLocation.replace,
      Word.FieldType.toc
    );
    field.load("result,code");
    await context.sync();

    if (field.isNullObject) {
      console.warn("The field wasn't inserted as expected.");
    } else {
      console.log("Code of the field: " + field.code);
      console.log("Result of the field: " + JSON.stringify(field.result));
    }
  });
}

// Prep document so there'll be elements that could be included in a table of contents.
async function setup() {
  await Word.run(async (context) => {
    const body: Word.Body = context.document.body;
    body.clear();
    body.insertParagraph("Document title", "End").styleBuiltIn = Word.BuiltInStyleName.title;
    body.insertParagraph("[To place table of contents]", "End").styleBuiltIn = Word.BuiltInStyleName.normal;
    body.insertParagraph("Introduction", "End").styleBuiltIn = Word.BuiltInStyleName.heading1;
    body.insertParagraph("Paragraph 1", "End").styleBuiltIn = Word.BuiltInStyleName.normal;
    body.insertParagraph("Topic 1", "End").styleBuiltIn = Word.BuiltInStyleName.heading1;
    body.insertParagraph("Paragraph 2", "End").styleBuiltIn = Word.BuiltInStyleName.normal;
    body.insertParagraph("Topic 2", "End").styleBuiltIn = Word.BuiltInStyleName.heading1;
    body.insertParagraph("Paragraph 3", "End").styleBuiltIn = Word.BuiltInStyleName.normal;
  });
}

Weitere Lektüre

Siehe auch