Übung – Arbeiten mit Dialogfeldern in Excel

  • 11 Minuten

Dialogfelder von Office-Add-Ins sind nicht modal. Das bedeutet, der Benutzer kann weiterhin sowohl mit dem Dokument in der Office-Hostanwendung als auch mit der Hostseite im Aufgabenbereich interagieren.

In dieser Übung öffnen Sie ein Dialogfeld in Ihrem Add-In, übergeben eine Nachricht aus dem Dialogprozess an den Aufgabenbereichprozess und schließen das Dialogfeld.

Erstellen der Dialogseite

  1. Erstellen Sie im Ordner ./src, der sich im Stammverzeichnis des Projekts befindet, einen Ordner mit dem Namen Dialogfelder.

  2. Erstellen Sie im Ordner ./src/dialogs eine neue Datei mit dem Namen popup.html.

  3. Fügen Sie das folgende Markup zu popup.html hinzu. Hinweis:

    • Die Seite enthält einen <input>, in den der Benutzer seinen Namen eingibt, sowie eine Schaltfläche, die den Namen an die Seite im Aufgabenbereich sendet, auf der er angezeigt wird.
    • Das Markup lädt ein Skript namens popup.js, das Sie in einem späteren Schritt erstellen werden.
    • Es lädt auch die Office.JS-Bibliothek, da diese in popup.js verwendet wird.
    <!DOCTYPE html>
<html>
  <head lang="en">
    <title>Dialog for My Office Add-in</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- For more information on Office UI Fabric, visit https://developer.microsoft.com/fabric. -->
    <link rel="stylesheet" href="https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/9.6.1/css/fabric.min.css"/>

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
    <script type="text/javascript" src="popup.js"></script>
  </head>
  <body style="display:flex;flex-direction:column;align-items:center;justify-content:center">
    <p class="ms-font-xl">ENTER YOUR NAME</p>
    <input id="name-box" type="text"/><br/><br/>
    <button id="ok-button" class="ms-Button">OK</button>
  </body>
</html>

  4. Erstellen Sie im Ordner ./src/dialogs eine neue Datei mit dem Namen popup.js.

  5. Fügen Sie den folgenden Code zu popup.js hinzu:

    (async () => {
  await Office.onReady();

  // TODO1: Assign handler to the OK button.

  // TODO2: Create the OK button handler
})();

    Hinweis

    • Jede Seite, die in der Bibliothek Office.js APIs aufruft, muss zuerst überprüfen, dass die Bibliothek vollständig initialisiert ist. Die beste Möglichkeit ist mit der Methode Office.onReady(). Wenn das Add-In über seine eigenen Initialisierungsaufgaben verfügt, sollte sich der Code in einer then()-Methode befinden, die mit einem Aufruf von Office.onReady() verkettet ist. Der Aufruf von Office.onReady() muss vor allen Aufrufen von Office.js ausgeführt werden. Die Zuweisung befindet sich daher in einer Skriptdatei, die von der Seite geladen wird, wie dies hier der Fall ist.

  6. Ersetzen Sie TODO1 durch den folgenden Code. Die sendStringToParentPage()-Methode wird im nächsten Schritt erstellt.

    document.getElementById("ok-button").onclick = sendStringToParentPage;

  7. Ersetzen Sie TODO2 durch den folgenden Code. Die messageParent()-Methode übergibt ihre Parameter an die übergeordnete Seite, in diesem Fall die Seite im Aufgabenbereich. Der Parameter kann ein boolescher Wert oder eine Zeichenfolge sein, die alles umfasst, was als Zeichenfolge serialisiert werden kann, z. B. XML oder JSON.

    function sendStringToParentPage() {
  const userName = document.getElementById("name-box").value;
  Office.context.ui.messageParent(userName);
}

Hinweis

Die Datei popup.html und die Datei popup.js, die geladen wird, werden in einem vollständig separaten Microsoft Edge oder Internet Explorer 11-Prozess des Add-In-Aufgabenbereichs ausgeführt. Würde die Datei popup.js in derselben bundle.js-Datei wie die app.js-Datei transpiliert, müsste das Add-In zwei Kopien der Datei bundle.js laden, was den Vorteil des Bündelns zunichte macht. Aus diesem Grund wird die Datei popup.js überhaupt nicht von dem Add-In transpiliert.

Aktualisieren der Webpack-Konfigurationseinstellungen

Öffnen Sie die Datei webpack.config.js im Stammverzeichnis des Projekts, und führen Sie die folgenden Schritte aus.

  1. Suchen Sie das entry-Objekt innerhalb des config-Objekts, und fügen Sie einen neuen Eintrag für popup hinzu.

    popup: "./src/dialogs/popup.js"

    Danach sieht das neue entry-Objekt folgendermaßen aus:

    entry: {
  polyfill: "@babel/polyfill",
  taskpane: "./src/taskpane/taskpane.js",
  commands: "./src/commands/commands.js",
  popup: "./src/dialogs/popup.js"
},

  2. Suchen Sie das plugins-Array innerhalb des config-Objekts und fügen Sie das folgende Objekt am Ende dieses Arrays hinzu.

    new HtmlWebpackPlugin({
  filename: "popup.html",
  template: "./src/dialogs/popup.html",
  chunks: ["polyfill", "popup"]
})

    Danach sieht das neue plugins-Array folgendermaßen aus:

    plugins: [
  new HtmlWebpackPlugin({
    filename: "taskpane.html",
    template: "./src/taskpane/taskpane.html",
    chunks: ["polyfill", "taskpane"],
  }),
  new CopyWebpackPlugin({
    patterns: [
      {
        from: "assets/*",
        to: "assets/[name][ext][query]",
      },
      {
        from: "manifest*.xml",
        to: "[name]." + buildType + "[ext]",
        transform(content) {
          if (dev) {
            return content;
          } else {
            return content.toString().replace(new RegExp(urlDev, "g"), urlProd);
          }
        },
      },
    ],
  }),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"],
  }),
  new HtmlWebpackPlugin({
    filename: "popup.html",
    template: "./src/dialogs/popup.html",
    chunks: ["polyfill", "popup"]
  })
],

  3. Wenn der lokale Webserver ausgeführt wird, beenden Sie ihn, indem Sie den folgenden Befehl in der Eingabeaufforderung eingeben.

    npm stop

  4. Führen Sie den folgenden Befehl aus, um das Projekt erneut zu erstellen.

    npm run build

Öffnen des Dialogfelds aus dem Aufgabenbereich

  1. Öffnen Sie die Datei ./src/taskpane/taskpane.html.

  2. Suchen Sie das <button>-Element für die Schaltfläche freeze-header, und fügen Sie nach dieser Zeile das folgende Markup hinzu:

    <button class="ms-Button" id="open-dialog">Open Dialog</button><br/><br/>

  3. Das Dialogfeld fordert den Benutzer auf, einen Namen einzugeben, und den Benutzernamen an den Aufgabenbereich zu übergeben. Der Aufgabenbereich zeigt diesen in einer Bezeichnung an. Fügen Sie das folgende Markup unmittelbar nach dem button hinzu, den Sie gerade hinzugefügt haben:

    <label id="user-name"></label><br/><br/>

  4. Öffnen Sie die Datei ./src/taskpane/taskpane.js.

  5. Suchen Sie im Office.onReady()-Methodenaufruf die folgende Zeile:

    document.getElementById("freeze-header").onclick = freezeHeader;

    Fügen Sie unmittelbar nach der Zeile den folgenden Code hinzu:

    document.getElementById("open-dialog").onclick = openDialog;

  6. Fügen Sie die folgende Deklaration am Ende der Datei hinzu. Diese Variable wird verwendet, um ein Objekt im Ausführungskontext der übergeordneten Seite zu halten, die als Vermittler zum Ausführungskontext der Dialogseite dient.

    let dialog = null;

  7. Fügen Sie die folgende Funktion am Ende der Datei hinzu (nach der Deklaration von dialog). Das Wichtige an diesem Code ist, was nicht vorhanden ist: kein Aufruf von Excel.run(). Das liegt daran, dass die API zum Öffnen eines Dialogs von allen Office-Hosts gemeinsam verwendet wird. Sie ist also Teil der Office JavaScript Common-API und nicht der Excel-spezifischen API.

    function openDialog() {
  // TODO1: Call the Office Common API that opens a dialog
}

  8. Ersetzen Sie TODO1 durch den folgenden Code:

    Office.context.ui.displayDialogAsync(
  'https://localhost:3000/popup.html',
  {height: 45, width: 55},

  // TODO2: Add callback parameter.
);

    Hinweis

    • Durch die displayDialogAsync()-Methode wird in der Mitte des Bildschirms ein Dialogfeld geöffnet.
    • Der erste Parameter ist die URL der zu öffnenden Seite.
    • Der zweite Parameter übergibt Optionen. height und width sind Prozentsätze für die Größe des Office-Anwendungsfensters.

Verarbeiten der Nachricht aus dem Dialogfeld und Schließen des Dialogfelds

  1. Ersetzen Sie in der openDialog()-Funktion der Datei ./src/taskpane/taskpane.jsTODO2 mit dem folgenden Code:

    function (result) {
  dialog = result.value;
  dialog.addEventHandler(Microsoft.Office.WebExtension.EventType.DialogMessageReceived, processMessage);
}

    Hinweis

    • Der Rückruf wird unmittelbar ausgeführt, nachdem das Dialogfeld erfolgreich geöffnet wurde und bevor der Benutzer eine Aktion im Dialogfeld ausgeführt hat.
    • result.value ist das Objekt, das als Zwischenstation zwischen den Ausführungskontexten der übergeordneten Seite und der Dialogseite fungiert.
    • Die processMessage()-Funktion wird in einem späteren Schritt erstellt. Dieser Handler verarbeitet alle Werte, die von der Dialogseite mit Aufrufen der messageParent()- -Funktion gesendet werden.

  2. Fügen Sie die folgende Funktion nach der Funktion openDialog() hinzu.

    function processMessage(arg) {
  document.getElementById("user-name").innerHTML = arg.message;
  dialog.close();
}

  3. Vergewissern Sie sich, dass Sie alle am Projekt vorgenommen Änderungen gespeichert haben.

Testen des Add-Ins

  1. Wenn der lokale Webserver bereits läuft und Ihr Add-In bereits in Excel geladen ist, fahren Sie mit Schritt 2 fort. Starten Sie andernfalls den lokalen Webserver, und laden Sie das Add-In quer:

    • Führen Sie zum Testen Ihres Add-Ins in Excel den folgenden Befehl im Stammverzeichnis Ihres Projekts aus. Damit wird der lokale Webserver gestartet (sofern er noch nicht ausgeführt wird), Excel wird geöffnet, und das Add-In wird in Excel geladen.

      npm start

    • Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus, um Ihr Add-In in Excel im Web zu testen. Wenn Sie diesen Befehl ausführen, wird der lokale Webserver gestartet (sofern er nicht bereits ausgeführt wird).

      npm run start:web

      Um das Add-In zu verwenden, öffnen Sie ein neues Dokument in Excel im Web, und laden Sie dann das Add-In quer, indem Sie den Anweisungen in Querladen von Office-Add-ins in Office im Web folgen.

  2. Um den Add-In-Aufgabenbereich zu öffnen, wählen Sie auf der Registerkarte StartseiteAufgabenbereich anzeigen aus.

  3. Wählen Sie Dialog öffnen aus.

  4. Ziehen Sie das Dialogfeld, und ändern Sie seine Größe, solange es geöffnet ist. Sie können mit dem Arbeitsblatt interagieren und andere Schaltflächen im Aufgabenbereich drücken. Sie können jedoch über dieselbe Seite des Aufgabebereichs kein zweites Dialogfeld starten.

  5. Geben Sie im Dialogfeld einen Namen ein und wählen Sie OK aus. Der Name wird im Aufgabenbereich angezeigt, und das Dialogfeld wird geschlossen.

  6. Optional können Sie in der processMessage-Funktion // vor der Zeile dialog.close(); hinzufügen. Wiederholen Sie dann die Schritte in diesem Abschnitt. Das Dialogfeld bleibt geöffnet, und Sie können den Namen ändern. Sie können es manuell schließen, indem Sie auf die Schaltfläche X in der oberen rechten Ecke klicken.

Screenshot des Dialogfelds, das vom Tutorial in Excel hinzugefügt wurde.

Zusammenfassung

In dieser Übung haben Sie ein Dialogfeld in Ihrem Add-In geöffnet, eine Nachricht aus dem Dialogprozess an den Aufgabenbereichprozess übergeben und das Dialogfeld geschlossen.

Testen Sie Ihr Wissen

1.

Wie kann ein Office-Add-In ein Dialogfeld aus Microsoft Excel öffnen?

2.

Office-Add-Ins können auf welche der folgenden Arten auf Werte aus dem Dialog zugreifen?