候補を使用する

Google ドキュメントでは、共同編集者が候補を作成できます。これは、承認を待つ編集を事実上延期するものです。

documents.get メソッドを使用してドキュメント コンテンツを取得すると、未解決の候補がコンテンツに含まれる場合があります。documents.get が候補をどのように表すかを制御するには、省略可能な SuggestionsViewMode パラメータを使用します。このパラメータでは、次のフィルタ条件を使用できます。

  • SUGGESTIONS_INLINE を使用してコンテンツを取得すると、削除または挿入の保留中のテキストがドキュメントに表示されます。
  • すべての候補を承認して、コンテンツをプレビューとして取得します。
  • コンテンツをプレビューとして取得し、候補はすべて拒否します。

SuggestionsViewMode を指定しない場合、Google Docs 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

上記のレスポンスの「候補に続くテキスト」行を含む段落は、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] }

上記のサンプルでは、段落は 6 行目、14 行目、50 行目から始まる 3 つのテキスト行で構成されています。中央のテキスト行を確認します。

  • 行 16: suggestedTextStyleChanges オブジェクトがあります。
  • 行 18: textStyle はさまざまなフォーマットを指定します。
  • 行 36: textStyleSuggestionState は、この仕様の太字の部分のみが候補であったことを示します。
  • 行 42: このテキスト行の斜体スタイルは現在のドキュメントの一部であり（候補の影響を受けません）。

textStyleSuggestionState で true に設定されたスタイル対象物のみが候補に含まれます。