Freigeben über

Erstellen eines Office-Add-Ins mit einer einfachen Ersten Ausführung

Die Implementierung einer Ersten Ausführung hilft beim Onboarding von Benutzern und hebt den Wert Ihres Add-Ins hervor. Dieses Tutorial führt Sie durch das Hinzufügen einer einfachen Ersten Ausführung zu Ihrem Office-Add-In mithilfe des lokalen Speichers, um nachzuverfolgen, ob der Benutzer das Add-In zuvor gestartet hat.

Hinweis

Die Erste Ausführung ist ein empfohlenes Muster für Office-Add-Ins. Es hilft Benutzern, die Features Ihres Add-Ins zu verstehen, und erhöht die Interaktion.

Was Sie lernen

  • Hier erfahren Sie, wie Sie Ihrem Add-In eine Benutzeroberfläche für die erste Ausführung hinzufügen.
  • Verwenden des lokalen Browserspeichers zum Beibehalten des Benutzerzustands
  • Hier erfahren Sie, wie Sie die HTML-, JavaScript- und CSS-Dateien Ihres Add-Ins aktualisieren, um die Benutzeroberfläche für die erste Ausführung zu unterstützen.

Übersicht

Wenn ein Benutzer Ihr Add-In zum ersten Mal öffnet, werden eine Begrüßungsnachricht und eine Liste der wichtigsten Features angezeigt. Bei nachfolgenden Starts überspringt das Add-In die Willkommensseite und zeigt die Hauptbenutzeroberfläche an. Dies wird erreicht, indem Sie im lokalen Speicher nach einem Flag suchen und die Benutzeroberfläche entsprechend aktualisieren.

Dieses Tutorial enthält Anweisungen und Screenshots für Excel, aber Sie können ein ähnliches Muster verwenden, um eine Erstausführung in anderen Office-Anwendungen zu implementieren, in denen Office Web-Add-Ins unterstützt werden.

Schritte

Führen Sie die folgenden Schritte aus, um die Erste Ausführung zu implementieren:

  1. Aktualisieren des HTML-Codes: Fügen Sie einen Container für die erste Ausführung hinzu.
  2. JavaScript aktualisieren: Überprüfen Sie den lokalen Speicher, und zeigen Sie bei Bedarf die Benutzeroberfläche für die erste Ausführung an.
  3. Aktualisieren des CSS: Stellen Sie sicher, dass die neue Benutzeroberfläche konsistent formatiert ist.
  4. Testen Des Add-Ins: Überprüfen Sie, ob die Erste Ausführung wie erwartet funktioniert.

Los geht's!

Tipp

Wenn Sie eine vollständige Version dieses Tutorials benötigen, besuchen Sie das Repository mit Den Office-Add-Ins-Beispielen auf GitHub.

Voraussetzungen

  1. Wählen Sie den Yo Office-Schnellstart für die Office-Anwendung aus, die Sie verwenden möchten.

  2. Befolgen Sie die Anweisungen im ausgewählten Schnellstart. Nachdem Sie den Abschnitt "Ausprobieren" abgeschlossen haben, kehren Sie hierher zurück, um fortzufahren.

Implementieren der Ersten Ausführung

Aktualisieren der HTML-Datei

Informieren Sie sich über den Bereich der Benutzeroberfläche, der Teil der Ersten Ausführung sein wird. In diesem Tutorial erstellen Sie ein <div> Element mit dem id Namen "first-run-experience", das darstellt, was Benutzern nur bei der ersten Ausführung Ihres Add-Ins angezeigt wird.

  1. Öffnen Sie die taskpane.html. Ersetzen Sie das <main> -Element durch das folgende Markup, und speichern Sie dann die Datei. Einige Hinweise zu diesem Markup:

    • Die "First-Run-Experience" <div> wird in das <main> -Element eingefügt. Sie umschließt die Liste der Office-Add-Ins-Features. Dies <div> wird standardmäßig nicht angezeigt.
    • Das erste <p> Element stellt dem Benutzer Anweisungen zur Verwendung des Add-Ins bereit.
    <main id="app-body" class="ms-welcome__main" style="display: none;">
    <div id="first-run-experience" style="display: none;">
        <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
        <ul class="ms-List ms-welcome__features">
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
                <span class="ms-font-m">Achieve more with Office integration</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Unlock ms-font-xl"></i>
                <span class="ms-font-m">Unlock features and functionality</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Design ms-font-xl"></i>
                <span class="ms-font-m">Create and visualize like a pro</span>
            </li>
        </ul>
    </div>
    <p class="ms-font-l">Select any range of cells in the worksheet, then click <b>Run</b>.</p>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
    <p><label id="item-subject"></label></p>    
</main>

  2. Wenn Sie eine Office-Anwendung neben Excel ausgewählt haben, aktualisieren Sie das erste <p> Element mit geeigneteren Anweisungen.

Aktualisieren der JavaScript-Datei

Aktualisieren Sie die JavaScript-Datei, um die Erste Ausführung anzuzeigen, wenn der Benutzer das Add-In zum ersten Mal ausführt.

  1. Öffnen Sie die taskpane.js Datei. Ersetzen Sie die Office.onReady -Anweisung durch den folgenden Code, und speichern Sie dann die Datei. Einige Hinweise zu diesem Code:

    • Es überprüft den lokalen Speicher auf einen Schlüssel namens "showedFRE". Wenn der Schlüssel nicht vorhanden ist, zeigen Sie die Erste Ausführung an.
    • Es fügt eine neue Funktion namens showFirstRunExperience hinzu, die die "First-Run-Experience" <div> anzeigt, die dem HTML hinzugefügt wurde. Diese Funktion fügt auch das Element "showedFRE" zum lokalen Speicher hinzu.
    Office.onReady((info) => {
  if (info.host === Office.HostType.Excel) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";

    // showedFRE is created and set to "true" when you call showFirstRunExperience().
    if (!localStorage.getItem("showedFRE")) {
      showFirstRunExperience();
    }

    document.getElementById("run").onclick = run;
  }
});

async function showFirstRunExperience() {
  document.getElementById("first-run-experience").style.display = "flex";
  localStorage.setItem("showedFRE", true);
}

  2. Wenn Sie eine Office-Anwendung neben Excel ausgewählt haben, aktualisieren Sie die Bedingung der ersten if Anweisung, um nach ihrem ausgewählten Office.HostType zu suchen.

Aktualisieren der CSS-Datei

Aktualisieren Sie die CSS-Datei, um sicherzustellen, dass die Add-In-Benutzeroberfläche entsprechend formatiert ist, wenn die "First-Run-Experience" <div>hinzugefügt wurde.

  • Öffnen Sie die datei taskpane.css . Ersetzen Sie die Zeile .ms-welcome__main { durch den folgenden Code, und speichern Sie dann die Datei.

    .ms-welcome__main, .ms-welcome__main > div {

Probieren Sie es aus

  1. Stellen Sie sicher, dass der Webserver ausgeführt wird und das Add-In quergeladen wurde, und öffnen Sie dann den Aufgabenbereich. Weitere Informationen finden Sie in den Anweisungen in der verwendeten Schnellstartanleitung.

  2. Vergewissern Sie sich, dass der Aufgabenbereich die Liste der Features enthält.

    Die Benutzeroberfläche des Add-In-Aufgabenbereichs bei der ersten Ausführung.

  3. Schließen Sie den Aufgabenbereich, und öffnen Sie ihn dann erneut. Stellen Sie sicher, dass im Aufgabenbereich die Liste der Features nicht mehr angezeigt wird.

    Die Benutzeroberfläche des Add-In-Aufgabenbereichs bei der zweiten Ausführung.

Nächste Schritte

Herzlichen Glückwunsch, Sie haben erfolgreich ein Office-Aufgabenbereich-Add-In mit einer ersten Ausführung erstellt!

Produktionsbereit machen

In diesem Tutorial haben Sie eine grundlegende Benutzeroberfläche für die erste Ausführung implementiert. Damit die Erste Ausführung für Benutzer bereit ist, sollten Sie Folgendes berücksichtigen:

  • Aktualisieren Sie die in der Wertplatzmatte aufgeführten Features so, dass sie den tatsächlichen Funktionen Ihres Add-Ins entsprechen.
  • Implementieren Sie ein anderes Muster (z. B. Videoplatzmaten oder Karussell), das die Vorteile Ihres Add-Ins besser veranschaulicht.
  • Verwenden Sie eine sicherere und robustere Option zum Nachverfolgen des Status der ersten Ausführung. Verwenden Sie z. B. Speicherpartitionierung, falls verfügbar, oder implementieren Sie eine Authentifizierungslösung für einmaliges Anmelden (Single Sign-On, SSO).

Wenn Sie planen, Ihr Add-In im Microsoft Marketplace verfügbar zu machen, benötigen Sie eine stabile und nützliche Benutzeroberfläche für die erste Ausführung. Weitere Informationen finden Sie unter Bewährte Methoden für die Entwicklung von Office-Add-Ins.

Codebeispiele

Siehe auch

  • Last updated on