Tutorial: Agregar controles a un documento en tiempo de ejecución en un complemento de VSTOWalkthrough: Adding Controls to a Document at Run Time in a VSTO Add-In

Puede agregar controles a cualquier documento abierto de Microsoft Office Word usando un complemento de VSTO.You can add controls to any open Microsoft Office Word document by using an VSTO Add-in. Este tutorial muestra cómo usar la cinta para permitir a los usuarios agregar un Button o un RichTextContentControl a un documento.This walkthrough demonstrates how to use the Ribbon to enable users to add a Button or a RichTextContentControl to a document.

Aplicación: la información de este tema se aplica a los proyectos de complemento de VSTO para Word 2010.Applies to: The information in this topic applies to VSTO Add-in projects for Word 2010. Para obtener más información, consulte Características disponibles por aplicación y tipo de proyecto de Office.For more information, see Features Available by Office Application and Project Type.

En este tutorial se muestran las tareas siguientes:This walkthrough illustrates the following tasks:

  • Crear un nuevo proyecto de complemento de VSTO de Word.Creating a new Word VSTO Add-in project.

  • Proporcionar una interfaz de usuario (UI) para agregar controles al documento.Providing a user interface (UI) to add controls to the document.

  • Agregar controles al documento en tiempo de ejecución.Adding controls to the document at run time.

  • Quitar controles del documento.Removing controls from the document.

    Nota

    Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obtener más información, vea Personalizar el IDE.For more information, see Personalizing the IDE.

Requisitos previosPrerequisites

Necesita los componentes siguientes para completar este tutorial:You need the following components to complete this walkthrough:

Crear un nuevo proyecto de complemento de WordCreating a New Word Add-in Project

Empiece creando un proyecto de complemento de VSTO de Word.Start by creating a Word VSTO Add-in project.

Para crear un nuevo proyecto de complemento de VSTO de WordTo create a new Word VSTO Add-in project

  1. Cree un proyecto de complemento de VSTO de Word con el nombre WordDynamicControls.Create an VSTO Add-in project for Word with the name WordDynamicControls. Para obtener más información, consulta How to: Create Office Projects in Visual Studio.For more information, see How to: Create Office Projects in Visual Studio.

  2. Agregue una referencia al ensamblado Microsoft.Office.Tools.Word.v4.0.Utilities.dll .Add a reference to the Microsoft.Office.Tools.Word.v4.0.Utilities.dll assembly. Esta referencia es obligatoria para agregar mediante programación un control de Windows Forms al documento más adelante en este tutorial.This reference is required to programmatically add a Windows Forms control to the document later in this walkthrough.

Proporcionar una interfaz de usuario para agregar controles a un documentoProviding a UI to Add Controls to a Document

Agregue una pestaña personalizada a la cinta en Word.Add a custom tab to the Ribbon in Word. Los usuarios pueden seleccionar las casillas en la pestaña para agregar controles a un documento.Users can select check boxes on the tab to add controls to a document.

Para proporcionar una interfaz de usuario para agregar controles a un documentoTo provide a UI to add controls to a document

  1. En el menú Proyecto , haga clic en Agregar nuevo elemento.On the Project menu, click Add New Item.

  2. En el cuadro de diálogo Agregar nuevo elemento , seleccione Cinta (diseñador visual).In the Add New Item dialog box, select Ribbon (Visual Designer).

  3. Cambie el nombre de la nueva cinta de opciones por MyRibbony haga clic en Agregar.Change the name of the new Ribbon to MyRibbon, and click Add.

    El archivo MyRibbon.cs o MyRibbon.vb se abre en el diseñador de la cinta de opciones y muestra una ficha y un grupo predeterminados.The MyRibbon.cs or MyRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.

  4. En el diseñador de la cinta, haga clic en el grupo group1 .In the Ribbon Designer, click the group1 group.

  5. En la ventana Propiedades , cambie la propiedad Etiqueta para group1 a Agregar controles.In the Properties window, change the Label property for group1 to Add Controls.

  6. Desde la pestaña Controles de la cinta de Office del Cuadro de herramientas, arrastre un control CheckBox a group1.From the Office Ribbon Controls tab of the Toolbox, drag a CheckBox control onto group1.

  7. Haga clic en CheckBox1 para seleccionarlo.Click CheckBox1 to select it.

  8. En la ventana Propiedades , cambie las siguientes propiedades:In the Properties window, change the following properties.

    PropertyProperty ValorValue
    NameName addButtonCheckBoxaddButtonCheckBox
    EtiquetaLabel Botón AgregarAdd Button
  9. Agregue una segunda casilla a group1, y, a continuación, cambie las siguientes propiedades.Add a second check box to group1, and then change the following properties.

    PropertyProperty ValorValue
    NameName addRichTextCheckBoxaddRichTextCheckBox
    LabelLabel Agregar control de texto enriquecidoAdd Rich Text Control
  10. En el diseñador de la cinta, haga doble clic en Agregar botón.In the Ribbon Designer, double-click Add Button.

    El controlador de eventos Click de la casilla Agregar botón se abre en el Editor de código.The Click event handler of the Add Button check box opens in the Code Editor.

  11. Vuelva al diseñador de la cinta y haga doble clic en Agregar control de texto enriquecido.Return to the Ribbon Designer, and double-click Add Rich Text Control.

    El controlador de eventos Click de la casilla Agregar control de texto enriquecido se abre en el Editor de código.The Click event handler of the Add Rich Text Control check box opens in the Code Editor.

    Más adelante en este tutorial, agregará código a estos controladores de eventos para agregar y quitar controles en el documento activo.Later in this walkthrough, you will add code to these event handlers to add and remove controls on the active document.

Agregar y quitar controles en el documento activoAdding and Removing Controls on the Active Document

En el código de complemento de VSTO, debe convertir el documento activo en un Documentde para poder agregar un control.In the VSTO Add-in code, you must convert the active document into a Documenthost item before you can add a control. En soluciones de Office, pueden agregarse controles administrados solo a los elementos host, que actúan como contenedores para los controles.In Office solutions, managed controls can be added only to host items, which act as containers for the controls. En los proyectos de complemento de VSTO, pueden crear elementos host en tiempo de ejecución mediante el método GetVstoObject.In VSTO Add-in projects, host items can be created at run time by using the GetVstoObject method.

Agregue métodos a la clase ThisAddIn que se puedan llamar para agregar o quitar un Button o RichTextContentControl en el documento activo.Add methods to the ThisAddIn class that can be called to add or remove a Button or RichTextContentControl on the active document. Más adelante en este tutorial, llamará a estos métodos desde los controladores de eventos Click de las casillas en la cinta.Later in this walkthrough, you will call these methods from the Click event handlers of the check boxes on the Ribbon.

Para agregar y quitar controles en el documento activoTo add and remove controls on the active document

  1. En el Explorador de soluciones, haga doble clic en ThisAddIn.cs o ThisAddIn.vb para abrir el archivo en el Editor de código.In Solution Explorer, double-click ThisAddIn.cs or ThisAddIn.vb to open the file in the Code Editor.

  2. Agregue el código siguiente a la clase ThisAddIn .Add the following code to the ThisAddIn class. Este código declara los objetos Button y RichTextContentControl que representan los controles que se agregarán al documento.This code declares Button and RichTextContentControl objects that represent the controls that will be added to the document.

    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;
    
  3. Agregue el método siguiente a la clase ThisAddIn.Add the following method to the ThisAddIn class. Cuando el usuario hace clic en la casilla Agregar botón en la cinta, este método agrega un Button a la selección actual en el documento si la casilla está activada, o quita el Button si la casilla está desactivada.When the user clicks the Add Button check box on the Ribbon, this method adds a Button to the current selection on the document if the check box is selected, or removes the Button if the check box is cleared.

    Friend Sub ToggleButtonOnDocument()
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
    
        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()
    {
        Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    
    
        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);
        }
    }
    
  4. Agregue el método siguiente a la clase ThisAddIn.Add the following method to the ThisAddIn class. Cuando el usuario hace clic en la casilla Agregar control de texto enriquecido en la cinta, este método agrega un RichTextContentControl a la selección actual en el documento si la casilla está activada, o quita el RichTextContentControl si la casilla está desactivada.When the user clicks the Add Rich Text Control check box on the Ribbon, this method adds a RichTextContentControl to the current selection on the document if the check box is selected, or removes the RichTextContentControl if the check box is cleared.

    Friend Sub ToggleRichTextControlOnDocument()
    
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
    
        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()
    {
    
        Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    
    
        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);
        }
    }
    

Quitar el control Button cuando el documento se guardaRemoving the Button Control When the Document is Saved

Los controles de formularios de Windows Forms no se conservan cuando se guarda y se cierra el documento.Windows Forms controls are not persisted when the document is saved and then closed. Sin embargo, un contenedor de ActiveX para cada control permanece en el documento, y el borde de este contenedor lo pueden ver los usuarios finales cuando se vuelve a abrir el documento.However, an ActiveX wrapper for each control remains in the document, and the border of this wrapper can be seen by end users when the document is reopened. Hay varias maneras de limpiar los controles de formularios de Windows Forms creados dinámicamente en complementos de VSTO. En este tutorial, se quita mediante programación el control Button cuando se guarda el documento.There are several ways to clean up dynamically created Windows Forms controls in VSTO Add-ins. In this walkthrough, you programmatically remove the Button control when the document is saved.

Para quitar el control Button cuando el documento se guardaTo remove the Button control when the document is saved

  1. En el archivo de código ThisAddIn.cs o ThisAddIn.vb, agregue el código siguiente a la clase ThisAddIn .In the ThisAddIn.cs or ThisAddIn.vb code file, add the following method to the ThisAddIn class. Este método es un controlador de eventos para el evento <xref:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave> .This method is an event handler for the <xref:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave> event. Si el documento tiene un elemento host Document que está asociado a él, el controlador de eventos obtiene el elemento host y quita el control Button , si existe.If the saved document has a Document host item that is associated with it, the event handler gets the host item and removes the Button control, if it exists.

    Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
        ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
    
        Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)
    
    
        If isExtended Then
            Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)
    
    
            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)
    {
        bool isExtended = Globals.Factory.HasVstoObject(Doc);
    
    
        if (isExtended)
        {
    
            Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
    
            if (vstoDocument.Controls.Contains(button))
            {
                vstoDocument.Controls.Remove(button);
                Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
            }
        }
    }
    
  2. En C#, agregue el código siguiente al controlador de eventos ThisAddIn_Startup .In C#, add the following code to the ThisAddIn_Startup event handler. Este código es necesario en C# para conectar el controlador de eventos Application_DocumentBeforeSave con el evento <xref:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave> .This code is required in C# to connect the Application_DocumentBeforeSave event handler with the <xref:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave> event.

    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
    

Agregar y quitar controles cuando el usuario hace clic en las casillas en la cinta de opcionesAdding and Removing Controls When the User Clicks the Check Boxes on the Ribbon

Por último, modifique los controladores del evento Click de las casillas que agregó a la cinta para agregar o quitar controles del documento.Finally, modify the Click event handlers of the check boxes you added to the Ribbon to add or remove controls on the document.

Para agregar y quitar controles cuando el usuario hace clic en las casillas en la cinta de opcionesTo add or remove controls when the user clicks the check boxes on the Ribbon

  1. En el archivo de código MyRibbon.cs o MyRibbon.vb, reemplace los controladores de evento addButtonCheckBox_Click y addRichTextCheckBox_Click con el código siguiente.In the MyRibbon.cs or MyRibbon.vb code file, replace the generated addButtonCheckBox_Click and addRichTextCheckBox_Click event handlers with the following code. Este código vuelve a definir estos controladores de eventos para llamar a los métodos ToggleButtonOnDocument y ToggleRichTextControlOnDocument que ha agregado a la clase ThisAddIn anteriormente en este tutorial.This code redefines these event handlers to call the ToggleButtonOnDocument and ToggleRichTextControlOnDocument methods that you added to the ThisAddIn class earlier in this walkthrough.

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

Probar la soluciónTesting the Solution

Agregue controles a un documento seleccionándolos en la pestaña personalizada de la cinta.Add controls to a document by selecting them from the custom tab on the Ribbon. Al guardar el documento, el control Button se quita.When you save the document, the Button control is removed.

Para probar la solución.To test the solution.

  1. Presione F5 para ejecutar el proyecto.Press F5 to run your project.

  2. En el documento activo, presione ENTRAR varias veces para agregar los nuevos párrafos vacíos al documento.In the active document, press ENTER several times to add new empty paragraphs to the document.

  3. Seleccione el primer párrafo.Select the first paragraph.

  4. Haga clic en la pestaña Complementos .Click the Add-Ins tab.

  5. En el grupo Agregar controles , haga clic en Agregar botón.In the Add Controls group, click Add Button.

    Se mostrará un botón en el primer párrafo.A button appears in the first paragraph.

  6. Seleccione el último párrafo.Select the last paragraph.

  7. En el grupo Agregar controles , haga clic en Agregar control de texto enriquecido.In the Add Controls group, click Add Rich Text Control.

    Se agregará un control de contenido de texto enriquecido al último párrafo.A rich text content control is added to the last paragraph.

  8. Guarde el documento.Save the document.

    El botón se quitará del documento.The button is removed from the document.

Pasos siguientesNext Steps

Puede obtener más información acerca de los controles en los complementos de VSTO en estos temas:You can learn more about controls in VSTO Add-ins from these topics:

Vea tambiénSee Also

Soluciones de Word Word Solutions
Agregar controles a documentos de Office en tiempo de ejecución Adding Controls to Office Documents at Run Time
Guardar controles dinámicos en documentos de Office Persisting Dynamic Controls in Office Documents
Cómo: agregar controles a documentos de Office de Windows Forms How to: Add Windows Forms Controls to Office Documents
Cómo: agregar controles de contenido a documentos de Word How to: Add Content Controls to Word Documents
Extender documentos de Word y libros de Excel en complementos VSTO en tiempo de ejecuciónExtending Word Documents and Excel Workbooks in VSTO Add-ins at Run Time