Cómo trabajar con sugerencias

Documentos de Google permite que los colaboradores hagan sugerencias que son, en efecto, ediciones diferidas que esperan aprobación.

Cuando usas el método documents.get para recuperar el contenido del documento, es posible que este incluya sugerencias no resueltas. Para controlar cómo documents.get representa las sugerencias, usa el parámetro opcional SuggestionsViewMode. Las siguientes condiciones de filtro están disponibles con este parámetro:

  • Obtén contenido con SUGGESTIONS_INLINE, de modo que el texto pendiente de eliminación o inserción aparezca en el documento.
  • Obtén contenido como vista previa con todas las sugerencias aceptadas.
  • Obtener contenido como vista previa, sin sugerencias, con todas las sugerencias rechazadas.

Si no proporcionas SuggestionsViewMode, la API de Google Docs usará un parámetro de configuración predeterminado adecuado para los privilegios del usuario actual.

Sugerencias e índices

Un motivo por el que SuggestionsViewMode es importante es que los índices de la respuesta pueden variar según si hay sugerencias, como se muestra a continuación.

Contenido con sugerencias Contenido sin sugerencias 
{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 51,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 50,
          "textRun": {
           "content": "Suggested insertion",
           "suggestedInsertionIds": [
            "suggest.vcti8ewm4mww"
           ],
           "textStyle": {}
          }
         },
         {
          "startIndex": 50,
          "endIndex": 51,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 51,
       "endIndex": 81,
       "paragraph": {
        "elements": [
         {
          "startIndex": 51,
          "endIndex": 81,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},


{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 32,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 32,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 32,
       "endIndex": 62,
       "paragraph": {
        "elements": [
         {
          "startIndex": 32,
          "endIndex": 62,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

En la respuesta anterior, el párrafo que contiene la línea "Texto después de la sugerencia" muestra la diferencia cuando se usa SuggestionsViewMode. Con el valor establecido en SUGGESTIONS_INLINE, el startIndex del ParagraphElement comienza en 51 y el endIndex se detiene en 81. Sin sugerencias, el rango de startIndex y endIndex es de 32 a 62.

Cómo obtener contenido sin sugerencias

En el siguiente ejemplo de código parcial, se muestra cómo obtener un documento como vista previa con todas las sugerencias rechazadas (si las hay) configurando el parámetro SuggestionsViewMode en PREVIEW_WITHOUT_SUGGESTIONS.

Java

final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();

Python

SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"
result = (
  service.documents()
  .get(
      documentId=DOCUMENT_ID,
      includeTabsContent=True,
      suggestionsViewMode=SUGGEST_MODE,
  )
  .execute()
)

Omitir el parámetro SuggestionsViewMode equivale a proporcionar DEFAULT_FOR_CURRENT_ACCESS como el valor del parámetro.

Sugerencias de estilo

Los documentos también pueden tener sugerencias de estilo. Estos son cambios sugeridos en el formato y la presentación, no en el contenido.

A diferencia de las inserciones o eliminaciones de texto, estas no compensan los índices (aunque pueden dividir un TextRun en fragmentos más pequeños), sino que solo agregan anotaciones sobre el cambio de estilo sugerido.

Una de esas anotaciones es SuggestedTextStyle, que consta de 2 partes:

  • El textStyle, que describe cómo se aplica el estilo al texto después del cambio sugerido, pero no indica qué cambió.

  • El textStyleSuggestionState, que indica cómo la sugerencia altera los campos del textStyle.

Puedes ver esto en el siguiente extracto de la pestaña del documento, que incluye un cambio de estilo sugerido:

[01] "paragraph": {
[02]    "elements": [
[03]        {
[04]            "endIndex": 106,
[05]            "startIndex": 82,
[06]            "textRun": {
[07]                "content": "Some text that does not ",
[08]                "textStyle": {}
[09]            }
[10]        },
[11]        {
[12]            "endIndex": 115,
[13]            "startIndex": 106,
[14]            "textRun": {
[15]                "content": "initially",
[16]                "suggestedTextStyleChanges": {
[17]                    "suggest.xymysbs9zldp": {
[18]                        "textStyle": {
[19]                            "backgroundColor": {},
[20]                            "baselineOffset": "NONE",
[21]                            "bold": true,
[22]                            "fontSize": {
[23]                                "magnitude": 11,
[24]                                "unit": "PT"
[25]                            },
[26]                            "foregroundColor": {
[27]                                "color": {
[28]                                    "rgbColor": {}
[29]                                }
[30]                            },
[31]                            "italic": false,
[32]                            "smallCaps": false,
[33]                            "strikethrough": false,
[34]                            "underline": false
[35]                        },
[36]                        "textStyleSuggestionState": {
[37]                            "boldSuggested": true,
[38]                            "weightedFontFamilySuggested": true
[39]                        }
[40]                    }
[41]                },
[42]                "textStyle": {
[43]                    "italic": true
[44]                }
[45]            }
[46]        },
[47]        {
[48]            "endIndex": 143,
[49]            "startIndex": 115,
[50]            "textRun": {
[51]                "content": " contain any boldface text.\n",
[52]                "textStyle": {}
[53]            }
[54]        }
[55]    ],
[56]    "paragraphStyle": {
[57]        "direction": "LEFT_TO_RIGHT",
[58]        "namedStyleType": "NORMAL_TEXT"
[59]    }
[60] }

En el ejemplo anterior, el párrafo consta de 3 ejecuciones de texto, que comienzan en las líneas 6, 14 y 50. Examina la ejecución de texto central:

  • Línea 16: Hay un objeto suggestedTextStyleChanges.
  • Línea 18: El textStyle especifica varios formatos.
  • Línea 36: El textStyleSuggestionState te indica que solo la parte en negrita de esta especificación fue la sugerencia.
  • Línea 42: El estilo en cursiva de este tramo de texto forma parte del documento actual (y no se ve afectado por la sugerencia).

Solo las funciones de diseño establecidas en true en el objeto textStyleSuggestionState forman parte de la sugerencia.