Como trabalhar com comentários
Este tópico aborda a classe Open XML SDK for Office Comment e como se relaciona com o esquema Open XML File Format PresentationML. Para obter mais informações sobre a estrutura geral das partes e elementos que compõem um documento PresentationML, consulte Estrutura de um Documento PresentationML.
Comentários no PresentationML
A especificação ISO/IEC 29500 descreve a secção Comentários da arquitetura Open XML PresentationML da seguinte forma:
Um comentário é uma nota de texto anexada a um diapositivo, com o objetivo principal de permitir que os leitores de uma apresentação forneçam feedback ao autor da apresentação. Cada comentário contém uma cadeia de texto não formatado e informações sobre o autor e está anexado a uma localização específica num diapositivo. Os comentários podem ser visíveis durante a edição da apresentação, mas não aparecem quando é dada uma apresentação de diapositivos. A aplicação de apresentação decide quando apresentar comentários e determina o aspeto do elemento visual.
A especificação ISO/IEC 29500 descreve o elemento Open XML PresentationML <cm/> utilizado para representar comentários num documento PresentationML da seguinte forma:
Este elemento especifica um único comentário anexado a um diapositivo. Contém o texto do comentário, a sua posição no diapositivo e os atributos que se referem ao respetivo autor e data.
Exemplo:
<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>
A tabela seguinte lista os elementos subordinados do <cm/> elemento utilizado ao trabalhar com comentários e as classes open XML SDK que correspondem aos mesmos.
| Elemento PresentationML | Abrir Classe SDK XML |
|---|---|
<extLst/> |
ExtensionListWithModification |
<pos/> |
Position |
<text/> |
Text |
A tabela seguinte da especificação ISO/IEC 29500 descreve os atributos do <cm/> elemento.
| Atributos | Description |
|---|---|
| authorId | Este atributo especifica o autor do comentário. Refere-se ao ID de um autor na lista de autores de comentários do documento. Os valores possíveis para este atributo são definidos pelo tipo de dados Esquema unsignedInt XML W3C. |
| dt | Este atributo especifica a data e hora em que este comentário foi modificado pela última vez. Os valores possíveis para este atributo são definidos pelo tipo de dados Esquema datetime XML W3C. |
| idx | Este atributo especifica um identificador para este comentário que é exclusivo numa lista de todos os comentários deste autor neste documento. O primeiro comentário de um autor num documento tem o índice 1. Nota: uma vez que o índice é exclusivo apenas para o autor do comentário, um documento pode conter vários comentários com o mesmo índice criado por diferentes autores. Os valores possíveis para este atributo são definidos pelo ST_Index tipo simples (}19.7.3). |
Abrir Classe de Comentários do SDK XML
A classe SDK Comment OXML representa o <cm/> elemento definido no esquema Open XML File Format para documentos PresentationML. Utilize a Comment classe para manipular elementos individuais <cm/> num documento PresentationML.
As classes que representam elementos subordinados do <cm/> elemento e que, por conseguinte, estão frequentemente associadas à Comment classe são apresentadas na lista seguinte.
Classe ExtensionListWithModification
A ExtensionListWithModification classe corresponde ao <extLst/>elemento . As seguintes informações da especificação ISO/IEC 29500 introduzem o <extLst/> elemento:
Este elemento especifica a lista de extensões com a capacidade de modificação na qual são definidas todas as extensões futuras do tipo <ext/> de elemento. A lista de extensões, juntamente com as extensões futuras correspondentes, é utilizada para expandir as capacidades de armazenamento da arquitetura PresentationML. Isto permite que vários novos tipos de dados sejam armazenados nativamente dentro da arquitetura.
Observação
A utilização deste extLst elemento permite que a aplicação geradora armazene se esta propriedade de extensão foi modificada. nota de fim
Classe de Posição
A Position classe corresponde ao <pos/>elemento . As seguintes informações da especificação ISO/IEC 29500 introduzem o <pos/> elemento:
Este elemento especifica as informações de posicionamento para a colocação de um comentário numa superfície de diapositivo. Nas versões LTR da aplicação geradora, estas informações de posição devem referir-se ao ponto superior esquerdo da forma de comentário. Nas versões RTL da aplicação geradora, estas informações de posição devem referir-se ao ponto superior direito da forma de comentário.
[Nota: o ponto de ancoragem na superfície do diapositivo não é afetado por uma alteração de esquema da direita para a esquerda ou da esquerda para a direita. Este é o ponto de ancoragem que permanece o mesmo para todas as versões de idioma. nota de fim]
[Nota: uma vez que não existe um tamanho ou formatação especificado para comentários, este widget de IU utilizado para apresentar um comentário pode ter qualquer tamanho e, portanto, o ponto inferior direito da forma de comentário é determinado pela forma como a aplicação de visualização opta por apresentar comentários. nota de fim]
[Exemplo: <p:pos x="1426" y="660"/> exemplo final]
Classe de texto
A Text classe corresponde ao <text/> elemento . As seguintes informações da especificação ISO/IEC 29500 introduzem o <text/> elemento:
Este elemento especifica o conteúdo de um comentário. Este é o texto com o qual o autor anotou o diapositivo.
Os valores possíveis para este elemento são definidos pelo tipo de dados Esquema string XML W3C.
Trabalhar com a Classe de Comentários
Um comentário é uma nota de texto anexada a um diapositivo, com o objetivo principal de permitir que os leitores de uma apresentação forneçam feedback ao autor da apresentação. Cada comentário contém uma cadeia de texto não formatado e informações sobre o autor e está anexado a uma localização específica num diapositivo. Os comentários podem ser visíveis durante a edição da apresentação, mas não aparecem quando é dada uma apresentação de diapositivos. A aplicação de apresentação decide quando apresentar comentários e determina o aspeto do elemento visual.
Conforme mostrado no exemplo de código SDK Open XML que se segue, todas as instâncias da Comment classe são associadas a uma instância da SlideCommentsPart classe, que representa uma parte dos comentários de diapositivos, uma das partes de um pacote de ficheiros de apresentação PresentationML e uma parte que é necessária para cada diapositivo num ficheiro de apresentação que contém comentários. Cada Comment instância de classe também está associada a uma instância da CommentAuthor classe, que por sua vez está associada a uma peça de apresentação com o mesmo nome, representada pela CommentAuthorsPart classe . Os autores de comentários de uma apresentação são especificados numa lista de autor de comentários, representada pela classe, enquanto os CommentAuthorList comentários de cada diapositivo são listados numa lista de comentários desse diapositivo, representada pela CommentList classe .
A Comment classe, que representa o <cm/> elemento, também está associada a outras classes que representam os elementos subordinados do <cm/> elemento. Entre estas classes, conforme mostrado no seguinte exemplo de código, estão a Position classe , que especifica a posição do comentário em relação ao diapositivo, e a Text classe, que especifica o conteúdo de texto do comentário.
Open XML SDK Code Example
O seguinte segmento de código do artigo Procedimentos: Adicionar um comentário a um diapositivo numa apresentação adiciona uma nova parte de comentários a um diapositivo existente numa apresentação (se o diapositivo ainda não contiver comentários) e cria uma instância de uma classe SDK Comment Open XML na parte de comentários do diapositivo. Também adiciona uma lista de comentários à parte de comentários ao criar uma instância da CommentList classe, se ainda não existir, atribui um ID ao comentário e, em seguida, adiciona um comentário à lista de comentários ao criar uma instância da Comment classe, atribuindo os valores de atributo necessários. Além disso, cria instâncias das Position classes e Text associadas à nova Comment instância de classe. Para obter o exemplo de código completo, veja o artigo acima mencionado.