Trabalhar com sugestões

No Documentos Google, os colaboradores podem fazer sugestões que são edições adiadas aguardando aprovação.

Quando você usa o método documents.get para buscar o conteúdo de documentos, o conteúdo pode incluir sugestões não resolvidas. Para controlar como o documents.get representa as sugestões, use o parâmetro opcional SuggestionsViewMode. As seguintes condições de filtro estão disponíveis com esse parâmetro:

  • Receber conteúdo com SUGGESTIONS_INLINE para que o texto com exclusão ou inserção pendente apareça no documento.
  • Receber conteúdo como uma prévia com todas as sugestões aceitas.
  • Recebe o conteúdo como uma visualização, sem sugestões, com todas as sugestões rejeitadas.

Se você não informar SuggestionsViewMode, a API Google Docs usará uma configuração padrão apropriada aos privilégios do usuário atual.

Sugestões e índices

Um motivo para SuggestionsViewMode ser importante é que os índices na resposta podem variar se houver sugestões, conforme mostrado abaixo.

Conteúdo com sugestões Conteúdo sem sugestões 
{
 "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"
  }
 }
},


{
 "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"
  }
 }
},

Na resposta acima, o parágrafo com a linha "Texto após a sugestão" mostra a diferença ao usar SuggestionsViewMode. Com o valor definido como SUGGESTIONS_INLINE, o startIndex do ParagraphElement começa em 51 e o endIndex para em 81. Sem sugestões, startIndex e endIndex vão de 32 a 62.

Receber conteúdo sem sugestões

O exemplo de código parcial a seguir mostra como receber um documento como visualização com todas as sugestões rejeitadas (se houver) definindo o parâmetro SuggestionsViewMode como PREVIEW_WITHOUT_SUGGESTIONS.

Java

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

Python

SUGGEST_MODE="PREVIEW_WITHOUT_Suggest" result = service.documents().get(documentId=DOCUMENT_ID, suggestionsViewMode=SUGGEST_MODE).execute()

Omitir o parâmetro SuggestionsViewMode é equivalente a fornecer DEFAULT_FOR_CURRENT_ACCESS como o valor do parâmetro.

Sugestões de estilo

Os documentos também podem ter sugestões de estilo. São sugestões de mudanças na formatação e na apresentação, em vez de alterações no conteúdo.

Ao contrário das inserções ou exclusões de texto, elas não deslocam os índices, embora possam dividir um TextRun em partes menores, apenas adicionam anotações sobre a mudança de estilo sugerida.

Uma dessas anotações é um SuggestedTextStyle, que consiste em duas partes:

  • O textStyle, que descreve como o texto é estilizado após a mudança sugerida, mas não informa o que mudou.

  • O textStyleSuggestionState, que indica como a sugestão altera os campos de textStyle.

Você pode conferir isso na seguinte extração de documento, que inclui uma mudança de estilo sugerida:

[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] }

No exemplo acima, o parágrafo consiste em três execuções de texto, começando nas linhas 6, 14 e 50. Analise o texto do meio:

  • Linha 16: há um objeto suggestedTextStyleChanges.
  • Linha 18: o textStyle especifica várias formatações.
  • Linha 36: o textStyleSuggestionState informa que apenas a parte em negrito dessa especificação foi a sugestão.
  • Linha 42: o estilo em itálico da execução do texto faz parte do documento atual e não é afetado pela sugestão.

Somente os recursos de estilo definidos como true em textStyleSuggestionState fazem parte da sugestão.