Menggunakan saran

Google Dokumen memungkinkan kolaborator membuat saran yang merupakan pengeditan yang ditangguhkan secara efektif dan menunggu persetujuan.

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

  • Dapatkan konten dengan SUGGESTIONS_INLINE, sehingga teks yang menunggu penghapusan atau penyisipan akan 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 SuggestionsViewMode penting adalah karena 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 dari 51 dan endIndex berhenti di 81. Tanpa saran, startIndex dan endIndex berkisar antara 32–62.

Mendapatkan konten tanpa saran

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

JavaPython

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

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

Menghapus parameter SuggestionsViewMode sama dengan memberikan DEFAULT_FOR_CURRENT_ACCESS sebagai nilai parameter.

Saran gaya

Dokumen juga dapat memiliki saran gaya. Ini adalah perubahan yang disarankan untuk format dan presentasi, bukan perubahan pada konten.

Tidak seperti penyisipan atau penghapusan teks, tindakan ini tidak akan mengimbangi indeks—meskipun tindakan ini dapat memecah TextRun menjadi bagian 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 cara gaya teks setelah perubahan yang disarankan, tetapi tidak menyebutkan apa yang berubah.

  • textStyleSuggestionState, yang menunjukkan cara saran mengubah kolom textStyle.

Anda dapat melihatnya di ekstrak tab dokumen berikut, yang menyertakan 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] }

Pada contoh di atas, paragraf terdiri dari 3 teks yang berjalan, dimulai dari baris 6, 14, dan 50. Periksa teks tengah yang dijalankan:

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

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