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 agregue o quite 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, consulte Características disponibles por aplicación de Office lication 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 los métodos del asistente de los objetos ControlCollection y ControlCollection.

La forma de acceder a estos objetos depende del tipo de proyecto que esté desarrollando:

  • En un proyecto de nivel de documento para Excel, use la propiedad Controls de las clases Sheet1, Sheet2y Sheet3 . Para obtener más información sobre estas clases, vea Elemento host de hoja de cálculo.

  • En un proyecto de nivel de documento para Word, use la propiedad Controls de la clase ThisDocument . Para obtener más información sobre esta clase, vea Elemento host de documento.

  • En un proyecto de complemento de VSTO para Excel o Word, use la Controls propiedad de o WorksheetDocument que genere en tiempo de ejecución. Para obtener más información sobre cómo generar estos objetos en tiempo de ejecución, vea Extender documentos de Word y libros de Excel en complementos de VSTO en tiempo de ejecución.

Agregar controles

Los tipos ControlCollection y ControlCollection incluyen métodos del asistente que puede utilizar para agregar controles host y controles comunes de formularios Windows Forms a documentos y hojas de cálculo. 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. Por ejemplo, para agregar un control NamedRange al documento, use el método AddNamedRange .

En el ejemplo de código siguiente se agrega un elemento NamedRange a Sheet1 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 elemento Worksheet o Document para recorrer en iteración todos los controles del documento, incluidos los controles que agregó en tiempo de diseño. Los controles que agregó 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. 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.

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

No se pueden quitar controles estáticos en tiempo de ejecución. Si intenta utilizar los métodos Delete o Remove para quitar un control estático, se producirá una 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 ya no estarán disponibles cuando se produzca el evento Shutdown . 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.

Adición de controles host a documentos

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. 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.

Si un documento se guarda 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:

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

Agregar controles de Windows Forms a documentos

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. 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 intervalo o coordenadas concretas para la ubicación del control.

Cuando un documento se guarda y se cierra, todos los controles de formularios 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 formularios Windows Forms no se puede 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 de ActiveX del control cuando se cierre el documento. El contenedor de ActiveX del control no se elimina automáticamente de los documentos protegidos.

Agregar controles personalizados

Si quiere agregar un elemento Control que no es compatible con los métodos del asistente disponibles, como un control de usuario personalizado, use los métodos siguientes:

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

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

    Para agregar el control, pase el elemento Control, una ubicación para el control y un nombre que identifique de forma única el control al método AddControl. El método AddControl devuelve un objeto que define cómo interactúa el control con el documento o la hoja de cálculo. 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 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. En este ejemplo, el control de usuario se denomina UserControl1y el elemento Range se llama range1. Para usar este ejemplo, ejecútelo desde una clase Sheetn del 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 utilizar uno de los métodos AddControl para agregar un control a una hoja de cálculo o a un documento, ahora dispone de dos objetos de control diferentes:

  • El objeto Control que representa el control personalizado.

  • El objeto ControlSite, OLEObject o OLEControl que representa el control después de agregarlo a la hoja de cálculo o al documento.

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

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

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

    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. Utilice siempre métodos o propiedades del objeto ControlSite, OLEObject o OLEControl, a menos que el método o la propiedad necesarios no estén disponibles; solo en ese caso debe hacer referencia a Control.

    Por ejemplo, tanto las clases ControlSite y Control tienen una propiedad Top. 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.

    // 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