Trabajar con comentarios
En este tema se describe la clase Open XML SDK for Office Comment y cómo se relaciona con el esquema PresentationML de formato de archivo Open XML. Para más información sobre la estructura general de los elementos que conforman un documento PresentationML, vea Estructura de un documento PresentationML.
Comentarios en PresentationML
La especificación ISO/IEC 29500 describe la sección de comentarios del marco PresentationML de Office Open XML de la siguiente manera:
Un comentario es una nota de texto adjunta a la diapositiva y su objetivo principal consiste en permitir a los lectores de una presentación proporcionar comentarios al autor de ésta. Cada comentario contiene una cadena de texto sin formato e información acerca del autor y está adjunto en una ubicación concreta de la diapositiva. Los comentarios pueden verse al editar la presentación, pero no al mostrarla. La aplicación que muestra la presentación decide cuándo mostrar los comentarios y determina su apariencia visual.
La especificación ISO/IEC 29500 describe el elemento <cm/> de PresentationML de Office Open XML, que se usa para representar comentarios en un documento PresentationML, de la siguiente manera:
Este elemento especifica un solo comentario adjunto a una diapositiva. Contiene el texto del comentario, su posición en la diapositiva y atributos que hacen referencia al autor y la fecha.
Ejemplo:
<p:cm authorId="0" dt="2006-08-28T17:26:44.129" idx="1">
<p:pos x="10" y="10"/>
<p:text\>Add diagram to clarify.</p:text>
</p:cm>
En la tabla siguiente se enumeran los elementos secundarios del <cm/> elemento que se usan al trabajar con comentarios y las clases del SDK de Open XML que se corresponden con ellos.
| Elemento de PresentationML | Open XML SDK (clase) |
|---|---|
<extLst/> |
ExtensionListWithModification |
<pos/> |
Position |
<text/> |
Text |
La siguiente tabla de la especificación ISO/IEC 29500 describe los atributos del elemento <cm/>.
| Atributos | Descripción |
|---|---|
| authorId | Este atributo especifica el autor del comentario. Hace referencia al identificador de un autor en la lista de autores de comentarios del documento. Los valores posibles para este atributo se definen mediante el tipo de datos de esquema unsignedInt XML W3C. |
| Despegue | Este atributo especifica la fecha y hora en que se modificó por última vez este comentario. Los valores posibles para este atributo se definen mediante el tipo de datos de esquema datetime XML W3C. |
| idx | Este atributo especifica un identificador de este comentario que es exclusivo dentro de una lista de todos los comentarios realizados por este autor en este documento. El primer comentario de un autor en un documento tiene el índice 1. Nota: Dado que el índice solo es único para el autor de comentarios, un documento puede contener varios comentarios con el mismo índice creado por diferentes autores. Los valores posibles para este atributo los define el tipo simple ST_Index (§19.7.3). |
Clase de comentario del SDK de Open XML
La clase DEL SDK Comment de OXML representa el <cm/> elemento definido en el esquema de formato de archivo Open XML para documentos PresentationML. Use la Comment clase para manipular elementos individuales <cm/> en un documento PresentationML.
Las clases que representan elementos secundarios del <cm/> elemento y que, por lo tanto, se asocian normalmente a la Comment clase se muestran en la lista siguiente.
Clase ExtensionListWithModification
La ExtensionListWithModification clase corresponde al <extLst/>elemento . La siguiente información de la especificación ISO/IEC 29500 presenta el <extLst/> elemento :
Este elemento especifica la lista de extensiones con capacidad de modificación, en la cual se definen todas las futuras extensiones del tipo de elemento <ext/>. La lista de extensiones, junto con las extensiones futuras correspondientes, se usa para ampliar la capacidad de almacenamiento del marco PresentationML. Esto permite que se almacenen en el marco diversos tipos de datos nuevos de forma nativa.
Nota:
El uso de este extLst elemento permite que la aplicación generadora almacene si se ha modificado esta propiedad de extensión. nota final
Clase Position
La Position clase corresponde al <pos/>elemento . La siguiente información de la especificación ISO/IEC 29500 presenta el <pos/> elemento :
Este elemento especifica la información de posicionamiento de la selección de ubicación de un comentario en la superficie de una diapositiva. En las versiones de izquierda a derecha de la aplicación que genera la presentación, esta información de posición debe hacer referencia al punto superior izquierdo de la forma de comentario. En las versiones de derecha a izquierda de la aplicación que la genera, esta información de posición debe hacer referencia al punto superior derecho de la forma de comentario.
[Nota: el punto de delimitación en la superficie de la diapositiva no se ve afectado por un cambio de diseño de derecha a izquierda o de izquierda a derecha. Esto significa que el punto de delimitación permanece igual para todas las versiones de idioma. Fin de la nota]
[Nota: dado que los comentarios no tienen tamaño o formato especificados, este widget de interfaz de usuario usado para mostrar un comentario puede tener cualquier tamaño y, por lo tanto, el punto inferior derecho de la forma de comentario se determina por el modo en que la aplicación que visualiza la presentación elige mostrar los comentarios. Fin de la nota]
[Ejemplo: <p:pos x="1426" y="660"/> end example]
Clase Text
La Text clase corresponde al <text/> elemento . La siguiente información de la especificación ISO/IEC 29500 presenta el <text/> elemento :
Este elemento especifica el contenido de un comentario. Se trata del texto con el que el autor ha anotado la diapositiva.
Los valores posibles para este elemento se definen mediante el tipo de datos esquema string XML de W3C.
Trabajar con la clase Comment
Un comentario es una nota de texto adjunta a una diapositiva y su objetivo principal consiste en permitir a los lectores de una presentación proporcionar comentarios al autor de dicha presentación. Cada comentario contiene una cadena de texto sin formato e información acerca del autor y está adjunto en una ubicación concreta de la diapositiva. Los comentarios pueden verse al editar la presentación, pero no al mostrarla. La aplicación que muestra la presentación decide cuándo mostrar los comentarios y determina su apariencia visual.
Como se muestra en el ejemplo de código del SDK de Open XML que sigue, cada instancia de la Comment clase está asociada a una instancia de la SlideCommentsPart clase , que representa una parte de comentarios de diapositiva, una de las partes de un paquete de archivo de presentación PresentationML y una parte necesaria para cada diapositiva de un archivo de presentación que contiene comentarios. Cada Comment instancia de clase también está asociada a una instancia de la CommentAuthor clase , que a su vez está asociada a un elemento de presentación con nombre similar, representado por la CommentAuthorsPart clase . Los autores de comentarios para una presentación se especifican en una lista de autores de comentarios, representada por la CommentAuthorList clase , mientras que los comentarios de cada diapositiva se muestran en una lista de comentarios para esa diapositiva, representada por la CommentList clase .
Por Comment lo tanto, la clase , que representa el <cm/> elemento , también está asociada a otras clases que representan los elementos secundarios del <cm/> elemento . Entre estas clases, como se muestra en el ejemplo de código siguiente, se encuentran la Position clase , que especifica la posición del comentario en relación con la diapositiva, y la Text clase , que especifica el contenido de texto del comentario.
Ejemplo de código de Open XML SDK 2.0
El siguiente segmento de código del artículo How to: Add a comment to a slide in a presentation agrega una nueva parte de comentarios a una diapositiva existente en una presentación (si la diapositiva no contiene ya comentarios) y crea una instancia de una clase de SDK Comment de Open XML en la parte de comentarios de diapositiva. También agrega una lista de comentarios a la parte de comentarios mediante la creación de una instancia de la CommentList clase, si aún no existe; asigna un identificador al comentario y, a continuación, agrega un comentario a la lista de comentarios mediante la creación de una instancia de la Comment clase, asignando los valores de atributo necesarios. Además, crea instancias de las Position clases y Text asociadas a la nueva Comment instancia de clase. Para obtener el ejemplo de código completo, vea el artículo mencionado anteriormente.