Início rápido: criar seu primeiro suplemento de painel de tarefas do Word com o Visual Studio

Neste início rápido, você criará um suplemento do painel de tarefas do Word que demonstra como:

  • Inserir texto em locais diferentes em um documento (seleção, início, fim).
  • Use a API JavaScript do Word para manipular o conteúdo do documento.
  • Configure um projeto do Visual Studio para o desenvolvimento de Suplementos do Office.

O que você criará

Você criará um suplemento de painel de tarefas simples, mas funcional, com três botões que inserem citações inspiradoras em um documento do Word em diferentes posições. Este início rápido prático ensina os conceitos básicos do desenvolvimento de suplementos do Word.

Principais recursos que você implementará

  • Inserir conteúdo na seleção atual.
  • Inserir o conteúdo no início do documento.
  • Inserir o conteúdo no final do documento.
  • Lide com operações assíncronas com a API JavaScript do Word.

Pré-requisitos

  • Visual Studio 2019 ou posterior com a carga de trabalho Desenvolvimento Office/SharePoint instalada.

    Observação

    Se você já instalou o Visual Studio, use o Instalador do Visual Studio para garantir que a carga de trabalho de desenvolvimento do Office/SharePoint esteja instalada.

  • Office conectado a uma assinatura Microsoft 365 (incluindo o Office na web).

Criar o projeto do suplemento

  1. No Visual Studio, escolha Criar um novo projeto.

  2. Usando a caixa de pesquisa, insira suplemento. Escolha Suplemento do Word Web , em seguida, selecione Próximo.

  3. Nomeie seu projeto e selecione Criar.

  4. O Visual Studio cria uma solução, e os dois projetos dele aparecem no Gerenciador de Soluções. O arquivo Home.html é aberto no Visual Studio.

Explorar a solução do Visual Studio

Ao concluir o assistente, o Visual Studio cria uma solução que contém dois projetos.

Project Descrição
Projeto de suplemento Contém apenas um arquivo de manifesto somente de suplemento formatado em XML, que contém todas as configurações que descrevem seu suplemento. As configurações ajudam o aplicativo do Office a determinar quando o suplemento deverá ser ativado e onde ele deverá aparecer. O Visual Studio gera o conteúdo desse arquivo para que você possa executar o projeto e usar o suplemento imediatamente. Altere essas configurações a qualquer momento modificando o arquivo XML.
Projeto de aplicativo Web Contém as páginas de conteúdo do suplemento, incluindo todos os arquivos e referências de arquivo de que você precisa para desenvolver páginas HTML e JavaScript com reconhecimento do Office. Enquanto você desenvolve o suplemento, o Visual Studio hospeda o aplicativo Web no servidor IIS local. Quando estiver pronto para publicar, você precisará implantar este projeto de aplicativo Web em um servidor Web.

Etapa 1: Atualizar a marcação HTML

Home.html especifica o HTML que será renderizado no painel de tarefas do suplemento. Em Home.html, substitua o elemento <body> pela marcação a seguir e salve o arquivo.

<body>
    <div id="content-header">
        <div class="padding">
            <h1>Welcome</h1>
        </div>
    </div>
    <div id="content-main">
        <div class="padding">
            <p>Choose the buttons below to add boilerplate text to the document by using the Word JavaScript API.</p>
            <br />
            <h3>Try it out</h3>
            <button id="emerson">Add quote from Ralph Waldo Emerson</button>
            <br /><br />
            <button id="checkhov">Add quote from Anton Chekhov</button>
            <br /><br />
            <button id="proverb">Add Chinese proverb</button>
        </div>
    </div>
    <br />
    <div id="supportedVersion"/>
</body>

Etapa 2: adicionar a funcionalidade JavaScript

Abra o arquivo Home.js na raiz do projeto do aplicativo Web. Este arquivo especifica o script do suplemento. Substitua todo o conteúdo pelo código a seguir e salve o arquivo.

'use strict';

(function () {

    Office.onReady(function() {
        // Office is ready.
        $(document).ready(function () {
            // The document is ready.
            // Use this to check whether the API is supported in the Word client.
            if (Office.context.requirements.isSetSupported('WordApi', '1.1')) {
                // Do something that is only available via the new APIs.
                $('#emerson').on("click", insertEmersonQuoteAtSelection);
                $('#checkhov').on("click", insertChekhovQuoteAtTheBeginning);
                $('#proverb').on("click", insertChineseProverbAtTheEnd);
                $('#supportedVersion').html('This code is using Word 2016 or later.');
            } else {
                // Lets you know that this code will not work with your version of Word.
                $('#supportedVersion').html('This code requires Word 2016 or later.');
            }
        });
    });

    async function insertEmersonQuoteAtSelection() {
        await Word.run(async (context) => {

            // Create a proxy object for the document.
            const thisDocument = context.document;

            // Queue a command to get the current selection.
            // Create a proxy range object for the selection.
            const range = thisDocument.getSelection();

            // Queue a command to replace the selected text.
            range.insertText('"Hitch your wagon to a star." - Ralph Waldo Emerson\n', Word.InsertLocation.replace);

            // Synchronize the document state by executing the queued commands,
            // and return a promise to indicate task completion.
            await context.sync();
            console.log('Added a quote from Ralph Waldo Emerson.');
        })
        .catch(function (error) {
            console.log('Error: ' + JSON.stringify(error));
            if (error instanceof OfficeExtension.Error) {
                console.log('Debug info: ' + JSON.stringify(error.debugInfo));
            }
        });
    }

    async function insertChekhovQuoteAtTheBeginning() {
        await Word.run(async (context) => {

            // Create a proxy object for the document body.
            const body = context.document.body;

            // Queue a command to insert text at the start of the document body.
            body.insertText('"Knowledge is of no value unless you put it into practice." - Anton Chekhov\n', Word.InsertLocation.start);

            // Synchronize the document state by executing the queued commands,
            // and return a promise to indicate task completion.
            await context.sync();
            console.log('Added a quote from Anton Chekhov.');
        })
        .catch(function (error) {
            console.log('Error: ' + JSON.stringify(error));
            if (error instanceof OfficeExtension.Error) {
                console.log('Debug info: ' + JSON.stringify(error.debugInfo));
            }
        });
    }

    async function insertChineseProverbAtTheEnd() {
        await Word.run(async (context) => {

            // Create a proxy object for the document body.
            const body = context.document.body;

            // Queue a command to insert text at the end of the document body.
            body.insertText('"To know the road ahead, ask those coming back." - Chinese proverb\n', Word.InsertLocation.end);

            // Synchronize the document state by executing the queued commands,
            // and return a promise to indicate task completion.
            await context.sync();
            console.log('Added a quote from a Chinese proverb.');
        })
        .catch(function (error) {
            console.log('Error: ' + JSON.stringify(error));
            if (error instanceof OfficeExtension.Error) {
                console.log('Debug info: ' + JSON.stringify(error.debugInfo));
            }
        });
    }
})();

Etapa 3: Adicionar estilo personalizado

Abra o arquivo Home.css na raiz do projeto do aplicativo Web. Este arquivo especifica os estilos personalizados para o suplemento. Substitua todo o conteúdo pelo código a seguir e salve o arquivo.

#content-header {
    background: #2a8dd4;
    color: #fff;
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 80px;
    overflow: hidden;
}

#content-main {
    background: #fff;
    position: fixed;
    top: 80px;
    left: 0;
    right: 0;
    bottom: 0;
    overflow: auto;
}

.padding {
    padding: 15px;
}

Etapa 4: atualizar o manifesto do suplemento

  1. Abra o arquivo de manifesto somente do suplemento no projeto do suplemento. Este arquivo define as configurações e os recursos do suplemento.

  2. O elemento ProviderName tem um valor de espaço reservado. Substitua-o com seu nome.

  3. O atributo DefaultValue do elemento DisplayName tem um espaço reservado. Substitua-o pelo suplementos do My Office.

  4. O atributo DefaultValue do elemento Description tem um espaço reservado. Substitua-o com um suplemento do painel de tarefas do PowerPoint.

  5. Salve o arquivo.

    ...
<ProviderName>John Doe</ProviderName>
<DefaultLocale>en-US</DefaultLocale>
<!-- The display name of your add-in. Used on the Store and various places of the Office UI such as the add-in's dialog. -->
<DisplayName DefaultValue="My Office Add-in" />
<Description DefaultValue="A task pane add-in for Word."/>
...

Experimente

  1. Usando o Visual Studio, teste o suplemento do Word recém-criado pressionando F5 ou escolhendo Depurar>Iniciar Depuração para iniciar o Word com o botão do suplemento Mostrar Painel de Tarefas exibido na faixa de opções. O suplemento será hospedado localmente no IIS.

  2. No Word, se o painel de tarefas do suplemento ainda não estiver aberto, escolha a guia Página Inicial e, em seguida, escolha o botão Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas do suplemento.

    O aplicativo Word com o botão Mostrar Painel de Tarefas realçado.

  3. No painel de tarefas, escolha qualquer um dos botões para adicionar o texto clichê ao documento.

    O aplicativo Word com o suplemento clichê carregado.

Observação

Para ver o console.log output, você precisará de um conjunto separado de ferramentas para desenvolvedores para um console de JavaScript. Para saber mais sobre as ferramentas F12 e o DevTools do Microsoft Edge, confira Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge.

Próximas etapas

Parabéns, você criou com êxito um suplemento do painel de tarefas do Word! Em seguida, para saber mais sobre como desenvolver suplementos do Office com o Visual Studio, continue no artigo a seguir.

Desenvolver Suplementos do Office com o Visual Studio

Solução de problemas

  • Se o suplemento mostrar um erro (por exemplo, "Não foi possível iniciar este suplemento. Feche esta caixa de diálogo para ignorar o problema ou clique em "Reiniciar" para tentar novamente.") quando você pressiona F5 ou escolhe Iniciar Depuração> no Visual Studio, consulte Depurar Suplementos do Office no Visual Studio para obter outras opções de depuração.

Exemplos de código

Confira também

Principais conceitos

Referência e ferramentas de API

Publicação e implantação

  • Last updated on