Google 文件可讓協作者提出建議，這些建議會有效延後編輯，等待核准。
使用 documents.get 方法擷取文件內容時，內容可能會包含未解決的建議。如要控制 documents.get 如何呈現建議，請使用選用的 SuggestionsViewMode 參數。這個參數可搭配下列篩選器條件使用：
- 使用
SUGGESTIONS_INLINE取得內容，以便在文件中顯示待刪除或插入的文字。 - 取得內容預覽畫面，並接受所有建議。
- 取得內容預覽畫面，不顯示任何建議，並拒絕所有建議。
如果您未提供 SuggestionsViewMode，Google 文件 API 會使用與目前使用者權限相符的預設設定。
建議與索引
SuggestionsViewMode 之所以重要，是因為回應中的索引可能會因是否有建議而有所不同，如下所示。
| 含有建議的內容 | 沒有建議的內容 |
|---|---|
{
"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"
}
}
}
]
}
}
}
]
},
|
在上述回應中，段落包含「建議後面的文字」行，顯示使用 SuggestionsViewMode 時的差異。將值設為 SUGGESTIONS_INLINE 時，ParagraphElement 的 startIndex 會從 51 開始，endIndex 則會在 81 停止。在沒有建議的情況下，startIndex 和 endIndex 的範圍為 32 到 62。
取得不含建議的內容
以下程式碼片段顯示如何將文件設為預覽畫面，並將 SuggestionsViewMode 參數設為 PREVIEW_WITHOUT_SUGGESTIONS，拒絕所有建議 (如有)。
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() )
省略 SuggestionsViewMode 參數等同於提供 DEFAULT_FOR_CURRENT_ACCESS 做為參數值。
建議樣式
文件也可能會顯示風格建議。這些建議的變更僅限於格式和呈現方式，而非內容變更。
與文字插入或刪除不同，這類操作不會偏移索引 (雖然可能會將 TextRun 分割成較小的區塊)，但會新增建議樣式變更的註解。
其中一個註解是 SuggestedTextStyle，由 2 個部分組成：
textStyle會說明建議變更後的文字樣式，但不會說明變更內容。textStyleSuggestionState：指出建議如何變更textStyle的欄位。
您可以在下列文件分頁摘錄中看到這點，其中包含建議的樣式變更：
[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] }
在上述範例中，段落由 3 個文字行組成，分別位於第 6、14 和 50 行。檢查中間的文字行：
- 第 16 行：有
suggestedTextStyleChanges物件。 - 第 18 行：
textStyle會指定各種格式。 - 行 36：
textStyleSuggestionState會指出這份規格說明中只有粗體部分是建議內容。 - 42 行：這段文字的斜體樣式是目前文件的一部分 (不會受到建議影響)。
只有在 textStyleSuggestionState 中設為 true 的樣式功能才會納入建議。