Controles de contenido
Los controles de contenido proporcionan un mecanismo para diseñar documentos y plantillas con las características siguientes:
Una interfaz de usuario que tiene la 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 elementos de documentos mediante controles de contenido.
Enlaces a un origen de datos. Para obtener más información, vea Enlazar datos a controles de contenido.
Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento y los proyectos de nivel de aplicación para Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.
.gif "vínculo a vídeo")
Para obtener una demostración de vídeo relacionada, vea Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0).
Información general sobre 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 selección de fechas al documento. Cuando los usuarios hagan clic en el control, aparecerá una interfaz de usuario de selector de fechas estándar. También puede definir 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, sólo aparecerá la fecha.
Los controles de contenido también le ayudan a realizar las tareas siguientes:
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 los controles de contenido a los campos de una base de datos, los objetos administrados de .NET Framework, los elementos XML que están almacenados en el documento y otros orígenes de datos.
En proyectos en el nivel del documento, puede agregar controles de contenido al documento en tiempo de diseño o en tiempo de ejecución. En los proyectos de nivel de aplicación, 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
Los controles de contenido se pueden usar únicamente en documentos que se han guardado con el formato Open XML. No se pueden utilizar en documentos que se han guardado con el formato Documento de Word 97-2003 (.doc).
Tipos de controles de contenido
Existen nueva 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 espacio de nombres Microsoft.Office.Tools.Word. También se puede utilizar un control ContentControl genérico, que puede representar cualquiera de los controles de contenido disponibles. Para obtener un tutorial en el que se muestra cómo se utiliza cada uno de los controles de contenido disponibles, vea Tutorial: Crear una plantilla mediante controles de contenido.
Galería de bloques de creación
Una galería de bloques de creación permite a los usuarios seleccionar una opción de una lista de bloques de creación de documento para insertarlo en un documento. Un bloque de creación de documento es un fragmento de contenido que se ha creado para utilizarse varias veces, como por ejemplo, una portada, una tabla con formato o un encabezado común. Para obtener más información, vea el tipo de BuildingBlockGalleryContentControl. Para obtener más información sobre los bloques de creación, vea Lo nuevo para programadores de Word 2007.
Casilla
Una casilla proporciona una interfaz de usuario que representa un estado binario: activada o desactivada. Este tipo de control de contenido solo está disponible en Word 2010.
A diferencia de los demás tipos de controles de contenido, Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office no proporciona ningún 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 si agrega un control 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 2010.
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, vea el tipo de 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 utilizar calendarios regionales y formatos de fecha diferentes. Para obtener más información, vea el tipo de DatePickerContentControl.
Listas desplegables
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, vea el tipo de DropDownListContentControl.
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, vea el tipo de GroupContentControl.
Imagen
En los controles de imagen se muestran imágenes. Puede especificar la imagen en tiempo de diseño o en 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, vea el tipo de 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, vea el tipo de 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, vea 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.
Sólo puede crear objetos ContentControl en tiempo de ejecución, no en tiempo de diseño. Para obtener más información, consulte Cómo: Agregar controles de contenido a documentos de Word.
Características comunes de controles de contenido
La mayor parte de los controles de contenido comparten un conjunto de miembros que se pueden utilizar para realizar tareas comunes. En la tabla siguiente se describen algunas de las tareas que puede realizar con estos miembros.
En esta tarea: |
Haga lo siguiente: |
|---|---|
Obtener o establecer el texto que se muestra en el control. |
Utilice la propiedad Text. .gif "Nota") Nota
Los tipos PictureContentControl y ContentControl no tienen esta propiedad.
|
Obtener o establecer el texto provisional que se muestra en el control hasta que el 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 tipo PictureContentControl 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. |
Utilice la propiedad Title. |
Quitar automáticamente el control del documento una vez que el usuario lo edite. (El texto del control permanece en el documento). |
Utilice 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 inmediatamente antes de que se elimine el control de contenido del documento. |
Controle el evento Deleting del control. |
Proteger elementos 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 controles de contenido.
Si el área que desea proteger está dentro de un control de contenido, puede utilizar 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 una área que contiene controles de contenido además de otro tipo de contenido, puede situar toda el área completa en un control GroupContentControl. A diferencia de otros controles de contenido, el control GroupContentControl no proporciona una interfaz visible para el usuario. Su único propósito es definir una región que los usuarios no puedan modificar.
Nota
Si crea un control GroupContentControl que contiene controles de contenido incrustados, estos controles de contenido incrustados no se protegerán automáticamente. Debe utilizar la propiedad LockContents de cada uno de los controles incrustados para impedir que los usuarios editen su contenido.
Si desea obtener más información acerca de cómo se utilizan los controles de contenido para proteger elementos de documentos, vea Cómo: Proteger elementos de documentos mediante controles de contenido.
Enlazar 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 guardar los cambios de nuevo en el origen de datos.
Los controles de contenido proporcionan las opciones de enlace de datos siguientes:
Puede enlazar controles de contenido a los campos de una base de datos o a los objetos administrados utilizando el mismo modelo de enlace de datos que los formularios Windows Forms.
Puede enlazar los controles de contenido a los objetos de los elementos XML (también llamados elementos XML personalizados) que están incrustados en el documento.
Para obtener información general sobre cómo enlazar a datos los controles host en las soluciones de Office, vea Enlazar datos a controles en soluciones de Office.
Utilizar el modelo de enlace de datos de los formularios Windows Forms
La mayor parte de los controles de contenido admite el modelo simple de enlace de datos que utilizan los formularios Windows Forms. Un enlace de datos simple significa que un control está enlazado a un único elemento de datos, como por ejemplo, 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 en el nivel del documento, puede enlazar datos a controles de contenido en la ventana Orígenes de datos de Visual Studio. Para obtener más información sobre cómo agregar a los documentos controles de contenido enlazados a datos, 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 se enlazan a cada tipo de dato 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 |
|---|---|---|
|
Matriz Byte |
Ninguna |
En proyectos en el nivel de la aplicación y del documento, puede enlazar un control de contenido a un origen de datos mediante programación utilizando el método Add() de la propiedad DataBindings del control. Si realiza esta operación, pase la cadena Text en el parámetro propertyName del método Add(). 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 realizan 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 enlace de datos complejo. Si enlaza un control DropDownListContentControl o ComboBoxContentControl a un origen de datos utilizando el modelo de datos de los formularios Windows Forms, los usuarios verán sólo 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 objetos 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 incrustados en el documento. Para obtener más información sobre los elementos XML personalizados, vea Información general sobre los elementos XML personalizados.
Para enlazar un control de contenido a un objeto de un elemento XML personalizado, utilice la propiedad XMLMapping del control. En el ejemplo de código siguiente se muestra cómo se enlaza un control PlainTextContentControl al objetoPrice situado bajo el nodo Product de un elemento XML personalizado que ya se ha agregado al documento.
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);
Para obtener un tutorial en el que se muestra con más detalle cómo se enlazan controles de contenido a elementos XML personalizados, vea Tutorial: Enlazar controles de contenido a elementos XML personalizados.
Cuando enlaza 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 un objeto 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 de controles de contenido
Todos los controles de contenido proporcionan un conjunto de eventos que pueden administrarse para realizar tareas relacionadas con datos, como validar que el texto de un control cumple ciertos criterios antes de que el origen de datos se actualice. En la tabla siguiente 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. |
|
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, una vez que se ha modificado el control de contenido). |
|
Ejecutar su propio código para validar el contenido del control según unos criterios personales. |
|
Ejecutar el código una vez que se ha validado correctamente el contenido del control. |
Limitaciones de los controles de contenido
Cuando utilice controles de contenido en sus proyectos de Office, tenga en cuenta las limitaciones siguientes.
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. Cuando diseñe la interfaz de usuario de su solución en el nivel del documento de Visual Studio, asegúrese de que los cambios que realiza en los controles de contenido se admiten en tiempo de ejecución.
Si modifica un control de contenido en tiempo de diseño de forma que el control no es admitido en tiempo de ejecución, el diseñador de Visual Studio no le avisará de que los cambios no son aceptables. Sin embargo, al depurar o ejecutar el proyecto (o al guardar y al abrir a continuación el proyecto), Word mostrará un mensaje de error y solicitará permiso para reparar el documento. Cuando repare el documento, Word quitará todo el contenido y el formato no compatible del control.
Por ejemplo, Word no impide que se agregue una tabla a un control PlainTextContentControl en tiempo de diseño. Sin embargo, como 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 además 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 podrá modificar el texto del control en el diseñador de Visual Studio. Esta propiedad sólo impide que los usuarios editen el control en tiempo de ejecución.
Limitaciones de los 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, puede enlazar el control a un elemento XML personalizado y, a continuación, administrar el evento StoreUpdating. Este evento se provoca cuando el usuario cambia el contenido de un control que está enlazado a un elemento XML personalizado. Para obtener un tutorial en el que se muestra cómo se enlaza 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 2010
Word 2010 introdujo un nuevo tipo de control de contenido que representa una casilla. Sin embargo, Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office no proporciona un tipo de CheckBoxContentControl correspondiente para que se use en los proyectos de Office. Para crear un control de contenido de casilla en un proyecto de Word 2010, utilice el método AddContentControl para crear un objeto Microsoft.Office.Tools.Word.ContentControl y pase el valor wdContentControlCheckBox al método para especificar un control de contenido de casilla. En el ejemplo de código siguiente se muestra cómo hacerlo.
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)
' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True
' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True
this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 =
this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);
// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;
// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;
Nota
La propiedad Checked de los objetos Microsoft.Office.Tools.Word.ContentControl solo se puede utilizar directamente en los proyectos destinados a .NET Framework 4. En proyectos que tienen como destino .NET Framework 3.5, debe utilizar la propiedad InnerObject para tener acceso a la propiedad Checked del objeto Microsoft.Office.Interop.Word.ContentControl subyacente. Para obtener más información, vea Limitaciones de programación de elementos y controles Host.
Vea también
Tareas
Cómo: Agregar controles de contenido a documentos de Word
Tutorial: Crear una plantilla mediante controles de contenido
Conceptos
Automatizar Word con objetos extendidos
Limitaciones de programación de elementos y controles Host