Na Slides API, o texto pode estar em formas ou em células de tabela. Antes de manipular e estilizar um texto, você precisa entender a estrutura e como o estilo funciona.
Esta página descreve como o texto é representado na API Slides.
Sequências de elementos de texto
O texto contido em uma forma ou célula de tabela é composto de uma sequência de estruturas TextElement. Essa sequência representa a estrutura do texto na ordem em que ele aparece do início ao fim.
Por exemplo, considere o conteúdo deste slide, tudo contido em uma caixa de texto:
O slide acima tem uma caixa de texto, cujo campo text
contém uma sequência
de elementos de texto, conforme mostrado no diagrama a seguir:
De forma mais concreta, essa sequência de texto é representada na API Slides desta forma:
"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": {} }
}]
Conteúdos de TextElement
Cada elemento de texto contém um índice inicial e um índice final baseado em zero, que descrevem a localização do elemento no texto completo do elemento de página, além de um destes tipos de objeto de texto:
Tipo do texto | Descrição |
---|---|
ParagraphMarker | Esse elemento de texto representa o início de um novo parágrafo. Os índices de início e fim do elemento de texto representam toda a extensão do parágrafo, incluindo o caractere de nova linha que o encerra. Um parágrafo nunca se sobrepõe a outro. Os parágrafos sempre terminam com um caractere de nova linha. Portanto, há sempre uma nova linha ao final do conteúdo de texto de uma forma ou célula de tabela. Eles podem pertencer a listas numeradas ou com marcadores. Nesse caso, o conteúdo do campo ParagraphMarker.bullet vai incluir um ID de lista. Esse ID faz referência a um elemento de lista que existe dentro de TextContent ao lado da sequência TextElement . Os parágrafos com a mesma lista lógica farão referência ao mesmo ID. |
TextRun | Esse elemento de texto representa uma string contígua de texto que tem o mesmo estilo. O texto nunca cruza os limites dos parágrafos: mesmo que o texto que termine em um parágrafo tenha o mesmo estilo que o do texto que inicia o próximo parágrafo, o conteúdo é dividido após o caractere de nova linha para formar execuções de texto separadas. Se você precisar processar toda a string de texto em um elemento de página, itere todos os elementos de texto, concatenando as strings encontradas em todas as execuções de texto. |
AutoText | O texto automático se refere a lugares no texto que mudam dinamicamente dependendo do contexto. No Apresentações, esse recurso é usado para representar o número do slide atual dentro do texto. |
Como modificar o conteúdo do texto
Quando você precisa modificar o texto usando a API Slides, não é necessário criar explicitamente
todos os elementos de texto adequados. Em vez disso, é possível operar no texto como
você faria no editor do Apresentações: inserindo texto, excluindo intervalos e atualizando estilos em intervalos. Essas operações criam elementos ParagraphMarker
e TextRun
implicitamente, conforme necessário, para refletir as alterações.
Como inserir texto
É possível inserir texto em um índice usando a solicitação
InsertTextRequest
em uma chamada para
batchUpdate. O
campo insertionIndex
desse método especifica onde inserir o texto. É possível
calcular esse índice usando os campos de início e fim do índice dentro dos elementos de texto.
A inserção de texto tem alguns efeitos colaterais que espelham o comportamento do editor do Apresentações:
- A inserção de um caractere de nova linha cria implicitamente um novo parágrafo,
criando um elemento de texto
ParagraphMarker
que começa no índice da nova linha e termina na nova linha seguinte. O estilo do parágrafo, incluindo os detalhes dos marcadores e da lista, é copiado do parágrafo atual para o novo. - O estilo dos caracteres inseridos é determinado automaticamente, geralmente mantendo o mesmo estilo de texto que existia no índice de inserção. Como resultado,
o texto geralmente é inserido no
TextRun
atual nesse índice. É possível atualizar esse estilo mais tarde usando uma solicitação UpdateTextStyle.
Excluindo texto
É possível excluir um intervalo de texto usando a mensagem DeleteTextRequest em uma chamada para batchUpdate. A exclusão de texto envolve algumas sutilezas:
- Uma exclusão que cruza um limite de parágrafo mescla os dois parágrafos,
excluindo o elemento de texto
ParagraphMarker
de separação. - O novo parágrafo mesclado usará um estilo de parágrafo combinado com o mesmo comportamento no editor das Apresentações.
- Uma exclusão com um intervalo que englobe uma execução de texto remove todo o conteúdo de uma execução de texto, além da própria execução de texto.
- Uma exclusão com um intervalo que englobe um elemento
AutoText
exclui o elementoAutoText
.
Como atualizar o estilo do texto
A aparência renderizada do texto em um slide é determinada pelas propriedades de estilo do texto:
- Estilos de parágrafo, como recuo, alinhamento e glifos de marcadores, são definidos por propriedades nos marcadores de parágrafo.
- Estilos de caracteres, como negrito, itálico e sublinhado, são definidos por propriedades em execuções de texto individuais.
Atualizando estilo dos caracteres
É possível atualizar estilos de caracteres usando a mensagem UpdateTextStyleRequest em uma chamada para batchUpdate.
Assim como outras operações de texto, o estilo de caracteres é aplicado a um intervalo
de texto e cria implicitamente novos objetos TextRun
conforme necessário.
Definir alguns estilos de caracteres atualiza implicitamente outros estilos relacionados para corresponder ao comportamento no editor das Apresentações. Por exemplo, adicionar um link muda automaticamente as propriedades de cor e sublinhado do texto em primeiro plano. Consulte a documentação de referência TextStyle para mais detalhes.
Atualizando estilo do parágrafo
É possível atualizar estilos de parágrafo usando a mensagem UpdateParagraphStyleRequest em uma chamada para batchUpdate.
A API Slides é compatível com um CreateParagraphBulletsRequest, que espelha a funcionalidade das predefinições de marcadores no editor das Apresentações para criar listas numeradas e com marcadores. Da mesma forma, DeleteParagraphBulletsRequest remove todos os marcadores existentes nos parágrafos.
Estilos herdados
Algumas formas, conhecidas como placeholders, podem herdar estilos de texto de outras formas mães. Consulte placeholders para saber mais sobre a herança de formas em geral.
Esta seção se concentra em como a herança de estilo funciona para criar os estilos de texto renderizados finais exibidos em um slide.
Representação de estilo em marcadores de posição
Na seção sobre placeholders, descrevemos como a herança funciona entre as formas mãe e filha. A herança de estilos de texto é tratada por recursos extras dentro do modelo de herança:
- As propriedades dos elementos de texto ParagraphMaker definem a formatação de parágrafos.
- As propriedades dos elementos de texto TextRun definem a formatação de caracteres.
- O conteúdo dos marcadores pais contém oito pares de ParagraphMarker/TextRun para oferecer suporte a oito níveis de aninhamento de lista.
- Um marcador filho herda as propriedades de texto padrão desses elementos de texto no conteúdo de texto do pai.
O diagrama a seguir mostra uma maneira de visualizar essas relações:
O primeiro ParagraphMarker/TextRun na forma mãe determina a maior parte do estilo de texto herdado. O estilo nos sete pares restantes só afeta parágrafos em níveis de marcadores aninhados progressivamente mais profundos:
Par de elementos de texto pai | Formatação filha controlada por ele |
---|---|
Primeiro ParagraphMarker primeiro TextRun |
Estilo de texto de parágrafos de lista de nível 0 (mais externo) e todos os que não são de lista. |
Segundo ParagraphMarker Segundo TextRun |
Estilo de texto dos níveis de lista restantes (aninhados) de 1 a 7 |
Terceiro ParagraphMarker Terceiro TextRun |
|
Quarto ParagraphMarker Quarto TextRun |
|
Quinta ParagraphMarker Quinta TextRun |
|
Sexta ParagraphMarker Sexto TextRun |
|
Sétimo ParagraphMarker sétimo TextRun |
|
Oitava ParagraphMarker Oitava TextRun |
Para acessar esses pares de elementos de texto, use o índice explícito deles no campo
textElements
, conforme mostrado no snippet abaixo, que mostra a configuração do
estilo padrão (herdável) para parágrafos de nível 0 e não de lista:
"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" } }, }
}
},{
...
} ]
}
O campo content
do TextRun
de uma forma mãe sempre consiste em
um único caractere de nova linha.
Os estilos herdados podem ser substituídos
Uma forma filha pode especificar propriedades de estilo nos elementos ParagraphMarker e TextRun no conteúdo. Essas propriedades especificadas localmente vão modificar as herdadas no escopo local. Elementos que não especificarem nenhum estilo usarão o estilo correspondente herdado do pai.
Remover uma propriedade de estilo explícita de uma forma secundária para que ela não fique mais definida fará com que ela seja herdada da forma mãe.
Exemplo
Considerando a herança mostrada no diagrama acima, suponha que a forma
ParentPlaceholder
tenha o seguinte conteúdo de texto:
"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"} }, ...}
}
},
...
]
}
E suponha que a forma ChildPlaceholder
tenha o seguinte conteúdo de texto:
"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": {},
...
}
}
]
}
Isso resulta nos resultados descritos nos parágrafos a seguir.
Herança de estilo em um parágrafo simples
O primeiro parágrafo da forma filha, que inclui o texto "Este é o meu primeiro parágrafo", é um parágrafo simples (não de uma lista). Nenhum elemento no conteúdo de texto especifica propriedades de estilo. Por isso, ele herda todos os estilos de caractere e parágrafo do pai. Isso causa a seguinte renderização:
- Texto: "Este é meu primeiro parágrafo" é o texto renderizado. O texto em si nunca é herdado.
- Alinhamento: o texto é renderizado com alinhamento
START
, herdado do primeiroParagraphMarker
do pai. - Cor de primeiro plano: o texto é renderizado com a cor de primeiro plano
DARK1
, herdada do primeiroTextRun
do elemento pai.
Herança de estilo em um parágrafo de lista
O próximo parágrafo, que inclui o texto "Este parágrafo está em uma lista", está em
uma lista com marcadores no nível de aninhamento 1, já que o ParagraphMarker
correspondente tem o campo bullet
definido nesse nível. Como resultado, ele herda o estilo de texto e
parágrafo do nível 1 de aninhamento no pai. Isso resulta na seguinte renderização:
- Texto: "Este parágrafo está em uma lista" é o texto renderizado. O texto em si nunca é herdado.
- Alinhamento: o texto é renderizado com o alinhamento "END", herdado da
segunda
ParagraphMarker
do pai. - Cor de primeiro plano: o texto é renderizado com a cor de primeiro plano
LIGHT1
, herdada da segundaTextRun
do elemento pai.
Interações entre atualização e herança de estilos de texto e parágrafo
Os estilos de texto que não forem definidos em uma forma filha herdarão valores do pai. Os estilos de texto definidos no filho vão "substituir" os valores pai em algum escopo local.
Você pode usar uma UpdateTextStyleRequest para desativar o estilo de texto de uma forma filha para que ela não tenha mais uma substituição local e herde os estilos da forma mãe. Além disso, atualizar o estilo de texto do filho para corresponder ao valor herdado de um pai desativa implicitamente o estilo para que ele use o valor herdado.
Isso não afeta a aparência do texto imediatamente após uma atualização, mas pode ser importante se você atualizar mais tarde um estilo de parágrafo ou texto em um marcador pai. Esse comportamento de herança corresponde ao do editor das Apresentações para que você possa testar os resultados das mudanças de estilo antes de trabalhar com a API.
Exemplo
Considere as definições no exemplo anterior para ChildPlaceholder
e ParentPlaceholder
.
Agora, suponha que você envie esta UpdateTextStyleRequest:
{ "updateTextStyle": {
"objectId": "ChildPlaceholder",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
"textRange": { "type": "ALL" },
"fields": "foregroundColor"
}
}
Essa solicitação tenta definir uma DARK1
firstColor para todo o
texto de ChildPlaceholder usando uma máscara de campo
para especificar que somente a cor do primeiro plano do elemento precisa mudar. Essa solicitação gera os seguintes resultados:
- Primeiro parágrafo: o novo
foregroundColor
corresponde aoforegroundColor
herdado. Portanto, esse estilo não é alterado e ainda é herdado. - Segundo parágrafo: o novo
foregroundColor
não corresponde aoforegroundColor
herdado. Portanto, a cor do primeiro plano do segundo parágrafo é atualizada paraDARK1
.
O conteúdo de texto de ChildPlaceholder agora é:
"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"} }, },
...
}
}
]
}
Estilo de texto do glifo de marcador
Assim como um texto normal, os glifos de marcador têm um estilo de texto que controla como eles são renderizados. Esses estilos de texto não podem ser modificados usando a API Slides diretamente. No entanto, se você usar uma UpdateTextStyleRequest para atualizar um parágrafo completo com um marcador, a API Slides vai atualizar o estilo de texto do glifo de marcador para corresponder.
Os estilos de texto de glifo de marcador seguem uma hierarquia de herança ligeiramente diferente dos estilos de texto normal.
- Um marcador em um determinado nível de aninhamento primeiro é herdado do
TextStyle
definido no campoNestingLevel.bullet_style
, dentro do objetoList
do marcador. - Em seguida, ele herda do
NestingLevel.bullet_style
correspondente noList
do marcador pai. - Por fim, ela busca herdar dos demais objetos de marcador de posição pais.