Estrutura e estilo do texto

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.

No futuro, a API Slides poderá incluir mais tipos de elementos de texto. O código que processa texto precisa processar novos tipos de elementos de texto com facilidade, geralmente ignorando tipos desconhecidos.

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 elemento AutoText.

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 primeiro ParagraphMarker do pai.
• Cor de primeiro plano: o texto é renderizado com a cor de primeiro plano DARK1, herdada do primeiro TextRun 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 segunda TextRun 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.

Definir o estilo de uma forma secundária para corresponder exatamente ao da forma mãe (fazendo com que ela herde o estilo) tem um resultado idêntico a desfazer a configuração do estilo da forma secundária.

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 ao foregroundColor herdado. Portanto, esse estilo não é alterado e ainda é herdado.
• Segundo parágrafo: o novo foregroundColor não corresponde ao foregroundColor herdado. Portanto, a cor do primeiro plano do segundo parágrafo é atualizada para DARK1.

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.

1. Um marcador em um determinado nível de aninhamento primeiro é herdado do TextStyle definido no campo NestingLevel.bullet_style, dentro do objeto List do marcador.
2. Em seguida, ele herda do NestingLevel.bullet_style correspondente no List do marcador pai.
3. Por fim, ela busca herdar dos demais objetos de marcador de posição pais.

Os marcadores em marcadores de posição em layouts e mestres têm um TextStyle vazio no campo "ParagraphMarker.bullet" e todas as atualizações de estilo de texto nesses parágrafos só serão refletidas nas mensagens "List".