Los comentarios son comentarios que proporciona el usuario sobre un archivo, como el lector de un documento de procesamiento de texto que sugiere cómo reformular una oración. Existen dos tipos de comentarios: comentarios fijos y no fijos. Un comentario fijo 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. En cambio, un comentario no anclado solo se asocia al documento.
Las respuestas se adjuntan a los comentarios y representan la respuesta de un usuario a este. La API de Drive permite a los usuarios agregar comentarios y respuestas a documentos creados por tu app. En conjunto, un comentario con respuestas se conoce como debate.
Cómo agregar un comentario sin fijar
Para agregar un comentario no anclado 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 con contenido con formato para mostrarse.
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 con contenido con formato de visualización.
Agregar un comentario fijo a la última revisión de un documento
Cuando agregas un comentario, puedes anclarlo a una región del archivo. Un ancla define la revisión y la región del archivo en un archivo al que hace referencia un comentario. El recurso comments define el campo anchor como una cadena JSON.
Para agregar un comentario fijo, haz lo siguiente:
(Opcional). Llama al método
revisions.listpara que se muestre cadarevisionIDde un documento. Solo sigue este paso si quieres anclar un comentario a una revisión que no sea la más reciente. Si quieres usar la revisión más reciente, utilizaheadpara elrevisionID.Llama al método
comments.createcon el parámetrofileID, un recursocommentsque contenga el comentario y una cadena de anclaje JSON que contengarevisionID(r) y la región (a).
La forma de definir una región depende del tipo de contenido del documento con el que trabajes. Para obtener más información, consulta Define una región.
Define una región
Como se mencionó antes, la cadena de anclaje 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 los que se fija un comentario. Un clasificador puede ser un rectángulo bidimensional para una imagen, una línea de texto en un documento o la duración de un video. Para definir una región, selecciona el clasificador de región que coincida con el tipo de contenido al que intentas anclar. 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 región en la API de Drive, consulta Clasificadores de región.
En el siguiente ejemplo, se muestra una cadena de anclaje JSON que ancla los comentarios en las líneas en dos áreas separadas de un documento:
- La primera área comienza en la línea 12 (
'n':12) y se extiende por tres líneas ('l':3). - La segunda á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.
Resolver un comentario
Usa el método comment.update para establecer la propiedad resolved en el recurso comments en true cuando se haya abordado un comentario.
Cuando tu app establece la propiedad resolved en true, la IU debe indicar que se corrigió 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
- Ocultar 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 comentarios como "deleted": "true".
Comentarios de la lista
Usa el método comments.list para enumerar los comentarios. Si deseas incluir comentarios borrados en los resultados, establece el campo includedDeleted en true.