Visão geral de itens de host e controles de host

  • Artigo

Itens de host e controles de host são tipos que ajudam a fornecer o modelo de programação para soluções do Office que são criadas usando as ferramentas de desenvolvimento do Office no Visual Studio. Itens de host e controles de host tornam a interação com os modelos de objeto do Microsoft Office Word e do Microsoft Office Excel, que são baseados em COM, mais parecida com a interação com objetos gerenciados, como controles do Windows Forms.

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

Itens de host

Itens de host são tipos que estão na parte superior das hierarquias de modelo de objeto em projetos do Office. O Visual Studio Tools for Office runtime define os seguintes itens de host para soluções do Word e Excel:

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

    Cada um desses tipos estende um objeto que existe nativamente no modelo de objeto do Word ou Excel, chamado de objeto nativo do Office. Por exemplo, o item de host estende o Document Document objeto, que é definido no assembly de interoperabilidade primário do Word.

    Os itens de host geralmente têm a mesma funcionalidade básica que os objetos do Office correspondentes, mas são aprimorados com os seguintes recursos:

  • A capacidade de hospedar controles gerenciados, incluindo controles de host e controles do Windows Forms.

  • Modelos de eventos mais ricos. Alguns eventos de documento, pasta de trabalho e planilha nos modelos de objeto nativos do Word e do Excel são gerados somente no nível do aplicativo. Os itens de host fornecem esses eventos no nível do documento, para que seja mais fácil manipular os eventos de um documento específico.

Compreender itens de host em projetos de nível de documento

Em projetos de nível de documento, os itens de host fornecem um ponto de entrada para seu código e eles têm designers que ajudam você a desenvolver sua solução.

Os Document itens e Worksheet host têm designers associados que são a representação visual do documento ou planilha, como um designer do Windows Forms. Você pode usar esse designer para modificar o conteúdo do documento ou planilha diretamente no Word ou Excel e para arrastar controles para a superfície de design. Para obter mais informações, consulte Item de host de documento e Item de host de planilha.

O Workbook item de host não atua como um contêiner para controles que têm uma interface do usuário. Em vez disso, o designer desse item de host funciona como uma bandeja de componentes, o que permite arrastar um componente, como um DataSet, para sua superfície de design. Para obter mais informações, consulte Item de host da pasta de trabalho.

Os itens de host não podem ser criados programaticamente em projetos de nível de documento. Em vez disso, use as classes , ThisWorkbookou Sheetn que o ThisDocumentVisual Studio gera automaticamente em seu projeto em tempo de design. Essas classes geradas derivam dos itens do host e fornecem um ponto de entrada para seu código. Para obter mais informações, consulte Limitações programáticas de itens de host e controles de host.

Compreender itens de host em projetos de suplemento VSTO

Quando você cria um suplemento VSTO, você não tem acesso a nenhum item de host por padrão. No entanto, você pode gerar Documentitens , Workbooke hospedar no Word e Worksheet Excel VSTO Add-ins em tempo de execução.

Depois de gerar um item de host, você pode executar tarefas como adicionar controles a documentos. Para obter mais informações, consulte Estender documentos do Word e pastas de trabalho do Excel em suplementos VSTO em tempo de execução.

Controles de host

Os controles de host estendem vários objetos de interface do usuário (UI) nos modelos de objeto do Word e do Excel, como Microsoft.Office.Interop.Word.ContentControl objetos e Range objetos.

Os seguintes controles de host estão disponíveis para projetos do Excel:

  • Controle de gráfico

  • ListObject controle

  • Controle NamedRange

  • Controle XmlMappedRange

    Os seguintes controles de host estão disponíveis para projetos do Word:

  • Controle de marcadores

  • Controles de conteúdo

  • Controle XMLNode

  • Controle XMLNodes

    Os controles de host adicionados aos documentos do Office se comportam como os objetos nativos do Office; no entanto, os controles de host têm funcionalidade adicional, incluindo eventos e recursos de vinculação de dados. Por exemplo, quando você deseja capturar os eventos de um objeto nativo Range no Excel, você deve primeiro manipular o evento de alteração da planilha. Em seguida, você deve determinar se a alteração ocorreu dentro do Range. Por outro lado, o NamedRange controle de host tem um Change evento que você pode manipular diretamente.

    A relação entre um item de host e controles de host é semelhante à relação entre um Windows Form e controles do Windows Forms. Assim como você colocaria um controle de caixa de texto em um Windows Form, você colocaria um controle em um NamedRange item de Worksheet host. A ilustração a seguir mostra a relação entre itens de host e controles de host.

    Relationship between host items and host controls

    Você também pode usar controles do Windows Forms em suas soluções do Office adicionando-os diretamente à superfície do documento do Word e do Excel. Para obter mais informações, consulte Visão geral sobre controles do Windows Forms em documentos do Office.

Observação

Não há suporte para a adição de controles de host ou controles do Windows Forms a um subdocumento do Word.

Adicionar controles de host aos seus documentos

Em projetos de nível de documento, você pode adicionar controles de host a seus documentos do Word ou planilhas do Excel em tempo de design das seguintes maneiras:

Controlar o host de nome

Quando você arrasta um controle de host da caixa de ferramentas para o documento, o controle é nomeado automaticamente usando o tipo de controle com um número incremental no final. Por exemplo, os marcadores são nomeados bookmark1, bookmark2 e assim por diante. Se você usar a funcionalidade nativa do Word ou Excel para adicionar o controle, você pode dar-lhe um nome específico no momento em que você criá-lo. Você também pode renomear seus controles alterando o valor da propriedade Name na janela Propriedades .

Observação

Não é possível usar palavras reservadas para nomear controles de host. Por exemplo, se você adicionar um NamedRange controle a uma planilha e alterar o nome para Sistema, ocorrerão erros ao criar o projeto.

Excluir controles de host

Em projetos de nível de documento, você pode excluir controles de host em tempo de design selecionando o controle na planilha do Excel ou no documento do Word e pressionando a tecla Delete . No entanto, você deve usar a caixa de diálogo Definir nome no Excel para excluir NamedRange controles.

Se você adicionar um controle de host a um documento em tempo de design, não deverá removê-lo programaticamente em tempo de execução porque na próxima vez que tentar usar o controle no código, uma exceção será lançada. O Delete método de um controle de host remove somente os controles de host que são adicionados ao documento em tempo de execução. Se você chamar o Delete método de um controle de host que foi criado em tempo de design, uma exceção será lançada.

Por exemplo, o método de um NamedRange somente exclui com êxito o NamedRange Delete se ele foi programaticamente adicionado à planilha, que é conhecido como criar controles de host dinamicamente. Os controles de host criados dinamicamente também podem ser removidos passando o nome do controle para o Remove Controls método da propriedade ou Controls . Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Se os usuários finais excluírem um controle de host do documento em tempo de execução, a solução poderá falhar de maneiras inesperadas. Você pode usar os recursos de proteção de documentos no Word e no Excel para proteger os controles de host de serem excluídos. Para obter mais informações, consulte Exemplos de desenvolvimento do Office e instruções passo a passo.

Observação

Não remova programaticamente controles durante o Shutdown manipulador de eventos do documento ou planilha. Os elementos da interface do usuário não estão mais disponíveis quando o Shutdown evento ocorre. Se você quiser remover controles antes que o aplicativo seja fechado, adicione seu código a outro manipulador de eventos, como BeforeClose ou BeforeSave.

Programa contra eventos de controle de host

Uma maneira de os controles de host estenderem objetos do Office é adicionando eventos. Por exemplo, o objeto no Excel e Bookmark o objeto no Word não têm eventos, mas o Range tempo de execução do Visual Studio Tools for Office estende esses objetos adicionando eventos programáveis. Você pode acessar e codificar esses eventos da mesma forma que acessa eventos de controles no Windows Forms: por meio da lista suspensa de eventos no Visual Basic e da página de propriedades do evento em C#. Para obter mais informações, consulte Demonstra Passo a passo: programa em relação a eventos de um controle NamedRange.

Observação

Você não deve definir a EnableEvents propriedade do Application objeto no Excel como false. Definir essa propriedade como false impede que o Excel gere quaisquer eventos, incluindo os eventos de controles de host.

Conteúdo relacionado