Para usar la API de Presentaciones de manera efectiva, debes comprender la arquitectura de las presentaciones y sus componentes, así como las interacciones entre estos componentes. En esta página, se proporciona una descripción general detallada de los siguientes temas:
- Modelo conceptual de los componentes de la presentación
- Cómo representa la API estos componentes
- Propiedades de diseño de los componentes
Leer esta y las otras descripciones generales de conceptos facilitará la comprensión y el uso de las guías prácticas, la documentación de referencia y las muestras de recetas.
Presentaciones, páginas y elementos de página
Las presentaciones son el elemento contenedor más externo de Presentaciones de Google. Esta es la unidad que se puede guardar en Google Drive y compartir con otros usuarios, entre otras opciones.
Cada presentación contiene varios tipos de páginas. Un tipo de página es una diapositiva, que son las páginas que los usuarios ven y entre las que alternan cuando la presentación se renderiza en una pantalla.
Cada página contiene varios elementos de página que, en conjunto, conforman el contenido de la página, como se muestra en el siguiente diagrama:
Además de las diapositivas, hay otros tipos de páginas que te permiten aplicar diseño a muchas diapositivas diferentes para lograr un aspecto coherente. Estos otros tipos de páginas son principales y diseños, y sus propiedades determinan la forma en que se renderizan las diapositivas, como se muestra en el siguiente diagrama:
Patrones: La página principal cumple dos funciones. Los marcadores de posición del diseño maestro contienen los valores predeterminados de los estilos de texto que se usan en tu presentación. El fondo y cualquier otra forma de la diapositiva principal constituyen el fondo predeterminado de todas las diapositivas que se basan en esa diapositiva principal. Si tienes el logotipo de una empresa que quieras que aparezca en todas las diapositivas de tu presentación, colócalo en la diapositiva principal.
Diseños: Las plantillas de diseño determinan cómo se organiza el contenido en cada tipo de diapositiva. Si deseas que todas tus diapositivas de título se vean de una manera determinada, por ejemplo, puedes editar la plantilla de diseño del título.
Existen dos tipos más de páginas, las páginas de notas y los patrones de notas, que son en su mayoría relevantes para trabajar con notas del orador.
Tipos de representación y estructura de la API
En esta sección, se describe cómo el modelo conceptual de Presentaciones de Google, como se describió antes, se representa en la API de Presentaciones.
En el siguiente diagrama, se muestra la relación entre presentaciones, páginas y elementos de página como tipos en la API de Presentaciones:
En las siguientes secciones, se muestra cómo se representan estos tipos en JSON.
Presentaciones
Una presentación incluye varias propiedades y contiene las páginas que se encuentran en ella:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Páginas
Una página incluye un conjunto de propiedades y contiene los elementos de página que se encuentran en ella:
{
"objectId": string,
"pageType": enum(PageType),
"pageElements": [ { object(PageElement) } ],
"pageProperties": { object(PageProperties) },
// Union field properties can be only one of the following:
"slideProperties": { object(SlideProperties) },
"layoutProperties": { object(LayoutProperties) },
"notesProperties": { object(NotesProperties) },
// End of list of possible types for union field properties.
}
Elementos de página
Los elementos de página son los componentes visuales que se disponen en las páginas. Un elemento de página de la API contiene varias propiedades, incluido un campo que varía según el tipo de elemento de página:
{
"objectId": string,
"size": { object(Size) },
"transform": { object(AffineTransform) },
"title": string,
"description": string,
// Union field element_kind can be only one of the following:
"elementGroup": { object(Group) },
"shape": { object(Shape) },
"image": { object(Image) },
"video": { object(Video) },
"line": { object(Line) },
"table": { object(Table) },
"wordArt": { object(WordArt) },
"sheetsChart": { object(SheetsChart) },
// End of list of possible types for union field element_kind.
}
Existen varios tipos de elementos de página, según lo define el campo de unión element_kind en la definición anterior. Estos tipos de elementos de página se describen en la siguiente tabla:
| Tipo de elemento | Descripción |
|---|---|
| Grupo | Es un conjunto de elementos de página que reciben tratamiento como una unidad individual. Pueden moverse, recibir ajustes de tamaño y girarse en conjunto. |
| Forma | Es un objeto visual simple, como rectángulos, elipses y cuadros de texto. Las formas pueden contener texto. Por lo tanto, son los elementos de página más comunes a la hora de crear diapositivas. |
| Imagen | Es un gráfico importado a Presentaciones. |
| Video | Un video importado a Presentaciones |
| Line | Una línea, curva o conector visual. |
| Tabla | Cuadrícula de contenido. |
| WordArt | Elemento de texto visual que se comporta más como una forma. |
| SheetsChart | Gráfico importado a Presentaciones desde Hojas de cálculo de Google. |
Propiedades de página y elemento de página
La API de Presentaciones te permite leer y actualizar el aspecto de las páginas y los elementos de las páginas de tu presentación. Los distintos elementos de página admiten diferentes propiedades que controlan la forma en que se representan los elementos de página.
Cada categoría de elemento de página tiene un elemento de propiedades correspondiente y un mensaje de actualización de propiedades, por ejemplo:
- Hay un tipo de elemento de página Forma
- Su campo de propiedad es shapeProperties
- La solicitud para actualizar estas propiedades es UpdateShapePropertiesRequest.
El mismo conjunto de solicitudes de elemento, propiedades y actualización existe para cada tipo de elemento de página: Image/imageProperties/UpdateImageProperties, etcétera.
Puedes leer el atributo de propiedades siempre que lo encuentres durante la lectura de un elemento; para cambiar sus valores, úsalo con el tipo de solicitud coincidente como carga útil para el método batchUpdate, lo que te permitirá cambiar estos valores en la presentación.
Tipos de propiedades
Existen algunas propiedades que son comunes entre varios tipos de objetos de la API de Presentaciones:
| Propiedad | Descripción |
|---|---|
| Color | Los colores en la API de Presentaciones pueden ser un valor RGB o una referencia a un color de tema. La referencia a los colores del tema se hacen por nombre (por ejemplo, "DARK1") y se pueden asignar a valores RGB a través del esquema de colores de una página. Este esquema de colores comúnmente se actualiza cuando se cambia el tema de la presentación en el editor de Presentaciones. |
| Fill | El relleno representa la renderización del espacio vacío dentro de un objeto. El relleno más común en Presentaciones es un relleno sólido, en el que el interior de un objeto se rellena con un único color sólido. Los rellenos también se pueden usar para los fondos de las Páginas. |
| Contorno | El contorno representa el conjunto de líneas que rodean el elemento de página. El color de las líneas se controla con un elemento Fill. Los emisores también pueden ajustar el ancho y el estilo de guion de los contornos. |
| Shadow | La sombra representa un efecto visual destinado a imitar una sombra física proyectada por el objeto. Actualmente, las sombras en la API de Presentaciones son de solo lectura. |
Actualiza propiedades
Para actualizar una propiedad, usa la solicitud Update...Properties correspondiente en una llamada al método batchUpdate (por ejemplo, UpdateShapeProperties para formas). Estas solicitudes aceptan un mensaje de propiedades completo y pueden usar máscaras de campo para determinar qué campos del mensaje de propiedades se deben actualizar.
Herencia de la propiedad
Una página o un elemento de página puede heredar propiedades de sus objetos principales. Las propiedades de un objeto, incluidas las que define y hereda, determinan su apariencia visual final.
- Propiedades de la página: Una página hereda las propiedades que no define, pero que se definen en el diseño o el diseño maestro en los que se basa.
- Propiedades de forma: Una forma se puede marcar como un marcador de posición, lo que te permite hacer una referencia explícita a otra forma de marcador de posición (en el diseño principal o principal de la página) de la que se heredarán propiedades.
Estas ideas se explican con más detalle en los párrafos siguientes.
Herencia de propiedades de página
La estructura de las diapositivas, los diseños y los diseños maestros definen una jerarquía de herencia dentro de la presentación: las diapositivas heredan los diseños y los diseños heredan los diseños. El diseño principal y el diseño principal de una diapositiva se especifican en el campo slideProperties.
Una página puede heredar propiedades, como el fondo y el esquema de colores, de una página superior. Para heredar una propiedad, la página secundaria simplemente no establece un valor para esa propiedad en su mensaje PageProperties. Si no se "anula" el valor definido por el elemento superior, la página acepta el valor heredado.
En el siguiente diagrama, se muestra una diapositiva que hereda propiedades de un diseño, el cual hereda de un diseño maestro:
Las propiedades que se usan para renderizar una diapositiva son una combinación de las que esta define y hereda. En este ejemplo, los valores resueltos que se usan para renderizar la diapositiva 1 son los siguientes:
- La propiedad A es “Rojo”.
- La propiedad B es “Naranja”.
Herencia de propiedades de formas
Las formas pueden heredar propiedades, como el relleno, el contorno o la sombra, de otras formas. Una forma es un marcador de posición si se configura su campo Shape.placeholder. El campo Shape.placeholder.parentObjectId del marcador de posición secundario identifica su marcador de posición superior. Cuando creas una diapositiva nueva basada en un diseño, los marcadores de posición de ese diseño aparecen como formas secundarias en la diapositiva nueva.
Del mismo modo, los marcadores de posición de las páginas principales pueden funcionar como marcadores de posición superiores de los diseños.
Con esta jerarquía de herencia definida, la página secundaria hereda una propiedad, ya que no establece ese valor en su mensaje ShapeProperties. Si no se anula el valor definido por el elemento superior, la forma secundaria acepta el valor heredado.
En el siguiente diagrama, se muestra la herencia de propiedades entre tres marcadores de posición contenidos en una diapositiva, un diseño y un diseño maestro:
Las propiedades que se usan para renderizar una forma de marcador de posición son una combinación de las que esta define y las hereda. En este ejemplo, los valores resueltos para estas formas son los siguientes:
- Marcador de posición 1: la propiedad A se representa como “Amarillo” y la B como “Verde”.
- Marcador de posición 2: la propiedad A se representa como “Amarillo” y la B como “Púrpura”.
- Marcador de posición 3: la propiedad A se representa como “Amarillo” y la B como “Púrpura”.
Las formas son el único tipo de elemento de página que puede tener elementos superiores. Otros tipos, como las imágenes, las tablas y los gráficos, no pueden ser marcadores de posición ni tener elementos superiores.
Cómo ocultar propiedades con PropertyState
La enumeración de PropertyState controla si la propiedad de una forma se usa realmente para la renderización o si solo se usa el valor para la herencia de formas secundarias. No se usará una propiedad con el estado de propiedad NOT_RENDERED cuando se renderice la forma en su página. Sin embargo, los elementos secundarios que tengan el estado de propiedad correspondiente RENDERED aún pueden heredar esta propiedad.
En el siguiente diagrama, se muestra la herencia de propiedades entre tres marcadores de posición que manipulan el campo PropertyState:
La renderización de propiedades de formas puede verse afectada por el campo PropertyState. En este ejemplo, los valores resueltos para estas formas son los siguientes:
- Marcador de posición 1: La propiedad A se representa como “Rojo”.
- Marcador de posición 2: la propiedad A no se renderiza. Si esta fuera la propiedad de contorno, el marcador de posición 2 no tendría contorno.
- Marcador de posición 3: la propiedad A no se renderiza.
Existe otro valor posible para la enumeración PropertyState: el estado de propiedad INHERIT significa que el estado de la propiedad en sí es heredado, y se debe usar el valor del elemento superior. El estado de propiedad de las formas sin elementos superiores no puede ser INHERIT.