Compartilhar via

Programar personalizações no nível do documento

Ao estender o Microsoft Office Word ou o Microsoft Office Excel usando uma personalização no nível do documento, você pode executar as seguintes tarefas:

  • Automatize o aplicativo usando seu modelo de objeto.

  • Adicione controles à superfície do documento.

  • Chame o código VBA (Visual Basic for Applications) no documento a partir do assembly de customização.

  • Chame o código no assembly de personalização a partir do VBA.

  • Gerencie determinados aspectos do documento enquanto ele estiver em um servidor que não tenha o Microsoft Office instalado.

  • Personalize a interface do usuário do aplicativo.

    Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento para Excel e Word. Para obter mais informações, consulte Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

    Alguns aspectos da escrita de código em projetos de nível de documento são diferentes de outros tipos de projetos no Visual Studio. Muitas dessas diferenças são causadas pela forma como os modelos de objeto do Office são expostos ao código gerenciado. Para obter mais informações, consulte Escrever código em soluções do Office.

    Para obter informações gerais sobre personalizações no nível do documento e outros tipos de soluções que você pode criar usando as ferramentas de desenvolvimento do Office no Visual Studio, consulte a VSTO (visão geral de desenvolvimento de soluções do Office).

Usar as classes geradas em projetos de nível de documento

Quando você cria um projeto no nível do documento, o Visual Studio gera automaticamente uma classe no projeto que você pode usar para começar a escrever seu código. O Visual Studio gera classes diferentes para Word e Excel:

  • Em projetos de nível de documento para o Word, a classe é chamada ThisDocument por padrão.

  • Os projetos de nível de documento para Excel têm várias classes geradas: uma para a própria pasta de trabalho e outra para cada planilha. Por padrão, essas classes têm os seguintes nomes:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    A classe gerada inclui manipuladores de eventos que são chamados quando o documento é aberto ou fechado. Para executar o código quando o documento for aberto, adicione código ao Startup manipulador de eventos. Para executar o código pouco antes de o documento ser fechado, adicione código ao Shutdown manipulador de eventos. Para obter mais informações, consulte Eventos em projetos do Office.

Entender o design das classes geradas

Em projetos direcionados ao .NET Framework 4 ou ao .NET Framework 4.5, os tipos de item de host no runtime das Ferramentas do Visual Studio para Office são interfaces, portanto, as classes geradas não podem derivar sua implementação deles. Em vez disso, as classes geradas derivam a maioria de seus membros das seguintes classes base:

  • ThisDocument: deriva de DocumentBase.

  • ThisWorkbook: deriva de WorkbookBase.

  • Sheet n: deriva de WorksheetBase.

    Essas classes base redirecionam todas as chamadas para seus membros para implementações internas das interfaces de item de host correspondentes no runtime das Ferramentas do Visual Studio para Office. Por exemplo, se você chamar o método Protect da classe ThisDocument, a classe DocumentBase redirecionará essa chamada para a implementação interna da interface Document no tempo de execução das Ferramentas do Visual Studio para Office.

Acessar o modelo de objeto do aplicativo host

Para acessar o modelo de objeto do aplicativo host, use membros da classe gerada em seu projeto. Cada uma dessas classes corresponde a um objeto no modelo de objeto do Excel ou do Word e elas contêm a maioria das mesmas propriedades, métodos e eventos. Por exemplo, a ThisDocument classe em um projeto de nível de documento para o Word fornece a maioria dos mesmos membros que o Document objeto no modelo de objeto do Word.

O exemplo de código a seguir mostra como usar o modelo de objeto do Word para salvar o documento que faz parte de uma personalização no nível do documento para o Word. Este exemplo destina-se a ser executado a partir da ThisDocument classe.

this.Save();

Para fazer a mesma coisa de fora da ThisDocument classe, use o Globals objeto para acessar a ThisDocument classe. Por exemplo, você pode adicionar esse código a um arquivo de código do painel ações se quiser incluir um botão Salvar na interface do usuário do painel de ações.

Globals.ThisDocument.Save();

Como a maioria dos membros da classe é obtida do item de host, o método Save chamado neste código é de fato o método Save do item de host Document. Esse método corresponde ao Save método do Document objeto no modelo de objeto do Word.

Para obter mais informações sobre como usar os modelos de objeto do Word e do Excel, consulte a visão geral do modelo de objeto do Word e a visão geral do modelo de objeto do Excel.

Para obter mais informações sobre o Globals objeto, consulte o acesso global a objetos em projetos do Office.

Adicionar controles a documentos

Para personalizar a interface do usuário do documento, você pode adicionar controles do Windows Forms ou controles de host à superfície do documento. Combinando diferentes conjuntos de controles e escrevendo código, você pode associar os controles aos dados, coletar informações do usuário e responder às ações do usuário.

Os controles de host são classes que estendem alguns dos objetos no modelo de objeto do Word e do Excel. Por exemplo, o controle ListObject host fornece todas as funcionalidades do ListObject no Excel. No entanto, o controle de ListObject host também possui eventos adicionais e capacidade de vinculação de dados.

Para obter mais informações, consulte visão geral de itens de host e controles de host e visão geral de controles de formulários do Windows em documentos do Office.

Combinar VBA e personalizações em nível de documento

Você pode usar o código VBA em um documento que faz parte de uma personalização no nível do documento. Você pode chamar o código VBA no documento a partir do assembly de personalização, e também pode configurar seu projeto para permitir que o código VBA no documento chame código no assembly de personalização.

Para obter mais informações, consulte Combinar personalizações em nível de documento e VBA.

Gerenciar documentos em um servidor

Você pode gerenciar vários aspectos diferentes de personalizações no nível do documento em um servidor que não tem o Microsoft Office Word ou o Microsoft Office Excel instalados. Por exemplo, você pode acessar e modificar dados no cache de dados do documento. Você também pode gerenciar o assembly de personalização associado ao documento. Por exemplo, você pode remover programaticamente o assembly do documento para que o documento não execute mais seu código ou você possa anexar programaticamente um assembly a um documento.

Para obter mais informações, consulte Gerenciar documentos em um servidor usando a classe ServerDocument.

Personalizar a interface do usuário de aplicativos do Microsoft Office

Você pode personalizar a interface do usuário do Word e do Excel das seguintes maneiras usando uma personalização no nível do documento:

Obter objetos ampliados de objetos nativos do Office em customizações de nível de documento

Muitos manipuladores de eventos para eventos do Office recebem um objeto nativo do Office que representa a pasta de trabalho, a planilha ou o documento que gerou o evento. Em alguns casos, talvez você queira executar algum código somente se a pasta de trabalho ou o documento em sua personalização no nível do documento gerar o evento. Por exemplo, em uma personalização no nível do documento para Excel, talvez você queira executar algum código quando o usuário ativar uma das planilhas na pasta de trabalho personalizada, mas não quando o usuário ativa uma planilha em alguma outra pasta de trabalho que esteja aberta ao mesmo tempo.

Quando você tiver um objeto nativo do Office, poderá testar se esse objeto foi estendido para um item de host ou controle de host em uma personalização no nível do documento. Itens de host e controles de host são tipos fornecidos pelas Ferramentas do Visual Studio para o runtime do Office que adicionam funcionalidade a objetos que existem nativamente nos modelos de objeto do Word ou do Excel ( chamados de objetos nativos do Office). Coletivamente, itens de host e controles de host também são chamados de objetos estendidos. Para obter mais informações sobre itens de host e controles de host, consulte a visão geral de itens de host e controles de host.

Entender os métodos GetVstoObject e HasVstoObject

Para testar um objeto nativo do Office, use os métodos HasVstoObject e GetVstoObject em seu projeto.

  • Use o método HasVstoObject se você quiser determinar se o objeto nativo do Office tem um objeto ampliado em sua personalização. Esse método retornará true se o objeto nativo do Office tiver um objeto estendido e false caso contrário.

  • Use o GetVstoObject método se você quiser obter o objeto estendido para um objeto nativo do Office. Esse método retorna um objeto ListObject, Workbook, Worksheet ou Document se o objeto nativo do Office especificado tiver um. Caso contrário, GetVstoObjectretornará nulo. Por exemplo, o GetVstoObject método retorna um Document se o especificado Document for o objeto subjacente para o documento em seu projeto de documento do Word.

    Em projetos de nível de documento, você não pode usar o método GetVstoObject para criar um novo item Workbook, Worksheet ou Document host em tempo de execução. Você pode usar esse método apenas para acessar itens de host existentes que são gerados em seu projeto em tempo de design. Se você quiser criar novos itens de host em tempo de execução, deverá desenvolver um projeto de Suplemento VSTO. Para obter mais informações, consulte Limitações programáticas de itens de host e controles de host e Ampliar documentos do Word e pastas de trabalho do Excel em suplementos VSTO durante a execução.

Usar os métodos GetVstoObject e HasVstoObject

Para chamar os métodos HasVstoObject e GetVstoObject, use os métodos Globals.Factory.GetVstoObject ou Globals.Factory.HasVstoObject e passe o objeto nativo do Word ou do Excel (como um Document ou Worksheet) que você deseja testar.

Conteúdo relacionado

  • Last updated on