Compartilhar via

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

Itens de host e controles de host são tipos que ajudam a fornecer o modelo de programação para soluções do Office criadas usando as ferramentas de desenvolvimento do Office no Visual Studio. Os itens de host e os 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, assemelha-se mais à 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 Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Itens do anfitrião

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

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

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

    Os itens de host geralmente têm a mesma funcionalidade base que os objetos correspondentes do Office, 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 avançados. 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 lidar com os eventos de um documento específico.

Entender os 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 têm designers que ajudam você a desenvolver sua solução.

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

O Workbook item de host não funciona como um contêiner para controles que têm uma interface do usuário. Em vez disso, o designer para este item de host funciona como uma bandeja de componentes, permitindo que você arraste um componente, como um DataSet, para sua superfície de design. Para obter mais informações, consulte o item host do workbook.

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

Entender os itens do host em projetos de complemento do VSTO

Ao criar um Suplemento VSTO, você não tem acesso a nenhum item de host por padrão. No entanto, você pode gerar Document, Workbook e Worksheet elementos host nos suplementos VSTO do Word e do Excel em tempo de execução.

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

Controles de host

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

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

  • Controle de gráfico

  • Controle ListObject

  • Controle de Intervalo Nomeado

  • Controle XmlMappedRange

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

  • Controle de marcador

  • 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 associação de dados. Por exemplo, quando você deseja capturar os eventos de um objeto nativo Range no Excel, primeiro deve manipular o evento de alteração da planilha. Em seguida, você deve determinar se a alteração ocorreu dentro do Range. Em contraste, o controle do host NamedRange tem um evento Change que você pode manipular diretamente.

    A relação entre um item de host e controles de host é semelhante à relação entre um Formulário do Windows e controles do Windows Forms. Assim como você colocaria um controle de caixa de texto em um Formulário do Windows, você deve colocar o controle NamedRange no item de host Worksheet. A ilustração a seguir mostra a relação entre elementos de host e controles do host.

    Relação entre itens de host e controles de host

    Você também pode usar controles do Windows Forms em suas soluções do Office adicionando-os diretamente à superfície de documentos do Word e do Excel. Para obter mais informações, consulte controles do Windows Forms na visão geral de 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 documentos

Em projetos de nível de documento, você pode adicionar controles de host aos documentos do Word ou planilhas do Excel no momento do design das seguintes maneiras:

Controles do 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 indicadores são nomeados indicador1, indicador2 e assim por diante. Se você usar a funcionalidade nativa do Word ou do Excel para adicionar o controle, poderá dar a ele um nome específico no momento em que o criar. Você também pode renomear seus controles alterando o valor da propriedade Name na janela Propriedades .

Observação

Você não pode 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 compilar o projeto.

Excluir controles de host

Em projetos de nível de documento, você pode excluir controles de host no momento do 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 você tentar usar o controle no código, uma exceção será gerada. O método Delete de um controle de host remove apenas os controles de host que são adicionados ao documento em tempo de execução. Se você chamar o método Delete de um controle de host que foi criado em tempo de design, uma exceção será lançada.

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

Se os usuários finais excluirem 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 os controles programaticamente durante o Shutdown manipulador de eventos do documento ou da planilha. Os elementos da interface do usuário não estão mais disponíveis quando o Shutdown evento ocorre. Se você quiser remover os controles antes do fechamento do aplicativo, 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 Range objeto no Excel e Bookmark o objeto no Word não têm eventos, mas o runtime das Ferramentas do Visual Studio para Office estende esses objetos adicionando eventos programáveis. Você pode acessar e codificar esses eventos da mesma maneira 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 Guia passo a passo: programar contra 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 eventos, incluindo os eventos de controles de host.

Conteúdo relacionado

  • Last updated on