Agregar controles a documentos de Office en tiempo de ejecuciónAdd controls to Office documents at runtime

Puede agregar controles a un documento de Microsoft Office Word y libros de Microsoft Office Excel en tiempo de ejecución.You can add controls to a Microsoft Office Word document and Microsoft Office Excel workbook at runtime. También puede quitarlos en tiempo de ejecución.You can also remove them at runtime. Controles que agregan o quitan en tiempo de ejecución se denominan controles dinámicos.Controls that you add or remove at runtime are called dynamic controls.

Aplicación: la información de este tema se aplica a los proyectos de nivel de documento y a los proyectos de complemento de VSTO para Excel y Word.Applies to: The information in this topic applies to document-level projects and VSTO add-in projects for Excel and Word. 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 tema se describe lo siguiente:This topic describes the following:

Administrar controles en tiempo de ejecución mediante el uso de colecciones de controlesManage controls at runtime by using control collections

Para agregar, obtener o quitar controles en tiempo de ejecución, use métodos auxiliares de ControlCollection y ControlCollection objetos.To add, get, or remove controls at runtime, use helper methods of ControlCollection and ControlCollection objects.

La forma de acceder a estos objetos depende del tipo de proyecto que esté desarrollando:The way that you access these objects depends on the type of project you are developing:

Agregar controlesAdd controls

Los tipos ControlCollection y ControlCollection incluyen métodos auxiliares que puede utilizar para agregar controles host y controles comunes de formularios Windows Forms a documentos y hojas de cálculo.The ControlCollection and ControlCollection types include helper methods that you can use to add host controls and common Windows Forms controls to documents and worksheets. Cada nombre de método tiene el formato Addclase de control, donde clase de control es el nombre de clase del control que quiere agregar.Each method name has the format Addcontrol class, where control class is the class name of the control that you want to add. Por ejemplo, para agregar un control NamedRange al documento, use el método AddNamedRange .For example, to add a NamedRange control to your document, use the AddNamedRange method.

En el ejemplo de código siguiente se agrega un elemento NamedRange a Sheet1 un proyecto de nivel de documento para Excel.The following code example adds a NamedRange to Sheet1 in a document-level project for Excel.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")
Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Controles de acceso y eliminaciónAccess and delete controls

Puede usar el Controls propiedad de un Worksheet o Document para recorrer en iteración todos los controles del documento, incluidos los controles agregados en tiempo de diseño.You can use the Controls property of a Worksheet or Document to iterate through all the controls in your document, including the controls you added at design time. Los controles que agregó en tiempo de diseño también se denominan controles estáticos.Controls that you add at design time are also called static controls.

Puede quitar controles dinámicos mediante una llamada a la Delete método del control o mediante una llamada a la Remove método de cada colección de controles.You can remove dynamic controls by calling the Delete method of the control, or by calling the Remove method of each Controls collection. El siguiente ejemplo de código utiliza el método Remove para quitar un elemento NamedRange de Sheet1 en un proyecto de nivel de documento para Excel.The following code example uses the Remove method to remove a NamedRange from Sheet1 in a document-level project for Excel.

Globals.Sheet1.Controls.Remove("ChartSource")
Globals.Sheet1.Controls.Remove("ChartSource");

No se puede quitar controles estáticos en tiempo de ejecución.You cannot remove static controls at runtime. Si intenta utilizar el Delete o Remove método para quitar un control estático, un CannotRemoveControlException se iniciará.If you try to use the Delete or Remove method to remove a static control, a CannotRemoveControlException will be thrown.

Nota

No quite controles mediante programación en el controlador de eventos Shutdown del documento.Do not programmatically remove controls in the Shutdown event handler of the document. Los elementos de la interfaz de usuario del documento ya no estarán disponibles cuando se produzca el evento Shutdown .The UI elements of the document are no longer available when the Shutdown event is raised. Si quiere quitar controles antes de que se cierre el documento, agregue el código al controlador de eventos de otro evento, como BeforeClose o BeforeSave para Word, o BeforeCloseo BeforeSave para Excel.If you want to remove controls before the document closes, add your code to the event handler for another event, such as BeforeClose or BeforeSave for Word, or BeforeClose, or BeforeSave for Excel.

Agregar controles host a documentosAdd host controls to documents

Cuando agregue controles host a documentos mediante programación, debe proporcionar un nombre que identifique de forma única el control y debe especificar en qué parte del documento se debe agregar el control.When you programmatically add host controls to documents, you must provide a name that uniquely identifies the control, and you must specify where to add the control on the document. Para obtener instrucciones específicas, consulte los temas siguientes:For specific instructions, see the following topics:

Nota

No se ofrecen métodos auxiliares para los siguientes controles host, debido a que estos controles no se pueden agregar mediante programación a documentos: XmlMappedRange, XMLNodey XMLNodes.Helper methods are not provided for the following host controls, because these controls cannot be added programmatically to documents: XmlMappedRange, XMLNode, and XMLNodes.

Agregar controles de formularios Windows Forms a documentosAdd Windows Forms controls to documents

Cuando se agrega mediante programación un control de formularios Windows Forms a un documento, debe proporcionar la ubicación del control y un nombre que lo identifique de forma única.When you programmatically add a Windows Forms control to a document, you must provide the location of the control and a name that uniquely identifies the control. Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime proporciona métodos auxiliares para cada control.The Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime provides helper methods for each control. Estos métodos están sobrecargados para que pueda pasar un intervalo o coordenadas concretas para la ubicación del control.These methods are overloaded so that you can pass either a range or specific coordinates for the location of the control.

Cuando un documento se guarda y se cierra, todos los controles de formularios Windows Forms creados dinámicamente se quitan del documento.When a document is saved and then closed, all dynamically created Windows Forms controls are removed from the document. Puede agregar código a la solución para volver a crear los controles cuando se vuelva a abrir el documento.You can add code to your solution to re-create the controls when the document is reopened. Si crea controles dinámicos de formularios Windows Forms mediante el uso de un complemento de VSTO, los contenedores de ActiveX de los controles se dejan en el documento.If you create dynamic Windows Forms controls by using an VSTO Add-in, the ActiveX wrappers for the controls are left in the document. Para obtener más información, consulte controles dinámicos en documentos de Office se conservan.For more information, see Persist dynamic controls in Office documents.

Nota

Los controles de formularios Windows Forms no se puede agregar mediante programación a documentos protegidos.Windows Forms controls cannot be programmatically added to protected documents. Si desprotege mediante programación un documento de Word o una hoja de cálculo de Excel para agregar un control, debe escribir código adicional para quitar el contenedor de ActiveX del control cuando se cierre el documento.If you programmatically unprotect a Word document or Excel worksheet to add a control, you must write additional code to remove the control's ActiveX wrapper when the document is closed. El contenedor de ActiveX del control no se elimina automáticamente de los documentos protegidos.The control's ActiveX wrapper is not automatically deleted from protected documents.

Agregar controles personalizadosAdd custom controls

Si quiere agregar un elemento Control que no es compatible con los métodos auxiliares disponibles, como un control de usuario personalizado, use los métodos siguientes:If you want to add a Control that is not supported by the available helper methods, such as a custom user control, use the following methods:

  • En Excel, use uno de los métodos AddControl de un objeto ControlCollection .For Excel, use one of the AddControl methods of a ControlCollection object.

  • En Word, use uno de los métodos AddControl de un objeto ControlCollection .For Word, use one of the AddControl methods of a ControlCollection object.

    Para agregar el control, pase el Control, una ubicación para el control y un nombre que identifica de forma única el control a la AddControl método.To add the control, pass the Control, a location for the control, and a name that uniquely identifies the control to the AddControl method. El AddControl método devuelve un objeto que define cómo interactúa el control con el documento o la hoja de cálculo.The AddControl method returns an object that defines how the control interacts with the worksheet or document. El AddControl método devuelve un ControlSite (para Excel) o un ControlSite objeto (para Word).The AddControl method returns a ControlSite (for Excel) or a ControlSite object (for Word).

    En el ejemplo de código siguiente, se muestra cómo utilizar el método AddControl para agregar dinámicamente un control de usuario personalizado a una hoja de cálculo en un proyecto de Excel de nivel de documento.The following code example demonstrates how to use the AddControl method to dynamically add a custom user control to a worksheet in a document-level Excel project. En este ejemplo, el control de usuario se denomina UserControl1y el elemento Range se llama range1.In this example, the user control is named UserControl1, and the Range is named range1. Para usar este ejemplo, ejecútelo desde una clase Sheetn del proyecto.To use this example, run it from a Sheetn class in the project.

    Dim customControl As New UserControl1()
    
    Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
        Me.Controls.AddControl(customControl, range1, "dynamic")
    
    UserControl1 customControl = new UserControl1();
    
    Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
        this.Controls.AddControl(customControl, range1, "dynamic");
    

Utilizar a los miembros de controles personalizadosUse members of custom controls

Después de utilizar uno de los AddControl métodos para agregar un control a una hoja de cálculo o documento, ahora dispone de dos objetos de control diferentes:After using one of the AddControl methods to add a control to a worksheet or document, you now have two different control objects:

  • El objeto Control que representa el control personalizado.The Control that represents the custom control.

  • El ControlSite, OLEObject, o OLEControl objeto que representa el control después de agregarlo a la hoja de cálculo o el documento.The ControlSite, OLEObject, or OLEControl object that represents the control after it was added to the worksheet or document.

    Muchos métodos y propiedades se comparten entre estos controles.Many properties and methods are shared between these controls. Es importante tener acceso a estos miembros a través del control adecuado:It is important that you access these members through the appropriate control:

  • Para acceder a miembros que pertenezcan solo al control personalizado, use Control.To access members that belong only to the custom control, use the Control.

  • Para obtener acceso a miembros compartidos por los controles, use el ControlSite, OLEObject, o OLEControl objeto.To access members that are shared by the controls, use the ControlSite, OLEObject, or OLEControl object.

    Si accede a un miembro compartido desde Control, se podría producir un error sin advertencia ni notificación, o se pueden generar resultados no válidos.If you access a shared member from the Control, it might fail without warning or notification, or it can produce invalid results. Utilice siempre métodos o propiedades de la ControlSite, OLEObject, o OLEControl objeto a menos que el método o propiedad necesaria no está disponible; solo en ese caso debe hacer referencia el Control.Always use methods or properties of the ControlSite, OLEObject, or OLEControl object unless the method or property needed is not available; only then should you reference the Control.

    Por ejemplo, tanto la ControlSite clase y la Control clase tiene un Top propiedad.For example, both the ControlSite class and the Control class have a Top property. Para obtener o establecer la distancia entre la parte superior del control y la parte superior del documento, use la propiedad Top de ControlSite, no la propiedad Top de Control.To get or set the distance between the top of the control and the top of the document, use the Top property of the ControlSite, not the Top property of the Control.

    ' Property is set in relation to the document.
    dynamicControl.Top = 100
    
    ' Property is set in relation to the container control.
    customControl.Top = 100
    
    // Property is set in relation to the document.
    dynamicControl.Top = 100;
    
    // Property is set in relation to the container control.
    customControl.Top = 100;
    

Vea tambiénSee also

Controles en documentos de Office Controls on Office documents
Conservar controles dinámicos en documentos de Office Persist dynamic controls in Office documents
Cómo: agregar controles ListObject a hojas de cálculo How to: Add ListObject controls to worksheets
Cómo: agregar controles NamedRange a hojas de cálculo How to: Add NamedRange controls to worksheets
Cómo: agregar controles Chart a hojas de cálculo How to: Add Chart controls to worksheets
Cómo: agregar controles de contenido a documentos de Word How to: Add content controls to Word documents
Cómo: agregar controles Bookmark a documentos de Word How to: Add Bookmark controls to Word documents
Controles de formularios Windows Forms en información general acerca de documentos de Office Windows Forms controls on Office documents overview
Cómo: agregar controles de formularios Windows Forms a documentos de OfficeHow to: Add Windows Forms controls to Office documents