Compartir a través de

Visión general de los elementos de host y los controles de host

Los elementos host y los controles host son tipos que ayudan a proporcionar el modelo de programación para las soluciones de Office que se crean mediante las herramientas de desarrollo de Office en Visual Studio. Los elementos host y los controles host hacen que la interacción con los modelos de objetos de Microsoft Office Word y Microsoft Office Excel, basados en COM, se asemeje más a la interacción con objetos administrados, como los controles de Windows Forms.

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.

Elementos host

Los elementos host son tipos que se encuentran en la parte superior de las jerarquías del modelo de objetos en proyectos de Office. El entorno de ejecución de Visual Studio Tools para Office define los siguientes elementos host para las soluciones de Word y Excel:

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

    Cada uno de estos tipos extiende un objeto que existe de forma nativa en el modelo de objetos de Word o Excel, denominado objeto nativo de Office. Por ejemplo, el Document elemento anfitrión extiende el Document objeto, que se define en el ensamblado de interoperabilidad primario de Word.

    Los elementos host suelen tener la misma funcionalidad base que los objetos de Office correspondientes, pero se mejoran con las siguientes características:

  • La capacidad de hospedar controles administrados, incluidos los controles host y los controles de Windows Forms.

  • Modelos de eventos más enriquecidos. Algunos eventos de documento, libro y hoja de cálculo en los modelos de objetos nativos de Word y Excel solo se generan en el nivel de aplicación. Los elementos host proporcionan estos eventos en el nivel de documento, de modo que sea más fácil controlar los eventos de un documento específico.

Comprender los elementos de host en proyectos de nivel de documento

En los proyectos de nivel de documento, los elementos host proporcionan un punto de entrada para el código y tienen diseñadores que le ayudan a desarrollar la solución.

Los Document elementos host y Worksheet tienen diseñadores asociados que son la representación visual del documento o hoja de cálculo, como un diseñador de Windows Forms. Puede usar este diseñador para modificar el contenido del documento o la hoja de cálculo directamente en Word o Excel, y para arrastrar controles a la superficie de diseño. Para obtener más información, vea Elemento host de documento y Elemento host de hoja de cálculo.

El Workbook elemento host no actúa como contenedor para los controles que tienen una interfaz de usuario. En su lugar, el diseñador de este elemento host funciona como una bandeja de componentes, lo que permite arrastrar un componente, como DataSet, a su superficie de diseño. Para obtener más información, vea Elemento host del libro de trabajo.

Los elementos host no se pueden crear mediante programación en proyectos de nivel de documento. En su lugar, use las ThisDocumentclases , ThisWorkbooko Sheetn que Visual Studio genera automáticamente en el proyecto en tiempo de diseño. Estas clases generadas derivan de los elementos host y proporcionan un punto de entrada para el código. Para obtener más información, consulte Limitaciones mediante programación de elementos host y controles host.

Descripción de los elementos host en proyectos de complemento de VSTO

Al crear un complemento de VSTO, no tiene acceso a ningún elemento host de forma predeterminada. Sin embargo, puede generar Document, Workbook y Worksheet elementos de hospedaje en complementos de VSTO de Word y Excel durante el tiempo de ejecución.

Después de generar un elemento host, puede realizar tareas como agregar controles a documentos. Para obtener más información, consulte Extender documentos de Word y libros de trabajo de Excel en complementos de VSTO en tiempo de ejecución.

Controles del anfitrión

Los controles host extienden varios objetos de interfaz de usuario (UI) en los modelos de objetos de Word y Excel, como los objetos Microsoft.Office.Interop.Word.ContentControl y Range.

Los siguientes controles host están disponibles para proyectos de Excel:

  • Control de gráfico

  • Control de objeto de lista

  • Control de rango con nombre

  • Control de XmlMappedRange

    Los siguientes controles host están disponibles para proyectos de Word:

  • Control de marcadores

  • Controles de contenido

  • Control de XMLNode

  • control de XMLNodes

    Los controles host que se agregan a los documentos de Office se comportan como los objetos nativos de Office; sin embargo, los controles host tienen funcionalidad adicional, incluidos eventos y funcionalidades de enlace de datos. Por ejemplo, cuando desea capturar los eventos de un objeto nativo Range en Excel, primero debe controlar el evento de cambio de la hoja de cálculo. A continuación, debe determinar si se produjo el cambio dentro de Range. Por el contrario, el NamedRange control host tiene un Change evento que puede controlar directamente.

    La relación entre un elemento host y los controles de host es similar a la relación entre un formulario Windows Forms y los controles de Windows Forms. Al igual que colocaría un control de cuadro de texto en un formulario de Windows Forms, coloca un control NamedRange en un elemento host Worksheet. En la ilustración siguiente se muestra la relación entre los elementos host y los controles host.

    Relación entre los elementos host y los controles host

    También puede usar controles de Windows Forms en las soluciones de Office agregándolos directamente a la superficie del documento de Word y Excel. Para obtener más información, vea Controles de Windows Forms en la visión general de documentos de Office.

Nota:

No se admite la adición de controles host o controles de Windows Forms a un subdocumento de Word.

Añade controles de host a tus documentos

En los proyectos de nivel de documento, puede agregar controles host a los documentos de Word o hojas de cálculo de Excel de las siguientes maneras durante el tiempo de diseño:

Nombres de los controles host

Al arrastrar un control host desde el Cuadro de herramientas al documento, el control se denomina automáticamente mediante el tipo de control con un número incremental al final. Por ejemplo, los marcadores se denominan bookmark1, bookmark2, etc. Si usa la funcionalidad nativa de Word o Excel para agregar el control, puede asignarle un nombre específico en el momento en que lo cree. También puede cambiar el nombre de los controles cambiando el valor de la propiedad Name en la ventana Propiedades .

Nota:

No se pueden usar palabras reservadas para asignar nombres a los controles host. Por ejemplo, si agrega un NamedRange control a una hoja de cálculo y cambia el nombre a Sistema, se producen errores al compilar el proyecto.

Eliminar controles del anfitrión

En los proyectos de nivel de documento, puede eliminar los controles de host durante la fase de diseño seleccionando el control en la hoja de cálculo de Excel o en el documento de Word y presionando la tecla Eliminar. Sin embargo, debe usar el cuadro de diálogo Definir nombre en Excel para eliminar controles NamedRange.

Si agrega un control host a un documento en tiempo de diseño, no debe quitarlo mediante programación en tiempo de ejecución porque la próxima vez que intente usar el control en el código, se produce una excepción. El Delete método de un control host solo quita los controles host que se agregan al documento en tiempo de ejecución. Si llama al método Delete de un control host que fue creado en el tiempo de diseño, se produce una excepción.

Por ejemplo, el método Delete de un NamedRange solo elimina correctamente el NamedRange si se agregó programáticamente a la hoja de cálculo, lo que se conoce como crear controles host dinámicamente. Los controles host creados dinámicamente también se pueden quitar pasando el nombre del control al método Remove de la propiedad Controls o Controls. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

Si los usuarios finales eliminan un control host del documento en tiempo de ejecución, es posible que la solución produzca un error inesperado. Puede usar las características de protección de documentos en Word y Excel para proteger los controles host de la eliminación. Para obtener más información, vea Ejemplos y tutoriales de desarrollo de Office.

Nota:

No elimine controles mediante programación durante el Shutdown controlador de eventos del documento o en la hoja de cálculo. Los elementos de la interfaz de usuario ya no están disponibles cuando se produce el Shutdown evento. Si desea quitar controles antes de que se cierre la aplicación, agregue el código a otro controlador de eventos, como BeforeClose o BeforeSave.

Programación contra eventos de control del servidor

Una manera de que los controles host extiendan los objetos de Office es agregando eventos. Por ejemplo, el Range objeto de Excel y Bookmark el objeto de Word no tienen eventos, pero el tiempo de ejecución de Visual Studio Tools para Office amplía estos objetos agregando eventos programables. Puede acceder e implementar código para estos eventos de la misma manera que accede a los eventos de controles en Windows Forms: a través de la lista desplegable de eventos en Visual Basic y la página de propiedades de eventos en C#. Para obtener más información, vea Tutorial: Programa con eventos de un control NamedRange.

Nota:

No debe establecer la propiedad EnableEvents del objeto Application en Excel a false. Establecer esta propiedad en false impide que Excel genere eventos, incluidos los eventos de los controles host.

Contenido relacionado

  • Last updated on