Struttura e stile del testo

Nell'API Presentazioni, il testo può essere contenuto in forme o nelle celle di una tabella. Prima di poter manipolare e applicare stili al testo, devi conoscerne la struttura e il funzionamento dello stile.

Questa pagina descrive come viene rappresentato il testo nell'API Presentazioni.

Sequenze di elementi di testo

Il testo contenuto in una forma o in una cella di tabella è costituito da una sequenza di strutture TextElement. Questa sequenza rappresenta la struttura del testo, nell'ordine di visualizzazione.

Ad esempio, consideriamo i contenuti di questa diapositiva, tutti contenuti in un'unica casella di testo:

La slide riportata sopra ha una casella di testo il cui campo text contiene una sequenza di elementi di testo, come mostrato nel seguente diagramma:

Più concretamente, questa sequenza di testo è rappresentata nell'API Presentazioni nel seguente modo:

"textElements": [ {
    "endIndex": 224,
    "paragraphMarker": { "style": {} }
  }, {
    "endIndex": 130,
    "textRun": { "content": "Li lingues differe in li grammatica e li vocabules. Omnicos directe al desirabilite de un nov ", "style": {} }
  }, {
    "endIndex": 143,
    "startIndex": 130,
    "textRun": { "content": "lingua franca", "style": { "italic": True } }
  }, {
    "endIndex": 224,
    "startIndex": 143,
    "textRun": { "content": ": solmen va esser necessi far:\n", "style": {} }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "paragraphMarker": {
      "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
      "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "textRun": { "content": "uniform grammatica\n", "style": {} }
  }, {
    "endIndex": 257,
    "startIndex": 243,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 257,
    "startIndex": 243,
    "textRun": { "content": "Pronunciation\n", "style": {} }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "textRun": { "content": "plu sommun paroles.\n", "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "paragraphMarker": { "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "textRun": { "content": "Ka swu thefognay, tay waddeant varpa u inzo.\n", "style": {} }
}]

Contenuti di TextElement

Ogni elemento di testo contiene un indice iniziale e un indice finale in base zero, che descrivono la posizione dell'elemento nel testo completo dell'elemento di pagina, insieme a uno dei seguenti tipi di oggetto di testo:

Tipo di testo	Descrizione
ParagraphMarker	Questo elemento di testo rappresenta l'inizio di un nuovo paragrafo. L'indice iniziale e finale dell'elemento di testo rappresenta l'intervallo completo del paragrafo, incluso il carattere di nuova riga che termina il paragrafo. Un paragrafo non si sovrappone mai a un altro. I paragrafi terminano sempre con un carattere di nuova riga, quindi c'è sempre una nuova riga alla fine dei contenuti testuali di una forma o di una cella di una tabella. I paragrafi possono appartenere a elenchi puntati o numerati. In tal caso, i contenuti del campo ParagraphMarker.bullet includono un ID elenco. Questo ID fa riferimento a un elemento dell'elenco che esiste all'interno di TextContent insieme alla sequenza TextElement. I paragrafi all'interno dello stesso elenco logico faranno riferimento allo stesso ID elenco.
TextRun	Questo elemento di testo rappresenta una stringa di testo contigua che ha lo stesso stile di testo. Le esecuzioni del testo non superano i limiti del paragrafo: anche se il testo che termina un paragrafo ha lo stesso stile del testo che inizia il paragrafo successivo, i contenuti vengono suddivisi dopo il carattere della nuova riga per formare esecuzioni di testo separate. Se devi elaborare la stringa di testo completa all'interno di un elemento di pagina, ripeti tutti gli elementi di testo, concatenando le stringhe trovate in tutto il testo.
AutoText	Autotext si riferisce ai punti del testo che cambiano in modo dinamico a seconda del contesto. In Presentazioni, questo viene utilizzato per rappresentare il numero della slide corrente all'interno del testo.

In futuro, l'API Presentazioni potrebbe includere altri tipi di elementi di testo. Il codice che elabora il testo deve gestire automaticamente i nuovi tipi di elementi di testo, in genere ignorando i tipi sconosciuti.

Modifica dei contenuti testuali

Quando devi modificare il testo utilizzando l'API Presentazioni, non è necessario creare esplicitamente tutti gli elementi di testo appropriati. Puoi invece intervenire sul testo come nell'editor di Presentazioni: inserendo testo, eliminando intervalli e aggiornando gli stili sugli intervalli. Queste operazioni creano implicitamente gli elementi ParagraphMarker e TextRun secondo necessità per riflettere le modifiche.

Inserimento di testo

Puoi inserire il testo in un indice utilizzando la richiesta InsertTextRequest in una chiamata a batchUpdate. Il campo insertionIndex di questo metodo specifica dove inserire il testo; puoi calcolare questo indice utilizzando i campi di indice iniziale e finale all'interno degli elementi di testo.

L'inserimento del testo ha alcuni effetti collaterali che rispecchiano il comportamento dell'editor di Presentazioni:

• L'inserimento di un carattere di nuova riga crea implicitamente un nuovo paragrafo, creando un elemento di testo ParagraphMarker che inizia in corrispondenza dell'indice della nuova riga e termina in corrispondenza della nuova riga successiva. Lo stile di paragrafo, inclusi i dettagli di punti ed elenchi, viene copiato dal paragrafo corrente al nuovo paragrafo.
• Lo stile dei caratteri inseriti viene determinato automaticamente, generalmente mantenendo lo stesso stile di testo esistente nell'indice di inserimento. Di conseguenza, il testo viene generalmente inserito nell'elemento TextRun esistente in quell'indice. Puoi aggiornare questo stile in un secondo momento utilizzando una richiesta UpdateTextStyle.

Eliminazione del testo in corso...

Puoi eliminare un intervallo di testo utilizzando il messaggio DeleteTextRequest in una chiamata a batchUpdate. L'eliminazione del testo prevede alcune sfumature:

• Un'eliminazione che attraversa il limite di un paragrafo unisce i due paragrafi, eliminando l'elemento di testo ParagraphMarker che separa.
• Il nuovo paragrafo unito utilizzerà uno stile di paragrafo combinato, con un comportamento corrispondente nell'editor di Presentazioni.
• Un'eliminazione il cui intervallo comprende un'esecuzione di testo rimuove tutti i contenuti da un'esecuzione di testo ed elimina anche l'esecuzione del testo stessa.
• Un'eliminazione il cui intervallo comprende un elemento AutoText elimina l'elemento AutoText.

Aggiornamento dello stile del testo

L'aspetto visualizzato del testo in una slide è determinato dalle proprietà dello stile di testo:

• Gli stili paragrafo, come rientro, allineamento e glifi elenco puntato, sono definiti dalle proprietà degli indicatori di paragrafo.
• Gli stili di carattere, come grassetto, corsivo e sottolineato, sono definiti dalle proprietà sulle singole esecuzioni di testo.

Aggiornamento dello stile dei caratteri

Puoi aggiornare gli stili dei caratteri tramite il messaggio UpdateTextStyleRequest in una chiamata a batchUpdate.

Come altre operazioni di testo, lo stile dei caratteri viene applicato a un intervallo di testo e crea implicitamente nuovi oggetti TextRun secondo necessità.

L'impostazione di alcuni stili di carattere aggiorna implicitamente altri stili correlati in modo che corrispondano al comportamento nell'editor di Presentazioni. Ad esempio, l'aggiunta di un link modifica automaticamente le proprietà di colore in primo piano e sottolineatura. Per ulteriori dettagli, consulta la documentazione di riferimento di TextStyle.

Aggiornamento dello stile di paragrafo in corso...

Puoi aggiornare gli stili di paragrafo tramite il messaggio UpdateParagraphStyleRequest in una chiamata a batchUpdate.

L'API Presentazioni supporta una richiesta CreateParagraphBulletsRequest, che rispecchia la funzionalità delle preimpostazioni dei punti elenco nell'editor di Presentazioni per la creazione di elenchi puntati e numerati. Allo stesso modo, DeleteParagraphBulletsRequest rimuove tutti i punti elenco esistenti nei paragrafi.

Stili ereditati

Alcune forme, note come placeholders, possono ereditare gli stili di testo da altre forme principali. Per ulteriori informazioni sull'ereditarietà delle forme in generale, consulta la sezione placeholders.

Questa sezione è incentrata sull'ereditarietà degli stili per creare gli stili di testo finali sottoposti a rendering visualizzati in una slide.

Rappresentazione degli stili nei segnaposto

La sezione sui placeholders descrive come funziona l'ereditarietà tra forme padre e figlio. L'ereditarietà degli stili di testo viene gestita da funzionalità aggiuntive all'interno del modello di ereditarietà:

• Le proprietà degli elementi di testo ParagraphMaker definiscono la formattazione del paragrafo.
• Le proprietà degli elementi di testo TextRun definiscono la formattazione dei caratteri.
• Il contenuto dei segnaposto principali contiene otto di queste coppie ParagraphMarker/TextRun (per supportare otto livelli di nidificazione di elenchi).
• Un segnaposto secondario eredita le proprietà di testo predefinite da questi elementi di testo nei contenuti di testo del segnaposto principale.

Il seguente diagramma mostra un modo per visualizzare queste relazioni:

Il primo ParagraphMarker/TextRun nel formato principale determina la maggior parte degli stili di testo ereditati; gli stili delle altre sette coppie influiscono solo sui paragrafi a livelli di punti elenco nidificati progressivamente:

Coppia elementi di testo principale	Formattazione dell'elemento secondario che controlla
Prime ParagraphMarker prime TextRun	Stile di testo dei paragrafi di livello 0 (più esterno) dell'elenco e di tutti i paragrafi che non sono elencati.
Secondo ParagraphMarker secondo TextRun	Stile di testo dei livelli 1-7 degli elenchi rimanenti (nidificati)
Terza ParagraphMarker terza TextRun
Quarta ParagraphMarker Quarta TextRun
Quinto ParagraphMarker Quinto TextRun
Sesta ParagraphMarker Sesta TextRun
Settimo ParagraphMarker Settimo TextRun
Ottava ParagraphMarker Ottava TextRun

Per accedere a queste coppie di elementi di testo, utilizza il relativo indice esplicito all'interno del campo textElements come mostrato nello snippet riportato di seguito, che mostra l'impostazione dello stile predefinito (ereditabile) per i paragrafi di livello 0 e non in elenco:

"text": {
  "textElements": [  {
     "startIndex": 0,
     "endIndex": 1,
     "paragraphMarker": {
       "style": {  "alignment": "START",  ...  },
       "bullet": {  "nestingLevel": 0,  ...  }
     }
   },{
     "startIndex": 0,
     "endIndex": 1,
     "textRun": {
       "content": "\n",
       "style": {  "foregroundColor": {  "opaqueColor": {  "themeColor": "DARK1"  }  },  }
     }
   },{
     ...
   } ]
 }

Tieni presente che il campo content dell'elemento TextRun di una forma principale è sempre costituito da un singolo carattere di nuova riga.

Gli stili ereditati possono essere sostituiti

Una forma secondaria può specificare le proprietà di stile per gli elementi ParagraphMarker e TextRun nei suoi contenuti. Queste proprietà specificate localmente sostituiranno tutte le proprietà ereditate all'interno dell'ambito locale. Negli elementi che non specificano alcuno stile verrà utilizzato lo stile corrispondente ereditato dall'elemento padre.

Se rimuovi una proprietà di stile esplicita da una forma secondaria, in modo che non sia più impostata, la proprietà verrà ereditata dalla forma principale.

Esempio

Data l'ereditarietà mostrata nel diagramma sopra, supponiamo che la forma ParentPlaceholder abbia i seguenti contenuti testuali:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {"alignment": "START", ...},
        "bullet": {"nestingLevel": 0, ...}
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, }
        ...
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {"alignment": "END", ...},
        "bullet": {"nestingLevel": 1, ...}
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "LIGHT1"} }, ...}
      }
    },
   ...
  ]
}

Supponiamo che la forma ChildPlaceholder abbia il seguente contenuto testuale:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    {  "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {
          "nestingLevel": 1,
          "listId": "someListId",
          "glyph": "●"
        }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {},
        ...
      }
    }
  ]
}

Questo dà come risultato i risultati descritti nei paragrafi seguenti.

Ereditarietà dello stile per un paragrafo normale

Il primo paragrafo della forma secondaria, che include il testo "This is my first paragraph", è un paragrafo normale (non in un elenco). Nessun elemento dei contenuti testuali specifica proprietà di stile, pertanto eredita tutti gli stili di carattere e paragrafo dal relativo elemento principale. Ciò causa il seguente rendering:

• Testo: "Questo è il mio primo paragrafo" è il testo visualizzato. Il testo in sé non viene mai ereditato.
• Allineamento: il testo viene visualizzato con l'allineamento START, ereditato dal primo ParagraphMarker del padre.
• Colore di primo piano: il testo viene visualizzato con il colore di primo piano DARK1, ereditato dal primo TextRun del publisher principale.

Ereditarietà dello stile per un paragrafo dell'elenco

Il paragrafo successivo, che include il testo "Questo paragrafo è in un elenco", si trova in un elenco puntato al livello di nidificazione 1, poiché il campo bullet corrispondente è impostato su questo livello.ParagraphMarker Di conseguenza, eredita il testo e lo stile di paragrafo dal livello di nidificazione 1 nell'elemento principale. Il risultato è il seguente rendering:

• Testo: "Questo paragrafo è in un elenco" è il testo visualizzato. Il testo in sé non viene mai ereditato.
• Allineamento: il testo viene visualizzato con l'allineamento"END", ereditato dal secondo ParagraphMarker del padre.
• Colore di primo piano: il testo viene visualizzato con il colore LIGHT1 in primo piano, che viene ereditato dal secondo TextRun del publisher principale.

Interazioni tra l'aggiornamento e l'ereditarietà degli stili di testo e paragrafo

Gli stili di testo che non sono impostati in una forma secondaria erediteranno i valori da quelli principali. Gli stili di testo impostati nell'elemento secondario "sostituiranno" i valori padre in un determinato ambito locale.

Puoi utilizzare un oggetto UpdateTextStyleRequest per annullare l'impostazione dello stile di testo di una forma secondaria, in modo che non abbia più una sostituzione locale e quindi erediti i relativi stili dalla forma principale. Inoltre, l'aggiornamento dello stile di testo del publisher secondario in modo che corrisponda al valore ereditato da un elemento principale annulla implicitamente lo stile in modo che utilizzi il valore ereditato.

L'impostazione dello stile di una forma secondaria affinché corrisponda esattamente a quello della forma principale (il che comporta l'ereditarietà dello stile) ha lo stesso risultato dell'annullamento dello stile della forma secondaria.

Ciò non influisce sull'aspetto visivo del testo immediatamente dopo un aggiornamento, ma potrebbe essere importante se in seguito aggiorni un paragrafo o uno stile di testo in un segnaposto principale. Questo comportamento di ereditarietà corrisponde a quello dell'editor di Presentazioni, per consentirti di sperimentare i risultati delle modifiche di stile prima di lavorare sull'API.

Esempio

Considera le definizioni nell'esempio precedente di ChildPlaceholder e ParentPlaceholder.

Ora supponi di inviare questa richiesta UpdateTextStyleRequest:

{ "updateTextStyle": {
    "objectId": "ChildPlaceholder",
    "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
    "textRange": { "type": "ALL" },
    "fields": "foregroundColor"
  }
}

Questa richiesta cerca di impostare un valore DARK1 primo piano per tutto il testo di ChildPlaceholder, utilizzando una maschera di campo per specificare che deve cambiare solo il colore di primo piano dell'elemento. Questa richiesta ha i seguenti risultati:

• Primo paragrafo: il nuovo foregroundColor corrisponde all'elemento foregroundColor ereditato, pertanto questo stile è invariato e eredita.
• Secondo paragrafo: il nuovo foregroundColor non corrisponde al valore foregroundColor ereditato, quindi il colore in primo piano del secondo paragrafo viene aggiornato in DARK1.

Il contenuto testuale di ChildPlaceholder è ora:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {"nestingLevel": 1, "listId": "someListId", "glyph": "●" }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
        ...
      }
    }
  ]
}

Stile testo glifo elenco puntato

Come il testo normale, i glifi punti elenco hanno uno stile di testo che controlla come viene visualizzato. Questi stili di testo non possono essere modificati direttamente utilizzando l'API Presentazioni. Tuttavia, se utilizzi una funzione UpdateTextStyleRequest per aggiornare un paragrafo completo che include un punto elenco, l'API Presentazioni aggiorna lo stile di testo del glifo bullet in modo che corrisponda.

Gli stili di testo dei glifi elenco puntato seguono una gerarchia di ereditarietà leggermente diversa rispetto agli stili di testo normali.

1. Un punto elenco a un determinato livello di nidificazione eredita prima dal set TextStyle nel campo NestingLevel.bullet_style all'interno dell'oggetto List del punto elenco.
2. Poi eredita dal valore NestingLevel.bullet_style corrispondente nel valore List del segnaposto principale.
3. Infine cerca di ereditare dagli oggetti segnaposto padre rimanenti.

Gli elenchi puntati nei segnaposto dei layout e degli schemi hanno un valore "TextStyle" vuoto nel campo "ParagraphMarker.bullet" e gli eventuali aggiornamenti di stile di testo su questi paragrafi verranno riportati solo nei messaggi "Elenco".