Limitações programáticas de itens de host e controles de host

  • Artigo

Cada item de host e controle de host é projetado para se comportar como um objeto nativo correspondente do Microsoft Office Word ou Microsoft Office Excel, com funcionalidade adicional. No entanto, há algumas diferenças fundamentais entre o comportamento de itens de host e controles de host e objetos nativos do Office em tempo de execução.

Para obter informações gerais sobre itens de host e controles de host, consulte Visão geral sobre itens de host e controles de host.

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.

Criar itens de host programaticamente

Quando você cria ou abre programaticamente um documento, pasta de trabalho ou planilha em tempo de execução usando o modelo de objeto do Word ou Excel, o item não é um item de host. Em vez disso, o novo objeto é um objeto nativo do Office. Por exemplo, se você usar o Add método para criar um novo documento do Word em tempo de execução, ele será um objeto nativo Document em vez de um item de Document host. Da mesma forma, quando você cria uma nova planilha em tempo de execução usando o Add método, você obtém um objeto nativo Worksheet em vez de um Worksheet item de host.

Em projetos de nível de documento, você não pode criar itens de host em tempo de execução. Os itens de host podem ser criados somente em tempo de design em projetos de nível de documento. Para obter mais informações, consulte Item de host de documento, Item de host de pasta de trabalho e Item de host de planilha.

Em projetos de suplemento VSTO, você pode criar DocumentWorkbook, ou Worksheet hospedar itens em tempo de execução. Para obter mais informações, consulte Estender documentos do Word e pastas de trabalho do Excel em suplementos VSTO em tempo de execução.

Criar controles de host programaticamente

Você pode programaticamente adicionar controles de host a um Document ou Worksheet item de host em tempo de execução. Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Não é possível adicionar controles de host a um nativo Document ou Worksheet.

Observação

Os seguintes controles de host não podem ser adicionados programaticamente a planilhas ou documentos: XmlMappedRange, XMLNodee XMLNodes.

Compreender as diferenças de tipo entre itens de host, controles de host e objetos nativos do Office

Para cada item de host e controle de host, há um objeto nativo subjacente do Microsoft Office Word ou Microsoft Office Excel. Você pode acessar o objeto subjacente usando a propriedade InnerObject do item de host ou controle de host. No entanto, não há nenhuma maneira de converter um objeto nativo do Office para seu item de host correspondente ou controle de host. Se você tentar converter um objeto nativo do Office no tipo de um item de host ou controle de host, um InvalidCastException será lançado.

Há vários cenários em que as diferenças entre os tipos de itens de host e controles de host e os objetos nativos subjacentes do Office podem afetar seu código.

Passar controles de host para métodos e propriedades

No Word, você não pode passar um controle de host para um método ou propriedade que requer um objeto nativo do Word como um parâmetro. Você deve usar a propriedade InnerObject do controle host para retornar o objeto nativo subjacente do Word. Por exemplo, você pode passar um objeto para um Bookmark método passando a InnerObject Bookmark propriedade do controle host para o método.

No Excel, você deve usar a propriedade InnerObject do controle host para passar o controle host para um método ou propriedade quando o método ou propriedade espera o objeto Excel subjacente.

O exemplo a seguir cria um NamedRange controle e o passa para o AutoFill método. O código usa a InnerObject propriedade do intervalo nomeado para retornar o Office Range subjacente que é exigido pelo AutoFill método.

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

Retornar tipos de métodos e propriedades nativos do Office

A maioria dos métodos e propriedades de itens de host retorna o objeto nativo subjacente do Office no qual o item de host é baseado. Por exemplo, a Parent propriedade de um controle de host no Excel retorna um objeto em vez de um NamedRange Worksheet Worksheet item de host. Da mesma forma, a Parent propriedade de um controle de host no Word retorna um objeto em vez de um RichTextContentControl Document Document item de host.

Acessar coleções de controles de host

O Visual Studio Tools for Office runtime não fornece coleções individuais para cada tipo de controle de host. Em vez disso, use a propriedade Controls de um item de host para iterar por todos os controles gerenciados (controles de host e controles do Windows Forms) no documento ou planilha e, em seguida, procure itens que correspondam ao tipo de controle de host no qual você está interessado. O exemplo de código a seguir examina cada controle em um documento do Word e determina se o controle é um Bookmarkarquivo .

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}

Para obter mais informações sobre a propriedade Controls de itens de host, consulte Adicionar controles a documentos do Office em tempo de execução.

Os modelos de objeto do Word e do Excel incluem propriedades que expõem coleções de controles nativos em documentos e planilhas. Não é possível acessar controles gerenciados usando essas propriedades. Por exemplo, não é possível enumerar cada Bookmark controle de host em um documento usando a propriedade de um ou a Bookmarks Bookmarks propriedade de um Document Documentarquivo . Essas propriedades incluem apenas os controles no documento, eles não contêm os Bookmark controles de Bookmark host no documento.

Conteúdo relacionado