Dokumenty Google umożliwiają współpracownikom tworzenie sugestii, które są w zasadzie odroczonymi zmianami czekającymi na zatwierdzenie.
Za pomocą interfejsu API możesz wyświetlać sugestie, ale nie możesz ich automatycznie akceptować, odrzucać ani tworzyć.
Gdy używasz metody
documents.get do pobierania treści dokumentu, mogą one zawierać nierozwiązane sugestie. Aby określić, w jaki sposób documents.get ma przedstawiać sugestie, użyj opcjonalnego parametru SuggestionsViewMode. W przypadku tego parametru dostępne są te warunki filtra:
- Pobierz treść z symbolem
SUGGESTIONS_INLINE, aby w dokumencie pojawił się tekst oczekujący na usunięcie lub wstawienie. - Wyświetl podgląd treści ze wszystkimi zaakceptowanymi sugestiami.
- Uzyskaj treści w formie podglądu bez sugestii, z odrzuconymi wszystkimi sugestiami.
Jeśli nie podasz wartości SuggestionsViewMode, interfejs Google Docs API użyje ustawienia domyślnego odpowiedniego dla uprawnień bieżącego użytkownika.
Sugestie i indeksy
Jednym z powodów, dla których SuggestionsViewMode jest ważne, jest to, że indeksy w odpowiedzi mogą się różnić w zależności od tego, czy są sugestie, jak pokazano poniżej.
documents.batchUpdate
| Treści z sugestiami | Treści bez sugestii |
|---|---|
{
"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"
}
}
}
]
}
}
}
]
},
|
W odpowiedzi powyżej akapit zawierający wiersz „Text following the
suggestion” pokazuje różnicę w przypadku użycia parametru SuggestionsViewMode. Jeśli wartość jest ustawiona na SUGGESTIONS_INLINE, startIndex elementu ParagraphElement zaczyna się od 51, a endIndex kończy się na 81. Bez sugestii zakres wartości startIndex i endIndex wynosi od 32 do 62.
Pobieranie treści bez sugestii
Poniższy fragment przykładowego kodu pokazuje, jak uzyskać dokument w wersji podglądowej ze wszystkimi odrzuconymi sugestiami (jeśli takie istnieją) przez ustawienie parametru SuggestionsViewMode na 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() )
Pominięcie parametru SuggestionsViewMode jest równoznaczne z podaniem wartości DEFAULT_FOR_CURRENT_ACCESS.
Sugestie dotyczące stylu
Dokumenty mogą też zawierać sugestie dotyczące stylu. Są to sugerowane zmiany formatowania i prezentacji, a nie treści.
W przeciwieństwie do wstawiania lub usuwania tekstu nie powodują one przesunięcia indeksów (chociaż mogą podzielić TextRun na mniejsze części), ale dodają adnotacje dotyczące sugerowanej zmiany stylu.
Jedną z takich adnotacji jest SuggestedTextStyle, która składa się z 2 części:
Znak
textStyle, który opisuje styl tekstu po wprowadzeniu sugerowanej zmiany, ale nie informuje o tym, co się zmieniło.textStyleSuggestionState, który wskazuje, jak sugestia zmienia polatextStyle.
Możesz to zobaczyć na wyciągu z karty dokumentu poniżej, który zawiera sugerowaną zmianę stylu:
[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] }
W powyższym przykładzie akapit składa się z 3 ciągów tekstu, które zaczynają się w wierszach 6, 14 i 50. Sprawdź środkowy ciąg tekstu:
- Wiersz 16: jest obiekt
suggestedTextStyleChanges. - Wiersz 18: znak
textStyleokreśla różne formatowanie. - Wiersz 36: znak
textStyleSuggestionStateinformuje, że sugestia dotyczy tylko pogrubionej części tej specyfikacji. - Wiersz 42: kursywa w tym fragmencie tekstu jest częścią bieżącego dokumentu (i nie ma na nią wpływu sugestia).
Tylko funkcje stylu ustawione na true w textStyleSuggestionState są częścią sugestii.