Procedimiento para obtener el documento completo de un complemento para PowerPoint o Word
Puede crear un complemento de Office para enviar o publicar una presentación de PowerPoint o un documento Word a una ubicación remota. En este artículo se muestra cómo crear un complemento de panel de tareas simple para PowerPoint o Word que obtiene toda la presentación o el documento como un objeto de datos y envía esos datos a un servidor web a través de una solicitud HTTP.
Requisitos previos para crear un complemento para PowerPoint o Word
En este artículo se supone que se usa un editor de texto para crear el complemento de panel de tareas para PowerPoint o Word. Para crear el complemento del panel de tareas, debe crear los siguientes archivos.
En una carpeta de red compartida o en un servidor web, necesita los siguientes archivos.
Un archivo HTML (GetDoc_App.html) que contiene la interfaz de usuario más vínculos a los archivos de JavaScript (incluidos Office.js y archivos de .js específicos de la aplicación) y archivos de hoja de estilos en cascada (CSS).
Un archivo JavaScript (GetDoc_App.js) para contener la lógica de programación del complemento.
Un archivo CSS (Program.css) para contener los estilos y el formato del complemento.
Un archivo de manifiesto de solo complemento (GetDoc_App.xml) para el complemento, disponible en una carpeta de red compartida o en un catálogo de complementos. El archivo de manifiesto debe apuntar a la ubicación del archivo HTML mencionado anteriormente.
Como alternativa, puede crear un complemento para la aplicación de Office mediante una de las siguientes opciones. No tendrá que crear nuevos archivos, ya que el equivalente de cada archivo necesario estará disponible para actualizar. Por ejemplo, las opciones del generador de Yeoman incluyen ./src/taskpane/taskpane.html, ./src/taskpane/taskpane.js, ./src/taskpane/taskpane.css y ./manifest.xml.
- PowerPoint
- Word
Conceptos básicos que deben considerarse al crear un complemento de panel de tareas
Antes de empezar a crear este complemento para PowerPoint o Word, debe estar familiarizado con la compilación de Complementos de Office y estar acostumbrado a trabajar con solicitudes HTTP. En este artículo no se describe cómo descodificar texto codificado en Base64 a partir de una solicitud HTTP en un servidor web.
Crear el manifiesto del complemento
El archivo de manifiesto de un complemento de Office proporciona información importante sobre el complemento: qué aplicaciones pueden hospedarlo, la ubicación del archivo HTML, el título y la descripción del complemento, y muchas otras características.
En un editor de texto, agregue el siguiente código al archivo de manifiesto.
<?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>Guarde el archivo como GetDoc_App.xml mediante la codificación UTF-8 en una ubicación de red o en un catálogo de complementos.
Crear la interfaz de usuario del complemento
Para la interfaz de usuario del complemento, puede usar HTML escrito directamente en el archivo GetDoc_App.html . La lógica de programación y la funcionalidad del complemento deben estar contenidas en un archivo JavaScript (por ejemplo, GetDoc_App.js).
Use el siguiente procedimiento para crear una interfaz de usuario simple para el complemento, que incluya un título y un solo botón.
En un nuevo archivo en el editor de texto, agregue el CÓDIGO HTML para la aplicación de Office seleccionada.
<!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.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>Guarde el archivo como GetDoc_App.html mediante la codificación UTF-8 en una ubicación de red o en un servidor web.
Nota:
Asegúrese de que las etiquetas principales del complemento contengan una etiqueta de script con un vínculo válido al archivo Office.js.
Usaremos algunos CSS para dar al complemento un aspecto simple pero moderno y profesional. Use el siguiente código CSS para definir el estilo del complemento.
En el editor de texto, en un archivo nuevo, agregue el siguiente código 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; }Guarde el archivo como Program.css mediante la codificación UTF-8 en la ubicación de red o en el servidor web donde se encuentra el archivo GetDoc_App.html .
Agregar el código JavaScript para obtener el documento
En el código del complemento, un controlador del evento Office.initialize agrega un controlador al evento de clic del botón Enviar en el formulario e informa al usuario de que el complemento está listo.
En el ejemplo de código siguiente se muestra el controlador de eventos para el Office.initialize evento junto con una función auxiliar, updateStatus, para escribir en el div de estado.
// 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/>";
}
Al elegir el botón Enviar en la interfaz de usuario, el complemento llama a la sendFile función , que contiene una llamada al método Document.getFileAsync . El getFileAsync método usa el patrón asincrónico, similar a otros métodos de la API de JavaScript de Office. Tiene un parámetro obligatorio, fileType, y dos parámetros opcionales, options y callback.
El parámetro fileType espera una de las tres constantes de la enumeración FileType : Office.FileType.Compressed ("comprimido"), Office.FileType.PDF ("pdf") o Office.FileType.Text ("texto"). La compatibilidad con el tipo de archivo actual para cada plataforma se muestra en los comentarios de Document.getFileType . Al pasar Compressed para el parámetro fileType, el getFileAsync método devuelve el documento actual como un archivo de presentación de PowerPoint (*.pptx) o Word archivo de documento (*.docx) mediante la creación de una copia temporal del archivo en el equipo local.
El getFileAsync método devuelve una referencia al archivo como un objeto File . El File objeto expone los cuatro miembros siguientes.
- size (propiedad)
- sliceCount (propiedad)
- Método getSliceAsync
- closeAsync ( método)
La size propiedad devuelve el número de bytes del archivo.
sliceCount devuelve el número de objetos Slice (descrito más adelante en este artículo) en el archivo.
Use el código siguiente para obtener el documento actual de PowerPoint o Word como un File objeto mediante el Document.getFileAsync método y, a continuación, realice una llamada a la función definida getSlice localmente. Tenga en cuenta que el File objeto, una variable de contador y el número total de segmentos del archivo se pasan a lo largo de la llamada a getSlice en un objeto anónimo.
// 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);
}
});
}
La función getSlice local realiza una llamada al File.getSliceAsync método para recuperar un segmento del File objeto . El getSliceAsync método devuelve un Slice objeto de la colección de segmentos. Tiene dos parámetros obligatorios: sliceIndex y callback. El parámetro sliceIndex toma un entero como indexador en la colección de segmentos. Al igual que otros métodos de la API de JavaScript de Office, el getSliceAsync método también toma una función de devolución de llamada como parámetro para controlar los resultados de la llamada al método.
El Slice objeto proporciona acceso a los datos contenidos en el archivo. A menos que se especifique lo contrario en el parámetro options del getFileAsync método, el Slice objeto tiene un tamaño de 4 MB. El Slice objeto expone tres propiedades: size, data e index. La size propiedad obtiene el tamaño, en bytes, del segmento. La index propiedad obtiene un entero que representa la posición del segmento en la colección de segmentos.
// 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);
}
});
}
La Slice.data propiedad devuelve los datos sin procesar del archivo como una matriz de bytes. Si los datos están en formato de texto (es decir, XML o texto sin formato), el segmento contiene el texto sin formato. Si pasa Office.FileType.Compressed para el parámetro fileType de Document.getFileAsync, el segmento contiene los datos binarios del archivo como una matriz de bytes. En el caso de los archivos de PowerPoint o Word, los segmentos contienen matrices de bytes.
Debe implementar su propia función (o usar una biblioteca disponible) para convertir los datos de la matriz de bytes en una cadena codificada en Base64. Para obtener más información sobre la codificación en Base64 con JavaScript, consulte Codificación y descodificación en Base64.
Una vez que haya convertido los datos en Base64, puede transmitirlos a un servidor web de varias maneras, incluido el cuerpo de una solicitud HTTP POST.
Agregue el siguiente código para enviar un segmento a un servicio web.
Nota:
Este código envía un archivo de PowerPoint o Word al servidor web en varios segmentos. El servidor o servicio web debe anexar cada segmento individual en un único archivo y, a continuación, guardarlo como un archivo .pptx o .docx antes de poder realizar cualquier manipulación en él.
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);
}
}
Como su nombre indica, el File.closeAsync método cierra la conexión al documento y libera los recursos. Aunque el elemento no utilizado del espacio aislado de complementos de Office recopila referencias fuera del ámbito a los archivos, sigue siendo un procedimiento recomendado cerrar explícitamente los archivos una vez que el código se haya terminado con ellos. El closeAsync método tiene un único parámetro, devolución de llamada, que especifica la función a la que llamar al finalizar la llamada.
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.");
}
});
}
El archivo JavaScript final podría ser similar al siguiente:
/*
* 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.");
}
});
}