Dokumenty Google umożliwiają współpracownikom współpracę poprzez pisanie komentarzy i zgłaszanie sugestii, które działają jak odroczone zmiany oczekujące na zatwierdzenie.
Za pomocą interfejsu API możesz wyświetlać sugerowane zmiany w tekście dokumentu. W wersji dla deweloperów możesz też programowo odczytywać, tworzyć, odpowiadać na wątki komentarzy i sugestii, aktualizować je oraz usuwać.
Gdy używasz metody
documents.get do
pobierania treści dokumentu, może ona zawierać nierozwiązane sugestie. Aby
kontrolować sposób, w jaki documents.get reprezentuje sugestie, użyj opcjonalnego
SuggestionsViewMode
parametru. W przypadku tego parametru dostępne są te warunki filtrowania:
- Pobieranie treści za pomocą
SUGGESTIONS_INLINE, dzięki czemu tekst oczekujący na usunięcie lub wstawienie pojawia się w dokumencie. - Pobieranie treści jako podglądu ze wszystkimi zaakceptowanymi sugestiami.
- Pobieranie treści jako podglądu bez sugestii, ze wszystkimi odrzuconymi sugestiami.
Jeśli nie podasz SuggestionsViewMode, interfejs API Dokumentów Google 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żny, jest to, że indeksy w odpowiedzi mogą się różnić w zależności od tego, czy są sugestie, jak pokazano poniżej.
| Treść z sugestiami | Treść 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 powyższej odpowiedzi akapit zawierający wiersz „Tekst po sugestii” pokazuje różnicę podczas używania SuggestionsViewMode. Gdy
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 od 32 do 62.
Pobieranie treści bez sugestii
Ten fragment przykładowego kodu pokazuje, jak pobrać dokument jako podgląd ze wszystkimi odrzuconymi sugestiami (jeśli takie istnieją), ustawiając parametr 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 DEFAULT_FOR_CURRENT_ACCESS jako wartości parametru.
Sugestie dotyczące stylu
Dokumenty mogą też zawierać sugestie dotyczące stylu. Są to sugerowane zmiany formatowania i prezentacji, a nie zmiany 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:
textStyle, który opisuje, jak tekst jest stylizowany po sugerowanej zmianie, ale nie mówi, co się zmieniło.textStyleSuggestionState, który wskazuje, jak sugestia zmienia polatextStyle.
Możesz to zobaczyć w tym fragmencie karty dokumentu, 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 fragmentów tekstu, zaczynających się w wierszach 6, 14 i 50. Sprawdź środkowy fragment tekstu:
- Wiersz 16: jest obiekt
suggestedTextStyleChanges. - Wiersz 18:
textStyleokreśla różne formatowanie. - Wiersz 36:
textStyleSuggestionStateinformuje, że tylko pogrubiona część tej specyfikacji była sugestią. - Wiersz 42: kursywa tego fragmentu tekstu jest częścią bieżącego dokumentu (i nie jest objęta sugestią).
Tylko funkcje stylu ustawione na true w textStyleSuggestionState są częścią sugestii.
Tworzenie komentarzy i zarządzanie nimi
Za pomocą metody documents.batchUpdate możesz programowo dodawać komentarze i odpowiedzi, edytować komentarze oraz usuwać
komentarze lub odpowiedzi.
Podczas wykonywania aktualizacji zbiorczych obejmujących komentarze lub sugestie należy monitorować potencjalne częściowe awarie. Więcej informacji znajdziesz w sekcji Stan aktualizacji komentarzy i sugestii.
Wstawianie komentarza
Aby wstawić wątek komentarza, użyj InsertCommentRequest
obiektu. Musisz podać treść komentarza i lokalizację kotwicy (np. zakres), do której jest dołączony komentarz.
Ten przykład w formacie JSON dodaje nieprzypisany wątek komentarza do określonego zakresu:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added via the API.",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Możesz przypisać komentarz do konkretnego użytkownika, podając jego adres e-mail w polu assigneeEmailAddress:
{
"requests": [
{
"insertComment": {
"content": "Please review this paragraph.",
"assigneeEmailAddress": "user@example.com",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Dodawanie odpowiedzi lub podejmowanie działań
Aby odpowiedzieć na komentarz lub wątek sugestii albo rozwiązać lub ponownie otworzyć wątek,
użyj AddCommentReplyRequest.
Odpowiedź jest reprezentowana przez Post obiekt.
Obiekt Post zawiera content odpowiedzi i opcjonalnie może określać commentAction (aby RESOLVE lub REOPEN wątek).
Ten przykład odpowiada na istniejący wątek komentarza:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Ten przykład rozwiązuje wątek komentarza, który nie wymaga treści:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Edytowanie posta
Aby edytować tekst posta, którego jesteś autorem, użyj UpdateCommentPostRequest.
Musisz określić identyfikator wątku (albo commentId albo suggestionId), postId posta, który chcesz edytować, oraz nową treść w postaci zwykłego tekstu content.
Pamiętaj, że nie możesz edytować głównego posta wątku sugestii (ponieważ są one generowane przez zmiany w trybie sugestii).
{
"requests": [
{
"updateCommentPost": {
"commentId": "comment_thread_id",
"postId": "post_id",
"content": "This is the updated comment text."
}
}
]
}
Usuwanie komentarzy i odpowiedzi
- Usuwanie wątku komentarza: aby usunąć cały wątek komentarza, użyj
DeleteCommentRequest. Wątek komentarza możesz usunąć tylko wtedy, gdy jesteś autorem głównego posta w tym wątku. - Usuwanie odpowiedzi: aby usunąć konkretny post z odpowiedzią, użyj
DeleteCommentReplyRequest. Możesz usuwać tylko odpowiedzi, których jesteś autorem. Nie możesz usuwać postów z odpowiedziami, które zawierają działania lub osoby przypisane.
Ten przykład usuwa wątek komentarza:
{
"requests": [
{
"deleteComment": {
"commentId": "comment_thread_id"
}
}
]
}
Pisanie sugestii i zarządzanie wątkami sugestii
Możesz pisać zmiany jako sugestie, a nie bezpośrednie zmiany, oraz programowo akceptować, odrzucać lub usuwać wątki sugestii.
Podczas wykonywania aktualizacji zbiorczych obejmujących sugestie należy monitorować potencjalne częściowe awarie. Więcej informacji znajdziesz w sekcji Stan aktualizacji komentarzy i sugestii.
Tworzenie sugestii w trybie sugestii
Aby zastosować zmiany jako sugestie, ustaw pole writeMode obiektu WriteControl na SUGGEST w żądaniu aktualizacji zbiorczej. Wszystkie aktualizacje w żądaniu są przetwarzane jako sugestie.
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
Nieobsługiwane żądania w trybie sugestii
Gdy używasz WriteMode.SUGGEST, te typy żądań nie są obsługiwane i zwrócą błąd:
AddDocumentTabCreateNamedRangeDeleteFooterDeleteHeaderDeleteNamedRangeDeleteTabUpdateDocumentTabPropertiesUpdateTableColumnProperties
Nie możesz też sugerować zmian formatu dokumentu ani ustawień nagłówków i stopek. W przypadku UpdateDocumentStyle sugestie nie są obsługiwane w przypadku tych typów stylów:
documentFormatuseEvenPageHeaderFooteruseFirstPageHeaderFooter
Akceptowanie, odrzucanie i usuwanie wątków sugestii
Wątkami sugestii możesz zarządzać za pomocą tych żądań:
- Zaakceptuj sugestię: aby zaakceptować sugestię, użyj
AcceptSuggestionRequest. Wymaga to uprawnień do edycji dokumentu. - Odrzuć sugestię: aby odrzucić sugestię, użyj
RejectSuggestionRequest. Wymaga to uprawnień do edycji dokumentu lub bycia autorem sugestii. - Usuń sugestię: aby usunąć sugestię, użyj
DeleteSuggestionRequest. Wymaga to bycia autorem sugestii.
Ten przykład akceptuje wątek sugestii:
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
Stan aktualizacji komentarzy i sugestii
Żądania, które wymagają zapisania wątków komentarzy lub sugestii (np. wstawianie komentarzy, dodawanie odpowiedzi lub zgłaszanie sugestii), mogą powodować częściowe awarie. W takich przypadkach zmiany w modelu dokumentu (np. wstawianie lub usuwanie tekstu) mogą zostać pomyślnie zatwierdzone w modelu Dokumentów, ale powiązane komentarze lub sugestie mogą nie zostać zapisane.
Aby sprawdzić, czy aktualizacje komentarzy lub sugestii zostały pomyślnie zastosowane, sprawdź pole commentUpdateState w BatchUpdateDocumentResponse.
W CommentUpdateState zwracane są te stany:
NO_UPDATES_REQUESTED: w operacji zbiorczej nie zażądano żadnych aktualizacji komentarzy ani sugestii.ALL_SAVED: wszystkie żądane aktualizacje komentarzy lub sugestii zostały pomyślnie zastosowane.ALL_FAILED_UNKNOWN_REASON: nie udało się zapisać wszystkich żądanych aktualizacji komentarzy lub sugestii, mimo że zmiany w modelu Dokumentów mogły zostać zatwierdzone.