Menggunakan saran

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

Saat Anda menggunakan documents.get untuk mengambil konten dokumen, konten tersebut mungkin menyertakan ejaan atau mendapatkan saran gaya. Untuk mengontrol cara documents.get merepresentasikan saran, gunakan opsional SuggestionsViewMode . Kondisi filter berikut tersedia dengan parameter ini:

  • Dapatkan konten dengan SUGGESTIONS_INLINE, jadi teks yang menunggu penghapusan atau penyisipan akan muncul di dokumen.
  • Dapatkan konten sebagai pratinjau dengan semua saran diterima.
  • Dapatkan konten sebagai pratinjau, tanpa saran, dengan semua saran ditolak.

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

Saran & indeks

Salah satu alasan SuggestionsViewMode penting adalah karena indeks di respons dapat bervariasi bergantung pada apakah ada saran atau tidak, seperti yang ditunjukkan di bawah ini.

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 berisi baris "Teks yang mengikuti saran" menunjukkan perbedaannya saat menggunakan SuggestionsViewMode. Dengan nilai ditetapkan ke SUGGESTIONS_INLINE, startIndex dari ParagraphElement dimulai di 51 dan endIndex berhenti di 81. Tanpa saran, startIndex dan endIndex 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 menyetel SuggestionsViewMode parameter 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 menyediakan DEFAULT_FOR_CURRENT_ACCESS sebagai nilai parameter.

Saran gaya

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

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

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

  • textStyle, yang menjelaskan cara penataan gaya teks setelah kode yang disarankan berubah, tetapi tidak mengatakan apa yang berubah.

  • textStyleSuggestionState, yang menunjukkan perubahan saran kolom textStyle.

Anda dapat melihatnya dalam 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] }

Dalam contoh di atas, paragraf terdiri dari 3 {i>text run<i}, mulai dari baris 6, 14, dan 50. Periksa berjalannya teks di tengah:

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