Compartir a través de


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

Actualización: Julio de 2008

Se aplica a

La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados.

Proyectos de nivel de documento

  • Excel 2003

  • Excel 2007

  • Word 2003

  • Word 2007

Proyectos de nivel de aplicación

  • Excel 2007

  • Word 2007

Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

Puede agregar controles a documentos de Microsoft Office Word 2003 y a libros de Microsoft Office Excel 2003, y también quitarlos, en tiempo de ejecución. Los controles que se agregan a los documentos en tiempo de ejecución se denominan controles dinámicos. A partir de Visual Studio 2008 Service Pack 1 (SP1), puede agregar los controles dinámicos a los documentos y libros utilizando complementos en el nivel de la aplicación.

En este tema se proporciona la información 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

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 las clases Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection.

La forma en que obtiene acceso a las colecciones de controles depende del tipo de proyecto que está desarrollando:

Agregar controles

Las clases Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection incluyen métodos auxiliares que puede utilizar para agregar controles host y controles de Windows Forms comunes a los documentos y las hojas de cálculo. Cada nombre de método tiene el formato Add<clase del control>, donde clase del control es el nombre de clase del control que desea agregar. Por ejemplo, para agregar un control NamedRange al documento, se utiliza el método AddNamedRange. Para obtener una lista completa de métodos auxiliares, vea Métodos auxiliares para controles host y Métodos auxiliares para controles de formularios Windows Forms.

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

Obtener 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. Visual Studio Tools para Office proporciona métodos auxiliares para cada control. Estos métodos se sobrecargan, de modo que puede pasar un intervalo o coordenadas específicas para la ubicación del control. Para obtener instrucciones específicas, vea Cómo: Agregar controles de Windows Forms a documentos de Office.

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.

Agregar controles personalizados

Si desea agregar un control System.Windows.Forms.Control no admitido por los métodos auxiliares disponibles (por ejemplo, un control de usuario personalizado), use los métodos siguientes:

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. En Excel, este método devuelve un objeto OLEObject. En Word, este método devuelve un objeto OLEControl. Estos objetos definen cómo interactúa el control con la hoja de cálculo o el documento.

En el ejemplo de código siguiente se muestra cómo utilizar el método AddControl(Control, Range, String) para agregar dinámicamente un control personalizado de usuario a una hoja de cálculo. En este ejemplo, el control de usuario se denomina UserControl1 y Range se denomina range1. En este ejemplo se supone que se ejecuta desde una de las clases Sheetn de un proyecto en el nivel del documento para Excel.

Dim customControl As New UserControl1()

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

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

Utilizar 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:

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

  • Para tener acceso a las propiedades y métodos que sólo pertenecen al control personalizado, utilice System.Windows.Forms.Control.

  • Para tener acceso a las propiedades y los métodos compartidos por los controles, utilice OLEObject o OLEControl.

Si tiene acceso a un método compartido o una propiedad de System.Windows.Forms.Control, podría producirse un error sin advertencia o notificación, o generarse resultados no válidos. Siempre utilice métodos o propiedades de OLEObject o 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 OLEObject 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 OLEObject, 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

Métodos auxiliares para controles host

Métodos auxiliares para controles de formularios Windows Forms

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

Referencia

ControlCollection.AddControl

ControlCollection.AddControl

ControlCollection.Remove

ControlCollection.Remove

Otros recursos

Controles en documentos de Office

Controles Host de Excel

Controles Host de Word

Historial de cambios

Fecha

Historial

Motivo

Julio de 2008

Se agrega información sobre cómo agregar controles a documentos utilizando complementos en el nivel de la aplicación.

Cambio de características de SP1.