Estructura y ajustes de estilo de texto

En la Slides API, el texto puede estar contenido en formas o celdas de tablas. Para poder manipularlo y aplicarle ajustes de estilo, debes comprender su estructura y la manera en que funcionan los estilos.

En esta página se describe cómo se representa el texto en la Slides API.

Secuencias de elementos de texto

El texto contenido en una forma o celda de tabla consta de una secuencia de estructuras TextElement. Esta secuencia representa la estructura del texto, en el orden en que aparece de principio a fin.

Por ejemplo, considera el contenido de esta diapositiva; todo en un cuadro de texto:

captura de pantalla de una diapositiva simple

La diapositiva anterior contiene un cuadro de texto, cuyo campo text contiene una secuencia de elementos de texto como los que se muestran en el siguiente diagrama:

diagrama que muestre una secuencia de elementos de texto

De manera más concreta, esta secuencia de texto se representa en la Slides API de la siguiente manera:

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

Contenido de TextElement

Cada elemento de texto contiene un índice de inicio y un índice de finalización basados en cero, que describen la ubicación del elemento dentro del texto completo del elemento de la página, junto con uno de los siguientes tipos de objetos de texto:

Clase de texto Descripción
ParagraphMarker Este elemento de texto representa el inicio de un nuevo párrafo. El índice de inicio y finalización del elemento de texto representa la extensión completa del párrafo, incluido el carácter de nueva línea que marca el final de este. Un párrafo nunca se superpone con otro. Los párrafos siempre finalizan con un carácter de nueva línea. Por lo tanto, siempre hay una nueva línea al final del contenido de texto de una forma o celda de tabla.

Los párrafos pueden pertenecer a listas con viñetas o números. En este caso, el contenido del campo ParagraphMarker.bullet incluye un ID de lista. Este ID hace referencia a un elemento de lista que existe dentro de TextContent junto con la secuencia de TextElement. Los párrafos dentro de la misma lista lógica harán referencia al mismo ID de lista.
TextRun Este elemento de texto representa una string contigua de texto que contiene en su totalidad el mismo estilo. Los cuerpos de texto nunca exceden los límites del párrafo. Aun cuando el texto con el que finalice un párrafo tenga el mismo estilo que el texto con el que comience el siguiente, el contenido se dividirá luego del carácter de nueva línea para formar cuerpos de texto separados.

Si debes procesar la string de texto completa de un elemento de página, aplica iteraciones en todos los elementos de texto y concatena las strings que encuentres en todos los cuerpos de texto.
AutoText El autotexto hace referencia a secciones del texto que cambian de manera dinámica según el contexto. En Slides, se usa para representar el número de diapositiva actual dentro del texto.

Modificación del contenido de texto

Cuando debas modificar texto usando la Slides API, no será necesario que crees de manera explícita todos los elementos de texto correspondientes. Como alternativa, puedes aplicar al texto las mismas operaciones que usarías en el editor de Slides: inserción de texto, eliminación de rangos y actualización de estilos de rangos. Con estas operaciones se crean de manera implícita elementos ParagraphMarker y TextRun según sea necesario para reflejar tus cambios.

Inserción de texto

Puedes insertar texto en un índice usando la solicitud InsertTextRequest en una llamada a batchUpdate. El campo insertionIndex de este método especifica el punto en el que se insertará el texto. Puedes computar este índice usando los campos de índices de inicio y finalización dentro de los elementos de texto.

La inserción de texto tiene algunos efectos colaterales que reflejan el comportamiento del editor de Slides:

  • Con la inserción de un carácter de nueva línea se crea de manera implícita un nuevo párrafo y, con ello, un elemento de texto ParagraphMarker que se inicia en el índice de la nueva línea y finaliza en la nueva línea siguiente. El estilo de párrafo (incluidos los detalles sobre viñetas y listas) se copia del párrafo actual al nuevo.
  • El estilo de los caracteres insertados se determina de manera automática; generalmente, se mantiene el mismo estilo de texto del índice de inserción. Como resultado, el texto en general se inserta en el TextRun de dicho índice. Puedes actualizar este estilo posteriormente usando una solicitud UpdateTextStyle.

Eliminación de texto

Puedes borrar un rango de texto usando el mensaje de DeleteTextRequest en una llamada a batchUpdate. Existen algunos detalles relacionados con la eliminación de texto:

  • Cuando en una eliminación se excede el límite de un párrafo, se fusionan este y el que le sigue, y se elimina el elemento de texto ParagraphMarker.
  • En el nuevo párrafo fusionado se usa un estilo de párrafo combinado, y se equipara el comportamiento del editor de Slides.
  • Con una eliminación cuyo rango abarca un cuerpo de texto se quita todo el contenido de este. También se quita el propio cuerpo.
  • Con una eliminación cuyo rango abarca un elemento AutoText se borra el elemento AutoText.

Actualización del estilo de texto

El aspecto representado del texto en una diapositiva se determina a través de propiedades de estilo de texto:

  • Los estilos de párrafo como la sangría, la alineación y los glifos de viñetas se definen a través de propiedades de marcadores de párrafos.
  • Los estilos de caracteres como la negrita, la cursiva y el subrayado se definen a través de propiedades de cuerpos de texto individuales.

Actualización del estilo de párrafo

Puedes actualizar estilos de párrafo usando el mensaje de UpdateTextStyleRequest en una llamada a batchUpdate.

Al igual que otras operaciones de texto, el estilo de párrafo se aplica a un rango de texto que crea de manera implícita nuevos objetos TextRun según se necesiten.

La configuración de determinados estilos de párrafos actualiza de manera implícita otros estilos relacionados para equiparar el comportamiento del editor de Slides. Por ejemplo, agregar un vínculo cambia de manera automática el color de fondo y las propiedades de subrayado del texto. Para obtener más información, consulta la documentación de referencia de TextStyle.

Actualización del estilo de párrafo

La Slides API admite una CreateParagraphBulletsRequest que refleje la funcionalidad de los valores preestablecidos de viñetas del editor de Slides, para la creación de listas con viñetas y números.

Estilos heredados

Algunas formas, conocidas como marcadores de posición, pueden heredar estilos de otras formas primarias: consulta la sección de marcadores de posición para obtener más información sobre la herencia de formas en general.

Esta sección se centra en el funcionamiento de la herencia de estilos para la creación de los estilos definitivos de texto representado que se muestran en una diapositiva.

Representación de estilos en marcadores de posición

En la sección sobre marcadores de posición se describe el funcionamiento de la herencia entre formas primarias y secundarias. La herencia de estilos de texto se maneja a través de funciones adicionales del modelo de herencia:

  • Las propiedades de los elementos de texto de ParagraphMaker definen el formato de párrafos.
  • Las propiedades de los elementos de texto de TextRun definen el formato de caracteres.
  • El contenido de los marcadores de posición primarios consta de ocho pares ParagraphMarker/TextRun (para admitir ocho niveles de anidamiento de listas).
  • Un marcador de posición secundario hereda sus propiedades de texto predeterminadas de estos elementos de texto del contenido de texto de su marcador de posición primario.

En el siguiente diagrama se muestra una manera de visualizar estas relaciones:

diagrama de una forma secundaria que hereda propiedades de texto

El primer par ParagraphMarker/TextRun de la forma primaria determina la mayor parte de los ajustes de estilo de texto heredados; los ajustes de estilo de los siete pares restantes solo afectan párrafos a niveles de viñetas anidados a profundidades cada vez mayores:

Par de elementos de texto primarios Formato secundario que controla
Primer ParagraphMarker
Primer TextRun
Estilo de texto de los párrafos de lista de nivel 0 (más periféricos) y de todos los párrafos excluidos de lista.
Segundo ParagraphMarker
Segundo TextRun
Estilo de texto de los niveles de lista 1 a 7 restantes (anidados).
Tercer ParagraphMarker
Tercer TextRun
Cuarto ParagraphMarker
Cuarto TextRun
Quinto ParagraphMarker
Quinto TextRun
Sexto ParagraphMarker
Sexto TextRun
Séptimo ParagraphMarker
Séptimo TextRun
Octavo ParagraphMarker
Octavo TextRun

Para acceder a estos pares de elementos de texto, usa el índice explícito de estos dentro del campo textElements como se muestra en el fragmento de código a continuación, en el cual se muestra la configuración del estilo predeterminado (heredable) para los párrafos de nivel 0 y excluidos 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"  }  },  }
     }
   },{
     ...
   } ]
 }

Ten en cuenta que el campo content del elemento TextRun de una forma primaria siempre consta de un único carácter de nueva línea.

Los estilos heredados pueden anularse

Una forma secundaria puede especificar propiedades de ajuste de estilo en los elementos ParagraphMarker y TextRun de su contenido. Estas propiedades que se especifican a nivel local anularán cualquier propiedad heredada dentro de su ámbito local. Los elementos que no especifican ningún estilo usan el estilo correspondiente heredado del elemento primario.

La eliminación de una propiedad de estilo explícita de una forma secundaria, a fin de que deje de configurarse, hará que herede material del elemento primario.

Ejemplo

Considerando la herencia que se muestra en el diagrama anterior, supón que la forma ParentPlaceholder tiene el siguiente contenido 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"} }, ...}
      }
    },
   ...
  ]
}

Supón también que la forma ChildPlaceholder tiene el siguiente contenido 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": {},
        ...
      }
    }
  ]
}

Esto proporciona los resultados descritos en los párrafos que siguen.

Herencia de estilo de un párrafo sin formato

El primer párrafo de la forma secundaria, que incluye el texto “This is my first paragraph” (este es mi primer párrafo), no tiene formato (no se encuentra en una lista). En ningún elemento de su contenido de texto se especifican propiedades de estilo. Por ello, hereda todos sus estilos de caracteres y párrafo de su forma primaria. Esto da como resultado la siguiente representación:

  • Texto: El texto representado es "This is my first paragraph". El texto nunca se hereda.
  • Alineación: El texto se representa con la alineación START, heredada del primer elemento ParagraphMarker de la forma primaria.
  • Color de primer plano: El texto se representa con el color de primer plano DARK1, heredado del primer elemento TextRun de la forma primaria.

Herencia de estilo de un párrafo de lista

El párrafo siguiente, que incluye el texto “This paragraph is in a list” (este párrafo se incluye en una lista), se encuentra en una lista con viñetas en el nivel 1 de anidamiento porque el campo bullet de su ParagraphMarker correspondiente está fijado en este nivel. Como resultado, hereda estilo de texto y párrafo del nivel de anidamiento 1 de la forma primaria. Esto da como resultado la siguiente representación:

  • Texto: El texto representado es “This paragraph is in a list”. El texto nunca se hereda.
  • Alineación: El texto se representa con la alineación "END", heredada del segundo elemento ParagraphMarker de la forma primaria.
  • Color de primer plano: El texto se representa con el color de primer plano LIGHT1, heredado del segundo elemento TextRun de la forma primaria.

Interacciones entre la actualización y la herencia de estilos de texto y párrafo

Los estilos de texto que no se configuren en una forma secundaria heredarán valores de la forma primaria. Los estilos de texto que se configuren en la forma secundaria “anularán” los valores primarios en un ámbito local determinado.

Puedes usar una UpdateTextStyleRequest para eliminar la configuración de estilo de texto de una forma secundaria, de modo que esta deje de tener una anulación local y herede sus estilos de la forma primaria. A su vez, la actualización del estilo de texto de la forma secundaria para que coincida con el valor heredado de una forma primaria elimina de manera implícita la configuración del estilo, de modo que use el valor heredado.

Esto no afecta el aspecto del texto inmediatamente después de una actualización, pero puede ser importante si después actualizas un estilo de párrafo o texto de un marcador de posición primario. Este comportamiento de herencia coincide con el comportamiento del editor de Slides. Por lo tanto, puedes experimentar con los resultados de los cambios de estilo antes de trabajar con la API.

Ejemplo

Considera las definiciones del ejemplo anterior para ChildPlaceholder y ParentPlaceholder.

Ahora, supón que envías esta UpdateTextStyleRequest:

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

El propósito de esta solicitud es configurar un foregroundColor en DARK1 para todo el texto del elemento ChildPlaceholder usando una máscara de campo, a fin de especificar que solo deba cambiar el color de primer plano del elemento. Esta solicitud tiene los siguientes resultados:

  • Primer párrafo: El nuevo elemento foregroundColor coincide con el elemento foregroundColor heredado. Por lo tanto, este estilo no se modifica y de todos modos hereda material.
  • Segundo párrafo: El nuevo elemento foregroundColor no coincide con el elemento foregroundColor heredado. Por lo tanto, el color de primer plano del segundo párrafo se actualiza a DARK1.

El contenido de texto de ChildPlaceholder, entonces, será:

"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 de glifos de viñetas

Al igual que el texto normal, los glifos de viñetas tienen un estilo de texto que controla la forma en que se representan. Estos estilos de texto no pueden modificarse usando la Slides API de manera directa. Sin embargo, si usas una UpdateTextStyleRequest para actualizar un párrafo completo que incluya una viñeta, la Slides API actualiza el estilo de texto del glifo de la viñeta para que coincida.

Los estilos de texto de glifos de viñetas se rigen por una jerarquía de herencia que se diferencia ligeramente de los estilos de texto normales.

  1. Una viñeta de un nivel de anidamiento determinado hereda primero material del conjunto de TextStyle del campo NestingLevel.bullet_style dentro del objeto List de la viñeta.
  2. Luego, hereda material del elemento NestingLevel.bullet_style correspondiente del objeto List del marcador de posición primario.
  3. Por último, intenta heredar material de objetos marcadores de posición primarios.

Enviar comentarios sobre…