Partilhar via

Personalizações no nível do documento do programa

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

  • Automatize o aplicativo usando seu modelo de objeto.

  • Adicione controles à superfície do documento.

  • Chamar o código do Visual Basic for Applications (VBA) no documento a partir do conjunto de personalização.

  • Código de chamada no assembly de personalização do VBA.

  • Gerencie certos aspetos 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 do Office e tipo de projeto.

    Alguns aspetos 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 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 no 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 do 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.

  • Os projetos de nível de documento para Excel têm várias classes geradas: uma para a pasta de trabalho em si 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 o código imediatamente 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.

Compreender 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 Visual Studio Tools for Office runtime são interfaces, portanto, as classes geradas não podem derivar sua implementação a partir 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 do Visual Studio Tools for Office. Por exemplo, se você chamar o Protect método da ThisDocument classe, a DocumentBase classe redirecionará essa chamada para a Document implementação interna da 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 eles 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 de 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 ThisDocument classe obtém a maioria dos seus membros do Document item host, o Save método que é chamado neste código é realmente o Save método do Document item host. Este método corresponde ao método Save do objeto Document no modelo de objetos 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 Globals objeto, consulte Acesso global a objetos em projetos do Office.

Adicionar controlos a documentos

Para personalizar a interface do usuário do documento, você pode adicionar controles Windows Forms ou controles de host à superfície do documento. Combinando diferentes conjuntos de controles e escrevendo código, você pode vincular 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 Excel. Por exemplo, o ListObject controle de host fornece todas as funcionalidades do ListObject no Excel. No entanto, o ListObject controle de host também tem eventos adicionais e recursos 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 dos controles de formulários do Windows em documentos do Office.

Combine o 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 a partir da assemblagem de personalização e também pode configurar o seu projeto para permitir que o código VBA no documento chame o código na assemblagem de personalização.

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

Gerenciar documentos em um servidor

Você pode gerenciar vários aspetos 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 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 no nível do documento:

Obter objetos ampliados a partir de objetos nativos do Office em personalizações ao nível de 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 na personalização no nível do documento gerar o evento. Por exemplo, em uma personalização no nível de documento para o Excel, talvez você queira executar algum código quando o usuário ativa uma das planilhas na pasta de trabalho personalizada, mas não quando o usuário ativa uma planilha em 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 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, 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 Visão geral de 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 HasVstoObject método 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 contrário.

  • Use o GetVstoObject método se quiser obter o objeto estendido para um objeto nativo do Office. Esse método retorna um ListObject, Workbook, Worksheet, ou Document objeto se o objeto nativo do Office especificado tiver um. Caso contrário, GetVstoObject retorna null. Por exemplo, o GetVstoObject método retorna um Document se o especificado Document é 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 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ê quiser criar novos itens de host em tempo de execução, você deve 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 Estender documentos do Word e pastas de trabalho do Excel em complementos do VSTO durante a execução.

Use 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 pretende testar.

Conteúdo relacionado

  • Last updated on