Mit Vorschlägen arbeiten

In Google Docs können Mitbearbeiter Vorschläge machen, die im Grunde aufgeschobene Änderungen sind, die auf Genehmigung warten.

Wenn Sie die Methode documents.get verwenden, um Dokumentinhalte abzurufen, können diese nicht aufgelöste Vorschläge enthalten. Mit dem optionalen Parameter SuggestionsViewMode können Sie festlegen, wie documents.get Vorschläge darstellt. Mit diesem Parameter sind die folgenden Filterbedingungen verfügbar:

  • Inhalte mit SUGGESTIONS_INLINE abrufen, damit Text, der entweder gelöscht oder eingefügt werden soll, im Dokument angezeigt wird.
  • Inhalte als Vorschau mit allen akzeptierten Vorschlägen ansehen
  • Inhalte als Vorschau ohne Vorschläge abrufen, wobei alle Vorschläge abgelehnt werden.

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

Vorschläge und Indexe

Ein Grund, warum SuggestionsViewMode wichtig ist, ist, dass die Indexe in der Antwort je nach Vorhandensein von Vorschlägen variieren können, 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

Im obigen Beispiel wird im Absatz mit der Zeile „Text following the suggestion“ (Text nach dem Vorschlag) der Unterschied bei der Verwendung von SuggestionsViewMode deutlich. Wenn der Wert auf SUGGESTIONS_INLINE festgelegt ist, beginnt die startIndex der 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 teilweisen Codebeispiel wird gezeigt, wie Sie ein Dokument als Vorschau abrufen, wobei alle Vorschläge abgelehnt werden (falls vorhanden). Dazu wird der Parameter SuggestionsViewMode auf PREVIEW_WITHOUT_SUGGESTIONS gesetzt.

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 der Angabe von DEFAULT_FOR_CURRENT_ACCESS als Parameterwert.

Stilvorschläge

Dokumente können auch Stilvorschläge enthalten. Es handelt sich um vorgeschlagene Änderungen an Formatierung und Darstellung, nicht an den Inhalten.

Im Gegensatz zu Texteinfügungen oder ‑löschungen werden die Indexe dadurch nicht verschoben. Allerdings kann ein TextRun in kleinere Abschnitte unterteilt werden. Es werden lediglich Anmerkungen zur vorgeschlagenen Stiländerung hinzugefügt.

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

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

  • Die textStyleSuggestionState gibt an, wie sich der Vorschlag auf die Felder des textStyle auswirkt.

Das sehen Sie im folgenden Auszug aus einem Dokumenttab, 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 Textlauf an:

  • Zeile 16: Es gibt ein suggestedTextStyleChanges-Objekt.
  • Zeile 18: Mit textStyle wird die Formatierung angegeben.
  • Zeile 36: Das textStyleSuggestionState gibt an, dass nur der fettgedruckte Teil dieser Spezifikation der Vorschlag war.
  • Zeile 42: Die kursive Formatierung dieses Textabschnitts ist Teil des aktuellen Dokuments und wird nicht durch den Vorschlag beeinflusst.

Nur die Stilmerkmale, die in der textStyleSuggestionState auf true gesetzt sind, sind Teil des Vorschlags.