I commenti sono feedback forniti dagli utenti su un file, ad esempio un lettore di un documento di elaborazione testi che suggerisce come riformulare una frase. Esistono due tipi di commenti: commenti ancorati e commenti non ancorati. Un commento ancorato è associato a una posizione specifica, ad esempio una frase in un documento di elaborazione testi, all'interno di una versione specifica di un documento. Viceversa, un commento non ancorato viene associato al documento.
Le risposte sono allegate ai commenti e rappresentano la risposta di un utente al commento. L'API Google Drive consente agli utenti di aggiungere commenti e risposte ai documenti creati dalla tua app. Collettivamente, un commento con risposte è noto come discussione.
Aggiungere un commento non ancorato
Per aggiungere un commento non ancorato a un documento, chiama il metodo comments.create
con il parametro fileId
e una risorsa comments
contenente il commento.
Il commento viene inserito come testo normale, ma il corpo della risposta fornisce un campo htmlContent
con contenuti formattati per la visualizzazione.
Aggiungere una risposta a un commento
Per aggiungere una risposta a un commento, chiama il metodo replies.create
con il commento, il parametro fileId
e una risorsa reply
contenente la risposta.
La risposta viene inserita come testo normale, ma il corpo della risposta fornisce un campo htmlContent
con contenuti formattati per la visualizzazione.
Aggiungere un commento ancorato all'ultima revisione di un documento
Quando aggiungi un commento, ti consigliamo di ancorarlo a un'area del file. Un anchor definisce la revisione e l'area geografica di un file a cui fa riferimento un commento. La risorsa comments
definisce il campo
anchor
come una stringa JSON.
Per aggiungere un commento ancorato:
(Facoltativo) Chiama il metodo
revisions.list
per elencare ognirevisionID
per un documento. Segui questo passaggio solo se vuoi ancorare un commento a qualsiasi revisione diversa dall'ultima revisione. Se vuoi usare la revisione più recente, usahead
perrevisionID
.Richiama il metodo
comments.create
con il parametrofileID
, una risorsacomments
contenente il commento e una stringa di ancoraggio JSON contenenterevisionID
(r
) e la regione (a
).
La modalità di definizione di un'area geografica dipende dal tipo di contenuti del documento con cui lavori. Per ulteriori informazioni, consulta la sezione Definire una regione di seguito.
Definisci una regione
Come accennato in precedenza, la stringa anchor JSON contiene un elemento revisionID
(r
) e un'area geografica (a
). La regione (a
) è un array JSON contenente classificatori della regione che specificano il formato e la posizione a cui è ancorato un commento. Un classificatore può essere un rettangolo bidimensionale per un'immagine, una riga di testo in un documento, la durata di un video e così via. Per definire una regione, seleziona il classificatore della regione che corrisponde al tipo di contenuti a cui stai tentando di eseguire l'ancoraggio. Ad
esempio, se i contenuti sono di testo, probabilmente utilizzerai la categoria di classificazione della regione txt
o line
.
Per un elenco delle categorie di classificazione dell'area geografica nell'API Drive, consulta Classificatori delle regioni.
L'esempio seguente mostra una stringa di ancoraggio JSON che ancora i commenti alle righe in 2 aree separate di un documento:
- La prima area inizia alla riga 12 (
'n':12
) e si estende per tre linee ('l':3
). - La seconda area copre solo la riga 18 (
'n':18, 'l':1
").
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Sostituisci REVISION_ID con head
o l'ID di una revisione specifica.
Risolvere un commento
Utilizza il metodo comment.update
per impostare la proprietà resolved
nella risorsa comments
su true
quando viene gestito un commento.
Quando l'app imposta la proprietà resolved
su true
, la UI dovrebbe indicare che il commento è stato gestito. Ad esempio, la tua app potrebbe:
- Non consentire ulteriori risposte e oscura tutte le risposte precedenti più il commento originale.
- Nascondi commenti risolti.
Eliminare un commento
Utilizza il metodo comments.delete
per
eliminare i commenti. Quando un commento viene eliminato, Drive contrassegna
la risorsa commento come "deleted": "true"
.
Elenca commenti
Usa il metodo comments.list
per elencare i commenti. Se vuoi includere commenti eliminati nei risultati, imposta il campo includedDeleted
su true
.