Los comentarios son comentarios que los usuarios proporcionan sobre un archivo, como un lector de un documento de procesamiento de texto que sugiere cómo reformular una oración. Existen dos tipos de comentarios: anclados y no anclados. Un comentario fijado está asociado con una ubicación específica, como una oración en un documento de procesamiento de texto, dentro de una versión específica de un documento. Por el contrario, un comentario sin anclar solo se asocia con el documento.
Las respuestas se adjuntan a los comentarios y representan la respuesta de un usuario a estos. La API de Drive permite que los usuarios agreguen comentarios y respuestas a los documentos que crea tu app. En conjunto, un comentario con respuestas se conoce como una discusión.
Agrega un comentario sin anclar
Para agregar un comentario sin anclar a un documento, llama al método comments.create con el parámetro fileId y un recurso comments que contenga el comentario.
El comentario se inserta como texto sin formato, pero el cuerpo de la respuesta proporciona un campo htmlContent que contiene contenido con formato para su visualización.
Cómo agregar una respuesta a un comentario
Para agregar una respuesta a un comentario, llama al método replies.create con el comentario, el parámetro fileId y un recurso replies que contenga la respuesta.
La respuesta se inserta como texto sin formato, pero el cuerpo de la respuesta proporciona un campo htmlContent que contiene contenido con formato para su visualización.
Cómo agregar un comentario anclado a la revisión más reciente de un documento
Cuando agregues un comentario, te recomendamos que lo ancles a una región del archivo. Un anclaje define la revisión y la región de un archivo al que hace referencia un comentario. El recurso comments define el campo anchor como una cadena JSON.
Para agregar un comentario anclado, sigue estos pasos:
(Opcional) Llama al método
revisions.listpara enumerar todos losrevisionIDde un documento. Sigue este paso solo si deseas fijar un comentario a cualquier revisión que no sea la más reciente. Si quieres usar la revisión más reciente, usaheadpararevisionID.Llama al método
comments.createcon el parámetrofileID, un recursocommentsque contenga el comentario y una cadena de ancla JSON que contengarevisionID(r) y la región (a).
La forma en que definas una región depende del tipo de contenido del documento con el que trabajes. Para obtener más información, consulta Cómo definir una región.
Define una región
Como se mencionó anteriormente, la cadena de ancla JSON contiene un revisionID (r) y una región (a). La región (a) es un array JSON que contiene clasificadores de región que especifican el formato y la ubicación a la que se ancla un comentario. Un clasificador puede ser un rectángulo bidimensional para una imagen, una línea de texto en un documento o una duración en un video. Para definir una región, selecciona el clasificador de regiones que coincida con el tipo de contenido al que intentas fijarlo. Por ejemplo, si tu contenido es texto, es probable que uses el clasificador de regiones txt o line.
Para obtener una lista de los clasificadores de regiones en la API de Drive, consulta Clasificadores de regiones.
En el siguiente ejemplo, se muestra una cadena de ancla JSON que ancla los comentarios a líneas en dos áreas separadas de un documento:
- El primer área comienza en la línea 12 (
'n':12) y se extiende por tres líneas ('l':3). - El segundo área solo abarca la línea 18 (
'n':18, 'l':1`).
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Reemplaza REVISION_ID por head o el ID de una revisión específica.
Cómo resolver un comentario
Usa el método comment.update para establecer la propiedad resolved en el recurso comments en true cuando se haya respondido un comentario.
Cuando tu app establece la propiedad resolved en true, la IU debe indicar que se abordó el comentario. Por ejemplo, tu app podría hacer lo siguiente:
- No permitir más respuestas y atenuar todas las respuestas anteriores, además del comentario original
- Oculta los comentarios resueltos.
Cómo borrar un comentario
Usa el método comments.delete para borrar comentarios. Cuando se borra un comentario, Drive marca el recurso de comentario como "deleted": "true".
Cómo enumerar comentarios
Usa el método comments.list para enumerar los comentarios. Si deseas incluir comentarios borrados en los resultados, establece el campo includedDeleted en true.