Dokument für die Ausführung von Code beim Öffnen konfigurieren

Sie können Ihr Office-Add-In so konfigurieren, dass Code geladen und ausgeführt wird, sobald das Dokument geöffnet wird. Dies ist nützlich, wenn Sie Ereignishandler registrieren, Daten für den Aufgabenbereich vorab laden, die Benutzeroberfläche synchronisieren oder andere Aufgaben ausführen müssen, bevor das Add-In sichtbar ist.

Tipp

In diesem Artikel wird ein Feature beschrieben, mit dem sich Add-Ins programmgesteuert selbst konfigurieren können, um beim Öffnen eines Dokuments Code auszuführen. Die Technik hat einen Dokumentenbereich, was bedeutet, dass sie auf jedes Dokument einzeln angewendet werden muss. Dieses Feature unterscheidet sich von drei ähnlichen Features:

  • Ein Add-In kann im Manifest zum Ausführen von Code beim Öffnen eines Dokuments konfiguriert werden. Dieses Feature hat Office-Anwendungsbereich. Nachdem ein Add-In von einem Microsoft 365-Administrator im Admin-Portal des Microsoft 365-Mandanten installiert wurde, startet das Add-In Code für jedes Office-Dokument, das in den Office-Anwendungen geöffnet wird, für die das Add-In im Manifest konfiguriert ist, und führt Code aus. Weitere Informationen finden Sie unter Aktivieren von Add-Ins mit Ereignissen, insbesondere die Informationen zum OnDocumentOpened Ereignis.
  • Ein Add-In kann ein Dokument programmgesteuert so konfigurieren, dass der Aufgabenbereich des Add-Ins automatisch geöffnet wird, wenn das Dokument geöffnet wird. Dieses Feature muss auch auf jedes Dokument einzeln angewendet werden. Weitere Informationen finden Sie unter Automatisches Öffnen eines Aufgabenbereichs mit einem Dokument.
  • Ein Add-In kann im Manifest so konfiguriert werden, dass sein Aufgabenbereich geöffnet wird, wenn das Add-In von einem Endbenutzer installiert wird. Dieses Feature ist auf ein einzelnes Dokument beschränkt: das Dokument, das bei der Installation des Add-Ins geöffnet ist. Weitere Informationen finden Sie unter Automatisches Öffnen eines Aufgabenbereichs bei Installation eines Add-Ins.

Die Konfiguration wird mit einer Methode implementiert, die der Code zur Laufzeit aufruft. Dies bedeutet, dass das Add-In nicht ausgeführt wird , wenn ein Benutzer das Dokument zum ersten Mal öffnet. Das Add-In muss zum ersten Mal manuell in einem beliebigen Dokument geöffnet werden. Nachdem die Methode ausgeführt wurde, entweder in Office.initialize, Office.onReady, oder weil der Benutzer einen Codepfad nimmt, der sie ausführt; Wenn das Dokument dann erneut geöffnet wird, wird das Add-In sofort geladen, und der Code in der Office.initializeOffice.onReady OR-Methode wird ausgeführt.

Hinweis

Für diesen Artikel ist es erforderlich, dass Ihr Office-Add-In für die Verwendung einer freigegebenen Runtime konfiguriert ist. Weitere Informationen finden Sie unter Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Laufzeit.

Wichtig

Die gemeinsame Laufzeit wird nur in einigen Office-Anwendungen unterstützt. Weitere Informationen finden Sie unter Gemeinsame Laufzeitanforderungsgruppen.

Konfigurieren Sie Ihr Add-In so, dass es beim Öffnen des Dokuments geladen wird

Der folgende Code konfiguriert Ihr Add-In so, dass es beim Öffnen des Dokuments geladen und ausgeführt wird.

Office.addin.setStartupBehavior(Office.StartupBehavior.load);

Hinweis

Die setStartupBehavior Methode ist asynchron.

Startcode in Office.initialize oder Office.onReady platzieren

Wenn Ihr Add-In so konfiguriert ist, dass es beim Öffnen des Dokuments geladen wird, wird es sofort ausgeführt. Der Office.initialize Ereignishandler wird aufgerufen. Platzieren Sie Ihren Startcode im Office.initialize Ereignishandler oder Office.onReady .

Der folgende Excel-Add-In-Code zeigt, wie ein Ereignishandler für Änderungsereignisse aus dem aktiven Arbeitsblatt registriert wird. Wenn Sie Ihr Add-In so konfigurieren, dass es beim Öffnen des Dokuments geladen wird, registriert dieser Code den Ereignishandler, wenn das Dokument geöffnet wird. Sie können Änderungsereignisse behandeln, bevor der Aufgabenbereich geöffnet wird.

// This is called as soon as the document opens.
// Put your startup code here.
Office.initialize = () => {
  // Add the event handler.
  Excel.run(async context => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onChanged.add(onChange);

    await context.sync();
    console.log("A handler has been registered for the onChanged event.");
  });
};

/**
 * Handle the changed event from the worksheet.
 *
 * @param event The event information from Excel
 */
async function onChange(event) {
    await Excel.run(async (context) => {    
        await context.sync();
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);
  });
}

Der folgende PowerPoint-Add-In-Code zeigt, wie ein Ereignishandler für Auswahländerungsereignisse aus dem PowerPoint-Dokument registriert wird. Wenn Sie Ihr Add-In so konfigurieren, dass es beim Öffnen des Dokuments geladen wird, registriert dieser Code den Ereignishandler, wenn das Dokument geöffnet wird. Sie können Änderungsereignisse behandeln, bevor der Aufgabenbereich geöffnet wird.

// This is called as soon as the document opens.
// Put your startup code here.
Office.onReady(info => {
  if (info.host === Office.HostType.PowerPoint) {
    Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, onChange);
    console.log("A handler has been registered for the onChanged event.");
  }
});

/**
 * Handle the changed event from the PowerPoint document.
 *
 * @param event The event information from PowerPoint
 */
async function onChange(event) {
  console.log("Change type of event: " + event.type);
}

Konfigurieren Sie Ihr Add-In für das Verhalten ohne Laden beim Öffnen des Dokuments

Es kann Szenarien geben, in denen Sie das Verhalten "Beim Öffnen des Dokuments ausführen" deaktivieren möchten. Der folgende Code konfiguriert Ihr Add-In so, dass es nicht gestartet wird, wenn das Dokument geöffnet wird. Stattdessen wird sie gestartet, wenn der Benutzer sie in irgendeiner Weise aktiviert, z. B. durch Auswählen einer Menübandschaltfläche oder Öffnen des Aufgabenbereichs. Dieser Code hat keine Auswirkungen, Office.StartupBehavior.load wenn die Methode nicht zuvor für das aktuelle Dokument mit als Parameter aufgerufen wurde.

Hinweis

Wenn das Add-In die Methode aufruft Office.StartupBehavior.load , mit als Parameter in Office.initialize or Office.onReady, wird das Verhalten wieder aktiviert. In diesem Szenario gilt das Deaktivieren also nur für das nächste Öffnen des Dokuments, nicht für alle nachfolgenden Öffnungen.

Office.addin.setStartupBehavior(Office.StartupBehavior.none);

Abrufen des aktuellen Ladeverhaltens

Es kann Szenarien geben, in denen Ihr Add-In wissen muss, ob es so konfiguriert ist, dass es beim nächsten Öffnen des aktuellen Dokuments automatisch gestartet wird. Um das aktuelle Startverhalten zu bestimmen, führen Sie die folgende Methode aus, die einen Office.StartupBehavior-Wert zurückgibt.

let behavior = await Office.addin.getStartupBehavior();

Siehe auch

  • Last updated on