Obter todo o documento por meio de um suplemento para PowerPoint ou Word
Você pode criar um Suplemento do Office para enviar ou publicar uma apresentação do PowerPoint ou Word documento para um local remoto. 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 por meio de uma solicitação 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, você deve criar os arquivos a seguir.
Em uma pasta de rede compartilhada ou em um servidor Web, você precisa dos arquivos a seguir.
Um arquivo HTML (GetDoc_App.html) que contém a interface do usuário mais links para os arquivos JavaScript (incluindo arquivos Office.js e .js específicos do aplicativo) e arquivos CSS (Folha de Estilo em cascata).
Um arquivo JavaScript (GetDoc_App.js) para conter a lógica de programação do suplemento.
Um arquivo CSS (Program.css) para conter os estilos e a formatação do suplemento.
Um arquivo de manifesto XML (GetDoc_App.xml) para o suplemento, disponível em uma pasta de rede compartilhada ou catálogo de suplementos. O arquivo de manifesto deve apontar para o local do arquivo HTML mencionado anteriormente.
Como alternativa, você pode criar um suplemento para seu aplicativo do Office usando uma das opções a seguir. Você não precisará criar novos arquivos, pois o equivalente a cada arquivo necessário estará disponível para você atualizar. Por exemplo, as opções de gerador do 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 discute como decodificar o texto codificado do Base64 de uma solicitação HTTP em um servidor Web.
Criar o manifesto para o suplemento
O arquivo de manifesto XML de um Suplemento do Office fornece informações importantes sobre o suplemento: quais aplicativos podem hospedá-lo, o local do arquivo 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>Salve o arquivo como GetDoc_App.xml usando a codificação UTF-8 em um local de rede ou em um catálogo de suplementos.
Criar a interface de usuário para o suplemento
Para a interface do usuário do suplemento, você pode usar HTML gravado diretamente no arquivo GetDoc_App.html . A lógica de programação e a funcionalidade do suplemento devem ser contidas em um arquivo 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.
Em um novo arquivo no editor de texto, adicione o HTML para seu aplicativo do Office selecionado.
<!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>Salve o arquivo como GetDoc_App.html usando a codificação UTF-8 em um local de rede ou em um servidor Web.
Observação
Verifique se as marcas principais do suplemento contêm uma marca de script com um link válido para o arquivo Office.js.
Usaremos alguns CSS para dar ao suplemento uma aparência simples, mas moderna 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; }Salve o arquivo como Program.css usando a codificação UTF-8 para o local de rede ou para o servidor Web em que o arquivo GetDoc_App.html está localizado.
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 a seguir mostra o manipulador de eventos do Office.initialize evento juntamente com uma função auxiliar, updateStatus, para escrever no 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/>";
}
Quando você escolhe o botão Enviar na interface do usuário, o suplemento chama a sendFile função, que contém uma chamada para o método Document.getFileAsync . O getFileAsync método usa o padrão assíncrono, semelhante a outros métodos na API JavaScript do Office. Ele tem um parâmetro necessário, fileType e dois parâmetros opcionais, opções e retorno de chamada.
O parâmetro fileType espera uma das três constantes da enumeração FileType : Office.FileType.Compressed ("compactada"), Office.FileType.PDF ("pdf") ou Office.FileType.Text ("texto"). O suporte do tipo de arquivo atual para cada plataforma está listado nas observações Document.getFileType . Quando você passa compactado para o parâmetro fileType, o getFileAsync método retorna o documento atual como um arquivo de apresentação do PowerPoint (*.pptx) ou Word arquivo de documento (*.docx) criando uma cópia temporária do arquivo no computador local.
O getFileAsync método retorna uma referência ao arquivo como um objeto File . O File objeto expõe os quatro membros a seguir.
- propriedade size
- propriedade sliceCount
- Método getSliceAsync
- método closeAsync
A size propriedade retorna o número de bytes no arquivo. O sliceCount retorna o número de objetos Slice (discutidos posteriormente neste artigo) no arquivo.
Use o código a seguir para obter o documento atual do PowerPoint ou Word como um File objeto usando o Document.getFileAsync método e, em seguida, fazer uma chamada para a função definida getSlice localmente. Observe que o File objeto, uma variável de contador e o número total de fatias no arquivo são passados na chamada para getSlice em um 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 recuperar uma fatia do File objeto. O getSliceAsync método retorna um Slice objeto da coleção de fatias. Ele tem dois parâmetros obrigatórios, sliceIndex e callback. O parâmetro sliceIndex usa um inteiro como indexador na coleção de fatias. Assim como outros métodos na API JavaScript do Office, o getSliceAsync método também usa uma função de retorno de chamada como um parâmetro para lidar com os resultados da chamada de método.
O Slice objeto fornece acesso aos dados contidos no arquivo. A menos que seja especificado de outra forma no parâmetro de opções do getFileAsync método, o Slice objeto tem 4 MB de tamanho. O Slice objeto expõe três propriedades: tamanho, dados e índice. A size propriedade obtém o tamanho, em bytes, da fatia. A index propriedade obtém um inteiro que representa a posição da fatia na coleção de fatias.
// 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 retorna os dados brutos do arquivo 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 você passar no Office.FileType.Compressed para o parâmetro fileType de Document.getFileAsync, a fatia contém os dados binários do arquivo 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 em Base64, você poderá transmiti-los para um servidor Web de várias maneiras, incluindo como o corpo de uma solicitação HTTP POST.
Adicione o seguinte código para enviar uma fatia para um serviço Web.
Observação
Esse código envia um arquivo do PowerPoint ou Word para o servidor Web em várias fatias. O servidor Web ou serviço deve acrescentar cada fatia individual em um único arquivo e salvá-la como um arquivo .pptx ou .docx para que você possa executar qualquer manipulação nele.
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 conexão com o documento e libera recursos. Embora o lixo de área restrita suplementos do Office colete referências fora do escopo para arquivos, ainda é uma prática recomendada fechar arquivos explicitamente depois que seu código é feito com eles. O closeAsync método tem um único parâmetro, o retorno de chamada, que especifica a função a ser chamada na 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 arquivo JavaScript final pode se parecer com o seguinte:
/*
* 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.");
}
});
}
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de