Struttura e stile del testo

Nell'API Slides, il testo può essere contenuto in forme o in celle di tabelle. Prima di poter manipolare e applicare stili al testo, devi comprenderne la struttura e il funzionamento degli stili.

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

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 in cui appare dall'inizio alla fine.

Ad esempio, prendi in considerazione i contenuti di questa diapositiva, tutti contenuti in una sola casella di testo:

screenshot di una diapositiva semplice

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

Diagramma che mostra una sequenza di elementi di testo

Più concretamente, questa sequenza di testo è rappresentata nell'API Slides come segue:

"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 a partire da zero, che descrivono la posizione dell'elemento all'interno del testo completo dell'elemento pagina, insieme a uno dei seguenti tipi di oggetti 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'intero intervallo del paragrafo, incluso il carattere di nuova riga che termina il paragrafo. Un paragrafo non si sovrappone mai a un altro paragrafo. I paragrafi terminano sempre con un carattere di a capo, quindi alla fine dei contenuti di testo di una forma o di una cella di tabella è sempre presente un a capo.

I paragrafi possono appartenere a elenchi puntati o numerati. In questo caso, i contenuti del campo ParagraphMarker.bullet includono un ID elenco. Questo ID fa riferimento a un elemento dell'elenco esistente 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 corse di testo non attraversano mai i confini dei paragrafi: 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 di a capo per formare corse di testo separate.

Se devi elaborare la stringa di testo completa all'interno di un elemento di pagina, esegui l'iterazione di tutti gli elementi di testo, concatenando le stringhe trovate in tutte le corse di testo.
AutoText Con Testo automatico si fa riferimento a parti del testo che cambiano dinamicamente in base al contesto. In Presentazioni, viene utilizzato per rappresentare il numero della slide corrente all'interno del testo.

Modifica dei contenuti di testo

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

Inserire del testo

Puoi inserire del 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 di testo ha alcuni effetti collaterali che rispecchiano il comportamento dell'editor di Presentazioni:

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

Eliminazione di testo

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

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

Aggiornamento dello stile di testo

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

  • Gli stili paragrafo, come rientro, allineamento e gli glifi di elenchi puntati, sono definiti dalle proprietà degli indicatori di paragrafo.
  • Gli stili di carattere, come grassetto, corsivo e sottolineato, sono definiti dalle proprietà delle singole righe di testo.

Aggiornamento dello stile dei caratteri

Puoi aggiornare gli stili di carattere utilizzando il messaggio UpdateTextStyleRequest in una chiamata a batchUpdate.

Come per altre operazioni di testo, lo stile di carattere viene applicato a un intervallo di testo e crea implicitamente nuovi oggetti TextRun in base alle esigenze.

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 consente di modificare automaticamente il colore di primo piano del testo e le proprietà di sottolineatura. Per ulteriori dettagli, consulta la documentazione di riferimento di TextStyle.

Aggiornamento dello stile di paragrafo

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

L'API Slides supporta una richiesta CreateParagraphBulletsRequest che rispecchia la funzionalità degli elenchi di punti elenco preimpostati nell'editor di Presentazioni per la creazione di elenchi di punti elenco e numerati. Analogamente, DeleteParagraphBulletsRequest rimuove eventuali elenchi puntati esistenti nei paragrafi.

Stili ereditati

Alcune forme, chiamate segnaposto, possono ereditare gli stili di testo da altre forme principali: consulta la sezione Segnaposto per scoprire di più sull'ereditarietà delle forme in generale.

Questa sezione illustra il funzionamento dell'eredità degli stili per creare gli stili di testo finali visualizzati in una presentazione.

Rappresentazione dello stile nei segnaposto

La sezione relativa ai segnaposto descrive il funzionamento dell'eredità tra le forme principali e secondarie. L'eredità degli stili di testo è 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.
  • I contenuti dei segnaposto principali contengono otto coppie di ParagraphMarker/TextRun (per supportare otto livelli di nidificazione dell'elenco).
  • Un segnaposto secondario eredita le proprietà di testo predefinite da questi elementi di testo nei contenuti di testo del relativo elemento principale.

Il seguente diagramma mostra un modo per visualizzare queste relazioni:

diagramma della forma secondaria che eredita le proprietà di testo

Il primo elemento ParagraphMarker/TextRun nella forma principale determina la maggior parte dello stile di testo ereditato. Lo stile nelle sette coppie rimanenti influisce solo sui paragrafi a livelli di elenchi nidificati progressivamente più profondi:

Coppia di elementi di testo principali La formattazione secondaria che controlla
Primo ParagraphMarker
Primo TextRun		 Stile di testo dei paragrafi dell'elenco di livello 0 (più esterno) e di tutti i paragrafi non in elenco.
Secondo ParagraphMarker
Secondo TextRun		 Stile del testo degli altri livelli di elenco (nidificati) da 1 a 7
Terzo ParagraphMarker
Terzo TextRun
Quarto ParagraphMarker
Quarto TextRun
Quinto ParagraphMarker
Quinto TextRun
Sesto ParagraphMarker
Sesto TextRun
Settimo ParagraphMarker
Settimo TextRun
Ottavo ParagraphMarker
Ottavo TextRun

Per accedere a queste coppie di elementi di testo, utilizza il relativo indice esplicito all'interno del campo textElements, come mostrato nello snippet 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 di 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 relativi contenuti. Queste proprietà specificate localmente sostituiranno eventuali proprietà ereditate all'interno del loro ambito locale. Gli elementi che non specificano alcun stile utilizzeranno lo stile corrispondente ereditato dall'elemento principale.

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

Esempio

Data l'eredità mostrata nel diagramma sopra, supponiamo che la forma ParentPlaceholder abbia i seguenti contenuti di testo:

"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 i seguenti contenuti di testo:

"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": {},
        ...
      }
    }
  ]
}

Ciò comporta i risultati descritti nei paragrafi seguenti.

Ereditarietà dello stile per un paragrafo normale

Il primo paragrafo della forma secondaria, che include il testo "Questo è il mio primo paragrafo", è un paragrafo normale (non in un elenco). Nessun elemento nei contenuti di testo specifica proprietà di stile, quindi eredita tutti gli stili di caratteri e paragrafi dall'elemento principale. Ciò comporta il seguente rendering:

  • Testo: "Questo è il mio primo paragrafo" è il testo visualizzato. Il testo stesso non viene mai ereditato.
  • Allineamento: il testo viene visualizzato con allineamento START, ereditato dal primo ParagraphMarker del parente.
  • Colore di primo piano: il testo viene visualizzato con il colore di primo piano DARK1, ereditato dal primo TextRun del contenitore principale.

Ereditarietà dello stile per un paragrafo dell'elenco

Il paragrafo successivo, che include il testo "Questo paragrafo è in un elenco", è in un elenco puntato a livello di nidificazione 1, poiché il relativo ParagraphMarker corrispondente ha il campo bullet impostato su questo livello. 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 stesso non viene mai ereditato.
  • Allineamento: il testo viene visualizzato con l'allineamento"FINE", ereditato dal secondo ParagraphMarker del parente.
  • Colore di primo piano: il testo viene visualizzato con il colore di primo piano del testo LIGHT1, ereditato dal secondo TextRun del contenitore principale.

Interazioni tra aggiornamento e ereditarietà di stili di testo e paragrafi

Gli stili di testo non impostati in una forma secondaria erediteranno i valori dalla forma principale. Gli stili di testo impostati nell'elemento secondario "sostituiranno" i valori principali in alcuni ambiti locali.

Puoi utilizzare un 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 suoi stili dalla forma principale. Inoltre, l'aggiornamento dello stile di testo dell'elemento figlio in modo che corrisponda al valore ereditato da un elemento principale rimuove implicitamente lo stile in modo che venga utilizzato il valore ereditato.

Ciò non influisce sull'aspetto visivo del testo subito dopo un aggiornamento, ma potrebbe essere importante se in un secondo momento aggiorni un paragrafo o uno stile di testo in un segnaposto principale. Questo comportamento di eredità corrisponde a quello dell'editor di Presentazioni, quindi puoi sperimentare i risultati delle modifiche dello stile prima di utilizzare l'API.

Esempio

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

Supponiamo ora di inviare questo UpdateTextStyleRequest:

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

Questa richiesta tenta di impostare un DARK1 foregroundColor per tutto il testo di TextPlaceHolder, 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 a quello ereditato foregroundColor, quindi questo stile rimane invariato e viene comunque ereditato.
  • Secondo paragrafo: il nuovo foregroundColor non corrisponde al valore ereditato foregroundColor, pertanto il colore di primo piano del secondo paragrafo viene aggiornato a DARK1.

Il contenuto di testo di Segnaposto figlio 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 di testo del glifo del punto elenco

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

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

  1. Un elenco puntato a un determinato livello di nidificazione eredita innanzitutto dall'impostazione TextStyle nel campo NestingLevel.bullet_style all'interno dell'oggetto List dell'elenco puntato.
  2. Poi eredita il valore dall'elemento NestingLevel.bullet_style corrispondente nell'elemento List del segnaposto principale.
  3. Infine, cerca di ereditare dagli oggetti segnaposto principali rimanenti.