Estenda documentos do Word e pastas de trabalho do Excel em suplementos do VSTO em tempo de execução

  • Artigo

Você pode usar um suplemento do VSTO para personalizar documentos do Word e pastas de trabalho do Excel das seguintes formas:

  • Adicione controles gerenciados a qualquer documento ou planilha aberta.

  • Converta um objeto de lista existente em uma planilha do Excel em um ListObject estendido que expõe eventos e pode ser vinculado a dados usando o modelo de vinculação de dados do Windows Forms.

  • Acesse eventos de nível de aplicativo expostos pelo Word e pelo Excel para documentos, pastas de trabalho e planilhas específicos.

    Para usar essa funcionalidade, você gera um objeto em tempo de execução que estende o documento ou pasta de trabalho.

    Aplica-se a: As informações neste artigo se aplicam a projetos de suplemento do VSTO para os seguintes aplicativos: Excel e Word. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Gerar objetos estendidos em suplementos do VSTO

Objetos estendidos são instâncias de tipos fornecidos pelo tempo de execução das Ferramentas do Visual Studio para Office que adicionam funcionalidade a objetos que existem nativamente nos modelos de objeto do Word ou Excel (chamados objetos nativos do Office). Para gerar um objeto estendido para um objeto do Word ou Excel, use o método GetVstoObject. Na primeira vez que você chama o método GetVstoObject para um objeto especificado do Word ou Excel, ele retorna um novo objeto que estende o objeto especificado. Cada vez que você chama o método e especifica o mesmo objeto do Word ou Excel, ele retorna o mesmo objeto estendido.

O tipo do objeto estendido tem o mesmo nome que o tipo do objeto nativo do Office, mas o tipo é definido no namespace Microsoft.Office.Tools.Excel ou Microsoft.Office.Tools.Word. Por exemplo, se você chamar o método GetVstoObject para estender um objeto Document, o método retornará um objeto Document.

Os métodos GetVstoObject devem ser usados principalmente em projetos de suplemento do VSTO. Você também pode usar esses métodos em projetos de nível de documento, mas eles se comportam de forma diferente e têm menos usos.

Para determinar se um objeto estendido já foi gerado para um determinado objeto nativo do Office, use o método HasVstoObject. Para obter mais informações, consulte Determinar se um objeto do Office foi estendido.

Gerar itens de host

Quando você usa o GetVstoObject para estender um objeto de nível de documento (ou seja, um Workbook, Worksheet ou Document), o objeto retornado é chamado de item de host. Um item de host é um tipo que pode conter outros objetos, incluindo outros objetos estendidos e controles. Ele se parece ao tipo correspondente no assembly de interoperabilidade primária do Word ou Excel, mas tem recursos adicionais. Para obter mais informações sobre itens de host, consulte Visão geral de controles de host e itens de host.

Depois de gerar um item de host, você pode usá-lo para adicionar controles gerenciados ao documento, pasta de trabalho ou planilha. Para obter mais informações, consulte Adicionar controles gerenciados a documentos e planilhas.

Para gerar um item de host para um documento do Word

  • O exemplo de código a seguir demonstra como gerar um item de host para o documento ativo.

    if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

Para gerar um item de host para uma pasta de trabalho do Excel

  • O exemplo de código a seguir demonstra como gerar um item de host para a pasta de trabalho ativa.

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

Para gerar um item de host para uma planilha do Excel

  • O exemplo de código a seguir demonstra como gerar um item de host para a planilha ativa em um projeto.

    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

Gerar controles de host ListObject

Quando você usa o método GetVstoObject para estender um ListObject, o método retorna um ListObject. O ListObject tem todas as características do ListObject original. Ele também tem funcionalidade adicional e pode ser vinculado a dados usando o modelo de vinculação de dados do Windows Forms. Para saber mais, consulte Controle ListObject.

Para gerar um controle de host para um ListObject

  • O exemplo de código a seguir demonstra como gerar um ListObject para o primeiro ListObject na planilha ativa em um projeto.

    Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

Adicionar controles gerenciados a documentos e planilhas

Depois de gerar um Document ou Worksheet, você pode adicionar controles ao documento ou planilha que esses objetos estendidos representam. Para adicionar controles, use a propriedade Controls do Document ou Worksheet. Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Você pode adicionar controles do Windows Forms ou controles de host. Um controle de host é um controle fornecido pelas Ferramentas do Visual Studio para Office Runtime que encapsula um controle correspondente no assembly de interoperabilidade primária do Word ou Excel. Um controle de host expõe todo o comportamento do objeto nativo subjacente do Office. Ele também gera eventos e pode ser vinculado a dados usando o modelo de vinculação de dados do Windows Forms. Para obter mais informações, consulte Visão geral de controles de host e itens de host.

Observação

Você não pode adicionar um controle XmlMappedRange a uma planilha ou um controle XMLNode ou XMLNodes a um documento usando um suplemento do VSTO. Esses controles de host não podem ser adicionados programaticamente. Para obter mais informações, consulte Limitações programáticas de itens de host e controles de host.

Persistir e remover controles

Quando você adiciona controles gerenciados a um documento ou planilha, os controles não são persistentes quando o documento é salvo e, em seguida, fechado. Todos os controles de host são removidos para que apenas os objetos nativos subjacentes do Office sejam deixados para trás. Por exemplo, um ListObject torna-se um ListObject. Todos os controles do Windows Forms também são removidos, mas os wrappers ActiveX para os controles são deixados para trás no documento. Você deve incluir código no suplemento do VSTO para limpar os controles ou para recriar os controles na próxima vez que o documento for aberto. Para obter mais informações, consulte Persistir controles dinâmicos em documentos do Office.

Acessar eventos em nível de aplicativo em documentos e pastas de trabalho

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. Por exemplo, o evento DocumentBeforeSave é gerado quando um documento é aberto no Word, mas esse evento é definido na classe Application, em vez da classe Document.

Ao usar apenas objetos nativos do Office no suplemento do VSTO, você deve manipular esses eventos de nível de aplicativo e, em seguida, escrever código adicional para determinar se o documento que gerou o evento é um que você personalizou. 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. Você pode gerar um item de host e depois manipular o evento para esse item de host.

Exemplo que usa objetos nativos do Word

O exemplo de código a seguir demonstra como manipular um evento de nível de aplicativo para documentos do Word. O método CreateDocument cria um novo documento e depois define um manipulador de eventos DocumentBeforeSave que impede que este documento seja salvo. O evento é um evento de nível de aplicativo que é gerado para o objeto Application, e o manipulador de eventos deve comparar o parâmetro Doc com o objeto document1 para determinar se document1 representa o documento salvo.

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Exemplos que usam um item de host

Os exemplos de código a seguir simplificam esse processo manipulando o evento BeforeSave de um item de host Document. O método CreateDocument2 nesses exemplos gera um Document que estende o objeto document2 e depois define um manipulador de eventos BeforeSave que impede que o documento seja salvo. O manipulador de eventos é chamado somente quando document2 é salvo e pode cancelar a ação de salvar sem fazer nenhum trabalho extra para verificar qual documento foi salvo.

O exemplo de código a seguir demonstra essa tarefa.

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Determinar se um objeto do Office foi estendido

Para determinar se um objeto estendido já foi gerado para um determinado objeto nativo do Office, use o método HasVstoObject. Esse método retornará true se um objeto estendido já tiver sido gerado.

Use o método Globals.Factory.HasVstoObject. Passe o objeto nativo do Word ou do Excel, como um Document ou Worksheet que você deseja testar se é um objeto estendido.

O método HasVstoObject é útil quando você deseja executar código somente quando um objeto do Office especificado tem um objeto estendido. Por exemplo, se você tiver um suplemento do VSTO do Word que manipula o evento DocumentBeforeSave para remover controles gerenciados de um documento antes que ele seja salvo, use o método HasVstoObject para determinar se o documento foi estendido. Se o documento não tiver sido estendido, ele não poderá ter controles gerenciados e o manipulador de eventos poderá retornar sem tentar limpar os controles no documento.

Conteúdo relacionado