Automatisches Öffnen eines Aufgabenbereichs mit einem Dokument

Sie können Add-In-Befehle in Ihrem Office-Add-In verwenden, um die Office-Benutzeroberfläche zu erweitern, indem Sie Schaltflächen zum Menüband der Office-App hinzufügen. Wenn Benutzer auf Ihre Befehlsschaltfläche klicken, wird eine Aktion ausgeführt, z. B. das Öffnen eines Aufgabenbereichs.

Einige Szenarien erfordern, dass ein Aufgabenbereich automatisch geöffnet wird, wenn ein Dokument geöffnet wird, ohne eine explizite Benutzerinteraktion. Sie können das im AddInCommands 1.1-Anforderungssatz eingeführte Feature zum automatischen Öffnen des Aufgabenbereichs verwenden, um automatisch einen Aufgabenbereich zu öffnen, wenn Ihr Szenario dies erfordert.

Wie unterscheidet sich das AutoOpen-Feature vom Einfügen eines Aufgabenbereichs?

Wenn ein Benutzer Add-Ins startet, die keine Add-In-Befehle verwenden, werden die Add-Ins in das Dokument eingefügt und bleiben in diesem Dokument erhalten. Wenn andere Benutzer das Dokument öffnen, werden sie zur Installation des Add-Ins aufgefordert, und der Aufgabenbereich wird geöffnet. Die Herausforderung bei diesem Modell besteht darin, dass die Benutzer in vielen Fällen nicht möchten, dass das Add-In im Dokument verbleibt. Beispielsweise möchte ein Schüler, der ein Wörterbuch-Add-In in einem Word Dokument verwendet, möglicherweise nicht, dass seine Klassenkameraden oder Lehrer aufgefordert werden, dieses Add-In zu installieren, wenn er das Dokument öffnet.

Mit dem AutoOpen-Feature können Sie explizit definieren oder dem Benutzer ermöglichen festzulegen, ob ein bestimmtes Aufgabenbereich-Add-In in einem bestimmten Dokument beibehalten wird.

Support und Verfügbarkeit

Das Autoopen-Feature wird derzeit in den folgenden Produkten und Plattformen unterstützt.

Bewährte Methoden

Wenden Sie die folgenden bewährten Methoden an, wenn Sie die AutoOpen-Funktion verwenden.

• Verwenden Sie das AutoOpen-Feature, wenn die Benutzer Ihres Add-Ins dadurch effizienter arbeiten können, wie beispielsweise in den folgenden Fällen:
  • Das Dokument benötigt das Add-In, damit es ordnungsgemäß ausgeführt werden kann. Beispiel: Eine Tabellenkalkulation mit Aktienwerten, die regelmäßig durch das Add-In aktualisiert werden. Das Add-In sollte beim Öffnen der Tabellenkalkulation automatisch geöffnet werden, damit die Werte auf dem neuesten Stand sind.
  • Der Benutzer verwendet wahrscheinlich immer das Add-In mit einem bestimmten Dokument. Beispiel: Ein Add-In, das den Benutzer beim Ausfüllen oder Ändern von Daten in einem Dokument unterstützt, indem es Daten aus dem Back-End-System abruft.
• Ermöglichen Sie den Benutzern, das AutoOpen-Feature aktivieren und deaktivieren zu können. Fügen Sie der Benutzeroberfläche eine Option hinzu, damit Benutzer wählen können, dass der Add-In-Aufgabenbereich nicht mehr automatisch geöffnet wird.
• Verwenden Sie die Anforderungssatzerkennung, um zu bestimmen, ob das AutoOpen-Feature verfügbar ist, und bieten Sie ein Fallbackverhalten, wenn dies nicht der Fall ist.
• Verwenden Sie das AutoOpen-Feature nicht, um die Nutzung Ihres Add-Ins künstlich zu erhöhen. Wenn es nicht sinnvoll ist, dass Ihr Add-In automatisch mit bestimmten Dokumenten geöffnet wird, kann diese Funktion Benutzer verärgern.
• Verwenden Sie dieses Feature nicht, um mehrere Aufgabenbereiche anzuheften. Sie können nur einen Bereich des Add-Ins festlegen, der automatisch in einem Dokument geöffnet wird.

Implementieren der Autoopen-Funktion

• Geben Sie an, welcher Aufgabenbereich automatisch geöffnet werden soll.
• Markieren Sie das Dokument zum automatischen Öffnen des Aufgabenbereichs.

Schritt 1: Angeben des zu öffnenden Aufgabenbereichs

Konfigurieren Sie das Manifest, um die Aufgabenbereichsseite anzugeben, die automatisch geöffnet werden soll. Der Prozess hängt davon ab, welche Art von Manifest das Add-In verwendet.

"runtimes": [
    {
        ...
        "code": {
            "page": "https://contoso.com/taskpane.html"
        },
        "actions": [
            {
                "id": "ShowTaskPane",
                "type": "openPage",
                "view": "Office.AutoShowTaskpaneWithDocument"
            }
        ]
    }
]

<Action xsi:type="ShowTaskpane">
    <TaskpaneId>Office.AutoShowTaskpaneWithDocument</TaskpaneId>
    <SourceLocation resid="Contoso.Taskpane.Url" />
</Action>

Schritt 2: Markieren des Dokument zum automatischen Öffnen des Aufgabenbereichs

Sie haben zwei Möglichkeiten, das Dokument zum Auslösen des AutoOpen-Features zu markieren. Wählen Sie die Alternative, die für Ihr Szenario am besten funktioniert.

Markieren des Dokuments auf Seite des Clients

Verwenden Sie die Office.js settings.set-Methode , um Office.AutoShowTaskpaneWithDocument auf truefestzulegen, wie im folgenden Beispiel gezeigt.

Office.context.document.settings.set("Office.AutoShowTaskpaneWithDocument", true);
Office.context.document.settings.saveAsync();

Verwenden Sie diese Methode, wenn Sie das Dokument als Teil Ihrer Add-In-Interaktion kennzeichnen müssen (z. B. sobald der Benutzer eine Bindung erstellt oder eine Option auswählt, um anzugeben, dass der Bereich automatisch geöffnet werden soll).

Verwenden von Open XML zum Markieren des Dokuments

Sie können Open XML verwenden, um ein Dokument zu erstellen oder zu ändern und das entsprechende Open Office XML-Markup zum Auslösen des AutoOpen-Features hinzuzufügen. Ein Beispiel zur Vorgehensweise finden Sie unter Office-OOXML-EmbedAddin.

Fügen Sie dem Dokument zwei Open XML-Teile hinzu.

• Ein webextension-Teil
• Ein taskpane-Teil

Das folgende Beispiel zeigt, wie Sie den webextension-Teil hinzufügen.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="[ADD-IN ID PER MANIFEST]">
  <we:reference id="[GUID or Microsoft Marketplace asset ID]" version="[your add-in version]" store="[Pointer to store or catalog]" storeType="[Store or catalog type]"/>
  <we:alternateReferences/>
  <we:properties>
   <we:property name="Office.AutoShowTaskpaneWithDocument" value="true"/>
  </we:properties>
  <we:bindings/>
  <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

Der webextension-Teil enthält einen Eigenschaftenbehälter und eine Eigenschaft mit dem Namen Office.AutoShowTaskpaneWithDocument, die auf true festgelegt werden muss.

Der webextension-Teil enthält auch einen Verweis auf den Store oder den Katalog mit Attributen für id, storeType, store und version. Von den storeType-Werten sind nur vier relevant für das AutoOpen-Feature. Die Werte für die anderen drei Attribute sind von dem Wert für storeType abhängig, wie in der folgenden Tabelle dargestellt.

Weitere Informationen über das Webextension-Markup finden Sie unter [MS-OWEXML] 2.2.5. WebExtensionReference.

Das folgende Beispiel zeigt, wie Sie den taskpane-Teil hinzufügen.

<wetp:taskpane dockstate="right" visibility="0" width="350" row="4" xmlns:wetp="http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11">
  <wetp:webextensionref xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" r:id="rId1" />
</wetp:taskpane>

Beachten Sie, dass in diesem Beispiel das Attribut visibility auf „0“ festgelegt ist. Dies bedeutet, dass nach dem Hinzufügen der Webextension- und taskpane-Teile der Benutzer beim ersten Öffnen des Dokuments das Add-In über die Schaltfläche Add-In auf dem Menüband installieren muss. Danach wird der Add-In-Aufgabenbereich automatisch geöffnet, wenn die Datei geöffnet wird. Wenn Sie visibility auf „0“ festlegen, können Sie außerdem „Office.js“ verwenden, um Benutzern zu ermöglichen, das AutoOpen-Feature zu aktivieren bzw. zu deaktivieren. Ihr Skript legt die Dokumenteinstellung Office.AutoShowTaskpaneWithDocument spezifisch auf true oder false fest. (Details finden Sie unter Markieren des Dokuments auf Seite des Clients.)

Ist visibility der Wert auf "1" gesetzt, wird der Aufgabenbereich beim ersten Öffnen des Dokuments automatisch geöffnet. Der Benutzer wird aufgefordert, dem Add-In zu vertrauen, und wenn die Vertrauensstellung gewährt wurde, wird das Add-In geöffnet. Danach wird der Add-In-Aufgabenbereich automatisch geöffnet, wenn die Datei geöffnet wird. Wenn visibility es jedoch auf "1" festgelegt ist, können Sie Office.js nicht verwenden, um Benutzern das Aktivieren oder Deaktivieren des AutoOpen-Features zu ermöglichen.

Es ist eine gute Wahl, visibility auf „1“ festzulegen, wenn das Add-In und die Vorlage oder der Inhalt des Dokuments so eng miteinander integriert sind, dass der Benutzer das AutoOpen-Feature nicht deaktivieren würde.

Eine einfache Möglichkeit zum Schreiben von XML besteht darin, zuerst Ihr Add-In auszuführen und das Dokument auf der Clientseite zu markieren , um den Wert zu schreiben, dann das Dokument zu speichern und den generierten XML-Code zu überprüfen. Office erkennt und stellt die entsprechenden Attributwerte bereit. Sie können auch das Open XML SDK-Produktivitätstool verwenden, um C#-Code zu generieren, um das Markup basierend auf dem von Ihnen generierten XML programmgesteuert hinzuzufügen.

Testen und überprüfen Aufgabenbereiche öffnen

Sie können eine Testversion Ihres Add-Ins bereitstellen, die mithilfe der zentralen Bereitstellung über das Microsoft 365 Admin Center automatisch einen Aufgabenbereich öffnet. Das folgende Beispiel zeigt, wie Add-Ins aus dem zentralen Bereitstellungs-Katalog mit der Version EXCatalog Store eingefügt werden.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="{52811C31-4593-43B8-A697-EB873422D156}">
    <we:reference id="af8fa5ba-4010-4bcc-9e03-a91ddadf6dd3" version="1.0.0.0" store="EXCatalog" storeType="EXCatalog"/>
    <we:alternateReferences/>
    <we:properties/>
    <we:bindings/>
    <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

Sie können das vorherige Beispiel testen, indem Sie Ihr Microsoft 365-Abonnement verwenden, um die zentrale Bereitstellung auszuprobieren und sicherzustellen, dass Ihr Add-In wie erwartet funktioniert. Wenn Sie noch nicht über ein Microsoft 365-Abonnement verfügen, qualifizieren Sie sich möglicherweise über das Microsoft 365 Developer Program für ein Microsoft 365 E5 Entwicklerabonnement; Details finden Sie in den FAQ. Alternativ können Sie sich für eine kostenlose 1-monatige Testversion registrieren oder einen Microsoft 365-Plan erwerben.

Siehe auch

• Ein Beispiel, das Ihnen zeigt, wie Sie das Feature autoopen verwenden, finden Sie unter Automatisches Öffnen eines Aufgabenbereichs mit einem Dokument.
• Automatisches Öffnen eines Aufgabenbereichs bei Installation eines Add-Ins
• Weitere Informationen zum Microsoft 365-Entwicklerprogramm
• Verwalten von Vertrauensstellungsoptionen für Office-Add-Ins