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 diselesaikan. 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 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 perubahan yang disarankan pada pemformatan dan presentasi, bukan perubahan pada konten.

Tidak seperti penyisipan atau penghapusan teks, hal ini tidak mengimbangi indeks—meskipun dapat memecah TextRun menjadi beberapa 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 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 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.