Como trabalhar com comentários

Artigo
11/16/2023

Este tópico discute a classe Open XML SDK for Office Comment e como ela 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 em PresentationML

A especificação ISO/IEC 29500 descreve a seção Comentários da estrutura Open XML PresentationML da seguinte maneira:

Um comentário é uma nota de texto anexada a um slide, com o objetivo principal de permitir que os leitores de uma apresentação forneçam comentários ao autor da apresentação. Cada comentário contém uma cadeia de texto não formatada e informações sobre seu autor e é anexado a um local específico em um slide. Os comentários podem ser visíveis durante a edição da apresentação, mas não aparecem quando uma apresentação de slides é fornecida. O aplicativo de exibição decide quando exibir comentários e determina sua aparência visual.

A especificação ISO/IEC 29500 descreve o elemento cm> Open XML PresentationML <usado para representar comentários em um documento PresentationML da seguinte maneira:

Esse elemento especifica um único comentário anexado a um slide. Ele contém o texto do comentário, sua posição no slide e atributos referentes ao 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 a seguir lista os elementos filho do <elemento cm > usado ao trabalhar com comentários e as classes SDK Open XML que correspondem a eles.

Elemento PresentationML	Classe SDK Open XML
<extLst>	ExtensionListWithModification
<Pos>	Posição
<Texto>	Text

A tabela a seguir da especificação ISO/IEC 29500 descreve os atributos do <elemento cm> .

Atributos	Description
authorId	Esse atributo especifica o autor do comentário. Refere-se à ID de um autor na lista de autores de comentários do documento. Os valores possíveis para esse atributo são definidos pelo tipo de dados W3C XML Schema unsignedInt .
Dt	Esse atributo especifica a data e a hora em que este comentário foi modificado pela última vez. Os valores possíveis para esse atributo são definidos pelo tipo de dados datetime do esquema XML W3C.
Idx	Este atributo especifica um identificador para este comentário que é exclusivo em uma lista de todos os comentários deste autor neste documento. O primeiro comentário de um autor em um documento tem índice 1. Observação: como o índice é exclusivo apenas para o autor do comentário, um documento pode conter vários comentários com o mesmo índice criado por autores diferentes. Os valores possíveis para esse atributo são definidos pelo tipo ST_Index simples (§19.7.3).

Abrir classe de comentário do SDK XML

A classe de comentário SDK oxml representa o <elemento cm> definido no esquema Open XML File Format para documentos PresentationML. Use a classe Comment para manipular elementos de cm> individuais <em um documento PresentationML.

Classes que representam elementos filho do <elemento cm> e que, portanto, são comumente associadas à classe Comment são mostradas na lista a seguir.

Classe ExtensionListWithModification

A classe ExtensionListWithModification corresponde ao <elemento extLst>. As seguintes informações da especificação ISO/IEC 29500 introduzem o <elemento extLst> :

Esse elemento especifica a lista de extensão com capacidade de modificação na qual todas as extensões futuras do tipo <de elemento são> definidas. A lista de extensão junto com as extensões futuras correspondentes é usada para estender os recursos de armazenamento da estrutura PresentationML. Isso permite que vários novos tipos de dados sejam armazenados nativamente dentro da estrutura.

Observação

O uso desse elemento extLst permite que o aplicativo gerador armazene se essa propriedade de extensão foi modificada. nota final

Classe Position

A classe Position corresponde ao <elemento pos>. As seguintes informações da especificação ISO/IEC 29500 introduzem o <elemento pos> :

Esse elemento especifica as informações de posicionamento para o posicionamento de um comentário em uma superfície de slide. Nas versões LTR do aplicativo gerador, essas informações de posição devem se referir ao ponto superior esquerdo da forma de comentário. Nas versões RTL do aplicativo gerador, essas informações de posição devem se referir ao ponto superior direito da forma de comentário.

[Observação: o ponto de ancoragem na superfície do slide não é afetado por uma alteração de layout da direita para a esquerda ou da esquerda para a direita. Esse é o ponto de ancoragem que permanece o mesmo para todas as versões de idioma. nota final]

[Observação: como não há tamanho ou formatação especificados para comentários, este widget de interface do usuário usado para exibir um comentário pode ser qualquer tamanho e, portanto, o ponto inferior direito da forma de comentário é determinado pela forma como o aplicativo de exibição opta por exibir comentários. nota final]

[Exemplo: <p:pos x="1426" y="660"/> exemplo final]

Classe de texto

A classe Text corresponde ao <elemento de texto>. As seguintes informações da especificação ISO/IEC 29500 introduzem o <elemento de texto> :

Esse elemento especifica o conteúdo de um comentário. Este é o texto com o qual o autor anotou o slide.

Os valores possíveis para esse elemento são definidos pelo tipo de dados de cadeia de caracteres W3C XML Schema.

Trabalhando com a Classe de Comentário

Um comentário é uma nota de texto anexada a um slide, com o objetivo principal de permitir que os leitores de uma apresentação forneçam comentários ao autor da apresentação. Cada comentário contém uma cadeia de caracteres de texto não formatada e informações sobre seu autor e é anexado a um local específico em um slide. Os comentários podem ser visíveis durante a edição da apresentação, mas não aparecem quando uma apresentação de slides é fornecida. O aplicativo de exibição decide quando exibir comentários e determina sua aparência visual.

Conforme mostrado no exemplo de código SDK do Open XML que se segue, cada instância da classe Comment está associada a uma instância da classe SlideCommentsPart , que representa uma parte de comentários de slide, uma das partes de um pacote de arquivo de apresentação PresentationML e uma parte necessária para cada slide em um arquivo de apresentação que contém comentários. Cada instância da classe Comment também está associada a uma instância da classe CommentAuthor , que por sua vez está associada a uma parte de apresentação igualmente nomeada, representada pela classe CommentAuthorsPart . Os autores de comentários de uma apresentação são especificados em uma lista de autores de comentários, representada pela classe CommentAuthorList , enquanto os comentários de cada slide são listados em uma lista de comentários para esse slide, representado pela classe CommentList .

A classe Comment , que representa o <elemento cm> , também está associada a outras classes que representam os elementos filho do <elemento cm> . Entre essas classes, conforme mostrado no exemplo de código a seguir, estão a classe Position , que especifica a posição do comentário em relação ao slide, e a classe Text , que especifica o conteúdo de texto do comentário.

Abrir o exemplo de código do SDK XML

O seguinte segmento de código do artigo Como: Adicionar um comentário a um slide em uma apresentação adiciona uma nova parte de comentários a um slide existente em uma apresentação (se o slide ainda não contiver comentários) e cria uma instância de uma classe Open XML SDK Comment na parte de comentários do slide. Ele também adiciona uma lista de comentários à parte de comentários criando uma instância da classe CommentList , se ainda não existir; atribui uma ID ao comentário; e, em seguida, adiciona um comentário à lista de comentários criando uma instância da classe Comment , atribuindo os valores de atributo necessários. Além disso, ele cria instâncias das classes Posição e Texto associadas à nova instância da classe Comentário . Para obter o exemplo de código completo, consulte o artigo acima mencionado.

C#
Visual Basic

// 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 });

' Declare a comments part.
Dim commentsPart As SlideCommentsPart

' Verify that there is a comments part in the first slide part.
If slidePart1.GetPartsOfType(Of SlideCommentsPart)().Count() = 0 Then

  ' If not, add a new comments part.
  commentsPart = slidePart1.AddNewPart(Of SlideCommentsPart)()
Else

  ' Else, use the first comments part in the slide part.
  commentsPart =
slidePart1.GetPartsOfType(Of SlideCommentsPart)().First()
End If

' If the comment list does not exist.
If (commentsPart.CommentList Is Nothing) Then

  ' Add a new comments list.
  commentsPart.CommentList = New CommentList()
End If

' Get the new comment ID.
Dim commentIdx As UInteger
If author.LastIndex Is Nothing Then
  commentIdx = 1
Else
  commentIdx = CType(author.LastIndex, UInteger) + 1
End If

author.LastIndex = commentIdx

' Add a new comment.
Dim comment As Comment =
(commentsPart.CommentList.AppendChild(Of Comment)(New Comment() _
With {.AuthorId = authorId, .Index = commentIdx, .DateTime = DateTime.Now}))

' Add the position child node to the comment element.
comment.Append(New Position() With
  {.X = 100, .Y = 200}, New Text() With {.Text = text})

PresentationML gerado

Quando o código SDK Open XML em Como: Adicionar um comentário a um slide em uma apresentação é executado, incluindo o segmento mostrado neste artigo, o XML a seguir é gravado em uma nova CommentAuthors.xml parte no documento PresentationML existente referenciado no código, supondo que o documento não continha comentários ou autores de comentários antes do código ser executado.

    <?xml version="1.0" encoding="utf-8"?>
    <p:cmAuthorLst xmlns:p="https://schemas.openxmlformats.org/presentationml/2006/main">
      <p:cmAuthor id="1"
                  name="userName"
                  initials="userInitials"
                  lastIdx="1"
                  clrIdx="0" />
    </p:cmAuthorLst>

Além disso, o XML a seguir é gravado em uma nova Comments.xml parte no documento PresentationML existente referenciado no código no artigo.

    <?xml version="1.0" encoding="utf-8"?>
    <p:cmLst xmlns:p="https://schemas.openxmlformats.org/presentationml/2006/main">
      <p:cm authorId="1"
            dt="2010-09-07T16:01:18.5351166-07:00"
            idx="1">
        <p:pos x="100"
               y="200" />
        <p:text>commentText</p:text>
      </p:cm>
    </p:cmLst>

Confira também

Sobre o SDK Open XML para Office Como criar uma apresentação fornecendo um nome de arquivo Como adicionar um comentário a um slide em uma apresentação Como excluir todos os comentários de um autor de todos os slides em uma apresentação

Compartilhar via