Zarządzanie komentarzami i odpowiedziami

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: zakotwiczone i niezakotwiczone. Komentarz zakotwiczony jest powiązany z konkretną lokalizacją, np. zdaniem w dokumencie edytora tekstu, w określonej wersji dokumentu. Natomiast niezakotwiczony komentarz jest powiązany tylko z dokumentem.

Odpowiedzi są dołączane do komentarzy i reprezentują odpowiedź użytkownika na komentarz. 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 i zasobem replies zawierającym 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 ostatniej 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:

  1. Opcjonalnie: Aby wyświetlić wszystkie revisionID w 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ści head dla parametru revisionID.

  2. Wywołaj metodę comments.create z parametrem fileID, zasobem comments zawierającym komentarz oraz ciągiem znaków kotwicy JSON zawierającym identyfikator revisionID (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.

Definiowanie regionu

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 region klasyfikator, który odpowiada rodzajowi treści, do których chcesz dołączyć etykietę. Jeśli na przykład Twoje treści to tekst, użyjesz prawdopodobnie 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

Po usunięciu problemu, który został zgłoszony w komentarzu, użyj metody comment.update, aby ustawić właściwość resolved w zasobie comments na true.

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.