Google ドキュメントでは、共同編集者が提案を行うことができます。これは、承認待ちの編集を効果的に延期するものです。
documents.get メソッドを使用してドキュメントのコンテンツを取得すると、未解決の候補がコンテンツに含まれることがあります。documents.get で候補を表す方法を制御するには、オプションの SuggestionsViewMode パラメータを使用します。このパラメータでは、次のフィルタ条件を使用できます。
SUGGESTIONS_INLINEを使用してコンテンツを取得し、削除または挿入が保留中のテキストをドキュメントに表示します。- すべての提案が承認された状態でコンテンツをプレビューとして取得します。
- 提案なしで、すべての提案が拒否された状態で、コンテンツをプレビューとして取得します。
SuggestionsViewMode を指定しない場合、Google ドキュメント API は現在のユーザーの権限に適したデフォルト設定を使用します。
候補とインデックス
SuggestionsViewMode が重要な理由の 1 つは、以下に示すように、レスポンスのインデックスが候補の有無によって異なる可能性があるためです。
| 提案を含むコンテンツ | 候補が表示されないコンテンツ |
|---|---|
{
"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 に設定すると、ParagraphElement の startIndex は 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 がより小さなチャンクに分割されることはありますが）。提案されたスタイルの変更に関するアノテーションが追加されるだけです。
このようなアノテーションの 1 つに 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 に設定されたスタイル機能のみが候補に含まれます。