Abrufen des gesamten Dokuments aus einem Add-In für PowerPoint oder WordGet the whole document from an add-in for PowerPoint or Word

Sie können ein Office-Add-In erstellen, um das Senden oder Veröffentlichen eines Word 2013- oder PowerPoint 2013-Dokuments an einen Remotespeicherort per Mausklick zu ermöglichen. In diesem Artikel wird veranschaulicht, wie Sie ein einfaches Aufgabenbereich-Add-In für PowerPoint 2013 erstellen, mit dem die gesamte Präsentation als Datenobjekt abgerufen wird und diese Daten per HTTP-Anforderung an einen Webserver gesendet werden.You can create an Office Add-in to provide one-click sending or publishing of a Word 2013 or PowerPoint 2013 document to a remote location. This article demonstrates how to build a simple task pane add-in for PowerPoint 2013 that gets all of the presentation as a data object and sends that data to a web server via an HTTP request.

Voraussetzungen für das Erstellen eines Add-ins für PowerPoint oder WordPrerequisites for creating an add-in for PowerPoint or Word

In diesem Artikel wird angenommen, dass Sie zum Erstellen des Aufgabenbereich-Add-ins für PowerPoint oder Word einen Text-Editor verwenden. Dafür müssen Sie die folgenden Dateien erstellen:This article assumes that you are using a text editor to create the task pane add-in for PowerPoint or Word. To create the task pane add-in, you must create the following files:

  • Auf einem freigegebenen Netzwerkordner bzw. auf einem Webserver benötigen Sie die folgenden Dateien:On a shared network folder or on a web server, you need the following files:

    • An HTML file (GetDoc_App.html) that contains the user interface plus links to the JavaScript files (including office.js and host-specific .js files) and Cascading Style Sheet (CSS) files.An HTML file (GetDoc_App.html) that contains the user interface plus links to the JavaScript files (including office.js and host-specific .js files) and Cascading Style Sheet (CSS) files.

    • Eine JavaScript-Datei (GetDoc_App.js) für die Programmierlogik des Add-insA JavaScript file (GetDoc_App.js) to contain the programming logic of the add-in.

    • Eine CSS-Datei (Program.css) für die Formatvorlagen und die Formatierung des Add-insA CSS file (Program.css) to contain the styles and formatting for the add-in.

  • Eine XML-Manifestdatei (GetDoc_App.xml) für das Add-in, die auf einem freigegebenen Netzwerkordner oder in einem Add-in-Katalog verfügbar ist. Die Manifestdatei muss auf den Speicherort der oben erwähnten HTML-Datei verweisen.An XML manifest file (GetDoc_App.xml) for the add-in, available on a shared network folder or add-in catalog. The manifest file must point to the location of the HTML file mentioned previously.

Sie können auch ein Add-in für PowerPoint erstellen, indem Sie Visual Studio oder den Generator für Office-Add-ins oder für Word verwenden, indem Sie Visual Studio oder den Generator für Office-Add-insverwenden.You can also create an add-in for PowerPoint by using Visual Studio or the Yeoman generator for Office Add-ins or for Word by using Visual Studio or Yeoman generator for Office Add-ins.

Wichtige Begriffe für die Erstellung eines Aufgabenbereich-Add-insCore concepts to know for creating a task pane add-in

Bevor Sie mit dem Erstellen dieses Add-Ins für PowerPoint oder Word beginnen, sollten Sie sich mit der Erstellung von Office-Add-Ins und der Verwendung von HTTP-Anforderungen vertraut gemacht haben. In diesem Artikel wird nicht beschrieben, wie Sie Base64-codierten Text aus einer HTTP-Anforderung auf einem Webserver decodieren.Before you begin creating this add-in for PowerPoint or Word, you should be familiar with building Office Add-ins and working with HTTP requests. This article does not discuss how to decode Base64-encoded text from an HTTP request on a web server.

Erstellen des Manifests für das Add-inCreate the manifest for the add-in

Mit der XML-Manifestdatei für das Add-In für PowerPoint werden wichtige Informationen zum Add-In bereitgestellt: welche Anwendungen es hosten kann, der Speicherort der HTML-Datei, der Add-In-Titel und die Add-In-Beschreibung sowie viele weitere Merkmale.The XML manifest file for the add-in for PowerPoint provides important information about the add-in: what applications can host it, the location of the HTML file, the add-in title and description, and many other characteristics.

  1. Fügen Sie der Manifestdatei im Texteditor den folgenden Code hinzu.In a text editor, add the following code to the manifest file.

    <?xml version="1.0" encoding="utf-8" ?>
    <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="TaskPaneApp">
        <Id>[Replace_With_Your_GUID]</Id>
        <Version>1.0</Version>
        <ProviderName>[Provider Name]</ProviderName>
        <DefaultLocale>EN-US</DefaultLocale>
        <DisplayName DefaultValue="Get Doc add-in" />
        <Description DefaultValue="My get PowerPoint or Word document add-in." />
        <IconUrl DefaultValue="http://officeimg.vo.msecnd.net/_layouts/images/general/office_logo.jpg" />
        <SupportUrl DefaultValue="[Insert the URL of a page that provides support information for the app]" />
        <Hosts>
        <Host Name="Document" />
        <Host Name="Presentation" />
        </Hosts>
        <DefaultSettings>
        <SourceLocation DefaultValue="[Network location of app]/GetDoc_App.html" />
        </DefaultSettings>
        <Permissions>ReadWriteDocument</Permissions>
    </OfficeApp>
    
  2. Speichern Sie die Datei unter dem Namen „GetDoc_App.xml“ und mit UTF-8-Codierung an einem Netzwerkspeicherort oder in einem Add-In-Katalog.Save the file as GetDoc_App.xml using UTF-8 encoding to a network location or to an add-in catalog.

Erstellen der Benutzeroberfläche für das Add-inCreate the user interface for the add-in

Für die Benutzeroberfläche des Add-ins können Sie HTML-Daten verwenden, die direkt in die Datei "GetDoc_App.html" geschrieben werden. Die Programmierlogik und die Funktionen des Add-ins müssen in einer JavaScript-Datei (z. B. "GetDoc_Apps.js") enthalten sein.For the user interface of the add-in, you can use HTML, written directly into the GetDoc_App.html file. The programming logic and functionality of the add-in must be contained in a JavaScript file (for example, GetDoc_App.js).

Verwenden Sie das folgende Verfahren, um eine einfache Benutzeroberfläche für das Add-in zu erstellen, die eine Überschrift und eine einzelne Schaltfläche umfasst.Use the following procedure to create a simple user interface for the add-in that includes a heading and a single button.

  1. Fügen Sie in einer neuen Datei im Texteditor die folgenden HTML-Daten hinzu.In a new file in the text editor, add the following HTML.

    <!DOCTYPE html>
    <html>
        <head>
            <meta charset="UTF-8" />
            <meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
            <title>Publish presentation</title>
            <link rel="stylesheet" type="text/css" href="Program.css" />
            <script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-1.9.0.min.js" type="text/javascript"></script>
            <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
            <script src="GetDoc_App.js"></script>
        </head>
        <body>
        <form>
            <h1>Publish presentation</h1>
            <br />
            <div><input id='submit' type="button" value="Submit" /></div>
            <br />
            <div><h2>Status</h2> 
                <div id="status"></div>
            </div>
        </form>
        </body>
    </html>
    
  2. Speichern Sie die Datei unter dem Namen "GetDoc_App.html" und mit UTF-8-Codierung an einem Netzwerkspeicherort oder auf einem Webserver.Save the file as GetDoc_App.html using UTF-8 encoding to a network location or to a web server.

    Hinweis

    Achten Sie darauf, dass die head-Tags des Add-Ins gültige Links zur Datei script enthalten.Be sure that the head tags of the add-in contains a script tag with a valid link to the office.js file.

    Hier werden Cascading Stylesheets verwendet, um dem Add-in ein einfaches und gleichzeitig modernes und professionelles Aussehen zu verleihen. Verwenden Sie die folgenden CSS-Daten, um das Format des Add-ins zu definieren.We'll use some CSS to give the add-in a simple, yet modern and professional appearance. Use the following CSS to define the style of the add-in.

  3. Fügen Sie in einer neuen Datei im Texteditor die folgenden CSS-Daten hinzu.In a new file in the text editor, add the following CSS.

    body
    {
        font-family: "Segoe UI Light","Segoe UI",Tahoma,sans-serif;
    }
    h1,h2
    {
        text-decoration-color:#4ec724;
    }
    input [type="submit"], input[type="button"]
    {
        height:24px;
        padding-left:1em;
        padding-right:1em;
        background-color:white;
        border:1px solid grey;
        border-color: #dedfe0 #b9b9b9 #b9b9b9 #dedfe0;
        cursor:pointer;
    }
    
  4. Speichern Sie die Datei unter dem Namen "Program.css" mit UTF-8-Codierung am Netzwerkspeicherort bzw. auf dem Webserver, auf dem sich die Datei "GetDoc_App.html" befindet.Save the file as Program.css using UTF-8 encoding to the network location or to the web server where the GetDoc_App.html file is located.

Hinzufügen des JavaScript-Codes zum DokumentAdd the JavaScript to get the document

Im Code für das Add-In wird über einen Handler für das Office.initialize-Ereignis ein Handler für das click-Ereignis der Schaltfläche Submit im Formular hinzugefügt, und der Benutzer wird informiert, dass das Add-In bereit ist.In the code for the add-in, a handler to the Office.initialize event adds a handler to the click event of the Submit button on the form and informs the user that the add-in is ready.

Im folgenden Codebeispiel wird der Ereignishandler für das Office.initialize-Ereignis zusammen mit der Hilfsfunktion updateStatus zum Schreiben in das div-Element "status" veranschaulicht.The following code example shows the event handler for the Office.initialize event along with a helper function, updateStatus, for writing to the status div.

// The initialize function is required for all add-ins.
Office.initialize = function (reason) {

    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {

        // Execute sendFile when submit is clicked
        $('#submit').click(function () {
            sendFile();
        });

        // Update status
        updateStatus("Ready to send file.");
    });
}

// Create a function for writing to the status div.
function updateStatus(message) {
    var statusInfo = $('#status');
    statusInfo.innerHTML += message + "<br/>";
}

Wenn Sie auf der Benutzeroberfläche die Schaltfläche Submit betätigen, ruft das Add-In die sendFile-Funktion auf, in der ein Aufruf der Methode Document.getFileAsync enthalten ist. Für die Methode getFileAsync wird das asynchrone Muster auf ähnliche Weise wie bei anderen Methoden in der JavaScript-API für Office verwendet. Sie verfügt über den erforderlichen Parameter fileType und die beiden optionalen Parameter options und callback.When you choose the Submit button in the UI, the add-in calls the sendFile function, which contains a call to the Document.getFileAsync method. The getFileAsync method uses the asynchronous pattern, similar to other methods in the JavaScript API for Office. It has one required parameter, fileType, and two optional parameters, options and callback.

Der fileType-Parameter erwartet von der FileType-Enumeration drei Konstanten: Office.FileType.Compressed ("compressed"), Office.FileType.PDF ("pdf") oder Office.FileType.Text ("text"). PowerPoint unterstützt nur Compressed als Argument, während Word alle drei Konstanten unterstützt. Wenn Sie Compressed für den fileType-Parameter übergeben, gibt die getFileAsync-Methode das Dokument als PowerPoint 2013-Präsentationsdatei (.pptx) oder Word 2013-Dokumentdatei (.docx) zurück, indem auf dem lokalen Computer eine temporäre Kopie der Datei erstellt wird.The fileType parameter expects one of three constants from the FileType enumeration: Office.FileType.Compressed ("compressed"), Office.FileType.PDF ("pdf"), or Office.FileType.Text ("text"). PowerPoint supports only Compressed as an argument; Word supports all three. When you pass in Compressed for the fileType parameter, the getFileAsync method returns the document as a PowerPoint 2013 presentation file (.pptx) or Word 2013 document file (.docx) by creating a temporary copy of the file on the local computer.

Die getFileAsync-Methode gibt einen Verweis auf die Datei als File-Objekt zurück. Vom File-Objekt werden vier Member verfügbar gemacht: die size-Eigenschaft, die sliceCount-Eigenschaft, die getSliceAsync-Methode und die closeAsync-Methode. Die size-Eigenschaft gibt die Byte-Anzahl der Datei zurück. Die sliceCount-Eigenschaft gibt die Anzahl von Slice-Objekten (weitere Informationen hierzu unten) in der Datei zurück.The getFileAsync method returns a reference to the file as a File object. The File object exposes four members: the size property, sliceCount property, getSliceAsync method, and closeAsync method. The size property returns the number of bytes in the file. The sliceCount returns the number of Slice objects (discussed later in this article) in the file.

Verwenden Sie den folgenden Code, um das PowerPoint- oder Word-Dokument mithilfe der Methode Document.getFileAsync als File-Objekt zurückzugeben und anschließend die lokal definierte Funktion getSlice aufzurufen. Beachten Sie, dass das Objekt File (eine Zählervariable) und die Gesamtzahl an Segmenten in der Datei beim Aufrufen von getSlice mittels eines anonymen Objekts übergeben werden.Use the following code to get the PowerPoint or Word document as a File object using the Document.getFileAsync method and then makes a call to the locally defined getSlice function. Note that the File object, a counter variable, and the total number of slices in the file are passed along in the call to getSlice in an anonymous object.

// Get all of the content from a PowerPoint or Word document in 100-KB chunks of text.
function sendFile() {
    Office.context.document.getFileAsync("compressed",
        { sliceSize: 100000 },
        function (result) {

            if (result.status == Office.AsyncResultStatus.Succeeded) {

                // Get the File object from the result.
                var myFile = result.value;
                var state = {
                    file: myFile,
                    counter: 0,
                    sliceCount: myFile.sliceCount
                };

                updateStatus("Getting file of " + myFile.size + " bytes");
                getSlice(state);
            }
            else {
                updateStatus(result.status);
            }
        });
}

Von der lokalen getSlice-Funktion wird die File.getSliceAsync-Methode aufgerufen, um ein Segment aus dem File-Objekt abzurufen. Die getSliceAsync-Methode gibt ein Slice-Objekt aus der Auflistung der Segmente zurück. Es verfügt über die beiden erforderlichen Parameter sliceIndex und callback. Der sliceIndex-Parameter nutzt eine ganze Zahl als Indexerstellung für die Auflistung der Segmente. Wie bei anderen Funktionen in der JavaScript-API für Office auch, verwendet die getSliceAsync-Methode ebenfalls eine Rückruffunktion als Parameter für die Behandlung der Ergebnisse des Methodenaufrufs.The local function getSlice makes a call to the File.getSliceAsync method to retrieve a slice from the File object. The getSliceAsync method returns a Slice object from the collection of slices. It has two required parameters, sliceIndex and callback. The sliceIndex parameter takes an integer as an indexer into the collection of slices. Like other functions in the JavaScript API for Office, the getSliceAsync method also takes a callback function as a parameter to handle the results from the method call.

Das Slice-Objekt ermöglicht Ihnen den Zugriff auf die in der Datei enthalten Daten.The Slice object gives you access to the data contained in the file. Sofern nicht anders angegeben im Optionen-Parameter der getFileAsync-Methode, hat das Slice-Objekt eine Größe von 4 MB.Unless otherwise specified in the options parameter of the getFileAsync method, the Slice object is 4 MB in size. Das Slice-Objekt legt drei Eigenschaften dar: Größe, Daten, und Index.The Slice object exposes three properties: size, data, and index. Die Eigenschaft Größe liefer die Größe des Slice (in Bytes).The size property gets the size, in bytes, of the slice. Die Eigenschaft Index liefert eine ganze Zahl, welche die Position des Slice in der Slice der Slices darstellt.The index property gets an integer that represents the slice's position in the collection of slices.

// Get a slice from the file and then call sendSlice.
function getSlice(state) {
    state.file.getSliceAsync(state.counter, function (result) {
        if (result.status == Office.AsyncResultStatus.Succeeded) {
            updateStatus("Sending piece " + (state.counter + 1) + " of " + state.sliceCount);
            sendSlice(result.value, state);
        }
        else {
            updateStatus(result.status);
        }
    });
}

Von der Eigenschaft Slice.data werden die Rohdaten der Datei als Bytearray zurückgegeben. Wenn die Daten im Textformat (XML oder Nur-Text) vorliegen, enthält das Segment den Rohtext. Wenn Sie Office.FileType.Compressed für den Parameter fileType von Document.getFileAsync übergeben, enthält das Segment die Binärdaten der Datei als Bytearray. Bei einer PowerPoint- oder Word-Datei enthalten die Segmente Bytearrays.The Slice.data property returns the raw data of the file as a byte array. If the data is in text format (that is, XML or plain text), the slice contains the raw text. If you pass in Office.FileType.Compressed for the fileType parameter of Document.getFileAsync, the slice contains the binary data of the file as a byte array. In the case of a PowerPoint or Word file, the slices contain byte arrays.

Sie müssen Ihre eigene Funktion implementieren (oder eine verfügbare Bibliothek verwenden), um Bytearraydaten in eine Base64-codierte Zeichenfolge zu konvertieren. Weitere Informationen zum Base64-Codieren mit JavaScript finden Sie unter Base64-Codierung und Decodierung.You must implement your own function (or use an available library) to convert byte array data to a Base64-encoded string. For information about Base64 encoding with JavaScript, see Base64 encoding and decoding.

Nachdem Sie die Daten in das Base64-Format konvertiert haben, können Sie diese auf unterschiedliche Arten auf einen Webserver übertragen, z. B. auch als Text einer HTTP POST-Anforderung.Once you have converted the data to Base64, you can then transmit it to a web server in several ways -- including as the body of an HTTP POST request.

Fügen Sie den folgenden Code hinzu, um ein Segment an einen Webdienst zu senden.Add the following code to send a slice to a web service.

Hinweis

Dieser Code sendet eine PowerPoint-oder Word-Datei an den Webserver in mehreren Segmenten.This code sends a PowerPoint or Word file to the web server in multiple slices. Der Webserver oder Dienst muss jedes einzelne Segment in eine einzelne Datei anhängen und es dann als PPTX-oder DOCX-Datei speichern, bevor Sie Manipulationen daran vornehmen können.The web server or service must append each individual slice into a single file, and then save it as a .pptx or .docx file, before you can perform any manipulations on it.

function sendSlice(slice, state) {
    var data = slice.data;

    // If the slice contains data, create an HTTP request.
    if (data) {

        // Encode the slice data, a byte array, as a Base64 string.
        // NOTE: The implementation of myEncodeBase64(input) function isn't
        // included with this example. For information about Base64 encoding with
        // JavaScript, see https://developer.mozilla.org/docs/Web/JavaScript/Base64_encoding_and_decoding.
        var fileData = myEncodeBase64(data);

        // Create a new HTTP request. You need to send the request
        // to a webpage that can receive a post.
        var request = new XMLHttpRequest();

        // Create a handler function to update the status
        // when the request has been sent.
        request.onreadystatechange = function () {
            if (request.readyState == 4) {

                updateStatus("Sent " + slice.size + " bytes.");
                state.counter++;

                if (state.counter < state.sliceCount) {
                    getSlice(state);
                }
                else {
                    closeFile(state);
                }
            }
        }

        request.open("POST", "[Your receiving page or service]");
        request.setRequestHeader("Slice-Number", slice.index);

        // Send the file as the body of an HTTP POST
        // request to the web server.
        request.send(fileData);
    }
}

Wie der Name vermuten lässt, wird die Methode File.closeAsync zum Schließen der Verbindung zum Dokument und zum Bereitstellen von Ressourcen verwendet. Obwohl von der Sandbox des Office-Add-Inss für nicht mehr relevante Dateiverweise eine Speicherbereinigung durchgeführt wird, ist es trotzdem am besten, Dateien explizit zu schließen, nachdem die Bearbeitung durch Ihren Code beendet ist. Die Methode closeAsync verfügt über einen callback-Parameter, mit dem angegeben wird, welche Funktion nach Abschluss des Aufrufs aufgerufen wird.As the name implies, the File.closeAsync method closes the connection to the document and frees up resources. Although the Office Add-ins sandbox garbage collects out-of-scope references to files, it is still a best practice to explicitly close files once your code is done with them. The closeAsync method has a single parameter, callback, that specifies the function to call on the completion of the call.

function closeFile(state) {
    // Close the file when you're done with it.
    state.file.closeAsync(function (result) {

        // If the result returns as a success, the
        // file has been successfully closed.
        if (result.status == "succeeded") {
            updateStatus("File closed.");
        }
        else {
            updateStatus("File couldn't be closed.");
        }
    });
}