Freigeben über

Ausführen von Code in Ihrem Office-Add-In, wenn ein Dokument geöffnet wird

  • Artikel

Wichtig

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

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.

Hinweis

Die Konfiguration wird mit einer Methode implementiert, die Ihr 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 auf einem Beliebigen Dokument geöffnet werden. Nachdem die Methode ausgeführt wird, entweder in Office.initialize, Office.onReady, oder weil der Benutzer einen Codepfad verwendet, der sie ausführt; wenn das Dokument dann erneut geöffnet wird, wird das Add-In sofort geladen, und jeglicher Code in der - oder Office.onReady -Office.initializeMethode wird ausgeführt.

Hinweis

Dieser Artikel erfordert, 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 Runtime.

Konfigurieren Des Add-Ins zum Laden beim Öffnen des Dokuments

Der folgende Code konfiguriert Ihr Add-In so, dass es geladen und ausgeführt wird, wenn das Dokument geöffnet wird.

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

Hinweis

Die setStartupBehavior -Methode ist asynchron.

Platzieren von Startcode in Office.initialize oder Office.onReady

Wenn Ihr Add-In so konfiguriert ist, dass es beim öffnenden Dokument geladen wird, wird es sofort ausgeführt. Der Office.initialize Ereignishandler wird aufgerufen. Platzieren Sie Den Startcode im Office.initialize Ereignishandler oder Office.onReady .

Der folgende Excel-Add-In-Code zeigt, wie Sie einen Ereignishandler für Änderungsereignisse aus dem aktiven Arbeitsblatt registrieren. 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 Sie einen Ereignishandler für Auswahländerungsereignisse aus dem PowerPoint-Dokument registrieren. 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 Des Add-Ins für kein Ladeverhalten beim Öffnen des Dokuments

Es kann Szenarien geben, in denen Sie das Verhalten "Bei Dokument öffnen ausführen" deaktivieren möchten. Mit dem folgenden Code wird das Add-In so konfiguriert, dass es nicht gestartet wird, wenn das Dokument geöffnet wird. Stattdessen wird es gestartet, wenn der Benutzer es auf irgendeine Weise einschaltet, z. B. durch Auswählen einer Menübandschaltfläche oder Öffnen des Aufgabenbereichs. Dieser Code hat keine Auswirkung, wenn die Methode noch nicht für das aktuelle Dokument Office.StartupBehavior.load mit als Parameter aufgerufen wurde.

Hinweis

Wenn das Add-In die -Methode mit Office.StartupBehavior.load als Parameter in Office.initialize oder Office.onReadyaufruft, wird das Verhalten erneut aktiviert. Daher gilt das Deaktivieren in diesem Szenario 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();

Weitere Informationen