Komentarze to opinie użytkowników na temat pliku, np. sugestia od czytelnika dokumentu edytora tekstu dotycząca tego, jak przeformułować zdanie. Istnieją 2 typy komentarzy: komentarze zakotwiczone i komentarze niezakotwiczone. Komentarz zakotwiczony jest powiązany z konkretną lokalizacją, np. zdaniem w dokumencie edytora tekstu, w określonej wersji dokumentu. Natomiast niezakotwiczony komentarz jest po prostu powiązany z dokumentem.
Odpowiedzi są dołączane do komentarzy i stanowią odpowiedź użytkownika. Interfejs API Dysku umożliwia użytkownikom dodawanie komentarzy i odpowiedzi do dokumentów utworzonych przez Twoją aplikację. Komentarze z odpowiedziami nazywane są dyskusją.
Dodawanie niezakotwiczonego komentarza
Aby dodać do dokumentu niezakotwiczony komentarz, wywołaj metodę comments.create z parametrem fileId i zasobem comments zawierającym komentarz.
Komentarz jest wstawiany jako zwykły tekst, ale treść odpowiedzi zawiera pole htmlContent z treścią sformatowaną do wyświetlania.
Dodawanie odpowiedzi na komentarz
Aby dodać odpowiedź na komentarz, wywołaj metodę replies.create z parametrem fileId zawierającym komentarz oraz zasób replies zawierający odpowiedź.
Odpowiedź jest wstawiana jako zwykły tekst, ale treść odpowiedzi zawiera pole htmlContent z treścią sformatowaną do wyświetlania.
Dodawanie zakotwiczonego komentarza do najnowszej wersji dokumentu
Dodając komentarz, możesz go przypiąć do wybranego obszaru w pliku. Ankiety określają wersję pliku i region w pliku, do którego odnosi się komentarz. Zasób comments definiuje pole anchor jako ciąg znaków JSON.
Aby dodać zakotwiczony komentarz:
Opcjonalnie: Aby wyświetlić wszystkie
revisionIDw dokumencie, wywołaj metodęrevisions.list. Wykonaj ten krok tylko wtedy, gdy chcesz zakotwiczyć komentarz do wersji innej niż najnowsza. Jeśli chcesz użyć najnowszej wersji, użyj wartościheaddla parametrurevisionID.Wywołaj metodę
comments.createz parametremfileID, zasobemcommentszawierającym komentarz oraz ciągiem znaków kotwicy JSON zawierającymrevisionID(r) i region (a).
Sposób zdefiniowania regionu zależy od typu treści dokumentu, z którym pracujesz. Więcej informacji znajdziesz w artykule Definiowanie regionu.
Zdefiniuj region
Jak już wspomnieliśmy, ciąg zakotwiczenia JSON zawiera element revisionID (r) i region (a). Region (a) to tablica JSON zawierająca klasyfikatory regionów określające format i lokalizację, do których jest zakotwiczony komentarz. Klasyfikator może być dwuwymiarowym prostokątem w przypadku obrazu, linią tekstu w dokumencie lub czasem trwania w filmie. Aby zdefiniować region, wybierz klasyfikator regionu odpowiadający typowi treści, które chcesz zakotwiczyć. Jeśli na przykład treść jest tekstem, prawdopodobnie użyjesz klasyfikatora regionów txt lub line.
Listę klasyfikatorów regionów w interfejsie Drive API znajdziesz w artykule o klasyfikatorach regionów.
Ten przykład pokazuje ciąg zakotwiczenia JSON, który zakotwicza komentarze do linii w 2 oddzielnych obszarach dokumentu:
- Pierwszy obszar zaczyna się w wierszu 12 (
'n':12) i zajmuje 3 wiersze ('l':3). - Drugi obszar obejmuje tylko wiersz 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.
Kończenie wątku komentarza
Użyj metody comment.update, aby ustawić właściwość resolved w zasobie comments na true po zareagowaniu komentarza.
Gdy aplikacja ustawia właściwość resolved na true, interfejs użytkownika powinien wskazywać, że komentarz został przetworzony. Aplikacja może na przykład:
- Zablokuj dalsze odpowiedzi i przyciemnij wszystkie poprzednie odpowiedzi oraz oryginalny komentarz.
- ukrywać zakończone komentarze.
Usuwanie komentarzy
aby usunąć komentarze, używaj metody comments.delete. Gdy komentarz zostanie usunięty, Dysk oznaczy zasób komentarza jako "deleted": "true".
Wyświetlanie listy komentarzy
Aby wyświetlić komentarze, użyj metody comments.list. Jeśli chcesz uwzględnić usunięte komentarze w wynikach, ustaw pole includedDeleted na true.