Controles de contenido

Los controles de contenido proporcionan una manera de diseñar documentos y plantillas que tienen estas características:

• Interfaz de usuario (UI) que tiene una entrada controlada como un formulario.

• Restricciones que impiden que los usuarios editen secciones protegidas del documento o plantilla. Para obtener más información, vea Proteger partes de documentos mediante controles de contenido.

• Enlace de datos a un origen de datos. Para obtener más información, consulte Enlace de datos a controles de contenido.

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

  Para ver una demostración de vídeo relacionada, vea Enlazar datos a controles de contenido de Word 2007 mediante Visual Studio Tools para Office System (3.0).

Acerca de los controles de contenido

Los controles de contenido proporcionan una interfaz de usuario optimizada para la entrada e impresión del usuario. Al agregar un control de contenido a un documento, el control se identifica mediante un borde, un título y un texto temporal que puede proporcionar instrucciones al usuario. El borde y el título del control no aparecen en 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 del selector de fechas al documento. Cuando los usuarios hacen clic en el control, aparece la interfaz de usuario del selector de fechas estándar. También puede establecer propiedades del control para establecer el calendario regional que se muestra y para especificar el formato de fecha. Una vez que el usuario elige una fecha, la interfaz de usuario del control está oculta y solo aparece la fecha si el usuario imprime el documento.

Los controles de contenido también le ayudan a hacer lo siguiente:

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

• Enlazar partes de un documento o plantilla a los datos. 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 los proyectos de nivel de documento, puede agregar controles de contenido al documento en tiempo de diseño o en tiempo de ejecución. En los 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.

Tipos de controles de contenido

Hay nueve tipos diferentes de controles de contenido que se pueden agregar a los documentos. La mayoría de los controles de contenido tienen un tipo correspondiente en el Microsoft.Office.Tools.Word espacio de nombres. También puede usar un genérico ContentControl, 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.

Galería de bloques básicos

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 documentos es un fragmento de contenido que se ha creado para usarse varias veces, como una página de portada común, una tabla con formato o un encabezado. Para obtener más información, consulte el BuildingBlockGalleryContentControl tipo . Para obtener más información sobre los bloques de creación, vea Novedades para desarrolladores en Word 2007.

Casilla

Una casilla proporciona una interfaz de usuario que representa un estado binario: seleccionado o desactivado.

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 hay ningún CheckBoxContentControl tipo. Sin embargo, todavía puede crear un control de contenido de casilla agregando un genérico ContentControl a un documento mediante programación. Para obtener más información, vea Controles de contenido de casilla en proyectos de Word.

Cuadro combinado

Un cuadro combinado muestra una lista de elementos que los usuarios pueden seleccionar. A diferencia de una lista desplegable, el cuadro combinado permite a los usuarios agregar sus propios elementos. Para obtener más información, consulte el ComboBoxContentControl tipo .

Selector de fecha

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

Lista desplegable

Una lista desplegable muestra una lista de elementos que los usuarios pueden seleccionar. A diferencia de un cuadro combinado, la lista desplegable no permite a los usuarios agregar ni editar elementos. Para obtener más información, consulte el DropDownListContentControl tipo .

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 de documento, como texto, tablas, gráficos y otros controles de contenido. Para obtener más información, consulte el GroupContentControl tipo .

Imagen

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

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

Texto sin formato

Un control de texto sin formato contiene texto. Un control de texto sin formato no puede contener 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 italiciza una palabra de una frase que se encuentra en un control de texto sin formato, todo el texto dentro del control se pone en cursiva. Para obtener más información, consulte el PlainTextContentControl tipo .

Control de contenido genérico

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

Puede crear objetos ContentControl solo 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ía de los controles de contenido comparten un conjunto de miembros que puede usar para realizar tareas comunes. En la tabla siguiente se describen algunas de las tareas que puede realizar mediante estos miembros.

Proteger partes de documentos mediante controles de contenido

Al proteger una parte de un documento, impide que los usuarios cambien o eliminen el contenido de esa parte del documento. Hay varias maneras de proteger partes de un documento mediante controles de contenido.

Si el área que desea proteger está dentro de un control de contenido, puede usar propiedades del control de contenido para evitar 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 y otros tipos de contenido, puede colocar todo el área en .GroupContentControl A diferencia de otros controles de contenido, un GroupContentControl no proporciona ninguna interfaz de usuario que sea visible para el usuario. Su único propósito es definir una región que los usuarios no puedan editar.

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.

Vincular datos a controles de contenido

Puede mostrar datos en documentos enlazando un control de contenido a un origen de datos. Cuando se actualiza el origen de datos, el control de contenido refleja los cambios. También puede 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 campos de base de datos o objetos administrados mediante 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ía de los controles de contenido admiten el modelo de enlace de datos simple que usa Windows Forms. El enlace de datos simple significa que un control está enlazado a un único elemento de datos, como un valor en una columna de una tabla de datos. Para obtener más información, consulte Vinculación de datos y 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 .

En los proyectos de nivel de documento y complementos VSTO, puede enlazar un control de contenido a un origen de datos programáticamente usando 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, en el que los cambios en el control se actualizan al origen de datos. Para obtener más información, consulte Cómo: Actualizar un origen de datos con datos de un control host.

Enlazar controles de contenido a elementos XML personalizados

Puede vincular algunos controles de contenido a elementos en partes XML personalizadas incrustadas 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 enlazar el elemento PlainTextContentControl al elemento Price en el nodo Product de una parte XML personalizada que ya se ha agregado al documento.

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

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")

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, el enlace de datos bidireccional se habilita automáticamente. Si un usuario edita texto en el control, los elementos XML correspondientes se actualizan automáticamente. Del mismo modo, si se cambian los valores de elemento de los elementos XML personalizados, los controles de contenido enlazados a los elementos XML mostrarán los nuevos datos.

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

• ComboBoxContentControl

• DatePickerContentControl

• DropDownListContentControl

• PictureContentControl

• PlainTextContentControl

Eventos de vinculación de datos para controles de contenido

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

Limitaciones de los controles de contenido

Cuando use 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 en 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 solicitará permiso para reparar el documento. Al reparar el documento, Word quita todo el contenido y el formato no admitidos del control.

Por ejemplo, Word no impide agregar una tabla en PlainTextContentControl tiempo de diseño. Sin embargo, dado que PlainTextContentControl los objetos 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, aún puede editar el texto dentro del control mediante 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 un evento que se genera cuando el usuario cambia el texto u otros elementos del control. Por ejemplo, no hay ningún evento que se genere cuando un usuario selecciona un elemento diferente en un 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, a continuación, controlar el StoreUpdating evento. Este evento se genera cuando el usuario cambia el contenido de un control 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 de verificación. 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 hacerlo.

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;

Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
    Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)


checkBoxControl1.Checked = True

Contenido relacionado

• Automatizar Word mediante objetos extendidos
• Cómo: Agregar controles de contenido a documentos de Word
• Tutorial: Creación de una plantilla mediante controles de contenido
• Datos en soluciones de Office
• Enlace de datos a controles en soluciones de Office
• Limitaciones programáticas de elementos y controles de host