Mit Vorschlägen arbeiten

In Google Docs können Mitbearbeiter Vorschläge machen, die effektiv als ausstehende Änderungen warten, bis sie genehmigt werden.

Wenn Sie die Methode documents.get verwenden, um Dokumentinhalte abzurufen, können diese ungelöste Vorschläge enthalten. Mit dem optionalen Parameter SuggestionsViewMode können Sie festlegen, wie Vorschläge mit documents.get dargestellt werden. Für diesen Parameter sind die folgenden Filterbedingungen verfügbar:

  • Inhalte mit SUGGESTIONS_INLINE abrufen, damit Text, der gelöscht oder eingefügt werden soll, im Dokument angezeigt wird.
  • Sie erhalten eine Vorschau der Inhalte, in der alle akzeptierten Vorschläge enthalten sind.
  • Inhalte als Vorschau ohne Vorschläge abrufen, wobei alle Vorschläge abgelehnt werden.

Wenn Sie SuggestionsViewMode nicht angeben, verwendet die Google Docs API eine Standardeinstellung, die den Berechtigungen des aktuellen Nutzers entspricht.

Vorschläge und Indexe

Ein Grund dafür, dass SuggestionsViewMode wichtig ist, ist, dass die Indizes in der Antwort variieren können, je nachdem, ob es Vorschläge gibt, wie unten dargestellt.

Inhalte mit Vorschlägen Inhalte ohne Vorschläge 
{
 "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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

In der Antwort oben zeigt der Absatz mit der Zeile „Text nach dem Vorschlag“ den Unterschied bei Verwendung von SuggestionsViewMode. Wenn der Wert auf SUGGESTIONS_INLINE festgelegt ist, beginnt die startIndex von ParagraphElement bei 51 und die endIndex endet bei 81. Ohne Vorschläge liegen die Werte für startIndex und endIndex zwischen 32 und 62.

Inhalte ohne Vorschläge erhalten

Im folgenden Codebeispiel wird gezeigt, wie Sie ein Dokument als Vorschau abrufen, wobei alle Vorschläge abgelehnt werden (falls vorhanden), indem Sie den Parameter SuggestionsViewMode auf PREVIEW_WITHOUT_SUGGESTIONS festlegen.

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()
)

Wenn Sie den Parameter SuggestionsViewMode weglassen, entspricht das dem Angeben von DEFAULT_FOR_CURRENT_ACCESS als Parameterwert.

Stilvorschläge

Dokumente können auch Stilvorschläge enthalten. Es handelt sich dabei um Vorschläge für Änderungen an Formatierung und Präsentation, nicht an Inhalten.

Im Gegensatz zu Texteinfügungen oder ‑löschungen werden die Indexe dadurch nicht verschoben. Sie können zwar einen TextRun in kleinere Abschnitte unterteilen, fügen aber nur Anmerkungen zur vorgeschlagenen Stiländerung hinzu.

Eine solche Anmerkung ist eine SuggestedTextStyle, die aus zwei Teilen besteht:

  • Das textStyle, das beschreibt, wie der Text nach der vorgeschlagenen Änderung formatiert wird, aber nicht, was sich geändert hat.

  • Die textStyleSuggestionState, die angibt, wie die Felder der textStyle durch den Vorschlag geändert werden.

Das sehen Sie in diesem Auszug aus dem Dokumententab, der eine vorgeschlagene Stiländerung enthält:

[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] }

Im Beispiel oben besteht der Absatz aus drei Textläufen, die in den Zeilen 6, 14 und 50 beginnen. Sehen Sie sich den mittleren Textablauf an:

  • Zeile 16: Es gibt ein suggestedTextStyleChanges-Objekt.
  • Zeile 18: Mit textStyle wird verschiedene Formatierung angegeben.
  • Zeile 36: Das textStyleSuggestionState gibt an, dass nur der fett formatierte Teil dieser Spezifikation der Vorschlag war.
  • Zeile 42: Die Kursivschrift dieses Textlaufs ist Teil des aktuellen Dokuments und wird vom Vorschlag nicht beeinflusst.

Nur die Stiloptionen, die im textStyleSuggestionState auf true gesetzt sind, sind Teil des Vorschlags.