Compartir a través de

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

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 puedes eliminarlos durante la ejecución. Los controles que agrega o quita en tiempo de ejecución se denominan controles dinámicos.

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

En este tema se describe lo siguiente:

Administración de controles en tiempo de ejecución mediante colecciones de controles

Para agregar, obtener o quitar controles en tiempo de ejecución, use métodos auxiliares de ControlCollection objetos y ControlCollection .

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

Agregar controles

Los tipos ControlCollection y ControlCollection incluyen métodos auxiliares que puede utilizar para agregar controles de host y controles comunes de Windows Forms a documentos y hojas de cálculo. Cada nombre de método tiene el formato Addclase de control, donde la clase de control es el nombre de la clase del control que desea agregar. Por ejemplo, para agregar un NamedRange control al documento, use el AddNamedRange método .

En el siguiente ejemplo de código se agrega un NamedRange a Sheet1 en un proyecto de nivel de documento para Excel.

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

Acceso y eliminación de controles

Puede usar la propiedad Controls de un Worksheet o Document para iterar a través de todos los controles de su documento, incluidos los controles que agregó en tiempo de diseño. Los controles que agregue en tiempo de diseño también se denominan controles estáticos.

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

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

No se pueden quitar controles estáticos en tiempo de ejecución. Si intenta usar el método Delete o Remove para quitar un control estático, se lanzará una CannotRemoveControlException.

Nota:

No quite controles en el Shutdown controlador de eventos del documento mediante programación. Los elementos de interfaz de usuario del documento ya no están disponibles cuando se genera el Shutdown evento. Si desea quitar controles antes de que se cierre el documento, agregue el código al controlador de eventos para otro evento, como BeforeClose o BeforeSave para Word, o BeforeCloseBeforeSave para Excel.

Agregar controles de host a documentos

Al agregar mediante programación controles host a documentos, debe proporcionar un nombre que identifique de forma única el control y debe especificar dónde agregar el control en el documento. Para obtener instrucciones específicas, consulte los temas siguientes:

Para obtener más información sobre los controles host, consulte Información general sobre los elementos host y los controles host.

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

Nota:

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

Agregar controles de Windows Forms a documentos

Al agregar mediante programación un control de Windows Forms a un documento, debe proporcionar la ubicación del control y un nombre que identifique de forma única el control. El entorno de ejecución de Visual Studio Tools para Office proporciona métodos auxiliares para cada control. Estos métodos están sobrecargados para que pueda pasar un rango o coordenadas específicas para la ubicación del control.

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

Nota:

Los controles de Windows Forms no se pueden agregar mediante programación a documentos protegidos. 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 ActiveX del control cuando se cierra el documento. El contenedor ActiveX del control no se elimina automáticamente de los documentos protegidos.

Agregar controles personalizados

Si desea agregar un Control que no sea compatible con los métodos auxiliares disponibles, como un control de usuario personalizado, use los métodos siguientes:

  • Para Excel, use uno de los AddControl métodos de un ControlCollection objeto .

  • Para Word, use uno de los AddControl métodos de un ControlCollection objeto .

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

    En el ejemplo de código siguiente se muestra cómo usar el AddControl método para agregar dinámicamente un control de usuario personalizado a una hoja de cálculo en un proyecto de Excel de nivel de documento. En este ejemplo, el control de usuario se denomina UserControl1y Range se denomina range1. Para usar este ejemplo, ejecútelo desde una Sheet clase n en el proyecto.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Usar miembros de controles personalizados

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

  • El Control que representa el control personalizado.

  • Objeto ControlSite, OLEObjecto OLEControl que representa el control después de agregarlo a la hoja de cálculo o documento.

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

  • Para acceder a los miembros que pertenecen solo al control personalizado, use Control.

  • Para acceder a los miembros compartidos por los controles, use el ControlSite, OLEObject o OLEControl.

    Si accede a un miembro compartido desde Control, podría fallar sin advertencia ni notificación, o podría producir resultados no válidos. Use siempre métodos o propiedades del objeto ControlSite, OLEObject o OLEControl, a menos que el método o la propiedad necesarios no esté disponible; solo entonces debe hacer referencia a Control.

    Por ejemplo, tanto la ControlSite clase como la Control clase tienen una Top propiedad . Para obtener o establecer la distancia entre la parte superior del control y la parte superior del documento, use la Top propiedad de ControlSite, no la Top propiedad de Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

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

Contenido relacionado

  • Last updated on