Utiliser les suggestions

Google Docs permet aux collaborateurs de faire des suggestions qui correspondent à des modifications réellement différées en attente d'approbation.

Lorsque vous utilisez la méthode documents.get pour récupérer le contenu d'un document, celui-ci peut inclure des suggestions non résolues. Pour contrôler la façon dont documents.get représente les suggestions, utilisez le paramètre SuggestionsViewMode facultatif. Les conditions de filtre suivantes sont disponibles avec ce paramètre:

  • Permet d'obtenir du contenu avec SUGGESTIONS_INLINE, de sorte que le texte en attente de suppression ou d'insertion s'affiche dans le document.
  • Obtenez un aperçu du contenu avec toutes les suggestions acceptées.
  • Permet d'obtenir un aperçu du contenu, sans aucune suggestion, et toutes les suggestions sont refusées.

Si vous ne fournissez pas SuggestionsViewMode, l'API Google Docs utilise un paramètre par défaut adapté aux droits de l'utilisateur actuel.

Suggestions et index

L'une des raisons pour lesquelles SuggestionsViewMode est important est que les index de la réponse peuvent varier en fonction de la présence ou non de suggestions, comme indiqué ci-dessous.

Contenu avec suggestions Contenu sans suggestions 
{
 "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"
  }
 }
},

Dans la réponse ci-dessus, le paragraphe contenant la ligne "Texte suivant la suggestion" montre la différence lorsque vous utilisez SuggestionsViewMode. Avec la valeur définie sur SUGGESTIONS_INLINE, le startIndex de ParagraphElement commence à 51 et endIndex s'arrête à 81. Sans suggestions, les valeurs startIndex et endIndex sont comprises entre 32 et 62.

Obtenir des contenus sans suggestions

L'exemple de code partiel suivant montre comment obtenir un aperçu d'un document avec toutes les suggestions refusées (le cas échéant) en définissant le paramètre SuggestionsViewMode sur PREVIEW_WITHOUT_SUGGESTIONS.

Java

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

Python

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

Si vous omettez le paramètre SuggestionsViewMode, cela revient à fournir DEFAULT_FOR_CURRENT_ACCESS comme valeur de paramètre.

Suggestions de style

Les documents peuvent également comporter des suggestions de style. Il s'agit de modifications suggérées de la mise en forme et de la présentation, et non du contenu.

Contrairement aux insertions ou aux suppressions de texte, celles-ci ne compensent pas les index, bien qu'elles puissent diviser une TextRun en fragments plus petits, mais simplement ajouter des annotations concernant le changement de style suggéré.

L'une de ces annotations est l'annotation SuggestedTextStyle, composée de deux parties:

  • Le textStyle, qui décrit le style du texte après la modification suggérée, mais qui n'indique pas ce qui a changé.

  • Le textStyleSuggestionState, qui indique comment la suggestion modifie les champs de l'textStyle.

Vous pouvez le voir dans l'extrait de document suivant, qui inclut une suggestion de modification de style:

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

Dans l'exemple ci-dessus, le paragraphe comprend trois exécutions de texte, en commençant aux lignes 6, 14 et 50. Examinez l'exécution du texte du milieu:

  • Ligne 16: un objet suggestedTextStyleChanges
  • Ligne 18: textStyle spécifie plusieurs mises en forme.
  • Ligne 36: textStyleSuggestionState vous indique que seule la partie en gras de cette spécification était la suggestion.
  • Ligne 42: le style en italique de cette exécution de texte fait partie du document actuel (et n'est pas affecté par la suggestion).

Seuls les éléments géographiques définis sur true dans textStyleSuggestionState font partie de la suggestion.