Menggunakan komentar dan saran

Google Dokumen memungkinkan kolaborator berkolaborasi dengan menulis komentar dan membuat saran yang berfungsi sebagai hasil edit yang ditangguhkan dan menunggu persetujuan.

Anda dapat menggunakan API untuk melihat perubahan yang disarankan secara inline dalam teks dokumen. Di Pratinjau Developer, Anda juga dapat membaca, membuat, membalas, memperbarui, atau menghapus rangkaian komentar dan saran secara terprogram.

Saat Anda menggunakan metode documents.get untuk mengambil konten dokumen, konten tersebut mungkin menyertakan saran yang belum diselesaikan. Untuk mengontrol cara documents.get menampilkan saran, gunakan parameter SuggestionsViewMode opsional. Kondisi filter berikut tersedia dengan parameter ini:

  • Mendapatkan konten dengan SUGGESTIONS_INLINE, sehingga teks yang menunggu penghapusan atau penyisipan muncul dalam dokumen.
  • Mendapatkan konten sebagai pratinjau dengan semua saran diterima.
  • Mendapatkan konten sebagai pratinjau, tanpa saran, dengan semua saran ditolak.

Jika Anda tidak memberikan SuggestionsViewMode, Google Docs API akan menggunakan setelan default yang sesuai dengan hak istimewa pengguna saat ini.

Saran & indeks

Salah satu alasan pentingnya SuggestionsViewMode adalah indeks dalam respons dapat bervariasi, bergantung pada apakah ada saran, seperti yang ditunjukkan di bawah.

Konten dengan saran Konten tanpa saran 
{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 51,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 50,
          "textRun": {
           "content": "Suggested insertion",
           "suggestedInsertionIds": [
            "suggest.vcti8ewm4mww"
           ],
           "textStyle": {}
          }
         },
         {
          "startIndex": 50,
          "endIndex": 51,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 51,
       "endIndex": 81,
       "paragraph": {
        "elements": [
         {
          "startIndex": 51,
          "endIndex": 81,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},


{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 32,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 32,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 32,
       "endIndex": 62,
       "paragraph": {
        "elements": [
         {
          "startIndex": 32,
          "endIndex": 62,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

Dalam respons di atas, paragraf yang berisi baris "Teks setelah saran" menunjukkan perbedaan saat menggunakan SuggestionsViewMode. Dengan nilai yang ditetapkan ke SUGGESTIONS_INLINE, startIndex dari ParagraphElement dimulai pada 51 dan endIndex berhenti pada 81. Tanpa saran, rentang startIndex dan endIndex adalah 32–62.

Mendapatkan konten tanpa saran

Contoh kode parsial berikut menunjukkan cara mendapatkan dokumen sebagai pratinjau dengan semua saran ditolak (jika ada) dengan menyetel parameter SuggestionsViewMode ke PREVIEW_WITHOUT_SUGGESTIONS.

Java

final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();

Python

SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"
result = (
  service.documents()
  .get(
      documentId=DOCUMENT_ID,
      includeTabsContent=True,
      suggestionsViewMode=SUGGEST_MODE,
  )
  .execute()
)

Menghilangkan parameter SuggestionsViewMode sama dengan memberikan DEFAULT_FOR_CURRENT_ACCESS sebagai nilai parameter.

Saran gaya

Dokumen juga dapat memiliki saran gaya. Ini adalah saran perubahan pada pemformatan dan presentasi, bukan perubahan pada konten.

Tidak seperti penyisipan atau penghapusan teks, hal ini tidak mengimbangi indeks—meskipun dapat memecah TextRun menjadi potongan yang lebih kecil—tetapi hanya menambahkan anotasi tentang perubahan gaya yang disarankan.

Salah satu anotasi tersebut adalah SuggestedTextStyle, yang terdiri dari 2 bagian:

  • textStyle, yang menjelaskan gaya teks setelah perubahan yang disarankan, tetapi tidak mengatakan apa yang berubah.

  • textStyleSuggestionState, yang menunjukkan cara saran mengubah kolom textStyle.

Anda dapat melihatnya di ekstrak tab dokumen berikut, yang mencakup perubahan gaya yang disarankan:

[01] "paragraph": {
[02]    "elements": [
[03]        {
[04]            "endIndex": 106,
[05]            "startIndex": 82,
[06]            "textRun": {
[07]                "content": "Some text that does not ",
[08]                "textStyle": {}
[09]            }
[10]        },
[11]        {
[12]            "endIndex": 115,
[13]            "startIndex": 106,
[14]            "textRun": {
[15]                "content": "initially",
[16]                "suggestedTextStyleChanges": {
[17]                    "suggest.xymysbs9zldp": {
[18]                        "textStyle": {
[19]                            "backgroundColor": {},
[20]                            "baselineOffset": "NONE",
[21]                            "bold": true,
[22]                            "fontSize": {
[23]                                "magnitude": 11,
[24]                                "unit": "PT"
[25]                            },
[26]                            "foregroundColor": {
[27]                                "color": {
[28]                                    "rgbColor": {}
[29]                                }
[30]                            },
[31]                            "italic": false,
[32]                            "smallCaps": false,
[33]                            "strikethrough": false,
[34]                            "underline": false
[35]                        },
[36]                        "textStyleSuggestionState": {
[37]                            "boldSuggested": true,
[38]                            "weightedFontFamilySuggested": true
[39]                        }
[40]                    }
[41]                },
[42]                "textStyle": {
[43]                    "italic": true
[44]                }
[45]            }
[46]        },
[47]        {
[48]            "endIndex": 143,
[49]            "startIndex": 115,
[50]            "textRun": {
[51]                "content": " contain any boldface text.\n",
[52]                "textStyle": {}
[53]            }
[54]        }
[55]    ],
[56]    "paragraphStyle": {
[57]        "direction": "LEFT_TO_RIGHT",
[58]        "namedStyleType": "NORMAL_TEXT"
[59]    }
[60] }

Dalam contoh di atas, paragraf terdiri dari 3 rangkaian teks, yang dimulai pada baris 6, 14, dan 50. Periksa jalannya teks di tengah:

  • Baris 16: Ada objek suggestedTextStyleChanges.
  • Baris 18: textStyle menentukan berbagai pemformatan.
  • Baris 36: textStyleSuggestionState memberi tahu Anda bahwa hanya bagian yang dicetak tebal dari spesifikasi ini yang merupakan saran.
  • Baris 42: Gaya miring pada rangkaian teks ini adalah bagian dari dokumen saat ini (dan tidak terpengaruh oleh saran).

Hanya fitur gaya yang ditetapkan ke true di textStyleSuggestionState yang menjadi bagian dari saran.

Membuat dan mengelola komentar

Anda dapat menambahkan komentar dan balasan, mengedit komentar, serta menghapus komentar atau balasan secara terprogram menggunakan metode documents.batchUpdate.

Saat melakukan update batch yang melibatkan komentar atau saran, Anda harus memantau potensi kegagalan sebagian. Untuk mengetahui informasi selengkapnya, lihat Status pembaruan komentar dan saran.

Menyisipkan komentar

Untuk menyisipkan rangkaian komentar, gunakan objek InsertCommentRequest. Anda harus memberikan konten teks komentar, dan lokasi penanda (seperti rentang) tempat komentar dilampirkan.

Contoh JSON berikut menambahkan rangkaian komentar yang tidak ditetapkan ke rentang yang ditentukan:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added via the API.",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

Anda dapat menetapkan komentar kepada pengguna tertentu dengan memberikan emailnya di kolom assigneeEmailAddress:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this paragraph.",
        "assigneeEmailAddress": "user@example.com",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

Menambahkan balasan atau mengambil tindakan

Untuk membalas rangkaian pesan komentar atau saran, atau untuk menyelesaikan atau membuka kembali rangkaian pesan, gunakan AddCommentReplyRequest.

Balasan direpresentasikan oleh objek Post. Objek Post berisi content balasan dan secara opsional dapat menentukan commentAction (untuk RESOLVE atau REOPEN rangkaian pesan).

Contoh berikut membalas rangkaian komentar yang ada:

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

Contoh berikut menyelesaikan rangkaian komentar, yang tidak memerlukan konten:

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

Mengedit postingan

Untuk mengedit konten teks postingan yang Anda buat, gunakan UpdateCommentPostRequest. Anda harus menentukan ID rangkaian pesan (commentId atau suggestionId), postId postingan yang ingin Anda edit, dan content teks biasa yang baru.

Perhatikan bahwa Anda tidak dapat mengedit postingan utama dalam rangkaian saran (karena postingan tersebut dibuat oleh pengeditan mode saran).

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

Menghapus komentar dan balasan

  • Menghapus rangkaian komentar: Untuk menghapus seluruh rangkaian komentar, gunakan DeleteCommentRequest. Anda hanya dapat menghapus rangkaian komentar jika Anda adalah penulis postingan utama rangkaian komentar tersebut.
  • Menghapus balasan: Untuk menghapus postingan balasan tertentu, gunakan DeleteCommentReplyRequest. Anda hanya dapat menghapus balasan yang Anda tulis. Anda tidak dapat menghapus postingan balasan yang berisi tindakan atau penerima tugas.

Contoh berikut menghapus rangkaian komentar:

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

Menulis saran dan mengelola rangkaian saran

Anda dapat menulis hasil edit sebagai saran, bukan hasil edit langsung, dan menerima, menolak, atau menghapus rangkaian saran secara terprogram.

Saat melakukan update batch yang melibatkan saran, Anda harus memantau potensi kegagalan sebagian. Untuk mengetahui informasi selengkapnya, lihat Status pembaruan komentar dan saran.

Membuat saran menggunakan mode saran

Untuk menerapkan pengeditan sebagai saran, tetapkan kolom writeMode objek WriteControl ke SUGGEST dalam permintaan update batch Anda. Semua pembaruan dalam permintaan diproses sebagai saran.

{
  "requests": [
    {
      "insertText": {
        "text": "suggested insertion text",
        "location": {
          "index": 1
        }
      }
    }
  ],
  "writeControl": {
    "writeMode": "SUGGEST"
  }
}

Permintaan yang tidak didukung dalam mode saran

Saat menggunakan WriteMode.SUGGEST, jenis permintaan berikut tidak didukung dan akan menampilkan error:

  • AddDocumentTab
  • CreateNamedRange
  • DeleteFooter
  • DeleteHeader
  • DeleteNamedRange
  • DeleteTab
  • UpdateDocumentTabProperties
  • UpdateTableColumnProperties

Selain itu, Anda tidak dapat menyarankan perubahan pada format dokumen atau setelan header/footer. Di UpdateDocumentStyle, saran tidak didukung untuk jenis gaya berikut:

  • documentFormat
  • useEvenPageHeaderFooter
  • useFirstPageHeaderFooter

Menerima, menolak, atau menghapus rangkaian saran

Anda dapat mengelola rangkaian saran menggunakan permintaan berikut:

  • Terima saran: Gunakan AcceptSuggestionRequest untuk menerima saran. Tindakan ini memerlukan akses edit ke dokumen.
  • Menolak saran: Gunakan RejectSuggestionRequest untuk menolak saran. Tindakan ini memerlukan akses edit ke dokumen atau Anda harus menjadi penulis saran.
  • Menghapus saran: Gunakan DeleteSuggestionRequest untuk menghapus saran. Tindakan ini mengharuskan Anda menjadi penulis saran.

Contoh berikut menerima thread saran:

{
  "requests": [
    {
      "acceptSuggestion": {
        "suggestionId": "suggestion_thread_id"
      }
    }
  ]
}

Status pembaruan komentar dan saran

Permintaan yang memerlukan penyimpanan rangkaian pesan komentar atau saran (seperti menyisipkan komentar, menambahkan balasan, atau membuat saran) mungkin mengalami kegagalan sebagian. Dalam kasus ini, perubahan model dokumen (seperti penyisipan atau penghapusan teks) mungkin berhasil dilakukan pada model Dokumen, tetapi komentar atau saran terkait mungkin gagal disimpan.

Anda dapat memverifikasi apakah pembaruan komentar atau saran berhasil diterapkan dengan memeriksa kolom commentUpdateState di BatchUpdateDocumentResponse.

Status berikut ditampilkan di CommentUpdateState:

  • NO_UPDATES_REQUESTED: Tidak ada pembaruan komentar atau saran yang diminta dalam operasi batch.
  • ALL_SAVED: Semua pembaruan komentar atau saran yang diminta berhasil diterapkan.
  • ALL_FAILED_UNKNOWN_REASON: Semua pembaruan komentar atau saran yang diminta gagal disimpan, meskipun perubahan model Dokumen mungkin telah dilakukan.