Grundlegendes zu JavaScript-APIs für Office
In dieser Einheit erfahren Sie mehr über das Programmiermodell für Office-Add-Ins, Entwicklertools und die Funktionen der Office JavaScript-APIs für Excel, Outlook und Word.
Grundlegendes zum Programmiermodell von Office-Add-Ins
Das Office-Add-in-Programmiermodell beruht auf zwei JavaScript-Objektmodellen:
- Host-spezifische JavaScript-API – Host-spezifische APIs für Excel und Word bieten typisierte Objekte, mit denen Sie auf bestimmte Elemente in der Host-Anwendung zugreifen können. So enthält beispielsweise die Excel-API Objekte, die Arbeitsblätter, Bereiche, Tabellen, Diagramme und vieles mehr repräsentieren.
- Gemeinsame API – mit der Einführung von Office 2013 können Sie mithilfe der gemeinsamen API auf Features wie folgende zugreifen:
- Benutzeroberfläche
- Dialoge
- Client-Einstellungen, die für mehrere Arten von Office-Anwendungen gleich sind
Benutzerdefinierte Funktionen verwenden ein etwas anderes Programmiermodell und werden in einer späteren Einheit behandelt.
JavaScript-API-Anforderungssätze für Office
Sie haben möglicherweise nicht immer Kontrolle über die Version von Office, die Ihre Benutzer installiert haben. Je nach der Version von Office und der Plattform, auf der sie ausgeführt wird, gibt es unterschiedliche APIs und Features, die für Ihr Add-In unterstützt werden. Office 2016 unterstützt beispielsweise mehr Funktionen als Office 2013. Für diese Situation bieten wir Anforderungsätze, mit denen Sie bestimmen können, ob ein Office-Host die von Ihrem Office-Add-In benötigten Funktionen unterstützt.
Anforderungssätze können für ihre jeweiligen Office-Hosts spezifisch sein, z. B. ExcelApi 1.7-Sätze oder für mehrere Hosts verwendbar sein, z.B. die Dialog-API. Die Anforderungssatzunterstützung variiert je nach Office-Host und -Hostversion.
Es ist möglich, programmgesteuert zu prüfen, ob Anforderungssätze vom Office-Host Ihres Add-Ins unterstützt werden, indem Sie isSetSupported verwenden. Falls der Anforderungssatz unterstützt wird, gibt isSetSupported den Wert true zurück und Ihr Add-In kann den zusätzlichen Code ausführen, der die API-Elemente aus dem Anforderungssatz verwendet. Wenn der Anforderungssatz vom Office-Host nicht unterstützt wird, gibt isSetSupported den Wert false zurück und der zusätzliche Code wird nicht ausgeführt. Im Folgenden finden Sie die mit isSetSupported zu verwendende Syntax.
if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion)) {
// Code that uses API members from RequirementSetName.
}
Hinweis
Office Insider-Programm
Wenn Sie die neuesten oder monatlichen Änderungen an den Office-Hosts erhalten möchten, können Sie am Office Insider-Programm teilnehmen. Dieses Programm ist nur für Windows-PCs vorgesehen und erfordert ein Microsoft 365-Abonnement. Wählen Sie in einer der Office-Anwendungen Datei>Konto>Office Insider aus, um schnell am Programm teilzunehmen.
Die Verwendung von Office JavaScript-APIs
Wenn Sie diese APIs verwenden möchten, referenzieren Sie sie auf dem Content Delivery Network (CDN) von Office.js, in der Regel durch Hinzufügen einer der folgenden Codeanweisungen zum <head>-Tag Ihrer Seite.
<!-- Reference the production APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
<!-- Reference the beta/preview APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js" type="text/javascript"></script>
Neben dem Hinzufügen Ihres bevorzugten CDN-Links ist für alle Office-Add-Ins ein Office.onReady()-Aufruf erforderlich. Sie fügen Ihren Add-In-Code in diese Methode ein und es wird aufgerufen, sobald die Office.js-Bibiothek intitialisiert wurde. In der onReady()-Methode können Sie bestimmen, welcher Host Ihr Add-In ausführt, indem Sie den Office.HostType Enumerationswert überprüfen (beispielsweise Excel oder Word). Sie können überprüfen, auf welcher Plattform das Add-in ausgeführt wird, mit einem Office.PlatformType-Enumerationswert (z. B. PC oder Mac).
Wenn Sie andere JavaScript-Frameworks verwenden, die eigene Initialisierungshandler oder Tests enthalten, sollten diese innerhalb der Antwort auf Office.onReady() platziert werden. So würden Sie beispielsweise die $(document).ready()-Funktion von jQuery so referenzieren, wie im folgenden Codebeispiel gezeigt.
Office.onReady(function() {
// Office is ready.
$(document).ready(function () {
// The document is ready.
});
});
Durchführen asynchroner Aufrufe mit Proxyobjekten
Wenn Sie mit einem Dokument arbeiten, werden die angeforderten Lese- oder Schreibvorgänge mit einem Proxyobjekt in einem Stapel verarbeitet. Ihre API-Aufrufe lesen oder aktualisieren das zugrunde liegende Dokument erst dann, wenn Sie die sync()-Methode aufrufen.
Zur Verbesserung der Sicherheit wird das Add-In in einer Sandbox-JavaScript-Umgebung ausgeführt, die keinen direkten Zugriff auf das Dokument oder andere Add-Ins bietet. Auf der Office-Add-Ins-Plattform wird ein RequestContext-Objekt bereitgestellt, das seinerseits Proxyobjekte zur Darstellung des Dokuments (z. B. Arbeitsblätter, Bereiche und Tabellen) bereitstellt. Die RequestContext wird in der Regel als Parameter mit der Bezeichnung context an Ihren Code übergeben. Sie können das context-Objekt dazu verwenden, jegliche Proxyobjekte zu erhalten, die Sie benötigen, um mit dem Dokument zu arbeiten.
Bevor Sie die Eigenschaften eines Proxyobjekts lesen können, müssen Sie die Eigenschaften laden, um das Proxyobjekt mit Daten aus dem Office-Dokument zu füllen. Dies erledigen Sie, indem Sie für alle benötigten Eigenschaften die load()-Methode auf das Proxyobjekt aufrufen. Rufen Sie dann die context.sync()-Methode auf, mit der alle angeforderten Eigenschaften geladen werden. Wenn Sie beispielsweise ein Proxybereichsobjekt erstellen, um mit einem vom Benutzer ausgewählten Bereich in einer Excel-Arbeitsmappe zu arbeiten, und dann die address-Eigenschaft des markierten Bereichs lesen möchten, müssen Sie die address-Eigenschaft laden, bevor Sie sie lesen können. Wenn Sie die Eigenschaften eines zu ladenden Proxyobjekts abfragen möchten, rufen Sie die load()-Methode für das Objekt auf und geben Sie die Eigenschaften an, die geladen werden sollen.
Das folgende Beispiel zeigt eine Funktion, die ein lokales Proxyobjekt definiert (selectedRange), die address-Eigenschaft dieses Objekts lädt und dann context.sync() aufruft. Wenn die Zusage von context.sync() aufgelöst ist, kann der Code die address-Eigenschaft lesen. Excel.run ist für diesen bestimmten Host erforderlich, um Eigenschaften zu laden, die sich auf das Plattformverhalten auswirken, wenn die Funktion ausgeführt wird. Nicht alle Hosts enthalten einen Run-Aufruf.
Excel.run(function (context) {
var selectedRange = context.workbook.getSelectedRange();
selectedRange.load('address');
return context.sync()
.then(function () {
console.log('The selected range is: ' + selectedRange.address);
});
}).catch(function (error) {
console.log('error: ' + error);
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Grundlegendes zu den Entwicklertools für Office-Add-Ins
Mit den Entwicklertools für Office-Add-Ins können Sie ein Office-Add-In erstellen, Office-JavaScript-APIs erkunden und eine Office-Add-Ins-Manifestdatei überprüfen. In diesem Abschnitt lernen Sie die folgenden Tools kennen:
- Yeoman-Generator für Office-Add-Ins
- Visual Studio
- Script Lab
- Manifest-Validator
Erstellen eines Office-Add-Ins
Für die Erstellung von Office-Add-Ins können Sie den Yeoman-Generator für Office-Add-Ins oder Visual Studio verwenden.
Tipp
Installieren und erfahren Sie mehr über den Yeoman-Generator für Office-Add-ins unter github.com/OfficeDev/generator-office.
Yeoman-Generator für Office-Add-Ins
Mit dem Yeoman-Generator für Office-Add-Ins kann ein Node.js-Office-Add-In-Projekt erstellt werden, das mit Visual Studio Code oder einem beliebigen anderen Editor verwaltet werden kann. Der Generator kann Office Add-Ins erstellen für:
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
- Benutzerdefinierte Excel-Funktionen
Sie können das Projekt mithilfe von HTML, CSS und JavaScript oder unter Verwendung von Angular oder React erstellen. Außerdem ist TrueScript auch eine Option.
Führen Sie die folgenden Schritte aus, um ein Office-Add-In-Projekt mit dem Yeoman-Generator zu erstellen.
Um Yeoman und den Yeoman-Generator für Office-Add-Ins mit npm, dem Node-Paketmanager, global zu installieren, führen Sie den folgenden Befehl aus.
npm install -g yo generator-officeFühren Sie den folgenden Befehl aus, um ein Add-In-Projekt mit dem Yeoman-Generator zu erstellen.
yo office
Visual Studio
Visual Studio kann verwendet werden, um Office-Add-Ins für Excel, Word, PowerPoint oder Outlook zu erstellen. Ein Office-Add-in-Projekt wird als Teil einer Visual Studio-Lösung erstellt, was bedeutet, dass Sie Visual Studio-Features wie die Auswahl von Start oder F5 nutzen können, um das Add-In automatisch lokal auf IIS auszuführen. Office-Add-In-Projekte, die Sie in Visual Studio erstellen, verwenden HTML, CSS und JavaScript.
Um ein Office Add-In mit Visual Studio zu erstellen, erstellen Sie ein neues C#- oder Visual Basic-Projekt und wählen Sie einen der folgenden Projekttypen:
- Excel-Web-Add-In
- Outlook-Web-Add-In
- PowerPoint-Web-Add-In
- Word-Web-Add-In
Erforschen Sie APIs mit Script Lab
Script Lab ist ein Add-In, das es Ihnen ermöglicht, Office-JavaScript-Codeausschnitte auszuführen, während Sie in einem Office-Programm wie z. B. Excel oder Word arbeiten. Es steht kostenlos unter AppSource- zur Verfügung und ist ein sehr nützliches Tool, das Sie in Ihr Entwickler-Toolkit einschließen sollten, wenn Sie testen und die Funktionalitäten, die Sie für Ihr Add-In wünschen, überprüfen möchten. Über Script Lab haben Sie Zugriff auf eine Bibliothek mit integrierten Beispielen, die Sie zum schnellen Ausprobieren von APIs oder sogar als Ausgangspunkt für Ihren eigenen Code verwenden können.
Das folgende Video zeigt Script Lab in Aktion.
Validieren der Manifestdatei eines Office-Add-Ins
Der Office-Add-In-Manifestdatei-Validator überprüft die Add-In-Manifestdatei, um zu bestimmen, ob sie korrekt und vollständig ist. Wenn Sie Ihr Add-In-Projekt mit dem Yeoman-Generator für Office-Add-Ins (Version 1.1.17 oder höher) erstellt haben, können Sie das Manifest validieren, indem Sie den folgenden Befehl im Stammverzeichnis des Projekts ausführen.
npm run validate
Falls Sie zum Erstellen des Add-In-Projekts nicht den Yeoman-Generator verwendet haben, können Sie das Manifest des Add-Ins überprüfen, indem Sie die folgenden Schritte ausführen.
Installieren Sie Node.js.
Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus.
Wichtig
Ersetzen Sie
{{MANIFEST_FILE}}durch den Namen Ihrer Manifestdatei.npx office-addin-manifest validate {{MANIFEST_FILE}}
Grundlegendes zu den Fähigkeiten der Excel-JavaScript-API
Mit den Excel-JavaScript-APIs können Ihre Add-ins auf Excel-Dokumente zugreifen. Ein Excel-Add-in kann den Inhalt, die Formatierung und die Struktur einer Arbeitsmappe oder eines Arbeitsblatts verwalten.
Grundlegendes zu den Fähigkeiten der Outlook-JavaScript-API
Mit den JavaScript-APIs von Outlook können Ihre Add-Ins auf das Postfach, die Nachrichten und Termine des Benutzers in Outlook zugreifen. Ein Outlook-Add-In kann den Inhalt und die Eigenschaften einer Nachricht oder eines Termins abrufen. Ein Add-In kann auch den Inhalt, die Formatierung und Struktur einer Nachricht oder eines Termins verwalten, die oder der gerade erstellt wird.
Objektmodell
Wenn Sie die Outlook-APIs verstehen möchten, schauen Sie sich zunächst an, wie die Hauptkomponenten eines Postfachs zueinander in Beziehung stehen.
- Das Postfach-Objekt ermöglicht Ihnen die Handhabung der Authentifizierung, das Verwalten eines ausgewählten Elements und die Einsicht auf Benutzerprofildaten.
- Das Element-Objekt stellt die ausgewählte Nachricht oder den ausgewählten Termin dar, die bzw. den der Benutzer liest oder verfasst.
Mithilfe der Outlook-APIs können Sie viele Eigenschaften einer E-Mail oder eines Termins verwalten. Viele der APIs sind um den Modus angeordnet, in dem sich der Benutzer befindet. Die folgende Tabelle verbindet Elementtypen und Modi.
| Elementtyp | Modi |
|---|---|
| Nachricht | Lesen Verfassen |
| Termin/Besprechung | Teilnehmer (lesen) Organisator (verfassen) |
Hauptmerkmale
Zusätzlich zu den Aufgabenbereich-Add-Ins können Sie Kontext-und Modul-Add-Ins erstellen. In diesem Abschnitt erfahren Sie mehr über einige der wichtigsten Features von Outlook-APIs.
- Authentifizierungsoptionen
- Kontext-Add-Ins
- Model-Add-Ins
Authentifizierung
Ihr Outlook-Add-In kann auf Informationen an beliebiger Stelle im Internet zugreifen. Einige Beispiele hierfür sind der Server, der das Add-In hostet, Ihr internes Netzwerk oder ein anderer Ort in der Cloud. Wenn diese Informationen geschützt sind, muss das Add-In Ihren Benutzer authentifizieren. Outlook-Add-Ins bieten je nach Ihrem speziellen Szenario zahlreiche unterschiedliche Methoden zum Authentifizieren.
Exchange-Benutzeridentitätstoken
Mithilfe von Exchange-Benutzeridentitätstoken kann Ihr Add-In die Identität des Benutzers ermitteln. Indem Sie die Identität des Benutzers überprüfen, können Sie einen Benutzer einmalig in Ihr System authentifizieren und dann das Benutzeridentitätstoken als Autorisierung für weitere Anforderungen akzeptieren. Erwägen Sie die Verwendung von Benutzeridentitätstoken, wenn das Add-In hauptsächlich von lokalen Exchange-Benutzern verwendet wird oder Zugriff auf einen nicht von Microsoft bereitgestellten Dienst benötigt, den Sie steuern. Das Add-In kann getUserIdentityTokenAsync() aufrufen, um Exchange-Benutzeridentitätstoken abzurufen.
Abrufen von Zugriffstoken mit OAuth2-Flows
Add-Ins können auch auf Drittanbieterdienste zugreifen, die für die Autorisierung OAuth2 unterstützen. Erwägen Sie die Verwendung von OAuth2-Token, falls Ihr Add-In Zugriff auf einen Drittanbieterdienst benötigt, der nicht Ihrer Kontrolle unterliegt. Bei dieser Methode fordert das Add-In den Benutzer auf, sich beim Dienst anzumelden, indem er beispielsweise die displayDialogAsync()-Methode verwendet, um den OAuth2-Fluss zu initialisieren.
Rückruftoken
Rückruftoken ermöglichen Ihrem Add-In den Zugriff auf das Postfach des Benutzers von Ihrem Server aus, entweder mithilfe der Exchange-Webdienste (EWS) oder der Outlook REST-API. Add-Ins erhalten Rückruftoken mithilfe einer der getCallbackTokenAsync()-Methoden. Die Zugriffsebene wird durch die im Add-In-Manifest angegebenen Berechtigungen gesteuert.
Authentifizierung: Zusammenfassung
Die folgende Tabelle fasst zusammen, in welchem Fall Sie welche Art von Zugriffstoken verwenden sollen.
| Zugriffstoken | Verwenden, falls Ihr Add-In ... |
|---|---|
| Benutzeridentitätstoken austauscht | Primär von lokalen Exchange-Benutzern verwendet wird. Zugriff auf einen nicht von Microsoft bereitgestellten Dienst benötigt, den Sie verwalten. |
| OAuth2-Zugriffstoken | Zugriff auf einen Drittanbieterdienst benötigt, den Sie nicht verwalten. |
| Rückruftoken | Zugriff auf das Postfach des Benutzers von Ihrem Server aus benötigt. |
Kontext-Add-Ins
Kontextbezogene Add-Ins sind Outlook-Add-Ins, die auf der Grundlage von Text in einer Nachricht oder einem Termin aktiviert werden. Sie kennen möglicherweise bereits die standardmäßigen kontextabhängigen Add-Ins in Outlook, wie Bing Maps oder Vorgeschlagene Besprechungen. Mit kontextuellen Add-Ins können Benutzer Aufgaben im Zusammenhang mit einer Nachricht starten, ohne die Nachricht selbst zu verlassen. Das erhöht die Benutzerfreundlichkeit und bietet mehr Möglichkeiten.
Die folgende Tabelle zeigt einige Beispielaufgaben basierend auf der Auswahl eines Benutzers.
| Der Benutzer wählt ... | Aktion des kontextbezogenen Add-Ins |
|---|---|
| Adresse | Öffnet eine Karte des Standorts. |
| Zeichenfolge | Öffnet ein Add-In, das Besprechungsvorschläge macht. |
| Telefonnummer | Fügt die Nummer Ihren Kontakten hinzu. |
Hinweis
Kontext-Add-Ins sind derzeit nicht in Outlook für Android und Outlook für iOS verfügbar.
Die folgende Abbildung zeigt ein kontextbezogenes Add-In, das in Outlook angezeigt wird.
Ein kontextbezogenes Add-In in Outlook
Das Manifest eines kontextbezogenen Add-Ins muss ein ExtensionPoint-Element mit einem xsi:type-Attribut mit dem Wert DetectedEntity aufweisen. Innerhalb des ExtensionPoint-Elements gibt das Add-In die Entitäten oder den regulären Ausdruck an, von denen bzw. dem es aktiviert werden kann. Wenn eine Entität angegeben wird, kann es sich um eine beliebige der Eigenschaften im Entities-Objekt handeln.
Als solches muss das Manifest des Add-Ins eine Regel des Typs ItemHasKnownEntity oder ItemHasRegularExpressionMatch beinhalten. Das folgende Beispiel zeigt, wie Sie festlegen, dass ein Add-In für Nachrichten aktiviert werden soll, die eine Telefonnummer enthalten.
<ExtensionPoint xsi:type="DetectedEntity">
<Label resid="contextLabel" />
<SourceLocation resid="detectedEntityURL" />
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="PhoneNumber" Highlight="all" />
</Rule>
</ExtensionPoint>
Nachdem ein kontextuelles Add-In mit einem Konto verknüpft wurde, wird es automatisch gestartet, wenn Benutzer eine hervorgehobene Entität oder einen regulären Ausdruck auswählen.
Ein Benutzer startet ein Kontext-Add-In durch Text, entweder eine bekannte Entität oder einen regulären Ausdruck eines Entwicklers. In der Regel identifiziert ein Benutzer ein Kontext-Add-In dadurch, dass die Entität hervorgehoben ist.
Model-Add-Ins
Modul-Add-Ins werden in der Outlook-Navigationsleiste rechts neben den E-Mail-Nachrichten, den Aufgaben und den Kalendern angezeigt. Sie können alle Funktionen der Outlook JavaScript-API in Ihrem Add-In verwenden und Befehlsschaltflächen im Outlook-Menüband erstellen, damit der Benutzer mit dem Add-In-Inhalt interagieren kann.
Hinweis
Modul-Add-Ins werden nur in Outlook 2016 oder neuer auf Windows unterstützt.
Die folgende Abbildung zeigt ein Beispiel für ein Modulerweiterungs-Add-In.
Beispiel für ein Modul-Add-In in Outlook unter Windows
Wenn Sie ein Modul-Add-In erstellen möchten, schließen Sie den Punkt „Modulerweiterung“ in die Manifestdatei Ihres Add-Ins ein. Das folgende Beispiel zeigt ein Codebeispiel einer Manifestdatei, die abgeändert wurde, um eine Modulerweiterung zu definieren.
...
<!-- Add Outlook module extension point. -->
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides"
xsi:type="VersionOverridesV1_0">
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
xsi:type="VersionOverridesV1_1">
<!-- Begin override of existing elements. -->
<Description resid="residVersionOverrideDesc" />
<Requirements>
<bt:Sets DefaultMinVersion="1.3">
<bt:Set Name="Mailbox" />
</bt:Sets>
</Requirements>
<!-- End override of existing elements. -->
<Hosts>
<Host xsi:type="MailHost">
<DesktopFormFactor>
<!-- Set the URL of the file that contains the
JavaScript function that controls the extension. -->
<FunctionFile resid="residFunctionFileUrl" />
<!-- Module extension point for a ModuleApp -->
<ExtensionPoint xsi:type="Module">
<SourceLocation resid="residExtensionPointUrl" />
<Label resid="residExtensionPointLabel" />
<CommandSurface>
<CustomTab id="idTab">
<Group id="idGroup">
<Label resid="residGroupLabel" />
<Control xsi:type="Button" id="group.changeToAssociate">
<Label resid="residChangeToAssociateLabel" />
<Supertip>
<Title resid="residChangeToAssociateLabel" />
<Description resid="residChangeToAssociateDesc" />
</Supertip>
<Icon>
<bt:Image size="16" resid="residAssociateIcon16" />
<bt:Image size="32" resid="residAssociateIcon32" />
<bt:Image size="80" resid="residAssociateIcon80" />
</Icon>
<Action xsi:type="ExecuteFunction">
<FunctionName>changeToAssociateRate</FunctionName>
</Action>
</Control>
</Group>
<Label resid="residCustomTabLabel" />
</CustomTab>
</CommandSurface>
</ExtensionPoint>
</DesktopFormFactor>
</Host>
</Hosts>
<Resources>
...
</Resources>
</VersionOverrides>
</VersionOverrides>
Erste Schritte zum Entwickeln von Outlook-Add-Ins
Wenn Sie ein Outlook-Add-In entwickeln möchten, verwenden Sie Folgendes:
- Der Yeoman-Generator für Office-Add-Ins
- Visual Studio
Sie können eine Vorlage als Basis verwenden und dann Ihre gewünschte Funktionalität hinzufügen.
Grundlegendes zu den Fähigkeiten der Word-JavaScript-API
Mit den Word-JavaScript-APIs können Ihre Add-Ins auf Word-Dokumente zugreifen. Ein Add-In für Word kann den Inhalt, die Formatierung und Struktur eines Dokuments verwalten.
Objektmodell
Um die Word-APIs zu verstehen, müssen Sie verstehen, wie die Hauptkomponenten eines Dokuments zueinander in Verbindung stehen.
- Ein Dokument enthält einen Textkörper und mindestens ein Abschnitt.
- Ein Textkörper kann folgendes enthalten:
- Absatz(einer oder mehrere)
- Tabelle (eine oder mehrere)
- Liste (eine oder mehrere)
- Text
- Objekte wie Bilder und Listen
- Ein Abschnitt gewährt Zugriff auf seinen Textkörper, Überschriften und Fußzeilen.
Schlüsselszenarien
In diesem Abschnitt lernen Sie einige der Schlüsselszenarien für Word-APIs kennen.
- Arbeiten mit Dokumententext
- Suche
Hinweis
Sie können mit den Office.js-APIs einfache Formatierungen auf ein gesamtes vorhandenes Dokument anwenden. Wenn Sie jedoch komplexe Formatierungen anwenden oder Rich-Content-Objekte verwenden möchten, können Sie diese Effekte mithilfe von Office Open XML (OOXML) erstellen. Beispiele für Funktionen in OOXML sind das Anwenden von Schlagschatten auf Text oder Bilder, das Erzwingen von Textfeldern in Formen und das Einfügen von Excel-Diagrammen in Echtzeit-Diagramme in Word-Dokumenten. Da es sich um eine fortgeschrittene Fertigkeit handelt, wird dieses Thema nicht vollständig behandelt, sondern für Entwickler erwähnt, die mit OOXML vertraut sind.
Arbeiten mit Dokumententext
Word Add-Ins nutzen zum Starten den Office.onReady()-Ereignishandler. Falls das Add-In auf Word 2016 oder neuer abzielt, ruft es die Word.run()-Methode auf, um Word JavaScript APIs auszuführen. Das Add-In muss eine Funktion an Word.run() übergeben, das erwartet, dass ein Kontextobjekt als Parameter übergeben wird. Das Kontextobjekt erlaub es dem Add-In, mit dem Word-Dokument zu interagieren. Sie können das Kontextobjekt verwenden, um jegliches benötigte Proxyobjekt für das Word-Dokument zu erstellen und die Proxies mit jeglichen Eigenschaften zu laden, die Sie verwenden möchten. Sie können Aktionen auch so programmieren, dass diese mit diesen Eigenschaften ausgeführt werden sollen. Wie immer synchronisiert ein Befehl context.sync() den Status zwischen den Proxyobjekten und Objekten im Word-Dokument.
Das folgende Beispiel zeigt Code, der Text nach dem Textkörpertext eines Word-Dokuments einfügt. Zur Vereinfachung lässt dieses Bespiel den Office.onReady()-Code aus und konzentriert sich auf den Code innerhalb eines Word.run()-Codeblocks.
// Run a batch operation against the Word JavaScript API.
Word.run(function (context) {
// Create a proxy object for the document body.
var body = context.document.body;
// Queue a command to load the text property of the proxy body object.
body.load("text");
// Queue a command to insert text into the end of the Word document body.
body.insertText('This is text inserted after loading the body.text property',
Word.InsertLocation.end);
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log("Body contents: " + body.text);
});
})
Suche
Sie können die APIs verwenden, um im Dokument nach Text zu suchen, der Ihren Kriterien entspricht. Sie können die Suche auch auf bestimmte Inhaltstypen festlegen, z.B. Absätze oder Tabellen.
Im folgenden Codebeispiel wird nach dem Text „video you“ gesucht und die Interpunktion wird ignoriert. Falls der Text gefunden wird, werden die Treffer fett formatiert, gelb hervorgehoben und die Schriftfarbe auf Violett festgelegt.
// Run a batch operation against the Word object model.
Word.run(function (context) {
// Queue a command to search the document and ignore punctuation.
var searchResults = context.document.body.search('video you', {ignorePunct: true});
// Queue a command to load the search results and get the font property values.
context.load(searchResults, 'font');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log('Found count: ' + searchResults.items.length);
// Queue a set of commands to change the font for each found item.
for (var i = 0; i < searchResults.items.length; i++) {
searchResults.items[i].font.color = 'purple';
searchResults.items[i].font.highlightColor = '#FFFF00'; // Yellow
searchResults.items[i].font.bold = true;
}
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync();
});
})
.catch(function (error) {
console.log('Error: ' + JSON.stringify(error));
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Erste Schritte zum Entwickeln von Word-Add-Ins
Um ein Word Add-In zu entwickeln, verwenden Sie:
- Der Yeoman-Generator für Office-Add-Ins
- Visual Studio
Wenn Sie mehr über die APIs erfahren möchten, empfehlen wir Ihnen das Script Lab Add-In. Dort finden Sie viele TypeScript- und JavaScript-Codebeispiele und können mit Word-Dokumenten experimentieren, ohne ein vollständiges Add-In erstellen zu müssen.
Lernen Sie die Fähigkeiten von benutzerdefinierten Funktionen kennen
Benutzerdefinierte Funktionen verfügen über mehrere einmalige Funktionen und Einschränkungen, da Sie von anderen Add-In-Interaktionen, z. B. Aufgabenbereichen, getrennt in einer separaten Laufzeit ausgeführt werden.
Fähigkeiten benutzerdefinierter Funktionen
Sie können eigene JavaScript- oder TypeScript-Funktionen erstellen, die genau wie eingebaute Excel-Funktionen aufgerufen werden können, wie z.B. SUM(). Sie können auch eigene Streamingfunktionen erstellen, die Werte timergesteuert zurückgeben. Beispielsweise können Sie die aktuelle Zeit einmal pro Sekunde in eine Zelle schreiben lassen. Sie können aus benutzerdefinierten Funktionen auch Netzwerkaufrufe tätigen.
JavaScript-Beispiel für eine benutzerdefinierte Funktion
Das folgende Codebeispiel definiert die eigene Funktion add(), die zwei Zahlen akzeptiert und dann deren Summe zurückgibt.
/**
* Adds two numbers.
* @customfunction
* @param first First number.
* @param second Second number.
* @returns The sum of the two numbers.
*/
function add(first, second){
return first + second;
}
JSDoc-Codekommentar-Beschreibungen
Die JSDoc-Tags in den Codekommentaren werden verwendet, um eine JSON-Metadatendatei zu generieren, die die benutzerdefinierte Funktion für Excel beschreibt. Die JSON-Metadatendatei ermöglicht es Excel, Informationen einem Benutzer gegenüber exakt vorzuführen und die erwarteten Parameter an die benutzerdefinierte Funktion zu übergeben.
@customfunction: Wird zuerst deklariert und gibt an, dass es sich um eine benutzerdefinierte Funktion handelt. Erforderlich.@param: Beschreibt den Parameter. Für jeden durch die Funktion definierten Parameter einschließen.@returnsBeschreibt die Ausgabe der Funktion.
Hinweis
Die Kommentarbeschreibung „Addiert zwei Zahlen.“ wird auch der JSON-Metadatendatei für Excel hinzugefügt, die angezeigt wird, wenn der Benutzer Ihre benutzerdefinierte Funktion anzeigt.
Laufzeitbeschränkungen benutzerdefinierter Funktionen
Die Laufzeit der benutzerdefinierten Funktion führt nur JavaScript aus. Es gibt kein Dokumentobjektmodell (DOM) und keinen lokalen Speicher, wie in einer browserbasierten JavaScript-Laufzeitumgebung. Dies bedeutet, dass Sie keine Bibliotheken laden können, die das DOM verwenden, wie z.B. jQuery. Außerdem können Sie nicht auf die Office.js-API zugreifen, um mit dem Dokument zu interagieren, wie das bei einem Taskbereich der Fall ist. Die Laufzeit der benutzerdefinierten Funktionen ist stattdessen für Aufgaben wie schnelle Berechnungen optimiert und muss in der Regel einige der Office.js-APIs, z. B. Formatierungstools in Excel, nicht verwenden.
Benutzerdefinierte Funktionen verfügen über eine Webseite, welche die Laufzeit der benutzerdefinierten Funktionen lädt. Da die Laufzeit der benutzerdefinierten Funktionen keine Benutzeroberfläche besitzt, muss bzw. kann die Webseite nichts anzeigen. Sie finden das folgende Script-Tag auf der Webseite, welche die Bibliothek für die Laufzeit der benutzerdefinierten Funktionen lädt.
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/custom-functions-runtime.js" type="text/javascript"></script>
Benutzerdefinierte Funktionen werden normalerweise mit einem Aufgabenbereich im selben Add-In kombiniert. Wenn Sie ein Add-in-Projekt mithilfe des Yeoman-Generators für Office-Add-Ins erstellen, enthält das Projekt eine Webseite für die benutzerdefinierten Funktionen und eine Webseite mit der Benutzeroberfläche für den Aufgabenbereich.
Die Verwendung von Speicher-APIs zur Kommunikation mit dem Aufgabenbereich
Code für benutzerdefinierte Funktionen und Code für den Aufgabenbereich (der Office.js verwendet) kann gegenseitig keine Aufrufe durchführen oder miteinander kommunizieren. Sie können aber eine Speicher-API verwenden, die es ihnen ermöglicht, Daten auszutauschen. Ein übliches Szenario zur Verwendung von Speicher-APIs ist der Fall, dass ein Add-In ein Sicherheitstoken zum Zugriff auf eine gesicherte Netzwerkressource freigeben muss. Der Benutzer könnte zuerst eine benutzerdefinierte Funktion aufrufen, die es erforderlich macht, angemeldet zu sein. Nach der Authentifizierung empfängt diese das Sicherheitstoken. Dann teilt es dieses Sicherheitstoken unter Verwendung der Speicher-API, damit später, wenn der Nutzer den Aufgabenbereich öffnet, dieser ihn nicht erneut zur Anmeldung auffordert.
Alternativ könnte der Nutzer zuerst den Aufgabenbereich öffnen. In diesem Fall wird der Aufgabenbereich den Nutzer anmelden und das Sicherheitstoken durch die Speicher-API freigeben. Wenn später eine benutzerdefinierte Funktion verwendet wird, kann die benutzerdefinierte Funktion das Sicherheitstoken über die Speicher-API abrufen.
Beispiel: Speicher-API
Das folgende Codebeispiel zeigt, wie alle vom Benutzer erstellten Werte gespeichert und abgerufen werden.
/**
* @customfunction
* @description Stores a value in OfficeRuntime.storage.
* @param {any} key Key in the key-value pair you will store.
* @param {any} value Value in the key-value pair you will store.
*/
function storeValue(key, value) {
return OfficeRuntime.storage.setItem(key, value).then(function (result) {
return "Success: Item with key '" + key + "' saved to storage.";
}, function (error) {
return "Error: Unable to save item with key '" + key + "' to storage. " + error;
});
}
/**
* @customfunction
* @description Gets value from OfficeRuntime.storage.
* @param {any} key Key of item you intend to get.
*/
function getValue(key) {
return OfficeRuntime.storage.getItem(key);
}
Dialog-API
Benutzerdefinierte Funktionen besitzen ihre eigene Dialog-API, da sie keinen Zugriff auf die Office.js-API besitzen. Jedoch ist die Funktionalität ähnlich. Das häufigste Szenario ist der Aufruf eines Dialogs, um den Benutzer anzumelden und ein Sicherheitstoken zu erhalten.
Das folgende Codebeispiel zeigt, wie ein Webdialogfeld aus einer benutzerdefinierten Funktion heraus angezeigt wird.
OfficeRuntime.displayWebDialog('https://myDomain/myDialog.html', {height: 30, width: 20});
Erstellung eines Projekts für benutzerdefinierte Funktionen
Sie können ein Projekt für benutzerdefinierte Funktionen durch die Verwendung des Yeoman-Generators für Office Add-Ins erstellen. Führen Sie yo office aus, um den Generator zu starten. Wählen Sie dann die Option Projekt für Excel Add-In mit benutzerdefinierten Funktionen aus. Sobald es erstellt wurde, wird Ihr Projekt einen Ordner /src/taskpane/ für die Quelldateien des Aufgabenbereichs enthalten sowie einen Ordner /src/functions für die Quelldateien der benutzerdefinierten Funktionen.
Hinweis
In Visual Studio können Sie kein Projekt für benutzerdefinierte Funktionen erstellen.
Zusammenfassung
In dieser Einheit haben Sie mehr über das Programmiermodell von Office-Add-Ins, Entwicklertools und die Funktionen der Office JavaScript-APIs für Excel, Outlook und Word erfahren.