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. |
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'elementoAutoText
.
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 primoParagraphMarker
del padre. - Colore di primo piano: il testo viene visualizzato con il colore di primo piano
DARK1
, ereditato dal primoTextRun
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 secondoTextRun
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.
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'elementoforegroundColor
ereditato, pertanto questo stile è invariato e eredita. - Secondo paragrafo: il nuovo
foregroundColor
non corrisponde al valoreforegroundColor
ereditato, quindi il colore in primo piano del secondo paragrafo viene aggiornato inDARK1
.
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.
- Un punto elenco a un determinato livello di nidificazione eredita prima dal set
TextStyle
nel campoNestingLevel.bullet_style
all'interno dell'oggettoList
del punto elenco. - Poi eredita dal valore
NestingLevel.bullet_style
corrispondente nel valoreList
del segnaposto principale. - Infine cerca di ereditare dagli oggetti segnaposto padre rimanenti.