Demonstra Passo a passo: Adicionar controles a um documento em tempo de execução em um suplemento em nível de aplicativo

Artigo
08/08/2011

Você pode adicionar controles para qualquer documento aberto do Word de Microsoft Office usando um suplemento em nível de aplicativo. Este passo a passo demonstra como usar a faixa de opções para permitir que os usuários adicionem uma Button ou RichTextContentControl a um documento.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de aplicativo para Word 2007 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

This walkthrough illustrates the following tasks:

Criando um novo Word add-in do projeto.
Fornecendo uma interface de usuário (UI) para adicionar controles ao documento.
Adicionar controles ao documento em tempo de execução.
Removendo os controles do documento.

Observação
Seu computador pode mostrar nomes ou locais diferentes para alguns dos elementos da interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos. Para obter mais informações, consulte Configurações do Visual Studio.

Pré-requisitos

You need the following components to complete this walkthrough:

Uma edição do Visual Studio 2010 que inclua as ferramentas de desenvolvedor do Microsoft Office. Para obter mais informações, consulte [Configurando um computador para desenvolver soluções do Office](bb398242\(v=vs.100\).md).

Word 2007 ou Word 2010.

Criar um novo Word Add-in do projeto

Comece criando um projeto de suplemento do Word.

Para criar um novo Word add-in do projeto

Crie um projeto de nível de aplicativo para o Word com o nome WordDynamicControls. For more information, see Como: Criar projetos do Office em Visual Studio.
Se os destinos do projeto de .NET Framework 4, adicione uma referência ao assembly Microsoft.Office.Tools.Word.v4.0.Utilities.dll. Esta referência é necessário para adicionar um controle Windows Forms por programação o documento posteriormente nesta explicação passo a passo.

Fornecendo uma interface de usuário para adicionar controles a um documento.

Adicione uma guia personalizada à Faixa de opções no Word. Os usuários podem selecionar as caixas de seleção na guia para adicionar controles a um documento.

Para fornecer uma interface de usuário para adicionar controles a um documento

On the Project menu, click Add New Item.
No Add New Item caixa de diálogo, selecione a faixa de opções (Visual Designer).
Alterar o nome da nova faixa de opções para MyRibbone clique em Add.

O MyRibbon.cs ou MyRibbon.vb abre no Designer de faixa de opções de arquivo e exibe uma guia de padrão e o grupo.
No Designer de faixa de opções, clique na Grupo1 grupo.
No Propriedades janela, alterar o rótulo propriedade para Grupo1 para adicionar controles.
Do Controles de faixa de opções do Office guia da Toolbox, arraste um caixa de seleção controlar até Grupo1.
Clique em CheckBox1 para selecioná-lo.
No Propriedades janela, altere as propriedades a seguir.

Property

Value

Name

addButtonCheckBox

Label

Add Button
Adicionar uma segunda caixa de seleção para Grupo1e altere as propriedades a seguir.

Property

Value

Name

addRichTextCheckBox

Label

Adicionar o controle de Rich Text
No Designer de faixa de opções, clique duas vezes no botão Adicionar.

O Click o manipulador de eventos da caixa de seleção Adicionar botão abre no Editor de código.
Retornar para o Designer de faixa de opções e clique duas vezes em Adicionar controle de Rich Text.

O Click o manipulador de eventos da caixa de seleção Adicionar controle de Rich Text é aberta no Editor de código.

Property	Value
Name	addButtonCheckBox
Label	Add Button

Property	Value
Name	addRichTextCheckBox
Label	Adicionar o controle de Rich Text

Posteriormente nesta explicação passo a passo, você irá adicionar código para esses manipuladores de eventos para adicionar e remover os controles no documento ativo.

Adicionando e removendo os controles no documento ativo

O código de add-in, você deve converter o documento ativo em um Microsoft.Office.Tools.Word.Document o item de host antes de adicionar um controle. Em Visual Studio Tools for Office soluções, gerenciadas controles podem ser adicionados somente aos itens de host, que atuam como recipientes para controles. No nível do aplicativo add-in de projetos, itens de host podem ser criados em tempo de execução usando o GetVstoObject método.

Adicionar métodos para a ThisAddIn classe que pode ser chamado para adicionar ou remover um Button ou RichTextContentControl no documento ativo. Posteriormente neste passo a passo, você chamará esses métodos de Click manipuladores de eventos das caixas de seleção na faixa de opções.

Para adicionar e remover os controles no documento ativo

Em Solution Explorer, clique duas vezes em ThisAddIn.cs ou ThisAddIn. vb para abrir o arquivo no Editor de código.

Add the following code to the ThisAddIn class. Esse código declara Button e RichTextContentControl objetos que representam os controles que serão adicionados ao documento.

Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
Private richTextControl As RichTextContentControl = Nothing

private Microsoft.Office.Tools.Word.Controls.Button button = null;
private RichTextContentControl richTextControl = null;

Adicione o seguinte método para o ThisAddIn classe. Quando o usuário clica a caixa de seleção do botão Adicionar na faixa de opções, este método adiciona uma Button à seleção atual no documento, se a caixa de seleção estiver selecionada ou remove o Button se a caixa de seleção está desmarcada.

Friend Sub ToggleButtonOnDocument()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyButton"

    If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            button = vstoDocument.Controls.AddButton( _
                selection.Range, 100, 30, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleButtonOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    string name = "MyButton";

    if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
    {
        Word.Selection selection = this.Application.Selection;
        if (selection != null && selection.Range != null)
        {
            button = vstoDocument.Controls.AddButton(
                selection.Range, 100, 30, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

Adicione o seguinte método para o ThisAddIn classe. Quando o usuário clica a caixa de seleção Adicionar controle de Rich Text na faixa de opções, este método adiciona uma RichTextContentControl à seleção atual no documento, se a caixa de seleção estiver selecionada ou remove o RichTextContentControl se a caixa de seleção está desmarcada.

Friend Sub ToggleRichTextControlOnDocument()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyRichTextBoxControl"

    If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                    selection.Range, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleRichTextControlOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    string name = "MyRichTextBoxControl";

    if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
    {
        Word.Selection selection = this.Application.Selection;
        if (selection != null && selection.Range != null)
        {
            richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                selection.Range, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

A remoção do botão controle quando o documento for salvo.

Controles Windows Forms não são mantidas quando o documento é salvo e, em seguida, fechado. Entretanto, um wrapper de ActiveX para cada controle permanecerá no documento e a borda desse wrapper pode ser vista pelos usuários finais, quando o documento for reaberto. Há várias maneiras para limpar os controles Windows Forms criados dinamicamente em suplementos. Esta explicação passo a passo, você remove programaticamente o Button controlar quando o documento for salvo.

Para remover o controle de botão quando o documento for salvo.

No arquivo de código ThisAddIn.cs ou ThisAddIn. vb, adicione o seguinte método para o ThisAddIn classe. Esse método é um manipulador de eventos para o DocumentBeforeSave de evento. Se o documento salvo tem uma Document obtém o item de host de item de host que está associado ele, o manipulador de eventos e remove o Button de controle, se ele existe.

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim isExtended As Boolean = Doc.HasVstoObject()

    If isExtended Then
        ' Use the following line of code in projects that target the .NET Framework 4.
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        ' In projects that target the .NET Framework 3.5, use the following line of code.
        ' Dim vstoDocument As Document = Doc.GetVstoObject()

        If vstoDocument.Controls.Contains(button) Then
            vstoDocument.Controls.Remove(button)
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
        End If
    End If
End Sub

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    // Use the following line of code in projects that target the .NET Framework 4.
    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // bool isExtended = Doc.HasVstoObject();

    if (isExtended)
    {
        // Use the following line of code in projects that target the .NET Framework 4.
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

        // In projects that target the .NET Framework 3.5, use the following line of code.
        // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();

        if (vstoDocument.Controls.Contains(button))
        {
            vstoDocument.Controls.Remove(button);
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
        }
    }
}

No C#, adicione o seguinte código para o ThisAddIn_Startup manipulador de eventos. Esse código é necessária em C# para conectar-se a Application_DocumentBeforeSave o manipulador de eventos com o DocumentBeforeSave de evento.
```
this.Application.DocumentBeforeSave += 
    new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
    Application_DocumentBeforeSave);
```

Adicionando e removendo os controles quando o usuário clica as caixas de seleção na faixa de opções

Finalmente, modificar o Click manipuladores de eventos das caixas de seleção que você adicionou à Faixa de opções para adicionar ou remover controles em um documento.

Para adicionar ou remover controles quando o usuário clica as caixas de seleção na faixa de opções

No arquivo de código MyRibbon.cs ou MyRibbon.vb, substitua o gerado addButtonCheckBox_Click e addRichTextCheckBox_Click manipuladores de eventos com o código a seguir. Esse código redefine esses manipuladores de eventos para chamar o ToggleButtonOnDocument e ToggleRichTextControlOnDocument métodos que você adicionou para a ThisAddIn classe anteriormente na explicação passo a passo.

Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
    Globals.ThisAddIn.ToggleButtonOnDocument()
End Sub

Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
    Globals.ThisAddIn.ToggleRichTextControlOnDocument()
End Sub

private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleButtonOnDocument();
}

private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleRichTextControlOnDocument();
}

Teste da solução

Adicione controles a um documento selecionando-os na guia personalizada na faixa de opções. Quando você salva o documento, o Button controle é removido.

Para testar a solução.

Pressione F5 para executar seu projeto.
No documento ativo, pressione ENTER várias vezes para adicionar novos parágrafos vazios no documento.
Selecione o primeiro parágrafo.
Clique o Add-Ins guia.
No Adicionar controles de de grupo, clique em Botão Adicionar.

Aparece um botão no primeiro parágrafo.
Selecione o último parágrafo.
No Adicionar controles de de grupo, clique em Adicionar controle de Rich Text.

Um controle de conteúdo de rich text é adicionado para o último parágrafo.
Save the document.

O botão é removido do documento.

Próximas etapas

Você pode aprender mais sobre os controles no nível do aplicativo add-ins com estes tópicos:

Para obter um exemplo que demonstra como adicionar muitos outros tipos de controles a um documento em tempo de execução e recriar os controles quando o documento for reaberto, consulte o Word Add-In dinâmico controles amostra em Exemplos de desenvolvimento do Office e Walkthroughs.
Para uma explicação passo a passo que demonstra como adicionar controles a uma planilha usando um suplemento em nível de aplicativo para o Excel, consulte Demonstra Passo a passo: Adicionar controles a uma planilha em tempo de execução em um projeto de nível de aplicativo.

Consulte também

Compartilhar via