Abrufen des gesamten Dokuments aus einem Add-In für Word oder PowerPoint
Sie können ein Office-Add-In erstellen, um ein Word Dokument oder eine PowerPoint-Präsentation an einem Remotespeicherort zu senden oder zu veröffentlichen. In diesem Artikel wird veranschaulicht, wie Sie ein einfaches Aufgabenbereich-Add-In für PowerPoint oder Word erstellen, das die gesamte Präsentation oder das Dokument als Datenobjekt abruft und diese Daten über eine HTTP-Anforderung an einen Webserver sendet.
Voraussetzungen für das Erstellen eines Add-ins für PowerPoint oder Word
In diesem Artikel wird angenommen, dass Sie zum Erstellen des Aufgabenbereich-Add-ins für PowerPoint oder Word einen Text-Editor verwenden. Zum Erstellen des Aufgabenbereich-Add-Ins müssen Sie die folgenden Dateien erstellen.
In einem freigegebenen Netzwerkordner oder auf einem Webserver benötigen Sie die folgenden Dateien.
Eine HTML-Datei (GetDoc_App.html), die die Benutzeroberfläche sowie Links zu den JavaScript-Dateien (einschließlich Office.js und anwendungsspezifischen .js-Dateien) und Css-Dateien (Cascading Style Sheet) enthält.
Eine JavaScript-Datei (GetDoc_App.js), die die Programmierlogik des Add-Ins enthält.
Eine CSS-Datei (Program.css), die die Formatvorlagen und Formatierungen für das Add-In enthält.
Eine XML-Manifestdatei (GetDoc_App.xml) für das Add-In, die in einem freigegebenen Netzwerkordner oder Add-In-Katalog verfügbar ist. Die Manifestdatei muss auf den Speicherort der oben erwähnten HTML-Datei verweisen.
Alternativ können Sie mithilfe einer der folgenden Optionen ein Add-In für Ihre Office-Anwendung erstellen. Sie müssen keine neuen Dateien erstellen, da die Entsprechung jeder erforderlichen Datei für Sie verfügbar ist, um sie zu aktualisieren. Zu den Yeoman-Generatoroptionen gehören beispielsweise ./src/taskpane/taskpane.html, ./src/taskpane/taskpane.js, ./src/taskpane/taskpane.css und ./manifest.xml.
- PowerPoint
- Word
Wichtige Begriffe für die Erstellung eines Aufgabenbereich-Add-ins
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 erläutert, wie Base64-codierter Text aus einer HTTP-Anforderung auf einem Webserver decodiert wird.
Erstellen des Manifests für das Add-in
Die XML-Manifestdatei für ein Office-Add-In enthält wichtige Informationen zum Add-In: welche Anwendungen es hosten können, den Speicherort der HTML-Datei, den Titel und die Beschreibung des Add-Ins und viele andere Merkmale.
Fügen Sie der Manifestdatei im Texteditor den folgenden Code hinzu.
<?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>Speichern Sie die Datei als GetDoc_App.xml mit UTF-8-Codierung an einem Netzwerkspeicherort oder in einem Add-In-Katalog.
Erstellen der Benutzeroberfläche für das Add-in
Für die Benutzeroberfläche des Add-Ins können Sie HTML verwenden, der direkt in die GetDoc_App.html-Datei geschrieben wurde. Die Programmierlogik und -funktionalität des Add-Ins müssen in einer JavaScript-Datei enthalten sein (z. B.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.
Fügen Sie in einer neuen Datei im Text-Editor den HTML-Code für Die ausgewählte Office-Anwendung hinzu.
<!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>Speichern Sie die Datei als GetDoc_App.html mit UTF-8-Codierung an einem Netzwerkspeicherort oder auf einem Webserver.
Hinweis
Stellen Sie sicher, dass die Kopftags des Add-Ins ein Skripttag mit einem gültigen Link zur Office.js Datei enthalten.
Wir verwenden CSS, um dem Add-In ein einfaches, aber modernes und professionelles Erscheinungsbild zu verleihen. Verwenden Sie die folgenden CSS-Daten, um das Format des Add-ins zu definieren.
Fügen Sie in einer neuen Datei im Texteditor die folgenden CSS-Daten hinzu.
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; }Speichern Sie die Datei als Program.css mit UTF-8-Codierung am Netzwerkspeicherort oder auf dem Webserver, auf dem sich die GetDoc_App.html-Datei befindet.
Hinzufügen des JavaScript-Codes zum Dokument
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.
Das folgende Codebeispiel zeigt den Ereignishandler für das Office.initialize Ereignis zusammen mit der Hilfsfunktion , updateStatuszum Schreiben in den status div.
// The initialize or onReady function is required for all add-ins.
Office.initialize = function (reason) {
// Checks for the DOM to load using the jQuery ready method.
$(document).ready(function () {
// Run sendFile when Submit is clicked.
$('#submit').on("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[0].innerHTML += message + "<br/>";
}
Wenn Sie auf der Benutzeroberfläche auf die Schaltfläche Senden klicken, ruft das Add-In die sendFile Funktion auf, die einen Aufruf der Document.getFileAsync-Methode enthält. Die getFileAsync -Methode verwendet das asynchrone Muster, ähnlich wie andere Methoden in der Office JavaScript-API. Es verfügt über einen erforderlichen Parameter, fileType, und zwei optionale Parameter, Optionen und Rückruf.
Der fileType-Parameter erwartet eine von drei Konstanten aus der FileType-Enumeration : Office.FileType.Compressed ("compressed"), Office.FileType.PDF ("pdf") oder Office.FileType.Text ("text"). Die aktuelle Dateitypunterstützung für jede Plattform ist unter den Document.getFileType-Hinweisen aufgeführt. Wenn Sie Compressed für den fileType-Parameter übergeben, gibt die getFileAsync Methode das aktuelle Dokument als PowerPoint-Präsentationsdatei (*.pptx) oder Word Dokumentdatei (*.docx) zurück, indem eine temporäre Kopie der Datei auf dem lokalen Computer erstellt wird.
Die getFileAsync -Methode gibt einen Verweis auf die Datei als File-Objekt zurück. Das File -Objekt macht die folgenden vier Member verfügbar.
Die size -Eigenschaft gibt die Anzahl der Bytes in der Datei zurück. Gibt sliceCount die Anzahl der Slice-Objekte (die weiter unten in diesem Artikel erläutert werden) in der Datei zurück.
Verwenden Sie den folgenden Code, um das aktuelle PowerPoint- oder Word Dokument mithilfe der Document.getFileAsync -Methode als File Objekt abzurufen, und rufen Sie dann die lokal definierte getSlice Funktion auf. Beachten Sie, dass das File -Objekt, eine Zählervariable und die Gesamtanzahl der Slices in der Datei beim Aufruf von getSlice in einem anonymen Objekt übergeben werden.
// 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);
}
});
}
Die lokale Funktion getSlice ruft die File.getSliceAsync -Methode auf, um einen Slice aus dem File -Objekt abzurufen. Die getSliceAsync -Methode gibt ein Slice -Objekt aus der Auflistung von Slices zurück. Es verfügt über die beiden erforderlichen Parameter sliceIndex und callback. Der sliceIndex-Parameter verwendet eine ganze Zahl als Indexer in die Auflistung von Slices. Wie andere Methoden in der Office JavaScript-API verwendet auch die getSliceAsync Methode eine Rückruffunktion als Parameter, um die Ergebnisse des Methodenaufrufs zu verarbeiten.
Mit Slice dem -Objekt erhalten Sie Zugriff auf die in der Datei enthaltenen Daten. Sofern im options-Parameter der getFileAsync -Methode nicht anders angegeben, ist das Slice Objekt 4 MB groß. Das Slice -Objekt macht drei Eigenschaften verfügbar: Größe, Daten und Index. Die size -Eigenschaft ruft die Größe des Slices in Bytes ab. Die index -Eigenschaft ruft eine ganze Zahl ab, die die Position des Slices in der Auflistung von Slices darstellt.
// 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);
}
});
}
Die Slice.data -Eigenschaft gibt die Rohdaten der Datei als Bytearray zurück. Wenn die Daten im Textformat (XML oder Nur-Text) vorliegen, enthält das Segment den Rohtext. Wenn Sie Office.FileType.Compressed für den fileType-Parameter von Document.getFileAsyncübergeben, enthält der Slice die Binärdaten der Datei als Bytearray. Bei einer PowerPoint- oder Word-Datei enthalten die Segmente Bytearrays.
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.
Nachdem Sie die Daten in Base64 konvertiert haben, können Sie sie auf verschiedene Arten an einen Webserver übertragen, einschließlich als Textkörper einer HTTP POST-Anforderung.
Fügen Sie den folgenden Code hinzu, um ein Segment an einen Webdienst zu senden.
Hinweis
Dieser Code sendet eine PowerPoint- oder Word-Datei in mehreren Slices an den Webserver. Der Webserver oder Dienst muss jedes einzelne Slice an eine einzelne Datei anfügen und dann als .pptx- oder .docx-Datei speichern, bevor Sie änderungen daran vornehmen können.
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 schon sagt, schließt die File.closeAsync Methode die Verbindung mit dem Dokument und gibt Ressourcen frei. Obwohl die Office-Add-Ins-Sandbox Garbage-Verweise außerhalb des Gültigkeitsbereichs auf Dateien sammelt, ist es dennoch eine bewährte Methode, Dateien explizit zu schließen, sobald Ihr Code mit ihnen fertig ist. Die closeAsync Methode verfügt über einen einzelnen Parameter, callback, der die Funktion angibt, die nach Abschluss des Aufrufs aufgerufen werden soll.
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 === Office.AsyncResultStatus.Succeeded) {
updateStatus("File closed.");
} else {
updateStatus("File couldn't be closed.");
}
});
}
Die endgültige JavaScript-Datei könnte wie folgt aussehen:
/*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/
// The initialize or onReady function is required for all add-ins.
Office.initialize = function (reason) {
// Checks for the DOM to load using the jQuery ready method.
$(document).ready(function () {
// Run sendFile when Submit is clicked.
$('#submit').on("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[0].innerHTML += message + "<br/>";
}
// 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);
}
});
}
// 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);
}
});
}
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);
}
}
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 === Office.AsyncResultStatus.Succeeded) {
updateStatus("File closed.");
} else {
updateStatus("File couldn't be closed.");
}
});
}
Office Add-ins
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für