Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Zarządzanie komentarzami

Arkusze Google umożliwiają współpracę użytkowników dzięki dodawaniu komentarzy do określonych komórek.

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

Czytanie komentarzy

Gdy używasz metody get w zasobie spreadsheets aby pobrać arkusz kalkulacyjny, 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 sheets.commentAnchors.

Ten przykładowy kod pokazuje, jak użyć żądania get, które pobiera wątki komentarzy i ich kotwice (zakresy siatki) z arkusza kalkulacyjnego:

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)

W odpowiedzi komentarze są zwracane w 2 miejscach:

Globalna tablica comments zawierająca CommentThread obiekty.
Tablica sheets.commentAnchors zawierająca CommentAnchor obiekty, które mapują identyfikatory kotwic komentarzy na lokalizacje komórek (zakresy siatki).

Filtrowanie komentarzy według zakresu lub arkusza

Podczas pobierania arkusza kalkulacyjnego możesz filtrować zwracane dane, określając zakresy (za pomocą ranges parametru zapytania w metodzie spreadsheets.get) lub arkusze (za pomocą dataFilters pola w treści żądania metody spreadsheets.getByDataFilter).

Jeśli filtrujesz według zakresu lub arkusza: zwracane są tylko wątki komentarzy zakotwiczone w określonych zakresach lub arkuszach. Komentarze bez kotwic (np. komentarze, których pierwotne współrzędne komórki zostały usunięte) nie są uwzględniane.
Jeśli nie filtrujesz według zakresu lub arkusza: zwracane są wszystkie wątki komentarzy, w tym komentarze bez kotwic.

Przykładowa odpowiedź

Ta przykładowa odpowiedź JSON pokazuje wątek komentarza zakotwiczony w komórce A1 (wiersz 0, kolumna 0) w arkuszu o identyfikatorze 0:

{
  "spreadsheetId": "SPREADSHEET_ID",
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Sheet1"
      },
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "range": {
            "sheetId": 0,
            "startRowIndex": 0,
            "endRowIndex": 1,
            "startColumnIndex": 0,
            "endColumnIndex": 1
          }
        }
      ]
    }
  ],
  "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ą metody batchUpdate w zasobie spreadsheets.

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 arkusza kalkulacyjnego, użyj InsertCommentRequest obiektu. Musisz podać treść komentarza i the coordinate gdzie komentarz jest zakotwiczony, używając a GridCoordinate obiekt.

Ten przykładowy kod JSON pokazuje, jak dodać nieprzypisany wątek komentarza do komórki B2 (wiersz 1, kolumna 1) w arkuszu o identyfikatorze 0:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

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

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review the data in this cell.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

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 the post gdzie 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.

Ten przykładowy kod JSON pokazuje, jak odpowiedzieć na istniejący wątek komentarza:

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

Ten przykładowy kod JSON pokazuje, jak rozwiązać wątek komentarza (który nie wymaga pola content):

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

Ten przykładowy kod JSON pokazuje, jak ponownie przypisać wątek komentarza:

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

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ść content w postaci zwykłego tekstu.

Ten przykładowy kod 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.

Ten przykładowy kod 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. wstawiania komentarzy lub dodawania odpowiedzi), mogą powodować częściowe awarie. W takich przypadkach zmiany w modelu arkusza kalkulacyjnego (np. aktualizowanie wartości komórek lub dodawanie arkuszy) mogą zostać zapisane, ale powiązane komentarze mogą nie zostać zapisane.

Aby sprawdzić, czy aktualizacje komentarzy zostały zastosowane, sprawdź commentUpdateState pole w treści odpowiedzi metody spreadsheets.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 arkuszu kalkulacyjnym mogły zostać zapisane.