Estendendo os documentos do Word e pastas de trabalho do Excel em suplementos de nível de aplicativo em tempo de execução

Artigo
02/25/2013

Você pode usar um suplemento ao nível para personalizar as seguintes maneiras documentos e pastas de trabalho do Excel do word:

Adicionar controles gerenciados para qualquer documento aberto ou planilha.
Converter um objeto de lista existente em uma planilha do excel a ListObject estendido que expõe eventos e pode ser associada a dados usando o modelo de associação de dados dos formulários do windows.
Acessar os eventos em nível de aplicativo que são expostos por palavra e Excel para documentos específicos, pastas de trabalho e, planilhas.

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

Se aplica: as informações contidas em este tópico aplica projetos no nível para os seguintes aplicativos: Excel 2010; palavras 2010.Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Criando objetos estendidos em suplementos

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

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

Os métodos de GetVstoObject pretendem ser usados principalmente em projetos de aplicativo.Você também pode usar esses métodos em projetos da nível de aplicativo, mas se comportam de maneira diferente, e têm-se menos usa.

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

Gerando itens host

Quando você usar GetVstoObject para estender um objeto de um documento nível (isto é, Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet, ou Microsoft.Office.Interop.Word.Document), o objeto retornado é chamado um item host.Um item host é um tipo que pode conter outros objetos, incluindo outros objetos e controles estendidos.Lembra o tipo correspondente no assembly de interoperabilidade primário do word ou o excel, mas tem recursos adicionais.Para obter mais informações sobre os itens host, consulte Itens de host e visão geral sobre controles de Host.

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

Para gerar um item de host de um documento do word

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

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

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 host para uma pasta de trabalho do Excel

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

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
    Globals.ThisAddIn.Application.ActiveWorkbook
If NativeWorkbook IsNot Nothing Then
    Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

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 host para uma planilha do excel

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

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

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

Gerando controles host de ListObject

Quando você usa o método de GetVstoObject para estender Microsoft.Office.Interop.Excel.ListObject, o método retorna Microsoft.Office.Tools.Excel.ListObject.Microsoft.Office.Tools.Excel.ListObject tem todos os recursos de Microsoft.Office.Interop.Excel.ListObjectoriginal, mas também possui funcionalidades adicionais, como a capacidade de ser associado a dados usando o modelo de associação de dados dos formulários do windows.Para obter mais informações, consulte Controle de ListObject.

Para gerar um controle do host para um ListObject

O exemplo de código a seguir demonstra como gerar Microsoft.Office.Tools.Excel.ListObject para primeiro Microsoft.Office.Interop.Excel.ListObject na planilha ativa em um projeto.

Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
        Globals.Factory.GetVstoObject(listObject)
End If

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);
}

Adicionando controles gerenciados para documentos e a planilhas

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

Você pode adicionar controles de formulários do windows ou controles host.Um controle do host é fornecido por um controle Visual Studio Tools for Office Runtime que envolve um controle correspondente no assembly principal interoperabilidade do word ou Excel.Um controle host expõem qualquer comportamento do objeto subjacente do Office de nativo, mas também gera eventos e podem ser associados a dados usando o modelo de associação de dados dos formulários do windows.Para obter mais informações, consulte Itens de host e visão geral sobre controles de Host.

Observação
Você não pode adicionar um controle de XmlMappedRange a uma planilha, ou um controle de XMLNode ou de XMLNodes a um documento, usando um suplemento.Esses controles host não podem ser adicionados por meio de programação.Para obter mais informações, consulte Limitações de programação de itens de Host e controles de Host.

Gravando e removendo controles

Quando você adiciona controles gerenciados a um documento ou a uma planilha, os controles não são persistentes quando o documento é salvo e fechado em.Todos os controles de host são removidos de modo que somente objetos subjacentes do Office de ambos são deixados code-behind.Por exemplo, Microsoft.Office.Tools.Excel.ListObject transformações Microsoft.Office.Interop.Excel.ListObject.Todos os controles de formulários do windows são removidos também, mas os wrappers ActiveX para os controles são deixados code-behind no documento.Você deve incluir o código no suplemento para limpar os controles, ou para recriar os controles na próxima vez que o documento está aberto.Para obter mais informações, consulte Persisting controles dinâmicos em documentos do Office.

Acessando eventos no Nível em documentos e em pastas de trabalho

Alguns documento, pasta de trabalho, e eventos da planilha nos modelos de objeto nativos de palavras Excel e são gerados apenas a nível do aplicativo.Por exemplo, o evento de DocumentBeforeSave é gerado quando um documento é aberto em palavras, mas este evento é definido na classe de Microsoft.Office.Interop.Word.Application , em vez da classe de Microsoft.Office.Interop.Word.Document .

Quando você usa apenas Office nativo objetos no suplemento, você deve manipular estes eventos de aplicativo e escrever código adicional para determinar se o documento que gera o evento é um que você personalizou.Os itens host fornecem esses eventos no nível do documento, de modo que é mais fácil manipular os eventos para um documento específico.Você pode gerar um item host e então manipular o evento para aquele item host.

O exemplo que usa palavra nativos objetos

O exemplo de código a seguir mostra como manipular um evento no nível para documentos do word.O método de CreateDocument cria um novo documento, e então define um manipulador de eventos de DocumentBeforeSave que impede este documento ser salvo.Porque este é um evento no nível que é gerado para o objeto de Microsoft.Office.Interop.Word.Application , o manipulador de eventos deve comparar o parâmetro de Doc com o objeto de document1 para determinar se document1 representa o documento salvo.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

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 host

Os exemplos de código simplificam o processo manipulando o evento de BeforeSave de um item de host de Microsoft.Office.Tools.Word.Document .O método de CreateDocument2 em este exemplo produz Microsoft.Office.Tools.Word.Document que estende o objeto de document2 , e então define um manipulador de eventos de BeforeSave que impede o documento ser salvo.Como este manipulador de eventos é chamado somente quando document2 é salvo, o manipulador de eventos pode cancelar a ação de salvar sem fazer qualquer trabalho adicional para verificar se o documento foi salvo.

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

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

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;
}

Determinando se um objeto do Office foi estendido

Para determinar se um objeto estendido já foi gerado para um objeto do Office de nativo de detalhe, use o método de HasVstoObject .Esse método retorna true se um objeto estendido já foi gerado; caso contrário, retornará false.

Use o método Globals.Factory.HasVstoMethod.Passe para o objeto nativo do word ou Excel, como Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet, que você deseja testar um objeto estendido.

O método de HasVstoObject é útil quando você deseja executar o código somente quando um objeto especificado do Office tem um objeto estendido.Por exemplo, se você tiver um suplemento a palavra que manipula o evento de DocumentBeforeSave para remover os controles gerenciados de um documento antes de ser salvo, você pode usar o método de HasVstoObject para determinar se o documento foi estendido.Se o documento não foi estendido, não pode conter controles gerenciados, e portanto o manipulador de eventos pode simplesmente retornar sem tentar limpar controles no documento.

Consulte também

Conceitos

Adicionar controles a documentos do Office em tempo de execução

Itens de host e visão geral sobre controles de Host

Outros recursos

Os suplementos de nível de aplicativo de programação.

Passo a passo e amostras de desenvolvimento do office

Compartilhar via