Controles de contenido

  • Artículo

Los controles de contenido proporcionan un mecanismo para diseñar documentos y plantillas con las siguientes características:

Acerca de los controles de contenido

Los controles de contenido proporcionan una interfaz de usuario que está optimizada para la entrada e impresión de datos. Cuando se agrega un control de contenido a un documento, este control se identifica por un borde, un título o un texto provisional que puede proporcionar instrucciones al usuario. El borde y el título del control no aparecen en las versiones impresas del documento.

Por ejemplo, si desea que el usuario escriba una fecha en una sección del documento, puede agregar un control de contenido de selector de fecha al documento. Cuando los usuarios hagan clic en el control, aparecerá la interfaz de usuario de selector de fecha estándar. También puede establecer las propiedades del control para configurar el calendario regional mostrado y especificar el formato de fecha. Una vez que el usuario elige una fecha, la interfaz de usuario del control se oculta y, si el usuario imprime el documento, solo aparecerá la fecha.

Los controles de contenido también le ayudan a llevar a cabo las siguientes tareas:

  • Impedir que los usuarios editen o eliminen elementos de un documento. Esto resulta útil si tiene información en un documento o plantilla que los usuarios deberían leer, pero no editar, o si desea que los usuarios puedan modificar controles de contenido, pero no eliminarlos.

  • Enlazar a datos los elementos de un documento o plantilla. Puede enlazar controles de contenido a campos de base de datos, objetos administrados en .NET Framework, elementos XML almacenados en el documento y otros orígenes de datos.

    En proyectos de nivel de documento, puede agregar controles de contenido al documento en tiempo de diseño o en tiempo de ejecución. En proyectos de complemento de VSTO, puede agregar controles de contenido a cualquier documento abierto en tiempo de ejecución. Para obtener más información, vea Cómo: Agregar controles de contenido a documentos de Word.

Nota:

Solo puede usar controles de contenido en documentos guardados en formato Open XML. No puede usar controles de contenido en documentos guardados en el formato de documento de Word 97-2003 (.doc).

Tipos de controles de contenido

Existen nueve tipos diferentes de controles de contenido que se pueden agregar a los documentos. La mayoría de ellos tienen un tipo correspondiente en el espacio de nombres Microsoft.Office.Tools.Word. También se puede usar un tipo ContentControl genérico, que puede representar cualquiera de los controles de contenido disponibles. Para ver un tutorial que muestra cómo usar cada uno de los controles de contenido disponibles, consulte Tutorial: Creación de una plantilla mediante controles de contenido.

Una galería de bloques de creación permite a los usuarios seleccionar una lista de bloques de creación de documentos para insertarlos en un documento. Un bloque de creación de documento es un fragmento de contenido que se ha creado para usarse varias veces, como una portada, una tabla con formato o un encabezado común. Para obtener más información, consulte el tipo BuildingBlockGalleryContentControl. Para obtener más información sobre los bloques de creación, vea Novedades para desarrolladores en Word 2007.

Casilla ver.

Una casilla proporciona una interfaz de usuario que representa un estado binario: activada o desactivada.

A diferencia de los otros tipos de controles de contenido, el entorno de ejecución de Visual Studio Tools para Office no proporciona un tipo específico que represente un control de contenido de casilla. En otras palabras, no existe ningún tipo CheckBoxContentControl. Sin embargo, puede crear un control de contenido de casilla agregando un ContentControl genérico a un documento mediante programación. Para obtener más información, vea Controles de contenido de casilla en proyectos de Word.

Cuadro combinado

En los cuadros combinados se muestra una lista de elementos que los usuarios pueden seleccionar. A diferencia de las listas desplegables, los cuadros combinados permiten a los usuarios agregar sus propios elementos. Para obtener más información, consulte el tipo ComboBoxContentControl.

Selector de fecha

Un selector de fecha proporciona una interfaz de usuario de calendario en la que se puede seleccionar una fecha. El calendario aparece cuando el usuario hace clic en la flecha de lista desplegable del control. Puede usar calendarios regionales y formatos de fecha diferentes. Para obtener más información, consulte el tipo DatePickerContentControl.

En las listas desplegables se muestra una lista de elementos que los usuarios pueden seleccionar. A diferencia de los cuadros combinados, las listas desplegables no permiten que los usuarios agreguen o modifiquen elementos. Para obtener más información, consulte el tipo DropDownListContentControl.

Group (Grupo)

Un control de grupo define una región protegida de un documento que los usuarios no pueden editar ni eliminar. Un control de grupo puede contener cualquier elemento del documento, como texto, tablas, gráficos y otros controles de contenido. Para obtener más información, consulte el tipo GroupContentControl.

Imagen

Un control de imagen muestra una imagen. Puede especificar la imagen en tiempo de diseño o tiempo de ejecución; asimismo, los usuarios pueden hacer clic en este control para seleccionar la imagen que se va a insertar en el documento. Para obtener más información, consulte el tipo PictureContentControl.

Texto enriquecido

Un control de texto enriquecido contiene texto u otros elementos, como tablas, imágenes u otros controles de contenido. Para obtener más información, consulte el tipo RichTextContentControl.

Texto sin formato

Un control de texto sin formato contiene texto. Un control de texto sin formato no puede incluir otros elementos, como tablas, imágenes u otros controles de contenido. Además, todo el texto de un control de texto sin formato tiene el mismo formato. Por ejemplo, si pone en cursiva una palabra de una frase que se encuentra en un control de texto sin formato, todo el texto incluido en el control se pone en cursiva. Para obtener más información, consulte el tipo PlainTextContentControl.

Control de contenido genérico

Un control de contenido genérico es un objeto ContentControl que puede representar cualquiera de los tipos de controles de contenido disponibles. Se puede cambiar un objeto ContentControl para que se comporte como un control de contenido de un tipo distinto mediante la propiedad Type. Por ejemplo, si crea un objeto ContentControl que representa un control de texto sin formato, puede cambiarlo en tiempo de ejecución para que se comporte como un cuadro combinado.

Solo puede crear objetos ContentControl en tiempo de ejecución, no en tiempo de diseño. Para obtener más información, vea Cómo: Agregar controles de contenido a documentos de Word.

Características comunes de los controles de contenido

La mayor parte de los controles de contenido comparten un conjunto de miembros que se pueden usar para llevar a cabo tareas comunes. En la tabla siguiente se describen algunas de las tareas que puede llevar a cabo con estos miembros.

Para efectuar esta tarea: Haga esto:
Obtener o establecer el texto que se muestra en el control. Use la propiedad Text . Nota: Los PictureContentControl tipos y ContentControl no tienen esta propiedad.
Obtener o establecer el texto provisional que se muestra en el control hasta que un usuario lo edita, se rellena con datos de un origen de datos o se elimina el contenido del control. Utilice la propiedad PlaceholderText . Nota: El PictureContentControl tipo no tiene esta propiedad.
Obtener o establecer el título que se muestra en el borde del control de contenido cuando el usuario hace clic en él. Use la propiedad Title .
Quitar automáticamente el control del documento una vez que el usuario lo haya editado (el texto del control permanece en el documento). Use la propiedad Temporary .
Ejecutar el código cuando el usuario haga clic en el control de contenido o cuando el cursor se mueva al control de contenido mediante programación. Controle el evento Entering del control.
Ejecutar el código cuando el usuario haga clic fuera del control de contenido o cuando el cursor se mueva fuera del control de contenido mediante programación. Controle el evento Exiting del control.
Ejecutar el código una vez que el control de contenido se haya agregado al documento como resultado de una operación de deshacer o rehacer. Controle el evento Added del control.
Ejecutar el código justo antes de que se elimine el control de contenido del documento. Controle el evento Deleting del control.

Proteger partes de documentos mediante controles de contenido

Al proteger un elemento de un documento, se impide que los usuarios cambien o eliminen el contenido de ese elemento. Existen varios modos de proteger los elementos de un documento mediante los controles de contenido.

Si el área que desea proteger está dentro de un control de contenido, puede usar las propiedades del control de contenido para impedir que los usuarios editen o eliminen el control:

  • La propiedad LockContents impide que los usuarios editen el contenido.

  • La propiedad LockContentControl impide que los usuarios eliminen el control.

    Si el área que desea proteger no está dentro de un control de contenido o si desea proteger un área que contiene controles de contenido además de otros tipos de contenido, puede situar el área completa en un GroupContentControl. A diferencia de otros controles de contenido, el GroupContentControl no proporciona una interfaz de usuario visible para el usuario. Su único propósito es definir una región que los usuarios no puedan modificar.

Nota:

Si crea un GroupContentControl que contiene controles de contenido insertados, estos controles no se protegerán automáticamente. Debe usar la propiedad LockContents de cada control incrustado para evitar que los usuarios editen su contenido.

Para obtener más información sobre cómo usar controles de contenido para proteger partes de documentos, vea Cómo: Proteger partes de documentos mediante controles de contenido.

Enlace de datos a controles de contenido

Puede mostrar los datos en documentos estableciendo enlaces entre un control de contenido y un origen de datos. Cuando el origen de datos se actualice, el control de contenido reflejará los cambios. También puede volver a guardar los cambios en el origen de datos.

Los controles de contenido proporcionan las siguientes opciones de enlace de datos:

  • Puede enlazar controles de contenido a los campos de una base de datos o a los objetos administrados usando el mismo modelo de enlace de datos que Windows Forms.

  • Puede enlazar controles de contenido a elementos de fragmentos de XML (también denominados elementos XML personalizados) incrustados en el documento.

    Para obtener información general sobre el enlace de controles host en soluciones de Office a datos, vea Enlazar datos a controles en soluciones de Office.

Usar el modelo de enlace de datos de Windows Forms

La mayor parte de los controles de contenido admite el modelo simple de enlace de datos que usa Windows Forms. Un enlace de datos simple significa que un control se enlaza a un único elemento de datos, como un valor de una columna de una tabla de datos. Para obtener más información, consulte Enlace de datos y Formularios Windows Forms.

En los proyectos de nivel de documento, puede enlazar datos a controles de contenido mediante la ventana Orígenes de datos de Visual Studio. Para obtener más información sobre cómo agregar controles de contenido enlazados a datos a documentos, vea Cómo: Rellenar documentos con datos de una base de datos y Cómo: Rellenar documentos con datos de objetos.

En la tabla siguiente se enumeran los controles de contenido que puede enlazar a cada tipo de datos en la ventana Orígenes de datos.

Tipo de datos Control de contenido predeterminado Otros controles de contenido que se pueden enlazar a este tipo de datos
Boolean

Byte

Char

Double

Enum

Guid

Int16

Int32

Int64

SByte

Single

String

TimeSpan

UInt16

UInt32

UInt64		 PlainTextContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

DatePickerContentControl

RichTextContentControl
DateTime DatePickerContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

PlainTextContentControl

RichTextContentControl
Image

Matriz Byte		 PictureContentControl None

En los proyectos de nivel de documento y de complemento de VSTO puede enlazar un control de contenido a un origen de datos mediante programación con el método Add de la propiedad DataBindings del control. Si lo hace, pase la cadena Text al parámetro propertyName del Add método . La propiedad Text es la propiedad de enlace de datos predeterminada de los controles de contenido.

Los controles de contenido también admiten el enlace de datos bidireccional, mediante el cual los cambios que se efectúan en el control se actualizan en el origen de datos. Para obtener más información, consulte Cómo: Actualizar un origen de datos con datos de un control host.

Nota:

Los controles de contenido no admiten el enlace de datos complejo. Si enlaza un control DropDownListContentControl o ComboBoxContentControl a un origen de datos mediante el modelo de datos de Windows Forms, los usuarios solo verán un valor único cuando hagan clic en el control. Si desea enlazar estos controles a un conjunto de valores de datos que los usuarios pueden elegir, puede enlazarlos a los elementos de un elemento XML personalizado.

Enlazar controles de contenido a elementos XML personalizados

Puede enlazar algunos controles de contenido a los elementos XML personalizados que están insertados en el documento. Para obtener más información sobre los elementos XML personalizados, consulte Información general sobre elementos XML personalizados.

Para enlazar un control de contenido a un elemento de un elemento XML personalizado, use la propiedad XMLMapping del control. En el siguiente ejemplo de código se muestra cómo se enlaza un control PlainTextContentControl al elemento Price situado bajo el nodo Product de un elemento XML personalizado que ya se ha agregado al documento.

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);

Para ver un tutorial que muestra cómo enlazar controles de contenido a elementos XML personalizados con más detalle, vea Tutorial: Enlazar controles de contenido a elementos XML personalizados.

Al enlazar un control de contenido a un elemento XML personalizado, se habilita automáticamente el enlace de datos bidireccional. Si un usuario edita el texto del control, los elementos XML correspondientes se actualizan automáticamente. De igual forma, si se modifican los valores de los elementos XML personalizados, los controles de contenido que están enlazados a los elementos XML mostrarán los nuevos datos.

Puede enlazar los siguientes tipos de controles de contenido a elementos XML personalizados:

Eventos de enlace de datos para controles de contenido

Todos los controles de contenido proporcionan un conjunto de eventos que puede controlar para llevar a cabo tareas relacionadas con datos, como validar que el texto de un control cumple determinados criterios antes de actualizar el origen de datos. En la siguiente tabla se enumeran los eventos de los controles de contenido que están relacionados con el enlace de datos.

Tarea Evento
Ejecutar código inmediatamente antes de que Word actualice automáticamente el texto de un control de contenido que está enlazado a un elemento XML personalizado. ContentUpdating
Ejecutar código inmediatamente antes de que Word actualice automáticamente los datos de un elemento XML personalizado que está enlazado a un control de contenido (es decir, después de modificar el texto en el control de contenido). StoreUpdating
Ejecutar su propio código para validar el contenido del control según unos criterios personalizados. Validating
Ejecutar el código una vez que se haya validado correctamente el contenido del control. Validated

Limitaciones de los controles de contenido

Al usar controles de contenido en los proyectos de Office, tenga en cuenta las siguientes limitaciones.

Diferencias de comportamiento entre tiempo de diseño y tiempo de ejecución

Muchas de las limitaciones que Microsoft Office Word impone a los controles de contenido en tiempo de ejecución no se aplican en tiempo de diseño. Al diseñar la interfaz de usuario de una solución de nivel de documento en Visual Studio, asegúrese de modificar los controles de contenido solo de maneras compatibles en tiempo de ejecución.

Si modifica un control de contenido en tiempo de diseño de una manera que el control no admite en tiempo de ejecución, el diseñador de Visual Studio no le avisará de los cambios no admitidos. Sin embargo, al depurar o ejecutar el proyecto, o si guarda y vuelve a abrir el proyecto, Word mostrará un mensaje de error y un permiso de solicitud para reparar el documento. Al reparar el documento, Word quitará todo el contenido y el formato no admitido del control.

Por ejemplo, Word no impide que se agregue una tabla a un control PlainTextContentControl en tiempo de diseño. Sin embargo, dado que los objetos PlainTextContentControl no pueden contener tablas en tiempo de ejecución, Word mostrará un mensaje de error cuando se abra el documento.

Tenga en cuenta también que muchas propiedades que definen el comportamiento de los controles de contenido no tienen ningún efecto en tiempo de diseño. Por ejemplo, si establece la propiedad LockContents de un control de contenido en True en tiempo de diseño, todavía puede editar texto en el control en el diseñador de Visual Studio. Esta propiedad solo impide que los usuarios editen el control en tiempo de ejecución.

Limitaciones de eventos

Los controles de contenido no proporcionan ningún evento que se produzca cuando el usuario cambia el texto u otros elementos del control. Por ejemplo, no hay ningún evento que se produzca cuando un usuario selecciona un elemento distinto en un control DropDownListContentControl o ComboBoxContentControl.

Para determinar cuándo un usuario edita el contenido de un control de contenido, puede enlazar el control a un elemento XML personalizado y controlar el evento StoreUpdating. Este evento se desencadena cuando el usuario cambia el contenido de un control que está enlazado a un elemento XML personalizado. Para ver un tutorial que muestra cómo enlazar un control de contenido a un elemento XML personalizado, vea Tutorial: Enlazar controles de contenido a elementos XML personalizados.

Controles de contenido de casilla en proyectos de Word

Word 2010 introdujo un nuevo tipo de control de contenido que representa una casilla. Sin embargo, el entorno de ejecución de Visual Studio Tools para Office no proporciona un tipo CheckBoxContentControl correspondiente para que lo use en proyectos de Office. Para crear un control de contenido de casilla en un proyecto de Word 2013 o Word 2010, use el AddContentControl método para crear un ContentControl objeto y pase el wdContentControlCheckBox valor al método para especificar un control de contenido de casilla. En el ejemplo de código siguiente se muestra cómo utilizar este recurso.

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

checkBoxControl1.Checked = true;

Contenido relacionado