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 dem Menüband der Office-App Schaltflächen 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 Anforderungssatz AddInCommands 1.1 eingeführte Autoopen-Aufgabenbereichsfeature verwenden, um automatisch einen Aufgabenbereich zu öffnen, wenn es in Ihrem Szenario erforderlich ist.

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 in diesem Dokument beibehalten. Wenn andere Benutzer das Dokument öffnen, werden sie daher aufgefordert, das Add-In zu installieren, und der Aufgabenbereich wird geöffnet. Die Herausforderung bei diesem Modell besteht darin, dass Benutzer in vielen Fällen nicht möchten, dass das Add-In im Dokument beibehalten wird. Beispielsweise möchte ein Kursteilnehmer, 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 sie das Dokument öffnen.

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 das AutoOpen-Feature 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 stellen Sie ein Fallbackverhalten bereit, falls 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 mit bestimmten Dokumenten automatisch geöffnet wird, kann dieses Feature Benutzer verärren.

  Hinweis

  Wenn Microsoft einen Missbrauch des AutoOpen-Features erkennt, kann dies dazu führen, dass das Add-In nicht für AppSource zugelassen wird.

• 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 des Features "AutoOpen"

• 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

Zum Angeben des automatisch zu öffnenden Aufgabenbereichs legen Sie für den Wert TaskpaneId auf Office.AutoShowTaskpaneWithDocument fest. Sie können diesen Wert nur für einen Aufgabenbereich festlegen. Wenn Sie diesen Wert für mehrere Aufgabenbereiche festlegen, wird das erste Vorkommen des Werts erkannt, und die anderen werden ignoriert.

Das folgende Beispiel zeigt den Wert „TaskPaneId“, festgelegt auf „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 festzulegen true, 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 AppSource 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.)

Wenn visibility auf "1" festgelegt ist, 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 wird, wird das Add-In geöffnet. Danach wird der Add-In-Aufgabenbereich automatisch geöffnet, wenn die Datei geöffnet wird. Wenn visibility jedoch auf "1" festgelegt ist, können Sie Office.js nicht verwenden, um Benutzern das Aktivieren oder Deaktivieren der AutoOpen-Funktion 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 des XML-Codes besteht darin, zuerst das Add-In auszuführen und das Dokument auf der Clientseite zu markieren , um den Wert zu schreiben, und 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 Productivity Tool verwenden, um C#-Code zum programmgesteuerten Hinzufügen des Markups basierend auf dem von Ihnen generierten XML-Code zu generieren.

Testen und überprüfen Aufgabenbereiche öffnen

Sie können eine Testversion Ihres Add-Ins bereitstellen, die automatisch einen Aufgabenbereich mithilfe der zentralen Bereitstellung über die Microsoft 365 Admin Center ö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, können Sie sich über das Microsoft 365-Entwicklerprogramm für ein Microsoft 365 E5-Entwicklerabonnement qualifizieren. Weitere Informationen finden Sie in den häufig gestellten Fragen. Alternativ können Sie sich für eine kostenlose 1-monatige Testversion registrieren oder einen Microsoft 365-Plan erwerben.

Siehe auch

• Ein Beispiel, das zeigt, wie Sie das AutoOpen-Feature verwenden, finden Sie unter Automatisches Öffnen eines Aufgabenbereichs mit einem Dokument.
• Automatisches Öffnen eines Aufgabenbereichs bei der Installation eines Add-Ins
• Weitere Informationen zum Microsoft 365-Entwicklerprogramm