この記事では、HTML5 Canvas のカスタムコンポーネントの作成方法について説明します。

Animate には一連のデフォルトコンポーネントが付属しています。しかし、それだけでは足りない場合があります。このトピックは、Animate のカスタム HTML5 コンポーネントを作成する方法を理解するのに役立ちます。

コンポーネント定義は次の 3 つの主要部分で構成されます。

  • メタデータ:コンポーネントに関する情報(表示名、バージョン、設定可能な一連のプロパティ、アイコンなど)を提供します。これは components.js というファイルに記述されます。複数のコンポーネントをカテゴリーとしてグループ化することができ、その場合は、このファイルによって、カテゴリーに属するすべてのコンポーネントのメタデータを提供することができます。
  • ソース:実際のコンポーネントソースに関する情報を提供します。これは、コンポーネントを使用するムービーをプレビューまたはパブリッシュする際に、実行時に埋め込まれます。
  • アセット:実行時の依存関係に関する情報(JavaScript ライブラリ、CSS、ランタイムアセット、アイコンなど)を提供します。これらのアセットは、Animate オーサリング環境で使用できます。

注意:

コンポーネントの定義には、ローカライズ関連のリソースが含まれます。

componentsJS
カスタムコンポーネントカテゴリーのフォルダー設定例

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 ディレクトリ内の別個のフォルダーに格納されています。 

metadata-code
ビデオコンポーネントのサンプルメタデータ

components.js

components.js

は、次のセクションで構成される JSON ファイルです。

  • category:コンポーネントパネルでのこのコンポーネントセットの名前で、ローカライズ可能です。
  • components:コンポーネントに関するメタデータを記述するエントリを要素とする配列。上記のサンプルでは、この配列の要素が 1 つだけです。メタデータは次のセクションで構成されます。

名前

必須かどうか

説明

className

はい

ソースファイルで指定されるコンポーネントのクラス名。クラス名では 1 レベルの名前空間をサポートしています。例えば、Video などです。

version

いいえ

コンポーネントのバージョン番号。これは、コンポーネントの今後のアップグレードに使用されます。ただし、この時点ではアップグレードフローは定義されていません。

source

はい

コンポーネントのメインソースファイルの相対パス。詳しくは、次の節に記載されているソースの内容を参照してください。

icon

いいえ

コンポーネントのアイコンの相対パス。このアイコンは、コンポーネントに対して名前を付けてインスタンスが作成された場合に、コンポーネントパネルとステージ上で使用されます。指定されない場合、デフォルトのアイコンが使用されます。

読み込むアイコン(通常 32x32 のサイズ)の PNG ファイル名を指定できます。または、明るい UI と暗い UI 用に異なるアイコンをサポートする場合は、次の命名規則に従う 2 つの .png ファイルを用意し、

custom_icon_N.png – 暗い UI 用のアイコン

custom_icon_D.png – 明るい UI 用のアイコン

名前の「custom_icon」の部分をこのフィールドの値として指定します。接尾辞は、現在のユーザー設定に基づいて自動的に付けられます。

dimensions

いいえ

コンポーネントインスタンスのデフォルトのサイズ。ユーザーがコンポーネントパネルからステージにコンポーネントをドラッグ&ドロップするたびに、新しいインスタンスが作成されます。このフィールドは、そのコンポーネントインスタンスのデフォルトの初期サイズを指定します。値は配列 [幅, 高さ] です。値が指定されない場合は、自動的にデフォルトサイズが設定されます。また、値は [2,2] から [1000, 1000] までの範囲に制限されます。

dependencies

いいえ

コンポーネントの依存先モジュールの集合。これは、ローカルソースの相対パス(キーが「src」)と CDN パス(キーが「cdn」)を指定するエントリを要素とする配列です。CDN パスは省略可能です。このパスが使用されるのは、パブリッシュ設定でホストのライブラリを使用する場合です。そうでない場合は、プレビュー時やパブリッシュ時にローカルソースが使用されます。

上記の例(video)で使用されている相対パスに注意してください。1 レベル上の依存先モジュールを読み込むので、複数のコンポーネントセット間で一部の依存先モジュールを共有することができます。

properties

はい

プロパティの配列。このコンポーネントのインスタンスをステージに作成すると、ここで設定したプロパティのセットがプロパティインスペクターに自動的に表示されます。このコンポーネントのユーザーはこれらのコンポーネントを Animate で設定でき、設定したプロパティは、実行時にコンポーネントがインスタンス化されるときに使用可能になります。

各プロパティエントリは次のキーで構成されます。

  1. name: このプロパティのプロパティインスペクターでの表示名。わかりやすい名前でなければなりません。これはローカライズ可能です。
  2. variable:このプロパティに使用される内部名。設定した値は、実行時にこの変数名で使用できます。詳しくは、後の節を参照してください。
  3. type:プロパティの型を指定します。Animate では次の型が使用可能です。
    1. Boolean - プロパティインスペクターのチェックボックス
    2. Number - プロパティインスペクターの数値ボックス
    3. String    -プロパティインスペクターのテキストボックス
    4. List        -ユーザーが値の配列を設定可能。
    5. Collection - ユーザーが <キー, 値> ペアのリストを設定可能。(コンボボックスを参照)
    6. File Path - ユーザーが任意のローカルファイルを参照して選択可能。文字列値は実行時に入力されます。ファイルは、パブリッシュされる出力の「assets」フォルダーに自動的にコピーされ、その相対パスが実行時に使用可能になります。
    7. Image Path - ユーザーが任意の画像を参照して選択可能。ファイルは、パブリッシュされる出力の設定済み画像フォルダーに自動的にコピーされ、その相対パスが実行時に使用可能になります。
    8. Video Content Path – ユーザーが任意の Web 形式ビデオソース(mp4、oggogvwebm)を参照して選択可能。設定したアセットは、パブリッシュされる出力の「videos フォルダーにコピーされます。
    9. Color - プロパティインスペクターのカラーピッカー
  4. default:プロパティのデフォルト値。デフォルトの型は、プロパティの型と同じである必要があります。

コンポーネントのソース

各コンポーネントには、以下を処理するコードを提供するソースファイルが関連付けられている必要があります。

  • 設定したプロパティ値セットを割り当てたコンポーネントインスタンスの実行時での作成
  • DOM へのアタッチと DOM からのデタッチ
  • フレームごとのプロパティの更新

カスタムコンポーネントを開発しやすいように、基底クラスとユーティリティ関数が anwidget.js ファイルに用意されています。このインターフェイスは今後、機能強化される予定ですが、下位互換性は保たれます。現時点では、DOM ベースのコンポーネントのみサポートされていますが、Canvas ベースのコンポーネントもサポートされる予定です。現時点では、ウィジェットのみサポートされていますが、フレームワークが機能強化され、動作の割り当て(非 UI コンポーネント)もサポートされる予定です。

anwidget.js ファイルは First Run フォルダー内の HTML5Components/sdk フォルダーにあります。この中には、カスタムコンポーネントの基底クラス AnWidget と、カスタムコンポーネントを登録するためのユーティリティメソッド $.anwidget(<className>, {Object Prototype}) が用意されています。現在の実装では jQuery を使用しているので、ウィジェットから提供されるサービスを使用するたびに、jQuery が依存先モジュールとして常に追加されます。ただし、jQuery に暗黙に依存しないようにする場合は、ウィジェットと同じインターフェイスを提供するコンポーネントクラスを jQuery を使用せずに実装する必要があります。

 

AnWidget
HTML テンプレート

HTML には、デフォルトで以下のセクション($PRELOADER_DIV を除く)が含まれます。

animation_container
デフォルトの HTML セクション($PRELOADER_DIV を除く)

上の図が DOM へのエレメントの追加順序を示していることに注意してください。したがって、dom_overlay_container div は canvas の上に示されています。

注意:

dom_overlay_container div の ID を変更しないでください。この最初のリリースでは、この ID のコード例のようなコードに依存している機能がいくつかあるからです。

上図からわかるように、dom_overlay_container div は canvas の上にオーバーレイとして示されています。ベースとなる canvas にもマウスイベントが必ず適切に伝達されるように、この div に CSS プロパティ {pointer-events: none} を使用しています。プロジェクトにおいて Animate で設定するすべてのコンポーネントインスタンスは、この dom_overlay_container div の子としてインスタンス化されアタッチされます。コンポーネントインスタンスの相対的順序は実行時に維持されますが、現時点では、コンポーネントインスタンスはすべて、常にオーバーレイとして表示されます。マウスイベントも受信するように、実行時のすべてのコンポーネントインスタンスに {pointer-events: all} を設定しています。

コンポーネントのライフサイクル

component_lifecycle
コンポーネントのライフサイクル

  1. コンポーネントインスタンスが作成されるのは、コンテナの DOM が作成されるときです。

  2. インスタンスはその後、コンポーネントインスタンスが使用されるフレームに再生ヘッドが達したときに DOM にアタッチされます。その次に、実行時に Tick イベントが発生するたびに呼び出される更新ハンドラーがアタッチされます。このとき、イベントデータ {id: id_of_the_instance} を持つ「attached」イベントが親エレメントで発生します。

  3. 更新コールバックが呼び出されるたびに、プロパティが更新されます。プロパティ更新はすべてキャッシュされ、Tick イベントハンドラーの呼び出し時に 1 回適用されます。現時点では、カスタムプロパティに対するトゥイーンはサポートされていません。変形や可視性などの基本プロパティのみ更新されます。

  4. コンポーネントインスタンスが削除されるフレームに再生ヘッドが達したときに、インスタンスが DOM からデタッチされます。このとき、「detached」イベントが親エレメントで発生します。

基本クラスは $.AnWidget と呼ばれ、以下のオーバーライドを提供します。

名前

必須かどうか

説明

getCreateOptions()

いいえ

コンポーネントがインスタンス化されるときに適用されるオプションを返します。典型的なオーバーライドでは、通常、これを使用して、すべてのインスタンスに一意な ID を割り当てます(グローバル変数 _widgetID を利用)。次の節で示す例では、この使用法をわかりやすく説明します。

getCreateString()

はい

DOM インスタンス作成の文字列を返します。この文字列が jQuery に渡されて、実際の DOM エレメントが作成されます。それは後で、ベースとなる DOM にアタッチされます。

 

例えば、画像コンポーネントの場合、これは「<image>」を返します。

 

実行時にそのエレメントが作成され、jQuery ラッパーへの参照がコンポーネントインスタンスに次のように格納されます。

 

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

 

// this._element – 作成されたベース DOM エレメントの jQuery ラッパー

 

コンポジットエレメントも作成できます。詳しくは、例の節を参照してください。

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);

//強制的に update を呼び出してすべてのプロパティを適用

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 プロパティおよび属性を適用します。または、force パラメーターが true の場合に適用します。

show()

いいえ

エレメントインスタンスを表示します。通常jは、これをオーバーライドする必要はありませんが、コンポジットエレメントの場合は、オーバーライドしなければならない可能性があります。

hide()

いいえ

エレメントインスタンスを非表示にします。通常jは、これをオーバーライドする必要はありませんが、コンポジットエレメントの場合は、オーバーライドしなければならない可能性があります。

getEventData(e)

いいえ

「e」という名前のイベントのカスタムデータを返します。デフォルトの実装では、attached イベントと detached イベントの「{id: instance_id}」データを渡します。

destroy()

いいえ

コンポーネントインスタンスが DOM からデタッチされると、メモリを解放します。通常は、これをオーバーライドする必要はありません。

applyProperties(e)

いいえ

CSS プロパティを jQuery ラッパー e に適用するためのヘルパー API

applyAttributes(e)

いいえ

属性を jQuery ラッパー e に適用するためのヘルパー API

ローカライゼーション

カテゴリー文字列、コンポーネント表示名およびプロパティ名はローカライズできます。components フォルダー下にある locale という名前のフォルダー内に strings.json という名前のファイルを作成します。ローカライズするすべての文字列にキーと値のペアを提供し、components.js 内のキーを使用します。他のロケールについては、locale フォルダー下の対応するフォルダー内のファイルに文字列を記述する必要があります。

localization
.json ファイルに定義される文字列

HTML5 のカスタムコンポーネントのパッケージ化と配布

Animate 開発者またはデザイナーは、パッケージ化されたすぐに利用できるコンポーネントを提供することにより、アニメーターがコードを書かなくてもカスタムコンポーネントをインストールして使用できるようにすることができます。以前は、アニメーターが HTML5 エクステンションを有効にするには、ファイル構造を理解し、プログラミングをおこない、特定のフォルダーにファイルを手動で移動する必要がありました。

前提条件

コンポーネントをパッケージ化する前に、コンポーネントのソースパスと出力先パスのメタデータを含む MXI ファイルを作成します。例えば、次のように指定します。

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

このソースと出力先ファイル情報は、エクステンションユーティリティがコンポーネントを正しくインストールするために必要となります。

コンポーネントのパッケージ化

HTML5 カスタムコンポーネントをパッケージ化するには、次の手順を実行します。 

  1. MXI ファイルを作成するには、テキストエディターを使用してサンプルのabc.mxi ファイルと同様の内容を入力し、MXI 拡張子を付けてファイルを保存します。

    Download

    ダウンロード

  2. MXI コンポーネントファイルとその他の関連ファイルをフォルダーに追加します。

    Add-MXI-file-to-component
  3. CC エクステンション署名ツール(ZXPSignCmd.exe)を使用して ZXP エクステンションの zip ファイルを作成します。ZXP 署名コマンドツールで次のコマンドを使用して ZXP ファイルを作成します。

    1. -selfSignedCert オプションを使用して自己署名証明書を作成します。

    既に証明書がある場合は、この手順をスキップできます。

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

    FileName.p12 ファイルがカレントフォルダーに生成されます。

    2. 次のコマンドを使用してエクステンションに署名します。

    Create-ZXP-file
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password

    projectName はエクステンションプロジェクトの名前です。カレントフォルダーに projectName.zxp という名前のファイルが生成されます。

コンポーネントの配布

パッケージ化されたこの projectName.zxp コンポーネントファイルは任意の Animate ユーザーに配布できます。

注意:

アドビでは、Adobe Add-ons Web サイトを通じて製品を配布することをお勧めします。アドオンは一般に(無料または有料で)配布することも、個人的に(特定のユーザーに無償で)配布することもできます。詳しくは、製品を個人的に共有する方法を参照してください。

配布されたコンポーネントのインストール

Animate デザイナーまたは開発者は、エクステンションの管理ユーティリティを使用して、配布された ZXP ファイルのコンポーネントをインストールできます。

詳しくは、配布されたコンポーネントのインストールを参照してください。