Share via

Personalizações em nível de documento do programa

  • Artigo

Ao estender o Microsoft Office Word ou o Microsoft Office Excel usando uma personalização em nível de 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 do assembly de personalização.

  • Código de chamada 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 (UI) 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 Recursos disponíveis por aplicativo e tipo de projeto do Office.

    Alguns aspectos de escrever 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 maneira 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 em nível de 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 de desenvolvimento de soluções do Office (VSTO).

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

Quando você cria um projeto de nível de documento, o Visual Studio gera automaticamente uma classe no projeto que você pode usar para começar a escrever seu código. 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.

  • Projetos de nível de documento para Excel têm várias classes geradas: uma para a própria pasta de trabalho e uma 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 código quando o documento é aberto, adicione código ao manipulador de Startup eventos. Para executar código antes de o documento ser fechado, adicione código ao manipulador de Shutdown eventos. Para obter mais informações, consulte Eventos em projetos do Office.

Entenda o design das classes geradas

Em projetos destinados ao .NET Framework 4 ou ao .NET Framework 4.5, os tipos de item de host no tempo de execução 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 base:

  • ThisDocument: deriva de DocumentBase.

  • ThisWorkbook: deriva de WorkbookBase.

  • Sheetn: 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 tempo de execução do Visual Studio Tools for Office. Por exemplo, se você chamar o ProtectThisDocument método da classe, a classe redireciona essa chamada para a DocumentBase implementação interna da Document interface no Visual Studio Tools for Office runtime .

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 Word e contêm a maioria das mesmas propriedades, métodos e eventos. Por exemplo, a classe em um projeto de nível de documento para o Word fornece a ThisDocument 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 em nível de 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 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 obtém a ThisDocument maioria de seus membros do Document item de host, o método que é chamado nesse código é realmente o SaveSave método do item de Document host. Esse método corresponde ao Save método do objeto no modelo de Document objeto do Word.

Para obter 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 obter mais informações sobre o objeto, consulte Acesso global a objetos em projetos do Globals 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 vincular os controles a dados, coletar informações do usuário e responder a ações do usuário.

Controles de host são classes que estendem alguns dos objetos no modelo de objeto do Word e Excel. Por exemplo, o ListObject controle de host fornece toda a funcionalidade do ListObject no Excel. No entanto, o controle de host também tem eventos adicionais e recursos de vinculação de ListObject 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 em nível de 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 habilitar o código VBA no documento para chamar código no assembly de personalização.

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

Gerenciar documentos em um servidor

Você pode gerenciar vários aspectos diferentes de personalizações em nível de documento em um servidor que não tenha o Microsoft Office Word ou o Microsoft Office Excel instalado. 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ê pode 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 em nível de documento:

Obter objetos estendidos de objetos nativos do Office em personalizações em nível de documento

Muitos manipuladores de eventos para 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 na personalização em nível de documento gerar o evento. Por exemplo, em uma personalização em nível de 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, você pode testar se esse objeto foi estendido em um item de host ou controle de host em uma personalização em nível de documento. Itens de host e controles de host são tipos fornecidos pelo Visual Studio Tools for Office runtime que adicionam funcionalidade 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 obter mais informações sobre itens de host e controles de host, consulte Visão geral sobre itens de host e controles de host.

Compreender os métodos GetVstoObject e HasVstoObject

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

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

  • Use o método se desejar obter o GetVstoObject objeto estendido para um objeto nativo do Office. Esse método retorna um objeto , , Worksheetou Document se o objeto Workbooknativo do Office especificado tiver umListObject. Caso contrário, GetVstoObject retornará null. Por exemplo, o método retorna um Document se o especificado Document é o objeto subjacente para o GetVstoObject documento em seu projeto de documento do Word.

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

Use os métodos GetVstoObject e HasVstoObject

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

Conteúdo relacionado