Lavorare con i suggerimenti

Documenti Google consente ai collaboratori di apportare suggerimenti che sono effettivamente differite in attesa di approvazione.

Quando utilizzi il metodo documents.get per recuperare i contenuti dei documenti, questi potrebbero includere suggerimenti non risolti. Per controllare il modo in cui documents.get rappresenta i suggerimenti, utilizza il parametro facoltativo SuggestionsViewMode. Con questo parametro sono disponibili le seguenti condizioni di filtro:

  • Ottieni contenuti con SUGGESTIONS_INLINE, in modo che il testo in attesa di eliminazione o inserimento venga visualizzato nel documento.
  • Visualizza i contenuti come anteprima con tutti i suggerimenti accettati.
  • Visualizza i contenuti come anteprima, senza suggerimenti, con tutti i suggerimenti rifiutati.

Se non fornisci SuggestionsViewMode, l'API Documenti Google utilizza un'impostazione predefinita appropriata per i privilegi dell'utente corrente.

Suggerimenti e indici

Un motivo per cui SuggestionsViewMode è importante è che gli indici nella risposta potrebbero variare a seconda dell'eventuale presenza di suggerimenti, come mostrato di seguito.

Contenuti con suggerimenti Contenuti senza suggerimenti 
{
 "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"
  }
 }
},

Nella risposta precedente, il paragrafo contenente la riga "Testo dopo il suggerimento" mostra la differenza quando utilizzi SuggestionsViewMode. Con il valore impostato su SUGGESTIONS_INLINE, il valore startIndex di ParagraphElement inizia a 51 e il valore di endIndex si ferma a 81. Senza suggerimenti, startIndex e endIndex sono compresi tra 32 e 62.

Ricevi contenuti senza suggerimenti

Il seguente esempio di codice parziale mostra come ottenere un documento come anteprima con tutti i suggerimenti rifiutati (se presenti) impostando il parametro SuggestionsViewMode su 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" risultato = service.documents().get(documentId=DOCUMENT_ID, suggestionsViewMode=SUGGEST_MODE).execute()

L'omissione del parametro SuggestionsViewMode equivale a fornire DEFAULT_FOR_CURRENT_ACCESS come valore del parametro.

Suggerimenti di stile

I documenti possono anche includere suggerimenti di stile. Si tratta di modifiche suggerite alla formattazione e alla presentazione, piuttosto che modifiche ai contenuti.

A differenza delle operazioni di inserimento o eliminazione di testo, non vengono sfalsate gli indici, anche se potrebbero suddividere un elemento TextRun in blocchi più piccoli, ma possono soltanto aggiungere annotazioni sulla modifica di stile suggerita.

Un'annotazione di questo tipo è un'annotazione SuggestedTextStyle, che consiste di 2 parti:

  • textStyle, che descrive lo stile del testo dopo la modifica suggerita, ma non indica cosa è cambiato.

  • textStyleSuggestionState, che indica in che modo il suggerimento modifica i campi di textStyle.

Puoi vederla nel seguente estratto del documento, che include una modifica di stile suggerita:

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

Nell'esempio precedente, il paragrafo è composto da 3 esecuzioni di testo, a partire dalle righe 6, 14 e 50. Esamina l'esecuzione del testo centrale:

  • Riga 16: è presente un oggetto suggestedTextStyleChanges.
  • Riga 18: textStyle specifica diverse formattazioni.
  • Riga 36: textStyleSuggestionState indica che solo la parte in grassetto di questa specifica era il suggerimento.
  • Riga 42: lo stile in corsivo di questa esecuzione di testo fa parte del documento corrente (e non è interessato dal suggerimento).

Solo gli elementi di stile impostati su true in textStyleSuggestionState fanno parte del suggerimento.