Lavorare con i suggerimenti

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

Quando utilizzi il metodo documents.get per recuperare i contenuti del documento, i contenuti potrebbero includere suggerimenti non risolti. Per controllare la modalità di rappresentazione dei suggerimenti da parte di documents.get, utilizza il parametro facoltativo SuggestionsViewMode. Con questo parametro sono disponibili le seguenti condizioni di filtro:

  • Inserisci i 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 ai privilegi dell'utente corrente.

Suggerimenti e indici

Un motivo per cui SuggestionsViewMode è importante è che gli indici nella risposta possono variare a seconda che siano presenti suggerimenti, come mostrato di seguito.

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

Nella risposta precedente, il paragrafo contenente la riga "Testo che segue il suggerimento" mostra la differenza quando si utilizza SuggestionsViewMode. Con il valore impostato su SUGGESTIONS_INLINE, il startIndex di ParagraphElement inizia a 51 e il endIndex si ferma a 81. Senza suggerimenti, startIndex e endIndex vanno da 32 a 62.

Trovare 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.

JavaPython

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

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

L'omissione del parametro SuggestionsViewMode è equivalente all'indicazione di DEFAULT_FOR_CURRENT_ACCESS come valore del parametro.

Suggerimenti di stile

I documenti possono anche avere suggerimenti di stile. Si tratta di modifiche suggerite alla formattazione e alla presentazione, non ai contenuti.

A differenza delle inserzioni o delle eliminazioni di testo, queste non compensano gli indici, anche se potrebbero suddividere un TextRun in blocchi più piccoli, ma aggiungono solo annotazioni sulla modifica dello stile suggerita.

Una di queste annotazioni è un SuggestedTextStyle, che è costituito da due parti:

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

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

Puoi visualizzarlo nell'estratto della scheda del documento riportato di seguito, che include una modifica dello 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 riportato sopra, il paragrafo è costituito da tre righe di testo, che iniziano rispettivamente alle righe 6, 14 e 50. Esamina la riga di testo centrale:

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

Solo le funzionalità di stile impostate su true in textStyleSuggestionState fanno parte del suggerimento.