Lavorare con i suggerimenti

Documenti Google consente ai collaboratori di fare suggerimenti che sono a tutti gli effetti modifiche posticipate in attesa di approvazione.

Puoi utilizzare l'API per visualizzare i suggerimenti, ma non per accettarli, rifiutarli o crearli in modo programmatico.

Quando utilizzi il documents.get metodo 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:

  • Recupera i contenuti con SUGGESTIONS_INLINE, in modo che nel documento venga visualizzato il testo in attesa di eliminazione o inserimento.
  • Recupera i contenuti come anteprima con tutti i suggerimenti accettati.
  • Recupera 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 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 sopra, il paragrafo contenente la riga "Testo dopo il suggerimento" mostra la differenza quando si utilizza SuggestionsViewMode. Con il valore impostato su SUGGESTIONS_INLINE, il startIndex di ParagraphElement inizia da 51 e il endIndex si ferma a 81. Senza suggerimenti, l'intervallo startIndex e endIndex va da 32 a 62.

Recuperare i contenuti senza suggerimenti

Il seguente esempio di codice parziale mostra come recuperare 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()
)

Omettere il parametro SuggestionsViewMode equivale a fornire DEFAULT_FOR_CURRENT_ACCESS come valore parametro.

Suggerimenti di stile

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

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

Una di queste annotazioni è un SuggestedTextStyle, che è composto 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 di textStyle.

Puoi vedere questo nell'estratto della scheda del documento seguente, 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 sopra, il paragrafo è composto da tre 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 varie 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 le funzionalità di stile impostate su true in textStyleSuggestionState fanno parte del suggerimento.