Lavorare con i suggerimenti

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

Quando utilizzi il metodo documents.get per recuperare i contenuti del documento, 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:

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

Se non fornisci SuggestionsViewMode, l'API Google Docs utilizza un'impostazione predefinita adatta ai privilegi dell'utente corrente.

Suggerimenti e indici

Uno dei motivi per cui SuggestionsViewMode è importante è che gli indici nella risposta potrebbero 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 "Text following the suggestion" mostra la differenza quando si utilizza SuggestionsViewMode. Se il valore è impostato su SUGGESTIONS_INLINE, l'startIndex di ParagraphElement inizia a 51 e endIndex si ferma a 81. Senza suggerimenti, l'intervallo startIndex e endIndex va da 32 a 62.

Visualizzare i 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)
        .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()
)

L'omissione del parametro SuggestionsViewMode equivale a fornire 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 degli inserimenti o delle eliminazioni di testo, questi non compensano gli indici, anche se potrebbero dividere 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:

  • Il 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 visualizzarlo nel seguente estratto della scheda del documento, 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 precedente, il paragrafo è costituito da tre sequenze 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 varie formattazioni.
  • Riga 36: textStyleSuggestionState indica che solo la parte in grassetto di questa specifica era il suggerimento.
  • Riga 42: La formattazione in corsivo di questo blocco di testo fa parte del documento corrente (e non è interessata dal suggerimento).

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