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"
}
}
}
]
}
}
}
]
},
|
在上述回應中，含有「Text following the
suggestion」這一行的段落，顯示使用 SuggestionsViewMode 時的差異。如果將值設為 SUGGESTIONS_INLINE，startIndex 的 ParagraphElementstartIndex 會從 51 開始，endIndex 則會在 81 停止。如果沒有建議，startIndex 和 endIndex 的範圍為 32 到 62。
取得內容但不顯示建議
以下部分程式碼範例說明如何將文件做為預覽畫面，並將 SuggestionsViewMode 參數設為 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() )
如果省略 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 的樣式特徵，才會納入建議。