Menggunakan saran

Google Dokumen memungkinkan kolaborator membuat saran yang secara efektif menunda pengeditan yang menunggu persetujuan.

Saat Anda menggunakan metode documents.get untuk mengambil konten dokumen, konten tersebut mungkin menyertakan saran yang belum terselesaikan. 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.
  • Dapatkan konten sebagai pratinjau dengan semua saran diterima.
  • Mendapatkan konten sebagai pratinjau, tanpa saran, dan 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 bahwa indeks dalam respons dapat bervariasi bergantung pada apakah ada saran, seperti yang ditunjukkan di bawah ini.

Konten dengan saran Konten tanpa saran 
{
 "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"
  }
 }
},


{
 "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"
  }
 }
},

Pada respons di atas, paragraf yang berisi baris "Teks mengikuti 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 akan memiliki rentang 32–62.

Dapatkan 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.

Java

string akhir SUGGEST_MODE = "PR_WITHOUT_SARAN"; Dokumen dokumen = service.documents().get(DOCUMENT_ID).setSuggestionsViewMode(SUGGEST_MODE).execute();

Python

SUGGEST_MODE="PRATINJAU_SARAN" hasil = service.documents().get(documentId=DOCUMENT_ID, suggestionsViewMode=SUGGEST_MODE).execute()

Menghapus parameter SuggestionsViewMode sama dengan memberikan DEFAULT_FOR_CURRENT_ACCESS sebagai parameter value.

Saran gaya

Dokumen juga dapat memiliki saran gaya. Perubahan ini disarankan pada format dan presentasi, bukan perubahan konten.

Tidak seperti penyisipan atau penghapusan teks, perubahan ini tidak mengimbangi indeks—meskipun dapat memecah TextRun menjadi bagian yang lebih kecil—tetapi cukup tambahkan 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 menjelaskan perubahan apa yang terjadi.

  • textStyleSuggestionState, yang menunjukkan cara saran mengubah kolom textStyle.

Anda dapat melihatnya di ekstrak 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 berjalan, mulai dari baris 6, 14, dan 50. Periksa teks tengah yang dijalankan:

  • Baris 16: Ada objek suggestedTextStyleChanges.
  • Baris 18: textStyle menentukan berbagai pemformatan.
  • Baris 36: textStyleSuggestionState memberi tahu Anda bahwa hanya bagian tebal dari spesifikasi ini yang merupakan saran.
  • Baris 42: Gaya miring dari eksekusi 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.