Korzystanie z sugestii

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 do pobierania treści dokumentu używasz metody documents.get, 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 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, ze wszystkimi odrzuconymi sugestiami.

Jeśli nie podasz wartości SuggestionsViewMode, interfejs Google Docs API użyje domyślnego ustawienia 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.

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 startIndex i endIndex wynosi 32–62.

Pobieranie treści bez sugestii

Poniższy przykładowy kod 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 o sugerowanej zmianie stylu.

Jedną z takich adnotacji jest SuggestedTextStyle, która składa się z 2 części:

  • Znak textStyle, który opisuje, jak tekst jest formatowany po wprowadzeniu sugerowanej zmiany, ale nie informuje, co się zmieniło.

  • textStyleSuggestionState, który wskazuje, jak sugestia zmienia pola textStyle.

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 tekstowych, które zaczynają się w wierszach 6, 14 i 50. Sprawdź środkowy fragment tekstu:

  • Wiersz 16: jest obiekt suggestedTextStyleChanges.
  • Wiersz 18: znak textStyle określa różne formatowanie.
  • Wiersz 36: znak textStyleSuggestionState informuje, ż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).

W sugestii uwzględniane są tylko funkcje stylu ustawione na true w textStyleSuggestionState.