Zarządzanie komentarzami

Prezentacje Google umożliwiają współpracę użytkowników dzięki dodawaniu komentarzy do slajdów i elementów strony.

Z tego dokumentu dowiesz się, jak za pomocą interfejsu Google Slides API programowo odczytywać, tworzyć, odpowiadać na komentarze, aktualizować je i usuwać.

Czytanie komentarzy

Gdy używasz metody get w zasobie presentations do pobierania prezentacji, wątki komentarzy i kotwice są domyślnie pomijane.

Aby uwzględnić komentarze w odpowiedzi, ustaw commentsViewMode parametr zapytania na COMMENTS_VIEW_MODE_INCLUDED. Jeśli użytkownik wywołujący ma dostęp do komentarzy w pliku, ustawienie parametru zapytania na COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS również spowoduje zwrócenie komentarzy.

W odpowiedzi zwracane są pola comments i commentAnchors.

Poniższy przykład kodu pokazuje, jak użyć żądania get, które pobiera wątki komentarzy i ich kotwice z prezentacji:

GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=presentationId,comments,slides(objectId,commentAnchors)

W odpowiedzi komentarze są zwracane w 2 lokalizacjach:

  • Globalna tablica comments zawierająca CommentThread obiekty.
  • Tablica commentAnchors zawierająca CommentAnchor obiekty, które mapują identyfikatory kotwic komentarzy na lokalizacje strony lub elementu strony (kotwice obiektów).

Czytanie komentarzy na określonej stronie

Możesz też pobrać komentarze i kotwice do konkretnej strony za pomocą metody pages.get w zasobie presentations.pages. Ustaw parametr zapytania commentsViewMode, aby uwzględnić komentarze do konkretnego celu strony:

GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID/pages/PAGE_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=objectId,comments,commentAnchors

Przykładowa odpowiedź

Poniższa przykładowa odpowiedź JSON przedstawia wątek komentarza zakotwiczony w zakresie tekstu w kształcie na stronie slajdu:

{
  "presentationId": "PRESENTATION_ID",
  "slides": [
    {
      "objectId": "SLIDE_PAGE_ID",
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "objectAnchors": [
            {
              "objectId": "SHAPE_OBJECT_ID",
              "shapeTextAnchors": {
                "ranges": [
                  {
                    "startIndex": 0,
                    "endIndex": 12
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "comments": [
    {
      "commentId": "COMMENT_ID",
      "anchorId": "ANCHOR_ID",
      "headPost": {
        "postId": "POST_ID",
        "content": "This is a comment thread head post.",
        "contentHtml": "The content of the post as HTML.",
        "author": {
          "displayName": "DISPLAY_NAME",
          "me": true,
          "user": "users/USER"
        },
        "createTime": "2026-07-01T10:13:12Z",
        "updateTime": "2026-07-01T10:13:12Z"
      },
      "replies": [
        {
          "postId": "REPLY_POST_ID",
          "content": "This is a reply to the comment.",
          "author": {
            "displayName": "DISPLAY_NAME",
            "me": false
          },
          "createTime": "2026-07-01T10:15:00Z",
          "updateTime": "2026-07-01T10:15:00Z"
        }
      ],
      "status": "OPEN"
    }
  ],
  "commentsViewMode": "COMMENTS_VIEW_MODE_INCLUDED"
}

Tworzenie komentarzy i zarządzanie nimi

Możesz programowo dodawać, edytować i usuwać komentarze lub odpowiedzi za pomocą batchUpdate metody w presentations zasobie.

Podczas wykonywania zbiorczych aktualizacji obejmujących komentarze należy monitorować potencjalne częściowe awarie. Więcej informacji znajdziesz w sekcji Stan aktualizacji komentarza.

Wstawianie komentarza

Aby wstawić wątek komentarza do prezentacji, użyj InsertCommentRequest obiektu. Musisz podać treść komentarza i lokalizację kotwicy. Lokalizacja kotwicy musi określać jedną z tych opcji:

  • objectId: identyfikator obiektu strony slajdu lub elementu strony (np. kształtu lub tabeli), do którego ma być zakotwiczony komentarz.
  • shapeTextAnchor: kotwiczy komentarz do zakresu tekstu w kształcie.
  • tableCellTextAnchor: kotwiczy komentarz do zakresu tekstu w komórce tabeli.
  • tableAnchor: kotwiczy komentarz do zakresu komórek w tabeli.

Poniższy przykład JSON pokazuje, jak dodać wątek komentarza zakotwiczony na stronie slajdu:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "objectId": "SLIDE_PAGE_ID"
      }
    }
  ]
}

Możesz przypisać komentarz do konkretnego użytkownika, podając jego adres e-mail w polu assigneeEmailAddress:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this slide.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "objectId": "SLIDE_PAGE_ID"
      }
    }
  ]
}

Dodawanie odpowiedzi lub podejmowanie działań

Aby odpowiedzieć na wątek komentarza, rozwiązać go lub ponownie otworzyć, użyj obiektu AddCommentReplyRequest.

Musisz podać commentId i post , w którym odpowiedź jest reprezentowana przez obiekt Post.

Obiekt Post zawiera content odpowiedzi i opcjonalnie może określać commentAction (w tym działanie RESOLVE lub REOPEN wątku komentarza). Jest reprezentowany przez CommentActionType obiekt.

Możesz też ponownie przypisać wątek komentarza, podając nowy assigneeEmail w obiekcie Post.

Poniższy przykład JSON pokazuje, jak odpowiedzieć na istniejący wątek komentarza:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

Poniższy przykład JSON pokazuje, jak rozwiązać wątek komentarza:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

Edytowanie posta

Aby edytować treść posta, którego jesteś autorem, użyj UpdateCommentPostRequest obiektu. Musisz określić commentId wątku, postId posta który chcesz edytować, oraz nową treść w postaci zwykłego tekstu content.

Poniższy przykład JSON pokazuje, jak edytować posta:

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "COMMENT_ID",
        "postId": "POST_ID",
        "content": "This is the updated comment text."
      }
    }
  ]
}

Usuwanie komentarzy i odpowiedzi

Aby usunąć komentarze i odpowiedzi, masz 2 opcje:

  • Usuwanie wątku komentarza: aby usunąć cały CommentThread, użyj obiektu DeleteCommentRequest. Wątek komentarza możesz usunąć tylko wtedy, gdy jesteś autorem wątku headPost w obiekcie CommentThread.

  • Usuwanie odpowiedzi: aby usunąć konkretną odpowiedź Post z CommentThread, użyj DeleteCommentReplyRequest obiektu. Możesz usuwać tylko odpowiedzi, których jesteś autorem. Nie możesz usuwać postów z odpowiedziami, które zawierają commentAction lub assigneeEmail.

Poniższy przykład JSON pokazuje, jak usunąć wątek komentarza:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

Stan aktualizacji komentarza

Żądania, które wymagają zapisania wątków komentarzy (np. wstawianie komentarzy lub dodawanie odpowiedzi), mogą powodować częściowe awarie. W takich przypadkach zmiany w modelu prezentacji (np. aktualizowanie treści slajdu lub tła) mogą zostać zapisane, ale powiązane z nimi komentarze mogą nie zostać zapisane.

Aby sprawdzić, czy aktualizacje komentarzy zostały zastosowane, sprawdź pole commentUpdateState w treści odpowiedzi metody presentations.batchUpdate. Pole jest reprezentowane przez CommentUpdateState obiekt.

W CommentUpdateState zwracane są te stany:

  • NO_UPDATES_REQUESTED: w operacji zbiorczej nie zażądano żadnych aktualizacji komentarzy.
  • ALL_SAVED: wszystkie żądane aktualizacje komentarzy zostały zastosowane.
  • ALL_FAILED_UNKNOWN_REASON: nie udało się zapisać wszystkich żądanych aktualizacji komentarzy, mimo że inne zmiany w prezentacji mogły zostać zapisane.