Arbeiten mit Text, Formatierung, Auswahlen und Bereichen in Word-Dokumenten

  • 14 Minuten

Die JavaScript-API für Word erleichtert die programmgesteuerte Kontrolle über Text, Formatierung, Auswahlen und Bereiche in Word-Dokumenten. In dieser Lektion erfahren Sie, wie Sie mit Text und Absätzen arbeiten, Formate und Formatierungen auf Text anwenden und wie Sie mit Textauswahlen und -bereichen aus einem benutzerdefinierten Word-Add-In arbeiten.

Übersicht über die Office-Entwicklerplattform

Die Microsoft 365-Entwicklerplattform, die Office umfasst, bietet Entwicklern viel Spielraum zum Einbetten von Anpassungen. Office-Add-Ins gehören zu einer dieser drei Spielräume: Dokumente, Unterhaltungen und Pages.

Microsoft Teams führt Unterhaltungen zwischen Benutzern durch und ermöglicht es Entwicklern, die Erfahrung mit Messaging-Erweiterungen, Unterhaltungs-Bots und anderen Anpassungsoptionen zu erweitern.

Entwickler passen Seiten in SharePoint-Server und SharePoint-Online mit dem SharePoint-Framework an.

Office-Clients wie Word, Excel, PowerPoint, OneNote und Outlook können ebenfalls erweitert werden, um benutzerdefinierte Aufgabenbereiche, Aktionen und andere Anpassungen mit Hilfe von Add-Ins zu implementieren.

Übersichtsdiagramm der Microsoft 365-Plattform.

Anatomie des Office.js-Add-Ins für Microsoft Word

Zuerst wird eine Anatomie eines Office.js für Microsoft Word betrachtet:

Überblick über die Anatomie eines Office.js-Add-Ins.

  • Alle Office-Add-Ins müssen beim ersten Laden einer Seite die Office.initialize()-Methode deaktivieren.
  • Wenn Sie eine neuere Office.js-Funktion in Ihrem Add-In verwenden, ist es wichtig zu prüfen, ob der Client diese Erweiterungen über die requirements-API unterstützt.
  • Für die JavaScript-APIs für Word verwenden Sie die Word.run()-Methode, um eine Instanz des aktuellen context-Dokuments zu erhalten.
  • Sobald Sie einen Verweis auf die context des aktuellen Word-Dokuments haben, können Sie mit der load()-Methode beliebige Eigenschaften auf den Kontext laden. Mit dieser Methode wird die Anfrage-Warteschlange hinzugefügt, so dass Sie mehrere Anfragen aus Performance-Gründen miteinander verketten können.
  • Wenn Sie bereit sind, die Eigenschaften, die Sie in die Warteschlange gestellt haben, abzurufen oder beliebige Aktionen in der Warteschlange durchzuführen, verwenden Sie die context.sync()-Methode, um den mit der load()-Methode definierten Stapel von Operationen in der Warteschlange auszuführen.
  • Die context.sync()-Methode gibt ein JavaScript-Versprechen zurück, das verwendet werden kann, um Ergebnisse oder einen vorherigen Vorgang zu erhalten und neue Vorgänge durchzuführen.
  • Als bewährte Methode sollten Sie auf Fehler, die bei der Arbeit mit den JavaScript-APIs für Word auftreten können, achten, sie abfangen und behandeln.

Text und Absätze

Entwickler von Word-Add-Ins sollten die Hierarchie eines Word-Dokuments und deren Beziehung zu den Objekten in Office.js verstehen.

Diagramm zeigt die Word-Dokumenthierarchie.

Office.js stellt den Kontext zu einem Word-Dokument über Word.run und die context.document-Eigenschaft zur Verfügung. Das Dokument enthält einen Textkörper, der viele Sammlungen enthält, einschließlich Absätzen, Tabellen und mehr.

Die Beziehungen in dieser Hierarchie werden als Eigenschaften in der API offengelegt, die das Traversieren nach oben (z. B.: paragraph.parentBody), nach unten (z. B.: body.paragraphs) und horizontal (z. B.: paragraph.getNext() oder paragraph.getPrevious()) zulassen.

Mit Office.js können Sie neue Absätze einfügen und bestehende Absätze und deren Darstellung in einem Dokument bearbeiten, löschen und entfernen.

Absätze erkennen ihre Angehörigen bei der Verwendung der Vorgänge getNext() und getPrevious() und beim Einfügen eines Absatzes relativ zu sich selbst bei der Verwendung von before oder dem Standort after.

Die folgenden Codeschnipsel demonstrieren Arbeitsbeispiele für Arbeitstext und Absätze unter Verwendung der JavaScript-API für Word:

  • einen Verweis auf den Dokumentenkörper erhalten:

    const docBody = context.document.body;

  • Einfügen eines Absatzes am Anfang des Dokumenttexts:

    docBody.insertParagraph('Hello World', 'Start');

  • Abrufen eines Verweises auf den ersten Absatz im Dokumenttext:

    const paragraph = context.document.body.paragraphs.getFirst();

  • Abrufen eines Verweises auf den zweiten Absatz in einem Dokumenttext:

    const paragraph = context.document.body.paragraphs.getFirst().getNext();

  • Abrufen eines Verweises auf den letzten Absatz in einem Dokumenttext:

    const paragraph = context.document.body.paragraphs.getLast();

  • Einfügen eines Absatzes nach der aktuellen Absatzposition:

    paragraph.insertParagraph('Hello World', 'After');

  • Löschen des Inhalts einer Tabelle:

    paragraph.clear();

  • Löschen des ersten Absatzes in einem Dokument:

    const paragraph = context.document.body.paragraphs.items[0].delete();

  • Einfügen eines Seitenumbruchs nach einem Absatz:

    paragraph.insertBreak('page', 'After');

  • Durchlaufen von allen Absätzen in einem Dokument:

    const paragraphs = context.document.body.paragraphs;
context.load(paragraphs, 'text');
return context.sync().then(() => {
  for (let i = 0; i < paragraphs.items.length; i++) {
    // do something with paragraph (paragraphs.items[i])
  }
}).then(context.sync);

Formatvorlagen und Textformatierung

Formatvorlagen und Formatierungen bilden ein attraktives Dokument. Office.js ermöglicht Ihnen die einfache Arbeit mit Formatvorlagen und Formatierungen aus Ihrem benutzerdefinierten Word-Add-In.

Screenshot der Formatvorlagen und Formatierungssteuerelemente im Word-Menüband.

Formatvorlagen

Die Formatvorlagen in Microsoft Word sind ähnlich wie eine CSS-Klasse in HTML. Sie bieten einen vorkonfigurierten und wiederverwendbaren Satz von Formatierungen, die auf einen Absatz oder einen Textbereich angewendet werden können.

Office.js kann sowohl Standard-Formatvorlagen als auch benutzerdefinierte Formatvorlagen auf Absätze und Textbereiche anwenden.

Schriftarten

Das Ändern einer Schriftart ist ähnlich der Anwendung eines Inline-Stils in HTML. Das Einstellen einer Schriftart ermöglicht es Ihnen, die Schriftfamilie, Gewicht, Größe, Farben und mehr zu manipulieren.

Wie Formatvorlagen können Schriftarten auf einen ganzen Absatz oder Textbereich angewendet werden.

Absatzformatierung

Über Formatvorlagen und Schriftarten hinaus bieten Absätze über „Office.js“ mehr Formatierung, z. B. Ausrichtung, Einzug und Zeilenabstand.

Die folgenden Codeschnipsel zeigen Arbeitsbeispiele für die Anwendung von Formatvorlagen und Formatierungen auf Text und Absätze unter Verwendung der JavaScript-API für Word:

  • Anwenden einer bekannten Word-Formatvorlage auf einen Absatz:

    paragraph.styleBuiltIn = Word.Style.intenseReference;

  • Anwenden einer benutzerdefinierten Formatvorlage auf einen Absatz:

    paragraph.style = 'MyCustomStyle';

  • Festlegen der Eigenschaft für die Absatzausrichtung mithilfe von left, centered, right oder justified:

    paragraph.alignment = 'centered';

  • Ändern der Schriftart eines Textbereichs:

    range.font.set({
    name: 'Courier New',
    bold: true,
    size: 18,
    color: '#0000ff',
    highlightColor: '#ffff00'
});

Auswahlen und Bereiche

Beim Arbeiten mit Office-Add-Ins hören Entwickler häufig den Begriff Bereich. Ein Bereich ist jeder angrenzende Bereich eines Dokuments in Microsoft Word.

Bereiche können auf verschiedene Weise festgelegt werden, z. B. durch Suche, Auswahl oder durch eine Konvertierung. Beispielsweise gibt die paragraph.getRange()-Methode den Absatz als Bereich zurück.

Screenshot von Microsoft Word mit ausgewähltem Text.

Auswahlen erlauben es Ihnen, sowohl den Inhalt als auch die Position des Fokus in einem Dokument zu manipulieren.

Sie können die Auswahl eines Bereichs erhalten oder die Auswahl auf einen Bereich setzen

Die folgenden Codeschnipsel zeigen Arbeitsbeispiele für die Beschaffung von und die Arbeit mit Textauswahlen unter Verwendung der JavaScript-API für Word:

  • Erhalten eines ausgewählten Textbereichs:

    const originalRange = document.getSelection();

  • Anhängen von Text an einen Textbereich:

    originalRange.insertText('added to the end', 'End');

  • Auswählen eines Textbereichs mithilfe der Abschnittsmodi Select, Start oder End:

    someRange.select('Select');

  • Suchen des aktuellen Absatzes nach einem Textbereich und ihn ersetzen:

    const ranges = paragraph.search('office', {matchCase: true, ignoreSpace: true});
context.load(ranges);
return context.sync().then(() => {
  for (let i = 0; i < ranges.items.length; i++) {
    ranges.items[i].insertText("Office", "Replace");
  }
}).then(context.sync);

Zusammenfassung

Die JavaScript-API für Word erleichtert die programmgesteuerte Kontrolle über Text, Formatierung, Auswahlen und Bereiche in Word-Dokumenten. In dieser Lektion erfahren Sie, wie Sie mit Text und Absätzen arbeiten, Formate und Formatierungen auf Text anwenden und wie Sie mit Textauswahlen und -bereichen aus einem benutzerdefinierten Word-Add-In arbeiten.