Trabalhar com sugestões

O Documentos Google permite que os colaboradores façam sugestões que são edições adiadas aguardando aprovação.

Você pode usar a API para conferir sugestões, mas não para aceitá-las, rejeitá-las ou criá-las de maneira programática.

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

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

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

Sugestões e índices

Um dos motivos pelos quais o SuggestionsViewMode é importante é que os índices na resposta podem variar dependendo se há sugestões, conforme mostrado abaixo.

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

Na resposta acima, o parágrafo que contém 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, o intervalo startIndex e endIndex varia de 32 a 62.

Receber conteúdo sem sugestões

O exemplo de código parcial a seguir mostra como receber um documento como uma 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_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 o parâmetro SuggestionsViewMode é equivalente a fornecer DEFAULT_FOR_CURRENT_ACCESS como o valor de parâmetro.

Sugestões de estilo

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

Ao contrário das inserções ou exclusões de texto, elas não compensam os índices, embora possam dividir um TextRun em partes menores, mas 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 diz o que mudou.

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

Você pode conferir isso no extrato da guia no documento a seguir, 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. Examine a execução de 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 dessa execução de texto faz parte do documento atual (e não é afetado pela sugestão).

Apenas os recursos de estilo definidos como true no textStyleSuggestionState fazem parte da sugestão.