Program document-level customizations

  • Artigo

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 do VBA (Visual Basic for Applications) no documento do assembly de personalização.

  • Chame o código no assembly de personalização 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.

    Aplicável a: as informações neste tópico são aplicáveis aos projetos no nível de documento para Excel e Word. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

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

    Para mais 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 Visão geral do desenvolvimento de soluções do Office (VSTO).

Usar as classes geradas em projetos no nível do 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 Word, a classe é chamada ThisDocument por padrão.

  • Os projetos no 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 manipulador de eventos Startup. Para executar o código antes de o documento ser fechado, adicione código ao manipulador de eventos Shutdown. Para obter mais informações, consulte Eventos em projetos do Office.

Entenda 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 do Visual Studio Tools for 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 de base:

  • ThisDocument: deriva de DocumentBase.

  • ThisWorkbook: deriva de WorkbookBase.

  • Sheet n: deriva de WorksheetBase.

    Essas classes de base redirecionam todas as chamadas para seus membros para implementações internas das interfaces de item de host correspondentes no runtime do Visual Studio Tools for 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 runtime do Visual Studio Tools for 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 contém a maioria das mesmas propriedades, métodos e eventos. Por exemplo, a classe ThisDocument em um projeto de nível de documento para Word fornece a maioria dos mesmos membros que o objeto Document 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 classe ThisDocument.

this.Save();

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

Globals.ThisDocument.Save();

Como a classe ThisDocument obtém a maioria de seus membros do item de host Document, o método Save chamado nesse código é realmente o método Save do item de host Document. Esse método corresponde ao método Save do objeto Document no modelo de objeto do Word.

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

Para mais informações sobre o objeto Globals, consulte 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 do 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 de host ListObject fornece todas as funcionalidades do ListObject no Excel. No entanto, o controle de host ListObject também tem eventos adicionais e recursos de associação de dados.

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

Combinar VBA e personalizações no nível do 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 do assembly de personalização e também pode configurar seu projeto para habilitar o código VBA no documento para chamar o código no assembly de personalização.

Para mais informações, consulte Combinar personalizações no nível do VBA e do documento.

Gerenciar documentos em um servidor

Você pode gerenciar vários aspectos diferentes das personalizações no nível do documento em um servidor que não tenha 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 pode anexar programaticamente um assembly a um documento.

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

Personalizar a interface do usuário dos 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 estendidos de objetos nativos do Office em personalizações no nível do documento

Muitos manipuladores de eventos do Office recebem um objeto nativo do Office que representa a pasta de trabalho, planilha ou 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 gerou o evento. Por exemplo, em uma personalização no nível do documento para o 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 ativar uma planilha em alguma outra pasta de trabalho que esteja aberta ao mesmo tempo.

Quando você tem um objeto nativo do Office, pode 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 e controles de host são tipos fornecidos pelo runtime pelo Visual Studio Tools for Office que adicionam funcionalidades a objetos que existem nativamente nos modelos de objeto do Word ou Excel (chamados objetos nativos do Office). Coletivamente, os itens de host e os controles de host também são chamados de objetos estendidos. Para mais informações sobre itens e controles de host, consulte Visão geral de controles e itens de host.

Entender os métodos GetVstoObject e HasVstoObject

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

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

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

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

Usar os métodos GetVstoObject e HasVstoObject

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

Conteúdo relacionado