Trabajar con comentarios
En este tema se describe la clase De comentarios del SDK de Open XML para Office 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 PresentationML <cm> de 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 <elemento cm > 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 |
| <Texto> | Texto |
En la tabla siguiente de la especificación ISO/IEC 29500 se describen 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 los define el tipo de datos unsignedInt del esquema 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 los define el tipo de datos datetime del esquema 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 Comment del SDK de OXML representa el <elemento cm> definido en el esquema de formato de archivo Open XML para documentos PresentationML. Use la clase Comment para manipular elementos cm> individuales <en un documento PresentationML.
Las clases que representan elementos secundarios del <elemento cm> y que, por lo tanto, se asocian normalmente a la clase Comment se muestran en la lista siguiente.
Clase ExtensionListWithModification
La clase ExtensionListWithModification corresponde al <elemento extLst>. La siguiente información de la especificación ISO/IEC 29500 presenta el <elemento extLst> :
Este elemento especifica la lista de extensiones con capacidad de modificación en la que se definen todas las extensiones futuras 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 elemento extLst permite a la aplicación generadora almacenar si se ha modificado esta propiedad de extensión. nota final
Clase Position
La clase Position corresponde al <elemento pos>. La siguiente información de la especificación ISO/IEC 29500 presenta el <elemento pos> :
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 clase Text corresponde al <elemento text>. La siguiente información de la especificación ISO/IEC 29500 presenta el elemento de <texto> :
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 los define el tipo de datos string del esquema XML 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 clase Comment está asociada a una instancia de la clase SlideCommentsPart , 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 instancia de clase Comment también está asociada a una instancia de la clase CommentAuthor , que a su vez está asociada a un elemento de presentación con nombre similar, representado por la clase CommentAuthorsPart . Los autores de comentarios para una presentación se especifican en una lista de autores de comentarios, representada por la clase CommentAuthorList , mientras que los comentarios de cada diapositiva se muestran en una lista de comentarios para esa diapositiva, representada por la clase CommentList .
Por lo tanto, la clase Comment , que representa el <elemento cm> , también está asociada a otras clases que representan los elementos secundarios del <elemento cm> . Entre estas clases, como se muestra en el siguiente ejemplo de código, se encuentran la clase Position, que especifica la posición del comentario en relación con la diapositiva, y la clase Text, 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 comentarios) y crea una instancia de una clase Comment del SDK de Open XML en la parte de comentarios de diapositiva. También se agrega una lista de comentarios a la parte de comentarios mediante la creación de una instancia de la clase CommentList, si todavía no existe una; se asigna un identificador al comentario y, a continuación, se agrega un comentario a la lista de comentarios mediante la creación de una instancia de la clase Comment, para lo cual se asignan los valores de atributo necesarios. Además, se crean instancias de las clases Position y Text asociadas a la nueva instancia de la clase Comment. Para obtener el ejemplo de código completo, vea el artículo mencionado anteriormente.
// Declare a comments part.
SlideCommentsPart commentsPart;
// Verify that there is a comments part in the first slide part.
if (slidePart1.GetPartsOfType<SlideCommentsPart>().Count() == 0)
{
// If not, add a new comments part.
commentsPart = slidePart1.AddNewPart<SlideCommentsPart>();
}
else
{
// Else, use the first comments part in the slide part.
commentsPart = slidePart1.GetPartsOfType<SlideCommentsPart>().First();
}
// If the comment list does not exist.
if (commentsPart.CommentList is null)
{
// Add a new comments list.
commentsPart.CommentList = new CommentList();
}
// Get the new comment ID.
uint commentIdx = author.LastIndex is null ? 1 : author.LastIndex + 1;
author.LastIndex = commentIdx;
// Add a new comment.
Comment comment = commentsPart.CommentList.AppendChild<Comment>(
new Comment()
{
AuthorId = authorId,
Index = commentIdx,
DateTime = DateTime.Now
});
// Add the position child node to the comment element.
comment.Append(
new Position() { X = 100, Y = 200 },
new Text() { Text = text });