Руководство пользователя Отмена

Создание пользовательских компонентов HTML5

 

В этой статье рассматривается создание пользовательских компонентов для HTML5 Canvas.

Animate уже включает набор компонентов по умолчанию. Однако для проекта их недостаточно. В этом разделе рассматривается создание пользовательских компонентов HTML5 для Animate.

Определение компонента состоит из трех основных частей.

  • Метаданные: информация о компоненте, такая как отображаемое имя, версия, набор настраиваемых свойств, значок и т. д. Они записываются в файл components.js. Компоненты можно группировать по категориям, и этот файл позволяет предоставлять метаданные для компонентов в категории.
  • Источник: информация об фактическом источнике компонентов. Она встраивается во время выполнения, когда вы просматривайте или публикуете фильм с использованием компонентов.
  • Ресурсы: информация о зависимости времени выполнения, такой как JavaScript или CSS, или ресурсы времени выполнения или значки. Ресурсы можно использовать в среде разработки Animate.

 Определение компонента также имеет ресурсы, связанные с локализацией.

Пример конфигурации папок для категории пользовательских компонентов

Animate проверяет следующие папки на наличие пользовательских компонентов HTML5 и загружает их при запуске.

• Windows:

<AppData>/Local/Adobe/Adobe Animate 2017/en_US/Configuration/HTML5Components

 

• MAC:

~/Library/Application Support/Adobe/Animate 2017/en_US/Configuration/HTML5Components/

 Приведенный выше путь к папке применим для английской версии (США). Если вы используете другой язык в Animate, найдите папку для этого языка, где вместо en_US стоит соответствующий код.

Для каждой папки в каталоге, который содержит файл components.js, Animate создает категорию и загружает все находящиеся в ней компоненты.

Метаданные компонента

Метаданные компонента записываются в файл с именем components.js, который находится в отдельной папке в каталоге HTML5Components.

Образец метаданных для видеокомпонента.

Components.js

Components.js

— это файл JSON, который содержит следующие разделы:

  • Категория: имя на панели «Компоненты» для этого набора компонентов, его можно локализовать.
  • Компоненты: массив, где каждая запись содержит метаданные о компоненте. Приведенный выше пример имеет только один элемент в массиве. Метаданные группируются по следующим разделам:

Имя

Обязательный

Описание

ClassName

Да

Имя класса компонента, указанное в исходном файле. Имя класса поддерживает один уровень пространств имен. Например, «Видео».

 

Версия

Нет

Номер версии компонента. Он используется для будущих обновлений компонентов. Однако на этом этапе поток еще не определяется.

Источник

Да

Относительный путь к основному исходному файлу компонента. Дополнительные данные о том, что содержится в источнике, см. в следующем разделе.

Значок

Нет

Относительный путь к значку для компонента. Этот значок используется на панели «Компоненты» и в рабочей области, когда создается экземпляр компонента вместе с именем. Если значок не задан, будет использоваться значок по умолчанию.

Можно указать имя png-файла значка, который требуется загрузить (обычно размером 32x32). А если требуется обеспечить поддержку разных значков для светлого ИП и темного ИП, то укажите два файла .png, придерживаясь следующей схемы именования:

custom_icon_N.png — значок для темного интерфейса пользователя

custom_icon_D.png — значок для светлого ИП

и укажите в этом поле имя custom_icon. Суффиксы автоматически добавляются на основе текущей пользовательской настройки.

Размеры

Нет

Размер по умолчанию для экземпляров компонента. При каждом перетаскивании компонента с панели «Компоненты» в рабочую область создается новый экземпляр. В этом поле указывается исходный размер по умолчанию для экземпляра компонента. Значение должно быть массивом [ширина, высота]. Если значение не указано, то Animate использует размер по умолчанию. Кроме того, Animate ограничивает размер диапазоном от [2,2] до [1000, 1000].

Зависимости

Нет

Набор зависимых объектов для компонента. Это массив, в котором каждая запись содержит относительный путь для локального источника (с ключом = “src”) и путь CDN (с ключом =’cdn’). Путь CDN не является обязательным. Этот путь используется, когда в параметрах публикации включены размещенные библиотеки. В противном случае при предварительном просмотре или публикации будет использоваться локальный источник.

Обратите внимание, что в приведенном выше примере используется относительный путь (видео). Он загружает зависимые объекты на один уровень выше, что обеспечивает совместное использование некоторых таких объектов несколькими наборами компонентов.

Свойства

Да

Это массив свойств. При создании экземпляра этого компонента в рабочей области настроенный в массиве набор свойств автоматически отображается в инспекторе свойств. Пользователи данного компонента могут настроить эти свойства в Animate, и настроенные свойства становятся доступными при создании экземпляра компонента во время выполнения.

Каждая запись свойства содержит следующие ключи:

  1. name: имя данного свойства, отображаемое в инспекторе свойств. Это должно быть удобное для чтения имя. Оно может быть локализовано
  2. variable: внутреннее имя для этого свойства. Настроенные значения будут доступны с данным именем переменной во время выполнения. Дополнительные сведения об этом см. в следующих разделах.
  3. Type: это указанный тип свойства. Animate допускает следующие типы свойств.
    1. Логическое значение — флажок в инспекторе свойств
    2. Числовое значение — числовое поле в инспекторе свойств
    3. Строковое значение — текстовое поле в инспекторе свойств
    4. Список — позволяет пользователю настроить массив значений.
    5. Коллекция — позволяет настроить список пар <key, value>. (См. поле со списком)
    6. Путь к файлу — позволяет выполнить обзор и выбрать любой локальный файл. Строковое значение предоставляется во время выполнения. Этот файл автоматически копируется в папке опубликованного вывода в подпапке assets, и относительный путь становится доступным во время выполнения.
    7. Путь к изображению — позволяет пользователю просмотреть и выбрать любое изображение. Этот файл автоматически копируется в подпапку настроенных изображений папки опубликованного вывода, и относительный путь становится доступным во время выполнения.
    8. Путь к видеосодержимому — позволяет пользователю просмотреть и выбрать любой источник видео в веб-формате (mp4, ogg , ogv , webm ). Настроенный ресурс копируется в подпапку videos в папке опубликованного вывода.
    9. Цвет — палитра цветов в инспекторе свойств
  4. По умолчанию: значение свойства по умолчанию. Тип значения по умолчанию должен совпадать с типом свойства.

Источник компонента

С каждым компонентом должен быть связан исходный файл, содержащий код для обработки следующих задач:

  • Создание экземпляра компонента во время выполнения с настроенным набором значений свойств
  • Присоединение к DOM и отсоединение.
  • Свойство обновляется в каждом кадре

Предоставляется базовый класс и функция утилиты в файле anwidget.js для упрощения разработки пользовательских компонентов. Этот интерфейс в будущем будет улучшен с обеспечением обратной совместимости. В настоящее время поддерживаются только компоненты на базе DOM. Однако поддержка компонентов на базе HTML5 Canvas будет расширена. В настоящее время поддерживаются только виджеты. Однако инфраструктура будет расширена для обеспечения поддержки поведений присоединения (не компоненты интерфейса пользователя).

Файл anwidget.js находится в папке HTML5Components/sdk в папке first run. Он предоставляет базовый класс AnWidget для пользовательских компонентов и метод утилиты $.anwidget(<className>, {Object Prototype}) для регистрации пользовательского компонента. В текущей реализации используется jQuery, поэтому jQuery всегда добавляется в качестве зависимого объекта всегда, когда используются сервисы, предоставленные виджетом. Однако если не требуется добавлять в подразумеваемую зависимость jQuery, то может потребоваться реализовать класс Component без jQuery, который обеспечивает такой же интерфейс, как и класс Widget.

 

Шаблон HTML

Html-файл по умолчанию содержит эти разделы (за исключением предзагрузчика div):

Разделы HTML по умолчанию (за исключением предзагрузчика div)

Обратите внимание, что на предыдущей иллюстрации показан порядок, в котором элементы добавляются в DOM. Таким образом, dom_overlay_container div отображается над холстом.

 Не изменяйте идентификатор dom_overlay_container div, как требовалось в первом выпуске, имеется несколько функций, которые используют этот идентификатор, например фрагменты кода.

Как показано на предыдущей иллюстрации, dom_overlay_container div отображается в верхней части холста в виде наложения. Чтобы события мыши правильно распространялись и на базовом холсте, свойство CSS {pointer-events: none} для этого div. Все экземпляры компонентов, настроенные в проекте Animate, создаются и присоединяются в качестве дочернего объекта для этого div-элемента dom_overlay_container. Относительный порядок экземпляров сохраняется во время выполнения, но все экземпляры компонента всегда отображаются как наложение. Задается {pointer-events: all} для всех экземпляров компонента во время выполнения, чтобы они также получали события мыши.

Жизненный цикл компонента

Жизненный цикл компонента

  1. Экземпляр компонента создается, когда конструируется DOM для контейнера.

  2. Затем он присоединяется к DOM, когда точка воспроизведения достигает кадра, в котором используется этот экземпляр компонента. Затем он присоединяет обработчик событий обновления, который вызывается при каждом событии Tick во время выполнения. Компонент также одновременно отправляет событие attached вместе со следующими данными события {id: id_of_the_instance} родительского элемента.

  3. Свойства обновляются в каждом обратном вызове update. Все обновления свойств кэшируются и применяются одновременно во время обработки событий Tick. В настоящее время не поддерживается анимация пользовательских свойств. Обновляются только базовые свойства, такие как прозрачность и видимость.

  4. Когда точка воспроизведения достигает кадра, в котором экземпляр компонента удаляется, он отсоединяется от DOM. На этот раз событие detached инициируется для родительского элемента.

Базовый класс называется $.AnWidget и обеспечивает следующие переопределения:

Имя

Обязательный

Описание

getCreateOptions()

Нет

Возвращает параметры, которые компоненту требуется назначить во время создания экземпляра. Для обычного переопределения этот метод применяется для назначения уникального идентификатора каждому экземпляру с использованием глобальной переменной _widgetID. Это демонстрирует пример в следующем разделе.

getCreateString()

Да

Возвращает строку для создания экземпляра DOM. Эта строка передается в jQuery для создания фактического элемента DOM, который позже присоединяется к базовому DOM.

 

Например, для компонента изображения будет возвращено «<image>».

 

Во время выполнения создается элемент, и ссылка на файл оболочки jQuery сохраняется в экземпляре компонента следующим образом:

 

this._element =  $(this.getCreateElement())

 

// this._element – создается файл оболочки jQuery для базового элемента DOM.

 

Также можно создавать составные элементы. Дополнительные сведения см. в разделе «Примеры».

getProperties()

Нет

Возвращает массив настраиваемых имен свойств CSS. Как правило, этот метод сопоставляет все свойства, настроенные в components.json

 

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

 

["left", "top", "width", "height", "position", "transform-origin", "transform"]

getAttributes()

Нет

Возвращает массив настраиваемых атрибутов. Как правило, этот метод сопоставляет все атрибуты, настройка которых разрешена в components.json

 

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

 

["id", "src", "controls", "autoplay", "loop", "class"]

attach(parent)

Нет

Эта функция вызывается каждый раз перед присоединением экземпляра компонента к «родительскому» элементу DOM.

 

При реализации по умолчанию выполняет следующие действия (помимо прочего):

 

// Добавляет элемент в родительский элемент DOM

$(parent).append(this._element);

 

//Сохраняет ссылку в this._$this

this._$this = $(this._element);

 

//Вызывает принудительное обновление для применения всех свойств

this.update(true);

this._attached = true;

 

//Инициирует событие attached для родительского элемента

$(parent).trigger("attached", this.getEventData("attached"))

 

Эту функцию не требуется переопределять. Однако это может потребоваться для составных элементов. Дополнительные сведения см. в разделе «Примеры».

 

Примечание. Можно использовать this._superApply(arguments) для вызова любого метода класса из любого переопределения.

detach()

Нет

Эта функция вызывается каждый раз перед удалением экземпляра компонента из DOM. При реализации по умолчанию выполняет следующие действия:

 

//Удаляет элемент из DOM

this._$this.remove();

//Инициирует событие detached для родительского элемента

$(parent).trigger("detached", this.getEventData("detached"));

setProperty(k,v)

Нет

Эта функция задает любое свойство для экземпляра. Эти изменения сразу кэшируются и применяются во время вызова update() для каждого кадра для каждого измененного свойства.

update(force)

Нет

Эта функция вызывается в каждом кадре, когда компонент входит в состав DOM и является видимым. Реализация по умолчанию применяет все свойства CSS и атрибуты, которые изменены или имеют параметр со значением true.

show()

Нет

Показывает экземпляр элемента. Как правило, эту функцию переопределять не нужно, но это может потребоваться для составных элементов.

hide()

Нет

Скрывает экземпляр элемента. Как правило, эту функцию переопределять не нужно, но это может потребоваться для составных элементов.

getEventData(e)

Нет

Возвращает пользовательские данные для события с именем «e». При реализации по умолчанию передаются данные {id: instance_id} для событий attached и detached.

destroy()

Нет

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

applyProperties(e)

Нет

Вспомогательный API-интерфейс для применения свойств CSS к файлу оболочки jQuery e.

applyAttributes(e)

Нет

Вспомогательный API-интерфейс для применения атрибутов к файлу оболочки jQuery e.

Локализация

Строку категории, отображаемое имя компонента и имя свойства можно локализовать. Создайте файл с именем strings.json в папке locale, которая находится в каталоге компонентов. Предоставьте пары «ключ-значение» для локализации всех строк и используйте ключ в components.js. Для других локалей необходимо предоставить строки в соответствующих папках в каталоге locale.

Строка .json

Упаковка и распределение пользовательских компонентов HTML5

Разработчики или дизайнеры Animate могут предоставлять аниматорам готовые упакованные компоненты, которые можно устанавливать и использовать без изменения кода. Ранее аниматорам необходимо было изучать файловые структуры, осваивать программирование и вручную перемещать файлы в определенные папки для активации расширений HTML5.

Предварительные условия

  • Наличие любого компонента, созданного разработчиком. Чтобы ознакомиться с инструкциями по созданию компонентов, щелкните здесь.
  • Набор средств для подписи расширений CC.

Перед упаковкой компонента создайте файл MXI с метаданными исходного и целевого путей размещения компонентов. Ниже приведен пример.

<file source=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />
<file source=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />
<file source=&quot;jquery-ui-1.12.0&quot; destination=&quot;$FLASH\HTML5Components\jQueryUI\&quot; file-type=&quot;ordinary&quot; />

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

Упаковка компонентов

Чтобы упаковать пользовательские компоненты HTML5, выполните следующие действия. 

  1. Чтобы создать файл MXI, воспользуйтесь текстовым редактором. Содержимое должно быть аналогично содержимому образца  abc.mxi Сохраните созданный документ с расширением MXI.

    Загрузить

  2. Добавьте в папку файл компонента MXI и связанные с ним файлы.

  3. Создайте архив с расширением ZXP, используя инструмент для подписи расширений CC (ZXPSignCmd.exe). Для создания файла ZXP используйте следующие команды в инструменте ZXP Sign Command.

    1. Создайте самозаверенный сертификат, используя параметр -selfSignedCert.

    Если у вас уже есть сертификат, этот шаг можно пропустить.

    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12

    В текущей папке появится файл FileName.p12.

    2. Подпишите расширение с помощью следующей команды: 

    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password

    Вместо projectName нужно подставить имя проекта по созданию расширения. В текущей папке появится файл с именем projectName.zxp.

Распределение компонентов

Упакованный файл компонента projectName.zxp можно распределить любому пользователю Animate.

 Компания Adobe рекомендует вам распространять продукты через веб-сайт надстроек Adobe Add-ons. Надстройки могут быть общедоступными (бесплатными или платными) или частными (бесплатными для определенных пользователей).

Установка распределенных компонентов

Дизайнеры или разработчики Animate могут установить распределенный компонент (файл ZXP), воспользовавшись утилитой Управление расширениями.

Получайте помощь быстрее и проще

Новый пользователь?