Страницы, элементы страниц и свойства

Чтобы эффективно использовать Slides API, необходимо понимать архитектуру презентаций и их компонентов, а также взаимодействие между этими компонентами. На этой странице подробно рассматриваются следующие темы:

• Концептуальная модель компонентов презентации
• Как API представляет эти компоненты
• Свойства стилей компонентов

Ознакомившись с этим и другими обзорами, вы сможете лучше понять и использовать практические руководства, справочную документацию и примеры кода.

Презентации, страницы и элементы страниц

Внешний контейнер в Google Презентациях – это презентация. Это единица, которую можно сохранить на Google Диске, поделиться ею с другими пользователями и т. д.

Каждая презентация содержит различные типы страниц. Один из типов страниц – это слайд. Слайды – это страницы, которые пользователи видят и перелистывают, когда презентация отображается на экране.

Каждая страница содержит несколько элементов, которые вместе составляют ее контент, как показано на следующей схеме:

Помимо слайдов, есть и другие типы страниц, которые позволяют применять дизайн к множеству разных слайдов, создавая единообразный внешний вид. Это макеты и шаблоны. Их свойства определяют, как будут выглядеть слайды.

Шаблоны. Шаблон страницы выполняет две функции. Плейсхолдеры на мастер-слайде содержат стили текста по умолчанию, которые используются во всей презентации. Фон и другие фигуры на мастер-слайде составляют фон по умолчанию для всех слайдов, основанных на этом мастер-слайде. Если у вас есть логотип компании, который вы хотите разместить на каждом слайде презентации, поместите его на мастер-слайд.

Макеты. Шаблоны макетов определяют, как контент располагается на слайдах каждого типа. Например, если вы хотите, чтобы все титульные слайды выглядели определенным образом, вы можете изменить шаблон макета титульного слайда.

Есть ещё два типа страниц – страницы заметок и образцы заметок. Они используются в основном для работы с заметками докладчика.

Типы и структура представлений API

В этом разделе описывается, как концептуальная модель Google Презентаций, описанная выше, представлена в Slides API.

На следующей диаграмме показана связь между презентациями, страницами и элементами страниц как типами в Slides API:

В следующих разделах показано, как эти типы представлены в JSON.

Презентации

Презентация включает ряд свойств и содержит страницы:

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

iWork Pages

Страница включает набор свойств и содержит элементы страницы:

{
  "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.
}

Элементы страницы

Элементы страницы – это визуальные компоненты, которые размещаются на страницах. Элемент страницы в API содержит ряд свойств, в том числе поле, которое зависит от типа элемента страницы:

{
  "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.
}

Существует несколько типов элементов страницы, которые определяются полем объединения element_kind в приведенном выше определении. Эти элементы страницы описаны в таблице ниже.

Свойства страниц и элементов страниц

Slides API позволяет считывать и обновлять внешний вид страниц и элементов страниц в презентации. Разные элементы страницы поддерживают разные свойства, которые управляют отображением элемента страницы.

Каждому типу элемента страницы соответствует элемент свойств и сообщение об обновлении свойств, например:

• Есть тип элемента страницы Shape.
• Его поле свойства – shapeProperties.
• Запрос на обновление этих свойств – UpdateShapePropertiesRequest.

Аналогичные наборы элементов, свойств и запросов на обновление существуют для каждого типа элементов страницы: Image/imageProperties/UpdateImageProperties и т. д.

Вы можете прочитать атрибут properties везде, где он встречается при чтении элемента. Чтобы изменить значения в нем, используйте его с соответствующим типом запроса в качестве полезной нагрузки для метода batchUpdate, что позволит вам изменить эти значения в презентации.

Типы ресурсов

Некоторые свойства являются общими для нескольких видов объектов в Slides API:

Обновление свойств

Чтобы обновить свойство, используйте соответствующий запрос Update...Properties в вызове batchUpdate, например UpdateShapeProperties для фигур. Эти запросы принимают полное сообщение о свойствах и могут использовать маски полей, чтобы определить, какие поля в сообщении о свойствах следует обновить.

Наследование разрешений ресурса

Страница или элемент страницы могут наследовать свойства родительских объектов. Свойства объекта, включая те, которые он определяет, и те, которые он наследует, определяют его окончательный внешний вид.

• Свойства страницы. Страница наследует все свойства, которые не определены в ней, но определены в макете или шаблоне, на котором она основана.
• Свойства фигур. Фигуру можно пометить как плейсхолдер, что позволяет явно ссылаться на другую фигуру-плейсхолдер (в родительском макете или шаблоне страницы), от которой наследуются свойства.

Ниже мы подробнее рассмотрим эти идеи.

Наследование свойств страниц

Структура слайдов, макетов и образцов определяет иерархию наследования в презентации: слайды наследуют от макетов, а макеты наследуют от образцов. Родительский макет и макет слайда указываются в поле slideProperties слайда.

Страница может наследовать свойства, такие как фон и цветовая схема, от родительской страницы. Чтобы унаследовать свойство, дочерняя страница просто не задает значение для этого свойства в своем сообщении PageProperties. Если не переопределить значение, заданное родительским элементом, страница примет унаследованное значение.

На следующей диаграмме показан слайд, наследующий свойства от макета, который наследует от мастера:

Свойства, используемые для рендеринга слайда, представляют собой комбинацию тех, которые он определяет, и те, которые он наследует. В этом примере для показа слайда 1 используются следующие значения:

• PropertyA – "Red".
• PropertyB – "Orange".

Наследование свойств фигур

Фигуры могут наследовать свойства, такие как заливка, контур или тень, от других фигур. Фигура является плейсхолдером, если задано ее поле Shape.placeholder. Поле Shape.placeholder.parentObjectId дочернего плейсхолдера указывает на родительский плейсхолдер. Когда вы создаете слайд на основе макета, все плейсхолдеры в этом макете появляются на новом слайде как дочерние фигуры. Аналогично, заполнители на мастер-страницах могут выступать в качестве родительских элементов для заполнителей макетов.

При такой иерархии наследования дочерняя страница наследует свойство, не задавая это значение в своем сообщении ShapeProperties. Если не переопределить значение, заданное родительским элементом, дочерний элемент примет унаследованное значение.

На следующей диаграмме показано наследование свойств между тремя заполнителями, которые содержатся в слайде, макете и мастере:

Свойства, используемые для отрисовки фигуры-заполнителя, представляют собой комбинацию тех, которые она определяет, и тех, которые она наследует. В этом примере разрешенные значения для этих фигур следующие:

• Placeholder1: propertyA is rendered as "Yellow", propertyB as "Green".
• Placeholder2: propertyA отображается как "Желтый", propertyB – как "Фиолетовый".
• Placeholder3: propertyA – "Желтый", propertyB – "Фиолетовый".

Фигуры – это единственный тип элементов страницы, у которых могут быть родительские элементы. Другие типы, такие как изображения, таблицы и диаграммы, не могут быть плейсхолдерами и не могут иметь родительские элементы.

Как скрыть свойства с помощью PropertyState

Перечисление PropertyState определяет, используется ли свойство фигуры для отрисовки или только для наследования дочерними фигурами. Свойство со статусом NOT_RENDERED не будет использоваться при отрисовке фигуры на странице, однако дочерние элементы с соответствующим статусом свойства RENDERED по-прежнему могут наследовать это свойство.

На следующей диаграмме показано наследование свойств между тремя плейсхолдерами, которые управляют полем PropertyState:

На отрисовку свойств фигур может влиять поле PropertyState. В этом примере значения для фигур будут следующими:

• Placeholder1: propertyA отображается как "Красный".
• Placeholder2: propertyA is not rendered. Если бы это было свойство outline, у Placeholder2 не было бы контура.
• Placeholder3: propertyA is not rendered.

Есть ещё одно возможное значение перечисления PropertyState: состояние свойства INHERIT означает, что состояние свойства наследуется и должно использоваться значение родительского элемента. Фигуры без родительских элементов не могут иметь свойство INHERIT.