Compartir a través de

Agregar controles a documentos de Office en tiempo de ejecución

  • Artículo

Puede agregar controles a un documento de Microsoft Office Word y a un libro de Microsoft Office Excel en tiempo de ejecución.También puede quitarlos en tiempo de ejecución.Los Controles que se agregan o quitan en tiempo de ejecución se denominan controles dinámicos.

Se aplica a: La información de este tema se aplica a los proyectos de nivel de documento y los proyectos de nivel de aplicación para las siguientes aplicaciones: Excel 2013 y Excel 2010; Word 2013 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Este tema describe el siguiente:

  • Administrar controles en tiempo de ejecución con colecciones de controles.

  • Agregar controles host a documentos.

  • Agregar controles de formularios Windows Forms a documentos.

vínculo a vídeo Dispone de una demostración en vídeo relacionada en How Do I: Add Controls to a Document Surface at Runtime?.

Administrar controles en tiempo de ejecución con colecciones de controles

Para agregar, obtener o quitar controles de un documento en tiempo de ejecución, use métodos auxiliares de los objetos Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection.

La forma en que se obtiene acceso a estos objetos depende del tipo de proyecto que se está desarrollando:

x97a5x3s.collapse_all(es-es,VS.110).gifAgregar controles

Los métodos auxiliares de inclusión de los tipos Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection que puede utilizar para agregar controles host y Windows Forms comunes controlan los documentos y hojas de cálculo.Cada nombre de método tiene el formato Addclase de control, donde es el nombre de clase clase de control del control que desea agregar.Por ejemplo, para agregar un control NamedRange al documento, se utiliza el método AddNamedRange.

En el siguiente ejemplo de código se agrega un NamedRange al objeto Sheet1 en un proyecto en el nivel del documento para 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");

x97a5x3s.collapse_all(es-es,VS.110).gifObtener acceso a los controles y eliminarlos

Puede utilizar la propiedad Controls de un objeto Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document para recorrer en iteración todos los controles del documento, incluso los que agregó en tiempo de diseño.Los controles que agrega en tiempo de diseño también se denominan controles estáticos.

Puede quitar los controles dinámicos llamando al método Delete del control o llamando al método Remove de cada colección Controls.En el siguiente ejemplo de código se utiliza el método Remove para quitar NamedRange de Sheet1 en un proyecto en el nivel del documento para Excel.

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

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

Los controles estáticos no se pueden quitar en tiempo de ejecución.Si intenta utilizar el método Remove o Delete para quitar un control estático, se iniciará una excepción CannotRemoveControlException.

[!NOTA]

No quite controles mediante programación en el controlador de eventos Shutdown del documento.Los elementos de la interfaz de usuario del documento dejan de estar disponibles cuando se provoca el evento Shutdown.Si desea quitar controles antes de que se cierre el documento, agregue su código al controlador de eventos de otro evento, como Document.BeforeClose o Document.BeforeSave para Word, o bien Workbook.BeforeClose o Workbook.BeforeSave para Excel.

Agregar controles host a documentos

Cuando agregue un control host a un documentos mediante programación, es preciso proporcionar un nombre que singularmente identifique ese control y, además, especificar dónde se agregará el control en el documento.Para obtener instrucciones concretas, consulte los temas siguientes:

Para obtener más información acerca de los controles de host, vea Información general sobre elementos y controles Host.

Cuando se guarda y cierra un documento, todos los controles host creados dinámicamente se desconectan de sus eventos y pierden la funcionalidad de enlace de datos.Puede agregar código a la solución para crear de nuevo los controles host cuando se vuelva a abrir el documento.Para obtener más información, vea Guardar controles dinámicos en documentos de Office.

[!NOTA]

No se proporcionan métodos auxiliares para los controles host siguientes, ya que estos controles no se pueden agregar a los documentos mediante programación: XmlMappedRange, XMLNode y XMLNodes.

Agregar controles de formularios Windows Forms a documentos

Cuando agrega un control de formularios Windows Forms a un documento mediante programación, debe proporcionar la ubicación del control y un nombre que lo identifique de forma única.El Runtime de Microsoft Visual Studio Tools para Office proporciona métodos auxiliares para cada control.Estos métodos se sobrecargan para poder pasar un intervalo o coordenadas específicas para la ubicación del control.

Cuando un documento se guarda y, a continuación, se cierra, todos los controles de Windows Forms creados dinámicamente se quitan del documento.Puede agregar código a la solución para crear de nuevo los controles cuando se vuelva a abrir el documento.Si crea controles dinámicos de Windows Forms utilizando un complemento en el nivel de la aplicación, los contenedores de ActiveX para los controles permanecen en el documento.Para obtener más información, vea Guardar controles dinámicos en documentos de Office.

[!NOTA]

Los controles de formularios Windows Forms no se pueden agregar mediante programación a los documentos protegidos.Si anula la protección de un documento de Word o una hoja de cálculo de Excel mediante programación para agregar un control, debe escribir código adicional para quitar el contenedor de ActiveX del control cuando se cierre el documento.El contenedor de ActiveX del control no se elimina automáticamente de los documentos protegidos.

x97a5x3s.collapse_all(es-es,VS.110).gifAgregar controles personalizados

Si desea agregar System.Windows.Forms.Control que no es compatible con los métodos auxiliares disponibles, como un control de usuario personalizado, utilice los siguientes métodos:

Para agregar el control, pase al método AddControl el control System.Windows.Forms.Control, una ubicación para el control y un nombre que lo identifique de forma única.El método AddControl devuelve un objeto que define cómo el control interactúa con la hoja de cálculo o el documento.El método AddControl devuelve Microsoft.Office.Tools.Excel.ControlSite (para Excel) o un objeto Microsoft.Office.Tools.Word.ControlSite (para word).

El ejemplo de código siguiente muestra cómo utilizar el método AddControl(Control, Range, String) para agregar dinámicamente un control de usuario personalizado a una hoja de cálculo en un proyecto de Excel de documento- nivel.En este ejemplo, el control de usuario se denomina UserControl1, y Range se denomina range1. Para usar este ejemplo, ejecútelo desde una clase Sheetn en el proyecto.

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

x97a5x3s.collapse_all(es-es,VS.110).gifUtilizar miembros de controles personalizados

Después de utilizar uno de los métodos AddControl para agregar un control a una hoja de cálculo o un documento, ahora tiene dos objetos de control diferentes:

  • System.Windows.Forms.Control, que representa el control personalizado.

  • Objeto ControlSite, OLEObject u OLEControl que representa el control una vez agregado a la hoja de cálculo o el documento.

Muchas propiedades y métodos se comparten entre estos controles.Es importante que obtenga acceso a estos miembros a través del control adecuado:

  • Para obtener acceso a los miembros que solo pertenecen al control personalizado, utilice System.Windows.Forms.Control.

  • Para obtener acceso a los miembros compartidos por los controles, use el objeto ControlSite, OLEObject u OLEControl.

Si obtiene acceso a un miembro compartido de System.Windows.Forms.Control, podría producirse un error sin advertencia o notificación, o podrían generarse resultados no válidos.Siempre utilice métodos o propiedades del objeto ControlSite, OLEObject u OLEControl, a menos que el método o la propiedad que se necesite no esté disponible; únicamente en este caso se debe hacer referencia a System.Windows.Forms.Control.

Por ejemplo, las clases ControlSite y System.Windows.Forms.Control tienen una propiedad Top.Para obtener o establecer la distancia entre la parte superior del control y la parte superior del documento, utilice la propiedad Top de ControlSite, no la propiedad Top de System.Windows.Forms.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én

Tareas

Cómo: Agregar controles ListObject a hojas de cálculo

Cómo: Agregar controles NamedRange a hojas de cálculo

Cómo: Agregar controles Chart a hojas de cálculo

Cómo: Agregar controles de contenido a documentos de Word

Cómo: Agregar controles Bookmark a documentos de Word

Cómo: Agregar controles de Windows Forms a documentos de Office

Conceptos

Guardar controles dinámicos en documentos de Office

Información general sobre controles de formularios Windows Forms en documentos de Office

Otros recursos

Controles en documentos de Office