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: los anclados y los no anclados. 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. Por el contrario, un comentario no anclado solo se asocia con el documento.
Las respuestas se adjuntan a los comentarios y representan la respuesta de un usuario al comentario. La API de Google Drive permite a los usuarios agregar comentarios y respuestas a los documentos creados por la app. En conjunto, un comentario con respuestas se conoce como debate.
Cómo agregar un comentario no anclado
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 reply 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 para mostrarse.
Agregar un comentario fijo a la última revisión de un documento
Cuando agregas un comentario, es posible que quieras anclarlo a una región del archivo. Un ancla define la revisión y región del archivo al que hace referencia un comentario. El recurso comments define el campo anchor como una cadena JSON.
Para agregar un comentario fijo, sigue estos pasos:
(Opcional). Llama al método
revisions.listpara enumerar cadarevisionIDde un documento. Solo sigue este paso si deseas anclar un comentario a cualquier revisión que no sea la más reciente. Si deseas usar la revisión más reciente, utilizaheadpara elrevisionID.Llama al método
comments.createcon el parámetrofileID, un recursocommentsque contiene el comentario y una cadena de anclaje JSON que contiene elrevisionID(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 Cómo definir una región a continuación.
Define una región
Como se mencionó anteriormente, la string de anclaje JSON contiene una revisionID (r) y una región (a). La región (a) es un array JSON que contiene clasificadores regionales 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, la duración de un video, etcétera. Para definir una región, selecciona el clasificador de región que coincida con el tipo de contenido al que intentas anclarte. 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 fija comentarios a las líneas en 2 áreas distintas 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 abordó el comentario. Por ejemplo, tu app podría hacer lo siguiente:
- No permitir respuestas adicionales y atenuar todas las respuestas anteriores además del comentario original
- Ocultar 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 comentarios como "deleted": "true".
Lista de comentarios
Usa el método comments.list para enumerar comentarios. Si deseas incluir comentarios borrados en los resultados, establece el campo includedDeleted en true.