Obter todo o documento por meio de um suplemento para PowerPoint ou Word
Pode criar um Suplemento do Office para enviar ou publicar uma apresentação do PowerPoint ou um documento do Word numa localização remota. Este artigo demonstra como criar um suplemento de painel de tarefas simples para o PowerPoint ou Word que obtém toda a apresentação ou documento como um objeto de dados e envia esses dados para um servidor Web através de um pedido HTTP.
Pré-requisitos para a criação de um suplemento para o PowerPoint ou Word
Este artigo pressupõe que você esteja usando um editor de texto para criar o suplemento de painel de tarefas do PowerPoint ou Word. Para criar o suplemento do painel de tarefas, tem de criar os seguintes ficheiros.
Numa pasta de rede partilhada ou num servidor Web, precisa dos seguintes ficheiros.
Um ficheiro HTML (GetDoc_App.html) que contém a interface de utilizador e ligações para os ficheiros JavaScript (incluindo ficheiros Office.js e .js específicos da aplicação) e ficheiros CSS (Cascading Style Sheet).
Um ficheiro JavaScript (GetDoc_App.js) para conter a lógica de programação do suplemento.
Um ficheiro CSS (Program.css) para conter os estilos e formatação do suplemento.
Um ficheiro de manifesto apenas de suplemento (GetDoc_App.xml) para o suplemento, disponível numa pasta de rede partilhada ou catálogo de suplementos. O arquivo de manifesto deve apontar para o local do arquivo HTML mencionado anteriormente.
Em alternativa, pode criar um suplemento para a sua aplicação do Office com uma das seguintes opções. Não terá de criar novos ficheiros, uma vez que o equivalente a cada ficheiro necessário estará disponível para atualização. Por exemplo, as opções do gerador Yeoman incluem ./src/taskpane/taskpane.html, ./src/taskpane/taskpane.js, ./src/taskpane/taskpane.css e ./manifest.xml.
- PowerPoint
- Word
Conceitos fundamentais para a criação de um suplemento de painel de tarefas
Antes de começar a criar esse suplemento do PowerPoint ou Word, você deve estar familiarizado com a criação de suplementos do Office e com o trabalho com solicitações HTTP. Este artigo não aborda como descodificar texto codificado com Base64 a partir de um pedido HTTP num servidor Web.
Criar o manifesto para o suplemento
O ficheiro de manifesto de um Suplemento do Office fornece informações importantes sobre o suplemento: que aplicações podem alojá-lo, a localização do ficheiro HTML, o título e a descrição do suplemento e muitas outras características.
Em um editor de texto, adicione o seguinte código ao arquivo do manifesto.
<?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 o ficheiro como GetDoc_App.xml através da codificação UTF-8 para uma localização de rede ou para um catálogo de suplementos.
Criar a interface de usuário para o suplemento
Para a interface de utilizador do suplemento, pode utilizar HTML escrito diretamente no ficheiro GetDoc_App.html . A lógica de programação e a funcionalidade do suplemento têm de estar contidas num ficheiro JavaScript (por exemplo, GetDoc_App.js).
Use o procedimento a seguir para criar uma interface de usuário simples para o suplemento incluindo um cabeçalho e um único botão.
Num novo ficheiro no editor de texto, adicione o HTML para a sua aplicação do Office selecionada.
<!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>Guarde o ficheiro como GetDoc_App.html através da codificação UTF-8 numa localização de rede ou num servidor Web.
Observação
Certifique-se de que as etiquetas principais do suplemento contêm uma etiqueta de script com uma ligação válida para o ficheiro de Office.js.
Vamos utilizar algum CSS para dar ao suplemento um aspeto simples, mas moderno e profissional. Use os seguintes CSS para definir o estilo do suplemento.
Em um novo arquivo no editor de texto, adicione o seguinte 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 o ficheiro como Program.css através da codificação UTF-8 para a localização de rede ou para o servidor Web onde se encontra o ficheiro GetDoc_App.html .
Adicionar o JavaScript para obter o documento
No código para o suplemento, um manipulador para o evento Office.initialize adiciona um manipulador para o evento de clique do botão Enviar no formulário e informa aos usuários que o suplemento está pronto.
O exemplo de código seguinte mostra o processador de eventos do Office.initialize evento juntamente com uma função auxiliar, updateStatus, para escrever no 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/>";
}
Quando seleciona o botão Submeter na IU, o suplemento chama a sendFile função, que contém uma chamada para o método Document.getFileAsync . O getFileAsync método utiliza o padrão assíncrono, semelhante a outros métodos na API JavaScript do Office. Tem um parâmetro necessário, fileType e dois parâmetros opcionais, opções e chamada de retorno.
O parâmetro fileType espera uma de três constantes da enumeração FileType : Office.FileType.Compressed ("comprimido"), Office.FileType.PDF ("pdf" ou Office.FileType.Text ("texto"). O suporte de tipo de ficheiro atual para cada plataforma está listado nas observações Document.getFileType . Quando transmite Comprimido para o parâmetro fileType , o getFileAsync método devolve o documento atual como um ficheiro de apresentação do PowerPoint (*.pptx) ou ficheiro de documento do Word (*.docx) ao criar uma cópia temporária do ficheiro no computador local.
O getFileAsync método devolve uma referência ao ficheiro como um objeto Ficheiro . O File objeto expõe os quatro membros seguintes.
- propriedade size
- propriedade sliceCount
- getSliceAsync method (Método getSliceAsync )
- closeAsync method (método closeAsync )
A size propriedade devolve o número de bytes no ficheiro. O sliceCount devolve o número de objetos Segmentação de Dados (abordados mais adiante neste artigo) no ficheiro.
Utilize o seguinte código para obter o documento atual do PowerPoint ou do Word como um File objeto com o Document.getFileAsync método e, em seguida, efetue uma chamada para a função definida getSlice localmente. Tenha em atenção que o File objeto, uma variável de contador e o número total de setores no ficheiro são transmitidos na chamada para getSlice num 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);
}
});
}
A função getSlice local faz uma chamada para o File.getSliceAsync método para obter um setor do File objeto. O getSliceAsync método devolve um Slice objeto da coleção de setores. Ele tem dois parâmetros obrigatórios, sliceIndex e callback. O parâmetro sliceIndex utiliza um número inteiro como indexador na coleção de setores. Tal como outros métodos na API javaScript do Office, o getSliceAsync método também utiliza uma função de chamada de retorno como um parâmetro para processar os resultados da chamada de método.
O Slice objeto dá-lhe acesso aos dados contidos no ficheiro. Salvo especificação em contrário no parâmetro de opções do getFileAsync método , o Slice objeto tem um tamanho de 4 MB. O Slice objeto expõe três propriedades: tamanho, dados e índice. A size propriedade obtém o tamanho, em bytes, do setor. A index propriedade obtém um número inteiro que representa a posição do setor na coleção de setores.
// 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);
}
});
}
A Slice.data propriedade devolve os dados não processados do ficheiro como uma matriz de bytes. Se os dados forem no formato de texto (ou seja, XML ou texto sem formatação), a fatia contém o texto não processado. Se transmitir Office.FileType.Compressed para o parâmetro fileType de Document.getFileAsync, o setor contém os dados binários do ficheiro como uma matriz de bytes. No caso de um arquivo do PowerPoint ou do Word, as fatias contêm matrizes de bytes.
Você deve implementar sua própria função (ou usar uma biblioteca disponível) para converter dados da matriz de bytes em uma cadeia de caracteres com codificação por Base64. Para saber mais sobre a codificação por Base64 com JavaScript, confira Codificação e decodificação por Base64.
Depois de converter os dados para Base64, pode transmiti-lo para um servidor Web de várias formas, incluindo como o corpo de um pedido HTTP POST.
Adicione o seguinte código para enviar uma fatia para um serviço Web.
Observação
Este código envia um ficheiro do PowerPoint ou word para o servidor Web em vários setores. O servidor ou serviço Web tem de acrescentar cada setor individual a um único ficheiro e, em seguida, guardá-lo como um ficheiro .pptx ou .docx antes de poder efetuar manipulações no mesmo.
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 o nome indica, o File.closeAsync método fecha a ligação ao documento e liberta recursos. Embora a memória do sandbox dos Suplementos do Office recolha referências fora do âmbito aos ficheiros, continua a ser uma melhor prática fechar explicitamente os ficheiros assim que o seu código for concluído com os mesmos. O closeAsync método tem um único parâmetro, chamada de retorno, que especifica a função a chamar após a conclusão da chamada.
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.");
}
});
}
O ficheiro JavaScript final pode ter o seguinte aspeto:
/*
* 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.");
}
});
}