Komentarze to przekazywane przez użytkowników opinie o pliku, np. czytelnik dokumentu edytora tekstu sugerującego, jak przeformułować zdanie. Istnieją 2 typy komentarzy: komentarze zakotwiczone i niezakotwiczone. Zakotwiczony komentarz jest powiązany z konkretną lokalizacją, taką jak zdanie w dokumencie edytującym tekst, w ramach określonej wersji dokumentu. I na odwrót – niezakotwiczony komentarz jest po prostu powiązany z dokumentem.
Odpowiedzi są dołączane do komentarzy i reprezentują odpowiedź użytkownika na ten komentarz. Interfejs Drive API umożliwia użytkownikom dodawanie komentarzy i odpowiedzi do dokumentów utworzonych przez Twoją aplikację. Zbiorczo komentarz z odpowiedziami jest nazywany dyskusją.
Dodaj niezakotwiczony komentarz
Aby dodać do dokumentu niezakotwiczony komentarz, wywołaj metodę comments.create
z parametrem fileId
i zasobem comments
zawierającym komentarz.
Komentarz jest wstawiony jako zwykły tekst, ale w treści odpowiedzi znajduje się pole htmlContent
z treścią sformatowaną do wyświetlenia.
Dodawanie odpowiedzi na komentarz
Aby dodać odpowiedź na komentarz, wywołaj metodę replies.create
z komentarzem, parametrem fileId
i zasobem replies
zawierającym odpowiedź.
Odpowiedź jest wstawiona jako zwykły tekst, ale w treści odpowiedzi znajduje się pole htmlContent
z treścią sformatowaną do wyświetlenia.
Dodaj zakotwiczony komentarz do najnowszej wersji dokumentu
Po dodaniu komentarza możesz go zakotwiczyć do regionu w pliku. Kotwica określa wersję i region pliku, do którego odnosi się komentarz. Zasób comments
definiuje pole anchor
jako ciąg znaków JSON.
Aby dodać zakotwiczony komentarz:
Opcjonalnie: Wywołaj metodę
revisions.list
, aby wyświetlić listę wszystkich parametrówrevisionID
w danym dokumencie. Wykonaj ten krok tylko wtedy, gdy chcesz zakotwiczyć komentarz do wersji innej niż najnowsza. Jeśli chcesz użyć najnowszej wersji, jakorevisionID
użyjhead
.Wywołaj metodę
comments.create
z parametremfileID
, zasobemcomments
zawierającym komentarz oraz ciągiem kotwicy JSON zawierającymrevisionID
(r
) i region (a
).
Sposób definiowania regionu zależy od typu dokumentu, nad którym pracujesz. Więcej informacji znajdziesz w sekcji Definiowanie regionu.
Zdefiniuj region
Jak już wspomnieliśmy, ciąg kotwicy JSON zawiera ciąg revisionID
(r
) i region (a
). Region (a
) to tablica JSON zawierająca klasyfikatory regionów określająca format i lokalizację, do których zostanie zakotwiczony komentarz. Klasyfikator może być dwuwymiarowym prostokątem obrazu, linią tekstu w dokumencie lub blokiem czasu w filmie. Aby zdefiniować region, wybierz klasyfikator regionu odpowiadający typowi treści, do których próbujesz się zakotwiczyć. Jeśli na przykład treść zawiera tekst, prawdopodobnie użyjesz klasyfikatora regionów txt
lub line
.
Listę klasyfikatorów regionów w interfejsie Drive API znajdziesz w artykule Klasyfikatory regionów.
Poniższy przykład przedstawia ciąg kotwicy JSON, który zakotwicza komentarze do wierszy w 2 osobnych obszarach dokumentu:
- Pierwszy obszar rozpoczyna się w linii 12 (
'n':12
) i obejmuje 3 wiersze ('l':3
). - Drugi obszar obejmuje tylko linię 18 (
'n':18, 'l':1
”).
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Zastąp REVISION_ID wartością head
lub identyfikatorem konkretnej wersji.
Zakończ komentarz
Użyj metody comment.update
, aby ustawić właściwość resolved
w zasobie comments
na true
w przypadku zaadresowania komentarza.
Gdy aplikacja ustawi właściwość resolved
na true
, w interfejsie aplikacji powinno pojawić się informacja, że komentarz został rozwiązany. Aplikacja może na przykład:
- Nie zezwalaj na kolejne odpowiedzi i przyciemnij wszystkie wcześniejsze odpowiedzi oraz oryginalny komentarz.
- Ukryj zakończone komentarze.
Usuwanie komentarzy
Do usuwania komentarzy używaj metody comments.delete
. Gdy komentarz zostanie usunięty, Dysk oznaczy zasób komentarza jako "deleted": "true"
.
Komentarze do listy
Do wyświetlania komentarzy użyj metody comments.list
. Jeśli w wynikach chcesz uwzględnić usunięte komentarze, w polu includedDeleted
ustaw wartość true
.