ACTIONSCRIPT® 3.0
開発ガイド

法律上の注意
法律上の注意については、http://help.adobe.com/ja_JP/legalnotices/index.html を参照してください。

最終更新日 2015/10/14

iii

目次
第 1 章：日付と時刻の操作
カレンダー日付と時刻の管理
タイマー間隔の制御............................................................................................... 1....................................................................................................... 4

日付と時刻の例：単純なアナログ時計....................................................................................... 6

第 2 章：ストリングの操作
ストリングの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

ストリングの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

length プロパティ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

ストリング内の文字の操作
ストリングの比較. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

他のオブジェクトのストリング表現の取得
ストリングの連結. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

ストリング内に含まれるサブストリングおよびパターンの検索
ストリングの大文字／小文字の変換
ストリングの例：ASCII アート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

第 3 章：配列の操作
配列の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

インデックス配列. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

結合配列

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

多次元配列

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

配列のコピー. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Array クラスの拡張. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

配列の例：PlayList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

第 4 章：エラー処理
エラー処理の基礎
エラーの種類. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

ActionScript 3.0 におけるエラー処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

デバッガーバージョンの Flash ランタイムの操作
アプリケーションの同期エラーの処理
カスタムエラークラスの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

エラーイベントおよびステータスへの応答. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Error クラスの比較 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
エラー処理の例：CustomErrors アプリケーション. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイドiv

目次

第 5 章：正規表現の使用
正規表現の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

正規表現のシンタックス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

ストリングに対して正規表現を使用するメソッド
正規表現の例：Wiki パーサー

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

第 6 章：XML の操作

XML の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

XML 処理の E4X アプローチ
XML オブジェクト. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

XMLList オブジェクト . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
XML 変数の初期化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

XML オブジェクトの構築と変形
XML 階層構造へのアクセス
XML 名前空間の使用
XML の型変換. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

外部 XML ドキュメントの読み込み. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

ActionScript 内の XML の例：インターネットからの RSS データのロード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

第 7 章：ネイティブ JSON 機能の使用

JSON API の概要. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

カスタム JSON 動作の定義. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

第 8 章：イベント処理
イベント処理の基本. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

ActionScript 3.0 イベント処理の以前のバージョンとの違い
イベントフロー. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

イベントオブジェクト
イベントリスナー. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

イベント処理の例：Alarm Clock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

第 9 章：アプリケーションドメインの操作
第 10 章：表示のプログラミング
表示のプログラミングの基本
コア表示クラス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

表示リストを使用するアプローチの利点. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

表示オブジェクトの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

表示オブジェクトの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

オブジェクトのアニメーション化
ステージの方向. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

表示コンテンツの動的ロード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

表示オブジェクトの例：SpriteArranger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイドv

目次

第 11 章：ジオメトリの操作
ジオメトリの基本. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Point オブジェクトの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Rectangle オブジェクトの使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Matrix オブジェクトの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

ジオメトリの例：マトリックス変換の表示オブジェクトへの適用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

第 12 章：描画 API の使用
描画 API の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Graphics クラス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
線と曲線の描画. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

ビルトインメソッドを使用したシェイプの描画
グラデーションの線と塗りの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

描画メソッドでの Math クラスの使用
描画 API でのアニメーション化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

描画 API の例：Algorithmic Visual Generator
描画 API の高度な使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

第 13 章：ビットマップの操作
ビットマップの操作の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Bitmap および BitmapData クラス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
ピクセルの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

ビットマップデータのコピー. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

ビットマップデータの圧縮. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

ノイズ関数によるテクスチャの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

ビットマップのスクロール. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

ミップマッピングの利用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

ビットマップの例：回転する月のアニメーション
ビットマップイメージの非同期デコード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

第 14 章：表示オブジェクトのフィルター処理
表示オブジェクトのフィルター処理の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

フィルターの作成と適用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

使用可能な表示フィルター. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

表示オブジェクトのフィルター処理の例：Filter Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

第 15 章：Pixel Bender シェーダーの操作

Pixel Bender シェーダーの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

シェーダーのロードまたは埋め込み. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

シェーダーメタデータへのアクセス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

シェーダーの入力およびパラメーターの値の指定
シェーダーの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイドvi

目次

第 16 章：ムービークリップの操作
ムービークリップの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

MovieClip オブジェクトの操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
ムービークリップの再生の制御. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

ActionScript での MovieClip オブジェクトの作成
外部の SWF ファイルのロード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

ムービークリップの例：RuntimeAssetsExplorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

第 17 章：モーショントゥイーンの操作
モーショントゥイーンの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Flash でのモーショントゥイーンスクリプトのコピー . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
モーショントゥイーンスクリプトの組み込み
アニメーションの作成
フィルターの追加. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

表示オブジェクトへのモーショントゥイーンの関連付け. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

第 18 章：インバースキネマティックの操作
インバースキネマティックの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

IK のアーマチュアのアニメーション化の概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
IK のアーマチュアの詳細 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
IK Mover のインスタンス化とその動きの制限. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

IK のアーマチュアの移動 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
スプリングの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

IK イベントの使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
第 19 章：3 次元（3D）での操作

3D 表示オブジェクトの基礎 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Flash Player および AIR ランタイムでの 3D 表示オブジェクトについて . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
3D 表示オブジェクトの作成と移動 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
2D ビューへの 3D オブジェクトの投影
例：遠近法投影. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

複雑な 3D 変換の実行. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

3D 効果のための三角形の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
第 20 章：テキストの操作の基礎
第 21 章：TextField クラスの使用
テキストの表示. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

テキストの選択と操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

テキスト入力のキャプチャ
テキスト入力の制限. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

テキストのフォーマット

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

高度なテキストレンダリング. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

vii

目次

静止テキストの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

TextField の例：新聞形式のテキストフォーマット . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
第 22 章：Flash Text Engine の使用
テキストの作成と表示. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

FTE でのイベントの処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

テキストのフォーマット

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

フォントの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

テキストの制御. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

Flash Text Engine の例：ニュースレイアウト. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

第 23 章：Text Layout Framework の使用

Text Layout Framework の概要. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Text Layout Framework の使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

TLF を使用したテキストの構造化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

TLF を使用したテキストの書式設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

TLF を使用したテキストの読み込みと書き出し
TLF を使用したテキストコンテナの管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

TLF を使用したテキスト選択、編集、取り消しの有効化
TLF を使用したイベント処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

テキスト内部へのイメージの配置. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

第 24 章：サウンドの操作
サウンドの操作の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

サウンドアーキテクチャについて. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

外部のサウンドファイルの読み込み. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

埋め込みサウンドの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

ストリーミングサウンドファイルの操作
動的に生成されたオーディオの操作
サウンドの再生. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

サウンドのロード時および再生時のセキュリティ重要事項
サウンドの音量とバランスの制御
サウンドメタデータの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

生のサウンドデータへのアクセス
サウンド入力のキャプチャ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

サウンドの例：Podcast Player. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

第 25 章：ビデオの操作
ビデオの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

ビデオ形式について. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454

Video クラスについて . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
ビデオファイルのロード
ビデオ再生の制御. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

viii

目次

フルスクリーンモードでのビデオ再生
ビデオファイルのストリーミング
キューポイントについて. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

メタデータとキューポイントのコールバックメソッドの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

キューポイントとメタデータの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

NetStream アクティビティの監視. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

ビデオファイルに関する高度なトピック. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

ビデオの例：ビデオジュークボックス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

ハードウェアアクセラレーションによる表示のための StageVideo クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

第 26 章：カメラの操作

Camera クラスについて. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

カメラコンテンツの画面への表示. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

カメラアプリケーションの設計. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

ユーザーのカメラへの接続. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

カメラのインストールの確認. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499

カメラのアクセス許可の検知. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

カメラビデオ品質の最大化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501

カメラステータスの監視. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502

第 27 章：電子著作権管理の使用保護されたコンテンツのワークフローについて. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

NetStream クラスの DRM 関連のメンバーおよびイベント
DRMStatusEvent クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

DRMAuthenticateEvent クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514

DRMErrorEvent クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

DRMManager クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

DRMContentData クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

Flash Player の更新による Adobe Access のサポート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520

帯域外ライセンス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

ドメインサポート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522

ドメインサポートを使用した暗号化されたコンテンツの再生ライセンスプレビュー
コンテンツの配信. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Open Source Media Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

第 28 章：AIR での PDF コンテンツの追加

PDF 機能の検出 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
PDF コンテンツの読み込み . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
PDF コンテンツのスクリプト作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
AIR 内の PDF コンテンツに関する既知の制限. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイドix

目次

第 29 章：ユーザー操作の基礎
ユーザー入力のキャプチャ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

フォーカスの管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

入力タイプの検出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534

第 30 章：キーボード入力
キーボード入力のキャプチャ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

IME クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538

仮想キーボード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

第 31 章：マウス入力
マウス入力のキャプチャ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

マウス入力の例：WordSearch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553

第 32 章：タッチ入力、マルチタッチ入力およびジェスチャ入力
タッチ入力の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

タッチのサポートの検出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

タッチイベント処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

タッチ＆ドラッグ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

ジェスチャイベント処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

トラブルシューティング. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

第 33 章：コピー＆ペースト
コピー＆ペーストの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

システムクリップボードとの間の読み書き. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

AIR での HTML コピー＆ペースト . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
クリップボードのデータ形式. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

第 34 章：加速度センサー入力
加速度センサーのサポートの確認
加速度センサーの変更の検出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

第 35 章：AIR でのドラッグ＆ドロップ

AIR でのドラッグ＆ドロップの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

ドラッグアウトジェスチャのサポート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

ドラッグインジェスチャのサポート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

HTML でのドラッグ＆ドロップ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
HTML エレメントからのデータのドラッグ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594

HTML エレメントへのデータのドラッグ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

例：デフォルトの HTML ドラッグインジェスチャの上書き. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

非アプリケーションの HTML サンドボックスでのファイルドロップの処理
ファイルプロミスのドロップ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイドx

目次

第 36 章：メニューの操作
メニューの基本. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607

ネイティブメニューの作成（AIR） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
コンテキストメニューについて：HTML（AIR）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616

ポップアップネイティブメニューの表示（AIR）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

メニューイベントの処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

ネイティブメニューの例：ウィンドウメニューとアプリケーションメニュー（AIR）. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

第 37 章：AIR のタスクバーアイコン
タスクバーアイコンについて
ドックアイコン. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

システムトレイアイコン. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

ウィンドウのタスクバーのアイコンとボタン. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

第 38 章：ファイルシステムの操作

FileReference クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628

AIR ファイルシステム API の使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

第 39 章：ローカルデータの保存
共有オブジェクト

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

暗号化されたローカルストア. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685

第 40 章：AIR を使用したローカル SQL データベースの操作
ローカル SQL データベースについて
データベースの作成と変更. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

SQL データベースのデータの操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
同期および非同期のデータベース操作の使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

SQL データベースでの暗号化の使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
SQL データベースの操作のための戦略 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
第 41 章：バイト配列の操作

ByteArray の読み取りと書き込み. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749

ByteArray の例：.zip ファイルの読み取り. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

第 42 章：ネットワーキングとコミュニケーションの基礎
ネットワークインターフェイス
ネットワーク接続の変更. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

ドメインネームシステム（DNS）レコード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766

第 43 章：ソケット

TCP ソケット . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
UDP ソケット（AIR） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
IPv6 アドレス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイドxi

目次

第 44 章：HTTP 通信
外部データのロード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782

Web サービス要求. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

別のアプリケーションで URL を開く. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797

第 45 章：Flash Player および AIR の他のインスタンスとの通信

LocalConnection クラスについて . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
2 つのアプリケーション間でのメッセージ送信 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
異なるドメインのコンテンツおよび AIR アプリケーションへの接続. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

第 46 章：AIR のネイティブプロセスとの通信
ネイティブプロセス通信の概要. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805

ネイティブプロセスの起動および終了
ネイティブプロセスとの通信. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806

ネイティブプロセス通信のセキュリティ上の考慮事項. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

第 47 章：External API の使用

External API 使用の基本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
外部 API の要件と利点. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

ExternalInterface クラスの使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
External API の例：Web ブラウザーでの ActionScript と JavaScript との通信

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816

第 48 章：AIR での XML 署名の検証

XML 署名の検証の基礎
XML 署名について. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

IURIDereferencer インターフェイスの実装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
第 49 章：クライアントのシステム環境
クライアントのシステム環境の基礎

System クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837

Capabilities クラスの使用. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838

機能の例：システム機能の検出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839

第 50 章：AIR アプリケーションの呼び出しと終了
アプリケーションの呼び出し. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843

コマンドライン引数のキャプチャ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845

ユーザーログイン時の AIR アプリケーションの呼び出し
ブラウザーからの AIR アプリケーションの呼び出し
アプリケーションの終了. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850

第 51 章：AIR ランタイムとオペレーティングシステムに関する情報の操作
ファイルの関連付けの管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852

ランタイムのバージョンとパッチレベルの取得. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

xii

目次

AIR 機能の検出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853

ユーザープレゼンスの追跡. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853

第 52 章：AIR ネイティブウィンドウの操作

AIR のネイティブウィンドウの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855

ウィンドウの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862

ウィンドウの管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

ウィンドウイベントのリッスン. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879

フルスクリーンウィンドウの表示. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881

第 53 章：AIR の表示スクリーン

AIR の表示スクリーンの基礎
スクリーンの列挙. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884

第 54 章：プリント
プリントの基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887

ページのプリント. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887

Flash ランタイムのタスクとシステムプリント . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888
サイズ、拡大率、用紙の向きの設定
高度なプリント技術. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893

プリントの例：複数ページのプリント. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895

プリントの例：拡大／縮小、トリミング、および応答
プリントの例：ページ設定とプリントオプション. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898

第 55 章：ジオロケーション
ジオロケーション変化の検出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901

第 56 章：アプリケーションの国際化
アプリケーション国際化の基礎. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905

flash.globalization パッケージの概要. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906

ロケールの特定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907

数値の形式の設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909

通貨の値の形式の設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911

日付と時刻の形式の設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913

文字列の並べ替えと比較. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914

大文字と小文字の変換. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916

例：相場表示アプリケーションの国際化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916

第 57 章：アプリケーションのローカライズ
ロケールの選択. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921

Flex コンテンツのローカライズ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
Flash コンテンツのローカライズ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
AIR アプリケーションのローカライズ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

日付、時刻および通貨のローカライズ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

xiii

目次

第 58 章：HTML 環境について

HTML 環境の概要 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
AIR および WebKit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928

第 59 章：AIR での HTML および JavaScript のプログラミング

HTMLLoader クラスについて. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944

セキュリティ関連の JavaScript エラーの回避. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946

JavaScript からの AIR API クラスのアクセス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950

AIR での URL について. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952

JavaScript から使用できる ActionScript オブジェクトの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

ActionScript からの HTML DOM オブジェクトおよび JavaScript オブジェクトへのアクセス
HTML への SWF コンテンツの埋め込み. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955

HTML ページ内での ActionScript ライブラリの使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
Date オブジェクトと RegExp オブジェクトの変換 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
ActionScript からの HTML スタイルシートの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960

異なるセキュリティサンドボックス内のコンテンツのクロススクリプト. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961

第 60 章：AIR HTML コンテナのスクリプト作成

HTMLLoader オブジェクトの表示プロパティ
HTML コンテンツのスクロール. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969

HTML 履歴リストへのアクセス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
HTML コンテンツの読み込み時に使用するユーザーエージェントの設定
HTML コンテンツで使用する文字エンコードの設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971

HTML コンテンツのブラウザー形式のユーザーインターフェイスの定義
HTMLLoader クラスのサブクラスの作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981

第 61 章：AIR における HTML 関連イベントの処理

HTMLLoader イベント . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
ActionScript による DOM イベントの処理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983

キャッチされない JavaScript 例外に対する応答. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983

JavaScript を使用したランタイムイベントの処理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
第 62 章：モバイルアプリケーションでの HTML コンテンツの表示

StageWebView オブジェクト . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
コンテンツ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988

ナビゲーションイベント. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990

ヒストリー. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991

フォーカス. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992

ビットマップキャプチャ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

xiv

目次

第 63 章：並行処理のためのワーカーの使用
ワーカーと並行処理について
ワーカーの作成と管理
ワーカー間の通信. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1000

第 64 章：セキュリティ

Flash Platform セキュリティの概要
セキュリティサンドボックス
権限の制御. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1004. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1006. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1010

ネットワーク API の制限. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1018

フルスクリーンモードのセキュリティ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1020

フルスクリーンインタラクティブモードのセキュリティ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1021

コンテンツのロード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1022

クロススクリプト. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1025

ロードされたメディアへのデータとしてのアクセス
データのロード. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1028. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1030

セキュリティドメインに読み込まれた SWF ファイルからの埋め込みコンテンツのロード
古いコンテンツの操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1034

LocalConnection 許可の設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1034
送信 URL アクセスの制御
共有オブジェクト

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1035. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1036

カメラ、マイク、クリップボード、マウス、キーボードのアクセス

AIR のセキュリティ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1038. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1038

第 65 章：ActionScript の使用方法の例
例の種類. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1059

Flash Professional での ActionScript 3.0 の例の実行
Flash Builder での ActionScript 3.0 の例の実行. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1061. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1062

モバイルデバイスでの ActionScript 3.0 の例の実行. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1063

第 66 章：ローカルデータベースでの SQL サポート
サポートされている SQL 構文
データ型のサポート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1068. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1088

第 67 章：SQL エラー詳細メッセージ、ID、および引数
第 68 章：Adobe Graphics Assembly Language（AGAL）

AGAL のバイトコード形式. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1096

最終更新日 2015/10/14

1

第 1 章：日付と時刻の操作
Flash Player 9 以降、Adobe AIR 1.0 以降
時間を扱う処理は常に必要なわけではありませんが、多くのソフトウェアアプリケーションにとって重要な要素の 1 つです。
ActionScript 3.0 には、カレンダーの日付、時刻、および時間間隔を扱う強力な機能が用意されています。時間に関連した
それらの機能のほとんどは、2 つのメインクラス、すなわち Date クラスと flash.utils パッケージに含まれる新しい Timer
クラスにより提供されます。
日付と時刻は、ActionScript プログラムで使用される一般的な情報のタイプです。例えば、現在の曜日を調べたり、ユーザーが多くの画面のうちで特定の画面にどの程度時間を費やしたか測定したりすることが必要になる場合があります。

ActionScript では、Date クラスを使用して、日付と時刻の情報を含む単一の時点を表すことができます。Date インスタン
スには、年、月、日、曜日、時、分、秒、ミリ秒、およびタイムゾーンを初めとする個別の日付と時刻の単位値が含まれます。ActionScript ではまた、より高度な使用を可能にするために、特定の遅延後、または反復する間隔でアクションを実行するために使用できる Timer クラスが用意されています。
関連項目

Date
flash.utils.Timer

カレンダー日付と時刻の管理
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、カレンダー日付と時刻の管理に関するすべての機能がトップレベルの Date クラスにまとめられています。Date クラスには、世界標準時（UTC）または何らかのタイムゾーンに基づくローカル時間において日付と時刻を処理するメソッドおよびプロパティがあります。UTC は時刻の基準となるもので、グリニッジ標準時（GMT）と基本的には同じです。

Date オブジェクトの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
Date クラスは、すべてのコアクラスの中で最も多くの用途に使用できるコンストラクターメソッドを備えています。このコ
ンストラクターは次のように 4 つの方法で使用できます。
（1）パラメーターを指定しない場合、Date() コンストラクターでは、動作環境のタイムゾーンにおけるローカル時間で現在の日付と時刻を格納した Date オブジェクトを返します。次に、その例を示します。
var now:Date = new Date();（2）1 つの数値パラメーターを指定した場合、Date() コンストラクターはその値を 1970 年 1 月 1 日からの経過ミリ秒数として解釈し、それに基づいた Date オブジェクトを返します。パラメーターは UTC の 1970 年 1 月 1 日を起点とする経過ミリ秒数として解釈されますが、返される Date オブジェクトが示す値は、(UTC 用メソッドを使用して取得および表示しない限り ) ローカルのタイムゾーンで表示されます。ミリ秒数を表す 1 個のパラメーターを指定して Date オブジェクトを新規作成する際は、ローカル時間と UTC の間のタイムゾーンの時差に注意してください。次のステートメントでは、UTC の 1970
年 1 月 1 日の深夜を表す Date オブジェクトを作成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

2

日付と時刻の操作

var millisecondsPerDay:int = 1000 * 60 * 60 * 24;// gets a Date one day after the start date of 1/1/1970
var startTime:Date = new Date(millisecondsPerDay);（3）複数の数値パラメーターを Date() コンストラクターに渡すこともできます。その場合、コンストラクターでは各パラメーターを順に年、月、日、時、分、秒、ミリ秒の値と解釈し、それらに基づいた Date オブジェクトを返します。パラメー
ターの値は UTC ではなくローカル時間を表すものと見なされます。次のステートメントでは、ローカル時間の 2000 年 1 月

1 日午前 0 時を表す Date オブジェクトを作成します。
var millenium:Date = new Date(2000, 0, 1, 0, 0, 0, 0);（4）1 つのストリングパラメーターを Date() コンストラクターに渡した場合、コンストラクターではそのストリングを解析して日付と時刻の要素を抽出しようと試み、それらに基づいた Date オブジェクトを返します。このアプローチを使用する場
合は、Date() コンストラクターを try..catch ブロックで囲んで、解析エラーをトラップします。Date() コンストラクターでは、様々なストリング形式を使用できます（『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』のリストを参照）。次のステートメントでは、新しい Date オブジェクトの初期化にストリング値を使用しています。
var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM");

Date() コンストラクターがストリングパラメーターの解析に失敗した場合、例外が発生するのではなく、作成した Date オ
ブジェクトに無効な日付値が格納されます。

時間単位値の取得
Flash Player 9 以降、Adobe AIR 1.0 以降
Date オブジェクトに格納された各種の時間単位の値は、Date クラスのプロパティとメソッドを使用して取得できます。
Date オブジェクトに格納されている時間単位の値を取得するには、次の各プロパティを使用します。

• fullYear プロパティ• month プロパティ：1 月から 12 月を 0 〜 11 で表す数値形式• date プロパティ：月の暦日を 1 〜 31 で表す数値形式• day プロパティ：日曜日から土曜日を 0 〜 6 で表す数値形式• hours プロパティ：時間を 0 〜 23 で表す数値形式• minutes プロパティ• seconds プロパティ• milliseconds プロパティ
また、Date クラスにはそれぞれの時間単位の値を取得する方法が複数用意されています。例えば、Date オブジェクトに格納された月の値は次の 4 とおりの方法で取得できます。

• month プロパティ• getMonth() メソッド
• monthUTC プロパティ• getMonthUTC() メソッド
4 つの方法は効率面ではいずれも同等なので、必要に応じて便利な方法を使用してください。
上記のプロパティはそれぞれ、日付の値全体の一部を構成する要素を表しています。例えば、milliseconds プロパティの値が 999 を超えることはありません。1000 に到達すると seconds プロパティの値が 1 加算され、milliseconds プロパ
ティの値は 0 になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

3

日付と時刻の操作

Date オブジェクトの値を 1970 年 1 月 1 日（UTC）からの経過ミリ秒数として取得する必要がある場合は、getTime() メ
ソッドを使用します。また、このメソッドと対照の関係にある setTime() メソッドを使用すれば、1970 年 1 月 1 日（UTC）からの経過ミリ秒数を指定して既存の Date オブジェクトの値を変更できます。

日付と時刻の加算および減算
Flash Player 9 以降、Adobe AIR 1.0 以降
Date クラスでは、日付と時刻に対して加算および減算を実行できます。日付値は、内部的にはミリ秒換算で維持されているので、Date オブジェクトとの間で加算または減算を行う前に、その他の値をミリ秒に変換する必要があります。
日付と時刻の加算および減算を数多く実行するアプリケーションの場合は、次のように、共通の時刻単位値をミリ秒換算で保持する定数を作成すると便利です。
public static const millisecondsPerMinute:int = 1000 * 60;
public static const millisecondsPerHour:int = 1000 * 60 * 60;
public static const millisecondsPerDay:int = 1000 * 60 * 60 * 24;

これで、標準の時刻単位を使用して容易に日付の演算を実行できます。次のコードでは、getTime() および setTime() メソッドを使用して、日付値を現在の時刻から 1 時間後に設定します。
var oneHourFromNow:Date = new Date();oneHourFromNow.setTime(oneHourFromNow.getTime() + millisecondsPerHour);

日付値を設定するもう 1 つの方法は、ミリ秒を表す 1 個のパラメーターを使用して新しい Date オブジェクトを作成することです。例えば、次のコードでは、ある日付に日数を 30 加えた日付を計算します。
// sets the invoice date to today's datevar invoiceDate:Date = new Date();// adds 30 days to get the due datevar dueDate:Date = new Date(invoiceDate.getTime() + (30 * millisecondsPerDay));

次に、30 日単位の時間を表すために millisecondsPerDay 定数に 30 を掛け、その結果を invoiceDate 値に加えて dueDate 値の設定に使用します。

タイムゾーン間の変換
Flash Player 9 以降、Adobe AIR 1.0 以降
日付と時刻の演算処理は、あるタイムゾーンを別のタイムゾーンに換算する必要がある場合に便利です。また、その際には、Date オブジェクトのタイムゾーンと UTC との時差（分）を返す getTimezoneOffset() メソッドも役立ちます。値が分単位で返されるのは、タイムゾーンによっては 1 時間未満の単位で時差が設定されており、隣接するタイムゾーンとの差が 30 分という場合があるためです。
次の例では、タイムゾーンのオフセットを使用してローカル時間の日付を UTC に変換します。まずミリ秒単位のタイム
ゾーン値を算出し、それに基づいて Date オブジェクトの値を調整するという方法で処理を実行しています。
// creates a Date in local time
var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM");// converts the Date to UTC by adding or subtracting the time zone offset
var offsetMilliseconds:Number = nextDay.getTimezoneOffset() * 60 * 1000;
nextDay.setTime(nextDay.getTime() + offsetMilliseconds);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

4

日付と時刻の操作

タイマー間隔の制御
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe Flash CS4 Professional によるアプリケーション開発の場合は、タイムラインを使用してアプリケーションの進行を
フレーム単位で確実に制御できますが、ActionScript だけを使用するプロジェクトの場合は、別のタイミング制御メカニズ
ムを使用する必要があります。

ループとタイマーの違い
Flash Player 9 以降、Adobe AIR 1.0 以降
プログラミング言語によっては、for や do..while.
一般にループステートメントは、動作環境となるローカルマシンの処理速度に応じてなるべく高速に実行されるため、使用するマシンによって速度に違いが生じます。アプリケーションを一定のタイミングで動作させるには、何らかのカレンダー
やクロックによって生成されるタイミングを利用する必要があります。ゲーム、アニメーション、およびリアルタイム制御など、多くのアプリケーションは、どのマシンでも一貫して利用できる、安定した時間ベースのタイミングメカニズムを必要とします。

ActionScript 3.0 の Timer クラスには、こうしたニーズを満たす強力な機能があります。Timer クラスでは ActionScript
3.0 のイベントモデルを使用し、指定された時間間隔が経過するごとにタイマーイベントを送出します。

Timer クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
タイマー制御関数の扱いについて、ActionScript 3.0 では Timer クラス（flash.utils.Timer）を使用する方法が推奨されています。このクラスを使用すると、所定の時間間隔が経過するたびにイベントを送出することができます。
タイマーを開始するには、最初に Timer クラスのインスタンスを作成し、そのインスタンスに対して、タイマーイベントを生成する頻度と生成終了までの送出回数を指定します。
例えば次のコードでは、1 秒ごとのイベント送出を 60 秒間続けるタイマーインスタンスを作成します。
var oneMinuteTimer:Timer = new Timer(1000, 60);

Timer オブジェクトでは、所定の時間間隔が経過するたびに TimerEvent オブジェクトを送出します。TimerEvent オブジェクトのイベント型は timer（定数 TimerEvent.TIMER によって定義される）です。TimerEvent オブジェクトには、標準の Event オブジェクトと同じプロパティが格納されます。
また、繰り返しの回数が固定されたタイマーインスタンスの場合、最後の時間間隔に到達したときに timerComplete イベン
ト（定数 TimerEvent.TIMER_COMPLETE によって定義される）も送出されます。

Timer クラスの実際の動作を確認できる短いサンプルアプリケーションを次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

5

日付と時刻の操作

package{import flash.display.Sprite;
import flash.events.TimerEvent;import flash.utils.Timer;
public class ShortTimer extends Sprite{
public function ShortTimer(){// creates a new five-second Timervar minuteTimer:Timer = new Timer(1000, 5);// designates listeners for the interval and completion events
minuteTimer.addEventListener(TimerEvent.TIMER, onTick);minuteTimer.addEventListener(TimerEvent.TIMER_COMPLETE, onTimerComplete);// starts the timer ticking
minuteTimer.start();}public function onTick(event:TimerEvent):void{// displays the tick count so far// The target of this event is the Timer instance itself.
trace("tick " + event.target.currentCount);}
public function onTimerComplete(event:TimerEvent):void{
trace("Time's Up!");}}}

この例では、ShortTimer クラスが作成されたとき、1 秒ごとのカウントを 5 秒間続ける Timer インスタンスを作成します。次に、このタイマー用のリスナーを 2 つ指定しています。1 つはカウント各回のイベントを受け取るリスナーであり、もう 1 つは timerComplete イベントを受け取るリスナーです。
その後、タイマーのカウントを開始すると、以後は 1 秒間隔で onTick() メソッドが繰り返し呼び出されます。

onTick() メソッドでは、単に現在のカウントを表示しています。5 秒が経過すると onTimerComplete() メソッドが呼び出され、カウントが終了したことを表示します。
このサンプルを実行すると、コンソールまたはトレースウィンドウに 1 秒ごとに次の行が表示されます。
tick 1tick 2
tick 3tick 4tick 5Time's Up!

flash.utils パッケージに含まれるタイマー制御関数
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 には、ActionScript 2.0 のタイマー制御関数に類似したいくつかのタイマー制御関数が含まれています。
これらの関数は、flash.utils パッケージのパッケージレベル関数として提供されており、ActionScript 2.0 と同様に動作します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

6

日付と時刻の操作

機能

説明

clearInterval(id:uint):void

指定した setInterval() 呼び出しをキャンセルします。

clearTimeout(id:uint):void

指定した setTimeout() 呼び出しをキャンセルします。

getTimer():int

Adobe® Flash® Player または Adobe® AIR™ が初期化された時点からの経過ミリ秒数を返します。

setInterval(closure:Function, delay:Number, ...
arguments):uint

ミリ秒単位で指定した間隔ごとに関数を実行します。

setTimeout(closure:Function, delay:Number, ...
arguments):uint

ミリ秒単位で指定した遅延時間の経過後に、指定した関数を実行します。

これらの関数は、後方互換性を維持する目的で ActionScript 3.0 にも残されているものです。新しい ActionScript 3.0 アプ
リケーションで使用することはお勧めしません。一般に、Timer クラスを使用する方が容易さの点でも効率の点でも有利です。

日付と時刻の例：単純なアナログ時計
Flash Player 9 以降、Adobe AIR 1.0 以降
日付と時刻に関する次の 2 つの内容について、単純なアナログ時計の例を使って示します。

•

現在の日付と時刻を取得し、時、分、秒の値を抽出する方法• Timer を使用してアプリケーションの進行ペースを制御する方法
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。SimpleClock アプリケーショ
ンのファイルは、Samples/SimpleClock フォルダーにあります。このアプリケーションは次のファイルで構成されてい
ます。
ファイル

説明

SimpleClockApp.mxml

Flash（FLA）または Flex（MXML）のメインアプリケーション
ファイル。

または

SimpleClockApp.fla
com/example/programmingas3/simpleclock/SimpleClock.as

メインアプリケーションファイル。

com/example/programmingas3/simpleclock/AnalogClockFace.as

時計の丸い文字盤と時間に合わせた時針、分針、秒針を描画する
コード。

SimpleClock クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
この時計のように単純なアプリケーションであっても、構造をわかりやすく整理しておけば、後で容易に拡張できて便利です。そこで、この SimpleClock アプリケーションの場合は SimpleClock クラスで起動時とタイマー制御の処理を扱い、時刻を実際に表示する処理には別の AnalogClockFace というクラスを使用しています。
次のコードでは、SimpleClock クラスの定義と初期化を行います（Flash バージョンでは、代わって SimpleClock がSprite クラスを拡張することに注意してください）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

7

日付と時刻の操作

public class SimpleClock extends UIComponent{/*** The time display component.
*/
private var face:AnalogClockFace;/*** The Timer that acts like a heartbeat for the application.
*/
private var ticker:Timer;

このクラスには、2 つの重要なプロパティがあります。

• face プロパティ : AnalogClockFace クラスのインスタンス• ticker プロパティ : Timer クラスのインスタンス
SimpleClock クラスではデフォルトのコンストラクターを使用します。initClock() メソッドでは実際のセットアップ処理を担当し、文字盤を作成して Timer インスタンスの動作を開始します。

文字盤の作成Flash Player 9 以降、Adobe AIR 1.0 以降
次のコードでは、時刻の表示に使用する文字盤を作成します。
/*** Sets up a SimpleClock instance.
*/
public function initClock(faceSize:Number = 200){// creates the clock face and adds it to the display list
face = new AnalogClockFace(Math.max(20, faceSize));face.init();addChild(face);// draws the initial clock display
face.draw();

initClock() メソッドに対して、文字盤のサイズを指定できます。faceSize の値を指定しない場合、デフォルト値の 200 ピクセ
ルが使用されます。
次に、このアプリケーションでは文字盤を初期化し、DisplayObjectContainer クラスから継承した addChild() メソッドを使用して表示リストに文字盤を追加します。さらに、いったん現在の時刻で盤面を表示するために AnalogClockFace.draw()
メソッドを呼び出します。

タイマーの開始
Flash Player 9 以降、Adobe AIR 1.0 以降
文字盤を作成した後は、initClock() メソッドでタイマーをセットアップします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

8

日付と時刻の操作// creates a Timer that fires an event once per second
ticker = new Timer(1000);// designates the onTick() method to handle Timer eventsticker.addEventListener(TimerEvent.TIMER, onTick);// starts the clock ticking
ticker.start();

このメソッドは、1 秒（1000 ミリ秒）ごとにイベントを送出する Timer インスタンスを最初に作成します。第 2 パラメー
ターの repeatCount を Timer() コンストラクターに渡していないので、この Timer はイベントの送出を無期限に繰り返します。

SimpleClock.onTick() メソッドは、timer イベントを受け取って 1 秒ごとに実行されます。
public function onTick(event:TimerEvent):void{// updates the clock display
face.draw();}

AnalogClockFace.draw() メソッドは、単に時計の盤面と針を描画します。

現在時刻の表示Flash Player 9 以降、Adobe AIR 1.0 以降
AnalogClockFace クラスのコードのほとんどは、時計の盤面を構成する表示要素のセットアップに関するものです。
AnalogClockFace が初期化される際には、丸い輪郭を描き、個々の定時目盛りの位置にテキストラベルで数字を配置し、さらに、時針、分針、秒針を表す 3 つの Shape オブジェクトを作成します。
SimpleClock アプリケーションが動作し始めた後は、次のように AnalogClockFace.draw() メソッドが 1 秒ごとに呼び出されます。
/*** Called by the parent container when the display is being drawn.
*/
public override function draw():void{// stores the current date and time in an instance variablecurrentTime = new Date();showTime(currentTime);}

このメソッドは、時計の針を描画している間に時刻が変化しないように、現在時刻を変数に保存します。それから、次のよ
うに showTime() メソッドを呼び出して針を表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

9

日付と時刻の操作/*** Displays the given Date/Time in that good old analog clock style.
*/public function showTime(time:Date):void{// gets the time values
var seconds:uint = time.getSeconds();
var minutes:uint = time.getMinutes();var hours:uint = time.getHours();// multiplies by 6 to get degrees
this.secondHand.rotation = 180 + (seconds * 6);
this.minuteHand.rotation = 180 + (minutes * 6);// Multiply by 30 to get basic degrees, then// add up to 29.5 degrees (59 * 0.5)// to account for the minutes.
this.hourHand.rotation = 180 + (hours * 30) + (minutes * 0.5);}

このメソッドでは、最初に現在時刻の時、分、秒それぞれの値を抽出し、それらに基づいて 3 本の針の角度を計算します。秒
針は 60 秒で 1 周するので、1 秒につき 6 度（360/60）だけ進むことになります。分針も 1 分につきこれと同じ角度だけ進みます。
分針が進むにつれて、時針も少しずつ動きます。時針は 1 時間につき 30 度（360/12）だけ進みますが、その間も 1 分につき 0.5 度（30 度 / 60 分）ずつ変化していきます。

最終更新日 2015/10/14

10

第 2 章：ストリングの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
String クラスには、テキストストリングを操作するためのメソッドが含まれています。ストリングの扱いは、様々なオブジェクトを使用する場合において重要となります。ここで説明する各種のメソッドは、TextField、StaticText、XML、ContextMenu、FileReference などのオブジェクトで使用されるストリングを操作する際に役立ちます。
ストリングは文字の連続によって構成されます。ActionScript 3.0 では ASCII と Unicode の文字がサポートされます。
関連項目

StringRegExpparseFloat()parseInt()

ストリングの基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
プログラミングの専門用語でストリングは、一連の文字、数値、または他の文字を単一の値に結合したテキスト値です。例
えば、このコード行では String データ型の変数を作成し、その変数にリテラルストリング値を割り当てます。
var albumName:String = "Three for the money";

この例が示すように、ActionScript では二重引用符または一重引用符でテキストを囲むことにより、ストリング値を表すことができます。次に、ストリングの例をいくつか示します。
"Hello""555-7649""http://www.adobe.com/"

ActionScript でテキストを操作する場合は常に、ストリング値を操作することになります。ActionScript の String クラス
は、テキスト値を操作するために使用できるデータ型です。String インスタンスは、その他の多くの ActionScript クラス内
で、プロパティ、メソッドパラメーターなどにより頻繁に使用されます。
重要な概念と用語
次の参照リストに、ストリングに関連する重要な用語を示します。

ASCII コンピュータープログラムでテキストの文字および記号を表すための体系。ASCII 体系では、26 文字の英字アルファベットに加えて、限定的な追加文字セットがサポートされます。
文字 テキストデータの最小単位（単一の文字または記号）。
連結 複数のストリング値を相互に結合し、あるストリング値を別のストリング値の末尾に追加することにより、新しいストリング値を作成します。
空のストリング テキスト、空白、その他の文字を含まないストリング。"" として記述されます。空のストリング値は、null値を持つ String 変数とは異なります。null の String 変数は、String インスタンスが未割り当てなのに対して、空のストリ
ングは文字を含まない値のインスタンスを含む変数です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

11

ストリングの操作

ストリング テキスト値（文字シーケンス）。
ストリングリテラル（「リテラルストリング」）コード内で明示的に記述されるストリング値。二重引用符または一重引用符
で囲まれたテキスト値として記述します。
サブストリング 別のストリングの一部であるストリング。

Unicode コンピュータープログラムでテキストの文字および記号を表すための標準体系。Unicode 体系では、任意の文字
記述システムの任意の文字を使用できます。

ストリングの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
String クラスは ActionScript 3.0 でストリング（テキスト）データを表すために使用されます。ActionScript ストリング
は ASCII と Unicode 文字の両方をサポートしています。ストリングを作成する最も簡単な方法は、ストリングリテラルを使用することです。ストリングリテラルを宣言するには、垂直の二重引用符（"）または一重引用符（'）を使用します。例えば、次の 2 つのストリングは同等です。
var str1:String = "hello";
var str2:String = 'hello';

次のように new 演算子を使用してストリングを宣言することもできます。
var str1:String = new String("hello");var str2:String = new String(str1);
var str3:String = new String();// str3 == ""次の 2 つのストリングは等価です。
var str1:String = "hello";
var str2:String = new String("hello");

一重引用符（'）の区切り文字で記述されているストリングリテラル内で一重引用符（'）を使用するには、エスケープ文字として円記号（¥）を使用します。同様に、二重引用符（"）の区切り文字で記述されているストリングリテラル内で二重引用符（"）を使用するには、エスケープ文字として円記号（¥）を付けます。次の 2 つのストリングは等価です。
var str1:String = "That's \"A-OK\"";var str2:String = 'That\'s "A-OK"';

次のように、ストリングリテラル内に存在する一重引用符または二重引用符に基づいて一重引用符または二重引用符を使用するように選択することができます。
var str1:String = "ActionScript <span class='heavy'>3.0</span>";var str2:String = '<item id="155">banana</item>';

ActionScript では、垂直の一重引用符（'）と右向きまたは左向きの引用符（' または ' ）は区別されるので注意してください。この点は二重引用符についても同様です。ストリングリテラルを囲む場合は垂直の引用符を使用する必要があります。別の場所からコピーしたテキストを ActionScript にペーストする際は、正しい文字になっているか確認してください。
次の表に示すとおり、エスケープ文字として円記号（¥）を使用して、ストリングリテラル内の他の文字を定義することができます。
エスケープシーケンス文字¥b

バックスペース

¥f

改ページ

¥n

改行

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

12

ストリングの操作

エスケープシーケンス

文字

¥r

復帰文字

¥t

タブ

¥unnnn16 進数値 nnnn で指定される文字コードを持つ Unicode 文字。例えば、¥u263a はスマイル記号です。

¥¥xnn

16 進数値 nn で指定した文字コードの ASCII 文字

¥'

一重引用符

¥"

二重引用符

¥¥

単一の円記号

length プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
すべてのストリングには length プロパティがあります。これは、ストリングの文字数と同じ値になります。
var str:String = "Adobe";
trace(str.length);// output: 5

次のとおり、空のストリングと null ストリングの length はいずれも 0 です。
var str1:String = new String();
trace(str1.length);// output: 0
str2:String = '';trace(str2.length);// output: 0

ストリング内の文字の操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ストリング内のすべての文字が、ストリング内のインデックス位置を持っています（整数）。先頭の文字を指すインデックス
位置は 0 です。例えば、次のストリング内で y という文字は 0 の位置にあり、w という文字は 5 の位置にあります。
"yellow"

この例に示すように、charAt() メソッドおよび charCodeAt() メソッドを使用して、ストリング内の様々な位置にある個々の文字を調べることができます。
var str:String = "hello world!";for (var i:int = 0; i < str.length; i++){trace(str.charAt(i), "-", str.charCodeAt(i));}

このコードを実行すると、次の出力が生成されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

13

ストリングの操作

h - 104e - 101l - 108l - 108o - 111- 32
w - 119o - 111r - 114l - 108
d - 100! - 33

次の例に示すように、fromCharCode() メソッドを使用して、ストリングを定義する文字コードを使用することもできます。
var myStr:String = String.fromCharCode(104,101,108,108,111,32,119,111,114,108,100,33);// Sets myStr to "hello world!"

ストリングの比較
Flash Player 9 以降、Adobe AIR 1.0 以降
ストリングを比較するために演算子 <、<=、!=、==、=>、および > を使用できます。これらの演算子は、次の例のように if
や while などの条件ステートメントで使用できます。
var str1:String = "Apple";var str2:String = "apple";if (str1 < str2){
trace("A < a, B < b, C < c, ...");}

これらの演算子をストリングで使用する場合、ActionScript は、次のように文字を左から右へ比較することにより、ストリ
ング内の各文字の文字コード値を考慮します。
trace("A" < "B"); // true
trace("A" < "a"); // true
trace("Ab" < "az"); // true
trace("abc" < "abza"); // true

次の例に示すように、== と != 演算子を使用して、ストリングを相互に比較し、ストリングを他の型のオブジェクトと比較します。
var str1:String = "1";
var str1b:String = "1";
var str2:String = "2";trace(str1 == str1b); // true
trace(str1 == str2); // false
var total:uint = 1;
trace(str1 == total); // true

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

14

ストリングの操作

他のオブジェクトのストリング表現の取得
Flash Player 9 以降、Adobe AIR 1.0 以降
任意の種類のオブジェクトのストリング表現を取得することができます。このために、すべてのオブジェクトには toString()
メソッドが用意されています。
var n:Number = 99.47;
var str:String = n.toString();// str == "99.47"

String オブジェクトとストリング以外のオブジェクトに対して + 連結演算子を使用する場合、toString() メソッドは必要ありません。連結の詳細については、次のセクションを参照してください。

String() グローバル関数は、指定されたオブジェクトに対し、toString() メソッドを呼び出すオブジェクトが返す値と同じ値を返します。

ストリングの連結
Flash Player 9 以降、Adobe AIR 1.0 以降
ストリングの連結とは、2 つのストリングを 1 つのストリングに順番に結合することです。例えば、次のように + 演算子を使用すると 2 つのストリングを連結できます。
var str1:String = "green";var str2:String = "ish";var str3:String = str1 + str2; // str3 == "greenish"

また、次の例に示すように += 演算子を使用しても同じ結果が得られます。
var str:String = "green";
str += "ish"; // str == "greenish"

さらに、次のように String クラスの concat() メソッドを使用して連結を実行する方法もあります。
var str1:String = "Bonjour";var str2:String = "from";
var str3:String = "Paris";var str4:String = str1.concat(" ", str2, " ", str3);// str4 == "Bonjour from Paris"+ 演算子（または += 演算子）を使用して、String オブジェクトとストリング以外のオブジェクトとを連結する場合、ActionScript では、次のようにストリングでないオブジェクトが String オブジェクトに自動変換され、それから式が評価されます。
var str:String = "Area = ";var area:Number = Math.PI * Math.pow(3, 2);
str = str + area; // str == "Area = 28.274333882308138"

ただし、次のように括弧をグループ化に使用すれば、+ 演算子のコンテキストを提供することができます。
trace("Total: $" + 4.55 + 1.45); // output: Total: $4.551.45
trace("Total: $" + (4.55 + 1.45)); // output: Total: $6

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

15

ストリングの操作

ストリング内に含まれるサブストリングおよびパターンの検索Flash Player 9 以降、Adobe AIR 1.0 以降
サブストリングとは、ストリング内の一部を構成する連続した文字です。例えば、ストリング「abc」のサブストリングは、「」、「a」、「ab」、「abc」、「b」、「bc」、「c」です。ストリング内のサブストリングは ActionScript のメソッドを使用して抽出できます。
パターンは、ActionScript ではストリングまたは正規表現によって定義されます。例えば、次の正規表現は、文字 A、B、C の後に数字が続く特定のパターンを定義します（スラッシュは正規表現の区切り記号です）。
/ABC\d/ActionScript には、ストリング内のパターンを検索し、一致するパターンが見つかった場合に、置換サブストリングと置き換えるメソッドが用意されています。それらのメソッドについては、次のセクションで説明します。
正規表現を使用すると複雑なパターンを定義できます。詳しくは、72 ページの「正規表現の使用」を参照してください。

サブストリングの文字位置による検索
Flash Player 9 以降、Adobe AIR 1.0 以降
substr() と substring() メソッドは似ています。いずれもストリング内のサブストリングを戻り値として返すメソッドです。また、指定するパラメーターは 2 つであり、どちらのメソッドでも、最初のパラメーターは、与えられたストリングの開始文
字の位置です。しかし、substr() メソッドの場合はサブストリングの長さを第 2 パラメーターで指定するのに対し、substring() メソッドの場合はサブストリングの終了位置を第 2 パラメーターで指定します（終了位置にある文字そのものは戻り値に含まれません）。2 つのメソッドの違いを確認できる例を次に示します。
var str:String = "Hello from Paris, Texas!!!";
trace(str.substr(11,15)); // output: Paris, Texas!!!
trace(str.substring(11,15)); // output: Parislice() メソッドの機能は、substring() メソッドに似ています。2 つの負でない整数をパラメーターとして与えた場合、両方のメソッドは完全に同じ働きをします。しかし、slice() メソッドではパラメーターに負の整数を指定することもでき、その場合は、ストリングの末尾を基準として文字の位置を指定したことになります。例を次に示します。
var str:String = "Hello from Paris, Texas!!!";
trace(str.slice(11,15)); // output: Pari
trace(str.slice(-3,-1)); // output: !!
trace(str.slice(-3,26)); // output: !!!
trace(str.slice(-3,str.length)); // output: !!!
trace(str.slice(-8,-3)); // output: Texas

slice() メソッドのパラメーターには、負でない整数と負の整数を組み合わせて指定できます。

一致するサブストリングの文字位置の検索
Flash Player 9 以降、Adobe AIR 1.0 以降
次の例に示すように、indexOf() と lastIndexOf() メソッドを使用して、ストリング内の一致するサブストリングの位置を特定することができます。
var str:String = "The moon, the stars, the sea, the land";trace(str.indexOf("the")); // output: 10

indexOf() メソッドでは大文字と小文字が区別されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

16

ストリングの操作

次のように第 2 パラメーターを指定すると、ストリング内で検索を開始する位置を示すことができます。
var str:String = "The moon, the stars, the sea, the land"
trace(str.indexOf("the", 11)); // output: 21

lastIndexOf() は、ストリング内に一致するサブストリングが最後に出現する位置を検索するメソッドです。
var str:String = "The moon, the stars, the sea, the land"
trace(str.lastIndexOf("the")); // output: 30

lastIndexOf() メソッドで次のように第 2 パラメーターを指定すると、ストリング内の指定したインデックス位置から先頭に向かって（右から左へ）検索が実行されます。
var str:String = "The moon, the stars, the sea, the land"
trace(str.lastIndexOf("the", 29)); // output: 21

区切り記号で分割されたサブストリング配列の作成
Flash Player 9 以降、Adobe AIR 1.0 以降
split() メソッドを使用して、区切り記号に基づいて分割されたサブストリングの配列を作成できます。例えば、カンマ区切
りやタブ区切りのデータを含んだストリングを複数のストリングに分割できます。
次の例では、アンパサンド（&）を区切り文字としてストリングを分割し、サブストリングの配列を作成します。
var queryStr:String = "first=joe&last=cheng&title=manager&StartDate=3/6/65";
var params:Array = queryStr.split("&", 2); // params == ["first=joe","last=cheng"]

split() メソッドの第 2 パラメーターはオプションで、返される配列の最大サイズを指定します。
区切り文字には、次のように正規表現を指定することもできます。
var str:String = "Give me\t5."var a:Array = str.split(/\s+/); // a == ["Give","me","5."]

詳しくは、72 ページの「正規表現の使用」および『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

ストリング内のパターンの検索およびサブストリングの置換Flash Player 9 以降、Adobe AIR 1.0 以降
String クラスには、ストリング内のパターンを扱う次のメソッドがあります。

• match() および search() メソッドでは、パターンに一致するサブストリングを検索できます。
• replace() メソッドでは、パターンに一致するサブストリングを検索し、該当する部分を指定のサブストリングに置換できます。
それらのメソッドについては、次のセクションで説明します。
これらのメソッドで使用するパターンは、ストリングまたは正規表現によって定義できます。正規表現について詳しくは、

72 ページの「正規表現の使用」を参照してください。
一致するサブストリングの検索

search() メソッドは、この例に示すように、特定のパターンに一致する最初のサブストリングのインデックス位置を返します。
var str:String = "The more the merrier.";// (This search is case-sensitive.)
trace(str.search("the")); // output: 9

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

17

ストリングの操作

検索するパターンは、次の例に示すように、正規表現を使用して定義することもできます。
var pattern:RegExp = /the/i;var str:String = "The more the merrier.";
trace(str.search(pattern)); // 0

ストリングの先頭にある文字のインデックス位置は 0 なので、この場合は trace() メソッドで 0 が出力されます。正規表現のi フラグを設定することで、大文字と小文字を区別せずに検索を実行しています。
search() メソッドは、一致するサブストリングを 1 つだけ検索してその開始位置のインデックスを返します。たとえ g（グローバル）フラグを設定しても、複数の一致箇所を検索することはありません。
次の例では、より複雑な正規表現を指定することで、二重引用符に囲まれたストリングを検索します。
var pattern:RegExp = /"[^"]*"/;
var str:String = "The \"more\" the merrier.";
trace(str.search(pattern)); // output: 4
str = "The \"more the merrier.";
trace(str.search(pattern)); // output: -1// (Indicates no match, since there is no closing double quotation mark.)

match() メソッドの機能も search() メソッドと似ており、パターンに一致するサブストリングを検索する点は同じです。ただし、次のように正規表現パターンでグローバルフラグを指定すると、match() の場合は一致したサブストリングの配列を返します。
var str:String = "bob@example.com, omar@example.org";
var pattern:RegExp = /\w*@\w*\.[org|com]+/g;
var results:Array = str.match(pattern);

results 配列は、次のように設定されます。
["bob@example.com","omar@example.org"]

正規表現について詳しくは、72 ページの「正規表現の使用」を参照してください。
一致するサブストリングの置換
次の例に示すように、replace() メソッドを使用して、ストリング内の指定されたパターンを検索し、一致するパターンを指定された置換ストリングに置き換えることができます。
var str:String = "She sells seashells by the seashore.";var pattern:RegExp = /sh/gi;
trace(str.replace(pattern, "sch")); //sche sells seaschells by the seaschore.

この例では、i（ignoreCase）フラグが正規表現で設定されているので、一致する文字列は大文字と小文字を区別せず、g（global）フラグが設定されているので、複数の一致が置き換えられます。詳しくは、72 ページの「正規表現の使用」を参照
してください。
置換ストリングには、次の $ 置換コードを含めることができます。$ 置換コードを記述した位置には、次の表に示す置換テ
キストが挿入されます。
$ コード

置換テキスト$$$$&パターンに一致したサブストリング$`

ストリングのうち、パターンに一致したサブストリングより前にある部分。このコードで使用する記号は、曲がっていな
い左側一重引用符（`）です。垂直の一重引用符（'）や、曲がった左側一重引用符（' ）ではありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

18

ストリングの操作$ コード

置換テキスト
ストリングのうち、パターンに一致したサブストリングより後にある部分。このコードで使用する記号は、垂直の一重引$'用符（' ）です。
パターン内のグループ化括弧によってキャプチャされた n 番目のサブストリング。n は 1 桁の数字（1 〜 9）であり、$n$nの後に 10 進数字は続きません。

$nn

括弧指定されたグループの nn 番目にキャプチャされた一致です。nn は 2 桁の 10 進数字（01 〜 99）です。nn 番目のキャプチャが未定義の場合、置換テキストは空のストリングになります。

例えば、次の例は、1 番目および 2 番目に一致したキャプチャグループを表す $2 および $1 置換コードを使用する方法を示しています。
var str:String = "flip-flop";
var pattern:RegExp = /(\w+)-(\w+)/g;
trace(str.replace(pattern, "$2-$1")); // flop-flip

replace() メソッドの第 2 パラメーターには関数を指定することもできます。その場合は、一致したテキストが、指定した関数の戻り値によって置換されます。
var str:String = "Now only $9.95!";
var price:RegExp = /\$([\d,]+.\d+)+/i;
trace(str.replace(price, usdToEuro));function usdToEuro(matchedSubstring:String, capturedMatch1:String,
str:String):String{
var usd:String = capturedMatch1;
usd = usd.replace(",", "");
var exchangeRate:Number = 0.853690;
var euro:Number = parseFloat(usd) * exchangeRate;
const euroSymbol:String = String.fromCharCode(8364);
return euro.toFixed(2) + " " + euroSymbol;}

index:int,

replace() メソッドの 2 番目のパラメーターとして関数を使用する場合、次の引数が関数に渡されます。

•

ストリング内の一致する部分。

•

グループ化括弧によってキャプチャされる一致。この方法で渡される引数の数は、括弧内のパターンとの一致数によって異なります。括弧内のパターンとの一致数は、関数コード内の arguments.length - 3 を確認して特定することができます。

•

ストリング内で一致部分が始まる場所のインデックス位置。

•

ストリング全体。

ストリングの大文字／小文字の変換
Flash Player 9 以降、Adobe AIR 1.0 以降
次の例に示すように、toLowerCase() メソッドと toUpperCase() メソッドは、ストリング内のアルファベット文字を大文字または小文字にそれぞれ変換します。
var str:String = "Dr. Bob Roberts, #9."
trace(str.toLowerCase()); // dr. bob roberts, #9.
trace(str.toUpperCase()); // DR. BOB ROBERTS, #9.

これらのメソッドを実行しても、ソースストリングは変更されません。元のストリング自体を変換するには、次のコードを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

19

ストリングの操作

str = str.toUpperCase();

これらのメソッドは、a 〜 z と A 〜 Z だけでなく、次のように拡張文字でも動作します。
var str:String = "José Barça";
trace(str.toUpperCase(), str.toLowerCase()); // JOSÉ BARÇA josé barça

ストリングの例：ASCII アート
Flash Player 9 以降、Adobe AIR 1.0 以降
ここでは ASCII アートの例を使って、ActionScript 3.0 の String クラスの操作について次のような機能を示します。

• String クラスの split() メソッドを使用して、文字区切りのストリング（タブ区切りテキストファイルのイメージ情報）
から値を抽出します。

• split()、連結、および substring() と substr() の使用によるストリング部分の抽出など、何とおりものストリング操作テクニックを使用して、イメージタイトルの各単語の先頭文字を大文字にします。

• getCharAt() メソッドを使用して、ストリングから 1 文字を取得します（グレースケールビットマップ値に対応する
ASCII 文字を決定します）。
•

ストリングの連結を使用して、イメージの ASCII アート表現を一度に 1 文字ずつ構築します。

ASCII アートという用語はイメージのテキスト表現を指し、イメージは Courier New 文字のような等幅フォント文字のグリッドで描画されます。次のイメージは、アプリケーションが生成した ASCII アートの例を示しています。

ASCII アートのグラフィックを右側に示してあります。

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。ASCIIArt アプリケーションのファイルは、Samples/AsciiArt フォルダーにあります。このアプリケーションは次のファイルで構成されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

20

ストリングの操作

ファイル

説明

Flash（FLA）または Flex（MXML）のメインアプリケーション

AsciiArtApp.mxml

ファイル。

または

AsciiArtApp.fla
com/example/programmingas3/asciiArt/AsciiArtBuilder.as

テキストファイルからのイメージメタデータの抽出、イメージのロード、イメージからテキストへの変換プロセスの管理など、ア
プリケーションのメイン機能を提供するクラス。

com/example/programmingas3/asciiArt/BitmapToAsciiConverter.as

イメージデータをストリングに変換するためのparseBitmapData() メソッドを提供するクラス。

com/example/programmingas3/asciiArt/Image.ascom/example/programmingas3/asciiArt/ImageInfo.as

ロードしたビットマップイメージを表すクラス。
タイトル、イメージファイル URL など、ASCII アートイメージのメタデータを表すクラス。

image/

アプリケーションが使用するイメージを含むフォルダー。

txt/ImageData.txt

アプリケーションがロードするイメージに関する情報を含む、タブ区切りのテキストファイル。

タブ区切りの値の抽出
Flash Player 9 以降、Adobe AIR 1.0 以降
この例では、アプリケーションデータをアプリケーション自体とは別に格納する一般的な慣習に従っています。そのようにしておくと、例えば、別のイメージが追加またはイメージのタイトルが変更されたときなど、データが変更された場合にSWF ファイルを再作成する必要がありません。この場合、イメージタイトル、実際のイメージファイルの URL、およびイメージの操作に使用する一部の値を含むイメージメタデータは、テキストファイル（プロジェクトの txt/ImageData.txt
ファイル）に格納されています。実際のテキストファイルの中身は次のようになっています。
FILENAMETITLEWHITE_THRESHHOLDBLACK_THRESHHOLD
FruitBasket.jpgPear, apple, orange, and bananad810
Banana.jpgA picture of a bananaC820
Orange.jpgorangeFF20
Apple.jpgpicture of an apple6E10

ファイルは特定のタブ区切り形式を使用します。最初の行はヘッダー行です。残りの行は、ロードするビットマップごとに次のデータを含みます。

•

ビットマップのファイル名•

ビットマップの表示名•

ビットマップの白しきい値および黒しきい値。これらは 16 進値で、この値を超えた場合および下回った場合にピクセルは完全に白または黒と見なされます。

アプリケーションが起動するとすぐに、AsciiArtBuilder クラスは、AsciiArtBuilder クラスの parseImageInfo() メソッドから次のコードを使用して、表示するイメージの「スタック」を作成するためにテキストファイルの内容をロードして解析します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

21

ストリングの操作

var lines:Array = _imageInfoLoader.data.split("\n");var numLines:uint = lines.length;
for (var i:uint = 1; i < numLines; i++){var imageInfoRaw:String = lines[i];...
if (imageInfoRaw.length > 0){// Create a new image info record and add it to the array of image info.
var imageInfo:ImageInfo = new ImageInfo();// Split the current line into values (separated by tab (\t)// characters) and extract the individual properties:
var imageProperties:Array = imageInfoRaw.split("\t");imageInfo.fileName = imageProperties[0];imageInfo.title = normalizeTitle(imageProperties[1]);imageInfo.whiteThreshold = parseInt(imageProperties[2], 16);
imageInfo.blackThreshold = parseInt(imageProperties[3], 16);
result.push(imageInfo);}}

テキストファイルのすべての内容が単一の String インスタンス _imageInfoLoader.data プロパティに含まれます。改行（"¥n"）をパラメーターとして split() メソッドを使用すると、String インスタンスは、要素がテキストファイルの各行になる

Array（lines）に分割されます。次に、ループを使用して各行の操作を行います（実際の内容ではなくヘッダーのみを含む
先頭行は除く）。ループ内で、split() メソッドをもう一度使用して、単一行の内容を値セット（imageProperties という Array
オブジェクト）に分割します。各行の値はタブ文字で区切られるため、この場合の split() メソッドで使用するパラメーター
はタブ文字（"¥t"）です。

ストリングメソッドの使用によるイメージタイトルの正規化
Flash Player 9 以降、Adobe AIR 1.0 以降
このアプリケーションの設計に関する決定事項の 1 つは、すべてのイメージタイトルを標準形式で表示し、そのとき各単語の先頭文字を大文字にします（英語タイトルで先頭大文字にしないのが一般的ないくつかの単語は除く）。適切に整形済みのタイトルがテキストファイルに含まれると見なすのではなく、テキストファイルからの抽出時にタイトルを整形します。
以前のコードリストでは、個々のイメージメタデータ値を抽出する一部として、次のコード行が使用されています。
imageInfo.title = normalizeTitle(imageProperties[1]);このコードでは、テキストファイルからのイメージのタイトルが、ImageInfo オブジェクトに格納される前にnormalizeTitle() メソッドを介して渡されます。
private function normalizeTitle(title:String):String{
var words:Array = title.split(" ");var len:uint = words.length;
for (var i:uint; i < len; i++){words[i] = capitalizeFirstLetter(words[i]);}return words.join(" ");}このメソッドは split() メソッドを使用して、タイトルを（空白文字で区切られた）個々の単語に分割し、capitalizeFirstLetter() メソッドを介して各単語を渡し、次に Array クラスの join() メソッドを使用して、単語をもう一度 1 つのストリングに結合します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

22

ストリングの操作

名前が示すとおり、capitalizeFirstLetter() メソッドは実際に各単語の先頭文字を大文字にする働きがあります。
/*** Capitalizes the first letter of a single word, unless it's one of* a set of words that are normally not capitalized in English.
*/
private function capitalizeFirstLetter(word:String):String{
switch (word){case "and":case "the":case "in":case "an":case "or":case "at":case "of":case "a":// Don't do anything to these words.
break;
default:// For any other word, capitalize the first character.
var firstLetter:String = word.substr(0, 1);
firstLetter = firstLetter.toUpperCase();var otherLetters:String = word.substring(1);word = firstLetter + otherLetters;}
return word;}

英語では、タイトルの各単語が「and」、「the」、「in」、「an」、「or」、「at」、「of」、または「a」のいずれかである場合、その先頭の文字は大文字にされません。これは簡易版の規則です。このロジックを実行するために、最初に switch ステートメン
トを使用して、先頭を大文字にしない単語のいずれかであるかどうかを確認します。先頭を大文字にしない単語の場合は、switch ステートメントからジャンプします。一方、先頭を大文字にする単語の場合は、次のように何ステップかでそれを行います。

1 substr(0, 1) を使用して、単語の先頭文字を抽出します。この抽出では、第 1 パラメーター 0 が指定するストリングの先頭文字、つまりインデックス 0 の文字から開始するサブストリングを抽出します。サブストリングは、第 2 パラメーター 1
が指定する 1 文字長になります。

2 toUpperCase() メソッドを使用して、その文字を大文字にします。
3 substring(1) を使用して、元の単語の残りの文字を抽出します。この抽出では、インデックス 1（第 2 文字）から開始して、ストリングの末尾（substring() メソッドの第 2 パラメーターの省略が示す）までのサブストリングを抽出します。

4 firstLetter + otherLetters の文字連結を使用して、新しく大文字にした先頭文字と残りの文字を結合することによって、最終的な単語を作成します。

ASCII アートテキストの生成
Flash Player 9 以降、Adobe AIR 1.0 以降
BitmapToAsciiConverter クラスは、ビットマップイメージを ASCII テキスト表現に変換する機能を提供します。このプ
ロセスは、次に一部を示してある parseBitmapData() メソッドが実行します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

23

ストリングの操作

var result:String = "";// Loop through the rows of pixels top to bottom:
for (var y:uint = 0; y < _data.height; y += verticalResolution){// Within each row, loop through pixels left to right:for (var x:uint = 0; x < _data.width; x += horizontalResolution){...
// Convert the gray value in the 0-255 range to a value// in the 0-64 range (since that's the number of "shades of// gray" in the set of available characters):
index = Math.floor(grayVal / 4);
result += palette.charAt(index);}
result += "\n";}return result;

このコードは、ビットマップイメージの ASCII アート版を作成するために使用する result という名前の String インスタン
スを最初に定義します。次に、ソースビットマップイメージについて個々のピクセルのループ処理をします。何とおりかの
カラー操作テクニックを使用して（ここでは簡略化のために省略）、個々のピクセルの赤、緑、青のカラー値を単一のグレー
スケール値（0 から 255 までの数値）に変換します。続いて例に示してあるように、その値を 4 で割り、0 〜 63 スケールの値に変換します。値は、変数 index に格納されます。0 〜 63 スケールを使用するのは、このアプリケーションで使用する利用可能な ASCII 文字の「パレット」に格納される値の数が 64 のためです。文字パレットは、BitmapToAsciiConverter ク
ラスの String インスタンスとして定義されています。
// The characters are in order from darkest to lightest, so that their// position (index) in the string corresponds to a relative color value// (0 = black).
private static const palette:String = "@#$%&8BMW*mwqpdbkhaoQ0OZXYUJCLtfjzxnuvcr[]{}1()|/?Il!i><+_~-;,. ";index 変数は、ビットマップイメージの現在のピクセルに対応するパレット内の ASCII 文字を定義するので、この文字はcharAt() メソッドを使用して palette ストリングから取得されます。続いて、連結代入演算子（+=）を使用して、result
String インスタンスに追加されます。さらに、各行のピクセルの最後で result String の最後に改行文字を連結して、文字ピ
クセルの新しい行を作成するために行の折り返しを強制します。

最終更新日 2015/10/14

24

第 3 章：配列の操作
Flash Player 9 以降、Adobe AIR 1.0 以降
配列を使用すると、1 つのデータ構造の中に複数の値を格納できます。配列にはインデックス配列と結合配列の 2 種類があります。値の格納場所を指定する方法として、インデックス配列では単純な整数のインデックスを使用し、結合配列では任意のキーを使用します。また、配列の個々の要素そのものが配列であるような多次元の配列も作成できます。最後に、すべての要素が同じデータ型のインスタンスである配列に対してベクターを使用できます。

関連項目

Array
Vector配列の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
多くの場合、プログラミングでは単一のオブジェクトではなく、アイテムのセットで作業する必要があります。例えば、
ミュージックプレーヤーアプリケーションで再生を待機する曲のリストがあるとします。このリストのそれぞれの曲に対して、個別の変数を作成したくはないはずです。すべての曲のオブジェクトを単一のバンドルにまとめ、グループとして操作できる方が望ましいでしょう。
配列は、曲のリストなど、一連のアイテムのコンテナとして機能するプログラミング要素です。最も一般的な場合、配列内のすべてのアイテムは同じクラスのインスタンスとして使用されますが、これは ActionScript の要件ではありません。配列
内の個別のアイテムを配列の要素と言います。配列は、変数のファイル用引き出しと見なすことができます。変数は、配列の要素として追加できます。これは、ファイル用引き出しにフォルダーを挿入することに似ています。別の位置に引き出し全体を運ぶことと同じように、配列を 1 つの変数として操作できます。ある 1 つの情報を探してフォルダーを 1 つずつ見ていくように、変数をグループとして操作できます。また、引き出しを開いて単一のフォルダーを選択するように、変数に個別にアクセスすることもできます。
例えば、ユーザーが複数の曲を選択してそれをプレイリストに追加できるミュージックプレーヤーアプリケーションを作成する場合を考えてください。ActionScript コードで、パラメーターとして単一の配列を受け取る addSongsToPlaylist() という名前のメソッドを作成することにします。リストに追加する曲の数にかかわらず（少数または多数の場合、あるいは 1 つだけの場合）、addSongsToPlaylist() メソッドを 1 回だけ呼び出して、Song オブジェクトを含む配列を渡すだけで済みます。
そして addSongsToPlaylist() メソッド内で、配列要素（曲）を 1 つずつループし、実際にプレイリストに追加できます。

ActionScript 配列の最も一般的なタイプに、インデックス配列があります。インデックス配列では、各アイテムが番号付きスロットに格納されます（インデックスと呼ばれます）。アイテムにはアドレスなどの番号を使用してアクセスします。インデックス配列は、大半のプログラミングニーズを満たします。Array クラスは、インデックス配列を表すために使用される一般的なクラスです。
多くの場合、インデックス配列は同じ型の複数のアイテム（同じクラスのインスタンスであるオブジェクト）を格納するために使用されます。Array クラスには、このクラスが含むアイテムの型を制限する手段がありません。Vector クラスは、イ
ンデックス配列の 1 つの型であり、単一の配列内のアイテムはすべて同じ型です。また、Array インスタンスではなくVector インスタンスを使用すると、パフォーマンスが改善されるだけでなく、その他の点でもメリットがあります。
Vector クラスは、Flash Player 10 および Adobe AIR 1.5 以降で使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

25

配列の操作

インデックス配列の特別な使用方法として多次元配列があります。多次元配列は、要素がインデックス配列（つまり、他の要素を含む）になっているインデックス配列です。
もう 1 つのタイプの配列に結合配列があります。この配列では、個別の要素を識別するために数値インデックスの代わりにストリングのキーを使用します。最後に、ActionScript 3.0 にはディクショナリを表す Dictionary クラスも含まれています。ディクショナリはオブジェクトの任意の型をキーとして使用して要素を区別できる配列です。
重要な概念と用語
次の参照リストに、配列およびベクター処理ルーチンのプログラミングで使用される重要な用語を示します。
配列 複数のオブジェクトをグループ化するためのコンテナとして役立つオブジェクト。
配列アクセス（[]）演算子 配列要素を一意に識別するインデックスまたはキーを囲む一組の角括弧。このシンタックスは配列変数名の後に使用され、配列全体ではなく配列の 1 つの要素を指定します。
結合配列 個別の要素を識別するためにストリングキーを使用する配列。
ベース型 Vector インスタンスを格納できるオブジェクトのデータ型。
辞書 アイテムがキーおよび値と呼ばれるペアのオブジェクトから構成される配列。キーは、単一の要素を識別するために数
値インデックスの代わりに使用します。
エレメント 配列内の単一のアイテム。
索引 インデックス配列内の単一の要素を識別するための「番号アドレス」。
インデックス配列 各要素を番号付きの位置に保存し、個別の要素を識別するために番号（インデックス）を使用する標準タイプの配列。
キー 結合配列またはディクショナリ内で単一要素を識別するためのストリングまたはオブジェクト。
多次元配列 単一の値ではなく配列であるアイテムを含む配列。

T ベース型が何であるかに関係なく、Vector インスタンスのベース型を表すこのマニュアルで使用する標準の表記規則。T
表記規則は、型パラメーターの説明に示すように、クラス名を表すために使用されます (「T」は「データ型」の「型」を表します )。
型パラメーター Vector クラス名で使用され、ベクターのベース型を指定するシンタックス（Vector クラスが格納するオブジェクトのデータ型）。シンタックスは、ピリオド（.）とその後に続く山括弧（<>）で囲まれたデータ型名で構成されます。
これらをまとめると、Vector.<T> のようになります。本マニュアルでは、型パラメーターで指定されるクラスは、通常、Tとして表されます。

Vector すべての要素が同じデータ型のインスタンスである配列の型。

インデックス配列
Flash Player 9 以降、Adobe AIR 1.0 以降
インデックス配列では、格納した一連の値に、符号なし整数値によるインデックスを指定してアクセスします。配列内の先頭の要素は常にインデックス 0 で示され、それに続く個々の要素は順に 1 ずつ大きい数のインデックスで示されます。

ActionScript 3.0 では、Array クラスおよび Vector クラスの 2 つのクラスがインデックス配列として使用されます。
インデックス配列のインデックスに使用する数値は、符号なし 32 ビット整数です。インデックス配列の最大サイズは 232 - 1（4,294,967,295）です。この最大サイズより大きい配列を作成しようとすると、ランタイムエラーが発生します。
インデックス配列の個別の要素にアクセスするには、配列アクセス（[]）演算子を使用して、アクセスする要素のインデックスの位置を指定します。例えば、次のコードでは、songTitles という名前のインデックス配列の 1 番目の要素（インデック
ス 0 の要素）を表します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

26

配列の操作

songTitles[0]配列変数名とその後に続く角括弧で囲まれたインデックスの組み合わせは、単一の識別子として機能します（つまり、変数
名として可能などのような組み合わせでも使用できます）。代入ステートメントの左側に名前とインデックスを使用して、インデックス配列要素に値を割り当てることができます。
songTitles[1] = "Symphony No. 5 in D minor";

同様に、代入ステートメントの右側に名前とインデックスを使用して、インデックス配列要素の値を取得できます。
var nextSong:String = songTitles[2];また、明示的な値を指定するのではなく、角括弧で囲まれた変数を使用することもできます（変数は、uint、正の int、正の整数の Number インスタンスなど、負でない整数値を含む必要があります）。このテクニックは、一般的に、インデック
ス配列内の要素を「ループ処理」して一部またはすべての要素に対して処理を実行する場合に使用されます。このテクニッ
クを説明するコード リストを次に示します。このコードは、oddNumbers という名前の Array オブジェクト内の各値にループを使用してアクセスします。このコードは、trace() ステートメントを使用して、「oddNumber[index] = value」の形式
で各値を出力します。
var oddNumbers:Array = [1, 3, 5, 7, 9, 11];
var len:uint = oddNumbers.length;
for (var i:uint = 0; i < len; i++){trace("oddNumbers[" + i.toString() + "] = " + oddNumbers[i].toString());}

Array クラス
インデックス配列の最初の型は、Array クラスです。Array インスタンスには、あらゆるデータ型の値を格納できます。同一の Array オブジェクトに、異なるデータ型のオブジェクトを格納できます。例えば、単一の Array インスタンスはインデックス 0 にストリング値を、インデックス 1 に Number インスタンスを、インデックス 2 に XML オブジェクトを含むことができます。

Vector クラス
ActionScript 3.0 で使用できるインデックス配列のもう 1 つの型は、Vector クラスです。Vector インスタンスは、型指定配列です。つまり、Vector インスタンスのすべての要素は必ず同一のデータ型を含みます。
注意：Vector クラスは、Flash Player 10 および Adobe AIR 1.5 以降で使用できます。

Vector 変数を宣言するか、または Vector オブジェクトをインスタンス化するときは、ベクターが含むことのできるオブジェクトのデータ型を明示的に指定します。指定したデータ型は、ベクターのベース型と呼ばれます。実行時およびコンパ
イル時（strict モード）には、Vector 要素の値を設定したりベクターから値を取得したりするコードはすべて検証されます。追加または取得されるオブジェクトのデータ型がベクターのベース型と一致しない場合は、エラーが発生します。
データ型の制限に加えて、Vector クラスには Array クラスと区別される次のようなその他の制限があります。

•

ベクターは高密度の配列です。Array オブジェクトは、位置 1 〜 6 に値を含まない場合でも、インデックス 0 および 7 に値を含む場合があります。ただし、ベクターはインデックスに値（つまり、null）を含む必要があります。

•

ベクターは、必要に応じて固定長にすることができます。固定長の場合、ベクターが含む要素数を変更することはできません。

•

ベクターの要素へのアクセスは範囲チェックが行われます。最後の要素（length - 1）より長いインデックスから値を読み取ることはできません。現在の最後のインデックスを越えて値を設定することはできません（つまり、既存のインデックスまたはインデックス [length] でのみ値を設定することができます）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

27

配列の操作

このような制限の結果として、Vector インスタンスには、エレメントがすべて単一クラスのインスタンスとなる Array イ
ンスタンスにはない、次の 3 つの主要な利点があります。

•

パフォーマンス：Array インスタンスを使用するよりも、Vector インスタンスを使用する方が、配列要素のアクセスと繰り返しが高速になります。

•

型の安全性：strict モードでは、コンパイラーでデータ型エラーを特定できます。このようなエラーの例としては、ベク
ターに不正なデータ型の値を割り当てたり、ベクターから値を読み取るときに誤ったデータ型を要求したりすることが挙げられます。実行時には、Vector オブジェクトにデータを追加するときや、このオブジェクトからデータを読み取るときにもデータ型が検証されます。ただし、push() メソッドまたは unshift() メソッドを使用してベクターに値を追加する
場合、引数のデータ型はコンパイル時にチェックされないことに注意してください。これらのメソッドを使用する場合でも、実行時には値が検証されます。

•

信頼性：実行時範囲チェック（固定長チェック）は、Array に対する信頼性を著しく高めます。

これらの追加の制限および利点以外では、Vector クラスは Array クラスに非常によく似ています。Vector オブジェクトのプロパティとメソッドは、配列のプロパティとメソッドと似ており、ほとんどの部分は同じです。多くの場合、すべての要素が同じデータ型を持つ配列を使用するときは、Vector インスタンスが推奨されます。

配列の作成
Flash Player 9 以降、Adobe AIR 1.0 以降
複数のテクニックを使用して、Array インスタンスまたは Vector インスタンスを作成できます。ただし、配列の各型を作成するテクニックは、やや異なります。

Array インスタンスの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
Array オブジェクトは、Array() コンストラクターを呼び出すことによって、または、配列リテラルシンタックスを使用することによって作成します。

Array () コンストラクター関数には 3 つの使用方法があります。第 1 に、パラメーターを指定せずに呼び出した場合、コンストラクターは空の配列を返します。Array クラスの length プロパティを使用すると、配列の要素が 1 つもないことを確認できます。例えば、次のコードは、Array() コンストラクターを引数なしで呼び出しています。
var names:Array = new Array();
trace(names.length); // output: 0

第 2 に、1 個の数値パラメーターだけを指定した場合、Array() コンストラクターではそのパラメーターで指定された長さの配列を作成し、各要素の値を undefined に設定します。指定する引数は、0 〜 4,294,967,295 の値を持つ符号なし整数である
必要があります。例えば、次のコードは、1 個の数値引数を指定して Array() コンストラクターを呼び出しています。
var names:Array = new Array(3);trace(names.length); // output: 3
trace(names[0]); // output: undefined
trace(names[1]); // output: undefined
trace(names[2]); // output: undefined

第 3 に、パラメーターとして要素リストを指定した場合、コンストラクターでは、各パラメーターの値を個々の要素に設定した配列を作成します。次のコードでは、Array() コンストラクターに対し 3 つの引数を指定しています。
var names:Array = new Array("John", "Jane", "David");
trace(names.length); // output: 3
trace(names[0]); // output: John
trace(names[1]); // output: Jane
trace(names[2]); // output: David

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

28

配列の操作

また、配列リテラルを使用して配列を作成することもできます。配列リテラルは、次の例に示すように配列変数に直接割り当てることができます。
var names:Array = ["John", "Jane", "David"];

Vector インスタンスの作成
Flash Player 10 以降、Adobe AIR 1.5 以降
Vector.<T>() コンストラクターを呼び出すことによって Vector インスタンスを作成するときは、ベース型を指定します。
また、Vector.<T>() グローバル関数を呼び出すことによってもベクターを作成できます。その関数は、指定されたオブジェ
クトを Vector インスタンスに変換します。Flash Professional CS5 以降、Flash Builder 4 以降および Flex 4 以降では、

Vector インスタンスの作成にベクターリテラルシンタックスを使用することもできます。
Vector 変数（または、同様に Vector メソッドパラメーターまたは Vector メソッドの戻り型）を宣言するときは、必ずVector 変数のベース型を指定します。また、Vector.<T>() コンストラクターを呼び出すことによって Vector インスタンスを作成するときは、ベース型を指定します。つまり、ActionScript で Vector という用語を使用する場合はいつでも、ベース型が伴うということです。
ベクターのベース型は、型パラメーターシンタックスを使用して指定します。コードでは、Vector という語の直後に型パラメーターが置かれます。例に示すように、このパラメーターは、ドット（.）と、その後に続く山括弧で囲まれた基本クラス名（<>）で構成されます。
var v:Vector.<String>;
v = new Vector.<String>();

この例の最初の行では、変数 v が Vector.<String> インスタンスとして宣言されます。つまり、これは、String インスタンス
のみを保持できるインデックス配列を表します。2 行目では、Vector() コンストラクターを呼び出し、同じ Vector 型（つまり、要素がすべて String オブジェクトである Vector）のインスタンスを作成します。そのオブジェクトは v に割り当てられます。

Vector.<T>() コンストラクターの使用
引数を指定しないで Vector.<T>() コンストラクターを使用すると、空の Vector インスタンスが作成されます。ベクターの
length プロパティを検証することによって、Vector が空であることをテストできます。例えば、次のコードでは、引数を指定しないで Vector.<T>() コンストラクターを呼び出します。
var names:Vector.<String> = new Vector.<String>();trace(names.length); // output: 0

ベクターが最初に必要とする要素の数を事前に把握している場合、ベクター内の要素数を事前に定義できます。特定の数の要素を含むベクターを作成するには、1 番目のパラメーター（length パラメーター）として要素数を渡します。Vector 要素
は空にできないので、要素にはベース型のインスタンスが入力されます。ベース型が null 値を許可する参照型である場合、すべての要素は null を含みます。その他の場合、要素はすべてクラスのデフォルト値を含みます。例えば、uint 変数は nullにできません。その結果、次のコードでは、7 つの要素を含みそれぞれの要素の値が 0 である ages というベクターが作成されます。
var ages:Vector.<uint> = new Vector.<uint>(7);trace(ages); // output: 0,0,0,0,0,0,0

最後に、Vector.<T>() コンストラクターを使用すると、第 2 パラメーター（fixed パラメーター）に true を渡すことによって固定長のベクターを作成することもできます。この場合、指定の数の要素を含むベクターが作成され、要素数は変更できません。ただし、固定長のベクターの要素の値を変更することはできます。
ベクターリテラルシンタックスコンストラクターの使用Flash Professional CS5 以降、Flash Builder 4 以降および Flex 4 以降では、Vector.<T>() コンストラクターに値リストを渡して、ベクターの初期値を指定することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

29

配列の操作

// var v:Vector.<T> = new <T>[E0, ..., En-1 ,];// For example:
var v:Vector.<int> = new <int>[0,1,2,];

このシンタックスには、次の情報が適用されます。

••

末尾のカンマは省略してもかまいません。
配列内の空白のアイテムはサポートされていません。var v:Vector.<int> = new <int>[0,,2,] のようなステートメントは、コンパイラーエラーをスローします。

• Vector インスタンスのデフォルトの長さは指定できません。指定はできませんが、デフォルトの長さは初期化リスト内のエレメントの数と同じになります。

• Vector インスタンスを固定長にするかどうかは指定できません。代わりに、fixed プロパティを使用します。
•

値として渡されたアイテムが指定した型と一致しない場合、データの損失またはエラーが発生する可能性があります。次に、例を示します。
var v:Vector.<int> = new <int>[4.2]; // compiler error when running in strict mode
trace(v[0]); //returns 4 when not running in strict mode

Vector.<T>() グローバル関数の使用
Vector.<T>() およびベクターリテラルシンタックスコンストラクターの他に、Vector.<T>() グローバル関数を使用して、Vector オブジェクトを作成することもできます。Vector.<T>() グローバル関数は変換関数です。Vector.<T>() グローバル関
数を呼び出す場合は、メソッドが返すベクターのべース型を指定します。単一のインデックス配列（Array または Vector
インスタンス）を引数として渡します。次に、このメソッドは指定されたベース型で、ソース配列引数の値を含むベクターを返します。次のコードに、Vector.<T>() グローバル関数を呼び出すシンタックスを示します。
var friends:Vector.<String> = Vector.<String>(["Bob", "Larry", "Sarah"]);Vector.<T>() グローバル関数は、2 段階でデータ型変換を実行します。まず、Array インスタンスがこの関数に渡され、Vector インスタンスが返されます。次に、ソース配列が Array インスタンスまたは Vector インスタンスのどちらであっても、この関数はソース配列の要素をベース型の値に変換します。この変換は標準の ActionScript データ型変換規則を使用します。例えば、次のコードでは、ソース配列のストリング値を結果のベクターの整数に変換します。結果では、最初の値の小数部分（"1.5"）は切り捨てられ、数値以外の 3 番目の値（"Waffles"）は 0 に変換されます。
var numbers:Vector.<int> = Vector.<int>(["1.5", "17", "Waffles"]);trace(numbers); // output: 1,17,0

いずれかのソース要素を変換できない場合、エラーが発生します。
コードで Vector.<T>() グローバル関数が呼び出される場合、ソース配列の要素が指定されているベース型のサブクラスのイ
ンスタンスであるときは、結果のベクターにその要素が追加されます（エラーは発生しません）。Vector.<T>() グローバル関
数の使用は、ベース型 T を持つベクターを T のスーパークラスであるベース型を持つベクターに変換する唯一の方法です。

配列要素の挿入
Flash Player 9 以降、Adobe AIR 1.0 以降
インデックス配列に要素を追加する最も基本的な方法は、配列アクセス（[]）演算子を使用することです。インデックス配
列要素の値を設定するには、代入ステートメントの左側に Array オブジェクトまたは Vector オブジェクトの名前とインデックス番号を使用します。
songTitles[5] = "Happy Birthday";Array または Vector にまだそのインデックスの要素がない場合は、インデックスが作成され、そこに値が格納されます。
そのインデックスに値が既にある場合は、既存の値は新しい値に置き換えられます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

30

配列の操作

Array オブジェクトでは、任意のインデックスに要素を作成できます。ただし、Vector オブジェクトでは、既存のインデックスまたは次に使用可能なインデックスにのみ値を割り当てることができます。次に使用可能なインデックスは、Vector オ
ブジェクトの length プロパティに相当します。Vector オブジェクトに新しい要素を追加する最も安全な方法は、次のようなコードを使用する方法です。
myVector[myVector.length] = valueToAdd;

インデックス配列に要素を挿入する場合は、Array および Vector クラスにある push()、unshift()、および splice() の 3 つのメソッドを使用できます。push() メソッドでは、配列の末尾に 1 つまたは複数の要素を追加します。したがって、push() メ
ソッドで挿入した最後の要素には最も大きいインデックス番号が付きます。unshift() メソッドでは、配列の先頭に 1 つまたは複数の要素を挿入します。したがって、挿入した要素には必ずインデックス番号 0 が付きます。splice() メソッドでは、配列内の指定されたインデックスに任意の数の要素を挿入します。
これら 3 つのメソッドについて使用例を次に示します。太陽に近い順に惑星の名前を格納するために、planets という名前の配列を作成します。まず、push() メソッドを呼び出して、最初の要素 Mars を追加します。次に、unshift() メソッドを呼び出
して、配列の先頭に位置する要素 Mercury を挿入します。最後に、splice() メソッドを呼び出して、Mercury の後、Mars の前に Venus および Earth を挿入します。splice() の第 1 パラメーターとして渡している整数 1 は、挿入先をインデックス 1 の場
所にするという指定です。また、splice() 第 2 パラメーターの整数 0 は、既存の要素を 1 つも削除しないという指定です。さらに、splice() の第 3 および第 4 パラメーターで指定している Venus と Earth は挿入する要素のリストです。
var planets:Array = new Array();
planets.push("Mars"); // array contents: Mars
planets.unshift("Mercury"); // array contents: Mercury,Mars
planets.splice(1, 0, "Venus", "Earth");trace(planets); // array contents: Mercury,Venus,Earth,Marspush() および unshift() メソッドはいずれも、変更後の配列の長さを示す符号なし整数値を返します。splice() は要素の挿入に使用した場合、空の配列を返します。これは奇異な動作のようにも見えますが、splice() メソッドの幅広い用途を考えると理にかなっています。splice() メソッドは配列に要素を挿入する場合だけでなく、配列から要素を削除する場合にも使用でき、削除の場合は、元の配列から削除した要素を格納した配列を返します。
注意：Vector オブジェクトの fixed プロパティが true である場合は、ベクターの要素数の合計を変更することはできません。ここで説明したテクニックを使用して固定長のベクターに新しい要素を追加しようとすると、エラーが発生します。

値の取得と配列要素の削除
Flash Player 9 以降、Adobe AIR 1.0 以降
インデックス配列から要素の値を取得する最も単純な方法は、配列アクセス（[]）演算子を使用する方法です。インデック
ス配列要素の値を取得するには、代入ステートメントの右側に Array オブジェクトまたは Vector オブジェクトの名前とインデックス番号を使用します。
var myFavoriteSong:String = songTitles[3];要素を含まないインデックスを使用して、配列またはベクターから値の取得を試みることは可能です。その場合、Array オ
ブジェクトでは未定義の値が返され、Vector オブジェクトでは RangeError 例外がスローされます。
要素を削除する場合は、Array および Vector クラスにある pop()、shift()、および splice() の 3 つのメソッドを使用できます。pop() メソッドでは、配列の末尾にある 1 個の要素、つまり最も大きいインデックス番号の付いた要素を削除します。
shift() メソッドでは、配列の先頭にある 1 個の要素、つまりインデックス番号が 0 である要素を削除します。splice() メソッ
ドは要素の挿入にも使用できますが、第 1 引数で指定したインデックス番号が示す位置から任意の数の要素を削除する場合にも使用できます。
これら 3 つのメソッドを使用して配列インスタンスの要素を削除する例を次に示します。この例では、広い海の名前を格納するために oceans という名前の配列を作成していますが、海ではなく湖の名前がいくつか含まれているので、それらを削除します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

31

配列の操作

まず、splice() メソッドを使用して Aral および Superior の要素を削除し、Atlantic および Indian の要素を挿入します。splice()の第 1 パラメーターとして渡している整数 2 は、3 番目の要素（インデックス 2）から始まる範囲を操作対象にするという指定です。また、第 2 パラメーターの整数 2 は、既存の要素を 2 つ削除するという指定です。残りのパラメーターで指定している Atlantic と Indian はインデックス 2 の位置に挿入する要素のリストです。
次に、pop() メソッドを使用して、配列の末尾に位置する要素 Huron を削除します。最後に shift() メソッドで、配列の先頭に位置する要素 Victoria を削除します。
var oceans:Array = ["Victoria", "Pacific", "Aral", "Superior", "Indian", "Huron"];oceans.splice(2, 2, "Arctic", "Atlantic"); // replaces Aral and Superior
oceans.pop(); // removes Huron
oceans.shift(); // removes Victoria
trace(oceans);// output: Pacific,Arctic,Atlantic,Indianpop() および shift() メソッドはいずれも、削除した要素を返します。Array インスタンスでは、配列にはあらゆるデータ型の値を格納できるので、戻り値のデータ型は Object になっています。Vector インスタンスでは、戻り値のデータ型はベク
ターのベース型になっています。splice() メソッドは、削除した値を格納した配列またはベクターを返します。oceans 配列の例を次のように改変すると、splice() の呼び出しで返される戻り値を新しい配列変数に割り当てることができます。
var lakes:Array = oceans.splice(2, 2, "Arctic", "Atlantic");
trace(lakes); // output: Aral,Superior

Array オブジェクトの要素に対して delete 演算子を使用しているコードもありますが、delete 演算子はその要素の値をundefined に設定するだけであり、配列から要素を削除するわけではありません。例えば次のコードでは、oceans 配列の 3 番
目の要素に対して delete 演算子を使用していますが、配列の要素数はその後も変わらず 5 のままです。
var oceans:Array = ["Arctic", "Pacific", "Victoria", "Indian", "Atlantic"];
delete oceans[2];trace(oceans);// output: Arctic,Pacific,,Indian,Atlantic
trace(oceans[2]); // output: undefined
trace(oceans.length); // output: 5

配列の length プロパティを使用して配列またはベクターを切り詰めることができます。インデックス配列の length プロパ
ティを配列の現在の長さ未満に設定すると、配列は切り詰められ、length - 1 という新しい値より大きい番号のインデックスに格納されているエレメントはすべて削除されます。例えば、oceans 配列のすべての有効なエントリが配列の先頭に格納されていた場合、次のコードに示すように、length プロパティを使用して配列の末尾のエントリを削除することができます。
var oceans:Array = ["Arctic", "Pacific", "Victoria", "Aral", "Superior"];oceans.length = 2;
trace(oceans); // output: Arctic,Pacific

注意：Vector オブジェクトの fixed プロパティが true である場合は、ベクターの要素数の合計を変更することはできません。ここで説明したテクニックを使用して固定長のベクターから要素を削除したり、固定長のベクターを切り詰めたりしようとすると、エラーが発生します。

配列のソートFlash Player 9 以降、Adobe AIR 1.0 以降
インデックス配列要素の並び順を変更する場合は、ソートまたは順序の逆転を行う reverse()、sort()、sortOn() の 3 つのメ
ソッドを使用できます。いずれのメソッドでも既存の配列が変化します。次の表に、Array オブジェクトおよび Vector オブ
ジェクトのこれらのメソッドとその動作をまとめます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

32

配列の操作

メソッド

配列の動作

ベクターの動作

reverse()

要素の並び順を逆転します。つまり、末尾にあった要素は先頭に、末尾の直前にあった要素は 2 番目に移動します。

配列の動作と同じです。

sort()

アルファベット順、番号順など、事前に定義した様々な方法で配列の要素をソートすることができます。また、カスタムのソートアルゴリズムを指定することもできます。

指定するカスタムのソートアルゴリズムに従って要素をソートします。

sortOn()ソート キーとして使用する 1 つ以上のプロパティを指定して、1 つ以上の共 Vector クラスでは使用できません。
通プロパティを含むオブジェクトをソートすることができます。

reverse() メソッド
reverse() メソッドは、パラメーターも戻り値もありませんが、既存の配列について現在の状態と、その並び順を逆転した状
態とを切り替えるのに使用できます。次の例では、oceans 配列に格納した海の名前を元とは逆の順序に並べ替えます。
var oceans:Array = ["Arctic", "Atlantic", "Indian", "Pacific"];
oceans.reverse();trace(oceans); // output: Pacific,Indian,Atlantic,Arctic

sort() メソッドを使用した基本的なソート（Array クラスのみ）
Array インスタンスでは、sort() メソッドがデフォルトのソート順を使用して配列要素を並べ替えます。このデフォルトのソート順には、次の特性があります。

•

大文字と小文字は区別され、大文字の方が小文字より先に並びます。例えば、D は b よりも先に並びます。

•

ソート方向は正順です。つまり、文字コードの値の小さい文字（例：A）の方が、文字コードの値の大きい文字（例：B）よりも先に並びます。

•

値が同等と見なされる要素は互いに隣接して並びますが、それらの間における並び順は決まっていません。

•

ソートはストリングベースで実行されます。つまり、要素は文字列に変換してから比較されます。例えば、数値の 10 は

3 よりも先に並びます。これは、ストリング「1」の文字コードの方がストリング「3」の文字コードよりも小さいためです。
大文字と小文字を区別しないソート、逆順のソート、またはアルファベット順でなく数値の大きさ順によるソートなどが必要な場合のために、Array クラスの sort() メソッドには、デフォルトのソート順に定められた各種の規則を変更する options
パラメーターがあります。こうしたオプションは、次に示す Array クラスの静的定数セットによって定義されます。

• Array.CASEINSENSITIVE：このオプションにより、ソートで大文字と小文字が無視されます。これにより、例えば小文字の b が大文字の D よりも先に並ぶようになります。
• Array.DESCENDING：デフォルトの正順ではなく逆順でソートします。例えば、B が A よりも先に並ぶようになります。
• Array.UNIQUESORT：同じ値を持つ複数の要素が見つかった場合にソートを中止するようにします。
• Array.NUMERIC：数値順でソートします。例えば、3 が 10 よりも先に並ぶようになります。
これらのオプションの一部を使用した例を次に示します。poets という名前の配列を作成し、いろいろなオプションを使用してソートを実行しています。
var poets:Array = ["Blake", "cummings", "Angelou", "Dante"];poets.sort(); // default sort
trace(poets); // output: Angelou,Blake,Dante,cummings
poets.sort(Array.CASEINSENSITIVE);
trace(poets); // output: Angelou,Blake,cummings,Dante
poets.sort(Array.DESCENDING);
trace(poets); // output: cummings,Dante,Blake,Angelou
poets.sort(Array.DESCENDING | Array.CASEINSENSITIVE); // use two options
trace(poets); // output: Dante,cummings,Blake,Angelou

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

33

配列の操作

sort() メソッドを使用したカスタムソート（Array クラスおよび Vector クラス）
Array オブジェクトで使用可能な基本のソートの他に、カスタムのソート規則を定義することもできます。このテクニック
は、Vector クラスで使用可能な唯一の形式の sort() メソッドです。カスタムソートを定義するには、カスタムのソート関数を作成し、それを sort() メソッドに引数として渡します。
例えば、各人のフルネームを要素として格納した人名リストがあるとします。このリストを姓を基準にして並べ替える場合
は、各要素を解析して姓の部分を比較するソート関数を独自に作成する必要があります。これを実現するコード例を、次に示します。この例では、カスタム関数を Array.sort() メソッドのパラメーターとして使用しています。
var names:Array = new Array("John Q. Smith", "Jane Doe", "Mike Jones");function orderLastName(a, b):int{
var lastName:RegExp = /\b\S+$/;var name1 = a.match(lastName);var name2 = b.match(lastName);if (name1 < name2){
return -1;}
else if (name1 > name2){
return 1;}
else{
return 0;}}
trace(names); // output: John Q. Smith,Jane Doe,Mike Jones
names.sort(orderLastName);
trace(names); // output: Jane Doe,Mike Jones,John Q. Smith

独自のソート関数 orderLastName() では、正規表現を使用して各要素から姓の部分を抽出し、それを比較演算に使用します。

names 配列に対する sort() メソッド呼び出しのパラメーターとして、この関数の識別子である orderLastName だけを指定しています。ソート関数に a および b の 2 つのパラメーターが渡されるのは、一度に 2 つの配列要素が処理の対象となるからです。ソート関数の戻り値は 2 つの要素の並び順を示すものであり、次の意味があります。

•

戻り値が -1 の場合、第 1 パラメーターの a を第 2 パラメーターの b よりも先に並べることを示します。

•

戻り値が 1 の場合、第 2 パラメーターの b を第 1 パラメーターの a よりも先に並べることを示します。

•

戻り値が 0 の場合、2 つの要素がソートにおいて同じ順位を持つことを示します。

sortOn() メソッド (Array クラスのみ )sortOn() メソッドは、要素がオブジェクトである Array オブジェクト用に作成されました。すべての要素のオブジェクトには、ソート用キーとなる共通のプロパティが少なくとも 1 つ含まれている必要があります。これらの条件に合わない配列に対して sortOn() メソッドを使用した場合の結果は予測不能です。
注意：Vector クラスには、sortOn() メソッドはありません。このメソッドは、Array オブジェクトでのみ有効です。
次の例は、poets 配列をストリング要素ではなくオブジェクト要素の配列に改変したものです。各オブジェクトには、詩人の姓と生誕年が格納されています。
var poets:Array = new Array();
poets.push({name:"Angelou", born:"1928"});poets.push({name:"Blake", born:"1757"});
poets.push({name:"cummings", born:"1894"});poets.push({name:"Dante", born:"1265"});poets.push({name:"Wang", born:"701"});

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

34

配列の操作

この配列では、born プロパティを基準として sortOn() メソッドによるソートを実行できます。sortOn() メソッドには、

fieldName および options の 2 つのパラメーターがあります。fieldName にはストリングを指定する必要があります。次の例
では、sortOn() にパラメーターとして「born」および Array.NUMERIC の 2 つを渡しています。Array.NUMERIC オプションを指定しているのは、アルファベット順ではなく数値順で確実にソートを実行するためです。たとえ各要素に格納されている数値の桁数がすべて同じであっても、必ずこのオプションを指定するようにしておけば、後で桁数の異なる要素が追加されたとしても正常に動作します。
poets.sortOn("born", Array.NUMERIC);
for (var i:int = 0; i < poets.length; ++i){
trace(poets[i].name, poets[i].born);}/* output:
Wang 701
Dante 1265
Blake 1757
cummings 1894
Angelou 1928*/

元の配列を変更しないソート（Array クラスのみ）
一般に、sort() および sortOn() メソッドを使用すると元の配列が変化します。既存の配列を変更せずにソートを実行する場
合は、options パラメーターに Array.RETURNINDEXEDARRAY 定数を含めます。このオプションを指定した場合、メソッドの戻り値はソート結果を示す新しい配列となり、元の配列の内容はそのまま維持されます。返される配列はソート後の並び順を示すインデックス番号だけを格納した単純なものであり、元の配列内の要素を格納した配列ではありません。例えば、

poets 配列について元の状態を維持したまま生誕年でのソートを実行するには、options パラメーターにArray.RETURNINDEXEDARRAY 定数を含めます。
次の例では、戻り値のインデックス情報を indices という配列に格納し、この indices と元のままの poets を使用して詩人のリストを生誕年順に表示しています。
var indices:Array;indices = poets.sortOn("born", Array.NUMERIC | Array.RETURNINDEXEDARRAY);
for (var i:int = 0; i < indices.length; ++i){
var index:int = indices[i];trace(poets[index].name, poets[index].born);}/* output:
Wang 701
Dante 1265
Blake 1757
cummings 1894
Angelou 1928*/

配列のクエリFlash Player 9 以降、Adobe AIR 1.0 以降
Array クラスおよび Vector クラスには concat()、join()、slice()、toString() の 4 つのメソッドがあります。これらはいずれもクエリによって配列から情報を取得するものであり、配列に変更を加えることはありません。concat() および slice() メソッ
ドは新しい配列を返し、join() および toString() メソッドはストリングを返します。concat() メソッドのパラメーターには配列または要素リストを指定します。既存の配列と、パラメーターで指定した別の配列または要素とを連結し、新しい配列を作成して返します。slice() メソッドには、startIndex および endIndex という 2 つのパラメーターがあります。元の配列から、最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

35

配列の操作

これらのパラメーターで指定したインデックスの範囲を切り出し、その部分のコピーを格納した新しい配列を返します。ただし、返される範囲は startIndex が指す要素から、endIndex が指す要素の直前までであり、endIndex の位置にある要素は含
まれません。
次の例では、既存の配列から concat() および slice() を使用して新しい配列を作成します。
var array1:Array = ["alpha", "beta"];
var array2:Array = array1.concat("gamma", "delta");
trace(array2); // output: alpha,beta,gamma,delta
var array3:Array = array1.concat(array2);
trace(array3); // output: alpha,beta,alpha,beta,gamma,delta
var array4:Array = array3.slice(2,5);
trace(array4); // output: alpha,beta,gammajoin() および toString() メソッドでは、配列の内容をストリングとして取得できます。join() メソッドのパラメーターを指定しない場合、これら 2 つのメソッドはいずれも、すべての配列要素をカンマで区切った内容のストリングを返します。join()
メソッドには、toString() メソッドにない delimiter というパラメーターがあり、戻り値のストリングで要素間に使用する区
切り文字を指定できます。
次の例では rivers という配列を作成し、join() および toString() を呼び出すことで、配列の内容をストリングとして取得しま
す。toString() メソッドはカンマ区切りの値（riverCSV）を得るため、また、join() メソッドは + で区切った値を得るために使用しています。
var rivers:Array = ["Nile", "Amazon", "Yangtze", "Mississippi"];var riverCSV:String = rivers.toString();
trace(riverCSV); // output: Nile,Amazon,Yangtze,Mississippi
var riverPSV:String = rivers.join("+");
trace(riverPSV); // output: Nile+Amazon+Yangtze+Mississippijoin() メソッドを使用する場合には、メインの配列要素に対して指定する区切り文字に関係なく、次に示す例のように、ネストされた Array インスタンスまたは Vector インスタンスには常にカンマ区切りの値が返されることに注意する必要があります。
var nested:Array = ["b","c","d"];var letters:Array = ["a",nested,"e"];var joined:String = letters.join("+");
trace(joined); // output: a+b,c,d+e

結合配列
Flash Player 9 以降、Adobe AIR 1.0 以降
ハッシュまたはマップとも呼ばれる結合配列は、格納される値を構成するために、数値インデックスの代わりにキーを使用します。結合配列に使用する個々のキーは、それぞれに対応する特定の格納値にアクセスするための一意のストリングです。
結合配列は Object クラスのインスタンスであり、したがって、各キーはそれぞれ 1 つのプロパティ名に対応します。結合配列は、キー / 値ペアの集合からなる、ソートされていないコレクションです。結合配列内のキーに何らかの決まった順序があるかのような前提でコードを記述してはなりません。
また、ActionScript 3.0 では、新たにディクショナリと呼ばれる高機能な結合配列を使用できるようになりました。ディク
ショナリは、flash.utils パッケージの Dictionary クラスのインスタンスですが、任意のデータ型にできるキーを使用します。つまり、ディクショナリのキーは String 型の値である必要はありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

36

配列の操作

ストリングキーを使用した結合配列
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、2 つの方法で結合配列を作成します。最初の方法は、Object インスタンスを使用する方法です。
Object インスタンスを使用することにより、オブジェクトリテラルで配列を初期化できます。Object クラスのインスタン
スは汎用オブジェクトとも呼ばれますが、機能的には結合配列と同じです。汎用オブジェクトの個々のプロパティ名が、格納した個々の値にアクセスするためのキーとして機能します。
次の例では、monitorInfo という名前の結合配列を作成します。オブジェクトリテラルを使用して、2 つのキーと値のペアが指定された配列を初期化します。
var monitorInfo:Object = {type:"Flat Panel", resolution:"1600 x 1200"};
trace(monitorInfo["type"], monitorInfo["resolution"]);// output: Flat Panel 1600 x 1200

宣言時に配列を初期化する必要がある場合は、次のように、Object コンストラクターを使って配列を作成できます。
var monitorInfo:Object = new Object();

オブジェクトリテラルまたは Object クラスのコンストラクターで配列を作成した後は、配列アクセス（[]）演算子または
ドット演算子（）を使用して新しい値を追加できます。次の例では、monitorArray に新しい値を 2 つ追加します。
monitorInfo["aspect ratio"] = "16:10"; // bad form, do not use spaces
monitorInfo.colors = "16.7 million";trace(monitorInfo["aspect ratio"], monitorInfo.colors);// output: 16:10 16.7 million

この例で、aspect ratio というキーの名前には空白文字が含まれています。配列アクセス（[]）演算子ではこのような名前も使用できますが、ドット演算子で使用するとエラーになります。空白文字を含んだキー名を使用することはお勧めしません。
結合配列を作成する 2 つ目の方法は、Array コンストラクター（またはダイナミッククラスのコンストラクター）を使用し、配列アクセス（[]）演算子またはドット演算子（.）を使用して、キーと値のペアを配列に追加します。結合配列を Array 型
として宣言した場合、オブジェクトリテラルで配列を初期化することはできません。次の例では、monitorInfo という名前の結合配列を Array コンストラクターで作成し、type および resolution という 2 つのキーとそれぞれに対応する値を追加します。
var monitorInfo:Array = new Array();
monitorInfo["type"] = "Flat Panel";monitorInfo["resolution"] = "1600 x 1200";
trace(monitorInfo["type"], monitorInfo["resolution"]);// output: Flat Panel 1600 x 1200

結合配列の作成に Array コンストラクターを使用するメリットはありません。たとえ Array コンストラクターや Array デー
タ型を使用して宣言した結合配列であっても、Array.length プロパティや Array クラスのメソッドはまったく使用できないからです。Array コンストラクターはインデックス配列を作成する場合に限って使用するようお勧めします。

オブジェクトのキーを使用した結合配列 （ディクショナリ）
Flash Player 9 以降、Adobe AIR 1.0 以降
Dictionary クラスを使用すると、ストリングではなくオブジェクトをキーとする結合配列を作成できます。そのような配列
は、ディクショナリ、ハッシュ、またはマップと呼ばれることがあります。例えば、特定のコンテナとの位置関係によってSprite オブジェクトの位置が決まるようなアプリケーションでは、個々の Sprite オブジェクトをコンテナへマップする場合に Dictionary オブジェクトを使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

37

配列の操作

次のコードでは、Dictionary オブジェクトのキーとして使用する Sprite クラスのインスタンスを 3 つ作成します。各キーに対しては、GroupA または GroupB いずれかの値を格納します。格納する値には任意のデータ型を使用できますが、この例では GroupA、GroupB のいずれも Object クラスのインスタンスです。次に、配列アクセス演算子（[]）を使用して、各キーに対応する値にアクセスします。
import flash.display.Sprite;
import flash.utils.Dictionary;var groupMap:Dictionary = new Dictionary();// objects to use as keys
var spr1:Sprite = new Sprite();var spr2:Sprite = new Sprite();var spr3:Sprite = new Sprite();// objects to use as values
var groupA:Object = new Object();
var groupB:Object = new Object();// Create new key-value pairs in dictionary.
groupMap[spr1] = groupA;
groupMap[spr2] = groupB;groupMap[spr3] = groupB;
if (groupMap[spr1] == groupA){
trace("spr1 is in groupA");}
if (groupMap[spr2] == groupB){
trace("spr2 is in groupB");}
if (groupMap[spr3] == groupB){
trace("spr3 is in groupB");}

オブジェクトのキーを使用した反復処理

for..in ループまたは for each..in ループで Dictionary オブジェクトの内容の繰り返し処理を実行することができます。for..inループを使用すると、キーに基づいて反復処理することができます。一方、for each..in ループを使用すると、各キーに関連付けられた値に基づいて反復処理することができます。
for..in ループの場合、Dictionary オブジェクト内のオブジェクトキーに直接アクセスできます。また、配列アクセス演算子（[]）を使用すれば Dictionary オブジェクト内の値にアクセスできます。次のコードでは、前の例と同じ groupMap ディク
ショナリを使用して、for..in ループで Dictionary オブジェクトの内容を反復処理する方法を示します。
for (var key:Object in groupMap){
trace(key, groupMap[key]);}/* output:[object Sprite] [object Object][object Sprite] [object Object][object Sprite] [object Object]*/for each..in ループの場合、Dictionary オブジェクトの値に直接アクセスできます。次のコードでもやはり groupMap ディク
ショナリを使用して、for each..in ループで Dictionary オブジェクトの内容を反復処理する方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

38

配列の操作

for each (var item:Object in groupMap){
trace(item);}/* output:[object Object][object Object][object Object]*/

オブジェクトキーとメモリ管理

Adobe® Flash® Player と Adobe® AIR™ では、使用されなくなったメモリはガベージコレクションのシステムによって開放されます。オブジェクトはどこからも参照されなくなった時点でガベージコレクションの対象とされ、次回ガベージコレク
ションが実行されるとき、そのオブジェクトに使用されていたメモリが解放されます。例えば次のコードでは、新しいオブジェクトを作成し、そのオブジェクトへの参照を myObject という変数に割り当てています。
var myObject:Object = new Object();

オブジェクトに対して何らかの参照が存在する間は、そのオブジェクトが使用しているメモリがガベージコレクションのシ
ステムによって解放されることはありません。myObject の値が別のオブジェクトを参照するように変更されるか、または

null に設定されると、それまで参照先となっていたオブジェクトはガベージコレクションの対象とされます（そのオブジェ
クトに対する参照が他に存在しない場合）。
この myObject を Dictionary オブジェクトのキーとして使用すると、参照先オブジェクトに対する参照がもう 1 つ作成されます。例えば次のコードでは、1 つのオブジェクトに対して 2 つの参照、つまり myObject 変数と、myMap オブジェクトのキーを作成しています。
import flash.utils.Dictionary;
var myObject:Object = new Object();
var myMap:Dictionary = new Dictionary();
myMap[myObject] = "foo";

myObject で参照しているオブジェクトをガベージコレクションに対して有効にするには、そのオブジェクトに対する参照をすべて削除する必要があります。この場合、そのためには myObject の値を変更するのに加え、myMap から myObject のキーを削除します。
myObject = null;
delete myMap[myObject];

別の方法として、Dictionary コンストラクターに対して useWeakReference パラメーターを指定し、すべてのディクショナ
リキーを弱参照にすることもできます。弱参照はガベージコレクションのシステムで無視されるため、弱参照による参照しか受けていないオブジェクトはガベージコレクションの対象となります。例えば次のコードでは、myMap 内の myObject
キーを削除しなくても、該当するオブジェクトをガベージコレクションの対象とすることができます。
import flash.utils.Dictionary;
var myObject:Object = new Object();
var myMap:Dictionary = new Dictionary(true);
myMap[myObject] = "foo";
myObject = null; // Make object eligible for garbage collection.

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

39

配列の操作

多次元配列
Flash Player 9 以降、Adobe AIR 1.0 以降
多次元配列には、配列の要素としてさらに配列が格納されています。例えば、ストリングのインデックス配列として格納される予定リストがあるとします。
var tasks:Array = ["wash dishes", "take out trash"];

曜日ごとに異なる予定リストを格納する必要がある場合は、各曜日を要素として持つ多次元配列を作成できます。それぞれの要素として、予定リストを表す tasks 配列と同様のインデックス配列を格納します。多次元配列内では、インデックス配列と結合配列を任意に組み合わせて使用できます。以降のセクションでは、2 つのインデックス配列を使用する例と、結合配列
およびインデックス配列を 1 つずつ使用する例を示します。また、実習として、考えられる残りの組み合わせについても作成してみてください。

2 つのインデックス配列を使用する例
Flash Player 9 以降、Adobe AIR 1.0 以降
インデックス配列を 2 つ使用した場合の結果は、テーブルまたはスプレッドシートのような図で表現できます。第 1 の配列に含まれる要素がテーブルの行を表し、第 2 の配列に含まれる要素が列を表します。
例えば、次の多次元配列には、曜日ごとの予定リストを 2 つのインデックス配列として格納しています。第 1 の配列

masterTaskList は、Array クラスのコンストラクターを使用して作成します。この配列の各要素は曜日に対応し、インデックス 0 が月曜、インデックス 6 が日曜を表します。それらの要素は、テーブルの行と見なすことができます。各曜日の予定リ
ストは、masterTaskList 配列内にある 7 つの要素それぞれに配列リテラルを割り当てることで作成できます。これらの配列
リテラルは、テーブルの列を表します。
var masterTaskList:Array = new Array();masterTaskList[0] = ["wash dishes", "take out trash"];masterTaskList[1] = ["wash dishes", "pay bills"];
masterTaskList[2] = ["wash dishes", "dentist", "wash dog"];masterTaskList[3] = ["wash dishes"];masterTaskList[4] = ["wash dishes", "clean house"];masterTaskList[5] = ["wash dishes", "wash car", "pay rent"];
masterTaskList[6] = ["mow lawn", "fix chair"];

配列アクセス（[]）演算子を使用すると、どの予定リストのアイテムにも個別にアクセスできます。最初の角括弧で曜日を指定し、2 番目の角括弧でその日の予定リスト内の項目を指定します。例えば、水曜日の予定リストから 2 番目の予定を取得するには、水曜日を表すインデックス 2 と、予定リストの 2 番目の項目を表すインデックス 1 を指定します。
trace(masterTaskList[2][1]); // output: dentist

日曜日の予定リストから 1 番目の予定を取得するには、日曜日を表すインデックス 6 と、予定リストの 1 番目の項目を表す
インデックス 0 を指定します。
trace(masterTaskList[6][0]); // output: mow lawn

結合配列の下位にインデックス配列を組み合わせる例
Flash Player 9 以降、Adobe AIR 1.0 以降
曜日について結合配列を使用し、予定リストについてインデックス配列を使用すると、個別の配列に対するアクセスが容易になります。結合配列では、特定の曜日を参照するときにドットシンタックスを使用することができますが、結合配列の各要素にアクセスするために、実行時の処理時間が余分に犠牲になります。次の例では、曜日ごとにキー / 値ペアを指定し、予定リストの基礎として結合配列を使用しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

40

配列の操作

var masterTaskList:Object = new Object();
masterTaskList["Monday"] = ["wash dishes", "take out trash"];masterTaskList["Tuesday"] = ["wash dishes", "pay bills"];
masterTaskList["Wednesday"] = ["wash dishes", "dentist", "wash dog"];masterTaskList["Thursday"] = ["wash dishes"];masterTaskList["Friday"] = ["wash dishes", "clean house"];masterTaskList["Saturday"] = ["wash dishes", "wash car", "pay rent"];
masterTaskList["Sunday"] = ["mow lawn", "fix chair"];

ドットシンタックスを使用すると、角括弧の繰り返しを避けることができるため、コードが読みやすくなります。
trace(masterTaskList.Wednesday[1]); // output: dentist
trace(masterTaskList.Sunday[0]);// output: mow lawnfor..in ループを使用して予定リストを反復処理できますが、各キーに関連付けられた値にアクセスするには、ドットシン
タックスの代わりに配列アクセス（[]）演算子を使用する必要があります。masterTaskList は結合配列であるため、次の例に示すように、必ずしも期待する順序で要素を取得する必要はありません。
for (var day:String in masterTaskList){
trace(day + ": " + masterTaskList[day])}/* output:
Sunday: mow lawn,fix chair
Wednesday: wash dishes,dentist,wash dog
Friday: wash dishes,clean house
Thursday: wash dishes
Monday: wash dishes,take out trash
Saturday: wash dishes,wash car,pay rent
Tuesday: wash dishes,pay bills*/

配列のコピーFlash Player 9 以降、Adobe AIR 1.0 以降
Array クラスには、配列のコピーを作成する組み込みメソッドは用意されていません。配列の浅いコピーは、concat() または
slice() メソッドをパラメーターなしで呼び出すことで作成できます。浅いコピーでは、オブジェクトである要素が元の配列に格納されている場合、コピーした配列内の要素は元の要素に格納されているオブジェクトへの参照となり、参照先オブジェクトはコピーされません。したがって、元の配列とコピーした配列が同一のオブジェクトを参照することになり、オブジェクトが変更されると、両方の配列に対してその変更が反映されます。
深いコピーとは、元の配列内で参照されているオブジェクトをすべてコピーすることです。その場合、元の配列とコピーした配列が同一のオブジェクトを参照する結果にはなりません。深いコピーを実行するには複数行のコードを記述する必要があり、通常、何らかの関数を作成することになります。こうした関数は、グローバルなユーティリティ関数として作成する
か、または Array のサブクラスにメソッドとして作成することができます。
次の例では、深いコピーを実行するための clone() という関数を定義しています。採用したアルゴリズムは、Java プログラ
ミングで一般的に使用されているテクニックです。まず元の配列を直列化して ByteArray クラスのインスタンスを作成し、それを新しい配列に読み込むことでコピーを実行しています。次のコードに示されているとおり、この関数はオブジェクトを受け付けるため、インデックス配列と結合配列の両方で使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

41

配列の操作

import flash.utils.ByteArray;function clone(source:Object):*{
var myBA:ByteArray = new ByteArray();
myBA.writeObject(source);
myBA.position = 0;
return(myBA.readObject());}

Array クラスの拡張
Flash Player 9 以降、Adobe AIR 1.0 以降
Array クラスはコアクラスとしては珍しく final 指定されていないため、Array のサブクラスを独自に定義できます。このセクションでは、Array のサブクラスを作成する方法について例を示し、その際に発生すると考えられる問題について説明します。
前述したとおり ActionScript の配列には型がありませんが、Array のサブクラスを定義すれば、特定のデータ型の要素だけを格納する配列を作成できるようになります。以下のセクションの例では、Array のサブクラスとして、第 1 パラメー
ターに指定されているデータ型の要素だけを格納する TypedArray というクラスを定義します。TypedArray クラスは、Array クラスの拡張方法の例として示したにすぎず、いくつかの理由で運用目的には適さない場合があります。第 1 に、コンパイル時ではなく、実行時に型チェックが行われます。第 2 に、メソッドは簡単な変更によって例外をスローする可能性がありますが、TypedArray メソッドで不一致が見つかった場合に、その不一致は無視されて例外がスローされます。第 3に、このクラスでは、配列に任意の型の要素を挿入する配列アクセス演算子の使用を防止できません。第 4 に、コーディン
グスタイルでは、パフォーマンスの最適化よりも単純さの方が優先されます。
注意：ここで説明したテクニックを使用すると、型指定された配列を作成できます。ただし、より良い方法は、Vector オブ
ジェクトを使用することです。Vector インスタンスは実際に型指定された配列であり、Array クラスまたはどのサブクラスをも上回るパフォーマンスをもたらし、その他の点でも強化されます。この説明の目的は、Array サブクラスの作成方法を示すことです。
サブクラスの宣言
定義するクラスが Array のサブクラスであることを示すには、extends キーワードを使用します。Array のサブクラスでは、
Array と同様に dynamic 属性を使用します。これに従わないとサブクラスが正常に機能しません。
次のコードに示す TypedArray クラスの定義には、データ型を保持する定数、コンストラクターメソッド、配列要素の追加に使用できる 4 つのメソッドがあります。ここでは各メソッドのコードを省略していますが、それらの詳細については以降のセクションで説明していきます。
public dynamic class TypedArray extends Array{
private const dataType:Class;public function TypedArray(...args) {}AS3 override function concat(...args):Array {}AS3 override function push(...args):uint {}AS3 override function splice(...args) {}AS3 override function unshift(...args):uint {}}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

42

配列の操作

4 つのオーバーライドしたメソッドはすべてが AS3 名前空間を使用し、public 属性は使用していません。この例では、コン
パイラーオプション -as3 の設定は true、コンパイラーオプション -es の設定は false と仮定しているためです。これらの設定
は、Adobe Flash Builder および Adobe Flash Professional のデフォルト設定です。
上級開発者でプロトタイプ継承の使用を優先したい場合は、TypedArray クラスに 2 つのマイナー変更を加え、コンパ
イラーオプション -es を true に設定してコンパイルします。最初に、すべての出現箇所の override 属性を削除し、AS3 名
前空間を public 属性で置換します。次に、出現するすべての 4 つの super の代わりに Array.prototype を使用します。

TypedArray コンストラクター
このコンストラクターを定義するにあたっては興味深い問題が 1 つあります。それは、任意の長さを持つリストをパラメーターとして受け付け、さらに、配列を作成するためにパラメーターをスーパーコンストラクターに引き渡す必要があるということです。パラメーターのリストを配列として渡せば、スーパーコンストラクターには Array 型のパラメーター 1 個として扱われてしまい、結果として配列の要素数は常に 1 になります。パラメーターリストをそのまま引き渡す場合の伝統的な処理方法として Function.apply() メソッドがあります。パラメーター配列をこのメソッドの第 2 パラメーターに指定すると、その要素を個々のパラメーターに展開して関数を実行させることができます。しかし、Function.apply() メソッドはコンスト
ラクター内では使用できません。
残る唯一の選択肢は、TypedArray コンストラクター内に Array コンストラクターと同様のロジックを再現することです。
次のコードは、Array クラスのコンストラクターで使用されているアルゴリズムを示しています。これは、Array のサブク
ラスのコンストラクターでも使用できます。
public dynamic class Array{public function Array(...args){
var n:uint = args.lengthif (n == 1 && (args[0] is Number)){var dlen:Number = args[0];var ulen:uint = dlen;
if (ulen != dlen){
throw new RangeError("Array index is not a 32-bit unsigned integer ("+dlen+")");}
length = ulen;}
else{
length = n;
for (var i:int=0; i < n; i++){this[i] = args[i]}}}}TypedArray コンストラクターは、そのほとんどが Array コンストラクターから流用したコードで構成され、変更点は 4 つだけです。1 つ目は、パラメーターリストに Class 型の新しい必須パラメーターを含め、配列のデータ型を指定できるようにしたことです。2 つ目は、コンストラクターに渡されるデータ型を dataType 変数に割り当てたことです。3 つ目は、else ス
テートメントにおいて、length プロパティの値は for ループの実行後に設定し、適切な型のパラメーターだけが length に含まれるようにしたことです。4 つ目は、オーバーライドした push() メソッドを for ループの本体の中で使用し、適切なデー
タ型のパラメーターだけを配列に追加するようにしたことです。次の例は、TypedArray コンストラクター関数を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

43

配列の操作

public dynamic class TypedArray extends Array{
private var dataType:Class;public function TypedArray(typeParam:Class, ...args){
dataType = typeParam;
var n:uint = args.lengthif (n == 1 && (args[0] is Number)){var dlen:Number = args[0];var ulen:uint = dlen
if (ulen != dlen){
throw new RangeError("Array index is not a 32-bit unsigned integer ("+dlen+")")}
length = ulen;}else{
for (var i:int=0; i < n; i++){// type check done in push()
this.push(args[i])}length = this.length;}}}

TypedArray でオーバーライドしたメソッド
TypedArray クラスでは、Array クラスのメソッドのうち、配列要素の追加に使用できる 4 つのメソッドをオーバーライド
しています。いずれのメソッドでも、適切なデータ型以外の要素が追加されるのを防ぐために型チェックを実行してから、
スーパークラスにある同じメソッドを呼び出します。

push() メソッドでは for..in ループで引数のリストを反復処理し、各引数の型チェックを行います。不適切な型のパラメー
ターがあれば、splice() メソッドで args 配列から削除します。この for..in ループを終了した後は、args には dataType 型の要素しか含まれていないことになります。それから、次のようにスーパークラスの push() に改変後の args 配列を渡して呼び出します。
AS3 override function push(...args):uint{for (var i:* in args){
if (!(args[i] is dataType)){
args.splice(i,1);}}
return (super.push.apply(this, args));}

concat() メソッドでは、型チェックに適合した引数を格納するために、passArgs という名前で一時的な TypedArray を作成します。これは、push() メソッド内の型チェックのコードを再利用するためです。for..in ループで、args 配列内の個々の要素について push() を呼び出します。passArgs の型は TypedArray なので、実行される push() メソッドは TypedArray クラスのものです。それから、次のようにスーパークラスの concat() メソッドを呼び出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

44

配列の操作

AS3 override function concat(...args):Array{var passArgs:TypedArray = new TypedArray(dataType);for (var i:* in args){// type check done in push()
passArgs.push(args[i]);}return (super.concat.apply(this, passArgs));}

splice() メソッドには任意の数の引数を指定できますが、最初の 2 つは必ず、インデックス番号と削除する要素の数を表す引
数になります。このため、オーバーライドした splice() メソッドでは、args のインデックス番号が 2 以降の配列要素に対してのみ型チェックを実行します。このコードでは、for ループ内で splice() を再帰的に呼び出しているように見えますが、実際には再帰ではありません。args の型は TypedArray ではなく Array なので、args.splice() の呼び出しで実行されるのはスーパークラスのメソッドです。この for..in ループを終了した後は、args にはインデックス番号が 2 以上の適切な型の要素しか含まれていません。それから、次のようにスーパークラスの splice() を呼び出します。
AS3 override function splice(...args):*{
if (args.length > 2){for (var i:int=2; i< args.length; i++){if (!(args[i] is dataType)){
args.splice(i,1);}}}
return (super.splice.apply(this, args));}

配列の先頭に要素を挿入する unshift() も、任意の数の引数リストを受け付けるメソッドです。オーバーライドした unshift()
メソッドでは、次のコードに示すとおり、push() メソッドと非常によく似たアルゴリズムを使用しています。
AS3 override function unshift(...args):uint{for (var i:* in args){
if (!(args[i] is dataType)){
args.splice(i,1);}}
return (super.unshift.apply(this, args));}}配列の例：PlayList
Flash Player 9 以降、Adobe AIR 1.0 以降
ここでは PlayList の例を使って、配列を操作する手法について、曲のリストを管理する音楽プレイリストアプリケーションのコンテキストで示します。それらの手法は、次のとおりです。

•

インデックス配列の作成•

インデックス配列への項目の追加

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

45

配列の操作

•

各種ソートオプションを使用したオブジェクト配列のプロパティ別ソート•

文字で区切られたストリングへの配列の変換

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。PlayList アプリケーションのファ
イルは、Samples/PlayList フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

PlayList.mxml

Flash（FLA）または Flex（MXML）のメインアプリケーションファ
イル。

または

PlayList.fla
com/example/programmingas3/playlist/PlayList.as

曲のリストを表すクラス。1 個の Array を使用してリストを格納し、リスト項目のソート順を管理します。
単一の曲に関する情報を表す値オブジェクト。PlayList クラスが管理

com/example/programmingas3/playlist/Song.as

する項目は Song インスタンスです。

com/example/programmingas3/playlist/SortProperty.as

利用可能な値が Song クラスのプロパティを表し、このプロパティでSong オブジェクトのリストをソート可能な擬似列挙。

PlayList クラスの概要
Flash Player 9 以降、Adobe AIR 1.0 以降
PlayList クラスは Song オブジェクトセットを管理するクラスで、曲をプレイリストに追加するための addSong() メソッド
や、リストの曲をソートするための sortList() メソッドなど、様々な機能のパブリックメソッドを備えています。このクラスには、読み取り専用アクセッサープロパティの songList もあり、これによってプレイリストの実際の曲セットにアクセスできます。内部的には、PlayList クラスは、Array プライベート変数を使用して曲を追跡し続けます。
public class PlayList{
private var _songs:Array;private var _currentSort:SortProperty = null;
private var _needToSort:Boolean = false;...
}

PlayList クラスが曲のリストを追跡し続けるために使用する _songs という Array 変数のほかに、2 つのプライベート変数（_needToSort と _currentSort）があり、前者はリストのソートが必要であるかどうかを、後者は指定の時刻にどのプロパ
ティで曲のリストをソートするかを追跡し続けます。
すべてのオブジェクトの場合と同様に、Array インスタンスを宣言するだけでは Array の作成作業は完了しません。Array
インスタンスのプロパティまたはメソッドにアクセスする前に、このインスタンスを PlayList クラスのコンストラクターでインスタンス化しておく必要があります。
public function PlayList(){
this._songs = new Array();// Set the initial sorting.
this.sortList(SortProperty.TITLE);}

コンストラクターの 1 行目は、_songs 変数をインスタンス化して使用できる状態にします。さらに、sortList() メソッドを呼び出し、最初のソート基準プロパティを設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

46

配列の操作

リストへの曲の追加
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーが新しい曲をアプリケーションに登録すると、データ入力フォームのコードが PlayList クラスの addSong() メソッ
ドを呼び出します。
/*** Adds a song to the playlist.
*/
public function addSong(song:Song):void{
this._songs.push(song);
this._needToSort = true;}

addSong() 内では、_songs 配列の push() メソッドが呼び出され、その配列の新しい要素として addSong() に渡された Song オ
ブジェクトが追加されます。push() メソッドでは、以前に適用していたソートとは関係なく、新しい要素を配列の末尾に追加します。つまり、push() メソッドを呼び出した後では、曲のリストはソート順が正しくなっていない可能性が高いため、_needToSort 変数は true に設定されます。理論上は、sortList() メソッドをすぐに呼び出すため、指定の時刻にリストをソートするかどうかを追跡し続けることは不要になります。しかし、実際には、取得する直前まで曲のリストをソートする必要はありません。例えば、取得前に何曲かリストに追加したときなど、ソート操作を遅らせると、アプリケーションは不要なソートを実行しなくなります。

曲のリストのソート
Flash Player 9 以降、Adobe AIR 1.0 以降
プレイリストが管理する Song インスタンスは複雑なオブジェクトであるため、そのアプリケーションのユーザーは、曲のタイトルまたは発表の年など、様々なプロパティに従ってプレイリストをソートしたいと考えることがあります。PlayList
アプリケーションにおいて、曲のリストをソートするタスクは、リストのソート基準としてのプロパティを見分けること、
そのプロパティによるソート時に必要なソートオプションを指定すること、実際のソート操作を実行することの 3 つの部分から構成されます。
ソートのプロパティ

Song オブジェクトは、曲のタイトル、アーティスト、発表の年、ファイル名、およびユーザーの選曲ジャンル集など、いくつものプロパティを追跡し続けます。言うまでもなく、ソートに実用的なのは、例に挙げた最初の 3 つのプロパティのみです。開発者の便宜のため、例に含めた SortProperty クラスは、ソートに利用可能なプロパティを表す値を持つ列挙として機能します。
public static const TITLE:SortProperty = new SortProperty("title");public static const ARTIST:SortProperty = new SortProperty("artist");public static const YEAR:SortProperty = new SortProperty("year");

SortProperty クラスには、TITLE、ARTIST、および YEAR の 3 つの定数があり、各定数には、ソートに使用する関連 Song
クラスプロパティの実際の名前を含むストリングが格納されます。コードの残り全体を通し、ソートプロパティが指定されると必ず列挙メンバーを使用して行われます。例えば、PlayList コンストラクターでは、次のように、sortList() メソッドを呼び出してリストを最初にソートします。
// Set the initial sorting.
this.sortList(SortProperty.TITLE);

ソートのプロパティは SortProperty.TITLE として指定されているため、曲はタイトルに従ってソートされます。
プロパティによるソートおよびソートオプションの指定
実際には曲のリストのソートは、次に示すように、PlayList クラスが sortList() メソッドで実行します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

47

配列の操作

/**
* Sorts the list of songs according to the specified property.
*/
public function sortList(sortProperty:SortProperty):void{...
var sortOptions:uint;
switch (sortProperty){case SortProperty.TITLE:
sortOptions = Array.CASEINSENSITIVE;
break;
case SortProperty.ARTIST:
sortOptions = Array.CASEINSENSITIVE;
break;
case SortProperty.YEAR:
sortOptions = Array.NUMERIC;
break;}// Perform the actual sorting of the data.
this._songs.sortOn(sortProperty.propertyName, sortOptions);// Save the current sort property.
this._currentSort = sortProperty;// Record that the list is sorted.
this._needToSort = false;}

タイトルやアーティストによってソートする場合はアルファベット順にソートし、年によってソートする場合は数値順にソートします。switch ステートメントを使用して、sortProperty パラメーターが指定する値に従った適切なソートオプション（変数 sortOptions に格納）を定義します。ここでも、プロパティの区別には、ハードコードされた値ではなく名前付き列挙
メンバーを使用しています。
ソートプロパティおよびソートオプションの決定に続き、_songs 配列を sortOn() メソッドの呼び出しで実際にソートし、それらの 2 つの値をパラメーターとして渡します。現在のソートプロパティが記録されますが、それは曲のリストが現時点でソートされたということです。

文字で区切られたストリングへの配列要素の結合
Flash Player 9 以降、Adobe AIR 1.0 以降
配列を使用して曲のリストを PlayList クラスで維持する以外に、この例では Song クラスでも配列を使用して、曲についてのジャンルリストを管理するのに役立てています。次の例で、Song クラスの定義からこのコードについて考えます。
private var _genres:String;
public function Song(title:String, artist:String, year:uint, filename:String, genres:Array){...
// Genres are passed in as an array// but stored as a semicolon-separated string.
this._genres = genres.join(";");}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

48

配列の操作

新しい Song インスタンスの作成時に、曲のジャンルの指定に使用する genres パラメーターが Array インスタンスとして定義されます。そのため、複数のジャンルを一緒のグループにまとめ、コンストラクターに渡せる 1 つの変数とするのに便利です。ただし、内部的には Song クラスは、セミコロンで区切られた String インスタンスとして _genres プライベート変数にジャンルを維持します。Array パラメーターは、リテラルストリング値「;」を区切り文字として指定して join() メソッドを呼び出すと、セミコロンで区切られたストリングに変換されます。
同じように、genres アクセッサーを使用して、ジャンルを配列として設定また取得できます。
public function get genres():Array{// Genres are stored as a semicolon-separated String,// so they need to be transformed into an Array to pass them back out.
return this._genres.split(";");}
public function set genres(value:Array):void{// Genres are passed in as an array,// but stored as a semicolon-separated string.
this._genres = value.join(";");}

genresset アクセッサーの動作は、コンストラクターの動作とまったく同じです。配列を受け取って join() メソッドを呼び出し、セミコロン区切りのストリングに変換します。get アクセッサーは反対の操作を実行します。つまり、_genres 変数のsplit() メソッドが呼び出されると、指定された区切り文字（リテラルストリング値 ";" など）を使用して、ストリングを値の配列に分割します。

最終更新日 2015/10/14

49

第 4 章：エラー処理
Flash Player 9 以降、Adobe AIR 1.0 以降
エラーの「処理」とは、エラーに応答したり、解決したりするロジックをアプリケーションに組み込むことを意味します。
エラーは、アプリケーションのコンパイル時またはコンパイル済みアプリケーションの実行時のいずれかに生成されます。
アプリケーションによるエラー処理では、応答なし（エラーを生成した何かのプロセスが説明のないまま異常終了する）とは異なり、エラー発生時に何らかの応答があります。エラー処理を正しく使用すれば、予期しない動作からアプリケーショ
ンとユーザーを保護するために役立ちます。
ただし、エラー処理は広範な概念であり、コンパイル時または実行時に発生する様々な種類のエラーに対する応答も含まれます。ここでは、ランタイムエラー（アプリケーションの実行中に発生するエラー）を処理する方法、生成される可能性のある様々な種類のエラー、および ActionScript 3.0 におけるエラー処理システムのメリットを中心に説明します。

エラー処理の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
ランタイムエラーは、ActionScript コードで生じた何らかの問題であり、ActionScript コンテンツの実行が意図的に中止されます。ActionScript コードをユーザーにとってスムーズに動作させるには、アプリケーションにエラーを処理（エラーの修正、解決、または少なくとも何が発生したかをユーザーに通知）するコードを記述します。この処理をエラー処理と言います。
エラー処理は広範な概念であり、コンパイル時または実行時に発生する様々な種類のエラーに対する応答も含まれます。多くの場合コンパイル時に発生するエラーは比較的簡単に特定できます。SWF ファイルの作成処理を完了するには、こうしたエラーを修正してください。
ランタイムエラーが発生するには、誤ったコードが実際に実行されることが必要であるために、その検出はより難しくなります。if..then..else ステートメントなど、プログラムのセグメントにコードの分岐がいくつか存在する場合は、実際のユーザーが使用する可能性があるあらゆる入力値ですべての条件についてテストし、コードにエラーが含まれないことを確認します。
ランタイムエラーはプログラムエラーと論理エラーの 2 つのカテゴリに分類できます。プログラムエラーは、メソッドパラ
メーターに誤ったデータ型を指定するなど、ActionScript コード内の誤りです。論理エラーは、銀行業務アプリケーション
で利率計算に誤った数式を使用するなど、プログラムの論理ロジック（データチェックおよび値操作）の誤りです。どちらのタイプのエラーも、アプリケーションの入念なテストにより事前に検出および修正できることが少なくありません。
理想的には、エンドユーザーにリリースする前に、アプリケーションのすべてのエラーを識別して削除することが望まれます。ただし、すべてのエラーを予見または防止することはできません。例えば、管理下にない特定の Web サイトから

ActionScript アプリケーションが情報をロードする場合を考えます。ある時点でその Web サイトが使用可能でなければ、該当する外部データに依存するアプリケーションの一部分が正しく動作しません。このような未知の状況に備えて安全なエ
ラー処理を行うことは、エラー処理の最も重要な要素です。ユーザーはアプリケーションの使用を続行できること、または
少なくとも動作しない理由をわかりやすく説明するエラーメッセージが表示されることを求めています。

ActionScript では、ランタイムエラーは次の 2 つの方法で表されます。

• Error クラス : 多くのエラーに Error クラスが関連付けられています。エラーが発生すると、Flash ランタイム（Flash
Player や Adobe AIR など）により、該当する特定のエラーに関連付けられた特定の Error クラスのインスタンスが作成されます。コードでは、エラーオブジェクトに含まれる情報を使用してエラーに対して適切な対処を行うことができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

50

エラー処理

•

エラーイベント：Flash ランタイムが通常どおりにイベントをトリガーしたときにエラーが発生することがあります。その場合、代わりにエラーイベントがトリガーされます。各エラーイベントにはクラスが関連付けられています。Flash ランタイムは、該当クラスのインスタンスをエラーイベントにサブスクライブされたメソッドに渡します。

特定のメソッドでエラーまたはエラーイベントをトリガーできるかどうかについては、『Adobe Flash Platform 用

ActionScript 3.0 リファレンスガイド』で、そのメソッドの説明を参照してください。
重要な概念と用語
次の参照リストに、エラー処理ルーチンのプログラミングに関する重要な用語を示します。
非同期 即時に結果を得られず、イベントの形式で結果（またはエラー）が得られるメソッドの呼び出しなどのプログラムコ
マンド。
キャッチ 例外（ランタイムエラー）が発生し、その例外をコードで認識したとき、コードが例外を「キャッチ」したと言います。例外がキャッチされると、Flash ランタイムは他の ActionScript コードに例外を通知することを停止します。
デバッガーバージョン ユーザーにランタイムエラーを通知するコードを含む、特殊なバージョンの Flash ランタイム（Flash Player デバッガーバージョンや AIR Debug Launcher（ADL）など）。大半のユーザーが使用する標準バージョンの Flash Player または Adobe AIR では、ActionScript コードによって処理されないエラーは無視されます。Adobe FlashCS4 Professional および Adobe Flash Builder に含まれるデバッガーバージョンでは、未処理のエラーが発生した場合に警告メッセージが表示されます。
例外 アプリケーションの実行中に発生し、Flash ランタイムが単独で解決できないエラー。
再スロー コードが例外をキャッチした場合、Flash ランタイムは他のオブジェクトに例外を通知しなくなります。他のオブジェクトで例外を受け取る必要がある場合は、コードで例外を「再スロー」して、通知処理を再度開始する必要があります。
同期 同じコードブロック内で応答を使用できるように即時に結果を提供する（またはエラーをスローする）メソッドの呼び出しなどのプログラムコマンド。
スロー エラーが発生したことを Flash ランタイムに通知する（したがって、他のオブジェクトおよび ActionScript コードにも通知する）処理をエラーの「スロー」と言います。

エラーの種類Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションの開発中および実行中に発生するエラーは、様々な種類があり、使用する用語が異なります。主要なエラーの種類と用語について簡単に説明します。

•

コンパイル時エラー : ActionScript コンパイラーによるコンパイル処理の際に発生します。コンパイル時エラーは、コードに文法的な問題があるためアプリケーションを構築できないことを示します。

•

ランタイムエラー : コンパイル済みのアプリケーションを実行している際に発生します。ランタイムエラーとは、SWF
ファイルを Flash ランタイム（Adobe Flash Player や Adobe AIR など）で再生中に発生するエラーです。多くの場合、発生と同時にランタイムエラーを処理してユーザーに報告し、アプリケーションの実行を継続するために必要な処置をとることができます。致命的なエラー（リモート Web サイトへの接続失敗、必須データのロード失敗など）の場合は、ア
プリケーションを安全に終了するための手段としてエラー処理を使用できます。

•

同期エラー：関数呼び出しの際に発生するランタイムエラーです。例えば、特定のメソッドを使用し、そのメソッドに無効な引数を渡すと、Flash ランタイムが例外をスローする場合などです。ほとんどのエラーは同期的に発生（該当するス
テートメントを実行した時点で発生）するので、制御フローはすぐに最も適切な catch ステートメントに渡されます。
次の抜粋コードの例では、プログラムがファイルをアップロードしようとする前に browse() メソッドを呼び出していな
いのでランタイムエラーがスローされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

51

エラー処理

var fileRef:FileReference = new FileReference();try{
fileRef.upload(new URLRequest("http://www.yourdomain.com/fileupload.cfm"));}catch (error:IllegalOperationError){
trace(error);// Error #2037: Functions called in incorrect sequence, or earlier// call was unsuccessful.
}

この場合、ファイルをアップロードしようとする前に browse() メソッドが呼び出されていないことが Flash Player によって検出されるので、ランタイムエラーが同期的にスローされます。
同期エラー処理について詳しくは、54 ページの「アプリケーションの同期エラーの処理」を参照してください。

•

非同期エラーは、通常のプログラムフロー外で発生するランタイムエラーです。非同期エラーでは、エラーをキャッチするイベントおよびイベントリスナーが生成されます。非同期操作とは、関数が操作を開始してその完了を待たない操作です。エラーイベントリスナーを作成して、アプリケーションまたはユーザーからの操作を待ち、操作が失敗した場合にはイベントリスナーでエラーをキャッチして、そのエラーイベントに応答できます。イベントリスナーはイベントハンド
ラー関数を呼び出して、エラーイベントに有効な方法で応答します。例えば、イベントハンドラーは、ユーザーにエラーの解決を促すダイアログボックスを起動できます。
前に示した、ファイルアップロードの同期エラーの例で考えてみます。browse() メソッドを正常に呼び出してからファイ
ルのアップロードを開始した場合、Flash Player からいくつかのイベントが送出されます。例えば、アップロードが開始したときには open イベントが送出され、ファイルのアップロードが正常に完了したときには complete イベントが送出されます。イベント処理は非同期なので（つまり、事前に設定済みの時刻に発生するのではないので）、次のように

addEventListener() メソッドを使用して、これら特定のイベントを監視します。
var fileRef:FileReference = new FileReference();fileRef.addEventListener(Event.SELECT, selectHandler);
fileRef.addEventListener(Event.OPEN, openHandler);
fileRef.addEventListener(Event.COMPLETE, completeHandler);
fileRef.browse();function selectHandler(event:Event):void{
trace("...select...");
var request:URLRequest = new URLRequest("http://www.yourdomain.com/fileupload.cfm");
request.method = URLRequestMethod.POST;
event.target.upload(request);}function openHandler(event:Event):void{
trace("...open...");}
function completeHandler(event:Event):void{
trace("...complete...");}

非同期エラー処理について詳しくは、60 ページの「エラーイベントおよびステータスへの応答」を参照してください。

•

不明な（キャッチされない）例外：それらのエラーに応答するための catch ステートメントなどの対応ロジックがないま
まスローされたエラーです。アプリケーションでエラーがスローされたとき、エラー処理のための該当する catch ステー
トメントまたはイベントハンドラーが現在のレベルまたはその上位レベルで見つからない場合、そのエラーは不明な例外と見なされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

52

エラー処理

不明なエラーが発生すると、ランタイムは uncaughtError イベントを送出します。このイベントは「グローバルなエラー
ハンドラー」とも呼ばれています。このイベントは SWF の UncaughtErrorEvents オブジェクトによって送出され、LoaderInfo.uncaughtErrorEvents プロパティを介して使用できます。uncaughtError イベントにリスナーが登録されていな
い場合、ランタイムでは不明なエラーを無視し、エラーによって SWF が停止されない限り、処理を続行しようとします。
また、デバッガーバージョンの Flash ランタイムでは、uncaughtError イベントを送出するだけでなく、不明なエラーに応答して実行中のスクリプトを終了します。その後で、その不明なエラーを trace ステートメントの出力に表示するか、
エラーメッセージをログファイルに書き込みます。例外オブジェクトが Error クラスのインスタンスまたはそのサブクラ
スのいずれかのインスタンスである場合、スタックトレース情報も出力に表示されます。デバッガーバージョンの Flash
ランタイムの使用について詳しくは、54 ページの「デバッガーバージョンの Flash ランタイムの操作」を参照してください。
注意：uncaughtError イベントの処理中に、uncaughtError ハンドラーからエラーイベントがスローされると、このイベントハンドラーが複数回呼び出されます。これによって、例外の無限ループが発生します。このようなシナリオを回避することをお勧めします。

ActionScript 3.0 におけるエラー処理
Flash Player 9 以降、Adobe AIR 1.0 以降
多くの場合、エラーを処理するためのロジックを構築しないままアプリケーションを実行できるので、開発者はエラー処理
をアプリケーションに組み入れることを後回しにする傾向があります。ただし、エラー処理がないと、何らかの要素が予想どおりに動作しない場合に、アプリケーションが簡単に機能を停止したり、ユーザーの作業を妨げたりする可能性があります。ActionScript 2.0 の Error クラスでは、特定のメッセージで例外をスローするためのロジックを独自の関数に組み入れることができました。エラー処理はユーザーフレンドリーなアプリケーションを作成する上で非常に重要であるため、ActionScript 3.0 ではエラーキャッチのために拡張アーキテクチャを追加しました。
注意：『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』では、様々なメソッドがスローする例外について説明していますが、各メソッドのすべての例外が記載されているとは限りません。メソッドがスローする例外の一部はメソッドの説明に記載されている場合でも、説明に明示的に記載されていないシンタックスエラーなどの問題について例外がスローされる場合もあります。

ActionScript 3.0 のエラー処理要素
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、次のような数多くのエラー処理用ツールを導入しています。

• Error クラス：ActionScript 3.0 には、エラーオブジェクトを生成する可能性がある状況の範囲を拡張するための幅広い
Error クラスがあります。システムエラー（MemoryError 状態など）、コーディングエラー（ArgumentError 状態など）、ネットワークおよび通信のエラー（URIError 状態など）、あるいはその他の状況のいずれであっても、アプリケー
ションが特定のエラー状態を処理しそれに応答するのに役立つ Error クラスがそれぞれに用意されています。各クラスについて詳しくは、63 ページの「Error クラスの比較」を参照してください。
•

説明のない異常終了の減少 : Flash Player の以前のバージョンでは、エラーは明示的に throw ステートメントを使用した
場合にしか生成および報告されませんでした。Flash Player 9 以降の Flash ランタイムでは、ActionScript のネイティブなメソッドおよびプロパティでランタイムエラーがスローされます。ランタイムエラーによって、これらの例外が発生した場合により効果的に処理し、各例外に対して個別に対応できるようになりました。

•

デバッグ中に表示されるエラーメッセージの明確化 : デバッガーバージョンの Flash ランタイムを使用すると、コードまたは状況に問題があるときに明確な内容を示すエラーメッセージが表示されるので、特定のコードブロックで異常が発生

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

53

エラー処理

した原因を容易に特定できます。これらのメッセージによって、より効果的にエラーを解決できます。詳しくは、54
ページの「デバッガーバージョンの Flash ランタイムの操作」を参照してください。

•

ユーザーに表示されるエラーメッセージの改良：Flash Player の以前のバージョンでは、upload() の呼び出しに失敗すると FileReference.upload() メソッドから Boolean 型の戻り値で false が返されましたが、その場合に考えられるエラーは 5
つありました。ActionScript 3.0 では、upload() メソッドの呼び出し時にエラーが発生すると、4 種類の特定のエラーを使用して、より正確なエラーメッセージをエンドユーザーに表示できます。

•

エラー処理の再定義 : 別個のエラーが多くの一般的な状況でスローされます。例えば、ActionScript 2.0 では、FileReference オブジェクトに値を設定するまで、name プロパティの値は null なので、name プロパティを使用したり表示したりする前に、値が設定されていて null でないことを確認する必要があります。ActionScript 3.0 では、FileReference オブジェクトの値が設定される前に name プロパティにアクセスしようとすると、値が未設定であることを示す IllegalOperationError 例外がスローされ、try..catch..finally ブロックを使用してエラーを処理することができます。詳しくは、55 ページの「try..catch..finally ステートメントの使用」を参照してください。

•

従来とほとんど変わらないパフォーマンス : try..catch..finally ブロックによるエラー処理に必要なリソース量は、ActionScript の以前のバージョンと同等またはわずかに増加する程度に抑えられています。

• ErrorEvent クラス : このクラスを使用すると、特定の非同期エラーイベントにリスナーを構築することができます。詳し
くは、60 ページの「エラーイベントおよびステータスへの応答」を参照してください。

エラー処理のアプローチ
Flash Player 9 以降、Adobe AIR 1.0 以降問題のある状況が生じない限り、コードにエラー処理ロジックが組み込まれていなくても、アプリケーションは正常に動作し続けることができます。しかし、積極的なエラー処理がないと、アプリケーションで問題が発生しても、ユーザーはその原因を知ることができません。
いろいろな方法によってアプリケーションでエラー処理にアプローチすることができます。エラー処理の主要な 3 つの方法の概略を次に示します。

• try..catch..finally ステートメントの使用：これらのステートメントは、発生する同期エラーをキャッチします。各種レベ
ルのコード実行で例外をキャッチするために、ステートメントを階層にネストすることができます。詳しくは、55 ページの「try..catch..finally ステートメントの使用」を参照してください。
•

独自のカスタムエラーオブジェクトの作成 : Error クラスを使用して、ビルトインのエラーの種類が扱わない特定の操作をアプリケーションで追跡するために、独自のカスタムエラーオブジェクトを作成することができます。これにより、カスタムエラーオブジェクトで try..catch..finally ステートメントを使用できます。詳しくは、59 ページの「カスタムエラー
クラスの作成」を参照してください。

•

エラーイベントに応答するイベントリスナーおよびハンドラーの記述 : この方法を採用すると、try..catch..finally ブロックのコードをいろいろな場所に記述することなく、グローバルなエラーハンドラーを作成して類似するイベントを処理できます。また、このアプローチを使用すると非同期エラーをキャッチする可能性が高くなります。詳しくは、60 ページの「エラーイベントおよびステータスへの応答」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

54

エラー処理

デバッガーバージョンの Flash ランタイムの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
開発者のデバッグ作業用に特別版の Flash ランタイムが用意されています。このデバッガーバージョンの Flash Player を入手するには、Adobe Flash Professional または Adobe Flash Builder をインストールします。また、ADL と呼ばれる
Adobe AIR アプリケーション向けデバッグ用ユーティリティは、これらのツールをインストールしたときに同時にインストールされますが、Adobe AIR SDK にも付属しています。
デバッガーバージョンとリリースバージョンの Flash Player および Adobe AIR では、エラーの表示方法に重要な差異があります。デバッガーバージョンの場合はエラーのタイプ（一般の Error、IOError、EOFError など）、エラー番号および人間が理解できるエラーメッセージが表示されますが、リリースバージョンの場合はエラーのタイプとエラー番号しか表示されません。例えば、次のようなコードがあるとします。
try{tf.text = myByteArray.readBoolean();}catch (error:EOFError){
tf.text = error.toString();}

readBoolean() メソッドがデバッガーバージョンの Flash Player で EOFError をスローした場合、tf テキストフィールドに、「EOFError：ファイルの終端（EOF）が検出されました。」というメッセージが表示されます。
同じコードをリリースバージョンの Flash Player または Adobe AIR 上で実行すると、「エラー #2030」というテキストが表示されます。
注意：デバッガープレーヤーは、「allComplete」という名前のイベントをブロードキャストして、「allComplete」という名前のカスタムイベントの作成を避けます。そうしないと、デバッグ時に予期しないビヘイビアーが発生します。
使用するリソースやサイズを最小限に抑えるため、リリースバージョンにはエラーメッセージのストリングが含まれていません。ドキュメント（『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の付録）でエラー番号を検索して、関連するエラーメッセージを確認してください。デバッガーバージョンの Flash Player および AIR 上でエラーを再現して、メッセージ全体を確認してください。

アプリケーションの同期エラーの処理
Flash Player 9 以降、Adobe AIR 1.0 以降
最も一般的なエラー処理は同期エラー処理のロジックで、アプリケーションの実行時に同期エラーをキャッチするためのス
テートメントをコードに挿入します。この種類のエラー処理では、関数失敗時のランタイムエラーをアプリケーションで認識してそこから回復できます。同期エラーをキャッチするロジックに try..catch..finally ステートメントがあります。このス
テートメントは実際に操作を試し、Flash ランタイムからのエラー応答をキャッチし、失敗した操作を処理するために最後に何らかの操作を実行します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

55

エラー処理

try..catch..finally ステートメントの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
同期的なランタイムエラーを扱う場合は、try..catch..finally ステートメントを使用してエラーをキャッチします。ランタイム
エラーが発生すると、Flash ランタイムは例外をスローします。これは、通常の実行処理を中断し、Error 型の特殊なオブジェクトを作成することを意味します。この Error オブジェクトは、該当する最初の catch ブロックにスローされます。

try ステートメントは、エラーが発生する可能性のあるステートメントを囲みます。try ステートメントには必ず catch ステー
トメントが伴います。try ステートメントのブロック内にある何らかのステートメントでエラーが検出されると、その try ス
テートメントに対応する catch ステートメントが実行されます。
finally ステートメントで囲んだステートメントは、try ブロックでエラーが発生したかどうかに関係なく実行されます。エ
ラーが発生しなかった場合は、try ブロック内のステートメントが終了した後で、finally ブロック内のステートメントが実行されます。エラーが発生した場合は、適切な catch ステートメントがまず実行され、その後で finally ブロック内のステート
メントが実行されます。

try..catch..finally ステートメントを使用する際のシンタックスを次のコードに示します。
try{// some code that could throw an error}
catch (err:Error){// code to react to the error}
finally{// Code that runs whether an error was thrown. This code can clean// up after the error, or take steps to keep the application running.
}

個々の catch ステートメントは、処理する特定の例外の型を指定します。catch ステートメントが指定できるのは Error クラスのサブクラスのみです。各 catch ステートメントは上から順にチェックされ、スローされたエラーに該当する最初の catch
ステートメントだけが実行されます。したがって、先に上位レベルの Error クラスをチェックし、その Error クラスのサブクラスを後からチェックすると、上位レベルの Error クラスに対する処理しか実行されません。この動作を説明するコードを次に示します。
try{
throw new ArgumentError("I am an ArgumentError");}catch (error:Error){
trace("<Error> " + error.message);}catch (error:ArgumentError){
trace("<ArgumentError> " + error.message);}

上のコードを実行すると、次のように表示されます。
<Error> I am an ArgumentError

ArgumentError を正しくキャッチするには、次のコードのように、最も具体的なエラーのチェックが最初で、下に行くほど一般性の強いエラーのチェックになるような順序にしてください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

56

エラー処理

try
{
throw new ArgumentError("I am an ArgumentError");}catch (error:ArgumentError){
trace("<ArgumentError> " + error.message);}catch (error:Error){
trace("<Error> " + error.message);}

ActionScript API に含まれるいくつかのメソッドとプロパティでは、実行中にエラーが発生するとランタイムエラーをス
ローします。例えば、Sound クラスの close() メソッドは、オーディオストリームを閉じることができない場合に IOError
をスローします。次にコード例を示します。
var mySound:Sound = new Sound();try{
mySound.close();}catch (error:IOError){// Error #2029: This URLStream object does not have an open stream.
}『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』をよく読むと、どのメソッドが例外をスローするかがわかります。詳しくは、各メソッドの説明に記載されています。

throw ステートメント
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションの実行中にエラーが発生すると、Flash ランタイムは例外をスローします。また、アプリケーション内でthrow ステートメントを使用すれば、開発者が例外を明示的にスローすることもできます。明示的にエラーをスローした場
合は、Error クラスまたはそのサブクラスのインスタンスをスローすることをお勧めします。次のコードは、Error クラスのインスタンス MyErr をスローする throw ステートメントを示し、最後に、エラーのスロー後に応答するために関数
myFunction() を呼び出しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

57

エラー処理

var MyError:Error = new Error("Encountered an error with the numUsers value", 99);
var numUsers:uint = 0;
try{
if (numUsers == 0){
trace("numUsers equals 0");}}catch (error:uint){
throw MyError; // Catch unsigned integer errors.
}
catch (error:int){
throw MyError; // Catch integer errors.
}
catch (error:Number){
throw MyError; // Catch number errors.
}
catch (error:*){throw MyError; // Catch any other error.
}
finally{
myFunction(); // Perform any necessary cleanup here.
}

このように、catch ステートメントは最も限定的なデータ型から順に記述してください。Number データ型に対する catch ス
テートメントを最初に記述した場合、uint データ型や int データ型に対する catch ステートメントは実行されません。
注意：Java プログラミング言語では、例外をスローする可能性があるすべての関数はその旨を宣言することが義務付けられています。宣言するには、スローする可能性がある例外クラスを列挙した throws 節を関数の宣言に含めます。ActionScript
では、関数がスローする例外を宣言する必要はありません。

単純なエラーメッセージの表示
Flash Player 9 以降、Adobe AIR 1.0 以降
新しい例外およびエラーイベントモデルがもたらす最大のメリットの 1 つに、アクションが失敗したタイミングと理由をユーザーに示すことができるという点があります。コードを記述する際、メッセージの表示と応答オプションの提示がある
ようにします。
次のコードは、エラーをテキストフィールドに表示する単純な try..catch ステートメントを示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

58

エラー処理

package{import flash.display.Sprite;
import flash.text.TextField;
public class SimpleError extends Sprite{
public var employee:XML =<EmpCode><costCenter>1234</costCenter><costCenter>1-234</costCenter></EmpCode>;
public function SimpleError(){try{
if (employee.costCenter.length() != 1){
throw new Error("Error, employee must have exactly one cost center assigned.");}}catch (error:Error){
var errorMessage:TextField = new TextField();
errorMessage.autoSize = TextFieldAutoSize.LEFT;
errorMessage.textColor = 0xFF0000;
errorMessage.text = error.message;
addChild(errorMessage);}}}}

広範囲のエラークラスおよびビルトインのコンパイルエラーを使用することで、ActionScript 3.0 では以前のバージョンのActionScript に比べ、何かが失敗したときにその理由に関してより多くの情報が提供されます。この情報により、エラー処理に優れ、安定性の向上したアプリケーションを構築できます。

エラーの再スロー
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションの開発時には、エラーを適切に処理できない場合にエラーを再スローする必要が生じることがあります。
例えば、次のコードはネストされた try..catch ブロックを示し、ネストされた catch ブロックでエラーを処理できない場合には独自の ApplicationError を再スローします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

59

エラー処理

try
{
try
{
trace("<< try >>");
throw new ApplicationError("some error which will be rethrown");}catch (error:ApplicationError){
trace("<< catch >> " + error);
trace("<< throw >>");
throw error;}
catch (error:Error){
trace("<< Error >> " + error);}}catch (error:ApplicationError){
trace("<< catch >> " + error);}

このコードを実行すると次のような内容が表示されます。
<< try >><< catch >> ApplicationError: some error which will be rethrown<< throw >><< catch >> ApplicationError: some error which will be rethrown

ネストされた try ブロックで独自の ApplicationError エラーをスローすると、それに続く catch ブロックがエラーをキャッチします。このネストされた catch ブロックではエラー処理を試みますが、処理できない場合は ApplicationError オブジェ
クトを上位の try..catch ブロックに対してスローします。

カスタムエラークラスの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript では、標準 Error クラスのいずれかを拡張し、目的に特化した独自の Error クラスを作成できます。独自のError クラスを作成する理由は、次のようにいくつかあります。

•

アプリケーションに特有のエラー群を識別するため :例えば、Flash ランタイムでトラップされたエラーとは別に、アプリケーションのコードでスローされたエラーに対して異なるアクションをとる場合などです。try..catch ブロックで新しいエラーデータ型を追跡するために、Error クラスのサブクラスを作成することができます。

•

アプリケーション内で生成したエラーについて独自の方法でエラー情報を表示するため :例えば、特定の方法でエラーメッセージの形式を設定するために新しい toString() メソッドを作成できます。また、必要に応じて lookupErrorString() メソッドを定義することもできます。このメソッドはパラメーターで指定したエラーコードに対して、ユーザーの言語環境設定に応じた適切な言語のメッセージを取得します。

独自の Error クラスは、ActionScript コア Error クラスを拡張したものである必要があります。次に、Error クラスを拡張した、独自の AppError クラスの例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

60

エラー処理

public class AppError extends Error{
public function AppError(message:String, errorID:int){
super(message, errorID);}}

次に、プロジェクトで AppError を使用した例を示します。
try{throw new AppError("Encountered Custom AppError", 29);}
catch (error:AppError){
trace(error.errorID + ": " + error.message)}

注意：サブクラスで Error.toString() メソッドをオーバーライドする場合は、...（残り）パラメーターを 1 つだけ指定します。

ActionScript 3.0 が基づいている ECMAScript 言語仕様では、Error.toString() メソッドをそのように定義しているため、ActionScript 3.0 では、後方互換のため同じようこのメソッドを定義しています。したがって、Error.toString() メソッドを
オーバーライドする際は正確にこのパラメーターを踏襲してください。ただし、実行時に toString() メソッドにパラメー
ターを渡しても、これらのパラメーターは無視されます。

エラーイベントおよびステータスへの応答
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 のエラー処理で向上した最も重要な機能の 1 つは、アプリケーションの実行中に非同期のランタイムエ
ラーに応答するためのエラーイベント処理のサポートです。非同期エラーの定義について詳しくは、50 ページの「エラーの種類」を参照してください。
エラーイベントに応答するためにイベントリスナーとイベントハンドラーを作成することができます。多くのクラスが、他のイベントの送出時と同じ方法でエラーイベントを送出します。例えば、XMLSocket クラスのインスタンスは通常、3 種類のイベント（Event.CLOSE、Event.CONNECT および DataEvent.DATA）を送出します。ただし、問題が発生した場合には、

XMLSocket クラスは IOErrorEvent.IOError または SecurityErrorEvent.SECURITY_ERROR を送出できます。イベントリス
ナーとイベントハンドラーについて詳しくは、119 ページの「イベント処理」を参照してください。
エラーイベントは、次の 2 つのカテゴリのいずれかに該当します。

• ErrorEvent クラスを拡張したエラーイベント
flash.events.ErrorEvent クラスは、アプリケーションの実行時におけるネットワークおよび通信の操作に関係したエラーを管理するためのプロパティおよびメソッドを含みます。AsyncErrorEvent、IOErrorEvent、およびSecurityErrorEvent クラスは ErrorEvent クラスを拡張したものです。デバッガーバージョンの Flash ランタイムを使用している場合は、リスナー関数が検出されなくても、実行時にダイアログボックスでエラーイベントが通知されます。

•

ステータスに基づくエラーイベント
ステータスに基づくエラーイベントは、ネットワークと通信のクラスの netStatus および status プロパティに関係します。
データの読み取りまたは書き込み時に Flash ランタイムで問題が検出されると、使用中のクラスオブジェクトに応じて、netStatus.info.level または status.level プロパティが値「error」に設定されます。このエラーに応答するため、イベントハ
ンドラー関数で level プロパティの値が「error」かどうかをチェックします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

61

エラー処理

エラーイベントの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ErrorEvent クラスとそのサブクラスは、データの読み取りまたは書き込みを行うとき Flash ランタイムから送出されるエ
ラーを処理するためにエラーの種類を格納します。
次の例では、ローカルファイルを読み取る際に検出されたエラーを表示するため、try..catch ステートメントおよびエラーイ
ベントハンドラーの両方を使用しています。もっと高度な処理コードを追加することで、ユーザーにオプションを表示する
か、またはコメントの「your error-handling code here」の場所でエラーを自動的に処理することもできます。
package{import flash.display.Sprite;
import flash.errors.IOError;
import flash.events.IOErrorEvent;import flash.events.TextEvent;import flash.media.Sound;import flash.media.SoundChannel;
import flash.net.URLRequest;
import flash.text.TextField;
import flash.text.TextFieldAutoSize;public class LinkEventExample extends Sprite{
private var myMP3:Sound;public function LinkEventExample(){myMP3 = new Sound();var list:TextField = new TextField();
list.autoSize = TextFieldAutoSize.LEFT;
list.multiline = true;
list.htmlText = "<a href=\"event:track1.mp3\">Track 1</a><br>";
list.htmlText += "<a href=\"event:track2.mp3\">Track 2</a><br>";addEventListener(TextEvent.LINK, linkHandler);
addChild(list);}
private function playMP3(mp3:String):void{try{
myMP3.load(new URLRequest(mp3));
myMP3.play();}
catch (err:Error)

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

62

エラー処理

{
trace(err.message);// your error-handling code here}
myMP3.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);}private function linkHandler(linkEvent:TextEvent):void{
playMP3(linkEvent.text);// your error-handling code here}
private function errorHandler(errorEvent:IOErrorEvent):void{
trace(errorEvent.text);// your error-handling code here}}}

ステータス変化イベントの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash ランタイムでは、アプリケーションの実行中に、level プロパティをサポートするクラスの netStatus.info.level プロパティまたは status.level プロパティの値を動的に変化させます。netStatus.info.level プロパティを持つクラスは、

NetConnection、NetStream および SharedObject です。status.level プロパティを持つクラスは、HTTPStatusEvent、Camera、Microphone および LocalConnection です。level 値の変化に応答して通信エラーを追跡するには、ハンドラー
関数を記述します。
次の例では、netStatusHandler() 関数を使用して、level プロパティの値をテストしています。level プロパティがエラーが検出されたことを示している場合は、「Video stream failed」というメッセージをトレースします。
package{import flash.display.Sprite;
import flash.events.NetStatusEvent;import flash.events.SecurityErrorEvent;import flash.media.Video;
import flash.net.NetConnection;
import flash.net.NetStream;
public class VideoExample extends Sprite{
private var videoUrl:String = "Video.flv";
private var connection:NetConnection;
private var stream:NetStream;
public function VideoExample(){connection = new NetConnection();connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);connection.connect(null);}
private function netStatusHandler(event:NetStatusEvent):void{if (event.info.level == "error")

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

63

エラー処理

{
trace("Video stream failed")}
else{
connectStream();}}private function securityErrorHandler(event:SecurityErrorEvent):void{
trace("securityErrorHandler: " + event);}
private function connectStream():void{
var stream:NetStream = new NetStream(connection);var video:Video = new Video();video.attachNetStream(stream);
stream.play(videoUrl);
addChild(video);}}}

Error クラスの比較
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript には多数の定義済み Error クラスがあります。一方、アプリケーションのコードでも同じ Error クラスを使用できます。ActionScript 3.0 の Error クラスは、ActionScript コア Error クラスと flash.error パッケージ Error クラスの 2つに大別されます。flash.error パッケージには、ActionScript 3.0 のアプリケーション開発およびデバッグを支援するクラスが追加されています。

コア Error クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
コア Error クラスとしては、Error、ArgumentError、EvalError、RangeError、ReferenceError、SecurityError、SyntaxError、TypeError、URIError、VerifyError の各クラスがあります。いずれのクラスもトップレベルの名前空間に属します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

64

エラー処理

クラス名

説明

注記

Error

Error クラスは例外をスローするためのクラスであり、
ECMAScript に定義されている他の例外クラス（EvalError、RangeError、ReferenceError、SyntaxError、TypeError、URIError）の基本クラスでError クラスはすべてのランタイムエラーの基本クラスであるだけ
でなく、独自に作成する Error クラスの基本クラスとすることが推奨されています。

す。

ArgumentError

ArgumentError クラスは、関数呼び出しで指定された

例えば、次のような状況でパラメーターエラーが発生します。

パラメーターの値がその関数の定義に適合していないために発生するエラーを表します。

• メソッドに対して指定された引数の個数が多すぎる、または少なすぎる場合。

• 列挙のメンバーを指定することが要求される引数に、それ以外の値が指定された場合。

EvalError

EvalError 例外は、Function クラスのコンストラクター ActionScript 3.0 では eval() 関数のサポートが除外されており、こにパラメーターが渡された場合または eval() 関数がユー
ザーコードで呼び出された場合にスローされます。

の関数を使用するとエラーが発生します。

Flash Player の以前のバージョンでは、変数、プロパティ、オブ
ジェクトまたはムービークリップに名前でアクセスする際に eval()関数が使用されていました。

RangeError

RangeError 例外は、数値の値が許容される範囲に収ま

例えば、Timer クラスに対する遅延の指定が負の値や無限である場

らない場合にスローされます。

合は RangeError がスローされます。また、表示オブジェクトを無限の深度に追加しようとした場合も RangeError がスローされます。

ReferenceError

ReferenceError 例外は、sealed 指定された（動的でな 未定義の変数に関する例外は潜在的なバグの発見につながり、ソフい）オブジェクトに対して未定義プロパティを参照しようとした場合にスローされます。ActionScript 3.0 より前のバージョンでは、undefined であるプロパティにア
クセスしようとしても ActionScript コンパイラーのエ

トウェア品質の向上に役立ちます。しかし、変数を初期化する必要がない従来の仕様に慣れた開発者は、ActionScript の動作が変更されたことによりコーディング上の習慣を変更する必要があります。

ラーはスローされませんでした。ただし、ActionScript
3.0 ではこの状況で ReferenceError 例外をスローします。

SecurityError

SecurityError 例外は、セキュリティ違反が発生してアクセスが拒否された場合に発生します。

例えば、次のような状況でセキュリティエラーが発生します。

• セキュリティサンドボックスの境界をまたいで、許可されていないプロパティアクセスやメソッド呼び出しを実行した場合。

• セキュリティサンドボックスで許可されていない URL にアクセスしようとした場合。

• ポートへのソケット接続が試行されたけれども、必要なソケッ
トポリシーファイルが存在しなかった場合。

• ユーザーのカメラやマイクへのアクセスを試み、そのアクセスがユーザーによって拒否された場合。

SyntaxError

SyntaxError 例外は、ActionScript コード内で解析エラーが発生した場合にスローされます。

SyntaxError は次の状況でスローされます。

• ActionScript では、RegExp クラスで無効な正規表現を解析した場合に SyntaxError 例外をスローします。

• ActionScript では、XMLDocument クラスで無効な XML を解析した場合に SyntaxError 例外をスローします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

65

エラー処理

クラス名

TypeError

説明

注記

TypeError 例外は、オペランドに要求される型と実際の TypeError は次の状況でスローされます。
型が異なる場合にスローされます。

• 関数またはメソッドの実際のパラメーターを、形式上必要とされるパラメーターの型に変換できない場合。

• 変数に割り当てられた値を、その変数の型に強制的に変換できない場合。

• is または instanceof 演算子の右辺が有効な型でない場合。
• super キーワードの使用方法が不正な場合。
• プロパティへの参照が複数のバインディングに解決され、結果があいまいである場合。

• 互換性のないオブジェクトに対してメソッドが呼び出された場合。例えば、RegExp クラスのメソッドが汎用オブジェクトに「移植」されて呼び出された場合に TypeError 例外がスローされます。

URIError

URIError 例外は、グローバルな URI 処理関数のいずれかが定義に合わない方法で使用された場合にスローされます。

VerifyError

VerifyError 例外は、不正な形式または破損した SWF
ファイルが検出された場合にスローされます。

URIError は次の状況でスローされます。
有効な URL を必要とする Flash Player API 関数（Socket.connect() など）に対し、無効な URI を指定した場合。

SWF ファイルが別の SWF ファイルをロードした場合、親の SWF
ファイルはロードされた SWF ファイルが生成する VerifyError をキャッチできます。

flash.error パッケージ Error クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
flash.error パッケージの Error クラスは、Flash ランタイム API の一部と見なされます。前述した他の Error クラスと違い、flash.error パッケージは Flash ランタイム（Flash Player や Adobe AIR など）に特有のエラーイベントを伝達するために使用されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

66

エラー処理

クラス名

説明

注記

EOFError

EOFError 例外は、取得できるデータの末尾よりも後 例えば、IDataInput インターフェイスの読み取りメソッの部分を読み取ろうとした場合にスローされます。

ドのいずれかを呼び出したとき、その読み取り要求を満たす量のデータが存在しない場合は EOFError がスローされます。

IllegalOperationError

IllegalOperationError 例外は、メソッドが実装され 例えば、次のような状況で無効な操作エラーの例外が発ていないか、使用方法に実装が対応していない場合にスローされます。

生します。

• 基本クラス（DisplayObjectContainer など）に、ス
テージでサポートされている範囲を超えた機能がある場合。例えば、stage.mask を使用してステージ上のマスクを取得または設定しようとすると、Flash ランタイムにより「Stage クラスは、このプロパティまたはメ
ソッドを実装しません」というメッセージと共にIllegalOperationError がスローされます。

• サブクラスで、継承する必要がなくサポートすると不都合が生じるようなメソッドを継承した場合。

• アクセシビリティのサポートを含めずにコンパイルされた Flash Player の環境で、特定のアクセシビリティ
関連メソッドを呼び出した場合。

• ランタイムバージョンの Flash Player でオーサリング
専用の機能を呼び出した場合。

• タイムライン上に配置されたオブジェクトに対して名前を設定しようとした場合。

IOError

IOError 例外は、ある種の I/O 例外が発生した場合に 例えば、未接続または切断済みのソケットに対して読み書き操作を実行しようとすると、このエラーが発生します。

スローされます。

MemoryError

MemoryError 例外は、メモリ割り当て要求が失敗し デフォルトでは、ActionScript 仮想マシン 2 はた場合にスローされます。
ActionScript プログラムが割り当てを受けられるメモリの量を制限しません。デスクトップシステム環境では、
メモリ割り当て失敗は頻繁に発生するエラーではありません。操作に必要とされるメモリをシステムが割り当てられないという状況は、デスクトップシステムではほとん
ど発生しないからです。32 ビット Microsoft®
Windows® プログラム（アドレス空間が 2 GB）で 3 GBの割り当てを要求した場合などは、要求を満たすことが不可能であるため、この例外が発生します。

ScriptTimeoutError

ScriptTimeoutError 例外は、スクリプトのタイムア 悪意のある開発者によってこの例外がキャッチされ、無す。ScriptTimeoutError 例外をキャッチすると、ス限ループから脱出できない事態が発生するのを防ぐために、1 つのスクリプトについて実行中にスローされる

クリプトのタイムアウトをより安全な方法で処理できます。例外ハンドラーを用意しない場合は、不明なません。それ以降の ScriptTimeoutError 例外はアプリ

例外のハンドラーによってダイアログボックスにエラーメッセージが表示されます。

ケーションのコードではキャッチされず、不明な例外のハンドラーが直ちに実行されます。

ウト間隔である 15 秒が経過した場合にスローされま

StackOverflowError

ScriptTimeoutError 例外は最初の 1 回しかキャッチでき

StackOverflowError 例外は、当該スクリプトで使用 StackOverflowError 例外は、無限の再帰が発生したことできるスタックを使い切った場合にスローされます。 を示す場合があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

67

エラー処理

エラー処理の例：CustomErrors アプリケーション
Flash Player 9 以降、Adobe AIR 1.0 以降
ここでは CustomErrors アプリケーションを使って、アプリケーション構築時のカスタムエラーを操作する手法について示します。それらの手法は、次のとおりです。

• XML パケットの検証•

カスタムエラーの記述•

カスタムエラーのスロー•

エラースロー時のユーザーへの通知

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。CustomErrors アプリケーションのファイルは、Samples/CustomError フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

CustomErrors.mxml

Flash（FLA）または Flex（MXML）のメインアプリケーションファイル。

またはCustomErrors.fla
com/example/programmingas3/errors/ApplicationError.as

FatalError および WarningError の両方の基本エラークラスとして機能するクラス。

com/example/programmingas3/errors/FatalError.as

アプリケーションによってスローされる FatalError エラーを定義するクラス。このクラスは独自の ApplicationError クラスを拡張します。

com/example/programmingas3/errors/Validator.as

ユーザー指定の従業員 XML パケットを検証する単一のメソッドを定義するクラス。

com/example/programmingas3/errors/WarningError.as

アプリケーションによってスローされる WarningError エラーを定義するクラス。このクラスは独自の ApplicationError クラスを拡張します。

CustomErrors アプリケーションの概要
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションがロードされるとき、Flex アプリケーションでは initApp() メソッドが 呼び出され、Flash Professional
アプリケーションではタイムライン（非関数）コードが実行されます。このコードは、Validator クラスによって検証されるサンプルの XML パケットを定義します。次のコードが実行されます。
employeeXML =<employee id="12345"><firstName>John</firstName><lastName>Doe</lastName><costCenter>12345</costCenter><costCenter>67890</costCenter></employee>;}

XML パケットは後で、TextArea コンポーネントインスタンスのステージ上に表示されます。この手順により、再検証を試みる前に XML パケットを変更できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

68

エラー処理

ユーザーが「Validate」ボタンをクリックすると、validateData() メソッドが呼び出されます。このメソッドは、Validator
クラスの validateEmployeeXML() メソッドを使用して、従業員 XML パケットを検証します。validateData() メソッドのコードを次に示します。
function validateData():void{try{
var tempXML:XML = XML(xmlText.text);
Validator.validateEmployeeXML(tempXML);status.text = "The XML was successfully validated.";}catch (error:FatalError){
showFatalError(error);}catch (error:WarningError){
showWarningError(error);}catch (error:Error){
showGenericError(error);}}

最初に、TextArea コンポーネントインスタンス xmlText のコンテンツを使用して、一時的な XML オブジェクトが作成されます。次に、独自の Validator クラス（com.example.programmingas3/errors/Validator.as）のvalidateEmployeeXML() メソッドが呼び出され、一時的な XML オブジェクトをパラメーターとして渡します。XML パケッ
トが有効な場合、Label コンポーネントインスタンス status が成功メッセージを表示して、アプリケーションが終了します。
validateEmployeeXML() メソッドがカスタムエラーをスローした（つまり、FatalError、WarningError または汎用 Errorが発生した）場合は、適切な catch ステートメントを実行して、showFatalError()、showWarningError() またはshowGenericError() メソッドのいずれかを呼び出します。これらの各メソッドは、適切なメッセージを statusText というテキスト領域に表示して、発生した具体的なエラーをユーザーに通知します。各メソッドは、具体的なメッセージで Label コ
ンポーネントインスタンス status の更新も行います。
従業員 XML パケットを検証しようとしたときに致命的なエラーが発生した場合は、次のコードが示すように、そのエラー
メッセージが statusText テキスト領域に表示され、TextArea コンポーネントインスタンス xmlText および Button コンポー
ネントインスタンス validateBtn が無効になります。
function showFatalError(error:FatalError):void{
var message:String = error.message + "\n\n";var title:String = error.getTitle();statusText.text = message + " " + title + "\n\nThis application has ended.";this.xmlText.enabled = false;
this.validateBtn.enabled = false;
hideButtons();}

致命的なエラーではなく警告エラーが発生した場合は、そのエラーメッセージが statusText TextArea インスタンスに表示されますが、xmlText TextField および Button コンポーネントインスタンスは無効になりません。showWarningError() メソッ
ドが、カスタムエラーメッセージを statusText テキスト領域に表示します。また、このメッセージでは、XML の検証を続行
するか、スクリプトを中止するかをユーザーに尋ねます。showWarningError() メソッドの抜粋コードを次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

69

エラー処理

function showWarningError(error:WarningError):void{
var message:String = error.message + "\n\n" + "Do you want to exit this application?";showButtons();
var title:String = error.getTitle();statusText.text = message;}

ユーザーが「Yes」または「No」ボタンをクリックすると、closeHandler() メソッドが呼び出されます。closeHandler() メ
ソッドの抜粋コードを次に示します。
function closeHandler(event:CloseEvent):void{switch (event.detail){case yesButton:
showFatalError(new FatalError(9999));
break;
case noButton:
statusText.text = "";hideButtons();
break;}}

ユーザーが「Yes」をクリックしてスクリプトの中止を選択した場合は、FatalError がスローされ、その結果、アプリケー
ションは終了します。

独自のバリデーターの構築
Flash Player 9 以降、Adobe AIR 1.0 以降
独自の Validator クラスは、1 つのメソッド validateEmployeeXML() を含みます。validateEmployeeXML() メソッドは、1 つの引数 employee（検証対象の XML パケット）を受け取ります。validateEmployeeXML() メソッドを次に示します。
public static function validateEmployeeXML(employee:XML):void{// checks for the integrity of items in the XML
if (employee.costCenter.length() < 1){throw new FatalError(9000);}if (employee.costCenter.length() > 1){
throw new WarningError(9001);}
if (employee.ssn.length() != 1){
throw new FatalError(9002);}}

検証のため、従業員は 1 つ（1 つのみ）の原価部門に属していなければなりません。従業員がいずれの原価部門にも属していない場合は、FatalError がスローされてメインアプリケーションファイルの validateData() メソッドに移ります。従業員が複数の原価部門に属している場合は、WarningError がスローされます。XML バリデーターの最終チェックでは、ユーザーに定義されている社会保障番号が厳密に 1 つであることを確認します（XML パケットの ssn ノード）。存在する ssn ノードが厳密に 1 つでない場合は、FatalError エラーがスローされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

70

エラー処理

validateEmployeeXML() メソッドにチェックを追加することもできます。例えば、ssn ノードに格納されている番号が有効であることを確認する場合や、従業員に少なくとも 1 つの電話番号と電子メールアドレスが割り当てられていて、その両方の値が有効であることを確認する場合などです。各従業員に一意の ID を割り当てその上司の ID を指定するために、XML を変更することもできます。

ApplicationError クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
ApplicationError クラスは、FatalError および WarningError の両方の基本クラスとして機能します。ApplicationError
クラスは Error クラスを拡張して、独自にメソッドおよびプロパティを定義します。エラー ID、重大度、独自のエラーコー
ドおよびメッセージを格納する XML オブジェクトなどを定義します。このクラスでは、エラーの種類ごとの重大度を定義するのに使用する 2 つの静的定数も定義します。
ApplicationError クラスのコンストラクターメソッドを次に示します。
public function ApplicationError(){messages =<errors><error code="9000"><![CDATA[Employee must be assigned to a cost center.]]></error><error code="9001"><![CDATA[Employee must be assigned to only one cost center.]]></error><error code="9002"><![CDATA[Employee must have one and only one SSN.]]></error><error code="9999"><![CDATA[The application has been stopped.]]></error></errors>;}

XML オブジェクトの各エラーコードは、一意の数値コードとエラーメッセージを格納します。次の getMessageText() メソッ
ドが示すように、エラーメッセージは、E4X を使用してエラーコードで簡単に調べることができます。
public function getMessageText(id:int):String{var message:XMLList = messages.error.(@code == id);
return message[0].text();}

getMessageText() メソッドは、1 つの整数引数 id を受け取り、ストリングを返します。id 引数には、調べるエラーのエラー
コードを指定します。例えば、id を 9001 で渡すと、従業員は 1 つの原価部門にのみ割り当てられる必要があることを示す
エラーを受け取ります。複数のエラーでエラーコードが同じ場合、ActionScript は検出された最初の結果のみについてエラーメッセージを返します（返された XMLList オブジェクトの message[0]）。
このクラスの次のメソッドである getTitle() はパラメーターを受け取らず、この特定のエラーのエラー ID を格納するストリ
ング値を返します。この値を使用すると、XML パケットの検証時に発生した正確なエラーを簡単に識別できます。
getTitle() メソッドの抜粋コードを次に示します。
public function getTitle():String{
return "Error #" + id;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

71

エラー処理

ApplicationError クラスの最後のメソッドは toString() です。 このメソッドは、エラーメッセージの表現をカスタマイズするために、Error クラスに定義されている関数をオーバーライドします。発生した特定のエラー番号とメッセージを識別する
ストリングを返します。
public override function toString():String{
return "[APPLICATION ERROR #" + id + "] " + message;}

FatalError クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
FatalError クラスは独自の ApplicationError クラスを拡張して、3 つのメソッド（FatalError コンストラクター、
getTitle() および toString()）を定義します。最初のメソッドである FatalError コンストラクターは、1 つの整数引数 errorIDを受け取り、ApplicationError クラスに定義されている静的定数値を使用してエラーの重大度を設定し、ApplicationError クラスの getMessageText() メソッドを呼び出して特定のエラーのエラーメッセージを取得します。
FatalError コンストラクターを次に示します。
public function FatalError(errorID:int){
id = errorID;
severity = ApplicationError.FATAL;
message = getMessageText(errorID);}

FatalError クラスの次のメソッドである getTitle() は、ApplicationError クラスで以前に定義された getTitle() メソッドを
オーバーライドし、致命的なエラーが発生したことをユーザーに通知するためにタイトルにテキスト「-- FATAL」を追加します。getTitle() メソッドを次に示します。
public override function getTitle():String{
return "Error #" + id + " -- FATAL";}

このクラスの最後のメソッドである toString() は、ApplicationError クラスに定義されている toString() メソッドをオー
バーライドします。toString() メソッドを次に示します。
public override function toString():String{
return "[FATAL ERROR #" + id + "] " + message;}

WarningError クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
WarningError クラスは ApplicationError クラスを拡張し、FatalError クラスとほぼ同一です。ただし、次のコードが示
すようなマイナー変更があり、エラー重大度は ApplicationError.FATAL ではなく ApplicationError.WARNING に設定されます。
public function WarningError(errorID:int){
id = errorID;
severity = ApplicationError.WARNING;
message = super.getMessageText(errorID);}

最終更新日 2015/10/14

72

第 5 章：正規表現の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
正規表現とは、ストリング内で条件に一致するテキストの検索および操作に使用するパターンの表記法です。正規表現はス
トリングのように見えますが、その内容には、パターンや繰り返しを表す特殊なコードが含まれています。例えば、次の正規表現は、先頭が A であり、その後に 1 桁以上の数字が続くようなストリングに一致します。
/A\d+/

以下のトピックでは、正規表現を作成するための基本的なシンタックスについて説明します。正規表現には複雑な要素や微妙に意味が異なる機能が数多く存在するため、詳細については、Web や書籍で他の参考資料を参照してください。ただし、プログラミング環境が異なると正規表現の実装も異なっている場合があるため注意が必要です。ActionScript 3.0 では、

ECMAScript Edition 3 言語仕様（ECMA-262）の定義に基づいて正規表現を実装しています。
関連項目

RegExp正規表現の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
正規表現は、文字のパターンを表します。一般的に、正規表現はテキスト値が特定のパターンに準拠していることを確認する場合（ユーザーが入力した電話番号の桁数が適切であることを確認する場合など）や、特定のパターンと一致するテキス
トを置き換える場合に使用されます。
正規表現には、単純なものもあります。例えば、特定のストリングが「ABC」に一致するかどうかを確認する場合や、ストリング内に出現するすべての「ABC」を別のテキストに置き換える場合を考えてください。その場合、文字 A、B、C が順に連続して出現するパターンを定義する次の正規表現を使用できます。
/ABC/

正規表現リテラルを囲む区切り文字はスラッシュ（/）です。
正規表現では、複雑なパターンや解読困難なパターンが使用されることもあります。例えば、次の正規表現は有効な電子メールアドレスに一致します。
/([0-9a-zA-Z]+[-._+&])*[0-9a-zA-Z]+@([-0-9a-zA-Z]+[.])+[a-zA-Z]{2,6}/

最も一般的には、ストリング内のパターンを検索し、文字を置換するために正規表現を使用します。そうした場合は、正規
表現オブジェクトを作成し、それをパラメーターとしていずれかの String クラスのメソッドで使用します。正規表現のパラ
メーターを指定できる String クラスのメソッドとしては、match()、replace()、search()、および split() があります。これらのメソッドについて詳しくは、16 ページの「ストリング内のパターンの検索およびサブストリングの置換」を参照してください。

RegExp クラスには、test() メソッドおよび exec() メソッドが含まれます。詳しくは、85 ページの「ストリングに対して正規表現を使用するメソッド」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド73

正規表現の使用

重要な概念と用語
次の参照リストに、この機能に関連した重要な用語を示します。
エスケープ文字 後に続く文字がリテラル文字ではなくメタ文字として処理する必要があることを示す文字。正規表現シンタックスでは、円記号（¥）はエスケープ文字であるため、別の文字の後続するバックスラッシュは単なる文字自体ではな
く特別なコードです。
フラグ 大文字と小文字を区別するかどうかなど、正規表現パターンの使用方法に関するいくつかのオプションを指定する文字。
メタ文字 パターン内で文字を逐語的に表すのではなく、正規表現パターン内で特別な意味を持つ文字。
制御文字 パターンの一部の反復回数を示す文字（または複数の文字）。例えば、米国の郵便番号では 5 桁または 9 桁の番号を含む必要があることを指定するために制御文字を使用します。
正規表現 パターンが他のストリングに一致するかどうかを確認するため、またはストリングの一部を置換するために使用できる文字パターンを定義するプログラムステートメント。

正規表現のシンタックス
Flash Player 9 以降、Adobe AIR 1.0 以降
このセクションでは、ActionScript の正規表現シンタックスを構成するすべての要素について説明します。以降で説明する
ように、正規表現は複雑であり、微妙な相違を把握することが必要です。詳細については、Web や書籍で他の参考資料を参照してください。ただし、プログラミング環境が異なると正規表現の実装も異なっている場合があるため注意が必要です。

ActionScript 3.0 では、ECMAScript Edition 3 言語仕様（ECMA-262）の定義に基づいて正規表現を実装しています。
多くの場合、正規表現は単純な文字の連続ではなく複雑なパターンを見つけるために使用します。例えば、次の正規表現では、文字 A、B、C が順に連続して出現し、その後に任意の数字が続くパターンを定義しています。
/ABC\d/¥d コードは「任意の数字」を表します。円記号（¥）はエスケープ文字と呼ばれ、正規表現の中では、直後に続く文字（この場合は d）との組み合わせによって特別な意味を表現します。
次の正規表現では、ABC という一連の文字が出現し、その後に任意の個数の数字が続くパターンを定義しています（アスタリスクが付いていることに注意してください）。
/ABC\d*/このアスタリスク文字（*）は、メタ文字の一種です。メタ文字とは、正規表現の中で特別な意味を持つ文字のことです。ア
スタリスクは繰り返し制御文字と呼ばれる種類のメタ文字で、文字または文字グループの繰り返しを指定する場合に使用します。詳しくは、78 ページの「繰り返し制御文字」を参照してください。
正規表現には、パターンに加え、その正規表現の一致方法を指定するフラグを必要に応じて設定できます。例えば、次の正規表現で使用している i フラグは、ストリング内の一致箇所を探す際に大文字と小文字を区別しないことを指定するものです。
/ABC\d*/i

詳しくは、82 ページの「フラグとプロパティ」を参照してください。
正規表現は、String クラスの match()、replace()、および search() メソッドで使用できます。これらのメソッドについて詳し
くは、16 ページの「ストリング内のパターンの検索およびサブストリングの置換」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

74

正規表現の使用

正規表現のインスタンスの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
正規表現のインスタンスを作成するには 2 つの方法があります。1 つは正規表現を区切り文字のスラッシュ（/）で囲んで記述する方法であり、もう 1 つは new コンストラクターを使用する方法です。例えば、次の正規表現はいずれも同等です。
var pattern1:RegExp = /bob/i;
var pattern2:RegExp = new RegExp("bob", "i");ストリングリテラルを引用符で囲むのと同じように、正規表現リテラルを記述する場合はスラッシュで囲みます。正規表現のうち 2 つのスラッシュで囲んだ部分がパターンです。それに加え、後ろのスラッシュに続いてフラグを指定することもできます。フラグは正規表現を構成する要素と見なされますが、パターンとは区別されています。

new コンストラクターを使用する場合は、2 つのストリングによって正規表現を定義します。次のように、第 1 のストリン
グでパターンを指定し、第 2 のストリングでフラグを指定します。
var pattern2:RegExp = new RegExp("bob", "i");スラッシュで囲んだ正規表現定義の中にスラッシュを含める場合は、中のスラッシュの直前にエスケープ文字の円記号（¥）
を置く必要があります。例えば、次の正規表現は 1/2 というパターンに一致します。
var pattern:RegExp = /1\/2/;

new コンストラクターによる正規表現定義の中に引用符を含める場合は、ストリングリテラルの場合と同じように、中の引用符の直前にエスケープ文字の円記号（¥）を置く必要があります。例えば、次の正規表現は eat at "joe's" というパターンに一致します。
var pattern1:RegExp = new RegExp("eat at \"joe's\"", "");
var pattern2:RegExp = new RegExp('eat at "joe\'s"', "");

スラッシュで囲んだ正規表現定義の中に引用符を含める場合は、エスケープ文字の円記号を付けないでください。同じように、new コンストラクターによる正規表現定義の中にスラッシュを含める場合は、エスケープ文字の円記号を付けないでください。次の正規表現は同等で、いずれも 1/2 "joe's" というパターンに一致します。
var pattern1:RegExp = /1\/2 "joe's"/;var pattern2:RegExp = new RegExp("1/2 \"joe's\"", "");
var pattern3:RegExp = new RegExp('1/2 "joe\'s"', '');

また、new コンストラクターによる正規表現定義の中で、円記号（¥）から始まるメタシーケンス（任意の数字を意味する¥d など）を使用する場合は、次のように円記号を二重に入力する必要があります。
var pattern:RegExp = new RegExp("\\d+", ""); // matches one or more digits

この場合は、RegExp() コンストラクターメソッドの最初のパラメーターがストリングで、ストリングリテラルの中で単一の円記号を認識させるためには円記号を二重に入力する必要があるため、円記号を二重に入力します。
以降のセクションでは、正規表現パターンの定義に使用するシンタックスについて説明します。
フラグについて詳しくは、82 ページの「フラグとプロパティ」を参照してください。

文字、メタ文字、およびメタシーケンス
Flash Player 9 以降、Adobe AIR 1.0 以降
最も単純な正規表現は、次のように一連の文字に一致するものです。
var pattern:RegExp = /hello/;

ただし、次の各文字はメタ文字と呼ばれ、正規表現の中では特別な意味を持ちます。
^ $ \ . * + ? ( ) [ ] { } |最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド75

正規表現の使用

例えば、次の正規表現は、文字 A の後に 0 個以上の B が続き（メタ文字のアスタリスクが繰り返しを表す）、さらにその後に C が続くストリングに一致します。
/AB*C/

メタ文字に該当する文字を正規表現のパターン内に含めて、特別な意味を表さないようにするには、エスケープ文字の円記
号（¥）を付ける必要があります。例えば、次の正規表現は、文字 A の後に B、アスタリスク、および C が続くストリングに一致します。
var pattern:RegExp = /AB\*C/;

メタシーケンスも、メタ文字と同じように正規表現の中で特別な意味を持ちます。1 つのメタシーケンスは複数の文字によって構成されます。以降のセクションでは、メタ文字とメタシーケンスの詳細な使用方法を示します。
メタ文字について次の表は、正規表現で使用できるメタ文字の一覧です。
メタ文字

説明

^（キャレット）

ストリングの先頭に一致します。また、m（multiline）フラグを設定した場合は、行の先頭にも一致します。82
ページの「フラグとプロパティ」を参照してください。ただし、文字クラスの先頭にキャレットを指定した場合
は、ストリングの先頭ではなく補集合を意味します。詳しくは、77 ページの「文字クラス」を参照してください。

$( ドル記号 )ストリングの末尾に一致します。また、m（multiline）フラグを設定した場合は、改行文字（¥n）の直前の位置にも一致します。詳しくは、82 ページの「フラグとプロパティ」を参照してください。

¥（円記号）

特殊文字が持つ特別な意味を無効化します。
また、/1¥/2/ のように、正規表現リテラルの中でスラッシュ文字を使用する場合も円記号を使用します（文字 1、スラッシュ、文字 2 の連続に一致）。

.（ドット）

任意の 1 文字に一致します。
ただし、改行文字（¥n）には s（dotall）フラグを設定した場合にのみ一致します。詳しくは、82 ページの「フラグとプロパティ」を参照してください。

*（アスタリスク）

直前のアイテムについて 0 回以上の繰り返しに一致します。
詳しくは、78 ページの「繰り返し制御文字」を参照してください。

+（プラス）

直前のアイテムについて 1 回以上の繰り返しに一致します。
詳しくは、78 ページの「繰り返し制御文字」を参照してください。

?（疑問符）

直前のアイテムについて 0 回または 1 回だけ一致します。
詳しくは、78 ページの「繰り返し制御文字」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

76

正規表現の使用

メタ文字

説明( および )

正規表現の中でグループを定義します。グループは次の場合に使用します。

• 選択制御文字 | の適用範囲を限定する場合。例：/(a|b|c)d/• 繰り返し制御文字の適用範囲を指定する場合。例：/(walla.){1,2}/• 後方参照を使用する場合。例えば、次の正規表現に含まれている ¥1 は、このパターン内にある最初のグループ
化括弧に一致したストリングに一致します。

• /(¥w*) is repeated: ¥1/
詳しくは、80 ページの「グループ」を参照してください。

[ および ]

文字クラス（該当位置に一致可能な文字を表す集合）を定義します。

/[aeiou]/ は、角括弧内に指定したいずれか 1 つの文字に一致します。
文字クラス内でハイフン（-）を使用すると、文字の範囲を指定できます。

/[A-Z0-9]/ は、大文字の A 〜 Z または 0 〜 9 に一致します。
文字クラス内で ] および - をエスケープするには、円記号を使用します。

/[+¥-]¥d+/ は、+ または - とそれに続く 1 桁以上の数字に一致します。
文字クラス内では、通常メタ文字として扱われる他の文字は、メタ文字でなく一般の文字として扱われます。円記号でエスケープする必要はありません。

/[$]/£ は、$ または £ に一致します。
詳しくは、77 ページの「文字クラス」を参照してください。

|（パイプ）

選択肢を示し、左側または右側のいずれかにある部分に一致します。

/abc|xyz/ は、abc または xyz に一致します。

メタシーケンスについて
メタシーケンスは、正規表現パターンの中で特別な意味を持つ一連の文字です。メタシーケンスについて次の表で説明します。
メタシーケンス

説明{n}

直前のアイテムについて、繰り返し回数または回数の範囲を指定します。

{n,}/A¥{27¥}/ は、文字 A の 27 回の繰り返しに一致します。

および/A{3,}/ は、文字 A の 3 回以上の繰り返しに一致します。

{n,n}/A{3,5}/ は、文字 A の 3 回以上 5 回以下の繰り返しに一致します。
詳しくは、78 ページの「繰り返し制御文字」を参照してください。

¥b

単語構成文字とそれ以外の文字の境界となる位置に一致します。ストリングの先頭または末尾が単語構成文字である場合は、その先頭または末尾にも一致します。

¥B

2 つの単語構成文字に挟まれた位置に一致します。また、単語構成文字でない 2 つの文字に挟まれた位置にも一致
します。

¥d

10 進数の数字 1 文字に一致します。

¥D

数字以外の任意の 1 文字に一致します。

¥f

改ページ文字に一致します。

¥n

改行文字に一致します。

¥r

復帰文字に一致します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

77

正規表現の使用

メタシーケンス説明¥s

任意の空白文字（スペース、タブ、改行、復帰）に一致します。

¥S

空白文字以外の任意の 1 文字に一致します。

¥t

タブ文字に一致します。

¥unnnn16 進数 nnnn で指定される文字コードを持つ Unicode 文字に一致します。例えば、¥u263a はスマイルマークです。

¥v

垂直フィード文字に一致します。

¥w

単語構成文字に一致します（AZ 〜、az 〜、0 〜 9 または _）。¥w は、é、ñ、ç など、英語以外の文字には一致しません。

¥W

単語構成文字以外の任意の 1 文字に一致します。

¥¥xnn

16 進数 nn で指定される文字コードを持つ ASCII 文字に一致します。

文字クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
文字クラスは、正規表現の中で該当する位置に一致可能な文字を表すリストを指定するために使用します。文字クラスを定義するには、リストを角括弧（[ および ]）で囲みます。例えば、次の正規表現で定義している文字クラスは、bag、beg、

big、bog、bug のいずれにも一致します。
/b[aeiou]g/

文字クラス内のエスケープシーケンス
正規表現において通常は特別な意味を持つメタ文字やメタシーケンスのほとんどは、文字クラス内では特別な意味を持ちません。例えば、アスタリスクは正規表現の中で繰り返しを意味しますが、文字クラス内に出現するアスタリスクはその例外です。次の文字クラスは、リストで指定されている他の文字と同じようにアスタリスク文字そのものにも一致します。
/[abc*123]/

ただし、次の表に示す 3 つの文字は、文字クラス内で特別な意味を持つメタ文字として機能します。
メタ文字

文字クラス内での意味]

文字クラスの末尾を示します。

-

文字の範囲を示します。次の「文字クラス内の文字範囲」の節を参照してください。

¥

メタシーケンスを指定します。また、メタ文字の特別な意味を無効化します。

これらの文字のいずれかをリテラル文字（特別な意味のない一般の文字）として認識させるには、その文字の直前にエス
ケープ文字の円記号を付ける必要があります。例えば、次の正規表現で定義している文字クラスは、$、¥、]、- の 4 つの記号
いずれにも一致します。
/[$\\\]\-]/

文字クラス内で特別な意味を持つメタ文字があるのと同じように、次のメタシーケンスは文字クラス内でもメタシーケンスとして機能します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

78

正規表現の使用

メタシーケンス

文字クラス内での意味¥n

改行文字に一致します。

¥r

復帰文字に一致します。

¥t

タブ文字に一致します。

¥unnnn16 進数 nnnn で指定される文字コードを持つ Unicode 文字に一致します。

¥¥xnn

16 進数 nn で指定される文字コードを持つ ASCII 文字に一致します。

その他の正規表現メタシーケンスおよびメタ文字は、文字クラス内では一般の文字として扱われます。
文字クラス内の文字範囲
ハイフンを使用すると、文字の範囲を指定できます（例：A-Z、a-z、0-9）。指定する文字は、使用している文字セットにおいて有効な範囲を構成するものである必要があります。例えば、次の文字クラスは、a 〜 z の範囲または任意の数字のうち 1
つに一致します。
/[a-z0-9]/

また、ASCII 文字コードを示す ¥¥xnn の形式を使用し、ASCII 値の範囲を指定することもできます。例えば、次の文字ク
ラスは、拡張 ASCII 文字のセットに属する任意の文字に一致します（é や ê など）。
\\x

文字クラスの補集合
文字クラスの先頭にキャレット文字（^）を指定すると、クラスの指定が反転し、リストに含まれない任意の文字に一致するという意味になります。例えば、次の文字クラスは、a 〜 z の範囲および数字を除く任意の 1 文字に一致します。
/[^a-z0-9]/補集合を表すキャレット文字（^）は、文字クラスの先頭に記述する必要があります。それ以外の場所に記述した場合は、
単に文字クラスにキャレット文字を含める意味になります。例えば、次の文字クラスは、いろいろな記号（キャレットを含む）のいずれかに一致します。
/[!.,#+*%$&^]/

繰り返し制御文字Flash Player 9 以降、Adobe AIR 1.0 以降
繰り返し制御文字は、パターンの中で文字またはシーケンスの繰り返しを指定するために使用します。次に例を示します。
繰り返し制御のメタ文字

説明*（アスタリスク）

直前のアイテムについて 0 回以上の繰り返しに一致します。

+（プラス）

直前のアイテムについて 1 回以上の繰り返しに一致します。

?（疑問符）

直前のアイテムについて 0 回または 1 回だけ一致します。

{n}

直前のアイテムについて、繰り返し回数または回数の範囲を指定します。

{n,}/A¥{27¥}/ は、文字 A の 27 回の繰り返しに一致します。

および/A{3,}/ は、文字 A の 3 回以上の繰り返しに一致します。

{n,n}/A{3,5}/ は、文字 A の 3 回以上 5 回以下の繰り返しに一致します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

79

正規表現の使用

次のように、繰り返し制御文字は単一の文字に適用することも、グループに適用することもできます。

• /a+/ は、文字 a の 1 回以上の繰り返しに一致します。
• /¥d+/ は、1 桁以上の数字に一致します。
• /[abc]+/ は、文字 a、b、c の任意の組み合わせで構成される 1 文字以上の繰り返しに一致します。
• /(very, )*/ は、very という単語の後にカンマと空白が続くストリングの 0 回以上の繰り返しに一致します。
繰り返し制御文字をグループ化括弧内で使用すると、グループに繰り返し制御を適用できます。例えば、次の繰り返し制御
文字は、word というストリングにも、word-word-word というストリングにも一致します。
/\w+(-\w+)*/

デフォルトでは、正規表現は「最長一致」の検索ロジックを使用します。すなわち、正規表現に含まれる各サブパターン（.* など）について、ストリング内で可能な限り多くの文字に一致する方法を探し、それから正規表現内の次の部分に処理を移します。例えば、次のような正規表現とストリングがあるとします。
var pattern:RegExp = /<p>.*<\/p>/;
str:String = "<p>Paragraph 1</p> <p>Paragraph 2</p>";

この正規表現はストリング全体に一致します。
<p>Paragraph 1</p> <p>Paragraph 2</p>

しかし、場合によっては、1 組の <p>... </p> グループのみに一致させることが本来の目的であることもあります。その場合は次のようにします。
<p>Paragraph 1</p>

任意の繰り返し制御文字の直後に疑問符（?）を付けると、その繰り返し制御文字は、「最短一致」の検索ロジックを使用するように動作が変更されます。例えば、次の正規表現では、*? という最短一致の繰り返し制御を使用しています。これは、<p> と最小限の文字の後に </p> が続くストリングに一致します。
/<p>.*?<\/p>/

繰り返し制御文字については、次の点に注意してください。

• ¥{0¥} または {0,0} と指定しても、対象のアイテムが一致から除外されるわけではありません。
• /abc+*/ のように複数の繰り返し制御文字を重複して指定することはできません。
•

ドット（.） に * などの繰り返し制御を付けても、s（dotall）フラグを設定しない限り複数行にわたって一致することはありません。例えば、次のようなコードがあるとします。
var str:String = "<p>Test\n";
str += "Multiline</p>";var re:RegExp = /<p>.*<\/p>/;trace(str.match(re)); // null;
re = /<p>.*<\/p>/s;
trace(str.match(re));// output: <p>Test//

Multiline</p>

詳しくは、82 ページの「フラグとプロパティ」を参照してください。

選択制御
Flash Player 9 以降、Adobe AIR 1.0 以降
正規表現で |（パイプ）文字を使用すると、複数ある選択肢のいずれかに一致することを指定できます。例えば、次の正規表
現は cat、dog、pig、rat のいずれかの単語に一致します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

80

正規表現の使用

var pattern:RegExp = /cat|dog|pig|rat/;

選択制御文字 | の適用範囲を限定するには、括弧を使用してグループを定義します。次の正規表現は、cat の後に nap または

nip が続くストリングに一致します。
var pattern:RegExp = /cat(nap|nip)/;

詳しくは、80 ページの「グループ」を参照してください。
次の 2 つの正規表現は、一方では選択制御文字 | を、もう一方では文字クラス（[ と ] で指定）を使用していますが、いずれも同等です。
/1|3|5|7|9//[13579]/

詳しくは、77 ページの「文字クラス」を参照してください。

グループ
Flash Player 9 以降、Adobe AIR 1.0 以降
次のように括弧を使用すると、正規表現の中でグループを定義できます。
/class-(\d*)/

グループはパターンの部分的なセクションであり、次の目的で使用できます。

•

繰り返し制御を複数の文字に適用する場合•

選択制御（| 文字）を適用する対象のサブパターンを区切る場合•一致したサブストリングをキャプチャする場合。例えば、正規表現の中で ¥1 を使用すると、前出のグループが一致した
ストリングと同じ内容に一致します。また、String クラスの replace() メソッドでは同様の目的に $1 を使用できます

以降のセクションでは、グループの使用方法について詳しく説明します。
繰り返し制御に対するグループの使用
グループを使用しない場合、次のように、繰り返し制御文字はその直前にある 1 つの文字または文字クラスに適用されます。
var pattern:RegExp = /ab*/ ;// matches the character a followed by// zero or more occurrences of the character bpattern = /a\d+/;// matches the character a followed by// one or more digits
pattern = /a[123]{1,3}/;// matches the character a followed by// one to three occurrences of either 1, 2, or 3

グループを使用すると、次のように、繰り返し制御文字を複数の文字や文字クラスに適用できます。
var pattern:RegExp = /(ab)*/;// matches zero or more occurrences of the character a// followed by the character b, such as ababab
pattern = /(a\d)+/;// matches one or more occurrences of the character a followed by// a digit, such as a1a5a8a3
pattern = /(spam ){1,3}/;// matches 1 to 3 occurrences of the word spam followed by a space

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

81

正規表現の使用

繰り返し制御文字について詳しくは、78 ページの「繰り返し制御文字」を参照してください。
選択制御文字（|）に対するグループの使用
グループは、次のように選択制御文字（|）の適用対象となる範囲を指定するために使用できます。
var pattern:RegExp = /cat|dog/;// matches cat or dog
pattern = /ca(t|d)og/;// matches catog or cadog

グループによる一致したサブストリングのキャプチャ
正規表現では、パターン内に通常のグループ化括弧を指定すると、後でそのグループに一致した内容を参照できます。これは後方参照と呼ばれる機能で、後方参照に使用するグループをキャプチャグループといいます。例えば、次の正規表現に含まれている ¥1 というシーケンスは、その前の括弧で指定したキャプチャグループに一致したサブストリングと同じ内容に一致します。
var pattern:RegExp = /(\d+)-by-\1/;// matches the following: 48-by-48

後方参照は、¥1、¥2、...、¥99 のように記述することにより、1 つの正規表現の中で最大 99 個まで使用できます。
同じように、String クラスの replace() メソッドでは $1$99 と記述することにより、キャプチャグループに一致したサブスト
リングを置換ストリング内に挿入できます。
var pattern:RegExp = /Hi, (\w+)\./;
var str:String = "Hi, Bob.";
trace(str.replace(pattern, "$1, hello."));// output: Bob, hello.

また、RegExp クラスの exec() メソッドまたは String クラスの match() メソッドでキャプチャグループを使用すると、グループに一致したサブストリングをメソッドの戻り値として取得できます。
var pattern:RegExp = /(\w+)@(\w+).(\w+)/;var str:String = "bob@example.com";
trace(pattern.exec(str));// bob@example.com,bob,example,com

非キャプチャグループと先読みグループの使用
非キャプチャグループとは、キャプチャおよび番号による後方参照の機能を持たない、グループ化だけを目的としたグループです。非キャプチャグループを定義するには、次のように (?: と ) を使用します。
var pattern = /(?:com|org|net);

次の例は、(com|org) というパターンをキャプチャグループおよび非キャプチャグループで使用した場合の違いを示しています。全体の一致を調べた後でキャプチャグループの一致内容を列挙するために exec() メソッドを使用します。
var pattern:RegExp = /(\w+)@(\w+).(com|org)/;
var str:String = "bob@example.com";
trace(pattern.exec(str));// bob@example.com,bob,example,com//noncapturing:var pattern:RegExp = /(\w+)@(\w+).(?:com|org)/;
var str:String = "bob@example.com";
trace(pattern.exec(str));// bob@example.com,bob,example

特殊な非キャプチャグループとして、先読みグループと呼ばれるものがあります。さらに、これは肯定先読みグループと否
定先読みグループの 2 つに分類されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

82

正規表現の使用

肯定先読みグループは (?= と ) で定義され、該当位置に一致する必要があるサブパターンを示しますが、肯定先読みグループに一致した部分は、同じ正規表現の中にある後続のパターンについても一致の対象となります。例えば、次のコードに含まれている (?=e) は肯定先読みグループなので、これに一致する文字 e は、正規表現の続き（この例ではキャプチャグループ
の ¥w*)）についても一致を調べる対象となります。
var pattern:RegExp = /sh(?=e)(\w*)/i;
var str:String = "Shelly sells seashells by the seashore";
trace(pattern.exec(str));// Shelly,elly

否定先読みグループは (?! と ) で定義され、該当位置に一致してはならないサブパターンを示します。次に、例を示します。
var pattern:RegExp = /sh(?!e)(\w*)/i;
var str:String = "She sells seashells by the seashore";
trace(pattern.exec(str));// shore,ore

名前付きグループの使用
名前付きグループとは、正規表現で使用するグループの一種で、名前による識別子を指定したものを指します。名前付きグ
ループを定義するには、(?P<name> と ) を使用します。例えば、次の正規表現では、digits という識別子を持つ名前付きグ
ループを指定しています。
var pattern = /[a-z]+(?P<digits>\d+)[a-z]+/;exec() メソッドを使用すると、次のように、一致する名前付きグループが result 配列のプロパティとして追加されます。
var myPattern:RegExp = /([a-z]+)(?P<digits>\d+)[a-z]+/;var str:String = "a123bcd";
var result:Array = myPattern.exec(str);
trace(result.digits); // 123

次の例では、name および dom という識別子を持つ 2 つの名前付きグループを使用しています。
var emailPattern:RegExp =/(?P<name>(\w|[_.\-])+)@(?P<dom>((\w|-)+))+\.\w{2,4}+/;var address:String = "bob@example.com";
var result:Array = emailPattern.exec(address);trace(result.name); // bob
trace(result.dom); // example

注意：名前付きグループは、ECMAScript の言語仕様には規定されていない、ActionScript 3.0 独自の拡張機能です。

フラグとプロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
次の表に、正規表現に対して設定できる 5 種類のフラグを示します。各フラグには正規表現オブジェクトのプロパティとしてアクセスできます。
フラグ

プロパティ

説明

g

global複数箇所に一致します。

iignoreCase

一致の判定において大文字と小文字を区別しません。A 〜 Z および a 〜 z の文字に適用されますが、
É や é などの拡張文字には適用されません。

mmultiline

このフラグを設定した場合、$ および ^ はそれぞれ行末と行頭にも一致します。

sdotall

このフラグを設定した場合、.（ドット）は改行文字（¥n）にも一致します。

xextended

正規表現の拡張機能を有効にします。パターンの一部と見なされない空白を正規表現の中に挿入できるようになります。これにより、正規表現コードの読みやすさを向上できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

83

正規表現の使用

これらのプロパティは読み取り専用です。次のように、正規表現変数を設定する際には、フラグ（g、i、m、s、x）を設定できます。
var re:RegExp = /abc/gimsx;

しかし、名前付きプロパティの値を直接設定することはできません。例えば、次のコードではエラーが発生します。
var re:RegExp = /abc/;
re.global = true; // This generates an error.

デフォルトでは、正規表現の宣言内で指定しない限りフラグは設定されず、対応する各プロパティの値は false となります。
正規表現には上記の他にも、次の 2 つのプロパティがあります。

• lastIndex プロパティは、正規表現に対する次回の exec() または test() メソッド呼び出しにおいて使用する、ストリング内のインデックス位置を示します。

• source プロパティは、正規表現の中でパターンを定義する部分のストリングを示します。
g（global）フラグ
g（global）フラグを設定しない場合、正規表現が複数の場所に一致することはありません。例えば、次の正規表現には g フ
ラグを設定していないので、String.match() メソッドは一致したサブストリングを 1 つしか返しません。
var str:String = "she sells seashells by the seashore.";var pattern:RegExp = /sh\w*/;trace(str.match(pattern)) // output: she

次のように g フラグを設定すると、Sting.match() メソッドは複数の一致箇所を返します。
var str:String = "she sells seashells by the seashore.";var pattern:RegExp = /sh\w*/g;// The same pattern, but this time the g flag IS set.
trace(str.match(pattern)); // output: she,shells,shorei（ignoreCase）フラグ
正規表現の一致を判定する際、デフォルトでは大文字と小文字が区別されますが、i（ignoreCase）フラグを設定した場合は大文字と小文字が区別されません。例えば、次の正規表現に含まれている小文字の s は、ストリングの先頭にある大文字の Sには一致しません。
var str:String = "She sells seashells by the seashore.";trace(str.search(/sh/)); // output: 13 -- Not the first character

この正規表現に i フラグを設定すると、大文字の S にも一致するようになります。
var str:String = "She sells seashells by the seashore.";trace(str.search(/sh/i)); // output: 0

i フラグによって大文字と小文字が無視されるのは、A 〜 Z および a 〜 z 文字についてのみであり、É や é では無視されません。

m（multiline）フラグ
m（multiline）フラグを設定しない場合、^ はストリングの先頭に、$ はストリングの末尾に一致します。m フラグを設定した場合、これらの文字はそれぞれ行頭と行末にも一致します。次の例では、ストリング内に改行文字が含まれています。
var str:String = "Test\n";
str += "Multiline";
trace(str.match(/^\w*/g)); // Match a word at the beginning of the string.

正規表現に g（global）フラグを設定していても、^ に一致する場所は 1 つ（ストリングの先頭）しか存在しないので、

match() メソッドが返すサブストリングは 1 つだけです。したがって、結果の出力は次のようになります。
Test

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

84

正規表現の使用

次の例も同じコードですが、今度は m フラグを設定しています。
var str:String = "Test\n";
str += "Multiline";
trace(str.match(/^\w*/gm)); // Match a word at the beginning of lines.

この場合、出力にはそれぞれの行頭にある単語が含まれます。
Test,Multiline

行末を示す文字は、¥n だけです。次の文字は行末と見なされません。

•

復帰文字（¥r）• Unicode 行区切り文字（¥u2028）• Unicode 段落区切り文字（¥u2029）
s（dotall）フラグ
s（dotall または dot all）フラグが設定されない場合、正規表現パターンのドット（.）は改行文字（¥n）に一致しません。したがって、次の例では一致する場所がありません。
var str:String = "<p>Test\n";
str += "Multiline</p>";var re:RegExp = /<p>.*?<\/p>/;trace(str.match(re));

ただし、s フラグを設定すると、ドットが改行文字にも一致するようになります。
var str:String = "<p>Test\n";
str += "Multiline</p>";var re:RegExp = /<p>.*?<\/p>/s;
trace(str.match(re));

この場合は、<p> タグに囲まれたサブストリング全体（改行文字を含む）に一致します。
<p>TestMultiline</p>x（extended）フラグ
正規表現は解読が困難になる場合があります。特に、メタ文字やメタシーケンスを多用した正規表現は難解になる場合があります。次に、例を示します。
/<p(>|(\s*[^>]*>)).*?<\/p>/gi

正規表現に x（extended）フラグを設定した場合、パターン内に入力した空白文字がすべて無視されます。例えば、次の正規表現は前の例と同等です。
/

<p

(>

| (\s*[^>]* >))

.*?

<\/p>

/gix

x フラグを設定している場合に空白文字の一致を調べるには、その空白文字の直前に円記号を付けます。例えば、次の 2 つの正規表現は同等です。
/foo bar//foo \ bar/x

lastIndex プロパティ
lastIndex プロパティは、ストリング内で次回の検索を開始するインデックス位置を示します。このプロパティは、exec() お
よび test() メソッドの呼び出しに対して g フラグを true に設定した場合に有効です。例えば、次のようなコードがあるとします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

85

正規表現の使用

var pattern:RegExp = /p\w*/gi;
var str:String = "Pedro Piper picked a peck of pickled peppers.";
trace(pattern.lastIndex);
var result:Object = pattern.exec(str);
while (result != null){trace(pattern.lastIndex);
result = pattern.exec(str);}

lastIndex プロパティは、デフォルトでは 0（ストリングの先頭から検索を開始）に設定されていますが、検索を実行するたびに、一致した場所に続くインデックス位置に設定されます。したがって、前の例で示したコードの出力は次のようになり
ます。
0
5
11
18
25
36
44

global フラグを false に設定している場合、exec() および test() メソッドでは lastIndex プロパティを使用しません。

String クラスの match()、replace()、search() の各メソッドでは、検索処理を常にストリングの先頭から実行します。呼び出
しに使用する正規表現の lastIndex プロパティにどのような値を設定しても影響はありません（ただし、match() メソッドを呼び出すと lastIndex には 0 が設定されます）。

lastIndex プロパティを設定することで、ストリング内で正規表現による検索を開始する位置を調整できます。

source プロパティ
source プロパティは、正規表現の中でパターンを定義する部分のストリングを示します。次に、例を示します。
var pattern:RegExp = /foo/gi;
trace(pattern.source); // foo

ストリングに対して正規表現を使用するメソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
RegExp クラスには、exec() および test() の 2 つのメソッドが含まれます。
RegExp クラスの exec() メソッドおよび test() メソッドに加えて、String クラスにはストリング内で正規表現に一致する
match()、replace()、search()、および splice() の各メソッドが含まれます。

test() メソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
RegExp クラスの test() メソッドは、次の例で示すように、指定したストリング内に正規表現に一致する部分があるかどうかを単に判定します。
var pattern:RegExp = /Class-\w/;
var str = "Class-A";
trace(pattern.test(str)); // output: true

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

86

正規表現の使用

exec() メソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
RegExp クラスの exec() メソッドは、指定したストリング内に正規表現に一致する部分があるかどうかを調べ、次の内容を格納した配列を返します。

•

パターンに一致したサブストリング•

正規表現に含まれるいずれかのグループ化括弧に一致したサブストリング

また、この配列には、サブストリングの一致を開始したインデックス位置を示す index プロパティがあります。
例えば、次のようなコードがあるとします。
var pattern:RegExp = /\d{3}\-\d{3}-\d{4}/; //U.S phone number
var str:String = "phone: 415-555-1212";
var result:Array = pattern.exec(str);
trace(result.index, " - ", result);// 7-415-555-1212

正規表現に g（global）フラグを設定して、exec() メソッドを繰り返し呼び出すことにより、次のように複数のサブストリン
グについて一致を調べることができます。
var pattern:RegExp = /\w*sh\w*/gi;
var str:String = "She sells seashells by the seashore";
var result:Array = pattern.exec(str);
while (result != null){trace(result.index, "\t", pattern.lastIndex, "\t", result);
result = pattern.exec(str);}//output:// 0 3 She// 10 19 seashells// 27 35 seashore

RegExp パラメーターを使用する String のメソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
正規表現のパラメーターを指定できる String クラスのメソッドとしては、match()、replace()、search()、および split() があります。これらのメソッドについて詳しくは、16 ページの「ストリング内のパターンの検索およびサブストリングの置換」を参照してください。

正規表現の例：Wiki パーサー
Flash Player 9 以降、Adobe AIR 1.0 以降
この単純な Wiki テキスト変換の例で、正規表現の使用方法をいくつか示します。

•

ソースの Wiki パターンに一致するテキスト行を適切な HTML 出力ストリングに変換する。

•

正規表現を使用して、URL パターンを HTML の <a> ハイパーリンクタグに変換する。

•

正規表現を使用して、米ドルストリング（「$9.95」など）をユーロストリング（「8.24 €」など）に変換する。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

87

正規表現の使用

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。WikiEditor アプリケーションのファイルは、Samples/WikiEditor フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

Flash（FLA）または Flex（MXML）のメインアプリケー

WikiEditor.mxml

ションファイル。

またはWikiEditor.fla
com/example/programmingas3/regExpExamples/WikiParser.ascom/example/programmingas3/regExpExamples/URLParser.as

正規表現を使用して Wiki 入力テキストパターンを同等のHTML 出力に変換するメソッドが含まれているクラス。
正規表現を使用して URL ストリングを HTML の <a> ハイ
パーリンクタグに変換するメソッドが含まれているクラス。

com/example/programmingas3/regExpExamples/CurrencyConverter.as

正規表現を使用して米ドルストリングをユーロストリングに変換するメソッドが含まれているクラス。

WikiParser クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
WikiParser クラスには、Wiki 入力テキストを同等の HTML 出力に変換するメソッドが含まれます。この Wiki 変換アプ
リケーションは堅牢ではありませんが、パターンマッチングおよびストリング変換を行う正規表現の使用方法を示します。
コンストラクター関数は setWikiData() メソッドと共に、Wiki 入力テキストのサンプルストリングを次のように単純に初期化します。
public function WikiParser(){wikiData = setWikiData();}

ユーザーがサンプルアプリケーションの「Test」ボタンをクリックすると、アプリケーションは WikiParser オブジェクトの parseWikiString() メソッドを呼び出します。このメソッドは、他の複数のメソッドを呼び出し、結果の HTML ストリン
グを組み立てます。
public function parseWikiString(wikiString:String):String{
var result:String = parseBold(wikiString);
result = parseItalic(result);
result = linesToParagraphs(result);
result = parseBullets(result);
return result;}

呼び出されるメソッド（parseBold()、parseItalic()、linesToParagraphs()、および parseBullets()）は、入力 Wiki テキストをHTML 形式のテキストに変換するために、ストリングの replace() メソッドを使用して、正規表現で定義された一致パターンを置き換えます。
ボールドおよびイタリックのパターンの変換

parseBold() メソッドは、Wiki のボールドテキストパターン（'''foo''' など）を探し、次のように、同等の HTML（<b>foo</b> など）に変換します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

88

正規表現の使用

private function parseBold(input:String):String{
var pattern:RegExp = /'''(.*?)'''/g;return input.replace(pattern, "<b>$1</b>");}正規表現の (.?*) の部分は、2 つの定義パターン ''' の間にある任意の数の文字（ *）に一致することに注意してください。? 繰り返し制御文字を使用すると、最短一致でマッチングが行われます。そのため、'''aaa''' bbb '''ccc''' のようなストリングの場合、最初に一致するストリングは '''aaa''' になります。''' パターンで開始し、終了するストリング全体ではありません。
正規表現内の括弧は、キャプチャグループを定義します。replace() メソッドは、置換ストリングの $1 コードを使用して、このグループを参照します。正規表現の g（global）フラグによって、replace() メソッドは（最初の 1 つだけではなく）ストリ
ング内のすべての一致を置き換えます。

parseItalic() メソッドは parseBold() メソッドと同じように動作しますが、イタリックテキストの区切り記号として 2 つのア
ポストロフィ（''）を探します（3 つではありません）。
private function parseItalic(input:String):String{
var pattern:RegExp = /''(.*?)''/g;return input.replace(pattern, "<i>$1</i>");}

箇条書きパターンの変換
次の例で示すように、parseBullet() メソッドは Wiki の箇条書き行パターン（* foo など）を探し、同等の HTML（<li>foo</li> など）に変換します。
private function parseBullets(input:String):String{
var pattern:RegExp = /^\*(.*)/gm;
return input.replace(pattern, "<li>$1</li>");}正規表現の先頭の ^ 記号は、行の先頭に一致します。正規表現で m（multiline）フラグを使用した場合、^ 記号は、単純にストリングの先頭ではなく、行頭とマッチングされます。

¥* パターンは、アスタリスク文字に一致します（* 繰り返し制御文字ではなく、リテラルのアスタリスクであることを示す
ために、円記号を使用します）。
正規表現内の括弧は、キャプチャグループを定義します。replace() メソッドは、置換ストリングの $1 コードを使用して、このグループを参照します。正規表現の g（global）フラグによって、replace() メソッドは（最初の 1 つだけではなく）ストリ
ング内のすべての一致を置き換えます。

Wiki 段落パターンの変換
linesToParagraphs() メソッドは、入力 Wiki ストリングの各行を HTML の <p> 段落タグに変換します。メソッド内の次の行によって、入力 Wiki ストリングから空の行を削除します。
var pattern:RegExp = /^$/gm;
var result:String = input.replace(pattern, "");

正規表現の ^ 記号は行の先頭に一致し、$ 記号は行の末尾に一致します。正規表現で m（multiline）フラグを使用した場合、^ 記号は、単純にストリングの先頭ではなく、行頭とマッチングされます。
replace() メソッドは、すべての一致するサブストリング（空の行）を空のストリング（""）で置き換えます。正規表現の g（global）フラグによって、replace() メソッドは（最初の 1 つだけではなく）ストリング内のすべての一致を置き換えます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

89

正規表現の使用

URL から HTML の <a > タグへの変換
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーがサンプルアプリケーションの「Test」ボタンをクリックしたとき、「urlToATag」チェックボックスがオンであると、アプリケーションは URLParser.urlToATag() 静的メソッドを呼び出して、入力 Wiki ストリングの URL ストリングをHTML の <a> タグに変換します。
var protocol:String = "((?:http|ftp)://)";
var urlPart:String = "([a-z0-9_-]+\.[a-z0-9_-]+)";
var optionalUrlPart:String = "(\.[a-z0-9_-]*)";
var urlPattern:RegExp = new RegExp(protocol + urlPart + optionalUrlPart, "ig");var result:String = input.replace(urlPattern, "<a href='$1$2$3'><u>$1$2$3</u></a>");RegExp() コンストラクター関数を使用して、複数の要素部分から得られた正規表現を組み立てます（urlPattern）。これらの要素部分は、正規表現パターンの一部を定義するストリングです。
正規表現パターンの最初の部分は、protocol ストリングで定義され、URL プロトコル（http:// または ftp://）を定義します。
括弧は ? 記号で示され、非キャプチャグループを定義します。これは、括弧が | 選択制御パターン用のグループの定義にのみ使用されるという意味です。このグループは replace() メソッドの置換ストリングの後方参照コード（$1、$2、$3）に一致しません。
正規表現のその他の要素部分は、それぞれキャプチャグループを使用し（パターン内の括弧で示されます）、replace() メソッ
ドの置換ストリングの後方参照コード（$1、$2、$3）で使用されます。

urlPart ストリングで定義されたパターン部分は、文字 a 〜 z、0 〜 9、_ または - の 1 つ以上に一致します。+ 繰り返し制御
文字は、少なくとも 1 つの文字に一致することを示します。¥. は、必要なドット（.）文字を指定します。残りは、文字 a 〜
z、0 〜 9、_ または - の 1 つ以上で構成される別のストリングに一致します。
optionalUrlPart ストリングで定義されたパターン部分は、0 個以上の任意の数の英数字文字（_ と - を含む）が続くドット（.）文字に一致します。* 繰り返し制御文字は、0 個以上の文字が一致することを示します。
replace() メソッドの呼び出しでは、正規表現を使用し、後方参照を使用して置換 HTML ストリングが組み立てられます。
urlToATag() メソッドは、次に emailToATag() メソッドを呼び出します。このメソッドは、似た手法を使用して、電子メー
ルパターンを HTML の <a> ハイパーリンクストリングに置き換えます。このサンプルファイルで HTTP、FTP、および電子メールの URL とのマッチングに使用する正規表現は、例を示すことが目的なので単純化されています。より正確にこれらの URL とマッチングするには、より複雑な正規表現を使用します。

米ドルストリングからユーロストリングへの変換
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーがサンプルアプリケーションの「Test」ボタンをクリックしたとき、「dollarToEuro」チェックボックスがオンであると、アプリケーションは CurrencyConverter.usdToEuro() 静的メソッドを呼び出して、次のように米ドルストリング（「$9.95」など）をユーロストリング（「8.24 €」など）に変換します。
var usdPrice:RegExp = /\$([\d,]+.\d+)+/g;
return input.replace(usdPrice, usdStrToEuroStr);最初の行で、米ドルストリングに一致する単純なパターンを定義します。$ 文字の前に円記号（¥）エスケープ文字が付いていることに注意してください。

replace() メソッドは、正規表現を使用してパターンマッチングを行い、usdStrToEuroStr() 関数を呼び出して置換ストリング（ユーロでの値）を決定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

90

正規表現の使用

関数名を replace() メソッドの第 2 パラメーターとして使用すると、次の要素がパラメーターとして呼び出し元関数に渡されます。

•

ストリング内の一致する部分。

•

グループ化括弧によってキャプチャされた一致。この方法で渡される引数の数は、グループ化括弧によってキャプチャされた一致数によって異なります。グループ化括弧によってキャプチャされた一致数は、関数コード内の arguments.length -3 を確認して特定することができます。

•

ストリング内で一致部分が始まる場所のインデックス位置。

•

ストリング全体。

usdStrToEuroStr() メソッドは、次のように米ドルストリングパターンをユーロストリングに変換します。
private function usdToEuro(...args):String{
var usd:String = args[1];usd = usd.replace(",", "");
var exchangeRate:Number = 0.828017;
var euro:Number = Number(usd) * exchangeRate;
trace(usd, Number(usd), euro);const euroSymbol:String = String.fromCharCode(8364); // €return euro.toFixed(2) + " " + euroSymbol;}

args[1] は、usdPrice 正規表現に一致した、キャプチャされた括弧指定グループを表します。これは、米ドルストリングの数
字部分です。すなわち、$ 記号が付いていない金額です。メソッドは、為替レート変換を適用し、結果のストリングを返します（前に $ 記号を付ける代わりに、後ろに € 記号を付けます）。

最終更新日 2015/10/14

91

第 6 章：XML の操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 には、ECMAScript for XML（E4X）仕様（ECMA-357 Edition 2）に基づいたクラス群が追加されています。これらのクラスは、XML データの処理に関する強力で扱いやすい機能を備えています。E4X を使用すれば、XML
データを処理するコードを、従来のプログラミングテクニックと比べて短期間で開発できます。しかも、コードの読みやす
さも従来より向上します。

関連項目

XML クラス
ECMA-357 仕様

XML の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
XML は、コンピューターを用意に操作でき、ユーザーが無理なく簡単に記述および理解できるように、構造化情報を表現する標準手段です。XML は、eXtensible Markup Language の略語です。XML 標準については、www.w3.org/XML/ を参照してください。

XML は、データを分類し、その読み取り、アクセス、および操作を容易にする標準の便利な方法を提供するものです。
XML は、HTML に似たツリー構造とタグ構造を使用します。次に、XML データの簡単な例を示します。
<song><title>What you know?</title><artist>Steve and the flubberblubs</artist><year>1989</year><lastplayed>2006-10-17-08:31</lastplayed></song>XML データはまた、他のタグや、属性、その他の構造コンポーネント内にネストされるタグにより、複雑になる場合があります。次に、XML データのより複雑な例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

92

XML の操作<album><title>Questions, unanswered</title><artist>Steve and the flubberblubs</artist><year>1989</year><tracks><song tracknumber="1" length="4:05"><title>What do you know?</title><artist>Steve and the flubberblubs</artist><lastplayed>2006-10-17-08:31</lastplayed></song><song tracknumber="2" length="3:45"><title>Who do you know?</title><artist>Steve and the flubberblubs</artist><lastplayed>2006-10-17-08:35</lastplayed></song><song tracknumber="3" length="5:14"><title>When do you know?</title><artist>Steve and the flubberblubs</artist><lastplayed>2006-10-17-08:39</lastplayed></song><song tracknumber="4" length="4:19"><title>Do you know?</title><artist>Steve and the flubberblubs</artist><lastplayed>2006-10-17-08:44</lastplayed></song></tracks></album>

この XML ドキュメント内には、他の完全な XML 構造が含まれることに注意してください（子タグを持つ song タグなど）。
この例ではまた、属性（song タグ内の tracknumber および length）など他の XML 構造や、データではなく他のタグを含む
タグ（tracks タグなど）を示しています。

XML 入門
ここでは、XML についてあまり知識をお持ちでない方のために、XML データの最も一般的な側面について簡単に説明します。XML データは、情報を構造化された形式で編成するための特別なシンタックスによりプレーンテキスト形式で記述されます。一般に、XML データセット一式を XML ドキュメントと言います。XML 形式では、データは階層構造によりエレメント（単一のデータアイテムまたは他のエレメントのコンテナ）内に編成されます。各 XML ドキュメントは、最上位アイ
テム（メインアイテム）として単一のエレメントを持ちます。このルートエレメント内部には、単一の情報が含まれることもありますが、多くの場合他のエレメントが含まれ、さらにそのエレメントに他のエレメントが含まれます（以降のエレメ
ントについても同様です）。例えば、この XML ドキュメントには音楽アルバムに関する情報が含まれます。
<song tracknumber="1" length="4:05"><title>What do you know?</title><artist>Steve and the flubberblubs</artist><mood>Happy</mood><lastplayed>2006-10-17-08:31</lastplayed></song>

各エレメントは、一連のタグにより区別されます。エレメントの名前は、山括弧（より小さい記号とより大きい記号）で囲
まれます。エレメントの先頭を示す開始タグには、エレメント名が含まれます。
<title>エレメントの末尾を示す終了タグでは、エレメント名の前にスラッシュが付きます。
</title>エレメントにコンテンツが含まれない場合は、空のエレメント（自己終了エレメントとも呼ばれます）を記述できます。

XML では、以下のエレメントは、<lastplayed/>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

93

XML の操作

次のエレメントと同じです。
<lastplayed></lastplayed>

開始タグと終了タグの間に含まれるエレメントのコンテンツに加えて、エレメントにはエレメントの開始タグで定義される「属性」と呼ばれる他の値を含めることもできます。例えば、次の XML エレメントでは値 4:19 を持つ length という名前の
単一の属性を定義しています。
<song length="4:19"></song>

各 XML エレメントには、単一の値、1 つ以上の XML エレメント、または空（空のエレメント）のいずれかであるコンテンツが含まれます。

XML の詳細について
次の Web サイトを含めて、XML の詳細について学習する場合に役立つ数多くの書籍および資料が存在します。

• W3Schools XML チュートリアル：http://w3schools.com/xml/• XMLpitstop チュートリアル、ディスカッションリスト、その他：http://xmlpitstop.com/
XML を操作するための ActionScript クラス
ActionScript 3.0 には、XML 構造化情報を操作するためのクラスがいくつか含まれています。次に、2 つのメインクラスを示します。

• XML : 単一の XML エレメント。複数の子エレメントまたはドキュメント内に単一値のエレメントを持つ XML ドキュメ
ント。

• XMLList : XML エレメントセット。兄弟エレメント（XML ドキュメント階層で同じレベルにあり、同じ親に含まれているエレメント）である複数の XML エレメントが存在する場合、XMLList オブジェクトが使用されます。例えば
XMLList インスタンスは、こうした XML エレメントセット（おそらく XML ドキュメントに含まれます）を操作するための最も容易な手段として使用できます。
<artist type="composer">Fred Wilson</artist><artist type="conductor">James Schmidt</artist><artist type="soloist">Susan Harriet Thurndon</artist>

XML 名前空間にかかわるより高度な使用を可能にするために、ActionScript には Namespace クラスおよび QName クラスも含まれています。詳しくは、106 ページの「XML 名前空間の使用」を参照してください。
XML を操作するためのビルトインクラスに加えて、ActionScript 3.0 には XML データにアクセスして操作するための特別な機能を提供するいくつかの演算子も含まれています。こうしたクラスおよび演算子を使用して XML を操作するこのアプローチを ECMAScript for XML（E4X）と言います。これは、ECMA-357 Edition 2 仕様により定義されています。
重要な概念と用語
次の参照リストに、XML 処理ルーチンのプログラミングで使用される重要な用語を示します。
エレメント XML ドキュメント内の単一アイテム。開始タグと終了タグ（タグも含みます）の間にあるコンテンツにより識別されます。XML エレメントには、テキストデータ、その他のエレメントを含めることができます。また、空であってもかまいません。
空のエレメント 子エレメントを含まない XML エレメント。空のエレメントは、自己終了タグ（<element/> など）として記述されることがよくあります。
ドキュメント 単一の XML 構造。XML ドキュメントには、任意の数のエレメントを含めることができます（また、単一の空のエレメントのみで構成することもできます）。ただし、XML ドキュメントには、ドキュメント内の他のすべてのエレメ
ントを含む単一の最上位エレメントが存在する必要があります。
ノード XML エレメントの別名。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

94

XML の操作

属性 エレメント内部にネストする個別の子エレメントとしてではなく、attributename="value" の形式でエレメントの開始タ
グに記述されるエレメントに関連する名前付き値。

XML 処理の E4X アプローチ
Flash Player 9 以降、Adobe AIR 1.0 以降
ECMAScript for XML 仕様には、XML データを処理するためのクラス群や機能が定義されています。これらのクラスは総称して E4X と呼ばれています。ActionScript 3.0 は、E4X 準拠のクラスとして、XML、XMLList、QName、およびNamespace を備えています。
E4X クラスのメソッド、プロパティ、演算子についての策定作業では、次の特徴を実現することが目標とされました。

•

簡易であること : E4X では、XML データを処理するコードをできるだけ簡単に作成および解読できるようになっています。

•

一貫性があること : E4X で採用されているメソッドや考え方は、E4X それ自体の中で首尾一貫しており、また、ActionScript の他の部分とも一貫性があります。

•

なじみやすいこと：XML データの操作には、よく知られているドット（.）などの演算子を使用します。

注意：ActionScript 2.0 には別の XML クラスがあります。E4X 仕様の一部である ActionScript 3.0 XML クラスと競合しないように、ActionScript 3.0 では XMLDocument というクラス名に変更されました。XMLDocument、XMLNode、

XMLParser、XMLTag の各クラスは、ActionScript 3.0 では、主にレガシー機能のサポートを目的として flash.xml パッ
ケージに含まれています。E4X の新しいクラスはコアクラスなので、使用の際にパッケージを読み込む必要はありません。
ActionScript 2.0 のレガシー XML クラスについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガ
イド』の flash.xml パッケージの項を参照してください。
E4X を使用したデータ処理の例を次に示します。
var myXML:XML =<order><item id='1'><menuName>burger</menuName><price>3.95</price></item><item id='2'><menuName>fries</menuName><price>1.45</price></item></order>

XML データは、実際のアプリケーションでは Web サービスや RSS フィードなどの外部ソースからロードすることが多いと考えられますが、ここでは、例を単純にするために XML データをリテラルで割り当てます。
次のコードに示すとおり、E4X には、XML のプロパティや属性へのアクセスに使用するドット（.）や属性識別用の接頭辞（@）などのわかりやすい演算子が用意されています。
trace(myXML.item[0].menuName); // Output: burger
trace(myXML.item.(@id==2).menuName); // Output: fries
trace(myXML.item.(menuName=="burger").price); // Output: 3.95

XML のノードに新しい子ノードを割り当てるには、次のように appendChild() メソッドを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

95

XML の操作

var newItem:XML =<item id="3"><menuName>medium cola</menuName><price>1.25</price></item>myXML.appendChild(newItem);@ および . 演算子は、読み取りだけでなく、次のようにデータの割り当てにも使用できます。
myXML.item[0].menuName="regular burger";
myXML.item[1].menuName="small fries";
myXML.item[2].menuName="medium cola";
myXML.item.(menuName=="regular burger").@quantity = "2";
myXML.item.(menuName=="small fries").@quantity = "2";
myXML.item.(menuName=="medium cola").@quantity = "2";次のように for ループを使用すると、XML の一連のノードに対する繰り返し処理ができます。
var total:Number = 0;
for each (var property:XML in myXML.item){
var q:int = Number(property.@quantity);
var p:Number = Number(property.price);var itemTotal:Number = q * p;
total += itemTotal;
trace(q + " " + property.menuName + " $" + itemTotal.toFixed(2))}
trace("Total: $", total.toFixed(2));

XML オブジェクト
Flash Player 9 以降、Adobe AIR 1.0 以降
1 つの XML オブジェクトは、1 つの XML エレメント、属性、コメント、処理命令、またはテキストエレメントを表します。

XML オブジェクトは、単純内容を持つものと複合内容を持つものに分類されます。複合内容の XML オブジェクトとは、子ノードを持つ XML オブジェクトです。単純内容の XML オブジェクトとは、属性、コメント、処理命令、テキストノードのいずれか 1 つを含んだ XML オブジェクトです。
例えば、次の XML オブジェクトは、コメントと処理命令が含まれた複合内容の XML オブジェクトです。
XML.ignoreComments = false;
XML.ignoreProcessingInstructions = false;
var x1:XML =<order><!--This is a comment. --><?PROC_INSTR sample ?><item id='1'><menuName>burger</menuName><price>3.95</price></item><item id='2'><menuName>fries</menuName><price>1.45</price></item></order>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

96

XML の操作

次の例に示すとおり、comments() および processingInstructions() メソッドを使用して、コメントおよび処理命令の新しいXML オブジェクトを作成できるようになりました。
var x2:XML = x1.comments()[0];var x3:XML = x1.processingInstructions()[0];XML プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
XML クラスには次の 5 つの静的プロパティがあります。

• ignoreComments および ignoreProcessingInstructions プロパティでは、XML オブジェクトの解析時にコメントまたは処理命令を無視するかどうかを指定します。

• ignoreWhitespace プロパティでは、空白文字だけで区切られているエレメントタグや埋め込み式について、空白文字を無視するかどうかを指定します。

• prettyIndent および prettyPrinting プロパティは、XML クラスの toString() および toXMLString() メソッドが返すテキストを整形するために使用します。
これらのプロパティについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

XML メソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
次の各メソッドは、XML オブジェクトの階層構造に関する操作に使用します。

• appendChild()• child()• childIndex()• children()• descendants()• elements()• insertChildAfter()• insertChildBefore()• parent()• prependChild()
次の各メソッドは、XML オブジェクトの属性に関する操作に使用します。

• attribute()• attributes()
次の各メソッドは、XML オブジェクトのプロパティに関する操作に使用します。

• hasOwnProperty()• propertyIsEnumerable()• replace()

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

97

XML の操作• setChildren()
次の各メソッドは、修飾名および名前空間に関する操作に使用します。

• addNamespace()• inScopeNamespaces()• localName()• name()• namespace()• namespaceDeclarations()• removeNamespace()• setLocalName()• setName()• setNamespace()
次の各メソッドは、XML の内容のタイプに関する操作および判定に使用します。

• comments()• hasComplexContent()• hasSimpleContent()• nodeKind()• processingInstructions()• text()次の各メソッドは、XML オブジェクトからストリングへの変換および整形に使用します。

• defaultSettings()• setSettings()• settings()• normalize()• toString()• toXMLString()
次の各メソッドはその他の用途に使用します。

• contains()• copy()• valueOf()• length()
これらのメソッドについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

98

XML の操作

XMLList オブジェクト
Flash Player 9 以降、Adobe AIR 1.0 以降
XMLList インスタンスは、XML オブジェクトの任意のコレクションを表し、完全な XML ドキュメント、XML フラグメン
ト、または XML クエリの結果を含むことができます。
次の各メソッドは、XMLList オブジェクトの階層構造に関する操作に使用します。

• child()• children()• descendants()• elements()• parent()
次の各メソッドは、XMLList オブジェクトの属性に関する操作に使用します。

• attribute()• attributes()
次の各メソッドは、XMLList オブジェクトのプロパティに関する操作に使用します。

• hasOwnProperty()• propertyIsEnumerable()
次の各メソッドは、XML の内容のタイプに関する操作および判定に使用します。

• comments()• hasComplexContent()• hasSimpleContent()• processingInstructions()• text()次の各メソッドは、XMLList オブジェクトからストリングへの変換および整形に使用します。

• normalize()• toString()• toXMLString()
次の各メソッドはその他の用途に使用します。

• contains()• copy()• length()• valueOf()
これらのメソッドについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

XML エレメントを 1 つだけ含んでいる XMLList オブジェクトに対しては、XML クラスのプロパティとメソッドをすべて使用できます。これは、XML エレメントを 1 つだけ含んでいる XMLList オブジェクトは XML オブジェクト 1 つと同等に扱われるためです。例えば、次のコードにある doc.div は、エレメントを 1 つだけ含んでいる XMLList オブジェクトなので、XML クラスの appendChild() メソッドを使用できます。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

99

XML の操作

var doc:XML =<body><div><p>Hello</p></div></body>;doc.div.appendChild(<p>World</p>);

XML プロパティおよびメソッドの一覧については、95 ページの「XML オブジェクト」を参照してください。

XML 変数の初期化
Flash Player 9 以降、Adobe AIR 1.0 以降
XML オブジェクトに対しては、次のようにして XML リテラルを割り当てることができます。
var myXML:XML =<order><item id='1'><menuName>burger</menuName><price>3.95</price></item><item id='2'><menuName>fries</menuName><price>1.45</price></item></order>

また、次のコードに示すとおり、XML データを含んだストリングから new コンストラクターを使用して XML オブジェク
トのインスタンスを作成することもできます。
var str:String = "<order><item id='1'><menuName>burger</menuName>"+ "<price>3.95</price></item></order>";var myXML:XML = new XML(str);

ストリング内の XML データが整形式でない場合（終了タグが欠落している場合など）は、ランタイムエラーが発生します。
また、次のように XML オブジェクトに対してデータを参照で（他の変数から）渡すこともできます。
var tagname:String = "item";var attributename:String = "id";var attributevalue:String = "5";var content:String = "Chicken";var x:XML = <{tagname} {attributename}={attributevalue}>{content}</{tagname}>;trace(x.toXMLString())// Output: <item id="5">Chicken</item>

指定した URL から XML データをロードするには、次のように URLLoader クラスを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

100

XML の操作

import flash.events.Event;import flash.net.URLLoader;import flash.net.URLRequest;
var externalXML:XML;var loader:URLLoader = new URLLoader();var request:URLRequest = new URLRequest("xmlFile.xml");loader.load(request);
loader.addEventListener(Event.COMPLETE, onComplete);function onComplete(event:Event):void{
var loader:URLLoader = event.target as URLLoader;if (loader != null){
externalXML = new XML(loader.data);
trace(externalXML.toXMLString());}
else{
trace("loader is not a URLLoader!");}}

ソケット接続から XML データを読み取るには、XMLSocket クラスを使用します。詳しくは、『Adobe Flash Platform 用

ActionScript 3.0 リファレンスガイド』の XMLSocket クラスの項を参照してください。

XML オブジェクトの構築と変形
Flash Player 9 以降、Adobe AIR 1.0 以降
XML オブジェクトが持つプロパティリストの先頭または末尾にプロパティを追加するには、次のように prependChild() メ
ソッドまたは appendChild() メソッドを使用します。
var x1:XML = <p>Line 1</p>var x2:XML = <p>Line 2</p>var x:XML = <body></body>x = x.appendChild(x1);x = x.appendChild(x2);x = x.prependChild(<p>Line 0</p>);// x == <body><p>Line 0</p><p>Line 1</p><p>Line 2</p></body>

特定のプロパティの直前または直後にプロパティを追加するには、次のように insertChildBefore() メソッドまたはinsertChildAfter() メソッドを使用します。
var x:XML =<body><p>Paragraph 1</p><p>Paragraph 2</p></body>var newNode:XML = <p>Paragraph 1.5</p>x = x.insertChildAfter(x.p[0], newNode)x = x.insertChildBefore(x.p[2], <p>Paragraph 1.75</p>)

また、XML オブジェクトの作成時に次のようにして中括弧演算子（{ および }）を使用し、参照によってデータを他の変数から渡すこともできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

101

XML の操作

var ids:Array = [121, 122, 123];
var names:Array = [["Murphy","Pat"], ["Thibaut","Jean"], ["Smith","Vijay"]]var x:XML = new XML("<employeeList></employeeList>");for (var i:int = 0; i < 3; i++){var newnode:XML = new XML();
newnode =<employee id={ids[i]}><last>{names[i][0]}</last><first>{names[i][1]}</first></employee>;x = x.appendChild(newnode)}XML オブジェクトにプロパティまたは属性を割り当てるには、次のように = 演算子を使用します。
var x:XML =<employee><lastname>Smith</lastname></employee>
x.firstname = "Jean";x.@id = "239";

これを実行すると、x という XML オブジェクトは次のように設定されます。
<employee id="239"><lastname>Smith</lastname><firstname>Jean</firstname></employee>+ 演算子および += 演算子を使用すると、次のように複数の XMLList オブジェクトを連結できます。
var x1:XML = <a>test1</a>var x2:XML = <b>test2</b>var xList:XMLList = x1 + x2;
xList += <c>test3</c>

これを実行すると、xList という XMLList オブジェクトは次のように設定されます。
<a>test1</a><b>test2</b><c>test3</c>

XML 階層構造へのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
XML が備えている強力な機能の 1 つは、複雑にネストされたデータを、テキストの文字による連続的なストリングによって表現できることです。データを XML オブジェクトにロードすると ActionScript によって解析され、階層構造のデータとしてメモリにロードされます（XML データが整形式でない場合はランタイムエラーが発生します）。

XML オブジェクトと XMLList オブジェクトの演算子やメソッドを使用すれば、この XML データの構造内を簡単に移動できます。

XML オブジェクトの子プロパティにアクセスするには、ドット（.）演算子と子孫アクセッサー（..）演算子を使用します。
例えば、次のような XML オブジェクトがあるとします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

102

XML の操作

var myXML:XML =<order><book ISBN="0942407296"><title>Baking Extravagant Pastries with Kumquats</title><author><lastName>Contino</lastName><firstName>Chuck</firstName></author><pageCount>238</pageCount></book><book ISBN="0865436401"><title>Emu Care and Breeding</title><editor><lastName>Case</lastName><firstName>Justin</firstName></editor><pageCount>115</pageCount></book></order>

オブジェクト myXML.book は XMLList オブジェクトであり、myXML オブジェクトの book という名前を持つ子プロパティを含んでいます。それらは、myXML オブジェクトが持つ 2 つの book プロパティに対応する 2 つの XML オブジェクトです。
オブジェクト myXML..lastName は XMLList オブジェクトであり、lastName という名前を持つすべての子孫プロパティを含んでいます。それらは、myXML オブジェクトが持つ 2 つの lastName プロパティに対応する 2 つの XML オブジェクトです。
オブジェクト myXML.book.editor.lastName は XMLList オブジェクトであり、myXML オブジェクトの book という子のeditor という子の、lastName という名前を持つすべての子を含んでいます。この場合、これは XML オブジェクトを 1 つだ
け含んだ XMLList オブジェクトです（値が「Case」である lastName プロパティ）。

親ノードおよび子ノードへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
parent() メソッドは、XML オブジェクトの親を返します。
子リストでは、序数のインデックス値を指定することにより特定の子オブジェクトにアクセスできます。例えば、XML オブ
ジェクト myXML に book という名前のプロパティが 2 つある場合、book という名前の各子プロパティには、次のようにインデックス番号が対応しています。
myXML.book[0]myXML.book[1]

特定の孫にアクセスするには、子の名前と孫の名前の両方に対してインデックス番号を指定します。
myXML.book[0].title[0]ただし、x.book[0] に title という子が 1 つしかない場合は、次のようにインデックス参照を省略できます。
myXML.book[0].title

同じように、x に book という子が 1 つしかなく、それに title オブジェクトが 1 つしか含まれない場合は、次のように両方のインデックス参照を省略できます。
myXML.book.title

変数や式で子の名前を指定してアクセスするには、次のように child() メソッドを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

103

XML の操作

var myXML:XML =<order><book><title>Dictionary</title></book></order>;var childName:String = "book";
trace(myXML.child(childName).title) // output: Dictionary

属性へのアクセスFlash Player 9 以降、Adobe AIR 1.0 以降
XML オブジェクトまたは XMLList オブジェクトの属性にアクセスするには、次のコードのように @ シンボル（属性識別用の演算子）を使用します。
var employee:XML =<employee id="6401" code="233"><lastName>Wu</lastName><firstName>Erin</firstName></employee>;trace(employee.@id); // 6401

XML オブジェクトまたは XMLList オブジェクトが持つすべての属性にアクセスするには、次のコードのように、@ シンボ
ルにワイルドカードの * シンボルを付けます。
var employee:XML =<employee id="6401" code="233"><lastName>Wu</lastName><firstName>Erin</firstName></employee>;trace(employee.@*.toXMLString());// 6401// 233

また、次のコードのように attribute() または attributes() メソッドを使用して、XML オブジェクトまたは XMLList オブジェ
クトが持つ特定の属性またはすべての属性にアクセスすることもできます。
var employee:XML =<employee id="6401" code="233"><lastName>Wu</lastName><firstName>Erin</firstName></employee>;trace(employee.attribute("id")); // 6401
trace(employee.attribute("*").toXMLString());// 6401// 233trace(employee.attributes().toXMLString());// 6401// 233

メモ：属性へのアクセスには次のシンタックスを使用することもできます。その場合は下の例のようになります。
employee.attribute("id")employee["@id"]
employee.@["id"]これらはいずれも employee.@id. employee.@id 構文が望ましい方法です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

104

XML の操作

属性またはエレメントの値によるフィルター処理
Flash Player 9 以降、Adobe AIR 1.0 以降
括弧演算子の ( および ) を使用すると、エレメント名または属性値を指定してエレメントをフィルター処理できます。例えば、次のような XML オブジェクトがあるとします。
var x:XML =<employeeList><employee id="347"><lastName>Zmed</lastName><firstName>Sue</firstName><position>Data analyst</position></employee><employee id="348"><lastName>McGee</lastName><firstName>Chuck</firstName><position>Jr. data analyst</position></employee></employeeList>

この場合、次の式はいずれも有効なコードです。

• x.employee.(lastName == "McGee")：2 番目の employee ノード• x.employee.(lastName == "McGee").firstName：2 番目の employee ノードが持つ firstName プロパティ• x.employee.(lastName == "McGee").@id：2 番目の employee ノードが持つ id 属性の値
• x.employee.(@id == 347)：最初の employee ノード• x.employee.(@id == 347).lastName：最初の employee ノードが持つ lastName プロパティ• x.employee.(@id > 300)：両方の employee プロパティを含んだ XMLList• x.employee.(position.toString().search("analyst") > -1)：両方の position プロパティを含んだ XMLList
存在しない属性またはエレメントを指定してフィルター処理を実行しようとすると、例外がスローされます。例えば、次のコード例では最後の行を実行しようとした時点でエラーが発生します。これは、2 番目の p エレメントに id 属性がないためです。
var doc:XML =<body><p id='123'>Hello, <b>Bob</b>.</p><p>Hello.</p></body>;trace(doc.p.(@id == '123'));

同じように、次のコード例では最後の行を実行しようとした時点でエラーが発生します。これは、2 番目の p エレメントに b
プロパティがないためです。
var doc:XML =<body><p id='123'>Hello, <b>Bob</b>.</p><p>Hello.</p></body>;trace(doc.p.(b == 'Bob'));

これらのエラーを避けるには、次のコードのように、attribute() メソッドおよび elements() メソッドを使用して、一致する属性またはエレメントを持つプロパティを識別します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

105

XML の操作

var doc:XML =<body><p id='123'>Hello, <b>Bob</b>.</p><p>Hello.</p></body>;trace(doc.p.(attribute('id') == '123'));trace(doc.p.(elements('b') == 'Bob'));

また、次のコードのように hasOwnProperty() メソッドを使用するともできます。
var doc:XML =<body><p id='123'>Hello, <b>Bob</b>.</p><p>Hello.</p></body>;trace(doc.p.(hasOwnProperty('@id') && @id == '123'));trace(doc.p.(hasOwnProperty('b') && b == 'Bob'));for..in および for each..in ステートメントの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
XMLList オブジェクトに対して繰り返し処理を実行する場合、ActionScript 3.0 では for..in ステートメントと for each..in ス
テートメントを使用できます。例えば、次のような XML オブジェクト myXML と XMLList オブジェクト myXML.item があるとします。XMLList オブジェクトの myXML.item は、XML オブジェクトの item という 2 つのノードで構成されています。
var myXML:XML =<order><item id='1' quantity='2'><menuName>burger</menuName><price>3.95</price></item><item id='2' quantity='2'><menuName>fries</menuName><price>1.45</price></item></order>;for..in ステートメントを使用して繰り返し処理を実行するには、次のようにします。
var total:Number = 0;
for (var pname:String in myXML.item){
total += myXML.item.@quantity[pname] * myXML.item.price[pname];}for each..in ステートメントを使用して繰り返し処理を実行するには、次のようにします。
var total2:Number = 0;
for each (var prop:XML in myXML.item){
total2 += prop.@quantity * prop.price;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

106

XML の操作

XML 名前空間の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
XML オブジェクト（またはドキュメント）に含まれるデータの種類は、そのオブジェクトの名前空間によって特定されます。例えば、メッセージ通信プロトコルとして SOAP を使用する Web サービスに対して XML データを送信または提供する場合は、その XML の開始タグにおいて次のように名前空間を宣言します。
var message:XML =<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><soap:Body xmlns:w="http://www.test.com/weather/"><w:getWeatherResponse><w:tempurature >78</w:tempurature></w:getWeatherResponse></soap:Body></soap:Envelope>;

この名前空間は soap という接頭辞を持ち、http://schemas.xmlsoap.org/soap/envelope/ という URI において定義されています。

ActionScript 3.0 には、XML の名前空間を扱うための Namespace クラスが用意されています。前の例に示した XML オブ
ジェクトに対する Namespace クラスの使用例を次に示します。
var soapNS:Namespace = message.namespace("soap");
trace(soapNS); // Output: http://schemas.xmlsoap.org/soap/envelope/var wNS:Namespace = new Namespace("w", "http://www.test.com/weather/");message.addNamespace(wNS);
var encodingStyle:XMLList = message.@soapNS::encodingStyle;var body:XMLList = message.soapNS::Body;
message.soapNS::Body.wNS::GetWeatherResponse.wNS::tempurature = "78";XML クラスには、名前空間の扱いに関するメソッドとして、addNamespace()、inScopeNamespaces()、localName()、name()、namespace()、namespaceDeclarations()、removeNamespace()、setLocalName()、setName()、および setNamespace()があります。
default xml namespace ディレクティブは、XML オブジェクトのデフォルトの名前空間を割り当てるために使用します。例えば、次の例では、x1 と x2 がいずれも同じデフォルトの名前空間を持ちます。
var ns1:Namespace = new Namespace("http://www.example.com/namespaces/");default xml namespace = ns1;
var x1:XML = <test1 />;var x2:XML = <test2 />;XML の型変換
Flash Player 9 以降、Adobe AIR 1.0 以降
XML オブジェクトと XMLList オブジェクトは、String 値に変換できます。同様に、ストリングを XML オブジェクトまたは XMLList オブジェクトに変換することもできます。また、XML の属性値、名前、テキスト値はすべてストリングです。
以降のセクションでは、これらすべてに関する XML 型変換について説明します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

107

XML の操作

XML および XMLList オブジェクトからストリングへの変換
Flash Player 9 以降、Adobe AIR 1.0 以降
XML クラスと XMLList クラスには、toString() メソッドと toXMLString() メソッドがあります。toXMLString() メソッドは、XML オブジェクトのすべてのタグ、属性、名前空間宣言、および内容を含んだストリングを返します。複合内容（子エレメント）を持つ XML オブジェクトの場合、toString() メソッドは toXMLString() メソッドとまったく同じように機能します。
テキストエレメントだけを含む単純内容の XML オブジェクトの場合、toString() メソッドは、次の例のように当該エレメントのテキストの内容だけを返します。
var myXML:XML =<order><item id='1' quantity='2'><menuName>burger</menuName><price>3.95</price></item><order>;trace(myXML.item[0].menuName.toXMLString());// <menuName>burger</menuName>
trace(myXML.item[0].menuName.toString());// burger

toString() または toXMLString() を指定せずに trace() メソッドを使用すると、次のコードのように、データはデフォルトで
toString() メソッドを使用して変換されます。
var myXML:XML =<order><item id='1' quantity='2'><menuName>burger</menuName><price>3.95</price></item><order>;trace(myXML.item[0].menuName);// burger

コードのデバッグ用に trace() メソッドを使用する際は、toXMLString() メソッドを使用し、より完全な形でデータを出力することがしばしば役立ちます。

ストリングから XML オブジェクトへの変換
Flash Player 9 以降、Adobe AIR 1.0 以降
次のように new XML() コンストラクターを使用すると、ストリングから XML オブジェクトを作成できます。
var x:XML = new XML("<a>test</a>");XML として有効でないストリングや、整形式の XML になっていないストリングを XML に変換しようとすると、次のよ
うにランタイムエラーが発生します。
var x:XML = new XML("<a>test"); // throws an error

ストリングから属性値、名前、テキスト値への変換
Flash Player 9 以降、Adobe AIR 1.0 以降
XML の属性値、名前、テキスト値はすべて String データ型で表現されており、場合によっては他のデータ型に変換する必要があります。例えば、次のコードでは Number() 関数を使用してテキスト値を数値に変換します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

108

XML の操作

var myXML:XML =<order><item><price>3.95</price></item><item><price>1.00</price></item></order>;var total:XML = <total>0</total>;
myXML.appendChild(total);for each (var item:XML in myXML.item){
myXML.total.children()[0] = Number(myXML.total.children()[0])+ Number(item.price.children()[0]);}trace(myXML.total); // 4.95;

このコードで Number() 関数を使用しないとすると、+ 演算子がストリング連結の演算子と解釈され、その結果、最終行にある trace() メソッドの出力は次のようになります。
01.003.95

外部 XML ドキュメントの読み込みFlash Player 9 以降、Adobe AIR 1.0 以降
URLLoader クラスを使用すると、指定した URL から XML データをロードできます。次のコードをアプリケーションで使用する際には、XML_URL の値を実際の有効な URL に置き換えてください。
import flash.events.Event;import flash.net.URLLoader;var myXML:XML = new XML();var XML_URL:String = "http://www.example.com/Sample3.xml";
var myXMLURL:URLRequest = new URLRequest(XML_URL);
var myLoader:URLLoader = new URLLoader(myXMLURL);
myLoader.addEventListener(Event.COMPLETE, xmlLoaded);function xmlLoaded(event:Event):void{
myXML = XML(myLoader.data);
trace("Data loaded.");}

また、XMLSocket クラスを使用すると、サーバーとの間に非同期の XML ソケット接続を確立できます。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

109

XML の操作

ActionScript 内の XML の例：インターネットからの RSS
データのロードFlash Player 9 以降、Adobe AIR 1.0 以降
RSSViewer サンプルアプリケーションは、次のような、ActionScript で XML を操作する様々な機能を示します。

• XML メソッドを使用して、RSS フィード形式の XML データにアクセスする。
• XML メソッドを使用して、テキストフィールドで使用する HTML の形式に XML データを構成する。
RSS 形式は、XML でニュースを受け取るために広く使用されています。単純な RSS データファイルの例を示します。
<?xml version="1.0" encoding="UTF-8" ?><rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/"><channel><title>Alaska - Weather</title><link>http://www.nws.noaa.gov/alerts/ak.html</link><description>Alaska - Watches, Warnings and Advisories</description><item><title>Short Term Forecast - Taiya Inlet, Klondike Highway (Alaska)</title><link>
http://www.nws.noaa.gov/alerts/ak.html#A18.AJKNK.1900</link><description>
Short Term Forecast Issued At: 2005-04-11T19:00:00
Expired At: 2005-04-12T01:00:00 Issuing Weather Forecast Office
Homepage: http://pajk.arh.noaa.gov</description></item><item><title>Short Term Forecast - Haines Borough (Alaska)</title><link>
http://www.nws.noaa.gov/alerts/ak.html#AKZ019.AJKNOWAJK.190000</link><description>
Short Term Forecast Issued At: 2005-04-11T19:00:00
Expired At: 2005-04-12T01:00:00 Issuing Weather Forecast Office
Homepage: http://pajk.arh.noaa.gov</description></item></channel></rss>

SimpleRSS アプリケーションは、インターネットから RSS データを読み取り、ヘッドライン（タイトル）、リンク、および説明のデータを解析し、そのデータを返します。SimpleRSSUI クラスは UI を提供し、SimpleRSS クラスを呼び出します。
SimpleRSS クラスはすべての XML 処理を行います。
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。RSSViewer アプリケーションのファイルは、Samples/RSSViewer フォルダーにあります。このアプリケーションは次のファイルで構成されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

110

XML の操作

ファイル

説明

RSSViewer.mxml

Flash（FLA）または Flex（MXML）のメインアプリケーションファイル。

またはRSSViewer.fla
com/example/programmingas3/rssViewer/RSSParser.as

E4X を使用して RSS（XML）データにアクセスし、対応する HTML 表現を生成するメソッドが含まれているクラス。

RSSData/ak.rss

サンプル RSS ファイル。アプリケーションは、アドビ システムズ社がホストする
Flex RSS フィードで、Web から RSS データを読み取るように設定されています。
ただし、使用するスキーマが Flex RSS フィードのスキーマとやや異なるこのドキュメントの RSS データを読み取るように、簡単にアプリケーションを変更できます。

XML データの読み取りと解析
Flash Player 9 以降、Adobe AIR 1.0 以降
RSSParser クラスには、rssXML 変数に保存されている入力 RSS データを HTML 形式の出力を含むストリングである
rssOutput に変換する xmlLoaded() メソッドがあります。
ソース RSS データにデフォルトの名前空間が含まれている場合にデフォルトの XML 名前空間を設定するコードが、メソッドの先頭近くにあります。
if (rssXML.namespace("") != undefined){
default xml namespace = rssXML.namespace("");}

次の行は、ソース XML データの内容でループし、item という子孫のプロパティを確認します。
for each (var item:XML in rssXML..item){
var itemTitle:String = item.title.toString();var itemDescription:String = item.description.toString();var itemLink:String = item.link.toString();
outXML += buildItemHTML(itemTitle,
itemDescription,
itemLink);}

最初の 3 行は、XML データの item プロパティの title、description、および link プロパティを表すストリング変数を単純に設定しています。次の行は、3 つの新しいストリング変数をパラメーターとして使用して buildItemHTML() メソッドを呼び出し、XMLList オブジェクトの形式で HTML データを取得しています。

XMLList データの構成
Flash Player 9 以降、Adobe AIR 1.0 以降
HTML データ（XMLList オブジェクト）の形式は、次のとおりです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

111

XML の操作<b>itemTitle</b><p>
itemDescription<br /><a href="link"><font color="#008000">More...</font>
</a>
</p>

メソッドの最初の行で、デフォルトの xml 名前空間を消去します。
default xml namespace = new Namespace();default xml namespace ディレクティブのスコープは、関数ブロックレベルです。すなわち、この宣言のスコープはbuildItemHTML() メソッドです。
次の行で、関数に渡されたストリング引数に基づいて、XMLList を構成します。
var body:XMLList = new XMLList();body += new XML("<b>" + itemTitle + "</b>");var p:XML = new XML("<p>" + itemDescription + "</p>");var link:XML = <a></a>;link.@href = itemLink; // <link href="itemLinkString"></link>
link.font.@color = "#008000";// <font color="#008000"></font></a>// 0x008000 = green
link.font = "More...";
p.appendChild(<br/>);p.appendChild(link);
body += p;

この XMLList オブジェクトは、ActionScript HTML テキストフィールドに適したストリングデータを表します。

xmlLoaded() メソッドは、buildItemHTML() メソッドの戻り値を使用して、ストリングに変換します。
XML.prettyPrinting = false;
rssOutput = outXML.toXMLString();

RSS フィードのタイトル抽出とカスタムイベントの送信
Flash Player 9 以降、Adobe AIR 1.0 以降
xmlLoaded() メソッドは、ソース RSS XML データの情報に基づいて、rssTitle ストリング変数を設定します。
rssTitle = rssXML.channel.title.toString();

最後に、xmlLoaded() メソッドが、データが解析され使用可能になったことをアプリケーションに通知するイベントを生成します。
dataWritten = new Event("dataWritten", true);

最終更新日 2015/10/14

112

第 7 章：ネイティブ JSON 機能の使用
ActionScript 3.0 には、JavaScript Object Notation（JSON）形式を使用して ActionScript オブジェクトのエンコードおよびデコードを行うためのネイティブ API が用意されています。JSON クラスおよびサポートするメンバー関数は、

ECMA-262 第 5 版の仕様にほぼ従っています。
コミュニケーションのメンバーである Todd Anderson が、ネイティブ JSON API とサードパーティの as3corelib

JSON クラスの比較を行っています。Working with Native JSON in Flash Player 11 をご覧ください。
関連項目

JSON

JSON API の概要
ActionScript JSON API は、JSON クラスと、いくつかのネイティブクラスの toJSON() メンバー関数から構成されています。クラスのカスタム JSON エンコードを必要とするアプリケーション向けに、ActionScript にはデフォルトのエンコー
ディングをオーバーライドする方法が用意されています。

JSON クラスは、toJSON() メンバーの用意されていないすべての ActionScript クラスについて、読み込みと書き出しを内部的に処理します。そのために、JSON は、検出した各オブジェクトのパブリックプロパティをスキャンします。オブジェ
クトに他のオブジェクトが含まれる場合、ネストされたオブジェクトを再帰的に処理し、同様にスキャンします。オブジェ
クトに toJSON() メソッドが含まれる場合、JSON では内部アルゴリズムの代わりにそのカスタムメソッドが使用されます。

JSON インターフェイスはエンコードメソッド stringify() とデコードメソッドの parse() で構成されます。これらのメソッドにはそれぞれ、JSON のエンコードまたはデコードワークフローに独自のロジックを挿入できるパラメーターが用意されています。stringify() では、このパラメーターは replacer です。parse() では、reviver です。これらのパラメーターは、次の署名を使用する 2 つの引数を持つ関数定義を持っています。
function(k, v):*toJSON() メソッド
toJSON() メソッドの署名は、次のとおりです。
public function toJSON(k:String):*

JSON.stringify() は、オブジェクトをスキャンして検出した各パブリックプロパティに toJSON() が存在する場合は、それを呼び出します。プロパティはキーと値のペアで構成されます。stringify() は toJSON() を呼び出すときに、現在調べているプロ
パティのキーである k を渡します。通常の toJSON() 実装は各プロパティ名を評価し、その値に必要となるエンコーディングを返します。
toJSON() メソッドは、String だけでなくすべての型（* で表す）の値を返すことができます。変数の戻り値の型が任意なので、状況に応じて toJSON() でオブジェクトを返すことができます。例えば、カスタムクラスのプロパティに他のサードパー
ティライブラリのオブジェクトが含まれる場合、toJSON() がプロパティを検出したときにそのオブジェクトを返すようにできます。その後、JSON はそのサードパーティオブジェクト内で再帰的に処理します。エンコードの処理フローは以下のとおりです。

• toJSON() が文字列として評価されないオブジェクトを返す場合、stringify() はそのオブジェクト内で再帰的に処理します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

113

ネイティブ JSON 機能の使用• toJSON() が文字列を返す場合、stringify() はその値を別の文字列内にラップし、ラップされた文字列を返してから次の値に移ります。
多くの場合、アプリケーションで作成される JSON 文字列を返すためにオブジェクトを返すことをお勧めします。オブジェ
クトを返す場合、ビルトイン JSON エンコードアルゴリズムが使用され、JSON はネストされたオブジェクトに再帰できます。

toJSON() メソッドは、Object クラス、または他の大部分のネイティブクラスには定義されていません。定義されていない
ことにより、JSON は、オブジェクトのパブリックプロパティに対して標準のスキャンを行うように指示されます。
toJSON() を使用して、オブジェクトのプライベートプロパティを公開することもできます。
いくつかのネイティブクラスでは、すべての使用ケースについて ActionScript ライブラリで効率的に解決できない問題もあります。これらのクラスに対しては、ActionScript で一般的な実装が用意されており、ユーザーはニーズに合わせてそれらを再実装できます。一般的な toJSON() メンバーを提供するクラスには、次のようなものがあります。

• ByteArray• Date• Dictionary• XML
ByteArray クラスをサブクラスにして、その toJSON() メソッドをオーバーライドするか、そのプロトタイプを再定義する
ことができます。最後に宣言される Date クラスおよび XML クラスは、toJSON() を再定義するためにクラスプロトタイプを使用する必要があります。Dictionary クラスは動的に宣言されるため、toJSON() をオーバーライドする際の自由度が増します。

カスタム JSON 動作の定義
ネイティブクラスの独自の JSON エンコードおよびデコードを実装するには、いくつかのオプションから選択できます。

•

最終以外のネイティブクラスのカスタムサブクラスの toJSON() を定義またはオーバーライドします•

クラスプロトタイプの toJSON() を定義または再定義します•

動的クラスの toJSON プロパティを定義します• JSON.stringify() replacer および JSON.parser() reviver パラメーターを使用します
関連項目

ECMA-262 第 5 版

ビルトインクラスのプロトタイプでの toJSON() の定義
ActionScript でのネイティブ JSON 実装は、ECMA-262 第 5 版で定義されている ECMAScript JSON メカニズムを反映しています。ECMAScript はクラスをサポートしていないので、ActionScript では、プロトタイプベースの送出という観点で JSON の動作を定義しています。プロトタイプは ActionScript 3.0 クラスに先行する位置づけにあり、継承のシミュ
レートと、メンバーの追加および再定義が可能です。

ActionScript では、任意のクラスのプロトタイプに toJSON() を定義または再定義できます。この特権は、最終とマークされているクラスに対しても適用されます。クラスのプロトタイプで toJSON() を定義すると、この定義はアプリケーションのスコープ内にあるそのクラスのすべてのインスタンスに適用されます。例えば、MovieClip プロトタイプで toJSON() メ
ソッドを定義する方法は次のとおりです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

114

ネイティブ JSON 機能の使用

MovieClip.prototype.toJSON = function(k):* {trace("prototype.toJSON() called.");return "toJSON";}

さらに、アプリケーションが MovieClip インスタンスの stringify() を呼び出すと、stringify() は toJSON() メソッドの出力を返します。
var mc:MovieClip = new MovieClip();
var js:String = JSON.stringify(mc); //"prototype toJSON() called."
trace("js: " + js); //"js: toJSON"

メソッドを定義しているネイティブクラスの toJSON() をオーバーライドすることもできます。例えば、次のコードではDate.toJSON() をオーバーライドします。
Date.prototype.toJSON = function (k):* {return "any date format you like via toJSON: "+"this.time:"+this.time + " this.hours:"+this.hours;}
var dt:Date = new Date();trace(JSON.stringify(dt));// "any date format you like via toJSON: this.time:1317244361947 this.hours:14"

toJSON() のクラスレベルでの定義またはオーバーライド
アプリケーションでは toJSON() を再定義するために必ずしもプロトタイプを使用する必要はありません。親クラスが最終とマークされていない場合は、toJSON() をサブクラスのメンバーとして定義することもできます。例えば、ByteArray クラス
を拡張してパブリックの toJSON() 関数を定義できます。
package {import flash.utils.ByteArray;public class MyByteArray extends ByteArray{public function MyByteArray() {}public function toJSON(s:String):*{
return "MyByteArray";}}}var ba:ByteArray = new ByteArray();
trace(JSON.stringify(ba)); //"ByteArray"var mba:MyByteArray = new MyByteArray(); //"MyByteArray"trace(JSON.stringify(mba)); //"MyByteArray"

クラスが動的な場合は、次のようにそのクラスのオブジェクトに toJSON プロパティを追加し、それに関数を割り当てることもできます。
var d:Dictionary = new Dictionary();
trace(JSON.stringify((d))); // "Dictionary"d.toJSON = function(){return {c : "toJSON override."};} // overrides existing function
trace(JSON.stringify((d))); // {"c":"toJSON override."}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

115

ネイティブ JSON 機能の使用

ActionScript クラスでは toJSON() をオーバーライド、定義または再定義できます。ただし、ほとんどのビルトイン
ActionScript クラスでは toJSON() は定義されていません。Object クラスでは toJSON をデフォルトのプロトタイプ内で定義しておらず、またクラスメンバーとして宣言していません。ネイティブクラスでこのメソッドをプロトタイプ関数として定義しているのはほんの少数です。そのため、ほとんどのクラスでは従来の感覚で toJSON() をオーバーライドすることはできません。

toJSON() を定義しないネイティブクラスは、内部 JSON 実装によって JSON に直列化されます。この組み込み機能は、できれば置き換えないでください。toJSON() メンバーを定義すると、JSON クラスでは独自の機能ではなくユーザーのロジックが使用されます。

JSON.stringify() replacer パラメーターの使用
プロトタイプで toJSON() をオーバーライドすると、アプリケーション全体でクラスの JSON 書き出し動作を変更することができます。ただし、場合によっては、書き出しのロジックが一時的な条件下の特殊な場合にのみ適用されることもあります。このような小さなスコープでの変更に対応するには、JSON.stringify() メソッドの replacer パラメーターを使用できます。

stringify() メソッドは、replacer パラメーターを通じて渡された関数を、エンコードされるオブジェクトに適用します。この関数の署名は、toJSON() の署名に似ています。
function (k,v):*toJSON() とは異なり、replacer 関数にはキー k に加えて、値 v が必要です。この違いが必要なのは、エンコードされるオブジェクトではなく JSON オブジェクトで stringify() が定義されるためです。JSON.stringify() が replacer(k,v) を呼び出すのは、元の入力オブジェクトがスキャンされている段階です。replacer 関数に暗黙的な this パラメーターを渡すと、キーと値を持つ
そのオブジェクトが参照されます。JSON.stringify() は元の入力オブジェクトを変更しないので、そのオブジェクトはスキャンされているコンテナ内で変更されないままの状態です。そのため、コード this[k] を使用して、元のオブジェクト上のキーを問い合わせることができます。v パラメーターには、toJSON() が変換する値が格納されます。

toJSON() と同様に、replacer 関数は任意の型の値を返すことができます。replacer がストリングを返す場合、JSON エンジンはアカウントを引用符で囲んでエスケープしてから、そのエスケープされたコンテンツも引用符で囲みます。このように囲むことで、stringify() は、その後の JSON.parse() の呼び出しでストリングを残す有効な JSON ストリングオブジェクトを受け取ることが保証されます。
次のコードは replacer パラメーターおよび暗黙的な this パラメーターを使用して、Date オブジェクトの time 値および hours
値を返します。
JSON.stringify(d, function (k,v):* {return "any date format you like via replacer: "+"holder[k].time:"+this[k].time + " holder[k].hours:"+this[k].hours;});

JSON.parse() の reviver パラメーターの使用
JSON.parse() メソッドの reviver パラメーターは、replacer 関数と反対の動作を行います。すなわち、JSON ストリングを、使用可能な ActionScript オブジェクトに変換します。reviver 引数は、2 つのパラメーターを持ち、任意の型を返す次のような関数です。
function (k,v):*

この関数で、k はキー、v は k の値です。stringify() と同様に、parse() は JSON のキーと値のペアをスキャンし、reviver 関数が存在する場合は、それを各ペアに適用します。潜在的な問題としては、JSON クラスがオブジェクトの ActionScript クラ
ス名を出力しないということがあります。したがって、回復するオブジェクトの型を認識することが難しい場合があります。
この問題は、オブジェクトがネストしている場合に、特に問題を引き起こす可能性があります。toJSON()、replacer およびreviver 関数を設計する段階で、元のオブジェクトをそのまま保ちつつ、書き出される ActionScript オブジェクトを識別する方法を工夫することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

116

ネイティブ JSON 機能の使用

解析の例
次の例は、JSON ストリングから解析したオブジェクトを回復する方法を示します。この例では、2 つのクラス

JSONGenericDictExample と JSONDictionaryExtnExample を定義しています。クラス JSONGenericDictExample は、カスタムのディクショナリクラスです。各レコードには、個人の名前、誕生日、一意の ID が含まれています。

JSONGenericDictExample コンストラクターが呼び出されるたびに、新しく作成されたオブジェクトが内部の静的な配列に追加されます。このとき、静的にインクリメントされる整数も ID として一緒に追加されます。クラス

JSONGenericDictExample は、長い id メンバーから整数部分だけを抽出する revive() メソッドも定義します。revive() メ
ソッドは、この整数を使用して検索を行い、回復可能な正しいオブジェクトを返します。
クラス JSONDictionaryExtnExample は、ActionScript Dictionary クラスを拡張します。このレコードは、構造が設定されておらず、どのようなデータも格納できません。データは、クラス定義として割り当てられるのではなく、

JSONDictionaryExtnExample オブジェクトが作成された後で割り当てられます。JSONDictionaryExtnExample レコー
ドは、JSONGenericDictExample オブジェクトをキーとして使用します。JSONDictionaryExtnExample オブジェクトが回復すると、JSONGenericDictExample.revive() 関数は JSONDictionaryExtnExample に関連付けられている ID を 使用
して、正しいキーオブジェクトを取得します。
最も重要なこととして、JSONDictionaryExtnExample.toJSON() メソッドは JSONDictionaryExtnExample オブジェクトに加えてマーカーストリングも返します。このストリングでは、JSON の出力は JSONDictionaryExtnExample クラスに属するものと認識されます。このマーカーにより、JSON.parse() で処理されるオブジェクトの種類が明確になります。
package {// Generic dictionary example:
public class JSONGenericDictExample {static var revivableObjects = [];static var nextId = 10000;
public var id;
public var dname:String;
public var birthday;
public function JSONGenericDictExample(name, birthday) {revivableObjects[nextId] = this;this.id= "id_class_JSONGenericDictExample_" + nextId;
this.dname= name;this.birthday = birthday;
nextId++;}public function toString():String { return this.dname; }public static function revive(id:String):JSONGenericDictExample {var r:RegExp = /^id_class_JSONGenericDictExample_([0-9]*)$/;
var res = r.exec(id);return JSONGenericDictExample.revivableObjects[res[1]];}}}package {import flash.utils.Dictionary;import flash.utils.ByteArray;// For this extension of dictionary, we serialize the contents of the// dictionary by using toJSON
public final class JSONDictionaryExtnExample extends Dictionary {public function toJSON(k):* {var contents = {};for (var a in this) {contents[a.id] = this[a];}// We also wrap the contents in an object so that we can

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

117

ネイティブ JSON 機能の使用// identify it by looking for the marking property "class E"// while in the midst of JSON.parse.
return {"class JSONDictionaryExtnExample": contents};}// This is just here for debugging and for illustration
public function toString():String {var retval = "[JSONDictionaryExtnExample <";var printed_any = false;for (var k in this) {retval += k.toString() + "=" +"[e="+this[k].earnings +",v="+this[k].violations + "], "printed_any = true;}
if (printed_any)
retval = retval.substring(0, retval.length-2);
retval += ">]"
return retval;}}}

次のランタイムスクリプトが JSONDictionaryExtnExample オブジェクトで JSON.parse() を呼び出すと、reviver 関数がJSONDictionaryExtnExample 内の各オブジェクトについて JSONGenericDictExample.revive() を呼び出します。この呼び出しはオブジェクトキーとなる ID を抽出します。JSONGenericDictExample.revive() 関数は、この ID を使用し、保存された

JSONDictionaryExtnExample オブジェクトをプライベートな静的配列から取得して返します。
import flash.display.MovieClip;
import flash.text.TextField;
var a_bob1:JSONGenericDictExample = new JSONGenericDictExample("Bob", new Date(Date.parse("01/02/1934")));
var a_bob2:JSONGenericDictExample = new JSONGenericDictExample("Bob", new Date(Date.parse("05/06/1978")));
var a_jen:JSONGenericDictExample = new JSONGenericDictExample("Jen", new Date(Date.parse("09/09/1999")));
var e = new JSONDictionaryExtnExample();e[a_bob1] = {earnings: 40, violations: 2};e[a_bob2] = {earnings: 10, violations: 1};e[a_jen] = {earnings: 25, violations: 3};
trace("JSON.stringify(e): " + JSON.stringify(e)); // {"class JSONDictionaryExtnExample"://{"id_class_JSONGenericDictExample_10001"://{"earnings":10,"violations":1},//"id_class_JSONGenericDictExample_10002"://{"earnings":25,"violations":3},//"id_class_JSONGenericDictExample_10000":// {"earnings":40,"violations":2}}}
var e_result = JSON.stringify(e);var e1 = new JSONDictionaryExtnExample();var e2 = new JSONDictionaryExtnExample();// It's somewhat easy to convert the string from JSON.stringify(e) back// into a dictionary (turn it into an object via JSON.parse, then loop// over that object's properties to construct a fresh dictionary).
//// The harder exercise is to handle situations where the dictionaries// themselves are nested in the object passed to JSON.stringify and// thus does not occur at the topmost level of the resulting string.
//// (For example: consider roundtripping something like

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

118

ネイティブ JSON 機能の使用//
var tricky_array = [e1, [[4, e2, 6]], {table:e3}]// where e1, e2, e3 are all dictionaries. Furthermore, consider// dictionaries that contain references to dictionaries.)//// This parsing (or at least some instances of it) can be done via// JSON.parse, but it's not necessarily trivial. Careful consideration// of how toJSON, replacer, and reviver can work together is// necessary.
var e_roundtrip =JSON.parse(e_result,// This is a reviver that is focused on rebuilding JSONDictionaryExtnExample objects.
function (k, v) {if ("class JSONDictionaryExtnExample" in v) { // special marker tag;//see JSONDictionaryExtnExample.toJSON().
var e = new JSONDictionaryExtnExample();var contents = v["class JSONDictionaryExtnExample"];for (var i in contents) {// Reviving JSONGenericDictExample objects from string// identifiers is also special;// see JSONGenericDictExample constructor and// JSONGenericDictExample's revive() method.
e[JSONGenericDictExample.revive(i)] = contents[i];}return e;} else {return v;}});
trace("// == Here is an extended Dictionary that has been round-tripped ==");
trace("// == Note that we have revived Jen/Jan during the roundtrip.
==");
trace("e:" + e); //[JSONDictionaryExtnExample <Bob=[e=40,v=2], Bob=[e=10,v=1],//Jen=[e=25,v=3]>]
trace("e_roundtrip: " + e_roundtrip); //[JSONDictionaryExtnExample <Bob=[e=40,v=2],//Bob=[e=10,v=1], Jen=[e=25,v=3]>]
trace("Is e_roundtrip a JSONDictionaryExtnExample? " + (e_roundtrip is JSONDictionaryExtnExample)); //true
trace("Name change: Jen is now Jan");a_jen.dname = "Jan"trace("e:" + e); //[JSONDictionaryExtnExample <Bob=[e=40,v=2], Bob=[e=10,v=1],//Jan=[e=25,v=3]>]
trace("e_roundtrip: " + e_roundtrip); //[JSONDictionaryExtnExample <Bob=[e=40,v=2],//Bob=[e=10,v=1], Jan=[e=25,v=3]>]

最終更新日 2015/10/14

119

第 8 章：イベント処理
Flash Player 9 以降、Adobe AIR 1.0 以降
イベント処理システムは、ユーザー入力やシステムイベントにプログラムが応答するための便利な仕組みです。

ActionScript 3.0 のイベントモデルは便利なだけでなく、標準規格に準拠しており、表示リストと高度に統合されています。
業界標準のイベント処理アーキテクチャであるドキュメントオブジェクトモデル（DOM）Level 3 Events 仕様に基づき、新しいイベントモデルは ActionScript プログラマー用の強力かつ直感性のあるイベント処理ツールを提供します。
ActionScript 3.0 のイベント処理システムは、表示リストと連携して動作します。表示リストの基本的な説明については、
143 ページの「表示のプログラミング」を参照してください。
関連項目

flash.events パッケージ
ドキュメントオブジェクトモデル（DOM）Level 3 Events 仕様

イベント処理の基本
Flash Player 9 以降、Adobe AIR 1.0 以降
イベントとは、SWF ファイル内でのプログラマーとして関心のある様々な事象の発生と考えることができます。例えば、大部分の SWF ファイルは、マウスクリックに応答する単純なものから、フォームに入力されたデータの受け入れまたは処理のような複雑なものまで、何らかのユーザーの操作をサポートします。ユーザーと SWF ファイルとの間で行われるそのような対話操作は、イベントの一種と考えられます。また、ユーザーによる直接的な操作が行われていないときも、サーバー
からのデータのロードが終了した場合や、接続されたカメラがアクティブになった場合などにイベントが発生することがあります。

ActionScript 3.0 では、1 回のイベントを 1 個のイベントオブジェクト（Event クラスまたはそのサブクラスのインスタンス）として表現します。イベントオブジェクトには、特定のイベントに関する情報が格納されているのに加え、イベントオ
ブジェクトを操作する際に役立つメソッドが備わっています。例えば Flash Player または AIR では、マウスクリックを検出すると、その特定のマウスクリックイベントを表すイベントオブジェクト（MouseEvent クラスのインスタンス）を作成します。
次に、Flash Player または AIR は作成したイベントオブジェクトを送出します。これは、イベントのターゲットとなるオブジェクトにイベントオブジェクトを引き渡すという意味です。イベントオブジェクトの送出先となるオブジェクトを、イベ
ントターゲットと呼びます。例えば、コンピューターに取り付けられているカメラがアクティブになった場合、Flash
Player はイベントターゲット（この場合はカメラを表すオブジェクト）に対して直接にイベントオブジェクトを送出します。ただし、イベントターゲットが表示リスト内にある場合、イベントオブジェクトは表示リストの階層内を下ってイベン
トターゲットまで伝達されていきます。場合によっては、この表示リスト階層内の経路をイベントオブジェクトが逆に「浮上」（バブリング）していくこともあります。この表示リスト階層の移動をイベントフローと呼びます。
アプリケーションのコードでイベントオブジェクトを受け取る（監視する）には、イベントリスナーを使用します。" イベ
ントリスナー " とは、特定のイベントに応答するために記述する関数やメソッドです。プログラムがイベントに常に応答するようにするには、イベントターゲットまたはイベントオブジェクトのイベントフローの一部である表示リストオブジェクトのいずれかにイベントリスナーを追加する必要があります。
イベントリスナーコードを作成する場合は、常に次の基本構造に従います（太字の要素は、特定の状況で入力するプレース
ホルダーです）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

120

イベント処理function eventResponse(eventObject:EventType):void{// Actions performed in response to the event go here.
}
eventTarget.addEventListener(EventType.EVENT_NAME, eventResponse);

このコードは 2 つのことを行います。まず、関数を定義します。これはイベントに対応して実行するアクションを指定する方法です。次に、ソースオブジェクトの addEventListener() メソッドを呼び出します。実際には、イベントの発生時に関数のアクションが実行されるように、指定されたイベントに関数を「サブスクライブ」します。実際にイベントが発生すると、イベントリスナーとして登録されたすべての関数とメソッドのリストが、イベントターゲットによりチェックされます。次にイベントターゲットは、リストの関数とメソッドを順に呼び出し、イベントオブジェクトをパラメーターとして渡します。
独自のイベントリスナーを作成するには、このコード内の 4 つの項目を変更する必要があります。最初に、関数の名前を使用したい名前に変更します（eventResponse と記述された 2 か所を変更します）。2 番目に、監視したいイベントにより送出されるイベントオブジェクトに適切なクラス名を指定します（コード内の EventType）。また、特定のイベントに対して適切な定数を指定します（リスト内の EVENT_NAME）。3 番目に、イベントを送出するオブジェクトの

addEventListener() メソッドを呼び出します（コード内の eventTarget）。オプションで、関数のパラメーターとして使用する変数の名前も変更できます（コード内の eventObject）。
重要な概念と用語
次の参照リストに、イベント処理ルーチンを作成する際に必要となる重要な用語を示します。
バブリング 親表示オブジェクトが、子表示オブジェクトによって送出されたイベントに応答できるように、一部のイベントに対してバブリングが実行されます。
バブリング段階 イベントフローで、イベントが親表示オブジェクトへと上方向に渡される段階です。バブリング段階は、
キャプチャ段階およびターゲット段階の後に発生します。
キャプチャ段階 イベントフローで、イベントが最も汎用的なターゲットオブジェクトから最も固有性の高いターゲットオブ
ジェクトへと下方向に渡される段階です。キャプチャ段階は、ターゲット段階およびバブリング段階の前に発生します。
デフォルト動作 一部のイベントでは、イベントにともなって動作が実行されます。これをデフォルト動作と呼びます。例えば、ユーザーがテキストフィールドにテキストを入力すると、テキスト入力イベントが生成されます。このイベントに対するデフォルト動作は、テキストフィールドに入力された文字を実際に表示することです。ただし、入力した文字を何らかの理由で表示したくない場合などは、このデフォルト動作をオーバーライドすることができます。
送出 イベントの発生をイベントリスナーに通知する処理です。
イベント あるオブジェクトに発生した事象で、そのオブジェクトから他のオブジェクトに通知できます。
イベントフロー 表示リスト上のオブジェクト（画面に表示されたオブジェクト）に対してイベントが発生すると、そのオブジェクトを含むすべてのオブジェクトにイベントが通知され、次にそのイベントリスナーに通知されます。このプロセスはステージで開始し、表示リストからイベントが発生した実際のオブジェクトへと移動して、再びステージに戻ります。このプロセスをイベントフローと呼びます。
イベントオブジェクト 特定のイベントの発生に関する情報を含むオブジェクトで、イベントが送出されるとすべてのリスナーに送信されます。
イベントターゲット イベントを送出するオブジェクトです。例えば、ステージ内の Sprite に含まれるボタンをユーザーがクリックした場合、そのステージ内のすべてのオブジェクトがイベントを送出しますが、イベントターゲットとは実際にイベントが発生したオブジェクトであり、この場合はクリックされたボタンのことです。
リスナー オブジェクトに登録したオブジェクトまたは関数で、特定のイベントの発生時に通知を受けることを示します。
ターゲット段階 イベントフローで、イベントが最も固有性の高いターゲットに到達した段階です。ターゲット段階は、キャ
プチャ段階とバブリング段階の間で発生します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

121

イベント処理ActionScript 3.0 イベント処理の以前のバージョンとの違いFlash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 のイベント処理と、ActionScript の以前のバージョンにおけるイベント処理との最も目立つ違いは、ActionScript 3.0 にはイベント処理に関するシステムが 1 つしかないのに対し、以前のバージョンには複数の異なるイベン
ト処理システムが存在していたことです。このセクションでは、まず、以前のバージョンにおけるイベント処理の仕組みを概観し、続いて、それが ActionScript 3.0 でどのように変更されたかを説明します。

ActionScript の以前のバージョンにおけるイベント処理
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 より前のバージョンでは、イベント処理に関して次のように複数の方法が存在していました。

• Button インスタンスや MovieClip インスタンスに直接配置できる on() イベントハンドラー• MovieClip インスタンスに直接配置できる onClipEvent() イベントハンドラー• XML.onload や Camera.onActivity などのコールバック関数プロパティ• addListener() メソッドを使用して登録するイベントリスナー• DOM イベントモデルの一部を実装した UIEventDispatcher クラス
いずれのメカニズムにも、それぞれに特有のメリットとデメリットがあります。on() ハンドラーと onClipEvent() ハンドラーの場合は、気軽に使用できる反面、ボタンやムービークリップにコードを直接配置すると見通しが悪いため以後のプロジェ
クト保守作業が困難になります。コールバック関数の場合も、実装作業は簡単ですが、1 種類のイベントについてコールバック関数を 1 つしか作成できないという制約があります。イベントリスナーの実装が困難になり、リスナーオブジェクトや関数の作成だけではなく、イベントを生成するオブジェクトを備えたリスナーの登録が必要です。ただし、このオーバーヘッドの増加により、複数のリスナーオブジェクトを作成し、それらのすべてを同じイベントに登録することが可能になります。

ActionScript 2.0 用コンポーネントが開発される際にもう 1 つのイベントモデルが導入され、この新しいモデルは、
UIEventDispatcher クラスで実装され、DOM Events 仕様のサブセットに基づいています。コンポーネントのイベント処理に詳しい開発者にとって、新しい ActionScript 3.0 イベントモデルへの移行は比較的容易です。
従来の各種イベントモデルの間には、使用するシンタックスが様々な形で重複していたり、また別の面では違っていたりす
るという問題がありました。例えば、ActionScript 2.0 における一部のプロパティ（TextField.onChanged など）は、コールバック関数として使用することも、イベントリスナーとして使用することもできました。ところが、リスナーをサポートする 6 つのクラスと UIEventDispatcher クラスとではリスナーオブジェクトを登録する際のシンタックスが違っていました。
つまり、Key、Mouse、MovieClipLoader、Selection、Stage、TextField の各クラスでは addListener() メソッドを使用する一方、コンポーネントのイベント処理については addEventListener() メソッドを呼び出す必要がありました。
他にも、イベント処理モデルが複数あることに起因して、イベントハンドラー関数のスコープが使用メカニズムによって異なるという問題がありました。このため、this キーワードの指す対象が一貫せず、使用するイベント処理システムによって異なっていました。

ActionScript 3.0 におけるイベント処理
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 ではイベント処理モデルが一本化され、以前のバージョンに存在していた複数のイベント処理メカニズムはそれによって置き換えられました。新しいイベントモデルは、ドキュメントオブジェクトモデル（DOM）レベル 3 のイベント仕様に基づいています。SWF ファイルの形式は DOM の標準仕様に準拠していませんが、表示リストと DOM の構造
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

122

イベント処理には、DOM イベントモデルを実装するために十分な程度の共通点があります。表示リスト上のオブジェクトは DOM 階層
構造のノードに類似しており、表示リストオブジェクトとノードという用語は、ここでの説明を通じて同じ意味で使用されます。

Flash Player および AIR における DOM イベントモデルの実装には、デフォルト動作という概念が導入されています。デフォルト動作とは、特定のイベントの通常の結果として Flash Player または AIR が実行するアクションです。
デフォルト動作
イベントに応答するコードは、通常は開発者が記述します。しかし、イベントに対して何らかの決まった動作が非常によく行われる場合については、一般的な処理が Flash Player または AIR によって自動的に実行されるようになっています（開発者が特にこの動作をキャンセルするためのコードを記述した場合を除く）。Flash Player または AIR が動作を自動的に表示するので、このような動作をデフォルト動作と呼びます。
例えば、ユーザーによって TextField オブジェクトにテキストが入力されたとき、たいていの場合は、入力されたテキスト
をその TextField オブジェクトに表示する必要があります。これは非常に一般的な動作なので、Flash Player および AIR に組み込まれています。この動作が不要な場合は、新しいイベント処理システムを使用してデフォルト動作をキャンセルできます。ユーザーによって TextField オブジェクトにテキストが入力されると、その入力を表す TextEvent クラスのインスタ
ンスが Flash Player または AIR によって作成されます。入力テキストが Flash Player または AIR によって TextField オブ
ジェクト内に表示されるのを防ぐには、その特定の TextEvent インスタンスにアクセスして preventDefault() メソッドを呼び出す必要があります。
デフォルト動作の中には、キャンセルできないものもあります。例えば、ユーザーによって TextField オブジェクト内の単語がダブルクリックされると、Flash Player および AIR から MouseEvent オブジェクトが生成されます。回避できないデ
フォルト動作は、カーソル位置にある単語がハイライト表示される動作です。
多くの種類のイベントオブジェクトには、デフォルト動作が関連付けられていません。例えば、ネットワーク接続が確立す
ると Flash Player から connect イベントが送出されますが、このイベントに関連付けられたデフォルト動作はありません。
API ドキュメントの Event クラスとそのサブクラスに関する項目には、各種イベントの一覧と、関連付けられたデフォルト動作がある場合はその内容、およびデフォルト動作をキャンセルできるかどうかが説明されています。
デフォルト動作は Flash Player または AIR から送出されるイベントオブジェクトにしか関連付けられないため、ActionScript のプログラムで送出したイベントオブジェクトに対しては実行されません。この点を理解しておくことは重要です。例えば、EventDispatcher クラスのメソッドを使用して textInput タイプのイベントオブジェクトを送出することはできますが、その場合はイベントオブジェクトにデフォルト動作が関連付けられません。したがって、プログラムから
textInput イベントを送出しても、その結果 Flash Player および AIR によって TextField オブジェクトに文字が表示されることはありません。

ActionScript 3.0 のイベントリスナーの新機能
ActionScript 2.0 の addListener() メソッドを使用した経験があれば、ActionScript 2.0 のイベントリスナーモデルとActionScript 3.0 のイベントモデルとの違いがよくわかります。次のリストでは、2 つのイベントモデル間のいくつかの主な違いについて説明します。

• ActionScript 2.0 でイベントリスナーを追加するには、ある場合には addListener() を使用し、他の場合にはaddEventListener() を使用します。一方、ActionScript 3.0 では、すべての場合に addEventListener() を使用します。
• ActionScript 2.0 にはイベントフローの仕組みがないため、addListener() メソッドを呼び出せるのは当該イベントをブロードキャストするオブジェクトに対してのみでした。ActionScript 3.0 では、イベントフローの一部となっているすべてのオブジェクトに対して addEventListener() メソッドを呼び出せます。

• ActionScript 2.0 では、イベントリスナーは関数、メソッド、オブジェクトのいずれかですが、ActionScript 3.0 では、関数とメソッドだけをイベントリスナーにできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

123

イベント処理イベントフローFlash Player 9 以降、Adobe AIR 1.0 以降
Flash Player または AIR では、イベントが発生するたびにイベントオブジェクトが送出されます。イベントターゲットが表
示リスト内にない場合、Flash Player または AIR からイベントターゲットに対して直接にイベントオブジェクトが送出されます。例えば、progress イベントオブジェクトは URLStream オブジェクトに対して直接に送出されます。イベントター
ゲットが表示リスト内にある場合、イベントオブジェクトは表示リストに対して送出され、表示リストの階層内を経由してイベントターゲットに到達します。
イベントフローは、表示リスト内をイベントオブジェクトが伝わる経路です。表示リストの構造はツリー状の階層になっており、そのトップの階層はステージです。ステージは特殊な表示オブジェクトコンテナであり、表示リストのルートとして機能します。ステージは flash.display.Stage クラスによって表され、表示オブジェクトを介してのみアクセスできます。すべての表示オブジェクトには、そのアプリケーションのステージを参照する stage という名前のプロパティが設定されています。

Flash Player または AIR によって表示リスト関連イベントのイベントオブジェクトが送出されると、そのイベントオブジェ
クトはステージからターゲットノードまでを往復します。DOM Events 仕様では、ターゲットノードとはイベントターゲッ
トを表すノードのことであると定義されています。これを言い換えれば、ターゲットノードとは当該イベントが発生した表示リストオブジェクトのことです。例えば、ユーザーが child1 という名前の表示リストオブジェクトをクリックすると、Flash Player または AIR は child1 をターゲットノードとして使用するイベントオブジェクトを送出します。
概念上、イベントフローは 3 つの部分に分けられます。第 1 の部分はキャプチャ段階と呼ばれ、ステージからターゲット
ノードの親までのノードすべてがこれに含まれます。第 2 の部分はターゲット段階と呼ばれ、ターゲットノードだけがこれに含まれます。第 3 の部分はバブリング段階と呼ばれ、バブリング段階は、ターゲットノードの親からステージに戻る帰り道
で検出されるノードで構成されます。
次の図のように、ステージを最上位とする縦の階層として表示リストの構造を考えると、各段階に付けられた名前の意味がよりよくわかります。
Stage

Parent NodeChild1 NodeChild2 Node

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

124

イベント処理ユーザーによって Child1 Node がクリックされると、Flash Player または AIR により、イベントオブジェクトがイベントフローに対して送出されます。次の図で示すように、オブジェクトは Stage から始まる伝達経路を下っていき、Parent Node を経て Child1 Node に到達してから、もう一度「バブリング」によって Parent Node から Stage へと逆方向の経路を浮上してい
きます。
Stage
キャプチャ
段階

バブリング
段階

Parent NodeChild1 NodeChild2 Node

ターゲット段階

この例で、イベントオブジェクトが下に向かって伝達されていくキャプチャ段階には、Stage および Parent Node が含まれています。ターゲット段階には Child1 Node が含まれています。バブリング段階は、ルートノードに戻る上方向への移動中に検出される Parent Node と Stage で構成されます。
このイベントフローは、従来よりいっそう強力な ActionScript 用イベント処理システムの実現に寄与しています。

ActionScript の以前のバージョンでは、イベントフローの仕組みが存在しなかったため、イベントの生成元となるオブジェ
クトにイベントリスナーを登録することしかできませんでした。ActionScript 3.0 では、ターゲットノード自体の他、イベントフローに含まれる任意のノードにイベントリスナーを登録できます。
イベントリスナーをイベントフローに追加する機能は、ユーザーインターフェイスコンポーネントが複数のオブジェクトで構成されている場合に役立ちます。例えばボタンオブジェクトは、ボタンのラベルとして機能するテキストオブジェクトを含むことがよくあります。リスナーをイベントフローに追加する機能がないと、ボタンの任意の場所で発生したクリックイ
ベントに関する通知を受信できるように、ボタンオブジェクトとテキストオブジェクトの両方にリスナーを追加する必要が生じます。しかし、イベントフローがあることで、単一のイベントリスナーをボタンオブジェクトに配置し、テキストオブ
ジェクトと、テキストオブジェクトで隠されていないボタンオブジェクトの領域の両方で発生したクリックイベントを処理できます。
ただし、イベントオブジェクトのタイプによっては、イベントフローの 3 段階のうち一部しか処理されないことがあります。
例えば、enterFrame や init などのタイプはターゲットノードに対して直接に送出され、キャプチャ段階とバブリング段階を経ることがありません。また、その他のイベントでは表示リストにないオブジェクトがターゲットになることがあります。

Socket クラスのインスタンスに対して送出されるイベントなどがこれに該当します。これらのイベントオブジェクトは、キャプチャ段階またはバブリング段階を経ずに、ターゲットオブジェクトにも直接フローします。
具体的な各種イベントタイプの動作については、API ドキュメントを参照するか、実際のイベントオブジェクトのプロパ
ティを確認してください。イベントオブジェクトのプロパティについては、次の節で説明します。

イベントオブジェクト
Flash Player 9 以降、Adobe AIR 1.0 以降
イベントオブジェクトは、新しいイベント処理システムで 2 つの主な目的に使用されます。1 つは、個々のイベントに関する情報を各種プロパティに格納して、具体的なイベントを表現することです。もう 1 つは、各種メソッドを使用してイベント
オブジェクトを操作し、イベント処理システムの動作を変化させることです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

125

イベント処理それらのプロパティとメソッドにアクセスしやすいよう、Flash Player API には、イベントオブジェクトすべての基本クラスとなる Event クラスが定義されています。Event クラスは、すべてのイベントオブジェクトに共通する基本的なプロパ
ティとメソッドを備えています。
このセクションでは、まず Event クラスのプロパティと、次に Event クラスのメソッドについて順に説明し、最後に、

Event クラスにサブクラスが存在する理由について説明します。

Event クラスのプロパティについてFlash Player 9 以降、Adobe AIR 1.0 以降
Event クラスには、イベントオブジェクトに関する重要な情報を提供する多数の読み取り専用プロパティと定数があります。
次のプロパティは特に重要です。

• Event オブジェクトのタイプは定数によって表され、Event.type プロパティに格納されます。
•

イベントのデフォルト動作を回避できるかどうかはブール値で表され、Event.cancelable プロパティに格納されます。

•

イベントフローに関する情報はその他のプロパティに格納されます。

イベントオブジェクトのタイプ
すべてのイベントオブジェクトには、それぞれイベントタイプが設定されます。イベントタイプはストリング値としてEvent.type プロパティに格納されます。イベントオブジェクトのタイプを知ることができると、コードを作成する際に、タイプに応じてオブジェクトの処理方法を区別できて便利です。例えば、次のコードでは、myDisplayObject に渡されるマウス
クリックのイベントオブジェクトすべてに対して clickHandler() リスナー関数が応答するように指定しています。
myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

20 数種類のイベントが Event クラスそのものに関連付けられ、Event クラス定数によって表されます。その内のいくつか
を Event クラス定義から抜粋して次に示します。
package flash.events{
public class Event{// class constants
public static const ACTIVATE:String = "activate";public static const ADDED:String= "added";// remaining constants omitted for brevity}}

これらの定数を使用すると、特定のイベントタイプを簡単に参照することができます。各定数が表すストリングを直接に使用することは避け、定数名で参照するようにしてください。コードに入力した定数名にスペルミスがあった場合はコンパイ
ラーによって検出できます。しかし、ストリングの値にスペルミスがあった場合はコンパイル時のエラーとならず実行時に予期しない動作が生じ、困難なデバッグ作業が必要となる可能性があります。例えば、イベントリスナーを登録する際は次のようなコードを使用してください。
myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

次のコードはお勧めできません。
myDisplayObject.addEventListener("click", clickHandler);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

126

イベント処理

デフォルト動作に関する情報
コードで cancelable プロパティを調べることにより、特定のイベントオブジェクトに対するデフォルト動作をキャンセルできるかどうかを知ることができます。cancelable プロパティの値は Boolean 型で、デフォルト動作に対するキャンセルの可否を示します。デフォルト動作をキャンセルできるイベントは少数ですが、キャンセルできる場合は、関連付けられた動作
を preventDefault() メソッドで無効化できます。詳しくは、127 ページの「Event クラスのメソッドについて」の「イベントのデフォルト動作のキャンセル」を参照してください。
イベントフロー情報

Event クラスの他のプロパティには、次に示すとおり、イベントオブジェクト自体やイベントフローとの関係に関する重要な情報が格納されます。

• bubbles プロパティには、そのイベントオブジェクトの伝達経路となるイベントフローの構成要素に関する情報が含まれます。

• eventPhase プロパティは、イベントフローが現在どの段階にあるかを示します。
• target プロパティには、イベントターゲットへの参照が格納されます。
• currentTarget プロパティには、当該イベントオブジェクトを現在処理している表示リストオブジェクトへの参照が格納されます。

bubbles プロパティ
イベントオブジェクトがバブリング段階にあるとき、そのオブジェクトによって表されるイベントは " 浮上 " 中、つまり、ターゲットノードからステージへと階層の上位に向かって戻る経路の途中にあります。Event.bubbles プロパティには、そのイベントオブジェクトがバブリング段階を経由するかどうかを示すブール値が格納されます。バブリングの対象となるイベ
ントは、必ずキャプチャ段階とターゲット段階の対象にもなるので、イベントフローの 3 段階すべてを経ることになります。
このプロパティの値が true の場合、当該イベントオブジェクトは 3 つの段階をすべて経由します。値が false の場合、イベン
トオブジェクトはバブリング段階の対象になりません。

eventPhase プロパティ
eventPhase プロパティを調べると、そのイベントオブジェクトがイベントのどの段階にあるかを知ることができます。
eventPhase プロパティには、イベントフローの 3 つの段階いずれかを示す符号なし整数値が格納されます。Flash Player
API は、次のコードの抜粋に示すように、3 つの符号なし整数値に対応する 3 つの定数を含む別個の EventPhase クラスを定義します。
package flash.events{
public final class EventPhase{
public static const CAPTURING_PHASE:uint = 1;
public static const AT_TARGET:uint = 2;
public static const BUBBLING_PHASE:uint= 3;}}

これらの定数は、eventPhase プロパティの 3 つの有効な値に対応します。定数を使用すると、コードの読みやすさを向上できます。例えば、イベントオブジェクトがターゲット段階にある場合にのみ myFunc() という関数を呼び出すようにするには、次のようなコードで条件を判断します。
if (event.eventPhase == EventPhase.AT_TARGET){
myFunc();}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

127

イベント処理target プロパティ
target プロパティには、当該イベントのターゲットであるオブジェクトへの参照が格納されます。ターゲットの扱いは単純な場合とそうでない場合があります。例えば、マイクがアクティブになったことを示すイベントでは、イベントオブジェク
トのターゲットは Microphone オブジェクトであることが明確です。しかし、ターゲットが表示リスト内にある場合は、表
示リストの階層構造を考慮する必要があります。例えば、複数の表示リストオブジェクトの重なり合う地点がユーザーによってマウスでクリックされた場合、Flash Player および AIR では、ステージから最も遠い階層にあるオブジェクトがイベ
ントターゲットとして選ばれます。
複雑な SWF ファイルでは、target プロパティがうまく機能しないことがあります。各ボタンに対して子オブジェクトを使用した定型的な修飾処理が施されているような場合は、target プロパティの参照先がボタンではなく修飾用の子オブジェクトになってしまう状況が発生しやすいためです。このような状況では、ボタンにイベントリスナーを登録し、currentTarget プ
ロパティを使用するのが一般的です。そうすれば、target プロパティが子オブジェクトを参照してしまう場合にもcurrentTarget プロパティでボタンを参照できます。
currentTarget プロパティ
currentTarget プロパティには、当該イベントオブジェクトを現在処理している表示リストオブジェクトへの参照が格納されます。調べる対象のイベントオブジェクトが現在どのノードで処理されているかが事前にわかっていないとは奇妙な状況のようにも聞こえますが、実際は特別なことではありません。なぜなら、当該イベントオブジェクトのイベントフローに含まれる任意の表示オブジェクトにリスナー関数が登録されている可能性があり、また、リスナー関数自体が任意の場所に配置されている可能性があるからです。さらに、1 つのリスナー関数が複数の表示オブジェクトに登録されている場合もあります。プロジェクトのサイズが拡大し、複雑さが増すと、currentTarget プロパティがますます有用になります。

Event クラスのメソッドについて
Flash Player 9 以降、Adobe AIR 1.0 以降
Event クラスのメソッドは、次の 3 種類に大別されます。

•

ユーティリティメソッド : イベントオブジェクトのコピーを作成する、またはストリングに変換する•

イベントフローメソッド : イベントオブジェクトをイベントフローから取り除く•

デフォルト動作メソッド : デフォルト動作をキャンセルする、またはキャンセル済みかどうかを確認する

Event クラスのユーティリティメソッド
Event クラスには 2 つのユーティリティメソッドがあります。clone() メソッドは、イベントオブジェクトのコピーを作成します。toString() メソッドは、イベントオブジェクトの各種プロパティとそれらの値を表すストリング表現を生成します。これらのメソッドの両方がイベントモデルシステムで内部的に使用されますが、開発者の一般的な使用のために公開されています。
上級開発者が Event クラスのサブクラスを作成する場合は、イベントサブクラスを正常に機能させるために、両方のユー
ティリティメソッドをオーバーライドして独自のバージョンを実装する必要があります。
イベントフローの停止
イベントオブジェクトがイベントフローで処理されるのを停止するには、Event.stopPropagation() メソッドまたはEvent.stopImmediatePropagation() メソッドを呼び出します。これら 2 つのメソッドはほとんど同じですが、現在のノードの他のイベントリスナーを実行できるかどうかという点のみが異なります。

• Event.stopPropagation() メソッドを呼び出すと、当該イベントオブジェクトがイベントフローで次のノードに伝達されるのを防ぐことができます。ただし、現在のノードに登録されている他のイベントリスナーはすべて実行されます。

• Event.stopImmediatePropagation() メソッドを呼び出すと、当該イベントオブジェクトがイベントフローで次のノードに伝達されるのを防ぎ、また現在のノードに登録されている他のイベントリスナーの実行も防ぐことができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

128

イベント処理いずれのメソッドを呼び出した場合も、イベントに関連付けられているデフォルト動作が実行されるかどうかには影響しま
せん。デフォルト動作をキャンセルするには、Event クラスのデフォルト動作メソッドを使用する必要があります。
イベントのデフォルト動作のキャンセル
デフォルト動作のキャンセルに関連するメソッドには、preventDefault() メソッドと isDefaultPrevented() メソッドの 2 つがあります。preventDefault() メソッドを呼び出すと、イベントに関連付けられたデフォルト動作をキャンセルできます。

preventDefault() が既にイベントオブジェクトで呼び出されているかどうかをチェックするには、isDefaultPrevented() メソッ
ドを呼び出します。メソッドが既に呼び出されている場合は値 true が返され、そうでない場合は false が返されます。
preventDefault() メソッドは、デフォルト動作のキャンセルが可能であるイベントに対してのみ使用できます。キャンセルの可否については、API ドキュメントで該当するイベントタイプの項目を参照するか、ActionScript で当該イベントオブジェ
クトの cancelable プロパティを確認してください。
デフォルト動作をキャンセルしても、イベントフローによるイベントオブジェクト処理の進行には影響しません。イベント
フローからイベントオブジェクトを削除するには、Event クラスのイベントフローメソッドを使用します。

Event クラスのサブクラス
Flash Player 9 以降、Adobe AIR 1.0 以降
多くのイベントは、Event クラスに定義されている共通のプロパティセットを使用すれば十分に表現できます。しかし、Event クラスのプロパティでは表現できない独特の性質を持ったイベントもあります。これらのイベントでは、ActionScript 3.0 は Event クラスの複数のサブクラスを定義します。
各サブクラスには、そのイベントのカテゴリに特有のプロパティおよびイベントタイプが追加されています。例えば、マウスの入力に関するイベントには、Event クラスに定義されているプロパティでは表現できない独特の性質があります。

MouseEvent クラスは、Event クラスを拡張し、マウスイベントの発生位置や、発生時に特定のキーが押されていたかどうかなどの情報を格納するプロパティを追加したものです。
また、Event のサブクラスには、当該サブクラスに関連付けられたイベントタイプを表す定数が格納されます。例えば

MouseEvent クラスの場合、マウス関連のイベントタイプである click、doubleClick、mouseDown、mouseUp を表す定数がそれぞれ定義されています。

124 ページの「イベントオブジェクト」下の Event クラスのユーティリティメソッドで説明したように、Event サブクラスを作成する場合は、clone() と toString() メソッドをオーバーライドして、サブクラスに固有の機能を提供する必要があります。

イベントリスナーFlash Player 9 以降、Adobe AIR 1.0 以降
イベントハンドラーとも呼ばれるイベントリスナーは、Flash Player および AIR が特定のイベントに応答して実行する関数です。イベントリスナーを登録するには 2 つの手順を実行します。まず、目的のイベントに応答して Flash Player または
AIR に実行させるための関数またはクラスメソッドを作成します。これは、リスナー関数またはイベントハンドラー関数と呼ばれることもあります。次に addEventListener() メソッドを使用して、そのリスナー関数を、イベントのターゲットまたは該当するイベントフローに含まれる任意の表示リストオブジェクトに登録します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

129

イベント処理リスナー関数の作成
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 のイベントモデルのうち、リスナー関数の作成に関する部分は DOM イベントモデルに準拠していません。DOM イベントモデルではイベントリスナーとリスナー関数が明確に区別されています。イベントリスナーはEventListener インターフェイスを実装するクラスのインスタンスで、リスナー関数はその handleEvent() というクラスのメソッドです。DOM イベントモデルにおいては、リスナー関数自体を登録するのではなく、リスナー関数を含んだクラスイ
ンスタンスを登録する形式をとります。

ActionScript 3.0 のイベントモデルには、イベントリスナーとリスナー関数との区別がありません。ActionScript 3.0 にはEventListener インターフェイスがなく、リスナー関数はクラス内、クラス外のいずれに定義することもできます。さらに、リスナー関数は handleEvent() で指定する必要がありません。任意の有効な識別子を使用して指定することができます。

ActionScript 3.0 においては、リスナー関数自体の名前を登録する形式をとります。
クラス外に定義したリスナー関数
次のコードは、赤い正方形のシェイプを表示する単純な SWF ファイルです。クラスの一部ではない clickHandler() という名前のリスナー関数は、赤い正方形上のマウスクリックイベントを監視します。
package{import flash.display.Sprite;
public class ClickExample extends Sprite{
public function ClickExample(){var child:ChildSprite = new ChildSprite();addChild(child);}}}
import flash.display.Sprite;
import flash.events.MouseEvent;class ChildSprite extends Sprite{
public function ChildSprite(){graphics.beginFill(0xFF0000);graphics.drawRect(0,0,100,100);graphics.endFill();
addEventListener(MouseEvent.CLICK, clickHandler);}}function clickHandler(event:MouseEvent):void{
trace("clickHandler detected an event of type: " + event.type);
trace("the this keyword refers to: " + this);}

ユーザーが、正方形をクリックして生成される SWF ファイルを操作すると、Flash Player または AIR は以下のトレース出力を生成します。
clickHandler detected an event of type: click
the this keyword refers to: [object global]

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

130

イベント処理イベントオブジェクトは、引数として clickHandler() に渡されるようになっています。これにより、リスナー関数の中でイ
ベントオブジェクトを調べることができます。この例では、イベントオブジェクトの type プロパティを使用し、イベントがクリックイベントであることを確認しています。
また、この例では this キーワードの値も確認しています。this はグローバルオブジェクトを参照しています。なぜなら、リスナー関数をカスタムクラスやオブジェクトに属さない外部で定義しているからです。
クラスメソッドとして定義されたリスナー関数
次の例では、前出の例と同じく ClickExample クラスを定義していますが、clickHandler() 関数を ChildSprite クラスのメソッドとして定義している点が異なります。
package{import flash.display.Sprite;
public class ClickExample extends Sprite{
public function ClickExample(){var child:ChildSprite = new ChildSprite();addChild(child);}}}
import flash.display.Sprite;
import flash.events.MouseEvent;class ChildSprite extends Sprite{
public function ChildSprite(){graphics.beginFill(0xFF0000);graphics.drawRect(0,0,100,100);graphics.endFill();
addEventListener(MouseEvent.CLICK, clickHandler);}private function clickHandler(event:MouseEvent):void{
trace("clickHandler detected an event of type: " + event.type);
trace("the this keyword refers to: " + this);}}

ユーザーが、赤い正方形をクリックして生成される SWF ファイルを操作すると、Flash Player または AIR は以下のトレース出力を生成します。
clickHandler detected an event of type: click
the this keyword refers to: [object ChildSprite]

this キーワードは child という名前の ChildSprite インスタンスを参照するようになっています。これは ActionScript 2.0 からビヘイビアーが変更されています。ActionScript 2.0 のコンポーネントでは、UIEventDispatcher.addEventListener() に対してクラスメソッドを指定した場合、リスナーメソッドのスコープが、メソッドが定義されているクラスではなくイベント
をブロードキャストしたコンポーネントに基づいて決まるようになっていました。つまり、この例と同じテクニックを
ActionScript 2.0 で使用したとすると、this キーワードは、ChildSprite インスタンスではなくイベントをブロードキャスト
したコンポーネントを参照することになります。
この従来の仕様では、リスナーメソッドからそのメソッドがあるクラス内の他のメソッドやプロパティにアクセスできない
ため、場合によっては非常に大きな問題が生じていました。これを回避するために、ActionScript 2.0 には、mx.util.Delegate
クラスを使用してリスナーメソッドのスコープを変更するという方法が用意されていました。ActionScript 3.0 では

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

131

イベント処理addEventListener() の呼び出し時にバインドメソッドが作成されるため、この回避策は不要です。これにより、this キーワー
ドで child という名前の ChildSprite インスタンスを参照し、プログラムから ChildSprite クラスの他のメソッドとプロパ
ティにアクセスできるようになります。
望ましくないイベントリスナー登録の方法
第 3 のテクニックとして、汎用オブジェクトを作成し、そのオブジェクトのプロパティによって動的にリスナー関数を割り当てる方法がありますが、これを使用することはお勧めできません。ActionScript 2.0 でよく使用されますが、ActionScript 3.0 で使用するのは望ましくないので、この章で説明しています。この方法は this キーワードがリスナーオブ
ジェクトの代わりにグローバルオブジェクトを参照するので、お勧めできません。
次の例では、前出の例と同じく ClickExample クラスを定義していますが、リスナー関数を myListenerObj という汎用オブジェクトの一部として定義している点が異なります。
package{import flash.display.Sprite;
public class ClickExample extends Sprite{
public function ClickExample(){var child:ChildSprite = new ChildSprite();addChild(child);}}}
import flash.display.Sprite;
import flash.events.MouseEvent;class ChildSprite extends Sprite{
public function ChildSprite(){graphics.beginFill(0xFF0000);graphics.drawRect(0,0,100,100);graphics.endFill();
addEventListener(MouseEvent.CLICK, myListenerObj.clickHandler);}}var myListenerObj:Object = new Object();
myListenerObj.clickHandler = function (event:MouseEvent):void{
trace("clickHandler detected an event of type: " + event.type);
trace("the this keyword refers to: " + this);}

トレースの結果は次のようになります。
clickHandler detected an event of type: click
the this keyword refers to: [object global]

this が myListenerObj を参照し、その結果トレース出力が [object Object] となると考えられる場合でも、this キーワードはグローバルオブジェクトを参照します。動的なプロパティ名を addEventListener() に引数として渡す場合、Flash Player または
AIR はバインドメソッドを作成できません。なぜなら、その場合に listener パラメーターとして渡されるのはリスナー関数の単なるメモリアドレスであり、Flash Player および AIR がそのメモリアドレスと myListenerObj インスタンスを結び付ける手段がないからです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

132

イベント処理イベントリスナーの管理
Flash Player 9 以降、Adobe AIR 1.0 以降
リスナー関数を管理するには、IEventDispatcher インターフェイスのメソッドを使用します。IEventDispatcher インターフェイスは、DOM イベントモデルにおける EventTarget インターフェイスの ActionScript 3.0 バージョンです。
IEventDispatcher という名前からは、Event オブジェクトを送信（送出）することが主な目的であるように思われますが、実際には、イベントリスナーを登録、確認、および削除する目的でメソッドを使用する機会が最も多いといえます。

IEventDispatcher インターフェイスは、次のコードに示すように、5 つのメソッドを定義します。
package flash.events{
public interface IEventDispatcher{
function addEventListener(eventName:String,
listener:Object,
useCapture:Boolean=false,priority:Integer=0,
useWeakReference:Boolean=false):Boolean;function removeEventListener(eventName:String,
listener:Object,
useCapture:Boolean=false):Boolean;function dispatchEvent(eventObject:Event):Boolean;function hasEventListener(eventName:String):Boolean;function willTrigger(eventName:String):Boolean;}}Flash Player API により IEventDispatcher インターフェイスが EventDispatcher クラスに実装され、イベントターゲット
またはイベントフローの一部になることができるすべてのクラスの基本クラスとして機能します。例えば、DisplayObject
クラスは EventDispatcher クラスを継承しています。つまり、表示リストの任意のオブジェクトが IEventDispatcher イン
ターフェイスのメソッドにアクセスできることを意味します。
イベントリスナーの追加

addEventListener() は、IEventDispatcher インターフェイスで最もよく使用されるメソッドです。リスナー関数を登録する
際にはこのメソッドを使用します。type および listener の 2 つのパラメーターは必須です。type パラメーターでは、イベントのタイプを指定します。listener パラメーターでは、目的のイベントが発生したときに実行するリスナー関数を指定します。

listener パラメーターには、関数への参照またはクラスメソッドへの参照のいずれかを指定できます。
listener パラメーターを指定する際には、括弧を使用しないでください。例えば、次の addEventListener() メソッド呼び出し
で、clickHandler() 関数は括弧なしで指定されます。
addEventListener(MouseEvent.CLICK, clickHandler)

addEventListener() メソッドの useCapture パラメーターを使用すると、イベントフローのどの段階においてリスナーをアクティブにするかを制御できます。useCapture に true を指定すると、そのリスナーはイベントフローのキャプチャ段階でアクティブになります。useCapture に false を指定すると、そのリスナーはイベントフローのターゲット段階とバブリング段階でアクティブになります。イベントフローのすべての段階でイベントを受け取るには、addEventListener() を 2 回、つまりuseCapture を true に設定して 1 回、false に設定して 1 回呼び出す必要があります。
addEventListener() メソッドの priority パラメーターは、DOM Level 3 イベントモデルの正式なパラメーターではありません。これは、イベントリスナーをより柔軟に編成できるようにするため、ActionScript 3.0 で独自に提供されているパラメーターです。addEventListener() を呼び出す際に priority パラメーターに整数値を指定することで、イベントリスナーの優

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

133

イベント処理先度を設定できます。デフォルト値は 0 ですが、負の整数値または正の整数値を指定することができます。指定した数値が高いほど、イベントリスナーが早い順序で実行されます。同じ優先度で登録された複数のイベントリスナーがある場合、それらは登録順に実行されます。つまり、先に登録したイベントリスナーほど早く実行されます。

useWeakReference パラメーターを使用すると、そのリスナー関数に対する参照を通常の参照にするか、弱参照にするかを指定できます。このパラメーターに true を指定すると、リスナー関数が使用されなくなった後もメモリ上に残り続けるのを防ぐことができます。Flash Player および AIR では、ガベージコレクションというテクニックによって、使用されなくなった
オブジェクトをメモリから削除します。あるオブジェクトに対して参照が 1 つも存在しなくなったとき、そのオブジェクト
はもう使用されないと見なされます。弱参照はガベージコレクションのシステムで無視されるため、弱参照による参照しか受けていないリスナー関数はガベージコレクションの対象となります。
イベントリスナーの削除
不要になったイベントリスナーを削除するには、removeEventListener() メソッドを使用します。不要になったリスナーは削除することをお勧めします。必須パラメーターには eventName および listener があります。これらは、addEventListener() メ
ソッドの必須パラメーターと同じです。前述したとおり、イベントフローのすべての段階においてイベントを受け取る場合
は、useCapture に true を指定した場合と false を指定した場合の両方について、合計 2 回 addEventListener() を呼び出します。
両方のイベントリスナーを削除するには、removeEventListener() を 2 回、つまり useCapture を true に設定して 1 回、false に設定して 1 回呼び出す必要があります。
イベントの送出

dispatchEvent() メソッドは、独自のイベントオブジェクトをイベントフローに送出する場合に使用する上級開発者向けのメソッドです。このメソッドに指定できるパラメーターは 1 つだけで、Event クラスまたはそのサブクラスのインスタンスを指定します。イベントを送出すると、イベントオブジェクトの target プロパティが dispatchEvent() を呼び出したオブジェク
トに設定されます。
既存のイベントリスナーの確認

IEventDispatcher インターフェイスが備える残り 2 つのメソッドは、イベントリスナーの存在に関する有用な情報を取得するために使用します。指定した表示リストオブジェクトに、指定したイベントタイプのイベントリスナーが登録されている場合、hasEventListener() メソッドは true を返します。willTrigger() メソッドも、指定した表示リストオブジェクトについてリスナーが登録されている場合に true を返します。ただし、willTrigger() では指定した表示オブジェクト自体を確認するだけでなく、イベントフローのすべての段階におけるその表示リストオブジェクトの祖先もすべて確認します。

エラーイベントのリスナーを登録しない場合
Flash Player 9 以降、Adobe AIR 1.0 以降
エラー処理に関して、ActionScript 3.0 における最も重要なメカニズムはイベントではなく例外ですが、非同期の操作（ファイルのロードなど）には例外処理を使用できません。非同期の操作を実行中にエラーが発生すると、Flash Player および AIR によりエラーイベントオブジェクトが送出されます。エラーイベントに対するリスナーを作成していない場合、デ最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

134

イベント処理バッグ版の Flash Player および AIR では、発生したエラーに関する情報がダイアログボックスに表示されます。例えば、

Flash Player のデバッガーのバージョンでは、アプリケーションが無効な URL からファイルをロードしようとした場合のエラーを説明する次のダイアログボックスを生成します。

エラーイベントのほとんどは ErrorEvent クラスに基づいているため、Flash Player または AIR で表示するためのエラー
メッセージを格納する text というプロパティがあります。ただし、StatusEvent クラスと NetStatusEvent クラスの 2 つはこれに該当しません。これらのクラスには level プロパティ（StatusEvent.level および NetStatusEvent.info.level）があります。
level プロパティの値が「error」の場合、これらのイベントタイプはエラーイベントと見なされます。
エラーイベントが発生しても、それによって SWF ファイルの実行が停止することはありません。エラーイベントは、ブラウ
ザープラグインやスタンドアローンプレーヤーのデバッガーバージョンではダイアログボックスとして、オーサリングプ
レーヤーの出力パネルにはメッセージとして、Adobe Flex Builder ではログファイルのエントリとして表示されるだけです。Flash Player または AIR のリリース版では一切表示されません。

イベント処理の例：Alarm ClockFlash Player 9 以降、Adobe AIR 1.0 以降
Alarm Clock の例は、アラームが鳴り出す時刻をユーザーが指定できる時計と、その時刻に表示されるメッセージで構成されます。Alarm Clock の例は、1 ページの「日付と時刻の操作」の SimpleClock アプリケーションを基に作成されています。Alarm Clock は、次のような ActionScript 3.0 のイベントを操作するいくつかの機能を示しています。

•

イベントの監視と応答•

リスナーへのイベントの通知•

カスタムイベントタイプの作成

このサンプルの Flash Professional アプリケーションのファイルを入手するには、

http://www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。このサンプルの Flex アプ
リケーションのファイルを入手するには、http://www.adobe.com/go/as3examples_jp を参照してください。Alarm

Clock アプリケーションのファイルは、Samples/AlarmClock フォルダーにあります。アプリケーションには次のファイルが含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

135

イベント処理ファイル

説明

AlarmClockApp.mxml

Flash（FLA）または Flex（MXML）のメインアプリケーションファイル。

またはAlarmClockApp.fla
com/example/programmingas3/clock/AlarmClock.ascom/example/programmingas3/clock/AlarmEvent.as

SimpleClock クラスを拡張し、目覚まし時計の機能を追加するクラス
AlarmClock クラスの alarm イベントのイベントオブジェクトとして機能するカスタムイベントクラス（flash.events.Event のサブクラス）

com/example/programmingas3/clock/AnalogClockFace.as

時計の丸い文字盤と時間に合わせた時針、分針、秒針を描画するコード（SimpleClock の例で説明）

com/example/programmingas3/clock/SimpleClock.as

単純な時刻合わせ機能を持つ時計インターフェイスコンポーネント（SimpleClock の例で説明）

Alarm Clock の概要
Flash Player 9 以降、Adobe AIR 1.0 以降
この例に示す時計の主な機能は、時刻を追跡して時計のディスプレイに表示すると共に、6 ページの「日付と時刻の例：単純なアナログ時計」で説明しているとおり、SimpleClock アプリケーションコードを再利用することです。AlarmClock ク
ラスは、アラーム時刻の設定やアラームが「鳴り出す」ときの通知の指定など、目覚まし時計に必要な機能を追加すること
で、前の例の SimpleClock クラスを拡張します。
イベントが作成された目的は、何かが発生したときの通知を行うためです。AlarmClock クラスが Alarm イベントを公開し、他のオブジェクトは Alarm イベントを監視して、必要なアクションを実行できます。また、AlarmClock クラスはTimer クラスのインスタンスを使用して、アラームをトリガーする時刻を判断します。AlarmClock クラスと同様に、Timer クラスは指定された時間が経過すると、他のオブジェクト（この例では AlarmClock インスタンス）に通知するイベントを提供します。ほとんどの ActionScript アプリケーションと同様に、イベントは Alarm Clock サンプルアプリケー
ションの機能の重要な部分を形成します。

アラームのトリガー
Flash Player 9 以降、Adobe AIR 1.0 以降
既に説明したように、AlarmClock クラスが実際に提供する機能は、アラームの設定とトリガーに関する機能だけです。組
み込みの Timer クラス（flash.utils.Timer）を使用して、指定された時間が経過した後で実行するようにコードを定義できます。AlarmClock クラスは Timer インスタンスを使用して、アラームを鳴らす時刻を判断します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

136

イベント処理import flash.events.TimerEvent;import flash.utils.Timer;/*** The Timer that will be used for the alarm.
*/
public var alarmTimer:Timer;...
/*** Instantiates a new AlarmClock of a given size.
*/
public override function initClock(faceSize:Number = 200):void{super.initClock(faceSize);
alarmTimer = new Timer(0, 1);
alarmTimer.addEventListener(TimerEvent.TIMER, onAlarm);}

AlarmClock クラスで定義された Timer インスタンスは alarmTimer と呼ばれます。AlarmClock インスタンスに必要なセットアップ操作を実行する initClock() メソッドは、alarmTimer 変数を使用して 2 つの処理を行います。まず、Timer イン
スタンスが 0 ミリ秒待機し、タイマーイベントを 1 回だけトリガーするように指示するパラメーターを使用して、変数をイ
ンスタンス化します。alarmTimer をインスタンス化した後、コードは変数の addEventListener() メソッドを呼び出し、変数のtimer イベントを監視しようとしていることを示します。指定された時間が経過した後、timer イベントを送出することで、Timer インスタンスが動作します。AlarmClock クラスは、独自のアラームを鳴らすために、いつ timer イベントが送出されたかを知る必要があります。addEventListener() を呼び出すことで、AlarmClock コードは自分自身をリスナーとして
alarmTimer に登録します。2 つのパラメーターは、AlarmClock クラスが timer イベントを監視しようとしていることを示し（定数 TimerEvent.TIMER で指定）、イベントが発生したときに、イベントに対する応答として AlarmClock クラスの
onAlarm() メソッドを呼び出す必要があることを示しています。
実際にアラームを設定するために、AlarmClock クラスの setAlarm() メソッドが次のように呼び出されます。
/*** Sets the time at which the alarm should go off.
* @param hour The hour portion of the alarm time.
* @param minutes The minutes portion of the alarm time.
* @param message The message to display when the alarm goes off.
* @return The time at which the alarm will go off.
*/
public function setAlarm(hour:Number = 0, minutes:Number = 0, message:String = "Alarm!"):Date{this.alarmMessage = message;
var now:Date = new Date();// Create this time on today's date.
alarmTime = new Date(now.fullYear, now.month, now.date, hour, minutes);// Determine if the specified time has already passed today.
if (alarmTime <= now){
alarmTime.setTime(alarmTime.time + MILLISECONDS_PER_DAY);}// Stop the alarm timer if it's currently set.
alarmTimer.reset();// Calculate how many milliseconds should pass before the alarm should// go off (the difference between the alarm time and now) and set that// value as the delay for the alarm timer.
alarmTimer.delay = Math.max(1000, alarmTime.time - now.time);
alarmTimer.start();return alarmTime;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

137

イベント処理このメソッドは、アラームメッセージの格納、Date オブジェクトの作成（alarmTime）、アラームが鳴る実際の時刻の表示など、複数の機能を実行します。この章と最も関係がある部分として、メソッドの最後の数行で、alarmTimer 変数のタイ
マーが設定され、アクティブ化されます。まず、reset() メソッドが呼び出され、タイマーが停止され、既に実行されていた
場合はリセットされます。次に、現在時刻（now 変数で表現）が alarmTime 変数の値から減算され、アラームを鳴らすまでに経過する時間がミリ秒単位で決定されます。Timer クラスは timer イベントを絶対時間ではトリガーしないため、この相対的な時間差が alarmTimer の delay プロパティに割り当てられます。最後に start() メソッドが呼び出され、タイマーが実際に開始されます。
指定された時間が経過すると、alarmTimer は timer イベントを送出します。AlarmClock クラスは、このイベントのリスナーとして onAlarm() メソッドを登録しているため、timer イベントが発生すると、onAlarm() が呼び出されます。
/*** Called when the timer event is dispatched.
*/public function onAlarm(event:TimerEvent):void{
trace("Alarm!");var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage);this.dispatchEvent(alarm);}

イベントリスナーとして登録されたメソッドは、適切なシグネチャ（つまり、メソッドのパラメーターと戻り値の型のセット）を使用して定義する必要があります。メソッドを Timer クラスの timer イベントのリスナーとして使用するには、データ型が Event クラスのサブクラス TimerEvent（flash.events.TimerEvent）であるパラメーターを 1 つ定義する必要があります。Timer インスタンスはイベントリスナーを呼び出すときに、TimerEvent インスタンスをイベントオブジェクトとして渡します。

アラームのその他の事項の通知
Flash Player 9 以降、Adobe AIR 1.0 以降
Timer クラスと同様に、AlarmClock クラスはイベントを提供し、これによってアラームが鳴り出すときに他のコードが通知を受信できます。ActionScript に組み込まれているイベント処理フレームワークをクラスで使用するには、そのクラスでflash.events.IEventDispatcher インターフェイスを実装する必要があります。最も一般的な方法として、
IEventDispatcher の標準実装を提供する flash.events.EventDispatcher クラスを拡張する方法があります（または、EventDispatcher のサブクラスのいずれかを拡張します）。先に説明したように、AlarmClock クラスによってSimpleClock クラスが拡張され、さらに SimpleClock クラスによって EventDispatcher クラスが拡張されています（継承のチェーンが利用されます）。すなわち、AlarmClock クラスには、既に独自のイベントを提供する組み込み機能があります。
他のコードは、AlarmClock が EventDispatcher から継承した addEventListener() メソッドを呼び出すことで、AlarmClock クラスの alarm イベントの通知を受けるように登録できます。alarm イベントが生成されたことをAlarmClock インスタンスが他のコードに通知する準備ができている場合は、同様に EventDispatcher から継承された
dispatchEvent() メソッドを呼び出して通知できます。
var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage);this.dispatchEvent(alarm);

これらのコード行は、AlarmClock クラスの onAlarm() メソッドから取得されます（全体は前に示したとおりです）。

AlarmClock インスタンスの dispatchEvent() メソッドが呼び出され、次に、AlarmClock インスタンスの alarm イベントがトリガーされたことが登録済みのすべてのリスナーに通知されます。dispatchEvent() に渡されるパラメーターは、リスナー
メソッドに渡されるイベントオブジェクトです。この例では、特に作成された Event サブクラスである AlarmEvent クラスのインスタンスです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

138

イベント処理カスタムアラームイベントの提供
Flash Player 9 以降、Adobe AIR 1.0 以降
すべてのイベントリスナーが、トリガーされる特定のイベントに関する情報が設定されているイベントオブジェクトパラ
メーターを受け取ります。多くの場合、イベントオブジェクトは Event クラスのインスタンスです。ただし、場合によっては、追加の情報をイベントリスナーに提供すると便利なことがあります。一般的にはこれを実現するために、新しいクラス（Event クラスのサブクラス）を定義し、このクラスのインスタンスをイベントオブジェクトとして使用します。この例では、AlarmClock クラスの alarm イベントが送出されたときに、AlarmEvent インスタンスがイベントオブジェクトとして使用されています。ここで示す AlarmEvent クラスは、alarm イベントに関する追加の情報（具体的にはアラームメッセージ）を提供します。
import flash.events.Event;/*** This custom Event class adds a message property to a basic Event.
*/public class AlarmEvent extends Event{/*** The name of the new AlarmEvent type.
*/
public static const ALARM:String = "alarm";/*** A text message that can be passed to an event handler* with this event object.
*/public var message:String;/***Constructor.
*@param message The text to display when the alarm goes off.
*/
public function AlarmEvent(message:String = "ALARM!"){
super(ALARM);
this.message = message;}...
}

カスタムイベントオブジェクトクラスを作成する最善の方法は、上述の例で示したように、Event クラスを拡張するクラスを定義することです。継承された機能を補うために、AlarmEvent クラスでは、イベントに関連付けられたアラームメッ
セージのテキストを含むプロパティ message を定義しています。message 値はパラメーターとして AlarmEvent コンストラ
クターに渡されます。AlarmEvent クラスは、定数 ALARM も定義します。これは、AlarmClock クラスのaddEventListener() メソッドを呼び出すときに、特定のイベント（alarm）を参照するために使用できます。
カスタム機能を追加するほか、Event サブクラスでは、ActionScript イベント処理フレームワークの一部として継承された

clone() メソッドをオーバーライドする必要があります。Event サブクラスでは、オプションで、toString() メソッドが呼び出されたときに返される値にカスタムイベントのプロパティを含めるように、継承された toString() メソッドをオーバーライ
ドすることもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

139

イベント処理/*** Creates and returns a copy of the current instance.
* @return A copy of the current instance.
*/
public override function clone():Event{
return new AlarmEvent(message);}/*** Returns a String containing all the properties of the current* instance.
* @return A string representation of the current instance.
*/
public override function toString():String{
return formatToString("AlarmEvent", "type", "bubbles", "cancelable", "eventPhase", "message");}

オーバーライドされた clone() メソッドは、現在のインスタンスに一致するすべてのカスタムプロパティセットを持つカスタム Event サブクラスの新しいインスタンスを返す必要があります。オーバーライドされた toString() メソッドは、ユーティ
リティメソッド formatToString()（Event から継承）を使用して、カスタムタイプの名前およびカスタムタイプのすべてのプ
ロパティの名前と値が設定されたストリングを提供します。

最終更新日 2015/10/14

140

第 9 章：アプリケーションドメインの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ApplicationDomain クラスの目的は、ActionScript 3.0 定義のテーブルを保存することです。SWF ファイル内のすべてのコードは、アプリケーションドメイン内に存在するように定義されます。アプリケーションドメインは、同じセキュリティ
ドメイン内にある複数のクラスを分離するために使用します。それにより、1 つのクラスについて複数の定義を用意することや、子が親の定義を再利用することが可能になります。

ActionScript 3.0 で作成された外部 SWF ファイルを Loader クラス API でロードするときは、アプリケーションドメインを使用できます。ActionScript 1.0 または ActionScript 2.0 で作成された SWF ファイルのイメージをロードするときは、ア
プリケーションドメインを使用できないことに注意してください。ロードされたクラスに含まれているすべてのActionScript 3.0 定義は、アプリケーションドメイン内に格納されます。SWF ファイルをロードするとき、LoaderContext
オブジェクトの applicationDomain パラメーターを ApplicationDomain.currentDomain に設定することにより、ファイルをLoader オブジェクトと同じアプリケーションドメインに含めるよう指定できます。ロードされた SWF ファイルを同じアプ
リケーションドメインに置くと、そのクラスに直接アクセスできます。これは、関連するクラス名によってアクセスできる
メディアが埋め込まれた SWF ファイルをロードする場合や、ロードされた SWF ファイルのメソッドにアクセスする場合に便利です。
次の例では、welcome() という名前のパブリックメソッドを定義している別の Greeter.swf というファイルにアクセスすることを想定しています。
package{import flash.display.Loader;import flash.display.Sprite;
import flash.events.*;
import flash.net.URLRequest;
import flash.system.ApplicationDomain;
import flash.system.LoaderContext;
public class ApplicationDomainExample extends Sprite{
private var ldr:Loader;public function ApplicationDomainExample(){
ldr = new Loader();var req:URLRequest = new URLRequest("Greeter.swf");
var ldrContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain);ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, completeHandler);
ldr.load(req, ldrContext);}
private function completeHandler(event:Event):void{
var myGreeter:Class = ApplicationDomain.currentDomain.getDefinition("Greeter") as Class;var myGreeter:Greeter = Greeter(event.target.content);
var message:String = myGreeter.welcome("Tommy");trace(message); // Hello, Tommy}}}『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の ApplicationDomain クラスの例も参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

141

アプリケーションドメインの操作

それ以外に、アプリケーションドメインを操作するときに注意すべき点は、次のとおりです。

• SWF ファイル内のすべてのコードは、アプリケーションドメイン内に存在するように定義されます。現在のドメインとは、メインアプリケーションが実行される場所のことです。現在のドメインなど、すべてのアプリケーションドメイン
は、システムドメインに含まれます。つまり、システムドメインにはすべての Flash Player クラスが含まれます。

•

システムドメインを除くすべてのアプリケーションドメインには、親ドメインが関連付けられています。メインアプリ
ケーションのアプリケーションドメインの親ドメインは、システムドメインです。ロードされるクラスは、そのクラスの親によってまだ定義されていない場合にのみ定義されます。ロードされるクラスの定義を新しい定義でオーバーライドすることはできません。

次の図に示すアプリケーションでは、様々な SWF ファイルから domain1.com という単一のドメイン内にコンテンツをロードしています。ロードするコンテンツによっては、異なるアプリケーションドメインを使用することもできます。このア
プリケーションに含まれる個々の SWF ファイルでは、それぞれに適した異なる形態でアプリケーションドメインを使用しています。各形態の使い分け方について次に説明します。
セキュリティドメイン：domain1.com
ステージ

Application domain 1
mx.core.Application

application1.swf

module1.swf
Loader
アプリケーション

LoaderLoaderLoader

モジュール

B

Application domain 3
module3.swf
Cモジュール

Application domain 2
mx.core.ApplicationA

application2.swf
モジュール

A. 使用形態 A B. 使用形態 B C. 使用形態 C

メインアプリケーションファイルは application1.swf です。これには、他の SWF ファイルからコンテンツをロードする

Loader オブジェクトが入っています。このシナリオでは、現在のドメインは Application domain 1 です。使用形態 A、使用形態 B、および使用形態 C は、アプリケーション内の各 SWF ファイルに適切なアプリケーションドメインを設定する
様々な手法の例を示しています。
使用形態 A システムドメインの子ドメインを作成することにより、子 SWF ファイルを分離します。図では、システムドメ
インの子ドメインとして Application domain 2 を作成しています。"application2.swf" ファイルを Application domain 2
内にロードしているため、このファイルに含まれるクラス定義は "application1.swf" のクラス定義と分離されます。
この形態の用途としては、古いアプリケーションにおいて同じアプリケーションの新バージョンを動的にロードする場合に競合の発生を防ぐことが考えられます。異なるバージョンを異なるアプリケーションドメインに分離すれば、それぞれにおいて同じクラス名を使用していても競合が発生しません。
次のコードでは、システムドメインの子ドメインとしてアプリケーションドメインを作成し、それを使用して SWF のロードを開始します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

142

アプリケーションドメインの操作

var appDomainA:ApplicationDomain = new ApplicationDomain();var contextA:LoaderContext = new LoaderContext(false, appDomainA);
var loaderA:Loader = new Loader();loaderA.load(new URLRequest("application2.swf"), contextA);

使用形態 B: 現在のクラス定義に新しいクラス定義が追加されます。図では、"module1.swf" に対するアプリケーションド
メインとして現在のドメイン（Application domain 1）を設定しています。この場合、アプリケーションに現在含まれている各種のクラス定義に、新しいクラス定義を加えることになります。この形態は、メインアプリケーションのランタイム共
有ライブラリに使用できます。ロードされた SWF は、リモート共有ライブラリ（RSL）として扱われます。アプリケーショ
ンが開始する前にプリローダーによって RSL をロードするには、このテクニックを使用します。
次のコードでは、SWF をロードし、現在のドメインをアプリケーションドメインとして設定します。
var appDomainB:ApplicationDomain = ApplicationDomain.currentDomain;
var contextB:LoaderContext = new LoaderContext(false, appDomainB);
var loaderB:Loader = new Loader();loaderB.load(new URLRequest("module1.swf"), contextB);

使用形態 C: 現在のドメインの新しい子ドメインを作成することにより、親のクラス定義を使用します。図では、"module3.swf" に対するアプリケーションドメインとして現在のドメインの子ドメインを設定しており、子ドメインでは、
親ドメインに含まれるすべてのクラス定義を使用します。この形態の用途としては、複数画面の RIA（高度なインターネッ
トアプリケーション）を構成するモジュールをメインアプリケーションの子としてロードし、メインアプリケーションで定義されている型をモジュール内でも使用できるようにすることが考えられます。クラスを更新される際に必ず後方互換性を維持するようにし、また、ロードされるモジュールよりもメインアプリケーションを常に新しくしておけば、メインアプリ
ケーションに含まれるクラス定義はモジュール内でも使用されます。また、このようにして新しいアプリケーションドメイ
ン内にロードしたモジュールは、アンロードすれば、すべてのクラス定義をガベージコレクションの対象とすることができます（ただし、子 SWF への参照を確実に破棄する必要があります）。
このテクニックでは、ロードする側にあるシングルトンオブジェクトや静的クラスメンバーを、ロードされる側のモジュールでも共有できます。
次のコードでは、現在のドメインの子ドメインを新しく作成し、そのアプリケーションドメインを使用して SWF のロードを開始します。
var appDomainC:ApplicationDomain = new ApplicationDomain(ApplicationDomain.currentDomain);var contextC:LoaderContext = new LoaderContext(false, appDomainC);
var loaderC:Loader = new Loader();loaderC.load(new URLRequest("module3.swf"), contextC);

最終更新日 2015/10/14

143

第 10 章：表示のプログラミング
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe® ActionScript® 3.0 では、表示ステージ上の表示オブジェクトを操作することで、ビジュアルエレメントをプログラ
ミングできます。例えば、ActionScript の表示プログラミング API を使用して、表示オブジェクトを追加、移動、削除または順序を変更したり、フィルターやマスクを適用したり、ベクターグラフィックやビットマップグラフィックを描画したり、3 次元の変形を実行したりできます。表示プログラミングで使用する主なクラスは、flash.display パッケージに含まれています。
注意：Adobe® AIR™ には、HTML コンテンツのレンダリングおよび表示のために HTMLoader オブジェクトが用意されています。HTMLLoader は、HTML DOM のビジュアルエレメントを 1 つの表示オブジェクトとしてレンダリングします。ActionScript の表示リスト階層を通して DOM の個々のエレメントに直接アクセスすることはできません。その代わり、HTMLLoader によって提供される個別の DOM API を使用して、これらの DOM エレメントにアクセスできます。

表示のプログラミングの基本
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 で構築された各アプリケーションには、表示リストと呼ばれる、表示されるオブジェクトの階層があります。表示リストには、アプリケーション内で表示されるエレメントがすべて含まれます。

ステージ
Stage

SWF ファイルのメインクラスのインスタンス

表示オブジェクト
コンテナ

表示オブジェクト

表示オブジェクト
コンテナ

表示オブジェクト

表示オブジェクト
コンテナ

表示オブジェクト

表示オブジェクト
コンテナ

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

144

表示のプログラミング

図に示すように、表示エレメントは次の 1 つ以上のグループに属します。

•

ステージ
ステージは、表示オブジェクトの基本コンテナです。各アプリケーションには 1 つの Stage オブジェクトがあり、この中に画面の表示オブジェクトがすべて含まれます。ステージは、最上位コンテナで、表示リスト階層の最上位に位置します。
それぞれの SWF ファイルには、関連する ActionScript クラスがあります。これは、SWF ファイルのメインクラスと呼ばれます。SWF ファイルが Flash Player または Adobe AIR 上で開かれると、このクラスのコンストラクター関数が呼び出され、作成されるインスタンス（常に表示オブジェクトの型になります）が Stage オブジェクトの子として追加されます。SWF ファイルのメインクラスは、必ず、Sprite クラスを拡張します（詳細については、148 ページの「表示リストを使用するアプローチの利点」を参照）。

DisplayObject インスタンスの stage プロパティからステージにアクセスできます。詳しくは、156 ページの「Stage プ
ロパティの設定」を参照してください。

•

表示オブジェクト

ActionScript 3.0 では、アプリケーション内で画面上に表示されるすべてのエレメントのタイプは、表示オブジェクトです。flash.display パッケージには DisplayObject クラスが含まれています。これは他の様々なクラスによって拡張される基本クラスです。これらの様々なクラスは、ベクターシェイプ、ムービークリップ、テキストフィールドなどの各種の表示オブジェクトを表します。これらのクラスの概要については、148 ページの「表示リストを使用するアプローチの利点」を参照してください。

•

表示オブジェクトコンテナ
表示オブジェクトコンテナは特殊な型の表示オブジェクトであり、独自の視覚的表現を持つだけでなく、それ自体が表示
オブジェクトである子オブジェクトを含むこともできます。

DisplayObjectContainer クラスは DisplayObject クラスのサブクラスです。DisplayObjectContainer オブジェクトには、子リスト内の複数の表示リストを含めることができます。例えば次の図は、様々な表示オブジェクトを含む

Sprite という DisplayObjectContainer オブジェクトの型を示しています。
A

B

C

D

A. SimpleButton オブジェクト。この型の表示オブジェクトには、「アップ」状態、「ダウン」状態、および「オーバー」状態があります。
B. Bitmap オブジェクト。この例では、Bitmap オブジェクトは Loader オブジェクトを使用して外部 JPEG からロードされました。 C. Shape オブジェクト。この「額縁」には、ActionScript で描画された丸みを付けた矩形が含まれています。Shape オブジェクトには、「ドロップシャドウ」
フィルターが適用されています。 D. TextField オブジェクト。

表示オブジェクトの説明では、DisplayObjectContainer オブジェクトは表示オブジェクトコンテナ、または単にコンテナと呼ばれます。前に説明したように、ステージは表示オブジェクトコンテナです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

145

表示のプログラミング

表示可能な表示オブジェクトはすべて DisplayObject クラスを継承しますが、そのタイプは DisplayObject クラスの特定のサブクラスです。例えば、Shape クラスまたは Video クラスにはコンストラクター関数がありますが、

DisplayObject クラスにはコンストラクター関数はありません。
重要な概念と用語
次の参照リストに、ActionScript グラフィックのプログラミングで使用される重要な用語を示します。
アルファ カラーの透明の度合い（より正確には不透明の度合い）を表すカラー値。例えば、アルファチャンネル値が 60%のカラーは、全強度の 60% だけを表示し、透明度 40% になります。
ビットマップグラフィック コンピューターで、カラーピクセルのグリッド（行および列）として定義されているグラフィッ
ク。一般に、ビットマップグラフィックにはデジタル写真や類似したイメージが含まれます。
ブレンドモード 2 つの重なり合うイメージの内容の相互関係を指定する仕様。一般に、別のイメージの上にある不透明なイメージは、その下にあるイメージを単に遮り、まったく見えなくしますが、それ以外のブレンドモードでは、そのイメージのカラーが様々に混ざり合い、その内容は 2 つのイメージの組み合わせになります。
表示リスト Flash Player および AIR によって目に見える画面の内容としてレンダリングされる表示オブジェクトの階層。
ステージは表示リストのルートであり、ステージまたはステージのいずれかの子に関連付けられたすべての表示オブジェク
トが表示リストを形成します（オブジェクトが、ステージの境界の外部にあるなど、実際にはレンダリングされていない場
合でも）。
表示オブジェクト Flash Player または AIR のある種の視覚的なコンテンツを表すオブジェクト。表示オブジェクトだけを表示リストに入れることができ、すべての表示オブジェクトクラスは、DisplayObject クラスのサブクラスです。
表示オブジェクトコンテナ 特殊な型の表示オブジェクトであり、（通常は）独自の視覚的表現を持つだけでなく、子オブジェクトを含むこともできます。

SWF ファイルのメインクラス SWF ファイルの最も外側の表示オブジェクトのビヘイビアーを定義するクラスであり、概念上は、その SWF ファイル自体のクラスです。例えば、Flash オーサリングで作成された SWF では、メインクラスはドキュメントクラスになります。このクラスには、その他のすべてのタイムラインが含まれる「メインタイムライン」があり、SWF ファイルのメインクラスは、そのメインタイムラインがインスタンスになるクラスです。
マスク イメージの特定の部分を非表示にする（または、逆にイメージの特定の部分だけを表示する）技術。マスクイメージの部分が透明になるので、その下の内容が透けて見えます。この用語は、ペンキが特定の場所に付かないように使用するマ
スキングテープと似ています。
ステージ SWF の目に見えるすべての内容の基礎または背景である視覚的なコンテナ。
変換 図形の視覚的特性を調整すること。オブジェクトの回転、尺度の変更、シェイプの傾斜や歪み、色の変更など。
ベクターグラフィック 特定の特性（太さ、長さ、サイズ、角度、位置）を使用して描かれる線またはシェイプとしてコン
ピューターで定義されるグラフィック。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

146

表示のプログラミング

コア表示クラスFlash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 flash.display パッケージには、Flash Player または AIR で表示できるビジュアルオブジェクトのクラスが含まれています。次の図は、このコア表示オブジェクトクラスのサブクラスの関係を示します。
DisplayObject

AVM1Movie

BitmapInteractiveObject

DisplayObjectContainer SimpleButton

LoaderSpriteMorphShape

Shape

StaticText

Video

TextField

Stage

MovieClip

この図は、表示オブジェクトクラスのクラス継承を示します。StaticText、TextField、および Video などの一部のクラス
は、flash.display パッケージに含まれていませんが、DisplayObject クラスを継承します。

DisplayObject クラスを拡張するすべてのクラスはそのメソッドとプロパティを継承します。詳しくは、150 ページの「DisplayObject クラスのプロパティとメソッド」を参照してください。

flash.display パッケージに含まれる次のクラスのオブジェクトをインスタンス化することができます。

• Bitmap - Bitmap クラスを使用して、外部ファイルからロードされたビットマップオブジェクト、または ActionScript
でレンダリングされたビットマップオブジェクトを定義します。Loader クラスを使用して外部ファイルからビットマッ
プをロードできます。ロードできるのは、GIF、JPG、PNG ファイルです。カスタムデータを使用して BitmapData オブ
ジェクトを作成した後、そのデータを使用する Bitmap オブジェクトを作成することもできます。ビットマップがロードされたか ActionScript で作成されたかに関係なく、BitmapData クラスのメソッドを使用してビットマップを変更できます。詳しくは、189 ページの「表示オブジェクトのロード」および 230 ページの「ビットマップの操作」を参照してください。

• Loader - Loader クラスを使用して、外部アセット（SWF ファイルまたはグラフィック）をロードします。詳しくは、
189 ページの「表示コンテンツの動的ロード」を参照してください。
• Shape - Shape クラスを使用して、ベクターグラフィック（矩形、線、円など）を作成します。詳しくは、212 ページの「描画 API の使用」を参照してください。
• SimpleButton - SimpleButton オブジェクトは、Flash オーサリングツールで作成されたボタンシンボルのActionScript 表現です。SimpleButton インスタンスには、アップ、ダウン、オーバー、およびヒットテスト（マウスとキーボードのイベントに対応する領域）の 4 つのボタン状態があります。
• Sprite - Sprite オブジェクトには独自のグラフィックを格納でき、子表示オブジェクトを格納することもできます。
Sprite クラスは DisplayObjectContainer クラスを拡張します。詳しくは、151 ページの「表示オブジェクトコンテナの操作」および 212 ページの「描画 API の使用」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

147

表示のプログラミング• MovieClip - MovieClip オブジェクトは、Flash オーサリングツールで作成されたムービークリップシンボルのActionScript 形式です。実際に、MovieClip は、タイムラインがあること以外、Sprite オブジェクトと似ています。詳
しくは、306 ページの「ムービークリップの操作」を参照してください。
flash.display パッケージ内にない次のクラスは、DisplayObject クラスのサブクラスです。

• flash.text パッケージに含まれる TextField クラスは、テキストの表示と入力用の表示オブジェクトです。詳しくは、352
ページの「テキストの操作の基礎」を参照してください。

• flash.text.engine パッケージに含まれる TextLine クラスは、Flash Text Engine および Text Layout Framework が作成するテキスト行の表示用の表示オブジェクトです。詳しくは、378 ページの「Flash Text Engine の使用」と 406 ページの「Text Layout Framework の使用」を参照してください。
• flash.media パッケージに含まれる Video クラスは、ビデオファイルの表示に使用される表示オブジェクトです。詳しくは、453 ページの「ビデオの操作」を参照してください。
flash.display パッケージに含まれる次のクラスは DisplayObject クラスを拡張しますが、これらのクラスのインスタンスを作成することはできません。その代わり、これらのクラスは他の表示オブジェクトの親クラスとなり、一般的な機能を単一のクラスに結合します。

• AVM1Movie - AVM1Movie クラスを使用して、ActionScript 1.0 または 2.0 でオーサリングされたロード済み SWF
ファイルを表現します。

• DisplayObjectContainer - Loader、Stage、Sprite、MovieClip の各クラスは、DisplayObjectContainer クラスを拡張します。詳しくは、151 ページの「表示オブジェクトコンテナの操作」を参照してください。
• InteractiveObject - InteractiveObject は、マウスとキーボードの操作に使用されるすべてのオブジェクトの基本クラスです。SimpleButton、TextField、Loader、Sprite、Stage、および MovieClip オブジェクトはすべて
InteractiveObject クラスのサブクラスです。マウスおよびキーボード操作の作成について詳しくは、532 ページの「ユーザー操作の基礎」を参照してください。

• MorphShape - このオブジェクトは、Flash オーサリングツールでシェイプトゥイーンを作成したときに作成されます。
MorphShape オブジェクトは、ActionScript を使用してインスタンス化することはできませんが、表示リストからはア
クセスできます。

• Stage - Stage クラスは、DisplayObjectContainer クラスを拡張します。アプリケーションには Stage インスタンスが 1
つあります。Stage インスタンスは表示リスト階層の最上位にあります。Stage にアクセスするには、任意のDisplayObject インスタンスの stage プロパティを使用します。詳しくは、156 ページの「Stage プロパティの設定」を参照してください。
また、flash.text パッケージ内の StaticText クラスは DisplayObject クラスを拡張しますが、インスタンスをコードで作成することはできません。静止テキストフィールドは、Flash だけで作成できます。
次のクラスは、表示オブジェクトでも表示オブジェクトコンテナでもないので表示リストには含まれませんが、ステージ上
でグラフィックの表示を実行します。これらのクラスはビューポートと呼ばれる矩形に描画され、ステージを基準として相対的に配置されます。

• StageVideo - StageVideo クラスは、可能な場合にハードウェアアクセラレーションを使用してビデオコンテンツを表示します。このクラスは Flash Player 10.2 以上で使用できます。詳しくは、489 ページの「ハードウェアアクセラレー
ションによる表示のための StageVideo クラスの使用」を参照してください。
• StageWebView - StageWebView クラスは HTML コンテンツを表示します。このクラスは AIR 2.5 以降で利用できます。詳しくは、988 ページの「StageWebView オブジェクト」を参照してください。
次の fl.display の各クラスでは、flash.display.Loader および LoaderInfo クラスと同等の機能が提供されます。Flash
Professional 環境（CS5.5 以降）で開発している場合は、flash.display の同等のクラスの代わりにこれらのクラスを使用してください。この環境では、これらのクラスが RSL プリロードによる TLF 関連の問題の解決に役立ちます。詳しくは、193ページの「ProLoader クラスおよび ProLoaderInfo クラスの使用」を参照してください。

• fl.display.ProLoader - flash.display.Loader に類似
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

148

表示のプログラミング• fl.display.ProLoaderInfo - flash.display.LoaderInfo に類似

表示リストを使用するアプローチの利点
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、各種の表示オブジェクトに対して別個のクラスがあります。ActionScript 1.0 および 2.0 では、同じタイプの多くのオブジェクトが、すべて 1 つのクラス、MovieClip クラスに含まれます。
このようなクラスの個別化および表示リストの階層構造には、次のような利点があります。

•

レンダリングの効率化とメモリ使用量の削減•

深度管理の向上•

表示リスト内の自由な移動•

リスト外表示オブジェクト•

表示オブジェクトのより容易なサブクラス化

レンダリングの効率化とファイルサイズの縮小
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 1.0 および 2.0 では、MovieClip オブジェクトでのみシェイプを描画できました。ActionScript 3.0 には、シェイプを描画できる簡単な表示オブジェクトクラスがあります。ActionScript 3.0 表示オブジェクトクラスには、MovieClip オブジェクトに含まれるメソッドとプロパティがすべて含まれるわけではないため、メモリおよびプロセッサー
リソースへの負担が軽減されます。
例えば、各 MovieClip オブジェクトにはムービークリップのタイムラインのプロパティが含まれますが、Shape オブジェ
クトには含まれません。タイムラインを制御するためのプロパティは、大量のメモリおよびプロセッサーリソースを使用する場合があります。ActionScript 3.0 では、Shape オブジェクトを使用することでパフォーマンスが向上します。Shape オブ
ジェクトは、複雑な MovieClip オブジェクトよりオーバーヘッドが少なくなります。Flash Player および AIR では、使用されていない MovieClip プロパティを管理する必要はないため、スピードが向上し、オブジェクトが使用するメモリフットプ
リントが削減されます。

深度管理の向上Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 1.0 および 2.0 では、getNextHighestDepth() のような線状の深度管理スキームとメソッドを使用して深度を管理します。

ActionScript 3.0 には、表示オブジェクトの深度を管理するために便利なメソッドおよびプロパティが含まれる
DisplayObjectContainer クラスがあります。
ActionScript 3.0 では、表示オブジェクトを DisplayObjectContainer インスタンスの子リスト内の新しい位置に移動すると、表示オブジェクトコンテナ内の他の子は、自動的に位置が変更され、表示オブジェクトコンテナ内の適切な子インデッ
クス位置が割り当てられます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

149

表示のプログラミング

ActionScript 3.0 では、常に表示オブジェクトコンテナの子オブジェクトをすべて見つけることができます。どの
DisplayObjectContainer インスタンスにも、表示オブジェクトコンテナの子の数を一覧表示する numChildren プロパティがあります。また、表示オブジェクトコンテナの子リストは常にインデックスリストであるため、リスト内のインデックス
位置 0 から最後のインデックス位置（numChildren - 1）までのすべてのオブジェクトを調べることができます。これは、ActionScript 1.0 および 2.0 の MovieClip オブジェクトのメソッドとプロパティでは不可能でした。
ActionScript 3.0 では、表示リスト内を順に移動するのは簡単です。表示オブジェクトコンテナの子リストのインデックス
番号に欠落番号がないためです。表示リスト内の移動とオブジェクトの深度管理は、ActionScript 1.0 および 2.0 より大幅に簡単になりました。ActionScript 1.0 および 2.0 では、ムービークリップに、深度順に断続的な欠落があるオブジェクトが含まれている可能性があり、オブジェクトのリスト内を移動するのが困難でした。ActionScript 3.0 では、表示オブジェク
トコンテナのそれぞれの子リストが 1 つの配列として内部にキャッシュされるので、インデックスによるルックアップが非
常に高速に実行されます。また、表示オブジェクトコンテナのすべての子を非常に高速にループすることもできます。

ActionScript 3.0 では、DisplayObjectContainer クラスの getChildByName() メソッドを使用して表示オブジェクトコンテ
ナの子にアクセスすることもできます。

表示リスト内の自由な移動
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 1.0 および 2.0 では、ベクターシェイプなど、Flash オーサリングツールで描画されたオブジェクトにはアクセスできませんでした。ActionScript 3.0 では、表示リスト内のすべてのオブジェクトにアクセスできます。これには、ActionScript を使用して作成されたオブジェクト、および Flash オーサリングツールで作成されたすべての表示オブジェク
トの両方が含まれます。詳しくは、155 ページの「表示リスト内の移動」を参照してください。

リスト外表示オブジェクト
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、表示リストに表示されない表示オブジェクトを作成できます。これらのオブジェクトをリスト外表
示オブジェクトと呼びます。表示オブジェクトは、既に表示リストに追加されている DisplayObjectContainer インスタン
スの addChild() または addChildAt() メソッドを呼び出したときにのみ、表示可能な表示リストに追加されます。
リスト外表示オブジェクトを使用すると、複数の表示オブジェクトが含まれる複数の表示オブジェクトコンテナを持つ表示
オブジェクトなど、複雑な表示オブジェクトを構成できます。表示オブジェクトをリスト外にしておくことで、これらの表
示オブジェクトをレンダリングする処理時間をかけずに、複雑なオブジェクトを構成できます。これにより、必要に応じて
リスト外表示オブジェクトを表示リストに追加できます。また、表示オブジェクトコンテナの子を表示リスト内および外に、
または表示リスト内の必要な場所に任意に移動できます。

表示オブジェクトのより容易なサブクラス化
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 1.0 および 2.0 では、通常は SWF ファイルに新しい MovieClip オブジェクトを追加して、基本シェイプを作成するか、またはビットマップを表示します。ActionScript 3.0 では、DisplayObject クラスに Shape、Bitmap などの多くのビルトインサブクラスが含まれています。ActionScript 3.0 のクラスは特定のタイプのオブジェクト用に特化されているので、ビルトインクラスの基本サブクラスを簡単に作成できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

150

表示のプログラミング

例えば、ActionScript 2.0 で円を描画するには、カスタムクラスのオブジェクトをインスタンス化したときに MovieClip ク
ラスを拡張する CustomCircle クラスを作成できました。しかし、このクラスには、クラスに適用されない MovieClip クラスの多数のプロパティやメソッド（totalFrames など）も含まれてしまいます。ActionScript 3.0 では、Shape オブジェクトを拡張する CustomCircle クラスを作成できるため、MovieClip クラスに含まれている関係のないプロパティやメソッドが含まれることはありません。次のコードは、CustomCircle クラスの例です。
import flash.display.*;
public class CustomCircle extends Shape{var xPos:Number;var yPos:Number;var radius:Number;var color:uint;
public function CustomCircle(xInput:Number,yInput:Number,rInput:Number,colorInput:uint){
xPos = xInput;
yPos = yInput;
radius = rInput;
color = colorInput;
this.graphics.beginFill(color);
this.graphics.drawCircle(xPos, yPos, radius);}}

表示オブジェクトの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ステージ、表示オブジェクト、表示オブジェクトコンテナ、および表示リストの基本概念を理解できたので、このセクショ
ンでは、ActionScript 3.0 での表示オブジェクトの操作について詳しく説明します。

DisplayObject クラスのプロパティとメソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
すべての表示オブジェクトは、DisplayObject クラスのサブクラスです。従って、表示オブジェクトは DisplayObject クラスのプロパティとメソッドを継承します。継承したプロパティは、すべての表示オブジェクトに適用される基本プロパティです。例えば、表示オブジェクトには、表示オブジェクトコンテナ内のオブジェクトの位置を指定する x プロパティと y プロ
パティがあります。

DisplayObject クラスコンストラクターを使用して DisplayObject インスタンスを作成することはできません。Sprite など
別の型のオブジェクト（DisplayObject クラスのサブクラスであるオブジェクト）を作成することにより、new 演算子でオブジェクトをインスタンス化する必要があります。また、カスタム表示オブジェクトクラスを作成する場合は、例えば、

Shape クラスや Sprite クラスなど、使用可能なコンストラクター関数を持ついずれかの表示オブジェクトサブクラスのサブクラスを作成する必要があります。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』のDisplayObject クラスの説明を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

151

表示のプログラミング

表示リストへの表示オブジェクトの追加
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトをインスタンス化する場合、表示リストにある表示オブジェクトコンテナに表示オブジェクトインスタン
スを追加するまで、表示オブジェクトは画面（ステージ）に表示されません。例えば、次のコードでは、コードの最後の行を省略すると myText TextField オブジェクトは表示されません。コードの最後の行で、this キーワードは、既に表示リストに追加されている表示オブジェクトコンテナを参照する必要があります。
import flash.display.*;
import flash.text.TextField;
var myText:TextField = new TextField();
myText.text = "Buenos dias.";this.addChild(myText);

ステージにビジュアルエレメントを追加すると、そのエレメントは、Stage オブジェクトの子になります。アプリケーショ
ン内にロードされた最初の SWF ファイル（HTML ページに埋め込む SWF ファイルなど）は、自動的に Stage オブジェクトの子として追加されます。これは、Sprite クラスを拡張する型のオブジェクトです。

ActionScript を使用せずに作成した表示オブジェクトは、表示リストに追加されます。例えば、Flex MXML ファイルでMXML タグを追加したり、Flash Professional のステージにアイテムを配置することで作成した表示オブジェクトです。これらの表示オブジェクトは ActionScript を使用して追加されていませんが、ActionScript からアクセスできます。例えば、
次のコードは、ActionScript ではなくオーサリングツールで追加された button1 というオブジェクトの幅を調整します。
button1.width = 200;

表示オブジェクトコンテナの操作Flash Player 9 以降、Adobe AIR 1.0 以降
DisplayObjectContainer オブジェクトが表示リストから削除されたか、何らかの方法で移動または変換された場合、DisplayObjectContainer 内の各表示オブジェクトも、削除、移動、変換されます。
表示オブジェクトコンテナはそれ自体が表示オブジェクトの 1 つの型であり、別の表示オブジェクトコンテナに追加できます。例えば、次の図は、アウトラインシェイプ 1 つと（PictureFrame 型の）表示オブジェクトコンテナ 4 つを含む表示オ
ブジェクトコンテナ pictureScreen を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

152

表示のプログラミング

AB

A. pictureScreen 表示オブジェクトコンテナの境界を定義するシェイプ B. pictureScreen オブジェクトの子である表示オブジェクトコンテナ 4 つ

表示リストに表示オブジェクトを表示するには、表示リスト上にある表示オブジェクトコンテナに表示オブジェクトを追加する必要があります。これには、コンテナオブジェクトの addChild() メソッドまたは addChildAt() メソッドを使用します。
例えば、次のコードの最後の行がなければ、myTextField オブジェクトは表示されません。
var myTextField:TextField = new TextField();
myTextField.text = "hello";
this.root.addChild(myTextField);

このサンプルコードでは、コードを格納する MovieClip 表示オブジェクトコンテナを this.root によって指定します。実際のコードでは、別のコンテナを指定できます。
表示オブジェクトコンテナの子リスト内の特定の位置に子を追加するには、addChildAt() メソッドを使用します。子リスト
内の 0 から始まるインデックス位置は、表示オブジェクトのレイヤー（前から後ろへの順）に対応しています。例えば、次のような 3 つの表示オブジェクトがあるとします。各オブジェクトは、Ball と呼ばれるカスタムクラスから作成されました。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

153

表示のプログラミング

コンテナ内のこれらの表示オブジェクトのレイヤーは、addChildAt() メソッドを使用して調整できます。例えば、次のようなコードがあるとします。
ball_A = new Ball(0xFFCC00, "a");ball_A.name = "ball_A";
ball_A.x = 20;
ball_A.y = 20;
container.addChild(ball_A);
ball_B = new Ball(0xFFCC00, "b");ball_B.name = "ball_B";
ball_B.x = 70;
ball_B.y = 20;
container.addChild(ball_B);
ball_C = new Ball(0xFFCC00, "c");ball_C.name = "ball_C";
ball_C.x = 40;
ball_C.y = 60;
container.addChildAt(ball_C, 1);

このコードを実行後、表示オブジェクトは、container DisplayObjectContainer オブジェクト内で次のように配置されます。オブジェクトのレイヤーに注意してください。

表示リストの一番上にオブジェクトを再配置するには、リストにオブジェクトを再度追加するだけです。例えば、前のコードの実行後、ball_A をスタックの最上部に移動するには、次のコード行を使用します。
container.addChild(ball_A);

このコードは、ball_A を container の表示リスト内から削除してリストの最上部に再度追加します。その結果、スタックの最上部に移動されます。
表示オブジェクトのレイヤーの順序を確認するには、getChildAt() メソッドを使用します。getChildAt() メソッドは、メソッ
ドに渡すインデックス番号に基づいてコンテナの子オブジェクトを返します。例えば、次のコードは、container

DisplayObjectContainer オブジェクトの子リスト内の異なる位置にある表示オブジェクトの名前を表示します。
trace(container.getChildAt(0).name); // ball_A
trace(container.getChildAt(1).name); // ball_C
trace(container.getChildAt(2).name); // ball_B

親コンテナの子リストから表示オブジェクトを削除すると、リスト上でそれより上位にあるエレメントの子インデックス内の位置がそれぞれ下がります。例えば、引き続き前のコードを使用すると、次のコードは、子リスト内の下位にある表示オ
ブジェクトが削除された場合、container DisplayObjectContainer 内の位置 2 にあった表示オブジェクトが位置 1 に移動することを示します。
container.removeChild(ball_C);
trace(container.getChildAt(0).name); // ball_A
trace(container.getChildAt(1).name); // ball_B

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

154

表示のプログラミング

removeChild() および removeChildAt() メソッドは、表示オブジェクトインスタンスを完全に削除しません。コンテナの子リストから削除するだけです。インスタンスは、別の変数で参照できます オブジェクトを完全に削除するには、delete 演算子を使用します。
表示オブジェクトには親コンテナが 1 つだけあるので、その 1 つだけの表示オブジェクトコンテナに表示オブジェクトのイ
ンスタンスを追加できます。例えば、次のコードは、表示オブジェクト tf1 が 1 つだけのコンテナ（この例では、DisplayObjectContainer クラスを拡張する Sprite）内にあることを示します。
tf1:TextField = new TextField();
tf2:TextField = new TextField();
tf1.name = "text 1";
tf2.name = "text 2";
container1:Sprite = new Sprite();container2:Sprite = new Sprite();container1.addChild(tf1);
container1.addChild(tf2);
container2.addChild(tf1);
trace(container1.numChildren); // 1
trace(container1.getChildAt(0).name); // text 2
trace(container2.numChildren); // 1
trace(container2.getChildAt(0).name); // text 1

表示オブジェクトコンテナ内に含まれる表示オブジェクトを別の表示オブジェクトコンテナに追加すると、表示オブジェク
トは最初の表示オブジェクトコンテナの子リストから削除されます。
上記で説明したメソッド以外にも、DisplayObjectContainer クラスでは、子表示オブジェクトを操作するための次のようなメソッドが定義されています。

• contains()：表示オブジェクトが DisplayObjectContainer の子であるかどうかを指定します。
• getChildByName()：表示オブジェクトを名前によって取得します。
• getChildIndex()：表示オブジェクトのインデックス位置を返します。
• setChildIndex()：子表示オブジェクトの位置を変更します。
• removeChildren()：複数の子表示オブジェクトを削除します。
• swapChildren()：2 つの表示オブジェクトの重ね順を入れ替えます。
• swapChildrenAt()：指定されたインデックス位置にある 2 つの表示オブジェクトの重ね順を入れ替えます。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の関連する項目を参照してください。
表示リスト外の表示オブジェクト、すなわち Stage の子である表示オブジェクトコンテナに含まれない表示オブジェクトをリスト外表示オブジェクトと呼びます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

155

表示のプログラミング

表示リスト内の移動
Flash Player 9 以降、Adobe AIR 1.0 以降
既に見たように、表示リストはツリー構造です。ツリーの一番上には、複数の表示オブジェクトを含めることができるス
テージがあります。これらの表示オブジェクトは、それ自体が表示オブジェクトコンテナであり、別の表示オブジェクト、
つまり表示オブジェクトコンテナを含めることができます。

ステージ
Stage

SWF ファイルのメインクラスのインスタンス

表示オブジェクト
コンテナ

表示オブジェクト

表示オブジェクト
コンテナ

表示オブジェクト

表示オブジェクト
コンテナ

表示オブジェクト

表示オブジェクト
コンテナ

DisplayObjectContainer クラスには、表示オブジェクトコンテナの子リストを使用して表示リスト内を移動するためのプ
ロパティとメソッドが含まれています。例えば、次のようなコードがあるとします。このコードは、2 つの表示オブジェクト

title と pict を container オブジェクト（Sprite、Sprite クラスは DisplayObjectContainer クラスを拡張します）に追加します。
var container:Sprite = new Sprite();var title:TextField = new TextField();
title.text = "Hello";
var pict:Loader = new Loader();var url:URLRequest = new URLRequest("banana.jpg");
pict.load(url);
pict.name = "banana loader";container.addChild(title);
container.addChild(pict);

getChildAt() メソッドは、特定のインデックス位置にある表示リストの子を返します。
trace(container.getChildAt(0) is TextField); // true

子オブジェクトに名前でアクセスすることもできます。表示オブジェクトには name プロパティがあります。name プロパ
ティを割り当てなかった場合は、Flash Player では「instance1」などのデフォルト値が割り当てられます。例えば、次のコードは、getChildByName() メソッドを使用して「banana loader」という名前で子表示オブジェクトにアクセスする方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

156

表示のプログラミング

trace(container.getChildByName("banana loader") is Loader); // true

getChildByName() メソッドを使用すると、getChildAt() メソッドを使用するよりパフォーマンスが低下します。
表示オブジェクトコンテナには表示リストの子オブジェクトとして別の表示オブジェクトコンテナを含めることができるため、ツリーのようにアプリケーションの表示リスト内を移動できます。例えば、前述のコードの抜粋では、pict Loader オブ
ジェクトのロード操作が完了すると、pict オブジェクトにビットマップである子表示オブジェクトがロードされます。この
ビットマップ表示オブジェクトにアクセスするために、pict.getChildAt(0) を記述することができます。また、
container.getChildAt(0) == pict であるため、container.getChildAt(0).getChildAt(0) を記述することもできます。
次の関数は、表示オブジェクトコンテナから表示リストのインデントされた trace() を出力します。
function traceDisplayList(container:DisplayObjectContainer,indentString:String = ""):void{
var child:DisplayObject;for (var i:uint=0; i < container.numChildren; i++){child = container.getChildAt(i);trace(indentString, child, child.name);if (container.getChildAt(i) is DisplayObjectContainer){
traceDisplayList(DisplayObjectContainer(child), indentString + "")}}}Adobe Flex
Flex を使用する場合、Flex では数多くのコンポーネント表示オブジェクトクラスが定義され、これらのクラスではDisplayObjectContainer クラスの表示リストアクセスメソッドがオーバーライドされることに注意してください。例えば、
mx.core パッケージの Container クラスでは、addChild() メソッドと、Container クラスで拡張される
DisplayObjectContainer クラスの他のメソッドがオーバーライドされます。addChild() メソッドの場合、クラスによってメ
ソッドがオーバーライドされるときに、Flex で Container インスタンスにすべてのタイプの表示オブジェクトを追加することはできません。この場合、オーバーライドされたメソッドでは、追加する子オブジェクトのタイプを

mx.core.UIComponent オブジェクトにする必要があります。

Stage プロパティの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
Stage クラスは、DisplayObject クラスのほとんどのプロパティとメソッドをオーバーライドします。オーバーライドされたプロパティまたはメソッドのいずれかを呼び出した場合、Flash Player および AIR は例外をスローします。例えば、Stage
オブジェクトは、アプリケーションのメインコンテナとして位置が固定されているため、x プロパティや y プロパティを持ちません。x プロパティと y プロパティは、コンテナを基準として表示オブジェクトの位置を参照します。Stage オブジェク
トは別の表示オジェクトコンテナに含まれていないので、この 2 つのプロパティは適用されません。
注意：Stage クラスの一部のプロパティおよびメソッドは、最初にロードされた SWF ファイルと同じセキュリティサンド
ボックス内にあるオブジェクトを表示するためにのみ使用できます。詳しくは、1026 ページの「ステージのセキュリティ」
を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

157

表示のプログラミング

再生フレームレートの制御
Flash Player 9 以降、Adobe AIR 1.0 以降
Stage クラスの frameRate プロパティは、アプリケーションにロードされたすべての SWF ファイルのフレームレートを設定するために使用します。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

ステージの拡大／縮小の制御
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player または AIR を表す画面の部分のサイズが変更されると、ランタイムは自動的にステージのコンテンツを調整して補正します。ステージのコンテンツを調整する方法は、Stage クラスの scaleMode プロパティで指定します。このプロパ
ティには、flash.display.StageScaleMode クラスの定数として定義されている次の 4 つの異なる値を設定できます。

• StageScaleMode.EXACT_FIT：元のコンテンツの縦横比を無視して、新しいステージサイズに合わせて SWF を拡大／縮小します。拡大／縮小率が幅と高さで異なる場合にステージの縦横比が変更されると、コンテンツが伸びたり縮んだりして見えるおそれがあります。

• StageScaleMode.SHOW_ALL：コンテンツの縦横比を変更せずに、新しいステージサイズ内に全体が収まるように SWF
を拡大／縮小します。この拡大／縮小モードではコンテンツの全体が表示されますが、標準のテレビでワイドスクリーンのムービーを見る際に現れる黒い帯のような、「レターボックス」の枠線が表示されることがあります。

• StageScaleMode.NO_BORDER：コンテンツの縦横比を変更せずに、新しいステージサイズ全体を満たすように SWF を拡大／縮小します。この拡大／縮小モードではステージ表示領域全体が利用されますが、トリミングが発生する場合があります。

• StageScaleMode.NO_SCALE：SWF を拡大／縮小しません。新しいステージサイズの方が小さい場合は、コンテンツのト
リミングが発生します。新しいステージサイズの方が大きい場合は、余分な領域は空白となります。

StageScaleMode.NO_SCALE 拡大／縮小モードでのみ、Stage クラスの stageWidth プロパティと stageHeight プロパティ
を使用して、サイズ変更後のステージの実際のピクセルサイズを指定できます。（他の拡大／縮小モードでは、stageWidth および stageHeight プロパティは常に SWF の元の幅と高さを反映します）。さらに、scaleMode をStageScaleMode.NO_SCALE に設定した場合、SWF ファイルがサイズ変更されると Stage クラスの resize イベントが送出されるので、それに合わせて調整することができます。
結果として、scaleMode を StageScaleMode.NO_SCALE に設定することにより、必要な場合は、ウィンドウのサイズ変更に応じて画面の内容をより詳細に制御できます。例えば、ビデオとコントロールバーが含まれる SWF の場合、ステージ
がサイズ変更されたときに、コントロールバーのサイズを変えずに、ビデオウィンドウのサイズだけをステージサイズの変更に合わせて変更できます。例を次のコードに示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

158

表示のプログラミング// mainContent is a display object containing the main content;// it is positioned at the top-left corner of the Stage, and// it should resize when the SWF resizes.
// controlBar is a display object (e.g. a Sprite) containing several// buttons; it should stay positioned at the bottom-left corner of the// Stage (below mainContent) and it should not resize when the SWF// resizes.
import flash.display.Stage;
import flash.display.StageAlign;import flash.display.StageScaleMode;
import flash.events.Event;var swfStage:Stage = mainContent.stage;
swfStage.scaleMode = StageScaleMode.NO_SCALE;
swfStage.align = StageAlign.TOP_LEFT;
swfStage.addEventListener(Event.RESIZE, resizeDisplay);function resizeDisplay(event:Event):void{
var swfWidth:int = swfStage.stageWidth;
var swfHeight:int = swfStage.stageHeight;// Resize the main content area
var newContentHeight:Number = swfHeight - controlBar.height;
mainContent.height = newContentHeight;
mainContent.scaleX = mainContent.scaleY;// Reposition the control bar.
controlBar.y = newContentHeight;}

AIR ウィンドウに対するステージの拡大／縮小モードの設定
ステージの scaleMode プロパティは、ウィンドウのサイズを変更した場合に、ステージで子表示オブジェクトを拡大／縮小
したり切り取ったりする方法を決定します。AIR では、noScale モードしか使用できません。このモードでは、ステージは拡大／縮小されません。その代わり、ステージのサイズは、ウィンドウの境界を使用して直接変更します。ウィンドウのサ
イズを小さくした場合は、ウィンドウが切り取られることがあります。
ステージの拡大／縮小モードは、ステージのサイズや縦横比を常に制御できるとは限らない Web ブラウザーなどの環境用に設計されています。モードにより、ステージがアプリケーションの理想的なサイズまたは縦横比に一致しない場合の最良の妥協策を選択できます。AIR ではステージを常に制御できるので、コンテンツの再レイアウトやウィンドウサイズの調整を行うことにより、ほとんどの場合、ステージの拡大／縮小を有効にするよりも適切な結果が得られます。
ブラウザーと AIR の初期ウィンドウでは、ウィンドウサイズと最初の縮尺率の関係は、読み込んだ SWF ファイルから読み取られます。ただし、NativeWindow オブジェクトを作成する場合は、AIR によってウィンドウサイズと縮尺率（72:1）の任意の関係が選択されます。したがって、ウィンドウが 72 x 72 ピクセルの場合、ウィンドウに追加された 10 x 10 の矩形は正しいサイズ（10 x 10 ピクセル）で描画されます。ただし、ウィンドウが 144 x 144 ピクセルの場合は、10 x 10 ピクセ
ルの矩形は 20 x 20 ピクセルに拡大されます。ウィンドウのステージに noScale 以外の scaleMode プロパティをどうしても使用する場合は、ウィンドウの表示オブジェクトの縮尺率を「72 ピクセル対ステージの現在の幅と高さ」に設定することによって補正できます。例えば、次のコードでは、client という名前の表示オブジェクトに必要な縮尺率を計算します。
if(newWindow.stage.scaleMode != StageScaleMode.NO_SCALE){
client.scaleX = 72/newWindow.stage.stageWidth;client.scaleY = 72/newWindow.stage.stageHeight;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

159

表示のプログラミング

注意：Flex ウィンドウと HTML ウィンドウでは、ステージの scaleMode プロパティは自動的に noScale に設定されます。

scaleMode を変更すると、これらのタイプのウィンドウで使用されている自動レイアウト機能の動作が妨げられます。

フルスクリーンモードの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
フルスクリーンモードを使用すると、ムービーのステージをビューアのモニター全体に設定できます。境界線やメニューなどは表示されません。Stage クラスの displayState プロパティは、SWF のフルスクリーンモードのオンとオフを切り替えるために使用されます。displayState プロパティは、flash.display.StageDisplayState クラスの定数で定義されるいずれかの値に設定できます。フルスクリーンモードをオンにするには、displayState プロパティを StageDisplayState.FULL_SCREEN に設定します。
stage.displayState = StageDisplayState.FULL_SCREEN;

フルスクリーンインタラクティブモード（Flash Player 11.3 の新機能）をオンにするには、displayState プロパティをStageDisplayState.FULL_SCREEN_INTERACTIVE に設定します。
stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE;

フルスクリーンモードは、マウスがクリックされた場合（右クリックを含む）またはキーが押された場合の応答として、

ActionScript によってのみ初期化することができます。アプリケーションのセキュリティサンドボックスで実行される AIR
コンテンツでは、ユーザーの操作に応答してフルスクリーンモードに入る必要はありません。
フルスクリーンモードを終了するには、displayState プロパティを StageDisplayState.NORMAL に設定します。
stage.displayState = StageDisplayState.NORMAL;

また、別のウィンドウにフォーカスを切り替えるか、Esc キー（すべてのプラットフォーム共通）、Ctrl+W キー（Windows）、Command+W キー（Mac OS）、Alt+F4 キー（Windows）のいずれかを使用してフルスクリーンモードを終了することもできます。

Flash Player のフルスクリーンモードの有効化
HTML ページに埋め込まれた SWF ファイルでフルスクリーンモードを有効にするには、Flash Player を埋め込む HTML
コードに param タグを含め、次のように embed 属性で名前 allowFullScreen と値 true を指定する必要があります。
<object>...
<param name="allowFullScreen" value="true" /><embed ... allowFullScreen="true" /></object>

Flash オーサリングツールで、ファイル／パブリッシュ設定を選択し、パブリッシュ設定ダイアログの「HTML」タブで、「Flash のみ - フルスクリーンサポート」テンプレートを選択します。

Flex で、HTML テンプレートにフルスクリーンをサポートする <object> タグおよび <embed> タグが含まれていることを確認します。

Web ページ内の JavaScript を使用して SWF 埋め込みタグを生成する場合、JavaScript を変更して、allowFullScreen param
タグや属性を追加する必要があります。例えば、HTML ページで AC_FL_RunContent() 関数（Flash Professional およびFlash Builder で生成された HTML ページで使用される）を使用する場合、allowFullScreen パラメーターを該当の関数呼び出しに対して次のように追加する必要があります。
AC_FL_RunContent(...
'allowFullScreen','true',...
); //end AC code

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

160

表示のプログラミング

これは、スタンドアローンの Flash Player で実行される SWF ファイルには適用されません。
注意：ウィンドウモード（HTML の wmode）を「不透明表示」（不透明）または「透明表示」（透明）に設定した場合、フルスクリーンウィンドウは常に不透明になります。
また、ブラウザー上の Flash Player におけるフルスクリーンモードの使用については、セキュリティに関連する制限があります。それらの制限についての説明は、1004 ページの「セキュリティ」を参照してください。

Flash Player 11.3 以降のフルスクリーンインタラクティブモードの有効化
Flash Player 11.3 以降では、フルスクリーンインタラクティブモードがサポートされています。このモードでは、キーボードのすべてのキー（フルスクリーンインタラクティブモードを終了する Esc を除く）が完全にサポートされます。フルスク
リーンインタラクティブモードは、複数のプレーヤーが参加するゲームでチャットを行う場合や、一人称シューティング
ゲームで WASD キーボードコントロールを使用する場合などに便利です。

HTML ページに埋め込まれた SWF ファイルでフルスクリーンインタラクティブモードを有効にするには、Flash Player を埋め込む HTML コードに param タグを含め、次のように embed 属性で名前 allowFullScreenInteractive と値 true を指定する必要があります。
<object>...
<param name="allowFullScreenInteractive" value="true" /><embed ... allowFullScreenInteractive="true" /></object>

Flash オーサリングツールで、ファイル／パブリッシュ設定を選択し、パブリッシュ設定ダイアログの「HTML」タブで、「Flash のみ - フルスクリーンサポート」テンプレートを選択します。

Flash Builder および Flex で、フルスクリーンインタラクティブサポートをサポートする <object> タグと <embed> タグがHTML テンプレートに含まれていることを確認します。
Web ページ内の JavaScript を使用して SWF 埋め込みタグを生成する場合、JavaScript を変更して、
allowFullScreenInteractive param タグや属性を追加する必要があります。例えば、HTML ページで AC_FL_RunContent() 関
数（Flash Professional および Flash Builder で生成された HTML ページで使用される）を使用する場合、
allowFullScreenInteractive パラメーターを該当の関数呼び出しに対して次のように追加する必要があります。
AC_FL_RunContent(...
'allowFullScreenInteractive','true',...
); //end AC code

これは、スタンドアローンの Flash Player で実行される SWF ファイルには適用されません。
フルスクリーンのステージサイズと拡大／縮小

Stage.fullScreenHeight プロパティと Stage.fullScreenWidth プロパティは、フルスクリーンの状態にすぐ移行する場合、フルスクリーンサイズで使用されるモニターの高さと幅を返します。これらの値を取得した後、フルスクリーンモードに移行する前にユーザーがブラウザーを別のモニター上に移動する機会があると、値が無効になる可能性があります。これらの値の取得処理と Stage.displayState プロパティを StageDisplayState.FULL_SCREEN に設定する処理を同じイベントハンドラー内で実行すれば、値は正しいものとなります。複数のモニターがあるユーザー環境では、SWF コンテンツは 1 台のモニターのみを使用してフルスクリーン表示されます。Flash Player および AIR では、SWF コンテンツのもっとも多くの部分が配置されているモニターを一定の基準によって判別し、そのモニターをフルスクリーンモードで使用します。fullScreenHeight お
よび fullScreenWidth プロパティは、フルスクリーンモードで使用されるモニターのサイズのみを反映します。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の Stage.fullScreenHeight および Stage.fullScreenWidth を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

161

表示のプログラミング

フルスクリーンモードでのステージの拡大／縮小操作は、通常モードの場合と同様です。拡大／縮小は、Stage クラスのscaleMode プロパティで制御します。scaleMode プロパティを StageScaleMode.NO_SCALE に設定した場合、Stage のstageWidth プロパティと stageHeight プロパティは、SWF が占める画面領域のサイズ（この場合は画面全体）に応じて変わります。ブラウザーで表示する場合は、これに対応する HTML パラメーターによって設定が制御されます。

Stage クラスの fullScreen イベントを使用すると、フルスクリーンモードのオンとオフを検出して応答することができます。
例えばこの例のように、フルスクリーンモードに移行するとき、またはフルスクリーンモードを終了するときに、画面アイ
テムの再配置、追加、削除を行うことができます。
import flash.events.FullScreenEvent;function fullScreenRedraw(event:FullScreenEvent):void{if (event.fullScreen){// Remove input text fields.
// Add a button that closes full-screen mode.
}else{// Re-add input text fields.
// Remove the button that closes full-screen mode.
}}
mySprite.stage.addEventListener(FullScreenEvent.FULL_SCREEN, fullScreenRedraw);

このコードが示すように、fullScreen イベントのイベントオブジェクトは、flash.events.FullScreenEvent クラスのインスタンスです。このクラスには、フルスクリーンモードが有効（true）であるか無効（false）であるかを示す fullScreen プロパ
ティがあります。
フルスクリーンモードでのキーボードサポート

Flash Player をブラウザー上で実行しているとき、フルスクリーンモードでは、キーボードイベントやテキスト入力などすべてのキーボード関連 ActionScript が無効になります。ただし、例外として次のキーは有効です。

••

非表示文字を表す一部のキー：矢印キー、スペースバー、Tab キー
フルスクリーンモードを終了するキーボードショートカット：Esc キー（Windows と Mac OS）、Ctrl+W キー（Windows）、Command+W キー（Mac OS）、Alt+F4 キー

これらの制約は、スタンドアローンの Flash Player または AIR ランタイムで実行されている SWF コンテンツには適用されません。AIR では、キーボード入力を許可するインタラクティブフルスクリーンモードがサポートされています。
フルスクリーンモードでのマウスサポート
デフォルトでは、フルスクリーンモードにおいても、マウスイベントはフルスクリーンモード以外の場合と同様に機能します。しかし、必要な場合は、Stage.mouseLock プロパティを設定してフルスクリーンモードのマウスロックを有効にすることができます。マウスロックを使用すると、カーソルが無効化され、境界のないマウス動作が可能になります。
注意：マウスロックは、デスクトップアプリケーションのフルスクリーンモードにおいてのみ有効化することができます。
アプリケーションがフルスクリーンモードでない場合や、モバイルデバイス上のアプリケーションでは、設定すると例外がスローされます。
次の場合に、マウスロックは自動的に無効化され、マウスカーソルが再度表示されます。

•

ユーザーが Esc キー（すべてのプラットフォーム）、Ctrl + W キー（Windows）、Command + W キー（Mac）またはAlt + F4 キー（Windows）を使用して、フルスクリーンモードを終了した場合。

•

アプリケーションウィンドウがフォーカスを失った場合。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

162

表示のプログラミング•

プライバシーダイアログボックスなどの設定 UI が表示された場合。

•

ファイルアップロードダイアログボックスなどのネイティブのダイアログボックスが表示された場合。

mouseMove イベントなど、マウスの動きに関連するイベントでは、イベントオブジェクトは MouseEvent クラスを使用して表現されます。マウスロックが無効になっているときマウスの位置を調べるには、MouseEvent.localX および

MouseEvent.localY プロパティを使用します。マウスロックが有効になっているときマウスの位置を調べるには、MouseEvent.movementX および MouseEvent.movementY プロパティを使用します。movementX および movementY プロパ
ティの値は、マウス位置の絶対座標ではなく、前回のイベントの時点からマウス位置がどれだけ変化したかを示しています。
フルスクリーンモードでのハードウェア拡大／縮小機能

Stage クラスの fullScreenSourceRect プロパティを使用すると、ステージの特定の領域をフルスクリーンモードに拡大するよ
うに Flash Player または AIR を設定できます。Flash Player と AIR では、ユーザーのコンピューターに搭載されたグラフィックカードやビデオカードにハードウェアの拡大／縮小機能があれば、これを利用します。通常、表示の拡大／縮小はソフトウェアよりもハードウェアで実行する方が高速に処理できます。
ハードウェアの拡大／縮小機能を活用するには、ステージ全体またはステージの一部をフルスクリーンモードに設定します。
次の ActionScript 3.0 コードでは、ステージ全体をフルスクリーンモードに設定します。
import flash.geom.*;{
stage.fullScreenSourceRect = new Rectangle(0,0,320,240);
stage.displayState = StageDisplayState.FULL_SCREEN;}

このプロパティを有効な矩形に設定し、displayState プロパティをフルスクリーンモードに設定すると、指定された領域がFlash Player および AIR により拡大／縮小されます。ActionScript 内の実際のステージサイズ（ピクセル単位）は変更されません。標準の「フルスクリーンモードを終了するには、Esc キーを押します」というメッセージに対応するため、矩形のサイズに最小限度が適用されます。通常、この限度は約 260 × 30 ピクセルですが、プラットフォームおよび Flash Player のバージョンによって異なる場合があります。

fullScreenSourceRect プロパティを設定できるのは、Flash Player がフルスクリーンモードでない場合のみです。このプ
ロパティを正しく使用するには、先にこのプロパティを設定し、次に displayState プロパティをフルスクリーンモードに設定します。
拡大／縮小を有効にするには、次のように fullScreenSourceRect プロパティを矩形オブジェクトに設定します。
stage.fullScreenSourceRect = new Rectangle(0,0,320,240);

拡大／縮小を無効にするには、fullScreenSourceRect プロパティを null に設定します。
stage.fullScreenSourceRect = null;Flash Player でハードウェアの拡大／縮小機能をすべて利用するには、Flash Player の設定ダイアログボックスで機能を有効にします。このダイアログボックスをロードするには、ブラウザー上の Flash Player コンテンツ内を右クリック（Windows）または Control キーを押しながらクリック（Mac OS）します。最初のタブである「表示」タブを選択し、「ハードウェアアクセラレーション」チェックボックスをクリックします。
直接ウィンドウモードおよび GPU 合成ウィンドウモード

Flash Player 10 では、直接および GPU 合成という 2 つのウィンドウモードが導入されました。これらのウィンドウモード
は、Flash オーサリングツールのパブリッシュ設定で有効にすることができます。これらのモードは、AIR ではサポートされていません。これらのモードを利用するには、Flash Player に対してハードウェアアクセラレーションを有効にする必要があります。
直接モードでは、最も速く最も直接的なパスを使用して画面にグラフィックスを挿入します。この方法はビデオの再生に有利です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

163

表示のプログラミング

GPU 合成では、ビデオカード上のグラフィックスプロセッシングユニットを使用して合成を加速します。ビデオ合成は、複数のイメージを階層化して単一のビデオイメージを作成するプロセスです。合成が GPU によって加速される場合、YUV
変換、カラー補正、回転または拡大／縮小、ブレンドのパフォーマンスが向上します。YUV 変換は、送信に使用されるコ
ンポジットアナログシグナルから、ビデオカメラと画面で使用される RGB（赤、緑、青）カラーモデルへの色変換を表します。GPU を使用して合成を加速すると、CPU に対するメモリと計算の要求が低減します。標準定義ビデオの再生も円滑になります。
これらのウィンドウモードを実装する際には注意が必要です。GPU 合成を使用すると、メモリおよび CPU リソースのコス
トが高くなる場合があります。ブレンドモード、フィルター処理、クリッピング、マスキングなどの一部の操作を GPU で実行できない場合は、ソフトウェアで行われます。これらのモードを使用し、バナーに対してこれらのモードを有効にしない場合は、HTML ページあたり 1 つの SWF ファイルに制限することをお勧めします。Flash Test Movie 機能では、ハード
ウェアアクセラレーションは使用されませんが、「パブリッシュプレビュー」オプションから使用することができます。
最大の画面更新レートである 60 を超えるフレームレートを SWF ファイルで設定することは無意味です。50 〜 55 のフレー
ムレートを設定すると、ドロップされたフレームが考慮されます。フレームのドロップは、様々な理由で時々発生することがあります。
直接モードを使用するには、Microsoft DirectX 9 対応で 128 MB の VRAM を搭載したハードウェア（Windows）か、OpenGL for Macintosh または Mac OS X v10.2 以上（Mac OS）が必要です。Windows で GPU 合成を使用するには、
Microsoft DirectX 9 および Pixel Shader 2.0 対応で 128 MB の VRAM を搭載したハードウェアが必要です。Mac OS および Linux で GPU 合成を使用するには、OpenGL 1.5 およびいくつかの OpenGL 拡張（フレームバッファーオブジェクト、
マルチテクスチャ、シェーダーオブジェクト、シェーディング言語、フラグメントシェーダー）が必要です。

direct および gpu アクセラレーションモードは、Flash のパブリッシュ設定ダイアログボックスで、「Flash」タブのハード
ウェアアクセラレーションメニューを使用して SWF ごとにアクティブにすることができます。「なし」を選択した場合、ウィンドウモードは、「HTML」タブの「ウィンドウモード」設定での指定に応じて default、transparent または opaque に戻ります。

表示オブジェクトのイベント処理
Flash Player 9 以降、Adobe AIR 1.0 以降
DisplayObject クラスは EventDispatcher クラスを継承します。これは、どの表示オブジェクトでもイベントモデルに完全に参加できることを意味します（119 ページの「イベント処理」を参照してください）。各表示オブジェクトは、EventDispatcher クラスから継承した独自の addEventListener() メソッドを使用して、特定のイベントを監視することができます。ただし、これは、監視しているオブジェクトがそのイベントのイベントフローの一部である場合に限ります。

Flash Player または AIR によってイベントオブジェクトが送出されると、そのイベントオブジェクトはステージからイベントが発生した表示オブジェクトへと往復します。例えば、ユーザーが child1 という名前の表示オブジェクトをクリックすると、Flash Player により、ステージから表示リスト階層を下がって child1 表示オブジェクトまでイベントオブジェクトが送出されます。
次の図に示されているように、概念上イベントフローは 3 段階に分けられます。
Stage
キャプチャ
段階

バブリング
段階

Parent NodeChild1 NodeChild2 Node

ターゲット段階

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

164

表示のプログラミング

詳しくは、119 ページの「イベント処理」を参照してください。
表示オブジェクトのイベント操作で注意すべき点は、表示オブジェクトを表示リストから削除するとき、（ガベージコレク
ションにより）表示オブジェクトが自動的にメモリから削除されたかどうかによってイベントリスナーの効果が異なることです。イベントのリスナーとしてサブスクライブされたオブジェクトを含む表示オブジェクトの場合、この表示オブジェク
トには該当のリスナーオブジェクトへの参照が設定されているため、表示リストからの削除時にも削除されません。詳しくは、132 ページの「イベントリスナーの管理」を参照してください。

DisplayObject サブクラスの選択
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトを操作する場合に重要なのは、複数のオプションを選択する場合に、どの表示オブジェクトをどの目的で使用するかを決定することです。これを決定する場合のガイドラインを次に示します。これらのガイドラインは、クラスのインスタンスが必要か、あるいは作成するクラスの基本クラスを選択するかを判断する場合にも適用できます。

•

他の表示オブジェクトのコンテナとなるオブジェクトを必要としない場合（すなわち、スタンドアローンの画面エレメン
トとなるオブジェクトのみを必要とする場合）、次の DisplayObject サブクラスまたは InteractiveObject サブクラスのいずれかを使用目的に合わせて選択します。

•

ビットマップイメージを表示するための Bitmap。

•

テキストを追加するための TextField。

•

ビデオを表示するための Video。

•

画面上のコンテンツを描画するための「キャンバス」用の Shape。具体的には、画面上でシェイプを描画するためのインスタンスを作成する必要があり、このオブジェクトが他の表示オブジェクト用のコンテナとはならない場合、Sprite や MovieClip ではなく Shape を使用することで、パフォーマンスが大幅に改善します。

• Flash オーサリングツールによって作成されるアイテムの MorphShape、StaticText、または SimpleButton（これらのクラスのインスタンスをプログラムによって作成することはできません。ただし、これらのデータ型を持つ変数を作成し、Flash オーサリングツールで作成されたアイテムを参照することはできます）。

•

メインの Stage を参照する変数が必要な場合、そのデータ型として Stage クラスを使用します。

•

外部 SWF ファイルやイメージファイルをロードするためのコンテナが必要な場合、Loader インスタンスを使用します。
ロードされたコンテンツは、Loader インスタンスの子として表示リストに追加されます。そのデータ型は、ロードされたコンテンツの特性によって次のように異なります。

•

ロードされたイメージは Bitmap インスタンスになります。

• ActionScript 3.0 で記述された SWF ファイルをロードした場合、Sprite または MovieClip インスタンス（または、コンテンツ作成者の指定により、これらのクラスのサブクラスのインスタンス）になります。

• ActionScript 1.0 または ActionScript 2.0 で記述された SWF ファイルをロードした場合、AVM1Movie インスタンスになります。

•

他の表示オブジェクトのコンテナとなるオブジェクトが必要な場合（ActionScript を使用して表示オブジェクトに描画するかどうかにかかわらず）、次のいずれかの DisplayObjectContainer サブクラスを選択します。

• ActionScript のみを使用してオブジェクトを作成する場合、または ActionScript のみによって作成および操作されるカスタム表示オブジェクトの基本クラスとしては、Sprite を選択します。
• Flash オーサリングツールで作成されたムービークリップシンボルを参照するための変数を作成する場合、MovieClip を選択します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

165

表示のプログラミング• Flash ライブラリ内のムービークリップシンボルと関連付けられるクラスを作成する場合は、クラスの基本クラスとして、次のいずれかの DisplayObjectContainer サブクラスを選択します。
•

関連付けられたムービークリップシンボルのコンテンツが複数のフレーム上に存在する場合、MovieClip を選択します。

•

関連付けられたムービークリップシンボルのコンテンツが最初のフレームのみに存在する場合、Sprite を選択します。

表示オブジェクトの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
どの表示オブジェクトを使用するかに関わらず、画面上に表示されるエレメントとして、すべての表示オブジェクトに対して共通に適用される操作が多数あります。例えば、これらの操作はすべて画面上に配置でき、表示オブジェクトの積み重ね
順序を前後に移動できます。また、拡大／縮小、回転などの操作も可能です。すべての表示オブジェクトは、共通の基本クラス（DisplayObject）からこの関数を継承しているため、TextField インスタンス、Video インスタンス、Shape インス
タンス、その他のどの表示オブジェクトを操作するかにかかわらず、この関数は同様に機能します。次のセクションでは、
こうした共通の表示オブジェクト操作について詳しく説明します。

位置の変更
Flash Player 9 以降、Adobe AIR 1.0 以降
あらゆる表示オブジェクトに対する最も基本的な操作は、画面上への配置です。表示オブジェクトの位置を設定するには、
オブジェクトの x プロパティと y プロパティを変更します。
myShape.x = 17;
myShape.y = 212;

表示オブジェクトの配置システムでは、Stage を直交座標系（水平方向の x 軸と垂直方向の y 軸を使用する一般的なグリッド方式）として処理します。座標系の原点（x 軸と y 軸が交わる 0,0 座標）は、ステージの左上隅になります。この位置から右方向が x 値の正方向、左方向が負方向になります。一方、( 一般的なグラフとは異なり ) 下方向が y 値の正方向、上方向が負方向になります。例えば上記のコード行の場合、オブジェクト myShape は、x 座標 17（原点から右方向へ 17 ピクセル）、

y 座標 212（原点から下方向へ 212 ピクセル）に移動します。
デフォルトでは、ActionScript を使用して表示オブジェクトを作成する場合、x プロパティと y プロパティはいずれも 0 に設定され、表示オブジェクトは親コンテンツの左上隅に配置されます。

ステージを基準とした位置の変更
x プロパティと y プロパティは、親表示オブジェクト軸の 0,0 座標を基準とした表示オブジェクトの位置を常に参照することに注意してください。このため、Sprite インスタンス内の Shape インスタンス（円など）の場合、Shape オブジェクトの x
プロパティと y プロパティを 0 に設定すると、円は Sprite の左上隅に配置されます。これは、必ずしもステージの左上隅とは限りません。グローバルステージ座標を基準としてオブジェクトを配置するには、任意の表示オブジェクトの
globalToLocal() メソッドを使用して、次のようにグローバル（ステージ）座標からローカル（表示オブジェクトコンテナ）
座標に変換します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

166

表示のプログラミング// Position the shape at the top-left corner of the Stage,// regardless of where its parent is located.
// Create a Sprite, positioned at x:200 and y:200.
var mySprite:Sprite = new Sprite();mySprite.x = 200;
mySprite.y = 200;
this.addChild(mySprite);// Draw a dot at the Sprite's 0,0 coordinate, for reference.
mySprite.graphics.lineStyle(1, 0x000000);
mySprite.graphics.beginFill(0x000000);
mySprite.graphics.moveTo(0, 0);
mySprite.graphics.lineTo(1, 0);
mySprite.graphics.lineTo(1, 1);
mySprite.graphics.lineTo(0, 1);
mySprite.graphics.endFill();// Create the circle Shape instance.
var circle:Shape = new Shape();
mySprite.addChild(circle);// Draw a circle with radius 50 and center point at x:50, y:50 in the Shape.
circle.graphics.lineStyle(1, 0x000000);circle.graphics.beginFill(0xff0000);circle.graphics.drawCircle(50, 50, 50);
circle.graphics.endFill();// Move the Shape so its top-left corner is at the Stage's 0, 0 coordinate.
var stagePoint:Point = new Point(0, 0);
var targetPoint:Point = mySprite.globalToLocal(stagePoint);
circle.x = targetPoint.x;
circle.y = targetPoint.y;

同様に、DisplayObject クラスの localToGlobal() メソッドを使用して、ローカル座標をステージ座標に変換できます。

マウスを使用した表示オブジェクトの移動
ActionScript では、マウスを使用して表示オブジェクトを移動する方法は 2 つあります。いずれの方法でも、2 つのマウス
イベントを使用します。つまり、マウスボタンを押したときはマウスカーソルに従って移動し、マウスボタンを離したときはマウスカーソルに従って停止するようにオブジェクトに指示を出します。
注意：Flash Player 11.3 以降および AIR 3.3 以降：MouseEvent.RELEASE_OUTSIDE イベントを使用して、Sprite を含む境界の外でユーザーがマウスボタンを離した場合に対応することもできます。
最初の方法では startDrag() メソッドを使用します。これは簡単な方法ですが、制約が多くなります。マウスボタンを押すと、ドラッグされる表示オブジェクトの startDrag() メソッドが呼び出されます。マウスボタンを離すと、stopDrag() メソッ
ドが呼び出されます。Sprite クラスがこれらの 2 つの機能を定義するので、移動対象のオブジェクトは Sprite クラスまたはそのサブクラスである必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

167

表示のプログラミング// This code creates a mouse drag interaction using the startDrag()// technique.
// square is a MovieClip or Sprite instance).
import flash.events.MouseEvent;// This function is called when the mouse button is pressed.
function startDragging(event:MouseEvent):void{square.startDrag();}// This function is called when the mouse button is released.
function stopDragging(event:MouseEvent):void{square.stopDrag();}square.addEventListener(MouseEvent.MOUSE_DOWN, startDragging);square.addEventListener(MouseEvent.MOUSE_UP, stopDragging);

この方法の場合、startDrag() を使用してドラッグできるのは一度に 1 つのアイテムだけという重大な制約があります。ある
表示オブジェクトがドラッグされているときに startDrag() メソッドが別の表示オブジェクトに対して呼び出された場合、最初の表示オブジェクトはマウスに従って直ちに停止します。例えば、startDragging() 関数を次のように変更した場合、
square.startDrag() メソッド呼び出しにもかかわらず、circle オブジェクトだけがドラッグされます。
function startDragging(event:MouseEvent):void{square.startDrag();
circle.startDrag();}

startDrag() を使用してドラッグできるのは、一度に 1 つのオブジェクトのみです。そのため、表示オブジェクトに対してstopDrag() メソッドが呼び出されると、現在ドラッグ中のオブジェクトがどんなオブジェクトであってもそのオブジェクト
は停止します。
複数の表示オブジェクトをドラッグする必要がある場合、または複数のオブジェクトが startDrag() を使用することで生じる
可能性のある競合を回避する必要がある場合は、マウス追従方式を使用してドラッグ効果を作成するのが最適です。この方式を使用すると、マウスボタンが押されたときに、ステージの mouseMove イベントに対するリスナーとして関数がサブス
クライブされます。マウスを移動するたびに呼び出されるこの関数により、ドラッグされるオブジェクトは、マウスの x, y
座標にジャンプします。マウスボタンを離すと、関数はリスナーとしてのサブスクライブを解除されます。この場合、マウスを移動しても関数が呼び出されなくなるため、オブジェクトはマウスカーソルに従って停止します。この方式を説明する
コードを次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

168

表示のプログラミング// This code moves display objects using the mouse-following// technique.
// circle is a DisplayObject (e.g. a MovieClip or Sprite instance).
import flash.events.MouseEvent;var offsetX:Number;var offsetY:Number;// This function is called when the mouse button is pressed.
function startDragging(event:MouseEvent):void{// Record the difference (offset) between where// the cursor was when the mouse button was pressed and the x, y// coordinate of the circle when the mouse button was pressed.
offsetX = event.stageX - circle.x;
offsetY = event.stageY - circle.y;// tell Flash Player to start listening for the mouseMove event
stage.addEventListener(MouseEvent.MOUSE_MOVE, dragCircle);}// This function is called when the mouse button is released.
function stopDragging(event:MouseEvent):void{// Tell Flash Player to stop listening for the mouseMove event.
stage.removeEventListener(MouseEvent.MOUSE_MOVE, dragCircle);}// This function is called every time the mouse moves,// as long as the mouse button is pressed down.
function dragCircle(event:MouseEvent):void{// Move the circle to the location of the cursor, maintaining// the offset between the cursor's location and the// location of the dragged object.
circle.x = event.stageX - offsetX;
circle.y = event.stageY - offsetY;// Instruct Flash Player to refresh the screen after this event.
event.updateAfterEvent();}
circle.addEventListener(MouseEvent.MOUSE_DOWN, startDragging);
circle.addEventListener(MouseEvent.MOUSE_UP, stopDragging);

表示オブジェクトをマウスカーソルに追従させるだけではなく、ドラッグするオブジェクトを画面の手前に移動することにより、他のすべてのオブジェクトよりも上に浮かせて表示させることもよくあります。例えば、円と四角形の 2 つのオブジェクトがあり、その両方をマウスで移動するとします。表示リスト上で円が四角形の下にある場合、カーソルが四角形の上に来るように円をクリック & ドラッグすると、円は四角形の後ろにスライドして表示され、ドラッグ & ドロップ効果がなくなります。これとは別に、円をクリックすると、円が表示リストの一番上に移動し、常に他のすべてのコンテンツの一番上に表示される方法があります。
次のコード（前の例を応用）では、円と四角形の 2 つの表示オブジェクトをマウスで移動します。いずれかのアイテム上でマウスボタンを押すたびに、そのアイテムはステージの表示リストの最上部に移動します。その結果、ドラッグされるアイ
テムは常に一番上に表示されます。（新しいコードと前の例から変更されたコードは、ボールド体で記述されています）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

169

表示のプログラミング// This code creates a drag-and-drop interaction using the mouse-following// technique.
// circle and square are DisplayObjects (e.g. MovieClip or Sprite// instances).
import flash.display.DisplayObject;import flash.events.MouseEvent;var offsetX:Number;var offsetY:Number;var draggedObject:DisplayObject;// This function is called when the mouse button is pressed.
function startDragging(event:MouseEvent):void{// remember which object is being dragged
draggedObject = DisplayObject(event.target);// Record the difference (offset) between where the cursor was when// the mouse button was pressed and the x, y coordinate of the// dragged object when the mouse button was pressed.
offsetX = event.stageX - draggedObject.x;
offsetY = event.stageY - draggedObject.y;// move the selected object to the top of the display liststage.addChild(draggedObject);// Tell Flash Player to start listening for the mouseMove event.
stage.addEventListener(MouseEvent.MOUSE_MOVE, dragObject);}// This function is called when the mouse button is released.
function stopDragging(event:MouseEvent):void{// Tell Flash Player to stop listening for the mouseMove event.
stage.removeEventListener(MouseEvent.MOUSE_MOVE, dragObject);}// This function is called every time the mouse moves,// as long as the mouse button is pressed down.
function dragObject(event:MouseEvent):void{// Move the dragged object to the location of the cursor, maintaining// the offset between the cursor's location and the location// of the dragged object.
draggedObject.x = event.stageX - offsetX;
draggedObject.y = event.stageY - offsetY;// Instruct Flash Player to refresh the screen after this event.
event.updateAfterEvent();}
circle.addEventListener(MouseEvent.MOUSE_DOWN, startDragging);
circle.addEventListener(MouseEvent.MOUSE_UP, stopDragging);square.addEventListener(MouseEvent.MOUSE_DOWN, startDragging);square.addEventListener(MouseEvent.MOUSE_UP, stopDragging);

トークンやカードをパイル間で移動するゲームなどでこの効果をさらに拡張するには、ドラッグされるオブジェクトを「拾う」ときにステージの表示リストに追加し、次にマウスボタンを離すときに別の表示リスト（オブジェクトがドロップされる「パイル」など）に追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

170

表示のプログラミング

最後に、効果を強調するために、表示オブジェクトをクリックしたとき（ドラッグを開始したとき）にドロップシャドウ
フィルターを適用し、オブジェクトを解放したときにドロップシャドウを削除します。ActionScript でのドロップシャドウ
フィルターや、その他の表示オブジェクトフィルターを使用する場合について詳しくは、254 ページの「表示オブジェクトのフィルター処理」を参照してください。

表示オブジェクトのパンとスクロール
Flash Player 9 以降、Adobe AIR 1.0 以降表示させたい領域に対して大きすぎる表示オブジェクトがある場合、scrollRect プロパティを使用して、表示オブジェクトの可視領域を定義できます。また、ユーザー入力に応じて scrollRect プロパティを変更することで、コンテンツの左右のパンや上下のスクロールが可能になります。

scrollRect プロパティは、Rectangle クラスのインスタンスです。Rectangle クラスは、矩形領域を単一のオブジェクトとして定義する場合に必要な値を結合するクラスです。最初に表示オブジェクトの可視領域を定義するには、新しい Rectangle
インスタンスを作成し、これを表示オブジェクトの scrollRect プロパティに割り当てます。その後でスクロールまたはパン
するには、scrollRect プロパティを個別の Rectangle 変数に読み込み、目的のプロパティを変更します（例えば、パンするには Rectangle インスタンスの x プロパティを、スクロールするには y プロパティを変更します）。次に、この Rectangle イン
スタンスを scrollRect プロパティに再度割り当て、変更された値を表示オブジェクトに通知します。
例えば、次に示すコードでは、SWF ファイルの境界内には収まらない高さが設定された bigText という名前の TextField オ
ブジェクトに対する可視領域を定義します。up と down という 2 つのボタンがクリックされると、TextField オブジェクトのコンテンツを上下にスクロールさせる関数が呼び出されます。この関数は、scrollRect Rectangle インスタンスの y プロパ
ティを変更することによってスクロールを行います。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

171

表示のプログラミング

import flash.events.MouseEvent;import flash.geom.Rectangle;// Define the initial viewable area of the TextField instance:// left: 0, top: 0, width: TextField's width, height: 350 pixels.
bigText.scrollRect = new Rectangle(0, 0, bigText.width, 350);// Cache the TextField as a bitmap to improve performance.
bigText.cacheAsBitmap = true;// called when the "up" button is clicked
function scrollUp(event:MouseEvent):void{// Get access to the current scroll rectangle.
var rect:Rectangle = bigText.scrollRect;// Decrease the y value of the rectangle by 20, effectively// shifting the rectangle down by 20 pixels.
rect.y -= 20;// Reassign the rectangle to the TextField to "apply" the change.
bigText.scrollRect = rect;}// called when the "down" button is clicked
function scrollDown(event:MouseEvent):void{// Get access to the current scroll rectangle.
var rect:Rectangle = bigText.scrollRect;// Increase the y value of the rectangle by 20, effectively// shifting the rectangle up by 20 pixels.
rect.y += 20;// Reassign the rectangle to the TextField to "apply" the change.
bigText.scrollRect = rect;}
up.addEventListener(MouseEvent.CLICK, scrollUp);
down.addEventListener(MouseEvent.CLICK, scrollDown);

上記の例に示すように、表示オブジェクトの scrollRect プロパティを操作する場合、cacheAsBitmap プロパティを使用して、Flash Player または AIR が表示オブジェクトのコンテンツをビットマップとしてキャッシュするように指定するのが最適な方法です。こうすると、Flash Player および AIR は、表示オブジェクトがスクロールされるたびに、そのコンテンツ全体を再描画する必要がなくなります。代わりに、キャッシュされたビットマップを使用して、必要な部分だけを画面に直接レンダリングできます。詳しくは、174 ページの「表示オブジェクトのキャッシュ」を参照してください。

サイズの変更とオブジェクトの拡大／縮小
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトのサイズを測定および操作する方法は 2 つあります。サイズのプロパティ（width および height）または拡大／縮小のプロパティ（scaleX および scaleY）のいずれかを使用します。
各表示オブジェクトには、width プロパティと height プロパティがあり、これらの値はオブジェクトのサイズに初期設定されています（ピクセル単位）。これらのプロパティの値を読み取って、表示オブジェクトのサイズを測定できます。また、次のように新しい値を指定して、オブジェクトのサイズを変更することもできます。
// Resize a display object.
square.width = 420;
square.height = 420;// Determine the radius of a circle display object.
var radius:Number = circle.width / 2;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

172

表示のプログラミング

表示オブジェクトの height または width を変更すると、オブジェクトが拡大または縮小されます。つまり、オブジェクトのコンテンツが新しい領域に合わせて拡張または縮小することになります。ベクターシェイプのみを含む表示オブジェクトの場合、これらのシェイプは新しいスケールで再描画されます。その際、画質が低下することはありません。表示オブジェク
ト内のすべてのビットマップグラフィックエレメントは、再描画されるのではなく、拡大／縮小されます。このため、イメージの実際のピクセル情報よりも大きな幅と高さが設定されたデジタル写真などの場合、ピクセル化されて粗く表示されます。
表示オブジェクトの width または height プロパティを変更すると、オブジェクトの scaleX プロパティと scaleY プロパティもFlash Player および AIR によって更新されます。
注意： TextField オブジェクトはこの拡大／縮小動作での例外です。テキストフィールドでは、テキストの折り返しとフォントサイズに合わせてテキストフィールド自体のサイズが変化する必要があります。そのため、サイズ変更後に scaleX 値または scaleY 値が 1 に戻ります。ただし、TextField オブジェクトの scaleX 値または scaleY 値を手動で調整した場合は、指定した拡大／縮小値に合わせて幅と高さの値が変化します。
これらのプロパティは、表示オブジェクトのサイズを、その元のサイズと比較して相対的に表します。scaleX プロパティとscaleY プロパティは、小数（十進分数）値を使用してパーセンテージを表します。例えば、表示オブジェクトの width を変
更して、その幅を元のサイズの半分にした場合、このオブジェクトの scaleX プロパティの値は 50% を表す .5 となります。このオブジェクトの高さを 2 倍にした場合、その scaleY プロパティの値は、200% を表す 2 となります。
// circle is a display object whose width and height are 150 pixels.
// At original size, scaleX and scaleY are 1 (100%).
trace(circle.scaleX); // output: 1
trace(circle.scaleY); // output: 1// When you change the width and height properties,// Flash Player changes the scaleX and scaleY properties accordingly.
circle.width = 100;circle.height = 75;
trace(circle.scaleX); // output: 0.6622516556291391
trace(circle.scaleY); // output: 0.4966887417218543

サイズの変更は相対的ではありません。つまり、四角形の height は変更するが width は変更しない場合、その比率は同じではなくなるため、オブジェクトは四角形ではなく矩形になります。表示オブジェクトのサイズを相対的に変更したい場合、

width プロパティまたは height プロパティを設定する代わりに、scaleX プロパティと scaleY プロパティの値を設定することによって、表示オブジェクトのサイズを変更できます。例えば次のコードは、square という名前の表示オブジェクトのwidth を変更し、次に垂直スケール（scaleY）を変更して水平スケールに一致させることで、このオブジェクトの相対的なサイズを保ちます。
// Change the width directly.
square.width = 150;// Change the vertical scale to match the horizontal scale,// to keep the size proportional.
square.scaleY = square.scaleX;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

173

表示のプログラミング

拡大／縮小時の歪みの制御
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトを拡大／縮小する場合（水平方向に伸縮する場合など）、結果として生じる歪みはオブジェクト全体で均等に拡散されるため、すべての部分が同じだけ伸縮するのが通常です。グラフィックエレメントやデザインエレメントの場合、これが問題になることはあまりありません。しかし場合によっては、表示オブジェクトの一部を伸縮し、一部を変更しない
ように制御したいことがあります。角の丸い矩形のボタンが、この場合の典型的な例です。通常の拡大／縮小操作の場合、ボタンのサイズを変更すると、ボタンの隅が伸縮し、角丸の半径が変化します。

しかしこの場合は、拡大／縮小を制御できれば（つまり、拡大／縮小する領域（直線の辺と中央部分）としない領域（角）を指定できれば）、表示したときの歪みが生じないため、その方が望ましいことになります。

9 スライスの拡大／縮小（スケール 9）を使用すると、表示オブジェクトを作成してそのオブジェクトの拡大／縮小方法を制御できます。9 スライスの拡大／縮小を使用すると、表示オブジェクトが 9 つの個別の矩形（三目並べの升目のような 3 ×

3 のグリッド）に分割されます。矩形は必ずしも同じサイズであるとは限りません。グリッド線をどこに配置するかは、ユーザーが指定します。表示オブジェクトを拡大／縮小しても、4 つの角にあたる矩形（ボタンの丸い角の部分など）内のコンテ
ンツのサイズは変更されません。上端中央部と下端中央部の矩形は水平方向に拡大／縮小しますが、垂直方向には拡大／縮小しません。一方、左端中央部と右端中央部の矩形は垂直方向に拡大／縮小しますが、水平方向には拡大／縮小しません。
中央部の矩形は、垂直方向と水平方向の両方に拡大／縮小します。

表示オブジェクトを作成し、そのオブジェクトの特定のコンテンツを拡大／縮小したくない場合は、そのコンテンツが矩形の 4 つの角のいずれかに配置されるように、9 スライスの拡大／縮小のグリッド境界線を設定する必要があります。

ActionScript の場合、表示オブジェクトの scale9Grid プロパティの値を設定すると、そのオブジェクトに対する 9 スライスの拡大／縮小がオンになり、オブジェクトのスケール 9 グリッドにおける矩形のサイズが定義されます。scale9Grid プロパ
ティの値として、Rectangle クラスのインスタンスを次のように使用します。
myButton.scale9Grid = new Rectangle(32, 27, 71, 64);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

174

表示のプログラミング

Rectangle コンストラクターの 4 つのパラメーターは、x 座標、y 座標、幅、高さです。この例の矩形の左上隅は、myButtonという表示オブジェクト上の x: 32、y: 27 に配置されます。この矩形の幅は 71 ピクセル、高さは 64 ピクセルです（従って、その右端は表示オブジェクト上の x 座標 103、下端は表示オブジェクト上の y 座標 92 になります）。

Rectangle インスタンスによって定義される領域に含まれる実際の領域は、スケール 9 グリッドの中央部の矩形を表します。
次に示すように、他の部分の矩形は Rectangle インスタンスの各辺を拡張することにより、Flash Player および AIR で算出されます。

この例では、ボタンを拡大／縮小しても角丸の部分は変化しませんが、他の領域は拡大／縮小に合わせて調整されます。

A

B

C

A. myButton.width = 131;myButton.height = 106; B. myButton.width = 73;myButton.height = 69; C. myButton.width = 54;myButton.height= 141;

表示オブジェクトのキャッシュFlash Player 9 以降、Adobe AIR 1.0 以降
Flash 内のデザインのサイズが大きくなると、アプリケーションの作成や、複雑なスクリプトで記述されたアニメーションの作成を行っている場合、パフォーマンスと最適化について考慮する必要があります。静的な状態のままのコンテンツ（矩形の Shape インスタンスなど）がある場合、Flash Player および AIR によるコンテンツの最適化は行われません。したがって、矩形の位置を変更すると、Flash Player および AIR によって Shape インスタンス全体が再度描画されます。
指定した表示オブジェクトをキャッシュすることにより、SWF ファイルのパフォーマンスを向上させることができます。表示オブジェクトはサーフェスであり、基本的にはインスタンスのベクターデータのビットマップバージョンです。このデー
タは、SWF ファイルの処理で大きく変更されることはありません。したがって、キャッシュがオンになっているインスタ
ンスでは、SWF ファイルの再生中に連続的に再描画されることがないので、SWF ファイルのレンダリングが高速になります。
注意：サーフェスが再作成されるときに、ベクターデータを更新できます。このため、サーフェス内にキャッシュされたベ
クターデータは、SWF ファイル全体で同じである必要はありません。
表示オブジェクトの cacheAsBitmap プロパティを true に設定すると、表示オブジェクト自体のビットマップ表現がキャッ
シュされます。Flash Player および AIR は、インスタンスのサーフェスオブジェクトを作成します。これは、ベクターデー
タではなくキャッシュされたビットマップです。表示オブジェクトの境界を変更すると、サーフェスはサイズ変更されるのではなく、再作成されます。サーフェスは、他のサーフェス内にネストできます。子サーフェスは、親サーフェス上にビットマップをコピーします。詳しくは、176 ページの「ビットマップキャッシュの有効化」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

175

表示のプログラミング

DisplayObject クラスの opaqueBackground プロパティと scrollRect プロパティは、cacheAsBitmap プロパティを使用してビットマップキャッシュに関連付けられています。この 3 つのプロパティは互いに独立していますが、opaqueBackground プ
ロパティと scrollRect プロパティは、オブジェクトがビットマップとしてキャッシュされるときに最適に動作します。また、

opaqueBackground プロパティと scrollRect プロパティによってパフォーマンスが向上するのは、cacheAsBitmap が true に設定されている場合のみです。表示オブジェクトのコンテンツのスクロールについて詳しくは、170 ページの「表示オブジェ
クトのパンとスクロール」を参照してください。不透明な背景の設定について詳しくは、177 ページの「不透明な背景色の設定」を参照してください。
cacheAsBitmap プロパティを true に設定する必要があるアルファチャンネルマスクについて詳しくは、181 ページの「表示オブジェクトのマスク」を参照してください。

キャッシュを有効にするシナリオ
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトのキャッシュを有効にすると、サーフェスが作成されます。これには、複雑なベクターアニメーションのレンダリングが速くなるなどいくつかの利点があります。キャッシュを有効にしたいシナリオとして、いくつかの場合が考えられます。常にキャッシュを有効にして SWF ファイルのパフォーマンスを向上させたい場合が考えられます。しかし、キャッシュを有効にしてもパフォーマンスが向上しない場合や、パフォーマンスが低下する場合もあります。このセクショ
ンでは、キャッシュを使用する必要があるシナリオと、通常の表示オブジェクトを使用する必要があるシナリオについて説明します。
キャッシュされたデータの全体的なパフォーマンスは、インスタンスのベクターデータの複雑さ、変更するデータの量、および opaqueBackground プロパティを設定するかどうかによって異なります。小さな領域を変更する場合、サーフェスを使用したときとベクターデータを使用したときの違いは、ごくわずかです。アプリケーションをデプロイする前に、両方のシナリオをテストする必要があります。
ビットマップキャッシュを使用するシナリオ
ビットマップキャッシュを有効にすることで大きな利点が得られる代表的なシナリオを次に示します。

•

複雑な背景イメージ：ベクターデータの詳細で複雑な背景イメージ（「ビットマップのトレース」コマンドを適用したイメージや Adobe Illustrator® で作成したアートワークなど）を含むアプリケーション。背景で文字をアニメーション化することがあります。この場合、背景で連続的にベクターデータを再生成する必要があるため、アニメーションが遅くなります。パフォーマンスを改善するには、背景の表示オブジェクトの opaqueBackground プロパティを true に設定します。
これにより、背景はビットマップとしてレンダリングされるため素早く再描画でき、アニメーションの再生がより高速に
なります。

•

テキストフィールドのスクロール : スクロールテキストフィールドに大量のテキストを表示するアプリケーション。スク
ロール境界（scrollRect プロパティ）によってスクロール可能に設定された表示オブジェクト内に、テキストフィールドを配置できます。これにより、指定したインスタンスの高速なピクセルスクロールが可能になります。ユーザーが表示オ
ブジェクトインスタンスをスクロールすると、Flash Player または AIR はスクロールされたピクセルを上方向に移動し、テキストフィールド全体を再生成するのではなく、新しく表示された領域だけを生成します。

•

ウィンドウシステム : 重なり合うウィンドウを持つ複雑なアプリケーション。各ウィンドウは、開いて閉じることができます（Web ブラウザーウィンドウなど）。各ウィンドウをサーフェスとしてマークした場合（cacheAsBitmap プロパティ
を true に設定することによりマーク）、各ウィンドウは分離されてキャッシュされます。ユーザーはウィンドウをドラッグできるため、互いに重ね合わせることが可能となり、各ウィンドウではベクターコンテンツの再生成は必要ありません。

•

アルファチャンネルマスク：アルファチャンネルマスクを使用する場合は、cacheAsBitmap プロパティを true に設定する必要があります。詳しくは、181 ページの「表示オブジェクトのマスク」を参照してください。

これらのシナリオでビットマップキャッシュを有効にすると、ベクターグラフィックの最適化により、アプリケーションの応答性とインタラクティブ性が向上します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

176

表示のプログラミング

また、表示オブジェクトに対してフィルターを適用するたびに、cacheAsBitmap が（明示的に false に設定されている場合でも）Flash Player によって自動的に true に設定されます。表示オブジェクトのすべてのフィルターをクリアすると、

cacheAsBitmap は最後に設定した値に戻ります。
ビットマップキャッシュの使用を避けるべきシナリオ
この機能を使用する状況を誤ると、SWF ファイルのパフォーマンスに悪影響を及ぼす可能性があります。ビットマップ
キャッシュを使用する場合は、次のガイドラインを覚えておく必要があります。

•

サーフェス（キャッシュを有効にした表示オブジェクト）を多用しないでください。各サーフェスは、通常の表示オブジェクトより多くのメモリを使用します。サーフェスを有効にするのは、レンダリングのパフォーマンスを改善する必要がある場合のみにしてください。
キャッシュされたビットマップは、通常の表示オブジェクトに比べてはるかに多くのメモリを使用します。例えば、ステージ上の Sprite インスタンスのサイズが 250 ピクセル × 250 ピクセルの場合、通常の（キャッシュされていない）

Sprite インスタンスでは 1 KB のメモリ使用量が、キャッシュされると 250 KB になることがあります。

•

キャッシュされたサーフェスのズームインは避けてください。ビットマップキャッシュを多用しすぎると、大量のメモリが消費されますが（前の項目を参照）、特にコンテンツをズームインした場合にメモリ使用量が大きくなります。

•

大部分が静的な（アニメーション化されていない）表示オブジェクトインスタンスに対しては、サーフェスを使用してください。インスタンスのドラッグや移動はできますが、インスタンスのコンテンツのアニメーション化や大幅な変更は避ける必要があります ( アニメーションや Video インスタンスを含む MovieClip インスタンスの場合、アニメーション化
やコンテンツの変更が行われる可能性が高くなります )。例えば、インスタンスの回転や変換を行うと、インスタンスはサーフェスからベクターデータ（またはその逆）へ変更されます。この処理は複雑なため、SWF ファイルに悪影響を与えます。

•

サーフェスとベクターデータを組み合わせると、Flash Player および AIR の処理量（そして場合によっては CPU の処理量も）が増加します。例えばウィンドウアプリケーションを作成するときなど、サーフェスをできる限りグループ化す
るようにしてください。

•

グラフィックが頻繁に変化するオブジェクトはキャッシュしないでください。表示オブジェクトの拡大／縮小、傾斜、回転、アルファの変更やカラーの変換の適用、子表示オブジェクトの移動、またはグラフィックプロパティを使用した描画を実行するたびに、ビットマップキャッシュが再描画されます。この処理がすべてのフレームで発生した場合、ランタイ
ムでは、オブジェクトをビットマップに描画してからそのビットマップをステージ上にコピーする処理が必要となります。つまり、キャッシュされていないオブジェクトを単にステージに描画する場合と比較して、多くの処理が発生します。キャッシュと頻繁な更新とのパフォーマンスのトレードオフは、表示オブジェクトの複雑さとサイズによって変わる
ため、個別のコンテンツをテストする以外に判断する方法はありません。

ビットマップキャッシュの有効化
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトのビットマップキャッシュを有効にするには、cacheAsBitmap プロパティを true に設定します。
mySprite.cacheAsBitmap = true;

cacheAsBitmap プロパティを true に設定すると、表示オブジェクトのピクセルが全体の座標に自動的に吸着します。SWF
ファイルをテストすると、複雑なベクターイメージで実行されるアニメーションのレンダリングが大幅に速くなっていることがわかります。
cacheAsBitmap を true に設定しても、次のうち 1 つまたは複数の条件に当てはまる場合、サーフェス（キャッシュされた
ビットマップ）は作成されません。

•

ビットマップの高さと幅のいずれかが 2880 ピクセルを超えている場合。

•

ビットマップが割り当てに失敗した場合（メモリ不足エラー）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

177

表示のプログラミング

キャッシュされたビットマップの変換マトリックス

Adobe AIR 2.0 以降（モバイルプロファイル）
モバイルデバイス用の AIR アプリケーションでは、cacheAsBitmap プロパティを設定する場合には必ずcacheAsBitmapMatrix プロパティを設定してください。このプロパティを設定すると、再レンダリングを実行せずに表示オ
ブジェクトに広範囲の変形を適用できます。
mySprite.cacheAsBitmap = true;
mySprite.cacheAsBitmapMatrix = new Matrix();

このマトリックスプロパティを設定すると、オブジェクトを再キャッシュせずに、表示オブジェクトに次のような追加の変形を適用できます。

•

ピクセルへの吸着なしの移動または平行移動

•

回転

•

拡大／縮小

•

傾斜

•

アルファの変更（0 〜 100 ％の透明度）

これらの変形は、キャッシュされたビットマップに直接適用されます。

不透明な背景色の設定
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトに不透明な背景を設定できます。例えば、背景に複雑なベクターアートが使用されている場合、

opaqueBackground プロパティを指定の色（通常はステージと同じ色）に設定できます。色は数値で指定します（通常は 16進数のカラー値）。これにより、背景はビットマップとして処理されるため、パフォーマンスの最適化に役立ちます。
cacheAsBitmap を true に設定し、opaqueBackground プロパティを指定の色に設定すると、opaqueBackground プロパティの設定によって内部ビットマップが不透明となり、レンダリングが高速になります。cacheAsBitmap を true に設定しなかった
場合、opaqueBackground プロパティによって表示オブジェクトの背景に不透明なベクター四角形シェイプが追加されます。
ビットマップは自動的には作成されません。
次の例は、表示オブジェクトの背景を設定してパフォーマンスを最適化する方法を示しています。
myShape.cacheAsBitmap = true;
myShape.opaqueBackground = 0xFF0000;

この例では、myShape という名前の Shape インスタンスの背景色を赤（0xFF0000）に設定します。白い背景のステージ上に描画された緑の三角形が Shape インスタンスに含まれている場合、緑の三角形の背景部分として、Shape インスタンスの境界ボックス（Shape の周りを囲む矩形）内の空き領域が赤で表示されます。

もちろんこのコードは、単色の赤の背景が設定されたステージで使用するのが実際的です。別の色の背景上では、その色が代わりに指定される可能性が高くなります。例えば、白い背景を持つ SWF では、opaqueBackground プロパティは 0xFFFFFF（白）に設定される可能性が高くなります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

178

表示のプログラミング

ブレンドモードの適用
Flash Player 9 以降、Adobe AIR 1.0 以降
ブレンドモードとは、あるイメージ（ベースイメージ）の色と別のイメージ（ブレンドイメージ）の色を組み合わせて第 3のイメージを作成することです。結果として作成されたイメージが、画面上で実際に表示されるイメージになります。あるイメージ内の各ピクセル値を他のイメージの対応するピクセル値で処理することにより、結果のイメージの同じ位置のピク
セル値が生成されます。
各表示オブジェクトには blendMode プロパティがあり、次のいずれかのブレンドモードに設定できます。これらのモード
は、BlendMode クラスで定義されている定数です。これらの代わりに、定数の実際の値である String 値（括弧内の値）を使用することもできます。

• BlendMode.ADD（"add"）：通常、2 つのイメージ間での色を薄くするディゾルブをアニメーション処理するのに使用されます。

• BlendMode.ALPHA（"alpha"）：通常、前景のアルファを背景に適用するのに使用されます。（GPU レンダリングではサポートされません。）• BlendMode.DARKEN（"darken"）：通常、重ね合わせ表示のタイプに使用されます。（GPU レンダリングではサポートされません。）• BlendMode.DIFFERENCE（"difference"）：通常、明るくて刺激的な色の作成に使用されます。
• BlendMode.ERASE（"erase"）：通常、前景のアルファを使用した背景の一部を切り抜く（消す）ために使用されます。
（GPU レンダリングではサポートされません。）• BlendMode.HARDLIGHT（"hardlight"）：通常、陰影効果の作成に使用されます。（GPU レンダリングではサポートされません。）• BlendMode.INVERT（"invert"）：背景を反転する場合に使用されます。
• BlendMode.LAYER（"layer"）：特定の表示オブジェクトを事前構成するための一時バッファーを強制的に作成する場合に使用されます。（GPU レンダリングではサポートされません。）• BlendMode.LIGHTEN（"lighten"）：通常、重ね合わせ表示のタイプに使用されます。（GPU レンダリングではサポートされません。）• BlendMode.MULTIPLY（"multiply"）：通常、影と深度の効果の作成に使用されます。
• BlendMode.NORMAL（"normal"）：ブレンドイメージのピクセル値でベースイメージのピクセル値を上書きするように指定するために使用されます。

• BlendMode.OVERLAY（"overlay"）：通常、陰影効果の作成に使用されます。（GPU レンダリングではサポートされません。）• BlendMode.SCREEN（"screen"）：通常、ハイライトとレンズのフレアに使用されます。
• BlendMode.SHADER（"shader"）：Pixel Bender シェーダーを使ってカスタムブレンド効果を作成するように指定するために使用されます。シェーダーの使用について詳しくは、285 ページの「Pixel Bender シェーダーの操作」を参照してください。（GPU レンダリングではサポートされません。）• BlendMode.SUBTRACT（"subtract"）：通常、2 つのイメージ間での色を濃くするディゾルブ効果をアニメーション処理するのに使用されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

179

表示のプログラミング

DisplayObject の色の調整
Flash Player 9 以降、Adobe AIR 1.0 以降
ColorTransform クラス（flash.geom.ColorTransform）のメソッドを使用して、表示オブジェクトの色を調整できます。
各表示オブジェクトには、transform プロパティがあります。このプロパティは Transform クラスのインスタンスであり、表示オブジェクトに適用される各種の変換（回転、スケールの変更、位置の変更など）に関する情報を格納します。また、Transform クラスは、図形変換に関する情報を格納するだけではなく、colorTransform プロパティも備えています。このプ
ロパティは ColorTransform クラスのインスタンスであり、このプロパティによって表示オブジェクトのカラーを調整できます。表示オブジェクトのカラー変換情報にアクセスするには、次のようなコードを使用します。
var colorInfo:ColorTransform = myDisplayObject.transform.colorTransform;

ColorTransform インスタンスを作成したらそのプロパティ値を読み取り、適用済みのカラー変換を確認できます。また、これらの値を設定して、表示オブジェクトに対してカラー変更を加えることもできます。何らかの変更後に表示オブジェク
トを更新するには、ColorTransform インスタンスを transform.colorTransform プロパティに再割り当てする必要があります。
var colorInfo:ColorTransform = myDisplayObject.transform.colorTransform;// Make some color transformations here.
// Commit the change.
myDisplayObject.transform.colorTransform = colorInfo;

コードを使用したカラー値の設定
Flash Player 9 以降、Adobe AIR 1.0 以降
ColorTransform クラスの color プロパティを使用すると、特定の赤、緑、青（RGB）のカラー値を表示オブジェクトに割り当てることができます。次の例では、color プロパティを使用し、blueBtn という名前のボタンがクリックされたときに、

square という名前の表示オブジェクトの色が青に変わるようにします。
// square is a display object on the Stage.
// blueBtn, redBtn, greenBtn, and blackBtn are buttons on the Stage.
import flash.events.MouseEvent;import flash.geom.ColorTransform;// Get access to the ColorTransform instance associated with square.
var colorInfo:ColorTransform = square.transform.colorTransform;// This function is called when blueBtn is clicked.
function makeBlue(event:MouseEvent):void{// Set the color of the ColorTransform object.
colorInfo.color = 0x003399;// apply the change to the display object
square.transform.colorTransform = colorInfo;}
blueBtn.addEventListener(MouseEvent.CLICK, makeBlue);color プロパティを使用して表示オブジェクトの色を変更すると、変更前のオブジェクトに複数の色があった場合でも、オブジェクト全体の色が完全に変更されます。上部に黒いテキストのある緑の円を含む表示オブジェクトがある場合、そのオブジェクトに関連付けられた ColorTransform インスタンスの color プロパティを赤の陰影に設定すると、オブジェクト、円、
テキストがすべて赤になります（したがって、テキストを他のオブジェクト部分から判別することはできなくなります）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

180

表示のプログラミング

コードを使用したカラーおよび明度効果の変更
Flash Player 9 以降、Adobe AIR 1.0 以降
複数の色を持つ表示オブジェクト（デジタル写真など）があり、オブジェクトの色を全面的に変更したくない（つまり、既存の色に基づいて表示オブジェクトの色を調整したい）という場合を想定します。このシナリオでは、こうした調整を作成するための乗数プロパティとオフセットプロパティが ColorTransform クラスに設定されています。redMultiplier、

greenMultiplier、blueMultiplier、alphaMultiplier という名前の乗数プロパティは、色付きの写真フィルター（または色付きサングラス）と同様に動作し、表示オブジェクト内の特定の色を強くしたり弱くしたりします。オフセットプロパティ（redOffset、greenOffset、blueOffset、alphaOffset）は、オブジェクトに特定の色を余分に追加したり、特定の色に対して設定できる最小値を指定する場合に使用されます。
これらの乗数プロパティとオフセットプロパティの共通点は、プロパティインスペクターで「カラー」ポップアップメ
ニューから「詳細」を選択すると、Flash オーサリングツールのムービークリップシンボルに対して詳細なカラー設定を利用できるようになることです。
次のコードでは、JPEG イメージをロードしてカラー変換を適用します。これにより、x 軸と y 軸に沿ってマウスポイン
ターを移動すると、赤のチャンネルと緑のチャンネルが調整されます。この例ではオフセット値が指定されていないため、画面上に表示される各カラーチャンネルのカラー値は、イメージ内の元のカラー値のパーセンテージになります。つまり、特定のピクセルで表示されるほとんどの赤や緑は、そのピクセル内の元の赤や緑の量と同じになります。
import flash.display.Loader;import flash.events.MouseEvent;import flash.geom.Transform;
import flash.geom.ColorTransform;
import flash.net.URLRequest;// Load an image onto the Stage.
var loader:Loader = new Loader();var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg");
loader.load(url);
this.addChild(loader);// This function is called when the mouse moves over the loaded image.
function adjustColor(event:MouseEvent):void{// Access the ColorTransform object for the Loader (containing the image)var colorTransformer:ColorTransform = loader.transform.colorTransform;// Set the red and green multipliers according to the mouse position.
// The red value ranges from 0% (no red) when the cursor is at the left// to 100% red (normal image appearance) when the cursor is at the right.
// The same applies to the green channel, except it's controlled by the// position of the mouse in the y axis.
colorTransformer.redMultiplier = (loader.mouseX / loader.width) * 1;colorTransformer.greenMultiplier = (loader.mouseY / loader.height) * 1;// Apply the changes to the display object.
loader.transform.colorTransform = colorTransformer;}
loader.addEventListener(MouseEvent.MOUSE_MOVE, adjustColor);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

181

表示のプログラミング

オブジェクトの回転
Flash Player 9 以降、Adobe AIR 1.0 以降
rotation プロパティを使用して、表示オブジェクトを回転することができます。この値を読み取って、オブジェクトが回転されたかどうかを確認したり、オブジェクトに適用される回転量を表す数値（度数）をこのプロパティで設定して、オブジェクトを回転したりすることができます。例えば、このコード行では、square という名前のオブジェクトを 45 度（完全な1 回転の 8 分の 1）回転します。
square.rotation = 45;

別の方法として、201 ページの「ジオメトリの操作」で説明されている変換行列を使用して表示オブジェクトを回転することもできます。

オブジェクトのフェード
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトの透明度を制御して、表示オブジェクトを部分的に（または完全に）透明にしたり、または透明度を変更
して、オブジェクトをフェードインまたはフェードアウトさせたりすることができます。DisplayObject クラスの alpha プロ
パティでは、表示オブジェクトの透明度（より正確には不透明度）を定義します。alpha プロパティは、0 と 1 の間の任意の値に設定できます。ここで、0 は完全に透明、1 は完全に不透明であることを意味します。例えば、このコード行では、マウスがクリックされたときに、myBall という名前のオブジェクトを部分的に（50%）透明にします。
function fadeBall(event:MouseEvent):void{
myBall.alpha = .5;}
myBall.addEventListener(MouseEvent.CLICK, fadeBall);ColorTransform クラスを通じて利用できるカラー調整を使用して、表示オブジェクトの透明度を変更することもできます。詳しくは、179 ページの「DisplayObject の色の調整」を参照してください。

表示オブジェクトのマスク
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトをマスクとして使用することにより、空洞を作成し、この空洞から別の表示オブジェクトのコンテンツを表示することができます。

マスクの定義別の表示オブジェクトのマスクとなる表示オブジェクトを指定するには、マスクされる表示オブジェクトの mask プロパティとしてマスクオブジェクトを設定します。
// Make the object maskSprite be a mask for the object mySprite.
mySprite.mask = maskSprite;

マスクされる表示オブジェクトは、マスクとして機能する表示オブジェクトのすべての不透明な（透明でない）領域で表示されます。例えば、次のコードでは、赤色で 100 × 100 ピクセルの四角形を含む Shape インスタンスと、青色で半径 25 ピク
セルの円を含む Sprite インスタンスを作成します。円をクリックすると、円は四角形のマスクとして設定されます。結果的に、四角形の表示される部分は、円の単体部分によって覆い隠された部分のみとなります。すなわち、赤い円しか表示されません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

182

表示のプログラミング// This code assumes it's being run within a display object container// such as a MovieClip or Sprite instance.
import flash.display.Shape;// Draw a square and add it to the display list.
var square:Shape = new Shape();square.graphics.lineStyle(1, 0x000000);
square.graphics.beginFill(0xff0000);
square.graphics.drawRect(0, 0, 100, 100);square.graphics.endFill();this.addChild(square);// Draw a circle and add it to the display list.
var circle:Sprite = new Sprite();circle.graphics.lineStyle(1, 0x000000);circle.graphics.beginFill(0x0000ff);
circle.graphics.drawCircle(25, 25, 25);
circle.graphics.endFill();this.addChild(circle);function maskSquare(event:MouseEvent):void{square.mask = circle;
circle.removeEventListener(MouseEvent.CLICK, maskSquare);}circle.addEventListener(MouseEvent.CLICK, maskSquare);

マスクとして機能する表示オブジェクトは、ドラッグ、アニメーション化、動的なサイズ変更が可能なほか、単一のマスク
内で別個のシェイプを使用できます。マスク表示オブジェクトは、必ずしも表示リストに追加する必要があるわけではありません。ただし、ステージが拡大／縮小されるときにマスクオブジェクトを拡大／縮小したい場合、または、マスクを使ったユーザー操作（ユーザー制御のドラッグやサイズ変更など）を可能にしたい場合は、マスクオブジェクトを表示リストに追加する必要があります。マスクオブジェクトを表示リストに追加する間、表示オブジェクトの実際の z 順序（重ね順）は関係ありません ( マスクオブジェクトは、マスクとして以外に画面上に表示されることはありません )。マスクオブジェクト
が、複数のフレームのある MovieClip インスタンスであった場合、このオブジェクトがマスクとして機能しなかった場合と同様に、すべてのフレームがそのタイムライン内で再生されます。mask プロパティを次のように null に設定すると、マスクを削除できます。
// remove the mask from mySprite
mySprite.mask = null;

別のマスクをマスクするためにマスクを使用することはできません。マスク表示オブジェクトの alpha プロパティを設定することはできません。マスクとして使用される表示オブジェクトでは、塗りのみを使用できます（線は無視されます）。

AIR 2
マスクされる表示オブジェクトが cacheAsBitmap プロパティおよび cacheAsBitmapMatrix プロパティの設定によってキャッシュされる場合は、マスクはマスクされる表示オブジェクトの子である必要があります。同様に、マスクされる表示オブジェクトが、キャッシュされる表示オブジェクトコンテナの子孫の場合は、マスクと表示オブジェクトの両方がそのコンテナの子孫である必要があります。マスクされるオブジェクトが複数のキャッシュされる表示オブジェクトコンテナの子孫の場合は、マスクは、表示リスト内のマスクされるオブジェクトに最も近い、キャッシュされるコンテナの子孫である必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

183

表示のプログラミング

デバイスフォントのマスクについて
表示オブジェクトを使用して、デバイスフォントで設定されたテキストをマスクすることができます。表示オブジェクトを使用して、デバイスフォントで設定されたテキストをマスクする場合、マスクの矩形境界ボックスがマスクシェイプとして使用されます。すなわち、デバイスフォントテキストに対する非矩形の表示オブジェクトマスクを作成する場合、SWF ファ
イルに表示されるマスクは、マスク自体のシェイプではなく、マスクの矩形境界ボックスのシェイプになります。

アルファチャンネルマスク
アルファチャンネルマスクがサポートされるのは、マスクおよびマスクされる側の両方の表示オブジェクトがビットマップ
キャッシュを使用している場合です。
// maskShape is a Shape instance which includes a gradient fill.
mySprite.cacheAsBitmap = true;
maskShape.cacheAsBitmap = true;
mySprite.mask = maskShape;

例えば、アルファチャンネルマスクの適用例の 1 つは、マスクされる表示オブジェクトに適用されるフィルターとは別にマスクオブジェクト上でフィルターを使用することです。
次に示す例では、外部のイメージファイルをステージ上にロードします。このイメージ（より正確には、イメージがその中にロードされる Loader インスタンス）は、マスクされる表示オブジェクトになります。グラデーションのある楕円形（単色の黒の中心から端に向かって透明にフェード）がイメージに描画されます。これが、アルファマスクです。両方の表示オブジェクトで、ビットマップキャッシュがオンになっています。楕円形はイメージのマスクとして設定され、次にドラッグ可能に設定されます。
// This code assumes it's being run within a display object container// such as a MovieClip or Sprite instance.
import flash.display.GradientType;import flash.display.Loader;import flash.display.Sprite;
import flash.geom.Matrix;
import flash.net.URLRequest;// Load an image and add it to the display list.
var loader:Loader = new Loader();var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg");
loader.load(url);
this.addChild(loader);// Create a Sprite.
var oval:Sprite = new Sprite();// Draw a gradient oval.
var colors:Array = [0x000000, 0x000000];
var alphas:Array = [1, 0];
var ratios:Array = [0, 255];

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

184

表示のプログラミング

var matrix:Matrix = new Matrix();
matrix.createGradientBox(200, 100, 0, -100, -50);
oval.graphics.beginGradientFill(GradientType.RADIAL,
colors,alphas,ratios,matrix);oval.graphics.drawEllipse(-100, -50, 200, 100);
oval.graphics.endFill();// add the Sprite to the display list
this.addChild(oval);// Set cacheAsBitmap = true for both display objects.
loader.cacheAsBitmap = true;
oval.cacheAsBitmap = true;// Set the oval as the mask for the loader (and its child, the loaded image)loader.mask = oval;// Make the oval draggable.
oval.startDrag(true);

オブジェクトのアニメーション化
Flash Player 9 以降、Adobe AIR 1.0 以降
アニメーションは、時間の経過と共に何かを動かす、または、何かを変化させる処理です。スクリプトで記述されたアニメーションは、ビデオゲームの基本的部分であり、他のアプリケーションを洗練したり、便利な操作上のヒントを提供した
りするために頻繁に使用されます。
スクリプトで記述されたアニメーションの基本的概念は、変化が生じる必要があり、その変化が時間の経過と共にインクリ
メントに分割される必要があるということです。ActionScript では、一般的なループステートメントを使用して、何かを繰り返す処理が簡単にできます。ただし、ループは、表示を更新するまで、すべての繰り返しを通じて実行されます。スクリ
プトで記述されたアニメーションを作成するには、時間の経過と共に繰り返しアクションを実行する ActionScript を記述
し、実行するたびに画面を更新する必要があります。
例えば、画面でボールが移動するような、単純なアニメーションを作成するとします。ActionScript には、時間の推移を追跡し、これに従って画面を更新できるシンプルなメカニズムが備わっています。これはすなわち、ボールが目的地に到達す
るまで、時間と共に少しずつ移動するようなコードを記述できることを意味します。各動きごとに画面を更新すると、ス
テージをまたがるモーションがビューアに表示されます。
実用的な観点から、スクリプトで記述するアニメーションは SWF ファイルのフレームレートと同期させる（個々の新しいフレームが表示されるタイミングまたはその直前にアニメーションを変化させる）ことが合理的です。なぜなら、Flash

Player または AIR で画面の更新処理を実行する頻度はフレームレートによって決定されるからです。各表示オブジェクトには、SWF ファイルのフレームレートに従って送出される enterFrame イベントがあります（各フレームに 1 イベント）。ス
クリプトで記述されたアニメーションを作成する開発者の多くは、enterFrame イベントを、時間と共に繰り返すアクションを作成する方法として使用しています。enterFrame イベントをリッスンするコードを記述して、アニメーション化されたボールを各フレームごとに一定量動かすことができます。画面の更新（各フレーム）後、ボールは新しい位置で再描画され、モーションが生成されます。
注意：時間の経過と共にアクションを繰り返し実行するためのもう 1 つの方法は、Timer クラスを使用することです。
Timer インスタンスは、指定された時間が経過するごとに、イベント通知をトリガーします。Timer クラスの timer イベン
トを処理して、時間間隔を短く（1 秒の数分の 1）に設定することにより、アニメーションを実行するコードを記述できま
す。Timer クラスの使用について詳しくは、4 ページの「タイマー間隔の制御」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

185

表示のプログラミング

次の例では、circle という名前の円 Sprite インスタンスを Stage 上に作成します。円がクリックされると、スクリプトで記述されたアニメーションのシーケンスが開始し、円が完全に透明になるまで circle がフェードします（その alpha プロパティ
が減少します）。
import flash.display.Sprite;
import flash.events.Event;import flash.events.MouseEvent;// draw a circle and add it to the display list
var circle:Sprite = new Sprite();circle.graphics.beginFill(0x990000);circle.graphics.drawCircle(50, 50, 50);
circle.graphics.endFill();
addChild(circle);// When this animation starts, this function is called every frame.
// The change made by this function (updated to the screen every// frame) is what causes the animation to occur.
function fadeCircle(event:Event):void{
circle.alpha -= .05;
if (circle.alpha <= 0){circle.removeEventListener(Event.ENTER_FRAME, fadeCircle);}}function startAnimation(event:MouseEvent):void{
circle.addEventListener(Event.ENTER_FRAME, fadeCircle);}
circle.addEventListener(MouseEvent.CLICK, startAnimation);

円がクリックされると、fadeCircle() が enterFrame イベントのリスナーとしてサブスクライブされます（フレームごとに 1 回
呼び出され始めます）。この関数では、alpha プロパティを変更することにより、circle をフェードさせます。したがって、フレームごとに 1 回、円の alpha が 0.05（5%）ずつ減少し、画面が更新されます。最終的には、alpha 値が 0（circle が完全に透明）になると、fadeCircle() 関数はリスナーとして削除され、アニメーションは終わります。
同じコードを使用して、例えば、フェードではなく、モーションのアニメーションを作成できます。enterFrame イベントリ
スナーである関数内で、alpha に対するプロパティを置き換えることにより、このプロパティが代わりにアニメーション化されます。例えば、次の行を
circle.alpha -= .05;

次の行にcircle.x += 5;置き換えると、x プロパティがアニメーション化され、結果的に円がステージの右へ移動します。目的の x 座標に達したら、アニメーションを終了する条件を変更して、アニメーションを終了できます（enterFrame リスナーがサブスクライブ解除されます）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

186

表示のプログラミング

ステージの方向AIR 2.0 以降
一般的なモバイルデバイスでは、ユーザーがデバイスを回転させたときに、ディスプレイの直立状態を維持するためにユー
ザーインターフェイスの方向が再設定されます。アプリケーションで自動回転を有効にすると、デバイスのディスプレイは正しい向きに維持されますが、ステージの縦横比が変更されたときにコンテンツを問題なく表示するには、開発者がそのように設定する必要があります。自動回転を無効にすると、デバイスの表示はユーザーが方向を手動で変更しない限り固定されます。

AIR アプリケーションは様々なモバイルデバイスやオペレーティングシステムで動作します。基になる方向設定の動作はオ
ペレーティングシステム間で異なる場合があり、さらには同じオペレーティングシステムでもデバイス間で異なる場合があります。あらゆるデバイスやオペレーティングシステムに適したシンプルなデザイン戦略は、自動回転を有効にし、Stageの resize イベントを監視してアプリケーションレイアウトの更新タイミングを判断することです。
また、アプリケーションが縦長の縦横比のみ、または横長の縦横比のみをサポートする場合は、自動回転を無効にして、サポートする縦横比を AIR アプリケーション記述子で設定することができます。このデザイン戦略によって一貫した動作が可能になり、選択した縦横比に応じた「最適な」方向が選択されます。例えば、横長の縦横比を指定する場合、選択した方向は、横長モードとスライド式キーボードを搭載したデバイスに適しています。

現在のステージの方向および縦横比の取得
方向は、デバイスの通常の位置を基準として報告されます。ほとんどのデバイスには、明確な直立位置があります。この位置を「default」（デフォルト）方向と考えます。他に取りうる 3 つの方向は、「rotated left」（左に回転）、「rotated right」（右に回転）、「upside down」（上下反転）です。StageOrientation クラスは、方向の値の設定や比較に使用する文字列定数を定義します。

Stage クラスでは方向を報告する 2 つのプロパティを定義します。

• Stage.deviceOrientation - デフォルト位置を基準としたデバイスの物理的な方向を報告します。
注意：deviceOrientation は常に取得できるとは限りません。アプリケーションの最初の起動時や、デバイスが水平に置かれている場合などは、デバイスの方向が「unknown」（不明）として報告されます。

• Stage.orientation - デフォルト位置を基準としたステージの方向を報告します。自動回転が有効な場合、ステージは直立状態を維持するよう、デバイスとは逆の方向に回転します。このため、orientation プロパティが報告する右と左の位置
は、deviceOrientation プロパティが報告する右と左の位置とは逆になります。例えば、deviceRotation が rotated rightと報告する場合、orientation は rotated left と報告します。
ステージの縦横比は、現在のステージの幅と高さを単純に比較することによって導き出すことが可能です。
var aspect:String = this.stage.stageWidth >= this.stage.stageHeight ? StageAspectRatio.LANDSCAPE :StageAspectRatio.PORTRAIT;

自動回転
自動回転が有効なときにユーザーがデバイスを回転させると、オペレーティングシステムは、システムタスクバーやアプリ
ケーションを含むユーザーインターフェイス全体の方向を再設定します。この結果、ステージの縦横比は縦長から横長へ、または横長から縦長へ変更されます。縦横比が変更されるとステージサイズも変更されます。
実行時に自動回転の有効と無効を切り替えるには、Stage の autoOrients プロパティを true または false に設定します。

<autoOrients> エレメントを使用して、AIR アプリケーション記述子にこのプロパティの初期値を設定することができます（AIR 2.6 よりも前のバージョンでは、autoOrients は読み取り専用プロパティであり、アプリケーション記述子のみで設定可能です）。
横長または縦長の縦横比を指定して自動回転を有効にすると、AIR では自動回転が指定された縦横比に制限されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

187

表示のプログラミング

ステージサイズの変更
ステージサイズが変更された場合、ステージのコンテンツは Stage オブジェクトの scaleMode と align に指定されたとおりに
拡大／縮小され、再配置されます。ほとんどの場合、Stage の scaleMode 設定に指定された自動的な動作を使用すると、良い結果が得られません。複数の縦横比をサポートするには、グラフィックやコンポーネントの再レイアウトと再描画が必要になります（柔軟なレイアウトロジックを実現することは同時に、画面サイズや縦横比が異なるデバイス間でアプリケー
ションが適切に動作することを意味します）。
次の図では、一般的なモバイルデバイスの回転時における様々な scaleMode 設定の効果について示します。

横長から縦長への縦横比の回転

この図は、それぞれの拡大／縮小モードで、横長の縦横比から縦長の縦横比に回転する際に発生する拡大／縮小の動作を示しています。縦長から横長への回転でも同様の結果となります。
方向変化イベントStage オブジェクトは 2 種類のイベントを送出します。これらのイベントは、方向の変化を検出してそれに対応するために使用できます。自動回転が有効の場合は、ステージの resize イベントと orientationChange イベントの両方が送出されます。

resize イベントは、自動回転を使用してディスプレイの直立状態を維持している場合に最適なイベントです。ステージからの resize イベントの送出時に、必要に応じてコンテンツの再レイアウトや再描画が実行されます。resize イベントは、ステー
ジの拡大／縮小モードが noScale に設定されている場合のみに送出されます。

orientationChange イベントを方向の変化の検出に使用することもできます。orientationChange イベントは、自動回転が有効な場合にのみに送出されます。
注意：一部のモバイルプラットフォームでは、ステージは、resize イベントまたは orientationChange イベントの送出前に、キャンセル可能な orientationChanging イベントを送出します。このイベントはすべてのプラットフォームでサポートされているわけではないので、使用を避けてください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

188

表示のプログラミング

手動の方向設定
AIR 2.6 以降
Stage オブジェクトの setOrientation() メソッドまたは setAspectRatio() メソッドを使用してステージの方向を制御できます。
ステージの方向の設定

Stage オブジェクトの setOrientation() メソッドを使用して、実行時にステージの方向を設定できます。必要な方向を指定す
るには、StageOrientation クラスで定義された文字列定数を使用します。
this.stage.setOrientation( StageOrientation.ROTATED_RIGHT );指定可能なすべての方向が、すべてのデバイスおよびオペレーティングシステムでサポートされているわけではありません。
例えば、Android 2.2 では、縦長を標準とするデバイスの左回転方向をプログラムによって選択することはできません。また、上下反転の方向はサポートされていません。ステージの supportedOrientations プロパティは、setOrientation() メソッドに渡すことのできる方向のリストを提供します。
var orientations:Vector.<String> = this.stage.supportedOrientations;for each( var orientation:String in orientations ){trace( orientation );}ステージの縦横比の設定
ステージの縦横比については、縦横比を縦長または横長に設定できます。Stage オブジェクトの setAspectRatio() メソッドを使用することで、AIR アプリケーション記述子に、または実行時に縦横比を設定できます。
this.stage.setAspectRatio( StageAspectRatio.LANDSCAPE );ランタイムでは、指定された縦横比に対して 2 つの方向のいずれかを選択します。これは、現在のデバイスの方向と一致しない場合があります。例えば、上下反転の方向よりも、デフォルトの方向が優先して選択され（AIR·3.2· 以前）、反対の方向よりも、スライド式キーボードに適した方向が優先して選択されます（AIR 3.3 以降）AIR 3.3（SWF バージョン 16）以降では、StageAspectRatio.ANY 定数を使用することもできます。

Stage.autoOrients が true に設定されている場合に setAspectRatio(StageAspectRatio.ANY) を呼び出すと、アプリケーションでは方向をすべての方向に再設定できます（横長 - 左、横長 - 右、縦長および縦長 - 上下反転）。また、AIR 3.3 では、縦横比が固定され、デバイスの回転が指定された方向に制限されるようになりました。
例：デバイスの方向に合わせたステージの方向の設定
次の例では、現在のデバイスの方向に合わせてステージの方向を更新する関数を示します。ステージの deviceOrientation プ
ロパティは、自動回転が無効な場合でも、デバイスの物理的な方向を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

189

表示のプログラミング

function refreshOrientation( theStage:Stage ):void{switch ( theStage.deviceOrientation ){case StageOrientation.DEFAULT:
theStage.setOrientation( StageOrientation.DEFAULT );break;
case StageOrientation.ROTATED_RIGHT:
theStage.setOrientation( StageOrientation.ROTATED_LEFT );break;
case StageOrientation.ROTATED_LEFT:
theStage.setOrientation( StageOrientation.ROTATED_RIGHT );break;
case StageOrientation.UPSIDE_DOWN:
theStage.setOrientation( StageOrientation.UPSIDE_DOWN );break;
default://No change}}

方向の変更は非同期です。ステージによって送出された orientationChange イベントをリッスンして、変更の完了を検出することができます。方向がデバイスでサポートされていない場合は、エラーをスローせずに setOrientation() の呼び出しが失敗します。

表示コンテンツの動的ロード
Flash Player 9 以降、Adobe AIR 1.0 以降
次の外部表示アセットを ActionScript 3.0 アプリケーションにロードできます。

• ActionScript 3.0 でオーサリングされた SWF ファイル — Sprite、MovieClip、または Sprite を拡張する任意のクラスです。iOS 上の AIR アプリケーションでは、ActionScript バイトコードを含まない SWF ファイルのみをロードできます。つまり、イメージやサウンドなどの埋め込みデータを含む SWF ファイルをロードできますが、実行可能コードを含む SWF ファイルはロードできません。
•

イメージファイル — JPG、PNG、および GIF ファイルが含まれます。

• AVM1 SWF ファイル — ActionScript 1.0 または 2.0 で記述された SWF ファイルです（モバイル AIR アプリケーショ
ンではサポートされていません）。
これらのアセットをロードするには、Loader クラスを使用します。

表示オブジェクトのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
Loader オブジェクトは、SWF ファイルおよびグラフィックファイルをアプリケーションにロードするために使用されます。Loader クラスは、DisplayObjectContainer クラスのサブクラスです。Loader オブジェクトは、その表示リストに子表示オブジェクト（ロードされる SWF またはグラフィックファイルを表す表示オブジェクト）を 1 つしか含むことができません。表示リストに Loader オブジェクトを追加するときは、次のコードのように、子表示オブジェクトのロードが完了したら、ロードされた子表示オブジェクトも表示リストに追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

190

表示のプログラミング

var pictLdr:Loader = new Loader();var pictURL:String = "banana.jpg"
var pictURLReq:URLRequest = new URLRequest(pictURL);
pictLdr.load(pictURLReq);
this.addChild(pictLdr);

SWF ファイルまたはイメージがロードされたら、ロードされた表示オブジェクトを、次の例に示す container
DisplayObjectContainer オブジェクトのような別の表示オブジェクトコンテナに移動できます。
import flash.display.*;
import flash.net.URLRequest;
import flash.events.Event;var container:Sprite = new Sprite();addChild(container);var pictLdr:Loader = new Loader();var pictURL:String = "banana.jpg"
var pictURLReq:URLRequest = new URLRequest(pictURL);
pictLdr.load(pictURLReq);
pictLdr.contentLoaderInfo.addEventListener(Event.COMPLETE, imgLoaded);function imgLoaded(event:Event):void{container.addChild(pictLdr.content);}

ロードの進行状況の監視
Flash Player 9 以降、Adobe AIR 1.0 以降
ファイルがロードを開始すると、LoaderInfo オブジェクトが作成されます。LoaderInfo オブジェクトは、ロードの進行状
況、ロードする側およびロードされる側の URL、メディアの総バイト数、メディアの規格高さと幅などの情報を提供します。LoaderInfo オブジェクトは、ロードの進行状況を監視するためのイベントも送出します。
次の図は、LoaderInfo オブジェクトの各種使用方法を示します。LoaderInfo オブジェクトは、SWF ファイルのメインク
ラスのインスタンス、Loader オブジェクト、および Loader オブジェクトによってロードされたオブジェクトの場合でそれぞれ使用方法が異なります。
ステージ

LoaderInfo
オブジェクトSWF ファイルのloaderInfo プロパティ

メインクラスのインスタンス

Loader オブジェクト

contentLoaderInfo プロパティ

LoaderInfo
オブジェクトオブジェクトloaderInfo プロパティ

LoaderInfo オブジェクトは、Loader オブジェクトと、ロードされた表示オブジェクトの両方のプロパティとしてアクセスできます。LoaderInfo オブジェクトは、ロードが開始されると同時に、Loader オブジェクトの contentLoaderInfo プロパ
ティを介してアクセスできます。また、表示オブジェクトのロード完了後は、表示オブジェクトの loaderInfo プロパティを介してロードされた表示オブジェクトのプロパティとして LoaderInfo オブジェクトにアクセスすることができます。ロー

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

191

表示のプログラミング

ドされた表示オブジェクトの loaderInfo プロパティは、Loader オブジェクトの contentLoaderInfo プロパティと同じLoaderInfo オブジェクトを参照します。つまり、LoaderInfo オブジェクトは、ロードされたオブジェクトファイルとロードした Loader オブジェクト間（ロードする側およびロードされる側の間）で共有されます。
ロードされたコンテンツのプロパティにアクセスするには、LoaderInfo オブジェクトにイベントリスナーを次のコードのように追加する必要があります。
import flash.display.Loader;import flash.display.Sprite;
import flash.events.Event;var ldr:Loader = new Loader();var urlReq:URLRequest = new URLRequest("Circle.swf");
ldr.load(urlReq);
ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, loaded);
addChild(ldr);function loaded(event:Event):void{
var content:Sprite = event.target.content;
content.scaleX = 2;}

詳しくは、119 ページの「イベント処理」を参照してください。

ロードコンテキストの指定
Flash Player 9 以降、Adobe AIR 1.0 以降
Loader クラスの load() または loadBytes() メソッドを介して Flash Player に外部ファイルをロードする場合、オプションで
context パラメーターを指定できます。このパラメーターは LoaderContext オブジェクトです。
LoaderContext クラスには、ロードされたコンテンツの使用方法のコンテキストを定義できる次の 3 つのプロパティが含まれています。

• checkPolicyFile：このプロパティは、SWF ファイルではなくイメージファイルをロードする場合にのみ使用します。このプロパティを true に設定した場合、Loader は元のサーバーで ポリシーファイルをチェックします（1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照）。これは、Loader オブジェクトを含む SWF ファイルのドメイン以外のドメインにあるコンテンツにのみ必要です。サーバーから Loader ドメインにアクセス許可が与えられている場合、Loader ドメイン内の SWF ファイルの ActionScript はロードされたイメージ内のデータにアクセスできます。
つまり、BitmapData.draw() コマンドを使用して、ロードされたイメージ内のデータにアクセスできます。

Loader オブジェクトのドメイン以外の他のドメインにある SWF ファイルは、Security.allowDomain() を呼び出して特定のドメインを許可できます。

• securityDomain：このプロパティは、イメージではなく SWF ファイルをロードする場合にのみ使用します。Loader オ
ブジェクトを含むファイルのドメイン以外のドメインの SWF ファイルに対してこのプロパティを指定します。このオプ
ションを指定すると、Flash Player はポリシーファイルが存在するかどうかをチェックします。ファイルが存在する場合
は、クロスポリシーファイルで許可されているドメインの SWF ファイルはロードされた SWF コンテンツをクロススク
リプトできます。このパラメーターとして flash.system.SecurityDomain.currentDomain を指定できます。

• applicationDomain：ActionScript 1.0 や 2.0 で記述されたイメージまたは SWF ファイルではなく、ActionScript 3.0 で記述された SWF ファイルをロードする場合にのみ、このプロパティを使用します。ファイルをロードするとき、applicationDomain パラメーターを flash.system.ApplicationDomain.currentDomain に設定することで、ファイルがLoader オブジェクトと同じアプリケーションドメインに含まれるように指定できます。ロードされた SWF ファイルを同じアプリケーションドメインに置くと、そのクラスに直接アクセスできます。これは、関連付けられたクラス名を使用

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

192

表示のプログラミング

してアクセスできる埋め込みメディアを含む SWF ファイルをロードする場合に便利です。詳しくは、140 ページの「アプリケーションドメインの操作」を参照してください。
次に示す例では、別のドメインからビットマップをロードするとき、ポリシーファイルをチェックします。
var context:LoaderContext = new LoaderContext();
context.checkPolicyFile = true;
var urlReq:URLRequest = new URLRequest("http://www.[your_domain_here].com/photo11.jpg");
var ldr:Loader = new Loader();
ldr.load(urlReq, context);

次に示す例では、別のドメインから SWF をロードするときに、ポリシーファイルをチェックし、このファイルを Loader
オブジェクトと同じセキュリティサンドボックス内に配置します。また、このコードは、ロードされた SWF ファイルのク
ラスを Loader オブジェクトと同じアプリケーションドメインに追加します。
var context:LoaderContext = new LoaderContext();
context.securityDomain = SecurityDomain.currentDomain;context.applicationDomain = ApplicationDomain.currentDomain;var urlReq:URLRequest = new URLRequest("http://www.[your_domain_here].com/library.swf");
var ldr:Loader = new Loader();
ldr.load(urlReq, context);

詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の LoaderContext クラスの項を参照してください。

AIR for iOS での SWF ファイルのロード
Adobe AIR 3.6 以降、iOS のみ
iOS デバイスでは、実行時のコードのロードやコンパイルに制限があります。この制限により、外部の SWF ファイルをア
プリケーションにロードする作業には、以下のような違いが必要になります。

• ActionScript コードを含む SWF ファイルはすべて、アプリケーションパッケージに含める必要があります。コードを含む SWF は、ネットワーク経由など、外部ソースからロードすることはできません。アプリケーションのパッケージ化の一環として、アプリケーションパッケージに含まれるすべての SWF ファイル内のすべての ActionScript コードが、
iOS デバイス用のネイティブコードにコンパイルされます。
• SWF ファイルをロードし、アンロードしてから再ロードすることはできません。これを行おうとすると、エラーが発生します。

•

メモリにロードしてからアンロードするビヘイビアーは、デスクトッププラットフォームの場合と同じです。SWF ファ
イルをロードしてからアンロードすると、SWF に含まれるすべてのビジュアルアセットがメモリからアンロードされます。ただし、ロードされた SWF 内の ActionScript クラスに対するクラス参照は、メモリ内に残り、ActionScript コー
ドでアクセスできます。

•

ロードされる SWF ファイルはすべて、メインの SWF ファイルと同じアプリケーションドメインにロードする必要があります。これはデフォルトのビヘイビアーではないため、SWF をロードするたびに、メインのアプリケーションドメイ
ンを指定する LoaderContext オブジェクトを作成し、その LoaderContext オブジェクトを Loader.load() メソッド呼び出しに渡す必要があります。メインの SWF アプリケーションドメイン以外のアプリケーションドメインに SWF をロードしようとすると、エラーが発生します。これは、ロードされる SWF にビジュアルアセットのみが含まれ、ActionScript コードが含まれていない場合でも同じです。
次の例は、アプリケーションパッケージからメインの SWF のアプリケーションドメインへ SWF をロードする際に使用するコードを示しています。
var loader:Loader = new Loader();var url:URLRequest = new URLRequest("swfs/SecondarySwf.swf");
var loaderContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain, null);loader.load(url, loaderContext);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

193

表示のプログラミング

アセットのみが含まれ、コードが含まれていない SWF ファイルは、アプリケーションパッケージからでも、ネットワーク
経由でも、ロードできます。いずれの場合も、SWF ファイルはメインのアプリケーションドメインにロードする必要があります。

AIR 3.6 より前のバージョンの AIR の場合は、コンパイル処理中に、メインのアプリケーション SWF ではなく、SWF から、すべてのコードが削除されます。ビジュアルアセットのみを含む SWF ファイルは、アプリケーションパッケージに含めて実行時にロードできますが、コードはできません。ActionScript コードを含む SWF をロードしようとすると、エラーが発生します。このエラーが発生すると、未コンパイルの ActionScript エラーダイアログがアプリケーションに表示されます。
参照項目

iOS 上の AIR アプリケーションでの複数の SWF のパッケージ化とロード

ProLoader クラスおよび ProLoaderInfo クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降および Flash Professional CS5.5 が必要
リモート共有ライブラリ（RSL）のプリロードのために、Flash Professional CS5.5 では、fl.display.ProLoader および

fl.display.ProLoaderInfo クラスが導入されています。これらのクラスは、flash.display.Loader クラスおよび
flash.display.LoaderInfo クラスをミラーしますが、さらに一貫したロード操作を実現します。
特に ProLoader では、RSL プリロードを伴う、Text Layout Framework（TLF）を使用する SWF ファイルのロードを簡
単に実行できます。実行時、TLF などの、他の SWF ファイルまたは SWZ ファイルをプリロードする SWF ファイルには、内部利用のみの SWF ラッパーファイルが必要になります。SWF ラッパーファイルによって複雑さのレイヤーが追加され、予期しない動作が発生することがあります。ProLoader は、このような複雑さを解決し、通常の SWF ファイルであるかのようにこれらのファイルをロードします。ProLoader クラスによって使用されるソリューションはユーザーに対しては透過的であり、ActionScript での特別な処理は必要ありません。さらに、ProLoader は通常の SWF コンテンツを正確にロードします。

Flash Professional CS5.5 以降では、Loader クラスのすべての使用箇所を ProLoader クラスに安全に置き換えることができます。その後、必要な ActionScript 機能に ProLoader がアクセスできるよう、アプリケーションを Flash Player 10.2 以
降に書き出します。ActionScript 3.0 をサポートする、以前の Flash Player のバージョンを対象とする場合も、ProLoader
を使用することができます。ただし、ProLoader 機能を最大限に活用できるのは Flash Player 10.2 以降のみです。Flash
Professional CS5.5 以降で TLF を使用する場合は常に ProLoader を使用してください。Flash Professional 以外の環境では、ProLoader は必要ありません。
重要：Flash Professional CS5.5 以降でパブリッシュされた SWF ファイルについては、flash.display.Loader および
flash.display.LoaderInfo の代わりに、常に fl.display.ProLoader および fl.display.ProLoaderInfo クラスを使用できます。

ProLoader クラスによって解決される問題
ProLoader クラスでは、従来の Loader クラスでは処理するよう想定されていなかった問題が解決されます。これらの問題
は、TLF ライブラリの RSL プリロードによるものです。特に、Loader オブジェクトを使用して他の SWF ファイルをロードする SWF ファイルに適用されます。解決される問題には次のものがあります。

•

ロードする側のファイルとロードされる側のファイルの間のスクリプティングが期待通りに動作しません。ProLoader
クラスは、ロードする側の SWF ファイルをロードされる側の SWF ファイルの親として自動的に設定します。このため、ロードする側の SWF ファイルからの情報が、ロードされる側の SWF ファイルに直接伝達されます。

• SWF アプリケーションで、積極的にロード処理を管理する必要があります。これを行うためには、added、removed、
addedToStage、removedFromStage などの追加イベントの実装が必要です。アプリケーションが Flash Player 10.2 以降を対象とする場合は、ProLoader を使用すればこのような追加の作業をする必要がなくなります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

194

表示のプログラミング

Loader の代わりに ProLoader を使用するためのコードの更新
ProLoader は Loader クラスをミラーするので、コード内で 2 つのクラスを簡単に入れ替えることができます。以下の例
は、新しいクラスを使用するために既存のコードを更新する方法を示します。
import flash.display.Loader;import flash.events.Event;var l:Loader = new Loader();
addChild(l);l.contentLoaderInfo.addEventListener(Event.COMPLETE, loadComplete);l.load("my.swf");function loadComplete(e:Event) {trace('load complete!');}このコードは、次のように ProLoader を使用するように更新することができます。
import fl.display.ProLoader;import flash.events.Event;var l:ProLoader = new ProLoader();
addChild(l);l.contentLoaderInfo.addEventListener(Event.COMPLETE, loadComplete);l.load("my.swf");function loadComplete(e:Event) {trace('load complete!');}

表示オブジェクトの例：SpriteArranger
Flash Player 9 以降、Adobe AIR 1.0 以降
SpriteArranger サンプルアプリケーションは、『ActionScript 3.0 の学習』で個別に説明した Geometric Shapes サンプル
アプリケーションを基に作成されます。

SpriteArranger サンプルアプリケーションは、表示オブジェクトの操作に関する次のような概念を示しています。

•

表示オブジェクトクラスの拡張•

表示リストへのオブジェクトの追加•

表示オブジェクトのレイヤーと表示オブジェクトコンテナの操作•

表示オブジェクトイベントへの応答•

表示オブジェクトのプロパティとメソッドの使用

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。SpriteArranger アプリケーションのファイルは、Examples/SpriteArranger フォルダーに入っています。このアプリケーションは次のファイルで構成されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

195

表示のプログラミング

ファイル

説明

Flash（FLA）または Flex（MXML）のメインアプリ

SpriteArranger.mxml

ケーションファイル。

またはSpriteArranger.fla
com/example/programmingas3/SpriteArranger/CircleSprite.as

画面上で円をレンダリングする Sprite オブジェクトの型を定義するクラス。

com/example/programmingas3/SpriteArranger/DrawingCanvas.as

キャンバスを定義するクラス。キャンバスは、GeometricSprite オブジェクトを格納する表示オブジェクトコンテナです。

com/example/programmingas3/SpriteArranger/SquareSprite.as

画面上で四角形をレンダリングする Sprite オブジェ
クトの型を定義するクラス。

com/example/programmingas3/SpriteArranger/TriangleSprite.as

画面上で三角形をレンダリングする Sprite オブジェ
クトの型を定義するクラス。

com/example/programmingas3/SpriteArranger/GeometricSprite.as

Sprite オブジェクトを拡張するクラス。画面上のシェイプを定義するのに使用されます。CircleSprite、

SquareSprite、および TriangleSprite は、それぞれこのクラスを拡張します。

com/example/programmingas3/geometricshapes/IGeometricShape.as

すべての図形クラスによって実装されるメソッドを定義する基本インターフェイス。

com/example/programmingas3/geometricshapes/IPolygon.as

複数の辺を持つ図形クラスによって実装されるメソッドを定義するインターフェイス。

com/example/programmingas3/geometricshapes/RegularPolygon.as

シェイプの中心から対称の位置に等しい長さの辺を有する一種の幾何学図形。

com/example/programmingas3/geometricshapes/Circle.as

円を定義する一種の幾何学図形。

com/example/programmingas3/geometricshapes/EquilateralTriangle.as

正三角形を定義する RegularPolygon のサブクラス。

com/example/programmingas3/geometricshapes/Square.as

正四角形を定義する RegularPolygon のサブクラス。

com/example/programmingas3/geometricshapes/GeometricShapeFactory.as

指定された種類およびサイズでシェイプを作成するための「ファクトリメソッド」を含むクラス。

SpriteArranger クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
SpriteArranger アプリケーションを使用して、画面上の「キャンバス」に、各種表示オブジェクトを追加することができます。

DrawingCanvas クラスは、ユーザーが画面上のシェイプを追加できる描画領域、すなわち表示オブジェクトコンテナのタイプを定義します。これらの画面上のシェイプは、GeometricSprite クラスのいずれかのサブクラスのインスタンスです。
DrawingCanvas クラス
Flex では、Container オブジェクトに追加されるすべての子表示オブジェクトのクラスは mx.core.UIComponent クラスの子孫でなければなりません。このアプリケーションは、SpriteArranger.mxml ファイルの MXML コードに定義されるよ
うに、DrawingCanvas クラスのインスタンスを mx.containers.VBox オブジェクトの子として追加します。この継承は次のように DrawingCanvas クラス宣言で定義されます。
public class DrawingCanvas extends UIComponent

UIComponent クラスは、DisplayObject、DisplayObjectContainer、および Sprite の各クラスから継承し、
DrawingCanvas クラスのコードはこれらのクラスのメソッドとプロパティを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

196

表示のプログラミング

DrawingCanvas クラスは Sprite クラスを拡張するもので、この継承は次のように DrawingCanvas クラス宣言で定義されます。
public class DrawingCanvas extends Sprite

Sprite クラスは DisplayObjectContainer クラスと DisplayObject クラスのサブクラスであり、DrawingCanvas クラス
は、これらのクラスのメソッドとプロパティを使用します。

DrawingCanvas() コンストラクターメソッドは、Rectangle オブジェクト、bounds を設定します。bounds は、後でキャン
バスのアウトラインを描画するために使用されるプロパティです。その後、コンストラクターメソッドは次のようにして
initCanvas() メソッドを呼び出します。
this.bounds = new Rectangle(0, 0, w, h);initCanvas(fillColor, lineColor);

次の例に示すように、initCanvas() メソッドは DrawingCanvas オブジェクトの各種プロパティを定義します。これらのプ
ロパティは、コンストラクター関数へ引数として渡されたものです。
this.lineColor = lineColor;this.fillColor = fillColor;this.width = 500;
this.height = 200;

その後、initCanvas() メソッドは drawBounds() メソッドを呼び出し、そのメソッドにより、DrawingCanvas クラスのgraphics プロパティを使用してキャンバスが描画されます。graphics プロパティは、Shape クラスから継承されます。
this.graphics.clear();this.graphics.lineStyle(1.0, this.lineColor, 1.0);
this.graphics.beginFill(this.fillColor, 1.0);
this.graphics.drawRect(bounds.left - 1,
bounds.top - 1,
bounds.width + 2,
bounds.height + 2);
this.graphics.endFill();

次に示す DrawingCanvas クラスの追加メソッドは、アプリケーションに対するユーザーの操作に基づいて呼び出されます。

• addShape() および describeChildren() メソッド。これらについては、197 ページの「キャンバスへの表示オブジェクトの追加」で説明します。

• moveToBack()、moveDown()、moveToFront()、および moveUp() メソッド。これらについては、199 ページの「表示オブジェクトのレイヤーの再配置」で説明します。

• onMouseUp() メソッド。これについては、198 ページの「表示オブジェクトのクリックとドラッグ」で説明します。
GeometricSprite クラスとそのサブクラス
ユーザーがキャンバスに追加できる表示オブジェクトは、GeometricSprite クラスの次のいずれかのサブクラスのインスタンスです。

• CircleSprite• SquareSprite• TriangleSprite
GeometricSprite クラスは、flash.display.Sprite クラスを拡張します。
public class GeometricSprite extends Sprite

GeometricSprite クラスは、すべての GeometricSprite オブジェクトに共通するいくつかのプロパティを含んでいます。それらは、関数に渡されたパラメーターに基づいてコンストラクター関数の中で設定されます。次に、例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

197

表示のプログラミング

this.size = size;
this.lineColor = lColor;this.fillColor = fColor;

GeometricSprite クラスの geometricShape プロパティは、IGeometricShape インターフェイスを定義し、このインターフェイスはシェイプの数学プロパティを定義しますが、ビジュアルプロパティは定義しません。IGeometricShape イン
ターフェイスを実装するクラスは、『ActionScript 3.0 の学習』で説明している GeometricShapes サンプルアプリケー
ションで定義されています。

GeometricSprite クラスは drawShape() メソッドを定義し、このメソッドは GeometricSprite の各サブクラス内のオーバーライド定義の中でさらに改良されます。詳しくは、この後の「キャンバスへの表示オブジェクトの追加」の節を参照してく
ださい。

GeometricSprite クラスは、次のメソッドも備えています。

• onMouseDown() および onMouseUp() メソッド。これらについては、198 ページの「表示オブジェクトのクリックとドラッグ」で説明します。

• showSelected() および hideSelected() メソッド。これらについては、198 ページの「表示オブジェクトのクリックとドラッ
グ」で説明します。

キャンバスへの表示オブジェクトの追加
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーが「シェイプの追加」ボタンをクリックすると、アプリケーションは DrawingCanvas クラスの addShape() メ
ソッドを呼び出します。アプリケーションは、次の例に示すように、新しい GeometricSprite のインスタンス化するために、いずれかの GeometricSprite サブクラスの適切なコンストラクター関数を呼び出します。
public function addShape(shapeName:String, len:Number):void{
var newShape:GeometricSprite;
switch (shapeName){case "Triangle":
newShape = new TriangleSprite(len);break;
case "Square":newShape = new SquareSprite(len);break;
case "Circle":
newShape = new CircleSprite(len);break;}
newShape.alpha = 0.8;
this.addChild(newShape);}

各コンストラクターメソッドは drawShape() メソッドを呼び出し、このメソッドは、Sprite クラスから継承したクラスのgraphics プロパティを使用して適切なベクターグラフィックを描画します。例えば、CircleSprite クラスの drawShape() メ
ソッドには、次のコードが含まれています。
this.graphics.clear();this.graphics.lineStyle(1.0, this.lineColor, 1.0);
this.graphics.beginFill(this.fillColor, 1.0);
var radius:Number = this.size / 2;
this.graphics.drawCircle(radius, radius, radius);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

198

表示のプログラミング

addShape() 関数の最後から 2 番目の行は、DisplayObject クラスから継承した表示オブジェクトの alpha プロパティを設定します。これにより、キャンバスに追加される表示オブジェクトはわずかに透明になり、ユーザーはその背後にあるオブジェクトを見ることができます。
addChild() メソッドの最後の行は、既に表示リストに載っている新しい表示オブジェクトを DrawingCanvas クラスのイン
スタンスの子リストに追加します。これにより、新しい表示オブジェクトがステージに表示されます。
アプリケーションのインターフェイスには、selectedSpriteTxt と outputTxt の 2 つのテキストフィールドが含まれています。
これらのテキストフィールドのテキストプロパティは、キャンバスに追加されるかユーザーによって選択された

GeometricSprite オブジェクトに関する情報で更新されます。GeometricSprite クラスは、次のように toString() メソッドを
オーバーライドすることにより、この情報報告タスクを処理します。
public override function toString():String{
return this.shapeType + " of size " + this.size + " at " + this.x + ", " + this.y;}shapeType プロパティは、各 GeometricSprite サブクラスのコンストラクターメソッドの中で、適切な値に設定されます。
例えば、toString() メソッドは、DrawingCanvas インスタンスに新たに追加された CircleSprite インスタンスの次の値を返す場合があります。
Circle of size 50 at 0, 0

DrawingCanvas クラスの describeChildren() メソッドは、DisplayObjectContainer クラスから継承した numChildren プロ
パティを使用して for ループの限度を設定し、キャンバスの子リストをループします。このメソッドは、次のように、それぞれの子をリストしたストリングを生成します。
var desc:String = "";var child:DisplayObject;for (var i:int=0; i < this.numChildren; i++){child = this.getChildAt(i);desc += i + ": " + child + '\n';}結果のストリングは、outputTxt テキストフィールドの text プロパティを設定するために使用されます。

表示オブジェクトのクリックとドラッグ
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーが GeometricSprite インスタンスをクリックすると、アプリケーションは onMouseDown() イベントハンドラーを呼び出します。次に示すように、このイベントハンドラーは GeometricSprite クラスのマウスダウンイベントを受け取るように設定されています。
this.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);

次に、onMouseDown() メソッドは GeometricSprite オブジェクトの showSelected() メソッドを呼び出します。このオブジェクトに対してこのメソッドが最初に呼び出された場合は、selectionIndicator という名前の新しい Shape オブジェクトが作成され、次のように、その Shape オブジェクトの graphics プロパティを使用して赤いハイライトの矩形が描画されます。
this.selectionIndicator = new Shape();this.selectionIndicator.graphics.lineStyle(1.0, 0xFF0000, 1.0);
this.selectionIndicator.graphics.drawRect(-1, -1, this.size + 1, this.size + 1);
this.addChild(this.selectionIndicator);

onMouseDown() メソッドの呼び出しが最初でない場合、このメソッドは、単に DisplayObject クラスから継承した
selectionIndicator シェイプの visible プロパティを次のように設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

199

表示のプログラミング

this.selectionIndicator.visible = true;

hideSelected() メソッドは、前に選択されたオブジェクトの selectionIndicator シェイプを、その visible プロパティを false に設定することによって非表示にします。
また、onMouseDown() イベントハンドラーは、次のコードを含んでいる startDrag() メソッドも呼び出します。このメソッドは、Sprite クラスから継承されたものです。
var boundsRect:Rectangle = this.parent.getRect(this.parent);
boundsRect.width -= this.size;
boundsRect.height -= this.size;
this.startDrag(false, boundsRect);

これにより、ユーザーは選択したオブジェクトを、キャンバスの boundsRect 矩形によって設定された境界内でドラッグできます。
ユーザーがマウスボタンを離すと、mouseUp イベントが送出されます。DrawingCanvas のコンストラクターメソッドは、次のイベントリスナーを設定します。
this.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);

このイベントリスナーは、個々の GeometricSprite オブジェクト用でなく、DrawingCanvas オブジェクト用に設定されます。なぜなら、GeometricSprite オブジェクトは、ドラッグされた場合、マウスボタンが離されたときに、別の表示オブジェクト（別の GeometricSprite オブジェクト）の背後で終了する可能性があるからです。前景の表示オブジェクトは、マウスアップイベントを受け取りますが、ユーザーがドラッグしている表示オブジェクトは、それを受け取りません。

DrawingCanvas オブジェクトにリスナーを追加すると、そのイベントが常に確実に処理されます。
onMouseUp() メソッドは GeometricSprite オブジェクトの onMouseUp() メソッドを呼び出し、後者のメソッドは
GeometricSprite オブジェクトの stopDrag() メソッドを呼び出します。

表示オブジェクトのレイヤーの再配置
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションのユーザーインターフェイスには、Move Back、Move Down、Move Up、および Move to Front というラベルの付いたボタンが含まれます。ユーザーがこれらのボタンをクリックすると、アプリケーションはDrawingCanvas クラスの対応するメソッド（moveToBack()、moveDown()、moveUp()、または moveToFront()）を呼び出します。例えば、moveToBack() メソッドには次のコードが含まれています。
public function moveToBack(shape:GeometricSprite):void{
var index:int = this.getChildIndex(shape);
if (index > 0){
this.setChildIndex(shape, 0);}}

このメソッドは、DisplayObjectContainer クラスから継承された setChildIndex() メソッドを使用して、表示オブジェクト
を DrawingCanvas インスタンス（this）の子リスト内のインデックス位置 0 に位置付けます。

moveDown() メソッドもほとんど同じ働きをしますが、次のように、DrawingCanvas インスタンスの子リスト内で表示オ
ブジェクトのインデックス位置を 1 ずつデクリメントする点が異なります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

200

表示のプログラミング

public function moveDown(shape:GeometricSprite):void{
var index:int = this.getChildIndex(shape);
if (index > 0){
this.setChildIndex(shape, index - 1);}}

moveUp() および moveToFront() メソッドは、moveToBack() および moveDown() メソッドと同様の働きをします。

最終更新日 2015/10/14

201

第 11 章：ジオメトリの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
flash.geom パッケージには、ポイント、矩形、変換マトリックスなどのジオメトリオブジェクトを定義するクラスがあります。これらのクラスは、他のクラスで使用されるオブジェクトのプロパティを定義する際に使用します。

関連項目

flash.geom パッケージ

ジオメトリの基本
Flash Player 9 以降、Adobe AIR 1.0 以降
flash.geom パッケージには、ポイント、矩形、変換マトリックスなどのジオメトリオブジェクトを定義するクラスがあります。これらのクラス自体は、必ずしも機能を提供するものではなく、他のクラスで使用されるオブジェクトのプロパティを定義する際に使用します。
すべてのジオメトリクラスは、画面上の位置は 2 次元の面で表されるという概念に基づいています。画面は、水平（x）軸と垂直（y）軸を持つ平面のグラフのように扱われます。画面上の任意の位置（ポイント）は、x 値と y 値の組み合わせ、つまり座標で表すことができます。
ステージなどのすべての表示オブジェクトは、独自の「座標空間」を持っています。この座標空間はオブジェクト自体のグ
ラフで、子表示オブジェクトや描画などが配置されます。「原点」は座標位置 0, 0（x 軸と y 軸が交わる座標）にあり、表示
オブジェクトの左上隅に配置されます。この原点の位置はステージには常に当てはまりますが、他の表示オブジェクトには当てはまらない場合もあります。x 軸の値が大きくなるほど右へ、小さくなるほど左へ移動します。原点の左側では x 座標
は負の値になります。ただし、通常の座標系とは異なり、Flash ランタイムでは y 軸上の座標値が大きくなるほど画面の下へ、小さくなるほど上へ移動します。原点の上側では、y 座標は負の値になります。ステージの左上隅が座標空間の原点なので、ステージ上のほとんどのオブジェクトは x 座標が 0 より大きくなり、幅はステージよりも小さくなります。また、そのオブジェクトの y 座標は 0 よりも大きくなり、高さはステージよりも小さくなります。
座標空間の個々のポイントを表すには、Point クラスのインスタンスを使用します。座標空間で矩形の領域を表すには、Rectangle インスタンスを作成します。上級ユーザーの場合は、Matrix インスタンスを使用して、表示オブジェクトに複数
変換または複合変換を適用できます。回転、位置の変更、拡大／縮小倍率の変更などの多くの単純な変換は、オブジェクトのプロパティを使用して表示オブジェクトに直接適用できます。表示オブジェクトのプロパティを使用した変換の適用について詳しくは、165 ページの「表示オブジェクトの操作」を参照してください。
重要な概念と用語
次の参照リストに、ジオメトリの重要な用語を示します。
直交座標 座標は一般に 2 つの数値で表されます（5, 12 や 17, -23 など）。この 2 つの数値はそれぞれ、x 座標と y 座標です。
座標空間 表示オブジェクトに含まれる座標グラフで、子エレメントがここに配置されます。
原点 座標空間で x 軸と y 軸が交わる点。このポイントの座標は 0, 0 です。
ポイント 座標空間内の 1 つの場所。ActionScript で使用する 2 次元座標系では、x 軸と y 軸上の位置（点の座標）によって点が定義されます。
基準点 表示オブジェクトの座標空間の原点（0, 0 座標）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

202

ジオメトリの操作

拡大／縮小 オブジェクトの元のサイズを基準とするサイズです。拡大／縮小とは、オブジェクトを伸縮させてサイズを変更することを意味します。
平行移動 ポイント座標を 1 つの座標空間から他の座標空間に変更すること。
変換 図形の視覚的特性を調整すること。オブジェクトの回転、尺度の変更、シェイプの傾斜や歪み、色の変更など。

X 軸 ActionScript で使用する 2 次元座標系の水平軸。
Y 軸 ActionScript で使用する 2 次元座標系の垂直軸。

Point オブジェクトの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Point オブジェクトは、座標の直交ペアを定義します。2 次元の座標系において、水平軸を表す x と垂直軸を表す y により 1
つのポイントを表現します。

Point オブジェクトを定義する際は、次のように x プロパティと y プロパティを設定します。
import flash.geom.*;var pt1:Point = new Point(10, 20); // x == 10; y == 20
var pt2:Point = new Point();
pt2.x = 10;
pt2.y = 20;

2 つのポイント間の距離の検索
Flash Player 9 以降、Adobe AIR 1.0 以降
Point クラスの distance() メソッドを使用すると、同じ座標空間内にある 2 つのポイント間について距離を調べることができます。例えば、次のコードでは、同じ表示オブジェクトコンテナ内にある 2 つの表示オブジェクト circle1 および circle2 が持つ基準点間の距離を取得します。
import flash.geom.*;var pt1:Point = new Point(circle1.x, circle1.y);var pt2:Point = new Point(circle2.x, circle2.y);var distance:Number = Point.distance(pt1, pt2);

座標空間の変換Flash Player 9 以降、Adobe AIR 1.0 以降
2 つの表示オブジェクトがそれぞれ異なる表示オブジェクトコンテナ内にある場合は、それぞれが異なる座標空間に属している可能性があります。DisplayObject クラスの localToGlobal() メソッドを使用すると、それらの座標を共通のグローバルな座標空間（ステージ座標）に変換できます。例えば、次のコードでは、別々の表示オブジェクトコンテナ内にある 2 つの表示オブジェクト circle1 および circle2 が持つ基準点間の距離を取得します。
import flash.geom.*;var pt1:Point = new Point(circle1.x, circle1.y);pt1 = circle1.localToGlobal(pt1);
var pt2:Point = new Point(circle2.x, circle2.y);pt2 = circle2.localToGlobal(pt2);
var distance:Number = Point.distance(pt1, pt2);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

203

ジオメトリの操作同様に、ステージ上の特定の点から表示オブジェクト target の基準点までの距離を調べるには、DisplayObject クラスのlocalToGlobal() メソッドを使用します。
import flash.geom.*;var stageCenter:Point = new Point();
stageCenter.x = this.stage.stageWidth / 2;stageCenter.y = this.stage.stageHeight / 2;
var targetCenter:Point = new Point(target.x, target.y);targetCenter = target.localToGlobal(targetCenter);var distance:Number = Point.distance(stageCenter, targetCenter);

表示オブジェクトの指定された角度と距離の移動
Flash Player 9 以降、Adobe AIR 1.0 以降
移動距離と角度を指定してオブジェクトを移動するには、Point クラスの polar() メソッドを使用します。例えば、次のコードでは、myDisplayObject オブジェクトを 60 度の方向に 100 ピクセル分だけ移動します。
import flash.geom.*;var distance:Number = 100;
var angle:Number = 2 * Math.PI * (90 / 360);
var translatePoint:Point = Point.polar(distance, angle);
myDisplayObject.x += translatePoint.x;
myDisplayObject.y += translatePoint.y;

Point クラスのその他の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Point オブジェクトは次のメソッドおよびプロパティで使用できます。
クラス

メソッドまたはプロパティ

説明

DisplayObjectContainer

areInaccessibleObjectsUnderPoint()getObjectsUnderPoint()

表示オブジェクトコンテナ内のポイントに存在するオブジェクトのリストを返すために使用します。

BitmapData

hitTest()

BitmapData オブジェクト内のピクセルと、衝突のチェックに使用するポイントを定義するために使用します。

BitmapData

操作の対象とする長方形の位置を定義するために使用します。

applyFilter()copyChannel()merge()
paletteMap()
pixelDissolve()
threshold()

MatrixdeltaTransformPoint()

変換を適用するポイントを定義するために使用します。

transformPoint()

Rectangle

これらのプロパティを定義するために使用します。

bottomRightsize
topLeft

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

204

ジオメトリの操作

Rectangle オブジェクトの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Rectangle オブジェクトは、矩形領域を定義します。Rectangle オブジェクトには、位置（左上隅の x 座標と y 座標で定義される）と、width プロパティ、height プロパティがあります。新しい Rectangle オブジェクトに対してこれらのプロパティを指定するには、次のように Rectangle() コンストラクターを呼び出します。
import flash.geom.Rectangle;
var rx:Number = 0;
var ry:Number = 0;
var rwidth:Number = 100;var rheight:Number = 50;
var rect1:Rectangle = new Rectangle(rx, ry, rwidth, rheight);

Rectangle オブジェクトのサイズ変更と再配置
Flash Player 9 以降、Adobe AIR 1.0 以降
Rectangle オブジェクトをサイズ変更および移動するには多数の方法があります。
x および y プロパティを変更すると、直接に Rectangle オブジェクトの位置を移動できます。Rectangle オブジェクトの幅と高さをこの方法で変更しても効果はありません。
import flash.geom.Rectangle;
var x1:Number = 0;
var y1:Number = 0;
var width1:Number = 100;var height1:Number = 50;
var rect1:Rectangle = new Rectangle(x1, y1, width1, height1);
trace(rect1) // (x=0, y=0, w=100, h=50)
rect1.x = 20;
rect1.y = 30;
trace(rect1); // (x=20, y=30, w=100, h=50)

次のコードで示すように、Rectangle オブジェクトの left または top プロパティを変更すると、長方形の位置が移動します。
長方形の x および y プロパティは、それぞれ left および top プロパティに対応します。ただし、Rectangle オブジェクトの左下隅の位置は変化せず、その代わりに長方形のサイズが変化します。
import flash.geom.Rectangle;
var x1:Number = 0;
var y1:Number = 0;
var width1:Number = 100;var height1:Number = 50;
var rect1:Rectangle = new Rectangle(x1, y1, width1, height1);
trace(rect1) // (x=0, y=0, w=100, h=50)
rect1.left = 20;
rect1.top = 30;
trace(rect1); // (x=20, y=30, w=80, h=20)

同様に、次の例で示すように、Rectangle オブジェクトの bottom または right プロパティを変更しても、左上隅の位置は変化しません。それに応じて長方形のサイズが変化します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

205

ジオメトリの操作

import flash.geom.Rectangle;
var x1:Number = 0;
var y1:Number = 0;
var width1:Number = 100;var height1:Number = 50;
var rect1:Rectangle = new Rectangle(x1, y1, width1, height1);
trace(rect1) // (x=0, y=0, w=100, h=50)
rect1.right = 60;
trect1.bottom = 20;
trace(rect1); // (x=0, y=0, w=60, h=20)

次のように、Rectangle オブジェクトの offset() メソッドでも位置を移動できます。
import flash.geom.Rectangle;
var x1:Number = 0;
var y1:Number = 0;
var width1:Number = 100;var height1:Number = 50;
var rect1:Rectangle = new Rectangle(x1, y1, width1, height1);
trace(rect1) // (x=0, y=0, w=100, h=50)
rect1.offset(20, 30);
trace(rect1); // (x=20, y=30, w=100, h=50)

offsetPt() メソッドも同様に機能しますが、パラメーターとして x および y のオフセット値ではなく Point オブジェクトを指定します。

Rectangle オブジェクトの inflate() メソッドに dx および dy の 2 つのパラメーターを指定してサイズを変更することもできます。dx パラメーターは、長方形の左辺と右辺の移動量（中心に対して）をピクセル数で表します。dy パラメーターは、長方形の上辺と下辺の移動量（中心に対して）をピクセル数で表します。
import flash.geom.Rectangle;
var x1:Number = 0;
var y1:Number = 0;
var width1:Number = 100;var height1:Number = 50;
var rect1:Rectangle = new Rectangle(x1, y1, width1, height1);
trace(rect1) // (x=0, y=0, w=100, h=50)
rect1.inflate(6,4);
trace(rect1); // (x=-6, y=-4, w=112, h=58)

inflatePt() メソッドも同様に機能しますが、パラメーターとして dx および dy の値ではなく Point オブジェクトを指定します。

Rectangle オブジェクトの結合と交差の検索
Flash Player 9 以降、Adobe AIR 1.0 以降
union() メソッドは、2 つの矩形の境界で形成された矩形領域の検索に使用します。
import flash.display.*;
import flash.geom.Rectangle;
var rect1:Rectangle = new Rectangle(0, 0, 100, 100);
trace(rect1); // (x=0, y=0, w=100, h=100)
var rect2:Rectangle = new Rectangle(120, 60, 100, 100);
trace(rect2); // (x=120, y=60, w=100, h=100)
trace(rect1.union(rect2)); // (x=0, y=0, w=220, h=160)

intersection() メソッドは、2 つの矩形の重なり合う領域で形成される矩形領域の検索に使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

206

ジオメトリの操作

import flash.display.*;
import flash.geom.Rectangle;
var rect1:Rectangle = new Rectangle(0, 0, 100, 100);
trace(rect1); // (x=0, y=0, w=100, h=100)
var rect2:Rectangle = new Rectangle(80, 60, 100, 100);
trace(rect2); // (x=120, y=60, w=100, h=100)
trace(rect1.intersection(rect2)); // (x=80, y=60, w=20, h=40)

2 つの長方形に重なり合う部分があるかどうかを調べるには、intersects() メソッドを使用します。また、表示オブジェクトがステージ上の特定の領域内に配置されているかどうかを調べる場合にも intersects() メソッドを使用できます。次のコード
例では、circle オブジェクトを含んだ表示オブジェクトコンテナの座標空間がステージの座標空間と同じであることが前提となっています。この例は、intersects() メソッドを使用して、表示オブジェクト circle が target1 および target2 Rectangle オブジェクトで定義されたステージの指定された領域と交差しているかどうかを判断する方法を示しています。
import flash.display.*;
import flash.geom.Rectangle;
var circle:Shape = new Shape();circle.graphics.lineStyle(2, 0xFF0000);circle.graphics.drawCircle(250, 250, 100);
addChild(circle);
var circleBounds:Rectangle = circle.getBounds(stage);var target1:Rectangle = new Rectangle(0, 0, 100, 100);
trace(circleBounds.intersects(target1)); // false
var target2:Rectangle = new Rectangle(0, 0, 300, 300);
trace(circleBounds.intersects(target2)); // true

同様に、2 つの表示オブジェクトの境界を示す矩形に重なり合う部分があるかどうかを調べる場合にも intersects() メソッドを使用できます。DisplayObject クラスの getRect() メソッドを使用すると、表示オブジェクトの線により境界範囲に挿入される空白を考慮することができます。

Rectangle オブジェクトのその他の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Rectangle オブジェクトは次のメソッドおよびプロパティで使用されます。
クラス

メソッドまたはプロパティ

説明BitmapData

applyFilter()、colorTransform()、copyChannel()、copyPixels()、draw()、drawWithQuality()、encode()、fillRect()、generateFilterRect()、getColorBoundsRect()、
getPixels()、merge()、paletteMap()、pixelDissolve()、
setPixels()、threshold()

BitmapData オブジェクトの領域を定義するパラメーターの型として使用します。

DisplayObject

getBounds()、getRect()、scrollRect、scale9Grid

プロパティのデータ型または返されるデータ型として使用します。

PrintJob

addPage()printArea パラメーターを定義するために使用します。

SpritestartDrag()bounds パラメーターを定義するために使用します。

TextField

getCharBoundaries()

戻り値型として使用します。

Transform

pixelBounds

データ型として使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

207

ジオメトリの操作

Matrix オブジェクトの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Matrix クラスは、2 つの座標空間の間におけるポイントのマッピング方法を決定する変換マトリックスを表します。
Matrix オブジェクトのプロパティを設定し、Matrix オブジェクトを Transform オブジェクトの matrix プロパティに適用
し、次に Transform オブジェクトを表示オブジェクトの transform プロパティとして適用することで、表示オブジェクトに対する各種グラフィック変換を実行できます。これらの変換機能には、平行移動（x と y の位置変更）、回転、拡大／縮小、傾斜などが含まれます。
マトリックスは、プロパティ（a、b、c、d、tx、ty）を調整して直接に定義することもできますが、createBox() メソッドを使用して定義する方が簡単です。このメソッドのパラメーターでは、作成するマトリックスに定義する拡大／縮小、回転、平行移動の効果を直接に定義できます。例えば、次のコードでは Matrix オブジェクトを作成して、水平方向に 2.0 倍、垂直方
向に 3.0 倍拡大し、45 度回転させて、右に 10 ピクセル、下に 20 ピクセル移動します。
var matrix:Matrix = new Matrix();
var scaleX:Number = 2.0;
var scaleY:Number = 3.0;
var rotation:Number = 2 * Math.PI * (45 / 360);
var tx:Number = 10;
var ty:Number = 20;
matrix.createBox(scaleX, scaleY, rotation, tx, ty);

Matrix オブジェクトの拡大／縮小、回転、平行移動のエフェクトは、scale()、rotate()、および translate() メソッドを使用して調整することもできます。これらのメソッドで指定した値は、既存の Matrix オブジェクトに設定されている値と組み合わされます。例えば、次のコードでは scale() と rotate() メソッドを 2 回呼び出しているので、Matrix オブジェクトは 4 倍に拡大して 60 度回転します。
var matrix:Matrix = new Matrix();
var rotation:Number = 2 * Math.PI * (30 / 360); // 30°
var scaleFactor:Number = 2;
matrix.scale(scaleFactor, scaleFactor);
matrix.rotate(rotation);
matrix.scale(scaleX, scaleY);matrix.rotate(rotation);
myDisplayObject.transform.matrix = matrix;

Matrix オブジェクトに傾斜変換を適用するには、オブジェクトの b または c プロパティをそれぞれ調整します。b プロパ
ティを調整するとマトリックスが垂直方向に傾斜し、c プロパティを調整するとマトリックスが水平方向に傾斜します。次のコードでは、myMatrix Matrix オブジェクトが垂直に 2 倍傾斜しています。
var skewMatrix:Matrix = new Matrix();
skewMatrix.b = Math.tan(2);myMatrix.concat(skewMatrix);

Matrix による変換は、表示オブジェクトの transform プロパティに適用できます。例えば、次のコードでは
myDisplayObject という表示オブジェクトにマトリックス変換を適用しています。
var matrix:Matrix = myDisplayObject.transform.matrix;
var scaleFactor:Number = 2;
var rotation:Number = 2 * Math.PI * (60 / 360); // 60°
matrix.scale(scaleFactor, scaleFactor);
matrix.rotate(rotation);
myDisplayObject.transform.matrix = matrix;

1 行目では、myDisplayObject 表示オブジェクトで使用される既存の変換マトリックスに Matrix オブジェクトが設定されます（myDisplayObject 表示オブジェクトの transformation プロパティの matrix プロパティ）。こうすることで、表示オブジェ
クトの現状の位置、拡大率、回転角をふまえた上に、Matrix クラスメソッドの実行による効果を累積的に適用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

208

ジオメトリの操作

注意：flash.geometry パッケージには ColorTransform クラスも含まれていますが、このクラスは Transform オブジェク
トの colorTransform プロパティを設定する際に使用するものです。幾何学変換には使用しないので、ここでは説明しません。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の ColorTransform クラスの項を参照
してください。

ジオメトリの例：マトリックス変換の表示オブジェクトへの適用
Flash Player 9 以降、Adobe AIR 1.0 以降
DisplayObjectTransformer サンプルアプリケーションには、Matrix クラスを使用して表示オブジェクトを変換する、次のような機能がいくつか示されます。

•

表示オブジェクトの回転•

表示オブジェクトの拡大／縮小•

表示オブジェクトの平行移動（再配置）•

表示オブジェクトの傾斜

このアプリケーションでは、マトリックス変換のパラメーターを次のように調整するためのインターフェイスが使用できます。

ユーザーが「Transform」ボタンをクリックすると、アプリケーションにより適切な変換が適用されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

209

ジオメトリの操作

元の表示オブジェクトと、-45° 回転し、50％拡大／縮小した表示オブジェクト

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。DisplayObjectTransformer アプ
リケーションのファイルは、Samples/DisplayObjectTransformer フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

DisplayObjectTransformer.mxml

Flash（FLA）または Flex（MXML）のメインアプリケーション
ファイル。

または

DisplayObjectTransformer.fla
com/example/programmingas3/geometry/MatrixTransformer.as

マトリックス変換を適用するためのメソッドが含まれているクラ
ス。

img/

アプリケーションが使用するサンプルイメージファイルが保存されているディレクトリ。

MatrixTransformer クラスの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
MatrixTransformer クラスには、Matrix オブジェクトの図形変換を適用する静的メソッドが含まれます。
transform() メソッド
transform() メソッドには、次の各パラメーターが含まれます。

• sourceMatrix — メソッドで変換される入力マトリックス• xScale と yScale — x と y の縮尺率
• dx と dy — x と y の変換ピクセル数• rotation — 回転度数
• skew — 傾斜率（％）• skewType — 傾斜の方向、「右」 または「左」
戻り値は、結果のマトリックスです。

transform() メソッドは、クラスの次の静的メソッドを呼び出します。

• skew()• scale()• translate()• rotate()

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

210

ジオメトリの操作

それぞれ、ソースマトリックスに変換を適用して返します。

skew() メソッド
skew() メソッドは、マトリックスの b および c プロパティを調整して、マトリックスを傾斜します。オプションのパラメー
ター unit によって、傾斜角度の定義に使用する単位が決まります。必要に応じて、メソッドは angle 値をラジアンに変換します。
if (unit == "degrees"){
angle = Math.PI * 2 * angle / 360;}
if (unit == "gradients"){
angle = Math.PI * 2 * angle / 100;}

傾斜変換を適用するために、skewMatrix Matrix オブジェクトが作成され、調整されます。最初は、次のように、同一のマトリックスです。
var skewMatrix:Matrix = new Matrix();

skewSide パラメーターによって、傾斜を適用する側が決まります。「right」 が設定されている場合、次のコードでマトリック
スの b プロパティが設定されます。
skewMatrix.b = Math.tan(angle);

それ以外の場合、次のように Matrix の c プロパティが調整され、下側が傾斜されます。
skewMatrix.c = Math.tan(angle);

次の例で示すように、2 つのマトリックスを連結することによって、結果の傾斜が既存のマトリックスに適用されます。
sourceMatrix.concat(skewMatrix);
return sourceMatrix;

scale () メソッド
次の例では、縮尺率がパーセントで指定されている場合、まず scale() メソッドで縮尺率を調整してから、マトリックスオブ
ジェクトの scale() メソッドを使用します。
if (percent){xScale = xScale / 100;yScale = yScale / 100;}sourceMatrix.scale(xScale, yScale);return sourceMatrix;

translate () メソッド
translate() メソッドは、次のようにマトリックスオブジェクトの translate() メソッドを呼び出し、単純に、dx および dy 平行移動係数を適用します。
sourceMatrix.translate(dx, dy);
return sourceMatrix;

rotate () メソッド
rotate() メソッドは、入力回転角度をラジアンに変換し（度またはグラデーションで指定されている場合）、マトリックスオ
ブジェクトの rotate() メソッドを呼び出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

211

ジオメトリの操作

if (unit == "degrees"){
angle = Math.PI * 2 * angle / 360;}
if (unit == "gradients"){
angle = Math.PI * 2 * angle / 100;}sourceMatrix.rotate(angle);
return sourceMatrix;

アプリケーションからの MatrixTransformer.transform() メソッドの呼び出しFlash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションには、ユーザーが変換パラメーターを指定するためのユーザーインターフェイスがあります。パラメー
ターが指定されると、次のように、パラメーターの値と表示オブジェクトの transform プロパティの matrix プロパティを

Matrix.transform() メソッドに渡します。
tempMatrix = MatrixTransformer.transform(tempMatrix,
xScaleSlider.value,
yScaleSlider.value,dxSlider.value,
dySlider.value,
rotationSlider.value,
skewSlider.value,
skewSide );次に、アプリケーションは戻り値を表示オブジェクトの transform プロパティの matrix プロパティに適用し、変換がトリガーされます。
img.content.transform.matrix = tempMatrix;

最終更新日 2015/10/14

212

第 12 章：描画 API の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
イメージやアートワークの読み込みは重要ですが、描画 API という機能を使用すると、ActionScript で線やシェイプを描画できます。これにより、コンピューター上で白いキャンバスに任意のイメージを作成するアプリケーションを起動することもできるようになります。独自のグラフィックを作成する機能により、アプリケーションの可能性が広がります。ここで説明する方法を使用すると、描画プログラムの作成、アニメーション化されたインタラクティブアートの作成、プログラムを使用した独自のユーザーインターフェイスエレメントの作成をはじめ、様々な処理を行うことができます。

関連項目

flash.display.Graphics

描画 API の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
描画 API は、ActionScript に組み込まれた機能の名前です。この機能を使用すると、線、曲線、シェイプ、塗り、グラ
デーションなどのベクターグラフィックを作成し、ActionScript でそれらを画面上に表示できます。
flash.display.Graphics クラスがこの機能を提供します。Shape、Sprite、または MovieClip の各クラスに定義された
graphics プロパティで、任意の Shape、Sprite、または MovieClip インスタンスに対して ActionScript を使用して描画できます。各クラスの graphics プロパティは、実際は Graphics クラスのインスタンスです。
コードを使用した描画に不慣れな場合、Graphics クラスには、円、楕円、矩形、および角の丸い矩形などの一般的なシェ
イプを簡単に描画するためのいくつかのメソッドがあります。それらは表示されない線としても、塗りつぶされたシェイプとしても描画できます。より高度な機能が必要な場合は、Graphics クラスには線および二次ベジェ曲線を描画するためのメ
ソッドもあり、Math クラスの三角関数と組み合わせて、任意のシェイプを作成できます。

Flash ランタイム（Flash Player 10 および Adobe AIR 1.5 以降など）では、プログラムから 1 つのコマンドでシェイプ全体を描画できる描画用 API が追加されています。「描画 API の使用の基礎」で説明されている Graphics クラスおよびタスクについて理解したなら、223 ページの「描画 API の高度な使用」に進み、これらの描画 API の機能についてさらに学習
してください。
重要な概念と用語
次の参照リストに、API の描画で使われる重要な用語を示します。
アンカーポイント 二次ベジェ曲線の 2 つの端点の 1 つ。
コントロールポイント 二次ベジェ曲線の方向と量を定義するポイント。曲線はコントロールポイントを通りません。コント
ロールポイントに引き付けられているような曲線が描画されます。
座標空間 表示オブジェクトに含まれる座標グラフで、子エレメントがここに配置されます。
塗り 色で塗りつぶされた輪郭のあるシェイプの内側の単色の部分、または輪郭のないシェイプ全体。
グラデーション ある色から別の 1 つ以上の色への段階的な変化を含む色（単色とは対照的な概念）。
ポイント 座標空間内の 1 つの場所。ActionScript で使用する 2 次元座標系では、ポイントは x 軸と y 軸における場所（ポイントの座標）によって定義されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

213

描画 API の使用

二次ベジェ曲線 特定の数式で定義される一種の曲線。この種の曲線のシェイプは、アンカーポイント（曲線の端点）の位置と、曲線の量と方向を定義するコントロールポイントの位置を基づいて計算されます。
拡大／縮小 オブジェクトの元のサイズを基準とするサイズです。拡大／縮小とは、オブジェクトを伸縮させてサイズを変更することを意味します。
境界線 シェイプの輪郭の、色で塗りつぶされた線の部分。または塗りのないシェイプの輪郭。
平行移動 ポイント座標を 1 つの座標空間から他の座標空間に変更すること。

X 軸 ActionScript で使用する 2 次元座標系の水平軸。
Y 軸 ActionScript で使用する 2 次元座標系の垂直軸。

Graphics クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
Shape、Sprite、および MovieClip の各オブジェクトには、Graphics クラスのインスタンスである graphics プロパティがあります。Graphics クラスには、線、塗り、およびシェイプを描画するためのプロパティおよびメソッドがあります。表示
オブジェクトを、コンテンツを描画するキャンバスとしてのみ使用する場合は、Shape インスタンスを使用します。Shape
インスタンスは、他の表示オブジェクトよりも描画の性能が優れています。Sprite クラスや MovieClip クラスにある追加機
能によるオーバーヘッドがないためです。表示オブジェクト上にグラフィックコンテンツを描画して、他の表示オブジェク
トも含める場合は、Sprite インスタンスを使用します。様々なタスクにどの表示オブジェクトを使用するかを判断する方法について詳しくは、164 ページの「DisplayObject サブクラスの選択」を参照してください。

線と曲線の描画
Flash Player 9 以降、Adobe AIR 1.0 以降
Graphics インスタンスを使用して行うすべての描画は、線と曲線の基本的な描画に基づいています。そのため、すべてのActionScript 描画は同じ一連の手順で実行される必要があります。

•

線と塗りのスタイルの定義•

最初の描画位置の設定•

線、曲線、およびシェイプの描画（オプションで、描画ポイントの移動）•

塗りの作成の完了（必要な場合）

線と塗りのスタイルの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
Shape、Sprite、または MovieClip インスタンスの graphics プロパティを使用して描画するには、まず、描画に使用するス
タイル（線のサイズと色、塗りの色）を定義する必要があります。Adobe ｮ Flash ｮ Professional などの描画アプリケーショ
ンで描画ツールを使用するときと同様に、ActionScript を使用して描画するときも、境界線や塗りの色の有無を指定して描画できます。境界線の外観は lineStyle() メソッドまたは lineGradientStyle() メソッドを使用して指定します。単色の線を作成するには lineStyle() メソッドを使用します。このメソッドを呼び出す場合に指定する最も一般的な値は、最初の 3 つのパラメーターである、線の太さ、色、およびアルファです。例えば、次のコード行は、myShape という名前の Shape に、線の太さが 2 ピクセルで、色が赤（0x990000）、不透明度が 75 % の線を描画するよう指定しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド214

描画 API の使用

myShape.graphics.lineStyle(2, 0x990000, .75);

アルファパラメーターのデフォルト値は 1.0（100%）であるため、完全に不透明な線を描画する場合はこのパラメーターを指定しないこともできます。lineStyle() メソッドは、ピクセルのヒンティングと拡大／縮小モードの 2 つの追加パラメーターも受け取ります。これらのパラメーターの使用方法について詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファ
レンスガイド』の Graphics.lineStyle() メソッドの説明を参照してください。
グラデーションの線を作成するには、lineGradientStyle() メソッドを使用します。このメソッドについては、216 ページの「グラデーションの線と塗りの作成」を参照してください。
塗りのシェイプを作成する場合、描画を開始する前に、beginFill() メソッド、beginGradientFill() メソッド、beginBitmapFill()
メソッド、または beginShaderFill() メソッドを呼び出します。これらのメソッドの中で最も基本的な beginFill() メソッドは、塗りの色と塗りの色のアルファ値（オプション）の 2 つのパラメーターを受け取ります。例えば、単色の緑の塗りでシェイプを描画するには、次のコードを使用します（myShape という名前のオブジェクトに描画すると仮定）。
myShape.graphics.beginFill(0x00FF00);

塗りメソッドを呼び出すと、新しい塗りを開始する前に、暗黙的に前の塗りを終了します。境界線のスタイルを指定したメ
ソッドを呼び出すと、前の境界線が置き換えられますが、前に指定した塗りは変更されません。逆の場合も同様です。
線のスタイルと塗りのプロパティを指定したら、次に描画の開始点を指定します。Graphics インスタンスには、用紙上のペン先のような描画ポイントがあります。描画ポイントが位置するところから、次の描画アクションが開始されます。初期状態
では、Graphics オブジェクトは、描画するオブジェクトの座標空間のポイント 0, 0 という描画ポイントから描画を開始します。別のポイントから描画を開始するには、まず moveTo() メソッドを呼び出してから、いずれかの描画メソッドを呼び出します。これは、ペン先を用紙から上げて新しい場所に移動するのと似ています。
描画ポイントを適切な場所に配置してから、lineTo() メソッド（直線の描画）や curveTo() メソッド（曲線の描画）に対する一連の呼び出しを使用して描画します。
描画中はいつでも moveTo() メソッドを呼び出して、描画せずに描画ポイントを新しい位置に移動することができます。

塗りの色を指定している場合、描画中に endFill() メソッドを呼び出して塗りを終了するように指定できます。閉じたシェイ
プを描画していない場合（つまり、endFill() を呼び出したときに描画ポイントがそのシェイプの開始点にない場合）、endFill() メソッドを呼び出した時点で、現在の描画ポイントから最後に moveTo() 呼び出しで指定した位置まで自動的に直線が描画され、閉じたシェイプが描画されます。塗りを開始して endFill() を呼び出していない場合、beginFill()（または他のいずれかの塗りメソッド）を呼び出すと、現在の塗りが終了し、新しい塗りが開始されます。

直線の描画
Flash Player 9 以降、Adobe AIR 1.0 以降
lineTo() メソッドを呼び出すと、Graphics オブジェクトは現在の描画ポイントからこのメソッド呼び出しの 2 つのパラメー
ターで指定した座標まで、指定した線のスタイルで直線を描画します。例えば、次のコード行では、描画ポイントをポイン
ト 100, 100 に配置し、ポイント 200, 200 まで線を描画します。
myShape.graphics.moveTo(100, 100);
myShape.graphics.lineTo(200, 200);

次の例では、高さ 100 ピクセルの赤と緑の三角形を描画します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

215

描画 API の使用

var triangleHeight:uint = 100;
var triangle:Shape = new Shape();// red triangle, starting at point 0, 0
triangle.graphics.beginFill(0xFF0000);
triangle.graphics.moveTo(triangleHeight / 2, 0);
triangle.graphics.lineTo(triangleHeight, triangleHeight);
triangle.graphics.lineTo(0, triangleHeight);
triangle.graphics.lineTo(triangleHeight / 2, 0);// green triangle, starting at point 200, 0
triangle.graphics.beginFill(0x00FF00);
triangle.graphics.moveTo(200 + triangleHeight / 2, 0);
triangle.graphics.lineTo(200 + triangleHeight, triangleHeight);
triangle.graphics.lineTo(200, triangleHeight);
triangle.graphics.lineTo(200 + triangleHeight / 2, 0);
this.addChild(triangle);

曲線の描画
Flash Player 9 以降、Adobe AIR 1.0 以降
curveTo() メソッドは、二次ベジェ曲線を描画します。このメソッドでは、2 つのポイント（アンカーポイント）をつなぐ弧を、3 番目のポイント（コントロールポイント）に向けて曲げながら描画します。Graphics オブジェクトは現在の描画位置
を最初のアンカーポイントとして使用します。curveTo() メソッドを呼び出す場合、コントロールポイントの x 座標と y 座
標、2 番目のアンカーポイントの x 座標と y 座標の順に、4 つのパラメーターを渡します。例えば、次のコードでは、ポイン
ト 100, 100 から始まりポイント 200, 200 で終わる曲線を描画します。コントロールポイントがポイント 175, 125 にあるため、まず右に、その後下に移動する曲線を作成します。
myShape.graphics.moveTo(100, 100);
myShape.graphics.curveTo(175, 125, 200, 200);

次の例では、幅と高さが 100 ピクセルの赤と緑の丸いオブジェクトを作成します。二次ベジェ曲線の特徴として、これらのオブジェクトは完全な円ではありません。
var size:uint = 100;var roundObject:Shape = new Shape();// red circular shaperoundObject.graphics.beginFill(0xFF0000);roundObject.graphics.moveTo(size / 2, 0);roundObject.graphics.curveTo(size, 0, size, size / 2);
roundObject.graphics.curveTo(size, size, size / 2, size);roundObject.graphics.curveTo(0, size, 0, size / 2);
roundObject.graphics.curveTo(0, 0, size / 2, 0);// green circular shaperoundObject.graphics.beginFill(0x00FF00);
roundObject.graphics.moveTo(200 + size / 2, 0);roundObject.graphics.curveTo(200 + size, 0, 200 + size, size / 2);
roundObject.graphics.curveTo(200 + size, size, 200 + size / 2, size);roundObject.graphics.curveTo(200, size, 200, size / 2);
roundObject.graphics.curveTo(200, 0, 200 + size / 2, 0);
this.addChild(roundObject);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド216

描画 API の使用

ビルトインメソッドを使用したシェイプの描画
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 には、円、楕円、矩形、および角の丸い矩形などの一般的なシェイプを描画できる便利なメソッドがあります。それは、Graphics クラスの drawCircle()、drawEllipse()、drawRect() および drawRoundRect() メソッドです。これらのメソッドは lineTo() メソッドおよび curveTo() メソッドの代わりに使用できます。ただし、これらのメソッドを呼び出す前にも、線と塗りのスタイルを指定しておく必要があります。
次の例は、前に示した例と同様に、幅と高さが 100 ピクセルの赤、緑、および青の四角形を描画します。このコードでは、

drawRect() メソッドを使用し、さらに塗りの色に 50 %（0.5）のアルファを指定しています。
var squareSize:uint = 100;var square:Shape = new Shape();square.graphics.beginFill(0xFF0000, 0.5);
square.graphics.drawRect(0, 0, squareSize, squareSize);
square.graphics.beginFill(0x00FF00, 0.5);
square.graphics.drawRect(200, 0, squareSize, squareSize);
square.graphics.beginFill(0x0000FF, 0.5);
square.graphics.drawRect(400, 0, squareSize, squareSize);
square.graphics.endFill();this.addChild(square);

Sprite オブジェクトまたは MovieClip オブジェクトでは、graphics プロパティを使用して作成された描画コンテンツは常に、オブジェクトに含まれているすべての子表示オブジェクトの背面に表示されます。また、graphics プロパティのコンテ
ンツは個別の表示オブジェクトではないため、Sprite オブジェクトまたは MovieClip オブジェクトの子のリストには表示されません。例えば、次の Sprite オブジェクトには graphics プロパティを使用して描画した円があり、その子表示オブジェク
トのリストには TextField オブジェクトがあります。
var mySprite:Sprite = new Sprite();mySprite.graphics.beginFill(0xFFCC00);
mySprite.graphics.drawCircle(30, 30, 30);
var label:TextField = new TextField();label.width = 200;
label.text = "They call me mellow yellow...";
label.x = 20;
label.y = 20;
mySprite.addChild(label);this.addChild(mySprite);

TextField は、グラフィックオブジェクトで描画された円の最上部に表示されます。

グラデーションの線と塗りの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
グラフィックオブジェクトでは、線と塗りを単色ではなく、グラデーションで描画することもできます。グラデーションの境界線は lineGradientStyle() メソッドで作成し、グラデーションの塗りは beginGradientFill() メソッドで作成します。
どちらのメソッドも同じパラメーターを受け取ります。最初の 4 つのパラメーター、タイプ、色、アルファ、および比率は必須です。残りの 4 つのパラメーターはオプションですが、高度なカスタマイズに役立ちます。

•

最初のパラメーターには、作成するグラデーションのタイプを指定します。指定できる値は GradientType.LINEAR またはGradientType.RADIAL です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

217

描画 API の使用• 2 番目のパラメーターには、使用するカラー値の配列を指定します。線状グラデーションの場合、色は左から右に配置されます。放射状グラデーションの場合、色は内側から外側に配置されます。配列での色の順序は、グラデーションで色が描画される順序を表します。

• 3 番目のパラメーターには、前のパラメーターの色に対応するアルファ透明度値を指定します。
• 4 番目のパラメーターには、各色のグラデーションの中での強調度を示すための比率を指定します。指定できる値の範囲
は 0 〜 255 です。これらの値は幅や高さではなく、グラデーション内での位置を表します。0 がグラデーションの始まりを表し、255 がグラデーションの終わりを表します。比率の配列は、順に増やしていく必要があり、2 番目および 3 番目のパラメーターで指定した色およびアルファの配列の両方とエントリの数が同じである必要があります。

5 番目のパラメーターである変換マトリックスはオプションですが、グラデーションの外観を制御する簡単で強力な方法であるため、よく使用されます。このパラメーターは Matrix インスタンスを受け取ります。グラデーション用の Matrix オブジェクトを最も簡単に作成するには、Matrix クラスの createGradientBox() メソッドを使用します。

グラデーションで使用する Matrix オブジェクトの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
シェイプで使用するグラデーションを定義するには、flash.display.Graphics クラスの beginGradientFill() およびlineGradientStyle() メソッドを使用します。グラデーションを定義する際、これらのメソッドのパラメーターでマトリックス
を指定します。
マトリックスを最も簡単に定義するには、Matrix クラスの createGradientBox() メソッドを使用してグラデーション定義用のマトリックスを作成します。createGradientBox() メソッドに指定するパラメーターでは、グラデーションの拡大／縮小、回転、および位置を定義します。createGradientBox() メソッドは次のパラメーターを受け取ります。

•

グラデーションボックスの幅：グラデーションが広がる幅（ピクセル単位）•

グラデーションボックスの高さ：グラデーションが広がる高さ（ピクセル単位）•

グラデーションボックスの回転：グラデーションに適用される回転角度（ラジアン単位）•

水平移動：グラデーションが水平方向に移動する距離（ピクセル単位）•

垂直移動：グラデーションが垂直方向に移動する距離（ピクセル単位）

例えば、次の性質を持つグラデーションを作成するとします。

• GradientType.LINEAR•

グリーンとブルーの 2 色、ratios 配列を [0, 255] に設定• SpreadMethod.PAD• InterpolationMethod.LINEAR_RGB
次の例で示すグラデーションは、createGradientBox() メソッドの rotation パラメーターが異なりますが、その他の設定はすべて同じです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

218

描画 API の使用

width = 100;height = 100;rotation = 0;tx = 0;ty = 0;width = 100;height = 100;rotation = Math.PI/4; // 45°
tx = 0;ty = 0;width = 100;height = 100;rotation = Math.PI/2; // 90°
tx = 0;ty = 0;次の例で示す緑〜青の線状グラデーション効果は、createGradientBox() メソッドの rotation、tx、ty パラメーターが異なりますが、その他の設定はすべて同じです。
width = 50;
height = 100;rotation = 0;tx = 0;ty = 0;width = 50;
height = 100;rotation = 0
tx = 50;ty = 0;width = 100;height = 50;
rotation = Math.PI/2; // 90°
tx = 0;ty = 0;width = 100;height = 50;
rotation = Math.PI/2; // 90°
tx = 0;ty = 50;

createGradientBox() メソッドの width、height、tx、ty パラメーターは、次の例で示すように、放射状グラデーションの塗りに関するサイズと位置にも影響します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

219

描画 API の使用

width = 50;
height = 100;rotation = 0;tx = 25;
ty = 0;

次のコードは、前の図の最後に示した放射状グラデーションを生成します。
import flash.display.Shape;
import flash.display.GradientType;import flash.geom.Matrix;
var type:String = GradientType.RADIAL;
var colors:Array = [0x00FF00, 0x000088];
var alphas:Array = [1, 1];
var ratios:Array = [0, 255];
var spreadMethod:String = SpreadMethod.PAD;
var interp:String = InterpolationMethod.LINEAR_RGB;
var focalPtRatio:Number = 0;
var matrix:Matrix = new Matrix();
var boxWidth:Number = 50;
var boxHeight:Number = 100;var boxRotation:Number = Math.PI/2; // 90°
var tx:Number = 25;
var ty:Number = 0;
matrix.createGradientBox(boxWidth, boxHeight, boxRotation, tx, ty);
var square:Shape = new Shape;square.graphics.beginGradientFill(type,
colors,alphas,ratios,matrix,spreadMethod,interp,focalPtRatio);square.graphics.drawRect(0, 0, 100, 100);
addChild(square);グラデーションの塗りの幅と高さは、Graphics オブジェクトを使用して描画される幅と高さではなく、グラデーションマ
トリックスの幅と高さによって決定されます。Graphics オブジェクトを使用して描画する場合、グラデーションマトリック
スのその座標に存在するものが描画されます。drawRect() などの Graphics オブジェクトのシェイプメソッドのいずれかを使用した場合でも、グラデーションは描画されるシェイプのサイズには伸縮されません。グラデーションのサイズはグラデー
ションマトリックス自体で指定する必要があります。
次のコードを使用して、グラデーションマトリックスのサイズと描画自体のサイズの視覚的な違いを説明します。
var myShape:Shape = new Shape();var gradientBoxMatrix:Matrix = new Matrix();
gradientBoxMatrix.createGradientBox(100, 40, 0, 0, 0);
myShape.graphics.beginGradientFill(GradientType.LINEAR, [0xFF0000, 0x00FF00, 0x0000FF], [1, 1, 1], [0, 128,255], gradientBoxMatrix);
myShape.graphics.drawRect(0, 0, 50, 40);
myShape.graphics.drawRect(0, 50, 100, 40);
myShape.graphics.drawRect(0, 100, 150, 40);
myShape.graphics.endFill();this.addChild(myShape);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

220

描画 API の使用

このコードは、赤、緑、青の色配分を同ーに指定した塗りのスタイルを持つ 3 つのグラデーションを描画します。グラデー
ションは、drawRect() メソッドを使用して、それぞれピクセル幅 50、100、150 で描画されます。beginGradientFill() メソッ
ドで指定するグラデーションマトリックスは、100 ピクセルの幅で作成されます。つまり、最初のグラデーションはグラ
デーション領域の半分のみを占め、2 番目は領域全体を占め、3 番目は領域全体を占めて、さらに青を 50 ピクセル右に拡張します。

lineGradientStyle() メソッドは beginGradientFill() と同様に動作しますが、グラデーションを定義するだけでなく、描画の前に、lineStyle() メソッドを使用して境界線の幅を指定する必要があります。次のコードは、赤、緑、および青のグラデーショ
ンの境界線でボックスを描画します。
var myShape:Shape = new Shape();var gradientBoxMatrix:Matrix = new Matrix();
gradientBoxMatrix.createGradientBox(200, 40, 0, 0, 0);
myShape.graphics.lineStyle(5, 0);
myShape.graphics.lineGradientStyle(GradientType.LINEAR, [0xFF0000, 0x00FF00, 0x0000FF], [1, 1, 1], [0, 128,255], gradientBoxMatrix);
myShape.graphics.drawRect(0, 0, 200, 40);
this.addChild(myShape);

Matrix クラスについて詳しくは、207 ページの「Matrix オブジェクトの使用」を参照してください。

描画メソッドでの Math クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Graphics オブジェクトを使用して円や四角形を描画できますが、特に、その描画メソッドを Math クラスのプロパティやメソッドと組み合わせて使用すると、より複雑なフォームを描画することもできます。Math クラスには、円周と円の直径の比を表す定数 Math.PI（約 3.14159265...）など、一般的な数学定数があります。また、Math.sin()、Math.cos()、Math.tan()などの三角関数のメソッドも含まれます。これらのメソッドおよび定数を使用してシェイプを描画すると、特に繰り返しや再帰を使用した場合、より動的な視覚効果を作成できます。

Math クラスの多くのメソッドでは、角度の単位に度ではなくラジアンを使用します。Math クラスは、これら 2 種類の単位間の変換によく使用されます。
var degrees = 121;
var radians = degrees * Math.PI / 180;
trace(radians) // 2.111848394913139

次の例では、正弦波と余弦波を作成して、特定の値での Math.sin() メソッドと Math.cos() メソッドの違いを示します。
var sinWavePosition = 100;var cosWavePosition = 200;
var sinWaveColor:uint = 0xFF0000;
var cosWaveColor:uint = 0x00FF00;
var waveMultiplier:Number = 10;
var waveStretcher:Number = 5;
var i:uint;for(i = 1; i < stage.stageWidth; i++){var sinPosY:Number = Math.sin(i / waveStretcher) * waveMultiplier;var cosPosY:Number = Math.cos(i / waveStretcher) * waveMultiplier;graphics.beginFill(sinWaveColor);graphics.drawRect(i, sinWavePosition + sinPosY, 2, 2);graphics.beginFill(cosWaveColor);graphics.drawRect(i, cosWavePosition + cosPosY, 2, 2);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

221

描画 API の使用

描画 API でのアニメーション化
Flash Player 9 以降、Adobe AIR 1.0 以降
描画 API を使用してコンテンツを作成する利点の 1 つは、コンテンツの配置が 1 度だけに制限されないことです。描画に使用した変数を保持または変更して、描画したコンテンツを変更できます。一定期間のフレーム上でまたはタイマーを使用して、変数を変更し再描画すると、アニメーションを表示できます。
例えば、次のコードは、Event.ENTER_FRAME イベントを監視して、通過フレームごとに表示を変更していきます。現在の度数を増やしていき、グラフィックオブジェクトをクリアして更新した位置に再描画します。
stage.frameRate = 31;
var currentDegrees:Number = 0;
var radius:Number = 40;
var satelliteRadius:Number = 6;
var container:Sprite = new Sprite();container.x = stage.stageWidth / 2;
container.y = stage.stageHeight / 2;
addChild(container);var satellite:Shape = new Shape();container.addChild(satellite);
addEventListener(Event.ENTER_FRAME, doEveryFrame);function doEveryFrame(event:Event):void{currentDegrees += 4;
var radians:Number = getRadians(currentDegrees);var posX:Number = Math.sin(radians) * radius;
var posY:Number = Math.cos(radians) * radius;satellite.graphics.clear();satellite.graphics.beginFill(0);satellite.graphics.drawCircle(posX, posY, satelliteRadius);}
function getRadians(degrees:Number):Number{
return degrees * Math.PI / 180;}

大きく異なる結果を生成するには、コードの先頭の初期シード変数 currentDegrees、radius および satelliteRadius を変更して試してみます。例えば、radius 変数を減らしたり、totalSatellites 変数を増やします。これは、描画 API が複雑なビジュア
ル表示をどれだけ簡単に作成できるかを示す一例にすぎません。

描画 API の例：Algorithmic Visual Generator
Flash Player 9 以降、Adobe AIR 1.0 以降
この例に示す Algorithmic Visual Generator は、ステージに複数の「サテライト」（円軌道を移動する円）を動的に描画します。ここでは、次の機能について説明します。

•

描画 API を使用した、動的な外観を持つ基本的なシェイプの描画•描画に使用するプロパティとユーザー操作との連動•

各フレーム上のステージをクリアして再描画することによる、アニメーションの表示

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

222

描画 API の使用

前のサブセクションの例では、Event.ENTER_FRAME イベントを使用して、単独の「サテライト」をアニメーション化しました。この例では、前の例を拡張して、複数のサテライトのビジュアル表示を即時に更新する一連のスライダーがあるコン
トロールパネルを作成します。この例では、コードを外部クラスに形式化し、サテライト作成コードを、各サテライトへの参照を satellites 配列に格納するループにラップします。
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。このアプリケーションのファイル
は、Samples/AlgorithmicVisualGenerator フォルダーにあります。このフォルダーには次のファイルが含まれます。
ファイル

説明

Flash Professional（FLA）のメインアプリケーション

AlgorithmicVisualGenerator.fla

ファイル。

com/example/programmingas3/algorithmic/AlgorithmicVisualGenerator.as

ステージにサテライトを描画する機能や、コントロール
パネルからのイベントに応答して、サテライトの描画に影響する変数を更新する機能など、アプリケーションの主要な機能を提供するクラス。

com/example/programmingas3/algorithmic/ControlPanel.as

複数のスライダーを使用したユーザー操作を管理し、それに応答してイベントを送出するクラス。

com/example/programmingas3/algorithmic/Satellite.as

中心点の周囲の軌道内を回転する表示オブジェクトを表すクラス。現在の描画状態に関連するプロパティが含まれます。

リスナーの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
このアプリケーションは、まず 3 つのリスナーを作成します。最初のリスナーは、サテライトを再構築する必要がある、コントロールパネルから送出されるイベントを監視します。2 番目のリスナーは SWF ファイルのステージのサイズ変更を監視します。3 番目のリスナーは SWF ファイルの各通過フレームを監視し、doEveryFrame() 関数を使用して再描画します。

サテライトの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
これらのリスナーを設定したら、build() 関数を呼び出します。この関数は、最初に clear() 関数を呼び出します。この関数
は、satellites 配列を空にしてステージ上の前の描画をすべてクリアします。この処理が必要なのは、カラー設定が変更された場合など、コントロールパネルがイベントを送出して build() 関数を再び呼び出す可能性があるためです。そのような場合
は、サテライトを削除して、再作成する必要があります。
次に、この関数はサテライトを作成します。そのために、軌道のランダムな位置で始まる position 変数や、この例ではサテライトの作成後は変更しない color 変数など、作成に必要な初期プロパティを設定します。
サテライトが作成されるたびに、そのサテライトへの参照が satellites 配列に追加されます。doEveryFrame() 関数を呼び出すと、この配列のすべてのサテライトが更新されます。

サテライト位置の更新
Flash Player 9 以降、Adobe AIR 1.0 以降
doEveryFrame() 関数は、アプリケーションの アニメーション処理の中心です。SWF ファイルのフレームレートと同じレートで、すべてのフレームに対して呼び出されます。描画の変数が少しずつ変化するため、アニメーションの外観が伝達されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

223

描画 API の使用

この関数は、最初に前の描画をすべてクリアし、背景を再描画します。その後、各サテライトコンテナをループ処理して各サテライトの position プロパティを増やし、ユーザーのコントロールパネル操作によって変更された可能性のある radius プ
ロパティと orbitRadius プロパティを更新します。最後に、Satellite クラスの draw() メソッドを呼び出して、サテライトを新しい位置に更新します。
カウンター i は、visibleSatellites 変数までしか増やすことができません。これは、ユーザーがコントロールパネルで表示する
サテライトの数を制限している場合、ループ内の残りのサテライトは再描画せずに非表示にする必要があるためです。これは、描画を行うループの直後のループで発生します。

doEveryFrame() 関数が完了すると、visibleSatellites の数のサテライトが画面上で新しい位置に更新されます。

ユーザー操作への応答
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザー操作は、ControlPanel クラスで管理されるコントロールパネルから行われます。このクラスは、各スライダーの個々の最小値、最大値、およびデフォルト値と併せてリスナーを設定します。ユーザーがこれらのスライダーを動かすと、

changeSetting() 関数が呼び出されます。この関数は、コントロールパネルのプロパティを更新します。変更により表示を再構築する必要がある場合、イベントが送出され、メインアプリケーションファイルで処理されます。コントロールパネルの設定が変更されると、doEveryFrame() 関数は更新された変数を使用して各サテライトを描画します。

追加カスタマイズ
Flash Player 9 以降、Adobe AIR 1.0 以降
この例は、描画 API を使用したビジュアルの生成方法の基本的な概略を示しています。比較的少ない行数のコードを使用して、とても複雑に見えるインタラクティブ機能を作成しています。それでも、この例を少し変更して拡張できます。いくつかのアイデアを示します。

• doEveryFrame() 関数で、サテライトのカラー値を増やします。
• doEveryFrame() 関数で、サテライトの半径を時間の経過と共に縮小または拡大します。
•

サテライトの軌道は円である必要はありません。例えば、Math クラスを使用して正弦波に沿ってサテライトを移動します。

•

他のサテライトとのヒット検出を使用します。

描画 API は、実行時に基本的なシェイプを描画する、Flash オーサリング環境で視覚効果を作成する代替機能として使用できます。また、手動で作成するのが不可能な変化やスコープの視覚効果を作成するのにも使用できます。描画 API と若干の数式を使用することで、ActionScript 作成者は斬新な作品を実現できます。

描画 API の高度な使用
Flash Player 10 以降、Adobe AIR 1.5 以降
Flash Player 10 および Adobe AIR 1.5 以降の Flash ランタイムでは、高度な描画機能のサポートが導入されています。これらのランタイムの描画 API は、従来のリリースからある描画メソッドを拡張し、シェイプの生成、実行時のシェイプ変更、3 次元効果の作成などを実行するためのデータセットを確立するものです。既存の各種メソッドは、この描画 API 拡張の提供する代替コマンド群として統合されています。それらのコマンドでは、描画メソッド用のデータセットはベクター配列と列挙クラスによって表されます。ベクター配列を使用するとさらに複雑なシェイプを速くレンダリングでき、開発者は配列の値をプログラムで変更して実行時にシェイプを動的にレンダリングできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

224

描画 API の使用

Flash Player 10 で導入された描画機能については、224 ページの「パスの描画」、225 ページの「ワインディング規則の定義」、227 ページの「グラフィックスデータクラスの使用」、および 229 ページの「drawTriangles() の使用について」の各節で説明します。

ActionScript の高度な描画 API を使用すると、次のような作業を実行できます。

• Vector オブジェクトを使用して描画メソッド用のデータを格納する• 1 つの操作でプログラムでシェイプを描画するためのパスを定義する•

重なり合うシェイプを塗りつぶす方法を決定するワインディング規則を定義する•

グラフィックスデータの直列化と保存、実行時のスプライトシートの生成、ベクターグラフィックスコンテンツのコピーの描画などのために、表示オブジェクトのベクターグラフィックスコンテンツを読み取る• 3 次元効果用に三角形と描画メソッドを使用する
重要な概念と用語
次の参照リストに、この節で使用する重要な用語を示します。

•

ベクター：すべてが同じデータ型の値の配列。Vector オブジェクトは、描画メソッドが 1 つのコマンドで線やシェイプを作成するのに使用する値の配列を格納できます。Vector オブジェクトの詳細については、25 ページの「インデックス
配列」を参照してください。

•

パス：1 つ以上の直線または曲線のセグメントで構成されます。各セグメントの始点と終点は座標で示され、ワイヤーを固定するピンのような働きをします。パスには、クローズパス（例えば、円）と離れた端点をもつオープンパス（例えば、波形線）とがあります。

•

ワインディング：レンダラーによって解釈されるパスの方向。正（時計回り）または負（反時計回り）です。

• GraphicsStroke：線のスタイルを設定するためのクラス。Stroke（線）という用語は今回の描画 API 拡張に属する概念
ではありませんが、クラス自体の塗りプロパティによって線のスタイルを指定する使用法は新しい描画 API で導入されたものです。GraphicsStroke クラスを使用すると、線のスタイルを動的に調節できます。
• Fill オブジェクト：flash.display.GraphicsBitmapFill や flash.display.GraphicsGradientFill などの新しい表示クラスを使用して作成され、描画コマンド Graphics.drawGraphicsData() に渡されるオブジェクト。Fill オブジェクトと拡張された描画コマンドでは、Graphics.beginBitmapFill() および Graphics.beginGradientFill() に相当する機能が、従来よりもオブ
ジェクト指向を強めたプログラミング手法で実装されています。

パスの描画
Flash Player 10 以降、Adobe AIR 1.5 以降
直線と曲線の描画に関する節（213 ページの「線と曲線の描画」を参照）では、1 つの直線を描画するコマンド（Graphics.lineTo()）および曲線を描画するコマンド（Graphics.curveTo()）と、線を別の位置に移動してシェイプを形成する
コマンド（Graphics.moveTo()）を紹介しました。Graphics.drawPath() メソッドおよび Graphics.drawTriangles() メソッドは、
これらの同じ描画コマンドを表す一連のオブジェクトをパラメーターとして受け入れます。これらのメソッドにより、一連の Graphics.lineTo()、Graphics.curveTo()、または Graphics.moveTo() コマンドが、Flash ランタイムで単一のステートメント
として実行されます。

GraphicsPathCommand 列挙クラスでは、描画コマンドに対応する一連の定数を定義します。これら一連の定数を、Vector インスタンスでラップして、Graphics.drawPath() メソッドのパラメーターとして渡します。これにより、1 つのコマンドで、シェイプ全体または複数のシェイプをレンダリングできます。また、これらのメソッドに渡す値を変えて、既存のシェイプを変更することもできます。
描画コマンドの Vector に加えて、drawPath() メソッドには、各描画コマンドの座標に対応する一連の座標も必要です。座標（Number インスタンス）を含む Vector インスタンスを作成し、drawPath() メソッドに、2 つ目の（data）引数として渡します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

225

描画 API の使用

注意：ベクター内の値は Point オブジェクトではありません。ベクターを一連の数値であり、2 つの数値からなる各グルー
プが、1 つの x/y 座標ペアを表します。

Graphics.drawPath() メソッドは、各コマンドとそれに対応するポイントの値（2 つまたは 4 つの値のコレクション）を一致させて、Graphics オブジェクトにパスを生成します。
package{import flash.display.*;
public class DrawPathExample extends Sprite{
public function DrawPathExample(){var squareCommands:Vector.<int> = new Vector.<int>(5, true);squareCommands[0] = GraphicsPathCommand.MOVE_TO;
squareCommands[1] = GraphicsPathCommand.LINE_TO;
squareCommands[2] = GraphicsPathCommand.LINE_TO;
squareCommands[3] = GraphicsPathCommand.LINE_TO;
squareCommands[4] = GraphicsPathCommand.LINE_TO;
var squareCoord:Vector.<Number> = new Vector.<Number>(10, true);squareCoord[0] = 20; //x
squareCoord[1] = 10; //ysquareCoord[2] = 50;
squareCoord[3] = 10;
squareCoord[4] = 50;
squareCoord[5] = 40;
squareCoord[6] = 20;
squareCoord[7] = 40;
squareCoord[8] = 20;
squareCoord[9] = 10;graphics.beginFill(0x442266);//set the color
graphics.drawPath(squareCommands, squareCoord);}}}

ワインディング規則の定義
Flash Player 10 以降、Adobe AIR 1.5 以降拡張された描画 API では、パスの「ワインディング」の概念も導入されました。これは、パスの方向を表します。パスのワ
インディングは、正（時計回り）または負（反時計回り）のいずれかです。data パラメーターに対してベクターで提供される座標をレンダラーが解釈する順序により、ワインディングが決まります。
A

0

3
B

1

0

2

1

3

2
C

正のワインディングと負のワインディング
A. 矢印は描画の方向を示す。 B. 正のワインディング（時計回り） C. 負のワインディング（反時計回り）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

226

描画 API の使用

さらに、Graphics.drawPath() メソッドには「winding」という第 3 のオプションのパラメーターがあります。
drawPath(commands:Vector.<int>, data:Vector.<Number>, winding:String = "evenOdd"):void

このコンテキストでは、3 番目のパラメーターは交差するパスのワインディングつまり塗り規則を指定する文字列または定数です。定数値は、GraphicsPathWinding クラスで GraphicsPathWinding.EVEN_ODD またはGraphicsPathWinding.NON_ZERO として定義されています。ワインディング規則は、パスが交差するときに重要です。
偶奇規則は、標準的なワインディング規則であり、以前の描画 API で使用されていた規則です。偶奇規則は、Graphics.drawPath() メソッドのデフォルトの規則でもあります。偶奇規則では、交差するすべてのパスは開いた塗りと閉じた塗りが交互になります。同じ塗りの交差を使用して 2 つの四角形を描画した場合、交差が発生している領域は塗りつぶされます。一般に、隣接する領域が、両方とも塗られること、または両方とも塗られないことはありません。
一方、非ゼロ規則は、ワインディング（描画方向）に基づいて、交差するパスによって定義されている領域を塗るかどうかを決定します。ワインディングが反対のパスが交差すると、定義される領域は塗られません。これは偶奇規則と同じです。
ワインディングが同じパスの場合は、偶奇規則では塗られなかった領域が塗られます。

A

B

交差する領域のワインディング規則
A. 偶奇ワインディング規則 B. 非ゼロワインディング規則

ワインディング規則名
Flash Player 10 以降、Adobe AIR 1.5 以降
名前は、これらの塗りを管理する方法を定義する、より具体的な規則を示します。正のワインディングのパスには +1 という値が割り当てられます。負のワインディングのパスには -1 という値が割り当てられます。シェイプの閉じた領域内のポイントから開始して、外側に無限に延びる直線を描画します。その直線がパスと交差した回数と、これらのパスの組み合わされた値を使用して、塗りが決定されます。偶奇ワインディングの場合は、直線がパスと交差した回数が使用されます。回数が奇数の場合、領域は塗られます。回数が偶数の場合、領域は塗られません。非ゼロワインディングの場合は、パスに割り当てられている値が使用されます。パスの組み合わされた値が 0 でない場合、領域は塗られます。組み合わされた値が 0 の場合、領域は塗られません。

A

B

ワインディング規則の回数と塗り
A. 偶奇ワインディング規則 B. 非ゼロワインディング規則

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

227

描画 API の使用

ワインディング規則の使用
Flash Player 10 以降、Adobe AIR 1.5 以降
これらの塗り規則は複雑ですが、状況によっては必要になります。例えば、星のシェイプを描画するとします。標準の偶奇規則では、シェイプを描画するために 10 本の異なる線が必要です。非ゼロワインディング規則では、必要な線が 5 本に減ります。5 本の線と非ゼロワインディング規則を使用して星を描画する ActionScript を次に示します。
graphics.beginFill(0x60A0FF);
graphics.drawPath( Vector.<int>([1,2,2,2,2]),GraphicsPathWinding.NON_ZERO);

Vector.<Number>([66,10, 23,127, 122,50, 10,49, 109,127]),

次のような星のシェイプが描画されます。

A

B

C

異なるワインディング規則を使用した星のシェイプ
A. 偶奇と 10 本の線 B. 偶奇と 5 本の線 C. 非ゼロと 5 本の線

また、イメージをアニメーション化するとき、または 3 次元のオブジェクトおよび重ね合わせでテクスチャとして使用する
ときは、ワインディング規則がいっそう重要になります。

グラフィックスデータクラスの使用
Flash Player 10 以降、Adobe AIR 1.5 以降拡張された描画 API には、IGraphicsData インターフェイスを実装する一連のクラスが flash.display パッケージに含まれます。これらのクラスは、描画 API の描画メソッドを表す値オブジェクト（データコンテナ）の役割を果たします。
以下のクラスが IGraphicsData インターフェイスを実装しています。

• GraphicsBitmapFill• GraphicsEndFill• GraphicsGradientFill• GraphicsPath• GraphicsShaderFill• GraphicsSolidFill• GraphicsStroke• GraphicsTrianglePath
これらのクラスを使用すると、完全な描画を IGraphicsData 型の Vector オブジェクト配列（Vector.<IGraphicsData>）に保存できます。その後、グラフィックスデータを他のシェイプインスタンスのデータソースとして再利用したり、描画情報を後から使用するために保存することができます。
塗りクラスは塗りのスタイルごとに複数ありますが、境界線クラスは 1 つだけです。境界線クラスは塗りクラスを使用してスタイルを定義するので、ActionScript の境界線クラスは IGraphicsData だけです。そのため、境界線はすべて、実際には境界線クラスと塗りクラスの組み合わせによって定義されます。それ以外については、これらのグラフィックスデータク
ラスの API は、flash.display.Graphics クラスに存在するメソッドを反映しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

228

描画 API の使用

グラフィックスメソッド

対応するクラス

beginBitmapFill()

GraphicsBitmapFill

beginFill()

GraphicsSolidFill

beginGradientFill()

GraphicsGradientFill

beginShaderFill()

GraphicsShaderFill

lineBitmapStyle()

GraphicsStroke + GraphicsBitmapFill

lineGradientStyle()

GraphicsStroke + GraphicsGradientFill

lineShaderStyle()

GraphicsStroke + GraphicsShaderFill

lineStyle()

GraphicsStroke + GraphicsSolidFill

moveTo()GraphicsPathlineTo()curveTo()
drawPath()drawTriangles()GraphicsTrianglePath

さらに、GraphicsPath クラスには、GraphicsPath インスタンス用にこれらのコマンドを簡単に定義するために、GraphicsPath.moveTo()、GraphicsPath.lineTo()、GraphicsPath.curveTo()、GraphicsPath.wideLineTo() および
GraphicsPath.wideMoveTo() の各ユーティリティメソッドを独自に備えています。これらのユーティリティメソッドを使用
すると、コマンドおよびデータ値を直接定義または更新する作業が簡単になります。

ベクターグラフィックスデータの描画
IGraphicsData インスタンスのコレクションを作成したら、Graphics クラスの drawGraphicsData() メソッドを使用してグ
ラフィックスをレンダリングします。drawGraphicsData() メソッドでは、IGraphicsData インスタンスのベクターから順番に一連の描画手順が実行されます。
// stroke object
var stroke:GraphicsStroke = new GraphicsStroke(3);stroke.joints = JointStyle.MITER;
stroke.fill = new GraphicsSolidFill(0x102020);// solid stroke// fill object
var fill:GraphicsGradientFill = new GraphicsGradientFill();
fill.colors = [0x0000FF, 0xEEFFEE];
fill.matrix = new Matrix();
fill.matrix.createGradientBox(70, 70, Math.PI/2);// path object
var path:GraphicsPath = new GraphicsPath(new Vector.<int>(), new Vector.<Number>());
path.commands.push(GraphicsPathCommand.MOVE_TO, GraphicsPathCommand.LINE_TO, GraphicsPathCommand.LINE_TO);
path.data.push(125,0, 50,100, 175,0);// combine objects for complete drawing
var drawing:Vector.<IGraphicsData> = new Vector.<IGraphicsData>();drawing.push(stroke, fill, path);// draw the drawing
graphics.drawGraphicsData(drawing);

例の描画で使用されているパスの値を 1 つ変更すると、シェイプを複数回再描画してさらに複雑なイメージを作成できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド229

描画 API の使用// draw the drawing multiple times// change one value to modify each variationgraphics.drawGraphicsData(drawing);
path.data[2] += 200;
graphics.drawGraphicsData(drawing);
path.data[2] -= 150;
graphics.drawGraphicsData(drawing);
path.data[2] += 100;graphics.drawGraphicsData(drawing);
path.data[2] -= 50;graphicsS.drawGraphicsData(drawing);

IGraphicsData オブジェクトでは塗りと境界線のスタイルを定義できますが、これらのスタイルは必ずしも必要ありません。つまり、Graphics クラスのメソッドを使用してスタイルを設定し、IGraphicsData オブジェクトを使用して保存されているパスのコレクションを描画したり、その逆のことを行ったりできます。
注意：新しい描画を開始する前に、Graphics.clear() メソッドを使用して以前の描画をクリアします。そうしないと、前の例のように、元の描画の上に新しい描画が追加されます。IGraphicsData オブジェクトのパスまたはコレクションの単一の部分を変更した場合は、変更を表示するために全体を再描画します。
グラフィックスデータクラスを使用した場合、3 つ以上のポイントが描画されると、その時点でシェイプが閉じるので、常に塗りがレンダリングされます。塗りが閉じても、境界線は閉じません。この動作は、複数の Graphics.lineTo() またはGraphics.moveTo() コマンドを使用するときと異なります。

ベクターグラフィックスデータの読み取り
Flash Player 11.6 以降、Adobe AIR 3.6 以降
表示オブジェクトへのベクターコンテンツの描画に加えて、Flash Player 11.6 および Adobe AIR 3.6 以降では、Graphics
クラスの readGraphicsData() メソッドを使用して、表示オブジェクトのベクターグラフィックスコンテンツのデータ表現を取得できます。これを使用すると、グラフィックのスナップショットを作成し、実行時にスプライトシートを保存、コピー、作成することなどができます。

readGraphicsData() メソッドを呼び出すと、IGraphicsData オブジェクトを含む Vector インスタンスが返されます。これらは、drawGraphicsData() メソッドを使用してベクターグラフィックスを描画する際に使用するものと同じオブジェクトです。

readGraphicsData() メソッドでベクターグラフィックスを読み取るには、いくつか制限があります。詳しくは、ActionScript リファレンスガイドの readGraphicsData() の項目を参照してください。

drawTriangles() の使用についてFlash Player 10 以降、Adobe AIR 1.5 以降
Flash Player 10 および Adobe AIR 1.5 に導入されたもう 1 つの高度なメソッド Graphics.drawTriangles() は、Graphics.drawPath() メソッドと似ています。また、Graphics.drawTriangles() メソッドでは、Vector.<Number> オブジェク
トを使用して、パスを描画するためのポイントの位置を指定します。
ただし、Graphics.drawTriangles() メソッドの実際の目的は、ActionScript による 3 次元効果を容易にすることです。
Graphics.drawTriangles() を使用して 3 次元効果を生成する方法については、344 ページの「3D 効果のための三角形の使用」
を参照してください。

最終更新日 2015/10/14

230

第 13 章：ビットマップの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ベクター描画機能に加え、ActionScript 3.0 にはビットマップイメージの作成や、SWF にロードされた外部ビットマップ
イメージのピクセルデータの操作を可能にする機能があります。個々のピクセル値にアクセスして変更する機能を利用すると、フィルターのような独自のイメージ効果を作成し、ビルトインのノイズ関数を使用してテクスチャやランダムノイズを作成することができます。

• Renaun Erickson：転送を使用した ActionScript でのゲームアセットのレンダリング• Bitmap programming：「Essential ActionScript 3」の第 26 章（Colin Moock（O'Reilly Media、2007 年））• Mike Jones：Working with Sprites in Pushbutton Engine• Flash & Math：Pixel Particles Made Simple• Flixel

ビットマップの操作の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
デジタルイメージを操作する際、主なグラフィックタイプにはビットマップとベクターがあります。ビットマップグラ
フィックは、ラスターグラフィックとも呼ばれ、矩形のグリッドに配列された小さな正方形（ピクセル）によって構成されます。ベクターグラフィックは、直線、曲線、ポリゴンなど、数学的に生成された幾何学図形によって構成されます。
ビットマップイメージはイメージの幅と高さによって定義され、ピクセル単位と 1 ピクセルあたりのビット数（1 ピクセルあたりの色数）で表されます。RGB カラーモデルを使用するビットマップイメージの場合、ピクセルは赤、緑、青の 3 バイ
トで構成されます。各バイトは、0 から 255 までの値になります。ピクセルの中でバイトを組み合わせることにより、画家が絵の具を混ぜ合わせるのと同じような形で色が生成されます。例えば、ピクセルのバイト値が赤 255、緑 102、青 0 であれ
ば、鮮やかなオレンジ色が生成されます。
ビットマップイメージの品質は、イメージの解像度と、色深度のビット値を組み合わせることによって決定されます。解像度とは、1 つのイメージに含まれるピクセル数を指します。ピクセル数が大きいほど解像度が高くなり、イメージが精細に表示されます。色深度とは、1 つのピクセルが格納できる情報量を指します。例えば、色深度値がピクセルあたり 16 ビットのイメージは、色深度が 48 ビットのイメージと同じ数の色を表現することはできません。その結果、48 ビットのイメージの方が 16 ビットのイメージよりもスムーズな階調を示すことができます。
ビットマップグラフィックは解像度に依存するので、効果的に拡大／縮小することができません。これは、ビットマップを拡大すると特に顕著です。ビットマップイメージを拡大すると細部が失われ、品質が劣化します。
ビットマップファイル形式
ビットマップイメージは、いくつかの一般的なファイル形式に分けられます。これらの形式は、それぞれに異なる圧縮アル
ゴリズムによってファイルサイズを縮小すると共に、イメージの最終用途に応じて画質を最適化します。Adobe ランタイム
が対応しているビットマップイメージ形式は、BMP、GIF、JPG 、PNG および TIFF です。

BMP
Microsoft Windows オペレーティングシステムが使用するデフォルトのイメージ形式は、BMP（ビット マップ）形式です。どのようなフォームの圧縮アルゴリズムも使用しないため、通常、結果のファイルサイズは大きくなります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

231

ビットマップの操作

GIF
Graphics Interchange Format（GIF）は、256 色、つまり 8 ビットカラーのイメージを伝送するために、1987 年にCompuServe 社によって開発されました。この形式はファイルサイズが小さいので、Web ベースのイメージには最適です。
GIF のカラーパレットには限界があるので、GIF イメージは通常は写真に適していません。写真は、細かな階調やカラーグ
ラデーションを必要とするからです。GIF イメージは単独ビットの透明度にも対応しているので、カラーを透明としてマッピングすることもできます。これにより、透明度がマッピングされたイメージを透過して Web ページの背景を表示することができます。

JPEG
Joint Photographic Experts Group（JPEG）によって開発された JPEG（または JPG）イメージ形式は非可逆圧縮アルゴ
リズムを使用し、小さいファイルサイズで 24 ビット色深度を実現することができます。非可逆圧縮では、イメージを保存す
るたびに品質とデータが失われますが、ファイルサイズを小さく抑えることができます。JPEG 形式では何百万もの色を表示できるので、写真に最適です。イメージに適用される圧縮の度合いを制御できるので、イメージの品質とファイルサイズを操作することができます。

PNG
Portable Network Graphics（PNG）形式は、特許を取得した GIF ファイル形式のオープンソース代替形式として開発されました。PNG は最大で 64 ビットの色深度に対応しているので、最大で 1,600 万色を表示することができます。PNG は比較的新しい形式なので、一部の古いブラウザーでは PNG ファイルをサポートしていません。JPG とは違い、PNG は可逆圧
縮を使用します。つまり、イメージが保存されても、イメージデータは失われません。PNG ファイルは、最大で 256 レベルの透明度に対応する、アルファ透明度もサポートしています。

TIFF
PNG が導入される前は、クロスプラットフォーム用の形式は Tagged Image File Format（TIFF）でした。TIFF 形式の短所は、TIFF に多くの種類が存在するために、すべてのバージョンを処理できる単一のリーダーがないということです。また、現在のところ、Web ブラウザーもこの形式をサポートしていません。TIFF は、非可逆圧縮または可逆圧縮のいずれかを使用しており、デバイス固有の色空間（CMYK など）を処理することができます。
透明なビットマップと不透明なビットマップ

GIF または PNG 形式を使用するビットマップイメージでは、各ピクセルに追加バイトとしてアルファチャンネルが付与されます。この追加バイトは、ピクセルの透明度の値を表します。

GIF イメージは単独ビットの透明度に対応しているので、256 色のカラーパレットの中から 1 色を指定し、その色を透明にすることができます。一方 PNG イメージでは、最大で 256 レベルの透明度に対応しています。この機能は、イメージやテキストを背景と混ぜ合わせる場合に特に有効です。

ActionScript 3.0 は、追加された透明度ピクセルバイトを BitmapData クラス内に複製します。PNG 透明度モデルと同様に、ActionScript は最大で 256 レベルの透明度を実現します。
重要な概念と用語
次に、ビットマップグラフィックに関する説明で使用される重要な用語を示します。
アルファ 色またはイメージの透明度（正確には不透明度）のレベルです。多くの場合、アルファの値は、アルファチャンネ
ル値として示されます。

ARGB カラー 各ピクセルの色を、赤、緑、青を混合したカラー値として示すカラースキームです。透明度はアルファ値として指定されます。
カラーチャンネル 通常、色は基本色を混ぜ合わせることで表示されます。コンピューターグラフィックでは、通常は赤、緑、青です。基本色はそれぞれカラーチャンネルとして見なされます。各カラーチャンネルが混ぜ合わされる量により、最終的な色が決定されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

232

ビットマップの操作

色深度 ビット深度とも呼ばれます。1 ピクセルに使用されるコンピューターメモリを示します。つまり、イメージで表示できる色の数を決定します。
ピクセル ビットマップイメージの最小情報単位、つまり色のドットです。
解像度 イメージのピクセルサイズで、これによりイメージの詳細さが決定します。解像度は、ピクセルの幅と高さによって表現されます。

RGB カラー 各ピクセルの色が赤、緑、青のカラー値で表示されるカラースキームです。

Bitmap および BitmapData クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
ビットマップイメージを操作するための主な ActionScript 3.0 クラスには、画面上にビットマップイメージを表示する
Bitmap クラスおよびビットマップの未処理のイメージデータにアクセスして操作するために使用する BitmapData クラスがあります。

関連項目

flash.display.Bitmap
flash.display.BitmapData

Bitmap クラスについてFlash Player 9 以降、Adobe AIR 1.0 以降
DisplayObject クラスのサブクラスである Bitmap クラスは、ビットマップイメージを表示するために使用される主なActionScript 3.0 クラスです。これらのイメージは、flash.display.Loader クラスによってロードされているか、Bitmap() コ
ンストラクターによって動的に作成されています。外部ソースからイメージをロードする場合、Bitmap オブジェクトは
GIF、JPEG、または PNG 形式のイメージしか使用できません。Bitmap インスタンスは BitmapData オブジェクトのラッパーとして見なされ、ステージにレンダリングする必要があります。Bitmap インスタンスは表示オブジェクトなので、表示
オブジェクトのすべての性質と機能を活用して Bitmap インスタンスを操作することもできます。表示オブジェクトの操作方法について詳しくは、143 ページの「表示のプログラミング」を参照してください。

ピクセルの吸着とスムージング
Flash Player 9 以降、Adobe AIR 1.0 以降
すべての表示オブジェクトに共通する機能に加え、Bitmap クラスはビットマップイメージに特有の機能も提供します。

Bitmap クラスの pixelSnapping プロパティは、Bitmap オブジェクトが最も近いピクセルに吸着されるかどうかを指定します。このプロパティは、PixelSnapping クラスで定義されている 3 つの定数、ALWAYS、AUTO および NEVER のいずれかを受け入れます。
ピクセルの吸着を適用するシンタックスは次のとおりです。
myBitmap.pixelSnapping = PixelSnapping.ALWAYS;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

233

ビットマップの操作

ビットマップイメージが拡大／縮小されると、ぼやけたり歪んだりすることが多々あります。この歪みを抑えるため、BitmapData クラスの smoothing プロパティを使用します。このブール型プロパティを true に設定すると、拡大／縮小されたイメージ内のピクセルをスムージングまたはアンチエイリアス化します。これにより、イメージをより鮮明に、より自然に表現できるようになります。

BitmapData クラスについてFlash Player 9 以降、Adobe AIR 1.0 以降
BitmapData クラスは flash.display パッケージにあり、ロードされたビットマップイメージや動的に作成されたビットマッ
プイメージ内のピクセルのスナップショットのようなものです。このスナップショットは、オブジェクト内のピクセルデー
タの配列として表されます。BitmapData クラスには、ピクセルデータの作成と操作に便利なビルトインメソッドもあります。

BitmapData オブジェクトをインスタンス化するには、次のコードを使用します。
var myBitmap:BitmapData = new BitmapData(width:Number, height:Number, transparent:Boolean,
fillColor:uinit);

width および height パラメーターでは、ビットマップのサイズを指定します。AIR 3 および Flash Player 11 以降、BitmapData オブジェクトのサイズ制限はなくなりました。ビットマップの最大サイズはオペレーティングシステムによって異なります。

AIR 1.5 および Flash Player 10 では、BitmapData オブジェクトの最大サイズは幅または高さで 8,191 ピクセルです。総ピ
クセル数が 16,777,215 ピクセルを超えることはできません。（したがって、BitmapData オブジェクトの幅が 8,191 ピクセ
ルであった場合、高さは 2,048 ピクセルまでしか指定できません）。Flash Player 9 以前および AIR 1.1 以前では、制限は高さ 2,880 ピクセル、幅 2,880 ピクセルです。

transparent パラメーターは、ビットマップデータにアルファチャンネルが含まれるかどうかを指定します。含まれる場合はtrue、含まれない場合は false です。fillColor パラメーターは、背景色を指定する 32 ビットのカラー値です。true に設定されている場合は、透明度の値も指定します。次の例では、透明度が 50% に設定されたオレンジ色の背景の BitmapData オブ
ジェクトを作成します。
var myBitmap:BitmapData = new BitmapData(150, 150, true, 0x80FF3300);

新たに作成された BitmapData オブジェクトを画面にレンダリングするには、このオブジェクトを Bitmap インスタンスに割り当てるか、ラップします。そのためには、Bitmap オブジェクトのコストラクタのパラメーターとして BitmapData オ
ブジェクトを渡すか、BitmapData オブジェクトを既存の Bitmap インスタンスの bitmapData プロパティに割り当てます。
また、Bitmap インスタンスを含む表示オブジェクトのコンテナの addChild() または addChildAt() メソッドを呼び出し、

Bitmap インスタンスを表示リストに追加する必要もあります。表示リストの操作方法について詳しくは、151 ページの「表示リストへの表示オブジェクトの追加」を参照してください。
次の例では、赤く塗りつぶした BitmapData オブジェクトを作成し、Bitmap インスタンスに表示します。
var myBitmapDataObject:BitmapData = new BitmapData(150, 150, false, 0xFF0000);
var myImage:Bitmap = new Bitmap(myBitmapDataObject);addChild(myImage);

ピクセルの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
BitmapData クラスには、ピクセルデータ値を操作するための一連のメソッドがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

234

ビットマップの操作

個々のピクセルの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ピクセルレベルでビットマップイメージの外観を変更するには、最初に、操作対象の領域にあるピクセルのカラー値を取得する必要があります。これらのピクセルの値を読み取るには、getPixel() メソッドを使用します。

getPixel() メソッドは、パラメーターとして渡される x, y（ピクセル）座標から RGB 値を取得します。操作対象のピクセルのいずれかに透明度、つまりアルファチャンネルの情報が含まれている場合は、getPixel32() メソッドを使用する必要があります。このメソッドは RGB 値も取得しますが、getPixel() とは異なり、getPixel32() によって返される値には、選択されたピ
クセルのアルファチャンネル（透明度）値を示す追加データがあります。
または、ビットマップに含まれるピクセルの色または透明度だけを変更するのであれば、setPixel() または setPixel32() メソッドを使用します。ピクセルの色を設定するには、いずれかのメソッドに x, y 座標とカラー値を渡すだけです。
次の例では、setPixel() を使用して、緑の BitmapData 背景に十字形を描画します。その後、getPixel() を使用して、座標値
が 50, 50 のピクセルからカラー値を取得し、戻り値をトレースします。
import flash.display.Bitmap;
import flash.display.BitmapData;var myBitmapData:BitmapData = new BitmapData(100, 100, false, 0x009900);
for (var i:uint = 0; i < 100; i++){var red:uint = 0xFF0000;
myBitmapData.setPixel(50, i, red);
myBitmapData.setPixel(i, 50, red);}var myBitmapImage:Bitmap = new Bitmap(myBitmapData);
addChild(myBitmapImage);var pixelValue:uint = myBitmapData.getPixel(50, 50);
trace(pixelValue.toString(16));

単一ピクセルではなく、ピクセルのグループの値を読み取る場合は、getPixels() メソッドを使用します。このメソッドは、
パラメーターとして渡されるピクセルデータの矩形領域からバイト配列を生成します。バイト配列の各エレメント、つまりピクセル値は、符号なしの整数、つまり 32 ビットの乗算されていないピクセル値です。
反対に、ピクセルのグループの値を変更（または設定）するには、setPixels() メソッドを使用します。このメソッドは rect お
よび inputByteArray の 2 つのパラメーターを想定しています。これらのパラメーターを組み合わせて、ピクセルデータ（inputByteArray）の矩形領域（rect）を出力します。
データが inputByteArray から読み取られ、書き込まれると、配列内の各ピクセルに対して ByteArray.readUnsignedInt() メ
ソッドが呼び出されます。何らかの理由により、inputByteArray に矩形全体に相応するピクセルデータが含まれていない場
合は、メソッドはその段階でイメージデータの処理を停止します。
重要な点は、ピクセルデータの取得と設定では、バイト配列は 32 ビットのアルファ、赤、緑、青（ARGB）ピクセル値を想定していることです。
次の例では、getPixels() メソッドと setPixels() メソッドを使用して、ある BitmapData オブジェクトから別の BitmapData
オブジェクトにピクセルのグループをコピーします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

235

ビットマップの操作

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.utils.ByteArray;
import flash.geom.Rectangle;
var bitmapDataObject1:BitmapData = new BitmapData(100, 100, false, 0x006666FF);
var bitmapDataObject2:BitmapData = new BitmapData(100, 100, false, 0x00FF0000);
var rect:Rectangle = new Rectangle(0, 0, 100, 100);var bytes:ByteArray = bitmapDataObject1.getPixels(rect);bytes.position = 0;
bitmapDataObject2.setPixels(rect, bytes);var bitmapImage1:Bitmap = new Bitmap(bitmapDataObject1);
addChild(bitmapImage1);
var bitmapImage2:Bitmap = new Bitmap(bitmapDataObject2);
addChild(bitmapImage2);
bitmapImage2.x = 110;

ピクセルレベルの衝突検出
Flash Player 9 以降、Adobe AIR 1.0 以降
BitmapData.hitTest() メソッドは、ビットマップデータと別のオブジェクトまたはポイント間でピクセルレベルの衝突を検出します。

BitmapData.hitTest() メソッドは、次の 5 つのパラメーターを受け入れます。

• firstPoint（ポイント）：このパラメーターは、最初の BitmapData の左上のピクセル位置であり、ヒットテストが実行される場所を指します。

• firstAlphaThreshold（uint）：このパラメーターは、このヒットテストで不透明と見なされるアルファチャンネルの最大値です。

• secondObject（オブジェクト）：このパラメーターは、影響を受ける領域を示します。secondObject オブジェクトは、
Rectangle、Point、Bitmap または BitmapData オブジェクトです。このオブジェクトは、衝突検出が実行されるヒッ
ト領域を指します。

• secondBitmapDataPoint（ポイント）：このパラメーターはオプションであり、2 番目の BitmapData オブジェクトのピク
セル位置を指定します。このパラメーターは、secondObject の値が BitmapData オブジェクトである場合にのみ使用します。デフォルト値は null です。

• secondAlphaThreshold（uint）：このパラメーターはオプションであり、2 番目の BitmapData オブジェクトで不透明と見なされるアルファチャンネルの最大値です。デフォルト値は 1 です。このパラメーターは、secondObject の値がBitmapData オブジェクトで、両方の BitmapData オブジェクトが透明である場合にのみ使用します。
不透明なイメージで衝突を検出する場合、ActionScript はイメージを完全に不透明な矩形または境界ボックスとして扱います。または、透明なイメージでピクセルレベルのヒットテストを実行する場合は、両方のイメージが透明である必要があります。これに加え、ActionScript ではアルファしきい値パラメーターを使用し、ピクセルがどの段階で透明から不透明に変わるかを決定します。
次の例では、3 つのビットマップイメージを作成し、false を返す衝突ポイントと true を返す衝突ポイントを使用してピクセ
ル衝突を確認します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

236

ビットマップの操作

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.geom.Point;
var bmd1:BitmapData = new BitmapData(100, 100, false, 0x000000FF);
var bmd2:BitmapData = new BitmapData(20, 20, false, 0x00FF3300);
var bm1:Bitmap = new Bitmap(bmd1);
this.addChild(bm1);// Create a red square.
var redSquare1:Bitmap = new Bitmap(bmd2);
this.addChild(redSquare1);
redSquare1.x = 0;// Create a second red square.
var redSquare2:Bitmap = new Bitmap(bmd2);
this.addChild(redSquare2);
redSquare2.x = 150;
redSquare2.y = 150;// Define the point at the top-left corner of the bitmap.
var pt1:Point = new Point(0, 0);// Define the point at the center of redSquare1.
var pt2:Point = new Point(20, 20);// Define the point at the center of redSquare2.
var pt3:Point = new Point(160, 160);
trace(bmd1.hitTest(pt1, 0xFF, pt2)); // true
trace(bmd1.hitTest(pt1, 0xFF, pt3)); // false

ビットマップデータのコピー
Flash Player 9 以降、Adobe AIR 1.0 以降
イメージ間でビットマップデータをコピーするには、clone()、copyPixels()、copyChannel()、draw() および

drawWithQuality() の各メソッドを使用できます（drawWithQuality メソッドは Flash Player 11.3 以降および AIR 3.3 以降で使用可能）。
その名のとおり、clone() メソッドを使用すると、BitmapData オブジェクト間でビットマップデータのクローンの作成やサンプリングを実行できます。このメソッドが呼び出されると、コピー元のインスタンスの同一クローンである新しい

BitmapData オブジェクトが返されます。
次の例では、親であるオレンジ色の正方形のクローンを作成し、そのクローンを元の親正方形の横に配置します。
import flash.display.Bitmap;
import flash.display.BitmapData;var myParentSquareBitmap:BitmapData = new BitmapData(100, 100, false, 0x00ff3300);
var myClonedChild:BitmapData = myParentSquareBitmap.clone();var myParentSquareContainer:Bitmap = new Bitmap(myParentSquareBitmap);
this.addChild(myParentSquareContainer);var myClonedChildContainer:Bitmap = new Bitmap(myClonedChild);
this.addChild(myClonedChildContainer);
myClonedChildContainer.x = 110;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

237

ビットマップの操作

copyPixels() メソッドは、BitmapData オブジェクト間でピクセルをすばやく、かつ簡単にコピーできます。このメソッド
は、sourceRect パラメーターで定義された、元のイメージの矩形のスナップショットを取得し、同一サイズの別の矩形領域にコピーします。新たに「ペーストされた」矩形の場所は、destPoint パラメーター内で指定されます。
copyChannel() メソッドは、ソース BitmapData オブジェクトから定義済みのカラーチャンネル値（アルファ、赤、緑または青）をサンプリングし、それをターゲット BitmapData オブジェクトのチャンネルにコピーします。このメソッドを呼び出しても、ターゲット BitmapData オブジェクトの他のチャンネルには影響しません。
draw() メソッドと drawWithQuality() メソッドは、元のスプライト、ムービークリップまたはその他の表示オブジェクトのグラフィックコンテンツを、新しいビットマップに描画（レンダリング）します。matrix、colorTransform、blendMode およびターゲット clipRect パラメーターを使用すると、新しいビットマップのレンダリング方法を変更することができます。このメソッドでは、Flash Player および AIR でベクターレンダラーを使用してデータを生成します。
draw() または drawWithQuality() を呼び出すと、次のように、スプライト、ムービークリップまたはその他の表示オブジェ
クトといったソースオブジェクトを最初のパラメーターとして渡します。
myBitmap.draw(movieClip);

ソースオブジェクトが最初にロードされてから、色やマトリックスなどが変換されている場合は、変換内容は新しいオブジェクトにコピーされません。新しいビットマップに変換内容をコピーするには、元のオブジェクトの transform プロパティの値を、新しい BitmapData オブジェクトを使用する Bitmap オブジェクトの transform プロパティにコピーする必要があります。

ビットマップデータの圧縮
Flash Player 11.3 以降、AIR 3.3 以降
flash.display.BitmapData.encode() メソッドを使用すると、ビットマップデータを次のいずれかのイメージ圧縮形式にネイ
ティブに圧縮できます。

• PNG - PNG 圧縮を使用します。必要に応じて、ファイルサイズよりも圧縮速度を重視した高速圧縮を使用します。
PNG 圧縮を使用するには、新しい flash.display.PNGEncoderOptions オブジェクトを BitmapData.encode() メソッドの 2 番
目のパラメーターとして渡します。

• JPEG - JPEG 圧縮を使用します。必要に応じて、イメージの画質を指定します。JPEG 圧縮を使用するには、新しいflash.display.JPEGEncoderOptions オブジェクトを BitmapData.encode() メソッドの 2 番目のパラメーターとして渡します。
• JPEGXR - JPEG Extended Range（XR）圧縮を使用します。必要に応じて、カラーチャンネル、非可逆およびエント
ロピーの設定を指定します。JPEGXR 圧縮を使用するには、新しい flash.display.JPEGXREncoderOptions オブジェクトをBitmapData.encode() メソッドの 2 番目のパラメーターとして渡します。
この機能は、サーバーのアップロードまたはダウンロードのワークフローの一部として、イメージ処理で使用できます。
次のサンプルスニペットでは、JPEGEncoderOptions を使用して BitmapData オブジェクトを圧縮します。
// Compress a BitmapData object as a JPEG file.
var bitmapData:BitmapData = new BitmapData(640,480,false,0x00FF00);
var byteArray:ByteArray = new ByteArray();bitmapData.encode(new Rectangle(0,0,640,480), new flash.display.JPEGEncoderOptions(), byteArray);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

238

ビットマップの操作

ノイズ関数によるテクスチャの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
ビットマップの外観を変えるには、noise() メソッドまたは perlinNoise() メソッドのいずれかを使用してノイズ効果を適用します。ノイズ効果とは、チューニングされていないテレビ画面に表示されるノイズのようなものです。
ビットマップにノイズ効果を適用するには、noise() メソッドを使用します。このメソッドは、ビットマップイメージの指定領域内のピクセルに対し、ランダムカラー値を適用します。
このメソッドは、次の 5 つのパラメーターを受け入れます。

• randomSeed（int）：パターンを決定するランダムシード数です。その名に反し、同じ数が渡されると実際には同じ結果が生成されます。真にランダムな結果を得るには、Math.random() メソッドを使用し、このパラメーターに乱数を渡します。

• low（uint）：このパラメーターは、0 から 255 までの各ピクセルに対して生成される最小値を示します。デフォルト値は0 です。この値を小さく設定すると暗いノイズパターンになり、大きい値に設定すると明るいパターンになります。
• high（uint）：このパラメーターは、0 から 255 までの各ピクセルに対して生成される最大値を示します。デフォルト値
は 255 です。この値を小さく設定すると暗いノイズパターンになり、大きい値に設定すると明るいパターンになります。
• channelOptions（uint）：このパラメーターは、ノイズパターンを適用する、ビットマップオブジェクトのカラーチャン
ネルを指定します。値は、4 つの ARGB カラーチャンネル値の任意の組み合わせです。デフォルト値は 7 です。
• grayScale（ブール値）：true に設定すると、ビットマップピクセルに randomSeed 値を適用し、イメージからすべてのカラーが効果的にウォッシュアウトされます。このパラメーターはアルファチャンネルに影響しません。デフォルト値はfalse です。
次の例では、ビットマップイメージを作成し、青いノイズパターンを適用します。
package{import flash.display.Sprite;
import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.display.BitmapDataChannel;
public class BitmapNoise1 extends Sprite{
public function BitmapNoise1(){
var myBitmap:BitmapData = new BitmapData(250, 250,false, 0xff000000);
myBitmap.noise(500, 0, 255, BitmapDataChannel.BLUE,false);
var image:Bitmap = new Bitmap(myBitmap);
addChild(image);}}}

より有機的な外観のテクスチャを作成するには、perlinNoise() メソッドを使用します。perlinNoise() メソッドは、煙、雲、
水、火、あるいは爆発といった効果に最適な、リアルで有機的なテクスチャを生成します。

perlinNoise() メソッドはアルゴリズムによって生成されるので、ビットマップベースのテクスチャよりもメモリ消費量を抑えられます。ただし、プロセッサーの使用に影響を与えるので、コンテンツを低速化し、特に古いコンピューターではフレームレートよりも画面の再描画速度が遅くなります。これは主に、Perlin ノイズアルゴリズムの処理に必要な浮動小数点計算によるものです。
このメソッドは、次の 9 つのパラメーターを受け入れます。最初の 6 つのパラメーターは必須です。

• baseX（数値）：作成されるパターンの x（サイズ）値を指定します。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

239

ビットマップの操作• baseY（数値）：作成されるパターンの y（サイズ）値を指定します。
• numOctaves（uint）：このノイズを作成するために組み合わせるオクターブ（個々のノイズ関数）の数です。オクターブ
数を多くすると、より詳細なイメージを作成できますが、処理時間も長くなります。

• randomSeed（int）：ランダムシードの数値の働きは、noise() 関数での働きと同じです。真にランダムな結果を得るには、
Math.random() メソッドを使用し、このパラメーターに乱数を渡します。

• stitch（ブール値）：true に設定すると、このメソッドはイメージのトランジションエッジをスティッチ（またはスムージング）してシームレスなテクスチャを作成し、ビットマップ塗りとして分割します。

• fractalNoise（ブール値）：このパラメーターは、メソッドによって生成されたグラデーションのエッジに関連します。
true に設定すると、効果のエッジをスムージングするフラクタルノイズを生成します。false に設定すると、乱流を生成します。乱流があるイメージにはグラデーションに視覚的な不連続性があるので、炎や海の波のようなシャープな視覚効果に適している場合があります。

• channelOptions（uint）：channelOptions パラメーターの働きは、noise() メソッドでの働きと同じです。ノイズパターンが適用される、ビットマップのカラーチャンネルを指定します。値は、4 つの ARGB カラーチャンネル値の任意の組み合わせです。デフォルト値は 7 です。
• grayScale（ブール値）：grayScale パラメーターの働きは、noise() メソッドでの働きと同じです。true に設定すると、ビッ
トマップピクセルに randomSeed 値が適用され、イメージからすべての色が効果的にウォッシュアウトされます。デフォ
ルト値は false です。

• offsets（配列）：各オクターブの x オフセットと y オフセットに対応するポイントの配列です。オフセット値を操作することで、イメージのレイヤーをスムーズにスクロールできます。オフセット配列内の各ポイントは、特定のオクターブノ
イズ関数に影響を与えます。デフォルト値は null です。
次の例では、perlinNoise() メソッドを呼び出して緑と青の雲効果を生成する、150 x 150 ピクセルの BitmapData オブジェ
クトを作成します。
package{import flash.display.Sprite;
import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.display.BitmapDataChannel;
public class BitmapNoise2 extends Sprite{
public function BitmapNoise2(){
var myBitmapDataObject:BitmapData =new BitmapData(150, 150, false, 0x00FF0000);
var seed:Number = Math.floor(Math.random() * 100);var channels:uint = BitmapDataChannel.GREEN | BitmapDataChannel.BLUE
myBitmapDataObject.perlinNoise(100, 80, 6, seed, false, true, channels, false, null);var myBitmap:Bitmap = new Bitmap(myBitmapDataObject);addChild(myBitmap);}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

240

ビットマップの操作

ビットマップのスクロール
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーが地図を動かすたびに、その移動幅がわずか数ピクセルであったとしても、ビューを更新しなければならないようなストリートマッピングアプリケーションを作成したとします。
この機能を実現するには、ユーザーが地図を動かすたびに、更新された部分を含む新しいイメージを再レンダリングするという方法があります。または、1 つの大きなイメージを作成して scroll() メソッドを使用する方法もあります。

scroll() メソッドは画面上のビットマップをコピーし、それを x, y パラメーターで指定する新しいオフセット位置にペーストします。ビットマップの一部がステージ外にあると、イメージがシフトされた効果をもたらします。タイマー制御関数または enterFrame イベントと組み合わせると、イメージがアニメーション化またはスクロールしているように見せることができます。
次の例では、前述の Perlin ノイズの例から大きなビットマップイメージを作成します。イメージの 4 分の 3 がステージ外でレンダリングされます。scroll() メソッドと、斜め下方向に 1 ピクセル分イメージをオフセットする enterFrame イベントリス
ナーが適用されます。このメソッドはフレームが入力されるたびに呼び出されるので、画面外にあるイメージは、イメージが下方向にスクロールされるとステージにレンダリングされます。
import flash.display.Bitmap;
import flash.display.BitmapData;var myBitmapDataObject:BitmapData = new BitmapData(1000, 1000, false, 0x00FF0000);
var seed:Number = Math.floor(Math.random() * 100);var channels:uint = BitmapDataChannel.GREEN | BitmapDataChannel.BLUE;
myBitmapDataObject.perlinNoise(100, 80, 6, seed, false, true, channels, false, null);var myBitmap:Bitmap = new Bitmap(myBitmapDataObject);
myBitmap.x = -750;
myBitmap.y = -750;
addChild(myBitmap);
addEventListener(Event.ENTER_FRAME, scrollBitmap);function scrollBitmap(event:Event):void{
myBitmapDataObject.scroll(1, 1);}

ミップマッピングの利用
Flash Player 9 以降、Adobe AIR 1.0 以降
MIP マップ（ミップマップとも呼ばれる）は、実行時のレンダリング品質とパフォーマンスを高めるためにテクスチャに関連付けられたビットマップの集合です。MIP マップ内の各ビットマップイメージはメインビットマップイメージのバージョンの 1 つですが、詳細レベルはメインイメージよりも低下します。
例えば、MIP マップには 64 × 64 ピクセルの最高画質のメインイメージを含めることができます。この場合、MIP マップ
内のその他のイメージは、より低画質の 32 × 32、16 × 16、8 × 8、4 × 4、2 × 2 および 1 × 1 ピクセルになります。
テクスチャストリーミング

は、最も画質の低いビットマップを最初にロードしてから、より画質の高いビットマップをロードしてプログレッシブに表示する機能です。画質の低いビットマップはサイズが小さいので、メインイメージよりも高速にロードされます。したがって、アプリケーションユーザーは、メインの高画質のビットマップがロードされる前に、ア
プリケーションにイメージを表示できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

241

ビットマップの操作

Flash Player 9.115.0 以降のバージョンおよび AIR にはこの技術が実装され（このプロセスはミップマッピングと呼ばれる）、各ビットマップのサイズが異なる最適化されたバージョンが作成されます。サイズは 50% から始まります。
Flash Player 11.3 および AIR 3.3 では、Context3D.createCubeTexture() メソッドと Context3D.createTexture() メソッドのstreamingLevels パラメーターを通じてテクスチャストリーミングがサポートされます。
テクスチャの圧縮では、テクスチャのイメージを圧縮形式で GPU に直接保存することにより、GPU のメモリとメモリ帯域
幅の消費を抑えることができます。通常圧縮テクスチャはオフラインで圧縮され、圧縮形式で GPU にアップロードされます。ただし、Flash Player 11.4 および AIR 3.4 はランタイムのテクスチャ圧縮をサポートします。これはベクターアートからのダイナミックテクスチャのレンダリングなど、特定の状況で使用すると便利です。ランタイムのテクスチャ圧縮を使用するには、以下の手順を実行します。

• Context3D.createTexture() メソッドを呼び出してテクスチャオブジェクトを作成し、3 番目のパラメーターでflash.display3D.Context3DTextureFormat.COMPRESSED または
flash.display3D.Context3DTextureFormat.COMPRESSED_ALPHA のどちらかに渡します。

• createTexture() から返される flash.display3D.textures.Texture インスタンスを使用して、flash.display3D.textures.Texture.uploadFromBitmapData() または flash.display3D.textures.Texture.uploadFromByteArray() のどちらかを呼び出します。これらのメソッドはテクスチャのアップロードと圧縮を 1 つのステップで行います。

MIP マップは、次の種類のビットマップに対して作成されます。

• ActionScript 3.0 Loader クラスを使用して表示されるビットマップ（JPEG、GIF または PNG ファイル）• Flash Professional ドキュメントのライブラリに含まれるビットマップ• BitmapData オブジェクト• ActionScript 2.0 の loadMovie() 関数を使用して表示されるビットマップ
MIP マップは、フィルターが適用されたオブジェクトまたはビットマップキャッシュされたムービークリップには適用されません。ただし、フィルターが適用された表示オブジェクト内にビットマップ変換が含まれている場合は、そのビットマッ
プがマスクされたコンテンツ内にある場合でも、MIP マップが適用されます。
ミップマッピングは自動的に行われますが、次のガイドラインに準拠していれば、イメージでこの最適化手法を確実に利用
できます。

•
•

ビデオ再生の場合、Video オブジェクトの smoothing プロパティを true に設定します（Video クラスを参照）。
ビットマップの場合は、smoothing プロパティを true に設定する必要はありませんが、スムージングを利用した方が品質が明らかに向上します。

• 2 次元イメージの場合は、ビットマップサイズを 4 または 8 で割り切れるサイズにします（例えば 640 x 128 では、
320 x 64 > 160 x 32 > 80 x 16 > 40 x 8 > 20 x 4 > 10 x 2 > 5 x 1 のようにサイズを縮小できます）。
3 次元テクスチャの場合は、各イメージの解像度が 2 の累乗（2^n）である MIP マップを使用します。例えば、メインイメージの解像度が 1024 x 1024 ピクセルであるとします。MIP マップ内のイメージが合計 11 個の場合、MIP マップ
内のその他のイメージは、より低画質の 512 x 512、256 x 256、128 x 128、1 x 1 ピクセルになります。
幅または高さが奇数であるビットマップコンテンツに対しては、ミップマッピングは行われません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

242

ビットマップの操作

ビットマップの例：回転する月のアニメーション
Flash Player 9 以降、Adobe AIR 1.0 以降
回転する月のアニメーションの例では、Bitmap オブジェクトとビットマップイメージデータ（BitmapData オブジェクト）を操作する手法について説明します。この例では、平らな月面のイメージを未処理のイメージデータとして使用し、回転する球体の月のアニメーションを作成します。次の手法について説明します。

•

外部イメージの読み込みと未処理のイメージデータへのアクセス•

ソースイメージの様々な部分からピクセルを繰り返しコピーすることによるアニメーションの作成•

ピクセル値の設定によるビットマップイメージの作成

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。回転する月のアニメーションに関するアプリケーションファイルは Samples/SpinningMoon フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

SpinningMoon.mxml

Flex（MXML）または Flash（FLA）のメインアプリケーションファイル。

またはSpinningMoon.fla
com/example/programmingas3/moon/MoonSphere.as

月の読み込み、表示、アニメーション機能を実行するクラス。

moonMap.png

月面写真が含まれるイメージファイル。このファイルを読み込み、回転する月のアニメーション作成に使用します。

ビットマップデータとしての外部イメージの読み込みFlash Player 9 以降、Adobe AIR 1.0 以降
このサンプルで実行する最初の主要なタスクは、外部イメージファイル（月面写真）の読み込みです。読み込み操作は、MoonSphere クラスの 2 つのメソッドである読み込みプロセスを開始する MoonSphere() コンストラクターと、外部イメー
ジが完全に読み込まれたときに呼び出される imageLoadComplete() メソッドによって処理されます。
外部イメージの読み込みは外部 SWF のロードに類似しており、いずれも flash.display.Loader クラスのインスタンスを使用して読み込み操作を実行します。イメージの読み込みを開始する MoonSphere() メソッドの実際のコードは次のとおりです。
var imageLoader:Loader = new Loader();
imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoadComplete);imageLoader.load(new URLRequest("moonMap.png"));

最初の行で imageLoader という名前の Loader インスタンスを宣言します。3 行目で、Loader オブジェクトの load() メソッ
ドを呼び出して実際に読み込みプロセスを開始し、読み込むイメージの URL を表す URLRequest インスタンスを渡します。2 行目では、イメージが完全に読み込まれたときにトリガーされるイベントリスナーを設定します。Loader インスタン
ス自体では addEventListener() メソッドは呼び出されず、Loader オブジェクトの contentLoaderInfo プロパティで呼び出されます。Loader インスタンス自体は、読み込み中のコンテンツに関連するイベントを送出しません。ただし、そのcontentLoaderInfo プロパティには、Loader オブジェクトに読み込まれるコンテンツ（この場合は外部イメージ）に関連付けられた LoaderInfo オブジェクトに対する参照が含まれます。LoaderInfo オブジェクトは、イメージが完全に読み込まれたときに imageLoadComplete() メソッドの呼び出しをトリガーする complete イベント（Event.COMPLETE）など、外部コン
テンツの読み込みの進捗や完了に関連するいくつかのイベントを提供します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

243

ビットマップの操作

外部イメージの読み込みを開始することは、このプロセスにおいて重要ですが、読み込みの終了時の動作を把握しておくことも同様に重要です。前のコードに示したように、イメージが読み込まれると、imageLoadComplete() 関数が呼び出されます。この関数は、読み込まれたイメージデータについて、以下で説明するいくつかの操作を行います。ただし、イメージデータを使用するには、そのデータにアクセスする必要があります。Loader オブジェクトを使用して外部イメージを読み込
むと、読み込まれたイメージが Bitmap インスタンスになり、これが Loader オブジェクトの子表示オブジェクトとして関連付けられます。この場合、Loader インスタンスは、メソッドにパラメーターとして渡されるイベントオブジェクトの一部
としてイベントリスナーメソッドに使用できます。imageLoadComplete() メソッドの最初の行は次のとおりです。
private function imageLoadComplete(event:Event):void{
textureMap = event.target.content.bitmapData;...
}

イベントオブジェクトのパラメーターの名前は event で、これは Event クラスのインスタンスです。Event クラスのすべてのインスタンスには target プロパティがあります。これは、イベント（この場合は、前述のように addEventListener() メソッ
ドが呼び出される LoaderInfo インスタンス）をトリガーするオブジェクトを参照します。LoaderInfo オブジェクトには、読み込まれたビットマップイメージと共に Bitmap インスタンスが含まれる content プロパティがあります（読み込みプロセスが完了した場合）。イメージを画面に直接表示する場合は、この Bitmap インスタンス（event.target.content）を表示オブ
ジェクトコンテナに関連付けることができます（Loader オブジェクトを表示オブジェクトコンテナに関連付けることもできます）。ただし、このサンプルでは、読み込まれたコンテンツは画面上に表示されるのではなく、未処理イメージデータのソースとして使用されます。したがって、imageLoadComplete() メソッドの最初の行は、読み込まれた Bitmap インスタンス（event.target.content.bitmapData）の bitmapData プロパティを読み取り、これを textureMap という名前のインスタンス変数に格納します。この変数は、回転する月のアニメーションを作成するためのイメージデータのソースとして使用されます。
これについては、次に説明します。

ピクセルのコピーによるアニメーションの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
アニメーションの基本的な定義は、イメージを徐々に変化させることによって、動いている、または変化しているように見せることです。このサンプルでは、球体の月がその垂直軸を中心に回転しているように見せることが目標です。ただし、このアニメーションでは、サンプルの球体の歪みは無視できます。月のイメージデータのソースとして実際に読み込んで使用するイメージを次に示します。

ここからわかるように、イメージは 1 つまたは複数の球体ではなく、月面の長方形の写真です。この写真は月の赤道で撮影されたものなので、イメージの上下に近い部分は引き伸ばされ、歪んでいます。イメージから歪みを削除し、球体に見えるようにするには、後で説明するように置き換えマップフィルターを使用します。ただし、このソースイメージは長方形なので、球体が回転しているように見せるには、コードで月面写真を水平方向に移動する必要があります。
このイメージには、実際には月面写真のコピーが 2 つ並んで含まれています。このイメージはソースイメージであり、ここからイメージデータを繰り返しコピーして、動いている様子を作成します。イメージの 2 つのコピーを並べることにより、連続した、中断されないスクロール効果をより簡単に作成できます。アニメーションのプロセスを順を追って説明し、その動作を確認していきます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

244

ビットマップの操作

このプロセスには、実際には 2 つの個別の ActionScript オブジェクトが関連しています。まず読み込まれたソースイメージがあり、このコードでは、textureMap という名前の BitmapData インスタンスによって表されます。前述のように、外部イメージが読み込まれると、直ちにイメージデータが textureMap に入力されます。
textureMap = event.target.content.bitmapData;

textureMap のコンテンツは、長方形の月のイメージです。さらに、回転のアニメーションを作成するために、月のイメージを画面上に表示する実際の表示オブジェクトである、sphere という名前の Bitmap インスタンスをコードで使用します。

textureMap と同様に sphere オブジェクトが作成され、次のコードを使用して、imageLoadComplete() メソッドの初期イメー
ジデータが入力されます。
sphere = new Bitmap();
sphere.bitmapData = new BitmapData(textureMap.width / 2, textureMap.height);
sphere.bitmapData.copyPixels(textureMap,
new Rectangle(0, 0, sphere.width, sphere.height),
new Point(0, 0));

コードに示されているように、sphere はインスタンス化されます。その bitmapData プロパティ（sphere によって表示される
未処理のイメージデータ）が、textureMap と同じ高さと半分の幅で作成されます。つまり、textureMap イメージには並べられた 2 枚の月面写真が含まれているので、sphere のコンテンツは 1 枚の写真のサイズになります。次に、bitmapData プロパ
ティに、その copyPixels() メソッドを使用してイメージデータが入力されます。copyPixels() メソッド呼び出しのパラメー
ターは次のことを示します。

•

最初のパラメーターは、イメージデータが textureMap からコピーされたことを示します。

• 2 番目のパラメーター（新規の Rectangle インスタンス）は、textureMap のどの部分からイメージスナップショットを取得するかを指定します。この場合は、スナップショットは、textureMap の左上隅（最初の 2 つの Rectangle() パラメー
ター 0, 0 で示される）から始まる長方形で、その長方形スナップショットの幅と高さは、sphere の width および height プ
ロパティに一致します。

• 3 番目のパラメーター（x および y 値が 0 の新規の Point インスタンス）は、ピクセルデータのターゲットを定義します。
この場合は、sphere.bitmapData の左上隅（0, 0）です。
視覚的に表現すると、このコードは、次のイメージに示す textureMap からピクセルをコピーし、sphere に貼り付けます。つまり、sphere の BitmapData コンテンツは、ここで強調表示した textureMap の一部です。

ただし、これは sphere の初期状態にすぎません。つまり、sphere にコピーされる最初のイメージコンテンツです。
ソースイメージを読み込んで sphere を作成すると、imageLoadComplete() メソッドによって実行される最後のタスクは、アニメーションの設定になります。アニメーションは、次のコードによって作成および開始される、rotationTimer という名前の Timer インスタンスによって制御されます。
var rotationTimer:Timer = new Timer(15);rotationTimer.addEventListener(TimerEvent.TIMER, rotateMoon);rotationTimer.start();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

245

ビットマップの操作

このコードは、最初に rotationTimer という名前の Timer インスタンスを作成します。Timer() コンストラクターに渡されたパラメーターは、rotationTimer がその timer を 15 ミリ秒ごとにトリガーすることを示します。次に addEventListener() メ
ソッドが呼び出され、timer イベント（TimerEvent.TIMER）が発生したときにメソッド rotateMoon() を呼び出すことを指定します。最後に、start() メソッドを呼び出すことにより、タイマーを実際に起動します。

rotationTimer の定義に従って、月のアニメーションが実行される MoonSphere クラスの rotateMoon() メソッドを Flash
Player が約 15 ミリ秒ごとに呼び出します。rotateMoon() メソッドのソースコードは次のとおりです。
private function rotateMoon(event:TimerEvent):void{
sourceX += 1;
if (sourceX > textureMap.width / 2){
sourceX = 0;}
sphere.Data.copyPixels(textureMap,
new Rectangle(sourceX, 0, sphere.width, sphere.height),
new Point(0, 0));event.updateAfterEvent();}

このコードによって次の 3 つの操作が行われます。

1 変数 sourceX の値（初期値は 0 に設定）が 1 ずつ大きくなります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

246

ビットマップの操作

sourceX += 1;

後で説明するように、sourceX は、sphere にピクセルをコピーする textureMap での元の位置を指定するので、このコードによって、textureMap で長方形が 1 ピクセル右に移動します。視覚的な表現で説明すると、数サイクルのアニメーショ
ンの後、ソース長方形は次のように数ピクセル右に移動します。

その数サイクル後には、長方形はさらに遠くに移動します。

このようにピクセルのコピー元を徐々に絶えず移動することが、アニメーションでは非常に重要です。ソースの位置をゆっくりと継続して右方向に移動することにより、sphere の画面に表示されるイメージは、左方向に絶え間なく移動しているように見えます。月面写真の 2 つのコピーがソースイメージ（textureMap）に必要なのはこのためです。長方形が絶え間なく右方向に移動しているので、ほとんどの時間は、長方形は 1 つの月面写真ではなく、2 つの月面写真に重なっています。

2 ソース長方形が右方向にゆっくりと移動すると、1 つの問題が発生します。最終的に長方形が textureMap の右端に達し、
sphere にコピーする月面写真のピクセルがなくなります。

次のコード行でこの問題を解決します。
if (sourceX >= textureMap.width / 2){
sourceX = 0;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

247

ビットマップの操作

このコードは、sourceX（長方形の左端）が textureMap の中央に達したかどうかをチェックします。達した場合は、

sourceX を 0 にリセットし、textureMap の左端に戻して、サイクルを再開します。

3 適切な sourceX 値を計算したら、アニメーション作成の最後の手順は、新しいソース長方形のピクセルを sphere に実際にコピーすることです。この操作を実行するコードは、最初に sphere にデータを入力したコードとよく似ています（前述）。唯一異なる点は、new Rectangle() コンストラクター呼び出しで長方形の左端が sourceX に置かれることです。
sphere.bitmapData.copyPixels(textureMap,
new Rectangle(sourceX, 0, sphere.width, sphere.height),
new Point(0, 0));

このコードは 15 ミリ秒ごとに繰り返し呼び出されます。ソース長方形の位置が絶え間なく移動し、ピクセルが sphere にコピーされると、画面上では sphere が表す月面写真イメージが絶え間なく流れ続けます。つまり、月が回転し続けているように見えます。

球体の外観の作成
Flash Player 9 以降、Adobe AIR 1.0 以降
当然ながら、月は球体であり、長方形ではありません。したがって、サンプルでは、アニメーション化を続けながら、長方形の月面写真を取得し、球体に変換する必要があります。このためには 2 つの個別の手順が必要です。マスクを使用して、月面写真の円形の領域を除くすべてのコンテンツを非表示にし、置き換えマップフィルターを使用して月面写真の外観を歪め、3 次元に見えるようにします。
最初に、円形マスクを使用して、フィルターによって作成された球体を除く、MoonSphere オブジェクトのすべてのコンテンツを非表示にします。次のコードは、マスクを Shape インスタンスとして作成し、これを MoonSphere インスタンスのマスクとして適用します。
moonMask = new Shape();moonMask.graphics.beginFill(0);moonMask.graphics.drawCircle(0, 0, radius);
this.addChild(moonMask);
this.mask = moonMask;

MoonSphere は Sprite クラスに基づく表示オブジェクトなので、継承した mask プロパティを使用して、マスクを
MoonSphere インスタンスに直接適用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

248

ビットマップの操作

円形のマスクを使用して写真の一部を非表示にするだけでは、回転する球体のリアルな効果を作成するには不十分です。月
面写真の撮影方法により、写真のサイズは実際のサイズに比例していません。イメージの上下に近い部分は、赤道部分よりも大きく歪み、引き伸ばされています。月面写真の外観を歪ませて、3 次元に見えるようにするために、置き換えマップ
フィルターを使用します。
置き換えマップフィルターは、イメージを歪ませるために使用するフィルターです。この場合は、中央を変化させずにイ
メージの上下を水平方向に押しつぶし、よりリアルに見せるように月面写真を「歪ませ」ます。フィルターが写真の正方形部分に作用するものと仮定すると、中央ではなく上下を押しつぶすことにより、正方形は円に変わります。この歪ませたイ
メージのアニメーション化によって発生する副作用として、イメージの中央が、上下に近い領域よりも、実際のピクセル距
離にして大きく動くように見えます。この結果、円が実際に 3 次元オブジェクト（球体）のように見えます。
次のコードを使用して、displaceFilter という名前の置き換えマップフィルターを作成します。
var displaceFilter:DisplacementMapFilter;
displaceFilter = new DisplacementMapFilter(fisheyeLens,
new Point(radius, 0),
BitmapDataChannel.RED,
BitmapDataChannel.GREEN,
radius, 0);

最初のパラメーター fisheyeLens は、マップイメージと呼ばれます。ここでは、プログラムにより作成される BitmapData
オブジェクトです。そのイメージの作成については、249 ページの「ピクセル値の設定によるビットマップイメージの作成」
で説明します。他のパラメーターは、フィルターイメージ内のフィルターを適用する部分、置き換え効果を制御するために使用するカラーチャンネル、置き換えに影響を与える範囲などを記述します。作成された置き換えマップフィルターは、

imageLoadComplete() メソッドの内部で sphere に適用されます。
sphere.filters = [displaceFilter];

マスクと置き換えマップフィルターが適用された最終的なイメージは次のようになります。

回転する月のアニメーションの 1 サイクルごとに、球体の BitmapData コンテンツがソースイメージデータの新しいスナッ
プショットによって上書きされます。ただし、フィルターを毎回適用し直す必要はありません。これは、フィルターがビット
マップデータ（未処理のピクセル情報）ではなく、Bitmap インスタンス（表示オブジェクト）に適用されるからです。
Bitmap インスタンスは実際のビットマップデータではなく、ビットマップデータを画面に表示する表示オブジェクトです。
例えば、Bitmap インスタンスは、写真のスライドを画面に表示するために使用するスライドプロジェクターのようなもの
で、BitmapData オブジェクトは、スライドプロジェクターを通じて表示できる実際の写真スライドのようなものです。
フィルターは BitmapData オブジェクトに直接適用できます。これは、写真のスライドに直接描画して、イメージを変更するようなものです。フィルターは、Bitmap インスタンスを含む任意の表示オブジェクトにも適用できます。これは、スライドプロジェクターのレンズの前にフィルターを置き、元のスライドは変更しないまま、画面上に表示される出力を歪ませることと似ています。未処理のビットマップデータには Bitmap インスタンスの bitmapData プロパティを通じてアクセスできるので、フィルターを未処理のビットマップデータに直接適用できます。ただし、この場合は、ビットマップデータよりも Bitmap 表示オブジェクトにフィルターを適用することをお勧めします。

ActionScript での置き換えマップフィルターの使用について詳しくは、254 ページの「表示オブジェクトのフィルター処理」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

249

ビットマップの操作

ピクセル値の設定によるビットマップイメージの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
置き換えマップフィルターの重要な特性の 1 つに、このフィルターが実際には 2 つのイメージを必要とする点があります。1
つのイメージ、つまりソースイメージは、フィルターによって実際に変更されるイメージです。このサンプルでは、ソース
イメージは、sphere という名前の Bitmap インスタンスです。フィルターによって使用されるもう 1 つのイメージはマップイメージです。マップイメージは、実際には画面に表示されません。代わりに、その各ピクセルのカラーが置き換え関数への入力として使用され、マップイメージの特定の x, y 座標のピクセルのカラーによって、ソースイメージのその x, y 座標のピ
クセルに適用される置き換え（位置の物理的な移動）の量が決まります。
したがって、置き換えマップフィルターを使用して球体の効果を作成するには、サンプルに適切なマップイメージが必要です。つまり、ここに示すように、背景が灰色で、暗から明に水平方向に変化する 1 つのカラー（赤）のグラデーションで塗りつぶされた円を含むマップイメージです。

このサンプルでは 1 つのマップイメージとフィルターだけが使用されているので、マップイメージは、imageLoadComplete()
メソッドで（つまり、外部イメージの読み込みが完了したときに）1 回だけ作成されます。fisheyeLens という名前のマップ
イメージは、MoonSphere クラスの createFisheyeMap() メソッドを呼び出すことにより作成されます。
var fisheyeLens:BitmapData = createFisheyeMap(radius);

createFisheyeMap() メソッドの内部で、実際のマップイメージは BitmapData クラスの setPixel() メソッドを使用して、一度に 1 ピクセルずつ描画されます。次に createFisheyeMap() メソッドの終了コードを示し、その動作について順を追って説明します。
private function createFisheyeMap(radius:int):BitmapData{var diameter:int = 2 * radius;
var result:BitmapData = new BitmapData(diameter,
diameter,false,
0x808080);// Loop through the pixels in the image one by onefor (var i:int = 0; i < diameter; i++){for (var j:int = 0; j < diameter; j++){// Calculate the x and y distances of this pixel from// the center of the circle (as a percentage of the radius).
var pctX:Number = (i - radius) / radius;
var pctY:Number = (j - radius) / radius;// Calculate the linear distance of this pixel from// the center of the circle (as a percentage of the radius).
var pctDistance:Number = Math.sqrt(pctX * pctX + pctY * pctY);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

250

ビットマップの操作// If the current pixel is inside the circle,// set its color.
if (pctDistance < 1){// Calculate the appropriate color depending on the// distance of this pixel from the center of the circle.
var red:int;
var green:int;
var blue:int;
var rgb:uint;
red = 128 * (1 + 0.75 * pctX * pctX * pctX / (1 - pctY * pctY));green = 0;blue = 0;
rgb = (red << 16 | green << 8 | blue);// Set the pixel to the calculated color.
result.setPixel(i, j, rgb);}}}
return result;}

最初にメソッドが呼び出されると、そのメソッドは、作成する円形イメージの半径を示すパラメーター radius を受け取ります。次に、その上に円を描画する BitmapData オブジェクトが作成されます。result という名前のそのオブジェクトは、最後にはメソッドの戻り値として返されます。次のコードスニペットに示すように、result BitmapData インスタンスは、円の直径と同じ幅と高さで作成され、3 番目のパラメーターが false なので透明度がなく、カラー 0x808080（中間の灰色）であら
かじめ塗りつぶされています。
var result:BitmapData = new BitmapData(diameter,
diameter,false,
0x808080);

次に、コードは 2 つのループを使用し、イメージの各ピクセルに対して繰り返し処理を実行します。外側のループはイメー
ジの各列を左から右に移動し（現在処理中のピクセルの水平位置を表す変数 i を使用します）、内側のループは現在の列の各ピクセルを上から下に移動します（現在のピクセルの垂直位置を表す変数 j を使用します）。次に、ループのコード（内側のループの内容は省略）を示します。
for (var i:int = 0; i < diameter; i++){for (var j:int = 0; j < diameter; j++)
{
...
}
}

ループがピクセルを 1 つずつ進むと、各ピクセルで値（マップイメージでのそのピクセルのカラー値）が計算されます。このプロセスには次の 4 つ手順が含まれます。

1 コードが、円の中心から現在のピクセルまでの距離を x 軸に沿って計算します（i - radius）。この値を半径で割り、絶対距離ではなく、半径のパーセンテージにします（(i - radius) / radius）。次のコードに示すように、そのパーセンテージ値
が pctX という名前の変数に格納され、y 軸の等価の値が計算されて、変数 pctY に格納されます。
var pctX:Number = (i - radius) / radius;
var pctY:Number = (j - radius) / radius;

2 標準的な三角関数の公式、ピタゴラスの定義を使用して、pctX と pctY から円の中心と現在のポイントとの直線距離を計算します。次に示すように、この値が pctDistance という名前の変数に格納されます。
var pctDistance:Number = Math.sqrt(pctX * pctX + pctY * pctY);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

251

ビットマップの操作

3 次に、コードは、距離のパーセンテージが 1 よりも小さいかどうか（半径の 100 ％。つまり、対象のピクセルが円の半径の内部にあるかどうか）をチェックします。ピクセルが円の内部にある場合は、計算されたカラー値がそのピクセルに割り当てられます（ここでは省略しますが、手順 4 で説明します）。内部にない場合は、そのピクセルについては何も実行されないので、そのカラーは、デフォルト値である中間の灰色のままになります。
if (pctDistance < 1){...
}

4 円の内部にあるピクセルでは、そのピクセルについてカラー値が計算されます。最終的なカラーは、円の左端の黒（赤 0％）から円の右端の鮮明な赤（100 ％）までの赤の明暗になります。次に示すように、カラー値は、最初は 3 つの部分
（赤、緑、青）で計算されます。
red = 128 * (1 + 0.75 * pctX * pctX * pctX / (1 - pctY * pctY));green = 0;blue = 0;

実際には、カラーの赤の部分（変数 red）だけに値があります。わかりやすいように、ここでは緑と青の値（変数 green
および blue）を示していますが、省略することもできます。このメソッドの目的は、赤のグラデーションが含まれる円を作成することなので、緑または青の値は不要です。

3 つの個々のカラー値を決定したら、次のコードに示す標準のビットシフトアルゴリズムを使用して、これらの値を 1 つの整数のカラー値に結合できます。
rgb = (red << 16 | green << 8 | blue);

最後にカラー値を計算し、ここに示すように result BitmapData オブジェクトの setPixel() メソッドを使用して、その値を現在のピクセルに実際に割り当てます。
result.setPixel(i, j, rgb);

ビットマップイメージの非同期デコード
Flash Player 11 以降、Adobe AIR 2.6 以降
ビットマップイメージの操作時に、ビットマップイメージの非同期デコードおよびロードを実行して、アプリケーションの体感的なパフォーマンスを向上できます。ビットマップイメージの非同期デコードにかかる時間は、多くの場合は同期デ
コードと同様です。しかしながら、ビットマップイメージの非同期デコードは別のスレッドで実行され、その後、関連付けられた Loader オブジェクトにより COMPLETE イベントが送信されます。したがって、大きなイメージをロード後に非同期にデコードできます。

flash.system パッケージの ImageDecodingPolicy クラスを使用すると、ビットマップのロードスキームを指定できます。デフォルトのロードスキームは「同期」です。
ビットマップのデコードポリシー

ビットマップのロードスキーム

説明

ImageDecodingPolicy.ON_DEMAND

同期

ロードされたイメージは、イメージデータにアクセスするときにデコードされます。
小さなイメージをデコードするには、このポリシーを使用します。また、アプリケー
ションが複雑なエフェクトやトランジションを使用しない場合にも、このポリシーを使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

252

ビットマップの操作

ビットマップのデコードポリシー

ビットマップのロードスキーム

説明

ImageDecodingPolicy.ON_LOAD

非同期

ロードされたイメージは、ロード時（COMPLETE イベントが送出される前）にデコードされます。
大きなイメージ（10 MP 以上）に適しています。ページのトランジションがある AIR
ベースモバイルアプリケーションを開発している場合は、このビットマップロードポ
リシーを使用して、アプリケーションの体
感的なパフォーマンスを改善してください。

注意：ロードされるファイルがビットマップイメージであり、使用するデコードポリシーが ON_LOAD の場合、イメージが非同期にデコードされてから COMPLETE イベントが送出されます。
次のコードは、ImageDecodingPolicy クラスの使用法を示しています。
var loaderContext:LoaderContext = new LoaderContext();
loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD
var loader:Loader = new Loader();loader.load(new URLRequest("http://www.adobe.com/myimage.png"), loaderContext);

Loader.load() メソッドおよび Loader.loadBytes() メソッドを使用して ON_DEMAND デコードを使用することもできます。ただし、LoaderContext オブジェクトを引数として使用する他のすべてのメソッドでは、渡される ImageDecodingPolicy の値が無視されます。
次の例は、ビットマップイメージの同期デコードと非同期デコードの違いを示しています。
package{import flash.display.Loader;import flash.display.Sprite;
import flash.events.Event;import flash.net.URLRequest;
import flash.system.ImageDecodingPolicy;
import flash.system.LoaderContext;
public class AsyncTest extends Sprite{
private var loaderContext:LoaderContext;
private var loader:Loader;private var urlRequest:URLRequest;
public function AsyncTest(){//Load the image synchronously
loaderContext = new LoaderContext();//Default behavior.
loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_DEMAND;
loader = new Loader();loadImageSync();//Load the image asynchronously
loaderContext = new LoaderContext();
loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD;
loader = new Loader();loadImageASync();}
private function loadImageASync():void{
trace("Loading image asynchronously...");
urlRequest = new URLRequest("http://www.adobe.com/myimage.png");
urlRequest.useCache = false;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

253

ビットマップの操作

loader.load(urlRequest, loaderContext);
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onAsyncLoadComplete);}
private function onAsyncLoadComplete(event:Event):void{
trace("Async. Image Load Complete");}private function loadImageSync():void{
trace("Loading image synchronously...");
urlRequest = new URLRequest("http://www.adobe.com/myimage.png");
urlRequest.useCache = false;
loader.load(urlRequest, loaderContext);
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onSyncLoadComplete);}
private function onSyncLoadComplete(event:Event):void{
trace("Sync. Image Load Complete");}}}

各デコードポリシーの効果のデモンストレーションについては、Thibaud Imbert：Asynchronous bitmap decoding in

the Adobe Flash runtimes を参照してください。

最終更新日 2015/10/14

254

第 14 章：表示オブジェクトのフィルター処理
Flash Player 9 以降、Adobe AIR 1.0 以降
従来、ビットマップイメージへのフィルター効果の適用は、Adobe Photoshop® や Adobe Fireworks® などのイメージ編集に特化したソフトウェアによって処理される領域でした。ActionScript 3.0 の flash.filters パッケージには、一連のビット
マップ効果フィルタークラスが含まれています。開発者はこれらの効果を利用して、プログラムでビットマップや表示オブジェクトにフィルターを適用することにより、グラフィック操作アプリケーションで適用できるような効果の多くを実現することができます。

表示オブジェクトのフィルター処理の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションを洗練する方法の 1 つは、簡単なグラフィック効果を追加することです。例えば、写真の背後にドロップシャドウを追加すると 3D 効果を生成できます。また、グローをボタンの周囲に追加するとボタンがアクティブであることを示すことができます。ActionScript 3.0 には 10 種類のフィルターがあり、表示オブジェクトまたは BitmapData インス
タンスに適用できます。組み込みのフィルターは、ドロップシャドウフィルターやグローフィルターなどの基本的なフィル
ターから、置き換えマップフィルターや畳み込みフィルターなどの複雑なフィルターまで用意されています。
注意：組み込みのフィルターを使用するだけでなく、Pixel Bender を使用して、カスタムフィルターやカスタム効果も作成できます。285 ページの「Pixel Bender シェーダーの操作」を参照してください。
重要な概念と用語
次の参照リストに、フィルターを作成する際に必要となる重要な用語を示します。
ベベル 2 方向でピクセルを明るくし、その反対側の 2 方向でピクセルを暗くして作成されるエッジです。境界が立体的に見える効果です。この効果は、浮き出たボタンや凹んだボタンなどのグラフィックでよく使用されます。
畳み込み 個々のピクセルの値と、隣接する一部またはすべてのピクセルの値とを様々な割合で合計することによって、イメージ内のピクセルに歪みを適用することです。
置き換え イメージ内のピクセルを新しい位置にシフトまたは移動することです。
マトリックス ある特定の数学的計算を実行するために使用される数値から成るグリッドです。この計算では、グリッドの数
値が様々な値に適用され、その結果が合計されます。

関連項目

flash.filters パッケージ
flash.display.DisplayObject.filters
flash.display.BitmapData.applyFilter()

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

255

表示オブジェクトのフィルター処理

フィルターの作成と適用Flash Player 9 以降、Adobe AIR 1.0 以降
フィルターを使用すると、ドロップシャドウからベベルやぼかしまでの一連の効果を、ビットマップオブジェクトや表示オ
ブジェクトに適用することができます。各フィルターはクラスとして定義されています。したがって、フィルターを適用するにはフィルターオブジェクトのインスタンスを作成する必要がありますが、他のオブジェクトを作成する場合との違いはありません。フィルターオブジェクトのインスタンスを作成した後は、表示オブジェクトの filters プロパティを使用して、そのインスタンスを表示オブジェクトに簡単に適用できます。BitmapData オブジェクトの場合は、applyFilter() メソッドを使用して簡単に適用することができます。

フィルターの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
フィルターオブジェクトは、適切なフィルタークラスのコンストラクターメソッドを呼び出すだけで作成できます。例えば、

DropShadowFilter オブジェクトを作成するには次のコードを使用します。
import flash.filters.DropShadowFilter;var myFilter:DropShadowFilter = new DropShadowFilter();

ここでは示していませんが、どのフィルタークラスのコンストラクターもそうであるように、DropShadowFilter() コンスト
ラクターも、フィルター効果の外観のカスタマイズに使用可能ないくつかの任意指定のパラメーターを受け入れます。

フィルターの適用
Flash Player 9 以降、Adobe AIR 1.0 以降
フィルターオブジェクトを作成した後には、そのオブジェクトを表示オブジェクトまたは BitmapData オブジェクトに適用することができます。フィルターの適用方法は、フィルターを適用するオブジェクトによって異なります。
表示オブジェクトへのフィルターの適用
フィルター効果を表示オブジェクトに適用する場合、filters プロパティを使用して適用します。表示オブジェクトの filters プ
ロパティは Array インスタンスであり、このインスタンスのエレメントは、その表示オブジェクトに適用されるフィルター
オブジェクトです。表示オブジェクトにフィルターを 1 つだけ適用する場合は、次のように、フィルターインスタンスを作成して Array インスタンスに追加した後、その Array オブジェクトを表示オブジェクトの filters プロパティに割り当てます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

256

表示オブジェクトのフィルター処理

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.filters.DropShadowFilter;// Create a bitmapData object and render it to screen
var myBitmapData:BitmapData = new BitmapData(100,100,false,0xFFFF3300);
var myDisplayObject:Bitmap = new Bitmap(myBitmapData);
addChild(myDisplayObject);// Create a DropShadowFilter instance.
var dropShadow:DropShadowFilter = new DropShadowFilter();// Create the filters array, adding the filter to the array by passing it as// a parameter to the Array() constructor.
var filtersArray:Array = new Array(dropShadow);// Assign the filters array to the display object to apply the filter.
myDisplayObject.filters = filtersArray;

オブジェクトに複数のフィルターを割り当てる場合は、単純にすべてのフィルターを Array インスタンスに追加します。その後で、filters プロパティにそのインスタンスを割り当てます。複数のオブジェクトを配列に追加するには、配列のコンス
トラクターにそれらをパラメーターとして渡します。例えば、次のコードでは、既に作成されている表示オブジェクトにベベルフィルターとグローフィルターを適用します。
import flash.filters.BevelFilter;
import flash.filters.GlowFilter;// Create the filters and add them to an array.
var bevel:BevelFilter = new BevelFilter();var glow:GlowFilter = new GlowFilter();var filtersArray:Array = new Array(bevel, glow);// Assign the filters array to the display object to apply the filter.
myDisplayObject.filters = filtersArray;

フィルターを含む配列を作成するときには、前の例に示したように、new Array() コンストラクターを使用して作成することができます。また、フィルターを角括弧（[]）で囲んで、配列リテラルシンタックスを使用することもできます。例えば、
次のようなコード行があるとします。
var filters:Array = new Array(dropShadow, blur);

この行の実行結果は次のコード行と同じになります。
var filters:Array = [dropShadow, blur];

複数のフィルターを表示オブジェクトに適用すると、それらのフィルターは順番に従って累積的に適用されます。例えば、
あるフィルター配列に 2 つのエレメントがあるとします。エレメントとしては、ベベルフィルターが最初に追加され、ドロップシャドウフィルターが 2 番目に追加されています。この場合、ドロップシャドウフィルターはベベルフィルターと表示オブジェクトの両方に適用されます。これは、フィルター配列内でドロップシャドウフィルターの位置が 2 番目であるためです。フィルターを非累積的に適用する場合は、各フィルターを別個に表示オブジェクトの新しいコピーに適用します。
単一またはごく少数のフィルターを表示オブジェクトに適用する場合には、フィルターインスタンスの作成とオブジェクトへの適用を 1 つのステートメントで行うことができます。例えば、次のコード行は、myDisplayObject という名前の表示オブジェクトにぼかしフィルターを適用するものです。
myDisplayObject.filters = [new BlurFilter()];

上記のコードでは、配列リテラルシンタックス（角括弧）を使用して Array インスタンスを作成し、その Array のエレメン
トとして BlurFilter インスタンスを作成しています。さらに、myDisplayObject という名前の表示オブジェクトの filters プロ
パティに、その Array を割り当てています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

257

表示オブジェクトのフィルター処理

表示オブジェクトからのフィルターの削除
表示オブジェクトからすべてのフィルターを削除する操作は、次のように、filters プロパティに null 値を割り当てるだけの
簡単な操作です。
myDisplayObject.filters = null;

オブジェクトに複数のフィルターを適用しており、それらのフィルターのうち 1 つだけを削除する必要がある場合には、複数の手順を実行して filters プロパティ内の配列を変更する必要があります。詳しくは、257 ページの「フィルター操作の潜在的な問題」を参照してください。

BitmapData オブジェクトへのフィルターの適用
BitmapData オブジェクトにフィルターを適用するには、次のように BitmapData オブジェクトの applyFilter() メソッドを使用する必要があります。
var rect:Rectangle = new Rectangle();var origin:Point = new Point();
myBitmapData.applyFilter(sourceBitmapData, rect, origin, new BlurFilter());

applyFilter() メソッドは、ソース BitmapData オブジェクトにフィルターを適用して、フィルター適用済みのイメージを新しく作成します。このメソッドによって元のソースイメージが変更されることはありません。その代わりに、ソースイメー
ジにフィルターを適用した結果が、この applyFilter() メソッドが呼び出された BitmapData インスタンスに格納されます。

フィルターのしくみFlash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトのフィルター処理は、元のオブジェクトのコピーを透明なビットマップとしてキャッシュするしくみになっています。
フィルターが表示オブジェクトに適用されると、そのオブジェクトに有効なフィルターリストがある限り、そのオブジェク
トがビットマップとしてキャッシュされます。このソースビットマップは、それ以降に適用されるすべてのフィルター効果の元イメージとして使用されます。
通常、表示オブジェクトにはそれぞれ 2 つのビットマップがあります。1 つはフィルター適用前の元の表示オブジェクトの
ビットマップで、もう 1 つはフィルター適用後の最終イメージのビットマップです。最終イメージはレンダリング時に使用されます。表示オブジェクトが変更されない限り、最終イメージを更新する必要はありません。

フィルター操作の潜在的な問題
Flash Player 9 以降、Adobe AIR 1.0 以降
フィルターを操作する際には、混乱やトラブルの原因になる可能性があるため注意を必要とする事項がいくつかあります。
フィルターとビットマップキャッシュ表示オブジェクトにフィルターを適用するには、そのオブジェクトのビットマップキャッシュを有効にする必要があります。

cacheAsBitmap プロパティが false に設定されている表示オブジェクトにフィルターを適用すると、オブジェクトのcacheAsBitmap プロパティが自動的に true に設定されます。表示オブジェクトのすべてのフィルターを削除すると、
cacheAsBitmap プロパティは現在の設定値の直前の設定値にリセットされます。
実行時のフィルターの変更
表示オブジェクトに 1 つ以上のフィルターが既に適用されている場合、filters プロパティ配列にフィルターを追加したり、配列からフィルターを削除したりして、フィルターのセットを変更することはできません。その代わり、適用されているフィルターのセットを追加または変更するには、独立した配列に対して変更を行い、その配列を表示オブジェクトの filters

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

258

表示オブジェクトのフィルター処理

プロパティに割り当てて、フィルターをオブジェクトに適用する必要があります。その最も簡単な方法は、filters プロパ
ティ配列を Array 変数に読み込み、この一時配列に対して修正を行うことです。次に、この配列を表示オブジェクトの filters
プロパティに再度割り当てます。さらに複雑な場合には、独立したマスタフィルター配列の保持が必要になる場合があります。マスタフィルター配列に対して変更を行い、変更ごとにマスタ配列を表示オブジェクトの filters プロパティに再度割り当てます。
フィルターの追加
次のコードは、1 つ以上のフィルターが既に適用されている表示オブジェクトにフィルターを追加するプロセスを示しています。まず、グローフィルターが myDisplayObject という名前の表示オブジェクトに適用されます。その後、この表示オブジェクトがクリックされたときに、関数 addFilters() が呼び出されます。この関数では、2 つの追加フィルターがmyDisplayObject に適用されます。
import flash.events.MouseEvent;import flash.filters.*;
myDisplayObject.filters = [new GlowFilter()];function addFilters(event:MouseEvent):void{// Make a copy of the filters array.
var filtersCopy:Array = myDisplayObject.filters;// Make desired changes to the filters (in this case, adding filters).
filtersCopy.push(new BlurFilter());
filtersCopy.push(new DropShadowFilter());// Apply the changes by reassigning the array to the filters property.
myDisplayObject.filters = filtersCopy;}
myDisplayObject.addEventListener(MouseEvent.CLICK, addFilters);

フィルターセットからのフィルターの削除
表示オブジェクトに複数のフィルターが適用されており、そのうち 1 つのフィルターを削除する一方、他のフィルターはオ
ブジェクトに適用し続ける必要がある場合には、フィルターを一時配列にコピーし、不要なフィルターをその配列から削除
して、表示オブジェクトの filters プロパティに一時配列を再度割り当てます。配列から 1 つ以上の要素を削除する方法については、30 ページの「値の取得と配列要素の削除」で説明します。
最も簡単なのは、オブジェクトの一番上のフィルター（オブジェクトに最後に適用されたフィルター）を削除する場合です。

Array クラスの pop() メソッドを使用して、配列からフィルターを削除します。
// Example of removing the top-most filter from a display object// named "filteredObject".
var tempFilters:Array = filteredObject.filters;// Remove the last element from the Array (the top-most filter).
tempFilters.pop();// Apply the new set of filters to the display object.
filteredObject.filters = tempFilters;

同様に、一番下のフィルター（オブジェクトに最初に適用されたフィルター）を削除するには、Array クラスの pop() メ
ソッドを shift() メソッドに置き換える以外は同じコードを使用します。
フィルターの配列の中間（配列に 3 つ以上のフィルターがあると仮定）からフィルターを削除するには、splice() メソッドを使用します。削除するフィルターのインデックス（配列内の位置）を確認しておく必要があります。例えば、次のコードでは、表示オブジェクトから 2 番目のフィルター（インデックス 1 のフィルター）を削除します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

259

表示オブジェクトのフィルター処理// Example of removing a filter from the middle of a stack of filters// applied to a display object named "filteredObject".
var tempFilters:Array = filteredObject.filters;// Remove the second filter from the array. It's the item at index 1// because Array indexes start from 0.
// The first "1" indicates the index of the filter to remove; the// second "1" indicates how many elements to remove.
tempFilters.splice(1, 1);// Apply the new set of filters to the display object.
filteredObject.filters = tempFilters;

フィルターのインデックスの確認
フィルターのインデックスを確認するには、どのフィルターを配列から削除するのかを知っておく必要があります。削除するフィルターのインデックスを確認する（アプリケーションの設計方法による）か、または計算する必要があります。
最良の方法は、削除するフィルターが常にフィルターのセット内の同じ位置にくるように、アプリケーションを設計することです。例えば、畳み込みフィルターとドロップシャドウフィルターを（この順序で）1 つの表示オブジェクトに適用し、ドロップシャドウフィルターを削除する一方、畳み込みフィルターを保持する場合、どの Array メソッドが使用されるのか（この場合、ドロップシャドウフィルターを削除する Array.pop()）を事前に確認できるように、フィルターは既知の位置（一番上のフィルター）にあります。
削除するフィルターが常に一定の種類だが、フィルターのセット内で常に同じ位置にあるとは限らない場合、配列内の各フィルターのデータ型を確認してどのフィルターを削除するのかを調べることができます。例えば、次のコードでは、フィルターのどのセットがグローフィルターであるかを調べ、そのフィルターをセットから削除しています。
// Example of removing a glow filter from a set of filters, where the//filter you want to remove is the only GlowFilter instance applied// to the filtered object.
var tempFilters:Array = filteredObject.filters;// Loop through the filters to find the index of the GlowFilter instance.
var glowIndex:int;
var numFilters:int = tempFilters.length;
for (var i:int = 0; i < numFilters; i++){if (tempFilters[i] is GlowFilter){
glowIndex = i;break;}}// Remove the glow filter from the array.
tempFilters.splice(glowIndex, 1);// Apply the new set of filters to the display object.
filteredObject.filters = tempFilters;

さらに複雑な場合で、例えば削除するフィルターが実行時に選択される場合、最良の方法は、フィルターのマスタリストとして機能するフィルター配列の独立した永続コピーを保持することです。フィルターのセットを変更するときは必ず、マスタリストを変更し、そのフィルター配列を表示オブジェクトの filters プロパティとして適用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

260

表示オブジェクトのフィルター処理

例えば、次のコードでは、複数の畳み込みフィルターが表示オブジェクトに適用されて、様々な視覚効果が作成されます。
さらに、アプリケーションの後半では、これらのフィルターのうちの 1 つが削除され、他のフィルターは保持されます。この場合、コードでは、フィルター配列のマスタコピーおよび削除するフィルターへの参照が保持されます。特定のフィル
ターの検索および削除の方法は、フィルター配列の一時コピーを作成する代わりに、マスタコピーが操作された後に表示オ
ブジェクトに適用されることを除いて、前述の方法に似ています。
// Example of removing a filter from a set of// filters, where there may be more than one// of that type of filter applied to the filtered// object, and you only want to remove one.
// A master list of filters is stored in a separate,// persistent Array variable.
var masterFilterList:Array;// At some point, you store a reference to the filter you// want to remove.
var filterToRemove:ConvolutionFilter;// ... assume the filters have been added to masterFilterList,// which is then assigned as the filteredObject.filters:
filteredObject.filters = masterFilterList;// ... later, when it's time to remove the filter, this code gets called:// Loop through the filters to find the index of masterFilterList.
var removeIndex:int = -1;
var numFilters:int = masterFilterList.length;
for (var i:int = 0; i < numFilters; i++){if (masterFilterList[i] == filterToRemove){
removeIndex = i;break;}}
if (removeIndex >= 0){// Remove the filter from the array.
masterFilterList.splice(removeIndex, 1);// Apply the new set of filters to the display object.
filteredObject.filters = masterFilterList;}

この方法では（格納されたフィルター参照をフィルター配列の項目と比較して削除対象のフィルターを調べる場合）、フィル
ター配列の独立したコピーを保持する必要があります。なぜなら、格納されたフィルター参照を、表示オブジェクトのfilters プロパティからコピーした一時配列内の要素と比較する場合、コードが機能しないからです。これは、配列を filters プ
ロパティに割り当てる際に、内部でランタイムによって配列内の各フィルターオブジェクトのコピーが作成されるからです。
これらのコピー（元のオブジェクトではなく）が表示オブジェクトに適用され、filters プロパティが一時配列に読み込まれると、その一時配列には、元のフィルターオブジェクトへの参照ではなく、コピーされたフィルターオブジェクトへの参照が含まれます。その結果、前述の例では、プロパティを一時フィルター配列のフィルターと比較することによって、filterToRemove のインデックスを調べることができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

261

表示オブジェクトのフィルター処理

フィルターとオブジェクト変形
ドロップシャドウなどのフィルター処理された領域のうち、表示オブジェクトの境界ボックスの矩形よりも外側にある部分
は、ヒット検出の対象サーフェスの一部と見なされません。ヒット検出は、インスタンス同士の重なりや交差があるかどうかを判定する処理です。DisplayObject クラスのヒット検出メソッドはベクターベースであるため、ビットマップとして生成された結果に対してヒット検出を実行することはできません。例えば、ベベルフィルターをボタンインスタンスに適用した場合、そのインスタンスのベベル部分ではヒット検出を使用できません。
フィルターでは拡大／縮小、回転、および傾斜がサポートされません。フィルター処理した表示オブジェクト自体を拡大／
縮小しても、すなわち scaleX と scaleY を 100 ％以外にしても、フィルター効果はインスタンスと共に拡大／縮小されません。つまり、インスタンスの元のシェイプを回転、拡大／縮小、または傾斜しても、そのインスタンスと共にフィルターも回転、拡大／縮小、または傾斜するわけではありません。
フィルターを適用してインスタンスをアニメーション化すると、リアルな効果を生成できます。インスタンスをネスト化し、BitmapData クラスを使用してフィルターをアニメーション化しても、同じ効果を実現できます。
フィルターとビットマップオブジェクト

BitmapData オブジェクトにフィルターを適用すると、cacheAsBitmap プロパティが自動的に true に設定されます。このようにして、実際には元のオブジェクトではなくオブジェクトのコピーにフィルターが適用されます。
このコピーは、その後、メイン表示で元のオブジェクトに重ねて配置され、最も近いピクセルに可能な限り近付けられます。
元のビットマップの境界が変化すると、フィルターが適用されたコピーのビットマップは、伸縮または歪曲されるのではな
く、元のビットマップから再作成されます。
ビットマップオブジェクトのフィルターをすべてクリアすると、cacheAsBitmap プロパティは、フィルター適用前の値にリセットされます。

使用可能な表示フィルターFlash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 には次に示す 10 個のフィルタークラスがあり、表示オブジェクトと BitmapData オブジェクトに適用できます。

•

ベベルフィルター（BevelFilter クラス）•

ぼかしフィルター（BlurFilter クラス）•

ドロップシャドウフィルター（DropShadowFilter クラス）•

グローフィルター（GlowFilter クラス )•グラデーションベベルフィルター（GradientBevelFilter クラス）•

グラデーショングローフィルター（GradientGlowFilter クラス）•

カラーマトリックスフィルター（ColorMatrixFilter クラス）•

畳み込みフィルター（ConvolutionFilter クラス）•

置き換えマップフィルター（DisplacementMapFilter クラス）•

シェーダーフィルター（ShaderFilter クラス）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

262

表示オブジェクトのフィルター処理

先頭から 6 番目までのフィルターは単純なフィルターです。それぞれ、1 つの特定の効果の生成に使用することができ、効果を若干カスタマイズすることができます。これらの 6 個のフィルターは、ActionScript を使用して適用できます。また、Flash Professional では、「フィルター」パネルを使用してオブジェクトに適用できます。したがって、フィルターをActionScript で適用しようとしている場合でも、Flash Professional があれば、ビジュアルなインターフェイスを使用して手軽に様々なフィルターや設定を試し、必要な効果の生成方法を把握することができます。
最後の 4 個のフィルターは、ActionScript でのみ使用できます。これらのカラーマトリックスフィルター、畳み込みフィル
ター、置き換えマップフィルター、シェーダーフィルターは、作成に使用できる効果の種類が非常に柔軟です。これらのフィルターは、単一の効果に最適化されているのではなく、様々な能力と柔軟性を提供しています。例えば、畳み込みフィ
ルターの場合、このフィルターのマトリックスに指定する値を変更することによって、ぼかし、エンボス、シャープ、カラーエッジ検出、変換などの各種効果の生成に使用することができます。
各フィルターは、単純なフィルターであるか複雑なフィルターであるかに関係なく、プロパティを使用してカスタマイズすることができます。通常、フィルターのプロパティの設定方法は 2 つあります。どのフィルターでも、フィルターオブジェク
トのコンストラクターにパラメーター値を渡すことによって、プロパティを設定できます。また、パラメーターを渡す方法
でフィルターのプロパティを設定したかどうかに関係なく、フィルターオブジェクトのプロパティの値を設定することによって、後からフィルターを調整できます。例として示すコードリストの大半では、例をわかりやすくするために、プロパ
ティを直接設定しています。ただし、通常は、フィルターオブジェクトのコンストラクターに値をパラメーターとして渡す方法を使用して、行数がより少ないコードで同じ結果を得ることができます。フィルター、そのプロパティおよびコンスト
ラクターパラメーターについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』で、flash.filters パッケージのリストを参照してください。

ベベルフィルター
Flash Player 9 以降、Adobe AIR 1.0 以降
BevelFilter クラス を使用すると、フィルターされたオブジェクトに 3D べベルエッジを追加することができます。このフィルターを適用すると、オブジェクトの角部分やエッジが、浮き彫りのように、または斜角面があるように見えます。

BevelFilter クラスのプロパティを使用して、ベベルの外観をカスタマイズすることができます。ハイライトカラーとシャド
ウカラー、ベベルエッジのぼかし、ベベルの角度、およびベベルエッジの配置を設定できます。さらに、ノックアウト効果を付加することもできます。
次の例では、外部イメージをロードし、そのイメージにベベルフィルターを適用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

263

表示オブジェクトのフィルター処理

import flash.display.*;
import flash.filters.BevelFilter;
import flash.filters.BitmapFilterQuality;
import flash.filters.BitmapFilterType;import flash.net.URLRequest;// Load an image onto the Stage.
var imageLoader:Loader = new Loader();var url:String = "http://www.helpexamples.com/flash/images/image3.jpg";
var urlReq:URLRequest = new URLRequest(url);
imageLoader.load(urlReq);
addChild(imageLoader);// Create the bevel filter and set filter properties.
var bevel:BevelFilter = new BevelFilter();bevel.distance = 5;bevel.angle = 45;
bevel.highlightColor = 0xFFFF00;
bevel.highlightAlpha = 0.8;
bevel.shadowColor = 0x666666;
bevel.shadowAlpha = 0.8;
bevel.blurX = 5;bevel.blurY = 5;bevel.strength = 5;bevel.quality = BitmapFilterQuality.HIGH;
bevel.type = BitmapFilterType.INNER;
bevel.knockout = false;// Apply filter to the image.
imageLoader.filters = [bevel];

ぼかしフィルター
Flash Player 9 以降、Adobe AIR 1.0 以降
BlurFilter クラスは、表示オブジェクトおよびそのコンテンツをにじませたり、ぼかしたりします。ぼかし効果は、オブジェクトにフォーカスがないことを印象付ける場合や、高速移動が行われているように見せる場合に便利です。ぼかしフィ
ルターの quality プロパティを低レベルに設定すると、ソフトフォーカスレンズの効果をシミュレートすることができます。

quality プロパティを高レベルに設定すると、ガウスぼかしに似たスムーズなぼかしが生成されます。
次の例では、Graphics クラスの drawCircle() メソッドを使用して円オブジェクトを作成し、そのオブジェクトにぼかしを適用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

264

表示オブジェクトのフィルター処理

import flash.display.Sprite;
import flash.filters.BitmapFilterQuality;
import flash.filters.BlurFilter;// Draw a circle.
var redDotCutout:Sprite = new Sprite();redDotCutout.graphics.lineStyle();redDotCutout.graphics.beginFill(0xFF0000);
redDotCutout.graphics.drawCircle(145, 90, 25);
redDotCutout.graphics.endFill();// Add the circle to the display list.
addChild(redDotCutout);// Apply the blur filter to the rectangle.
var blur:BlurFilter = new BlurFilter();blur.blurX = 10;
blur.blurY = 10;
blur.quality = BitmapFilterQuality.MEDIUM;
redDotCutout.filters = [blur];

ドロップシャドウフィルターFlash Player 9 以降、Adobe AIR 1.0 以降
ドロップシャドウを使用すると、ターゲットオブジェクトの上部に別個の光源があるような印象を与えることができます。
この光源の位置や強さを変更して、様々なドロップシャドウ効果を生成することが可能です。

DropShadowFilter クラスでは、ぼかしフィルターアルゴリズムと同様のアルゴリズムを使用します。主な違いは、ドロッ
プシャドウフィルターには若干多くのプロパティが用意されており、それらを変更すると光源の各種属性（アルファ、カラー、オフセット、明度など）をシミュレートできることです。
また、ドロップシャドウフィルターでは、内側シャドウ、外側シャドウ、ノックアウト（カットアウト）モードなどのドロップシャドウのスタイルに関するカスタム変換オプションも適用することができます。
次のコードでは、四角形のボックスのスプライトを作成し、そのボックスにドロップシャドウフィルターを適用します。
import flash.display.Sprite;
import flash.filters.DropShadowFilter;// Draw a box.
var boxShadow:Sprite = new Sprite();boxShadow.graphics.lineStyle(1);boxShadow.graphics.beginFill(0xFF3300);
boxShadow.graphics.drawRect(0, 0, 100, 100);
boxShadow.graphics.endFill();
addChild(boxShadow);// Apply the drop shadow filter to the box.
var shadow:DropShadowFilter = new DropShadowFilter();shadow.distance = 10;
shadow.angle = 25;// You can also set other properties, such as the shadow color,// alpha, amount of blur, strength, quality, and options for// inner shadows and knockout effects.
boxShadow.filters = [shadow];

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

265

表示オブジェクトのフィルター処理

グローフィルター
Flash Player 9 以降、Adobe AIR 1.0 以降
GlowFilter クラスでは、表示オブジェクトに照明効果を適用し、オブジェクトの下から光を輝かせ、弱いグローを作成します。
ドロップシャドウフィルターと同様に、グローフィルターも光源の距離、角度、およびカラーを変更できるプロパティを備えており、様々な効果を生成できます。また、グローフィルターには、内側グロー、外側グロー、ノックアウトモードなどのグローのスタイルを変更するためのオプションもいくつか用意されています。
次のコードでは、Sprite クラスを使用して十字形を作成し、その十字形にグローフィルターを適用します。
import flash.display.Sprite;
import flash.filters.BitmapFilterQuality;
import flash.filters.GlowFilter;// Create a cross graphic.
var crossGraphic:Sprite = new Sprite();crossGraphic.graphics.lineStyle();crossGraphic.graphics.beginFill(0xCCCC00);
crossGraphic.graphics.drawRect(60, 90, 100, 20);crossGraphic.graphics.drawRect(100, 50, 20, 100);crossGraphic.graphics.endFill();
addChild(crossGraphic);// Apply the glow filter to the cross shape.
var glow:GlowFilter = new GlowFilter();glow.color = 0x009922;
glow.alpha = 1;
glow.blurX = 25;
glow.blurY = 25;
glow.quality = BitmapFilterQuality.MEDIUM;
crossGraphic.filters = [glow];

グラデーションベベルフィルターFlash Player 9 以降、Adobe AIR 1.0 以降
GradientBevelFilter クラスを使用すると、表示オブジェクトまたは BitmapData オブジェクトに対して強化されたべベル
効果を適用することができます。グラデーションカラーがベベルに使用されるので、ベベルの空間的な深みが大幅に向上し、エッジがいっそうリアルな 3D に見えるようになります。
次のコードでは、Shape クラスの drawRect() メソッドを使用して矩形オブジェクトを作成し、そのオブジェクトにグラデー
ションベベルフィルターを適用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

266

表示オブジェクトのフィルター処理

import flash.display.Shape;
import flash.filters.BitmapFilterQuality;
import flash.filters.GradientBevelFilter;// Draw a rectangle.
var box:Shape = new Shape();box.graphics.lineStyle();box.graphics.beginFill(0xFEFE78);
box.graphics.drawRect(100, 50, 90, 200);
box.graphics.endFill();// Apply a gradient bevel to the rectangle.
var gradientBevel:GradientBevelFilter = new GradientBevelFilter();
gradientBevel.distance = 8;
gradientBevel.angle = 225; // opposite of 45 degrees
gradientBevel.colors = [0xFFFFCC, 0xFEFE78, 0x8F8E01];
gradientBevel.alphas = [1, 0, 1];
gradientBevel.ratios = [0, 128, 255];
gradientBevel.blurX = 8;
gradientBevel.blurY = 8;
gradientBevel.quality = BitmapFilterQuality.HIGH;// Other properties let you set the filter strength and set options// for inner bevel and knockout effects.
box.filters = [gradientBevel];// Add the graphic to the display list.
addChild(box);

グラデーショングローフィルターFlash Player 9 以降、Adobe AIR 1.0 以降
GradientGlowFilter クラスでは、表示オブジェクトまたは BitmapData オブジェクトに強化されたグロー効果を適用することができます。この効果を使用することによって、グローのカラー制御が充実し、グロー効果がいっそうリアルになります。また、グラデーショングローフィルターでは、オブジェクトの内側、外側、または上側のエッジにグラデーショング
ローを適用することができます。
次の例では、ステージ上に円を描画し、その円にグラデーショングローフィルターを適用します。マウスを右方向と下方向に移動すると、それぞれ水平方向と垂直方向で、ぼかしの量が増加します。また、ステージをクリックすると、ぼかしの強さが増加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

267

表示オブジェクトのフィルター処理

import flash.events.MouseEvent;import flash.filters.BitmapFilterQuality;
import flash.filters.BitmapFilterType;import flash.filters.GradientGlowFilter;// Create a new Shape instance.
var shape:Shape = new Shape();// Draw the shape.
shape.graphics.beginFill(0xFF0000, 100);
shape.graphics.moveTo(0, 0);
shape.graphics.lineTo(100, 0);
shape.graphics.lineTo(100, 100);
shape.graphics.lineTo(0, 100);
shape.graphics.lineTo(0, 0);
shape.graphics.endFill();// Position the shape on the Stage.
addChild(shape);
shape.x = 100;
shape.y = 100;// Define a gradient glow.
var gradientGlow:GradientGlowFilter = new GradientGlowFilter();
gradientGlow.distance = 0;
gradientGlow.angle = 45;
gradientGlow.colors = [0x000000, 0xFF0000];
gradientGlow.alphas = [0, 1];
gradientGlow.ratios = [0, 255];
gradientGlow.blurX = 10;
gradientGlow.blurY = 10;
gradientGlow.strength = 2;
gradientGlow.quality = BitmapFilterQuality.HIGH;
gradientGlow.type = BitmapFilterType.OUTER;// Define functions to listen for two events.
function onClick(event:MouseEvent):void{
gradientGlow.strength++;shape.filters = [gradientGlow];}function onMouseMove(event:MouseEvent):void{
gradientGlow.blurX = (stage.mouseX / stage.stageWidth) * 255;
gradientGlow.blurY = (stage.mouseY / stage.stageHeight) * 255;
shape.filters = [gradientGlow];}
stage.addEventListener(MouseEvent.CLICK, onClick);
stage.addEventListener(MouseEvent.MOUSE_MOVE, onMouseMove);

例 : 基本的なフィルターの組み合わせ
Flash Player 9 以降、Adobe AIR 1.0 以降
次のコード例では、いくつかの基本的なフィルターをタイマーと組み合わせて使用して、繰り返されるアクションを作成し、アニメーションによる信号機のシミュレーションを作成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

268

表示オブジェクトのフィルター処理

import flash.display.Shape;
import flash.events.TimerEvent;import flash.filters.BitmapFilterQuality;
import flash.filters.BitmapFilterType;import flash.filters.DropShadowFilter;
import flash.filters.GlowFilter;
import flash.filters.GradientBevelFilter;
import flash.utils.Timer;
var count:Number = 1;
var distance:Number = 8;
var angleInDegrees:Number = 225; // opposite of 45 degrees
var colors:Array = [0xFFFFCC, 0xFEFE78, 0x8F8E01];
var alphas:Array = [1, 0, 1];
var ratios:Array = [0, 128, 255];
var blurX:Number = 8;
var blurY:Number = 8;
var strength:Number = 1;
var quality:Number = BitmapFilterQuality.HIGH;
var type:String = BitmapFilterType.INNER;
var knockout:Boolean = false;// Draw the rectangle background for the traffic light.
var box:Shape = new Shape();box.graphics.lineStyle();box.graphics.beginFill(0xFEFE78);
box.graphics.drawRect(100, 50, 90, 200);
box.graphics.endFill();// Draw the 3 circles for the three lights.
var stopLight:Shape = new Shape();stopLight.graphics.lineStyle();stopLight.graphics.beginFill(0xFF0000);
stopLight.graphics.drawCircle(145,90,25);
stopLight.graphics.endFill();var cautionLight:Shape = new Shape();cautionLight.graphics.lineStyle();cautionLight.graphics.beginFill(0xFF9900);
cautionLight.graphics.drawCircle(145,150,25);
cautionLight.graphics.endFill();var goLight:Shape = new Shape();goLight.graphics.lineStyle();goLight.graphics.beginFill(0x00CC00);
goLight.graphics.drawCircle(145,210,25);
goLight.graphics.endFill();// Add the graphics to the display list.
addChild(box);
addChild(stopLight);
addChild(cautionLight);
addChild(goLight);// Apply a gradient bevel to the traffic light rectangle.
var gradientBevel:GradientBevelFilter = new GradientBevelFilter(distance, angleInDegrees, colors, alphas,ratios, blurX, blurY, strength, quality, type, knockout);
box.filters = [gradientBevel];// Create the inner shadow (for lights when off) and glow// (for lights when on).
var innerShadow:DropShadowFilter = new DropShadowFilter(5, 45, 0, 0.5, 3, 3, 1, 1, true, false);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

269

表示オブジェクトのフィルター処理

var redGlow:GlowFilter = new GlowFilter(0xFF0000, 1, 30, 30, 1, 1, false, false);
var yellowGlow:GlowFilter = new GlowFilter(0xFF9900, 1, 30, 30, 1, 1, false, false);
var greenGlow:GlowFilter = new GlowFilter(0x00CC00, 1, 30, 30, 1, 1, false, false);// Set the starting state of the lights (green on, red/yellow off).
stopLight.filters = [innerShadow];
cautionLight.filters = [innerShadow];
goLight.filters = [greenGlow];// Swap the filters based on the count value.
function trafficControl(event:TimerEvent):void{if (count == 4){
count = 1;}
switch (count){case 1:stopLight.filters = [innerShadow];
cautionLight.filters = [yellowGlow];
goLight.filters = [innerShadow];
break;
case 2:stopLight.filters = [redGlow];
cautionLight.filters = [innerShadow];
goLight.filters = [innerShadow];
break;
case 3:stopLight.filters = [innerShadow];
cautionLight.filters = [innerShadow];
goLight.filters = [greenGlow];
break;}
count++;}// Create a timer to swap the filters at a 3 second interval.
var timer:Timer = new Timer(3000, 9);
timer.addEventListener(TimerEvent.TIMER, trafficControl);timer.start();

カラーマトリックスフィルターFlash Player 9 以降、Adobe AIR 1.0 以降
ColorMatrixFilter クラスは、フィルターオブジェクトのカラーおよびアルファ値を操作するために使用されます。その結果、1 つのカラーチャンネルの値とその値を他のチャンネルに潜在的に適用する値を使用して、彩度変更、色相回転（ある範囲のカラーから別の範囲のカラーへのパレットのシフト）、輝度アルファ変換などのカラー操作効果を生成することができます。
概念的には、フィルターでソースイメージのピクセルが 1 つずつ処理され、各ピクセルが赤、緑、青、アルファの各成分に分解されます。次に、これらのそれぞれの値とカラーマトリックス内の指定値が乗算され、その結果が合計されて、画面上に表示される各ピクセルの最終的なカラーの値が決定されます。フィルターの matrix プロパティは、最終的なカラーの計算に使用される 20 個の配列になっています。カラー値の算出に使用する特別なアルゴリズムについて詳しくは、『Adobe

Flash Platform 用 ActionScript 3.0 リファレンスガイド』で、ColorMatrixFilter クラスの matrix プロパティについて解説
している項目を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

270

表示オブジェクトのフィルター処理

畳み込みフィルター
Flash Player 9 以降、Adobe AIR 1.0 以降
ConvolutionFilter クラスを使用すると、BitmapData オブジェクトまたは表示オブジェクトにぼかし、エッジ検出、
シャープ、エンボス、べベルなどの幅広い画像変換を適用することができます。
概念的には、畳み込みフィルターでソースイメージのピクセルが 1 つずつ処理され、処理対象のピクセルとその周囲のピクセルの値を使用して、その対象ピクセルの最終的なカラーが決定されます。マトリックスは、数値の配列として指定されており、個々の隣接ピクセルの値が最終結果の値にどの程度影響するかを示します。
ここでは、最もよく使用される種類のマトリックスである 3 × 3 のマトリックスについて考えてみます。このマトリックスには、9 個の値が含まれています。
N
N
N

N
P
N

N
N
N

畳み込みフィルターを特定のピクセルに適用する場合、そのピクセル自体（この例では「P」）のカラー値を参照すると共に、周囲のピクセル（この例では「N」）の値も参照します。ただし、マトリックス内に値を設定することによって、結果として得られるイメージに対する影響の優先度をピクセルごとに指定することができます。
例えば、次のマトリックスが畳み込みフィルターによって適用されると、イメージは適用前とまったく同じ状態のままにな
ります。
0
0
0

0
1
0

0
0
0

イメージが変更されない理由は、最終的なピクセルカラーが決定されるときに、元のピクセルの値の相対的な強さが 1 になるのに対し、周囲のピクセルの値の相対的な強さが 0 になるためです。つまり、周囲のピクセルの色は最終イメージに影響しません。
これと同様の理由で、次のマトリックスの場合にはイメージが左方向に 1 ピクセル分シフトすることになります。
0
0
0

0
0
0

0
1
0

この場合、処理対象のピクセル自体は、最終イメージでこのピクセルの位置に表示されるピクセルの最終値に影響しません。
右隣にあったピクセルの値だけが、その表示されるピクセルの最終値の決定に使用されます。

ActionScript でマトリックスを作成するときには、値を含む Array インスタンスと、マトリックスの行数および列数を指定する 2 つのプロパティとを組み合わせたものとして作成します。次の例では、イメージをロードし、イメージのロードが完了したら前述のマトリックスを使用して畳み込みフィルターをそのイメージに適用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

271

表示オブジェクトのフィルター処理// Load an image onto the Stage.
var loader:Loader = new Loader();var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg");
loader.load(url);
this.addChild(loader);function applyFilter(event:MouseEvent):void{// Create the convolution matrix.
var matrix:Array = [0, 0, 0,
0, 0, 1,0, 0, 0];var convolution:ConvolutionFilter = new ConvolutionFilter();
convolution.matrixX = 3;
convolution.matrixY = 3;
convolution.matrix = matrix;
convolution.divisor = 1;
loader.filters = [convolution];}
loader.addEventListener(MouseEvent.CLICK, applyFilter);

マトリックスで 1 または 0 以外の値を使用するとどのような結果になるかはこのコードからはわかりません。例えば、上と同じマトリックスで右側の位置の 1 の代わりに数値 8 を使用した場合には、同じアクションが実行されます。つまり、左方
向にピクセルがシフトします。また、イメージのカラーが影響を受け、イメージが 8 倍明るくなります。これは、最終的なピ
クセルカラーの値は、マトリックスの各値と元の各ピクセルのカラーを乗算し、値を合計した後、フィルターの divisor プロ
パティに指定されている値で除算することによって算出されるためです。例に示したコードでは、divisor プロパティは 1 に設定されています。基本的に、カラーの明度を元のイメージとほぼ同じ明度のままにする場合は、除数をマトリックスの各値の合計と等しくする必要があります。このように、値の合計が 8 になるマトリックスを使用し、除数を 1 にした場合には、結果として得られるイメージは元のイメージよりも約 8 倍明るくなります。
ここで紹介したマトリックスの効果は目立つものではありませんが、別のマトリックス値を使用すれば様々な効果を生成することができます。次に、3 × 3 マトリックスを使用して各種効果を生成する場合の標準的なマトリックス値の組み合わせをいくつか示します。

•

基本的なぼかし（除数は 5）：
0 1 0
1 1 1
0 1 0

•

シャープ（除数は 1）：
0, -1, 0-1, 5, -1
0, -1, 0•

エッジ検出（除数は 1）：
0, -1, 0-1, 4, -1
0, -1, 0•

エンボス効果（除数は 1）：-2, -1, 0-1, 1, 1
0, 1, 2

これらの効果を使用すると、ほとんどの場合、除数は 1 になります。これは、負のマトリックス値と正のマトリックス値
を足すと 1 になるからです（エッジ検出の場合は 0 ですが、divisor プロパティ値は 0 になりません）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

272

表示オブジェクトのフィルター処理

置き換えマップフィルターFlash Player 9 以降、Adobe AIR 1.0 以降
DisplacementMapFilter クラスでは、BitmapData オブジェクト（置き換えマップイメージと呼ばれる）のピクセル値を使用して、新しいオブジェクトに置き換え効果を実行することができます。通常、置き換えマップイメージは、フィルターの適用先となる実際の表示オブジェクトや BitmapData インスタンスとは異なります。置き換え効果では、フィルターを適用したイメージのピクセルが置き換えられます。つまり、ピクセルが元の位置から若干シフトします。このフィルターを使用して、シフト効果、ワープ効果、または斑点効果を生成することができます。
個々のピクセルに適用される置き換えの位置と量は、置き換えマップイメージのカラー値に基づいて決定されます。このフィルターを操作するときには、マップイメージの指定に加えて、マップイメージに基づいて置き換えをどのように計算するかを制御する次の値を指定する必要があります。

•

マップポイント：フィルターの適用対象となるイメージ上の位置であり、この位置に置き換えフィルターの左上隅が適用されます。イメージの一部にのみフィルターを適用する場合に使用できます。

• X コンポーネント : マップイメージのカラーチャンネルのうち、ピクセルの x 方向位置に影響するものを示します。
• Y コンポーネント : マップイメージのカラーチャンネルのうち、ピクセルの y 方向位置に影響するものを示します。
• X スケール : x 軸方向の置き換えの拡大の程度を指定する乗数値です。
• X スケール : y 軸方向の置き換えの拡大の程度を指定する乗数値です。
•

フィルターモード：ピクセルのシフトによって生じた空白の領域に対する処理を決定します。オプションは

DisplacementMapFilterMode クラスの定数として定義されており、元のピクセルを表示する（フィルターモード
IGNORE）か、イメージの反対側でピクセルを折り返す（フィルターモード WRAP、デフォルト）か、最も近くにある
シフトしたピクセルを使用する（フィルターモード CLAMP）か、またはその領域をカラーで塗りつぶす（フィルター
モード COLOR）ことができます。
配置マップフィルターの仕組みを理解するために、基本的な例について検討してみましょう。次のコードでは、イメージをロードし、ロードが完了したらイメージをステージの中央に移動して、置き換えマップフィルターをそのイメージに適用します。その結果、イメージ全体のピクセルが左方向に水平にシフトします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

273

表示オブジェクトのフィルター処理

import flash.display.BitmapData;
import flash.display.Loader;import flash.events.MouseEvent;import flash.filters.DisplacementMapFilter;
import flash.geom.Point;
import flash.net.URLRequest;// Load an image onto the Stage.
var loader:Loader = new Loader();var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image3.jpg");
loader.load(url);
this.addChild(loader);var mapImage:BitmapData;var displacementMap:DisplacementMapFilter;// This function is called when the image finishes loading.
function setupStage(event:Event):void{// Center the loaded image on the Stage.
loader.x = (stage.stageWidth - loader.width) / 2;
loader.y = (stage.stageHeight - loader.height) / 2;// Create the displacement map image.
mapImage = new BitmapData(loader.width, loader.height, false, 0xFF0000);// Create the displacement filter.
displacementMap = new DisplacementMapFilter();
displacementMap.mapBitmap = mapImage;displacementMap.mapPoint = new Point(0, 0);
displacementMap.componentX = BitmapDataChannel.RED;
displacementMap.scaleX = 250;
loader.filters = [displacementMap];}
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, setupStage);

置き換えの定義に使用されているプロパティは次のとおりです。

•

マップビットマップ : 置き換えビットマップは、このコードで作成する新しい BitmapData インスタンスです。サイズ
は、ロードされるイメージのサイズと一致しています。したがって、置き換えはイメージ全体に適用されます。赤一色のピクセルで塗りつぶされています。

•

マップポイント：この値はポイント (0, 0) に設定されています。これも、置き換えがイメージ全体に適用されるようにするためです。

• X コンポーネント：この値は定数 BitmapDataChannel.RED に設定されています。つまり、ピクセルがどの程度 x 軸方向に置き換えられる（移動する）かについては、マップビットマップの赤の値に基づいて決定されます。

• X スケール：この値は 250 に設定されています。マップイメージの色が完全な赤で、置き換え量が最大（フル）になる
場合でも、それに対応する実際のイメージの置き換えはごくわずかな量（1/2 ピクセル程度）です。そのため、この値が1 に設定されていると、イメージは 0.5 ピクセルしか水平方向にシフトしません。250 に設定すると、イメージは約 125ピクセル分シフトします。
これらの設定の結果、フィルターが適用されたイメージは 250 ピクセル左方向にシフトするようになります。シフトの方向（左または右）と量は、マップイメージ内のピクセルのカラー値に基づいて決まります。概念的には、フィルターが適用されたイメージのピクセルが 1 つずつ処理されます。少なくとも、フィルターが適用された領域のピクセル（ここで示した例ではすべてのピクセル）が処理されます。ピクセルごとに次の処理が行われます。

1 マップイメージ内の対応するピクセルが特定されます。例えば、フィルターが適用されたイメージの左上隅のピクセルの置き換え量が計算されるときには、マップイメージの左上隅のピクセルが参照されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

274

表示オブジェクトのフィルター処理

2 マップ上のピクセルで、指定されたカラーチャンネルの値が判定されます。ここで示した例では、x コンポーネントに指定されたカラーチャンネルは赤チャンネルです。そのため、対象のピクセルの位置でマップイメージの赤チャンネルの値が調べられます。マップイメージが単色の赤なので、ピクセルの赤チャンネルは 0xFF または 255 です。この値は置き換
え値として使用されます。

3 置き換え値が「中間」値と比較されます。中間値は、0 〜 255 の中間にあたる 127 です。置き換え値が中間値よりも小さい場合、正の方向（x 置き換えでは右方向、y 置き換えでは下方向）にピクセルがシフトします。一方、ここで示した
例のように置き換え値が中間値よりも大きい場合には、負の方向（x 置き換えでは左方向、y 置き換えでは上方向）にピ
クセルがシフトします。さらに正確に説明すると、127 から置き換え値が減算され、その結果（正または負）が、適用される相対的な置き換え量になります。

4 最後に、実際の置き換え量が決定されます。そのために、相対的な置き換え量の値が最大置き換えの何パーセントに相当するかが判定されます。ここで示した例では、完全な赤の場合に 100% の置き換えになります。続いて、そのパーセント
値と x スケール値または y スケール値が乗算されて、適用される置き換えピクセル数が決定されます。ここで示した例では、100% に乗数 250 を掛けて、置き換え量が決定されます。これは左方向に約 125 ピクセルになります。

y コンポーネントと y スケールについては、値が指定されていないため、デフォルト設定が使用されます。デフォルト設定
では置き換えが発生しません。イメージが垂直方向にシフトしないのはこのためです。
ここで示した例では、デフォルトのフィルターモード設定である WRAP が使用されます。そのため、ピクセルが左方向にシフトしたとき、右側に生じる空白の領域は、イメージの左端から押し出されたピクセルで塗りつぶされます。この値を変更してみると、様々な効果を確認できます。例えば、置き換えの各プロパティを設定しているコードの部分（loader.filters =[displacementMap] と記述されている行の前）に次の行を追加すると、イメージは、ステージ上でにじんだように見えるようになります。
displacementMap.mode = DisplacementMapFilterMode.CLAMP;

さらに複雑な例を示します。次のリストでは、置き換えマップフィルターを使用して、イメージに拡大鏡の効果を付加します。
import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.display.BitmapDataChannel;
import flash.display.GradientType;import flash.display.Loader;import flash.display.Shape;
import flash.events.MouseEvent;import flash.filters.DisplacementMapFilter;
import flash.filters.DisplacementMapFilterMode;
import flash.geom.Matrix;
import flash.geom.Point;
import flash.net.URLRequest;// Create the gradient circles that will together form the// displacement map image
var radius:uint = 50;
var type:String = GradientType.LINEAR;var redColors:Array = [0xFF0000, 0x000000];
var blueColors:Array = [0x0000FF, 0x000000];
var alphas:Array = [1, 1];
var ratios:Array = [0, 255];
var xMatrix:Matrix = new Matrix();
xMatrix.createGradientBox(radius * 2, radius * 2);
var yMatrix:Matrix = new Matrix();
yMatrix.createGradientBox(radius * 2, radius * 2, Math.PI / 2);
var xCircle:Shape = new Shape();xCircle.graphics.lineStyle(0, 0, 0);xCircle.graphics.beginGradientFill(type, redColors, alphas, ratios, xMatrix);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

275

表示オブジェクトのフィルター処理

xCircle.graphics.drawCircle(radius, radius, radius);
var yCircle:Shape = new Shape();yCircle.graphics.lineStyle(0, 0, 0);
yCircle.graphics.beginGradientFill(type, blueColors, alphas, ratios, yMatrix);
yCircle.graphics.drawCircle(radius, radius, radius);// Position the circles at the bottom of the screen, for reference.
this.addChild(xCircle);xCircle.y = stage.stageHeight - xCircle.height;
this.addChild(yCircle);yCircle.y = stage.stageHeight - yCircle.height;
yCircle.x = 200;// Load an image onto the Stage.
var loader:Loader = new Loader();var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg");
loader.load(url);
this.addChild(loader);// Create the map image by combining the two gradient circles.
var map:BitmapData = new BitmapData(xCircle.width, xCircle.height, false, 0x7F7F7F);
map.draw(xCircle);var yMap:BitmapData = new BitmapData(yCircle.width, yCircle.height, false, 0x7F7F7F);
yMap.draw(yCircle);
map.copyChannel(yMap, yMap.rect, new Point(0, 0), BitmapDataChannel.BLUE, BitmapDataChannel.BLUE);
yMap.dispose();// Display the map image on the Stage, for reference.
var mapBitmap:Bitmap = new Bitmap(map);
this.addChild(mapBitmap);
mapBitmap.x = 400;
mapBitmap.y = stage.stageHeight - mapBitmap.height;// This function creates the displacement map filter at the mouse location.
function magnify():void{// Position the filter.
var filterX:Number = (loader.mouseX) - (map.width / 2);
var filterY:Number = (loader.mouseY) - (map.height / 2);
var pt:Point = new Point(filterX, filterY);
var xyFilter:DisplacementMapFilter = new DisplacementMapFilter();
xyFilter.mapBitmap = map;
xyFilter.mapPoint = pt;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

276

表示オブジェクトのフィルター処理// The red in the map image will control x displacement.
xyFilter.componentX = BitmapDataChannel.RED;// The blue in the map image will control y displacement.
xyFilter.componentY = BitmapDataChannel.BLUE;
xyFilter.scaleX = 35;
xyFilter.scaleY = 35;
xyFilter.mode = DisplacementMapFilterMode.IGNORE;
loader.filters = [xyFilter];}// This function is called when the mouse moves. If the mouse is// over the loaded image, it applies the filter.
function moveMagnifier(event:MouseEvent):void{if (loader.hitTestPoint(loader.mouseX, loader.mouseY)){magnify();}}loader.addEventListener(MouseEvent.MOUSE_MOVE, moveMagnifier);

このコードでは、まずグラデーション塗りを適用した円が 2 つ生成されます。これらを合成することによって置き換えマッ
プイメージが形成されます。赤色の円は x 軸方向の置き換えを実現するためのもので（xyFilter.componentX =BitmapDataChannel.RED）、青色の円は y 軸方向の置き換えを実現するためのものです（xyFilter.componentY =BitmapDataChannel.BLUE）。また、置き換えマップイメージがどのようなものかを容易に把握できるようにするため、元の円が、マップイメージとなる合成後の円と共に画面下部に追加されます。

このコードでは、さらにイメージがロードされ、マウスが移動するとマウスポインターの下にある部分のイメージに置き換えフィルターが適用されます。グラデーション塗りを適用した円が置き換えマップイメージとして使用されているため、置き換えが適用された領域は、ポインターを中心として周囲に広がります。置き換えマップイメージのグレーの領域では、置き換えは発生しません。このグレーのカラーは 0x7F7F7F です。この階調がグレーの場合、青チャンネルと赤チャンネルの値は、それぞれのカラーチャンネルの階調範囲の中央の値とちょうど一致します。そのため、マップイメージのグレーの領域では置き換えが発生しません。同様に、円の中心でも置き換えが発生しません。この位置のカラーはグレーではありません。しかし、このカラーの青チャンネルと赤チャンネルの値は、赤、緑、青のちょうど中間のグレーの青チャンネルおよび赤チャンネルの値と一致しています。置き換えを発生させるカラーは青と赤です。したがって、この位置では置き換えが発生しません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

277

表示オブジェクトのフィルター処理

シェーダーフィルターFlash Player 10 以降、Adobe AIR 1.5 以降
ShaderFilter クラスでは、Pixel Bender シェーダーとして定義されているカスタムフィルター効果を使用することができます。フィルター効果は Pixel Bender シェーダーとして記述されるので、効果を完全にカスタマイズできます。フィルター
されたコンテンツがイメージ入力としてシェーダーに渡され、シェーダー処理の結果がフィルター結果になります。
注意：シェーダーフィルターは、Flash Player 10 および Adobe AIR 1.5 以降で ActionScript から使用できます。
シェーダーフィルターをオブジェクトに適用するには、使用する Pixel Bender シェーダーを表す Shader インスタンスを作成します。Shader インスタンスを作成する手順および入力イメージとパラメーター値を指定する方法について詳しくは、
285 ページの「Pixel Bender シェーダーの操作」を参照してください。
シェーダーをフィルターとして使用する場合は、次の 3 点に注意してください。

•

少なくとも 1 つの入力イメージを受け入れるようにシェーダーを定義する必要があります。

•

フィルターオブジェクト（フィルターが適用される表示オブジェクトまたは BitmapData オブジェクト）が最初の入力イメージ値としてシェーダーに渡されます。このため、手動で最初のイメージ入力値を指定しないでください。

•

シェーダーによって複数の入力イメージが定義される場合、追加入力を手動で指定する必要があります（つまり、Shader インスタンスに属する任意の ShaderInput インスタンスの input プロパティを設定します）。
シェーダーの Shader オブジェクトを作成したら、ShaderFilter インスタンスを作成します。このオブジェクトは、他のフィルターと同じように使用する実際のフィルターオブジェクトです。Shader オブジェクトを使用する ShaderFilter を作成するには、次に示すように ShaderFilter() コンストラクターを呼び出し、Shader オブジェクトを引数として渡します。
var myFilter:ShaderFilter = new ShaderFilter(myShader);シェーダーフィルター使用の完全な例については、302 ページの「フィルターでのシェーダーの使用」を参照してください。

表示オブジェクトのフィルター処理の例：Filter

Workbench

Flash Player 9 以降、Adobe AIR 1.0 以降
Filter Workbench は、イメージやその他のビジュアルコンテンツに様々なフィルターを適用し、同じ効果を ActionScriptで生成するために使用できる結果コードを表示するユーザーインターフェイスを備えています。このアプリケーションは、
様々なフィルターを試すためのツールを提供するだけではなく、次の操作も行います。

•

様々なフィルターのインスタンスの作成•

表示オブジェクトに対する複数のフィルターの適用

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。Filter Workbench アプリケー
ションファイルは Samples/FilterWorkbench フォルダーにあります。このアプリケーションは次のファイルで構成されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

278

表示オブジェクトのフィルター処理

ファイル

説明

com/example/programmingas3/filterWorkbench/FilterWorkbenchController.asフィルターを適用するコンテンツの切り替え、コンテ
ンツへのフィルターの適用など、アプリケーションの主な機能を提供するクラス。

com/example/programmingas3/filterWorkbench/IFilterFactory.as

各フィルターファクトリクラスによって実装される一般的なメソッドを定義するインターフェイス。このイン
ターフェイスは、FilterWorkbenchController クラス
が個々のフィルターファクトリクラスとやり取りする
ときに使用する一般的な機能を定義します。

com/example/programmingas3/filterWorkbench/ フォルダー：それぞれが IFilterFactory インターフェイスを実装するクラスのセット。これらの各クラスは、1 種類のフィ

BevelFactory.as

ルターの値を作成し、設定するための機能を提供します。アプリケーションのフィルタープロパティパネル

BlurFactory.as

は、これらのファクトリクラスを使用して特定のフィ
ルターのインスタンスを作成し、FilterWorkbenchController クラスがこのインスタン

ColorMatrixFactory.as
ConvolutionFactory.asスを取得して、イメージコンテンツに適用します。

DropShadowFactory.as
GlowFactory.as
GradientBevelFactory.as
GradientGlowFactory.as
com/example/programmingas3/filterWorkbench/IFilterPanel.ascom/example/programmingas3/filterWorkbench/ColorStringFormatter.as

アプリケーションでフィルター値の操作に使用される
ユーザーインターフェイスパネルを定義するクラスによって実装される、一般的なメソッドを定義するイン
ターフェイス。
数値で表したカラー値を 16 進数の String 形式に変換
するメソッドが含まれるユーティリティクラス。

com/example/programmingas3/filterWorkbench/GradientColor.as

値オブジェクトとして機能し、GradientBevelFilter とGradientGlowFilter の各カラーに関連付けられた 3 つの値（カラー、アルファ値、比率）を 1 つのオブジェ
クトに結合するクラス。

ユーザーインターフェイス（Flex）

FilterWorkbench.mxml

アプリケーションのユーザーインターフェイスを定義するメインファイル。

flexapp/FilterWorkbench.as

メインアプリケーションのユーザーインターフェイスの機能を提供するクラス。このクラスは、アプリケー
ション MXML ファイルのコードを実装したクラスとして使用されます。

flexapp/filterPanels フォルダー：1 つのフィルターのオプションを設定するために使用する各パネルの機能を提供する MXML コンポーネントのBevelPanel.mxml

セット。

BlurPanel.mxml
ColorMatrixPanel.mxml
ConvolutionPanel.mxml
DropShadowPanel.mxml
GlowPanel.mxml
GradientBevelPanel.mxml
GradientGlowPanel.mxml
画面上に読み込まれたイメージのコンテナとして機能する表示オブジェクト。

flexapp/ImageContainer.as

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

279

表示オブジェクトのフィルター処理

ファイル

説明

flexapp/controls/BGColorCellRenderer.as

DataGrid コンポーネントのセルの背景色を変更するために使用するカスタムセルレンダラー。

flexapp/controls/QualityComboBox.as

フィルターパネルの品質設定に使用できるコンボボッ
クスを定義するカスタムコントロール。

flexapp/controls/TypeComboBox.as

フィルターパネルの種類設定に使用できるコンボボッ
クスを定義するカスタムコントロール。

ユーザーインターフェイス（Flash）

FilterWorkbench.fla

アプリケーションのユーザーインターフェイスを定義するメインファイル。

flashapp/FilterWorkbench.as

メインアプリケーションのユーザーインターフェイスの機能を提供するクラス。このクラスは、アプリケー
ション FLA ファイルのドキュメントクラスとして使用されます。

flashapp/filterPanels フォルダー：1 つのフィルターのオプションを設定するために使用する各パネルの機能を提供するクラスのセット。

BevelPanel.as

各クラスには、メインアプリケーション FLA ファイル

BlurPanel.asのライブラリ内に、名前がクラスの名前に一致する関連付けられた MovieClip シンボルもあります（例えColorMatrixPanel.as

ば、シンボル「BlurPanel」は BlurPanel.as で定義さConvolutionPanel.as

れたクラスにリンクされています）。ユーザーインター
フェイスを構成するコンポーネントは、これらのシン
ボル内部に配置され、名前が指定されます。

DropShadowPanel.as
GlowPanel.as
GradientBevelPanel.as
GradientGlowPanel.as

画面上に読み込まれたイメージのコンテナとして機能する表示オブジェクト。

flashapp/ImageContainer.as

DataGrid コンポーネントのセルの背景色を変更するた

flashapp/BGColorCellRenderer.as

めに使用するカスタムセルレンダラー。

DataGrid コンポーネントのセルにボタンコンポーネン

flashapp/ButtonCellRenderer.as

トを含めるために使用するカスタムセルレンダラー。
フィルターされたイメージコンテンツ

com/example/programmingas3/filterWorkbench/ImageType.as

このクラスは、アプリケーションがフィルターを読み込んで適用できる 1 つのイメージファイルの種類とURL が含まれる値オブジェクトとして機能します。このクラスには、使用可能な実際のイメージファイルを表す定数のセットも含まれます。
アプリケーションでフィルターが適用されるイメージ
やその他のビジュアルコンテンツ。

images/sampleAnimation.swf,
images/sampleImage1.jpg,
images/sampleImage2.jpg

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

280

表示オブジェクトのフィルター処理

様々な ActionScript フィルターの使用Flash Player 9 以降、Adobe AIR 1.0 以降
Filter Workbench アプリケーションは、様々なフィルター効果を試し、その効果に関連する ActionScript コードを生成する際に役立つように設計されています。このアプリケーションを使用すると、ビットマップイメージや Flash が作成するア
ニメーションなどのビジュアルコンテンツが含まれる 3 つの 異なるフィルターから選択し、選択したイメージに 8 つの異なる ActionScript フィルターを個別に、または他のフィルターと組み合わせて適用できます。このアプリケーションには次のフィルターが含まれます。

•

ベベル（flash.filters.BevelFilter）•

ぼかし（flash.filters.BlurFilter）•

カラーマトリックス（flash.filters.ColorMatrixFilter）•

畳み込み（flash.filters.ConvolutionFilter）•

ドロップシャドウ（flash.filters.DropShadowFilter）•

グロー（flash.filters.GlowFilter）•

グラデーションベベル（flash.filters.GradientBevelFilter）•

グラデーショングロー（flash.filters.GradientGlowFilter）

イメージと、そのイメージに適用するフィルターを選択すると、選択したフィルターに固有のプロパティを設定するためのコントロールが含まれるパネルが表示されます。例えば、次のイメージは、ベベルフィルターが選択されたアプリケーションを示しています。

フィルタープロパティを調整すると、プレビューがリアルタイムで更新されます。1 つのフィルターをカスタマイズして適用
ボタンをクリックし、別のフィルターをカスタマイズして適用ボタンをクリックすることにより、複数のフィルターを適用することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

281

表示オブジェクトのフィルター処理

アプリケーションのフィルターパネルにはいくつかの機能と制限があります。

•

カラーマトリックスフィルターには、明度、コントラスト、彩度、色相など、イメージの一般的なプロパティを直接操作するためのコントロールのセットが含まれます。さらに、カスタムカラーマトリックス値を指定できます。

• ActionScript を使用した場合にのみ利用できる畳み込みフィルターには、頻繁に使用される畳み込みマトリックス値が含まれます。カスタム値を指定することもできます。ただし、ConvolutionFilter クラスには任意のサイズのマトリック
スを指定できますが、Filter Workbench アプリケーションは、最も一般的に使用されるフィルターサイズである固定の3 x 3 マトリックスを使用します。
•

置き換えマップフィルターとシェーダーフィルターは ActionScript だけで利用可能であり、Filter Workbench アプリ
ケーションでは使用できません。

フィルターインスタンスの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
Filter Workbench アプリケーションには、フィルターを作成するために各パネルによって使用されるクラスのセットが、使用可能なフィルターごとに 1 つずつ含まれます。フィルターを選択すると、そのフィルターパネルに関連付けられた
ActionScript コードが、適切なフィルターファクトリクラスのインスタンスを作成します （これらのクラスは、その目的が他のオブジェクトのインスタンスを作成することであり、実際の工場が個別の製品を製造することと類似しているので、「ファクトリクラス」と呼ばれます）。
パネルのプロパティ値を変更すると、パネルのコードがファクトリクラスの適切なメソッドを呼び出します。各ファクトリ
クラスには、パネルが適切なフィルターインスタンスの作成に使用する固有のメソッドが含まれます。例えば、ぼかしフィ
ルターを選択すると BlurFactory インスタンスが作成されます。BlurFactory クラスには、希望の BlurFilter インスタンスを作成するために合わせて使用される 3 つのパラメーター blurX、blurY、quality を受け入れる modifyFilter() メソッドが含まれます。
private var _filter:BlurFilter;
public function modifyFilter(blurX:Number = 4, blurY:Number = 4, quality:int = 1):void{_filter = new BlurFilter(blurX, blurY, quality);
dispatchEvent(new Event(Event.CHANGE));}

これに対して、畳み込みフィルターを選択した場合は、そのフィルターによって柔軟性が大幅に向上し、その結果、制御するプロパティが増えます。ConvolutionFactory クラスでは、フィルターパネルで別の値を選択すると、次のコードが呼び出されます。
private var _filter:ConvolutionFilter;
public function modifyFilter(matrixX:Number = 0,
matrixY:Number = 0,
matrix:Array = null,divisor:Number = 1.0,
bias:Number = 0.0,
preserveAlpha:Boolean = true,
clamp:Boolean = true,
color:uint = 0,alpha:Number = 0.0):void{_filter = new ConvolutionFilter(matrixX, matrixY, matrix, divisor, bias, preserveAlpha, clamp, color,alpha);
dispatchEvent(new Event(Event.CHANGE));}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

282

表示オブジェクトのフィルター処理

いずれの場合でも、フィルター値が変化すると、ファクトリオブジェクトが Event.CHANGE イベントを送出し、フィルターの値が変更されたことをリスナーに通知します。フィルターされたコンテンツに実際にフィルターを適用する

FilterWorkbenchController クラスは、そのイベントを待機して、フィルターの新しいコピーを取得し、フィルターされたコンテンツにそのコピーを再度適用する必要がある時期を確認します。

FilterWorkbenchController クラスは、各フィルターファクトリクラスに固有の詳細情報を認識する必要はありません。
フィルターが変更され、フィルターのコピーにアクセスできるようになったことだけを認識する必要があります。これをサポートするために、アプリケーションの FilterWorkbenchController インスタンスがそのジョブを実行できるように、
フィルターファクトリクラスが提供する必要がある動作を定義するインターフェイス、IFilterFactory がアプリケーションに含まれます。IFilterFactory は、FilterWorkbenchController クラスで使用される getFilter () メソッドを定義します。
function getFilter():BitmapFilter;

getFilter() インターフェイスメソッドの定義では、特定の種類のフィルターではなく、BitmapFilter インスタンスを返すことを指定しています。BitmapFilter クラスは、特定の種類のフィルターを定義するものではなく、すべてのフィルタークラ
スを構築する際の基礎となるクラスです。各フィルターファクトリクラスは、getFilter() メソッドの特定の実装を定義し、このメソッドで、構築したフィルターオブジェクトへの参照を返します。例えば、ConvolutionFactory クラスの簡略化した
ソースコードを次に示します。
public class ConvolutionFactory extends EventDispatcher implements IFilterFactory{// ------- Private vars ------private var _filter:ConvolutionFilter;...
// ------- IFilterFactory implementation ------public function getFilter():BitmapFilter{
return _filter;}...
}

ConvolutionFactory クラスによる getFilter() メソッドの実装では ConvolutionFilter インスタンスが返されますが、
getFilter() を呼び出すどのオブジェクトも、必ずしもそれを認識していません。ConvolutionFactory が従う getFilter() メ
ソッドの定義に応じて、いずれかの ActionScript フィルタークラスのインスタンスである任意の BitmapFilter インスタン
スを返す必要があります。

表示オブジェクトに対するフィルターの適用Flash Player 9 以降、Adobe AIR 1.0 以降
前に説明したように、Filter Workbench アプリケーションは FilterWorkbenchController クラスのインスタンス（以降は「コントローラーインスタンス」と呼ぶ）を使用します。このインスタンスが、選択したビジュアルオブジェクトに対するフィルターの適用という実際のタスクを実行します。コントローラーインスタンスがフィルターを適用するには、その前に、フィルターの適用先のイメージまたはビジュアルコンテンツを認識しておく必要があります。イメージを選択すると、アプリケーションは FilterWorkbenchController クラスの setFilterTarget() メソッドを呼び出し、ImageType クラスで定義された定数の 1 つで渡します。
public function setFilterTarget(targetType:ImageType):void{...
_loader = new Loader();...
_loader.contentLoaderInfo.addEventListener(Event.COMPLETE, targetLoadComplete);...
}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

283

表示オブジェクトのフィルター処理

その情報を使用して、コントローラーインスタンスは指定のファイルを読み込み、その後に _currentTarget という名前のイ
ンスタンス変数に保存します。
private var _currentTarget:DisplayObject;private function targetLoadComplete(event:Event):void{...
_currentTarget = _loader.content;...
}

フィルターを選択すると、アプリケーションはコントローラーインスタンスの setFilter() メソッドを呼び出し、関連するフィルターファクトリオブジェクトに対する参照をコントローラーに渡し、_filterFactory という名前のインスタンス変数に保存します。
private var _filterFactory:IFilterFactory;
public function setFilter(factory:IFilterFactory):void{...
_filterFactory = factory;_filterFactory.addEventListener(Event.CHANGE, filterChange);}

前述のように、コントローラーインスタンスは、指定されたフィルターファクトリインスタンスの固有のデータ型を認識せず、オブジェクトが IFilterFactory インスタンスを実装することだけを認識します。つまり、getFilter() メソッドを持っており、フィルターが変更されたときに change（Event.CHANGE）イベントを送出するということです。
ユーザーがフィルターパネルでフィルターのプロパティを変更すると、コントローラーインスタンスでは、コントローラー
インスタンスの filterChange() メソッドを呼び出すフィルターファクトリの change イベントを介して、フィルターが変更されたことが認識されます。そのメソッドは、次に applyTemporaryFilter() メソッドを呼び出します。
private function filterChange(event:Event):void{
applyTemporaryFilter();}
private function applyTemporaryFilter():void{
var currentFilter:BitmapFilter = _filterFactory.getFilter();// Add the current filter to the set temporarily_currentFilters.push(currentFilter);// Refresh the filter set of the filter target_currentTarget.filters = _currentFilters;// Remove the current filter from the set// (This doesn't remove it from the filter target, since// the target uses a copy of the filters array internally.)_currentFilters.pop();}

表示オブジェクトに対するフィルターの適用は applyTemporaryFilter() メソッド内部で行われます。最初に、コントローラー
がフィルターファクトリの getFilter() メソッドを呼び出して、フィルターオブジェクトに対する参照を取得します。
var currentFilter:BitmapFilter = _filterFactory.getFilter();

コントローラーインスタンスには _currentFilters という名前の Array インスタンスがあり、ここには、表示オブジェクトに適用されたすべてのフィルターが保存されています。次に、新たに更新されたフィルターを配列に追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

284

表示オブジェクトのフィルター処理_currentFilters.push(currentFilter);

次に、このコードがフィルターの配列を表示オブジェクトの filters プロパティに割り当て、このプロパティが実際にフィルターをイメージに適用します。
_currentTarget.filters = _currentFilters;

最後に、この最後に追加したフィルターはこの時点でも「稼働中」のフィルターなので、表示オブジェクトに永続的に適用してはなりません。したがって、_currentFilters 配列から削除されます。
_currentFilters.pop();

このフィルターを配列から削除しても、フィルターされた表示オブジェクトには影響はありません。これは、表示オブジェ
クトが、filters プロパティに適用されたときにフィルター配列のコピーを作成し、元の配列ではなく、その内部配列を使用するからです。したがって、フィルターの配列に対して行われたすべての変更は、配列が表示オブジェクトの filters プロパ
ティに再び割り当てられるまでは、表示オブジェクトに影響を与えません。

最終更新日 2015/10/14

285

第 15 章：Pixel Bender シェーダーの操作
Flash Player 10 以降、Adobe AIR 1.5 以降
Adobe Pixel Bender Toolkit を使用すると、開発者は、グラフィックエフェクトを作成してその他のイメージやデータの処理を行うシェーダーを記述することができます。Pixel Bender のバイトコードは、ActionScript で実行してイメージデータ
やビジュアルコンテンツにエフェクトを適用できます。ActionScript で Pixel Bender シェーダーを使用することによって、ActionScript のビルトイン機能をはるかに超えたカスタムビジュアルエフェクトの作成やデータ処理が可能です。
注意：Pixel Bender は、Flash Player 10 および Adobe AIR 1.5 以降でサポートされています。Pixel Bender のブレンド、
フィルター、および塗りは GPU レンダリングではサポートされていません。
関連項目

Adobe Pixel Bender Technology Center
Pixel Bender Developer's Guide
Pixel Bender Reference
flash.display.Shader
flash.filters.ShaderFilter
Pixel Bender の基本事項（Flash 向け）
Flex および AIR のための Pixel Bender の基礎

Pixel Bender シェーダーの基礎
Flash Player 10 以降、Adobe AIR 1.5 以降
Adobe Pixel Bender は、イメージコンテンツの作成や操作に使用するプログラミング言語です。Pixel Bender を使用して、カーネル（シェーダーとも呼ばれます）を作成します。シェーダーでは、イメージの各ピクセルで個別に実行される単一の関数を定義します。各関数呼び出し結果が、イメージ内のそのピクセル座標の出力カラーとなります。入力イメージおよびパラメーター値を指定して、操作をカスタマイズできます。シェーダーの 1 回の実行では、入力およびパラメーター値は一定です。唯一変化するのは、関数呼び出しの結果がカラーとなるピクセル座標です。
可能な場合は、複数の出力ピクセル座標のシェーダー関数が並列で呼び出されます。これにより、シェーダーのパフォーマンスが向上し、パフォーマンスに優れた処理を提供できます。

ActionScript では、シェーダーを使用して次の 3 種類のエフェクトを簡単に作成できます。

•

描画の塗り

•

ブレンドモード•

フィルター

シェーダーは、スタンドアローンモードでも実行できます。スタンドアローンモードを使用する場合は、事前に用途を指定
せずに、シェーダーの結果に直接アクセスします。結果はイメージデータ、バイナリデータ、数値データとしてアクセスできます。データがイメージデータである必要はありません。これらのデータセットを入力としてシェーダーに指定できます。
シェーダーでデータが処理されると、シェーダーで返された結果データにアクセスできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

286

Pixel Bender シェーダーの操作

Pixel Bender は、Flash Player 10 および Adobe AIR 1.5 以降でサポートされています。Pixel Bender のブレンド、フィル
ター、および塗りは GPU レンダリングではサポートされていません。モバイルデバイスでは、Pixel Bender シェーダーはCPU レンダリングで実行されます。ただし、デスクトップコンピューターの場合と同じレベルのパフォーマンスは得られません。多くのシェーダープログラムを実行する場合のフレームレートは毎秒数フレームです。
重要な概念と用語
次の参照リストに、Pixel Bender シェーダーの作成および使用に関連した重要な用語を示します。
カーネル Pixel Bender では、カーネルはシェーダーと同じものです。Pixel Bender のコードでカーネルを定義し、イメー
ジの各ピクセルで個別に実行される単一の関数を定義します。

Pixel Bender バイトコード Pixel Bender カーネルは、コンパイル時に Pixel Bender バイトコードに変換されます。バイ
トコードは、実行時にアクセスされ、実行されます。

Pixel Bender 言語 Pixel Bender カーネルの作成に使用するプログラミング言語です。
Pixel Bender Toolkit Pixel Bender ソースコードから Pixel Bender バイトコードファイルを作成するのに使用するアプ
リケーションです。ツールキットを使用して、Pixel Bender ソースコードを作成、テスト、コンパイルできます。

Shader 本書の用途では、シェーダーとは Pixel Bender 言語で作成された一連の機能です。シェーダーのコードでは、ビジュアルエフェクトの作成や計算の実行が行われます。どちらの場合も、シェーダーではデータセットが返されます（通常はイメージのピクセル）。シェーダーは各データポイントで同じ操作を実行しますが、唯一の違いは出力ピクセルの座標です。シェーダーは ActionScript で作成するのではありません。Pixel Bender 言語で作成され、Pixel Bender バイトコードにコンパイルされます。コンパイル時に SWF ファイルに埋め込んだり、実行時に外部ファイルとしてロードしたりできます。どちらの場合も、ActionScript で、Shader オブジェクトを作成し、そのオブジェクトをシェーダーのバイトコードにリンクすることでアクセスします。
シェーダー入力 計算で使用するためにシェーダーに提供される複雑な入力であり、通常はビットマップイメージデータです。シェーダーで定義される各入力変数では、単一値（つまり、単一のイメージまたはバイナリデータセット）がシェー
ダーの実行全体に使用されます。
シェーダーパラメーター 計算で使用するためにシェーダーに提供される単一値（または値の制限されたセット）です。各パ
ラメーター値は単一のシェーダー実行用に定義され、シェーダー実行全体で同じ値が使用されます。
コード例の使用
記載されているサンプルコードリストを実際にテストすることができます。コードをテストするには、コードを実行し、作成された SWF で結果を確認する必要があります。すべての例は、描画 API を使用して、シェーダーエフェクトを使用する
コンテンツや、シェーダーエフェクトで変更されるコンテンツを作成します。
例で示すコードリストの大半は、2 つの部分から成ります。1 つは、例で使用するシェーダーの Pixel Bender ソースコードです。まず、Pixel Bender Toolkit を使用して、ソースコードを Pixel Bender バイトコードファイルにコンパイルする必要があります。Pixel Bender バイトコードファイルを作成するには、以下の手順を実行します。

1 Adobe Pixel Bender Toolkit を開きます。必要に応じて、メニューの Build ／ Turn on Flash Player warnings anderrors を選択します。
2 Pixel Bender コードリストをコピーし、Pixel Bender Toolkit のコードエディターペインに貼り付けます。
3 メニューの File ／ Export kernel filter for Flash Player を選択します。
4 Pixel Bender バイトコードファイルを Flash ドキュメントと同じディレクトリに保存します。ファイル名は、例の説明で指定されている名前と一致している必要があります。
各例の ActionScript の部分は、クラスファイルとして作成されています。この例を Flash Professional でテストするには、
次のようにします。

1 新しい Flash ドキュメントを作成し、コンピューターに保存します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

287

Pixel Bender シェーダーの操作

2 新しい ActionScript ファイルを作成し、Flash ドキュメントと同じディレクトリに保存します。ファイル名は、コードリ
スト内のクラスの名前と同じ名前にしてください。例えば、コードリストで MyApplication というクラスが定義されている場合は、MyApplication.as という名前で ActionScript ファイルを保存します。

3 ActionScript ファイル内にコードをコピーし、ファイルを保存します。
4 Flash ドキュメント内で、ステージまたはワークスペースの空白部分をクリックして、ドキュメントのプロパティインス
ペクターをアクティブにします。

5 プロパティインスペクターの「ドキュメントクラス」フィールドに、テキストからコピーした ActionScript クラスの名前を入力します。

6 制御／ムービープレビューを使用して、プログラムを実行します。
例の結果がプレビューウィンドウに表示されます。
サンプルコードをテストするこれらのテクニックについては、1059 ページの「ActionScript の使用方法の例」で詳しく説明しています。

シェーダーのロードまたは埋め込みFlash Player 10 以降、Adobe AIR 1.5 以降
Pixel Bender シェーダーを ActionScript で使用するには、最初に、ActionScript のコードからシェーダーにアクセスしま
す。シェーダーは Adobe Pixel Bender Toolkit を使用して作成され、Pixel Bender 言語で記述されているので、ActionScript から直接アクセスできません。代わりに、ActionScript で Pixel Bender シェーダーを表す Shader クラスのイ
ンスタンスを作成します。Shader オブジェクトを使用すると、必要なパラメーターや入力イメージの値など、シェーダーに関する情報を検出できます。実際にシェーダーを使用するには Shader オブジェクトを他のオブジェクトに渡します。例えば、シェーダーをフィルターとして使用するには、ShaderFilter オブジェクトの shader プロパティに Shader オブジェクトを割り当てます。また、シェーダーを描画の塗りに使用するには、Graphics.beginShaderFill() メソッドに Shader オブジェク
トを引数として渡します。

ActionScript コードは Adobe Pixel Bender Toolkit（.pbj ファイル）で作成されたシェーダーに 2 つの方法でアクセスできます。

•

実行時にロード：シェーダーファイルは URLLoader オブジェクトを使用して外部アセットとしてロードできます。この方法はテキストファイルなどの外部アセットをロードすることと似ています。次の例は、シェーダーバイトコードファ
イルを実行時にロードし、それを Shader インスタンスにリンクする方法を示しています。
var loader:URLLoader = new URLLoader();loader.dataFormat = URLLoaderDataFormat.BINARY;
loader.addEventListener(Event.COMPLETE, onLoadComplete);loader.load(new URLRequest("myShader.pbj"));var shader:Shader;function onLoadComplete(event:Event):void {// Create a new shader and set the loaded data as its bytecode
shader = new Shader();shader.byteCode = loader.data;// You can also pass the bytecode to the Shader() constructor like this:// shader = new Shader(loader.data);// do something with the shader}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

288

Pixel Bender シェーダーの操作• SWF ファイルに埋め込む：シェーダーファイルは [Embed] メタタグを使用してコンパイル時に SWF ファイルに埋め込
むことができます。[Embed] メタデータタグは、Flex SDK を使用して SWF ファイルをコンパイルした場合にのみ使用できます。この例では、[Embed] タグの source パラメーターがシェーダーファイルを指定し、mimeType パラメーター
は、「application/octet-stream」となります。
[Embed(source="myShader.pbj", mimeType="application/octet-stream")]var MyShaderClass:Class;// ...
// create a shader and set the embedded shader as its bytecodevar shader:Shader = new Shader();shader.byteCode = new MyShaderClass();// You can also pass the bytecode to the Shader() constructor like this:// var shader:Shader = new Shader(new MyShaderClass());// do something with the shader

どちらの場合も、未処理のシェーダーバイトコード（URLLoader.data プロパティまたは [Embed] データクラスのインスタンス）を Shader インスタンスにリンクします。前の例で示すように、バイトコードは 2 つの方法で Shader インスタンスに割り当てることができます。シェーダーバイトコードを引数として Shader() コンストラクターに渡します。または、Shader
インスタンスの byteCode プロパティとして設定することもできます。

Pixel Bender シェーダーを作成し、Shader オブジェクトにリンクすると、様々な方法でエフェクトの作成にシェーダーを使用できます。フィルター、ブレンドモード、ビットマップの塗りなどに使用したり、ビットマップなどのデータのスタン
ドアローン処理に使用することもできます。Shader オブジェクトの data プロパティを使用してシェーダーのメタデータへのアクセス、入力イメージの指定およびパラメーター値の設定も行うことができます。

シェーダーメタデータへのアクセス
Flash Player 10 以降、Adobe AIR 1.5 以降
Pixel Bender シェーダーのカーネルを作成するとき、Pixel Bender のソースコード内でシェーダーに関するメタデータを指定できます。ActionScript でシェーダーを使用する際、シェーダーを調べてそのメタデータを抽出できます。
Shader インスタンスを作成して、Pixel Bender シェーダーにリンクする場合、シェーダーに関するデータを含む
ShaderData オブジェクトが作成され、Shader オブジェクトの data プロパティに格納されます。ShaderData クラスはそれ自体のプロパティは定義しません。ただし、実行時に、シェーダーソースコードで定義されている個々のメタデータ値に対応するプロパティが ShaderData オブジェクトに動的に追加されます。プロパティにはメタデータで指定されている名前と同じ名前が指定されます。例えば、Pixel Bender シェーダーのソースコードに次のようなメタデータ定義が含まれているとします。
namespace : "Adobe::Example";vendor : "Bob Jones";version : 1;
description : "Creates a version of the specified image with the specified brightness.";

このシェーダー用に作成される ShaderData オブジェクトには次のようなプロパティと値が設定されます。

• namespace（String）："Adobe::Example"• vendor（String）："Bob Jones"• version（String）："1"• description（String）："Creates a version of the specified image with the specified brightness"

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

289

Pixel Bender シェーダーの操作

メタデータプロパティは ShaderData オブジェクトに動的に追加されるので、for..in ループを使用して ShaderData オブ
ジェクトを調べることができます。この方法を使用すると、シェーダーにメタデータが含まれているかどうかとメタデータの値を知ることができます。メタデータプロパティのほか、ShaderData オブジェクトには、シェーダーで定義されている
入力とパラメーターを表すプロパティを設定できます。for..in ループを使用して ShaderData オブジェクトを調べる場合、プロパティが入力（ShaderInput インスタンス）か、パラメーター（ShaderParameter インスタンス）か、メタデータ値（String インスタンス）かを識別するために各プロパティのデータ型を調べます。次の例では、for..in ループを使用してシェーダーの data プロパティのダイナミックプロパティを調べる方法を示します。各メタデータ値が metadata という名前のVector インスタンスに追加されます。この例では、myShader という名前の Shader インスタンスが既に作成されているとします。
var shaderData:ShaderData = myShader.data;
var metadata:Vector.<String> = new Vector.<String>();for (var prop:String in shaderData){
if (!(shaderData[prop] is ShaderInput) && !(shaderData[prop] is ShaderParameter)){
metadata[metadata.length] = shaderData[prop];}}// do something with the metadata

この例をシェーダーの入力およびパラメーターの抽出も行うように変更した例は、289 ページの「シェーダーの入力およびパラメーターの識別」を参照してください。入力とパラメーターのプロパティについて詳しくは、289 ページの「シェーダーの入力およびパラメーターの値の指定」を参照してください。

シェーダーの入力およびパラメーターの値の指定Flash Player 10 以降、Adobe AIR 1.5 以降
多くの場合、Pixel Bender シェーダーは、シェーダー処理過程で 1 つまたは複数の入力イメージを使用するように定義されています。例えば、シェーダーがソースイメージを取得し、特定のエフェクトを適用してそのイメージを出力する場合などがあります。シェーダーの使用方法に応じて、入力値が自動的に指定される場合と、値を明示的に指定する必要がある場合があります。同様に、多くのシェーダーでは、シェーダーの出力をカスタマイズするためのパラメーターを指定します。
シェーダーを使用する前に、個々のパラメーターの値も明示的に指定する必要があります。

Shader オブジェクトの data プロパティは、シェーダーの入力およびパラメーターの設定と、そのシェーダーに入力またはパラメーターが必要かどうかの特定に使用されます。data プロパティは ShaderData インスタンスです。

シェーダーの入力およびパラメーターの識別Flash Player 10 以降、Adobe AIR 1.5 以降
シェーダーの入力値とパラメーター値を指定するには、まず、そのシェーダーに入力イメージとパラメーターが必要かどうかを確認します。各 Shader インスタンスには ShaderData オブジェクトを含む data プロパティがあります。シェーダーに定義されている入力やパラメーターには、ShaderData オブジェクトのプロパティとしてアクセスします。プロパティの名
前は、シェーダーソースコードで指定されている入力やパラメーターの名前と一致します。例えば、シェーダーに src という入力が定義されている場合、ShaderData オブジェクトは src という名前のプロパティでその入力を表します。入力を表す
個々のプロパティは ShaderInput インスタンスで、パラメーターを表す個々のプロパティは ShaderParameter インスタンスです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

290

Pixel Bender シェーダーの操作

理想的には、シェーダーの作者が、シェーダーに必要な入力イメージの値やパラメーター、それらが表す内容、適切な値など、シェーダーに関する説明を提供します。
ただし、シェーダーに説明がない場合やソースコードがない場合、シェーダーデータを調べて入力やパラメーターを確認できます。入力やパラメーターを表すプロパティは ShaderData オブジェクトに動的に追加されます。したがって、for..inループを使用して ShaderData オブジェクトを調べ、関連付けられているシェーダーで入力やパラメーターが定義されているかどうかを確認できます。288 ページの「シェーダーメタデータへのアクセス」で説明しているように、シェーダーに定義されているメタデータ値には、Shader.data プロパティに追加されたダイナミックプロパティとしてもアクセスできます。
この方法でシェーダーの入力とパラメーターを識別する場合は、ダイナミックプロパティのデータ型を調べます。

ShaderInput インスタンスであるプロパティは、入力を表し、ShaderParameter インスタンスであるプロパティは、パラ
メーターを表します。どちらでもなければ、メタデータ値です。次の例では、for..in ループを使用してシェーダーの data プ
ロパティのダイナミックプロパティを調べる方法を示します。各入力（ShaderInput オブジェクト）は inputs という名前のVector インスタンスに追加されます。各パラメーター（ShaderParameter オブジェクト）は parameters という名前のVector インスタンスに追加されます。最後に、メタデータプロパティは metadata という名前の Vector インスタンスに追加されます。この例では、myShader という名前の Shader インスタンスが既に作成されているとします。
var shaderData:ShaderData = myShader.data;
var inputs:Vector.<ShaderInput> = new Vector.<ShaderInput>();var parameters:Vector.<ShaderParameter> = new Vector.<ShaderParameter>();var metadata:Vector.<String> = new Vector.<String>();for (var prop:String in shaderData){
if (shaderData[prop] is ShaderInput){
inputs[inputs.length] = shaderData[prop];}
else if (shaderData[prop] is ShaderParameter){parameters[parameters.length] = shaderData[prop];}
else{
metadata[metadata.length] = shaderData[prop];}}// do something with the inputs or properties

シェーダー入力値の指定
Flash Player 10 以降、Adobe AIR 1.5 以降
多くのシェーダーは、シェーダー処理過程で使用する 1 つまたは複数の入力イメージを必要とします。ただし、多くの場合、Shader オブジェクトの使用時に入力は自動的に指定されます。例えば、1 つの入力を使用するシェーダーがあり、そのシェーダーがフィルターとして使用される場合を考えてみましょう。そのフィルターが表示オブジェクトまたはBitmapData オブジェクトに適用されるとき、オブジェクトは自動的に入力として設定されます。この場合は入力値を明示的に設定しません。
ただし、場合によっては、特にシェーダーに複数の入力が定義されている場合は、入力値を明示的に設定します。シェー
ダー内に定義されている各入力は ActionScript 内では ShaderInput オブジェクトで表されます。289 ページの「シェーダーの入力およびパラメーターの識別」で説明しているように、ShaderInput オブジェクトは Shader オブジェクトの data
プロパティにおける ShaderData インスタンスのプロパティです。例えば、シェーダーに src という名前の入力が定義されていて、そのシェーダーが myShader という名前の Shader オブジェクトにリンクしているとします。この場合、src 入力に対応する ShaderInput オブジェクトには次の識別子を使用してアクセスします。
myShader.data.src

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

291

Pixel Bender シェーダーの操作

各 ShaderInput オブジェクトには、入力の値を設定するために使用される input プロパティがあります。イメージデータを指定するには、input プロパティを BitmapData インスタンスに設定します。また、バイナリデータや数値データを指定す
るには、input プロパティを BitmapData または Vector.<Number> インスタンスに設定します。BitmapData またはVector.<Number> インスタンスの input プロパティとしての使用や制限について詳しくは、『Adobe Flash Platform 用
ActionScript 3.0 リファレンスガイド』の ShaderInput.input を参照してください。

input プロパティのほか、ShaderInput オブジェクトには、入力に必要なイメージの種類を特定するために使用するプロパ
ティもあります。これらのプロパティには width、height および channels プロパティが含まれます。各 ShaderInput オブ
ジェクトには、明示的に入力値を指定する必要があるかどうかの判断に役立つ index プロパティもあります。シェーダーに必要な入力が自動的に設定された数より多い場合は、これらの入力の値を設定します。シェーダーの様々な使用方法や、入力値が自動的に設定されるかどうかについて詳しくは、294 ページの「シェーダーの使用」を参照してください。

シェーダーパラメーター値の指定
Flash Player 10 以降、Adobe AIR 1.5 以降
一部のシェーダーは、結果出力の作成時に使用するパラメーター値を定義します。例えば、イメージの輝度を変更する
シェーダーは、操作が輝度に与える影響を決定する brightness パラメーターを指定します。シェーダーのパラメーター定義に応じて、シェーダーで定義されている 1 つのパラメーターに必要な値が 1 つである場合も複数である場合もあります。
シェーダーで定義されている各パラメーターは、ActionScript 内では ShaderParameter オブジェクトで表されます。289
ページの「シェーダーの入力およびパラメーターの識別」で説明しているように、ShaderParameter オブジェクトはShader オブジェクトの data プロパティにおける ShaderData インスタンスのプロパティです。例えば、シェーダーにbrightness という名前のパラメーターが定義されていて、そのシェーダーが myShader という名前の Shader オブジェクトで表されているとします。この場合、brightness パラメーターに対応する ShaderParameter には次の識別子を使用してアクセスします。
myShader.data.brightness

パラメーターの値（1 つまたは複数）を設定するには、その値を含む ActionScript 配列を作成し、配列をShaderParameter オブジェクトの value プロパティに割り当てます。1 つのシェーダーパラメーターに複数の値が必要な場
合があるので、value プロパティは Array インスタンスとして定義されます。シェーダーパラメーターに必要な値が 1 つでも、値を ShaderParameter.value プロパティに割り当てるには、値を Array オブジェクトに含める必要があります。次の例
は、value プロパティとして 1 つの値を設定する方法を示します。
myShader.data.brightness.value = [75];シェーダーの Pixel Bender ソースコードがパラメーターのデフォルト値を定義している場合、Shader オブジェクトの作成時に、そのデフォルト値を含む配列が作成され、ShaderParameter オブジェクトの value プロパティに割り当てられます。

value プロパティに配列（デフォルト配列である場合も含む）を割り当てた後は、配列要素の値を変更することによってパラ
メーター値を変更できます。新しい配列を作成して value プロパティに割り当てる必要はありません。
次の例は、ActionScript 内でシェーダーのパラメーター値を設定する方法を示します。この例ではシェーダーは color という名前のパラメーターを定義します。color パラメーターは Pixel Bender ソースコードで float4 変数として宣言されています。つまり、4 つの浮動小数点数を持つ配列です。この例では、color パラメーター値が繰り返し変更され、変更のたびに画面に色付きの矩形を描画するシェーダーが使用されます。結果は色が変化するアニメーションになります。
注意：このコード例は Ryan Taylor 氏が作成したものです。この例の掲載を許可してくれた Ryan 氏に感謝いたします。
Ryan 氏の著述は www.boostworthy.com/ で読むことができます。

ActionScript コードには重要な 3 つのメソッドがあります。

• init()：init() メソッドで、シェーダーが含まれる Pixel Bender バイトコードファイルがロードされます。ファイルがロードされると、onLoadComplete() メソッドが呼び出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

292

Pixel Bender シェーダーの操作• onLoadComplete()：onLoadComplete() メソッドで、shader という名前の Shader オブジェクトが作成されます。また、
texture という名前の Sprite インスタンスも作成されます。renderShader() メソッドで、1 フレームに 1 回、シェーダーの結果が texture に描画されます。

• onEnterFrame()：onEnterFrame() メソッドは 1 フレームに 1 回呼び出され、アニメーションエフェクトを作成します。このメソッドで、シェーダーパラメーター値が新しい色に設定され、renderShader() メソッドが呼び出されてシェーダーの結果が矩形として描画されます。

• renderShader()：renderShader() メソッドで、シェーダーの塗りを指定するために Graphics.beginShaderFill() メソッドが呼び出されます。それによって、シェーダー出力が定義する塗り（生成された色）で矩形が描画されます。この方法でシェーダーを使用する方法について詳しくは、294 ページの「描画の塗りでのシェーダーの使用」を参照してください。
この例の ActionScript コードは次のようになります。Flash Builder の ActionScript のみのプロジェクトでは、このクラスをメインアプリケーションクラスとして使用します。または、Flash Professional の FLA ファイルでは、ドキュメントク
ラスとして使用します。
package{import flash.display.Shader;import flash.display.Sprite;
import flash.events.Event;import flash.net.URLLoader;import flash.net.URLLoaderDataFormat;
import flash.net.URLRequest;
public class ColorFilterExample extends Sprite{
private const DELTA_OFFSET:Number = Math.PI * 0.5;
private var loader:URLLoader;private var shader:Shader;private var texture:Sprite;
private var delta:Number = 0;
public function ColorFilterExample(){init();}
private function init():void{loader = new URLLoader();loader.dataFormat = URLLoaderDataFormat.BINARY;
loader.addEventListener(Event.COMPLETE, onLoadComplete);loader.load(new URLRequest("ColorFilter.pbj"));}private function onLoadComplete(event:Event):void{
shader = new Shader(loader.data);
texture = new Sprite();addChild(texture);
addEventListener(Event.ENTER_FRAME, onEnterFrame);}
private function onEnterFrame(event:Event):void{

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

293

Pixel Bender シェーダーの操作

shader.data.color.value[0] = 0.5 + Math.cos(delta - DELTA_OFFSET) * 0.5;
shader.data.color.value[1] = 0.5 + Math.cos(delta) * 0.5;
shader.data.color.value[2] = 0.5 + Math.cos(delta + DELTA_OFFSET) * 0.5;// The alpha channel value (index 3) is set to 1 by the kernel's default// value. This value doesn't need to change.
delta += 0.1;
renderShader();}
private function renderShader():void{
texture:graphics.clear();texture.graphics.beginShaderFill(shader);texture.graphics.drawRect(0, 0, stage.stageWidth, stage.stageHeight);
texture.graphics.endFill();}}}

次の例は、「ColorFilter.pbj」という Pixel Bender バイトコードファイルの作成に使用された ColorFilter シェーダーカー
ネルのソースコードです。
<languageVersion : 1.0;>
kernel ColorFilter<namespace : "boostworthy::Example";vendor : "Ryan Taylor";
version : 1;
description : "Creates an image where every pixel has the specified color value.";>{
output pixel4 result;parameter float4 color<
minValue:float4(0, 0, 0, 0);
maxValue:float4(1, 1, 1, 1);
defaultValue:float4(0, 0, 0, 1);>;
void evaluatePixel(){
result = color;}}

パラメーターの説明がないシェーダーを使用する場合、ShaderParameter オブジェクトの type プロパティを調べることによって、配列に含まれている要素のデータ型と個数を知ることができます。type プロパティはシェーダー自体で定義されているパラメーターのデータ型を示します。各パラメーター型に必要な要素の個数と型については、『ActionScript 3.0 リファ
レンスガイド』の ShaderParameter.value プロパティの説明を参照してください。
各 ShaderParameter オブジェクトには、一連のシェーダーパラメーターの中でのそのパラメーターの順番を示す index プロ
パティもあります。これらのプロパティのほか、ShaderParameter オブジェクトには、シェーダーの作者が指定したメタ
データ値を保持するプロパティを追加できます。例えば、作者はパラメーターの最小、最大、デフォルトなどの値をメタデータ値として指定できます。作者が指定したメタデータ値は、ShaderParameter オブジェクトにダイナミックプロパティ
として追加されます。そのようなプロパティを調べるには、for..in ループを使用して ShaderParameter オブジェクトのダイ
ナミックプロパティをループ処理し、そのメタデータを識別します。次の例では、for..in ループを使用して最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

294

Pixel Bender シェーダーの操作

ShaderParameter オブジェクトのメタデータを識別する方法を示します。各メタデータ値が metadata という名前の Vector
インスタンスに追加されます。この例では、myShader という名前の Shader インスタンスが既に作成され、brightness という名前のパラメーターがあることがわかっているとします。
var brightness:ShaderParameter = myShader.data.brightness;var metadata:Vector.<String> = new Vector.<String>();for (var prop:String in brightness){
if (brightness[prop] is String){
metadata[metadata.length] = brightness[prop];}}// do something with the metadata

シェーダーの使用
Flash Player 10 以降、Adobe AIR 1.5 以降
Pixel Bender シェーダーが ActionScript で Shader オブジェクトとして使用可能になると、様々な方法で使用できます。

•

シェーダーによる描画の塗り：シェーダーは描画 api を使用して描画したシェイプの塗りの部分を定義します。

•

ブレンドモード：シェーダーは 2 つの重なった表示オブジェクトのブレンドを定義します。

•

フィルター：シェーダーはビジュアルコンテンツの外観を変更するフィルターを定義します。

•

スタンドアローンのシェーダー処理：出力の用途を指定しないままシェーダー処理を実行します。シェーダーは必要に応じてバックグランドでも実行でき、処理が完了すると結果を使用できるようになります。この方法は、ビットマップデー
タの生成やビジュアルデータ以外のデータの処理にも使用できます。

描画の塗りでのシェーダーの使用Flash Player 10 以降、Adobe AIR 1.5 以降
シェーダーを使用して描画の塗りを作成する場合は、描画 API メソッドを使用してベクターシェイプを作成します。描画
API を使用してビットマップイメージをビットマップ塗りに使用できるのと同様に、シェーダーの出力はシェイプの塗りに使用されます。シェーダーの塗りを作成するには、コード内のシェイプの描画を開始する場所で、Graphics オブジェクトの beginShaderFill() メソッドを呼び出します。次のリストに示すように、beginShaderFill() メソッドの第 1 引数としてShader オブジェクトを渡します。
var canvas:Sprite = new Sprite();canvas.graphics.beginShaderFill(myShader);canvas.graphics.drawRect(10, 10, 150, 150);
canvas.graphics.endFill();// add canvas to the display list to see the result

シェーダーを描画の塗りとして使用する場合は、シェーダーで必要なすべての入力イメージ値およびパラメーター値を設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

295

Pixel Bender シェーダーの操作

次の例は、シェーダーを描画の塗りとして使用する方法を示します。この例では、シェーダーによって 3 つの点のグラデーションが作成されます。三角形の頂点にグラデーションの 3 色が示され、中間でブレンドされます。さらに、各色が回転し、回転するカラーエフェクトのアニメーションが作成されます。

注意：このコード例は Petri Leskinen 氏が作成したものです。この例の掲載を許可してくれた Petri 氏に感謝いたします。

Petri 氏のその他のサンプルとチュートリアルについて詳しくは、http://pixelero.wordpress.com/ を参照してください。
ActionScript コードには 3 つのメソッドがあります。

• init()：アプリケーションがロードされると、init() メソッドが呼び出されます。このメソッドでは、三角形の頂点を表す
Point オブジェクトの初期値を設定します。また、canvas という名前の Sprite インスタンスも作成します。後から、
updateShaderFill() で、1 フレームに 1 回、シェーダーの結果が canvas に描画されます。最後に、シェーダーのバイト
コードファイルがロードされます。

• onLoadComplete()：onLoadComplete() メソッドで、shader という名前の Shader オブジェクトが作成されます。また、パラメーターの初期値も設定されます。最後に、updateShaderFill() メソッドが enterFrame イベントのリスナーとして追加されるため、アニメーションエフェクトを作成するために 1 フレームに 1 回呼び出されます。

• updateShaderFill()：updateShaderFill() メソッドは 1 フレームに 1 回呼び出され、アニメーションエフェクトを作成します。このメソッドで、シェーダーのパラメーター値が計算され、設定されます。次に、beginShaderFill() メソッドを呼び出してシェーダーの塗りを作成し、別の描画 API メソッドを呼び出してシェーダーの結果を三角形に描画します。
この例の ActionScript コードは次のようになります。Flash Builder の ActionScript のみのプロジェクトでは、このクラスをメインアプリケーションクラスとして使用します。または、Flash Professional の FLA ファイルでは、ドキュメントク
ラスとして使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

296

Pixel Bender シェーダーの操作

package{import flash.display.Shader;import flash.display.Sprite;
import flash.events.Event;import flash.geom.Point;
import flash.net.URLLoader;import flash.net.URLLoaderDataFormat;
import flash.net.URLRequest;
public class ThreePointGradient extends Sprite{
private var canvas:Sprite;
private var shader:Shader;private var loader:URLLoader;private var topMiddle:Point;
private var bottomLeft:Point;
private var bottomRight:Point;
private var colorAngle:Number = 0.0;
private const d120:Number = 120 / 180 * Math.PI; // 120 degrees in radianspublic function ThreePointGradient(){
init();}
private function init():void{canvas = new Sprite();addChild(canvas);
var size:int = 400;
topMiddle = new Point(size / 2, 10);bottomLeft = new Point(0, size - 10);bottomRight = new Point(size, size - 10);loader = new URLLoader();loader.dataFormat = URLLoaderDataFormat.BINARY;
loader.addEventListener(Event.COMPLETE, onLoadComplete);loader.load(new URLRequest("ThreePointGradient.pbj"));}private function onLoadComplete(event:Event):void{
shader = new Shader(loader.data);
shader.data.point1.value = [topMiddle.x, topMiddle.y];shader.data.point2.value = [bottomLeft.x, bottomLeft.y];shader.data.point3.value = [bottomRight.x, bottomRight.y];
addEventListener(Event.ENTER_FRAME, updateShaderFill);}
private function updateShaderFill(event:Event):void{colorAngle += .06;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

297

Pixel Bender シェーダーの操作

var c1:Number = 1 / 3 + 2 / 3 * Math.cos(colorAngle);
var c2:Number = 1 / 3 + 2 / 3 * Math.cos(colorAngle + d120);var c3:Number = 1 / 3 + 2 / 3 * Math.cos(colorAngle - d120);shader.data.color1.value = [c1, c2, c3, 1.0];
shader.data.color2.value = [c3, c1, c2, 1.0];
shader.data.color3.value = [c2, c3, c1, 1.0];
canvas.graphics.clear();canvas.graphics.beginShaderFill(shader);canvas.graphics.moveTo(topMiddle.x, topMiddle.y);canvas.graphics.lineTo(bottomLeft.x, bottomLeft.y);canvas.graphics.lineTo(bottomRight.x, bottomLeft.y);canvas.graphics.endFill();}}}

次の例は、「ThreePointGradient.pbj」という Pixel Bender バイトコードファイルの作成に使用されたThreePointGradient シェーダーカーネルのソースコードです。
<languageVersion : 1.0;>
kernel ThreePointGradient<
namespace : "Petri Leskinen::Example";vendor : "Petri Leskinen";version : 1;
description : "Creates a gradient fill using three specified points and colors.";>{
parameter float2 point1 // coordinates of the first point<
minValue:float2(0, 0);
maxValue:float2(4000, 4000);
defaultValue:float2(0, 0);>;parameter float4 color1 // color at the first point, opaque red by default<
defaultValue:float4(1.0, 0.0, 0.0, 1.0);>;
parameter float2 point2 // coordinates of the second point<
minValue:float2(0, 0);
maxValue:float2(4000, 4000);
defaultValue:float2(0, 500);>;
parameter float4 color2 // color at the second point, opaque green by default<
defaultValue:float4(0.0, 1.0, 0.0, 1.0);>;
parameter float2 point3 // coordinates of the third point<
minValue:float2(0, 0);
maxValue:float2(4000, 4000);
defaultValue:float2(0, 500);>;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

298

Pixel Bender シェーダーの操作

parameter float4 color3 // color at the third point, opaque blue by default<
defaultValue:float4(0.0, 0.0, 1.0, 1.0);>;
output pixel4 dst;
void evaluatePixel(){
float2 d2 = point2 - point1;
float2 d3 = point3 - point1;// transformation to a new coordinate system// transforms point 1 to origin, point2 to (1, 0), and point3 to (0, 1)
float2x2 mtrx = float2x2(d3.y, -d2.y, -d3.x, d2.x) / (d2.x * d3.y - d3.x * d2.y);float2 pNew = mtrx * (outCoord() - point1);// repeat the edge colors on the outside
pNew.xy = clamp(pNew.xy, 0.0, 1.0); // set the range to 0.0 ... 1.0// interpolating the output color or alpha value
dst = mix(mix(color1, color2, pNew.x), color3, pNew.y);}}

注意：グラフィックスプロセッシングユニット（GPU）でのレンダリング時にシェーダーの塗りを使用する場合、塗りつぶされる領域の色はシアンになります。
描画 API を使用したシェイプの描画について詳しくは、212 ページの「描画 API の使用」を参照してください。

ブレンドモードでのシェーダーの使用Flash Player 10 以降、Adobe AIR 1.5 以降
ブレンドモードでのシェーダーの使用は、他のブレンドモードを使用する場合と同じです。シェーダーは、視覚的にブレンドされている 2 つの表示オブジェクトから生成される外観を定義します。シェーダーをブレンドモードで使用するには、前景の表示オブジェクトの blendShader プロパティに Shader オブジェクトを割り当てます。null 以外の値を blendShader プロ
パティに割り当てると、表示オブジェクトの blendMode プロパティが自動的に BlendMode.SHADER に設定されます。次の
例は、シェーダーをブレンドモードで使用する方法を示します。この例では、表示リスト上で他の表示コンテンツと同じ親に含まれている foreground という名前の表示オブジェクトがあり、foreground が他のコンテンツと重なっていることを前提としています。
foreground.blendShader = myShader;

ブレンドモードでシェーダーを使用する場合は、シェーダーに最低 2 つの入力を定義する必要があります。例に示すように、
コードでは入力値を設定しません。その代わり、シェーダーの入力として 2 つのブレンドされたイメージが自動的に使用されています。前景イメージは 2 番目のイメージとして設定されています（これは、ブレンドモードが適用される表示オブジェクトです）。背景イメージは、前景イメージの境界ボックスの後ろのすべてのピクセルを複合して作成されます。この背景イメージは、最初の入力イメージとして設定されています。3 つ以上の入力を使用するシェーダーでは、最初の 2 つ以外の入力値を指定します。
次の例は、シェーダーをブレンドモードで使用する方法を示します。この例では、輝度に基づくより明るいブレンドモード
を使用します。ブレンドの結果、ブレンドされたいずれかのオブジェクトの最も明るいピクセル値が、表示されるピクセルになります。
注意：このコード例は Mario Klingemann 氏が作成したものです。この例の掲載を許可してくれた Mario 氏に感謝いたします。Mario 氏のその他の著述については、www.quasimondo.com/ で読むことができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

299

Pixel Bender シェーダーの操作重要な ActionScript コードは、次の 2 つのメソッドにあります。

• init()：アプリケーションがロードされると、init() メソッドが呼び出されます。このメソッドで、シェーダーのバイト
コードファイルがロードされます。

• onLoadComplete()：onLoadComplete() メソッドで、shader という名前の Shader オブジェクトが作成されます。次に、3つのオブジェクトを描画します。第 1 の backdrop は、ブレンドされたオブジェクトの後ろにある濃い灰色の背景です。
第 2 の backgroundShape は、緑色のグラデーションの楕円です。第 3 のオブジェクト foregroundShape は、オレンジ色のグラデーションの楕円です。

foregroundShape 楕円はブレンドの前景オブジェクトです。ブレンドの背景イメージは、backdrop の部分とbackgroundShape の部分から構成され、foregroundShape オブジェクトの境界ボックスがこれに重なっています。
foregroundShape オブジェクトは、表示リストで最も前面のオブジェクトです。このオブジェクトは、backgroundShapeの一部と backdrop の全体に重なっています。このように重なっているため、ブレンドモードが適用されない場合は、オ
レンジ色の楕円（foregroundShape）の全体が表示され、緑色の楕円（backgroundShape）の一部がこれによって隠されています。

ただし、ブレンドモードを適用すると、foregroundShape の重なった部分よりも明るいために、緑色の楕円のより明るい部分が表示されるようになります。

この例の ActionScript コードは次のようになります。Flash Builder の ActionScript のみのプロジェクトでは、このクラスをメインアプリケーションクラスとして使用します。または、Flash Professional の FLA ファイルでは、ドキュメントク
ラスとして使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

300

Pixel Bender シェーダーの操作

package{import flash.display.BlendMode;
import flash.display.GradientType;import flash.display.Graphics;
import flash.display.Shader;import flash.display.Shape;
import flash.display.Sprite;
import flash.events.Event;import flash.geom.Matrix;
import flash.net.URLLoader;import flash.net.URLLoaderDataFormat;
import flash.net.URLRequest;
public class LumaLighten extends Sprite{
private var shader:Shader;private var loader:URLLoader;public function LumaLighten(){init();}
private function init():void{loader = new URLLoader();loader.dataFormat = URLLoaderDataFormat.BINARY;
loader.addEventListener(Event.COMPLETE, onLoadComplete);loader.load(new URLRequest("LumaLighten.pbj"));}private function onLoadComplete(event:Event):void{
shader = new Shader(loader.data);
var backdrop:Shape = new Shape();var g0:Graphics = backdrop.graphics;
g0.beginFill(0x303030);
g0.drawRect(0, 0, 400, 200);
g0.endFill();
addChild(backdrop);
var backgroundShape:Shape = new Shape();var g1:Graphics = backgroundShape.graphics;
var c1:Array = [0x336600, 0x80ff00];
var a1:Array = [255, 255];
var r1:Array = [100, 255];
var m1:Matrix = new Matrix();
m1.createGradientBox(300, 200);
g1.beginGradientFill(GradientType.LINEAR, c1, a1, r1, m1);
g1.drawEllipse(0, 0, 300, 200);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

301

Pixel Bender シェーダーの操作

g1.endFill();
addChild(backgroundShape);
var foregroundShape:Shape = new Shape();var g2:Graphics = foregroundShape.graphics;
var c2:Array = [0xff8000, 0x663300];
var a2:Array = [255, 255];
var r2:Array = [100, 255];
var m2:Matrix = new Matrix();
m2.createGradientBox(300, 200);
g2.beginGradientFill(GradientType.LINEAR, c2, a2, r2, m2);
g2.drawEllipse(100, 0, 300, 200);
g2.endFill();
addChild(foregroundShape);
foregroundShape.blendShader = shader;
foregroundShape.blendMode = BlendMode.SHADER;
}
}
}

次の例は、
「LumaLighten.pbj」という Pixel Bender バイトコードファイルの作成に使用された LumaLighten シェーダー
カーネルのソースコードです。
<languageVersion : 1.0;>
kernel LumaLighten<
namespace : "com.quasimondo.blendModes";vendor : "Quasimondo.com";version : 1;
description : "Luminance based lighten blend mode";>{
input image4 background;
input image4 foreground;
output pixel4 dst;
const float3 LUMA = float3(0.212671, 0.715160, 0.072169);
void evaluatePixel(){
float4 a = sampleNearest(foreground, outCoord());
float4 b = sampleNearest(background, outCoord());
float luma_a = a.r * LUMA.r + a.g * LUMA.g + a.b * LUMA.b;
float luma_b = b.r * LUMA.r + b.g * LUMA.g + b.b * LUMA.b;
dst = luma_a > luma_b ? a : b;}}

ブレンドモードについて詳しくは、178 ページの「ブレンドモードの適用」を参照してください。
注意：Flash Player または AIR で Pixel Bender シェーダープログラムをブレンドとして実行する場合、サンプリング関数と outCoord() 関数の動作は他のコンテキストと異なります。ブレンドの場合、サンプリング関数は、シェーダーで評価される現在のピクセルを常に返します。例えば、隣接するピクセルをサンプリングするために outCoord() にオフセットを追加することはできません。同様に、サンプリング関数の外で outCoord() 関数を使用すると、その座標は常に 0 に評価されます。
例えば、ピクセルの位置を使用して、ブレンドされたイメージの結合方法を制御することはできません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

302

Pixel Bender シェーダーの操作

フィルターでのシェーダーの使用Flash Player 10 以降、Adobe AIR 1.5 以降
フィルターでのシェーダーの使用は、ActionScript で他のフィルターを使用する場合と同じです。フィルターとしてシェーダーを使用する場合は、フィルターされたイメージ（表示オブジェクトまたは BitmapData オブジェクト）がシェーダーに渡されます。シェーダーは入力イメージを使用してフィルター出力を作成します。これは通常、元のイメージが変更されたイメージです。フィルターされたオブジェクトが表示オブジェクトである場合、シェーダーの出力は、画面上のフィルター
された表示オブジェクトの位置に表示されます。フィルターされたオブジェクトが BitmapData オブジェクトである場合
は、シェーダーの出力が、applyFilter() メソッドが呼び出される BitmapData オブジェクトのコンテンツになります。
フィルターとしてシェーダーを使用するには、まず、287 ページの「シェーダーのロードまたは埋め込み」で説明している
手順で Shader オブジェクトを作成します。次に、Shader オブジェクトにリンクされた ShaderFilter オブジェクトを作成します。ShaderFilter オブジェクトは、フィルターされたオブジェクトに適用されるフィルターです。任意のフィルターを適用する場合と同じように、このフィルターをオブジェクトに適用します。これを表示オブジェクトの filters プロパティに渡すか、または BitmapData オブジェクトの applyFilter() メソッドを呼び出します。例えば、次のコードでは、ShaderFilter
オブジェクトを作成し、homeButton という名前の表示オブジェクトにフィルターを適用します。
var myFilter:ShaderFilter = new ShaderFilter(myShader);homeButton.filters = [myFilter];

フィルターとしてシェーダーを使用する場合は、シェーダーに最低 1 つの入力を定義する必要があります。例に示すように、
コードでは入力値を設定しません。その代わり、フィルターされた表示オブジェクトまたは BitmapData オブジェクトが入力イメージとして設定されています。2 つ以上の入力を使用するシェーダーでは、最初の 1 つ以外の入力値を指定します。
フィルターによって、元のイメージのサイズが変更される場合があります。例えば、一般的なドロップシャドウ効果では、イメージに追加されるシャドウを含んでいるピクセルが追加されます。イメージのサイズを変更するシェーダーを使用する
場合は、イメージサイズをどのくらい変更するかを示す leftExtension、rightExtension、topExtension および bottomExtensionの各プロパティを設定します。
次の例は、フィルターとしてシェーダーを使用する方法を示します。この例では、フィルターによってイメージの赤、緑、青チャンネルの値が反転されます。この結果、イメージの「負」のバージョンが生成されます。
注意：この例で使用しているシェーダーは、Pixel Bender Toolkit に含まれている、invertRGB.pbk という Pixel Bender
カーネルです。Pixel Bender Toolkit インストールディレクトリからカーネルのソースコードをロードできます。ソース
コードをコンパイルし、ソースコードと同じディレクトリにバイトコードファイルを保存します。
重要な ActionScript コードは、次の 2 つのメソッドにあります。

• init()：アプリケーションがロードされると、init() メソッドが呼び出されます。このメソッドで、シェーダーのバイト
コードファイルがロードされます。

• onLoadComplete()：onLoadComplete() メソッドで、shader という名前の Shader オブジェクトが作成されます。次に、
target という名前のオブジェクトが作成され、コンテンツが描画されます。target オブジェクトは、左側が赤、中央が緑、右側が青の線状グラデーションで塗られた矩形です。フィルターされていないオブジェクトは、次のようになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

303

Pixel Bender シェーダーの操作

フィルターの適用により色が反転されて、次のような矩形になります。

この例で使用しているシェーダーは、Pixel Bender Toolkit に含まれている、「invertRGB.pbk」という Pixel Bender カー
ネルのサンプルです。Pixel Bender Toolkit インストールディレクトリの invertRGB.pbk ファイルからソースコードを利用できます。ソースコードをコンパイルし、ActionScript ソースコードと同じディレクトリに、「invertRGB.pbj」という名前でバイトコードファイルを保存します。
この例の ActionScript コードは次のようになります。Flash Builder の ActionScript のみのプロジェクトでは、このクラスをメインアプリケーションクラスとして使用します。または、Flash Professional の FLA ファイルでは、ドキュメントク
ラスとして使用します。
package{import flash.display.GradientType;import flash.display.Graphics;
import flash.display.Shader;import flash.display.Shape;
import flash.display.Sprite;
import flash.filters.ShaderFilter;
import flash.events.Event;import flash.geom.Matrix;
import flash.net.URLLoader;import flash.net.URLLoaderDataFormat;
import flash.net.URLRequest;
public class InvertRGB extends Sprite{
private var shader:Shader;private var loader:URLLoader;public function InvertRGB(){
init();}
private function init():void{loader = new URLLoader();loader.dataFormat = URLLoaderDataFormat.BINARY;
loader.addEventListener(Event.COMPLETE, onLoadComplete);loader.load(new URLRequest("invertRGB.pbj"));}private function onLoadComplete(event:Event):void{

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

304

Pixel Bender シェーダーの操作

shader = new Shader(loader.data);
var target:Shape = new Shape();
addChild(target);var g:Graphics = target.graphics;
var c:Array = [0x990000, 0x445500, 0x007799];
var a:Array = [255, 255, 255];
var r:Array = [0, 127, 255];
var m:Matrix = new Matrix();
m.createGradientBox(w, h);g.beginGradientFill(GradientType.LINEAR, c, a, r, m);g.drawRect(10, 10, w, h);g.endFill();var invertFilter:ShaderFilter = new ShaderFilter(shader);target.filters = [invertFilter];}}}

フィルターの適用について詳しくは、255 ページの「フィルターの作成と適用」を参照してください。

スタンドアローンモードでのシェーダーの使用Flash Player 10 以降、Adobe AIR 1.5 以降
スタンドアローンモードでシェーダーを使用する場合は、出力の用途に依存せずに、シェーダーの処理が実行されます。実行するシェーダーを指定し、入力およびパラメーター値を設定し、結果のデータを配置するオブジェクトを指定します。次の 2 つの場合に、スタンドアローンモードでシェーダーを使用できます。

•

イメージ以外のデータの処理：スタンドアローンモードでは、ビットマップイメージデータではなく、任意のバイナリ
データまたは数値データをシェーダーに渡すように選択できます。シェーダーの結果は、ビットマップイメージデータのほか、バイナリデータまたは数値データとして返されるように選択できます。

•

バックグラウンド処理：スタンドアローンモードでシェーダーを実行する場合、シェーダーはデフォルトで非同期で実行されます。これにより、アプリケーションの実行が続行している間、シェーダーがバックグラウンドで実行され、シェーダーの処理が完了するとコードに通知されます。実行時間の長いシェーダーを使用しても、シェーダーの実行中にアプリ
ケーションのユーザーインターフェイスやその他の処理が一時停止することはありません。

スタンドアローンモードでシェーダーを実行するには、ShaderJob オブジェクトを使用します。まず、ShaderJob オブジェ
クトを作成し、実行するシェーダーを表す Shader オブジェクトにこれをリンクします。
var job:ShaderJob = new ShaderJob(myShader);

次に、シェーダーが使用する入力またはパラメーター値を設定します。バックグラウンドでシェーダーを実行している場合
は、ShaderJob オブジェクトの complete イベントのリスナーも登録します。シェーダーの処理が完了すると、リスナーが呼び出されます。
function completeHandler(event:ShaderEvent):void{// do something with the shader result}
job.addEventListener(ShaderEvent.COMPLETE, completeHandler);

次に、シェーダー処理の完了時に処理結果が書き込まれるオブジェクトを作成します。このオブジェクトを、ShaderJob オ
ブジェクトの target プロパティに割り当てます。
var jobResult:BitmapData = new BitmapData(100, 75);
job.target = jobResult;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

305

Pixel Bender シェーダーの操作

ShaderJob をイメージ処理に使用している場合は、BitmapData インスタンスを target プロパティに割り当てます。バイナ
リまたは数値データの処理を行う場合は、ByteArray オブジェクトまたは Vector.<Number> インスタンスを target プロパ
ティに割り当てます。この場合は、ShaderJob オブジェクトの width および height プロパティを設定して、target オブジェ
クトに出力されるデータの大きさを指定する必要があります。
注意：ShaderJob オブジェクトの shader、target、width および height プロパティを一度に設定するには、ShaderJob() コンス
トラクターに引数を渡します。例えば、次のようになります。var job:ShaderJob = new ShaderJob(myShader, myTarget,

myWidth, myHeight);
シェーダーを実行する準備ができたら、ShaderJob オブジェクトの start() メソッドを呼び出します。
job.start();

デフォルトでは、start() の呼び出しによって、ShaderJob が非同期で実行されます。この場合、プログラムは、シェーダーの完了を待機せずに、直ちに次のコード行を続行します。シェーダー処理が完了すると、ShaderJob オブジェクトは自身のcomplete イベントリスナーを呼び出し、完了を通知します。この時点で（つまり、complete イベントリスナーの本体内）、target オブジェクトにはシェーダー処理の結果が含まれています。
注意：target プロパティオブジェクトを使用するのではなく、リスナーメソッドに渡されたイベントオブジェクトから直接シェーダーの結果を取得できます。イベントオブジェクトは、ShaderEvent インスタンスです。ShaderEvent オブジェク
トには、target プロパティとして設定したオブジェクトのデータ型に応じて、結果にアクセスするために使用できる 3 つのプロパティがあります。これらは、ShaderEvent.bitmapData、ShaderEvent.byteArray、ShaderEvent.vector です。
他の方法として、true 引数を start() メソッドに渡すこともできます。この場合は、シェーダー処理が同期的に実行されます。
すべてのコード（ユーザーインターフェイスやその他のイベントとの対話など）は、シェーダーの実行中に停止します。
シェーダーが完了すると、target オブジェクトにはシェーダーの結果が含まれ、プログラムは次のコード行を続行します。
job.start(true);

最終更新日 2015/10/14

306

第 16 章：ムービークリップの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
MovieClip クラスは、Adobe® Flash® 開発環境で作成されたアニメーションおよびムービークリップのシンボルのコアクラスです。このクラスには、表示オブジェクトの動作と機能がすべて備わっていますが、タイムラインを制御するための追加
プロパティとメソッドもあります。

ムービークリップの基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
ムービークリップとは、Flash オーサリングツールを使用してアニメーションコンテンツを作成したり、そのコンテンツをActionScript で操作するユーザー向けの主要エレメントです。Flash でムービークリップのシンボルを作成すると、そのFlash ドキュメントのライブラリにシンボルが必ず追加されます。デフォルトでは、このシンボルは MovieClip クラスのイ
ンスタンスになり、したがって、MovieClip クラスのプロパティとメソッドを持ちます。
ムービークリップシンボルのインスタンスがステージ上に配置されると、1 フレーム以上ある場合、ムービークリップは自動的にタイムライン上を進みます。ただし、ActionScript を使用して再生が変更される場合を除きます。MovieClip クラスを識別するのは、このタイムラインです。MovieClip クラスを使用すると、Flash オーサリングツールを使用して、モーショントゥイーンやシェイプトゥイーンによるアニメーションの作成が可能になります。一方、Sprite クラスのインスタン
スである表示オブジェクトでアニメーションを作成するには、オブジェクトの値をプログラムによって変更する方法しかありません。
以前のバージョンの ActionScript では、MovieClip クラスはステージ上のすべてのインスタンスの基本クラスとして機能していました。ActionScript 3.0 では、ムービークリップは画面に表示可能な多くの表示オブジェクトの 1 つにすぎません。
表示オブジェクトの関数でタイムラインが必要でない場合、MovieClip クラスの代わりに Shape クラスまたは Sprite クラスを使用すると、レンダリングパフォーマンスが向上する可能性があります。タスクに適した表示オブジェクトの選択方法について詳しくは、164 ページの「DisplayObject サブクラスの選択」を参照してください。
重要な概念と用語
次の参照リストに、ムービークリップに関連した重要な用語を示します。

AVM1 SWF ActionScript 1.0 または ActionScript 2.0 によって作成される SWF ファイルです。通常は、Flash Player 8
以前を対象としています。

AVM2 SWF Flash Player 9 以降または Adobe AIR 用に ActionScript 3.0 によって作成される SWF ファイルです。
外部 SWF プロジェクト SWF ファイルとは別に作成される SWF ファイルです。プロジェクト SWF ファイルにロードされ、その SWF ファイル内で再生されます。
フレーム タイムライン上の時間の最小分割単位です。映画スライドと同じように、各フレームはアニメーションのスナップ
ショットのようなものであり、フレームをすばやく連続して再生すると、アニメーションの効果を得ることができます。
タイムライン ムービークリップのアニメーションシーケンスを形成する一連のフレームを、比喩的に表現したものです。

MovieClip オブジェクトのタイムラインは、Flash オーサリングツールのタイムラインと同じです。
再生ヘッド タイムライン上の現在時点（フレーム）を示すマーカーです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

307

ムービークリップの操作

MovieClip オブジェクトの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルをパブリッシュすると、Flash はステージ上のすべてのムービークリップシンボルインスタンスをMovieClip オブジェクトに変換します。プロパティインスペクターの「インスタンス名」フィールドにムービークリップシ
ンボルのインスタンス名を入力すると、ActionScript でそのシンボルを使用できるようになります。SWF ファイルが作成されると、Flash はステージ上に MovieClip インスタンスを作成するコードを生成し、インスタンス名を使用して変数を宣言します。他の名前を持つムービークリップの中にネストされたムービークリップに名前を付けると、その子ムービーク
リップは親ムービークリップのプロパティとして扱われます。子ムービークリップにアクセスするには、ドットシンタック
スを使用します。例えば、インスタンス名が childClip のムービークリップが、インスタンス名が parentClip のムービーク
リップ内にネストされている場合、このコードを呼び出すことによって子クリップのタイムラインのアニメーションを再生できます。
parentClip.childClip.play();

注意：：Flash オーサリングツールのステージに配置された子インスタンスは、親インスタンスのコンストラクター内からコードでアクセスできません。コード実行の該当時点では作成されていないからです。子にアクセスするには、親はコードを使用して子インスタンスを作成するか、子を待機するコールバック関数が Event.ADDED_TO_STAGE イベントを送出するまでアクセスを遅延させる必要があります。

ActionScript 2.0 の MovieClip クラスの古いメソッドおよびプロパティには、変更されているものと、変更されていないものがあります。アンダースコアで始まるプロパティの名前はすべて変更されています。例えば、_width プロパティと _height
プロパティは width と height として、_xscale プロパティと _yscale プロパティは scaleX と scaleY としてアクセスするようになりました。MovieClip クラスのプロパティとメソッドの詳細なリストについては、『Adobe Flash Platform 用

ActionScript 3.0 リファレンスガイド』を参照してください。

ムービークリップの再生の制御
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash では、タイムラインのメタファーを使用して、アニメーションまたは状態の変化を伝達します。タイムラインを使用するビジュアルエレメントは、MovieClip オブジェクトか、または MovieClip クラスの拡張である必要があります。
ActionScript ではムービークリップの停止、再生、またはタイムラインの別のポイントへの移動を指示できますが、ActionScript を使用してタイムラインを動的に作成したり、特定のフレームにコンテンツを追加したりすることはできません。これには、Flash オーサリングツールを使用する必要があります。
MovieClip の再生は、SWF のフレームレートで指定された速度でタイムラインに沿って行われます。また、ActionScript
で Stage.frameRate プロパティを設定すると、この設定をオーバーライドできます。

ムービークリップの再生と再生の停止
Flash Player 9 以降、Adobe AIR 1.0 以降
play() メソッドおよび stop() メソッドを使用すると、タイムライン内でムービークリップの基本的な制御を行うことができます。例えば、画面上を走る自転車のアニメーションが組み込まれたステージ上にムービークリップシンボルがあり、そのインスタンス名が bicycle に設定されているとします。メインタイムラインのキーフレームに次のコードが関連付けられている場合、
bicycle.stop();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

308

ムービークリップの操作

自転車は動きません。つまり、アニメーションは再生されません。自転車の動きは、他のユーザー操作によって開始できます。例えば、startButton という名前のボタンがある場合、ボタンをクリックするとアニメーションが再生されるように、次のようなメインタイムライン上のキーフレームのコードが実行されます。
// This function will be called when the button is clicked. It causes the// bicycle animation to play.
function playAnimation(event:MouseEvent):void{
bicycle.play();}// Register the function as a listener with the button.
startButton.addEventListener(MouseEvent.CLICK, playAnimation);

早送りと巻き戻しFlash Player 9 以降、Adobe AIR 1.0 以降
ムービークリップで再生を制御する方法は、play() メソッドと stop() メソッドだけではありません。nextFrame() メソッドおよび prevFrame() メソッドを使用して、再生ヘッドをタイムラインに沿って手動で前後に動かすこともできます。これらのメソッドのいずれかを呼び出すと、再生が停止して、再生ヘッドが前方または後方に 1 フレームずつ動きます。

play() メソッドを使用することは、ムービークリップオブジェクトの enterFrame イベントがトリガーされるたびにnextFrame() を呼び出すのに似ています。次の例では、enterFrame イベントにイベントリスナーを作成して bicycle をリスナー関数の前のフレームに戻すことによって、bicycle のムービークリップを逆方向に動かすことができます。
// This function is called when the enterFrame event is triggered, meaning// it's called once per frame.
function everyFrame(event:Event):void{if (bicycle.currentFrame == 1){
bicycle.gotoAndStop(bicycle.totalFrames);}else{
bicycle.prevFrame();}}bicycle.addEventListener(Event.ENTER_FRAME, everyFrame);

ムービークリップに複数のフレームが含まれている場合、ムービークリップの再生は無限に繰り返されます。つまり、最後のフレームの再生が終わると最初のフレームに戻ります。prevFrame() または nextFrame() を使用する場合、この動作は自動的には行われません。つまり、再生ヘッドが最初のフレーム上にあるときに prevFrame() を呼び出しても、再生ヘッドは最後のフレームに移動しません。上記の例の if 条件では、逆方向の再生ヘッドが最初のフレームまで到達したかどうかを確認し、最初のフレームに到達した場合に再生ヘッドを最終フレームに設定することによって、ムービークリップの逆方向連続再生を実現しています。

異なるフレームへのジャンプとフレームラベルの使用Flash Player 9 以降、Adobe AIR 1.0 以降
ムービークリップを新しいフレームに進めるのは簡単です。gotoAndPlay() または gotoAndStop() を呼び出すと、ムービーク
リップはパラメーターで指定されたフレーム番号までジャンプします。あるいは、フレームラベルの名前と同じ文字列を渡すこともできます。タイムライン上の任意のフレームに、ラベルを割り当てることができます。ラベルを設定するには、タイ
ムライン上のフレームを選択して、プロパティインスペクターの フレーム「ラベル」フィールドに名前を入力します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

309

ムービークリップの操作

複雑なムービークリップを作成する場合を考えると、番号の代わりにフレームラベルを使用する利点は明らかです。アニメーションのフレーム、レイヤー、およびトゥイーンの数が大きくなる場合は、重要なフレームにムービークリップの動作を表す説明として「オフ」、「ウォーキング」、または「ランニング」などのラベルを付けるようにしてください。ラベル付きフレームに移動する ActionScript 呼び出しは、指定のフレーム番号ではなく単一の参照、つまりラベルに対するポインターであるため、読みやすさと柔軟性が向上します。アニメーションの特定のセグメントを、後から別のフレームに移動する場
合でも、移動先のフレームに対して同じラベルを使用する限りは、ActionScript コードを変更する必要はありません。
コードのフレームラベルを表示するため、ActionScript 3.0 には FrameLabel クラスがあります。このクラスの各インスタンスは単一のフレームラベルを表し、プロパティインスペクターで示されるフレームラベル名を表す name プロパティと、
タイムライン上でラベルが配置されているフレームの番号を表す frame プロパティがあります。
ムービークリップインスタンスに関連付けられている FrameLabel インスタンスへのアクセスを可能にするため、MovieClip クラスには FrameLabel オブジェクトを直接返すプロパティが 2 つあります。currentLabels プロパティは、ムー
ビークリップのタイムライン全体のすべての FrameLabel オブジェクトで構成される配列を返します。currentLabel プロパ
ティは、タイムラインで最後に到達したフレームラベルの名前を文字列で返します。
ロボット（robot） という名前のムービークリップを作成し、そのアニメーションの様々な状態にラベルを付ける場合を考えます。次のコードでは、currentLabel プロパティをチェックする条件を設定して、ロボットの現在の状態を確認しています。
if (robot.currentLabel == "walking"){// do something}

Flash Player 11.3 および AIR 3.3 では、FrameLabel クラスに frameLabel イベントが追加されています。フレームラベルを表す FrameLabel インスタンスにイベントハンドラーを割り当てることができます。このイベントは、再生ヘッドがフレー
ムに入ると送出されます。
次の例では、MovieClip のフレームラベルの Array に、2 番目のフレームラベルの FrameLabel インスタンスを作成します。次に、frameLabel イベントのイベントハンドラーを登録します。
var myFrameLabel:FrameLabel = robot.currentLabels[1];myFrameLabel.addEventListener(Event.FRAME_LABEL, onFrameLabel);function onFrameLabel(e:Event):void {//do something}

シーンの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash のオーサリング環境では、シーンを使用して SWF ファイルで再生される一連のタイムラインを区切ることができます。gotoAndPlay() メソッドまたは gotoAndStop() メソッドの 2 番目のパラメーターを使用して、再生ヘッドを送るシーンを指定できます。FLA ファイルはすべて最初のシーンから開始されますが、新しいシーンを作成することもできます。
シーンにはいくつかの短所があるため、シーンの使用が必ずしも最適であるとは限りません。複数のシーンを含む Flash ド
キュメントで、特に作成者が複数存在する場合には、管理が困難になる可能性があります。パブリッシュする際には 1 つのタイムラインにすべてのシーンがマージされるため、複数のシーンを使用すると、帯域幅の利用効率が悪くなる可能性もあります。再生されないシーンがある場合でも、すべてのシーンのプログレッシブダウンロードが行われます。このような理由から、複数の長いタイムラインベースアニメーションを整理するのに必要な場合を除いて、複数のシーンを使用することは推奨されません。

MovieClip クラスの scenes プロパティは、SWF ファイルのすべてのシーンを示す Scene オブジェクトの配列を返します。
currentScene プロパティは Scene オブジェクトを返します。このオブジェクトは、再生中のシーンを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

310

ムービークリップの操作

Scene クラスには、シーンに関する情報を示すプロパティがいくつかあります。labels プロパティは、シーン内のフレームラ
ベルを示す FrameLabel オブジェクトの配列を返します。name プロパティは、シーンの名前を文字列で返します。
numFrames プロパティは、シーンのフレーム総数を示す整数を返します。

ActionScript での MovieClip オブジェクトの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
ライブラリからステージ上にアセットをドラッグすると、Flash の画面にコンテンツを追加できますが、方法はこれだけではありません。複雑なプロジェクトの場合、一般的に、経験豊富な開発者はプログラムを使ってムービークリップを作成しようと考えます。この方法は、コードの再利用が容易でコンパイル時間を短縮できます。また、ActionScript のみで利用可
能な高度な修正も可能になります。

ActionScript 3.0 の表示リスト API は、MovieClip オブジェクトを動的に作成することによって、プロセスを効率化します。表示リストに追加するプロセスとは別に、MovieClip インスタンスを直接インスタンス化できるので、コントロールを犠牲にせずに柔軟性と簡便性がもたらされます。

ActionScript 3.0 では、ムービークリップまたはその他の表示オブジェクトのインスタンスをプログラムによって作成すると、それが表示リストに追加されるまでは画面上には表示されません。追加するには、表示オブジェクトコンテナで

addChild() メソッドまたは addChildAt() メソッドを呼び出します。このため、ムービークリップが画面にレンダリングされる前にムービークリップを作成し、プロパティを設定し、メソッドを呼び出すことが可能です。表示リストの操作方法について詳しくは、151 ページの「表示オブジェクトコンテナの操作」を参照してください。

ActionScript に対するライブラリシンボルの書き出しFlash Player 9 以降、Adobe AIR 1.0 以降
デフォルトでは、Flash ドキュメントのライブラリのムービークリップシンボルのインスタンスは、動的に作成することはできません。つまり、ActionScript を使用してのみ作成可能です。これは、ActionScript で使用する目的で書き出されるシンボルはすべて SWF ファイルに追加されますが、シンボルの中にはステージで使用されないものもあるからです。このような理由から、ActionScript でシンボルを使用可能にするには、シンボルを ActionScript に書き出すよう指定する必要があります。

ActionScript 用にシンボルを書き出すには :1 ライブラリパネルでシンボルを選択し、シンボルプロパティダイアログボックスを開きます。
2 必要であれば、詳細設定を開きます。
3 「リンケージ」セクションで、「AcrionScript に書き出し」チェックボックスを選択します。
この操作を行うと「クラス」フィールドと「基本クラス」フィールドがアクティブ化されます。
デフォルトでは、「クラス」フィールドにはスペースを消去したシンボル名が表示されます。例えば、「Tree House」というシンボル名は、「TreeHouse」となります。シンボルの動作でカスタムクラスを使用するよう指定するには、パッケージも含むクラスのフルネームをこのフィールドに入力します。ActionScript にシンボルのインスタンスを作成できるようにしたいが、動作を追加する必要がない場合は、クラス名をそのまま残しておくことができます。
「基本クラス」フィールドのデフォルト値は flash.display.MovieClip です。シンボルによって他のカスタムクラスの機能を拡張する場合、そのクラスが Sprite または MovieClip クラスを拡張できれば、代わりにそのクラスの名前を指定することができます。

4 「OK」ボタンをクリックして変更内容を保存します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

311

ムービークリップの操作

この段階で、シンボルに対して動作を追加する必要がなかった場合など、リンクされた SWC ファイルまたは指定クラスの定義を含んでいる外部 ActionScript ファイルが見つからなかった場合は、次の警告が表示されます。
クラスパスにこのクラスの定義が見つからなかったため、書き出す際に SWF ファイル内にクラスを自動生成します。
ライブラリシンボルで MovieClip クラスの機能以外の独自の機能が必要ない場合は、この警告を無視できます。
シンボルに対してクラスを提供しなければ、Flash はシンボルに対し、次のようなクラスを作成します。
package{import flash.display.MovieClip;
public class ExampleMovieClip extends MovieClip{
public function ExampleMovieClip(){}}}

シンボルに対して ActionScript 機能を追加する場合は、この構造に適切なプロパティとメソッドを追加します。例えば、
幅 50 ピクセル、高さ 50 ピクセルの円を含むムービークリップシンボルがあり、そのシンボルは、クラス名 Circle として
ActionScript に書き出されるよう設定されているとします。以下のコードを Circle.as ファイルに配置すると、MovieClip
クラスが拡張されて、シンボルに getArea() メソッドと getCircumference() メソッドが追加で提供されます。
package{import flash.display.MovieClip;
public class Circle extends MovieClip{
public function Circle(){}
public function getArea():Number{// The formula is Pi times the radius squared.
return Math.PI * Math.pow((width / 2), 2);}public function getCircumference():Number{// The formula is Pi times the diameter.
return Math.PI * width;}}}Flash ドキュメントの最初のフレームのキーフレームに配置される次のコードにより、シンボルのインスタンスが作成され、それが画面に表示されます。
var c:Circle = new Circle();addChild(c);trace(c.width);
trace(c.height);
trace(c.getArea());
trace(c.getCircumference());

次のコードでは、個々のアセットをステージ上にドラッグする代わりに、ActionScript ベースのインスタンス化を行っています。作成される円には、ムービークリップのすべてのプロパティと Circle クラスに定義した独自のメソッドが含まれます。
これは非常に基本的な例です。ライブラリシンボルは、クラス内でプロパティとメソッドをいくつでも指定できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

312

ムービークリップの操作

手作業で用意するのが困難な大量のインスタンスを動的に作成できるため、ActionScript ベースのインスタンス化は非常に有効です。また、作成時に各インスタンスのプロパティをカスタマイズできるので、柔軟性にも優れています。ループを使用して複数の Circle インスタンスを動的に作成すると、これらの利点を理解できます。Circle シンボルとクラスは Flash ド
キュメントのライブラリであらかじめ記述されているので、次のコードを最初のフレームのキーフレーム上に配置します。
import flash.geom.ColorTransform;var totalCircles:uint = 10;
var i:uint;for (i = 0; i < totalCircles; i++){// Create a new Circle instance.
var c:Circle = new Circle();// Place the new Circle at an x coordinate that will space the circles// evenly across the Stage.
c.x = (stage.stageWidth / totalCircles) * i;// Place the Circle instance at the vertical center of the Stage.
c.y = stage.stageHeight / 2;// Change the Circle instance to a random colorc.transform.colorTransform = getRandomColor();// Add the Circle instance to the current timeline.
addChild(c);}function getRandomColor():ColorTransform{// Generate random values for the red, green, and blue color channels.
var red:Number = (Math.random() * 512) - 255;
var green:Number = (Math.random() * 512) - 255;
var blue:Number = (Math.random() * 512) - 255;// Create and return a ColorTransform object with the random colors.
return new ColorTransform(1, 1, 1, 1, red, green, blue, 0);}

ここでは、コードを使用してシンボルの複数インスタンスをすばやく作成し、カスタマイズする方法を示します。各インス
タンスはループ内で現在のカウントに基づいて配置され、さらに transform プロパティを設定することにより、ランダムなカラーが各インスタンスに付けられます。このプロパティは、MovieClip クラスを拡張することによって Circle が継承します。

外部の SWF ファイルのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、Loader クラスを使用して SWF ファイルをロードします。外部 SWF ファイルをロードするには、
ActionScript で次の 4 つのタスクを実行する必要があります。
1 ファイルの url により、新規 URLRequest オブジェクトを作成します。
2 新規 Loader オブジェクトを作成します。
3 URLRequest インスタンスをパラメーターとして渡し、Loader オブジェクトの load() メソッドを呼び出します。
4 Flash ドキュメントのメインタイムラインなどの表示オブジェクトコンテナで addChild() メソッドを呼び出し、表示リス
トに Loader インスタンスを追加します。
最終的に、コードは次のようになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

313

ムービークリップの操作

var request:URLRequest = new URLRequest("http://www.[yourdomain].com/externalSwf.swf");
var loader:Loader = new Loader()loader.load(request);
addChild(loader);

これと同じコードを使用して、JPEG、GIF、PNG イメージなどの外部イメージファイルをロードできます。その際、SWF ファイルの url ではなく、イメージファイルの url を指定します。イメージファイルとは異なり、SWF ファイルにはActionScript を含めることができます。このため、SWF ファイルをロードするプロセスがイメージのロードと同じでも、Flash Player または AIR で SWF ファイルを再生しており、ActionScript を使用して外部の SWF ファイルと何らかの通信を行う場合は、外部の SWF ファイルをロードするときに、ロードする SWF ファイルとロードされる SWF ファイルの両方が同じセキュリティサンドボックスに属している必要があります。また、ロードされる SWF ファイル内のクラスと同じ名
前空間を使用するクラスが外部の SWF ファイルに含まれる場合には、名前空間の競合を避けるために、ロードされる SWF
ファイル用に新しいアプリケーションドメインを作成する必要があります。セキュリティとアプリケーションドメインの考慮事項について詳しくは、140 ページの「アプリケーションドメインの操作」および 1022 ページの「コンテンツのロード」
を参照してください。
正常にロードされた外部の SWF ファイルには、Loader.content プロパティを使用してアクセスできます。外部の SWF ファ
イルを ActionScript 3.0 用としてパブリッシュすると、拡張するクラスに基づいて、ムービークリップまたはスプライトのいずれかになります。

Adobe AIR for iOS と、その他のプラットフォームでは、SWF ファイルのロード方法に少々違いがあります。詳しくは、
192 ページの「AIR for iOS での SWF ファイルのロード」を参照してください。

従来の SWF ファイルをロードする際の注意事項
Flash Player 9 以降、Adobe AIR 1.0 以降
以前のバージョンの ActionScript を使用して外部 SWF ファイルをパブリッシュする場合には、制約事項に注意する必要があります。AVM2（ActionScript Virtual Machine 2）で実行される ActionScript 3.0 の SWF ファイルと異なり、ActionScript 1.0 または 2.0 用としてパブリッシュされる SWF ファイルは AVM1（ActionScript Virtual Machine 1）で実行されます。

ActionScript 1.0 または 2.0 の SWF ファイルを ActionScript 3.0 の SWF ファイルにロードする場合には、（ActionScript
3.0 の SWF ファイルをロードする場合と比較して）重要な違いがあります。Flash Player には、以前にパブリッシュされたコンテンツとの完全な後方互換性があります。旧バージョンの Flash Player で実行できるすべてのコンテンツは、ActionScript 3.0 をサポートするバージョンの Flash Player でも実行できます。ただし、次の制約があります。

• ActionScript 3.0 のコードでは、ActionScript 1.0 または 2.0 で記述された SWF ファイルをロードできます。
ActionScript 1.0 または 2.0 の SWF ファイルが正常にロードされると、ロードされたオブジェクト（Loader.content プロパティ）は、AVM1Movie オブジェクトになります。AVM1Movie インスタンスは、MovieClip インスタンスと同じではありません。これは表示オブジェクトで、ムービークリップとは異なり、タイムラインに関連するメソッドまたはプ
ロパティを含んでいません。親 AVM2 SWF ファイルは、ロードされた AVM1Movie オブジェクトのプロパティ、メ
ソッドまたはオブジェクトにアクセスできません。

• ActionScript 1.0 または 2.0 で記述された SWF ファイルは、ActionScript 3.0 で記述された SWF ファイルをロードすることはできません。つまり、Flash 8 または Flex Builder 1.5 以前のバージョンで作成された SWF ファイルは、ActionScript 3.0 で記述された SWF ファイルをロードできません。
この規則には唯一例外があり、以前に ActionScript 2.0 SWF ファイルによってどのレベルにも何もロードされていなけ
れば、ActionScript 2.0 SWF ファイル自体を ActionScript 3.0 SWF ファイルで置き換えることができます。

ActionScript 2.0 SWF ファイルは、loadMovieNum() の呼び出しによってこの置き換えを行い、値 0 を level パラメー
ターに渡します。

•

一般に、ActionScript 1.0 または 2.0 で記述された SWF ファイルは、ActionScript 3.0 で記述された SWF ファイルと共に使用するには移行する必要があります。例えば、ActionScript 2.0 を使用してメディアプレーヤーを作成したとしま

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

314

ムービークリップの操作す。このメディアプレーヤーでは、ActionScript 2.0 を使用して作成された様々なコンテンツをロードできますが、ActionScript 3.0 で新しいコンテンツを作成して、このメディアプレーヤーにロードすることはできません。メディアプ
レーヤーを ActionScript 3.0 に移行する必要があります。
ただし、ActionScript 3.0 でメディアプレーヤーを作成すれば、ActionScript 2.0 で作成されたコンテンツを簡単にロードできます。
次の表に、新しいコンテンツのロードおよびコードの実行に対する旧バージョンの Flash Player の制限について概要を示します。また、異なるバージョンの ActionScript で記述された SWF ファイル間のクロススクリプトの制限についても概要を示します。
サポートされる機能

Flash Player 7

Flash Player 8

Flash Player 9 および 10

ロード可能な SWF のパブリッシュ対象

7 以前

8 以前

9（または 10）以前

含まれている AVM

AVM1

AVM1

AVM1 および AVM2

実行可能な SWF の記述に使用されるActionScript

1.0 および 2.0

1.0 および 2.0

1.0、2.0、および 3.0

次の表の「サポートされる機能」は Flash Player 9 以降で実行するコンテンツを指します。Flash Player 8 以前で実行する
コンテンツは、ActionScript 1.0 および 2.0 のみロード、表示、実行、クロススクリプトが可能です。
サポートされる機能

ActionScript 1.0 および 2.0 で作成されたコン ActionScript 3.0 で作成されたコンテンツ
テンツ

ロードしてコードを実行できるコンテンツの作
成元
クロススクリプト可能なコンテンツの作成元

ActionScript 1.0 および 2.0 のみ

ActionScript 1.0、2.0、および ActionScript
3.0

ActionScript 1.0 および 2.0 のみ（ローカル接

ローカル接続を使用する ActionScript 1.0 およ続を使用する ActionScript 3.0）

び 2.0

ActionScript 3.0

ムービークリップの例：RuntimeAssetsExplorer
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript に書き出す機能は、特にライブラリに有効で、複数のプロジェクトで役立つ場合があります。Flash Player ま
たは AIR で SWF ファイルを実行する場合、ActionScript に書き出されたシンボルは、SWF ファイルをロードする同じセキュリティサンドボックス内のすべての SWF ファイルで使用できます。このようにすると、単一の Flash ドキュメントでグラフィカルアセット保持専用の SWF ファイルを生成できます。この方法は特に、大規模なプロジェクトで、ビジュアルア
セットを担当する複数のデザイナーが「ラッパー」SWF ファイルを作成する複数の開発者と平行して作業を行い、実行時にグラフィカルアセットの SWF ファイルをロードする場合に役立ちます。この方法を使用すると、一連のバージョン化されたファイルの管理が可能です。この場合、グラフィカルアセットはプログラミング開発の進捗に依存しません。

RuntimeAssetsExplorer アプリケーションは RuntimeAsset のサブクラスであるすべての SWF ファイルをロードします。
このため、SWF ファイルの利用可能なアセットを参照できます。この例では、次の内容について説明します。

• Loader.load() を使用した外部 SWF ファイルのロード• ActionScript に書き出されるライブラリシンボルの動的な作成• MovieClip 再生の ActionScript による制御操作を開始する前に、各 SWF ファイルを同じセキュリティサンドボックスに置く必要があることに注意してください。詳
しくは、1006 ページの「セキュリティサンドボックス」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

315

ムービークリップの操作

このサンプルのアプリケーションのファイルを入手するには、Flash Professional のサンプルをダウンロードしてください。

RuntimeAssetsExplorer アプリケーションのファイルは、Samples/Chapters/RuntimeAssetsExplorer フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

RuntimeAssetsExample.mxml

アプリケーションのユーザーインターフェイスです（Flex 用の MXML、または Flash 用の FLA）。

またはRuntimeAssetsExample.fla
Flash アプリケーション（FLA）のドキュメントクラス

RuntimeAssetsExample.asです。

RuntimeAsset インターフェイスを実装するサンプルク

GeometricAssets.as

ラスです。

ActionScript 用に書き出されるシンボルを含んでいる
GeometricAssets クラス（FLA のドキュメントクラス）にリンクされている FLA ファイル。

GeometricAssets.fla

com/example/programmingas3/runtimeassetexplorer/RuntimeLibrary.a エクスプローラーコンテナにロードされるすべてのラン
タイムアセット SWF ファイルに必要なメソッドを定義
s
するインターフェイスです。

com/example/programmingas3/runtimeassetexplorer/AnimatingBox.as

回転するボックス形のライブラリシンボルのクラスです。

com/example/programmingas3/runtimeassetexplorer/AnimatingStar.as 回転する星形のライブラリシンボルのクラスです。

ランタイムライブラリインターフェイスの確立
Flash Player 9 以降、Adobe AIR 1.0 以降
エクスプローラーで正しく SWF ライブラリを操作できるようにするには、ランタイムアセットライブラリの構造を形式化する必要があります。構造を形式化するには、インタフェースを作成します。これはメソッドの設計図であり、目的の構造を定義するという点ではクラスに似ていますが、メソッド本体は提供しない点がクラスとは異なります。インターフェイス
を使用すると、ランタイムライブラリとエクスプローラーが相互にやり取りできます。ブラウザーにロードされるランタイ
ムアセットの SWF はそれぞれ、このインターフェイスを実装します。インターフェイスとその利便性について詳しくは、『ActionScript 3.0 の学習』のインターフェイスに関する内容を参照してください。

RuntimeLibrary インターフェイスは非常にシンプルです。必要なのは、書き出されるシンボルのクラスパスの配列をエク
スプローラーに提供でき、ランタイムライブラリで使用可能な関数だけです。このため、インタフェースには getAssets() というメソッドだけを含めます。
package com.example.programmingas3.runtimeassetexplorer{
public interface RuntimeLibrary{function getAssets():Array;}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

316

ムービークリップの操作

アセットライブラリ SWF ファイルの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
RuntimeLibrary インタフェースを定義すると、別の SWF ファイルにロード可能な複数のアセットライブラリ SWF ファ
イルを作成できます。個々の SWF アセットライブラリを作成する際には、次の 4 つのタスクを実行します。

•

アセットライブラリ SWF ファイルのクラスを作成する•

ライブラリを含む各アセットのクラスを作成する•

実際のグラフィックアセットを作成する•

グラフィックエレメントにクラスを関連付けて、ライブラリ SWF をパブリッシュする

RuntimeLibrary インターフェイスを実装するクラスの作成
次に、RuntimeLibrary インタフェースを実装する GeometricAssets クラスを作成します。これは、FLA のドキュメント
クラスになります。このクラスのコードは RuntimeLibrary インタフェースによく似ています。両者の違いは、クラス定義
で getAssets() メソッドにはメソッド本体がある点です。
package{import flash.display.Sprite;
import com.example.programmingas3.runtimeassetexplorer.RuntimeLibrary;public class GeometricAssets extends Sprite implements RuntimeLibrary{
public function GeometricAssets() {}public function getAssets():Array {return [ "com.example.programmingas3.runtimeassetexplorer.AnimatingBox","com.example.programmingas3.runtimeassetexplorer.AnimatingStar" ];}}}2 番目のランタイムライブラリを作成する場合は、独自の getAssets() を実装する AnimationAssets などの別のクラスをベースにした別の FLA を作成できます。
各 MovieClip アセット用クラスの作成
この例では、カスタムアセットに機能を追加することなく、MovieClip クラスの拡張のみを行います。次のAnimatingStar のコードは、AnimatingBox のコードと類似しています。
package com.example.programmingas3.runtimeassetexplorer{
import flash.display.MovieClip;
public class AnimatingStar extends MovieClip{
public function AnimatingStar() {}}}ライブラリのパブリッシュ
次に、新しい FLA を作成し、プロパティインスペクターの「ドキュメントクラス」フィールドに GeometricAssets を入力
して、MovieClip ベースのアセットと新しいクラスを接続します。この例では、タイムライントゥイーンを使用して、360
フレームを時計回りに 1 回転する 2 つの基本シェイプを作成しています。animatingBox および animatingStar のシンボルはい

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

317

ムービークリップの操作

ずれも「ActionScript に書き出し」に設定され、「クラス」フィールドは getAssets() の実装で指定されたそれぞれのクラス
パスに設定されます。標準の MovieClip メソッドをサブクラスにする必要があるので、デフォルトのベースクラスである
flash.display.MovieClip は変更されません。
シンボルの書き出し設定を指定したら、FLA をパブリッシュします。これで、最初のランタイムライブラリが設定されます。この SWF は別の AVM2 SWF ファイルにロードできます。また、AnimatingBox および AnimatingStar のシンボル
は新しい SWF ファイルでも使用できます。

別の SWF ファイルへのライブラリのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
必要な最後の機能は、アセットエクスプローラーのユーザーインターフェイスです。この例では、ランタイムライブラリのパスは、ASSETS_PATH という名前の変数としてハードコードされています。また、FileReference クラスを使用して、ハードドライブ上の特定の SWF ファイルを参照するインターフェイスの作成などを行うこともできます。
ランタイムライブラリが正常にロードされると、runtimeAssetsLoadComplete() メソッドが呼び出されます。
private function runtimeAssetsLoadComplete(event:Event):void{
var rl:* = event.target.content;
var assetList:Array = rl.getAssets();
populateDropdown(assetList);
stage.frameRate = 60;}

このメソッドでは、rl 変数はロードされた SWF ファイルを示します。このコードでは、ロードされた SWF ファイルのgetAssets() メソッドを呼び出して、使用可能なアセットのリストを取得しています。その後、populateDropDown() メソッドを呼び出し、使用可能なアセットのリストを使用して ComboBox コンポーネントを指定しています。このメソッドに各アセットの完全なクラスパスが保存されます。ユーザーインタフェースの「追加」ボタンをクリックすると、addAsset() メソッ
ドがトリガーされます。
private function addAsset():void{
var className:String = assetNameCbo.selectedItem.data;
var AssetClass:Class = getDefinitionByName(className) as Class;var mc:MovieClip = new AssetClass();...
}

これにより、現在 ComboBox で選択しているアセットのクラスパスが取得され（assetNameCbo.selectedItem.data）、

flash.utils パッケージから getDefinitionByName() 関数を使用して、アセットのクラスに対する実際の参照が入手され、そのアセットの新規インスタンスが作成されます。

最終更新日 2015/10/14

318

第 17 章：モーショントゥイーンの操作
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）184 ページの「オブジェクトのアニメーション化」では、ActionScript においてスクリプトで記述されたアニメーションを実装する方法が説明されています。
ここでは、アニメーションを作成するもう 1 つの技法であるモーショントゥイーンについて説明します。この方法では、

Adobe® Flash® Professional を使用してドキュメントで対話的にモーションを設定することで動きを作成します。その後
は、実行時に ActionScript ベースのダイナミックなアニメーションで、そのモーションを使用できます。

Flash Professional は、モーショントゥイーンを実装する ActionScript を自動的に生成し、コピーや再利用に使用できるよ
うにします。
モーショントゥイーンを作成するには、Flash Professional のライセンスが必要です。
関連項目

fl.motion パッケージ

モーショントゥイーンの基礎
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）
モーショントゥイーンを使用すると、アニメーションを簡単に作成できます。
モーショントゥイーンは、表示オブジェクトの位置や回転などのプロパティを、フレームごとに変更します。また、様々なフィルターや他のプロパティを適用することで、表示オブジェクトを動かしながらその外観を変えることもできます。モーショントゥイーンの作成は、Flash Professional と対話しながら行います。結果として、モーショントゥイーンのActionScript が生成されます。Flash 内からは、モーショントゥイーンを作成した ActionScript をコピーするには、「ActionScript 3.0 としてのモーションのコピー」コマンドを使用します。その後は、実行時に、ActionScript を再利用して、独自のダイナミック アニメーション内の動きを作成できます。
モーショントゥイーンの作成については、『Flash Professional ユーザーガイド』で「モーショントゥイーン」の節を参照
してください。
重要な概念と用語次に、この機能に関連した重要な用語を示します。
モーショントゥイーン 異なるときに異なる状態で表示オブジェクトの中間フレームを生成する構造。ある状態が別の状態へと滑らかに変化する外観を作り出します。表示オブジェクトをステージ上で動かすために使用します。また、時間とともに表示オブジェクトを拡大、縮小、回転、フェードさせたり、オブジェクトの色を変えたりすることもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

319

モーショントゥイーンの操作

Flash でのモーショントゥイーンスクリプトのコピー
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）トゥイーンは、タイムライン上の 2 つの異なるフレームの間に、異なる状態の表示オブジェクトを表示する中間フレームを生成します。最初のフレームのイメージが 2 番目のフレームのイメージへと滑らかに変化する視覚的効果を作り出します。
モーショントゥイーンでは、通常、外観の変化には表示オブジェクトの位置の変化が伴うので、動きが生み出されます。表示オブジェクトの位置の変更だけでなく、モーショントゥイーンは、表示オブジェクトの回転、傾斜、サイズ変更を行った
り、表示オブジェクトにフィルターを適用したりすることもできます。

Flash を使用し、タイムライン上のキーフレーム間で表示オブジェクトを動かすことにより、モーショントゥイーンを作成します。Flash は、トゥイーンを記述する ActionScript コードを自動的に生成します。このコードをコピーしてファイルに保存できます。モーショントゥイーンの作成については、『Flash Professional ユーザーガイド』で「モーショントゥイー
ン」の節を参照してください。

Flash で「ActionScript 3.0 としてのモーションのコピー」コマンドにアクセスするには、2 つの方法があります。第 1 の方法は、ステージのトゥイーンコンテキストメニューからです。

1 ステージでモーショントゥイーンを選択します。
2 右クリック（Windows の場合）するか、または Control キーを押しながらクリック（Macintosh の場合）します。
3 「AS 3.0 にモーションを書き出してコピー」を選択します。

もう 1 つの方法は、Flash の編集メニューからコマンドを直接選択します。

1 ステージでモーショントゥイーンを選択します。
2 編集／タイムライン／ AS 3.0 にモーションを書き出してコピーを選択します。

スクリプトをコピーした後、ファイルに貼り付けて保存します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

320

モーショントゥイーンの操作

モーショントゥイーンを作成し、スクリプトをコピーして保存した後は、それをそのまま再利用することも、独自のActionScript ベースのダイナミック アニメーションで変更することもできます。

モーショントゥイーンスクリプトの組み込みFlash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）Flash からコピーした ActionScript コードのヘッダーには、モーショントゥイーンをサポートするために必要なすべてのモジュールが列記されています。

モーショントゥイーンクラス
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）
必ず必要なモーショントゥイーンクラスは、fl.motion パッケージの AnimatorFactory、MotionBase および Motion クラ
スです。モーショントゥイーンが操作するプロパティによっては、これ以外のクラスも必要になります。例えば、モーショ
ントゥイーンが表示オブジェクトを変換または回転する場合は、適切な flash.geom クラスをインポートします。フィルターを適用する場合は、flash.filter クラスをインポートします。ActionScript では、モーショントゥイーンは Motion クラスのインスタンスです。Motion クラスは、ビジュアルオブジェクトに適用できるキーフレームアニメーションのシーケンスを格納します。アニメーションデータには、位置、拡大／縮小、回転、傾斜、カラー、フィルター、イージングなどが含まれます。
次の ActionScript は、Symbol1_2 というインスタンス名の表示オブジェクトをアニメーション化するために Flash で作成されたモーショントゥイーンからコピーしたものです。MotionBase オブジェクトの __motion_Symbol1_2 という名前の変数を宣言します。MotionBase クラスは Motion クラスの親です。
var __motion_Symbol1_2:MotionBase;

次に、スクリプトは Motion オブジェクトを作成します。
__motion_Symbol1_2 = new Motion();Motion オブジェクトの名前
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）前の例では、Motion オブジェクトの名前 __motion_Symbol1_2 は、Flash が自動的に生成したものです。表示オブジェクト
名に接頭辞 __motion_ が追加されています。このように、自動的に生成される名前は、Flash でのモーショントゥイーンのターゲットオブジェクトのインスタンス名が基になっています。Motion オブジェクトの duration プロパティは、モーショ
ントゥイーンの総フレーム数を示します。
__motion_Symbol1_2.duration = 200;

デフォルトでは、同じ名前のインスタンスが存在していない限り、Flash はコピーされたモーショントゥイーンの表示オブジェクトのインスタンスの名前を自動的に設定します。

Flash によって作成された ActionScript を独自のアニメーションで再利用する場合は、トゥイーンに対して Flash で自動的に生成された名前を保持するか、または別の名前を付けることができます。トゥイーンの名前を変更する場合は、スクリプ
ト全体を漏れなく変更するように注意してください。
または、Flash で、モーショントゥイーンのターゲットオブジェクトに適当な名前を選んで割り当てることもできます。その後で、モーショントゥイーンを作成し、スクリプトをコピーします。どちらの命名方法を使用する場合でも、ActionScript コード内の各 Motion オブジェクトが一意の名前を持つようにする必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

321

モーショントゥイーンの操作

アニメーションの作成
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）MotionBase クラスの addPropertyArray() メソッドは、トゥイーン化されるすべてのプロパティを記述する値の配列を追加します。
この配列は、モーショントゥイーンのすべてのキーフレームに対して 1 つずつ配列項目を含む可能性があります。ただし、通常は、モーショントゥイーンのキーフレームの総数より、配列に含まれる項目の数の方が少なくなります。このような状況が発生するのは、配列内の最後の値が、残りのフレームで変化しない場合です。
配列引数の長さが、Motion オブジェクトの duration プロパティより長い場合、addPropertyArray() は duration プロパティの値を引数の長さに従って調節します。以前に追加されたプロパティにキーフレームを追加することはありません。新しく追加されるキーフレームは、アニメーションの余分なフレームとして存続します。

Motion オブジェクトの x プロパティと y プロパティは、トゥイーン化されたオブジェクトのアニメーション実行中の位置の変化を記述します。表示オブジェクトの位置が変化する場合、すべてのキーフレームで変化する可能性が最も高いのはこれらの座標の値です。addPropertyArray() メソッドを使用すると、さらにモーションプロパティを追加できます。例えば、トゥイーン化されたオブジェクトのサイズを変える場合は、scaleX と scaleY の値を追加します。傾斜させる場合は、scewXと skewY の値を追加します。回転させる場合は、rotationConcat プロパティを追加します。
以下のトゥイーンプロパティを定義するには、addPropertyArray() メソッドを使用します。
x

親の座標空間での、オブジェクトの変形点の水平位置y

親の座標空間での、オブジェクトの変形点の垂直位置z

親の座標空間での、オブジェクトの変形点の深度（z 軸）位置

scaleX

変形点から適用されるオブジェクトの水平方向の拡大／縮小率（パーセンテージ）

scaleY

変形点から適用されるオブジェクトの垂直方向の拡大／縮小率（パーセンテージ）

skewX

変形点から適用されるオブジェクトの水平方向の傾斜角度

skewY

変形点から適用されるオブジェクトの垂直方向の傾斜角度

rotationX

x 軸に対する、オブジェクトの元の方向からの回転

rotationY

y 軸に対する、オブジェクトの元の方向からの回転

rotationConcat

変形点から適用される、以前の方向に対する相対的な動作での、オブジェクトの回転（z 軸）の値

useRotationConcat

設定した場合、addPropertyArray() によって動作のデータが提供されると、ターゲットオブジェクトは回転しますblendMode

オブジェクトの色と下にあるグラフィックの混合を指定する BlendMode クラスの値

matrix3D

キーフレームに指定されている場合は、その matrix3D プロパティ。3D トゥイーンに使用されます。使用されると、それまでのすべての変形プロパティは無視されます

rotationZ

3D 親コンテナを基準とする、元の方向からのオブジェクトの z 軸の回転（度）。3D トゥイーンで rotationConcat の代わりに使用されます

自動生成されるスクリプトで追加されるプロパティは、Flash でモーショントゥイーンに割り当てられたプロパティによって決まります。独自バージョンのスクリプトをカスタマイズするときは、これらのプロパティを追加、削除、または変更できます。
次に示すコードは、__motion_Wheel という名前のモーショントゥイーンのプロパティに値を割り当てます。この例では、トゥイーン化された表示オブジェクトの位置は変わりませんが、モーショントゥイーンの 29 フレームの間、同じ位置で回転します。rotationConcat 配列に割り当てられた複数の値が、回転を定義しています。このモーショントゥイーンの他のプロ
パティ値は変化しません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

322

モーショントゥイーンの操作__motion_Wheel = new Motion();__motion_Wheel.duration = 29;__motion_Wheel.addPropertyArray("x", [0]);__motion_Wheel.addPropertyArray("y", [0]);__motion_Wheel.addPropertyArray("scaleX", [1.00]);__motion_Wheel.addPropertyArray("scaleY", [1.00]);__motion_Wheel.addPropertyArray("skewX", [0]);__motion_Wheel.addPropertyArray("skewY", [0]);__motion_Wheel.addPropertyArray("rotationConcat",[
0,-13.2143,-26.4285,-39.6428,-52.8571,-66.0714,-79.2857,-92.4999,-105.714,-118.929,-132.143,-145.357,-158.571,-171.786,-185,-198.214,-211.429,-224.643,-237.857,-251.071,-264.286,-277.5,-290.714,-303.929,-317.143,-330.357,-343.571,-356.786,-370]);__motion_Wheel.addPropertyArray("blendMode", ["normal"]);次に示す例では、Leaf_1 という名前の表示オブジェクトが、ステージを横切って移動します。x プロパティと y プロパティの配列に、アニメーションの 100 フレームのそれぞれに対する値が含まれています。さらに、ステージ上を移動しながら、オ
ブジェクトは z 軸を中心に回転します。rotationZ プロパティ配列の複数の項目が、回転を決定します。
__motion_Leaf_1 = new MotionBase();__motion_Leaf_1.duration = 100;__motion_Symbol1_4.addPropertyArray("y",[0,5.91999,11.84,17.76,23.68,29.6,35.52,41.44,47.36,53.28,59.2,65.12,71.04,
76.96,82.88,88.8,94.72,100.64,106.56,112.48,118.4,124.32,130.24,136.16,142.08,
148,150.455,152.909,155.364,157.818,160.273,162.727,165.182,167.636,170.091,
172.545,175,177.455,179.909,182.364,184.818,187.273,189.727,192.182,194.636,
197.091,199.545,202,207.433,212.865,218.298,223.73,229.163,234.596,240.028,
245.461,250.893,256.326,261.759,267.191,272.624,278.057,283.489,
288.922,294.354,299.787,305.22,310.652,316.085,321.517,326.95,330.475,334,
337.525,341.05,344.575,348.1,351.625,355.15,358.675,362.2,365.725,369.25,
372.775,376.3,379.825,383.35,386.875,390.4,393.925,397.45,400.975,404.5,
407.5,410.5,413.5,416.5,419.5,422.5,425.5]);__motion_Symbol1_4.addPropertyArray("scaleX", [1.00]);__motion_Symbol1_4.addPropertyArray("scaleY", [1.00]);__motion_Symbol1_4.addPropertyArray("skewX", [0]);__motion_Symbol1_4.addPropertyArray("skewY", [0]);__motion_Symbol1_4.addPropertyArray("z",[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

323

モーショントゥイーンの操作__motion_Symbol1_4.addPropertyArray("rotationX", [64.0361]);__motion_Symbol1_4.addPropertyArray("rotationY", [41.9578]);__motion_Symbol1_4.addPropertyArray("rotationZ",[-18.0336,-17.5536,-17.0736,-16.5936,-16.1136,-15.6336,-15.1536,-14.6736,-14.1936,-13.7136,-13.2336,-12.7536,-12.2736,-11.7936,-11.3136,-10.8336,-10.3536,-9.8736,-9.3936,-8.9136,-8.4336,-7.9536,-7.4736,-6.9936,-6.5136,-6.0336,-7.21542,-8.39723,-9.57905,-10.7609,-11.9427,-13.1245,-14.3063,-15.4881,-16.67,-17.8518,-19.0336,-20.2154,-21.3972,-22.5791,-23.7609,-24.9427,-26.1245,-27.3063,-28.4881,-29.67,-30.8518,-32.0336,-31.0771,-30.1206,-29.164,-28.2075,-27.251,-26.2945,-25.338,-24.3814,-23.4249,-22.4684,-21.5119,-20.5553,-19.5988,-18.6423,-17.6858,-16.7293,-15.7727-14.8162,-13.8597,-12.9032,-11.9466,-10.9901,-10.0336,-10.9427,-11.8518,-12.7609,-13.67,-14.5791,-15.4881,-16.3972,-17.3063,-18.2154,-19.1245,-20.0336,-20.9427,-21.8518,-22.7609,-23.67,-24.5791,-25.4881,-26.3972,-27.3063,-28.2154,-29.1245,-30.0336,-28.3193,-26.605,-24.8907,-23.1765,-21.4622,-19.7479,-18.0336]);__motion_Symbol1_4.addPropertyArray("blendMode", ["normal"]);フィルターの追加
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）
モーショントゥイーンのターゲットオブジェクトがフィルターを含む場合、フィルターは Motion クラスの initFilters() メ
ソッドおよび addFilterPropertyArray() メソッドを使用して追加します。

フィルター配列の初期化
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）
initFilters() メソッドはフィルターを初期化します。1 番目の引数は、表示オブジェクトに適用するすべてのフィルターの完
全修飾クラス名の配列です。このフィルター名の配列は、Flash でモーショントゥイーンに対するフィルターのリストから生成されます。スクリプトのコピーでは、この配列の flash.filters パッケージで、フィルターを削除または追加できます。次に示す呼び出しは、ターゲット表示オブジェクトのフィルターリストを初期化します。DropShadowFilter、GlowFilter、BevelFilter を適用し、リストを Motion オブジェクトの各キーフレームにコピーします。
__motion_Box.initFilters(["flash.filters.DropShadowFilter", "flash.filters.GlowFilter","flash.filters.BevelFilter"], [0, 0, 0]);フィルターの追加
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）
addFilterPropertyArray() メソッドは、次の引数を使用して初期化済みフィルターのプロパティを記述します。

1 1 番目の引数は、インデックスでフィルターを指定します。インデックスは、その前の initFilters() の呼び出しで渡されたフィルタークラス名配列でのフィルター名の位置を示します。

2 2 番目の引数は、各キーフレームでそのフィルターに格納するフィルタープロパティです。
3 3 番目の引数は、指定したフィルタープロパティの値です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

324

モーショントゥイーンの操作

前に示した initFilters() の呼び出しに対し、次の addFilterPropertyArray() の呼び出しでは、DropShadowFilter の blurX プロパティと blurY プロパティに値 5 が割り当てられます。DropShadowFilter は、初期化済みフィルター配列の最初の（インデックス 0）の項目です。
__motion_Box.addFilterPropertyArray(0, "blurX", [5]);__motion_Box.addFilterPropertyArray(0, "blurY", [5]);次の 3 つの呼び出しは、初期化済みフィルター配列の 2 番目（インデックス 1）の項目である GlowFilter の quality、alpha、

color プロパティに値を割り当てます。
__motion_Box.addFilterPropertyArray(1, "quality", [BitmapFilterQuality.LOW]);__motion_Box.addFilterPropertyArray(1, "alpha", [1.00]);__motion_Box.addFilterPropertyArray(1, "color", [0xff0000]);

次の 4 つの呼び出しは、初期化済みフィルター配列の 3 番目（インデックス 2）の項目である BevelFilter の shadowAlpha、

shadowColor、highlightAlpha、highlightColor に値を割り当てます。
__motion_Box.addFilterPropertyArray(2, "shadowAlpha", [1.00]);__motion_Box.addFilterPropertyArray(2, "shadowColor", [0x000000]);__motion_Box.addFilterPropertyArray(2, "highlightAlpha", [1.00]);__motion_Box.addFilterPropertyArray(2, "highlightColor", [0xffffff]);

ColorMatrixFilter での色の調節
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）ColorMatrixFilter を初期化した後は、適切な AdjustColor プロパティを設定して、トゥイーン化された表示オブジェクトの明度、コントラスト、彩度、色相を調節できます。通常は、Flash でモーショントゥイーンが作成されるときに AdjustColor
フィルターが適用されます。このフィルターは、ActionScript のコピーで微調整できます。次の例では、移動中の表示オブジェクトの色相と彩度を変更しています。
__motion_Leaf_1.initFilters(["flash.filters.ColorMatrix"], [0], -1, -1);__motion_Leaf_1.addFilterPropertyArray(0, "adjustColorBrightness", [0], -1, -1);__motion_Leaf_1.addFilterPropertyArray(0, "adjustColorContrast", [0], -1, -1);__motion_Leaf_1.addFilterPropertyArray(0, "adjustColorSaturation",[
0,-0.589039,1.17808,-1.76712,-2.35616,-2.9452,-3.53424,-4.12328,-4.71232,-5.30136,-5.89041, 6.47945,-7.06849,-7.65753,-8.24657,-8.83561,-9.42465,-10.0137,-10.6027,-11.1918,11.7808,-12.3699,-12.9589,-13.5479,-14.137,-14.726,-15.3151,-15.9041,-16.4931,
17.0822,-17.6712,-18.2603,-18.8493,-19.4383,-20.0274,-20.6164,-21.2055,-21.7945,22.3836,-22.9726,-23.5616,-24.1507,-24.7397,-25.3288,-25.9178,-26.5068,-27.0959,27.6849,-28.274,-28.863,-29.452,-30.0411,-30.6301,-31.2192,-31.8082,-32.3973,32.9863,-33.5753,-34.1644,-34.7534,-35.3425,-35.9315,-36.5205,-37.1096,-37.6986,
38.2877,-38.8767,-39.4657,-40.0548,-40.6438,-41.2329,-41.8219,-42.411,-43],-1, -1);__motion_Leaf_1.addFilterPropertyArray(0, "adjustColorHue",[
0,0.677418,1.35484,2.03226,2.70967,3.38709,4.06451,4.74193,5.41935,
6.09677,6.77419,7.45161,8.12903,8.80645,9.48387,10.1613,10.8387,11.5161,
12.1935,12.871,13.5484,14.2258,14.9032,15.5806,16.2581,16.9355,17.6129,
18.2903,18.9677,19.6452,20.3226,21,22.4286,23.8571,25.2857,26.7143,28.1429,
29.5714,31,32.4286,33.8571,35.2857,36.7143,38.1429,39.5714,41,42.4286,43.8571,
45.2857,46.7143,48.1429,49.5714,51,54,57,60,63,66,69,72,75,78,81,84,87,
90,93,96,99,102,105,108,111,114],-1, -1);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

325

モーショントゥイーンの操作

表示オブジェクトへのモーショントゥイーンの関連付け
Flash Player 9 以降、Adobe AIR 1.0 以降、Flash CS3 以降（必須）
最後のタスクは、モーショントゥイーンと、それが操作する表示オブジェクトを関連付けることです。

AnimatorFactory クラスは、モーショントゥイーンとそのターゲット表示オブジェクトの間の関連付けを管理します。
AnimatorFactory のコンストラクターには、引数として Motion オブジェクトを渡します。
var __animFactory_Wheel:AnimatorFactory = new AnimatorFactory(__motion_Wheel);

AnimatorFactory クラスの addTarget() メソッドを使用して、ターゲット表示オブジェクトとモーショントゥイーンを関連付けます。Flash からコピーした ActionScript では、addTarget() の行はコメントになっており、インスタンス名は指定されません。
// __animFactory_Wheel.addTarget(<instance name goes here>, 0);

コピーでは、モーショントゥイーンと関連付ける表示オブジェクトを指定します。次の例では、ターゲットとしてgreenWheel および redWheel を指定しています。
__animFactory_Wheel.AnimatorFactory.addTarget(greenWheel, 0);__animFactory_Wheel.AnimationFactory.addTarget(redWheel, 0);

addTarget() を複数回呼び出して、同じモーショントゥイーンに複数の表示オブジェクトを関連付けることができます。

最終更新日 2015/10/14

326

第 18 章：インバースキネマティックの操作
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）
逆運動学（IK）は現実的な動きを作成する優れたテクニックです。

IK を使用すると、IK のアーマチュアと呼ばれる接続された部分の連鎖内で協調された運動を作成することによって、その部分全体を生きているように動かすことができます。アーマチュアの部分は、骨と関節です。アーマチュアの端点を前提として、IK では端点に到達するために必要な関節の角度を計算します。
そのような角度の計算をユーザーが手計算で行うことは困難です。この機能の優れた点は、Adobe® Flash® Professional を使用してインタラクティブにアーマチュアを作成できるということです。そして、ActionScript を使用してアーマチュアをアニメーション化します。Flash Professional に含まれる IK エンジンは、アーマチュアの動きを記述する計算を実行します。この動きを ActionScript コードの特定のパラメーターに制限できます。

Flash Professional CS5 バージョンの IK でボーンスプリングの概念が新しく導入されています。ボーンスプリングは、通常、ハイエンドのアニメーションアプリケーションで使用されます。この機能は、新しい動的な物理演算エンジンと共に使用され、自然な動作を設定できます。また、この機能は実行時およびオーサリング時の両方で表示できます。
逆運動学アーマチュアを作成するには、Flash Professional のライセンスを所有している必要があります。
関連項目

fl.ik パッケージ

インバースキネマティックの基礎
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）
逆運動学（IK）では、部分をリンクさせて実際のように相互に連携して動かすことによって、生き生きとしたアニメーショ
ンを作成できます。
例えば、IK を使用すると、目的のポーズを取るために必要な脚の関節の動きを関連付けることによって、特定の位置に脚を動かすことができます。IK は IK アーマチュアという構造内の全体が連鎖している骨格を使用します。fl.ik パッケージを使用
すると、自然な動きに似たアニメーションを作成することができます。このパッケージでは、IK アルゴリズムの背景の動きについての詳細を理解する必要なく、複数の IK アーマチュアをシームレスにアニメーション化することができます。

Flash Professional では、付随するボーンとジョイントを含む IK アーマチュアを作成します。次に、IK クラスにアクセス
して実行時にそれらのアーマチュアをアニメーション化します。

IK アーマチュアの作成方法について詳しくは、『Flash Professional ユーザーガイド』の「インバースキネマティックの使用」の節を参照してください。
重要な概念と用語
次の参照リストに、この機能に関連した重要な用語を示します。
アーマチュア 現実的な動きをシミュレートするためにコンピューターアニメーションで使用されるボーン、ジョイントで構成される運動連鎖。
ボーン アーマチュアの硬いセグメント。動物の骨格の骨に相当します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

327

インバースキネマティックの操作

インバースキネマティック（IK）運動連鎖またはアーマチュアと呼ばれるジョイントのある柔軟なオブジェクトのパラメー
ターを特定するプロセス。
ジョイント 2 つのボーンが接する場所。ボーンの動きを可能にするように組み立てられており、動物の関節に相当します。
物理演算エンジン 物理演算に関するアルゴリズムのパッケージ。アニメーションで自然な動作を表現するのに使用します。
スプリング 親ボーンの動きに反応して動き、時間の経過とともに徐々に減衰するボーンの性質。

IK のアーマチュアのアニメーション化の概要
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）Flash Professional で IK のアーマチュアを作成したら、fl.ik クラスを使用して、動きを制限し、イベントを追跡し、実行時にアニメーション化します。
次の図に、Wheel という名前のムービークリップを示します。車軸は、Axle という名前の IKArmature のインスタンスです。IKMover クラスは車輪の回転と同期してアーマチュアを動かします。アーマチュアの IKBone、ikBone2 が後ろ側の継ぎ目にある車輪に接続されます。
A

B

C

A. 車輪 B. 車軸 C. ikBone2

実行時には、__motion_Wheel モーショントゥイーンに従って車輪が回転します。このモーショントゥイーンについては、

321 ページの「アニメーションの作成」で解説しています。IKMover オブジェクトは車軸の動きを開始し、制御します。
次の図に、回転の異なるフレームで回転している車輪に連結されている車軸アーマチュアの 2 つのスナップショットを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

328

インバースキネマティックの操作実行時は、次の ActionScript では以下を実行します。

•

アーマチュアとそのコンポーネントに関する情報の取得• IKMover オブジェクトのインスタンス化•

車輪の回転と連携して車軸を動かす

import fl.ik.*
var tree:IKArmature = IKManager.getArmatureByName("Axle");var bone:IKBone = tree.getBoneByName("ikBone2");var endEffector:IKJoint = bone.tailJoint;
var pos:Point = endEffector.position;
var ik:IKMover = new IKMover(endEffector, pos);ik.limitByDistance = true;ik.distanceLimit = 0.1;
ik.limitByIteration = true;ik.iterationLimit = 10;
Wheel.addEventListener(Event.ENTER_FRAME, frameFunc);function frameFunc(event:Event){if (Wheel != null){var mat:Matrix = Wheel.transform.matrix;
var pt = new Point(90, 0);pt = mat.transformPoint(pt);ik.moveTo(pt);}}

車軸を動かすために使用される IK クラスは次のとおりです。

• IK のアーマチュア：アーマチュア、つまり、骨と関節で構成されるツリー構造を記述する。Flash Professional で作成されている必要があります。

• IKManager：ドキュメント内のすべての IK アーマチュアのコンテナクラス。Flash Professional で作成されている必要があります。

• IKBone：IK アーマチュアのセグメント。
• IKJoint：2 つの IK の骨を接続する部分。
• IKMover：アーマチュアの IK の動きを開始し、制御する。
これらのクラスについて詳しくは、ik パッケージを参照しください。

IK のアーマチュアの詳細Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）
まず、動かしたい部分を構成するアーマチュア、骨、および関節の変数を宣言します。
次のコードでは、IKManager のクラスの getArmatureByName() メソッドを使用して、IKArmature 変数 tree に Axle アー
マチュアの値を割り当てます。この Axle アーマチュアは、事前に Flash Professional を使用して作成したものです。
var tree:IKArmature = IKManager.getArmatureByName("Axle");最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

329

インバースキネマティックの操作

同様に、次のコードでは、IKArmature クラスの getBoneByName() メソッドを使用して、IKBone 変数を ikBone2 骨の値に割り当てます。
var bone:IKBone = tree.getBoneByName("ikBone2");

ikBone2 骨の後ろ側の継ぎ目は、回転している車輪に接続されているアーマチュアの部分です。
次の行では、変数 endEffector を宣言し、この変数を ikBone2 骨の tailjoint プロパティに割り当てます。
var endEffector:IKJoint = home.tailjoint;

変数 pos は、endEffector 関節の現在の位置を格納するポイントです。
var pos:Point = endEffector.position;

この例で、pos は車輪に接続している車軸の末端にある関節の位置です。この変数の元の値は、IKJoint の position プロパ
ティから取得されます。

IK Mover のインスタンス化とその動きの制限
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）
IKMover クラスのインスタンスは車軸を動かします。
次の行では、IKMover オブジェクト ik をインスタンス化し、動かすエレメントおよび動きの開始点をコンストラクターに渡します。
var ik:IKMover = new IKMover(endEffector, pos);

IKMover クラスのプロパティを使用すると、アーマチュアの動きを制限できます。距離、反復、動きの回数を基に動きを制限することができます。
プロパティの次のペアにより、これらの制限が実行されます。このペアは、動きが制限されているかどうかを示す Boolean
値と、その制限を指定する整数の組み合わせです。
Boolean プロパティ

整数プロパティ

設定される制限

limitByDistance:Boolean

distanceLimit:int

IK エンジンが反復ごとに動くピクセルの最大距離を設定します。

limitByIteration:Boolean

iterationLimit:int

IK エンジンの 1 回の移動での最大繰り返し回数を設定します。

limitByTime:Boolean

timeLimit:int

動きを実行するために IK エンジンに割り当てられる最大の時間をミリ秒単位で設定します。

デフォルトでは、すべての Boolean 値が false に設定されているため、明示的に Boolean 値を true に設定しない限り、動きは制限されません。制限を適用するには、適切なプロパティを true に設定した後、対応する整数プロパティに値を指定します。対応する Boolean プロパティを設定せずに、制限の値を設定しても、その制限は無視されます。この場合、IK エンジ
ンは、IKMover の別の制限または目的の位置に到達するまで引き続きオブジェクトを動かします。
次の例では、アーマチュアの動きの最大距離は、反復ごとに 0.1 ピクセルに設定されています。すべての動きの反復の最大数は 10 に設定されます。
ik.limitByDistance = true;ik.distanceLimit = 0.1;
ik.limitByIteration = true;ik.iterationLimit = 10;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

330

インバースキネマティックの操作

IK のアーマチュアの移動
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）
IKMover は車輪のイベントリスナの内側に車軸を動かします。車輪の各 enterFrame イベントでは、アーマチュアの新しいターゲット位置が計算されます。その moveTo() メソッドを使用して、IKMover は後ろ側の継ぎ目を目的位置まで動かす
か、limitByDistance、limitByIteration、limitByTime プロパティで設定した制約内で到達可能な位置まで動かします。
Wheel.addEventListener(Event.ENTER_FRAME, frameFunc);function frameFunc(event:Event){if (Wheel != null){var mat:Matrix = Wheel.transform.matrix;
var pt = new Point(90,0);pt = mat.transformPoint(pt);ik.moveTo(pt);}}スプリングの使用
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS5 以降（必須）Flash Professional CS5 のインバースキネマティックでは、ボーンスプリングがサポートされています。どちらのスプリン
グともオーサリング時に設定可能で、ボーンスプリング属性は実行時に追加または変更できます。スプリングはボーンおよ
びそのジョイントのプロパティです。スプリングには 2 つの属性があります。1 つは IKJoint.springStrength 属性で、スプリングの強さを設定します。もう 1 つは IKJoint.springDamping 属性で、強さの値に抵抗を追加してスプリングの減衰率を変更します。
スプリングの強さは、デフォルトの 0（完璧な硬さ）から 100（非常にゆるく、物理演算で制御されます）までのパーセン
ト値を設定します。スプリングが設定されたボーンは、ボーン自体のジョイントの動きに反応します。他の移動（回転、x軸または y 軸方向）が有効化されていない場合は、スプリングを設定しても効果はありません。
スプリングの減衰は、デフォルトの 0（抵抗なし）から 100（減衰最大）までのパーセント値を設定します。減衰によって、ボーンの最初の動作から静止位置に戻るまでの時間が変化します。

IKArmature オブジェクトでスプリングが有効になっているかどうかを調べるには、IKArmature.springsEnabled プロパティ
を確認します。スプリングに関するその他のプロパティおよびメソッドは、個々の IKJoint オブジェクトに属します。ジョ
イントは、角度回転と x 軸および y 軸方向の移動に対して有効化できます。回転ジョイントのスプリング角度を設定するには IKJoint.setSpringAngle を使用し、移動ジョイントのスプリング位置は IKJoint.setSpringPt で設定できます。
この例では、名前でボーンを選択し、その tailJoint を識別します。コードでは、親アーマチュアをテストしてスプリングが有効になっているかどうかを確認してから、ジョイントのスプリングプロパティを設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

331

インバースキネマティックの操作

var arm:IKArmature = IKManager.getArmatureAt(0);var bone:IKBone = arm.getBoneByName("c");var joint:IKJoint = bone.tailJoint;
if (arm.springsEnabled) {joint.springStrength = 50; //medium spring strength
joint.springDamping = 10; //light damping resistanceif (joint.hasSpringAngle) {joint.setSpringAngle(30); //set angle for rotational spring}}

IK イベントの使用
Flash Player 10 以降、Adobe AIR 1.5 以降、Flash CS4 以降（必須）
IKEvent クラスでは、IK イベントの関する情報を含むイベントオブジェクトを作成することができます。IKEvent 情報は、
指定時間、距離または反復の制限を超えたために終了した動きを記述します。
次のコードは、時間制限イベントを追跡するためのイベントリスナーおよびハンドラーを示します。このイベントハンド
ラーは、IKMover の時間制限を超えたときに起動されるイベントの時間、距離、反復回数および関節の各プロパティについてレポートします。
var ikmover:IKMover = new IKMover(endjoint, pos);
ikMover.limitByTime = true;
ikMover.timeLimit = 1000;
ikmover.addEventListener(IKEvent.TIME_LIMIT, timeLimitFunction);function timeLimitFunction(evt:IKEvent):void{
trace("timeLimit hit");
trace("time is " + evt.time);
trace("distance is " + evt.distance);
trace("iterationCount is " + evt.iterationCount);
trace("IKJoint is " + evt.joint.name);}

最終更新日 2015/10/14

332

第 19 章：3 次元（3D）での操作
Flash Player 10 以降、Adobe AIR 1.5 以降
Flash Player と AIR のランタイムでは、3D グラフィックが 2 種類の方法でサポートされています。Flash の表示リストでは、3 次元表示オブジェクトを使用できます。これは、Flash のコンテンツやポリゴン数の少ないオブジェクトに 3 次元の効果を追加するのに適しています。Flash Player 11 および AIR 3 以降では、Stage3D API を使用して複雑な 3D シーンをレンダリングできます。

Stage3D のビューポートは、表示オブジェクトではありません。3D グラフィックは、Flash 表示リストの下（StageVideo
ビューポート面の上）に表示されるビューポートにレンダリングされます。Flash DisplayObject クラスを使用してシーンを作成するのではなく、プログラム可能な 3D パイプライン（OpenGL や Direct3D に類似のもの）を使用します。このパイプラインは、三角形のデータとテクスチャを入力とし、与えられたシェーダープログラムを使用してシーンをレンダリン
グします。ハードウェアアクセラレーションに対応した GPU およびサポートされているドライバーをクライアントコン
ピューターが備えている場合は、ハードウェアアクセラレーションが使用されます。

Stage3D が提供しているのは、非常に低レベルの API です。アプリケーションでは、Stage3D をサポートしている 3D フ
レームワークを使用することをお勧めします。独自のフレームワークを作成することも、既に入手可能な商用およびオープ
ンソースのフレームワークのいずれかを使用することもできます。

Stage3D を使用した 3D アプリケーションの開発、および入手可能な 3D フレームワークについて詳しくは、Flash Player
Developer Center: Stage 3D を参照してください。

3D 表示オブジェクトの基礎
Flash Player 10 以降、Adobe AIR 1.5 以降
2 次元の画面に投影される 2 次元（2D）オブジェクトと 3 次元（3D）オブジェクトの主な違いは、オブジェクトに第 3 の次元が追加されることです。3 次元では、オブジェクトをユーザーの視点に近付けたり視点から離したりすることができます。
表示オブジェクトの z プロパティを明示的に数値に設定すると、オブジェクトによって 3D 変換マトリックスが自動的に作成されます。このマトリックスを変更して、そのオブジェクトの 3D 変換設定を変更することができます。
また、3D の回転は 2D の回転と異なります。2D では、回転の軸が常に x/y 平面に対して垂直になります。つまり z 軸で回転されます。3D では、回転の軸は x、y、z 軸のいずれにでもすることができます。表示オブジェクトの回転および拡大／
縮小プロパティを設定すると、そのオブジェクトを 3D 空間で移動できるようになります。
重要な概念と用語
次の参照リストに、3 次元グラフィックのプログラミングで使われる重要な用語を示します。
遠近法 2D 平面で、消失点が収束して奥行きと距離の効果を与えるときの平行線の表現です。
投影 より高次元のオブジェクトの 2D イメージを生成することです。3D 投影は 3D ポイントを 2D 平面にマップします。
回転 オブジェクトに含まれるすべてのポイントを回転させて移動することにより、オブジェクトの方向（また、多くの場合に位置）を変更することです。
変換 平行移動、回転、拡大／縮小、傾斜またはこれらのアクションの組み合わせによって 3D ポイントまたはポイントのセットを変更することです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド333

3 次元（3D）での操作

平行移動 オブジェクトに含まれるすべてのポイントを同じ方向に同じ量だけ移動することにより、オブジェクトの位置を変更することです。
消失点 線形遠近法で表現される場合に、遠のく平行線が集まるように見えるポイントです。
ベクター 3D ベクターは、極座標 x、y および z を使用して 3 次元空間でのポイントまたは位置を表します。
頂点 コーナーポイントです。
テクスチャメッシュ 3D 空間内のオブジェクトを定義する任意のポイントです。

UV マッピング テクスチャまたはビットマップを 3D サーフェスに適用する方法です。UV マッピングは、イメージ上の座
標に、水平（U）軸および垂直（V）軸のパーセンテージとしての値を割り当てます。
T 値 オブジェクトが現在の視点に近付いたり視点から離れたりするときに、3D オブジェクトのサイズを決定するための縮尺率です。
カリング 特定の湾曲を持つサーフェスをレンダリングするかどうか。カリングを使用して、現在の視点からは見えないサー
フェスを非表示にすることができます。

Flash Player および AIR ランタイムでの 3D 表示オブジェク
トについてFlash Player 10 以降、Adobe AIR 1.5 以降
Flash Player 10 よりも前の Flash Player と、Adobe AIR 1.5 よりも前の Adobe AIR の場合、表示オブジェクトには 2D
平面上の配置に使用する x および y プロパティがあります。Flash Player 10 および Adobe AIR 1.5 からは、すべてのActionScript 表示オブジェクトに、そのオブジェクトを z 軸に沿って配置するための z プロパティがあります。一般に、このプロパティは奥行きまたは距離を示すために使用されます。

Flash Player 10 および Adobe AIR 1.5 から、3D エフェクトのサポートが導入されています。ただし、表示オブジェクトの性質は平面です。MovieClip オブジェクトや Sprite オブジェクトなどの各表示オブジェクトは、最終的に自身を単一平面上に 2 次元でレンダリングします。3D 機能を使用すると、これらの平面オブジェクトを 3 次元で配置、移動、回転および変換することができます。また、3D ポイントを管理し、2D の x, y 座標に変換して、3D オブジェクトを 2D ビューに投影することもできます。これらの機能を使用して、多くの種類の 3D エクスペリエンスをシミュレートすることができます。

ActionScript で使用される 3D 座標系は、他の座標系と異なります。ActionScript で 2D 座標系を使用する場合、x 軸に沿って右に移動すると x の値が増加し、y 軸に沿って下に移動すると y の値が増加します。3D 座標系は、これらの規則を保持し、視点から遠ざかる方に移動したときに値が増加する z 軸を追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド334

3 次元（3D）での操作

A(0,0,0)C
B

D

ActionScript 3D 座標系の x、y および z 軸の正の方向。
A. + Z 軸 B. 原点 C. +X 軸 D. +Y 軸

注意：Flash Player および AIR は、3D を常にレイヤーで表現することに注意してください。つまり、オブジェクト A が表示リストでオブジェクト B の前にある場合、2 つのオブジェクトの z 軸値に関係なく、Flash Player または AIR では常に A
が B の前にレンダリングされます。表示リスト順序と z 軸順序の間のこの矛盾を解決するには、

transform.getRelativeMatrix3D() メソッドを使用して 3D 表示オブジェクトのレイヤーを保存してから、再び並べ替えます。
詳しくは、343 ページの「Matrix3D オブジェクトを使用した表示の並べ替え」を参照してください。
次の ActionScript クラスでは、新しい 3D 関連機能がサポートされます。

1 flash.display.DisplayObject クラスには、z プロパティと、3D 空間の表示オブジェクトを操作するための新しい回転および拡大／縮小プロパティがあります。DisplayObject.local3DToGlobal() メソッドは、3D ジオメトリを 2D 平面に投影する単純な方法を提供します。

2 flash.geom.Vector3D クラスは、3D ポイントを管理するためのデータ構造として使用することができます。ベクター
数式もサポートします。

3 flash.geom.Matrix3D クラスでは、回転、拡大／縮小、平行移動など、3D ジオメトリの複雑な変換がサポートされます。

4 flash.geom.PerspectiveProjection クラスでは、3D ジオメトリを 2D ビューにマッピングするためのパラメーターが制御されます。

ActionScript で 3D イメージをシミュレートするアプローチは 2 つあります。
1 3D 空間に平面オブジェクトを配置およびアニメーション化します。このアプローチでは、表示オブジェクトの x、y お
よび z プロパティを使用して表示オブジェクトをアニメーション化するか、DisplayObject クラスを使用して回転および拡大／縮小プロパティを設定します。DisplayObject.transform.matrix3D オブジェクトを使用して、より複雑な動きを実現することができます。DisplayObject.transform.perspectiveProjection オブジェクトでは、表示オブジェクトが3D 遠近法で描画される方法をカスタマイズします。主に平面から構成される 3D オブジェクトをアニメーション化する
場合は、このアプローチを使用します。このアプローチの例として、3D イメージギャラリや、3D 空間に配置された 2D
アニメーションオブジェクトがあります。

2 3D ジオメトリから 2D 三角形を生成し、これらの三角形をテクスチャ付きでレンダリングします。このアプローチを使用するには、最初に 3D オブジェクトに関するデータを定義および管理してから、データをレンダリングするために 2D
三角形に変換する必要があります。ビットマップテクスチャをこれらの三角形にマップすることができ、三角形はGraphics.drawTriangles() メソッドを使用してグラフィックスオブジェクトに描画されます。このアプローチの例には、ファイルからの 3D モデルデータのロードや画面上でのモデルのレンダリング、または三角形メッシュとしての 3D テレ
インの生成と描画があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド335

3 次元（3D）での操作

3D 表示オブジェクトの作成と移動Flash Player 10 以降、Adobe AIR 1.5 以降
2D 表示オブジェクトを 3D 表示オブジェクトに変換するには、その z プロパティを明示的に数値に設定します。z プロパ
ティに値を割り当てると、新しい Transform オブジェクトが表示オブジェクトに対して作成されます。
DisplayObject.rotationX または DisplayObject.rotationY プロパティを設定することでも、新しい Transform オブジェクトが作成されます。Transform オブジェクトには、3D スペースでの表示オブジェクトの表現方法を管理する Matrix3D プロパ
ティが含まれます。
次のコードでは、「leaf」という表示オブジェクトの座標を設定します。
leaf.x = 100; leaf.y = 50; leaf.z = -30;

これらの値と、これらの値から派生するプロパティは、リーフの Transform オブジェクトの matrix3D プロパティで参照することができます。
var leafMatrix:Matrix3D= leaf.transform.matrix3D;

trace(leafMatrix.position.x);
trace(leafMatrix.position.y);
trace(leafMatrix.position.z);
trace(leafMatrix.position.length);
trace(leafMatrix.position.lengthSquared);Transform オブジェクトのプロパティについては、Transform クラスを参照してください。Matrix3D オブジェクトのプ
ロパティについては、Matrix3D クラスを参照してください。

3D 空間でのオブジェクトの移動
Flash Player 10 以降、Adobe AIR 1.5 以降
x、y または z プロパティの値を変更することにより、3D 空間でオブジェクトを移動することができます。z プロパティの値を変更すると、オブジェクトがユーザーに近付いたりユーザーから遠ざかったりするように見えます。
次のコードでは、イベントに応答して z プロパティの値を変更することにより、z 軸に沿って 2 つの楕円を前後に移動します。ellipse2 は ellipse1 よりも高速に移動します。その z プロパティは各 Frame イベントで 20 の倍数で増加しますが、

ellipse1 の z プロパティは 10 の倍数で増加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド336

3 次元（3D）での操作

var depth:int = 1000;
function ellipse1FrameHandler(e:Event):void{ellipse1Back = setDepth(e, ellipse1Back);e.currentTarget.z += ellipse1Back * 10;}
function ellipse2FrameHandler(e:Event):void{ellipse2Back = setDepth(e, ellipse1Back);e.currentTarget.z += ellipse1Back * 20;}
function setDepth(e:Event, d:int):int{
if(e.currentTarget.z > depth){
e.currentTarget.z = depth;d = -1;}else if (e.currentTarget.z < 0){e.currentTarget.z = 0;
d = 1;}}

3D 空間でのオブジェクトの回転
Flash Player 10 以降、Adobe AIR 1.5 以降
オブジェクトは、rotationX、rotationY および rotationZ という回転プロパティの設定に応じて、3 通りの方法で回転することができます。
次の図に、回転されていない 2 つの正方形を示します。

次の図に、正方形のコンテナの rotationY プロパティをインクリメントして y 軸上で回転した場合の 2 つの正方形を示します。2 つの正方形のコンテナ、つまり親表示オブジェクトを回転すると、両方の正方形が回転します。
container.rotationY += 10;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド337

3 次元（3D）での操作

次の図に、正方形のコンテナの rotationX プロパティを設定するとどうなるかを示します。これにより、正方形が x 軸上で回転します。

次の図に、正方形のコンテナの rotationZ プロパティをインクリメントするとどうなるかを示します。これにより、正方形がz 軸上で回転します。

表示オブジェクトは、3D 空間で移動と回転を同時に行うことができます。

2D ビューへの 3D オブジェクトの投影
Flash Player 10 以降、Adobe AIR 1.5 以降
flash.geom パッケージ内の PerspectiveProjection クラスは、3D 空間で表示オブジェクトを移動する場合に基本的な遠近法を適用する単純な方法を提供します。

3D 空間の遠近法投影を明示的に作成しない場合、3D エンジンでは、ルートに存在し、すべての子に伝播されるデフォルトの PerspectiveProjection オブジェクトが使用されます。
PerspectiveProjection オブジェクトが 3D 空間に表示される方法を定義する 3 つのプロパティは次のとおりです。

• fieldOfView• projectionCenter• focalLength
fieldOfView と focalLength は相互に依存しているので、一方の値を変更すると、もう一方の値が自動的に変更されます。
特定の fieldOfView に対する focalLength の計算に使用される式は次のとおりです。
focalLength = stageWidth/2 * (cos(fieldOfView/2) / sin(fieldOfView/2)

通常は、fieldOfView プロパティを明示的に変更します。

ビューのフィールド
Flash Player 10 以降、Adobe AIR 1.5 以降
PerspectiveProjection クラスの fieldOfView プロパティを操作することにより、3D 表示オブジェクトがユーザーに近付くほど大きく表示され、ユーザーから遠ざかるほど小さく表示されるようにすることができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド338

3 次元（3D）での操作

fieldOfView プロパティでは、遠近法投影の強度を決定する 0 〜 180 度の角度を指定します。値が大きいほど、z 軸に沿って移動する表示オブジェクトに適用される歪みが強くなります。低い fieldOfView 値では、拡大／縮小が非常にわずかになり、
オブジェクトは空間内で若干後方に移動するように見えます。高い fieldOfView 値では、歪みが大きくなり、より大幅に移動したように見えます。最大値の 179.9999... 度を指定すると、極端な魚眼カメラレンズ効果が生成されます。fieldOfViewの最大値は 179.9999...、最小値は 0.00001... です。0 および 180 は無効な値です。

投影の中心Flash Player 10 以降、Adobe AIR 1.5 以降
projectionCenter プロパティは、遠近法投影の消失点を表します。このプロパティは、ステージの左上隅にあるデフォルトの登録ポイント（0,0）へのオフセットとして適用されます。
オブジェクトがユーザーから遠い方へ移動するように見える場合、そのオブジェクトは消失点に向かって傾斜し、最終的に消失します。無限の深さの穴を想像してください。穴を見下ろした場合、壁面のエッジは穴のはるか下方の消失点に収束します。
消失点がステージの中心にある場合、穴は中心のポイントに向かって消失します。projectionCenter プロパティのデフォルト
値はステージの中心です。例えば、エレメントをステージの左に表示し、3D 領域を右に表示する場合は、projectionCenterをステージの右のポイントに設定して、そのポイントを 3D 表示領域の消失点にします。

焦点の長さ
Flash Player 10 以降、Adobe AIR 1.5 以降
focalLength プロパティは、視点の原点（0,0,0）と z 軸上の表示オブジェクトの位置との間の距離を表します。
長い焦点は望遠レンズと同様で、視野が狭く、オブジェクト間の距離が圧縮されます。短い焦点は広角レンズと同様で、歪みの多い広い視野が得られます。中程度の長さの焦点は、人間の目に見えるものとほぼ同じです。
通常、focalLength は、表示オブジェクトが移動するときの遠近法変換中に動的に再計算されますが、明示的に設定することもできます。

デフォルトの遠近法投影値
Flash Player 10 以降、Adobe AIR 1.5 以降
ルートに作成されるデフォルトの PerspectiveProjection オブジェクトは、次の値を持ちます。

• fieldOfView：55• perspectiveCenter：stagewidth/2, stageHeight/2• focalLength：stageWidth/ 2 * ( cos(fieldOfView/2) / sin(fieldOfView/2) )これらは、独自の PerspectiveProjection オブジェクトを作成しない場合に使用される値です。

projectionCenter と fieldOfView を自身で変更する目的で、独自の PerspectiveProjection オブジェクトをインスタンス化することができます。この場合、新規に作成したオブジェクトのデフォルト値は、デフォルトのステージサイズである 500 ×

500 に基づいて次のようになります。

• fieldOfView：55• perspectiveCenter：250,250• focalLength：480.24554443359375

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド339

3 次元（3D）での操作

例：遠近法投影
Flash Player 10 以降、Adobe AIR 1.5 以降
次の例は、遠近法投影を使用した 3D 空間の作成を示しています。消失点を変更し、projectionCenter プロパティを通じて空間の遠近法投影を変更する方法を示します。この変更により、focalLength と fieldOfView が、変更に伴う 3D 空間の歪みによって強制的に再計算されます。
この例では、次の処理を行います。

1 center という名前のスプライトを、十字線の付いた円として作成します。
2 center スプライトの座標をルートの transform プロパティの perspectiveProjection プロパティの projectionCenter プロパ
ティに割り当てます。

3 center オブジェクトの位置の後になるように projectionCenter を変更するハンドラーを呼び出すマウスイベントのイベン
トリスナーを追加します。

4 遠近法空間の壁面を形成するアコーディオンスタイルの 4 つのボックスを作成します。
この ProjectionDragger.swf という例をテストする場合は、円を別の位置にドラッグします。消失点が円に続いて移動し、ドロップされた位置に配置されます。空間の伸縮を囲むボックスを観察し、ステージの中心から離れた方向に投影の中心を移動した場合に歪むことを確認します。
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。ProjectionDragger アプリケー
ションファイルは、Samples/ProjectionDragger フォルダーにあります。
package{import flash.display.Sprite;
import flash.display.Shape;
import flash.geom.Point;
import flash.events.*;
public class ProjectionDragger extends Sprite{
private var center : Sprite;
private var boxPanel:Shape;
private var inDrag:Boolean = false;
public function ProjectionDragger():void{
createBoxes();createCenter();}
public function createCenter():void{
var centerRadius:int = 20;
center = new Sprite();// circle
center.graphics.lineStyle(1, 0x000099);
center.graphics.beginFill(0xCCCCCC, 0.5);
center.graphics.drawCircle(0, 0, centerRadius);
center.graphics.endFill();// cross hairs
center.graphics.moveTo(0, centerRadius);
center.graphics.lineTo(0, -centerRadius);
center.graphics.moveTo(centerRadius, 0);center.graphics.lineTo(-centerRadius, 0);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

340

3 次元（3D）での操作

center.x = 175;
center.y = 175;
center.z = 0;
this.addChild(center);center.addEventListener(MouseEvent.MOUSE_DOWN, startDragProjectionCenter);center.addEventListener(MouseEvent.MOUSE_UP, stopDragProjectionCenter);center.addEventListener( MouseEvent.MOUSE_MOVE, doDragProjectionCenter);root.transform.perspectiveProjection.projectionCenter = new Point(center.x, center.y);}public function createBoxes():void{// createBoxPanel();var boxWidth:int = 50;
var boxHeight:int = 50;
var numLayers:int = 12;
var depthPerLayer:int = 50;// var boxVec:Vector.<Shape> = new Vector.<Shape>(numLayers);for (var i:int = 0; i < numLayers; i++){this.addChild(createBox(150, 50, (numLayers - i) * depthPerLayer, boxWidth, boxHeight,
0xCCCCFF));this.addChild(createBox(50, 150, (numLayers - i) * depthPerLayer, boxWidth, boxHeight,
0xFFCCCC));
this.addChild(createBox(250, 150, (numLayers - i) * depthPerLayer, boxWidth, boxHeight,
0xCCFFCC));
this.addChild(createBox(150, 250, (numLayers - i) * depthPerLayer, boxWidth, boxHeight,
0xDDDDDD));}}
public function createBox(xPos:int = 0, yPos:int = 0, zPos:int = 100, w:int = 50, h:int = 50,
color:int = 0xDDDDDD):Shape{var box:Shape = new Shape();box.graphics.lineStyle(2, 0x666666);
box.graphics.beginFill(color, 1.0);
box.graphics.drawRect(0, 0, w, h);box.graphics.endFill();
box.x = xPos;
box.y = yPos;box.z = zPos;
return box;}
public function startDragProjectionCenter(e:Event){

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド341

3 次元（3D）での操作

center.startDrag();
inDrag = true;}
public function doDragProjectionCenter(e:Event){if (inDrag){root.transform.perspectiveProjection.projectionCenter = new Point(center.x, center.y);}}public function stopDragProjectionCenter(e:Event){center.stopDrag();root.transform.perspectiveProjection.projectionCenter = new Point(center.x, center.y);
inDrag = false;}}}

より複雑な遠近法投影の場合は、Matrix3D クラスを使用します。

複雑な 3D 変換の実行
Flash Player 10 以降、Adobe AIR 1.5 以降
Matrix3D クラスでは、座標空間内の 3D ポイントを変換したり、3D ポイントをある座標空間から別の座標空間にマップしたりすることができます。

Matrix3D クラスを使用するために、マトリックス数式を理解する必要はありません。一般的な変換操作のほとんどは、クラスのメソッドを使用して処理することができます。マトリックス内の各エレメントの値の明示的な設定や計算について心配する必要はありません。
表示オブジェクトの z プロパティを数値に設定した後で、表示オブジェクトの Transform オブジェクトの Matrix3D プロ
パティを使用してオブジェクトの変換マトリックスを取得することができます。
var leafMatrix:Matrix3D = this.transform.matrix3D;

Matrix3D オブジェクトのメソッドを使用して、表示オブジェクトに対して平行移動、回転、拡大／縮小および遠近法投影を実行することができます。

Vector3D クラスは、3D ポイントを管理するために x、y および z プロパティと共に使用します。方向と大きさを持つ空間
ベクターを物理的に表すこともできます。Vector3D クラスのメソッドでは、加算、ドット積、クロス積計算などの一般的な計算を空間ベクターで実行することができます。
注意：Vector3D クラスは、ActionScript の Vector クラスと関連していません。Vector3D クラスには、3D ポイントを定義および操作するためのプロパティとメソッドが含まれますが、Vector クラスでは型を持つオブジェクトの配列がサポートされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド342

3 次元（3D）での操作

Matrix3D オブジェクトの作成
Flash Player 10 以降、Adobe AIR 1.5 以降
Matrix3D オブジェクトを作成または取得する主な方法は 3 つあります。

• Matrix3D() コンストラクターメソッドを使用して、新しいマトリックスをインスタンス化します。Matrix3D() コンスト
ラクターは、16 個の数値を含む Vector オブジェクトを受け取り、各値をマトリックスのセルに配置します。次に、例を示します。
var rotateMatrix:Matrix3D = new Matrix3D(1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1);•

表示オブジェクトの z プロパティの値を設定します。次に、そのオブジェクトの transform.matrix3D プロパティから変換
マトリックスを取得します。

•

ルート表示オブジェクトの perspectiveProjection.toMatrix3D() メソッドを呼び出すことにより、ステージ上の 3D オブ
ジェクトの表示を制御する Matrix3D オブジェクトを取得します。

複数の 3D 変換の適用
Flash Player 10 以降、Adobe AIR 1.5 以降
Matrix3D オブジェクトを使用して、一度に多数の 3D 変換を適用することができます。例えば、立方体を回転、拡大／縮小してから移動する場合は、立方体の各ポイントに 3 つの異なる変換を適用することができます。ただし、1 つのMatrix3D オブジェクトで複数の変換を事前計算してから、各ポイントに対して 1 つのマトリックス変換を実行する方がはるかに効率的です。
注意：マトリックス変換を適用する順序は重要です。マトリックス計算は累積されません。例えば、回転に続いて平行移動を適用すると、同じ平行移動に続いて同じ回転を適用した場合とは異なる結果が生成されます。
次の例に、複数の 3D 変換を実行する 2 つの方法を示します。
package {import flash.display.Sprite;
import flash.display.Shape;
import flash.display.Graphics;
import flash.geom.*;
public class Matrix3DTransformsExample extends Sprite{
private var rect1:Shape;
private var rect2:Shape;
public function Matrix3DTransformsExample():void{
var pp:PerspectiveProjection = this.transform.perspectiveProjection;
pp.projectionCenter = new Point(275,200);
this.transform.perspectiveProjection = pp;
rect1 = new Shape();
rect1.x = -70;
rect1.y = -40;
rect1.z = 0;
rect1.graphics.beginFill(0xFF8800);
rect1.graphics.drawRect(0,0,50,80);
rect1.graphics.endFill();
addChild(rect1);
rect2 = new Shape();
rect2.x = 20;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド343

3 次元（3D）での操作

rect2.y = -40;
rect2.z = 0;
rect2.graphics.beginFill(0xFF0088);
rect2.graphics.drawRect(0,0,50,80);
rect2.graphics.endFill();
addChild(rect2);
doTransforms();}
private function doTransforms():void{
rect1.rotationX = 15;
rect1.scaleX = 1.2;
rect1.x += 100;
rect1.y += 50;
rect1.rotationZ = 10;
var matrix:Matrix3D = rect2.transform.matrix3D;
matrix.appendRotation(15, Vector3D.X_AXIS);
matrix.appendScale(1.2, 1, 1);
matrix.appendTranslation(100, 50, 0);
matrix.appendRotation(10, Vector3D.Z_AXIS);
rect2.transform.matrix3D = matrix;}}}

doTransforms() メソッドのコードの最初のブロックでは、DisplayObject プロパティを使用して四角形シェイプの回転、拡大／縮小および位置を変更します。コードの 2 つ目のブロックでは、Matrix3D クラスのメソッドを使用して、同じ変換を行います。
Matrix3D メソッドを使用する主な利点は、すべての計算が最初にマトリックで実行されることです。その後、
transform.matrix3D プロパティが設定されたときに表示オブジェクトに 1 回のみ適用されます。DisplayObject プロパティを設定すると、ソースコードが若干読みやすくなります。ただし、回転プロパティや拡大／縮小プロパティが設定されるたびに、複数の計算が実行され、複数の表示オブジェクトプロパティが変更されます。
コードで同じ複雑な変換が表示オブジェクトに複数回適用される場合は、Matrix3D オブジェクトを変数として保存してから、繰り返し再適用します。

Matrix3D オブジェクトを使用した表示の並べ替え
Flash Player 10 以降、Adobe AIR 1.5 以降
前述のように、相対的な z 軸に関係なく、表示リスト内の表示オブジェクトのレイヤー順序によって表示のレイヤー順序が決定されます。アニメーションによって表示オブジェクトのプロパティが表示リスト順序とは異なる順序に変換される場合、ユーザーには、z 軸レイヤーに対応しない表示オブジェクトレイヤーが表示される場合があります。したがって、ユーザーから離れた場所に表示する必要のあるオブジェクトが、ユーザーに近い場所にあるオブジェクトの前に表示される場合があります。

3D 表示オブジェクトのレイヤーがオブジェクトの相対的な奥行きに対応していることを確認するには、次のようなアプ
ローチを使用します。

1 Transform オブジェクトの getRelativeMatrix3D() メソッドを使用して、子 3D 表示オブジェクトの相対的な z-axes を取得します。

2 removeChild() メソッドを使用して、表示リストからオブジェクトを削除します。
3 相対的な z 軸値に基づいて表示オブジェクトを並べ替えます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド344

3 次元（3D）での操作

4 addChild() メソッドを使用して、子を逆の順序で表示リストに再び追加します。
この並べ替えにより、オブジェクトが確実に相対的な z 軸に従って表示されます。
次のコードでは、3D ボックスの 6 つの面が正しく表示されます。回転が適用された後で、ボックスの面を並べ替えます。
public var faces:Array; . . .
public function ReorderChildren(){for(var ind:uint = 0; ind < 6; ind++){faces[ind].z = faces[ind].child.transform.getRelativeMatrix3D(root).position.z;
this.removeChild(faces[ind].child);}
faces.sortOn("z", Array.NUMERIC | Array.DESCENDING);
for (ind = 0; ind < 6; ind++){this.addChild(faces[ind].child);}}

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。アプリケーションのファイルは、
Samples/ReorderByZ フォルダーにあります。

3D 効果のための三角形の使用
Flash Player 10 以降、Adobe AIR 1.5 以降
ActionScript では、3D モデルは空間内の三角形のコレクションによって表現されるので、Graphics.drawTriangles() メソッドを使用してビットマップ変換を実行します（ただし、Flash Player と AIR では深度バッファーがサポートされないので、表示オブジェクトは依然として平面、つまり 2D の性質を持ちます。これについては、333 ページの「Flash Player および
AIR ランタイムでの 3D 表示オブジェクトについて」で説明しています）。Graphics.drawTriangles() メソッドは、座標のセッ
トを受け取って三角形のパスを描画するので、Graphics.drawPath() メソッドに似ています。

Graphics.drawPath() の使用方法については、224 ページの「パスの描画」を参照してください。
Graphics.drawTriangles() メソッドでは、Vector.<Number> を使用して、三角形パスのポイント位置を指定します。
drawTriangles(vertices:Vector.<Number>, indices:Vector.<int> = null, uvtData:Vector.<Number> = null,culling:String = "none"):void

drawTriangles() の最初のパラメーターは、唯一の必須パラメーターである vertices パラメーターです。このパラメーターは、三角形の描画に使用される座標を定義する数値のベクターです。3 セットの座標（6 つの数値）すべてが三角形パスを表します。各三角形には 3 つの座標のペア（2 つの x/y 値の 3 つのセット）が必要なので、indices パラメーターがないと、ベク
ターの長さは常に 6 の因数になります。次に、例を示します。
graphics.beginFill(0xFF8000);graphics.drawTriangles(
Vector.<Number>([
10,10, 100,10, 10,100,
110,10, 110,100, 20,100]));

これらの三角形のいずれもポイントを共有していませんが、共有していた場合は、2 つ目の drawTriangles() パラメーターである indices を使用して、複数の三角形の vertices ベクターの値を再利用することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド345

3 次元（3D）での操作

indices パラメーターを使用している場合は、indices 値が、vertices 配列エレメントに直接関係するインデックスではなく、
ポイントインデックスであることに注意してください。つまり、vertices ベクター内のインデックス（indices で定義されたもの）は、実際には 2 で除算された現実のインデックスです。例えば、vertices ベクターの 3 つ目のポイントについては、そのポイントの最初の数値が 4 つのベクターインデックスから開始する場合でも、2 の indices 値を使用します。
例えば、indices パラメーターを使用し、2 つの三角形をマージして、対角線のエッジを共有します。
graphics.beginFill(0xFF8000);graphics.drawTriangles(
Vector.<Number>([10,10, 100,10, 10,100, 100,100]),
Vector.<int>([0,1,2, 1,3,2]));正方形は 2 つの三角形を使用して描画されますが、vertices ベクターでは 4 つのポイントのみ指定されていることに注意してください。indices を使用すると、2 つの三角形で共有されている 2 つのポイントが各三角形に再利用されます。これにより、全体の頂点数が 6（12 個の数値）から 4（8 個の数値）に減ります。

0

1

2

3

頂点パラメーターを使用して 2 つの三角形で描画された正方形

この技法は、ほとんどのポイントが複数の三角形によって共有される大きな三角形メッシュで役立ちます。
すべての塗りが三角形に適用されます。塗りは、他のシェイプに対する場合と同様に、生成される三角形メッシュに適用されます。

ビットマップの変換
Flash Player 10 以降、Adobe AIR 1.5 以降
ビットマップ変換は、3 次元オブジェクトの遠近法または「テクスチャ」の効果を提供します。具体的には、イメージが消
失点の方向に移動するにつれて縮小するように、消失点に向かってビットマップを歪めることができます。または、2 次元
ビットマップを使用して、3 次元オブジェクトのサーフェスを作成し、その 3 次元オブジェクトに対してテクスチャまたは「ラップ」の効果を提供することができます。

消失点を使用した 2 次元サーフェスと、ビットマップにラップされた 3 次元オブジェクト。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド346

3 次元（3D）での操作

UV マッピング
Flash Player 10 以降、Adobe AIR 1.5 以降
テクスチャの操作を開始した後、drawTriangles() の uvtData パラメーターを使用することができます。このパラメーターにより、ビットマップを塗るために UV マッピングを設定することができます。

UV マッピングは、オブジェクトのテクスチャを作成するためのメソッドです。U 水平（x）値および V 垂直（y）値という2 つの値に依存します。ピクセル値に基づくのではなく、パーセンテージに基づきます。0 U および 0 V はイメージの左上であり、1 U および 1 V は右下です。

ビットマップイメージ上の UV 0 および 1 の位置

三角形のベクターには、イメージ上のそれぞれの場所に関連付けるために UV 座標を与えることができます。

ビットマップイメージの三角形領域の UV 座標

UV 値は、三角形のポイントとの整合性を保ちます。

三角形の頂点が移動し、ビットマップが歪められて、個別のポイントの UV 値が同じに保たれます。

ActionScript 3D 変換が、ビットマップに関連付けられている三角形に適用されると、ビットマップイメージが UV 値に基づいて三角形に適用されます。そのため、マトリックス計算を使用する代わりに、UV 値を設定または調整して 3 次元効果を作成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド347

3 次元（3D）での操作

Graphics.drawTriangles() メソッドは、3 次元変換のオプションの情報部分である T 値を受け入れることもあります。
uvtData の T 値は 3D 遠近法を表します。より具体的には、関連付けられた頂点の縮尺率を表します。UVT マッピングでは、UV マッピングに遠近法補正が追加されます。例えば、オブジェクトが「原点」の 50 ％ のサイズで表示されるように視点から離れた 3D 空間に配置される場合、そのオブジェクトの T 値は 0.5 になります。三角形が 3D 空間のオブジェクトを表すように描画される場合、z 軸に沿ったその位置によって T 値が決定されます。T 値を決定する等式は次のとおりです。
T = focalLength/(focalLength + z);

この等式では、focalLength は、ビューに提供される遠近法の量を示す焦点の長さまたは計算された「スクリーン」位置を
表します。
A

B

D

C

E

焦点の長さと z 値
A. 視点 B. スクリーン C. 3D オブジェクト D. focalLength 値 E. z 値

T の値を使用して、基本的なシェイプを拡大／縮小し、遠くにあるように見せます。通常これは、3D ポイントを 2D ポイン
トに変換するために使用する値です。UVT データの場合は、遠近法で三角形の内部の頂点の間のビットマップを拡大／縮小するためにも使用されます。

UVT 値を定義する場合、T 値は頂点に対して定義されている UV 値に直接従います。T を含める場合、uvtData パラメー
ターの 3 つの値（U、V および T）がすべて、vertices パラメーターの 2 つの値（x および y）に一致します。UV 値単体では、uvtData.length == vertices.length となります。T 値を含めると、uvtData.length = 1.5*vertices.length となります。
次の例では、UVT データを使用して 3D 空間で回転された平面を表示します。この例では、ocean.jpg というイメージおよび「ヘルパー」クラス ImageLoader を使用して ocean.jpg イメージがロードされるので、BitmapData オブジェクトに割り当てることができます。
次に、ImageLoader クラスソースを示します（このコードは ImageLoader.as という名前のファイルに保存します）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド348

3 次元（3D）での操作

package {import flash.display.*import flash.events.*;
import flash.net.URLRequest;
public class ImageLoader extends Sprite {public var url:String;
public var bitmap:Bitmap;
public function ImageLoader(loc:String = null) {if (loc != null){
url = loc;
loadImage();}}public function loadImage():void{
if (url != null){var loader:Loader = new Loader();loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onComplete);loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, onIoError);var req:URLRequest = new URLRequest(url);loader.load(req);}}
private function onComplete(event:Event):void {var loader:Loader = Loader(event.target.loader);var info:LoaderInfo = LoaderInfo(loader.contentLoaderInfo);
this.bitmap = info.content as Bitmap;
this.dispatchEvent(new Event(Event.COMPLETE));}
private function onIoError(event:IOErrorEvent):void {trace("onIoError: " + event);}}}

また、トライアングル、UV マッピングおよび T 値を使用して、消失点に向かって縮小し、回転するように見えるイメージを作成する ActionScript を次に示します。このコードを、Spinning3dOcean.as という名前のファイルに保存します。
package {import flash.display.*import flash.events.*;
import flash.utils.getTimer;
public class Spinning3dOcean extends Sprite {// plane vertex coordinates (and t values)
var x1:Number = -100,y1:Number = -100,z1:Number = 0,t1:Number = 0;
var x2:Number = 100,y2:Number = -100,z2:Number = 0,t2:Number = 0;
var x3:Number = 100,y3:Number = 100,z3:Number = 0,t3:Number = 0;
var x4:Number = -100,y4:Number = 100,z4:Number = 0,t4:Number = 0;
var focalLength:Number = 200;// 2 triangles for 1 plane, indices will always be the samevar indices:Vector.<int>;
var container:Sprite;
var bitmapData:BitmapData; // texture
var imageLoader:ImageLoader;public function Spinning3dOcean():void {indices = new Vector.<int>();indices.push(0,1,3, 1,2,3);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド349

3 次元（3D）での操作

container = new Sprite(); // container to draw triangles incontainer.x = 200;
container.y = 200;
addChild(container);
imageLoader = new ImageLoader("ocean.jpg");
imageLoader.addEventListener(Event.COMPLETE, onImageLoaded);}function onImageLoaded(event:Event):void {bitmapData = imageLoader.bitmap.bitmapData;// animate every frame
addEventListener(Event.ENTER_FRAME, rotatePlane);}function rotatePlane(event:Event):void {// rotate vertices over time
var ticker = getTimer()/400;
z2 = z3 = -(z1 = z4 = 100*Math.sin(ticker));x2 = x3 = -(x1 = x4 = 100*Math.cos(ticker));// calculate t values
t1 = focalLength/(focalLength + z1);
t2 = focalLength/(focalLength + z2);t3 = focalLength/(focalLength + z3);
t4 = focalLength/(focalLength + z4);// determine triangle vertices based on t values
var vertices:Vector.<Number> = new Vector.<Number>();vertices.push(x1*t1,y1*t1, x2*t2,y2*t2, x3*t3,y3*t3, x4*t4,y4*t4);// set T values allowing perspective to change// as each vertex moves around in z space
var uvtData:Vector.<Number> = new Vector.<Number>();uvtData.push(0,0,t1, 1,0,t2, 1,1,t3, 0,1,t4);// draw
container.graphics.clear();container.graphics.beginBitmapFill(bitmapData);
container.graphics.drawTriangles(vertices, indices, uvtData);}}}

この例をテストするには、この 2 つのクラスファイルを「ocean.jpg」という名前のイメージと同じディレクトリに保存します。元のビットマップがどのように変換されて、3D 空間内で遠くに消失し、回転するように見えるかを参照することが
できます。

カリング
Flash Player 10 以降、Adobe AIR 1.5 以降
カリングは、現在の視点から隠れているのでレンダラーでレンダリングする必要のない 3 次元オブジェクトのサーフェスを決定するプロセスです。3D 空間では、3 次元オブジェクトの「背面」にあるサーフェスは、視点から隠されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

350

3 次元（3D）での操作

A

B

C

3D オブジェクトの背面は、視点から隠されます。
A. 視点 B. 3D オブジェクト C. 3 次元オブジェクトの背面

本質的に、すべての三角形は、サイズ、シェイプまたは位置にかかわらず常にレンダリングされます。カリングによって、Flash Player または AIR によって確実に 3D オブジェクトが正しくレンダリングされます。また、レンダリングサイクルを短縮するために、一部の三角形がレンダリングでスキップされるようにする場合があります。空間内で回転する立方体について考えます。特定の時点で、ビューにない面は立方体の他の面の他の方向に面しているので、その立方体の 3 つの面以外は見えません。これらの面は表示されないので、レンダラーは描画しない必要があります。カリングを使用しないと、Flash Player または AIR では、前面と背面の両方がレンダリングされます。

立方体には、現在の視点からは見えない面があります。

したがって、Graphics.drawTriangles() メソッドには、カリング値を設定するための第 4 のパラメーターがあります。
public function drawTriangles(vertices:Vector.<Number>, indices:Vector.<int> = null,
uvtData:Vector.<Number> = null, culling:String = "none"):void

カリングパラメーターは、TriangleCulling 列挙クラスの値である TriangleCulling.NONE、TriangleCulling.POSITIVE および

TriangleCulling.NEGATIVE です。これらの値は、オブジェクトのサーフェスを定義する三角形パスの方向に依存します。カ
リングを決定する ActionScript API では、3D シェイプのすべての外向き三角形が同じパス方向に描画されると想定されます。三角形の表面が裏返ると、パス方向も変更されます。そのポイントで、三角形をカリング（レンダリングから削除）することができます。
したがって、POSITIVE の TriangleCulling 値によって、三角形が正のパス方向（時計回り）に削除されます。NEGATIVE のTriangleCulling 値では、三角形が負（反時計回り）のパス方向に削除されます。立方体の場合、前面を向いているサーフェ
スは正のパス方向を持ち、背面を向いているサーフェスは負のパス方向を持ちます。

立方体は「ラップ解除」されて、パス方向が表示されます。「ラップ」されている場合は、背面のパス方向が逆転します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド351

3 次元（3D）での操作

カリングの動作を参照するには、前の 346 ページの「UV マッピング」の例から開始し、drawTriangles() メソッドのカリン
グパラメーターを TriangleCulling.NEGATIVE に設定します。
container.graphics.drawTriangles(vertices, indices, uvtData, TriangleCulling.NEGATIVE);

イメージの「背面」は、オブジェクトが回転したときにレンダリングされないことに注意してください。

最終更新日 2015/10/14

352

第 20 章：テキストの操作の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe® Flash® Player または Adobe® AIR™ の画面にテキストを表示するには、TextField クラスのインスタンスまたはFlash Text Engine クラスを使用します。これらのクラスを使用することにより、テキストを作成、表示、フォーマットできます。または、Text Layout Framework（TLF）を使用することもできます。Text Layout Framework は、Flash Text
Engine クラスに基づいたコンポーネントライブラリですが、使いやすいように設計されています。モバイルデバイスでは、StageText クラスを使用してテキスト入力を作成できます。
テキストフィールドに特定のコンテンツを設定するかテキストのソースを指定してから、そのテキストの外観を設定することができます。また、テキストの入力や、ハイパーテキストリンクのクリックなどのユーザーイベントに応答することもできます。

TextField クラスと Flash Text Engine クラスのどちらを使用しても、Flash Player および AIR でテキストを表示および管理できます。TextField クラスを使用して、表示および入力するテキストオブジェクトを作成できます。TextField クラス
では、TextArea や TextInput のような他のテキストベースコンポーネントの基礎が提供されます。TextFormat クラスを使用して TextField オブジェクトの文字および段落の形式を設定し、Textfield.styleSheet プロパティと StyleSheet クラス
を使用して Cascading Style Sheets（CSS）を適用できます。HTML 形式のテキストをテキストフィールドに直接割り当て
ることができます。HTML 形式のテキストには、埋め込みメディア（ムービークリップ、SWF ファイル、GIF ファイル、
PNG ファイルおよび JPEG ファイル）を含めることができます。
Flash Player 10 および Adobe AIR 1.5 以降で使用可能な Flash Text Engine は、テキストメトリック、フォーマットおよび双方向テキストの高度な制御の低レベルのサポートを提供します。改善されたテキストフローと強化された言語サポートも提供します。Flash Text Engine を使用してテキストエレメントを作成および管理できますが、基本的にはテキスト処理
コンポーネントの作成の基盤として設計されており、より多くのプログラミング知識が必要です。Text Layout Frameworkには Flash Text Engine に基づいたテキスト処理コンポーネントが含まれており、新しいテキストエンジンの拡張機能を容易に使用することができます。Text Layout Framework は、すべて ActionScript 3.0 で作成されている拡張可能なライブ
ラリです。既存の TLF コンポーネントを使用できますが、このフレームワークを使用して独自のテキストコンポーネントを作成することも可能です。

StageText クラス（AIR 3 以降で使用可能）は、ネイティブなテキスト入力フィールドを作成するクラスです。これはデバ
イスの OS に用意されているフィールドなので、そのデバイスのユーザーに最もよく馴染んだ使い勝手を実現することができます。StageText インスタンスは表示オブジェクトではありません。表示リストに追加するのではなく、インスタンスをステージに割り当て、そのステージ上のビューポートと呼ばれる表示領域に割り当てます。StageText インスタンスは、他の表示オブジェクトよりも前面に表示されます。
これらのトピックについて詳しくは、以下を参照してください。

• 354 ページの「TextField クラスの使用」• 378 ページの「Flash Text Engine の使用」
• 406 ページの「Text Layout Framework の使用」
• StageText によるネイティブテキスト入力
重要な概念と用語
次の参照リストに、テキスト処理に関連する重要な用語を示します。
カスケーディングスタイルシート（CSS）XML（または HTML）形式で構造化されたコンテンツのスタイルやフォーマッ
トを指定するための標準的なシンタックスです。
デバイスフォント ユーザーのコンピューターにインストールされているフォントです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

353

テキストの操作の基礎

ダイナミックテキストフィールド コンテンツを ActionScript で変更することはできるが、ユーザー入力で変更することはできないテキストフィールドです。
埋め込みフォント 文字のアウトラインデータがアプリケーションの SWF ファイルに保存されるフォントです。

HTML テキスト 実際のテキストコンテンツと共に HTML フォーマットタグを含み、ActionScript によってテキスト
フィールドに入力されるテキストコンテンツです。
テキスト入力フィールド ユーザー入力と ActionScript のいずれでもコンテンツを変更できるテキストフィールドです。
カーニング 文字のペア間のスペースを調整して、単語内のスペースを均一にし、テキストを読みやすくすることです。
静止テキストフィールド オーサリングツールで作成された、SWF ファイルの実行時にコンテンツを変更することができな
いテキストフィールドです。
テキスト行のメトリック テキストのベースライン、文字の最上部の高さ、ディセンダ（一部の英小文字でベースラインよりも下側にある部分）のサイズなどの、テキストフィールド内のテキストコンテンツの様々な部分のサイズの測定情報です。
トラッキング 文字のグループまたはテキストのブロック間のスペースを調整して、密度を増減し、テキストを読みやすくすることです。

最終更新日 2015/10/14

354

第 21 章：TextField クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
TextField クラスのインスタンスを使用して、Adobe® Flash® Player または Adobe® AIR™ の画面にテキストを表示したり、
テキスト入力フィールドを作成したりできます。TextField クラスは、TextArea コンポーネントや TextInput コンポーネントのような他のテキストベースコンポーネントの基礎となります。
テキストフィールドのコンテンツは、SWF ファイル内にあらかじめ指定することも、テキストファイルやデータベースからロードすることもできます。また、アプリケーションを操作するユーザーが入力することもできます。テキストフィールド内では、テキストはレンダリング済み HTML にイメージが埋め込まれたレンダリング済み HTML コンテンツとして表示されます。テキストフィールドのインスタンスを作成したら、TextFormat や StyleSheet などの flash.text クラスを使用してテキストの外観を制御できます。flash.text パッケージ には、ActionScript でのテキストの作成、管理および書式設定に関連するクラスがほぼすべて含まれています。
テキストをフォーマットするには、TextFormat オブジェクトを使用してフォーマットを定義し、そのオブジェクトをテキ
ストフィールドに割り当てます。テキストフィールドに HTML テキストが含まれる場合、テキストフィールドに StyleSheet
オブジェクトを適用すると、テキストフィールドのコンテンツの特定の部分にスタイルを割り当てることができます。

TextFormat オブジェクトまたは StyleSheet オブジェクトには、カラー、サイズ、太さなど、テキストの外観を定義するプ
ロパティが含まれています。TextFormat オブジェクトは、テキストフィールド内のすべてのコンテンツ、または一部の範囲のテキストにこれらのプロパティを割り当てます。例えば、同じテキストフィールド内で、ある文をボールドの赤いテキストとし、次の文をイタリックの青いテキストにすることができます。
テキスト関連のユーザー操作への応答には、flash.text パッケージ内のクラスに加えて、flash.events.TextEvent クラスも使用することができます。

関連項目

361 ページの「テキストフォーマットの割り当て」
356 ページの「HTML テキストの表示」
362 ページの「CSS の適用」

テキストの表示Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe Flash Builder や Flash Professional などのオーサリングツールには、テキスト関連コンポーネントやテキストツー
ルなどのいくつかのオプションがテキスト表示のために用意されていますが、テキストをプログラムによって表示する最も単純な方法はテキストフィールドを使用する方法です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

355

TextField クラスの使用

テキストのタイプ
Flash Player 9 以降、Adobe AIR 1.0 以降
テキストフィールド内のテキストのタイプは、そのソースによって次のように分類されます。

•

ダイナミックテキスト
ダイナミックテキストには、テキストファイル、XML ファイル、さらにはリモート Web サービスなどの外部ソースからロードされたコンテンツが含まれます。

•

入力テキスト
入力テキストは、ユーザーが入力した任意のテキストまたはユーザーが編集可能なダイナミックテキストです。入力テキストをフォーマットするスタイルシートを設定するか、または flash.text.TextFormat クラスを使用して、入力コンテンツのテキストフィールドにプロパティを割り当てることができます。詳しくは、360 ページの「テキスト入力のキャプ
チャ」を参照してください。

•

静止テキスト静止テキストは、Flash Professional でのみ作成できます。ActionScript 3.0 を使用して静止テキストのインスタンスを作成することはできません。ただし、StaticText および TextSnapshot などの ActionScript クラスを使用して、既存の静止テキストのインスタンスを操作することができます。詳しくは、367 ページの「静止テキストの操作」を参照してください。

テキストフィールドのコンテンツの変更
Flash Player 9 以降、Adobe AIR 1.0 以降
flash.text.TextField.text プロパティにストリングを割り当てることにより、ダイナミックテキストを定義できます。次のように、ストリングをプロパティに直接割り当てます。
myTextField.text = "Hello World";

次の例に示すように、text プロパティにスクリプトで定義した変数の値を割り当てることもできます。
package{import flash.display.Sprite;
import flash.text.*;
public class TextWithImage extends Sprite{
private var myTextBox:TextField = new TextField();
private var myText:String = "Hello World";
public function TextWithImage(){
addChild(myTextBox);
myTextBox.text = myText;}}}

または、text プロパティにリモート変数の値を割り当てることができます。リモートソースからテキストの値をロードする
方法には、以下の 3 つのオプションがあります。

• flash.net.URLLoader および flash.net.URLRequest クラスは、ローカルまたはリモートロケーションからテキストの変数をロードします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

356

TextField クラスの使用• FlashVars 属性は、SWF ファイルをホストする HTML ページに埋め込むもので、テキストの変数の値を含めることができます。

• flash.net.SharedObject クラスは値の永続ストレージを管理します。詳しくは、676 ページの「ローカルデータの保存」
を参照してください。

HTML テキストの表示
Flash Player 9 以降、Adobe AIR 1.0 以降
flash.text.TextField クラスには htmlText プロパティが含まれており、このプロパティを使用すると、コンテンツをフォーマットするための HTML タグが含まれているストリングとして、テキストストリングを指定することができます。次の例に示すように、Flash Player または AIR でテキストを HTML としてレンダリングするには、text プロパティではなく、
htmlText プロパティにストリング値を割り当てる必要があります。
var myText:String = "<p>This is <b>some</b> content to <i>render</i> as <u>HTML</u> text.</p>";myTextBox.htmlText = myText;

Flash Player および AIR は、htmlText プロパティでは、一部の HTML タグと HTML エンティティをサポートします。
『ActionScript 3.0 リファレンス』の flash.text.TextField.htmlText プロパティの説明には、サポートされる HTML タグとHTML エンティティについての詳細情報が用意されています。
htmlText プロパティを使用してコンテンツを指定した後、スタイルシートまたは textformat タグを使用してコンテンツのフォーマットを管理することができます。詳しくは、361 ページの「テキストのフォーマット」を参照してください。

テキストフィールドでのイメージの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
コンテンツを HTML テキストとして表示することには、テキストフィールドにイメージを含めることができるという利点もあります。img タグを使用して、ローカルまたはリモートのイメージを参照し、関連付けられたテキストフィールドに表示させることができます。
次の例では、myTextBox という名前のテキストフィールドを作成し、SWF ファイルと同じディレクトリに格納されている目の JPG イメージを、表示テキスト内に埋め込みます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

357

TextField クラスの使用

package{import flash.display.Sprite;
import flash.text.*;
public class TextWithImage extends Sprite{
private var myTextBox:TextField;
private var myText:String = "<p>This is <b>some</b> content to <i>test</i> and <i>see</i></p><p><img
src='eye.jpg' width='20' height='20'></p><p>what can be rendered.</p><p>You should see an eye image and some<u>HTML</u> text.</p>";public function TextWithImage(){
myTextBox.width = 200;
myTextBox.height = 200;
myTextBox.multiline = true;
myTextBox.wordWrap = true;
myTextBox.border = true;
addChild(myTextBox);
myTextBox.htmlText = myText;}}}

img タグは、JPEG、GIF、PNG、および SWF ファイルをサポートします。

テキストフィールド内のテキストのスクロール
Flash Player 9 以降、Adobe AIR 1.0 以降
テキストが、テキストを表示するテキストフィールドよりも長くなる場合がよくあります。または、一度に表示可能なテキストより長いテキストを入力できる入力フィールドを使用する場合があります。flash.text.TextField クラスのスクロール関
連プロパティを使用して、長いコンテンツを垂直または水平方向に管理することができます。
スクロール関連のプロパティには、TextField.scrollV、TextField.scrollH、maxScrollV および maxScrollH があります。これらのプロパティを使用して、マウスのクリックやキー押下などのイベントに応答します。
次の例では、フィールドで一度に表示可能な長さを超えるテキストを含むようにサイズが設定されたテキストフィールドを作成します。ユーザーがテキストフィールドをクリックすると、テキストが垂直方向にスクロールされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

358

TextField クラスの使用

package{import flash.display.Sprite;
import flash.text.*;
import flash.events.MouseEvent;public class TextScrollExample extends Sprite{
private var myTextBox:TextField = new TextField();
private var myText:String = "Hello world and welcome to the show. It's really nice to meet you.
Take your coat off and stay a while. OK, show is over. Hope you had fun. You can go home now. Don't forget
to tip your waiter. There are mints in the bowl by the door. Thank you. Please come again.";public function TextScrollExample(){myTextBox.text = myText;
myTextBox.width = 200;
myTextBox.height = 50;
myTextBox.multiline = true;
myTextBox.wordWrap = true;
myTextBox.background = true;
myTextBox.border = true;
var format:TextFormat = new TextFormat();format.font = "Verdana";
format.color = 0xFF0000;
format.size = 10;
myTextBox.defaultTextFormat = format;
addChild(myTextBox);
myTextBox.addEventListener(MouseEvent.MOUSE_DOWN, mouseDownScroll);}
public function mouseDownScroll(event:MouseEvent):void{
myTextBox.scrollV++;}}}

テキストの選択と操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ダイナミックまたは入力テキストを選択できます。TextField クラスのテキスト選択プロパティとメソッドは、インデックス
位置を使用して操作するテキストの範囲を設定するので、コンテンツがわからない場合でも、プログラムによってダイナ
ミックまたは入力テキストを選択することができます。
注意：Flash Professional では、選択可能にするオプションを静止テキストフィールドで選択した場合、表示リストにエク
スポートされて配置されるテキストフィールドは、通常のダイナミックテキストフィールドになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

359

TextField クラスの使用

テキストの選択Flash Player 9 以降、Adobe AIR 1.0 以降
flash.text.TextField.selectable プロパティはデフォルトで true になっています。したがって、setSelection() メソッドを使用してプログラムでテキストを選択することができます。
例えば、ユーザーがテキストフィールドをクリックしたときにそのテキストフィールドの内部の特定のテキストが選択されるように設定することができます。
var myTextField:TextField = new TextField();
myTextField.text = "No matter where you click on this text field the TEXT IN ALL CAPS is selected.";myTextField.autoSize = TextFieldAutoSize.LEFT;
addChild(myTextField);
addEventListener(MouseEvent.CLICK, selectText);
function selectText(event:MouseEvent):void{
myTextField.setSelection(49, 65);}

テキストフィールド内のテキストが最初に表示されるときにそのテキストが選択されるようにする場合も、同様にして、テキストフィールドが表示リストに追加されるときに呼び出されるイベントハンドラー関数を作成します。

ユーザー選択テキストのキャプチャ
Flash Player 9 以降、Adobe AIR 1.0 以降
TextField の selectionBeginIndex プロパティと selectionEndIndex プロパティを使用すると、ユーザーが現在選択している内容をキャプチャできます。これらのプロパティは “ 読み取り専用 ” のため、プログラムに従ってテキストを選択するように設定することはできません。また、入力テキストフィールドでは caretIndex プロパティを使用できます。
例えば、次のコードではユーザー選択テキストのインデックス値をトレースしています。
var myTextField:TextField = new TextField();
myTextField.text = "Please select the TEXT IN ALL CAPS to see the index values for the first and lastletters.";
myTextField.autoSize = TextFieldAutoSize.LEFT;
addChild(myTextField);
addEventListener(MouseEvent.MOUSE_UP, selectText);
function selectText(event:MouseEvent):void{
trace("First letter index position: " + myTextField.selectionBeginIndex);
trace("Last letter index position: " + myTextField.selectionEndIndex);}

選択範囲に TextFormat オブジェクトのプロパティのコレクションを適用すると、テキストの外観を変更することができます。選択されているテキストに TextFormat のプロパティのコレクションを適用する方法について詳しくは、364 ページの「テキストフィールド内のテキストの範囲のフォーマット」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

360

TextField クラスの使用

テキスト入力のキャプチャ
Flash Player 9 以降、Adobe AIR 1.0 以降
デフォルトでは、テキストフィールドの type プロパティは dynamic に設定されます。TextFieldType クラスを使用して type
プロパティを input に設定すると、アプリケーションの他の部分で使用するために、ユーザー入力を収集し、値を保存することができます。入力テキストフィールドは、フォームで使用するのに便利です。また、テキスト値をユーザーに定義させてその値をプログラムの他の部分で使用するアプリケーションでも役に立ちます。
例えば、次のコードは、myTextBox という名前の入力テキストフィールドを作成します。ユーザーがフィールドにテキストを入力すると、textInput イベントがトリガーされます。textInputCapture という名前のイベントハンドラーが、入力されたテキストのストリングをキャプチャして、変数を割り当てます。Flash Player は、myOutputBox という名前の別のテキスト
フィールドにその新しいテキストを表示します。
package{import flash.display.Sprite;
import flash.display.Stage;
import flash.text.*;
import flash.events.*;
public class CaptureUserInput extends Sprite{
private var myTextBox:TextField = new TextField();
private var myOutputBox:TextField = new TextField();
private var myText:String = "Type your text here.";public function CaptureUserInput(){
captureText();}
public function captureText():void{
myTextBox.type = TextFieldType.INPUT;
myTextBox.background = true;
addChild(myTextBox);
myTextBox.text = myText;
myTextBox.addEventListener(TextEvent.TEXT_INPUT, textInputCapture);}
public function textInputCapture(event:TextEvent):void{
var str:String = myTextBox.text;
createOutputBox(str);}
public function createOutputBox(str:String):void{
myOutputBox.background = true;
myOutputBox.x = 200;
addChild(myOutputBox);
myOutputBox.text = str;}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

361

TextField クラスの使用

テキスト入力の制限
Flash Player 9 以降、Adobe AIR 1.0 以降
通常、入力テキストフィールドはアプリケーションのフォームまたはダイアログボックスとして使用されるので、ユーザーがテキストフィールドに入力できる文字のタイプを制限する必要や、パスワードなどのテキストを非表示にする必要がある
場合があります。flash.text.TextField クラスには、ユーザー入力を制御するために設定できる displayAsPassword プロパ
ティと restrict プロパティが用意されています。

displayAsPassword プロパティは、単にユーザーが入力するテキストを非表示にします（一連のアスタリスクとして表示）。
displayAsPassword を true に設定すると、「カット」コマンドと「コピー」コマンド、およびそれに対応するキーボード
ショートカットが機能しなくなります。次の例に示すように、displayAsPassword プロパティは、背景や色などの他のプロパ
ティと同様の方法で割り当てます。
myTextBox.type = TextFieldType.INPUT;
myTextBox.background = true;
myTextBox.displayAsPassword = true;
addChild(myTextBox);

restrict プロパティは、ユーザーが入力テキストフィールドに入力できる文字を指定する必要があるので若干複雑です。特定の文字、数字、または文字、数字の範囲を指定することができます。次のコードでは、ユーザーはテキストフィールドに大文字のみ入力することができます（数字または特殊文字は入力できません）。
myTextBox.restrict = "A-Z";

ActionScript 3.0 では、ハイフンを使用して範囲を定義し、キャレットを使用して除外する文字を定義します。入力テキス
トフィールドでの制限事項の定義について詳しくは、『ActionScript 3.0 リファレンス』の flash.text.TextField.restrict プロパ
ティの項を参照してください。
注意：flash.text.TextField.restrict プロパティを使用する場合は、ランタイムによって、制限された文字が、許可された大文字
または小文字に自動的に変換されます。fl.text.TLFTextField.restrict プロパティを使用する場合（つまり、TLF テキスト
フィールドを使用する場合）は、ランタイムによって、制限された文字が無視されます。

テキストのフォーマット
Flash Player 9 以降、Adobe AIR 1.0 以降
テキストの表示をプログラムによってフォーマットする方法には、いくつかのオプションがあります。TextFIeld.thickness、

TextField.textColor および TextField.textHeight プロパティなどの TextField インスタンスで、直接プロパティを設定することができます。または htmlText プロパティを使用してテキスト フィールドのコンテンツを指定し、b、i、u などのサポート
される HTML タグを使用することができます。ただし、プレーンテキストを含むテキストフィールドに TextFormat オブジェクトを適用することや、htmlText プロパティを含むテキストフィールドに StyleSheet オブジェクトを適用することもできます。TextFormat と StyleSheet オブジェクトを使用することにより、アプリケーション全体を通じてテキストの外観を制御し、一貫性を保持することができます。TextFormat または StyleSheet オブジェクトを定義して、アプリケーションの大部分またはすべてのテキストフィールドに適用することができます。

テキストフォーマットの割り当てFlash Player 9 以降、Adobe AIR 1.0 以降
TextFormat クラスを使用すると、様々なテキスト表示プロパティを設定して、TextField オブジェクト全体、または一部の範囲のテキストにそれらのプロパティを適用することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

362

TextField クラスの使用

次の例では、TextField オブジェクト全体に 1 つの TextFormat オブジェクトを適用し、その TextField オブジェクトに含まれるテキスト範囲に別の TextFormat オブジェクトを適用します。
var tf:TextField = new TextField();
tf.text = "Hello Hello";
var format1:TextFormat = new TextFormat();format1.color = 0xFF0000;
var format2:TextFormat = new TextFormat();format2.font = "Courier";
tf.setTextFormat(format1);
var startRange:uint = 6;
tf.setTextFormat(format2, startRange);
addChild(tf);

TextField.setTextFormat() メソッドは、既にテキストフィールドに表示されているテキストにのみ影響します。TextField のコンテンツが変化する場合、TextField.setTextFormat() メソッドをアプリケーションからもう一度呼び出して、フォーマット
を再適用しなければならないことがあります。また、TextField オブジェクトの defaultTextFormat プロパティを設定すると、ユーザー入力テキストに適用するフォーマットを指定することができます。

CSS の適用
Flash Player 9 以降、Adobe AIR 1.0 以降
テキストフィールドには、プレーンテキストまたは HTML 形式のテキストを含めることができます。プレーンテキストはインスタンスの text プロパティに格納し、HTML テキストは htmlText プロパティに格納します。

CSS スタイル宣言を使用すると、多数の異なるテキストフィールドに適用できるテキストスタイルを定義することができます。CSS スタイル宣言は、アプリケーションコード内で作成することも、実行時に外部 CSS ファイルからロードすることもできます。

CSS スタイルの処理には flash.text.StyleSheet クラスを使用します。StyleSheet クラスでは、一部の CSS プロパティに限り認識されます。StyleSheet クラスでサポートされるスタイルプロパティの詳細な一覧については、『ActionScript 3.0 リファ
レンス』の flash.textStylesheet の項を参照してください。
次の例に示すように、StyleSheet オブジェクトを使用してコードで CSS を作成し、作成したスタイルを HTML テキストに適用することができます。
var style:StyleSheet = new StyleSheet();var styleObj:Object = new Object();styleObj.fontSize = "bold";styleObj.color = "#FF0000";style.setStyle(".darkRed", styleObj);var tf:TextField = new TextField();
tf.styleSheet = style;tf.htmlText = "<span class = 'darkRed'>Red</span> apple";
addChild(tf);

この例のコードでは、StyleSheet オブジェクトを作成した後、一連のスタイル宣言プロパティを保持する単純オブジェクトを作成します。続いて、StyleSheet.setStyle() メソッドを呼び出します。このメソッドによって、「.darkred」という名前の新しいスタイルがスタイルシートに追加されます。次に、StyleSheet オブジェクトを TextField の styleSheet プロパティに割り当てることにより、スタイル シートのフォーマットを適用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

363

TextField クラスの使用

CSS スタイルを有効にするには、htmlText プロパティが設定される前に、TextField オブジェクトにスタイルシートを適用する必要があります。
設計上、スタイルシートを含むテキストフィールドは編集できません。入力テキストフィールドがあり、スタイルシートが割り当てられている場合、テキストフィールドにはスタイルシートのプロパティが表示されますが、ユーザーはテキスト
フィールドに新しいテキストを入力することはできません。また、スタイルシートが割り当てられたテキストフィールドで、次の ActionScript API を使用することはできません。

• TextField.replaceText() メソッド
• TextField.replaceSelectedText() メソッド
• TextField.defaultTextFormat プロパティ• TextField.setTextFormat() メソッド
テキストフィールドにスタイルシートが割り当てられている場合に、後で TextField.styleSheet プロパティを null に設定すると、TextField.text プロパティと TextField.htmlText プロパティの両方のコンテンツがタグと属性をそれぞれのコンテンツに追加し、以前に割り当てられたスタイルシートのフォーマットを組み込みます。元の htmlText プロパティを維持するには、
スタイルシートを null に設定する前に、このプロパティを変数に保存します。

外部 CSS ファイルのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
CSS を使用してフォーマットを適用する手法は、実行時に外部ファイルから CSS 情報をロードできる場合にはいっそう強力なものになります。CSS データがアプリケーション自体の外部にある場合、ActionScript 3.0 のソースコードを変更しなくても、アプリケーションのテキストの視覚的なスタイルを変更することができます。アプリケーションをデプロイした後、外部 CSS ファイルを変更することによってアプリケーションの外観を変更できます。このとき、アプリケーションの SWF
ファイルを再度デプロイする必要はありません。

StyleSheet.parseCSS() メソッドは、CSS データが含まれているストリングを変換して、StyleSheet オブジェクトにスタイル宣言として格納します。次の例は、外部 CSS ファイルを読み取り、そのファイルに含まれるスタイル宣言を TextField オブジェクトに適用する方法を示しています。
まず、ロードする CSS ファイルの内容を示します。このファイルには example.css という名前を付けます。
p {font-family: Times New Roman, Times, _serif;
font-size: 14;}
h1 {font-family: Arial, Helvetica, _sans;font-size: 20;
font-weight: bold;}.bluetext {color: #0000CC;}

次に、example.css ファイルをロードして TextField のコンテンツにスタイルを適用するクラスの ActionScript コードを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

364

TextField クラスの使用

package{import flash.display.Sprite;
import flash.events.Event;import flash.net.URLLoader;import flash.net.URLRequest;
import flash.text.StyleSheet;
import flash.text.TextField;
import flash.text.TextFieldAutoSize;public class CSSFormattingExample extends Sprite{
var loader:URLLoader;var field:TextField;
var exampleText:String = "<h1>This is a headline</h1>" +"<p>This is a line of text. <span class='bluetext'>" +"This line of text is colored blue.</span></p>";public function CSSFormattingExample():void{
field = new TextField();
field.width = 300;
field.autoSize = TextFieldAutoSize.LEFT;
field.wordWrap = true;
addChild(field);var req:URLRequest = new URLRequest("example.css");
loader = new URLLoader();loader.addEventListener(Event.COMPLETE, onCSSFileLoaded);loader.load(req);}public function onCSSFileLoaded(event:Event):void{
var sheet:StyleSheet = new StyleSheet();sheet.parseCSS(loader.data);
field.styleSheet = sheet;field.htmlText = exampleText;}}}

CSS データがロードされると、onCSSFileLoaded() メソッドが実行され、StyleSheet.parseCSS() メソッドが呼び出されて、スタイル宣言が StyleSheet オブジェクトに転送されます。

テキストフィールド内のテキストの範囲のフォーマット
Flash Player 9 以降、Adobe AIR 1.0 以降
flash.text.TextField クラスの便利なメソッドは、setTextFormat() メソッドです。setTextFormat() を使用すると、ユーザー
入力に応答する形でテキストフィールドの一部のコンテンツに特定のプロパティを割り当てることができます。例えば、特定の項目が入力必須であることをユーザーに通知する必要があるフォームや、ユーザーがテキストを部分的に選択したときにテキストフィールド内のテキストの一部の強調を変更する必要があるフォームで使用します。
次の例では、ユーザーがテキストフィールド myTextField をクリックすると一部の範囲の文字に対してTextField.setTextFormat() が使用され、このテキストフィールドの一部のコンテンツの外観が変更されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

365

TextField クラスの使用

var myTextField:TextField = new TextField();
myTextField.text = "No matter where you click on this text field the TEXT IN ALL CAPS changes format.";myTextField.autoSize = TextFieldAutoSize.LEFT;
addChild(myTextField);
addEventListener(MouseEvent.CLICK, changeText);
var myformat:TextFormat = new TextFormat();myformat.color = 0xFF0000;
myformat.size = 18;
myformat.underline = true;
function changeText(event:MouseEvent):void{
myTextField.setTextFormat(myformat, 49, 65);}

高度なテキストレンダリング
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、埋め込みフォント、アンチエイリアス設定、アルファチャンネル制御、およびその他固有の設定を含む、表示するテキストのプロパティを制御する様々なクラスが flash.text パッケージに用意されています。CSMSettings、
Font、TextRenderer の各クラスを始めとするこれらのクラスとプロパティについては、『ActionScript 3.0 リファレンス』
で詳細に説明しています。

埋め込みフォントの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションで TextField に対して特定のフォントを指定すると、Flash Player または AIR は同じ名前のデバイスフォ
ント（ユーザーのコンピューターに存在するフォント）を検索します。そのようなフォントがシステムに見つからない場合
や、名前が同じでバージョンが若干異なるフォントが存在している場合には、テキストの表示が、意図したものとはかなり異なるものになることがあります。デフォルトでは、Times Roman フォントでテキストが表示されます。
意図したとおりに適切なフォントがユーザーに表示されるようにするには、アプリケーションの SWF ファイルにそのフォントを埋め込みます。埋め込みフォントにはいくつかの利点があります。

•

埋め込みフォントの文字はアンチエイリアス処理されるので、エッジが滑らかに見えます。テキストのサイズが大きい場
合に特によくわかります。

•

埋め込みフォントを使用しているテキストは回転することができます。

•

埋め込みフォントを使用しているテキストは透明や半透明にすることができます。

•

埋め込みフォントには CSS の kerning スタイルを使用することができます。

埋め込みフォントを使用する場合の最大の制約は、そのためにアプリケーションのファイルサイズまたはダウンロードサイズが増加することです。
フォントファイルをアプリケーションの SWF ファイルに埋め込む方法は、開発環境によって異なります。
フォントを埋め込んだ後は、次の作業を行って、TextField で正しい埋め込みフォントが使用されるようにします。

• TextField の embedFonts プロパティを true に設定します。
• TextFormat オブジェクトを作成し、そのオブジェクトの fontFamily プロパティに、埋め込みフォントの名前を設定します。その後で、作成した TextFormat オブジェクトを TextField に適用します。埋め込みフォントを指定するとき、最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

366

TextField クラスの使用

fontFamily プロパティに格納する名前は 1 つだけにする必要があります。このプロパティでは、複数のフォント名を含む
カンマ区切りリストを使用することはできません。

• CSS スタイルを使用して TextField やコンポーネントのフォントを設定している場合は、CSS プロパティ font-family に、埋め込みフォントの名前を設定します。埋め込みフォントを指定する場合、font-family プロパティに格納する名前は 1 つだけにする必要があります。名前のリストを格納しないでください。

Flash でのフォントの埋め込みFlash Professional では、TrueType フォントや Type 1 PostScript フォントを含め、システムにインストールされているほとんどすべてのフォントを埋め込むことができます。
アプリケーションでは次のような様々な方法でフォントを埋め込むことができます。

•

ステージ上にある TextField のフォントとスタイルのプロパティを設定し、[ フォントを埋め込む ] チェックボックスをクリックします。

•

フォントシンボルの作成と参照•

埋め込みフォントシンボルを含むランタイム共有ライブラリの作成と使用

アプリケーションでフォントを埋め込む方法について詳しくは、『Flash ユーザーガイド』の「ダイナミックテキストフィー
ルド用またはテキスト入力フィールド用の埋め込みフォント」を参照してください。

Flex でのフォントの埋め込み
Flex アプリケーションでは次のような様々な方法でフォントを埋め込むことができます。

•

スクリプトで [Embed] メタデータタグを使用する• @font-face スタイル宣言を使用する•

フォントのクラスを作成し、[Embed] タグを使用して埋め込みます。

Flex アプリケーションで直接埋め込むことができるのは TrueType フォントのみです。Type 1 Postscript フォントなど、その他の形式のフォントは、最初に Flash Professional を使用して SWF ファイルに埋め込んだ後、その SWF ファイルを
Flex アプリケーションで使用します。Flex の SWF ファイルの埋め込みフォントの使用について詳しくは、『Flex 4 ユーザーガイド』の「SWF ファイルからのフォントの埋め込み」を参照してください。
関連項目
環境を問わず一貫した外観でテキストを表示するためのフォントの埋め込みPeter deHaan：Embedding fonts
Divillysausages.com：AS3 Font embedding masterclass

シャープ、太さ、およびアンチエイリアスの制御
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player または AIR では、テキストのサイズ変更、色の変更、または様々な背景でテキストを表示する場合に、シャー
プネス、太さ、アンチエイリアスなどのテキスト表示制御の設定がデフォルトで決定されます。非常に小さなテキスト、非常に大きなテキスト、様々な独自の背景を使用するテキストを使用する場合など、これらの設定を制御したい場合があります。flash.text.TextRenderer クラスとその関連クラス（CSMSettings クラスなど）を使用して、Flash Player または AIR の設定をオーバーライドすることができます。これらのクラスにより、埋め込みテキストのレンダリング品質を正確に制御することができます。埋め込みフォントについて詳しくは、365 ページの「埋め込みフォントの使用」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

367

TextField クラスの使用

注意：シャープネス、太さ、または gridFitType プロパティを設定する場合、または

TextRenderer.setAdvancedAntiAliasingTable() メソッドを使用する場合は、flash.text.TextField.antiAliasType プロパティの値が AntiAliasType.ADVANCED である必要があります。
次の例では、myFont という名前の埋め込みフォントを使用している表示テキストに、カスタム CSM（Continuous Stroke

Modulation）プロパティとフォーマットを適用します。ユーザーが表示テキストをクリックすると、カスタム設定が Flash
Player または Adobe AIR によって適用されます。
var format:TextFormat = new TextFormat();format.color = 0x336699;
format.size = 48;
format.font = "myFont";
var myText:TextField = new TextField();
myText.embedFonts = true;
myText.autoSize = TextFieldAutoSize.LEFT;
myText.antiAliasType = AntiAliasType.ADVANCED;
myText.defaultTextFormat = format;
myText.selectable = false;
myText.mouseEnabled = true;
myText.text = "Hello World";
addChild(myText);
myText.addEventListener(MouseEvent.CLICK, clickHandler);function clickHandler(event:Event):void{
var myAntiAliasSettings = new CSMSettings(48, 0.8, -0.8);
var myAliasTable:Array = new Array(myAntiAliasSettings);
TextRenderer.setAdvancedAntiAliasingTable("myFont", FontStyle.ITALIC, TextColorType.DARK_COLOR,
myAliasTable);}

静止テキストの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
静止テキストは、Flash Professional でのみ作成できます。ActionScript を使用して、プログラムによって静止テキストをインスタンス化することはできません。静止テキストは、テキストが短く、（ダイナミックテキストと異なり）変更が意図されない場合に便利です。Flash Professional のステージで描画された円または四角形のようなグラフィックエレメントとしての静止テキストについて考えてください。静止テキストにはダイナミックテキストよりも大きな制約がありますが、ActionScript 3.0 は StaticText クラスを使用して、静止テキストのプロパティ値を読み取る機能をサポートします。さらに、TextSnapshot クラスを使用して静止テキスト外の値を読み取ることもできます。

StaticText クラスによる静止テキストフィールドへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
ステージ上に配置された静止テキストインスタンスを操作するには、通常は Flash Professional のアクションパネルでflash.text.StaticText クラスを使用します。静止テキストを含む SWF ファイルとやり取りする ActionScript ファイルを操作することもできます。いずれの場合も、プログラムを通じて静止テキストインスタンスをインスタンス化することはできません。静止テキストは、Flash Professional で作成できます。
既存の静止テキストフィールドへの参照を作成するには、表示リスト内のアイテムに対して反復処理を行い、変数を割り当てます。次に、例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

368

TextField クラスの使用

for (var i = 0; i < this.numChildren; i++) {var displayitem:DisplayObject = this.getChildAt(i);if (displayitem instanceof StaticText) {trace("a static text field is item " + i + " on the display list");var myFieldLabel:StaticText = StaticText(displayitem);
trace("and contains the text: " + myFieldLabel.text);}}

静止テキストフィールドへの参照が設定されたら、ActionScript 3.0 でそのフィールドのプロパティを使用できます。次のコードは、タイムラインのフレームにアタッチされ、myFieldLabel という名前の変数が静止テキスト参照に割り当てられることを想定しています。myField という名前のダイナミックテキストフィールドは、myFieldLabel の値 x と y を基準として配置され、myFieldLabel の値を再び表示します。
var myField:TextField = new TextField();
addChild(myField);
myField.x = myFieldLabel.x;
myField.y = myFieldLabel.y + 20;
myField.autoSize = TextFieldAutoSize.LEFT;
myField.text = "and " + myFieldLabel.text

TextSnapshot クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
既存の静止テキストインスタンスをプログラムで操作する必要がある場合は、flash.text.TextSnapshot クラスを使用して、flash.display.DisplayObjectContainer の textSnapshot プロパティを操作します。これは、DisplayObjectContainer.textSnapshot プロパティから TextSnapshot インスタンスを作成することになります。次に、このインスタンスにメソッドを適用して、値を取得するか、静止テキストの部分を選択することができます。
例えば、テキスト "TextSnapshot Example" を含む静止テキストフィールドをステージ上に配置することができます。次のActionScript をタイムラインのフレーム 1 に追加します。
var mySnap:TextSnapshot = this.textSnapshot;
var count:Number = mySnap.charCount;
mySnap.setSelected(0, 4, true);
mySnap.setSelected(1, 2, false);
var myText:String = mySnap.getSelectedText(false);
trace(myText);

TextSnapshot クラスは、テキストをアプリケーションの別の部分の値として使用する場合に、ロードされた SWF の静止
テキストフィールドからテキストを取得するときに便利です。

TextField の例：新聞形式のテキストフォーマット
Flash Player 9 以降、Adobe AIR 1.0 以降
ここで示す News Layout という例では、紙面版の新聞の記事と同様に見えるようにテキストをフォーマットします。入力テキストには記事のヘッドライン、サブタイトル、および本文を含めることができます。この News Layout という例は、表示領域の幅と高さが指定されると、表示領域の幅いっぱいに表示されるようにヘッドラインとサブタイトルをフォーマットします。記事の本文テキストは 2 段組みまたは 3 段組みで配置されます。
この例では、ActionScript の以下のプログラミング手法について説明します。

• TextField クラスの拡張•

外部 CSS ファイルのロードと適用

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

369

TextField クラスの使用• CSS スタイルから TextFormat オブジェクトへの変換• TextLineMetrics クラスによるテキスト表示サイズ情報の取得
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。News Layout アプリケーションのファイルは、Samples/NewsLayout フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

NewsLayout.mxml

アプリケーションのユーザーインターフェイスです（Flex 用の MXML、または Flash 用の FLA）。

またはNewsLayout.fla
com/example/programmingas3/n StoryLayout インスタンスを配置する Flex UIComponent クラスです。
ewslayout/StoryLayoutComponent.ascom/example/programmingas3/n
ewslayout/StoryLayout.as

ニュース記事のすべてのコンポーネントを表示用に配置する、メインの ActionScript クラスです。

com/example/programmingas3/n
ewslayout/FormattedTextField.as

TextField クラスのサブクラスであり、それ自体の TextFormat オブジェクトを管理します。

com/example/programmingas3/n
ewslayout/HeadlineTextField.as

FormattedTextField クラスのサブクラスであり、適切な幅に合わせてフォントサイズを調整します。

com/example/programmingas3/n
ewslayout/MultiColumnTextField.
as

テキストを複数の段に分割する ActionScript クラスです。

story.css

レイアウトのテキストスタイルが定義されている CSS ファイルです。

外部 CSS ファイルの読み取り
Flash Player 9 以降、Adobe AIR 1.0 以降
News Layout アプリケーションは、最初にローカル XML ファイルから記事のテキストを読み取ります。次に、ヘッドライ
ン、サブタイトル、および本文テキストのフォーマット情報が含まれている外部 CSS ファイルを読み取ります。

CSS ファイルには 3 つのスタイルが定義されています。記事本文用の標準段落スタイル、およびヘッドラインとサブタイト
ルにそれぞれ対応する h1 スタイルと h2 スタイルです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

370

TextField クラスの使用

p {font-family: Georgia, "Times New Roman", Times, _serif;
font-size: 12;
leading: 2;
text-align: justify;
indent: 24;}
h1 {font-family: Verdana, Arial, Helvetica, _sans;font-size: 20;
font-weight: bold;color: #000099;
text-align: left;}h2 {font-family: Verdana, Arial, Helvetica, _sans;font-size: 16;
font-weight: normal;
text-align: left;}

外部 CSS ファイルの読み取りに使用される手法は、363 ページの「外部 CSS ファイルのロード」で説明している手法と同じです。CSS ファイルのロードが完了すると、アプリケーションでは、次に示す onCSSFileLoaded() メソッドが実行されます。
public function onCSSFileLoaded(event:Event):void{
this.sheet = new StyleSheet();this.sheet.parseCSS(loader.data);h1Format = getTextStyle("h1", this.sheet);if (h1Format == null){
h1Format = getDefaultHeadFormat();}h2Format = getTextStyle("h2", this.sheet);if (h2Format == null){
h2Format = getDefaultHeadFormat();h2Format.size = 16;}
pFormat = getTextStyle("p", this.sheet);if (pFormat == null){pFormat = getDefaultTextFormat();pFormat.size = 12;}
displayText();}

onCSSFileLoaded() メソッドによって新しい StyleSheet オブジェクトが作成され、そのオブジェクトを使用して入力 CSS
データが解析されます。記事の本文テキストは MultiColumnTextField オブジェクトに表示されます。このオブジェクト
では StyleSheet オブジェクトを直接使用できます。一方、ヘッドラインフィールドには HeadlineTextField クラスが使用されます。このクラスではフォーマットに TextFormat オブジェクトを使用します。
onCSSFileLoaded() メソッドは、getTextStyle() メソッドを 2 回呼び出して CSS スタイル宣言を TextFormat オブジェクトに変換し、2 つの HeadlineTextField オブジェクトのそれぞれで TextFormat オブジェクトを使用できるようにします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

371

TextField クラスの使用

public function getTextStyle(styleName:String, ss:StyleSheet):TextFormat{
var format:TextFormat = null;var style:Object = ss.getStyle(styleName);if (style != null){var colorStr:String = style.color;
if (colorStr != null && colorStr.indexOf("#") == 0){style.color = colorStr.substr(1);}format = new TextFormat(style.fontFamily,
style.fontSize,style.color,(style.fontWeight == "bold"),(style.fontStyle == "italic"),(style.textDecoration == "underline"),style.url,
style.target,
style.textAlign,
style.marginLeft,
style.marginRight,
style.indent,
style.leading);
if (style.hasOwnProperty("letterSpacing")){
format.letterSpacing = style.letterSpacing;}}
return format;}

プロパティ名とプロパティ値の意味は、CSS スタイル宣言と TextFormat オブジェクトでは異なります。getTextStyle() メ
ソッドは、CSS のプロパティ値を、TextFormat オブジェクトで想定されている値に変換します。

ページへの記事要素の配置
Flash Player 9 以降、Adobe AIR 1.0 以降
StoryLayout クラスでは、ヘッドライン、サブタイトル、および本文テキストのフィールドが、フォーマットされ、レイアウトされて、新聞形式で配置されます。まず、displayText() メソッドによって各フィールドが作成され、配置されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

372

TextField クラスの使用

public function displayText():void{
headlineTxt = new HeadlineTextField(h1Format);headlineTxt.wordWrap = true;
headlineTxt.x = this.paddingLeft;headlineTxt.y = this.paddingTop;
headlineTxt.width = this.preferredWidth;
this.addChild(headlineTxt);
headlineTxt.fitText(this.headline, 1, true);
subtitleTxt = new HeadlineTextField(h2Format);subtitleTxt.wordWrap = true;
subtitleTxt.x = this.paddingLeft;subtitleTxt.y = headlineTxt.y + headlineTxt.height;
subtitleTxt.width = this.preferredWidth;
this.addChild(subtitleTxt);
subtitleTxt.fitText(this.subtitle, 2, false);
storyTxt = new MultiColumnText(this.numColumns, 20,
this.preferredWidth, 400, true, this.pFormat);storyTxt.x = this.paddingLeft;
storyTxt.y = subtitleTxt.y + subtitleTxt.height + 10;
this.addChild(storyTxt);
storyTxt.text = this.content;...

各フィールドはその直前のフィールドの下に配置されます。このように配置するため、各フィールドの y プロパティは、直前のフィールドの y プロパティにその高さを加えた値と等しくなるように設定されます。このような動的配置のための計算が必要になるのは、HeadlineTextField オブジェクトと MultiColumnTextField オブジェクトの高さが、それぞれのコン
テンツに合わせて変化するためです。

フィールドサイズに合わせるためのフォントサイズ変更
Flash Player 9 以降、Adobe AIR 1.0 以降
HeadlineTextField では、幅（ピクセル単位）と最大表示行数が指定されると、テキストがフィールドいっぱいに表示されるようにフォントサイズが変更されます。テキストが短い場合には、フォントサイズが非常に大きくなり、タブロイドスタ
イルのヘッドラインが作成されます。テキストが長い場合は、フォントサイズは小さくなります。
次に示す HeadlineTextField.fitText() メソッドで、フォントサイズの変更処理が実行されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

373

TextField クラスの使用

public function fitText(msg:String, maxLines:uint = 1, toUpper:Boolean = false, targetWidth:Number = 1):uint{
this.text = toUpper ? msg.toUpperCase() : msg;
if (targetWidth == -1){
targetWidth = this.width;}
var pixelsPerChar:Number = targetWidth / msg.length;
var pointSize:Number = Math.min(MAX_POINT_SIZE, Math.round(pixelsPerChar * 1.8 * maxLines));if (pointSize < 6){// the point size is too small
return pointSize;}
this.changeSize(pointSize);if (this.numLines > maxLines){
return shrinkText(--pointSize, maxLines);}
else{
return growText(pointSize, maxLines);}}
public function growText(pointSize:Number, maxLines:uint = 1):Number{
if (pointSize >= MAX_POINT_SIZE){
return pointSize;}
this.changeSize(pointSize + 1);
if (this.numLines > maxLines){// set it back to the last size
this.changeSize(pointSize);
return pointSize;}
else{
return growText(pointSize + 1, maxLines);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

374

TextField クラスの使用}
public function shrinkText(pointSize:Number, maxLines:uint=1):Number{
if (pointSize <= MIN_POINT_SIZE){
return pointSize;}
this.changeSize(pointSize);if (this.numLines > maxLines){
return shrinkText(pointSize - 1, maxLines);}
else{
return pointSize;}}

HeadlineTextField.fitText() メソッドでは、単純な再帰的手法によってフォントサイズが変更されます。最初にテキストの 1
文字あたりの平均ピクセル数が推定され、それに基づいて開始ポイントサイズが算出されます。次に、フォントサイズが変更されます。その後、テキストが折り返されたされたためにテキスト行の最大数を超えて行が生成されていないかどうかが確認されます。行数が多すぎる場合には、shrinkText() メソッドが呼び出されて、フォントサイズを小さくする操作が何回か試行されます。最大行数を超えていない場合には、growText() メソッドが呼び出されて、フォントサイズを大きくする操作が何回か試行されます。フォントサイズを現在の値よりも 1 ポイント大きくすると最大行数を超えるような状態に達したときに、処理が終了します。

複数の段へのテキストの分割
Flash Player 9 以降、Adobe AIR 1.0 以降
MultiColumnTextField クラスは、複数の TextField オブジェクトにテキストを配分します。これらのオブジェクトは、後で新聞の段組みのように配置されます。
まず、MultiColumnTextField() コンストラクターによって、次のように TextField オブジェクトの配列が作成されます。1
つのオブジェクトが 1 つの段に対応します。
for (var i:int = 0; i < cols; i++){var field:TextField = new TextField();
field.multiline = true;
field.autoSize = TextFieldAutoSize.NONE;
field.wordWrap = true;
field.width = this.colWidth;field.setTextFormat(this.format);this.fieldArray.push(field);this.addChild(field);}

各 TextField オブジェクトは配列に追加され、さらに addChild() メソッドによって表示リストに追加されます。

StoryLayout オブジェクトの text プロパティまたは styleSheet プロパティが変更されると、layoutColumns() メソッドが呼び出されて、テキストが再表示されます。layoutColumns() メソッドは、次に示す getOptimalHeight() メソッドを呼び出して、指定されたレイアウト幅に合わせてすべてのテキストを配置するために必要な高さを正確にピクセル単位で算出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

375

TextField クラスの使用

public function getOptimalHeight(str:String):int{
if (field.text == "" || field.text == null){
return this.preferredHeight;}
else{
this.linesPerCol = Math.ceil(field.numLines / this.numColumns);
var metrics:TextLineMetrics = field.getLineMetrics(0);this.lineHeight = metrics.height;
var prefHeight:int = linesPerCol * this.lineHeight;
return prefHeight + 4;}}

getOptimalHeight() メソッドでは、まず各段の幅が計算されます。次に、配列の最初の TextField オブジェクトの幅とhtmlText プロパティが設定されます。getOptimalHeight() メソッドでは、この最初の TextField オブジェクトを使用してテキストの折り返された総行数を調べ、その総行数に基づいて、各段に配分する行数を特定します。続いて、最初の行のテキ
ストのサイズの詳細情報を含む TextLineMetrics オブジェクトを取得するために、TextField.getLineMetrics() メソッドが呼び出されます。TextLineMetrics.height プロパティは、アセント、ディセント、および行送りを含めたテキスト行全体の高さを表します（ピクセル単位）。MultiColumnTextField オブジェクトの最適な高さは、この行全体の高さと 1 段の行数を乗算し、さらに 4 ピクセルを加算したものになります。この 4 ピクセルは、TextField オブジェクトの上下それぞれに設ける 2ピクセルの境界の分です。
layoutColumns() メソッド全体のコードを次に示します。
public function layoutColumns():void{if (this._text == "" || this._text == null){
return;}var field:TextField = fieldArray[0] as TextField;
field.text = this._text;
field.setTextFormat(this.format);this.preferredHeight = this.getOptimalHeight(field);var remainder:String = this._text;
var fieldText:String = "";var lastLineEndedPara:Boolean = true;var indent:Number = this.format.indent as Number;for (var i:int = 0; i < fieldArray.length; i++){field = this.fieldArray[i] as TextField;
field.height = this.preferredHeight;
field.text = remainder;
field.setTextFormat(this.format);var lineLen:int;
if (indent > 0 && !lastLineEndedPara && field.numLines > 0){lineLen = field.getLineLength(0);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

376

TextField クラスの使用

if (lineLen > 0){
field.setTextFormat(this.firstLineFormat, 0, lineLen);}}
field.x = i * (colWidth + gutter);field.y = 0;
remainder = "";fieldText = "";var linesRemaining:int = field.numLines;
var linesVisible:int = Math.min(this.linesPerCol, linesRemaining);for (var j:int = 0; j < linesRemaining; j++){
if (j < linesVisible){
fieldText += field.getLineText(j);}else{remainder +=field.getLineText(j);}}field.text = fieldText;
field.setTextFormat(this.format);if (indent > 0 && !lastLineEndedPara){lineLen = field.getLineLength(0);if (lineLen > 0){
field.setTextFormat(this.firstLineFormat, 0, lineLen);}}var lastLine:String = field.getLineText(field.numLines - 1);
var lastCharCode:Number = lastLine.charCodeAt(lastLine.length - 1);
if (lastCharCode == 10 || lastCharCode == 13){
lastLineEndedPara = true;}
else{
lastLineEndedPara = false;}if ((this.format.align == TextFormatAlign.JUSTIFY) &&(i < fieldArray.length - 1)){
if (!lastLineEndedPara){justifyLastLine(field, lastLine);}}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

377

TextField クラスの使用

getOptimalHeight() メソッドの呼び出しによって preferredHeight プロパティが設定された後、layoutColumns() メソッドでは
TextField オブジェクトが反復処理され、各オブジェクトの高さには preferredHeight の値が設定されます。続いて、
layoutColumns() メソッドによって、各フィールドにちょうど収まる行数のテキストが配分されます。このとき、個々のフィールドでスクロールが発生することがなく、また、各後続フィールドのテキストは直前のフィールドでテキストが終わった箇所から始まるように配分されます。テキストの整列のスタイルが “ ジャスティファイ ” に設定されている場合は、
justifyLastLine() メソッドが呼び出され、フィールド内のテキストの最後の行がジャスティファイされます。それ以外の場合
は、最後の行は段落の終わりの行として扱われ、ジャスティファイされません。

最終更新日 2015/10/14

378

第 22 章：Flash Text Engine の使用
Flash Player 10 以降、Adobe AIR 1.5 以降
Flash Player 10 および Adobe® AIR™1.5 以降で使用可能な Adobe® Flash® Text Engine（FTE）は、テキストメトリック、
フォーマットおよび双方向テキストの高度な制御の低レベルのサポートを提供します。改善されたテキストフローと強化された言語サポートを提供します。FTE は単純なテキストエレメントの作成および管理に使用できますが、FTE は主に開発者がテキスト処理コンポーネントを作成するための基盤として設計されています。そのため、Flash Text Engine ではプログ
ラミングに関するより高度な専門知識が必要になります。単純なテキストエレメントを表示する方法については、354 ページの「TextField クラスの使用」を参照してください。

Text Layout Framework には FTE に基づいたテキスト処理コンポーネントが含まれており、高度な機能を容易に使用することができます。Text Layout Framework は、すべて ActionScript 3.0 で作成されている拡張可能なライブラリです。既
存の TLF コンポーネントを使用できますが、このフレームワークを使用して独自のテキストコンポーネントを作成することも可能です。詳しくは、406 ページの「Text Layout Framework の使用」を参照してください。
関連項目

flash.text.engine パッケージ

テキストの作成と表示Flash Player 10 以降、Adobe AIR 1.5 以降
Flash Text Engine を構成するクラスにより、テキストの作成、フォーマット、および制御が可能になります。次のクラス
は、Flash Text Engine でのテキストの作成と表示のための基本的な構成要素です。

• TextElement/GraphicElement/GroupElement - TextBlock インスタンスのコンテンツが格納されています。
• ElementFormat - TextBlock インスタンスのコンテンツのフォーマット属性を指定します。
• TextBlock - テキストの段落を構築するためのファクトリです。
• TextLine - TextBlock から作成したテキストの行です。
テキストを表示するには、ElementFormat オブジェクトを使用してフォーマット特性を指定して、String から

TextElement オブジェクトを作成します。TextElement を TextBlock オブジェクトの content プロパティに割り当てます。
TextBlock.createTextLine() メソッドを呼び出して、表示するテキストの行を作成します。createTextLine() メソッドは、指定された幅に収まるだけの文字列を含む TextLine オブジェクトを返します。文字列全体が行にフォーマットされるまで、このメソッドを繰り返し呼び出します。作成する行がなくなると、TextBlock オブジェクトの textLineCreationResult プロ
パティが値 TextLineCreationResult.COMPLETE に割り当てられます。行を表示するには、行を（位置を示す適切な x 値および y 値を指定して）表示リストに追加します。
例えば、次のコードではこれらの FTE クラスを使用して、形式およびフォントのデフォルト値で「Hello World! This isFlash Text Engine!」を表示します。この単純な例で作成されるのは、わずか 1 行のテキストです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

379

Flash Text Engine の使用

package{import flash.text.engine.*;import flash.display.Sprite;
public class HelloWorldExample extends Sprite{
public function HelloWorldExample(){var str = "Hello World! This is Flash Text Engine!";var format:ElementFormat = new ElementFormat();var textElement:TextElement = new TextElement(str, format);var textBlock:TextBlock = new TextBlock();
textBlock.content = textElement;
var textLine1:TextLine = textBlock.createTextLine(null, 300);
addChild(textLine1);
textLine1.x = 30;
textLine1.y = 30;}}}

createTextLine() のパラメーターは、新しい行を開始する行および行の幅（ピクセル単位）を指定します。新しい行を開始す
る行は、通常は前の行ですが、最初の行の場合、この値は null になります。

GraphicElement オブジェクトと GroupElement オブジェクトの追加
Flash Player 10 以降、Adobe AIR 1.5 以降
GraphicElement オブジェクトを TextBlock オブジェクトに割り当てると、イメージまたはグラフィックエレメントを表示することができます。グラフィックまたはイメージから GraphicElement クラスのインスタンスを作成し、それをTextBlock.content プロパティに割り当てるだけです。通常どおりに TextBlock.createTextline() を呼び出してテキスト行を作成します。次の例では、2 つのテキスト行を作成します。一方のテキスト行には GraphicElement オブジェクトが含まれ、他方には TextElement オブジェクトが含まれます。
package{import flash.text.engine.*;import flash.display.Sprite;
import flash.display.Shape;
import flash.display.Graphics;
public class GraphicElementExample extends Sprite{
public function GraphicElementExample(){var str:String = "Beware of Dog!";var triangle:Shape = new Shape();triangle.graphics.beginFill(0xFF0000, 1);
triangle.graphics.lineStyle(3);triangle.graphics.moveTo(30, 0);
triangle.graphics.lineTo(60, 50);
triangle.graphics.lineTo(0, 50);
triangle.graphics.lineTo(30, 0);
triangle.graphics.endFill();var format:ElementFormat = new ElementFormat();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

380

Flash Text Engine の使用

format.fontSize = 20;
var graphicElement:GraphicElement = new GraphicElement(triangle, triangle.width,
triangle.height, format);var textBlock:TextBlock = new TextBlock();
textBlock.content = graphicElement;
var textLine1:TextLine = textBlock.createTextLine(null, triangle.width);
textLine1.x = 50;
textLine1.y = 110;addChild(textLine1);
var textElement:TextElement = new TextElement(str, format);textBlock.content = textElement;
var textLine2 = textBlock.createTextLine(null, 300);
addChild(textLine2);
textLine2.x = textLine1.x - 30;
textLine2.y = textLine1.y + 15;}}}

GroupElement オブジェクトを作成して、TextElement、GraphicElement およびその他の GroupElement オブジェクトのグループを作成できます。GroupElement は、TextBlock オブジェクトの content プロパティに割り当てることができます。GroupElement() コンストラクターのパラメーターは Vector です。Vector はグループを構成するテキスト、グラフィッ
ク、およびグループエレメントを参照します。次の例では、2 つのグラフィックエレメントおよびテキストエレメントをグ
ループにまとめ、それらを 1 つの単位としてテキストブロックに割り当てます。
package{import flash.text.engine.*;import flash.display.Sprite;
import flash.display.Shape;
import flash.display.Graphics;
public class GroupElementExample extends Sprite{
public function GroupElementExample(){var str:String = "Beware of Alligators!";
var triangle1:Shape = new Shape();triangle1.graphics.beginFill(0xFF0000, 1);
triangle1.graphics.lineStyle(3);triangle1.graphics.moveTo(30, 0);
triangle1.graphics.lineTo(60, 50);
triangle1.graphics.lineTo(0, 50);
triangle1.graphics.lineTo(30, 0);
triangle1.graphics.endFill();var triangle2:Shape = new Shape();triangle2.graphics.beginFill(0xFF0000, 1);
triangle2.graphics.lineStyle(3);triangle2.graphics.moveTo(30, 0);
triangle2.graphics.lineTo(60, 50);
triangle2.graphics.lineTo(0, 50);
triangle2.graphics.lineTo(30, 0);
triangle2.graphics.endFill();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

381

Flash Text Engine の使用

var format:ElementFormat = new ElementFormat();format.fontSize = 20;
var graphicElement1:GraphicElement = new GraphicElement(triangle1, triangle1.width,
triangle1.height, format);var textElement:TextElement = new TextElement(str, format);var graphicElement2:GraphicElement = new GraphicElement(triangle2, triangle2.width,
triangle2.height, format);var groupVector:Vector.<ContentElement> = new Vector.<ContentElement>();groupVector.push(graphicElement1, textElement, graphicElement2);
var groupElement = new GroupElement(groupVector);
var textBlock:TextBlock = new TextBlock();
textBlock.content = groupElement;
var textLine:TextLine = textBlock.createTextLine(null, 800);
addChild(textLine);
textLine.x = 100;
textLine.y = 200;}}}

テキストの置換Flash Player 10 以降、Adobe AIR 1.5 以降
TextElement.replaceText() を呼び出して、TextBlock.content プロパティに割り当てた TextElement 内のテキストを置換する
ことにより、TextBlock インスタンスのテキストを置換できます。
次の例では、repaceText() を使用して、行の先頭にテキストを挿入した後、行末にテキストを追加し、最後に行の中央のテキストを置換します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

382

Flash Text Engine の使用

package{import flash.text.engine.*;import flash.display.Sprite;
public class ReplaceTextExample extends Sprite{
public function ReplaceTextExample(){var str:String = "Lorem ipsum dolor sit amet";
var fontDescription:FontDescription = new FontDescription("Arial");var format:ElementFormat = new ElementFormat(fontDescription);format.fontSize = 14;
var textElement:TextElement = new TextElement(str, format);var textBlock:TextBlock = new TextBlock();
textBlock.content = textElement;
createLine(textBlock, 10);textElement.replaceText(0, 0, "A text fragment: ");createLine(textBlock, 30);
textElement.replaceText(43, 43, "...");
createLine(textBlock, 50);
textElement.replaceText(23, 28, "(ipsum)");createLine(textBlock, 70);}
function createLine(textBlock:TextBlock, y:Number):void {var textLine:TextLine = textBlock.createTextLine(null, 300);
textLine.x = 10;
textLine.y = y;
addChild(textLine);}}}

replaceText() メソッドは、beginIndex パラメーターおよび endIndex パラメーターによって指定されたテキストを newText パ
ラメーターによって指定されたテキストで置換します。beginIndex パラメーターと endIndex パラメーターの値が同じである
場合は、replaceText() はその位置に指定されたテキストを挿入します。それ以外の場合は、beginIndex および endIndex によって指定された文字を新しいテキストで置換します。

FTE でのイベントの処理
Flash Player 10 以降、Adobe AIR 1.5 以降
TextLine インスタンスには、他の表示オブジェクトと同様に、イベントリスナーを追加できます。例えば、テキスト行上へのマウスの移動や、行のクリックを検知できます。次の例では、これら両方のイベントを検知します。マウスを行の上に移動すると、カーソルはボタンカーソルに変わり、行をクリックするとその色が変わります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

383

Flash Text Engine の使用

package{import flash.text.engine.*;import flash.ui.Mouse;
import flash.display.Sprite
import flash.events.MouseEvent;import flash.events.EventDispatcher;public class EventHandlerExample extends Sprite{
var textBlock:TextBlock = new TextBlock();
public function EventHandlerExample():void{
var str:String = "I'll change color if you click me.";var fontDescription:FontDescription = new FontDescription("Arial");var format:ElementFormat = new ElementFormat(fontDescription, 18);
var textElement = new TextElement(str, format);textBlock.content = textElement;
createLine(textBlock);}
private function createLine(textBlock:TextBlock):void{
var textLine:TextLine = textBlock.createTextLine(null, 500);
textLine.x = 30;
textLine.y = 30;
addChild(textLine);
textLine.addEventListener("mouseOut", mouseOutHandler);textLine.addEventListener("mouseOver", mouseOverHandler);textLine.addEventListener("click", clickHandler);}private function mouseOverHandler(event:MouseEvent):void{
Mouse.cursor = "button";}
private function mouseOutHandler(event:MouseEvent):void{
Mouse.cursor = "arrow";}function clickHandler(event:MouseEvent):void {if(textBlock.firstLine)removeChild(textBlock.firstLine);
var newFormat:ElementFormat = textBlock.content.elementFormat.clone();最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

384

Flash Text Engine の使用

switch(newFormat.color){case 0x000000:
newFormat.color = 0xFF0000;
break;
case 0xFF0000:
newFormat.color = 0x00FF00;
break;
case 0x00FF00:
newFormat.color = 0x0000FF;
break;
case 0x0000FF:
newFormat.color = 0x000000;
break;}
textBlock.content.elementFormat = newFormat;
createLine(textBlock);}}}

イベントのミラーリング
Flash Player 10 以降、Adobe AIR 1.5 以降
さらに、テキストブロック、テキストブロックの一部のイベントをイベントディスパッチャにミラーリングすることもできます。まず、EventDispatcher インスタンスを作成してから、TextElement インスタンスの eventMirror プロパティにそれを割り当てます。テキスト ブロックが単一のテキストエレメントで構成される場合は、Text Engine はテキストブロック全体のイベントをミラーリングします。テキスト ブロックが複数のテキストエレメントで構成される場合は、Text Engine はeventMirror プロパティが設定されている TextElement インスタンスに対してのみイベントをミラーリングします。次の例のテキストは、「Click」および「here」という単語と、「to see me in italic」という文字列の 3 つのエレメントで構成されます。この例では、イベントディスパッチャを 2 番目のテキストエレメントである「here」という単語に割り当て、イベント
リスナー clickHandler() メソッドを追加します。clickHandler() メソッドは、テキストをイタリックに変更します。さらに、3番目のテキストエレメントのコンテンツが「Click here to see me in normal font!」となるように置き換えます。
package{import flash.text.engine.*;import flash.ui.Mouse;
import flash.display.Sprite;
import flash.events.MouseEvent;import flash.events.EventDispatcher;public class EventMirrorExample extends Sprite{
var fontDescription:FontDescription = new FontDescription("Helvetica", "bold");
var format:ElementFormat = new ElementFormat(fontDescription, 18);
var textElement1 = new TextElement("Click ", format);var textElement2 = new TextElement("here ", format);var textElement3 = new TextElement("to see me in italic! ", format);var textBlock:TextBlock = new TextBlock();
public function EventMirrorExample(){var myEvent:EventDispatcher = new EventDispatcher();myEvent.addEventListener("click", clickHandler);
myEvent.addEventListener("mouseOut", mouseOutHandler);
myEvent.addEventListener("mouseOver", mouseOverHandler);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

385

Flash Text Engine の使用

textElement2.eventMirror=myEvent;var groupVector:Vector.<ContentElement> = new Vector.<ContentElement>;groupVector.push(textElement1, textElement2, textElement3);
var groupElement:GroupElement = new GroupElement(groupVector);
textBlock.content = groupElement;
createLines(textBlock);}
private function clickHandler(event:MouseEvent):void{
var newFont:FontDescription = new FontDescription();newFont.fontWeight = "bold";var newFormat:ElementFormat = new ElementFormat();newFormat.fontSize = 18;
if(textElement3.text == "to see me in italic! ") {newFont.fontPosture = FontPosture.ITALIC;
textElement3.replaceText(0,21, "to see me in normal font! ");}else {
newFont.fontPosture = FontPosture.NORMAL;
textElement3.replaceText(0, 26, "to see me in italic! ");}newFormat.fontDescription = newFont;
textElement1.elementFormat = newFormat;
textElement2.elementFormat = newFormat;
textElement3.elementFormat = newFormat;
createLines(textBlock);}
private function mouseOverHandler(event:MouseEvent):void{
Mouse.cursor = "button";}
private function mouseOutHandler(event:MouseEvent):void{
Mouse.cursor = "arrow";}
private function createLines(textBlock:TextBlock):void{if(textBlock.firstLine)removeChild (textBlock.firstLine);
var textLine:TextLine = textBlock.createTextLine (null, 300);
textLine.x = 15;
textLine.y = 20;
addChild (textLine);}}}mouseOverHandler() 関数と mouseOutHandler() 関数は、カーソルが「here」という単語の上にあるときはボタンカーソルに、それ以外の場合は矢印に戻るように設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

386

Flash Text Engine の使用

テキストのフォーマット
Flash Player 10 以降、Adobe AIR 1.5 以降
TextBlock オブジェクトは、テキスト行を作成するファクトリです。TextBlock のコンテンツは TextElement オブジェクトを使用して割り当てます。ElementFormat オブジェクトは、テキストのフォーマットを処理します。ElementFormat クラス
は、ベースライン整列、カーニング、トラッキング、テキスト回転、フォントサイズ、カラーおよび大文字小文字などのプ
ロパティを定義します。これには、FontDescription も含まれます。このプロパティについては、389 ページの「フォントの操作」で詳しく説明しています。

ElementFormat オブジェクトの使用
Flash Player 10 以降、Adobe AIR 1.5 以降
ElementFormat オブジェクトのコンストラクターは、FontDescription を含む、多数あるオプションのパラメーターを取ります。また、コンストラクターの外でこれらのプロパティを設定することもできます。次の例は、単純なテキスト行の定義と表示における様々なオブジェクトの関係を示しています。
package{import flash.display.Sprite;
import flash.text.*;
public class ElementFormatExample extends Sprite{
private var tb:TextBlock = new TextBlock();
private var te:TextElement;
private var ef:ElementFormat;
private var fd:FontDescription = new FontDescription();private var str:String;private var tl:TextLine;public function ElementFormatExample(){fd.fontName = "Garamond";
ef = new ElementFormat(fd);ef.fontSize = 30;
ef.color = 0xFF0000;
str = "This is flash text";
te = new TextElement(str, ef);tb.content = te;tl = tb.createTextLine(null,600);
addChild(tl);}}}フォントカラーと透明度（アルファ）Flash Player 10 以降、Adobe AIR 1.5 以降
ElementFormat オブジェクトの color プロパティはフォントカラーを設定します。値はカラーの RGB コンポーネントを表す
整数です。例えば、赤の場合は 0xFF0000、緑の場合は 0x00FF00 です。デフォルト値は黒（0x000000）です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

387

Flash Text Engine の使用

alpha プロパティは、エレメント（TextElement と GraphicElement の両方）のアルファ透明度の値を設定します。値はの範囲
は 0（完全に透明）から 1（完全に不透明 ) です。デフォルトは 1 です。alpha が 0 のエレメントは表示されませんが、アクティブです。この値は、継承された任意のアルファ値で乗算できるので、エレメントの透明度が増します。
var ef:ElementFormat = new ElementFormat();ef.alpha = 0.8;
ef.color = 0x999999;

ベースライン整列およびシフト
Flash Player 10 以降、Adobe AIR 1.5 以降
行内の最大のテキストのフォントとサイズは、優先ベースラインを決定します。これらの値は、

TextBlock.baselineFontDescription および TextBlock.baselineFontSize を設定することにより、オーバーライドできます。優先
ベースラインは、テキスト内の複数のベースラインの 1 つに合わせて整列させることができます。これらのベースラインには、アセントライン、ディセントライン、または仮想ボディの上 / 右、中央、下 / 左が含まれます。
A

D

B

C

A. アセント B. ベースライン C. ディセント D. x の高さ

ElementFormat オブジェクトでは、3 つのプロパティによってベースラインと整列特性が決定されます。alignmentBaseline
プロパティは、TextElement または GraphicElement のメインベースラインを設定します。このベースラインは、エレメント
が「スナップする」行で、すべてのテキストの優先ベースラインはこの位置に合わせて整列します。
dominantBaseline プロパティは、エレメントの様々なベースラインのどれを使用するかを決定し、それにより行上のエレメ
ントの縦の位置が決定されます。デフォルト値は TextBaseline.ROMAN ですが、IDEOGRAPHIC_TOP またはIDEOGRAPHIC_BOTTOM ベースラインのいずれかが優先されるように設定することもできます。
baselineShift プロパティは、ｙ 軸上、一定のピクセル数分ベースラインを移動します。通常（回転なし）のテキストでは、正の値はベースラインを下方向に、負の値はそれを上方向に移動します。

活字の大文字小文字
Flash Player 10 以降、Adobe AIR 1.5 以降
ElementFormat の TypographicCase プロパティは、大文字、小文字、またはスモールキャピタルなど、テキストの大文字小文字の区別を指定します。
var ef_Upper:ElementFormat = new ElementFormat();
ef_Upper.typographicCase = TypographicCase.UPPERCASE;
var ef_SmallCaps:ElementFormat = new ElementFormat();
ef_SmallCaps.typographicCase = TypographicCase.SMALL_CAPS;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

388

Flash Text Engine の使用

テキストの回転Flash Player 10 以降、Adobe AIR 1.5 以降
テキストのブロック、またはテキストのセグメント内の字形を 90 度ずつ回転させることができます。TextRotation クラス
は、テキストブロックまたは字形の回転の設定のために次の定数を定義します。
定数

値

説明

AUTO

“auto”

反時計回りの 90 度の回転を指定します。通常、縦のアジア系テキストで使用し、回転が必要
な字形だけ回転させます。

ROTATE_0“rotate_0”

回転は指定しません。

ROTATE_180“rotate_180”

180 度の回転を指定します。

ROTATE_270“rotate_270”

270 度の回転を指定します。

ROTATE_90“rotate_90”

時計回りの 90 度回転を指定します。

テキストブロック内のテキスト行を回転させるには、テキスト行を作成する TextBlock.createTextLine() メソッドを呼び出す
前に TextBlock.lineRotation プロパティを設定する必要があります。
テキストブロックまたはセグメント内の字形を回転させるには、ElementFormat.textRotation プロパティを文字を回転させる
度数に設定します。字形とは、文字を構成するシェイプ、または複数の字形を構成する文字の一部を指します。例えば「a」
１、および「i」の上部の点は、それぞれ字形です。
字形の回転は、行内の文字は回転せずに、行を縦に回転させる一部のアジア系言語で有意義です。アジア系テキストの回転について詳しくは、393 ページの「東アジア系テキストのジャスティファイ」を参照してください。
次に、アジア系のテキストの場合に、テキストのブロックおよびその中の字形の両方を回転させる例を示します。例では日本語のフォントも使用しています。
package{import flash.display.Sprite;
import flash.text.*;
public class RotationExample extends Sprite{
private var tb:TextBlock = new TextBlock();
private var te:TextElement;
private var ef:ElementFormat;
private var fd:FontDescription = new FontDescription();private var str:String;private var tl:TextLine;public function RotationExample(){fd.fontName = "MS Mincho";ef = new ElementFormat(fd);ef.textRotation = TextRotation.AUTO;
str = "This is rotated Japanese text";
te = new TextElement(str, ef);tb.lineRotation = TextRotation.ROTATE_90;
tb.content = te;tl = tb.createTextLine(null,600);
addChild(tl);}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

389

Flash Text Engine の使用

ElementFormat のロックと複製Flash Player 10 以降、Adobe AIR 1.5 以降
ElementFormat オブジェクトを任意のタイプの ContentElement に割り当てた場合、その locked プロパティは自動的に trueに設定されます。ロックされた ElementFormat オブジェクトを変更しようとすると、IllegalOperationError がスローされます。最善の方法は、TextElement インスタンスに割り当てる前にそのようなオブジェクトを完全に定義することです。
既存の ElementFormat インスタンスを変更する場合は、まずその locked プロパティを確認します。true の場合は、clone() メ
ソッドを使用して、オブジェクトのロックされていないコピーを作成します。このロックされていないオブジェクトのプロ
パティを変更してから、TextElement インスタンスに割り当てることができます。このオブジェクトから作成された新しい行には新しいフォーマットが適用されます。この同じオブジェクトから作成された前の行および古いフォーマットは変更されません。
package{import flash.display.Sprite;
import flash.text.*;
public class ElementFormatCloneExample extends Sprite{
private var tb:TextBlock = new TextBlock();
private var te:TextElement;
private var ef1:ElementFormat;
private var ef2:ElementFormat;
private var fd:FontDescription = new FontDescription();public function ElementFormatCloneExample(){fd.fontName = "Garamond";
ef1 = new ElementFormat(fd);ef1.fontSize = 24;
var str:String = "This is flash text";
te = new TextElement(str, ef);tb.content = te;var tx1:TextLine = tb.createTextLine(null,600);
addChild(tx1);
ef2 = (ef1.locked) ? ef1.clone() : ef1;
ef2.fontSize = 32;
tb.content.elementFormat = ef2;
var tx2:TextLine = tb.createTextLine(null,600);
addChild(tx2);}}}

フォントの操作
Flash Player 10 以降、Adobe AIR 1.5 以降
FontDescription オブジェクトは、ElementFormat と一緒に使用し、フォントを特定し、その特性の一部を定義します。これ
らの特性には、フォント名、太さ、ポスチャー、表現、およびフォントの場所（デバイスか埋め込みか）などがあります。
注意： FTE では、Type 1 のフォントや、Type 3、ATC、sfnt-wrapped CID、Naked CID などのビットマップフォント
はサポートされません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

390

Flash Text Engine の使用

フォント特性の定義（FontDescription オブジェクト）
Flash Player 10 以降、Adobe AIR 1.5 以降
FontDescription オブジェクトの fontName プロパティは、単一の名前またはカンマで区切った名前のリストである場合があります。例えば、「Arial, Helvetica, _sans」のようなリストでは、テキスト エンジンは最初に「Arial」を探し、次に「Helvetica」を探します。どちらも見つからない場合は、最後に「_sans」を探します。フォント名のセットには、「_sans」、「_serif」、および「_typewriter」という 3 つの汎用のデバイスフォント名が含まれています。これらのフォント
は、再生システム固有のデバイスフォントにマップされます。デバイスフォントを使用するすべてのフォントの記述で、これらのようなデフォルト名を指定すると効果的です。fontName が指定されていない場合は、デフォルトとして「_serif」が使用されます。
fontPosture プロパティは、デフォルト（FontPosture.NORMAL）またはイタリック（FontPosture.ITALIC）のいずれかに設定できます。fontWeight プロパティは、デフォルト（FontWeight.NORMAL）またはボールド（FontWeight.BOLD）のいずれかに設定できます。
var fd1:FontDescription = new FontDescription();fd1.fontName = "Arial, Helvetica, _sans";
fd1.fontPosture = FontPosture.NORMAL;
fd1.fontWeight = FontWeight.BOLD;

埋め込みフォントおよびデバイスフォント
Flash Player 10 以降、Adobe AIR 1.5 以降
FontDescription オブジェクトの fontLookup プロパティは、テキスト エンジンが、テキストのレンダリングのために、デバ
イスフォントと埋め込みフォントのどちらを探すかを指定します。デバイスフォント（FontLookup.DEVICE）を指定すると、ランタイムは再生システムでフォントを探します。埋め込みフォント（FontLookup.EMBEDDED_CFF）を指定すると、ランタイムは、SWF ファイルで指定された名前の埋め込みフォントを探します。この設定で使用できるのは埋め込み CFF（コンパクトフォントフォーマット）のみです。指定したフォントが見つからないと、代替のデバイスフォントが使用されます。
デバイスフォントの場合は、SWT ファイルサイズがより小さくなります。埋め込みフォントでは、プラットフォームへの忠実度が高くなります。
var fd1:FontDescription = new FontDescription();fd1.fontLookup = FontLookup.EMBEDDED_CFF;
fd1.fontName = "Garamond, _serif";

レンダリングモードとヒンティング
Flash Player 10 以降、Adobe AIR 1.5 以降
CFF（コンパクトフォントフォーマット）レンダリングは、Flash Player 10 および Adobe AIR 1.5 以降で使用できます。
テキストの読みやすさを向上し、小さいサイズのフォントを優れた品質で表示できるフォントレンダリング形式です。この設定は、埋め込みフォントのみに適用されます。FontDescription の renderingMode プロパティのデフォルト値はこの設定（RenderingMode.CFF）です。このプロパティを RenderingMode.NORMAL に設定すると、Flash Player 7 以前のバージョン
で使用したレンダリングのタイプと一致させることができます。

CFF レンダリングを選択すると、2 番目のプロパティ cffHinting は、フォントの横方向の軸がサブピクセルグリッドに収まる方法を制御します。デフォルト値 CFFHinting.HORIZONTAL_STEM では、CFF ヒンティングを使用します。このプロパ
ティを CFFHinting.NONE に保存すると、ヒンティングが除去されます。これはアニメーションや大きいフォントサイズに適しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

391

Flash Text Engine の使用

var fd1:FontDescription = new FontDescription();fd1.renderingMode = RenderingMode.CFF;
fd1.cffHinting = CFFHinting.HORIZONTAL_STEM;

FontDescription のロックとクローニング
Flash Player 10 以降、Adobe AIR 1.5 以降
FontDescription オブジェクトを ElementFormat に割り当てると、その locked プロパティは自動的に true に設定されます。
ロックされた FontDescription オブジェクトを変更しようとすると、IllegalOperationError がスローされます。最善の方法は、ElementFormat インスタンスに割り当てる前にそのようなオブジェクトを完全に定義することです。
既存の FontDescription インスタンスを変更する場合は、まずその locked プロパティを確認します。true の場合は、clone()
メソッドを使用して、オブジェクトのロックされていないコピーを作成します。このロックされていないオブジェクトのプ
ロパティを変更してから、ElementFormat インスタンスに割り当てることができます。この TextElement から作成された新しい行には新しいフォーマットが適用されます。この同じオブジェクトから作成された前の行は変更されません。
package{import flash.display.Sprite;
import flash.text.*;
public class FontDescriptionCloneExample extends Sprite{
private var tb:TextBlock = new TextBlock();
private var te:TextElement;
private var ef1:ElementFormat;
private var ef2:ElementFormat;
private var fd1:FontDescription = new FontDescription();private var fd2:FontDescription;
public function FontDescriptionCloneExample(){fd1.fontName = "Garamond";
ef1 = new ElementFormat(fd);var str:String = "This is flash text";
te = new TextElement(str, ef);tb.content = te;var tx1:TextLine = tb.createTextLine(null,600);
addChild(tx1);
fd2 = (fd1.locked) ? fd1.clone() : fd1;
fd2.fontName = "Arial";
ef2 = (ef1.locked) ? ef1.clone() : ef1;
ef2.fontDescription = fd2;
tb.content.elementFormat = ef2;
var tx2:TextLine = tb.createTextLine(null,600);
addChild(tx2);}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

392

Flash Text Engine の使用

テキストの制御
Flash Player 10 以降、Adobe AIR 1.5 以降
FTE では、ジャスティファイおよび文字スペース（カーニングおよびトラッキング）を処理する新しい一連のテキスト
フォーマットコントロールが提供されています。さらに改行や行内でのタブストップの設定などの方法を制御するためにプロパティもあります。

テキストのジャスティファイ
Flash Player 10 以降、Adobe AIR 1.5 以降
テキストをジャスティファイすると、単語間、また場合によっては文字間のスペースを調整することにより、段落内のすべての行が同じ長さになります。テキストが両端で行揃えされるという効果がありますが、単語および文字間のスペースは様々です。新聞や雑誌のテキストの列は、ジャスティファイされていることがよくあります。

SpaceJustifier クラスの lineJustfication プロパティにより、テキストのブロック内の行のジャスティファイを制御できます。
LineJustification クラスは、次のようにジャスティファイオプションの指定に使用できる定数を定義します。
ALL_BUT_LAST は、最後の行を除くすべてのテキストをジャスティファイします。ALL_INCLUDING_LAST は、最後の行も含めてすべてのテキストをジャスティファイします。UNJUSTIFIED はデフォルトですが、テキストはジャスティファイ
されていない状態のままにします。
テキストをジャスティファイするには、SpaceJustifier クラスのインスタンスに lineJustification プロパティを設定し、そのインスタンスを TextBlock インスタンスの textJustifier プロパティに割り当てます。次の例では、最後の行以外のすべてのテキストがジャスティファイされる段落を作成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

393

Flash Text Engine の使用

package{import flash.text.engine.*;import flash.display.Sprite;
public class JustifyExample extends Sprite{
public function JustifyExample(){var str:String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, " +"sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut " +"enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut " +"aliquip ex ea commodo consequat.";var format:ElementFormat = new ElementFormat();var textElement:TextElement=new TextElement(str,format);var spaceJustifier:SpaceJustifier=new SpaceJustifier("en",LineJustification.ALL_BUT_LAST);
var textBlock:TextBlock = new TextBlock();
textBlock.content=textElement;
textBlock.textJustifier=spaceJustifier;createLines(textBlock);}
private function createLines(textBlock:TextBlock):void {var yPos=20;
var textLine:TextLine=textBlock.createTextLine(null,150);
while (textLine) {addChild(textLine);
textLine.x=15;
yPos+=textLine.textHeight+2;
textLine.y=yPos;
textLine=textBlock.createTextLine(textLine,150);}}}}

文字間および単語間のスペースを多様にするには、SpaceJustifier.letterspacing プロパティを true にします。文字間のスペー
スをオンにしておくと、単純な位置揃えに見られる単語間の見苦しいギャップの発生の可能性が低減されます。

東アジア系テキストのジャスティファイ
Flash Player 10 以降、Adobe AIR 1.5 以降
東アジア系テキストのジャスティファイには、追加の考慮事項があります。上から下に書かれ、禁則として知られる一部の文字は、行の先頭または末尾に使用できません。JustificationStyle クラスは、文字の処理のためのオプションを指定する次の定数を定義します。PRIORITIZE_LEAST_ADJUSTMENT は、最も好ましい結果を生むのはどちらかにより、行の拡張または圧縮に基づき、位置揃えします。PUSH_IN_KINSOKU は、行末の圧縮される禁則に応じて、または禁則がない場合やスペースが不足している場合の拡張に応じて、位置揃えします。

PUSH_OUT_ONLY は、拡張に応じて位置揃えします。縦書きのアジア系テキストのブロックを作成するには、
TextBlock.lineRotation プロパティを TextRotation.ROTATE_90 に設定し、ElementFormat.textRotation プロパティをデフォル
トの TextRotation.AUTO に設定します。textRotation プロパティを AUTO に設定すると、テキスト内の字形は行を回転させても横にならずに縦のままになります。AUTO 設定では、字形の Unicode プロパティによって決定される全角および幅広の字形のみが反時計回りに 90 度回転されます。次の例は、日本語テキストの縦書きのブロックを表示し、PUSH_IN_KINSOKU オプションを使用してジャスティファイします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

394

Flash Text Engine の使用

package{import flash.text.engine.*;import flash.display.Stage;
import flash.display.Sprite;
import flash.system.Capabilities;
public class EastAsianJustifyExample extends Sprite{
public function EastAsianJustifyExample(){var Japanese_txt:String = String.fromCharCode(0x5185, 0x95A3, 0x5E9C, 0x304C, 0x300C, 0x653F, 0x5E9C, 0x30A4,
0x30F3, 0x30BF, 0x30FC, 0x30CD, 0x30C3, 0x30C8, 0x30C6, 0x30EC,
0x30D3, 0x300D, 0x306E, 0x52D5, 0x753B, 0x914D, 0x4FE1, 0x5411,
0x3051, 0x306B, 0x30A2, 0x30C9, 0x30D3, 0x30B7, 0x30B9, 0x30C6,
0x30E0, 0x30BA, 0x793E, 0x306E)
var textBlock:TextBlock = new TextBlock();
var font:FontDescription = new FontDescription();var format:ElementFormat = new ElementFormat();format.fontSize = 12;
format.color = 0xCC0000;
format.textRotation = TextRotation.AUTO;
textBlock.baselineZero = TextBaseline.IDEOGRAPHIC_CENTER;
var eastAsianJustifier:EastAsianJustifier = new EastAsianJustifier("ja",
LineJustification.ALL_BUT_LAST);
eastAsianJustifier.justificationStyle = JustificationStyle.PUSH_IN_KINSOKU;
textBlock.textJustifier = eastAsianJustifier;
textBlock.lineRotation = TextRotation.ROTATE_90;
var linePosition:Number = this.stage.stageWidth - 75;
if (Capabilities.os.search("Mac OS") > -1)// set fontName: Kozuka Mincho Pro R
font.fontName = String.fromCharCode(0x5C0F, 0x585A, 0x660E, 0x671D) + " Pro R";
else
font.fontName = "Kozuka Mincho Pro R";
textBlock.content = new TextElement(Japanese_txt, format);var previousLine:TextLine = null;
while (true){
var textLine:TextLine = textBlock.createTextLine(previousLine, 200);
if (textLine == null)
break;
textLine.y = 20;
textLine.x = linePosition;
linePosition -= 25;
addChild(textLine);previousLine = textLine;}}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

395

Flash Text Engine の使用

カーニングとトラッキング
Flash Player 10 以降、Adobe AIR 1.5 以降
カーニングとトラッキングは、テキストブロック内の隣接する 2 文字間の距離に影響します。カーニングは、「WA」や「Va」などの文字のペアの整合方法を制御します。カーニングは、ElementFormat オブジェクトで設定されます。デフォル
トではオン（Kerning.ON）になっており、OFF または AUTO に設定することもできます。その場合、カーニングは 2 つの文字のどちらも漢字、ひらがな、カタカナのいずれでもない場合にのみ、適用されます。
トラッキングは、テキストブロック内のすべての文字間の一定のピクセル数を加算、または減算します。この機能もElementFormat オブジェクトで設定されます。カーニングは埋め込みフォントとデバイスフォントの両方で使用できます。
FTE は、文字の左側のピクセルを追加または削除する trackingLeft および文字の右側のピクセルを追加または削除する
trackingRight の 2 つのトラッキングプロパティをサポートしています。カーニングを使用している場合は、トラッキング値
は各文字ペアで追加または削除されます。

A

B

C

VAY
VAY
VAY

D

E

F

VAY
VAY
VAY

A. Kerning.OFF B. TrackingRight=5, Kerning.OFF C. TrackingRight=-5, Kerning.OFF D. Kerning.ON E. TrackingRight=-5, Kerning.ON
F. TrackingRight=-5, Kerning.ON

var ef1:ElementFormat = new ElementFormat();
ef1.kerning = Kerning.OFF;
var ef2:ElementFormat = new ElementFormat();
ef2.kerning = Kerning.ON;
ef2.trackingLeft = 0.8;
ef2.trackingRight = 0.8;
var ef3:ElementFormat = new ElementFormat();
ef3.trackingRight = -0.2;

ラップされたテキストの改行Flash Player 10 以降、Adobe AIR 1.5 以降
ElementFormat オブジェクトの breakOpportunity プロパティは、ラップされたテキストを複数の行に分割する場合に、どの文字を使用するかを決定します。デフォルトの BreakOpportunity.AUTO では、単語間やハイフンでの改行など、標準のUnicode プロパティを使用します。BreakOpportunity.ALL を使用すると、任意の文字を改行として扱うことができるので、パスに沿ったテキストなどの効果の作成に役立ちます。
var ef:ElementFormat = new ElementFormat();ef.breakOpportunity = BreakOpportunity.ALL;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

396

Flash Text Engine の使用

タブストップFlash Player 10 以降、Adobe AIR 1.5 以降
テキストブロックにタブストップを設定するには、TabStop クラスのインスタンスを作成してタブストップを定義します。

TabStop() コンストラクターのパラメーターは、テキストがタブストップと整列する方法を指定します。これらのパラメー
ターは、タブストップの位置、また小数点の位置合わせの場合は、位置合わせの基準とする値を文字列を使用して指定します。通常、この値は小数点ですが、カンマ、ドル記号、円、ユーロなどの記号である場合もあります。次のコード行では、
tab1 というタブストップが作成されます。
var tab1:TabStop = new TabStop(TabAlignment.DECIMAL, 50, ".");

テキストブロックのタブストップを作成したら、それらを TextBlock インスタンスの tabStops プロパティに割り当てます。
ただし、tabStops プロパティには、ベクターが必要なので、まずベクターを作成してそれにタブストップを追加します。ベ
クターでは、テキストブロックに一連のタブストップを割り当てることができます。次の例では、Vector<TabStop> インス
タンスを作成し、一連の TabStop オブジェクトをそれに追加します。次に、タブストップを TextBlock インスタンスのtabStops プロパティに追加します。
var tabStops:Vector.<TabStop> = new Vector.<TabStop>();tabStops.push(tab1, tab2, tab3, tab4);
textBlock.tabStops = tabStops

ベクターについて詳しくは、24 ページの「配列の操作」を参照してください。
次の例は、それぞれの TabStop 整列オプションの効果を示しています。
package {import flash.text.engine.*;import flash.display.Sprite;
public class TabStopExample extends Sprite{
public function TabStopExample(){var format:ElementFormat = new ElementFormat();format.fontDescription = new FontDescription("Arial");format.fontSize = 16;
var tabStops:Vector.<TabStop> = new Vector.<TabStop>();tabStops.push(
new TabStop(TabAlignment.START, 20),
new TabStop(TabAlignment.CENTER, 140),
new TabStop(TabAlignment.DECIMAL, 260, "."),
new TabStop(TabAlignment.END, 380));
var textBlock:TextBlock = new TextBlock();
textBlock.content = new TextElement("\tt1\tt2\tt3\tt4\n" +"\tThis line aligns on 1st tab\n" +"\t\t\t\tThis is the end\n" +"\tThe following fragment centers on the 2nd tab:\t\t\n" +"\t\tit's on me\t\t\n" +"\tThe following amounts align on the decimal point:\n" +"\t\t\t45.00\t\n" +最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

397

Flash Text Engine の使用"\t\t\t75,320.00\t\n" +"\t\t\t6,950.00\t\n" +"\t\t\t7.01\t\n", format);textBlock.tabStops = tabStops;
var yPosition:Number = 60;
var previousTextLine:TextLine = null;var textLine:TextLine;var i:int;for (i = 0; i < 10; i++) {textLine = textBlock.createTextLine(previousTextLine, 1000, 0);
textLine.x = 20;
textLine.y = yPosition;
addChild(textLine);yPosition += 25;
previousTextLine = textLine;}}}}

Flash Text Engine の例：ニュースレイアウト
Flash Player 10 以降、Adobe AIR 1.5 以降
このプログラミング例は、単純な新聞のページのレイアウトに使用される Flash Text Engine を示しています。ページには、
大きなヘッドライン、サブヘッドおよび複数列の本文セクションが含まれます。
まず、FLA ファイルを作成し、次のコードをデフォルトレイヤーのフレーム #2 に関連付けます。
import com.example.programmingas3.newslayout.StoryLayout ;// frame sc ript - create a 3-columned arti cle layout
var story:StoryLayout = new StoryLayout(720, 500, 3, 10);story.x = 20;
story.y = 80;
addChild(story);stop();

StoryLayout.as は、この例のコントローラースクリプトです。このスクリプトは、コンテンツを設定し、外部スタイルシー
トからスタイル情報を読み取り、これらのスタイルを ElementFormat オブジェクトに割り当てます。次に、ヘッドライン、
サブヘッドおよび複数列のテキストエレメントを作成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

398

Flash Text Engine の使用

package com.example.programmingas3.newslayout{
import flash.display.Sprite;
import flash.text.StyleSheet;
import flash.text.engine.*;import flash.events.Event;import flash.net.URLRequest;
import flash.net.URLLoader;import flash.display.Sprite;
import flash.display.Graphics;
public class StoryLayout extends Sprite{
public var headlineTxt:HeadlineTextField;
public var subtitleTxt:HeadlineTextField;
public var storyTxt:MultiColumnText;
public var sheet:StyleSheet;public var h1_ElFormat:ElementFormat;
public var h2_ElFormat:ElementFormat;
public var p_ElFormat:ElementFormat;
private var loader:URLLoader;public var paddingLeft:Number;public var paddingRight:Number;public var paddingTop:Number;public var paddingBottom:Number;public var preferredWidth:Number;public var preferredHeight:Number;public var numColumns:int;public var bgColor:Number = 0xFFFFFF;
public var headline:String = "News Layout Example";public var subtitle:String = "This example formats text like a newspaper page using the Flash Text
Engine API. ";public var rawTestData:String ="From the part Mr. Burke took in the American Revolution, it was natural that I should consider him
a friend to mankind; and as our acquaintance commenced on that ground, it would have been more agreeable to
me to have had cause to continue in that opinion than to change it. " +"At the time Mr. Burke made his violent speech last winter in the English Parliament against the
French Revolution and the National Assembly, I was in Paris, and had written to him but a short time before
to inform him how prosperously matters were going on. Soon after this I saw his advertisement of the Pamphlet
he intended to publish: As the attack was to be made in a language but little studied, and less understoodin France, and as everything suffers by translation, I promised some of the friends of the Revolution inthat country that whenever Mr. Burke's Pamphlet came forth, I would answer it. This appeared to me the morenecessary to be done, when I saw the flagrant misrepresentations which Mr. Burke's Pamphlet contains; andthat while it is an outrageous abuse on the French Revolution, and the principles of Liberty, it is an
imposition on the rest of the world. " +"I am the more astonished and disappointed at this conduct in Mr. Burke, as (from the circumstances
I am going to mention) I had formed other expectations. " +"I had seen enough of the miseries of war, to wish it might never more have existence in the world,
and that some other mode might be found out to settle the differences that should occasionally arise in theneighbourhood of nations. This certainly might be done if Courts were disposed to set honesty about it, or
if countries were enlightened enough not to be made the dupes of Courts. The people of America had been bredup in the same prejudices against France, which at that time characterised the people of England; but
experience and an acquaintance with the French Nation have most effectually shown to the Americans thefalsehood of those prejudices; and I do not believe that a more cordial and confidential intercourse exists

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

399

Flash Text Engine の使用

between any two countries than between America and France. ";public function StoryLayout(w:int = 400, h:int = 200, cols:int = 3, padding:int = 10):void{
this.preferredWidth = w;
this.preferredHeight = h;this.numColumns = cols;
this.paddingLeft = padding;this.paddingRight = padding;this.paddingTop = padding;this.paddingBottom = padding;var req:URLRequest = new URLRequest("story.css");
loader = new URLLoader();loader.addEventListener(Event.COMPLETE, onCSSFileLoaded);loader.load(req);}public function onCSSFileLoaded(event:Event):void{
this.sheet = new StyleSheet();this.sheet.parseCSS(loader.data);// convert headline styles to ElementFormat objects
h1_ElFormat = getElFormat("h1", this.sheet);
h1_ElFormat.typographicCase = TypographicCase.UPPERCASE;
h2_ElFormat = getElFormat("h2", this.sheet);p_ElFormat = getElFormat("p", this.sheet);displayText();}
public function drawBackground():void{
var h:Number = this.storyTxt.y + this.storyTxt.height +this.paddingTop + this.paddingBottom;
var g:Graphics = this.graphics;
g.beginFill(this.bgColor);
g.drawRect(0, 0, this.width + this.paddingRight + this.paddingLeft, h);g.endFill();}/*** Reads a set of style properties for a named style and then creates* a TextFormat object that uses the same properties.
*/
public function getElFormat(styleName:String, ss:StyleSheet):ElementFormat{
var style:Object = ss.getStyle(styleName);if (style != null){var colorStr:String = style.color;
if (colorStr != null && colorStr.indexOf("#") == 0){style.color = colorStr.substr(1);}var fd:FontDescription = new FontDescription(style.fontFamily,
style.fontWeight,
FontPosture.NORMAL,
FontLookup.DEVICE,

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

400

Flash Text Engine の使用

RenderingMode.NORMAL,
CFFHinting.NONE);var format:ElementFormat = new ElementFormat(fd,style.fontSize,style.color,
1,
TextRotation.AUTO,
TextBaseline.ROMAN,TextBaseline.USE_DOMINANT_BASELINE,
0.0,
Kerning.ON,
0.0,
0.0,
"en",
BreakOpportunity.AUTO,
DigitCase.DEFAULT,
DigitWidth.DEFAULT,
LigatureLevel.NONE,
TypographicCase.DEFAULT);
if (style.hasOwnProperty("letterSpacing")){
format.trackingRight = style.letterSpacing;}}
return format;}
public function displayText():void{
headlineTxt = new HeadlineTextField(h1_ElFormat,headline,this.preferredWidth);
headlineTxt.x = this.paddingLeft;headlineTxt.y = 40 + this.paddingTop;
headlineTxt.fitText(1);this.addChild(headlineTxt);
subtitleTxt = new HeadlineTextField(h2_ElFormat,subtitle,this.preferredWidth);
subtitleTxt.x = this.paddingLeft;subtitleTxt.y = headlineTxt.y + headlineTxt.height;
subtitleTxt.fitText(2);this.addChild(subtitleTxt);
storyTxt = new MultiColumnText(rawTestData, this.numColumns,
20, this.preferredWidth, this.preferredHeight, p_ElFormat);storyTxt.x = this.paddingLeft;
storyTxt.y = subtitleTxt.y + subtitleTxt.height + 10;
this.addChild(storyTxt);
drawBackground();}}}FormattedTextBlock.as は、テキストのブロックを作成するためのベースクラスとして使用されます。フォントサイズと大文字小文字を変更するためのユーティリティ関数も含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

401

Flash Text Engine の使用

package com.example.programmingas3.newslayout{
import flash.text.engine.*;import flash.display.Sprite;
public class FormattedTextBlock extends Sprite{
public var tb:TextBlock;private var te:TextElement;
private var ef1:ElementFormat;
private var textWidth:int;public var totalTextLines:int;public var blockText:String;
public var leading:Number = 1.25;
public var preferredWidth:Number = 720;
public var preferredHeight:Number = 100;
public function FormattedTextBlock(ef:ElementFormat,txt:String, colW:int = 0){
this.textWidth = (colW==0) ? preferredWidth : colW;
blockText = txt;
ef1 = ef;
tb = new TextBlock();
tb.textJustifier = new SpaceJustifier("en",LineJustification.UNJUSTIFIED,false);
te = new TextElement(blockText,this.ef1);
tb.content = te;this.breakLines();}
private function breakLines(){
var textLine:TextLine = null;var y:Number = 0;var lineNum:int = 0;
while (textLine = tb.createTextLine(textLine,this.textWidth,0,true)){
textLine.x = 0;
textLine.y = y;y += this.leading*textLine.height;
this.addChild(textLine);}for (var i:int = 0; i < this.numChildren; i++){TextLine(this.getChildAt(i)).validity = TextLineValidity.STATIC;}
this.totalTextLines = this.numChildren;}
private function rebreakLines(){
this.clearLines();this.breakLines();}
private function clearLines(){
while(this.numChildren){
this.removeChildAt(0);}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

402

Flash Text Engine の使用

public function changeSize(size:uint=12):void{if (size > 5){
var ef2:ElementFormat = ef1.clone();ef2.fontSize = size;
te.elementFormat = ef2;
this.rebreakLines();}}public function changeCase(newCase:String = "default"):void{
var ef2:ElementFormat = ef1.clone();ef2.typographicCase = newCase;te.elementFormat = ef2;}}}

HeadlineTextBlock.as は、FormattedTextBlock クラスを拡張し、ヘッドラインの作成に使用されます。ページ上の定義済み空間にテキストを収めるための関数も含まれます。
package com.example.programmingas3.newslayout{
import flash.text.engine.*;public class HeadlineTextField extends FormattedTextBlock{public static var MIN_POINT_SIZE:uint = 6;
public static var MAX_POINT_SIZE:uint = 128;
public function HeadlineTextField(te:ElementFormat,txt:String,colW:int = 0){
super(te,txt);}
public function fitText(maxLines:uint = 1, targetWidth:Number = -1):uint{
if (targetWidth == -1){
targetWidth = this.width;}
var pixelsPerChar:Number = targetWidth / this.blockText.length;
var pointSize:Number = Math.min(MAX_POINT_SIZE,
Math.round(pixelsPerChar * 1.8 * maxLines));if (pointSize < 6){// the point size is too small
return pointSize;}
this.changeSize(pointSize);if (this.totalTextLines > maxLines){
return shrinkText(--pointSize, maxLines);}
else{
return growText(pointSize, maxLines);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

403

Flash Text Engine の使用}}
public function growText(pointSize:Number, maxLines:uint = 1):Number{
if (pointSize >= MAX_POINT_SIZE){
return pointSize;}
this.changeSize(pointSize + 1);
if (this.totalTextLines > maxLines){// set it back to the last size
this.changeSize(pointSize);
return pointSize;}
else{
return growText(pointSize + 1, maxLines);}}
public function shrinkText(pointSize:Number, maxLines:uint=1):Number{
if (pointSize <= MIN_POINT_SIZE){
return pointSize;}
this.changeSize(pointSize);if (this.totalTextLines > maxLines){
return shrinkText(pointSize - 1, maxLines);}
else{
return pointSize;}}}}

MultiColumnText.as は、複数列設計のテキストのフォーマットを処理します。テキスト行の作成、フォーマットおよび配置のためのファクトリとしての TextBlock オブジェクトの柔軟な使用方法も示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

404

Flash Text Engine の使用

package com.example.programmingas3.newslayout{
import flash.display.Sprite;
import flash.text.engine.*;public class MultiColumnText extends Sprite{
private var tb:TextBlock;private var te:TextElement;
private var numColumns:uint = 2;
private var gutter:uint = 10;
private var leading:Number = 1.25;
private var preferredWidth:Number = 400;
private var preferredHeight:Number = 100;
private var colWidth:int = 200;
public function MultiColumnText(txt:String = "",cols:uint = 2,
gutter:uint = 10, w:Number = 400, h:Number = 100,
ef:ElementFormat = null):void{
this.numColumns = Math.max(1, cols);
this.gutter = Math.max(1, gutter);this.preferredWidth = w;
this.preferredHeight = h;this.setColumnWidth();var field:FormattedTextBlock = new FormattedTextBlock(ef,txt,this.colWidth);
var totLines:int = field.totalTextLines;
field = null;var linesPerCol:int = Math.ceil(totLines/cols);
tb = new TextBlock();
te = new TextElement(txt,ef);tb.content = te;var textLine:TextLine = null;var x:Number = 0;
var y:Number = 0;
var i:int = 0;
var j:int = 0;
while (textLine = tb.createTextLine(textLine,this.colWidth,0,true)){
textLine.x = Math.floor(i/(linesPerCol+1))*(this.colWidth+this.gutter);
textLine.y = y;y += this.leading*textLine.height;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

405

Flash Text Engine の使用

j++;if(j>linesPerCol){y = 0;
j = 0;}
i++;this.addChild(textLine);}}
private function setColumnWidth():void{
this.colWidth = Math.floor( (this.preferredWidth ((this.numColumns - 1) * this.gutter)) / this.numColumns);}}}

最終更新日 2015/10/14

406

第 23 章：Text Layout Framework の使用
Flash Player 10 以降、Adobe AIR 1.5 以降

Text Layout Framework の概要
Flash Player 10 以降、Adobe AIR 1.5 以降
Text Layout Framework（TLF）は、拡張可能な ActionScript ライブラリです。TLF は、Adobe® Flash® Player 10 および Adobe® AIR® 1.5 のテキストエンジン上に構築されています。TLF は高度なテキスト編集機能とテキストレイアウト機能を提供し、Web での革新的なテキスト編集を実現します。このフレームワークは、Adobe® Flex® または Adobe® Flash®
Professional で使用できます。開発者は既存のコンポーネントを使用または拡張することも、フレームワークを使用して独自のテキストコンポーネントを作成することもできます。

TLF には次の機能が含まれます。

•

双方向テキスト、縦書きテキストおよびアラビア文字、ヘブライ文字、中国語、日本語、韓国語、タイ文字、ラオ文字、
ベトナム語などの 30 種を超える記述スクリプト•

複数の列やリンクされたコンテナをまたがるテキストの選択、編集、フロー設定•

縦書きテキスト、縦中横（縦書きのテキスト内部の横書きテキスト）、日中韓のテキスト編集用の位置揃え•

カーニング、合字、文字の大文字と小文字、数字の大文字と小文字、数字の幅、任意ハイフンなどの機能豊富なテキスト
編集コントロール•

切り取り、コピー、ペースト、取り消しおよび編集のための標準のキーボード操作とマウス操作•

テキストコンテンツ、レイアウト、マークアップの操作とカスタムテキストコンポーネントの作成を行う機能豊富な開発
者 API

•

カスタムのマーカーや番号付け形式を含む堅牢なリストのサポート•

インラインイメージと配置ルール

TLF は、Flash Player 10 で導入された Flash Text Engine（FTE）に基づいて構築された ActionScript 3.0 ライブラリです。FTE には flash.text.engine パッケージを通じてアクセスできます。このパッケージは、Flash Player 10 アプリケーショ
ンプログラミングインターフェイス（API）の一部です。
ただし、Flash Player API で提供されているテキストエンジンへのアクセス手段は低レベルなものです。したがって、作業
によっては比較的大量のコードが必要となります。TLF は低レベルのコードを単純な API にカプセル化します。また、TLF
は概念アーキテクチャを提供します。これは、FTE によって定義される基本的な構成要素を、使いやすいシステムにまとめたものです。

FTE とは異なり、TLF は Flash Player に組み込まれていません。TLF は、一貫して ActionScript 3.0 で記述された独立したコンポーネントライブラリです。このフレームワークは拡張可能なので、特定の環境に合わせてカスタマイズできます。

Flash Professional と Flex SDK の両方に、TLF フレームワークをベースにしたコンポーネントが用意されています。
関連項目「Flow」TLF マークアップアプリケーション

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

407

Text Layout Framework の使用

複雑なスクリプトのサポート
Flash Player 10 以降、Adobe AIR 1.5 以降
TLF は複雑なスクリプトをサポートしています。複雑なスクリプトのサポートには、右から左に表記されるスクリプトの表
示、編集機能などが含まれます。また、TLF には、左から右への表記と右から左への表記が混在するアラビア文字やヘブラ
イ文字などのスクリプトの表示、編集機能も用意されています。このフレームワークでは、中国語、日本語、韓国語向けの
縦書きレイアウトのサポートに加えて、縦中横（TCY エレメント）もサポートされています。TCYElement は、縦書きのテキスト範囲に埋め込まれた横書きのブロックです。次のスクリプトがサポートされています。

•

ラテン文字（英語、スペイン語、フランス語、ベトナム語など）•

ギリシャ文字、キリル文字、アルメニア文字、グルジア文字、エチオピア文字•

アラビア文字、ヘブライ文字•

漢字およびかな（中国語、日本語、韓国語）およびハングル Johab（韓国語）•

タイ文字、ラーオ文字、クメール文字•

デーバナーガリー文字、ベンガル文字、グルムキー文字、マラヤーラム文字、テルグ文字、タミル文字、グジャラート文
字、オリヤー文字、カンナダ文字、チベット文字•

ティフナグ文字、イ文字、チェロキー文字、カナダ先住民文字、ディザレット文字、シャビアン文字、ヴァイ文字、タガ
ログ文字、ハヌノオ文字、ブヒッド文字、タグバンワ文字

Flash Professional および Flex での Text Layout Framework の使用
TLF クラスを直接使用して、Flash でカスタムコンポーネントを作成できます。さらに、Flash Professional CS5 では、TLF 機能をカプセル化する fl.text.TLFTextField という新しいクラスが提供されています。この TLFTextField クラスは、TLF の高度なテキスト表示機能を使用するテキストフィールドを ActionScript で作成するために使用します。TextField ク
ラスを使用してテキストフィールドを作成する場合と同じ方法で、TLFTextField オブジェクトを作成します。次に、textFlow プロパティを使用して、TLF クラスによる詳細な書式設定を割り当てます。
Flash Professional のテキストツールを使用して、ステージ上に TLFTextField のインスタンスを作成することもできます。
その後、ActionScript を使用して、TLF クラスを使用するテキストフィールドの内容の書式設定とレイアウトを制御できます。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「TLFTextField」を参照してください。

Flex で作業している場合は、TLF クラスを使用します。詳しくは、407 ページの「Text Layout Framework の使用」を参照してください。

Text Layout Framework の使用
Flash Player 10 以降、Adobe AIR 1.5 以降
Flex で作業している場合やカスタムテキストコンポーネントを作成している場合は、TLF クラスを使用します。TLF は
ActionScript 3.0 ライブラリであり、その全体が textLayout.swc ライブラリ内に含まれています。TLF ライブラリには、
10 個のパッケージに編成された約 100 個の ActionScript 3.0 クラスおよびインターフェイスが含まれています。これらのパッケージは、flashx.textLayout パッケージのサブパッケージです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

408

Text Layout Framework の使用

Text Layout Framework のクラス
Flash Player 10 以降、Adobe AIR 1.5 以降
TLF クラスは次の 3 種類のカテゴリに分類できます。

•

データ構造および書式設定クラス•

レンダリングクラス•

ユーザー操作クラス

データ構造および書式設定クラス
次のパッケージには、TLF 用のデータ構造および書式設定クラスが含まれています。
• flashx.textLayout.elements• flashx.textLayout.formats• flashx.textLayout.conversion
TLF の主要なデータ構造であるテキストフロー階層は、elements パッケージに定義されています。この構造内で、formats
パッケージを使用してスタイルと属性をテキスト範囲に割り当てることができます。また、conversion パッケージを使用して、データ構造に対するテキストの読み込みや書き出しの方法を制御することもできます。

レンダリングクラス
次のパッケージには、TLF 用のレンダリングクラスが含まれています。
• flashx.textLayout.factory• flashx.textLayout.container• flashx.textLayout.compose
これらのパッケージ内のクラスは、Flash Player による表示用テキストのレンダリングを容易にします。factory パッケージ
は、静止テキストを表示するための単純な方法を提供します。container パッケージには、ダイナミックテキストの表示コ
ンテナを定義するクラスとインターフェイスが含まれています。compose パッケージでは、コンテナでダイナミックテキス
トを配置および表示するためのテクニックが定義されます。

ユーザー操作クラス
次のパッケージには、TLF 用のユーザー操作クラスが含まれています。
• flashx.textLayout.edit• flashx.textLayout.operations• flashx.textLayout.events
edit パッケージおよび operations パッケージでは、データ構造に格納されているテキストの編集に使用できるクラスを定義します。events パッケージには、イベント処理クラスが含まれています。

Text Layout Framework を使用したテキスト作成の一般的な手順
次の手順は、Text Layout Framework を使用した一般的なテキスト作成プロセスを表したものです。

1 書式設定済みのテキストを TLF データ構造に読み込みます。詳しくは、412 ページの「TLF を使用したテキストの構造化」と 415 ページの「TLF を使用したテキストの書式設定」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

409

Text Layout Framework の使用

2 テキスト用に、リンクされた表示オブジェクトコンテナを 1 つ以上作成します。詳しくは、417 ページの「TLF を使用したテキストコンテナの管理」を参照してください。

3 データ構造内のテキストをコンテナに関連付けて、編集オプションとスクロールオプションを設定します。詳しくは、

418 ページの「TLF を使用したテキスト選択、編集、取り消しの有効化」を参照してください。
4 サイズ変更などのイベントに応答してテキストのフローを再設定するイベントハンドラーを作成します。詳しくは、419
ページの「TLF を使用したイベント処理」を参照してください。

Text Layout Framework の例：ニュースレイアウト
Flash Player 10 以降、Adobe AIR 1.5 以降
TLF を使用して単純な新聞ページをレイアウトする例を次に示します。ページには、大きなヘッドライン、サブヘッドおよび複数列の本文セクションが含まれます。
package{import flash.display.Sprite;
import flash.display.StageAlign;import flash.display.StageScaleMode;
import flash.events.Event;import flash.geom.Rectangle;
import flashx.textLayout.compose.StandardFlowComposer;
import flashx.textLayout.container.ContainerController;
import flashx.textLayout.container.ScrollPolicy;
import flashx.textLayout.conversion.TextConverter;
import flashx.textLayout.elements.TextFlow;
import flashx.textLayout.formats.TextLayoutFormat;
public class TLFNewsLayout extends Sprite{
private var hTextFlow:TextFlow;
private var headContainer:Sprite;
private var headlineController:ContainerController;
private var hContainerFormat:TextLayoutFormat;
private var bTextFlow:TextFlow;
private var bodyTextContainer:Sprite;
private var bodyController:ContainerController;
private var bodyTextContainerFormat:TextLayoutFormat;
private const headlineMarkup:String = "<flow:TextFlow
xmlns:flow='http://ns.adobe.com/textLayout/2008'><flow:p textAlign='center'><flow:spanfontFamily='Helvetica' fontSize='18'>TLF News Layout Example</flow:span><flow:br/><flow:spanfontFamily='Helvetica' fontSize='14'>This example formats text like a newspaper page with a headline, asubtitle, and multiple columns</flow:span></flow:p></flow:TextFlow>";
private const bodyMarkup:String = "<flow:TextFlow xmlns:flow='http://ns.adobe.com/textLayout/2008'
fontSize='12' textIndent='10' marginBottom='15' paddingTop='4' paddingLeft='4'><flow:pmarginBottom='inherit'><flow:span>There are many </flow:span><flow:span
fontStyle='italic'>such</flow:span><flow:span> lime-kilns in that tract of country, for the purpose ofburning the white marble which composes a large part of the substance of the hills. Some of them, built
years ago, and long deserted, with weeds growing in the vacant round of the interior, which is open to thesky, and grass and wild-flowers rooting themselves into the chinks of the stones, look already like relicsof antiquity, and may yet be overspread with the lichens of centuries to come. Others, where the lime-burnerstill feeds his daily and nightlong fire, afford points of interest to the wanderer among the hills, whoseats himself on a log of wood or a fragment of marble, to hold a chat with the solitary man. It is alonesome, and, when the character is inclined to thought, may be an intensely thoughtful occupation; as it

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

410

Text Layout Framework の使用

proved in the case of Ethan Brand, who had mused to such strange purpose, in days gone by, while the firein this very kiln was burning.</flow:span></flow:p><flow:p marginBottom='inherit'><flow:span>The man who
now watched the fire was of a different order, and troubled himself with no thoughts save the very few thatwere requisite to his business. At frequent intervals, he flung back the clashing weight of the iron door,
and, turning his face from the insufferable glare, thrust in huge logs of oak, or stirred the immense brands
with a long pole. Within the furnace were seen the curling and riotous flames, and the burning marble, almost
molten with the intensity of heat; while without, the reflection of the fire quivered on the dark intricacyof the surrounding forest, and showed in the foreground a bright and ruddy little picture of the hut, thespring beside its door, the athletic and coal-begrimed figure of the lime-burner, and the half-frightenedchild, shrinking into the protection of his father's shadow. And when again the iron door was closed, thenreappeared the tender light of the half-full moon, which vainly strove to trace out the indistinct shapesof the neighboring mountains; and, in the upper sky, there was a flitting congregation of clouds, still
faintly tinged with the rosy sunset, though thus far down into the valley the sunshine had vanished long
and long ago.</flow:span></flow:p></flow:TextFlow>";
public function TLFNewsLayout(){//wait for stage to exist
addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);}
private function onAddedToStage(evtObj:Event):void{
removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage);stage.scaleMode = StageScaleMode.NO_SCALE;
stage.align = StageAlign.TOP_LEFT;// Headline text flow and flow composer
hTextFlow = TextConverter.importToFlow(headlineMarkup, TextConverter.TEXT_LAYOUT_FORMAT);// initialize the headline container and controller objects
headContainer = new Sprite();headlineController = new ContainerController(headContainer);headlineController.verticalScrollPolicy = ScrollPolicy.OFF;
hContainerFormat = new TextLayoutFormat();hContainerFormat.paddingTop = 4;
hContainerFormat.paddingRight = 4;
hContainerFormat.paddingBottom = 4;
hContainerFormat.paddingLeft = 4;
headlineController.format = hContainerFormat;
hTextFlow.flowComposer.addController(headlineController);
addChild(headContainer);stage.addEventListener(flash.events.Event.RESIZE, resizeHandler);// Body text TextFlow and flow composerbTextFlow = TextConverter.importToFlow(bodyMarkup, TextConverter.TEXT_LAYOUT_FORMAT);// The body text container is below, and has three columns
bodyTextContainer = new Sprite();bodyController = new ContainerController(bodyTextContainer);
bodyTextContainerFormat = new TextLayoutFormat();bodyTextContainerFormat.columnCount = 3;
bodyTextContainerFormat.columnGap = 30;
bodyController.format = bodyTextContainerFormat;
bTextFlow.flowComposer.addController(bodyController);
addChild(bodyTextContainer);resizeHandler(null);}
private function resizeHandler(event:Event):void

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

411

Text Layout Framework の使用{
const verticalGap:Number = 25;
const stagePadding:Number = 16;
var stageWidth:Number = stage.stageWidth - stagePadding;var stageHeight:Number = stage.stageHeight - stagePadding;var headlineWidth:Number = stageWidth;
var headlineContainerHeight:Number = stageHeight;// Initial compose to get height of headline after resize
headlineController.setCompositionSize(headlineWidth,
headlineContainerHeight);
hTextFlow.flowComposer.compose();var rect:Rectangle = headlineController.getContentBounds();
headlineContainerHeight = rect.height;// Resize and place headline text container// Call setCompositionSize() again with updated headline heightheadlineController.setCompositionSize(headlineWidth, headlineContainerHeight );headlineController.container.x = stagePadding / 2;
headlineController.container.y = stagePadding / 2;
hTextFlow.flowComposer.updateAllControllers();// Resize and place body text container
var bodyContainerHeight:Number = (stageHeight - verticalGap - headlineContainerHeight);
bodyController.format = bodyTextContainerFormat;
bodyController.setCompositionSize(stageWidth, bodyContainerHeight );bodyController.container.x = (stagePadding/2);
bodyController.container.y = (stagePadding/2) + headlineContainerHeight + verticalGap;
bTextFlow.flowComposer.updateAllControllers();}}}

TLFNewsLayout クラスでは 2 つのテキストコンテナが使用されています。ヘッドラインとサブヘッドを表示するコンテナと、3 列の本文テキストを表示するコンテナです。便宜上、テキストを TLF Markup テキストとして例の中にハードコー
ディングしています。headlineMarkup 変数にはヘッドラインとサブヘッドの両方が含まれ、bodyMarkup 変数には本文が含まれます。TLF Markup について詳しくは、412 ページの「TLF を使用したテキストの構造化」を参照してください。
初期化処理の後に、onAddedToStage() 関数によりヘッドラインテキストが TextFlow オブジェクトに読み込まれます。この
オブジェクトは TLF の主要なデータ構造です。
hTextFlow = TextConverter.importToFlow(headlineMarkup, TextConverter.TEXT_LAYOUT_FORMAT);

次に、コンテナ用の Sprite オブジェクトが作成され、さらにコントローラーが作成されてコンテナに関連付けられます。
headContainer = new Sprite();headlineController = new ContainerController(headContainer);

コントローラーが初期化され、書式設定、スクロール、その他のオプションが設定されます。コントローラーには、テキス
トが設定されるコンテナの領域を定義するジオメトリが含まれます。TextLayoutFormat オブジェクトには書式設定オプ
ションが含まれます。
hContainerFormat = new TextLayoutFormat();コントローラーはフローコンポーザーに割り当てられ、この関数によってコンテナが表示リストに追加されます。コンテナの実際の構成と表示は resizeHandler() メソッドによって行われます。本文の TextFlow オブジェクトを初期化するために、同じ手順が実行されます。

resizeHandler() メソッドでは、コンテナのレンダリングに使用できる領域を測定し、それに応じてコンテナのサイズを決定します。compose() メソッドの最初の呼び出しによって、ヘッドラインコンテナの適切な高さを計算できるようにします。
次に、resizeHandler() メソッドで、updateAllControllers() メソッドを使用してヘッドラインコンテナを配置および表示します。最後に、resizeHandler() メソッドで、ヘッドラインコンテナのサイズを使用して本文コンテナの配置を決定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

412

Text Layout Framework の使用

TLF を使用したテキストの構造化
TLF では、階層ツリーを使用してテキストを表します。ツリー内の各ノードは、elements パッケージで定義されたクラスのインスタンスです。例えば、ツリーのルートノードは常に、TextFlow クラスのインスタンスです。TextFlow クラスは、
テキストのストーリー全体を表します。ストーリーとは、1 つの単位、つまりフローとして処理されるテキストや他のエレ
メントのコレクションです。1 つのストーリーで、複数の列やテキストコンテナの表示が必要になることがあります。
ルートノードは別として、それ以外のエレメントは大まかに XHTML エレメントに基づいています。次の図は、フレームワークの階層を示しています。

TextFlow 階層

Text Layout Framework Markup
TLF の構造を理解することは、TLF Markup を扱う場合にも役立ちます。TLF Markup は TLF の一部であり、テキストのXML 表現です。フレームワークでは他の XML フォーマットもサポートされていますが、TLF Markup は、特に TextFlow
階層の構造に基づいているという点で特徴的です。このマークアップフォーマットを使用して TextFlow から XML を書き出す場合、この階層はそのままの状態で XML が書き出されます。
TLF Markup を使用すれば、テキストを TextFlow 構造で最も正確に表現できます。このマークアップ言語には、
TextFlow 構造の各基本エレメントに対応するタグや、TextLayoutFormat クラスで利用できるすべての書式設定プロパ
ティに対応する属性も用意されています。
次の表には、TLF Markup で使用できるタグを示しています。
エレメント

説明

子

クラス

textflow

マークアップのルートエレメントです。

div、p

TextFlowdiv

TextFlow 内の範囲です。段落のグループを含

div、list、p

DivElement
ParagraphElement

めることができます。

p

段落です。

a、tcy、span、img、
tab、br、ga

リンクです。

tcy、span、img、tab、 LinkElement
br、g

横書きのテキスト範囲です（縦書きのa、span、img、tab、
br、g

tcy

TextFlow で使用されます）。
span

段落内のテキスト範囲です。

TCYElement

SpanElement

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

413

Text Layout Framework の使用

エレメント

説明

img

段落内のイメージです。

InlineGraphicElementtab

タブ文字です。

TabElementbr

ブレーク文字です。段落内の行を終了させるために使用します。テキストは次の行に続きますが、同じ段落のままです。

BreakElement

linkNormalFormat

通常の状態のリンクに使用されるフォーマット
属性を定義します。

TextLayoutFormat

TextLayoutFormat

linkActiveFormat

マウスをリンク上で押しているときに、アクティブ状態のリンクに使用されるフォーマット
属性を定義します。

TextLayoutFormat

TextLayoutFormat

linkHoverFormat

マウスをリンク上で動かしているときに、アクティブ状態のリンクに使用されるフォーマット
属性を定義します。

TextLayoutFormat

TextLayoutFormat

リストアイテムエレメントです。list エレメン

div、li、list、p

ListItemElement

li

子

クラス

トの内部に指定する必要があります。

list

リストです。リストはネスト可能であり、また互いに隣接するように配置できます。リストア
イテムには、異なるラベルや番号付け方式を適用できます。

div、li、list、pListElementg

グループエレメントです。段落内でのエレメン
トのグループ化に使用します。段落よりも下のレベルでエレメントをネストできます。

a、tcy、span、img、
tab、br、g

SubParagraphGroup
Element

関連項目

TLF 2.0 Lists Markup
TLF 2.0 SubParagraphGroupElements and typeName

番号付きリストおよび箇条書きリストの使用
ListElement クラスと ListItemElement クラスを使用して、テキストコントロールに箇条書きリストを追加できます。箇条
書きリストはネスト可能であり、異なる箇条書き記号（マーカー）や自動番号付け、およびアウトラインスタイルの番号付
けを使用するようカスタマイズできます。
テキストフローにリストを作成するには、<list> タグを使用します。さらに、<list> タグ内部で、リスト内のリストアイテム
ごとに <li> タグを使用します。箇条書き記号の外観は、ListMarkerFormat クラスを使用してカスタマイズできます。
次の例では、単純なリストが作成されます。
<flow:list paddingRight="24" paddingLeft="24"><flow:li>Item 1</flow:li><flow:li>Item 2</flow:li><flow:li>Item 3</flow:li></flow:list>

次の例のように、他のリストの内部にリストをネストできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

414

Text Layout Framework の使用<flow:list paddingRight="24" paddingLeft="24"><flow:li>Item 1</flow:li><flow:list paddingRight="24" paddingLeft="24"><flow:li>Item 1a</flow:li><flow:li>Item 1b</flow:li><flow:li>Item 1c</flow:li></flow:list><flow:li>Item 2</flow:li><flow:li>Item 3</flow:li></flow:list>

リスト内のマーカーのタイプをカスタマイズするには、ListElement の listStyleType プロパティを使用します。このプロパ
ティには、ListStyleType クラスに定義されたいずれかの値を設定できます（check、circle、decimal、box など）。次の例では、様々なマーカータイプとカスタムのカウンターのインクリメントを使用したリストが作成されます。
<flow:list paddingRight="24" paddingLeft="24" listStyleType="upperAlpha"> <flow:li>upperAlphaitem</flow:li> <flow:li>another</flow:li> </flow:list> <flow:list paddingRight="24" paddingLeft="24"
listStyleType="lowerAlpha"> <flow:li>lowerAlpha item</flow:li> <flow:li>another</flow:li> </flow:list><flow:list paddingRight="24" paddingLeft="24" listStyleType="upperRoman"> <flow:li>upperRoman
item</flow:li> <flow:li>another</flow:li> </flow:list> <flow:list paddingRight="24" paddingLeft="24"
listStyleType="lowerRoman"> <flow:listMarkerFormat> <!-- Increments the list by 2s rather than 1s. --><flow:ListMarkerFormat counterIncrement="ordered 2"/> </flow:listMarkerFormat> <flow:li>lowerRoman
item</flow:li> <flow:li>another</flow:li> </flow:list>

カウンターの定義には、ListMarkerFormat クラスを使用します。カウンターのインクリメントの定義に加えて、counterReset プロパティによりカウンターをリセットしてカスタマイズすることもできます。
さらに、ListMarkerFormat の beforeContent プロパティと afterContent プロパティを使用して、リスト内のマーカーの外観をカスタマイズできます。これらのプロパティは、マーカーのコンテンツの前後に表示されるコンテンツに適用されます。
次の例では、マーカーの前に文字列「XX」が追加され、マーカーの後ろに文字列「YY」が追加されます。
<flow:list listStyleType="upperRoman" paddingLeft="36" paddingRight="24"><flow:listMarkerFormat><flow:ListMarkerFormat fontSize="16"
beforeContent="XX"afterContent="YY"
counterIncrement="ordered -1"/></flow:listMarkerFormat><flow:li>Item 1</flow:li><flow:li>Item 2</flow:li><flow:li>Item 3</flow:li></flow:list>

content プロパティ自体でも、マーカー形式のカスタマイズをさらに定義できます。次の例では、順序付けられた大文字のローマ数字マーカーが表示されます。
<flow:list listStyleType="disc" paddingLeft="96" paddingRight="24"><flow:listMarkerFormat><flow:ListMarkerFormat fontSize="16"
beforeContent="Section "content="counters(ordered,&quot;*&quot;,upperRoman)"afterContent=": "/></flow:listMarkerFormat><flow:li>Item 1</li><flow:li>Item 2</li><flow:li>Item 3</li></flow:list>

前述の例が示す通り、content プロパティには接尾辞を挿入することもできます。接尾辞は、マーカーの後、afterContent の前に表示される文字列です。フローに XML コンテンツを設定する場合にこの文字列を挿入するには、引用符で文字列を囲むのではなく（"<string>"）、HTML エンティティの &quote; で囲むようにします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

415

Text Layout Framework の使用

関連項目

TLF 2.0 Lists Markup

TLF での余白の使用
それぞれの FlowElement では、余白プロパティがサポートされています。余白プロパティは、各エレメントのコンテンツ
領域の位置と、コンテンツ領域間のスペースを制御するために使用します。
エレメントの全体の幅は、コンテンツの幅と、paddingLeft プロパティおよび paddingRight プロパティの合計になります。エ
レメントの全体の高さは、コンテンツの高さと、paddingTop プロパティおよび paddingBottom プロパティの合計になります。
余白は、境界線とコンテンツの間のスペースです。余白プロパティは、paddingBottom、paddingTop、paddingLeft、
paddingRight です。余白は TextFlow オブジェクトおよび次の子エレメントに適用できます。

• div
• img
• li
• list• p
余白プロパティは、span エレメントには適用できません。
次の例では、TextFlow に余白プロパティを設定します。
<flow:TextFlow version="2.0.0" xmlns:flow="http://ns.adobe.com/textLayout/2008" fontSize="14"
textIndent="15" paddingTop="4" paddingLeft="4" fontFamily="Times New Roman">

余白プロパティの有効な値は、数値（ピクセル単位）、「auto」または「inherit」です。デフォルト値は「auto」です。これは、余白が自動的に計算され、ListElement 以外のすべてのエレメントには 0 が設定されることを示します。
ListElement の場合は、「auto」を設定すると、listAutoPadding プロパティの値が使用されているリストの開始側以外では 0となります。listAutoPadding のデフォルト値は 40 です。これによって、リストのデフォルトのインデントが設定されます。
余白プロパティはデフォルトでは継承されません。
「auto」値および「inherit」値は、FormatValue クラスに定義された定数です。
余白プロパティには負の値を設定できます。

関連項目

Padding changes in TLF 2.0

TLF を使用したテキストの書式設定
Flash Player 10 以降、Adobe AIR 1.5 以降
flashx.textLayout.formats パッケージには、テキストフロー階層ツリー内の任意の FlowElement にフォーマットを割り当てることができるインターフェイスおよびクラスが含まれています。フォーマットを適用するには、2 通りの方法があります。特定のフォーマットを個別に割り当てる方法と、特殊なフォーマットオブジェクトを使用してフォーマットのグループを同時に割り当てる方法です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

416

Text Layout Framework の使用

ITextLayoutFormat インターフェイスには、FlowElement に適用できるすべてのフォーマットが含まれています。フォー
マットには、テキストのコンテナ全体または段落全体に適用されるが、論理的に個々の文字には適用されないものもあります。例えば、均等配置、タブストップなどのフォーマットは、段落全体に適用されますが、個々の文字には適用されません。

プロパティを使用した FlowElement へのフォーマットの割り当てFlash Player 10 以降、Adobe AIR 1.5 以降
プロパティの割り当てを通して、任意の FlowElement にフォーマットを設定できます。FlowElement クラスは

ITextLayoutFormat インターフェイスを実装しているので、FlowElement クラスのすべてのサブクラスでもこのインターフェイスを実装する必要があります。
例えば、次のコードでは ParagraphElement のインスタンスにフォーマットを個別に割り当てる方法を示しています。
var p:ParagraphElement = new ParagraphElement();
p.fontSize = 18;
p.fontFamily = "Arial";

TextLayoutFormat クラスを使用した FlowElement へのフォーマットの割り当てFlash Player 10 以降、Adobe AIR 1.5 以降
TextLayoutFormat クラスを使用して、FlowElement にフォーマットを適用できます。このクラスを使用して、必要な
フォーマット値がすべて含まれている特殊なフォーマットオブジェクトを作成します。次にそのオブジェクトを、任意のFlowElement オブジェクトの format プロパティに割り当てます。TextLayoutFormat と FlowElement の両方で、
ITextLayoutFormat インターフェイスを実装します。こうすることで、両方のクラスに同じ format プロパティが含まれる
ようにします。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「TextLayoutFormat」を参照してください。

フォーマットの継承
Flash Player 10 以降、Adobe AIR 1.5 以降
フォーマットはテキストフロー階層を通して継承されます。TextLayoutFormat のインスタンスを、子を持つ

FlowElement インスタンスに割り当てた場合、フレームワークは「カスケード」と呼ばれる処理を開始します。カスケー
ドの間、フレームワークは FlowElement から継承した階層内の各ノードを再帰的に調べ、継承した値をそれぞれのフォー
マットプロパティに割り当てるかどうかを判断します。次のルールがカスケードの間に適用されます。

1 プロパティ値は、最も近い上位（「親」と呼ばれることがあります）からのみ継承されます。
2 プロパティ値は、プロパティに既に値が設定されていない場合にのみ継承されます（つまり、値が undefined の場合）。
3 いくつかの属性は、値が「inherit」または定数 flashx.textLayout.formats.FormatValue.INHERIT に設定されていないと、未定義では値を継承しません。
例えば、TextFlow レベルで fontSize 値を設定した場合、その設定は TextFlow のすべてのエレメントに適用されます。つまり、値はテキストフロー階層の下位に向かってカスケードします。ただし、エレメントに新しい値を直接割り当てること
で、特定のエレメントの値をオーバーライドすることができます。反例として、TextFlow レベルで backgroundColor 値を設定しても、値は TextFlow の子に継承されません。backgroundColor プロパティはカスケードの間にその親から値を継承しないプロパティです。この動作は、それぞれの子の backgroundColor プロパティをflashx.textLayout.formats.FormatValue.INHERIT に設定することによってオーバーライドできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

417

Text Layout Framework の使用

詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「TextLayoutFormat」を参照してください。

TLF を使用したテキストの読み込みと書き出し
Flash Player 10 以降、Adobe AIR 1.5 以降
flashx.textLayout.conversion.* パッケージの TextConverter クラスを使用すると、TLF へのテキストの読み込み、および TLF からのテキストの書き出しを実行できます。このクラスは、テキストを SWF ファイルにコンパイルするのではな
く、実行時にテキストをロードする場合に使用します。また、このクラスを使用すると、TextFlow インスタンスに保存されているテキストを String オブジェクトまたは XML オブジェクトに書き出すこともできます。
読み込みと書き出しは両方とも、直接的なプロシージャです。ともに TextConverter クラスの一部である、export() メソッ
ドまたは importToFlow() メソッドを呼び出します。どちらのメソッドも静的です。つまり、TextConverter クラスのインスタンスではなく、TextConverter クラスでメソッドを呼び出します。

flashx.textLayout.conversion パッケージ内のクラスでは、テキストの格納先を柔軟に選択することができます。例えば、テキストをデータベースに格納した場合に、テキストをフレームワークに読み込んで表示することができます。その後、

flashx.textLayout.edit パッケージのクラスを使用してテキストを変更し、変更後のテキストを再度データベースに書き出すことができます。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「flashx.textLayout.conversion」を参照
してください。

TLF を使用したテキストコンテナの管理
Flash Player 10 以降、Adobe AIR 1.5 以降
TLF データ構造内にテキストを格納した後は、Flash Player でそのテキスト表示できます。フロー階層に格納されているテキストは、Flash Player で表示可能なフォーマットに変換する必要があります。TLF では、フローから表示オブジェクトを作成するための 2 種類の方法を利用できます。1 つ目の単純なアプローチは、静止テキストの表示に適しています。2 つ目の複雑なアプローチでは、選択や編集が可能なダイナミックテキストを作成できます。いずれの場合も、テキストは最終的に、Flash Player 10 の flash.text.engine.* パッケージの一部である、TextLine クラスのインスタンスに変換されます。

静止テキストの作成
単純なアプローチでは、flashx.textLayout.factory パッケージ内にある TextFlowTextLineFactory クラスを使用します。
このアプローチの利点は、単純であるということ以上に、FlowComposer アプローチよりメモリフットプリントが小さいという点です。このアプローチは、ユーザーが編集、選択またはスクロールする必要がない静止テキストに適しています。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「TextFlowTextLineFactory」を参照してください。

ダイナミックテキストおよびコンテナの作成
TextFlowTextLineFactory よりもテキストの表示を綿密に調整したい場合には、フローコンポーザーを使用します。例えば、フローコンポーザーを使用すると、ユーザーがテキストを選択して編集することができます。詳しくは、418 ページの「TLF を使用したテキスト選択、編集、取り消しの有効化」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

418

Text Layout Framework の使用

フローコンポーザーは、flashx.textLayout.compose パッケージ内の StandardFlowComposer クラスのインスタンスです。フローコンポーザーは、TextFlow の TextLine インスタンスへの変換と、変換した TextLine インスタンスの 1 つ以上のコンテナへの配置を管理します。

TextFlowStage

IFlowComposer

SpriteContainerController

TextLine

TextLine

IFlowComposer には 0 個以上の ContainerController があります。

各 TextFlow インスタンスには、IFlowComposer インターフェイスを実装する、対応するオブジェクトがあります。この
IFlowComposer オブジェクトには、TextFlow.flowComposer プロパティを通じてアクセス可能です。このプロパティを通じて、IFlowComposer インターフェイスで定義されたメソッドを呼び出すことができます。これらのメソッドを使用すると、1 つ以上のコンテナにテキストを関連付けて、コンテナ内に表示するテキストを作成することができます。
コンテナは、DisplayObjectContainer クラスのサブクラスである Sprite クラスのインスタンスです。これらのクラスは両方とも、Flash Player 表示リスト API. の一部です。コンテナは、TextLineFactory クラスで使用される境界を示す矩形のより高度な形式です。境界を示す矩形と同様に、コンテナでは TextLine インスタンスが表示される領域を定義します。境界を示す矩形とは異なり、コンテナには対応する「コントローラー」オブジェクトが存在します。コントローラーは、1 個のコンテナまたは複数のコンテナに対するスクロール、構成、リンク、書式設定、およびイベント処理を管理します。各コンテナには、flashx.textLayout.container パッケージ内にある ContainerController クラスのインスタンスである対応するコントローラーオブジェクトがあります。
テキストを表示するには、コンテナを管理するコントローラーオブジェクトを作成し、それをフローコンポーザーに関連付けます。コンテナを関連付けたら、テキストを表示できるように構成します。このように、コンテナには構成と表示の 2 つの状態があります。構成は、テキストフロー階層のテキストを TextLine インスタンスに変換し、これらのインスタンスがコンテナに収まるかどうかを計算するプロセスです。表示は、Flash Player 表示リストを更新するプロセスです。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「IFlowComposer」、「StandardFlowComposer」、および「ContainerController」を参照してください。

TLF を使用したテキスト選択、編集、取り消しの有効化
Flash Player 9.0 以降、Adobe AIR 1.0 以降
テキストを選択または編集できるかどうかは、テキストフローレベルで制御されます。TextFlow クラスの各インスタンスには、関連付けられた対話マネージャーがあります。TextFlow オブジェクトの対話マネージャーには、オブジェクトのTextFlow.interactionManager プロパティを通じてアクセスできます。テキストの選択を有効にするには、SelectionManager
クラスのインスタンスを interactionManager プロパティに割り当てます。テキストの選択と編集の両方を有効にするには、
SelectionManager クラスのインスタンスではなく、EditManager クラスのインスタンスを割り当てます。取り消し操作を有効にするには、UndoManager クラスのインスタンスを作成し、EditManager のコンストラクターを呼び出すときに引数としてそのインスタンスを含めます。UndoManager クラスでは、ユーザーの最新の編集アクティビティのヒストリーは維持されます。また、ユーザーは特定の編集の取り消しまたはやり直しを行うことができます。これらの 3 つのクラスはすべて edit パッケージの一部です。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「SelectionManager」、「EditManager」、
および「UndoManager」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

419

Text Layout Framework の使用

TLF を使用したイベント処理
Flash Player 10 以降、Adobe AIR 1.5 以降
TextFlow オブジェクトからは、次のような様々な状況でイベントが送出されます。

•

テキストまたはレイアウトの変更時•

操作の開始前および操作の完了後• FlowElement オブジェクトのステータス変更時•

構成操作の完了時

詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の「flashx.textLayout.events」を参照して
ください。

関連項目

TLF FlowElement and LinkElement Events and EventMirrors

テキスト内部へのイメージの配置
テキスト内部に InlineGraphicElement を配置するには、次のプロパティを使用します。

• InlineGraphicElement クラスの float プロパティ• FlowElement の clearFloats プロパティ
float プロパティにより、グラフィックおよびその周囲のテキストの位置が制御されます。clearFloats プロパティにより、
float を基準とした段落エレメントの位置が制御されます。
テキストエレメント内部のイメージの位置を制御するには、float プロパティを使用します。次の例では、段落にイメージを追加し、テキストが右側で折り返されるように左側にイメージを配置しています。
<flow:p paragraphSpaceAfter="15" >Images in a flow are a good thing. For example, here is a float. It should
show on the left: <flow:img float="left" height="50" width="19" source="../assets/bulldog.jpg"></flow:img>
Don't you agree? Another sentence here. Another sentence here. Another sentence here. Another sentence here.
Another sentence here. Another sentence here. Another sentence here. Another sentence here.</flow:p>float プロパティの有効な値は、「left」、「right」、「start」、「end」および「none」です。Float クラスにこれらの定数が定義されています。デフォルト値は「none」です。
clearFloats プロパティは、通常はイメージの周囲で折り返される、後に続く段落の開始位置を調整する場合に役に立ちます。
例えば、最初の段落よりも大きいイメージがあるとします。2 つ目の段落がイメージの後に始まるようにするには、
clearFloats プロパティを設定します。
次の例では、最初の段落のテキストよりも縦の長さが大きいイメージを使用しています。テキストブロック内のイメージの後に 2 つ目の段落が始まるように、この例では 2 つ目の段落の clearFloats プロパティを「end」に設定しています。
<flow:p paragraphSpaceAfter="15" >Here is another float, it should show up on the right: <flow:img
float="right" height="50" elementHeight="200" width="19" source="../assets/bulldog.jpg"></flow:img>We'll
add another paragraph that should clear past it.</flow:p><flow:p clearFloats="end" >This should appear after
the previous float on the right.</flow:p>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

420

Text Layout Framework の使用

clearFloats プロパティの有効な値は、「left」、「right」、「end」、「start」、「none」および「both」です。ClearFloats クラスにこれらの定数が定義されています。また、clearFloats プロパティを「inherit」に設定することもできます。この値はFormatValue クラスに定義されている定数です。デフォルト値は「none」です。
関連項目

TLF Floats

最終更新日 2015/10/14

421

第 24 章：サウンドの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript は没入型のインタラクティブなアプリケーション向けに作成されています。そして、没入性の高いアプリケー
ションの中でも見過ごされがちな要素と言えばサウンドです。サウンドをアプリケーションの中核として、ビデオゲームに
サウンドエフェクトを追加、アプリケーションユーザーインターフェイスにオーディオフィードバックを追加、またはインターネット上でロードされた MP3 ファイルを分析するプログラムを作成することができます。
外部オーディオファイルをロードしたり、SWF に埋め込まれたオーディオを操作したりできます。また、オーディオを制御したり、サウンド情報の視覚的表現を作成したり、ユーザーのマイクからサウンドをキャプチャしたりもできます。

関連項目

flash.media パッケージ
flash.events.SampleDataEvent

サウンドの操作の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
コンピューターは、サウンド情報のデジタル表現であるデジタル オーディオをキャプチャしてエンコードし、保存し、取得してスピーカから再生できます。サウンドの再生は、Adobe® Flash® Player または Adobe® AIR™ と ActionScript を使用して行うことができます。
サウンドデータがデジタル形式に変換されると、サウンドボリュームや、サウンドがステレオであるかモノラルサウンドであるかなどの様々な性質があります。ActionSctipt でサウンドを再生すると、それらの性質も調節ができます。つまり、サウンドを大きくしたり、一定の方向から聞こえるようにすることができます。

ActionScript でサウンドを制御する前に、Flash Player または AIR にサウンド情報をロードする必要があります。オー
ディオデータを Flash Player または AIR に取り入れ、ActionScript で操作するには、5 種類の方法があります。

• MP3 ファイルなどの外部サウンドファイルを、SWF に読み込みます。
•

サウンド情報を、作成時に SWF ファイルに直接埋め込みます。

•

ユーザーのコンピューターに接続されているマイクからオーディオをキャプチャします。

•

サーバーからオーディオをストリーミングします。

•

オーディオを動的に生成して再生します。

サウンドデータを外部サウンドファイルから読み込むときは、サウンドデータの読み込みがすべて終わらないうちに、サウンドファイルの先頭部分の再生を開始できます。
デジタルオーディオをエンコードするサウンドファイルには様々な形式がありますが、ActionScript 3.0、Flash Player、および AIR は、MP3 形式で保存されるサウンドファイルをサポートしています。WAV や AIFF などの他の形式のサウン
ドファイルを、直接読み込んだり再生したりすることはできません。
サウンドを ActionScript で操作するときは、一般に flash.media パッケージの複数のクラスを使用します。Sound クラス
は、サウンドファイルをロードすることにより、またはサウンドデータをサンプリングして再生を開始するイベントに関数を割り当てることにより、オーディオ情報にアクセスするために使用するクラスです。サウンドの再生を開始すると、Flash Player および AIR は SoundChannel オブジェクトへのアクセスを可能にします。ロードされたオーディオファイル
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

422

サウンドの操作は、ユーザーのコンピューターで再生される複数のサウンドのうちの 1 つでしかないこともあるので、再生されるそれぞれのサウンドは独自の SoundChannel オブジェクトを使用します。すべての SoundChannel オブジェクトを合成して出力す
ると、そのサウンドがコンピューターのスピーカーから実際に流れます。サウンドのプロパティを制御したり、再生を停止したりするには、この SoundChannel インスタンスを使用します。最後に、混合されたオーディオを制御する必要がある
場合は、SoundMixer クラスを使用して混合出力を制御できます。
また、ActionScript でサウンドを操作しているときには、他のクラスも使用してより特定されたタスクを実行することもできます。サウンド関連のすべてのクラスについては、422 ページの「サウンドアーキテクチャについて」を参照してください。
重要な概念と用語
次の参照リストに、使用する重要な用語を示します。
振幅 ゼロまたは平衡の状態から、サウンド波形上のポイントまでの距離です。
ビットレート サウンドファイルで 1 秒あたりにエンコードまたはストリーミングされるデータ量です。MP3 ファイルでは、ビットレートは 1,000 ビット / 秒（kbps）で示されます。ビットレートが高くなると、通常は高品質なサウンド波形が生まれます。
バッファリング サウンドデータを再生する前に受信し、保存することです。

MP3 MPEG-1 オーディオレイヤー 3、つまり MP3 は、広く使用されているサウンド圧縮形式です。
パンニング ステレオ音場の左チャンネルと右チャンネルの間にオーディオ信号を配置することです。
ピーク 波形で一番高い地点です。
サンプリングレート デジタル信号を生成するために、アナログオーディオ信号から取り出した 1 秒あたりのサンプル数を示すものです。標準的なコンパクトディスクオーディオのサンプリングレートは、毎秒 44.1 kHz、つまり毎秒 44,100 サンプ
ルです。
ストリーミング サウンドファイルまたはビデオファイルの後の方の部分をサーバーからロードしながら、ファイルの前の方の部分を再生することです。
ボリューム サウンドの音量です。
波形 サウンド信号の振幅の推移を示すグラフです。

サウンドアーキテクチャについてFlash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションでは、次の 5 つのメインソースからサウンドデータをロードすることができます。

•

実行時に読み込む外部サウンドファイル•

アプリケーションの SWF ファイル内に埋め込まれたサウンドリソース•

ユーザーのシステムに接続されたマイクロフォンから入力されるサウンドデータ• Flash Media Server などのリモートメディアサーバーからストリーミングされるサウンドデータ• sampleData イベントハンドラーを使用して動的に生成されるサウンドデータ
サウンドデータは、完全に読み込んでから再生することも、ストリーミングすることも、つまりまだ読み込みの途中で再生することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

423

サウンドの操作

ActionScript 3.0 のサウンドクラスは、MP3 形式で保存されているサウンドファイルをサポートします。WAV や AIFF といった、他の形式のサウンドファイルを直接ロードまたは再生することはできません。ただし、Flash Player 9.0.115.0 以降
では、NetStream クラスを使用して AAC オーディオファイルをロードおよび再生できます。これは、ビデオコンテンツのロードと再生に使用されるものと同じ技法です。この技法について詳しくは、453 ページの「ビデオの操作」を参照してください。

Adobe Flash Professional を使用すると、WAV または AIFF サウンドファイルを読み込んで、アプリケーションの SWF
ファイルに MP3 形式で埋め込むことができます。Flash オーサリングツールを使用すると、埋め込まれたサウンドファイル
を圧縮してファイルサイズを小さくすることができます。ただし、サイズが減少する代わりにサウンドの品質は低下します。
詳しくは、『Flash ユーザーガイド』の「サウンドの読み込み」を参照してください。

ActionScript 3.0 サウンドアーキテクチャは、flash.media パッケージの次のクラスを利用します。
クラス

説明flash.media.Sound

Sound クラスは、サウンドの読み込みを処理し、サウンドの基本的なプロパティを管理し、サウンドの再生を開始します。

flash.media.SoundChannel

アプリケーションが Sound オブジェクトを再生するときは、再生を制御するために新しい SoundChannel
オブジェクトが作成されます。SoundChannel オブジェクトは、サウンドの左右の再生チャンネルの音量を制御します。再生するサウンドはそれぞれ、専用の SoundChannel オブジェクトを使用します。

flash.media.SoundLoaderContext

SoundLoaderContext クラスは、サウンドのロード中に何秒間バッファリングするか、また、ファイルのロード中に Flash Player または AIR がサーバーのポリシーファイルを検索するかどうかを指定します。

SoundLoaderContext オブジェクトは、Sound.load() メソッドに対するパラメーターとして使用されます。
flash.media.SoundMixer

SoundMixer クラスは、アプリケーション内のすべてのサウンドに関係する再生とセキュリティのプロパ
ティを制御します。実際、共通の SoundMixer オブジェクトを通じて複数のサウンドチャンネルが合成されるので、SoundMixer オブジェクトのプロパティ値は、再生中のすべての SoundChannel オブジェクトに影響を与えます。

flash.media.SoundTransformflash.media.ID3Info

SoundTransform クラスには、サウンドの音量とバランスを制御する値が含まれます。SoundTransform
オブジェクトは、数あるオブジェクトの中で、個々の SoundChannel オブジェクト、グローバルSoundMixer オブジェクト、または Microphone オブジェクトに適用できます。
ID3Info オブジェクトには、通常は MP3 サウンドファイルに格納される ID3 メタデータ情報を表すプロパ
ティが含まれています。

flash.media.Microphone

Microphone クラスは、ユーザーのコンピューターに接続されたマイクロフォンまたはその他のサウンド入力デバイスを表します。マイクロフォンからのオーディオ入力は、ローカルスピーカに渡したり、リモートサーバーに送信したりできます。Microphone オブジェクトは、ゲイン、サンプリングレート、および固有のサウンドストリームの他の特性を制御します。

flash.media.AudioPlaybackMode

AudioPlaybackMode クラスは、SoundMixer クラスの audioPlaybackMode プロパティの定数を定義します。

読み込まれて再生される各サウンドには、Sound クラスと SoundChannel クラスについて、専用のインスタンスが必要です。複数の SoundChannel インスタンスからの出力は、再生中にグローバルな SoundMixer クラスによって合成されます。

Sound、SoundChannel、および SoundMixer クラスは、マイクロフォンから取得したサウンドデータ、または FlashMedia Server などのストリーミングメディアサーバーからのサウンドデータには使用されません。

外部のサウンドファイルの読み込みFlash Player 9 以降、Adobe AIR 1.0 以降
Sound クラスの各インスタンスは、特定のサウンドリソースを読み込んで再生をトリガーするために存在します。アプリ
ケーションは、1 つの Sound オブジェクトを再利用して複数のサウンドを読み込むことはできません。新しいサウンドリ
ソースをロードする必要がある場合は、新しい Sound オブジェクトを作成する必要があります。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド424

サウンドの操作

ボタンに関連付けるクリック音など、小さなサウンドファイルをロードする場合、アプリケーションは新しい Sound オブ
ジェクトを作成し、次のようにサウンドファイルを自動的にロードできます。
var req:URLRequest = new URLRequest("click.mp3");
var s:Sound = new Sound(req);

Sound() コンストラクターは、最初のパラメーターとして URLRequest オブジェクトを受け取ります。URLRequest パラ
メーターに値が渡ると、新しい Sound オブジェクトは指定されたサウンドリソースの読み込みを自動的に開始します。
最も単純なケースを除いて、アプリケーションではサウンドの読み込みの進行状況に注意し、読み込み中のエラーを監視する必要があります。例えば、クリックサウンドが比較的大きい場合、サウンドをトリガーするボタンがクリックされても、サウンドが完全にロードされていないこともあります。読み込まれていないサウンドを再生しようとすると、ランタイムエ
ラーが発生する場合があります。そのため、サウンドが完全にロードされてから、サウンドの再生を開始するアクションを実行する方が安全です。

Sound オブジェクトは、サウンド読み込みプロセスの間に、複数の種類のイベントを送出します。アプリケーションは、これらのイベントをリッスンして読み込みの進行状況を追跡し、サウンドが完全に読み込まれたのを確認してから再生できます。次の表は、Sound オブジェクトによって送出されるイベントをまとめたものです。
イベント

説明

open (Event.OPEN)

サウンド読み込み操作の開始直前に送出されます。

progress (ProgressEvent.PROGRESS)

データをファイルまたはストリームから受け取るとき、サウンド読み込み処理の間に定期的に送出されます。

id3 (Event.ID3)

ID3 データが MP3 サウンドで使用できるようになると送出されます。

complete (Event.COMPLETE)

サウンドリソースの全データが読み込まれると送出されます。

ioError (IOErrorEvent.IO_ERROR)

サウンドファイルを読み込むことができない場合、または全サウンドデータを受け取る前に読み込み処理が中断された場合に送出されます。

次のコードは、読み込みが終了した後でサウンドを再生する方法を示しています。
import flash.events.Event;import flash.media.Sound;import flash.net.URLRequest;
var s:Sound = new Sound();s.addEventListener(Event.COMPLETE, onSoundLoaded);var req:URLRequest = new URLRequest("bigSound.mp3");s.load(req);
function onSoundLoaded(event:Event):void{
var localSound:Sound = event.target as Sound;
localSound.play();}

まず、URLRequest パラメーターの初期値を指定せずに新しい Sound オブジェクトを作成します。その後、Sound オブ
ジェクトの Event.COMPLETE イベントを監視し、すべてのサウンドデータがロードされると onSoundLoaded() メソッドが実行されます。次に、サウンドファイルの新しい URLRequest 値を指定して Sound.load() メソッドを呼び出します。
サウンドの読み込みが完了すると、onSoundLoaded() メソッドを実行します。Event オブジェクトの target プロパティは、Sound オブジェクトへの参照です。Sound オブジェクトの play() メソッドを呼び出すと、サウンドの再生が開始されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

425

サウンドの操作

サウンド読み込み処理の監視Flash Player 9 以降、Adobe AIR 1.0 以降
サウンドファイルのサイズが大きく、ロードに時間がかかることがあります。Flash Player および AIR では、サウンドを完
全にロードしなくてもアプリケーションで再生することができます。その際に、サウンドデータがどれだけロード済みであるか、また、どれだけのサウンドが再生済みであるかを示すこともできます。

Sound クラスは、ProgressEvent.PROGRESS および Event.COMPLETE の 2 つのイベントを送出するので、サウンドのロードの進行状況を比較的簡単に表示することができます。次の例では、これらのイベントを使用して読み込み中のサウンドに関する進行状況の情報を表示する方法を示します。
import flash.events.Event;import flash.events.ProgressEvent;import flash.media.Sound;import flash.net.URLRequest;
var s:Sound = new Sound();s.addEventListener(ProgressEvent.PROGRESS, onLoadProgress);s.addEventListener(Event.COMPLETE, onLoadComplete);s.addEventListener(IOErrorEvent.IO_ERROR, onIOError);var req:URLRequest = new URLRequest("bigSound.mp3");s.load(req);
function onLoadProgress(event:ProgressEvent):void{
var loadedPct:uint = Math.round(100 * (event.bytesLoaded / event.bytesTotal));trace("The sound is " + loadedPct + "% loaded.");}function onLoadComplete(event:Event):void{
var localSound:Sound = event.target as Sound;
localSound.play();}function onIOError(event:IOErrorEvent){
trace("The sound could not be loaded: " + event.text);}

このコードは、まず Sound オブジェクトを作成し、次に ProgressEvent.PROGRESS および Event.COMPLETE イベントのリスナーをこのオブジェクトに追加します。Sound.load() メソッドが呼び出され、サウンドファイルから最初のデータが受信されると、ProgressEvent.PROGRESS イベントが発生し、onSoundLoadProgress() メソッドがトリガーされます。
ロード済みのサウンドデータの割合は、ProgressEvent オブジェクトの bytesLoaded プロパティの値を、bytesTotal プロパ
ティの値で除算した値に相当します。同じ bytesLoaded プロパティと bytesTotal プロパティは、Sound オブジェクトでも使用できます。上記の例は、サウンドのロードの進行状況に関するメッセージを表示するだけですが、bytesLoaded およびbytesTotal 値を使用し、Adobe Flex Framework または Adobe Flash オーサリングツールに付属しているようなプログレス
バーコンポーネントを簡単に更新することもできます。
この例では、アプリケーションでサウンドファイル読み込み中のエラーを検出して対応する方法も示されています。例えば、
特定のファイル名を持つサウンドファイルが見つからない場合は、Sound オブジェクトによって Event.IO_ERROR イベントが送出されます。前述のコードでは、エラーが発生すると onIOError() メソッドを実行して簡単なエラーメッセージを表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド426

サウンドの操作

埋め込みサウンドの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
外部ファイルからサウンドをロードする代わりに埋め込みサウンドを使用することは、ボタンがクリックされたときに再生されるサウンドなど、アプリケーションのユーザーインターフェイス内のインジケーターとして使用される小さなサウンドに非常に便利です。
アプリケーションにサウンドファイルを埋め込むと、その結果として生成される SWF ファイルのサイズが、サウンドファ
イルの分だけ増加します。つまり、アプリケーションに大きなサウンドファイルを埋め込むと、SWF ファイルが望ましくないサイズに増加する可能性があるということです。
アプリケーションの ファイルにサウンドファイルを埋め込む厳密な方法は、SWF の開発環境によって異なります。

Flash での埋め込みサウンドファイルの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash オーサリングツールでは、複数のサウンド形式のサウンドを読み込んで、ライブラリにシンボルとして格納できます。
保存したサウンドは、タイムラインのフレームやボタン状態のフレームに割り当てる、ビヘイビアーで使用する、ActionScript コードで直接使用する、というように使用できます。この節では、Flash オーサリングツールで ActionScript
コードを処理する際に埋め込みサウンドを使用する方法について説明します。Flash で埋め込みサウンドを使用するその他の方法について詳しくは、『Flash ユーザーガイド』の「サウンドの読み込み」を参照してください。
Flash オーサリングツールを使用してサウンドファイルを埋め込むには：
1 ファイル／読み込み／ライブラリに読み込みを選択し、サウンドファイルを選択して読み込みます。
2 ライブラリパネルで読み込んだファイルの名前を右クリックし、「プロパティ」を選択します。「ActionScript に書き出し」チェックボックスをクリックします。

3 「クラス」フィールドに、ActionScript でこの埋め込みサウンドを参照する際に使う名前を入力します。デフォルトでは、このフィールド内のサウンドファイル名が使用されます。「DrumSound.mp3」のようにファイル名にピリオドが含まれている場合は、「DrumSound」のように変更する必要があります。ActionScript では、クラス名でピリオドを使用できません。「基本クラス」フィールドには引き続き flash.media.Sound と表示されます。

4 「OK」をクリックします。このクラスの定義がクラスパスで見つからなかったことを示すダイアログボックスが表示される場合もあります。「OK」をクリックして続行します。アプリケーションのクラスパスに含まれるいずれのクラス名とも一致しないクラス名を入力した場合は、flash.media.Sound クラスから継承する新しいクラスが自動的に生成されます。

5 埋め込まれているサウンドを使用するには、そのサウンドのクラス名を ActionScript で参照します。例えば、次のコードでは最初に、自動生成された DrumSound クラスの新しいインスタンスが作成されます。
var drum:DrumSound = new DrumSound();var channel:SoundChannel = drum.play();

DrumSound は、flash.media.Sound クラスのサブクラスなので、上記のとおり play() メソッドを含む Sound クラスのメソッドとプロパティを継承します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

427

サウンドの操作

Flex での埋め込みサウンドファイルの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Flex アプリケーションにサウンドアセットを埋め込むには、次のような様々な方法があります。

•

スクリプトで [Embed] メタデータタグを使用する• MXML で @Embed ディレクティブを使用して、Button、SoundEffect などのコンポーネントのプロパティとして埋め込みアセットを割り当てる• CSS ファイルで @Embed ディレクティブを使用する
この節では、最初の、[Embed] メタデータタグを使用して、Flex アプリケーション内の ActionScript コードにサウンドを埋め込む方法を説明します。

ActionScript コードにアセットを埋め込むには、[Embed] メタデータタグを使用します。
サウンドファイルを、メインソースフォルダーまたはプロジェクトのビルドパスにある別のフォルダーに配置します。コン
パイラーで埋め込みメタデータタグが検出されると、自動的に埋め込みアセットクラスが作成されます。このクラスには、[Embed] メタデータタグの直後に宣言するデータ型クラスの変数からアクセスできます。
次のコードでは、smallSound.mp3 というサウンドを埋め込み、soundClass という変数を使用して、サウンドに関連付けられている埋め込みアセットクラスへの参照を格納します。次に、埋め込みアセットクラスのインスタンスを作成して、Sound クラスのインスタンスとしてキャストし、そのインスタンスで play() メソッドを呼び出します。
package{import flash.display.Sprite;
import flash.media.Sound;import flash.media.SoundChannel;
public class EmbeddedSoundExample extends Sprite{[Embed(source="smallSound.mp3")]
public var soundClass:Class;public function EmbeddedSoundExample(){var smallSound:Sound = new soundClass() as Sound;smallSound.play();}}}

埋め込みサウンドを使用して Flex コンポーネントのプロパティを設定するには、Sound クラスのインスタンスとしてではなく、mx.core.SoundAsset クラスのインスタンスとしてキャストする必要があります。SoundAsset クラスを使用する同様の例については、『ActionScript 3.0 の学習』の「埋め込みアセットクラス」を参照してください。

ストリーミングサウンドファイルの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
サウンドファイルまたはビデオファイルをまだ読み込んでいる間にそのデータを再生することを、「ストリーミング」と呼びます。サウンドデータが完全にロードされなくてもサウンドを聴くことができるので、リモートサーバーからロードされる
外部サウンドファイルの多くはストリーミングされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

428

サウンドの操作SoundMixer.bufferTime プロパティは、サウンドが再生される前に Flash Player または AIR が収集する必要のあるサウンド
データをミリ秒単位で示します。つまり、bufferTime プロパティが 5000 に設定されていると、Flash Player または AIR はサウンドが再生されるまでに、少なくとも 5000 ミリ秒分のデータをサウンドファイルからロードします。
SoundMixer.bufferTime のデフォルト値は 1000 です。
アプリケーションでは、サウンドを読み込むときに bufferTime の新しい値を明示的に指定することで、個別のサウンドについてグローバルな SoundMixer.bufferTime の値をオーバーライドできます。デフォルトのバッファー時間をオーバーライド
するには、次に示すように、まず SoundLoaderContext クラスの新しいインスタンスを作成し、その bufferTime プロパ
ティを設定し、Sound.load() メソッドにパラメーターとして渡します。
import flash.media.Sound;import flash.media.SoundLoaderContext;
import flash.net.URLRequest;
var s:Sound = new Sound();var req:URLRequest = new URLRequest("bigSound.mp3");
var context:SoundLoaderContext = new SoundLoaderContext(8000, true);s.load(req, context);s.play();サウンドの再生時において、Flash Player および AIR はサウンドバッファーを同じサイズか、それ以上のサイズに維持します。サウンドデータが再生速度よりも速くロードされると、再生は中断することなく続行します。しかし、ネットワークの制限によりデータの読み込み速度が低下すると、再生ヘッドがサウンドバッファーの最後に達する場合があります。その場合、再生は一時停止しますが、サウンドデータが読み込まれると自動的に再開します。

Flash Player または AIR がデータのロードを待機しているために再生が中断しているのかどうかを確認するには、Sound.isBuffering プロパティを使用します。

動的に生成されたオーディオの操作
Flash Player 10 以降、Adobe AIR 1.5 以降
注意：オーディオの動的生成機能は、Flash Player 10 および Adobe AIR 1.5 以降で使用できます。
既存のサウンドを読み込んだりストリーミングしたりする代わりに、オーディオデータを動的に生成することもできます。
オーディオデータを生成するには、Sound オブジェクトの sampleData イベントのイベントリスナーを割り当てる必要があ
ります sampleData イベントは、flash.events パッケージの SampleDataEvent クラスで定義されています。この環境では、Sound オブジェクトはファイルからサウンドデータを読み込みません。代わりに、このイベントに割り当てた関数を使用して自身にストリーミングされるサウンドデータのソケットとして機能します。

Sound オブジェクトに sampleData イベントリスナーを追加すると、サウンドバッファーに追加するデータが定期的に要求されます。このバッファーには、Sound オブジェクトで再生するデータが格納されます。Sound オブジェクトの play() メ
ソッドを呼び出すと、新しいサウンドデータの要求時に sampleData イベントが送出されます（Sound オブジェクトがファ
イルから mp3 データを読み込んでいない場合のみ）。
SampleDataEvent オブジェクトには、data プロパティがあります。イベントリスナーでは、この data オブジェクトに
ByteArray オブジェクトを書き込みます。このオブジェクトに書き込んだバイト配列は、バッファーに格納されたサウンド
データに追加され、Sound オブジェクトで再生されます。バッファー内のバイト配列は、-1 〜 1 の浮動小数点数値のストリームです。各浮動小数点数値は、サウンドサンプルの 1 つのチャンネル（左または右）の振幅を表します。サウンドは、1
秒間に 44,100 回サンプリングされます。各サンプルには、バイト配列の浮動小数点数値としてインターリーブされた、左または右のチャンネルが格納されます。
ハンドラー関数では、ByteArray.writeFloat() メソッドを使用して、data プロパティ（sampleData イベント）に書き込みます。
例えば、次のコードでは正弦波が生成されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド429

サウンドの操作

var mySound:Sound = new Sound();
mySound.addEventListener(SampleDataEvent.SAMPLE_DATA, sineWaveGenerator);
mySound.play();function sineWaveGenerator(event:SampleDataEvent):void{for (var i:int = 0; i < 8192; i++){var n:Number = Math.sin((i + event.position) / Math.PI / 4);
event.data.writeFloat(n);event.data.writeFloat(n);}}Sound.play() を呼び出すと、アプリケーションがイベントハンドラーの呼び出しを開始し、サウンドサンプルデータを要求します。データの供給を中止するか、SoundChannel.stop() を呼び出すまでは、サウンドが再生される間、アプリケーション
はイベントを送信し続けます。
イベントの待ち時間はプラットフォームにより異なりますが、Flash Player および AIR の将来のバージョンでは変更できるようになります。特定の待ち時間に依存するのではなく、計算して求めてください。待ち時間を計算するには、次の式を使用します。
(SampleDataEvent.position / 44.1) - SoundChannelObject.position

イベントリスナーの各呼び出しでは、SampleDataEvent オブジェクトの data プロパティに 2048 〜 8192 サンプルを指定します。最適なパフォーマンスを得るためには、できるだけ多くのサンプル数を指定します（最大 8192）。サンプル数が少な
いと、再生中にクリック / ポップが発生する可能性が高くなります。この動作は、プラットフォームによって異なります。
また、ブラウザーのサイズを変更したときなど、様々な状況で発生します。2048 サンプルだけを指定した場合、あるプラットフォームで機能するコードが、別のプラットフォームで実行した場合は機能しなくなる可能性があります。できるだけ待ち時間を小さくする必要がある場合は、データの量をユーザーが選択できるようにすることを検討してください。

sampleData イベントリスナーの 1 回の呼び出しごとのサンプル数を 2048 未満にすると、残りのサンプルの再生後にアプリ
ケーションが停止します。SoundChannel オブジェクトは SoundComplete イベントを送出します。

MP3 データのサウンドの変更
Flash Player 10 以降、Adobe AIR 1.5 以降
Sound オブジェクトからデータを抽出するには、Sound.extract() メソッドを使用します。そのデータを使用（および変更）
して、再生用に別の Sound オブジェクトの動的ストリームに書き込むことができます。例えば、次のコードでは、読み込んだ MP3 ファイルのバイトを、フィルター関数 upOctave() を使用して渡しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

430

サウンドの操作

var mySound:Sound = new Sound();var sourceSnd:Sound = new Sound();var urlReq:URLRequest = new URLRequest("test.mp3");sourceSnd.load(urlReq);
sourceSnd.addEventListener(Event.COMPLETE, loaded);function loaded(event:Event):void{
mySound.addEventListener(SampleDataEvent.SAMPLE_DATA, processSound);mySound.play();}function processSound(event:SampleDataEvent):void{
var bytes:ByteArray = new ByteArray();sourceSnd.extract(bytes, 8192);
event.data.writeBytes(upOctave(bytes));}function upOctave(bytes:ByteArray):ByteArray{var returnBytes:ByteArray = new ByteArray();
bytes.position = 0;
while(bytes.bytesAvailable > 0){
returnBytes.writeFloat(bytes.readFloat());
returnBytes.writeFloat(bytes.readFloat());
if (bytes.bytesAvailable > 0){bytes.position += 8;}}
return returnBytes;}

生成されたサウンドに関する制限事項
Flash Player 10 以降、Adobe AIR 1.5 以降
Sound オブジェクトと共に sampleData イベントリスナーを使用する場合、Sound の他のメソッドのうち、使用できるのはSound.extract() と Sound.play() だけです。その他のメソッドまたはプロパティを呼び出すと、例外が発生します。
SoundChannel オブジェクトのすべてのメソッドおよびプロパティは、引き続き使用できます。

サウンドの再生Flash Player 9 以降、Adobe AIR 1.0 以降
次に示すように、読み込んだサウンドは Sound オブジェクトの Sound.play() メソッドを呼び出すだけで再生できます。
var snd:Sound = new Sound(new URLRequest("smallSound.mp3"));
snd.play();

ActionScript 3.0 を使用してサウンドを再生しているときに、次の操作を実行することができます。

•

特定の開始位置からサウンドを再生する•サウンドを一時停止し、後で同じ位置から再生を再開する•

サウンドの再生が終了する正確な時間を知る•

サウンドの再生の進行状況を追跡する

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

431

サウンドの操作•

サウンドの再生中に音量またはバランスを変更する

再生中にこれらの操作を実行するには、SoundChannel、SoundMixer、SoundTransform の各クラスを使用します。

SoundChannel クラスは、単一のサウンドの再生を制御します。SoundChannel.position プロパティは再生ヘッドと考えることができ、サウンドデータ内で再生中の現在位置を示します。
アプリケーションが Sound.play() メソッドを呼び出すと、再生を制御するために SoundChannel クラスの新しいインスタン
スが作成されます。
アプリケーションは Sound.play() メソッドの startTime パラメーターとして、ミリ秒の単位で表した特定の開始位置を渡すことで、その位置からサウンドを再生できます。また、Sound.play() メソッドの loops パラメーターで数値を渡すことで、間を置かずにサウンドを繰り返して再生する固定回数を指定できます。

startTime パラメーターおよび loops パラメーターと共に Sound.play() メソッドが呼び出されると、次のコードに示すように、同じ開始位置からサウンドが繰り返し再生されます。
var snd:Sound = new Sound(new URLRequest("repeatingSound.mp3"));
snd.play(1000, 3);

この例では、サウンドの先頭から 1 秒後の位置から連続して 3 回、サウンドを再生します。

サウンドの一時停止と再開
Flash Player 9 以降、Adobe AIR 1.0 以降
歌やポッドキャストのような長いサウンドをアプリケーションで再生する場合、通常は、ユーザーがサウンドの再生を一時停止および再開できるようにする必要があります。サウンドは、ActionScript での再生中は文字どおり一時停止することはできません。サウンドは停止されるだけです。ただし、サウンドの再生はどこからでも開始できます。サウンドを停止した
位置を記録しておき、後でその位置からサウンドの再生を開始できます。
例えば、次のようなサウンドファイルを読み込んで再生するコードがあるとします。
var snd:Sound = new Sound(new URLRequest("bigSound.mp3"));var channel:SoundChannel = snd.play();

サウンドの再生中、SoundChannel.position プロパティは再生中のサウンドファイルの位置を示します。アプリケーションでは次のようにして、サウンドの再生を停止する前に位置の値を保存できます。
var pausePosition:int = channel.position;
channel.stop();

サウンドの再生を再開するには、保存しておいた位置の値を渡します。サウンドは停止したときと同じ位置から再開されます。
channel = snd.play(pausePosition);

再生の監視
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションは、別のサウンドを再生、または前回の再生で使用されたリソースの一部をクリーンアップするため、サウンドの再生が停止したタイミングを認識する必要がある場合もあります。SoundChannel クラスは、サウンドが再生を終了したときに Event.SOUND_COMPLETE イベントを送出します。次に示すように、アプリケーションは、このイベントを監視し、適切なアクションを実行することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

432

サウンドの操作

import flash.events.Event;import flash.media.Sound;import flash.net.URLRequest;
var snd:Sound = new Sound();var req:URLRequest = new URLRequest("smallSound.mp3");
snd.load(req);var channel:SoundChannel = snd.play();
channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete);public function onPlaybackComplete(event:Event){
trace("The sound has finished playing.");}SoundChannel クラスは、再生中には progress イベントを送出しません。再生の進行状況を報告するために、アプリケー
ションで独自のタイミングメカニズムを設定してサウンド再生ヘッドの位置を追跡できます。
サウンドの再生済みの割合を計算するには、SoundChannel.position プロパティの値を、再生しているサウンドデータの長さで割ります。
var playbackPercent:uint = 100 * (channel.position / snd.length);

ただし、このコードが正確な再生済みの割合を報告するのは、再生を開始する前にサウンドデータが完全に読み込まれていた場合のみです。Sound.length プロパティが示すのは、現時点で読み込まれているサウンドデータのサイズであり、サウン
ドファイル全体の最終的なサイズではありません。まだ読み込みが完了していないストリーミングサウンドの再生の進行を追跡するには、サウンドファイル全体の最終的なサイズを推定し、その値を使用して計算する必要があります。サウンド
データの最終的な長さは、次のように Sound オブジェクトの bytesLoaded プロパティと bytesTotal プロパティを使用して推定できます。
var estimatedLength:int =Math.ceil(snd.length / (snd.bytesLoaded / snd.bytesTotal));var playbackPercent:uint = 100 * (channel.position / estimatedLength);

次のコードは大きなサウンドファイルをロードし、再生の進行状況を示すタイミング制御メカニズムとしてEvent.ENTER_FRAME イベントを使用します。ここでは再生率を定期的にレポートします。再生率は、現在位置の値をサウ
ンドデータの合計長で除算することで算出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

433

サウンドの操作

import flash.events.Event;import flash.media.Sound;import flash.net.URLRequest;
var snd:Sound = new Sound();var req:URLRequest = new
URLRequest("http://av.adobe.com/podcast/csbu_dev_podcast_epi_2.mp3");
snd.load(req);var channel:SoundChannel;
channel = snd.play();
addEventListener(Event.ENTER_FRAME, onEnterFrame);channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete);function onEnterFrame(event:Event):void{
var estimatedLength:int =Math.ceil(snd.length / (snd.bytesLoaded / snd.bytesTotal));var playbackPercent:uint =Math.round(100 * (channel.position / estimatedLength));trace("Sound playback is " + playbackPercent + "% complete.");}function onPlaybackComplete(event:Event){
trace("The sound has finished playing.");removeEventListener(Event.ENTER_FRAME, onEnterFrame);}

サウンドデータの読み込みを開始した後、このコードは snd.play() メソッドを呼び出して、結果の SoundChannel オブジェ
クトを channel 変数に格納します。次に、Event.ENTER_FRAME イベントのイベントリスナーをメインアプリケーションに追加し、さらに、再生が完了したときに発生する Event.SOUND_COMPLETE イベントのイベントリスナーをSoundChannel オブジェクトに追加します。
アプリケーションがアニメーションの新しいフレームに到達するたびに、onEnterFrame() メソッドが呼び出されます。

onEnterFrame() メソッドは、ロード済みのデータ量に基づいてサウンドファイルの合計長を予測し、現在の再生率を算出して表示します。
サウンド全体が再生されると onPlaybackComplete() メソッドが実行され、Event.ENTER_FRAME イベントのイベントリス
ナーが削除されるので、再生が完了すると進行状況の更新情報は表示されなくなります。

Event.ENTER_FRAME イベントは、1 秒間に何度も送出することができます。場合によっては、頻繁に再生の進行状況を表示しないこともあります。そのような場合は、flash.util.Timer クラスを使用して独自のタイミング制御メカニズムを設定することができます。詳しくは、1 ページの「日付と時刻の操作」を参照してください。

ストリーミングサウンドの停止
Flash Player 9 以降、Adobe AIR 1.0 以降
ストリーミング中のサウンド、つまり再生中にまだ読み込まれているサウンドの再生処理では、他の場合とは異なる動作が発生します。ストリーミングサウンドを再生している SoundChannel インスタンスで SoundChannel.stop() メソッドが呼び出されると、サウンドの再生は 1 フレーム分停止し、次のフレームでサウンドを最初から再開します。このようなことが発生するのは、サウンドの読み込み処理が進行中であるためです。ストリーミングサウンドの読み込みと再生の両方を停止す
るには、Sound.close() メソッドを呼び出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド434

サウンドの操作

サウンドのロード時および再生時のセキュリティ重要事項
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションによるサウンドデータへのアクセスは、Flash Player および AIR のセキュリティモデルに従って制限できます。各サウンドは、コンテンツ自体のサンドボックス（コンテンツサンドボックス）と、サウンドのロードと再生を行う
アプリケーションまたはオブジェクトのサンドボックス（オーナーサンドボックス）の 2 つの異なるセキュリティサンド
ボックスの制限を受けます。アプリケーションセキュリティサンドボックス内の AIR アプリケーションコンテンツの場合、他のドメインからロードしたサウンドを含むすべてのサウンドは、アプリケーションセキュリティサンドボックス内のコン
テンツにアクセスできます。ただし、他のセキュリティサンドボックス内のコンテンツは、Flash Player で実行中のコンテンツと同じ規則に従います。Flash Player のセキュリティモデルの一般的な情報と、サンドボックスの定義について詳しくは、1004 ページの「セキュリティ」を参照してください。
コンテンツサンドボックスは、詳細なサウンドデータを id3 プロパティを使用してサウンドから抽出するか、またはSoundMixer.computeSpectrum() メソッドから抽出するかを制御します。サウンドファイル自体のロードまたは再生を制限するわけではありません。
サウンドファイルの発生ドメインによって、コンテンツサンドボックスのセキュリティ制限が決定します。一般的に、サウンドファイルがアプリケーションの SWF ファイル、またはサウンドファイルをロードするオブジェクトと同じドメインまたはフォルダーにある場合、アプリケーションまたはオブジェクトには、そのサウンドファイルに対するフルアクセス権が与えられます。サウンドがアプリケーションとは異なるドメインから発生していても、ポリシーファイルを使用することで、コンテンツサンドボックス内に取り入れることができます。
アプリケーションは、checkPolicyFile プロパティを持つ SoundLoaderContext オブジェクトを、Sound.load() メソッドのパ
ラメーターとして渡すことができます。checkPolicyFile プロパティを true に設定すると、Flash Player または AIR は、サウンドのロード元のサーバーでポリシーファイルを検索します。ポリシーファイルが存在し、ロードされる SWF ファイルのドメインへのアクセス権が付与される場合、SWF は、サウンドファイルのロード、Sound オブジェクトの id3 プロパティ
へのアクセス、およびロードされたサウンドの SoundMixer.computeSpectrum() メソッドの呼び出しを行うことができます。
オーナーサンドボックスは、サウンドのローカル再生を制御します。サウンドの再生を開始するアプリケーションまたはオ
ブジェクトによってオーナーサンドボックスが定義されます。

SoundMixer.stopAll() メソッドは、次の基準を満たしている場合、再生中のすべての SoundChannel オブジェクトのサウン
ドを無音にします。

•

サウンドは、同じオーナーサンドボックス内のオブジェクトによって開始されています。

•

サウンドは、SoundMixer.stopAll() メソッドを呼び出すアプリケーションまたはオブジェクトのドメインへのアクセス権を付与するポリシーファイルを持つソースから発生しています。

ただし、AIR アプリケーションでは、アプリケーションセキュリティサンドボックス内のコンテンツ（AIR アプリケーショ
ンと共にインストールされたコンテンツ）は、これらのセキュリティ制限による制約を受けません。

SoundMixer.stopAll() メソッドが再生中のすべてのサウンドを実際に停止するかどうかを確認するために、アプリケーション
で SoundMixer.areSoundsInaccessible() メソッドを呼び出すことができます。このメソッドが値 true を返すと、再生中のサウンドの一部は現在のオーナーサンドボックスの制御の対象外にあるので、SoundMixer.stopAll() メソッドによって停止されません。
SoundMixer.stopAll() メソッドは、外部ファイルからロードされたすべてのサウンドで、再生ヘッドの動作を停止します。ただし、FLA ファイルに埋め込まれ、Flash オーサリングツールによってタイムラインのフレームに関連付けられたサウンド
は、アニメーションが新しいフレームに移動すると再生を再開することがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

435

サウンドの操作

サウンドの音量とバランスの制御
Flash Player 9 以降、Adobe AIR 1.0 以降
個々の SoundChannel オブジェクトは、サウンドの左右のステレオチャンネルを両方とも制御します。MP3 サウンドがモ
ノラルサウンドである場合、SoundChannel オブジェクトの左右のステレオチャンネルの波形は同一になります。
再生中のサウンドの各ステレオチャンネルの振幅を検出するには、SoundChannel オブジェクトの leftPeak プロパティとrightPeak プロパティを使用します。これらのプロパティは、サウンド波形自体のピーク振幅を示します。実際の再生音量を表してはいません。実際の再生音量は、サウンド波形の振幅と、SoundChannel オブジェクトおよび SoundMixer クラス
で設定されている音量値の相関結果です。

SoundChannel オブジェクトの pan プロパティを使用すると、再生中の左右のチャンネルに異なる音量レベルを指定できます。pan プロパティには、-1 から 1 までの値を指定することができます。ここで -1 とは、左チャンネルが最大ボリュームで再生され、右チャンネルが無音になること、そして 1 は右チャンネルが最大ボリュームで再生され、左チャンネルが無音であることを意味します。-1 から 1 までの数値は、左右のチャンネル値に対して相対値を設定します。値が 0 であると、両方のチャンネルで均衡が取れた中程度のボリュームレベルで再生されます。
次のコード例では、SoundTransform オブジェクトを作成し、音量の値を 0.6 に、バランスの値を -1（左チャンネルは最大音量、右チャンネルは消音）に設定しています。SoundTransform オブジェクトが play() メソッドのパラメーターとして渡されます。それにより、SoundTransform オブジェクトは、再生を制御するために新しく作成された SoundChannel オ
ブジェクトに適用されます。
var snd:Sound = new Sound(new URLRequest("bigSound.mp3"));var trans:SoundTransform = new SoundTransform(0.6, -1);
var channel:SoundChannel = snd.play(0, 1, trans);

SoundTransform オブジェクトの pan または volume プロパティを設定し、このオブジェクトを SoundChannel オブジェ
クトの soundTransform プロパティとして適用することで、サウンドの再生中にボリュームとパンを変更することができます。
また、次の例で示すように、SoundMixer クラスの soundTransform プロパティを使用することで、すべてのサウンドのグ
ローバルボリューム値とパン値を一度に設定することもできます。
SoundMixer.soundTransform = new SoundTransform(1, -1);

SoundTransform オブジェクトを使用し、Microphone オブジェクト（440 ページの「サウンド入力のキャプチャ」を参照）、Sprite オブジェクトおよび SimpleButton オブジェクトのボリューム値とパン値を設定することも可能です。
次の例では、サウンドの再生中に左右のチャンネル間でサウンドを交互にパンする方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド436

サウンドの操作

import flash.events.Event;import flash.media.Sound;import flash.media.SoundChannel;
import flash.media.SoundMixer;
import flash.net.URLRequest;
var snd:Sound = new Sound();var req:URLRequest = new URLRequest("bigSound.mp3");
snd.load(req);var panCounter:Number = 0;
var trans:SoundTransform;
trans = new SoundTransform(1, 0);
var channel:SoundChannel = snd.play(0, 1, trans);
channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete);
addEventListener(Event.ENTER_FRAME, onEnterFrame);function onEnterFrame(event:Event):void{trans.pan = Math.sin(panCounter);channel.soundTransform = trans; // or SoundMixer.soundTransform = trans;
panCounter += 0.05;}
function onPlaybackComplete(event:Event):void{
removeEventListener(Event.ENTER_FRAME, onEnterFrame);}

このコードは、まずサウンドファイルをロードし、次に新しい SoundTransform オブジェクトを作成します。このとき、ボリュームを 1（フルボリューム）に、パンを 0（左右で均衡）に設定します。次に、snd.play() メソッドを呼び出し、SoundTransform オブジェクトをパラメーターとして渡します。
サウンドの再生中は、onEnterFrame() メソッドが繰り返し実行されます。onEnterFrame() メソッドは、Math.sin() 関数を使用して -1 から 1 までの値を生成します。この値の範囲は、SoundTransform.pan プロパティで許容される値の範囲となります。SoundTransform オブジェクトの pan プロパティを新しい値に設定した後、チャンネルの soundTransform プロパティ
を、変更後の SoundTransform オブジェクトを使用するように設定します。
このコード例を実行する場合は、ファイル名 bigSound.mp3 をローカルの MP3 ファイルの名前に変更します。その後で例を実行します。まず、左チャンネルの音量が大きくなって右チャンネルの音量が小さくなり、次にはその逆に音量が変化します。
この例では、SoundMixer クラスの soundTransform プロパティを設定することで同じ効果を実現することもできます。ただし、これにより、SoundChannel オブジェクトによって再生されている単独のサウンドだけではなく、再生中のすべてのサウンドのパンが影響を受けます。

サウンドメタデータの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
MP3 形式を使用するサウンドファイルには、サウンドに関する追加データが ID3 タグの形式で含まれることがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

437

サウンドの操作

すべての MP3 ファイルに ID3 メタデータが含まれるわけではありません。Sound オブジェクトが MP3 サウンドファイル
をロードすると、サウンドファイルに ID3 メタデータが含まれる場合でも、Event.ID3 イベントが送出されます。ランタイ
ムエラーを防ぐため、アプリケーションでは、Event.ID3 イベントを受信するのを待ってから、読み込まれたサウンドのSound.id3 プロパティにアクセスする必要があります。
次のコードでは、サウンドファイルの ID3 メタデータが読み込まれたことを認識する方法を示します。
import flash.events.Event;import flash.media.ID3Info;
import flash.media.Sound;var s:Sound = new Sound();s.addEventListener(Event.ID3, onID3InfoReceived);
s.load("mySound.mp3");function onID3InfoReceived(event:Event){var id3:ID3Info = event.target.id3;
trace("Received ID3 Info:");for (var propName:String in id3){
trace(propName + " = " + id3[propName]);}}

このコードは、まず Sound オブジェクトを作成し、Event.ID3 イベントを監視するよう指示します。サウンドファイルのID3 メタデータが読み込まれると、onID3InfoReceived() メソッドが呼び出されます。onID3InfoReceived() メソッドに渡される Event オブジェクトのターゲットは元の Sound オブジェクトなので、メソッドは Sound オブジェクトの id3 プロパティを取得し、指定されたすべてのプロパティで反復処理を実行して値をトレースします。

生のサウンドデータへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
SoundMixer.computeSpectrum() メソッドを使用すると、現在再生されている波形の生のサウンドデータを、アプリケーショ
ンで読み取ることができます。複数の SoundChannel オブジェクトが再生中であれば、SoundMixer.computeSpectrum() メ
ソッドはすべての SoundChannel オブジェクトを合成したサウンドデータを示します。
サウンドデータは、512 バイトのデータを含む ByteArray オブジェクトとして返されます。このデータはそれぞれ -1 から 1までの浮動小数点値を持ちます。これらの値は、再生中のサウンド波形のポイントの振幅を示します。値はそれぞれが 256個の値から成る 2 つのグループとして提供され、第 1 のグループは左ステレオチャンネルを表し、第 2 のグループは右ステ
レオチャンネルを表します。

SoundMixer.computeSpectrum() メソッドは、FFTMode パラメーターが true に設定されている場合は、波形データではなく周波数スペクトルデータを返します。周波数スペクトルは、最低周波数から最高周波数へと、サウンドの周波数順に並べられた振幅を示します。波形データを周波数スペクトルデータに変換するには、高速フーリエ変換（FFT）が使用されます。
結果の周波数スペクトルの値は、0 から約 1.414（2 の平方根）の範囲になります。
次の図は、computeSpectrum() メソッドから返されるデータを、FFTMode パラメーターが true の場合と false の場合で比較したものです。この図でデータが使用されたサウンドでは、左チャンネルには大音量のベースサウンドが、右チャンネルにはドラム音が流れています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

438

サウンドの操作SoundMixer.computeSpectrum() メソッドから返される値
A. fftMode=true B. fftMode=false

computeSpectrum() メソッドは、より低いビットレートで再サンプリングされたデータを返すこともできます。一般にはこのようにすると、音の細部は損なわれますが、より滑らかな波形データまたは周波数データが得られます。
computeSpectrum() メソッドのデータをサンプリングするレートは、stretchFactor パラメーターで制御します。stretchFactor
パラメーターを 0（デフォルト値）に設定すると、サウンドデータは 44.1 kHz のレートでサンプリングされます。
stretchFactor パラメーターの値が増えるに従い、レートは半減します。つまり、値が 1 であればレートは 22.05 KHz、値が 2 であればレートは 11.025 KHz となり、以下同様です。computeSpectrum() メソッドは、stretchFactor 値が高い場合は、ステレオチャンネルごとに 256 バイトを返します。
SoundMixer.computeSpectrum() メソッドにもいくつか制限があります。

•

マイクまたは RTMP ストリームからのサウンドデータはグローバルな SoundMixer オブジェクトを通過しないので、SoundMixer.computeSpectrum() メソッドはこれらのソースからデータを返しません。

•

再生中の 1 つまたは複数のサウンドが現在のコンテンツサンドボックスの外部のソースから発生している場合は、セキュ
リティ制限により、SoundMixer.computeSpectrum() メソッドはエラーをスローします。SoundMixer.computeSpectrum()
メソッドのセキュリティ制限について詳しくは、434 ページの「サウンドのロード時および再生時のセキュリティ重要事項」および 1028 ページの「ロードされたメディアへのデータとしてのアクセス」を参照してください。

ただし、AIR アプリケーションでは、アプリケーションセキュリティサンドボックス内のコンテンツ（AIR アプリケーショ
ンと共にインストールされたコンテンツ）は、これらのセキュリティ制限による制約を受けません。

簡易なサウンドビジュアライザの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
次の例は、SoundMixer.computeSpectrum() メソッドを使用し、各フレームでアニメーション化されるサウンド波形のチャー
トを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド439

サウンドの操作

import flash.display.Graphics;
import flash.events.Event;import flash.media.Sound;import flash.media.SoundChannel;
import flash.media.SoundMixer;
import flash.net.URLRequest;
const PLOT_HEIGHT:int = 200;
const CHANNEL_LENGTH:int = 256;var snd:Sound = new Sound();var req:URLRequest = new URLRequest("bigSound.mp3");
snd.load(req);var channel:SoundChannel;
channel = snd.play();
addEventListener(Event.ENTER_FRAME, onEnterFrame);
snd.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete);var bytes:ByteArray = new ByteArray();function onEnterFrame(event:Event):void{
SoundMixer.computeSpectrum(bytes, false, 0);
var g:Graphics = this.graphics;
g.clear();g.lineStyle(0, 0x6600CC);
g.beginFill(0x6600CC);
g.moveTo(0, PLOT_HEIGHT);
var n:Number = 0;// left channel
for (var i:int = 0; i < CHANNEL_LENGTH; i++){n = (bytes.readFloat() * PLOT_HEIGHT);
g.lineTo(i * 2, PLOT_HEIGHT - n);}g.lineTo(CHANNEL_LENGTH * 2, PLOT_HEIGHT);
g.endFill();// right channelg.lineStyle(0, 0xCC0066);
g.beginFill(0xCC0066, 0.5);
g.moveTo(CHANNEL_LENGTH * 2, PLOT_HEIGHT);
for (i = CHANNEL_LENGTH; i > 0; i--){n = (bytes.readFloat() * PLOT_HEIGHT);
g.lineTo(i * 2, PLOT_HEIGHT - n);}g.lineTo(0, PLOT_HEIGHT);
g.endFill();}function onPlaybackComplete(event:Event){removeEventListener(Event.ENTER_FRAME, onEnterFrame);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

440

サウンドの操作

この例では、まずサウンドファイルをロードして再生し、次にサウンドの再生中に onEnterFrame() メソッドをトリガーする

Event.ENTER_FRAME イベントを監視します。onEnterFrame() メソッドは、サウンド波形データを bytes ByteArray オブ
ジェクトに格納する SoundMixer.computeSpectrum() メソッドを呼び出すことで開始されます。
サウンド波形は、ベクター描画 API によってプロットされます。for ループは、左ステレオチャンネルを表す最初の 256 バ
イトのデータ値を順次実行し、Graphics.lineTo() メソッドを使用してポイントとポイントの間に線を描画します。2 つめのfor ループは、次の 256 バイトのデータ値を順次実行し、今回は右から左へと逆順にプロットします。この結果として生成される波形プロットから、次に示すような面白い鏡像効果が生まれます。

サウンド入力のキャプチャ
Flash Player 9 以降、Adobe AIR 1.0 以降
Microphone クラスにより、アプリケーションはユーザーのシステム上にあるマイクなどのサウンド入力デバイスに接続し、入力オーディオをシステムのスピーカーにブロードキャストしたり、オーディオデータを Flash Media Server などのリモートサーバーに送信したりできます。マイクから未処理のオーディオデータにアクセスし、そのデータを録音または処理することができます。また、システムのスピーカーに直接オーディオを送信したり、圧縮したオーディオデータをリモートサーバーに送信したりすることもできます。リモートサーバーに送信するデータには、Speex または Nellymoser コーデッ
クを使用できます（Speex コーデックは、Flash Player 10 および Adobe AIR 1.5 以降でサポートされています）。
関連項目

Michael Chaize：AIR, Android, and the Microphone
Christophe Coenraets：Voice Notes for Android

マイクロフォンへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
Microphone クラスにはコンストラクターメソッドはありません。代わりに、次のように静的な
Microphone.getMicrophone() メソッドを使用し、新しい Microphone インスタンスを取得します。
var mic:Microphone = Microphone.getMicrophone();パラメーターを指定せずに Microphone.getMicrophone() メソッドを呼び出すと、ユーザーのシステムで検出された最初のサ
ウンド入力デバイスが返されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

441

サウンドの操作システムには複数のサウンド入力デバイスを接続できます。アプリケーションでは、Microphone.names プロパティを使用して、使用可能なすべてのサウンド入力デバイスの名前の配列を取得できます。次に、Microphone.getMicrophone() メソッド
を、配列にあるデバイスの名前のインデックス値と一致する index パラメーターを指定して呼び出します。
システムには、マイクロフォンまたは他のサウンド入力デバイスが接続されていない場合があります。Microphone.names プ
ロパティまたは Microphone.getMicrophone() メソッドを使用すると、サウンド入力デバイスがインストールされているかど
うかを確認できます。サウンド入力デバイスがインストールされていない場合は names 配列の長さがゼロになり、
getMicrophone() メソッドは null 値を返します。
アプリケーションが Microphone.getMicrophone() メソッドを呼び出すと、Flash Player の設定ダイアログボックスが表示されます。ここでは、Flash Player にシステムのカメラおよびマイクへのアクセスを許可するかどうかを指定することができます。このダイアログの「許可」または「拒否」ボタンをクリックすると、StatusEvent が送出されます。その StatusEvent
インスタンスの code プロパティは、次のように、マイクのアクセスが許可されているか、拒否されているかを示します。
import flash.media.Microphone;var mic:Microphone = Microphone.getMicrophone();mic.addEventListener(StatusEvent.STATUS, this.onMicStatus);
function onMicStatus(event:StatusEvent):void{if (event.code == "Microphone.Unmuted"){
trace("Microphone access was allowed.");}else if (event.code == "Microphone.Muted"){
trace("Microphone access was denied.");}}

アクセスが許可されている場合は、StatusEvent.code プロパティに "Microphone.Unmuted" があり、アクセスが拒否されている場合は "Microphone.Muted" があります。

Microphone.muted プロパティは、ユーザーがマイクへのアクセスを許可した場合は true に、拒否した場合は false にそれぞれ設定されます。ただし、muted プロパティは、StatusEvent が送出されるまで Microphone インスタンスに設定されない
ので、Microphone.muted プロパティを確認するには StatusEvent.STATUS イベントが送出されるまで待機する必要があります。

Flash Player で設定ダイアログを表示するには、ダイアログの大きさに合わせてアプリケーションウィンドウのサイズを拡大する必要があります（少なくとも 215 x 138 ピクセル）。この操作を行わないと、アクセスが自動的に拒否されます。
AIR アプリケーションサンドボックスで実行されるコンテンツでは、マイクにアクセスするためにユーザーの許可は不要です。したがって、マイクのミュートおよびミュート解除の status イベントは送出されません。アプリケーションサンドボッ
クスの外部の AIR で実行されるコンテンツではユーザーの許可が必要なので、これらの status イベントを送出できます。

マイクロフォンのオーディオからローカルスピーカへのルーティング
Flash Player 9 以降、Adobe AIR 1.0 以降
Microphone.setLoopback() メソッドを呼び出してパラメーター値に true を指定することで、マイクロフォンからのオーディ
オ入力をローカルシステムのスピーカにルーティングできます。
ローカルマイクからのサウンドがローカルスピーカーに転送されると、オーディオフィードバックループが発生する恐れがあります。これにより、きしんだような音が鳴り、サウンドハードウェアが損傷する可能性もあります。

Microphone.setUseEchoSuppression() メソッドを呼び出してパラメーターに true を指定すると、オーディオフィードバック

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

442

サウンドの操作が発生するリスクは低下しますが、完全に除去することはできません。ヘッドホンなど、スピーカー以外のものからサウンドが再生されることが確実な場合を除き、Microphone.setLoopback(true) を呼び出す前に必ずMicrophone.setUseEchoSuppression(true) を呼び出すことをお勧めします。
次のコードでは、ローカルマイクロフォンからローカルシステムのスピーカにオーディオをルーティングする方法を示します。
var mic:Microphone = Microphone.getMicrophone();mic.setUseEchoSuppression(true);mic.setLoopBack(true);

マイクロフォンのオーディオの変更
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションでは、マイクロフォンから入力されたオーディオデータを 2 つの方法で変更できます。1 つ目は、入力サ
ウンドのゲインを変更することです。これにより、入力値が指定量の分だけ効果的に増加するので、サウンドを大きくまたは小さくすることができます。Microphone.gain プロパティは、0 以上 100 以下の数値を受け入れます。50 という値は 1 を掛けるのと同じで、通常の音量を指定します。値 0 は 0 を掛けるのと同じで、結果として入力オーディオは消音されます。50
より大きい値を指定すると、通常の音量より大きくなります。
アプリケーションでは、入力オーディオのサンプリングレートを変更することもできます。サンプリングレートを高くする
ほどサウンドの品質は向上しますが、データストリームの密度も高くなり、送信と格納に必要なリソースの量が増加します。

Microphone.rate プロパティは、キロヘルツ（kHz）単位で測定されたオーディオサンプリングレートを表します。デフォル
トのサンプリングレートは 8 kHz です。マイクロフォンがこれより高いレートをサポートしている場合は、Microphone.rate
プロパティに 8 kHz より高い値を設定できます。例えば、Microphone.rate プロパティの値を 11 に設定すると、サンプル
レートは 11 kHz になり、22 に設定すると、22 kHz になります。使用可能なサンプリングレートは、選択したコーデック
によって異なります。Nellymoser コーデックを使用する場合は、サンプリングレートとして 5、8、11、16、22 および 44
kHz を指定できます。Speex コーデックを使用する場合は（Flash Player 10 および Adobe AIR 1.5 以降で使用可能）、16
kHz のみ指定できます。

マイクロフォンの動作の検出Flash Player 9 以降、Adobe AIR 1.0 以降
帯域幅と処理のリソースを節約するため、Flash Player は、マイクからサウンドが伝送されていない状態を検知しようとします。一定期間にわたり、マイクのアクティビティレベルが無音レベルのしきい値を下回っていると、Flash Player はオー
ディオ入力の伝送を停止し、代わりにシンプルな ActivityEvent を送出します。Speex コーデックを使用する場合（Flash

Player 10 および Adobe AIR 1.5 以降で使用可能）、オーディオデータの転送が連続的に実行されるようにするには無音レベ
ルを 0 に設定してください。Speex の音声動作検出によって、帯域幅が自動的に軽減されます。
注意：アプリケーションでマイクを監視している場合、Microphone オブジェクトは Activity イベントのみを送出します。
したがって、setLoopBack( true ) を呼び出さない場合は、サンプルデータイベントのリスナーを追加するか、NetStream オ
ブジェクトにマイクを付加してください。これで、activity イベントは送出されません。

Microphone クラスの 3 つのプロパティを使用して、動作の検出を監視および制御します。

•

読み取り専用の activityLevel プロパティは、マイクロフォンが検出しているサウンドの大きさを、0 〜 100 のスケールで示します。

• silenceLevel プロパティは、マイクを有効にするために必要なサウンド量を指定し、ActivityEvent.ACTIVITY イベントを送出します。silenceLevel プロパティも 0 〜 100 のスケールを使用し、デフォルト値は 10 です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

443

サウンドの操作• silenceTimeout プロパティは、ActivityEvent.ACTIVITY イベントが送出されてマイクが無音状態であると判断されるまで、アクティビティレベルが無音レベルを下回る時間をミリ秒単位で指定します。silenceTimeout のデフォルト値は2000 です。
Microphone.silenceLevel プロパティと Microphone.silenceTimeout プロパティはどちらも読み取り専用ですが、Microphone.setSilenceLevel() メソッドを使用して値を変更できます。
場合によっては、新しい動作が検出されたときにマイクロフォンをアクティブにする処理過程で短い遅延が発生する可能性があります。常にマイクロフォンをアクティブにしておくことで、アクティブ化に伴うこのような遅延を除去できます。

silenceLevel パラメーターをゼロに設定して Microphone.setSilenceLevel() メソッドを呼び出すと、サウンドが検知されなくてもマイクを常に有効にし、オーディオデータを継続的に収集するよう Flash Player に指示することができます。逆に、
silenceLevel パラメーターを 100 に設定すると、マイクロフォンがアクティブにならなくなります。
次の例では、マイクロフォンに関する情報を表示し、Microphone オブジェクトが送出する activity イベントと status イベ
ントを報告します。
import flash.events.ActivityEvent;import flash.events.StatusEvent;import flash.media.Microphone;var deviceArray:Array = Microphone.names;
trace("Available sound input devices:");for (var i:int = 0; i < deviceArray.length; i++){trace(" " + deviceArray[i]);}var mic:Microphone = Microphone.getMicrophone();mic.gain = 60;
mic.rate = 11;
mic.setUseEchoSuppression(true);mic.setLoopBack(true);mic.setSilenceLevel(5, 1000);
mic.addEventListener(ActivityEvent.ACTIVITY, this.onMicActivity);
mic.addEventListener(StatusEvent.STATUS, this.onMicStatus);
var micDetails:String = "Sound input device name: " + mic.name + '\n';micDetails += "Gain: " + mic.gain + '\n';micDetails += "Rate: " + mic.rate + " kHz" + '\n';micDetails += "Muted: " + mic.muted + '\n';micDetails += "Silence level: " + mic.silenceLevel + '\n';micDetails += "Silence timeout: " + mic.silenceTimeout + '\n';micDetails += "Echo suppression: " + mic.useEchoSuppression + '\n';trace(micDetails);
function onMicActivity(event:ActivityEvent):void{
trace("activating=" + event.activating + ", activityLevel=" +mic.activityLevel);}function onMicStatus(event:StatusEvent):void{
trace("status: level=" + event.level + ", code=" + event.code);}

上記のコード例を実行する際は、システムのマイクに向かって発話するか音を出し、コンソールまたはデバッグウィンドウに表示されるトレースステートメントを確認します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド444

サウンドの操作

メディアサーバーとのオーディオの送受信Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Media Server（FMS）のようなストリーミングメディアサーバーと共に ActionScript を使用すると、オーディオ機
能が追加されます。
具体的には、Microphone オブジェクトを NetStream オブジェクトに付加し、ユーザーのマイクからサーバーに直接デー
タを送信することができます。オーディオデータはサーバーからアプリケーションにストリーミングされ、MovieClip の一部として、または Video オブジェクトを使用して再生されます。

Speex コーデックは、Flash Player 10 および Adobe AIR 1.5 以降で使用できます。メディアサーバーに送信されるオー
ディオの圧縮に使用するコーデックを指定するには、Microphone オブジェクトの codec プロパティを設定します。このプ
ロパティには、SoundCodec クラスで列挙されている 2 つの値を設定できます。codec プロパティを SoundCodec.SPEEX に設定すると、オーディオの圧縮時に Speex コーデックスが選択されます。このプロパティを SoundCodec.NELLYMOSER（デフォルト）に設定すると、オーディオの圧縮に Nellymoser コーデックが選択されます。
詳しくは、www.adobe.com/go/learn_fms_docs_jp でオンラインの Flash Media Server ドキュメントを参照してください。

マイクサウンドデータのキャプチャ
Flash Player 10.1 以降、Adobe AIR 2 以降
Flash Player 10.1 および AIR 2 以降では、マイクからのデータを浮動小数点値のバイト配列としてキャプチャできます。値はそれぞれモノラルオーディオデータの 1 つのサンプルを表します。
モノラルデータを取得するには、Microphone オブジェクトの sampleData イベントのイベントリスナーを設定します。
Microphone オブジェクトは、マイクのバッファにサウンドサンプルが入力されると、sampleData イベントを定期的に送出します。SampleDataEvent オブジェクトには、サウンドサンプルのバイト配列である data プロパティがあります。サンプ
ルは、それぞれが浮動小数点値として表現され、モノラルサウンドサンプルを表します。
次のコードでは、マイクサウンドデータが soundBytes という ByteArray オブジェクトにキャプチャされます。
var mic:Microphone = Microphone.getMicrophone();mic.setSilenceLevel(0, DELAY_LENGTH);
mic.addEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler);function micSampleDataHandler(event:SampleDataEvent):void {while(event.data.bytesAvailable) {var sample:Number = event.data.readFloat();soundBytes.writeFloat(sample);}}

サンプルバイトは、Sound オブジェクトの再生オーディオとして再利用できます。再利用する場合は、Microphone オブ
ジェクトの rate プロパティを 44 に設定します。これは、Sound オブジェクトで使用されるサンプルレートです（低いレートでキャプチャされたマイクサンプルを、Sound オブジェクトに必要な 44 kHz のレートに変換することもできます）。また、Microphone オブジェクトではモノラルのサンプルがキャプチャされることを覚えておいてください。Sound オブジェ
クトではステレオサウンドを使用するため、Microphone オブジェクトによってキャプチャされたバイトはそれぞれ Sound
オブジェクトに 2 回ずつ書き込む必要があります。次の例では、4 秒のマイクデータをキャプチャし、Sound オブジェクトを使用して再生します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

445

サウンドの操作

const DELAY_LENGTH:int = 4000;
var mic:Microphone = Microphone.getMicrophone();mic.setSilenceLevel(0, DELAY_LENGTH);
mic.gain = 100;
mic.rate = 44;
mic.addEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler);var timer:Timer = new Timer(DELAY_LENGTH);
timer.addEventListener(TimerEvent.TIMER, timerHandler);
timer.start();function micSampleDataHandler(event:SampleDataEvent):void{
while(event.data.bytesAvailable){
var sample:Number = event.data.readFloat();soundBytes.writeFloat(sample);}}var sound:Sound = new Sound();var channel:SoundChannel;
function timerHandler(event:TimerEvent):void{
mic.removeEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler);
timer.stop();soundBytes.position = 0;
sound.addEventListener(SampleDataEvent.SAMPLE_DATA, playbackSampleHandler);channel.addEventListener( Event.SOUND_COMPLETE, playbackComplete );channel = sound.play();}function playbackSampleHandler(event:SampleDataEvent):void{for (var i:int = 0; i < 8192 && soundBytes.bytesAvailable > 0; i++){trace(sample);var sample:Number = soundBytes.readFloat();event.data.writeFloat(sample);
event.data.writeFloat(sample);}}function playbackComplete( event:Event ):void{
trace( "Playback finished.");}サウンドサンプルデータからサウンドを再生する方法について詳しくは、428 ページの「動的に生成されたオーディオの操作」を参照してください。

サウンドの例：Podcast Player
Flash Player 9 以降、Adobe AIR 1.0 以降
ポッドキャストとは、オンデマンドで、またはサブスクリプションによってインターネット配信されるサウンドファイルです。通常、ポッドキャストは、ポッドキャストチャンネルとも呼ばれるシリーズの一部としてパブリッシュされています。
ポッドキャストエピソードは、1 分で終わるものから数時間かかるものまであるため、再生しながらストリーミングされま

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド446

サウンドの操作す。ポッドキャストエピソードは別名アイテムとも呼ばれ、多くの場合は MP3 ファイル形式で配信されます。ビデオポッド
キャストも一般的ではありますが、このサンプルアプリケーションでは MP3 ファイルを使用するオーディオポッドキャス
トのみを再生します。
この例は、フル機能を備えたポッドキャストアグリゲーターアプリケーションではありません。例えば、このアプリケー
ションは特定のポッドキャストへのサブスクリプションを管理したり、アプリケーションの次回実行時のために、ユーザー
がどのポッドキャストを聴いていたかを覚えるということはありません。だたし、より多くの機能を備えたポッドキャスト
アグリゲーターのたたき台として使用することができます。

Podcast Player の例では、次の ActionScript プログラミング手法を示します。

•

外部 RSS フィードの読み取りと、XML コンテンツの解析• SoundFacade クラスを作成することによる、サウンドファイルのロードと再生の簡便化•

サウンド再生の進行状況の表示•

サウンド再生の一時停止と再開

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。Podcast Player アプリケーションのファイルは、Samples/PodcastPlayer フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

PodcastPlayer.mxml

アプリケーションのユーザーインターフェイスです（Flex 用の MXML、または Flash 用の FLA）。

またはPodcastPlayer.fla
comp/example/progra ポッドキャストプレーヤー用のユーザーインターフェイスロジックを含んだドキュメントクラスです（Flash 専用）。
mmingas3/podcastpla
yer/PodcastPlayer.asSoundPlayer.mxml

再生ボタンとプログレスバーを表示し、サウンド再生を制御する MXML コンポーネントです（Flex 専用）。

main.css

アプリケーションユーザーインターフェイスのスタイルです（Flex 専用）。

images/

ボタンのスタイル設定に使用するアイコンです（Flex 専用）。

comp/example/progra サウンドプレーヤー用のユーザーインターフェイスロジックを含んだ、SoundPlayer ムービークリップシンボルのクラmmingas3/podcastpla スです（Flash 専用）。
yer/SoundPlayer.as
comp/example/progra 再生ボタンをデータグリッドセル内に表示するためのカスタムセルレンダラーです（Flash 専用）。
mmingas3/podcastpla
yer/PlayButtonRender
er.as
com/example/progra RSSChannel クラスと RSSItem クラスに共通のプロパティとメソッドを提供する基本クラスです。
mmingas3/podcastpla
yer/RSSBase.ascom/example/progra RSS チャンネルに関するデータを保有する ActionScript クラスです。
mmingas3/podcastpla
yer/RSSChannel.ascom/example/progra RSS アイテムに関するデータを保有する ActionScript クラスです。
mmingas3/podcastpla
yer/RSSItem.ascom/example/progra アプリケーションのメイン ActionScript クラスです。Sound クラスおよび SoundChannel クラスのメソッドとイベン
mmingas3/podcastpla トをカプセル化し、再生の一時停止と再開をサポートします。
yer/SoundFacade.as

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

447

サウンドの操作

ファイル

説明

com/example/progra リモート URL からデータを取得する ActionScript クラスです。
mmingas3/podcastpla
yer/URLService.as
playerconfig.xml

ポッドキャストチャンネルを示す RSS フィードのリストが記された XML ファイルです。

comp/example/progra 日付の書式指定を簡単に実行するためのクラスです（Flash 専用）。
mmingas3/utils/DateU
til.asポッドキャストチャンネルの RSS データの読み取り
Flash Player 9 以降、Adobe AIR 1.0 以降
Podcast Player アプリケーションは、最初にいくつかのポッドキャストチャンネルとエピソードに関する情報を読み取ります。

1. アプリケーションはまず、ポッドキャストチャンネルのリストを含む XML 設定ファイルを読み取り、チャンネルのリストを表示します。

2. ユーザーがいずれかのポッドキャストチャンネルを選択すると、チャンネルの RSS フィードが読み取られ、チャンネルエ
ピソードのリストが表示されます。
この例では、URLLoader ユーティリティクラスを使用し、テキストベースのデータをリモートまたはローカルのファイルから取得します。Podcast Player はまず URLLoader オブジェクトを作成し、playerconfig.xml ファイルから XML 形式の

RSS フィードのリストを取得します。次に、ユーザーがリストから特定のフィードを選択すると、新しい URLLoader オブ
ジェクトが作成され、フィードの URL から RSS データを読み取ります。

SoundFacade クラスを使用した、サウンドのロードと再生の簡便化
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 のサウンドアーキテクチャは強力ですが、複雑でもあります。サウンドの基本的なロード機能と再生機能しか必要としないアプリケーションでは、シンプルなメソッド呼び出しとイベントによって複雑さを隠すことができるクラスを使用することができます。ソフトウェア設計パターンの分野で、このようなクラスはファサードと呼ばれます。

SoundFacade クラスは、次のタスクを実行するために単一のインターフェイスを提供します。

• Sound オブジェクト、SoundLoaderContext オブジェクト、および SoundMixer クラスを使用したサウンドファイルのロード• Sound オブジェクトと SoundChannel オブジェクトを使用したサウンドファイルの再生• playback progress イベントの送出• Sound オブジェクトと SoundChannel オブジェクトを使用したサウンド再生の一時停止と再開
SoundFacade クラスは、ActionScript サウンドクラスの大半の機能を、複雑さを軽減した形で提供します。
次のコードは、クラス宣言、クラスプロパティおよび SoundFacade() コンストラクターメソッドを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

448

サウンドの操作

public class SoundFacade extends EventDispatcher{
public var s:Sound;public var sc:SoundChannel;
public var url:String;
public var bufferTime:int = 1000;
public var isLoaded:Boolean = false;
public var isReadyToPlay:Boolean = false;
public var isPlaying:Boolean = false;
public var isStreaming:Boolean = true;
public var autoLoad:Boolean = true;
public var autoPlay:Boolean = true;
public var pausePosition:int = 0;
public static const PLAY_PROGRESS:String = "playProgress";public var progressInterval:int = 1000;
public var playTimer:Timer;
public function SoundFacade(soundUrl:String, autoLoad:Boolean = true,
autoPlay:Boolean = true, streaming:Boolean = true,
bufferTime:int = -1):void{
this.url = soundUrl;// Sets Boolean values that determine the behavior of this object
this.autoLoad = autoLoad;this.autoPlay = autoPlay;
this.isStreaming = streaming;// Defaults to the global bufferTime valueif (bufferTime < 0){bufferTime = SoundMixer.bufferTime;}// Keeps buffer time reasonable, between 0 and 30 seconds
this.bufferTime = Math.min(Math.max(0, bufferTime), 30000);if (autoLoad){load();}}

SoundFacade クラスは、独自のイベントを送出できるよう EventDispatcher クラスを拡張します。クラスコードは、まずSound オブジェクトと SoundChannel オブジェクトのプロパティを宣言します。このクラスは、サウンドをストリーミング
するときに使用する、サウンドファイルの URL の値と bufferTime プロパティも格納します。さらに、ロードおよび再生の動作に影響するブールパラメーター値のいくつかを受け取ります。

• autoLoad パラメーターは、オブジェクトが作成されると同時にサウンドのロードを開始するようオブジェクトに指示します。

• autoPlay パラメーターは、十分な量のサウンドデータがロードされると同時に、サウンドの再生を開始するよう指示します。ストリーミングサウンドであれば、bufferTime プロパティで指定されるデータ量がロードされると再生が開始されます。

• streaming パラメーターは、ロードが完了する前にサウンドファイルの再生を開始できることを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

449

サウンドの操作

bufferTime パラメーターのデフォルト値は -1 です。コンストラクターメソッドが bufferTime パラメーターに負の値を検知した場合、bufferTime プロパティを SoundMixer.bufferTime の値に設定します。これにより、アプリケーションのデフォル
ト値は、必要に応じてグローバルな SoundMixer.bufferTime の値になります。
autoLoad パラメーターが true に設定されている場合、コンストラクターメソッドはすぐに次の load() メソッドを呼び出し、
サウンドファイルのロードを開始します。
public function load():void{if (this.isPlaying){this.stop();this.s.close();}this.isLoaded = false;
this.s = new Sound();this.s.addEventListener(ProgressEvent.PROGRESS, onLoadProgress);
this.s.addEventListener(Event.OPEN, onLoadOpen);this.s.addEventListener(Event.COMPLETE, onLoadComplete);
this.s.addEventListener(Event.ID3, onID3);
this.s.addEventListener(IOErrorEvent.IO_ERROR, onIOError);this.s.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onIOError);var req:URLRequest = new URLRequest(this.url);var context:SoundLoaderContext = new SoundLoaderContext(this.bufferTime, true);this.s.load(req, context);}load() メソッドは新しい Sound オブジェクトを作成し、すべての重要なサウンドイベントのリスナーを追加します。その後、bufferTime 値に渡す SoundLoaderContext オブジェクトを使用して、Sound オブジェクトにサウンドファイルをロードするよう指示します。

url プロパティは変更することができるので、SoundFacade インスタンスを使用して異なるサウンドファイルを連続して再生することができます。url プロパティを変更して load() メソッドを呼び出すだけで、新しいサウンドファイルがロードされます。
次の 3 つのイベントリスナーメソッドは、SoundFacade オブジェクトがどのようにロードの進行状況をトラッキングし、サウンドを再生するタイミングを決定するかを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

450

サウンドの操作

public function onLoadOpen(event:Event):void{if (this.isStreaming){
this.isReadyToPlay = true;
if (autoPlay){
this.play();}}
this.dispatchEvent(event.clone());}
public function onLoadProgress(event:ProgressEvent):void{
this.dispatchEvent(event.clone());}
public function onLoadComplete(event:Event):void{
this.isReadyToPlay = true;
this.isLoaded = true;
this.dispatchEvent(evt.clone());
if (autoPlay && !isPlaying){play();}}

サウンドのロードが開始すると、onLoadOpen() メソッドが実行されます。サウンドをストリーミングモードで再生できる場
合、onLoadComplete() メソッドは isReadyToPlay フラグをすぐに true に設定します。isReadyToPlay フラグは、「再生」ボタンをクリックするなどのユーザーアクションに反応して、アプリケーションがサウンドの再生を開始できるかどうかを決定します。SoundChannel クラスはサウンドデータのバッファリングを管理するので、play() メソッドを呼び出す前に十分なデータ量がロードされたかどうかを明示的に確認する必要はありません。
ロードプロセス中は、onLoadProgress() メソッドが定期的に実行されます。このメソッドは、SoundFacade オブジェクトを使用するコードによって使用される ProgressEvent オブジェクトのクローンを送出するだけです。
サウンドデータが完全にロードされると、onLoadComplete() メソッドが実行されます。必要であれば、非ストリーミングサ
ウンドのために play() メソッドを呼び出します。play() メソッドを以下に示します。
public function play(pos:int = 0):void{if (!this.isPlaying){if (this.isReadyToPlay){
this.sc = this.s.play(pos);this.sc.addEventListener(Event.SOUND_COMPLETE, onPlayComplete);
this.isPlaying = true;
this.playTimer = new Timer(this.progressInterval);this.playTimer.addEventListener(TimerEvent.TIMER, onPlayTimer);this.playTimer.start();}}}

サウンドが再生できる状態になると、play() メソッドは Sound.play() メソッドを呼び出します。生成される SoundChannel
オブジェクトは、sc プロパティに格納されます。その後、play() メソッドは Timer オブジェクトを作成します。これを使用すると、playback progress イベントを定期的に送出することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

451

サウンドの操作

再生の進行状況の表示
Flash Player 9 以降、Adobe AIR 1.0 以降
Timer オブジェクトを作成して再生を監視する処理は複雑なので、コードの実行は一度きりにする必要があります。このTimer ロジックを、SoundFacade クラスのような再利用可能なクラスにカプセル化することで、アプリケーションはサウンドのロード時や再生時に同様の progress イベントを監視することができます。
SoundFacade.play() メソッドによって作成される Timer オブジェクトは、TimerEvent インスタンスを毎秒送出します。以下に示す onPlayTimer() メソッドは、新しい TimerEvent が受信されるたびに実行されます。
public function onPlayTimer(event:TimerEvent):void{
var estimatedLength:int =Math.ceil(this.s.length / (this.s.bytesLoaded / this.s.bytesTotal));var progEvent:ProgressEvent =new ProgressEvent(PLAY_PROGRESS, false, false, this.sc.position, estimatedLength);this.dispatchEvent(progEvent);}

onPlayTimer() メソッドは、431 ページの「再生の監視」の節で説明したサイズ予測方法を実装します。イベントタイプ
SoundFacade.PLAY_PROGRESS で新しい ProgressEvent インスタンスが作成されます。そのとき、bytesLoaded プロパティ
は SoundChannel オブジェクトの現在位置に設定され、bytesTotal プロパティはサウンドデータの予測長に設定されます。

再生の一時停止と再開
Flash Player 9 以降、Adobe AIR 1.0 以降
前述の SoundFacade.play() メソッドは、サウンドデータの開始位置に対応する pos パラメーターを受け取ります。pos 値がゼロの場合、サウンドは最初から再生されます。

SoundFacade.stop() メソッドは、次に示す pos パラメーターも受け取ります。
public function stop(pos:int = 0):void{if (this.isPlaying){this.pausePosition = pos;this.sc.stop();this.playTimer.stop();this.isPlaying = false;}}

SoundFacade.stop() メソッドが呼び出されると pausePosition プロパティが設定されるので、アプリケーションは同じサウンドの再生を再開する場合の再生ヘッドの位置を特定できます。
以下に示す SoundFacade.pause() メソッドおよび SoundFacade.resume() メソッドは、それぞれ SoundFacade.stop() メソッドおよび SoundFacade.play() メソッドを呼び出し、呼び出すたびに pos パラメーター値を渡します。
public function pause():void{stop(this.sc.position);}public function resume():void{play(this.pausePosition);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

452

サウンドの操作

pause() メソッドは、現在の SoundChannel.position 値を play() メソッドに渡します。このメソッドは、この値をpausePosition プロパティに格納します。resume() メソッドは、開始位置として pausePosition 値を使用し、同じサウンドを再生を開始します。

Podcast Player の拡張例
Flash Player 9 以降、Adobe AIR 1.0 以降
この例では、再利用可能な SoundFacade クラスを主に使用する、必要最小限の機能だけを備えた Podcast Player を示します。次のような機能を追加して、アプリケーションの利便性を高めることもできます。

•

フィードのリストと、各エピソードに関する使用情報を SharedObject インスタンスに格納します。このインスタンス
は、アプリケーションの次回実行時に使用することができます。

•

ユーザー独自の RSS フィードを、ポッドキャストチャンネルのリストに追加します。

•

ユーザーがエピソードを停止または終了したときの再生ヘッドの位置を記憶します。そうすると、アプリケーションの次回実行時に同じ場所から再開することができます。

•

ユーザーがインターネットに接続していない場合も、オフライン状態でエピソードを聞くために、MP3 ファイルをダウンロードします。

•

ポッドキャストチャンネルの新しいエピソードを定期的に確認してエピソードリストを自動的に更新する、サブスクリプ
ション機能を追加します。

• Odeo.com などのポッドキャストホスティングサービスの API を使用し、ポッドキャスト検索および閲覧機能を追加します。

最終更新日 2015/10/14

453

第 25 章：ビデオの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Video は、インターネットで使用可能な優れた技術の 1 つです。ただし、従来のビデオ表示（下部にプログレスバーとコントロールボタンがある四角形の画面）は、ビデオの可能な使用方法の 1 つにすぎません。ActionScript を使用すると、ビデオのロード、表示、再生を細部にわたって調節し、制御することができます。

ビデオの基礎Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe® Flash® Player と Adobe® AIR™ には、イメージ、アニメーション、テキストといったその他の視覚的なコンテンツと同様に、ActionScript でビデオ情報を表示し、操作することができるという重要な機能があります。Adobe Flash CS4
Professional で Flash Video（FLV）ファイルを作成する場合、共通の再生コントロールを含むスキンを選択することができます。しかし、ここで提供されるオプションしか使用できないわけではありません。ActionScript を使用すると、ビデオのロード、表示および再生を細部にわたって調節することができます。つまり、独自のビデオプレーヤースキンを作成した
り、新しい方法でビデオを使用したりすることができます。ActionScript でビデオを操作する場合は、いくつかのクラスを組み合わせます。

• Video クラス：ステージ上の従来のビデオコンテンツボックスは、Video クラスのインスタンスです。Video クラスは表示オブジェクトです。そのため、配置や変換、フィルターの適用、ブレンドモードなど、他の表示オブジェクトにも適用される技法を使用して操作することができます。

• StageVideo クラス：Video クラスは通常、ソフトウェアによるデコードとレンダリングを使用します。GPU ハード
ウェアアクセラレーションがデバイス上で利用可能な場合、StageVideo クラスに切り替えることによって、アプリケー
ションでハードウェアアクセラレーションによる表示を最大限に活用できます。StageVideo API には、StageVideo オ
ブジェクトと Video オブジェクトを切り替えるべきタイミングをアプリケーションコードに伝える一連のイベントが含まれています。ステージビデオにはビデオの再生に関する軽微な制限が伴います。アプリケーションでこれらの制限を受け入れる場合は、StageVideo API を実装してください。491 ページの「ガイドラインおよび制限」を参照してください。

• NetStream クラス：ActionScript で制御するビデオファイルをロードする場合、NetStream インスタンスは、ビデオ
コンテンツのソース（この場合はビデオデータのストリーム）を表します。NetStream インスタンスを使用すると、NetConnection オブジェクトも使用することになります。NetConnection オブジェクトとは、ビデオデータが送信されるトンネルのように、ビデオファイルに接続するために使用されます。

• Camera クラス：ユーザーのコンピューターに接続しているカメラからビデオデータを操作している場合、Camera イン
スタンスはビデオコンテンツのソース（ユーザーのカメラおよび使用可能になるビデオデータ）を表します。Flash
Player 11.4 と AIR 3.4 では、新たにカメラを使用して StageVideo をフィードできます。
外部ビデオをロードする場合、標準的な Web サーバーからファイルをロードしてプログレッシブダウンロードを行うか、アドビ システムズ社の Flash® Media Server などの専用のサーバーから配信されるストリーミングビデオを操作することができます。
重要な概念と用語
キューポイント ビデオファイルの特定の時点に配置できるマーカーです。その時点を探すときのブックマークとして、またはその時点に関連するデータを追加するときなどに使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

454

ビデオの操作

エンコーディング ある形式のビデオデータを、別のビデオデータ形式に変換することです。例えば、高解像度のソースビデ
オを、インターネット配信に適した形式に変換するなどが挙げられます。
フレーム ビデオ情報のセグメント。1 枚のフレームは、ビデオの特定の時点のスナップショットを表す静止画のようなものです。フレームを連続して高速再生することで動きが生まれます。
キーフレーム フレームの完全な情報を格納したビデオフレームです。キーフレームの後に続くフレームには、フレーム全体に相当する情報ではなく、キーフレームとの違いに関する情報のみが含まれます。
メタデータ ビデオファイルに関する情報で、ビデオファイル内に埋め込まれ、ビデオがロードされると取得されるものです。
プログレッシブダウンロード ビデオファイルが標準的な Web サーバーから配信されると、ビデオデータはプログレッシブ
ダウンロードによってロードされます。つまり、ビデオ情報は順番にロードされます。ファイル全体がダウンロードされる
前にビデオの再生を開始できるという利点がありますが、ロードされていない部分にジャンプすることはできません。
ストリーミング プログレッシブダウンロードの代わりに、特別なビデオサーバーを使用し、ストリーミング（別名「トゥルーストリーミング」）という技法により、インターネット上でビデオを配信することができます。ストリーミングを使用する場合、ユーザーのコンピューターは一度にビデオ全体をダウンロードしません。コンピューターではどの時点でも、ビデオ情報全体の一部しか必要としないので、ダウンロード時間を短縮することができます。特別なサーバーがビデオコンテン
ツの配信を制御するので、ビデオがダウンロードされるのを待たずに、ビデオのどの部分にも自由にアクセスすることができます。

ビデオ形式についてFlash Player 9 以降、Adobe AIR 1.0 以降
Adobe FLV ビデオ形式に加えて、Flash Player および Adobe AIR では、MPEG-4 標準ファイル形式から H.264 および
HE-AAC でエンコードされたビデオとオーディオがサポートされます。これらの形式では、低いビットレートで高品質のビデオがストリーミングされます。開発者は、Adobe Premiere Pro や Adobe After Effects などの業界標準のツールを利用して、説得力のあるビデオコンテンツを作成し、配信することができます。
型

フォーマット

コンテナ

ビデオ

H.264

MPEG-4：MP4、M4V、F4V、3GPP

ビデオ

Sorenson SparkFLV ファイル

ビデオ

ON2 VP6

FLV ファイル

オーディオ

AAC+ / HE-AAC / AAC v1 / AAC v2

MPEG-4：MP4、M4V、F4V、3GPP

オーディオ

MP3

MP3

オーディオ

Nellymoser

FLV ファイル

オーディオ

Speex

FLV ファイル

関連項目

Flash Media Server：Supported codecs
Adobe HTTP Dynamic Streaming

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

455

ビデオの操作

モバイルデバイス用のビデオのエンコーディング
Android 上の AIR では、幅広い用途に対応する H.264 ビデオをデコードできます。ただし、携帯電話上でのスムーズな再生に適した H.264 ビデオはごく一部です。これは、多くの携帯電話に処理能力上の制約があるからです。モバイル用のAdobe Flash Player では、組み込みのハードウェアアクセラレーションを使用して H.264 ビデオをデコードできます。このデコード方法では、低い消費電力で高い画質を確保できます。

H.264 標準は、各種のエンコード方式をサポートします。複雑なプロファイルとレベルのビデオをスムーズに再生できるのは、ハイエンドなデバイスだけです。ただし、ベースラインプロファイルでエンコードされたビデオなら、ほとんどのデバ
イスで再生できます。モバイルデバイス上でハードウェアアクセラレーションを利用できるのは、これらのエンコード方式の一部のみです。プロファイルおよびレベルパラメーターは、このようなエンコード方式のサブセットと、エンコーダーによって使用される設定を定義したものです。開発者には、ほとんどのデバイスで問題なく再生できるように選択された解像度でビデオをエンコードすることが求められます。
ハードウェアアクセラレーションによるメリットを得られる解像度はデバイスによって異なりますが、ほとんどのデバイス
では次の標準解像度がサポートされます。
縦横比（アスペクト比）

推奨する解像度

4:3

640 × 480

512 × 384

480 × 360

16:9

640 × 360

512 × 288

480 × 272

注意：Flash Player は、H.264 標準のすべてのレベルとプロファイルをサポートします。これらの推奨事項を守ることにより、ほとんどのデバイスでハードウェアアクセラレーションが使用され、ユーザーエクスペリエンスが向上します。これらの推奨事項は必須ではありません。
詳細な説明と Adobe Media Encoder CS5 でのエンコーディング設定については、「モバイルデバイス用 Flash Player 10.1
向けの H.264 ビデオエンコーディングの推奨事項」を参照してください。
注意：iOS では、Sorenson Spark コーデックおよび On2 VP6 コーデックでエンコードされたビデオのみを Video クラス
を使用して再生できます。デバイスのビデオプレーヤーでは、flash.net.navigateToURL() 関数を使用してビデオの URL を起動することにより、H.264 でエンコードされたビデオを再生できます。また、StageWebView オブジェクトに表示される

HTML ページで <video> タグを使用して H.264 ビデオを再生することもできます。

Flash Player および AIR とエンコードされたビデオファイルとの互換性
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player 7 では、Sorenson™ Spark™ ビデオコーデックでエンコードされた FLV ファイルをサポートしています。
Flash Player 8 は、Sorenson Spark または Flash Professional 8 の On2 VP6 エンコーダーによってエンコードされた FLV
ファイルをサポートします。On2 VP6 ビデオコーデックはアルファチャンネルに対応しています。
Flash Player 9.0.115.0 以降のバージョンでは、標準の MPEG-4 コンテナ形式から派生したファイルがサポートされます。
H.264 ビデオ、HE-AAC v2 エンコードオーディオ、またはその両方が含まれる場合、このようなファイルには F4V、
MP4、M4A、MOV、MP4V、3GP、3G2 があります。H.264 では、Sorenson または On2 の同じエンコードプロファイ
ルと比較して、低いビットレートで高品質のビデオが配信されます。HE-AAC v2 は、MPEG-4 ビデオ標準で定義された標準オーディオ形式である AAC の拡張です。HE-AAC v2 では、スペクトルバンドレプリケーション（SBR）およびパラメ
トリックステレオ（PS）技法を使用して、低いビットレートでのコーディング効率を向上させます。
次の表に、サポートされるコーデックの一覧を示します。対応する SWF ファイル形式と、それらのファイル形式の再生に必要な Flash Player および AIR のバージョンも示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

456

ビデオの操作

コーデック

SWF ファイル形式バージョン（最もFlash Player および AIR（再生に必要な最低バージョン）

早くからサポートされていたパブリッ
シュバージョン）Sorenson Spark6

On2 VP6

6

Flash Player 6、Flash Lite 3
Flash Player 8、Flash Lite 3。
On2 VP6 ビデオのパブリッシュと再生をサポートしているのは、Flash Player 8 以降のバージョンだけです。

H.264（MPEG-4 Part 10）

9Flash Player 9 Update 3、AIR 1.0

ADPCM

6

Flash Player 6、Flash Lite 3

MP3

6Flash Player 6、Flash Lite 3

AAC（MPEG-4 Part 3）

9Flash Player 9 Update 3、AIR 1.0

Speex（オーディオ）

10

Flash Player 10、AIR 1.5

Nellymoser

6

Flash Player 6

Adobe F4V および FLV ビデオファイル形式についてFlash Player 9 以降、Adobe AIR 1.0 以降
Flash Player および AIR にコンテンツをストリーミングするために、F4V および FLV ビデオファイル形式が用意されています。これらのビデオ形式について詳しくは、www.adobe.com/go/video_file_format_jp を参照してください。

F4V ビデオファイル形式
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player Update 3（9.0.115.0）および AIR 1.0 以降、Flash Player および AIR では Adobe F4V ビデオ形式がサポートされます。このビデオ形式は、ISO MP4 形式に基づき、形式のサブセットではそれぞれ異なる機能がサポートされます。
Flash Player では、次の最上位ボックスの 1 つから開始する有効な F4V ファイルが必要です。

• ftypftyp ボックスでは、プログラムが特定のファイル形式を再生するためにサポートする必要のある機能が識別されます。

• moovmoov ボックスは、事実上 F4V ファイルのヘッダーです。このボックスには、F4V データの構造を定義する他のボック
スを含む 1 つ以上の他のボックスが含まれます。F4V ファイルには、moov ボックスが必ず 1 つだけ含まれている必要があります。

• mdatmdat ボックスには、F4V ファイルのデータペイロードが含まれます。FV ファイルには、mdat ボックスが 1 つだけ含まれます。mdat ボックス単体では認識できないので、moov ボックスもファイルに存在する必要があります。
F4V ファイルでは、最下位アドレスの最上位バイトが最初に出現するビッグエンディアンバイト順序でマルチバイト整数がサポートされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

457

ビデオの操作

FLV ビデオファイル形式
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe FLV ファイル形式には、Flash Player で配信するエンコード済みのオーディオデータやビデオデータが含まれています。Adobe Media Encoder や Sorenson™ Squeeze などのエンコーダーを使用して、QuickTime または Windows
Media ビデオファイルを FLV ファイルに変換することができます。
注意：Flash にビデオを取り込み、それを FLV ファイルとして書き出すと、FLV ファイルを作成することができます。
FLV Export プラグインを使用すると、サポートされるビデオ編集アプリケーションから FLV ファイルを書き出すことができます。Web サーバーから FLV ファイルをロードするには、ファイル名拡張子と MIME タイプを Web ブラウザーに登録します。Web サーバーのドキュメントを参照してください。FLV ファイルの MIME タイプは video/x-flv です。詳しくは、
482 ページの「サーバーでホスティングするための FLV ファイルの設定」を参照してください。

FLV ファイルについて詳しくは、482 ページの「ビデオファイルに関する高度なトピック」を参照してください。

外部ビデオと埋め込みビデオ
Flash Player 9 以降、Adobe AIR 1.0 以降
外部ビデオファイルでは、取り込まれたビデオでは使用できない機能も使用することができます。

•

再生速度を遅くしなくても、アプリケーションで長いビデオクリップを表示することができます。外部ビデオファイルではキャッシュされたメモリを使用するので、大きなファイルが小さな部分に分割されて格納され、動的にアクセスされます。このため、外部 F4V ファイルおよび FLV ファイルは、埋め込みビデオファイルよりもメモリを必要としません。

•

外部ビデオファイルには、それを再生する SWF ファイルとは異なるフレームレートを持たせることができます。例えば、SWF ファイルのフレームレートを毎秒 30 フレーム（fps）に設定する一方で、ビデオのフレームレートを 21 fps に設定することができます。このように設定すると、埋め込みビデオよりも操作性が高くなり、ビデオをスムーズに再生することができます。また、既存の SWF ファイルコンテンツを変更することなく、異なるフレームレートでビデオファイ
ルを再生することが可能になります。

•

外部ビデオファイルでは、ビデオファイルのロード中に SWF コンテンツの再生が中断されません。取り込まれたビデオ
ファイルの場合、CD-ROM ドライブへのアクセスといった機能を実行するために、ドキュメントの再生が中断されることがあります。ビデオファイルでは、再生を中断することなく、SWF コンテンツから独立して機能を実行することができます。

•

また、ビデオコンテンツへのキャプション追加も、外部 FLV ファイルの方が簡単です。これは、イベントハンドラーを使用してビデオのメタデータにアクセスできるからです。

Video クラスについてFlash Player 9 以降、Adobe AIR 1.0 以降
Video クラスを使用すると、SWF ファイルに埋め込むことなく、ライブストリーミングビデオをアプリケーションで表示することができます。Camera.getCamera() メソッドを使用して、ライブビデオをキャプチャして再生できます。また、Video
クラスを使用して、HTTP 経由またはローカルファイルシステムからビデオファイルを再生することもできます。プロジェ
クトで Video クラスを使用するには、いくつかの方法があります。

• NetConnection クラスおよび NetStream クラスを使用してビデオファイルを動的にロードし、Video オブジェクトでビデオを表示します。

•

ユーザーのカメラから入力をキャプチャします。詳しくは、497 ページの「カメラの操作」を参照してください。

• FLVPlayback コンポーネントを使用します。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

458

ビデオの操作• VideoDisplay コントロールを使用します。
注意：ステージ上の Video オブジェクトのインスタンスは、Video クラスのインスタンスです。

Video クラスは flash.media パッケージにありますが、flash.display.DisplayObject クラスから継承されるので、マトリックス変換やフィルターといった表示オブジェクトのすべての機能も Video インスタンスに適用されます。
詳しくは、165 ページの「表示オブジェクトの操作」、201 ページの「ジオメトリの操作」および 254 ページの「表示オブジェクトのフィルター処理」を参照してください。

ビデオファイルのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
NetStream および NetConnection クラスを使用したビデオのロードは、次に示す複数の手順で実行されます。ベストプラ
クティスとして、表示リストへの Video オブジェクトの追加、Video インスタンスへの NetStream オブジェクトの関連付
け、NetStream オブジェクトの play() メソッドの呼び出しは、指定された順序で実行します。

1 NetConnection オブジェクトを作成します。ローカルビデオファイルまたはアドビ システムズ社の Flash Media Server

2 などのサーバーを使用していないビデオファイルに接続している場合は、null を connect() メソッドに渡して、HTTP
アドレスまたはローカルドライブからビデオファイルを再生します。サーバーに接続している場合は、サーバー上のビデ
オファイルが格納されているアプリケーションの URI をパラメーターに設定します。
var nc:NetConnection = new NetConnection();nc.connect(null);

2 以下のスニペットのように、ビデオを表示してステージの表示リストに追加する新しい Video オブジェクトを作成します。
var vid:Video = new Video();
addChild(vid);

3 NetConnection オブジェクトを引数としてコンストラクターに渡し、NetStream オブジェクトを作成します。以下のスニペットは NetStream オブジェクトを NetConnection インスタンスに接続して、ストリームのイベントハンドラーを設定します。
var ns:NetStream = new NetStream(nc);ns.addEventListener(NetStatusEvent.NET_STATUS,netStatusHandler);ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);function netStatusHandler(event:NetStatusEvent):void{// handle netStatus events, described later}
function asyncErrorHandler(event:AsyncErrorEvent):void{// ignore error}

4 以下のスニペットのように、Video オブジェクトの attachNetStream() メソッドを使用して NetStream オブジェクトをVideo オブジェクトに関連付けます。
vid.attachNetStream(ns);

5 ビデオファイルの URL を引数として使用して NetStream オブジェクトの play() メソッドを呼び出し、ビデオの再生を開始します。以下のスニペットは、SWF ファイルと同じディレクトリ内の「video.mp4」という名前のビデオファイルをロードして再生します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

459

ビデオの操作

ns.play("video.mp4");

関連項目

Flex：Spark VideoPlayer control
spark.components.VideoDisplay

ビデオ再生の制御
Flash Player 9 以降、Adobe AIR 1.0 以降
NetStream クラスは、ビデオ再生を制御する 4 つの主な方法を提供します。
pause()：ビデオストリームの再生を停止します。ビデオが既に停止している場合は、このメソッドを呼び出しても何も実行されません。
resume()：停止中のビデオストリームの再生を再開します。ビデオが既に再生中である場合は、このメソッドを呼び出しても何も実行されません。

seek()：指定された場所（ストリームの先頭からの秒単位のオフセット）に最も近いキーフレームをシークします。
togglePause()：ストリームの再生を停止または再開します。
注意：stop() メソッドはありません。ストリームを停止するには、再生を一時停止し、ビデオストリームの先頭にシークする必要があります。
注意：play() メソッドは再生を再開しません。ビデオファイルのロードに使用されます。
次の例は、様々なボタンを使用してビデオを制御する方法を示します。次の例を実行するには、新しいドキュメントを作成
し、ワークスペース内に pauseBtn、playBtn、stopBtn および togglePauseBtn の 4 つのボタンインスタンスを追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

460

ビデオの操作

var nc:NetConnection = new NetConnection();nc.connect(null);var ns:NetStream = new NetStream(nc);ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);ns.play("video.flv");function asyncErrorHandler(event:AsyncErrorEvent):void{// ignore error}
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);pauseBtn.addEventListener(MouseEvent.CLICK, pauseHandler);playBtn.addEventListener(MouseEvent.CLICK, playHandler);
stopBtn.addEventListener(MouseEvent.CLICK, stopHandler);
togglePauseBtn.addEventListener(MouseEvent.CLICK, togglePauseHandler);function pauseHandler(event:MouseEvent):void{ns.pause();}function playHandler(event:MouseEvent):void{ns.resume();}function stopHandler(event:MouseEvent):void{// Pause the stream and move the playhead back to// the beginning of the stream.
ns.pause();ns.seek(0);}function togglePauseHandler(event:MouseEvent):void{ns.togglePause();}

ビデオの再生中に pauseBtn ボタンインスタンスをクリックすると、ビデオファイルが一時停止します。ビデオが既に一時停止状態にある場合、このボタンインスタンスをクリックしても何も効果がありません。再生が一時停止状態にある場合にplayBtn ボタンインスタンスをクリックすると、ビデオ再生が再開されます。ビデオが既に再生中であれば、何も効果がありません。

ビデオストリームの末尾の検知
Flash Player 9 以降、Adobe AIR 1.0 以降
ビデオストリームの先頭と末尾を監視するには、netStatus イベントを監視するためのイベントリスナーを NetStream イン
スタンスに追加する必要があります。次のコードは、ビデオ再生全体において、様々なコードがどのように監視されるかを示します。
ns.addEventListener(NetStatusEvent.NET_STATUS, statusHandler);function statusHandler(event:NetStatusEvent):void{
trace(event.info.code)}

上のコードを実行すると、次のように表示されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

461

ビデオの操作NetStream.Play.Start
NetStream.Buffer.Empty
NetStream.Buffer.Full
NetStream.Buffer.Empty
NetStream.Buffer.Full
NetStream.Buffer.Empty
NetStream.Buffer.Full
NetStream.Buffer.FlushNetStream.Play.Stop
NetStream.Buffer.Empty
NetStream.Buffer.Flush

特に便利なのは、ビデオ再生の先頭と末尾を知らせる「NetStream.Play.Start」および 「NetStream.Play.Stop」の 2 つのコードです。次のコード例では、switch ステートメントを使用してこれら 2 つのコードをフィルタリングし、メッセージをトレースします。
function statusHandler(event:NetStatusEvent):void{switch (event.info.code){
case "NetStream.Play.Start":
trace("Start [" + ns.time.toFixed(3) + " seconds]");break;
case "NetStream.Play.Stop":
trace("Stop [" + ns.time.toFixed(3) + " seconds]");break;}}

netStatus イベント（NetStatusEvent.NET_STATUS）を監視すると、再生中のビデオが終了したときに、プレイリストの次のビデオをロードするビデオプレーヤーを作成することができます。

フルスクリーンモードでのビデオ再生
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player および AIR には、ビデオ再生を行うフルスクリーンアプリケーションを作成し、フルスクリーンのサイズにビデオを拡大／縮小して表示できる機能があります。
デスクトップでフルスクリーンモードで実行されている AIR コンテンツの場合、ビデオ入力が停止するか、ユーザーがフルスクリーンモードを終了するまで、再生中はシステムのスクリーンセーバーと省電力オプションが無効になります。
フルスクリーンモードの使用法について詳しくは、159 ページの「フルスクリーンモードの操作」を参照してください。
ブラウザーでの Flash Player のフルスクリーンモードの有効化
ブラウザーで Flash Player のフルスクリーンモードを実装する前に、パブリッシュテンプレートを使用して、アプリケー
ションに対してフルスクリーンモードを有効にする必要があります。フルスクリーンを可能にするテンプレートには、<object> タグおよび <embed> タグが含まれます。これらのタグには、allowFullScreen パラメーターが含まれます。次の例
は、<embed> タグ内の allowFullScreen パラメーターを示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

462

ビデオの操作<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="fullScreen" width="100%" height="100%"
codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">...
<param name="allowFullScreen" value="true" /><embed src="fullScreen.swf" allowFullScreen="true" quality="high" bgcolor="#869ca7"
width="100%" height="100%" name="fullScreen" align="middle"
play="true"
loop="false"
quality="high"allowScriptAccess="sameDomain"
type="application/x-shockwave-flash"pluginspage="http://www.adobe.com/go/getflashplayer"></embed>...
</object>

Flash では、ファイル／パブリッシュ設定を選択し、パブリッシュ設定ダイアログの「HTML」タブで、「Flash のみ - フルスクリーンサポート」テンプレートを選択します。

Flex で、HTML テンプレートにフルスクリーンをサポートする <object> タグおよび <embed> タグが含まれていることを確認します。
フルスクリーンモードの開始
ブラウザー上で実行される Flash Player コンテンツでは、マウスのクリックまたはキー押下に応答してビデオのスクリーン
モードを開始します。例えば、ユーザーが「フルスクリーン」というラベルのボタンをクリックしたとき、またはコンテキ
ストメニューから「フルスクリーン」コマンドを選択したときに、フルスクリーンモードを開始することができます。ユー
ザーに応答するには、アクションが発生するオブジェクトにイベントリスナーを追加します。次のコードでは、ユーザーがフルスクリーンモードに入るためにクリックするボタンにイベントリスナーを追加しています。
var fullScreenButton:Button = new Button();fullScreenButton.label = "Full Screen";
addChild(fullScreenButton);
fullScreenButton.addEventListener(MouseEvent.CLICK, fullScreenButtonHandler);function fullScreenButtonHandler(event:MouseEvent){stage.displayState = StageDisplayState.FULL_SCREEN;}

Stage.displayState プロパティを StageDisplayState.FULL_SCREEN に設定することでフルスクリーンモードを開始しています。
このコードは、ステージを占める空間に比例したビデオスケーリングで、ステージ全体をフルスクリーンに拡大します。
fullScreenSourceRect プロパティでは、フルスクリーンに拡大するステージの特定領域を指定することができます。まず、フルスクリーンに拡大する四角形を定義します。次に、その四角形を Stage.fullScreenSourceRect プロパティに割り当てます。
次のバージョンの fullScreenButtonHandler() 関数では、ビデオのみをフルスクリーンに拡大する 2 行のコードが追加されています。
private function fullScreenButtonHandler(event:MouseEvent){var screenRectangle:Rectangle = new Rectangle(video.x, video.y, video.width, video.height);
stage.fullScreenSourceRect = screenRectangle;
stage.displayState = StageDisplayState.FULL_SCREEN;}

この例ではマウスのクリックに応答してイベントハンドラーを呼び出していますが、フルスクリーンモードにする方法はFlash Player と AIR の両方で同じです。拡大する四角形を定義し、Stage.displayState プロパティを設定します。詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

463

ビデオの操作

以下の完全な例では、ビデオの接続および NetStream オブジェクトを作成し、その再生を開始するコードを追加しています。
package{import flash.net.NetConnection;
import flash.net.NetStream;
import flash.media.Video;
import flash.display.StageDisplayState;
import fl.controls.Button;
import flash.display.Sprite;
import flash.events.MouseEvent;import flash.events.FullScreenEvent;import flash.geom.Rectangle;
public class FullScreenVideoExample extends Sprite{
var fullScreenButton:Button = new Button();var video:Video = new Video();public function FullScreenVideoExample(){var videoConnection:NetConnection = new NetConnection();videoConnection.connect(null);var videoStream:NetStream = new NetStream(videoConnection);videoStream.client = this;addChild(video);video.attachNetStream(videoStream);
videoStream.play("http://www.helpexamples.com/flash/video/water.flv");
fullScreenButton.x = 100;
fullScreenButton.y = 270;
fullScreenButton.label = "Full Screen";
addChild(fullScreenButton);
fullScreenButton.addEventListener(MouseEvent.CLICK, fullScreenButtonHandler);}private function fullScreenButtonHandler(event:MouseEvent){var screenRectangle:Rectangle = new Rectangle(video.x, video.y, video.width, video.height);
stage.fullScreenSourceRect = screenRectangle;
stage.displayState = StageDisplayState.FULL_SCREEN;}
public function onMetaData(infoObject:Object):void{// stub for callback function}}}

onMetaData() 関数は、ビデオメタデータが存在する場合にそのメタデータを処理するためのコールバック関数です。コール
バック関数は、何らかのタイプの出現またはイベントに応答してランタイムによって呼び出される関数です。この例では、
onMetaData() 関数は、関数を提供するための要件を満たすスタブです。詳しくは、466 ページの「メタデータとキューポイ
ントのコールバックメソッドの作成」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

464

ビデオの操作

フルスクリーンモードの終了
ユーザーは、Esc キーなどのキーボードショートカットの 1 つを入力することによりフルスクリーンモードを終了できます。

ActionScript では、Stage.displayState プロパティを StageDisplayState.NORMAL に設定することによりフルスクリーンモードを終了できます。次の例のコードは、NetStream.Play.Stop netStatus イベントの発生時にフルスクリーンモードを終了します。
videoStream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);private function netStatusHandler(event:NetStatusEvent){if(event.info.code == "NetStream.Play.Stop")
stage.displayState = StageDisplayState.NORMAL;}

フルスクリーンのハードウェアアクセラレーション
ステージの矩形領域をフルスクリーンモードに拡大する場合、Flash Player または AIR ではハードウェアアクセラレーションが使用されます（使用可能で、有効になっている場合）。コンピューターのビデオアダプターを使用することで、ビデオやステージの一部をフルスクリーンサイズに拡大表示する処理が高速化されます。このような状況では、多くの場合、Flash

Player アプリケーションは Video クラス（または Flash Player 11.4 ／ AIR 3.4 では Camera クラス）から StageVideo ク
ラスに切り替えると便利です。
フルスクリーンモードのハードウェアアクセラレーションについて詳しくは、159 ページの「フルスクリーンモードの操作」
を参照してください。StageVideo について詳しくは、489 ページの「ハードウェアアクセラレーションによる表示のための StageVideo クラスの使用」を参照してください。

ビデオファイルのストリーミング
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Media Server からファイルをストリーミングするには、NetConnection および NetStream クラスを使用してリモー
トサーバーインスタンスに接続し、指定のストリームを再生することができます。Real-Time Messaging Protocol（RTMP）サーバーを指定するには、NetConnection.connect() メソッドに、null 値ではなく「rtmp://localhost/appName/appInstance」といった RTMP URL を渡します。指定の Flash Media Server から特定のライブストリームまたは記録されているストリームを再生するには、NetStream.publish() によってパブリッシュされたライブ
データの識別名か、再生のために記録されたファイル名を NetStream.play() メソッドに渡します。

サーバーへのビデオ送信
Flash Player 9 以降、Adobe AIR 1.0 以降
Video オブジェクトまたは Camera オブジェクトを使用する、より複雑なアプリケーションを構築するため、Flash Media
Server ではメディアアプリケーションを幅広いユーザー向けに作成して配信するためのストリーミングメディア機能と開発環境を提供します。これらがあると、開発者はビデオオンデマンド、ライブ Web イベントブロードキャスト、MP3 スト
リーミング、そしてビデオブログ、ビデオメッセージング、マルチメディアチャット環境などのアプリケーションを構築することができます。詳しくは、www.adobe.com/go/learn_fms_docs_jp でオンラインの Flash Media Server ドキュメン
トを参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

465

ビデオの操作

キューポイントについて
Flash Player 9 以降、Adobe AIR 1.0 以降
エンコード時に、Adobe F4V または FLV ビデオにキューポイントを埋め込むことができます。従来、キューポイントはムービーに埋め込まれ、フィルムのリールが終わりに達したことを示す視覚的なシグナルを映写技師に提供していました。

Adobe F4V および FLV ビデオ形式では、キューポイントがビデオストリームに出現したときに、アプリケーションの他の
1 つ以上のアクションをトリガーすることができます。
Flash Video では、数種類のキューポイントを使用することができます。ActionScript を使用して、作成時にビデオファイ
ルに埋め込んだキューポイントとやり取りすることができます。

•

ナビゲーションキューポイント：ビデオファイルをエンコードするときに、ビデオストリームとビデオメタデータパケッ
トにナビゲーションキューポイントを埋め込みます。ナビゲーションキューポイントを使用すると、ユーザーはファイルの指定部分にシークすることができます。

•

イベントキューポイント：ビデオファイルをエンコードするときに、ビデオストリームとビデオメタデータパケットにイ
ベントキューポイントを埋め込みます。ビデオの再生時に、指定のポイントでトリガーされるイベントを処理するコードを作成することができます。

• ActionScript キューポイント：ActionScript キューポイントは、Flash FLVPlayback コンポーネントでのみ使用することができます。ActionScript キューポイントは、ActionScript コードで作成およびアクセスする外部キューポイントです。ビデオの再生に関連付け、これらのキューポイントをトリガーするコードを作成することができます。ビデオプ
レーヤーは、これらのキューポイントを個別にトラッキングするので、埋め込まれるキューポイントに比べると精度が低くなります（最大で 10 分の 1 秒）。ユーザーがキューポイントにナビゲートするようなアプリケーションを作成する場合
は、ActionScript キューポイントを使用する代わりに、ファイルをエンコードするときにキューポイントを作成し、埋め込みます。キューポイントは、FLV ファイルに埋め込む必要があります。この方が、精度が高いからです。
ナビゲーションキューポイントは、指定のキューポイント位置でキーフレームを作成するので、コードを使用して、ビデオ
プレーヤーの再生ヘッドをその位置に移動することができます。ユーザーがシークする位置として、ビデオファイルにポイントを設定することもできます。例えば、ビデオに複数のチャプターまたはセグメントがあるとすると、ビデオファイルに埋め込まれたナビゲーションキューポイントを使用してビデオを制御することができます。
キューポイントによる Adobe ビデオファイルのエンコードについて詳しくは、『Flash ユーザーガイド』の「キューポイン
トの埋め込み」を参照してください。

ActionScript を記述することで、キューポイントパラメーターにアクセスすることができます。キューポイントパラメー
ターとは、コールバックハンドラーから受け取るイベントオブジェクトの一部です。

FLV ファイルが指定のキューポイントに到達したときに、コードで特定のアクションをトリガーするには、
NetStream.onCuePoint イベントハンドラーを使用します。

F4V ビデオファイルのキューポイントのアクションを同期するには、onMetaData() または onXMPData() コールバック関数からキューポイントデータを取得し、ActionScript 3.0 の Timer クラスを使用してキューポイントをトリガーする必要があります。F4V キューポイントについて詳しくは、476 ページの「onXMPData() の使用」を参照してください。
キューポイントとメタデータの処理について詳しくは、466 ページの「メタデータとキューポイントのコールバックメソッ
ドの作成」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

466

ビデオの操作

メタデータとキューポイントのコールバックメソッドの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
プレーヤーによって特定のメタデータが受信されたとき、または特定のキューポイントに到達したときに、アプリケーショ
ンでアクションをトリガーすることができます。これらのイベントが発生した場合は、特定のコールバックメソッドをイベ
ントハンドラーとして使用する必要があります。NetStream クラスでは、再生中に発生する可能性のある onCuePoint（FLV ファイルのみ）、onImageData、onMetaData、onPlayStatus、onTextData および onXMPData のメタデータイベントを指定します。
これらのハンドラーのコールバックメソッドも記述しておく必要があります。コールバックメソッドがなければ、Flash ランタイムがエラーをスローします。例えば、次のコードは、SWF ファイルと同じフォルダーの video.flv という名前の FLVファイルを再生します。
var nc:NetConnection = new NetConnection();nc.connect(null);var ns:NetStream = new NetStream(nc);ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);ns.play("video.flv");function asyncErrorHandler(event:AsyncErrorEvent):void{
trace(event.text);}
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);

前述のコードは、video.flv という名前のローカルビデオファイルをロードし、送出される asyncError（AsyncErrorEvent.ASYNC_ERROR）を監視します。このイベントは、ネイティブ非同期コードから例外がスローされると送出されます。この場合、ビデオファイルにメタデータまたはキューポイント情報が含まれ、適切なリスナーが定義されていない場合に送出されます。前述のコードでは、ユーザーがビデオファイルのメタデータまたはキューポイント情報に関心がなければ、asyncError イベントを処理し、エラーを無視します。メタデータと複数のキューポイントがある FLV がある場合
は、trace() 関数によって、次のエラーメッセージが表示されます。
Error #2095: flash.net.NetStream was unable to invoke callback onMetaData.
Error #2095: flash.net.NetStream was unable to invoke callback onCuePoint.
Error #2095: flash.net.NetStream was unable to invoke callback onCuePoint.
Error #2095: flash.net.NetStream was unable to invoke callback onCuePoint.

エラーが発生する理由は、NetStream オブジェクトが onMetaData または onCuePoint コールバックメソッドを見つけられなかったからです。アプリケーション内でこれらのコールバックメソッドを定義するには、いくつかの方法があります。

関連項目

Flash Media Server：Handling metadata in streams

NetStream オブジェクトの client プロパティをオブジェクトに設定
Flash Player 9 以降、Adobe AIR 1.0 以降
client プロパティをオブジェクトまたは NetStream のサブクラスに設定すると、onMetaData および onCuePoint コールバッ
クメソッドをリルートするか、完全に無視することができます。次の例は、空のオブジェクトを使用し、asyncError イベン
トを監視せずにコールバックメソッドを無視する方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

467

ビデオの操作

var nc:NetConnection = new NetConnection();nc.connect(null);var customClient:Object = new Object();
var ns:NetStream = new NetStream(nc);ns.client = customClient;ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);

onMetaData または onCuePoint コールバックメソッドのいずれかを監視するには、次のコード例で示すように、これらのコールバックメソッドを処理するメソッドを定義する必要があります。
var customClient:Object = new Object();
customClient.onMetaData = metaDataHandler;function metaDataHandler(infoObject:Object):void{
trace("metadata");}

上記のコードは onMetaData コールバックメソッドを監視し、ストリングをトレースする metaDataHandler() メソッドを呼び出します。Flash ランタイムがキューポイントに到達した場合、onCuePoint コールバックメソッドが定義されていなくても、エラーは発生しません。

カスタムクラスの作成とコールバックメソッドを処理するメソッドの定義
Flash Player 9 以降、Adobe AIR 1.0 以降
次のコードは NetStream オブジェクトの client プロパティを、カスタムクラスである CustomClient に設定します。

CustomClient は、コールバックメソッドのハンドラーを定義します。
var nc:NetConnection = new NetConnection();nc.connect(null);var ns:NetStream = new NetStream(nc);ns.client = new CustomClient();
ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);

CustomClient クラスを次に示します。
package{public class CustomClient{
public function onMetaData(infoObject:Object):void{
trace("metadata");}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

468

ビデオの操作

CustomClient クラスは、onMetaData コールバックハンドラーのハンドラーを定義します。キューポイントに到達し、
onCuePoint コールバックハンドラーが呼び出されると、asyncError イベント（AsyncErrorEvent.ASYNC_ERROR）が送出され、「flash.net.NetStream was unable to invoke callback onCuePoint」（flash.net.NetStream は onCuePoint コールバッ
クを開始できませんでした）と示されます。このエラーを回避するには、CustomClient クラスで onCuePoint コールバック
メソッドを定義するか、asyncError イベントのイベントハンドラーを定義する必要があります。

NetStream クラスの拡張とコールバックメソッドを処理するメソッドの追加
Flash Player 9 以降、Adobe AIR 1.0 以降
次のコードでは、後述するコードで定義されている CustomNetStream クラスのインスタンスを作成します。
var ns:CustomNetStream = new CustomNetStream();ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);

次のコードは、NetStream クラスを拡張し、必要な NetConnection オブジェクトを作成し、onMetaData および

onCuePoint コールバックハンドラーメソッドを処理する CustomNetStream クラスを定義します。
package{import flash.net.NetConnection;
import flash.net.NetStream;
public class CustomNetStream extends NetStream{
private var nc:NetConnection;
public function CustomNetStream(){
nc = new NetConnection();nc.connect(null);super(nc);}public function onMetaData(infoObject:Object):void{
trace("metadata");}public function onCuePoint(infoObject:Object):void{
trace("cue point");}}}

CustomNetStream クラスの onMetaData() および onCuePoint() メソッドの名前を変更するには、次のコードを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

469

ビデオの操作

package{import flash.net.NetConnection;
import flash.net.NetStream;
public class CustomNetStream extends NetStream{
private var nc:NetConnection;
public var onMetaData:Function;
public var onCuePoint:Function;
public function CustomNetStream(){
onMetaData = metaDataHandler;
onCuePoint = cuePointHandler;nc = new NetConnection();nc.connect(null);super(nc);}private function metaDataHandler(infoObject:Object):void{
trace("metadata");}private function cuePointHandler(infoObject:Object):void{
trace("cue point");}}}

NetStream クラスの拡張と動的化
Flash Player 9 以降、Adobe AIR 1.0 以降
NetStream クラスを拡張し、サブクラスを動的にすると、onCuePoint および onMetaData コールバックハンドラーを動的に追加することができます。例を次のコードに示します。
var ns:DynamicCustomNetStream = new DynamicCustomNetStream();ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);

DynamicCustomNetStream クラスを次に示します。
package{import flash.net.NetConnection;
import flash.net.NetStream;
public dynamic class DynamicCustomNetStream extends NetStream{
private var nc:NetConnection;
public function DynamicCustomNetStream(){
nc = new NetConnection();nc.connect(null);super(nc);}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

470

ビデオの操作

onMetaData および onCuePoint コールバックハンドラーのハンドラーがない場合でも、DynamicCustomNetStream クラスは動的なのでエラーはスローされません。onMetaData および onCuePoint コールバックハンドラーのメソッドを定義するには、次のコードを使用します。
var ns:DynamicCustomNetStream = new DynamicCustomNetStream();ns.onMetaData = metaDataHandler;
ns.onCuePoint = cuePointHandler;
ns.play("http://www.helpexamples.com/flash/video/cuepoints.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);function metaDataHandler(infoObject:Object):void{
trace("metadata");}function cuePointHandler(infoObject:Object):void{
trace("cue point");}

NetStream オブジェクトの client プロパティを this に設定
Flash Player 9 以降、Adobe AIR 1.0 以降
client プロパティを this に設定すると、アプリケーションは onMetaData() および onCuePoint() メソッドの現在の範囲を探します。これを次の例に示します。
var nc:NetConnection = new NetConnection();nc.connect(null);var ns:NetStream = new NetStream(nc);ns.client = this;ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);

onMetaData または onCuePoint コールバックハンドラーが呼び出され、コールバックを処理するメソッドがない場合、エラーは発生しません。これらのコールバックハンドラーを処理するには、次のコード例に示すように、コードに
onMetaData() および onCuePoint() メソッドを作成します。
function onMetaData(infoObject:Object):void{
trace("metadata");}function onCuePoint(infoObject:Object):void{
trace("cue point");}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

471

ビデオの操作

キューポイントとメタデータの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
NetStream コールバックメソッドを使用して、ビデオ再生時にキューポイントおよびメタデータイベントをキャプチャして処理します。

キューポイントの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
次の表に、Flash Player および AIR で F4V および FLV キューポイントをキャプチャするために使用できるコールバックメ
ソッドを説明します。
ランタイム

F4V

FLV

Flash Player 9/AIR1.0

OnCuePoint
OnMetaData

Flash Player 10

OnCuePoint
OnMetaData

OnMetaData

OnXMPData

OnXMPData

次の例では、単純な for..in ループを使用して、onCuePoint() 関数が受け取る infoObject パラメーターの各プロパティを反復します。キューポイントデータの受信時に、trace() 関数を呼び出してメッセージを表示します。
var nc:NetConnection = new NetConnection();nc.connect(null);var ns:NetStream = new NetStream(nc);ns.client = this;ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);function onCuePoint(infoObject:Object):void{
var key:String;for (key in infoObject){
trace(key + ": " + infoObject[key]);}}

出力は次のとおりです。
parameters:
name: point1
time: 0.418
type: navigation

このコードでは、コールバックメソッドを実行するオブジェクトを設定する技法の 1 つを使用しています。他の技法を使用することもできます。詳しくは、466 ページの「メタデータとキューポイントのコールバックメソッドの作成」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

472

ビデオの操作

ビデオメタデータの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
OnMetaData() および OnXMPData() 関数を使用して、キューポイントなど、ビデオファイル内のメタデータ情報にアクセスすることができます。

OnMetaData() の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
メタデータには、長さ、幅、高さ、フレームレートなどビデオファイルに関する情報が含まれています。ビデオファイルに追加されるメタデータ情報は、ビデオファイルのエンコードに使用するソフトウェアによって決まります。
var nc:NetConnection = new NetConnection();nc.connect(null);var ns:NetStream = new NetStream(nc);ns.client = this;ns.play("video.flv");
var vid:Video = new Video();vid.attachNetStream(ns);addChild(vid);function onMetaData(infoObject:Object):void{
var key:String;for (key in infoObject){
trace(key + ": " + infoObject[key]);}}

前述のコードを実行すると、次のような出力が生成されます。
width: 320
audiodelay: 0.038
canSeekToEnd: trueheight: 213
cuePoints: ,,audiodatarate: 96
duration: 16.334
videodatarate: 400
framerate: 15
videocodecid: 4audiocodecid: 2

ビデオにオーディオがない場合は、エンコード中にメタデータにオーディオ情報が追加されないので、audiodatarate などのオーディオ関連のメタデータ情報は undefined を返します。
前述のコードでは、キューポイント情報は表示されていません。キューポイントメタデータを表示するには、オブジェクトのアイテムを再帰的に表示する次の関数を使用することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

473

ビデオの操作function traceObject(obj:Object, indent:uint = 0):void{
var indentString:String = "";var i:uint;
var prop:String;var val:*;for (i = 0; i < indent; i++){indentString += "\t";}for (prop in obj){
val = obj[prop];
if (typeof(val) == "object"){
trace(indentString + " " + prop + ": [Object]");traceObject(val, indent + 1);}
else{
trace(indentString + " " + prop + ": " + val);}}}

前述のコード例を使用し、onMetaData() メソッドの infoObject パラメーターをトレースすると、出力は次のようになります。
width: 320
audiodatarate: 96
audiocodecid: 2
videocodecid: 4
videodatarate: 400
canSeekToEnd: true
duration: 16.334
audiodelay: 0.038
height: 213
framerate: 15
cuePoints: [Object]
0: [Object]parameters: [Object]
lights: beginning
name: point1
time: 0.418
type: navigation
1: [Object]parameters: [Object]
lights: middle
name: point2
time: 7.748
type: navigation
2: [Object]parameters: [Object]
lights: end
name: point3
time: 16.02
type: navigation

次の例では、MP4 ビデオのメタデータが表示されます。metaDataOut という TextArea オブジェクトがあり、このオブジェ
クトにメタデータを書き込むことを想定しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

474

ビデオの操作

package{import flash.net.NetConnection;
import flash.net.NetStream;
import flash.events.NetStatusEvent;import flash.media.Video;
import flash.display.StageDisplayState;
import flash.display.Loader;import flash.display.Sprite;
import flash.events.MouseEvent;public class onMetaDataExample extends Sprite{
var video:Video = new Video();public function onMetaDataExample():void{
var videoConnection:NetConnection = new NetConnection();videoConnection.connect(null);var videoStream:NetStream = new NetStream(videoConnection);videoStream.client = this;addChild(video);video.x = 185;
video.y = 5;video.attachNetStream(videoStream);
videoStream.play("video.mp4");
videoStream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);}public function onMetaData(infoObject:Object):void{for(var propName:String in infoObject){
metaDataOut.appendText(propName + "=" + infoObject[propName] + "\n");}}private function netStatusHandler(event:NetStatusEvent):void{if(event.info.code == "NetStream.Play.Stop")
stage.displayState = StageDisplayState.NORMAL;}}}

onMetaData() 関数では、このビデオに対して次の出力が生成されました。
moovposition=731965
height=352
avclevel=21
videocodecid=avc1
duration=2.36
width=704
videoframerate=25
avcprofile=88
trackinfo=[object Object]

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

475

ビデオの操作

情報オブジェクトの使用
次の表に、onMetaData() コールバック関数に渡すことのできる、受信したオブジェクト内のビデオメタデータの値を示します。
パラメーター説明aacaot

AAC オーディオオブジェクトタイプ。0、1 または 2 がサポートされています。

avclevel

10、11、20、21 などの AVC IDC レベル番号です。

avcprofile

55、77、100 などの AVC プロファイル番号です。

audiocodecid使用されたオーディオコーデック（コード / デコード技法）を示すストリング（「.Mp3」や「mp4a」など）です。

audiodatarate

オーディオがエンコードされるレートをキロバイト秒で示す数値です。

audiodelay

元の FLV ファイルの「time 0」の時間を示す数値です。オーディオと正しく同期化するには、ビデオコンテンツを少し遅延させる必要があります。

canSeekToEnd

ブール値です。プログレッシブダウンロードされるビデオクリップの最後をシークできるようにするために、最後のフレームにキーフレームを付けて FLV ファイルをエンコードした場合に true になります。最後のフレームにキーフレームを付けずに FLV ファイルをエンコードした場合は false になります。

cuePoints

オブジェクトの配列。FLV ファイルに埋め込まれたそれぞれのキューポイントに 1 つずつあります。FLV ファイルにキューポイントがない場合は、値は未定義となります。各オブジェクトには次のプロパティがあります。

• type：キューポイントのタイプを「navigation」または「event」として指定するストリング。
• name：キューポイントの名前を示すストリング。
• time：キューポイントの時間を示す数値。小数点以下 3 桁（ミリ秒）まで使用します。
• parameters：キューポイントを作成するときにユーザーによって指定される、名前と値のペアを持つオプションのオブジェクト。

duration

ビデオファイルの長さを秒単位で示す数値です。

framerate

FLV ファイルのフレームレートを示す数値です。

heightFLV ファイルの高さをピクセル単位で示す数値です。

seekpoints

ミリ秒単位のタイムスタンプとして使用可能なキーフレームの一覧を示す配列です（オプション）。

tags「ilst」アトム内の情報を表すキーと値のペアの配列であり、MP4 ファイルの ID3 タグと同等です。iTunes ではこれらのタグが使用されます。アートワークが使用可能な場合に、その表示に使用することができます。

trackinfo
videocodecid

サンプル説明 ID など、MP4 ファイル内のすべてのトラックに関する情報を提供するオブジェクトです。
ビデオのエンコードに使用されたコーデックバージョンを示すストリングです。例えば、「avc1」や「VP6F」などです。

videodatarate

FLV ファイルのビデオデータレートを示す数値です。

videoframerate

MP4 ビデオのフレームレートです。

width

FLV ファイルの幅をピクセル単位で示す数値です。

次の表に、videocodecid パラメーターで使用可能な値をまとめます。
videocodecid

コーデック名2

Sorenson H.263

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

476

ビデオの操作

videocodecid

コーデック名3

Screen Video（SWF バージョン 7 以降のみ）

4

VP6（SWF バージョン 8 以降のみ）

5

アルファチャンネルを使用する VP6 Video（SWF バージョン 8 以降のみ）

次の表に、audiocodecid パラメーターで使用可能な値をまとめます。
audiocodecid

コーデック名0

uncompressed

1

ADPCM

2

MP3

4

Nellymoser @ 16 kHz モノラル

5

Nellymoser、8kHz モノラル

6

Nellymoser

10

AAC

11

Speex

onXMPData() の使用
Flash Player 10 以降、Adobe AIR 1.5 以降
onXMPData() コールバック関数は、Adobe F4V または FLV ビデオファイルに埋め込まれている Adobe Extensible
Metadata Platform（XMP）に固有の情報を受け取ります。XMP メタデータには、キューポイントとその他のビデオメタ
データが含まれます。XMP メタデータのサポートは、Flash Player 10 および Adobe AIR 1.5 で導入され、後続のバージョンで使用できます。
次の例では、XMP メタデータ内のキューポイントデータを処理します。
package{import flash.display.*;
import flash.net.*;import flash.events.NetStatusEvent;import flash.media.Video;
public class onXMPDataExample extends Sprite{
public function onXMPDataExample():void{
var videoConnection:NetConnection = new NetConnection();videoConnection.connect(null);var videoStream:NetStream = new NetStream(videoConnection);videoStream.client = this;var video:Video = new Video();
addChild(video);video.attachNetStream(videoStream);
videoStream.play("video.f4v");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

477

ビデオの操作}
public function onMetaData(info:Object):void {trace("onMetaData fired");}public function onXMPData(infoObject:Object):void{
trace("onXMPData Fired\n");//trace("raw XMP =\n");//trace(infoObject.data);
var cuePoints:Array = new Array();
var cuePoint:Object;var strFrameRate:String;
var nTracksFrameRate:Number;var strTracks:String = "";var onXMPXML = new XML(infoObject.data);// Set up namespaces to make referencing easiervar xmpDM:Namespace = new Namespace("http://ns.adobe.com/xmp/1.0/DynamicMedia/");var rdf:Namespace = new Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#");for each (var it:XML in onXMPXML..xmpDM::Tracks){
var strTrackName:String = it.rdf::Bag.rdf::li.rdf::Description.@xmpDM::trackName;var strFrameRateXML:String = it.rdf::Bag.rdf::li.rdf::Description.@xmpDM::frameRate;
strFrameRate = strFrameRateXML.substr(1,strFrameRateXML.length);nTracksFrameRate = Number(strFrameRate);
strTracks += it;}var onXMPTracksXML:XML = new XML(strTracks);
var strCuepoints:String = "";for each (var item:XML in onXMPTracksXML..xmpDM::markers){
strCuepoints += item;}
trace(strCuepoints);}}}

startrekintro.f4v という短いビデオファイルについて、この例は次のトレース行を生成します。行は、XMP メタデータ内のナビゲーションおよびイベントキューポイントのキューポイントデータを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

478

ビデオの操作

onMetaData fired
onXMPData Fired<xmpDM:markers xmlns:xmp="http://ns.adobe.com/xap/1.0/"
xmlns:xmpDM="http://ns.adobe.com/xmp/1.0/DynamicMedia/"
xmlns:stDim="http://ns.adobe.com/xap/1.0/sType/Dimensions#" xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"
xmlns:stEvt="http://ns.adobe.com/xap/1.0/sType/ResourceEvent#"
xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:x="adobe:ns:meta/"><rdf:Seq><rdf:li><rdf:Description xmpDM:startTime="7695905817600" xmpDM:name="Title1" xmpDM:type="FLVCuePoint"
xmpDM:cuePointType="Navigation"><xmpDM:cuePointParams><rdf:Seq><rdf:li xmpDM:key="Title" xmpDM:value="Star Trek"/><rdf:li xmpDM:key="Color" xmpDM:value="Blue"/></rdf:Seq></xmpDM:cuePointParams></rdf:Description></rdf:li><rdf:li><rdf:Description xmpDM:startTime="10289459980800" xmpDM:name="Title2" xmpDM:type="FLVCuePoint"
xmpDM:cuePointType="Event"><xmpDM:cuePointParams><rdf:Seq><rdf:li xmpDM:key="William Shatner" xmpDM:value="First Star"/><rdf:li xmpDM:key="Color" xmpDM:value="Light Blue"/></rdf:Seq></xmpDM:cuePointParams></rdf:Description></rdf:li></rdf:Seq></xmpDM:markers>
onMetaData fired

注意： XMP データでは、時間が秒ではなく DVA Tick で格納されます。キューポイント時間を計算するには、開始時刻を
フレームレートで除算します。例えば、7695905817600 の開始時刻を 254016000000 のフレームレートで除算すると、30:30 になります。
フレームレートを含む完全に未処理の XMP メタデータを表示するには、秒の前のコメント識別子（//）と、onXMPData()
関数の先頭にある 3 つ目の trace() ステートメントを削除します。

XMP について詳しくは、以下を参照してください。

• partners.adobe.com/public/developer/xmp/topic.html• www.adobe.com/devnet/xmp/

イメージメタデータの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
onImageData イベントは、AMF0 データチャンネルを介してイメージデータをバイト配列として送信します。データは、
JPEG、PNG または GIF 形式です。この情報を処理する onImageData() コールバックメソッドは、onCuePoint およびonMetaData のコールバックメソッドを定義する場合と同じ方法で定義します。次の例は、onImageData() コールバックメ
ソッドを使用してイメージデータにアクセスし、表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

479

ビデオの操作

public function onImageData(imageData:Object):void{// display track number
trace(imageData.trackid);
var loader:Loader = new Loader();//imageData.data is a ByteArray object
loader.loadBytes(imageData.data);
addChild(loader);}

テキストメタデータの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
onTextData イベントは、AMF0 データチャンネルを介してテキストデータを送信します。このテキストデータは UTF-8 形式であり、3GP Timed Text 仕様に基づくフォーマットに関する追加情報を格納します。この仕様では、標準化されたサブ
タイトル形式が定義されます。この情報を処理する onTextData() コールバックメソッドは、onCuePoint または onMetaDataのコールバックメソッドを定義する場合と同じ方法で定義します。次の例では、onTextData() メソッドによってトラック ID
番号および対応するトラックテキストが表示されます。
public function onTextData(textData:Object):void{// display the track number
trace(textData.trackid);// displays the text, which can be a null string, indicating old text// that should be erased
trace(textData.text);}

NetStream アクティビティの監視Flash Player 10.3 以降、Adobe AIR 2.7 以降
NetStream アクティビティを監視して、メディアの使用状況の分析とレポートをサポートするために必要な情報を収集します。このセクションで説明されている監視機能を使用すると、メディアを表示するビデオプレーヤーが特定のプレーヤーに限定されることなく、データを収集するメディア測定ライブラリを作成できます。これにより、クライアントの開発者はライブラリを使用するときに好きなビデオプレイヤーを選択できます。アプリケーションでの NetStream オブジェクトの作
成とアクティビティを監視するには、NetMonitor クラスを使用します。NetMonitor クラスは、指定の期間に存在するア
クティブな NetStream のリストを提供し、また NetStream オブジェクトが作成されるたびにイベントを送出します。

NetStream オブジェクトは、再生されるメディアの種類によって、以下の表に示されるイベントを送出します。
イベント

プログレッシブダウン
ロード

RTMP ストリーミング

HTTP ストリーミング

NetStream.Play.Start

可

可

不可

NetStream.Play.Stop

可

可

不可

NetStream.Play.Complete

可

可

不可

NetStream.SeekStart.Notify

可

可

可

NetStream.Seek.Notify

可

可

可

NetStream.Unpause.Notify

可

可

可

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

480

ビデオの操作イベント

プログレッシブダウン
ロード

RTMP ストリーミング

HTTP ストリーミング

NetStream.Unpause.Notify

可

可

可

NetStream.Play.Transition

非対応

可

非対応

NetStream.Play.TransitionComplete

非対応

可

非対応

NetStream.Buffer.Full

可

可

可

NetStream.Buffer.Flush

可

可

可

NetStream.Buffer.Empty

可

可

可

NetStream インスタンスに関連する NetStreamInfo オブジェクトは、メディアで使用された最後のメタデータと XMP
データオブジェクトも格納します。

HTTP ストリーミングを使用してメディアが再生されると、メディアストリームは完全にアプリケーションによって制御されるので、NetStream.Play.Start、NetStream.Play.Stop および NetStream.Play.Complete は送出されません。ビデオプ
レーヤーは、これらのイベントを HTTP ストリーム用に合成して送出します。
同様に、NetStream.Play.Transition と NetStream.Play.TransitionComplete は、プログレッシブダウンロードまたはHTTP メディアでは送出されません。動的ビットレートスイッチングは、RTMP の機能です。HTTP ストリームを使用するビデオプレーヤーで同様の機能がサポートされている場合、ビデオプレーヤーはトランジションイベントの合成と送信を
行えます。

関連項目

Adobe Developer Connection：Measuring video consumption in FlashNetStream イベントの監視
2 種類のイベント、netStatus および mediaTypeData は、有益な使用状況データを提供します。また、タイマーを使用してNetStream の再生ヘッドの位置を定期的に記録することもできます。
netStatus イベントは、ユーザーが表示したストリームの量を把握するために使用できる情報を提供します。バッファーおよび RTMFP ストリームのトランジションイベントも、netStatus イベントになります。

mediaTypeData イベントはメタデータおよび XMP データの情報を提供します。Netstream.Play.Complete イベントは、
mediaTypeData イベントとして送出されます。ストリームに埋め込まれているその他のデータも、キューポイント、テキス
ト、イメージなどの mediaTypeData イベントを介して使用できます。
以下の例は、アプリケーション内のアクティブな NetStream から、ステータスおよびデータイベントを監視するクラスを作成する方法を示します。通常このようなクラスは、分析に関連するデータを収集用のサーバーにアップロードします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

481

ビデオの操作

package com.adobe.example{
import flash.events.NetDataEvent;import flash.events.NetMonitorEvent;import flash.events.NetStatusEvent;import flash.net.NetMonitor;
import flash.net.NetStream;
public class NetStreamEventMonitor{
private var netmon:NetMonitor;
private var heartbeat:Timer = new Timer( 5000 );public function NetStreamEventMonitor(){//Create NetMonitor object
netmon = new NetMonitor();netmon.addEventListener( NetMonitorEvent.NET_STREAM_CREATE, newNetStream );//Start the heartbeat timer
heartbeat.addEventListener( TimerEvent.TIMER, onHeartbeat );heartbeat.start();}//On new NetStream
private function newNetStream( event:NetMonitorEvent ):void{
trace( "New Netstream object");
var stream:NetStream = event.netStream;
stream.addEventListener(NetDataEvent.MEDIA_TYPE_DATA, onStreamData);
stream.addEventListener(NetStatusEvent.NET_STATUS, onStatus);}//On data events from a NetStream object
private function onStreamData( event:NetDataEvent ):void{
var netStream:NetStream = event.target as NetStream;
trace( "Data event from " + netStream.info.uri + " at " + event.timestamp );switch( event.info.handler ){case "onMetaData"://handle metadata;
break;
case "onXMPData"://handle XMP;
break;
case "onPlayStatus"://handle NetStream.Play.Complete
case "onImageData"://handle image
break;
case "onTextData"://handle text
break;
default://handle other events}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

482

ビデオの操作//On status events from a NetStream object
private function onStatus( event:NetStatusEvent ):void{
trace( "Status event from " + event.target.info.uri + " at " + event.target.time );//handle status events}//On heartbeat timer
private function onHeartbeat( event:TimerEvent ):void{
var streams:Vector.<NetStream> = netmon.listStreams();for( var i:int = 0; i < streams.length; i++ ){trace( "Heartbeat on " + streams[i].info.uri + " at " + streams[i].time );//handle heartbeat event}}}}

プレーヤードメインの検出
ユーザーがメディアコンテンツを表示する Web ページの URL およびドメインは、常に簡単に入手できるとは限りません。
ホストしている Web サイトで許可されていれば、ExternalInterface クラスを使用して URL を抽出できます。ただし、サードパーティのビデオプレーヤーを許可している Web サイトには、ExternalInterface の使用を許可していないサイトがあります。そのような場合は、現在の Web ページのドメインを Security クラスの pageDomain プロパティから取得できます。ユーザーのセキュリティとプライバシーのため、完全な URL は開示されません。
ページのドメインは、以下の Security クラスの静的プロパティ pageDomain から取得できます。
var domain:String = Security.pageDomain;

ビデオファイルに関する高度なトピック
Flash Player 9 以降、Adobe AIR 1.0 以降
次のトピックでは、FLV ファイルを操作する上での特別な問題点について取り上げます。

サーバーでホスティングするための FLV ファイルの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
FLV ファイルを操作するとき、FLV ファイル形式を扱えるようサーバーを設定する必要が生じることがあります。MIME
は標準的なデータ仕様であり、非 ASCII ファイルをインターネット上で送信することができます。Web ブラウザーや電子
メールクライアントは、ビデオやオーディオ、グラフィックおよびフォーマット済みテキストを送信できるよう、様々な

MIME タイプを解釈できるしくみになっています。Web サーバーから FLV ファイルをロードするには、ファイル拡張子とMIME タイプを Web サーバーに登録する必要があります。そのため、Web サーバーのマニュアルを確認する必要があります。FLV ファイルの MIME タイプは video/x-flv です。FLV ファイルタイプの詳細は次のとおりです。

• Mime Type：video/x-flv•

ファイル拡張子：.flv•

必須パラメーター：なし

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

483

ビデオの操作•

任意パラメーター：なし•

エンコード上の考慮事項：FLV ファイルはバイナリファイルであること。アプリケーションによってはapplication/octet-stream サブタイプも設定する必要があります。

•

セキュリティ上の問題点：なし•

公開されている仕様：www.adobe.com/go/video_file_format_jp

Microsoft Internet Information Services（IIS）6.0 Web サーバーのストリーミングメディアの処理方法が、旧バージョンの処理方法から変更されました。旧バージョンの IIS では、Flash Video をストリーミングするための修正は不要でした。
しかし、Windows 2003 のデフォルト Web サーバーとして付属している IIS 6.0 では、FLV ファイルをストリーミングメ
ディアとして認識させるには、MIME タイプが必要となります。
外部 FLV ファイルをストリーミングする SWF ファイルが Microsoft Windows Server® 2003 に配置され、ブラウザーで表示されると、SWF ファイルは正常に再生されますが、FLV ビデオはストリーミングされません。この問題は、旧バージョンの Flash オーサリングツールおよびアドビ システムズ社の Macromedia Flash Video Kit for Dreamweaver MX

2004 で作成されたファイルを含め、Windows Server 2003 上に置かれたすべての FLV ファイルに影響を与えます。これらのファイルは、他のオペレーティングシステムでテストした場合は正常に動作します。

FLV ビデオストリーミング用の Microsoft Windows 2003 および Microsoft IIS Server 6.0 の設定については、
www.adobe.com/go/tn_19439_jp を参照してください。

Macintosh のローカル FLV ファイルのターゲット化
Flash Player 9 以降、Adobe AIR 1.0 以降
スラッシュ（/）を使用する相対パスにより、Apple® Macintosh® の非システムドライブからローカル FLV を再生しようとしても、ビデオは再生されません。ここで、非システムドライブとは、CD-ROM、パーティション分割されたハードディ
スク、リムーバブルストレージメディア、外部ストレージメディアなどがありますが、これらに限定されるわけではありません。
注意：再生されない理由は、Flash Player または AIR 上の制限ではなく、オペレーティングシステムの制限です。

Macintosh の非システムドライブから FLV ファイルを再生するには、スラッシュ（/）ベースではなくコロン（:）ベースの表記による絶対パスにより、そのファイルを参照します。次に、2 つの表記法の違いを示します。

•

スラッシュベース表記：myDrive/myFolder/myFLV.flv•

コロンベース表記：（Mac OS®）myDrive:myFolder:myFLV.flv

ビデオの例：ビデオジュークボックス
Flash Player 9 以降、Adobe AIR 1.0 以降
次の例では、順番に再生されるビデオのリストを動的にロードする、シンプルなビデオジュークボックスを構築します。こうすると、一連のビデオチュートリアルを閲覧したり、ユーザーが要求したビデオの再生前にどの広告を再生するかを指定したりできるようなアプリケーションを構築することができます。この例は、ActionScript 3.0 の次のような機能を示しています。

•

ビデオファイルの再生の進行状況に基づく再生ヘッドの更新•

ビデオファイルのメタデータの監視および解析•

ネットストリームの特定のコーデックの処理•

動的にロードされた FLV のロード、再生、一時停止、停止

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

484

ビデオの操作•

ネットストリームのメタデータに基づく、表示リストの Video オブジェクトのサイズ変更

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。ビデオジュークボックスアプリ
ケーションのファイルは、Samples/VideoJukebox フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

VideoJukebox.fla

Flex（MXML）または Flash（FLA）のメインアプリケーションファイル。

またはVideoJukebox.mxml
VideoJukebox.as

このクラスは、アプリケーションの主な機能を提供します。

playlist.xml

ビデオジュークボックスにロードされるビデオファイルをリストするファイル。

ビデオプレイリストファイルのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
外部の playlist.xml ファイルは、ロードするビデオおよび再生の順序を指定します。XML ファイルをロードするには、次に示すように、URLLoader オブジェクトと URLRequest オブジェクトを使用する必要があります。
uldr = new URLLoader();uldr.addEventListener(Event.COMPLETE, xmlCompleteHandler);uldr.load(new URLRequest(PLAYLIST_XML_URL));

このコードは、VideoJukebox クラスのコンストラクターに配置されるので、ファイルはコードが実行される前にロードされます。XML ファイルのロードが完了するとすぐに xmlCompleteHandler() メソッドが呼び出され、次のコードに示すように、外部ファイルが XML オブジェクトに解析されます。
private function xmlCompleteHandler(event:Event):void{playlist = XML(event.target.data);
videosXML = playlist.video;main();}

playlist の XML オブジェクトには、外部ファイルから取得された未処理 XML がありますが、ビデオの XML は、ビデオノードしか含まない XMLList オブジェクトです。サンプルの playlist.xml ファイルを次のコード例に示します。
<videos><video url="video/caption_video.flv" /><video url="video/cuepoints.flv" /><video url="video/water.flv" /></videos>

最後に xmlCompleteHandler() メソッドが main() メソッドを呼び出し、表示リスト上の様々なコンポーネントインスタンスに加え、外部 FLV ファイルをロードするために使用される NetConnection および NetStream オブジェクトを設定します。

ユーザーインターフェイスの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーインターフェイスを構築するには、表示リストに 5 つの Button インスタンスをドラッグし、それぞれ playButton、

pauseButton、stopButton、backButton、forwardButton というインスタンス名を与える必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

485

ビデオの操作

これらの Button インスタンスのそれぞれに対し、次のコード例に示すように、click イベントのハンドラーを割り当てる必要があります。
playButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);pauseButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);
stopButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);backButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);
forwardButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);

次のコードで示すように、buttonClickHandler() メソッドでは、どのボタンインスタンスがクリックされたかを判断するために switch ステートメントを使用します。
private function buttonClickHandler(event:MouseEvent):void{switch (event.currentTarget){case playButton:
ns.resume();break;
case pauseButton:
ns.togglePause();break;
case stopButton:
ns.pause();ns.seek(0);break;
case backButton:
playPreviousVideo();break;
case forwardButton:
playNextVideo();break;}}

次に、Slider インスタンスを表示リストに追加し、volumeSlider というインスタンス名を与えます。次のコードは、Slider
インスタンスの liveDragging プロパティを true に設定し、Slider インスタンスの change イベントのイベントリスナーを定義します。
volumeSlider.value = volumeTransform.volume;
volumeSlider.minimum = 0;
volumeSlider.maximum = 1;
volumeSlider.snapInterval = 0.1;
volumeSlider.tickInterval = volumeSlider.snapInterval;
volumeSlider.liveDragging = true;
volumeSlider.addEventListener(SliderEvent.CHANGE, volumeChangeHandler);

表示リストに ProgressBar インスタンスを追加し、positionBar というインスタンス名を与えます。次のコード例で示すように、mode プロパティを manual に設定します。
positionBar.mode = ProgressBarMode.MANUAL;

最後に、表示リストに Label インスタンスを追加し、positionLabel というインスタンス名を与えます。Label インスタンスの値は、Timer インスタンスによって設定されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

486

ビデオの操作

ビデオオブジェクトのメタデータの監視Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player がロードされた各ビデオのメタデータを検出すると、onMetaData() コールバックハンドラーが NetStream オ
ブジェクトの client プロパティで呼び出されます。次のコードではオブジェクトを初期化し、指定のコールバックハンド
ラーを設定します。
client = new Object();client.onMetaData = metadataHandler;

metadataHandler() メソッドは、コードの前部で指定されたメタプロパティにデータをコピーします。これにより、アプリ
ケーション全体で、いつでも現在のビデオのメタデータにアクセスすることが可能になります。次に、ステージ上の Video
オブジェクトは、メタデータから返されたサイズに合わせてサイズ変更されます。最後に、再生中のビデオのサイズに合わ
せて positionBar プログレスバーインスタンスが移動、サイズ変更されます。次のコードは、metadataHandler() メソッド全体を示しています。
private function metadataHandler(metadataObj:Object):void{meta = metadataObj;
vid.width = meta.width;
vid.height = meta.height;
positionBar.move(vid.x, vid.y + vid.height);
positionBar.width = vid.width;}Video の動的なロードFlash Player 9 以降、Adobe AIR 1.0 以降
ビデオを動的にロードするには、アプリケーションで NetConnection および NetStream オブジェクトを使用する必要があります。次のコードは NetConnection オブジェクトを作成し、null を connect() メソッドに渡します。null を指定すると、Flash Player は、Flash Media Server などのサーバーではなく、ローカルサーバー上のビデオに接続します。
次のコードは、NetConnection および NetStream インスタンスの両方を作成し、netStatus イベントのイベントリスナーを定義し、client オブジェクトを client プロパティに割り当てます。
nc = new NetConnection();nc.connect(null);
ns = new NetStream(nc);ns.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
ns.client = client;

ビデオのステータスが変更されるたびに netStatusHandler() メソッドが呼び出されます。ステータスとは、ビデオの再生の開始または停止、バッファリング、またはビデオストリームが見つからないなどの状態を指します。次のコードはnetStatusHandler() イベントをリストします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

487

ビデオの操作

private function netStatusHandler(event:NetStatusEvent):void{try{switch (event.info.code){
case "NetStream.Play.Start":t.start();break;
case "NetStream.Play.StreamNotFound":case "NetStream.Play.Stop":
t.stop();playNextVideo();break;}}
catch (error:TypeError){// Ignore any errors.
}}

前述のコードは、info オブジェクトのコードプロパティを評価し、コードが「NetStream.Play.Start」、「NetStream.Play.StreamNotFound」または「NetStream.Play.Stop」のどれであるかをフィルタリングします。他のす
べてのコードは無視されます。ネットストリームが開始すると、再生ヘッドを更新する Timer インスタンスがコードによって開始します。ネットストリームが見つからない場合、または停止している場合は、Timer インスタンスは停止し、アプリ
ケーションはプレイリスト内の次のビデオの再生を試行します。

Timer が実行されるたびに、ProgressBar クラスの setProgress() メソッドを呼び出すことで positionBar プログレスバーイン
スタンスの現在の位置が更新され、Label インスタンスである positionLabel は、現在のビデオの経過時間と合計時間によって更新されます。
private function timerHandler(event:TimerEvent):void{try{positionBar.setProgress(ns.time, meta.duration);
positionLabel.text = ns.time.toFixed(1) + " of " meta.duration.toFixed(1) + " seconds";}
catch (error:Error){// Ignore this error.
}}

ビデオのボリュームの制御
Flash Player 9 以降、Adobe AIR 1.0 以降
動的にロードされたビデオのボリュームを制御するには、NetStream オブジェクトで soundTransform プロパティを設定します。ビデオジュークボックスアプリケーションでは、Slider インスタンスである volumeSlider の値を変更することでボ
リュームレベルを変更することができます。次のコードは、NetStream オブジェクトの soundTransform プロパティに設定されている SoundTransform オブジェクトに Slider コンポーネントの値を割り当てることで、ボリュームレベルを変更する方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

488

ビデオの操作

private function volumeChangeHandler(event:SliderEvent):void{
volumeTransform.volume = event.value;
ns.soundTransform = volumeTransform;}

ビデオ再生の制御
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションの残りの部分では、ビデオがビデオストリームの末尾に到達したとき、またはユーザーが前のビデオまたは次のビデオにスキップしたときに、ビデオの再生を制御します。
次のメソッドは、選択中のインデックスの XMLList からビデオ URL を取得します。
private function getVideo():String{
return videosXML[idx].@url;}

playVideo() メソッドは、NetStream オブジェクトの play() メソッドを呼び出し、現在選択されているビデオをロードします。
private function playVideo():void{
var url:String = getVideo();ns.play(url);}

playPreviousVideo() メソッドは、現在のビデオインデックスをデクリメントし、playVideo() メソッドを呼び出して新しいビ
デオファイルをロードし、プログレスバーを表示可能な状態に設定します。
private function playPreviousVideo():void{if (idx > 0){idx--;
playVideo();positionBar.visible = true;}}

最後のメソッド、playNextVideo() はビデオインデックスをインクリメントし、playVideo() メソッドを呼び出します。現在のビデオがプレイリストの最後のビデオである場合は、Video オブジェクトで clear() メソッドが呼び出され、プログレスバー
インスタンスの visible プロパティが false に設定されます。
private function playNextVideo():void{if (idx < (videosXML.length() - 1)){
idx++;
playVideo();positionBar.visible = true;}else{
idx++;
vid.clear();positionBar.visible = false;}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

489

ビデオの操作

ハードウェアアクセラレーションによる表示のためのStageVideo クラスの使用
Flash Player 10.2 以降
Flash Player では、H.264 デコードにハードウェアアクセラレーションを使用することで、ビデオのパフォーマンスが最適化されます。StageVideo API を使用して、さらにパフォーマンスを向上できます。ステージビデオを使用すると、アプリ
ケーションはハードウェアアクセラレーションによる表示を活用できます。

StageVideo API をサポートするランタイムには次のものがあります。

• Flash Player 10.2 以降
注意：Flash Player 11.4 ／ AIR 3.4 以上では、StageVideo にカメラ入力を使用できます。
ステージビデオ機能に関するダウンロード可能なソースコードやその他の詳細情報は、「Getting Started with Stage

Video」から取得できます。
StageVideo クイックスタートチュートリアルについては、「Working with Stage Video」を参照してください。

StageVideo を使用したハードウェアアクセラレーションについて
ビデオの拡大／縮小、カラー変換、転送などのハードウェアアクセラレーションによる表示は、ハードウェアアクセラレー
ションによるデコードのパフォーマンス面のメリットを拡大します。GPU（ハードウェア）アクセラレーション機能を備えるデバイスでは、flash.media.StageVideo オブジェクトを使用して、デバイスハードウェア上で直接ビデオを処理できます。直接処理すると CPU が解放され、GPU によるビデオの処理中に他のタスクが実行されます。一方、従来の Video ク
ラスは、通常はソフトウェアによる表示を使用します。ソフトウェアによる表示は CPU 内で実行され、大量の共有システ
ムリソースが消費される場合があります。
現在は、完全な GPU アクセラレーションを実行するデバイスは多くありません。しかし、ステージビデオを使用すると、利用可能なあらゆるハードウェアアクセラレーションをアプリケーションで最大限に活用できるようになります。

StageVideo クラスにより Video クラスが不要になるわけではありません。この 2 つのクラスは連携し、デバイスリソースの許容範囲内で最適なビデオ表示エクスペリエンスをいつでも実現します。アプリケーション側で、適切なイベントを監視し必要に応じて StageVideo と Video を切り替えることで、ハードウェアアクセラレーションを活用できます。

StageVideo クラスには、ビデオの使用法に関していくつか制限があります。StageVideo を実装する前に、ガイドラインを
見直し、アプリケーションでこれらの制限を受け入れられることを確認してください。制限を受け入れる場合は、Flash
Player でハードウェアアクセラレーションによる表示が利用可能であることを検出したときは常に StageVideo クラスを使用してください。491 ページの「ガイドラインおよび制限」を参照してください。

平行面：ステージビデオと Flash 表示リスト
Flash Player ではステージビデオモデルを使用して、表示リストからビデオを分離できます。Flash Player では、複合的な表示を次のような z 順序による 2 枚の面に分割します。
ステージビデオ面 ステージビデオ面は後側に位置し、StageVideo クラスでは、ハードウェアアクセラレーションによるビデオのみが表示されます。このような設計により、ハードウェアアクセラレーションがサポートされない場合、またはデバ
イス上で利用できない場合は、ステージビデオ面は利用できません。ActionScript で、StageVideo オブジェクトは、ス
テージビデオ面で再生されるビデオを処理します。

Flash 表示リスト面 Flash 表示リストのエンティティは、ステージビデオ面の前にある面の上に構成されます。表示リストのエンティティには、再生コントロールなど、ランタイムによってレンダリングされるすべてのものが含まれます。ハード
ウェアアクセラレーションが利用できない場合、ビデオは Video クラスオブジェクトを使用して、この面上のみで再生されます。ステージビデオは常に Flash 表示リストのグラフィックの背後に表示されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

490

ビデオの操作

䋩

↪

䉕૶

䊢䊮

䉲

䊷

䊤䊧

䉪䉶

U䉝

P

䋨G

sh
Fla 䉪
䈱 䉾
ઁ 䊐䉞
䊤
䉫

㕙

䉥

䊎䊂

䉳

䊷

䊁

䉴

䊎䊂

䊎䊂

䉥

䉥

1

䉮

2

䊨
䊮䊃

䉮

䊷

䊨
䊮䊃

h⴫

␜

䊦

䊷

䊥䉴

䊦

1

2
䋩

䉂

U䈱

CP
䊃䋨

s
Fla
ビデオ表示面

StageVideo オブジェクトは、画面上でウィンドウとして配置された、回転なしの矩形領域に表示されます。ステージビデ
オ面の背後にオブジェクトをレイヤー化することはできませんが、Flash 表示リスト面を使用して、ステージビデオ面の上に他のグラフィックをレイヤー化できます。ステージビデオは表示リストと同時に実行されます。このため、この 2 つのメ
カニズムを同時に使用して、2 つの異なる面を使用する統合ビジュアル効果を作成できます。例えば、後ろの面で実行中のステージビデオ上で動作する再生コントロール用に、前の面を使用できます。

ステージビデオと H.264 コーデック
Flash Player アプリケーションでは、ビデオのハードウェアアクセラレーションの実装には次の 2 つの手順が伴います。
1 ビデオの H.264 エンコーディング
2 StageVideo API の実装
最適な結果を得るためには、両方の手順を実行してください。H.264 コーデックを使用すると、ビデオのデコードから表示まで、ハードウェアアクセラレーションを最大限に活用できます。
ステージビデオによって、GPU から CPU へのリードバックが発生しなくなります。つまり、表示リストオブジェクトとの合成のために、GPU が CPU に対してデコードされたフレームを送り返すことがありません。この代わりに、デコードされレンダリングされたフレームを、GPU が直接、表示リストオブジェクトの背後の画面に転送します。このテクニックによって CPU とメモリの使用率が削減され、さらにピクセル精度が向上します。
関連項目

454 ページの「ビデオ形式について」

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

491

ビデオの操作

ガイドラインおよび制限
ビデオがフルスクリーンモードで実行中のとき、ハードウェアアクセラレーションをサポートしているデバイスでは、ス
テージビデオは常に利用可能な状態にあります。ただし、Flash Player はブラウザー内でも実行されます。ブラウザーコン
テキストでステージビデオを利用できるかどうかは wmode 設定の影響を受けます。ステージビデオを使用する場合は、常にwmode="direct" を使用するようにしてください。ステージビデオは、フルスクリーンモードの場合を除き、この他の wmode
設定との互換性がありません。この制約によって、実行時にステージビデオが予期せず利用可能になったり利用不能になったりするおそれがあります。例えば、ステージビデオの実行中にユーザーがフルスクリーンモードを終了すると、ビデオコ
ンテキストがブラウザーに戻されます。ブラウザーの wmode パラメーターが "direct" に設定されていない場合は、ステージ
ビデオが突然利用できなくなる可能性があります。Flash Player は一連のイベントによって再生コンテキストの変更をアプ
リケーションに伝達します。StageVideo API を実装する場合は、ステージビデオが利用不能になった場合のバックアップ
として Video オブジェクトを保持してください。
ステージビデオはハードウェアと直接関係付けられるので、一部のビデオ機能に制約が生じます。ステージビデオには、次の制約が適用されます。

• Flash Player でビデオを同時に表示できる StageVideo オブジェクトの数は、SWF ファイルごとに最大 4 個です。ただし、実際の数は、デバイスのハードウェアリソースに応じてさらに少なく制限される場合があります。

•

ビデオのタイミングは、ランタイムにより表示されるコンテンツのタイミングとは同期しません。

•

ビデオ表示領域の形は長方形のみです。楕円形や不規則な形などの複雑な領域に表示することはできません。

•

ビデオを回転することはできません。

•

ビデオのビットマップキャッシュを保持することはできません。また、BitmapData オブジェクトを使用してビデオにアクセスすることはできません。

•

ビデオにフィルターを適用することはできません。

•

ビデオにカラー変換を適用することはできません。

•

ビデオにアルファ値を適用することはできません。

•

表示リスト面のオブジェクトに適用されたブレンドモードは、ステージビデオには適用されません。

•

ビデオを配置できる位置はフルピクセル境界のみです。

•

指定されたデバイスハードウェアにおいて、GPU レンダリングは最も適した手段ではありますが、デバイス間で完全なピクセル整合性が保たれているわけではありません。ドライバーやプラットフォームの違いにより、多少の差異が生じます。

•

必須のカラースペースの一部をサポートしないデバイスも少数存在します。例えば、一部のデバイスは H.264 標準である BT.709 をサポートしません。そのような場合は、BT.601 を使用して高速表示を実現できます。

• wmode 設定が normal、opaque、transparent の場合、ステージビデオを使用することはできません。ステージビデオ
では、フルスクリーンモードの場合を除き、wmode=direct のみがサポートされます。WMODE は、Safari 4 以降およびIE 9 以降では無効です。
ほとんどの場合、これらの制限によりビデオプレーヤーアプリケーションが影響を受けることはありません。これらの制限を受け入れられる場合は、可能な限りステージビデオを使用してください。

関連項目

159 ページの「フルスクリーンモードの操作」

StageVideo API の使用
ステージビデオは、ビデオの再生とデバイスのパフォーマンスを向上するためのランタイム内部のメカニズムです。このメカニズムを作成し維持するのはランタイムです。開発者の役割は、このメカニズムを活用するようにアプリケーションを設定することです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

492

ビデオの操作

ステージビデオを使用するには、ステージビデオが利用可能であるか、利用不能であるかを検出するイベントハンドラーのフレームワークを実装します。ステージビデオが利用可能であるという通知を受信した場合、Stage.stageVideos プロパティ
から StageVideo オブジェクトを取得します。ランタイムがこの Vector オブジェクトに値を設定します。このオブジェクト
は 1 つ以上の StageVideo オブジェクトで構成されます。開発者はその後、Video オブジェクトではなく、これらのStageVideo オブジェクトのいずれかを使用して、ストリーミングビデオを表示できます。
Flash Player で、ステージビデオが利用不能となったことを示す通知を受信した際は、ビデオストリームを Video オブジェ
クトに再度切り替えてください。
注意：StageVideo オブジェクトを作成することはできません。

Stage.stageVideos プロパティ
Stage.stageVideos プロパティは Vector オブジェクトであり、ここから StageVideo インスタンスにアクセスできます。この
Vector には、ハードウェアおよびシステムリソースに応じて、最大 4 個の StageVideo オブジェクトを含めることができます。モバイルデバイスでは、1 個のみ、または「なし」に制限されることがあります。
ステージビデオが利用不能な場合、この Vector にはオブジェクトは含まれません。実行時エラーを回避するため、最新のStageVideoAvailability イベントが、ステージビデオが利用可能であることを示している場合のみ、このベクターのメンバーにアクセスするようにしてください。

StageVideo イベント
StageVideo API フレームワークは、次のイベントを提供します。
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY Stage.stageVideos プロパティの変更時に送信されます。
StageVideoAvailabilityEvent.availability プロパティは、AVAILABLE と UNAVAILABLE のどちらかが指定されます。
stageVideos プロパティに StageVideo オブジェクトが含まれているかどうかの確認には、Stage.stageVideos のベクターの長さを直接チェックするのではなく、このイベントを使用してください。

StageVideoEvent.RENDER_STATE NetStream または Camera オブジェクトが StageVideo オブジェクトに割り当てられ、再生中となったときに送信されます。ハードウェア、ソフトウェア、利用不能（何も表示されない）の中から、現在使用中のデコードの種類が示されます。イベントターゲットには、videoWidth プロパティと videoHeight プロパティが含まれており、これらはビデオのビューポートのサイズを変更するために安全に使用できます。
重要：StageVideo ターゲットオブジェクトから取得された座標は、標準表示リストに含まれていないので、ステージの座標が使用されます。

VideoEvent.RENDER_STATE Video オブジェクトの使用中に送信されます。ソフトウェアによるデコードとハードウェ
アアクセラレーションによるデコードのどちらが使用中であるかを示します。このイベントがハードウェアアクセラレー
ションによるデコードを示す場合は、可能であれば StageVideo オブジェクトに切り替えてください。Video イベントター
ゲットには、videoWidth プロパティと videoHeight プロパティが含まれており、これらはビデオのビューポートのサイズを変更するために安全に使用できます。

StageVideo 機能の実装ワークフロー
次のトップレベルの手順に従って、StageVideo 機能を実装します。

1 Stage.stageVideos ベクターが変更されたタイミングを知るために、StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントをリッスンします 494 ページの「StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントの使用」を参照してください

2 StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントによりステージビデオが利用可能であることがレポートされた場合に、そのイベントハンドラー内の Stage.stageVideos ベクターオブジェクトを使用して StageVideo オブ
ジェクトにアクセスします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

493

ビデオの操作

3 StageVideo.attachNetStream() を使用して NetStream オブジェクトを関連付けるか、または StageVideo.attachCamera() を使用して Camera オブジェクトを関連付けます。

4 NetStream.play() を使用してビデオを再生します。
5 ビデオ再生のステータスを知るために、StageVideo オブジェクト上の StageVideoEvent.RENDER_STATE イベントをリッスンします。また、このイベントの受領は、ビデオの width および height プロパティが初期化または変更されたことも示します。495 ページの「StageVideoEvent.RENDER_STATE イベントと VideoEvent.RENDER_STATE イベ
ントの使用」を参照してください。

6 Video オブジェクト上の VideoEvent.RENDER_STATE イベントをリッスンします。このイベントは、StageVideoEvent.RENDER_STATE と同じステータスを提供します。したがって、このイベントを使用して GPU アクセ
ラレーションが利用可能かどうかを判断することができます。また、このイベントの受領は、ビデオの width およびheight プロパティが初期化または変更されたことも示します。495 ページの「StageVideoEvent.RENDER_STATE イ
ベントと VideoEvent.RENDER_STATE イベントの使用」を参照してください。

StageVideo イベントリスナーの初期化
アプリケーションの初期化中に、StageVideoAvailabilityEvent と VideoEvent のリスナーを設定します。例えば、これらのリスナーを flash.events.Event.ADDED_TO_STAGE イベントハンドラー内で初期化できます。このイベントによって、アプ
リケーションがステージ上で可視状態となることを保証できます。
public class SimpleStageVideo extends Sprite
private var nc:NetConnection;
private var ns:NetStream;
public function SimpleStageVideo(){// Constructor for SimpleStageVideo class// Make sure the app is visible and stage available
addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);}
private function onAddedToStage(event:Event):void{//...
// Connections
nc = new NetConnection();nc.connect(null);
ns = new NetStream(nc);ns.addEventListener(NetStatusEvent.NET_STATUS, onNetStatus);
ns.client = this;// Screenvideo = new Video();video.smoothing = true;// Video Events// the StageVideoEvent.STAGE_VIDEO_STATE informs you whether// StageVideo is available
stage.addEventListener(StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY,
onStageVideoState);// in case of fallback to Video, listen to the VideoEvent.RENDER_STATE// event to handle resize properly and know about the acceleration mode running
video.addEventListener(VideoEvent.RENDER_STATE, videoStateChange);//...
}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

494

ビデオの操作

StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントの使用
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY ハンドラーでは、StageVideo が利用可能であるかどうかに基づいて、Video と StageVideo のどちらのオブジェクトを使用するかを決定します。StageVideoAvailabilityEvent.availability
プロパティが StageVideoAvailability.AVAILABLE に設定されている場合は、StageVideo を使用します。この場合、Stage.stageVideos の Vector に 1 つ以上の StageVideo オブジェクトが含まれていると見なすことができます。
Stage.stageVideos プロパティから StageVideo オブジェクトを取得し、それに NetStream オブジェクトを割り当てます。
StageVideo オブジェクトは常に後ろの面に表示されるので、常に前の面に表示される既存の Video オブジェクトがある場
合にはそれらを削除します。また、このイベントハンドラーを使用して、StageVideoEvent.RENDER_STATE イベントのリスナーを追加することもできます。
StageVideoAvailabilityEvent.availability プロパティが StageVideoAvailability.UNAVAILABLE に設定されている場合は、StageVideo の使用や Stage.stageVideos ベクターへのアクセスは避けてください。この場合は、Video オブジェクトにNetStream オブジェクトを割り当ててください。最後に、ステージに StageVideo オブジェクトまたは Video オブジェクトを追加し、NetStream.play() を呼び出します。
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY イベントの処理方法について、次のコードに示します。
private var sv:StageVideo;
private var video:Video;
private function onStageVideoState(event:StageVideoAvailabilityEvent):void{// Detect if StageVideo is available and decide what to do in toggleStageVideo
toggleStageVideo(event.availability == StageVideoAvailability.AVAILABLE);}
private function toggleStageVideo(on:Boolean):void{// To choose StageVideo attach the NetStream to StageVideoif (on){stageVideoInUse = true;
if ( sv == null ){sv = stage.stageVideos[0];sv.addEventListener(StageVideoEvent.RENDER_STATE, stageVideoStateChange);sv.attachNetStream(ns);}if (classicVideoInUse){// If you use StageVideo, remove from the display list the// Video object to avoid covering the StageVideo object

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

495

ビデオの操作// (which is always in the background)stage.removeChild ( video );classicVideoInUse = false;}} else{// Otherwise attach it to a Video object
if (stageVideoInUse)
stageVideoInUse = false;classicVideoInUse = true;video.attachNetStream(ns);stage.addChildAt(video, 0);}
if ( !played ){played = true;ns.play(FILE_NAME);}}

重要：アプリケーションが最初に Stage.stageVideos[0] のベクターエレメントにアクセスすると、デフォルトの rect が「0,0,0,0」に設定され、pan プロパティと zoom プロパティにデフォルト値が使用されます。これらの値を必要な値に再設定するようにしてください。StageVideoEvent.RENDER_STATE イベントターゲットまたは VideoEvent.RENDER_STATE イ
ベントターゲットの videoWidth プロパティと videoHeight プロパティを使用して、ビデオビューポートのサイズを計算できます。
このサンプルアプリケーションのソースコード全体は、「Getting Started with Stage Video」からダウンロードしてください。

StageVideoEvent.RENDER_STATE イベントと VideoEvent.RENDER_STATE イベントの使用
StageVideo オブジェクトと Video オブジェクトは、表示環境が変化した際にアプリケーションに通知するイベントを送信します。これらのイベントは、StageVideoEvent.RENDER_STATE と VideoEvent.RENDER_STATE です。

NetStream オブジェクトが割り当てられ再生を開始したときに、StageVideo オブジェクトまたは Video オブジェクトから
レンダリング状態イベントが送出されます。また、ビデオビューポートのサイズが変更された場合など、表示環境が変化したときにもこのイベントが送信されます。これらの通知を使用して、ビューポートを、イベントターゲットオブジェクトの
現在の videoHeight および videoWidth 値に再設定します。
レポートされるレンダリング状態には次のものがあります。

• RENDER_STATUS_UNAVAILABLE• RENDER_STATUS_SOFTWARE• RENDER_STATUS_ACCELERATED
現在どのクラスがビデオを再生しているかに関わらず、レンダリング状態では、ハードウェアアクセラレーションによるデコードがいつ使用されるかが示されます。必要なデコードが利用可能かどうかを確認するには、StageVideoEvent.status プロ
パティをチェックしてください。このプロパティが「unavailable」に設定されている場合、StageVideo オブジェクトによりビデオを再生することはできません。この状態の場合、すぐに NetStream オブジェクトを Video オブジェクトに割り当て直す必要があります。他の状態の場合、アプリケーションに対して現在のレンダリング状況が通知されます。

Flash Player における StageVideoEvent オブジェクトと VideoEvent オブジェクトの各レンダリング状態値が表す状況について、次の表に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

496

ビデオの操作VideoStatus.ACCELERATEDVideoStatus.SOFTWARE

VideoStatus.UNAVAILABLE

StageVideoEven デコードも表示もハードウェア
で実行されています（最適なパt

表示はハードウェアで、デ
コードはソフトウェアで実行されています（許容できるパフォーマンス）。

リソースがなく、何も表示されていません。Video オブジェク

フォーマンス）。

VideoEvent

表示はソフトウェアで、デコー
ドはハードウェアで実行されています（最新のデスクトップシ
ステムでのみ許容できるパフォーマンス。フルスクリーンのパフォーマンスが低下）。

表示はソフトウェアで、デコードもソフトウェアで実行されています（パフォーマン
スの面では最悪のケース。フ
ルスクリーンのパフォーマン
スが低下）。

ビデオの処理に利用可能な GPUトに戻してください。

(N/A)

カラースペース
ステージビデオは、下層のハードウェア機能を使用して、カラースペースをサポートします。SWF コンテンツには、優先するカラースペースを示すメタデータを設定できますが、そのカラースペースが使用可能かどうかを判定するのはデバイスのグラフィックハードウェアです。様々なカラースペースをサポートするデバイスもあれば、カラースペースを一切サポー
トしないデバイスもあります。要求されたカラースペースがハードウェアでサポートされていない場合には、Flash Player
は、サポートされるカラースペースの中で最も近いものを見つけようとします。
ハードウェアでサポートされるカラースペースを調べるには、StageVideo.colorSpaces プロパティを使用します。このプロパ
ティは、サポートされるカラースペースのリストを String の Vector で返します。
var colorSpace:Vector.<String> = stageVideo.colorSpaces();

現在再生中のビデオで使用されているカラースペースを調べるには、StageVideoEvent.colorSpace プロパティをチェックしま
す。StageVideoEvent.RENDER_STATE イベントのイベントハンドラーで、このプロパティをチェックしてください。
var currColorSpace:String;//StageVideoEvent.RENDER_STATE event handler
private function stageVideoRenderState(event:Object):void{//...
currColorSpace = (event as StageVideoEvent).colorSpace;//...
}

サポートされないカラースペースの代わりとなるカラースペースが見つからない場合、ステージビデオではデフォルトのカ
ラースペースである BT.601 が使用されます。例えば、H.264 エンコーディングによるビデオストリームでは、通常 BT.709
カラースペースが使用されます。デバイスハードウェアが BT.709 をサポートしていない場合、colorSpace プロパティは"BT601" を返します。StageVideoEvent.colorSpace の値が "unknown" の場合、カラースペースを調べる手段をハードウェアが提供していないことを示します。
現在のカラースペースがアプリケーション側で受け入れられないと判断された場合は、StageVideo オブジェクトからVideo オブジェクトに切り替えることが可能です。Video クラスでは、ソフトウェア合成によってすべてのカラースペース
がサポートされます。

最終更新日 2015/10/14

497

第 26 章：カメラの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーのコンピューターに接続されたカメラをビデオデータのソースとして使用し、ActionScript で表示および操作することができます。Camera クラスは、ActionScript に組み込まれているメカニズムで、コンピューターまたはデバイスのカメラを操作するためのものです。
モバイルデバイスでは、CameraUI クラスを使用することもできます。CameraUI クラスは、個別のカメラアプリケー
ションを起動し、ユーザーが静止画やビデオをキャプチャできるようにします。ユーザーがキャプチャを終了すると、アプ
リケーションは MediaPromise オブジェクトを使用して、イメージやビデオにアクセスすることができます。
関連項目

Christian Cantrell：How to use CameraUI in a Cross-platform Way
Michaël CHAIZE：Android, AIR and the Camera

Camera クラスについてFlash Player 9 以降、Adobe AIR 1.0 以降
Camera オブジェクトを使用すると、ユーザーのローカルカメラに接続し、ビデオをローカルでブロードキャスト（ユーザーに表示）したり、リモートで Flash Media Server などのサーバーに表示したりすることができます。
Camera クラスにより、ユーザーのカメラに関する次の情報を入手することができます。

•

ユーザーのコンピューターまたはデバイスにインストールされたカメラのうち、使用可能なもの•

カメラがインストールされているかどうか• Flash Player がユーザーのカメラを使用できるかどうか•

どのカメラがアクティブか•

キャプチャされるビデオの幅と高さ

Camera クラスには、Camera オブジェクトの操作で使用できる便利なメソッドとプロパティがいくつかあります。例えば、
静的な Camera.names プロパティには、ユーザーのコンピューターにインストールされているカメラ名の配列があります。
また、name プロパティを使用し、アクティブなカメラの名前を表示することもできます。
注意：ネットワークを介してカメラビデオをストリーミングする際には、必ずネットワーク障害への対応が必要となります。
ネットワーク障害は、特にモバイルデバイスにおいて、様々な原因により発生する可能性があります。

カメラコンテンツの画面への表示
Flash Player 9 以降、Adobe AIR 1.0 以降
カメラに接続すると、NetConnection および NetStream クラスでビデオをロードするよりもコード数が少なくて済みます。Flash Player では、カメラにアクセスする前に、そのカメラに接続するためのユーザーの許可が必要なので、Camera
クラスは扱いが面倒になる可能性もあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

498

カメラの操作

次のコードでは、Camera クラスを使用してユーザーのローカルカメラに接続する方法を示します。
var cam:Camera = Camera.getCamera();var vid:Video = new Video();vid.attachCamera(cam);
addChild(vid);

注意：Camera クラスには、コンストラクターメソッドはありません。新しい Camera インスタンスを作成するには、静的な Camera.getCamera() メソッドを使用します。

カメラアプリケーションの設計
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーのカメラに接続されるアプリケーションを作成するには、コードで次の点を考慮する必要があります。

•

カメラがインストールされているかどうかを確認します。使用できるカメラがない状況に対応します。

• Flash Player の場合のみ、ユーザーがカメラへのアクセスを明示的に許可したかどうかをチェックします。セキュリティの理由から、カメラへのアクセスを許可するか拒否するかを選択するため、Flash Player の設定ダイアログボックスが表示されます。これにより、Flash Player がユーザーの許可なくカメラに接続し、ビデオストリームをブロードキャストすることができなくなります。ユーザーの許可がある場合は、アプリケーションはユーザーのカメラに接続することができます。ユーザーが拒否した場合、アプリケーションはユーザーのカメラにアクセスすることができません。いずれの場合
でも、適切に対応する必要があります。

• AIR の場合のみ、アプリケーションでサポートされているデバイスプロファイルで Camera クラスがサポートされるかどうかをチェックします。

• Camera クラスはモバイルブラウザーではサポートされません。
• Camera クラスは、GPU レンダリングモードを使用するモバイル AIR アプリケーションではサポートされません。
•

モバイルデバイスでは、アクティブにできるカメラは一度に 1 つのみです。

関連項目

Christophe Coenraets：Multi-User Video Tic-Tac-Toe
Mark Doherty: Android Radar app (source)

ユーザーのカメラへの接続
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーのカメラに接続するには、最初に、Camera タイプの変数を作成して新しい Camera インスタンスを作成し、静的な Camera.getCamera() メソッドの値を返すように初期化する必要があります。
次に、新しい Video オブジェクトを作成し、それに Camera オブジェクトを関連付けます。
次に、表示リストに Video オブジェクトを追加します。Camera クラスは DisplayObject クラスを拡張せず、表示リストに直接追加することができないので、手順 2 および 3 を実行する必要があります。カメラでキャプチャしたビデオを表示するには、新しい Video オブジェクトを作成し、attachCamera() メソッドを呼び出します。
次のコードは、上記の 3 つの手順を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

499

カメラの操作

var cam:Camera = Camera.getCamera();var vid:Video = new Video();vid.attachCamera(cam);
addChild(vid);

カメラがインストールされていない場合、アプリケーションでは何も表示されません。
実際には、アプリケーションで追加手順を実行する必要があります。詳しくは、499 ページの「カメラのインストールの確認」および 500 ページの「カメラのアクセス許可の検知」を参照してください。
関連項目

Lee Brimelow：How to access the camera on Android devices

カメラのインストールの確認
Flash Player 9 以降、Adobe AIR 1.0 以降
Camera インスタンスでメソッドまたはプロパティを使用する前に、カメラがインストールされているかどうかを確認します。そのためには、次の 2 つの方法があります。

•

使用可能なカメラ名の配列を含む、静的な Camera.names プロパティを確認します。一度に複数のカメラをインストール
しているユーザーはあまりいないので、この配列には通常は少数のストリングしか含まれていません。次のコードでは、Camera.names プロパティをチェックして、使用可能なカメラの有無を確認する方法を示します。
if (Camera.names.length > 0){
trace("User has at least one camera installed.");var cam:Camera = Camera.getCamera(); // Get default camera.
}
else{
trace("User has no cameras installed.");}•

静的な Camera.getCamera() メソッドの戻り値を確認します。使用可能またはインストールされているカメラがない場合、
このメソッドは null を返します。それ以外の場合は、Camera オブジェクトへの参照を返します。次のコードでは、Camera.getCamera() メソッドをチェックして、使用可能なカメラの有無を確認する方法を示します。
var cam:Camera = Camera.getCamera();if (cam == null){trace("User has no cameras installed.");}else{
trace("User has at least 1 camera installed.");}Camera クラスは DisplayObject クラスを拡張しないので、addChild() メソッドを使用して表示リストに直接追加することはできません。カメラでキャプチャしたビデオを表示するには、新しい Video オブジェクトを作成し、Video インスタンス
で attachCamera() メソッドを呼び出す必要があります。
次のコード例では、カメラがある場合にそれを付加する方法を示します。カメラがない場合、アプリケーションには何も表示されません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

500

カメラの操作

var cam:Camera = Camera.getCamera();if (cam != null){var vid:Video = new Video();vid.attachCamera(cam);
addChild(vid);}

モバイルデバイスのカメラ
モバイルブラウザーの Flash Player ランタイムでは、Camera クラスはサポートされていません。
モバイルデバイスの AIR アプリケーションでは、デバイス上のカメラにアクセスできます。モバイルデバイスでは、前面カメラと背面カメラの両方を使用できますが、特定の時点で表示可能なカメラ出力は 1 つだけです（2 番目のカメラを接続す
ると、最初のカメラは切断されます）。iOS 上では前面カメラの水平方向のミラー処理が行われますが、Android では行われません。

カメラのアクセス許可の検知
Flash Player 9 以降、Adobe AIR 1.0 以降
AIR アプリケーションサンドボックスでは、アプリケーションはユーザーの許可なくカメラにアクセスすることができます。ただし、Android では、アプリケーション記述子に Android の CAMERA 権限を指定する必要があります。

Flash Player がカメラの出力を表示する前に、ユーザーが Flash Player にカメラへのアクセスを明示的に許可する必要があります。attachCamera() メソッドが呼び出されると、Flash Player によって設定ダイアログボックスが表示されます。このダイアログボックスで、ユーザーは Flash Player にカメラとマイクへのアクセスを許可するかどうかを指定します。ユー
ザーが「許可」ボタンをクリックした場合、Flash Player では、カメラの出力がステージの Video インスタンスに表示されます。
「拒否」ボタンをクリックした場合は、Flash Player はカメラに接続できないので、Video オブジェクトは何も表示しません。

Flash Player がカメラへのアクセスを許可されているかどうかを確認するには、次のコードで示すように、カメラの status
イベント（StatusEvent.STATUS）を監視します。
var cam:Camera = Camera.getCamera();if (cam != null){
cam.addEventListener(StatusEvent.STATUS, statusHandler);var vid:Video = new Video();vid.attachCamera(cam);
addChild(vid);}function statusHandler(event:StatusEvent):void{// This event gets dispatched when the user clicks the "Allow" or "Deny"// button in the Flash Player Settings dialog box.
trace(event.code); // "Camera.Muted" or "Camera.Unmuted"}「許可」または「拒否」のいずれかがクリックされると同時に、statusHandler() 関数が呼び出されます。次のいずれかのメ
ソッドを使用し、どのボタンがクリックされたかを検知することができます。

• statusHandler() 関数の event パラメーターには、「Camera.Muted」または「Camera.Unmuted」というストリングを含むコードプロパティがあります。値が「Camera.Muted」であれば、「拒否」ボタンがクリックされているので、Flash Player はカメラにアクセスできません。次に例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

501

カメラの操作function statusHandler(event:StatusEvent):void{switch (event.code){
case "Camera.Muted":
trace("User clicked Deny.");break;
case "Camera.Unmuted":
trace("User clicked Accept.");break;}}• Camera クラスには muted という名前の読み取り専用のプロパティがあり、ユーザーがカメラへのアクセスを拒否したか（true）または許可したか（false）が、「Macromedia Flash Player 設定」の「プライバシー」パネルに表示されます。
次に例を示します。
function statusHandler(event:StatusEvent):void{if (cam.muted){
trace("User clicked Deny.");}else{
trace("User clicked Accept.");}}送出されるステータスイベントを確認すると、カメラへのアクセスの可否を処理するコードを記述し、適切にクリーンアッ
プすることができます。例えば、「拒否」ボタンがクリックされた場合、ビデオチャットに参加するには「許可」ボタンをクリックする必要があるというメッセージを表示することができます。または、表示リストの Video オブジェクトが削除され、システムリソースが解放されていることを確認します。

AIR では、カメラを使用するための許可は動的ではないので、Camera オブジェクトはステータスイベントを送出しません。

カメラビデオ品質の最大化
Flash Player 9 以降、Adobe AIR 1.0 以降
デフォルトでは、Video クラスの新規インスタンスは幅 320 ピクセル、高さ 240 ピクセルです。ビデオ品質を最大化するには、Video オブジェクトと、Camera オブジェクトによって返されるビデオのサイズを一致させる必要があります。
Camera クラスの width および height プロパティを使用して Camera オジェクトの幅と高さを取得し、Video オブジェクトの width および height プロパティを Camera オブジェクトと同じサイズに設定するか、次に示すようにカメラの幅と高さをVideo クラスのコンストラクターメソッドに渡すことができます。
var cam:Camera = Camera.getCamera();if (cam != null){var vid:Video = new Video(cam.width, cam.height);
vid.attachCamera(cam);
addChild(vid);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

502

カメラの操作

getCamera() メソッドは Camera オブジェクトへの参照を返すので（カメラがない場合は null）、ユーザーがカメラへのアクセスを拒否している場合でも、カメラのメソッドとプロパティにアクセスすることができます。これにより、カメラのネイ
ティブの高さと幅を使用してビデオインスタンスのサイズを設定することができます。
var vid:Video;
var cam:Camera = Camera.getCamera();if (cam == null){trace("Unable to locate available cameras.");}else{
trace("Found camera: " + cam.name);
cam.addEventListener(StatusEvent.STATUS, statusHandler);
vid = new Video();vid.attachCamera(cam);}function statusHandler(event:StatusEvent):void{if (cam.muted){
trace("Unable to connect to active camera.");}else{// Resize Video object to match camera settings and// add the video to the display list.
vid.width = cam.width;
vid.height = cam.height;
addChild(vid);}// Remove the status event listener.
cam.removeEventListener(StatusEvent.STATUS, statusHandler);}

フルスクリーンモードについて詳しくは、156 ページの「Stage プロパティの設定」のフルスクリーンモードに関する節を参照してください。

カメラステータスの監視Flash Player 9 以降、Adobe AIR 1.0 以降
カメラクラスには、Camera オブジェクトの現在のステータスを監視するためのプロパティがいくつかあります。例えば次のコードでは、表示リストで Timer オブジェクトとテキストフィールドインスタンスを使用して、カメラのプロパティをいくつか表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

503

カメラの操作

var vid:Video;
var cam:Camera = Camera.getCamera();var tf:TextField = new TextField();
tf.x = 300;
tf.autoSize = TextFieldAutoSize.LEFT;
addChild(tf);if (cam != null){
cam.addEventListener(StatusEvent.STATUS, statusHandler);
vid = new Video();vid.attachCamera(cam);}function statusHandler(event:StatusEvent):void{if (!cam.muted){
vid.width = cam.width;
vid.height = cam.height;
addChild(vid);t.start();}cam.removeEventListener(StatusEvent.STATUS, statusHandler);}var t:Timer = new Timer(100);t.addEventListener(TimerEvent.TIMER, timerHandler);function timerHandler(event:TimerEvent):void{
tf.text = "";tf.appendText("activityLevel: " + cam.activityLevel + "\n");tf.appendText("bandwidth: " + cam.bandwidth + "\n");tf.appendText("currentFPS: " + cam.currentFPS + "\n");tf.appendText("fps: " + cam.fps + "\n");tf.appendText("keyFrameInterval: " + cam.keyFrameInterval + "\n");tf.appendText("loopback: " + cam.loopback + "\n");tf.appendText("motionLevel: " + cam.motionLevel + "\n");tf.appendText("motionTimeout: " + cam.motionTimeout + "\n");tf.appendText("quality: " + cam.quality + "\n");}Timer オブジェクトの timer イベントは 10 分の 1 秒、つまり 100 ミリ秒ごとに送出され、timerHandler() 関数は表示リストのテキストフィールドを更新します。

最終更新日 2015/10/14

504

第 27 章：電子著作権管理の使用
Flash Player 10.1 以降、Adobe AIR 1.5 以降
Adobe® Access™ は、コンテンツ保護ソリューションです。コンテンツ所有者、販売店、広告主は、Flash Access によって有料コンテンツへのシームレスなアクセスを提供することにより、新たな収入源を実現することができます。発行者は、

Adobe Access を使用してコンテンツの暗号化、ポリシーの作成、ライセンスの発行を行います。Adobe Flash Player とAdobe AIR には、Adobe Access モジュールである DRM ライブラリが組み込まれています。このモジュールにより、ランタイムは Adobe Access ライセンスサーバーと通信し、保護されたコンテンツを再生できます。ランタイムは、このようにして、Adobe Access によって保護され、Flash Media Server によって配布されるコンテンツのライフサイクルを完了します。
コンテンツプロバイダーは、Adobe Access を使用して、無料コンテンツと有料コンテンツの両方を提供できます。例えば、ユーザーは広告のないテレビプログラムを視聴したいと考えているとします。この場合、ユーザーはコンテンツ発行者に登録して支払いを行います。その後、ユーザーは広告のないプログラムにアクセスして視聴するために、ユーザー資格情報を入力できるようになります。
別の例では、ユーザーは移動中でインターネットにアクセスできないときに、コンテンツをオフラインで表示したいと考えているとします。このオフラインワークフローは、AIR アプリケーションでサポートされています。ユーザーは、発行者に登録してコンテンツの料金を支払うと、コンテンツおよび関連する AIR アプリケーションにアクセスし、発行者の Web サ
イトからダウンロードすることができます。ユーザーは、AIR アプリケーションを使用して、許可された期間中はコンテン
ツをオフラインで表示できます。コンテンツは、ドメインを使用して同一デバイスグループ内の他のデバイスと共有することもできます（3.0 の新機能）。

Adobe Access では匿名アクセスもサポートされています。匿名アクセスでは、ユーザー認証は必要ありません。例えば、発行者は匿名アクセスを使用して広告支援コンテンツを配布することができます。また、発行者は匿名アクセスを使用して、指定した日数に限り現在のコンテンツに自由にアクセスできる権利を許可することもできます。コンテンツプロバイダーは、コンテンツに対して必要なプレイヤーの種類とバージョンを指定し、制限することもできます。
保護されたコンテンツをユーザーが Flash Player または Adober AIR で再生しようとするときは、アプリケーションは
DRM API を呼び出す必要があります。DRM API は、保護されたコンテンツを再生するワークフローを開始します。ラン
タイムは、Adobe Access モジュールを通じて、ライセンスサーバーにアクセスします。ライセンスサーバーは必要に応じてユーザーを認証し、保護されたコンテンツの再生を許可するライセンスを発行します。ランタイムはライセンスを受け取り、再生するコンテンツの暗号解読を行います。
ここでは、アプリケーションで、Adobe Access によって保護されたコンテンツの再生を有効にする方法を説明します。コンテンツを暗号化する方法や、Adobe Access を使用してポリシーを維持する方法を理解する必要はありません。ただし、Adobe Access ライセンスサーバーと通信してユーザーを認証し、ライセンスを取得することが前提です。また、Adobe
Access によって保護されたコンテンツを再生するようにアプリケーションを設計することも前提です。
ポリシーの作成を含む Adobe Access の概要については、Adobe Access に付属するドキュメントを参照してください。
関連項目

flash.net.drm パッケージ
flash.net.NetConnection
flash.net.NetStream

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

505

電子著作権管理の使用保護されたコンテンツのワークフローについて
Flash Player 10.1 以降、Adobe AIR 2.0 以降
重要：Flash Player 11.5 以降は、Adobe Access モジュールと統合されているので、更新手順（SystemUpdater.update(SystemUpdaterType.DRM) の呼び出し）を行う必要はありません。この更新手順が不要となるのは、次のブラウザーとプラットフォームです。

• Flash Player 11.5 ActiveX コントロール（Windows 8 上の Internet Explorer を除くすべてのプラットフォーム）。
Intel プロセッサ• Flash Player 11.5 プラグイン（すべてのブラウザー）。
• Adobe AIR（デスクトップおよびモバイル）。
つまり、次の場合は、更新手順を行う必要があります。

• Windows 8 上の Internet Explorer。Intel プロセッサ• Flash Player 11.4 以前。ただし、Google Chrome 22 以降（すべてのプラットフォーム）および Google Chrome 21 以降（Windows）の場合は更新手順を行う必要はありません。
注意：Flash Player 11.5 以降を備えたシステムでも、SystemUpdater.update（SystemUpdaterType.DRM） を安全に呼び出すことはできますが、何もダウンロードされません。
次の高レベルなワークフローは、保護されたコンテンツをアプリケーションが取得して再生する方法を示しています。ワー
クフローでは、Adobe Access によって保護されたコンテンツを再生するようにアプリケーションが設計されていることが前提です。

1 コンテンツメタデータを取得します。
2 必要に応じて、Flash Player を更新します。
3 ライセンスをローカルに利用できるかどうか確認します。利用できる場合は、読み込んで手順 7 に移動します。利用できない場合は、手順 4 に移動します。

4 認証が必要かどうかを確認します。必要でない場合は、手順 7 に移動します。
5 認証が必要な場合は、ユーザーから認証資格情報を取得し、ライセンスサーバーに渡します。
6 ドメイン登録が必要な場合は、ドメインに参加します（AIR 3.0 以降）。
7 認証に成功したら、サーバーからライセンスをダウンロードします。
8 コンテンツを再生します。
エラーが発生せず、ユーザーがコンテンツの表示を許可された場合は、NetStream オブジェクトが DRMStatusEvent オブジェクトを送出します。その後、アプリケーションが再生を開始します。DRMStatusEvent オブジェクトは、関連する証明書の情報を保持し、それによってユーザーのポリシーと権限を識別します。例えば、コンテンツをオフラインで利用できるようにするかどうかや、ライセンスの有効期限に関する情報を保持します。アプリケーションは、このデータを使用してユーザーにポリシーのステータスを通知します。例えば、アプリケーションは、コンテンツをユーザーが表示できる残りの日数をステータスバーに表示できます。
ユーザーにオフラインアクセスが許可される場合、証明書がキャッシュされ、暗号化されたコンテンツがユーザーのマシンにダウンロードされます。コンテンツは、ライセンスのキャッシュ期間として定義される間はアクセス可能になります。イ
ベントの detail プロパティには、「DRM.voucherObtained」が含まれます。アプリケーションは、オフラインでコンテンツを使用できるようにするために、コンテンツをローカルに格納する場所を決定します。DRMManager クラスを使用して証明書を事前に読み込むこともできます。
注意：証明書のキャッシュおよび事前読み込みは、AIR および Flash Player でサポートされています。ただし、暗号化されたコンテンツのダウンロードおよび保存は、AIR でのみサポートされています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド506

電子著作権管理の使用

エラーイベントを明示的に処理する責務はアプリケーション側にあります。このイベントには、ユーザーが有効な資格情報を入力した場合が含まれますが、暗号化されたコンテンツを保護する証明書はコンテンツに対するアクセスを制限します。
例えば、認証されたユーザーは、権利に対して支払いが済んでいない場合、コンテンツにアクセスすることはできません。
また、同じ発行者による 2 人の登録メンバーのうち 1 人しか支払いを済ませていないコンテンツを、その 2 人が共有しようとするような場合も、このイベントが発生します。アプリケーションがユーザーに対してエラーを通知し、代替手段を提示する必要があります。一般的な代替手段として、表示する権利の登録およびその権利に対する支払いの方法について説明することが挙げられます。

詳細な API ワークフロー
Flash Player 10.1 以降、AIR 2.0 以降
このワークフローでは、保護されたコンテンツのワークフローをより詳細に示します。このワークフローは、Adobe

Access によって保護されたコンテンツを再生するために使用される特定の API を示しています。
1 URLLoader オブジェクトを使用して、保護されたコンテンツのメタデータファイルのバイトを読み込みます。このオブジェクトを metadata_bytes などの変数に設定します。

Adobe Access によって制御されるすべてのコンテンツは、Adobe Access メタデータを持ちます。コンテンツがパッ
ケージ化されると、このメタデータは別のメタデータファイル（.metadata）として、コンテンツと共に保存できるようになります。詳しくは、Adobe Access のマニュアルを参照してください。

2 DRMContentData インスタンスを作成します。このコードを次の try-catch ブロックに配置します。
new DRMContentData(metadata_bytes)
ここで、metadata_bytes は手順 1 で取得した URLLoader オブジェクトです。

3 （Flash Player のみ）ランタイムは、Adobe Access モジュールをチェックします。見つからない場合は、

DRMErrorEvent エラーコード 3344 または DRMErrorEvent エラーコード 3343 の IllegalOperationError がスローされます。
このエラーを処理するには、SystemUpdater API を使用して Adobe Access モジュールをダウンロードします。このモジュールのダウンロード後、SystemUpdater オブジェクトは COMPLETE イベントを送出します。これには、このイベントが送出されたときに手順 2 に戻る、このイベントのイベントリスナーが含まれます。これらの手順について、次のコードで示します。
flash.system.SystemUpdater.addEventListener(Event.COMPLETE, updateCompleteHandler);
flash.system.SystemUpdater.update(flash.system.SystemUpdaterType.DRM)
private function updateCompleteHandler (event:Event):void {/*redo step 2*/
drmContentData = new DRMContentData(metadata_bytes);}

プレーヤーそのものを更新する必要がある場合は、ステータスイベントが送出されます。このイベントの処理について詳
しくは、520 ページの「更新イベントの監視」を参照してください。
注意：AIR アプリケーションでは、AIR インストーラーは Adobe Access モジュールの更新および必要なランタイム更新を処理します。

4 DRMManager オブジェクトから送出される DRMStatusEvent および DRMErrorEvent を監視するリスナーを次のように作成します。
DRMManager.addEventListener(DRMStatusEvent.DRM_STATUS, onDRMStatus);
DRMManager.addEventListener(DRMErrorEvent.DRM_ERROR, onDRMError);

DRMStatusEvent リスナーで、証明書が有効である（null でない）ことを確認します。DRMErrorEvent リスナーで、DRMErrorEvents を処理します。513 ページの「DRMStatusEvent クラスの使用」および 517 ページの「DRMErrorEvent クラスの使用」を参照してください。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

507

電子著作権管理の使用

5 コンテンツの再生に必要な証明書（ライセンス）を読み込みます。
最初に、ローカルに保存されたライセンスを読み込んで、コンテンツの再生を試みます。
DRMManager.loadvoucher(drmContentData, LoadVoucherSetting.LOCAL_ONLY)

読み込みが完了すると、DRMManager オブジェクトは DRMStatusEvent.DRM_Status を送出します。

6 DRMVoucher オブジェクトが null でない場合、証明書は有効です。手順 13 に進みます。
7 DRMVoucher オブジェクトが null の場合は、このコンテンツに対してポリシーで要求されている認証方法を確認します。DRMContentData.authenticationMethod プロパティを使用します。

8 認証方法が ANONYMOUS の場合は、手順 13 に進みます。
9 認証方法が USERNAME_AND_PASSWORD の場合、アプリケーションはユーザーが資格情報を入力するためのメカニズ
ムを提供する必要があります。その資格情報をライセンスサーバーに渡してユーザーを認証します。
DRMManager.authenticate(metadata.serverURL, metadata.domain, username, password)

認証に失敗した場合、DRMManager は DRMAuthenticationErrorEvent を送出し、認証に成功した場合はDRMAuthenticationCompleteEvent を送出します。これらのイベントのリスナーを作成します。

10 認証方法が UNKNOWN の場合、カスタム認証方法を使用する必要があります。この場合、コンテンツプロバイダーは、ActionScript 3.0 API を使用せずに、帯域外で認証が行われるよう手配しておく必要があります。カスタム認証手順では、DRMManager.setAuthenticationToken() メソッドに渡すことができる認証トークンを生成する必要があります。

11 認証が失敗した場合、アプリケーションは手順 9 に戻る必要があります。アプリケーションに、認証の失敗が繰り返されたときにそれを処理し、制限するメカニズムがあることを確認します。例えば、3 回の試行後に、認証に失敗してコンテンツを表示できないことを示すメッセージをユーザーに表示します。

12 ユーザーに資格情報の入力を求めるのではなく、保存されたトークンを使用するには、
DRMManager.setAuthenticationToken() メソッドを使用してトークンを設定します。次に、ライセンスサーバーからライ
センスをダウンロードし、手順 8 のようにコンテンツを再生します。

13 （オプション）認証に成功した場合は、認証トークンをキャプチャできます。これは、メモリにキャッシュされるバイト配列です。このトークンは、DRMAuthenticationCompleteEvent.token プロパティを使用して取得します。認証トーク
ンを保存および使用し、ユーザーが繰り返しこのコンテンツの資格情報を入力しなくても済むようにすることができます。ライセンスサーバーは、認証トークンの有効期限を決定します。

14 認証に成功した場合は、次のようにライセンスサーバーからライセンスをダウンロードします。
DRMManager.loadvoucher(drmContentData, LoadVoucherSetting.FORCE_REFRESH)

読み込みが完了すると、DRMManager オブジェクトは DRMStatusEvent.DRM_STATUS を送出します。このイベントを監視し、これが送出されたら、コンテンツを再生できます。

15 NetStream オブジェクトを作成し、その play() メソッドを呼び出して、ビデオを再生します。
stream = new NetStream(connection);stream.addEventListener(DRMStatusEvent.DRM _STATUS, drmStatusHandler);stream.addEventListener(DRMErrorEvent.DRM_ERROR, drmErrorHandler);stream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);stream.client = new CustomClient();
video.attachNetStream(stream);
stream.play(videoURL);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

508

電子著作権管理の使用

DRMContentData およびセッションオブジェクト
DRMContentData が作成されると、Flash Player DRM モジュールを参照するセッションオブジェクトとして使用されます。
この DRMContentData を受信するすべての DRMManager API は、特定の DRM モジュールを使用します。ただし、DRMContentData を使用しない DRMManager API が 2 つあります。異なる規則を以下に示します。

1 authenticate()
2 setAuthenticationToken()
DRMContentData と関連がないので、これらの DRMManager API を呼び出すと、ディスクにある最新の DRM モジュールが使用されます。これは、アプリケーションの DRM ワークフローの途中で DRM モジュールが更新される場合に問題となることがあります。次のシナリオについて考えます。

1 アプリケーションが DRMContentData オブジェクト contentData1 を作成します。このオブジェクトは、DRM モジュールとして AdobeCP1 を使用します。

2 アプリケーションが DRMManager.authenticate(contentData1.serverURL,...) メソッドを呼び出します。
3 アプリケーションが DRMManager.loadVoucher(contentData1, ...) メソッドを呼び出します。
アプリケーションが手順 2 に到達するまでに DRM モジュールの更新が発生した場合、DRMManager.authenticate() メソッ
ドは、最終的に DRM モジュールとして AdobeCP2 を使用して認証します。手順 3 の loadVoucher() メソッドは、DRM モ
ジュールとしてまだ AdobeCP1 を使用しているので失敗します。他のアプリケーションが DRM モジュールの更新を呼び出すことで、更新が発生する可能性があります。このようなシナリオを回避するには、アプリケーション起動時に DRM モ
ジュールの更新を呼び出します。

DRM 関連イベント
保護されたコンテンツの再生をアプリケーションが試みたときに、ランタイムは次に示す多数のイベントを送出します。

• DRMDeviceGroupErrorEvent（AIR のみ）、DRMManager によって送出• DRMAuthenticateEvent（AIR のみ）、NetStream によって送出• DRMAuthenticationCompleteEvent、DRMManager によって送出• DRMAuthenticationErrorEvent、DRMManager によって送出• DRMErrorEvent、NetStream および DRMManager によって送出• DRMStatusEvent、NetStream および DRMManager によって送出• StatusEvent• NetStatusEvent. 520 ページの「更新イベントの監視」を参照してください。
Adobe Access によって保護されるコンテンツをサポートするために、DRM イベントを処理するイベントリスナーを追加します。

オフライン再生用の証明書の事前読み込み
Adobe AIR 1.5 およびそれ以降
Adobe Access によって保護されているコンテンツの再生に必要な証明書（ライセンス）を事前に読み込むことができます。
証明書を事前に読み込むことにより、ユーザーは、アクティブなインターネット接続の有無にかかわらず、コンテンツを表示できるようになります（ただし、事前読み込みのプロセスではインターネット接続が必要です）。証明書を事前に読み込むには、NetStream クラスの preloadEmbeddedMetadata() メソッドと、DRMManager クラスを使用します。AIR 2.0 以降で最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド509

電子著作権管理の使用

は、DRMContentData オブジェクトを使用して証明書を事前に直接読み込むことができます。このテクニックがお勧めなのは、コンテンツとは無関係に DRMContentData オブジェクトを更新できるためです（preloadEmbeddedData() メソッド
はコンテンツから DRMContentData をフェッチします）。

DRMContentData の使用
Adobe AIR 2.0 およびそれ以降
次の手順は、DRMContentData オブジェクトを使用して、保護されたメディアファイルに対して証明書を事前に読み込むためのワークフローを示しています。

1 パッケージ化されたコンテンツのバイナリメタデータを取得します。Adobe Access Java Reference Packager を使用している場合、このメタデータファイルは自動的に .metadata 拡張子を使用して生成されます。例えば、URLLoader クラスを使用してこのメタデータをダウンロードできます。

2 DRMContentData オブジェクトを作成し、メタデータをコンストラクター関数に渡します。
var drmData:DRMContentData = new DRMContentData( metadata );3 以降の手順は、505 ページの「保護されたコンテンツのワークフローについて」で説明しているワークフローと同じです。

preloadEmbeddedMetadata() の使用
Adobe AIR 1.5 およびそれ以降
次の手順では、preloadEmbeddedMetadata() を使用して、DRM で保護されたメディアファイルの証明書を事前に読み込むためのワークフローを示します。

1 メディアファイルをダウンロードして保存します（DRM メタデータは、ローカルに保存されたファイルからのみ事前に読み込むことができます）。

2 NetConnection オブジェクトと NetStream オブジェクトを作成して、NetStream クライアントオブジェクトの
onDRMContentData() コールバック関数および onPlayStatus() コールバック関数を実装します。

3 NetStreamPlayOptions オブジェクトを作成し、stream プロパティをローカルのメディアファイルの URL に設定します。

4 NetStream preloadEmbeddedMetadata() を呼び出して、解析するメディアファイルを識別する NetStreamPlayOptions
オブジェクトを渡します。

5 メディアファイルに DRM メタデータが含まれている場合は、onDRMContentData() コールバック関数が呼び出されます。メタデータは、この関数に DRMContentData オブジェクトとして渡されます。

6 DRMManager loadVoucher() メソッドを使用し、DRMContentData オブジェクトを使用して証明書を取得します。
DRMContentData オブジェクトの authenticationMethod プロパティの値がflash.net.drm.AuthenticationMethod.USERNAME_AND_PASSWORD の場合は、証明書を読み込む前に Media Rights
Server でユーザーを認証する必要があります。DRMContentData オブジェクトの serverURL プロパティおよび domain
プロパティが、ユーザー情報と共に DRMManager authenticate() メソッドに渡されます。

7 ファイルの解析が完了すると、onPlayStatus() コールバック関数が呼び出されます。onDRMContentData() 関数が呼び出
されていない場合、そのファイルには証明書の取得に必要なメタデータが含まれていません。また、この関数が呼び出されていない場合、Adobe Access がこのファイルを保護していない可能性があります。
例えば、次の AIR 用のコードは、ローカルのメディアファイルの 証明書を事前に読み込む方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

510

電子著作権管理の使用

package{import flash.display.Sprite;
import flash.events.DRMAuthenticationCompleteEvent;import flash.events.DRMAuthenticationErrorEvent;import flash.events.DRMErrorEvent;import flash.ev ents.DRMStatusEvent;import flash.events.NetStatusEvent;import flash.net.NetConnection;
import flash.net.NetStream;
import flash.net.NetStreamPlayOptions;
import flash.net.drm.AuthenticationMethod;
import flash.net.drm.DRMContentData;
import flash.net.drm.DRMManager;
import flash.net.drm.LoadVoucherSetting;public class DRMPreloader extends Sprite{
private var videoURL:String = "app-storage:/video.flv";
private var userName:String = "user";private var password:String = "password";
private var preloadConnection:NetConnection;
private var preloadStream:NetStream;
private var drmManager:DRMManager = DRMManager.getDRMManager();
private var drmContentData:DRMContentData;public function DRMPreloader():void {drmManager.addEventListener(
DRMAuthenticationCompleteEvent.AUTHENTICATION_COMPLETE,
onAuthenticationComplete);
drmManager.addEventListener(DRMAuthenticationErrorEvent.AUTHENTICATION_ERROR,
onAuthenticationError);drmManager.addEventListener(DRMStatusEvent.DRM_STATUS, onDRMStatus);
drmManager.addEventListener(DRMErrorEvent.DRM_ERROR, onDRMError);preloadConnection = new NetConnection();preloadConnection.addEventListener(NetStatusEvent.NET_STATUS, onConnect);
preloadConnection.connect(null);}
private function onConnect( event:NetStatusEvent ):void{
preloadMetadata();}private function preloadMetadata():void{
preloadStream = new NetStream( preloadConnection );preloadStream.client = this;var options:NetStreamPlayOptions = new NetStreamPlayOptions();
options.streamName = videoURL;
preloadStream.preloadEmbeddedData( options );}public function onDRMContentData( drmMetadata:DRMContentData ):void{
drmContentData = drmMetadata;
if ( drmMetadata.authenticationMethod == AuthenticationMethod.USERNAME_AND_PASSWORD ){authenticateUser();}else{
getVoucher();}}
private function getVoucher():void

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

511

電子著作権管理の使用{
drmManager.loadVoucher( drmContentData, LoadVoucherSetting.ALLOW_SERVER );}private function authenticateUser():void{
drmManager.authenticate( drmContentData.serverURL, drmContentData.domain, userName, password );}private function onAuthenticationError( event:DRMAuthenticationErrorEvent ):void{
trace( "Authentication error: " + event.errorID + ", " + event.subErrorID );}private function onAuthenticationComplete( event:DRMAuthenticationCompleteEvent ):void{
trace( "Authenticated to: " + event.serverURL + ", domain: " + event.domain );getVoucher();}
private function onDRMStatus( event:DRMStatusEvent ):void{
trace( "DRM Status: " + event.detail);
trace("--Voucher allows offline playback = " + event.isAvailableOffline );trace("--Voucher already cached= " + event.isLocal );trace("--Voucher required authentication = " + !event.isAnonymous );}private function onDRMError( event:DRMErrorEvent ):void{
trace( "DRM error event: " + event.errorID + ", " + event.subErrorID + ", " + event.text );}public function onPlayStatus( info:Object ):void{
preloadStream.close();}}}NetStream クラスの DRM 関連のメンバーおよびイベント
Flash Player 10.1 以降、Adobe AIR 1.0 以降
NetStream クラスは、Flash Player または AIR アプリケーションと Flash Media Server またはローカルファイルシステムの間の接続の一方向のストリーミングを提供します（NetStream クラスはこれを発展させた形のダウンロードもサポートします）。NetStream オブジェクトは、NetConnection オブジェクト内のチャンネルです。NetStream クラスは次に示す 4
つの DRM 関連イベントを送出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

512

電子著作権管理の使用

イベント

説明

drmAuthenticate

DRMAuthenticateEvent クラスで定義されています。このイベントが送出されるのは、NetStream オブジェクト（AIR のみ）

が、再生の前に認証のためのユーザー資格情報を必要とする、保護されたコンテンツを再生しようとしたときです。
このイベントのプロパティには、ユーザー情報の取得および設定において使用できる header、usernamePrompt、

passwordPrompt および urlPrompt プロパティが含まれます。このイベントは、NetStream オブジェクトが有効なユーザー情報を受け取るまで繰り返し発生します。

drmError

DRMErrorEvent クラスに定義され、NetStream オブジェクトが、保護されたコンテンツの再生を試み、DRM 関連
エラーが発生したときに送出されます。例えば、ユーザー承認に失敗したときに DRM エラーイベントオブジェクトが送出されます。このエラーは、ユーザーがコンテンツを表示する権利を購入していない場合に発生します。また、コンテンツプロバイダーがアプリケーションの表示をサポートしていない場合にも発生します。

drmStatus

DRMStatusEvent クラスで定義されます。このイベントが送出されるのは、保護されたコンテンツが再生を開始する（ユーザーが認証され、コンテンツの再生を許可される）ときです。DRMStatusEvent オブジェクトには、証明書に関連する情報が含まれています。証明書情報には、コンテンツがオフラインで利用できるか、証明書の期限が切れたときにコンテンツを表示できなくなるかについての情報が含まれます。

statusevents.StatusEvent に定義され、アプリケーションが NetStream.play() メソッドを呼び出して、保護されたコンテンツの再生を試みたときにみ送出されます。status コードプロパティの値は、「DRM.encryptedFLV」です。

NetStream クラスには、AIR のみで使用する、次の DRM 関連メソッドが含まれます。
メソッド

resetDRMVouchers()

説明
ローカルにキャッシュされたすべての電子著作権管理（DRM）証明書データを削除します。ユーザーが暗号化コンテンツにアクセスできるようにするには、アプリケーションで証明書をもう一度ダウンロードする必要があります。
例えば、次のコードではすべての証明書をキャッシュから削除します。

NetStream.resetDRMVouchers();
setDRMAuthenticationCredentials()

ユーザー名、パスワード、認証タイプで構成される認証情報のセットを認証のために NetStream オブ
ジェクトに渡します。有効な暗号化タイプは、「drm」と「proxy」です。「drm」認証タイプの場合、提供された資格情報は Adobe Access に対して認証されます。
「proxy」認証タイプを使用して、情報はプロキシサーバーに対して認証され、プロキシサーバーによって要求される資格情報に一致する必要があります。例えば、アプリケーションがプロキシサーバーに対して認証を行ってからユーザーがインターネットにアクセスできることを、企業がアプリケーションの要件として指定できます。proxy オプ
ションによってこのような認証タイプを実現できます。匿名認証が使用される場合を除き、プロキシ認証の後、証明書を取得してコンテンツを再生するためにユーザーは引き続き Adobe Access に対する認証を行う必要があります。2 回目は setDRMAuthenticationCredentials() を「drm」オプションと共に使用して、Adobe Access に対する認証を行うことができます。

preloadEmbeddedMetadata()

ローカルのメディアファイルを解析して埋め込みメタデータを探します。DRM 関連のメタデータが見つかると、AIR によって onDRMContentData() コールバック関数が呼び出されます。

さらに、AIR では、NetStream オブジェクトは onDRMContentData() コールバック関数および onPlayStatus() コールバック
関数を、preloadEmbeddedMetaData() メソッドの呼び出しの結果として呼び出します。onDRMContentData() 関数は、メディアファイル内で DRM メタデータが見つかった場合に呼び出されます。onPlayStatus() 関数は、ファイルが解析されたときに呼び出されます。onDRMContentData() 関数と onPlayStatus() 関数は、NetStream インスタンスに割り当てられた client
オブジェクトで定義されている必要があります。同じ NetStream オブジェクトを使用して証明書の事前読み込みとコンテンツの再生を実行する場合は、再生を開始する前に、onPlayStatus() 呼び出しが preloadEmbeddedMetaData() によって生成されるのを待ちます。
次の AIR 用コードでは、ユーザー名（「administrator」）、パスワード（「password」）および「drm」認証タイプがユー
ザー認証に対して設定されます。setDRMAuthenticationCredentials() メソッドは、コンテンツプロバイダーにとって既知で受け入れられる情報に一致する資格情報を提供する必要があります。これらの資格情報は、ユーザーがコンテンツを表示できるようにするのと同じユーザー資格情報です。ビデオを再生するためのコード、およびビデオのストリームに対する正常な接続が確立していることを確認するためのコードは、ここには含まれていません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

513

電子著作権管理の使用

var connection:NetConnection = new NetConnection();connection.connect(null);var videoStream:NetStream = new NetStream(connection);videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE,
drmAuthenticateEventHandler)
private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void{
videoStream.setDRMAuthenticationCredentials("administrator", "password", "drm");}

DRMStatusEvent クラスの使用
Flash Player 10.1、Adobe AIR 1.0 以降
NetStream オブジェクトは、Adobe Access によって保護されているコンテンツが正常に再生を開始すると、DRMStatusEvent オブジェクトを送出します（正常な再生は、ライセンスが確認され、ユーザーが認証されてコンテンツの表示を許可されたことを示します）。DRMStatusEvent は、匿名ユーザーがアクセスを許可されている場合は、それらのユーザーに対しても送出されます。ライセンスは、認証を必要としない匿名ユーザーがコンテンツを再生するためのアクセスを許可されているかどうかを検証するためにも確認されます。匿名ユーザーは、様々な理由でアクセスを拒否されることがあります。例えば、匿名ユーザーは、コンテンツの有効期限が切れているとコンテンツにアクセスできません。

DRMStatusEvent オブジェクトには、ライセンスに関連する情報が含まれています。これには、ライセンスがオフラインで利用できるか、証明書の期限が切れたときにコンテンツを表示できなくなるかについての情報が含まれます。アプリケー
ションは、このデータを使用してユーザーのポリシーのステータスと権限を伝えることができます。

DRMStatusEvent プロパティ
Flash Player 10.1、Adobe AIR 1.0 以降
DRMStatusEvent クラスには、次のプロパティが含まれます。一部のプロパティは、1.0 以降のバージョンの AIR で利用できるようになったものです。詳細なバージョン情報は、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』を参照してください。

Flash Player 10.1 でサポートされていないプロパティについては、DRMVoucher クラスは Flash Player 用に類似したプロ
パティを提供します。
プロパティ

説明

contentData

コンテンツに埋め込まれた DRM メタデータを含む DRMContentData オブジェクト。

detail（AIR のみ）

status イベントのコンテキストを説明するストリング。DRM 1.0 では、有効な値は DRM.voucherObtained だけです。

isAnonymous（AIR のみ）

Adobe Access で保護されたコンテンツがユーザーによる認証情報の提供を必要としないで使用できるか（true）、使用できないか（false）を示します。値 false は、コンテンツプロバイダーに対して既知で予期されているものに一致するユーザー名とパスワードをユーザーが提供する必要があることを示します。

isAvailableOffline（AIR の

Adobe Access で保護されたコンテンツをオフラインで使用可能にできるか（true）、使用可能にできないかみ）（false）を示します。電子的に保護されたコンテンツをオフラインで使用可能にするには、その証明書をユーザーのローカルマシンにキャッシュする必要があります。

isLocal

コンテンツの再生に必要な証明書がローカルにキャッシュされているかどうかを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

514

電子著作権管理の使用

プロパティ

説明

offlineLeasePeriod（AIRコンテンツをオフラインで表示できる残りの日数。

のみ）

policies（AIR のみ）

カスタム DRM プロパティを含めることができるカスタムオブジェクト。

voucher

DRMVoucher。

voucherEndDate（AIR の証明書が期限切れになり、コンテンツを表示できなくなる絶対的な日付。

み）DRMStatusEvent ハンドラーの作成
Flash Player 10.1、Adobe AIR 1.0 以降
次の例では、イベントの発生元となった NetStream オブジェクトに対する DRM コンテンツのステータス情報を出力する
イベントハンドラーを作成します。保護されたコンテンツをポイントする NetStream オブジェクトにこのイベントハンド
ラーを追加します。
function drmStatusEventHandler(event:DRMStatusEvent):void{
trace(event);}
function drmStatusEventHandler(event:DRMStatusEvent):void{
trace(event);}

DRMAuthenticateEvent クラスの使用
Adobe AIR 1.0 およびそれ以降再生前に認証のためのユーザー資格情報を必要とする、保護されたコンテンツを NetStream オブジェクトが再生しようとしたときに、DRMAuthenticationEvent オブジェクトが送出されます。

DRMAuthenticateEvent ハンドラーは、必要な情報（ユーザー名、パスワード、タイプ）を収集し、その値を検証のために NetStream.setDRMAuthenticationCredentials() メソッドに渡す必要があります。各 AIR アプリケーションは、ユーザー情報を取得するためのメカニズムを提供する必要があります。例えば、アプリケーションは、ユーザー名とパスワードの値を入力するための簡単なユーザーインターフェイスをユーザーに提供できます。また、ユーザーが認証の試行を繰り返したときに、それを処理し、制限するメカニズムも提供できます。

DRMAuthenticateEvent プロパティ
Adobe AIR 1.0 およびそれ以降
DRMAuthenticateEvent クラスには、次のプロパティが含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

515

電子著作権管理の使用

プロパティ

authenticationType

説明提供された情報が Adobe Access（「drm」）に対する認証のためのものか、プロキシサーバー（「proxy」）に対する認証のためのものかを示します。例えば、「proxy」オプションでは、アプリケーションが必要に応じてプロキシ
サーバーに対して認証を行ってからユーザーがインターネットにアクセスできるように指定できます。匿名認証が使用される場合を除き、プロキシ認証の後、証明書を取得してコンテンツを再生するためにユーザーは引き続きAdobe Access に対する認証を行う必要があります。2 回目に setDRMAuthenticationcredentials() を使用するときに「drm」オプションを指定すると、Adobe Access に対して認証することができます。
header

サーバーによって提供される暗号化されたコンテンツファイルヘッダー。暗号化されたコンテンツのコンテキスト
に関する情報が含まれます。
アプリケーションでユーザー名とパスワードのダイアログボックスを構成するために、このヘッダーストリングをFlash アプリケーションに渡すことができます。ヘッダーストリングはダイアログボックスの説明として使用できます。例えば、「ユーザー名とパスワードを入力してください」というヘッダーにすることができます。

netstream

このイベントを開始した NetStream オブジェクト。

passwordPrompt

サーバーによって提供される、パスワード情報に対するプロンプト。このストリングには、必要なパスワードの種類についての説明を含めることができます。

urlPrompt

サーバーによって提供される、URL ストリングに対するプロンプト。このストリングは、ユーザー名とパスワードが送信される場所を指定できます。

usernamePrompt

サーバーによって提供される、ユーザー名情報に対するプロンプト。このストリングには、必要なユーザー名の種類についての説明を含めることができます。例えば、コンテンツプロバイダーがユーザー名を電子メールアドレスにするよう要求することができます。

前述のストリングは FMRMS サーバーのみで提示されます。Adobe Access サーバーではこれらのストリングは使用されません。

DRMAuthenticateEvent ハンドラーの作成
Adobe AIR 1.0 およびそれ以降
次の例では、イベントの発生元となった NetStream オブジェクトにハードコードされた認証情報のセットを渡すイベント
ハンドラーを作成します（ビデオを再生するためのコード、およびビデオのストリームに対する正常な接続が確立していることを確認するためのコードは、ここには含まれていません）。
var connection:NetConnection = new NetConnection();connection.connect(null);var videoStream:NetStream = new NetStream(connection);videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE,
drmAuthenticateEventHandler)
private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void{
videoStream.setDRMAuthenticationCredentials("administrator", "password", "drm");}

ユーザー情報を取得するためのインターフェイスの作成
Adobe AIR 1.0 およびそれ以降保護されたコンテンツがユーザー認証を必要とする場合、通常、AIR アプリケーションはユーザーインターフェイスを経由してユーザーの認証情報を取得する必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

516

電子著作権管理の使用

次に、Flex でのユーザー情報を取得するための単純なユーザーインターフェイスの例を示します。これは、2 つの

TextInput オブジェクト（ユーザー名情報用のオブジェクトとパスワード情報用のオブジェクト）を含んでいる 1 つのパネ
ルオブジェクトで構成されています。パネルには、credentials() メソッドを起動するボタンも 1 つ含まれています。
<mx:Panel x="236.5" y="113" width="325" height="204" layout="absolute" title="Login"><mx:TextInput x="110" y="46" id="uName"/><mx:TextInput x="110" y="76" id="pWord" displayAsPassword="true"/><mx:Text x="35" y="48" text="Username:"/><mx:Text x="35" y="78" text="Password:"/><mx:Button x="120" y="115" label="Login" click="credentials()"/></mx:Panel>credentials() メソッドは、setDRMAuthenticationCredentials() メソッドにユーザー名とパスワードの値を渡すユーザー定義メ
ソッドです。値が渡されると、credentials() メソッドは TextInput オブジェクトの値をリセットします。
<mx:Script><![CDATA[
public function credentials():void{
videoStream.setDRMAuthenticationCredentials(uName, pWord, "drm");
uName.text = "";pWord.text = "";}]]></mx:Script>

この種の簡単なインターフェイスを実装する方法の 1 つに、パネルを新しい状態の一部に含める方法があります。この新しい状態は、DRMAuthenticateEvent オブジェクトがスローされるときのベースとなる状態から作成されます。次の例には、保護された FLV ファイルをポイントする source 属性を持つ VideoDisplay オブジェクトが含まれます。この例では、credentials() メソッドはさらにアプリケーションをベースの状態に戻すように変更されています。メソッドがこれを実行するのは、ユーザーの資格情報を渡して TextInput オブジェクトの値をリセットした後になります。
<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="absolute"width="800"height="500"
title="DRM FLV Player"creationComplete="initApp()" ><mx:states><mx:State name="LOGIN"><mx:AddChild position="lastChild"><mx:Panel x="236.5" y="113" width="325" height="204" layout="absolute"
title="Login"><mx:TextInput x="110" y="46" id="uName"/><mx:TextInput x="110" y="76" id="pWord" displayAsPassword="true"/><mx:Text x="35" y="48" text="Username:"/><mx:Text x="35" y="78" text="Password:"/><mx:Button x="120" y="115" label="Login" click="credentials()"/><mx:Button x="193" y="115" label="Reset" click="uName.text='';pWord.text='';"/></mx:Panel></mx:AddChild></mx:State></mx:states><mx:Script><![CDATA[
import flash.events.DRMAuthenticateEvent;private function initApp():void{

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

517

電子著作権管理の使用

videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE,
drmAuthenticateEventHandler);}public function credentials():void{
videoStream.setDRMAuthenticationCredentials(uName, pWord, "drm");
uName.text = "";pWord.text = "";currentState='';}private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void{currentState='LOGIN';}]]></mx:Script><mx:VideoDisplay id="video" x="50" y="25" width="700" height="350"autoPlay="true"
bufferTime="10.0"
source="http://www.example.com/flv/Video.flv" /></mx:WindowedApplication>

DRMErrorEvent クラスの使用
Flash Player 10.1 以降、Adobe AIR 1.0 以降保護されたコンテンツを NetStream オブジェクトが再生しようとしたときに DRM 関連のエラーが発生すると、Adobe

Flash Player および Adobe AIR は DRMErrorEvent オブジェクトを送出します。AIR アプリケーションでユーザー資格情報が無効の場合、ユーザーが有効な資格情報を入力するか、アプリケーションがそれ以上の試行を拒否するまで、

DRMAuthenticationEvent オブジェクトが繰り返し送出されます。アプリケーションは、その他の DRM エラーイベントを監視して、DRM 関連エラーを検出、識別、処理する必要があります。
ユーザーの資格情報が有効であっても、コンテンツの証明書の条件によっては、ユーザーが暗号化されたコンテンツを表示できないことがあります。例えば、許可されていないアプリケーションでコンテンツを表示しようとした際に、ユーザーはアクセスを拒否されます。許可されていないアプリケーションとは、暗号化されたコンテンツの発行者がまだ検証していな
いアプリケーションのことです。この場合、DRMErrorEvent オブジェクトが送出されます。
このエラーイベントは、コンテンツが破損している場合や、アプリケーションのバージョンが証明書が指定するバージョンと一致しない場合にも、発生させることができます。アプリケーションは、エラーを処理するための適切なメカニズムを提供する必要があります。

DRMErrorEvent プロパティ
Flash Player 10.1 以降、Adobe AIR 1.0 以降
エラーの完全な一覧については、『Adobe Flash Professional 用 ActionScript 3.0 リファレンスガイド』のランタイムエ
ラーコードを参照してください。DRM 関連エラーはエラー 3300 で始まります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

518

電子著作権管理の使用

DRMErrorEvent ハンドラーの作成
Flash Player 10.1 以降、Adobe AIR 1.0 以降
次の例では、イベントの発生元となった NetStream オブジェクトに対するイベントハンドラーを作成します。これは、保護されたコンテンツを再生しようとしている間に NetStream でエラーが発生したときに呼び出されます。通常、エラーが発生した際には、アプリケーションはあらゆるクリーンアップタスクを実行します。その後、ユーザーにエラーを通知し、問題を解決するためのオプションを提示します。
private function drmErrorEventHandler(event:DRMErrorEvent):void{
trace(event.toString());}

DRMManager クラスの使用
Flash Player 10.1 以降、Adobe AIR 1.5 以降
DRMManager クラスを使用すると、アプリケーションで証明書や Media Rights Server セッションを管理できます。
証明書の管理（AIR のみ）
ランタイムは、保護されたコンテンツをユーザーが再生するたびに、コンテンツの表示に必要なライセンスを取得してキャッシュします。アプリケーションがローカルにファイルを保存した場合、ライセンスはオフラインでの再生を許可し、ユーザーは AIR アプリケーションでコンテンツを表示できます。このようなローカルのオフラインでの再生は、Media
Rights Server に接続できない場合でも実行できます。DRMManager および NetStream の preloadEmbeddedMetadata() メ
ソッドを使用して、証明書を事前にキャッシュすることができます。アプリケーションは、コンテンツの表示に必要なライセンスを取得する必要はありません。例えば、アプリケーションでメディアファイルをダウンロードし、ユーザーがオンライン状態であるうちに証明書を取得することができます。
証明書を事前に読み込むには、NetStream preloadEmbeddedMetadata() メソッドを使用して DRMContentData オブジェク
トを取得します。DRMContentData オブジェクトには、ライセンスを提供できる Media Rights Server の URL とドメインが格納されているだけでなく、ユーザー認証が必要かどうかも記述されています。この情報を使用して DRMManager

loadVoucher() メソッドを呼び出し、証明書を取得してキャッシュできます。証明書を事前に読み込むためのワークフローについては、508 ページの「オフライン再生用の証明書の事前読み込み」を参照してください。
セッションの管理

DRMManager を使用して、Media Rights Server でユーザーを認証し、永続的なセッションを管理することもできます。
Media Rights Server とのセッションを確立するには、DRMManager authenticate() メソッドを呼び出します。認証が正常に完了すると、DRMManager から DRMAuthenticationCompleteEvent オブジェクトが送出されます。このオブジェク
トにはセッショントークンが格納されています。このトークンを保存すると、ユーザーは今後のセッション確立時にアカウ
ント情報を入力する必要がなくなります。新しい認証済みのセッションを確立するには、トークンを

setAuthenticationToken() メソッドに渡します（トークンを生成したサーバーの設定によって、トークンの有効期限などの属性が決定します。AIR アプリケーションコードではトークンのデータ構造を解析しないでください。今後の AIR の更新によってデータ構造が変更される可能性があるからです）。
認証トークンは、他のコンピューターに転送できます。トークンを保護するには、トークンを AIR の暗号化されたローカル
ストアに保存します。詳しくは、685 ページの「暗号化されたローカルストア」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド519

電子著作権管理の使用

DRMStatus イベント
Flash Player 10.1 以降、Adobe AIR 1.5 以降
loadVoucher() メソッドの呼び出しが正常に完了すると、DRMManager から DRMStatusEvent オブジェクトが送出されます。
証明書が取得されると、イベントオブジェクトの detail プロパティ（AIR のみ）の値が「DRM.voucherObtained」になり、voucher プロパティに DRMVoucher オブジェクトが格納されます。
証明書が取得されなかった場合も detail プロパティ（AIR のみ）の値は「DRM.voucherObtained」になりますが、

voucher プロパティは null になります。証明書を取得できないのは、LoadVoucherSetting が localOnly に設定されているにもかかわらず、ローカルにキャッシュされている証明書がない場合などです。
loadVoucher() の呼び出しが（認証エラーまたは通信エラーなどにより）正常に完了しなかった場合、DRMManager からは代わりに DRMErrorEvent オブジェクトまたは DRMAuthenticationErrorEvent オブジェクトが送出されます。

DRMAuthenticationComplete イベント
Flash Player 10.1 以降、Adobe AIR 1.5 以降
authenticate() メソッドの呼び出しによってユーザーの認証が正常に完了した場合、DRMManager から
DRMAuthenticationCompleteEvent オブジェクトが送出されます。

DRMAuthenticationCompleteEvent オブジェクトには、複数のアプリケーションセッションでユーザー認証の保持に使用できる再利用可能なトークンが格納されています。このトークンを DRMManager setAuthenticationToken() メソッドに渡すとセッションを再確立できます（トークンの作成者は、有効期限などのトークンの属性を設定します。トークン属性を調べる API は提供されません）。

DRMAuthenticationError イベント
Flash Player 10.1 以降、Adobe AIR 1.5 以降
authenticate() メソッドまたは setAuthenticationToken() メソッドの呼び出しによってユーザーの認証を正常に完了できない
場合、DRMManager から DRMAuthenticationErrorEvent オブジェクトが送出されます。

DRMContentData クラスの使用
Flash Player 10.1 以降、Adobe AIR 1.5 以降
DRMContentData オブジェクトには、Adobe Access によって保護されるコンテンツのメタデータプロパティが含まれています。DRMContentData のプロパティには、コンテンツを表示するためのライセンス証明書の取得に必要な情報が格納されます。506 ページの「詳細な API ワークフロー」に示しているように、DRMContentData クラスを使用して、コンテ
ンツに関連するメタデータを取得できます。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の DRMContentData クラスを参照してく
ださい。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

520

電子著作権管理の使用

Flash Player の更新による Adobe Access のサポート
Flash Player 10.1 以降
重要：Flash Player 11.5 以降は、Adobe Access モジュールと統合されているので、更新手順（SystemUpdater.update(SystemUpdaterType.DRM） の呼び出し）を行う必要はありません。この更新手順が不要となるのは、次のブラウザーとプラットフォームです。

• Flash Player 11.5 ActiveX コントロール（Windows 8 上の Internet Explorer を除くすべてのプラットフォーム）。
• Flash Player 11.5 プラグイン（すべてのブラウザー）。
• Adobe AIR（デスクトップおよびモバイル）。
つまり、次の場合は、更新手順を行う必要があります。

• Windows 8 上の Internet Explorer。
• Flash Player 11.4 以前。ただし、Google Chrome 22 以降（すべてのプラットフォーム）および Google Chrome 21 以降（Windows）の場合は更新手順を行う必要はありません。
注意：Flash Player 11.5 以降を備えたシステムでも、SystemUpdater.update(SystemUpdaterType.DRM) を安全に呼び出すことはできますが、何もダウンロードされません。

Flash Player で Adobe Access をサポートするには、Adobe Access モジュールが必要です。保護されたコンテンツをFlash Player が再生しようとすると、ランタイムは、Flash Player のモジュールまたは新しいバージョンをダウンロードする必要があるかどうかを示します。Flash Player では、この方法により、必要に応じて更新しないオプションが SWF 開発
者に提供されます。
ほとんどの場合、保護されたコンテンツを再生するために、SWF 開発者は必要な Adobe Access モジュールまたはプレー
ヤーを更新します。更新するには、SystemUpdater API を使用して、最新バージョンの Adobe Access モジュールまたはFlash Player を取得します。
SystemUpdater API では、一度に 1 回の更新のみが許可されます。エラーコード 2202 は、現在のランタイムインスタンス
または別のインスタンスで、更新が既に発生していることを示します。例えば、Internet Explorer において Flash Playerのインスタンスで更新が発生している場合、Firefox で実行されている Flash Player のインスタンスでは、更新を継続することはできません。

SystemUpdater API は、デスクトッププラットフォームのみに対してサポートされています。
注意：10.1 以前のバージョンの Flash Player では、以前のバージョンのプレーヤーでサポートされている更新メカニズム（手動のダウンロードおよび www.adobe.com からのインストールまたは Express Install）を使用します。また、AIR イン
ストーラーは Adobe Access に必要な更新を処理しますが、SystemUpdater API をサポートしていません。

更新イベントの監視Flash Player 10.1 以降
Adobe Access モジュールの更新が必要な場合、NetStream オブジェクトはコード値 DRM.UpdateNeeded と共にNetStatisEvent を送出します。この値は、NetStream オブジェクトでは、現在インストールされているいずれの
AdobeAccess モジュールを使用しても、保護されたストリームを再生できないことを示します。このイベントを監視して、
次のコードを呼び出します。
SystemUpdater.update(flash.system.SystemUpdaterType.DRM)

このコードは、プレーヤーにインストールされている Adobe Access モジュールを更新します。このモジュールに対するユーザーの同意は必要ありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

521

電子著作権管理の使用

Adobe Access モジュールが見つからない場合は、エラーがスローされます。506 ページの「詳細な API ワークフロー」の
手順 3 を参照してください。
注意：10.1 以前のプレーヤーで、暗号化されたストリームで play() が呼び出された場合、コード値
NetStream.Play.StreamNotFound と共に NetStatusEvent が送出されます。以前のプレーヤーでは、そのプレーヤーでサポートされている更新メカニズム（手動のダウンロードおよび www.adobe.com からのインストールまたは Express
Install）を使用します。
プレーヤーそのものの更新が必要な場合、SystemUpdater オブジェクトはコード値 DRM.UpdateNeededButIncompatible と共に StatusEvent を送出します。プレーヤーの更新には、ユーザーの同意が必要です。アプリケーションで、ユーザーが同意し、プレーヤーの更新を開始するためのインターフェイスを提供します。StatusEvent イベントを監視し、次のコードを呼び出します。
SystemUpdater.update(flash.system.SystemUpdaterType.SYSTEM);

このコードは、プレーヤーの更新を開始します。

SystemUpdater クラスの追加のイベントは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』に記載されています。
プレーヤーの更新が完了すると、ユーザーは、更新を開始したページにリダイレクトされます。Adobe Access モジュール
がダウンロードされ、ストリームは再生を開始できます。

帯域外ライセンスFlash Player 11 以降、Adobe AIR 3.0 以降
storeVoucher メソッドを使用してディスク上およびメモリ内に証明書（ライセンス）を保存することで、ライセンスを（Adobe Access ライセンスサーバーを使用せずに）帯域外で取得することもできます。
暗号化されたビデオを Flash Player および AIR で再生するには、各ランタイムでそのビデオの DRM 証明書を取得する必要があります。DRM 証明書にはビデオの復号化キーが含まれており、この証明書は顧客がデプロイした Adobe Access ラ
イセンスサーバーによって生成されます。

Flash Player ／ AIR ランタイムは通常、ビデオの DRM メタデータ（DRMContentData クラス）内で指定された Adobe
Access ライセンスサーバーに証明書のリクエストを送信することで証明書を取得します。Flash ／ AIR アプリケーション
は、DRMManager.loadVoucher() メソッドを呼び出して、このライセンスのリクエストをトリガーできます。または、ディ
スク上やメモリ内にコンテンツのライセンスが存在しない場合には、Flash Player ／ AIR ランタイムによって、暗号化されたビデオ再生の開始時にライセンスが自動的に要求されます。どちらの場合でも、Flash ／ AIR アプリケーションのパ
フォーマンスは Adobe Access ライセンスサーバーとの通信の影響を受けます。

DRMManager.storeVoucher() を呼び出すと、Flash ／ AIR アプリケーションは、Flash Player ／ AIR ランタイムの帯域外で取得した DRM 証明書を送信できます。次に、ランタイムはライセンス要求プロセスをスキップして、転送された証明書を暗号化されたビデオの再生に使用できます。DRM 証明書は、帯域外で取得される前でも Adobe Access ライセンスサー
バーによって生成される必要があります。ただし、外部に公開される Adobe Access ライセンスサーバーではなく、任意のHTTP サーバー上で証明書をホストすることもできます。
DRMManager.storeVoucher() は、複数デバイス間での DRM 証明書の共有をサポートするためにも使用されます。Adobe
Access 3.0 では、この機能は「ドメインサポート」と呼ばれます。デプロイ環境でこの使用法がサポートされる場合は、
DRMManager.addToDeviceGroup() メソッドを使用してデバイスグループに複数のマシンを登録できます。あるコンテンツに対する、ドメインにバインドされた有効な証明書を持つマシンがある場合は、AIR アプリケーションでは
DRMVoucher.toByteArray() メソッドを使用して直列化された DRM 証明書を抽出し、DRMManager.storeVoucher() メソッドを使用して、他のマシンでその証明書を読み込むことができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

522

電子著作権管理の使用

デバイス登録DRM 証明書はエンドユーザーのマシンにバインドされます。そのため、Flash ／ AIR アプリケーションでは、ユーザーのマシンが正しい直列化された DRM 証明書オブジェクトを参照するための一意の ID が必要です。次のシナリオでは、デバイスの登録プロセスを示します。
前提として、次のタスクを実行済みとします。

• Adobe Access サーバー SDK の設定•

事前に生成されたライセンスを取得するための HTTP サーバーの設定•保護されたコンテンツを表示するための Flash アプリケーションの作成

デバイス登録の段階では、次の操作が含まれます。

1 Flash アプリケーションは、ランダムに生成された ID を作成します。
2 Flash アプリケーションは、DRMManager.authenticate() メソッドを呼び出します。アプリケーションでは、ランダムに生成された ID を認証リクエストに含める必要があります。例えば、ユーザー名フィールドに ID を含めます。

3 手順 2 での操作の結果、Adobe Access が顧客のサーバーに認証リクエストを送信します。このリクエストにはデバイス証明書が含まれます。

a サーバーは、リクエストからデバイス証明書および生成された ID を抽出して保存します。
b 顧客のサブシステムは、このデバイス証明書のライセンスを事前に生成して保存し、そのライセンスと生成された IDとを関連付けることでアクセス権限を付与します。

4 サーバーは「成功」のメッセージでリクエストに応答します。
5 Flash アプリケーションは、生成された ID をローカル共有オブジェクト（LSO）内にローカルで保存します。
デバイスの登録後、Flash アプリケーションは、以前のスキームでデバイス ID を使用したのと同じように、次のようにして生成された ID を使用します。

1 Flash アプリケーションは、LSO で生成された ID の検索を試みます。
2 生成された ID が見つかった場合は、Flash アプリケーションは事前に生成されたライセンスのダウンロードの際に、生成された ID を使用します。Flash アプリケーションは、DRMManager.storeVoucher() メソッドを使用して、利用されるライセンスを Adobe Access クライアントに送信します。

3 生成された ID が見つからない場合は、Flash アプリケーションはデバイス登録手順を実行します。

工場出荷時状態へのリセット
デバイスのユーザーが工場出荷時状態へのリセットオプションを実行すると、デバイス証明書は消去されます。保護されたコンテンツの再生を続行するには、Flash アプリケーションでデバイス登録手順を再度実行する必要があります。Flash アプ
リケーションが事前に生成された期限切れのライセンスを送信すると、古いデバイス ID で暗号化されたライセンスなので、Adobe Access クライアントはライセンスを拒否します。

ドメインサポート
Flash Player 11 以降、Adobe AIR 3.0 以降
コンテンツメタデータでドメイン登録が必要であると指定されている場合は、AIR アプリケーションでデバイスグループに参加するための API を呼び出すことができます。この操作は、ドメインサーバーに送信されるドメイン登録リクエストをト
リガーします。ライセンスがデバイスグループに発行されると、デバイスグループに参加している他のデバイスにライセンスを書き出したり共有したりできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

523

電子著作権管理の使用

次に、デバイスグループ情報は DRMContentData の VoucherAccessInfo オブジェクトで使用されます。このオブジェクトは、証明書の正常な取得と使用に必要となる情報を表すために使用されます。

ドメインサポートを使用した暗号化されたコンテンツの再生
暗号化されたコンテンツを Adobe Access を使用して再生するには、次の手順を実行します。

1 VoucherAccessInfo.deviceGroup を使用して、デバイスグループ登録が必要かどうかを確認します。
2 認証が必要な場合：
a DeviceGroupInfo.authenticationMethod プロパティを使用して、認証が必要かどうかを確認します。
b 認証が必要な場合は、次のいずれかの手順を実行してユーザーを認証します。

•

ユーザーのユーザー名およびパスワードを取得します。DRMManager.authenticate(deviceGroup.serverURL,

deviceGroup.domain, username, password) を呼び出します。

•

キャッシュされた、または事前に生成された認証トークンを取得し、DRMManager.setAuthenticationToken() を呼び出します。

c DRMManager.addToDeviceGroup() を呼び出します。
3 次のいずれかのタスクを実行して、コンテンツの証明書を取得します。
a DRMManager.loadVoucher() メソッドを使用します。
b 同じデバイスグループ内に登録されている別のデバイスから証明書を取得します。DRMManager.storeVoucher() メ
ソッドを使用して、証明書を DRMManager に送信します。

4 NetStream.play() メソッドを使用して暗号化されたコンテンツを再生します。
コンテンツのライセンスを書き出すには、Adobe Access ライセンスサーバーからライセンスを取得した後、DRMVoucher.toByteArray() メソッドを使用して、いずれかのデバイスでライセンスの未加工のバイトを提供します。コンテ
ンツプロバイダーは通常、デバイスグループ内のデバイス数を制限しています。制限に達した場合は、現在のデバイスを登録する前に、未使用のデバイスで DRMManager.removeFromDeviceGroup() メソッドを呼び出す必要があります。

ライセンスプレビュー
Flash アプリケーションは、ライセンスプレビューリクエストを送信できます。つまり、ユーザーのマシンで、再生に必要なすべての条件が実際に満たされているかを判断するためにアプリケーションでプレビュー操作を実行し、その後でユーザーにコンテンツの購入を促すことができます。ライセンスプレビューは、クライアントでライセンスをプレビューできる機能のことを指します（ライセンスで許可されている権限を確認するため）。購入決定前にコンテンツの一部を参照する、コ
ンテンツのプレビューとは異なります。各マシンに固有のパラメーターには、利用可能な出力と保護ステータス、利用可能
なランタイムおよび DRM のバージョン、DRM クライアントのセキュリティレベルなどがあります。ライセンスプレ
ビューモードでは、ランタイムおよび DRM のクライアントでライセンスサーバーのビジネスロジックをテストし、ユー
ザーが十分な情報に基づいた決定を行えるように情報を提供することができます。そのため、クライアントは有効なライセ
ンスの状況を確認できますが、コンテンツの複合化キーを実際に受信することはありません。ライセンスプレビューのサ
ポートはオプションであり、この機能を使用するカスタムアプリケーションを実装する場合にのみ必要になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

524

電子著作権管理の使用

コンテンツの配信
Flash Player はネットワーク層を抽象化し、単純に Adobe Access サブシステムに保護されたコンテンツを提供しているので、Adobe Access はコンテンツの配信メカニズムは認識していません。これにより、コンテンツは HTTP、HTTP

Dynamic Streaming、RTMP または RTMPE 経由で配信できます。
しかし、Adobe Access がコンテンツ複合化のためのライセンスを取得する前に、保護されたコンテンツのメタデータ（通常「.metadata」ファイルの形式）が必要になり、問題が発生する場合があります。具体的には、RTMP および RTMPE プ
ロトコルでは、Flash Media Server（FMS）経由でクライアントに配信できるのは、FLV および F4V データだけです。そのため、クライアントは別の方法でメタデータ BLOB を受信する必要があります。この問題を解決する方法の 1 つは、HTTP Web サーバー上でメタデータをホストし、再生されるコンテンツに応じて適切なメタデータを取得するためのクライアントビデオプレーヤーを実装することです。
private function getMetadata():void{
extrapolated-path-to-metadata = "http://metadatas.mywebserver.com/" + videoname;var urlRequest : URLRequest = new URLRequest(extrapolated-path-to-the-metadata + ".metadata");var urlStream : URLStream = new URLStream();urlStream.addEventListener(Event.COMPLETE, handleMetadata);
urlStream.addEventListener(IOErrorEvent.NETWORK_ERROR, handleIOError);urlStream.addEventListener(IOErrorEvent.IO_ERROR, handleIOError);urlStream.addEventListener(IOErrorEvent.VERIFY_ERROR, handleIOError);try{
urlStream.load(urlRequest);}catch(se:SecurityError){videoLog.text += se.toString() + "\n";}catch(e:Error){videoLog.text += e.toString() + "\n";}}Open Source Media Framework
Open Source Media Framework（OSMF）は、独自のリッチメディアエクスペリエンスの構築において完全な柔軟性と制御性を可能にする ActionScript ベースのフレームワークです。OSMF について詳しくは、OSMF デベロッパーのサイトを参照してください。

保護されたコンテンツの再生ワークフロー
1 MediaPlayer インスタンスを作成します。
player = new MediaPlayer();

2 プレーヤーに MediaPlayerCapabilityChangeEvent.HAS_DRM_CHANGE イベントを登録します。このイベントは、コンテ
ンツが DRM 保護されている場合に送出されます。
player.addEventListener(MediaPlayerCapabilityChangeEvent.HAS_DRM_CHANGE, onDRMCapabilityChange);

3 イベントハンドラーで、DRMTrait インスタンスを取得します。DRMTrait は、authenticate() などの DRM 関連メソッドを呼び出すためのインターフェイスです。DRM 保護されたコンテンツを読み込むと、OSMF は DRM 検証を実行し、状態イベントを送出します。DRMEvent.DRM_STATE_CHANGE イベントハンドラーを DRMTrait に追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

525

電子著作権管理の使用

private function onDRMCapabilityChange(event :MediaPlayerCapabilityChangeEvent) :void{if (event.type == MediaPlayerCapabilityChangeEvent.HAS_DRM_CHANGE&& event.enabled){
drmTrait = player.media.getTrait(MediaTraitType.DRM) as DRMTrait;
drmTrait.addEventListener(DRMEvent.DRM_STATE_CHANGE, onDRMStateChange);}}

4 onDRMStateChange() メソッド内で DRM イベントを処理します。
private function onDRMStateChange(event :DRMEvent) :void{
trace ( "DRMState: ",event.drmState);switch(event.drmState){case DRMState.AUTHENTICATION_NEEDED:// Identity-based content
var authPopup :AuthWindow = AuthWindow.create(_parentWin);
authPopup.serverURL = event.serverURL;
authPopup.addEventListener("dismiss", function () :void {trace ("Authentication dismissed");if(_drmTrait != null){//Ignore authentication. Just//try to acquire a license.
_drmTrait.authenticate(null, null);}});authPopup.addEventListener("authenticate",function (event :AuthWindowEvent) :void {if(_drmTrait != null){_drmTrait.authenticate(event.username, event.password);}});
authPopup.show();break;
case DRMState.AUTHENTICATING://Display any authentication message.
trace("Authenticating...");
break;
case DRMState.AUTHENTICATION_COMPLETE:// Start to retrieve voucher and playback.
// You can display the voucher information at this point.
if(event.token)// You just received the authentication token.
{
trace("Authentication success. Token: \n", event.token);}else// You have got the voucher.
{trace("DRM License:");trace("Playback window period: ",!isNaN(event.period) ? event.period == 0 ?
"<unlimited>" : event.period : "<none>");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド526

電子著作権管理の使用

trace("Playback window end date: ",event.endDate != null ? event.endDate : "<none>");trace("Playback window start date: ",event.startDate != null ? event.startDate : "<none>");}break;
case DRMState.AUTHENTICATION_ERROR:
trace ("DRM Error:", event.mediaError.errorID +"[" + DRMErrorEventRef.getDRMErrorMnemonic(event.mediaError.errorID) + "]");//Stop everything.
player.media = null;
break;
case DRMState.DRM_SYSTEM_UPDATING:
Logger.log("Downloading DRM module...");
break;
case DRMState.UNINITIALIZED:
break;}}

最終更新日 2015/10/14

527

第 28 章：AIR での PDF コンテンツの追加
Adobe AIR 1.0 およびそれ以降
Adobe® AIR® で実行しているアプリケーションでは、SWF コンテンツや HTML コンテンツだけでなく、PDF コンテンツ
もレンダリングできます。AIR アプリケーションは、HTMLLoader クラス、WebKit エンジンおよび Adobe® Reader® のブラウザープラグインを使用して PDF コンテンツをレンダリングします。AIR アプリケーションでは、PDF コンテンツをアプリケーションのウィンドウ全体の大きさまで拡大したり、インターフェイスの一部にしたりすることができます。

Adobe Reader ブラウザープラグインは、AIR アプリケーションでの PDF ファイルの表示を制御します。Reader のツール
バーインターフェイス（位置、アンカー設定、可視性など）を変更すると、その変更は、後で AIR アプリケーションとブラウザーで PDF ファイルを表示する場合にも反映されます。
重要：AIR で PDF コンテンツをレンダリングするには、Adobe Reader または Adobe® Acrobat® のバージョン 8.1 以降がユーザーのコンピューターにインストールされている必要があります。

PDF 機能の検出
Adobe AIR 1.0 およびそれ以降
Adobe Reader または Adobe Acrobat 8.1 以降がインストールされていない場合、AIR アプリケーションに PDF コンテン
ツは表示されません。ユーザーが PDF コンテンツをレンダリングできるかどうかを調べるには、最初にHTMLLoader.pdfCapability プロパティを確認します。このプロパティは、HTMLPDFCapability クラスの次のいずれかの定数に設定されます。
定数

説明

HTMLPDFCapability.STATUS_OK

適切なバージョン（8.1 以降）の Adobe Reader が検出されたため、PDF コンテンツを HTMLLoader オブジェクトに読み込むことができます。

HTMLPDFCapability.ERROR_INSTALLED_READER_NOT_FOUND

Adobe Reader が検出されませんでした。HTMLLoader オブジェクト
は PDF コンテンツを表示できません。

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

Adobe Reader が検出されましたが、バージョンが古すぎます。
HTMLLoader オブジェクトは PDF コンテンツを表示できません。

HTMLPDFCapability.ERROR_PREFERRED_READER_TOO_OLD

適切なバージョン（8.1 以降）の Adobe Reader が検出されましたが、

8.1 より前のバージョンの Adobe Reader で PDF コンテンツを処理するように設定されています。HTMLLoader オブジェクトは PDF コンテン
ツを表示できません。

Windows では、ユーザーのシステムで Adobe Acrobat または Adobe Reader のバージョン 7.x 以降が動作している場合、PDF の読み込みをサポートするより新しいバージョンがインストールされていたとしても、そのバージョンが使用されます。この場合、pdfCapability プロパティの値が HTMLPDFCapability.STATUS_OK であれば、AIR アプリケーションで PDF
コンテンツを読み込もうとしたときに、古いバージョンの Acrobat または Reader に警告が表示されます（AIR アプリケー
ションで例外がスローされることはありません）。エンドユーザーがこのような状況になる可能性がある場合は、アプリケー
ションを実行しているときに Acrobat を開かないよう指示するメッセージをエンドユーザーに表示することを検討してください。PDF コンテンツが許容可能な時間内に読み込まれない場合は、このようなメッセージが表示されるようにすることをお勧めします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

528

AIR での PDF コンテンツの追加

Linux では、AIR はユーザーが書き出した PATH 内（acroread コマンドが含まれる場合）および /opt/Adobe/Reader
ディレクトリ内の Adobe Reader を検索します。
次のコードでは、ユーザーが AIR アプリケーションで PDF を表示できるかどうかを調べます。PDF を表示できない場合はHTMLPDFCapability エラーオブジェクトに対応するエラーコードがトレースされます。
if(HTMLLoader.pdfCapability == HTMLPDFCapability.STATUS_OK){
trace("PDF content can be displayed");}else{
trace("PDF cannot be displayed. Error code:", HTMLLoader.pdfCapability);}

PDF コンテンツの読み込み
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションに PDF を追加するには、HTMLLoader インスタンスを作成し、そのサイズを設定して、PDF のパスを読み込みます。
次の例では、外部サイトから PDF を読み込んでいます。URLRequest を使用可能な外部 PDF へのパスに置き換えます。
var request:URLRequest = new URLRequest("http://www.example.com/test.pdf");
pdf = new HTMLLoader();
pdf.height = 800;
pdf.width = 600;
pdf.load(request);
container.addChild(pdf);

また、file URL スキームや AIR 固有の URL スキーム（app や app-storage など）からコンテンツを読み込むこともできます。例えば、次のコードでは、アプリケーションディレクトリの PDFs サブディレクトリにある test.pdf を読み込んでいます。

app:/js_api_reference.pdf
AIR の URL スキームについて詳しくは、784 ページの「URI スキーム」を参照してください。

PDF コンテンツのスクリプト作成
Adobe AIR 1.0 およびそれ以降
ブラウザー内の Web ページと同様に、JavaScript を使用して PDF コンテンツを制御することができます。

Acrobat の JavaScript 拡張機能には、次のような機能があります。

•

ページのナビゲーションおよび表示倍率の制御•

ドキュメント内のフォームの処理•

マルチメディアイベントの制御

Adobe Acrobat の JavaScript 拡張機能について詳しくは、Adobe Acrobat Developer Connection（http://www.adobe.com/devnet/acrobat/javascript.html）を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

529

AIR での PDF コンテンツの追加

HTML と PDF 間の通信の基礎
Adobe AIR 1.0 およびそれ以降
HTML ページ内の JavaScript では、PDF コンテンツを表す DOM オブジェクトの postMessage() メソッドを呼び出すこと
で、PDF コンテンツ内の JavaScript にメッセージを送信することができます。例えば、次のような埋め込み PDF コンテンツがあるとします。
<object id="PDFObj" data="test.pdf" type="application/pdf" width="100%" height="100%"/>コンテナとなっている HTML コンテンツ内にある次の JavaScript は、PDF ファイル内の JavaScript にメッセージを送信します。
pdfObject = document.getElementById("PDFObj");
pdfObject.postMessage(["testMsg", "hello"]);PDF ファイルには、このメッセージを受信するための JavaScript を含めることができます。PDF ファイルには、ドキュメ
ントレベル、フォルダーレベル、ページレベル、フィールドレベル、バッチレベルなどのコンテキストで JavaScript を追加できます。ここでは、PDF ドキュメントが開いたときに評価されるスクリプトを定義するドキュメントレベルコンテキストについてのみ説明します。

PDF ファイルでは、hostContainer オブジェクトに messageHandler プロパティを追加できます。messageHandler プロパティ
は、メッセージに応答するハンドラー関数を定義するオブジェクトです。例えば、次のコードでは、PDF ファイルがホスト
コンテナ（PDF ファイルが埋め込まれた HTML コンテンツ）から受信したメッセージを処理する関数を定義しています。
this.hostContainer.messageHandler = {onMessage: myOnMessage};function myOnMessage(aMessage){if(aMessage[0] == "testMsg"){
app.alert("Test message: " + aMessage[1]);}else{
app.alert("Error");}}HTML ページ内の JavaScript では、ページに含まれている PDF オブジェクトの postMessage() メソッドを呼び出すことができます。このメソッドを呼び出すと、PDF ファイル内のドキュメントレベルの JavaScript にメッセージ（"Hello from
HTML"）が送信されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

530

AIR での PDF コンテンツの追加<html><head><title>PDF Test</title><script>function init(){
pdfObject = document.getElementById("PDFObj");try {pdfObject.postMessage(["alert", "Hello from HTML"]);}
catch (e){alert( "Error: \n name = " + e.name + "\n message = " + e.message );}}</script></head><body onload='init()'><object
id="PDFObj"
data="test.pdf"
type="application/pdf"
width="100%" height="100%"/></body></html>より高度な例と、Acrobat 8 を使用して PDF ファイルに JavaScript を追加する方法については、「Adobe AIR アプリケー
ションの PDF コンテンツのクロススクリプト」を参照してください。

ActionScript からの PDF コンテンツのスクリプト作成
Adobe AIR 1.0 およびそれ以降
SWF コンテンツ内の ActionScript コードでは、PDF コンテンツ内の JavaScript と直接通信することができません。ただし、ActionScript では、PDF コンテンツを読み込む HTMLLoader オブジェクトに読み込まれた HTML ページ内のJavaScript と通信できます。さらに、その JavaScript コードでは、読み込まれた PDF ファイル内の JavaScript と通信できます。詳しくは、944 ページの「AIR での HTML および JavaScript のプログラミング」を参照してください。

AIR 内の PDF コンテンツに関する既知の制限
Adobe AIR 1.0 およびそれ以降
Adobe AIR 内の PDF コンテンツには、次のような制限があります。

• PDF コンテンツは、透明な（transparent プロパティが true に設定されている）ウィンドウ（NativeWindow オブジェ
クト）には表示されません。

• PDF ファイルの表示順序は、AIR アプリケーションの他の表示オブジェクトの表示順序とは動作が異なります。PDF コ
ンテンツは、HTML の表示順序に従って適切に配置されますが、AIR アプリケーションの表示順序では常にコンテンツの最上部に配置されます。

• PDF ドキュメントを含む HTMLLoader オブジェクトの特定のビジュアルプロパティが変更されると、PDF ドキュメン
トは表示されなくなります。このようなプロパティには、filters、alpha、rotation および scaling があります。これらのプ
ロパティを変更すると、プロパティがリセットされるまで PDF コンテンツは表示されません。HTMLLoader オブジェ
クトを含む表示オブジェクトコンテナで同じプロパティを変更した場合も PDF コンテンツは表示されません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

531

AIR での PDF コンテンツの追加• PDF コンテンツが表示されるのは、PDF コンテンツを含む NativeWindow オブジェクトの Stage オブジェクトのscaleMode プロパティが StageScaleMode.NO_SCALE に設定されている場合のみです。他の値に設定されている場合、PDF コンテンツは表示されません。

• PDF ファイル内のコンテンツへのリンクをクリックすると、PDF コンテンツのスクロール位置が更新されます。PDF
ファイルの外部にあるコンテンツへのリンクをクリックすると、（リンクのターゲットが新規ウィンドウである場合でも）PDF ファイルを含む HTMLLoader オブジェクトがリダイレクトされます。

• PDF コメントワークフローは、AIR では機能しません。

最終更新日 2015/10/14

532

第 29 章：ユーザー操作の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションでは、ActionScript 3.0 を使用して、ユーザー操作に応答するインタラクティブ機能を作成できます。この節では、ActionScript 3.0 イベントモデルについての知識を前提としています。詳しくは、119 ページの「イベント処理」
を参照してください。

ユーザー入力のキャプチャ
Flash Player 9 以降、Adobe AIR 1.0 以降
キーボード、マウス、カメラ、またはこれらのデバイスの組み合わせによるユーザー操作は、インタラクティブ機能の基盤となります。ActionScript 3.0 では、ユーザー操作を識別しそれに応答するには、まずイベントを監視する必要があります。

InteractiveObject クラス は、DisplayObject クラスのサブクラスであり、ユーザー操作の処理に必要なイベントおよび機能に共通の構造を提供します。InteractiveObject クラスのインスタンスは直接作成しません。代わりに、SimpleButton、Sprite、TextField などの表示オブジェクトと様々な Flash オーサリングツールおよび Flex コンポーネントは、このクラス
からユーザー操作モデルを継承し、共通の構造を共有します。つまり、InteractiveObject から派生した 1 つのオブジェクト
でユーザー操作を処理するために使用する方法およびコードは、派生した他のオブジェクトにも適用できます。
重要な概念と用語
先に進む前に、次の主要なユーザー操作の用語について理解しておくことが重要です。
文字コード 現在の文字セットの文字を表す数値コード。文字セットは、キーボードで押されるキーに関連付けられています。例えば、「D」と「d」は米国英語キーボードでは同じキーで入力されますが、それぞれ異なる文字コードを持っています。
コンテキストメニュー ユーザーが右クリックした場合、またはキーボードとマウスの特定の組み合わせを使用した場合に表示されるメニュー。コンテキストメニューのコマンドは、通常、クリックしたエレメントに対して直接適用されます。例えば、イメージのコンテキストメニューにはイメージを別のウィンドウで表示するコマンドや、イメージをダウンロードする
コマンドがあります。
フォーカス 選択されたエレメントがアクティブ状態で、キーボード操作またはマウス操作の対象となっていることの表示。
キーコード キーボード上の物理的なキーに対応する数値コード。

関連項目

InteractiveObject
Keyboard
Mouse
ContextMenu

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

533

ユーザー操作の基礎

フォーカスの管理
Flash Player 9 以降、Adobe AIR 1.0 以降
インタラクティブオブジェクトは、プログラムまたはユーザー操作のいずれかによってフォーカスを取得できます。また、

tabEnabled プロパティが true に設定されている場合に Tab キーを押すと、オブジェクトのフォーカスを別のオブジェクトに渡すことができます。tabEnabled 値のデフォルトは false です。ただし、次の場合を除きます。

• SimpleButton オブジェクトの場合、この値は true です。
•

テキスト入力フィールドの場合、この値は true です。

• buttonMode が true に設定されている Sprite オブジェクトまたは MovieClip オブジェクトの場合、この値は true です。
これらの各シナリオでは、FocusEvent.FOCUS_IN または FocusEvent.FOCUS_OUT に対するリスナーを追加して、フォーカ
スを変更したときの追加動作を設定できます。これはテキストフィールドおよびフォームで特に便利ですが、スプライトやムービークリップ、つまり InteractiveObject クラスを継承する任意のオブジェクトでも使用できます。次の例では、Tabキーを使用してフォーカスの順次移動を有効にする方法と、それ以降のフォーカスイベントに応答する方法を示しています。
この場合、各四角形はフォーカスを取得すると色が変わります。
注意：Flash Professional は、フォーカスの管理にキーボードショートカットを使用するため、フォーカス管理を正確にシミュレートするには、Flash ではなくブラウザーまたは AIR で SWF ファイルをテストする必要があります。
var rows:uint = 10;
var cols:uint = 10;
var rowSpacing:uint = 25;
var colSpacing:uint = 25;
var i:uint;
var j:uint;for (i = 0; i < rows; i++){for (j = 0; j < cols; j++){createSquare(j * colSpacing, i * rowSpacing, (i * cols) + j);}}
function createSquare(startX:Number, startY:Number, tabNumber:uint):void{
var square:Sprite = new Sprite();square.graphics.beginFill(0x000000);
square.graphics.drawRect(0, 0, colSpacing, rowSpacing);square.graphics.endFill();square.x = startX;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

534

ユーザー操作の基礎

square.y = startY;square.tabEnabled = true;square.tabIndex = tabNumber;square.addEventListener(FocusEvent.FOCUS_IN, changeColor);
addChild(square);}function changeColor(event:FocusEvent):void{
event.target.transform.colorTransform = getRandomColor();}function getRandomColor():ColorTransform{// Generate random values for the red, green, and blue color channels.
var red:Number = (Math.random() * 512) - 255;
var green:Number = (Math.random() * 512) - 255;
var blue:Number = (Math.random() * 512) - 255;// Create and return a ColorTransform object with the random colors.
return new ColorTransform(1, 1, 1, 1, red, green, blue, 0);}

入力タイプの検出Flash Player 10.1 以降、Adobe AIR 2 以降
Flash Player 10.1 および Adobe AIR2 リリースでは、特定の入力タイプをサポートするために、ランタイム環境をテストする機能が導入されています。ActionScript を使用して、ランタイムが現在デプロイされているデバイスで次のことをテストできます。

•

スタイラス入力または指入力をサポートしているかどうか ( またはタッチ入力をまったくサポートしていないかどうか )•ユーザー用の仮想キーボードまたは物理キーボードがあるかどうか（またはまったくキーボードがないかどうか）•カーソルを表示するかどうか（表示しない場合、オブジェクトの上にカーソルを移動したときに発生する機能は動作しません）

入力検出 ActionScript API には次のものがあります。

• flash.system.Capabilities.touchscreenType プロパティ：現在の環境でサポートされている入力タイプを示す、実行時に提供される値。

• flash.system.TouchscreenType クラス：Capabilities.touchScreenType プロパティ用の列挙値定数のクラス。
• flash.ui.Mouse.supportsCursor プロパティ：永続的なカーソルを利用できるかどうかを示す、実行時に提供される値。
• flash.ui.Keyboard.physicalKeyboardType プロパティ：完全な物理キーボードを利用できるか、テンキーのみを利用で
きるか、まったくキーボードがないかを示す、実行時に提供される値。

• flash.ui.KeyboardType クラス：flash.ui.Keyboard.physicalKeyboardType プロパティの列挙値定数のクラス。
• flash.ui.Keyboard.hasVirtualKeyboard プロパティ：（物理キーボードの代わり、または物理キーボードに加えて）仮想キーボードがユーザーに提供されるかどうかを示す、実行時に提供される値。
入力検出 API を使用すると、ユーザーのデバイスの機能を活用したり、それらの機能が存在しない場合に、別の方法を提供したりできます。これらの API は、モバイルアプリケーションおよびタッチが有効なアプリケーションを開発するうえで、特に有用です。例えば、スタイラス用の小さいボタンがあるモバイルデバイス向けのインターフェイスがある場合は、指を使って入力を行うユーザー用に、大きいボタンを備えた別のインターフェイスを提供することができます。次のコードは、

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

535

ユーザー操作の基礎

スタイラスの操作に適切であるユーザーインターフェイスエレメントの 1 つのセットを割り当てる、createStylusUI() という関数を備えたアプリケーション用です。createTouchUI() という別の関数では、指による操作に適切であるユーザーイン
ターフェイスの別のセットを割り当てます。
if(Capabilities.touchscreenType == TouchscreenType.STYLUS ){//Construct the user interface using small buttons for a stylus//and allow more screen space for other visual content
createStylusUI();} else if(Capabilities.touchscreenType = TouchscreenType.FINGER){//Construct the user interface using larger buttons//to capture a larger point of contact with the device
createTouchUI();}

異なる入力環境用のアプリケーションを開発するときは、次の互換性に関する表を考慮してください。
環境

supportsCursor

touchscreenType == FINGER touchscreenType == STYLUS touchscreenType == NONE

従来のデスクトップ

true

false

false

true

容量性タッチスクリーンデ
false
バイス（タブレット、PDA、

true

false

false

false

false

true

false

false

false

false

true

および Apple iPhone、Palm Pre など人の微妙なタッチを検出する電話）
抵抗タッチスクリーンデバ
イス（タブレット、PDA、および HTC Fuse など精密で高圧力のタッチを検出する
電話）
非タッチスクリーンデバイス（アプリケーションを実行するが、タッチを検出するスクリーンを持たない高機能電話およびデバイス）

注意： デバイスプラットフォームによっては、多くの入力タイプの組み合わせをサポートできます。この表は一般的なガイドとして使用してください。

最終更新日 2015/10/14

536

第 30 章：キーボード入力
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションでは、キーボード入力をキャプチャして応答できるだけでなく、IME を操作して、ユーザーが ASCII テ
キスト文字以外のマルチバイト言語の文字を入力できるようにすることができます。この節では、ActionScript 3.0 イベン
トモデルについての知識を前提としています。詳しくは、119 ページの「イベント処理」を参照してください。
実行時に利用可能なキーボード（物理、仮想、英数字、12 ボタン数字など）のサポートの検出について詳しくは、534 ページの「入力タイプの検出」を参照してください。
入力方式エディター（IME）を使用すると、ユーザーは標準キーボードから複雑な文字や記号を入力できます。また、IMEを使用すると、ユーザーはアプリケーション内でシステム IME を利用することもできます。
関連項目

flash.events.KeyboardEventflash.system.IME

キーボード入力のキャプチャ
Flash Player 9 以降、Adobe AIR 1.0 以降
InteractiveObject クラスから操作モデルを継承する表示オブジェクトは、イベントリスナーを使用してキーボードイベン
トに応答できます。例えば、ステージにイベントリスナーを配置してキーボード入力を監視し、それに応答できます。次のコードでは、イベントリスナーでキーの押し下げをキャプチャして、キー名とキーコードのプロパティが表示されます。
function reportKeyDown(event:KeyboardEvent):void{
trace("Key Pressed: " + String.fromCharCode(event.charCode) + " (character code: " + event.charCode +")");}stage.addEventListener(KeyboardEvent.KEY_DOWN, reportKeyDown);

Ctrl キーなどの一部のキーには字形表現がありませんが、キーを押すとイベントが生成されます。
上記のコード例では、キーボードイベントリスナーがステージ全体のキーボード入力をキャプチャします。ステージ上の特定の表示オブジェクトに対してイベントリスナーを記述することもできます。このイベントリスナーは、オブジェクトにフォーカスがあるとトリガーされます。
次の例では、ユーザーが TextField インスタンス内に入力した場合のみ、キーストロークが出力パネルに表示されます。
Shift キーを押したままにすると、TextField の境界線の色が一時的に赤に変わります。
このコードは、ステージ上に tf という名前の TextField インスタンスがあることを前提としています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

537

キーボード入力

tf.border = true;
tf.type = "input";
tf.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown);
tf.addEventListener(KeyboardEvent.KEY_UP,reportKeyUp);function reportKeyDown(event:KeyboardEvent):void{
trace("Key Pressed: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + "character code: " + event.charCode + ")");
if (event.keyCode == Keyboard.SHIFT) tf.borderColor = 0xFF0000;}
function reportKeyUp(event:KeyboardEvent):void{
trace("Key Released: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + "character code: " + event.charCode + ")");
if (event.keyCode == Keyboard.SHIFT){
tf.borderColor = 0x000000;}}

TextField クラスは、ユーザーがテキストを入力したときに監視できる textInput イベントも報告します。詳しくは、360ページの「テキスト入力のキャプチャ」を参照してください。
注意：AIR の実行時に、キーボードイベントはキャンセルできます。Flash Player の実行時に、キーボードイベントはキャ
ンセルできません。

キーコードおよび文字コード
Flash Player 9 以降、Adobe AIR 1.0 以降
キーボードイベントの keyCode プロパティと charCode プロパティを使用することで、どのキーが押されたかを判断し、その結果として他のアクションをトリガーできます。keyCode プロパティは、キーボードのキーの値に対応する数値です。

charCode プロパティは、現在の文字セットにおけるそのキーの数値です。デフォルトの文字セットは UTF-8 で、ASCII をサポートしています。
キーコード値と文字値の主な相違点は、キーコード値がキーボードの特定のキーを表している（キーパッドの 1 は一番上の行の 1 とは異なるが、「1」を生成するキーと「!」を生成するキーは同じキーである）のに対し、文字値は特定の文字を表している（R と r の文字は異なる）ことです。
『Adobe Flash Platform 用 ActionScript 3.0 リ
注意：ASCII のキーとその文字コード値とのマッピングについて詳しくは、
ファレンスガイド』の flash.ui.Keyboard クラスの項を参照してください。
キーとキーコード間のマッピングは、デバイスやオペレーティングシステムによって異なります。このため、キーマッピン
グを使用してアクションをトリガーしないでください。代わりに、Keyboard クラスによって提供される事前定義された定数値を使って、適切な keyCode プロパティを参照します。例えば、Shift キーのキーマッピングを使用する代わりに、

Keyboard.SHIFT 定数を使用します（前のサンプルコードを参照）。

KeyboardEvent の優先度
Flash Player 9 以降、Adobe AIR 1.0 以降
他のイベントの場合と同様、キーボードイベントシーケンスは、コードで addEventListener() メソッドが割り当てられた順
番ではなく、表示オブジェクト階層によって決定されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

538

キーボード入力

例えば、次の例に示すように、tf というテキストフィールドを container というムービークリップ内に配置し、キーボードイ
ベント用のイベントリスナーを両方のインスタンスに追加すると仮定します。
container.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown);
container.tf.border = true;container.tf.type = "input";
container.tf.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown);function reportKeyDown(event:KeyboardEvent):void{
trace(event.currentTarget.name + " hears key press: " + String.fromCharCode(event.charCode) + " (keycode: " + event.keyCode + " character code: " + event.charCode + ")");}

テキストフィールドとその親コンテナの両方にリスナーがあるため、reportKeyDown() 関数は TextField 内でのキースト
ロークごとに 2 回呼び出されます。キーが押されるたびに、テキストフィールドの方が container ムービークリップより先にイベントを送出します。
オペレーティングシステムや Web ブラウザーは、Adobe Flash Player または AIR より先にキーボードイベントを処理します。例えば、Microsoft Internet Explorer では、Ctrl + W を押すと、表示されている SWF ファイルがキーボードイベントを送出する前に、ブラウザーウィンドウが閉じます。

IME クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
IME クラスを使用すると、オペレーティングシステムの IME を Flash Player または Adobe AIR 内で操作できます。
ActionScript から、次の事項を調べることができます。

•

ユーザーのコンピューターに IME がインストールされているかどうか（Capabilities.hasIME）•

ユーザーのコンピューターで IME が有効になっているかどうか（IME.enabled）•

現在の IME で使用されている変換モード（IME.conversionMode）

テキスト入力フィールドを特定の IME コンテキストに関連付けることができます。それにより、入力フィールド間をフォー
カスが移動するのに従って IME の変換モード（ひらがな、全角数字、半角数字、直接入力など）の切り替えができます。

IME を使用すると、中国語、日本語、韓国語といったマルチバイトの言語で ASCII 以外の文字を入力できるようになります。

IME の使用方法の詳細については、アプリケーションの開発対象であるオペレーティングシステムのマニュアルを参照してください。追加情報については、次の Web サイトを参照してください。

• http://www.msdn.microsoft.com/goglobal/• http://developer.apple.com/library/mac/navigation/• http://www.java.sun.com/
注意：IME がユーザーのコンピューターでアクティブではない場合、IME のメソッドまたはプロパティの呼び出しは、Capabilities.hasIME を除き、失敗します。IME を手動でアクティブにすると、それ以降の ActionScript による IME のメ
ソッドまたはプロパティの呼び出しは、意図したとおりに動作します。例えば、日本語 IME を使用する場合は、IME のメ
ソッドまたはプロパティを呼び出す前に IME をアクティブにする必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

539

キーボード入力

IME がインストールされ有効になっているかどうかの確認
Flash Player 9 以降、Adobe AIR 1.0 以降
IME のメソッドまたはプロパティを呼び出す前に、必ずユーザーのコンピューターを調べ、IME が現在インストールされ有効にされているかどうかを確認する必要があります。次のコードは、いずれかのメソッドを呼び出す前に、ユーザーがIME をインストール済みで、それがアクティブであるかどうかを確認する方法を示しています。
if (Capabilities.hasIME){
if (IME.enabled){
trace("IME is installed and enabled.");}else{
trace("IME is installed but not enabled. Please enable your IME and try again.");
}
}
else
{
trace("IME is not installed. Please install an IME and try again.");}上記のコードは、最初に、Capabilities.hasIME プロパティを使用して、ユーザーが IME をインストールしているかどうかを確認します。このプロパティが true に設定されている場合は、次に IME.enabled プロパティを使用し、ユーザーの IME が現在有効にされているかどうかを確認します。

現在有効になっている IME 変換モードの判別
Flash Player 9 以降、Adobe AIR 1.0 以降
複数言語アプリケーションを構築するときは、ユーザーが現在どの変換モードをアクティブにしているかを判別することが必要な場合もあります。次のコードは、ユーザーが IME をインストールしているかどうか、また、インストールしている場
合は、どの IME 変換モードが現在アクティブであるかを確認する方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

540

キーボード入力

if (Capabilities.hasIME){
switch (IME.conversionMode){case IMEConversionMode.ALPHANUMERIC_FULL:
tf.text = "Current conversion mode is alphanumeric (full-width).";break;
case IMEConversionMode.ALPHANUMERIC_HALF:
tf.text = "Current conversion mode is alphanumeric (half-width).";break;
case IMEConversionMode.CHINESE:
tf.text = "Current conversion mode is Chinese.";break;
case IMEConversionMode.JAPANESE_HIRAGANA:
tf.text = "Current conversion mode is Japananese Hiragana.";break;
case IMEConversionMode.JAPANESE_KATAKANA_FULL:
tf.text = "Current conversion mode is Japanese Katakana (full-width).";break;
case IMEConversionMode.JAPANESE_KATAKANA_HALF:
tf.text = "Current conversion mode is Japanese Katakana (half-width).";break;
case IMEConversionMode.KOREAN:
tf.text = "Current conversion mode is Korean.";break;
default:
tf.text = "Current conversion mode is " + IME.conversionMode + ".";
break;}}
else{
tf.text = "Please install an IME and try again.";}

上記のコードでは、最初に、ユーザーが IME をインストールしているかどうかを確認します。次に、現在の IME がどの変換モードを使用しているかを確認するために、IME.conversionMode プロパティを IMEConversionMode クラス内のそれぞれの定数と照合します。

IME 変換モードの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーの IME の変換モードを変更するときは、コードが try..catch ブロック内にラップされていることを確認する必要があります。なぜなら、conversionMode プロパティを使用して変換モードを設定すると、IME が変換モードを設定できない
場合にエラーがスローされる可能性があるからです。次のコードは、try..catch ブロックを使用して IME.conversionMode プ
ロパティを設定する方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

541

キーボード入力

var statusText:TextField = new TextField;
statusText.autoSize = TextFieldAutoSize.LEFT;
addChild(statusText);
if (Capabilities.hasIME){
try{
IME.enabled = true;
IME.conversionMode = IMEConversionMode.KOREAN;
statusText.text = "Conversion mode is " + IME.conversionMode + ".";}
catch (error:Error){
statusText.text = "Unable to set conversion mode.\n" + error.message;}}

上述のコードは、最初に、ユーザーに対してステータスメッセージを表示するためのテキストフィールドを作成します。次に、このコードは、IME がインストールされている場合、IME を有効にして変換モードを韓国語に設定します。ユーザーのコンピューターに韓国語 IME がインストールされていない場合は Flash Player によってエラーがスローされ、try..catch ブ
ロックによってキャッチされます。try..catch ブロックは、前に作成されたテキストフィールドにエラーメッセージを表示します。

特定のテキストフィールドに対する IME の無効化
Flash Player 9 以降、Adobe AIR 1.0 以降
場合によっては、ユーザーが文字を入力する間、ユーザーの IME を無効にした方が望ましいときもあります。例えば、数値入力だけを受け入れるテキストフィールドがある場合、IME が起動されてデータ入力操作が遅くなることは望ましくありません。
次の例は、FocusEvent.FOCUS_IN イベントと FocusEvent.FOCUS_OUT イベントを待ち受け、それらのイベントに応じてユーザーの IME を無効にする方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

542

キーボード入力

var phoneTxt:TextField = new TextField();
var nameTxt:TextField = new TextField();
phoneTxt.type = TextFieldType.INPUT;
phoneTxt.addEventListener(FocusEvent.FOCUS_IN, focusInHandler);phoneTxt.addEventListener(FocusEvent.FOCUS_OUT, focusOutHandler);phoneTxt.restrict = "0-9";
phoneTxt.width = 100;phoneTxt.height = 18;
phoneTxt.background = true;phoneTxt.border = true;
addChild(phoneTxt);
nameField.type = TextFieldType.INPUT;
nameField.x = 120;
nameField.width = 100;
nameField.height = 18;
nameField.background = true;
nameField.border = true;
addChild(nameField);function focusInHandler(event:FocusEvent):void{if (Capabilities.hasIME){
IME.enabled = false;}}function focusOutHandler(event:FocusEvent):void{if (Capabilities.hasIME){
IME.enabled = true;}}

この例は、phoneTxt と nameTxt という 2 つの入力テキストフィールドを作成した後、2 つのイベントリスナーを phoneTxt
テキストフィールドに追加します。ユーザーが phoneTxt テキストフィールドにフォーカスを設定すると、

FocusEvent.FOCUS_IN イベントが送出され、IME は無効になります。phoneTxt テキストフィールドがフォーカスを失うと、FocusEvent.FOCUS_OUT イベントが送出され、IME が再び有効になります。

IME 入力イベントの待ち受けFlash Player 9 以降、Adobe AIR 1.0 以降
IME 入力イベントは、入力ストリングが設定されようとしているときに送出されます。例えば、ユーザーが IME を有効にしてあり、それをアクティブにして日本語でストリングを入力する場合、ユーザーが入力ストリングを選択すると同時にIMEEvent.IME_COMPOSITION イベントが送出されます。IMEEvent.IME_COMPOSITION イベントを待ち受けるためには、
次の例に示すように、System クラス（flash.system.System.ime.addEventListener(...)）の静的プロパティ ime にイベントリス
ナーを追加する必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

543

キーボード入力

var inputTxt:TextField;
var outputTxt:TextField;
inputTxt = new TextField();
inputTxt.type = TextFieldType.INPUT;
inputTxt.width = 200;
inputTxt.height = 18;
inputTxt.border = true;
inputTxt.background = true;
addChild(inputTxt);
outputTxt = new TextField();
outputTxt.autoSize = TextFieldAutoSize.LEFT;
outputTxt.y = 20;
addChild(outputTxt);
if (Capabilities.hasIME){
IME.enabled = true;try{
IME.conversionMode = IMEConversionMode.JAPANESE_HIRAGANA;}
catch (error:Error){
outputTxt.text = "Unable to change IME.";}
System.ime.addEventListener(IMEEvent.IME_COMPOSITION, imeCompositionHandler);}else{
outputTxt.text = "Please install IME and try again.";}function imeCompositionHandler(event:IMEEvent):void{
outputTxt.text = "you typed: " + event.text;}

上記のコードは 2 つのテキストフィールドを作成し、表示リストに追加します。最初のテキストフィールド、inputTxt は、ユーザーが日本語テキストを入力できる入力テキストフィールドです。2 番目のテキストフィールド、outputTxt は、ユーザーに対するエラーメッセージを表示するか、ユーザーが inputTxt テキストフィールドに入力した日本語ストリングをエコーするための動的テキストフィールドです。

仮想キーボードFlash Player 10.2 以降、AIR 2.6 以降
多くの場合、電話やタブレットなどのモバイルデバイスには、物理キーボードの代わりに仮想ソフトウェアキーボードが用意されています。Flash API のクラスを使用すると、次の処理が可能です。

•

仮想キーボードがいつ表示され、閉じられるかを検出します。

•

キーボードが表示されないようにします。

•

仮想キーボードによって隠されるステージの領域を特定します。

•

フォーカスを取得したときにキーボードを表示するインタラクティブオブジェクトを作成します（iOS 上の AIR アプリ
ケーションではサポートされていません）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

544

キーボード入力• （AIR のみ）自動パンの動作を無効にして、アプリケーションでキーボードに合わせて表示を変更できるようにします。

仮想キーボードの動作の制御
ユーザーがテキストフィールドの内部や、特別に設定されたインタラクティブオブジェクトをタップすると、自動的に仮想キーボードが開きます。キーボードが開くと、ユーザーが入力中のテキストを参照できるように、ネイティブプラット
フォームの規則に従って、アプリケーションコンテンツのパンとサイズ変更が実行されます。
キーボードが開くと、フォーカスのあるオブジェクトから次のイベントが順に送出されます。

softKeyboardActivating イベント - キーボードがステージの上に表示され始める直前に送出されます。送出されたイベントオ
ブジェクトの preventDefault() メソッドを呼び出すと、仮想キーボードは開きません。
softKeyboardActivate イベント - softKeyboardActivating イベントの処理の完了後に送出されます。フォーカスのあるオブジェ
クトからこのイベントが送出されると、Stage オブジェクトの softKeyboardRect プロパティが、仮想キーボードによって隠されたステージの領域を反映するよう更新されます。このイベントはキャンセルできません。
注意：ユーザーがキーボードタイプを変更するなど、キーボードのサイズが変更されると、フォーカスのあるオブジェクトから 2 つ目の softKeyboardActivate イベントが送出されます。

softKeyboardDeactivate イベント - 仮想キーボードが何らかの理由で閉じたときに送出されます。このイベントはキャンセル
できません。
次の例では、ステージ上に 2 つの TextField オブジェクトを追加します。上側の TextField では、ユーザーがこのフィールドをタップしたときにキーボードが表示されないようにし、キーボードが既に表示されている場合は、そのキーボードを閉じます。下側の TextField では、デフォルトの動作が示されています。この例では、両方のテキストフィールドから送出されるソフトキーボードイベントについて報告します。
package{import flash.display.Sprite;
import flash.text.TextField;
import flash.text.TextFieldType;import flash.events.SoftKeyboardEvent;public class SoftKeyboardEventExample extends Sprite{
private var tf1:TextField = new TextField();
private var tf2:TextField = new TextField();
public function SoftKeyboardEventExample(){
tf1.width = this.stage.stageWidth;
tf1.type = TextFieldType.INPUT;
tf1.border = true;
this.addChild( tf1 );tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATING, preventSoftKe
yboard );tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, preventSoftKe
yboard );tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, preventSoftKeyboard );tf2.border = true;
tf2.type = TextFieldType.INPUT;
tf2.width = this.stage.stageWidth;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

545

キーボード入力

tf2.y = tf1.y + tf1.height + 30;
this.addChild( tf2 );tf2.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATING, allowSoftKeyboard );tf2.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, allowSoftKeyboard );tf2.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, allowSoftKeyboard);}
private function preventSoftKeyboard( event:SoftKeyboardEvent ):void{
event.preventDefault();
this.stage.focus = null; //close the keyboard, if raised
trace( "tf1 dispatched: " + event.type + " -- " + event.triggerType );}private function allowSoftKeyboard( event:SoftKeyboardEvent ):void{
trace( "tf2 dispatched: " + event.type + " -- " + event.triggerType );}}}インタラクティブオブジェクトへの仮想キーボードサポートの追加
Flash Player 10.2 以降、AIR 2.6 以降（ただし、iOS ではサポートされていません）
通常、仮想キーボードは TextField オブジェクトがタップされたときのみ開きます。InteractiveObject クラスのインスタンスを設定し、そのインスタンスがフォーカスを受け取ったときに仮想キーボードを開くことができます。
ソフトキーボードを開くように InteractiveObject インスタンスを設定するには、そのインスタンスの needsSoftKeyboard プ
ロパティを true に設定します。ステージの focus プロパティにオブジェクトが割り当てられるたびに、ソフトキーボードが自動的に開きます。また、InteractiveObject の requestSoftKeyboard() メソッドを呼び出してキーボードを表示できます。
次の例では、テキスト入力フィールドとして機能するように InteractiveObject をプログラミングする方法を示します。この例に示す TextInput クラスは、needsSoftKeyboard プロパティを設定して、必要に応じてキーボードが表示されるようにします。次に、このオブジェクトは keyDown イベントをリッスンし、型指定された文字をフィールドに挿入します。
この例では、Flash Text Engine を使用して、型指定されたテキストを追加および表示し、いくつかの重要なイベントを処理します。わかりやすくするために、この例では、すべての機能を備えたテキストフィールドを実装していません。
package {import flash.geom.Rectangle;
import flash.display.Sprite;
import flash.text.engine.TextElement;
import flash.text.engine.TextBlock;import flash.events.MouseEvent;import flash.events.FocusEvent;import flash.events.KeyboardEvent;import flash.text.engine.TextLine;
import flash.text.engine.ElementFormat;
import flash.events.Event;public class TextInput extends Sprite{
public var text:String = " ";public var textSize:Number = 24;
public var textColor:uint = 0x000000;
private var _bounds:Rectangle = new Rectangle( 0, 0, 100, textSize );private var textElement: TextElement;
private var textBlock:TextBlock = new TextBlock();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

546

キーボード入力

public function TextInput( text:String = "" ){this.text = text;
this.scrollRect = _bounds;
this.focusRect= false;//Enable keyboard support
this.needsSoftKeyboard = true;
this.addEventListener(MouseEvent.MOUSE_DOWN, onSelect);
this.addEventListener(FocusEvent.FOCUS_IN, onFocusIn);
this.addEventListener(FocusEvent.FOCUS_OUT, onFocusOut);//Setup text engine
textElement = new TextElement( text, new ElementFormat( null, textSize, textColor ) );textBlock.content = textElement;
var firstLine:TextLine = textBlock.createTextLine( null, _bounds.width - 8 );firstLine.x = 4;
firstLine.y = 4 + firstLine.totalHeight;
this.addChild( firstLine );}private function onSelect( event:MouseEvent ):void{stage.focus = this;}private function onFocusIn( event:FocusEvent ):void{
this.addEventListener( KeyboardEvent.KEY_DOWN, onKey );}private function onFocusOut( event:FocusEvent ):void{
this.removeEventListener( KeyboardEvent.KEY_UP, onKey );}private function onKey( event:KeyboardEvent ):void{
textElement.replaceText( textElement.text.length, textElement.text.length,
String.fromCharCode( event.charCode ) );updateText();}
public function set bounds( newBounds:Rectangle ):void{_bounds = newBounds.clone();drawBackground();updateText();
this.scrollRect = _bounds;//force update to focus rect, if needed
if( this.stage!= null && this.focusRect && this.stage.focus == this )this.stage.focus = this;}private function updateText():void{//clear text lines
while( this.numChildren > 0 ) this.removeChildAt( 0 );//and recreate themvar textLine:TextLine = textBlock.createTextLine( null, _bounds.width - 8);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

547

キーボード入力

while ( textLine){
textLine.x = 4;if( textLine.previousLine != null ){textLine.y = textLine.previousLine.y +textLine.previousLine.totalHeight + 2;}
else{
textLine.y = 4 + textLine.totalHeight;}
this.addChild(textLine);
textLine = textBlock.createTextLine(textLine, _bounds.width - 8 );}}private function drawBackground():void{//draw background and border for the field
this.graphics.clear();this.graphics.beginFill( 0xededed );this.graphics.lineStyle( 1, 0x000000 );this.graphics.drawRect( _bounds.x + 2, _bounds.y + 2, _bounds.width - 4, _bounds.height - 4);
this.graphics.endFill();}}}

次のメインアプリケーションクラスでは、キーボードが表示されるときまたはデバイスの方向が変更されるときに、

TextInput クラスを使用してアプリケーションレイアウトを管理する方法を示します。メインクラスは、TextInput オブ
ジェクトを作成し、ステージに表示する境界を設定します。このクラスでは、ソフトキーボードが表示されるとき、またはステージのサイズが変更されるときに、TextInput オブジェクトのサイズを調整します。このクラスは、TextInput オブ
ジェクトからのソフトキーボードイベントおよびステージからのサイズ変更イベントをリッスンします。イベントの原因に関係なく、アプリケーションではステージの表示可能な領域を特定し、ステージに表示する入力コントロールのサイズを変更します。ただし、実際のアプリケーションでは、より高度なレイアウトアルゴリズムが必要になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

548

キーボード入力

package{import flash.display.MovieClip;
import flash.events.SoftKeyboardEvent;import flash.geom.Rectangle;
import flash.events.Event;import flash.display.StageScaleMode;
import flash.display.StageAlign;
public class CustomTextField extends MovieClip {private var customField:TextInput = new TextInput("Input text: ");public function CustomTextField() {this.stage.scaleMode = StageScaleMode.NO_SCALE;
this.stage.align = StageAlign.TOP_LEFT;
this.addChild( customField );customField.bounds = new Rectangle( 0, 0, this.stage.stageWidth, this.stage.stageHeight );//track soft keyboard and stage resize events
customField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, onDisplayAreaChange );customField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, onDisplayAreaChange);
this.stage.addEventListener( Event.RESIZE, onDisplayAreaChange );}private function onDisplayAreaChange( event:Event ):void{//Fill the stage if possible, but avoid the area covered by a keyboard
var desiredBounds = new Rectangle( 0, 0, this.stage.stageWidth, this.stage.stageHeight );if( this.stage.stageHeight - this.stage.softKeyboardRect.height < desiredBounds.height )desiredBounds.height = this.stage.stageHeight - this.stage.softKeyboardRect.height;
customField.bounds = desiredBounds;}}}

注意：scaleMode プロパティが noScale に設定されている場合、方向の変更に応答してステージが送出するのは、サイズ変更
イベントのみです。他のモードでは、ステージのサイズが変更されません。その代わりに、コンテンツを拡大／縮小して補正します。

アプリケーション表示の変更の処理
AIR 2.6 以降
AIR では、アプリケーション記述子の softKeyboardBehavior エレメントを none· に設定して、ソフトキーボードの表示に関連するデフォルトのパンおよびサイズ変更の動作を無効にすることができます。
<softKeyboardBehavior>none</softKeyboardBehavior>

自動的な動作を無効にした場合は、アプリケーション表示に対する必要な調整をアプリケーションで行う必要があります。
キーボードが開くと、softKeyboardActivate イベントが送出されます。softKeyboardActivate イベントの送出時に、ステー
ジの softKeyboardRect プロパティに、開いているキーボードに隠された領域のサイズが設定されます。これらのサイズを使用してコンテンツの移動またはサイズ変更を行い、キーボードが開いてユーザーが入力するときにコンテンツが適切に表示されるようにします（キーボードが閉じると、softKeyboardRect 長方形のサイズはすべてゼロになります）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

549

キーボード入力

キーボードが閉じると、softKeyboardDeactivate イベントが送出され、アプリケーション表示を通常に戻すことができます。
package {import flash.display.MovieClip;
import flash.events.SoftKeyboardEvent;import flash.events.Event;import flash.display.StageScaleMode;
import flash.display.StageAlign;import flash.display.InteractiveObject;import flash.text.TextFieldType;import flash.text.TextField;
public class PanningExample extends MovieClip {private var textField:TextField = new TextField();
public function PanningExample() {this.stage.scaleMode = StageScaleMode.NO_SCALE;
this.stage.align = StageAlign.TOP_LEFT;
textField.y = this.stage.stageHeight - 201;
textField.width = this.stage.stageWidth;
textField.height = 200;
textField.type = TextFieldType.INPUT;
textField.border = true;
textField.wordWrap = true;
textField.multiline = true;
this.addChild( textField );//track soft keyboard and stage resize events
textField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, onKeyboardChange );textField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, onKeyboardChange );this.stage.addEventListener( Event.RESIZE, onDisplayAreaChange );}private function onDisplayAreaChange( event:Event ):void{
textField.y = this.stage.stageHeight - 201;
textField.width = this.stage.stageWidth;}
private function onKeyboardChange( event:SoftKeyboardEvent ):void{
var field:InteractiveObject = textField;
var offset:int = 0;//if the softkeyboard is open and the field is at least partially coveredif( (this.stage.softKeyboardRect.y != 0) && (field.y + field.height >this.stage.softKeyboardRect.y) )offset = field.y + field.height - this.stage.softKeyboardRect.y;//but don't push the top of the field above the top of the screen
if( field.y - offset < 0 ) offset += field.y - offset;
this.y = -offset;}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

550

キーボード入力

注意：Android では、キーボードの正確なサイズをオペレーティングシステムから取得できない場合があります（フルスクリーンモードを含む）。このような場合は、サイズが推定されます。また、横方向の場合は、ネイティブのフルスクリーン

IME キーボードがすべてのテキスト入力に使用されます。この IME キーボードにはビルトインのテキスト入力フィールドがあります。また、このキーボードはステージ全体を隠します。画面全体に表示されない横長のキーボードを表示する方法はありません。

最終更新日 2015/10/14

551

第 31 章：マウス入力
Flash Player 9 以降、Adobe AIR 1.0 以降
マウス入力をキャプチャして応答することにより、アプリケーションでインタラクティビティを実現できます。この節では、ActionScript 3.0 イベントモデルについての知識を前提としています。詳しくは、119 ページの「イベント処理」を参照してください。
実行時に利用可能なマウス（永続的なカーソル、スタイラス、タッチ入力など）のサポートの検出について詳しくは、534
ページの「入力タイプの検出」を参照してください。

関連項目

flash.ui.Mouse
flash.events.MouseEvent
557 ページの「タッチ入力、マルチタッチ入力およびジェスチャ入力」

マウス入力のキャプチャ
Flash Player 9 以降、Adobe AIR 1.0 以降
マウスクリックにより、インタラクティブ機能のトリガーに使用できるマウスイベントが作成されます。イベントリスナー
をステージに追加して、SWF ファイル内で発生するマウスイベントを監視できます。InteractiveObject クラスを継承する
ステージ上のオブジェクト（Sprite や MovieClip など）にイベントリスナーを追加することもできます。これらのリスナー
はオブジェクトがクリックされるとトリガーされます。
キーボードイベントと同様に、マウスイベントはバブルします。次の例では、square はステージの子であるため、四角形がクリックされると、スプライト square および Stage オブジェクトの両方によってイベントが送出されます。
var square:Sprite = new Sprite();square.graphics.beginFill(0xFF0000);
square.graphics.drawRect(0,0,100,100);square.graphics.endFill();square.addEventListener(MouseEvent.CLICK, reportClick);square.x =square.y = 50;
addChild(square);stage.addEventListener(MouseEvent.CLICK, reportClick);function reportClick(event:MouseEvent):void{
trace(event.currentTarget.toString() + " dispatches MouseEvent. Local coords [" + event.localX + "," +event.localY + "] Stage coords [" + event.stageX + "," + event.stageY + "]");}

上記の例では、マウスイベントには、クリックに関する位置情報が含まれます。localX プロパティと localY プロパティには、表示チェーン内の最下位の子でのクリックの場所に関する位置情報が含まれます。例えば、square の左上隅をクリック
すると、この位置は square の基準点であるため、ローカル座標の [0,0] が表示されます。一方、stageX プロパティと stageY

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

552

マウス入力

プロパティでは、ステージ上でのクリックのグローバル座標が参照されます。同じ場所をクリックすると、グローバル座標の [50,50] が表示されます。これは、square がこの座標に移動されたためです。ユーザー操作に応答する方法に応じて、これらの座標ペアの両方を使用できます。
注意：フルスクリーンモードでは、マウスロックを使用するようにアプリケーションを設定できます。マウスロックを使用
すると、カーソルが無効化され、境界のないマウス動作が可能になります。詳細については、159 ページの「フルスクリー
ンモードの操作」を参照してください。

MouseEvent オブジェクトには、altKey プロパティ、ctrlKey プロパティ、shiftKey Boolean プロパティがあります。これらのプロパティを使って、Alt キー、Ctrl キー、または Shift キーがマウスクリックと同時に押されていたかどうかを確認する
ことができます。

ステージ上でのスプライトのドラッグFlash Player 9 以降、Adobe AIR 1.0 以降
ステージ上で Sprite オブジェクトをドラッグできるようにするには、Sprite クラスの startDrag() メソッドを使用します。その例を次のコードに示します。
import flash.display.Sprite;
import flash.events.MouseEvent;var circle:Sprite = new Sprite();circle.graphics.beginFill(0xFFCC00);
circle.graphics.drawCircle(0, 0, 40);
var target1:Sprite = new Sprite();target1.graphics.beginFill(0xCCFF00);
target1.graphics.drawRect(0, 0, 100, 100);
target1.name = "target1";
var target2:Sprite = new Sprite();target2.graphics.beginFill(0xCCFF00);
target2.graphics.drawRect(0, 200, 100, 100);
target2.name = "target2";
addChild(target1);
addChild(target2);
addChild(circle);
circle.addEventListener(MouseEvent.MOUSE_DOWN, mouseDown)function mouseDown(event:MouseEvent):void{
circle.startDrag();}
circle.addEventListener(MouseEvent.MOUSE_UP, mouseReleased);function mouseReleased(event:MouseEvent):void{
circle.stopDrag();
trace(circle.dropTarget.name);}

詳しくは、165 ページの「位置の変更」でマウスのドラッグ操作の作成に関する節を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

553

マウス入力

AIR でのドラッグ＆ドロップ
Adobe AIR では、ドラッグ＆ドロップ機能のサポートを有効にすると、アプリケーションとの間でデータをドラッグイン
またはドラッグアウトできるようになります。詳しくは、584 ページの「AIR でのドラッグ＆ドロップ」を参照してください。

マウスカーソルのカスタマイズ
Flash Player 9 以降、Adobe AIR 1.0 以降
マウスカーソル（マウスポインター）を非表示にしたり、ステージ上の任意の表示オブジェクトと入れ替えたりすることができます。マウスカーソルを非表示にするには、Mouse.hide() メソッドを呼び出します。カーソルをカスタマイズするには、Mouse.hide() を呼び出し、MouseEvent.MOUSE_MOVE イベントについてステージを監視し、表示オブジェクト（カスタムカーソル）の座標をイベントの stageX プロパティと stageY プロパティに設定します。次の例は、この操作の基本的な実行方法を示したものです。
var cursor:Sprite = new Sprite();cursor.graphics.beginFill(0x000000);
cursor.graphics.drawCircle(0,0,20);
cursor.graphics.endFill();
addChild(cursor);stage.addEventListener(MouseEvent.MOUSE_MOVE,redrawCursor);
Mouse.hide();function redrawCursor(event:MouseEvent):void{cursor.x = event.stageX;
cursor.y = event.stageY;}

マウス入力の例：WordSearchFlash Player 9 以降、Adobe AIR 1.0 以降
この例では、マウスイベントの処理によるユーザーとの対話を説明します。ユーザーはマス目にランダムに配置された文字を縦横につないで、できる限り多くの単語を作ります。ただし、同じ文字を 2 回使用することはできません。この例は、ActionScript 3.0 の次のような機能を使用します。

•

コンポーネントのグリッドの動的な作成•

マウスイベントへの応答•

ユーザー操作に基づくスコアの管理

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。WordSearch アプリケーションのファイルは、Samples/WordSearch フォルダーにあります。このアプリケーションは次のファイルで構成されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

554

マウス入力

ファイル

説明

WordSearch.as

このクラスは、アプリケーションの主な機能を提供します。

WordSearch.fla

Flex（MXML）または Flash（FLA）のメインアプリケーションファイル。

またはWordSearch.mxml
dictionary.txt

作成された単語のスペルが正しく、スコアを加算できるかどうかを判断するファイル。

辞書のロードFlash Player 9 以降、Adobe AIR 1.0 以降
単語検索を利用するゲームを作成するには、辞書が必要になります。この例では、復帰文字で区切られた単語のリストを格納する dictionary.txt というテキストファイルを使用しています。words という配列を作成した後、loadDictionary() 関数がこのファイルを要求します。ロードに成功すると、このファイルは長い 1 つのストリングになります。split() メソッドを使用し、復帰文字（文字コード 10）または改行文字（文字コード 13）の各インスタンスで分割することにより、このストリングを単語の配列に変換して解析することができます。この解析は、dictionaryLoaded() 関数で発生します。
words = dictionaryText.split(String.fromCharCode(13, 10));

ユーザーインターフェイスの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
単語を配列に格納したら、ユーザーインターフェイスを設定します。2 つの Button インスタンスを作成します。1 つは単語の送信用、もう 1 つは、ユーザーが現在作成している単語のクリア用です。どちらの場合も、MouseEvent.CLICK イベントを監視して、関数を呼び出し、ユーザー入力に応答する必要があります。このイベントは、ボタンが押されるとブロードキャ
ストされます。setupUI() 関数内で、このコードは 2 つのボタンに対するリスナーを作成します。
submitWordButton.addEventListener(MouseEvent.CLICK,submitWord);clearWordButton.addEventListener(MouseEvent.CLICK,clearWord);

ゲームボードの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
ゲームボードはランダムな文字のマス目です。generateBoard() 関数内で、1 つのループを別のループ内にネストすることによって 2 次元のマス目を作成できます。最初のループが行を増やし、2 番目のループが行ごとの列の総数を増やします。これ
らの行と列で作成された各セルには、ボード上の文字を表すボタンを配置します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

555

マウス入力

private function generateBoard(startX:Number, startY:Number, totalRows:Number, totalCols:Number,buttonSize:Number):void{
buttons = new Array();
var colCounter:uint;
var rowCounter:uint;for (rowCounter = 0; rowCounter < totalRows; rowCounter++){for (colCounter = 0; colCounter < totalCols; colCounter++){var b:Button = new Button();b.x = startX + (colCounter*buttonSize);b.y = startY + (rowCounter*buttonSize);b.addEventListener(MouseEvent.CLICK, letterClicked);b.label = getRandomLetter().toUpperCase();b.setSize(buttonSize,buttonSize);b.name = "buttonRow"+rowCounter+"Col"+colCounter;
addChild(b);buttons.push(b);}}}MouseEvent.CLICK イベントに対するリスナーを追加するコードを 1 行記述するだけで、これは for ループ内の処理であるため、リスナーが各 Button インスタンスに割り当てられます。さらに、その行と列の位置を使用した名前を各ボタンに割り当てます。これにより、後からコード内で各ボタンの行と列を容易に参照できるようになります。

ユーザー入力からの単語構築
Flash Player 9 以降、Adobe AIR 1.0 以降
単語は横または縦に隣り合う文字を選択することで作成できますが、同じ文字を 2 度使用することはできません。文字をクリックすると、マウスイベントが生成されます。このときに、ユーザーが作成している単語をチェックし、前にクリックした文字の続きとして適切かどうかを確認する必要があります。適切でない場合は、前に作成していた単語を削除して新しい単語を開始します。このチェックは、isLegalContinuation() メソッドで発生します。
private function isLegalContinuation(prevButton:Button, currButton:Button):Boolean{
var currButtonRow:Number = Number(currButton.name.charAt(currButton.name. indexOf("Row") + 3));var currButtonCol:Number = Number(currButton.name.charAt(currButton.name.indexOf("Col") + 3));var prevButtonRow:Number = Number(prevButton.name.charAt(prevButton.name.indexOf("Row") + 3));var prevButtonCol:Number = Number(prevButton.name.charAt(prevButton.name.indexOf("Col") + 3));return ((prevButtonCol == currButtonCol && Math.abs(prevButtonRow - currButtonRow) <= 1) ||(prevButtonRow == currButtonRow && Math.abs(prevButtonCol - currButtonCol) <= 1));}

String クラスの charAt() メソッドと indexOf() メソッドは、現在クリックされているボタンと前にクリックされたボタンの両方から適切な行と列を取得します。行または列の値が変更されていない場合、あるいは、変更された行または列の値が前のクリックの値よりも 1 だけ大きい場合、isLegalContinuation() メソッドは true を返します。ゲームのルールを変えて縦横の他に斜めのスペリングも許可したい場合、変更されていない行または列の値のチェックを削除します。この場合、最終行は次のようになります。
return (Math.abs(prevButtonRow - currButtonRow) <= 1) && Math.abs(prevButtonCol - currButtonCol) <= 1));

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

556

マウス入力

単語送信のチェックFlash Player 9 以降、Adobe AIR 1.0 以降
ゲームのコードを完成するには、単語送信とスコア計算のチェック機能が必要です。searchForWord() メソッドにこの両方の処理が含まれます。
private function searchForWord(str:String):Number{
if (words && str){var i:uint = 0
for (i = 0; i < words.length; i++){var thisWord:String = words[i];if (str == words[i]){return i;}}
return -1;}
else{
trace("WARNING: cannot find words, or string supplied is null");}
return -1;}

この関数は、辞書内にあるすべての単語をループ処理します。ユーザーの作成した単語が辞書内の単語と一致した場合、この単語の辞書内での位置が返されます。次に、submitWord() メソッドがこの応答をチェックし、位置が有効であればスコアを更新します。

カスタマイズFlash Player 9 以降、Adobe AIR 1.0 以降
クラスの先頭にはいくつかの定数があります。これらの変数を変更してこのゲームを変更することができます。例えば、

TOTAL_TIME 変数の値を大きくすることにより、プレイ時間を変更できます。また、PERCENT_VOWELS 変数の値を少しだけ大きくすると、単語が見つかる可能性が高くなります。

最終更新日 2015/10/14

557

第 32 章：タッチ入力、マルチタッチ入力およびジェスチャ入力
Flash Player 10.1 以降、Adobe AIR 2 以降
Flash Platform のタッチイベント処理機能は、タッチ対応デバイス上の単一または複数の接触点からの入力を処理します。
また、Flash ランタイムでは、複数のタッチポイントと動作を組み合わせてジェスチャを作成するイベントを処理します。
つまり、Flash ランタイムは 2 つのタイプの入力を解釈します。
タッチ 単一のポインティングデバイス（指、スタイラスまたはその他のツール）を使用した、タッチ対応デバイス上の入力。一部のデバイスでは、指またはスタイラスを使用した複数の接触点への同時入力をサポートしています。
マルチタッチ 複数の接触点への同時入力。
ジェスチャ デバイスまたはオペレーティングシステムが、1 つ以上のタッチイベントに応答して解釈する入力。例えば、
ユーザーが 2 本の指を同時に回転させると、デバイスまたはオペレーティングシステムでは、そのタッチ入力を回転ジェス
チャとして解釈します。ジェスチャは、1 本指または単一のタッチポイントで実行される場合もあれば、複数のタッチポイ
ントを必要とする場合もあります。デバイスまたはオペレーティングシステムは、ジェスチャの種類を判定して入力に割り当てます。
タッチ入力とジェスチャ入力は、どちらもマルチタッチ入力に対応可能です。ただし、ユーザーのデバイスによって異なります。ActionScript には、タッチイベントやジェスチャイベントを処理したり、マルチタッチ入力のタッチイベントを個々に追跡して処理したりする API が用意されています。
注意：コンピューターデバイスやオペレーティングシステムによっては、タッチイベントおよびジェスチャイベントの監視で大量の処理リソース（1 秒あたり複数のフレームをレンダリングする場合と同等）が消費される可能性があります。多くの場合、タッチやジェスチャによって実現される追加機能が必要ない場合は、マウスイベントを使用する方が無難です。
タッチイベントやジェスチャイベントを実際に使用する場合は、起こりうるグラフィック変更の量を減らすことを検討してください。これは特に、パン、回転またはズーム操作中にこれらのイベントが早急に送出されるような場合に当てはまります。例えば、ユーザーがズームジェスチャを使用してコンポーネントのサイズを変更する間は、コンポーネント内のアニメーションを停止するなどの方法があります。

関連項目

flash.ui.Multitouch
flash.events.TouchEventflash.events.GestureEventflash.events.TransformGestureEventflash.events.GesturePhaseflash.events.PressAndTapGestureEvent
Paul Trani：Touch Events and Gestures on Mobile
Mike Jones：Virtual Game Controllers

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

558

タッチ入力、マルチタッチ入力およびジェスチャ入力

タッチ入力の基礎
Flash Player 10.1 以降、Adobe AIR 2 以降
タッチ入力をサポートしている環境で Flash Platform が実行されている場合、InteractiveObject のインスタンスは、タッチイベントを監視してハンドラーを呼び出すことができます。一般に、ActionScript では、他のイベントと同じ方法でタッチ、マルチタッチおよびジェスチャの各イベントを処理します（ActionScript によるイベント処理の基本情報については、

119 ページの「イベント処理」を参照してください）。
ただし、Flash ランタイムでタッチまたはジェスチャを解釈するには、タッチ入力またはマルチタッチ入力をサポートしているハードウェアとソフトウェア環境でランタイムが実行されている必要があります。様々なタッチスクリーンの種類については、534 ページの「入力タイプの検出」の比較表を参照してください。また、ランタイムがブラウザーなどのコンテナ
アプリケーション内で実行されている場合は、そのコンテナからランタイムに入力が渡されます。現在のハードウェアとオペレーティングシステム環境でマルチタッチがサポートされていても、Flash ランタイムが組み込まれているブラウザーが入力を解釈し、ランタイムに入力を渡さない場合があります。または、単に入力を完全に無視する場合があります。
次の図は、ユーザーからランタイムへの入力のフローを示しています。

ユーザー

デバイス

オペレーティング
システム

アプリケーションのコンテナ（ブラウザー）

Flash
ランタイム

ユーザーから Flash Platform ランタイムへの入力のフロー

タッチアプリケーション開発用 ActionScript API には、ランタイム環境でタッチ入力またはマルチタッチ入力がサポートされているかどうかを判断するためのクラス、メソッドおよびプロパティが用意されています。タッチ入力のサポートを判断する際に使用する API は、タッチイベント処理の「検出 API」です。
重要な概念と用語
次の参照リストに、タッチイベント処理のアプリケーションを記述する上で重要な用語を示します。
検出 API ランタイム環境でタッチイベントや様々な入力モードがサポートされているかどうかをテストするためのメソッ
ドおよびプロパティです。
タッチイベント タッチ対応デバイス上で単一の接触点を使用して実行される入力操作です。
タッチポイント 1 回のタッチイベントの接触点です。デバイスがジェスチャ入力をサポートしていない場合でも、複数の同時タッチポイントをサポートしている場合があります。
タッチシーケンス 複数のイベントの連続で、1 回のタッチの存続期間を表します。これらのイベントには、開始、移動（必要に応じて）および終了が含まれます。
マルチタッチイベント タッチ対応デバイス上で複数の接触点（2 本以上の指など）を使用して実行される入力操作です。
ジェスチャイベント タッチ対応デバイス上で実行される入力操作で、複雑な動きをトレースします。例えば、2 本の指で画面をタッチし、イメージした円の周囲をなぞるよう両方の指を同時に動かして、回転の動作を示すなどのジェスチャがあります。
フェーズ イベントフローにおける異なる時間点（開始や終了など）です。
スタイラス タッチ対応スクリーンを操作するための道具です。スタイラスを使用すると、人間の指よりも精密な操作が行えます。一部のデバイスは、特殊なスタイラスを使用した入力のみを認識します。スタイラス入力を認識するデバイスは、複数の接触点への同時入力や指による接触を認識しない場合があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

559

タッチ入力、マルチタッチ入力およびジェスチャ入力

押しながらタップ ユーザーがタッチ対応デバイスを指で押しながら、別の指またはポインティングデバイスでタップするという、特殊なマルチタッチ入力のジェスチャです。通常、このジェスチャは、マルチタッチアプリケーションでマウスの右クリック操作の代わりに使用します。

タッチ入力の API 構造
ActionScript のタッチ入力 API は、タッチ入力処理が Flash ランタイムのハードウェアとソフトウェア環境に依存するという事実に対応した設計になっています。タッチ入力 API では、主に、タッチアプリケーション開発の 3 つのニーズ（検出、イベントおよびフェーズ）に対応しています。これらの API を組み合わせて使用すれば、アプリケーションの開発時にターゲットデバイスが不明でも、予測可能で快適な操作性をユーザーに提供できます。

検出
検出 API は、実行時にハードウェアとソフトウェア環境をテストする機能を提供します。ランタイムで設定した値に基づ
き、Flash ランタイムが現在のコンテキストでタッチ入力を使用できるかどうかを判断します。また、検出のプロパティおよびメソッドのコレクションを使用して、アプリケーションがマウスイベントに反応するように設定します（環境によってサポートされていないタッチ入力がある場合に備えて、タッチイベントには設定しません）。詳しくは、560 ページの「タッチのサポートの検出」を参照してください。

イベント
ActionScript では、他のイベント処理と同様に、イベントリスナーとイベントハンドラーを使用してタッチ入力イベントを管理します。ただし、タッチ入力イベント処理では、次の点も考慮する必要があります。

•

デバイスまたはオペレーティングシステムでは、タッチを、タッチシーケンスまたは複数のタッチを組み合わせたジェスチャとして、様々に解釈します。

•

タッチ対応デバイスを（指、スタイラスまたはポインティングデバイスで）タッチするたびに、マウスイベントも送出されます。マウスイベントは MouseEvent クラスのイベントタイプで処理できます。または、タッチイベントのみに応答するようにアプリケーションを設計することができます。または、両方のイベントに応答するようにアプリケーションを設計することができます。

•

アプリケーションは、同時に発生した複数のタッチイベントに応答して、それぞれを個別に処理できます。

通常は、検出 API を使用して、アプリケーションで処理するイベントを条件に基づいて仕分けしたり、処理方法を指定したりします。アプリケーションでランタイム環境を把握していれば、ユーザーがアプリケーションを操作したときに、適切なハンドラーを呼び出したり、正しいイベントオブジェクトを確立したりできます。または、現在の環境では特定の入力を処理できないことを通知して、ユーザーに代替機能や情報を提供することができます。詳しくは、561 ページの「タッチイベ
ント処理」および 565 ページの「ジェスチャイベント処理」を参照してください。

フェーズ
タッチアプリケーションとマルチタッチアプリケーションでは、ユーザー操作のフェーズを追跡するプロパティがタッチイ
ベントオブジェクトに用意されています。ユーザー入力の開始、更新または終了などの各フェーズを処理して、ユーザーにフィードバックを提供する ActionScript を記述してみましょう。ユーザーが画面をタッチしたり、画面上でタッチポイントを移動したりしたときに、イベントのフェーズに応じて、ビジュアルオブジェクトを変化させてみます。または、フェーズを使用して、ジェスチャの展開に合わせてジェスチャの特定のプロパティを追跡します。
タッチポイントイベントでは、ユーザーが特定の操作オブジェクトを操作している時間を追跡します。アプリケーションは、複数の同時タッチポイントのフェーズを個別に追跡して、それぞれを処理することができます。
ジェスチャでは、ジェスチャの遷移に従って、その遷移に関する固有の情報を解釈します。（単一または複数の）接触点の座標が、画面上で移動するのを追跡します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

560

タッチ入力、マルチタッチ入力およびジェスチャ入力

タッチのサポートの検出
Flash Player 10.1 以降、Adobe AIR 2 以降
Multitouch クラスのプロパティを使用して、アプリケーションで処理するタッチ入力の範囲を設定します。次に、現在の環境をテストし、ActionScript で処理するイベントがサポートされていることを確認します。具体的には、まずアプリケー
ションのタッチ入力のタイプを判定します。オプションには、タッチポイント、ジェスチャ、なし（すべてのタッチ入力をマウスクリックとして解釈し、マウスイベントハンドラーのみを使用します）が用意されています。次に、Multitouch ク
ラスのプロパティとメソッドを使用して、ランタイム環境がアプリケーションで必要なタッチ入力をサポートしていることを確認します。タッチ入力のタイプがサポートされ（ジェスチャを解釈できるかどうかなど）適切に応答することを、ランタイム環境でテストします。
注意：Multitouch クラスのプロパティは静的プロパティです。どのクラスのインスタンスにも属しません。例えば、「Multitouch. プロパティ」のようなシンタックスで使用します。以下を参照してください。
var touchSupport:Boolean = Multitouch.supportsTouchEvents;

入力タイプの設定
タッチイベントには多くのエレメントやフェーズが含まれている可能性があるので、Flash ランタイムでは解釈するタッチ
入力のタイプを把握している必要があります。タッチ対応スクリーンに指でタッチするだけで、ランタイムはタッチイベン
トを送出するか。または、ジェスチャが生成されるまで待機するのか。または、タッチをマウスダウンイベントとして追跡するか。タッチ入力をサポートしているアプリケーションは、処理するタッチイベントのタイプを判定して、Flash ランタ
イムに伝える必要があります。タッチ入力タイプを判定してランタイムに伝えるには、Multitouch.inputMode プロパティを使用します。入力モードには、以下に示す 3 つのオプションのいずれかを指定できます。
なし タッチイベントに対して特別な処理は提供されません。Multitouch.inputMode=MultitouchInputMode.NONE と設定し、MouseEvent クラスを使用して入力を処理します。
単一のタッチポイント すべてのタッチ入力は個別に解釈され、すべてのタッチポイントが追跡および処理されます。

Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT と設定し、TouchEvent クラスを使用して入力を処理します。
ジェスチャ入力 デバイスまたはオペレーティングシステムは、入力を、画面上における指の動きの複雑な形態として解釈します。デバイスまたはオペレーティングシステムは、これらの動きを組み合わせて、単一のジェスチャ入力イベントに割り当てます。Multitouch.inputMode=MultitouchInputMode.GESTURE と設定し、TransformGestureEvent、PressAndTapGestureEvent または GestureEvent の各クラスを使用して入力を処理します。
タッチイベントを処理するには、事前に 561 ページの「タッチイベント処理」を参照し、Multitouch.inputMode プロパティ
を使用して入力タイプを設定する例を確認してください。

タッチ入力のサポートのテスト
Multitouch クラスには、他にも、現在の環境のタッチサポートに合わせてアプリケーションを微調整するための値を提供するプロパティがあります。Flash ランタイムでは、対応可能な同時タッチポイント数または利用可能なジェスチャ数の値を設定します。現在のランタイム環境で、アプリケーションに必要なタッチイベント処理がサポートされていない場合は、ユーザーに代替機能を提供してください。例えば、マウスイベント処理を使用するか、現在の環境で対応 / 未対応の機能に関する情報を提供します。
また、キーボード、タッチまたはマウス対応の API を使用することもできます。534 ページの「入力タイプの検出」を参照
してください。
互換性テストについて詳しくは、569 ページの「トラブルシューティング」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

561

タッチ入力、マルチタッチ入力およびジェスチャ入力

タッチイベント処理
Flash Player 10.1 以降、Adobe AIR 2 以降
ActionScript では、他のイベント（マウスイベントなど）と同じ方法で、基本タッチイベントを処理します。TouchEvent
クラスのイベントタイプ定数によって定義された一連のタッチイベントを監視できます。
注意：複数のタッチポイント入力（2 本以上の指でデバイスにタッチするなど）の場合、最初のタッチしたときにマウスイ
ベントとタッチイベントが送出されます。
基本タッチイベントを処理するには：

1 アプリケーションでタッチイベントを処理するように設定するには、flash.ui.Multitouch.inputMode プロパティを
MultitouchInputMode.TOUCH_POINT に設定します。

2 InteractiveObject クラスからプロパティを継承しているクラス（Sprite や TextField など）のインスタンスに、イベン
トリスナーをアタッチします。

3 処理対象のタッチイベントのタイプを指定します。
4 イベントに応答して処理を行うには、イベントハンドラー関数を呼び出します。
例えば、次のコードは、タッチスクリーン上で mySprite に描画された四角形をタップしたときにメッセージを表示します。
Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT;
var mySprite:Sprite = new Sprite();var myTextField:TextField = new TextField();
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(TouchEvent.TOUCH_TAP, taphandler);function taphandler(evt:TouchEvent): void {myTextField.text = "I've been tapped";
myTextField.y = 50;
addChild(myTextField);}

タッチイベントのプロパティ
イベントが発生すると、イベントオブジェクトが作成されます。TouchEvent オブジェクトには、タッチイベントの位置及び状態に関する情報が含まれています。この情報を取得するには、イベントオブジェクトのプロパティを使用します。
例えば、次のコードは、evt という TouchEvent オブジェクトを作成してから、テキストフィールドにイベントオブジェク
トの stageX プロパティ（ステージ領域でタッチが発生した位置の x 座標）を表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

562

タッチ入力、マルチタッチ入力およびジェスチャ入力

Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT;
var mySprite:Sprite = new Sprite();var myTextField:TextField = new TextField();
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(TouchEvent.TOUCH_TAP, taphandler);function taphandler(evt:TouchEvent): void {myTextField.text = evt.stageX.toString;
myTextField.y = 50;
addChild(myTextField);}

イベントオブジェクト全体で使用可能なプロパティについては、TouchEvent クラスを参照してください。
注意：すべての TouchEvent プロパティがすべてのランタイム環境でサポートされているわけではありません。例えば、一部のタッチ対応デバイスは、ユーザーがタッチスクリーンに加えている接触圧の大きさを検出できません。このようなデバイスでは、TouchEvent.pressure プロパティはサポートされません。アプリケーションが動作することを保証するには、特定のプロパティのサポートを確認します。詳しくは、569 ページの「トラブルシューティング」を参照してください。

タッチイベントのフェーズ
マウスイベントの場合と同様に、InteractiveObject 上およびその外部で、様々なステージにまたがってタッチイベントを追跡します。また、タッチ操作の開始、経過、終了を通してタッチイベントを追跡します。TouchEvent クラスはtouchBegin、touchMove および touchEnd の各イベントを処理するための値を提供します。
例えば、ユーザーが表示オブジェクトをタッチまたは移動したときに、touchBegin、touchMove および touchEnd の各イベン
トを使用して、ユーザーにビジュアルフィードバックを提供できます。
Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT;
var mySprite:Sprite = new Sprite();mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);var myTextField:TextField = new TextField();
myTextField.width = 200;
myTextField.height = 20;
addChild(myTextField);
mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin);
stage.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove);stage.addEventListener(TouchEvent.TOUCH_END, onTouchEnd);function onTouchBegin(event:TouchEvent) {myTextField.text = "touch begin" + event.touchPointID;}
function onTouchMove(event:TouchEvent) {myTextField.text = "touch move" + event.touchPointID;}
function onTouchEnd(event:TouchEvent) {myTextField.text = "touch end" + event.touchPointID;}

注意：mySprite には開始タッチイベントのリスナーはアタッチされていますが、移動または編集のタッチイベントに対するリスナーはアタッチされていません。ユーザーの指またはポインティングデバイスが表示オブジェクトの前面に移動すると、ステージが継続的にタッチイベントを監視します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

563

タッチ入力、マルチタッチ入力およびジェスチャ入力

タッチポイント ID
TouchEvent.touchPointID プロパティは、タッチ入力に応答するアプリケーションを記述する上で重要です。Flash ランタイ
ムは、タッチポイントごとに一意の touchPointID 値を割り当てます。アプリケーションは、タッチ入力のフェーズまたは動きに応答する時は必ず、イベントを処理する前に touchPointID を確認します。Sprite クラスのタッチ入力のドラッグメソッ
ドでは、適切な入力インスタンスを処理するために touchPointID プロパティをパラメーターとして使用します。
touchPointID プロパティは、イベントハンドラーが適切なタッチポイントに応答していることを保証します。このプロパ
ティがなければ、イベントハンドラーは、デバイス上におけるタッチイベントタイプの不特定のインスタンス（例えば、すべての touchMove イベント）に応答するので、予期せぬ動きが発生します。このプロパティはオブジェクトをドラッグする
場合に特に重要です。
タッチシーケンス全体を管理するには、touchPointID プロパティを使用します。タッチシーケンスには touchBegin イベント
（1 つ）、touchMove イベント（必要に応じて）および touchEnd イベント（1 つ）が含まれ、すべて同じ touchPointID 値を保持しています。
次の例は、変数 touchMoveID を確立し、touchMove イベントに応答する前に、touchPointID の値が正しいことを確認します。この値が正しくないと、他のタッチ入力によってもイベントハンドラーがトリガーされます。移動段階と終了段階のリスナーはステージ上にあります。表示オブジェクト上にはありません。ユーザーはタッチポイントを表示オブジェクトの境界外に移動する可能性があるので、移動フェーズと終了フェーズはステージによって監視されます。
Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT;
var mySprite:Sprite = new Sprite();mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);var myTextField:TextField = new TextField();
addChild(myTextField);myTextField.width = 200;
myTextField.height = 20;
var touchMoveID:int = 0;
mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin);function onTouchBegin(event:TouchEvent) {if(touchMoveID != 0) {myTextField.text = "already moving. ignoring new touch";
return;}touchMoveID = event.touchPointID;
myTextField.text = "touch begin" + event.touchPointID;stage.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove);stage.addEventListener(TouchEvent.TOUCH_END, onTouchEnd);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

564

タッチ入力、マルチタッチ入力およびジェスチャ入力}
function onTouchMove(event:TouchEvent) {if(event.touchPointID != touchMoveID) {myTextField.text = "ignoring unrelated touch";
return;}mySprite.x = event.stageX;
mySprite.y = event.stageY;
myTextField.text = "touch move" + event.touchPointID;}
function onTouchEnd(event:TouchEvent) {if(event.touchPointID != touchMoveID) {myTextField.text = "ignoring unrelated touch end";
return;}touchMoveID = 0;stage.removeEventListener(TouchEvent.TOUCH_MOVE, onTouchMove);stage.removeEventListener(TouchEvent.TOUCH_END, onTouchEnd);
myTextField.text = "touch end" + event.touchPointID;}

タッチ＆ドラッグ
Flash Player 10.1 以降、Adobe AIR 2 以降
Sprite クラスに 2 つのメソッドが追加されました。これらは、Sprite.startTouchDrag() および Sprite.stopTouchDrag() で、
タッチポイント入力をサポートしているタッチ対応アプリケーションに追加機能を提供します。これらのメソッドは、マウ
スイベントに対する Sprite.startDrag() メソッドおよび Sprite.stopDrag() メソッドと同じように機能します。ただし、Sprite.startTouchDrag() メソッドおよび Sprite.stopTouchDrag() メソッドはいずれも touchPointID 値をパラメーターとして取得します。
ランタイムでは touchPointID 値をタッチイベントのイベントオブジェクトに割り当てます。複数の同時タッチポイントがサポートされている環境では（ジェスチャが処理されない場合でも）、この値を使用して、特定のタッチポイントに応答します。touchPointID プロパティについて詳しくは、563 ページの「タッチポイント ID」を参照してください。
次のコードは、タッチイベントについて、開始ドラッグイベントハンドラーと停止ドラッグイベントハンドラーの簡単な例を示しています。変数 bg は mySprite を含む表示オブジェクトです。
mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin);
mySprite.addEventListener(TouchEvent.TOUCH_END, onTouchEnd);function onTouchBegin(e:TouchEvent) {e.target.startTouchDrag(e.touchPointID, false, bg.getRect(this));trace("touch begin");}function onTouchEnd(e:TouchEvent) {e.target.stopTouchDrag(e.touchPointID);
trace("touch end");}

また、次のコードは、ドラッグ操作にタッチイベントのフェーズを組み合わせた、より高度な例を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

565

タッチ入力、マルチタッチ入力およびジェスチャ入力

Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT;
var mySprite:Sprite = new Sprite();mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin);
mySprite.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove);
mySprite.addEventListener(TouchEvent.TOUCH_END, onTouchEnd);function onTouchBegin(evt:TouchEvent) {evt.target.startTouchDrag(evt.touchPointID);
evt.target.scaleX *= 1.5;
evt.target.scaleY *= 1.5;}
function onTouchMove(evt:TouchEvent) {evt.target.alpha = 0.5;}
function onTouchEnd(evt:TouchEvent) {evt.target.stopTouchDrag(evt.touchPointID);
evt.target.width = 40;
evt.target.height = 40;
evt.target.alpha = 1;}

ジェスチャイベント処理
Flash Player 10.1 以降、Adobe AIR 2 以降
ジェスチャは基本タッチイベントと同じ方法で処理します。TransformGestureEvent クラス、GestureEvent クラスおよび PressAndTapGestureEvent クラスのイベントタイプ定数で定義された一連のジェスチャイベントを監視できます。
ジェスチャタッチイベントを処理するには：

1 flash.ui.Multitouch.inputMode プロパティを MultitouchInputMode.GESTURE に設定し、アプリケーションでジェスチャ
入力を処理するように設定します。

2 InteractiveObject クラスからプロパティを継承しているクラス（Sprite や TextField など）のインスタンスに、イベン
トリスナーをアタッチします。

3 処理対象のジェスチャイベントのタイプを指定します。
4 イベントに応答して処理を行うには、イベントハンドラー関数を呼び出します。
例えば、次のコードは、タッチスクリーン上で mySprite に描画された四角形をスワイプしたときにメッセージを表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

566

タッチ入力、マルチタッチ入力およびジェスチャ入力

Multitouch.inputMode=MultitouchInputMode.GESTURE;
var mySprite:Sprite = new Sprite();var myTextField:TextField = new TextField();
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(TransformGestureEvent.GESTURE_SWIPE, swipehandler);function swipehandler(evt:TransformGestureEvent): void {myTextField.text = "I've been swiped";
myTextField.y = 50;
addChild(myTextField);}

2 本指タップのイベントも同様に処理されますが、その場合は GestureEvent クラスを使用します。
Multitouch.inputMode=MultitouchInputMode.GESTURE;
var mySprite:Sprite = new Sprite();var myTextField:TextField = new TextField();
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(GestureEvent.GESTURE_TWO_FINGER_TAP, taphandler);function taphandler(evt:GestureEvent): void {myTextField.text = "I've been two-finger tapped";
myTextField.y = 50;
addChild(myTextField);}

また、押しながらタップのイベントも同様に処理されますが、その場合は PressAndTapGestureEvent クラスを使用します。
Multitouch.inputMode=MultitouchInputMode.GESTURE;
var mySprite:Sprite = new Sprite();var myTextField:TextField = new TextField();
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(PressAndTapGestureEvent.GESTURE_PRESS_AND_TAP, taphandler);function taphandler(evt:PressAndTapGestureEvent): void {myTextField.text = "I've been press-and-tapped";
myTextField.y = 50;
addChild(myTextField);}

注意：すべての GestureEvent、TransformGestureEvent および PressAndTapGestureEvent イベントタイプがすべてのランタイム環境でサポートされているわけではありません。例えば、一部のタッチ対応デバイスは、複数指のスワイプを検出できません。このようなデバイスでは、InteractiveObject の gestureSwipe イベントはサポートされません。アプリケー
ションが動作することを保証するには、特定のイベントのサポートを確認します。詳しくは、569 ページの「トラブルシューティング」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

567

タッチ入力、マルチタッチ入力およびジェスチャ入力

ジェスチャイベントのプロパティ
ジェスチャイベントのイベントプロパティの範囲は、基本タッチイベントよりも狭くなっています。このプロパティには、
イベントハンドラー関数の Event オブジェクトからアクセスできます。
例えば、次のコードは、ユーザーが mySprite 上で回転ジェスチャを実行したときに、このオブジェクトを回転させます。
テキストフィールドには、前回のジェスチャからの回転量（度数）が表示されます（このコードをテストするときは、オブジェクトを何度か回転させて、値が変化するのを確認してください）。
Multitouch.inputMode=MultitouchInputMode.GESTURE;
var mySprite:Sprite = new Sprite();var mySpriteCon:Sprite = new Sprite();var myTextField:TextField = new TextField();
myTextField.y = 50;
addChild(myTextField);
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(-20,-20,40,40);
mySpriteCon.addChild(mySprite);
mySprite.x = 20;
mySprite.y = 20;
addChild(mySpriteCon);
mySprite.addEventListener(TransformGestureEvent.GESTURE_ROTATE, rothandler);function rothandler(evt:TransformGestureEvent): void {evt.target.parent.rotationZ += evt.target.rotation;
myTextField.text = evt.target.parent.rotation.toString();}

注意：すべての TransformGestureEvent プロパティがすべてのランタイム環境でサポートされているわけではありません。例えば、一部のタッチ対応デバイスは、画面上の回転ジェスチャを検出できません。このようなデバイスでは、TransformGestureEvent.rotation プロパティはサポートされません。アプリケーションが動作することを保証するには、特定のプロパティのサポートを確認します。詳しくは、569 ページの「トラブルシューティング」を参照してください。

ジェスチャのフェーズ
また、ジェスチャイベントは全フェーズを通して追跡できるので、ジェスチャの発生に従ってプロパティを追跡できます。
例えば、スワイプジェスチャでオブジェクトを移動したときに、X 座標を追跡することができます。これらの値を使用して、スワイプの終了後に移動経路上のすべての点を通る線を描画してみましょう。また、パンジェスチャを使用して画面上で表示オブジェクトをドラッグ中に、表示オブジェクトを視覚的に変化させてみます。パンジェスチャが終了したら、オブジェ
クトを再度変化させます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

568

タッチ入力、マルチタッチ入力およびジェスチャ入力

Multitouch.inputMode = MultitouchInputMode.GESTURE;
var mySprite = new Sprite();mySprite.addEventListener(TransformGestureEvent.GESTURE_PAN , onPan);
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0, 0, 40, 40);
var myTextField = new TextField();
myTextField.y = 200;
addChild(mySprite);
addChild(myTextField);function onPan(evt:TransformGestureEvent):void {evt.target.localX++;if (evt.phase==GesturePhase.BEGIN) {myTextField.text = "Begin";
evt.target.scaleX *= 1.5;
evt.target.scaleY *= 1.5;}
if (evt.phase==GesturePhase.UPDATE) {myTextField.text = "Update";
evt.target.alpha = 0.5;}
if (evt.phase==GesturePhase.END) {myTextField.text = "End";
evt.target.width = 40;
evt.target.height = 40;
evt.target.alpha = 1;}}

注意：更新フェーズの間隔は、ランタイム環境によって異なります。オペレーティングシステムとハードウェアの組み合わせによっては、更新が全く中継されない場合があります。

単純なジェスチャイベントのジェスチャフェーズ「all」
一部のジェスチャイベントオブジェクトでは、ジェスチャイベントの個々のフェーズを追跡しません。その代わりに、イベ
ントオブジェクトの phase プロパティに「all」という値を設定します。スワイプや 2 本指タップなどの単純なジェスチャでは、イベントを複数フェーズで追跡しません。gestureSwipe イベントまたは gestureTwoFingerTap イベントを監視しているInteractiveObject のイベントオブジェクトの phase プロパティは、イベントが一度送出されると必ず all に設定されます。
Multitouch.inputMode = MultitouchInputMode.GESTURE;
var mySprite = new Sprite();mySprite.addEventListener(TransformGestureEvent.GESTURE_SWIPE, onSwipe);
mySprite.addEventListener(GestureEvent.GESTURE_TWO_FINGER_TAP, onTwoTap);
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0, 0, 40, 40);
var myTextField = new TextField();
myTextField.y = 200;
addChild(mySprite);
addChild(myTextField);function onSwipe(swipeEvt:TransformGestureEvent):void {myTextField.text = swipeEvt.phase // Output is "all"}function onTwoTap(tapEvt:GestureEvent):void {myTextField.text = tapEvt.phase // Output is "all"}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

569

タッチ入力、マルチタッチ入力およびジェスチャ入力

トラブルシューティング
Flash Player 10.1 以降、Adobe AIR 2 以降
ハードウェアとソフトウェアにおけるタッチ入力のサポートは急速に変化しています。この資料は、マルチタッチをサポートしているデバイスおよびオペレーティングシステムとソフトウェアの組み合わせに関するリストを示したものではありません。ここでは、検出 API を使用して、マルチタッチをサポートしているデバイスにアプリケーションをデプロイできるかどうか判断するためのガイダンスと、ActionScript コードのトラブルシューティングのヒントを提供しています。

Flash ランタイムは、デバイス、オペレーティングシステムまたは搭載されているソフトウェア（ブラウザーなど）からランタイムに渡される情報に基づいて、タッチイベントに応答します。このようなソフトウェア環境への依存が原因で、マルチタッチ対応の説明が複雑化しています。ジェスチャ動作またはタッチ動作の解釈はデバイスによって異なります。例えば、2 本の指を同時に回転させる動作を回転として定義するのか、画面上で 1 本の指を使用して円を描く動作を回転とするのか。
ハードウェアとソフトウェア環境によって、回転ジェスチャはこのどちらかの動作で定義される場合もあれば、全く異なる動作の場合もあります。したがって、デバイスがユーザー入力を解釈してオペレーティングシステムに伝達し、オペレー
ティングシステムがその情報をランタイムに渡します。ランタイムがブラウザー内にあると、ブラウザーソフトウェアがジェスチャイベントまたはタッチイベントを解釈して、その入力をランタイムに渡さない場合があります。この動作は、「ホットキー」の動作と似ています。例えば、特定のキーの組み合わせを使用して、ブラウザー内で Flash Player を操作しようとすると、ブラウザーではメニューが開いた状態になるだけです。
個々の API およびクラスには、互換性のないオペレーティングシステムについての説明があります。次のサイトでは、

Multitouch クラスを始めとして、個々の API エントリを調べることができます。
http://help.adobe.com/ja_JP/FlashPlatform/reference/actionscript/3/flash/ui/Multitouch.html
以下に、一般的なジェスチャおよびタッチについて説明します。
パン 指を左から右または右から左に動かします。デバイスによっては、2 本指でパンする必要があります。
回転 2 本の指でタッチしてから、円の周囲をなぞるようにその指を動かします（画面上でイメージした円を 2 本の指で同時にトレースしているような動作です）。2 本指のタッチポイントの中間点がピボットポイントとして設定されます。
スワイプ 3 本の指を左から右、右から左、上から下、下から上にすばやく動かします。
ズーム 2 本の指でタッチして、ズームインするには両方の指を引き離すように動かし、ズームアウトするには両方の指を近づけます。
押しながらタップ 1 本の指を動かしながら、または押しながら、別の指で画面をタップします。
デバイスがサポートしているジェスチャおよびデバイス上でジェスチャを実行する方法については、デバイスごとに独自のドキュメントが用意されています。一般に、ジェスチャ間では、デバイスと接触しているすべての指をデバイスから離す必要があります。ただし、この動作はオペレーティングシステムによって異なります。
アプリケーションがタッチイベントまたはジェスチャに応答していないことを検出したら、次の点を確認してください。

1 InteractiveObject クラスを継承したオブジェクトクラスにアタッチされているタッチイベントまたはジェスチャイベントに対してイベントリスナーを用意していることを確認してください。タッチイベントやジェスチャイベントを監視できるのは、InteractiveObject インスタンスだけです。

2 アプリケーションのテストを Flash Professional CS5 内で実行している場合は、Flash Professional が操作を阻害している可能性があるので、アプリケーションのパブリッシュとテストを試行してください。

3 まず単純な処理を実行して、動作を確認してください（次のコード例は、Multitouch.inputMode の API エントリから援用したものです）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

570

タッチ入力、マルチタッチ入力およびジェスチャ入力

Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT;
var mySprite:Sprite = new Sprite();var myTextField:TextField = new TextField()
mySprite.graphics.beginFill(0x336699);
mySprite.graphics.drawRect(0,0,40,40);
addChild(mySprite);
mySprite.addEventListener(TouchEvent.TOUCH_TAP, taplistener);function taplistener(e:TouchEvent): void {myTextField.text = "I've been tapped";
myTextField.y = 50;
addChild(myTextField);}

長方形をタップします。この例が動作する場合は、現在の環境で単純なタップがサポートされていることがわかります。
この後で、より複雑な処理を試みます。
ジェスチャサポートのテストはさらに複雑です。各デバイスやオペレーティングシステムが様々な組み合わせのジェス
チャ入力を個別にサポートしている場合とサポートしていない場合があります。
次にズームジェスチャの簡単なテストを示します。
Multitouch.inputMode = MultitouchInputMode.GESTURE;
stage.addEventListener(TransformGestureEvent.GESTURE_ZOOM , onZoom);var myTextField = new TextField();
myTextField.y = 200;
myTextField.text = "Perform a zoom gesture";
addChild(myTextField);function onZoom(evt:TransformGestureEvent):void {myTextField.text = "Zoom is supported";}

デバイスのズームジェスチャを実行し、テキストフィールドにメッセージ Zoom is supported が設定されるかどうかを確認します。テストアプリケーションのどの箇所でもジェスチャを実行できるように、ステージにイベントリスナーが追加されます。
次にパンジェスチャの簡単なテストを示します。
Multitouch.inputMode = MultitouchInputMode.GESTURE;
stage.addEventListener(TransformGestureEvent.GESTURE_PAN , onPan);var myTextField = new TextField();
myTextField.y = 200;
myTextField.text = "Perform a pan gesture";
addChild(myTextField);function onPan(evt:TransformGestureEvent):void {myTextField.text = "Pan is supported";}

デバイスのパンジェスチャを実行し、テキストフィールドにメッセージ Pan is supported が設定されるかどうかを確認します。テストアプリケーションのどの箇所でもジェスチャを実行できるように、ステージにイベントリスナーが追加されます。
オペレーティングシステムとデバイスの組み合わせによっては、両方のジェスチャをサポートする場合や、どちらか一方のジェスチャのみをサポートする場合や、ジェスチャを一切サポートしない場合があります。アプリケーションのデプロイメント環境をテストします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

571

タッチ入力、マルチタッチ入力およびジェスチャ入力

既知の問題
タッチ入力に関連する既知の問題には次のものがあります。

1 Windows Mobile オペレーティングシステムの Internet Explorer Mobile では、SWF ファイルのコンテンツが自動的に拡大表示（ズーム）されます。

Internet Explorer のズーム機能は、SWF ファイルをホストしている HTML ページに次のコードを追加することによりオーバーライドされます。
<head><meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0"></head>2 Windows 7（および場合によってはその他のオペレーティングシステム）の場合、ジェスチャ間でポインティングデバ
イス（または指）を画面から離す必要があります。例えば、イメージを回転してズームする場合は、次のようにする必要があります。

•

回転ジェスチャを実行します。

•

画面からすべての指を離します。

•

画面上に指を戻し、ズームジェスチャを実行します。

3 Windows 7（および場合によってはその他のオペレーティングシステム）では、ユーザーのジェスチャが非常に高速の場合に、回転ジェスチャおよびズームジェスチャが常に「更新」フェーズを発生させるとは限りません。

4 Windows 7 Starter Edition ではマルチタッチをサポートしていません。詳しくは、AIR Labs Forum（http://forums.adobe.com/thread/579180?tstart=0）を参照してください。

5 Mac OS 10.5.3 以降では、ハードウェアがジェスチャイベントをサポートしていない場合でも、Multitouch.supportsGestureEvents の値は常に true です。

最終更新日 2015/10/14

572

第 33 章：コピー＆ペースト
Flash Player 10 以降、Adobe AIR 1.0 以降
システムクリップボードとの間で情報をコピーするには、クリップボード API のクラスを使用します。Adobe® Flash®

Player または Adobe® AIR® で実行されているアプリケーションとの間で送受信できるデータ形式は次のとおりです。

•

テキスト

• HTML 形式のテキスト•

リッチテキスト形式データ•

直列化されたオブジェクト•

オブジェクト参照（元のアプリケーション内でのみ有効）•

ビットマップ（AIR のみ）•

ファイル（AIR のみ）• URL ストリング（AIR のみ）

コピー＆ペーストの基礎
Flash Player 10 以降、Adobe AIR 1.0 以降
コピー＆ペースト API には、次のクラスが含まれます。
パッケージ

クラス

flash.desktop• Clipboard• ClipboardFormats• ClipboardTransferMode

静的 Clipboard.generalClipboard プロパティは、オペレーティングシステムのクリップボードを表します。Clipboard クラスには、クリップボードオブジェクトのデータを読み書きするためのメソッドが用意されています。

HTMLLoader クラス（AIR 内）および TextField クラスは、通常のコピー & ペーストのキーボードショートカットのデ
フォルト動作を実装します。コピー＆ペーストのショートカット動作をカスタムコンポーネントに実装するには、これらのキーストロークを直接リッスンします。また、ネイティブメニューコマンドをキーボードショートカット使用し、キースト
ロークに間接的に応答することもできます。
同じ情報の異なる表現を単一の Clipboard オブジェクトで使用できるようにして、他のアプリケーションがデータを認識して使用する可能性を高めることができます。例えば、イメージをイメージデータ、直列化された Bitmap オブジェクト、
ファイルとして含めることができます。ある形式でのデータのレンダリングを、その形式のデータが読み取られるまでは形式の実際の作成が行われないように遅延させることができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

573

コピー＆ペースト

システムクリップボードとの間の読み書き
Flash Player 10 以降、Adobe AIR 1.0 以降
オペレーティングシステムのクリップボードを読み取るには、次のように Clipboard.generalClipbooard オブジェクトの

getData() メソッドを呼び出して、読み取り形式で渡します。
import flash.desktop.Clipboard;
import flash.desktop.ClipboardFormats;if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){var text:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT);}

注意：Flash Player で実行されているコンテンツ、または AIR のアプリケーション以外のサンドボックスで実行されているコンテンツは、paste イベントのイベントハンドラーでのみ getData() メソッドを呼び出すことができます。つまり、AIR ア
プリケーションサンドボックスで実行されているコードのみが、paste イベントハンドラー外の getData() メソッドを呼び出すことができます。
クリップボードに書き込むには、1 つ以上の形式で Clipboard.generalClipboard オブジェクトにデータを追加します。同じ形式の既存のデータは、自動的に上書きされます。ただし、新しいデータを書き込む前にシステムクリップボードのクリアも行い、他の形式の無関係なデータも削除されるようにすることをお勧めします。
import flash.desktop.Clipboard;
import flash.desktop.ClipboardFormats;var textToCopy:String = "Copy to clipboard.";Clipboard.generalClipboard.clear();
Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, textToCopy, false);

注意：Flash Player で実行されているコンテンツ、または AIR のアプリケーション以外のサンドボックスで実行されているコンテンツは、setData() メソッドを、キーボードイベント、マウスイベント、copy イベント、cut イベントなどのユーザー
イベントのイベントハンドラー内でのみ呼び出すことができます。つまり、AIR アプリケーションサンドボックスで実行されているコードのみが、ユーザーイベントハンドラー外の setData() メソッドを呼び出すことができます。

AIR での HTML コピー＆ペースト
Adobe AIR 1.0 およびそれ以降
Adobe AIR の HTML 環境では、コピー＆ペーストに関して独自のイベントとデフォルト動作が提供されています。アプリ
ケーションサンドボックス内で実行するコードのみが、AIR の Clipboard.generalClipboard オブジェクトを通して、システム
クリップボードに直接アクセスできます。非アプリケーションのサンドボックス内の JavaScript コードは、HTML ドキュ
メントのエレメントから送出されたコピーイベントまたはペーストイベントのいずれかに応答して送出されるイベントオブ
ジェクトを通して、クリップボードにアクセスできます。
コピー＆ペーストイベントには、copy、cut、paste などがあります。これらのイベントに対して送出されるオブジェクトでは、clipboardData プロパティを使用してクリップボードにアクセスできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

574

コピー＆ペースト

デフォルト動作
Adobe AIR 1.0 およびそれ以降
デフォルトでは、AIR は、コピーコマンドに応答して選択されたアイテムをコピーします。コピーコマンドは、キーボード
ショートカットまたはコンテキストメニューによって生成されます。編集可能な領域では、AIR はカットコマンドに応答してテキストをカットするか、またはペーストコマンドに応答してカーソル位置または選択位置にテキストをペーストします。
デフォルトの動作を実行しないようにするには、送出されたイベントオブジェクトの preventDefault() メソッドを、イベント
ハンドラーで呼び出します。

イベントオブジェクトの clipboardData プロパティの使用
Adobe AIR 1.0 およびそれ以降
コピーイベントまたはペーストイベントのいずれかの結果として送出されるイベントオブジェクトの clipboardData プロパ
ティを使用すると、クリップボードのデータを読み書きできます。
コピーイベントまたはカットイベントの処理時にクリップボードに書き込むには、clipboardData オブジェクトの setData() メ
ソッドを使用し、コピーするデータと MIME タイプを渡します。
function customCopy(event){
event.clipboardData.setData("text/plain", "A copied string.");}

ペーストされるデータにアクセスするには、clipboardData オブジェクトの getData() メソッドを使用し、データ形式のMIME タイプを渡します。使用できる形式は、types プロパティによって通知されます。
function customPaste(event){
var pastedData = event.clipboardData("text/plain");}

getData() メソッドと types プロパティには、paste イベントから送出されるイベントオブジェクト内でのみアクセスできます。
次の例では、デフォルトのコピー＆ペースト動作を HTML ページでオーバーライドする方法を示します。copy イベントハ
ンドラーは、コピーされるテキストをイタリック体にして、HTML テキストとしてクリップボードにコピーします。cut イ
ベントハンドラーは、選択されたデータをクリップボードにコピーし、ドキュメントからデータを削除します。paste ハンド
ラーは、クリップボードの内容を HTML として挿入し、さらに挿入部分のスタイルを太字にします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

575

コピー＆ペースト<html><head><title>Copy and Paste</title><script language="javascript" type="text/javascript">function onCopy(event){
var selection = window.getSelection();event.clipboardData.setData("text/html","<i>" + selection + "</i>");event.preventDefault();}function onCut(event){
var selection = window.getSelection();event.clipboardData.setData("text/html","<i>" + selection + "</i>");var range = selection.getRangeAt(0);range.extractContents();
event.preventDefault();}function onPaste(event){
var insertion = document.createElement("b");insertion.innerHTML = event.clipboardData.getData("text/html");var selection = window.getSelection();var range = selection.getRangeAt(0);range.insertNode(insertion);
event.preventDefault();}</script></head><body onCopy="onCopy(event)"
onPaste="onPaste(event)"
onCut="onCut(event)"><p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium
doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore
veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam
voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur
magni dolores eos qui ratione voluptatem sequi nesciunt.</p></body></html>クリップボードのデータ形式
Flash Player 10 以降、Adobe AIR 1.0 以降
クリップボードの形式では、Clipboard オブジェクトに配置されるデータについて説明します。Flash Player または AIR
は、ActionScript データ型の形式とシステムクリップボード形式間で標準データ形式を自動的に変換します。また、アプリ
ケーションオブジェクトは、アプリケーション定義の形式を使用して ActionScript ベースのアプリケーション内およびアプ
リケーション間で転送することができます。

Clipboard オブジェクトは、同じ情報の異なる形式での表現を格納できます。例えば、Sprite を表すクリップボードオブ
ジェクトには、ファイルシステムに Sprite の表現をコピーまたはドラッグするために、同一のアプリケーション内で使用する参照形式、Flash Player または AIR で実行される別のアプリケーションが使用する直列化形式、イメージ エディターが使用するビットマップ形式、ファイル リスト形式、さらに、PNG ファイルをエンコードするための遅延レンダリング形式が含まれている可能性があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

576

コピー＆ペースト

標準データ形式
Flash Player 10 以降、Adobe AIR 1.0 以降
標準形式名を定義する定数は、ClipboardFormats クラスで提供されています。
定数

説明

TEXT_FORMAT

テキスト形式データは、ActionScript の String クラスとの間で変換されます。

HTML_FORMATHTML マークアップを含むテキストです。

RICH_TEXT_FORMAT

リッチテキスト形式データは、ActionScript の ByteArray クラスとの間で変換されます。RTF マークアップはどのような方法でも解釈または変換されません。

BITMAP_FORMAT（AIR のみ）ビットマップ形式データは、ActionScript の BitmapData クラス間で変換されます。

FILE_LIST_FORMAT（AIR のみ）ファイルリスト形式データは、ActionScript のファイルオブジェクトの配列間で変換されます。

URL_FORMAT（AIR のみ）URL 形式データは、ActionScript の String クラス間で変換されます。

AIR アプリケーションでホストされる HTML コンテンツで copy、cut または paste イベントに応答してデータをコピーおよびペーストするときは、ClipboardFormat ストリングの代わりに MIME タイプを使用する必要があります。データの有効な MIME タイプは、次のとおりです。
MIME タイプ

説明

テキスト"text/plain"

URL"text/uri-list"

ビットマップ"image/x-vnd.adobe.air.bitmap"

ファイルリスト"application/x-vnd.adobe.air.file-list"

注意：リッチテキスト形式データは、HTML コンテンツ内の paste イベントの結果として送出されたイベント オブジェクトの clipboardData プロパティから利用することはできません。

カスタムデータ形式
Flash Player 10 以降、Adobe AIR 1.0 以降
アプリケーション定義のカスタム形式を使用し、参照として、または直列化されたコピーとして、オブジェクトを転送できます。参照は、同じアプリケーション内でのみ有効です。直列化されたオブジェクトは アプリケーション間で転送できます
が、直列化および直列化解除しても有効なオブジェクトについてのみ使用できます。通常、プロパティが単純型または直列化可能なオブジェクトの場合は、オブジェクトを直列化できます。
直列化されたオブジェクトを Clipboard オブジェクトに追加するには、serializable パラメーターを true に設定して、Clipboard.setData() メソッドを呼び出します。形式名としては、いずれかの標準形式、またはアプリケーションで定義されている任意のストリングを使用できます。

転送モード
Flash Player 10 以降、Adobe AIR 1.0 以降
カスタムデータ形式でクリップボードにオブジェクトを書き込む場合は、元のオブジェクトへの参照またはその直列化コ
ピーとしてオブジェクトデータをクリップボードから読み取ることができます。オブジェクトを参照として転送するか直列化されたコピーとして転送するかを決定する 4 つの転送モードがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

577

コピー＆ペースト

転送モード

説明

ClipboardTransferModes.ORIGINAL_ONLY

参照のみが返されます。参照を使用できない場合は、null 値が返されます。

ClipboardTransferModes.ORIGINAL_PREFFERED

使用できる場合は、参照が返されます。参照を使用できない場合は、直列化されたコピーが返されます。

ClipboardTransferModes.CLONE_ONLY

直列化されたコピーのみが返されます。直列化されたコピーを使用できない場合は、null値が返されます。

ClipboardTransferModes.CLONE_PREFFERED

使用できる場合は、直列化されたコピーが返されます。直列化されたコピーを使用できな
い場合は、参照が返されます。

カスタムデータ形式の読み取りと書き込み
Flash Player 10 以降、Adobe AIR 1.0 以降
クリップボードにオブジェクトを書き込むときの形式パラメータとして、予約された接頭辞である air: または flash: で始まらない任意のストリングを使用できます。そのオブジェクトを読み取るには、形式として同じストリングを使用します。次の例では、クリップボードにオブジェクトを読み書きする方法を示します。
public function createClipboardObject(object:Object):Clipboard{var transfer:Clipboard = Clipboard.generalClipboard;transfer.setData("object", object, true);}

クリップボードオブジェクトから直列化オブジェクトを抽出する（ドロップまたはペースト操作後）には、同じ形式名および CLONE_ONLY または CLONE_PREFFERED 転送モードを使用します。
var transfer:Object = clipboard.getData("object", ClipboardTransferMode.CLONE_ONLY);

参照は、Clipboard オブジェクトに常に追加されます。（ドロップ操作またはペースト操作の後で）直列化されたコピーの代わりに参照をクリップボードオブジェクトから抽出するには、ORIGINAL_ONLY または ORIGINAL_PREFFERED 転送
モードを使用します。
var transferredObject:Object =clipboard.getData("object", ClipboardTransferMode.ORIGINAL_ONLY);

参照は、Clipboard オブジェクトが現在のアプリケーションから発生している場合にのみ有効です。参照が使用できるときには参照にアクセスし、参照が使用できないときには直列化されたクローンにアクセスするには、ORIGINAL_PREFFERED
転送モードを使用します。

遅延レンダリング
Flash Player 10 以降、Adobe AIR 1.0 以降
データ形式の作成に大量の処理が必要になる場合は、必要に応じてデータを提供する関数を用意することで、遅延レンダリ
ングを使用できます。この関数は、ドロップ操作またはペースト操作の受け取り側が遅延された形式でデータを要求する場
合にのみ呼び出されます。
レンダリング関数を Clipboard オブジェクトに追加するには、setDataHandler() メソッドを使用します。この関数は、適切な形式でデータを返す必要があります。例えば、setDataHandler(ClipboardFormat.TEXT_FORMAT, writeText) を呼び出した場合、writeText() 関数はストリングを返す必要があります。
同じ型のデータ形式が setData() メソッドで Clipboard オブジェクトに追加された場合は、そのデータが遅延バージョンより優先されます（レンダリング関数は呼び出されません）。同じクリップボードデータが 2 回目にアクセスされるときは、レンダリング関数が再び呼び出される場合と、呼び出されない場合があります。
注意：Mac OS X では、遅延レンダリングは、カスタムデータ形式でのみ機能します。標準データ形式では、レンダリング
関数は直ちに呼び出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

578

コピー＆ペースト

遅延レンダリング関数を使用したテキストのペースト
Flash Player 10 以降、Adobe AIR 1.0 以降
次の例では、遅延レンダリング関数の実装方法を示します。
ユーザーが「コピー」ボタンを押すと、アプリケーションによってシステムクリップボードがクリアされ、前のクリップ
ボード操作のデータが消去されます。次に、setDataHandler() メソッドがクリップボードレンダラーとして renderData() 関数を設定します。
目的のテキストフィールドのコンテキストメニューから「ペースト」コマンドを選択すると、アプリケーションはクリップ
ボードにアクセスして、目的のテキストを設定します。クリップボードのテキストデータ形式はストリングではなく関数を使用して設定されるので、クリップボードは renderData() 関数を呼び出します。renderData() 関数はテキストをソーステキストで返し、それがペースト先のテキストに割り当てられます。
「ペースト」ボタンをクリックする前にソーステキストを編集した場合、「コピー」ボタンをクリックした後で編集を行ったとしても、ペーストされるテキストに編集が反映されます。これは、「ペースト」ボタンがクリックされてから、レンダリン
グ関数がソーステキストをコピーするからです（実際のアプリケーションで遅延レンダリングを使用するときは、このような問題を防ぐため、ソースデータを何らかの方法で保存または保護することが必要になる場合があります）。

Flash の例
package {import flash.desktop.Clipboard;
import flash.desktop.ClipboardFormats;import flash.desktop.ClipboardTransferMode;
import flash.display.Sprite;
import flash.text.TextField;
import flash.text.TextFormat;
import flash.text.TextFieldType;import flash.events.MouseEvent;import flash.events.Event;public class DeferredRenderingExample extends Sprite{
private var sourceTextField:TextField;
private var destination:TextField;
private var copyText:TextField;
public function DeferredRenderingExample():void{
sourceTextField = createTextField(10, 10, 380, 90);sourceTextField.text = "Neque porro quisquam est qui dolorem "+ "ipsum quia dolor sit amet, consectetur, adipisci velit.";
copyText = createTextField(10, 110, 35, 20);
copyText.htmlText = "<a href='#'>Copy</a>";copyText.addEventListener(MouseEvent.CLICK, onCopy);
destination = createTextField(10, 145, 380, 90);
destination.addEventListener(Event.PASTE, onPaste);}private function createTextField(x:Number, y:Number, width:Number,height:Number):TextField{
var newTxt:TextField = new TextField();
newTxt.x = x;
newTxt.y = y;
newTxt.height = height;
newTxt.width = width;
newTxt.border = true;
newTxt.multiline = true;
newTxt.wordWrap = true;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

579

コピー＆ペースト

newTxt.type = TextFieldType.INPUT;
addChild(newTxt);
return newTxt;}
public function onCopy(event:MouseEvent):void{
Clipboard.generalClipboard.clear();
Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT,
renderData);}
public function onPaste(event:Event):void{
sourceTextField.text =Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT).toString;}
public function renderData():String{
trace("Rendering data");var sourceStr:String = sourceTextField.text;
if (sourceTextField.selectionEndIndex >sourceTextField.selectionBeginIndex){
return sourceStr.substring(sourceTextField.selectionBeginIndex,
sourceTextField.selectionEndIndex);}
else{
return sourceStr;}}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

580

コピー＆ペースト

Flex の例<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="326" height="330"applicationComplete="init()"><mx:Script><![CDATA[
import flash.desktop.Clipboard;
import flash.desktop.ClipboardFormats;public function init():void{destination.addEventListener("paste", doPaste);}public function doCopy():void{
Clipboard.generalClipboard.clear();
Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, renderData);}
public function doPaste(event:Event):void{destination.text = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT).toString;}
public function renderData():String{
trace("Rendering data");return source.text;}]]></mx:Script><mx:Label x="10" y="10" text="Source"/><mx:TextArea id="source" x="10" y="36" width="300" height="100"><mx:text>Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit.</mx:text></mx:TextArea><mx:Label x="10" y="181" text="Destination"/><mx:TextArea id="destination" x="12" y="207" width="300" height="100"/><mx:Button click="doCopy();" x="91" y="156" label="Copy"/></mx:Application>

最終更新日 2015/10/14

581

第 34 章：加速度センサー入力
Flash Player 10.1 以降、Adobe AIR 2 以降
Accelerometer クラスは、デバイスのモーションセンサーによって検出されたアクティビティに基づいてイベントを送出します。このデータは、デバイスの位置または 3D 軸に沿った移動を表します。デバイスが移動すると、センサーによってその移動が検出され、デバイスの加速度座標が返されます。Accelerometer クラスは、加速度センサーがサポートされているかどうかを照会するメソッドを提供します。また、加速度センサーイベントが送出される頻度を設定するメソッドも提供します。
加速度センサーの軸は、デバイスの物理的な方向ではなく、表示の方向に沿って正規化されます。デバイスで表示の方向が再設定されると、加速度センサーの軸の方向も同様に再設定されます。このため、ユーザーが通常の直立状態の表示位置で電話を保持しているときは、電話がどの方向に回転しても、Y 軸はほぼ垂直になります。例えば、自動回転が無効で、ブラウザーの SWF コンテンツがフルスクリーンモードの場合は、デバイスの回転時にも加速度センサーの軸の方向は再設定さ
れません。

関連項目

flash.sensors.Accelerometer
flash.events.AccelerometerEvent

加速度センサーのサポートの確認
ランタイム環境でこの機能を使用できるかどうかを確認するには、Accelerometer.isSupported プロパティを使用します。
if (Accelerometer.isSupported){// Set up Accelerometer event listeners and code.
}

Accelerometer クラスおよびそのメンバーは、各 API エントリにリスト表示されているランタイムバージョンにアクセスできます。ただし、この機能を使用できるかどうかは、実行時の現在の環境によって決まります。例えば、Flash Player
10.1 では、Accelerometer クラスのプロパティを使用してコードをコンパイルできますが、Accelerometer.isSupported プロ
パティを使用して、ユーザーのデバイス上で加速度センサー機能が使用できるかどうかを確認する必要があります。

Accelerometer.isSupported がランタイムで true の場合、Accelerometer は現在サポートされています。

加速度センサーの変更の検出
加速度センサーを使用するには、Accelerometer オブジェクトをインスタンス化し、送出する update イベントに登録する必要があります。update イベントは、加速度センサーイベントオブジェクトです。このイベントには 4 つのプロパティがあり、それぞれ数値を表します。

• accelerationX - X 軸方向の加速度。単位は G。デバイスが直立状態にある場合、X 軸はデバイスの左から右へ伸びます（デバイスの上部が上を向いている場合がデバイスの直立状態です）。デバイスが右方向に移動する場合、加速度は正の値になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

582

加速度センサー入力• accelerationY - Y 軸方向の加速度。単位は G。デバイスが直立状態にある場合は、Y 軸はデバイスの下から上へ伸びます（デバイスの上部が上を向いている場合がデバイスの直立状態です）。デバイスがこの軸を基準にして上方向に移動する場
合、加速度は正の値になります。

• accelerationZ - Z 軸方向の加速度。単位は G。Z 軸はデバイス面の垂直方向に伸びます。デバイスの画面が上を向くように移動する場合、加速度は正の値になります。デバイスの画面が地面に向いている場合、加速度は負の値になります。

• timestamp — ランタイムが初期化されてからイベント発生時までの時間（ミリ秒）です。
1 G は引力に起因する標準加速度で、約 9.8 m/sec2 です。
以下に、テキストフィールドに加速度センサーのデータを表示する基本例を示します。
var accl:Accelerometer;
if (Accelerometer.isSupported){
accl = new Accelerometer();accl.addEventListener(AccelerometerEvent.UPDATE, updateHandler);}else{
accTextField.text = "Accelerometer feature not supported";}function updateHandler(evt:AccelerometerEvent):void{
accTextField.text = "acceleration X: " + evt.accelerationX.toString() + "\n"+ "acceleration Y: " + evt.accelerationY.toString() + "\n"+ "acceleration Z: " + evt.accelerationZ.toString()}

この例を使用するには、このコードを実行する前に accTextField テキストフィールドを作成し、表示リストに追加する必要があります。

Accelerometer オブジェクトの setRequestedUpdateInterval() メソッドを呼び出すことにより、加速度センサーイベントの間隔を必要に応じて調整できます。このメソッドは 1 つのパラメーター interval を受け取ります。これは、必要な更新間隔（ミリ秒単位）です。
var accl:Accelerometer;accl = new Accelerometer();accl.setRequestedUpdateInterval(1000);

加速度センサーの実際の更新間隔は、この値よりも大きかったり小さかったりする可能性があります。更新間隔が変更された場合、登録されたリスナーすべてに影響します。setRequestedUpdateInterval() メソッドを呼び出さない場合、アプリケー
ションはデバイスのデフォルトの間隔に基づいて更新を受け取ります。
加速度センサーのデータには、ある程度の誤差が生じます。最近のデータの移動平均を使用して、データを平均化することができます。例えば、次の例では、加速度センサーの最近の測定値に現在の測定値を取り込み、平均値を算出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

583

加速度センサー入力

var accl:Accelerometer;
var rollingX:Number = 0;
var rollingY:Number = 0;
var rollingZ:Number = 0;
const FACTOR:Number = 0.25;
if (Accelerometer.isSupported){
accl = new Accelerometer();accl.setRequestedUpdateInterval(200);
accl.addEventListener(AccelerometerEvent.UPDATE, updateHandler);}else{
accTextField.text = "Accelerometer feature not supported";}function updateHandler(event:AccelerometerEvent):void{
accelRollingAvg(event);
accTextField.text = rollingX + "\n" + rollingY + "\n" + rollingZ + "\n";}function accelRollingAvg(event:AccelerometerEvent):void{rollingX = (event.accelerationX * FACTOR) + (rollingX * (1 - FACTOR));rollingY = (event.accelerationY * FACTOR) + (rollingY * (1 - FACTOR));rollingZ = (event.accelerationZ * FACTOR) + (rollingZ * (1 - FACTOR));}ただし、この移動平均は、加速度センサーの更新間隔が短い場合にのみ有効です。

最終更新日 2015/10/14

584

第 35 章：AIR でのドラッグ＆ドロップ
Adobe AIR 1.0 およびそれ以降
ユーザーインターフェイスのドラッグ＆ドロップジェスチャをサポートするには、Adobe® AIR™ ドラッグ＆ドロップ APIのクラスを使用します。ここで言うジェスチャとは、ユーザーが情報をコピー、移動、またはリンクするために、オペレー
ションシステムとアプリケーションの両方を介して行う操作のことです。ドラッグアウトジェスチャは、ユーザーがコン
ポーネントまたはアプリケーションの内部からその外部へオブジェクトをドラッグしたときに発生します。ドラッグイン
ジェスチャは、ユーザーがコンポーネントまたはアプリケーションの外部からその内部へオブジェクトをドラッグしたときに発生します。
ドラッグ＆ドロップ API を使用すると、ユーザーがアプリケーション間およびアプリケーション内のコンポーネント間でデータをドラッグできるようにすることができます。サポートされている移動形式は次のとおりです。

•

ビットマップ•ファイル• HTML 形式のテキスト
•

テキスト

•

リッチテキスト形式データ

• URL
•

ファイルプロミス•

直列化されたオブジェクト•

オブジェクト参照（転送元アプリケーション内でのみ有効）

AIR でのドラッグ＆ドロップの基礎
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションでのドラッグ＆ドロップの使用に関する簡単な説明およびコード例については、Adobe Developer
Connection で次のクイックスタートの記事を参照してください。

•

データのドラッグ、コピー、ペースト（Flex）•

データのドラッグ、コピー、ペースト（Flash）

ドラッグ＆ドロップ API には、次のクラスが含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

585

AIR でのドラッグ＆ドロップ

パッケージ

クラス

flash.desktop• NativeDragManager• NativeDragOptions• Clipboard• URLFilePromise• IFilePromise
ドラッグ＆ドロップ API で使用する定数は、次のクラスで定義されます。

• NativeDragActions• ClipboardFormat• ClipboardTransferModes
flash.events

NativeDragEvent

ドラッグ＆ドロップジェスチャのステージ
ドラッグ＆ドロップジェスチャには、次の 3 つのステージがあります。
開始 ユーザーは、マウスボタンを押しながらコンポーネントからドラッグするか、またはコンポーネント内のアイテムをドラッグすることで、ドラッグ＆ドロップ操作を開始します。アイテムのドラッグ元のコンポーネントは、通常はドラッグ
イニシエータとして設計されており、nativeDragStart イベントと nativeDragComplete イベントを送出します。Adobe AIR
アプリケーションは、NativeDragManager.doDrag() メソッドを mouseDown イベントまたは mouseMove イベントに応じて呼び出してドラッグ操作を開始します。
ドラッグ操作が AIR アプリケーションの外で開始された場合、nativeDragStart イベントまたは nativeDragComplete イベントを送出するイニシエータオブジェクトはありません。
ドラッグ ユーザーは、マウスボタンを押しながら、マウスカーソルを他のコンポーネントやアプリケーション、またはデスクトップへ移動します。ドラッグが行われている間、イニシエータオブジェクトによって nativeDragUpdate イベントが送出されます（ただし、このイベントは Linux の AIR には送出されません）。ユーザーが AIR アプリケーション内のドロップ
可能なドロップターゲットの上にマウスを移動すると、そのドロップターゲットによって nativeDragEnter イベントが送出されます。イベントハンドラーでは、イベントオブジェクトを調べて、ドラッグされたデータの形式がターゲットに受け入れられるかどうかを確認できます。受け入れられる場合は、NativeDragManager.acceptDragDrop() メソッドを呼び出して、ユーザーがデータをターゲット上にドロップできるようにします。
ドラッグジェスチャがインタラクティブオブジェクトの上にある間、そのオブジェクトによって nativeDragOver イベントが送出されます。ドラッグジェスチャがインタラクティブオブジェクトから離れると、そのオブジェクトによってnativeDragExit イベントが送出されます。
ドロップ ユーザーは、対象となるドロップターゲットの上でマウスを放します。ターゲットが AIR アプリケーションまたはコンポーネントである場合、そのターゲットオブジェクトによって nativeDragDrop イベントが送出されます。イベントハ
ンドラーでは、移動されたデータにイベントオブジェクトからアクセスできます。ターゲットが AIR の外部にある場合は、オペレーティングシステムまたは他のアプリケーションによってドロップが処理されます。どちらの場合も、ドラッグ元のオブジェクトによって nativeDragComplete イベントが送出されます（AIR 内からドラッグが開始された場合）。

NativeDragManager クラスは、ドラッグインジェスチャとドラッグアウトジェスチャの両方を制御します。
NativeDragManager クラスのメンバはすべて静的であるため、このクラスのインスタンスは作成しないでください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

586

AIR でのドラッグ＆ドロップ

Clipboard オブジェクト
アプリケーションやコンポーネントの内部または外部へドラッグされたデータは、Clipboard オブジェクトに格納されます。1 つの Clipboard オブジェクトを使用すると、同じ情報を様々な形式で表現することができます。これにより、他のア
プリケーションがデータを解釈および使用できる可能性が高まります。例えば、イメージをイメージデータ、直列化されたBitmap オブジェクト、ファイルとして含めることができます。ある形式でのデータのレンダリングを、データの読み取り
後に呼び出されるレンダリング関数に任せることができます。
ドラッグジェスチャの開始後は、nativeDragEnter イベント、nativeDragOver イベント、および nativeDragDrop イベントのイ
ベントハンドラー内からのみ Clipboard オブジェクトにアクセスできます。ドラッグジェスチャの終了後に、Clipboard オ
ブジェクトの読み取りや再使用を行うことはできません。
アプリケーションオブジェクトは、参照および直列化されたオブジェクトとして移動できます。参照は、転送元アプリケー
ション内でのみ有効です。直列化されたオブジェクトは AIR アプリケーション間で有効ですが、直列化および直列化解除しても有効なオブジェクトについてのみ使用できます。直列化されたオブジェクトは、ストリングベースのデータ移動形式である Action Message Format for ActionScript 3 （AMF3）に変換されます。

Flex フレームワークの操作
Flex アプリケーションを作成する場合は、一般に Adobe® Flex™ のドラッグ＆ドロップ API を使用するほうが便利です。
AIR で Flex アプリケーションを実行する場合（AIR NativeDragManager が内部で使用されます）、Flex フレームワークでは、AIR のドラッグ＆ドロップ API と同等の機能セットが提供されます。また、制限の多いブラウザー環境でアプリケー
ションまたはコンポーネントを実行する場合に使用できる、より限定的な機能セットも用意されています。AIR クラスは、
AIR ランタイム環境の外部で実行されるコンポーネントまたはアプリケーションでは使用できません。

ドラッグアウトジェスチャのサポート
Adobe AIR 1.0 およびそれ以降
ドラッグアウトジェスチャをサポートするには、mouseDown イベントに応じて Clipboard オブジェクトを作成し、そのClipboard オブジェクトを NativeDragManager.doDrag() メソッドに渡す必要があります。これにより、アプリケーションでドラッグ元オブジェクトの nativeDragComplete イベントをリッスンし、ユーザーがジェスチャを完了または破棄した場合に実行するアクションを決定できます。

データを移動するための準備
Flash Player 9 以降、Adobe AIR 1.0 以降
データまたはオブジェクトをドラッグするための準備を行うには、Clipboard オブジェクトを作成し、移動する情報を 1 つ以上の形式で追加する必要があります。標準のデータ形式を使用すると、ネイティブなクリップボード形式に自動的に変換できるデータを渡すことができます。オブジェクトを渡すには、アプリケーション定義の形式を使用します。
移動する情報を特定の形式に変換するのに大量の計算が必要になる場合は、変換を実行するハンドラー関数の名前を指定できます。この関数は、ドロップ先のコンポーネントまたはアプリケーションが関連する形式を読み取る場合にのみ呼び出されます。
クリップボード形式について詳しくは、575 ページの「クリップボードのデータ形式」を参照してください。
次の例は、複数の形式（Bitmap オブジェクト、ネイティブなビットマップ形式、およびビットマップの読み込み元のファイルを含むファイルリスト形式）のビットマップを含む Clipboard オブジェクトを作成する方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

587

AIR でのドラッグ＆ドロップ

import flash.desktop.Clipboard;
import flash.display.Bitmap;
import flash.filesystem.File;public function createClipboard(image:Bitmap, sourceFile:File):Clipboard{var transfer:Clipboard = new Clipboard();transfer.setData("CUSTOM_BITMAP", image, true); //Flash object by value and by referencetransfer.setData(ClipboardFormats.BITMAP_FORMAT, image.bitmapData, false);transfer.setData(ClipboardFormats.FILE_LIST_FORMAT, new Array(sourceFile), false);
return transfer;}

ドラッグアウト操作の開始
Adobe AIR 1.0 およびそれ以降
ドラッグ操作を開始するには、mouseDown イベントに応じて NativeDragManager.doDrag() メソッドを呼び出します。

doDrag() メソッドは、次のパラメーターを受け取る静的メソッドです。
パラメーター

initiator

説明
ドラッグ元のオブジェクトです。このオブジェクトは、dragStart イベントと dragComplete イベントを送出します。イニシエータはインタラクティブオブジェクトである必要があります。

clipboard

移動されるデータを含む Clipboard オブジェクトです。Clipboard オブジェクトは、ドラッグ＆ドロップシーケン
スの実行中に送出された NativeDragEvent オブジェクトで参照されます。

dragImage（オプション）ドラッグ中に表示される BitmapData オブジェクトです。このイメージには、alpha 値を指定できます。（注意：Microsoft Windows では、常に一定のアルファフェードがドラッグ画像に適用されます）。

offset（オプション）ドラッグ画像とマウスのホットスポットとのオフセットを指定する Point オブジェクトです。マウス
カーソルの左上にドラッグ画像を移動するには、負の座標を使用します。オフセットを指定しない場合、ドラッグ
画像の左上隅がマウスのホットスポットの位置に配置されます。

actionsAllowed（オプション）ドラッグ操作の有効なアクション（コピー、移動、またはリンク）を指定する NativeDragOptions
オブジェクトです。引数を指定しない場合、すべてのアクションが許可されます。DragOptions オブジェクトは、

NativeDragEvent オブジェクトで参照されます。これにより、許可されたアクションがターゲットコンポーネントの目的に適合しているかどうかを、可能性があるドラッグターゲットでチェックできます。例えば、「ごみ箱」コン
ポーネントでは、移動アクションを許可するドラッグジェスチャしか受け入れられない場合があります。

次の例は、ファイルから読み込んだビットマップオブジェクトのドラッグ操作を開始する方法を示しています。この例では、イメージを読み込み、mouseDown イベントの発生時にドラッグ操作を開始します。
package{import flash.desktop.NativeDragManager;
import mx.core.UIComponent;
import flash.display.Sprite;
import flash.display.Loader;import flash.system.LoaderContext;
import flash.net.URLRequest;
import flash.geom.Point;
import flash.desktop.Clipboard;
import flash.display.Bitmap;
import flash.filesystem.File;
import flash.events.Event;import flash.events.MouseEvent;public class DragOutExample extends UIComponent Sprite {protected var fileURL:String = "app:/image.jpg";
protected var display:Bitmap;
private function init():void {最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

588

AIR でのドラッグ＆ドロップ

loadImage();}private function onMouseDown(event:MouseEvent):void {var bitmapFile:File = new File(fileURL);
var transferObject:Clipboard = createClipboard(display, bitmapFile);
NativeDragManager.doDrag(this,transferObject,display.bitmapData,
new Point(-mouseX,-mouseY));}public function createClipboard(image:Bitmap, sourceFile:File):Clipboard {var transfer:Clipboard = new Clipboard();transfer.setData("bitmap",
image,
true);// ActionScript 3 Bitmap object by value and by referencetransfer.setData(ClipboardFormats.BITMAP_FORMAT,
image.bitmapData,
false);// Standard BitmapData format
transfer.setData(ClipboardFormats.FILE_LIST_FORMAT,
new Array(sourceFile),
false);// Standard file list format
return transfer;}private function loadImage():void {var url:URLRequest = new URLRequest(fileURL);
var loader:Loader = new Loader();loader.load(url,new LoaderContext());
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoadComplete);}
private function onLoadComplete(event:Event):void {display = event.target.loader.content;
var flexWrapper:UIComponent = new UIComponent();
flexWrapper.addChild(event.target.loader.content);
addChild(flexWrapper);flexWrapper.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);}}}

ドラッグアウト移動の完了
Adobe AIR 1.0 およびそれ以降ユーザーがマウスを放してドラッグしたアイテムをドロップすると、イニシエータオブジェクトによってnativeDragComplete イベントが送出されます。イベントオブジェクトの dropAction プロパティを調べて、適切なアクションを実行することができます。例えば、アクションが NativeDragAction.MOVE である場合は、ソースアイテムを元の場所から削除できます。ユーザーは、マウスのカーソルが対象となるドロップターゲットの外側にあるときにマウスボタンを放すことで、ドラッグジェスチャを破棄できます。ドラッグマネージャーは、破棄されたジェスチャの dropAction プロパティを
NativeDragAction.NONE に設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

589

AIR でのドラッグ＆ドロップ

ドラッグインジェスチャのサポート
Adobe AIR 1.0 およびそれ以降
ドラッグインジェスチャをサポートするには、アプリケーション（より一般的にはアプリケーションのビジュアルコンポーネント）が nativeDragEnter イベントまたは nativeDragOver イベントに応答する必要があります。

一般的なドロップ操作の手順
Adobe AIR 1.0 およびそれ以降
ドロップ操作の一般的なイベントシーケンスを次に示します。

1 ユーザーがコンポーネント上にクリップボードオブジェクトをドラッグします。
2 コンポーネントによって nativeDragEnter イベントが送出されます。
3 nativeDragEnter イベントハンドラーがイベントオブジェクトを調べて、使用可能なデータ形式と許可されたアクション
を確認します。コンポーネントがドロップを処理できる場合は、NativeDragManager.acceptDragDrop() が呼び出されます。

4 NativeDragManager によって、オブジェクトがドロップ可能であることを示すようにマウスカーソルが変更されます。
5 ユーザーがコンポーネント上にオブジェクトをドロップします。
6 ドロップ先のコンポーネントによって nativeDragDrop イベントが送出されます。
7 ドロップ先のコンポーネントがイベントオブジェクト内の Clipboard オブジェクトから必要な形式でデータを読み取ります。

8 ドラッグジェスチャが AIR アプリケーション内で開始された場合、ドラッグ元のインタラクティブオブジェクトによって nativeDragComplete イベントが送出されます。ジェスチャが AIR の外部で開始された場合、フィードバックは送信されません。

ドラッグインジェスチャの確認
Adobe AIR 1.0 およびそれ以降ユーザーがビジュアルコンポーネントの境界内にクリップボードオブジェクトをドラッグすると、そのコンポーネントによって nativeDragEnter イベントと nativeDragOver イベントが送出されます。これらのイベントのハンドラーでは、イベン
トオブジェクトの clipboard プロパティと allowedActions プロパティを調べて、コンポーネントがクリップボードアイテムを受け入れ可能かどうかを確認できます。イベントハンドラーでは、コンポーネントがドロップを受け入れ可能であることを通知するために、NativeDragManager.acceptDragDrop() メソッドを呼び出して、ドロップ先のコンポーネントに参照を渡す必要があります。複数の登録済みイベントリスナーが acceptDragDrop() メソッドを呼び出した場合、リストの最後のハンドラーが優先されます。acceptDragDrop() メソッドは、マウスがドロップ先オブジェクトの境界から離れて nativeDragExit イ
ベントが発生するまで有効のままです。

doDrag() に渡される allowedActions パラメーターで複数のアクションが許可されている場合、ユーザーは、修飾キーを押す
ことで、実行するアクションを指定できます。ドラッグマネージャーは、ドロップが完了した場合に実行されるアクションをユーザーに通知するために、カーソルのイメージを変更します。目的のアクションは、NativeDragEvent オブジェクトの dropAction プロパティで報告されます。ドラッグジェスチャのアクションセットは報告のみです。移動に関連するコン
ポーネントには、適切な動作を実装する必要があります。例えば、移動アクションを完了するために、ドラッグイニシエー
タがドラッグされたアイテムを削除し、ドロップターゲットがそのアイテムを追加する場合があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

590

AIR でのドラッグ＆ドロップ

NativeDragManager クラスの dropAction プロパティを設定することで、ドラッグターゲットのドロップアクションを、実行可能な 3 つのアクションのいずれかに制限できます。ユーザーがキーボードを使用して別のアクションを選択しようとした場合、NativeDragManager によって使用不可カーソルが表示されます。ハンドラーの dropAction プロパティを
nativeDragEnter イベントと nativeDragOver イベントの両方に設定します。
次の例は、nativeDragEnter イベントまたは nativeDragOver イベントのイベントハンドラーを示しています。ドラッグ中のクリップボードにテキスト形式のデータが含まれている場合、このハンドラーはドラッグインジェスチャのみを受け入れます。
import flash.desktop.NativeDragManager;
import flash.events.NativeDragEvent;public function onDragIn(event:NativeDragEvent):void{
NativeDragManager.dropAction = NativeDragActions.MOVE;
if(event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){
NativeDragManager.acceptDragDrop(this); //'this' is the receiving component}}

ドロップの完了
Adobe AIR 1.0 およびそれ以降ユーザーがジェスチャを受け入れたインタラクティブオブジェクトにドラッグしたアイテムをドロップすると、そのインタ
ラクティブオブジェクトによって nativeDragDrop イベントが送出されます。このイベントのハンドラーは、イベントオブ
ジェクトの clipboard プロパティからデータを取得できます。
クリップボードにアプリケーション定義の形式が含まれている場合、Clipboard オブジェクトの getData() メソッドに渡される transferMode パラメーターによって、ドラッグマネージャーが参照または直列化されたオブジェクトのどちらを返すかが決定されます。
次の例は、nativeDragDrop イベントのイベントハンドラーを示しています。
import flash.desktop.Clipboard;
import flash.events.NativeDragEvent;public function onDrop(event:NativeDragEvent):void {if (event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)) {var text:String =String(event.clipboard.getData(ClipboardFormats.TEXT_FORMAT,
ClipboardTransferMode.ORIGINAL_PREFERRED));}

イベントハンドラーが呼び出されると、Clipboard オブジェクトは無効になります。オブジェクトまたはそのデータにアクセスしようとすると、エラーが発生します。

コンポーネントの外観の更新
Adobe AIR 1.0 およびそれ以降
NativeDragEvent イベントに基づいてコンポーネントの外観を更新できます。一般的なコンポーネントが様々なイベントに応じて行う変更の種類を次の表に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

591

AIR でのドラッグ＆ドロップ

イベント

nativeDragStart

説明ドラッグ元のインタラクティブオブジェクトでは、nativeDragStart イベントを使用して、そのインタラクティブオ
ブジェクトからドラッグジェスチャが開始されたことを示すビジュアルフィードバックを提供できます。

nativeDragUpdate

ドラッグ元のインタラクティブオブジェクトでは、DragUpdate イベントを使用して、ジェスチャ中にオブジェク
トの状態を更新できます（このイベントは Linux の AIR には存在しません）。

nativeDragEnter

ドロップ可能なインタラクティブオブジェクトでは、このイベントを使用して、フォーカスを受け取ったり、ドロップを受け入れ可能かどうかをビジュアルで示したりできます。

nativeDragOver

ドロップ可能なインタラクティブオブジェクトでは、このイベントを使用して、オブジェクト内でのマウスの動き（市街地図表示などの複雑なコンポーネントの「ホット」領域にマウスが移動した場合など）に対応できます。

nativeDragExit

ドロップ可能なインタラクティブオブジェクトでは、このイベントを使用して、ドラッグジェスチャが境界の外側に移動したときにオブジェクトの状態を復元できます。

nativeDragComplete

ドラッグ元のインタラクティブオブジェクトでは、このイベントを使用して、関連するデータモデルを更新し（リストからアイテムを削除するなど）、オブジェクトの外観を復元することができます。

ドラッグインジェスチャ中のマウス位置の追跡
Adobe AIR 1.0 およびそれ以降
ドラッグジェスチャがコンポーネント上にある間、そのコンポーネントによって nativeDragOver イベントが送出されます。
このイベントは数ミリ秒ごとに送出されます。また、マウスの移動時にも送出されます。nativeDragOver イベントオブジェ
クトを使用すると、コンポーネント上のマウスの位置を確認できます。これは、ドロップ先のコンポーネントがサブコン
ポーネントを含まない複雑なコンポーネントである場合に役立つことがあります。例えば、市街地図を含むビットマップを表示するアプリケーションで、ユーザーが地図上のゾーンに情報をドラッグしたときにそのゾーンを強調表示する場合は、
nativeDragOver イベントで報告されるマウス座標を使用してマップ内のマウス位置を追跡できます。

HTML でのドラッグ＆ドロップ
Adobe AIR 1.0 およびそれ以降
HTML ベースのアプリケーション（または HTMLLoader に表示される HTML）の内部または外部にデータをドラッグす
るには、HTML ドラッグ＆ドロップイベントを使用します。HTML ドラッグ＆ドロップ API を使用すると、HTML コン
テンツ内の DOM エレメントに、または DOM エレメントからドラッグできます。
注意：また、HTML コンテンツを含む HTMLLoader オブジェクトのイベントをリッスンすることで、AIR
NativeDragEvent および NativeDragManager API を使用することもできます。ただし、HTML DOM とより密接に統合されているのは HTML API です。HTML API を使用すると、デフォルト動作を制御できます。

デフォルトのドラッグ＆ドロップ動作
Adobe AIR 1.0 およびそれ以降
HTML 環境では、テキスト、イメージ、および URL に関連するドラッグ＆ドロップ操作のデフォルト動作を使用できます。デフォルト動作を使用する場合、常にこれらの種類のデータをエレメントからドラッグできます。ただし、エレメントにドラッグできるのはテキストだけです。また、ページの編集可能な領域内のエレメントにしかドラッグできません。ページの編集可能な領域間または領域内でテキストをドラッグすると、デフォルト動作によって移動アクションが実行されます。
編集不能な領域またはアプリケーションの外部から編集可能な領域にテキストをドラッグすると、デフォルト動作によってコピーアクションが実行されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

592

AIR でのドラッグ＆ドロップ

デフォルト動作を上書きするには、ドラッグ＆ドロップイベントを独自に処理します。デフォルト動作をキャンセルするには、ドラッグ＆ドロップイベントに応じて送出されたオブジェクトの preventDefault() メソッドを呼び出す必要があります。
その後、必要に応じてドロップターゲットへのデータの挿入とドラッグ元からのデータの削除を行ってから、選択したアクションを実行することができます。
デフォルトでは、ユーザーは任意のテキストを選択してドラッグしたり、イメージおよびリンクをドラッグしたりできます。

WebKit CSS プロパティである -webkit-user-select を使用すると、HTML エレメントの選択方法を制御できます。例えば、webkit-user-select を none に設定すると、エレメントのコンテンツを選択できなくなります。そのため、ドラッグすることもできません。また、-webkit-user-drag CSS プロパティを使用すると、エレメントをまとめてドラッグできるかどうかを制御できます。ただし、エレメントのコンテンツは個別に扱われます。この場合でも、ユーザーは選択したテキスト部分をドラッグできます。詳しくは、939 ページの「AIR での CSS」を参照してください。

HTML のドラッグ＆ドロップイベント
Adobe AIR 1.0 およびそれ以降
ドラッグの開始元であるイニシエータエレメントによって送出されるイベントは次のとおりです。
イベント

説明

dragstart

ユーザーがドラッグジェスチャを開始したときに送出されます。このイベントのハンドラーでは、イベントオブ
ジェクトの preventDefault() メソッドを呼び出すことで、必要に応じてドラッグを防止できます。ドラッグした
データをコピー、リンク、または移動できるかどうかを制御するには、effectAllowed プロパティを設定します。
選択されたテキスト、イメージ、およびリンクは、デフォルト動作によってクリップボードに格納されます。ただし、イベントオブジェクトの dataTransfer プロパティを使用すると、異なるデータをドラッグジェスチャに設定することができます。

drag

ドラッグジェスチャの実行中に継続的に送出されます。

dragendユーザーがマウスボタンを放してドラッグジェスチャを終了したときに送出されます。

ドラッグターゲットによって送出されるイベントは次のとおりです。
イベント

説明

dragoverドラッグジェスチャがエレメントの境界内にあるときに継続的に送出されます。このイベントのハンドラーでは、
dataTransfer.dropEffect プロパティを設定して、ユーザーがマウスボタンを放してドロップしたときに実行されるアクション（コピー、移動、またはリンク）を指定する必要があります。

dragenter

ドラッグジェスチャがエレメントの境界内に入ったときに送出されます。

dragenter イベントハンドラーで dataTransfer オブジェクトのプロパティを変更した場合、その変更は次のdragover イベントによって直ちに上書きされます。一方、dragenter イベントと最初の dragover イベントとの間には若干の遅延があります。そのため、プロパティを変更した場合、カーソルが点滅することがあります。多くの場合、両方のイベントに同じイベントハンドラーを使用できます。

dragleave

ドラッグジェスチャがエレメントの境界から離れたときに送出されます。

drop

ユーザーがエレメント上にデータをドロップしたときに送出されます。ドラッグ中のデータには、このイベントのハンドラー内からのみアクセスできます。

これらのイベントに応じて送出されたイベントオブジェクトはマウスイベントに似ています。(clientX, clientY) や (screenX,

screenY) などのマウスイベントプロパティを使用すると、マウスの位置を確認できます。
ドラッグイベントオブジェクトの最も重要なプロパティは dataTransfer です。このプロパティには、ドラッグ中のデータが含まれています。dataTransfer オブジェクト自体には、次のプロパティとメソッドがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

593

AIR でのドラッグ＆ドロップ

プロパティまたはメソッド

説明

effectAllowed

ドラッグ元で許可される効果です。通常、この値は、dragstart イベントのハンドラーによって設定されます。詳し
くは、594 ページの「HTML のドラッグ効果」を参照してください。

dropEffect

ターゲットまたはユーザーによって選択された効果です。dropEffect を dragover イベントハンドラーまたはdragenter イベントハンドラーで設定した場合、AIR によって、ユーザーがマウスを放したときに生じる効果を示す
ようにマウスカーソルが更新されます。dropEffect の設定が許可された効果のいずれかに一致しない場合、ドロップは許可されず、使用不可カーソルが表示されます。dropEffect（最新の dragover イベントまたは dragenter イベン
トに応答）を設定していない場合、ユーザーは、標準のオペレーティングシステム修飾キーを使用して許可された効果を選択できます。
最後の効果は、dragend に応じて送出されたオブジェクトの dropEffect プロパティによって報告されます。ユー
ザーが有効なターゲットの外部でマウスを放すことでドロップを破棄した場合、dropEffect が none に設定されま
す。

types

dataTransfer オブジェクトに格納されている各データ形式の MIME タイプのストリングを含む配列です。

getData(mimeType)

mimeType パラメーターで指定された形式のデータを取得します。
getData() メソッドは、drop イベントに応じて呼び出すことしかできません。

setData(mimeType)

mimeType パラメーターで指定された形式のデータを dataTransfer に追加します。複数の形式のデータを追加するには、MIME タイプごとに setData() を呼び出します。デフォルトのドラッグ動作によって dataTransfer オブジェク
トに格納されたデータはすべて消去されます。

setData() メソッドは、dragstart イベントに応じて呼び出すことしかできません。

clearData(mimeType)

mimeType パラメーターで指定された形式のデータをすべて消去します。

setDragImage(image,offsetX, offsetY)

カスタムドラッグイメージを設定します。setDragImage() メソッドは、dragstart イベントに応じてのみ、および -webkit-user-drag CSS スタイルを element に設定することで HTML エレメント全体をドラッグする場合にのみ、呼び出すことができます。image パラメーターとしては、JavaScript エレメントまたは Image オブジェクトを指定できます。

HTML ドラッグ＆ドロップの MIME タイプ
Adobe AIR 1.0 およびそれ以降
HTML ドラッグアンドドロップイベントの dataTransfer オブジェクトで使用される MIME タイプは次のとおりです。
データ形式

MIME タイプ

テキスト"text/plain"HTML"text/html"

URL"text/uri-list"

ビットマップ"image/x-vnd.adobe.air.bitmap"

ファイルリスト"application/x-vnd.adobe.air.file-list"

アプリケーション定義のストリングなど他の MIME ストリングも使用できます。ただし、他のアプリケーションでは、移動されたデータを認識または使用できない場合があります。必要な形式のデータを dataTransfer オブジェクトに追加する作
業は、開発者が行う必要があります。
重要：ドロップされたファイルにアクセスできるのは、アプリケーションサンドボックス内で実行されているコードだけです。非アプリケーションのサンドボックス内から File オブジェクトのプロパティの読み取りまたは設定を実行しようとすると、セキュリティエラーが発生します。詳しくは、598 ページの「非アプリケーションの HTML サンドボックスでのファ
イルドロップの処理」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

594

AIR でのドラッグ＆ドロップ

HTML のドラッグ効果
Adobe AIR 1.0 およびそれ以降
dataTransfer.effectAllowed プロパティを dragstart イベントのハンドラーで設定すると、ドラッグジェスチャのイニシエータで許可されるドラッグ効果を制限できます。使用できるストリング値は次のとおりです。
ストリング値

説明"none"

ドラッグ操作は許可されません。

"copy"

ドロップ先にデータがコピーされます。ドラッグ元のデータは変更されません。

"link"

ドラッグ元へのリンクバックを介してドロップ先との間でデータが共有されます。

"move”

ドロップ先にデータがコピーされ、ドラッグ元のデータが削除されます。

"copyLink"

データをコピーまたはリンクすることができます。

"copyMove"

データをコピーまたは移動することができます。

"linkMove"

データをリンクまたは移動することができます。

"all"

データをコピー、移動、またはリンクすることができます。デフォルト動作を使用しない場合は、All がデフォルトの効果になります。

ドラッグジェスチャのターゲットでは、dataTransfer.dropEffect プロパティを設定することで、ユーザーがドロップを完了したときに実行されるアクションを指定できます。ドロップ効果が許可されたアクションのいずれかである場合は、該当する
コピーカーソル、移動カーソル、またはリンクカーソルが表示されます。許可されたアクションでない場合は、使用不可
カーソルが表示されます。ターゲットでドロップ効果が設定されていない場合、ユーザーは修飾キーを使用して許可されたアクションを選択できます。

dropEffect の値を dragover イベントと dragenter イベントの両方のハンドラーで設定します。
function doDragStart(event) {event.dataTransfer.setData("text/plain","Text to drag");
event.dataTransfer.effectAllowed = "copyMove";}function doDragOver(event) {event.dataTransfer.dropEffect = "copy";}function doDragEnter(event) {event.dataTransfer.dropEffect = "copy";}

注意：dropEffect プロパティを dragenter のハンドラーで必ず設定する必要がありますが、次の dragover イベントによってこのプロパティがデフォルト値にリセットされることに注意してください。両方のイベントに対応する dropEffect を設定します。

HTML エレメントからのデータのドラッグ
Adobe AIR 1.0 およびそれ以降
デフォルト動作を使用すると、HTML ページ内の大部分のコンテンツをドラッグでコピーすることができます。CSS プロ
パティである -webkit-user-select と -webkit-user-drag を使用すると、ドラッグが許可されるコンテンツを制御できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

595

AIR でのドラッグ＆ドロップ

dragstart イベントのハンドラーでデフォルトのドラッグアウト動作を上書きします。イベントオブジェクトの dataTransfer
プロパティの setData() メソッドを呼び出して、ドラッグジェスチャに独自のデータを追加します。
デフォルト動作を使用しない場合にソースオブジェクトでサポートされるドラッグ効果を指定するには、dragstart イベントに応じて送出されたイベントオブジェクトの dataTransfer.effectAllowed プロパティを設定します。任意の組み合わせの効果を選択できます。例えば、ソースエレメントでコピー効果とリンク効果の両方をサポートする場合は、このプロパティを"copyLink" に設定します。

ドラッグされるデータの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
dragstart イベントのハンドラーで、dataTransfer プロパティを使用してドラッグジェスチャのデータを追加します。MIME
タイプと移動するデータを dataTransfer.setData() メソッドに渡して、クリップボードにデータを格納します。
例えば、imageOfGeorge という ID を持つイメージエレメントがアプリケーションに含まれている場合は、次のようなdragstart イベントハンドラーを使用できます。この例では、George の写真を複数のデータ形式で追加しています。これにより、ドラッグされたデータを他のアプリケーションで使用できる可能性が高まります。
function dragStartHandler(event){
event.dataTransfer.effectAllowed = "copy";
var dragImage = document.getElementById("imageOfGeorge");var dragFile = new air.File(dragImage.src);
event.dataTransfer.setData("text/plain","A picture of George");event.dataTransfer.setData("image/x-vnd.adobe.air.bitmap", dragImage);
event.dataTransfer.setData("application/x-vnd.adobe.air.file-list",
new Array(dragFile));}

注意：dataTransfer オブジェクトの setData() メソッドを呼び出した場合、デフォルトのドラッグ＆ドロップ動作によってデータが追加されることはありません。

HTML エレメントへのデータのドラッグ
Adobe AIR 1.0 およびそれ以降
デフォルト動作では、ページの編集可能な領域にテキストをドラッグすることしかできません。エレメントの開始タグにcontenteditable 属性を追加することで、エレメントとその子が編集可能であることを指定できます。また、ドキュメントオ
ブジェクトの designMode プロパティを "on" に設定することで、ドキュメント全体を編集可能にすることもできます。
ドラッグされたデータを受け入れ可能なエレメントの dragenter イベント、dragover イベント、および drop イベントを処理することで、ページ上での代替的なドラッグイン動作をサポートできます。

ドラッグインの有効化
Adobe AIR 1.0 およびそれ以降
ドラッグインジェスチャを処理するには、最初にデフォルト動作をキャンセルする必要があります。ドロップターゲットとして使用する HTML エレメントの dragenter イベントと dragover イベントをリッスンします。これらのイベントのハンド
ラーで、送出されたイベントオブジェクトの preventDefault() メソッドを呼び出します。デフォルト動作をキャンセルすると、編集不能な領域にドロップできるようになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

596

AIR でのドラッグ＆ドロップ

ドロップされたデータの取得
Adobe AIR 1.0 およびそれ以降ドロップされたデータには、ondrop イベントのハンドラーからアクセスできます。
function doDrop(event){
droppedText = event.dataTransfer.getData("text/plain");}

読み取るデータ形式の MIME タイプを dataTransfer.getData() メソッドに渡して、クリップボードのデータを読み取ります。

dataTransfer オブジェクトの types プロパティを使用すると、使用可能なデータ形式を確認できます。types 配列には、使用可能な各形式の MIME タイプのストリングが含まれています。

dragenter イベントまたは dragover イベントのデフォルト動作をキャンセルする場合は、ドロップされたデータをドキュ
メント内の適切な場所に挿入する必要があります。マウスの位置をエレメント内の挿入場所に変換する API は存在しません。この制約により、挿入タイプのドラッグジェスチャの実装が困難になります。

例：デフォルトの HTML ドラッグインジェスチャの上書き
Adobe AIR 1.0 およびそれ以降
この例では、ドロップされたアイテムで使用可能な各データ形式を示すテーブルを表示するドロップターゲットを実装します。
アプリケーション内でテキスト、リンク、およびイメージをドラッグできるようにするために、デフォルト動作が使用されます。この例では、ドロップターゲットとなる div エレメントのデフォルトのドラッグイン動作を上書きします。編集不能な領域がドラッグインジェスチャを受け入れられるようにするための重要な手順は、dragenter イベントおよび dragover イベ
ントに応じて送出されたイベントオブジェクトの preventDefault() メソッドを呼び出すことです。drop イベントに応じて、ハンドラーは移動されたデータを HTML 行エレメントに変換し、この行を表示用のテーブルに挿入します。
<html><head><title>Drag-and-drop</title><script language="javascript" type="text/javascript" src="AIRAliases.js"></script><script language="javascript">function init(){var target = document.getElementById('target');target.addEventListener("dragenter", dragEnterOverHandler);target.addEventListener("dragover", dragEnterOverHandler);target.addEventListener("drop", dropHandler);var source = document.getElementById('source');source.addEventListener("dragstart", dragStartHandler);source.addEventListener("dragend", dragEndHandler);
emptyRow = document.getElementById("emptyTargetRow");}function dragStartHandler(event){
event.dataTransfer.effectAllowed = "copy";}function dragEndHandler(event){
air.trace(event.type + ": " + event.dataTransfer.dropEffect);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

597

AIR でのドラッグ＆ドロップ

function dragEnterOverHandler(event){
event.preventDefault();}
var emptyRow;function dropHandler(event){for(var prop in event){
air.trace(prop + " = " + event[prop]);}var row = document.createElement('tr');
row.innerHTML = "<td>" + event.dataTransfer.getData("text/plain") + "</td>" +"<td>" + event.dataTransfer.getData("text/html") + "</td>" +"<td>" + event.dataTransfer.getData("text/uri-list") + "</td>" +"<td>" + event.dataTransfer.getData("application/x-vnd.adobe.air.file-list") +"</td>";
var imageCell = document.createElement('td');if((event.dataTransfer.types.toString()).search("image/x-vnd.adobe.air.bitmap") > -1){
imageCell.appendChild(event.dataTransfer.getData("image/x-vnd.adobe.air.bitmap"));}row.appendChild(imageCell);var parent = emptyRow.parentNode;parent.insertBefore(row, emptyRow);}</script></head><body onLoad="init()" style="padding:5px"><div><h1>Source</h1><p>Items to drag:</p><ul id="source"><li>Plain text.</li><li>HTML <b>formatted</b> text.</li><li>A <a href="http://www.adobe.com">URL.</a></li><li><img src="icons/AIRApp_16.png" alt="An image"/></li><li style="-webkit-user-drag:none;">Uses "-webkit-user-drag:none" style.
</li><li style="-webkit-user-select:none;">Uses "-webkit-user-select:none" style.
</li>
</ul>
</div><div id="target" style="border-style:dashed;"><h1 >Target</h1><p>Drag items from the source list (or elsewhere).</p><table id="displayTable" border="1"><tr><th>Plain text</th><th>Html text</th><th>URL</th><th>File list</th><th>Bitmap Data</th></tr><tr
id="emptyTargetRow"><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr></table></div></div></body></html>最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

598

AIR でのドラッグ＆ドロップ

非アプリケーションの HTML サンドボックスでのファイルドロップの処理Adobe AIR 1.0 およびそれ以降
AIR アプリケーションにファイルをドラッグしたときに生成される File オブジェクトに、非アプリケーションのコンテンツ
からアクセスすることはできません。また、これらの File オブジェクトのいずれかをサンドボックスブリッジ経由でアプリ
ケーションコンテンツに渡すこともできません（オブジェクトのプロパティには、直列化時にアクセスする必要があります）。ただし、HTMLLoader オブジェクトの AIR nativeDragDrop イベントをリッスンすることで、この場合でもアプリ
ケーションにファイルをドロップできます。
ユーザーが非アプリケーションのコンテンツをホストするフレームにファイルをドロップした場合、通常、ドロップイベン
トは子から親へと伝達されません。ただし、HTMLLoader（AIR アプリケーション内のすべての HTML コンテンツのコンテナ）によって送出されたイベントは HTML イベントフローの一部ではないため、アプリケーションコンテンツのドロップイベントを受け取ることは可能です。
親ドキュメントでは、ファイルドロップイベントを受け取るために、window.htmlLoader によって提供された参照を使用して、HTMLLoader オブジェクトにイベントリスナーを追加します。
window.htmlLoader.addEventListener("nativeDragDrop",function(event){
var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT);
air.trace(filelist[0].url);});

次の例では、リモートサンドボックス（http://localhost/）に子ページを読み込む親ドキュメントを使用しています。親ドキュメントでは、HTMLLoader オブジェクトの nativeDragDrop イベントをリッスンし、ファイルの URL をトレースします。
<html><head><title>Drag-and-drop in a remote sandbox</title><script language="javascript" type="text/javascript" src="AIRAliases.js"></script><script language="javascript">window.htmlLoader.addEventListener("nativeDragDrop",function(event){
var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT);
air.trace(filelist[0].url);});</script></head><body><iframe src="child.html"
sandboxRoot="http://localhost/"
documentRoot="app:/"frameBorder="0" width="100%" height="100%"></iframe></body></html>子ドキュメントでは、HTML dragenter および dragover のイベントハンドラーで Event オブジェクトの preventDefault() メ
ソッドを呼び出すことで、有効なドロップターゲットを提供する必要があります。そうしないとドロップイベントが発生しません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

599

AIR でのドラッグ＆ドロップ<html><head><title>Drag and drop target</title><script language="javascript" type="text/javascript">function preventDefault(event){
event.preventDefault();}</script></head><body ondragenter="preventDefault(event)" ondragover="preventDefault(event)"><div><h1>Drop Files Here</h1></div></body></html>ファイルプロミスのドロップ
Adobe AIR 2 以降
ファイルプロミスはドラッグ＆ドロップクリップボード形式です。これにより、ユーザーは、まだ存在しないファイルを

AIR アプリケーションからドラッグできます。例えば、ファイルプロミスを使用すると、アプリケーションでプロキシアイ
コンをデスクトップフォルダーにドラッグできます。プロキシアイコンは、ある URL に存在することがわかっているファ
イルまたはデータを表します。アイコンをドロップすると、ランタイムによってデータがダウンロードされ、ドロップ位置にファイルが書き込まれます。

AIR アプリケーションの URLFilePromise クラスを使用すると、ある URL でアクセス可能なファイルをドラッグ＆ドロッ
プできます。URLFilePromise 実装は、AIR 2 SDK の一部として aircore ライブラリで提供されています。SDK
frameworks/libs/air ディレクトリにある aircore.swc ファイルまたは aircore.swf ファイルのどちらかを使用してください。
または、ランタイム flash.desktop パッケージに定義されている IFilePromise インターフェイスを使用して、独自のファイ
ルプロミスロジックを実装することもできます。
概念上、ファイルプロミスは、クリップボード上のデータハンドラー関数を使用した遅延レンダリングに似ています。ファ
イルをドラッグ＆ドロップするときは、遅延レンダリングの代わりにファイルプロミスを使用します。遅延レンダリングテ
クニックを使用すると、データが生成またはダウンロードされるときに、ドラッグ操作が一時停止する場合があり、望まし
くありません。遅延レンダリングは、ファイルプロミスがサポートされていないコピー＆ペースト操作に使用してください。
ファイルプロミス使用時の制限
ドラッグ＆ドロップクリップボードに配置できる他のデータ形式と比較して、ファイルプロミスには次の制限があります。

•

ファイルプロミスは AIR アプリケーションからドラッグするのみで、AIR アプリケーションにドロップすることはできません。

•

ファイルプロミスは、すべてのオペレーティングシステムでサポートされているわけではありません。

Clipboard.supportsFilePromise プロパティを使用して、ホストシステムでファイルプロミスがサポートされているかどうかをテストしてください。ファイルプロミスがサポートされていないシステムでは、ファイルデータをダウンロードまたは生成するための代替のメカニズムを提供する必要があります。

•

ファイルプロミスは、コピー＆ペーストクリップボード（Clipboard.generalClipboard）では使用できません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

600

AIR でのドラッグ＆ドロップ

関連項目

flash.desktop.IFilePromise
air.desktop.URLFilePromise

リモートファイルのドロップ
Adobe AIR 2 以降
URL 上のファイルまたはデータを表すファイルプロミスオブジェクトの作成には、URLFilePromise クラスを使用します。
FILE_PROMISE_LIST クリップボード形式を使用して、1 つまたは複数のファイルプロミスオブジェクトをクリップボードに追加します。次の例では、http://www.example.com/foo.txt にある単一のファイルがダウンロードされ、ドロップ位置に bar.txt という名前で保存されます。リモートとローカルのファイル名を一致させる必要はありません。
if( Clipboard.supportsFilePromise ){var filePromise:URLFilePromise = new URLFilePromise();filePromise.request = new URLRequest("http://example.com/foo.txt");
filePromise.relativePath = "bar.txt";
var fileList:Array = new Array( filePromise );var clipboard:Clipboard = new Clipboard();clipboard.setData( ClipboardFormats.FILE_PROMISE_LIST_FORMAT, fileList );NativeDragManager.doDrag( dragSource, clipboard );}クリップボードに割り当てられている配列にファイルプロミスオブジェクトをさらに追加すると、一度に複数のファイルをドラッグできます。また、relativePath プロパティでサブディレクトリを指定して、操作に含まれているファイルの一部または全部をドロップ位置と相対的なサブフォルダーに配置することもできます。
次の例は、複数のファイルプロミスを含むドラッグ操作の開始方法を示しています。この例では、html ページ
article.html が、2 つのリンクされたイメージファイルと共にファイルプロミスとしてクリップボードに配置されます。イ
メージは images サブフォルダーにコピーされ、相対リンクが維持されます。
if( Clipboard.supportsFilePromise ){//Create the promise objects
var filePromise:URLFilePromise = new URLFilePromise();filePromise.request = new URLRequest("http://example.com/article.html");
filePromise.relativePath = "article.html";
var image1Promise:URLFilePromise = new URLFilePromise();image1Promise.request = new URLRequest("http://example.com/images/img_1.jpg");
image1Promise.relativePath = "images/img_1.html";
var image2Promise:URLFilePromise = new URLFilePromise();image2Promise.request = new URLRequest("http://example.com/images/img_2.jpg");
image2Promise.relativePath = "images/img_2.jpg";//Put the promise objects onto the clipboard inside an arrayvar fileList:Array = new Array( filePromise, image1Promise, image2Promise );var clipboard:Clipboard = new Clipboard();clipboard.setData( ClipboardFormats.FILE_PROMISE_LIST_FORMAT, fileList );//Start the drag operation
NativeDragManager.doDrag( dragSource, clipboard );}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

601

AIR でのドラッグ＆ドロップ

IFilePromise インターフェイスの実装
Adobe AIR 2 以降
URLFilePromise オブジェクトを使用してアクセスできないリソースにファイルプロミスを提供するために、IFilePromise
インターフェイスをカスタムクラスに実装できます。IFilePromise インターフェイスは、ファイルプロミスがドロップされたときにファイルに書き込まれるデータにアクセスするために AIR ランタイムで使用するメソッドおよびプロパティを定義します。

IFilePromise 実装は、ファイルプロミスにデータを提供する別のオブジェクトを AIR ランタイムに渡します。このオブジェクトは IDataInput インターフェイスを実装する必要があります。AIR ランタイムでは、これを使用してデータを読み取ります。例えば、IFilePromise を実装する URLFilePromise クラスでは、URLStream オブジェクトをデータプロバイ
ダーとして使用します。

AIR では、データを同期でも非同期でも読み取ることができます。IFilePromise 実装では、isAsync プロパティで対応する値を返すことにより、どのアクセスモードがサポートされているかを報告します。非同期データアクセスが提供されている
場合、データプロバイダーオブジェクトは IEventDispatcher インターフェイスを実装し、open、progress、complete などの必要なイベントを送出しなければなりません。
ファイルプロミスのデータプロバイダーとして使用できるのは、カスタムクラス、または次のいずれかのビルトインクラスです。

• ByteArray（同期）• FileStream（同期または非同期）• Socket（非同期）• URLStream（非同期）
IFilePromise インターフェイスを実装するには、次の関数およびプロパティにコードを指定する必要があります。

• open():IDataInput — プロミスファイルのデータの読み取り元であるデータプロバイダーオブジェクトを返します。この
オブジェクトは、IDataInput インターフェイスを実装する必要があります。データが非同期で提供されている場合、オブジェクトでは IEventDispatcher インターフェイスも実装し、必要なイベントを送出する必要があります（603 ページの「ファイルプロミスでの非同期データプロバイダーの使用」を参照）。

• get relativePath():String — 作成されたファイルのパスを、ファイル名も含めて指定します。パスは、ユーザーがドラッグ＆ドロップ操作で選択したドロップ位置と相対的に解決されます。ホストオペレーティングシステムに適切な区切り文字がパスで使用されていることを確認するには、ディレクトリを含むパスを指定するときに File.separator 定数を使用します。setter 関数を追加するか、コンストラクターパラメーターを使用すると、実行時にパスを設定できます。

• get isAsync():Boolean — データプロバイダーオブジェクトが非同期、同期のどちらでデータを提供するかを AIR ランタ
イムに通知します。

• close():void — データが完全に読み込まれたとき（または、エラーにより読み取りを続行できない場合）に、ランタイム
によって呼び出されます。この関数を使用するとリソースをクリーンアップできます。

• reportError( e:ErrorEvent ):void — データの読み取りエラーが発生したときに、ランタイムによって呼び出されます。
ファイルプロミスを含むドラッグ＆ドロップ操作中に、IFilePromise のすべてのメソッドがランタイムによって呼び出されます。通常は、アプリケーションロジックがこれらのメソッドを直接呼び出すことはありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

602

AIR でのドラッグ＆ドロップ

ファイルプロミスでの同期データプロバイダーの使用
Adobe AIR 2 以降
IFilePromise インターフェイスを実装する最も簡単な方法は、ByteArray や同期 FileStream など、同期のデータプロバイ
ダーオブジェクトを使用することです。次の例では、ByteArray オブジェクトが作成され、データが指定されて、open() メ
ソッドを呼び出したときに返されます。
package{import flash.desktop.IFilePromise;import flash.events.ErrorEvent;import flash.utils.ByteArray;
import flash.utils.IDataInput;
public class SynchronousFilePromise implements IFilePromise{
private const fileSize:int = 5000; //size of file data
private var filePath:String = "SynchronousFile.txt";
public function get relativePath():String{
return filePath;}public function get isAsync():Boolean{
return false;}
public function open():IDataInput{
var fileContents:ByteArray = new ByteArray();//Create some arbitrary data for the filefor( var i:int = 0; i < fileSize; i++ ){fileContents.writeUTFBytes( 'S' );}//Important: the ByteArray is read from the current position
fileContents.position = 0;
return fileContents;}
public function close():void{//Nothing needs to be closed in this case.
}public function reportError(e:ErrorEvent):void{
trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text );}}}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

603

AIR でのドラッグ＆ドロップ

実際には、同期ファイルプロミスの用途は限られています。データ量が少ない場合は、一時ディレクトリに同じくらい簡単にファイルを作成し、通常のファイルリスト配列をドラッグ＆ドロップクリップボードに追加できます。一方で、データ量が多い場合や、データを作成するとコンピューター処理上の負荷が高い場合は、同期プロセスに長時間かかります。同期プロセスが長引くと、UI の更新がかなり長時間に渡ってブロックされ、アプリケーションが応答していないように見える場合があります。この問題を回避するために、タイマーによって制御される非同期データプロバイダーを作成できます。

ファイルプロミスでの非同期データプロバイダーの使用
Adobe AIR 2 以降
非同期データプロバイダーオブジェクトを使用するときは、IFilePromise の isAsync プロパティを true に設定し、open() メ
ソッドによって返されるオブジェクトに IEventDispatcher インターフェイスを実装する必要があります。様々なビルトイ
ンオブジェクトをデータプロバイダーとして使用できるように、ランタイムは複数の代替イベントを監視します。例えば、

progress イベントは FileStream オブジェクトおよび URLStream オブジェクトによって送出され、socketData イベントはSocket オブジェクトによって送出されます。ランタイムは、これらすべてのオブジェクトから適切なイベントを監視します。
次の各イベントは、データプロバイダーオブジェクトからのデータの読み取りプロセスを制御します。

• Event.OPEN — データソースの準備が完了していることをランタイムに通知します。
• ProgressEvent.PROGRESS — データが使用可能であることをランタイムに通知します。ランタイムは、使用可能なデータの量をデータプロバイダーオブジェクトから読み取ります。

• ProgressEvent.SOCKET_DATA — データが使用可能であることをランタイムに通知します。socketData イベントはソケットベースのオブジェクトによって送出されます。その他のオブジェクトタイプについては、progress イベントを送出する必要があります（ランタイムは両方のイベントを監視してデータの読み取りが可能なタイミングを検出します）。

• Event.COMPLETE — データがすべて読み込まれたことをランタイムに通知します。
• Event.CLOSE — データがすべて読み込まれたことをランタイムに通知します（この場合、ランタイムは close とcomplete の両方を監視します）。

• IOErrorEvent.IOERROR — データの読み取りエラーが発生したことをランタイムに通知します。ランタイムはファイル作成を中止し、IFilePromise の close() メソッドを呼び出します。
• SecurityErrorEvent.SECURITY_ERROR — セキュリティエラーが発生したことをランタイムに通知します。ランタ
イムはファイル作成を中止し、IFilePromise の close() メソッドを呼び出します。
• HTTPStatusEvent.HTTP_STATUS — 使用可能なデータがエラーメッセージ（404 ページなど）ではなく必要なコンテンツを表していることを確認するために、httpResponseStatus と共にランタイムによって使用されます。このイベント
は HTTP プロトコルに基づくオブジェクトによって送出されます。

• HTTPStatusEvent.HTTP_RESPONSE_STATUS — 使用可能なデータが必要なコンテンツを表していることを確認するために、httpStatus と共にランタイムによって使用されます。このイベントは HTTP プロトコルに基づくオブジェクト
によって送出されます。
データプロバイダーでは、これらのイベントが次の順序で送出されます。

1 open イベント
2 progress イベントまたは socketData イベント
3 complete イベントまたは close イベント
注意：ビルトインオブジェクト、FileStream、Socket、および URLStream では、該当するイベントが自動的に送出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

604

AIR でのドラッグ＆ドロップ

次の例では、カスタムの非同期データプロバイダーを使用してファイルプロミスを作成します。データプロバイダークラス
によって ByteArray が拡張され（IDataInput サポート用）、IEventDispatcher インターフェイスが実装されます。タイ
マーイベントごとに、オブジェクトではデータのグループを生成し、データが使用可能であることをランタイムに通知する

progress イベントを送出します。十分なデータが生成されたら、オブジェクトは complete イベントを送出します。
package{import flash.events.Event;import flash.events.EventDispatcher;import flash.events.IEventDispatcher;import flash.events.ProgressEvent;import flash.events.TimerEvent;import flash.utils.ByteArray;
import flash.utils.Timer;[Event(name="open", type="flash.events.Event.OPEN")][Event(name="complete", type="flash.events.Event.COMPLETE")][Event(name="progress", type="flash.events.ProgressEvent")][Event(name="ioError", type="flash.events.IOErrorEvent")][Event(name="securityError", type="flash.events.SecurityErrorEvent")]
public class AsyncDataProvider extends ByteArray implements IEventDispatcher{
private var dispatcher:EventDispatcher = new EventDispatcher();
public var fileSize:int = 0; //The number of characters in the fileprivate const chunkSize:int = 1000; //Amount of data written per event
private var dispatchDataTimer:Timer = new Timer( 100 );private var opened:Boolean = false;
public function AsyncDataProvider(){super();
dispatchDataTimer.addEventListener( TimerEvent.TIMER, generateData );}public function begin():void{
dispatchDataTimer.start();}public function end():void{dispatchDataTimer.stop();}private function generateData( event:Event ):void{if( !opened ){var open:Event = new Event( Event.OPEN );dispatchEvent( open );opened = true;}else if( position + chunkSize < fileSize ){for( var i:int = 0; i <= chunkSize; i++ ){writeUTFBytes( 'A' );}//Set position back to the start of the new data
this.position -= chunkSize;
var progress:ProgressEvent =new ProgressEvent( ProgressEvent.PROGRESS, false, false, bytesAvailable, bytesAvailable +chunkSize);dispatchEvent( progress )最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

605

AIR でのドラッグ＆ドロップ

}
else
{
var complete:Event = new Event( Event.COMPLETE );dispatchEvent( complete );}}//IEventDispatcher implementation
public function addEventListener(type:String, listener:Function, useCapture:Boolean=false,priority:int=0, useWeakReference:Boolean=false):void{dispatcher.addEventListener( type, listener, useCapture, priority, useWeakReference );}public function removeEventListener(type:String, listener:Function, useCapture:Boolean=false):void{dispatcher.removeEventListener( type, listener, useCapture );}public function dispatchEvent(event:Event):Boolean{
return dispatcher.dispatchEvent( event );}public function hasEventListener(type:String):Boolean{
return dispatcher.hasEventListener( type );}public function willTrigger(type:String):Boolean{
return dispatcher.willTrigger( type );}}}注意：この例の AsyncDataProvider クラスでは、ByteArray が拡張されるため、EventDispatcher も同時に拡張することはできません。IEventDispatcher インターフェイスを実装するには、内部の EventDispatcher オブジェクトを使用して、その内部オブジェクトに対して IEventDispatcher メソッド呼び出しを転送します。また、EventDispatcher を拡張してIDataInput を実装（または両方のインターフェイスを実装）することもできます。
非同期の IFilePromise 実装は、同期の実装とほぼ同じです。主な違いは、isAsync が true を返し、open() メソッドが非同期
データオブジェクトを返すことです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

606

AIR でのドラッグ＆ドロップ

package{import flash.desktop.IFilePromise;import flash.events.ErrorEvent;import flash.events.EventDispatcher;import flash.utils.IDataInput;
public class AsynchronousFilePromise extends EventDispatcher implements IFilePromise{
private var fileGenerator:AsyncDataProvider;private const fileSize:int = 5000; //size of file data
private var filePath:String = "AsynchronousFile.txt";
public function get relativePath():String{
return filePath;}public function get isAsync():Boolean{
return true;}
public function open():IDataInput{
fileGenerator = new AsyncDataProvider();
fileGenerator.fileSize = fileSize;
fileGenerator.begin();return fileGenerator;}
public function close():void{
fileGenerator.end();}public function reportError(e:ErrorEvent):void{
trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text );}}}最終更新日 2015/10/14

607

第 36 章：メニューの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
コンテキストメニュー API のクラスを使用して、Web ベースの Flex および Flash Player アプリケーションのコンテキスト
メニューを変更できます。
ネイティブメニュー API のクラスを使用して、Adobe® AIR® でアプリケーション、ウィンドウ、コンテキストおよびポップアップの各メニューを定義できます。

メニューの基本
Flash Player 9 以降、Adobe AIR 1.0 以降
AIR アプリケーションでのネイティブメニューの作成に関する簡単な説明およびコード例については、Adobe Developer
Connection で次のクイックスタートの記事を参照してください。

• Adding native menus to an AIR application（Flex）• Adding native menus to an AIR application（Flash）
ネイティブメニュークラスを使用すると、アプリケーションを実行しているオペレーティングシステムのネイティブメ
ニュー機能にアクセスすることができます。NativeMenu オブジェクトは、アプリケーションメニュー（Mac OS X で使用可能）、ウィンドウメニュー（Windows および Linux で使用可能）、コンテキストメニューおよびポップアップメニューに使用できます。

AIR の外部で、コンテキストメニュークラスを使用することにより、アプリケーションでユーザーがオブジェクトを右クリックまたは Command キーを押しながらクリックしたときに Flash Player で自動的に表示するコンテキストメニューを変更できます（自動コンテキストメニューは AIR アプリケーションでは表示されません）。

メニュークラスFlash Player 9 以降、Adobe AIR 1.0 以降
メニュークラスには、次のクラスが含まれます。
パッケージ

クラス

flash.display• NativeMenu• NativeMenuItem

flash.ui• ContextMenu• ContextMenuItem

flash.events• Event• ContextMenuEvent

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

608

メニューの操作

メニューのタイプ
Flash Player 9 以降、Adobe AIR 1.0 以降
AIR では、次のタイプのメニューをサポートしています。
コンテキストメニュー コンテキストメニューは、SWF コンテンツ内のインタラクティブオブジェクトまたは HTML コン
テンツ内のドキュメントエレメントを右クリックまたは Command キーを押しながらクリックすると開くメニューです。

Flash Player ランタイムでは、コンテキストメニューが自動的に表示されます。ContextMenu および ContextMenuItem
クラスを使用して、メニューに独自のコマンドを追加できます。また、ビルトインコマンドの一部（全部ではなく）を削除できます。

AIR ランタイムでは、NativeMenu クラスまたは ContextMenu クラスを使用して、コンテキストメニューを作成できます。AIR の HTML コンテンツでは、Webkit HTML や JavaScript の API を使用して、コンテキストメニューを HTML エ
レメントに追加できます。
アプリケーション メニュー（AIR のみ）アプリケーションメニューは、アプリケーション全体に適用されるグローバルなメ
ニューです。アプリケーションメニューは Mac OS X でサポートされ、Windows および Linux ではサポートされません。
Mac OS X では、オペレーティングシステムで自動的にアプリケーションメニューが作成されます。AIR のメニュー API を使用すると、標準のメニューにアイテムやサブメニューを追加したり、既存のメニューコマンドを処理するリスナーを追加したり、既存のアイテムを削除したりすることができます。
ウィンドウメニュー（AIR のみ）ウィンドウメニューは、1 つのウィンドウに関連付けられるメニューで、タイトルバーの下に表示されます。NativeMenu オブジェクトを作成して NativeWindow オブジェクトの menu プロパティに割り当てることで、ウィンドウにメニューを追加できます。ウィンドウメニューは Windows および Linux オペレーティングシステム
でサポートされ、Mac OS X ではサポートされません。ネイティブウィンドウメニューは、システムクロムを持つウィンド
ウでのみ使用できます。
ドックおよびシステムトレイアイコンメニュー（AIR のみ）これらのアイコンメニューは、コンテキストメニューに似ており、Mac OS X の場合はドック内、Windows および Linux の場合はタスクバーの通知領域内に表示されるアプリケーショ
ンアイコンに割り当てられます。ドックおよびシステムトレイアイコンメニューでは、NativeMenu クラスが使用されます。Mac OS X では、メニューのアイテムは、オペレーティングシステムの標準のアイテムの上に追加されます。

Windows または Linux では、標準のメニューはありません。
ポップアップメニュー（AIR のみ）AIR のポップアップメニューはコンテキストメニューに似ていますが、特定のアプリ
ケーションオブジェクトまたはコンポーネントに必ずしも関連付けられません。ポップアップメニューは、任意のNativeMenu オブジェクトの display() メソッドを呼び出すことで、ウィンドウ内の任意の位置に表示できます。
カスタムメニュー ネイティブメニューは、完全にオペレーティングシステムによって描画されるため、Flash や HTML のレンダリングモデル内に含めることはできません。ネイティブメニューを使用する代わりに、MXML、ActionScript または JavaScript（AIR の場合）を使用して独自のカスタム非ネイティブメニューをいつでも作成できます。そのようなメニューは、アプリケーションコンテンツ内で完全にレンダリングされる必要があります。

Flex メニュー Adobe® Flex™ フレームワークには、一連の Flex メニューコンポーネントが用意されています。Flex メ
ニューは、オペレーティングシステムではなくランタイムによって描画されるメニューであり、ネイティブメニューではありません。Flex メニューコンポーネントは、システムクロムを持たない Flex ウィンドウに使用することができます。Flex
メニューコンポーネントを使用するもう 1 つのメリットは、メニューを MXML 形式で宣言的に指定できることです。Flex
フレームワークを使用する場合、ウィンドウメニューには、ネイティブクラスではなく Flex メニュークラスを使用します。
デフォルトメニュー（AIR のみ）
オペレーティングシステムまたは AIR ビルトインクラスで、次のデフォルトのメニューが提供されます。

• Mac OS X のアプリケーションメニュー• Mac OS X のドックアイコンメニュー

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

609

メニューの操作• HTML コンテンツの選択されたテキストおよびイメージに対応するコンテキストメニュー• TextField オブジェクト（または TextField を拡張するオブジェクト）の選択されたテキストに対応するコンテキストメ
ニュー

コンテキストメニューについて
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF コンテンツでは、InteractiveObject を継承するオブジェクトの contextMenu プロパティにメニューオブジェクトを割り当てることによって、そのオブジェクトにコンテキストメニューを含めることができます。「進む」、「戻る」、「印刷」、「品質」、「ズーム」などのいくつかのコマンドは、デフォルトで組み込まれています。AIR ランタイムでは、contextMenu に割
り当てることができるメニューオブジェクトのタイプは、NativeMenu または ContextMenu です。Flash Player ランタイ
ムでは、ContextMenu クラスだけを使用できます。

ContextMenu クラスと ContextMenuItem クラスを使用する場合、ネイティブメニューイベントまたはコンテキストメ
ニューイベントをリッスンできます。両方のクラスが送出されます。ContextMenuEvent オブジェクトのプロパティの利
点の 1 つは、contextMenuOwner はメニューが関連付けられているオブジェクトを識別し、mouseTarget はメニューを開くためにクリックされたオブジェクトを識別する点です。この情報は、NativeMenuEvent オブジェクトからは使用できません。
次の例では、Sprite を作成し、単純な編集コンテキストメニューを追加します。
var sprite:Sprite = new Sprite();sprite.contextMenu = createContextMenu()
private function createContextMenu():ContextMenu{
var editContextMenu:ContextMenu = new ContextMenu();
var cutItem:ContextMenuItem = new ContextMenuItem("Cut")
cutItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCutCommand);editContextMenu.customItems.push(cutItem);var copyItem:ContextMenuItem = new ContextMenuItem("Copy")
copyItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCopyCommand);editContextMenu.customItems.push(copyItem);var pasteItem:ContextMenuItem = new ContextMenuItem("Paste")pasteItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doPasteCommand);editContextMenu.customItems.push(pasteItem);return editContextMenu}
private function doCutCommand(event:ContextMenuEvent):void{trace("cut");}private function doCopyCommand(event:ContextMenuEvent):void{trace("copy");}private function doPasteCommand(event:ContextMenuEvent):void{trace("paste");}注意：ブラウザー環境で表示される SWF コンテンツとは異なり、AIR のコンテキストメニューにはビルトインコマンドはありません。

Flash Player コンテキストメニューのカスタマイズ
ブラウザーまたはプロジェクターでは、SWF コンテンツのコンテキストメニューに常にビルトインアイテムが含まれます。
「設定」および「Flash Player について」コマンド以外のデフォルトのコマンドは、すべてメニューから削除できます。そうするには、Stage プロパティ showDefaultContextMenu を false に設定します。
特定の表示オブジェクトに対してカスタマイズしたコンテキストメニューを作成する場合、ContextMenu クラスの新しいインスタンスを作成して hideBuiltInItems() メソッドを呼び出し、そのインスタンスを該当の DisplayObject インスタンスの contextMenu プロパティに割り当てます。次の例では、動的に描画される四角形に、色をランダムに変更するコンテキス
トメニューコマンドを設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

610

メニューの操作

var square:Sprite = new Sprite();square.graphics.beginFill(0x000000);
square.graphics.drawRect(0,0,100,100);square.graphics.endFill();square.x =square.y = 10;
addChild(square);var menuItem:ContextMenuItem = new ContextMenuItem("Change Color");menuItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT,changeColor);
var customContextMenu:ContextMenu = new ContextMenu();
customContextMenu.hideBuiltInItems();
customContextMenu.customItems.push(menuItem);square.contextMenu = customContextMenu;
function changeColor(event:ContextMenuEvent):void{square.transform.colorTransform = getRandomColor();}function getRandomColor():ColorTransform{
return new ColorTransform(Math.random(), Math.random(), Math.random(),1,(Math.random() * 512) - 255,
(Math.random() * 512) -255, (Math.random() * 512) - 255, 0);}

ネイティブメニューの構造（AIR）
Adobe AIR 1.0 およびそれ以降
ネイティブメニューは、性質として階層的な構造をしています。NativeMenu オブジェクトには、子の NativeMenuItem
オブジェクトが含まれます。さらに、サブメニューを表す NativeMenuItem オブジェクトに NativeMenu オブジェクトを含めることができます。構造内の最上位レベル、つまりルートレベルのメニューオブジェクトは、アプリケーションメ
ニューおよびウィンドウメニューのメニューバーを表します（コンテキスト、アイコンおよびポップアップの各メニューにはメニューバーはありません）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

611

メニューの操作

次の図に、典型的なメニューの構造を示します。ルートメニューはメニューバーを表しており、File サブメニューおよび

Edit サブメニューを参照する 2 つのメニューアイテムが含まれています。この構造の File サブメニューには、2 つのコマン
ドアイテムと、Open Recent Menu サブメニュー（このサブメニュー自体にも 3 つのアイテムが含まれています）を参照
するアイテムが含まれています。Edit サブメニューには、3 つのコマンドと 1 つのセパレーターが含まれています。
NativeMenu

ルートメニュー

NativeMenuItem“File”

NativeMenu

File メニュー

NativeMenuItem“New”

NativeMenuItem“Save”

NativeMenuItem“Open Recent”

NativeMenu

NativeMenuItem
NativeMenu

Open Recent メニュー

NativeMenuItem“GreatGatsby.pdf”

NativeMenuItem“WarAndPeace.pdf”

NativeMenuItem“Iliad.pdf”“Edit”
Edit メニュー

NativeMenuItem“Copy”

NativeMenuItem“Paste”

NativeMenuItem

区切り線

NativeMenuItem“Preferences”

サブメニューを定義するには、NativeMenu オブジェクトと NativeMenuItem オブジェクトの両方が必要です。

NativeMenuItem オブジェクトでは親メニューに表示されるラベルが定義され、ユーザーはこのオブジェクトを使用してサブメニューを開くことができます。NativeMenu オブジェクトは、サブメニューのアイテムのコンテナとして機能します。
NativeMenuItem オブジェクトでは、NativeMenuItem の submenu プロパティを通して NativeMenu オブジェクトを参照します。
このメニューを作成するコードの例については、619 ページの「ネイティブメニューの例：ウィンドウメニューとアプリ
ケーションメニュー（AIR）」を参照してください。

メニューイベント
Adobe AIR 1.0 およびそれ以降
NativeMenu オブジェクトと NativeMenuItem オブジェクトは、どちらも preparing イベント、displaying イベント、selectイベントを送出します。

preparing：オブジェクトがユーザー操作を開始する直前に、登録されているすべてのリスナーに対して、メニューおよび
そのメニューアイテムから preparin イベントが送出されます。操作には、メニューを開く操作やキーボードショートカット
によるアイテムの選択などが含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

612

メニューの操作

注意：preparing イベントは、Adobe AIR 2.6 以降のみで利用できます。

displaying： メニューが表示される直前に、メニューおよびそのメニューアイテムから、登録されているすべてのリス
ナーに displaying イベントが送出されます。

preparing イベントと displaying イベントにより、メニューの内容やアイテムの外観を、ユーザーに表示される前に更新できます。例えば、最近使用したファイルを開くメニューの displaying イベントのリスナーでは、最近表示したドキュメントの最新の一覧を反映するようにメニューアイテムを変更することができます。

preparing イベントをトリガーしたキーボードショートカットに対応するメニューアイテムを削除すると、メニュー操作は事
実上キャンセルされ、select イベントは送出されません。
イベントの target プロパティと currentTarget プロパティはどちらもリスナーの登録先のオブジェクト（メニューそのものか
メニューアイテムの 1 つ）です。

preparing イベントは displaying イベントの前に送出されます。通常はこれらのイベントの両方をリッスンすることはなく、一方のみをリッスンします。

select： コマンドアイテムがユーザーによって選択されると、そのアイテムから、登録されているすべてのリスナーに
select イベントが送出されます。サブメニューアイテムとセパレーターアイテムは選択できないため、これらから select イベ
ントが送出されることはありません。
select イベントは、メニューアイテムからそれを含むメニューへと、ルートメニューに達するまでバブルします。select イベ
ントは、アイテムで直接リッスンすることも、メニュー構造の上位でリッスンすることもできます。select イベントをメ
ニューでリッスンする場合は、そのイベントの target プロパティを使用して、選択されたアイテムを識別できます。メ
ニュー階層の上方にイベントがバブルしていくのに合わせて、イベントオブジェクトの currentTarget プロパティは、現在のメニューオブジェクトを識別します。
注意：ContextMenu オブジェクトと ContextMenuItem オブジェクトでは、menuItemSelect イベントと menuSelect イベ
ントに加え、select イベント、preparing イベント、displaying イベントも送出します。

ネイティブメニューコマンドと等価なキー（AIR）
Adobe AIR 1.0 およびそれ以降
メニューコマンドにキーボードショートカット（アクセラレーター）を割り当てることができます。キーまたはキーの組み合わせが押されると、メニューアイテムから、登録されているすべてのリスナーに select イベントが送出されます。アイテ
ムが格納されるメニューは、コマンドが呼び出されるアプリケーションまたはアクティブなウィンドウのメニューの一部である必要があります。
キーボードショートカットは 2 つの部分から構成されます。主キーを表すストリングと、一緒に押される必要がある修飾
キーの配列です。主キーを割り当てるには、メニューアイテムの keyEquivalent プロパティに、そのキーの 1 文字のストリン
グを設定します。大文字を使用した場合、修飾キーの配列に Shift キーが自動的に追加されます。

Mac OS X では、デフォルトの修飾キーは Command キー（Keyboard.COMMAND）です。Windows および Linux では、
Ctrl キー（Keyboard.CONTROL）です。これらのデフォルトのキーは、修飾キーの配列に自動的に追加されます。別の修飾
キーを割り当てるには、そのキーコードを含む新しい配列を keyEquivalentModifiers プロパティに割り当てます。デフォルトの配列は上書きされます。デフォルトの修飾キーを使用するか独自の修飾キーの配列を割り当てるかに関係なく、
keyEquivalent プロパティに割り当てたストリングが大文字の場合は Shift キーが追加されます。修飾キーに使用するキー
コードの定数は、Keyboard クラスで定義されています。
割り当てられたキーボードショートカットのストリングは、自動的にメニューアイテム名の横に表示されます。形式は、ユーザーのオペレーティングシステムおよびシステムの環境設定によって異なります。
注意：Windows オペレーティングシステムでキー修飾の配列に Keyboard.COMMAND 値を割り当てた場合、メニューにキーボードショートカットは表示されません。ただし、そのメニューコマンドをアクティブにするには Ctrl キーを使用する必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

613

メニューの操作

次の例では、メニューアイテムのキーボードショートカットとして Ctrl+Shift+G を割り当てます。
var item:NativeMenuItem = new NativeMenuItem("Ungroup");item.keyEquivalent = "G";

次の例では、修飾キーの配列を直接設定することにより、キーボードショートカットとして Ctrl+Shift+G を割り当てます。
var item:NativeMenuItem = new NativeMenuItem("Ungroup");item.keyEquivalent = "G";item.keyEquivalentModifiers = [Keyboard.CONTROL];

注意：キーボードショートカットでトリガーできるのは、アプリケーションメニューまたはウィンドウメニューのみです。
コンテキストメニューまたはポップアップメニューにキーボードショートカットを追加した場合、メニューラベルにはキー
ボードショートカットが表示されますが、関連付けられたメニューコマンドを呼び出すことはできません。

ニーモニック（AIR）
Adobe AIR 1.0 およびそれ以降
ニーモニックは、オペレーティングシステムのメニューのキーボードインターフェイスの一部です。Linux、Mac OS X お
よび Windows では、いずれもキーボードでメニューを開いてコマンドを選択する操作ができますが、その方法には微妙な違いがあります。

Mac OS X では、ユーザーはメニューまたはコマンドの最初の 1 文字か 2 文字を入力して、Return キーを押します。
mnemonicIndex プロパティは無視されます。

Windows では、これを 1 文字だけで実行できます。デフォルトでは、有効な文字はラベルの最初の文字ですが、メニュー
アイテムにニーモニックを割り当てると、有効な文字は指定した文字になります。メニュー内の 2 つのアイテムの有効な文
字が同じ場合（ニーモニックが割り当てられているかどうかに関係なく）、メニューのキーボード操作が少し異なります。1
文字入力してメニューまたはコマンドを選択するのではなく、ユーザーは必要な回数だけその文字を入力して対象のアイテ
ムを強調表示してから、Enter キーを押して選択を完了する必要があります。動作の一貫性を維持するために、ウィンドウ
メニューでは、メニュー内のアイテムそれぞれに異なるニーモニックを割り当てることをお勧めします。

Linux では、既定のニーモニックは設定されません。メニューアイテムの mnemonicIndex プロパティ値を設定することでニーモニックを指定する必要があります。
ニーモニック文字は、ラベルストリングのインデックスとして指定します。ラベルの最初の文字のインデックスは 0 です。
したがって、「Format」というラベルのメニューアイテムのニーモニックとして「r」を使用するには、mnemonicIndex プ
ロパティを 2 に設定します。
var item:NativeMenuItem = new NativeMenuItem("Format");item.mnemonicIndex = 2;

メニューアイテムの状態
Adobe AIR 1.0 およびそれ以降
メニューアイテムには、状態を表すプロパティとして、checked および enabled という 2 つのプロパティがあります。

checked true に設定すると、アイテムラベルの横にチェックマークが表示されます。
var item:NativeMenuItem = new NativeMenuItem("Format");item.checked = true;

enabled 値を true と false で切り替えて、コマンドを有効にするかどうかを制御します。無効にしたアイテムは「グレー表示」され、そのアイテムからは select イベントは送出されません。
var item:NativeMenuItem = new NativeMenuItem("Format");item.enabled = false;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

614

メニューの操作

メニューアイテムへのオブジェクトの関連付け
Adobe AIR 1.0 およびそれ以降
NativeMenuItem クラスの data プロパティを使用して、各アイテムの任意のオブジェクトを参照できます。例えば、最近使用したファイルを開くメニューでは、それぞれのメニューアイテムに各ドキュメントの File オブジェクトを割り当てることができます。
var file:File = File.applicationStorageDirectory.resolvePath("GreatGatsby.pdf")
var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name));menuItem.data = file;

ネイティブメニューの作成（AIR）
Adobe AIR 1.0 およびそれ以降
このトピックでは、AIR でサポートされる様々なタイプのネイティブメニューを作成する方法を示します。

ルートメニューオブジェクトの作成
Adobe AIR 1.0 およびそれ以降
メニューのルートとして機能する NativeMenu オブジェクトを作成するには、NativeMenu コンストラクターを使用します。
var root:NativeMenu = new NativeMenu();

アプリケーションメニューおよびウィンドウメニューでは、ルートメニューはメニューバーを表し、サブメニューを開くア
イテムのみが格納されます。コンテキストメニューおよびポップアップメニューにはメニューバーがないため、ルートメ
ニューにコマンドやセパレーター線、およびサブメニューを含めることはできません。
メニューを作成したら、メニューアイテムを追加できます。アイテムは、追加した順序で表示されます。アイテムを特定のインデックスに表示するには、メニューオブジェクトの addItemAt() メソッドを使用します。
以降の節で示すように、メニューはアプリケーション、ウィンドウ、アイコンまたはコンテキストのいずれかのメニューとして割り当てるか、ポップアップメニューとして表示します。
アプリケーションメニューの設定またはウィンドウメニューの設定
コードには、アプリケーションメニュー（Mac OS でサポート）とウィンドウメニュー（その他のオペレーティングシステ
ムでサポート）の両方を含めることが重要です。
var root:NativeMenu = new NativeMenu();
if (NativeApplication.supportsMenu){
NativeApplication.nativeApplication.menu = root;}
else if (NativeWindow.supportsMenu){
nativeWindow.menu = root;}

注意：Mac OS では、すべてのアプリケーション用の標準アイテムを含むメニューを定義します。新しい NativeMenu オブジェクトを NativeApplication オブジェクトの menu プロパティに割り当てると、標準のメニューが置き換えられます。置
き換えずに標準のメニューを使用することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

615

メニューの操作

Adobe Flex の FlexNativeMenu クラスを使用すると、様々なプラットフォームで機能するメニューを簡単に作成できます。Flex フレームワークを使用している場合は、NativeMenu クラスではなく FlexNativeMenu クラスを使用します。
インタラクティブオブジェクトのコンテキストメニューの設定
interactiveObject.contextMenu = root;

ドックアイコンメニューの設定またはシステムトレイアイコンメニューの設定
コードには、アプリケーションメニュー（Mac OS でサポート）とウィンドウメニュー（その他のオペレーティングシステ
ムでサポート）の両方を含めることが重要です。
if (NativeApplication.supportsSystemTrayIcon){
SystemTrayIcon(NativeApplication.nativeApplication.icon).menu = root;}
else if (NativeApplication.supportsDockIcon){
DockIcon(NativeApplication.nativeApplication.icon).menu = root;}

注意：Mac OS X では、アプリケーションのドックアイコン用に標準のメニューが定義されています。新しい NativeMenu
を DockIcon オブジェクトの menu プロパティに割り当てると、そのメニューに含まれるアイテムが標準のアイテムの上に表示されます。標準のメニューアイテムの削除、アクセスまたは変更を行うことはできません。
ポップアップとしてのメニューの表示
root.display(stage, x, y);

関連項目

Developing cross-platform AIR applications

サブメニューの作成
Adobe AIR 1.0 およびそれ以降
サブメニューを作成するには、NativeMenuItem オブジェクトを親メニューに追加し、そのアイテムの submenu プロパ
ティにサブメニューを定義する NativeMenu オブジェクトを割り当てます。AIR には、サブメニューアイテムとそれに関連するメニューオブジェクトを作成する方法が 2 つあります。

addSubmenu() メソッドを使用すると、メニューアイテムおよび関連するメニューオブジェクトを 1 つの手順で作成できます。
var editMenuItem:NativeMenuItem = root.addSubmenu(new NativeMenu(), "Edit");

メニューアイテムの作成とその submenu プロパティへのメニューオブジェクトの割り当てを、別々に行うこともできます。
var editMenuItem:NativeMenuItem = root.addItem("Edit", false);
editMenuItem.submenu = new NativeMenu();

メニューコマンドの作成
Adobe AIR 1.0 およびそれ以降
メニューコマンドを作成するには、NativeMenuItem オブジェクトをメニューに追加し、メニューコマンドを実装する関数を参照するイベントリスナーを追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

616

メニューの操作

var copy:NativeMenuItem = new NativeMenuItem("Copy", false);
copy.addEventListener(Event.SELECT, onCopyCommand);editMenu.addItem(copy);

select イベントは、この例のようにコマンドアイテム自体でリッスンすることも、親メニューオブジェクトでリッスンすることもできます。
注意：サブメニューおよびセパレーター線を表すメニューアイテムからは select イベントは送出されないため、それらのアイテムをコマンドとして使用することはできません。

メニューセパレーター線の作成
Adobe AIR 1.0 およびそれ以降
セパレーター線を作成するには、NativeMenuItem を作成し、そのコンストラクターで isSeparator パラメーターを true に設定します。次に、セパレーターアイテムをメニュー内の適切な位置に追加します。
var separatorA:NativeMenuItem = new NativeMenuItem("A", true);
editMenu.addItem(separatorA);

セパレーターにラベルを指定しても、そのラベルは表示されません。

コンテキストメニューについて：HTML（AIR）
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトを使用して表示される HTML コンテンツでは、contextmenu イベントを使用してコンテキスト
メニューを表示できます。デフォルトでは、ユーザーが選択したテキストで（テキストを右クリックするか Command
キーを押しながらクリックして）コンテキストメニューを呼び出すと、自動的にコンテキストメニューが表示されます。デ
フォルトのメニューが開かないようにするには、contextmenu イベントをリッスンし、そのイベントオブジェクトのpreventDefault() メソッドを呼び出します。
function showContextMenu(event){
event.preventDefault();}

その後、DHTML の手法を使用するか AIR のネイティブコンテキストメニューを表示して、カスタムコンテキストメ
ニューを表示できます。次の例では、HTML の contextmenu イベントに応答してメニューの display() メソッドを呼び出す
ことにより、ネイティブコンテキストメニューを表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

617

メニューの操作<html><head><script src="AIRAliases.js" language="JavaScript" type="text/javascript"></script><script language="javascript" type="text/javascript">function showContextMenu(event){
event.preventDefault();
contextMenu.display(window.nativeWindow.stage, event.clientX, event.clientY);}
function createContextMenu(){
var menu = new air.NativeMenu();
var command = menu.addItem(new air.NativeMenuItem("Custom command"));command.addEventListener(air.Event.SELECT, onCommand);return menu;}function onCommand(){
air.trace("Context command invoked.");}var contextMenu = createContextMenu();</script></head><body><p oncontextmenu="showContextMenu(event)" style="-khtml-user-select:auto;">Custom context menu.</p></body></html>ポップアップネイティブメニューの表示（AIR）
Adobe AIR 1.0 およびそれ以降
NativeMenu オブジェクトは、メニューの display() メソッドを呼び出すことで、いつでもウィンドウ上の任意の位置に表示できます。このメソッドではステージを参照する必要があるため、メニューをポップアップとして表示できるのは、アプリ
ケーションサンドボックス内のコンテンツのみになります。
次のメソッドでは、マウスクリックに応答して、popupMenu という NativeMenu オブジェクトで定義されたメニューを表示します。
private function onMouseClick(event:MouseEvent):void {popupMenu.display(event.target.stage, event.stageX, event.stageY);}

注意：メニューを表示するのに、必ずしもイベントに直接応答する必要はありません。display() 関数は、どのメソッドでも呼び出せます。

メニューイベントの処理
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーがメニューを選択したり、メニューアイテムを選択したりすると、メニューからイベントが送出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

618

メニューの操作

メニュークラスのイベントの概要
Flash Player 9 以降、Adobe AIR 1.0 以降
メニューイベントを処理するには、メニューまたは個々のアイテムにイベントリスナーを追加します。
オブジェクト

送出されるイベント

NativeMenu（AIR）

Event.PREPARING（Adobe AIR 2.6 以降）
Event.DISPLAYING
Event.SELECT（子のアイテムおよびサブメニューから伝達される）

NativeMenuItem（AIR） Event.PREPARING（Adobe AIR 2.6 以降）
Event.SELECT
Event.DISPLAYING（親メニューから伝達される）
ContextMenu

ContextMenuEvent.MENU_SELECT

ContextMenuItem

ContextMenuEvent.MENU_ITEM_SELECT
Event.SELECT（AIR）

Select メニューイベント
Adobe AIR 1.0 およびそれ以降
メニューアイテムがクリックされたときにそれに対処するには、select イベントのイベントリスナーを NativeMenuItem オ
ブジェクトに追加します。
var menuCommandX:NativeMenuItem = new NativeMenuItem("Command X");
menuCommandX.addEventListener(Event.SELECT, doCommandX)

select イベントは、上位の格納元メニューにバブルするため、親メニューでリッスンすることもできます。メニューレベル
でリッスンする場合は、イベントオブジェクトの target プロパティを使用して、選択されたメニューコマンドを判断できます。次の例では、選択されたコマンドのラベルをトレースします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

619

メニューの操作

var colorMenuItem:NativeMenuItem = new NativeMenuItem("Choose a color");var colorMenu:NativeMenu = new NativeMenu();
colorMenuItem.submenu = colorMenu;
var red:NativeMenuItem = new NativeMenuItem("Red");var green:NativeMenuItem = new NativeMenuItem("Green");var blue:NativeMenuItem = new NativeMenuItem("Blue");colorMenu.addItem(red);colorMenu.addItem(green);colorMenu.addItem(blue);if(NativeApplication.supportsMenu){
NativeApplication.nativeApplication.menu.addItem(colorMenuItem);
NativeApplication.nativeApplication.menu.addEventListener(Event.SELECT, colorChoice);} else if (NativeWindow.supportsMenu){
var windowMenu:NativeMenu = new NativeMenu();
this.stage.nativeWindow.menu = windowMenu;
windowMenu.addItem(colorMenuItem);windowMenu.addEventListener(Event.SELECT, colorChoice);}function colorChoice(event:Event):void {var menuItem:NativeMenuItem = event.target as NativeMenuItem;
trace(menuItem.label + " has been selected");}ContextMenuItem クラスを使用する場合、select イベントまたは menuItemSelect イベントのいずれかをリッスンできます。
menuItemSelect イベントでは、コンテキストメニューを所有するオブジェクトに関する追加の情報が提供されます。ただし、このイベントは、上位の格納元メニューにはバブルしません。

Displaying メニューイベント
Adobe AIR 1.0 およびそれ以降
メニューが開かれたときにそれに対処するには、displaying イベントのリスナーを追加します。このイベントは、メニューが表示される前に送出されます。displaying イベントは、メニューを更新する場合に使用できます。例えば、アイテムを追加
または削除したり、個々のアイテムについて有効化やチェックの状態を更新できます。また、ContextMenu オブジェクトから menuSelect イベントをリッスンすることもできます。

AIR 2.6 以降では、preparing イベントを使用して、メニューの表示またはキーボードショートカットによるアイテムの選択に応答して、メニューを更新できます。

ネイティブメニューの例：ウィンドウメニューとアプリケー
ションメニュー（AIR）
Adobe AIR 1.0 およびそれ以降
次の例では、610 ページの「ネイティブメニューの構造（AIR）」で説明したメニューを作成します。
メニューは、Windows（ウィンドウメニューのみがサポートされます）および Mac OS X（アプリケーションメニューのみがサポートされます）の両方で機能するように設計されています。それらを区別するために、MenuExample クラスコン
ストラクターで、NativeWindow クラスおよび NativeApplication クラスの静的プロパティ supportsMenu を確認していま

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

620

メニューの操作

す。NativeWindow.supportsMenu が true の場合は、ウィンドウの NativeMenu オブジェクトを作成してから、File サブメ
ニューと Edit サブメニューを作成して追加します。NativeApplication.supportsMenu が true の場合は、File メニューと Edit
メニューを作成して、それらを Mac OS X オペレーティングシステムで提供される既存のメニューに追加します。
次の例では、メニューイベント処理についても示しています。select イベントはアイテムレベルで処理され、さらにメニュー
レベルでも処理されます。選択されたアイテムを格納するメニューからルートメニューまでのチェーンにある各メニューで、

select イベントに応答しています。displaying イベントは、最近使用したファイルを開くメニューで使用されています。メニューが開かれる直前に、メニュー内のアイテムが最新の Documents 配列で更新されます（この例では実際には変更されません）。この例では示していませんが、displaying イベントは個々のアイテムでリッスンすることもできます。
package {import flash.display.NativeMenu;
import flash.display.NativeMenuItem;
import flash.display.NativeWindow;
import flash.display.Sprite;
import flash.events.Event;import flash.filesystem.File;
import flash.desktop.NativeApplication;
public class MenuExample extends Sprite{
private var recentDocuments:Array =new Array(new File("app-storage:/GreatGatsby.pdf"),
new File("app-storage:/WarAndPeace.pdf"),
new File("app-storage:/Iliad.pdf"));public function MenuExample(){var fileMenu:NativeMenuItem;var editMenu:NativeMenuItem;
if (NativeWindow.supportsMenu){stage.nativeWindow.menu = new NativeMenu();stage.nativeWindow.menu.addEventListener(Event.SELECT, selectCommandMenu);
fileMenu = stage.nativeWindow.menu.addItem(new NativeMenuItem("File"));fileMenu.submenu = createFileMenu();
editMenu = stage.nativeWindow.menu.addItem(new NativeMenuItem("Edit"));editMenu.submenu = createEditMenu();}
if (NativeApplication.supportsMenu){
NativeApplication.nativeApplication.menu.addEventListener(Event.SELECT,
selectCommandMenu);
fileMenu = NativeApplication.nativeApplication.menu.addItem(new NativeMenuItem("File"));fileMenu.submenu = createFileMenu();
editMenu = NativeApplication.nativeApplication.menu.addItem(new NativeMenuItem("Edit"));editMenu.submenu = createEditMenu();}}
public function createFileMenu():NativeMenu {var fileMenu:NativeMenu = new NativeMenu();
fileMenu.addEventListener(Event.SELECT, selectCommandMenu);
var newCommand:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("New"));
newCommand.addEventListener(Event.SELECT, selectCommand);var saveCommand:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("Save"));saveCommand.addEventListener(Event.SELECT, selectCommand);var openRecentMenu:NativeMenuItem =fileMenu.addItem(new NativeMenuItem("Open Recent"));openRecentMenu.submenu = new NativeMenu();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

621

メニューの操作

openRecentMenu.submenu.addEventListener(Event.DISPLAYING,
updateRecentDocumentMenu);
openRecentMenu.submenu.addEventListener(Event.SELECT, selectCommandMenu);
return fileMenu;}
public function createEditMenu():NativeMenu {var editMenu:NativeMenu = new NativeMenu();
editMenu.addEventListener(Event.SELECT, selectCommandMenu);
var copyCommand:NativeMenuItem = editMenu.addItem(new NativeMenuItem("Copy"));copyCommand.addEventListener(Event.SELECT, selectCommand);
copyCommand.keyEquivalent = "c";var pasteCommand:NativeMenuItem =editMenu.addItem(new NativeMenuItem("Paste"));pasteCommand.addEventListener(Event.SELECT, selectCommand);pasteCommand.keyEquivalent = "v";editMenu.addItem(new NativeMenuItem("", true));var preferencesCommand:NativeMenuItem =editMenu.addItem(new NativeMenuItem("Preferences"));preferencesCommand.addEventListener(Event.SELECT, selectCommand);return editMenu;}
private function updateRecentDocumentMenu(event:Event):void {trace("Updating recent document menu.");var docMenu:NativeMenu = NativeMenu(event.target);for each (var item:NativeMenuItem in docMenu.items) {docMenu.removeItem(item);}for each (var file:File in recentDocuments) {var menuItem:NativeMenuItem =docMenu.addItem(new NativeMenuItem(file.name));menuItem.data = file;menuItem.addEventListener(Event.SELECT, selectRecentDocument);}}
private function selectRecentDocument(event:Event):void {trace("Selected recent document: " + event.target.data.name);}
private function selectCommand(event:Event):void {trace("Selected command: " + event.target.label);}
private function selectCommandMenu(event:Event):void {if (event.currentTarget.parent != null) {var menuItem:NativeMenuItem =findItemForMenu(NativeMenu(event.currentTarget));if (menuItem != null) {trace("Select event for \"" +event.target.label +"\" command handled by menu: " +menuItem.label);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

622

メニューの操作}} else {trace("Select event for \"" +event.target.label +"\" command handled by root menu.");}}private function findItemForMenu(menu:NativeMenu):NativeMenuItem {for each (var item:NativeMenuItem in menu.parent.items) {if (item != null) {if (item.submenu == menu) {return item;}}}
return null;}}}

最終更新日 2015/10/14

623

第 37 章：AIR のタスクバーアイコン
Adobe AIR 1.0 およびそれ以降
多くのオペレーティングシステムには、アプリケーションを表すアイコンを格納できるタスクバー（Mac OS X のドックなど）があります。Adobe® AIR® には、NativeApplication.nativeApplication.icon プロパティを通じてアプリケーションタスク
バーアイコンを操作するためのインターフェイスが用意されています。

•

ドックとシステムトレイの操作（Flex）•

ドックとシステムトレイの操作（Flash）

関連項目

flash.desktop.NativeApplication
flash.desktop.DockIcon
flash.desktop.SystemTrayIcon

タスクバーアイコンについて
Adobe AIR 1.0 およびそれ以降
AIR では、NativeApplication.nativeApplication.icon オブジェクトが自動的に作成されます。オブジェクトのタイプは、オペ
レーティングシステムに応じて、DockIcon または SystemTrayIcon のいずれかになります。現在のオペレーティングシス
テムでこれらの InteractiveIcon サブクラスのどちらがサポートされるかは、NativeApplication.supportsDockIcon プロパ
ティと NativeApplication.supportsSystemTrayIcon プロパティを使用して確認できます。InteractiveIcon 基本クラスには、
width プロパティ、height プロパティおよび bitmaps プロパティが用意されており、これらを使用してアイコンで使用するイ
メージを変更することができます。ただし、DockIcon または SystemTrayIcon 固有のプロパティを対応していないオペ
レーティングシステムで調べると、ランタイムエラーが発生します。
アイコンに使用するイメージを設定または変更するには、1 つ以上のイメージを格納する配列を作成し、その配列をNativeApplication.nativeApplication.icon.bitmaps プロパティに割り当てます。タスクバーアイコンのサイズは、オペレーティ
ングシステムの種類によって異なる場合があります。サイズ調整による画質の劣化を防ぐには、複数のサイズのイメージを

bitmaps 配列に追加します。複数のイメージを追加した場合は、AIR によってタスクバーアイコンの現在の表示サイズに最も近いサイズが選択され、必要な場合にのみサイズが調整されます。次の例では、2 つのイメージを使用してタスクバーア
イコンのイメージを設定しています。
NativeApplication.nativeApplication.icon.bitmaps =[bmp16x16.bitmapData, bmp128x128.bitmapData];

アイコンイメージを変更するには、1 つ以上の新しいイメージを格納する配列を bitmaps プロパティに割り当てます。

enterFrame イベントまたは timer イベントに応答してイメージを変更すると、アイコンをアニメーション化することができます。

Windows および Linux で通知領域からアイコンを削除するか、または Mac OS X でアイコンの外観をデフォルトに戻すには、bitmaps に空の配列を設定します。
NativeApplication.nativeApplication.icon.bitmaps = [];最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

624

AIR のタスクバーアイコン

ドックアイコン
Adobe AIR 1.0 およびそれ以降
NativeApplication.supportsDockIcon が true の場合、AIR でドックアイコンがサポートされます。
NativeApplication.nativeApplication.icon プロパティは、ドックのアプリケーションアイコンを表します（ウィンドウドック
アイコンは除く）。
注意：AIR では、Mac OS X でのドックのウィンドウアイコンの変更はサポートされません。また、アプリケーションドッ
クアイコンに対する変更はアプリケーションの実行中にのみ適用され、アプリケーションが終了されるとアイコンの外観は標準の外観に戻ります。

ドックアイコンのメニュー
Adobe AIR 1.0 およびそれ以降コマンドを格納する NativeMenu オブジェクトを作成し、そのオブジェクトを

NativeApplication.nativeApplication.icon.menu プロパティに割り当てることで、標準のドックメニューにコマンドを追加することができます。メニューのアイテムは、標準のドックアイコンメニューアイテムの上に表示されます。

ドックのバウンス
Adobe AIR 1.0 およびそれ以降
NativeApplication.nativeApplication.icon.bounce() メソッドを呼び出すことにより、ドックアイコンをバウンスさせることができます。bounce() priority パラメーターを informational に設定すると、アイコンが 1 回バウンスします。critical に設定
すると、ユーザーがアプリケーションをアクティブにするまでアイコンがバウンスします。priority パラメーターの定数は、NotificationType クラスで定義されています。
注意：アプリケーションが既にアクティブになっている場合は、アイコンはバウンスしません。

ドックアイコンのイベント
Adobe AIR 1.0 およびそれ以降
ドックアイコンがクリックされると、NativeApplication オブジェクトから invoke イベントが送出されます。アプリケー
ションが実行されていない場合は、システムによってアプリケーションが起動されます。それ以外の場合は、invoke イベン
トは実行中のアプリケーションインスタンスに送られます。

システムトレイアイコン
Adobe AIR 1.0 およびそれ以降
NativeApplication.supportsSystemTrayIcon が true の場合、AIR でシステムトレイアイコンがサポートされます（現在、Windows と大半の Linux ディストリビューションのみ該当します）。Windows および Linux では、システムトレイアイコ
ンはタスクバーの通知領域に表示されます。デフォルトではアイコンは表示されません。アイコンを表示するには、
BitmapData オブジェクトを格納する配列をアイコンの bitmaps プロパティに割り当てます。アイコンイメージを変更するには、新しいイメージを格納する配列を bitmaps に割り当てます。アイコンを削除するには、bitmaps を null に設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

625

AIR のタスクバーアイコン

システムトレイアイコンのメニュー
Adobe AIR 1.0 およびそれ以降
NativeMenu オブジェクトを作成し、そのオブジェクトを NativeApplication.nativeApplication.icon.menu プロパティに割り当てることで、システムトレイアイコンにメニューを追加することができます（オペレーティングシステムのデフォルトのメニューはありません）。システムトレイアイコンのメニューにアクセスするには、アイコンを右クリックします。

システムトレイアイコンのツールチップ
Adobe AIR 1.0 およびそれ以降
アイコンにツールチップを追加するには、tooltip プロパティを設定します。
NativeApplication.nativeApplication.icon.tooltip = "Application name";

システムトレイアイコンのイベント
Adobe AIR 1.0 およびそれ以降
NativeApplication.nativeApplication.icon プロパティによって参照される SystemTrayIcon オブジェクトから、click、
mouseDown、mouseUp、rightClick、rightMouseDown、rightMouseUp の各イベントに対して ScreenMouseEvent が送出されます。これらのイベントをアイコンメニューと一緒に使用すると、アプリケーションに可視のウィンドウがない場合にユーザーがそのアプリケーションを操作できるようになります。

例：ウィンドウがないアプリケーションの作成
Adobe AIR 1.0 およびそれ以降
次の例では、システムトレイアイコンがあり、可視のウィンドウはない AIR アプリケーションを作成します（アプリケー
ションの visible プロパティは、アプリケーション記述で true に設定しないようにする必要があります。さもなければ、アプ
リケーションの起動時にウィンドウが表示されます）。
package{import flash.display.Loader;import flash.display.NativeMenu;
import flash.display.NativeMenuItem;
import flash.display.NativeWindow;
import flash.display.Sprite;
import flash.desktop.DockIcon;
import flash.desktop.SystemTrayIcon;
import flash.events.Event;import flash.net.URLRequest;
import flash.desktop.NativeApplication;
public class SysTrayApp extends Sprite{
public function SysTrayApp():void{
NativeApplication.nativeApplication.autoExit = false;
var icon:Loader = new Loader();var iconMenu:NativeMenu = new NativeMenu();
var exitCommand:NativeMenuItem = iconMenu.addItem(new NativeMenuItem("Exit"));exitCommand.addEventListener(Event.SELECT, function(event:Event):void {NativeApplication.nativeApplication.icon.bitmaps = [];NativeApplication.nativeApplication.exit();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

626

AIR のタスクバーアイコン});
if (NativeApplication.supportsSystemTrayIcon) {NativeApplication.nativeApplication.autoExit = false;
icon.contentLoaderInfo.addEventListener(Event.COMPLETE, iconLoadComplete);icon.load(new URLRequest("icons/AIRApp_16.png"));var systray:SystemTrayIcon =NativeApplication.nativeApplication.icon as SystemTrayIcon;
systray.tooltip = "AIR application";systray.menu = iconMenu;}
if (NativeApplication.supportsDockIcon){icon.contentLoaderInfo.addEventListener(Event.COMPLETE,iconLoadComplete);icon.load(new URLRequest("icons/AIRApp_128.png"));var dock:DockIcon = NativeApplication.nativeApplication.icon as DockIcon;
dock.menu = iconMenu;}}
private function iconLoadComplete(event:Event):void{
NativeApplication.nativeApplication.icon.bitmaps =[event.target.content.bitmapData];}}}

注意：Flex WindowedApplication コンポーネントを使用している場合、WindowedApplication タグの visible 属性を

false に設定する必要があります。この属性は、アプリケーション記述の設定より優先されます。
注意：この例では、AIRApp_16.png および AIRApp_128.png という名前のイメージファイルがアプリケーションの icons サブ
ディレクトリに含まれていることを前提にしています（サンプルのアイコンファイルは AIR SDK に含まれており、プロ
ジェクトフォルダーにコピーできます）。

ウィンドウのタスクバーのアイコンとボタン
Adobe AIR 1.0 およびそれ以降
ウィンドウを表すアイコンは、通常はタスクバーまたはドックのウィンドウ領域に表示されます。ユーザーはこれらを使用
して、バックグラウンドで実行されているウィンドウや最小化されているウィンドウに簡単にアクセスすることができます。

Mac OS X のドックには、アプリケーションのアイコンと最小化された各ウィンドウのアイコンが表示されます。
Microsoft Windows および Linux では、アプリケーションで表示する通常種類の各ウィンドウを表すボタンがタスクバーに表示され、各ボタンにプログラムアイコンとタイトルが表示されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

627

AIR のタスクバーアイコン

タスクバーのウィンドウボタンの強調表示
Adobe AIR 1.0 およびそれ以降
ウィンドウがバックグラウンドで実行されているときに、ウィンドウに関連するイベントが発生したことをユーザーに通知することができます。Mac OS X では、アプリケーションドックアイコンをバウンスさせてユーザーに通知できます（624
ページの「ドックのバウンス」の説明を参照）。Windows および Linux では、NativeWindow インスタンスの

notifyUser() メソッドを呼び出すと、そのウィンドウに対応するタスクバーボタンが強調表示されます。メソッドに渡される
type パラメーターによって、通知の緊急度が決まります。

• NotificationType.CRITICAL：ユーザーがウィンドウを前面に表示するまでウィンドウアイコンが点滅します。
• NotificationType.INFORMATIONAL：別の色でウィンドウアイコンが強調表示されます。
注意：Linux では、サポートされている通知の種類は INFORMATIONAL のみです。notifyUser() 関数にどの type 値を渡しても同じ効果になります。
次のステートメントでは、ウィンドウのタスクバーボタンを強調表示します。
stage.nativeWindow.notifyUser(NotificationType.CRITICAL);

ウィンドウレベルの通知がサポートされていないオペレーティングシステムでは、NativeWindow.notifyUser() メソッドを呼び出しても効果はありません。ウィンドウの通知がサポートされているかどうかを確認するには、

NativeWindow.supportsNotification プロパティを使用します。

タスクバーのボタンまたはアイコンがないウィンドウの作成
Adobe AIR 1.0 およびそれ以降
Windows オペレーティングシステムでは、utility または lightweight のタイプで作成されたウィンドウはタスクバーに表示されません。また、不可視のウィンドウもタスクバーに表示されません。
初期ウィンドウのタイプは必ず normal であるため、ウィンドウがタスクバーに表示されないアプリケーションを作成するには、初期ウィンドウを閉じるか、不可視のままにしておく必要があります。アプリケーションを終了しないでアプリケー
ションのすべてのウィンドウを閉じるには、最後のウィンドウを閉じる前に、NativeApplication オブジェクトの autoExit
プロパティを false に設定します。単に初期ウィンドウが可視にならないようにするには、<visible>false</visible> をアプリ
ケーション記述ファイルの <initalWindow> エレメントに追加します（さらに、visible プロパティを true に設定したり、ウィ
ンドウの activate() メソッドを呼び出したりしないようにします）。
アプリケーションで開かれる新しいウィンドウでは、ウィンドウコンストラクターに渡される NativeWindowInitOption
オブジェクトの type プロパティを NativeWindowType.UTILITY または NativeWindowType.LIGHTWEIGHT に設定します。

Mac OS X では、最小化されたウィンドウはドックタスクバーに表示されます。最小化されたアイコンが表示されないようにするには、ウィンドウを最小化するのではなく非表示にします。次の例では、nativeWindowDisplayState 変更イベントをリッスンし、ウィンドウが最小化される場合にキャンセルします。その代わりに、ハンドラーでウィンドウの visible プロパ
ティを false に設定します。
private function preventMinimize(event:NativeWindowDisplayStateEvent):void{if(event.afterDisplayState == NativeWindowDisplayState.MINIMIZED){
event.preventDefault();
event.target.visible = false;}}

visible プロパティを false に設定している場合に Mac OS X ドックでウィンドウが最小化されても、ドックアイコンが削除されるわけではありません。ユーザーは、引き続きアイコンをクリックしてウィンドウを再表示することができます。

最終更新日 2015/10/14

628

第 38 章：ファイルシステムの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash® Player には基本的なファイルの読み取りと書き込みの機能があり、それには FileReference クラスが使用されます。
Flash Player の実行中にファイルの読み取りまたは書き込みを実行するには、セキュリティ上の理由から、常にユーザーによる許可が必要になります。

Adobe® AIR® では、ホストコンピューターのファイルシステムにアクセスして、Flash Player よりも充実した操作を実行することができます。AIR ファイルシステム API を使用すると、ディレクトリやファイルにアクセスしてそれらを管理した
り、ディレクトリやファイルを作成したり、ファイルにデータを書き込んだりすることができます。

関連項目

flash.net.FileReference
flash.net.FileReferenceList
flash.filesystem.File
flash.filesystem.FileStream

FileReference クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
FileReference オブジェクトはクライアントまたはサーバーマシン上のデータファイルを表します。FileReference クラスのメソッドを使用して、アプリケーションでデータファイルをローカルにロードおよび保存したり、リモートサーバーとの間でファイルデータを転送したりできます。

FileReference クラスには、データファイルをロード、転送、保存する 2 つの異なる方法が用意されています。
FileReference クラスには、導入時から browse() メソッド、upload() メソッドおよび download() メソッドが用意されています。browse() メソッドを使用すると、ユーザーはファイルを選択できるようになります。upload() メソッドは、ファイル
データをリモートサーバーへ転送するのに使用します。download() メソッドでは、データをサーバーから取得して、ローカ
ルファイルに保存します。Flash Player 10 および Adobe AIR 1.5 以降、FileReference クラスには load() メソッドおよびsave() メソッドが含まれています。load() メソッドおよび save() メソッドを使用すると、ローカルファイルに直接アクセスして保存することもできます。これらのメソッドの使用法は、URLLoader および Loader クラスが持つ同等の名前のメソッドとほぼ同じです。
注意：FileReference クラスを拡張したクラスである File クラスと、FileStream クラスにより、ファイルとローカルファイ
ルシステムを扱うための様々な機能が追加されます。File クラスと FileStream クラスは AIR でのみサポートされ、Flash

Player ではサポートされません。

FileReference クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
各 FileReference オブジェクトは、ローカルマシン上の 1 つのデータファイルを表します。FileReference クラスのプロパ
ティには、ファイルのサイズ、種類、名前、ファイル拡張子、作成者、作成日および変更日の情報が含まれています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

629

ファイルシステムの操作

注意：creator プロパティは Mac OS でのみサポートされており、それ以外のすべてのプラットフォームでは null が返されます。
注意：extension プロパティは Adobe AIR でのみサポートされています。

FileReference クラスのインスタンスを作成する方法は 2 種類あります。

•

以下のコードに示すように、new 演算子を使用します。
import flash.net.FileReference;var fileRef:FileReference = new FileReference();• FileReferenceList.browse() メソッドを呼び出して、アップロードするファイルをユーザーが選択できるダイアログボック
スを開きます。ユーザーによって 1 つ以上のファイルが正しく選択された場合は、FileReference オブジェクトの配列が作成されます。

FileReference オブジェクトを作成した後は、以下の操作を実行できます。

• FileReference.browse() メソッドを呼び出して、ローカルファイルシステムの 1 つのファイルをユーザーが選択できるダイ
アログボックスを開きます。この操作は通常、FileReference.upload() メソッドまたは FileReference.load() メソッドを後で呼び出す前に実行します。FileReference.upload() メソッドを呼び出して、ファイルをリモートサーバーにアップロードします。FileReference.load() メソッドを呼び出して、ローカルファイルを開きます。

• FileReference.download() メソッドを呼び出します。これにより、新しいファイルの保存場所をユーザーが選択できるダ
イアログボックスが開きます。その後、サーバーからのデータがダウンロードされ、新しいファイルに保存されます。

• FileReference.load() メソッドを呼び出します。このメソッドは、先に browse() メソッドで選択されたファイルからデータをロードする処理を開始します。browse() 操作が完了（ユーザーがファイルを選択）するまで、load() メソッドを呼び出すことはできません。

• FileReference.save() メソッドを呼び出します。このメソッドは、ダイアログボックスを表示し、ローカルファイルシステ
ム上のファイルの場所を 1 つ選択することをユーザーに求めます。次に、指定された場所にデータを保存します。
注意：browse()、download() または save() のアクションを複数並行して実行することはできません。これは、一度に 1 つしかダイアログボックスを表示できないからです。

name、size、modificationDate などの FileReference オブジェクトのプロパティは、以下のいずれかの操作が行われるまで定義されません。

• FileReference.browse() メソッドまたは FileReferenceList.browse() メソッドが呼び出され、ユーザーがダイアログボックス
からファイルを選択する。

• FileReference.download() メソッドが呼び出され、ユーザーがダイアログボックスから新しいファイルの場所を指定する。
注意：ダウンロードを実行する場合、FileReference.name プロパティだけはダウンロードの完了より前に設定されます。ダウンロードが完了すると、すべてのプロパティの値が設定されます。
ほとんどのプレーヤーでは、FileReference.browse()、FileReferenceList.browse()、FileReference.download()、

FileReference.load() または FileReference.save() メソッドの実行中も、イベントの送出やコードの実行を含めた SWF ファイルの再生処理が続行されます。
アップロード処理およびダウンロード処理では、当該 SWF ファイル自体が属するドメイン内のファイルと、ポリシーファ
イルで指定されたドメイン内のファイルに対してのみアクセスできます。SWF ファイルとは異なるドメインにあるサーバー上のファイルに対して SWF からアップロードまたはダウンロード操作を開始するには、そのサーバー上にポリシー
ファイルが置かれている必要があります。
「FileReference」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

630

ファイルシステムの操作

ファイルからのデータのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
FileReference.load() メソッドでは、ローカルファイルからのデータをメモリにロードできます。
注意：アプリケーションのコードでは、まず FileReference.browse() メソッドを呼び出して、ロードするファイルをユーザーに選択させる必要があります。この制限は、アプリケーションセキュリティサンドボックスで実行されている Adobe AIRのコンテンツには適用されません。

FileReference.load() メソッドは呼び出されると直ちに戻りますが、ロードするデータは直ちに使用可能とはなりません。
FileReference オブジェクトは、ロードプロセスの各段階で、リスナーメソッドを呼び出すイベントを送出します。

FileReference オブジェクトからロードプロセス中に送出されるのは次のイベントです。

• open イベント（Event.OPEN）：ロード処理が開始したときに送出されます。
• progress イベント（ProgressEvent.PROGRESS）：ファイルのデータバイトが読み取られると定期的に送出されます。
• complete イベント（Event.COMPLETE）：ファイルのロード処理が正常に完了したときに送出されます。
• ioError イベント：（IOErrorEvent.IO_ERROR）：ファイルを開く際やデータを読み取る際に入出力エラーが発生し、それが原因でロードプロセスが失敗した場合に送出されます。

FileReference オブジェクトから complete イベントが送出された後は、その FileReference オブジェクトの data プロパ
ティに格納された ByteArray として、ロードしたデータにアクセスできます。
次の例は、ユーザーにファイルを選択するよう求め、そのファイルからのデータをメモリにロードする方法を示します。
package{import flash.display.Sprite;
import flash.events.*;
import flash.net.FileFilter;
import flash.net.FileReference;
import flash.net.URLRequest;
import flash.utils.ByteArray;public class FileReferenceExample1 extends Sprite{
private var fileRef:FileReference;
public function FileReferenceExample1(){
fileRef = new FileReference();fileRef.addEventListener(Event.SELECT, onFileSelected);
fileRef.addEventListener(Event.CANCEL, onCancel);
fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR,
onSecurityError);var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)","*.txt;*.rtf");
fileRef.browse([textTypeFilter]);}
public function onFileSelected(evt:Event):void{
fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress);
fileRef.addEventListener(Event.COMPLETE, onComplete);
fileRef.load();}public function onProgress(evt:ProgressEvent):void{
trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes.");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

631

ファイルシステムの操作}
public function onComplete(evt:Event):void{
trace("File was successfully loaded.");trace(fileRef.data);}
public function onCancel(evt:Event):void{
trace("The browse request was canceled by the user.");}public function onIOError(evt:IOErrorEvent):void{
trace("There was an IO Error.");}public function onSecurityError(evt:Event):void{
trace("There was a security error.");}}}

例のコードでは、fileRef という名前の FileReference オブジェクトを作成し、このオブジェクトの browse() メソッドを呼び出しています。browse() メソッドによりダイアログボックスを開いて、ユーザーがファイルを選択できるようにします。
ファイルを選択すると、onFileSelected() メソッドが呼び出されます。このメソッドでは、progress および complete イベントのリスナーを追加してから、FileReference オブジェクトの load() メソッドを呼び出します。他のハンドラーメソッドは、
ロード操作の進行状況を知らせるメッセージを出力するだけです。ロードが完了すると、このアプリケーションは、ロードしたファイルの内容を trace() メソッドで表示します。

Adobe AIR の FileStream クラスには、ローカルファイルからデータを読み取るための機能が用意されています。664 ページの「ファイルの読み取りと書き込み」を参照してください。

ローカルファイルへのデータの保存Flash Player 9 以降、Adobe AIR 1.0 以降
FileReference.save() メソッドでは、ローカルファイルにデータを保存できます。最初に、新しいファイル名と、ファイルを保存する新しい場所をユーザーが入力できるダイアログボックスを開きます。ユーザーがファイル名と場所を選択すると、データが新しいファイルに書き込まれます。ファイルが正常に保存されると、FileReference オブジェクトのプロパティに
ローカルファイルのプロパティが設定されます。
注意：アプリケーションのコードで FileReference.save() メソッドを呼び出す操作は、マウスクリックまたはキー押下イベン
トなど、ユーザーイベントに応答する形でのみ実行してください。それ以外の場合はエラーが発生します。この制限は、ア
プリケーションセキュリティサンドボックスで実行されている Adobe AIR のコンテンツには適用されません。

FileReference.save() メソッドは呼び出されると直ちに戻ります。FileReference オブジェクトは、ファイル保存プロセスの各段階で、リスナーメソッドを呼び出すイベントを送出します。

FileReference オブジェクトはファイル保存プロセスで以下のイベントを送出します。

• select イベント（Event.SELECT）：新しく保存するファイルのファイル名と場所をユーザーが指定した場合に送出されます。

• cancel イベント（Event.CANCEL）：ユーザーがダイアログボックスの「キャンセル」ボタンをクリックした場合に送出されます。

• open イベント（Event.OPEN）：保存処理が開始したときに送出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

632

ファイルシステムの操作• progress イベント（ProgressEvent.PROGRESS）：ファイルのデータバイトが保存されると定期的に送出されます。
• complete イベント（Event.COMPLETE）：ファイルの保存処理が正常に完了したときに送出されます。
• ioError イベント：（IOErrorEvent.IO_ERROR）：データをファイルに保存しようとした際に入出力エラーが発生し、それが原因で保存プロセスが失敗した場合に送出されます。
ファイルにデータを書き込む方法は、次のように、FileReference.save() メソッドの data パラメーターに渡されるオブジェク
トの型により決定されます。

• String 値の場合、UTF-8 エンコーディングを使用してテキストファイルとして保存されます。
• XML オブジェクトの場合、すべての形式が維持された XML 形式でファイルに書き込まれます。
• ByteArray オブジェクトの場合、コンテンツは変換されずにファイルに直接書き込まれます。
•

他のオブジェクトの場合、FileReference.save() メソッドはそのオブジェクトの toString() メソッドを呼び出し、結果として取得した String 値を UTF-8 テキストファイルに保存します。オブジェクトの toString() メソッドを呼び出すことができない場合は、エラーがスローされます。

data パラメーターの値が null である場合は、エラーがスローされます。
次のコードは、前に示した FileReference.load() メソッドの例を拡張したものです。ファイルからデータを読み取った後、この例ではユーザーにファイル名の入力を求め、新しいファイルにデータを保存します。
package{import flash.display.Sprite;
import flash.events.*;
import flash.net.FileFilter;
import flash.net.FileReference;
import flash.net.URLRequest;
import flash.utils.ByteArray;public class FileReferenceExample2 extends Sprite{
private var fileRef:FileReference;
public function FileReferenceExample2(){
fileRef = new FileReference();fileRef.addEventListener(Event.SELECT, onFileSelected);
fileRef.addEventListener(Event.CANCEL, onCancel);
fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR,
onSecurityError);var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)","*.txt;*.rtf");
fileRef.browse([textTypeFilter]);}
public function onFileSelected(evt:Event):void{
fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress);
fileRef.addEventListener(Event.COMPLETE, onComplete);
fileRef.load();}public function onProgress(evt:ProgressEvent):void{
trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes.");}public function onCancel(evt:Event):void{
trace("The browse request was canceled by the user.");}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

633

ファイルシステムの操作

public function onComplete(evt:Event):void{
trace("File was successfully loaded.");fileRef.removeEventListener(Event.SELECT, onFileSelected);
fileRef.removeEventListener(ProgressEvent.PROGRESS, onProgress);
fileRef.removeEventListener(Event.COMPLETE, onComplete);
fileRef.removeEventListener(Event.CANCEL, onCancel);saveFile();}public function saveFile():void{
fileRef.addEventListener(Event.SELECT, onSaveFileSelected);
fileRef.save(fileRef.data,"NewFileName.txt");}
public function onSaveFileSelected(evt:Event):void{
fileRef.addEventListener(ProgressEvent.PROGRESS, onSaveProgress);
fileRef.addEventListener(Event.COMPLETE, onSaveComplete);
fileRef.addEventListener(Event.CANCEL, onSaveCancel);}public function onSaveProgress(evt:ProgressEvent):void{
trace("Saved " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes.");}public function onSaveComplete(evt:Event):void{
trace("File saved.");fileRef.removeEventListener(Event.SELECT, onSaveFileSelected);
fileRef.removeEventListener(ProgressEvent.PROGRESS, onSaveProgress);
fileRef.removeEventListener(Event.COMPLETE, onSaveComplete);
fileRef.removeEventListener(Event.CANCEL, onSaveCancel);}public function onSaveCancel(evt:Event):void{
trace("The save request was canceled by the user.");}public function onIOError(evt:IOErrorEvent):void{
trace("There was an IO Error.");}public function onSecurityError(evt:Event):void{
trace("There was a security error.");}}}

すべてのデータがファイルから読み込まれると、onComplete() メソッドが呼び出されます。onComplete() メソッドによってロードイベントのリスナーが削除され、saveFile() メソッドが呼び出されます。saveFile() メソッドは、FileReference.save() メ
ソッドを呼び出します。FileReference.save() メソッドは、新しいファイル名とファイル保存場所の入力をユーザーに求める
新しいダイアログボックスを開きます。他のイベントリスナーメソッドは、ファイル保存プロセスの処理が完了するまで進行状況をトレースします。

Adobe AIR の FileStream クラスには、ローカルファイルにデータを書き込むための機能が用意されています。664 ページの「ファイルの読み取りと書き込み」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

634

ファイルシステムの操作サーバーへのファイルのアップロード
Flash Player 9 以降、Adobe AIR 1.0 以降
サーバーにファイルをアップロードするには、まず browse() メソッドを呼び出して、ユーザーがファイルを選択できるようにします。次に、FileReference.upload() メソッドが呼び出されると、選択したファイルがサーバーに転送されます。ユー
ザーが FileReferenceList.browse() メソッドで複数のファイルを選択した場合は、それらのファイルを示す

FileReferenceList.fileList という配列が作成されます。その後、FileReference.upload() メソッドを使用して、各ファイルを個別にアップロードします。
注意：FileReference.browse() メソッドを使用する場合は、ファイルを 1 つだけアップロードできます。複数のファイルをアップロードできるようにするには、FileReferenceList.browse() メソッドを使用します。
デフォルトでは、ユーザーはシステムのファイルピッカーダイアログボックスを使用して、ローカルコンピューター上にある任意のタイプのファイルを選択できます。次のように FileFilter クラスを使用してファイルタイプのフィルターを作成し、browse() メソッドでファイルフィルターインスタンスの配列を指定することによって、選択できるファイルを限定することもできます。
var imageTypes:FileFilter = new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif;*.png");
var textTypes:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf");
var allTypes:Array = new Array(imageTypes, textTypes);var fileRef:FileReference = new FileReference();fileRef.browse(allTypes);

ユーザーがシステムのファイルピッカーでファイルを選択し、「開く」ボタンをクリックすると、Event.SELECT イベントが送出されます。FileReference.browse() メソッドを使用して、アップロードするファイルを選択する場合は、次のコードで

Web サーバーにファイルを送信します。
var fileRef:FileReference = new FileReference();fileRef.addEventListener(Event.SELECT, selectHandler);
fileRef.addEventListener(Event.COMPLETE, completeHandler);try{
var success:Boolean = fileRef.browse();}catch (error:Error){
trace("Unable to browse for files.");}function selectHandler(event:Event):void{
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm")
try{fileRef.upload(request);}
catch (error:Error){
trace("Unable to upload file.");}}function completeHandler(event:Event):void{
trace("uploaded");}

FileReference.upload() メソッドでは、URLRequest.method プロパティおよび URLRequest.data プロパティを使用し、POST メソッドまたは GET メソッドで変数のデータをサーバーに送信できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

635

ファイルシステムの操作

FileReference.upload() メソッドを使用してファイルをアップロードしようとすると、次のイベントが送出されます。

• open イベント（Event.OPEN）：アップロード処理が開始したときに送出されます。
• progress イベント（ProgressEvent.PROGRESS）：ファイルのデータバイトがアップロードされると定期的に送出されます。

• complete イベント（Event.COMPLETE）：ファイルのアップロード処理が正常に完了したときに送出されます。
• httpStatus イベント（HTTPStatusEvent.HTTP_STATUS）：HTTP エラーが原因でアップロード処理が失敗した場合に送出されます。

• httpResponseStatus イベント（HTTPStatusEvent.HTTP_RESPONSE_STATUS）：upload() または uploadUnencoded() メ
ソッドを呼び出して HTTP を介してデータにアクセスを試み、Adobe AIR で要求のステータスコードを検出して返すことができる場合に送出されます。

• securityError イベント（SecurityErrorEvent.SECURITY_ERROR）：セキュリティ侵害が原因でアップロード処理が失敗した場合に送出されます。

• uploadCompleteData イベント（DataEvent.UPLOAD_COMPLETE_DATA）：アップロードの正常終了後、サーバーからデータを受信したときに送出されます。

• ioError イベント（IOErrorEvent.IO_ERROR）：次のいずれかの原因でアップロードが失敗した場合に送出されます。
• Flash Player によるファイルの読み込み中、書き込み中、または転送中に入出力エラーが発生した場合。
• SWF ファイルが、認証（例 : ユーザー名とパスワード）を必要とするサーバーにファイルをアップロードしようとした場合。Flash Player には、アップロード時にユーザーがパスワードを入力する手段が用意されていません。
• url パラメーターに無効なプロトコルが指定されている場合。FileReference.upload() メソッドでは、HTTP またはHTTPS を使用する必要があります。
認証を必要とするサーバーに対する Flash Player のサポートは完全ではありません。認証用のユーザー名とパスワードを入力するダイアログボックスは、ブラウザープラグインまたは Microsoft ActiveX® コントロールを使用してブラウ
ザー上で実行される SWF ファイルにおいて、ダウンロードを実行する場合にのみ表示できます。プラグインまたは

ActiveX コントロールを使用する場合のアップロードと、スタンドアローン Player または外部 Player を使用する場合のアップロードおよびダウンロードでは、ファイル転送に失敗します。

Flash Player によるファイルのアップロードを受け付けるサーバースクリプトを ColdFusion で作成する場合は、次のようなコードを使用します。
<cffile action="upload" filefield="Filedata" destination="#ExpandPath('./')#" nameconflict="OVERWRITE" />この ColdFusion コードでは、Flash Player から送信されたファイルをアップロードし、ColdFusion テンプレートと同じディレクトリに保存します。同じ名前のファイルが既に存在する場合は上書きされます。このコードではファイルのアップロードに必要な最低限の処理しか行っていないため、実際の運用環境ではこのスクリプトを使用しないでください。データ
検証のコードを付け加えて、特定のファイルタイプ（イメージなど）についてのみアップロードを許可し、サーバーサイド
スクリプトなど危険が生じる可能性のあるファイルを受け付けないようにすることをお勧めします。
次のコードは PHP によるファイルのアップロード処理の例で、データ検証も実行します。このスクリプトでは、アップロー
ド先ディレクトリにアップロードするファイルの数を 10 個まで、ファイルサイズを 200 KB までに制限し、しかも、JPEG、

GIF、PNG のいずれかのファイルだけをアップロードしてファイルシステムに保存できるようにしています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

636

ファイルシステムの操作<?php$MAXIMUM_FILESIZE = 1024 * 200; // 200KB$MAXIMUM_FILE_COUNT = 10; // keep maximum 10 files on server
echo exif_imagetype($_FILES['Filedata']);if ($_FILES['Filedata']['size'] <= $MAXIMUM_FILESIZE){
move_uploaded_file($_FILES['Filedata']['tmp_name'], "./temporary/".$_FILES['Filedata']['name']);$type = exif_imagetype("./temporary/".$_FILES['Filedata']['name']);if ($type == 1 || $type == 2 || $type == 3){
rename("./temporary/".$_FILES['Filedata']['name'], "./images/".$_FILES['Filedata']['name']);}else{
unlink("./temporary/".$_FILES['Filedata']['name']);}}$directory = opendir('./images/');$files = array();
while ($file = readdir($directory)){
array_push($files, array('./images/'.$file, filectime('./images/'.$file)));}usort($files, sorter);if (count($files) > $MAXIMUM_FILE_COUNT){$files_to_delete = array_splice($files, 0, count($files) - $MAXIMUM_FILE_COUNT);
for ($i = 0; $i < count($files_to_delete); $i++){
unlink($files_to_delete[$i][0]);}}print_r($files);closedir($directory);function sorter($a, $b){if ($a[1] == $b[1]){return 0;}
else{
return ($a[1] < $b[1]) ? -1 : 1;}}?>

このアップロードスクリプトには、POST または GET リクエストメソッドを使用して追加の変数を渡すこともできます。追加の POST 変数をアップロードスクリプトに送信するには、次のようなコードを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

637

ファイルシステムの操作

var fileRef:FileReference = new FileReference();fileRef.addEventListener(Event.SELECT, selectHandler);
fileRef.addEventListener(Event.COMPLETE, completeHandler);
fileRef.browse();function selectHandler(event:Event):void{
var params:URLVariables = new URLVariables();params.date = new Date();params.ssid = "94103-1394-2345";
var request:URLRequest = new
URLRequest("http://www.yourdomain.com/FileReferenceUpload/fileupload.cfm");
request.method = URLRequestMethod.POST;
request.data = params;
fileRef.upload(request, "Custom1");}function completeHandler(event:Event):void{
trace("uploaded");}

上記の例では、URLVariables オブジェクトを作成してリモートのサーバーサイドスクリプトに送信しています。

ActionScript の以前のバージョンでは、変数をサーバーアップロードスクリプトに送信するには値をクエリ文字列に含めて渡す必要がありました。ActionScript 3.0 では、URLRequest オブジェクトを使用して POST または GET メソッドで変数をリモートスクリプトに送信できます。そのため、データのセット数が多い場合でも容易かつ簡潔に送信処理を記述できるよ
うになりました。変数の受け渡しに使用する GET または POST リクエストメソッドを指定するには、URLRequest.method プ
ロパティを URLRequestMethod.GET（GET メソッドの場合）または URLRequestMethod.POST（POST メソッドの場合）に設定します。
また、ActionScript 3.0 では、upload() メソッドに 2 番目のパラメーターを指定することで、デフォルトの Filedata アップ
ロードファイルフィールド名を変更できます。前のコード例では、この操作の例としてデフォルト値の Filedata を Custom1に置き換えています。

Flash Player のデフォルトではテストアップロードが試行されませんが、upload() メソッドの 3 番目のパラメーターに値
true を指定するとこの動作を変更できます。テストアップロードの目的は、実際のファイルアップロードを正常に実行できるかどうか試すことと、( 認証が必要な場合に ) 認証を通過できるかどうか確認することです。
注意：テストアップロードは、現在のところ Windows 版の各種 Flash Player でのみ実行されます。
ファイルのアップロードを処理するサーバースクリプトは、次の要素を含んでいる HTTP POST リクエストを受け付ける必要があります。

• Content-Type：値として multipart/form-data が設定されています。
• Content-Disposition：name 属性が "Filedata"、filename 属性が元のファイルの名前に設定されています。
FileReference.upload() メソッドの uploadDataFieldName パラメーターに値を指定すると、name 属性に独自の値を指定できます。

•

ファイルの内容を表すバイナリデータ。

HTTP POST リクエストの例を次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

638

ファイルシステムの操作

POST /handler.asp HTTP/1.1
Accept: text/*
Content-Type: multipart/form-data;boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
User-Agent: Shockwave FlashHost: www.mydomain.com
Content-Length: 421
Connection: Keep-Alive
Cache-Control: no-cache------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
Content-Disposition: form-data; name="Filename"sushi.jpg------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
Content-Disposition: form-data; name="Filedata"; filename="sushi.jpg"
Content-Type: application/octet-stream
Test File------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
Content-Disposition: form-data; name="Upload"
Submit Query------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6(actual file data,,,)

次に示すサンプルの HTTP POST 要求は、api_sig、api_key、auth_token の 3 つの POST 変数を送信します。この例では、カスタムアップロードデータフィールド名の値は "photo" です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

639

ファイルシステムの操作

POST /handler.asp HTTP/1.1
Accept: text/*
Content-Type: multipart/form-data;boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
User-Agent: Shockwave FlashHost: www.mydomain.com
Content-Length: 421
Connection: Keep-Alive
Cache-Control: no-cache------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7Content-Disposition: form-data; name="Filename"sushi.jpg------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7Content-Disposition: form-data; name="api_sig"
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7Content-Disposition: form-data; name="api_key"
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7Content-Disposition: form-data; name="auth_token"
XXXXXXXXXXXXXXXXXXXXXXX------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7Content-Disposition: form-data; name="photo"; filename="sushi.jpg"
Content-Type: application/octet-stream(actual file data,,,)------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7Content-Disposition: form-data; name="Upload"
Submit Query------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--

サーバーからのファイルのダウンロード
Flash Player 9 以降、Adobe AIR 1.0 以降
FileReference.download() メソッドを使用すると、サーバー上のファイルをユーザーがダウンロードできます。このメソッドには、request および defaultFileName の 2 つのパラメーターがあります。第 1 パラメーターには、ダウンロードするファイ
ルの URL を表す URLRequest オブジェクトを指定します。第 2 パラメーターはオプションです。ダウンロードファイルのダイアログボックスに表示されるデフォルトのファイル名を指定できます。2 番目のパラメーターの defaultFileName を省略
すると、指定した URL に含まれているファイル名が使用されます。
次のコードでは、SWF ファイルと同じディレクトリから index.xml というファイルをダウンロードします。
var request:URLRequest = new URLRequest("index.xml");var fileRef:FileReference = new FileReference();fileRef.download(request);

デフォルトの名前を index.xml ではなく currentnews.xml に設定するには、次のコードのように defaultFileName パラメー
ターを指定します。
var request:URLRequest = new URLRequest("index.xml");var fileToDownload:FileReference = new FileReference();fileToDownload.download(request, "currentnews.xml");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

640

ファイルシステムの操作

サーバーにあるファイルに意味のわかりにくい名前が付いている場合や、ファイル名がサーバーで自動生成される場合、ファイル名の変更は役立ちます。また、ファイルを直接ダウンロードするのではなくサーバーサイドスクリプトを使用してダウンロードする場合も、defaultFileName パラメーターを明示的に指定することをお勧めします。例えば、指定した URL
変数に基づいて特定のファイルをダウンロードするようなサーバーサイドスクリプトに対しては、defaultFileName パラメー
ターを指定する必要があります。指定しない場合、ダウンロードするファイルのデフォルトの名前はサーバーサイドスクリ
プトの名前と同じになります。
データ解析用サーバースクリプトを表す URL にパラメーターを追加すると、download() メソッドを使用してサーバーにデータを送信できます。次の ActionScript 3.0 コードでは、ColdFusion スクリプトに渡すパラメーターに基づいてドキュ
メントをダウンロードします。
package{import flash.display.Sprite;
import flash.net.FileReference;
import flash.net.URLRequest;
import flash.net.URLRequestMethod;
import flash.net.URLVariables;
public class DownloadFileExample extends Sprite{
private var fileToDownload:FileReference;
public function DownloadFileExample(){var request:URLRequest = new URLRequest();request.url = "http://www.[yourdomain].com/downloadfile.cfm";
request.method = URLRequestMethod.GET;
request.data = new URLVariables("id=2");
fileToDownload = new FileReference();try{
fileToDownload.download(request, "file2.txt");}
catch (error:Error){
trace("Unable to download file.");}}}}次のコードは "download.cfm" という ColdFusion スクリプトの例です。URL 変数の値に応じて、サーバー上にある 2 つのファイルのうちいずれかをダウンロードします。
<cfparam name="URL.id" default="1" /><cfswitch expression="#URL.id#"><cfcase value="2"><cfcontent type="text/plain" file="#ExpandPath('two.txt')#" deletefile="No" /></cfcase><cfdefaultcase><cfcontent type="text/plain" file="#ExpandPath('one.txt')#" deletefile="No" /></cfdefaultcase></cfswitch>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

641

ファイルシステムの操作

FileReferenceList クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
FileReferenceList クラスを使用すると、サーバーサイドスクリプトにアップロードするファイルをユーザーが指定できます。ファイルのアップロードについては、ユーザーが選択した個々のファイルに対して FileReference.upload() メソッドを呼び出すことによって処理する必要があります。
次のコードでは、2 つの FileFilter オブジェクト（imageFilter および textFilter）を作成し、それらを配列として
FileReferenceList.browse() メソッドに渡しています。これにより、OS のファイルダイアログボックスにはファイルタイプを指定するフィルターが 2 つ表示されます。
var imageFilter:FileFilter = new FileFilter("Image Files (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg;*.gif; *.png");var textFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf");
var fileRefList:FileReferenceList = new FileReferenceList();try{
var success:Boolean = fileRefList.browse(new Array(imageFilter, textFilter));}catch (error:Error){
trace("Unable to browse for files.");}FileReferenceList クラスを使用して複数のファイルを選択およびアップロードできるようにする場合も、ファイルの選択はFileReference.browse() と同様に行いますが、複数のファイルを選択できる点が異なります。複数のファイルをアップロード
する際は、次のコードのように FileReference.upload() を使用して、選択した個々のファイルをアップロードする必要があります。
var fileRefList:FileReferenceList = new FileReferenceList();fileRefList.addEventListener(Event.SELECT, selectHandler);
fileRefList.browse();function selectHandler(event:Event):void{
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm");
var file:FileReference;var files:FileReferenceList = FileReferenceList(event.target);var selectedFileArray:Array = files.fileList;for (var i:uint = 0; i < selectedFileArray.length; i++){file = FileReference(selectedFileArray[i]);file.addEventListener(Event.COMPLETE, completeHandler);try{file.upload(request);}
catch (error:Error){
trace("Unable to upload files.");}}}function completeHandler(event:Event):void{
trace("uploaded");}

配列内の各 FileReference オブジェクトに Event.COMPLETE イベントが追加されているので、各ファイルのアップロードが完了するたびに、Flash Player によって completeHandler() メソッドが呼び出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

642

ファイルシステムの操作

AIR ファイルシステム API の使用
Adobe AIR 1.0 およびそれ以降
Adobe AIR ファイルシステム API には、次のクラスがあります。

• File• FileMode• FileStream
AIR ファイルシステム API を利用して、次のような処理を実行できます（これに限りません）。

•

ディレクトリのコピー、作成、削除、移動•

ファイルおよびディレクトリに関する情報の取得•

ファイルの読み取りと書き込み

AIR ファイルの基礎
Adobe AIR 1.0 およびそれ以降
AIR でのファイルシステムの操作に関する簡単な説明およびコード例については、Adobe Developer Connection で次のクイックスタートの記事を参照してください。

•

テキストファイルエディターの構築（Flash）•

テキストファイルエディターの構築（Flex）•

ディレクトリ検索アプリケーションの構築（Flex）• XML 環境設定ファイルの読み取りと書き込み（Flex）•

ファイルとデータの圧縮（Flex）

Adobe AIR には、ファイルとフォルダーの両方に対するアクセス、作成および管理に使用できるクラスが用意されています。これらのクラスは、flash.filesystem パッケージに含まれており、次のように使用します。
File クラス
File

説明

File オブジェクトは、ファイルまたはディレクトリへのパスを表します。File オブジェクトを使用してファイルまたはフォルダーへのポインターを作成することで、ファイルまたはフォルダーの操作を実行できるようになります。

FileMode

FileMode クラスは、fileMode パラメーターで使用されるストリング定数を定義します。このパラメーター
は、FileStream クラスの open() メソッドおよび openAsync() メソッドで指定します。これらのメソッドの

fileMode パラメーターによって、ファイルが開かれたときに FileStream オブジェクトで使用できる機能（書き込み、読み取り、追加および更新）が決まります。

FileStream

FileStream オブジェクトは、ファイルを開いて読み取りと書き込みを行うために使用されます。新規または既存のファイルを参照する File オブジェクトを作成してそのポインターを FileStream オブジェクトに渡すと、そのファイルを開いて、データの読み取りまたは書込みができるようになります。

File クラスのメソッドには、同期バージョンと非同期バージョンの両方を持つものがあります。

• File.copyTo() と File.copyToAsync()• File.deleteDirectory() と File.deleteDirectoryAsync()• File.deleteFile() と File.deleteFileAsync()

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

643

ファイルシステムの操作• File.getDirectoryListing() と File.getDirectoryListingAsync()• File.moveTo() と File.moveToAsync()• File.moveToTrash() と File.moveToTrashAsync()
また、FileStream 操作の処理も、同期的に行われる場合と非同期で行われる場合があります。どちらで処理されるかは、

FileStream オブジェクトでファイルを開く際に open() メソッドを呼び出したか openAsync() メソッドを呼び出したかによって決まります。
非同期バージョンで処理を開始すると、バックグラウンドで処理が実行され、完了時（またはエラーイベントの発生時）にイベントが送出されます。これらの非同期のバックグラウンド処理を実行している間に、他のコードを実行することができます。非同期バージョンの操作では、イベントリスナー関数を設定する必要があります。イベントリスナー関数を設定するには、その関数を呼び出す File オブジェクトまたは FileStream オブジェクトの addEventListener() メソッドを使用します。
同期バージョンでは、イベントリスナーを設定する必要がない、より単純なコードを記述できます。ただし、同期メソッドの実行中は他のコードを実行できないので、表示オブジェクトのレンダリングやアニメーションなどの重要な処理が遅延することがあります。

AIR での File オブジェクトの操作
Adobe AIR 1.0 およびそれ以降
File オブジェクトは、ファイルシステム内のファイルまたはディレクトリへのポインターです。
File クラスは FileReference クラスを拡張します。FileReference クラス（Adobe® Flash® Player および AIR で利用可能）
はファイルへのポインターを表します。File クラスには、セキュリティ上の考慮事項により Flash Player（ブラウザーで実行している SWF ファイル）で公開されていない追加のプロパティおよびメソッドがあります。

File クラスについて
Adobe AIR 1.0 およびそれ以降
File クラスを使用して以下を実行できます。

•

特殊なディレクトリへのパスの取得（ユーザーディレクトリ、ユーザーのドキュメントディレクトリ、アプリケーションが起動されたディレクトリ、アプリケーションディレクトリなど）•

ファイルおよびディレクトリのコピー•

ファイルおよびディレクトリの移動•

ファイルおよびディレクトリの削除（またはごみ箱への移動）•

ディレクトリに格納されているファイルおよびディレクトリの一覧の出力•

一時ファイルおよび一時フォルダーの作成

File オブジェクトでファイルパスを参照すると、FileStream クラスでそれを使用してファイルデータの読み取りと書き込みができるようになります。

File オブジェクトでは、まだ存在しないファイルまたはディレクトリのパスを参照できます。このような File オブジェクト
は、ファイルまたはディレクトリの作成に使用できます。

File オブジェクトのパス
Adobe AIR 1.0 およびそれ以降
各 File オブジェクトには、そのオブジェクトのパスをそれぞれ定義する 2 つのプロパティがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

644

ファイルシステムの操作

プロパティ

説明

nativePath

ファイルへのプラットフォーム固有のパスを指定します。例えば、Windows では「c:¥Sample

directory¥test.txt」、Mac OS では「/Sample directory/test.txt」のようになります。nativePath プロパ
ティでは、ディレクトリの区切り文字として、Windows では円記号（¥）、Mac OS および Linux ではス
ラッシュ（/）を使用します。

urlfile URL スキームを使用してファイルを参照できます。例えば、Windows では「file:///c:/Sample%20directory/test.txt」、Mac OS では「file:///Sample%20directory/test.txt」のよ
うになります。ランタイムには、file 以外にも特殊な URL スキームが含まれます。それらについては、

652 ページの「サポートされる AIR URL スキーム」で説明します。

File クラスには、Mac OS、Windows および Linux の標準のディレクトリを参照するための静的プロパティが含まれます。
これらのプロパティは次のとおりです。

• File.applicationStorageDirectory - インストールされている各 AIR アプリケーションに固有の記憶領域ディレクトリ。このディレクトリは、動的なアプリケーションのアセットとユーザー環境設定の格納に適した場所です。データが大量の場合
は、他の場所への格納を検討してください。

Android および iOS では、アプリケーションをアンインストールした場合、またはユーザーがアプリケーションデータ
を消去するよう選択した場合に、アプリケーション記憶領域ディレクトリが削除されますが、これは他のプラットフォー
ムには当てはまりません。

• File.applicationDirectory - アプリケーションがインストールされている（インストールされるアセットがある場合はそれらも含まれる）ディレクトリ。一部のオペレーティングシステムでは、物理ディレクトリではなく単一のパッケージファ
イルにアプリケーションが格納されます。この場合、ネイティブパスを使用してコンテンツにアクセスできない可能性があります。アプリケーションディレクトリは読み取り専用です。

• File.desktopDirectory - ユーザーのデスクトップディレクトリ。デスクトップディレクトリがプラットフォームで定義されていない場合は、ファイルシステム上の別の場所が使用されます。

• File.documentsDirectory - ユーザーのドキュメントディレクトリ。ドキュメントディレクトリがプラットフォームで定義されていない場合は、ファイルシステム上の別の場所が使用されます。

• File.userDirectory - ユーザーディレクトリ。ユーザーディレクトリがプラットフォームで定義されていない場合は、ファイルシステム上の別の場所が使用されます。
注意：デスクトップディレクトリ、ドキュメントディレクトリ、またはユーザーディレクトリの標準の場所がプラットフォームで定義されていない場合、File.documentsDirectory、File.desktopDirectory、および File.userDirectory は同じディレ
クトリを参照できます。
これらのプロパティには、オペレーティングシステムに応じて異なる値が設定されています。例えば、Mac と Windows で設定されているユーザーのデスクトップディレクトリのネイティブパスはそれぞれ異なります。ただし、File.desktopDirectory プロパティは、すべてのプラットフォーム上の適切なディレクトリパスを参照します。複数のプラットフォームにわたって正常に機能するアプリケーションを作成するには、アプリケーションが使用する他のディレクトリやファイルを参照する土台としてこれらのプロパティを使用します。次に、resolvePath() メソッドを使用してパスの詳細を設定します。例えば、次のコードは、アプリケーション記憶領域ディレクトリの preferences.xml ファイルを参照しています。
var prefsFile:File = File.applicationStorageDirectory;
prefsFile = prefsFile.resolvePath("preferences.xml");

File クラスでは特定のファイルパスを参照できますが、その場合、アプリケーションが複数のプラットフォームにわたって機能しなくなる可能性があります。例えば、C:¥Documents and Settings¥joe¥ というパスは、Windows 上でのみ機能します。このような理由から、File.documentsDirectory などの File クラスの静的プロパティを使用することをお勧めします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

645

ファイルシステムの操作

一般的なディレクトリの場所
プラット
フォーム

ディレクトリの種類

一般的なファイルシステムの場所

Android

アプリケーション/data/data/

アプリケーション記憶領域/data/data/air.applicationID/filename/Local Storeキャッシュ/data/data/applicationID/cache

デスクトップ/mnt/sdcard

ドキュメント/mnt/sdcard

一時/data/data/applicationID/cache/FlashTmp.randomString

ユーザー/mnt/sdcard

アプリケーション/var/mobile/Applications/uid/filename.app

アプリケーション記憶領域/var/mobile/Applications/uid/Library/Application Support/applicationID/Local Storeキャッシュ/var/mobile/Applications/uid/Library/Caches

デスクトップ

アクセス不可ドキュメント/var/mobile/Applications/uid/Documents

一時/private/var/mobile/Applications/uid/tmp/FlashTmpNNN

ユーザー

アクセス不可アプリケーション/opt/filename/share

アプリケーション記憶領域/home/userName/.appdata/applicationID/Local Store

デスクトップ/home/userName/Desktop

ドキュメント/home/userName/Documents

一時/tmp/FlashTmp.randomString

ユーザー/home/userName

アプリケーション/Applications/filename.app/Contents/Resources

アプリケーション記憶領域/Users/userName/Library/Preferences/applicationid/Local Store（AIR 3.2 以前）

iOS

Linux

Mac

キャッシュ
デスクトップドキュメント
一時
ユーザー

path/Library/Application Support/applicationid/Local Store（AIR 3.3 以降）。path は/Users/userName/Library/Containers/bundle-id/Data（サンドボックス化した環境の場合）または /Users/userName（サンドボックス化した環境外で実行する場合）/Users/userName/Library/Caches/Users/userName/Desktop/Users/userName/Documents/private/var/folders/JY/randomString/TemporaryItems/FlashTmp/Users/userName

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

646

ファイルシステムの操作

プラット
フォーム

ディレクトリの種類

一般的なファイルシステムの場所

Windows

アプリケーション

C:¥Program Files¥filename

アプリケーション記憶領
域

C:¥Documents and settings¥userName¥ApplicationData¥applicationID¥Local Store

キャッシュ

C:¥Documents and settings¥userName¥Local Settings¥Temp

デスクトップC:¥Documents and settings¥userName¥Desktop

ドキュメントC:¥Documents and settings¥userName¥My Documents

一時C:¥Documents and settings¥userName¥Local Settings¥Temp¥randomString.tmp

ユーザー

C:¥Documents and settings¥userName

これらのディレクトリの実際のネイティブパスは、オペレーティングシステムとコンピューターの構成によって異なります。
この表には、典型的なパスの例を示しています。プラットフォーム上でアプリケーションを正しく動作させるには、これらのディレクトリを参照する適切な File クラスの静的プロパティを使用する必要があります。実際の AIR アプリケーションでは、この表に示す applicationID と filename の値はアプリケーション記述子から取得されます。アプリケーション記述子に発行者 ID を指定すると、その発行者 ID がこれらのパスのアプリケーション ID に追加されます。userName の値は、インストールを行うユーザーのアカウント名です。

File オブジェクトでのディレクトリの参照
Adobe AIR 1.0 およびそれ以降
File オブジェクトでディレクトリの参照を設定するには、様々な方法があります。
ユーザーのホームディレクトリの参照

Adobe AIR 1.0 およびそれ以降
File オブジェクトでユーザーのホームディレクトリを参照できます。次のコードでは、ホームディレクトリの AIR Test サ
ブディレクトリを参照するように File オブジェクトを設定しています。
var file:File = File.userDirectory.resolvePath("AIR Test");

ユーザーのドキュメントディレクトリの参照

Adobe AIR 1.0 およびそれ以降
File オブジェクトでユーザーのドキュメントディレクトリを参照できます。次のコードでは、ドキュメントディレクトリの
AIR Test サブディレクトリを参照するように File オブジェクトを設定しています。
var file:File = File.documentsDirectory.resolvePath("AIR Test");

デスクトップディレクトリの参照

Adobe AIR 1.0 およびそれ以降
File オブジェクトでデスクトップを参照できます。次のコードでは、デスクトップの AIR Test サブディレクトリを参照するように File オブジェクトを設定しています。
var file:File = File.desktopDirectory.resolvePath("AIR Test");最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

647

ファイルシステムの操作

アプリケーション記憶領域ディレクトリの参照

Adobe AIR 1.0 およびそれ以降
File オブジェクトでアプリケーション記憶領域ディレクトリを参照できます。AIR アプリケーションにはそれぞれ、アプリ
ケーション記憶領域ディレクトリを定義する一意のパスが関連付けられています。このディレクトリは、アプリケーション
およびユーザーごとに一意に割り当てられます。このディレクトリは、ユーザーおよびアプリケーションに固有のデータ（ユーザーデータや環境設定ファイルなど）を格納するために使用できます。例えば、次のコードでは、アプリケーション記
憶領域ディレクトリに格納されている prefs.xml という環境設定ファイルを File オブジェクトで参照します。
var file:File = File.applicationStorageDirectory;
file = file.resolvePath("prefs.xml");

通常、アプリケーション記憶領域ディレクトリの場所は、ユーザー名とアプリケーション ID に基づきます。次に示すファ
イルシステムの場所は、アプリケーションをデバッグする場合に使用できます。このディレクトリ内のファイルを解決するには、File.applicationStorage プロパティまたは app-storage: URI スキームを常に使用する必要があります。

• Mac OS の場合（AIR バージョンごとに異なる）：
AIR 3.2 以前：/Users/user name/Library/Preferences/applicationID/Local Store/
AIR 3.3 以降：path/Library/Application Support/applicationID/Local Store。path は/Users/username/Library/Containers/bundle-id/Data（サンドボックス化した環境の場合）または /Users/username（サンドボックス化した環境外で実行する場合）
例（AIR 3.2）：/Users/babbage/Library/Preferences/com.example.TestApp/Local Store• Windows の場合（Documents and Settings ディレクトリ内）
C:¥Documents and Settings\user name\Application Data\applicationID¥Local Store¥
次に、例を示します。
C:\Documents and Settings\babbage\Application Data\com.example.TestApp\Local Store• Linux の場合/home/user name/.appdata/applicationID/Local Store/
次に、例を示します。
/home/babbage/.appdata/com.example.TestApp/Local Store• Android の場合/data/data/androidPackageID/applicationID/Local Store
次に、例を示します。
/data/data/air.com.example.TestApp/com.example.TestApp/Local Store

注意：アプリケーションに発行者 ID がある場合、発行者 ID はアプリケーション記憶領域ディレクトリへのパスとしても使用されます。

File.applicationStorageDirectory で作成された File オブジェクトの URL （および url プロパティ）では、次のように appstorage URL スキーム（652 ページの「サポートされる AIR URL スキーム」を参照）が使用されます。
var dir:File = File.applicationStorageDirectory;
dir = dir.resolvePath("preferences");
trace(dir.url); // app-storage:/preferences

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

648

ファイルシステムの操作

アプリケーションディレクトリの参照

Adobe AIR 1.0 およびそれ以降
File オブジェクトで、アプリケーションがインストールされたディレクトリ（アプリケーションディレクトリ）を参照できます。このディレクトリを参照するには、File.applicationDirectory プロパティを使用します。このディレクトリでは、アプ
リケーション記述ファイルなど、アプリケーションと共にインストールされたリソースを確認できます。例えば、次のコー
ドでは、アプリケーションディレクトリにある images というディレクトリを File オブジェクトで参照します。
var dir:File = File.applicationDirectory;
dir = dir.resolvePath("images");File.applicationDirectory で作成された File オブジェクトの URL （および url プロパティ）では、次のように app URL ス
キーム（652 ページの「サポートされる AIR URL スキーム」を参照）が使用されます。
var dir:File = File.applicationDirectory;
dir = dir.resolvePath("images");
trace(dir.url); // app:/images

注意：Android では、nativePath を使用してアプリケーションパッケージ内のファイルにアクセスすることはできません。

nativePath プロパティは空のストリングです。アプリケーションディレクトリ内のファイルにアクセスする場合は、ネイ
ティブパスではなく必ず URL を使用してください。
キャッシュディレクトリの参照

Adobe AIR 3.6 およびそれ以降
File.cacheDirectory プロパティを使用して、File オブジェクトで、オペレーティングシステムの一時ディレクトリまたはキャッシュディレクトリを参照できます。このディレクトリには、アプリケーションの実行には必要のない一時ファイルが含まれており、これらのファイルを削除しても、データ損失などの問題が発生することはありません。
ほとんどのオペレーティングシステムで、キャッシュディレクトリは一時ディレクトリです。iOS では、キャッシュディレ
クトリは、アプリケーションライブラリの Caches ディレクトリに対応します。このディレクトリ内のファイルはオンライ
ン記憶領域にバックアップされず、デバイスの記憶領域の空き容量が少なすぎる場合は、オペレーティングシステムによって削除される可能性があります。詳しくは、652 ページの「ファイルのバックアップとキャッシュの制御」を参照してくだ
さい。
ファイルシステムルートの参照

Adobe AIR 1.0 およびそれ以降
File.getRootDirectories() メソッドは、すべてのルートボリュームの一覧を出力します。Windows コンピューターの場合は、
C: およびマウントされたボリュームが含まれます。Mac OS および Linux の場合は、常にマシンの一意のルートディレクト
リ（「/」ディレクトリ）が返されます。StorageVolumeInfo.getStorageVolumes() メソッドは、マウントされたストレージボ
リュームに関する詳細を提供します（663 ページの「ストレージボリュームの操作」を参照）。
注意：Android では、ファイルシステムのルートを読み取ることはできません。ネイティブパス「/」を含むディレクトリ
を参照する File オブジェクトが返されますが、そのオブジェクトのプロパティには正確な値が指定されていません。例えば、spaceAvailable は常に 0 になります。
明示的なディレクトリの参照

Adobe AIR 1.0 およびそれ以降
File オブジェクトの nativePath プロパティを設定することにより、File オブジェクトで明示的なディレクトリを参照できます。Windows の場合の例を次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

649

ファイルシステムの操作

var file:File = new File();file.nativePath = "C:\\AIR Test";

重要：このような方法で明示的なパスを参照すると、コードが複数のプラットフォームにわたって機能しなくなる可能性があります。例えば、前の例は Windows 上でのみ機能します。クロスプラットフォームで機能するディレクトリを見つけるには、File.applicationStorageDirectory などの File オブジェクトの静的プロパティを使用します。次に、resolvePath() メソッド（次の節を参照）を使用して、相対パスに移動します。
相対パスのナビゲーション

Adobe AIR 1.0 およびそれ以降
resolvePath() メソッドを使用すると、別の特定のパスを基準とした相対的なパスを取得できます。例えば、次のコードでは、ユーザーのホームディレクトリの AIR Test サブディレクトリを参照するように File オブジェクトを設定しています。
var file:File = File.userDirectory;
file = file.resolvePath("AIR Test");

また、次のように、File オブジェクトの url プロパティを使用すると、URL ストリングに基づいてディレクトリを参照する
こともできます。
var urlStr:String = "file:///C:/AIR Test/";var file:File = new File()
file.url = urlStr;

詳しくは、651 ページの「File パスの変更」を参照してください。
参照するディレクトリの選択

Adobe AIR 1.0 およびそれ以降
File クラスの browseForDirectory() メソッドを使用すると、ユーザーがオブジェクトに割り当てるディレクトリを選択できるシステムダイアログボックスを表示できます。browseForDirectory() メソッドは、非同期のメソッドです。File オブジェク
トでは、ユーザーがディレクトリを選択して「開く」ボタンをクリックすると select イベントを送出し、ユーザーが「キャンセル」ボタンをクリックすると cancel イベントを送出します。
例えば、次のコードでは、ユーザーがディレクトリを選択できるようにし、その選択に応じたディレクトリパスを出力します。
var file:File = new File();file.addEventListener(Event.SELECT, dirSelected);
file.browseForDirectory("Select a directory");function dirSelected(e:Event):void {trace(file.nativePath);}

注意：Android では、browseForDirectory() メソッドはサポートされていません。このメソッドを呼び出しても効果はありません。すぐに cancel イベントが送出されます。ユーザーがディレクトリを選択できるようにするには、代わりにアプリ
ケーションで定義されているカスタムダイアログを使用します。
アプリケーションを起動したディレクトリの参照

Adobe AIR 1.0 およびそれ以降
アプリケーションを起動したディレクトリの場所を取得するには、アプリケーションの起動時に送出された InvokeEvent
オブジェクトの currentDirectory プロパティを確認します。詳しくは、845 ページの「コマンドライン引数のキャプチャ」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

650

ファイルシステムの操作

File オブジェクトでのファイルの参照
Adobe AIR 1.0 およびそれ以降
File オブジェクトで参照するファイルを設定するには、様々な方法があります。
明示的なファイルパスの参照

Adobe AIR 1.0 およびそれ以降
重要：明示的なパスを参照すると、コードが複数のプラットフォームにわたって機能しなくなる可能性があります。例えば、

C:¥foo.txt というパスは、Windows 上でのみ機能します。クロスプラットフォームで機能するディレクトリを見つけるには、File.applicationStorageDirectory などの File オブジェクトの静的プロパティを使用します。次に、resolvePath() メソッド
（651 ページの「File パスの変更」を参照）を使用して、相対パスに移動します。
次のように、File オブジェクトの url プロパティを使用すると、URL ストリングに基づいてファイルまたはディレクトリを
参照できます。
var urlStr:String = "file:///C:/AIR Test/test.txt";
var file:File = new File()
file.url = urlStr;

URL は、次のように File() コンストラクター関数に渡すこともできます。
var urlStr:String = "file:///C:/AIR Test/test.txt";
var file:File = new File(urlStr);url プロパティでは、常に URI エンコード形式の URL が返されます（例えば、スペースは "%20 に置き換えられます）。
file.url = "file:///c:/AIR Test";
trace(file.url); // file:///c:/AIR%20Test

また、File オブジェクトの nativePath プロパティを使用して明示的なパスを設定することもできます。例えば、次のコード
を Windows コンピューターで実行すると、C: ドライブの AIR Test サブディレクトリにある test.txt ファイルを参照するよ
うに File オブジェクトが設定されます。
var file:File = new File();file.nativePath = "C:/AIR Test/test.txt";

このパスは、次のように File() コンストラクター関数に渡すこともできます。
var file:File = new File("C:/AIR Test/test.txt");

nativePath プロパティのパス区切り文字としては、スラッシュ（/）を使用します。Windows では、円記号（¥）も使用できますが、その場合、アプリケーションが複数のプラットフォームにわたって機能しなくなる可能性があります。
詳しくは、651 ページの「File パスの変更」を参照してください。
ディレクトリ内のファイルの列挙

Adobe AIR 1.0 およびそれ以降
File オブジェクトの getDirectoryListing() メソッドを使用すると、ディレクトリのルートレベルにあるファイルおよびサブディレクトリを参照する File オブジェクトの配列を取得することができます。詳しくは、658 ページの「ディレクトリの列挙」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

651

ファイルシステムの操作

参照するファイルの選択

Adobe AIR 1.0 およびそれ以降
File クラスには、ユーザーがオブジェクトに割り当てるファイルを選択できるシステムダイアログボックスを表示する以下のメソッドがあります。

• browseForOpen()• browseForSave()• browseForOpenMultiple()
これらのメソッドでは、いずれも非同期で処理が行われます。browseForOpen() メソッドと browseForSave() メソッドでは、ユーザーがファイル（browseForSave() の場合はターゲットパス）を選択すると select イベントを送出します。

browseForOpen() メソッドと browseForSave() メソッドのターゲットの File オブジェクトは、その選択に応じて、選択されたファイルを参照します。browseForOpenMultiple() メソッドでは、ユーザーがファイルを選択すると selectMultiple イベントを送出します。selectMultiple イベントは FileListEvent 型のイベントで、その files プロパティに（選択されたファイルを参照する）File オブジェクトの配列が格納されます。
例えば、次のコードでは、ファイルを選択するための「開く」ダイアログボックスが表示されます。
var fileToOpen:File = File.documentsDirectory;
selectTextFile(fileToOpen);function selectTextFile(root:File):void{
var txtFilter:FileFilter = new FileFilter("Text", "*.as;*.css;*.html;*.txt;*.xml");root.browseForOpen("Open", [txtFilter]);root.addEventListener(Event.SELECT, fileSelected);}function fileSelected(event:Event):void{
trace(fileToOpen.nativePath);}

アプリケーションで別の参照ダイアログボックスが開かれている場合に参照メソッドを呼び出すと、ランタイムから Error
例外がスローされます。
注意：Android で browseForOpen() メソッドと browseForOpenMultiple() メソッドを使用して選択できるのは、イメージ
ファイル、ビデオファイル、およびオーディオファイルのみです。また、ユーザーが任意のファイル名を入力できる場合でも、browseForSave() ダイアログにはメディアファイルのみ表示されます。メディアファイル以外のファイルを開いたり保存したりするには、これらのメソッドの代わりにカスタムダイアログの使用を検討する必要があります。

File パスの変更
Adobe AIR 1.0 およびそれ以降
resolvePath() メソッドを呼び出すか、オブジェクトの nativePath プロパティまたは url プロパティを変更することにより、既存の File オブジェクトのパスを変更することもできます。Windows の場合の例を次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

652

ファイルシステムの操作

var file1:File = File.documentsDirectory;
file1 = file1.resolvePath("AIR Test");trace(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test
var file2:File = File.documentsDirectory;
file2 = file2.resolvePath("..");
trace(file2.nativePath); // C:\Documents and Settings\userName
var file3:File = File.documentsDirectory;
file3.nativePath += "/subdirectory";
trace(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectoryvar file4:File = new File();file4.url = "file:///c:/AIR Test/test.txt";
trace(file4.nativePath); // C:\AIR Test\test.txt

nativePath プロパティを使用する場合、ディレクトリの区切り文字としてスラッシュ（/）を使用します。Windows では、
円記号（¥）も使用できますが、コードがクロスプラットフォームで機能しなくなるため、それは避ける必要があります。

サポートされる AIR URL スキーム
Adobe AIR 1.0 およびそれ以降
AIR における File オブジェクトの url プロパティの定義では、以下のいずれかの URL スキームを使用できます。
URL スキーム

説明

file

ファイルシステムのルートを基準とした相対的なパスを指定する場合に使用します。次に、例を示します。
file:///c:/AIR Test/test.txt

file URL を指定する標準的な URL の形式は、file://<host>/<path> です。例外として、<host> のストリングは
空にすることができます。その場合、「URL の解釈を行っているマシン」を示すものと解釈されます。そのため、file URL では、スラッシュが 3 つ連なる（///）ことがよくあります。
app

インストールされたアプリケーションのルートディレクトリ（インストールされたアプリケーションのapplication.xml ファイルが格納されたディレクトリ）を基準とした相対的なパスを指定する場合に使用します。例えば、次のパスは、インストールされているアプリケーションのディレクトリの images サブディレクト
リを参照しています。
app:/images

app-storage

アプリケーション記憶領域ディレクトリを基準とした相対的なパスを指定する場合に使用します。AIR では、インストールされたアプリケーションごとに、一意のアプリケーション記憶領域ディレクトリが定義されます。このディレクトリは、そのアプリケーション固有のデータを格納するための便利な場所として使用できます。例えば、次のパスは、アプリケーション記憶領域ディレクトリの settings サブディレクトリにある prefs.xml ファ
イルを参照しています。
app-storage:/settings/prefs.xml

ファイルのバックアップとキャッシュの制御
Adobe AIR 3.6 およびそれ以降、iOS および OS X のみ
iOS や Mac OS X を始めとする特定のオペレーティングシステムでは、アプリケーションファイルをリモート記憶領域に自動的にバックアップできます。さらに、iOS では、ファイルがバックアップ可能かどうかや、目的の異なるファイルの保存場所に関して制限があります。
ファイルのバックアップや記憶領域に関する Apple のガイドラインに準拠する方法について、次にまとめます。詳しくは、これ以降のセクションを参照してください。

•

特定のファイルに関して、バックアップが不要で、（iOS のみ）デバイスの記憶領域が少ない場合にオペレーティングシ
ステムによって削除できるように指定するには、そのファイルをキャッシュディレクトリ（File.cacheDirectory）に保存します。これは iOS 上の推奨される保存場所です。再生成や再ダウンロードが可能なほとんどのファイルに使用してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

653

ファイルシステムの操作•

特定のファイルに関して、バックアップが不要なものの、オペレーティングシステムによって削除されないように指定す
るには、そのファイルを、アプリケーション記憶領域ディレクトリ（File.applicationStorageDirectory）やドキュメント
ディレクトリ（File.documentsDirectory）などのアプリケーションライブラリディレクトリに保存します。File オブジェ
クトの preventBackup プロパティを true に設定します。これは、再生成や再ダウンロードが可能なものの、オフライン使
用時にアプリケーションが適切に機能するために必要なコンテンツに関して、Apple が必須としている設定です。

バックアップ用ファイルの指定
バックアップ容量を節約し、ネットワーク帯域幅の使用率を抑えるために、iOS および Mac のアプリケーションに関するApple のガイドラインでは、ユーザーが入力したデータやその他の理由で再生成や再ダウンロードができないデータを含むファイルのみをバックアップ対象として指定するよう定められています。
デフォルトでは、アプリケーションライブラリフォルダー内のすべてのファイルがバックアップされます。Mac OS X では、
これはアプリケーション記憶領域ディレクトリです。iOS では、これにはアプリケーション記憶領域ディレクトリ、アプリ
ケーションディレクトリ、デスクトップディレクトリ、ドキュメントディレクトリ、ユーザーディレクトリが含まれます（これらのディレクトリは iOS 上のアプリケーションライブラリフォルダーにマップされているため）。その結果、これらのディレクトリ内のファイルはすべて、デフォルトでサーバー記憶領域にバックアップされます。
使用しているアプリケーションで再作成可能なファイルをこれらの場所に保存する場合は、オペレーティングシステムにバックアップしないよう知らせるために、該当するファイルにフラグを付ける必要があります。特定のファイルをバックアップしないよう指定するには、File オブジェクトの preventBackup プロパティを true に設定します。

iOS では、いずれかのアプリケーションライブラリフォルダーに含まれるファイルに関して、preventBackup プロパティがtrue に設定されている場合でも、そのファイルには、オペレーティングシステムによって削除されない永続ファイルとしてフラグが付けられます。
ファイルのキャッシュと削除の制御

iOS アプリケーションに関する Apple のガイドラインでは、可能な限り、デバイスの記憶領域の容量が少なくなった場合に、再生成が可能なコンテンツをオペレーティングシステムが削除できるようにするよう定められています。

iOS では、アプリケーションライブラリフォルダー（アプリケーション記憶領域ディレクトリやドキュメントディレクトリ
など）内のファイルは、永続ファイルとしてフラグが付けられ、オペレーティングシステムによって削除されることはありません。
アプリケーションで再生成でき、記憶領域の容量が少ない場合に削除しても安全なファイルは、アプリケーションキャッ
シュディレクトリに保存してください。キャッシュディレクトリには、File.cacheDirectory 静的プロパティを使用してアクセスします。

iOS では、キャッシュディレクトリはアプリケーションのキャッシュディレクトリ（<Application
Home>/Library/Caches）に対応します。その他のオペレーティングシステムでは、このディレクトリは同等のディレクト
リにマップされます。例えば、Mac OS X では、アプリケーションライブラリ内の Caches ディレクトリにもマップします。
Android では、キャッシュディレクトリはアプリケーションのキャッシュディレクトリにマップします。Windows では、キャッシュディレクトリはオペレーティングシステムの TEMP ディレクトリにマップします。Android でも Windows でも、これは、File クラスの createTempDirectory() メソッドおよび createTempFile() メソッドに対する呼び出しによってアクセスする同じディレクトリです。

2 つのファイル間の相対パスの取得
Adobe AIR 1.0 およびそれ以降
getRelativePath() メソッドを使用すると、2 つのファイル間の相対パスを取得できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

654

ファイルシステムの操作

var file1:File = File.documentsDirectory.resolvePath("AIR Test");var file2:File = File.documentsDirectory
file2 = file2.resolvePath("AIR Test/bob/test.txt");
trace(file1.getRelativePath(file2)); // bob/test.txt

getRelativePath() メソッドの 2 番目のパラメーターである useDotDot パラメーターを使用すると、.. シンタックスを結果として返して、親ディレクトリを示すことができるようになります。
var file1:File = File.documentsDirectory;
file1 = file1.resolvePath("AIR Test");var file2:File = File.documentsDirectory;
file2 = file2.resolvePath("AIR Test/bob/test.txt");
var file3:File = File.documentsDirectory;
file3 = file3.resolvePath("AIR Test/susan/test.txt");
trace(file2.getRelativePath(file1, true)); // ../..
trace(file3.getRelativePath(file2, true)); // ../../bob/test.txt

標準化バージョンのファイル名の取得
Adobe AIR 1.0 およびそれ以降
Windows および Mac OS では、ファイル名およびパス名で大文字と小文字が区別されません。次のような場合、2 つのFile オブジェクトで同じファイルが参照されます。
File.documentsDirectory.resolvePath("test.txt");
File.documentsDirectory.resolvePath("TeSt.TxT");

ただし、実際のドキュメント名やディレクトリ名には大文字も使用されます。例えば、次の例では、ドキュメントディレク
トリに AIR Test というフォルダーがあることを前提にしています。
var file:File = File.documentsDirectory.resolvePath("AIR test");trace(file.nativePath); // ... AIR test
file.canonicalize();
trace(file.nativePath); // ... AIR Testcanonicalize() メソッドでは、大文字と小文字が区別された正しいファイル名またはディレクトリ名を使用するように
nativePath オブジェクトが変換されます。Linux などの大文字と小文字を区別するファイルシステムでは、大文字と小文字の区別だけが異なる複数のファイルが存在する場合、canonicalize() メソッドにより、最初に見つかったファイル（ファイルシステムによって決められた順序による）に合わせてパスが調整されます。
canonicalize() メソッドは、次のように、Windows で短いファイル名（「8.3」形式の名前）を長いファイル名に変換する場合にも使用できます。
var path:File = new File();path.nativePath = "C:\\AIR~1";
path.canonicalize();
trace(path.nativePath); // C:\AIR Test

パッケージおよびシンボリックリンクの操作
Adobe AIR 1.0 およびそれ以降
各種のオペレーティングシステムで、パッケージファイルおよびシンボリックリンクファイルがサポートされています。
パッケージ - Mac OS では、ディレクトリをパッケージとして指定して、Mac OS Finder にディレクトリではなく単一のファイルとして表示することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

655

ファイルシステムの操作

シンボリックリンク - Mac OS、Linux および Windows Vista では、シンボリックリンクがサポートされています。シンボ
リックリンクを使用すると、ファイルからディスク上の別のファイルやディレクトリを参照できるようになります。シンボ
リックリンクはエイリアスに似ていますが、同じではありません。エイリアスは常に（ディレクトリではなく）ファイルとして報告され、エイリアスまたはショートカットに対して読み取りまたは書き込みを行っても、その参照先である元のファ
イルまたはディレクトリが影響を受けることはありません。これに対し、シンボリックリンクは、参照先のファイルまたはディレクトリとまったく同じように動作します。ファイルまたはディレクトリとして報告することができ、シンボリックリンクに対して読み取りまたは書き込みを行うと、シンボリックリンク自体ではなく、参照先のファイルまたはディレクトリ
に反映されます。さらに、Windows では、ジャンクションポイント（NTFS ファイルシステムで使用される）を参照する

File オブジェクトの isSymbolicLink プロパティが true に設定されています。
File クラスには、File オブジェクトがパッケージまたはシンボリックリンクを参照しているかどうかを確認するための
isPackage プロパティおよび isSymbolicLink プロパティが用意されています。
次のコードでは、ユーザーのデスクトップディレクトリを繰り返し処理して、パッケージではないサブディレクトリの一覧
を出力します。
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing();for (var i:uint = 0; i < desktopNodes.length; i++){if (desktopNodes[i].isDirectory && !desktopNodes[i].isPackage){
trace(desktopNodes[i].name);}}

次のコードでは、ユーザーのデスクトップディレクトリを繰り返し処理して、シンボリックリンクではないファイルおよびディレクトリの一覧を出力します。
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing();for (var i:uint = 0; i < desktopNodes.length; i++){if (!desktopNodes[i].isSymbolicLink){
trace(desktopNodes[i].name);}}canonicalize() メソッドでは、シンボリックリンクのパスを、そのリンクの参照先のファイルまたはディレクトリを参照する
ように変更します。次のコードでは、ユーザーのデスクトップディレクトリを繰り返し処理して、シンボリックリンクであるファイルによって参照されているパスを報告します。
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing();for (var i:uint = 0; i < desktopNodes.length; i++){if (desktopNodes[i].isSymbolicLink){
var linkNode:File = desktopNodes[i] as File;linkNode.canonicalize();
trace(linkNode.nativePath);}}

ボリューム上の利用可能な領域の特定
Adobe AIR 1.0 およびそれ以降
File オブジェクトの spaceAvailable プロパティは、ファイルの場所として使用できる領域をバイト単位で示します。例えば、
次のコードでは、アプリケーション記憶領域ディレクトリで利用可能な領域を確認します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

656

ファイルシステムの操作

trace(File.applicationStorageDirectory.spaceAvailable);

File オブジェクトがディレクトリを参照している場合、spaceAvailable プロパティはファイルが使用できるディレクトリ内の領域を示します。File オブジェクトがファイルを参照している場合、spaceAvailable プロパティはファイルが増大可能な領域を示します。ファイルの場所が存在しない場合、spaceAvailable プロパティは 0 に設定されます。File オブジェクトがシンボ
リックリンクを参照している場合、spaceAvailable プロパティは、シンボリックリンクが指している場所で利用可能な領域に設定されます。
通常、ディレクトリやファイルに利用可能な領域は、ディレクトリまたはファイルを格納するボリュームで利用可能な領域と同じです。ただし、利用可能な領域では、クォータやディレクトリごとの制限が考慮される場合があります。
ファイルやディレクトリをボリュームに追加するには、一般的に、実際のファイルのサイズやディレクトリのコンテンツのサイズよりも大きな領域が必要です。例えば、オペレーティングシステムの場合、インデックス情報を格納するためにより多くの領域が必要になる可能性があります。また、必要なディスクセクタのために、追加の領域が使用される場合があります。さらに、利用可能な領域は動的に変化します。したがって、報告されたすべての領域をファイル記憶域として割り当てることはできません。ファイルシステムへの書き込みについては、664 ページの「ファイルの読み取りと書き込み」を参照
してください。

StorageVolumeInfo.getStorageVolumes() メソッドは、マウントされたストレージボリュームに関する詳細を提供します（663
ページの「ストレージボリュームの操作」を参照）。

デフォルトのシステムアプリケーションでファイルを開く
Adobe AIR 2 以降
AIR 2 では、オペレーティングシステムによって登録されているアプリケーションを使用してファイルを開くことができます。例えば、AIR アプリケーションで DOC ファイルを開く場合は、DOC ファイルを開くように登録されているアプリ
ケーションを使用します。File オブジェクトの openWithDefaultApplication() メソッドを使用すると、ファイルを開くことができます。例えば、次のコードでは、test.doc というファイルがユーザーのデスクトップに、DOC ファイル用のデフォル
トのアプリケーションを使用して開かれます。
var file:File = File.deskopDirectory;
file = file.resolvePath("test.doc");
file.openWithDefaultApplication();

注意：Linux では、ファイル名拡張子でなく、ファイルの MIME タイプによって、ファイルのデフォルトのアプリケー
ションが判断されます。
次のコードでは、MP3 ファイルに移動して、MP3 ファイルを再生するためのデフォルトのアプリケーションで開くことができます。
var file:File = File.documentsDirectory;
var mp3Filter:FileFilter = new FileFilter("MP3 Files", "*.mp3");
file.browseForOpen("Open", [mp3Filter]);file.addEventListener(Event.SELECT, fileSelected);function fileSelected(e:Event):void{
file.openWithDefaultApplication();}

openWithDefaultApplication() メソッドは、アプリケーションディレクトリに配置されているファイルでは使用できません。

AIR では、openWithDefaultApplication() メソッドを使用して開くことができないファイルがあります。Windows では、
EXE や BAT など、一定の種類のファイルを開くことができません。Mac OS および Linux では、特定のアプリケーションを起動するファイルは開けません（Mac OS の Terminal と AppletLauncher、および Linux の csh、bash または ruby が最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

657

ファイルシステムの操作含まれます）。openWithDefaultApplication() メソッドを使用して、これらのファイルを開こうとすると、例外が発生します。
開くことができないファイルの種類について詳しくは、File.openWithDefaultApplication() メソッドのリファレンスガイドを参照してください。
注意：ネイティブインストーラーを使用してインストールされた AIR アプリケーション（拡張デスクトップアプリケーショ
ン）の場合、この制限はありません。

ファイルシステム情報の取得
Adobe AIR 1.0 およびそれ以降
File クラスには、ファイルシステムに関するいくつかの有益な情報を示す以下の静的プロパティがあります。
プロパティ

File.lineEnding

説明
ホストオペレーティングシステムで使用される行終了文字シーケンスです。Mac OS および Linux では、
これは改行文字です。Windows では、復帰文字の後に改行文字が続いたものです。

File.separator

ホストオペレーティングシステムのパスコンポーネントの区切り文字です。Mac OS および Linux では、
これはスラッシュ（/）です。Windows では、円記号（¥）です。

File.systemCharset

ホストオペレーティングシステムでファイルに対して使用されるデフォルトのエンコーディングです。これは、オペレーティングシステムでその言語に応じて使用される文字セットに関連します。

Capabilities クラスにも、ファイルの操作に役立つ有益なシステム情報があります。
プロパティ

説明

Capabilities.hasIME

システムに IME がインストールされているか（true）、インストールされていないか（false）を示します。

Capabilities.language

コンテンツが実行されているシステムの言語コードを示します。

Capabilities.os

現在のオペレーティングシステムを示します。

注意：Capabilities.os を使用してシステムの特性を確認する場合には、慎重に行う必要があります。システム特性を確認する
ためのより固有なプロパティが存在する場合は、それを使用してください。それ以外の場合、すべてのプラットフォームで正しく機能することがないコードを記述する危険があります。例えば、次のようなコードがあるとします。
var separator:String;if (Capablities.os.indexOf("Mac") > -1){
separator = "/";}
else{
separator = "\\";}

このコードは Linux 上で問題を引き起こします。単に File.separator プロパティを使用することをお勧めします。

ディレクトリの操作
Adobe AIR 1.0 およびそれ以降
ランタイムには、ローカルファイルシステム上のディレクトリを操作する機能が用意されています。
ディレクトリを参照する File オブジェクトの作成について詳しくは、646 ページの「File オブジェクトでのディレクトリの参照」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

658

ファイルシステムの操作

ディレクトリの作成
Adobe AIR 1.0 およびそれ以降
File.createDirectory() メソッドを使用して、ディレクトリを作成することができます。例えば、次のコードでは、ユーザーのホームディレクトリのサブディレクトリとして AIR Test というディレクトリを作成します。
var dir:File = File.userDirectory.resolvePath("AIR Test");dir.createDirectory();

既にそのディレクトリが存在する場合、createDirectory() メソッドでは何も行われません。
また、一部のモードでは、FileStream オブジェクトでファイルを開くときにもディレクトリが作成されます。FileStream
インスタンスの作成時に FileStream() コンストラクターの fileMode パラメーターを FileMode.APPEND またはFileMode.WRITE に設定すると、存在しない場合にディレクトリが作成されます。詳しくは、664 ページの「ファイルの読
み取りと書き込みのワークフロー」を参照してください。

一時ディレクトリの作成
Adobe AIR 1.0 およびそれ以降
File クラスの createTempDirectory() メソッドを使用すると、次のように、システムの一時ディレクトリフォルダーにディレクトリを作成できます。
var temp:File = File.createTempDirectory();

createTempDirectory() メソッドでは、一意の一時ディレクトリが自動的に作成されます（そのため、新しい一意の場所を指定する手間が省けます）。
一時ディレクトリは、アプリケーションのセッションに使用される一時ファイルを一時的に格納するために使用できます。
システムの一時ディレクトリに新しい一意の一時ファイルを作成するための createTempFile() メソッドも用意されています。
一時ディレクトリはすべてのデバイスで自動的に削除されるわけではないので、アプリケーションを終了する前に削除する必要がないか確認してください。

ディレクトリの列挙
Adobe AIR 1.0 およびそれ以降
File オブジェクトの getDirectoryListing() メソッドまたは getDirectoryListingAsync() メソッドを使用すると、ディレクトリ内のファイルおよびサブフォルダーを参照する File オブジェクトの配列を取得することができます。
例えば、次のコードでは、ユーザーのドキュメントディレクトリの内容の一覧を出力します（サブディレクトリの内容は確認されません）。
var directory:File = File.documentsDirectory;
var contents:Array = directory.getDirectoryListing();for (var i:uint = 0; i < contents.length; i++){trace(contents[i].name, contents[i].size);}

このメソッドの非同期バージョンを使用した場合は、directoryListing イベントオブジェクトの files プロパティに、ディレク
トリに関連する File オブジェクトの配列が格納されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

659

ファイルシステムの操作

var directory:File = File.documentsDirectory;
directory.getDirectoryListingAsync();
directory.addEventListener(FileListEvent.DIRECTORY_LISTING, dirListHandler);function dirListHandler(event:FileListEvent):void{
var contents:Array = event.files;
for (var i:uint = 0; i < contents.length; i++){trace(contents[i].name, contents[i].size);}}

ディレクトリのコピーおよび移動
Adobe AIR 1.0 およびそれ以降
ファイルをコピーまたは移動する場合と同じメソッドを使用して、ディレクトリをコピーまたは移動することができます。
例えば、次のコードでは、同期的にディレクトリがコピーされます。
var sourceDir:File = File.documentsDirectory.resolvePath("AIR Test");var resultDir:File = File.documentsDirectory.resolvePath("AIR Test Copy");sourceDir.copyTo(resultDir);

copyTo() メソッドの overwrite パラメーターに true を指定すると、既存のターゲットディレクトリにあるすべてのファイル
およびフォルダーが削除され、ソースディレクトリ内のファイルおよびフォルダーに置き換えられます（ターゲットファイ
ルがソースディレクトリに存在しない場合でも同様に処理されます）。
copyTo() メソッドの newLocation パラメーターとして指定するディレクトリは、結果として生成されるディレクトリへのパスを指定するものであり、そのディレクトリを格納する親ディレクトリを指定するものではありません。
詳しくは、661 ページの「ファイルのコピーおよび移動」を参照してください。

ディレクトリの内容の削除
Adobe AIR 1.0 およびそれ以降
File クラスの deleteDirectory() メソッドおよび deleteDirectoryAsync() メソッドを使用すると、ディレクトリを削除することができます。1 つ目のメソッドでは同期的に処理が行われ、2 つ目のメソッドでは非同期で処理が行われます（642 ページの「AIR ファイルの基礎」を参照）。どちらのメソッドにも deleteDirectoryContents パラメーター（Boolean 型）があり、メソッドの呼び出しでこのパラメーターが true に設定されている場合は空ではないディレクトリが削除され、false （デフォルト値）の場合は空のディレクトリだけが削除されます。
例えば、次のコードでは、ユーザーのドキュメントディレクトリの AIR Test サブディレクトリが同期的に削除されます。
var directory:File = File.documentsDirectory.resolvePath("AIR Test");directory.deleteDirectory(true);

次のコードでは、ユーザーのドキュメントディレクトリの AIR Test サブディレクトリが非同期で削除されます。
var directory:File = File.documentsDirectory.resolvePath("AIR Test");directory.addEventListener(Event.COMPLETE, completeHandler)
directory.deleteDirectoryAsync(true);function completeHandler(event:Event):void {trace("Deleted.")}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

660

ファイルシステムの操作

また、moveToTrash() メソッドおよび moveToTrashAsync() メソッドを使用すると、ディレクトリをシステムのごみ箱に移動することもできます。詳しくは、662 ページの「ごみ箱へのファイルの移動」を参照してください。

ファイルの操作
Adobe AIR 1.0 およびそれ以降
AIR のファイル API を使用すると、ファイル操作の基本的な機能をアプリケーションに追加することができます。例えば、ファイルの読み取りおよび書き込み、ファイルのコピーおよび削除などを追加できます。アプリケーションからローカル
ファイルシステムにアクセスできるようになるので、まだ参照していない場合は 1038 ページの「AIR のセキュリティ」を参照してください。
注意：ファイルの種類を AIR アプリケーションに関連付けることができます（これによりダブルクリックでアプリケーショ
ンを開けるようになります）。詳しくは、852 ページの「ファイルの関連付けの管理」を参照してください。

ファイル情報の取得
Adobe AIR 1.0 およびそれ以降
File クラスには、File オブジェクトが参照するファイルまたはディレクトリに関する情報を示す以下のプロパティがあります。
File プロパティ

説明creationDate

ローカルディスク上に存在するファイルの作成日です。

creator

使用されなくなりました。extension プロパティを使用してください（このプロパティでは、ファイルの Mac
OS クリエータータイプが報告されます。これは、Mac OS X より前のバージョンの Mac OS でのみ使用されます）。

downloaded（AIR 2 以降）参照先のファイルまたはディレクトリが、インターネット経由でダウンロード済みであるかどうかを示します。プロパティは、ファイルにダウンロード済みのフラグを付けられるオペレーティングシステ
ム（以下参照）でのみ意味を持ちます。

• Windows XP Service Pack 2 以降および Windows Vista• Mac OS 10.5 以降
exists

参照先のファイルまたはディレクトリが存在するかどうかを表します。

extension

ファイル拡張子です。拡張子は、ファイル名の最後のドット（「.」）より後の部分です（ドットは含みません）。ファイル名にドットが含まれていない場合、extension は null になります。

icon

ファイルに対して定義されたアイコンを格納している Icon オブジェクトです。

isDirectory

File オブジェクトの参照先がディレクトリであるかどうかを表します。

modificationDate

ローカルディスク上に存在するファイルまたはディレクトリの最終変更日です。

name

ローカルディスク上に存在するファイルまたはディレクトリの名前です（ファイル拡張子も含みます（ファイル拡張子がある場合））。

nativePath

ホストオペレーティングシステムの表現形式に従った完全パスです。643 ページの「File オブジェクトのパス」を参照してください。

parentFile オブジェクトで表されるフォルダーまたはファイルが格納されているフォルダーです。このプロパティ
は、File オブジェクトがファイルシステムのルートにあるファイルまたはディレクトリを参照している場合はnull になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

661

ファイルシステムの操作

File プロパティ

説明

size

ローカルディスク上に存在するファイルのサイズ（バイト単位）です。

type

使用されなくなりました。extension プロパティを使用してください（Mac OS では、このプロパティは 4 文
字で表されるファイルの種類になります。これは、Mac OS X より前のバージョンの Mac OS でのみ使用され
ます）。

url

ファイルまたはディレクトリの URL です。643 ページの「File オブジェクトのパス」を参照してください。

これらのプロパティについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の File クラスの項を参照してください。

ファイルのコピーおよび移動
Adobe AIR 1.0 およびそれ以降
File クラスには、ファイルまたはディレクトリをコピーするためのメソッドとして、copyTo() と copyToAsync() という 2 つのメソッドがあります。また、ファイルまたはディレクトリを移動するためのメソッドとして、moveTo() と moveToAsync()という 2 つのメソッドがあります。copyTo() メソッドと moveTo() メソッドでは同期的に処理が行われ、copyToAsync() メ
ソッドと moveToAsync() メソッドでは非同期で処理が行われます（642 ページの「AIR ファイルの基礎」を参照）。
ファイルをコピーまたは移動するには、2 つの File オブジェクトを設定します。1 つは、コピーまたは移動する対象のファイルを参照するオブジェクトで、このオブジェクトでコピーまたは移動メソッドを呼び出します。もう 1 つは、コピー先または移動先（結果）のパスを参照します。
次の例では、ユーザーのドキュメントディレクトリの AIR Test サブディレクトリにある test.txt ファイルを、copy.txt という名前で同じディレクトリにコピーします。
var original:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var newFile:File = File.resolvePath("AIR Test/copy.txt");
original.copyTo(newFile, true);

この例では、copyTo() メソッドの overwrite パラメーター（2 番目のパラメーター）の値が true に設定されています。

overwrite を true に設定することにより、既存のターゲットファイルが上書きされます。このパラメーターはオプションです。このパラメーターを false （デフォルト値）に設定した場合、ターゲットファイルが既に存在すると IOErrorEvent イベ
ントが送出されます（ファイルはコピーされません）。
「非同期」バージョンのコピーメソッドおよび移動メソッドでは、非同期で処理が行われます。タスクの完了またはエラーの状態を監視するには、次のように addEventListener() を使用します。
var original = File.documentsDirectory;
original = original.resolvePath("AIR Test/test.txt");
var destination:File = File.documentsDirectory;
destination = destination.resolvePath("AIR Test 2/copy.txt");
original.addEventListener(Event.COMPLETE, fileMoveCompleteHandler);original.addEventListener(IOErrorEvent.IO_ERROR, fileMoveIOErrorEventHandler);original.moveToAsync(destination);function fileMoveCompleteHandler(event:Event):void {trace(event.target); // [object File]}function fileMoveIOErrorEventHandler(event:IOErrorEvent):void {trace("I/O Error.");}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

662

ファイルシステムの操作

File クラスには、ファイルまたはディレクトリをシステムのごみ箱に移動する File.moveToTrash() メソッドとFile.moveToTrashAsync() メソッドもあります。

ファイルの削除
Adobe AIR 1.0 およびそれ以降
File クラスの deleteFile() メソッドおよび deleteFileAsync() メソッドを使用すると、ファイルを削除することができます。1
つ目のメソッドでは同期的に処理が行われ、2 つ目のメソッドでは非同期で処理が行われます（642 ページの「AIR ファイ
ルの基礎」を参照）。
例えば、次のコードでは、ユーザーのドキュメントディレクトリにある test.txt ファイルが同期的に削除されます。
var file:File = File.documentsDirectory.resolvePath("test.txt");
file.deleteFile();

次のコードでは、ユーザーのドキュメントディレクトリの test.txt ファイルが非同期で削除されます。
var file:File = File.documentsDirectory.resolvePath("test.txt");
file.addEventListener(Event.COMPLETE, completeHandler)
file.deleteFileAsync();function completeHandler(event:Event):void {trace("Deleted.")}また、moveToTrash() メソッドおよび moveToTrashAsync() メソッドを使用すると、ファイルまたはディレクトリをシステ
ムのごみ箱に移動することもできます。詳しくは、662 ページの「ごみ箱へのファイルの移動」を参照してください。

ごみ箱へのファイルの移動
Adobe AIR 1.0 およびそれ以降
File クラスの moveToTrash() メソッドおよび moveToTrashAsync() メソッドを使用すると、ファイルまたはディレクトリをシステムのごみ箱に送ることができます。1 つ目のメソッドでは同期的に処理が行われ、2 つ目のメソッドでは非同期で処理が行われます（642 ページの「AIR ファイルの基礎」を参照）。
例えば、次のコードでは、ユーザーのドキュメントディレクトリにある test.txt ファイルがシステムのごみ箱に同期的に移動されます。
var file:File = File.documentsDirectory.resolvePath("test.txt");
file.moveToTrash();注意：回復可能なごみ箱フォルダーの概念をサポートしていないオペレーティングシステムでは、ファイルがすぐに削除されます。

一時ファイルの作成
Adobe AIR 1.0 およびそれ以降
File クラスの createTempFile() メソッドを使用すると、次のように、システムの一時ディレクトリフォルダーにファイルを作成できます。
var temp:File = File.createTempFile();createTempFile() メソッドでは、一意の一時ファイルが自動的に作成されます（そのため、新しい一意の場所を指定する手間が省けます）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

663

ファイルシステムの操作

一時ファイルは、アプリケーションのセッションで使用される情報を一時的に格納するために使用できます。システムの一時ディレクトリに一意の一時ディレクトリを作成するための createTempDirectory() メソッドも用意されています。
一時ファイルはすべてのデバイスで自動的に削除されるわけではないので、アプリケーションを終了する前に削除する必要がないか確認してください。

ストレージボリュームの操作
Adobe AIR 2 以降
AIR 2 では、マスストレージボリュームのマウントまたはアンマウントを検出できます。StorageVolumeInfo クラスは、
シングルトンオブジェクト storageVolumeInfo を定義します。StorageVolumeInfo.storageVolumeInfo オブジェクトは、スト
レージボリュームがマウントされたときに、storageVolumeMount イベントを送出します。また、ボリュームがアンマウント
されたときには storageVolumeUnmount イベントを送出します。StorageVolumeChangeEvent クラスでは、これらのイベントを定義します。
注意：最新の Linux ディストリビューションでは、StorageVolumeInfo オブジェクトは、特定の場所にマウントされた物
理ドライブおよびネットワークドライブに対して storageVolumeMount および storageVolumeUnmount イベントのみを送出します。

StorageVolumeChangeEvent クラスの storageVolume プロパティは StorageVolume オブジェクトです。StorageVolume
クラスは、次のようなストレージボリュームの基本的なプロパティを定義します。

• drive - Windows のボリ ームドライブ文字（その他のオペレーティングシステムでは null）• fileSystemType — ストレージボリューム上のファイルシステムのタイプ（「FAT」、「NTFS」、「HFS」、「UFS」など）• isRemoveable — ボリュームが削除可能（true）か不可能（false）か• isWritable — ボリュームが書き込み可能（true）か不可能（false）か• name — ボリュームの名前• rootDirectory — ボリュームのルートディレクトリに対応する File オブジェクト
StorageVolumeChangeEvent クラスには rootDirectory プロパティも含まれています。rootDirectory プロパティは File オ
ブジェクトで、マウントまたはアンマウントされたストレージボリュームのルートディレクトリを参照します。

StorageVolumeChangeEvent オブジェクトの storageVolume プロパティは、アンマウントされたボリュームに対しては定義されていません（null）。ただし、イベントの rootDirectory プロパティにアクセスすることはできます。
次のコードでは、ストレージボリュームがマウントされたときに、その名前とファイルパスを出力します。
StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME_MOUNT,
onVolumeMount);function onVolumeMount(event:StorageVolumeChangeEvent):void{
trace(event.storageVolume.name, event.rootDirectory.nativePath);}

次のコードでは、ストレージボリュームがアンマウントされたときに、そのファイルパスを出力します。
StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME_UNMOUNT,
onVolumeUnmount);function onVolumeUnmount(event:StorageVolumeChangeEvent):void{
trace(event.rootDirectory.nativePath);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

664

ファイルシステムの操作

StorageVolumeInfo.storageVolumeInfo オブジェクトには getStorageVolumes() メソッドが含まれています。このメソッドは、
現在マウントされているストレージボリュームに対応する StorageVolume オブジェクトのベクトルを返します。次のコードは、マウントされているすべてのストレージボリュームの名前とルートディレクトリのリストを表示する方法を示しています。
var volumes:Vector.<StorageVolume> = new Vector.<StorageVolume>;
volumes = StorageVolumeInfo.storageVolumeInfo.getStorageVolumes();for (var i:int = 0; i < volumes.length; i++){trace(volumes[i].name, volumes[i].rootDirectory.nativePath);}

注意：最新の Linux ディストリビューションでは、getStorageVolumes() メソッドは、物理デバイスおよび特定の場所にマウントされたネットワークドライブに対応するオブジェクトを返します。

File.getRootDirectories() メソッドによって、ルートディレクトリがリストされます（648 ページの「ファイルシステムルー
トの参照」を参照）。ただし、StorageVolume オブジェクト（StorageVolumeInfo.getStorageVolumes() メソッドによって列挙）のほうが、ストレージボリュームに関する情報がより詳細に表示されます。

StorageVolume オブジェクトの rootDirectory プロパティの spaceAvailable プロパティを使用すると、ストレージボリュー
ム上で利用可能な領域を確認できます（655 ページの「ボリューム上の利用可能な領域の特定」を参照）。
関連項目

StorageVolume
StorageVolumeInfo

ファイルの読み取りと書き込み
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションでは、FileStream クラスを使用してファイルシステムの読み取りおよび書き込みを実行できます。

ファイルの読み取りと書き込みのワークフロー
Adobe AIR 1.0 およびそれ以降
ファイルの読み取りおよび書き込みのワークフローを次に示します。
パスを参照する File オブジェクトを初期化します。

File オブジェクトは、操作対象のファイル（または後で作成するファイル）のパスを表します。
var file:File = File.documentsDirectory;
file = file.resolvePath("AIR Test/testFile.txt");

この例では、File オブジェクトの File.documentsDirectory プロパティと resolvePath() メソッドを使用して File オブジェクトを初期化しています。ただし、File オブジェクトでファイルを参照する方法は、これ以外にも多数あります。詳しくは、

650 ページの「File オブジェクトでのファイルの参照」を参照してください。
FileStream オブジェクトを初期化します。
FileStream オブジェクトの open() メソッドまたは openAsync() メソッドを呼び出します。
呼び出すメソッドは、ファイルを開いて同期操作と非同期操作のどちらを行うかによって異なります。open() メソッドのfile パラメーターとして File オブジェクトを使用します。fileMode パラメーターに、ファイルの使用方法を示す FileMode
クラスの定数を指定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

665

ファイルシステムの操作

例えば、次のコードでは、ファイルを作成して既存のデータを上書きするために使用する FileStream オブジェクトを初期化します。
var fileStream:FileStream = new FileStream();fileStream.open(file, FileMode.WRITE);

詳しくは、666 ページの「FileStream オブジェクトの初期化とファイルのオープンおよびクローズ」および 666 ページの「FileStream を開く際のモード」を参照してください。
ファイルを（openAsync() メソッドを使用して）非同期で開いた場合は、FileStream オブジェクトのイベントリスナーを追加して設定します。
これらのイベントリスナーメソッドは、様々な状況で FileStream オブジェクトから送出されたイベントに反応します。例
えば、ファイルからのデータ読み取り時や I/O エラーの発生時、または書き込み対象のデータの書き込みが完了した時などの状況があります。
詳しくは、670 ページの「非同期プログラミングと非同期で開いた FileStream オブジェクトで生成されるイベント」を参照してください。
必要に応じて、データの読み取りおよび書き込みを行うためのコードを含めます。

FileStream クラスには、読み取りおよび書き込みに関連するメソッドが多数用意されています（それぞれ「read」または「write」で始まります）。データの読み取りおよび書き込みにどのメソッドを使用するかは、ターゲットファイルのデータの形式によって異なります。
例えば、ターゲットファイルのデータが UTF エンコード形式のテキストの場合は、readUTFBytes() メソッドおよび

writeUTFBytes() メソッドを使用できます。データをバイト配列として処理する場合は、readByte()、readBytes()、writeByte()
および writeBytes() の各メソッドを使用できます。詳しくは、671 ページの「データ形式と使用する読み取りおよび書き込み
メソッドの選択」を参照してください。
ファイルを非同期で開いた場合は、読み取りメソッドを呼び出す前に、十分なデータを使用できることを確認します。詳し
くは、668 ページの「読み取りバッファーと FileStream オブジェクトの bytesAvailable プロパティ」を参照してください。
ファイルに書き込む前に、利用可能なディスク領域の容量を確認する場合は、File オブジェクトの spaceAvailable プロパ
ティを確認します。詳しくは、655 ページの「ボリューム上の利用可能な領域の特定」を参照してください。
ファイルの処理が完了したら、FileStream オブジェクトの close() メソッドを呼び出します。
close() メソッドを呼び出すと、他のアプリケーションでファイルを使用できるようになります。
詳しくは、666 ページの「FileStream オブジェクトの初期化とファイルのオープンおよびクローズ」を参照してください。

FileStream クラスを使用してファイルの読み取りおよび書き込みを行うサンプルアプリケーションについては、Adobe
AIR デベロッパーセンターの次の記事を参照してください。

•

テキストファイルエディターの構築•

テキストファイルエディターの構築• XML 環境設定ファイルの読み取りと書き込み

FileStream オブジェクトの操作
Adobe AIR 1.0 およびそれ以降
FileStream クラスでは、ファイルのオープン、読み取りおよび書き込みを行うためのメソッドが定義されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

666

ファイルシステムの操作

FileStream を開く際のモード
Adobe AIR 1.0 およびそれ以降
FileStream オブジェクトの open() メソッドおよび openAsync() メソッドには、それぞれ fileMode パラメーターがあります。
このパラメーターでは、ファイルストリームについての次のようないくつかのプロパティを定義します。

•

ファイルから読み取れるかどうか•

ファイルに書き込めるかどうか•

データを常にファイルの末尾の後に追加するかどうか（書き込み時）•

ファイルが存在しない場合（およびその親ディレクトリが存在しない場合）にどのように処理するか

各ファイルモードを以下に示します（open() メソッドおよび openAsync() メソッドの fileMode パラメーターとして指定できます）。
ファイルモード説明

FileMode.READ

ファイルを読み取り専用で開くことを指定します。

FileMode.WRITE

ファイルを書き込み用に開くことを指定します。ファイルが存在しない場合は、FileStream オブジェクトを開いたときに作成されます。ファイルが存在する場合は、既存のデータは削除されます。

FileMode.APPEND

ファイルを追加用に開くことを指定します。ファイルが存在しない場合は作成されます。ファイルが存在する
場合は、既存のデータは上書きされず、すべてファイルの末尾から書き込まれます。

FileMode.UPDATE

ファイルを読み書き用に開くことを指定します。ファイルが存在しない場合は作成されます。ランダムアクセ
スでファイルの読み書きを行う場合は、このモードを指定します。ファイルの任意の位置から読み取ることができます。ファイルに書き込む際は、書き込んだバイトのみが既存のデータに上書きされます（それ以外はどのバイトも変更されません）。

FileStream オブジェクトの初期化とファイルのオープンおよびクローズ
Adobe AIR 1.0 およびそれ以降
FileStream オブジェクトを開くとき、そのオブジェクトでファイルに対するデータの読み取りおよび書き込みができるように設定します。FileStream オブジェクトを開くには、File オブジェクトを FileStream オブジェクトの open() メソッドまたは openAsync() メソッドに渡します。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.READ);

fileMode パラメーター（open() メソッドおよび openAsync() メソッドの 2 番目のパラメーター）で、ファイルを開くモード（読み取り、書き込み、追加または更新）を指定します。詳しくは、前の節の 666 ページの「FileStream を開く際のモード」を参照してください。

openAsync() メソッドを使用して非同期のファイル操作用にファイルを開く場合は、非同期イベントを処理するイベントリ
スナーを設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

667

ファイルシステムの操作

var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completeHandler);
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.addEventListener(IOErrorEvent.IO_Error, errorHandler);
myFileStream.openAsync(myFile, FileMode.READ);
function completeHandler(event:Event):void {// ...
}
function progressHandler(event:ProgressEvent):void {// ...
}
function errorHandler(event:IOErrorEvent):void {// ...
}

ファイルは、同期操作用または非同期操作用のいずれかで開かれます。どちらで開かれるかは、open() メソッドとopenAsync() メソッドのどちらを使用したかによって決まります。詳しくは、642 ページの「AIR ファイルの基礎」を参照
してください。

FileStream オブジェクトの open() メソッドで fileMode パラメーターを FileMode.READ または FileMode.UPDATE に設定した場合、FileStream オブジェクトを開くとすぐにデータが読み取りバッファーに読み取られます。詳しくは、668 ページの「読み取りバッファーと FileStream オブジェクトの bytesAvailable プロパティ」を参照してください。
関連付けられたファイルを閉じるには、FileStream オブジェクトの close() メソッドを呼び出します。これにより、そのファイルが他のアプリケーションで使用できるようになります。

FileStream オブジェクトの position プロパティ
Adobe AIR 1.0 およびそれ以降
FileStream オブジェクトの position プロパティでは、次の読み取りまたは書き込みメソッドでデータの読み取りまたは書き込みを行う位置を指定します。
読み取りまたは書き込み操作の前に、position プロパティにファイル内の任意の有効な位置を設定します。
例えば、次のコードでは、ファイル内の位置 8 にストリング「hello」を（UTF エンコード形式で）書き込みます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.UPDATE);
myFileStream.position = 8;
myFileStream.writeUTFBytes("hello");

最初に FileStream オブジェクトを開いたときは、position プロパティは 0 に設定されています。
読み取り操作を行う場合はその操作の前に、position の値が 0 以上で、かつファイルのバイト数より小さい値（ファイル内に存在する位置）に設定されている必要があります。

position プロパティの値は、次の場合にのみ変更されます。

• position プロパティを明示的に設定したとき•読み取りメソッドを呼び出したとき•書き込みメソッドを呼び出したとき

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

668

ファイルシステムの操作

FileStream オブジェクトの読み取りまたは書き込みメソッドを呼び出すと、すぐに position プロパティの値が、読み取りまたは書き込みを行ったバイト数だけインクリメントされます。使用する読み取りメソッドによって、position プロパティの値が、指定された読み取り対象のバイト数だけインクリメントされる場合と、使用できるバイト数だけインクリメントされる場合があります。その後に読み取りまたは書き込みメソッドを呼び出すと、その新しい位置から読み取りまたは書き込みが開始されます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.UPDATE);
myFileStream.position = 4000;
trace(myFileStream.position); // 4000
myFileStream.writeBytes(myByteArray, 0, 200);
trace(myFileStream.position); // 4200

ただし 1 つ例外があり、追加モードで開いた FileStream では、書き込みメソッドの呼び出し後に position プロパティは変更されません（追加モードでは、position プロパティの値に関係なく、常にファイルの末尾にデータが書き込まれます）。
非同期操作用に開いたファイルでは、次のコード行が実行されるまで書き込み操作は実行されません。ただし、複数の非同期メソッドを連続して呼び出すことは可能で、その場合はランタイムによって順番に実行されます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.openAsync(myFile, FileMode.WRITE);
myFileStream.writeUTFBytes("hello");
myFileStream.writeUTFBytes("world");
myFileStream.addEventListener(Event.CLOSE, closeHandler);
myFileStream.close();trace("started.");closeHandler(event:Event):void{
trace("finished.");}

このコードのトレース出力は次のようになります。
started.
finished.

position の値は、読み取りまたは書き込みメソッドを呼び出した後すぐに（いつでも）指定できます。次の読み取りまたは書き込み操作は、その位置から開始されます。例えば、次のコードでは、writeBytes() メソッドを呼び出した直後に position
プロパティを設定しています。書き込み操作の完了後も、position はその値（300）に設定されています。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.openAsync(myFile, FileMode.UPDATE);
myFileStream.position = 4000;
trace(myFileStream.position); // 4000
myFileStream.writeBytes(myByteArray, 0, 200);
myFileStream.position = 300;
trace(myFileStream.position); // 300

読み取りバッファーと FileStream オブジェクトの bytesAvailable プロパティ

Adobe AIR 1.0 およびそれ以降
読み取り機能を指定して FileStream オブジェクトを開いた場合（open() メソッドまたは openAsync() メソッドの fileMode
パラメーターを READ または UPDATE に設定した場合）、ランタイムでデータが内部バッファーに格納されます。

FileStream オブジェクトでのバッファーへのデータの読み取りは、（FileStream オブジェクトの open() メソッドまたは
openAsync() メソッドを呼び出して）ファイルを開くとすぐに開始されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

669

ファイルシステムの操作

同期操作用に（open() メソッドを使用して）開いたファイルでは、いつでも position プロパティに任意の有効な位置（ファイルの範囲内）を指定して、任意の量のデータ（ファイルの範囲内）の読み取りを開始できます。次にコードの例を示します（ファイルに 100 バイト以上あることを前提にしています）。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.READ);
myFileStream.position = 10;
myFileStream.readBytes(myByteArray, 0, 20);
myFileStream.position = 89;
myFileStream.readBytes(myByteArray, 0, 10);

ファイルを同期操作用と非同期操作用のどちらで開いたかに関係なく、読み取りメソッドでは常に、bytesAvalable プロパ
ティで表される「使用可能な」バイトから読み取りを行います。同期的に読み取る場合は、常にファイルのすべてのバイトが使用可能です。非同期で読み取る場合は、非同期バッファーへの入力が progress イベントによって通知されるにつれて、

position プロパティで指定された位置以降のバイトが使用可能になります。
同期操作用に開いたファイルでは、bytesAvailable プロパティは、常に position プロパティからファイルの末尾までのバイト数を表すように設定されます（常にファイル内のすべてのバイトを読み取ることができます）。
非同期操作用に開いたファイルでは、読み取りメソッドを呼び出す前に、読み取りバッファーに十分なデータが格納されていることを確認する必要があります。非同期で開いたファイルでは、読み取り操作が進むにつれ、読み取り操作の開始時にposition で指定された位置以降のデータがファイルからバッファーに追加され、バイトが読み取られるたびに bytesAvailable
プロパティの値がインクリメントされます。bytesAvailable プロパティは、position プロパティで指定された位置にあるバイトからバッファーの末尾までの使用可能なバイト数を示します。定期的に、FileStream オブジェクトから progress イベントが送信されます。
非同期で開いたファイルでは、読み取りバッファーでデータが使用可能になると、FileStream オブジェクトから定期的に

progress イベントが送出されます。例えば、次のコードでは、データがバッファーに読み取られると、そのデータを
ByteArray オブジェクトの bytes に読み取ります。
var bytes:ByteArray = new ByteArray();
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.openAsync(myFile, FileMode.READ);
function progressHandler(event:ProgressEvent):void{
myFileStream.readBytes(bytes, myFileStream.position, myFileStream.bytesAvailable);}

非同期で開かれたファイルでは、読み取りバッファー内のデータのみを読み取ることができます。また、データを読み取ると、読み取りバッファーからそのデータは削除されます。読み取り操作を行う場合は、読み取り操作を呼び出す前に、読み取りバッファーにデータが存在することを確認する必要があります。例えば、次のコードでは、ファイル内の位置 4000 から始まる 8000 バイトのデータを読み取ります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

670

ファイルシステムの操作

var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.addEventListener(Event.COMPLETE, completed);
myFileStream.openAsync(myFile, FileMode.READ);
myFileStream.position = 4000;
var str:String = "";function progressHandler(event:Event):void{if (myFileStream.bytesAvailable > 8000 ){str += myFileStream.readMultiByte(8000, "iso-8859-1");}}

書き込み操作中は、FileStream オブジェクトでは読み取りバッファーにデータを読み取りません。書き込み操作が完了すると（書き込みバッファー内のすべてのデータがファイルに書き込まれると）、FileStream オブジェクトでは新しい読み取り
バッファーを開始し（関連付けられている FileStream オブジェクトが読み取り機能を指定して開かれている場合）、position
プロパティで指定された位置から、読み取りバッファーへのデータの読み取りを開始します。position プロパティは、書き込まれた最後のバイトの位置にするか、別の位置を指定することもできます。別の位置を指定するには、書き込み操作後にposition プロパティに別の値を指定します。
非同期プログラミングと非同期で開いた FileStream オブジェクトで生成されるイベント

Adobe AIR 1.0 およびそれ以降
ファイルを（openAsync() メソッドを使用して）非同期で開いた場合、ファイルの読み取りおよび書き込みは非同期で実行されます。読み取りバッファーへのデータの読み取り中や出力データの書き込み中に、他の ActionScript コードを実行する
ことができます。
そのため、非同期で開いた FileStream オブジェクトによって生成されるイベントに登録する必要があります。
次のように、progress イベントに登録すると、新しいデータが読み取り可能になったときに通知を受けることができます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.openAsync(myFile, FileMode.READ);
var str:String = "";function progressHandler(event:ProgressEvent):void{
str += myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1");}

次のように、complete イベントに登録すると、データ全体を読み取ることができます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completed);
myFileStream.openAsync(myFile, FileMode.READ);
var str:String = "";function completeHandler(event:Event):void{
str = myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1");}

入力データをバッファーに格納して非同期読み取りを有効にする場合とほぼ同じようにして、非同期ストリームに書き込んだデータは、バッファーに格納されて非同期でファイルに書き込まれます。データがファイルに書き込まれると、

FileStream オブジェクトから定期的に OutputProgressEvent オブジェクトが送出されます。OutputProgressEvent オブジェク
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

671

ファイルシステムの操作

トには、書き込まれる残りのバイト数が設定された bytesPending プロパティがあります。outputProgress イベントに登録すると、このバッファーが実際にファイルに書き込まれたときに通知を受けることができます（進捗状況ダイアログを表示する場合などに便利です）。ただし、一般には、このようにする必要はありません。具体的に言うと、書き込まれていないバイトについては考慮せずに、close() メソッドを呼び出すことができます。FileStream オブジェクトでは引き続きデータの書き込みが行われ、最後のバイトがファイルに書き込まれて書き込み元のファイルが閉じられた後に close イベントが送出されます。
データ形式と使用する読み取りおよび書き込みメソッドの選択

Adobe AIR 1.0 およびそれ以降
すべてのファイルは、ディスク上のバイトのセットからなります。ActionScript では、ファイルのデータを常に ByteArrayとして表すことができます。例えば、次のコードでは、ファイルのデータを bytes という ByteArray オブジェクトに読み取ります。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completeHandler);
myFileStream.openAsync(myFile, FileMode.READ);
var bytes:ByteArray = new ByteArray();function completeHandler(event:Event):void{
myFileStream.readBytes(bytes, 0, myFileStream.bytesAvailable);}

同様に、次のコードでは、bytes という ByteArray のデータをファイルに書き込みます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.WRITE);
myFileStream.writeBytes(bytes, 0, bytes.length);

ただし、ActionScript の ByteArray オブジェクトにデータを格納したくない場合もよくあります。また、多くの場合、
データファイルのファイル形式は決められています。
例えば、ファイルのデータがテキストファイル形式であり、そのデータを String オブジェクトで表したい場合があります。
そのため、FileStream クラスには、ByteArray オブジェクト以外の種類のデータを読み書きするための読み取りおよび書
き込みメソッドが用意されています。例えば、次のコードのように、readMultiByte() メソッドを使用すると、ファイルからデータを読み取って String オブジェクトに格納できます。
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completed);
myFileStream.openAsync(myFile, FileMode.READ);
var str:String = "";function completeHandler(event:Event):void{
str = myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1");}

readMultiByte() メソッドの 2 番目のパラメーターでは、ActionScript でデータの解釈に使用するテキスト形式（この例では「iso-8859-1」）を指定します。Adobe AIR では、一般的な文字セットのエンコードがサポートされています（「サポートされている文字セット」を参照）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

672

ファイルシステムの操作

FileStream クラスには、読み取りバッファーのデータを、UTF-8 文字セットを使用してストリングに読み取る
readUTFBytes() メソッドも用意されています。UTF-8 文字セットの文字は可変長なので、progress イベントに応答するメ
ソッドでは readUTFBytes() は使用しないでください。読み取りバッファーの末尾にあるデータが不完全な文字を表す可能性があります（これは、readMultiByte() メソッドを可変長の文字エンコード形式で使用した場合にも当てはまります）。そのた
め、FileStream オブジェクトから complete イベントが送出されたら、データセット全体を読み取ります。
同様に、String オブジェクトおよびテキストファイルを処理するための書き込みメソッドとして、writeMultiByte() メソッド
および writeUTFBytes() メソッドが用意されています。

readUTF() メソッドおよび writeUTF() メソッド（readUTFBytes() および writeUTFBytes() と混同しないようにしてください）でもファイルのテキストデータが読み書きされますが、これらのメソッドでは、テキストデータの前にそのテキストデータの長さを指定するデータがあることが前提になります。このような指定は、標準的なテキストファイルでは一般的ではありません。
一部の UTF エンコード形式のテキストファイルは、エンコード形式（UTF-16 や UTF-32 など）と同様にエンディアン形
式を定義する「UTF-BOM」（バイト順序マーク）で始まります。
テキストファイルの読み取りおよび書き込みの例については、673 ページの「例：XML オブジェクトへの XML ファイルの読み取り」を参照してください。
複雑な ActionScript オブジェクトのデータを格納および取得する場合は、readObject() および writeObject() が適しています。データは ActionScript Message Format （AMF）でエンコードされます。Adobe AIR、Flash Player、Flash Media

Server、Flex Data Services には、この形式のデータを操作するための API が用意されています。
他にも、読み取りおよび書き込みメソッド（readDouble() と writeDouble() など）がいくつか用意されています。ただし、これらを使用する場合は、これらのメソッドで定義されるデータの形式にファイル形式が適合することを確認してください。
多くの場合、ファイル形式は単純なテキスト形式よりも複雑です。例えば、MP3 ファイルには、MP3 ファイル固有の復元
およびデコードアルゴリズムでしか解釈できない圧縮データが含まれています。また、MP3 ファイルには、ファイルに関するメタタグ情報（曲のタイトルやアーティストなど）を格納する ID3 タグが含まれる場合もあります。ID3 形式には複数のバージョンがありますが、最も単純なバージョン（ID3 バージョン 1）について 674 ページの「例：ランダムアクセスによるデータの読み取りと書き込み」の節で説明します。
他のファイル形式（イメージ、データベース、アプリケーションドキュメントなどで使用される形式）でもそれぞれ構造が異なるため、それらのデータを ActionScript で処理するには、データの構造を理解する必要があります。

load() メソッドおよび save() メソッドの使用
Flash Player 10 以降、Adobe AIR 1.5 以降
Flash Player 10 では、FileReference クラスに load() メソッドおよび save() メソッドが追加されています。これらのメソッドは AIR 1.5 にもあり、File クラスがこれらのメソッドを FileReference クラスから継承しています。これらのメソッドは、Flash Player でユーザーが安全にファイルデータの読み込みや保存を行うことができるように設計されています。しかし、AIR アプリケーションでは、ファイルの非同期での読み込みや保存を簡単に実行するための手段として、これらのメソッドを使用することもできます。
例えば、次のコードは、文字列をテキストファイルに保存します。
var file:File = File.applicationStorageDirectory.resolvePath("test.txt");
var str:String = "Hello.";file.addEventListener(Event.COMPLETE, fileSaved);
file.save(str);function fileSaved(event:Event):void{
trace("Done.");}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

673

ファイルシステムの操作

data パラメーター（save() メソッド）は、String、XML、または ByteArray の値を指定できます。この引数が String または XML の値の場合、UTF-8 エンコード形式のテキストファイルとしてファイルが保存されます。
このコード例を実行すると、ファイルの保存先を選択するためのダイアログボックスが表示されます。
次のコードは、UTF-8 エンコード形式のテキストファイルから文字列を読み込みます。
var file:File = File.applicationStorageDirectory.resolvePath("test.txt");
file.addEventListener(Event.COMPLETE, loaded);
file.load();var str:String;
function loaded(event:Event):void{
var bytes:ByteArray = file.data;
str = bytes.readUTFBytes(bytes.length);
trace(str);}

FileStream クラスを使用すると、load() メソッドおよび save() メソッドよりも多くの機能を使用できます。次に例を示します。

• FileStream クラスを使用すると、同期および非同期の両方でデータを読み書きできます。
• FileStream クラスを使用すると、ファイルに対してインクリメンタルな書き込みを行うことができます。
• FileStream クラスを使用すると、ファイルを開いてランダムアクセス（ファイルの任意の場所の読み書き）を実行できます。

• FileStream クラスを使用すると、fileMode パラメーター（open() メソッドまたは openAsync() メソッド）を設定することにより、ファイルに対するファイルアクセスの種類を指定できます。

• FileStream クラスを使用すると、ファイルを開くダイアログボックスや名前を付けて保存ダイアログボックスを表示せずに、データをファイルに保存できます。

• FileStream クラスを使用してデータを読み込む場合は、バイト配列以外の型を直接使用できます。
例：XML オブジェクトへの XML ファイルの読み取り
Adobe AIR 1.0 およびそれ以降
以下の例では、XML データが格納されているテキストファイルの読み取りおよび書き込みを行う方法を示します。
ファイルからの読み取りを行うには、File オブジェクトと FileStream オブジェクトを初期化し、FileStream の

readUTFBytes() メソッドを呼び出して、ストリングを XML オブジェクトに変換します。
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml");var fileStream:FileStream = new FileStream();fileStream.open(file, FileMode.READ);
var prefsXML:XML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable));fileStream.close();同様に、ファイルへのデータの書き込みも、適切な File オブジェクトと FileStream オブジェクトを設定してからFileStream オブジェクトの書き込みメソッドを呼び出すだけで簡単にできます。書き込みメソッドには、次のように String
型の XML データを渡します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

674

ファイルシステムの操作

var prefsXML:XML = <prefs><autoSave>true</autoSave></prefs>;
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml");
fileStream = new FileStream();fileStream.open(file, FileMode.WRITE);
var outputString:String = '<?xml version="1.0" encoding="utf-8"?>\n';outputString += prefsXML.toXMLString();
fileStream.writeUTFBytes(outputString);
fileStream.close();

これらの例では、ファイルが UTF-8 形式であるという前提で、readUTFBytes() メソッドと writeUTFBytes() メソッドを使用
しています。形式が異なる場合は、別のメソッドを使用する必要がある場合があります（671 ページの「データ形式と使用する読み取りおよび書き込みメソッドの選択」を参照）。
上記の例では、同期操作用に開いた FileStream オブジェクトを使用しています。ファイルは非同期操作用に開くこともできます（イベントに応答するイベントリスナー関数が必要になります）。例えば、次のコードは、XML ファイルを非同期で読み取る方法を示しています。
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml");var fileStream:FileStream = new FileStream();fileStream.addEventListener(Event.COMPLETE, processXMLData);
fileStream.openAsync(file, FileMode.READ);
var prefsXML:XML;function processXMLData(event:Event):void{
prefsXML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable));fileStream.close();}ファイル全体が読み取りバッファーに読み取られると（FileStream オブジェクトから complete イベントが送出されると）、processXMLData() メソッドが呼び出されます。これにより、readUTFBytes() メソッドが呼び出されて String 型の読み取り
データが取得され、そのストリングに基づいて XML オブジェクトである prefsXML が作成されます。
これらの機能を示すサンプルアプリケーションについては、「XML 環境設定ファイルの読み取りおよび書き込み」を参照してください。

例：ランダムアクセスによるデータの読み取りと書き込み
Adobe AIR 1.0 およびそれ以降
MP3 ファイルには、ID3 タグが含まれている場合があります。これは、記録した内容を識別するメタデータが格納された、ファイルの先頭または末尾にあるセクションです。ID3 タグ形式自体、様々なリビジョンがあります。この例では、最も単「ファイルデータのランダムアクセス」を使用して読み書き
純な ID3 形式（ID3 バージョン 1.0）を含む MP3 ファイルを、する（つまり、ファイル内の任意の位置で読み書きを行う）方法を示します。

ID3 バージョン 1 のタグを含む MP3 ファイルでは、ファイルの末尾（最後の 128 バイト）に ID3 データが格納されています。
ランダムアクセスで読み書きを行うためにファイルにアクセスする場合、open() メソッドまたは openAsync() メソッドの

fileMode パラメーターとして FileMode.UPDATE を指定することが重要です。
var file:File = File.documentsDirectory.resolvePath("My Music/Sample ID3 v1.mp3");
var fileStr:FileStream = new FileStream();fileStr.open(file, FileMode.UPDATE);

これにより、ファイルに対する読み取りと書き込みの両方が可能になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

675

ファイルシステムの操作

ファイルを開いたら、次のようにして position ポインターをファイルの末尾から 128 バイトの位置に設定できます。
fileStr.position = file.size - 128;

このコードで position プロパティをファイル内のこの位置に設定する理由は、ID3 v1.0 形式では ID3 タグデータをファイルの末尾 128 バイトに格納するように決められているからです。仕様ではさらに、次のように決められています。

•

タグの最初の 3 バイトには、ストリング「TAG」を記述する。

•

次の 30 文字には、MP3 トラックのタイトルをストリングで記述する。

•

次の 30 文字には、アーティストの名前をストリングで記述する。

•

次の 30 文字には、アルバムの名前をストリングで記述する。

•

次の 4 文字には、年をストリングで記述する。

•

次の 30 文字には、コメントをストリングで記述する。

•

次のバイトには、トラックのジャンルを示すコードを記述する。

•

テキストデータはすべて ISO 8859-1 形式にする。

id3TagRead() メソッドで、読み取り後（complete イベント後）にデータを確認します。
function id3TagRead():void{if (fileStr.readMultiByte(3, "iso-8859-1").match(/tag/i)){
var id3Title:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3Artist:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3Album:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3Year:String = fileStr.readMultiByte(4, "iso-8859-1");
var id3Comment:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3GenreCode:String = fileStr.readByte().toString(10);}}

ファイルへの書き込みもランダムアクセスで実行できます。例えば、id3Title 変数を解析して（String クラスのメソッドで）
大文字小文字が正しいかを確認した後で、次のように、変更後のストリング（newTitle）をファイルに書き込むことができます。
fileStr.position = file.length - 125;// 128 - 3
fileStr.writeMultiByte(newTitle, "iso-8859-1");

ID3 バージョン 1 の規格に準拠するには、newTitle のストリングの長さが 30 文字になるように、末尾を文字コード 0（String.fromCharCode(0)）で埋める必要があります。

最終更新日 2015/10/14

676

第 39 章：ローカルデータの保存Flash Player 9 以降、Adobe AIR 1.0 以降
SharedObject クラスを使用して、クライアントコンピューターに少量のデータを格納します。また、Adobe AIR では、
EncryptedLocalStore クラスを使用して、AIR アプリケーション内でローカルコンピューターに少量のユーザー機密データを格納できます。
また、ファイルシステム上のファイルを読み書きしたり、（Adobe AIR で）ローカルデータベースファイルにアクセスしたりもできます。詳しくは、628 ページの「ファイルシステムの操作」および 689 ページの「AIR を使用したローカル SQL
データベースの操作」を参照してください。
共有オブジェクトに関しては、いくつかのセキュリティ要素があります。詳しくは、1004 ページの「セキュリティ」の1036 ページの「共有オブジェクト」を参照してください。

共有オブジェクト
Flash Player 9 以降、Adobe AIR 1.0 以降「Flash cookie」とも呼ばれる共有オブジェクトは、アクセスしたサイトによってコンピューター上に作成されるデータファ
イルです。ほとんどの場合、共有オブジェクトは、ユーザーが頻繁にアクセスする Web サイトの外観をパーソナライズする場合など、Web ブラウジングの操作性を向上するために使用されます。

共有オブジェクトについて
Flash Player 9 以降、Adobe AIR 1.0 以降
共有オブジェクトは、ブラウザーの Cookie のように機能します。SharedObject クラスを使用して、ユーザーのローカル
ハードディスクにデータを格納し、同じセッションやその後のセッションで、格納したデータを呼び出します。アプリケー
ションは、SharedObject データが同じドメインで実行されている場合に限り、独自の SharedObject データのみにアクセスできます。データはサーバーに送信されず、他のドメインで実行中の他のアプリケーションがデータにアクセスすることもできません。ただし、同じドメインのアプリケーションがデータにアクセスできるようにすることは可能です。

共有オブジェクトと Cookie の比較
Flash Player 9 以降、Adobe AIR 1.0 以降
Cookie と共有オブジェクトは非常によく似ています。大多数の Web プログラマーは Cookie の機能に精通しているので、Cookie とローカル SharedObject を比較すると役立つ場合があります。
RFC 2109 標準に準拠する Cookie には通常、次のような特性があります。

•

期限切れになることがあり、多くの場合、デフォルトではセッションの終了時に期限切れになります。

•

サイトごとにクライアントによって無効にすることができます。

•

合計 300 Cookie、サイトごとに最大 20 Cookie の制限があります。

•

通常は、それぞれ 4 KB までのサイズに制限されています。

•

セキュリティ脅威と認識されることがあるので、結果として、クライアントで無効にされることがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

677

ローカルデータの保存•

クライアントブラウザーで指定された場所に格納されます。

• HTTP を介してクライアントからサーバーに送信されます。
一方、共有オブジェクトには次のような特性があります。

•

デフォルトでは期限切れになりません。

•

デフォルトでは、それぞれ 100 KB までのサイズに制限されています。

•

単純なデータ型（String、Array、Date など）を格納できます。

•

アプリケーションで指定された場所（ユーザーのホームディレクトリ内）に格納されます。

•

クライアントとサーバーとの間で送信されることはありません。

SharedObject クラスについてFlash Player 9 以降、Adobe AIR 1.0 以降
SharedObject クラスを使用して、共有オブジェクトを作成および削除したり、使用している SharedObject オブジェクトの現在のサイズを検出したりできます。

共有オブジェクトの作成
Flash Player 9 以降、Adobe AIR 1.0 以降
SharedObject オブジェクトを作成するには、SharedObject.getLocal() メソッドを使用します。このメソッドのシンタックスは次のとおりです。
SharedObject.getLocal("objectName" [, pathname]): SharedObject

次の例では、mySO という共有オブジェクトを作成します。
public var mySO:SharedObject;
mySO = SharedObject.getLocal("preferences");

これによってクライアントのマシン上に preferences.sol というファイルが作成されます。

local という用語は、共有オブジェクトの場所を指します。この場合、Adobe® Flash® Player によって、クライアントのホームディレクトリ内に SharedObject ファイルがローカルに格納されます。
共有オブジェクトを作成すると、Flash Player によってアプリケーションおよびドメインに対してサンドボックス内に新規ディレクトリが作成されます。また、SharedObject データを格納する *.sol ファイルも作成されます。このファイルのデ
フォルトの場所は、ユーザーのホームディレクトリのサブディレクトリです。次の表に、このディレクトリのデフォルトの場所を示します。
オペレーティングシステム

場所

Windows 95 ／ 98 ／ ME
／ 2000 ／ XP

c:/Documents and Settings/username/Application Data/Macromedia/Flash
Player/#SharedObjects

Windows Vista ／Windows 7

c:/Users/username/AppData/Roaming/Macromedia/Flash Player/#SharedObjects

Macintosh OS X

/Users/username/Library/Preferences/Macromedia/Flash
Player/#SharedObjects/web_domain/path_to_application/application_name/obje
ct_name.sol

Linux ／ Unix

/home/username/.macromedia/Flash_Player/#SharedObjects/web_domain/path_to_
application/application_name/object_name.sol

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

678

ローカルデータの保存#SharedObjects ディレクトリの下は、ランダムに名前が付けられたディレクトリになります。その下はホスト名に一致す
るディレクトリ、次にアプリケーションへのパス、最後に *.sol ファイルとなります。
例えば、ローカルホスト上で /sos という名前のサブディレクトリ内に MyApp.swf という名前のアプリケーションを要求した場合、Flash Player によって Windows XP の次の場所に *.sol ファイルが格納されます。
c:/Documents and Settings/fred/Application Data/Macromedia/Flash
Player/#SharedObjects/KROKWXRK/#localhost/sos/MyApp.swf/data.sol

注意：SharedObject.getLocal() メソッドに名前を指定しない場合は、Flash Player によってファイルに undefined.sol という名前が付けられます。
デフォルトでは、Flash によってドメインごとに最大 100 KB の永続的な SharedObject オブジェクトをローカルに保存できます。この値はユーザーが設定可能です。アプリケーションが共有オブジェクトにデータを保存しようとし、その共有オ
ブジェクトが 100 KB を超えるサイズになる場合には、Flash Player によってローカル記憶領域ダイアログボックスが表示されます。ユーザーはこのダイアログボックスを使用すると、アクセスを要求しているドメインに対してより多くのローカ
ル記憶領域を許可または拒否することができます。

パスの指定Flash Player 9 以降、Adobe AIR 1.0 以降
オプションの pathname パラメーターを使用して、SharedObject ファイルの場所を指定できます。このファイルは、そのドメインの SharedObject ディレクトリのサブディレクトリである必要があります。例えば、ローカルホスト上でアプリ
ケーションを要求し、次のように指定した場合、
mySO = SharedObject.getLocal("myObjectFile","/");

Flash Player によって SharedObject ファイルが /#localhost ディレクトリ（アプリケーションがオフラインの場合は/localhost）に書き込まれます。これは、クライアント上の複数のアプリケーションが同じ共有オブジェクトにアクセスできるようにする必要がある場合に役立ちます。この場合、クライアントは、ドメインのルートである共有オブジェクトへのパスを指定する 2 つの Flex アプリケーションを実行可能です。クライアントは両方のアプリケーションから同じ共有オブ
ジェクトにアクセスできるようになります。永続性のない複数のアプリケーション間でデータを共有するには、

LocalConnection オブジェクトを使用できます。
存在しないディレクトリを指定した場合、Flash Player によって SharedObject ファイルは作成されません。

共有オブジェクトへのデータの追加
Flash Player 9 以降、Adobe AIR 1.0 以降
SharedObject オブジェクトの data プロパティを使用して、SharedObject の *.sol ファイルにデータを追加します。共有オ
ブジェクトに新規データを追加するには、次のシンタックスを使用します。
sharedObject_name.data.variable = value;

次の例では、userName、itemNumbers および adminPrivileges プロパティとその値を SharedObject に追加します。
public var currentUserName:String = "Reiner";
public var itemsArray:Array = new Array(101,346,483);
public var currentUserIsAdmin:Boolean = true;
mySO.data.userName = currentUserName;
mySO.data.itemNumbers = itemsArray;
mySO.data.adminPrivileges = currentUserIsAdmin;

data プロパティに値を割り当てた後、これらの値を SharedObject のファイルに書き込むように Flash Player に指示する必要があります。Flash Player によって強制的に SharedObject のファイルに値を書き込むには、次のようにSharedObject.flush() メソッドを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

679

ローカルデータの保存

mySO.flush();SharedObject.flush() メソッドを呼び出さない場合は、アプリケーションの終了時に Flash Player によって値がファイルに書き込まれます。ただし、データがデフォルト設定を超える場合に、Flash Player でそのデータの格納に使用可能なスペースを増やす機会はユーザーに与えられません。したがって、SharedObject.flush() を呼び出すことをお勧めします。
flush() メソッドを使用してユーザーのハードディスクに共有オブジェクトを書き込む場合は、次の例に示すように、Flash
Player の設定マネージャー（www.macromedia.com/support/documentation/jp/flashplayer/help/settings_manager07.html）を使用してローカ
ル記憶領域を明示的に無効にしてあるかどうかを慎重に確認する必要があります。
var so:SharedObject = SharedObject.getLocal("test");trace("Current SharedObject size is " + so.size + " bytes.");so.flush();

共有オブジェクトへのオブジェクトの格納

Array や String などの単純なオブジェクトは、SharedObject の data プロパティに格納できます。
次の例に、共有オブジェクトとの対話を制御するメソッドを定義する ActionScript クラスを示します。これらのメソッドを使用すると、ユーザーは共有オブジェクトにオブジェクトを追加したり、共有オブジェクトからオブジェクトを削除した
りすることができます。このクラスには、単純なオブジェクトを含む ArrayCollection が格納されます。
package {import mx.collections.ArrayCollection;
import flash.net.SharedObject;public class LSOHandler {private var mySO:SharedObject;private var ac:ArrayCollection;
private var lsoType:String;// The parameter is "feeds" or "sites".
public function LSOHandler(s:String) {init(s);}private function init(s:String):void {ac = new ArrayCollection();lsoType = s;
mySO = SharedObject.getLocal(lsoType);if (getObjects()) {最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

680

ローカルデータの保存

ac = getObjects();}}
public function getObjects():ArrayCollection {return mySO.data[lsoType];}
public function addObject(o:Object):void {ac.addItem(o);updateSharedObjects();}
private function updateSharedObjects():void {mySO.data[lsoType] = ac;
mySO.flush();}}}次の Flex アプリケーションでは、必要な共有オブジェクトのタイプごとに、ActionScript クラスのインスタンスが作成されます。その後、ユーザーがブログまたはサイト URL を追加または削除するときに、そのクラスでメソッドが呼び出されます。
<?xml version="1.0"?><!-- lsos/BlogAggregator.mxml --><mx:Application
xmlns:local="*"xmlns:mx="http://www.adobe.com/2006/mxml"
creationComplete="initApp()"backgroundColor="#ffffff"><mx:Script><![CDATA[
import mx.collections.ArrayCollection;
import mx.utils.ObjectUtil;
import flash.net.SharedObject;[Bindable]
public var welcomeMessage:String;[Bindable]
public var localFeeds:ArrayCollection = new ArrayCollection();[Bindable]
public var localSites:ArrayCollection = new ArrayCollection();public var lsofeeds:LSOHandler;
public var lsosites:LSOHandler;
private function initApp():void {lsofeeds = new LSOHandler("feeds");lsosites = new LSOHandler("sites");if (lsofeeds.getObjects()) {localFeeds = lsofeeds.getObjects();}
if (lsosites.getObjects()) {localSites = lsosites.getObjects();}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

681

ローカルデータの保存// Adds a new feed to the feeds DataGrid.
private function addFeed():void {// Construct an object you want to store in the// LSO. This object can contain any number of fields.
var o:Object = {name:ti1.text, url:ti2.text, date:new Date()};lsofeeds.addObject(o);// Because the DataGrid's dataProvider property is// bound to the ArrayCollection, Flex updates the// DataGrid when you call this method.
localFeeds = lsofeeds.getObjects();// Clear the text fields.
ti1.text = '';ti2.text = '';}// Removes feeds from the feeds DataGrid.
private function removeFeed():void {// Use a method of ArrayCollection to remove a feed.
// Because the DataGrid's dataProvider property is// bound to the ArrayCollection, Flex updates the// DataGrid when you call this method. You do not need// to update it manually.
if (myFeedsGrid.selectedIndex > -1) {localFeeds.removeItemAt(myFeedsGrid.selectedIndex);}}private function addSite():void {var o:Object = {name:ti3.text, date:new Date()};lsosites.addObject(o);localSites = lsosites.getObjects();
ti3.text = '';}private function removeSite():void {if (mySitesGrid.selectedIndex > -1) {localSites.removeItemAt(mySitesGrid.selectedIndex);}}]]></mx:Script><mx:Label text="Blog aggregator" fontSize="28"/><mx:Panel title="Blogs"><mx:Form id="blogForm"><mx:HBox><mx:FormItem label="Name:"><mx:TextInput id="ti1" width="100"/></mx:FormItem><mx:FormItem label="Location:"><mx:TextInput id="ti2" width="300"/></mx:FormItem><mx:Button id="b1" label="Add Feed" click="addFeed()"/></mx:HBox>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

682

ローカルデータの保存<mx:FormItem label="Existing Feeds:"><mx:DataGrid
id="myFeedsGrid"
dataProvider="{localFeeds}"
width="400"/></mx:FormItem><mx:Button id="b2" label="Remove Feed" click="removeFeed()"/></mx:Form></mx:Panel><mx:Panel title="Sites"><mx:Form id="siteForm"><mx:HBox><mx:FormItem label="Site:"><mx:TextInput id="ti3" width="400"/></mx:FormItem><mx:Button id="b3" label="Add Site" click="addSite()"/></mx:HBox><mx:FormItem label="Existing Sites:"><mx:DataGrid
id="mySitesGrid"
dataProvider="{localSites}"
width="400"/></mx:FormItem><mx:Button id="b4" label="Remove Site" click="removeSite()"/></mx:Form></mx:Panel></mx:Application>

共有オブジェクトへの型指定オブジェクトの格納型指定された ActionScript インスタンスを共有オブジェクトに格納できます。これを行うには、flash.net.registerClassAlias()
メソッドを呼び出してクラスを登録します。クラスのインスタンスを作成し、それを共有オブジェクトのデータメンバーに格納して、後にオブジェクトを読み出す場合は、型指定されたインスタンスを取得します。デフォルトでは、

SharedObject の objectEncoding プロパティでは AMF3 エンコーディングがサポートされており、SharedObject オブジェ
クトから格納されたインスタンスがアンパックされます。格納されたインスタンスでは、ユーザーが registerClassAlias() メ
ソッドを呼び出したときに指定したものと同じ型が保持されます。

（iOS のみ）ローカル共有オブジェクトがクラウドでバックアップされないようにする
Adobe AIR 3.7 以降、iOS のみ
SharedObject.preventBackup プロパティを設定して、ローカル共有オブジェクトを iOS のクラウドバックアップサービスでバックアップするかどうかを制御できます。これは、再生成や再ダウンロードが可能なものの、オフライン使用時にアプリ
ケーションが適切に機能するために必要なコンテンツに関して、Apple が必須としている設定です。

複数の共有オブジェクトの作成
同じ Flex アプリケーションに対して複数の共有オブジェクトを作成できます。これを行うには、次の例に示すように、共有
オブジェクトのそれぞれに異なるインスタンス名を割り当てます。
public var mySO:SharedObject = SharedObject.getLocal("preferences");public var mySO2:SharedObject = SharedObject.getLocal("history");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

683

ローカルデータの保存

これによって preferences.sol ファイルおよび history.sol ファイルが Flex アプリケーションのローカルディレクトリに作成されます。

セキュアな SharedObject の作成
Flash Player 9 以降、Adobe AIR 1.0 以降
getLocal() または getRemote() でローカルまたはリモートの SharedObject を作成する際にオプションの secure というパラメーターを指定すると、その共有オブジェクトについて、HTTPS 経由で配信される SWF ファイルのみにアクセスを制限するかどうかを定義できます。HTTPS 経由で配信される SWF ファイルにおいて、このパラメーターを true に設定すると、セキュアな共有オブジェクトが新しく作成されるか、既存のセキュアな共有オブジェクトに対する参照が取得されます。このセキュアな共有オブジェクトに対する読み取りまたは書き込みは、HTTPS で配信された SWF ファイルによってのみ行
えます。このとき SWF ファイルは SharedObject.getLocal() を、secure パラメーターを true に設定して呼び出します。
HTTPS 経由で配信される SWF ファイルにおいて、このパラメーターを false に設定すると、共有オブジェクトが新しく作成されるか、既存の共有オブジェクトに対する参照が取得されます。
この場合の共有オブジェクトは HTTPS 以外の接続を経由して配信される SWF ファイルからも読み書きできます。HTTPS
以外の接続を経由して配信される SWF ファイルにおいて、このパラメーターを true に設定しようとすると、新しい共有オ
ブジェクトの作成（または既存のセキュアな共有オブジェクトへのアクセス）に失敗してエラーがスローされ、共有オブジェクトは null に設定されます。次のコードを、HTTPS 以外の接続を経由して配信される SWF ファイルで実行しようとすると、SharedObject.getLocal() メソッドでエラーがスローされます。
try{
var so:SharedObject = SharedObject.getLocal("contactManager", null, true);}catch (error:Error){
trace("Unable to create SharedObject.");}

このパラメーターの値にかかわらず、作成された共有オブジェクトは、各ドメインに割り当てられた総ディスク容量の一部を使用します。

共有オブジェクトのコンテンツの表示
Flash Player 9 以降、Adobe AIR 1.0 以降
共有オブジェクトに保存する値は、data プロパティ内に格納されます。ループで共有オブジェクトインスタンス内の個々の値にアクセスするには、次のように for..in ループを使用します。
var so:SharedObject = SharedObject.getLocal("test");so.data.hello = "world";
so.data.foo = "bar";so.data.timezone = new Date().timezoneOffset;for (var i:String in so.data){
trace(i + ":\t" + so.data[i]);}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

684

ローカルデータの保存

共有オブジェクトの破棄
Flash Player 9 以降、Adobe AIR 1.0 以降
クライアント上で SharedObject を破棄するには、SharedObject.clear() メソッドを使用します。これによってアプリケー
ションの共有オブジェクトに対するデフォルトパス内のディレクトリは破棄されません。
次の例では、クライアントから SharedObject ファイルが削除されます。
public function destroySharedObject():void {mySO.clear();}SharedObject の例
Flash Player 9 以降、Adobe AIR 1.0 以降
次の例では、Date オブジェクトなどの単純なオブジェクトを手動で直列化または非直列化する必要なく、SharedObject オ
ブジェクトに格納します。
次の例では、まず、ユーザーを初めての訪問者として歓迎します。「Log Out」をクリックすると、アプリケーションによって共有オブジェクトに現在の日付が格納されます。次にユーザーがこのアプリケーションを起動するかページを更新したとき、アプリケーションではユーザーのログアウト時間とともに再訪問歓迎のメッセージが表示されます。
アプリケーションの動作を確認するには、アプリケーションを起動し、「Log Out」をクリックしてから、ページを更新します。ユーザーが前回の訪問時に「Log Out」ボタンをクリックした日付と時間がアプリケーションに表示されます。
「DeleteLSO」ボタンをクリックすると、格納されている情報をいつでも削除できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

685

ローカルデータの保存<?xml version="1.0"?><!-- lsos/WelcomeMessage.mxml --><mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="initApp()"><mx:Script><![CDATA[
public var mySO:SharedObject;[Bindable]
public var welcomeMessage:String;
public function initApp():void {mySO = SharedObject.getLocal("mydata");
if (mySO.data.visitDate==null) {welcomeMessage = "Hello first-timer!"} else {welcomeMessage = "Welcome back. You last visited on " +getVisitDate();}}private function getVisitDate():Date {return mySO.data.visitDate;}private function storeDate():void {mySO.data.visitDate = new Date();mySO.flush();}private function deleteLSO():void {// Deletes the SharedObject from the client machine.
// Next time they log in, they will be a 'first-timer'.
mySO.clear();}]]></mx:Script><mx:Label id="label1" text="{welcomeMessage}"/><mx:Button label="Log Out" click="storeDate()"/><mx:Button label="Delete LSO" click="deleteLSO()"/></mx:Application>

暗号化されたローカルストア
EncryptedLocalStore クラス（ELS）は、暗号化されたローカル記憶領域のメカニズムを提供します。このメカニズムは、
アプリケーションのプライベートデータ用の小規模なキャッシュとして使用できます。ELS のデータはアプリケーション間で共有できません。ELS の目的は、ログイン資格情報や他の個人情報などの再作成されたアイテムをアプリケーションで簡単に格納できるようにすることです。ELS のデータは、以下の「暗号化されたローカルストアの制限事項」および「ベストプラクティス」で説明されているように、永続的なデータとしては扱わないでください。
注意：暗号化されたローカルストアが用意されているだけでなく、AIR は、SQL データベースに格納されたコンテンツの暗号化も提供します。詳しくは、729 ページの「SQL データベースでの暗号化の使用」を参照してください。

Web サービスに対するログイン資格情報など、セキュリティで保護する必要がある情報をキャッシュするために暗号化されたローカルストアを使用する必要がある場合があります。他のユーザーに対して非公開にする必要がある情報を保存するには、ELS が適切です。ただし、ELS では同じユーザーアカウントで実行される他のプロセスからデータを保護することはできません。このため、DRM や暗号化キーなどの機密アプリケーションデータを保護するには適切でありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

686

ローカルデータの保存

デスクトッププラットフォームにおいて、AIR では、Windows は DPAPI、Mac OS は KeyChain、Linux は KeyRing ま
たは KWallet を使用して、暗号化されたローカルストアを各アプリケーションおよびユーザーに関連付けます。暗号化されたローカルストアは AES-CBC 128 ビット暗号化を使用します。

Android では、EncryptedLocalStorage クラスによって保存されたデータは暗号化されません。代わりに、データはオペ
レーティングシステムに用意されているユーザーレベルのセキュリティによって保護されます。Android オペレーティング
システムはすべてのアプリケーションに個別のユーザー ID を割り当てます。アプリケーションがアクセスできるのは、自身のファイルと、パブリックロケーション（リムーバブルストレージカードなど）で作成されたファイルだけです。「ルート化された」Android デバイス上では、ルート権限で実行しているアプリケーションは、他のアプリケーションのファイルにアクセス可能です。したがって、ルート化されたデバイスでは、ルート化されていないデバイスで確保される暗号化されたローカルストアの高いデータ保護レベルが実現されません。
暗号化されたローカルストア内の情報は、アプリケーションセキュリティサンドボックス内の AIR アプリケーションコンテ
ンツでのみ使用できます。

AIR アプリケーションを更新すると、更新されたバージョンには暗号化されたローカルストアの既存のデータへのアクセス権が保持されます。ただし、次の場合を除きます。

• stronglyBound パラメーターを true に設定してアイテムが追加された場合。
•

既存バージョンと更新バージョンが両方とも AIR 1.5.3 以前にパブリッシュされていて、更新が移行署名で署名されている場合。

暗号化されたローカルストアの制限事項
暗号化されたローカルストアのデータは、ユーザーのオペレーティングシステムアカウントの資格情報で保護されています。
他のエンティティは、そのユーザーとしてログインできる場合を除き、ストア内のデータにアクセスできません。ただし、認証されたユーザーによって実行される他のアプリケーションからのアクセスに対しては、データのセキュリティは保護されません。
このような攻撃を機能させるにはユーザーが認証される必要があるので、ユーザーのプライベートデータは保護されます（ユーザーアカウント自体が偽装されない限り）。ただし、ライセンスやデジタル権限管理用のキーなど、アプリケーション
でユーザーに公開しない可能性のあるデータは、保護されません。したがって、ELS はそのような情報を格納するのに適切な場所ではありません。ELS は、パスワードなどのユーザーのプライベートデータを保存する目的にのみ適しています。

ELS 内のデータは、様々な理由で失われる場合があります。例えば、ユーザーがアプリケーションをアンインストールしたり、暗号化されたデータを削除したりする場合があります。また、更新の結果、発行者 ID が変更される場合があります。
このように、ELS は永続的なデータ記憶領域ではなく、プライベートキャッシュとして扱う必要があります。

stronglyBound パラメーターはサポートされなくなったため、true に設定しないでください。このパラメーターを true に設定
しても、追加のデータ保護は提供されません。同時に、発行者 ID が同じでもアプリケーションが更新されるとデータへのアクセスが失われます。
格納されたデータが 10MB を超えると、暗号化されたローカルストアの処理が遅くなる場合があります。

AIR アプリケーションをアンインストールするときは、アンインストーラーは暗号化されたローカルストアに格納されたデータを削除しません。
ベストプラクティス

ELS を使用するためのベストプラクティスには次のようなものがあります。

•

パスワードなどのユーザーの機密データを保存する目的で ELS を使用します（stronglyBound を false に設定）。

• DRM キーやライセンスのトークンなどのアプリケーションの機密情報を保存する目的では ELS を使用しないでくださ
い。

• ELS データが失われた場合に、ELS に保存されたデータをアプリケーションで作成し直す方法を提供します。例えば、必要に応じて、ユーザーにアカウント資格情報の再入力を求めます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

687

ローカルデータの保存• stronglyBound パラメーターは使用しないでください。
• stronglyBound を true に設定する場合は、更新中に保存されたアイテムを移行しないでください。代わりに、更新後にデータを再作成します。

•

比較的少量のデータのみ保存します。それより大きな量のデータに対しては、暗号化を適用した AIR SQL データベースを使用します。

関連項目

flash.data.EncryptedLocalStore

暗号化されたローカルストアへのデータの追加
EncryptedLocalStore クラスの setItem() 静的メソッドを使用して、データをローカルストアに格納します。データは、ス
トリングをキーとして使用し、バイト配列として格納されたデータと共に、ハッシュテーブルに格納されます。
例えば、次のコードは暗号化されたローカルストアにストリングを格納します。
var str:String = "Bob";var bytes:ByteArray = new ByteArray();
bytes.writeUTFBytes(str);
EncryptedLocalStore.setItem("firstName", bytes);

setItem() メソッドの 3 番目のパラメーターである stronglyBound パラメーターはオプションです。このパラメーターを trueに設定すると、暗号化されたローカルストアは、格納している AIR アプリケーションのデジタル署名とビット列に、格納されたアイテムをバインドします。
var str:String = "Bob";var bytes:ByteArray = new ByteArray();
bytes.writeUTFBytes(str);
EncryptedLocalStore.setItem("firstName", bytes, false);true に設定された stronglyBound を使用して格納されたアイテムの場合、getItem() に対する後続の呼び出しは、呼び出しを行っている AIR アプリケーションが格納を行っているアプリケーションと同一である場合（アプリケーションディレクトリ
内のファイル内のデータが変更されていない場合）にのみ成功します。呼び出しを行っている AIR アプリケーションが格納を行っているアプリケーションと異なる場合、強力にバインドされたアイテムに対する getItem() を呼び出したときに、アプ
リケーションは Error 例外をスローします。アプリケーションをアップデートした場合、暗号化されたローカルストアに以前書き込まれた、強力にバインドされたデータを読み取ることはできません。モバイルデバイスでは stronglyBound を trueに設定しても無視され、このパラメーターは常に false として扱われます。
stronglyBound パラメーターが false （既定）に設定されている場合、アプリケーションがデータを読み取るためには、発行者 ID のみ同じままである必要があります。アプリケーションのビット列は変化してもよく（同じ発行者による署名が必要です）、データを格納したアプリケーションのビット列とまったく同じである必要はありません。元のアプリケーションと同じ発行者 ID を持つアップデートされたアプリケーションは、データに引き続きアクセスできます。
注意：実際には、stronglyBound を true に設定すると、新たなデータ保護は追加されません。このため、悪意のあるユーザー
がアプリケーションを改ざんして ELS に格納されているアイテムにアクセスする可能性が残ります。さらに、データはstronglyBound を true 設定するか false に設定するかにかかわらず、外部の、ユーザー以外の脅威から同様に強力に保護されます。こうした理由から、stronglyBound を true に設定することはお勧めしません。

暗号化されたローカルストアのデータへのアクセス
Adobe AIR 1.0 およびそれ以降
次の例のように EncryptedLocalStore.getItem() メソッドを使用すると、暗号化されたローカルストアから値を取得できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

688

ローカルデータの保存

var storedValue:ByteArray = EncryptedLocalStore.getItem("firstName");trace(storedValue.readUTFBytes(storedValue.length)); // "Bob"

暗号化されたローカルストアからのデータの削除
Adobe AIR 1.0 およびそれ以降
次の例のように、EncryptedLocalStore.removeItem() メソッドを使用して、暗号化されたローカルストアから値を削除できます。
EncryptedLocalStore.removeItem("firstName");

次の例のように、EncryptedLocalStore.reset() メソッドを呼び出すことによって、暗号化されたローカルストアからすべてのデータを消去できます。
EncryptedLocalStore.reset();最終更新日 2015/10/14

689

第 40 章：AIR を使用したローカル SQL データ
ベースの操作
Adobe AIR 1.0 およびそれ以降
Adobe® AIR® にはローカル SQL データベースの作成と操作を行う機能が含まれています。Adobe AIR ランタイムには、
オープンソースの SQLite データベースシステムを使用する、多くの標準 SQL 機能をサポートする SQL データベースエンジンが含まれています。ローカル SQL データベースは永続的なローカルデータの格納に使用できます。例えば、ローカル

SQL データベースは、アプリケーションデータ、アプリケーションユーザー設定、ドキュメント、またはアプリケーション
でローカルに保存する他の任意のタイプのデータに使用できます。

ローカル SQL データベースについて
Adobe AIR 1.0 およびそれ以降
SQL データベースの使用に関する簡単な説明およびコード例については、Adobe Developer Connection で次のクイック
スタートの記事を参照してください。

•

ローカル SQL データベースの非同期操作（Flex）•

ローカル SQL データベースの同期操作（Flex）•

暗号化されたローカル SQLite データベースの操作（Flex）•

ローカル SQL データベースの非同期操作（Flash）•

ローカル SQL データベースの同期操作（Flash）•

暗号化されたローカル SQLite データベースの操作（Flash）

Adobe AIR には、ランタイム内で実行される SQL ベースのリレーショナルデータベースエンジンが含まれています。デー
タベースのデータは、AIR アプリケーションが実行されているコンピューター上（コンピューターのハードディスク上など）のデータベースファイルにローカルで格納されます。データベースの実行やデータファイルの格納はローカルで行われるため、ネットワーク接続が利用可能かどうかに関係なく AIR アプリケーションでデータベースを使用できます。したがって、ランタイムのローカル SQL データベースエンジンは、永続的なローカルアプリケーションデータを格納するための便利なメカニズムとして利用できます。SQL やリレーショナルデータベースの使用経験がある場合には特に便利です。

ローカル SQL データベースの用途
Adobe AIR 1.0 およびそれ以降
AIR のローカル SQL データベース機能は、ユーザーのローカルコンピューターにアプリケーションデータを格納するあらゆる用途に使用できます。Adobe AIR には、データをローカルに格納するためのメカニズムが複数含まれており、それぞれに異なる利点があります。AIR アプリケーションでのローカル SQL データベースの用途としては、例えば次のようなものが考えられます。

•

データ指向アプリケーション（アドレス帳など）では、データベースを使用してメインアプリケーションデータを格納できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

690

AIR を使用したローカル SQL データベースの操作•

ユーザーがドキュメントを作成して保存したり共有したりするドキュメント指向アプリケーションでは、各ドキュメント
をデータベースファイルとしてユーザーが指定した場所に保存できます（ただし、データベースが暗号化されていない限
り、任意の AIR アプリケーションでデータベースファイルを開くことができます。潜在的に機密性の高いドキュメントについては、暗号化することをお勧めします）。

•

ネットワーク対応アプリケーションでは、アプリケーションデータのローカルキャッシュを格納したり、ネットワーク接続を利用できない場合にデータを一時的に格納したりするためにデータベースを使用できます。ローカルデータベースをネットワークデータストアと同期させるためのメカニズムを作成することもできます。

•

すべてのアプリケーションで、個々のユーザーのアプリケーション設定（ユーザーオプションなど）やアプリケーション
情報（ウィンドウのサイズや位置など）を格納するためにデータベースを使用できます。

関連項目

Christophe Coenraets：Employee Directory on AIR for Android
Raymond Camden：jQuery and AIR - Moving from web page to application

AIR データベースとデータベースファイルについて
Adobe AIR 1.0 およびそれ以降
個々の Adobe AIR ローカル SQL データベースは、コンピューターのファイルシステム内の 1 つのファイルとして格納されます。ランタイムには、データベースファイルの作成および構成や、データベースファイルのデータの操作および取得を管理する SQL データベースエンジンが含まれています。データベースのデータをファイルシステムのどこにどのように格納す
るかをランタイムが指定することはありません。各データベースはそれぞれがすべて 1 つのファイルに格納されます。デー
タベースファイルをファイルシステムのどこに格納するかはユーザーが指定します。1 つの AIR アプリケーションで、独立した 1 つ以上のデータベース（データベースファイル）にアクセスできます。各データベースはファイルシステム上の 1 つのファイルとして格納されるため、アプリケーションの設計やオペレーティングシステムのファイルアクセスの制約によって必要とされる場所にデータベースを配置できます。各ユーザーが自分のデータのためにそれぞれ異なるデータベースファイルを使用することも、1 つのコンピューターのすべてのアプリケーションユーザーが 1 つのデータベースファイルにアクセスしてデータを共有することもできます。データは 1 つのコンピューターでローカルに格納されるため、別のコンピュー
ターのユーザーとは自動的に共有されません。ローカル SQL データベースエンジンには、リモートデータベースやサーバー
ベースのデータベースに対して SQL ステートメントを実行する機能は用意されていません。

リレーショナルデータベースについて
Adobe AIR 1.0 およびそれ以降
リレーショナルデータベースは、データをコンピューターに格納（および取得）するためのメカニズムです。リレーショナ
ルデータベースのデータはテーブルにまとめられます。テーブルの行はレコードまたは項目を表し、テーブルの列（「フィールド」とも呼ばれます）は各レコードを個別の値に分割します。例えば、アドレス帳アプリケーションに「友人」テーブルが含まれていた場合、テーブルの各行はデータベースに格納されている 1 人の友人を表し、テーブルの列は名前、姓、誕生日などのデータを表します。テーブルの各友人の行に対して、各列の値が個別に格納されます。
リレーショナルデータベースは、項目が別の種類の項目に関連付けられる複雑なデータを格納できるように作られています。
リレーショナルデータベースでは、一対多の関係を持つ（1 つのレコードを別の種類の複数のレコードに関連付けることができる）データをすべて別のテーブルに分割する必要があります。例えば、アドレス帳アプリケーションで各友人について複数の電話番号を格納する場合、それは一対多の関係になります。この場合は、「友人」テーブルに各友人のすべての個人情報を格納し、別の「電話番号」テーブルにすべての友人のすべての電話番号を格納します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

691

AIR を使用したローカル SQL データベースの操作

各テーブルでは、友人や電話番号のデータを格納するほかに、この 2 つのテーブルの関係を追跡する（個々の友人のレコードをその電話番号に対応させる）ためのデータも必要になります。このデータを主キーと呼びます。主キーとは、テーブルの各行をそのテーブルの他の行から区別する一意の識別子です。主キーには、「自然キー」を使用することができます。自然
キーとは、テーブルの各レコードを自然に区別するデータ項目です。「友人」テーブルに同じ誕生日を持つ友人が含まれていないことがわかっている場合は、誕生日の列を「友人」テーブルの主キー（自然キー）として使用できます。自然キーがない場合は、「友人 ID」などの主キー列を別途作成します。これは、アプリケーションで行を区別するために使用する人工的な値です。
主キーを使用して複数のテーブルの間に関係を設定することができます。例えば、各行（各友人）の一意の番号を含む「友人 ID」列が「友人」テーブルにある場合、「友人」テーブルに関連付けられる「電話番号」テーブルは、電話番号が属する
友人の「友人 ID」を含む列と、実際の電話番号を含む列の、2 つの列で構成できます。これにより、どんなにたくさんの電話番号を持つ友人がいたとしても、すべての電話番号を「電話番号」テーブルに格納し、「友人 ID」の主キーを使用してその友人に関連付けることができます。あるテーブルの主キーが、関連テーブルでレコード間の関連を指定するために使用されている場合、その関連テーブルの値を外部キーと呼びます。AIR のローカルデータベースエンジンでは、多くのデータ
ベースのように外部キー制約（挿入されたり更新されたりした外部キーの値に対応する行が主キーテーブルにあるかどうかを自動的に確認する制約）を作成することはできませんが、外部キー関係はリレーショナルデータベースの構造の重要な部分です。データベースのテーブルの間に関係を作成するときには外部キーを使用する必要があります。

SQL についてAdobe AIR 1.0 およびそれ以降
構造化照会言語（SQL）は、リレーショナルデータベースでデータを操作したり取得したりするために使用されます。SQL
は、手続き型言語ではなく記述言語です。SQL ステートメントでは、データの取得方法をコンピューターに指示するのではなく、必要なデータのセットを記述します。データの取得方法はデータベースエンジンによって決定されます。

SQL 言語は、米国規格協会（ANSI）によって標準化されています。Adobe AIR のローカル SQL データベースは、SQL92 標準のほとんどをサポートしています。
Adobe AIR でサポートされる SQL 言語について詳しくは、1067 ページの「ローカルデータベースでの SQL サポート」を参照してください。

SQL データベースクラスについて
Adobe AIR 1.0 およびそれ以降
ActionScript 3.0 でローカル SQL データベースを操作するには、flash.data パッケージの以下のクラスのインスタンスを使
用します。
クラス

説明

flash.data.SQLConnection

データベース（データベースファイル）を作成したり開いたりするための手段や、データベースレベルの操作を実行したりデータベーストランザクションを制御したりするためのメソッドを提供します。

flash.data.SQLStatement

データベースに対して実行される 1 つの SQL ステートメント（1 つのクエリまたはコマンド）を表します。ス
テートメントテキストの定義とパラメーター値の設定が含まれます。

flash.data.SQLResult

ステートメントの実行に関する情報や実行の結果（SELECT ステートメントの結果行、UPDATE ステートメントやDELETE ステートメントの影響を受ける行の数など）を取得するための方法を提供します。

データベースの構造を記述するスキーマの情報を取得するには、flash.data パッケージの以下のクラスを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

692

AIR を使用したローカル SQL データベースの操作

クラス

説明

flash.data.SQLSchemaResult

SQLConnection.loadSchema() メソッドの呼び出しによって生成されるデータベーススキーマの結果のコンテナ

flash.data.SQLTableSchema

データベース内の 1 つのテーブルを記述する情報を提供します。

flash.data.SQLViewSchema

データベース内の 1 つのビューを記述する情報を提供します。

として機能します。

flash.data.SQLIndexSchema データベース内のテーブルまたはビューの 1 つの列を記述する情報を提供します。
flash.data.SQLTriggerSchem データベース内の 1 つのトリガーを記述する情報を提供します。
aflash.data パッケージにはそのほか、SQLConnection クラスや SQLColumnSchema クラスで使用される定数を提供する
クラスもあります。
クラス

説明flash.data.SQLMode

SQLConnection.open() メソッドと SQLConnection.openAsync() メソッドの openMode パラメーターで使用できる値を表す一連の定数を定義します。

flash.data.SQLColumnNameStyleSQLConnection.columnNameStyle プロパティで使用できる値を表す一連の定数を定義します。

flash.data.SQLTransactionLockTyp SQLConnection.begin() メソッドのオプションパラメーターで使用できる値を表す一連の定数を定義します。
e
SQLColumnSchema.defaultCollationType プロパティと SQLColumnSchema() コンストラクターのdefaultCollationType パラメーターで使用できる値を表す一連の定数を定義します。

flash.data.SQLCollationType

また、flash.events パッケージには、使用するイベント（およびサポート定数）を表す以下のクラスがあります。
クラス

説明flash.events.SQLEvent

SQLConnection または SQLStatement のインスタンスで操作が正常に実行された場合に送出されるイベントを定義します。SQLEvent クラスには、各操作に関連付けられたイベント型定数が定義されています。

flash.events.SQLErrorEvent

SQLConnection または SQLStatement のインスタンスで操作がエラーになった場合に送出されるイベントを定義します。

flash.events.SQLUpdateEve INSERT、UPDATE、DELETE のいずれかの SQL ステートメントが実行された結果、接続先データベースのテーブ
nt
ルデータが変更された場合に、SQLConnection インスタンスで送出されるイベントを定義します。

さらに、flash.errors パッケージには、データベース操作のエラーに関する情報を提供する以下のクラスがあります。
クラス

説明flash.errors.SQLError

データベース操作のエラーに関する情報（実行された操作や失敗の原因など）を提供します。

flash.errors.SQLErrorOperat SQLError クラスの operation プロパティで使用できる値を表す一連の定数を定義します。このプロパティは、エion
ラーになったデータベース操作を示します。

同期実行モードと非同期実行モードについて
Adobe AIR 1.0 およびそれ以降
ローカル SQL データベースを操作するためのコードを記述する際には、非同期実行モードまたは同期実行モードのどちらの実行モードでデータベース操作を実行するかを指定します。コード例では通常、各操作の実行方法が両方の方法で示されているため、ニーズに合う方の例を使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

693

AIR を使用したローカル SQL データベースの操作

非同期実行モードでは、ランタイムに命令を与えると、要求した操作が完了または失敗したときにイベントが送出されます。
まず、データベースエンジンに操作を実行するように命令します。データベースエンジンの処理はバックグラウンドで行われ、アプリケーションは引き続き実行されます。操作が完了（または失敗）すると、データベースエンジンがイベントを送出します。そのイベントによってコードがトリガーされて、それに続く操作が実行されます。このアプローチには、データベース操作がバックグラウンドで実行されている間もメインのアプリケーションコードの実行が継続されるという大きな利点があります。データベースの操作に時間がかかったとしても、アプリケーションは引き続き実行されるため、最も重要な点として、画面が動かなくなったりしてユーザーの操作が妨げられることがありません。その一方で、非同期操作のコードは他のコードに比べて記述が難しくなることがあります。一般的には、依存する複数の操作を様々なイベントリスナーメ
ソッドに分割しなければならない場合に記述が難しくなります。
概念的には、操作をステップの 1 つのシーケンス（一連の同期操作）として記述する方が、複数のイベントリスナーメソッドに分割された一連の操作として記述するより簡単です。Adobe AIR では、データベース操作を非同期に実行するほかに、同期的に実行することもできます。同期実行モードでは、操作はバックグラウンドではなく、他のすべてのアプリケーショ
ンコードと同じ実行シーケンスで実行されます。データベースエンジンに操作を実行するように命令すると、その時点でコードが一時停止して、その間にデータベースエンジンの処理が行われます。操作が完了すると、コードの次の行から実行が再開されます。
操作を非同期に実行するか同期的に実行するかは、SQLConnection のレベルで設定します。1 つのデータベース接続を使用して、操作やステートメントの一部を同期的に実行し、その他を非同期に実行することはできません。SQLConnection
で同期実行モードと非同期実行モードのどちらを使用するかは、データベースを開くための SQLConnection メソッドを呼び出すことによって指定します。SQLConnection.open() を呼び出すとその接続で同期実行モードが使用され、
SQLConnection.openAsync() を呼び出すと非同期実行モードが使用されます。open() または openAsync() を使用して
SQLConnection インスタンスをデータベースに接続すると、実行モードが同期または非同期のいずれかに固定されます。
実行モードを変更するには、データベースへの接続をいったん閉じてもう一度開く必要があります。
各実行モードにはそれぞれ利点があります。ほとんどの面は似ていますが、各モードを使用するときに頭に入れておく必要がある違いがいくつかあります。これらのトピックの詳細と、各モードを使用する際のヒントについては、725 ページの「同期および非同期のデータベース操作の使用」を参照してください。

データベースの作成と変更
Adobe AIR 1.0 およびそれ以降
アプリケーションでデータの追加や取得ができるようになる前に、アプリケーションがアクセスできるデータベースにテーブルが定義されている必要があります。ここで説明するのは、データベース作成タスクと、データベース内にデータ構造を作成するタスクです。これらのタスクはデータの挿入や取得よりも使用回数は少ないですが、ほとんどのアプリケーションに必須のものです。

関連項目

Mind the Flex：Updating an existing AIR database

データベースの作成
Adobe AIR 1.0 およびそれ以降
データベースファイルを作成するには、まず SQLConnection インスタンスを作成します。次に、SQLConnection インス
タンスの open() メソッドを呼び出して接続を同期実行モードで開くか、openAsync() メソッドを呼び出して非同期実行モー
ドで開きます。open() メソッドと openAsync() メソッドは、データベースへの接続を開くために使用されます。open() メ

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

694

AIR を使用したローカル SQL データベースの操作

ソッドまたは openAsync() メソッドで、存在しないファイルの場所を参照する File インスタンスを reference パラメーター（最初のパラメーター）に渡すと、その場所にデータベースファイルが作成され、新たに作成されたデータベースへの接続が開かれます。
データベースを作成する際には、open() メソッドを呼び出すか openAsync() メソッドを呼び出すかに関係なく、任意のファイル名拡張子を持つ任意の有効なファイル名をデータベースファイル名として使用できます。reference パラメーターに nullを渡して open() メソッドや openAsync() メソッドを呼び出すと、ディスク上のデータベースファイルではなく新しいインメ
モリデータベースが作成されます。
次のコードリストは、非同期実行モードを使用してデータベースファイル（新しいデータベース）を作成する手順を示しています。この例では、データベースファイルが「DBSample.db」というファイル名で 647 ページの「アプリケーション記
憶領域ディレクトリの参照」に保存されます。
import flash.data.SQLConnection;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;import flash.filesystem.File;var conn:SQLConnection = new SQLConnection();conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");conn.openAsync(dbFile);
function openHandler(event:SQLEvent):void{
trace("the database was created successfully");}function errorHandler(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

695

AIR を使用したローカル SQL データベースの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;import flash.filesystem.File;private function init():void{
var conn:SQLConnection = new SQLConnection();conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");conn.openAsync(dbFile);}
private function openHandler(event:SQLEvent):void{
trace("the database was created successfully");}
private function errorHandler(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}]]></mx:Script></mx:WindowedApplication>

注意：File クラスでは特定のネイティブファイルパスを参照できますが、その場合、アプリケーションが複数のプラットフォームにわたって機能しなくなる可能性があります。例えば、C:¥Documents and Settings¥joe¥test.db というパスは、Windows 上でのみ機能します。このような理由から、File.applicationStorageDirectory などの File クラスの静的プロパティ
および resolvePath() メソッド（前の例で示したように）を使用することをお勧めします。詳しくは、643 ページの「File オ
ブジェクトのパス」を参照してください。
操作を同期的に実行する場合は、SQLConnection インスタンスでデータベース接続を開くときに open() メソッドを呼び出します。次の例は、操作を同期的に実行する SQLConnection インスタンスを作成して開く方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

696

AIR を使用したローカル SQL データベースの操作

import flash.data.SQLConnection;
import flash.errors.SQLError;
import flash.filesystem.File;var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");try{conn.open(dbFile);
trace("the database was created successfully");}
catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.errors.SQLError;
import flash.filesystem.File;private function init():void{
var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");try{conn.open(dbFile);
trace("the database was created successfully");}
catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}}]]></mx:Script></mx:WindowedApplication>

データベーステーブルの作成
Adobe AIR 1.0 およびそれ以降
データベースのテーブルを作成する際には、SELECT や INSERT などの SQL ステートメントを実行するときと同じ手順を使用して、そのデータベースに対して SQL ステートメントを実行します。テーブルを作成するには、新しいテーブルの列と制約の定義を含む CREATE TABLE ステートメントを使用します。SQL ステートメントの実行について詳しくは、703 ページの「SQL ステートメントの操作」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

697

AIR を使用したローカル SQL データベースの操作

次の例では、非同期実行モードを使用して既存のデータベースファイルに「employees」という名前のテーブルを作成しています。このコードでは、conn という名前の SQLConnection インスタンスが既に作成されてデータベースに接続されていることを前提としています。
import flash.data.SQLConnection;
import flash.data.SQLStatement;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;// ... create and open the SQLConnection instance named conn ...
var createStmt:SQLStatement = new SQLStatement();
createStmt.sqlConnection = conn;
var sql:String ="CREATE TABLE IF NOT EXISTS employees (" +"empId INTEGER PRIMARY KEY AUTOINCREMENT, " +"firstName TEXT, " +"lastName TEXT, " +"salary NUMERIC CHECK (salary > 0)" +")";createStmt.text = sql;
createStmt.addEventListener(SQLEvent.RESULT, createResult);
createStmt.addEventListener(SQLErrorEvent.ERROR, createError);createStmt.execute();function createResult(event:SQLEvent):void{
trace("Table created");}function createError(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLStatement;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;private function init():void{// ... create and open the SQLConnection instance named conn ...
var createStmt:SQLStatement = new SQLStatement();
createStmt.sqlConnection = conn;
var sql:String ="CREATE TABLE IF NOT EXISTS employees (" +"empId INTEGER PRIMARY KEY AUTOINCREMENT, " +"firstName TEXT, " +"lastName TEXT, " +"salary NUMERIC CHECK (salary > 0)" +")";最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

698

AIR を使用したローカル SQL データベースの操作

createStmt.text = sql;
createStmt.addEventListener(SQLEvent.RESULT, createResult);
createStmt.addEventListener(SQLErrorEvent.ERROR, createError);createStmt.execute();}private function createResult(event:SQLEvent):void{
trace("Table created");}private function createError(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}]]></mx:Script></mx:WindowedApplication>

次の例では、同期実行モードを使用して既存のデータベースファイルに「employees」という名前のテーブルを作成しています。このコードでは、conn という名前の SQLConnection インスタンスが既に作成されてデータベースに接続されていることを前提としています。
import flash.data.SQLConnection;
import flash.data.SQLStatement;
import flash.errors.SQLError;// ... create and open the SQLConnection instance named conn ...
var createStmt:SQLStatement = new SQLStatement();
createStmt.sqlConnection = conn;
var sql:String ="CREATE TABLE IF NOT EXISTS employees (" +"empId INTEGER PRIMARY KEY AUTOINCREMENT, " +"firstName TEXT, " +"lastName TEXT, " +"salary NUMERIC CHECK (salary > 0)" +")";createStmt.text = sql;
try{createStmt.execute();trace("Table created");}catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

699

AIR を使用したローカル SQL データベースの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLStatement;
import flash.errors.SQLError;
private function init():void{// ... create and open the SQLConnection instance named conn ...
var createStmt:SQLStatement = new SQLStatement();
createStmt.sqlConnection = conn;
var sql:String ="CREATE TABLE IF NOT EXISTS employees (" +"empId INTEGER PRIMARY KEY AUTOINCREMENT, " +"firstName TEXT, " +"lastName TEXT, " +"salary NUMERIC CHECK (salary > 0)" +")";createStmt.text = sql;
try{createStmt.execute();trace("Table created");}catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}}]]></mx:Script></mx:WindowedApplication>

SQL データベースのデータの操作
Adobe AIR 1.0 およびそれ以降
ローカル SQL データベースを操作するときに実行する一般的なタスクがいくつか存在します。タスクの内容は、データベースへの接続、データベース内のテーブルへのデータ追加、テーブルからのデータ取得などです。これらのタスクを行う
ときには心がけておくべきいくつかの項目があります。それは例えば、データ型の操作やエラー処理などです。
一般的なタスクよりも実行頻度が少ないデータベースタスクもいくつかありますが、一般的なタスクよりも前に実行が必要なタスクがほとんどです。例えば、データベースに接続してテーブルからデータを取得できるようになる前には、データベースを作成し、そのデータベースの中にテーブル構造を作成する必要があります。これらの実行頻度の少ない初期設定タ
スクについては、693 ページの「データベースの作成と変更」を参照してください。
データベース操作を非同期で実行すると選択することもできます。非同期操作では、データベースエンジンがバックグラウ
ンドで実行され、イベントの送出によって操作の成功または失敗が通知されます。また、これらの操作を同期的に実行することもできます。同期の場合、データベース操作は 1 つずつ実行され、アプリケーション全体（画面への更新を含む）はある操作が完了するのを待ってから別のコードを実行します。非同期実行モードおよび同期実行モードでの操作について詳し
くは、725 ページの「同期および非同期のデータベース操作の使用」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

700

AIR を使用したローカル SQL データベースの操作

データベースへの接続
Adobe AIR 1.0 およびそれ以降
データベース操作を実行するには、まずデータベースファイルへの接続を開く必要があります。SQLConnection インスタ
ンスは 1 つ以上のデータベースへの接続を表すために使用されます。SQLConnection インスタンスを使用して接続した最初のデータベースを「メイン」データベースと呼びます。このデータベースには、open() メソッド（同期実行モードの場合）
または openAsync() メソッド（非同期実行モードの場合）を使用して接続します。
非同期 openAsync() 操作を使用してデータベースを開く場合は、openAsync() 操作が完了したら通知されるように、

SQLConnection インスタンスの open イベントに登録します。また、操作が失敗したかどうかを確認できるように、
SQLConnection インスタンスの error イベントに登録します。
次の例は、既存のデータベースファイルを非同期実行用に開く方法を示しています。このデータベースファイルは「DBSample.db」という名前で、ユーザーの 647 ページの「アプリケーション記憶領域ディレクトリの参照」に保存されています。
import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;import flash.filesystem.File;var conn:SQLConnection = new SQLConnection();conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");conn.openAsync(dbFile, SQLMode.UPDATE);
function openHandler(event:SQLEvent):void{
trace("the database opened successfully");}function errorHandler(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

701

AIR を使用したローカル SQL データベースの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;import flash.filesystem.File;private function init():void{
var conn:SQLConnection = new SQLConnection();conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");conn.openAsync(dbFile, SQLMode.UPDATE);}
private function openHandler(event:SQLEvent):void{
trace("the database opened successfully");}
private function errorHandler(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}]]></mx:Script></mx:WindowedApplication>

次の例は、既存のデータベースファイルを同期実行用に開く方法を示しています。このデータベースファイルは「DBSample.db」という名前で、ユーザーの 647 ページの「アプリケーション記憶領域ディレクトリの参照」に保存されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

702

AIR を使用したローカル SQL データベースの操作

import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.errors.SQLError;
import flash.filesystem.File;var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");try{conn.open(dbFile, SQLMode.UPDATE);
trace("the database opened successfully");}
catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.errors.SQLError;
import flash.filesystem.File;private function init():void{
var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");try{conn.open(dbFile, SQLMode.UPDATE);
trace("the database opened successfully");}
catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}}]]></mx:Script></mx:WindowedApplication>

非同期実行の例の openAsync() メソッドの呼び出しと、同期実行の例の open() メソッドの呼び出しで、2 番目の引数が定数

SQLMode.UPDATE になっていることに注意してください。2 番目のパラメーター（openMode）に SQLMode.UPDATE を指定すると、指定したファイルが存在しない場合にエラーが送出されます。openMode パラメーターに SQLMode.CREATE を渡すと（または openMode パラメーターをオフのままにすると）、指定したファイルが存在しない場合にデータベースファイ
ルが作成されます。ただし、ファイルが存在する場合は、ファイルが開かれます。この動作は、SQLMode.Update を使用し最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

703

AIR を使用したローカル SQL データベースの操作た場合と同じです。そのほか、openMode パラメーターに SQLMode.READ を指定して既存のデータベースを読み取り専用
モードで開くこともできます。その場合は、データベースからデータを取得することはできますが、データを追加したり、削除したり、変更したりすることはできません。

SQL ステートメントの操作
Adobe AIR 1.0 およびそれ以降
個々の SQL ステートメント（クエリまたはコマンド）は、ランタイム内で SQLStatement オブジェクトとして表されます。

SQL ステートメントを作成して実行するには次の手順に従ってください。
SQLStatement インスタンスを作成します。
SQLStatement オブジェクトは、アプリケーション内で SQL ステートメントを表します。
var selectData:SQLStatement = new SQLStatement();

クエリを実行するデータベースを指定します。
そのためには、SQLStatement オブジェクトの sqlConnection プロパティを、目的のデータベースに接続されている

SQLConnection インスタンスに設定します。
// A SQLConnection named "conn" has been created previously
selectData.sqlConnection = conn;

実際の SQL ステートメントを指定します。
ステートメントテキストを String として作成し、SQLStatement インスタンスの text プロパティに割り当てます。
selectData.text = "SELECT col1, col2 FROM my_table WHERE col1 = :param1";

実行操作の結果を処理するための関数を定義します（非同期実行モードのみ）。

addEventListener() メソッドを使用して、SQLStatement インスタンスの result イベントと error イベントのリスナーとして関数を登録します。
// using listener methods and addEventListener()selectData.addEventListener(SQLEvent.RESULT, resultHandler);selectData.addEventListener(SQLErrorEvent.ERROR, errorHandler);function resultHandler(event:SQLEvent):void{// do something after the statement execution succeeds}
function errorHandler(event:SQLErrorEvent):void{// do something after the statement execution fails}

または、Responder オブジェクトを使用してリスナーメソッドを指定することもできます。その場合は、Responder イン
スタンスを作成してリスナーメソッドを関連付けます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

704

AIR を使用したローカル SQL データベースの操作// using a Responder (flash.net.Responder)
var selectResponder = new Responder(onResult, onError);function onResult(result:SQLResult):void{// do something after the statement execution succeeds}
function onError(error:SQLError):void{// do something after the statement execution fails}

ステートメントテキストにパラメーター定義が含まれている場合は、それらのパラメーターに値を割り当てます。
パラメーター値を割り当てるには、SQLStatement インスタンスの parameters 連想配列プロパティを使用します。
selectData.parameters[":param1"] = 25;

SQL ステートメントを実行します。
SQLStatement インスタンスの execute() メソッドを呼び出します。
// using synchronous execution mode// or listener methods in asynchronous execution mode
selectData.execute();

さらに、非同期実行モードでイベントリスナーの代わりに Responder を使用している場合は、その Responder インスタン
スを execute() メソッドに渡します。
// using a Responder in asynchronous execution mode
selectData.execute(-1, selectResponder);これらの手順の具体例については、以下のトピックを参照してください。

707 ページの「データベースからのデータの取得」
716 ページの「データの挿入」
721 ページの「データの変更または削除」

ステートメント内でのパラメーターの使用
Adobe AIR 1.0 およびそれ以降
SQL ステートメントパラメーターを使用すると、再利用可能な SQL ステートメントを作成できます。ステートメントパラ
メーターを使用する場合、ステートメント内の値は変わっても（INSERT ステートメントの追加される値など）、基本的なス
テートメントテキストは変わりません。その結果、パラメーターを使用することでパフォーマンスが向上し、アプリケー
ションのコーディングも容易になります。

ステートメントパラメーターについて
Adobe AIR 1.0 およびそれ以降
アプリケーションで 1 つの SQL ステートメントが、小さな変更を加えながら何度も使用されることがよくあります。例えば、ユーザーが新しい在庫品目をデータベースに追加できる在庫追跡アプリケーションでは、在庫品目をデータベースに追加するアプリケーションコードで、データを実際にデータベースに追加する SQL INSERT ステートメントが実行されますが、このステートメントは実行のたびに多少変更されます。テーブルに挿入される実際の値は、追加される在庫品目に固有の値であるため、毎回異なるからです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

705

AIR を使用したローカル SQL データベースの操作

このように異なる値で何度も使用される SQL ステートメントがある場合は、SQL テキスト内にリテラル値の代わりにパラメーターを含む SQL ステートメントを使用することをお勧めします。パラメーターは、ステートメントが実行されるたびに実際の値に置き換えられるステートメントテキスト内のプレースホルダーです。SQL ステートメント内でパラメーターを使用するには、SQLStatement インスタンスを通常どおりに作成し、text プロパティに割り当てる実際の SQL ステートメント
で、リテラル値の代わりにパラメータープレースホルダーを使用します。各パラメーターの値は、SQLStatement インスタ
ンスの parameters プロパティの要素の値を設定して定義します。parameters プロパティは連想配列であるため、特定の値を設定するには次のシンタックスを使用します。
statement.parameters[parameter_identifier] = value;

parameter_identifier は、名前付きパラメーターを使用する場合は文字列で、名前のないパラメーターを使用する場合は
整数インデックスです。

名前付きパラメーターの使用
Adobe AIR 1.0 およびそれ以降
パラメーターは、名前付きパラメーターにすることができます。名前付きパラメーターには、パラメーター値をステートメ
ントテキスト内のそのプレースホルダーの場所に対応させるためにデータベースで使用される特定の名前があります。パラ
メーター名は、「:」または「@」の文字と、それに続く名前で構成されます。以下に例を示します。
:itemName@firstName

次のコードリストは、名前付きパラメーターの使用方法を示しています。
var sql:String ="INSERT INTO inventoryItems (name, productCode)" +"VALUES (:name, :productCode)";var addItemStmt:SQLStatement = new SQLStatement();
addItemStmt.sqlConnection = conn;
addItemStmt.text = sql;// set parameter values
addItemStmt.parameters[":name"] = "Item name";
addItemStmt.parameters[":productCode"] = "12345";
addItemStmt.execute();

名前のないパラメーターの使用
Adobe AIR 1.0 およびそれ以降
名前付きパラメーターの代わりに、名前のないパラメーターを使用することもできます。名前のないパラメーターを使用する場合は、SQL ステートメント内で「?」文字を使用してパラメーターを表します。ステートメント内の順番に従って、0 から始まる数値インデックスが各パラメーターに割り当てられます。次の例では、先ほどの例が、名前のないパラメーターを使用するように変更されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

706

AIR を使用したローカル SQL データベースの操作

var sql:String ="INSERT INTO inventoryItems (name, productCode)" +"VALUES (?, ?)";
var addItemStmt:SQLStatement = new SQLStatement();
addItemStmt.sqlConnection = conn;
addItemStmt.text = sql;// set parameter values
addItemStmt.parameters[0] = "Item name";
addItemStmt.parameters[1] = "12345";
addItemStmt.execute();パラメーターを使用するメリット
Adobe AIR 1.0 およびそれ以降
SQL ステートメントでパラメーターを使用すると、次のようなメリットがあります。
パフォーマンスの向上 パラメーターを使用する SQLStatement インスタンスは、実行のたびに SQL テキストを動的に作成する SQLStatement インスタンスに比べて効率的に実行できます。このようにパフォーマンスが向上するのは、1 回準備したステートメントを異なるパラメーター値で何度も実行できるため、SQL ステートメントを再コンパイルする必要がないからです。
明示的なデータ型の指定 パラメーターを使用すると、SQL ステートメントの作成時には不明な値の型指定された置き換えが可能になります。データベースに渡される値の格納クラスを保証するには、パラメーターを使用するしかありません。パラメーターを使用しない場合は、すべての値が、関連付けられている列の型の類似性に基づいてテキスト表現から格納クラスに変換されます。
格納クラスと列の親和型について詳しくは、1088 ページの「データ型のサポート」を参照してください。
セキュリティの強化 パラメーターを使用すると、SQL インジェクション攻撃と呼ばれる悪質なテクニックの防止に役立ちます。SQL インジェクション攻撃では、ユーザーがアクセスできる場所（データ入力フィールドなど）に SQL コードが入力されます。この場合、ユーザー入力を直接 SQL テキストに連結して SQL ステートメントを作成するアプリケーション
コードでは、ユーザーが入力した SQL コードがデータベースに対して実行されます。次のリストは、ユーザー入力が SQL
テキストに連結される例を示しています。この方法は使用しないでください。
// assume the variables "username" and "password"// contain user-entered data
var sql:String ="SELECT userId " +"FROM users " +"WHERE username = '" + username + "' " +"AND password = '" + password + "'";
var statement:SQLStatement = new SQLStatement();
statement.text = sql;

ユーザーが入力した値をステートメントのテキストに連結する代わりにステートメントパラメーターを使用すると、SQL イ
ンジェクション攻撃を防止できます。この場合に SQL インジェクションが発生しないのは、パラメーター値はリテラルス
テートメントテキストの一部にはならず、置き換えられる値として明示的に扱われるからです。以下は、前のリストの代わりとして推奨されるリストです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

707

AIR を使用したローカル SQL データベースの操作// assume the variables "username" and "password"// contain user-entered data
var sql:String ="SELECT userId " +"FROM users " +"WHERE username = :username " +"AND password = :password";var statement:SQLStatement = new SQLStatement();
statement.text = sql;// set parameter values
statement.parameters[":username"] = username;statement.parameters[":password"] = password;

データベースからのデータの取得
Adobe AIR 1.0 およびそれ以降
データベースからデータを取得する操作には 2 つのステップが含まれます。まず、データベースから取得するデータのセッ
トを記述する SQL SELECT ステートメントを実行します。次に、取得したデータにアクセスして、必要に応じてアプリケー
ションで表示または操作します。

SELECT ステートメントの実行
Adobe AIR 1.0 およびそれ以降
データベースから既存のデータを取得するには、SQLStatement インスタンスを使用します。適切な SQL SELECT ステート
メントをインスタンスの text プロパティに割り当てて、インスタンスの execute() メソッドを呼び出します。

SELECT ステートメントのシンタックスについて詳しくは、1067 ページの「ローカルデータベースでの SQL サポート」を参照してください。
次の例では、非同期実行モードを使用し、SELECT ステートメントを実行して「products」という名前のテーブルからデータを取得しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

708

AIR を使用したローカル SQL データベースの操作

var selectStmt:SQLStatement = new SQLStatement();// A SQLConnection named "conn" has been created previously
selectStmt.sqlConnection = conn;
selectStmt.text = "SELECT itemId, itemName, price FROM products";
selectStmt.addEventListener(SQLEvent.RESULT, resultHandler);selectStmt.addEventListener(SQLErrorEvent.ERROR, errorHandler);selectStmt.execute();function resultHandler(event:SQLEvent):void{
var result:SQLResult = selectStmt.getResult();
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++){var row:Object = result.data[i];var output:String = "itemId: " + row.itemId;
output += "; itemName: " + row.itemName;
output += "; price: " + row.price;
trace(output);}}function errorHandler(event:SQLErrorEvent):void{// Information about the error is available in the// event.error property, which is an instance of// the SQLError class.
}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.errors.SQLError;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;private function init():void{
var selectStmt:SQLStatement = new SQLStatement();// A SQLConnection named "conn" has been created previously
selectStmt.sqlConnection = conn;
selectStmt.text = "SELECT itemId, itemName, price FROM products";
selectStmt.addEventListener(SQLEvent.RESULT, resultHandler);selectStmt.addEventListener(SQLErrorEvent.ERROR, errorHandler);selectStmt.execute();}private function resultHandler(event:SQLEvent):void{
var result:SQLResult = selectStmt.getResult();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

709

AIR を使用したローカル SQL データベースの操作

var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++){var row:Object = result.data[i];var output:String = "itemId: " + row.itemId;
output += "; itemName: " + row.itemName;
output += "; price: " + row.price;
trace(output);}}
private function errorHandler(event:SQLErrorEvent):void{// Information about the error is available in the// event.error property, which is an instance of// the SQLError class.
}]]></mx:Script></mx:WindowedApplication>

次の例では、同期実行モードを使用し、SELECT ステートメントを実行して「products」という名前のテーブルからデータを取得します。
var selectStmt:SQLStatement = new SQLStatement();// A SQLConnection named "conn" has been created previously
selectStmt.sqlConnection = conn;
selectStmt.text = "SELECT itemId, itemName, price FROM products";
try{
selectStmt.execute();var result:SQLResult = selectStmt.getResult();
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++){var row:Object = result.data[i];var output:String = "itemId: " + row.itemId;
output += "; itemName: " + row.itemName;
output += "; price: " + row.price;
trace(output);}}
catch (error:SQLError){// Information about the error is available in the// error variable, which is an instance of// the SQLError class.
}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

710

AIR を使用したローカル SQL データベースの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.errors.SQLError;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;private function init():void{
var selectStmt:SQLStatement = new SQLStatement();// A SQLConnection named "conn" has been created previously
selectStmt.sqlConnection = conn;
selectStmt.text = "SELECT itemId, itemName, price FROM products";
try{
selectStmt.execute();var result:SQLResult = selectStmt.getResult();
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++){var row:Object = result.data[i];var output:String = "itemId: " + row.itemId;
output += "; itemName: " + row.itemName;
output += "; price: " + row.price;
trace(output);}}
catch (error:SQLError){// Information about the error is available in the// error variable, which is an instance of// the SQLError class.
}}]]></mx:Script></mx:WindowedApplication>

非同期実行モードでは、ステートメントの実行が完了すると SQLStatement インスタンスによって result イベント
（SQLEvent.RESULT）が送出されて、ステートメントが正常に実行されたことが通知されます。または、Responder オブジェクトを引数として execute() メソッドに渡した場合は、Responder オブジェクトの結果ハンドラー関数が呼び出されます。同期実行モードでは、execute() 操作が完了するまで実行が一時停止され、その後、コードの次の行から再開されます。

SELECT ステートメントの結果データへのアクセス
Adobe AIR 1.0 およびそれ以降
SELECT ステートメントの実行が完了したら、次の手順として、取得したデータにアクセスします。SELECT ステートメン
トの実行結果のデータを取得するには、SQLStatement オブジェクトの getResult() メソッドを呼び出します。
var result:SQLResult = selectStatement.getResult();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

711

AIR を使用したローカル SQL データベースの操作

getResult() メソッドは SQLResult オブジェクトを返します。SQLResult オブジェクトの data プロパティは SELECT ステー
トメントの結果が格納された配列です。
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++){// row is an Object representing one row of result data
var row:Object = result.data[i];}SELECT の結果セットの各データ行は、data 配列に格納される Object インスタンスになります。そのオブジェクトには、結果セットの列と同じ名前のプロパティがあります。そのプロパティに、結果セットの列の値が格納されます。例えば、「itemId」、「itemName」および「price」の 3 つの列を含む結果セットを SELECT ステートメントで指定した場合は、
itemId、itemName および price の 3 つのプロパティを持つ Object インスタンスが結果セットの各行について作成されて、各プロパティにそれぞれの列の値が格納されます。
次のコードリストでは、text プロパティが SELECT ステートメントの SQLStatement インスタンスを定義しています。このステートメントは、employees というテーブルのすべての行の firstName 列と lastName 列の値を含む行を取得します。この
例では非同期実行モードを使用しています。実行が完了したら、selectResult() メソッドを呼び出します。その後、
SQLStatement.getResult() を使用して結果行にアクセスして、trace() メソッドを使用して表示します。このリストでは、connという名前の SQLConnection インスタンスが既に作成されてデータベースに接続されていることと、「employees」テー
ブルが既に作成されてデータが設定されていることを前提としています。
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var selectStmt:SQLStatement = new SQLStatement();
selectStmt.sqlConnection = conn;// define the SQL text
var sql:String ="SELECT firstName, lastName " +"FROM employees";
selectStmt.text = sql;// register listeners for the result and error events
selectStmt.addEventListener(SQLEvent.RESULT, selectResult);
selectStmt.addEventListener(SQLErrorEvent.ERROR, selectError);// execute the statement
selectStmt.execute();function selectResult(event:SQLEvent):void{

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

712

AIR を使用したローカル SQL データベースの操作// access the result data
var result:SQLResult = selectStmt.getResult();
var numRows:int = result.data.length;
for (var i:int = 0; i < numRows; i++){var output:String = "";for (var columnName:String in result.data[i]){output += columnName + ": " + result.data[i][columnName] + "; ";}trace("row[" + i.toString() + "]\t", output);}}function selectError(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;private function init():void{// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var selectStmt:SQLStatement = new SQLStatement();
selectStmt.sqlConnection = conn;// define the SQL text
var sql:String ="SELECT firstName, lastName " +"FROM employees";
selectStmt.text = sql;// register listeners for the result and error events
selectStmt.addEventListener(SQLEvent.RESULT, selectResult);
selectStmt.addEventListener(SQLErrorEvent.ERROR, selectError);// execute the statement
selectStmt.execute();}private function selectResult(event:SQLEvent):void{// access the result data
var result:SQLResult = selectStmt.getResult();

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

713

AIR を使用したローカル SQL データベースの操作

var numRows:int = result.data.length;
for (var i:int = 0; i < numRows; i++){var output:String = "";for (var columnName:String in result.data[i]){output += columnName + ": " + result.data[i][columnName] + "; ";}trace("row[" + i.toString() + "]\t", output);}}
private function selectError(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}]]></mx:Script></mx:WindowedApplication>

次のコードリストで使用されているのは、先ほどの例と同じテクニックです。ただし、今度は同期実行モードを使用しています。この例では、text プロパティが SELECT ステートメントの SQLStatement インスタンスを定義しています。このス
テートメントは、employees というテーブルのすべての行の firstName 列と lastName 列の値を含む行を取得します。
SQLStatement.getResult() を使用して結果行にアクセスして、trace() メソッドを使用して表示します。このリストでは、connという名前の SQLConnection インスタンスが既に作成されてデータベースに接続されていることと、「employees」テー
ブルが既に作成されてデータが設定されていることを前提としています。
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.errors.SQLError;// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var selectStmt:SQLStatement = new SQLStatement();
selectStmt.sqlConnection = conn;// define the SQL text
var sql:String ="SELECT firstName, lastName " +"FROM employees";
selectStmt.text = sql;try{// execute the statement
selectStmt.execute();最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

714

AIR を使用したローカル SQL データベースの操作// access the result data
var result:SQLResult = selectStmt.getResult();
var numRows:int = result.data.length;
for (var i:int = 0; i < numRows; i++){var output:String = "";for (var columnName:String in result.data[i]){output += columnName + ": " + result.data[i][columnName] + "; ";}trace("row[" + i.toString() + "]\t", output);}}
catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.errors.SQLError;
private function init():void{// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var selectStmt:SQLStatement = new SQLStatement();
selectStmt.sqlConnection = conn;// define the SQL text
var sql:String ="SELECT firstName, lastName " +"FROM employees";
selectStmt.text = sql;try{// execute the statement
selectStmt.execute();// access the result data
var result:SQLResult = selectStmt.getResult();
var numRows:int = result.data.length;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

715

AIR を使用したローカル SQL データベースの操作

for (var i:int = 0; i < numRows; i++){var output:String = "";for (var columnName:String in result.data[i]){output += columnName + ": ";output += result.data[i][columnName] + "; ";}trace("row[" + i.toString() + "]\t", output);}}
catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}}]]></mx:Script></mx:WindowedApplication>

SELECT の結果データのデータ型の定義
Adobe AIR 1.0 およびそれ以降既定では、SELECT ステートメントによって返される各行は Object インスタンスとして作成されます。この Object インス
タンスには結果セットの列名と同じ名前のプロパティがあり、各列の値がプロパティの値として格納されます。しかし、

SQL SELECT ステートメントを実行する前に SQLStatement インスタンスの itemClass プロパティを設定してクラスを指定することもできます。itemClass プロパティを設定すると、SELECT ステートメントによって返される各行が、指定したクラスのインスタンスとして作成されます。結果の列の値は、SELECT の結果セットの列名を itemClass クラスのプロパティ名に対応付けることによってプロパティ値に割り当てられます。

itemClass プロパティとして割り当てるクラスには、パラメーターを必要としないコンストラクターと、SELECT ステートメ
ントによって返される各列に対応するプロパティが必要です。SELECT のリストの列に対応するプロパティ名が itemClass ク
ラスにない場合はエラーと見なされます。

SELECT の結果の分割
Adobe AIR 1.0 およびそれ以降既定では、SELECT ステートメントを実行すると結果セットのすべての行が一度に取得されます。ステートメントの完了後は、取得したデータを何らかの形で処理するのが一般的ですが（オブジェクトを作成する、データを画面に表示するなど）、
ステートメントによって返される行の数が多い場合にすべてのデータを一度に処理すると、コンピューターに負荷がかかり、
ユーザーインターフェイスの再描画が行われなくなる可能性があります。
このような場合にアプリケーションの体感的なパフォーマンスを向上させるには、一度に取得する結果行の数を指定します。
これにより、最初の結果データがすぐに返されるようになるほか、結果行を複数のセットに分割して、各セットが処理されるたびにユーザーインターフェイスが更新されるようにすることができます。ただし、このテクニックを使用できるのは非同期実行モードを使用している場合だけです。

SELECT の結果を分割して取得するには、SQLStatement.execute() メソッドの最初のパラメーター（prefetch パラメーター）の値を指定します。prefetch パラメーターは、ステートメントが初めて実行されたときに取得する行数を表します。

SQLStatement インスタンスの execute() メソッドを呼び出すときに prefetch パラメーター値を指定すると、指定した行数のみが取得されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

716

AIR を使用したローカル SQL データベースの操作

var stmt:SQLStatement = new SQLStatement();
stmt.sqlConnection = conn;
stmt.text = "SELECT ...";
stmt.addEventListener(SQLEvent.RESULT, selectResult);
stmt.execute(20); // only the first 20 rows (or fewer) are returned

結果行の最初のセットが利用可能になると、result イベントが送出されます。結果となる SQLResult インスタンスの data プ
ロパティにデータの行が格納され、取得する結果行がまだあるかどうかが complete プロパティによって示されます。さらに
結果行を取得するには、SQLStatement インスタンスの next() メソッドを呼び出します。next() メソッドの最初のパラメー
ターは、execute() メソッドと同様に、次に result イベントが送出されたときに取得する行数を表します。
function selectResult(event:SQLEvent):void{
var result:SQLResult = stmt.getResult();
if (result.data != null){// ... loop through the rows or perform other processing ...
if (!result.complete){stmt.next(20); // retrieve the next 20 rows}
else{
stmt.removeEventListener(SQLEvent.RESULT, selectResult);}}}

result イベントは、next() メソッドによって結果行の続きのセットが返されるたびに送出されます。したがって、すべての行が取得されるまで同じリスナー関数を使用して（next() の呼び出しの）結果の処理を続けることができます。
詳しくは、SQLStatement.execute() メソッド（の prefetch パラメーター）の説明と SQLStatement.next() メソッドの説明を参照してください。

データの挿入Adobe AIR 1.0 およびそれ以降
データベースにデータを追加する際には SQL INSERT ステートメントを実行します。ステートメントの実行が完了したら、新たに挿入された行の主キーにアクセスできます（データベースによってキーが生成された場合）。

INSERT ステートメントの実行
Adobe AIR 1.0 およびそれ以降
データベースのテーブルにデータを追加するには、text プロパティが SQL INSERT ステートメントの SQLStatement イン
スタンスを作成して実行します。
次の例では、既に存在している employees テーブルに 1 行のデータを追加する SQLStatement インスタンスが使用されています。この例は、非同期実行モードを使用してデータを挿入する方法を示しています。このリストでは、conn という名前の SQLConnection インスタンスが既に作成されてデータベースに接続されていることと、「employees」テーブルが既に作成されていることを前提としています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

717

AIR を使用したローカル SQL データベースの操作

import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var insertStmt:SQLStatement = new SQLStatement();
insertStmt.sqlConnection = conn;// define the SQL text
var sql:String ="INSERT INTO employees (firstName, lastName, salary) " +"VALUES ('Bob', 'Smith', 8000)";
insertStmt.text = sql;// register listeners for the result and failure (status) events
insertStmt.addEventListener(SQLEvent.RESULT, insertResult);
insertStmt.addEventListener(SQLErrorEvent.ERROR, insertError);// execute the statement
insertStmt.execute();function insertResult(event:SQLEvent):void{
trace("INSERT statement succeeded");}function insertError(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;private function init():void{// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var insertStmt:SQLStatement = new SQLStatement();
insertStmt.sqlConnection = conn;// define the SQL text
var sql:String ="INSERT INTO employees (firstName, lastName, salary) " +"VALUES ('Bob', 'Smith', 8000)";
insertStmt.text = sql;// register listeners for the result and failure (status) events

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

718

AIR を使用したローカル SQL データベースの操作

insertStmt.addEventListener(SQLEvent.RESULT, insertResult);
insertStmt.addEventListener(SQLErrorEvent.ERROR, insertError);// execute the statement
insertStmt.execute();}private function insertResult(event:SQLEvent):void{
trace("INSERT statement succeeded");}private function insertError(event:SQLErrorEvent):void{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}]]></mx:Script></mx:WindowedApplication>

次の例では、同期実行モードを使用して、既に存在する employees テーブルに 1 行のデータを追加しています。このリスト
では、conn という名前の SQLConnection インスタンスが既に作成されてデータベースに接続されていることと、「employees」テーブルが既に作成されていることを前提としています。
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.errors.SQLError;// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var insertStmt:SQLStatement = new SQLStatement();
insertStmt.sqlConnection = conn;// define the SQL text
var sql:String ="INSERT INTO employees (firstName, lastName, salary) " +"VALUES ('Bob', 'Smith', 8000)";
insertStmt.text = sql;try{// execute the statement
insertStmt.execute();trace("INSERT statement succeeded");}catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

719

AIR を使用したローカル SQL データベースの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"><mx:Script><![CDATA[
import flash.data.SQLConnection;
import flash.data.SQLResult;import flash.data.SQLStatement;
import flash.errors.SQLError;
private function init():void{// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var insertStmt:SQLStatement = new SQLStatement();
insertStmt.sqlConnection = conn;// define the SQL text
var sql:String ="INSERT INTO employees (firstName, lastName, salary) " +"VALUES ('Bob', 'Smith', 8000)";
insertStmt.text = sql;try{// execute the statement
insertStmt.execute();trace("INSERT statement succeeded");}catch (error:SQLError){
trace("Error message:", error.message);
trace("Details:", error.details);}}]]></mx:Script></mx:WindowedApplication>

挿入された行の（データベースによって生成される）主キーの取得
Adobe AIR 1.0 およびそれ以降
テーブルにデータの行を挿入した後に、新たに挿入された行の（データベースによって生成される）主キーや行識別子の値がコードで必要になることがよくあります。例えば、テーブルに行を挿入した後に関連テーブルの行を追加する場合は、主キー値を関連テーブルの外部キーとして挿入する必要があります。新たに挿入された行の主キーを取得するには、ステート
メントの実行に関連した SQLResult オブジェクトを使用します。これは、SELECT ステートメントの実行後に結果データにアクセスするために使用するのと同じオブジェクトです。INSERT ステートメントの実行が完了すると、他の SQL ステート
メントの場合と同様に SQLResult インスタンスが作成されます。その SQLResult インスタンスにアクセスするには、

SQLStatement オブジェクトの getResult() メソッドを呼び出します（イベントリスナーを使用している場合と同期実行モードを使用している場合）。非同期実行モードを使用していて、execute() の呼び出しで Responder インスタンスを渡した場合
は、その結果ハンドラー関数に SQLResult インスタンスが引数として渡されます。いずれの場合も、その SQLResult イン
スタンスの lastInsertRowID プロパティに、直前に挿入された行の行識別子が格納されています（実行された SQL ステート
メントが INSERT ステートメントの場合）。
次の例は、挿入された行の主キーに非同期実行モードでアクセスする方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

720

AIR を使用したローカル SQL データベースの操作

insertStmt.text = "INSERT INTO ...";
insertStmt.addEventListener(SQLEvent.RESULT, resultHandler);
insertStmt.execute();function resultHandler(event:SQLEvent):void{// get the primary key
var result:SQLResult = insertStmt.getResult();
var primaryKey:Number = result.lastInsertRowID;// do something with the primary key}

次の例は、挿入された行の主キーに同期実行モードでアクセスする方法を示しています。
insertStmt.text = "INSERT INTO ...";
try{
insertStmt.execute();// get the primary key
var result:SQLResult = insertStmt.getResult();
var primaryKey:Number = result.lastInsertRowID;// do something with the primary key}
catch (error:SQLError){// respond to the error}

行識別子は、テーブル定義で主キー列として指定されている列の値である場合もあれば、そうでない場合もあります。これは次のルールによって決まります。

•

テーブルの定義で使用されている主キー列の類似性（列のデータ型）が INTEGER の場合は、その行に挿入された値（AUTOINCREMENT 列の場合にはランタイムによって生成された値）が lastInsertRowID プロパティに格納されます。

•

テーブルの定義で複数の主キー列（複合キー）が使用されている場合や、主キー列が 1 つでも親和型 INTEGER ではない
場合は、その行の行識別子の整数値が背後で生成されます。その生成された値が lastInsertRowID プロパティの値になります。

•

この値は常に、直前に挿入された行の行識別子です。INSERT ステートメントがトリガーを発生させて、その結果として行が挿入された場合は、INSERT ステートメントによって作成された行ではなく、トリガーによって挿入された最後の行の行識別子が lastInsertRowID プロパティに格納されます。

これらのルールによって、INSERT コマンドの実行後に SQLResult.lastInsertRowID プロパティを通じて値を取得できる、明示的に定義された主キー列が必要な場合は、その列を INTEGER PRIMARY KEY 列として定義する必要があります。明示的な INTEGER PRIMARY KEY 列がテーブルに含まれていなくても、関連テーブルとの関係を定義するという意味では、デー
タベースによって生成される行識別子をテーブルの主キーとして使用しても何ら問題はありません。SQL ステートメントで行識別子列の値を取得するには、特殊な列名のいずれか（ROWID、_ROWID_、または OID）を使用します。関連テーブル
で外部キー列を作成して、行識別子の値を（明示的に宣言された INTEGER PRIMARY KEY 列の場合と同じように）その外部キー列の値として使用することもできます。その意味では、自然キーではなく恣意的な主キーを使用している場合に、主キー値がランタイムによって生成されても問題がなければ、2 つのテーブルの間の外部キー関係を定義するためのテーブルの主キーとして INTEGER PRIMARY KEY 列を使用しても、システム生成の行識別子を使用しても、ほとんど違いはありません。
主キーと生成された行識別子について詳しくは、1067 ページの「ローカルデータベースでの SQL サポート」を参照してく
ださい。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

721

AIR を使用したローカル SQL データベースの操作

データの変更または削除
Adobe AIR 1.0 およびそれ以降
その他のデータ操作を実行するための手順は、703 ページの「SQL ステートメントの操作」で説明している SQL SELECT
ステートメントや INSERT ステートメントを実行するための手順と変わりません。SQLStatement インスタンスの text プロ
パティを別の SQL ステートメントに置き換えるだけです。

•

テーブルの既存のデータを変更する場合は UPDATE ステートメントを使用します。

•

テーブルの 1 つ以上のデータ行を削除する場合は DELETE ステートメントを使用します。

これらのステートメントについて詳しくは、1067 ページの「ローカルデータベースでの SQL サポート」を参照してください。

複数のデータベースの操作
Adobe AIR 1.0 およびそれ以降
SQLConnection.attach() メソッドを使用すると、既に開いているデータベースがある SQLConnection インスタンスで追加のデータベースへの接続を開くことができます。attach() メソッドの呼び出しで name パラメーターを使用して、関連付け
るデータベースに名前を付けます。その名前は、そのデータベースを操作するステートメントを記述する際に、SQL ステー
トメント内でテーブル名を修飾するための接頭辞として使用できます（データベース名 . テーブル名の形式を使用します）。こ
れにより、そのテーブルがそのデータベースにあることをランタイムに対して示すことができます。
同じ SQLConnection インスタンスに接続されている複数のデータベースのテーブルを含む 1 つの SQL ステートメントを実行することができます。SQLConnection インスタンスでトランザクションを作成すると、そのトランザクションは、その SQLConnection インスタンスを使用して実行されるすべての SQL ステートメントに適用されます。関連付けられているどのデータベースに対してステートメントが実行されるかは関係ありません。
また、アプリケーションで複数の SQLConnection インスタンスを作成して、各インスタンスを 1 つ以上のデータベースに接続することもできます。ただし、同じデータベースに対して複数の接続を使用する場合は、データベーストランザクショ
ンは複数の SQLConnection インスタンスにまたがって共有されないことに注意する必要があります。その結果、複数の

SQLConnection インスタンスを使用して同じデータベースファイルに接続すると、両方の接続のデータ変更が正しく適用されるという保証が得られなくなります。例えば、2 つの UPDATE ステートメントまたは DELETE ステートメントを別のSQLConnection インスタンスを通じて同じデータベースに対して実行した場合に、1 つ目の操作の実行後にアプリケー
ションエラーが発生すると、データベースのデータが元に戻せない中間状態のままになり、データベースの整合性（および、結果としてアプリケーション）に影響が及ぶ可能性があります。

データベースエラーの処理
Adobe AIR 1.0 およびそれ以降
一般に、データベースエラーの処理は他のランタイムエラーの処理と同様で、発生する可能性があるエラーに備えたコードを記述して、ランタイムではなくそのコードがエラーに応答するようにします。発生する可能性があるデータベースエラー
は、一般的な意味において 3 つのカテゴリに分類できます。接続エラー、SQL シンタックスエラーおよび制約エラーの 3 つです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

722

AIR を使用したローカル SQL データベースの操作

接続エラー
Adobe AIR 1.0 およびそれ以降
ほとんどのデータベースエラーは接続エラーです。接続エラーはあらゆる操作で発生します。接続エラーを防止するための対策はありますが、データベースがアプリケーションの重要な部分である場合、接続エラーから速やかに回復するための簡単な方法はほとんどありません。
ほとんどの接続エラーは、ランタイムとオペレーティングシステム、ファイルシステムおよびデータベースファイルとのやり取りに関連しています。例えば、ファイルシステム上の特定の場所にデータベースファイルを作成する権限がユーザーにないと、接続エラーが発生します。接続エラーを防止するための対策を以下に示します。
ユーザー固有のデータベースファイルを使用する 1 つのコンピューターでアプリケーションを使用するすべてのユーザーに対して 1 つのデータベースファイルを使用する代わりに、各ユーザーに専用のデータベースファイルを割り当てます。そのファイルは、ユーザーのアカウントに関連付けられているディレクトリに配置します（アプリケーションの格納ディレクト
リ、ユーザーのドキュメントフォルダー、ユーザーのデスクトップなど）。
様々なユーザーの種類を考慮に入れる 様々なオペレーティングシステムで様々な種類のユーザーアカウントを使用してアプ
リケーションをテストします。ユーザーがコンピューターの管理者権限を持っているとは限りませんし、アプリケーション
をインストールしたユーザーがアプリケーションを実行するとも限りません。
様々なファイルの場所を考慮に入れる ユーザーがデータベースファイルの保存場所を指定したり、開くファイルを選択したりできるようにする場合は、ユーザーによって使用される可能性があるファイルの場所について検討します。さらに、ユーザーがデータベースファイルを格納できる場所（またはデータベースファイルを開くことができる場所）を制限することも検討します。例えば、自分のユーザーアカウントの格納場所にあるファイルのみを開けるようにすることができます。
接続エラーが発生する可能性が最も高いのは、データベースを最初に作成したり開いたりするときです。したがって、接続エラーが発生すると、ユーザーがアプリケーションでデータベース関連の操作を一切実行できなくなります。読み取り専用
エラーや権限エラーなどの一部の種類のエラーに対しては、データベースファイルを別の場所にコピーするという方法でエラーから回復できます。アプリケーションで、ユーザーがファイルの作成や書き込みの権限を持っている別の場所にデータ
ベースファイルをコピーして、その場所を代わりに使用します。

シンタックスエラー
Adobe AIR 1.0 およびそれ以降
シンタックスエラーは、形式が正しくない SQL ステートメントをアプリケーションが実行しようとすると発生します。
ローカルデータベースの SQL ステートメントは文字列として作成されるため、コンパイル時に SQL シンタックスをチェッ
クすることはできません。SQL ステートメントのシンタックスをチェックするには、そのステートメントを実行する必要があります。SQL シンタックスエラーを防止するための対策を以下に示します。
すべての SQL ステートメントを徹底的にテストする できれば、アプリケーションの開発時（SQL ステートメントをステー
トメントテキストとしてアプリケーションコードに含める前）に別途 SQL ステートメントのテストを行います。さらに、単体テストなどのコードテスト手法を使用して、コードのすべてのオプションやバリエーションを実行するテストセットを作成します。

SQL を連結する（動的に生成する）代わりにステートメントパラメーターを使用する SQL ステートメントを動的に作成する代わりにパラメーターを使用すると、毎回同じ SQL ステートメントテキストを使用してステートメントが実行されることになります。その結果、ステートメントのテストが格段に容易になり、コードのバリエーションも限定されます。SQL ス
テートメントを動的に生成する必要がある場合は、ステートメントの動的な部分を最小限に抑えます。また、シンタックス
エラーを引き起こさないようにユーザー入力を慎重に検証します。
アプリケーションでシンタックスエラーから回復するには、SQL ステートメントを調べてシンタックスを修正するための複雑なロジックが必要になります。シンタックスエラーを防止するための上述のガイドラインに従うと、実行時に SQL シン
タックスエラーを引き起こす可能性がある場所（ステートメント内で使用されるユーザー入力など）をコードで特定できま

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

723

AIR を使用したローカル SQL データベースの操作す。シンタックスエラーから回復するには、ユーザーにアドバイスを提供して、ステートメントが正常に実行されるようにするにはどこを修正すればよいかを知らせます。

制約エラー
Adobe AIR 1.0 およびそれ以降
制約エラーは、INSERT ステートメントや UPDATE ステートメントでデータを列に追加するときに、そのテーブルまたは列に対して定義されている制約に新しいデータが違反していると発生します。制約には次のようなものがあります。

UNIQUE 制約 テーブルのすべての行で列の値が重複していてはいけないことを表します。複数の列が UNIQUE 制約で結合される場合は、それらの列の値の組み合わせが重複していてはいけないことになります。つまり、一意として指定された列では、各行がそれぞれ異なっている必要があります。
主キー制約 制約で許可されるデータと許可されないデータに関しては、主キー制約は UNIQUE 制約と同じです。

NOT NULL 制約 列に NULL 値を格納できないことを表します。したがって、すべての行でその列に値がなければならない
ことになります。

CHECK 制約 1 つ以上のテーブルに対して任意の制約を指定できます。CHECK 制約では、列の値が取りうる範囲を定義するルール（数値列の値が 0 より大きくなければならないなど）を指定したり、列の値の関係（一方の列の値がもう一方の列の同じ行の値と異なっていなければならないなど）を指定したりするのが一般的です。
データ型（列の類似性）の制約 列の値のデータ型が強制されて、正しくない型の値を列に格納しようとするとエラーが発生します。ただし、多くの場合は、宣言されている列のデータ型に合わせて値が変換されます。詳しくは、724 ページの「データベースのデータ型の操作」を参照してください。
外部キーの値に対する制約は適用されません。したがって、外部キーの値が既存の主キーの値と一致している必要はありま
せん。
ランタイムの SQL エンジンでは、あらかじめ定義されている種類の制約に加えて、トリガーを使用することもできます。
トリガーとは、イベントハンドラーのように、特定のアクションが発生すると実行される定義済みの命令のセットです。例
えば、特定のテーブルのデータが挿入されたり削除されたりした場合に実行されるトリガーを定義することができます。ト
リガーを使用すると、データの変更を調べて、指定した条件が満たされていない場合にエラーを発生させることもできます。
したがって、トリガーは制約と同じ目的で使用することができます。制約エラーの防止と回復のための対策は、トリガーによって生成されるエラーにも当てはまります。ただし、トリガーによって生成されるエラーのエラー ID は制約エラーのエ
ラー ID とは異なります。
特定のテーブルに適用する制約のセットは、アプリケーションの設計時に決定します。制約を意識的に設計すると、アプリ
ケーションの設計で制約エラーの防止や回復が容易になります。ただし、制約エラーは体系的な予測や防止が困難です。制
約エラーの予測が困難なのは、アプリケーションのデータが追加されるまで明らかにならないからです。制約エラーは、
データベースの作成後、そこに追加されたデータによって発生します。それらのエラーは多くの場合、新しいデータとデー
タベースの既存のデータとの関係に起因しています。多くの制約エラーの防止に役立つ対策を以下に示します。
データベースの構造と制約について入念に計画する 制約の目的は、アプリケーションのルールを適用してデータベースのデータの整合性を保護することです。アプリケーションの計画を立てる際には、アプリケーションをサポートするために必要なデータベースの構造について検討し、その一環としてデータのルールを特定します（特定の値が必要かどうか、値に既定値があるかどうか、重複する値を許可するかどうかなど）。それらのルールに基づいてデータベースの制約を定義できます。
列の名前を明示的に指定する INSERT ステートメントは、値を挿入する列を明示的に指定しなくても記述できますが、無駄にリスクを高めることになります。値を挿入する列の名前を明示的に指定すると、自動的に生成される値、既定値を持つ列、

NULL 値を許容する列などを使用できるようになります。また、すべての NOT NULL 列に明示的な値が挿入されていることを確認することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

724

AIR を使用したローカル SQL データベースの操作

既定値を使用する 列に対して NOT NULL 制約を指定する場合は、可能であれば列定義で既定値を指定します。アプリケー
ションコードで既定値を指定することもできます。例えば、String 変数を使用してステートメントのパラメーター値を設定する前に、その String 変数が null かどうかをコードでチェックして値を割り当てることができます。
ユーザーが入力したデータを検証する 特に NOT NULL 制約と CHECK 制約では、ユーザーが入力したデータを事前にチェックして、制約によって指定されている制限に従っているかどうかを確認します。UNIQUE 制約では、このチェックを行うには SELECT クエリを実行してデータが一意かどうかを確認する必要があるため、必然的に他の制約に比べてチェックが困難になります。
トリガーを使用する トリガーを記述すると、挿入されたデータを検証（および場合によっては置換）したり、正しくない
データを修正するためのその他のアクションを実行したりできます。この検証と修正によって制約エラーの発生を防止できます。
制約エラーは様々な点で他の種類のエラーに比べて防止が困難ですが、幸い、アプリケーションが不安定になったり使用できなくなったりしないような形で制約エラーから回復するための方法がいくつかあります。
競合アルゴリズムを使用する 列に対して制約を定義した場合は、INSERT ステートメントや UPDATE ステートメントを作成するときに競合アルゴリズムを指定することができます。競合アルゴリズムは、制約違反が発生した場合にデータベース
で実行されるアクションを定義します。データベースエンジンで実行できるアクションはいくつかあります。例えば、1 つのステートメントを終了する、トランザクション全体を終了する、エラーを無視するなどのほか、古いデータを削除して、格納しようとしているデータに置き換えることもできます。
詳しくは、1067 ページの「ローカルデータベースでの SQL サポート」の「ON CONFLICT（競合アルゴリズム）」を参照
してください。
修正のためのフィードバックを提供する 特定の SQL コマンドに影響を与える可能性がある制約のセットは事前に特定できるため、ステートメントで発生する可能性がある制約エラーを予測することができます。その知識に基づいて、制約エラーに応答するアプリケーションロジックを作成できます。例えば、新しい製品を入力するためのデータ入力フォームを含むア
プリケーションで、データベースの製品名列の定義で UNIQUE 制約を使用すると、データベースに新しい製品行を挿入する
アクションで制約エラーが発生する可能性があります。したがって、このアプリケーションは、制約エラーを予測する形で設計されます。エラーが発生したら、指定した製品名は既に使用されているという内容の警告メッセージをユーザーに表示
して、別の名前を選択するように求めます。あるいは、同じ名前を持つ他の製品に関する情報をユーザーが表示できるようにすることもできます。

データベースのデータ型の操作
Adobe AIR 1.0 およびそれ以降
データベースにテーブルを作成する際には、テーブルを作成するための SQL ステートメントでテーブルの各列の類似性（データ型）を定義します。類似性の宣言は省略することもできますが、CREATE TABLE SQL ステートメントで列の類似性を明示的に宣言することをお勧めします。
原則として、INSERT ステートメントを使用してデータベースに格納したオブジェクトは、SELECT ステートメントを実行すると同じデータ型のインスタンスとして返されます。ただし、値が格納されるデータベースの列の類似性によっては、異なるデータ型の値が返される場合もあります。値を列に格納するときに、その値のデータ型が列の類似性と一致していないと、値が列の類似性に合わせて変換されます。例えばデータベースの列が NUMERIC 類似性を使用して宣言されていた場合、挿入したデータは、格納される前に数値格納クラス（INTEGER または REAL）に変換されます。データを変換できない場合はエラーがスローされます。このルールに従うと、「12345」という String を NUMERIC 列に挿入した場合は、データベースに格納される前に 12345 という整数値に自動的に変換されます。その値を SELECT ステートメントで取得すると、String ではなく数値データ型（Number など）のインスタンスとして返されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

725

AIR を使用したローカル SQL データベースの操作

望ましくないデータ型の変換が行われないようにするには、2 つのルールに従うのが最善の策になります。まず、各列を定義する際に、その列に格納する予定のデータの型と一致する類似性を使用して定義します。次に、定義されている類似性と一致するデータ型の値のみを挿入するようにします。これらのルールに従うと、2 つのメリットがあります。まず、データの挿入時にデータが予期せず変換される（その結果、場合によってはデータの本来の意味が失われる）ことがなくなります。
また、データの取得時にデータが元のデータ型で返されるようになります。
使用可能な列の親和型の種類と SQL ステートメントでのデータ型の使用について詳しくは、1088 ページの「データ型のサポート」を参照してください。

同期および非同期のデータベース操作の使用
Adobe AIR 1.0 およびそれ以降
これまでの節では、データの取得、挿入、更新、削除などの一般的なデータベース操作と、データベースファイルの作成やデータベース内のテーブルなどのオブジェクトの作成について説明し、それらの操作を非同期に実行する方法と同期的に実行する方法の両方の例を紹介しました。
先にも述べたように、非同期実行モードでは、データベースエンジンに操作を実行するように命令すると、データベースエ
ンジンの処理がバックグラウンドで行われ、アプリケーションは引き続き実行されます。操作が完了すると、そのことを通知するイベントが送出されます。非同期実行には、データベース操作がバックグラウンドで実行されている間もメインのア
プリケーションコードの実行が継続されるという大きな利点があります。このことは、操作の実行に時間がかかる場合に特に重要になります。
一方、同期実行モードでは、操作はバックグラウンドで実行されません。データベースエンジンに操作を実行するように命令すると、その時点でコードが一時停止して、その間にデータベースエンジンの処理が行われます。操作が完了すると、コードの次の行から実行が再開されます。

1 つのデータベース接続で操作やステートメントの一部を同期的に実行し、その他を非同期に実行することはできません。
SQLConnection で同期実行モードと非同期実行モードのどちらを使用するかは、データベースへの接続を開くときに指定します。SQLConnection.open() を呼び出すとその接続で同期実行モードが使用され、SQLConnection.openAsync() を呼び出
すと非同期実行モードが使用されます。open() または openAsync() を使用して SQLConnection インスタンスをデータベースに接続すると、実行モードが同期または非同期のいずれかに固定されます。

同期データベース操作の使用
Adobe AIR 1.0 およびそれ以降
同期実行を使用する場合に操作の実行や応答のために使用する実際のコードは、非同期実行モードのコードとほとんど変わりません。この 2 つのアプローチの主な違いは 2 つの領域に分類できます。1 つは別の操作に依存する操作の実行（SELECTの結果行や、INSERT ステートメントによって追加された行の主キーなど）、もう 1 つはエラー処理です。

同期操作のためのコードの記述
Adobe AIR 1.0 およびそれ以降
同期実行と非同期実行の主な違いとして、同期モードではコードを一続きのステップとして記述するのに対し、非同期コー
ドではイベントリスナーを登録し、たいていは操作を複数のリスナーメソッドに分割します。データベースが同期実行モードで接続されている場合は、一連のデータベース操作を 1 つのコードブロックで連続して実行できます。次の例は、この方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

726

AIR を使用したローカル SQL データベースの操作

var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");// open the databaseconn.open(dbFile, OpenMode.UPDATE);// start a transaction
conn.begin();// add the customer record to the databasevar insertCustomer:SQLStatement = new SQLStatement();
insertCustomer.sqlConnection = conn;
insertCustomer.text ="INSERT INTO customers (firstName, lastName) " +"VALUES ('Bob', 'Jones')";insertCustomer.execute();var customerId:Number = insertCustomer.getResult().lastInsertRowID;// add a related phone number record for the customer
var insertPhoneNumber:SQLStatement = new SQLStatement();
insertPhoneNumber.sqlConnection = conn;
insertPhoneNumber.text ="INSERT INTO customerPhoneNumbers (customerId, number) " +"VALUES (:customerId, '800-555-1234')";
insertPhoneNumber.parameters[":customerId"] = customerId;
insertPhoneNumber.execute();// commit the transaction
conn.commit();

この例からわかるように、同期実行と非同期実行のどちらを使用する場合も、データベース操作を実行するために呼び出す
メソッドは同じです。この 2 つのアプローチの主な違いは、別の操作に依存する操作の実行とエラー処理にあります。

別の操作に依存する操作の実行
Adobe AIR 1.0 およびそれ以降
同期実行モードを使用する場合は、操作の完了を確認するためにイベントをリッスンするコードを記述する必要はなく、コードの前の行の操作が正常に完了するとコードの次の行が実行されるものと考えることができます。したがって、別の操作の成功に依存する操作を実行するには、その操作のコードを依存する操作の直後に記述するだけで済みます。例えば、アプリケーションでトランザクションを開始して、INSERT ステートメントを実行し、挿入した行の主キーを取得して、その主キーを別のテーブルの別の行に挿入した後、最後にトランザクションをコミットするコードを記述する場合、これらすべてのコードを一続きのステートメントとして記述できます。これらの操作を実行する例を以下に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

727

AIR を使用したローカル SQL データベースの操作

var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");// open the databaseconn.open(dbFile, SQLMode.UPDATE);// start a transaction
conn.begin();// add the customer record to the databasevar insertCustomer:SQLStatement = new SQLStatement();
insertCustomer.sqlConnection = conn;
insertCustomer.text ="INSERT INTO customers (firstName, lastName) " +"VALUES ('Bob', 'Jones')";insertCustomer.execute();var customerId:Number = insertCustomer.getResult().lastInsertRowID;// add a related phone number record for the customer
var insertPhoneNumber:SQLStatement = new SQLStatement();
insertPhoneNumber.sqlConnection = conn;
insertPhoneNumber.text ="INSERT INTO customerPhoneNumbers (customerId, number) " +"VALUES (:customerId, '800-555-1234')";
insertPhoneNumber.parameters[":customerId"] = customerId;
insertPhoneNumber.execute();// commit the transaction
conn.commit();

同期実行でのエラー処理
Adobe AIR 1.0 およびそれ以降
同期実行モードでは、操作の失敗を確認するためにエラーイベントをリッスンする代わりに、エラーをトリガーする可能性があるコードを try..catch..finally コードブロックで囲みます。エラーをスローするコードを try ブロックでラップし、それぞれの種類のエラーに対して実行するアクションを個別の catch ブロックに記述して、操作が成功したか失敗したかに関係なく常に実行するコード（不要になったデータベース接続を閉じるコードなど）を finally ブロックに配置します。エラー処理のために try..catch..finally ブロックを使用する例を以下に示します。この例は、前の例にエラー処理のコードを追加したものです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

728

AIR を使用したローカル SQL データベースの操作

var conn:SQLConnection = new SQLConnection();// The database file is in the application storage directoryvar folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");// open the databaseconn.open(dbFile, SQLMode.UPDATE);// start a transaction
conn.begin();try{// add the customer record to the databasevar insertCustomer:SQLStatement = new SQLStatement();
insertCustomer.sqlConnection = conn;
insertCustomer.text ="INSERT INTO customers (firstName, lastName)" +"VALUES ('Bob', 'Jones')";insertCustomer.execute();var customerId:Number = insertCustomer.getResult().lastInsertRowID;// add a related phone number record for the customer
var insertPhoneNumber:SQLStatement = new SQLStatement();
insertPhoneNumber.sqlConnection = conn;
insertPhoneNumber.text ="INSERT INTO customerPhoneNumbers (customerId, number)" +"VALUES (:customerId, '800-555-1234')";
insertPhoneNumber.parameters[":customerId"] = customerId;
insertPhoneNumber.execute();// if we've gotten to this point without errors, commit the transaction
conn.commit();}catch (error:SQLError){// rollback the transaction
conn.rollback();}

非同期実行モデルについて
Adobe AIR 1.0 およびそれ以降
非同期実行モードについて、同じデータベース接続に対して別の SQLStatement が実行されている場合には

SQLStatement インスタンスを開始できないと考えている人がよくいますが、それは正しくありません。SQLStatement イ
ンスタンスが実行されている間は、そのステートメントの text プロパティを変更することはできません。ただし、実行する

SQL ステートメントごとに異なる SQLStatement インスタンスを使用すれば、まだ別の SQLStatement インスタンスが実行されている間に SQLStatement の execute() メソッドを呼び出すことができます。エラーが発生することもありません。
非同期実行モードを使用してデータベース操作を実行する場合、各データベース接続（各 SQLConnection インスタンス）に対して固有のキュー（実行するように命令された操作のリスト）が内部で割り当てられます。各操作はそのキューに追加された順に実行されます。SQLStatement インスタンスを作成してその execute() メソッドを呼び出すと、そのステートメン
トの実行操作が接続のキューに追加され、その SQLConnection インスタンスで現在実行されている操作がなければ、バッ
クグラウンドで実行が開始されます。ここで、同じコードブロックの中で別の SQLStatement インスタンスを作成し、その最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

729

AIR を使用したローカル SQL データベースの操作

execute() メソッドを呼び出したとすると、その 2 つ目のステートメントの実行操作はキューの 1 つ目のステートメントの後に追加されます。1 つ目のステートメントの実行が完了すると、すぐにキューの次の操作が実行されます。キューの次の操
作の処理は、まだメインアプリケーションコードで 1 つ目の操作の result イベントが送出されている間にバックグラウンド
で開始されます。このテクニックを説明するコードを次に示します。
// Using asynchronous execution modevar stmt1:SQLStatement = new SQLStatement();
stmt1.sqlConnection = conn;// ... Set statement text and parameters, and register event listeners ...
stmt1.execute();// At this point stmt1's execute() operation is added to conn's execution queue.
var stmt2:SQLStatement = new SQLStatement();
stmt2.sqlConnection = conn;// ... Set statement text and parameters, and register event listeners ...
stmt2.execute();// At this point stmt2's execute() operation is added to conn's execution queue.
// When stmt1 finishes executing, stmt2 will immediately begin executing// in the background.

このようにキューの次のステートメントを自動的に実行する際には、重要な副作用として、ステートメントが別の操作の結果に依存している場合はその 1 つ目の操作が完了するまでそのステートメントをキューに追加できません（つまり、そのス
テートメントの execute() メソッドを呼び出すことができません）。これは、その 2 つ目のステートメントの execute() メソッ
ドを呼び出してしまうと、そのステートメントの text プロパティや parameters プロパティを変更できなくなるからです。この場合は、1 つ目の操作の完了を知らせるイベントを待ってから次の操作を開始する必要があります。例えば、トランザク
ションのコンテキストでステートメントを実行する場合は、そのステートメントの実行はトランザクションを開く操作に依存するため、SQLConnection.begin() メソッドを呼び出してトランザクションを開いた後、SQLConnection インスタンスのbegin イベントが送出されるまで待機する必要があります。このイベントが送出されるまでは SQLStatement インスタンスの execute() メソッドを呼び出すことはできません。この例で、操作が正常に実行されるようにアプリケーションを構成するには、begin イベントのリスナーとして登録されたメソッドを作成するのが最も簡単です。そのリスナーメソッドの中に、
SQLStatement.execute() メソッドを呼び出すコードを配置します。

SQL データベースでの暗号化の使用
Adobe AIR 1.5 およびそれ以降
すべての Adobe AIR アプリケーションは、同じローカルデータベースエンジンを共有します。したがって、すべての AIR
アプリケーションは、暗号化されていないデータベースファイルに対して接続、読み取り、書き込みを行うことができます。

Adobe AIR 1.5 以降の AIR には、暗号化されたデータベースファイルの作成と接続の機能が含まれています。暗号化されたデータベースを使用する場合、データベースに接続するには、アプリケーションは適切な暗号化キーを提供する必要があります。正しくない暗号化キーが提供された場合、または暗号化キーが提供されなかった場合、アプリケーションはデータベースに接続できません。この結果、アプリケーションはデータベースからデータを読み取ることができず、データベース
へのデータの書き込みやデータベースのデータの変更も行うことができません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

730

AIR を使用したローカル SQL データベースの操作

暗号化されたデータベースを使用するには、暗号化されたデータベースとしてデータベースを作成する必要があります。暗号化された既存のデータベースがある場合は、そのデータベースへの接続を開くことができます。暗号化されたデータベースの暗号化キーを変更することもできます。暗号化されたデータベースの使用方法については、その作成方法と接続方法以外は、暗号化されていないデータベースの場合と同じです。例えば、SQL ステートメントの実行は、データベースが暗号化されている場合も暗号化されていない場合も同じです。

暗号化されたデータベースの使用
Adobe AIR 1.5 およびそれ以降
暗号化は、データベースに保存されている情報へのアクセスを制限する場合に役立ちます。Adobe AIR のデータベース暗号化機能は、いくつかの用途に使用できます。暗号化されたデータベースを使用する場合の例を、いくつか次に示します。

•

サーバーからダウンロードした非公開のアプリケーションデータの読み取り専用キャッシュ。

•

サーバーと同期している、非公開データのローカルアプリケーションストア（データはサーバーに送信され、サーバーから読み込まれます）。

•

アプリケーションによって作成および編集されたドキュメントのファイル形式として使用される、暗号化されたファイ
ル。ファイルは、特定のユーザー専用である場合と、アプリケーションのすべてのユーザーで共有するように設計されている場合があります。

•

ローカルデータストアのその他の用途。例えば、689 ページの「ローカル SQL データベースの用途」に記載されている
ように、マシンまたはデータベースファイルにアクセスできる他のユーザーに対してデータを公開しない場合があります。

暗号化されたデータベースの使用が必要となる理由がわかると、アプリケーションの設計方法を決定しやすくなります。このことは、特に、アプリケーションによるデータベースの暗号化キーの作成、取得および保存の方法に影響します。これらの考慮事項について詳しくは、734 ページの「データベースで暗号化を使用する場合の考慮事項」を参照してください。
暗号化されたデータベース以外に、機密データを保護する方法としては、暗号化されたローカルストアがあります。暗号化されたローカルストアの場合、String 型のキーを使用して単一の ByteArray 値を格納します。この値に対するアクセスは、値を格納する AIR アプリケーション自体によって、値が格納されているコンピューター上から実行される場合に限り可能です。暗号化されたローカルストアの場合、独自に暗号化キーを作成する必要はありません。このため、暗号化されたローカ
ルストアは、ByteArray に容易にエンコードできるストリング値または値セットを格納する場合に最も適しています。暗号化されたデータベースは、構造化されたデータの格納と照会が必要とされる、より大きなデータセットの場合に最も適しています。暗号化されたローカルストアの使用について詳しくは、685 ページの「暗号化されたローカルストア」を参照してください。

暗号化されたデータベースの作成
Adobe AIR 1.5 およびそれ以降暗号化されたデータベースを使用するには、データベースファイルを作成時に暗号化する必要があります。暗号化せずに作成したデータベースを、後で暗号化することはできません。同様に、暗号化されたデータベースを後で非暗号化することもできません。必要な場合は、暗号化されたデータベースの暗号化キーを変更できます。詳しくは、733 ページの「データベースの暗号化キーの変更」を参照してください。暗号化されていない既存のデータベースがあり、データベース暗号化を使用する必要がある場合は、暗号化されたデータベースを新たに作成し、既存のテーブル構造とデータを新しいデータベー
スにコピーします。
暗号化されたデータベースを作成する方法は、暗号化されていないデータベースを作成する方法（693 ページの「データベースの作成」を参照）とほぼ同じです。最初に、データベースへの接続を表す SQLConnection インスタンスを作成します。SQLConnection オブジェクトの open() メソッドまたは openAsync() メソッドを呼び出して、データベースを作成しま

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

731

AIR を使用したローカル SQL データベースの操作

す。このとき、ファイルがまだ存在しないデータベースの場所を指定します。暗号化されたデータベースを作成する場合、唯一の違いは、encryptionKey パラメーター（open() メソッドの第 5 パラメーターであり、openAsync() メソッドの第 6 パラ
メーター）の値を指定することです。
有効な encryptionKey パラメーターの値は、16 バイトを格納している ByteArray オブジェクトです。
次の例では、暗号化されたデータベースの作成方法を示します。わかりやすくするために、これらの例では、暗号化キーをアプリケーションコード内にハードコードしています。ただし、この方法は安全ではないため、使用しないでください。
var conn:SQLConnection = new SQLConnection();var encryptionKey:ByteArray = new ByteArray();
encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure!
// Create an encrypted database in asynchronous mode
conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);// Create an encrypted database in synchronous mode
conn.open(dbFile, SQLMode.CREATE, false, 1024, encryptionKey);

暗号化キーの生成の推奨される方法を示す例については、735 ページの「例：暗号化キーの生成と使用」を参照してください。

暗号化されたデータベースへの接続
Adobe AIR 1.5 およびそれ以降暗号化されたデータベースの作成方法と同様に、暗号化されたデータベースへの接続を開く手順は、暗号化されていない
データベースへの接続の場合と似ています。この手順については、700 ページの「データベースへの接続」を参照してくだ
さい。接続を同期実行モードで開く場合は open() メソッドを呼び出し、非同期実行モードで開く場合は openAsync() メソッ
ドを呼び出します。唯一の違いは、暗号化されたデータベースを開くには、encryptionKey パラメーター（open() メソッドの第 5 パラメーターであり、openAsync() メソッドの第 6 パラメーター）の適切な値を指定することです。
指定された暗号化キーが正しくない場合はエラーが発生します。open() メソッドの場合は、SQLError 例外がスローされます。openAsync() メソッドの場合は、SQLConnection オブジェクトによって SQLErrorEvent が送出されます。これには、

SQLError オブジェクトの error プロパティが格納されています。いずれの場合も、例外によって生成された SQLError オ
ブジェクトの errorID プロパティの値は 3138 になります。このエラー ID は、「File opened is not a database file」というエラーメッセージに対応します。
暗号化されたデータベースを非同期実行モードで開く方法を次の例に示します。わかりやすくするために、この例では、暗号化キーをアプリケーションコードでハードコードしています。ただし、この方法は安全ではないため、使用しないでくだ
さい。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

732

AIR を使用したローカル SQL データベースの操作

import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.events.SQLErrorEvent;import flash.events.SQLEvent;import flash.filesystem.File;var conn:SQLConnection = new SQLConnection();conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);var dbFile:File = File.applicationStorageDirectory.resolvePath("DBSample.db");
var encryptionKey:ByteArray = new ByteArray();
encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure!
conn.openAsync(dbFile, SQLMode.UPDATE, null, false, 1024, encryptionKey);function openHandler(event:SQLEvent):void{
trace("the database opened successfully");}function errorHandler(event:SQLErrorEvent):void{if (event.error.errorID == 3138){
trace("Incorrect encryption key");}
else{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);}}

暗号化されたデータベースを同期実行モードで開く方法を次の例に示します。わかりやすくするために、この例では、暗号化キーをアプリケーションコードでハードコードしています。ただし、この方法は安全ではないため、使用しないでくださ
い。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

733

AIR を使用したローカル SQL データベースの操作

import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.filesystem.File;var conn:SQLConnection = new SQLConnection();var dbFile:File = File.applicationStorageDirectory.resolvePath("DBSample.db");
var encryptionKey:ByteArray = new ByteArray();
encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure!
try{conn.open(dbFile, SQLMode.UPDATE, false, 1024, encryptionKey);
trace("the database was created successfully");}
catch (error:SQLError){
if (error.errorID == 3138){
trace("Incorrect encryption key");}
else{
trace("Error message:", error.message);
trace("Details:", error.details);}}

暗号化キーの生成の推奨される方法を示す例については、735 ページの「例：暗号化キーの生成と使用」を参照してください。

データベースの暗号化キーの変更
Adobe AIR 1.5 およびそれ以降
データベースが暗号化されている場合、データベースの暗号化キーを後で変更できます。データベースの暗号化キーを変更するには、まず、データベースへの接続を開きます。そのためには、SQLConnection インスタンスを作成し、open() メ
ソッドまたは openAsync() メソッドを呼び出します。データベースに接続したら、新しい暗号化キーを引数として渡して、

reencrypt() メソッドを呼び出します。
他の多くのデータベース操作と同様に、reencrypt() メソッドの動作は、データベースの接続に使用するモードが同期実行
モードか非同期実行モードかによって異なります。open() メソッドを使用してデータベースに接続した場合、reencrypt() 操
作は同期的に実行されます。操作が完了すると、コードの次の行から実行が再開されます。
var newKey:ByteArray = new ByteArray();// ... generate the new key and store it in newKey
conn.reencrypt(newKey);

これに対し、openAsync() メソッドを使用してデータベース接続を開いた場合、reencrypt() 操作は非同期で実行されます。

reencrypt() を呼び出すと、再暗号化プロセスが開始されます。操作が完了すると、SQLConnection オブジェクトによってreencrypt イベントが送出されます。再暗号化が完了したことを判別するには、イベントリスナーを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

734

AIR を使用したローカル SQL データベースの操作

var newKey:ByteArray = new ByteArray();// ... generate the new key and store it in newKey
conn.addEventListener(SQLEvent.REENCRYPT, reencryptHandler);conn.reencrypt(newKey);function reencryptHandler(event:SQLEvent):void{// save the fact that the key changed}

reencrypt() 操作は、独自のトランザクション内で実行されます。操作が中断または失敗する（例えば、操作が完了する前にアプリケーションが閉じられる）と、トランザクションがロールバックされます。その場合は、データベースの暗号化キー
は元の暗号化キーのままになります。
reencrypt() メソッドを使用して、データベースの暗号化を解除することはできません。null 値または 16 バイト以外の
ByteArray を reencrypt() メソッドに渡すと、エラーが発生します。

データベースで暗号化を使用する場合の考慮事項
Adobe AIR 1.5 およびそれ以降
730 ページの「暗号化されたデータベースの使用」では、暗号化されたデータベースの使用が適している例をいくつか示します。機密性の要件は、アプリケーションの使用例（ここに示す例および他の例を含む）によって異なります。アプリケー
ションでの暗号化の使用をどのように設計するかが、データベースのデータの機密性を制御する上で重要な役割を担います。
例えば、暗号化されたデータベースを使用して、同じマシンを使用している他のユーザーに対しても個人情報を公開しないようにするには、各ユーザーのデータベースで独自の暗号化キーが必要になります。セキュリティを最大限に高めるために、ユーザーが入力したパスワードに基づいてキーを生成することができます。パスワードに基づいて暗号化キーを生成すると、他のユーザーがマシンのユーザーのアカウントを偽装できたとしても、データにアクセスすることはできません。機密性について別の観点から考えてみましょう。特定のアプリケーションのすべてのユーザーがデータベースファイルを読み取ることができるようにする必要があるとします。ただし、他のアプリケーションのユーザーは、このデータベースファイルを読み取ることができないようにします。この場合、そのアプリケーションがインストールされている各環境から、共有の暗号化キーにアクセスできる必要があります。
アプリケーションデータに求められる機密性のレベルに応じて、アプリケーション（具体的には、暗号化キーの生成に使用する手法）を設計できます。様々なデータ機密性レベルにおけるデザイン上の推奨事項を次の一覧に示します。

•

任意のマシンにインストールされている特定のアプリケーションにアクセスできるすべてのユーザーがデータベースにア
クセスできるようにするには、アプリケーションのすべてのインスタンスで利用できる単一のキーを使用します。例えば、アプリケーションの初回実行時に、SSL などのセキュリティ保護されたプロトコルを使用して、サーバーから共有の暗号化キーをダウンロードできます。このキーを、暗号化されたローカルストアに保存して、次回以降も使用できるようにします。別の方法としては、マシンのユーザーごとにデータを暗号化し、サーバーなどのリモートデータストアとデータを同期させることで、データをポータブルにします。

•

単一のユーザーがどのマシンからでもデータベースにアクセスできるようにするには、ユーザーの秘密（パスワードなど）から暗号化キーを生成します。特に、特定のコンピューターに関連付けられた値（例えば、暗号化されたローカルス
トアに保存されている値）は、キーの生成に使用しないでください。別の方法としては、マシンのユーザーごとにデータを暗号化し、サーバーなどのリモートデータストアとデータを同期させることで、データをポータブルにします。

•

単一のマシンの単一のユーザーのみがデータベースにアクセスできるようにするには、パスワードおよび生成されたソルトからキーを生成します。この方法の例については、735 ページの「例：暗号化キーの生成と使用」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

735

AIR を使用したローカル SQL データベースの操作

暗号化されたデータベースを使用するアプリケーションを設計する場合に注意する必要がある、セキュリティ上の追加考慮
事項を次に示します。

•

システムの安全性は、その最も弱い部分で決まります。ユーザーが入力したパスワードを使用して暗号化キーを生成する
場合は、パスワードの最小の長さと複雑さについての制約を設けることを検討してください。基本文字のみで構成される
短いパスワードは、簡単に推測できます。

• AIR アプリケーションのソースコードは、プレーンテキスト（HTML コンテンツの場合）または簡単に逆コンパイルできるバイナリ形式（SWF コンテンツの場合）でユーザーのマシンに保存されます。ソースコードはアクセス可能なので、次の 2 つの点に注意する必要があります。
•

暗号化キーをソースコード内にハードコードしないこと•

暗号化キーの生成に使用する技法（ランダム文字生成ツールや特定のハッシュアルゴリズムなど）は、攻撃者によって簡単に解読されることを前提とすること• AIR のデータベース暗号化では、AES（Advanced Encryption Standard）を CCM（Counter with CBC-MAC）
モードで使用します。この暗号化では、暗号の安全性を高めるために、ユーザーが入力したキーをソルト値と組み合わせることが必要になります。この方法の例については、735 ページの「例：暗号化キーの生成と使用」を参照してください。

•

データベースを暗号化することにした場合、そのデータベースに関連してデータベースエンジンが使用するすべてのディ
スクファイルが暗号化されます。ただし、データベースエンジンでは、トランザクションにおける読み取りと書き込みのパフォーマンスを改善するために、一部のデータを一時的にインメモリキャッシュに保持します。メモリに常駐するデー
タは暗号化されません。攻撃者がデバッガーなどを使用して、AIR アプリケーションによって使用されているメモリにアクセスできてしまうと、現在開いている、暗号化されていないデータベースのデータが入手可能になります。

例：暗号化キーの生成と使用
Adobe AIR 1.5 およびそれ以降
このアプリケーション例では、暗号化キーを生成する方法を 1 つ示します。このアプリケーションは、ユーザーのデータについて、最も高いレベルの機密性と安全性を提供するように設計されています。非公開データのセキュリティ保護に関する重要な側面の 1 つは、アプリケーションがデータベースに接続する際、ユーザーにパスワードの入力を毎回要求することです。したがって、この例が示すように、このレベルの機密性を要求するアプリケーションがデータベースの暗号化キーを直接保存しておくことは絶対に避けるべきです。
このアプリケーションは、暗号化キーを生成する ActionScript クラス（EncryptionKeyGenerator クラス）、および、そのクラスの使用方法を示す基本的なユーザーインターフェイスという 2 つの部分から構成されます。ソースコード全体については、737 ページの「暗号化キーの生成と使用のコード例全体」を参照してください。

EncryptionKeyGenerator クラスによる安全な暗号化キーの取得
Adobe AIR 1.5 およびそれ以降
アプリケーションで EncryptionKeyGenerator クラスを使用する際にその動作の詳細を理解する必要はありません。デー
タベースの暗号化キーがクラスによって生成される方法について詳しくは、741 ページの「EncryptionKeyGenerator クラスについて」を参照してください。
アプリケーションで EncryptionKeyGenerator クラスを使用するには、次の手順に従ってください。

1 EncryptionKeyGenerator クラスをソースコードまたはコンパイル済み SWC としてダウンロードします。

EncryptionKeyGenerator クラスは、オープンソースの ActionScript 3.0 コアライブラリ（as3corelib）プロジェクトに含まれるクラスです。as3corelib パッケージ（ソースコードおよびドキュメントを含む）をダウンロードできます。
また、プロジェクトページから SWC またはソースコードのファイルをダウンロードすることもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

736

AIR を使用したローカル SQL データベースの操作

2 EncryptionKeyGenerator クラス（または as3corelib SWC）のソースコードを、アプリケーションソースコードが見つけられる場所に置きます。

3 アプリケーションソースコードで、EncryptionKeyGenerator クラスの import ステートメントを追加します。
import com.adobe.air.crypto.EncryptionKeyGenerator;

4 コード内の、データベースを作成またはデータベースへの接続を開くポイントの前に、EncryptionKeyGenerator() コンス
トラクターを呼び出して EncryptionKeyGenerator インスタンスを作成するコードを追加します。
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();5 ユーザーからパスワードを取得します。
var password:String = passwordInput.text;
if (!keyGenerator.validateStrongPassword(password)){// display an error message
return;}EncryptionKeyGenerator インスタンスは、暗号化キーのベースとしてこのパスワードを使用します（次の手順で示します）。EncryptionKeyGenerator インスタンスは、強力なパスワードの検証要件に照らし合わせてパスワードをテストします。検証に失敗すると、エラーが発生します。このサンプルコードのように、EncryptionKeyGenerator オブジェ
クトの validateStrongPassword() メソッドを呼び出すことで、パスワードを事前にチェックすることができます。このよ
うに、パスワードが強力なパスワードの最小限の要件を満たすかどうかをチェックして、エラーを防ぐことができます。

6 次のように、パスワードから暗号化キーを生成します。
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);

getEncryptionKey() メソッドは、暗号化キー（16 バイト ByteArray）を生成して返します。暗号化キーを使用して、暗号化された新しいデータベースを作成するか、既存のデータベースを開くことができます。
getEncryptionKey() メソッドは必要なパラメーターを 1 つ持ちます。これは手順 5 で取得されたパスワードです。
注意：アプリケーションでは、最も高いレベルのデータのセキュリティとプライバシーを維持するために、アプリケー
ションがデータベースに接続するたびにユーザーのパスワード入力を要求する必要があります。ユーザーのパスワードまたはデータベース暗号化キーを直接格納しないでください。セキュリティのリスクが高くなります。代わりに、この例に示すように、暗号化データベースの作成時とその接続時に、同じ方法を使用してパスワードから暗号化キーを抽出するようにします。

getEncryptionKey() メソッドは、2 番目（オプション）のパラメーターである overrideSaltELSKey パラメーターも受け入れます。EncryptionKeyGenerator は、salt と呼ばれるランダムな値を作成します。これは、暗号化キーの一部として使用されます。暗号化キーを再作成できるようにするために、salt の値は AIR アプリケーションの暗号化されたローカ
ルストア（ELS）に格納されます。デフォルトでは、EncryptionKeyGenerator クラスは特定の String を ELS キーとして使用します。まれに、アプリケーションが使用している他のキーと、このキーが競合する可能性があります。デフォル
トのキーを使用する代わりに、独自の ELS キーを指定することもできます。その場合は、次のように、2 番目のgetEncryptionKey() パラメーターとしてカスタムキーを渡すことで、カスタムキーを指定します。
var customKey:String = "My custom ELS salt key";var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password, customKey);

7 データベースの作成とオープン
getEncryptionKey() メソッドから返される暗号化キーにより、コードは新しい暗号化されたデータベースを作成するか、既存の暗号化されたデータベースを開こうとします。いずれの場合も、SQLConnection クラスの open() メソッドまたは openAsync() メソッドを使用します。詳しくは、730 ページの「暗号化されたデータベースの作成」および 731 ページの「暗号化されたデータベースへの接続」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

737

AIR を使用したローカル SQL データベースの操作

この例では、アプリケーションは非同期実行モードでデータベースを開くように設計されています。該当するイベントリ
スナーを設定し、最後の引数として暗号化キーを渡して、openAsync() メソッドを呼び出します。
conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, openError);conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);

リスナーのメソッドでは、イベントリスナーの登録を解除します。次に、データベースが作成または開かれたか、エラーが発生したかを示すステータスメッセージが表示されます。これらのイベントハンドラーの最も注目すべき点は、

openError() メソッドです。このメソッドでは、if ステートメントが、データベースが存在するかどうか（コードが既存のデータベースに接続しようとしているかどうか）、および、エラー ID が定数
EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID に合致するかどうかをチェックします。この両方の条件が成立する場合、おそらく、ユーザーが入力したパスワードが正しくないことを意味します（指定されたファイルがデータベースファイルではないことを意味する可能性もあります）。次のコードは、エラー ID をチェックするコードです。
if (!createNewDB && event.error.errorID == EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID){
statusMsg.text = "Incorrect password!";}else{
statusMsg.text = "Error creating or opening database.";}

この例のイベントリスナーのコード全体については、737 ページの「暗号化キーの生成と使用のコード例全体」を参照してください。

暗号化キーの生成と使用のコード例全体
Adobe AIR 1.5 およびそれ以降
アプリケーション例「暗号化キーの生成と使用」のコード全体を次に示します。このコードは 2 つの部分から構成されます。
この例では、EncryptionKeyGenerator を使用してパスワードから暗号化キーを作成しています。

EncryptionKeyGenerator クラスは、オープンソースの ActionScript 3.0 コアライブラリ（as3corelib）プロジェクトに含まれるクラスです。as3corelib パッケージ（ソースコードおよびドキュメントを含む）をダウンロードできます。また、プロジェクトページから SWC またはソースコードのファイルをダウンロードすることもできます。
Flex の例
アプリケーションの MXML ファイルには、暗号化されたデータベースに対する接続を作成する（開く）単純なアプリケー
ションのソースコードが含まれています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

738

AIR を使用したローカル SQL データベースの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
creationComplete="init();"><mx:Script><![CDATA[
import com.adobe.air.crypto.EncryptionKeyGenerator;
private const dbFileName:String = "encryptedDatabase.db";
private var dbFile:File;private var createNewDB:Boolean = true;
private var conn:SQLConnection;// ------- Event handling ------private function init():void{conn = new SQLConnection();dbFile = File.applicationStorageDirectory.resolvePath(dbFileName);if (dbFile.exists){
createNewDB = false;
instructions.text = "Enter your database password to open the encrypted database.";
openButton.label = "Open Database";}}
private function openConnection():void{
var password:String = passwordInput.text;
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();if (password == null || password.length <= 0){statusMsg.text = "Please specify a password.";return;}if (!keyGenerator.validateStrongPassword(password)){
statusMsg.text = "The password must be 8-32 characters long. It must contain at least
one lowercase letter, at least one uppercase letter, and at least one number or symbol.";return;}passwordInput.text = "";passwordInput.enabled = false;
openButton.enabled = false;
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, openError);conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);}
private function openHandler(event:SQLEvent):void{conn.removeEventListener(SQLEvent.OPEN, openHandler);conn.removeEventListener(SQLErrorEvent.ERROR, openError);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

739

AIR を使用したローカル SQL データベースの操作

statusMsg.setStyle("color", 0x009900);
if (createNewDB){
statusMsg.text = "The encrypted database was created successfully.";}else{
statusMsg.text = "The encrypted database was opened successfully.";}}
private function openError(event:SQLErrorEvent):void{conn.removeEventListener(SQLEvent.OPEN, openHandler);conn.removeEventListener(SQLErrorEvent.ERROR, openError);if (!createNewDB && event.error.errorID ==EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID){
statusMsg.text = "Incorrect password!";}else{
statusMsg.text = "Error creating or opening database.";}}]]></mx:Script><mx:Text id="instructions" text="Enter a password to create an encrypted database. The next time you
open the application, you will need to re-enter the password to open the database again." width="75%"height="65"/><mx:HBox><mx:TextInput id="passwordInput" displayAsPassword="true"/><mx:Button id="openButton" label="Create Database" click="openConnection();"/></mx:HBox><mx:Text id="statusMsg" color="#990000" width="75%"/></mx:WindowedApplication>

Flash Professional の例
アプリケーションの FLA ファイルには、暗号化されたデータベースに対する接続を作成する（開く）単純なアプリケー
ションのソースコードが含まれています。FLA ファイルのステージ上には、次に示す 4 個のコンポーネントが配置されています。
インスタンス名コンポーネントの種類

説明

instructions

Label

ユーザーに対する手順説明

passwordInput

TextInput

ユーザーがパスワードを入力するための入力フィールド

openButton

Buttonユーザーがパスワードを入力した後にクリックするボタン

statusMsg

Labelステータス（成功、失敗）メッセージの表示

アプリケーションのコードは、メインタイムラインのフレーム 1 にあるキーフレーム上に定義されています。アプリケー
ションのコードを次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

740

AIR を使用したローカル SQL データベースの操作

import com.adobe.air.crypto.EncryptionKeyGenerator;
const dbFileName:String = "encryptedDatabase.db";
var dbFile:File;var createNewDB:Boolean = true;
var conn:SQLConnection;
init();// ------- Event handling ------function init():void{
passwordInput.displayAsPassword = true;
openButton.addEventListener(MouseEvent.CLICK, openConnection);statusMsg.setStyle("textFormat", new TextFormat(null, null, 0x990000));
conn = new SQLConnection();dbFile = File.applicationStorageDirectory.resolvePath(dbFileName);if (dbFile.exists){
createNewDB = false;
instructions.text = "Enter your database password to open the encrypted database.";
openButton.label = "Open Database";}
else{
instructions.text = "Enter a password to create an encrypted database. The next time you open theapplication, you will need to re-enter the password to open the database again.";
openButton.label = "Create Database";}}function openConnection(event:MouseEvent):void{
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();var password:String = passwordInput.text;
if (password == null || password.length <= 0){statusMsg.text = "Please specify a password.";return;}if (!keyGenerator.validateStrongPassword(password)){
statusMsg.text = "The password must be 8-32 characters long. It must contain at least one lowercase
letter, at least one uppercase letter, and at least one number or symbol.";return;}passwordInput.text = "";passwordInput.enabled = false;
openButton.enabled = false;
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);conn.addEventListener(SQLEvent.OPEN, openHandler);conn.addEventListener(SQLErrorEvent.ERROR, openError);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

741

AIR を使用したローカル SQL データベースの操作

conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);}function openHandler(event:SQLEvent):void{conn.removeEventListener(SQLEvent.OPEN, openHandler);conn.removeEventListener(SQLErrorEvent.ERROR, openError);statusMsg.setStyle("textFormat", new TextFormat(null, null, 0x009900));
if (createNewDB){
statusMsg.text = "The encrypted database was created successfully.";}else{
statusMsg.text = "The encrypted database was opened successfully.";}}function openError(event:SQLErrorEvent):void{conn.removeEventListener(SQLEvent.OPEN, openHandler);conn.removeEventListener(SQLErrorEvent.ERROR, openError);if (!createNewDB && event.error.errorID == EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID){
statusMsg.text = "Incorrect password!";}else{
statusMsg.text = "Error creating or opening database.";}}EncryptionKeyGenerator クラスについて
Adobe AIR 1.5 およびそれ以降
EncryptionKeyGenerator クラスを使用してアプリケーションデータベースの安全な暗号化キーを作成するに当たり、このクラスの機能を理解することは必須ではありません。このクラスの使用方法については、735 ページの「EncryptionKeyGenerator クラスによる安全な暗号化キーの取得」で説明されています。ただし、このクラスが使用している技術を理解しておくと便利です。例えば、さまざまなレベルのデータプライバシーが要求される状況で、このクラスを適応させたり、その技術の一部を組み込むことができます。

EncryptionKeyGenerator クラスは、オープンソースの ActionScript 3.0 コアライブラリ（as3corelib）プロジェクトに含まれるクラスです。as3corelib パッケージ（ソースコードおよびドキュメントを含む）をダウンロードからダウンロードできます。また、プロジェクトサイトでソースコードを表示したり、説明に従ってダウンロードできます。
コードで EncryptionKeyGenerator インスタンスを作成し、その getEncryptionKey() メソッドを呼び出す場合、正当なユーザーのみがデータにアクセスできるようにするための手順がいくつか講じられています。この手順は、データベース作成前にユーザー入力パスワードから暗号化キーを生成したり、データベースを開くために暗号化キーを再作成する手順と同じです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

742

AIR を使用したローカル SQL データベースの操作

強力なパスワードの取得と検証

Adobe AIR 1.5 およびそれ以降
コードで getEncryptionKey() メソッドを呼び出す際には、パラメーターとしてパスワードを渡します。パスワードは、暗号化キーの土台として使用されます。ユーザーだけが知っている情報を使用することで、パスワードを知っているユーザーだ
けがデータベースのデータにアクセスできるように設計します。攻撃者がコンピューター上のユーザーのアカウントにアクセスできたとしても、パスワードを知らない限りはデータベースにアクセスできません。セキュリティを最大限に高めるために、アプリケーションではパスワードを保存しません。
アプリケーションのコードは、EncryptionKeyGenerator インスタンスを生成し、getEncryptionKey() メソッドを呼び出して、ユーザーによって入力されたパスワードを引数（この例の変数 password）として渡します。
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);

EncryptionKeyGenerator クラスでは、getEncryptionKey() メソッドが呼び出されると、まずユーザーの入力したパスワー
ドがパスワード強度の要件を満たしているかチェックします。EncryptionKeyGenerator クラスでは、パスワードの長さを
8 〜 32 文字に設定する必要があります。パスワードは大文字と小文字を組み合わせたもので、数字または記号が少なくとも
1 文字含まれている必要があります。
このパターンをチェックするための正規表現が、STRONG_PASSWORD_PATTERN という名前の定数として定義されています。
private static const STRONG_PASSWORD_PATTERN:RegExp = /(?=^.{8,32}$)((?=.*\d)|(?=.*\W+))(?![.\n])(?=.*[AZ])(?=.*[a-z]).*$/;

パスワードのチェックを実行するコードは、EncryptionKeyGenerator クラスの validateStrongPassword() メソッド内にあります。コードは次のとおりです。
public function vaidateStrongPassword(password:String):Boolean{
if (password == null || password.length <= 0){
return false;}
return STRONG_PASSWORD_PATTERN.test(password))}

内部的に、getEncryptionKey() メソッドは、EncryptionKeyGenerator クラスの validateStrongPassword() メソッドを呼び出し、パスワードが有効でない場合には例外をスローします。validateStrongPassword() メソッドはパブリックメソッドなので、

getEncryptionKey() メソッドを呼び出さずにパスワードをチェックし、エラーの発生を回避できます。
パスワードを 256 ビットに拡張
Adobe AIR 1.5 およびそれ以降プロセスの後半で、パスワードを 256 ビット長にする必要があります。次のコードでは、各ユーザーが 256 ビット（32 文字）長のパスワードを入力するよう要求する代わりに、パスワード文字を繰り返すことによって、長いパスワードを作成します。
長いパスワードを作成する処理は、getEncryptionKey() メソッドから concatenatePassword() メソッドを呼び出すことで実行しています。
var concatenatedPassword:String = concatenatePassword(password);

concatenatePassword() メソッドのコードを次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

743

AIR を使用したローカル SQL データベースの操作

private function concatenatePassword(pwd:String):String{
var len:int = pwd.length;
var targetLength:int = 32;
if (len == targetLength){
return pwd;}
var repetitions:int = Math.floor(targetLength / len);var excess:int = targetLength % len;var result:String = "";for (var i:uint = 0; i < repetitions; i++){result += pwd;}
result += pwd.substr(0, excess);
return result;}

パスワードの長さが 256 ビット未満である場合、パスワード自体を連結して 256 ビットにしています。ちょうどの長さにならない場合は、最後の繰り返しを短くして、ちょうど 256 ビットにします。

256 ビットのソルト値の生成と取得
Adobe AIR 1.5 およびそれ以降
次の手順では、256 ビットのソルト値を取得します。このソルト値は後の手順でパスワードに結合されます。ソルトは、ランダム値であり、ユーザーが入力した値に追加または結合されてパスワードを形成します。ソルトをパスワードと共に使用することにより、実際に存在する単語や一般的な言葉をユーザーがパスワードとして選択した場合でも、システムで使用されるパスワードとソルトの組み合わせはランダム値になります。このランダムな性質は、辞書攻撃（攻撃者が単語のリストを使用してパスワードを推測しようとする）からシステムを守るために役立ちます。また、ソルト値を生成し、暗号化されたローカルストアに保存することにより、データベースファイルが置かれているマシンのユーザーアカウントに関連付けられます。
アプリケーションが getEncryptionKey() メソッドを初めて呼び出す際には、このコードによってランダムな 256 ビットのソルト値が生成されます。それ以外の場合は、暗号化されたローカルストアからソルト値が読み込まれます。
ソルトは、salt という名前の変数に格納されます。このコードでは、暗号化されたローカルストアからソルト値を読み込もうとすることで、既に作成済みのソルトがあるかどうかを判断しています。
var salt:ByteArray = EncryptedLocalStore.getItem(saltKey);if (salt == null){salt = makeSalt();
EncryptedLocalStore.setItem(saltKey, salt);}

新しいソルト値を作成する場合は、makeSalt() メソッドで 256 ビットのランダムな値を生成します。この値は、最終的に、暗号化されたローカルストアに格納されるため、ByteArray オブジェクトとして生成されます。makeSalt() メソッドは、
Math.random() メソッドを使用して、ランダムに値を生成します。Math.random() メソッドでは、256 ビットの値を一度に生成することはできません。代わりに、ループを使用して、Math.random() を 8 回呼び出しています。それぞれの呼び出し

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

744

AIR を使用したローカル SQL データベースの操作

では、0 〜 4294967295（uint 値の最大値）のランダムな uint 値が生成されます。uint はちょうど 32 ビットであるため、
ここでは便宜上 uint 値を使用しています。8 個の uint 値を ByteArray に書き込むことにより、256 ビットの値が生成されます。makeSalt() メソッドのコードを次に示します。
private function makeSalt():ByteArray{var result:ByteArray = new ByteArray;for (var i:uint = 0; i < 8; i++){result.writeUnsignedInt(Math.round(Math.random() * uint.MAX_VALUE));}
return result;}

暗号化されたローカルストア（ELS）にソルトを保存する際と、ELS からソルトを抽出する際には、そのソルトの保存に使用する String キーが必要です。このキーがわからないと、ソルトの抽出はできず、したがって、暗号化キーを再現してデータベースを開き直すこともできません。EncryptionKeyGenerator のデフォルトでは、あらかじめ定数 SALT_ELS_KEY として定義されている ELS キーを使用します。デフォルト以外のキーを使用する場合は、アプリケーションのコードがgetEncryptionKey() メソッドを呼び出す際に、使用する ELS キーを指定できます。デフォルトまたはアプリケーションによって指定されたソルト ELS キーは、saltKey という変数に格納されます。この変数は、前に示したように、
EncryptedLocalStore.setItem() と EncryptedLocalStore.getItem() の呼び出しで使用されます。

XOR 演算子による 256 ビットのパスワードとソルトの結合
Adobe AIR 1.5 およびそれ以降
256 ビットのパスワードと 256 ビットのソルト値が用意できました。次は、ソルト値と連結パスワードとをビット XOR 演
算で組み合わせ、1 つの値にします。これによって、文字データとして表現可能なあらゆる文字を含む可能性がある 256
ビットのパスワードを作成できます。ユーザーの入力するパスワードは主に英数字で構成されている場合がほとんどですが、そうであっても、ここで生成されるパスワードの性質は変わりません。ユーザーに長く複雑なパスワードの入力を要求しな
くても、こうしてランダムな性質を付加すれば、パスワードの組み合わせの数を増やすことができます。

XOR 演算の結果は、変数 unhashedKey に格納されます。2 つの値に対してビット単位の XOR を実行する実際の処理は、
xorBytes() メソッドで行われます。
var unhashedKey:ByteArray = xorBytes(concatenatedPassword, salt);

ビット単位の XOR 演算子（^）は、2 つの uint 値を受け取って、1 つの uint 値を返します（1 つの uint 値は 32 個のビッ
トを含みます）。引数として xorBytes() メソッドに渡される入力値は、String（パスワード）と ByteArray（ソルト）です。
したがって、ループを使用して入力値から一度に 32 ビットずつ抽出し、XOR 演算子を使用して結合します。
private function xorBytes(passwordString:String, salt:ByteArray):ByteArray{var result:ByteArray = new ByteArray();for (var i:uint = 0; i < 32; i += 4){// ...
}
return result;}

このループ内では、passwordString パラメーターから先頭の 32 ビット（4 バイト）を抽出します。抽出したビット列を、2段階のプロセスを経て 1 つの uint 値（o1）に変換します。最初に、charCodeAt() メソッドによって各文字の数値が取得されます。次に、ビット単位の左シフト演算子（<<）を使用して値を uint 内の適切な位置にシフトし、その値を o1 に加算しま

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

745

AIR を使用したローカル SQL データベースの操作

す。例えば、最初の文字（i）は、ビット単位の左シフト演算子（<<）を使用して 24 ビット分だけ左にシフトされ、その値を o1 に代入することにより、最初の 8 ビットになります。2 番目の文字（(i + 1）は、値を 16 ビット分だけ左にシフトし、その結果を o1 に代入することにより、2 番目の 8 ビットになります。同様に、3 番目と 4 番目の文字の値が追加されます。
// ...
// Extract 4 bytes from the password string and convert to a uint
var o1:uint = passwordString.charCodeAt(i) << 24;
o1 += passwordString.charCodeAt(i + 1) << 16;
o1 += passwordString.charCodeAt(i + 2) << 8;
o1 += passwordString.charCodeAt(i + 3);// ...

以上で、変数 o1 に passwordString パラメーターから抽出した 32 ビットが格納されました。次に、salt パラメーターから 32
ビットが抽出されます。これは、readUnsignedInt() メソッドを呼び出すことにより行います。この 32 ビット列を、uint の変数 o2 に格納します。
// ...
salt.position = i;var o2:uint = salt.readUnsignedInt();// ...

最後に、XOR 演算子を使用して 2 つの 32 ビット（uint）値を結合し、結果を result という名前の ByteArray に書き込みます。
// ...
var xor:uint = o1 ^ o2;
result.writeUnsignedInt(xor);// ...

ループが終了したら、XOR の結果を格納している ByteArray が返されます。
// ...
}
return result;}

キーのハッシング

Adobe AIR 1.5 およびそれ以降連結したパスワードとソルト値とを組み合わせた後は、さらにセキュリティを強化するために、SHA-256 ハッシュアルゴ
リズムを使用してこの値をハッシュします。値をハッシュすることにより、攻撃者がリバースエンジニアリングを行うのが困難になります。
この時点で、連結したパスワードとソルトを組み合わせた結果の値が unhashedKey という ByteArray に格納されています。

ActionScript 3.0 コアライブラリ（as3corelib）プロジェクトに、com.adobe.crypto パッケージに属する SHA256 というクラスがあり、このクラスの SHA256.hashBytes() メソッドは、ByteArray に対して SHA-256 ハッシュを実行し、256 ビッ
トのハッシュ結果を 16 進数形式で格納した String を返します。EncryptionKeyGenerator クラスでは、この SHA256 ク
ラスを使用してキーをハッシュします。
var hashedKey:String = SHA256.hashBytes(unhashedKey);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

746

AIR を使用したローカル SQL データベースの操作

ハッシュからの暗号化キーの抽出

Adobe AIR 1.5 およびそれ以降
暗号化キーは、16 バイト（128 ビット）ちょうどの長さの ByteArray でなければなりません。SHA-256 ハッシュアルゴリ
ズムの結果は常に 256 ビット長になります。したがって、最後の手順では、実際の暗号化キーとして使用される 128 ビット
分をハッシュ結果から選択します。

EncryptionKeyGenerator クラスのコードで、キーを 128 ビットに短縮するために generateEncryptionKey() メソッドを呼び出します。さらに、このメソッドの結果を getEncryptionKey() メソッドの結果として返します。
var encryptionKey:ByteArray = generateEncryptionKey(hashedKey);
return encryptionKey;

最初の 128 ビットは、暗号化キーとして使用する必要がありません。その他任意の場所から始まるビット範囲や、1 つおきに抽出したビット列、または何か別の方法で選択したビットを使用することもできます。重要なのは、128 個の別個のビットを選択すること、および毎回同じ 128 個のビットを使用することです。
この例の generateEncryptionKey() メソッドでは、18 番目のバイトから始まる範囲を暗号化キーとして使用しています。前述のように、SHA256 クラスは、256 ビットのハッシュを 16 進数値として格納した String を返します。128 ビットの塊はバ
イト数が多すぎるため、一度に ByteArray に追加することができません。このため、コードでは、for ループを使用して 16
進数の String から文字を抽出し、実際の数値に変換してから、ByteArray に追加します。SHA-256 の結果として得られるString の長さは 64 文字です。128 ビットの範囲がこの String の 32 文字に相当し、各文字は 4 ビットを表します。
ByteArray に追加できる最小のデータインクリメント単位は 1 バイト（8 ビット）です。これは、hash String の 2 文字に相当します。このため、loop では、2 文字分のインクリメントで 0 〜 31（32 文字）がカウントされます。
ループ内では、最初に現在の文字ペアの開始位置を特定します。目的の範囲はインデックス位置 17（18 番目のバイト）で開始されるため、position 変数には、現在のイテレータ値（i）に 17 を足した値が代入されます。コードでは、String オブ
ジェクトの substr() メソッドを使用して、現在の位置にある 2 文字を抽出します。この文字は変数 hex に格納されます。次に、parseInt() メソッドを使用して、hex String を 10 進数の整数値に変換します。変換された値は、int 型の変数 byte に格納されます。最後に、byte の値を、result ByteArray に writeByte() メソッドで追加します。ループが終了した時点で、result
ByteArray には、データベースの暗号化キーとして使用できる 16 個のバイトが格納されています。
private function generateEncryptionKey(hash:String):ByteArray{var result:ByteArray = new ByteArray();for (var i:uint = 0; i < 32; i += 2){
var position:uint = i + 17;
var hex:String = hash.substr(position, 2);
var byte:int = parseInt(hex, 16);
result.writeByte(byte);}
return result;}

SQL データベースの操作のための戦略
Adobe AIR 1.0 およびそれ以降
アプリケーションでローカル SQL データベースにアクセスして操作するには様々な方法があります。アプリケーション
コードの構成や、操作を実行する順序やタイミングなどは、アプリケーションの設計によって様々です。選択する方法によって、アプリケーションの開発の容易さや、将来の更新でアプリケーションに変更を加えるときの容易さ、ユーザーから見たアプリケーションのパフォーマンスなどが違ってきます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

747

AIR を使用したローカル SQL データベースの操作

設定済みデータベースの配布
Adobe AIR 1.0 およびそれ以降
アプリケーションで AIR ローカル SQL データベースを使用する際には、テーブルや列などの特定の構造がデータベースに含まれている必要があります。さらに、アプリケーションによっては、データベースファイルに特定のデータがあらかじめ設定されている必要がある場合もあります。データベースに適切な構造が含まれるようにするには、まず、アプリケーショ
ンコードでデータベースを作成するという方法があります。データベースファイルが特定の場所にあるかどうかをアプリ
ケーションの読み込み時にチェックして、ファイルが存在しない場合には一連のコマンドを実行してデータベースファイルを作成し、データベース構造を作成し、テーブルに初期データを設定します。
データベースとそのテーブルを作成するコードは複雑になることが多く、たいていはアプリケーションがインストールされている期間に 1 回しか使用されないにもかかわらず、アプリケーションのサイズと複雑さを増加させる要因になります。
データベース、構造およびデータをプログラムで作成する代わりに、設定済みのデータベースをアプリケーションと一緒に配布することもできます。そのためには、データベースファイルをアプリケーションの AIR パッケージに含めます。
同梱されたデータベースファイルは、AIR パッケージに含まれているすべてのファイルと同様に、アプリケーションディレ
クトリ（File.applicationDirectory プロパティによって表されるディレクトリ）にインストールされます。ただし、このディレクトリのファイルは読み取り専用であるため、AIR パッケージのファイルを「テンプレート」データベースとして使用して、ユーザーが初めてアプリケーションを実行したときに元のデータベースファイルをユーザーの 647 ページの「アプリケーション記憶領域ディレクトリの参照」（または別の場所）にコピーし、そのデータベースをアプリケーション内で使用します。

ローカル SQL データベースの操作のベストプラクティス
Adobe AIR 1.0 およびそれ以降
ローカル SQL データベースを使用する際には、アプリケーションのパフォーマンス、セキュリティおよびメンテナンス性を向上させるために以下のテクニックを使用することをお勧めします。

データベース接続を事前に作成する
Adobe AIR 1.0 およびそれ以降
アプリケーションの最初の読み込み時に実行するステートメントがなくても、ステートメントの実行時に遅れが生じないよ
うに、事前に（アプリケーションの起動後など）SQLConnection オブジェクトをインスタンス化してその open() メソッド
または openAsync() メソッドを呼び出します。700 ページの「データベースへの接続」を参照してください。

データベース接続を再利用する
Adobe AIR 1.0 およびそれ以降
アプリケーションの実行期間全体にわたってアクセスするデータベースがある場合は、接続を閉じたり開いたりする代わりに、SQLConnection インスタンスへの参照を保持してアプリケーション全体で再利用します。700 ページの「データベースへの接続」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

748

AIR を使用したローカル SQL データベースの操作

非同期実行モードを優先的に使用する
Adobe AIR 1.0 およびそれ以降
データアクセスコードを記述する際には、同期操作を使用した方がコードが短く単純になることが多いため、操作を非同期
ではなく同期的に実行したくなるかもしれませんが、725 ページの「同期および非同期のデータベース操作の使用」で説明したように、同期操作はユーザーの体感的なパフォーマンスに影響を与え、アプリケーションのユーザーエクスペリエンスを低下させる可能性があります。1 つの操作にかかる時間は操作（特に、操作に含まれるデータの量）によって変わります。
例えば、データベースにデータを 1 行だけ追加する SQL INSERT ステートメントにかかる時間は、数千行のデータを取得す
る SELECT ステートメントより短くなります。しかし、同期実行を使用して複数の操作を実行すると、通常はそれらの操作が一続きで実行されます。1 つ 1 つの操作にかかる時間は非常に短くても、すべての同期操作が完了するまでアプリケー
ションが応答しなくなります。その結果、一続きで実行される複数の操作の時間が累積されて、アプリケーションの動作が停止する場合もあります。
非同期操作を標準のアプローチとして使用します。多数の行を含む操作では特にそうするようにしてください。SELECT ス
テートメントの結果が大きい場合にその処理を分割する方法もありますが（715 ページの「SELECT の結果の分割」を参照）、非同期実行モードでしか使用できません。同期操作を使用するのは、非同期プログラミングでは実現できない機能がある場合のみにしてください。その場合も、アプリケーションのユーザーへのパフォーマンスの影響を考慮し、アプリケー
ションをテストしてアプリケーションのパフォーマンスへの影響を確認する必要があります。非同期実行を使用するとコードが複雑になる場合もありますが、コードを記述するのは 1 回だけで済むのに対し、アプリケーションのユーザーはそれを（速くても遅くても）繰り返し使用しなければならないことを忘れないでください。
多くの場合は、実行する SQL ステートメントごとに個別の SQLStatement インスタンスを使用することで、複数の SQL 操
作を一度にキューに登録できます。これにより、非同期コードを同期コードのように記述することができます。詳しくは、

728 ページの「非同期実行モデルについて」を参照してください。

SQLStatement の text プロパティを変更せずに別の SQL ステートメントを使用する
Adobe AIR 1.0 およびそれ以降
アプリケーション内で複数回実行される SQL ステートメントがある場合は、SQL ステートメントごとに個別の

SQLStatement インスタンスを作成し、その SQL コマンドを実行するたびにその SQLStatement インスタンスを使用します。例えば、作成するアプリケーションに何度も実行される 4 つの異なる SQL 操作が含まれている場合は、4 つのSQLStatement インスタンスを作成し、各ステートメントの execute() メソッドを呼び出してステートメントを実行します。
すべての SQL ステートメントに対して 1 つの SQLStatement インスタンスを使用し、ステートメントを実行する前に毎回その text プロパティを再定義するという方法は避けてください。

ステートメントパラメーターを使用する
Adobe AIR 1.0 およびそれ以降
ユーザー入力をステートメントテキストに連結する代わりに SQLStatement のパラメーターを使用します。パラメーターを使用すると、SQL インジェクション攻撃が行われる可能性がなくなるため、アプリケーションのセキュリティが向上します。クエリで（SQL リテラル値だけでなく）オブジェクトを使用できるようにもなります。さらに、ステートメントを実行のたびに再コンパイルせずに再利用できるため、実行効率も向上します。詳しくは、704 ページの「ステートメント内でのパラメーターの使用」を参照してください。

最終更新日 2015/10/14

749

第 41 章：バイト配列の操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ByteArray クラスを使用すると、データのバイナリストリームを読み書きできます。バイナリストリームは基本的にバイトの配列です。このクラスは、最も基本的なレベルのデータにアクセスするための手段を提供します。コンピューターのデー
タはバイト（8 ビットのグループ）で構成されるので、バイト単位でデータを読み取れるということは、クラスとアクセスメソッドが存在しないデータにアクセスできることを意味します。ByteArray クラスを使用すると、ビットマップから、
ネットワーク経由で伝送されるデータストリームに至るまで、任意のデータストリームをバイトレベルで解析できます。

writeObject() メソッドを使用すると、オブジェクトを直列化された Action Message Format（AMF）で ByteArray に書き込むことができます。一方、readObject() メソッドを使用すると、直列化されたオブジェクトを ByteArray から元のデータ型の変数に読み取ることができます。表示オブジェクトを除くすべてのオブジェクトを直列化できます。表示オブジェクト
は、表示リストに配置できるオブジェクトです。カスタムクラスをランタイムに使用できる場合は、直列化されたオブジェ
クトをカスタムクラスインスタンスに割り当てて戻すこともできます。オブジェクトを AMF に変換した後は、ネットワー
ク接続を通して効率よく転送したり、ファイルに保存したりできます。
ここで説明する Adobe® AIR® のサンプルアプリケーションでは、バイトストリーム処理の例として .zip ファイルを読み取
り、.zip ファイルに含まれるファイルのリストを抽出して、それをデスクトップに書き込みます。
関連項目

flash.utils.ByteArray
flash.utils.IExternalizable
Action Message Format 仕様

ByteArray の読み取りと書き込み
Flash Player 9 以降、Adobe AIR 1.0 以降
ByteArray クラスは、flash.utils パッケージの一部です。ActionScript 3.0 で ByteArray オブジェクトを作成するには、次の例に示すように、ByteArray クラスを読み込んでコンストラクターを呼び出します。
import flash.utils.ByteArray;var stream:ByteArray = new ByteArray();

ByteArray のメソッド
Flash Player 9 以降、Adobe AIR 1.0 以降意味のあるデータストリームはすべて、分析して目的の情報を発見できるような形式に編成されています。例えば、単純な従業員ファイルのレコードには通常、ID 番号、氏名、住所、電話番号などが含まれます。MP3 オーディオファイルには、
ダウンロードされているファイルのタイトル、作成者、アルバム、発行日、およびジャンルを示す ID3 タグが含まれます。
一定の形式を使用することで、データストリーム上のデータの予想される順序がわかります。これにより、データストリー
ムをインテリジェントに読み取ることができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

750

バイト配列の操作

ByteArray クラスには、データストリームの読み書きを容易にするメソッドがいくつか用意されています。例えば、
readBytes() と writeBytes()、readInt() と writeInt()、readFloat() と writeFloat()、readObject() と writeObject()、readUTFBytes()と writeUTFBytes() などがあります。これらのメソッドを使用することで、データストリームから特定のデータ型の変数にデータを読み取ったり、特定のデータ型からバイナリデータストリームに直接書き込んだりすることができます。
例えば、次のコードは、ストリングと浮動小数点数の単純な配列を読み取り、各エレメントを ByteArray に書き込みます。
この配列は、コードから適切な ByteArray メソッド（writeUTFBytes() および writeFloat()）を呼び出してデータを書き込む
処理に適した編成になっています。同じデータパターンの繰り返しなので、ループを使用して配列を読み取ることができます。
// The following example reads a simple Array (groceries), made up of strings// and floating-point numbers, and writes it to a ByteArray.
import flash.utils.ByteArray;// define the grocery list Arrayvar groceries:Array = ["milk", 4.50, "soup", 1.79, "eggs", 3.19, "bread" , 2.35]// define the ByteArrayvar bytes:ByteArray = new ByteArray();// for each item in the arrayfor (var i:int = 0; i < groceries.length; i++) {bytes.writeUTFBytes(groceries[i++]); //write the string and position to the next item
bytes.writeFloat(groceries[i]);// write the float
trace("bytes.position is: " + bytes.position);//display the position in ByteArray}
trace("bytes length is: " + bytes.length);// display the length

position プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
position プロパティには、読み取り中または書き込み中の ByteArray のインデックスを示すポインターの現在位置が格納されます。次のコードに示すように、position プロパティの初期値は 0（ゼロ）です。
var bytes:ByteArray = new ByteArray();
trace("bytes.position is initially: " + bytes.position); // 0

ByteArray の読み書きを行うと、使用したメソッドによって position プロパティが更新され、最後に読み書きしたバイトの直後の位置を指すようになります。例えば次のコードでは、ストリングを ByteArray に書き込んだ後、position プロパ
ティは ByteArray 内のストリングの直後のバイトを指すようになります。
var bytes:ByteArray = new ByteArray();
trace("bytes.position is initially: " + bytes.position); // 0
bytes.writeUTFBytes("Hello World!");trace("bytes.position is now: " + bytes.position);// 12

同様に、読み取り操作を行うと、読み取ったバイト数だけ position プロパティがインクリメントされます。
var bytes:ByteArray = new ByteArray();
trace("bytes.position is initially: " + bytes.position); // 0
bytes.writeUTFBytes("Hello World!");trace("bytes.position is now: " + bytes.position);// 12
bytes.position = 0;
trace("The first 6 bytes are: " + (bytes.readUTFBytes(6)));//Hellotrace("And the next 6 bytes are: " + (bytes.readUTFBytes(6)));// World!

position プロパティを ByteArray の特定の位置に設定することで、そのオフセットを読み書きできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

751

バイト配列の操作

bytesAvailable プロパティと length プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
length プロパティと bytesAvailable プロパティは、ByteArray の長さ、および現在位置から終端までの間に残っているバイト数を示します。次の例では、これらのプロパティの使用方法を示します。この例では、テキストのストリングを ByteArrayに書き込んだ後、ByteArray を一度に 1 バイトずつ読み取り、文字「a」または終端（bytesAvailable <= 0）を検出すると終了します。
var bytes:ByteArray = new ByteArray();
var text:String = "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vivamus etc.";
bytes.writeUTFBytes(text); // write the text to the ByteArray
trace("The length of the ByteArray is: " + bytes.length);// 70
bytes.position = 0; // reset position
while (bytes.bytesAvailable > 0 && (bytes.readUTFBytes(1) != 'a')) {//read to letter a or end of bytes}
if (bytes.position < bytes.bytesAvailable) {trace("Found the letter a; position is: " + bytes.position); // 23
trace("and the number of bytes available is: " + bytes.bytesAvailable);// 47}

endian プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
マルチバイトの数値、つまり格納に必要なメモリが 1 バイトより多い数値の格納方法は、コンピューターによって異なる場
合があります。例えば、整数の格納に 4 バイト（32 ビット）のメモリを使用するとします。あるコンピューターでは数値の最上位バイトが最初に（最も小さいメモリアドレスに）格納され、別のコンピューターでは最下位バイトが最初に格納されます。このようなコンピューターの属性、すなわちバイト順序の属性は、ビッグエンディアン（最上位バイトが最初）またはリトルエンディアン（最下位バイトが最初）と呼ばれます。例えば、0x31323334 という数値は、バイト順序がビッグエ
ンディアンかリトルエンディアンかに応じて次のように格納されます。a0 は 4 バイトのうちの最小メモリアドレスを表し、a3 は最大メモリアドレスを表します。
ビッグエ
ンディア
ン

ビッグエ
ンディア
ン

ビッグエ
ンディア
ン

ビッグエ
ンディア
ン

a0

a1

a2

a3

31

32

33

34

リトルエ
ンディア
ン

リトルエ
ンディア
ン

リトルエ
ンディア
ン

リトルエ
ンディア
ン

a0

a1

a2

a3

34

33

32

31

ByteArray クラスの endian プロパティを使用すると、マルチバイト数値を処理する際のバイト順序を指定することができます。このプロパティに設定できる値は「bigEndian」または「littleEndian」で、Endian クラスでは endian プロパティを設定するための定数として BIG_ENDIAN と LITTLE_ENDIAN が定義されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

752

バイト配列の操作

compress() メソッドと uncompress() メソッド
Flash Player 9 以降、Adobe AIR 1.0 以降
compress() メソッドを使用すると、パラメーターとして指定する圧縮アルゴリズムに従って、ByteArray を圧縮できます。
uncompress() メソッドを使用すると、圧縮アルゴリズムに従って、圧縮されている ByteArray を圧縮解除できます。
compress() および uncompress() の呼び出し後、バイト配列の長さは新しい長さに設定され、position プロパティは終端に設定されます。

CompressionAlgorithm クラスで定義されている定数を使用して、圧縮アルゴリズムを指定できます。ByteArray クラス
では、deflate（AIR のみ）、zlib および lzma アルゴリズムがサポートされます。zlib 圧縮データ形式については、

http://www.ietf.org/rfc/rfc1950.txt の説明を参照してください。Flash Player 11.4 および AIR 3.4 用に、lzma アルゴリ
ズムが追加されました。詳しくは、http://www.7-zip.org/7z.html の説明を参照してください。
deflate 圧縮アルゴリズムは、zlib、gzip および一部の zip 実装など、いくつかの圧縮形式で使用されています。deflate 圧
縮アルゴリズムについては、http://www.ietf.org/rfc/rfc1951.txt の説明を参照してください。
次の例では、bytes という名前の ByteArray を lzma アルゴリズムで圧縮しています。
bytes.compress(CompressionAlgorithm.LZMA);

次の例では、deflate アルゴリズムで圧縮された ByteArray の圧縮を解除しています。
bytes.uncompress(CompressionAlgorithm.LZMA);

オブジェクトの読み取りと書き込み
Flash Player 9 以降、Adobe AIR 1.0 以降
readObject() メソッドと writeObject() メソッドは、直列化された Action Message Format （AMF）でエンコードされた
ByteArray のオブジェクトを読み取ったり、書き込んだりします。AMF はアドビ システムズ社が開発した独自のメッセー
ジプロトコルであり、Netstream、NetConnection、NetStream、LocalConnection、Shared Objects など、様々なActionScript 3.0 クラスで使用されています。

1 バイト型のマーカーが、その後に続くエンコードされたデータの型を示します。AMF では、次の 13 のデータ型が使用されます。
value-type = undefined-marker | null-marker | false-marker | true-marker | integer-type |double-type | string-type | xml-doc-type | date-type | array-type | object-type |xml-type | byte-array-type型マーカーの後には、エンコードされたデータが続きます。ただし、マーカーが null や true または false などの単一の可能な値を表す場合は例外です。このようなマーカーの場合、他には何もエンコードされません。

AMF には、AMF0 と AMF3 という 2 つのバージョンがあります。AMF 0 では複雑なオブジェクトの参照渡しがサポートされ、エンドポイントでオブジェクトの関係を復元することができます。AMF 3 は AMF 0 の改良版であり、オブジェクトの参照に加えてオブジェクトの特性とストリングを渡し、ActionScript 3.0 で導入された新しいデータ型をサポートします。
オブジェクトデータのエンコードに使用する AMF のバージョンは、ByteArray.objectEcoding プロパティで指定します。
flash.net.ObjectEncoding クラスでは、AMF のバージョンを指定するための定数として、ObjectEncoding.AMF0 とObjectEncoding.AMF3 が定義されています。
次の例では、writeObject() を呼び出して XML オブジェクトを ByteArray に書き込んだ後、Deflate アルゴリズムで圧縮し、デスクトップの order ファイルに書き込んでいます。この例では、終了時に AIR ウィンドウに「Wrote order file todesktop!」というメッセージを表示するために、ラベルを使用しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

753

バイト配列の操作

import flash.filesystem.*;import flash.display.Sprite;
import flash.display.TextField;
import flash.utils.ByteArray;public class WriteObjectExample extends Sprite{
public function WriteObjectExample(){var bytes:ByteArray = new ByteArray();
var myLabel:TextField = new TextField();
myLabel.x = 150;
myLabel.y = 150;
myLabel.width = 200;
addChild(myLabel);var myXML:XML =<order><item id='1'><menuName>burger</menuName><price>3.95</price></item><item id='2'><menuName>fries</menuName><price>1.45</price></item></order>;// Write XML object to ByteArraybytes.writeObject(myXML);bytes.position = 0;//reset position to beginningbytes.compress(CompressionAlgorithm.DEFLATE);// compress ByteArray
writeBytesToFile("order.xml", bytes);
myLabel.text = "Wrote order file to desktop!";}private function writeBytesToFile(fileName:String, data:ByteArray):void{
var outFile:File = File.desktopDirectory; // dest folder is desktop
outFile = outFile.resolvePath(fileName); // name of file to write
var outStream:FileStream = new FileStream();// open output file stream in WRITE modeoutStream.open(outFile, FileMode.WRITE);// write out the file
outStream.writeBytes(data, 0, data.length);// close it
outStream.close();}}readObject() メソッドは、直列化された AMF のオブジェクトを ByteArray から読み取り、指定された型のオブジェクトに格納します。次の例では、order ファイルをデスクトップから ByteArray（inBytes）に読み取り、圧縮を解除した後、readObject() を呼び出して XML オブジェクト orderXML に格納しています。この例では、for each() ループ構造を使用して、各ノードを表示用のテキスト領域に追加しています。また、objectEncoding プロパティの値を、order ファイルのコンテンツのヘッダーと共に表示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

754

バイト配列の操作

import flash.filesystem.*;import flash.display.Sprite;
import flash.display.TextField;
import flash.utils.ByteArray;public class ReadObjectExample extends Sprite{
public function ReadObjectExample(){var inBytes:ByteArray = new ByteArray();// define text area for displaying XML content
var myTxt:TextField = new TextField();
myTxt.width = 550;
myTxt.height = 400;
addChild(myTxt);//display objectEncoding and file heading
myTxt.text = "Object encoding is: " + inBytes.objectEncoding + "\n\n" + "order file: \n\n";readFileIntoByteArray("order", inBytes);
inBytes.position = 0; // reset position to beginning
inBytes.uncompress(CompressionAlgorithm.DEFLATE);
inBytes.position = 0;//reset position to beginning// read XML Object
var orderXML:XML = inBytes.readObject();// for each node in orderXML
for each (var child:XML in orderXML){// append child node to text area
myTxt.text += child + "\n";}}// read specified file into byte arrayprivate function readFileIntoByteArray(fileName:String, data:ByteArray):void{
var inFile:File = File.desktopDirectory; // source folder is desktop
inFile = inFile.resolvePath(fileName); // name of file to readvar inStream:FileStream = new FileStream();inStream.open(inFile, FileMode.READ);
inStream.readBytes(data);
inStream.close();}}

ByteArray の例：.zip ファイルの読み取り
Adobe AIR 1.0 およびそれ以降
この例では、種類の異なる複数のファイルを含む単純な .zip ファイルを読み取る方法を示します。その手段として、ここでは各ファイルに関連するデータをメタデータから抽出し、ファイルごとに ByteArray に圧縮解除して、ファイルをデスクトップに書き込んでいます。

.zip ファイルの一般的な構造は、http://www.pkware.com/documents/casestudies/APPNOTE.TXT に記載されている
PKWARE Inc. の仕様に基づきます。最初にあるのは .zip アーカイブ内の最初のファイルのファイルヘッダーとファイル
データで、その後に、他の各ファイルのファイルヘッダーとファイルデータのペアが続きます。ファイルヘッダーの構造については後で説明します。.zip ファイルには次に、必要に応じてデータ記述子レコードが含まれます（通常は、出力 zip

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

755

バイト配列の操作

ファイルがディスクに保存されずメモリに作成された場合がこれに当たります）。次に、アーカイブ復号化ヘッダー、アーカ
イブ追加データレコード、中央ディレクトリ構造、Zip64 中央ディレクトリ終了レコード、Zip64 中央ディレクトリ終了ロ
ケーター、中央ディレクトリ終了レコードなど、いくつかの追加オプションエレメントがあります。
この例のコードは、フォルダーを含まない zip ファイルのみを解析するように作られており、データ記述子レコードは想定していません。最後のファイルデータの後にある情報はすべて無視します。
各ファイルのファイルヘッダーの形式は次のとおりです。
ファイルヘッダーシグネチャ

4 バイト

必要なバージョン

2 バイト

汎用ビットフラグ

2 バイト

圧縮方法

2 バイト（8 = DEFLATE、0 =UNCOMPRESSED）

最終ファイル更新時刻

2 バイト

最終ファイル更新日

2 バイト

crc-32

4 バイト

圧縮サイズ

4 バイト

非圧縮サイズ

4 バイト

ファイル名の長さ

2 バイト

追加フィールドの長さ

2 バイト

ファイル名

variable

追加フィールド

variable

ファイルヘッダーの後には実際のファイルデータがあり、圧縮方法フラグに応じて、圧縮されている場合とされていない場
合があります。フラグの値は、ファイルデータが圧縮されていない場合は 0（ゼロ）、データが DEFLATE アルゴリズムで圧縮されている場合は 8、他の圧縮アルゴリズムの場合は別の値になります。
この例のユーザーインターフェイスは、ラベルとテキスト領域（taFiles）で構成されています。アプリケーションは、.zip
ファイルで検出したファイルごとに、ファイル名、圧縮サイズおよび非圧縮サイズの情報をテキスト領域に書き込みます。
次の MXML ドキュメントは、Flex バージョンのアプリケーションのユーザーインターフェイスの定義です。
<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
creationComplete="init();"><mx:Script><![CDATA[// The application code goes here]]></mx:Script><mx:Form><mx:FormItem label="Output"><mx:TextArea id="taFiles" width="320" height="150"/></mx:FormItem></mx:Form></mx:WindowedApplication>

プログラムの最初で、次のタスクを実行します。

•

必要なクラスを読み込みます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

756

バイト配列の操作

import flash.filesystem.*;import flash.utils.ByteArray;
import flash.events.Event;•

ユーザーインターフェイスを定義します。（Flash）。
import fl.controls.*;//requires TextArea and Label components in the Libraryvar taFiles = new TextArea();var output = new Label();taFiles.setSize(320, 150);
taFiles.move(10, 30);
output.move(10, 10);
output.width = 150;
output.text = "Contents of HelloAir.zip";
addChild(taFiles);
addChild(output);• ByteArray の bytes を定義します。
var bytes:ByteArray = new ByteArray();•

ファイルヘッダーのメタデータを格納する変数を定義します。
// variables for reading fixed portion of file header
var fileName:String = new String();var flNameLength:uint;
var xfldLength:uint;
var offset:uint;
var compSize:uint;
var uncompSize:uint;
var compMethod:int;
var signature:int;• .zip ファイルを表す File（zfile）オブジェクトと FileStream（zStream）オブジェクトを定義し、展開するファイルが含まれている .zip ファイルの場所（デスクトップディレクトリの「HelloAIR.zip」という名前のファイル）を指定します。
// File variables for accessing .zip filevar zfile:File = File.desktopDirectory.resolvePath("HelloAIR.zip");
var zStream:FileStream = new FileStream();Flex の場合、プログラムのコードは init() メソッドで開始し、このメソッドは、ルート mx:WindowedApplication タグのcreationComplete ハンドラーとして呼び出されます。
// for Flex
private function init():void{

プログラムは、.zip ファイルを READ モードで開くことにより開始します。
zStream.open(zfile, FileMode.READ);

次に、bytes の endian プロパティを LITTLE_ENDIAN に設定し、数値フィールドのバイト順序は最下位バイトが最初である
ことを示します。
bytes.endian = Endian.LITTLE_ENDIAN;

次に、while() ステートメントでループを開始し、ファイルストリーム内の現在位置がファイルのサイズ以上になるまで続けます。
while (zStream.position < zfile.size){

ループ内部の最初のステートメントでは、ファイルストリームの最初の 30 バイトを ByteArray の bytes に読み取ります。最初の 30 バイトは、最初のファイルヘッダーの固定サイズ部分を構成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

757

バイト配列の操作// read fixed metadata portion of local file header
zStream.readBytes(bytes, 0, 30);

次に、コードは、30 バイトのヘッダーの最初のバイトから整数（signature）を読み取ります。ZIP 形式の定義では、すべてのファイルヘッダーのシグネチャは 16 進数値 0x04034b50 と指定されています。シグネチャが異なる場合は、コードが .zip
ファイルのファイル部分を超えており、展開するファイルがそれ以上ないことを意味します。その場合は、コードはバイト
配列の終端を待つことなく、直ちに while ループを終了します。
bytes.position = 0;signature = bytes.readInt();// if no longer reading data files, quitif (signature != 0x04034b50){
break;}

コードの次の部分では、オフセット位置 8 のヘッダーバイトを読み取って、値を変数 compMethod に格納します。このバイトには、そのファイルの圧縮時に使用された圧縮方法を示す値が含まれます。複数の圧縮方法を使用できますが、実際には、ほとんどすべての .zip ファイルで DEFLATE 圧縮アルゴリズムが使用されます。現在のファイルが DEFLATE 圧縮アルゴ
リズムで圧縮されている場合は、compMethod は 8 です。ファイルが圧縮されていない場合は、compMethod は 0 です。
bytes.position = 8;
compMethod = bytes.readByte();// store compression method (8 == Deflate)

最初の 30 バイトの後にはヘッダーの可変長部分があり、ファイル名と、場合によっては追加フィールドが含まれます。変
数 offset に、この部分のサイズが格納されています。サイズはファイル名の長さと追加フィールドの長さを加えたもので、これらの値はヘッダーのオフセット 26 および 28 から読み取ります。
offset = 0;// stores length of variable portion of metadata
bytes.position = 26; // offset to file name length
flNameLength = bytes.readShort();// store file nameoffset += flNameLength; // add length of file namebytes.position = 28;// offset to extra field length
xfldLength = bytes.readShort();offset += xfldLength;// add length of extra field

次に、プログラムは、offset 変数に格納されているバイト数だけ、ファイルヘッダーの可変長部分を読み取ります。
// read variable length bytes between fixed-length header and compressed file data
zStream.readBytes(bytes, 30, offset);

そして、ヘッダーの可変長部分からファイル名を読み取り、ファイルの圧縮サイズ（zip サイズ）と非圧縮サイズ（元のサイズ）と共にテキスト領域に表示します。
// Flash version
bytes.position = 30;
fileName = bytes.readUTFBytes(flNameLength); // read file nametaFiles.appendText(fileName + "\n"); // write file name to text area
bytes.position = 18;
compSize = bytes.readUnsignedInt(); // store size of compressed portion
taFiles.appendText("\tCompressed size is: " + compSize + '\n');bytes.position = 22; // offset to uncompressed size
uncompSize = bytes.readUnsignedInt(); // store uncompressed size
taFiles.appendText("\tUncompressed size is: " + uncompSize + '\n');

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

758

バイト配列の操作// Flex version
bytes.position = 30;
fileName = bytes.readUTFBytes(flNameLength); // read file nametaFiles.text += fileName + "\n"; // write file name to text area
bytes.position = 18;
compSize = bytes.readUnsignedInt(); // store size of compressed portion
taFiles.text += "\tCompressed size is: " + compSize + '\n';bytes.position = 22; // offset to uncompressed size
uncompSize = bytes.readUnsignedInt(); // store uncompressed size
taFiles.text += "\tUncompressed size is: " + uncompSize + '\n';

続いて、圧縮サイズで指定されている長さだけファイルストリームからファイルの残りを読み取って bytes に格納し、最初の 30 バイトのファイルヘッダーを上書きします。圧縮サイズは、ファイルが圧縮されていない場合でも正確です。その場合の圧縮サイズはファイルの非圧縮サイズと等しくなるからです。
// read compressed file to offset 0 of bytes; for uncompressed files// the compressed and uncompressed size is the sameif (compSize == 0) continue;
zStream.readBytes(bytes, 0, compSize);

次に、圧縮ファイルの圧縮を解除し、outfile() 関数を呼び出して出力ファイルストリームに書き込みます。outfile() には、
ファイル名と、ファイルデータを含むバイト配列を渡します。
if (compMethod == 8) // if file is compressed, uncompress{
bytes.uncompress(CompressionAlgorithm.DEFLATE);}
outFile(fileName, bytes);// call outFile() to write out the file

上記の例で、bytes.uncompress(CompressionAlgorithm.DEFLATE) は AIR アプリケーションでみ動作します。AIR と Flash
Player の両方用に圧縮されていない deflatede のデータを取得するには、ByteArray の inflate() 関数を呼び出します。
右中括弧は、while ループの終わり、および init() メソッドと Flex アプリケーションコード（outFile() メソッド以外）の終わりを示します。実行は while ループの先頭に戻り、.zip ファイルの次のバイトの処理を続けます。つまり、別のファイルを展開するか、または最後のファイルの処理が済んだ場合は .zip ファイルの処理を終了します。
} // end of while loop
} // for Flex version, end of init() method and application

outfile() 関数は、デスクトップ上の出力ファイルを WRITE モードで開き、filename パラメーターで指定された名前を設定します。次に、ファイルデータを data パラメーターから出力ファイルストリーム（outStream）に書き込み、ファイルを閉じます。
// Flash version
function outFile(fileName:String, data:ByteArray):void{
var outFile:File = File.desktopDirectory; // destination folder is desktop
outFile = outFile.resolvePath(fileName); // name of file to write
var outStream:FileStream = new FileStream();// open output file stream in WRITE modeoutStream.open(outFile, FileMode.WRITE);// write out the file
outStream.writeBytes(data, 0, data.length);// close it
outStream.close();}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

759

バイト配列の操作

private function outFile(fileName:String, data:ByteArray):void{
var outFile:File = File.desktopDirectory; // dest folder is desktop
outFile = outFile.resolvePath(fileName); // name of file to write
var outStream:FileStream = new FileStream();// open output file stream in WRITE modeoutStream.open(outFile, FileMode.WRITE);// write out the file
outStream.writeBytes(data, 0, data.length);// close it
outStream.close();}最終更新日 2015/10/14

760

第 42 章：ネットワーキングとコミュニケーショ
ンの基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player または AIR でアプリケーションを構築するときは、アプリケーションの外部のリソースにアクセスする必要が頻繁に生じます。例えば、インターネット Web サーバーにイメージの要求を送信して、返されたイメージデータを取得する場合、または、直列化されたオブジェクトを、ソケット接続経由でアプリケーションサーバーとやりとりする場合などです。Flash Player と AIR API には、アプリケーションでこのようなデータのやりとりを可能にするクラスがいくつか用意されています。これらの API は、UDP、TCP、HTTP、RTMP および RTMFP などのプロトコルに対応した IP ベースのネットワーキングをサポートしています。
次のクラスを使用すると、ネットワークを介したデータの送受信を行うことができます。
クラス

Loader

サポートしているデータ形
式
SWF、PNG、JPEG、GIF

プロトコル

説明

HTTP、HTTPS

サポートしているデータ型をロードして、そのデータを表示オブジェクトに変換します。

189 ページの「表示コンテンツの動的ロード」を
URLLoader

任意（テキスト、XML、バHTTP、HTTPS

参照してください。
任意の形式のデータをロードします。アプリケー
ションではデータを解釈する必要があります。

HTTP

照してください。
ファイルをアップロードおよびダウンロードしま
す。

イナリ、その他）

786 ページの「URLLoader クラスの使用」を参
FileReference任意628 ページの「FileReference クラスの使用」を
NetConnection

ビデオ、オーディオ、
ActionScript メッセージ

HTTP、HTTPS、
RTMP、RTMFP

形式（AMF）

Sound

オーディオ

参照してください。
ビデオ、オーディオおよびリモートオブジェクトの各ストリームに接続します。

453 ページの「ビデオの操作」を参照してくださHTTPい。
サポートしているオーディオ形式をロードして再生します。

423 ページの「外部のサウンドファイルの読み込
み」を参照してください。

XMLSocket

XML

TCP

XMLSocket サーバーと XML メッセージをやりとりします。

773 ページの「XML ソケット」を参照してくだ
Socket

任意

TCP

さい。
TCP ソケットサーバーに接続します。

769 ページの「バイナリクライアントソケット」
を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

761

ネットワーキングとコミュニケーションの基礎クラス

SecureSocket（AIR）

サポートしているデータ形
式
任意

プロトコル

説明

TCP SSLv3 または TCP TLSv1

ソケットサーバーに接続します。

SSL または TLS セキュリティが要求される TCP
769 ページの「セキュアなクライアントソケット（AIR）」を参照してください。

ServerSocket（AIR）

任意

TCP

着信 TCP ソケット接続用のサーバーとして機能します。

777 ページの「サーバーソケット」を参照してく
ださい。

DatagramSocket（AIR）

任意

UDP

UDP パケットを送受信します。
779 ページの「UDP ソケット（AIR）」を参照してください。

通常、Web アプリケーションを作成する場合は、ユーザーのアプリケーションの状態に関する永続的な情報を格納しておくと便利です。一般的に、HTML ページとアプリケーションでは Cookie を使用してこれに対応します。Flash Player の場
合は、SharedObject クラスを使用できます。676 ページの「共有オブジェクト」を参照してください（AIR アプリケー
ションでは SharedObject クラスを使用できますが、データを通常のファイルに保存するだけの方が、制限は少なくなります）。
同一コンピューター上で、Flash Player または AIR アプリケーションが別の Flash Player または AIR アプリケーションと通信する必要がある場合は、LocalConnection クラスを使用できます。例えば、同じ Web ページ上にある 2 つ（以上）のSWF は相互に通信できます。同様に、Web ページ上で実行している SWF は AIR アプリケーションと通信できます。799
ページの「Flash Player および AIR の他のインスタンスとの通信」を参照してください。
ローカルコンピューター上で、SWF 以外の他のプロセスと通信する必要がある場合は、AIR 2 で追加された
NativeProcess クラスを使用できます。NativeProcess クラスを使用すると、AIR アプリケーションは他のアプリケーショ
ンを起動して通信することができます。805 ページの「AIR のネイティブプロセスとの通信」を参照してください。

AIR アプリケーションが動作しているコンピューターのネットワーク環境に関する情報が必要な場合は、次のクラスを使用できます。

• NetworkInfo - 利用可能なネットワークインターフェイスの情報（コンピューターの IP アドレスなど）を提供します。
762 ページの「ネットワークインターフェイス」を参照してください。
• DNSResolver - DNS レコードのルックアップを可能にします。766 ページの「ドメインネームシステム（DNS）レ
コード」を参照してください。

• ServiceMonitor — サーバーの可用性を監視できます。764 ページの「サービス監視」を参照してください。
• URLMonitor — 特定の URL におけるリソースの可用性を監視できます。765 ページの「HTTP 監視」を参照してくだ
さい。

• SocketMonitor および SecureSocketMonitor - ソケットにおけるリソースの可用性を監視できます。765 ページの「ソケット監視」を参照してください。
重要な概念と用語
次の参照リストに、ネットワーキングおよび通信に関するコードのプログラミングで使用される重要な用語を示します。
外部データ アプリケーションの外部に何らかの形式で保存され、必要に応じてアプリケーションに読み込まれるデータです。このデータは、直接ロードされるファイル内に格納したり、データベース内、またはサーバー上で実行中のプログラム
やスクリプトを呼び出すことで取得可能なその他の形式で格納することができます。

URL エンコード形式の変数 URL エンコード形式を使用すると、複数の変数（変数の名前と値のペア）を 1 つのテキストス
トリングで表現できます。各変数は、name=value という形式で記述されます。各変数（名前と値の各ペア）は、
variable1=value1&variable2=value2 のように、アンパサンド文字で区切られます。このように、任意の数の変数を 1 つのメッセージとして送信できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

762

ネットワーキングとコミュニケーションの基礎

MIME タイプ インターネット通信において特定のファイルの種類を識別するために使用される標準コードです。ファイルの種類にはそれぞれ、識別に使用される特定のコードがあります。ファイルやメッセージの送信時、Web サーバーやユーザーの Flash Player または AIR インスタンスなどのコンピューターが、送信するファイルのタイプを指定します。
HTTP インターネットを介して送信される Web ページやその他の様々なタイプのコンテンツを配信するための標準形式であるハイパーテキスト転送プロトコルです。
要求メソッド AIR アプリケーションや Web ブラウザーなどのアプリケーションが HTTP リクエストと呼ばれるメッセー
ジを Web サーバーに送信するとき、送信されるデータはすべて 2 つの方法のいずれかでリクエスト内に埋め込まれます。
この 2 つのリクエストメソッドとは、GET および POST です。サーバー側で、リクエストを受信するプログラムはリクエ
ストの該当箇所を確認してデータを探す必要があります。そのため、アプリケーションからのデータの送信に使用するリク
エストメソッドは、サーバーでそのデータの読み取りに使用するリクエストメソッドと一致している必要があります。
ソケット接続 2 台のコンピューター間での通信に使用される永続的な接続です。
アップロード 他のコンピューターにファイルを送信すること。
ダウンロード 他のコンピューターからファイルを取得すること。

ネットワークインターフェイス
Adobe AIR 2 以降
NetworkInfo オブジェクトを使用すると、アプリケーションで使用できるハードウェアおよびソフトウェアのネットワーク
インターフェイスを検出できます。NetworkInfo オブジェクトは「シングルトン」オブジェクトで、作成する必要はありません。代わりに、静的クラスプロパティ networkInfo を使用して、NetworkInfo シングルトンオブジェクトにアクセスしま
す。また、NetworkInfo オブジェクトは、使用可能なインターフェイスのいずれかが変更されると、networkChange イベン
トを送出します。

NetworkInterface オブジェクトのリストを取得するには、findInterfaces() メソッドを呼び出します。リストには
NetworkInterface オブジェクトごとに、使用可能なインターフェイスの 1 つが記載されています。NetworkInterface オブジェクトでは、IP アドレス、ハードウェアアドレス、最大転送ユニット、インターフェイスの稼働状況などに関する情報を提供します。
次のコード例では、クライアントコンピューター上で各インターフェイスの NetworkInterface プロパティをトレースします。
package {import flash.display.Sprite;
import flash.net.InterfaceAddress;
import flash.net.NetworkInfo;
import flash.net.NetworkInterface;public class NetworkInformationExample extends Sprite{
public function NetworkInformationExample(){var networkInfo:NetworkInfo = NetworkInfo.networkInfo;var interfaces:Vector.<NetworkInterface> = networkInfo.findInterfaces();if( interfaces != null ){trace( "Interface count: " + interfaces.length );for each ( var interfaceObj:NetworkInterface in interfaces ){trace( "\nname: " + interfaceObj.name );trace( "display name: " + interfaceObj.displayName );最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

763

ネットワーキングとコミュニケーションの基礎

trace( "mtu: " + interfaceObj.mtu );trace( "active?: " + interfaceObj.active );trace( "parent interface: " + interfaceObj.parent );trace( "hardware address: " + interfaceObj.hardwareAddress );if( interfaceObj.subInterfaces != null ){trace( "# subinterfaces: " + interfaceObj.subInterfaces.length );}trace("# addresses: " + interfaceObj.addresses.length );for each ( var address:InterfaceAddress in interfaceObj.addresses ){trace( " type: "+ address.ipVersion );trace( " address: " + address.address );trace( " broadcast: " + address.broadcast );trace( " prefix length: " + address.prefixLength );
}
}
}
}
}
}

詳しくは、以下を参照してください。

• NetworkInfo• NetworkInterface• InterfaceAddress• Flexpert：Detecting the network connection type with Flex 4.5

ネットワーク接続の変更
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、ネットワーク接続が一定ではなく変化する環境で実行できます。アプリケーションでオンライン
リソースに対する接続を管理できるように、Adobe AIR では、ネットワーク接続が使用できるようになったり使用できなくなったりするたびにネットワーク変更イベントが送信されます。NetworkInfo オブジェクトおよびアプリケーションのNativeApplication オブジェクトは両方とも networkChange イベントを送出します。このイベントに対処するには、リスナーを追加します。
NetworkInfo.networkInfo.addEventListener(Event.NETWORK_CHANGE, onNetworkChange);

さらに、イベントハンドラー関数を定義します。
function onNetworkChange(event:Event){//Check resource availability}

networkChange イベントは、ネットワーク活動全体の変更ではなく、個々のネットワーク接続の変更のみを示します。AIR
では、ネットワークが変更された意味については解釈されません。ネットワークに接続されたコンピューターには実際の接
続や仮想接続が多数存在できるので、1 つの接続が切断されても必ずしもリソースが失われるわけではありません。一方、新しい接続でも、リソースの可用性の向上が保証されるわけではありません。新しい接続によって、それまで使用できていたリソースへのアクセスがブロックされることもあります（例えば、VPN に接続する場合など）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

764

ネットワーキングとコミュニケーションの基礎

一般に、アプリケーションでリモートリソースに接続できるかどうかを確認するには、試してみるしかありません。サービス監視フレームワークには、特定のホストに対するネットワーク接続が変更された場合に、イベントに基づいて応答する方法が用意されています。
注意：サービス監視フレームワークでは、サーバーで要求が受け入れられたかどうかが検出されます。良好な結果が確認されても、完全な接続が保証されるわけではありません。拡張可能な Web サービスでは、多くの場合、キャッシュ装置や負荷分散装置を使用して、Web サーバーのクラスタに対するトラフィックにリダイレクトしています。この場合、サービスプ
ロバイダーによって、ネットワーク接続の部分的な診断のみが提供されます。

サービス監視Adobe AIR 1.0 およびそれ以降
サービス監視フレームワークは、AIR フレームワークとは別に、aircore.swc ファイルに含まれています。このフレームワークを使用するには、aircore.swc ファイルがビルドプロセスで組み込まれる必要があります。

Adobe® Flash® Builder では、このライブラリが自動的に組み込まれます。
ServiceMonitor クラスでは、ネットワークサービスを監視するためのフレームワークを実装し、サービス監視の基本的な機能を提供します。デフォルトでは、ServiceMonitor クラスのインスタンスから、ネットワーク接続に関するイベントが送出されます。ServiceMonitor オブジェクトでは、インスタンスの作成時やランタイムでネットワークの変更が検出されるたびに、これらのイベントを送出します。さらに、ServiceMonitor インスタンスの pollInterval プロパティを設定すると、通常のネットワーク接続イベントに関係なく、指定した間隔（ミリ秒）で接続を確認することができます。

ServiceMonitor オブジェクトによるネットワーク接続の確認は、start() メソッドが呼び出されるまで実行されません。
URLMonitor クラスは ServiceMonitor クラスのサブクラスで、このクラスでは、特定の URLRequest に対する HTTP 接続の変更を検出します。

SocketMonitor クラスも ServiceMonitor クラスのサブクラスで、このクラスでは、特定のポートの特定のホストに対する接続の変更を検出します。
注意：AIR 2 以前は、サービス監視フレームワークは servicemonitor.swc ライブラリで公開されていました。現在、このライブラリは使用されません。代わりに aircore.swc ライブラリを使用します。

Flash CS4 および CS5 Professional
これらのクラスを Adobe® Flash® CS4 または CS5 Professional で使用するには、次のようにします。
1 ファイル／パブリッシュ設定を選択します。
2 ActionScript 3.0 の「設定」ボタンをクリックし、「ライブラリパス」を選択します。
3 「SWC ファイル を参照」ボタンをクリックし、Flash Professional のインストール先フォルダーの AIK フォルダーを参照します。

4 このフォルダー内で、/frameworks/libs/air/aircore.swc（AIR 2 の場合）または/frameworks/libs/air/servicemonitor.swc（AIR 1.5 の場合）を見つけます。
5 「OK」ボタンをクリックします。
6 次の import ステートメントを ActionScript 3.0 コードに追加します。
import air.net.*;最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

765

ネットワーキングとコミュニケーションの基礎

Flash CS3 Professional
これらのクラスを Adobe® Flash® CS3 Professional で使用するには、ServiceMonitorShim コンポーネントをコンポーネントパネルからライブラリにドラッグします。その後で、次の import ステートメントを ActionScript 3.0 コードに追加します。
import air.net.*;HTTP 監視
Adobe AIR 1.0 およびそれ以降
URLMonitor クラスでは、HTTP 要求をポート 80（HTTP 通信の一般的なポート）で特定のアドレスに送信できるかどうかを確認します。次のコードでは、URLMonitor クラスのインスタンスを使用して、アドビ システムズ社の Web サイトに対する接続の変更を検出します。
import air.net.URLMonitor;
import flash.net.URLRequest;
import flash.events.StatusEvent;var monitor:URLMonitor;
monitor = new URLMonitor(new URLRequest('http://www.example.com'));monitor.addEventListener(StatusEvent.STATUS, announceStatus);
monitor.start();function announceStatus(e:StatusEvent):void {trace("Status change. Current status: " + monitor.available);}

ソケット監視Adobe AIR 1.0 およびそれ以降
AIR アプリケーションでは、プッシュモデルの接続にソケット接続を使用することもできます。セキュリティ上の理由から、許可されていないポートでのネットワーク通信は、ファイアウォールやネットワークルーターによって制限されるのが一般的です。したがって、開発者は、ユーザーが常にソケット接続を実行できるとは限らないことを考慮する必要があります。
次のコードでは、SocketMonitor クラスのインスタンスを使用して、ソケット接続に対する接続の変更を検出します。監視対象のポートは 6667（IRC で一般に使用されるポート）です。
import air.net.ServiceMonitor;
import flash.events.StatusEvent;
socketMonitor = new SocketMonitor('www.example.com',6667);
socketMonitor.addEventListener(StatusEvent.STATUS, socketStatusChange);socketMonitor.start();function announceStatus(e:StatusEvent):void {trace("Status change. Current status: " + socketMonitor.available);}

ソケットサーバーでセキュア接続が必要な場合は、SocketMonitor クラスの代わりに SecureSocketMonitor クラスを使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

766

ネットワーキングとコミュニケーションの基礎

ドメインネームシステム（DNS）レコード
Adobe AIR 2.0 およびそれ以降
DNS リソースレコードのルックアップには、DNSResolver クラスを使用できます。DNS リソースレコードでは、ドメイ
ン名の IP アドレスまたは IP アドレスのドメイン名のような情報を提供します。ルックアップ可能な DNS リソースレコー
ドのタイプを以下に示します。

• ARecord - ホストの IPv4 アドレス
• AAAARecord - ホストの IPv6 アドレス
• MXRecord - ホストのメール交換レコード• PTRRecord - IP アドレスのホスト名• SRVRecord - サービスのサービスレコード
レコードをルックアップするには、クエリ文字列とレコードタイプを表すクラスオブジェクトを DNSResolver オブジェク
トの lookup() メソッドに渡します。使用するクエリ文字列はレコードタイプによって異なります。
レコードクラス

クエリ文字列

クエリ文字列の例

ARecord

ホスト名“example.com”

AAAARecord

ホスト名“example.com”

MXRecord

ホスト名“example.com”

PTRRecord

IP アドレス“208.77.188.166”

SRVRecord

サービス識別子：_service._protocol.host“_sip._tcp.example.com”

次のコード例では、ホスト "example.com" の IP アドレスをルックアップします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

767

ネットワーキングとコミュニケーションの基礎

package{import flash.display.Sprite;
import flash.events.DNSResolverEvent;import flash.events.ErrorEvent;import flash.net.dns.ARecord;
import flash.net.dns.DNSResolver;
public class DNSResolverExample extends Sprite{
public function DNSResolverExample(){var resolver:DNSResolver = new DNSResolver();resolver.addEventListener( DNSResolverEvent.LOOKUP, lookupComplete );resolver.addEventListener( ErrorEvent.ERROR, lookupError );resolver.lookup( "example.com.", ARecord );}private function lookupComplete( event:DNSResolverEvent ):void{
trace( "Query string: " + event.host );trace( "Record count: " + event.resourceRecords.length );for each( var record:* in event.resourceRecords ){if( record is ARecord ) trace( record.address );}}private function lookupError( error:ErrorEvent ):void{
trace("Error: " + error.text );}}}詳しくは、以下を参照してください。

• DNSResolver• DNSResolverEvent• ARecord• AAAARecord• MXRecord• PTRRecord• SRVRecord

最終更新日 2015/10/14

768

第 43 章：ソケット
Flash Player 9 以降、Adobe AIR 1.0 以降
ソケットとは、2 つのコンピュータープロセス間で確立されるネットワーク接続のタイプです。通常、これらのプロセスは、同じインターネットプロトコル（IP）ネットワークに接続している 2 台の異なるコンピューター上で実行されています。ただし、「local host」という名前の特殊な IP アドレスを使用すれば、接続された 2 つのプロセスを同じコンピューター上で実行することができます。

Adobe Flash Player は、クライアントサイドの伝送制御プロトコル（TCP）ソケットをサポートしています。Flash Player
アプリケーションは、ソケットサーバーとして機能している別のプロセスに接続できますが、他のプロセスからの着信接続要求を受け入れることはできません。つまり、Flash Player アプリケーションは、TCP サーバーへの接続は可能ですが、サーバーとして機能することはできません。

Flash Player API には XMLSocket クラスも含まれています。XMLSocket クラスでは、Flash Player 固有のプロトコルを使用します。これにより、当該プロトコルを理解するサーバーと XML メッセージをやりとりできます。XMLSocket クラスは ActionScript 1 で導入され、後方互換性の維持のために、引き続きサポートされています。一般に、Socket クラスは、
特に Flash XMLSocket との通信のために作成されたサーバーに接続する場合を除いて、新しいアプリケーションに対して使用する必要があります。

Adobe AIR によって、ソケットベースのネットワークプログラミング用のクラスがいくつか追加されます。AIR アプリ
ケーションは、ServerSocket クラスを使用すれば TCP ソケットサーバーとして機能できます。また、SSL または TLS セ
キュリティが要求されるソケットサーバーには SecureSocket クラスを使用して接続できます。AIR アプリケーションは、
DatagramSocket クラスを使用して、ユニバーサルデータグラムプロトコル（UDP）メッセージを送受信することもでき
ます。

関連項目

flash.net パッケージ
1031 ページの「ソケットへの接続」

TCP ソケットFlash Player 9 以降、Adobe AIR 1.0 以降
伝送制御プロトコル（TCP）には、固定ネットワーク接続経由でメッセージを交換する方法が用意されています。TCP では、送信されたメッセージは、（大きなネットワークの問題が発生しない限り）正しい順序で到達することが保証されています。TCP 接続では、「クライアント」と「サーバー」が必要です。Flash Player はクライアントソケットを作成できます。

Adobe AIR では、さらに、サーバーソケットも作成できます。
以下の ActionScript API が TCP 接続を提供します。

• Socket - クライアントアプリケーションがサーバーに接続できるようにします。Socket クラスは受信接続を監視できません。

• SecureSocket（AIR）- クライアントアプリケーションが信頼できるサーバーに接続して、暗号化された通信を確立できるようにします。

• ServerSocket（AIR）- アプリケーションが受信接続を監視して、サーバーとして機能できるようにします。
• XMLSocket - クライアントアプリケーションが XMLSocket サーバーに接続できるようにします。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

769

ソケット

バイナリクライアントソケット
Flash Player 9 以降、Adobe AIR 1.0 以降
バイナリソケット接続は、XML ソケットに似ていますが、クライアント / サーバー間で交換するデータが XML メッセージに限定されないという点が異なります。データはバイナリ情報として伝送されます。したがって、電子メールサーバー（POP3、SMTP、IMAP）やニュースサーバー（NNTP）など様々なサービスに接続できます。

Socket クラス
Flash Player 9 以降、Adobe AIR 1.0 以降
Socket クラスを使用すると、ソケット接続を確立して生のバイナリデータを読み書きできます。Socket クラスは、バイナ
リプロトコルを使用するサーバーとの通信に役立ちます。バイナリソケット接続を使用すれば、POP3、SMTP、IMAP、
NNTP など様々なインターネットプロトコルによる通信のコードを記述できます。この操作によって、アプリケーションから電子メールサーバーやニュースサーバーに接続することもできます。

Flash Player からサーバーに直接接続するには、サーバーが使用するバイナリプロトコルに従う必要があります。バイト順
序にビッグエンディアンを使用するサーバーと、リトルエンディアンを使用するサーバーがあります。「ネットワークバイト
順序」がビッグエンディアンとされているため、インターネット上の大部分のサーバーはビッグエンディアンのバイト順序を使用しています。また、Intel® x86 アーキテクチャでリトルエンディアンが採用されているので、リトルエンディアンの
バイト順序が使用されることもよくあります。データを送受信する対象のサーバーに適したエンディアンバイト順序を使用
してください。IDataInput および IDataOutput インターフェイスで実行されるすべての操作と、これらのインターフェイスを実装するクラス（ByteArray、Socket、URLStream）では、デフォルトでビッグエンディアン形式（先頭が最上位バイト）を使用します。Java と公式なネットワークバイト順序を一致させるために、このデフォルトのバイト順序が選択されました。使用するエンディアンを変更する場合は、endian プロパティを Endian.BIG_ENDIAN またはEndian.LITTLE_ENDIAN に設定します。

Socket クラスは、（flash.utils パッケージ内の）IDataInput および IDataOutput インターフェイスで定義されているすべてのメソッドを継承します。これらのメソッドは、Socket クラスからの読み取りおよび書き込みに使用する必要があります。
詳しくは、以下を参照してください。

• Socket• IDataInput• IDataOutput• socketData event
セキュアなクライアントソケット（AIR）
Adobe AIR 2 以降
SecureSocket クラスを使用すると、セキュアソケットレイヤーバージョン 4（SSLv4）またはトランスポート層セキュリ
ティバージョン 1（TLSv1）を使用しているソケットサーバーに接続できます。セキュアなソケットには 3 つのメリット（サーバー認証、データの整合性、メッセージの機密性）があります。ランタイムでは、サーバー証明書と、ユーザーの信頼ストアに格納されているルート証明機関証明書または中間証明機関証明書との関連付けを使用してサーバーを認証します。
ランタイムでは、SSL および TLS プロトコル実装で使用されている暗号化アルゴリズムに基づいて、データの整合性およびメッセージの機密性を確保します。

SecureSocket オブジェクトを使用してサーバーに接続する場合、ランタイムでは証明書信頼ストアを使用してサーバー証
明書を検証します。Windows および Mac では、オペレーティングシステムが信頼ストアを提供します。Linux では、ランタイムが独自の信頼ストアを提供します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

770

ソケット

サーバー証明書が有効でないまたは信頼できないと判断されると、ランタイムは ioError イベントを送出します。

SecureSocket オブジェクトの serverCertificateStatus プロパティを調べることにより、無効とされた理由を確認できます。有効または信頼された証明書を持たないサーバーとの通信は許可されません。

CertificateStatus クラスでは、想定される検証結果を表す文字列定数を定義します。

• Expired - 証明書の有効期限が切れています。
• Invalid - 証明書が無効と判断される理由は様々です。例えば、証明書が変更されているまたは破損している場合もあれ
ば、証明書のタイプが間違っている場合もあります。

• Invalid chain - サーバーの証明書チェーン内に無効な証明書が 1 つ以上存在します。
• Principal mismatch - サーバーのホスト名と証明書の共通名が一致しません。つまり、サーバーでは間違った証明書が使用されています。

• Revoked - 発行元の証明機関によって証明書が失効されています。
• Trusted - 証明書は有効で信頼されています。SecureSocket オブジェクトでは、有効で信頼された証明書を使用しているサーバーにのみ接続できます。

• Unknown - SecureSocket オブジェクトではまだ証明書を検証していません。connect() を呼び出す前と connect イベン
トまたは ioError イベントのいずれかが送出される前は、serverCertificateStatus プロパティにはこの状態が設定されています。

• Untrusted signers - 証明書には、クライアントコンピューターの信頼ストアに格納されている信頼されたルート証明書
への「チェーン」がありません。

SecureSocket オブジェクトと通信する場合は、セキュアなプロトコルおよび有効で信頼された証明書が使用されているサーバーが必要です。その他の点では、SecureSocket オブジェクトと Socket オブジェクトの使用方法は同じです。
SecureSocket オブジェクトは一部のプラットフォームではサポートされていません。SecureSocket クラスの isSupported
プロパティを使用すると、ランタイムが現在のクライアントコンピューターで SecureSocket オブジェクトの使用をサポートしているかどうかを確認できます。
詳しくは、以下を参照してください。

• SecureSocket• CertificateStatus• IDataInput• IDataOutput• socketData event

TCP ソケットの例：Telnet クライアントの構築
Flash Player 9 以降、Adobe AIR 1.0 以降
この Telnet の例では、Socket クラスを使用してリモートサーバーに接続し、データを伝送する手法を示します。この例は、次の手法を示します。

• Socket クラスを使用したカスタム Telnet クライアントの作成• ByteArray オブジェクトを使用したリモートサーバーへのテキストの送信•

リモートサーバーから受信したデータの処理

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。Telnet アプリケーションのファイ
ルは、Samples/Telnet フォルダーにあります。このアプリケーションは次のファイルで構成されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

771

ソケット

ファイル

説明

TelnetSocket.fla

Flex（MXML）または Flash（FLA）のユーザーインターフェイスを構成するメインア

またはプリケーションファイル。

TelnetSocket.mxml
TelnetSocket.as

ユーザーインターフェイスロジックを提供するドキュメントクラス（Flash 専用）。

com/example/programmingas3/Telnet/Telnet.as

リモートサーバーへの接続、データの送受信と表示など、アプリケーションに Telnet
クライアント機能を提供します。

Telnet ソケットアプリケーションの概要
Flash Player 9 以降、Adobe AIR 1.0 以降
メイン TelnetSocket.mxml ファイルは、アプリケーション全体で使用するユーザーインターフェイス（UI）の作成に責任を負います。
このファイルでは、UI の他に、ユーザーを指定されたサーバーに接続するために、login() と sendCommand() の 2 つのメ
ソッドも定義しています。
次のコードは、メインアプリケーションファイル内の ActionScript を示しています。
import com.example.programmingas3.socket.Telnet;
private var telnetClient:Telnet;
private function connect():void{
telnetClient = new Telnet(serverName.text, int(portNumber.text), output);
console.title = "Connecting to " + serverName.text + ":" + portNumber.text;
console.enabled = true;}
private function sendCommand():void{
var ba:ByteArray = new ByteArray();ba.writeMultiByte(command.text + "\n", "UTF-8");telnetClient.writeBytesToSocket(ba);command.text = "";}コードの 1 行目は、Telnet クラスをカスタム com.example.programmingas.socket パッケージから読み込みます。コードの 2 行目は、Telnet クラスのインスタンス telnetClient を宣言します。このインスタンスは、後で connect() メソッドによって初期化されます。次に、connect() メソッドが宣言され、前に宣言された telnetClient 変数が初期化されます。このメソッ
ドは、ユーザーが指定した Telnet サーバーの名前とポートを引き渡すほか、ソケットサーバーからのテキスト応答の表示に使用される表示リスト上の TextArea コンポーネントへの参照を引き渡します。connect() メソッドの最後の 2 行は、Panelの title プロパティを設定し、Panel コンポーネントを有効にします。このコンポーネントを使用すると、リモートサーバーにデータを送信できます。メインアプリケーションファイル内の最後のメソッド、sendCommand() は、ユーザーのコマンド
を ByteArray オブジェクトとしてリモートサーバーに送信するために使用されます。

Telnet クラスの概要
Flash Player 9 以降、Adobe AIR 1.0 以降
Telnet クラスは、リモート Telnet サーバーへの接続と、データの送受信に責任を負います。
Telnet クラスは、次のプライベート変数を宣言します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

772

ソケット

private var serverURL:String;private var portNumber:int;
private var socket:Socket;
private var ta:TextArea;
private var state:int = 0;

最初の変数、serverURL は、ユーザーが指定した接続先サーバーアドレスを格納します。

2 番目の変数、portNumber は、Telnet サーバーが現在稼働しているポートの番号です。デフォルトでは、Telnet サービス
はポート 23 上で稼働します。
3 番目の変数 socket は、serverURL 変数と portNumber 変数によって定義されたサーバーへの接続を試みる Socket インスタンスです。

4 番目の変数、ta は、ステージ上の TextArea コンポーネントインスタンスへの参照です。このコンポーネントは、リモー
ト Telnet サーバーからの応答やエラーメッセージを表示するために使用されます。
最後の変数、state は、その Telnet クライアントがどのオプションをサポートするかを決定するために使用される数値です。
前に述べたように、Telnet クラスのコンストラクター関数は、メインアプリケーションファイル内の connect() メソッドによって呼び出されます。

Telnet コンストラクターは、server、port および output の 3 つのパラメーターを受け取ります。server パラメーターと port
パラメーターは、Telnet サーバーが稼働しているサーバーの名前とポート番号を指定します。最後のパラメーター output
は、サーバーの出力がユーザーに対して表示されるステージ上の TextArea コンポーネントインスタンスへの参照です。
public function Telnet(server:String, port:int, output:TextArea){
serverURL = server;
portNumber = port;
ta = output;
socket = new Socket();socket.addEventListener(Event.CONNECT, connectHandler);socket.addEventListener(Event.CLOSE, closeHandler);socket.addEventListener(ErrorEvent.ERROR, errorHandler);socket.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);socket.addEventListener(ProgressEvent.SOCKET_DATA, dataHandler);
Security.loadPolicyFile("http://" + serverURL + "/crossdomain.xml");try{
msg("Trying to connect to " + serverURL + ":" + portNumber + "\n");socket.connect(serverURL, portNumber);}catch (error:Error){msg(error.message + "\n");socket.close();}}ソケットへのデータの書き込み

Flash Player 9 以降、Adobe AIR 1.0 以降
ソケット接続にデータを書き込むには、Socket クラス内の任意の書き込みメソッドを呼び出します。これらの書き込みメ
ソッドには、writeBoolean()、writeByte()、writeBytes()、writeDouble() などがあります。次に、flush() メソッドを使用して、出力バッファー内のデータをフラッシュします。Telnet サーバー内では、データは writeBytes() メソッドを使用してソケッ
ト接続に書き込まれます。このメソッドは、パラメーターとしてバイト配列を受け取り、それを出力バッファーに送信します。writeBytesToSocket() メソッドは次のとおりです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

773

ソケット

public function writeBytesToSocket(ba:ByteArray):void{socket.writeBytes(ba);socket.flush();}このメソッドは、メインアプリケーションファイルの sendCommand() メソッドによって呼び出されます。
ソケットサーバーからのメッセージの表示

Flash Player 9 以降、Adobe AIR 1.0 以降
ソケットサーバーからメッセージを受け取るか、イベントが発生すると、カスタム msg() メソッドが呼び出されます。このメソッドは、ステージ上の TextArea に文字列を付加し、カスタム setScroll() メソッドを呼び出します。それによって、

TextArea コンポーネントは最下部までスクロールします。msg() メソッドは次のとおりです。
private function msg(value:String):void{ta.text += value;
setScroll();}

TextArea コンポーネントの内容を自動的にスクロールしなかった場合、サーバーからの最新の応答を参照するには、テキスト領域にあるスクロールバーを手動でドラッグする必要があります。

TextArea コンポーネントのスクロール
Flash Player 9 以降、Adobe AIR 1.0 以降
setScroll() メソッドには、TextArea コンポーネントの内容を垂直方向にスクロールする 1 行だけの ActionScript が含まれており、これにより、ユーザーは返されたテキストの最後の行を見ることができます。次のコードは、setScroll() メソッドを示しています。
public function setScroll():void{ta.verticalScrollPosition = ta.maxVerticalScrollPosition;}

このメソッドは、現在表示されている文字の一番上の行の行番号を示す verticalScrollPosition プロパティを設定し、そのプロパティを maxVerticalScrollPosition プロパティの値に設定します。

XML ソケットFlash Player 9 以降、Adobe AIR 1.0 以降
XML ソケットを使用すると、明示的に閉じるまで開いたままの、リモートサーバーへの接続を作成できます。サーバーとクライアント間で、XML などのストリングデータを交換できます。XML ソケットサーバーを使用するメリットは、クライ
アントが明示的にデータを要求する必要がないことです。サーバーは要求に対してデータを送信するために待機することな
く、すべての接続済みのクライアントにデータを送信できます。

Flash Player およびアプリケーションサンドボックスの外部にある Adobe AIR コンテンツの XML ソケット接続では、ターゲットサーバー上にソケットポリシーファイルが存在することが必要です。詳しくは、1013 ページの「Web サイトのコントロール（ポリシーファイル）」および 1031 ページの「ソケットへの接続」を参照してください。

XMLSocket クラスは、ファイアウォールをトンネリングによって自動的に通過することはできません。RTMP とは異なり、XMLSocket には HTTP トンネリング機能が備わっていないためです。HTTP トンネリングが必要な場合は、Flash
Remoting または（RTMP をサポートする）Flash Media Server の使用をお勧めします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

774

ソケット

アプリケーションセキュリティサンドボックスの外部にある、Flash Player または AIR アプリケーションのコンテンツから

XMLSocket オブジェクトを介してサーバーに接続する場合、その接続方法と接続先に関して次のような制限が適用されます。

•

アプリケーションセキュリティサンドボックスの外部にあるコンテンツの場合、XMLSocket.connect() メソッドでは、1024 以上の TCP ポート番号にしか接続できません。この制限により、XMLSocket オブジェクトと通信するサーバー
デーモンにも、1024 以上のポート番号を割り当てる必要があります。1024 未満のポート番号は、FTP（21）、Telnet（23）、SMTP（25）、HTTP（80）、POP3（110）などのシステムサービスによって使用されることが多いため、XMLSocket オブジェクトはセキュリティ上の理由からこれらのポートにアクセスできません。こうしたリソースが不適切な方法でアクセスされたり悪用されたりする可能性を小さくするために、ポート番号が制限されています。

•

アプリケーションセキュリティサンドボックスの外部にあるコンテンツの場合、XMLSocket.connect() メソッドでは、コンテンツが存在するドメイン内のコンピューターにしか接続できません（この制限は、URLLoader.load() のセキュリティ
規則と同じです）。コンテンツが存在するドメイン以外で実行されるサーバーデーモンに接続するには、特定のドメインからのアクセスを許可するクロスドメインポリシーファイルを作成します。クロスドメインポリシーファイルについて詳
しくは、1038 ページの「AIR のセキュリティ」を参照してください。

注意：XMLSocket オブジェクトと通信できるようにサーバーを設定することは、場合によっては困難が伴います。リアル
タイムのインタラクティブ機能を必要としないアプリケーションでは、XMLSocket クラスではなく URLLoader クラスを使用してください。

XMLSocket クラスの XMLSocket.connect() メソッドと XMLSocket.send() メソッドを使用すると、ソケット接続を介してサーバーとの間で XML を転送できます。XMLSocket.connect() メソッドは、Web サーバーのポートに対してソケット接続を確立します。XMLSocket.send() メソッドは、ソケット接続で指定されたサーバーに XML オブジェクトを渡します。
XMLSocket.connect() メソッドを呼び出すと、アプリケーションによってサーバーへの TCP/IP 接続が開かれ、次のいずれかのイベントが発生するまでその接続が開いたまま維持されます。

• XMLSocket クラスの XMLSocket.close() メソッドが呼び出される。
• XMLSocket オブジェクトへの参照が 1 つも存在しなくなる。
• Flash Player が終了する。
•

接続が切れる（モデムの切断など）。

XMLSocket クラスによるサーバーへの接続
Flash Player 9 以降、Adobe AIR 1.0 以降
ソケット接続を確立するには、ソケット接続の要求を受け付けて Flash Player または AIR アプリケーションに応答を送る
サーバーサイドアプリケーションを作成する必要があります。このようなサーバーサイドアプリケーションは、AIR またはJava、Python、Perl などの別のプログラミング言語で作成できます。XMLSocket クラスを使用するには、サーバーコン
ピューターは XMLSocket クラスで使用されるシンプルプロトコルに対応したデーモンを実行する必要があります。

• XML メッセージは、全二重 TCP/IP ストリームソケット接続を介して送られます。
•

個々の XML メッセージは完全な XML ドキュメントであり、ゼロ（0）バイトで終了します。

• 1 つの XMLSocket 接続を使用して送受信できる XML メッセージの数に制限はありません。
Java XML ソケットサーバーの作成および接続Flash Player 9 以降、Adobe AIR 1.0 以降
次のコードは、Java で作成した単純な XMLSocket サーバーの例です。接続を受け付け、受信したメッセージをコマンドプ
ロンプトウィンドウに表示します。デフォルトでは新しいサーバーをローカルマシンのポート番号 8080 に作成しますが、サーバーを起動する際のコマンドラインでポート番号を変更することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

775

ソケット

新しいテキストドキュメントを作成し、次のコードを入力します。
import java.io.*;import java.net.*;class SimpleServer{
private static SimpleServer server;
ServerSocket socket;
Socket incoming;
BufferedReader readerIn;
PrintStream printOut;
public static void main(String[] args){
int port = 8080;
try{port = Integer.parseInt(args[0]);}catch (ArrayIndexOutOfBoundsException e){// Catch exception and keep going.
}
server = new SimpleServer(port);}
private SimpleServer(int port){
System.out.println(">> Starting SimpleServer");try{
socket = new ServerSocket(port);
incoming = socket.accept();
readerIn = new BufferedReader(new InputStreamReader(incoming.getInputStream()));
printOut = new PrintStream(incoming.getOutputStream());
printOut.println("Enter EXIT to exit.\r");out("Enter EXIT to exit.\r");boolean done = false;
while (!done){
String str = readerIn.readLine();if (str == null){
done = true;}
else{
out("Echo: " + str + "\r");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

776

ソケット

if(str.trim().equals("EXIT")){
done = true;}}
incoming.close();}}catch (Exception e){
System.out.println(e);}}private void out(String str){
printOut.println(str);
System.out.println(str);}}

このドキュメントを SimpleServer.java という名前でハードディスクに保存し、Java コンパイラーでコンパイルして、

SimpleServer.class という Java クラスを作成します。
コマンドプロンプトを開き、java SimpleServer と入力して XMLSocket サーバーを起動します。SimpleServer.class ファイ
ルはローカルコンピューター上またはネットワーク上のどこに配置しても使用できます。Web サーバーのルートディレクト
リに置く必要はありません。
ファイルを置いた場所が Java クラスパスに含まれていないためにサーバーを起動できない場合は、「java -classpath .
SimpleServer」と入力すると、起動できることがあります。
アプリケーションから XMLSocket に接続するには、次のように XMLSocket クラスの新しいインスタンスを作成し、ホスト名とポート番号を指定して XMLSocket.connect() メソッドを呼び出します。
var xmlsock:XMLSocket = new XMLSocket();xmlsock.connect("127.0.0.1", 8080);

サーバーからデータを受信するたびに、data イベント（flash.events.DataEvent.DATA）が送出されます。
xmlsock.addEventListener(DataEvent.DATA, onData);
private function onData(event:DataEvent):void{
trace("[" + event.type + "] " + event.data);}

XMLSocket サーバーにデータを送信するには、XMLSocket.send() メソッドを使用して XML オブジェクトまたは XML ス
トリングを渡します。Flash Player によってパラメーターが String オブジェクトに変換され、その内容に終端を示すゼロ（0）バイトを付加したデータが XMLSocket サーバーに送信されます。
xmlsock.send(xmlFormattedData);

XMLSocket.send() メソッドは、データが正常に転送されたかどうかを示す値を返しません。データの送信中にエラーが発生した場合は、IOError エラーがスローされます。

XML ソケットサーバーに送信する個々のメッセージには、末尾に終端の改行文字（¥n）を付ける必要があります。
詳しくは、「XMLSocket」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

777

ソケット

サーバーソケット
Adobe AIR 2 以降
ServerSocket クラスを使用すると、他のプロセスが伝送制御プロトコル（TCP）ソケットを使用してアプリケーションに接続できます。接続しているプロセスは、ローカルコンピューターまたはネットワークに接続された別のコンピューター上で動作できます。ServerSocket オブジェクトが接続要求を受信すると、connect イベントが送出されます。このイベントを伴って送出された ServerSocketConnectEvent オブジェクトには Socket オブジェクトが含まれています。それ以降は、この Socket オブジェクトを使用して他のプロセスと通信できます。
受信ソケット接続を監視するには：

1 ServerSocket オブジェクトを作成して、ローカルポートにバインドします。
2 connect イベントに対するイベントリスナーを追加します。
3 listen() メソッドを呼び出します。
4 connect イベントに応答して、各受信接続に Socket オブジェクトを提供します。

ServerSocket オブジェクトは close() メソッドが呼び出されるまで、新しい接続を継続的に監視します。
次のコード例では、ソケットサーバーアプリケーションの作成方法を示します。この例では、ポート 8087 で受信接続を監視します。接続を受信すると、メッセージ（「Connected」という文字列）がクライアントソケットに送信されます。これ
以降、サーバーで受信したメッセージはすべてクライアントにエコーバックされます。
package{import flash.display.Sprite;
import flash.events.Event;import flash.events.IOErrorEvent;import flash.events.ProgressEvent;import flash.events.ServerSocketConnectEvent;import flash.net.ServerSocket;
import flash.net.Socket;
public class ServerSocketExample extends Sprite{
private var serverSocket:ServerSocket;
private var clientSockets:Array = new Array();
public function ServerSocketExample(){try{// Create the server socket
serverSocket = new ServerSocket();// Add the event listenerserverSocket.addEventListener( Event.CONNECT, connectHandler );serverSocket.addEventListener( Event.CLOSE, onClose );// Bind to local port 8087
serverSocket.bind( 8087, "127.0.0.1" );// Listen for connections
serverSocket.listen();trace( "Listening on " + serverSocket.localPort );}catch(e:SecurityError){
trace(e);最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

778

ソケット

}
}
public function connectHandler(event:ServerSocketConnectEvent):void{//The socket is provided by the event object
var socket:Socket = event.socket as Socket;
clientSockets.push( socket );socket.addEventListener( ProgressEvent.SOCKET_DATA, socketDataHandler);socket.addEventListener( Event.CLOSE, onClientClose );socket.addEventListener( IOErrorEvent.IO_ERROR, onIOError );//Send a connect message
socket.writeUTFBytes("Connected.");socket.flush();trace( "Sending connect message" );}public function socketDataHandler(event:ProgressEvent):void{
var socket:Socket = event.target as Socket//Read the message from the socket
var message:String = socket.readUTFBytes( socket.bytesAvailable );trace( "Received: " + message);// Echo the received message back to the sendermessage = "Echo -- " + message;
socket.writeUTFBytes( message );socket.flush();trace( "Sending: " + message );}private function onClientClose( event:Event ):void{
trace( "Connection to client closed." );//Should also remove from clientSockets array...
}
private function onIOError( errorEvent:IOErrorEvent ):void{
trace( "IOError: " + errorEvent.text );}private function onClose( event:Event ):void{
trace( "Server socket closed by OS." );}}}詳しくは、以下を参照してください。

• ServerSocket• ServerSocketConnectEvent• Socket

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

779

ソケット

UDP ソケット（AIR）
Adobe AIR 2 以降
ユニバーサルデータグラムプロトコル（UDP）は、ステートレスネットワーク接続経由でメッセージを交換する手段です。

UDP では、メッセージの配信順序またはメッセージの配信自体が保証されません。UDP を使用すると、通常、オペレー
ティングシステムのネットワークコードでは、メッセージのマーシャリング、追跡および応答にかかる時間が短縮されます。
したがって、一般的に、UDP メッセージが送信先のアプリケーションに到着するまでの遅延時間は TCP メッセージよりも短くなります。

UDP ソケット通信は、ゲームでの位置の更新や音声チャットアプリケーションの音声パケットなど、リアルタイムな情報を送信する必要がある場合に役に立ちます。このようなアプリケーションでは、ある程度のデータ損失は許容されるので、受信が保証されるよりも伝送待ち時間が短縮される方が重要です。その他の場合は、ほとんどすべての用途に TCP ソケッ
トの方が適しています。

AIR アプリケーションでは、DatagramSocket クラスおよび DatagramSocketDataEvent クラスを使用して、UDP メッ
セージを送受信できます。UDP メッセージを送受信するには：
1 DatagramSocket オブジェクトを作成します。
2 data イベントに対するイベントリスナーを追加します。
3 bind() メソッドを使用して、ソケットを IP アドレスとポートにバインドします。
4 send() メソッドを呼び出し、送信先コンピューターの IP アドレスとポートを渡してメッセージを送信します。
5 data イベントに応答してメッセージを受信します。このイベントに対して送出された DatagramSocketDataEvent オブジェクトには、メッセージデータが格納された ByteArray オブジェクトが含まれています。
次のコード例では、アプリケーションで UDP メッセージを送受信する方法を示します。この例では、文字列「Hello」を含
む単一メッセージを送信先コンピューターに送信します。また、すべての受信メッセージをトレースします。
package{import flash.display.Sprite;
import flash.events.DatagramSocketDataEvent;import flash.events.Event;import flash.net.DatagramSocket;
import flash.utils.ByteArray;public class DatagramSocketExample extends Sprite{
private var datagramSocket:DatagramSocket;//The IP and port for this computerprivate var localIP:String = "192.168.0.1";
private var localPort:int = 55555;//The IP and port for the target computerprivate var targetIP:String = "192.168.0.2";
private var targetPort:int = 55555;
public function DatagramSocketExample(){//Create the socket
datagramSocket = new DatagramSocket();datagramSocket.addEventListener( DatagramSocketDataEvent.DATA, dataReceived );//Bind the socket to the local network interface and port

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

780

ソケット

datagramSocket.bind( localPort, localIP );//Listen for incoming datagrams
datagramSocket.receive();//Create a message in a ByteArrayvar data:ByteArray = new ByteArray();
data.writeUTFBytes("Hello.");//Send the datagram message
datagramSocket.send( data, 0, 0, targetIP, targetPort);}
private function dataReceived( event:DatagramSocketDataEvent ):void{//Read the data from the datagram
trace("Received from " + event.srcAddress + ":" + event.srcPort + "> " +event.data.readUTFBytes( event.data.bytesAvailable ) );}}}UDP ソケットを使用する場合は、以下の事項を考慮してください。

•

単一パケットのデータは、送信者と受信者との間にあるすべてのネットワークノードまたはネットワークインターフェイスの最大転送ユニット（MTU）の最小値を超えることはできません。send() メソッドに渡される ByteArray オブジェ
クトのデータはすべて単一パケットとして送信されます（TCP では、サイズの大きいメッセージは複数のパケットに分割されます）。

•

送信元と送信先との間にハンドシェイクは確立されません。送信先が存在しないか、指定されたポートにアクティブなリスナーが設定されていない場合、メッセージは破棄され、エラーは通知されません。

• connect() メソッドを使用する場合、他の送信元から送信されたメッセージは無視されます。UDP 接続では、簡易的なパケットフィルタリング機能しか提供されません。ただし、送信先アドレスとポートで必ずしも監視プロセスが有効になっているわけではありません。

• UDP トラフィックによってネットワークが圧迫される可能性があります。ネットワークで輻輳が発生する場合、ネット
ワーク管理者はサービス品質の管理機能を実装する必要があります（TCP にはビルトインのトラフィック管理機能があり、ネットワークでの輻輳による影響を軽減できます）。
詳しくは、以下を参照してください。

• DatagramSocket• DatagramSocketDataEvent• ByteArray

IPv6 アドレス
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player 9.0.115.0 以降では、IPv6（インターネットプロトコルバージョン 6）がサポートされています。IPv6 は、
128 ビットのアドレスをサポートするインターネットプロトコルのバージョンです（32 ビットのアドレスをサポートする、
以前の IPv4 プロトコルの機能を向上したものです）。ネットワークインターフェイスでの IPv6 のアクティブ化が必要になる場合があります。詳細については、データをホストするオペレーティングシステムのヘルプを参照してください。
ホストしているシステムで IPv6 がサポートされる場合、次に示すように、角括弧（[]）内に URL の IPv6 数値リテラルア
ドレスを指定できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

781

ソケット

[2001:db8:ccc3:ffff:0:444d:555e:666f]

Flash Player では、以下の規則に従ってリテラル IPv6 値が返されます。

• Flash Player では IPv6 アドレスの長い形式の文字列が返されます。
• IP 値には二重コロンの省略形は含まれません。
• 16 進数は小文字のみです。
• IPv6 アドレスは角括弧（[]）で囲まれています。
••

アドレスの各 4 桁は 0 〜 4 桁の 16 進数として出力され、先頭のゼロは省略されます。
アドレスの各 4 桁がすべてゼロの場合は、以下に示す例外を除いて、二重コロンではなく、1 個のゼロとして出力されます。

Flash Player で返される IPv6 の値には、以下の例外があります。

•

不明な IPv6 アドレス（すべてゼロ）は [::] として出力されます。

•

ループバックまたは localhost の IPv6 アドレスは [::1] として出力されます。

• IPv4 のマップされた（IPv6 に変換された）アドレスは [::ffff:a.b.c.d] として出力されます。a.b.c.d は、一般的な IPv4のドット付き 10 進表記の値です。
• IPv4 と互換性のあるアドレスは [::a.b.c.d] として出力されます。a.b.c.d は、一般的な IPv4 のドット付き 10 進表記の値です。

最終更新日 2015/10/14

782

第 44 章：HTTP 通信
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe® AIR® および Adobe® Flash® Player アプリケーションでは、HTTP ベースのサーバーと通信して、データ、イメー
ジおよびビデオのロードやメッセージのやりとりを行うことができます。

関連項目

flash.net.URLLoader
flash.net.URLStream
flash.net.URLRequest
flash.net.URLRequestDefaults
flash.net.URLRequestHeader
flash.net.URLRequestMethod
flash.net.URLVariables

外部データのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 には、外部ソースからデータをロードするメカニズムが含まれます。外部ソースは、テキストファイルな
どの静的コンテンツや、Web スクリプトによって生成される動的コンテンツを提供します。データは様々な形式で書式設定されている可能性があります。そのため、ActionScript には、データのデコードおよびデータへのアクセスのための機能が用意されています。また、データを取得する際に、外部サーバーにデータを送信することもできます。

URLRequest クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
外部データをロードする API の多くは、URLRequest クラスを使用して必要なネットワーク要求のプロパティを定義します。

URLRequest プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
次の URLRequest オブジェクトのプロパティは、任意のセキュリティサンドボックス内で設定できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

783

HTTP 通信

プロパティ

contentType

説明

URL 要求で送信されるデータの MIME コンテンツタイプです。contentType が設定されていない場合、値はapplication/x-www-form-urlencoded 形式で送信されます。

data

URL 要求で送信されるデータを含むオブジェクトです。

digestAdobe® Flash® Player キャッシュに保存（または Adobe® Flash® Player キャッシュから取得）される署名付き
Adobe プラットフォームコンポーネントを一意に識別するストリングです。

methodGET や POST などの HTTP 要求メソッドです。AIR アプリケーションのセキュリティドメインで実行されているコンテンツでは、"GET" や "POST" 以外のストリングを method プロパティとして指定できます。任意の HTTP 動詞を指定できます。デフォルトのメソッドは "GET" です。1038 ページの「AIR のセキュリティ」を参照してください。

requestHeaders

HTTP 要求に追加される HTTP 要求ヘッダーの配列です。アプリケーションセキュリティサンドボックスの外部で実行されている Flash Player および AIR コンテンツには、ヘッダーの設定に一定の制限が設けられています。

url

要求される URL を指定します。

AIR には、URLRequest クラスで設定できる追加のプロパティが用意されています。これらのプロパティは、アプリケー
ションセキュリティサンドボックス内で実行されている AIR コンテンツに対してのみ使用できます。アプリケーションサン
ドボックスのコンテンツでは、（file や http などの標準スキームに加えて）新しい URL スキームを使用して URL を定義することもできます。
プロパティ

説明

followRedirects

後でリダイレクトするかどうかを指定します。リダイレクトする場合は true（デフォルト値）、リダイレクトしない
場合は false を指定します。これは AIR アプリケーションサンドボックスのみでサポートされます。

manageCookies

HTTP プロトコルスタックで、この要求の Cookie を管理するかどうかを指定します。管理する場合は true（デフォ
ルト値）、管理しない場合は false を指定します。このプロパティの設定は AIR アプリケーションサンドボックスのみ
でサポートされます。

authenticate

この要求の認証要求を処理するかどうかを指定します。処理する場合は true を指定します。このプロパティの設定
は AIR アプリケーションサンドボックスのみでサポートされます。デフォルトでは要求を認証します。そのため、サーバーが資格情報を必要とする場合、認証ダイアログボックスが表示されることがあります。
URLRequestDefaults クラスを使用して、ユーザー名やパスワードを設定することもできます。783 ページの「URLRequest のデフォルトの設定（AIR のみ）」を参照してください。

cacheResponse

この要求に対する応答データをキャッシュするかどうかを指定します。このプロパティの設定は AIR アプリケー
ションサンドボックスのみでサポートされます。デフォルトでは応答をキャッシュします（true）。

useCache

この URLRequest がデータを取得する前にローカルキャッシュを調べるかどうかを指定します。このプロパティの設定は AIR アプリケーションサンドボックスのみでサポートされます。デフォルト（true）ではローカルキャッシュバージョンを使用します。

userAgent

HTTP 要求でユーザーエージェントストリングを使用するよう指定します。

注意：HTMLLoader クラスには、HTMLLoader オブジェクトによって読み込まれたコンテンツの設定に関連するプロパ
ティがあります。詳しくは、944 ページの「HTMLLoader クラスについて」を参照してください。

URLRequest のデフォルトの設定（AIR のみ）
Adobe AIR 1.0 およびそれ以降
URLRequestDefaults クラスを使用すると、URLRequest オブジェクトに対して、アプリケーション固有のデフォルト設
定を定義できます。例えば、次のコードでは、manageCookies プロパティおよび useCache プロパティのデフォルト値を設定しています。新たに作成されるすべての URLRequest オブジェクトでは、標準のデフォルト値ではなく、指定した値がこれらのプロパティで使用されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

784

HTTP 通信

URLRequestDefaults.manageCookies = false;
URLRequestDefaults.useCache = false;

注意：URLRequestDefaults クラスは、Adobe AIR で実行されているコンテンツに対してのみ定義されます。Flash

Player ではサポートされていません。
URLRequestDefaults クラスには、setLoginCredentialsForHost() メソッドが含まれています。このメソッドを使用すると、特定のホストに対して使用するデフォルトのユーザー名とパスワードを指定できます。ホストは、このメソッドの

hostname パラメーターで指定します。ホストには、ドメイン（"www.example.com" など）またはドメインとポート番号（"www.example.com:80" など）を指定できます。"example.com"、"www.example.com"、および "sales.example.com" は、それぞれ固有のホストと見なされることに注意してください。
これらの資格情報は、サーバーから要求された場合にのみ使用されます。ユーザーがすでに認証されている場合（認証ダイ
アログボックスを使用した場合など）は、setLoginCredentialsForHost() メソッドを呼び出しても、認証されたユーザーが変更されることはありません。
次のコードでは、www.example.com に対して送信する要求で使用する、デフォルトのユーザー名とパスワードを設定します。
URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X");

URLRequestDefaults の設定は、現在のアプリケーションドメインのみに適用されます。ただし、例外的に、
setLoginCredentialsForHost() メソッドに渡される資格情報は、AIR アプリケーション内で、任意のアプリケーションドメイ
ンで実行された要求に対して使用されます。
詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の URLRequestDefaults クラスの項を参照
してください。

URI スキーム
Flash Player 9 以降、Adobe AIR 1.0 以降
標準の URI スキーム（以下参照）は、任意のセキュリティサンドボックスから実行された要求で使用できます。

http: および https:
標準のインターネット URL で使用します（Web ブラウザーで使用する場合と同じ方法）。

file:
ローカルファイルシステムに保存されているファイルの URL を指定するには、file: を使用します。次に、例を示します。
file:///c:/AIR Test/test.txt

AIR では、アプリケーションセキュリティサンドボックス内で実行されているコンテンツの URL を定義する際には、次のスキームを使用することもできます。

app:
app: は、インストールされたアプリケーションのルートディレクトリを基準とした相対的なパスを指定する場合に使用します。例えば、次のパスは、インストールされているアプリケーションのディレクトリの resources サブディレクトリを参照
しています。
app:/resources

AIR Debug Launcher（ADL）を使用して AIR アプリケーションを起動する場合、アプリケーションディレクトリはアプ
リケーション記述ファイルが含まれているディレクトリです。

File.applicationDirectory で作成した File オブジェクトの URL（および url プロパティ）では、次のように app URI スキームを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

785

HTTP 通信var dir:File = File.applicationDirectory;
dir = dir.resolvePath("assets");
trace(dir.url); // app:/assets

app-storage:
app-storage: は、アプリケーションのデータ記憶領域ディレクトリを基準とした相対的なパスを指定する場合に使用します。
AIR では、インストールされたアプリケーション（およびユーザー）ごとに、一意のアプリケーション記憶領域ディレクト
リが作成されます。このディレクトリは、そのアプリケーション固有のデータを格納するための便利な場所として使用できます。例えば、次のパスは、アプリケーション記憶領域ディレクトリの settings サブディレクトリにある prefs.xml ファイ
ルを参照しています。
app-storage:/settings/prefs.xml

File.applicationStorageDirectory メソッドで作成した File オブジェクトの URL（および url プロパティ）では、次のように
app-storage URI スキームを使用します。
var prefsFile:File = File.applicationStorageDirectory;
prefsFile = prefsFile.resolvePath("prefs.xml");trace(dir.prefsFile); // app-storage:/prefs.xml

mailto:mailto スキームは、navigateToURL() 関数に渡される URLRequest オブジェクトで使用できます。797 ページの「別のアプ
リケーションで URL を開く」を参照してください。
前述の URI スキームを使用する URLRequest オブジェクトを使用すると、多数の異なるオブジェクト（FileStream オブ
ジェクトや Sound オブジェクトなど）に対する URL 要求を定義できます。また、これらのスキームは、AIR 内で実行されている HTML コンテンツ（img タグの src 属性など）で使用することもできます。
ただし、AIR 固有の URI スキーム（app: および app-storage:）は、アプリケーションセキュリティサンドボックス内のコンテンツでしか使用できません。詳しくは、1038 ページの「AIR のセキュリティ」を参照してください。

URL 変数の設定
変数は URL ストリングに直接追加できますが、URLVariables クラスを使用して要求に必要な変数を定義する方が簡単な場合があります。

URLVariables オブジェクトにパラメーターを追加するには、3 つの方法があります。

• URLVariables コンストラクターで指定する方法• URLVariables.decode() メソッドで指定する方法• URLVariables オブジェクト自体の動的プロパティとして設定する方法
次の例は、3 つのメソッドすべてと、URLRequest オブジェクトに変数を割り当てる方法を示しています。
var urlVar:URLVariables = new URLVariables( "one=1&two=2" );urlVar.decode("amp=" + encodeURIComponent( "&" ) );urlVar.three = 3;
urlVar.amp2 = "&&";
trace(urlVar.toString()); //amp=%26&amp2=%26%26&one=1&two=2&three=3
var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" );urlRequest.data = urlVar;

URLVariables コンストラクターまたは URLVariables.decode() メソッドで変数を定義する場合は必ず、URI ストリング内の特別な意味を持つ文字を URL エンコードしてください。例えば、パラメーター名またはパラメーター値でアンパサンドを使用する場合、アンパサンドはパラメーターの区切り文字として機能するので、& を %26 に変更してアンパサンドをエンコードする必要があります。これには、トップレベルの encodeURIComponent() 関数を使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

786

HTTP 通信

URLLoader クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
URLLoader クラスを使用すると、サーバーに要求を送信したり、返された情報にアクセスしたりできます。ローカルファ
イルへのアクセスが許可されているコンテキストで、ローカルファイルシステム上のファイルにアクセスする場合にも、

URLLoader クラスを使用できます。URLLoader クラスは、指定した URL からテキスト、バイナリデータ、または URL
エンコード形式の変数をダウンロードする際に使用します。URLLoader クラスは、complete、httpStatus、ioError、open、
progress、securityError などのイベントを送出します。

ActionScript 3.0 イベント処理モデルは、LoadVars.onData、LoadVars.onHTTPStatus および LoadVars.onLoad の各イベント
ハンドラーを使用していた ActionScript 2.0 モデルとは大きく異なります。ActionScript 3.0 でのイベント処理について詳
しくは、119 ページの「イベント処理」を参照してください。
ダウンロードデータは、ダウンロードが完了するまで使用できません。ダウンロードの進捗状況（ロード済みバイト数と合計バイト数）は、progress イベントの送出をリッスンすることで監視できます。ただし、ファイルのロードの完了が早すぎると progress イベントは送出されない場合があります。ファイルが正常にダウンロードされた場合、complete イベントが送出されます。URLLoader の dataFormat プロパティを設定することにより、データをテキスト、生のバイナリデータまたはURLVariables オブジェクト形式で受信できます。
URLLoader.load() メソッドのパラメーターは、URLRequest オブジェクトを指定する request パラメーターの 1 つだけです（URLLoader クラスのコンストラクターにも、必要に応じて同じパラメーターを指定できます）。URLRequest インスタン
スには、1 件の HTTP 要求に関して、ターゲット URL、要求メソッド（GET または POST）、付加的なヘッダー情報、

MIME タイプおよびその他すべての情報が格納されます。
例えば、XML パケットをサーバーサイドスクリプトにアップロードする場合のコードは次のようになります。
var secondsUTC:Number = new Date().time;
var dataXML:XML =<clock><time>{secondsUTC}</time></clock>;var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm");
request.contentType = "text/xml";
request.data = dataXML.toXMLString();
request.method = URLRequestMethod.POST;
var loader:URLLoader = new URLLoader();loader.load(request);

上記のコードスニペットでは、サーバーに送信される XML パケットを格納する dataXML という名前の XML ドキュメントを作成します。この例では、URLRequest の contentType プロパティを "text/xml" に設定し、XML ドキュメントを

URLRequest の data プロパティに割り当てます。最後に、URLLoader オブジェクトを作成し、load() メソッドを使用してリモートスクリプトに要求を送信します。

URLStream クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
URLStream クラスを使用すると、データを受信している最中にダウンロードデータにアクセスできます。URLStream ク
ラスでは、ダウンロードの完了前にストリームを閉じることもできます。ダウンロードされたデータは、生のバイナリデー
タ形式で利用できます。

URLStream オブジェクトからデータを読み込むときは、bytesAvailable プロパティを使用して、読み取るデータが十分にあるかどうかを事前に確認します。読み取り可能なデータ量よりも多くのデータを読み取ろうとすると、EOFError 例外がス
ローされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

787

HTTP 通信

httpResponseStatus イベント（AIR）
Adobe AIR では、httpStatus イベントに加えて httpResponseStatus イベントが URLStream クラスから送出されます。
httpResponseStatus イベントは、応答データの前に送出されます。HTTPStatusEvent クラスで表わされる
httpResponseStatus イベントには、応答を返した URL を示す responseURL プロパティと、応答によって返された応答ヘッ
ダーを表す URLRequestHeader オブジェクトの配列である responseHeaders プロパティが含まれています。

外部ドキュメントからのデータのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
動的なアプリケーションを作成する場合、外部のファイルまたはサーバーサイドスクリプトからデータをロードするようにすると、アプリケーションの編集と再コンパイルを必要としない動的なアプリケーションを実現できます。例えば、「今日の一言」アプリケーションを作成する場合、サーバーサイドスクリプトで、データベースからランダムに選んだ一言を取得して 1 日 1 回テキストファイルに保存するようにします。そうすれば、アプリケーションでは静的なテキストファイルをロードするだけでよく、毎回データベースへのクエリを発行する必要はなくなります。
次のコードでは、URLRequest オブジェクトと URLLoader オブジェクトを作成し、それによって "params.txt" という外部のテキストファイルから内容をロードします。
var request:URLRequest = new URLRequest("params.txt");
var loader:URLLoader = new URLLoader();loader.load(request);

デフォルトでは、要求メソッドを定義しない場合、Flash Player および Adobe AIR では HTTP GET メソッドを使用してコンテンツがロードされます。POST メソッドで要求を送信する場合は、次のように、静的定数 URLRequestMethod.POST を使用して request.method プロパティに POST を設定します。
var request:URLRequest = new URLRequest("sendfeedback.cfm");
request.method = URLRequestMethod.POST;

実行時に読み込まれる外部ドキュメント params.txt の内容は次のようなデータです。
monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

このファイルには、monthNames および dayNames の 2 つのパラメーターが含まれています。各パラメーターの内容は、ス
トリングとして解析されるカンマ区切りリストです。このリストは String.split() メソッドを使用して分割し、配列に変換できます。
外部データファイル内の変数名には、予約語やプログラミング言語の構成要素を含めないでください。そのような変数名を使用すると、コードの解読やデバッグ作業が困難になります。
データの読み込みが完了すると complete イベントが送出され、次のように、URLLoader の data プロパティで外部ドキュメ
ントのコンテンツを使用できるようになります。
function completeHandler(event){var loader2 = event.target;
air.trace(loader2.data);}

リモートドキュメントに名前と値のペアが格納されている場合は、URLVariables クラスを使用し、読み込んだファイルのコンテンツを次のように渡すことでデータを解析できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

788

HTTP 通信private function completeHandler(event:Event):void{
var loader2:URLLoader = URLLoader(event.target);var variables:URLVariables = new URLVariables(loader2.data);
trace(variables.dayNames);}

外部ファイルから読み込んだ個々の名前 / 値ペアから、URLVariables オブジェクトの個別のプロパティが作成されます。
このコード例にある variables オブジェクトの各プロパティは、ストリングとして扱われます。名前 / 値ペアの値がアイテムのリストである場合は、次のように String.split() メソッドを呼び出すことでストリングから配列に変換できます。
var dayNameArray:Array = variables.dayNames.split(",");

外部テキストファイルから数値データをロードするには、トップレベル関数の int()、uint()、Number() などを使用して値を数値に変換します。
リモートファイルの内容を文字列としてロードして新しい URLVariables オブジェクトを作成する方法とは別に、URLLoader.dataFormat プロパティを URLLoaderDataFormat クラスの静的プロパティのいずれかに設定する方法もあります。URLLoader.dataFormat プロパティに設定できる値は次の 3 つのうちいずれかです。

• URLLoaderDataFormat.BINARY - URLLoader.data プロパティには、ByteArray オブジェクトに格納されたバイナリデー
タが含められます。

• URLLoaderDataFormat.TEXT - URLLoader.data プロパティには、String オブジェクトのテキストが含められます。
• URLLoaderDataFormat.VARIABLES - URLLoader.data プロパティには、URLVariables オブジェクトに格納された URL
エンコードされた変数が含められます。
次のコードでは URLLoader.dataFormat プロパティを URLLoaderDataFormat.VARIABLES に設定しているので、ロードした
データは自動的に解析されて URLVariables オブジェクトが作成されます。
package{import flash.display.Sprite;
import flash.events.*;
import flash.net.URLLoader;import flash.net.URLLoaderDataFormat;
import flash.net.URLRequest;
public class URLLoaderDataFormatExample extends Sprite{
public function URLLoaderDataFormatExample(){var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt");
var variables:URLLoader = new URLLoader();variables.dataFormat = URLLoaderDataFormat.VARIABLES;
variables.addEventListener(Event.COMPLETE, completeHandler);try{variables.load(request);}
catch (error:Error){
trace("Unable to load URL: " + error);}}
private function completeHandler(event:Event):void{
var loader:URLLoader = URLLoader(event.target);trace(loader.data.dayNames);}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

789

HTTP 通信

注意：URLLoader.dataFormat のデフォルト値は URLLoaderDataFormat.TEXT です。
次の例に示すように、外部ファイルから XML を読み込む方法も、URLVariables を読み込む場合と同じです。
URLRequest インスタンスと URLLoader インスタンスを作成し、それらを使用してリモート XML ドキュメントをダウンロードします。ファイルのダウンロードが完了すると、Event.COMPLETE イベントが送出され、外部ファイルの内容はXML インスタンスに変換されます。このインスタンスは XML のメソッドとプロパティを使用して解析できます。
package{import flash.display.Sprite;
import flash.errors.*;
import flash.events.*;
import flash.net.URLLoader;import flash.net.URLRequest;
public class ExternalDocs extends Sprite{
public function ExternalDocs(){
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml");var loader:URLLoader = new URLLoader();loader.addEventListener(Event.COMPLETE, completeHandler);try{
loader.load(request);}
catch (error:ArgumentError){
trace("An ArgumentError has occurred.");}catch (error:SecurityError){
trace("A SecurityError has occurred.");}}private function completeHandler(event:Event):void{
var dataXML:XML = XML(event.target.data);
trace(dataXML.toXMLString());}}}

外部スクリプトとの通信
Flash Player 9 以降、Adobe AIR 1.0 以降
URLVariables クラスを使用すると、外部データファイルからデータをロードできるだけでなく、サーバーサイドスクリプ
トに変数を送信し、サーバーの応答を処理することもできます。例えば、ゲームを作成する場合、ユーザーの得点をサーバーに送信して高得点者リストに掲載できるかどうか確認することや、ユーザーのログイン情報をサーバーに送信して検証することなどが考えられます。サーバーサイドスクリプトでは、ユーザー名とパスワードを処理してデータベースに照会し、入力されたユーザー資格情報が有効かどうかの確認を応答として返します。
次のコードでは、variables という URLVariables オブジェクトを作成し、このオブジェクトを使用して name という新しい変数を作成しています。次に、変数の送信先となるサーバーサイドスクリプトの URL を指定する URLRequest オブジェク
トを作成します。その後、URLRequest オブジェクトの method プロパティに、HTTP POST 要求で変数を送信するように

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

790

HTTP 通信

設定します。URL 要求に URLVariables オブジェクトを追加するには、前の例で作成した URLVariables オブジェクトを

URLRequest オブジェクトの data プロパティに設定します。最後に、URLLoader インスタンスを作成し、URLLoader.load() メソッドを呼び出して要求を送信します。
var variables:URLVariables = new URLVariables("name=Franklin");var request:URLRequest = new URLRequest();request.url = "http://www.[yourdomain].com/greeting.cfm";
request.method = URLRequestMethod.POST;
request.data = variables;
var loader:URLLoader = new URLLoader();loader.dataFormat = URLLoaderDataFormat.VARIABLES;
loader.addEventListener(Event.COMPLETE, completeHandler);try{
loader.load(request);}
catch (error:Error){
trace("Unable to load URL");}
function completeHandler(event:Event):void{
trace(event.target.data.welcomeMessage);}

次のコードには、前の例で使用された ColdFusion® greeting.cfm ドキュメントのコンテンツが含まれています。
<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0><cfset Form.Name = "Stranger" /></cfif><cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)#</cfoutput>

Web サービス要求
Flash Player 9 以降、Adobe AIR 1.0 以降
HTTP ベースの Web サービスにはさまざまなタイプがあります。主なタイプを以下に示します。

• REST• XML-RPC• SOAP[SOAP]
ActionScript 3 で Web サービスを利用するには、URLRequest オブジェクトを作成し、URL 変数または XML ドキュメントを使用して Web サービス呼び出しを作成し、URLLoader オブジェクトを使用してサービスに呼び出しを送信します。
Flex フレームワークには、Web サービスの利用を容易にするいくつかのクラスが用意されています。これらのクラスは、複雑な SOAP サービスにアクセスする場合に特に役立ちます。Flash Professional CS3 以降では、Flash Professional で開発したアプリケーションおよび Flash Builder で開発したアプリケーション内で、Flex のクラスを使用できます。
HTML ベースの AIR アプリケーションでは、URLRequest クラスと URLLoader クラスの組み合わせ、または Javascriptの XMLHttpRequest クラスのいずれかを使用できます。必要に応じて、Flex フレームワークの Web サービスコンポーネントを Javascript コードに公開する SWF ライブラリを作成することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

791

HTTP 通信

アプリケーションをブラウザーで実行する場合は、Web サービスをホストしているサーバーが他のドメインからのアクセスを許可するクロスドメインポリシーファイルをホストしている場合を除き、呼び出し側の SWF と同じインターネットドメ
イン内にある Web サービスのみを利用できます。クロスドメインポリシーファイルが用意されていない場合は、自分のサーバーをプロキシとして要求を中継するテクニックがよく使用されます。Adobe Blaze DS および Adobe LiveCycle では、Web サービスのプロキシをサポートしています。

AIR アプリケーションでは、アプリケーションセキュリティサンドボックスから Web サービス呼び出しを実行する場合、クロスドメインポリシーファイルは必要ありません。AIR アプリケーションのコンテンツがリモートドメインから提供されることはありません。したがって、クロスドメインポリシーファイルによって防御されている攻撃にさらされる可能性はありません。HTML ベースの AIR アプリケーションでは、アプリケーションセキュリティサンドボックス内のコンテンツからクロスドメイン XMLHttpRequest を実行できます。また、コンテンツが iframe にロードされる場合に限り、他のセキュ
リティサンドボックス内のコンテンツからクロスドメイン XMLHttpRequest を実行できます。
関連項目

1013 ページの「Web サイトのコントロール（ポリシーファイル）」Adobe BlazeDS
Adobe LiveCycle ES2REST アーキテクチャ
XML-RPC
SOAP プロトコル

REST スタイルの Web サービス要求
Flash Player 9 以降、Adobe AIR 1.0 以降
REST スタイルの Web サービスでは、HTTP メソッド（動詞）を使用して基本操作を指定し、URL 変数で操作の詳細を指定します。例えば、アイテムのデータを取得する要求では、GET 動詞と URL 変数を使用して、メソッド名とアイテム IDを指定することができます。つまり、URL ストリングは次のようになります。
http://service.example.com/?method=getItem&id=d3452

ActionScript で REST スタイルの Web サービスにアクセスするには、URLRequest、URLVariables および URLLoaderの各クラスを使用できます。AIR アプリケーション内の Javascript コードでは、XMLHttpRequest も使用できます。
REST スタイルの Web サービス呼び出しを ActionScript でプログラミングする場合、通常は次の手順を実行します。
1 URLRequest オブジェクトを作成します。
2 URLRequest で、サービス URL および HTTP メソッド（動詞）を設定します。
3 URLVariables オブジェクトを作成します。
4 サービス呼び出しのパラメーターを URLVariables オブジェクトの動的プロパティとして設定します。
5 URLRequest オブジェクトの data プロパティに URLVariables オブジェクトを割り当てます。
6 URLLoader オブジェクトを使用して、サービスに呼び出しを送信します。
7 URLLoader から送出される complete イベントを処理します。このイベントは、サービス呼び出しが完了したことを示します。URLLoader オブジェクトから送出される可能性のあるエラーイベントを監視することもお勧めします。
例えば、呼び出しパラメーターを送信元にエコーバックするテストメソッドを公開している Web サービスについて検討してみましょう。次の ActionScript コードは、サービスの呼び出しに使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

792

HTTP 通信

import flash.events.Event;import flash.events.ErrorEvent;import flash.events.IOErrorEvent;import flash.events.SecurityErrorEvent;import flash.net.URLLoader;import flash.net.URLRequest;
import flash.net.URLRequestMethod;
import flash.net.URLVariables;
private var requestor:URLLoader = new URLLoader();
public function restServiceCall():void{//Create the HTTP request object
var request:URLRequest = new URLRequest( "http://service.example.com/" );request.method = URLRequestMethod.GET;//Add the URL variables
var variables:URLVariables = new URLVariables();variables.method = "test.echo";variables.api_key = "123456ABC";
variables.message = "Able was I, ere I saw Elba.";request.data = variables;//Initiate the transaction
requestor = new URLLoader();requestor.addEventListener( Event.COMPLETE, httpRequestComplete );requestor.addEventListener( IOErrorEvent.IOERROR, httpRequestError );requestor.addEventListener( SecurityErrorEvent.SECURITY_ERROR, httpRequestError );requestor.load( request );}private function httpRequestComplete( event:Event ):void{
trace( event.target.data );}private function httpRequestError( error:ErrorEvent ):void{
trace( "An error occured: " + error.message );}AIR アプリケーション内の Javascript では、XMLHttpRequest オブジェクトを使用して同様の要求を実行できます。
<html><head><title>RESTful web service request</title><script type="text/javascript">function makeRequest(){
var requestDisplay = document.getElementById( "request" );var resultDisplay = document.getElementById( "result" );//Create a conveninece object to hold the call properties
var request = {};request.URL = "http://service.example.com/";request.method = "test.echo";request.HTTPmethod = "GET";
request.parameters = {};request.parameters.api_key = "ABCDEF123";
request.parameters.message = "Able was I ere I saw Elba.";
var requestURL = makeURL( request );xmlhttp = new XMLHttpRequest();xmlhttp.open( request.HTTPmethod, requestURL, true);
xmlhttp.onreadystatechange = function() {if (xmlhttp.readyState == 4) {最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

793

HTTP 通信

resultDisplay.innerHTML = xmlhttp.responseText;}}
xmlhttp.send(null);requestDisplay.innerHTML = requestURL;}//Convert the request object into a properly formatted URL
function makeURL( request ){var url = request.URL + "?method=" + escape( request.method );for( var property in request.parameters ){url += "&" + property + "=" + escape( request.parameters[property] );}return url;}</script></head><body onload="makeRequest()"><h1>Request:</h1><div id="request"></div><h1>Result:</h1><div id="result"></div></body></html>XML-RPC Web サービス要求
Flash Player 9 以降、Adobe AIR 1.0 以降
XML-RPC Web サービスでは、呼び出しパラメーターを URL 変数のセットとしてではなく XML 形式のドキュメントとして取得します。XML-RPC Web サービスでトランザクションを実行するには、適切にフォーマットされた XML メッセー
ジを作成し、そのメッセージを HTTP POST メソッドを使用して Web サービスに送信します。また、要求に Content-Type
ヘッダーを設定して、サーバーが要求データを XML 形式で扱えるようにする必要があります。
次の例は、REST の例で示した Web サービス呼び出しを実行する方法を示しています。ただし、今回は XML-RPC サービ
スとして呼び出します。
import flash.events.Event;import flash.events.ErrorEvent;import flash.events.IOErrorEvent;import flash.events.SecurityErrorEvent;import flash.net.URLLoader;import flash.net.URLRequest;
import flash.net.URLRequestMethod;
import flash.net.URLVariables;
public function xmlRPCRequest():void{//Create the XML-RPC document
var xmlRPC:XML = <methodCall><methodName></methodName><params><param><value><struct/></value></param></params>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

794

HTTP 通信</methodCall>;
xmlRPC.methodName = "test.echo";//Add the method parameters
var parameters:Object = new Object();
parameters.api_key = "123456ABC";
parameters.message = "Able was I, ere I saw Elba.";for( var propertyName:String in parameters ){xmlRPC..struct.member[xmlRPC..struct.member.length + 1] =<member><name>{propertyName}</name><value><string>{parameters[propertyName]}</string></value></member>;}//Create the HTTP request object
var request:URLRequest = new URLRequest( "http://service.example.com/xml-rpc/" );request.method = URLRequestMethod.POST;
request.cacheResponse = false;request.requestHeaders.push(new URLRequestHeader("Content-Type", "application/xml"));request.data = xmlRPC;//Initiate the request
requestor = new URLLoader();requestor.dataFormat = URLLoaderDataFormat.TEXT;
requestor.addEventListener( Event.COMPLETE, xmlRPCRequestComplete );requestor.addEventListener( IOErrorEvent.IO_ERROR, xmlRPCRequestError );requestor.addEventListener( SecurityErrorEvent.SECURITY_ERROR, xmlRPCRequestError );requestor.load( request );}private function xmlRPCRequestComplete( event:Event ):void{
trace( XML(event.target.data).toXMLString() );}private function xmlRPCRequestError( error:ErrorEvent ):void{
trace( "An error occurred: " + error );}AIR の WebKit では E4X シンタックスをサポートしていません。したがって、前述の例で XML ドキュメントの作成に使用したメソッドは、Javascript コードでは機能しません。代わりに、DOM メソッドを使用して XML ドキュメントを作成するか、ドキュメントをストリングとして作成し、Javascript の DOMParser クラスを使用してストリングを XML に変換する必要があります。
次の例では、DOM メソッドを使用して XML-RPC メッセージを作成し、XMLHttpRequest を使用して Web サービスト
ランザクションを実行します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

795

HTTP 通信<html><head><title>XML-RPC web service request</title><script type="text/javascript">function makeRequest(){
var requestDisplay = document.getElementById( "request" );var resultDisplay = document.getElementById( "result" );var request = {};request.URL = "http://services.example.com/xmlrpc/";
request.method = "test.echo";request.HTTPmethod = "POST";
request.parameters = {};request.parameters.api_key = "123456ABC";
request.parameters.message = "Able was I ere I saw Elba.";
var requestMessage = formatXMLRPC( request );xmlhttp = new XMLHttpRequest();xmlhttp.open( request.HTTPmethod, request.URL, true);
xmlhttp.onreadystatechange = function() {if (xmlhttp.readyState == 4) {resultDisplay.innerText = xmlhttp.responseText;}}
xmlhttp.send( requestMessage );requestDisplay.innerText = xmlToString( requestMessage.documentElement );}//Formats a request as XML-RPC document
function formatXMLRPC( request ){var xmldoc = document.implementation.createDocument( "", "", null );var root = xmldoc.createElement( "methodCall" );xmldoc.appendChild( root );var methodName = xmldoc.createElement( "methodName" );var methodString = xmldoc.createTextNode( request.method );methodName.appendChild( methodString );root.appendChild( methodName );var params = xmldoc.createElement( "params" );root.appendChild( params );var param = xmldoc.createElement( "param" );params.appendChild( param );var value = xmldoc.createElement( "value" );param.appendChild( value );var struct = xmldoc.createElement( "struct" );value.appendChild( struct );for( var property in request.parameters ){var member = xmldoc.createElement( "member" );struct.appendChild( member );var name = xmldoc.createElement( "name" );var paramName = xmldoc.createTextNode( property );name.appendChild( paramName )member.appendChild( name );最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

796

HTTP 通信var value = xmldoc.createElement( "value" );var type = xmldoc.createElement( "string" );value.appendChild( type );var paramValue = xmldoc.createTextNode( request.parameters[property] );type.appendChild( paramValue )member.appendChild( value );}return xmldoc;}//Returns a string representation of an XML nodefunction xmlToString( rootNode, indent ){if( indent == null ) indent = "";var result = indent + "<" + rootNode.tagName + ">\n";for( var i = 0; i < rootNode.childNodes.length; i++){if(rootNode.childNodes.item( i ).nodeType == Node.TEXT_NODE ){result += indent + "" + rootNode.childNodes.item( i ).textContent + "\n";}}if( rootNode.childElementCount > 0 ){result += xmlToString( rootNode.firstElementChild, indent + "" );}if( rootNode.nextElementSibling ){result += indent + "</" + rootNode.tagName + ">\n";result += xmlToString( rootNode.nextElementSibling, indent );}else{
result += indent +"</" + rootNode.tagName + ">\n";}return result;}</script></head><body onload="makeRequest()"><h1>Request:</h1><pre id="request"></pre><h1>Result:</h1><pre id="result"></pre></body></html>SOAP Web サービス要求
Flash Player 9 以降、Adobe AIR 1.0 以降
SOAP は、一般的な XML-RPC Web サービスの概念に基づいており、型指定付きデータを転送するための豊富な機能を備えた（ただし、より複雑な）手段です。SOAP Web サービスは通常、Web サービス呼び出し、データ型およびサービス
URL を指定する Web サービス記述言語ファイル（WSDL）を提供します。ActionScript 3 では SOAP を直接はサポートしていませんが、SOAP XML メッセージを「手動で」作成してサーバーにポストし、その結果を解析することができます。
ただし、非常に単純な SOAP Web サービスを除き、多くの場合で、既存の SOAP ライブラリを使用することにより、開発にかかる時間を大幅に節約できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

797

HTTP 通信

Flex フレームワークには、SOAP Web サービスにアクセスするためのライブラリが用意されています。Flash Builder では、ライブラリ rpc.swc が Flex フレームワークに含まれているので、このライブラリが自動的に Flex プロジェクトに追加されます。Flash Professional では、Flex の framework.swc および rpc.swc をプロジェクトのライブラリパスに追加すると、ActionScript で Flex のクラスにアクセスできるようになります。
関連項目

Flash Professional での Flex Web サービスコンポーネントの使用
Cristophe Coenraets：Real-time Trader Desktop for Android

別のアプリケーションで URL を開く
Flash Player 9 以降、Adobe AIR 1.0 以降
navigateToURL() 関数を使用すると、Web ブラウザーまたは他のアプリケーションで URL を開くことができます。AIR で実行されているコンテンツの場合、navigateToURL() 関数はデフォルトのシステム Web ブラウザーのページを開きます。
この関数の request パラメーターとして URLRequest オブジェクトを渡す場合は、url プロパティのみが使用されます。

navigateToURL() 関数の最初のパラメーターである navigate は URLRequest オブジェクトです（782 ページの「URLRequest クラスの使用」を参照してください）。2 番目のパラメーターである window では、ウィンドウ名を指定できます。このパラメーターはオプションです。例えば、次のコードでは、Web ページ www.adobe.com を開いています。
var url:String = "http://www.adobe.com";
var urlReq:URLRequest = new URLRequest(url);navigateToURL(urlReq);

注意：navigateToURL() 関数を使用する場合、ランタイムは GET メソッドを使用する場合と同じように、（method プロパ
ティが URLRequestMethod.POST に設定されている）POST メソッドを使用する URLRequest オブジェクトを扱います。

navigateToURL() 関数を使用する場合、使用可能な URI スキームは、navigateToURL() 関数を呼び出しているコードのセ
キュリティサンドボックスに基づいて決定されます。
一部の API では、Web ブラウザーでコンテンツを起動することができます。これらの API を AIR で使用する場合、セキュリティ上の理由のため、一部の URI スキームの使用が禁止されています。使用できないスキームは、API を使用する
コードのセキュリティサンドボックスに応じて異なります。（セキュリティサンドボックスについて詳しくは、1038 ページの「AIR のセキュリティ」を参照してください）。
アプリケーションサンドボックス（AIR のみ）

AIR アプリケーションサンドボックス内で実行しているコンテンツによって起動された URL では、どの URI スキームも使用できます。アプリケーションは URI スキームを処理するよう登録する必要があり、そうしなければリクエストをしても何も実行されません。次のスキームは多くのコンピューターやデバイスでサポートされています。

• http:• https:• file:• mailto: — AIR は、登録されているシステムの電子メールアプリケーションにこれらの要求を送ります。
• sms： — AIR は、デフォルトのテキストメッセージアプリケーションに sms： リクエストを送ります。アプリケーションを実行するシステムの規則に準拠した URL の形式を使用する必要があります。例えば、Android の URI スキームは小文字です。
navigateToURL( new URLRequest( "sms:+15555550101") );最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

798

HTTP 通信• tel： — AIR は、デフォルトの電話ダイヤルアプリケーションに tel： リクエストを送ります。アプリケーションを実行するシステムの規則に準拠した URL の形式を使用する必要があります。例えば、Android の URI スキームは小文字です。
navigateToURL( new URLRequest( "tel:5555555555") );• market： — AIR は、Android デバイスで通常サポートされている Market アプリケーションに market： リクエストを送ります。
navigateToURL( new URLRequest( "market://search?q=Adobe Flash") );navigateToURL( new URLRequest( "market://search?q=pname:com.adobe.flashplayer") );オペレーティングシステムに許可されている場所であれば、アプリケーションはカスタム URI スキームを定義および登録できます。スキームを使用する URL を作成し、AIR からアプリケーションを起動できます。
リモートサンドボックス
次のスキームを使用できます。これらのスキームの使用方法は、Web ブラウザーで使用する場合と同様です。

• http:• https:• mailto: — AIR は、登録されているシステムの電子メールアプリケーションにこれらの要求を送ります。
他の URI スキームはすべて使用できません。

Local-with-file サンドボックス
次のスキームを使用できます。これらのスキームの使用方法は、Web ブラウザーで使用する場合と同様です。

• file:• mailto: — AIR は、登録されているシステムの電子メールアプリケーションにこれらの要求を送ります。
他の URI スキームはすべて使用できません。

Local-with-networking サンドボックス
次のスキームを使用できます。これらのスキームの使用方法は、Web ブラウザーで使用する場合と同様です。

• http:• https:• mailto: — AIR は、登録されているシステムの電子メールアプリケーションにこれらの要求を送ります。
他の URI スキームはすべて使用できません。

Local-trusted サンドボックス
次のスキームを使用できます。これらのスキームの使用方法は、Web ブラウザーで使用する場合と同様です。

• file:• http:• https:• mailto: — AIR は、登録されているシステムの電子メールアプリケーションにこれらの要求を送ります。
他の URI スキームはすべて使用できません。

最終更新日 2015/10/14

799

第 45 章：Flash Player および AIR の他のインス
タンスとの通信Flash Player 9 以降、Adobe AIR 1.0 以降
LocalConnection クラスを使用すると、ブラウザーで実行される SWF コンテンツ間だけでなく、Adobe® AIR® アプリ
ケーション間でも通信できます。また、LocalConnection クラスを使用して、AIR アプリケーションとブラウザーで実行される SWF コンテンツとの間で通信することもできます。 LocalConnection クラスを使用すれば、Flash Player およびAIR の複数のインスタンス間でデータを共有し、用途の広いアプリケーションを作成できます。

LocalConnection クラスについてFlash Player 9 以降、Adobe AIR 1.0 以降
LocalConnection クラスを使用すると、fscommand() メソッドや JavaScript を使用することなく他の SWF ファイルに命令を送信できる SWF ファイルを開発できます。LocalConnection オブジェクトでの通信相手は、同じクライアントコン
ピューター上で動作する SWF ファイルに限られますが、通信相手が同じアプリケーションで動作している必要はありません。例えば、ブラウザー上で動作している SWF ファイルとプロジェクターの SWF ファイルで情報を共有しつつ、プロジェ
クターがローカルの情報を管理し、ブラウザー上の SWF ファイルがリモート接続を実行するといった分担もできます。プ
ロジェクターは、スタンドアローンアプリケーションとして実行可能な形式で保存される SWF ファイルです。つまり、実行可能ファイルの内部に埋め込まれているので、プロジェクトに Flash Player がインストールされている必要はありません。

LocalConnection オブジェクトは、異なるバージョンの ActionScript を使用した SWF 間の通信に使用できます。

• ActionScript 1.0 または 2.0 の LocalConnection オブジェクトは、ActionScript 2.0 で作成された LocalConnection
オブジェクトと通信できます。

• ActionScript 1.0 または 2.0 の LocalConnection オブジェクトは、ActionScript 3.0 で作成された LocalConnection
オブジェクトと通信できます。

Flash Player は、このバージョンが異なる LocalConnection オブジェクト間の通信を自動的に処理します。
LocalConnection オブジェクトの最も簡単な使用方法は、同じドメイン内または同じ AIR アプリケーション内のLocalConnection オブジェクト間の通信のみを許可することです。この場合、セキュリティに関する問題への対処は不要です。しかし、異なるドメイン間で通信を行う必要がある場合は、セキュリティ対策を実施する必要があります。いくつかの方法があります。詳しくは、send() メソッドの connectionName パラメーターおよび LocalConnection クラスのallowDomain() と domain のエントリに関する説明を参照してください。このクラスは、『Adobe Flash Platform 用

ActionScript 3.0 リファレンスガイド』のリストに含まれています。
LocalConnection オブジェクトを使用して 1 つの SWF ファイル内でデータを送受信することは可能ですが、お勧めしません。代わりに、共有オブジェクトを使用します。

LocalConnection オブジェクトにコールバックメソッドを追加するには、次の 3 つの方法があります。

• LocalConnection クラスのサブクラスを作成してメソッドを追加する方法• LocalConnection.client プロパティを、メソッドを実装したオブジェクトに設定する方法• LocalConnection を拡張した動的なクラスを作成し、動的にメソッドを追加する方法

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

800

Flash Player および AIR の他のインスタンスとの通信

第 1 の方法では、LocalConnection クラスを拡張することでコールバックメソッドを追加します。LocalConnection イン
スタンスに動的にメソッドを追加するのではなく、カスタムクラス内にメソッドを定義します。この方法を使用する例を次のコードに示します。
package{import flash.net.LocalConnection;
public class CustomLocalConnection extends LocalConnection{
public function CustomLocalConnection(connectionName:String){try{
connect(connectionName);}catch (error:ArgumentError){// server already created/connected}}public function onMethod(timeString:String):void{
trace("onMethod called at: " + timeString);}}}

CustomLocalConnection クラスの新しいインスタンスを作成する場合、次のコードを使用できます。
var serverLC:CustomLocalConnection;
serverLC = new CustomLocalConnection("serverName");

コールバックメソッドを追加する 2 つ目の方法は、LocalConnection.client プロパティを使用する方法です。次のコードのよ
うに、カスタムクラスを作成し、そのクラスの新しいインスタンスを client プロパティに設定します。
var lc:LocalConnection = new LocalConnection();lc.client = new CustomClient();

LocalConnection.client プロパティは、呼び出されるオブジェクトのコールバックメソッドを指定します。このコードでは、
client プロパティに CustomClient というカスタムクラスの新しいインスタンスを設定しています。client プロパティのデ
フォルト値は、現在の LocalConnection インスタンスです。例えば、あるウィンドウ内のボタンが別のウィンドウの表示を切り替えるアプリケーションのように、同じメソッドのセットが設定されていながら動作の異なる 2 つのデータハンド
ラーがある場合、client プロパティを使用できます。

CustomClient クラスを作成するには、次のようなコードを使用します。
package{public class CustomClient extends Object{
public function onMethod(timeString:String):void{
trace("onMethod called at: " + timeString);}}}

コールバックメソッドを追加する 3 つ目の方法は、ダイナミッククラスを作成してメソッドを動的に関連付ける方法です。
この方法は次のコードが示すように、ActionScript の以前のバージョンで LocalConnection クラスを使用する方法と非常によく似ています。
import flash.net.LocalConnection;
dynamic class DynamicLocalConnection extends LocalConnection {}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

801

Flash Player および AIR の他のインスタンスとの通信

コールバックメソッドは、次のコードを使用して、このクラスに動的に追加できます。
var connection:DynamicLocalConnection = new DynamicLocalConnection();connection.onMethod = this.onMethod;// Add your code here.
public function onMethod(timeString:String):void{
trace("onMethod called at: " + timeString);}

以前のコールバックメソッドの追加方法はコードの移植があまり簡単ではないため、お勧めしません。また、この方法でローカル接続を作成すると、ダイナミックプロパティへのアクセスは sealed プロパティにアクセスするより大幅に時間を要するため、パフォーマンスの問題が起きるおそれがあります。

isPerUser プロパティ
isPerUser プロパティは、複数のユーザーが Mac コンピューターにログインしているときに発生する競合を解決するために、Flash Player （10.0.32）と AIR （1.5.2）に追加されました。他のオペレーティングシステムでは、ローカル接続は常に個別のユーザーが対象なので、このプロパティは無視されます。新規に作成するコードでは、isPerUser プロパティを true に設定することが必要です。ただし、後方互換性のために、デフォルト値は現在 false です。このデフォルト値は、今後のバー
ジョンのランタイムで変更される可能性があります。

2 つのアプリケーション間でのメッセージ送信Flash Player 9 以降、Adobe AIR 1.0 以降
LocalConnection クラスを使用すると、異なる AIR アプリケーション間でも、ブラウザーで実行される異なる Adobe®
Flash® Player（SWF）アプリケーション間でも通信できます。また、LocalConnection クラスを使用して、AIR アプリ
ケーションとブラウザーで実行される SWF アプリケーションとの間で通信することもできます。
例えば、1 つの Web ページ上に複数の Flash Player インスタンスがある場合や、ポップアップウィンドウ内の Flash
Player インスタンスから提供されるデータを別の Flash Player インスタンスで取得する場合などが考えられます。
次のコードでは、サーバーとして動作し、他のアプリケーションから受信する LocalConnection 呼び出しを受け付ける

LocalConnection オブジェクトを定義します。
package{import flash.net.LocalConnection;
import flash.display.Sprite;
public class ServerLC extends Sprite{
public function ServerLC(){var lc:LocalConnection = new LocalConnection();lc.client = new CustomClient1();try{lc.connect("conn1");}catch (error:Error){
trace("error:: already connected");}}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

802

Flash Player および AIR の他のインスタンスとの通信

このコードでは、まず、lc という LocalConnection オブジェクトを作成し、client プロパティを clientObject オブジェクトに設定します。この LocalConnection インスタンスのメソッドを別のアプリケーションが呼び出すと、ランタイムはclientObject オブジェクトでそのメソッドを探します。
指定した名前の接続が既に存在する場合は Argument Error 例外がスローされます。この例外は、オブジェクトが接続済みであるために接続の試行が失敗したことを示します。

Flash Player インスタンスがこの SWF ファイルに接続し、指定されたローカル接続に対してメソッドを呼び出そうとすると、そのたびに、client プロパティで指定されたクラス（CustomClient1 クラス）に対してリクエストが送信されます。
package{import flash.events.*;
import flash.system.fscommand;
import flash.utils.Timer;
public class CustomClient1 extends Object{
public function doMessage(value:String = ""):void{
trace(value);}
public function doQuit():void{
trace("quitting in 5 seconds");
this.close();var quitTimer:Timer = new Timer(5000, 1);
quitTimer.addEventListener(TimerEvent.TIMER, closeHandler);}public function closeHandler(event:TimerEvent):void{
fscommand("quit");}}}

LocalConnection サーバーを作成するには、LocalConnection.connect() メソッドを呼び出して一意の名前を指定します。指定した名前の接続が既に存在する場合は ArgumentError エラーが発生します。このエラーは、オブジェクトが接続済みであるために接続の試行が失敗したことを示します。
次のコードでは、conn1 という名前を指定して LocalConnection を作成する方法を示します。
try{
connection.connect("conn1");}catch (error:ArgumentError){
trace("Error! Server already exists\n");}

第 1 のアプリケーションに第 2 のアプリケーションから接続するには、まず、送信側 LocalConnection オブジェクト内でLocalConnection オブジェクトを作成し、次に、接続名と実行するメソッドの名前を指定して LocalConnection.send() メ
ソッドを呼び出す必要があります。例えば、前述の例で作成した LocalConnection オブジェクトに doQuit メソッドを送信するには、次のコードを使用します。
sendingConnection.send("conn1", "doQuit");

このコードでは、既存の LocalConnection オブジェクトに接続名 conn1 で接続し、リモートアプリケーションのdoMessage() メソッドを呼び出しています。リモートアプリケーションにパラメーターを送信する場合は、次のコードに示すように、send() メソッドに対するメソッド名の指定の後に追加パラメーターを指定します。
sendingConnection.send("conn1", "doMessage", "Hello world");

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

803

Flash Player および AIR の他のインスタンスとの通信

異なるドメインのコンテンツおよび AIR アプリケーションへの接続
Flash Player 9 以降、Adobe AIR 1.0 以降
特定のドメインからの通信のみ許可するには、LocalConnection クラスの allowDomain() メソッドまたは

allowInsecureDomain() メソッドを呼び出し、この LocalConnection オブジェクトへのアクセスを許可するドメインのリストを渡し、許可するドメインの 1 つ以上の名前を渡します。

ActionScript の以前のバージョンでは、開発者が LocalConnection.allowDomain() およびLocalConnection.allowInsecureDomain() をコールバックメソッドとして実装する必要があり、また、いずれも戻り値としてBoolean 値を返すようにする必要がありました。ActionScript 3.0 では、LocalConnection.allowDomain() およびLocalConnection.allowInsecureDomain() は両方ともビルトインメソッドとなりました。開発者はアクセスを許可するドメイ
ン名を渡して、これらのメソッドを Security.allowDomain() や Security.allowInsecureDomain() と同様に呼び出すだけで済みます。
Flash Player 8 から、ローカル SWF ファイルに関するセキュリティ制限が導入されました。これにより、インターネットへのアクセスを許可された SWF ファイルは、ローカルファイルシステムにはアクセスできません。localhost を指定すると、どのローカル SWF ファイルもこの SWF ファイルにアクセスできます。セキュリティ Sandbox 内から、呼び出し元コードがアクセスを認められていない SWF ファイルに対して LocalConnection.send() メソッドで接続しようとすると、securityError
event（SecurityErrorEvent.SECURITY_ERROR）が送出されます。このエラーを回避するには、受信側のLocalConnection.allowDomain() メソッドで、呼び出し元のドメインを指定してください。
LocalConnection.allowDomain() メソッドおよび LocalConnection.allowInsecureDomain() メソッドに渡すことができる特別な値として、* と localhost の 2 つがあります。アスタリスク値（*） は、すべてのドメインにアクセスを許可することを示します。localhost というストリングは、ローカル（ただし、アプリケーションリソースディレクトリ外）にインストールされているコンテンツから該当のアプリケーションへの呼び出しを許可することを示します。

LocalConnection.send() メソッドで、呼び出し元コードでのアクセスが認められていないアプリケーションにセキュリティサ
ンドボックスから通信しようとすると、securityError イベント（SecurityErrorEvent.SECURITY_ERROR）が送出されます。
このエラーを回避するには、受信側の LocalConnection.allowDomain() メソッドで、呼び出し元のドメインを指定してください。
同じドメイン内のコンテンツ間のみで通信を行う場合は、connectionName パラメーターに対して、先頭がアンダースコア（_）以外で、かつドメイン名を含まない名前を指定します（例：myDomain:connectionName）。また、それと同じストリン
グを LocalConnection.connect(connectionName) コマンドでも使用します。
異なるドメインにあるコンテンツ間での通信を実装する場合は、connectionName パラメーターに対して、アンダースコアで始まる名前を指定します。このアンダースコアを付けると、受信側 LocalConnection オブジェクトを含むコンテンツのドメイン間におけるポータビリティが高まります。考えられる 2 つの状況を次に示します。

• connectionName のストリングがアンダースコア（_）で始まっていない場合、myDomain:connectionName のように、スーパードメイン名とコロンの接頭辞がランタイムによって追加されます。この処理には他のドメインにある同じ名前の接続との競合を回避する意味がありますが、その代わり、このスーパードメインをすべての送信側 LocalConnection オ
ブジェクトで指定する必要があります（例：myDomain:connectionName）。受信側 LocalConnection オブジェクトを含んだ HTML ファイルまたは SWF ファイルを別のドメインに移動すると、ランタイムによって追加される接頭辞は、
スーパードメインの変更を反映して変化します（例：anotherDomain:connectionName）。したがって、新しいスーパードメインを参照するようにすべての送信側 LocalConnection オブジェクトを手動で編集する必要が生じます。

• connectionName のストリングが、_connectionName のようにアンダースコアで始まっている場合、ストリングに接頭辞は追加されません。つまり、受信側と送信側の LocalConnection オブジェクトは、connectionName にまったく同じス
トリングを使用します。すべてのドメインからの接続を受け付けることを受信側オブジェクトがLocalConnection.allowDomain() によって指定していれば、受信側 LocalConnection オブジェクトを含んだ HTML ファ

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

804

Flash Player および AIR の他のインスタンスとの通信

イルまたは SWF ファイルを別のドメインに移動した場合でも、送信側 LocalConnection オブジェクトに変更を加える
必要はありません。

connectionName でアンダースコア付きの名前を使用する場合の欠点の 1 つは、2 つのアプリケーションの両方が同じ
connectionName を使用して接続しようとする場合など、競合の可能性があることです。もう 1 つの欠点は、セキュリ
ティ関連です。アンダースコアシンタックスを使用する接続名では、リッスンしているアプリケーションのドメインは識別されません。これらの理由から、ドメイン修飾名の使用が推奨されます。

Adobe AIR
AIR アプリケーションセキュリティサンドボックス内で実行するコンテンツ（AIR アプリケーションでインストールされたコンテンツ）と通信するには、接続名に AIR アプリケーションを識別するスーパードメイン名を接頭辞として付加する必要があります。スーパードメインのストリングは、app# で始まり、アプリケーション ID、ドット（.）文字、発行者 ID （定義されている場合）と続きます。例えば、アプリケーション ID が com.example.air.MyApp で、発行者 ID はないアプリケー
ションに対して、connectionName パラメーターで使用する適切なスーパードメインは、「app#com.example.air.MyApp」です。このようにして、接続名のベース部分が appConnection の場合、connectionName パラメーターで使用されるストリン
グ全体は、「app#com.example.air.MyApp:appConnection」となります。アプリケーションに発行者 ID がある場合は、そのID もスーパードメインのストリングに組み込んで、「app#com.example.air.MyApp.B146A943FBD637B68C334022D304CEA226D129B4.1」などとする必要があります。
ローカル接続を通じて別の AIR アプリケーションからユーザーのアプリケーションに通信できるようにする場合は、

LocalConnection オブジェクトの allowDomain() を呼び出し、ローカル接続のドメイン名を渡す必要があります。AIR アプ
リケーションでは、このドメイン名は接続ストリングと同じ要領でアプリケーション ID と発行者 ID により構成されます。
例えば、送信側 AIR アプリケーションのアプリケーション ID が com.example.air.FriendlyApp で、発行者 ID が214649436BD677B62C33D02233043EA236D13934.1 である場合、このアプリケーションから接続するときに使用するドメイ
ンストリングは「app#com.example.air.FriendlyApp.214649436BD677B62C33D02233043EA236D13934.1」になります。
（AIR

1.5.3 の時点では、すべての AIR アプリケーションに発行者 ID が付いているわけではありません）。

最終更新日 2015/10/14

805

第 46 章：AIR のネイティブプロセスとの通信
Adobe AIR 2 以降
Adobe AIR 2 では、AIR アプリケーションの実行や他のネイティブプロセスとの通信を、コマンドライン経由で行うことができます。例えば、AIR アプリケーションでは、プロセスを実行し、標準の入出力ストリームを使用してそのプロセスと通信できます。
ネイティブプロセスと通信するには、ネイティブインストーラーでインストールされるように AIR アプリケーションをパッケージ化します。ネイティブインストーラーのファイルタイプは、そのインストーラーが作成されたオペレーティングシス
テムに固有のものです。

• Mac OS では DMG ファイルです。
• Windows では EXE ファイルです。
• Linux では RPM または DEB パッケージです。
これらのアプリケーションは、拡張デスクトッププロファイルアプリケーションとして知られています。ネイティブインス
トーラーを作成するには、ADT を使用して -package コマンドを呼び出すときに、-target native オプションを指定します。
関連項目

flash.filesystem.File.openWithDefaultApplication()
flash.desktop.NativeProcess

ネイティブプロセス通信の概要
Adobe AIR 2 以降
拡張デスクトッププロファイルの AIR アプリケーションでは、コマンドラインでファイルを呼び出すときと同様にファイルを実行できます。また、ネイティブプロセスの標準ストリームと通信することができます。標準ストリームには、標準入力
ストリーム（stdin）、出力ストリーム（stdout）、標準エラーストリーム（stderr）が含まれます。
注意：拡張デスクトッププロファイルのアプリケーションでは、File.openWithDefaultApplication() メソッドを使用してファイルおよびアプリケーションを起動することもできます。ただし、このメソッドを使用しても、AIR アプリケーションは標
準ストリームにアクセスできません。詳しくは、656 ページの「デフォルトのシステムアプリケーションでファイルを開く」
を参照してください。
次のコードサンプルは、アプリケーションディレクトリで test.exe アプリケーションを起動する方法を示しています。アプ
リケーションは、引数 "hello" をコマンドライン引数として渡し、プロセスの標準出力ストリームにイベントリスナーを追加します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

806

AIR のネイティブプロセスとの通信

var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;var processArgs:Vector.<String> = new Vector.<String>();processArgs.push("hello");nativeProcessStartupInfo.arguments = processArgs;
process = new NativeProcess();
process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, onOutputData);
process.start(nativeProcessStartupInfo);
public function onOutputData(event:ProgressEvent):void{
var stdOut:ByteArray = process.standardOutput;
var data:String = stdOut.readUTFBytes(process.standardOutput.bytesAvailable);trace("Got: ", data);}

ネイティブプロセスの起動および終了
Adobe AIR 2 以降
ネイティブプロセスを起動するには、次の処理を行うように NativeProcessInfo オブジェクトを設定します。

•

起動するファイルを参照する•

起動時にプロセスに渡すコマンドライン引数を保存する（オプション）•

プロセスの作業ディレクトリを設定する（オプション）

ネイティブプロセスを起動するには、NativeProcessInfo オブジェクトを、NativeProcess オブジェクトの start() メソッドのパラメーターとして渡します。
例えば、次のコードは、アプリケーションディレクトリで test.exe アプリケーションを起動する方法を示しています。アプ
リケーションは引数 "hello" を渡し、ユーザーのドキュメントディレクトリを作業ディレクトリとして設定します。
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;var processArgs:Vector.<String> = new Vector.<String>();processArgs[0] = "hello";
nativeProcessStartupInfo.arguments = processArgs;
nativeProcessStartupInfo.workingDirectory = File.documentsDirectory;
process = new NativeProcess();
process.start(nativeProcessStartupInfo);

プロセスを終了するには、NativeProcess オブジェクトの exit() メソッドを呼び出します。
インストールされたアプリケーションでファイルを実行可能にする場合には、アプリケーションをパッケージ化するときに、対象のファイルシステムでそのファイルが実行可能であることを確認してください（Mac と Linux では、必要に応じて、

chmod を使用して実行可能フラグを設定できます）。

ネイティブプロセスとの通信
Adobe AIR 2 以降
AIR アプリケーションでは、ネイティブプロセスを起動したら、プロセスの標準入力ストリーム、標準出力ストリーム、および標準エラーストリームと通信できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

807

AIR のネイティブプロセスとの通信

ストリームのデータの読み取りおよび書き込みは、NativeProcess オブジェクトの次のプロパティを使用して行います。

• standardInput — 標準入力ストリームデータへのアクセスを含みます。
• standardOutput — 標準出力ストリームデータへのアクセスを含みます。
• standardError — 標準エラーストリームデータへのアクセスを含みます。
標準入力ストリームへの書き込み
標準入力ストリームにデータを書き込むには、NativeProcess オブジェクトの standardInput プロパティの書き込みメソッド
を使用します。AIR アプリケーションがプロセスにデータを書き込むと、NativeProcess オブジェクトは

standardInputProgress イベントを送出します。
標準入力ストリームへの書き込みでエラーが発生すると、NativeProcess オブジェクトは ioErrorStandardInput イベントを送出します。
入力ストリームを終了するには、NativeProcess オブジェクトの closeInput() メソッドを呼び出します。入力ストリームが終了するとき、NativeProcess オブジェクトは standardInputClose イベントを送出します。
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;process = new NativeProcess();
process.start(nativeProcessStartupInfo);
process.standardInput.writeUTF("foo");if(process.running){process.closeInput();}

標準出力ストリームからの読み取り
標準出力ストリームからデータを読み取るには、このプロパティの読み取りメソッドを使用します。AIR アプリケーション
がプロセスから出力ストリームデータを受信すると、NativeProcess オブジェクトは standardOutputData イベントを送出します。
標準出力ストリームへの書き込みでエラーが発生すると、NativeProcess オブジェクトは standardOutputError イベントを送出します。
出力ストリームが終了するとき、NativeProcess オブジェクトは standardOutputClose イベントを送出します。
標準データストリームからデータを読み取るときは、生成時にデータを読み取ってください。言い換えると、standardOutputData イベントのイベントリスナーを追加します。standardOutputData イベントリスナーで、NativeProcess
オブジェクトの standard utput プロパティからデータを読み取ります。standardOutputClose イベントまたは exit イベントがすべてのデータを読み取るのを待たないでください。ネイティブプロセスが生成するときにデータを読み取らないと、バッ
ファーがいっぱいになるか、データが失われる可能性があります。バッファーがいっぱいになると、さらにデータを書き込もうとしたときにネイティブプロセスがストールすることがあります。ただし、standardOutputData イベントのイベントリスナーを登録しない場合、バッファーはいっぱいにならず、プロセスはストールしません。この場合、データにアクセスすることはできません。
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;process = new NativeProcess();
process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, dataHandler);process.start(nativeProcessStartupInfo);
var bytes:ByteArray = new ByteArray();function dataHandler(event:ProgressEvent):void{bytes.writeBytes(process.standardOutput.readBytes(process.standardOutput.bytesAvailable);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

808

AIR のネイティブプロセスとの通信

標準エラーストリームからの読み取り
標準エラーストリームからデータを読み取るには、このプロパティの読み取りメソッドを使用します。AIR アプリケーショ
ンがプロセスからエラーストリームデータを読み取ると、NativeProcess オブジェクトは standardErrorData イベントを送出します。
標準エラーストリームへの書き込みでエラーが発生すると、NativeProcess オブジェクトは standardErrorIoError イベントを送出します。
エラーストリームが終了するとき、NativeProcess オブジェクトは standardErrorClose イベントを送出します。
標準エラーストリームからデータを読み取るときは、生成時にデータを読み取ります。言い換えると、standardErrorData イ
ベントのイベントリスナーを追加します。standardErrorData イベントリスナーで、NativeProcess オブジェクトのstandardError プロパティからデータを読み取ります。standardErrorClose イベントまたは exit イベントがすべてのデータを読み取るのを待たないでください。ネイティブプロセスが生成するときにデータを読み取らないと、バッファーがいっぱいになるか、データが失われる可能性があります。バッファーがいっぱいになると、さらにデータを書き込もうとしたときにネイティブプロセスがストールすることがあります。ただし、standardOutputData イベントのイベントリスナーを登録しない場合、バッファーはいっぱいにならず、プロセスはストールしません。この場合、データにアクセスすることはできません。
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;process = new NativeProcess();
process.addEventListener(ProgressEvent.STANDARD_ERROR_DATA, errorDataHandler);process.start(nativeProcessStartupInfo);
var errorBytes:ByteArray = new ByteArray();function errorDataHandler(event:ProgressEvent):void{bytes.writeBytes(process.standardError.readBytes(process.standardError.bytesAvailable);}

ネイティブプロセス通信のセキュリティ上の考慮事項
Adobe AIR 2 以降
ネイティブプロセス API は、ユーザーのシステム上で任意の実行可能ファイルを実行できます。コマンドの構築時および実行時には、十分に注意を払ってください。実行されるコマンドが一部でも外部ソースから発行されている場合には、そのコ
マンドを実行しても安全であるかどうかを慎重に検証してください。同様に、AIR アプリケーションにおいても、実行中のプロセスに渡されるデータを検証する必要があります。
ただし、入力を検証することは難しい場合があります。このような問題を回避するには、特定の API を含むネイティブアプ
リケーション（Windows 上の EXE ファイルなど）を作成することが最適です。これらの API は、アプリケーションによって定義されるコマンドのみを処理する必要があります。例えば、アプリケーションは標準入力ストリームを介して限られたセットのインストラクションのみを受け付けることができます。

Windows 上の AIR は、ユーザーが .bat ファイルを直接実行することを許可しません。コマンドインタープリターアプリ
ケーション（cmd.exe）は、Windows の .bat ファイルを実行します。.bat ファイルを呼び出すとき、このコマンドアプリ
ケーションは、コマンドに渡される引数を、起動する追加のアプリケーションとして解釈することができます。引数のストリングに悪質な意図で不要な文字が挿入されている場合、有害または安全ではないアプリケーションを cmd.exe が実行する
おそれがあります。例えば、妥当なデータ検証が行われない場合、AIR アプリケーションが myBat.bat myArguments
c:/evil.exe を呼び出す可能性があります。このコマンドアプリケーションは、バッチファイルを実行するときに、一緒に
evil.exe アプリケーションを起動することになります。

最終更新日 2015/10/14

809

第 47 章：External API の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 外部 API（flash.external.ExternalInterface）を使用すると、Adobe Flash Player が実行されるコンテナ
アプリケーションと ActionScript の間で直接通信できます。HTML ページで SWF ドキュメントと JavaScript の間のやり取りを作成するには、ExternalInterface API を使用します。
HTML ページで外部 API を使用すると、コンテナアプリケーションとやり取りしたり、ActionScript と JavaScript の間でデータの受け渡しを行ったりすることができます。
一般的な External API タスクの一部は次のとおりです。

•

コンテナアプリケーションに関する情報の取得• ActionScript の使用による、ブラウザーまたは AIR デスクトップアプリケーションに表示された Web ページ内のコードの呼び出し• Web ページからの ActionScript コードの呼び出し• Web ページからの ActionScript コードの呼び出しを簡易化するプロキシの作成
注意：外部インターフェイスに関するこの説明は、SWF 内の ActionScript と、SWF をロードする Flash Player またはインスタンスへの参照が含まれるコンテナアプリケーションの間の通信のみを対象としています。アプリケーション内でのその他の Flash Player の使用は、本マニュアルの範囲外です。Flash Player は、ブラウザーのプラグインまたはプロジェク
ター（スタンドアローンアプリケーション）として使用することを目的としています。それ以外の使用法については、サポートが制限される場合があります。

AIR での External API の使用
AIR アプリケーションには外部コンテナがないので、この外部インターフェイスは通常は該当せず、必要もありません。
AIR アプリケーションで SWF ファイルを直接ロードする場合、アプリケーションコードは SWF で ActionScript コードと直接通信できます（セキュリティサンドボックスの制限が適用されます）。
ただし、AIR アプリケーションが HTMLLoader オブジェクト（または Flex の HTML コンポーネント）の HTML ページを使用して SWF ファイルをロードするときは、HTMLLoader オブジェクトは外部コンテナとして機能します。したがって、外部インターフェイスを使用して、ロードされた SWF で ActionScript コードと、HTMLLoader でロードされたHTML ページの JavaScript コードの間で通信することができます。

External API 使用の基本
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe® Flash® Professional を使用して SWF プロジェクターを作成する際など、SWF ファイルが単独で実行されることもありますが、ほとんどの場合、SWF アプリケーションは他のアプリケーションの埋め込みエレメントとして実行されます。
通常、SWF が含まれているコンテナは HTML ファイルですが、稀にデスクトップアプリケーションのユーザーインター
フェイスの全部または一部として SWF ファイルが使用されることがあります。
より高度なアプリケーションで作業するようになると、SWF ファイルとコンテナアプリケーションの間の通信設定が必要になるでしょう。例えば、一般的には、Web ページで HTML 形式でテキストなどの情報を表示させ、SWF ファイルでチャートやビデオなどの動的かつ視覚的なコンテンツを表示させます。この場合、Web ページ上のボタンを押すと SWF

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

810

External API の使用

ファイルも変更されるようにしたいと思うかもしれません。ActionScript に含まれる External API というメカニズムにより、SWF ファイル内の ActionScript とコンテナアプリケーションに含まれるその他のコード間におけるこのような通信が容易になります。
重要な概念と用語
次の参照リストに、この機能に関連のある重要な用語について説明します。
コンテナアプリケーション Web ブラウザー内の HTML ページが Flash Player コンテンツを含む場合や、Web ページ内にSWF を読み込む AIR アプリケーションのように、SWF ファイルを実行する Flash Player を含むアプリケーション。
プロジェクター SWF コンテンツと埋め込み Flash Player を含む、実行可能ファイル。Flash Professional またはスタンドアローン Flash Player を使用して、プロジェクター ファイルを作成できます。プロジェクターは通常、SWF ファイルを

CD-ROM で配布する場合や、ダウンロードサイズが問題にならず、ユーザーのコンピューターに Flash Player がインストールされているかどうかにかかわらず確実に SWF ファイルが実行されるようにしたいと SWF 作成者が考えているような状況で使用されます。
プロキシ あるアプリケーション（「外部アプリケーション」）のコードを他のアプリケーション（「呼び出しアプリケーション」）に代わって呼び出す仲介者となるアプリケーションまたはコード。呼び出しアプリケーションに値を返します。プロキ
シは次のような様々な目的で使用されます。

•

呼び出しアプリケーションにおけるネイティブ関数の呼び出しを、外部アプリケーションで理解可能なフォーマットに変換することにより、外部関数の呼び出しプロセスを簡単にする。

•

呼び出し元と外部アプリケーションとの直接通信を防止する、セキュリティおよびその他の制約に対処する。

直列化 オブジェクトやデータ値を、2 つのプログラミングシステム間（インターネット上、1 台のコンピューターで実行中の 2 つの異なるアプリケーション間など）のメッセージにおいて値を受け渡しできるフォーマットに変換すること。
コード例の使用
この章のコードの多くは、デモンストレーション目的の小さなコードであり、完全な実用例または値をチェックするコード
ではありません。External API を使用するには ActionScript コードおよびコンテナアプリケーション内のコードを作成する必要があることが定義されているので、サンプルをテストするには、コンテナ（SWF を含んだ Web ページなど）を作成
して、コードリストを使用してコンテナとやり取りする必要があります。

ActionScript と JavaScript 間の通信の例をテストするには :1 Flash Professional を使用して新規のドキュメントを作成し、コンピューターに保存します。
2 メインメニューからファイル／パブリッシュ設定を選択します。
3 パブリッシュ設定ダイアログボックスの「フォーマット」タブで、「Flash」および「HTML」チェックボックスが選択されていることを確認します。

4 「パブリッシュ」ボタンをクリックします。同じフォルダーに、ドキュメントを保存したときと同じ名前で SWF ファイ
ルと HTML ファイルが生成されます。「OK」をクリックして、パブリッシュ設定ダイアログボックスを閉じます。

5 「HTML」チェックボックスを選択解除します。これにより HTML ページが生成されるので、その HTML ページを変更して、適切な JavaScript コードを追加します。「HTML」チェックボックスを選択解除すると、HTML ページを変更
してから SWF ファイルをパブリッシュするときに、Flash により変更が上書きされることはありません。

6 「OK」をクリックして、パブリッシュ設定ダイアログボックスを閉じます。
7 HTML またはテキストエディターアプリケーションで、SWF ファイルをパブリッシュしたときに Flash で作成されたHTML ファイルを開きます。HTML ソースコードで script タグの開始タグと終了タグを追加し、サンプルコードリスト
からそのタグを JavaScript コードにコピーします。
<script>// add the sample JavaScript code here</script>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

811

External API の使用

8 HTML ファイルを保存して、Flash に戻ります。
9 タイムラインのフレーム 1 のキーフレームを選択して、アクションパネルを開きます。
10 ActionScript コードリストを スクリプトペインにコピーします。
11 メインメニューからファイル／パブリッシュを選択し、変更内容を使用して SWF ファイルを更新します。
12 Web ブラウザーで、編集した HTML ページを開いてページを表示し、ActionScript と HTML ページ間の通信をテストします。

ActionScript と ActiveX コンテナ間の通信の例をテストするには :1 Flash Professional を使用して新規のドキュメントを作成し、コンピューターに保存します。コンテナアプリケーション
が SWF ファイルを検索する宛先のフォルダーに保存することをお勧めします。
2 メインメニューからファイル／パブリッシュ設定を選択します。
3 パブリッシュ設定ダイアログボックスの「フォーマット」タブで、「Flash」チェックボックスだけが選択されていることを確認します。

4 「Flash」チェックボックスの横の「ファイル」フィールドで、フォルダーアイコンをクリックして、SWF ファイルがパブリッシュされるフォルダーを選択します。SWF ファイルの場所を設定することにより、ドキュメントを 1 つのフォル
ダーで管理しながら、パブリッシュした SWF ファイルを別のフォルダー（コンテナアプリケーションのソースコードが含まれるフォルダーなど）で管理できます。

5 タイムラインのフレーム 1 のキーフレームを選択して、アクションパネルを開きます。
6 サンプルの ActionScript コードをスクリプトペインにコピーします。
7 メインメニューからファイル／パブリッシュを選択して、SWF ファイルを再びパブリッシュします。
8 ActionScript とコンテナアプリケーション間の通信をテストするためのコンテナアプリケーションを作成して実行します。
外部 API を使用して HTML ページと通信するすべての例については、次のトピックを参照してください。

• 816 ページの「External API の例：Web ブラウザーでの ActionScript と JavaScript との通信」
これらの例には完全なコードが含まれており、その中には、External API を使用してコードを作成するときに使用する、ActionScript とコンテナエラーチェックコードも含まれています。External API を使用する別の完全な例については、
ActionScript 3.0 リファレンスで、ExternalInterface クラスの例を参照してください。

外部 API の要件と利点
Flash Player 9 以降、Adobe AIR 1.0 以降
External API は ActionScript の一部で、Flash Player のコンテナとして機能する「外部アプリケーション」（一般的には
Web ブラウザーまたはスタンドアローンのプロジェクターアプリケーション）で実行されるコードと ActionScript 間の通信用メカニズムを提供します。ActionScript 3.0 では、External API の機能が ExternalInterface クラスによって提供されます。Flash Player 8 よりも前のバージョンの Flash Player では、fscommand() アクションを使用してコンテナアプリケー
ション内での通信が実行されていました。ExternalInterface クラスは、fscommand() に代わるものです。
注意：以前の fscommand() 関数を使用する必要がある場合（例えば、以前のバージョンのアプリケーションとの互換性を維持する場合や、サードパーティーの SWF コンテナアプリケーションやスタンドアローン Flash Player で操作する場合など）
は、パッケージレベルの関数として flash.system パッケージに用意されています。

ExternalInterface クラスは、HTML ページ上で ActionScript および Flash Player から JavaScript への通信を容易にする
サブシステムです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

812

External API の使用

ExternalInterface クラスは次の条件でのみ使用できます。

• Windows 版 Internet Explorer の全サポートバージョン（5.0 以降）• NPRuntime インターフェイスをサポートする任意のブラウザー。これには現在、Firefox 1.0 以降、Mozilla 1.7.5 以降、Netscape 8.0 以降および Safari 1.3 以降が含まれます。
• HTMLLoader コントロールによって表示されている HTML ページに SWF が埋め込まれている場合の AIR アプリケー
ション
その他の環境（スタンドアローン Player で実行する場合など）では、ExternalInterface.available プロパティは false を返します。

ActionScript から、HTML ページの JavaScript 関数を呼び出すことができます。External API の機能は、次の点においてfscommand() よりも強力です。

• fscommand() 関数から使用できる機能だけでなく、すべての JavaScript 関数を使用できます。
• 1 つのコマンドと 1 つのストリングパラメーターという制限はなく、任意の個数のパラメーターを任意の名前で渡すことができます。これにより、External API は fscommand() よりも非常に柔軟になっています。
• String パラメーターだけでなく、様々なデータ型（Boolean、Number、String など）を渡すことができます。
•

呼び出し結果の値を受け取ることができます。結果は呼び出しに対する戻り値として、直ちに ActionScript に戻されます。

重要：HTML ページの Flash Player インスタンスに指定された名前（object タグの id 属性）がハイフン（-）またはJavaScript の演算子として定義されているその他の文字（+、*、/、¥、. など）を含んでいる場合、コンテナ Web ページがInternet Explorer で表示されると、ActionScript からの ExternalInterface 呼び出しが機能しません。また、Flash Player
インスタンスを定義する HTML タグ（object タグと embed タグ）が HTML form タグ内にネストされている場合、ActionScript からの ExternalInterface 呼び出しが機能しません。

ExternalInterface クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript とコンテナアプリケーション間の通信には、コンテナで定義されたコード（JavaScript 関数など）をActionScript から呼び出す方法と、呼び出し可能なように設計された ActionScript 関数をコンテナのコードから呼び出す
方法の 2 種類の形式があります。いずれの場合も、呼び出される側のコードに情報が送信され、その結果が呼び出し側コードに返されます。
この通信を容易にするため、ExternalInterface クラスには 2 つの静的プロパティと 2 つの静的メソッドが用意されています。これらのプロパティとメソッドは、外部インターフェイス接続に関する情報を取得し、コンテナ内のコードをActionScript から実行し、コンテナから ActionScript 関数を呼び出せるようにするために使用されます。

外部コンテナに関する情報の取得
Flash Player 9 以降、Adobe AIR 1.0 以降
ExternalInterface.available プロパティは、外部インターフェイス機能を提供するコンテナ内に現在の Flash Player が格納されているかどうかを示します。外部インターフェイスが利用できる場合、このプロパティは true になります。利用できない
場合には false になります。ExternalInterface クラスの他の機能を使用する前に、現在のコンテナにおいて外部インターフェ
イスによる通信がサポートされているかどうかを、次のようにして必ず確認してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

813

External API の使用

if (ExternalInterface.available){// Perform ExternalInterface method calls here.
}

注意：ExternalInterface.available プロパティで確認できるのは、現在のコンテナが ExternalInterface 接続をサポートするタ
イプなのかどうかです。現在使用しているブラウザーの設定で JavaScript が有効化されているかどうかは確認できません。

ExternalInterface.objectID プロパティを使用すると、Flash Player インスタンスの一意の識別子（特に、Internet Explorer
における object タグの id 属性や、NPRuntime インターフェイスを使用するブラウザーにおける embed タグの name 属性）を確認できます。この一意の ID は、ブラウザー内の現在の SWF ドキュメントを表し、SWF ドキュメントを参照する場合に使用できます（コンテナ HTML ページ内の JavaScript 関数の呼び出しなど）。Flash Player コンテナが Web ブラウザー
ではない場合、このプロパティは null になります。

ActionScript からの外部コードの呼び出しFlash Player 9 以降、Adobe AIR 1.0 以降
ExternalInterface.call() メソッドでは、コンテナアプリケーション内のコードが実行されます。パラメーターは最低 1 つ必要
で、コンテナアプリケーション内で呼び出される関数の名前を含んだストリングを指定します。ExternalInterface.call() メ
ソッドに渡された追加パラメーターは、関数呼び出しのパラメーターとしてコンテナに渡されます。
// calls the external function "addNumbers"// passing two parameters, and assigning that function's result// to the variable "result"var param1:uint = 3;
var param2:uint = 7;
var result:uint = ExternalInterface.call("addNumbers", param1, param2);

コンテナが HTML ページの場合は、指定された名前の JavaScript 関数がこのメソッドによって呼び出されます。この名前は、格納された HTML ページの script エレメントで定義されている必要があります。JavaScript 関数の戻り値はActionScript に返されます。
<script language="JavaScript">// adds two numbers, and sends the result back to ActionScript
function addNumbers(num1, num2){
return (num1 + num2);}</script>

コンテナがその他の ActiveX コンテナの場合は、このメソッドによって Flash Player ActiveX コントロールから FlashCall
イベントが送出されます。指定された関数名とパラメーターは、Flash Player によって直列化されて XML ストリングになります。コンテナは、イベントオブジェクトの request プロパティでその情報にアクセスし、それを使用して自身のコードの実行方法を判定できます。値を ActionScript に返すには、コンテナコードで ActiveX オブジェクトの SetReturnValue() メ
ソッドを呼び出し、その結果（シリアル化された XML ストリング）をメソッドのパラメーターとして渡します。この通信で使用される XML フォーマットについて詳しくは、814 ページの「External API の XML フォーマット」を参照してください。
コンテナが Web ブラウザーでも、その他の ActiveX コンテナでも、呼び出しが失敗した場合やコンテナ側のメソッドが戻り値を返さなかった場合は、null が返されます。呼び出し側コードによるアクセスが、コンテナ環境の属するセキュリティ

Sandbox によって許可されていない場合、ExternalInterface.call() メソッドは SecurityError 例外をスローします。この問題を回避するには、コンテナ環境の allowScriptAccess に適切な値を設定します。例えば、HTML ページの allowScriptAccess の値を変更するには、object および embed タグの該当する属性を編集します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

814

External API の使用

コンテナからの ActionScript コードの呼び出しFlash Player 9 以降、Adobe AIR 1.0 以降
コンテナが呼び出すことができるのは、関数内の ActionScript コードのみです。それ以外の ActionScript コードは、コン
テナから呼び出すことはできません。コンテナアプリケーションから ActionScript 関数を呼び出すには、ExternalInterface クラスへの関数の登録と、コンテナコードからの関数の呼び出しという、2 つの処理が必要になります。
最初に、ActionScript 関数を登録し、コンテナから使用可能にすることを示す必要があります。

ExternalInterface.addCallback() メソッドを次のように使用します。
function callMe(name:String):String{
return "busy signal";}
ExternalInterface.addCallback("myFunction", callMe);

addCallback() メソッドには 2 つのパラメーターがあります。1 つはストリングの関数名で、コンテナはその名前で関数を認識します。もう 1 つのパラメーターは実際の ActionScript 関数で、定義された関数名をコンテナが呼び出すと実行されます。これらの名前は区別されるため、実際の ActionScript 関数が異なる名前であっても、コンテナで使用される関数名を指定できます。これは、匿名関数が指定された場合や、呼び出される関数が実行時に決定される場合など、関数名が不明な場
合に非常に便利です。

ActionScript 関数が ExternalInterface クラスに登録されると、コンテナが実際に関数を呼び出せるようになります。その方法は、コンテナのタイプによって異なります。例えば、Web ブラウザーの JavaScript コードの場合、登録された関数名をまるで Flash Player ブラウザーオブジェクトのメソッド（object または embed タグを表す JavaScript オブジェクトのメソッド）のように使用して ActionScript 関数が呼び出されます。つまり、パラメーターが渡され、呼び出されたローカル関数から結果が返されます。
<script language="JavaScript">// callResult gets the value "busy signal"
var callResult = flashObject.myFunction("my name");</script>...
<object id="flashObject"...>...
<embed name="flashObject".../></object>

あるいは、デスクトップアプリケーションで実行されている SWF ファイルの ActionScript 関数を呼び出す場合、登録された関数名とすべてのパラメーターを直列化して XML フォーマットストリングにする必要があります。その後、ActiveX コ
ントロールの CallFunction() メソッドとパラメーターとして XML ストリングを呼び出すことで、呼び出しが実際に実行されます。この通信で使用される XML フォーマットについて詳しくは、814 ページの「External API の XML フォーマッ
ト」を参照してください。
いずれの場合も、ActionScript 関数の戻り値はコンテナコードに返されますが、呼び出し側がブラウザーの JavaScript
コードの場合は値として直接返され、呼び出し側が ActiveX コンテナの場合は XML フォーマットストリングとして直列化して返されます。

External API の XML フォーマット
Flash Player 9 以降、Adobe AIR 1.0 以降
Shockwave Flash ActiveX コントロールをホストするアプリケーションと ActionScript 間の通信では、関数呼び出しと値をエンコードする際に専用の XML フォーマットが使用されます。External API で使用される XML フォーマットには 2 つの部分があります。1 つのフォーマットは、関数呼び出しを表すために使用されます。もう 1 つのフォーマットは個々の値を表しています。このフォーマットは、関数のパラメーターおよび関数の戻り値に使用されます。関数呼び出し用の XML

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

815

External API の使用

フォーマットは、ActionScript との間の呼び出しに使用されます。ActionScript からの関数呼び出しに対して、Flash

Player は XML をコンテナに渡します。コンテナからの呼び出しに対しては、Flash Player はこのフォーマットで XML ス
トリングを渡すコンテナアプリケーションが必要になります。次の XML は、XML フォーマットされた関数呼び出しの例を示しています。
<invoke name="functionName" returntype="xml"><arguments>... (individual argument values)</arguments></invoke>

ルートノードは invoke ノードです。name は関数呼び出しの名前を表し、returntype は常に xml になります。関数呼び出しにパラメーターが含まれている場合、invoke ノードには arguments 子ノードができます。さらにその子ノードは、次に説明す
る個別の値フォーマットを使用してフォーマットされたパラメーター値になります。
関数のパラメーターや関数の戻り値などの個々の値では、実際の値に加えてデータ型情報を含んだフォーマッティングス
キームが使用されます。次の表に、ActionScript クラス、およびそのデータ型の値のエンコードに使用する XML フォー
マットの一覧を示します。
ActionScript のクラスまC# のクラスまたは値

フォーマットnull

null<null/>

Boolean truebool true<true/>

Boolean falsebool false<false/>Stringstring<string> ストリング値 </string>Number、int、uint

single、double、int、
uint<number>27.5</number><number>-12</number>

コメント

たは値

Array（エレメントは型のArrayList や object[] など、 <array>property ノードでは混在可）

エレメントの型の混在が可
能なコレクション

個々のエレメントが定義され、id 属性は 0 かObjectストリングキー付きの

HashTable など、ストリン
グキーとオブジェクト値のある辞書

その他のビルトインクラ
スまたはカスタムクラス<property id="0"><number>27.5</number></property><property id="1"><string>Hello there!</string></property>...
</array><object><property id="name"><string>John Doe</string></property><property id="age"><string>33</string></property>...
</object><null/> or<object></object>

ら始まるインデックスの数値です。

property ノードでは個々のプロパティが定義され、id 属性はプロ
パティ名（ストリング）です。

ActionScript では他のオブジェクトが null ま
たは空のオブジェクトとしてエンコードされます。いずれの場合も、すべてのプロパティ値が失われます。

注意：この表では、ActionScript クラスに加えて同等の C# クラスを例示していますが、External API は、C# アプリケー
ションに限定されることなく、ActiveX コントロールをサポートする任意のプログラミング言語やランタイムとの通信に使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

816

External API の使用

External API と ActiveX コンテナアプリケーションを使用して独自のアプリケーションを構築している場合は、ネイティブ関数の呼び出しを直列化 XML 形式に変換できるプロキシを作成すると便利です。C# で記述されたプロキシクラスの例については、ExternalInterfaceProxy クラスの内部を参照してください。

External API の例：Web ブラウザーでの ActionScript とJavaScript との通信
Flash Player 9 以降、Adobe AIR 1.0 以降
このサンプルアプリケーションでは、ユーザーが自分自身とチャットできる Instant Messaging アプリケーションの場合に、Web ブラウザー内で ActionScript と JavaScript が通信するための方法を示しています（アプリケーション名 :Introvert IM）。メッセージは External API を使用して、Web ページ内の HTML 形式と SWF インターフェイスとの間で送信されます。この例で示す方法では、次のことを行います。

•

ブラウザーが通信可能なことを確認してから通信を設定することによる、通信の正しい初期化•

コンテナが External API をサポートしているかどうかの確認• ActionScript からの JavaScript 関数の呼び出し、パラメーターの受け渡し、および応答による値の受け取り• JavaScript から呼び出される ActionScript メソッドの有効化、および呼び出しの実行
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。Introvert IM アプリケーションのファイルは、Samples/IntrovertIM_HTML フォルダーにあります。このアプリケーションは次のファイルで構成されてい
ます。
ファイル

説明

IntrovertIMApp.fla

Flash（FLA）または Flex（MXML）のメインアプリケーションファイル。

またはIntrovertIMApp.mxml
com/example/programmingas3/introvertIM/IMManager.as

ActionScript とコンテナとの間の通信を確立および管理するクラス。

com/example/programmingas3/introvertIM/IMMessageEvent. コンテナからメッセージを受信したときに IMManager クラスから送出されasるカスタムイベントタイプ。
com/example/programmingas3/introvertIM/IMStatus.as

アプリケーションで選択可能な、様々な「availability」ステータス値を値が表している列挙。

html-flash/IntrovertIMApp.html
または

html-template/index.template.html

Flash アプリケーションの HTML ページ（htmlflash/IntrovertIMApp.html）または Adobe Flex アプリケーションのコン
テナ HTML ページ作成に使用するテンプレート（htmltemplate/index.template.html）。このファイルには、アプリケーションのコンテナ部分を構成するすべての JavaScript 関数が格納されています。

ActionScript とブラウザー間の通信の準備
Flash Player 9 以降、Adobe AIR 1.0 以降
External API の最も一般的な用途の 1 つは、ActionScript アプリケーションと Web ブラウザーとの通信です。External
API を使用すると、ActionScript メソッドから JavaScript コードへの呼び出し、および JavaScript コードからActionScript メソッドへの呼び出しを実現できます。ブラウザーの仕組みは複雑であり、また、ブラウザー内部で実行されるページレンダリング処理が不明であることから、HTML ページ上の JavaScript コードが最初に実行される前に SWF ド
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

817

External API の使用

キュメントのコールバックを登録できる保証はありません。したがって、JavaScript から SWF ドキュメントの関数を呼び出
す前に、SWF ドキュメント側の接続受け付け準備ができたことを通知するために、必ず SWF ドキュメントから HTML
ページへの呼び出しを実行してください。
例えば、IMManager クラスで実行される一連の手順によって、ブラウザーの通信準備ができ、SWF ファイルを通信で使用できることが、Introvert IM で判定されます。ブラウザーの通信準備ができたことを判定する最初の手順は、次のように
IMManager コンストラクターで実行されます。
public function IMManager(initialStatus:IMStatus){_status = initialStatus;// Check if the container is able to use the external API.
if (ExternalInterface.available){try{// This calls the isContainerReady() method, which in turn calls// the container to see if Flash Player has loaded and the container// is ready to receive calls from the SWF.
var containerReady:Boolean = isContainerReady();if (containerReady){// If the container is ready, register the SWF's functions.
setupCallbacks();}else{// If the container is not ready, set up a Timer to call the// container at 100ms intervals. Once the container responds that// it's ready, the timer will be stopped.
var readyTimer:Timer = new Timer(100);
readyTimer.addEventListener(TimerEvent.TIMER, timerHandler);
readyTimer.start();
}
}
...
}
else
{
trace("External interface is not available for this container.");}}

最初に、このコードは ExternalInterface.available プロパティを使用して、External API が現在のコンテナで利用可能かどうかをチェックします。利用可能であれば、通信の設定手順が開始されます。外部アプリケーションと通信しようとするとセキュリティ例外やその他のエラーが発生することがあるため、コードは try ブロックでラップされています（簡単にするため、対応する catch ブロックは省略されています）。
次に、ここに示すように isContainerReady() メソッドが呼び出されます。
private function isContainerReady():Boolean{
var result:Boolean = ExternalInterface.call("isReady");
return result;}

isContainerReady() メソッドは、ExternalInterface.call() メソッドを使用して次のように JavaScript 関数 isReady() を呼び出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

818

External API の使用<script language="JavaScript"><!-// ------- Private vars ------var jsReady = false;...
// ------- functions called by ActionScript ------// called to check if the page has initialized and JavaScript is available
function isReady(){
return jsReady;}...
// called by the onload event of the <body> tagfunction pageInit(){// Record that JavaScript is ready to go.
jsReady = true;
}
...
//-->
</script>

isReady() 関数は、単純に jsReady 変数の値を返します。この変数の初期値は false です。Web ページの onload イベントがトリガーされると、変数の値が true に変化します。つまり、ページのロード前に ActionScript から isReady() 関数が呼び出されると、JavaScript から ExternalInterface.call("isReady") に false が返され、その結果 ActionScript isContainerReady() メソッ
ドから false が返されます。ページがロードされると、JavaScript isReady() 関数から true が返されるため、ActionScript
isContainerReady() メソッドからも true が返されます。

IMManager コンストラクターでは、コンテナの準備状態に応じて 2 つのことが行われます。isContainerReady() から true が返された場合は、コードから単純に setupCallbacks() メソッドが呼び出されて、JavaScript での通信の設定手順が完了します。一方、isContainerReady() から false が返された場合、手順は実質的に保留状態になります。Timer オブジェクトが作成され、次のように 100 ミリ秒間隔で timerHandler() メソッドを呼び出すよう指示されます。
private function timerHandler(event:TimerEvent):void{// Check if the container is now ready.
var isReady:Boolean = isContainerReady();if (isReady){// If the container has become ready, we don't need to check anymore,// so stop the timer.
Timer(event.target).stop();// Set up the ActionScript methods that will be available to be// called by the container.
setupCallbacks();}}

timerHandler() メソッドが呼び出されるたびに、isContainerReady() メソッドの結果が再確認されます。コンテナが初期化されると、このメソッドから true が返されます。次に、コードでは Timer を停止して setupCallbacks() メソッドを呼び出し、
ブラウザーの通信の設定手順を終了します。

JavaScript への ActionScript メソッドの公開
Flash Player 9 以降、Adobe AIR 1.0 以降
上記の例で示したように、ブラウザーの準備ができたことがコードで判定されると、setupCallbacks() メソッドが呼び出されます。このメソッドでは、次のように JavaScript からの呼び出しを受信するよう ActionScript が準備されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

819

External API の使用

private function setupCallbacks():void{// Register the SWF client functions with the container
ExternalInterface.addCallback("newMessage", newMessage);
ExternalInterface.addCallback("getStatus", getStatus);// Notify the container that the SWF is ready to be called.
ExternalInterface.call("setSWFIsReady");}

setCallBacks() メソッドは、ExternalInterface.addCallback() を呼び出して JavaScript から呼び出し可能な 2 つのメソッドを登録することにより、コンテナとの通信準備のタスクを終了します。このコードでは、ActionScript のメソッド名と同じ名前
が第 1 パラメーターになっています。JavaScript（「newMessage」および「getStatus」）は、この名前によってメソッドを認識します ( この場合、異なる名前を使用することに意味がないため、同じ名前を再利用しました )。最後に、ExternalInterface.call() メソッドを使用して JavaScript 関数 setSWFIsReady() が呼び出され、ActionScript 関数の登録されたコンテナが通知されます。

ActionScript からブラウザーへの通信
Flash Player 9 以降、Adobe AIR 1.0 以降
Introvert IM アプリケーションは、コンテナページでの JavaScript 関数の呼び出しに関する様々な例を示しています。最も単純な場合（setupCallbacks() メソッドの例）には、パラメーターを渡したり、返される値を受け取ったりすることなく、

JavaScript 関数 setSWFIsReady() が呼び出されます。
ExternalInterface.call("setSWFIsReady");

isContainerReady() メソッドの別の例では、ActionScript から isReady() 関数が呼び出され、それに対する応答としてブール値を受け取ります。
var result:Boolean = ExternalInterface.call("isReady");

External API を使用して JavaScript 関数にパラメーターを渡すこともできます。例えば、IMManager クラスのsendMessage() メソッドについて考えてみます。このメソッドは、ユーザーが自分の「交信パートナー」に新しいメッセージを送信するときに呼び出されます。
public function sendMessage(message:String):void{
ExternalInterface.call("newMessage", message);}

ここでも、指定された JavaScript 関数が ExternalInterface.call() を使用して呼び出され、ブラウザーに新しいメッセージが通知されます。また、メッセージ自身は ExternalInterface.call() の追加パラメーターとして渡され、結果的に JavaScript 関数

newMessage() のパラメーターとして渡されます。

JavaScript からの ActionScript コードの呼び出しFlash Player 9 以降、Adobe AIR 1.0 以降
通信は双方向形式でサポートされ、Introvert IM アプリケーションも例外ではありません。Flash Player IM クライアント
がメッセージ送信のために JavaScript を呼び出すだけでなく、HTML フォームも JavaScript コードを呼び出して、メッ
セージを SWF ファイルに送信したり、SWF ファイルに情報を問い合わせます。例えば、接続が完了し、通信準備ができたことを SWF ファイルがコンテナに通知する場合、ブラウザーが最初に行うことは、IMManager クラスの getStatus() メ
ソッドを呼び出して、初期のユーザー availability ステータスを SWF IM クライアントから受信することです。これは、次のように Web ページの updateStatus() 関数で行われます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

820

External API の使用<script language="JavaScript">...
function updateStatus(){
if (swfReady){var currentStatus = getSWF("IntrovertIMApp").getStatus();
document.forms["imForm"].status.value = currentStatus;}}...
</script>

このコードでは、swfReady 変数の値が確認されます。この変数により、SWF ファイルのメソッドが ExternalInterface クラスに登録されたことが SWF ファイルからブラウザーに通知されたかどうかが追跡されます。SWF ファイルで通信の受信準備ができている場合、その次の行（var currentStatus = ...）では実際に IMManager クラスの getStatus() メソッドが呼び出されます。コードのこの行では、次の 3 つのことが行われます。

• getSWF() JavaScript 関数が呼び出され、SWF ファイルを表す JavaScript オブジェクトへの参照が返されます。
getSWF() に渡されたパラメーターによって、HTML ページ内に複数の SWF ファイルが存在する場合にどのブラウザー
オブジェクトが返されるかが決まります。このパラメーターに渡される値は、object タグの id 属性、および SWF ファイ
ルの埋め込みに使用される embed タグの name 属性と一致している必要があります。

• SWF ファイルへの参照を使用することで、SWF オブジェクトのメソッドであるかのように getStatus() メソッドが呼び出されます。この場合、関数名「getStatus」が使用されるのは、ExternalInterface.addCallback() を使用して ActionScript
関数がこの名前で登録されるからです。

• getStatus() ActionScript メソッドでは値が返され、その値が currentStatus 変数に割り当てられて、それがさらに status テ
キストフィールドのコンテンツ（value プロパティ）として割り当てられます。
注意：このコードをたどると、updateStatus() 関数のソースコードでは、getSWF() 関数を呼び出すコードの行が実際は次のように書かれていることがわかります。var currentStatus = getSWF("${application}").getStatus(); ${application} というテキストは、HTML ページ テンプレートのプレースホルダーです。Adobe Flex Builder が実際の HTML ページを生成する場
合、このプレースホルダーのテキストは、object タグの id 属性および embed タグの name 属性（この例では、IntrovertIMApp）として使用されているテキストと同じテキストによって置き換えられます。これは getSWF() 関数に必要な値です。

sendMessage() JavaScript 関数は、ActionScript 関数へのパラメーターの受け渡しを示しています（sendMessage() は、ユーザーが HTML ページの「送信」ボタンを押したときに呼び出される関数です）。
<script language="JavaScript">...
function sendMessage(message){if (swfReady){...
getSWF("IntrovertIMApp").newMessage(message);}}...
</script>

newMessage() ActionScript メソッドにはパラメーターが 1 つ必要なため、JavaScript コード内の newMessage() メソッドの呼び出しで JavaScript message 変数をパラメーターとして使用することで、この変数が ActionScript に渡されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

821

External API の使用

ブラウザータイプの検出
Flash Player 9 以降、Adobe AIR 1.0 以降
ブラウザーがコンテンツにアクセスする方法は様々であるため、この例の getSWF() JavaScript 関数に示すように、必ずJavaScript を使用してユーザーが実行しているブラウザーを検出すること、およびウィンドウまたはドキュメントオブジェ
クトを使用して、ブラウザー固有のシンタックスに従ってムービーにアクセスすることが重要です。
<script language="JavaScript">...
function getSWF(movieName){
if (navigator.appName.indexOf("Microsoft") != -1){
return window[movieName];}
else{
return document[movieName];}}...
</script>

スクリプトによってユーザーのブラウザータイプが検出されない場合、HTML コンテナの SWF ファイルを再生したときに予期しない動作が発生することがあります。

最終更新日 2015/10/14

822

第 48 章：AIR での XML 署名の検証
Adobe AIR 1.5 およびそれ以降
Adobe® AIR® の XMLSignatureValidator API のクラスを使用して、W3C 勧告「XML-Signature Syntax andProcessing」（http://http://www.w3.org/TR/xmldsig-core/）のサブセットに準拠した電子署名を検証します。XML 署
名を使用して、データまたは情報の整合性と署名者 ID を検証できます。
アプリケーションでは、ダウンロードするメッセージやリソースの検証に XML 署名を使用できます。例えば、サブスクリ
プション制でサービスを提供するアプリケーションにおいて、サブスクリプションの条件をカプセル化して署名付き XML
ドキュメント内に保存しておくことが考えられます。そのドキュメントが何者かに改変された場合は検証が失敗します。
また、アプリケーションでダウンロードするリソースに、ダイジェストを格納した署名付きマニフェストを含めておき、それらのリソースの検証に XML 署名を役立てることも考えられます。リソースが改変されていないことをアプリケーション
で検証するには、署名されたファイルのダイジェストと、読み込んだバイトデータから計算したダイジェストとを比較します。ダウンロードするリソースが、アプリケーションセキュリティサンドボックス内で実行する SWF ファイルその他のア
クティブコンテンツである場合、この使用方法は非常に有用です。

XML 署名の検証の基礎
Adobe AIR 1.5 およびそれ以降
XML 署名の検証に関する簡単な説明およびコード例については、Adobe Developer Connection で次のクイックスタートの記事を参照してください。

• XML 署名の作成および検証（Flex）• XML 署名の作成および検証 )（Flash）
Adobe® AIR® は、XML 署名を検証するための XMLSignatureValidator クラスと IURIDereferencer インターフェイスを備えています。XMLSignatureValidator クラスが受け入れる XML シンタックスは、W3C 勧告「XML Signature Syntax
and Processing」のサブセットです（この勧告のサブセットのみがサポートされているので、すべての法的署名を検証できるわけではありません）。AIR には、XML 署名を作成するための API はありません。

XML 署名の検証クラス
Adobe AIR 1.5 およびそれ以降
XML 署名の検証 API には、次のクラスが含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

823

AIR での XML 署名の検証

パッケージ

クラス

flash.security• XMLSignatureValidator• IURIDereferencer（インターフェイス）
XMLSignatureValidator のストリング定数は、次のクラスで定義されています。

• ReferencesValidationSetting• RevocationCheckSettings• SignatureStatus• SignerTrustSettings
flash.events• Event• ErrorEvent

XML 署名の検証クラスの使用
Adobe AIR 1.5 およびそれ以降
XMLSignatureValidator クラスを使用して XML 署名を検証するには、次の操作を行う必要があります。

• XMLSignatureValidator オブジェクトを作成します。
• IURIDereferencer インターフェイスの実装を用意します。XMLSignatureValidator オブジェクトは
IURIDereferencer の dereference() メソッドを呼び出して、署名内の各参照の URI を渡します。dereference() メソッド
は URI を解決し、参照先のデータを返す必要があります（参照先のデータは、同じドキュメント内に署名として含める
ことも、外部リソースに含めることもできます）。

•

アプリケーションに応じて、XMLSignatureValidator オブジェクトの、証明書の信頼、失効のチェックおよび参照の検証に関する設定を行います。

• complete イベントと error イベントのイベントリスナーを追加します。
• verify() メソッドを呼び出して、検証する署名を渡します。
• complete イベントと error イベントを処理し、結果を解釈します。
次の例では、XML 署名の有効性を検証する validate() 関数を実装します。XMLSignatureValidator のプロパティは、署名証明書がシステムの信頼ストアにあるか信頼ストアの証明書にチェーン化される必要があるように設定されています。また、
この例では、XMLDereferencer という名前の適切な IURIDereferencer クラスが存在することを前提としています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

824

AIR での XML 署名の検証

private function validate( xmlSignature:XML ):void{
var verifier:XMLSignatureValidator = new XMLSignatureValidator();verifier.addEventListener(Event.COMPLETE, verificationComplete);verifier.addEventListener(ErrorEvent.ERROR, verificationError);try{
verifier.uriDereferencer = new XMLDereferencer();verifier.referencesValidationSetting =ReferencesValidationSetting.VALID_IDENTITY;
verifier.revocationCheckSetting = RevocationCheckSettings.BEST_EFFORT;
verifier.useSystemTrustStore = true;//Verify the signature
verifier.verify( xmlSignature );}catch (e:Error){
trace("Verification error.\n" + e);}}//Trace verification results
private function verificationComplete(event:Event):void
var signature:XMLSignatureValidator = event.target as XMLSignatureValidator;
trace("Signature status: " + signature.validityStatus + "\n");trace(" Digest status: " + signature.digestStatus + "\n");trace(" Identity status: " + signature.identityStatus + "\n");trace(" Reference status: " + signature.referencesStatus + "\n");}private function verificationError(event:ErrorEvent):void{
trace("Verification error.\n" + event.text);}

XML 署名の検証プロセス
Adobe AIR 1.5 およびそれ以降
XMLSignatureValidator の verify() メソッドを呼び出すと、AIR では次の手順を実行します。

•

署名証明書の公開キーを使用して、署名の暗号化の整合性をランタイムにより検証します。

• XMLSignatureValidator オブジェクトの現在の設定に基づいて、証明書の暗号化の整合性、ID および信頼性をランタ
イムにより確認します。
署名証明書の信頼性は、検証プロセスの完全性を確保するために重要です。署名の検証は適切に定義された暗号化プロセスを使用して行われますが、署名証明書の信頼性はアルゴリズムでは判断できません。
一般に、証明書の信頼性を確認するには、次の 3 つの方法があります。

••

証明機関とオペレーティングシステムの信頼ストアを信頼する。
署名者から直接、証明書、証明書の信頼アンカーとして機能する別の証明書または証明書を確実に識別できる情報（公開キーなど）を入手する。

•

アプリケーションのエンドユーザーに、証明書を信頼するかどうかを確認する。このような照会は、自己署名入り証
明書では無効です。自己署名入り証明書の識別情報は、本来信頼できないものだからです。

•

署名されたデータの暗号化の整合性をランタイムにより検証します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

825

AIR での XML 署名の検証

署名されたデータは、IURIDereferencer の実装を利用して検証されます。署名ドキュメント内の各参照に対して、

IURIDereferencer の実装の dereference() メソッドが呼び出されます。dereference() メソッドから返されたデータは、参照のダイジェストの計算に使用されます。このダイジェスト値は、署名ドキュメントに記録されているダイジェストと比較されます。ダイジェストが一致する場合、データは署名後に変更されていません。

XML 署名の検証結果を信頼する際の重要な注意事項の 1 つは、署名された対象のみが安全であるということです。例えば、パッケージ内のファイルを一覧表示する署名されたマニフェストがあるとします。XMLSignatureValidator がこの署名を検証するときは、マニフェスト自体が変更されたかどうかをチェックするだけです。ファイル内のデータは署名されていないので、マニフェストで参照されているファイルが変更または削除されても、署名は有効なままです。
注意：このようなマニフェスト内のファイルを検証するには、（マニフェストで使用されているのと同じハッシュアルゴ
リズムを使用して）ファイルデータのダイジェストを計算し、署名されたマニフェストに格納されているダイジェストと計算結果を比較します。場合によっては、他のファイルの存在もチェックする必要があります。

検証結果の解釈
Adobe AIR 1.5 およびそれ以降
検証結果は、XMLSignatureValidator オブジェクトのステータスプロパティで報告されます。これらのプロパティは、検証オブジェクトが complete イベントを送出した後に読み取ることができます。ステータスプロパティには、validityStatus、
digestStatus、identityStatus および referencesStatus の 4 つがあります。

validityStatus プロパティ
Adobe AIR 1.5 およびそれ以降
validityStatus プロパティは、署名の全体的な有効性を報告します。validityStatus は他の 3 つのステータスプロパティの状態に依存します。値は次のうちのいずれかです。

• valid — digestStatus、identityStatus および referencesStatus がすべて valid の場合。
• invalid — 個々のステータスプロパティのいずれかが invalid の場合。
• unknown — 個々のステータスプロパティのうち 1 つ以上が unknown であり、かつ、1 つのステータスも invalid ではない場合。

digestStatus プロパティ
Adobe AIR 1.5 およびそれ以降
digestStatus プロパティは、メッセージダイジェストの暗号化の検証結果を報告します。digestStatus プロパティの値は、次のうちのいずれかです。

• valid — 署名ドキュメント自体が署名後に変更されていない場合。
• invalid — 署名ドキュメントが改変されている場合または正しい形式でない場合。
• unknown — verify() メソッドが正常に実行されなかった場合。
identityStatus プロパティ
Adobe AIR 1.5 およびそれ以降
identityStatus プロパティは、署名証明書のステータスを報告します。このプロパティの値は、次のような要因に依存します。

•

証明書の暗号化の整合性•

証明書が期限切れまたは失効しているかどうか

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

826

AIR での XML 署名の検証•証明書が現在のマシンで信頼されているかどうか• XMLSignatureValidator オブジェクトの状態（信頼チェーンを作成するために他の証明書が追加されているかどうか、それらの証明書を信頼できるかどうか、useSystemTrustStore プロパティと revocationCheckSettings プロパティの値など）

identityStatus プロパティの値は、次のうちのいずれかです。

• valid — 署名証明書が有効と見なされるためには、次の条件を満たしている必要があります。
•

署名証明書が変更されていない。

•

署名証明書は、期限切れのものや失効したものであってはなりません。ただし、署名内に有効なタイムスタンプが存在する場合を除きます。署名がタイムスタンプ付きであり、そのドキュメントが署名された時点で証明書が有効であった場合は、証明書が有効であるものと見なされます（タイムスタンプに署名するときタイムスタンプサービスにより使用された証明書は、ユーザーのコンピューター上の信頼できるルート証明書とチェーンされている必要があります）。

•

署名証明書が信頼されている。証明書が信頼されるのは、証明書がシステムの信頼ストアにあるか、システムの信頼ストアにある別の証明書にチェーン化されていて、useSystemTrustStore プロパティが true に設定されている場合です。XMLSignatureValidator オブジェクトの addCertificate() メソッドを使用して、証明書を信頼するように指定することもできます。

•

証明書が実際の署名証明書である。

• invalid — 証明書が期限切れまたは失効していて署名時の有効性を証明するタイムスタンプがないか、証明書が変更されています。

• unknown — 証明書は無効ではないが、信頼できません。例えば、自己署名入り証明書は、明示的に信頼されない限り、
unknown として報告されます。identityStatus が unknown として報告される他の例としては、verify() メソッドが正常に実行されなかった場合や、署名ダイジェストが無効であるために ID がチェックされなかった場合が挙げられます。

referencesStatus プロパティ
Adobe AIR 1.5 およびそれ以降
referencesStatus プロパティは、署名の SignedData エレメントに含まれる参照の暗号化の整合性を報告します。

• valid — 署名内の各参照について計算されたダイジェストが、XML 署名に記録された対応するダイジェストに一致する場合。valid ステータスは、署名されたデータが変更されていないことを示します。

• invalid — 計算されたいずれかのダイジェストが、署名内の対応するダイジェストに一致しない場合。
• unknown — 参照のダイジェストがチェックされなかった場合。署名のダイジェスト全体が invalid の場合や、署名証明書が無効である場合、参照はチェックされません。identityStatus が unknown の場合、参照がチェックされるのは、

referencesValidationSetting が validOrUnknown の場合のみです。

XML 署名について
Adobe AIR 1.5 およびそれ以降
XML 署名は、XML シンタックスで表された電子署名です。XML 署名のデータを使用して、署名された情報が署名後に変更されていないかどうかを検証できます。また、署名証明書が信頼できる証明機関から発行されている場合は、公開キーイ
ンフラストラクチャを使用して署名者の ID を検証できます。

XML 署名は、バイナリまたは XML 形式のあらゆる種類のデジタルデータに適用できます。XML 署名は、通常、次のような目的に使用されます。

•

外部リソースやダウンロードされたリソースが変更されているかどうかのチェック

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

827

AIR での XML 署名の検証•

メッセージが既知のソースから発信されたかどうかの検証•

アプリケーションのライセンスやサブスクリプション権限の検証

サポートされる XML 署名のシンタックス
Adobe AIR 1.5 およびそれ以降
AIR では、W3C 勧告「XML Signature Syntax and Processing」に含まれる次のエレメントをサポートしています。

•

すべてのコア署名シンタックスエレメント（W3C 勧告ドキュメントのセクション 4）。ただし、KeyInfo エレメントは
完全にはサポートされていません。

• KeyInfo エレメント。X509Data エレメントのみを含んでいる必要があります。
• X509Data エレメント。X509Certificate エレメントのみを含んでいる必要があります。
• SHA256 ダイジェストメソッド。
• RSA-SHA1（PKCS1）署名アルゴリズム。
• 「コメントのない Canonical XML」正規化方法と変換。
• enveloped 署名の変換。
•

タイムスタンプ

次のドキュメントに、一般的な XML 署名を示します（例を単純にするために、ほとんどの暗号化データを除いてあります）。
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI="URI_to_signed_data"><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><DigestValue>uoo...vY=</DigestValue></Reference></SignedInfo><SignatureValue>Ked...w==</SignatureValue><KeyInfo><X509Data><X509Certificate>i7d...w==</X509Certificate></X509Data></KeyInfo></Signature>

署名の主要なエレメントは次のとおりです。

• SignedInfo - 署名対象データへの参照と、署名時に計算されたダイジェスト値が含まれます。署名対象データは、XML
署名と同じドキュメントに含めることも、外部に配置することもできます。

• SignatureValue - 署名者の秘密キーで暗号化された SignedInfo エレメントのダイジェストが含まれます。
• KeyInfo - 署名証明書と、信頼チェーンを作成するために必要なその他の証明書が含まれます。KeyInfo エレメントは技
術的には省略可能ですが、このエレメントが含まれていない場合、AIR では署名を検証できません。
XML 署名には、大きく分けて次の 3 つの種類があります。

• enveloped - 署名が、署名対象の XML データ内に挿入されています。
• enveloping - 署名対象の XML データが、Signature エレメント内の Object エレメントに内包されています。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

828

AIR での XML 署名の検証• detached - 署名対象のデータが、XML 署名の外部にあります。署名対象のデータを外部ファイルに置くこともできます。また、署名と同じ XML ドキュメント内に、親エレメントや子エレメント以外として含めることもできます。
XML 署名では、URI を使用して署名対象データを参照します。署名側のアプリケーションと検証側のアプリケーションは、同じ規則を使用してこれらの URI を解決する必要があります。XMLSignatureValidator クラスを使用するときは、

IURIDereferencer インターフェイスの実装を用意する必要があります。この実装は URI を解決し、署名されたデータを
ByteArray オブジェクトとして返します。署名のダイジェストを生成したのと同じアルゴリズムを使用して、返された
ByteArray オブジェクトのダイジェストが生成されます。

証明書と信頼Adobe AIR 1.5 およびそれ以降証明書は公開キーと識別情報で構成され、場合によっては発行側の証明機関に属する 1 つ以上の証明書が含まれています。
証明書の信頼性を確認する方法は 2 つあります。物理メディアや SSL トランザクションなどの安全な電子通信を利用して署名者から証明書を直接入手することにより、信頼性を確認できます。また、証明機関を信頼することによって署名証明書の信頼性を確認することもできます。
証明機関を信頼するには、署名証明書の署名が検証されるコンピューターで信頼されている機関から発行されている必要があります。ほとんどのオペレーティングシステムでは、システムの信頼ストアに、多くの証明機関のルート証明書があらか
じめ組み込まれています。ユーザーがストアの証明書の追加や削除を行うこともできます。
証明書が信頼できる証明機関から発行されていても、証明書の所有者を信頼できるかどうかを確認する必要があります。多くの場合、この判断はエンドユーザーに委ねられます。例えば、AIR アプリケーションのインストールでは、アプリケー
ションをインストールするかどうかをユーザーに確認する際に、発行者の証明書の識別情報が表示されます。また、公開
キーやその他の証明書情報を、許容されるキーのリストと比較する必要がある場合もあります（このリストは、それ自体が改ざんされないように、リスト自身による署名や AIR の暗号化されたローカルストアへの格納によって保護される必要があります）。
注意：署名が「自己署名」である場合などに、単独での検証を行わずに署名証明書を信頼することもできますが、その場合、署名を検証してもあまり多くの保証は得られません。署名の作成者がわからない場合、署名が改ざんされていないという保証にほとんど意味はありません。署名は、有効に署名された偽造である可能性があります。
証明書の期限切れと失効

Adobe AIR 1.5 およびそれ以降
すべての証明書には期限があります。また、証明書に関連付けられた秘密キーが改ざんされたり盗まれたりした場合などに、発行側の証明機関によって証明書が取り消されることもあります。署名が期限切れの証明書や失効した証明書で署名されている場合、署名にタイムスタンプが含まれていない限り、その署名は無効として報告されます。タイムスタンプが含まれている場合は、証明書が署名時に有効である限り、XMLSignatureValidator クラスは署名を有効と見なします。
タイムスタンプはタイムスタンプサービスから送信される署名された電子メッセージで、特定の日時にデータが署名されたことを証明します。タイムスタンプはタイムスタンプ機関から発行され、タイムスタンプ機関自身の証明書で署名されています。タイムスタンプが有効と見なされるには、タイムスタンプに組み込まれているタイムスタンプ機関の証明書が、現在のマシンで信頼されている必要があります。XMLSignatureValidator には、タイムスタンプの検証に使用する別の証明書を指定するための API はありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

829

AIR での XML 署名の検証

IURIDereferencer インターフェイスの実装
Adobe AIR 1.5 およびそれ以降
XML 署名を検証するためには、IURIDereferencer インターフェイスの実装を用意する必要があります。この実装は、
XML 署名ドキュメントの Reference エレメントに含まれる URI を解決してデータを返し、ダイジェストを計算できるようにします。計算されたダイジェストは署名内のダイジェストと比較され、それにより、署名の作成後に参照先のデータが変更されたかどうかを確認できます。
注意：HTML ベースの AIR アプリケーションで XML 署名を検証するためには、ActionScript の実装を含む SWF ライブ
ラリをインポートする必要があります。IURIDereferencer インターフェイスは JavaScript では実装できません。

IURIDerefencer インターフェイスには、dereference(uri:String) という 1 つのメソッドがあります。このメソッドは実装する必要があります。XMLSignatureValidator オブジェクトは、署名内の各参照に対してこのメソッドを呼び出します。このメソッドは、ByteArray オブジェクトでデータを返す必要があります。
ほとんどの場合、間接参照オブジェクトが参照先データを見つけられるようにするためのプロパティやメソッドも追加する必要があります。例えば、署名されたデータが署名と同じドキュメント内にある場合は、その XML ドキュメントへの参照を提供するメンバ変数を追加します。dereference() メソッドは、この変数を URI と共に使用して、参照先のデータを見つけることができます。同様に、署名されたデータがローカルファイルシステムのディレクトリにある場合、dereference() メ
ソッドが参照先ファイルを解決するためには、そのディレクトリへのパスを提供するプロパティが必要です。

XMLSignatureValidator は、URI ストリングの解釈を間接参照に完全に依存します。URI の間接参照に関する標準的な規則は、W3C 勧告「XML Signature Syntax and Processing」のセクション 4.3.3 に記載されています。

enveloped 署名での URI の間接参照
Adobe AIR 1.5 およびそれ以降
enveloped XML 署名が生成されるときは、署名対象データの内部に署名エレメントが挿入されます。例えば、enveloped
署名構造を使用して次のメッセージに署名したとします。
<message><data>...</data></message>

署名後のドキュメントは次のようになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

830

AIR での XML 署名の検証<message><data>...</data><Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI=""><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><DigestValue>yv6...Z0Y=</DigestValue></Reference></SignedInfo><SignatureValue>cCY...LQ==</SignatureValue><KeyInfo><X509Data><X509Certificate>MII...4e</X509Certificate></X509Data></KeyInfo></Signature></message>

この署名には、空のストリングを URI として含む Reference エレメントが 1 つあります。このコンテキストでの空のストリングは、ドキュメントのルートを指します。
また、変換アルゴリズムは、enveloped 署名変換が適用されていることを示しています。enveloped 署名変換が適用された
場合、XMLSignatureValidator は、ダイジェストを計算する前にドキュメントから署名を自動的に削除します。つまり、間接参照がデータを返すときに Signature エレメントを削除する必要はありません。
次の例に、enveloped 署名の間接参照を示します。
package{import flash.events.ErrorEvent;import flash.events.EventDispatcher;import flash.security.IURIDereferencer;
import flash.utils.ByteArray;
import flash.utils.IDataInput;
public class EnvelopedDereferencer
extends EventDispatcher implements IURIDereferencer{
private var signedMessage:XML;public function EnvelopedDereferencer( signedMessage:XML ){this.signedMessage = signedMessage;}
public function dereference( uri:String ):IDataInput{try{if( uri.length != 0 ){throw( new Error("Unsupported signature type.") );最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

831

AIR での XML 署名の検証}
var data:ByteArray = new ByteArray();
data.writeUTFBytes( signedMessage.toXMLString() );data.position = 0;}
catch (e:Error){
var error:ErrorEvent =new ErrorEvent("Ref error " + uri + " ", false, false, e.message);this.dispatchEvent(error);data = null;
throw new Error("Reference not resolvable: " + uri + ", " + e.message);}
finally{
return data;}}}}

この間接参照クラスは、signedMessage というパラメーターを持つコンストラクター関数を使用して、enveloped 署名ドキュメントを dereference() メソッドで使用できるようにします。enveloped 署名内の参照は常に署名対象データのルートを指すので、dereferencer() メソッドはドキュメントをバイト配列に書き込み、それを返します。

enveloping 署名および detached 署名での URI の間接参照
Adobe AIR 1.5 およびそれ以降
署名対象のデータが署名自体と同じドキュメント内にある場合、通常、参照の URI は XPath シンタックスまたは XPointer
シンタックスを使用して署名対象エレメントのアドレスを指定します。W3C 勧告「XML Signature Syntax andProcessing」はこのシンタックスを推奨しているだけなので、想定される署名に基づいて実装を行う必要があります（さらに、サポートされないシンタックスを適切に処理するための十分なエラーチェックを追加する必要があります）。

AIR アプリケーションの署名は、enveloping 署名の一例です。アプリケーション内のファイルは Manifest エレメントに一覧表示されます。Manifest エレメントのアドレスは、Reference URI 属性内で、Manifest エレメントの ID を指す“#PackageContents” というストリングを使用して指定されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

832

AIR での XML 署名の検証<Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="PackageSignature"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/><SignatureMethod Algorithm="http://www.w3.org/TR/xmldsig-core#rsa-sha1"/><Reference URI="#PackageContents"><Transforms><Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><DigestValue>ZMGqQdaRKQc1HirIRsDpeBDlaElS+pPotdziIAyAYDk=</DigestValue></Reference></SignedInfo><SignatureValue Id="PackageSignatureValue">cQK...7Zg==</SignatureValue><KeyInfo><X509Data><X509Certificate>MII...T4e</X509Certificate></X509Data></KeyInfo><Object><Manifest Id="PackageContents"><Reference URI="mimetype"><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></DigestMethod><DigestValue>0/oCb84THKMagtI0Dy0KogEu92TegdesqRr/clXct1c=</DigestValue></Reference><Reference URI="META-INF/AIR/application.xml"><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></DigestMethod><DigestValue>P9MqtqSdqcqnFgeoHCJysLQu4PmbUW2JdAnc1WLq8h4=</DigestValue></Reference><Reference URI="XMLSignatureValidation.swf"><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></DigestMethod><DigestValue>OliRHRAgc9qt3Dk0m0Bi53Ur5ur3fAweIFwju74rFgE=</DigestValue></Reference></Manifest></Object></Signature>

この署名を検証する間接参照は、Reference エレメントから "#PackageContents" を含む URI ストリングを取得し、Manifest
エレメントを ByteArray オブジェクトで返す必要があります。「#」記号はエレメント ID 属性の値を示します。
次の例では、AIR アプリケーションの署名を検証する間接参照を実装します。実装は、既知の構造の AIR 署名を使用して単純化されています。汎用の間接参照はこれよりもかなり複雑になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

833

AIR での XML 署名の検証

package{import flash.events.ErrorEvent;import flash.security.IURIDereferencer;
import flash.utils.ByteArray;
import flash.utils.IDataInput;
public class AIRSignatureDereferencer implements IURIDereferencer {private const XML_SIG_NS:Namespace =new Namespace( "http://www.w3.org/2000/09/xmldsig#" );private var airSignature:XML;public function AIRSignatureDereferencer( airSignature:XML ) {this.airSignature = airSignature;}public function dereference( uri:String ):IDataInput {var data:ByteArray = null;try{
if( uri != "#PackageContents" ){throw( new Error("Unsupported signature type.") );}var manifest:XMLList =airSignature.XML_SIG_NS::Object.XML_SIG_NS::Manifest;
data = new ByteArray();
data.writeUTFBytes( manifest.toXMLString());
data.position = 0;}
catch (e:Error){
data = null;
throw new Error("Reference not resolvable: " + uri + ", " + e.message);}
finally{
return data;}}}}

この種類の署名を検証するときは、Manifest エレメントのデータだけが検証されます。パッケージ内の実際のファイルは
まったくチェックされません。パッケージのファイルが改ざんされていないかどうかをチェックするには、ファイルを読み取って SHA256 ダイジェストを計算し、その結果をマニフェストに記録されているダイジェストと比較する必要があります。XMLSignatureValidator は、このような二次参照を自動的にはチェックしません。
注意：この例は、署名の検証プロセスを示すためだけに提供されています。それ自身の署名を検証する AIR アプリケーショ
ンはほとんど役に立ちません。アプリケーションが既に改ざんされている場合、改ざん者が検証チェックを取り除いている
可能性があります。

外部リソースのダイジェスト値の計算
Adobe AIR 1.5 およびそれ以降
AIR には SHA256 ダイジェストを計算するためのビルトイン関数が含まれていませんが、Flex SDK には SHA256 ユー
ティリティクラスが含まれています。この SDK には、計算したダイジェストを署名に格納されているダイジェストと比較するのに役立つ Base64 エンコーダーユーティリティのクラスも含まれています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

834

AIR での XML 署名の検証

次の関数の例では、AIR パッケージのマニフェストに含まれているファイルを読み取って検証します。
import mx.utils.Base64Encoder;import mx.utils.SHA256;
private function verifyManifest( sigFile:File, manifest:XML ):Boolean{
var result:Boolean = true;
var message:String = '';var nameSpace:Namespace = manifest.namespace();if( manifest.nameSpace::Reference.length() <= 0 ){result = false;message = "Nothing to validate.";}for each (var reference:XML in manifest.nameSpace::Reference){var file:File = sigFile.parent.parent.resolvePath( reference.@URI );var stream:FileStream = new FileStream();stream.open(file, FileMode.READ);
var fileData:ByteArray = new ByteArray();
stream.readBytes( fileData, 0, stream.bytesAvailable );var digestHex:String = SHA256.computeDigest( fileData );//Convert hexidecimal string to byte arrayvar digest:ByteArray = new ByteArray();for( var c:int = 0; c < digestHex.length; c += 2 ){var byteChar:String = digestHex.charAt(c) + digestHex.charAt(c+1);
digest.writeByte( parseInt( byteChar, 16 ));}digest.position = 0;
var base64Encoder:Base64Encoder = new Base64Encoder();base64Encoder.insertNewLines = false;
base64Encoder.encodeBytes( digest, 0, digest.bytesAvailable );var digestBase64:String = base64Encoder.toString();if( digestBase64 == reference.nameSpace::DigestValue ){result = result && true;message += "" + reference.@URI + " verified.\n";}else{result = false;message += " ---- " + reference.@URI + " has been modified!\n";}base64Encoder.reset();}trace( message );return result;}

この関数は、Manifest エレメントに含まれているすべての参照を反復処理します。各参照に対して SHA256 ダイジェストが計算され、base64 形式でエンコードされ、マニフェスト内のダイジェストと比較されます。AIR パッケージ内の URI は、
アプリケーションディレクトリへの相対パスを指します。このパスは署名ファイルの場所に基づいて解決されます。署名
ファイルは常に、アプリケーションディレクトリ内の META-INF サブディレクトリにあります。Flex の SHA256 クラス
は、ダイジェストを 16 進文字のストリングとして返します。このストリングを、16 進ストリングで表されたバイトを含む

ByteArray に変換する必要があります。
Flash CS4 で mx.utils.SHA256 クラスと Base64Encoder クラスを使用するには、これらのクラスを探してアプリケーショ
ン開発ディレクトリにコピーするか、これらのクラスを含む SWF ライブラリを Flex SDK を使用してコンパイルします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

835

AIR での XML 署名の検証

外部データを参照する detached 署名での URI の間接参照
Adobe AIR 1.5 およびそれ以降
URI が外部リソースを指している場合、データにアクセスし、データを ByteArray オブジェクトに読み込む必要があります。URI に絶対 URL が含まれる場合は、ファイルを読み取るか URL を要求するだけです。しかし、より一般的な、URIに相対パスが含まれる場合には、署名対象ファイルへのパスを解決する手段が IURIDereferencer 実装に含まれている必要があります。
次の例では、署名対象ファイルを解決するための基礎として、間接参照インスタンスの作成時に初期化される File オブジェ
クトを使用します。
package{import flash.events.ErrorEvent;import flash.events.EventDispatcher;import flash.filesystem.File;
import flash.filesystem.FileMode;
import flash.filesystem.FileStream;
import flash.security.IURIDereferencer;
import flash.utils.ByteArray;
import flash.utils.IDataInput;
public class RelativeFileDereferencer
extends EventDispatcher implements IURIDereferencer{
private var base:File;public function RelativeFileDereferencer( base:File ){this.base = base;}public function dereference( uri:String ):IDataInput{
var data:ByteArray = null;try{
var referent:File = this.base.resolvePath( uri );var refStream:FileStream = new FileStream();data = new ByteArray();
refStream.open( referent, FileMode.READ );refStream.readBytes( data, 0, data.bytesAvailable );} catch ( e:Error ) {data = null;
throw new Error("Reference not resolvable: " + referent.nativePath + ", " + e.message );} finally {return data;}}}}

dereference() 関数は単に、参照 URI によってアドレス指定されたファイルを探し、ファイルの内容をバイト配列に読み込
み、ByteArray オブジェクトを返します。
注意：リモートの外部参照を検証する場合は、悪意ある細工が施された署名付きドキュメントによる「phone home」攻撃（情報を収集して密かに攻撃者のサイトへと送信すること）または似た種類の攻撃に対してアプリケーションが脆弱性を持っていないか、事前に検討してください。

最終更新日 2015/10/14

836

第 49 章：クライアントのシステム環境
Flash Player 9 以降、Adobe AIR 1.0 以降
ここでは、ユーザーのシステムを操作する方法について説明します。ここでは、サポートされている機能を判別する方法と、ユーザーが入力方式エディター（IME）をインストールしてある場合に、IME を使用して複数言語のアプリケーションを構築する方法を示します。また、アプリケーションドメインの一般的な使用方法も示します。

関連項目

flash.system.System
flash.system.Capabilities

クライアントのシステム環境の基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
高度な アプリケーションを構築していると、ユーザーのオペレーティングシステムの詳細およびアクセス機能を知る必要がある場合があります。flash.system パッケージには、次のようなシステムレベルの機能にアクセスできるクラスのコレクションが含まれています。

•

実行しているアプリケーションとセキュリティドメインコードの判別•

画面サイズ（解像度）などのユーザーの Flash ランタイム（Flash® Player、Adobe® AIR™ など）インスタンスの機能、および MP3 などの特定の機能が使用可能かどうかの判別• IME を使用した複数言語サイトの構築• Flash ランタイムのコンテナ（HTML ページの場合もコンテナアプリケーションの場合もあります）または AIR のコン
テナの操作

•

ユーザーのクリップボードへの情報の保存

また、flash.system パッケージには IMEConversionMode および SecurityPanel クラスも含まれています。これらでは、それぞれ IME クラスと Security クラスで使用する静的定数が定義されています。
重要な概念と用語
次の参照リストに、重要な用語を示します。
オペレーティングシステム Microsoft Windows、Mac OS X、Linux® など、コンピューターで実行されるメインプログラ
ム。他のすべてのアプリケーションはこのプログラムの内部で実行されます。
クリップボード コピーまたはカットしたテキストやアイテムを保持するためのオペレーティングシステムのコンテナ。コン
テナ内のアイテムはアプリケーションにペーストできます。
アプリケーションドメイン 異なる SWF ファイルに使用されているクラスを分離するメカニズム。これにより、複数のSWF ファイルで同じ名前の別のクラスが使用されていても、そのクラスが他のクラスを上書きすることはありません。
IME（入力方式エディター）標準キーボードを使用して複雑な文字や記号を入力するために使用するプログラム（またはオペレーティングシステムツール）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

837

クライアントのシステム環境

クライアントシステム プログラミング用語では、クライアントは個々のコンピューターで実行されるアプリケーションの一部（またはアプリケーション全体）で、単一のユーザーによって使用されます。クライアントシステムはユーザーのコン
ピューター上の基になるオペレーティングシステムです。

System クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
System クラスには、ユーザーのオペレーティングシステムを操作したり、ランタイムの現在のメモリ使用状況を取得できるメソッドとプロパティが格納されています。System クラスのメソッドとプロパティを使用すると、imeComposition イベ
ントの待ち受け、ユーザーの現行コードページを使用した外部テキストファイルのロードまたは Unicode としてのロードを行うためのランタイムに対する指示、ユーザーのクリップボードの内容の設定も行うことができます。

実行時のユーザーのシステムに関するデータの取得
Flash Player 9 以降、Adobe AIR 1.0 以降
System.totalMemory プロパティを調べると、ランタイムが現在使用しているメモリの量をバイト単位で判別できます。この
プロパティを使用してメモリ使用量を監視すれば、空きメモリの状況の変化に応じてアプリケーションの動作を最適に調整できます。例えば、特定のビジュアル効果を使用するとメモリ使用量が大幅に増加する場合、状況によってその効果を変化
または完全に無効にすることが考えられます。
System.ime プロパティは、現在インストールされている IME（入力メソッドエディター）への参照です。このプロパティを使用すると、addEventListener() メソッドで imeComposition イベント（flash.events.IMEEvent.IME_COMPOSITION）を待ち受けることができます。

System クラスの 3 番目のプロパティは useCodePage です。useCodePage を true に設定した場合、ランタイムは、オペレー
ティングシステムの通常のコードページを使用して外部テキストファイルを読み込みます。このプロパティを false に設定す
ると、ランタイムは外部ファイルを Unicode として解釈します。

System.useCodepage を true に設定した場合、外部テキストファイル内で使用されている文字がオペレーティングシステムの通常のコードページに含まれていないと、そのテキストは表示されないことに注意してください。例えば、中国語を含んだ
外部テキストファイルをロードする場合、English Windows コードページを使用しているシステム上では文字が表示されません。これは、English Windows コードページには中国語の文字が含まれないためです。
アプリケーション内で使用される外部テキストファイルをすべてのプラットフォームのユーザーが表示できるようにするには、すべての外部テキストファイルを Unicode で保存し、System.useCodePage をデフォルトの false の設定のままにします。
このように、ランタイムは、テキストを Unicode として解釈します。

クリップボードへのテキストの保存
Flash Player 9 以降、Adobe AIR 1.0 以降
System クラスには setClipboard() というメソッドがあります。このメソッドを使用すると、Flash ランタイムから指定したストリングをユーザーのクリップボードの内容として設定できます。セキュリティ上の理由から、Security.getClipboard() メ
ソッドはありません。そのようなメソッドは、悪意あるサイトがユーザーのクリップボードへ最後にコピーされたデータにアクセスすることを許すおそれがあるからです。
次のコードは、セキュリティエラーが発生したときに、ユーザーのクリップボードへエラーメッセージをコピーする方法の例です。このエラーメッセージは、ユーザーがアプリケーションの潜在的なバグを報告する場合に役に立ちます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

838

クライアントのシステム環境

private function securityErrorHandler(event:SecurityErrorEvent):void{
var errorString:String = "[" + event.type + "] " + event.text;
trace(errorString);
System.setClipboard(errorString);}

Flash Player 10 および AIR 1.0
Clipboard クラスを使用すると、ユーザーイベントに反応してクリップボードデータの読み取りと書き込みを行えます。
AIR では、クリップボードへのアクセスのためにアプリケーションサンドボックス内で実行されるコードにユーザーイベン
トは不要です。

Capabilities クラスの使用
Flash Player 9 以降、Adobe AIR 1.0 以降
Capabilities クラスを使用すると、開発者はアプリケーションの実行環境に関する情報を取得できます。Capabilities クラスの様々なプロパティにより、ユーザーのシステムにおける画面解像度、アクセシビリティソフトウェアに対するサポートの有無、ユーザーのオペレーティングシステムの言語、および、現在インストールされている Flash ランタイムのバージョンを知ることができます。

Capabilities クラスのプロパティを確認すれば、実際のユーザー環境に応じてアプリケーションの動作を最適に調整できます。例えば、Capabilities.screenResolutionX および Capabilities.screenResolutionY プロパティを調べることにより、ユーザーのシステムで使用されているディスプレイ解像度を判別し、どのサイズのビデオが最適かを判断できます。また、Capabilities.hasMP3 プロパティを調べれば、外部 MP3 ファイルをロードする前にユーザーのシステムにおける MP3 再生のサポート状況を知ることができます。
次のコードでは、クライアント環境にインストールされている Flash ランタイムのバージョン情報を正規表現で解析しています。
var versionString:String = Capabilities.version;
var pattern:RegExp = /^(\w*) (\d*),(\d*),(\d*),(\d*)$/;
var result:Object = pattern.exec(versionString);
if (result != null){trace("input: " + result.input);trace("platform: " + result[1]);trace("majorVersion: " + result[2]);trace("minorVersion: " + result[3]);trace("buildNumber: " + result[4]);trace("internalBuildNumber: " + result[5]);}else{
trace("Unable to match RegExp.");}ユーザーのシステムの機能に関する情報をサーバーサイドスクリプトに送信してデータベースに保存するには、次のようなActionScript コードを使用します。
var url:String = "log_visitor.cfm";
var request:URLRequest = new URLRequest(url);
request.method = URLRequestMethod.POST;
request.data = new URLVariables(Capabilities.serverString);
var loader:URLLoader = new URLLoader(request);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

839

クライアントのシステム環境

機能の例：システム機能の検出Flash Player 9 以降
この CapabilitiesExplorer の例は、flash.system.Capabilities クラスを使用してユーザーの Flash ランタイムがどのような機能をサポートしているかを判別する方法を示しています。この例から、次の手法を学習できます。

• Capabilities クラスを使用してユーザーの Flash ランタイムのバージョンがサポートしている機能を検出する方法• ExternalInterface クラスを使用してユーザーのブラウザーがサポートしているブラウザー設定を検出する方法
このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。CapabilitiesExplorer アプリケー
ションのファイルは、Samples/CapabilitiesExplorer フォルダーにあります。このアプリケーションは、次のファイルで構成されています。
ファイル

説明

CapabilitiesExplorer.fla

Flash（FLA）または Flex（MXML）のメインアプリケーション
ファイル。

または

CapabilitiesExplorer.mxml
com/example/programmingas3/capabilities/CapabilitiesGrabber.as

配列へのシステム Capabilities の追加、項目のソート、ExternalInterface クラスを使用したブラウザー機能の取得など、ア
プリケーションの主要な機能を提供するクラス。

External API との通信に必要な JavaScript を格納する HTML コン

capabilities.html

テナ。

CapabilitiesExplorer の概要
Flash Player 9 以降
CapabilitiesExplorer.mxml ファイルは、CapabilitiesExplorer アプリケーションのユーザーインターフェイスを設定する
ことに責任を負います。ユーザーの Flash ランタイムのバージョンの機能は、ステージ上の DataGrid コンポーネントインス
タンス内に表示されます。また、ユーザーが HTML コンテナからアプリケーションを実行している場合、しかも External
API が使用可能な場合は、ユーザーのブラウザー機能も表示されます。
メインアプリケーションファイルの creationComplete イベントが送出されると、initApp() メソッドが起動されます。

initApp() メソッドは com.example.programmingas3.capabilities.CapabilitiesGrabber クラスの中から getCapabilities()
メソッドを呼び出します。initApp() メソッドのコードは次のとおりです。
private function initApp():void{
var dp:Array = CapabilitiesGrabber.getCapabilities();
capabilitiesGrid.dataProvider = dp;}

CapabilitiesGrabber.getCapabilities() メソッドは、Flash ランタイム機能およびブラウザー機能のソートされた配列を返します。その後、その配列はステージ上の capabilitiesGrid DataGrid コンポーネントインスタンスの dataProvider プロパティに設定されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

840

クライアントのシステム環境

CapabilitiesGrabber クラスの概要
Flash Player 9 以降
CapabilitiesGrabber クラスの静的 getCapabilities() メソッドは、flash.system.Capabilities クラスからの各プロパティを配列（capDP）に追加します。その後、CapabilitiesGrabber クラス内の静的 getBrowserObjects() メソッドを呼び出します。
getBrowserObjects() メソッドは、External API を使用して、ブラウザーの機能を格納するブラウザーのナビゲーターオブ
ジェクトをループ処理します。getCapabilities() メソッドは、次のとおりです。
public static function getCapabilities():Array{var capDP:Array = new Array();capDP.push({name:"Capabilities.avHardwareDisable", value:Capabilities.avHardwareDisable});capDP.push({name:"Capabilities.hasAccessibility", value:Capabilities.hasAccessibility});capDP.push({name:"Capabilities.hasAudio", value:Capabilities.hasAudio});...
capDP.push({name:"Capabilities.version", value:Capabilities.version});var navArr:Array = CapabilitiesGrabber.getBrowserObjects();
if (navArr.length > 0){
capDP = capDP.concat(navArr);}
capDP.sortOn("name", Array.CASEINSENSITIVE);
return capDP;}

getBrowserObjects() メソッドは、ブラウザーのナビゲーターオブジェクトに含まれる各プロパティの配列を返します。その配列の長さが 1 項目以上である場合、ブラウザー機能の配列（navArr）が Flash Player 機能の配列（capDP）に付加され、配列全体がアルファベット順でソートされます。最後に、ソートされた配列がメインアプリケーションファイルへ返され、
メインアプリケーションファイルがデータグリッドにデータを入れます。getBrowserObjects() メソッドのコードは次のとおりです。
private static function getBrowserObjects():Array{var itemArr:Array = new Array();
var itemVars:URLVariables;
if (ExternalInterface.available){try{
var tempStr:String = ExternalInterface.call("JS_getBrowserObjects");
itemVars = new URLVariables(tempStr);for (var i:String in itemVars){
itemArr.push({name:i, value:itemVars[i]});}}catch (error:SecurityError){// ignore}}
return itemArr;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

841

クライアントのシステム環境

現在のユーザー環境で External API が使用可能な場合、Flash ランタイムは JavaScript の JS_getBrowserObjects() メソッドを呼び出します。このメソッドはブラウザーのナビゲーターオブジェクトをループ処理し、URL エンコードされた値のストリングを ActionScript に返します。このストリングは、その後、URLVariables オブジェクト（itemVars）に変換され、itemArr 配列に追加されます。その配列が、呼び出し元のスクリプトへ返されます。

JavaScript との通信
Flash Player 9 以降
CapabilitiesExplorer アプリケーションを構築する最後の部分は、ブラウザーのナビゲーターオブジェクト内の各項目をループ処理して名前と値のペアを一時配列に付加するために必要な JavaScript を作成することです。container.html ファ
イルに入っている JavaScript JS_getBrowserObjects() メソッドのコードは、次のとおりです。
<script language="JavaScript">function JS_getBrowserObjects(){// Create an array to hold each of the browser's items.
var tempArr = new Array();// Loop over each item in the browser's navigator object.
for (var name in navigator){
var value = navigator[name];// If the current value is a string or Boolean object, add it to the// array, otherwise ignore the item.
switch (typeof(value)){case "string":case "boolean":// Create a temporary string which will be added to the array.
// Make sure that we URL-encode the values using JavaScript's// escape() function.
var tempStr = "navigator." + name + "=" + escape(value);// Push the URL-encoded name/value pair onto the array.
tempArr.push(tempStr);
break;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

842

クライアントのシステム環境}// Loop over each item in the browser's screen object.
for (var name in screen){var value = screen[name];// If the current value is a number, add it to the array, otherwise// ignore the item.
switch (typeof(value)){case "number":var tempStr = "screen." + name + "=" + escape(value);
tempArr.push(tempStr);
break;}}// Return the array as a URL-encoded string of name-value pairs.
return tempArr.join("&");}</script>

このコードは最初に、ナビゲーターオブジェクト内にあるすべての名前と値のペアを保持する一時配列を作成します。次に、ナビゲーターオブジェクトが for..in ループでループ処理され、現在の値のデータ型が評価されます。これにより、不要な値が除外されます。このアプリケーションでは、String 値または Boolean 値だけが注目され、それ以外のデータ型（関数または配列など）は無視されます。ナビゲーターオブジェクト内のそれぞれの String 値または Boolean 値は、tempArr 配列に付加されます。次に、ブラウザーの画面オブジェクトが for..in ループでループ処理され、それぞれの数値が tempArr 配列に追加されます。最後に、一時配列オブジェクトが、Array.join() メソッドでストリングに変換されます。この配列は、アンパサ
ンド（&）を区切り記号として使用します。これにより、ActionScript は URLVariables クラスを使用してデータを簡単に解析できます。

最終更新日 2015/10/14

843

第 50 章：AIR アプリケーションの呼び出しと終了Adobe AIR 1.0 およびそれ以降
この節では、インストールした Adobe® AIR® アプリケーションを呼び出す方法、および実行中のアプリケーションの終了に使用するオプションと考慮事項について説明します。
注意：NativeApplication、InvokeEvent および BrowserInvokeEvent オブジェクトは、AIR アプリケーションサンド
ボックスで実行されている SWF コンテンツでのみ使用できます。Flash Player ランタイムで実行されている SWF コンテンツ、ブラウザーまたはスタンドアローンプレーヤー（プロジェクター）内で実行されている SWF コンテンツおよびアプリ
ケーションサンドボックスの外部の AIR アプリケーションで実行されている SWF コンテンツは、これらのクラスにアクセ
スできません。

AIR アプリケーションの呼び出しと終了に関する簡単な説明およびコード例については、Adobe Developer Connection
で次のクイックスタートの記事を参照してください。

•

起動オプション

関連項目

flash.desktop.NativeApplication
flash.events.InvokeEventflash.events.BrowserInvokeEvent

アプリケーションの呼び出し
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、ユーザー（またはオペレーティングシステム）が次の動作を行った場合に呼び出されます。

•

アプリケーションをデスクトップシェルから起動する。

•

アプリケーションをコマンドラインシェルのコマンドとして使用する。

•

アプリケーションがデフォルトで関連付けられている種類のファイルを開く。

• （Mac OS X）ドックタスクバーでアプリケーションアイコンをクリックする（アプリケーションが現在実行中であるかどうかは問いません）。

•

インストーラーでアプリケーションの起動を選択する（新規インストール作業の最後、またはインストール済みアプリ
ケーションの AIR ファイルをダブルクリックした後）。

•インストールされたバージョンがアプリケーションのアップデートを自動処理していることを表示したときに、AIR ア
プリケーションのアップデートを開始する（アプリケーション記述ファイルに<customUpdateUI>true</customUpdateUI> 宣言を含めている場合）。

• （iOS）Apple Push Notification サービス（APNs）から通知を受信する。
• URL を経由してアプリケーションを起動する。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

844

AIR アプリケーションの呼び出しと終了• AIR アプリケーション向けの識別情報を指定した com.adobe.air.AIR launchApplication() メソッドを呼び出す Flash バッ
ジまたはアプリケーションをホストしている Web ページを表示する（ブラウザーによる呼び出しを可能にするには、ア
プリケーション記述子に <allowBrowserInvocation>true</allowBrowserInvocation> 宣言も含まれている必要があります）。

AIR アプリケーションが呼び出されるたびに、AIR はシングルトンの NativeApplication オブジェクトを通じて、型
invoke の InvokeEvent オブジェクトを送出します。アプリケーション時間が自分自身を初期化し、イベントリスナーを登録できるようにするには、invoke イベントを破棄せず、キューに入れる必要があります。リスナーが登録されると、キューに入れられているすべてのイベントが直ちに送出されます。
注意：ブラウザー呼び出し機能を使用してアプリケーションが呼び出されると、NativeApplication オブジェクトは、そのアプリケーションが既に実行中でなければ、invoke イベントのみを送出します。

invoke イベントを受け取るには、NativeApplication オブジェクト（NativeApplication.nativeApplication）のaddEventListener() メソッドを呼び出します。イベントリスナーは、invoke イベントについて登録されると、登録前に発生したすべての invoke イベントも受け取ります。キューに入れられた invoke イベントは、addEventListener() に対する呼び出しが返された後、短い間隔で一度に 1 つずつ送出されます。このプロセス中に新しい invoke イベントが発生した場合、このイベントを、キューに入れられた 1 つ以上のイベントが送出される前に送出することができます。このイベントキューイング
により、初期化コードが実行される前に発生した任意の invoke イベントを処理できます。イベントリスナーは、実行の比較
的遅い時点（アプリケーション初期化の後）で追加された場合でも、アプリケーション起動後に発生したすべての invoke イ
ベントを受け取ります。

1 つの AIR アプリケーションについて、起動されるインスタンスは 1 つだけです。既に実行されているアプリケーションが再び呼び出されると、AIR は実行中のインスタンスに対して新しい invoke イベントを送出します。invoke イベントに応答し、適切なアクションを実行する（例えば新しいドキュメントウィンドウを開く）ことは、AIR アプリケーションの役割です。

InvokeEvent オブジェクトには、アプリケーションと、そのアプリケーションが呼び出されたディレクトリに渡された任意の引数が格納されます。アプリケーションがファイルの種類による関連付けによって呼び出された場合には、コマンドライ
ン引数にそのファイルへのフルパスが含まれます。同様に、アプリケーションがアプリケーションアップデートのために呼び出された場合には、アップデート AIR ファイルへのフルパスが設定されます。

1 回の操作で複数のファイルが開かれる場合、Mac OS X では InvokeEvent オブジェクトが 1 回送出されます。各ファイル
は arguments 配列に格納されます。Windows および Linux では、各ファイルごとに InvokeEvent オブジェクトが送出されます。
アプリケーションが invoke イベントを処理できるようにするには、その NativeApplication オブジェクトにリスナーを次のように登録します。
NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvokeEvent);

さらに、イベントリスナーを次のように定義します。
var arguments:Array;var currentDir:File;public function onInvokeEvent(invocation:InvokeEvent):void {arguments = invocation.arguments;
currentDir = invocation.currentDirectory;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

845

AIR アプリケーションの呼び出しと終了

コマンドライン引数のキャプチャ
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションの呼び出しに関連するコマンドライン引数は、NativeApplication オブジェクトによって送出される
InvokeEvent オブジェクトで送出されます。InvokeEvent の arguments プロパティには、AIR アプリケーションの呼び出
し時にオペレーティングシステムによって渡される引数の配列が格納されています。引数にファイルの相対パスが含まれている場合、パスを解決するには、通常は currentDirectory プロパティを使用します。

AIR プログラムに渡される引数は、次の表に示すように、二重引用符で囲まれている場合を除いて、空白で区切られたストリングとして扱われます。
引数

配列

tick tock{tick,tock}tick "tick tock"{tick,tick tock}"tick" “tock”{tick,tock}\"tick\" \"tock\"{"tick","tock"}

InvokeEvent オブジェクトの currentDirectory プロパティには、そのアプリケーションが起動されたディレクトリを表す
File オブジェクトが格納されます。
アプリケーションが、そのアプリケーションによって登録された種類のファイルが開かれたことによって呼び出された場合には、そのファイルへのネイティブパスがコマンドライン引数にストリングとして設定されます（ファイルを開いたり、ファイルに対して目的の操作を実行することは、アプリケーションの役割です）。同様に、アプリケーションがアップデート
を自動で（標準の AIR アップデートユーザーインターフェイスを使用せずに）実行するようにプログラムされている場合には、一致するアプリケーション ID を持つアプリケーションを格納した AIR ファイルをユーザーがダブルクリックしたときに、AIR ファイルへのネイティブパスが設定されます。
ファイルにアクセスするには、currentDirectory File オブジェクトの resolve() メソッドを次のように使用します。
if((invokeEvent.currentDirectory != null)&&(invokeEvent.arguments.length > 0)){dir = invokeEvent.currentDirectory;
fileToOpen = dir.resolvePath(invokeEvent.arguments[0]);}

引数が本当にファイルへのパスであるかどうかについても検証する必要があります。

例：呼び出しイベントログ
Adobe AIR 1.0 およびそれ以降
次の例では、invoke イベントに対するリスナーを登録し、このイベントを処理する方法を示します。この例では、受け取ったすべての呼び出しイベントを記録し、現在のディレクトリとコマンドライン引数を表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

846

AIR アプリケーションの呼び出しと終了

ActionScript の例
package{import flash.display.Sprite;
import flash.events.InvokeEvent;import flash.desktop.NativeApplication;
import flash.text.TextField;
public class InvokeEventLogExample extends Sprite{
public var log:TextField;
public function InvokeEventLogExample(){
log = new TextField();
log.x = 15;
log.y = 15;
log.width = 520;
log.height = 370;
log.background = true;
addChild(log);
NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvoke);}public function onInvoke(invokeEvent:InvokeEvent):void{
var now:String = new Date().toTimeString();logEvent("Invoke event received: " + now);
if (invokeEvent.currentDirectory != null){logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath);}
else{
logEvent("--no directory information available--");}
if (invokeEvent.arguments.length > 0){
logEvent("Arguments: " + invokeEvent.arguments.toString());}
else{
logEvent("--no arguments--");}}
public function logEvent(entry:String):void{
log.appendText(entry + "\n");trace(entry);}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

847

AIR アプリケーションの呼び出しと終了

Flex の例<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
invoke="onInvoke(event)" title="Invocation Event Log"><mx:Script><![CDATA[
import flash.events.InvokeEvent;import flash.desktop.NativeApplication;
public function onInvoke(invokeEvent:InvokeEvent):void {var now:String = new Date().toTimeString();logEvent("Invoke event received: " + now);
if (invokeEvent.currentDirectory != null){logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath);} else {logEvent("--no directory information available--");}
if (invokeEvent.arguments.length > 0){
logEvent("Arguments: " + invokeEvent.arguments.toString());} else {logEvent("--no arguments--");}}
public function logEvent(entry:String):void {log.text += entry + "\n";trace(entry);}]]></mx:Script><mx:TextArea id="log" width="100%" height="100%" editable="false"
valueCommit="log.verticalScrollPosition=log.textHeight;"/></mx:WindowedApplication>

ユーザーログイン時の AIR アプリケーションの呼び出し
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションが、現在のユーザーがログインしたときに自動的に起動するように設定するには、
NativeApplication startAtLogin プロパティを true に設定します。このように設定すると、アプリケーションはユーザーがログインすると自動的に起動します。ログイン時にアプリケーションが自動起動しないようにするには、設定を false に変更
するか、ユーザーが設定をオペレーティングシステムから手動で変更するか、またはアプリケーションをアンインストール
します。ログイン時の起動は、実行時設定です。この設定は、現在のユーザーにのみ適用されます。startAtLogin プロパ
ティを true に設定するには、アプリケーションがインストールされている必要があります。アプリケーションがインストー
ルされていない（例えば ADL で起動される）場合、プロパティを設定するとエラーがスローされます。
注意：アプリケーションは、コンピューターシステムの起動時には起動しません。アプリケーションは、ユーザーのログイ
ン時に起動します。
アプリケーションが自動的に起動されたのか、ユーザーアクションの結果起動されたのかを判別するには、InvokeEvent オ
ブジェクトの reason プロパティを確認できます。このプロパティが InvokeEventReason.LOGIN の場合、アプリケーションは自動的に起動したことになります。その他の起動手順については、reason プロパティは次のように設定されます。

• InvokeEventReason.NOTIFICATION（iOS の場合のみ）- アプリケーションは APNs を経由して起動されました。APNs
について詳しくは、「プッシュ通知の使用」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

848

AIR アプリケーションの呼び出しと終了• InvokeEventReason.OPEN_URL - アプリケーションは他のアプリケーションまたはシステムによって起動されました。
• InvokeEventReason.Standard - その他すべての場合。
reason プロパティにアクセスするには、アプリケーションのターゲットを AIR 1.5.1 以降にする必要があります（アプリ
ケーション記述ファイルで正しい名前空間値を設定します）。
次の単純化されたアプリケーションでは、InvokeEvent reason プロパティを使用して、invoke イベントの発生時の動作方法を決定します。reason プロパティが「login」である場合、アプリケーションは背景に留まります。それ以外の場合、メイ
ンアプリケーションが表示されるようになります。このパターンを使用しているアプリケーションは、バックグラウンド処理やイベント監視を実行できるように通常ログイン時に起動し、ユーザーがトリガーした invoke イベントに応じてウィンドウを開きます。
package {import flash.desktop.InvokeEventReason;
import flash.desktop.NativeApplication;
import flash.display.Sprite;
import flash.events.InvokeEvent;public class StartAtLogin extends Sprite{
public function StartAtLogin(){try{
NativeApplication.nativeApplication.startAtLogin = true;}
catch ( e:Error ){trace( "Cannot set startAtLogin:" + e.message );}NativeApplication.nativeApplication.addEventListener( InvokeEvent.INVOKE, onInvoke );}private function onInvoke( event:InvokeEvent ):void{if( event.reason == InvokeEventReason.LOGIN ){//do background processing...
trace( "Running in background..." );}else{
this.stage.nativeWindow.activate();}}}}

注意：動作の違いを確認するには、アプリケーションをパッケージ化してインストールします。startAtLogin プロパティは、
インストール済みのアプリケーションに対してのみ設定できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

849

AIR アプリケーションの呼び出しと終了

ブラウザーからの AIR アプリケーションの呼び出し
Adobe AIR 1.0 およびそれ以降
ブラウザー呼び出し機能を使用すると、Web サイトでは、インストールされている AIR アプリケーションをブラウザーから起動されるように起動できます。ブラウザーによる呼び出しは、アプリケーション記述ファイルで allowBrowserInvocationが次のように true に設定されている場合にのみ許可されます。
<allowBrowserInvocation>true</allowBrowserInvocation>

アプリケーションがブラウザーによって呼び出されると、アプリケーションの NativeApplication オブジェクトはBrowserInvokeEvent オブジェクトを送出します。
BrowserInvokeEvent イベントを受け取るには、AIR アプリケーションの NativeApplication オブジェクト（NativeApplication.nativeApplication）の addEventListener() メソッドを呼び出します。イベントリスナーは、

BrowserInvokeEvent イベントについて登録されると、登録前に発生したすべての BrowserInvokeEvent イベントも受け取ります。これらのイベントは、addEventListener() に対する呼び出しが返された後で送出されますが、登録後に受け取られる可能性のある他の BrowserInvokeEvent イベントよりも前とは限りません。これにより、初期化コードが実行される前（例えばアプリケーションがブラウザーから最初に呼び出されたとき）に発生した BrowserInvokeEvent イベントを処理できます。イベントリスナーは、実行の比較的遅い時点（アプリケーション初期化の後）で追加された場合でも、アプリケー
ション起動後に発生したすべての BrowserInvokeEvent イベントを受け取ります。

BrowserInvokeEvent オブジェクトには、次のプロパティが含まれます。
プロパティ

説明

arguments

アプリケーションに渡す引数（ストリング）の配列。

isHTTPS

ブラウザー内のコンテンツが https URL スキームを使用する（true）か、使用しない（false）かを指定します。

isUserEvent

ブラウザーによる呼び出しがユーザーイベント（例えばマウスクリック）で発生したかどうかを示します。AIR 1.0
では、このプロパティは常に true に設定されます。AIR では、ブラウザー呼び出し機能に対するユーザーイベントが必要です。

sandboxType

ブラウザー内のコンテンツに対して使用するサンドボックスのタイプ。有効値の定義は、Security.sandboxType プ
ロパティで使用できる有効値の場合と同じで、次のいずれかです。

• Security.APPLICATION — コンテンツは、アプリケーションセキュリティサンドボックスで実行されます。
• Security.LOCAL_TRUSTED — コンテンツは、local-with-filesystem セキュリティサンドボックスで実行されます。

• Security.LOCAL_WITH_FILE — コンテンツは、local-with-filesystem セキュリティサンドボックスで実行されます。

• Security.LOCAL_WITH_NETWORK — コンテンツは、local-with-networking セキュリティサンドボックスで実行されます。

• Security.REMOTE — コンテンツは、リモート（ネットワーク）ドメインで実行されます。
securityDomain

ブラウザー内のコンテンツのセキュリティドメイン。例えば「www.adobe.com」や「www.example.org」など。
このプロパティは、リモートのセキュリティサンドボックスで実行されるコンテンツ（ネットワークドメインからのコンテンツ）に対してのみ設定されます。ローカルまたはアプリケーションセキュリティサンドボックスで実行されるコンテンツに対しては設定されません。

ブラウザー呼び出し機能を使用する場合は、セキュリティ上の影響を考慮してください。Web サイトで AIR アプリケー
ションが起動されると、アプリケーションは BrowserInvokeEvent オブジェクトの arguments プロパティを介してデータを送信できます。このデータを、ファイルやコードを読み込む API のような注意を必要とする操作で使用する場合には、慎重に行う必要があります。リスクのレベルは、アプリケーションがそのデータを使用して実行する処理の種類によって異なります。アプリケーションが特定の Web サイトだけで呼び出されることを想定している場合、そのアプリケーションは最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

850

AIR アプリケーションの呼び出しと終了

BrowserInvokeEvent オブジェクトの securityDomain プロパティを検査する必要があります。また、そのアプリケーションを呼び出す Web サイトに対して、HTTPs を使用するように要求することもできます。これは、BrowserInvokeEvent オ
ブジェクトの isHTTPS プロパティを検査することで検証できます。
アプリケーションは、渡されたデータを検証する必要があります。例えば、あるアプリケーションが特定のドメインの URLを渡されることを予期している場合、そのアプリケーションは、その URL が本当にそのドメインを指し示しているかどうかを検証する必要があります。これにより、攻撃者がアプリケーションを不正に操作して重要なデータを送信させることを防ぐことができます。
ローカルのリソースを指し示す可能性のある BrowserInvokeEvent 引数を、アプリケーションで使用しないでください。例
えば、アプリケーションでは、ブラウザーから渡されたパスに基づいて File オブジェクトを作成することは避けてください。ブラウザーからリモートのパスが渡されることを想定している場合、アプリケーションでは、リモートプロトコルの代
わりに file:// プロトコルがパスに使用されていないことを確認する必要があります。

アプリケーションの終了
Adobe AIR 1.0 およびそれ以降
アプリケーションを終了する最も早い方法は、NativeApplication exit() メソッドを呼び出すことです。これは、アプリ
ケーションで保存するデータやクリーンアップするリソースがない場合には、適切に機能します。exit() を呼び出すと、すべてのウィンドウが閉じ、アプリケーションが終了します。しかし、例えば重要なデータを保存するために、アプリケーショ
ンのウィンドウやその他のコンポーネントが終了プロセスを中断できるようにする場合は、exit() を呼び出す前に、適切な警告イベントを送出します。
アプリケーションを適切な手順に従ってシャットダウンするためのもう一つの方法は、シャットダウンプロセスを開始する
方法とは関係なく、単一の実行経路を設定することです。ユーザー（またはオペレーティングシステム）は、次に示す方法
でアプリケーションの終了をトリガーすることができます。

• NativeApplication.nativeApplication.autoExit が true の場合に、最後のアプリケーションウィンドウを閉じる。
•

オペレーティングシステムから、アプリケーション終了コマンドを選択する（例えば、ユーザーがデフォルトのメニュー
からアプリケーションを終了するコマンドを選択した場合）。
（これは Mac OS でのみ可能です。Windows および Linuxでは、システムクロムによるアプリケーション終了コマンドは提供されていません。）•

コンピューターをシャットダウンする。

終了コマンドがオペレーティングシステムを介して、これらのいずれかの方法で渡されると、NativeApplication は exiting
イベントを送出します。リスナーが exiting イベントをキャンセルしなければ、開いているすべてのウィンドウが閉じられます。各ウィンドウは closing イベントを送出し、次に close イベントを送出します。いずれかのウィンドウで closing イベント
がキャンセルされると、シャットダウンプロセスは停止します。
アプリケーションで、ウィンドウを閉じる順序が重要である場合には、NativeApplication からの exiting イベントをリッス
ンし、ユーザー自身がウィンドウを正しい順序で閉じます。これは、例えば、ツールパレットを含むドキュメントウィンド
ウがある場合などに、必要となる可能性があります。システムがパレットを閉じたが、ユーザーはデータを保存するために終了コマンドをキャンセルすることにした、というような場合には、これは非常に不便です。Windows では、exiting イベ
ントを受け取る唯一の機会は、最後のウィンドウを閉じた後です（NativeApplication オブジェクトの autoExit プロパティ
が true に設定されている場合）。
すべてのプラットフォームで一貫性のある動作を実現するためには、終了シーケンスがオペレーティングシステムクロム、
メニューコマンド、アプリケーションロジックのいずれから開始される場合でも、アプリケーションを終了するための、次に示す正しい方法を遵守してください。

1 常に exiting イベントを NativeApplication オブジェクトから、アプリケーションコードで exit() を呼び出す前に送出し、アプリケーションの他のコンポーネントがこのイベントをキャンセルしていないことを確認します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

851

AIR アプリケーションの呼び出しと終了

public function applicationExit():void {var exitingEvent:Event = new Event(Event.EXITING, false, true);
NativeApplication.nativeApplication.dispatchEvent(exitingEvent);
if (!exitingEvent.isDefaultPrevented()) {NativeApplication.nativeApplication.exit();}}

2 NativeApplication.nativeApplication オブジェクトから送出されたアプリケーションの exiting イベントをリッスンし、ハンドラーですべてのウィンドウを閉じます（最初に closing イベントを送出します）。すべてのウィンドウが閉じたら、ア
プリケーションデータの保存や一時ファイルの削除などの必要なクリーンアップタスクを実行します。クリーンアップでは同期メソッドのみを使用することで、アプリケーションの終了前にそれらのメソッドが必ず終了するようにします。
ウィンドウを閉じる順序が重要でない場合は、NativeApplication.nativeApplication.openedWindows 配列をループし、各ウィンドウを順次閉じていきます。順序が重要である場合には、ウィンドウを正しい順序で閉じる手段を提供します。
private function onExiting(exitingEvent:Event):void {var winClosingEvent:Event;for each (var win:NativeWindow in NativeApplication.nativeApplication.openedWindows) {winClosingEvent = new Event(Event.CLOSING,false,true);
win.dispatchEvent(winClosingEvent);
if (!winClosingEvent.isDefaultPrevented()) {win.close();} else {exitingEvent.preventDefault();}}
if (!exitingEvent.isDefaultPrevented()) {//perform cleanup}}

3 各ウィンドウは、それ自身の closing イベントをリッスンすることで、常にそれ自身のクリーンアップを処理する必要があります。

4 アプリケーションでは、使用する exiting リスナーを 1 つだけにします。これは、以前に呼び出されたハンドラーは、後続のハンドラーが exiting イベントをキャンセルするかどうかを知ることができないためです（また、実行の順序に依拠することも賢明ではありません）。

最終更新日 2015/10/14

852

第 51 章：AIR ランタイムとオペレーティングシ
ステムに関する情報の操作
Adobe AIR 1.0 およびそれ以降
この節では、オペレーティングシステムファイルの関連付けの管理、ユーザーアクティビティの検出、Adobe® AIR® ランタ
イムに関する情報の取得を AIR アプリケーションで行う方法について説明します。
関連項目

flash.desktop.NativeApplication

ファイルの関連付けの管理
Adobe AIR 1.0 およびそれ以降
アプリケーションとファイルの種類との関連付けは、アプリケーション記述子で宣言する必要があります。インストールプ
ロセス時、AIR アプリケーションインストーラーでは、宣言済みの各ファイルの種類を開くデフォルトのアプリケーション
として AIR アプリケーションを関連付けます。ただし、別のアプリケーションが既にデフォルトのアプリケーションになっている場合を除きます。AIR アプリケーションのインストールプロセスでは、既存のファイルの種類の関連付けを上書きしません。別のアプリケーションから関連付けを引き継ぐには、実行時に NativeApplication.setAsDefaultApplication() メソッドを呼び出します。
アプリケーションの起動時に、期待されるファイルの関連付けが適切であるかどうかを確認することをお勧めします。この
理由は、AIR アプリケーションインストーラーでは既存のファイルの関連付けを上書きしないため、また、ユーザーのシス
テムにおけるファイルの関連付けは常に変更される可能性があるためです。現在のファイルの関連付けが別のアプリケー
ションに設定されている場合は、既存の関連付けを変更する前にユーザーに確認することも推奨されます。

NativeApplication クラスの次のメソッドを使用すると、アプリケーションでファイルの関連付けを管理できます。各メ
ソッドは、ファイルの種類の拡張子をパラメーターとして受け取ります。
メソッド

isSetAsDefaultApplication()説明
指定されたファイルの種類に AIR アプリケーションが現在関連付けられている場合は、true を返します。

setAsDefaultApplication()

AIR アプリケーションと特定のファイルの種類を開くアクションとの間の関連付けを作成します。

removeAsDefaultApplication()

AIR アプリケーションと特定のファイルの種類との間の関連付けを削除します。

getDefaultApplication()

特定のファイルの種類に現在関連付けられているアプリケーションのパスを報告します。

AIR で管理できるのは、アプリケーション記述子であらかじめ宣言されているファイルの種類の関連付けだけです。宣言されていないファイルの種類の関連付けに関する情報は、そのファイルの種類とアプリケーションの間の関連付けをユーザーが手動で作成した場合も含めて取得できません。アプリケーション記述子で宣言されていないファイルの種類の拡張子を指定して、ファイルの関連付けの管理メソッドを呼び出すと、ランタイム例外がアプリケーションからスローされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

853

AIR ランタイムとオペレーティングシステムに関する情報の操作

ランタイムのバージョンとパッチレベルの取得
Adobe AIR 1.0 およびそれ以降
NativeApplication オブジェクトには、アプリケーションが実行されているランタイムのバージョン（「1.0.5」などのストリング）を示す runtimeVersion プロパティがあります。また、NativeApplication オブジェクトには、ランタイムのパッチ
レベル（2960 などの番号）を示す runtimePatchLevel プロパティもあります。次のコードでは、これらのプロパティを使用します。
trace(NativeApplication.nativeApplication.runtimeVersion);trace(NativeApplication.nativeApplication.runtimePatchLevel);

AIR 機能の検出
Adobe AIR 1.0 およびそれ以降
Adobe AIR アプリケーションに付属するファイルでは、Security.sandboxType プロパティは、Security.APPLICATION 定数
で定義されている値に設定されます。ファイルが Adobe AIR セキュリティサンドボックス内にあるかどうかに基づいて、コンテンツ（AIR 固有の API を含んでいるかどうかわからないコンテンツ）を読み込むことができます。これを次のコードに示します。
if (Security.sandboxType == Security.APPLICATION){// Load SWF that contains AIR APIs}else{// Load SWF that does not contain AIR APIs}

AIR アプリケーションのインストールに含まれないすべてのリソースは、Web ブラウザーの Adobe® Flash® Player によって割り当てられる場合と同じセキュリティサンドボックスに割り当てられます。リモートリソースは、そのソースドメインに従ってサンドボックスに配置され、ローカルリソースは、local-with-networking、local-with-filesystem、local-

trusted のいずれかのサンドボックスに配置されます。
Capabilities.playerType 静的プロパティが「Desktop」に設定されているかどうかをチェックして、コンテンツがランタイムで実行される（ブラウザーで実行される Flash Player では実行されない）かどうかを確認できます。
詳しくは、1038 ページの「AIR のセキュリティ」を参照してください。

ユーザープレゼンスの追跡
Adobe AIR 1.0 およびそれ以降
NativeApplication オブジェクトは、ユーザーがコンピューターをアクティブに使用していることを検出するのに役立つ 2
つのイベントを送出します。NativeApplication.idleThreshold プロパティで指定されている期間内に、マウスまたはキーボードの操作が検出されないと、NativeApplication は userIdle イベントを送出します。キーボードまたはマウスの次回の入力が発生すると、NativeApplication オブジェクトは userPresent イベントを送出します。idleThreshold の期間は秒単位で計測され、デフォルト値は 300（5 分）です。最後のユーザー入力からの経過秒数をNativeApplication.nativeApplication.lastUserInput プロパティから取得することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

854

AIR ランタイムとオペレーティングシステムに関する情報の操作

次のコード行では、アイドル時間のしきい値を 2 分に設定し、userIdle イベントと userPresent イベントをリッスンします。
NativeApplication.nativeApplication.idleThreshold = 120;
NativeApplication.nativeApplication.addEventListener(Event.USER_IDLE, function(event:Event) {trace("Idle");});NativeApplication.nativeApplication.addEventListener(Event.USER_PRESENT, function(event:Event) {trace("Present");});

注意：2 つの userPresent イベントの間に、userIdle イベントが 1 つだけ送出されます。

最終更新日 2015/10/14

855

第 52 章：AIR ネイティブウィンドウの操作
Adobe AIR 1.0 およびそれ以降
デスクトップウィンドウを作成および管理するには、Adobe® AIR® ネイティブウィンドウ API のクラスを使用します。

AIR のネイティブウィンドウの基礎
Adobe AIR 1.0 およびそれ以降
AIR でのネイティブウィンドウの操作に関する簡単な説明およびコード例については、Adobe Developer Connection で
次のクイックスタートの記事を参照してください。

•

透明ウィンドウアプリケーションの作成（Flex）•

ウィンドウの操作（Flex）•

ウィンドウの外観のカスタマイズ（Flex）•

ウィンドウの起動（Flex）•

トーストスタイルのウィンドウの作成（Flex）•

ウィンドウの表示順序の制御（Flex）•

サイズ変更可能な、矩形でないウィンドウの作成（Flex）•

ウィンドウの操作（Flash）•

ウィンドウの外観のカスタマイズ（Flash）•

トーストスタイルのウィンドウの作成（Flash）•

ウィンドウの表示順序の制御（Flash）•

サイズ変更可能な、矩形でないウィンドウの作成（Flash）

AIR には、Flash®、Flex™ および HTML のプログラミング技法を使用してオペレーティングシステムのネイティブウィン
ドウを作成するための、簡単に使用できるクロスプラットフォームのウィンドウ API が用意されています。
AIR では、アプリケーションの外観を柔軟に開発できます。ユーザーが作成するウィンドウは、標準のデスクトップアプリ
ケーションのようになります。Macintosh で実行する場合は Apple スタイルに一致し、Windows で実行する場合はMicrosoft の規則に準拠し、Linux で実行する場合はウィンドウマネージャーに適合します。いずれの場合も、プラット
フォーム固有のコード行を含める必要はありません。または、Flex フレームワークで提供されているスキンとして使用できて拡張性のあるクロムを使用して、アプリケーションの実行環境に左右されない独自のスタイルを作成することもできます。
さらには、デスクトップに対する透明度とアルファブレンドを完全にサポートするベクトルとビットマップのアートワーク
を使用して、独自のウィンドウクロムを描画することもできます。矩形のウィンドウに飽きているなら、丸いウィンドウを作成してみてください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

856

AIR ネイティブウィンドウの操作

AIR のウィンドウ
Adobe AIR 1.0 およびそれ以降
AIR では、ウィンドウを操作するための 3 つの API がサポートされています。

• ActionScript 指向の NativeWindow クラスは、最下位レベルのウィンドウ API を提供します。NativeWindows は、ActionScript および Flash Professional オーサリングによるアプリケーションで使用します。アプリケーションで使用する目的に特化したウィンドウを作成する場合は、NativeWindow クラスの拡張を検討してください。
• HTML 環境では、ブラウザーベースの Web アプリケーションの場合と同じように JavaScript Window クラスを使用できます。JavaScript Window メソッドの呼び出しは、基になるネイティブウィンドウオブジェクトに転送されます。
• Flex framework mx:WindowedApplication クラスおよび mx:Window クラスは、NativeWindow クラスに Flex の「ラッパー」を提供します。Flex を使用して作成した AIR アプリケーションを Flex アプリケーションの初期ウィンドウとして使用する必要がある場合、WindowedApplication コンポーネントは Application コンポーネントを置き換えます。

ActionScript ウィンドウ
NativeWindow クラスでウィンドウを作成するときは、Flash Player のステージと表示リストを直接使用します。
NativeWindow に表示オブジェクトを追加するには、ウィンドウステージの表示リストまたはステージの別の表示オブジェクトコンテナにオブジェクトを追加します。

HTML ウィンドウHTML ウィンドウを作成するときは、HTML、CSS および JavaScript を使用してコンテンツを表示します。表示オブジェ
クトを HTML ウィンドウに追加するには、そのコンテンツを HTML DOM に追加します。HTML ウィンドウは、
NativeWindow の特殊なカテゴリです。AIR ホストでは、基になる NativeWindow インスタンスへのアクセスを提供する
nativeWindow プロパティが、HTML ウィンドウで定義されています。このプロパティを使用して、ここで説明する
NativeWindow のプロパティ、メソッドおよびイベントにアクセスできます。
注意：また、JavaScript の Window オブジェクトには、moveTo() や close() など、コンテナウィンドウのスクリプトを作成するためのメソッドもあります。オーバーラップするメソッドを使用できる場合は、どれでも便利なメソッドを使用してかまいません。

Flex フレームワークウィンドウ
Flex フレームワークでウィンドウを作成するときは、通常、MXML コンポーネントを使用してウィンドウを設定します。
Flex コンポーネントをウィンドウに追加するには、コンポーネントエレメントをウィンドウの MXML 定義に追加します。
また、ActionScript を使用してコンテンツを動的に追加することもできます。mx:WindowedApplication コンポーネントと mx:Window コンポーネントは Flex コンテナとして作られているので、Flex コンポーネントを動的に受け入れることができますが、NativeWindow オブジェクトはできません。必要な場合は、nativeWindow プロパティを使用してWindowedApplication オブジェクトおよび Window オブジェクトを通して、NativeWindow のプロパティとメソッドにアクセスできます。
初期アプリケーションウィンドウ
アプリケーションの最初のウィンドウは、AIR によって自動的に作成されます。AIR は、アプリケーション記述ファイルのinitialWindow エレメントで指定されているパラメーターを使用して、ウィンドウのプロパティとコンテンツを設定します。
ルートコンテンツが SWF ファイルの場合、AIR は NativeWindow インスタンスを作成して、SWF ファイルを読み込み、それをウィンドウステージに追加します。ルートコンテンツが HTML ファイルの場合、AIR は HTML ウィンドウを作成
して HTML を読み込みます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

857

AIR ネイティブウィンドウの操作

ネイティブウィンドウクラス
Adobe AIR 1.0 およびそれ以降
ネイティブウィンドウ API には、次のクラスが含まれます。
パッケージ

クラス

flash.display• NativeWindow• NativeWindowInitOptions• NativeWindowDisplayState• NativeWindowResize• NativeWindowSystemChrome• NativeWindowType

flash.events• NativeWindowBoundsEvent• NativeWindowDisplayStateEvent

ネイティブウィンドウのイベントフロー
Adobe AIR 1.0 およびそれ以降
ネイティブウィンドウは、イベントを送出して、重要な変更が発生しようとしていること、または既に発生したことを、関係するコンポーネントに通知します。多くのウィンドウ関連イベントは、ペアで送出されます。最初のイベントは、変更が発生しようとしていることを警告します。2 番目のイベントは、変更が行われたことを通知します。警告イベントはキャン
セルできますが、通知イベントはキャンセルできません。次のシーケンスは、ユーザーがウィンドウの最大化ボタンをクリックすると発生するイベントのフローを示したものです。

1 NativeWindow オブジェクトが、displayStateChanging イベントを送出します。
2 登録済みのどのリスナーもイベントをキャンセルしない場合、ウィンドウは最大化します。
3 NativeWindow オブジェクトが、displayStateChange イベントを送出します。
さらに、NativeWindow オブジェクトはウィンドウのサイズと位置に関連する変更についてのイベントも送出します。
これらの関連する変更については、警告イベントは送出されません。次のような関連イベントがあります。

a 最大化操作によりウィンドウの左上隅の位置が移動した場合、move イベントが送出されます。
b 最大化操作によりウィンドウのサイズが変更された場合、resize イベントが送出されます。

NativeWindow オブジェクトは、ウィンドウを最小化する、元のサイズに戻す、閉じる、移動する、サイズ変更するときも、同様のシーケンスでイベントを送出します。
警告イベントは、ウィンドウクロムまたはその他のオペレーティングシステムによって制御されるメカニズムを通して変更が開始されるときにのみ、送出されます。ウィンドウメソッドを呼び出してウィンドウのサイズ、位置、表示状態を変更すると、ウィンドウは変更を通知するイベントのみを送出します。必要な場合は、ウィンドウの dispatchEvent() メ
ソッドを使用して警告イベントを送出した後、警告イベントがキャンセルされたかどうかを確認してから、変更を継続できます。
ウィンドウ API のクラス、メソッド、プロパティおよびイベントについて詳しくは、『Adobe Flash Platform 用
ActionScript 3.0 リファレンスガイド』を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

858

AIR ネイティブウィンドウの操作

ネイティブウィンドウのスタイルと動作を制御するプロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
ウィンドウの基本的な外観と動作は、次のプロパティが制御します。

• type• systemChrome• transparent• owner
ウィンドウを作成するときは、ウィンドウコンストラクターに渡す NativeWindowInitOptions オブジェクトで、これらのプロパティを設定します。AIR は、初期アプリケーションウィンドウのプロパティを、アプリケーション記述子から読み取
ります（ただし、type プロパティはアプリケーション記述子では設定できず、常に normal に設定されます）。ウィンドウの作成後に、プロパティを変更することはできません。
これらのプロパティの設定の中には、同時に指定できないものがあります。例えば、transparent が true のとき、または typeが lightweight のときには、systemChrome を standard に設定することはできません。

ウィンドウタイプ
Adobe AIR 1.0 およびそれ以降
AIR のウィンドウタイプでは、ネイティブオペレーティングシステムの chrome 属性と visibility 属性を結合して、ウィンドウの 3 つの機能タイプを作成します。コードでタイプ名を参照するには、NativeWindowType クラスで定義されている定数を使用します。AIR には次のウィンドウタイプがあります。
型

説明normal

一般的なウィンドウです。normal ウィンドウは、フルサイズスタイルのクロムを使用し、Windows のタスクバー
および Mac OS X のウィンドウメニューに表示されます。

utility

ツールパレットです。utility ウィンドウはスリムなバージョンのシステムクロムを使用し、Windows のタスクバー
および Mac OS X のウィンドウメニューには表示されません。

lightweight

lightweight ウィンドウはクロムを持たず、Windows のタスクバーおよび Mac OS-X のウィンドウメニューには表示されません。また、lightweight ウィンドウには、Windows のシステムメニュー（Alt + Space）がありません。
lightweight ウィンドウは、通知バブルや、短時間だけ表示される領域を開くコンボボックスなどのコントロールに適しています。lightweight の type を使用するときは、systemChrome を none に設定する必要があります。

ウィンドウクロム
Adobe AIR 1.0 およびそれ以降
ウィンドウクロムは、ユーザーがデスクトップ環境内のウィンドウを操作できるようにする一連のコントロールです。クロ
ムエレメントには、タイトルバー、タイトルバーボタン、ボーダー、サイズ変更グリップなどがあります。
システムクロム

systemChrome プロパティには、standard または none を設定できます。ユーザーのオペレーティングシステムによって作成
およびスタイル設定される標準コントロールのセットをウィンドウで使用するには、standard システムクロムを選択します。
ウィンドウに独自のクロムを使用するには、none を選択します。コードでシステムクロムの設定を参照するには、
NativeWindowSystemChrome クラスで定義されている定数を使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

859

AIR ネイティブウィンドウの操作

システムクロムは、システムによって管理されます。アプリケーションでは、コントロール自体に直接アクセスすることはできませんが、コントロールが使用されるときに送出されるイベントには対応できます。ウィンドウに標準のクロムを使用する場合は、transparent プロパティを false に設定し、type プロパティを normal または utility に設定する必要があります。

Flex クロム
Flex の WindowedApplication コンポーネントまたは Window コンポーネントを使用する場合は、システムクロムまたはFlex フレームワークで提供されるクロムをウィンドウで使用できます。Flex クロムを使用するには、ウィンドウの作成に使用する systemChrome プロパティを none に設定します。mx コンポーネントではなく Flex 4 spark コンポーネントを使用する場合は、Flex クロムを使用するためにスキンクラスを指定する必要があります。ビルトインスキンを使用するか、または独自のスキンを指定できます。次の例では、ビルトインの spark の WindowedApplication スキンクラスを使用してウィン
ドウクロムを提供する方法を示します。
<?xml version="1.0" encoding="utf-8"?><s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"xmlns:mx="library://ns.adobe.com/flex/mx"><fx:Style>@namespace "library://ns.adobe.com/flex/spark";
WindowedApplication{
skinClass:ClassReference("spark.skins.spark.SparkChromeWindowedApplicationSkin");}</fx:Style></s:WindowedApplication>

詳しくは、『Using Flex 4』の「About the AIR window containers」の「Controlling window chrome」を参照してくだ
さい。
カスタムクロム
システムクロムを使用しないでウィンドウを作成する場合は、独自のクロムコントロールを追加して、ユーザーとウィンドウの間の対話を処理する必要があります。また、透明で非矩形のウィンドウを作成してもかまいません。

mx:WindowedApplication または mx:Window コンポーネントでカスタムクロムを使用するには、showFlexChrome スタ
イルを false に設定する必要があります。そうしないと、Flex によって独自のクロムがウィンドウに追加されます。

ウィンドウの透明度
Adobe AIR 1.0 およびそれ以降
ウィンドウとデスクトップまたは他のウィンドウとのアルファブレンドを可能にするには、transparent プロパティを true に設定します。transparent プロパティは、ウィンドウを作成する前に設定する必要があり、変更することはできません。
透明なウィンドウには、デフォルトの背景はありません。アプリケーションによって描画されたオブジェクトを含まない
ウィンドウ領域は表示されません。表示されたオブジェクトのアルファ設定が 1 未満の場合は、同じウィンドウ内の他の表
示オブジェクト、他のウィンドウ、デスクトップなど、オブジェクトの下にあるすべてのものが透けて見えます。
ボーダーが不規則な形のウィンドウ、または「フェードアウト」するウィンドウや不可視のウィンドウを作成するには、透明なウィンドウが便利です。ただし、大きいアルファブレンド領域のレンダリングには時間がかかる場合があるので、この効果は控えめに使用する必要があります。
重要：Linux の場合、マウスイベントは完全に透明なピクセルを通過できません。完全に透明で面積が広いウィンドウを作成すると、見えないウィンドウによってユーザーの操作がブロックされ、デスクトップ上にある他のウィンドウやアイテム
がアクセス不能になるため、望ましくありません。Mac OS X および Windows の場合、マウスイベントは完全に透明なピ
クセルを通過します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

860

AIR ネイティブウィンドウの操作

透明度は、システムクロムを使用するウィンドウでは使用できません。さらに、HTML 内の SWF コンテンツと PDF コン
テンツは、透明ウィンドウに表示されない場合があります。詳しくは、968 ページの「HTML ページに SWF コンテンツまたは PDF コンテンツを読み込む場合の考慮事項」を参照してください。
ウィンドウの透明度が使用可能かどうかは、静的な NativeWindow.supportsTransparency プロパティによって報告されます。
透明度がサポートされていない場合、アプリケーションの背景は黒になります。この場合、アプリケーションの透明領域は不透明の黒として表示されます。このプロパティがテストで false になった場合のために、フォールバックを用意することをお勧めします。例えば、警告ダイアログをユーザーに表示するか、矩形の不透明なユーザーインターフェイスを表示することができます。

Windows および Macintosh オペレーティングシステムでは、常に透明度がサポートされます。Linux オペレーティングシ
ステムでのサポートには、合成ウィンドウマネージャーが必要ですが、合成ウィンドウマネージャーがアクティブな場合でも、ユーザーの表示オプションまたはハードウェア構成により、透明度は使用できません。

MXML アプリケーションウィンドウでの透明度
Adobe AIR 1.0 およびそれ以降
デフォルトでは、MXML ウィンドウの背景は、transparent としてウィンドウを作成した場合でも不透明です（透明効果はウィンドウの角でわかります）。ウィンドウの背景を透明にするには、スタイルシートまたはアプリケーションの MXML
ファイルに含まれる <mx:Style> エレメントで、背景の色とアルファ値を設定します。例えば、次のスタイル宣言を使用す
ると、背景は少しだけ透明な緑色のシェードになります。
WindowedApplication{
background-alpha:".8";background-color:"0x448234";}

HTML アプリケーションウィンドウでの透明度
Adobe AIR 1.0 およびそれ以降
デフォルトでは、HTML ウィンドウおよび HTMLLoader オブジェクトに表示される HTML コンテンツの背景は、コン
テナウィンドウが透明であっても不透明です。HTML コンテンツに表示されるデフォルトの背景をオフにするには、
paintsDefaultBackground プロパティを false に設定します。次の例では、HTMLLoader を作成し、デフォルトの背景をオフにしています。
var htmlView:HTMLLoader = new HTMLLoader();
htmlView.paintsDefaultBackground = false;

この例では、JavaScript を使用して HTML ウィンドウのデフォルトの背景をオフにしています。
window.htmlLoader.paintsDefaultBackground = false;

HTML ドキュメント内のエレメントに背景色を設定すると、そのエレメントの背景は透明ではなくなります。透明度（または不透明度）の値の部分的な設定は、サポートされていません。ただし、透明な PNG 形式のグラフィックをページまたはページエレメントの背景として使用することで、同じような視覚効果を得ることができます。

ウィンドウの所有権
1 つのウィンドウは、1 つ以上の他のウィンドウを所有できます。所有されているウィンドウは、常にマスターウィンドウの前面に表示され、マスターウィンドウと共に最小化と復元が実行され、マスターウィンドウが閉じられると一緒に閉じられます。ウィンドウの所有権を他のウィンドウに転送したり、削除したりすることはできません。複数のウィンドウが同じ

1 つのウィンドウを所有することはできませんが、1 つのウィンドウが複数のウィンドウを所有することはできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

861

AIR ネイティブウィンドウの操作

ウィンドウの所有機能を使用することで、ツールパレットやダイアログに使用されるウィンドウの管理が簡単になります。
例えば、ドキュメントウィンドウに関連する保存ダイアログを表示する場合、ドキュメントウィンドウを保存ダイアログの所有者として設定しておくことによって、自動的にドキュメントウィンドウの前面にダイアログを表示し続けることができます。

• NativeWindow.owner• Christian Cantrell：Owned windows in AIR 2.6

表示ウィンドウカタログ
Adobe AIR 1.0 およびそれ以降
次の表に、異なるウィンドウプロパティ設定の組み合わせが Mac OS X、Windows および Linux オペレーティングシステ
ムでどのような視覚効果になるかを示します。
ウィンドウ設定

Mac OS X

Microsoft Windows

Type：normal
SystemChrome：standard
Transparent：false

Type：utility
SystemChrome：standard
Transparent：false

最終更新日 2015/10/14

Linux*ACTIONSCRIPT 3.0 開発ガイド

862

AIR ネイティブウィンドウの操作

ウィンドウ設定

Mac OS X

Microsoft Windows

Linux*

Type：Any
SystemChrome ：none
Transparent：false

Type：Any
SystemChrome ：none
Transparent：true

mxWindowedApplication または
mx:Window
Type：Any
SystemChrome ：none
Transparent：true*Ubuntu と Compiz ウィンドウマネージャー

注意：Mac OS X ツールバー、Mac OS X プロキシアイコン、Windows タイトルバーアイコン、代替システムクロムの各
システムクロムエレメントは、AIR ではサポートされていません。

ウィンドウの作成
Adobe AIR 1.0 およびそれ以降
アプリケーションの最初のウィンドウは AIR によって自動的に作成されますが、必要に応じて任意の追加ウィンドウを作成できます。ネイティブウィンドウを作成するには、NativeWindow コンストラクターメソッドを使用します。

HTML ウィンドウを作成するには、HTMLLoader の createRootWindow() メソッドを使用するか、または HTML ドキュ
メントから JavaScript の window.open() メソッドを呼び出します。作成されたウィンドウは、表示リストに HTMLLoader
オブジェクトを含む NativeWindow オブジェクトとなります。HTMLLoader オブジェクトは、ウィンドウの HTML および JavaScript コンテンツを解釈して表示します。window.nativeWindow プロパティを使用して、基になる NativeWindow
オブジェクトのプロパティに JavaScript からアクセスできます（このプロパティには、AIR アプリケーションサンドボック
スで実行されているコードでのみアクセスできます）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

863

AIR ネイティブウィンドウの操作

ウィンドウを初期化するときは（最初のアプリケーションウィンドウを含む）、ウィンドウを非表示の状態で作成し、コンテ
ンツのロードまたはグラフィックの更新を実行した後で、ウィンドウを表示することを検討する必要があります。このシーケンスにより、目障りな視覚的変化がユーザーに表示されないようにすることができます。アプリケーションの初期ウィン
ドウが非表示の状態で作成されるようにするには、アプリケーション記述ファイルで <visible>false</visible> タグを指定します（この値はデフォルトで false になっているので、省略しても構いません）。新しい NativeWindows はデフォルトで非表示になります。HTMLLoader の createRootWindow() メソッドを使用して HTML ウィンドウを作成する場合は、visible 引
数を false に設定します。ウィンドウを表示するには、NativeWindow の activate() メソッドを呼び出すか、visible プロパ
ティを true に設定します。

ウィンドウの初期化プロパティの指定
Adobe AIR 1.0 およびそれ以降
デスクトップウィンドウの作成後に、ネイティブウィンドウの初期化プロパティを変更することはできません。このような不変のプロパティとそのデフォルト値は次のとおりです。
プロパティ

デフォルト値

systemChrome

standard

type

normaltransparent

false

owner

null

maximizabletrue

minimizabletrue

resizabletrue

AIR によって作成される初期ウィンドウのプロパティは、アプリケーション記述ファイルで設定します。AIR アプリケー
ションのメインウィンドウのタイプは、常に normal です（記述ファイルでは、visible、width、height などの他のウィンド
ウプロパティを指定することができますが、これらのプロパティはいつでも変更できます）。
アプリケーションで作成する他のネイティブウィンドウおよび HTML ウィンドウのプロパティは、
NativeWindowInitOptions クラスを使用して設定します。ウィンドウを作成するときは、ウィンドウプロパティを指定す
る NativeWindowInitOptions オブジェクトを、NativeWindow コンストラクター関数または HTMLLoader

createRootWindow() メソッドに渡す必要があります。
次のコードでは、UTILITY ウィンドウの NativeWindowInitOptions オブジェクトを作成します。
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.type = NativeWindowType.UTILITY
options.transparent = false;
options.resizable = false;
options.maximizable = false;transparent が true のとき、または type が lightweight のときに、systemChrome を standard に設定することはできません。
注意：JavaScript の window.open() 関数で作成するウィンドウの初期化プロパティは設定できません。ただし、独自のHTMLHost クラスを実装することで、これらのウィンドウの作成方法をオーバーライドすることはできます。詳しくは、
978 ページの「window.open() の JavaScript 呼び出しの処理」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

864

AIR ネイティブウィンドウの操作

Flex mx:Window クラスでウィンドウを作成するときは、ウィンドウオブジェクト自体で初期化プロパティを指定します。
指定は、ウィンドウの MXML 宣言またはウィンドウを作成するコードの中で行います。基になる NativeWindow オブジェクトは、open() メソッドを呼び出すまで作成されません。ウィンドウが開かれた後に、これらの初期化プロパティを変更することはできません。

初期アプリケーションウィンドウの作成
Adobe AIR 1.0 およびそれ以降
AIR は、アプリケーション記述子で指定されているプロパティに基づいて初期アプリケーションウィンドウを作成し、content エレメントで参照されているファイルを読み込みます。content エレメントは、SWF ファイルまたは HTML ファ
イルを参照する必要があります。
初期ウィンドウは、アプリケーションのメインウィンドウであっても、1 つ以上の他のウィンドウを起動するためだけのものであってもかまいません。表示する必要もありません。

ActionScript での初期ウィンドウの作成
Adobe AIR 1.0 およびそれ以降
ActionScript を使用して AIR アプリケーションを作成する場合、アプリケーションのメインクラスは Sprite クラス（または Sprite のサブクラス）を拡張する必要があります。このクラスは、アプリケーションのメインのエントリポイントとしての役割を果たします。
アプリケーションを起動すると、AIR はウィンドウを作成し、メインクラスのインスタンスを作成して、ウィンドウステー
ジにインスタンスを追加します。ウィンドウにアクセスするには、addedToStage イベントをリッスンした後、Stage オブ
ジェクトの nativeWindow プロパティを使用して、NativeWindow オブジェクトへの参照を取得します。
次の例では、ActionScript で作成された AIR アプリケーションのメインクラスの基本的な構造を示します。
package {import flash.display.NativeWindow;
import flash.display.Sprite;
import flash.events.Event;public class MainClass extends Sprite{
private var mainWindow:NativeWindow;
public function MainClass(){
this.addEventListener(Event.ADDED_TO_STAGE, initialize);}
private function initialize(event:Event):void{
mainWindow = this.stage.nativeWindow;//perform initialization...
mainWindow.activate(); //show the window}}}

注意：一般に、nativeWindow プロパティにはメインクラスのコンストラクター関数でアクセスできます。ただし、これは初期アプリケーションウィンドウにのみ適用される特殊なケースです。

Flash Professional でアプリケーションを作成するときに、別個の ActionScript ファイル内に独自のクラスを作成しない場
合は、メインドキュメントクラスが自動的に作成されます。初期ウィンドウの NativeWindow オブジェクトには、ステー
ジの nativeWindow プロパティを使用してアクセスできます。例えば、次のコードは、メインウィンドウを（タイムライン
から）最大化状態でアクティブにします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

865

AIR ネイティブウィンドウの操作

import flash.display.NativeWindow;
var mainWindow:NativeWindow = this.stage.nativeWindow;
mainWindow.maximize();
mainWindow.activate();Flex での初期ウィンドウの作成
Adobe AIR 1.0 およびそれ以降
Flex フレームワークで AIR アプリケーションを作成するときは、メイン MXML ファイルのルートエレメントとして
mx:WindowedApplication を使用します（mx:Application コンポーネントも使用できますが、このコンポーネントはAIR で使用できる機能のすべてをサポートしているわけではありません）。WindowedApplication コンポーネントは、ア
プリケーションに対する初期エントリポイントとして機能します。
アプリケーションを起動すると、AIR はネイティブウィンドウを作成し、Flex フレームワークを初期化して、WindowedApplication オブジェクトをウィンドウステージに追加します。起動シーケンスが終了すると、WindowedApplication は applicationComplete イベントを送出します。デスクトップウィンドウオブジェクトには、WindowedApplication インスタンスの nativeWindow プロパティを使用してアクセスします。
次の例では、x 座標と y 座標を設定する簡単な WindowedApplication コンポーネントを作成します。
<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
applicationComplete="placeWindow()"><mx:Script><![CDATA[
private function placeWindow():void{
this.nativeWindow.x = 300;
this.nativeWindow.y = 300;}]]></mx:Script><mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/></mx:WindowedApplication>

NativeWindow の作成
Adobe AIR 1.0 およびそれ以降
NativeWindow を作成するには、NativeWindowInitOptions オブジェクトを NativeWindow コンストラクターに渡します。
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.transparent = false;
var newWindow:NativeWindow = new NativeWindow(options);

ウィンドウは、visible プロパティを true に設定すると、または activate() メソッドを呼び出すと表示されます。
ウィンドウが作成されたなら、ステージプロパティと Flash 表示リストの技法を使用して、ウィンドウのプロパティを初期化し、コンテンツをウィンドウに読み込むことができます。
ほとんどの場合は、新しいネイティブウィンドウのステージプロパティ scaleMode を noScale に設定する必要があります（StageScaleMode.NO_SCALE 定数を使用）。Flash スケールモードは、アプリケーション作成者がアプリケーション表示領域の縦横比を事前に知ることができない状況のために用意されています。スケールモードを使用することで、作成者は、コンテンツのクリッピング、拡大や縮小、または空き領域でのパディングから、最も影響の小さいものを選択できます。表示領
域は AIR（ウィンドウフレーム）で制御するので、悪影響を与えることなく、ウィンドウのサイズをコンテンツに、またはコンテンツのサイズをウィンドウに合わせることができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

866

AIR ネイティブウィンドウの操作

Flex および HTML ウィンドウのスケールモードは、noScale に自動的に設定されます。
注意：現在のオペレーティングシステムで許される最大および最小のウィンドウサイズを判別するには、次の静的

NativeWindow プロパティを使用します。
var maxOSSize:Point = NativeWindow.systemMaxSize;
var minOSSize:Point = NativeWindow.systemMinSize;HTML ウィンドウの作成
Adobe AIR 1.0 およびそれ以降
HTML ウィンドウを作成するには、JavaScript で Window.open() メソッドを呼び出すか、または AIR で HTMLLoader ク
ラスの createRootWindow() メソッドを呼び出します。
セキュリティサンドボックス内の HTML コンテンツは、JavaScript の標準の Window.open() メソッドを使用できます。コンテンツがアプリケーションサンドボックスの外部で実行している場合は、マウスクリックやキー押下などのユーザー操作に対して呼び出すことができるのは、open() メソッドだけです。open() を呼び出すと、指定した URL にあるコンテンツを表示するために、システムクロムを使用するウィンドウが作成されます。次に、例を示します。
newWindow = window.open("xmpl.html", "logWindow", "height=600, width=400, top=10, left=10");

注意：ActionScript で HTMLHost クラスを拡張し、JavaScript の window.open() 関数で作成されるウィンドウをカスタマ
イズできます。972 ページの「HTMLHost クラスの拡張について」を参照してください。
アプリケーションセキュリティサンドボックス内のコンテンツは、ウィンドウ作成用のさらに強力なメソッドである

HTMLLoader.createRootWindow() にアクセスできます。このメソッドを使用すると、新規ウィンドウ用のすべての作成オプ
ションを指定できます。例えば、次の JavaScript コードでは、システムクロムを使用しない最小タイプウィンドウを、

300x400 ピクセルのサイズで作成しています。
var options = new air.NativeWindowInitOptions();
options.systemChrome = "none";
options.type = "lightweight";
var windowBounds = new air.Rectangle(200,250,300,400);
newHTMLLoader = air.HTMLLoader.createRootWindow(true, options, true, windowBounds);
newHTMLLoader.load(new air.URLRequest("xmpl.html"));

注意：新しいウィンドウによって読み込まれたコンテンツがアプリケーションセキュリティサンドボックスの外部にある場
合は、ウィンドウオブジェクトには AIR プロパティの runtime、nativeWindow、または htmlLoader はありません。
透明ウィンドウを作成する場合は、そのウィンドウに読み込まれた HTML に埋め込まれている SWF コンテンツは、常に表示されるとは限りません。SWF ファイルを参照するために使用されるオブジェクトまたは埋め込みタグの wmode パラ
メーターを、opaque または transparent のどちらかに設定する必要があります。wmode のデフォルト値は window なので、
デフォルトでは、SWF コンテンツは透明ウィンドウに表示されません。どの wmode 値が設定されていようと、PDF コンテ
ンツを透明ウィンドウに表示することはできません（AIR 1.5.2 より前のバージョンでは、SWF コンテンツも透明ウィンド
ウに表示することはできませんでした）。

createRootWindow() メソッドで作成したウィンドウは、それを開いたウィンドウから独立したままになります。JavaScript
Window オブジェクトの parent プロパティと opener プロパティは、null です。新しいウィンドウを開いたウィンドウは、
createRootWindow() 関数から返る HTMLLoader の参照を使用して、新しいウィンドウの Window オブジェクトにアクセスできます。前記の例のコンテキストでは、ステートメント newHTMLLoader.window は作成されたウィンドウのJavaScript Window オブジェクトを参照します。
注意：createRootWindow() 関数は、JavaScript と ActionScript のどちらからでも呼び出すことができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

867

AIR ネイティブウィンドウの操作

mx:Window の作成
Adobe AIR 1.0 およびそれ以降
mx:Window を作成するには、mx:Window をルートタグとして使用する MXML ファイルを作成するか、または
Window クラスのコンストラクターを直接呼び出します。
次の例では、Window コンストラクターを呼び出して、mx:Window を作成および表示しています。
var newWindow:Window = new Window();
newWindow.systemChrome = NativeWindowSystemChrome.NONE;
newWindow.transparent = true;
newWindow.title = "New Window";
newWindow.width = 200;
newWindow.height = 200;
newWindow.open(true);

ウィンドウへのコンテンツの追加
Adobe AIR 1.0 およびそれ以降
AIR ウィンドウにコンテンツを追加する方法は、ウィンドウのタイプによって異なります。例えば、MXML と HTML では、ウィンドウの基本的なコンテンツを宣言的に定義できます。リソースをアプリケーションの SWF ファイルに埋め込む
ことも、別のアプリケーションファイルからリソースを読み込むこともできます。Flex、Flash、HTML のコンテンツはい
ずれも、同時進行で作成し、ウィンドウに動的に追加できます。

SWF コンテンツ、または JavaScript を含む HTML コンテンツを読み込むときは、AIR のセキュリティモデルを考慮する必要があります。アプリケーションセキュリティサンドボックス内のコンテンツ、つまりアプリケーションでインストール
されて、app: URL スキームで読み込み可能なコンテンツは、すべての AIR API にアクセスできる完全な権限を持っています。このサンドボックスの外部から読み込まれるコンテンツは、AIR API にアクセスできません。アプリケーションサンド
ボックスの外部にある JavaScript コンテンツは、JavaScript Window オブジェクトの runtime、nativeWindow、または

htmlLoader プロパティを使用できません。
安全なクロススクリプトを可能にするには、サンドボックスブリッジを使用して、アプリケーションコンテンツと非アプリ
ケーションコンテンツの間に制限されたインターフェイスを提供できます。HTML コンテンツでは、アプリケーションのページを非アプリケーションサンドボックスにマップし、そのページのコードが外部コンテンツをクロススクリプトできるようにすることもできます。1038 ページの「AIR のセキュリティ」を参照してください。

SWF ファイルまたはイメージの読み込みFlash SWF ファイルまたはイメージをネイティブウィンドウの表示リストに読み込むには、flash.display.Loader クラスを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

868

AIR ネイティブウィンドウの操作

package {import flash.display.Sprite;
import flash.events.Event;import flash.net.URLRequest;
import flash.display.Loader;public class LoadedSWF extends Sprite{
public function LoadedSWF(){
var loader:Loader = new Loader();loader.load(new URLRequest("visual.swf"));loader.contentLoaderInfo.addEventListener(Event.COMPLETE,loadFlash);}private function loadFlash(event:Event):void{
addChild(event.target.loader);}}}

注意：ActionScript 1 または 2 を使用して作成された古い SWF ファイルは、同じウィンドウに読み込まれた場合、クラス
定義、シングルトン、グローバル変数などのグローバルな状態を共有します。このような SWF ファイルの正常な動作が、変更されていないグローバル状態に依存する場合は、ファイルを同じウィンドウに 2 回以上読み込むこと、またはオーバーラップするクラス定義と変数を使用して別の SWF ファイルとして同じウィンドウに読み込むことはできません。このようなコンテンツを別のウィンドウに読み込むことはできます。

NativeWindow への HTML コンテンツの読み込み
HTML コンテンツを NativeWindow に読み込むには、HTMLLoader オブジェクトをウィンドウステージに追加してからHTML コンテンツを HTMLLoader に読み込むか、または HTMLLoader.createRootWindow() メソッドを使用してHTMLLoader オブジェクトを既に含んでいるウィンドウを作成します。次の例では、ネイティブウィンドウのステージ上の 300 × 500 ピクセルの表示領域に、HTML コンテンツを表示します。
//newWindow is a NativeWindow instancevar htmlView:HTMLLoader = new HTMLLoader();
htmlView.width = 300;
htmlView.height = 500;//set the stage so display objects are added to the top-left and not scaled
newWindow.stage.align = "TL";
newWindow.stage.scaleMode = "noScale";
newWindow.stage.addChild( htmlView );//urlString is the URL of the HTML page to load
htmlView.load( new URLRequest(urlString) );HTML ページを Flex アプリケーションに読み込むには、Flex HTML コンポーネントを使用します。
ウィンドウで透明度が使用されている場合（ウィンドウの transparent プロパティが true の場合）は、SWF ファイルを参照
するために使用されるオブジェクトまたは埋め込みタグの wmode パラメーターが opaque または transparent のどちらかに設定されていない限り、HTML ファイル内の SWF コンテンツは表示されません。wmode 値のデフォルトは window なので、
デフォルトでは、SWF コンテンツは透明ウィンドウには表示されません。どの wmode 値が使用されていようと、PDF コン
テンツは透明ウィンドウには表示されません。
また、HTMLLoader コントロールが拡大／縮小または回転されている場合、または HTMLLoader の alpha プロパティが1.0 以外の値に設定されている場合、SWF コンテンツと PDF コンテンツのどちらも表示されません。

HTML ウィンドウ上のオーバーレイとしての SWF コンテンツの追加
HTML ウィンドウは NativeWindow インスタンス内に含まれるので、表示リストでは HTML レイヤーの上または下のど
ちらにでも、Flash 表示オブジェクトを追加できます。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

869

AIR ネイティブウィンドウの操作

HTML レイヤーの上位に表示オブジェクトを追加するには、window.nativeWindow.stage プロパティの addChild() メソッド
を使用します。addChild() メソッドは、ウィンドウ内の既存のすべてのコンテンツより上のレイヤーに、コンテンツを追加します。

HTML レイヤーより下位に表示オブジェクトを追加するには、window.nativeWindow.stage プロパティの addChildAt() メ
ソッドを使用し、index パラメーターに値 0 を渡します。0 インデックスにオブジェクトを配置すると、HTML の表示を含む既存のコンテンツが 1 レイヤーだけ上に移動し、新しいコンテンツが最下位に挿入されます。HTML ページより下位のレイヤーにあるコンテンツを表示するには、HTMLlLoader オブジェクトの paintsDefaultBackground プロパティを false に設定する必要があります。また、ページのエレメントで背景色が設定されているものはすべて、透明になりません。例えば、ページの body エレメントに背景色を設定すると、ページのすべてのものが透明ではなくなります。
次の例では、Flash 表示オブジェクトをオーバーレイおよびアンダーレイとして HTML ページに追加する方法を示します。
この例では、単純な形のオブジェクトを 2 つ作成し、1 つは HTML コンテンツより下位に、もう 1 つは上位に追加します。
また、enterFrame イベントに基づいて図形の位置も更新します。
<html><head><title>Bouncers</title><script src="AIRAliases.js" type="text/javascript"></script><script language="JavaScript" type="text/javascript">
air.Shape = window.runtime.flash.display.Shape;
function Bouncer(radius, color){
this.radius = radius;
this.color = color;//velocity
this.vX = -1.3;
this.vY = -1;//Create a Shape object and draw a circle with its graphics property
this.shape = new air.Shape();this.shape.graphics.lineStyle(1,0);
this.shape.graphics.beginFill(this.color,.9);
this.shape.graphics.drawCircle(0,0,this.radius);
this.shape.graphics.endFill();//Set the starting position
this.shape.x = 100;
this.shape.y = 100;//Moves the sprite by adding (vX,vY) to the current position
this.update = function(){this.shape.x += this.vX;
this.shape.y += this.vY;//Keep the sprite within the windowif( this.shape.x - this.radius < 0){
this.vX = -this.vX;}
if( this.shape.y - this.radius < 0){
this.vY = -this.vY;}
if( this.shape.x + this.radius > window.nativeWindow.stage.stageWidth){this.vX = -this.vX;}
if( this.shape.y + this.radius > window.nativeWindow.stage.stageHeight){
this.vY = -this.vY;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

870

AIR ネイティブウィンドウの操作};}
function init(){//turn off the default HTML backgroundwindow.htmlLoader.paintsDefaultBackground = false;
var bottom = new Bouncer(60,0xff2233);
var top = new Bouncer(30,0x2441ff);//listen for the enterFrame event
window.htmlLoader.addEventListener("enterFrame",function(evt){
bottom.update();top.update();});//add the bouncing shapes to the window stage
window.nativeWindow.stage.addChildAt(bottom.shape,0);
window.nativeWindow.stage.addChild(top.shape);}</script><body onload="init();"><h1>de Finibus Bonorum et Malorum</h1><p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium
doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis
et quasi architecto beatae vitae dicta sunt explicabo.</p><p style="background-color:#FFFF00; color:#660000;">This paragraph has a background color.</p><p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis
praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias
excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui
officia deserunt mollitia animi, id est laborum et dolorum fuga.</p></body></html>

この例では、AIR において JavaScript と ActionScript の間にある境界を越える、若干高度な技法の初歩的な概要について説明しています。ActionScript の表示オブジェクトの使用に関する知識がない場合は、『ActionScript 3.0 開発ガイド』の143 ページの「表示のプログラミング」を参照してください。

例：ネイティブウィンドウの作成
Adobe AIR 1.0 およびそれ以降
次の例では、ネイティブウィンドウの作成方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

871

AIR ネイティブウィンドウの操作

public function createNativeWindow():void {//create the init options
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.transparent = false;
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.type = NativeWindowType.NORMAL;//create the window
var newWindow:NativeWindow = new NativeWindow(options);
newWindow.title = "A title";
newWindow.width = 600;
newWindow.height = 400;
newWindow.stage.align = StageAlign.TOP_LEFT;
newWindow.stage.scaleMode = StageScaleMode.NO_SCALE;//activate and show the new window
newWindow.activate();}ウィンドウの管理
Adobe AIR 1.0 およびそれ以降
デスクトップウィンドウの外観、動作、ライフサイクルを管理するには、NativeWindow クラスのプロパティとメソッドを使用します。
注意：Flex フレームワークを使用する場合は、一般にフレームワーククラスを使用してウィンドウ動作を管理する方が適切です。NativeWindow のほとんどのプロパティおよびメソッドには、mx:WindowedApplication および mx:Window ク
ラスを使用してアクセスできます。

NativeWindow インスタンスの取得
Adobe AIR 1.0 およびそれ以降
ウィンドウを操作するには、最初にウィンドウインスタンスを取得する必要があります。ウィンドウインスタンスは、次のいずれかの場所から取得できます。

•

ウィンドウの作成に使用されるネイティブウィンドウコンストラクター：
var win:NativeWindow = new NativeWindow(initOptions);•

ウィンドウステージの nativeWindow プロパティ：
var win:NativeWindow = stage.nativeWindow;•

ウィンドウ内の表示オブジェクトの stage プロパティ：
var win:NativeWindow = displayObject.stage.nativeWindow;•

ウィンドウによって送出されるネイティブウィンドウイベントの target プロパティ：
private function onNativeWindowEvent(event:NativeWindowBoundsEvent):void{
var win:NativeWindow = event.target as NativeWindow;}•

ウィンドウに表示される HTML ページの nativeWindow プロパティ：
var win:NativeWindow = htmlLoader.window.nativeWindow;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

872

AIR ネイティブウィンドウの操作• NativeApplication オブジェクトの activeWindow プロパティと openedWindows プロパティ：
var nativeWin:NativeWindow = NativeApplication.nativeApplication.activeWindow;
var firstWindow:NativeWindow = NativeApplication.nativeApplication.openedWindows[0];NativeApplication.nativeApplication.activeWindow は、アプリケーションのアクティブなウィンドウを示しています（ただし、アクティブなウィンドウが AIR アプリケーションのウィンドウでない場合は、null を返します）。
NativeApplication.nativeApplication.openedWindows 配列には、AIR アプリケーション内で閉じられていないすべてのウィンドウが格納されています。

Flex の mx:WindowedApplication オブジェクトと mx:Window オブジェクトは表示オブジェクトなので、次に示すように、stage プロパティを使用して、MXML ファイル内のアプリケーションウィンドウを簡単に参照できます。
<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" applicationComplete="init();"><mx:Script><![CDATA[
import flash.display.NativeWindow;
public function init():void{
var appWindow:NativeWindow = this.stage.nativeWindow;//set window properties
appWindow.visible = true;}]]></mx:Script></WindowedApplication

注意：WindowedApplication コンポーネントまたは Window コンポーネントが Flex フレームワークによってウィンドウ
ステージに追加されるまで、コンポーネントの stage プロパティは null です。この動作は、Flex Application コンポーネン
トの動作と同じですが、creationComplete などの WindowedApplication および Window コンポーネントの初期化サイク
ルの早い段階で発生するイベントに対するリスナーでは、ステージまたは NativeWindow インスタンスにアクセスできないことを意味します。applicationComplete イベントが送出された時点では、ステージおよび NativeWindow インスタンスにアクセスしても安全です。

ウィンドウのアクティブ化、表示、非表示
Adobe AIR 1.0 およびそれ以降
ウィンドウをアクティブ化するには、NativeWindow の activate() メソッドを呼び出します。ウィンドウをアクティブ化す
ると、ウィンドウが前面になり、キーボードとマウスのフォーカスが設定され、必要な場合は、ウィンドウを復元するか、または visible プロパティを true に設定することでウィンドウが表示されるようになります。あるウィンドウをアクティブ化
しても、アプリケーション内での他のウィンドウの順序は変わりません。activate() メソッドを呼び出すと、ウィンドウはactivate イベントを送出します。
非表示になっているウィンドウをアクティブ化しないで表示するには、visible プロパティを true に設定します。これによりウィンドウは前面になりますが、フォーカスがウィンドウに割り当てられることはありません。
ウィンドウを非表示にするには、visible プロパティを false に設定します。ウィンドウを非表示にすると、ウィンドウ、関連するタスクバーアイコン、および MacOS X ではウィンドウメニューのエントリが表示されなくなります。
ウィンドウの可視性を変更すると、このウィンドウが所有するすべてのウィンドウの可視性も同様に変更されます。例えば、
ウィンドウを非表示にすると、そのウィンドウが所有しているウィンドウもすべて非表示になります。
注意：Mac OS X では、ドックのウィンドウ部分にアイコンがある最小化されたウィンドウを完全に非表示にすることはできません。最小化されたウィンドウの visible プロパティを false に設定しても、そのウィンドウのドックアイコンは表示されています。ユーザーがアイコンをクリックすると、ウィンドウは復元されて表示されるようになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

873

AIR ネイティブウィンドウの操作

ウィンドウの表示順序の変更
Adobe AIR 1.0 およびそれ以降
AIR では、ウィンドウの表示順序を複数の方法で直接変更できます。ウィンドウの表示順序の前面は背面に移動したり、ウィンドウを別のウィンドウの前や後に移動したりできます。同時に、ウィンドウをアクティブ化することでウィンドウの順序を変更することもできます。

alwaysInFront プロパティを true に設定することで、あるウィンドウを他のウィンドウより前面に保つことができます。このように設定されたウィンドウが複数ある場合、同じ設定のウィンドウ間で表示順序が並べ替えられます。ただし、それらのウィンドウは、alwaysInFront が false に設定されたウィンドウよりは常に前面に配置されます。
また、最上位グループのウィンドウは、AIR アプリケーションがアクティブではない場合でも、他のアプリケーションのウィンドウより前面に表示されます。この動作はユーザーにとっては迷惑である場合があるので、alwaysInFront を true に設定するのは、それが必要であって適切である場合にのみ行う必要があります。例えば、次のような場合には使用が正当化されます。

•

ツールチップ、ポップアップリスト、カスタムメニュー、コンボボックスなどのコントロール用の一時的なポップアップ
ウィンドウ。これらのウィンドウはフォーカスを失ったときに閉じる必要があるので、別のウィンドウの表示の邪魔になるのを避けることができます。

•

特に緊急を要するエラーメッセージと警告。ユーザーが直ちに応答しないと元に戻すことのできない変更が発生する可能性がある場合は、警告ウィンドウを最前面に移動してもかまいません。ただし、ほとんどのエラーと警告は、通常のウィ
ンドウ表示順序で処理できます。

•

短時間だけ表示されるトーストスタイルのウィンドウ。

注意：AIR では、alwaysInFront プロパティの適切な使用は強制されません。ただし、ユーザーのワークフローを妨害するよ
うなアプリケーションは、ごみ箱行きになることでしょう。
ウィンドウが他のウィンドウを所有している場合、所有下にあるウィンドウは常に所有者のウィンドウより前に配置される
ように並べ替えられます。他のウィンドウを所有するウィンドウで orderToFront() を呼び出したり、alwaysInFront を true に設定した場合、所有下にあるウィンドウも所有者ウィンドウと一緒に並べ替えられ、他のウィンドウの前面に配置されます。
ただし、所有下にあるウィンドウは、所有者ウィンドウの前面に引き続き表示されます。
所有下にあるウィンドウからウィンドウの並べ替えメソッドを呼び出した場合、所有者ウィンドウが同じであるウィンドウ間では通常通り動作します。ただし、所有下にあるウィンドウのグループ全体が、そのグループ以外のウィンドウと比較され、並べ替えられることがあります。例えば、所有下にあるウィンドウから orderToFront() を呼び出すと、そのウィンドウ
自身、その所有者、所有者が同じであるその他すべてのウィンドウが、ウィンドウ表示順序の前面に移動します。

NativeWindow クラスには、ウィンドウ間の相対的な表示順序を設定する次のプロパティとメソッドが用意されています。
メンバー

説明

alwaysInFront プロパティ

ウィンドウを最上位ウィンドウグループに表示するかどうかを指定します。
通常は、false が最善の設定です。値を false から true に変更すると、そのウィンドウは他のウィンドウの前面に移動します（ただし、アクティブにはなりません）。値を true から false に変更すると、そのウィンドウは最上位グループに残っているウィンドウの背後に移動しますが、他のウィンドウよりは前面になっています。プ
ロパティをウィンドウの現在値と同じ値に設定すると、ウィンドウの表示順序は変わりません。

alwaysInFront 設定は、他のウィンドウに所有されているウィンドウに対しては効果はありません。

orderToFront()

ウィンドウを前面に移動します。

orderInFrontOf()

ウィンドウを特定のウィンドウのすぐ前面に表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

874

AIR ネイティブウィンドウの操作

メンバー

説明

orderToBack()

ウィンドウを他のウィンドウの背後に移動します。

orderBehind()

ウィンドウを特定のウィンドウのすぐ背後に表示します。

activate()

ウィンドウを前面に移動します（同時に、ウィンドウを表示状態にしてフォーカスを割り当てます）。

注意：ウィンドウが非表示状態（visible が false）または最小化状態の場合は、表示順序メソッドを呼び出しても順序は変更されません。

Linux オペレーティングシステムでは、別のウィンドウマネージャーにより、ウィンドウの表示順序に関する別の規則が適用されます。

•

一部のウィンドウマネージャーでは、normal ウィンドウの前面にユーティリティウィンドウが常に表示されます。

•

一部のウィンドウマネージャーでは、alwaysInFront が true に設定されているフルスクリーンウィンドウが、

alwaysInFront が true に設定されている他のウィンドウの前面に常に表示されます。

ウィンドウを閉じる
Adobe AIR 1.0 およびそれ以降
ウィンドウを閉じるには、NativeWindow.close() メソッドを使用します。
ウィンドウを閉じると、ウィンドウのコンテンツの読み込みは解除されますが、他のオブジェクトがそのコンテンツを参照
している場合は、コンテンツオブジェクトは破棄されません。NativeWindow.close() メソッドは非同期に実行するので、ウィンドウに含まれるアプリケーションは、閉じる処理が行われている間も実行を続けます。閉じる操作が完了すると、close メソッドは close イベントを送出します。NativeWindow オブジェクトは技術的にはまだ有効な状態ですが、閉じられたウィンドウのほとんどのプロパティとメソッドは、アクセスすると IllegalOperationError が生成されます。閉じられたウィンドウを再び開くことはできません。ウィンドウが閉じられているかどうかを確認するには、ウィンドウの closed プ
ロパティを調べます。単にウィンドウを非表示にするには、NativeWindow.visible プロパティを false に設定します。

Nativeapplication.autoExit プロパティが true の場合は（デフォルト）、最後のウィンドウが閉じるとアプリケーションは終了します。
所有下にあるウィンドウは、所有者が閉じられたときに一緒に閉じます。所有下にあるウィンドウからは closing イベントが送出されないため、閉じる処理を取り消すことはできません。close イベントは送出されます。

ウィンドウ操作のキャンセルの許可
Adobe AIR 1.0 およびそれ以降
ウィンドウがシステムクロムを使用している場合は、適切なイベントをリッスンし、イベントのデフォルト動作をキャンセルすることで、ユーザーによるウィンドウの操作をキャンセルできます。例えば、ユーザーがシステムクロムの閉じるボタ
ンをクリックすると、closing イベントが送出されます。登録されているリスナーがイベントの preventDefault() メソッドを呼び出すと、ウィンドウは閉じません。
ウィンドウがシステムクロムを使用していない場合は、目的の変更が行われる前に変更の通知イベントが自動的に送出されることはありません。したがって、ウィンドウを閉じたり、ウィンドウの状態を変更したり、ウィンドウ境界プロパティを設定したりするメソッドを呼び出した場合、変更はキャンセルできません。ウィンドウの変更が行われる前にアプリケー
ションのコンポーネントに通知するには、アプリケーションのロジックで、ウィンドウの dispatchEvent() メソッドを使用して、関連する通知イベントを送出します。
例えば、次のロジックは、ウィンドウの閉じるボタンに対するキャンセル可能なイベントハンドラーを実装しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

875

AIR ネイティブウィンドウの操作

public function onCloseCommand(event:MouseEvent):void{
var closingEvent:Event = new Event(Event.CLOSING,true,true);dispatchEvent(closing);
if(!closingEvent.isDefaultPrevented()){
win.close();}}イベントの preventDefault() メソッドがリスナーによって呼び出されると、dispatchEvent() メソッドは false を返します。ただし、このメソッドは他の理由でも false を返す場合があるので、isDefaultPrevented() メソッドを明示的に使用して、変更をキャンセルする必要があるかどうかを判定するのがよい方法です。

ウィンドウの最大化、最小化、復元
Adobe AIR 1.0 およびそれ以降
ウィンドウを最大化するには、NativeWindow の maximize() メソッドを使用します。
myWindow.maximize();

ウィンドウを最小化するには、NativeWindow の minimize() メソッドを使用します。
myWindow.minimize();

ウィンドウを復元するには（つまり、最大化または最小化されていたウィンドウを元のサイズに戻すには）、NativeWindow の restore() メソッドを使用します。
myWindow.restore();所有下にあるウィンドウは、所有者ウィンドウが最小化または復元されたときに、一緒に最小化または復元されます。所有者の最小化に伴い最小化される際には、所有下にあるウィンドウからはイベントは送出されません。
注意：AIR ウィンドウを最大化したときの動作は、Mac OS X での標準の動作とは異なります。アプリケーションで定義されている「標準」サイズとユーザーが最後に設定したサイズの間で切り替えが行われるのではなく、AIR ウィンドウは、ア
プリケーションまたはユーザーが最後に設定したサイズと、画面で使用可能な領域全体との間で切り替わります。

Linux オペレーティングシステムでは、別のウィンドウマネージャーにより、ウィンドウの表示状態の設定に関する別の規則が適用されます。

•

一部のウィンドウマネージャーでは、ユーティリティウィンドウを最大化できません。

•

ウィンドウに最大サイズが設定されている場合、一部のウィンドウではウィンドウを最大化できません。他のウィンドウマネージャーでは、表示状態が最大化に設定されますが、ウィンドウのサイズは変更されません。いずれの場合も、表示
状態変更イベントは送出されません。

•

一部のウィンドウマネージャーは、ウィンドウの maximizable 設定または minimizable 設定を受け取りません。

注意：Linux では、ウィンドウプロパティは非同期で変更されます。プログラムのある行で表示状態を変更し、次の行で値を読み取る場合、読み取られた値には古い値が反映されます。すべてのプラットフォームで、表示状態が変更されると、NativeWindow オブジェクトから displayStateChange イベントが送出されます。ウィンドウの新しい状態に基づいて何らかのアクションを実行する必要がある場合、常に displayStateChange イベントハンドラーで行ってください。879 ページの「ウィンドウイベントのリッスン」を参照してください。

例：ウィンドウの最小化、最大化、復元、終了
Adobe AIR 1.0 およびそれ以降
次の短い MXML アプリケーションでは、Window の maximize()、minimize()、restore() および close() メソッドの使用方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

876

AIR ネイティブウィンドウの操作<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication
xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"><mx:Script><![CDATA[
public function minimizeWindow():void{
this.stage.nativeWindow.minimize();}public function maximizeWindow():void{
this.stage.nativeWindow.maximize();}public function restoreWindow():void{
this.stage.nativeWindow.restore();}public function closeWindow():void{
this.stage.nativeWindow.close();}]]></mx:Script><mx:VBox><mx:Button label="Minimize" click="minimizeWindow()"/><mx:Button label="Restore" click="restoreWindow()"/><mx:Button label="Maximize" click="maximizeWindow()"/><mx:Button label="Close" click="closeWindow()"/></mx:VBox></mx:WindowedApplication>

次に示す Flash 用の ActionScript の例では、NativeWindow の minimize()、maximize()、restore() および close() メソッド
をトリガーする 4 つのクリック可能なテキストフィールドを作成しています。
package{import flash.display.Sprite;
import flash.events.MouseEvent;import flash.text.TextField;
public class MinimizeExample extends Sprite{
public function MinimizeExample():void{
var minTextBtn:TextField = new TextField();
minTextBtn.x = 10;
minTextBtn.y = 10;
minTextBtn.text = "Minimize";
minTextBtn.background = true;
minTextBtn.border = true;
minTextBtn.selectable = false;
addChild(minTextBtn);
minTextBtn.addEventListener(MouseEvent.CLICK, onMinimize);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

877

AIR ネイティブウィンドウの操作

var maxTextBtn:TextField = new TextField();
maxTextBtn.x = 120;
maxTextBtn.y = 10;
maxTextBtn.text = "Maximize";
maxTextBtn.background = true;
maxTextBtn.border = true;
maxTextBtn.selectable = false;
addChild(maxTextBtn);
maxTextBtn.addEventListener(MouseEvent.CLICK, onMaximize);var restoreTextBtn:TextField = new TextField();
restoreTextBtn.x = 230;
restoreTextBtn.y = 10;
restoreTextBtn.text = "Restore";
restoreTextBtn.background = true;
restoreTextBtn.border = true;
restoreTextBtn.selectable = false;
addChild(restoreTextBtn);
restoreTextBtn.addEventListener(MouseEvent.CLICK, onRestore);var closeTextBtn:TextField = new TextField();
closeTextBtn.x = 340;
closeTextBtn.y = 10;
closeTextBtn.text = "Close Window";
closeTextBtn.background = true;
closeTextBtn.border = true;
closeTextBtn.selectable = false;
addChild(closeTextBtn);closeTextBtn.addEventListener(MouseEvent.CLICK, onCloseWindow);}
function onMinimize(event:MouseEvent):void{
this.stage.nativeWindow.minimize();}function onMaximize(event:MouseEvent):void{
this.stage.nativeWindow.maximize();}function onRestore(event:MouseEvent):void{
this.stage.nativeWindow.restore();}function onCloseWindow(event:MouseEvent):void{
this.stage.nativeWindow.close();}}}

ウィンドウのサイズ変更と移動
Adobe AIR 1.0 およびそれ以降
ウィンドウがシステムクロムを使用している場合は、クロムがウィンドウのサイズ変更とデスクトップ上での移動に対するドラッグを制御します。システムクロムを使用しない場合は、独自のコントロールを追加して、ユーザーがウィンドウのサ
イズ変更および移動を行うことができるようにする必要があります。
注意：ウィンドウのサイズ変更または移動を行うには、最初に、NativeWindow インスタンスに対する参照を取得する必要があります。ウィンドウの参照を取得する方法について詳しくは、871 ページの「NativeWindow インスタンスの取得」
を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

878

AIR ネイティブウィンドウの操作

ウィンドウのサイズ変更
ユーザーがインタラクティブにウィンドウのサイズを変更できるようにするには、NativeWindow の startResize() メソッド
を使用します。mouseDown イベントからこのメソッドを呼び出すと、マウスの動作に応じてサイズ変更操作が行われ、オペレーティングシステムが mouseUp イベントを受信すると完了します。startResize() を呼び出すときは、ウィンドウのサイズ変更の基準になる辺または角を指定する引数を渡します。
ウィンドウサイズをプログラムによって設定するには、ウィンドウの width、height または bounds の各プロパティを目的のサイズに設定します。境界を設定すると、ウィンドウのサイズと位置をすべて同時に変更できます。ただし、変更が行われる順序は保証されません。一部の Linux ウィンドウマネージャーでは、デスクトップ画面の境界の外側にウィンドウを拡張することはできません。このような場合、プロパティの設定順序により、通常は変更の純粋な影響により正式なウィンドウが作成される場合でも、最終的なウィンドウのサイズが制限される可能性があります。例えば、画面の下部付近でウィンドウの高さと y 位置の両方を変更する場合、y 位置の変更の前に高さの変更が適用されると、高さが完全に変更されない可能性があります。
注意：Linux では、ウィンドウプロパティは非同期で変更されます。プログラムのある行でウィンドウのサイズを変更し、次の行でサイズを読み取る場合、読み取られた値には古い値が反映されます。すべてのプラットフォームで、ウィンドウのサイズが変更されると、NativeWindow オブジェクトから resize イベントが送出されます。ウィンドウの新しいサイズまたは状態に基づいて何らかのアクション（ウィンドウ内のコントロールのレイアウトなど）を実行する必要がある場合、常にresize イベントハンドラーで行ってください。879 ページの「ウィンドウイベントのリッスン」を参照してください。
ステージのスケールモードにより、ウィンドウのサイズが変更されるときのウィンドウステージとそのコンテンツの動作が決まります。ステージのスケールモードは、アプリケーションが表示領域のサイズや縦横比を制御しない Web ブラウザーのような状況を対象に設計されていることに注意してください。一般に、ステージの scaleMode プロパティをStageScaleMode.NO_SCALE に設定すると、最善の結果が得られます。ウィンドウのコンテンツを拡大／縮小する必要がある
場合は、ウィンドウの境界の変更に呼応してコンテンツの scaleX および scaleY パラメーターを設定してもかまいません。
ウィンドウの移動
サイズを変更しないでウィンドウを移動するには、NativeWindow startMove() メソッドを使用します。startResize() メソッドと同様に、mouseDown イベントから startMove() メソッドを呼び出すと、マウスの操作に応じて移動処理が行われ、オペ
レーティングシステムが mouseUp イベントを受信すると完了します。

startResize() メソッドおよび startMove() メソッドについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレ
ンスガイド』を参照してください。
ウィンドウをプログラムによって移動するには、ウィンドウの x、y または bounds の各プロパティを目的の位置に設定します。境界を設定すると、ウィンドウのサイズと位置を両方同時に変更できます。
注意：Linux では、ウィンドウプロパティは非同期で変更されます。プログラムのある行でウィンドウを移動し、次の行で位置を読み取る場合、読み取られた値には古い値が反映されます。すべてのプラットフォームで、位置が変更されると、NativeWindow オブジェクトから move イベントが送出されます。ウィンドウの新しい位置に基づいて何らかのアクションを実行する必要がある場合、常に move イベントハンドラーで行ってください。879 ページの「ウィンドウイベントのリッ
スン」を参照してください。

例：ウィンドウのサイズ変更と移動
Adobe AIR 1.0 およびそれ以降
次の例では、ウィンドウでのサイズ変更および移動操作を開始する方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

879

AIR ネイティブウィンドウの操作

package{import flash.display.Sprite;
import flash.events.MouseEvent;import flash.display.NativeWindowResize;
public class NativeWindowResizeExample extends Sprite{
public function NativeWindowResizeExample():void{// Fills a background area.
this.graphics.beginFill(0xFFFFFF);
this.graphics.drawRect(0, 0, 400, 300);
this.graphics.endFill();// Creates a square area where a mouse down will start the resize.
var resizeHandle:Sprite =createSprite(0xCCCCCC, 20, this.width - 20, this.height - 20);
resizeHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartResize);// Creates a square area where a mouse down will start the move.
var moveHandle:Sprite = createSprite(0xCCCCCC, 20, this.width - 20, 0);
moveHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartMove);}public function createSprite(color:int, size:int, x:int, y:int):Sprite{
var s:Sprite = new Sprite();s.graphics.beginFill(color);s.graphics.drawRect(0, 0, size, size);s.graphics.endFill();s.x = x;s.y = y;this.addChild(s);return s;}
public function onStartResize(event:MouseEvent):void{
this.stage.nativeWindow.startResize(NativeWindowResize.BOTTOM_RIGHT);}
public function onStartMove(event:MouseEvent):void{
this.stage.nativeWindow.startMove();}}}

ウィンドウイベントのリッスン
Adobe AIR 1.0 およびそれ以降
ウィンドウによって送出されるイベントをリッスンするには、リスナーをウィンドウのインスタンスに登録します。例えば、

closing イベントをリッスンするには、次のようにリスナーをウィンドウに登録します。
myWindow.addEventListener(Event.CLOSING, onClosingEvent);

イベントが送出されると、target プロパティはイベントを送信したウィンドウを示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

880

AIR ネイティブウィンドウの操作

ほとんどのウィンドウイベントには、2 つの関連メッセージがあります。第 1 のメッセージはウィンドウの変更が行われようとしていること（およびキャンセルできること）を通知し、第 2 のメッセージは変更が行われたことを通知します。例えば、ユーザーがウィンドウの閉じるボタンをクリックすると、closing イベントのメッセージが送出されます。リスナーがイベントをキャンセルしないと、ウィンドウが閉じ、close イベントがリスナーに送出されます。
通常、closing などの警告イベントは、システムクロムを使用してイベントがトリガーされた場合にのみ送出されます。例えばウィンドウの close() メソッドなどを呼び出しても、closing イベントは自動的には送出されず、close イベントのみが送出されます。ただし、closing イベントオブジェクトを作成し、ウィンドウの dispatchEvent() メソッドを使用して送出することはできます。

Event オブジェクトを送出するウィンドウイベントは次のとおりです。
イベント

説明

activate

ウィンドウがフォーカスを受け取ると送出されます。

deactivate

ウィンドウがフォーカスを失うと送出されます。

closing

ウィンドウが閉じられようとするときに送出されます。このイベントが自動的に発生するのは、システムクロムの閉じるボタンが押されたとき、または Mac OS X で Quit コマンドが呼び出されたときのみです。

close

ウィンドウが閉じると送出されます。

NativeWindowBoundsEvent オブジェクトを送出するウィンドウイベントは次のとおりです。
イベント

説明

moving

移動、サイズ変更またはウィンドウ表示状態の変更の結果として、ウィンドウの左上隅の位置が変更される直前に送出されます。

move

左上隅の位置が変更された後で送出されます。

resizing

サイズ変更または表示状態変更の結果としてウィンドウの幅または高さが変更される直前に送出されます。

resizeウィンドウのサイズが変更された後で送出されます。

NativeWindowBoundsEvent イベントの場合は、beforeBounds および afterBounds プロパティを使用して、変更の直前と直後のウィンドウ境界を取得できます。

NativeWindowDisplayStateEvent オブジェクトを送出するウィンドウイベントは次のとおりです。
イベント

説明

displayStateChanging

ウィンドウの表示状態が変更される直前に送出されます。

displayStateChange

ウィンドウの表示状態が変更された後で送出されます。

NativeWindowDisplayStateEvent イベントの場合は、beforeDisplayState および afterDisplayState プロパティを使用して、変更の直前と直後のウィンドウの表示状態を取得できます。
一部の Linux ウィンドウマネージャーでは、最大サイズが設定されているウィンドウを最大化しても、表示状態変更イベン
トは送出されません（ウィンドウは最大表示状態に設定されますが、サイズは変更されません）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

881

AIR ネイティブウィンドウの操作

フルスクリーンウィンドウの表示
Adobe AIR 1.0 およびそれ以降
Stage の displayState プロパティを StageDisplayState.FULL_SCREEN_INTERACTIVE に設定すると、ウィンドウはフルスク
リーンモードになり、このモードでのキーボード入力が許可されます（ブラウザーで実行する SWF コンテンツでは、キーボード入力は許可されません）。ユーザーが Esc キーを押すと、フルスクリーンモードは終了します。
注意：一部の Linux ウィンドウマネージャーでは、ウィンドウに最大サイズが設定されている場合、ウィンドウのサイズはスクリーンいっぱいになりません（ただし、ウィンドウシステムクロムは削除されます）。
例えば、次の Flex コードは、単純なフルスクリーン端末を設定する簡単な AIR アプリケーションを定義しています。
<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"
applicationComplete="init()" backgroundColor="0x003030" focusRect="false"><mx:Script><![CDATA[
private function init():void{stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE;
focusManager.setFocus(terminal);
terminal.text = "Welcome to the dumb terminal app. Press the ESC key to exit..\n";terminal.selectionBeginIndex = terminal.text.length;
terminal.selectionEndIndex = terminal.text.length;}]]></mx:Script><mx:TextArea
id="terminal"
height="100%" width="100%"
scroll="false"
backgroundColor="0x003030"
color="0xCCFF00"
fontFamily="Lucida Console"
fontSize="44"/></mx:WindowedApplication>

次に示す Flash 用の ActionScript の例は、簡単なフルスクリーンテキスト端末をシミュレーションします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

882

AIR ネイティブウィンドウの操作

import flash.display.Sprite;
import flash.display.StageDisplayState;
import flash.text.TextField;
import flash.text.TextFormat;
public class FullScreenTerminalExample extends Sprite{
public function FullScreenTerminalExample():void{
var terminal:TextField = new TextField();
terminal.multiline = true;
terminal.wordWrap = true;
terminal.selectable = true;
terminal.background = true;
terminal.backgroundColor = 0x00333333;
this.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE;
addChild(terminal);
terminal.width = 550;
terminal.height = 400;
terminal.text = "Welcome to the dumb terminal application. Press the ESC key to exit.\n_";var tf:TextFormat = new TextFormat();
tf.font = "Courier New";
tf.color = 0x00CCFF00;
tf.size = 12;
terminal.setTextFormat(tf);terminal.setSelection(terminal.text.length - 1, terminal.text.length);}}

最終更新日 2015/10/14

883

第 53 章：AIR の表示スクリーン
Adobe AIR 1.0 およびそれ以降
Adobe® AIR® Screen クラスを使用すると、コンピューターまたはデバイスに接続された表示スクリーンに関する情報にアクセスできます。

関連項目

flash.display.Screen

AIR の表示スクリーンの基礎
Adobe AIR 1.0 およびそれ以降•

仮想デスクトップのサイズ計算（Flex）•

仮想デスクトップのサイズ計算（Flash）

スクリーン API には Screen という 1 つのクラスが含まれており、このクラスには、システムのスクリーンに関する情報を取得するための静的メンバーと、特定のスクリーンを表すためのインスタンスメンバーが用意されています。
コンピューターシステムには複数のモニターまたはディスプレイを接続でき、仮想空間に配置された複数のデスクトップス
クリーンにそれらを対応させることができます。AIR の Screen クラスは、スクリーン、スクリーンの相対的な配置、スクリーンの利用可能な領域に関する情報を提供します。複数のモニターを同じスクリーンにマップした場合、1 つだけのスクリーンが存在することになります。スクリーンのサイズがモニターの表示領域より大きい場合、スクリーンのどの部分が現在表示されているかを特定する方法はありません。

1 つのスクリーンは、1 つの独立したデスクトップ表示領域を表します。仮想デスクトップ内では、スクリーンは矩形で表されます。プライマリディスプレイとして指定されているスクリーンの左上隅が、仮想デスクトップの座標系の原点です。
スクリーンを表すために使用する値は、すべてピクセル単位で指定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

884

AIR の表示スクリーン

スクリーンの範囲
仮想スクリーン
利用可能な範囲

このスクリーン配置では、2 つのスクリーンが仮想デスクトップ上に存在します。メインスクリーン（#1）の左上隅の座標は、常に（0,0）です。スクリーン配置を変更してスクリーン #2 をメインスクリーンとして指定すると、スクリーン #1 の座標は負になります。スクリーンの利用可能な範囲の報告
時、メニューバー、タスクバーおよびドックは除外されます。

スクリーン API のクラス、メソッド、プロパティおよびイベントについて詳しくは、『Adobe Flash Platform 用
ActionScript 3.0 リファレンスガイド』を参照してください。

スクリーンの列挙
Adobe AIR 1.0 およびそれ以降
スクリーンの次のメソッドとプロパティを使用して、仮想デスクトップのスクリーンを列挙できます。
メソッドまたはプロパティ

説明

Screen.screens

使用可能なスクリーンを表す Screen オブジェクトの配列を提供します。配列の順序は重要ではありません。

Screen.mainScreen

メインスクリーンの Screen オブジェクトを提供します。Mac OS X では、メインスクリーンはメニューバー
を表示するスクリーンです。Windows では、メインスクリーンはシステム指定のプライマリスクリーンです。

Screen.getScreensForRectangle 指定された矩形に重なるスクリーンを表す Screen オブジェクトの配列を提供します。このメソッドに渡す矩形は、仮想デスクトップ上のピクセル座標で指定します。矩形に重なるスクリーンがない場合、配列は空にな()ります。このメソッドを使用して、ウィンドウが表示されるスクリーンを調べることができます。

Screen クラスのメソッドとプロパティから返された値は保存しないでください。使用可能なスクリーンとその配置は、ユーザーまたはオペレーティングシステムによって常に変更される可能性があります。
次の例では、スクリーン API を使用して、矢印キーの押下に応答して複数のスクリーン間でウィンドウを移動します。ウィンドウを次のスクリーンに移動するため、この例では、screens 配列を取得し、その配列を縦方向または横方向に並べ替えます（方向は押された矢印キーによって決まります）。次に、並べ替えた配列に従って、各スクリーンを現在のスクリーンの座標と比較します。ウィンドウの現在のスクリーンを特定するため、この例では、Screen.getScreensForRectangle() を呼び出してウィンドウの境界を渡します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

885

AIR の表示スクリーン

package {import flash.display.Sprite;
import flash.display.Screen;
import flash.events.KeyboardEvent;import flash.ui.Keyboard;
import flash.display.StageAlign;import flash.display.StageScaleMode;public class ScreenExample extends Sprite{
public function ScreenExample(){stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
stage.addEventListener(KeyboardEvent.KEY_DOWN,onKey);}
private function onKey(event:KeyboardEvent):void{
if(Screen.screens.length > 1){
switch(event.keyCode){case Keyboard.LEFT :moveLeft();
break;
case Keyboard.RIGHT :moveRight();
break;
case Keyboard.UP :moveUp();break;
case Keyboard.DOWN :moveDown();
break;}}}
private function moveLeft():void{
var currentScreen = getCurrentScreen();var left:Array = Screen.screens;
left.sort(sortHorizontal);for(var i:int = 0; i < left.length - 1; i++){if(left[i].bounds.left < stage.nativeWindow.bounds.left){stage.nativeWindow.x +=left[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += left[i].bounds.top - currentScreen.bounds.top;}}}
private function moveRight():void{
var currentScreen:Screen = getCurrentScreen();var left:Array = Screen.screens;
left.sort(sortHorizontal);for(var i:int = left.length - 1; i > 0; i--){if(left[i].bounds.left > stage.nativeWindow.bounds.left){stage.nativeWindow.x +=left[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += left[i].bounds.top - currentScreen.bounds.top;}}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

886

AIR の表示スクリーン

private function moveUp():void{
var currentScreen:Screen = getCurrentScreen();var top:Array = Screen.screens;
top.sort(sortVertical);for(var i:int = 0; i < top.length - 1; i++){if(top[i].bounds.top < stage.nativeWindow.bounds.top){
stage.nativeWindow.x += top[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += top[i].bounds.top - currentScreen.bounds.top;
break;}}}
private function moveDown():void{
var currentScreen:Screen = getCurrentScreen();var top:Array = Screen.screens;
top.sort(sortVertical);for(var i:int = top.length - 1; i > 0; i--){if(top[i].bounds.top > stage.nativeWindow.bounds.top){
stage.nativeWindow.x += top[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += top[i].bounds.top - currentScreen.bounds.top;
break;}}}
private function sortHorizontal(a:Screen,b:Screen):int{
if (a.bounds.left > b.bounds.left){return 1;} else if (a.bounds.left < b.bounds.left){return -1;} else {return 0;}}
private function sortVertical(a:Screen,b:Screen):int{
if (a.bounds.top > b.bounds.top){
return 1;} else if (a.bounds.top < b.bounds.top){
return -1;} else {return 0;}}
private function getCurrentScreen():Screen{
var current:Screen;var screens:Array = Screen.getScreensForRectangle(stage.nativeWindow.bounds);(screens.length > 0) ? current = screens[0] : current = Screen.mainScreen;
return current;}}}

最終更新日 2015/10/14

887

第 54 章：プリント
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe® Flash® Player および Adobe® AIR™ などの Flash ランタイムはオペレーティングシステムのプリントインターフェ
イスと通信できるので、ページをプリントスプーラに渡すことができます。スプーラに送信するページには、表示されているコンテンツ、動的なコンテンツ、または画面外にあってユーザーに表示されないコンテンツ（データベースの値や動的なテキストなど）を含めることができます。また、flash.printing.PrintJob クラスのプロパティにはユーザーのプリンター設定に基づいて値が格納されるので、ページを正しく書式設定できます。
以下では、flash.printing.PrintJob クラスのメソッドとプロパティを使用して、プリントジョブの作成、ユーザーのプリン
ト設定の読み取り、Flash ランタイムとユーザー OS のフィードバックに基づいたプリントジョブの調整を行う際の指針について詳しく説明します。

プリントの基礎
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、PrintJob クラスを使用して、表示コンテンツのスナップショットを作成し、インクと紙を使った印刷結果として出力できます。コンテンツのプリント設定は画面表示の設定と似たところがあります。いずれの場合も、エレ
メントの位置やサイズを指定して、目的のレイアウトを作成します。ただし、プリントには画面レイアウトとは異なる点もあります。例えば、プリンターではコンピューターのモニターとは異なる解像度が使用されます。コンピューター画面のコンテンツは動的に変化しますが、印刷されたコンテンツは基本的に静止しています。また、プリントの場合は、固定ページ
サイズによる制約や複数ページプリントの可能性を考慮する必要があります。
これらの違いは当然のように思われるかもしれませんが、ActionScript でプリントを設定する際には十分に注意してください。正確にプリントできるかどうかは、指定する値と使用するプリンターの特性との組み合わせによって決まります。

PrintJob クラスには、使用プリンターの重要な特性を決定できるプロパティが用意されています。
重要な概念と用語
次の参照リストに、プリントに関連した重要な用語を示します。
スプーラ オペレーティングシステムまたはプリンタードライバーの一部で、印刷待機中のページを追跡し、プリンターが使用可能になるとページをプリンターに送信します。
用紙の向き プリントされるコンテンツの、用紙に対する向き。水平（横方向）または垂直（縦方向）。
プリントジョブ 1 回の印刷結果を構成するページまたはページのセット。

ページのプリント
Flash Player 9 以降、Adobe AIR 1.0 以降
PrintJob クラスのインスタンスを使用して、プリントを処理できます。Flash Player または AIR からページをプリントする
際の基本的な手順としては、次に示す 4 つのステートメントを順に使用します。

• new PrintJob()：指定した名前で新しいプリントジョブのインスタンスを作成します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

888

プリント

• PrintJob.start()：OS のプリント処理を開始します。印刷ダイアログボックスを呼び出してユーザーに表示し、プリント
ジョブの読み取り専用プロパティを設定します。

• PrintJob.addPage()：プリントジョブのコンテンツに関する詳細を設定します。これには、Sprite オブジェクト（およびそれに含まれる子）の指定、プリント範囲のサイズ指定、およびイメージをベクターとビットマップのいずれの形式でプリントするかの指定が含まれます。addPage() を複数回呼び出せば、複数のページに複数のスプライトをプリントできます。

• PrintJob.send()：ページを OS のプリンターに送信します。
したがって、単純なプリントジョブスクリプトは次のようになります（コンパイルに必要な package、import および class ス
テートメントを含む）。
package{import flash.printing.PrintJob;
import flash.display.Sprite;
public class BasicPrintExample extends Sprite{
var myPrintJob:PrintJob = new PrintJob();
var mySprite:Sprite = new Sprite();public function BasicPrintExample(){
myPrintJob.start();myPrintJob.addPage(mySprite);
myPrintJob.send();}}}

注意：この例は、プリントジョブスクリプトの基本的なエレメントを示すためのもので、エラー処理は含まれていません。
ユーザーがプリントジョブをキャンセルしたときに適切に応答するスクリプトを作成するには、889 ページの「例外および戻り値に対する処理」を参照してください。
何らかの理由で PrintJob オブジェクトのプロパティをクリアする場合は、PrintJob 変数に null を設定します（例：myPrintJob = null）。

Flash ランタイムのタスクとシステムプリント
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash ランタイムでは、ページが OS のプリントインターフェイスに送出されるので、Flash ランタイムが管理するタスクと、OS 自体のプリントインターフェイスが管理するタスクについて注意する必要があります。Flash ランタイムでは、プリントジョブの開始、プリンターのページ設定の読み込み、OS に対するプリントジョブのコンテンツの送信、およびユーザーまたはシステムによってプリントジョブがキャンセルされたかどうかの確認を実行します。その他の処理（プリンター
固有のダイアログボックスの表示、スプールされたプリントジョブのキャンセル、プリンターのステータスに関するレポートなど）は、すべて OS で実行されます。Flash ランタイムはプリントジョブの開始や書式指定に問題がある場合に応答できますが、OS のプリントインターフェイスから取得した特定のプロパティや状態についてのみレポートを返すことができます。アプリケーション開発者は、レポートされたプロパティや状態に応じて何らかの処理を実行するコードを用意する必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

889

プリント

例外および戻り値に対する処理
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーがプリントジョブをキャンセルした場合に対応するため、addPage() および send() の呼び出しを実行する前に、

PrintJob.start() メソッドが true を返したかどうかを確認してください。これらのメソッドに対する呼び出しを次のように if
ステートメントで囲むと、続行する前にキャンセルされたかどうかを簡単にチェックできます。
if (myPrintJob.start()){// addPage() and send() statements here}

PrintJob.start() が true の場合は、ユーザーが「印刷」を選択（または Flash Player または AIR などの Flash ランタイムがPrint コマンドを開始）しています。したがって、addPage() および send() メソッドを呼び出すことができます。
また、プリント処理を管理しやすくするために、PrintJob.addPage() メソッドに対して Flash ランタイムから例外が送出されます。これらのエラーをキャッチすることにより、ユーザーに情報と対処方法の選択肢を示すことができます。

PrintJob.addPage() メソッドが失敗した場合は、別の関数を呼び出すか、現在のプリントジョブを停止する方法もあります。
これらの例外は、addPage() の呼び出しを try..catch ステートメント内に埋め込むことによってキャッチできます。この例では、[params] はパラメーターのプレースホルダーで、実際にプリントする内容を指定します。
if (myPrintJob.start()){
try{
myPrintJob.addPage([params]);}
catch (error:Error){// Handle error,}
myPrintJob.send();}

プリントジョブを開始した後は、PrintJob.addPage() を使用してコンテンツを追加し、それによって例外（ユーザーがプリン
トジョブをキャンセルした場合など）が発生するかどうかを確認できます。例外が発生した場合は、catch ステートメントにロジックを追加して、ユーザー（または Flash ランタイム）に情報と対処方法の選択肢を示すか、現在のプリントジョブを停止できます。ページを正常に追加できた場合は、次に PrintJob.send() でページをプリンターに送信します。

Flash ランタイムがプリントジョブをプリンターに送信する際に問題が発生した場合（プリンターがオフラインになっていた場合など）も、同様にその例外をキャッチし、情報と対処方法の選択肢を示すことができます（メッセージテキストと警告をアニメーションで表示することなどが考えられます）。例えば、次のコードに示すように、テキストフィールドに if..else
ステートメントで新しいテキストを割り当てることができます。
if (myPrintJob.start()){
try{
myPrintJob.addPage([params]);}
catch (error:Error){// Handle error.
}
myPrintJob.send();}else{
myAlert.text = "Print job canceled";}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

890

プリント

実際に動作するサンプルについては、897 ページの「プリントの例：拡大／縮小、トリミング、および応答」を参照してください。

ページプロパティの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーが印刷ダイアログボックスで「OK」をクリックし、PrintJob.start() が true を返すと、プリンターの設定で定義されているプロパティにアクセスできます。この設定には、用紙の幅と高さ（pageHeight と pageWidth）および用紙の向きが含まれます。これらはプリンターの設定であり、Flash ランタイムの制御下にあるプロパティではありません。したがって、設定を変更することはできませんが、これらの情報を使用することで、コンテンツを現在の設定に適した形式に整形してプリンターに送信できます。詳しくは、891 ページの「サイズ、拡大率、用紙の向きの設定」を参照してください。

ベクター形式またはビットマップ形式のレンダリング
Flash Player 9 以降、Adobe AIR 1.0 以降
プリントジョブで各ページをベクターグラフィックとしてスプールするか、ビットマップイメージとしてスプールするかは、手動で設定できます。場合によっては、ベクター形式でプリントするとスプールファイルが小さくなり、画質もビットマッ
プ形式でプリントするより向上することがあります。ただし、コンテンツにビットマップイメージが含まれている場合、ア
ルファ透明度やカラー効果を再現するには、ページをビットマップイメージとしてプリントします。また、PostScript 非対応のプリンターでは、ベクターグラフィックは自動的にビットマップイメージに変換されます。
ビットマップ形式でのプリントを指定するには、PrintJobOptions オブジェクトを PrintJob.addPage() の第 3 パラメーターとして渡します。

Flash Player および AIR 2 よりも前の AIR では、PrintJobOptions オブジェクトの printAsBitmap パラメーターを true に設定します。以下に例を示します。
var options:PrintJobOptions = new PrintJobOptions();
options.printAsBitmap = true;
myPrintJob.addPage(mySprite, null, options);

第 3 パラメーターの値を指定しない場合、そのプリントジョブではデフォルトのベクター形式のプリントが実行されます。

AIR 2 以降では、PrintJobOptions オブジェクトの printMethod プロパティを使用して、プリント方法を指定します。この
プロパティには、PrintMethod クラス内の定数として定義された、次の 3 つの値を指定できます。

• PrintMethod.AUTO：プリントするコンテンツに基づいて、最適なプリント方法を自動的に選択します。例えば、ページにテキストが含まれている場合は、ベクター形式のプリント方法が選択されます。ただし、アルファ透明度を使用した透かしイメージがテキスト上に重なって表示されている場合は、透明度を維持するためにビットマップ形式のプリントが選択されます。

• PrintMethod.BITMAP：コンテンツに関わらず、ビットマップ形式のプリントが強制されます。
• PrintMethod.VECTOR：コンテンツに関わらず、ベクター形式のプリントが強制されます。

プリントジョブステートメントのタイミング
Flash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 では、ActionScript の以前のバージョンと同様に、PrintJob オブジェクトが単一フレームに制限されません。ただし、印刷ダイアログボックスで「OK」ボタンをクリックすると印刷ステータス情報が表示されるので、ページをスプーラに送信した直後に PrintJob.addPage() と PrintJob.send() を呼び出してください。PrintJob.send() 呼び出しの格納されたフレームに遅延が到達すると、印刷処理が遅延します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

891

プリント

ActionScript 3.0 には、15 秒間のスクリプトタイムアウトの制限があります。したがって、プリントジョブのシーケンスにおける主要なステートメント間の時間が 15 秒を超えてはなりません。つまり、15 秒間のスクリプトタイムアウトの制限は、次の間隔に適用されます。

• PrintJob.start() と最初の PrintJob.addPage()• PrintJob.addPage() と次の PrintJob.addPage()•

最後の PrintJob.addPage() と PrintJob.send()

上記の間隔のいずれかが 15 秒以上の場合、次に PrintJob インスタンスの PrintJob.start() を呼び出したときに false が返されます。また、次に PrintJob インスタンスの PrintJob.addPage() を呼び出したときに、Flash Player または AIR からランタイ
ム例外がスローされます。

サイズ、拡大率、用紙の向きの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
887 ページの「ページのプリント」の節で詳しく説明している基本的なプリントジョブの実行手順では、指定したスプライ
トの画面サイズおよび位置を直接反映した同等のプリントが出力されます。しかし、プリンターの解像度は環境によって異なり、また、プリンターの設定によってスプライトのプリント結果に悪影響が出る場合もあります。

Flash ランタイムはオペレーティングシステムの印刷設定を読み取ることができますが、これらのプロパティは読み取り専用です。値に応答できても、設定はできません。したがって、プリンターの用紙サイズ設定を調べた後は、そのサイズに合
わせてコンテンツを調整できます。また、プリンターの余白や用紙の向きに関する設定を調べることもできます。プリン
ターの設定に合わせるには、プリント範囲の指定、画面解像度とプリンターのポイント尺度との違いに関する調整、用紙のサイズと向きに応じた変換などを行います。

矩形によるプリント範囲の指定Flash Player 9 以降、Adobe AIR 1.0 以降
PrintJob.addPage() メソッドでは、プリントするスプライトの範囲を指定できます。それには、第 2 パラメーターのprintArea として Rectangle オブジェクトを指定します。このパラメーターの値については、次の 3 つの指定方法があります。

•

特定のプロパティを持つ Rectangle オブジェクトを作成し、それを次のように addPage() の呼び出しで使用します。
private var rect1:Rectangle = new Rectangle(0, 0, 400, 200);
myPrintJob.addPage(sheet, rect1);• Rectangle オブジェクトを前もって指定しない場合は、次のように、呼び出し時に直接指定できます。
myPrintJob.addPage(sheet, new Rectangle(0, 0, 100, 100));• addPage() 呼び出しの第 3 パラメーターを指定する必要がある場合に、プリント範囲の矩形を指定しないようにするには、
次のように、第 2 パラメーターとして null を使用します。
myPrintJob.addPage(sheet, null, options);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

892

プリント

ポイントとピクセルの比較
Flash Player 9 以降、Adobe AIR 1.0 以降
矩形の幅と高さはピクセル値です。一方、プリンターで使用する測定単位はポイントです。ポイントの物理サイズは固定（1/72 インチ）ですが、画面上のピクセルのサイズは解像度によって異なります。したがって、ピクセル値とポイント値の変換比率は、プリンターの設定と、スプライトが拡大または縮小されているかどうかによって変化します。72 ピクセル幅の伸縮されていない Sprite は、用紙上では 1 インチ幅で印刷されます。1 ポイントは 1 ピクセルに相当し、画面の解像度とは無関係です。
インチおよびセンチメートルと、ポイントおよび twip（1/20 ポイント）との間には、次の等式が成り立ちます。

• 1 ポイント = 1/72 インチ = 20 twip
• 1 インチ = 72 ポイント = 1440 twip
• 1 センチメートル = 567 twip
printArea パラメーターを省略するか、このパラメーターの指定が正しくない場合は、スプライト全体がプリントされます。

拡大／縮小
Flash Player 9 以降、Adobe AIR 1.0 以降
印刷前に Sprite オブジェクトを拡大／縮小するには、PrintJob.addPage() メソッドを呼び出す前に拡大／縮小のプロパティ（171 ページの「サイズの変更とオブジェクトの拡大／縮小」を参照）を設定します。印刷後、これらのプロパティを元の値に戻します。Sprite オブジェクトの拡大／縮小は、printArea プロパティとは無関係です。つまり、50×50 ピクセルのプリン
ト範囲を指定した場合は常に 2500 個のピクセルがプリントされます。Sprite オブジェクトを拡大または縮小している場合、その設定を反映してプリント結果は伸縮しますが、プリントの対象となる 2500 個のピクセルは変わりません。
例については、897 ページの「プリントの例：拡大／縮小、トリミング、および応答」を参照してください。

横長 / 縦長方向のプリント
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player または AIR では用紙の向きの設定を検出できるため、次の例に示すように、プリンター設定に応じてコンテン
ツのサイズや向きを調整するロジックを ActionScript に組み込むことができます。
if (myPrintJob.orientation == PrintJobOrientation.LANDSCAPE){
mySprite.rotation = 90;}

注意：用紙の向きについてシステム設定を読み込む場合は、PrintJobOrientation クラスを読み込んでください。

PrintJobOrientation クラスには、用紙の向きを表す定数値が定義されています。クラスを読み込むには次のステートメン
トを使用します。
import flash.printing.PrintJobOrientation;

ページの幅と高さへの対応
Flash Player 9 以降、Adobe AIR 1.0 以降
用紙の向きに関する設定情報を扱う場合と同様に、if ステートメントで囲んだロジックを埋め込むと、ページの幅と高さの設定を読み取って、それに応じた処理ができます。その例を次のコードに示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

893

プリント

if (mySprite.height > myPrintJob.pageHeight){
mySprite.scaleY = .75;}

また、余白の設定を調べるには、次のように用紙の寸法とページの寸法を比較します。
margin_height = (myPrintJob.paperHeight - myPrintJob.pageHeight) / 2;
margin_width = (myPrintJob.paperWidth - myPrintJob.pageWidth) / 2;

高度なプリント技術
Adobe AIR 2 以降
Adobe AIR 2 以降、PrintJob クラスにはプロパティおよびメソッドが追加されています。また、3 つのクラス（PrintUIOptions、PaperSize および PrintMethod）が追加でサポートされるようになりました。これらの変更によって、プリンターのワークフローを追加できるようになり、作成者はより詳細にプリント処理を制御できるようになりました。変
更には、以下の内容が含まれます。

•

ページ設定ダイアログ：標準ダイアログとページ設定ダイアログの両方を表示できます。ユーザーは、印刷する前に、印
刷範囲、用紙サイズ、用紙の方向および拡大／縮小を設定できます。

•

プリント表示：用紙サイズ、余白およびページ上のコンテンツの位置を正確に表示する表示モードを作成できます。

•

プリント制限：作成者は印刷可能なページの範囲などの印刷オプションを制限できます。

•

品質オプション：作成者はドキュメントのプリント品質を調整でき、ユーザーは解像度とカラーオプションを選択できます。

•

複数のプリントセッション：単一の PrintJob インスタンスで複数のプリントセッションを処理できるようになりました。
ページ設定と印刷ダイアログが表示されるたびに、アプリケーションで一貫した設定を提供できます。

プリントワークフローの変更
新しいプリントワークフローは、次の 4 つの手順から構成されます。

• new PrintJob()：PrintJob インスタンスを作成（または既存のインスタンスを再利用）します。PrintJob の新しいプロパ
ティおよびメソッド（selectPaperSize() など）の多くは、プリントジョブの開始前またはプリント中に使用できます。

• PrintJob.showPageSetupDialog()：（省略可）プリントジョブを開始せずに、ページ設定ダイアログを表示します。
• PrintJob.start() または PrintJob.start2()：start() メソッドに加え、start2() メソッドを使用して、プリントスプール処理を開始できます。start2() メソッドを使用すると、印刷ダイアログを表示して、表示時にダイアログをカスタマイズするかどうかを選択できます。

• PrintJob.addPage()：コンテンツをプリントジョブに追加します。既存のプロセスからの変更はありません。
• PrintJob.send() または PrintJob.terminate()：選択されたプリンターにページを送信するか、または送信せずにプリント
ジョブを強制終了します。プリントジョブはエラーに応答して強制終了されます。PrintJob インスタンスは、強制終了
されても引き続き再利用できます。プリントジョブをプリンターに送信するか、強制終了するかに関わらず、PrintJob
インスタンスを再利用するときは、現在の印刷設定が保持されます。

ページ設定ダイアログ
showPageSetupDialog() メソッドは、現在の環境でサポートされている場合、オペレーティングシステムのページ設定ダイア
ログを表示します。このメソッドは呼び出す前に、必ず、supportsPageSetupDialog プロパティを確認してください。次に簡単な例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

894

プリント

import flash.printing.PrintJob;
var myPrintJob:PrintJob = new PrintJob();//check for static property supportsPageSetupDialog of PrintJob classif (PrintJob.supportsPageSetupDialog) {myPrintJob.showPageSetupDialog();}

このメソッドは、必要に応じて、ページ設定ダイアログに表示するオプションを制御する PrintUIOptions クラスのプロパ
ティと共に呼び出すことができます。ページ番号の最小値と最大値を設定できます。次の例では、最初の 3 ページの印刷に制限しています。
import flash.printing.PrintJob;
var myPrintJob:PrintJob = new PrintJob();
if (PrintJob.supportsPageSetupDialog) {var uiOpt:PrintUIOptions = new PrintUIOptions();
uiOpt.minPage = 1;
uiOpt.maxPage = 3;
myPrintJob.showPageSetupDialog(uiOpt);}

プリント設定の変更
PrintJob インスタンスの設定は、インスタンスの作成後、いつでも変更できます。例えば、addPage() を次回呼び出すとき
や、プリントジョブが送信または強制終了された後などに、設定を変更できます。printer プロパティなどの一部の設定は、個々のページではなく、プリントジョブ全体に適用されます。これらの設定は、start() または start2() を呼び出す前に設定されている必要があります。

selectPaperSize() メソッドは、ページ設定ダイアログおよび印刷ダイアログで、デフォルトの用紙サイズを設定するために呼び出すことができます。プリントジョブ中に呼び出して、特定のページ範囲の用紙サイズを設定することもできます。このメソッドは PaperSize クラスで定義されている定数を使用して呼び出されます。次の例では、#10 封筒サイズが選択されています。
import flash.printing.PrintJob;
import flash.printing.PaperSize;
var myPrintJob:PrintJob = new PrintJob();
myPrintJob.selectPaperSize(PaperSize.ENV_10);

printer プロパティを使用して、現在のプリントジョブのプリンター名を取得または設定します。デフォルトで、このプロパ
ティは既定のプリンターの名前に設定されます。利用可能なプリンターがないか、システムでプリントがサポートされていない場合、printer プロパティは null です。プリンターを変更するには、最初に printers プロパティを使用して利用可能なプ
リンターの一覧を取得します。このプロパティは String エレメントが利用可能なプリンター名であるベクターです。printerプロパティをこれらの String 値のいずれかに設定して、対象のプリンターをアクティブにします。アクティブな印刷ジョブの printer プロパティは変更できません。start() または start2() が正常に呼び出された後で、ジョブが送信または強制終了される前にこのプロパティを変更しようとすると、その操作は失敗します。このプロパティの設定例を次に示します。
import flash.printing.PrintJob;
var myPrintJob:PrintJob = new PrintJob();
myPrintJob.printer = "HP_LaserJet_1";
myPrintJob.start();copies プロパティは、オペレーティングシステムの印刷ダイアログの部数の値を取得します。firstPage と lastPage のプロパ
ティによって、ページ範囲を取得します。orientation プロパティは、用紙の向きの設定を取得します。これらのプロパティを設定すると、印刷ダイアログの値を上書きできます。これらのプロパティの設定例を次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

895

プリント

import flash.printing.PrintJob;
import flash.printing.PrintJobOrientation;
var myPrintJob:PrintJob = new PrintJob();
myPrintJob.copies = 3;
myPrintJob.firstPage = 1;
myPrintJob.lastPage = 3;
myPrintJob.orientation = PrintJobOrientation.LANDSCAPE;

PrintJob に関連付けられた次の読み取り専用の設定は、現在のプリンター設定に関する有用な情報を提供します。

• paperArea：プリンター用メディアの長方形範囲（ポイント単位）• printableArea：印刷可能な領域の長方形範囲（ポイント単位）• maxPixelsPerInch：現在のプリンターの物理的な解像度（ピクセル / インチ）
• isColor：現在のプリンターのカラー印刷機能の有無（現在のプリンターがカラー印刷可能な場合、true を返します）
898 ページの「プリントの例：ページ設定とプリントオプション」を参照してください。

プリントの例：複数ページのプリント
Flash Player 9 以降、Adobe AIR 1.0 以降
複数ページのコンテンツをプリントする場合は、各ページのコンテンツを別々のスプライト（下の例では sheet1 と sheet2）に割り当て、それぞれについて PrintJob.addPage() を呼び出します。このテクニックを説明するコードを次に示します。
package{import flash.display.MovieClip;
import flash.printing.PrintJob;
import flash.printing.PrintJobOrientation;
import flash.display.Stage;
import flash.display.Sprite;
import flash.text.TextField;
import flash.geom.Rectangle;
public class PrintMultiplePages extends MovieClip{
private var sheet1:Sprite;
private var sheet2:Sprite;
public function PrintMultiplePages():void{init();
printPages();}
private function init():void{
sheet1 = new Sprite();createSheet(sheet1, "Once upon a time...", {x:10, y:50, width:80, height:130});
sheet2 = new Sprite();createSheet(sheet2, "There was a great story to tell, and it ended quickly.\n\nThe end.", null);}
private function createSheet(sheet:Sprite, str:String, imgValue:Object):void{
sheet.graphics.beginFill(0xEEEEEE);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

896

プリント

sheet.graphics.lineStyle(1, 0x000000);
sheet.graphics.drawRect(0, 0, 100, 200);
sheet.graphics.endFill();var txt:TextField = new TextField();
txt.height = 200;
txt.width = 100;
txt.wordWrap = true;
txt.text = str;
if (imgValue != null){var img:Sprite = new Sprite();img.graphics.beginFill(0xFFFFFF);
img.graphics.drawRect(imgValue.x, imgValue.y, imgValue.width, imgValue.height);
img.graphics.endFill();sheet.addChild(img);}
sheet.addChild(txt);}
private function printPages():void{
var pj:PrintJob = new PrintJob();var pagesToPrint:uint = 0;
if (pj.start()){
if (pj.orientation == PrintJobOrientation.LANDSCAPE){
throw new Error("Page is not set to an orientation of portrait.");}sheet1.height = pj.pageHeight;
sheet1.width = pj.pageWidth;
sheet2.height = pj.pageHeight;
sheet2.width = pj.pageWidth;try{
pj.addPage(sheet1);
pagesToPrint++;}
catch (error:Error){// Respond to error.

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

897

プリント

}
try
{
pj.addPage(sheet2);
pagesToPrint++;}
catch (error:Error){// Respond to error.
}
if (pagesToPrint > 0){
pj.send();
}
}
}
}
}

プリントの例：拡大／縮小、トリミング、および応答
Flash Player 9 以降、Adobe AIR 1.0 以降
場合によっては、画面の表示とプリントとの外観上の違いに対応するために、表示オブジェクトのサイズ（またはその他のプロパティ）をプリント時に調整する必要が生じることがあります。プリントの前に表示オブジェクトのプロパティ（例：scaleX および scaleY プロパティ）を調整する際には、プリント範囲を定義する矩形よりも大きくオブジェクトを拡大するとトリミングされることに注意してください。また、多くの場合には、ページをプリントした後でプロパティを元の値に戻す必要があります。
次のコードは、txt 表示オブジェクトの寸法を拡大／縮小するので（ただし、背景の緑色のボックスはそのまま）、指定した矩形のサイズだけテキストフィールドがトリミングされます。プリントした後は、テキストフィールドを画面表示用の元のサイズに戻します。ユーザーが OS の印刷ダイアログボックスでプリントジョブをキャンセルした場合は、Flash ランタイムの表示内容が、ジョブのキャンセルを知らせる警告に変わります。
package{import flash.printing.PrintJob;
import flash.display.Sprite;
import flash.text.TextField;
import flash.display.Stage;
import flash.geom.Rectangle;
public class PrintScaleExample extends Sprite{
private var bg:Sprite;
private var txt:TextField;
public function PrintScaleExample():void{init();draw();
printPage();}private function printPage():void{

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

898

プリント

var pj:PrintJob = new PrintJob();
txt.scaleX = 3;
txt.scaleY = 2;
if (pj.start()){
trace(">> pj.orientation: " + pj.orientation);trace(">> pj.pageWidth: " + pj.pageWidth);
trace(">> pj.pageHeight: " + pj.pageHeight);
trace(">> pj.paperWidth: " + pj.paperWidth);
trace(">> pj.paperHeight: " + pj.paperHeight);
try{
pj.addPage(this, new Rectangle(0, 0, 100, 100));}
catch (error:Error){// Do nothing.
}
pj.send();}else{
txt.text = "Print job canceled";}// Reset the txt scale properties.
txt.scaleX = 1;
txt.scaleY = 1;}
private function init():void{
bg = new Sprite();bg.graphics.beginFill(0x00FF00);
bg.graphics.drawRect(0, 0, 100, 200);
bg.graphics.endFill();
txt = new TextField();
txt.border = true;
txt.text = "Hello World";}
private function draw():void{
addChild(bg);addChild(txt);
txt.x = 50;
txt.y = 50;}}}

プリントの例：ページ設定とプリントオプション
Adobe AIR 2 以降
次の例では、部数、用紙サイズ（リーガル）、印刷の向き（横）について、PrintJob 設定を初期化しています。最初にページ設定ダイアログを表示してから、印刷ダイアログを表示して印刷ジョブを開始します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

899

プリント

package{import flash.printing.PrintJob;
import flash.printing.PrintJobOrientation;
import flash.printing.PaperSize;import flash.printing.PrintUIOptions;
import flash.display.Sprite;
import flash.text.TextField;
import flash.display.Stage;
import flash.geom.Rectangle;
public class PrintAdvancedExample extends Sprite{
private var bg:Sprite = new Sprite();private var txt:TextField = new TextField();
private var pj:PrintJob = new PrintJob();
private var uiOpt:PrintUIOptions = new PrintUIOptions();
public function PrintAdvancedExample():void{
initPrintJob();
initContent();draw();
printPage();}private function printPage():void{//test for dialog support as a static property of PrintJob classif (PrintJob.supportsPageSetupDialog){
pj.showPageSetupDialog();}if (pj.start2(uiOpt, true)){try{
pj.addPage(this, new Rectangle(0, 0, 100, 100));}
catch (error:Error){// Do nothing.
}
pj.send();}else{
txt.text = "Print job terminated";
pj.terminate();}}private function initContent():void{
bg.graphics.beginFill(0x00FF00);
bg.graphics.drawRect(0, 0, 100, 200);
bg.graphics.endFill();
txt.border = true;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

900

プリント

txt.text = "Hello World";}
private function initPrintJob():void{
pj.selectPaperSize(PaperSize.LEGAL);
pj.orientation = PrintJobOrientation.LANDSCAPE;
pj.copies = 2;
pj.jobName = "Flash test print";}
private function draw():void{
addChild(bg);addChild(txt);
txt.x = 50;
txt.y = 50;}}}

最終更新日 2015/10/14

901

第 55 章：ジオロケーション
デバイスでジオロケーションがサポートされている場合、このジオロケーション API を使用して、デバイスの最新の位置情報を取得できます。デバイスがこの機能をサポートしている場合は、ジオロケーション情報を取得できます。この情報には、場所の最新の変化の高度、精度、向き、速度およびタイムスタンプが含まれます。

Geolocation クラスは、デバイスのロケーションセンサーに応答して update イベントを送出します。update イベントはGeolocationEvent オブジェクトです。
関連項目

flash.sensors.Geolocation
flash.events.GeolocationEvent

ジオロケーション変化の検出
ジオロケーションセンサーを使用するには、Geolocation オブジェクトをインスタンス化し、このオブジェクトが送出する

update イベントを登録します。update イベントは、Geolocation イベントオブジェクトです。このイベントには次の 8 個のプロパティがあります。

• altitude — 高度（メートル単位）を返します。
• heading — 真北を基準とする移動の方角（整数）を返します。
• horizontalAccuracy — 水平精度（メートル単位）を返します。
• latitude — 緯度（度単位）を返します。
• longitude — 経度（度単位）を返します。
• speed — 速度（m/ 秒）を返します。
• timestamp — ランタイムが初期化されてからイベント発生時までの時間（ミリ秒）です。
• verticalAccuracy — 垂直精度（メートル単位）を返します。
timestamp プロパティは int オブジェクトです。その他は Number オブジェクトです。
テキストフィールドでジオロケーションデータを表示する基本的な例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

902

ジオロケーション

var geo:Geolocation;
if (Geolocation.isSupported){geo = new Geolocation();geo.addEventListener(GeolocationEvent.UPDATE, updateHandler);}else{
geoTextField.text = "Geolocation feature not supported";}function updateHandler(event:GeolocationEvent):void{
geoTextField.text = "latitude: " + event.latitude.toString() + "\n"+ "longitude: " + event.longitude.toString() + "\n"+ "altitude: " + event.altitude.toString()+ "speed: " + event.speed.toString()+ "heading: " + event.heading.toString()+ "horizontal accuracy: " + event.horizontalAccuracy.toString()+ "vertical accuracy: " + event.verticalAccuracy.toString()}

この例を使用するには、必ず geoTextField テキストフィールドを作成し、そのフィールドを表示リストに追加してから、このコードを使用します。
ジオロケーションイベントの目的の間隔を調整するには、Geolocation オブジェクトの setRequestedUpdateInterval() メソッ
ドを呼び出します。このメソッドは 1 つのパラメーター interval を受け取ります。これは、必要な更新間隔（ミリ秒単位）です。
var geo:Geolocation = new Geolocation();geo.setRequestedUpdateInterval(10000);

ジオロケーションを更新する実際の間隔は、この値より大きかったり小さかったりする可能性があります。更新間隔が変更された場合、登録されたリスナーすべてに影響します。setRequestedUpdateInterval() メソッドを呼び出さない場合、アプリ
ケーションはデバイスのデフォルトの間隔に基づいて更新を受け取ります。
ユーザーは、アプリケーションがジオロケーションデータにアクセスするのを防ぐことができます。例えば、iPhone は、
アプリケーションがジオロケーションデータを入手しようとしたときに、ユーザーにプロンプトを表示します。ユーザーは、
プロンプトに応じて、ジオロケーションデータへのアプリケーションアクセスを拒否できます。ユーザーがジオロケーショ
ンデータへのアクセスを使用できないようにしたときに、Geolocation オブジェクトは status イベントを送出します。また、

Geolocation オブジェクトには muted プロパティがあります。このプロパティは、ジオロケーションセンサーを使用できな
いときに、true に設定されます。Geolocation オブジェクトは、muted プロパティが変更されると、status イベントを送出します。次のコードは、ジオロケーションデータを使用できないときの検出方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

903

ジオロケーション

package{import flash.display.Sprite;
import flash.display.StageAlign;import flash.display.StageScaleMode;
import flash.events.GeolocationEvent;import flash.events.MouseEvent;import flash.events.StatusEvent;import flash.sensors.Geolocation;
import flash.text.TextField;
import flash.text.TextFormat;
public class GeolocationTest extends Sprite{
private var geo:Geolocation;
private var log:TextField;
public function GeolocationTest(){
super();
stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
setUpTextField();
if (Geolocation.isSupported){geo = new Geolocation();if (!geo.muted){
geo.addEventListener(GeolocationEvent.UPDATE, geoUpdateHandler);}geo.addEventListener(StatusEvent.STATUS, geoStatusHandler);}else{
log.text = "Geolocation not supported";}}
public function geoUpdateHandler(event:GeolocationEvent):void{
log.text = "latitude : " + event.latitude.toString() + "\n";log.appendText("longitude : " + event.longitude.toString() + "\n");}public function geoStatusHandler(event:StatusEvent):void{if (geo.muted)
geo.removeEventListener(GeolocationEvent.UPDATE, geoUpdateHandler);else
geo.addEventListener(GeolocationEvent.UPDATE, geoStatusHandler);}private function setUpTextField():void

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

904

ジオロケーション{
log = new TextField();
var format:TextFormat = new TextFormat("_sans", 24);log.defaultTextFormat = format;
log.border = true;log.wordWrap = true;
log.multiline = true;
log.x = 10;
log.y = 10;
log.height = stage.stageHeight - 20;
log.width = stage.stageWidth - 20;
log.addEventListener(MouseEvent.CLICK, clearLog);
addChild(log);}
private function clearLog(event:MouseEvent):void{
log.text = "";}}}注意：GPS を搭載していない第 1 世代 iPhone は、update イベントをほとんど送出しません。このデバイスでは、

Geolocation オブジェクトが最初に 1 つまたは 2 つの update イベントを送出します。その後、情報が大幅に変更されたときに update イベントを送出します。

ジオロケーションサポートの確認
ランタイム環境でこの機能を使用できるかどうかをテストするには、Geolocation.isSupported プロパティを使用します。
if (Geolocation.isSupported){// Set up geolocation event listeners and code.
}

現在、ジオロケーションがサポートされているのは、iPhone および Flash Lite 4 用の ActionScript ベースのアプリケー
ションのみです。Geolocation.isSupported が実行時に true の場合は、ジオロケーションサポートが存在しています。
一部の iPhone モデルには GPS ユニットがありません。これらのモデルは他の方法（携帯電話の三角測量など）を使用して、ジオロケーションデータを取得します。これらのモデルや、GPS を無効にしている iPhone では、Geolocation オブ
ジェクトは 1 つまたは 2 つの初期 update イベントを送出できるだけです。

最終更新日 2015/10/14

905

第 56 章：アプリケーションの国際化
Flash Player 10.1 以降、Adobe AIR 2.0 以降
flash.globalization パッケージを使用すると、別の言語や地域の表記規則に適合する国際化対応ソフトウェアを容易に作成
できます。

関連項目

flash.globalization パッケージ
921 ページの「アプリケーションのローカライズ」
Charles Bihis：Want to Localize your Flex/AIR Apps?

アプリケーション国際化の基礎「グローバリゼーション」と「国際化」という用語は、よく同じ意味で使用されることがあります。ただし、ほとんどの定義に基づくと、「国際化」がエンジニアリングプロセスについてのみ使用されるのに対して、「グローバリゼーション」はビジ
ネスプロセスとエンジニアリングプロセスを合わせたものについて使用されます。
以下に、いくつかの重要な用語の定義を示します。
グローバリゼーション 製品および企業の活動を世界規模で準備および立ち上げるために必要な、広範なエンジニアリングプ
ロセスとビジネスプロセスのことです。グローバリゼーションは、国際化、ローカリゼーション、カルチャライゼーションなどのエンジニアリング活動と、製品管理、財務計画、マーケティング、法務などのビジネス活動から成ります。グローバ
リゼーションは「G11n」と略記されることもあります。これは、「Globalization」という単語の先頭が G、末尾が n で、間に 11 個の文字があるからです。グローバリゼーションは「ビジネスの観点」で行われる作業を指す言葉です。
国際化対応 複数の言語、スクリプトおよび文化に基づく表記規則（通貨、並べ替え規則、数値および日付の形式など）の設計やコンパイルをやり直すことなく、製品の汎用化を行うエンジニアリングプロセスのことです。このプロセスは、イネー
ブルメントとローカリゼーションという 2 つの活動に分けられます。国際化は、「World-Readiness（世界への対応化）」と呼ばれることがあります。また、「I18n」と略記されることもあります。国際化は「エンジニアリングの観点」で行われる作業を指す言葉です。
ローカリゼーション 製品またはサービスを特定の言語、文化および対象の地域向けの画面や操作性に適合させるためのプロ
セスのことです。ローカリゼーションは、「L10n」と略記されることがあります。ローカリゼーションは「翻訳者の観点」
で行われる作業を指す言葉です。
カルチャライゼーション 文化の独自性のニーズに基づいた固有の機能を開発または適合化するためのエンジニアリングプロ
セスです。この例として、Adobe InDesign で使用可能な日本語組版機能や Adobe Acrobat でのハンコ（スタンプ機能）への対応などがあります。
国際化に関するいくつかの重要な用語とその定義を次に示します。
文字セット ある言語または言語グループによって使用される文字のことです。文字セットには、各国語文字、特殊文字（句
読記号、数学記号など）、数字およびコンピューター制御文字などがあります。
照合順序 テキストを特定のロケール用に適切な順序に並べ替えることです。
ロケール 地理、政治または文化によって区分された地域（多くの場合、それぞれが 1 つの国に該当します）で使用される言語と文化上の表記規則を表す値のことです。この値は、一意のロケール識別子（ロケール ID）によって表されます。ロケー

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

906

アプリケーションの国際化

ル ID は、そのロケール固有のサポートを提供する一連のロケールデータを検索するのに使用されます。このサポートは、測定単位（つまり、数字や日付などの解析とフォーマット）に適用されます。
リソースバンドル アプリケーションが使用されるロケール用に作成されるロケール固有の要素を格納したセットのことです。通常、リソースバンドルには、アプリケーションのユーザーインターフェイスのテキスト要素がすべて含まれます。バンドル内では、これらの要素は特定のロケールの適切な言語に翻訳されています。また、特定のロケール用のユーザーイン
ターフェイスのレイアウトや動作を変更する、その他の設定も含めることができます。リソースバンドルには、他のメディアタイプや、ロケールに固有の他のメディアタイプへの参照を含めることができます。

flash.globalization パッケージの概要
Flash Player 10.1 以降、Adobe AIR 2.0 以降
flash.globalization パッケージは、基になるオペレーティングシステムの文化サポート機能を利用します。これによって、個別のユーザーの文化上の表記規則に準拠したアプリケーションの記述が容易になります。
パッケージに含まれる主なクラスは、次のとおりです。

•

文字列の並べ替えと照合を管理する Collator クラス•

数値を通貨の金額文字列の形式に変更し、入力文字列から通貨の金額と記号を解釈する CurrencyFormatter クラス•

日付の値の形式を設定する DateTimeFormatter クラス•

特定のロケールに関する情報を取得する LocaleID クラス•

数値の形式の設定および解釈を行う NumberFormatter クラス•

ロケールに基づいた文字列の大文字と小文字の変換を処理する StringTools クラス

flash.globalization パッケージとリソースのローカリゼーション
flash.globalization パッケージはリソースのローカリゼーションを処理しません。ただし、他のテクニックを使用して、ローカライズされたリソースを取得するためのキー値として、flash.globalization ロケール ID を使用できます。例えば、
ResourceManager クラスおよび ResourceBundle クラスを使用して、Flex で作成されたアプリケーションリソースをロー
カライズできます。詳しくは、「Flex アプリケーションのローカライズ」を参照してください。
922 ページの「AIR アプリケーションのローカライズ」で説明しているように、Adobe AIR 1.1 には、AIR アプリケー
ションのローカライズに役立ついくつかの機能が用意されています。

アプリケーション国際化の一般的な方法
次の手順は、flash.globalization パッケージを使用してアプリケーションを国際化するための高レベルな共通の手順を示しています。

1 ロケールを決定または設定します。
2 サーバークラスのインスタンス（Collator、CurrencyFormatter、DateTimeFormatter、NumberFormatter またはStringTools）を作成します。
3 lastOperationStatus プロパティを使用してエラーと代替を確認します。
4 ロケールに固有の設定を使用して、情報の形式を設定し、表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

907

アプリケーションの国際化

次の手順では、ロケールに固有の文字列およびユーザーインターフェイスリソースをロードおよび表示します。この手順には次のようなタスクを含めることができます。

•

自動レイアウト機能を使用して、文字列の長さに合わせて UI のサイズを変更する•

適切なフォントを選択し、フォントの代替をサポートする• FTE テキストエンジンを使用して他の書き込みシステムをサポートする•

入力方式エディターが正しく処理されることを確認する

エラーと代替の確認
flash.globalization サービスクラスではすべて、同様のパターンに従ってエラーを識別します。また、要求されているロケールが使用できない場合に、その代わりとして、ユーザーのオペレーティングシステムがサポートしているロケールを使用するときの代替パターンも共有しています。
次の例は、サービスクラスをインスタンス化するときのエラーと代替の確認方法を示しています。各サービスクラスには、直前のメソッド呼び出しでエラーまたは警告がトリガーされたかどうかを示す lastOperationStatus プロパティがあります。
var nf:NumberFormatter = new NumberFormatter("de-DE");if(nf.lastOperationStatus != LastOperationStatus.NO_ERROR){
if(nf.lastOperationStatus == LastOperationStatus.USING_FALLBACK_WARNING){// perform fallback logic here, if needed
trace("Warning - Fallback locale ID: " + nf.actualLocaleIDName);}else{// perform error handling logic here, if needed
trace("Error: " + nf.lastOperationStatus);}}

この例では、代替ロケール ID が使用されたか、エラーがある場合に、単純にメッセージをトレースします。アプリケー
ションでは、必要に応じて追加のエラー処理ロジックを実行できます。例えば、メッセージをユーザーに表示して、サポートされている特定のロケールを使用するようにアプリケーションに強制することができます。

ロケールの特定Flash Player 10.1 以降、Adobe AIR 2.0 以降
ロケールは、言語と、国または地域の文化に基づく表記規則の特定の組み合わせを識別します。
ロケール識別子は、文字列として安全に管理できます。ただし、LocaleID クラスを使用して、ロケールに関連する追加情報を取得することができます。

LocaleID オブジェクトは次のように作成します。
var locale:LocaleID = new LocaleID("es-MX");

LocaleID オブジェクトの作成後は、ロケール ID に関するデータを取得できます。getKeysAndValues()、getLanguage()、
getRegion()、getScript()、getVariant() および isRightToLeft() メソッドと name プロパティを使用します。
これらのメソッドおよびプロパティから取得された値は、ロケールに関してロケール識別子から直接抽出できない追加の情報を反映することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

908

アプリケーションの国際化

アプリケーションが日付表示形式などのロケール対応サービスを作成するときは、使用するロケールを指定する必要があります。サポートされているロケールのリストは、オペレーティングシステムごとに異なるので、要求されたロケールが必ずしも使用できるとは限りません。

Flash Player は、要求されたロケールの言語コードに一致するように最初に試みます。次に、一致する書き込みシステム（スクリプト）および地域を検索してロケールを調整します。次に、例を示します。
var loc:LocaleID = new LocaleID("es");
trace(loc.getLanguage()); // estrace(loc.getScript()); // Latn
trace(loc.getRegion()); // ES

この例では、LocaleID() コンストラクターが、そのユーザーの言語コード「es」に最も一致するロケールに関するデータを取得しました。

ロケール ID の設定
アプリケーションの現在のロケールを設定する方法は、次のように複数あります。

•

単一のロケール ID をアプリケーションにハードコーディングする。これは一般的な手法ですが、アプリケーションの国
際化をサポートしていません。

•

ユーザーのオペレーティングシステムまたはブラウザーからロケール ID 環境設定を使用するか、またはその他のユー
ザー環境設定を使用する。通常、この手法によりユーザーに対する最適なロケール設定が得られますが、常に正確であるとは限りません。オペレーティングシステム設定にユーザーの実際の環境設定が反映されていないというリスクがあります。例えば、ユーザーは共有されたコンピューターを使用していて、オペレーティングシステムで希望のロケールを変更できない可能性があります。

•

ユーザーの環境設定に基づいてロケール ID を設定したら、サポートされているロケールの一覧からユーザーが選択できるようにします。アプリケーションが複数のロケールをサポートできる場合、通常はこの手法が最善のオプションです。

この 3 つ目のオプションは次のように実装できます。

1 ユーザープロファイル、ブラウザー設定、オペレーティングシステム設定または Cookie から、ユーザーが希望するロケールまたは言語のリストを取得します（アプリケーションはこのロジックを実装する必要があります。

flash.globalization ライブラリは、このような環境設定を直接読み取ることはサポートしていません）。
2 これらのロケールのうち、アプリケーションがサポートしているものを判断し、デフォルトで最適なものを選択します。

LocaleID.determinePreferredLocales() メソッドを使用して、希望のロケールおよびオペレーティングシステムでサポートされているロケールに基づいて、ユーザーに対して最適なロケールを見つけます。

3 デフォルトのロケールが適切でない場合に備えて、デフォルトのロケール設定をユーザーが変更する方法を用意します。

ロケールと言語用の他のクラスでの制限
fl.lang.Locale クラスを使用すると、文字列値を含むリソースバンドルを使用して、ロケールに基づいてテキスト文字列を置き換えることができます。ただし、このクラスは、数、通貨、日付の形式の設定、並べ替え、一致など、その他の国際化機
能をサポートしていません。さらに、このクラスは Flash Professional のみでしか使用できません。
また、flash.system.Capabilities.language プロパティを使用して、オペレーティングシステムの現在の言語コード設定を取得できます。ただし、このプロパティは、完全なロケール ID ではなく、2 文字表記の ISO 639-1 言語コードのみを取得し、特定のロケールセットのみをサポートします。

AIR 1.5 では、flash.system.Capabilities.languages プロパティを使用できます。このプロパティは、ユーザーが優先するユー
ザーインターフェイスの言語の配列を提供します。したがって、このプロパティには Capabilities.language の制限はありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

909

アプリケーションの国際化

数値の形式の設定
Flash Player 10.1 以降、Adobe AIR 2.0 以降
数値の表示形式は地域によって大きく異なります。例えば、特定のロケールでは数値 123456.78 は次のように形式が設定さ
れます。
ロケール

数値形式

en-US（英語、米国）-123,456.78

de-DE（ドイツ語、ドイツ）-123.456,78

fr-FR（フランス、フランス語）-123 456,78

de-CH （ドイツ語、スイス）-123'456.78

en-IN（英語、インド）-1,23,456.78

多くのアラビア語ロケール

123,456.78-

数値形式には、次の示すものを含めて多くの要素が影響します。

•

区切り文字。小数点区切り文字は、数値の整数部分と小数部分の間に配置されます。これは、ピリオド、カンマまたはその他の文字の場合があります。グループの区切り文字または 1000 の区切り文字は、ピリオド、カンマ、改行しないス
ペースまたは別の文字の場合があります。

•

グループのパターン。小数点より左にある各グループ区切り文字間の桁数は、2 桁、3 桁またはその他の値の場合があります。

•

マイナスの数値の表示。マイナスの数値は、数値の左または右にマイナス記号を付けて表示するか、または財務アプリ
ケーションでは括弧内に表示する場合があります。例えば、マイナス 19 は -19、19- または (19) と表示されます。

•

先頭および末尾のゼロ一部の文化上の表記規則では、表示される値に先頭または末尾のゼロが追加されます。例えば、値0.17 は .17、0.17、0.170 などのように表示されます。

•

異なる数字のセット。ヒンズー語、アラビア語、日本語など多くの言語では、異なる数字のセットが使用されます。

flash.globalization パッケージは、0 〜 9 にマップされる任意の数字をサポートしています。
NumberFormatter クラスでは、数値の形式を設定するときに、これらの要素がすべて考慮されます。

NumberFormatter クラスの使用
NumberFormatter クラスは、特定のロケールの表記規則に従って、数値（int、uint、または Number タイプ）の形式を設定します。
次の例は、ユーザーのオペレーティングシステムで提供されるデフォルトの形式プロパティを使用して数値の形式を設定するための、最も簡単な方法を示しています。
var nf:NumberFormatter = new NumberFormatter(LocaleID.DEFAULT);
trace(nf.formatNumber(-123456.789))

この結果は、ユーザーのロケール設定およびユーザー環境設定に応じて異なります。例えば、ユーザーのロケールが fr-FRの場合、設定される値は次のようになります。

-123.456,789
ユーザーの設定に関わらず、特定のロケール用に数値の形式を設定するだけの場合は、ロケール名を固有に設定します。次に、例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

910

アプリケーションの国際化

var nf:NumberFormatter = new NumberFormatter("de-CH");
trace(nf.formatNumber(-123456.789));

この結果は次のようになります。

-123'456.789
formatNumber() メソッドは、Number をパラメーターとして受け取ります。NumberFormatter クラスには、int を入力として受け取る formatint() メソッドと、unit を入力として受け取る formatUnit() メソッドがあります。
この例に示すように、NumberFormatter クラスのプロパティを設定することにより、形式の設定ロジックを明示的に制御できます。
var nf:NumberFormatter = new NumberFormatter("de-CH");
nf.negativeNumberFormat = 0;
nf.fractionalDigits = 5;
nf.trailingZeros = true;
nf.decimalSeparator = ",";
nf.useGrouping = false;
trace(nf.formatNumber(-123456.789)); //(123456.78900)

この例では、最初に NumberFormatter オブジェクトを作成し、次のことを行います。

•

マイナスの数値の形式を設定して、財務アプリケーションと同様に括弧を使用するようにします。

•

小数点区切り文字の後の数値を 5 に設定します。

• 5 桁であることを確実にするために、末尾のゼロを使用することを指定します。
•

小数点区切り文字をカンマに設定します。

•

グループ区切り文字を使用しないように指定します。

注意：これらのプロパティの一部を変更すると、結果の数値形式は、指定されたロケールの形式に対応しなくなります。これらのプロパティは、ロケールへの対応が重視されない場合にのみ使用します。例えば、末尾に挿入するゼロの数など、数値形式の 1 つの側面のみを詳細に制御する必要がある場合や、ユーザーが Windows コントロールパネルから変更を直接要求している場合にのみ使用します。

数値を含む文字列の解析
NumberFormatter クラスは、ロケールに固有の形式要件に適合する文字列から数値を抽出することもできます。
NumberFormatter.parseNumber() メソッドは、文字列から単一の数値を抽出します。次に、例を示します。
var nf:NumberFormatter = new NumberFormatter( "en-US" );var inputNumberString:String = "-1,234,567.890"
var parsedNumber:Number = nf.parseNumber(inputNumberString);
trace("Value:" + parsedNumber); // -1234567.89
trace("Status:" + nf.lastOperationStatus); // noError

parseNumber() メソッドは、数字と、マイナス記号、区切り文字など数値の形式を設定する文字のみを含む文字列を処理します。文字列にそれら以外の文字が含まれていると、エラーコードが設定されます。
var nf:NumberFormatter = new NumberFormatter( "en-US" );var inputNumberString:String = "The value is 1,234,567.890"
var parsedNumber:Number = nf.parseNumber(inputNumberString);
trace("Value:" + parsedNumber); // NaN
trace("Status:" + nf.lastOperationStatus); // parseError

その他のアルファベット文字を含む文字列から数字を抽出するには、NumberFormatter.parse() メソッドを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

911

アプリケーションの国際化

var nf:NumberFormatter = new NumberFormatter( "en-US" );var inputNumberString:String = "The value is 123,456,7.890";
var parseResult:NumberParseResult = nf.parse(inputNumberString);
trace("Value:" + parseResult.value); // 1234567.89
trace("startIndex: " + parseResult.startIndex); // 14
trace("Status:" + nf.lastOperationStatus); // noError

parse() メソッドは、解析された数値を値プロパティに含む NumberParseResult オブジェクトを返します。startIndex プ
ロパティは、見つかった最初の数字のインデックスを示します。startIndex プロパティおよび endIndex プロパティを使用
すると、数字の前および後の文字列部分を抽出できます。

通貨の値の形式の設定
Flash Player 10.1 以降、Adobe AIR 2.0 以降
通貨の値の表示形式は、数字と同じように大きく異なります。例えば、米ドルの値 $123456.78 の形式を特定のロケールで設定すると、次のようになります。
ロケール

数値形式

en-US（英語、米国）$123,456.78

de-DE（ドイツ語、ドイツ）

123.456,78 $en-IN（英語、インド）$ 1,23,456.78

通貨の形式では、数値の形式と同じすべての要素に加えて、次の要素が関連します。

•

通貨の ISO コード。使用されている実際のロケールに対する 3 文字の ISO 4217 通貨コード（USD、EUR など）。

•

通貨記号。使用される実際のロケールの通貨記号または文字列（$、€ など）。

•

マイナスの通貨形式。通貨額の数値部分に関連する通貨記号とマイナス記号または括弧の位置を定義します。

•

プラスの通貨形式。通貨額の数値部分に関連する通貨記号の位置を定義します。

CurrencyFormatter クラスの使用
CurrencyFormatter クラスは、特定のロケールの表記規則に従って、数値の形式を、通貨文字列と形式が設定された数字を含む文字列に設定します。
新しい CurrencyFormatter オブジェクトをインスタンス化すると、このオブジェクトにより、通貨は特定のロケールのデ
フォルトの通貨に設定されます。
次の例では、ドイツ語ロケールを使用して作成された CurrencyFormatter オブジェクトにより、通貨額がユーロであると見なされています。
var cf:CurrencyFormatter = new CurrencyFormatter( "de-DE" );trace(cf.format(1234567.89)); // 1.234.567,89 EUR

ほとんどの場合、ロケールのデフォルトの通貨に依存しないでください。ユーザーのデフォルトのロケールがサポートされていない場合、CurrencyFormatter クラスは代替ロケールを割り当てます。代替ロケールには、異なるデフォルトの通貨を設定できます。さらに、額がユーザーの地域の通貨でない場合であっても、通貨形式がユーザーに対して正しく表示されるようにしたいと考えるのが通常です。例えば、カナダのユーザーは、ドイツの企業の価格をユーロで表示するが、カナダのスタイルで形式が設定されることを望みます。

CurrencyFormatter.setCurrency() メソッドは、正確な通貨文字列と使用する通貨記号を指定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

912

アプリケーションの国際化

次の例では、カナダのフランス語圏のユーザーに対して、通貨をユーロで表示します。
var cf:CurrencyFormatter = new CurrencyFormatter( "fr-CA" );cf.setCurrency("EUR", "€");
trace(cf.format(1234567.89)); // 1.234.567,89 EUR

setCurrency() メソッドを使用すると、一義的な通貨記号を設定して混乱を避けることもできます。次に、例を示します。
cf.setCurrency("USD","US$");

デフォルトでは、format() メソッドは、通貨記号の代わりに 3 文字の ISO 4217 通貨コードを表示します。ISO 4217 コー
ドは一義的で、ローカリゼーションの必要はありません。ただし、多くのユーザーは、ISO コードではなく通貨記号を表示することを望みます。

CurrencyFormatter クラスは、形式を設定された通貨文字列で通貨記号（ドル記号、ユーロ記号など）または 3 文字のISO 通貨文字列（USD、EUR など）のどちらを使用するかを決定するうえで役立ちます。例えば、カナダドルの金額を、
カナダのユーザーには $200 と表示できます。一方、米国のユーザーには CAD 200 と表示できます。ユーザーのロケール設
定を基にして、額の通貨記号をあいまいまたは不正確にするかどうかを決定するには、

formattingWithCurrencySymbolIsSafe() メソッドを使用します。
次の例では、ユーロの値を en-US ロケールの形式に設定します。ユーザーのロケールに応じて、出力文字列は ISO 通貨
コードまたは通貨記号を使用します。
var cf:CurrencyFormatter = new CurrencyFormatter( "en-CA");if (cf.formattingWithCurrencySymbolIsSafe("USD")){
trace(cf.format(1234567.89, true)); // $1,234,567.89}
else{
cf.setCurrency("USD", "$");
trace(cf.format(1234567.89)); // USD1,234,567.89}

通貨値を含む文字列の解析
CurrencyFormatter クラスは、入力文字列から、ロケールに固有の形式の設定要件に適合する通貨額と通貨文字列を抽出することもできます。CurrencyFormatter.parse() メソッドは、次に示すように、解析された額および通貨文字列をCurrencyParseResult オブジェクトに格納します。
var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" );var inputCurrencyString:String = "(GBP 123,56,7.890)";
var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString);
trace("parsed amount: " + parseResult.value); // -1234567.89
trace("currencyString: " + parseResult.currencyString ); // GBP

入力文字列の通貨文字列部分には、通貨記号、通貨の ISO コード、追加のテキスト文字が含まれます。通貨文字列、マイナ
ス記号、数値の位置は、negativeCurrencyFormat プロパティおよび positiveCurrencyFormat プロパティで指定された形式に一致します。次に、例を示します。
var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" );var inputCurrencyString:String = "Total $-123,56,7.890";
var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString);
trace("status: " + cf.lastOperationStatus ); // parseError
trace("parsed amount: " + parseResult.value); // NaN
trace("currencyString: " + parseResult.currencyString ); //cf.negativeCurrencyFormat = 2;
parseResult = cf.parse(inputCurrencyString);
trace("status: " + cf.lastOperationStatus ); // noError
trace("parsed amount: " + parseResult.value); // -123567.89
trace("currencyString: " + parseResult.currencyString ); // Total $最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

913

アプリケーションの国際化

この例では、入力文字列には通貨文字列に続いてマイナス記号と数字があります。ただし、en-US ロケール用のデフォルトの negativeCurrencyFormat 値では、先頭にマイナス記号が挿入されることが指定されます。その結果、parse() メソッド
はエラーを生成し、解析値は NaN になります。

negativeCurrencyFormat を 2 に設定すると（通貨文字列が最初にくることを指定します）、parse() メソッドは成功します。

日付と時刻の形式の設定
Flash Player 10.1 以降、Adobe AIR 2.0 以降
日付と時刻の値の表示形式は、地域によって大きく異なります。例えば、1962 年 1 月 2 日 1:01 PM は、特定のスケールの短い形式では次のように表示されます。
ロケール

日付と時刻の形式

en-US（英語、米国）

1/2/62 1:01pm

fr-FR（フランス、フランス語）

2/1/62 13:01

ja-JP（日本、日本語）

1962/2/1 13:01

DateTimeFormatter クラスの使用
DateTimeFormatter クラスは、特定のロケールの表記規則に従って、Date 値の形式を日付と時刻の文字列に設定します。
この設定は、日付および地域の値に置き換える文字のシーケンスを含むパターン文字列に従います。例えば、「yyyy/MM」というパターンでは、「yyyy」という文字列が 4 桁の年に置き換えられ、その後に「/」および 2 桁の月が続きます。
このパターン文字列は、setDateTimePattern() メソッドを使用して明示的に設定できます。ただし、パターンの設定は、ユーザーのロケールとオペレーティングシステムの設定に応じて自動的に行うことをお勧めします。この方法を使用すると、文化的に適切な結果が確実に得られます。

DateTimeFormatter は 3 つの標準スタイル（LONG、MEDIUM、SHORT）で日付と時刻を表すことができ、
CUSTOM パターンを使用することもできます。1 つのスタイルを日付に使用し、2 つ目のスタイルを時刻に使用できます。
各スタイルに使用する実際のパターンは、オペレーティングシステムによっていくらか異なります。
スタイルは、DateTimeFormatter オブジェクトを作成するときに指定できます。スタイルパラメーターを指定しない場合、
デフォルトで DateTimeStyle.LONG に設定されます。次の例に示すように、後で setDateTimeStyles() メソッドを使用してスタイルを変更できます。
var date:Date = new Date(2009, 2, 27, 13, 1);
var dtf:DateTimeFormatter = new DateTimeFormatter("en-US",
DateTimeStyle.LONG, DateTimeStyle.LONG);
var longDate:String = dtf.format(date);
trace(longDate); // March 27, 2009 1:01:00 PM
dtf.setDateTimeStyles(DateTimeStyle.SHORT, DateTimeStyle.SHORT);
var shortDate:String = dtf.format(date);
trace(shortDate); // 3/27/09 1:01 PM

月の名前および曜日のローカライズ
多くのアプリケーションでは、月の名前と曜日をカレンダー表示やプルダウンリストに表示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

914

アプリケーションの国際化

ローカライズした月の名前のリストは、DateTimeFormatter.getMonthNames() メソッドを使用して取得できます。オペ
レーティングシステムに応じて、完全な形式と省略形式を利用できます。値 DateTimeNameStyle.FULL を渡すと、完全な月の名前を取得できます。値 DateTimeNameStyle.LONG_ABBREVIATION または
DateTimeNameStyle.SHORT_ABBREVIATION を渡すと、短い月の名前を取得できます。
一部の言語では、日付形式の日の値の横に配置されていると、月の名前が属格形式に変化します。月の名前を単独で使用する計画の場合は、値 DateTimeNameContext.STANDALONE を getMonthNames() メソッドに渡します。ただし、形式が設定された日付で月の名前を使用する場合は、値 DateTimeNameContext.FORMAT を渡します。
var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR");var months:Vector.<String> = dtf.getMonthNames(DateTimeNameStyle.FULL,
DateTimeNameContext.STANDALONE);
trace(months[0]); // janvier
months = dtf.getMonthNames(DateTimeNameStyle.SHORT_ABBREVIATION,
DateTimeNameContext.STANDALONE);
trace(months[0]); // janv.

DateTimeFormatter.getWeekdayNames() メソッドは曜日のローカライズされたリストを提供します。
getWeekdayNames() メソッドは、getMonthNames() メソッドが受け取るのと同じ nameStyle およびコンテキストパラ
メーターを受け取ります。
var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR");var weekdays:Vector.<String> = dtf.getWeekdayNames(DateTimeNameStyle.FULL,
DateTimeNameContext.STANDALONE);
trace(weekdays[0]); // dimanche
weekdays = dtf.getWeekdayNames(DateTimeNameStyle.LONG_ABBREVIATION,
DateTimeNameContext.STANDALONE);
trace(weekdays[0]); // dim.

さらに、getFirstWeekday() メソッドは、選択されたロケールにおいて慣習となっている週の最初の日のインデックス値を返します。

文字列の並べ替えと比較
Flash Player 10.1 以降、Adobe AIR 2.0 以降
照合は、正しい順序で物事を配置するプロセスです。照合ルールはロケールによって大きく異なります。また、リストを並べ替える場合や、テキスト検索アルゴリズムなどで類似する項目を照合する場合も異なります。
並べ替えの際は、大文字と小文字の違い、アクセントなどの付加記号がしばしば重要になります。例えば、文字 ö（分音符
号付きの o）は、フランス語や英語の文字 o とほぼ同じものとみなされます。ただし、この文字はスウェーデン語の文字 zの後に続きます。また、フランス語やその他の一部の言語では、単語の最後のアクセントの違いが、並べ替えリストでの順番に影響します。
検索を実行する場合、関連性の高い項目を検索するために、大文字小文字や分音記号はしばしば無視します。例えば、フランス語のドキュメントで文字「cote」を検索すると、「cote」、「côte」、「coté」などの結果が返される可能性があります。

Collator クラスの使用
Collator クラスの主要なメソッドは、主に並べ替えに使用される compare() メソッドと、値の一致に使用される equals()
メソッドです。
次の例は、compare() メソッドと equals() メソッドの異なるビヘイビアーを示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

915

アプリケーションの国際化

var words:Array = new

Array("coté", "côte");var sorter:Collator = new Collator("fr-FR", CollatorMode.SORTING);
words.sort(sorter.compare);trace(words); // côte,coté
var matcher:Collator = new Collator("fr-FR", CollatorMode.MATCHING);
if (matcher.equals(words[0], words[1])){trace(words[0] + " = " + words[1]); // côte = coté}

この例では、フランス語 - フランスロケール用に SORTING モードで Collator オブジェクトを最初に作成します。次に、分音記号のみが異なる 2 つの単語を並べ替えます。この例では、SORTING 比較において、アクセント記号のある文字とない文字が区別されます。
並べ替えは、Collator オブジェクトの sort() メソッドに、Array.sort() メソッドのパラメーターとして参照を渡すことで実行されます。これは、Collator オブジェクトを使用して並べ替え順序を制御するための最も効率的な方法の 1 つです。
この例では、次に MATCHING モードで Collator オブジェクトを作成します。その Collator オブジェクトが 2 つの単語を比較するときに、それらを同じものとして処理します。これは、MATCHING 比較では、アクセント記号のある文字とない文字が同じように扱われることを示します。

Collator クラスのビヘイビアーのカスタマイズ
デフォルトでは、Collator クラスは、ロケールとユーザーのシステム環境設定に基づいてオペレーティングシステムから取得した文字列比較ルールを使用します。様々なプロパティを明示的に設定することで、compare() メソッドおよび equals()
メソッドのビヘイビアーをカスタマイズできます。次の表は、プロパティと、比較におけるその影響を示しています。
Collator プロパティ

エフェクト

numericComparison

数字を数値として扱うか、テキストとして扱うかを制御します。

ignoreCase

大文字と小文字を区別するかどうかを制御します。

ignoreCharacterWidth

中国語と日本語の一部の文字の全角形式と半角形式を同じものとして評価するかどうかを制御します。

ignoreDiacritics

同じベース文字を使用しているが、異なるアクセント記号や分音記号を使用している文字列を、同じものとして評価するかどうかを制御します。

ignoreKanaType

使用されているかな文字のタイプのみが異なる文字列を、同じものとして処理するかどうかを制御します。

ignoreSymbols

スペース、通貨文字、数学記号などの記号文字を無視するかどうかを制御します。

次のコードは、ignoreDiacritics プロパティを true に設定すると、フランス語の単語のリストの並べ替え順序が変わることを示しています。
var words:Array = new Array("COTE", "coté", "côte", "Coté","cote");var sorter:Collator = new Collator("fr-CA", CollatorMode.SORTING);
words.sort(sorter.compare);trace(words); // cote,COTE,côte,coté,Cotésorter.ignoreDiacritics = true;words.sort(sorter.compare);trace(words); // côte,coté,cote,Coté,COTE

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

916

アプリケーションの国際化

大文字と小文字の変換
Flash Player 10.1 以降、Adobe AIR 2.0 以降
言語によって、大文字形式（大文字体）と小文字形式（小文字体）の間の変換ルールも異なります。
例えば、ラテン系のアルファベットを使用するほとんどの言語では、大文字「I」の小文字は「i」です。ただし、トルコ語、
アゼリー語など一部の言語では、これに加えて点のない文字「ı」もあります。このような言語の場合、結果として、点のな
い小文字「ı」は大文字「I」に変換されます。小文字「i」は、点を持つ大文字「İ」に変換されます。

StringTools クラスには、言語固有のルールを使用してこのような変換を実行するメソッドが用意されています。

StringTools クラスの使用
StringTools クラスには、toLowerCase() および toUpperCase() という、大文字と小文字の変換を実行する 2 つのメソッドが用意されています。StringTools オブジェクトを作成するには、ロケール ID を使用してコンストラクターを呼び出します。StringTools クラスは、オペレーティングシステムから、そのロケール（または代替ロケール）の大文字と小文字の変換ルール）を取得します。大文字と小文字の変換アルゴリズムをさらにカスタマイズすることはできません。
次の例では、toUpperCase() メソッドおよび toLowerCase() メソッドを使用して、文字「ß」（鋭い S）を含むドイツ語の語句を変換します。
var phrase:String = "Schloß Neuschwanstein";var converter:StringTools = new StringTools("de-DE");var upperPhrase:String = converter.toUpperCase(phrase);
trace(upperPhrase); // SCHLOSS NEUSCHWANSTEIN
var lowerPhrase:String = converter.toLowerCase(upperPhrase);
trace(lowerPhrase);// schloss neuschwansteintoUpperCase() メソッドは、小文字「ß」を大文字「SS」に変換します。この変換は一方向にのみ行われます。文字「SS」
が小文字に戻されるときは、結果は「ß」ではなく「ss」になります。

例：相場表示アプリケーションの国際化
Flash Player 10.1 以降、Adobe AIR 2.0 以降
Global Stock Ticker アプリケーションは、米国、日本、欧州という 3 つの異なる株式市場の株式に関する架空のデータを取得して表示します。このアプリケーションは、様々なロケールの規則に応じてデータの形式を設定します。
この例は、flash.globalization パッケージの次の機能を示しています。

•

ロケールに対応した数値形式の設定•

ロケールに対応した通貨形式の設定•

通貨の ISO コードおよび通貨記号の設定•

ロケールに対応した日付形式の設定•

月の名前の適切な略語の取得と表示

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

917

アプリケーションの国際化

このサンプルのアプリケーションのファイルを入手するには、

www.adobe.com/go/learn_programmingAS3samples_flash_jp を参照してください。Global Stock Ticker アプリケー
ションファイルは、Samples/GlobalStockTicker フォルダーにあります。このアプリケーションは次のファイルで構成されています。
ファイル

説明

GlobalStockTicker.mx
ml

アプリケーションのユーザーインターフェイスです（Flex 用の MXML、または Flash 用の FLA）。

または

GlobalStockTicker.fla
styles.css

アプリケーションユーザーインターフェイスのスタイルです（Flex 専用）。

com/example/progra
mmingas3/stockticker/flex/FinGraph.mxml

シミュレーションされた株式データのチャートを表示する MXML コンポーネントです（Flex 専用）。

com/example/progra アプリケーション用のユーザーインターフェイスロジックを含んだドキュメントクラスです（Flash 専用）。
mmingas3/stockticker/flash/GlobalStockTicker.as
comp/example/progra Flash DataGrid コンポーネントのカスタムセルレンダラーです（Flash 専用）。
mmingas3/stockticker/flash/RightAlignedCol
umn.ascom/example/progra
mmingas3/stockticker/FinancialGraph.as

シミュレーションされた株式データのチャートを描画する ActionScript クラスです。

com/example/progra
mmingas3/stockticker/Localizer.as

ロケールおよび通貨を管理し、数字、通貨額、日付のローカライズされた形式を処理する ActionScript クラスです。

com/example/progra
mmingas3/stockticker/StockDataModel.as

Global Stock Ticker の例のすべてのサンプルデータを保持する ActionScript クラスです。

ユーザーインターフェイスとサンプルデータについて
アプリケーションのメインユーザーインターフェイスの要素は次のとおりです。

•

ロケールを選択するコンボボックス•

市場を選択するコンボボックス•

各市場の 6 つの企業のデータを表示する DataGrid•

選択された企業の株式のシュミレーションされた履歴データを表示するチャート

このアプリケーションは、ロケール、市場、企業の株式に関するすべてのサンプルデータを StockDataModel クラスに格納します。本物のアプリケーションでは、サーバーからデータを取得し、そのデータを StockDataModel などのクラスに格納します。この例では、すべてのデータが StockDataModel クラスにハードコーディングされています。
注意：財務チャートに表示されるデータは、DataGrid コントロールに表示されるデータと一致するとは限りません。このチャートは、別の企業が選択されるたびにランダムに再描画されます。これは機能を示すことのみを目的としています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

918

アプリケーションの国際化

ロケールの設定
アプリケーションは、初期的な設定作業の後に、Localizer.setLocale() メソッドを呼び出して、デフォルトロケールのフォーマッターオブジェクトを作成します。また、setLocale() メソッドは、ユーザーが「Locale」コンボボックスから新
しい値を選択するたびに呼び出されます。
public function setLocale(newLocale:String):void{locale = new LocaleID(newLocale);nf = new NumberFormatter(locale.name);
traceError(nf.lastOperationStatus, "NumberFormatter", nf.actualLocaleIDName);
cf = new CurrencyFormatter(locale.name);
traceError(cf.lastOperationStatus, "CurrencyFormatter", cf.actualLocaleIDName);symbolIsSafe = cf.formattingWithCurrencySymbolIsSafe(currentCurrency);
cf.setCurrency(currentCurrency, currentSymbol);cf.fractionalDigits = currentFraction;
df = new DateTimeFormatter(locale.name, DateTimeStyle.LONG, DateTimeStyle.SHORT);
traceError(df.lastOperationStatus, "DateTimeFormatter", df.actualLocaleIDName);monthNames = df.getMonthNames(DateTimeNameStyle.LONG_ABBREVIATION);}
public function traceError(status:String, serviceName:String, localeID:String) :void{if(status != LastOperationStatus.NO_ERROR){
if(status == LastOperationStatus.USING_FALLBACK_WARNING){
trace("Warning - Fallback locale ID used by "+ serviceName + ": " + localeID);}
else if (status == LastOperationStatus.UNSUPPORTED_ERROR){
trace("Error in " + serviceName + ": " + status);//abort application
throw(new Error("Fatal error", 0));}else{
trace("Error in " + serviceName + ": " + status);
}
}
else
{
trace(serviceName + " created for locale ID: " + localeID);}}

最初に、setLocale() メソッドは LocaleID オブジェクトを作成します。このオブジェクトにより、必要に応じて、後で実際のロケールに関する詳細を取得するのが簡単になります。
次に、このメソッドはロケール用の新しい NumberFormatter、CurrencyFormatter、DateTimeFormatter の各オブジェクトを作成します。各フォーマッターオブジェクトを作成した後、traceError() メソッドを呼び出します。このメソッ
ドは、要求されたロケールに問題があると、コンソールにエラーおよび警告メッセージを表示します（本物のアプリケー
ションでは、問題をトレースするだけではなく、このようなエラーに基づいて対応する必要があります）。

CurrencyFormatter オブジェクトの作成後、setLocale() メソッドはフォーマッターの通貨 ISO コード、通貨記号、
fractionalDigits のプロパティを、それまでに決定された値に設定します（これらの値は、ユーザーが「Markets」コンボ
ボックスから新しい市場を選択するたびに設定されます）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

919

アプリケーションの国際化

setLocale() メソッドは、DateTimeFormatter オブジェクトを作成した後に、ローカライズされた月の名前の略語の配列を取得します。

データの形式の設定
形式を設定された株式データは DataGrid コントロールに表示されます。DataGrid 列は、それぞれ、適切なフォーマッ
ターオブジェクトを使用して列の値の形式を設定するラベル関数を呼び出します。
例えば、Flash バージョンでは、次のコードは DataGrid 列を設定します。
var col1:DataGridColumn = new DataGridColumn("ticker");
col1.headerText = "Company";col1.sortOptions = Array.NUMERIC;
col1.width = 200;
var col2:DataGridColumn = new DataGridColumn("volume");col2.headerText = "Volume";
col2.width = 120;
col2.cellRenderer = RightAlignedCell;
col2.labelFunction = displayVolume;var col3:DataGridColumn = new DataGridColumn("price");col3.headerText = "Price";col3.width = 70;
col3.cellRenderer = RightAlignedCell;
col3.labelFunction = displayPrice;
var col4:DataGridColumn = new DataGridColumn("change");col4.headerText = "Change";col4.width = 120;
col4.cellRenderer = RightAlignedCell;
col4.labelFunction = displayPercent;

例の Flex バージョンは、MXML で DataGrid を宣言します。また、各列用に類似したラベル関数を定義します。

labelFunction プロパティは次の関数を参照します。これらの関数は、Localizer クラスの形式の設定メソッドを呼び出します。
private function displayVolume(item:Object):String{
return localizer.formatNumber(item.volume, 0);}private function displayPercent(item:Object):String{
return localizer.formatPercent(item.change ) ;}private function displayPrice(item:Object):String{
return localizer.formatCurrency(item.price);}

次に、Localizer メソッドは、適切なフォーマッターを設定して呼び出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

920

アプリケーションの国際化

public function formatNumber(value:Number, fractionalDigits:int = 2):String{
nf.fractionalDigits = fractionalDigits;
return nf.formatNumber(value);}
public function formatPercent(value:Number, fractionalDigits:int = 2):String{// HACK WARNING: The position of the percent sign, and whether a space belongs// between it and the number, are locale-sensitive decisions. For example,// in Turkish the positive format is %12 and the negative format is -%12.
// Like most operating systems, flash.globalization classes do not currently// provide an API for percentage formatting.
nf.fractionalDigits = fractionalDigits;
return nf.formatNumber(value) + "%";}
public function formatCurrency(value:Number):String{
return cf.format(value, symbolIsSafe);}
public function formatDate(dateValue:Date):String{
return df.format(dateValue);}|

最終更新日 2015/10/14

921

第 57 章：アプリケーションのローカライズ
Flash Player 9 以降、Adobe AIR 1.0 以降
ローカリゼーションは、複数のロケールをサポートするアセットを含む処理です。ロケールは、言語と国コードの組み合わせです。例えば、en_US は米国で話されている英語を指し、fr_FR はフランスで話されているフランス語を指します。これらのロケールのアプリケーションをローカライズするには、2 セットのアセットを指定します。1 つは en_US ロケール用でもう 1 つは fr_FR ロケール用のものです。
ロケールでは言語を共有できます。例えば、en_US と en_GB（英国）は異なるロケールです。この場合は両方のロケール
で英語を使用していますが、国コードでは両方のロケールが別のロケールであることが示されているので、別のアセットを使用している可能性があります。例えば、アプリケーションは en_US ロケールでは「color」という単語の綴りを使用しますが、en_GB ロケールでは単語の綴りは「colour」になります。また、通貨単位はロケールに応じてドルまたはポンドで表され、日付と時刻の形式も異なっている可能性があります。
国コードを指定せずに、言語アセットのセットを提供することもできます。例えば、英語用に en アセットを提供し、米国
英語に固有の en_US ロケール用に追加アセットを提供できます。
ローカリゼーションは、単にアプリケーションで使用されているストリングを翻訳することではありません。これには、オーディオファイル、イメージ、ビデオなどの各種のアセットが含まれることもあります。

ロケールの選択Flash Player 9 以降、Adobe AIR 1.0 以降
コンテンツまたはアプリケーションが使用するロケールを決定するには、次のいずれかの方法を使用します。

• flash.globalization パッケージ - flash.globalization パッケージ内にあるロケール対応のクラスを使用し、オペレーティ
ングシステムとユーザー設定に基づいて、ユーザーのデフォルトのロケールを取得します。これは、Flash Player 10.1
以降または AIR 2.0 以降のランタイム上で実行するアプリケーションに推奨される方法です。詳しくは、907 ページの「ロケールの特定」を参照してください。

•

ユーザープロンプト — アプリケーションをいずれかのデフォルトロケールで起動してから、ユーザーに必要なロケールを選択するように要求できます。

• （AIR のみ）Capabilities.languages — Capabilities.languages プロパティは、オペレーティングシステムで設定されている、ユーザーが優先する言語で使用可能な言語の配列を一覧表示します。このストリングには、RFC4646（http://www.ietf.org/rfc/rfc4646.txt）で定義されている言語タグ（および該当する場合は、スクリプトおよび地域情報）が含まれます。このストリングではハイフンが区切り文字として使用されます（"en-US"、"ja-JP" など）。返された配列の最初のエントリは、language プロパティと同じプライマリ言語 ID です。例えば、languages[0] が "en-US" に設定されている場合、language プロパティは "en" に設定されています。 ただし、language プロパティが "xu"（不明な用語を指定する）に設定されている場合は、languages 配列の最初のエレメントは異なります。

• Capabilities.language - Capabilities.language プロパティは、オペレーティングシステムのユーザーインターフェイスの言語
コードを示します。ただし、このプロパティは 20 個の既知の言語に制限されています。英語のシステムでは、このプロ
パティは言語コードのみを返し、国コードは返しません。このような理由から、Capabilities.languages 配列の最初のエレメントを使用することをお勧めします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

922

アプリケーションのローカライズ

Flex コンテンツのローカライズ
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe Flex には、Flex コンテンツをローカライズするためのフレームワークが含まれています。このフレームワークには、
Locale、ResourceBundle、ResourceManagerImpl の各クラスと、IResourceBundle、IResourceManagerImpl の各イ
ンターフェイスが含まれています。
アプリケーションのロケールを並べ替えるユーティリティクラスを含む Flex ローカリゼーションライブラリが Google

Code（http://code.google.com/p/as3localelib/）に公開されています。
関連項目

http://code.google.com/p/as3localelib/

Flash コンテンツのローカライズ
Flash Player 9 以降、Adobe AIR 1.0 以降
Adobe Flash Professional には、ActionScript 3.0 コンポーネントの Locale クラスが含まれています。Locale クラスを使用すると、SWF ファイルでの多言語テキストの表示方法を指定できます。Flash のストリングパネルでは、ダイナミックテ
キストフィールドでストリングリテラルの代わりにストリング ID を使用できます。この機能により、言語別の XML ファイ
ルからテキストを読み込んで表示する SWF ファイルを作成できます。Locale クラスの使用について詳しくは、「Adobe
Flash Platform 用 ActionScript 3.0 リファレンスガイド」を参照してください。

AIR アプリケーションのローカライズ
Adobe AIR 1.0 およびそれ以降
AIR SDK には、HTML ローカリゼーションフレームワーク（AIRLocalizer.js ファイルに含まれる）が用意されています。
このフレームワークには、HTML ベースのアプリケーションで複数のロケールを操作するのに役立つ API が含まれています。ロケールを並べ替える ActionScript ライブラリが http://code.google.com/p/as3localelib/ に公開されています。
関連項目

http://code.google.com/p/as3localelib/

日付、時刻および通貨のローカライズ
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションが日付、時刻および通貨を表示する方法は各ロケールで大きく異なります。例えば、日付表示に関する米国標準が month/day/year であるのに対してヨーロッパ標準では day/month/year になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

923

アプリケーションのローカライズ

日付、時刻および通貨の形式を指定するコードを作成できます。例えば、次のコードは Date オブジェクトを

month/day/year 形式または day/month/year 形式に変換します。locale 変数（ロケールを表す）が "en_US" に設定されている場合、この関数は month/day/year 形式を返します。この例は、他のすべてのロケールについては、Date オブジェク
トを day/month/year 形式に変換します。
function convertDate(date){if (locale == "en_US"){
return (date.getMonth() + 1) + "/" + date.getDate() + "/" + date.getFullYear();}else{
return date.getDate() + "/" + (date.getMonth() + 1) + "/" + date.getFullYear();}}ADOBE FLEX
Flex フレームワークには、日付、時刻および通貨の形式を設定するためのコントロールが含まれています。これには、
DateFormatter コントロールや CurrencyFormatter コントロールが含まれています。

• mx:DateFormatter• mx:CurrencyFormatter

最終更新日 2015/10/14

924

第 58 章：HTML 環境について
Adobe AIR 1.0 およびそれ以降
Adobe®AIR® では、Safari Web ブラウザーでも使用される WebKit（www.webkit.org）を使用して、HTML および
JavaScript のコンテンツの解析、配置およびレンダリングを行います。HTML コンテンツでの AIR API の使用はオプションです。HTMLLoader オブジェクトまたは HTML ウィンドウのコンテンツ全体で、HTML および JavaScript を使用してプログラミングできます。既存の HTML ページおよびアプリケーションの多くは、ほとんど変更することなく実行できます（WebKit との互換性がある HTML、CSS、DOM および JavaScript の機能を使用している場合）。
重要：Adobe AIR ランタイムの新しいバージョンには、WebKit の更新されたバージョンが含まれている場合があります。
新しいバージョンの AIR に含まれる WebKit の更新により、デプロイされた AIR アプリケーションに予期しない変更が生じる可能性があります。そのような変更は、アプリケーションの HTML コンテンツの動作や外観に影響を与える場合があります。例えば、WebKit のレンダリングの改善または修正によって、アプリケーションのユーザーインターフェイスの要
素のレイアウトが変化する場合があります。そのため、アプリケーションには更新メカニズムを用意することを強くお勧めします。AIR に含まれる WebKit のバージョンに加えられた変更により、アプリケーションを更新する必要がある場合は、

AIR の更新メカニズムによって、アプリケーションの新しいバージョンをインストールするかどうかを確認するメッセージが表示されます。
次の表に、AIR で使用されている WebKit と同等のバージョンを使用する Safari Web ブラウザーのバージョンを示します。
AIR バージョン
1.0
1.1
1.5
2.0
2.5
2.6
2.7
3

Safari バージョン
2.04
3.04
4.0 Beta
4.03
4.03
4.03
4.03
5.0.3

インストールされている WebKit のバージョンは、HTMLLoader オブジェクトによって返されるデフォルトのユーザー
エージェント文字列を調べることにより、いつでも確認できます。
var htmlLoader:HTMLLoader = new HTMLLoader();
trace( htmlLoader.userAgent );AIR で使用されている WebKit のバージョンは、オープンソースバージョンと同じであるとは限りません。一部の機能はAIR でサポートされていません。また、AIR バージョンには、対応する WebKit バージョンではまだ利用できないセキュリ
ティ修正やバグ修正が含まれていることがあります。939 ページの「AIR でサポートされていない WebKit の機能」を参照
してください。

AIR アプリケーションはファイルシステムへのフルアクセスを使用してデスクトップで直接実行されるので、HTML コン
テンツのセキュリティモデルは、一般的な Web ブラウザーのセキュリティモデルより厳格です。AIR では、アプリケー
ションのインストールディレクトリから読み込まれたコンテンツのみ、アプリケーションサンドボックスに配置されます。
アプリケーションサンドボックスには最高レベルの権限が設定されており、このサンドボックスから AIR API にアクセスできます。AIR では、その他のコンテンツは、そのコンテンツの生成元に基づいて個別のサンドボックスに配置されます。
ファイルシステムから読み込まれたファイルは、ローカルサンドボックスに含められます。http: プロトコルまたは https: プ
ロトコルを使用してネットワークから読み込まれたファイルは、リモートサーバーのドメインに基づいてサンドボックスに含められます。これらの非アプリケーションサンドボックス内のコンテンツは、AIR API へのアクセスが禁止され、一般的な Web ブラウザーでの場合とほぼ同様に実行されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

925

HTML 環境について

AIR の HTML コンテンツでは、アルファ、拡大／縮小または透明度の設定が適用されている場合、SWF コンテンツやPDF コンテンツは表示されません。詳しくは、968 ページの「HTML ページに SWF コンテンツまたは PDF コンテンツを読み込む場合の考慮事項」および 859 ページの「ウィンドウの透明度」を参照してください。
関連項目

Webkit DOM リファレンス
Safari HTML リファレンス
Safari CSS リファレンス
www.webkit.org

HTML 環境の概要
Adobe AIR 1.0 およびそれ以降
Adobe AIR では、HTML レンダラー、ドキュメントオブジェクトモデルおよび JavaScript インタプリタを備えた、完全なブラウザー形式の JavaScript 環境を提供します。この JavaScript 環境を表すのが、AIR の HTMLLoader クラスです。
HTML ウィンドウでは、HTMLLoader オブジェクトはすべての HTML コンテンツを格納し、そのオブジェクト自体がNativeWindow オブジェクト内に格納されます。SWF コンテンツでは、Sprite クラスを拡張する HTMLLoader クラス
は、他の表示オブジェクトと同様にステージの表示リストに追加できます。このクラスの Adobe® ActionScript® 3.0 プロパ
ティについては、966 ページの「AIR HTML コンテナのスクリプト作成」および『Adobe Flash Platform 用
ActionScript 3.0 リファレンスガイド』で説明されています。Flex フレームワークでは、AIR の HTMLLoader クラスを
mx:HTML コンポーネントでラップします。mx:HTML コンポーネントは、UIComponent クラスを拡張するので、他のFlex コンテナで直接使用できます。mx:HTML コンポーネント内での JavaScript 環境は、それ以外の点は同一です。

JavaScript 環境および AIR ホストとの関係について
Adobe AIR 1.0 およびそれ以降
次の図に、JavaScript 環境と AIR ランタイム環境の関係を示します。1 つのネイティブウィンドウしか示されていません
が、AIR アプリケーションには複数のウィンドウを含めることができます（また、1 つのウィンドウに複数のHTMLLoader オブジェクトを含めることができます）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

926

HTML 環境について

AIR ランタイム環境

NativeWindow

HTMLLoader
window
JavaScript
環境
window

document

body

head

htmlLoader

nativeWindow

runtime
h1

div

table

p

JavaScript 環境には、独自の Document オブジェクトと Window オブジェクトがあります。JavaScript コードでは、runtime、nativeWindow、
htmlLoader の各プロパティを使用して、AIR ランタイム環境を操作できます。ActionScript コードでは、JavaScript の Window オブジェクトを参照
する、HTMLLoader オブジェクトの window プロパティを使用して、JavaScript 環境を操作できます。また、ActionScript オブジェクトとJavaScript オブジェクトの両方で、AIR オブジェクトと JavaScript オブジェクトから送出されたイベントをリッスンできます。

runtime プロパティは AIR API クラスへのアクセスを提供します。このプロパティを使用すると、クラスメンバー（静的メンバー）にアクセスできるだけでなく、新しい AIR オブジェクトを作成することもできます。AIR API にアクセスするには、package を使用して、クラスの名前を runtime プロパティに追加します。例えば、File オブジェクトを作成するには、次のステートメントを使用します。
var file = new window.runtime.filesystem.File();

注意：AIR SDK には、AIRAliases.js という JavaScript ファイルが付属しており、このファイルでは、最もよく使用される

AIR クラスの便利なエイリアスが定義されています。このファイルを読み込むと、window.runtime.package.Class の代わりに、短い形式の air.Class を使用できます。例えば、new air.File() を使用して File オブジェクトを作成することもできます。

NativeWindow オブジェクトには、デスクトップウィンドウを制御するためのプロパティが用意されています。HTMLページ内から、window.nativeWindow プロパティを使用して、コンテナとなっている NativeWindow オブジェクトにアクセスできます。

HTMLLoader オブジェクトには、コンテンツを読み込んでレンダリングする方法を制御するためのプロパティ、メソッド
およびイベントが用意されています。HTML ページ内から、window.htmlLoader プロパティを使用して、親 HTMLLoader
オブジェクトにアクセスできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

927

HTML 環境について

重要：htmlLoader、nativeWindow、runtime の各プロパティを使用できるのは、アプリケーションの一部としてインストー
ルされたページのみで、トップレベルドキュメントとして読み込まれた場合だけです。これらのプロパティは、ドキュメン
トがフレームまたはインラインフレームに読み込まれた場合には追加されません（子ドキュメントは、同じセキュリティサ
ンドボックスにある限り、親ドキュメントのこれらのプロパティにアクセスできます。例えば、フレームに読み込まれたドキュメントでは、parent.runtime を使用して、その親の runtime プロパティにアクセスできます）。

セキュリティについて
Adobe AIR 1.0 およびそれ以降
AIR では、すべてのコードは、元のドメインに基づいてセキュリティサンドボックス内で実行されます。アプリケーション
コンテンツ（アプリケーションのインストールディレクトリから読み込まれたコンテンツに限定）は、アプリケーションサ
ンドボックスに配置されます。ランタイム環境および AIR API へのアクセスは、このサンドボックス内で実行されるHTML および JavaScript からのみ可能です。その際、ページの load イベントのすべてのハンドラーから処理が戻った後、JavaScript の動的な評価と実行の多くはアプリケーションサンドボックス内でブロックされます。
アプリケーションページを非アプリケーションサンドボックスにマップするには、ページをフレームまたはインラインフ
レームに読み込み、そのフレームの AIR 固有の sandboxRoot 属性と documentRoot 属性を設定します。sandboxRoot 値を実際のリモートドメインに設定すると、サンドボックスに割り当てたコンテンツで、そのドメインのコンテンツをクロススク
リプトできるようになります。この方法によるページのマッピングは、マッシュアップアプリケーションなどで、リモート
コンテンツの読み込みおよびスクリプト作成を行う場合に役立ちます。
アプリケーションおよび非アプリケーションのコンテンツで互いにクロススクリプトできるようにするもう 1 つの方法、また非アプリケーションコンテンツから AIR API にアクセスできるようにする唯一の方法は、サンドボックスブリッジを作成することです。親から子へのブリッジを使用すると、アプリケーションサンドボックスで定義されている指定のメソッドとプロパティに、子のフレーム、インラインフレームまたはウィンドウのコンテンツからアクセスできます。逆に、子から親へのブリッジを使用すると、子のサンドボックスで定義されている指定のメソッドとプロパティに、アプリケーションコン
テンツからアクセスできます。サンドボックスブリッジを確立するには、ウィンドウオブジェクトの parentSandboxBridge
プロパティと childSandboxBridge プロパティを設定します。詳しくは、1043 ページの「Adobe AIR の HTML セキュリ
ティ」および 935 ページの「HTML の frame エレメントと iframe エレメント」を参照してください。

プラグインと埋め込みオブジェクトについて
Adobe AIR 1.0 およびそれ以降
AIR では、Adobe® Acrobat® プラグインをサポートしています。PDF コンテンツを表示するには、ユーザーは、Acrobat
または Adobe® Reader® 8.1 以上を使用する必要があります。HTMLLoader オブジェクトには、ユーザーのシステムでPDF を表示できるかどうかをチェックするためのプロパティが用意されています。SWF ファイルコンテンツも HTML 環
境内で表示できますが、この機能は AIR に組み込まれており、外部プラグインは必要ありません。
その他の Webkit プラグインは、AIR ではサポートされていません。
関連項目

1043 ページの「Adobe AIR の HTML セキュリティ」
928 ページの「HTML サンドボックス」
935 ページの「HTML の frame エレメントと iframe エレメント」
933 ページの「JavaScript の Window オブジェクト」
929 ページの「XMLHttpRequest オブジェクト」
527 ページの「AIR での PDF コンテンツの追加」

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

928

HTML 環境について

AIR および WebKit
Adobe AIR 1.0 およびそれ以降
Adobe AIR では、Safari Web ブラウザーでも使用されるオープンソースの Webkit エンジンを使用します。AIR では、セキュリティ目的のほかに、ランタイムクラスとオブジェクトにアクセスできるようにするため、いくつかの拡張機能を追加します。また、Webkit 自体でも、HTML、CSS および JavaScript の W3C 標準には含まれていない機能を追加します。
ここでは、AIR の追加機能と Webkit の最も注目される拡張機能についてのみ説明します。非標準の HTML、CSS および

JavaScript に関する他のドキュメントについては、www.webkit.org および developer.apple.com/jp を参照してください。
標準規格については、W3C Web サイトを参照してください。Mozilla にも、HTML、CSS および DOM のトピックに関する有用な一般リファレンスがあります（ただし、WebKit エンジンと Mozilla エンジンは同一ではありません）。

AIR での JavaScript
Flash Player 9 以降、Adobe AIR 1.0 以降
AIR では、一般的な JavaScript オブジェクトの通常動作にいくつか変更が加えられます。これらの変更の多くは、AIR で安全なアプリケーションを容易に作成できるようにするために行われます。また、この動作の違いによって、JavaScript の一般的なコーディングパターンの一部と、そのパターンを使用している既存の Web アプリケーションが、AIR では期待ど
おりに実行されない場合があります。このような問題の修正については、946 ページの「セキュリティ関連の JavaScript エ
ラーの回避」を参照してください。

HTML サンドボックス
Adobe AIR 1.0 およびそれ以降
AIR では、コンテンツは、そのコンテンツの生成元に従って個別のサンドボックスに配置されます。サンドボックス規則
は、Adobe Flash Player で実装されているサンドボックスの規則と同様、ほとんどの Web ブラウザーで実装されている同一生成元ポリシーに従っています。また、AIR には、アプリケーションコンテンツを格納して保護する、新しいアプリケー
ションサンドボックスタイプが用意されています。AIR アプリケーションの開発時に扱う場合があるサンドボックスのタイプについて詳しくは、1006 ページの「セキュリティサンドボックス」を参照してください。
ランタイム環境および AIR API へのアクセスは、アプリケーションサンドボックス内で実行される HTML および
JavaScript からのみ可能です。ただし、その際、JavaScript の動的な評価と実行は、様々な形で、セキュリティ上の理由か
らアプリケーションサンドボックス内で大きく制限されます。これらの制限は、実際にアプリケーションでサーバーから直接情報を読み込むかどうかに関わらず適用されます（ファイルコンテンツ、ペーストされたストリングおよび直接ユーザー
入力であっても、信頼できない可能性があります）。
ページ内のコンテンツの生成元によって、割り当て先のサンドボックスが決まります。アプリケーションディレクトリ
（app: URL スキームで参照するインストールディレクトリ）から読み込まれたコンテンツのみ、アプリケーションサンド
ボックスに配置されます。ファイルシステムから読み込まれたコンテンツは、local-with-file system サンドボックスまたは local-trusted サンドボックスに配置されます。このサンドボックスでは、ローカルファイルシステム上のコンテンツへのアクセスおよび操作は許可されますが、リモートコンテンツへのアクセスおよび操作は許可されません。ネットワークから読み込まれたコンテンツは、元のドメインに対応するリモートサンドボックスに配置されます。
リモートサンドボックス内のコンテンツをアプリケーションページから自由に操作できるようにするには、リモートコンテ
ンツと同じドメインにページをマップします。例えば、インターネットサービスからマップデータを表示するアプリケー
ションを作成する場合は、そのサービスからコンテンツを読み込んで表示するアプリケーションのページをサービスドメイ
ンにマップします。リモートサンドボックスおよびドメインにページをマップするための属性は、HTML の frame エレメ
ントと iframe エレメントに追加された新しい属性です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

929

HTML 環境について

非アプリケーションサンドボックス内のコンテンツで安全に AIR 機能を使用できるようにするには、親サンドボックスブ
リッジを設定します。アプリケーションコンテンツで他のサンドボックス内のコンテンツのメソッドの呼び出しおよびプロ
パティへのアクセスを安全に行えるようにするには、子サンドボックスブリッジを設定します。この場合の安全とは、明示的に公開していないオブジェクト、プロパティまたはメソッドに、リモートコンテンツから誤って参照しないようにすることを指します。単純データ型、関数および匿名オブジェクトのみ、ブリッジを介して渡すことができます。ただし、危険性のある関数は明示的に公開しないでください。例えば、ユーザーのシステム上の任意の場所にあるファイルの読み取りと書き込みをリモートコンテンツに許可するインターフェイスを公開すると、ユーザーに多大な被害を与える可能性をリモート
コンテンツが持つことになります。

JavaScript の eval() 関数
Adobe AIR 1.0 およびそれ以降
ページの読み込みが完了すると、eval() 関数の使用はアプリケーションサンドボックス内で制限されます。JSON 形式のデー
タを安全に解析できるように一部の使用は許可されますが、実行可能ステートメントを生成する評価はすべてエラーになります。1045 ページの「異なるサンドボックス内のコンテンツに対するコードの制限」で、eval() 関数の許可される使用について説明しています。

関数コンストラクター
Adobe AIR 1.0 およびそれ以降
アプリケーションサンドボックスでは、ページの読み込みが完了する前に関数コンストラクターを使用できます。ページのload イベントハンドラーがすべて終了した後は、新しい関数は作成できません。

外部スクリプトの読み込み
Adobe AIR 1.0 およびそれ以降
アプリケーションサンドボックス内の HTML ページでは、script タグを使用してアプリケーションディレクトリ外から

JavaScript ファイルを読み込むことはできません。アプリケーションのページでアプリケーションディレクトリ外からスク
リプトを読み込むには、そのページを非アプリケーションサンドボックスにマップする必要があります。

XMLHttpRequest オブジェクト
Adobe AIR 1.0 およびそれ以降
AIR には、アプリケーションでデータ要求を行うために使用できる XMLHttpRequest（XHR）オブジェクトが用意されています。次の例に、簡単なデータ要求を示します。
xmlhttp = new XMLHttpRequest();xmlhttp.open("GET", "http:/www.example.com/file.data", true);
xmlhttp.onreadystatechange = function() {if (xmlhttp.readyState == 4) {//do something with data...
}}
xmlhttp.send(null);

ブラウザーとは対照的に、AIR では、アプリケーションサンドボックス内で実行されるコンテンツは任意のドメインのデー
タを要求できます。JSON ストリングを含む XHR の結果は、実行可能コードもその結果に含まれる場合を除き、データオ
ブジェクトになります。実行可能ステートメントが XHR 結果で表される場合、エラーがスローされ、評価の試行は失敗します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

930

HTML 環境について

リモートソースからコードが意図せず挿入されないようにするため、同期 XHR は、ページの読み込みが完了する前に行われた場合は空の結果を返します。非同期 XHR は、常に、ページが読み込まれた後に返します。
デフォルトでは、AIR は、非アプリケーションサンドボックスでのクロスドメイン XMLHttpRequest をブロックします。
アプリケーションサンドボックス内の親ウィンドウでは、非アプリケーションサンドボックス内のコンテンツを含む子フ
レームでのクロスドメイン要求を許可することを選択できます。それには、コンテナとなっている frame エレメントまたはiframe エレメントで、allowCrossDomainXHR（AIR で追加された属性）を true に設定します。
<iframe id="mashup"src="http://www.example.com/map.html"
allowCrossDomainXHR="true"</iframe>

注意：必要に応じて、AIR の URLStream クラスを使用してデータをダウンロードすることもできます。
リモートサンドボックスにマップされているアプリケーションコンテンツを含むフレームまたはインラインフレームからリ
モートサーバーに XMLHttpRequest を送出する場合は、マッピング URL で、XHR で使用するサーバーアドレスをマスクしていないことを確認してください。例えば、example.com ドメインのリモートサンドボックスにアプリケーションコン
テンツをマップする、次の iframe 定義について考えます。
<iframe id="mashup"src="http://www.example.com/map.html"
documentRoot="app:/sandbox/"
sandboxRoot="http://www.example.com/"allowCrossDomainXHR="true"</iframe>

sandboxRoot 属性は www.example.com アドレスのルート URL を再マップするので、すべての要求はアプリケーション
ディレクトリから読み込まれ、リモートサーバーからは読み込まれません。要求は、ページナビゲーションとXMLHttpRequest のいずれから発生するかに関わらず、再マップされます。
リモートサーバーへのデータ要求が誤ってブロックされないようにするには、sandboxRoot を、ルートではなくリモート

URL のサブディレクトリにマップします。このディレクトリは存在していなくてもかまいません。例えば、
www.example.com への要求でアプリケーションディレクトリではなくリモートサーバーからの読み込みを許可するには、
上述の iframe を次のように変更します。
<iframe id="mashup"src="http://www.example.com/map.html"
documentRoot="app:/sandbox/"
sandboxRoot="http://www.example.com/air/"allowCrossDomainXHR="true"</iframe>

この場合、air サブディレクトリ内のコンテンツのみローカルに読み込まれます。
サンドボックスのマッピングについて詳しくは、935 ページの「HTML の frame エレメントと iframe エレメント」および1043 ページの「Adobe AIR の HTML セキュリティ」を参照してください。

CookieAdobe AIR 1.0 およびそれ以降
AIR アプリケーションでは、リモートサンドボックス内のコンテンツ（http: ソースおよび https: ソースから読み込まれたコンテンツ）のみ、Cookie（document.cookie プロパティ）を使用できます。アプリケーションサンドボックスには、

EncryptedLocalStore、SharedObject および FileStream クラスなど、永続データを格納するための他の手段が用意されています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

931

HTML 環境について

Clipboard オブジェクト
Adobe AIR 1.0 およびそれ以降
WebKit Clipboard API は、copy、cut、paste の各イベントによって動作します。これらのイベントで渡されるイベントオ
ブジェクトでは、clipboardData プロパティを使用してクリップボードにアクセスできます。クリップボードのデータを読み取ったり、書き込んだりするには、clipboardData オブジェクトの次のメソッドを使用します。
メソッド

説明

clearData(mimeType)

クリップボードのデータを消去します。mimeType パラメーターを、消去するデータの MIME タイプに設定します。

getData(mimeType)

クリップボードのデータを取得します。このメソッドは、paste イベントのハンドラーでのみ呼び出すことができます。mimeType パラメーターを、取得するデータの MIME タイプに設定します。

setData(mimeType, data)

データをクリップボードにコピーします。mimeType パラメーターをデータの MIME タイプに設定します。

アプリケーションサンドボックス外の JavaScript コードからクリップボードにアクセスするには、これらのイベントを使用する必要があります。ただし、アプリケーションサンドボックス内のコンテンツでは、AIR の Clipboard クラスを使用してシステムクリップボードに直接アクセスできます。例えば、次のステートメントを使用すると、クリップボードのテキスト
形式のデータを取得できます。
var clipping = air.Clipboard.generalClipboard.getData("text/plain",
air.ClipboardTransferMode.ORIGINAL_ONLY);

データの有効な MIME タイプは、次のとおりです。
MIME タイプ

値

テキスト"text/plain"HTML"text/html"

URL"text/uri-list"

ビットマップ"image/x-vnd.adobe.air.bitmap"

ファイルリスト"application/x-vnd.adobe.air.file-list"

重要：アプリケーションサンドボックス内のコンテンツからのみ、クリップボード上にあるファイルデータにアクセスできます。非アプリケーションコンテンツからクリップボードのファイルオブジェクトにアクセスしようとすると、セキュリ
ティエラーがスローされます。
クリップボードの使用について詳しくは、572 ページの「コピー＆ペースト」および「JavaScript からのペーストボードの使用（Apple デベロッパーセンター）」を参照してください。

ドラッグ＆ドロップ
Adobe AIR 1.0 およびそれ以降
HTML への、また HTML からのドラッグ＆ドロップ操作は、dragstart、drag、dragend、dragenter、dragover、dragleave、
drop の各 DOM イベントを発生させます。これらのイベントで渡されるイベントオブジェクトでは、dataTransfer プロパ
ティを使用してドラッグしたデータにアクセスできます。dataTransfer プロパティは、クリップボードイベントに関連付けられている clipboardData オブジェクトと同じメソッドを備えたオブジェクトを参照します。例えば、次の関数を使用すると、drop イベントからテキスト形式のデータを取得できます。
function onDrop(dragEvent){
return dragEvent.dataTransfer.getData("text/plain",
air.ClipboardTransferMode.ORIGINAL_ONLY);}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

932

HTML 環境について

dataTransfer オブジェクトには、次の重要なメンバーがあります。
メンバー

説明

clearData(mimeType)

データを消去します。mimeType パラメーターを、消去するデータ表現の MIME タイプに設定します。

getData(mimeType)

ドラッグするデータを取得します。このメソッドは、drop イベントのハンドラーでのみ呼び出すことができます。

mimeType パラメーターを、取得するデータの MIME タイプに設定します。

setData(mimeType, data)

ドラッグするデータを設定します。mimeType パラメーターをデータの MIME タイプに設定します。

types

dataTransfer オブジェクトで現在使用できるすべてのデータ表現の MIME タイプを含む、ストリングの配列です。

effectsAllowed

ドラッグするデータのコピー、移動、リンクまたはそれらを組み合わせた操作を行えるかどうかを指定します。
dragstart イベントのハンドラーで effectsAllowed プロパティを設定します。

dropEffect

可能なドロップ操作のうち、ドラッグターゲットでサポートするものを指定します。dragEnter イベントのハンド
ラーで dropEffect プロパティを設定します。ドラッグ時、ユーザーがマウスを放すと発生する操作を示すよう、カーソルが変化します。dropEffect を指定していない場合は、effectsAllowed プロパティの操作が選択されます。
コピー操作は移動操作より優先度が高く、移動操作はリンク操作より優先度が高いです。ユーザーは、キーボードを使用して、デフォルトの優先度を変更できます。

AIR アプリケーションにドラッグ＆ドロップのサポートを追加する方法について詳しくは、584 ページの「AIR でのドラッ
グ＆ドロップ」および「JavaScript からのドラッグ＆ドロップの使用（Apple デベロッパーセンター）」を参照してください。

innerHTML プロパティと outerHTML プロパティ
Adobe AIR 1.0 およびそれ以降
AIR では、アプリケーションサンドボックス内で実行されるコンテンツの innerHTML プロパティと outerHTML プロパティの使用に対して、セキュリティ制限が適用されます。ページの load イベントの前、また load イベントハンドラーの実行中
は、innerHTML プロパティと outerHTML プロパティの使用は制限されません。ただし、ページが読み込まれると、

innerHTML プロパティまたは outerHTML プロパティを使用できるのは、ドキュメントへの静的コンテンツの追加に限定されます。実行可能コードになる、innerHTML または outerHTML に割り当てられたストリング内のステートメントは、すべて無視されます。例えば、イベントのコールバック属性をエレメント定義に含めると、イベントリスナーは追加されません。
同様に、埋め込みの <script> タグは評価されません。詳しくは、1043 ページの「Adobe AIR の HTML セキュリティ」を参照してください。

Document.write() メソッドと Document.writeln() メソッド
Adobe AIR 1.0 およびそれ以降
ページの load イベントの前は、write() メソッドと writeln() メソッドの使用はアプリケーションサンドボックスで制限されません。ただし、ページが読み込まれると、これらのメソッドのいずれかを呼び出しても、ページがクリアされることも新しいページが作成されることもありません。非アプリケーションサンドボックスでは、ほとんどの Web ブラウザーの場合と同様に、ページの読み込み完了後に document.write() または writeln() を呼び出すと、現在のページがクリアされ、新しい空白のページが開かれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

933

HTML 環境について

Document.designMode プロパティ
Adobe AIR 1.0 およびそれ以降
ドキュメント内のすべてのエレメントを編集可能にするには、document.designMode プロパティを値 on に設定します。ビル
トインエディターのサポートに含まれるのは、テキストの編集、コピー、ペーストおよびドラッグ＆ドロップです。
designMode を on に設定することは、body エレメントの contentEditable プロパティを true に設定することと同じです。編集可能にするドキュメントのセクションを定義するため、HTML エレメントのほとんどで contentEditable プロパティを使用できます。詳しくは、938 ページの「HTML の contentEditable 属性」を参照してください。

unload イベント（body オブジェクトおよび frameset オブジェクトの場合）
Adobe AIR 1.0 およびそれ以降
ウィンドウ（アプリケーションのメインウィンドウを含む）のトップレベルの frameset タグまたは body タグでは、閉じられるウィンドウ（またはアプリケーション）への応答に unload イベントを使用しないでください。代わりに、

NativeApplication オブジェクトの exiting イベントを使用します（アプリケーションが終了するときを検出するために使用）。または、NativeWindow オブジェクトの closing イベントを使用します（ウィンドウが閉じるときを検出するために使用）。例えば、次の JavaScript コードでは、ユーザーがアプリケーションを閉じるときにメッセージ（「Goodbye.」）を表示します。
var app = air.NativeApplication.nativeApplication;
app.addEventListener(air.Event.EXITING, closeHandler);function closeHandler(event){alert("Goodbye.");}

ただし、スクリプトでは、フレーム、インラインフレームまたはトップレベルウィンドウのコンテンツのナビゲーションによって発生した unload イベントに正常に応答できます。
注意：これらの制限は、Adobe AIR の将来のバージョンで取り除かれる可能性があります。

JavaScript の Window オブジェクト
Adobe AIR 1.0 およびそれ以降
Window オブジェクトは、JavaScript 実行コンテキストではグローバルオブジェクトのままです。アプリケーションサンド
ボックスでは、重要なホストオブジェクトと同様、AIR のビルトインクラスへのアクセスを提供するため、新しいプロパ
ティが JavaScript の Window オブジェクトに追加されます。また、一部のメソッドとプロパティは、アプリケーションサ
ンドボックス内であるかどうかによって動作が異なります。

Window.runtime プロパティ runtime プロパティを使用すると、アプリケーションサンドボックス内から、ビルトインのランタイムクラスをインスタンス化して使用できます。これらのクラスには、AIR および Flash Player の API が含まれます（ただし、Flex フレームワークなどは含まれません）。例えば、次のステートメントでは、AIR ファイルオブジェクトを作成します。
var preferencesFile = new window.runtime.flash.filesystem.File();AIR SDK に付属する AIRAliases.js ファイルには、このような参照を短くすることができるエイリアス定義が含まれています。例えば、AIRAliases.js をページに読み込むと、次のステートメントで File オブジェクトを作成できます。
var preferencesFile = new air.File();window.runtime プロパティは、アプリケーションサンドボックス内のコンテンツと、フレームまたはインラインフレームがあるページの親ドキュメントのためだけに定義されています。

951 ページの「AIRAliases.js ファイルの使用」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

934

HTML 環境について

Window.nativeWindow プロパティ nativeWindow プロパティは、基になるネイティブウィンドウオブジェクトへの参照
を提供します。このプロパティを使用すると、画面の位置、サイズ、可視性など、ウィンドウの関数とプロパティのスクリ
プトを作成することも、終了、サイズ変更、移動などのウィンドウイベントを処理することもできます。例えば、次のス
テートメントではウィンドウを閉じます。
window.nativeWindow.close();

注意：NativeWindow オブジェクトが提供するウィンドウ制御機能は、JavaScript の Window オブジェクトが提供する機能と重複します。そのような場合は、使いやすい方のメソッドを使用できます。

window.nativeWindow プロパティは、アプリケーションサンドボックス内のコンテンツと、フレームまたはインラインフ
レームがあるページの親ドキュメントのためだけに定義されています。

Window.htmlLoader プロパティ htmlLoader プロパティは、HTML コンテンツを含む AIR の HTMLLoader オブジェ
クトへの参照を提供します。このプロパティを使用すると、HTML 環境の外観と動作のスクリプトを作成できます。例えば、htmlLoader.paintsDefaultBackground プロパティを使用して、コントロールでデフォルトの白い背景を描画するかどうかを指定できます。
window.htmlLoader.paintsDefaultBackground = false;

注意：HTMLLoader オブジェクト自体に、格納している HTML コンテンツの JavaScript Window オブジェクトを参照する window プロパティがあります。このプロパティを使用すると、コンテナとなっている HTMLLoader への参照を通じて

JavaScript 環境にアクセスできます。
window.htmlLoader プロパティは、アプリケーションサンドボックス内のコンテンツと、フレームまたはインラインフレー
ムがあるページの親ドキュメントのためだけに定義されています。

Window.parentSandboxBridge プロパティと Window.childSandboxBridge プロパティ parentSandboxBridge プロ
パティと childSandboxBridge プロパティを使用すると、親と子のフレーム間のインターフェイスを定義できます。詳しくは、

961 ページの「異なるセキュリティサンドボックス内のコンテンツのクロススクリプト」を参照してください。
Window.setTimeout() 関数と Window.setInterval() 関数 AIR では、アプリケーションサンドボックス内でのsetTimeout() 関数と setInterval() 関数の使用に対して、セキュリティ制限が適用されます。setTimeout() または setInterval()を呼び出すときに、ストリングとして実行されるコードを定義することはできません。関数参照を使用する必要があります。
詳しくは、948 ページの「setTimeout() および setInterval()」を参照してください。

Window.open() 関数 非アプリケーションサンドボックス内で実行されるコードから呼び出す場合、open() メソッドは、
ユーザー操作（マウスクリックやキー入力など）の結果として呼び出されたときにのみウィンドウを開きます。また、ウィンドウのタイトルには、アプリケーションタイトルが前に付けられます（リモートコンテンツによって開かれたウィンドウが、アプリケーションによって開かれたウィンドウを偽装しないようにするため）。詳しくは、1048 ページの「JavaScript

window.open() メソッドの呼び出しに関する制限」を参照してください。

air.NativeApplication オブジェクト
Adobe AIR 1.0 およびそれ以降
NativeApplication オブジェクトは、アプリケーションの状態に関する情報を提供し、いくつかの重要なアプリケーション
レベルのイベントを送出し、アプリケーション動作の制御に役立つ関数を提供します。NativeApplication オブジェクトの
単一インスタンスは、自動的に作成され、クラスで定義されている NativeApplication.nativeApplication プロパティを使用してアクセスできます。
このオブジェクトに JavaScript コードからアクセスするには、次のステートメントを使用できます。
var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

または、AIRAliases.js スクリプトが読み込まれている場合は、次の短い形式を使用できます。
var app = air.NativeApplication.nativeApplication;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

935

HTML 環境について

NativeApplication オブジェクトには、アプリケーションサンドボックス内からのみアクセスできます。
NativeApplication オブジェクトについて詳しくは、852 ページの「AIR ランタイムとオペレーティングシステムに関する情報の操作」を参照してください。

JavaScript URL スキーム
Adobe AIR 1.0 およびそれ以降
JavaScript URL スキーム（href="javascript:alert('Test')" など）で定義されたコードの実行は、アプリケーションサンドボッ
クス内でブロックされます。エラーはスローされません。

AIR での HTMLAdobe AIR 1.0 およびそれ以降
AIR および WebKit では、次に示す、非標準の HTML エレメントと属性を定義します。
935 ページの「HTML の frame エレメントと iframe エレメント」
937 ページの「HTML エレメントのイベントハンドラー」

HTML の frame エレメントと iframe エレメント
Adobe AIR 1.0 およびそれ以降
AIR では、アプリケーションサンドボックス内のコンテンツの frame エレメントと iframe エレメントに新しい属性を追加します。

sandboxRoot 属性 sandboxRoot 属性は、フレームの src 属性で指定されているファイルの元の場所の代わりとなる非アプ
リケーションドメインを指定します。ファイルは、指定したドメインに対応する非アプリケーションサンドボックスに読み込まれます。ファイル内のコンテンツと、指定したドメインから読み込まれたコンテンツでは、互いにクロススクリプトできます。
重要：sandboxRoot の値をドメインのベース URL に設定すると、そのドメインからのコンテンツに対するすべての要求は、リモートサーバーではなく、アプリケーションディレクトリから読み込まれます（その要求が、ページナビゲーション、

XMLHttpRequest、コンテンツを読み込むその他の手段のいずれによって発生したかは関係ありません）。
documentRoot 属性 documentRoot 属性は、sandboxRoot で指定されている場所にあるファイルに解決される URL の読み込み元となるローカルディレクトリを指定します。
フレームの src 属性またはフレームに読み込まれたコンテンツのいずれかで、URL を解決するとき、sandboxRoot で指定されている値に一致する URL の部分は、documentRoot で指定されている値によって置き換えられます。したがって、次のフレームタグでは、後述の動作になります。
<iframe src="http://www.example.com/air/child.html"
documentRoot="app:/sandbox/"
sandboxRoot="http://www.example.com/air/"/>child.html は、アプリケーションのインストールフォルダーの sandbox サブディレクトリから読み込まれます。child.html の相対 URL は、sandbox ディレクトリに基づいて解決されます。www.example.com/air のリモートサーバー上のいずれのファ
イルにもフレームでアクセスできません。これは、AIR が app:/sandbox/ ディレクトリからファイルを読み込もうとするためです。

allowCrossDomainXHR 属性 フレーム内のコンテンツで任意のリモートドメインに対する XMLHttpRequest を生成することを許可するには、フレームの開始タグに allowCrossDomainXHR="allowCrossDomainXHR" を含めます。デフォルトでは、非アプリケーションコンテンツは、元の個々のドメインに対してのみこの要求を行うことができます。クロスドメイン

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

936

HTML 環境について

XHR を許可する場合、重大なセキュリティ上の影響を伴います。ページのコードで任意のドメインとデータを交換できるようになります。悪意のあるコンテンツが何らかの形でページに挿入されている場合、現在のサンドボックス内のコードからアクセスできるあらゆるデータが、漏洩してしまう可能性があります。クロスドメイン XHR は、自分で作成して制御するページに対してのみ有効にし、クロスドメインのデータ読み込みが本当に必要な場合にのみ有効にしてください。また、コードの挿入や他の形での攻撃を避けるため、ページで読み込まれるすべての外部データを慎重に検証してください。
重要：allowCrossDomainXHR 属性を frame エレメントまたは iframe エレメントに含めると、クロスドメイン XHR が有効になります（割り当てられた値が「0」であるか、「f」または「n」で始まる場合を除く）。例えば、allowCrossDomainXHR
を "deny" に設定した場合は、クロスドメイン XHR は有効のままになります。クロスドメイン要求を有効にしない場合は、エレメントの宣言からこの属性全体を除外してください。

ondominitialize 属性 [ondominitialize ぞくせい ] フレームの dominitialize イベントのイベントハンドラーを指定します。このイベントは、AIR 固有のイベントで、フレームのウィンドウオブジェクトおよびドキュメントオブジェクトが作成されたときに発生します。ただし、スクリプトが解析されたり、ドキュメントエレメントが作成されたりする前に発生します。
フレームは、dominitialize ハンドラーによって子ドキュメントに追加されたオブジェクト、変数および関数を子ページのスクリプトで参照できる読み込み順序で、dominitialize イベントを十分早期に送出します。子ドキュメントのオブジェクトについて、直接追加したり、アクセスしたりするには、親ページが子と同じサンドボックスに含まれている必要があります。
ただし、アプリケーションサンドボックス内の親で、サンドボックスブリッジを確立して、非アプリケーションサンドボッ
クス内のコンテンツと通信できます。
次の例に、AIR での iframe タグの使用を示します。

child.html を、リモートサーバーの実際のドメインにマップせずに、リモートサンドボックスに配置します。
<iframe src="http://localhost/air/child.html"
documentRoot="app:/sandbox/"
sandboxRoot="http://localhost/air/"/>child.html をリモートサンドボックスに配置し、www.example.com への XMLHttpRequest のみ許可します。
<iframe src="http://www.example.com/air/child.html"
documentRoot="app:/sandbox/"
sandboxRoot="http://www.example.com/air/"/>child.html をリモートサンドボックスに配置し、任意のリモートドメインへの XMLHttpRequest を許可します。
<iframe src="http://www.example.com/air/child.html"
documentRoot="app:/sandbox/"
sandboxRoot="http://www.example.com/air/"allowCrossDomainXHR="allowCrossDomainXHR"/>

child.html を local-with-file-system サンドボックスに配置します。
<iframesrc="file:///templates/child.html"
documentRoot="app:/sandbox/"
sandboxRoot="app-storage:/templates/"/>child.html をリモートサンドボックスに配置し、dominitialize イベントを使用してサンドボックスブリッジを確立します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

937

HTML 環境について<html><head><script>
var bridgeInterface = {};bridgeInterface.testProperty = "Bridge engaged";function engageBridge(){document.getElementById("sandbox").parentSandboxBridge = bridgeInterface;}</script></head><body><iframe id="sandbox"
src="http://www.example.com/air/child.html"
documentRoot="app:/"sandboxRoot="http://www.example.com/air/"ondominitialize="engageBridge()"/></body></html>次の child.html ドキュメントは、子コンテンツから親サンドボックスブリッジにアクセスする方法を示しています。
<html><head><script>
document.write(window.parentSandboxBridge.testProperty);</script></head><body></body></html>

詳しくは、961 ページの「異なるセキュリティサンドボックス内のコンテンツのクロススクリプト」および 1043 ページの「Adobe AIR の HTML セキュリティ」を参照してください。

HTML エレメントのイベントハンドラー
Adobe AIR 1.0 およびそれ以降
AIR および Webkit の DOM オブジェクトは、標準の DOM イベントモデルにはないイベントを送出します。次の表に、
これらのイベントのハンドラーを指定するために使用できる、関連するイベント属性を示します。
コールバック属性名

説明

oncontextmenu

選択されたテキストでの右クリックまたはコマンドクリックなどによってコンテキストメニューが呼び出されるときに呼び出されます。

oncopyエレメントでの選択内容がコピーされるときに呼び出されます。

oncut

エレメントでの選択内容がカットされるときに呼び出されます。

ondominitialize

フレームまたはインラインフレームに読み込まれたドキュメントのDOM が作成されるときに呼び出されます。ただし、DOM エレメントが作成されたり、スクリプトが解析されたりする前に呼び出されます。

ondrag

エレメントがドラッグされるときに呼び出されます。

ondragend

ドラッグが放されるときに呼び出されます。

ondragenter

ドラッグ操作がエレメントの境界に入るときに呼び出されます。

ondragleave

ドラッグ操作がエレメントの境界から出るときに呼び出されます。

ondragover

ドラッグ操作がエレメントの境界内にある間、連続して呼び出されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

938

HTML 環境について

コールバック属性名

説明

ondragstart

ドラッグ操作が開始されるときに呼び出されます。

ondrop

ドラッグ操作がエレメント上で放されるときに呼び出されます。

onerror

エレメントの読み込み中にエラーが発生したときに呼び出されます。

oninput

テキストがフォームエレメントに入力されるときに呼び出されます。

onpasteアイテムがエレメントにペーストされるときに呼び出されます。

onscroll

スクロールできるエレメントのコンテンツがスクロールされるときに呼び出されます。

onselectstart

選択が開始されるときに呼び出されます。

HTML の contentEditable 属性
Adobe AIR 1.0 およびそれ以降
contentEditable 属性を任意の HTML エレメントに追加して、そのエレメントのコンテンツをユーザーが編集できるようにすることができます。例えば、次の例の HTML コードでは、最初の p エレメントを除き、ドキュメント全体を編集可能として設定します。
<html><head/><body contentEditable="true"><h1>de Finibus Bonorum et Malorum</h1><p contentEditable="false">Sed ut perspiciatis unde omnis iste natus error.</p><p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis.</p></body></html>注意：document.designMode プロパティを on に設定すると、個々のエレメントに対する contentEditable の設定に関わらず、ドキュメント内のすべてのエレメントが編集可能になります。ただし、designMode を off に設定しても、contentEditable がtrue になっているエレメントの編集は無効になりません。詳しくは、933 ページの「Document.designMode プロパティ」
を参照してください。

data: URL
Adobe AIR 2 以降
AIR は、次のエレメントの data: URL をサポートしています。

• img• input type="image"• CSS ルールで許可されているイメージ（background-image など）
data: URL を使用すると、CSS または HTML ドキュメントにバイナリイメージデータを直接 base64 エンコード文字列として挿入できます。次の例では、data: URL を繰り返す背景として使用しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

939

HTML 環境について<html><head><style>body {
backgroundimage:url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAGXRFWHRTb2Z0d2FyZQBBZG9i
ZSBJbWFnZVJlYWR5ccllPAAAAAZQTFRF%2F6cA%2F%2F%2F%2Fgxp3lwAAAAJ0Uk5T%2FwDltzBKAAABF0lEQVR42uzZQQ7CMAxE0e%2F
7X5oNCyRocWzPiJbMBZ6qpIljE%2BnwklgKG7kwUjc2IkIaxkY0CPdEsCCasws6ShXBgmBBmEagpXQQLAgWBAuSY2gaKaWPYEGwIEwg0F
RmECwIFoQeQjJlhJWUEFazjFDJCkI5WYRWMgjtfEGYyQnCXD4jTCdm1zmngFpBFznwVNi5RPSbwbWnpYr%2BBHi%2FtCTfgPLEPL7jBct
AKBRptXJ8M%2BprIuZKu%2BUKcg4YK1PLz7kx4bSqHyPaT4d%2B28OCJJiRBo4FCQsSA0bziT3XubMgYUG6fc5fatmGBQkL0hoJ1IaZMi
QsSFiQ8vRscTjlQOI2iHZwtpHuf%2BJAYiOiJSkj8Z%2FIQ4ABANvXGLd3%2BZMrAAAAAElFTkSuQmCC');
background-repeat:repeat;}</style></head><body></body></html>data: URL を使用するときは、空白の有無に意味があることに留意してください。例えば、データ文字列は改行されていな
い単一行として入力する必要があります。改行すると、改行がデータの一部として処理され、イメージがデコードされません。

AIR での CSS
Adobe AIR 1.0 およびそれ以降
WebKit では、様々な拡張 CSS プロパティをサポートしています。これらの拡張機能の多くでは、接頭辞 -webkit が使用されます。これらの拡張機能の一部は実験的なものであり、将来のバージョンの WebKit からは除外される可能性があります。CSS に対する WebKit のサポートと拡張機能について詳しくは、「Safari CSS リファレンス」を参照してください。

AIR でサポートされていない WebKit の機能
Adobe AIR 1.0 およびそれ以降
AIR は、WebKit または Safari 4 で利用できる次の機能をサポートしていません。

• window.postMessage 経由のクロスドメインメッセージング（AIR は独自のクロスドメイン通信 API を提供）。
• CSS 変数• Web Open Font Format（WOFF）および SVG フォント
• HTML ビデオタグおよびオーディオタグ•

メディアデバイスキュー•

オフラインアプリケーションキャッシュ•プリント（AIR は独自の PrintJob API を提供）•

スペルチェッカーおよび文法チェッカー• SVG• WAI-ARIA• WebSocket（AIR は独自のソケット API を提供）
• Web ワーカー
• WebKit SQL API（AIR は独自の API を提供）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

940

HTML 環境について• WebKit ジオロケーション API（API はサポートされているデバイスで独自のジオロケーション API を提供）
• WebKit マルチファイルアップロード API• WebKit タッチイベント（AIR は独自のタッチイベントを提供）• Wireless Markup Language（WML）
次のリストは、AIR がサポートしていない特定の JavaScript API、HTML エレメント、CSS プロパティと値を示しています。
サポートされない JavaScript Window オブジェクトメンバー：• applicationCache()• console• openDatabase()• postMessage()• document.print()
サポートされない HTML タグ：• audio• video
サポートされない HTML 属性：• aria-*• draggable• formnovalidate• list• novalidate• onbeforeload• onhashchange• onorientationchange• onpagehide• onpageshow• onpopstate• ontouchstart• ontouchmove• ontouchend• ontouchcancel• onwebkitbeginfullscreen• onwebkitendfullscreen• pattern• required• sandbox

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

941

HTML 環境についてサポートされない JavaScript イベント：• beforeload• hashchange• orientationchange• pagehide• pageshow• popstate• touchstart• touchmove• touchend• touchcancel• webkitbeginfullscreen• webkitendfullscreen
サポートされない CSS プロパティ：• background-clip• background-origin（-webkit-background-origin を使用）
• background-repeat-x• background-repeat-y• background-size（-webkit-background-size を使用）
• border-bottom-left-radius• border-bottom-right-radius• border-radius• border-top-left-radius• border-top-right-radius• text-rendering• -webkit-animation-play-state• -webkit-background-clip• -webkit-color-correction• -webkit-font-smoothing
サポートされない CSS 値：•

外観プロパティの値：• media-volume-slider-container• media-volume-slider• media-volume-sliderthumb• outer-spin-button

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

942

HTML 環境について• border-box（background-clip および background-origin）• contain（background-size）• content-box（background-clip および background-origin）• cover（background-size）•

リストプロパティの値：• afar• amharic• amharic-abegede• cjk-earthly-branch• cjk-heavenly-stem• ethiopic• ethiopic-abegede• ethiopic-abegede-am-et• ethiopic-abegede-gez• ethiopic-abegede-ti-er• ethiopic-abegede-ti-et• ethiopic-halehame-aa-er• ethiopic-halehame-aa-et• ethiopic-halehame-am-et• ethiopic-halehame-gez• ethiopic-halehame-om-et• ethiopic-halehame-sid-et• ethiopic-halehame-so-et• ethiopic-halehame-ti-er• ethiopic-halehame-ti-et• ethiopic-halehame-tig• hangul• hangul-consonant• lower-norwegian• oromo• sidama• somali• tigre• tigrinya-er• tigrinya-er-abegede

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

943

HTML 環境について• tigrinya-et• tigrinya-et-abegede• upper-greek• upper-norwegian• -wap-marquee（表示プロパティ）

最終更新日 2015/10/14

944

第 59 章：AIR での HTML および JavaScript のプログラミング
Adobe AIR 1.0 およびそれ以降
HTML および JavaScript を使用した Adobe® AIR® アプリケーション開発に特有のプログラミングトピックがいくつかあります。以降の情報は、HTML ベースの AIR アプリケーションをプログラミングする場合にも、HTMLLoader クラス（または mx:HTML Flex™ コンポーネント）を使用して HTML および JavaScript を実行する SWF ベースの AIR アプリケー
ションをプログラミングする場合にも重要です。

HTMLLoader クラスについて
Adobe AIR 1.0 およびそれ以降
Adobe AIR の HTMLLoader クラスは、AIR アプリケーション内で HTML コンテンツを表示できる表示オブジェクトを定義します。SWF ベースのアプリケーションでは、HTMLLoader コントロールを既存のウィンドウに追加したり、HTMLLoader.createRootWindow() を使用して、自動的に HTMLLoader オブジェクトを取り込む HTML ウィンドウを作成したりできます。HTMLLoader オブジェクトには、読み込まれた HTML ページ内から JavaScript の window.htmlLoader
プロパティを通じてアクセスできます。

URL からの HTML コンテンツの読み込み
Adobe AIR 1.0 およびそれ以降
次のコードは、URL を HTMLLoader オブジェクトに読み込みます（HTMLLoader をステージまたは他の表示オブジェ
クトコンテナの子として追加し、アプリケーション内で HTML コンテンツを表示します）。
import flash.html.HTMLLoader;var html:HTMLLoader = new HTMLLoader;
html.width = 400;
html.height = 600;
var urlReq:URLRequest = new URLRequest("http://www.adobe.com/");html.load(urlReq);

HTMLLoader オブジェクトの width プロパティおよび height プロパティはいずれもデフォルトで 0 に設定されます。
HTMLLoader オブジェクトをステージに追加するときに、大きさの設定が必要となる場合があります。HTMLLoader は、ページが読み込まれるときにいくつかのイベントを送出します。このイベントを使用すると、読み込まれたページと安全に通信するタイミングを確認できます。このイベントについて詳しくは、982 ページの「AIR における HTML 関連イベントの処理」を参照してください。
注意：Flex フレームワークでは、UIComponent クラスを拡張するクラスのみが Flex Container コンポーネントの子として追加できます。そのため、HTMLLoader を直接 Flex Container コンポーネントの子として追加することはできません
が、Flex mx:HTML コントロールを使用して UIComponent を拡張するカスタムクラスを作成し、HTMLLoader を

UIComponent の子として組み込むことができます。または、HTMLLoader を UIComponent の子として追加し、
UIComponent を Flex Container に追加することができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

945

AIR での HTML および JavaScript のプログラミング

TextField クラスを使用して HTML テキストをレンダリングすることもできますが、機能に制限があります。Adobe®
Flash® Player の TextField クラスは、HTML マークアップのサブセットをサポートしています。ただし、サイズに制限があるので機能が制限されます（Adobe AIR に含まれる HTMLLoader クラスは、Flash Player では使用できません）。

ストリングからの HTML コンテンツの読み込み
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトの loadString() メソッドは、HTML コンテンツのストリングを HTMLLoader オブジェクトに読み込みます。
var html:HTMLLoader = new HTMLLoader();var htmlStr:String = "<html><body>Hello <b>world</b>.</body></html>";html.loadString(htmlStr);

デフォルトでは、loadString() メソッドを介して読み込まれたコンテンツは、次の特性を持つ非アプリケーションサンドボッ
クスに配置されます。

• （ファイルシステムからではなく）ネットワークからコンテンツを読み込むためのアクセス権を持つ• XMLHttpRequest を使用してデータを読み込むことができない• window.location プロパティが "about:blank" に設定されている• （非アプリケーションサンドボックス内のコンテンツがアクセスできるように）コンテンツは window.runtime プロパティにアクセスできない

AIR 1.5 では、HTMLLoader クラスには placeLoadStringContentInApplicationSandbox プロパティが含まれています。この
プロパティが HTMLLoader オブジェクトに対して true に設定されている場合、loadString() メソッドを介して読み込まれたコンテンツはアプリケーションサンドボックスに配置されます（デフォルト値は false です）。これにより、loadString() メ
ソッドを介して読み込まれたコンテンツは、window.runtime プロパティおよびすべての AIR API にアクセスできます。このプロパティを true に設定する場合は、loadString() メソッドの呼び出しで使用されるストリングのデータソースが信頼できることを確認してください。このプロパティが true に設定されている場合、HTML ストリング内のコードステートメント
は完全なアプリケーション権限で実行されます。ストリングに有害なコードが含まれていないと確信できる場合のみ、このプロパティを true に設定します。

AIR 1.0 または AIR 1.1 SDK でコンパイルされたアプリケーションでは、loadString() メソッドを介して読み込まれたコン
テンツはアプリケーションサンドボックスに配置されます。

AIR アプリケーションでの HTML 使用時の重要なセキュリティ規則
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションと共にインストールするファイルから、AIR API にアクセスできます。セキュリティ上の理由で、他のソースのコンテンツからはアクセスできません。例えば、この制限により、リモートドメイン（http://example.com な
ど）のコンテンツからユーザーのデスクトップディレクトリを読み込むこと（またはさらに悪い状況）はできません。

eval() 関数（および関連する API）を呼び出すことによって攻撃される可能性があるセキュリティの抜け穴があるので、ア
プリケーションと共にインストールされるコンテンツは、これらのメソッドの使用がデフォルトで制限されています。しかし、一部の Ajax フレームワークは、eval() 関数および関連する API の呼び出しを使用します。

AIR アプリケーションで動作するコンテンツを適切に構成するには、異なるソース別のコンテンツに対するセキュリティ制
限の規則を考慮する必要があります。異なるソースのコンテンツは、サンドボックスと呼ばれる個別のセキュリティ区分に配置されます（1006 ページの「セキュリティサンドボックス」を参照）。デフォルトで、アプリケーションと共にインス

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

946

AIR での HTML および JavaScript のプログラミングトールされるコンテンツは、アプリケーションサンドボックスというサンドボックスにインストールされ、AIR API へのア
クセス権が付与されます。アプリケーションサンドボックスは、信頼できないコードの実行を防止するよう設計された制限があり、一般に最も安全性の高いサンドボックスです。
ランタイムでは、アプリケーションと共にインストールされたコンテンツをアプリケーションサンドボックス以外のサンドボックスに読み込むことができます。非アプリケーションサンドボックス内のコンテンツは、一般的な Web ブラウザーのコンテンツと同様のセキュリティ環境で動作します。例えば、非アプリケーションサンドボックス内のコードは、eval() メ
ソッドおよび関連するメソッドを使用できます（ただし、同時に AIR API にアクセスすることはできません）。ランタイムには、（AIR API を例えば非アプリケーションコンテンツに公開せずに）異なるサンドボックス内のコンテンツが安全に通信できる方法が備えられています。詳しくは、961 ページの「異なるセキュリティサンドボックス内のコンテンツのクロス
スクリプト」を参照してください。
サンドボックスで使用が制限されているコードを呼び出すと、セキュリティ上の理由から、ランタイムは JavaScript エラー「Adobe AIR security violation for JavaScript code in the application security sandbox.」を送出します。
このエラーを回避するには、次節、946 ページの「セキュリティ関連の JavaScript エラーの回避」で説明するコーディングの手法を参照してください。
詳しくは、1043 ページの「Adobe AIR の HTML セキュリティ」を参照してください。

セキュリティ関連の JavaScript エラーの回避
Adobe AIR 1.0 およびそれ以降
セキュリティ制限により、サンドボックスで使用が制限されているコードを呼び出すと、ランタイムは JavaScript エラー「Adobe AIR security violation for JavaScript code in the application security sandbox.」を送出します。このエラーを回避するには、ここで説明するコーディングの手法を参考にしてください。

セキュリティ関連の JavaScript エラーの原因
Adobe AIR 1.0 およびそれ以降
アプリケーションサンドボックスで実行するコードでは、ドキュメントの load イベントが開始し、任意の load イベントハン
ドラーが終了すると、ストリングの評価および実行を伴うほとんどの操作が制限されます。潜在的に安全でないストリングを評価および実行する次のタイプの JavaScript ステートメントの使用を試みると、JavaScript エラーが発生します。

• eval() 関数• setTimeout() および setInterval()• Function コンストラクター
さらに、次のタイプの JavaScript ステートメントは、安全でない JavaScript エラーを発生させずにエラーになります。

• javascript: URL• innerHTML および outerHTML ステートメントの onevent 属性によって割り当てられるイベントコールバック•

アプリケーションインストールディレクトリの外部からの JavaScript ファイルの読み込み• document.write() および document.writeln()• load イベントの前または load イベントハンドラー実行中に同期する XMLHttpRequests•

動的に作成されるスクリプトエレメント

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

947

AIR での HTML および JavaScript のプログラミング

注意：制限されるケースの一部では、ストリングの評価は許可されます。詳しくは、1045 ページの「異なるサンドボッ
クス内のコンテンツに対するコードの制限」を参照してください。
アドビ システムズ社では、アプリケーションセキュリティサンドボックスをサポートする Ajax フレームワークのリスト
を http://www.adobe.com/go/airappsandboxframeworks_jp で管理しています。
以降の節では、アプリケーションサンドボックスで実行するコードについて、安全でない JavaScript エラーおよびメッ
セージを出さない障害を回避するようスクリプトを書き直す方法について説明します。

異なるサンドボックスへのアプリケーションコンテンツのマッピング
Adobe AIR 1.0 およびそれ以降
ほとんどの場合、アプリケーションを書き直したり再構築したりすることで、セキュリティ関連の JavaScript エラーを回避できます。しかし、書き直しまたは再構築時ができない場合には、962 ページの「アプリケーションコンテンツの非アプリ
ケーションサンドボックスへの読み込み」で説明する方法で、アプリケーションコンテンツを別のサンドボックスに読み込めます。該当のコンテンツからも AIR API にアクセスする必要がある場合、963 ページの「サンドボックスブリッジイン
ターフェイスの設定」で説明するようにして、サンドボックスブリッジを作成できます。

eval() 関数
Flash Player 9 以降、Adobe AIR 1.0 以降
アプリケーションサンドボックスでは、eval() 関数は、ページの load イベントの前または load イベントハンドラー実行中にのみ使用できます。ページが読み込まれた後、eval() を呼び出してもコードは実行されません。しかし、次の場合は、コー
ドを書き直すことで eval() の使用を避けることができます。

プロパティのオブジェクトへの割り当て
Adobe AIR 1.0 およびそれ以降
ストリングを解析してプロパティアクセサを構築する次のようなコードにしないでください。
eval("obj." + propName + " = " + val);

次のように角括弧表記でプロパティにアクセスします。
obj[propName] = val;

コンテキストで使用可能な変数を持つ関数の作成
Adobe AIR 1.0 およびそれ以降
次のようなステートメントは、
function compile(var1, var2){
eval("var fn = function(){ this."+var1+"(var2) }");
return fn;}

次のように置き換えます。
function compile(var1, var2){
var self = this;return function(){ self[var1](var2) };}最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

948

AIR での HTML および JavaScript のプログラミング

クラス名をストリングのパラメーターとして使用するオブジェクトの作成
Adobe AIR 1.0 およびそれ以降
次のコードで定義する仮定の JavaScript クラスを考えます。
var CustomClass ={Utils:{
Parser: function(){ alert('constructor') }
},
Data:
{
}
};
var constructorClassName = "CustomClass.Utils.Parser";

インスタンスを最も簡単に作成するには、次のように eval() を使用します。
var myObj;
eval('myObj=new ' + constructorClassName +'()')

しかし、クラス名の各コンポーネントを解析し、角括弧表記を使用して新規のオブジェクトを作成すれば、eval() の呼び出しを避けることができます。
function getter(str){var obj = window;
var names = str.split('.');
for(var i=0;i<names.length;i++){if(typeof obj[names[i]]=='undefined'){var undefstring = names[0];for(var j=1;j<=i;j++)undefstring+="."+names[j];throw new Error(undefstring+" is undefined");}obj = obj[names[i]];}return obj;}

インスタンスを作成するには、次のようにします。
try{var Parser = getter(constructorClassName);
var a = new Parser();}catch(e){alert(e);}setTimeout() および setInterval()
Adobe AIR 1.0 およびそれ以降
関数参照またはオブジェクトと共にハンドラー関数として渡されるストリングを置き換えます。次に例を示します。
setTimeout("alert('Timeout')", 100);

次のように置き換えます。
setTimeout(function(){alert('Timeout')}, 100);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

949

AIR での HTML および JavaScript のプログラミング

または、関数に必要な this オブジェクトが呼び出し元によって設定される場合に、次のようなステートメントを
this.appTimer = setInterval("obj.customFunction();", 100);

次のステートメントに置き換えます。
var _self = this;this.appTimer = setInterval(function(){obj.customFunction.apply(_self);}, 100);

Function コンストラクター
Adobe AIR 1.0 およびそれ以降
new Function(param, body) の呼び出しは、インライン関数宣言に置き換えるか、ページの load イベントの処理が完了する前にのみ使用します。

javascript: URL
Adobe AIR 1.0 およびそれ以降
javascript: URL スキームを使用してリンクに定義されるコードは、アプリケーションサンドボックス内では無視されます。
安全でない JavaScript エラーは生成されません。javascript: URL を使用するリンクを置き換えることができます。次に例を示します。
<a href="javascript:code()">Click Me</a>

次のように置き換えます。
<a href="#" onclick="code()">Click Me</a>innerHTML および outerHTML ステートメントの onevent 属性によって割り当
てられるイベントコールバック
Adobe AIR 1.0 およびそれ以降
innerHTML または outerHTML を使用してドキュメントの DOM にエレメントを追加するとき、onclick またはonmouseover などのステートメント内で割り当てられたイベントコールバックは無視されます。セキュリティエラーは生成されません。代わりに、id 属性を新しいエレメントに割り当て、addEventListener() メソッドを使用してイベントハンドラー
コールバック関数を設定できます。
例えば、次のようなドキュメントのターゲットエレメントがあるとします。
<div id="container"></div>

次のようなステートメントを置き換えます。
document.getElementById('container').innerHTML ='<a href="#" onclick="code()">Click Me.</a>';次のように置き換えます。
document.getElementById('container').innerHTML = '<a href="#" id="smith">Click Me.</a>';document.getElementById('smith').addEventListener("click", function() { code(); });最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

950

AIR での HTML および JavaScript のプログラミング

アプリケーションインストールディレクトリの外部からの JavaScript ファイルの読み込み
Adobe AIR 1.0 およびそれ以降
アプリケーションサンドボックス外部からのスクリプトファイルの読み込みは許可されていません。セキュリティエラーは生成されません。アプリケーションサンドボックス内で実行されるすべてのスクリプトファイルがアプリケーションディレ
クトリにインストールされている必要があります。ページ内で外部スクリプトを使用するには、ページを別のサンドボック
スにマップする必要があります。962 ページの「アプリケーションコンテンツの非アプリケーションサンドボックスへの読み込み」を参照してください。

document.write() および document.writeln()
Adobe AIR 1.0 およびそれ以降
document.write() または document.writeln() の呼び出しは、ページの load イベントの処理が完了した後は無視されます。セキュリティエラーは生成されません。代わりに、新しいファイルを読み込むか、DOM 操作のテクニックを使用してドキュ
メントの body を置き換えることができます。

load イベントの前または load イベントハンドラー実行中に同期する
XMLHttpRequests
Adobe AIR 1.0 およびそれ以降
ページの load イベントまたは load イベントハンドラー実行中に開始された同期の XMLHttpRequests はコンテンツを返しません。非同期の XMLHttpRequests を開始することはできますが、load イベントの後まで制御が戻りません。load イベン
トの処理が完了した後は、同期の XMLHttpRequests は正常に動作します。

動的に作成されるスクリプトエレメント
Adobe AIR 1.0 およびそれ以降
innerHTML や document.createElement() メソッドなどで動的に作成されたスクリプトエレメントは無視されます。

JavaScript からの AIR API クラスのアクセス
Adobe AIR 1.0 およびそれ以降
HTML および JavaScript のコードでは、Webkit の標準的なエレメントおよび拡張されたエレメントに加えて、ランタイムが提供するホストクラスにアクセスできます。これらのクラスによって、AIR が備える次の拡張機能にアクセスできます。

•

ファイルシステムへのアクセス•

ローカル SQL データベースの使用•

アプリケーションのコントロールおよびウィンドウメニュー•

ネットワーキング用ソケットへのアクセス•

ユーザー定義クラスおよびオブジェクトの使用

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

951

AIR での HTML および JavaScript のプログラミング•

サウンド機能
例えば、AIR ファイル API には、flash.filesystem パッケージ内に File クラスが含まれます。JavaScript で次のようにして File オブジェクトを作成できます。
var myFile = new window.runtime.flash.filesystem.File();runtime オブジェクトは、特殊な JavaScript オブジェクトで、アプリケーションサンドボックスの AIR で実行されるHTML コンテンツから使用できます。runtime オブジェクトによって、JavaScript からランタイムクラスにアクセスできます。runtime オブジェクトの flash プロパティによって、flash パッケージにアクセスできます。また、runtime オブ
ジェクトの flash.filesystem プロパティでは、flash.filesystem パッケージにアクセスできます（このパッケージは File ク
ラスを含みます）。パッケージは、ActionScript で使用されるクラスを編成する手段です。
注意：runtime プロパティは、フレームまたはインラインフレームに読み込まれるウィンドウに自動的には追加されません。しかし、子ドキュメントがアプリケーションサンドボックス内にある限り、子は親の runtime プロパティにアクセスできます。
ランタイムクラスのパッケージ構造は、各クラスにアクセスする JavaScript コードストリングの長いストリングを開発者が入力する必要があるので（window.runtime.flash.desktop.NativeApplication など）、AIR SDK には、ランタイムクラスにもっと容易にアクセスできるようにする（例えば、簡単に air.NativeApplication と入力するなど）ための

AIRAliases.js ファイルが含まれています。
AIR API クラスについては、このガイド全体を通じて随所で言及します。HTML 開発に役立つ Flash Player API の他のクラスについては、『HTML 開発者用 Adobe AIR API リファレンスガイド』を参照してください。ActionScript は、SWF（Flash Player）コンテンツで使用される言語です。ただし、JavaScript と ActionScript のシンタックスは似ています（この 2 つは、いずれも ECMAScript 言語を基にしています）。すべてのビルトインクラスが JavaScript（HTMLコンテンツ内）と ActionScript（SWF コンテンツ内）の両方で使用できます。
注意：Dictionary クラス、XML クラスおよび XMLList クラスは、JavaScript コードでは使用できませんが、ActionScript では使用できます。

AIRAliases.js ファイルの使用
Adobe AIR 1.0 およびそれ以降
ランタイムクラスは、次のようなパッケージ構造に編成されます。

• window.runtime.flash.desktop.NativeApplication• window.runtime.flash.desktop.ClipboardManager• window.runtime.flash.filesystem.FileStream• window.runtime.flash.data.SQLDatabase
AIR SDK には、少ない入力でランタイムクラスへのアクセスを可能にする「エイリアス」定義を指定する
AIRAliases.js ファイルが含まれています。例えば、次のように入力するだけで上記のクラスにアクセスできます。

• air.NativeApplication• air.Clipboard• air.FileStream• air.SQLDatabase
これは、AIRAliases.js ファイル内のクラスのほんの一部です。クラスおよびパッケージレベルの関数の完全な一覧については、『HTML 開発者用 Adobe AIR API リファレンスガイド』を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

952

AIR での HTML および JavaScript のプログラミング

AIRAliases.js ファイルには、一般に使用されるランタイムクラスに加えて、よく使用されるパッケージレベルの関数のエイリアスが含まれています。例えば、window.runtime.trace()、window.runtime.flash.net.navigateToURL() および

window.runtime.flash.net.sendToURL() のエイリアスは、air.trace()、air.navigateToURL() および air.sendToURL() です。

AIRAliases.js ファイルを使用するには、HTML ページに次の script 参照が必要です。
<script src="AIRAliases.js"></script>

必要に応じて src 参照のパスを調整します。
重要：特に記載がない限り、このマニュアルの JavaScript サンプルコードは、HTML ページに AIRAliases.js ファイルを組み込むことを想定しています。

AIR での URL について
Adobe AIR 1.0 およびそれ以降
AIR で実行する HTML コンテンツでは、img タグ、frame タグ、iframe タグ、script タグの src 属性の定義で、link タグのhref 属性で、または URL を指定できる任意の場所で、次の URL スキームのいずれかを使用できます。
URL スキーム

説明

例

file

ファイルシステムのルートを基準とした相対的なパス。

file:///c:/AIR Test/test.txt

app

インストールされたアプリケーションのルートディレクトリを基準とした相対的なパス。

app:/images

app-storage

アプリケーション記憶領域ディレクトリを基準とした相対的なパス。AIR では、インストールされたアプリケーションごとに、一app-storage:/settings/prefs.xml

意のアプリケーション記憶領域ディレクトリが定義されます。このディレクトリは、そのアプリケーション固有のデータを格納するための便利な場所として使用できます。

http標準の HTTP リクエスト。

http://www.adobe.com

https

標準の HTTPS リクエスト。

https://secure.example.com

AIR の URL スキームの使用法について詳しくは、784 ページの「URI スキーム」を参照してください。
File クラス、Loader クラス、URLStream クラスおよび Sound クラスなど、AIR API の多くは、URL を含むストリング
ではなく、URLRequest オブジェクトを使用します。URLRequest オブジェクト自体は、同じ URL スキームで使用できるストリングで初期化されます。例えば、次のステートメントは、アドビ システムズ社の Web サイトの要求に使用できる

URLRequest オブジェクトを作成します。
var urlReq = new air.URLRequest("http://www.adobe.com/");URLRequest オブジェクトについて詳しくは、782 ページの「HTTP 通信」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

953

AIR での HTML および JavaScript のプログラミング

JavaScript から使用できる ActionScript オブジェクトの作
成
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトによって読み込まれる HTML ページ内の JavaScript は、HTML ページの window.runtime プ
ロパティ、window.htmlLoader プロパティおよび window.nativeWindow プロパティを使用して ActionScript の実行コンテ
キストに定義されたクラス、オブジェクトおよび関数を呼び出すことができます。JavaScript の実行コンテキスト内にActionScript のオブジェクトと関数への参照を作成することによって、JavaScript コードから使用できる ActionScript のオブジェクトと関数を作成することもできます。

ActionScript から JavaScript オブジェクトにアクセスする基本のサンプル
Adobe AIR 1.0 およびそれ以降
次の例は、ActionScript オブジェクトを参照するプロパティを HTML ページのグローバル window オブジェクトに追加する方法を示しています。
var html:HTMLLoader = new HTMLLoader();var foo:String = "Hello from container SWF."
function helloFromJS(message:String):void {trace("JavaScript says:", message);}var urlReq:URLRequest = new URLRequest("test.html");html.addEventListener(Event.COMPLETE, loaded);
html.load(urlReq);
function loaded(e:Event):void{
html.window.foo = foo;
html.window.helloFromJS = helloFromJS;}

前の例の HTMLLoader オブジェクトに読み込まれる（test.html という名前のファイル内の）HTML コンテンツは、親SWF ファイルに定義された foo プロパティおよび helloFromJS() メソッドにアクセスできます。
<html><script>function alertFoo() {alert(foo);}</script><body><button onClick="alertFoo()">What is foo?
</button><p><button onClick="helloFromJS('Hi.')">
Call helloFromJS() function.
</button></p></body></html>ドキュメントを読み込む JavaScript コンテキストにアクセスするとき、htmlDOMInitialize イベントを使用して、ページに定義された任意のスクリプトからアクセスできるページ構成シーケンスで前もってオブジェクトを作成できます。complete
イベントを待つ場合に、追加されたオブジェクトにアクセスできるのは、ページの load イベントの後で実行されるページ内のスクリプトのみです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

954

AIR での HTML および JavaScript のプログラミング

JavaScript から使用できるクラス定義の作成
Adobe AIR 1.0 およびそれ以降
JavaScript で使用できるアプリケーションの ActionScript クラスを作成するために、読み込まれる HTML コンテンツを、クラス定義を含むアプリケーションドメインに割り当てることができます。JavaScript 実行コンテキストのアプリケーショ
ンドメインは、HTMLLoader オブジェクトの runtimeApplicationDomain プロパティで設定できます。アプリケーションド
メインをプライマリアプリケーションドメインに設定するコードを以下に示します。ここでは、runtimeApplicationDomain
を ApplicationDomain.currentDomain に設定しています。
html.runtimeApplicationDomain = ApplicationDomain.currentDomain;

runtimeApplicationDomain プロパティが設定されると、JavaScript コンテキストは割り当てられたドメインとクラス定義を共有します。JavaScript でカスタムクラスのインスタンスを作成するには、次のようにして window.runtime プロパティを通じてクラス定義を参照し、new 演算子を使用します。
var customClassObject = new window.runtime.CustomClass();

HTML コンテンツは互換性のあるセキュリティドメインのものである必要があります。HTML コンテンツが、割り当てる
アプリケーションドメインとは異なるセキュリティドメインのものである場合、そのページは代わりにデフォルトのアプリ
ケーションドメインを使用します。例えば、インターネットからリモートページを読み込む場合、ページのアプリケーショ
ンドメインとして ApplicationDomain.currentDomain を割り当てることはできません。

イベントリスナーの削除
Adobe AIR 1.0 およびそれ以降
ランタイムオブジェクト、読み込まれた SWF コンテンツ内のオブジェクト、他のページで実行中の JavaScript オブジェク
トなど、現在のページ以外のオブジェクトに JavaScript イベントリスナーを追加する場合、ページの読み込みを解除するときに必ずイベントリスナーを削除する必要があります。そうしないと、イベントリスナーは存在しなくなったハンドラー関数に対してイベントを送出します。この事象が発生すると、「The application attempted to reference a JavaScript object

in an HTML page that is no longer loaded.」というエラーメッセージが表示されます。不要なイベントリスナーを削除す
ると、AIR が関連するメモリを再生することもできます。詳しくは、987 ページの「移動する HTML ページでのイベント
リスナーの削除」を参照してください。

ActionScript からの HTML DOM オブジェクトおよび
JavaScript オブジェクトへのアクセス
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトが complete イベントを送出すると、ページの HTML DOM（ドキュメントオブジェクトモデ
ル）内のすべてのオブジェクトにアクセスできます。アクセス可能なオブジェクトには、表示エレメント（ページの div オ
ブジェクトおよび p オブジェクトなど）および JavaScript の変数と関数があります。complete イベントは、JavaScript ペー
ジの load イベントに対応します。complete イベントが送出されるまでは、DOM エレメント、変数および関数は解析または作成されていない可能性があります。可能であれば、complete イベントを待ってから HTML DOM にアクセスします。
例えば、次のような HTML ページがあるとします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

955

AIR での HTML および JavaScript のプログラミング<html><script>
foo = 333;
function test() {return "OK.";}</script><body><p id="p1">Hi.</p></body></html>この簡単な HTML ページは、foo という名前の JavaScript 変数と test() という名前の JavaScript 関数を定義しています。

2 つとも、ページのグローバル window オブジェクトのプロパティです。また、window.document オブジェクトには、名前付きの P エレメント（ID は p1）が含まれ、getElementById() メソッドを使用してアクセスできます。ページが読み込まれる（HTMLLoader オブジェクトが complete イベントを送出する）と、次に示す ActionScript コードで、ActionScript から各オブジェクトにアクセスできます。
var html:HTMLLoader = new HTMLLoader();
html.width = 300;
html.height = 300;
html.addEventListener(Event.COMPLETE, completeHandler);var xhtml:XML =<html><script>
foo = 333;
function test() {return "OK.";}</script><body><p id="p1">Hi.</p></body></html>;html.loadString(xhtml.toString());
function completeHandler(e:Event):void {trace(html.window.foo); // 333
trace(html.window.document.getElementById("p1").innerHTML); // Hi.
trace(html.window.test()); // OK.
}HTML エレメントのコンテンツにアクセスするには、innerHTML プロパティを使用します。例えば、前のコードでは
html.window.document.getElementById("p1").innerHTML を使用して、p1 という名前の HTML エレメントのコンテンツを取得しています。

ActionScript から HTML ページのプロパティを設定することもできます。例えば、次の例では、ページ上の p1 エレメン
トのコンテンツと foo JavaScript 変数の値を、包含する HTMLLoader オブジェクトへの参照を使用して設定しています。
html.window.document.getElementById("p1").innerHTML = "Goodbye";html.window.foo = 66;

HTML への SWF コンテンツの埋め込み
Adobe AIR 1.0 およびそれ以降
ブラウザーでの埋め込みと同じ方法で、AIR アプリケーション内で HTML コンテンツに SWF コンテンツを埋め込むことができます。SWF コンテンツを埋め込むには、object タグまたは embed タグを使用するか、両方のタグを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

956

AIR での HTML および JavaScript のプログラミング

注意：Web 開発の一般的な方法では、object タグと embed タグの両方を使用して HTML ページ内に SWF コンテンツを表示します。この方法は AIR では利点がありません。AIR では、W3C 標準の object タグを単独で使用してコンテンツを表示できます。同時に、HTML コンテンツをブラウザーにも表示する場合は、必要に応じて object タグと embed タグの両方を使用することもできます。

HTML コンテンツと SWF コンテンツを表示する NativeWindow オブジェクトで透明度を有効にしている場合、コンテンツを埋め込むために使用されるウィンドウモード（wmode）が値 window に設定されているとき、AIR は SWF コンテンツを表示しません。透明ウィンドウの HTML ページで SWF コンテンツを表示するには、wmode パラメーターを opaque または transparent に設定します。wmode のデフォルト値は window なので、値を指定しなかった場合、コンテンツは表示されない可能性があります。
次の例では、HTML の object タグを使用して SWF ファイルを HTML コンテンツ内に表示する方法を示します。基になる
NativeWindow オブジェクトが透明の場合でもコンテンツが表示されるように、wmode パラメーターが opaque に設定されています。SWF ファイルはアプリケーションディレクトリから読み込まれますが、AIR でサポートされている任意の URL
スキームから読み込むことができます。どこから SWF ファイルを読み込むかによって、コンテンツの挿入先のセキュリ
ティサンドボックスが決まります。
<object type="application/x-shockwave-flash" width="100%" height="100%"><param name="movie" value="app:/SWFFile.swf"></param><param name="wmode" value="opaque"></param></object>

スクリプトを使用してコンテンツを動的に読み込むこともできます。次の例では、object ノードを作成して urlString パラ
メーターに指定された SWF ファイルを表示します。この例では、elementID パラメーターによって指定された ID を使用してページエレメントの子としてノードを追加します。
<script>function showSWF(urlString, elementID){var displayContainer = document.getElementById(elementID);var flash = createSWFObject(urlString, 'opaque', 650, 650);
displayContainer.appendChild(flash);}function createSWFObject(urlString, wmodeString, width, height){
var SWFObject = document.createElement("object");
SWFObject.setAttribute("type","application/x-shockwave-flash");SWFObject.setAttribute("width","100%");
SWFObject.setAttribute("height","100%");var movieParam = document.createElement("param");movieParam.setAttribute("name","movie");movieParam.setAttribute("value",urlString);
SWFObject.appendChild(movieParam);
var wmodeParam = document.createElement("param");wmodeParam.setAttribute("name","wmode");wmodeParam.setAttribute("value",wmodeString);
SWFObject.appendChild(wmodeParam);
return SWFObject;}</script>

HTMLLoader オブジェクトが拡大／縮小または回転されている場合、または alpha プロパティが 1.0 以外の値に設定されている場合、SWF コンテンツは表示されません。AIR 1.5.2 より前のバージョンでは、どの wmode 値が設定されていようと、SWF コンテンツは透明ウィンドウに表示されませんでした。
注意：埋め込まれた SWF オブジェクトがビデオファイルなどの外部アセットを読み込もうとすると、ビデオファイルの絶対パスが HTML ファイルで指定されていない場合に SWF コンテンツが正しくレンダリングされないことがあります。ただし、埋め込まれた SWF オブジェクトでは、相対パスを使用して外部イメージファイルを読み込むことができます。
次の例では、HTML コンテンツに埋め込まれた SWF オブジェクトを通じて外部アセットを読み込む方法を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

957

AIR での HTML および JavaScript のプログラミング

var imageLoader;function showSWF(urlString, elementID){var displayContainer = document.getElementById(elementID);
imageLoader = createSWFObject(urlString,650,650);
displayContainer.appendChild(imageLoader);}function createSWFObject(urlString, width, height){
var SWFObject = document.createElement("object");
SWFObject.setAttribute("type","application/x-shockwave-flash");SWFObject.setAttribute("width","100%");
SWFObject.setAttribute("height","100%");var movieParam = document.createElement("param");movieParam.setAttribute("name","movie");movieParam.setAttribute("value",urlString);
SWFObject.appendChild(movieParam);
var flashVars = document.createElement("param");flashVars.setAttribute("name","FlashVars");//Load the asset inside the SWF content.
flashVars.setAttribute("value","imgPath=air.jpg");
SWFObject.appendChild(flashVars);
return SWFObject;}
function loadImage(){
showSWF("ImageLoader.swf", "imageSpot");}

次に示す ActionScript の例では、HTML ファイルによって渡されるイメージのパスが読み取られ、そのイメージがステー
ジに読み込まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

958

AIR での HTML および JavaScript のプログラミング

package{import flash.display.Sprite;
import flash.display.LoaderInfo;
import flash.display.StageScaleMode;
import flash.display.StageAlign;import flash.display.Loader;import flash.net.URLRequest;
public class ImageLoader extends Sprite{
public function ImageLoader(){var flashvars = LoaderInfo(this.loaderInfo).parameters;
if(flashvars.imgPath){var imageLoader = new Loader();var image = new URLRequest(flashvars.imgPath);
imageLoader.load(image);
addChild(imageLoader);imageLoader.x = 0;
imageLoader.y = 0;stage.scaleMode=StageScaleMode.NO_SCALE;
stage.align=StageAlign.TOP_LEFT;}}}}HTML ページ内での ActionScript ライブラリの使用
Adobe AIR 1.0 およびそれ以降
AIR では、コンパイルされた SWF ファイルの ActionScript クラスをページがインポートできるように HTML の script エ
レメントを拡張します。例えば、ルートアプリケーションフォルダーの lib サブディレクトリにある myClasses.swf という名前のライブラリを読み込むには、HTML ファイル内に次の script タグを記述します。
<script src="lib/myClasses.swf" type="application/x-shockwave-flash"></script>

重要：ライブラリが適切に読み込まれるには、type 属性を type="application/x-shockwave-flash" と指定する必要があります。

SWF コンテンツが Flash Player 10 または AIR 1.5 SWF としてコンパイルされる場合、アプリケーション記述ファイルのXML 名前空間を AIR 1.5 名前空間に設定する必要があります。
AIR ファイルをパッケージ化するときには、lib ディレクトリと myClasses.swf ファイルも含める必要があります。
JavaScript Window オブジェクトの runtime プロパティを通じて、読み込まれたクラスにアクセスします。
var libraryObject = new window.runtime.LibraryClass();

SWF ファイル内のクラスをパッケージに編成する場合、パッケージ名も指定する必要があります。例えば、LibraryClass
定義が utilities という名前のパッケージ内にある場合、次のようにしてクラスのインスタンスを作成します。
var libraryObject = new window.runtime.utilities.LibraryClass();

注意：AIR で HTML ページの一部として使用する ActionScript SWF ライブラリをコンパイルするには、acompc コンパイ
ラーを使用します。acompc ユーティリティは、Flex SDK の一部です。詳しくは、Flex SDK ドキュメントを参照してくだ
さい。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

959

AIR での HTML および JavaScript のプログラミング

読み込まれた ActionScript ファイルからの HTML DOM オブジェクトおよび
JavaScript オブジェクトへのアクセス
Adobe AIR 1.0 およびそれ以降<script> タグを使用してページに読み込まれた SWF ファイルの ActionScript から HTML ページのオブジェクトにアクセ
スするには、window や document などの JavaScript オブジェクトへの参照を、ActionScript コードに定義された関数に渡します。JavaScript オブジェクト（または渡された参照からアクセスできる他のオブジェクト）にアクセスする関数内の参照を使用します。
例えば、次のような HTML ページがあるとします。
<html><script src="ASLibrary.swf" type="application/x-shockwave-flash"></script><script>num = 254;
function getStatus() {return "OK.";}
function runASFunction(window){
var obj = new runtime.ASClass();
obj.accessDOM(window);}</script><body onload="runASFunction"><p id="p1">Body text.</p></body></html>この簡単な HTML ページには、num という名前の JavaScript 変数と getStatus() という名前の JavaScript 関数があります。2 つともページの window オブジェクトのプロパティです。また、window.document オブジェクトには名前付きの P エ
レメント（ID は p1）があります。
ページは、ASClass というクラスを含む ActionScript ファイル「ASLibrary.swf」を読み込みます。ASClass には、

JavaScript オブジェクトの値を単純に追跡する accessDOM() という名前の関数が定義されています。accessDOM() メソッド
は、JavaScript Window オブジェクトをパラメーターとして使用します。次の定義に示すように、この Window 参照を使用すると、変数、関数および DOM エレメントなど、ページ内の他のオブジェクトにアクセスできます。
public class ASClass{public function accessDOM(window:*):void {trace(window.num); // 254
trace(window.document.getElementById("p1").innerHTML); // Body text..
trace(window.getStatus()); // OK.
}}

読み込まれた ActionScript クラスから HTML ページのプロパティを取得することも設定することもできます。例えば、次の関数はページ上の p1 エレメントのコンテンツを設定し、ページ上の foo JavaScript 変数の値を設定します。
public function modifyDOM(window:*):void {window.document.getElementById("p1").innerHTML = "Bye";window.foo = 66;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

960

AIR での HTML および JavaScript のプログラミング

Date オブジェクトと RegExp オブジェクトの変換
Adobe AIR 1.0 およびそれ以降
JavaScript 言語と ActionScript 言語はいずれも Date クラスと RegExp クラスを定義していますが、これらの型のオブジェ
クトは 2 つの実行コンテキスト間で自動的に変換されません。Date オブジェクトと RegExp オブジェクトを代わりの実行コンテキストのプロパティまたは関数パラメーターの設定に使用する前に、対応する型に変換する必要があります。
例えば、次の ActionScript コードは、jsDate という名前の JavaScript の Date オブジェクトを ActionScript の Date オブ
ジェクトに変換します。
var asDate:Date = new Date(jsDate.getMilliseconds());

次の ActionScript コードは、jsRegExp という名前の JavaScript の RegExp オブジェクトを ActionScript の RegExp オブジェクトに変換します。
var flags:String = "";if (jsRegExp.dotAll) flags += "s";if (jsRegExp.extended) flags += "x";if (jsRegExp.global) flags += "g";if (jsRegExp.ignoreCase) flags += "i";if (jsRegExp.multiline) flags += "m";var asRegExp:RegExp = new RegExp(jsRegExp.source, flags);

ActionScript からの HTML スタイルシートの操作
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトが complete イベントを送出すると、ページ内の CSS スタイルを調べたり操作したりできます。
例えば、次の簡単な HTML ドキュメントを考えます。
<html><style>.style1A { font-family:Arial; font-size:12px }.style1B { font-family:Arial; font-size:24px }</style><style>.style2 { font-family:Arial; font-size:12px }</style><body><p class="style1A">
Style 1A</p>
<p class="style1B">
Style 1B</p>
<p class="style2">
Style 2</p></body></html>HTMLLoader オブジェクトによってこのコンテンツが読み込まれると、次に示すように window.document.styleSheets 配列の cssRules 配列を通じてページ内の CSS スタイルを操作できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

961

AIR での HTML および JavaScript のプログラミング

var html:HTMLLoader = new HTMLLoader( );var urlReq:URLRequest = new URLRequest("test.html");html.load(urlReq);
html.addEventListener(Event.COMPLETE, completeHandler);function completeHandler(event:Event):void {var styleSheet0:Object = html.window.document.styleSheets[0];styleSheet0.cssRules[0].style.fontSize = "32px";
styleSheet0.cssRules[1].style.color = "#FF0000";
var styleSheet1:Object = html.window.document.styleSheets[1];styleSheet1.cssRules[0].style.color = "blue";styleSheet1.cssRules[0].style.font-family = "Monaco";}

このコードで SCC スタイルが調整された結果の HTML ドキュメントは次のように表示されます。

コードでページにスタイルを追加できるのは、HTMLLoader オブジェクトが complete イベントを送出した後であることに注意してください。

異なるセキュリティサンドボックス内のコンテンツのクロス
スクリプト
Adobe AIR 1.0 およびそれ以降
ランタイムセキュリティモデルでは、発信元が異なるコードを分離します。異なるセキュリティサンドボックス内のコンテ
ンツをクロススクリプトすると、あるセキュリティサンドボックス内のコンテンツから、別のサンドボックス内の選択されたプロパティおよびメソッドにアクセスできるようになります。

AIR セキュリティサンドボックスおよび JavaScript コード
Adobe AIR 1.0 およびそれ以降
AIR では、あるドメインのコードが別のドメインのコンテンツを操作するのを避けるために、同一生成元のポリシーを適用します。すべてのファイルが生成元に基づいたサンドボックス内に配置されます。通常、アプリケーションサンドボックス
内のコンテンツは、同一生成元の原則を破って、アプリケーションインストールディレクトリの外部から読み込まれたコン
テンツをクロススクリプトすることはできません。ただし、AIR には非アプリケーションコンテンツのクロススクリプトを可能にするいくつかのテクニックがあります。
まず、フレームまたはインラインフレームを使用してアプリケーションコンテンツを異なるセキュリティサンドボックスにマップする方法があります。アプリケーションのサンドボックス領域から読み込まれたページは、リモートドメインから読み込まれたページのように動作します。例えば、アプリケーションコンテンツを example.com ドメインにマップすると、そのコンテンツでは example.com から読み込まれたページ間のクロススクリプトを実行できます。
このテクニックはアプリケーションコンテンツを異なるサンドボックスに配置するので、このコンテンツ内のコードは評価されたストリング内のコード実行に関する制限も受けなくなります。このサンドボックスのマッピングを使用すると、リモートコンテンツをクロススクリプトする必要がない場合でも制限を緩和できます。この方法でのコンテンツのマッピング

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

962

AIR での HTML および JavaScript のプログラミング

は、多くの JavaScript フレームワークの中の 1 つを操作する場合や、評価するストリングに依存する既存のコードを操作する場合に特に有用です。ただし、コンテンツがアプリケーションサンドボックスの外部で実行される場合には、信頼できないコンテンツが挿入されて実行される可能性があります。この付加的なリスクに対して、考慮し、防御する必要があります。
同時に、別のサンドボックスにマップされるアプリケーションコンテンツは AIR API へのアクセス権を失うので、サンドボックスのマッピングを使用してアプリケーションサンドボックスの外部で実行されるコードに AIR 機能を公開することはできません。
別のクロススクリプトの方法としては、非アプリケーションサンドボックス内のコンテンツと、アプリケーションサンド
ボックス内のその親ドキュメントの間にサンドボックスブリッジと呼ばれるインターフェイスを作成します。サンドボック
スブリッジを使用すると、親コンテンツが定義したプロパティとメソッドに子コンテンツからアクセスしたり、子コンテンツで定義したプロパティとメソッドに親コンテンツからアクセスしたりできます。
最後の方法として、アプリケーションサンドボックス（および必要に応じて他のサンドボックス）からクロスドメインのXMLHttpRequest を実行できます。
詳しくは、935 ページの「HTML の frame エレメントと iframe エレメント」、1043 ページの「Adobe AIR の HTML セ
キュリティ」および 929 ページの「XMLHttpRequest オブジェクト」を参照してください。

アプリケーションコンテンツの非アプリケーションサンドボックスへの読み込み
Adobe AIR 1.0 およびそれ以降
アプリケーションインストールディレクトリ以外から読み込まれたコンテンツのクロススクリプトをアプリケーションコン
テンツで安全に実行できるようにするには、frame エレメントまたは iframe エレメントを使用して、アプリケーションコン
テンツを外部コンテンツとして同じセキュリティサンドボックスに読み込みます。リモートコンテンツのクロススクリプトは必要ないが、アプリケーションサンドボックス外のアプリケーションのページを読み込む必要がある場合は、元のドメインとして http://localhost/ または問題のない他の値を指定して、同じテクニックを使用できます。

AIR では、frame エレメントに sandboxRoot および documentRoot という新しい属性を追加しています。これにより、フレームに読み込まれるアプリケーションファイルを非アプリケーションサンドボックスにマップするかどうかを指定できます。sandboxRoot URL の下のパスに解決されるファイルは、代わりに documentRoot ディレクトリから読み込まれます。セキュリティのため、この方法で読み込まれるアプリケーションコンテンツは、実際に sandboxRoot URL から読み込まれているかのように扱われます。

sandboxRoot プロパティは、フレームコンテンツを配置するサンドボックスおよびドメインの決定に使用する URL を指定します。file:、http: または https: URL スキームを使用する必要があります。相対的な URL を指定する場合、コンテンツはア
プリケーションサンドボックス内に留まります。
documentRoot プロパティでは、フレームコンテンツの読み込み元のディレクトリを指定します。file:、app: または appstorage: URL スキームを使用する必要があります。
次の例では、アプリケーションの sandbox サブディレクトリにインストールされたコンテンツをマップし、リモートサンド
ボックスおよび www.example.com ドメインで実行します。
<iframesrc="http://www.example.com/local/ui.html"
sandboxRoot="http://www.example.com/local/"documentRoot="app:/sandbox/"></iframe>

ui.html ページでは、次のスクリプトタグを使用してローカル sandbox フォルダーから javascript ファイルを読み込むことができます。
<script src="http://www.example.com/local/ui.js"></script>

また、次のようなスクリプトタグを使用してリモートサーバーのディレクトリからコンテンツを読み込むこともできます。
<script src="http://www.example.com/remote/remote.js"></script>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

963

AIR での HTML および JavaScript のプログラミング

sandboxRoot URL は、リモートサーバー上の同じ URL にあるコンテンツをマスクします。上の例では、AIR によって要求がローカルアプリケーションディレクトリに再マップされるので、www.example.com/local/（またはそのサブディレクトリ）にあるリモートコンテンツにはアクセスできません。要求は、ページナビゲーションからの派生か、XMLHttpRequest からの派生か、コンテンツを読み込む他の手段からの派生かによって、再マップされます。

サンドボックスブリッジインターフェイスの設定
Adobe AIR 1.0 およびそれ以降
アプリケーションサンドボックス内のコンテンツが非アプリケーションサンドボックス内のコンテンツによって定義されたプロパティやメソッドにアクセスする必要がある場合、または非アプリケーションコンテンツがアプリケーションサンド
ボックス内のコンテンツによって定義されたプロパティとメソッドにアクセスする必要がある場合に、サンドボックスブ
リッジを使用できます。子ドキュメントの window オブジェクトの childSandboxBridge プロパティと parentSandboxBridge プ
ロパティを使用してブリッジを作成します。

子サンドボックスブリッジの確立
Adobe AIR 1.0 およびそれ以降
childSandboxBridge プロパティを使用すると、子ドキュメントで親ドキュメント内のコンテンツにインターフェイスを公開できます。インターフェイスを公開するには、childSandbox プロパティを子ドキュメント内の関数またはオブジェクトに設定します。設定すると、親ドキュメント内のコンテンツからオブジェクトまたは関数にアクセスできます。次の例では、子ドキュメントで実行中のスクリプトで、関数とプロパティを 1 つずつ含むオブジェクトをその親に公開する方法を示します。
var interface = {};interface.calculatePrice = function(){return ".45 cents";}
interface.storeID = "abc"window.childSandboxBridge = interface;

この子コンテンツが「子」の ID を割り当てられたインラインフレームに読み込まれていれば、次のようにして、フレームの childSandboxBridge プロパティを読み取ることによって親コンテンツからインターフェイスにアクセスできます。
var childInterface = document.getElementById("child").contentWindow.childSandboxBridge;
air.trace(childInterface.calculatePrice()); //traces ".45 cents"
air.trace(childInterface.storeID)); //traces "abc"親サンドボックスブリッジの確立
Adobe AIR 1.0 およびそれ以降
parentSandboxBridge プロパティを使用すると、親ドキュメントで子ドキュメント内のコンテンツにインターフェイスを公開できます。インターフェイスを公開するには、親ドキュメントで子ドキュメントの parentSandbox プロパティを親ドキュメ
ント内に定義された関数またはオブジェクトに設定します。設定すると、子ドキュメント内のコンテンツからオブジェクト
または関数にアクセスできます。次の例では、親フレームで実行中のスクリプトで、関数を含むオブジェクトを子ドキュメ
ントに公開する方法を示します。
var interface = {};interface.save = function(text){
var saveFile = air.File("app-storage:/save.txt");//write text to file}
document.getElementById("child").contentWindow.parentSandboxBridge = interface;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

964

AIR での HTML および JavaScript のプログラミング

このインターフェイスを使用すると、子フレーム内のコンテンツで、テキストを save.txt という名前のファイルに保存できますが、ファイルシステムに他の方法ではアクセスできません。子コンテンツは、save 関数を次のように呼び出します。
var textToSave = "A string.";
window.parentSandboxBridge.save(textToSave);

アプリケーションコンテンツは、他のサンドボックスにできる限り範囲の狭いインターフェイスを公開する必要があります。
非アプリケーションコンテンツは、偶発的に、または悪意によってコードが挿入される可能性があるので、本来、信頼できないものです。親サンドボックスブリッジによって公開するインターフェイスの誤用を防ぐ適切な安全対策を実施する必要があります。

ページ読み込み時の親サンドボックスブリッジへのアクセス
Adobe AIR 1.0 およびそれ以降
子ドキュメント内のスクリプトから親サンドボックスブリッジにアクセスするには、スクリプトを実行する前にブリッジを設定する必要があります。新しいページの DOM が作成された後で、スクリプトが解析されるか DOM エレメントが追加される前に、ウィンドウ、フレームおよびインラインフレームのオブジェクトは、dominitialize イベントを送出します。

dominitialize イベントを使用して、子ドキュメント内のすべてのスクリプトがアクセスできるページ構成シーケンスで、前もってブリッジを確立できます。
次の例は、子フレームから送出された dominitialize イベントに対応して親サンドボックスブリッジを作成する方法を示しています。
<html><head><script>
var bridgeInterface = {};bridgeInterface.testProperty = "Bridge engaged";function engageBridge(){document.getElementById("sandbox").contentWindow.parentSandboxBridge = bridgeInterface;}</script></head><body><iframe id="sandbox"
src="http://www.example.com/air/child.html"
documentRoot="app:/"sandboxRoot="http://www.example.com/air/"ondominitialize="engageBridge()"/></body></html>次の child.html ドキュメントは、子コンテンツから親サンドボックスブリッジにアクセスする方法を示しています。
<html><head><script>
document.write(window.parentSandboxBridge.testProperty);</script></head><body></body></html>フレームではなく、子ウィンドウ上で dominitialize イベントをリッスンするには、次のようにして、window.open() 関数によって作成された新しい子ウィンドウオブジェクトにリスナーを追加する必要があります。
var childWindow = window.open();childWindow.addEventListener("dominitialize", engageBridge());
childWindow.document.location = "http://www.example.com/air/child.html";

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

965

AIR での HTML および JavaScript のプログラミング

この場合、アプリケーションコンテンツを非アプリケーションサンドボックスにマップする方法はありません。このテクニックは、child.html がアプリケーションディレクトリの外部から読み込まれる場合にのみ有用です。ウィンドウ内のアプリ
ケーションコンテンツを非アプリケーションサンドボックスにマップすることはできますが、フレームを使用して子ドキュ
メントを読み込んで目的のサンドボックスにマップする中間ページを最初に読み込む必要があります。

HTMLLoader クラスの createRootWindow() 関数を使用してウィンドウを作成する場合、新しいウィンドウはcreateRootWindow() の呼び出し元のドキュメントの子ではありません。したがって、呼び出し元ウィンドウから、新しいウィンドウに読み込まれる非アプリケーションコンテンツへのサンドボックスブリッジを作成することはできません。その代わり、フレームを使用して子ドキュメントを読み込む新しいウィンドウ内の中間ページを読み込む必要があります。その後、新しいウィンドウの親ドキュメントから、フレームに読み込まれた子ドキュメントへのブリッジを確立できます。

最終更新日 2015/10/14

966

第 60 章：AIR HTML コンテナのスクリプト作
成
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスは、Adobe® AIR® の HTML コンテンツのコンテナとして機能します。このクラスには、
ActionScript® 3.0 表示リストのオブジェクトの動作や外観を制御するための多数のプロパティとメソッド（Sprite クラスから継承）が用意されています。また、HTML コンテンツの読み込みや操作、履歴管理などのタスクに使用するプロパティとメソッドについても、このクラスで定義します。

HTMLHost クラスは、HTMLLoader の一連のデフォルトの動作を定義します。HTMLLoader オブジェクトを作成しても、HTMLHost の実装は提供されません。そのため、HTML コンテンツによって、ウィンドウ位置やウィンドウタイトルの変更などのデフォルト動作がトリガーされても、何も起こりません。HTMLHost クラスを拡張することで、アプリケー
ションに必要な動作を定義できます。

HTMLHost のデフォルト実装は、AIR で作成された HTML ウィンドウに対して提供されます。HTMLHost のデフォル
ト実装を別の HTMLLoader オブジェクトに割り当てるには、そのオブジェクトの htmlHost プロパティを、defaultBehavior
パラメーターを true に設定して作成した新しい HTMLHost オブジェクトを使用して設定します。
注意：Adobe® Flex™ Framework では、HTMLLoader オブジェクトを mx:HTML コンポーネントでラップします。Flexを使用する場合は、HTML コンポーネントを使用します。

HTMLLoader オブジェクトの表示プロパティ
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトは、Adobe® Flash® Player の Sprite クラスの表示プロパティを継承します。例えば、サイズを変更する、移動する、隠す、背景色を変更するなどの操作を行うことができます。それ以外にも、フィルター、マスク、拡大／縮小、回転などの高度なエフェクトを適用できます。エフェクトを適用する場合は、見やすさへの影響を考慮してください。適用するエフェクトによっては、HTML ページに読み込まれる SWF コンテンツおよび PDF コンテンツを表示できなくなります。

HTML ウィンドウには、HTML コンテンツをレンダリングする HTMLLoader オブジェクトが含まれます。このオブジェ
クトはウィンドウの領域の制約を受けるので、サイズ、位置、回転または拡大／縮小率を変更しても、意図した結果が得られない場合があります。

基本的な表示プロパティ
Adobe AIR 1.0 およびそれ以降
HTMLLoader の基本的な表示プロパティを使用すると、親表示オブジェクト内でのコントロールの位置指定、サイズの設定、コントロールの表示と非表示の切り替えを行うことができます。HTML ウィンドウの HTMLLoader オブジェクトについては、これらのプロパティを変更しないでください。
基本的な表示プロパティを次に示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

967

AIR HTML コンテナのスクリプト作成

プロパティ

注記

x、y

親コンテナ内でのオブジェクトの位置を指定します。

width、height

表示領域のサイズを変更します。

visibleオブジェクトとオブジェクトに含まれるコンテンツを表示するかどうかを指定します。

HTML ウィンドウ外では、HTMLLoader オブジェクトの width プロパティと height プロパティのデフォルト値は 0 です。
読み込んだ HTML コンテンツを表示するには、まず width と height を設定する必要があります。HTML コンテンツは、
HTMLLoader のサイズで描画され、コンテンツの HTML プロパティと CSS プロパティに従ってレイアウトされます。
HTMLLoader のサイズを変更すると、コンテンツが再配置されます。
コンテンツを新しい HTMLLoader オブジェクトに読み込む場合（width は 0 に設定されたまま）、HTMLLoader の表示のwidth と height を contentWidth プロパティと contentHeight プロパティで設定することもできます。このテクニックは、HTML と CSS の配置ルールに従ってレイアウトした場合に、最小幅が十分に確保されるページに対しては有効です。ただし、HTMLLoader によって適正な幅が指定されていないと、ページが細長いレイアウトに配置される場合があります。
注意：他のタイプの表示オブジェクトについても一般的に言えることですが、HTMLLoader オブジェクトの width とheight を変更しても、scaleX と scaleY の値は変化しません。

HTMLLoader コンテンツの透明度
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトの paintsDefaultBackground プロパティは、HTMLLoader オブジェクトで不透明な背景を描画するかどうかを決定するもので、デフォルトで true になっています。paintsDefaultBackground を false にすると、背景が透明になります。表示オブジェクトコンテナまたは HTMLLoader オブジェクトの下に位置するその他の表示オブジェクトは、

HTML コンテンツの前景エレメントの背後に表示されます。
body エレメントまたは HTML ドキュメントのその他のエレメントで背景色を指定（例えば style="background-color:gray"を使用して指定）すると、HTML の該当部分の背景は不透明になり、指定した背景色でレンダリングされます。
HTMLLoader オブジェクトの opaqueBackground プロパティを設定し、paintsDefaultBackground を false にした場合は、
opaqueBackground に設定した色が表示されます。
注意：透明な PNG 形式のグラフィックを使用して、HTML ドキュメント内のエレメントにアルファブレンドの背景を指定できます。HTML エレメントの opacity スタイルの設定はサポートされていません。

HTMLLoader コンテンツの拡大／縮小
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトの拡大／縮小では、拡大／縮小率が 1.0 を超えないようにしてください。HTMLLoader コン
テンツのテキストは特定の解像度でレンダリングされるので、HTMLLoader オブジェクトを拡大するとピクセルが目立つようになります。ウィンドウのサイズが変更されたときに HTMLLoader とそのコンテンツが拡大／縮小されないようにするには、Stage の scaleMode プロパティを StageScaleMode.NO_SCALE に設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

968

AIR HTML コンテナのスクリプト作成

HTML ページに SWF コンテンツまたは PDF コンテンツを読み込む場合の考慮事
項
Adobe AIR 1.0 およびそれ以降
次の場合、HTMLLoader オブジェクトに読み込まれる SWF コンテンツおよび PDF コンテンツは表示されません。

• HTMLLoader オブジェクトを 1.0 以外の倍率に拡大／縮小した場合。
• HTMLLoader オブジェクトの alpha プロパティを 1.0 以外の値に設定した場合。
• HTMLLoader コンテンツを回転した場合。
問題のあるプロパティ設定を削除し、アクティブなフィルターを削除すると、コンテンツが再表示されます。
また、ランタイムでは、透明ウィンドウに PDF コンテンツを表示できません。オブジェクトまたは埋め込みタグの wmode
パラメーターが opaque または transparent に設定されている場合、ランタイムでは HTML ページに埋め込まれた SWF コン
テンツのみが表示されます。wmode のデフォルト値は window なので、wmode パラメーターを明示的に設定しない限り、SWF コンテンツは透明ウィンドウに表示されません。
注意：AIR 1.5.2 より前のバージョンでは、どの wmode 値が使用されていようと、HTML に埋め込まれた SWF が表示されることはありません。

HTMLLoader でこれらのタイプのメディアを読み込む方法について詳しくは、955 ページの「HTML への SWF コンテンツの埋め込み」および 527 ページの「AIR での PDF コンテンツの追加」を参照してください。

高度な表示プロパティ
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスは、特殊エフェクトに使用できるメソッドを複数継承しています。一般に、これらのエフェクトは、
HTMLLoader の表示で使用する場合は制限がありますが、トランジションやその他の一時的なエフェクトに役立ちます。
例えば、ユーザー入力を収集するダイアログウィンドウを表示する場合に、ユーザーがダイアログを閉じるまでメインウィ
ンドウの表示をぼかすことができます。同様に、ウィンドウを閉じるときに表示をフェードアウトさせることもできます。
高度な表示プロパティを次に示します。
プロパティ

制限

alpha

HTML コンテンツが見えにくくなる場合があります。

filters

HTML ウィンドウでは、外部エフェクトはウィンドウの端でクリップされます。

graphics

graphics コマンドを使用して描画されるシェイプは、デフォルトの背景を含め、HTML コンテンツの下に表示されます。描画されたシェイプが表示されるようにするには、paintsDefaultBackground プロパティを false にする必要があります。

opaqueBackground

デフォルトの背景の色は変更されません。このカラーレイヤーが表示されるようにするには、paintsDefaultBackground プロパティを false にする必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

969

AIR HTML コンテナのスクリプト作成

プロパティ

制限

rotation

矩形の HTMLLoader 領域の角が、ウィンドウの端でクリップされることがあります。HTML コンテンツに読み込まれた SWF コンテンツおよび PDF コンテンツは表示されません。

scaleX、scaleY

拡大／縮小率が 1 を超えると、レンダリングされた表示部分のピクセルが目立つようになることがあります。HTML コンテンツに読み込まれた SWF コンテンツお
よび PDF コンテンツは表示されません。

HTML コンテンツが見えにくくなる場合があります。HTML 表示がウィンドウのtransform

端でクリップされることがあります。回転、拡大／縮小または傾斜を伴う変形の場合、HTML コンテンツに読み込まれた SWF コンテンツおよび PDF コンテンツは表示されません。

次の例では、filters 配列を設定して HTML 表示全体をぼかす方法を示します。
var html:HTMLLoader = new HTMLLoader();var urlReq:URLRequest = new URLRequest("http://www.adobe.com/");html.load(urlReq);
html.width = 800;
html.height = 600;
var blur:BlurFilter = new BlurFilter(8);var filters:Array = [blur];html.filters = filters;

HTML コンテンツのスクロール
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスに含まれている次のプロパティを使用すると、HTML コンテンツのスクロールを制御することがで
きます。
プロパティ

説明

contentHeightHTML コンテンツの高さをピクセル単位で指定します。

contentWidth

HTML コンテンツの幅をピクセル単位で指定します。

scrollH

HTMLLoader オブジェクト内の HTML コンテンツの水平スクロール位置を指定します。

scrollV

HTMLLoader オブジェクト内の HTML コンテンツの垂直スクロール位置を指定します。

次のコードでは、HTML コンテンツがページの一番下までスクロールされるように scrollV プロパティを設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

970

AIR HTML コンテナのスクリプト作成

var html:HTMLLoader = new HTMLLoader();
html.addEventListener(Event.HTML_BOUNDS_CHANGE, scrollHTML);
const SIZE:Number = 600;
html.width = SIZE;
html.height = SIZE;var urlReq:URLRequest = new URLRequest("http://www.adobe.com");
html.load(urlReq);
this.addChild(html);
function scrollHTML(event:Event):void{
html.scrollV = html.contentHeight - SIZE;}HTMLLoader には、水平スクロールバーと垂直スクロールバーはありません。スクロールバーは、ActionScript で実装す
るか、Flex コンポーネントを使用して実装できます。Flex HTML コンポーネントには、HTML コンテンツ用のスクロール
バーが自動的に組み込まれます。HTMLLoader.createRootWindow() メソッドを使用して、スクロールバーを備えた

HTMLLoader オブジェクトを含むウィンドウを作成することもできます（980 ページの「スクロールする HTML コンテ
ンツを含むウィンドウの作成」を参照してください）。

HTML 履歴リストへのアクセス
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトに新しいページが読み込まれるとき、ランタイムでは、そのオブジェクトの履歴リストを維持します。履歴リストは、HTML ページの window.history オブジェクトに対応します。HTMLLoader クラスに含まれている
次のプロパティとメソッドを使用すると、HTML 履歴リストを操作することができます。
クラスメンバー説明

historyLength

後方と前方のエントリを含む、履歴リスト全体の長さです。

historyPosition

履歴リストでの現在の位置です。この位置より前の履歴アイテムは「戻る」ナビゲーションを表し、この位置より後の履歴アイテムは「進む」ナビゲーションを表します。

getHistoryAt()

履歴リスト内の指定した位置にある履歴エントリに対応する URLRequest オブジェクトを返します。

historyBack()

可能であれば、履歴リスト内を後方に進みます。

historyForward()

可能であれば、履歴リスト内を前方に進みます。

historyGo()

ブラウザーの履歴内を指定のステップ数だけ移動します。正の場合は前方に、負の場合は後方に移動します。0 の場
合はページが再読み込みされます。終端を超える位置を指定すると、リストの最後に移動します。

履歴リスト内の項目は、HTMLHistoryItem 型のオブジェクトとして格納されます。HTMLHistoryItem クラスには、次のプロパティがあります。
プロパティ

説明

isPostHTML ページに POST データが含まれている場合は true に設定されます。

originalUrl

リダイレクトされる前の HTML ページの元の URL です。

title

HTML ページのタイトルです。

urlHTML ページの URL です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

971

AIR HTML コンテナのスクリプト作成

HTML コンテンツの読み込み時に使用するユーザーエージェ
ントの設定
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスの userAgent プロパティを使用すると、HTMLLoader で使用するユーザーエージェントストリングを設定することができます。HTMLLoader オブジェクトの userAgent プロパティは、load() メソッドを呼び出す前に設定してください。HTMLLoader インスタンスに対してこのプロパティを設定した場合、load() メソッドに渡される
URLRequest の userAgent プロパティは使用されません。
アプリケーションドメインですべての HTMLLoader オブジェクトが使用するデフォルトのユーザーエージェントストリン
グを設定するには、URLRequestDefaults.userAgent プロパティを設定します。静的な URLRequestDefaults プロパティは、
HTMLLoader オブジェクトの load() メソッドで使用される URLRequests だけでなく、すべての URLRequest オブジェク
トのデフォルトとして適用されます。HTMLLoader の userAgent プロパティの設定は、デフォルトのURLRequestDefaults.userAgent 設定をオーバーライドします。

HTMLLoader オブジェクトの userAgent プロパティと URLRequestDefaults.userAgent のどちらにもユーザーエージェント
値を設定していない場合は、デフォルトの AIR ユーザーエージェント値が使用されます。このデフォルト値は、次の 2 つの例に示すように、ランタイムのオペレーティングシステム（Mac OS や Windows など）、ランタイムの言語およびランタイ
ムのバージョンによって異なります。

• "Mozilla/5.0 (Mac OS; U; PPC Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0"• "Mozilla/5.0 (Windows; U; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0"

HTML コンテンツで使用する文字エンコードの設定
Adobe AIR 1.0 およびそれ以降
HTML ページでは、次のように meta タグを含めることによって、使用する文字エンコードを指定できます。
meta http-equiv="content-type" content="text/html" charset="ISO-8859-1";

HTMLLoader オブジェクトの textEncodingOverride プロパティを設定して、特定の文字エンコードが使用されるように
ページ設定をオーバーライドします。
var html:HTMLLoader = new HTMLLoader();
html.textEncodingOverride = "ISO-8859-1";

HTML ページで設定が指定されていない場合に使用する HTMLLoader コンテンツの文字エンコードは、HTMLLoader
オブジェクトの textEncodingFallback プロパティで指定します。
var html:HTMLLoader = new HTMLLoader();
html.textEncodingFallback = "ISO-8859-1";

textEncodingOverride プロパティは、HTML ページでの設定をオーバーライドします。また、textEncodingOverride プロパ
ティと HTML ページでの設定は、textEncodingFallback プロパティをオーバーライドします。

textEncodingOverride プロパティまたは textEncodingFallback プロパティを設定してから、HTML コンテンツを読み込んでください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

972

AIR HTML コンテナのスクリプト作成

HTML コンテンツのブラウザー形式のユーザーインターフェ
イスの定義
Adobe AIR 1.0 およびそれ以降
JavaScript には、HTML コンテンツを表示するウィンドウを制御するための API がいくつか用意されています。AIR では、これらの API はカスタム HTMLHost クラスを実装してオーバーライドできます。

HTMLHost クラスの拡張について
Adobe AIR 1.0 およびそれ以降
例えば、アプリケーションで複数の HTMLLoader オブジェクトをタブ付きインターフェイスに表示する場合、読み込まれた HTML ページによってタイトルを変更する際に、メインウィンドウのタイトルではなく、タブのラベルを変更したい場
合があります。同様に、コードで、window.moveTo() 呼び出しへの応答として、親表示オブジェクトコンテナ内でHTMLLoader オブジェクトの位置を変更したり、HTMLLoader オブジェクトを含むウィンドウを移動したり、何も行わなかったり、まったく別の操作を行ったりすることもできます。

AIR HTMLHost クラスは、次の JavaScript プロパティとメソッドを制御します。

• window.status• window.document.title• window.location• window.blur()• window.close()• window.focus()• window.moveBy()• window.moveTo()• window.open()• window.resizeBy()• window.resizeTo()
new HTMLLoader() を使用して HTMLLoader オブジェクトを作成した場合、上記の JavaScript プロパティまたはメソッド
は有効になりません。HTMLHost クラスは、これらの JavaScript API のデフォルトのブラウザー形式の実装を提供します。HTMLHost クラスを拡張して、動作をカスタマイズすることもできます。デフォルトの動作をサポートする
HTMLHost オブジェクトを作成するには、HTMLHost コンストラクターの defaultBehaviors パラメーターを true に設定します。
var defaultHost:HTMLHost = new HTMLHost(true);

AIR で、HTMLLoader クラスの createRootWindow() メソッドを使用して HTML ウィンドウを作成する場合は、デフォル
トの動作をサポートする HTMLHost インスタンスが自動的に割り当てられます。ホストオブジェクトの動作を変更するには、別の HTMLHost 実装を HTMLLoader の htmlHost プロパティに割り当てます。また、このプロパティに null を割り当てて、機能全体を無効にすることもできます。
注意：AIR では、HTML ベースの AIR アプリケーション用に作成された初期ウィンドウと、JavaScript の window.open()
メソッドのデフォルト実装によって作成されたすべてのウィンドウに、デフォルトの HTMLHost オブジェクトが割り当てられます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

973

AIR HTML コンテナのスクリプト作成

例：HTMLHost クラスの拡張
Adobe AIR 1.0 およびそれ以降
次の例では、HTMLHost クラスを拡張して、HTMLLoader オブジェクトがユーザーインターフェイスに及ぼす影響をカ
スタマイズする方法を示します。

Flex の例：
1 HTMLHost クラスを拡張するクラス（サブクラス）を作成します。
2 新しいクラスのメソッドをオーバーライドして、ユーザーインターフェイス関連の設定の変更を処理します。例えば、次の CustomHost クラスは、window.open() の呼び出しと window.document.title の変更の動作を定義します。

window.open() の呼び出しによって新しいウィンドウで HTML ページを開き、window.document.title の変更（HTMLページの <title> エレメントの設定を含む）によってそのウィンドウのタイトルを設定します。
package{import flash.html.*;
import flash.display.StageScaleMode;
import flash.display.NativeWindow;
import flash.display.NativeWindowInitOptions;public class CustomHost extends HTMLHost{
import flash.html.*;override public function
createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader{
var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();var bounds:Rectangle = new Rectangle(windowCreateOptions.x,
windowCreateOptions.y,
windowCreateOptions.width,
windowCreateOptions.height);
var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions,windowCreateOptions.scrollBarsVisible, bounds);
htmlControl.htmlHost = new HTMLHostImplementation();if(windowCreateOptions.fullscreen){
htmlControl.stage.displayState =StageDisplayState.FULL_SCREEN_INTERACTIVE;}
return htmlControl;}
override public function updateTitle(title:String):void{
htmlLoader.stage.nativeWindow.title = title;}}}

3 HTMLLoader を含むコードで（HTMLHost の新しいサブクラスのコードではなく）、新しいクラスのオブジェクトを作成します。その新しいオブジェクトを HTMLLoader の htmlHost プロパティに割り当てます。次の Flex コードでは、前述の手順で定義した CustomHost クラスを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

974

AIR HTML コンテナのスクリプト作成<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication
xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"
applicationComplete="init()"><mx:Script><![CDATA[
import flash.html.HTMLLoader;import CustomHost;
private function init():void{
var html:HTMLLoader = new HTMLLoader();
html.width = container.width;
html.height = container.height;
var urlReq:URLRequest = new URLRequest("Test.html");html.htmlHost = new CustomHost();html.load(urlReq);
container.addChild(html);}]]></mx:Script><mx:UIComponent id="container" width="100%" height="100%"/></mx:WindowedApplication>

ここで示したコードをテストするには、次のコンテンツを含む HTML ファイルをアプリケーションディレクトリに含めます。
<html><head><title>Test</title></head><script>function openWindow(){
window.runtime.trace("in");document.title = "foo"window.open('Test.html');
window.runtime.trace("out");}</script><body><a href="#" onclick="openWindow()">window.open('Test.html')</a></body></html>Flash Professional の例：
1 AIR の Flash ファイルを作成します。ドキュメントクラスを CustomHostExample に設定し、CustomHostExample.fla としてファイルを保存します。
2 HTMLHost クラスを拡張するクラス（サブクラス）を含む CustomHost.as という ActionScript ファイルを作成します。このクラスは、新しいクラスの特定のメソッドをオーバーライドして、ユーザーインターフェイス関連の設定の変更を処理します。例えば、次の CustomHost クラスは、window.open() の呼び出しと window.document.title の変更の動作を定義します。window.open() メソッドの呼び出しによって新しいウィンドウで HTML ページを開き、
window.document.title プロパティの変更（HTML ページの <title> エレメントの設定を含む）によってそのウィンドウのタイトルを設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

975

AIR HTML コンテナのスクリプト作成

package{import flash.display.StageScaleMode;
import flash.display.NativeWindow;
import flash.display.NativeWindowInitOptions;
import flash.events.Event;import flash.events.NativeWindowBoundsEvent;import flash.geom.Rectangle;
import flash.html.HTMLLoader;import flash.html.HTMLHost;
import flash.html.HTMLWindowCreateOptions;
import flash.text.TextField;
public class CustomHost extends HTMLHost{
public var statusField:TextField;
public function CustomHost(defaultBehaviors:Boolean=true){super(defaultBehaviors);}
override public function windowClose():void{
htmlLoader.stage.nativeWindow.close();}override public function createWindow(
windowCreateOptions:HTMLWindowCreateOptions ):HTMLLoader{
var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();var bounds:Rectangle = new Rectangle(windowCreateOptions.x,
windowCreateOptions.y,
windowCreateOptions.width,
windowCreateOptions.height);
var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions,windowCreateOptions.scrollBarsVisible, bounds);
htmlControl.htmlHost = new HTMLHostImplementation();if(windowCreateOptions.fullscreen){
htmlControl.stage.displayState =StageDisplayState.FULL_SCREEN_INTERACTIVE;}
return htmlControl;}
override public function updateLocation(locationURL:String):void{
trace(locationURL);}
override public function set windowRect(value:Rectangle):void{
htmlLoader.stage.nativeWindow.bounds = value;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

976

AIR HTML コンテナのスクリプト作成}
override public function updateStatus(status:String):void{statusField.text = status;
trace(status);}
override public function updateTitle(title:String):void{
htmlLoader.stage.nativeWindow.title = title + "- Example Application";}override public function windowBlur():void{
htmlLoader.alpha = 0.5;}
override public function windowFocus():void{
htmlLoader.alpha = 1;}}}

3 アプリケーションのドキュメントクラスを格納する CustomHostExample.as という別の ActionScript ファイルを作成します。このクラスは、HTMLLoader オブジェクトを作成し、そのホストプロパティを前述の手順で定義した

CustomHost クラスのインスタンスに設定します。
package{import flash.display.Sprite;
import flash.html.HTMLLoader;import flash.net.URLRequest;
import flash.text.TextField;
public class CustomHostExample extends Sprite{
function CustomHostExample():void{
var html:HTMLLoader = new HTMLLoader();
html.width = 550;
html.height = 380;var host:CustomHost = new CustomHost();html.htmlHost = host;var urlReq:URLRequest = new URLRequest("Test.html");html.load(urlReq);
addChild(html);
var statusTxt:TextField = new TextField();
statusTxt.y = 380;
statusTxt.height = 20;
statusTxt.width = 550;
statusTxt.background = true;
statusTxt.backgroundColor = 0xEEEEEEEE;
addChild(statusTxt);
host.statusField = statusTxt;}}}

ここで示したコードをテストするには、次のコンテンツを含む HTML ファイルをアプリケーションディレクトリに含めます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

977

AIR HTML コンテナのスクリプト作成<html><head><title>Test</title><script>function openWindow(){
document.title = "Test"
window.open('Test.html');}</script></head><body bgColor="#EEEEEE"><a href="#" onclick="window.open('Test.html')">window.open('Test.html')</a><br/><a href="#" onclick="window.document.location='http://www.adobe.com'">
window.document.location = 'http://www.adobe.com'</a><br/><a href="#" onclick="window.moveBy(6, 12)">moveBy(6, 12)</a><br/><a href="#" onclick="window.close()">window.close()</a><br/><a href="#" onclick="window.blur()">window.blur()</a><br/><a href="#" onclick="window.focus()">window.focus()</a><br/><a href="#" onclick="window.status = new Date().toString()">window.status=new
Date().toString()</a></body></html>window.location プロパティの変更の処理
Adobe AIR 1.0 およびそれ以降
locationChange() メソッドをオーバーライドして、HTML ページの URL の変更を処理します。locationChange() メソッド
は、ページの JavaScript で window.location の値を変更するときに呼び出されます。次の例では、要求された URL を読み込んでいます。
override public function updateLocation(locationURL:String):void{
htmlLoader.load(new URLRequest(locationURL));}

注意：HTMLHost オブジェクトの htmlLoader プロパティを使用して、現在の HTMLLoader オブジェクトを参照できます。

window.moveBy()、window.moveTo()、window.resizeTo()、window.resizeBy() の JavaScript 呼び出しの処理
Adobe AIR 1.0 およびそれ以降
set windowRect() メソッドをオーバーライドして、HTML コンテンツの境界の変更を処理します。set windowRect() メソッ
ドは、ページの JavaScript から window.moveBy()、window.moveTo()、window.resizeTo() または window.resizeBy() を呼び出すときに呼び出されます。次の例では、デスクトップウィンドウの境界を更新します。
override public function set windowRect(value:Rectangle):void{
htmlLoader.stage.nativeWindow.bounds = value;}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

978

AIR HTML コンテナのスクリプト作成

window.open() の JavaScript 呼び出しの処理
Adobe AIR 1.0 およびそれ以降
createWindow() メソッドをオーバーライドして、window.open() の JavaScript 呼び出しを処理します。createWindow() メ
ソッドの実装は、新しい HTMLLoader オブジェクトを作成して返します。通常、HTMLLoader は新しいウィンドウに表示しますが、ウィンドウの作成は必須ではありません。
次の例では、createWindow() 関数を HTMLLoader.createRootWindow() で実装し、ウィンドウと HTMLLoader オブジェク
トの両方を作成する方法を示します。NativeWindow オブジェクトを別個に作成し、HTMLLoader をウィンドウステージに追加することもできます。
override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader{var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y,
windowCreateOptions.width, windowCreateOptions.height);
var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions,windowCreateOptions.scrollBarsVisible, bounds);
htmlControl.htmlHost = new HTMLHostImplementation();if(windowCreateOptions.fullscreen){
htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE;}
return htmlControl;}

注意：この例では、window.open() で作成した新しいウィンドウにカスタム HTMLHost 実装を割り当てます。必要に応じて、別の実装を使用したり、新しいウィンドウの htmlHost プロパティを null に設定したりすることもできます。

createWindow() メソッドにパラメーターとして渡されるオブジェクトは HTMLWindowCreateOptions オブジェクトです。HTMLWindowCreateOptions クラスには、features パラメーターストリング（window.open() の呼び出しで使用）の設定値を知らせるプロパティがあります。
HTMLWindowCreateOptions window.open() の JavaScript 呼び出
しにおける features ストリングの対応
プロパティ
する設定

fullscreen

fullscreen

heightheightlocationBarVisible

location

menuBarVisible

menubarresizeable

resizable

scrollBarsVisible

scrollbars

statusBarVisible

statustoolBarVisible

toolbar

width

width

x

left または screenXy

top または screenY

HTMLLoader クラスは、features ストリングで指定できる機能の一部は実装していません。スクロールバー、ロケーショ
ンバー、メニューバー、ステータスバーおよびツールバーは、必要に応じてアプリケーションで用意する必要があります。

JavaScript の window.open() メソッドのその他の引数は、システムによって処理されます。createWindow() の実装では、
HTMLLoader オブジェクトにコンテンツを読み込んだり、ウィンドウタイトルを設定したりしないでください。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

979

AIR HTML コンテナのスクリプト作成

window.close() の JavaScript 呼び出しの処理
Adobe AIR 1.0 およびそれ以降
windowClose() をオーバーライドして、window.close() メソッドの JavaScript 呼び出しを処理します。次の例では、
window.close() メソッドが呼び出されたときにデスクトップウィンドウを閉じます。
override public function windowClose():void{
htmlLoader.stage.nativeWindow.close();}window.close() の JavaScript 呼び出しでは、必ずしもコンテナウィンドウを閉じる必要はありません。例えば、次のコードのように、ウィンドウ（他のコンテンツを含んでいるウィンドウ）を開いたまま、表示リストから HTMLLoader を削除することもできます。
override public function windowClose():void{
htmlLoader.parent.removeChild(htmlLoader);}window.status プロパティの変更の処理
Adobe AIR 1.0 およびそれ以降
updateStatus() メソッドをオーバーライドして、JavaScript による window.status の値の変更を処理します。次の例では、ス
テータス値をトレースします。
override public function updateStatus(status:String):void{
trace(status);}

要求されたステータスが、updateStatus() メソッドにストリングとして渡されます。

HTMLLoader オブジェクトにステータスバーはありません。

window.document.title プロパティの変更の処理
Adobe AIR 1.0 およびそれ以降
updateTitle() メソッドをオーバーライドして、JavaScript による window.document.title の値の変更を処理します。次の例では、ウィンドウタイトルを変更し、「Sample」というストリングをタイトルに追加します。
override public function updateTitle(title:String):void{
htmlLoader.stage.nativeWindow.title = title + " - Sample";}document.title が HTML ページで設定されると、要求されたタイトルが updateTitle() メソッドにストリングとして渡されます。

document.title の変更では、必ずしも HTMLLoader オブジェクトを含むウィンドウのタイトルを変更する必要はありません。例えば、テキストフィールドなど、別のインターフェイスエレメントを変更することもできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

980

AIR HTML コンテナのスクリプト作成

window.blur() と window.focus() の JavaScript 呼び出しの処理
Adobe AIR 1.0 およびそれ以降
windowBlur() メソッドと windowFocus() メソッドをオーバーライドして、window.blur() と window.focus() の JavaScript 呼び出しを処理します。この例を次に示します。
override public function windowBlur():void{
htmlLoader.alpha = 0.5;}
override public function windowFocus():void{
htmlLoader.alpha = 1.0;
NativeApplication.nativeApplication.activate(htmlLoader.stage.nativeWindow);}

注意：AIR には、ウィンドウまたはアプリケーションを非アクティブ化するための API はありません。

スクロールする HTML コンテンツを含むウィンドウの作成
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスには HTMLLoader.createRootWindow() という静的メソッドがあり、このメソッドを使用すると、HTMLLoader オブジェクトを含む新しいウィンドウ（NativeWindow オブジェクトによって表されるウィンドウ）を開き、そのウィンドウのユーザーインターフェイス設定を定義することができます。このメソッドは、ユーザーインターフェ
イスの定義に使用できる 4 つのパラメーターを受け取ります。
パラメーター説明visible

初期状態でウィンドウを表示する（true）か、非表示にする（false）かを指定する Boolean 値です。

windowInitOptions

NativeWindowInitOptions オブジェクトです。NativeWindowInitOptions クラスは、NativeWindow オブ
ジェクトの初期化オプションを定義します。例えば、ウィンドウの最小化、最大化またはサイズ変更が可能かどうか、ウィンドウでシステムクロムまたはカスタムクロムを使用するか、ウィンドウを透明にするかどうか（システ
ムクロムを使用しないウィンドウの場合）や、ウィンドウのタイプなどを指定するオプションがあります。

scrollBarsVisible

スクロールバーを表示する（true）か、表示しない（false）かを指定します。

bounds

新しいウィンドウの位置とサイズを定義する Rectangle オブジェクトです。

例えば、次のコードでは、HTMLLoader.createRootWindow() メソッドを使用して、スクロールバーを使用する

HTMLLoader コンテンツを含むウィンドウを作成します。
var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();var bounds:Rectangle = new Rectangle(10, 10, 600, 400);var html2:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, true, bounds);
var urlReq2:URLRequest = new URLRequest("http://www.example.com");
html2.load(urlReq2);
html2.stage.nativeWindow.activate();

注意：JavaScript で createRootWindow() を直接呼び出すことによって作成されたウィンドウは、そのウィンドウを開いたHTML ウィンドウから独立したままになります。例えば、JavaScript ウィンドウの opener プロパティと parent プロパティ
は null になります。ただし、createRootWindow() を、HTMLHost の createWindow() メソッドをオーバーライドして
createRootWindow() を呼び出すことによって間接的に呼び出した場合には、opener と parent は、そのウィンドウを開いたHTML ウィンドウを参照します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

981

AIR HTML コンテナのスクリプト作成

HTMLLoader クラスのサブクラスの作成
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスのサブクラスを作成して、新しい動作を作成することができます。例えば、HTMLLoader イベント
（HTML がレンダリングされるときや、ユーザーがリンクをクリックしたときに発生するイベントなど）のデフォルトのイ
ベントリスナーを定義するサブクラスを作成できます。
次の例では、HTMLHost クラスを拡張して、JavaScript の window.open() メソッドが呼び出されたときの通常の動作を指定します。その後、カスタム HTMLHost 実装クラスを使用する HTMLLoader のサブクラスを定義します。
package{import flash.html.HTMLLoader;public class MyHTMLHost extends HTMLHost{
public function MyHTMLHost(){
super(false);}
override public function createWindow(opts:HTMLWindowCreateOptions):void{
var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();var bounds:Rectangle = new Rectangle(opts.x, opts.y, opts.width, opts.height);
var html:HTMLLoader = HTMLLoader.createRootWindow(true,
initOptions,opts.scrollBarsVisible,
bounds);html.stage.nativeWindow.orderToFront();
return html}}

次の例では、MyHTMLHost オブジェクトを htmlHost プロパティに割り当てる HTMLLoader クラスのサブクラスを定義します。
package{import flash.html.HTMLLoader;import MyHTMLHost;
import HTMLLoader;public class MyHTML extends HTMLLoader{
public function MyHTML(){
super();
htmlHost = new MyHTMLHost();}}}

HTMLHost クラスと、この例で使用されている HTMLLoader.createRootWindow() メソッドついて詳しくは、972 ページの「HTML コンテンツのブラウザー形式のユーザーインターフェイスの定義」を参照してください。

最終更新日 2015/10/14

982

第 61 章：AIR における HTML 関連イベントの処理
Adobe AIR 1.0 およびそれ以降
イベント処理システムは、ユーザー入力やシステムイベントにプログラムが応答するための便利な仕組みです。Adobe®

AIR® のイベントモデルは、便利なだけでなく、標準に準拠しています。業界標準のイベント処理アーキテクチャであるド
キュメントオブジェクトモデル（DOM）Level 3 Events 仕様に基づいたイベントモデルにより、強力で直感的に使用できるイベント処理ツールが提供されます。

HTMLLoader イベント
Adobe AIR 1.0 およびそれ以降
HTMLLoader オブジェクトは、次の Adobe® ActionScript®3.0 イベントを送出します。
イベント

説明

htmlDOMInitialize

HTML ドキュメントが作成されたとき（ただし、スクリプトが解析される前、またはDOM ノードがページに追加される前）に送出されます。

complete

読み込み操作に対する応答として HTML DOM が作成されたとき（HTML ページのonload イベントの直後）に送出されます。
htmlBoundsChanged

contentWidth および contentHeight プロパティの一方または両方が変更されたときに送出されます。

locationChange

HTMLLoader の location プロパティが変更されたときに送出されます。

locationChanging

ユーザーによるナビゲーション、JavaScript の呼び出しまたはリダイレクトにより、HTMLLoader の location が変更される前に送出されます。locationChanging イベント
は、load()、loadString()、reload()、historyGo()、historyForward() または historyBack()
メソッドの呼び出し時には送出されません。
送出されたイベントオブジェクトの preventDefault() メソッドを呼び出すと、ナビゲー
ションがキャンセルされます。
システムブラウザーでリンクが開いている場合、HTMLLoader は location を変更しない
ので、locationChanging イベントは送出されません。

scrollHTML エンジンがスクロール位置を変更するたびに送出されます。scroll イベントは、ページ内のアンカーリンク（# リンク）への移動、または window.scrollTo() メソッドの呼び出しによって発生します。テキスト入力欄またはテキスト領域にテキストを入力した場
合にも、scroll イベントが発生する可能性があります。

uncaughtScriptException

HTMLLoader で JavaScript 例外が発生し、その例外が JavaScript コードでキャッチされない場合に送出されます。

ActionScript 関数を JavaScript イベント（例えば onClick）について登録する、という方法もあります。詳しくは、983
ページの「ActionScript による DOM イベントの処理」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

983

AIR における HTML 関連イベントの処理

ActionScript による DOM イベントの処理
Adobe AIR 1.0 およびそれ以降
ActionScript 関数を、JavaScript イベントに応答するように登録することができます。例えば、次のような HTML コンテンツがあるとします。
<html><body><a href="#" id="testLink">Click me.</a></html>ActionScript 関数は、ページ内の任意のイベントに対するハンドラーとして登録できます。例えば次のコードは、
clickHandler() 関数を、HTML ページにある testLink エレメントの onclick イベントに対するリスナーとして追加します。
var html:HTMLLoader = new HTMLLoader( );var urlReq:URLRequest = new URLRequest("test.html");html.load(urlReq);
html.addEventListener(Event.COMPLETE, completeHandler);function completeHandler(event:Event):void {html.window.document.getElementById("testLink").onclick = clickHandler;}function clickHandler( event:Object ):void {trace("Event of type: " + event.type );}送出されるイベントオブジェクトは flash.events.Event 型ではなく、どの Event サブクラスにも属していません。Object
クラスを使用して、イベントハンドラー関数の引数に対して型を宣言します。

addEventListener() メソッドを使用することで、これらのイベントについて登録することもできます。例えば、前述のcompleteHandler() メソッドを、次のコードで置き換えることができます。
function completeHandler(event:Event):void {var testLink:Object = html.window.document.getElementById("testLink");
testLink.addEventListener("click", clickHandler);}

リスナーが特定の DOM エレメントを参照する場合には、親 HTMLLoader が complete イベントを送出するまで待機し、送出後にイベントリスナーを追加することをお勧めします。HTML ページは多くの場合、複数のファイルを読み込み、HTML DOM はすべてのファイルが読み込まれて解析されるまで完全には作成されません。HTMLLoader は、すべてのエ
レメントが作成されると、complete イベントを送出します。

キャッチされない JavaScript 例外に対する応答
Adobe AIR 1.0 およびそれ以降
次の HTML について考えてみます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

984

AIR における HTML 関連イベントの処理<html><head><script>function throwError() {var x = 400 * melbaToast;}</script></head><body><a href="#" onclick="throwError()">Click me.</a></html>

この HTML には JavaScript 関数 throwError() が含まれており、この関数は不明な変数 melbaToast を参照しています。
var x = 400 * melbaToast;

JavaScript の操作中に try/catch 構造を持つ JavaScript コードでキャッチされない不正な操作が検出されると、そのページを格納している HTMLLoader オブジェクトは HTMLUncaughtScriptExceptionEvent イベントを送出します。このイベントに対するハンドラーを登録することができます。コード例を次に示します。
var html:HTMLLoader = new HTMLLoader();var urlReq:URLRequest = new URLRequest("test.html");html.load(urlReq);
html.width = container.width;
html.height = container.height;
container.addChild(html);
html.addEventListener(HTMLUncaughtScriptExceptionEvent.UNCAUGHT_SCRIPT_EXCEPTION,
htmlErrorHandler);function htmlErrorHandler(event:HTMLUncaughtJavaScriptExceptionEvent):void{
event.preventDefault();
trace("exceptionValue:", event.exceptionValue)for (var i:int = 0; i < event.stackTrace.length; i++){trace("sourceURL:", event.stackTrace[i].sourceURL);
trace("line:", event.stackTrace[i].line);
trace("function:", event.stackTrace[i].functionName);}}

JavaScript 内では、次の例に示すように、同じイベントを window.htmlLoader プロパティを使用して処理できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

985

AIR における HTML 関連イベントの処理<html><head><script language="javascript" type="text/javascript" src="AIRAliases.js"></script><script>function throwError() {var x = 400 * melbaToast;}function htmlErrorHandler(event) {event.preventDefault();
var message = "exceptionValue:" + event.exceptionValue + "\n";for (var i = 0; i < event.stackTrace.length; i++){message += "sourceURL:" + event.stackTrace[i].sourceURL +"\n";message += "line:" + event.stackTrace[i].line +"\n";message += "function:" + event.stackTrace[i].functionName + "\n";}alert(message);}
window.htmlLoader.addEventListener("uncaughtScriptException", htmlErrorHandler);</script></head><body><a href="#" onclick="throwError()">Click me.</a></html>htmlErrorHandler() イベントハンドラーは、イベントのデフォルトの動作（JavaScript エラーメッセージを AIR トレース出力に送信する）をキャンセルし、独自の出力メッセージを生成します。このメッセージは、
HTMLUncaughtScriptExceptionEvent オブジェクトの exceptionValue の値を出力します。この値は各オブジェクトのプ
ロパティを、次に示す stackTrace 配列として出力します。
exceptionValue: ReferenceError: Can't find variable: melbaToast
sourceURL: app:/test.html
line: 5function: throwError
sourceURL: app:/test.html
line: 10function: onclick

JavaScript を使用したランタイムイベントの処理
Adobe AIR 1.0 およびそれ以降
ランタイムクラスでは、addEventListener() メソッドを使用することで、イベントハンドラーを追加できます。あるイベント
に対するハンドラー関数を追加するには、そのイベントを送出したオブジェクトの addEventListener() メソッドを呼び出し、
イベントタイプと処理関数を指定します。例えば、ユーザーがウィンドウのタイトルバーにある閉じるボタンをクリックしたときに送出される closing イベントをリッスンするには、次のステートメントを使用します。
window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing);

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

986

AIR における HTML 関連イベントの処理

イベントハンドラー関数の作成
Adobe AIR 1.0 およびそれ以降
次のコードでは、メインウィンドウの位置に関する情報を表示する簡単な HTML ファイルを作成します。ハンドラー関数
は moveHandler() という名前で、メインウィンドウの move イベント（NativeWindowBoundsEvent クラスによって定義されています）をリッスンします。
<html><script src="AIRAliases.js" /><script>function init() {writeValues();
window.nativeWindow.addEventListener(air.NativeWindowBoundsEvent.MOVE,
moveHandler);}function writeValues() {document.getElementById("xText").value = window.nativeWindow.x;
document.getElementById("yText").value = window.nativeWindow.y;}function moveHandler(event) {air.trace(event.type); // movewriteValues();}</script><body onload="init()" /><table><tr><td>Window X:</td><td><textarea id="xText"></textarea></td>
</tr>
<tr>
<td>Window Y:</td><td><textarea id="yText"></textarea></td></tr></table></body></html>

ユーザーがウィンドウを移動すると、textarea エレメントにウィンドウの更新された X および Y 位置が表示されます。
イベントオブジェクトが引数として moveHandler() メソッドに渡されています。この event パラメーターにより、ハンド
ラー関数はイベントオブジェクトを確認できます。この例では、イベントオブジェクトの type プロパティを使用して、イベントが move イベントであることを報告しています。

イベントリスナーの削除
Adobe AIR 1.0 およびそれ以降不要になったイベントリスナーを削除するには、removeEventListener() メソッドを使用します。不要になったリスナーは削除することをお勧めします。必須パラメーターには eventName および listener があります。これらは、addEventListener() メ
ソッドの必須パラメーターと同じです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

987

AIR における HTML 関連イベントの処理移動する HTML ページでのイベントリスナーの削除
Adobe AIR 1.0 およびそれ以降
HTML コンテンツを移動する場合、または HTML コンテンツを格納しているウィンドウが閉じられたためにそのコンテンツが破棄される場合、読み込みを解除されたページ上のオブジェクトを参照するイベントリスナーは、自動的には削除されません。オブジェクトが既に読み込みを解除されたハンドラーにイベントを送出すると、「The application attempted toreference a JavaScript object in an HTML page that is no longer loaded.」というエラーメッセージが表示されます。
このエラーを回避するには、HTML ページが読み込みを解除される前に、ページ内の JavaScript イベントリスナーを削除します。（HTMLLoader オブジェクト内での）ページナビゲーションの場合には、イベントリスナーを window オブジェク
トの unload イベントの処理中に削除します。
例えば、次の JavaScript コードでは、uncaughtScriptException イベントをリッスンするイベントリスナーを削除します。
window.onunload = cleanup;
window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException);function cleanup(){
window.htmlLoader.removeEventListener('uncaughtScriptException',
uncaughtScriptExceptionHandler);}

HTML コンテンツを格納したウィンドウを閉じる際にエラーが発生しないようにするには、NativeWindow オブジェクト（window.nativeWindow）の closing イベントに対する応答として、cleanup 関数を呼び出します。例えば、次の JavaScript
コードでは、uncaughtScriptException イベントをリッスンするイベントリスナーを削除します。
window.nativeWindow.addEventListener(air.Event.CLOSING, cleanup);function cleanup(){
window.htmlLoader.removeEventListener('uncaughtScriptException',
uncaughtScriptExceptionHandler);}

また、イベントの処理が 1 回のみの場合、実行後すぐにイベントリスナーを削除することで、このエラーが発生しないようにできます。例えば、次の JavaScript コードでは、HTMLLoader クラスの createRootWindow() メソッドを呼び出し、

complete イベントのイベントリスナーを追加することで、html ウィンドウを作成します。complete イベントハンドラーは、呼び出されると、removeEventListener() 関数を使用して自身のイベントリスナーを削除します。
var html = runtime.flash.html.HTMLLoader.createRootWindow(true);
html.addEventListener('complete', htmlCompleteListener);function htmlCompleteListener(){
html.removeEventListener(complete, arguments.callee)// handler code..
}
html.load(new runtime.flash.net.URLRequest("second.html"));

また、不要なイベントリスナーを削除することで、システムのガベージコレクタは、これらのリスナーに関連付けられていたメモリを再生できます。

既存のイベントリスナーの確認
Adobe AIR 1.0 およびそれ以降
hasEventListener() メソッドを使用することで、あるオブジェクトに関してイベントリスナーが存在しているかどうかを確認することができます。

最終更新日 2015/10/14

988

第 62 章：モバイルアプリケーションでの HTML
コンテンツの表示
Adobe AIR 2.5 以降
StageWebView クラスは、モバイルデバイスではシステムのブラウザーコントロールを、デスクトップコンピューターでは標準の Adobe® AIR® HTMLLoader コントロールを使用して HTML コンテンツを表示します。このクラスが現在のデバイスでサポートされているかどうかを判断するには、StageWebView.isSupported プロパティを確認してください。モバイル
プロファイル内のすべてのデバイスでサポートされているとは限りません。
すべてのプロファイルにおいて、StageWebView クラスがサポートする HTML コンテンツと他のアプリケーションとの間のやり取りは限定されています。ナビゲーションの制御は可能ですが、データのクロススクリプト（直接交換）は許可されていません。ローカルまたはリモートの URL からコンテンツを読み込んだり、HTML のストリングを渡したりすることができます。

StageWebView オブジェクト
StageWebView オブジェクトは表示オブジェクトではないので、表示リストに追加することはできません。代わりに、ス
テージに直接関連付けられたビューポートとして機能します。StageWebView コンテンツは、表示リストのコンテンツの上に描画されます。複数の StageWebView オブジェクトの描画順序を制御する方法はありません。
StageWebView オブジェクトを表示するには、StageWebView の stage プロパティに、オブジェクトを表示するステージを割り当てます。viewPort プロパティを使用して表示サイズを設定します。

viewPort プロパティの x 座標と y 座標には -8192 〜 8191 を設定します。ステージの幅と高さの最大値は 8191 です。サイズがこの最大値を上回ると、例外がスローされます。
次の例では、StageWebView オブジェクトを作成し、stage プロパティと viewPort プロパティを設定して、HTML のスト
リングを表示します。
var webView:StageWebView = new StageWebView();
webView.viewPort = new Rectangle( 0, 0, this.stage.stageWidth, this .stage.stageHeight);
webView.stage = this.stage;
var htmlString:String = "<!DOCTYPE HTML>" +"<html><body>" +"<p>King Philip could order five good steaks.</p>" +"</body></html>";
webView.loadString( htmlString );StageWebView オブジェクトを非表示にするには、その stage プロパティを null に設定します。オブジェクトを完全に破棄するには、dispose() メソッドを呼び出します。dispose() の呼び出しはオプションですが、このメソッドを呼び出すと、オブジェクトですぐに使用するメモリをガベージコレクターで再生できます。

コンテンツ
loadURL() および loadString() という 2 つのメソッドを使用して、StageWebView オブジェクトにコンテンツを読み込むことができます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

989

モバイルアプリケーションでの HTML コンテンツの表示

loadURL() メソッドは、指定された URL にあるリソースを読み込みます。システムの Web ブラウザーコントロールでサポートされている任意の URI スキーム（data:、file:、http:、https:、javascript: など）を使用できます。app: スキームとapp-storage: スキームはサポートされていません。AIR では、URL ストリングの検証は行われません。
loadString() メソッドは、HTML コンテンツを含むリテラルストリングを読み込みます。このメソッドにより読み込まれるページの場所は、次のように表されます。

•

デスクトップ上：about:blank• iOS 上：htmlString• Android 上：エンコードされた htmlString のデータ URI 形式
URI スキームでは、埋め込まれたコンテンツまたはデータを読み込むルールを決定します。
URI スキーム

ローカルリソースの読
み込み

リモートリソースの読み込み

ローカル XMLHttpRequest

リモート XMLHttpRequest

data:

不可

可

不可

不可

file:

可

可

可

可

http:、https:

不可

可

不可

同じドメイン

about:（loadString() 不可

可

不可

不可

メソッド）

注意：ステージの displayState プロパティが FULL_SCREEN に設定されている場合、StageWebView に表示されるテキスト
フィールドに入力することはできません。ただし、iOS と Android では、ステージの displayState が FULL_SCREEN の場合でも StageWebView のテキストフィールドに入力できます。
次の例では、StageWebView オブジェクトを使用して Adobe の Web サイトを表示します。
package {import flash.display.MovieClip;
import flash.media.StageWebView;
import flash.geom.Rectangle;
public class StageWebViewExample extends MovieClip{
var webView:StageWebView = new StageWebView();
public function StageWebViewExample() {webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );webView.loadURL( "http://www.adobe.com" );}}}Android デバイスのアプリケーションでリモートリソースを正常に読み込むには、Android の INTERNET 権限を指定する必要があります。

Android 3.0 以降では、アプリケーションは AIR アプリケーション記述子の Android manifestAdditions エレメントでハードウェアアクセラレーションを有効にして、StageWebView オブジェクト内のプラグインコンテンツを表示する必要があります。「StageWebView オブジェクトでの Flash Player およびその他のプラグインの有効化」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

990

モバイルアプリケーションでの HTML コンテンツの表示

JavaScript URIJavaScript URI を使用して、StageWebView オブジェクトが読み込んだ HTML ページに定義されている関数を呼び出すことができます。JavaScript URI を使用して呼び出す関数は、読み込まれた Web ページのコンテキストで実行されます。
次の例では、StageWebView オブジェクトを使用して JavaScript 関数を呼び出します。
package {import flash.display.*;
import flash.geom.Rectangle;
import flash.media.StageWebView;
public class WebView extends Sprite{
public var webView:StageWebView = new StageWebView();
public function WebView(){
var htmlString:String = "<!DOCTYPE HTML>" +"<html><script type=text/javascript>" +"function callURI(){" +"alert(\"You clicked me!!\");"+"}</script><body>" +"<p><a href=javascript:callURI()>Click Me</a></p>" +"</body></html>";
webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );webView.loadString( htmlString );
}
}
}

関連項目

Sean Voisen：Making the Most of StageWebView

ナビゲーションイベント
ユーザーが HTML 内のリンクをクリックすると、StageWebView オブジェクトは locationChanging イベントを送出します。このイベントオブジェクトの preventDefault() メソッドを呼び出すと、ナビゲーションを停止することができます。それ以外の場合、StageWebView オブジェクトは新しいページに移動して locationChange イベントを送出します。ページの読み込みが完了すると、StageWebView は complete イベントを送出します。

HTML リダイレクトのたびに locationChanging イベントが送出されます。locationChange イベントと complete イベントは
適切なタイミングで送出されます。

iOS では、locationChanging イベントは、最初の loadURL() メソッドまたは loadString() メソッドの場合を除き、
locationChange イベントの前に送出されます。また、locationChange イベントは、iFrame およびフレームのナビゲーションを変更した場合にも送出されます。
次の例は、場所の変更を行わず、代わりにシステムのブラウザーで新しいページを開く方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

991

モバイルアプリケーションでの HTML コンテンツの表示

package {import flash.display.MovieClip;
import flash.media.StageWebView;
import flash.events.LocationChangeEvent;import flash.geom.Rectangle;
import flash.net.navigateToURL;
import flash.net.URLRequest;
public class StageWebViewNavEvents extends MovieClip{
var webView:StageWebView = new StageWebView();
public function StageWebViewNavEvents() {webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );webView.addEventListener( LocationChangeEvent.LOCATION_CHANGING, onLocationChanging );webView.loadURL( "http://www.adobe.com" );}private function onLocationChanging( event:LocationChangeEvent ):void{
event.preventDefault();
navigateToURL( new URLRequest( event.location ) );
}
}
}

ヒストリー
ユーザーが StageWebView オブジェクトに表示されているコンテンツ内のリンクをクリックすると、このコントロールは後方と前方の履歴スタックを保存します。次の例は、2 つの履歴スタック間を移動する方法を示しています。この例では、「Back」および「Search」というソフトキーを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

992

モバイルアプリケーションでの HTML コンテンツの表示

package {import flash.display.MovieClip;
import flash.media.StageWebView;
import flash.geom.Rectangle;
import flash.events.KeyboardEvent;import flash.ui.Keyboard;public class StageWebViewExample extends MovieClip{
var webView:StageWebView = new StageWebView();
public function StageWebViewExample(){
webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );webView.loadURL( "http://www.adobe.com" );stage.addEventListener( KeyboardEvent.KEY_DOWN, onKey );}private function onKey( event:KeyboardEvent ):void{if( event.keyCode == Keyboard.BACK && webView.isHistoryBackEnabled ){trace("back");
webView.historyBack();
event.preventDefault();}
if( event.keyCode == Keyboard.SEARCH && webView.isHistoryForwardEnabled ){trace("forward");webView.historyForward();
}
}
}
}

フォーカス
StageWebView クラスが表示オブジェクトではない場合でも、このクラスには、コントロールに対するフォーカスの切り替えの管理を可能にするメンバーが含まれています。

StageWebView オブジェクトは、フォーカスを取得すると focusIn イベントを送出します。必要に応じて、このイベントを使用してアプリケーション内のフォーカスエレメントを管理します。

StageWebView は、フォーカスを放棄すると focusOut イベントを送出します。StageWebView インスタンスは、ユーザーがデバイスのトラックボールや矢印キーを使用して Web ページ上の先頭または末尾のタブコントロールに移動したときにフォーカスを放棄できます。このイベントオブジェクトの direction プロパティを確認すると、フォーカスのフローがページの下から上なのか上から下なのかを把握することができます。StageWebView の上または下にある適切な表示オブジェクトにフォーカスを割り当てるには、この情報を使用します。

iOS では、フォーカスをプログラムから設定することはできません。StageWebView が focusIn イベントと focusOut イベン
トを、FocusEvent の direction プロパティに none を設定して送出します。ユーザーが StageWebView の内部をタッチすると、focusIn イベントが送出されます。ユーザーが StageWebView の外部をタッチすると、focusOut イベントが送出されます。
次の例は、StageWebView オブジェクトから Flash 表示オブジェクトにフォーカスを渡す方法を示しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

993

モバイルアプリケーションでの HTML コンテンツの表示

package {import flash.display.MovieClip;
import flash.media.StageWebView;
import flash.geom.Rectangle;
import flash.events.KeyboardEvent;import flash.ui.Keyboard;
import flash.text.TextField;
import flash.text.TextFieldType;import flash.events.FocusEvent;import flash.display.FocusDirection;
import flash.events.LocationChangeEvent;public class StageWebViewFocusEvents extends MovieClip{
var webView:StageWebView = new StageWebView();
var topControl:TextField = new TextField();
var bottomControl:TextField = new TextField();
public function StageWebViewFocusEvents(){
trace("Starting");
topControl.type = TextFieldType.INPUT;
addChild( topControl );topControl.height = 60;
topControl.width = stage.stageWidth;
topControl.background = true;
topControl.text = "One control on top.";
topControl.addEventListener( FocusEvent.FOCUS_IN, flashFocusIn );topControl.addEventListener( FocusEvent.FOCUS_OUT, flashFocusOut );webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 60, stage.stageWidth, stage.stageHeight- 120 );
webView.addEventListener( FocusEvent.FOCUS_IN, webFocusIn );webView.addEventListener(FocusEvent.FOCUS_OUT, webFocusOut );webView.addEventListener(LocationChangeEvent.LOCATION_CHANGING,
function( event:LocationChangeEvent ):void{
event.preventDefault();} );webView.loadString("<form action='#'><input/><input/><input/></form>");webView.assignFocus();bottomControl.type = TextFieldType.INPUT;
addChild( bottomControl );bottomControl.y = stage.stageHeight - 60;
bottomControl.height = 60;
bottomControl.width = stage.stageWidth;bottomControl.background = true;bottomControl.text = "One control on the bottom.";bottomControl.addEventListener( FocusEvent.FOCUS_IN, flashFocusIn );bottomControl.addEventListener( FocusEvent.FOCUS_OUT, flashFocusOut );}private function webFocusIn( event:FocusEvent ):void{
trace("Web focus in");}private function webFocusOut( event:FocusEvent ):void{
trace("Web focus out: " + event.direction);if( event.direction == FocusDirection.TOP ){最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

994

モバイルアプリケーションでの HTML コンテンツの表示

stage.focus = topControl;}
else{
stage.focus = bottomControl;}}
private function flashFocusIn( event:FocusEvent ):void{
trace("Flash focus in");var textfield:TextField = event.target as TextField;
textfield.backgroundColor = 0xff5566;}
private function flashFocusOut( event:FocusEvent ):void{
trace("Flash focus out");
var textfield:TextField = event.target as TextField;
textfield.backgroundColor = 0xffffff;}}}

ビットマップキャプチャ
StageWebView オブジェクトは、すべての表示リストコンテンツ上でレンダリングされます。StageWebView オブジェク
ト上にコンテンツを追加することはできません。例えば、StageWebView コンテンツにドロップダウンを拡張することはできません。この問題を解決するには、StageWebView のスナップショットをキャプチャします。その後、StageWebView
を隠し、代わりにビットマップスナップショットを追加します。
次の例は、drawViewPortToBitmapData メソッドを使用して StageWebView オブジェクトのスナップショットをキャプチャする方法を示しています。このメソッドは、ステージに null を設定することによって StageWebView オブジェクトを隠します。Web ページが完全に読み込まれた後に、ビットマップをキャプチャして表示する関数を呼び出します。実行時には、
このコードにより Google と Facebook という 2 つのラベルが表示されます。ラベルをクリックすると対応する Web ページ
がキャプチャされ、これがスナップショットしてステージ上に表示されます。
package{import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.display.Sprite;
import flash.events.*;
import flash.geom.Rectangle;
import flash.media.StageWebView;
import flash.net.*;import flash.text.TextField;
public class stagewebview extends Sprite{
public var webView:StageWebView=new StageWebView();
public var textGoogle:TextField=new TextField();
public var textFacebook:TextField=new TextField();
public function stagewebview(){
textGoogle.htmlText="<b>Google</b>";textGoogle.x=300;
textGoogle.y=-80;

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

995

モバイルアプリケーションでの HTML コンテンツの表示

addChild(textGoogle);
textFacebook.htmlText="<b>Facebook</b>";textFacebook.x=0;
textFacebook.y=-80;
addChild(textFacebook);
textGoogle.addEventListener(MouseEvent.CLICK,goGoogle);
textFacebook.addEventListener(MouseEvent.CLICK,goFaceBook);
webView.stage = this.stage;
webView.viewPort = new Rectangle(0, 0, stage.stageWidth, stage.stageHeight);}
public function goGoogle(e:Event):void{
webView.loadURL("http://www.google.com");
webView.stage = null;
webView.addEventListener(Event.COMPLETE,handleLoad);}public function goFaceBook(e:Event):void{
webView.loadURL("http://www.facebook.com");
webView.stage = null;
webView.addEventListener(Event.COMPLETE,handleLoad);}public function handleLoad(e:Event):void{
var bitmapData:BitmapData = new BitmapData(webView.viewPort.width, webView.viewPort.height);
webView.drawViewPortToBitmapData(bitmapData);
var webViewBitmap:Bitmap=new Bitmap(bitmapData);
addChild(webViewBitmap);}}}

最終更新日 2015/10/14

996

第 63 章：並行処理のためのワーカーの使用Flash Player 11.4 以降、Adobe AIR 13.4 以降（デスクトッププラットフォーム向け）
ActionScript ワーカーを使用すると、コードを並行して実行できます。つまり、メインコードの実行を中断せずに、コードをバックグラウンドで実行できます。

ActionScript 並行処理 API は、Flash Player 11.4 以降および AIR 3.4 以降のデスクトッププラットフォームのみで使用できます。並行処理は、モバイルプラットフォーム向け AIR ではサポートされません。

ワーカーと並行処理についてFlash Player 11.4 以降、Adobe AIR 13.4 以降（デスクトッププラットフォーム向け）
アプリケーションでワーカーを使用しない場合、実行スレッドと呼ばれる、1 本の線状の実行ステップブロック内でアプリ
ケーションのコードが実行されます。スレッドは、開発者が記述したコードを実行します。また、スレッドは、ランタイムに含まれるコードの大部分も実行します。その中で特に重要なのが、表示オブジェクトのプロパティが変更されたときに画面を更新するコードです。コードはメソッドやクラスという一定の単位で記述されますが、実行時には、1 本の長い連続したステップとして記述されたかのように一度に 1 行ずつ実行されます。アプリケーションが実行するステップに関する、次のような仮定の例について考察します。

1 フレーム移動：ランタイムは enterFrame イベントハンドラーを呼び出し、一度に 1 回ずつそのコードを実行します。
2 マウスイベント：ユーザーがマウスを動かして、様々なロールオーバーおよびロールアウトのイベントが発生するのに応じて、ランタイムがマウスイベントハンドラーを呼び出します。

3 ロード完了イベント：URL から XML ファイルをロードするリクエストによって、ロード済みのファイルデータが返されます。呼び出されたイベントハンドラーは、XML コンテンツを読み取り、XML データからオブジェクトのセットを作成するというステップを実行します。

4 マウスイベント：マウスが再度動かされると、ランタイムが関連するマウスイベントハンドラーを呼び出します。
5 レンダリング：その他の待機中のイベントは存在しないので、ランタイムは表示オブジェクトに対する変更内容に基づいて画面を更新します。

6 フレーム移動：このサイクルが繰り返されます。
この例で説明したように、仮定のステップ 1 〜 5 は、フレームと呼ばれる 1 つの時間ブロック内で、順に実行されます。これらのステップが 1 つのスレッドで順に実行されるので、ランタイムは、このプロセスの特定のステップを、別のステップを実行するために中断することはできません。1 秒あたり 30 フレームのフレームレートの場合、これらのすべての処理を実行するためにランタイムに与えられる時間は 1/30 秒未満です。多くの場合、これはコードを実行するために十分な時間であり、残った時間で、ランタイムは単純に待機します。一方、ステップ 3 でロードする XML データが非常に大きく、深い入れ子構造の XML であるとします。この場合、コードでは XML に対するループ処理を実行してオブジェクトを作成するので、その処理を完了するまでに、1/30 秒よりも長い時間がかかる可能性があります。そうなると、その後のステップ（マウスへの反応と画面の再描画）は、想定した時間内に実行されません。そのため、画面がユーザーによるマウスの動作に反応してすぐに再描画されないので、画面がフリーズし、スムーズに進みません。
コード全体を同じスレッドで実行する場合に、ときおりスムーズに進まずフリーズするような状況を避けるための方法は 1つだけあります。それは、大きなデータセットに対するループ処理などの、長時間持続する処理を実行しないことです。これとは異なる解決策を提供するのが ActionScript ワーカーです。ワーカーを使用すると、長時間持続するコードを個別の最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

997

並行処理のためのワーカーの使用

ワーカー内で実行できます。それぞれのワーカーが個別のスレッドで実行され、バックグラウンドワーカーが独自のスレッ
ド内で長時間持続する処理を実行します。そのため、メインワーカーの実行スレッドが解放され、他の作業によってブロックされることなく、フレームごとに画面を再描画できます。
このようにコードの複数の処理を同時に実行できる機能は、並行処理として知られています。バックグラウンドワーカーが自身の作業を完了するか、途中で「進捗」ポイントに達したときに、メインワーカーに通知とデータを送信できます。このようにして、複雑な処理や時間のかかる処理を実行するコードを記述し、一方で画面のフリーズが発生するような粗悪なユーザーエクスペリエンスを防ぐことができます。
レンダリング用のメインスレッドが他のコードによってブロックされることによるフレームレートのドロップの可能性は、
ワーカーを使用して軽減できるので便利です。ただし、ワーカーを使用すると追加のシステムメモリおよび CPU の利用が必要になります。そのため、アプリケーション全体のパフォーマンスに対する負荷が増大する可能性があります。それぞれのワーカーは独自のランタイム仮想マシンのインスタンスを使用するので、小さなワーカーであってもオーバーヘッドが大きくなる場合があります。ワーカーを使用する際には、すべてのターゲットプラットフォーム上でコードをテストし、システムに対して過大な要求が課されないことを確認してください。通常のシナリオで使用するバックグラウンドワーカーは、

1 〜 2 個以内とすることをお勧めします。

ワーカーの作成と管理Flash Player 11.4 以降、Adobe AIR 13.4 以降（デスクトッププラットフォーム向け）
並行処理のためにワーカーを使用する最初の手順は、バックグラウンドワーカーを作成することです。ワーカーを作成するには、2 種類のオブジェクトを使用します。1 つ目は Worker インスタンスです。Worker は作成対象のオブジェクトです。
2 つ目は WorkerDomain オブジェクトです。WorkerDomain は、Worker を作成し、アプリケーション内で実行中のWorker オブジェクトを管理するオブジェクトです。
ランタイムがロードされるときに、WorkerDomain オブジェクトが自動的に作成されます。また、ランタイムによって、アプリケーションのメイン SWF のワーカーも自動的に作成されます。この最初のワーカーは、基本ワーカーと呼ばれます。

WorkerDomain オブジェクトはアプリケーションごとに 1 つのみ存在するので、WorkerDomain インスタンスにアクセ
スするには、静的な WorkerDomain.current プロパティを使用します。
現在の Worker インスタンス（現在実行中のコードが属するワーカー）には、静的な Worker.current プロパティを使用していつでもアクセスできます。

SWF からの Worker オブジェクトの作成
基本ワーカー内部でメイン SWF が実行されるのと同様に、バックグラウンドワーカーで 1 つの SWF ファイルのコードが実行されます。バックグラウンドワーカーを使用するには、ワーカーのコードを SWF ファイルとしてオーサリングし、コ
ンパイルする必要があります。バックグラウンドワーカーを作成するには、親ワーカーで、その SWF ファイルのバイトデータに ByteArray オブジェクトとしてアクセスする必要があります。その ByteArray を WorkerDomain オブジェクトの createWorker() メソッドに渡すことで、実際にワーカーを作成します。
バックグラウンドワーカー ·SWF· を ·ByteArray· オブジェクトとして取得する方法は主に 3 つあります。

ワーカー SWF の埋め込み[Embed] メタタグを使用して、ワーカー SWF を ByteArray としてメイン SWF に埋め込みます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

998

並行処理のためのワーカーの使用[Embed(source="../swfs/BgWorker.swf", mimeType="application/octet-stream")]private static var BgWorker_ByteClass:Class;private function createWorker():void{
var workerBytes:ByteArray = new BgWorker_ByteClass();var bgWorker:Worker = WorkerDomain.current.createWorker(workerBytes);// ... set up worker communication and start the worker}

ワーカー SWF は、BgWorker_ByteClass という名前の ByteArray サブクラスとして、メイン SWF 内部にコンパイルされます。このクラスのインスタンスを作成することで、ワーカー SWF のバイトデータが事前に設定された状態の ByteArrayを取得できます。

外部ワーカー SWF のロード
URLLoader オブジェクトを使用して、外部 SWF ファイルをロードします。この SWF ファイルは、メイン SWF と同じイ
ンターネットドメインからロードした SWF ファイル、AIR アプリケーションパッケージに含まれる SWF ファイルなど、同じセキュリティドメインにある必要があります。
var workerLoader:URLLoader = new URLLoader();
workerLoader.dataFormat = URLLoaderDataFormat.BINARY;
workerLoader.addEventListener(Event.COMPLETE, loadComplete);
workerLoader.load(new URLRequest("BgWorker.swf"));private function loadComplete(event:Event):void{// create the background worker
var workerBytes:ByteArray = event.target.data as ByteArray;var bgWorker:Worker = WorkerDomain.current.createWorker(workerBytes);// ... set up worker communication and start the worker}

URLLoader で SWF ファイルのロードが完了すれば、SWF のバイトデータを URLLoader オブジェクトの data プロパティ（例では event.target.data）で取得できます。

メイン SWF をワーカー SWF として使用
1 つの SWF を、メイン SWF とワーカー SWF の両方として使用できます。メイン表示クラスの loaderInfo.bytes プロパティ
を使用して、SWF のバイトデータにアクセスします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

999

並行処理のためのワーカーの使用// The primordial worker's main class constructor
public function PrimordialWorkerClass(){
init();}
private function init():void{
var swfBytes:ByteArray = this.loaderInfo.bytes;// Check to see if this is the primordial worker or the background worker
if (Worker.current.isPrimordial){// create a background worker
var bgWorker:Worker = WorkerDomain.current.createWorker(swfBytes);// ... set up worker communication and start the worker}
else // entry point for the background worker{// set up communication between workers using getSharedProperty()// ... (not shown)// start the background work}}

このテクニックを使用する場合、メインクラスのコンストラクター内部か、呼び出すメソッド内部で、if 文を使用して SWF
ファイルのコードを分岐します。実行中のコードがメインワーカー内にあるかバックグラウンドワーカー内にあるかを判定するには、例に示すとおり、現在の Worker オブジェクトの isPrimordial プロパティを確認します。

ワーカーの実行の開始
ワーカーの作成後、Worker オブジェクトの start() メソッドを呼び出して、ワーカーのコードの実行を開始します。start()の処理はすぐには開始しません。ワーカーが実行中となっているかを把握するには、Worker オブジェクトの workerState イ
ベントに対するリスナーを登録します。このイベントは、Worker オブジェクトのライフサイクルの状態が切り替わったとき（例えば、コードの実行を開始したとき）に送出されます。workerState イベントハンドラー内で、Worker オブジェクトの state プロパティが WorkerState.RUNNING であるかを確認します。WorkerState.RUNNING となった時点で、ワーカー
は実行中であり、ワーカーのメインクラスのコンストラクターは実行済みの状態です。次のコードに、workerState イベントを登録し、start() メソッドを呼び出す例を示します。
// listen for worker state changes to know when the worker is running
bgWorker.addEventListener(Event.WORKER_STATE, workerStateHandler);// set up communication between workers using// setSharedProperty(), createMessageChannel(), etc.
// ... (not shown)
bgWorker.start();private function workerStateHandler(event:Event):void{if (bgWorker.state == WorkerState.RUNNING){// The worker is running.
// Send it a message or wait for a response.
}}

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1000

並行処理のためのワーカーの使用

ワーカー実行の管理
WorkerDomain クラスの listWorkers() メソッドを使用して、アプリケーション内で実行中のワーカーのセットにいつでもアクセスできます。このメソッドは、state プロパティが WorkerState.RUNNING であるワーカーのセット（基本ワーカーを含む）を返します。開始されていないワーカーや、実行が既に停止したワーカーは含まれません。
ワーカーが必要なくなった場合は、Worker オブジェクトの terminate() メソッドを呼び出してワーカーをシャットダウン
し、メモリやその他のシステムリソースを解放できます。

ワーカー間の通信
Flash Player 11.4 以降、Adobe AIR 13.4 以降（デスクトッププラットフォーム向け）
それぞれのワーカーは個別の実行スレッド内でコードを実行しますが、ワーカーがお互いに完全に分離されているとすると何のメリットもありません。複数のワーカー間での通信は、結局のところ、ワーカー間でのデータの受け渡しを意味します。
あるワーカーのデータを他のワーカーに渡すメカニズムは主に 3 つあります。
これらのデータ共有方法のいずれがデータを渡す際に適切な方法であるかを判断するときには、これらの方法に関する 2 つの主な相違点を考慮してください。第 1 の相違点は、新しいデータが使用可能になったことを受信者に通知するイベントが存在するかどうか、または受信ワーカーが更新をチェックする必要があるかどうかという点です。第 2 の相違点は、データが実際に渡される方法に関連しています。受信ワーカーが共有データのコピーを取得する場合、より多くのオブジェクトが作成され、メモリと CPU サイクルの消費量も増加します。また、基盤となる同一のシステムメモリを参照するオブジェク
トにワーカーがアクセスする場合は、作成されるオブジェクトは少なくなり、全体で使用されるメモリの量も少なくなります。これらの相違点を次にまとめました。
通信方法

データを受信したときにイベントを送出する

ワーカー間でメモリを共有する

ワーカー共有プロ
パティ

不可

不可。オブジェクトは参照ではなく、コピーになります。

MessageChanne 可
l
共有可能な

不可

不可。オブジェクトはは参照ではなく、コピーになります。
可。メモリは共有されます。

ByteArray

共有プロパティを使用したデータの受け渡し
ワーカー間でデータを共有する最も基本的な方法は、共有プロパティを使用することです。それぞれのワーカーで、共有プ
ロパティの値を管理するための内部辞書を保持します。プロパティを区別するために、文字列型のキー名と共にプロパティ
を保存します。ワーカー上でオブジェクトを共有プロパティとして保存するには、Worker オブジェクトの

setSharedProperty() メソッドを、保存するキー名と値という 2 つの引数を指定して呼び出します。
// code running in the parent worker
bgWorker.setSharedProperty("sharedPropertyName", someObject);

共有プロパティの設定後は、Worker オブジェクトの getSharedProperty() メソッドにキー名を渡して呼び出すことで、値を読み取ることができます。
// code running in the background worker
receivedProperty = Worker.current.getSharedProperty("sharedPropertyName");

プロパティ値の読み取りや設定を行うワーカーに関する制約はありません。例えば、バックグラウンドワーカーのコードでsetSharedProperty() メソッドを呼び出して値を保存し、次に、親ワーカーの実行中のコードで getSharedProperty() を使用してデータを取得できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1001

並行処理のためのワーカーの使用

setSharedProperty() メソッドに渡す値では、ほぼすべてのタイプのオブジェクトが許容されます。getSharedProperty() メソッ
ドを呼び出して返されるオブジェクトは、いくつかの特殊なケースを除き、setSharedProperty() に渡したオブジェクトのコ
ピーとなります。同じオブジェクトに対する参照ではありません。データの共有方法に関する詳細は、1002 ページの「共有参照とコピーされた値」で説明しています。
共有プロパティを使用したワーカー間でのデータの受け渡しにおける最大のメリットは、ワーカーの実行前でも共有プロパ
ティを使用できることです。ワーカーの実行前でも、バックグラウンド Worker オブジェクトの setSharedProperty() メソッ
ドを呼び出して共有プロパティを設定できます。親ワーカーで Worker の start() メソッドを呼び出したときに、ランタイム
によって子ワーカーのメインクラスのコンストラクターが呼び出されます。start() が呼び出される前に設定された共有プロ
パティはすべて、子ワーカーのコードで読み取ることができます。

MessageChannel を使用したデータの受け渡し
メッセージチャンネルは、2 つのワーカー間で単方向のデータ受け渡しリンクを確立します。MessageChannel オブジェク
トを使用したワーカー間でのデータ受け渡しには、1 つの重要なメリットがあります。メッセージチャンネルを使用してメッセージ（オブジェクト）を送信する場合、MessageChannel オブジェクトによって channelMessage イベントが送出されます。受信ワーカーのコードでそのイベントをリッスンして、データを取得できるタイミングを把握できます。そのようにした場合、受信ワーカーではデータの更新状況を継続的に確認する必要がありません。
メッセージチャンネルは、送信側と受信側の 2 つのワーカーのみに関連付けられます。MessageChannel オブジェクトを作成するには、送信 Worker オブジェクトの createMessageChannel() メソッドを、受信ワーカーを引数として渡して呼び出します。
// In the sending worker swf
var sendChannel:MessageChannel;
sendChannel = Worker.current.createMessageChannel(receivingWorker);

両方のワーカーから MessageChannel オブジェクトにアクセスできる必要があります。これを実行する最も単純な方法は、

setSharedProperty() メソッドを使用して MessageChannel オブジェクトを渡すことです。
receivingWorker.setSharedProperty("incomingChannel", sendChannel);

受信ワーカーでは、MessageChannel オブジェクトの channelMessage イベントに対するリスナーを登録します。このイベ
ントは、送信ワーカーがメッセージチャンネルを通してデータを送信するときに送出されます。
// In the receiving worker swf
var incomingChannel:MessageChannel;
incomingChannel = Worker.current.getSharedProperty("incomingChannel");incomingChannel.addEventListener(Event.CHANNEL_MESSAGE, handleIncomingMessage);

実際にデータを送信するには、送信ワーカーで、MessageChannel オブジェクトの send() メソッドを呼び出します。
// In the sending worker swf
sendChannel.send("This is a message");

受信ワーカーでは、MessageChannel で channelMessage イベントハンドラーを呼び出します。次に、受信ワーカーで、

MessageChannel オブジェクトの receive() メソッドを呼び出して、データを取得できます。
private function handleIncomingMessage(event:Event):void{
var message:String = incomingChannel.receive() as String;}receive メソッドから返されたオブジェクトは、send() メソッドに渡したオブジェクトと同じデータタイプになります。受信するオブジェクトは、いくつかのデータタイプのオブジェクトを除き、送信側によって渡されたオブジェクトのコピーとなります。送信ワーカー内にあるオブジェクトに対する参照ではありません。詳しくは、1002 ページの「共有参照とコピーされた値」で説明します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1002

並行処理のためのワーカーの使用共有可能な ByteArray を使用したデータの共有
オブジェクトが 2 人のワーカーの間で渡されるとき、受信ワーカーが取得する新しいオブジェクトは元のオブジェクトのコピーです。これにより、2 つのオブジェクトがシステムのメモリ内の異なる場所に格納されることになります。したがって、受信されるオブジェクトの各コピーによって、ランタイムで使用されるメモリの合計量が増加します。また、あるワーカーのオブジェクトに対して行った変更は、他のワーカーが取得したコピーには反映されません。データのコピー方法について
詳しくは、1002 ページの「共有参照とコピーされた値」を参照してください。
デフォルトでは、ByteArray オブジェクトは同じ動作を使用します。Worker オブジェクトの setSharedProperty() メソッド
または MessageChannel オブジェクトの send() メソッドに ByteArray インスタンスを渡す場合、ランタイムによってコンピューターのメモリ内に新しい ByteArray が作成され、受信ワーカーはその新しい ByteArray に対する参照である

ByteArray インスタンスを取得します。ただし、ByteArray オブジェクトの shareable プロパティを true に設定することにより、ByteArray オブジェクトのこの動作を変更することができます。
共有可能な ByteArray オブジェクトが、あるワーカーから他のワーカーへ渡されるとき、受信ワーカーの ByteArray イン
スタンスは、送信ワーカーの ByteArray インスタンスが使用する基盤となるオペレーティングシステムメモリと同じメモリを参照しています。あるワーカーのコードでバイト配列の内容が変更されると、これらの変更は、その共有バイト配列にア
クセスできる他のワーカー側でも直ちに使用できるようになります。
各ワーカーはそれぞれのコードを同時に実行できるので、2 人のワーカーがバイト配列内の同じバイトに同時にアクセスする可能性があります。これにより、データの消失や破損につながる恐れがあります。共有リソースへのアクセスを管理し、こうした問題を回避するために使用できる API がいくつかあります。

ByteArray クラスには、1 つの操作でバイト配列の内容の検証と変更を実行できる次のメソッドがあります。

• atomicCompareAndSwapIntAt() メソッド
• atomicCompareAndSwapLength() メソッド
また、flash.concurrent パッケージには、共有リソースを操作するためのアクセス制御を提供する次のクラスも含まれています。

• Mutex クラス• Condition クラス

共有参照とコピーされた値
通常、Worker.setSharedProperty() または MessageChannel.send() を呼び出して受信ワーカーに渡されるオブジェクトは、AMF 形式で直列化して渡されます。これには次のような重要な点があります。

• getSharedProperty() メソッドの呼び出し時に受信ワーカー内に作成されたオブジェクトは、AMF バイトデータから直列化解除されたものです。これは、オリジナルのオブジェクトのコピーであり、オリジナルのオブジェクトに対する参照ではありません。いずれかのワーカー内のオブジェクトに対して加えられた変更は、他のワーカー内のコピー内には反映さ
れません。

•

表示オブジェクトなど、AMF 形式で直列化できないオブジェクトは、Worker.setSharedProperty() またはMessageChannel.send() を使用してワーカーに渡すことはできません。

•

カスタムクラスを正常に直列化解除するためには、flash.net.registerClassAlias() 関数または [RemoteClass] メタデータを使用してクラス定義を登録する必要があります。両方のワーカーのクラスのバージョンで同じエイリアスを使用する必要があります。

オブジェクトがワーカー間でコピーされるのではなく、本当の意味で共有される特殊なケースが 5 つあります。

• Worker オブジェクト• MessageChannel オブジェクト•

共有可能なバイト配列（shareable プロパティが true になっている ByteArray オブジェクト）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1003

並行処理のためのワーカーの使用• Mutex オブジェクト• Condition オブジェクト
Worker.setSharedProperty() メソッドまたは MessageChannel.send() メソッドを使用してこれらのいずれかのオブジェクトのインスタンスを渡すと、それぞれのワーカーには同じオリジナルのオブジェクトに対する参照が設定されます。あるワー
カー内でインスタンスに変更を加えると、その内容は他のワーカーに即座に反映されます。さらに、これらのいずれかのオ
ブジェクトのインスタンスと同じものを、1 つのワーカーに 2 回以上渡した場合、受信ワーカー内のオブジェクトの新しい
コピーは作成されません。代わりに、同じ参照が再利用されます。

その他のデータ共有テクニック
データの受け渡しに関するワーカー固有のメカニズムに加えて、2 つの SWF アプリケーション間でデータを共有できる既存の API を使用して、ワーカー間でデータをやり取りすることもできます。例えば、次のような方法があります。

•

ローカル共有オブジェクト•

あるワーカー内でファイルにデータを書き込み、別のワーカー内でそのファイルから読み取る方法• SQLite データベースを介してデータの保存と読み取りを行う方法
2 つ以上のワーカー間でリソースを共有する際には、通常、複数のワーカーがそのリソースに同時にアクセスできないようにする必要があります。例えば、ローカルファイルシステム上のファイルに対して複数のワーカーがアクセスすると、データの消失や破損につながる恐れがあり、この操作はオペレーティングシステムによってサポートされない可能性があります。
並行アクセスによる問題を防ぐために、flash.concurrent パッケージに含まれる Mutex および Condition クラスを使用して、共有リソースを操作する際にアクセス制御を行います。
他のデータ共有メカニズムとは異なり、SQLite データベースエンジンは並行アクセスを目的として設計されており、独自のトランザクションサポートが組み込まれています。データ破損のリスクを負うことなく、複数のワーカーが SQLite デー
タベースにアクセスできます。ワーカーはそれぞれ異なる SQLConnection インスタンスを使用するので、各ワーカーは個別のトランザクション内でデータベースにアクセスします。そのため、同時にデータを操作することによって、データの完全性が影響を受けることはありません。
参照項目

689 ページの「AIR を使用したローカル SQL データベースの操作」
flash.concurrent パッケージ

最終更新日 2015/10/14

1004

第 64 章：セキュリティ
Flash Player 9 以降、Adobe AIR 1.0 以降
セキュリティは、Adobe、ユーザー、Web サイト所有者、およびコンテンツ開発者にとって大きな問題です。したがって、

Adobe® Flash® Player および Adobe® AIR™ には、ユーザー、Web サイト所有者およびコンテンツ開発者を保護するための一連のセキュリティルールとコントロールが用意されています。ここでは、別途記載のない限り、ActionScript 3.0 でパブ
リッシュされ Flash Player 9.0.124.0 以降で実行する SWF ファイルと AIR 1.0 以降で実行する SWF、HTML および
JavaScript ファイルのセキュリティモデルについて説明します。
この章の目的はセキュリティの概要を説明することで、あらゆる実装の詳細、使用方法、特定の API を使用する際の問題などについて包括的な説明をするものではありません。Flash Player のセキュリティ概念について詳しくは、Flash Player デ
ベロッパーセンターの「セキュリティ」トピック（www.adobe.com/go/devnet_security_jp）を参照してください。

Flash Platform セキュリティの概要
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player および AIR ランタイムで使用されるセキュリティモデルの大部分は、ロードされた SWF ファイル、HTML、
メディアおよびその他のアセットの元のドメインに基づいています。特定のインターネットドメイン（www.example.comなど）から取得したファイル内の実行可能コードは、常にそのドメインのすべてのデータにアクセスできます。これらのアセットはセキュリティサンドボックスと呼ばれる同じセキュリティグループに配置されます（詳しくは、1006 ページの「セキュリティサンドボックス」を参照してください）。
例えば、SWF ファイルの ActionScript コードでは、ドメイン内の SWF ファイル、ビットマップ、オーディオ、テキスト
ファイルおよびその他のアセットをロードできます。また、ファイルが ActionScript 3.0 で記述されている場合は常に、同じドメインの 2 つの SWF ファイル間でクロススクリプトを行うこともできます。
「クロススクリプト」とは、ファイル内のコードから別のファイルのコードで定義されたプロパティ、メソッドおよびオブジェクトにアクセスする機能です。
しかし、ActionScript 3.0 で記述された SWF ファイルと旧バージョンの ActionScript で記述された SWF ファイルではク
ロススクリプトはサポートされません。この場合は、LocalConnection クラスを使用して通信できます。また、SWF ファ
イルで別のドメインの ActionScript 3.0 SWF ファイルをクロススクリプトして別のドメインからデータをロードする機能
は、デフォルトで禁止されています。ただし、ロードした SWF ファイルで Security.allowDomain() メソッドを呼び出すことで、それらのアクセスを許可できます。詳しくは、1025 ページの「クロススクリプト」を参照してください。
デフォルトでは、次の基本的なセキュリティルールが常に適用されます。

•

同じセキュリティサンドボックス内のリソースは、常に互いにアクセスできます。

•

リモートサンドボックス内にあるファイルの実行可能コードは、ローカルファイルおよびデータにはアクセスできません。

Flash Player および AIR ランタイムでは、次のサイトを個々のドメインと見なし、それぞれに個別のセキュリティサンド
ボックスを設定します。

• http://example.com• http://www.example.com• http://store.example.com• https://www.example.com

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1005

セキュリティ• http://192.0.34.166
http://example.com などの名前付きドメインが http://192.0.34.166 などの特定の IP アドレスに対応している場合も、ランタイムは、それぞれに対して別々のセキュリティサンドボックスを設定します。
開発者が SWF ファイルにそれ自体のサンドボックス以外のサンドボックスのアセットへのアクセスを許可するために使用できる基本的な方法には、次の 2 つがあります。

• Security.allowDomain() メソッド（1017 ページの「作成者（開発者）コントロール」を参照）• URL ポリシーファイル（1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照）
Flash Player および AIR ランタイムのセキュリティモデルでは、コンテンツのロードとデータの抽出またはデータへのアクセスは区別されています。「コンテンツ」は、ランタイムが再生できるビジュアルメディアを含むメディア、オーディオ、ビデオ、または表示メディアを含む SWF ファイルや HTML と定義されます。「データ」は、コードからのみアクセスできる
ものとして定義されます。コンテンツとデータは、それぞれ異なる方法でロードされます。

•

コンテンツのロード - コンテンツは、Loader、Sound、NetStream などのクラスを使用してロードできます。Flex では

MXML タグを介し、AIR アプリケーションでは HTML タグを介します。

•

データの抽出 — ロードしたメディアコンテンツからデータを抽出するには、Bitmap オブジェクト、BitmapData.draw()
メソッド、BitmapData.drawWithQuality() メソッド、Sound.id3 プロパティまたは SoundMixer.computeSpectrum() メソッドを使用します。drawWithQuality メソッドは Flash Player 11.3 以降および AIR 3.3 以降で使用できます。

•

データへのアクセス — URLStream、URLLoader、FileReference、Socket、XMLSocket などのクラスを使用して、外部ファイル（XML ファイルなど）からデータをロードして、データに直接アクセスできます。AIR には、データのロード用に FileStream や XMLHttpRequest などのクラスが追加されています。

Flash Player セキュリティモデルは、コンテンツのロードとデータへのアクセスのために、様々な規則を定義しています。
一般に、コンテンツのロードには、データへのアクセスより制限が少なくなっています。
一般に、コンテンツ（SWF ファイル、ビットマップ、MP3 ファイルおよびビデオ）はどこからでもロードできますが、ロードされる側のコンテンツとロードする側のコードまたはコンテンツのドメインが異なる場合は、別々のセキュリティサ
ンドボックスに分割されます。
コンテンツのロードには、次のような制限があります。

•

デフォルトでは、ローカルの SWF ファイル（ユーザーのハードディスクなどの非ネットワークアドレスからロードされた SWF ファイル）は、local-with-filesystem システムサンドボックスに分類されます。これらのファイルでは、ネットワークからコンテンツをロードできません。詳しくは、1006 ページの「ローカルサンドボックス」を参照してください。

• RTMP（Real-Time Messaging Protocol）サーバーでは、コンテンツへのアクセスを制限することができます。詳しくは、1024 ページの「RTMP サーバーを使用して送信されたコンテンツ」を参照してください。
ロードされたメディアがイメージ、オーディオまたはビデオの場合、セキュリティサンドボックス外部にある SWF ファイ
ルからピクセルデータやサウンドデータなどのデータにアクセスするには、その SWF ファイルのドメインがメディアの元のドメインにある URL ポリシーファイルに含まれている必要があります。詳しくは、1028 ページの「ロードされたメディ
アへのデータとしてのアクセス」を参照してください。
その他のロードされたデータの形態としては、テキストファイルまたは XML ファイルがあり、これらは URLLoader オブジェクトを使用してロードされます。この場合も、別のセキュリティサンドボックスのデータにアクセスするには、元のドメインでの URL ポリシーファイルによって許可が付与されている必要があります。詳しくは、1030 ページの「URLLoader と URLStream の使用」を参照してください。
注意：AIR アプリケーションサンドボックス内で実行するコードがリモートのコンテンツまたはデータをロードする場合、ポリシーファイルは必要ありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1006

セキュリティ

セキュリティサンドボックス
Flash Player 9 以降、Adobe AIR 1.0 以降
クライアントコンピューターは、外部 Web サイト、ローカルファイルシステム、インストールされた AIR アプリケーショ
ンなどの様々なソースから、コード、コンテンツおよびデータが含まれている個々のファイルを取得できます。Flash
Player および AIR ランタイムでは、コードファイルやその他のリソース（共有オブジェクト、ビットマップ、サウンド、
ビデオ、データファイルなど）がロードされると、それらを元の場所に基づいてセキュリティサンドボックスに個別に割り当てます。次の節では、ランタイムで適用される規則について説明します。これらの規則は、任意のサンドボックス内で実行するコードやコンテンツがアクセスできるものを管理します。

Flash Player のセキュリティについて詳しくは、Flash Player デベロッパーセンターの「セキュリティ」トピック（www.adobe.com/go/devnet_security_jp）を参照してください。

リモートサンドボックス
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player および AIR ランタイムでは、インターネットのアセット（SWF ファイルを含む）を元のドメインに対応する
個別のサンドボックスに分類します。例えば、example.com からロードされたアセットは、foo.org からロードされたアセットとは異なるセキュリティサンドボックスに配置されます。デフォルトでは、それらのファイルは、それら自体のサーバーにあるリソースへのアクセスを許可されています。リモート SWF ファイルは、URL ポリシーファイル、
Security.allowDomain() メソッドなどの Web サイトおよび作成者の明示的な許可によって、他のドメインのその他のデータにアクセスできます。詳しくは、1013 ページの「Web サイトのコントロール（ポリシーファイル）」と 1017 ページの「作成者（開発者）コントロール」を参照してください。
リモート SWF ファイルは、ローカルファイルまたはローカルリソースをロードできません。

Flash Player のセキュリティについて詳しくは、Flash Player デベロッパーセンターの「セキュリティ」トピック（www.adobe.com/go/devnet_security_jp）を参照してください。

ローカルサンドボックス
Flash Player 9 以降、Adobe AIR 1.0 以降
ローカルファイルとは、file: プロトコルまたは UNC（Universal Naming Convention）パスを使用して参照されるすべてのファイルを表しています。ローカル SWF ファイルは、次の 4 つのローカルサンドボックスのいずれかに配置されます。

• local-with-filesystem サンドボックス - セキュリティを目的として、Flash Player および AIR ランタイムは、デフォル
トで、すべてのローカルファイルを local-with-file-system サンドボックスに配置します。このサンドボックスから、実行可能コードは（例えば、URLLoader クラスを使用して）ローカルファイルを読み取ることはできますが、ネットワー
クとの通信はできません。その結果、ローカルデータがネットワークに漏れ出したり、不正に共有されたりすることがな
くなります。

• local-with-networking サンドボックス - SWF ファイルをコンパイルする際に、ローカルファイルとして実行される場
合、ネットワークアクセスの許可を指定できます（1009 ページの「ローカル SWF ファイルのサンドボックスタイプの設定」を参照）。これらのファイルは local-with-networking サンドボックスに配置されます。SWF ファイルが localwith-networking サンドボックスに割り当てられると、ローカルファイルへのアクセス権が失われます。代わりに、SWF ファイルはネットワークのデータにアクセスできるようになります。しかし、local-with-networking SWF ファイ
ルは、そのための許可を得ない限り、URL ポリシーファイルを使用するか、Security.allowDomain() メソッドの呼び出しを使用してネットワークからのデータを読み取ることはできません。そのような許可を付与するには、<allow-access-from domain="*"/> または Security.allowDomain("*") を使用して、URL ポリシーファイルですべてのドメインに許可を付

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1007

セキュリティ

与する必要があります。詳しくは、1013 ページの「Web サイトのコントロール（ポリシーファイル）」および 1017
ページの「作成者（開発者）コントロール」を参照してください。

• local-trusted サンドボックス —（ユーザーまたはインストーラープログラムによって）信頼できるファイルとして登録されたローカル SWF ファイルは、local-trusted サンドボックスに配置されます。システム管理者とユーザーは、セキュリティ上の配慮に基づき、local-trusted サンドボックス間でローカル SWF ファイルの再割り当て（移動）も実行できます（1010 ページの「管理ユーザーのコントロール」および 1012 ページの「ユーザーのコントロール」を参照）。localtrusted サンドボックスに割り当てられた SWF ファイルは、他の SWF ファイルと自由に通信したり、どこからでも（リモートでもローカルでも）データをロードしたりすることができます。

• AIR アプリケーションサンドボックス — このサンドボックスには、実行中の AIR アプリケショーンと一緒にインストールされたコンテンツが含まれます。デフォルトでは、AIR アプリケーションサンドボックスで実行するコードは、
任意のドメインのコードをクロススクリプトできます。ただし、AIR アプリケーションサンドボックス外部にあるファイルからは、アプリケーションサンドボックス内のコードをクロススクリプトできません。デフォルトでは、AIR アプ
リケーションサンドボックスのコードとコンテンツは、任意のドメインからコンテンツおよびデータをロードできます。

local-with-networking サンドボックスと local-with-filesystem サンドボックスの間の通信は、local-with-filesystem サ
ンドボックスとリモートサンドボックスの間の通信と同様に、厳しく禁じられています。そのような通信を可能にする許可
を、Flash Player で実行中のアプリケーションまたはユーザーや管理者が付与することはできません。
ローカル HTML ファイルとローカル SWF ファイル間の一方向のみのスクリプト — 例えば、ExternalInterface クラスを使用するには、HTML と SWF の両ファイルを local-trusted サンドボックスに配置する必要があります。その理由は、ブラウザーのローカルセキュリティモデルが Flash Player のローカルセキュリティモデルと異なるからです。

local-with-networking サンドボックス内の SWF ファイルは、local-with-filesystem サンドボックス内の SWF ファイルをロードできません。local-with-filesystem サンドボックス内の SWF ファイルは、local-with-networking サンドボック
ス内の SWF ファイルをロードできません。

AIR アプリケーションサンドボックス
Adobe AIR 1.0 およびそれ以降
Adobe AIR ランタイムでは、「アプリケーション」サンドボックスと呼ばれるサンドボックスが Flash Player セキュリティ
サンドボックスモデルに追加されます。AIR アプリケーションの一部としてインストールされたファイルは、アプリケー
ションサンドボックスにロードされます。アプリケーションがロードするその他のファイルには、通常の Flash Player セ
キュリティモデルで指定されているセキュリティ制限が適用されます。
アプリケーションがインストールされると、AIR パッケージに含まれているすべてのファイルがユーザーのコンピューターのアプリケーションディレクトリにインストールされます。開発者は、app:/ URL スキームを使用してコード内でこのディレクトリを参照できます（784 ページの「URI スキーム」を参照）。アプリケーションの実行時にアプリケーションディレ
クトリツリー内のすべてのファイルがアプリケーションサンドボックスに割り当てられます。アプリケーションサンドボッ
クス内のコンテンツには、ローカルファイルシステムとのやり取りを含め、AIR アプリケーションで使用できる完全な権限が与えられます。

AIR アプリケーションの多くは、ローカルにインストールされたこれらのファイルのみを使用してアプリケーションを実行します。ただし、AIR アプリケーションがアプリケーションディレクトリ内のファイルだけに制限されるわけではなく、どのソースのどの種類のファイルでも読み込むことができます。これにはユーザーのコンピューターのローカルファイルだけ
でなく、ローカルネットワークやインターネットなど使用可能な外部ソースのファイルも含まれます。ファイルの種類はセキュリティ制限に影響しません。読み込まれた HTML ファイルは、同じソースから読み込まれた SWF ファイルと同じセキュリティ権限を持ちます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1008

セキュリティ

アプリケーションセキュリティサンドボックス内のコンテンツは、他のサンドボックス内のコンテンツでは使用できない

AIR API にアクセスできます。例えば、アプリケーションのアプリケーション記述ファイルのコンテンツを返す
air.NativeApplication.nativeApplication.applicationDescriptor プロパティは、アプリケーションセキュリティサンドボックス
内のコンテンツに制限されます。制限される API のもう 1 つの例として FileStream クラスがあります。このクラスには
ローカルファイルシステムに対して読み取りと書き込みを行うためのメソッドが含まれています。
アプリケーションセキュリティサンドボックス内のコンテンツでのみ使用可能な ActionScript API は、『Adobe Flash

Platform 用 ActionScript 3.0 リファレンスガイド』に AIR のロゴ付きで示されています。これらの API を他のサンドボックスで使用すると、ランタイムから SecurityError 例外がスローされます。
HTML コンテンツ（HTMLLoader オブジェクト内）の場合、すべての AIR JavaScript API （AIRAliases.js ファイルを使用するときに、window.runtime プロパティまたは air オブジェクトを通じて使用できる API）は、アプリケーションセ
キュリティサンドボックス内のコンテンツで使用できます。別のサンドボックス内の HTML コンテンツは window.runtime
プロパティにアクセスできないので、AIR API または Flash Player API にアクセスできません。
AIR アプリケーションサンドボックス内で実行するコンテンツには、次に示す追加の制限があります。

•

アプリケーションセキュリティサンドボックス内の HTML コンテンツの場合、コードの読み込み後にストリングを実行可能コードに動的変換できる API の使用について制限があります。これは、アプリケーションで、アプリケーション以
外のソース（潜在的に安全でないネットワークドメインなど）から誤ってコードを挿入（および実行）されないようにするための制限です。例えば、eval() 関数の使用には制限があります。詳しくは、1045 ページの「異なるサンドボックス
内のコンテンツに対するコードの制限」を参照してください。

•

フィッシング攻撃を回避するために、ActionScript の TextField オブジェクト内の HTML コンテンツの img タグは、
アプリケーションセキュリティサンドボックス内の SWF コンテンツでは無視されます。

•

アプリケーションサンドボックス内のコンテンツは、ActionScript 2.0 テキストフィールドの HTML コンテンツのasfunction プロトコルを使用できません。

•

アプリケーションサンドボックス内の SWF コンテンツは、Flash Player 9 アップデート 3 に追加されたクロスドメイン
キャッシュ機能を使用できません。この機能を使用すると、Flash Player は Adobe プラットフォームコンポーネントのコンテンツを永続的にキャッシュし、そのコンテンツを読み込んだ SWF コンテンツでオンデマンドに再利用できます（コンテンツを何度も読み込む必要がありません）。

AIR における JavaScript の制限
Adobe AIR 1.0 およびそれ以降
アプリケーションセキュリティサンドボックスのコンテンツとは異なり、非アプリケーションセキュリティサンドボックスの JavaScript コンテンツは、eval() 関数を呼び出して、動的に生成されたコードをいつでも実行できます。ただし、AIR の
非アプリケーションセキュリティサンドボックス内で実行する JavaScript には制限があります。以下の制限があります。

•

非アプリケーションサンドボックス内の JavaScript コードは、window.runtime オブジェクトにアクセスできないので、

AIR API を実行できません。

•

デフォルトでは、非アプリケーションセキュリティサンドボックス内のコンテンツは、XMLHttpRequest 呼び出しを使用して、その呼び出しを行っているドメイン以外のドメインからデータを読み込むことができません。ただし、コンテンツに含まれるフレームまたはインラインフレームの allowCrossdomainXHR 属性を設定することにより、非アプリケー
ションコンテンツの権限をアプリケーションコードから付与してこの処理を行うことができます。詳しくは、1045 ページの「異なるサンドボックス内のコンテンツに対するコードの制限」を参照してください。

• JavaScript の window.open() メソッドの呼び出しには制限があります。詳しくは、1048 ページの「JavaScript
window.open() メソッドの呼び出しに関する制限」を参照してください。
•

リモート（ネットワーク）セキュリティサンドボックス内の HTML コンテンツは、CSS、frame、iframe および img エ
レメントをリモートドメイン（ネットワーク URL）からのみ読み取ります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1009

セキュリティ

• local-with-filesystem、local-with-networking または local-trusted サンドボックス内の HTML コンテンツは、CSS、
frame、iframe および img エレメントをローカルサンドボックス（アプリケーションまたはネットワーク URL 以外から）からのみ読み込みます。
詳しくは、1045 ページの「異なるサンドボックス内のコンテンツに対するコードの制限」を参照してください。

ローカル SWF ファイルのサンドボックスタイプの設定
Flash Player 9 以降、Adobe AIR 1.0 以降
コンピューターのエンドユーザーまたは管理者は、ローカル SWF ファイルが信頼できることを指定し、ローカルおよび
ネットワークの他のドメインからデータをロードできるようにすることができます。これは、Global Flash Player Trust
ディレクトリおよび User Flash Player Trust ディレクトリで指定します。詳しくは、1010 ページの「管理ユーザーのコント
ロール」および 1012 ページの「ユーザーのコントロール」を参照してください。
ローカルサンドボックスについて詳しくは、1006 ページの「ローカルサンドボックス」を参照してください。

Adobe Flash Professional
local-with-filesystem サンドボックスまたは local-with-networking サンドボックス用の SWF ファイルを構成できます。
そのためには、オーサリングツールでドキュメントのパブリッシュ設定を設定します。

Adobe Flex
local-with-filesystem サンドボックスまたは local-with-networking サンドボックス用の SWF ファイルを構成できます。
そのためには、Adobe Flex コンパイラーで use-network フラグを設定します。詳しくは、Flex 3 アプリケーションの構築と展開の「アプリケーションコンパイラーのオプションについて」を参照してください。

Security.sandboxType プロパティ
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルの作成者は、読み取り専用の静的プロパティ Security.sandboxType を使用して、Flash Player または AIR ラ
ンタイムによって SWF ファイルが割り当てられたサンドボックスのタイプを特定できます。Security クラスは、
Security.sandboxType プロパティに指定できる値を表す次のような定数を含んでいます。

• Security.REMOTE - SWF ファイルはインターネット URL からダウンロードされ、ドメインベースのサンドボックスルー
ルに従って機能します。

• Security.LOCAL_WITH_FILE - SWF ファイルはローカルファイルですが、ユーザーの信頼性はなく、ネットワークを指定してパブリッシュされているわけではありません。この SWF ファイルはローカルデータソースからの読み取りはでき
ますが、インターネットとの通信はできません。

• Security.LOCAL_WITH_NETWORK - SWF ファイルはローカルファイルであり、ユーザーの信頼性はありませんが、
ネットワークを指定してパブリッシュされています。この SWF ファイルはインターネットとのやり取りはできますが、
ローカルデータソースからの読み取りはできません。

• Security.LOCAL_TRUSTED - SWF ファイルはローカルファイルであり、ユーザーの信頼性があり、設定マネージャーまたは Flash Player トラスト構成ファイルを使用します。ローカルのデータソースから読み取ることも、インターネット
でやり取りすることもできます。

• Security.APPLICATION - このファイルは AIR アプリケーションで実行され、そのアプリケーションのパッケージ（AIRファイル）と共にインストールされます。デフォルトでは、AIR アプリケーションサンドボックスのファイルは、任意
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1010

セキュリティ

のドメインのファイルをクロススクリプトできます。ただし、AIR アプリケーションサンドボックス外部にあるファイルからは、AIR ファイルをクロススクリプトできません。デフォルトでは、AIR アプリケーションサンドボックスのファイルは、任意のドメインからコンテンツおよびデータをロードできます。

権限の制御Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player クライアントランタイムのセキュリティモデルは、SWF ファイル、ローカルデータ、インターネット URL な
どのオブジェクトであるリソースに基づいて設計されています。ステークホルダーは、これらのリソースの所有者または使用者です。ステークホルダーはそのリソースを管理（セキュリティ設定）できます。また、各リソースにはステークホル
ダーが 4 つあります。次の図に示すように、Flash Player ではこれらの管理の権限階層が厳密に適用されます。
管理者(ユーザー制度)設定

ユーザー設定Web サイト設定

作者設定

セキュリティ管理の階層

これは、例えば管理者がリソースへのアクセスを制限した場合、他のステークホルダーはこの制限をオーバーライドすることはできないことを示します。

AIR アプリケーションでは、これらのアクセス制御は AIR アプリケーションサンドボックスの外部で実行するコンテンツに対してのみ適用されます。

管理ユーザーのコントロール
Flash Player 9 以降、Adobe AIR 1.0 以降
コンピューターの管理ユーザー（管理者権限でログインするユーザー）は、そのコンピューターの全ユーザーに有効なFlash Player セキュリティ設定を適用できます。家庭用コンピューターなど、エンタープライズ以外の環境では、管理者権限も持つユーザーは通常 1 人です。エンタープライズ環境でも、個々のユーザーが管理者権限を持つ場合があります。
管理ユーザーのコントロールには次の 2 種類があります。

• mms.cfg ファイル
• Global Flash Player Trust ディレクトリ

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1011

セキュリティ

mms.cfg ファイル
Flash Player 9 以降、Adobe AIR 1.0 以降
mms.cfg ファイルは、様々な機能へのアクセスを許可または制限するために管理者が使用できるテキストファイルです。
Flash Player が起動すると、このファイルからセキュリティ設定を読み取り、機能を制限するために使用します。mms.cfg
ファイルには、プライバシー制御、ローカルファイルセキュリティ、ソケット接続などの機能を管理するために管理者が使用する設定が含まれています。

SWF ファイルは、Capabilities.avHardwareDisable および Capabilities.localFileReadDisable プロパティを呼び出すことにより、無効化されている機能に関する一部の情報にアクセスできます。ただし、mms.cfg ファイルのほとんどの設定は、AcrionScript から照会できません。
コンピューターのセキュリティとプライバシーに関するセキュリティを、アプリケーションから独立して適用するには、シ
ステム管理者のみが mms.cfg ファイルを変更する必要があります。mms.cfg ファイルは、アプリケーションインストーラーが使用するためのものではありません。管理権限のあるユーザーが実行しているインストーラーは、mms.cfg ファイルの内容を変更できますが、アドビ システムズ社では、そのような使用状況はユーザーの信頼を裏切るものであると考えており、
インストーラーの作成者に mms.cfg ファイルを決して変更しないように強く要請しています。

mms.cfg ファイルは次の場所に格納されています。

• Windows: system¥Macromed¥Flash¥mms.cfg（例：C:¥WINDOWS¥system32¥Macromed¥Flash¥mms.cfg）• Mac: app support/Macromedia/mms.cfg（例：/Library/Application Support/Macromedia/mms.cfg）

mms.cfg ファイルについて詳しくは、『Flash Player 管理ガイド』（www.adobe.com/go/flash_player_admin_jp）を参照
してください。

Global Flash Player Trust ディレクトリ
Flash Player 9 以降、Adobe AIR 1.0 以降
管理ユーザーおよびインストーラーアプリケーションは、指定されたローカル SWF ファイルをすべてのユーザーの信頼できるファイルとして登録できます。これらの SWF ファイルは、local-trusted サンドボックスに割り当てられます。割り当てられたファイルは、他の SWF ファイルと自由に通信し、リモートまたはローカルを問わずどこからでもデータをロードできます。ファイルは、次の場所の Global Flash Player Trust ディレクトリで信頼できるファイルとして指定されます。

• Windows：system¥Macromed¥Flash¥FlashPlayerTrust（例：C:¥WINDOWS¥system32¥Macromed¥Flash¥FlashPlayerTrust）• Mac：app support/Macromedia/FlashPlayerTrust( 例 : /Library/Application Support/Macromedia/FlashPlayerTrust)Flash Player Trust ディレクトリには、任意の数のテキストファイルを格納でき、それぞれのファイルは、信頼できるパス
を 1 行に 1 パスずつ示したリストです。1 つのパスを 1 つの SWF ファイル、HTML ファイル、またはディレクトリとする
こともできます。コメント行は、# 記号で始まります。例えば、次のテキストが入っている Flash Player トラスト構成ファイ
ルは、指定されたディレクトリとそのすべてのサブディレクトリにあるすべてのファイルに、信頼されている状態を付与します。
# Trust files in the following directories:
C:\Documents and Settings\All Users\Documents\SampleApp

トラスト構成ファイル内に示されるパスは、常にローカルパスであるか SMB ネットワークパスであることが必要です。トラ
スト構成ファイル内の HTTP パスは、すべて無視されます。信頼できるのは、ローカルファイルだけです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1012

セキュリティ

競合を避けるため、それぞれのトラスト構成ファイルにはインストールするアプリケーションに対応したファイル名を付け、.cfg のファイル拡張子を使用してください。
ローカルで実行する SWF ファイルをインストーラーアプリケーションから配布する開発者は、インストーラーアプリケー
ションに Global Flash Player Trust ディレクトリへ構成ファイルを追加させて、配布するファイルに対するすべての権限を付与することができます。インストーラーアプリケーションは、管理者権限のあるユーザーが実行する必要があります。

mms.cfg ファイルと異なり、Global Flash Player Trust ディレクトリはトラスト許可を付与するインストーラーアプリケー
ションのために組み込まれています。管理ユーザーとインストーラーアプリケーションは、どちらも Global Flash Player

Trust ディレクトリを使用して、信頼できるローカルアプリケーションを指定できます。
また個々のユーザーの Flash Player Trust ディレクトリも使用できます（1012 ページの「ユーザーのコントロール」を参照）。

ユーザーのコントロール
Flash Player 9 以降
Flash Player には、権限を設定するためのユーザーレベルのメカニズムとして、設定 UI、設定マネージャーおよび User
Flash Player Trust ディレクトリの 3 つがあります。

設定 UI および設定マネージャー
Flash Player 9 以降
設定 UI は、特定のドメインの設定をすばやくインタラクティブに行うメカニズムです。設定マネージャーは、詳細なインターフェイスを提供し、多数またはすべてのドメインのアクセス許可を対象とするグローバルな変更を行う機能を備えています。また、SWF ファイルによって新しいアクセス許可が要求され、セキュリティやプライバシーに関する実行時決定が必要なとき、ユーザーが Flash Player 設定を調整できるダイアログボックスが表示されます。
設定マネージャーおよび設定 UI には、カメラとマイクの設定、共有オブジェクトの記憶領域の設定、古いコンテンツに関する設定などのセキュリティ関連のオプションが用意されています。設定マネージャーまたは設定 UI のいずれも AIR アプ
リケーションでは使用できません。
注意：mms.cfg ファイルで行われる設定は（1010 ページの「管理ユーザーのコントロール」を参照）、設定マネージャーに反映されません。
設定マネージャーについて詳しくは、www.adobe.com/go/settingsmanager_jp を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1013

セキュリティ

User Flash Player Trust ディレクトリ
Flash Player 9 以降、Adobe AIR 1.0 以降
ユーザーおよびインストーラーアプリケーションは、指定されたローカル SWF ファイルを信頼できるファイルとして登録できます。これらの SWF ファイルは、local-trusted サンドボックスに割り当てられます。割り当てられたファイルは、他のSWF ファイルと自由に通信し、リモートまたはローカルを問わずどこからでもデータをロードできます。ユーザーは、User
Player Trust ディレクトリでファイルを信頼できるファイルに指定します。このディレクトリは、Flash 共有オブジェクトの記憶領域と同じディレクトリ内にあり、現在のユーザーに固有の次の場所にあります。

• Windows：app data¥Macromedia¥Flash Player¥#Security¥FlashPlayerTrust（例：Windows XP の場合は C:¥Documents and Settings¥JohnD¥Application Data¥Macromedia¥Flash

Player¥#Security¥FlashPlayerTrust、Windows Vista の場合はC:¥Users¥JohnD¥AppData¥Roaming¥Macromedia¥Flash Player¥#Security¥FlashPlayerTrust）
Windows では、Application Data フォルダーはデフォルトで非表示になっています。非表示のフォルダーおよびファイルを表示するには、マイコンピューターを選択して Windows エクスプローラーを開き、ツール／フォルダーオプショ
ンを選択して「表示」タブを選択します。
「表示」タブで「すべてのファイルとフォルダーを表示する」ラジオボタンを選択します。

• Mac: app data/Macromedia/Flash Player/#Security/FlashPlayerTrust( 例 : /Users/JohnD/Library/Preferences/Macromedia/Flash Player/#Security/FlashPlayerTrust)
この設定は、現在のユーザーだけに影響を及ぼし、コンピューターにログインする他のユーザーには影響を及ぼしません。管理権限のないユーザーがシステムの個人領域にアプリケーションをインストールする場合、インストーラーはUser Flash Player Trust ディレクトリに、アプリケーションをそのユーザーの信頼できるアプリケーションとして登録できます。
ローカルで実行する SWF ファイルをインストーラーアプリケーションによって配布する開発者は、インストーラーアプ
リケーションに User Flash Player Trust ディレクトリへ構成ファイルを追加させて、配布するファイルに対するすべての権限を付与することができます。この場合でも、User Flash Player Trust ディレクトリファイルは、管理ユーザーのアクション（インストール）によって開始されるため、管理ユーザーのコントロールと見なされます。
また、管理ユーザーまたはインストーラーが、コンピューターの全ユーザーのアプリケーションの登録先に使用する

Global Flash Player Trust ディレクトリもあります（1010 ページの「管理ユーザーのコントロール」を参照）。

Web サイトのコントロール（ポリシーファイル）
Flash Player 9 以降、Adobe AIR 1.0 以降
Web サーバーにあるデータを他のドメインの SWF ファイルから利用できるようにするために、サーバー上にポリシーファ
イルを作成できます。ポリシーファイルは、サーバーの特定の場所に配置される XML ファイルです。
ポリシーファイルは、次のようなアセットへのアクセスに影響を及ぼします。

•

ビットマップ、サウンド、およびビデオのデータ• XML ファイルとテキストファイルのロード•

他のセキュリティドメインから、ロードする SWF ファイルのセキュリティドメインへの SWF ファイルの読み込み•

ソケットと XML ソケット接続へのアクセス

ActionScript オブジェクトは、2 種類のサーバー接続をインスタンス化します。ドキュメントベースのサーバー接続とソケット接続です。Loader、Sound、URLLoader、URLStream のような ActionScript オブジェクトは、ドキュメントベー
スのサーバー接続をインスタンス化し、URL からファイルをロードします。ActionScript の Socket オブジェクトとXMLSocket オブジェクトはソケット接続を作成し、ロードされたドキュメントでなくストリーミングデータを処理します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1014

セキュリティ

Flash Player は 2 種類のサーバー接続をサポートするので、URL ポリシーファイルとソケットポリシーファイルの 2 種類のポリシーファイルがあります。

•

ドキュメントベースの接続では、URL ポリシーファイルが必要です。これらのファイルにより、サーバーは、そのデー
タとドキュメントを特定のドメインまたはすべてのドメインの SWF ファイルで使用できることを示すことができます。

•

ソケット接続では、Socket および XMLSocket クラスを使用して、下位 TCP ソケットレベルでネットワーキングを直接有効にするソケットポリシーファイルが必要です。

Flash Player では、目的の接続で使用するプロトコルと同じプロトコルを使用してポリシーファイルを送信する必要があります。例えば、ポリシーファイルを HTTP サーバーに置いた場合、他のドメインの SWF ファイルは、その HTTP サー
バーからデータをロードできます。しかし、同じサーバーでソケットポリシーファイルを提供しなければ、他のドメインのSWF ファイルはそのサーバーにソケットレベルで接続できなくなります。つまり、ポリシーファイルを取得する手段は、接続の手段に一致する必要があります。
ポリシーファイルの使用方法とシンタックスは、Flash Player 10 用にパブリッシュされた SWF ファイルに適用されるので、この節の後半で簡単に説明します（最近のリリースでは Flash Player のセキュリティが強化されているので、以前のバージョンの Flash Player ではポリシーファイルの実装が若干異なります）。ポリシーファイルについて詳しくは、Flash
Player デベロッパーセンターで Flash Player 9 のポリシーファイル変更点に関するトピック（www.adobe.com/go/devnet_security_jp）を参照してください。

AIR アプリケーションサンドボックス内で実行するコードが URL またはソケットからのデータにアクセスする場合、ポリ
シーファイルは必要ありません。非アプリケーションサンドボックス内で実行する AIR アプリケーションのコードには、ポリシーファイルが必要です。

マスターポリシーファイル
Flash Player 9 以降、Adobe AIR 1.0 以降
デフォルトでは、Flash Player（および AIR アプリケーションサンドボックスに含まれていない AIR コンテンツ）は、最初にサーバーのルートディレクトリで crossdomain.xml という名前の URL ポリシーファイルを探し、ポート 843 でソケット
ポリシーファイルを探します。これらの場所のいずれかにあるファイルは、マスターポリシーファイルと呼ばれます（ソケット接続の場合、メインの接続と同じポート上のソケットポリシーファイルも検索されます。しかし、そのポートで検出されたポリシーファイルはマスターポリシーファイルとは見なされません）。
アクセス許可の指定に加えて、マスターポリシーファイルには、メタポリシーステートメントも含めることができます。メ
タポリシーは、ポリシーファイルを格納できる場所を指定します。URL ポリシーファイルのデフォルトメタポリシーは「マスターのみ」で、/crossdomain.xml がサーバーで許可される唯一のポリシーファイルです。ソケットポリシーファイルのデフォルトメタポリシーは「すべて」であり、ホスト上の任意のソケットでソケットポリシーファイルを提供できます。
注意：Flash Player 9 以前のバージョンでは、URL ポリシーファイルのデフォルトメタポリシーは「すべて」であり、任意のディレクトリにポリシーファイルを格納できます。デフォルトの /crossdomain.xml ファイル以外の場所からポリシー
ファイルをロードするアプリケーションを開発し、そのアプリケーションが Flash Player 10 で動作する可能性がある場合
は、開発者（またはサーバー管理者）がマスターポリシーファイルを変更して追加のポリシーファイルを許可する必要があります。異なるメタポリシーを指定する方法について詳しくは、Flash Player デベロッパーセンターで Flash Player 9 のポ
リシーファイル変更点に関するトピック（www.adobe.com/go/devnet_security_jp）を参照してください。

SWF ファイルは、Security.loadPolicyFile() メソッドを呼び出して、別のポリシーファイル名または別のディレクトリ内をチェックできます。ただし、ターゲットの場所でポリシーファイルを提供できることがマスターポリシーファイルで指定されていない場合は、その場所にポリシーファイルが存在していても loadPolicyFile() への呼び出しは無効です。ポリシーファ
イルを必要とするネットワーク処理を行う前に、loadPolicyFile() を呼び出します。Flash Player は、対応するポリシーファ
イル試行のバックグラウンドでネットワーキング要求を自動的にキューに入れます。したがって、ネットワーキング操作を開始する直前などに Security.loadPolicyFile() を呼び出すことが可能です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1015

セキュリティ

マスターポリシーファイルのチェックを行うとき、Flash Player はサーバーの応答を 3 秒間待機します。応答がない場合、Flash Player ではマスターポリシーファイルが存在しないと判断されます。しかし、loadPolicyFile() の呼び出しのデフォル
トタイムアウト値はありません。Flash Player では、呼び出されているファイルが存在するものとして、そのファイルをロードするのに必要なだけ待機します。したがって、マスターポリシーファイルを確実にロードするには、loadPolicyFile()を使用し、明示的に呼び出します。
メソッドの名前は Security.loadPolicyFile() ですが、ポリシーファイルは、ポリシーファイルを必要とするネットワーク呼び出しが発生するまでロードされません。loadPolicyFile() の呼び出しでは、Flash Player に対し、必要なときにポリシーファ
イルを検索する場所が指示されるだけです。
ポリシーファイル要求が開始されたときまたは完了したときに通知を受信する理由はないので、そのような通知は受信できません。Flash Player ではポリシーチェックは非同期で実行され、ポリシーファイルチェックが成功するまで接続の開始が自動的に待機されます。
次の節には、URL ポリシーファイルにのみ該当する情報が記載されています。ソケットポリシーファイルについて詳しくは、1031 ページの「ソケットへの接続」を参照してください。

URL ポリシーファイルのスコープFlash Player 9 以降、Adobe AIR 1.0 以降
URL ポリシーファイルは、ロード元のディレクトリとその子ディレクトリにのみ、適用されます。ルートディレクトリのポ
リシーファイルは、サーバー全体に適用されます。任意のサブディレクトリからロードされたポリシーファイルは、そのディレクトリおよびサブディレクトリにのみ適用されます。
ポリシーファイルは、そのファイルが存在する特定のサーバーへのアクセスにのみ影響を及ぼします。例えば、

https://www.adobe.com:8080/crossdomain.xml にあるポリシーファイルは、HTTPS 経由でポート 8080 から
www.adobe.com に対して呼び出されるデータロード呼び出しにのみ適用されます。

URL ポリシーファイルでのアクセス許可の指定
Flash Player 9 以降、Adobe AIR 1.0 以降
ポリシーファイルには、<cross-domain-policy> タグが 1 つ含まれ、このタグには <allow-access-from> タグが含まれている場
合もあります。各 <allow-access-from> タグには、domain という属性が 1 つ含まれています。この属性は、正確な IP アドレス、正確なドメインまたはワイルドカードドメイン（任意のドメイン）のいずれかを指定します。ワイルドカードドメイン
は、2 つの方法のいずれかで指定されます。

• 1 つのアスタリスク（*）：すべてのドメインおよびすべての IP アドレスに一致します。
•

アスタリスクの後に接尾辞：指定した接尾辞で終わるドメインにのみ一致します。

接尾辞は、ドットで始める必要があります。ただし、この先頭のドットは検索には使用されません。ドットを除いた接尾辞に一致するドメインだけが検索されます。例えば、xyz.com は *.xyz.com の一部と見なされます。IP ドメインの指定にワイ
ルドカードは使用できません。
次の例は、*.example.com、www.friendOfExample.com および 192.0.34.166 に置かれている SWF ファイルへのアクセスを許可する URL ポリシーファイルを示しています。
<?xml version="1.0"?><cross-domain-policy><allow-access-from domain="*.example.com" /><allow-access-from domain="www.friendOfExample.com" /><allow-access-from domain="192.0.34.166" /></cross-domain-policy>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1016

セキュリティ

IP アドレスを指定した場合は、IP シンタックス（http://65.57.83.12/flashmovie.swf など）を使用してその IP アドレスからロードされた SWF ファイルにのみアクセスが許可されます。ドメイン名シンタックスを使用した SWF ファイルへのアクセスは許可されません。Flash Player は、DNS 解決を行いません。
次のように、すべてのドメインのドキュメントに対してアクセスを許可できます。
<?xml version="1.0"?><!-- http://www.foo.com/crossdomain.xml --><cross-domain-policy><allow-access-from domain="*" /></cross-domain-policy>

各 <allow-access-from> タグには、オプションの secure 属性もあります。この属性のデフォルトは true です。ポリシーファイ
ルが HTTPS サーバー上にあり、HTTPS サーバー以外にある SWF ファイルで HTTPS サーバーのデータをロードする場合は、この属性を false に設定できます。

secure 属性を false に設定すると、HTTPS のセキュリティが影響を受けます。特に、この属性を false に設定すると、セキュ
アなコンテンツがスヌープ攻撃やスプーフィング攻撃にさらされる可能性があります。secure 属性は false に設定しないことを強くお勧めします。
ロードするデータが HTTPS サーバー上にあり、そのデータをロードする SWF ファイルが HTTP サーバー上にある場合
は、SWF ファイルを HTTPS サーバーに移動することをお勧めします。SWF ファイルを HTTPS サーバーに移動すると、セキュアデータのすべてのコピーを HTTPS の保護下に置くことができます。しかし、SWF ファイルを HTTP サーバー上に置く必要がある場合は、次のコードに示すように、secure="false" 属性を <allow-access-from> タグに追加します。
<allow-access-from domain="www.example.com" secure="false" />アクセスを許可するために、allow-http-request-headers-from タグも使用できます。このエレメントは、別の許可ドメインのコンテンツをホストとするクライアントにユーザー定義ヘッダーをユーザー自身のドメインに送信する許可を付与します。

<allow-access-from> タグは、その他のドメインに、ユーザー自身のドメインからデータをプルする許可を付与しますが、
allow-http-request-headers-from タグは、その他のドメインに、ユーザー自身のドメインに対してヘッダーの形式でデータをプッシュする許可を付与します。次の例では、SOAPAction ヘッダーを現在のドメインに送信することを任意のドメインに許可します。
<cross-domain-policy><allow-http-request-headers-from domain="*" headers="SOAPAction"/></cross-domain-policy>

マスターポリシーファイルに allow-http-request-headers-from ステートメントが含まれている場合、このステートメントはホ
スト上のすべてのディレクトリに適用されます。含まれていない場合、このステートメントは、ステートメントを含むポリ
シーファイルのディレクトリおよびサブディレクトリにのみ適用されます。

ポリシーファイルのプリロード
Flash Player 9 以降、Adobe AIR 1.0 以降
サーバーからのデータのロードまたはソケットへの接続は、非同期操作です。Flash Player は、ポリシーファイルのダウン
ロードが終了するまで、主な操作を開始しません。しかし、イメージからのピクセルデータの抽出やサウンドからのサンプ
ルデータの抽出は同期操作です。データを抽出するには、ポリシーファイルをロードする必要があります。メディアをロードするときは、ポリシーファイルの有無をチェックするよう指定します。

• Loader.load() メソッドを使用する場合、LoaderContext オブジェクトである context パラメーターの checkPolicyFile プロ
パティを設定します。

• <img> タグを使用してテキストフィールドにイメージを埋め込む場合は、次に示すように <img> タグの checkPolicyFile
属性を「true」に設定します。
<img checkPolicyFile = "true" src = "example.jpg">

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1017

セキュリティ

• Sound.load() メソッドを使用する場合、SoundLoaderContext オブジェクトである context パラメーターのcheckPolicyFile プロパティを設定します。

• NetStream クラスを使用する場合、NetStream オブジェクトの checkPolicyFile プロパティを設定します。
これらのいずれかのパラメーターを設定すると、Flash Player は最初に、既にそのドメイン用にダウンロードされたポリシーファイルがあるかどうかをチェックします。次に、サーバー上のデフォルトの場所にあるポリシーファイルが検索され、<allow-access-from> ステートメントのチェックとメタポリシーの有無のチェックが行われます。最後に、Security.loadPolicyFile() メソッドへの保留中の呼び出しがスコープ内にあるかどうかがチェックされます。

作成者（開発者）コントロール
Flash Player 9 以降、Adobe AIR 1.0 以降
セキュリティ権限を付与するために使用される主な ActionScript API は、Security.allowDomain() メソッドです。このメ
ソッドは、指定されたドメイン内の SWF ファイルに権限を付与します。次の例では、SWF ファイルはwww.example.com ドメインに置かれた SWF ファイルへのアクセスを許可します。
Security.allowDomain("www.example.com")

次のメソッドは次の権限を許可します。

• SWF ファイル間のクロススクリプト（1025 ページの「クロススクリプト」を参照）•

表示リストへのアクセス（1027 ページの「表示リスト内の移動」を参照）•

イベント検出（1027 ページの「イベントセキュリティ」を参照）• Stage オブジェクトのプロパティとメソッドへのフルアクセス（1026 ページの「ステージのセキュリティ」を参照）
Security.allowDomain() メソッドを呼び出す主な目的は、外部ドメインにある SWF ファイルに、Security.allowDomain() メ
ソッドを呼び出す SWF ファイルをスクリプトする許可を付与することです。詳しくは、1025 ページの「クロススクリプ
ト」を参照してください。

Security.allowDomain() メソッドにパラメーターとして IP アドレスを指定しても、指定された IP アドレスに存在するすべてのアクセス元からのアクセスが許可されるわけではありません。許可されるのは、その IP アドレスに対応するドメイン名ではなく、URL として指定された IP アドレスを含むアクセス元からのアクセスだけです。例えば、ドメイン名
www.example.com が IP アドレス 192.0.34.166 に対応している場合、Security.allowDomain("192.0.34.166") の呼び出しではwww.example.com へのアクセスは許可されません。
ワイルドカード「*」を Security.allowDomain() メソッドに渡して、すべてのドメインからのアクセスを許可できます。「*」
ワイルドカードはすべてのドメインにある SWF ファイルに、呼び出しを行う SWF ファイルをスクリプトする許可を付与するので、使用に注意してください。

ActionScript には、Security.allowInsecureDomain() という第 2 の許可 API が組み込まれています。このメソッドではSecurity.allowDomain() メソッドとほとんど同じ処理が行われますが、異なる点は、セキュアな HTTPS 接続によって提供された SWF ファイルから呼び出された場合に、HTTP などのセキュアでないプロトコルから提供される他の SWF ファイルに、呼び出し側の SWF ファイルへのアクセスを追加的に許可することです。しかし、セキュアなプロトコル（HTTPS）からのファイルと、セキュアでないプロトコル（HTTP など）からのファイルの間でスクリプティングを許可することはセキュリティ上望ましくありません。それにより、セキュアなコンテンツがスヌープ攻撃やスプーフィング攻撃にさらされる可能性があります。そのような攻撃が可能になる理由は、Security.allowInsecureDomain() メソッドは、HTTP 接続によって提供される SWF ファイルがセキュアな HTTPS データにアクセスすることを許可するので、HTTP サーバーとユーザーの間に割り込んだ攻撃者は、HTTP の SWF ファイルを独自のものに置き換えることにより、HTTPS データにアクセスできるからです。
重要：AIR アプリケーションサンドボックス内で実行するコードは、Security クラスの allowDomain() メソッドまたは
allowInsecureDomain() メソッドのいずれも呼び出すことはできません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1018

セキュリティ

セキュリティに関連したもう 1 つの重要なメソッドは、Security.loadPolicyFile() です。このメソッドを使用すると、Flash

Player は標準以外の場所にポリシーファイルがあるかどうかをチェックします。詳しくは、1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照してください。

ネットワーク API の制限
Flash Player 9 以降、Adobe AIR 1.0 以降
ネットワーク API は、2 つの方法で制限できます。悪意のあるアクティビティを防止するために、一般的に予約されているポートへのアクセスはブロックされます。これらのブロックをコードで上書きすることはできません。その他のポートに関してネットワーク機能への SWF ファイルのアクセスを制御するために、allowNetworking 設定を使用できます。

ブロックされたポート
Flash Player 9 以降、Adobe AIR 1.0 以降
ブラウザーと同様に、Flash Player および Adobe AIR には、特定のポートへの HTTP アクセスの制限があります。HTTP
以外の種類のサーバーに使用されている特定の標準ポートには HTTP 要求が許可されません。
ネットワーク URL にアクセスする API は、これらのポートブロック制限の対象となります。例外は、ソケットを直接呼び出す API（Socket.connect() や XMLSocket.connect() など）、またはソケットポリシーファイルがロードされる

Security.loadPolicyFile() への呼び出しのみです。ソケット接続は、ターゲットサーバー上のソケットポリシーファイルの使用により許可または拒否されます。
次のリストは、ポートブロックが適用される ActionScript 3.0 API を示します。

FileReference.download()、FileReference.upload()、Loader.load()、Loader.loadBytes()、navigateToURL()、
NetConnection.call()、NetConnection.connect()、NetStream.play()、Security.loadPolicyFile()、sendToURL()、Sound.load()、
URLLoader.load()、URLStream.load()
ポートブロックは、共有ライブラリの読み込み、テキストフィールドでの <img> タグの使用および <object> と <embed> タグを使用した HTML ページ内の SWF ファイルのロードにも適用されます。
ポートブロックは、共有ライブラリの読み込み、テキストフィールドでの <img> タグの使用および <object> と <embed> タグを使用した HTML ページ内の SWF ファイルのロードにも適用されます。
次のリストは、ブロックされるポートを示します。

HTTP：20（FTP データ）、21（FTP 制御）
HTTP と FTP：1（tcpmux）、7（echo）、9（discard）11（systat）、13（daytime）15（netstat）、17（qotd）、19（chargen）、22（ssh）、23（telnet）、25（smtp）、37（time）、42（name）、43（nicname）、53（domain）、77（priv-rjs）、79（finger）、87（ttylink）、95（supdup）、101（hostriame）、102（iso-tsap）、103（gppitnp）、104（acrnema）、109（pop2）、110（pop3）、111（sunrpc）、113（auth）、115（sftp）、117（uucp-path）、119（nntp）、123（ntp）、135（loc-srv / epmap）、139（netbios）、143（imap2）、179（bgp）、389（ldap）、465（smtp+ssl）、512（print / exec）、513（login）、514（shell）、515（printer）、526（tempo）、530（courier）、531（chat）、532（netnews）、540（uucp）、556（remotefs）、563（nntp+ssl）、587（smtp）、601（syslog）、636（ldap+ssl）、993（ldap+ssl）、995（pop3+ssl）、2049（nfs）、4045（lockd）、6000（x11）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1019

セキュリティ

allowNetworking パラメーターの使用Flash Player 9 以降、Adobe AIR 1.0 以降
SWF コンテンツを含む HTML ページで <object> および <embed> タグに allowNetworking パラメーターを設定することによって、ネットワーク機能に対する SWF ファイルのアクセスを制御できます。
allowNetworking に指定できる値は次のとおりです。

• 「all」（デフォルト）- SWF ファイルですべてのネットワーク API が許可されます。
• 「internal」- SWF ファイルは、この節の後半に示すブラウザーナビゲーションまたはブラウザーインタラクション APIを呼び出すことはできませんが、その他のネットワーク API を呼び出すことができます。
• 「none」- SWF ファイルは、この節の後半に示すブラウザーナビゲーションまたはブラウザーインタラクション API を呼び出すことはできません。また、後半に示す SWF 間の通信 API を使用できません。
allowNetworking パラメーターは、主に SWF ファイルと上位の HTML ページのドメインが異なる場合に使用するために設計されています。ロードする SWF ファイルが上位の HTML ページと同じドメインにある場合は、意図した HTML ページと一緒に SWF ファイルが常にロードされることを保証できないので、「internal」または「none」の値を使用することは推奨されません。信頼されていないアクセス元は、ドメインから上位 HTML なしで SWF ファイルをロードできます。その場
合、allowNetworking の制限は意図したとおりに機能しません。
禁止された API を呼び出すと、SecurityError 例外がスローされます。
次の例に示すように、SWF ファイルへの参照を含む HTML ページの <object> および <embed> タグに allowNetworking パ
ラメーターを追加して値を設定します。
<object classic="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
Code base="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,124,0"
width="600" height="400" ID="test" align="middle"><param name="allowNetworking" value="none" /><param name="movie" value="test.swf" /><param name="bgcolor" value="#333333" /><embed src="test.swf" allowNetworking="none" bgcolor="#333333"
width="600" height="400"
name="test" align="middle" type="application/x-shockwave-flash"pluginspage="http://www.macromedia.com/go/getflashplayer" /></object>HTML ページでは、SWF 埋め込みタグを生成するスクリプトも使用できます。スクリプトが正しい allowNetworking 設定を挿入するように変更する必要があります。Adobe Flash Professional および Adobe Flash Builder で生成された HTML
ページでは、AC_FL_RunContent() 関数を使用して SWF ファイルへの参照を埋め込みます。次に示すように、スクリプトに
allowNetworking パラメーターの設定を追加します。
AC_FL_RunContent( ... "allowNetworking", "none", ...)

allowNetworking が「internal」に設定されている場合は、以下の API を使用できません。
navigateToURL()、fscommand()、ExternalInterface.call()
前記のリストの API 以外に、次の API も allowNetworking が「none」に設定されている場合は禁止されます。

sendToURL()、FileReference.download()、FileReference.upload()、Loader.load()、LocalConnection.connect()、
LocalConnection.send()、NetConnection.connect()、NetStream.play()、Security.loadPolicyFile()、SharedObject.getLocal()、SharedObject.getRemote()、Socket.connect()、Sound.load()、URLLoader.load()、URLStream.load()、XMLSocket.connect()
選択された allowNetworking 設定により SWF ファイルがネットワーク API を使用することが許可されている場合でも、セキュリティサンドボックスの制限に基づいて他の制限が適用されることがあります（1006 ページの「セキュリティサンドボックス」を参照）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1020

セキュリティ

allowNetworking が「none」に設定されている場合、TextField オブジェクトの htmlText プロパティの <img> タグで外部メ
ディアを参照できません（SecurityError 例外がスローされます）。
allowNetworking を「none」に設定すると、ActionScript ではなく Flash Professional で追加された、読み込み済み共有ラ
イブラリのシンボルは、実行時にブロックされます。

フルスクリーンモードのセキュリティ
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player 9.0.27.0 以降は、Flash Player で実行中のコンテンツを画面全体に表示できるフルスクリーンモードをサポートしています。フルスクリーンモードに移行するためには、ステージの displayState プロパティをStageDisplayState.FULL_SCREEN 定数に設定します。詳細については、159 ページの「フルスクリーンモードの操作」を参照してください。
リモートサンドボックスで実行中の SWF ファイルについては、セキュリティ上の考慮事項がいくつかあります。
フルスクリーンモードを有効にするには、SWF ファイルの参照を含む HTML ページの <object> と <embed> タグで、次に示すように allowFullScreen パラメーターを追加して、その値を「true」に設定します（デフォルト値は「false」）。
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,18,0"
width="600" height="400" id="test" align="middle"><param name="allowFullScreen" value="true" /><param name="movie" value="test.swf" /><param name="bgcolor" value="#333333" /><embed src="test.swf" allowFullScreen="true" bgcolor="#333333"
width="600" height="400"
name="test" align="middle" type="application/x-shockwave-flash"pluginspage="http://www.macromedia.com/go/getflashplayer" /></object>HTML ページでは、SWF 埋め込みタグを生成するスクリプトも使用できます。allowFullScreen 設定が正しく挿入されるよ
うに、スクリプトを変更する必要があります。Flash Professional および Flash Builder で生成された HTML ページでは、
AC_FL_RunContent() 関数を使用して SWF ファイルへの参照を埋め込みます。ユーザーは、次のように allowFullScreen パ
ラメーターの設定を追加する必要があります。
AC_FL_RunContent( ... "allowFullScreen", "true", ...)

フルスクリーンモードを開始する ActionScript は、マウスイベントまたはキーボードイベントへの応答としてのみ呼び出
すことができます。別の状況で呼び出された場合、Flash Player は例外をスローします。
コンテンツがフルスクリーンモードに移行すると、このモードの終了および通常モードへの復帰の方法を指示するメッセー
ジが表示されます。メッセージは数秒間表示された後、消えます。
ブラウザーで実行するコンテンツの場合、フルスクリーンモードではキーボードの使用が制限されます。Flash Player 9 では、Esc キーの押下など、アプリケーションを通常のモードに戻すキーボードショートカットのみがサポートされています。
テキストフィールドにテキストを入力したり、画面を移動したりすることはできません。Flash Player 10 以降では、非表示
文字を入力する一部のキー（矢印キー、スペースバー、Tab キー）についてはサポートされています。ただし、テキスト入力は依然として禁止されています。
フルスクリーンモードは、スタンドアロンプレイヤーまたはプロジェクターファイルは常に使用できます。また、これらの環境では、テキスト入力を含むキーボードの使用が完全にサポートされています。

Stage オブジェクトの displayState プロパティを呼び出すと、ステージ所有者と同じセキュリティ Sandbox 内にない呼び出
し元について例外がスローされます。この場合のステージ所有者とはメイン SWF ファイルです。詳しくは、1026 ページの「ステージのセキュリティ」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1021

セキュリティ

管理者は、mms.cfg ファイルで FullScreenDisable = 1 を設定することで、ブラウザーで実行中の SWF ファイルのフルスク
リーンモードを無効にできます。詳しくは、1010 ページの「管理ユーザーのコントロール」を参照してください。
ブラウザーでは、SWF ファイルは HTML ページ内に配置されなければフルスクリーンモードになりません。

フルスクリーンインタラクティブモードのセキュリティ
Flash Player 11.3 以降、Adobe AIR 1.0 以降
Flash Player 11.3 以降は、Flash Player で実行中のコンテンツを画面全体に表示し、テキスト入力を利用できるフルスク
リーンインタラクティブモードをサポートしています。フルスクリーンインタラクティブモードに移行するためには、ス
テージの displayState プロパティを StageDisplayState.FULL_SCREEN_INTERACTIVE 定数に設定します。詳しくは、159
ページの「フルスクリーンモードの操作」を参照してください。
リモートサンドボックスで実行中の SWF ファイルについては、セキュリティ上の考慮事項がいくつかあります。
フルスクリーンモードを有効にするには、SWF ファイルの参照を含む HTML ページの <object> と <embed> タグで、次に示すように allowFullScreenInteractive パラメーターを追加して、その値を「true」に設定します（デフォルト値は「false」）。
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,18,0"
width="600" height="400" id="test" align="middle"><param name="allowFullScreenInteractive" value="true" /><param name="movie" value="test.swf" /><param name="bgcolor" value="#333333" /><embed src="test.swf" allowFullScreen="true" bgcolor="#333333"
width="600" height="400"
name="test" align="middle" type="application/x-shockwave-flash"pluginspage="http://www.macromedia.com/go/getflashplayer" /></object>HTML ページでは、SWF 埋め込みタグを生成するスクリプトも使用できます。allowFullScreenInteractive 設定が正しく挿入されるように、スクリプトを変更する必要があります。Flash Professional および Flash Builder で生成された HTML
ページでは、AC_FL_RunContent() 関数を使用して SWF ファイルへの参照を埋め込みます。ユーザーは、次のように
allowFullScreenInteractive パラメーターの設定を追加する必要があります。
AC_FL_RunContent( ... "allowFullScreenInteractive", "true", ...)

フルスクリーンインタラクティブモードを開始する ActionScript は、マウスイベントまたはキーボードイベントへの応答としてのみ呼び出すことができます。別の状況で呼び出された場合、Flash Player は例外をスローします。
コンテンツがフルスクリーンインタラクティブモードに移行すると、オーバーレイメッセージが表示されます。このメッセージには、フルスクリーンページのドメイン、フルスクリーンモードを終了する手順および「許可」ボタンが表示されます。フルスクリーンインタラクティブモードであることを通知するこのオーバーレイは、ユーザーが「許可」をクリックするまで表示されます。
管理者は、mms.cfg ファイルで FullScreenInteractiveDisable = 1 を設定することで、ブラウザーで実行中の SWF ファイルのフルスクリーンインタラクティブモードを無効にできます。詳しくは、1010 ページの「管理ユーザーのコントロール」を参照してください。
ブラウザーでは、SWF ファイルは HTML ページ内に配置されなければフルスクリーンインタラクティブモードになりません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1022

セキュリティ

コンテンツのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player および AIR のコンテンツは、様々なタイプのコンテンツをロードできます。以下に例を示します。

• SWF ファイル
•

イメージ

•

サウンド

•

ビデオ

• HTML ファイル（AIR のみ）• JavaScript（AIR のみ）

Loader クラスを使用した SWF ファイルとイメージのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルおよびイメージ（JPG、GIF、または PNG ファイル）をロードするには、Loader クラスを使用します。
local-with-filesystem サンドボックス以外にある SWF ファイルは、任意のネットワークドメインから SWF ファイルおよびイメージをロードできます。ローカルサンドボックス内にある SWF ファイルだけが、SWF ファイルとイメージをローカ
ルファイルシステムからロードできます。しかし、local-with-networking サンドボックス内のファイルは、local-trusted
サンドボックスまたは local-with-networking サンドボックス内のローカル SWF ファイルしかロードできません。localwith-networking サンドボックス内の SWF ファイルは、SWF ファイル以外のローカルコンテンツ（イメージなど）をロードしますが、ロードしたコンテンツの中のデータにはアクセスできません。
信頼できないソース（Loader オブジェクトのルート SWF ファイルのドメイン以外のドメインなど）から SWF ファイルをロードするとき、次のコードに示すように、Loader オブジェクトのマスクを定義して、ロードされたコンテンツ（Loader
オブジェクトの子）がそのマスクの外部にあるステージの一部分に描画されないようにすることができます。
import flash.display.*;
import flash.net.URLRequest;
var rect:Shape = new Shape();rect.graphics.beginFill(0xFFFFFF);
rect.graphics.drawRect(0, 0, 100, 100);
addChild(rect);
var ldr:Loader = new Loader();
ldr.mask = rect;
var url:String = "http://www.unknown.example.com/content.swf";
var urlReq:URLRequest = new URLRequest(url);
ldr.load(urlReq);
addChild(ldr);

Loader オブジェクトの load() メソッドを呼び出す場合、LoaderContext オブジェクトである context パラメーターを指定できます。LoaderContext クラスには、ロードされたコンテンツの使用方法のコンテキストを定義できる次の 3 つのプロパ
ティが含まれています。

• checkPolicyFile：このプロパティは、SWF ファイルではなくイメージファイルをロードする場合にのみ使用します。
Loader オブジェクトを含んでいるファイルのドメイン以外のドメインのイメージファイルに対して、このプロパティを指定します。このプロパティを true に設定した場合、Loader は元のサーバーで URL ポリシーファイルをチェックします（1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照）。サーバーが Loader ドメインに許可を与えた場合、Loader ドメイン内にある SWF ファイルの ActionScript は、ロードされたイメージ内のデータにアクセスできます。つまり、Loader.content プロパティを使用して、ロードされたイメージを表す Bitmap オブジェクトへの参照を取得するか、BitmapData.draw() メソッドまたは BitmapData.drawWithQuality() メソッドを使用して、ロードされたイ

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1023

セキュリティ

メージのピクセルにアクセスできます。drawWithQuality メソッドは Flash Player 11.3 以降および AIR 3.3 以降で使用できます。

• securityDomain：このプロパティは、イメージではなく SWF ファイルをロードする場合にのみ使用します。Loader オ
ブジェクトを含むファイルのドメイン以外のドメインの SWF ファイルに対してこのプロパティを指定します。現時点でsecurityDomain プロパティに指定できる値は、null（デフォルト）と SecurityDomain.currentDomain の 2 つだけです。
SecurityDomain.currentDomain を指定した場合、これはロードされた SWF ファイルを、ロードする側の SWF ファイルのサンドボックスへ読み込むよう要求します。つまり、ロードされた SWF ファイルが、ロードする側の SWF ファイル自体のサーバーからロードされたかのように動作します。これが許可されるのは、ロードされた SWF ファイルのサーバー上に URL ポリシーファイルがあり、ロードする側の SWF ファイルのドメインによるアクセスを許可している場合だけです。要求されたポリシーファイルが検出された場合、ロードする側とロードされる側は、同じサンドボックス内にあるので、ロードが開始された後、自由にお互いをスクリプトすることができます。サンドボックスの読み込みは、ほとんどの場合、通常のロードを実行した後、ロードされた SWF ファイルで Security.allowDomain() メソッドを呼び出す操作に置き換えることができます。後者の方法の方が使いやすい場合もあります。なぜなら、ロードされた SWF ファイルはそれ自体の自然なサンドボックス内に入り、それ自体の実際のサーバー上にあるリソースにアクセスできるからです。

• applicationDomain：ActionScript 1.0 や 2.0 で記述されたイメージまたは SWF ファイルではなく、ActionScript 3.0 で記述された SWF ファイルをロードする場合にのみ、このプロパティを使用します。ファイルをロードするときに、ファイルを特定のアプリケーションドメインに配置するよう指定できます。デフォルトでは、ファイルは新しいアプリケー
ションドメイン ( ロードする側の SWF ファイルのアプリケーションドメインの子 ) に配置されます。アプリケーション
ドメインはセキュリティドメインのサブユニットです。したがって、ターゲットアプリケーションドメインを指定できるのは、ロード対象の SWF ファイルがユーザー自身のセキュリティドメイン内にある場合だけです。その理由は、そのSWF ファイルがユーザー自身のサーバー内にあるか、securityDomain プロパティを使用してセキュリティドメインに正
しく読み込まれた SWF ファイルだからです。アプリケーションドメインを指定しても、ロードされた SWF ファイルが別のセキュリティドメインにある場合、applicationDomain で指定したドメインは無視されます。詳しくは、140 ページの「アプリケーションドメインの操作」を参照してください。
詳しくは、191 ページの「ロードコンテキストの指定」を参照してください。

Loader オブジェクトの重要なプロパティの 1 つに、contentLoaderInfo プロパティがあります。これは LoaderInfo オブジェクトです。他のほとんどのオブジェクトと異なり、LoaderInfo オブジェクトはロードする側の SWF ファイルとロードされたコンテンツの間で共有され、常に双方からアクセスできます。ロードされたコンテンツが SWF ファイルである場合、そのSWF ファイルは DisplayObject.loaderInfo プロパティを通じて LoaderInfo オブジェクトにアクセスできます。LoaderInfo
オブジェクトには、ロードの進行状況、ロードする側とロードされる側の URL、ロードする側とロードされる側の信頼関係、およびその他の情報が含まれています。詳しくは、190 ページの「ロードの進行状況の監視」を参照してください。

サウンドとビデオのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
すべてのコンテンツ（local-with-filesystem サンドボックス内のコンテンツを除く）で、Sound.load()、

NetConnection.connect() および NetStream.play() メソッドを使用して、ネットワークからサウンドおよびビデオをロードできます。
ローカルファイルシステムからメディアをロードできるのは、local-with-filesystem サンドボックスおよび AIR アプリ
ケーションサンドボックス内にあるコンテンツのみです。また、ロードされたこれらのファイル内のデータにアクセスできるのは、local-with-filesystem サンドボックス、AIR アプリケーションサンドボックスまたは local-trusted サンドボック
ス内にあるコンテンツのみです。
それ以外にも、ロードされたメディアのデータへのアクセスには制限があります。詳しくは、1028 ページの「ロードされたメディアへのデータとしてのアクセス」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1024

セキュリティ

テキストフィールドに <img > タグを使用した SWF ファイルとイメージのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルおよびビットマップをテキストフィールドにロードするには、次のコードに示すように、<img> タグを使用します。
<img src = 'filename.jpg' id = 'instanceName' >この方法でロードされたコンテンツには、次のコードのように TextField インスタンスの getImageReference() メソッドを使用してアクセスします。
var loadedObject:DisplayObject = myTextField.getImageReference('instanceName');

ただし、この方法でロードされた SWF ファイルとイメージは、オリジンに対応するサンドボックスに置かれます。
テキストフィールド内の <img> タグを使用してイメージファイルをロードする場合、イメージ内のデータへのアクセスは、

URL ポリシーファイルによって許可できます。次のコードのように、checkPolicyFile 属性を <img> タグに追加してポリシー
ファイルをチェックします。
<img src = 'filename.jpg' checkPolicyFile = 'true' id = 'instanceName' >テキストフィールドに <img> タグを使用した SWF をロードする場合、Security.allowDomain() メソッドを呼び出して、そのSWF ファイルのデータへのアクセスを許可できます。
SWF 内に埋め込んだ Bitmap クラスを使用せず、テキストフィールド内の <img> タグを使用して外部ファイルをロードす
る場合、Loader オブジェクトは TextField オブジェクトの子として自動的に作成され、外部ファイルは、ActionScript 内の Loader オブジェクトを使用してファイルをロードする場合とまったく同じように、Loader にロードされます。その場
合、getImageReference() メソッドは、自動的に作成された Loader を返します。この Loader オブジェクトは、呼び出しコードと同じセキュリティサンドボックス内に置かれているため、このオブジェクトにアクセスする場合にはセキュリティ
チェックは不要です。
しかし、ロードされたメディアにアクセスするために Loader オブジェクトの content プロパティを参照する場合は、セキュ
リティルールが適用されます。コンテンツがイメージの場合は、URL ポリシーファイルを実装する必要があり、コンテンツ
が SWF ファイルの場合は、SWF ファイル内のコードを使用して allowDomain() メソッドを呼び出す必要があります。

Adobe AIR
アプリケーションサンドボックスでは、フィッシング攻撃を回避するために、テキストフィールド内の <img> タグは無視されます。また、アプリケーションサンドボックス内で実行するコードでは、Security クラスの allowDomain() メソッドを呼び出せません。

RTMP サーバーを使用して送信されたコンテンツ
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Media Server は、RTMP（Real-Time Media Protocol）を使用してデータ、オーディオ、およびビデオを提供します。このメディアをロードするには、NetConnection クラスの connect() メソッドを使用して、RTMP URL をパラメーターとして渡します。Flash Media Server は、要求元ファイルのドメインに基づいて、接続を制限し、コンテンツがダウンロードされないようにすることができます。詳しくは、www.adobe.com/go/learn_fms_docs_jp でオンラインの FlashMedia Server ドキュメントを参照してください。
BitmapData.draw() メソッド、BitmapData.drawWithQuality() メソッドおよび SoundMixer.computeSpectrum() メソッドを使用
して RTMP ストリームからランタイムグラフィックとサウンドデータを抽出するには、サーバーでアクセスを許可する必要があります。Flash Media Server にある特定のディレクトリへのアクセスを許可するには、サーバーサイド ActionScript

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1025

セキュリティ

の Client.videoSampleAccess プロパティおよび Client.audioSampleAccess プロパティを使用します。詳しくは、『サーバーサイド ActionScript 言語リファレンス』を参照してください（drawWithQuality メソッドは Flash Player 11.3 以降および AIR
3.3 以降で使用できます）。

クロススクリプトFlash Player 9 以降、Adobe AIR 1.0 以降
ActionScript 3.0 で記述された 2 つの SWF ファイル、または AIR で実行される 2 つの HTML ファイルが同じドメインに所属している場合は、例えば 1 つの SWF ファイルの URL が http://www.example.com/swfA.swf、もう 1 つの SWF ファ
イルの URL が http://www.example.com/swfB.swf であれば、片方のファイルに定義されたコードはもう一方の変数、オブジェクト、プロパティ、メソッドなどを検査および変更でき、その逆も可能です。これをクロススクリプトと呼びます。

2 つのファイルが異なるドメインに所属している場合（例えば http://siteA.com/swfA.swf および
http://siteB.com/swfB.swf）、Flash Player および AIR のデフォルトでは、swfA.swf で swfB.swf をスクリプトすることも、swfB.swf で swfA.swf をスクリプトすることもできません。SWF ファイルは、Security.allowDomain() を呼び出すことで他のドメインの SWF ファイルに許可を付与します。Security.allowDomain("siteA.com") を呼び出すことで、swfB.swf でのsiteA.com の SWF ファイルのスクリプト許可が付与されます。
AVM1 SWF ファイルと AVM2 SWF ファイル間でのクロススクリプトはサポートされません。AVM1 SWF ファイルは、ActionScript 1.0 または ActionScript 2.0 を使用して作成されたファイルです。AVM1 および AVM2 は、ActionScript 仮
想マシンを意味します。しかし、LocalConnection クラスを使用すると、AVM1 と AVM2 間でデータを送信できます。
クロスドメインの場合は、関与する 2 つのドメインを明確にすることが重要です。説明のため、ここでは、クロススクリプ
トを実行する側をアクセス元（通常、アクセスする SWF）と呼び、もう一方をアクセス先（通常、アクセスされる SWF）と呼びます。次の図に示すように、siteA.swf が siteB.swf をスクリプトする場合、siteA.swf がアクセス元で、siteB.swf がアクセス先です。
siteA.com / swfA.swf
SWF

var url:String = "http://siteB.com/swfB.swf";
var req:URLRequest = new URLRequest(url);myLoader.load(req);

myLoader.content.eggCount = 3;
myLoader.content.DisplayEggs();

3

クロススクリプト

2

1

ロード

許可

Security.allowDomain("siteA.com");var eggCount:Number;function DisplayEggs() { ... };siteB.com / swfB.swf SWF

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1026

セキュリティ

Security.allowDomain() メソッドを使用して確立されるクロスドメイン許可は非対称です。前の例では、siteA.swf はsiteB.swf をスクリプトできますが、siteB.swf は siteA.swf をスクリプトできません。この理由は、siteB.com の SWF ファ
イルに siteA.swf をスクリプトする許可を付与するための Security.allowDomain() メソッドを siteA.swf で呼び出していないからです。対称的な許可を設定するには、両方の SWF ファイルで Security.allowDomain() メソッドを呼び出します。

Flash Player では、SWF ファイルを他の SWF ファイルによるクロスドメインスクリプトから保護するだけでなく、HTML ファイル によるクロスドメインスクリプトからも保護します。HTML から SWF へのスクリプトは、ExternalInterface.addCallback() メソッドを通じて確立されたコールバックで発生させることができます。HTML から SWF
へのスクリプトがドメインを越える場合、アクセス先 SWF ファイルは、アクセス元が SWF ファイルの場合と同様に、
Security.allowDomain() メソッドを呼び出す必要があります。さもなければ、操作は失敗します。詳しくは、1017 ページの「作成者（開発者）コントロール」を参照してください。
また、Flash Player は SWF から HTML へのスクリプトのセキュリティ管理も行います。詳しくは、1035 ページの「送信URL アクセスの制御」を参照してください。

ステージのセキュリティ
Flash Player 9 以降、Adobe AIR 1.0 以降
Stage オブジェクトの一部のプロパティとメソッドは、表示リストのスプライトやムービークリップで使用できます。
しかし、Stage オブジェクトには所有者があるといいます。つまり、ロードされた最初の SWF ファイルです。デフォルトでは、Stage オブジェクトの次のプロパティおよびメソッドは、ステージ所有者と同じセキュリティサンドボックス内の SWF
ファイルでのみ使用できます。
プロパティ

メソッド

align

addChild()

displayState

addChildAt()

frameRate

addEventListener()heightdispatchEvent()

mouseChildren

hasEventListener()

numChildren

setChildIndex()quality

willTrigger()scaleMode
showDefaultContextMenu
stageFocusRect
stageHeightstageWidth
tabChildren
textSnapshot
width

ステージ所有者のサンドボックスを除き、サンドボックス内の SWF ファイルが上記のプロパティおよびメソッドにアクセ
スするには、ステージ所有者の SWF ファイルは、Security.allowDomain() メソッドを呼び出して、外部サンドボックスのドメインを許可する必要があります。詳しくは、1017 ページの「作成者（開発者）コントロール」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1027

セキュリティ

frameRate プロパティは特殊なケースです。SWF ファイルはすべて frameRate プロパティを読み取ることができます。しかし、このプロパティを変更できるのは、ステージ所有者のセキュリティサンドボックス内にあるか、Security.allowDomain()
メソッドの呼び出しによって許可を付与された SWF ファイルだけです。

Stage オブジェクトの removeChildAt() および swapChildrenAt() メソッドにも制限がありますが、それらは他の制限と異なっています。これらのメソッドを呼び出すには、コードは、ステージ所有者と同じドメイン内にある必要はなく、影響を受ける子オブジェクトの所有者と同じドメイン内にある必要があります。あるいは、子オブジェクトはSecurity.allowDomain() メソッドを呼び出すことができます。

表示リスト内の移動
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルから他のサンドボックスからロードされた表示オブジェクトにアクセスする機能は制限されます。SWF ファ
イルが別のサンドボックス内にある別の SWF ファイルによって作成された表示オブジェクトにアクセスするには、アクセス先の SWF ファイルが Security.allowDomain() メソッドを呼び出し、アクセス元の SWF ファイルのドメインによるアクセスを許可する必要があります。詳しくは、1017 ページの「作成者（開発者）コントロール」を参照してください。

Loader オブジェクトでロードされた Bitmap オブジェクトにアクセスするには、URL ポリシーファイルはイメージファイ
ルの元のサーバー上に存在する必要があり、その URL ポリシーファイルは、SWF ファイルのドメインに、Bitmap オブジェクトにアクセスする許可を付与する必要があります（1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照）。
ロードされたファイル（および Loader オブジェクト）に対応する LoaderInfo オブジェクトは、3 つのプロパティ（childAllowsParent、parentAllowsChild および sameDomain）を含んでおり、これらのプロパティはロードされたオブジェク
トと Loader オブジェクトの間の関係を定義します。

イベントセキュリティ
Flash Player 9 以降、Adobe AIR 1.0 以降
表示オブジェクトに関連するイベントには、イベントを送出する表示オブジェクトのサンドボックスに基づくセキュリティ
アクセスの制限があります。表示リストのイベントは、バブリング段階とキャプチャ段階に分けられます（119 ページの「イベント処理」を参照）。バブリングおよびキャプチャ段階では、イベントは表示リスト内のソース表示オブジェクトから親表示オブジェクトに移行します。親オブジェクトがソースの表示オブジェクトと異なるセキュリティサンドボックス内にある場合、キャプチャおよびバブリング段階はその親オブジェクトの下で停止します。ただし、親オブジェクトの所有者とソースオブジェクトの所有者の間に相互の信頼関係がある場合は除きます。この相互の信頼関係は、次のようにして達成できます。

1 親オブジェクトを所有する SWF ファイルは、ソースオブジェクトを所有する SWF ファイルのドメインを信頼するために、Security.allowDomain() メソッドを呼び出す必要があります。

2 ソースオブジェクトを所有する SWF ファイルは、親オブジェクトを所有する SWF ファイルのドメインを信頼するために、Security.allowDomain() メソッドを呼び出す必要があります。
ロードされたファイル（および Loader オブジェクト）に対応する LoaderInfo オブジェクトは、2 つのプロパティ(childAllowsParent および parentAllowsChild）を含んでおり、これらのプロパティはロードされたオブジェクトと Loader オ
ブジェクトの間の関係を定義します。
表示オブジェクト以外のオブジェクトから送出されたイベントの場合、セキュリティチェックやセキュリティ関連の影響はありません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1028

セキュリティ

ロードされたメディアへのデータとしてのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降ロードされたデータにアクセスするには、BitmapData.draw() メソッド、BitmapData.drawWithQuality() メソッドおよびSoundMixer.computeSpectrum() メソッドを使用します。デフォルトでは、別のサンドボックス内にロードされたメディアによってレンダリングまたは再生されるグラフィックオブジェクトまたはオーディオオブジェクトから、ピクセルデータまたはオーディオデータを取得できません。ただし、次のメソッドを使用すれば、このようなサンドボックス境界をまたがる
データへのアクセス許可を付与できます。

•

アクセス対象のデータをレンダリングまたは再生しているコンテンツ内で、Security.allowDomain() メソッドを呼び出し、別のドメインにあるコンテンツへのデータアクセスを許可します。

•

ロードされたイメージ、サウンドまたはビデオの場合は、ロードされたファイルのサーバー上で URL ポリシーファイル
を追加します。このポリシーファイルでは、BitmapData.draw() メソッド、BitmapData.drawWithQuality() メソッドまたは SoundMixer.computeSpectrum() メソッドを呼び出してファイルからデータを抽出しようとする SWF ファイルのドメ
インへのアクセスを許可する必要があります。drawWithQuality メソッドは Flash Player 11.3 以降および AIR 3.3 以降で使用できます。

次の節では、ビットマップ、サウンド、およびビデオのデータにアクセスする方法を詳しく説明します。

ビットマップデータへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
BitmapData オブジェクトの draw() メソッドと drawWithQuality() メソッド（Flash Player 11.3 および AIR 3.3）を使用す
ると、任意の表示オブジェクトの現在表示されているピクセルを BitmapData オブジェクトに描画できます。描画できるピ
クセルには、MovieClip オブジェクト、Bitmap オブジェクトまたは任意の表示オブジェクトのピクセルがあります。これらのメソッドを使用して BitmapData オブジェクトにピクセルを描画するには、次の条件を満たす必要があります。

•

ロードされたビットマップ以外のソースオブジェクトの場合、そのソースオブジェクトおよび（Sprite またはMovieClip オブジェクトの場合には）そのすべての子オブジェクトは、draw メソッドを呼び出すオブジェクトと同じドメインに属しているか、Security.allowDomain() メソッドを呼び出したことによって、呼び出し側からアクセスできる

SWF ファイル内に存在する必要があります。

•

ロードされたビットマップソースオブジェクトの場合、ソースオブジェクトは draw メソッドを呼び出すオブジェクトと同じドメインに属する必要があります。あるいはそのソースサーバーは、呼び出し側ドメインに権限を付与する URL ポ
リシーファイルをインクルードしている必要があります。

これらの条件が満たされない場合は、SecurityError 例外が発生します。
イメージをロードするとき、Loader クラスの load() メソッドを使用すると、LoaderContext オブジェクトである context
パラメーターを指定できます。LoaderContext オブジェクトの checkPolicyFile プロパティを true に設定した場合、Flash

Player は、イメージがロードされるサーバー上に URL ポリシーファイルがあるかどうかをチェックします。ポリシーファ
イルが存在し、そのファイルがロードを行おうとしている SWF ファイルのドメインを許可している場合、その SWF ファイ
ルは Bitmap オブジェクト内のデータにアクセスできます。それ以外の場合は、アクセスできません。
テキストフィールド内の <img> タグによってロードされるイメージで checkPolicyFile プロパティを指定することもできます。詳しくは、1024 ページの「テキストフィールドに <img > タグを使用した SWF ファイルとイメージのロード」を参照
してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1029

セキュリティ

サウンドデータへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
次のサウンド関連の ActionScript 3.0 API にはセキュリティ制限があります。

• SoundMixer.computeSpectrum() メソッド - サウンドファイルと同じセキュリティサンドボックス内で実行中のコードで常に使用できます。他のサンドボックス内で実行中のコードには、セキュリティチェックが行われます。

• SoundMixer.stopAll() メソッド - サウンドファイルと同じセキュリティサンドボックス内で実行中のコードで常に使用できます。他のサンドボックス内のファイルには、セキュリティチェックが行われます。

• Sound クラスの id3 プロパティ - サウンドファイルと同じセキュリティサンドボックス内にある SWF ファイルで常に使用できます。他のサンドボックス内で実行中のコードには、セキュリティチェックが行われます。
それぞれのサウンドに、コンテンツサンドボックスとオーナーサンドボックスの 2 種類のサンドボックスが関連付けられています。

•

サウンドの元のドメインはコンテンツサンドボックスを決定し、コンテンツサンドボックスは、サウンドの id3 プロパティと SoundMixer.computeSpectrum() メソッドによってサウンドからデータを抽出できるかどうかを決定します。

•

サウンドの再生を開始したオブジェクトは、所有者サンドボックスを決定し、所有者サンドボックスは、SoundMixer.stopAll() メソッドを使用してサウンドを停止できるかどうかを決定します。
サウンドをロードするとき、Sound クラスの load() メソッドを使用すると、SoundLoaderContext オブジェクトである

context パラメーターを指定できます。SoundLoaderContext オブジェクトの checkPolicyFile プロパティを true に設定した
場合、ランタイムは、サウンドがロードされるサーバー上に URL ポリシーファイルがあるかどうかをチェックします。ポ
リシーファイルがあり、ロードする側のコードのドメインがそのファイルで許可されている場合、そのコードは Sound オブ
ジェクトの id プロパティにアクセスできます。それ以外の場合はアクセスできません。また、checkPolicyFile プロパティの設定により、ロードされたサウンドの SoundMixer.computeSpectrum() メソッドを有効にできます。
SoundMixer.areSoundsInaccessible() メソッドを使用すると、呼び出し側からサウンド所有者のサンドボックスにアクセスできないので、SoundMixer.stopAll() メソッドの呼び出しがすべてのサウンドを停止できるかどうかを知ることができます。
SoundMixer.stopAll() メソッドを呼び出すと、所有者サンドボックスが stopAll() の呼び出し側と同じものであるサウンドが停止します。また、stopAll() メソッドを呼び出す SWF ファイルのドメインによるアクセスを許可するために

Security.allowDomain() メソッドを呼び出した SWF ファイルによって再生が開始されたサウンドも停止します。それ以外のサウンドは停止しません。そのようなサウンドの存在は、SoundMixer.areSoundsInaccessible() メソッドを呼び出すことによって確認できます。

computeSpectrum() メソッドを呼び出すには、再生中のすべてのサウンドが、このメソッドを呼び出すオブジェクトと同じ
サンドボックスに属するか、呼び出し側のサンドボックスに許可を付与したソースに属する必要があります。それ以外の場
合は、SecurityError 例外が発生します。SWF ファイル内でライブラリの埋め込みサウンドからロードされたサウンドの場
合、ロードされた SWF ファイルの Security.allowDomain() メソッドへの呼び出しを使用して許可を付与します。SWF ファ
イル以外のソースからロードされたサウンド（ロードされた MP3 ファイルまたはビデオファイルからのサウンド）の場合、
ソースサーバー上の URL ポリシーファイルが、ロードされたメディア内のデータへのアクセスを許可します。
詳しくは、1017 ページの「作成者（開発者）コントロール」および 1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照してください。

RTMP ストリームのサウンドデータにアクセスするには、サーバーでアクセスを許可する必要があります。Flash Media
Server にある特定のディレクトリへのアクセスを許可するには、サーバーサイド ActionScript の Client.audioSampleAccess
プロパティを使用します。詳しくは、『サーバーサイド ActionScript 言語リファレンス』を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1030

セキュリティ

ビデオデータへのアクセス
Flash Player 9 以降、Adobe AIR 1.0 以降
ビデオの現在のフレームのピクセルデータをキャプチャするには、BitmapData.draw() メソッドまたはBitmapData.drawWithQuality() メソッドを使用します（drawWithQuality メソッドは Flash Player 11.3 以降および AIR 3.3
以降で使用できます）。
ビデオには、次の 2 種類があります。

• Flash Media Server から RTMP 経由でストリーミング配信されるビデオ• FLV または F4V ファイルからロードされるプログレッシブビデオ
draw メソッドを使用して RTMP ストリームからランタイムグラフィックを抽出するには、サーバーでアクセスを許可する必要があります。Flash Media Server にある特定のディレクトリへのアクセスを許可するには、サーバーサイド
ActionScript の Client.videoSampleAccess プロパティを使用します。詳しくは、『サーバーサイド ActionScript 言語リファ
レンス』を参照してください。
プログレッシブビデオを source パラメーターとして draw メソッドを呼び出す場合は、メソッドの呼び出し側が FLV ファ
イルと同じサンドボックスに属しているか、FLV ファイルのサーバーに、呼び出しを行う SWF ファイルのドメインに許可を付与するポリシーファイルがある必要があります。NetStream オブジェクトの checkPolicyFile プロパティを true に設定して、ポリシーファイルがダウンロードされるように要求できます。

データのロードFlash Player 9 以降、Adobe AIR 1.0 以降
Flash Player および AIR コンテンツは、サーバーとデータをやり取りできます。データのロードはメディアのロードとは異なる種類の操作です。なぜなら、ロードされた情報は、メディアとして表示されず、プログラムオブジェクトとして表示されるからです。一般に、コンテンツは、コンテンツ自体のドメインからデータをロードします。ただし、別のドメインからのデータをロードする場合、通常はポリシーファイルが必要です。1013 ページの「Web サイトのコントロール（ポリシーファイル）」を参照してください。
注意：AIR アプリケーションサンドボックス内で実行中のコンテンツがリモートドメインから提供されることはありません（開発者が意図的にリモートコンテンツをアプリケーションサンドボックスに読み込む場合を除く）。したがって、ポリシー
ファイルによって防御されている攻撃にさらされる可能性はありません。アプリケーションサンドボックス内の AIR コンテ
ンツがデータをロードする場合、ポリシーファイルによる制限を受けません。ただし、他のサンドボックス内にある AIR コ
ンテンツは、ここで説明している制限を受けます。

URLLoader と URLStream の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
データは、XML ファイルまたはテキストファイルとしてロードできます。URLLoader クラスと URLStream クラスのload() メソッドは、URL ポリシーファイルの許可により制御されます。
load() メソッドを使用して、このメソッドを呼び出しているコードのドメイン以外のドメインからコンテンツをロードする
場合、ランタイムはロードされるアセットのサーバー上に URL ポリシーファイルがあるかどうかをチェックします。ポリ
シーファイルが存在し、ロードするコンテンツのドメインへのアクセスが許可されている場合は、データをロードできます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1031

セキュリティ

ソケットへの接続
Flash Player 9 以降、Adobe AIR 1.0 以降
デフォルトでは、ランタイムはポート 843 から提供されるソケットポリシーファイルを検索します。URL ポリシーファイ
ルと同様に、このファイルはマスターポリシーファイルと呼ばれます。
ポリシーファイルが最初に Flash Player 6 に導入されたとき、ソケットポリシーファイルのサポートはありませんでした。
ソケットサーバーへの接続は、ソケットサーバーと同じホストのポート 80 上にある HTTP サーバーのデフォルトの場所に置かれているポリシーファイルによって承認されていました。Flash Player 9 では、この機能が引き続きサポートされていますが、Flash Player 10 ではサポートされていません。Flash Player 10 では、ソケットポリシーファイルだけがソケット接続を承認できます。

URL ポリシーファイルと同様に、ソケットポリシーファイルは、ポリシーファイルを提供するポートを指定するメタポリ
シーステートメントをサポートします。しかし、ソケットポリシーファイルのデフォルトメタポリシーは、「マスターのみ」
ではなく「すべて」です。したがって、マスターポリシーファイルで高度な制限が設定されている場合を除き、Flash

Player では、ホスト上の任意のソケットがソケットポリシーファイルを提供できるものと見なされます。
接続先のソケットが SWF ファイルと同じドメインにある場合でも、ソケットへのアクセスおよび XML ソケット接続は、
デフォルトで無効です。次の場所のいずれかからソケットポリシーファイルを提供して、ソケットレベルのアクセスを許可
できます。

•

ポート 843（マスターポリシーファイルの場所）•

メインソケット接続と同じポート•

メインソケット接続以外のポート

デフォルトでは、Flash Player はポート 843 およびメインソケット接続と同じポートでソケットポリシーファイルを検索します。別のポートからソケットポリシーファイルを提供する場合、SWF ファイルは、Security.loadPolicyFile() を呼び出す必要があります。
ソケットポリシーファイルのシンタックスは URL ポリシーファイルと同じですが、アクセスを許可するポートも指定する必要がある点が異なります。ソケットポリシーファイルが 1024 未満のポート番号から提供される場合、任意のポートへのアクセスが許可されます。ポリシーファイルがポート 1024 以上のポートから提供される場合、1024 以上のポートへのアクセスのみが許可されます。許可するポートは、<allow-access-from> タグの to-ports 属性で指定します。指定できる値は、単一のポート番号、ポート範囲、およびワイルドカードです。
次に、ソケットポリシーファイルの例を示します。
<?xml version="1.0"?><!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd"><!-- Policy file for xmlsocket://socks.mysite.com --><cross-domain-policy><allow-access-from domain="*" to-ports="507" /><allow-access-from domain="*.example.com" to-ports="507,516" /><allow-access-from domain="*.example.org" to-ports="516-523" /><allow-access-from domain="adobe.com" to-ports="507,516-523" /><allow-access-from domain="192.0.34.166" to-ports="*" /></cross-domain-policy>

ポート 843 またはメインソケット接続と同じポートからソケットポリシーファイルを取得するには、Socket.connect() または XMLSocket.connect() メソッドを呼び出します。Flash Player は、最初にポート 843 上のマスターポリシーファイルをチェックします。マスターポリシーファイルが見つかった場合、Flash Player は、ターゲットポート上のソケットポリシー
ファイルを禁止するメタポリシーステートメントがファイルに含まれているかどうかをチェックします。アクセスが禁止されていない場合、マスターポリシーファイル内の適切な allow-access-from ステートメントが最初に検索されます。適切なス
テートメントが見つからない場合、メインソケット接続と同じポート上でソケットポリシーファイルが検索されます。
別の場所からソケットポリシーファイルを取得するには、次に示すように、最初に特別な「xmlsocket」シンタックスでSecurity.loadPolicyFile() メソッドを呼び出します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1032

セキュリティ

Security.loadPolicyFile("xmlsocket://server.com:2525");

Socket.connect() または XMLSocket.connect() メソッドを呼び出す前に Security.loadPolicyFile() メソッドを呼び出します。その場合、Flash Player は、ユーザーのメイン接続を許可するかどうかを決める前に、ユーザーのポリシーファイル要求が満たされるのを待ちます。しかし、ターゲットの場所でポリシーファイルを提供できないことがマスターポリシーファイルで指定されている場合は、その場所にポリシーファイルが存在していても loadPolicyFile() への呼び出しは無効です。
ソケットサーバーを実装し、ソケットポリシーファイルを提供する必要がある場合は、ポリシーファイルを提供するのに、メイン接続を受け入れるのと同じポートを使用するか、別のポートを使用するかを決めてください。いずれの場合も、サーバーは、クライアントからの最初の送信を待ってから応答を送信する必要があります。

Flash Player は、ポリシーファイルを要求する場合、接続が確立されると同時に、必ず次のストリングを送信します。
<policy-file-request/>

サーバーはこのストリングを受信すると、ポリシーファイルを送信できます。Flash Player からの要求は、常に null バイト
によって終了し、サーバーからの応答も null バイトで終了する必要があります。
同じ接続をポリシーファイル要求とメイン接続の両方に再使用しないでください。ポリシーファイルの送信後は、接続を閉
じてください。そのようにしなかった場合、Flash Player はポリシーファイル接続を閉じてから、再接続してメイン接続を設定します。

データの保護Flash Player 9 以降、Adobe AIR 1.0 以降
インターネット上に配信されるデータを漏えいや改ざんから保護するために、データの送信元のサーバーで、トランスポー
ト層セキュリティ（TLS）またはセキュアソケットレイヤー（SSL）を使用できます。これで、HTTPS プロトコルを使用
してサーバーに接続できます。

AIR 2 以降向けに作成されたアプリケーションでは、TCP ソケット通信を保護することもできます。SecureSocket クラス
を使用すると、TLS バージョン 1 または SSL バージョン 4 を使用するソケットサーバーに対するソケット通信を開始できます。

データの送信Flash Player 9 以降、Adobe AIR 1.0 以降
データ送信は、コードによりサーバーまたはリソースにデータが送信されるときに発生します。ネットワークドメインのコンテンツでは、常にデータの送信を実行できます。ローカル SWF ファイルは、その SWF ファイルが local-trusted サンドボックス、local-with-networking サンドボックスまたは AIR アプリケーションサンドボックスに入っている場合にのみ、
ネットワークアドレスにデータを送信できます。詳しくは、1006 ページの「ローカルサンドボックス」を参照してください。

flash.net.sendToURL() 関数を使用すると、URL にデータを送信できます。それ以外のメソッドも、URL に要求を送信します。これらのメソッドには、Loader.load() や Sound.load() などのロードメソッドと URLLoader.load() や URLStream.load() な
どのデータロードメソッドがあります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1033

セキュリティ

ファイルのアップロードとダウンロード
Flash Player 9 以降、Adobe AIR 1.0 以降
FileReference.upload() メソッドは、ユーザーによって選択されたファイルのリモートサーバーへのアップロードを開始します。FileReference.upload() メソッドを呼び出す前に、FileReference.browse() メソッドまたは FileReferenceList.browse() メソッ
ドを呼び出す必要があります。
FileReference.browse() メソッドまたは FileReferenceList.browse() メソッドを開始するコードは、マウスイベントまたはキー
ボードイベントへの応答としてのみ呼び出すことができます。別の状況で呼び出された場合、Flash Player は例外をスローします。ただし、AIR アプリケーションサンドボックスからこれらのメソッドを呼び出す場合、ユーザーイベントは必要ありません。
FileReference.download() メソッドを呼び出すと、ユーザーがリモートサーバーからファイルをダウンロードできるダイアロ
グボックスが開きます。
注意：サーバーでユーザー認証が必要な場合、ブラウザー内で実行される、つまり、ブラウザープラグインまたは ActiveX
コントロールを使用する SWF ファイルでのみ、認証用のユーザー名とパスワードをユーザーが入力できるダイアログボッ
クスを表示できます。ただし、それはダウンロードの場合のみです。Flash Player では、ユーザー認証が必要なサーバーへのアップロードはできません。
呼び出しを行う SWF ファイルが local-with-filesystem サンドボックス内にある場合、アップロードとダウンロードは許可されません。
デフォルトでは、SWF ファイルは、それ自体のサーバー以外のサーバーとの間でアップロードまたはダウンロードを行うことはできません。SWF ファイルは、別のサーバーへのアップロードまたはダウンロードが可能ですが、そのサーバーに、呼び出し側 SWF ファイルのドメインに許可を付与するポリシーファイルが格納されている必要があります。

セキュリティドメインに読み込まれた SWF ファイルからの埋め込みコンテンツのロード
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルをロードするとき、ファイルをロードするために使用する Loader オブジェクトの load() メソッドの context
パラメーターを設定できます。このパラメーターは、LoaderContext オブジェクトを取得します。この LoaderContext オ
ブジェクトの securityDomain プロパティを Security.currentDomain に設定すると、Flash Player はロードされた SWF ファ
イルのサーバー上に URL ポリシーファイルがあるかどうかをチェックします。ポリシーファイルが存在し、そのファイルでロードする側の SWF ファイルのドメインへのアクセスが許可されている場合、SWF ファイルを読み込んだメディアとしてロードできます。この方法により、ロードする側のファイルは、SWF ファイルのライブラリにあるオブジェクトにアクセスできるようになります。

SWF ファイルから別のセキュリティサンドボックスにあるロードされた SWF ファイルのクラスにアクセスするもう 1 つの方法は、ロードされた SWF ファイルで Security.allowDomain() メソッドを呼び出し、呼び出す側の SWF ファイルのドメイ
ンへのアクセスを許可することです。Security.allowDomain() メソッドの呼び出しを、ロードされた SWF ファイルのメイン
クラスのコンストラクターメソッドに追加し、その後、ロードする側の SWF ファイルで、Loader オブジェクトの
contentLoaderInfo プロパティによって送出された init イベントに応答するイベントリスナーを追加することができます。このイベントが送出される時点で、ロードされた SWF ファイルはコンストラクターメソッド内の Security.allowDomain() メ
ソッドの呼び出しを完了しており、ロードされた SWF ファイル内のクラスは、ロードする側の SWF ファイルから使用可能です。ロードする側の SWF ファイルは、Loader.contentLoaderInfo.applicationDomain.getDefinition() またはLoader.contentLoaderInfo.applicationDomain.getQualifiedDefinitionNames()（Flash Player 11.3 以降および AIR
3.3 以降）を呼び出すことにより、ロードされた SWF ファイルからクラスを取得できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1034

セキュリティ

古いコンテンツの操作
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player 6 では、特定の Flash Player 設定に使用されるドメインは、SWF ファイルのドメインの最後の部分に基づいています。この設定には、カメラとマイクの許可、記憶領域の割り当て、永続共有オブジェクトの記憶領域などがあります。

www.example.com のように SWF ファイルのドメインに 3 つ以上のセグメントが含まれている場合、ドメインの最初のセグメント（www）は削除され、ドメインの残りの部分が使用されます。したがって、Flash Player 6 では、www.example.com と store.example.com はどちらも example.com をこれらの設定のドメインとして使用します。同様に、www.example.co.uk と store.example.co.uk はどちらも example.co.uk をこれらの設定のドメインとして使用します。このため、example1.co.uk と example2.co.uk など、互いに無関係のドメインの SWF ファイルが、同じ共有オブジェ
クトにアクセスできるという問題が起きる場合があります。

Flash Player 7 以降では、プレーヤー設定はデフォルトで SWF ファイルの正確なドメインに従って選択されます。例えば、
www.example.com の SWF ファイルは www.example.com のプレーヤー設定を使用し、store.example.com の SWF ファ
イルはそれとは別の store.example.com のプレーヤー設定を使用します。
ActionScript 3.0 で記述された SWF ファイルでは、Security.exactSettings が true に設定された場合（デフォルト）、Flash
Player はプレーヤー設定に正確なドメインを使用します。false に設定された場合、Flash Player は Flash Player 6 で使用されていたドメイン設定を使用します。exactSettings をデフォルト値から変更する場合は、Flash Player でプレーヤー設定を選択する必要があるイベントが発生する前にその変更を行う必要があります。例えば、カメラまたはマイクの使用や永続共有オブジェクトの取得などのイベントが発生する前です。
バージョン 6 の SWF ファイルをパブリッシュし、そこから永続共有オブジェクトを作成した場合、ActionScript 3.0 を使用する SWF から永続共有オブジェクトを取得するには、SharedObject.getLocal() を呼び出す前に、Security.exactSettings を

false に設定する必要があります。

LocalConnection 許可の設定
Flash Player 9 以降、Adobe AIR 1.0 以降
LocalConnection クラスを使用すると、Flash Player 間または AIR アプリケーション間で相互にメッセージを送信できます。LocalConnection オブジェクトを使用して通信できるのは、同じクライアントコンピューター上で実行中の Flash
Player 間または AIR コンテンツ間だけです。ただし、実行されているアプリケーションが異なっても構いません。例えば、ブラウザで実行されている SWF ファイル、プロジェクターで実行されている SWF ファイルおよび AIR アプリケーション
はすべて、LocalConnection クラスを使用して通信できます。
すべての LocalConnection 通信に、送信側と受信側が存在します。Flash Player では、デフォルトで、同じドメイン内で実行中のコード間における LocalConnection 通信が可能です。別のサンドボックス内で実行中のコードの場合、受信側はLocalConnection.allowDomain() メソッドを使用して送信側に許可を付与する必要があります。
LocalConnection.allowDomain() メソッドへ引数として渡すストリングには、正確なドメイン名、IP アドレスおよび * ワイル
ドカードを含めることができます。。
allowDomain() メソッドは、ActionScript 1.0 および 2.0 での形式から変更されています。これらの以前のバージョンでは、
allowDomain() はユーザーが実装するコールバックメソッドでした。ActionScript 3.0 では、allowDomain() は、ユーザーが呼び出す LocalConnection クラスのビルトインメソッドです。この変更により、allowDomain() は Security.allowDomain()とほとんど同じように動作します。

SWF ファイルは LocalConnection クラスの domain プロパティを使用して、そのドメインを決定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1035

セキュリティ

送信 URL アクセスの制御
Flash Player 9 以降、Adobe AIR 1.0 以降
送信スクリプトおよび（HTTP URL、mailto: などを介した）URL アクセスは、次の API を使用して行われます。

• flash.system.fscommand() 関数• ExternalInterface.call() メソッド
• flash.net.navigateToURL() 関数
ローカルファイルシステムからロードされるコンテンツの場合、コードとこれを含む Web ページ（存在する場合）がlocal-trusted または AIR アプリケーションのいずれかのセキュリティサンドボックス内に置かれている場合にのみ、上記のメソッドを正常に呼び出すことができます。上記のメソッドの呼び出しが失敗するのは、コンテンツが local-with-

networking または local-with-filesystem のいずれかのサンドボックス内にある場合です。
ローカルでロードされていないコンテンツの場合、次に説明する AllowScriptAccess パラメーターの値に応じて、これらのAPI はすべてその API が埋め込まれている Web ページと通信できます。flash.net.navigateToURL() 関数には、SWF ファイ
ルが埋め込まれているページだけではなく、開いているブラウザーウィンドウまたはフレームと通信する追加機能があります。この機能について詳しくは、1036 ページの「navigateToURL() 関数の使用」を参照してください。

SWF ファイルをロードする HTML コード内の AllowScriptAccess パラメーターは、SWF ファイル内から送信 URL アクセスを実行する機能を制御します。このパラメーターは PARAM または EMBED タグの内部で設定します。
AllowScriptAccess に値を設定しない場合、SWF ファイルと HTML ページは、その両方が同じドメインにある場合にのみ通信できます。

AllowScriptAccess パラメーターには、3 つの値（「always」、「sameDomain」または「never」）のいずれかを設定できます。

• AllowScriptAccess が「always」に設定されている場合、SWF ファイルと HTML ページのドメインが異なる場合でも、SWF ファイルは埋め込み先の HTML ページと通信できます。
• AllowScriptAccess が「sameDomain」に設定されている場合、SWF ファイルと HTML ページのドメインが同じでないと、SWF ファイルは埋め込み先の HTML ページと通信できません。この値は、AllowScriptAccess のデフォルト値です。
この設定を使用した場合または AllowScriptAccess に値を設定しない場合、1 つのドメインでホストされる SWF ファイルは、別のドメインにある HTML ページのスクリプトにアクセスできなくなります。
• AllowScriptAccess が「never」に設定されていると、SWF ファイルはどの HTML ページとも通信できません。Adobe
Flash CS4 Professional のリリース以降、この値の使用は推奨されていません。自身のドメインの信頼されない SWF
ファイルを処理しない場合は、この値の使用は推奨されず、通常は必要もありません。信頼されていない SWF ファイルを提供する必要がある場合は、区別するためのサブドメインを作成し、信頼されていないコンテンツはすべてそこに配置することをお勧めします。
別のドメインへの送信 URL アクセスを許可する HTML ページ内の AllowScriptAccess タグの設定例を次に示します。
<object id='MyMovie.swf' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'
codebase='http://download.adobe.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0' height='100%'
width='100%'><param name='AllowScriptAccess' value='always'/><param name='src' value=''MyMovie.swf'/><embed name='MyMovie.swf' pluginspage='http://www.adobe.com/go/getflashplayer' src='MyMovie.swf'
height='100%' width='100%' AllowScriptAccess='never'/></object>

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1036

セキュリティ

navigateToURL() 関数の使用
Flash Player 9 以降、Adobe AIR 1.0 以降
前述の allowScriptAccess パラメーターで指定するセキュリティ設定に加えて、navigateToURL() 関数に 2 番目のオプション
パラメーター target があります。target パラメーターを使用して、URL 要求の送信先の HTML ウィンドウまたはフレームの名前を指定できます。そのような要求に追加のセキュリティ制限が適用されます。制限は、navigateToURL() がスクリプ
トステートメントと非スクリプトステートメントのどちらとして使用されているかによって異なります。

navigateToURL("javascript: alert('Hello from Flash Player.')") などのスクリプトステートメントの場合、次のルールが適用されます。

• SWF ファイルがローカルで信頼されているファイルの場合、要求は成功します。
• SWF ファイルが埋め込まれている HTML ページがターゲットの場合、前述の allowScriptAccess ルールが適用されます。
• SWF ファイルと同じドメインからロードされたコンテンツがターゲットに格納されている場合、要求は成功します。
• SWF ファイルとは別のドメインからロードされたコンテンツがターゲットに格納されていて、前の 2 つの条件のいずれも適合しない場合、要求は失敗します。

HTTP、HTTPS、mailto: などの非スクリプトステートメントの場合、次のすべての条件が満たされると要求は失敗します。

•

ターゲットが特殊キーワード（「_top」または「_parent」）の 1 つである。

•

別のドメインでホストされる Web ページに SWF ファイルが含まれている。

• 「always」以外の値の allowScriptAccess と一緒に SWF ファイルが埋め込まれている。

詳細情報
Flash Player 9 以降、Adobe AIR 1.0 以降
送信 URL アクセスについて詳しくは、『Adobe Flash Platform 用 ActionScript 3.0 リファレンスガイド』の次の項目を参照してください。

• flash.system.fscommand() 関数• ExternalInterface クラスの call() メソッド
• flash.net.navigateToURL() 関数

共有オブジェクト
Flash Player 9 以降、Adobe AIR 1.0 以降
Flash Player では、共有オブジェクト（SWF ファイルの外部で存続する ActionScript オブジェクト）をユーザーのローカ
ルファイルシステム上だけでなく、リモート RTMP サーバー上でも使用することができます。共有オブジェクトは、Flash
Player 内のその他のメディアと同様に、いくつかのセキュリティサンドボックスに区分されます。しかし、共有オブジェク
トのサンドボックスモデルは、少し異なっています。なぜなら、共有オブジェクトはドメインの境界を越えてアクセスできるリソースではないからです。共有オブジェクトは常に、SharedObject クラスのメソッドを呼び出す各 SWF ファイルのドメインに固有の共有オブジェクトストアから取得されます。通常、共有オブジェクトストアは SWF ファイルのドメインよりもさらに細分化されています。デフォルトでは、それぞれの SWF ファイルごとに、その元の URL 全体に固有の共有オブジェクトストアが使用されます。共有オブジェクトについて詳しくは、676 ページの「共有オブジェクト」を参照してくだ
さい。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1037

セキュリティ

SWF ファイルは SharedObject.getLocal() および SharedObject.getRemote() メソッドの localPath パラメーターを使用して、その URL の一部分だけに関連付けられた共有オブジェクトストアを使用することができます。この方法により、SWF ファイ
ルは、他の URL からの別の SWF ファイルとの共有を許可できます。localPath パラメーターとして「/」を渡した場合でも、独自のドメインに固有の共有オブジェクトストアが指定されます。

Flash Player の設定ダイアログボックスまたは設定マネージャーを使用して、共有オブジェクトへのアクセスを制限できます。デフォルトでは、ドメインごとに最大 100KB のデータサイズまでの共有オブジェクトを作成できます。管理ユーザーおよび一般ユーザーは、ファイルシステムへの書き込み機能に制限を適用することもできます。詳しくは、1010 ページの「管理ユーザーのコントロール」および 1012 ページの「ユーザーのコントロール」を参照してください。
共有オブジェクトがセキュアであることを指定するには、SharedObject.getLocal() メソッドまたは SharedObject.getRemote()
メソッドの secure パラメーターに true を指定します。secure パラメーターについて、次の点に注意してください。

•

このパラメーターを true に設定すると、Flash Player は新しいセキュアな共有オブジェクトを作成するか、既存のセキュアな共有オブジェクトの参照を取得します。このセキュアな共有オブジェクトに対する読み取りまたは書き込みは、

HTTPS で配信された SWF ファイルによってのみ行えます。このとき SWF ファイルは SharedObject.getLocal() を、
secure パラメーターを true に設定して呼び出します。

•

このパラメーターが false に設定された場合、Flash Player は共有オブジェクトを新しく作成するか、または HTTPS 以外の接続で配信された SWF ファイルにより読み込みまたは書き込みのできる既存の共有オブジェクトの参照を取得します。

呼び出し側の SWF ファイルが HTTPS URL からのものでない場合、SharedObject.getLocal() メソッドまたはSharedObject.getRemote() メソッドの secure パラメーターに true を指定すると、SecurityError 例外が発生します。
共有オブジェクトストアの選択は、SWF ファイルの元の URL に基づきます。このことは、SWF ファイルが単純な URL
から提供されない 2 つの状況でも当てはまります。それらの状況は、読み込みロードとダイナミックロードです。読み込み
ロードとは、LoaderContext.securityDomain プロパティを SecurityDomain.currentDomain に設定して SWF ファイルをロードする状況のことです。この状況では、ロードされた SWF ファイルは、ロードする側の SWF ファイルのドメインで始まり、その後に実際の元の URL を指定した疑似 URL を持ちます。ダイナミックロードとは、Loader.loadBytes() メソッドを使用して SWF ファイルをロードすることです。この状況では、ロードされた SWF ファイルは、ロードする側の SWF ファイルの
完全な URL で始まり、その後に整数 ID が続く擬似 URL を持ちます。読み込みロードとダイナミックロードの両方で、LoaderInfo.url プロパティを使用して SWF ファイルの疑似 URL を検証できます。疑似 URL は、共有オブジェクトストア
を選択する目的で実 URL とまったく同じように扱われます。疑似 URL の一部または全部を使用する、共有オブジェクトの
localPath パラメーターを指定できます。
ユーザーおよび管理者は、サードパーティー共有オブジェクトの使用を無効にすることもできます。この場合は、Web ブラ
ウザー内で実行されているすべての SWF ファイルが共有オブジェクトを使用し、その SWF ファイルの元の URL は、ブラウザーのアドレスバーに表示される URL と異なるドメインに属しています。ユーザーと管理者は、プライバシーの理由から、クロスドメイントラッキングを避けるために、サードパーティー共有オブジェクトの使用を無効にすることもできます。
この制限を回避するために、共有オブジェクトを使用するすべての SWF ファイルが、ブラウザーのアドレスバーに表示されているのと同じドメインから SWF ファイルが提供される HTML ページ構造内でのみロードされるようにすることもできます。サードパーティー SWF ファイルの共有オブジェクトを使用しようとして、サードパーティー共有オブジェクトの使用が無効の場合、SharedObject.getLocal() および SharedObject.getRemote() メソッドは null を返します。詳しくは、

www.adobe.com/jp/products/flashplayer/articles/thirdpartylso を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1038

セキュリティ

カメラ、マイク、クリップボード、マウス、キーボードのア
クセス
Flash Player 9 以降、Adobe AIR 1.0 以降
SWF ファイルが Camera.get() または Microphone.get() メソッドを使用してユーザーのカメラまたはマイクにアクセスしようとした場合、Flash Player にはプライバシーダイアログボックスが表示されます。このダイアログボックスで、ユーザーはカメラおよびマイクへのアクセスを許可または拒否できます。ユーザーと管理ユーザーは、mms.cfg ファイル、設定 UI お
よび設定マネージャーのコントロールを通じて、カメラアクセスをサイト別またはグローバルに無効にすることもできます（1010 ページの「管理ユーザーのコントロール」および 1012 ページの「ユーザーのコントロール」を参照）。ユーザー制限があると、Camera.get() および Microphone.get() メソッドは null 値を返します。Capabilities.avHardwareDisable プロパティを使用すると、カメラおよびマイクが管理上禁止されているか（true）または許可されているか（false）を特定できます。

System.setClipboard() メソッドでは、SWF ファイルでクリップボードの内容をプレーンテキストストリング文字に置き換えることができます。これにより、セキュリティリスクが発生することはありません。パスワードなどの機密データがクリップボードにカットまたはコピーされることによるリスクを防ぐため、対応する getClipboard() メソッドはありません。

Flash Player で実行中のアプリケーションは、フォーカス内で発生するキーボードイベントおよびマウスイベントのみを監視できます。Flash Player で実行中のコンテンツは、他のアプリケーションのキーボードイベントまたはマウスイベントを検出できません。

AIR のセキュリティ
Adobe AIR 1.0 およびそれ以降

AIR のセキュリティの基礎
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、ネイティブアプリケーションと同じセキュリティ制限で実行されます。一般的に、AIR アプリ
ケーションでは、ネイティブアプリケーションと同様に、ファイルの読み取りや書き込み、アプリケーションの起動、画面への描画、ネットワークとの通信など、オペレーティングシステム機能に広範囲にアクセスできます。ネイティブアプリ
ケーションに適用されるオペレーティングシステムの制限（ユーザー固有の権限など）は、AIR アプリケーションにも同等に適用されます。

Adobe® AIR® のセキュリティモデルは Adobe® Flash® Player のセキュリティモデルの進化形ですが、セキュリティコント
ラクトは、ブラウザーのコンテンツに適用されるセキュリティコントラクトとは異なります。このコントラクトは、開発者に、ブラウザーベースのアプリケーションには十分すぎるほど自由にリッチエクスペリエンスを実現できる豊富な機能を提供します。

AIR アプリケーションは、コンパイル済みバイトコード（SWF コンテンツ）またはインタープリットされるスクリプト（JavaScript、HTML）のいずれかを使用して作成されているので、ランタイムでメモリ管理できます。これにより、メモリ管理に関連する脆弱性（バッファーオーバーフローやメモリの破損など）によって AIR アプリケーションが影響を受ける
可能性を最小限に抑えることができます。これらは、ネイティブコードで作成されたデスクトップアプリケーションに影響を与える最も一般的な脆弱性の一部です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1039

セキュリティ

インストールとアップデート
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、拡張子が air の AIR インストーラーファイルまたはネイティブインストーラーを使用して配布されます。ネイティブインストーラーでは、ネイティブプラットフォームのファイル形式と拡張子を使用します。例えば、

Windows のネイティブインストーラーの形式は EXE ファイルです。Android のネイティブインストーラーの形式は APK
ファイルです。

Adobe AIR がインストールされている環境で AIR インストーラーファイルを開く場合、AIR ランタイムによってインス
トールプロセスが管理されます。ネイティブインストーラーを使用する場合、オペレーティングシステムによってインス
トールプロセスが管理されます。
注意：AIR ファイル形式を使用する場合、開発者はバージョン、アプリケーション名、発行者ソースを指定できますが、ア
プリケーションのインストールの最初のワークフロー自体は変更できません。ランタイムによって管理される安全で合理化された一貫性のあるインストール手順をすべての AIR アプリケーションで共有できるので、この制限はユーザーにとってメリットになります。アプリケーションのカスタマイズが必要な場合は、アプリケーションを初めて実行するときに指定できます。

ランタイムのインストール先Adobe AIR 1.0 およびそれ以降
SWF ファイルで最初に Flash Player ブラウザープラグインをインストールする必要があるのと同様に、AIR ファイル形式を使用する AIR アプリケーションでも、最初にランタイムをユーザーのコンピューターにインストールする必要があります。
ランタイムはデスクトップコンピューター上の次の場所にインストールされます。

• Mac OS：/Library/Frameworks/• Windows：C:¥Program Files¥Common Files¥Adobe AIR• Linux：/opt/Adobe AIR/
Mac OS でアプリケーションのアップデートバージョンをインストールするには、アプリケーションディレクトリにインストールするための適切なシステム権限が必要です。Windows および Linux では、管理権限が必要です。
注意：iOS では、各 AIR ランタイムは個別にインストールされません。それぞれの AIR アプリケーションは 1 つのアプリ
ケーションに統合されています。
ランタイムは 2 つの方法でインストールできます。1 つはシームレスインストール機能を使用する（Web ブラウザーから直接インストールする）方法で、もう 1 つは手動でインストールする方法です。また、AIR アプリケーションをネイティブイ
ンストーラーとしてパッケージ化する場合は、通常のアプリケーションインストール処理の一環として AIR ランタイムのイ
ンストールも行うようにすることができます（この方法で AIR ランタイムを配布するには、アドビとの再配布契約が必要です）。

シームレスインストール（ランタイムおよびアプリーション）
Adobe AIR 1.0 およびそれ以降
シームレスインストール機能を使用すると、開発者は、Adobe AIR をインストールしていないユーザーに合理化されたイ
ンストールエクスペリエンスを提供できます。シームレスインストール方法では、開発者はインストール対象のアプリケー
ションを表す SWF ファイルを作成します。ユーザーが SWF ファイルをクリックしてアプリケーションをインストールすると、SWF ファイルはランタイムの検出を試みます。ランタイムが検出されない場合、ランタイムはインストールされて、開発者のアプリケーションのインストールプロセスですぐに有効化されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1040

セキュリティ

手動によるインストール
Adobe AIR 1.0 およびそれ以降ユーザーが AIR ファイルを開く前にランタイムを手動でダウンロードしてインストールすることもできます。この場合、開発者は様々な方法（電子メールや Web サイト上の HTML リンクなど）で AIR ファイルを配布できます。AIR ファイルを開くと、ランタイムはアプリケーションのインストール処理を開始します。

アプリケーションのインストールフロー
Adobe AIR 1.0 およびそれ以降
AIR のセキュリティモデルでは、ユーザーが AIR アプリケーションをインストールするかどうかを決定できます。AIR イン
ストールエクスペリエンスでは、ユーザーがこの信用判断をより簡単に行うことができるように、ネイティブアプリケー
ションのインストールテクノロジにいくつかの改良が行われています。

•

ランタイムは、AIR アプリケーションが Web ブラウザー内のリンクからインストールされる場合でも、すべてのオペ
レーティングシステムで一貫したインストールエクスペリエンスを提供します。ネイティプアプリケーションのインス
トールエクスペリエンスは、セキュリティ情報がすべて提供される場合、セキュリティ情報を提供するブラウザーまたは
他のアプリケーションに依存します。

• AIR アプリケーションのインストールエクスペリエンスでは、アプリケーションのソースと、アプリケーションで使用可能な権限（ユーザーがインストールの処理を許可されている場合）に関する情報を識別します。

•

ランタイムは、AIR アプリケーションのインストールプロセスを管理します。AIR アプリケーションは、ランタイムが使用するインストールプロセスを操作できません。

一般的に、ユーザーは信頼していないソース、または検証できないソースからのデスクトップアプリケーションはインス
トールしません。他のインストール可能なアプリケーションと同様に、ネイティブアプリケーションのセキュリティに関する立証責任は、AIR アプリケーションにも同等に当てはまります。

アプリケーションのインストール先Adobe AIR 1.0 およびそれ以降
インストールディレクトリは、次の 2 つのオプションのいずれかを使用して設定できます。

1 ユーザーがインストール中にインストール先をカスタマイズします。アプリケーションは、ユーザーが指定した場所にインストールされます。

2 ユーザーがインストール先を変更しない場合、アプリケーションはランタイムが指定した次のデフォルトパスにインストールされます。

• Mac OS：~/Applications/• Windows XP 以前：C:¥¥rogram Files¥• Windows Vista：~¥¥• Linux：/opt/
開発者がアプリケーション記述ファイルで installFolder 設定を指定している場合は、このディレクトリのサブパスにアプ
リケーションがインストールされます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1041

セキュリティ

AIR ファイルシステム
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションのインストールプロセスでは、開発者が AIR インストーラーファイルに含めたすべてのファイルがユーザーのローカルコンピューターにコピーされます。インストールされたアプリケーションの構成は次のとおりです。

• Windows：AIR インストーラーファイルに含まれるすべてのファイルを格納するディレクトリ。AIR アプリケーショ
ンのインストール時にはランタイムによって exe ファイルも作成されます。
• Linux：AIR インストーラーファイルに含まれるすべてのファイルを格納するディレクトリ。AIR アプリケーションのインストール時にはランタイムによって bin ファイルも作成されます。
• Mac OS：AIR インストーラーファイルのコンテンツがすべて含まれる app ファイル。このファイルは、Finder の「Show Package Contents」オプションを使用して調べることができます。ランタイムはこの app ファイルを AIR アプ
リケーションのインストール中に作成します。

AIR アプリケーションは次の方法で実行されます。

• Windows：インストールフォルダーで .exe ファイル、またはこのファイルに対応するショートカット（スタートメ
ニューまたはデスクトップのショートカットなど）を実行します。

• Linux：インストールフォルダーの .bin ファイルを起動、アプリケーションメニューのアプリケーションを選択、またはエイリアスやデスクトップショートカットからアプリケーションを実行します。

• Mac OS：.app ファイル、または .app ファイルを参照するエイリアスを実行します。
アプリケーションファイルシステムには、アプリケーションの機能に関連するサブディレクトリも含まれます。例えば、暗号化されたローカル記憶領域に書き込まれた情報は、アプリケーションのアプリケーション ID に基づく名前が付いたディレクトリ内のサブディレクトリに保存されます。

AIR アプリケーション記憶領域
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、ユーザーのハードディスク上のどの場所にも書き込むことができる権限を持っています。ただし、開発者は、作成したアプリケーションに関連するローカル記憶領域に app-storage:/ パスを使用することをお勧めします。
アプリケーションから app-storage:/ に書き込まれたファイルは、ユーザーのオペレーティングシステムの標準の保存場所に保存されます。

• Mac OS：アプリケーションの記憶領域ディレクトリは AIR バージョンごとに異なります。
• AIR 3.2 以降 - <appData>/<appId>/Local Store/ です。ここで、<appData> はユーザーの「環境設定フォルダー」であり、通常は /Users/<user>/Library/Preferences になります。

• AIR 3.3 以降 - <path>/Library/Application Support/<appID>/Local Store です。ここで、<path> は/Users/<user>/Library/Containers/<bundle-id>/Data（サンドボックス化した環境の場合）または /Users/<user>（サンドボックス化した環境外で実行する場合）です。

• Windows：アプリケーションの記憶領域ディレクトリは <appData>¥>¥¥ です。ここで、<appData> は、ユーザーの
CSIDL_APPDATA 「特殊フォルダー」で、通常は C:¥Documents and Settings¥<user>¥Application Data になります。
• Linux：<appData>/<appID>/Local Store/ です。ここで、<appData> は、/home/<user>/.appdata です。
アプリケーション記憶領域ディレクトリには、air.File.applicationStorageDirectory プロパティを介してアクセスできます。このディレクトリのコンテンツには、File クラスの resolvePath() メソッドを使用してアクセスできます。詳しくは、628 ページの「ファイルシステムの操作」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1042

セキュリティ

Adobe AIR のアップデート
Adobe AIR 1.0 およびそれ以降
ランタイムのアップデートバージョンを必要とする AIR アプリケーションをユーザーがインストールすると、ランタイムによって必要なランタイムアップデートが自動的にインストールされます。
ランタイムをアップデートする作業は、当該コンピューターの管理権限を持つユーザーが実行する必要があります。

AIR アプリケーションのアップデート
Adobe AIR 1.0 およびそれ以降
ソフトウェアアップデートの開発と展開は、ネイティブコードアプリケーションの中でも最も大きなセキュリティ問題の 1
つです。AIR API には、この問題を改善するメカニズムが用意されています。Updater.update() メソッドを起動時に呼び出して、リモートの場所に AIR ファイルがあるかどうか確認することができます。アップデートが必要な場合、AIR ファイルがダウンロード、インストールされ、アプリケーションが再起動します。開発者はこのクラスを、新しい機能を提供するためだけでなく、潜在的なセキュリティの脆弱性に対処するためにも使用できます。

Updater クラスは、AIR ファイルとして配布されたアプリケーションの更新にのみ使用できます。ネイティブアプリケー
ションとして配布されたアプリケーションでは、ネイティブオペレーティングシステムの更新機能があれば、それを使用する必要があります。
注意：開発者はアプリケーション記述ファイルの versionNumber プロパティを設定してアプリケーションのバージョンを指定できます。

AIR アプリケーションのアンインストール
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションを削除すると、アプリケーションディレクトリ内のすべてのファイルが削除されます。ただし、アプ
リケーションがアプリケーションディレクトリ以外のディレクトリに書き込んだファイルは削除されません。AIR アプリ
ケーションを削除すると、AIR アプリケーションがアプリケーションディレクトリ以外のディレクトリに行った変更は元に戻りません。

管理者用の Windows レジストリ設定
Adobe AIR 1.0 およびそれ以降
Windows では、管理者は、AIR アプリケーションのインストールおよびランタイムのアップデートを行わないように（または許可するように）マシンを設定できます。これらの設定は、Windows レジストリの

HKLM¥Software¥Policies¥Adobe¥AIR というキーの下にあります。次の設定があります。
レジストリ設定説明

AppInstallDisabled

AIR アプリケーションのインストールとアンインストールを許可することを指定します。「許可」する場合は0 に設定し、「許可しない」場合は 1 に設定します。

UntrustedAppInstallDisabled

信頼できない AIR アプリケーション（信頼できる証明書を含まないアプリケーション）のインストールを許可することを指定します。「許可」する場合は 0 に設定し、「許可しない」場合は 1 に設定します。

UpdateDisabled

ランタイムのアップデートを、バックグラウンドタスクまたは明示的なインストールの一部として許可することを指定します。「許可」する場合は 0 に設定し、「許可しない」場合は 1 に設定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1043

セキュリティ

Adobe AIR の HTML セキュリティ
Adobe AIR 1.0 およびそれ以降
このトピックでは、AIR HTML セキュリティアーキテクチャについて、およびインラインフレーム、フレーム、サンド
ボックスブリッジを使用して HTML ベースのアプリケーションを設定し、HTML コンテンツを SWF ベースのアプリケー
ションに安全に統合する方法について説明します。
ランタイムは、HTML および JavaScript の潜在的なセキュリティの脆弱性を克服するためのルールを適用し、メカニズムを提供します。同じルールは、アプリケーションを最初に JavaScript で記述する場合や HTML および JavaScript コンテンツを SWF ベースのアプリケーション内に読み込む場合にも適用されます。アプリケーションサンドボックスと非アプリ
ケーションセキュリティサンドボックスのコンテンツは権限が異なります。コンテンツをインラインフレームまたはフレー
ムに読み込むと、ランタイムによって安全なサンドボックスブリッジメカニズムが提供されて、フレームまたはインライン
フレーム内のコンテンツはアプリケーションセキュリティサンドボックス内のコンテンツと安全にやり取りできるようになります。

AIR SDK には、HTML コンテンツのレンダリングに使用する 3 つのクラスが用意されています。
HTMLLoader クラスは、JavaScript コードと AIR API との密接な統合を提供します。
StageWebView クラスは、HTML レンダリングクラスです。このクラスとホスト AIR アプリケーションとの統合は非常に限定されています。StageWebView クラスによって読み込まれたコンテンツは、アプリケーションセキュリティサンドボッ
クスに配置されません。また、ホスト AIR アプリケーションでのデータへのアクセスや関数の呼び出しもできません。デス
クトッププラットフォームの場合、StageWebView クラスは、Webkit をベースとしたビルトイン AIR HTML エンジンを使用します。このエンジンは HTMLLoader クラスでも使用されます。モバイルプラットフォームの場合、StageWebView
クラスは、オペレーティングシステムが提供する HTML コントロールを使用します。したがって、モバイルプラット
フォームの場合、StageWebView クラスには、システムの Web ブラウザーと同じセキュリティ上の考慮事項と脆弱性があります。

TextField クラスは、HTML テキストのストリングを表示できます。JavaScript を実行することはできませんが、リンクおよび外部から読み込まれたイメージをテキストに含めることはできます。
詳しくは、946 ページの「セキュリティ関連の JavaScript エラーの回避」を参照してください。

HTML ベースのアプリケーションの設定の概要
Adobe AIR 1.0 およびそれ以降
フレームとインラインフレームは、AIR で HTML コンテンツを編成するための便利な構造を提供します。フレームを使用
すると、データの永続化の維持とリモートコンテンツの安全な使用の両方が実現できます。

AIR 内の HTML では標準のページベースの編成が維持されるので、HTML コンテンツの最上位のフレームが別のページに「移動」すると HTML 環境は完全に更新されます。フレームとインラインフレームを使用すると、ブラウザーで実行されている Web アプリケーションと同じように、AIR でデータの永続性を維持できます。最上位のフレームでメインのアプ
リケーションオブジェクトを定義すると、フレームが新しいページに移動できない限り、それらのオブジェクトは永続化されます。アプリケーションの一時的な部分を読み込んで表示するには、子のフレームまたはインラインフレームを使用します（フレーム以外にも使用できるデータ永続化の維持方法は多数あります。例えば、Cookie、ローカル共有オブジェクト、
ローカルファイルストレージ、暗号化されたファイルストア、ローカルデータベースストレージがあります）。

AIR では、HTML の実行可能なコードとデータとの間に通常のあいまいな境界が維持されるため、HTML 環境のトップフ
レームのコンテンツはアプリケーションサンドボックスに配置されます。ページの load イベント後は、テキストのストリン
グを実行可能なオブジェクトに変換する eval() などの操作は制限されます。この制限は、アプリケーションがリモートコン
テンツを読み込まない場合でも適用されます。そのような制限された操作を HTML コンテンツで実行できるようにするには、フレームまたはインラインフレームを使用して、コンテンツをアプリケーションとは別のサンドボックス内に配置する必要があります（eval() 関数に依存する JavaScript アプリケーションフレームワークを使用する場合も、サンドボックス化

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1044

セキュリティ

した子フレーム内でコンテンツを実行する必要が生じることがあります）。アプリケーションサンドボックスでのJavaScript に関する制限について詳しくは、1045 ページの「異なるサンドボックス内のコンテンツに対するコードの制限」
を参照してください。

AIR 内の HTML ではリモートの安全でない可能性のあるコンテンツを読み込む機能が維持されるので、AIR では別のドメ
イン内のコンテンツとやり取りを回避するための同一生成元ポリシーを適用します。アプリケーションコンテンツと別のドメイン内のコンテンツ間のやり取りを許可するためには、親フレームと子フレーム間のインターフェイスとして機能するブ
リッジを設定します。
親子サンドボックス関係の設定

Adobe AIR 1.0 およびそれ以降
AIR では、HTML の frame および iframe エレメントに sandboxRoot 属性と documentRoot 属性を追加します。これらの属性を使用すると、アプリケーションコンテンツを別のドメインからのコンテンツとして扱うことができます。
属性

説明

sandboxRoot

フレームコンテンツを配置するサンドボックスとドメインを決定するために使用する URL。file:、http: または https: URL スキームを使用する必要があります。

documentRoot

フレームコンテンツの読み込み元の URL。file:、app: または app-storage: URL ス
キームを使用する必要があります。

次の例では、アプリケーションのサンドボックスサブディレクトリにインストールされているコンテンツをマップして、リ
モートサンドボックスおよび www.example.com ドメインで実行します。
<iframesrc="ui.html"
sandboxRoot="http://www.example.com/local/"documentRoot="app:/sandbox/"></iframe>

異なるサンドボックスまたはドメインでの親フレームと子フレーム間のブリッジの設定

Adobe AIR 1.0 およびそれ以降
AIR では、childSandboxBridge および parentSandboxBridge プロパティを、任意の子フレームの window オブジェクトに追加します。これらのプロパティを使用すると、親フレームと子フレームの間のインターフェイスとして機能するブリッジを定義できます。各ブリッジは一方向に移動します。

childSandboxBridge — childSandboxBridge プロパティを使用すると、子フレームで親フレーム内のコンテンツにインターフェイスを公開できます。インターフェイスを公開するには、childSandbox プロパティを子フレーム内の関数またはオブジェクトに設定します。これで、親フレーム内のコンテンツからオブジェクトまたは関数にアクセスできます。次の例では、
子フレームで実行中のスクリプトで、関数とプロパティを 1 つずつ含むオブジェクトをその親に公開する方法を示します。
var interface = {};interface.calculatePrice = function(){return .45 + 1.20;}
interface.storeID = "abc"window.childSandboxBridge = interface;

id として 「child」 が割り当てられたインラインフレーム内に子コンテンツがある場合、フレームの childSandboxBridge プロ
パティを読み取って親コンテンツからインターフェイスにアクセスできます。
var childInterface = document.getElementById("child").childSandboxBridge;
air.trace(childInterface.calculatePrice()); //traces "1.65"
air.trace(childInterface.storeID)); //traces "abc"

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1045

セキュリティ

parentSandboxBridge — parentSandboxBridge プロパティを使用すると、親フレームは子フレーム内のコンテンツにインターフェイスを公開できます。インターフェイスを公開するには、子フレームの parentSandbox プロパティを、親フレーム内の関数またはオブジェクトに設定します。これで、子フレーム内のコンテンツからオブジェクトまたは関数にアクセスできます。次の例では、親フレームで実行中のスクリプトで、save 関数を含むオブジェクトを子に公開する方法を示します。
var interface = {};interface.save = function(text){
var saveFile = air.File("app-storage:/save.txt");//write text to file}
document.getElementById("child").parentSandboxBridge = interface;

このインターフェイスを使用すると、子フレーム内のコンテンツで、テキストを save.txt という名前のファイルに保存できます。ただし、コンテンツはファイルシステムに対する他のアクセス権を持つことはできません。一般的に、アプリケー
ションコンテンツは、他のサンドボックスにできる限り範囲の狭いインターフェイスを公開する必要があります。子コンテ
ンツは、save 関数を次のように呼び出します。
var textToSave = "A string.";
window.parentSandboxBridge.save(textToSave);

子コンテンツが parentSandboxBridge オブジェクトのプロパティを設定しようとすると、ランタイムによって SecurityError
例外がスローされます。親コンテンツが childSandboxBridge オブジェクトのプロパティを設定しようとすると、ランタイム
によって SecurityError 例外がスローされます。

異なるサンドボックス内のコンテンツに対するコードの制限
Adobe AIR 1.0 およびそれ以降
このトピックの概要（1043 ページの「Adobe AIR の HTML セキュリティ」）で説明したように、ランタイムは、HTMLおよび JavaScript の潜在的なセキュリティの脆弱性を克服するためのルールを適用し、メカニズムを提供します。ここでは、それらの制限について説明します。コードでこれらの制限された API を呼び出そうとすると、ランタイムによって、「Adobe AIR runtime security violation for JavaScript code in the application security sandbox」というメッセージのエラーがスローされます。
詳しくは、946 ページの「セキュリティ関連の JavaScript エラーの回避」を参照してください。

JavaScript eval() 関数および同様の方法の使用に関する制限
Adobe AIR 1.0 およびそれ以降
アプリケーションセキュリティサンドボックス内の HTML コンテンツの場合は、コードが読み込まれた後（body エレメントの onload イベントが送出され、onload ハンドラー関数が実行を完了した後）にストリングを実行可能コードに動的に変換できる API の使用について制限があります。これは、アプリケーションで、アプリケーション以外のソース（潜在的に安全でないネットワークドメインなど）から誤ってコードを挿入（および実行）されないようにするための制限です。
例えば、アプリケーションがリモートソースのストリングデータを使用して DOM エレメントの innerHTML プロパティに書き込みを行うと、ストリングには安全ではない操作を実行する可能性のある実行可能（JavaScript）コードが含まれている場合があります。ただし、コンテンツが読み込まれている間は、DOM にリモートストリングが挿入される可能性はありません。

1 つの制限は、JavaScript eval() 関数の使用に関するものです。アプリケーションサンドボックス内のコードが読み込まれ、
onload イベントハンドラーの処理が完了した後は、eval() 関数を制限された方法でのみ使用できます。eval() 関数（アプリ
ケーションセキュリティサンドボックスからコードが読み込まれた後）の使用については、次のルールが適用されます。

•

リテラルを含む式は許可されます。次に、例を示します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1046

セキュリティ

eval("null");eval("3 + .14");eval("'foo'");•

次のようなオブジェクトリテラルは許可されます。
{ prop1: val1, prop2: val2 }•次のようなオブジェクトリテラル setter/getter は、禁止されます。
{ get prop1() { ... }, set prop1(v) { ... } }•次のような配列リテラルは許可されます。
[ val1, val2, val3 ]•次のようなプロパティの読み込みを含む式は、禁止されます。
a.b.c

•

関数の呼び出しは、禁止されます。

•

関数の定義は、禁止されます。

•

プロパティの設定は、禁止されます。

•

関数リテラルは、禁止されます。

ただし、コードの読み込み中、onload イベントの前、および onload イベントハンドラー関数の実行中は、これらの制限はア
プリケーションセキュリティサンドボックス内のコンテンツに適用されません。
例えば、コードが読み込まれた後に、次のコードを実行するとランタイムによって例外がスローされます。
eval("alert(44)");eval("myFunction(44)");eval("NativeApplication.applicationID");eval() 関数を呼び出すときに作成されるような、動的に生成されたコードがアプリケーションサンドボックス内で許可されると、セキュリティリスクが発生します。例えば、アプリケーションがネットワークドメインから読み込まれたストリングを誤って実行し、そのストリングに悪意のあるコードが含まれている可能性があります。これは例えば、ユーザーのコン
ピューターのファイルを削除または変更するコードである可能性があります。または、信頼されないネットワークドメインにローカルファイルのコンテンツを送り返すコードである場合もあります。
動的なコードを生成する方法は次のとおりです。

• eval() 関数を呼び出します。
• innerHTML プロパティまたは DOM 関数を使用して、アプリケーションディレクトリ外のスクリプトを読み込む script
タグを挿入します。

• innerHTML プロパティまたは DOM 関数を使用して、（src 属性を使用してスクリプトを読み込むのではなく）インライ
ンコードを含む script タグを挿入します。
• src 属性を script タグに設定し、アプリケーションディレクトリ外にある JavaScript ファイルを読み込みます。
• javascript URL スキームを使用します（href="javascript:alert('Test')" など）。
• setInterval() または setTimout() 関数を使用します。この場合、（非同期で実行する関数を定義する）最初の関数が関数名ではなく（評価される）ストリングになります（setTimeout('x = 4', 1000) など )。
• document.write() または document.writeln() を呼び出します。
アプリケーションセキュリティサンドボックス内のコードは、コンテンツを読み込んでいるときにのみこれらのメソッドを使用できます。
これらの制限で回避されないのは、JSON オブジェクトリテラルを含む eval() の使用です。これによってアプリケーション
コンテンツは、JSON JavaScript ライブラリで使用できます。ただし、オーバーロードされた JSON コード（イベントハン
ドラーを含む）の使用は制限されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1047

セキュリティ

その他の Ajax フレームワークおよび JavaScript コードライブラリの場合は、フレームワークまたはライブラリ内のコードが動的に生成されたコードに関するこれらの制限内で機能しているかどうかを確認します。制限に従っていない場合は、フレームワークまたはライブラリを使用するコンテンツを非アプリケーションセキュリティサンドボックスに含めます。詳し
くは、1008 ページの「AIR における JavaScript の制限」および 1053 ページの「アプリケーションコンテンツと非アプリ
ケーションコンテンツ間のスクリプト作成」を参照してください。アドビ システムズ社では、アプリケーションセキュリ
ティサンドボックスをサポートする Ajax フレームワークのリストをhttp://www.adobe.com/products/jp/air/develop/ajax/features/ で管理しています。
アプリケーションセキュリティサンドボックスのコンテンツとは異なり、非アプリケーションセキュリティサンドボックスの JavaScript コンテンツは、eval() 関数を呼び出して、動的に生成されたコードをいつでも実行できます。

AIR API へのアクセスに関する制限（非アプリケーションサンドボックス）
Adobe AIR 1.0 およびそれ以降
非アプリケーションサンドボックス内の JavaScript コードは、window.runtime オブジェクトにアクセスできないので、AIR

API を実行できません。非アプリケーションセキュリティサンドボックス内のコンテンツが次のコードを呼び出すと、アプ
リケーションは TypeError 例外をスローします。
try {window.runtime.flash.system.NativeApplication.nativeApplication.exit();}catch (e){alert(e);}例外のタイプが TypeError（未定義の値）であるのは、非アプリケーションサンドボックス内のコンテンツでは

window.runtime オブジェクトが認識されず、未定義の値として示されるからです。
スクリプトブリッジを使用してランタイム機能を非アプリケーションサンドボックス内のコンテンツに公開できます。詳し
くは、1053 ページの「アプリケーションコンテンツと非アプリケーションコンテンツ間のスクリプト作成」を参照してく
ださい。

XMLHttpRequest 呼び出しの使用に関する制限
Adobe AIR 1.0 およびそれ以降
アプリケーションセキュリティサンドボックス内の HTML コンテンツでは、HTML コンテンツが読み込まれている間や

onLoad イベントの発生時に同期 XMLHttpRequest メソッドを使用してアプリケーションサンドボックス外からデータを読み込むことはできません。
デフォルトでは、非アプリケーションセキュリティサンドボックス内の HTML コンテンツで JavaScript

XMLHttpRequest オブジェクトを使用して、リクエストを呼び出すドメイン以外のドメインからデータを読み込むことはできません。frame または iframe タグには、allowcrosscomainxhr 属性を含めることができます。この属性を null 値以外の値に設定すると、frame または iframe 内のコンテンツで Javascript XMLHttpRequest オブジェクトを使用して、リクエストを呼び出しているコードのドメイン以外のドメインからデータを読み込むことができます。
<iframe id="UI"
src="http://example.com/ui.html"
sandboxRoot="http://example.com/"allowcrossDomainxhr="true"
documentRoot="app:/"></iframe>

詳しくは、1049 ページの「異なるドメインのコンテンツ間のスクリプト作成」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1048

セキュリティ

CSS、frame、iframe および img エレメントの読み込みに関する制限（非アプリケーションサンドボックス内のコンテンツ）Adobe AIR 1.0 およびそれ以降
リモート（ネットワーク）セキュリティサンドボックス内の HTML コンテンツは、CSS、frame、iframe および img エレメ
ントをリモートサンドボックス（ネットワーク URL）からのみ読み込みます。

local-with-filesystem、local-with-networking または local-trusted サンドボックス内の HTML コンテンツは、CSS、
frame、iframe および img コンテンツを（アプリケーションサンドボックスまたはリモートサンドボックスからではなく）ローカルサンドボックスからのみ読み込みます。

JavaScript window.open() メソッドの呼び出しに関する制限
Adobe AIR 1.0 およびそれ以降
JavaScript window.open() メソッドの呼び出しによって作成されたウィンドウに非アプリケーションセキュリティサンド
ボックスのコンテンツが表示される場合、ウィンドウのタイトルはメイン（起動している）ウィンドウのタイトルで始まり、その後にコロンが続きます。コードを使用してウィンドウのタイトルの部分を画面から移動することはできません。
非アプリケーションセキュリティサンドボックス内のコンテンツは、ユーザーがマウスやキーボードを操作すると発生するイベントに応じてのみ JavaScript window.open() メソッドを正しく呼び出すことができます。これにより、非アプリケー
ションコンテンツで、詐欺に使用される（フィッシング攻撃など）可能性のあるウィンドウが作成されることはなくなります。また、マウスイベントやキーボードイベントのイベントハンドラーでは、window.open() メソッドを、遅延の後に（setTimeout() 関数を呼び出す場合など）実行されるように設定することはできません。
リモート（ネットワーク）サンドボックス内のコンテンツでは、リモートネットワークサンドボックス内のコンテンツを開く目的でのみ window.open() メソッドを使用できます。window.open() メソッドを使用して、アプリケーションサンドボック
スやローカルサンドボックスのコンテンツを開くことはできません。

local-with-filesystem、local-with-networking または local-trusted サンドボックス内のコンテンツ（1006 ページの「セキュリティサンドボックス」を参照）は、ローカルサンドボックスのコンテンツを開く目的でのみ window.open() メソッドを使用できます。window.open() を使用してアプリケーションサンドボックスやリモートサンドボックスのコンテンツを開くことはできません。
制限付きコードを呼び出した場合のエラー

Adobe AIR 1.0 およびそれ以降
これらのセキュリティ制限によりサンドボックスで使用が制限されているコードを呼び出すと、ランタイムは JavaScript エ
ラー「Adobe AIR runtime security violation for JavaScript code in the application security sandbox」を送出します。
詳しくは、946 ページの「セキュリティ関連の JavaScript エラーの回避」を参照してください。

ストリングから HTML コンテンツを読み込む場合のサンドボックスによる保護
Adobe AIR 1.0 およびそれ以降
HTMLLoader クラスの loadString() メソッドを使用すると、実行時に HTML コンテンツを作成できます。ただし、安全でないインターネットソースから読み込んだデータを HTML コンテンツとして使用すると、データが壊れる場合があります。
このため、デフォルトでは、loadString() メソッドを使用して作成した HTML はアプリケーションサンドボックスに配置されず、AIR API にアクセスできません。ただし、HTMLLoader オブジェクトのplaceLoadStringContentInApplicationSandbox プロパティを true に設定すると、loadString() メソッドを使用して作成したHTML をアプリケーションサンドボックスに配置できます。詳しくは、945 ページの「ストリングからの HTML コンテンツの読み込み」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1049

セキュリティ

異なるドメインのコンテンツ間のスクリプト作成
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、インストール時に特殊な権限を付与されます。アプリケーションに含まれていないリモートファ
イルやローカルファイルなどの他のコンテンツに同じ権限情報が流出しないようにすることが重要です。

AIR サンドボックスブリッジについて
Adobe AIR 1.0 およびそれ以降
通常、他のドメインのコンテンツで、他のドメインのスクリプトを呼び出すことはできません。AIR アプリケーションで権限が与えられている情報や制御が誤って流出しないようにするために、アプリケーションセキュリティサンドボックス内のコンテンツ（アプリケーションと共にインストールされるコンテンツ）に次の制限が適用されます。

•

アプリケーションセキュリティサンドボックス内のコードでは、Security.allowDomain() メソッドを呼び出して他のサンドボックスへのクロススクリプトを実行できません。アプリケーションセキュリティサンドボックスからこのメソッドを呼び出すと、エラーがスローされます。

• LoaderContext.securityDomain または LoaderContext.applicationDomain プロパティを設定して、非アプリケーションコン
テンツをアプリケーションサンドボックスに読み込むことはできません。
メインの AIR アプリケーションが、リモートドメインのコンテンツに対してメインの AIR アプリケーション内のスクリプ
トへの制御付きアクセス権を持っていることを要求する場合や、その逆の場合もあります。これを実現するために、ランタ
イムには、2 つのサンドボックス間のゲートウェイとして機能する、サンドボックスブリッジメカニズムがあります。サンドボックスブリッジを使用すると、リモートサンドボックスとアプリケーションセキュリティサンドボックス間で明示的な操作を実行できます。
サンドボックスブリッジは、読み込まれる側のスクリプトと読み込む側のスクリプトの両方がアクセスできる 2 つのオブジェクトを公開します。

• parentSandboxBridge オブジェクトを使用すると、読み込む側のコンテンツは読み込まれる側のコンテンツのスクリプトにプロパティと関数を公開できます。

• childSandboxBridge オブジェクトを使用すると、読み込まれる側のコンテンツが読み込む側のコンテンツのスクリプトにプロパティと関数を公開できます。
サンドボックスブリッジによって公開されるオブジェクトは、参照ではなく値によって受け渡されます。すべてのデータは直列化されます。つまり、ブリッジの片側で公開されたオブジェクトはもう一方の側で設定できず、公開されたそのオブジェクトはすべて型指定されません。また、公開できるのは単純なオブジェクトと関数だけで、複雑なオブジェクトは公開できません。
子コンテンツがオブジェクトを parentSandboxBridge オブジェクトに設定しようとすると、ランタイムによってSecurityError 例外がスローされます。同様に、親コンテンツがオブジェクトを childSandboxBridge オブジェクトに設定しようとすると、ランタイムによって SecurityError 例外がスローされます。

サンドボックスブリッジの例（SWF）
Adobe AIR 1.0 およびそれ以降
AIR ミュージックストアアプリケーションでは、リモート SWF ファイルでアルバムの価格をブロードキャストできるようにする必要がありますが、リモート SWF ファイルでその価格が販売価格かどうかを公開しないようにする必要があるとします。この場合、StoreAPI クラスのメソッドを使用して、価格を取得しても販売価格は公開されないようにします。次に、この StoreAPI クラスのインスタンスが、リモート SWF を読み込む Loader オブジェクトの LoaderInfo オブジェクトのparentSandboxBridge プロパティに割り当てられます。

AIR ミュージックストアのコードを次に示します。
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1050

セキュリティ

<?xml version="1.0" encoding="utf-8"?><mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" title="Music Store"creationComplete="initApp()"><mx:Script>
import flash.display.Loader;import flash.net.URLRequest;
private var child:Loader;private var isSale:Boolean = false;
private function initApp():void {var request:URLRequest =new URLRequest("http://[www.yourdomain.com]/PriceQuoter.swf")
child = new Loader();child.contentLoaderInfo.parentSandboxBridge = new StoreAPI(this);child.load(request);
container.addChild(child);}
public function getRegularAlbumPrice():String {return "$11.99";}
public function getSaleAlbumPrice():String {return "$9.99";}
public function getAlbumPrice():String {if(isSale) {return getSaleAlbumPrice();}else {
return getRegularAlbumPrice();}}</mx:Script><mx:UIComponent id="container" /></mx:WindowedApplication>

StoreAPI オブジェクトはメインアプリケーションを呼び出して通常のアルバム価格を取得しますが、getSaleAlbumPrice()
メソッドが呼び出されると、「Not available」を返します。次のコードでは、StoreAPI クラスを定義します。
public class StoreAPI{
private static var musicStore:Object;public function StoreAPI(musicStore:Object){this.musicStore = musicStore;}
public function getRegularAlbumPrice():String {return musicStore.getRegularAlbumPrice();}public function getSaleAlbumPrice():String {return "Not available";}
public function getAlbumPrice():String {return musicStore.getRegularAlbumPrice();}}

次のコードは、ストアの価格を報告しても、販売価格は報告できない PriceQuoter SWF ファイルの例を表しています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1051

セキュリティ

package{import flash.display.Sprite;
import flash.system.Security;
import flash.text.*;
public class PriceQuoter extends Sprite{
private var storeRequester:Object;public function PriceQuoter() {trace("Initializing child SWF");
trace("Child sandbox: " + Security.sandboxType);storeRequester = loaderInfo.parentSandboxBridge;
var tf:TextField = new TextField();
tf.autoSize = TextFieldAutoSize.LEFT;
addChild(tf);tf.appendText("Store price of album is: " + storeRequester.getAlbumPrice());
tf.appendText("\n");tf.appendText("Sale price of album is: " + storeRequester.getSaleAlbumPrice());}}}

サンドボックスブリッジの例（HTML）
Adobe AIR 1.0 およびそれ以降
HTML コンテンツで、parentSandboxBridge プロパティと childSandboxBridge プロパティが子ドキュメントの JavaScript のwindow オブジェクトに追加されます。HTML コンテンツでのブリッジ関数の設定方法の例については、963 ページの「サンドボックスブリッジインターフェイスの設定」を参照してください。

API 公開の制限
Adobe AIR 1.0 およびそれ以降
サンドボックスブリッジを公開する場合は、高度なレベルの API を公開してそれらが悪用されない程度まで制限することが重要です。ブリッジ実装を呼び出しているコンテンツは（コードの挿入などにより）改ざんされる可能性があることに注意
してください。例えば、readFile(path:String) メソッド（任意のファイルのコンテンツを読み込むメソッド）をブリッジを通じて公開すると、悪用されやすくなります。この場合はパスを取得せずに特定のファイルを読み込む

readApplicationSetting() API を公開する方が安全です。アプリケーションの一部が改ざんされた後でもアプリケーションで実行できる、より意味のある方法によって、損害の広がりを抑えることができます。
関連項目

961 ページの「異なるセキュリティサンドボックス内のコンテンツのクロススクリプト」
1007 ページの「AIR アプリケーションサンドボックス」

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1052

セキュリティ

ディスクへの書き込み
Adobe AIR 1.0 およびそれ以降
Web ブラウザーで実行中のアプリケーションは、ユーザーのローカルファイルシステムとのやり取りのみが制限されます。
Web ブラウザーは、Web コンテンツを読み込んでもユーザーのコンピューターが改ざんされないことを保証するセキュリ
ティポリシーを実装します。例えば、ブラウザーで Flash Player を使って実行されている SWF ファイルは、ユーザーのコ
ンピューターに既に存在するファイルと直接やり取りできません。共有オブジェクトと Cookie はユーザーの環境設定およびその他のデータを管理する目的でユーザーのコンピューターに書き込むことができますが、これはファイルシステム操作の制限になります。AIR アプリケーションはネイティブにインストールされるため、ローカルファイルシステムに対する読
み取りと書き込みの機能を含む、異なるセキュリティコントラクトを持ちます。
この自由度には開発者の大きな責任が伴います。アプリケーションの予想外の不安定さは、アプリケーションの機能だけでなく、ユーザーのコンピューターの完全性も危険にさらします。このような理由から、開発者は、1054 ページの「開発者のためのセキュリティのベストプラクティス」を参照する必要があります。

AIR 開発者は、いくつかの URL スキーム規則を使用してローカルファイルシステムにアクセスしたり、ファイルをそのシステムに書き込むことができます。
URL スキーム

説明

app:/

アプリケーションディレクトリのエイリアス。このパスからアクセスされたファイルはアプリケーションサンドボック
スに割り当てられ、ランタイムによって完全な権限が与えられます。

app-storage:/

ランタイムによって標準化されたローカル記憶領域ディレクトリのエイリアス。このパスからアクセスされたファイル
は非アプリケーションサンドボックスに割り当てられます。

file:///

ユーザーのハードディスクのルートを表すエイリアス。このパスからアクセスされたファイルは、アプリケーション
ディレクトリ内に存在している場合はアプリケーションサンドボックスに割り当てられ、それ以外の場合は非アプリ
ケーションサンドボックスに割り当てられます。

注意：AIR アプリケーションは、app: URL スキームを使用してコンテンツを変更できません。また、アプリケーション
ディレクトリは、管理者の設定により、読み取り専用になる場合があります。
ユーザーのコンピューターに対する管理者の制限がない限り、AIR アプリケーションには、ユーザーのハードドライブ上のどの場所にも書き込むことができる権限が付与されます。開発者には、app-storage:/ パスを、アプリケーションに関連する
ローカル記憶領域に使用することをお勧めします。アプリケーションから app-storage:/ へ書き込まれたファイルは、標準の場所に挿入されます。

• Mac OS：アプリケーションの記憶領域ディレクトリは <appData>/<appId>/Local Store/ です。ここで <appData> はユー
ザーの環境設定フォルダーです。これは通常 /Users/<user>/Library/Preferences になります。

• Windows：アプリケーションの記憶領域ディレクトリは <appData>¥<appId>¥Local Store¥ です。ここで <appData> はユーザーの CSIDL_APPDATA 特殊フォルダーです。通常は、C:¥Documents and Settings¥<userName>¥Application Dataになります。

• Linux：<appData>/<appID>/Local Store/ です。ここで、<appData> は、/home/<user>/.appdata です。
アプリケーションがユーザーのファイルシステム内の既存のファイルとやり取りするように設計されている場合は、必ず1054 ページの「開発者のためのセキュリティのベストプラクティス」を参照してください。

信頼されないコンテンツの安全な使用
Adobe AIR 1.0 およびそれ以降
アプリケーションサンドボックスに割り当てられていないコンテンツは、ランタイムのセキュリティ基準を満たす場合のみ
アプリケーションに追加のスクリプト機能を提供できます。ここでは、非アプリケーションコンテンツでの AIR セキュリ
ティコントラクトについて説明します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1053

セキュリティ

Security.allowDomain()
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、Flash Player のブラウザープラグインが信頼されないコンテンツのスクリプトによるアクセスを制限するよりも厳格に、非アプリケーションコンテンツのスクリプトによるアクセスを制限します。例えば、ブラウザーのFlash Plyaer で、local-trusted サンドボックスに割り当てられている SWF ファイルが System.allowDomain() メソッドを呼び出すと、スクリプトによるアクセスが指定されたドメインから読み込まれた SWF に付与されます。同様の方法は AIR アプ
リケーションのアプリケーションコンテンツからは許可されません。許可した場合、非アプリケーションファイルにユーザーのファイルシステムへの不当なアクセス権が付与されてしまうからです。リモートファイルは、Security.allowDomain() メ
ソッドの呼び出しに関係なく、アプリケーションサンドボックスに直接アクセスできません。

アプリケーションコンテンツと非アプリケーションコンテンツ間のスクリプト作成
Adobe AIR 1.0 およびそれ以降
アプリケーションコンテンツと非アプリケーションコンテンツとの間をスクリプト化する AIR アプリケーションではさらに複雑なセキュリティの調整が行われます。アプリケーションサンドボックス内に含まれていないファイルは、サンドボック
スブリッジを使用したアプリケーションサンドボックス内のファイルのプロパティとメソッドへのアクセスのみが許可されます。サンドボックスブリッジはアプリケーションコンテンツと非アプリケーションコンテンツ間のゲートウェイとして機能し、2 つのファイル間の明示的な操作を可能にします。サンドボックスブリッジを正しく使用すると、セキュリティの追加のレイヤーが提供され、非アプリケーションコンテンツが、アプリケーションコンテンツの一部となるオブジェクト参照にアクセスするのを制限します。
サンドボックスブリッジのメリットについて、例を使って説明します。AIR ミュージックストアアプリケーションは、独自の SWF ファイルを作成する必要のある広告主に API を提供し、ストアアプリケーションはこのファイルを使用して通信できます。ストアは、ストアが提供するアーティストと CD を探すためのメソッドを広告主に提供する必要がありますが、セキュリティ上の理由でサードパーティの SWF ファイルからメソッドとプロパティを分離する必要もあります。
サンドボックスブリッジはこの機能を提供できます。デフォルトでは、ランタイムで外部から AIR アプリケーションに読み込まれたコンテンツには、メインアプリケーションのどのメソッドまたはプロパティへのアクセス権もありません。カスタムのサンドボックスブリッジ実装を使用すると、開発者はこれらのメソッドやプロパティを公開せずにリモートコンテンツにサービスを提供できます。サンドボックスブリッジは信頼されるコンテンツと信頼されないコンテンツ間の通路と見なすことができ、オブジェクト参照を公開せずに読み込む側のコンテンツと読み込まれる側のコンテンツ間の通信を可能にします。
サンドボックスブリッジを安全に使用する方法について詳しくは、1049 ページの「異なるドメインのコンテンツ間のスクリプト作成」を参照してください。

動的に生成される安全ではない SWF コンテンツからの保護
Adobe AIR 1.0 およびそれ以降
Loader.loadBytes() メソッドを使用すると、アプリケーションでバイト配列から SWF コンテンツを生成できます。ただし、リモートソースから読み込まれるデータに対するインジェクション攻撃によって、コンテンツを読み込むときに深刻なダメージを与える可能性があります。これは特に、アプリケーションサンドボックスにデータが読み込まれるときに発生することがあります。アプリケーションサンドボックスでは生成された SWF コンテンツで AIR API の完全なセットにアクセスできます。
実行可能な SWF コードを生成せずに、loadBytes() メソッドを使用する正当な使用法があります。例えば、loadBytes() メ
ソッドを使用してイメージデータを生成し、イメージ表示のタイミングを制御できます。また、オーディオ再生のためのSWF コンテンツの動的な作成など、コードの実行に依存する正当な使用法もあります。AIR では、デフォルトでloadBytes() メソッドを使用して SWF コンテンツを読み込むことができません。このメソッドでは、イメージコンテンツの最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1054

セキュリティ

み読み込むことができます。AIR では、loadBytes() メソッドの loaderContext プロパティに allowLoadBytesCodeExecution プ
ロパティが含まれています。このプロパティを true に設定すると、アプリケーションで loadBytes() を使用して実行可能な

SWF コンテンツを読み込むことを明示的に許可できます。次のコードは、この機能の使用方法を示します。
var loader:Loader = new Loader();var loaderContext:LoaderContext = new LoaderContext();
loaderContext.allowLoadBytesCodeExecution = true;
loader.loadBytes(bytes, loaderContext);

loadBytes() を呼び出して SWF コンテンツを読み込み、LoaderContext オブジェクトの allowLoadBytesCodeExecution プロ
パティを false（デフォルト）に設定すると、Loader オブジェクトは SecurityError 例外をスローします。
注意：Adobe AIR の将来のリリースでは、この API は変更される可能性があります。変更された場合は、LoaderContext
クラスの allowLoadBytesCodeExecution プロパティを使用するコンテンツを再コンパイルする必要がある場合があります。

開発者のためのセキュリティのベストプラクティス
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションが Web テクノロジを使用して構築されていても、開発者はそれらの AIR アプリケーションがブラウ
ザーのセキュリティサンドボックス内で機能していないことに気づくことが重要です。つまり、故意にまたは誤ってローカ
ルシステムに損害を与える可能性がある AIR アプリケーションを構築する場合があります。AIR はリスクを最小化しようと試みますが、脆弱性が取り込まれる可能性はまだあります。ここでは、重要なセキュリティ上の潜在的なリスクについて説明します。

ファイルをアプリケーションセキュリティサンドボックスにインポートした場合のリスク
Adobe AIR 1.0 およびそれ以降
アプリケーションディレクトリに存在するファイルはアプリケーションサンドボックスに割り当てられ、ランタイムの完全な権限が付与されます。ローカルファイルシステムに書き込みを行うアプリケーションは、app-storage:/ に書き込むことをお勧めします。このディレクトリはユーザーのコンピューター上のアプリケーションファイルとは別の場所にあるため、ファイルはアプリケーションサンドボックスに割り当てられず、セキュリティのリスクは軽減されます。開発者は次の点に注意する必要があります。

•

ファイルは必要な場合にのみ AIR ファイル（インストール済みアプリケーション内）に含めます。

•

スクリプトファイルは、動作が完全に把握され、信頼される場合にのみ AIR ファイル（インストール済みアプリケー
ション内）に含めます。

•

アプリケーションディレクトリに書き込みを行ったり、アプリケーションディレクトリ内のコンテンツを変更したりしな
いでください。ランタイムでは、アプリケーションが app:/ URL スキームを使用してファイルやディレクトリに書き込みを行ったり、それらを変更したりすると、SecurityError 例外をスローしてその操作を回避します。

•

ネットワークソースのデータを AIR API のメソッドのパラメーターとして使用しないでください。これによりコードが実行される可能性があります。これには、Loader.loadBytes() メソッドや JavaScript eval() 関数の使用が含まれます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1055

セキュリティ

外部ソースを使用してパスを判断する場合のリスク
Adobe AIR 1.0 およびそれ以降
AIR アプリケーションは、外部のデータまたはコンテンツを使用すると、改ざんされる可能性があります。このため、ネッ
トワークまたはファイルシステムのデータを使用する場合は特に注意する必要があります。信頼の責任は最終的には開発者と、開発者が作成するネットワーク接続にありますが、外部データの読み込みは本来リスクを伴うものであるので、機密データの操作への入力には使用しないでください。開発者は次の操作を行わないことをお勧めします。

•

ネットワークソースのデータを使用したファイル名の決定•

ネットワークソースのデータを使用した、アプリケーションでの個人情報の送信に使用される URL の作成

保護されていない資格情報を使用、保存または送信する場合のリスク
Adobe AIR 1.0 およびそれ以降
ユーザー資格情報をユーザーのローカルファイルシステムに保存することは本来リスクを伴い、これらの資格情報が改ざんされる可能性があります。開発者は次の点に注意する必要があります。

•

資格情報をローカルに保存する必要がある場合は、ローカルファイルシステムに書き込むときに資格情報を暗号化します。ランタイムでは、EncryptedLocalStore クラスを使って各インストール済みアプリケーションに固有の暗号化された記憶領域を提供します。詳しくは、685 ページの「暗号化されたローカルストア」を参照してください。

•

ネットワークソースが信頼され、送信に HTTPS: または Transport Layer Security（TLS）プロトコルが使用されているのでなければ、暗号化されていないユーザー資格情報をそのソースに送信しないでください。

•

資格情報の作成時にデフォルトのパスワードを指定しないでください。パスワードはユーザー自身が作成できるようにしてください。デフォルトパスワードを指定すると、それが攻撃者に知られた場合、デフォルトを変更しないで使用しているユーザーの資格情報が無防備な状態に置かれることになります。

ダウングレード攻撃のリスク
Adobe AIR 1.0 およびそれ以降
アプリケーションのインストール中に、ランタイムはアプリケーションのバージョンが現在インストールされていないことを確認します。アプリケーションが既にインストールされている場合、ランタイムはバージョンストリングをインストール
されているバージョンと比較します。このストリングが異なる場合、ユーザーはインストールのアップグレードを選択できます。ランタイムは、新しくインストールされたバージョンが古いバージョンよりも新しいことを保証せず、それが異なるバージョンであるということだけを保証します。攻撃者は古いバージョンをユーザーに配布して、セキュリティの弱点をくぐり抜ける可能性があります。このため、開発者はアプリケーションの実行時にバージョンの確認を行うことをお勧めします。ネットワークで要求されたアップデートがあるかどうかをアプリケーションに確認させるのも良い方法です。その場合、攻撃者がユーザーに古いバージョンを実行させていても、その古いバージョンは更新する必要があることを認識します。また、アプリケーションで明確なバージョン管理スキームを使用すると、ユーザーがダウングレードバージョンをインストー
ルする可能性が低くなります。

コード署名
Adobe AIR 1.0 およびそれ以降
すべての AIR インストーラーファイルには、コード署名を実行する必要があります。コード署名は、ソフトウェアの指定された作成元が正確であるかどうかを確認する暗号化プロセスです。AIR アプリケーションの署名には、外部の認証機関（CA）が発行した証明書または独自に作成した自己署名入り証明書を使用できます。有名な CA の商用証明書を使用することを強くお勧めします。これらの証明書を使用すると、偽造ではない正しいアプリケーションをインストールしていること

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1056

セキュリティ

をユーザーに保証できます。ただし、SDK から adt を使用するか、証明書の作成に adt を使用する Flash、Flash Builder ま
たは別のアプリケーションを使用して、自己署名入り証明書を作成できます。自己署名入り証明書では、インストールする
アプリケーションが本物であることを保証できません。この証明書は、アプリケーションを公開する前のテスト用としてのみご使用ください。

Android デバイスのセキュリティ
Adobe AIR 2.5 およびそれ以降
すべてのコンピューティングデバイスと同様、Android の AIR は、ネイティブセキュリティモデルに準拠しています。同時に、AIR では、安全なインターネット接続アプリケーションを開発者が簡単に作成できるようにするための独自のセキュリティ規則を維持しています。

Android 上の AIR アプリケーションでは Android パッケージ形式を使用するので、インストールには Android セキュリ
ティモデルが適用されます。AIR アプリケーションインストーラーは使用されません。
Android セキュリティモデルには、次に示す主要な 3 つの要素があります。

•

権限

•

アプリケーションの署名•

アプリケーションユーザー ID

Android 権限
Android の多くの機能は、オペレーティングシステムの権限メカニズムによって保護されます。保護された機能を使用するには、アプリケーションに権限が必要であることを AIR アプリケーション記述子で宣言する必要があります。ユーザーがア
プリケーションをインストールしようとすると、Android オペレーティングシステムでは、インストールを続行するために必要な権限がすべて表示されます。
ほとんどの AIR アプリケーションでは、アプリケーション記述子に Android 権限を指定する必要があります。デフォルト
では、権限は含まれていません。AIR ランタイムを通じて公開される Android の保護された機能を使用するには、次の権限が必要です。

ACCESS_COARSE_LOCATION アプリケーションが、Geolocation クラスを介して Wi-Fi およびセルラーネットワーク
位置データにアクセスすることを許可します。

ACCESS_FINE_LOCATION アプリケーションが Geolocation クラスを介して GPS データにアクセスすることを許可します。

ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE アプリケーションが、NetworkInfo クラスを介して ネット
ワーク情報にアクセスすることを許可します。

CAMERA アプリケーションがカメラにアクセスすることを許可します。
INTERNET アプリケーションがネットワーク要求を行うことを許可します。また、リモートデバッグも許可します。
READ_PHONE_STATE 着信呼び出しがあったときに、AIR ランタイムがオーディオをミュートすることを許可します。
RECORD_AUDIO アプリケーションがマイクにアクセスすることを許可します。
WAKE_LOCK および DISABLE_KEYGUARD アプリケーションが、SystemIdleMode クラス設定を使用してデバイスのスリープ状態を防ぐことを許可します。

WRITE_EXTERNAL_STORAGE アプリケーションがデバイスの外部メモリカードへ書き込むことを許可します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1057

セキュリティ

アプリケーションの署名

Android プラットフォーム用に作成されたすべてのアプリケーションパッケージには署名が必要です。Android 上の AIR
アプリケーションはネイティブの Android APK 形式でパッケージ化されるので、アプリケーションの署名は AIR の規則ではなく Android の規則に従って行われます。Android と AIR で使用するコード署名はよく似ていますが、次のような大きな違いがあります。

• Android では、開発者が秘密キーを所有しているかどうかが署名によって検証されますが、開発者の ID の検証には署名が使用されません。

• Android マーケットに送信されるアプリケーションの場合、少なくとも 25 年間有効な証明書が必要です。
• Android では、別の証明書へのパッケージの署名の移行がサポートされません。更新の署名が別の証明書によって行われている場合、ユーザーは、更新されたアプリケーションをインストールする前に元のアプリケーションをアンインス
トールする必要があります。

•

同じ証明書を使用して署名された 2 つのアプリケーションでは、互いにキャッシュやデータファイルにアクセスできる共有 ID を指定できます（このような共有は AIR では容易ではありません )。

アプリケーションユーザー ID

Android では Linux カーネルを使用します。インストールされたすべてのアプリケーションには Linux タイプのユーザー
ID が割り当てられます。この ID によって、ファイルアクセスなどの操作の権限が決定されます。アプリケーションディレクトリ、アプリケーション記憶領域ディレクトリ、および一時ディレクトリ内のファイルは、ファイルシステムの権限によってアクセスから保護されます。外部ストレージへ書き込まれるファイル（つまり、SD カード）は、SD カードがマスス
トレージデバイスとしてコンピューターにマウントされている場合、他のアプリケーションまたはユーザーが読み込み、変更、削除を行うことができます。
インターネット要求と共に受け取った Cookie は、AIR アプリケーション間で共有されません。
バックグラウンドイメージのプライバシー
ユーザーがアプリケーションをバックグラウンドに切り替えると、一部の Android バージョンでは最近使用したアプリ
ケーションリスト内のサムネイルとして使用するためのスナップショットがキャプチャされます。このスクリーンショット
はデバイスメモリ内に保存され、攻撃者がデバイスの物理的な制御時にアクセスすることが可能です。
アプリケーションで機密情報を表示する場合は、このような情報がバックグラウンドのスクリーンショットによってキャプ
チャされないよう保護する必要があります。NativeApplication オブジェクトによって送出される deactivate イベントは、
アプリケーションがバックグラウンドに切り替えられる直前の状態であることを通知するものです。このイベントを使用して、機密情報を消去するか隠してください。

関連項目

Android：Security and Permissions

Android における暗号化されたデータ
Android 上の AIR アプリケーションでは、ビルトイン SQL データベースに用意されている暗号化オプションを使用して、暗号化されたデータを保存できます。最適なセキュリティを確保するため、アプリケーションが実行されるたびに入力されるユーザー入力のパスワードに基づいた暗号化キーを使用してください。ローカルに保存された暗号化キーやパスワードは、
アプリケーションファイルにアクセス可能な攻撃者から「隠す」のが難しいか、不可能です。攻撃者がキーを取得できると、データを暗号化しても Android システムに用意されているユーザー ID ベースのファイルシステムセキュリティ以上の保護は行われません。

EncryptedLocalStore クラスはデータの保存に使用できますが、そのデータは Android デバイスでは暗号化されません。
代わりに、Android のセキュリティモデルではアプリケーションのユーザー ID を使用して、他のアプリケーションからデータを保護します。共有ユーザー ID を使用し、かつ同じコードサイニング証明書を使用して署名されているアプリケー
ションは、暗号化されたローカルストアとして同じものを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1058

セキュリティ

重要：ルート化された電話では、ルート権限で実行されたアプリケーションが他のあらゆるアプリケーションのファイルにもアクセスできます。そのため、暗号化されたローカルストアを使用して保存されたデータは、ルート化されたデバイスでは安全ではありません。

iOS デバイスのセキュリティ
iOS では、AIR はネイティブセキュリティモデルに準拠します。同時に、AIR では、安全なインターネット接続アプリケー
ションを開発者が簡単に作成できるようにするための独自のセキュリティ規則を維持しています。

iOS 上の AIR アプリケーションでは iOS パッケージ形式を使用するので、インストールには iOS セキュリティモデルが適用されます。AIR アプリケーションインストーラーは使用されません。さらに、iOS デバイスでは個別の AIR ランタイムが使用されません。各 AIR アプリケーションには、機能に必要なすべてのコードが含まれています。
アプリケーションの署名

iOS プラットフォーム用に作成されたすべてのアプリケーションパッケージには署名が必要です。iOS 上の AIR アプリケー
ションはネイティブの iOS IPA 形式でパッケージ化されるので、アプリケーションの署名は AIR の要件ではなく iOS の要件に従って行われます。iOS と AIR で使用するコード署名はよく似ていますが、次のような大きな違いがあります。

• iOS では、Apple が発行した証明書をアプリケーションの署名に使用する必要があります。他の証明機関の証明書は使用できません。

• iOS の場合、Apple が発行した配布証明書は、通常 1 年間有効です。
バックグラウンドイメージのプライバシー
ユーザーが iOS でアプリケーションをバックグラウンドに切り替えると、オペレーティングシステムによって、トランジ
ションのアニメーション化に使用されるスクリーンショットがキャプチャされます。このスクリーンショットはデバイスメ
モリ内に保存され、攻撃者がデバイスの物理的な制御時にアクセスすることが可能です。
アプリケーションで機密情報を表示する場合は、このような情報がバックグラウンドのスクリーンショットによってキャプ
チャされないよう保護する必要があります。NativeApplication オブジェクトによって送出される deactivate イベントは、
アプリケーションがバックグラウンドに切り替えられる直前の状態であることを通知するものです。このイベントを使用して、機密情報を消去するか隠してください。

最終更新日 2015/10/14

1059

第 65 章：ActionScript の使用方法の例
ActionScript 3.0 のコード例を実行することは、特定のクラスおよびメソッドの動作を学ぶ最も優れた方法の 1 つです。例
は、使用するデバイス、またはターゲットにするデバイスに応じてさまざまな方法で使用できます。

Flash Professional または Flash Builder を実行しているコンピューター これらの開発環境を使用して ActionScript 3.0の例を実行する方法について詳しくは、1061 ページの「Flash Professional での ActionScript 3.0 の例の実行」または1062 ページの「Flash Builder での ActionScript 3.0 の例の実行」を参照してください。trace 文などのデバッグツールを使用して、コード例がどのように動作するかについて理解を深めることができます。
モバイルデバイス ActionScript 3.0 コード例は、Flash Player 10.1 以降のリリースをサポートするモバイルデバイス上で実行できます。1063 ページの「モバイルデバイスでの ActionScript 3.0 の例の実行」を参照してください。これらの例は、Flash Professional または Flash Builder を使用することにより、コンピューターで実行することもできます。
TV デバイス これらの例を TV デバイスで実行することはできませんが、コンピューターで実行することによって例から学ぶことは可能です。TV デバイス向けのアプリケーション開発について詳しくは、Adobe Developer Connection の Web
サイトにある Flash Platform for TV を参照してください。

例の種類
ActionScript 3.0 には、次の種類のコード例があります。

•

コードスニペット例（ActionScript 3.0 のドキュメントセット全体で使用）•クラスの使用例（主に Adobe® Flash® Platform 用 ActionScript® 3.0 リファレンスガイドで使用）•

複数のソースファイルを含む実例（www.adobe.com/go/learn_programmingAS3samples_flash_jp からソースのZIP ファイルをダウンロード）
コードスニペット例
コードスニペット例を以下に示します。
var x:int = 5;
trace(x); // 5

コードスニペットには、1 つの概念を示すのに十分なコードしか含まれていません。通常、package ステートメントや class
ステートメントは含まれていません。
クラスの使用例
多くの例では、完全な ActionScript クラスのソースコードが示されています。クラスの使用例を以下に示します。
package {public class Example1 {public function Example1():void {var x:int = 5;
trace(x); //5}}}

クラスの使用例を示すコードには、package ステートメント、クラス宣言およびコンストラクター関数が含まれています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1060

ActionScript の使用方法の例

複数のソースファイルを含む実例『ActionScript 3.0 開発ガイド』の多くのトピックでは、最後に実例が記載されています。そこでは、実際の現場で使える

ActionScript 機能の使用例が示されています。通常、これらの例には次のような複数のファイルが含まれています。

• 1 つ以上の ActionScript のソースファイル• Flash Professional で使用する .FLA ファイル
• Flash Builder で使用する 1 つ以上の MXML ファイル•

データファイル、イメージファイル、音声ファイルまたはサンプルアプリケーションで使用するその他のアセット（省略可能）

通常、実例は ZIP 形式のアーカイブファイルで提供されます。
開発ガイドの例のリストを含む ZIP ファイル

Flash Professional CS5 および Flex 4 用の ZIP ファイル（www.adobe.com/go/learn_programmingAS3samples_flash_jp からダウンロード）には、次の例が含まれています。

• AlarmClock（134 ページの「イベント処理の例：Alarm Clock」）• AlgorithmicVisualGenerator（221 ページの「描画 API の例：Algorithmic Visual Generator」）• ASCIIArt（19 ページの「ストリングの例：ASCII アート」）• CapabilitiesExplorer（839 ページの「機能の例：システム機能の検出」）• CustomErrors（67 ページの「エラー処理の例：CustomErrors アプリケーション」）• DisplayObjectTransformer（208 ページの「ジオメトリの例：マトリックス変換の表示オブジェクトへの適用」）• FilterWorkbench（277 ページの「表示オブジェクトのフィルター処理の例：Filter Workbench」）• GlobalStockTicker（916 ページの「例：相場表示アプリケーションの国際化」）• IntrovertIM_HTML（816 ページの「External API の例：Web ブラウザーでの ActionScript と JavaScript との通信」）• NewsLayout（368 ページの「TextField の例：新聞形式のテキストフォーマット」）• PlayList（44 ページの「配列の例：PlayList」）• PodcastPlayer（445 ページの「サウンドの例：Podcast Player」）• ProjectionDragger（339 ページの「例：遠近法投影」）• ReorderByZ（343 ページの「Matrix3D オブジェクトを使用した表示の並べ替え」）• RSSViewer（109 ページの「ActionScript 内の XML の例：インターネットからの RSS データのロード」）• RuntimeAssetsExplorer（314 ページの「ムービークリップの例：RuntimeAssetsExplorer」）• SimpleClock（6 ページの「日付と時刻の例：単純なアナログ時計」）• SpinningMoon（242 ページの「ビットマップの例：回転する月のアニメーション」）• SpriteArranger（194 ページの「表示オブジェクトの例：SpriteArranger」）• TelnetSocket（770 ページの「TCP ソケットの例：Telnet クライアントの構築」）• VideoJukebox（483 ページの「ビデオの例：ビデオジュークボックス」）• WikiEditor（86 ページの「正規表現の例：Wiki パーサー」）• WordSearch（553 ページの「マウス入力の例：WordSearch」）
また、Flash デベロッパーセンターや Flex デベロッパーセンターの様々なクイックスタート記事でも実例を入手できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1061

ActionScript の使用方法の例

Flash Professional での ActionScript 3.0 の例の実行
Flash Professional を使用して例を実行するには、次のいずれかの手順を（例の種類に応じて）使用します。
Flash Professional でのコードスニペット例の実行
Flash Professional でコードスニペット例を実行するには：
1 ファイル／新規を選択します。
2 新規ドキュメントダイアログボックスで 「Flash ドキュメント」を選択し、「OK」をクリックします。
新しい Flash ウィンドウが表示されます。

3 タイムラインパネルで、レイヤー 1 の最初のフレームをクリックします。
4 アクションパネルにコードスニペット例を入力するか貼り付けます。
5 ファイル／保存を選択します。ファイル名を指定し、「OK」をクリックします。
6 例をテストするには、制御／ムービープレビューを選択します。

Flash Professional でのクラスの使用例の実行
Flash Professional でクラスの使用例を実行するには：
1 ファイル／新規を選択します。
2 新規ドキュメントダイアログボックスで 「ActionScript ファイル」を選択し、「OK」をクリックします。新しいエディ
ターウィンドウが表示されます。

3 クラスを使用したコード例をコピーして、エディターウィンドウに貼り付けます。
このクラスがプログラムのメインドキュメントクラスの場合は、次のように MovieClip クラスを拡張する必要があります。
import flash.display.MovieClip;
public class Example1 extends MovieClip{//...
}

また、この例で参照するすべてのクラスを import ステートメントを使用して宣言するようにしてください。

4 ファイル／保存を選択します。ファイルには、例で使用されているクラス名と同じ名前を指定します（ContextMenuExample.as など）。
注意：flashx.textLayout.container.ContainerController クラスの使用例など、クラスの使用例にはパッケージの宣言に複数の階層がある（package flashx.textLayout.container.examples {）ものもあります。これらの例では、パッケージの宣言に一致するサブフォルダー（flashx/textLayout/container/examples）にファイルを保存するか、ActionScript の最初が package { のみになるようにパッケージ名を削除すると、このファイルをどの場所からでもテストできるようになります。

5 ファイル／新規を選択します。
6 新規ドキュメントダイアログボックスで「Flash ドキュメント」を選択し（ActionScript 3.0）、「OK」をクリックします。新しい Flash ウィンドウが表示されます。

7 プロパティパネルの「ドキュメントクラス」フィールドに、例で使用されているクラス名を入力します。この名前は、保存した ActionScript ソースファイルの名前と一致している必要があります（ContextMenuExample など）。

8 ファイル／保存を選択します。FLA ファイルには、例で使用されているクラス名と同じ名前を指定します（ContextMenuExample.fla など）。

9 例をテストするには、制御／ムービープレビューを選択します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1062

ActionScript の使用方法の例

Flash Professional での実例の実行
通常、実例は ZIP 形式のアーカイブファイルで提供されます。Flash Professional で実例を実行するには：
1 アーカイブファイルを任意のフォルダーに解凍します。
2 Flash Professional で、ファイル／開くを選択します。
3 アーカイブファイルを解凍したフォルダーを参照します。そのフォルダー内にある FLA ファイルを選択して、「開く」
をクリックします。

4 例をテストするには、制御／ムービープレビューを選択します。

Flash Builder での ActionScript 3.0 の例の実行
Flash Builder を使用して例を実行するには、次のいずれかの手順を（例の種類に応じて）使用します。
Flash Builder でのコードスニペット例の実行
Flash Builder でコードスニペット例を実行するには：
1 新しい Flex プロジェクトを作成（ファイル／新規／ Flex プロジェクトを選択）するか、既存の Flex プロジェクト内で新しい MXML アプリケーションを作成（ファイル／新規／ MXML アプリケーションを選択）します。プロジェクトまたはアプリケーションにわかりやすい名前を付けます（ContextMenuExample など）。

2 生成された MXML ファイル内に <mx:Script> タグを追加します。
3 <mx:Script> タグと </mx:Script> タグの間にコードスニペット例の内容を貼り付けます。MXML ファイルを保存します。
4 例を実行するには、「実行」を選択して、メイン MXML ファイルの実行メニューオプション（例：実行／

ContextMenuExample を実行）を選択します。
Flash Builder でのクラスの使用例の実行
Flash Builder でクラスの使用例を実行するには：
1 ファイル／新規／ ActionScript プロジェクトを選択します。
2 「プロジェクト名」フィールドに主要なクラスの名前（ContextMenuExample など）を入力します。他のフィールドではデフォルト値を使用（または固有の環境に合わせて変更）します。「終了」をクリックしてプロジェクトとメイン

ActionScript ファイルを作成します。
3 ActionScript ファイルにコードが生成されている場合はすべて削除します。コード例（package および import ステー
トメントを含む）を ActionScript ファイルに貼り付けてファイルを保存します。
注意：flashx.textLayout.container.ContainerController クラスの使用例など、クラスの使用例にはパッケージの宣言に複数の階層がある（package flashx.textLayout.container.examples {）ものもあります。これらの例では、パッケージの宣言に一致するサブフォルダー（flashx/textLayout/container/examples）にファイルを保存するか、ActionScript の最初が package { のみになるようにパッケージ名を削除すると、このファイルをどの場所からでもテストできるようになります。

4 例を実行するには、「実行」を選択して、メイン ActionScript クラス名の実行メニューオプション（例：実行／

ContextMenuExample を実行）を選択します。
Flash Builder での実例の実行
通常、実例は ZIP 形式のアーカイブファイルで提供されます。Flash Builder で実例を実行するには：
1 アーカイブファイルを任意のフォルダーに解凍します。フォルダーにわかりやすい名前を付けます（ContextMenuExample など）。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1063

ActionScript の使用方法の例

2 Flash Builder で、ファイル／新規／ Flex プロジェクトを選択します。「プロジェクトの場所」セクションで「参照」をクリックし、サンプルファイルが保存されているフォルダーを選択します。「プロジェクト名」フィールドにフォルダー
名（ContextMenuExample など）を入力します。他のフィールドではデフォルト値を使用（または固有の環境に合わ
せて変更）します。「次へ」をクリックして続行します。

3 出力パネルで、「次へ」をクリックし、デフォルト値をそのまま使用します。
4 ソースパスパネルで、「メインアプリケーションファイル」フィールドの横にある「参照」ボタンをクリックします。サンプルフォルダーからサンプルのメイン MXML ファイルを選択します。「終了」をクリックしてプロジェクトファイルを作成します。

5 例を実行するには、「実行」を選択して、メイン MXML ファイルの実行メニューオプション（例：実行／

ContextMenuExample を実行）を選択します。

モバイルデバイスでの ActionScript 3.0 の例の実行
ActionScript 3.0 のコード例は、Flash Player 10.1 をサポートしているモバイルデバイス上で実行できます。ただし、一般にコード例を実行する目的は、特定のクラスやメソッドの動作を確認することにあります。その場合には、デスクトップコ
ンピューターなどのモバイル以外のデバイス上で例を実行してください。デスクトップコンピューターでは、trace ステー
トメントや Flash Professional または Flash Builder のデバッグツールを使用してコード例について理解を深めることができます。
モバイルデバイス上で例を実行する場合は、デバイスまたは Web サーバーにファイルをコピーします。ファイルをデバイスにコピーしてブラウザーで例を実行するには、次の手順に従います。

1 1061 ページの「Flash Professional での ActionScript 3.0 の例の実行」または 1062 ページの「Flash Builder でのActionScript 3.0 の例の実行」の手順に従って、SWF ファイルを作成します。Flash Professional では、制御／ムー
ビープレビューを選択するときに SWF ファイルが作成されます。Flash Builder では、Flash Builder プロジェクトを実行、デバッグまたはビルドするときに SWF ファイルが作成されます。

2 SWF ファイルをモバイルデバイス上のディレクトリにコピーします。ファイルをコピーするには、デバイスに付属のソフトウェアを使用します。

3 モバイルデバイス上で、ブラウザーのアドレスバーに SWF ファイルの file:// URL を入力します。例えば、
file:://applications/myExample.swf と入力します。
ファイルを Web サーバーにコピーしてデバイスのブラウザーで例を実行するには、次の手順に従います。

1 SWF ファイルおよび HTML ファイルを作成します。まず、1061 ページの「Flash Professional での ActionScript 3.0の例の実行」または 1062 ページの「Flash Builder での ActionScript 3.0 の例の実行」の手順に従います。Flash
Professional で、制御／ムービープレビューを選択すると、SWF ファイルのみが作成されます。両方のファイルを作成するには、まず、パブリッシュ設定ダイアログの「フォーマット」タブで、「Flash」と「HTML」の両方を選択します。
次に、ファイル／パブリッシュを選択すると、HTML ファイルと SWF ファイルの両方が作成されます。Flash Builder
では、Flash Builder プロジェクトを実行、デバッグまたはビルドするときに SWF ファイルと HTML ファイルの両方が作成されます。

2 SWF ファイルと HTML ファイルを Web サーバーのディレクトリにコピーします。
3 モバイルデバイス上で、ブラウザーのアドレスバーに、HTML ファイルの HTTP アドレスを入力します。例えば、
http://www.myWebServer/examples/myExample.html と入力します。
モバイルデバイス上で例を実行する前に、次の各事項考慮について検討してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1064

ActionScript の使用方法の例

ステージサイズ
モバイルデバイス上で例を実行するときに使用するステージのサイズは、モバイル以外のデバイスで使用する場合よりも、かなり小さくなります。多くの例では、ステージのサイズが指定されていません。SWF の作成時に、ご使用のデバイスに合わせてステージのサイズを指定してください。例えば、176 x 208 ピクセルと指定します。
『ActionScript 3.0 開発ガイド』の実例は、様々な ActionScript 3.0 の概念とクラスについて説明することを目的としています。そこで使用されるユーザーインターフェイスは、デスクトップまたはラップトップコンピューター上で正しく表示および動作できるように設計されています。例はモバイルデバイス上でも動作しますが、ステージのサイズやユーザーイン
ターフェイスの設計は、小さな画面には適していません。アドビ システムズ社では、コンピューター上で実例を実行してActionScript について学習し、付随するコードスニペットをモバイルアプリケーションで使用することをお勧めします。
テキストフィールドによる trace ステートメントの代替
モバイルデバイス上で例を実行する場合は、例の trace ステートメントからの出力を表示できません。出力を表示するには、

TextField クラスのインスタンスを作成します。次に、trace ステートメントからのテキスト出力をテキストフィールドのtext プロパティに追加します。
テキストフィールドを設定しトレースの代替機能として使用するには、次の関数を使用します。
function createTracingTextField(x:Number, y:Number,width:Number, height:Number):TextField {var tracingTF:TextField = new TextField();
tracingTF.x = x;tracingTF.y = y;tracingTF.width = width;
tracingTF.height = height;// A border lets you more easily see the area the text field covers.
tracingTF.border = true;// Left justifying means that the right side of the text field is automatically// resized if a line of text is wider than the width of the text field.
// The bottom is also automatically resized if the number of lines of text// exceed the length of the text field.
tracingTF.autoSize = TextFieldAutoSize.LEFT;// Use a text size that works well on the device.
var myFormat:TextFormat = new TextFormat();myFormat.size = 18;
tracingTF.defaultTextFormat = myFormat;
addChild(tracingTF);
return tracingTF;}

例えば、この関数をドキュメントクラスに private 関数として追加します。次に、ドキュメントクラスの他のメソッドで次のようなコードを使用してデータをトレースします。
var traceField:TextField = createTracingTextField(10, 10, 150, 150);// Use the newline character "\n" to force the text to the next line.
traceField.appendText("data to trace\n");traceField.appendText("more data to trace\n");// Use the following line to clear the text field.
traceField.appendText("");

appendText() メソッドがパラメーターとして受け付ける値は 1 つだけです。その値はストリング（String インスタンスまたはストリングリテラル）にする必要があります。ストリング以外の変数の値を出力するには、まず値を String に変換する必要があります。このための最も簡単な方法は、オブジェクトの toString() メソッドを呼び出すことです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1065

ActionScript の使用方法の例

var albumYear:int = 1999;
traceField.appendText("albumYear = ");traceField.appendText(albumYear.toString());

テキストサイズ
多くの例では、概念を説明するのにテキストフィールドが使用されています。テキストフィールド内のテキストサイズを調整すると、モバイルデバイス上の表示が読みやすくなる場合があります。例えば、例で myTextField という名前のテキスト
フィールドインスタンスが使用されている場合は、そのテキストのサイズを次のコードで変更します。
// Use a text size that works well on the device.
var myFormat:TextFormat = new TextFormat();myFormat.size = 18;
myTextField.defaultTextFormat = myFormat

ユーザー入力のキャプチャ
モバイル用オペレーティングシステムとブラウザーでは、SWF コンテンツでは受信されないいくつかのユーザー入力イベ
ントをキャプチャします。イベント固有の動作はオペレーティングシステムとブラウザーによって異なりますが、モバイル
デバイス上で例を実行したときに予期しない動作を示す可能性があります。詳しくは、537 ページの「KeyboardEvent の優先度」を参照してください。
また、多くの例のユーザーインターフェイスは、デスクトップまたはラップトップコンピューターを対象として設計されています。例えば、『ActionScript 3.0 開発ガイド』で使用されている実例の多くは、デスクトップでの表示に適しています。
したがって、モバイルデバイスの画面では、ステージ全体を表示できない場合があります。ブラウザーのコンテンツ全体をパンできるかどうかは、使用しているブラウザーによって異なります。さらに、例はスクロールまたはパンのイベントをキャッチして処理するように設計されていません。したがって、例で使用されているユーザーインターフェイスの一部は、小さな画面で実行するのには適していません。アドビ システムズ社では、コンピューター上で例を実行して ActionScriptについて学習し、付随するコードスニペットをモバイルアプリケーションで使用することをお勧めします。
詳しくは、170 ページの「表示オブジェクトのパンとスクロール」を参照してください。
フォーカスの処理
一部の例では、フィールドにフォーカスを設定する必要があります。フィールドにフォーカスを設定することにより、テキスト入力やボタン選択などを実行できます。フィールドにフォーカスを設定するには、指またはペンなどのモバイルデバイ
スのポインターデバイスを使用します。または、モバイルデバイスのナビゲーションキーを使用してフィールドにフォーカスを設定します。フォーカスの設定されているボタンを選択するには、モバイルデバイスの選択キーを使用します。コン
ピューターで Enter キーを使用するのと同じ要領です。一部のデバイスでは、ボタンを 2 回タップすると選択できます。
フォーカスについて詳しくは、533 ページの「フォーカスの管理」を参照してください。
マウスイベントの処理
多くの例ではマウスイベントを監視します。コンピューターでは、例えば、ユーザーが表示オブジェクト上にマウスを移動したり、表示オブジェクト上でマウスボタンをクリックしたりしたときに、これらのマウスイベントが発生します。モバイ
ルデバイスでは、指またはペンなどのポインターデバイスを使用したときに発生するイベントはタッチイベントと呼ばれます。Flash Player 10.1 では、タッチイベントをマウスイベントにマップします。このマッピングによって、Flash Player

10.1 より前に開発された SWF コンテンツでも引き続き動作することが保証されます。したがって、ポインターデバイスを使用して表示オブジェクトを選択したり、ドラッグしたりする場合でも、例は動作します。
パフォーマンス
モバイルデバイスの処理能力はデスクトップデバイスに劣ります。CPU に高い負荷のかかる例をモバイルデバイスで実行
すると、パフォーマンスが低下します。例えば、221 ページの「描画 API の例：Algorithmic Visual Generator」の例では、フレームに入るたびに膨大な量の計算と描画が実行されます。この例をコンピューターで実行すると、様々な描画 APIが例示されます。しかし、一部のモバイルデバイスはパフォーマンスに制限があるので、この例を実行するのに適していません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1066

ActionScript の使用方法の例

モバイルデバイスでのパフォーマンスについて詳しくは、「Flash Platform のパフォーマンスの最適化」を参照してください。
ベストプラクティス
例では、モバイルデバイス向けアプリケーションを開発する上でのベストプラクティスを考慮していません。モバイルデバ
イスにおけるメモリおよび処理能力の制限は、特別な考慮を必要とします。同様に、小さい画面用のユーザーインターフェ
イスもデスクトップ表示とは異なる考慮が必要です。モバイルデバイス用のアプリケーション開発について詳しくは、「Flash Platform のパフォーマンスの最適化」を参照してください。

最終更新日 2015/10/14

1067

第 66 章：ローカルデータベースでの SQL サポート
Adobe AIR には、SQL データベースエンジンが含まれています。このデータベースエンジンは、オープンソースの SQLite
データベースシステムを使用して、多くの標準 SQL 機能を備えたローカル SQL データベースをサポートします。ランタイ
ムでは、データベースのデータをファイルシステムのどこに、どのように格納するのかは指定しません。各データベースは、
完全に単一ファイル内に格納されます。開発者は、データベースファイルを格納する場所をファイルシステム内に指定できます。また、1 つの AIR アプリケーションから 1 つまたは複数の異なるデータベース（別々のデータベースファイル）にア
クセスできます。このドキュメントでは、Adobe AIR ローカル SQL データベースでサポートされる SQL 構文とデータ型について概説します。このドキュメントは、包括的な SQL リファレンスとしての利用を想定したものではなく、Adobe AIR
でサポートする SQL ダイアレクトの詳細を説明したものです。このランタイムは、SQL-92 標準 SQL ダイアレクトの大部分をサポートしています。SQL 学習用には様々な参考文献、Web サイト、書籍、およびトレーニング資料が存在するので、このドキュメントでは、包括的な SQL のリファレンスまたはチュートリアルの体裁はとらず、AIR でサポートしている

SQL 構文について、また、このダイアレクトと SQL-92 との違いについての説明を主眼としています。
SQL ステートメントの定義で使用する表記規則
このドキュメントに記載された SQL 文の定義では、次の表記規則を使用しています。

•

テキストの大文字と小文字• UPPER CASE - リテラルの SQL キーワードはすべて大文字で表記されています。
• lower case - プレースホルダー項または句の名前はすべて小文字で表記されています。
•

定義文字• ::= 句またはステートメントの定義を示します。
•

グループおよび置換可能を示す文字• | パイプ文字は置換可能なオプションの間で使用されており、「または」に読み替えることができます。
• [] 角括弧で囲まれた項目はオプション項目です。角括弧の中には、単一の項目、または互いに置換可能な複数の項目が記載されています。

• () 置換可能な複数の項目（パイプ文字で区切られた項目）が丸括弧で囲まれている場合は、必須の項目グループ（つまり、単一の必須項目に対して有効な値を示す項目のセット）を示します。

•

繰り返し制御文字•+ 丸括弧で囲まれた項目の後にプラス文字が付いている場合は、前の項目を 1 回以上繰り返すことができることを示します。

• * 角括弧で囲まれた項目の後にアスタリスク文字が付いている場合は、前の（角括弧で囲まれた）項目を 0 回以上繰り返すことができることを示します。

•

リテラル文字• * 列名、または関数名の後の丸括弧の中でアスタリスク文字が使用されている場合は、0 回以上の繰り返しではなく、リテラルのアスタリスク文字を示します。

• . ピリオド文字はリテラルのピリオドを表します。
• , カンマ文字はリテラルのカンマを表します。
• () 単一の句または項目を囲む 1 組の丸括弧は、その丸括弧が必須のリテラル丸括弧文字であることを示します。
•

その他の文字は、特に記載されていない限り、そのリテラル文字を表します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1068

ローカルデータベースでの SQL サポート

サポートされている SQL 構文
Adobe AIR SQL データベースエンジンでサポートされている SQL 構文について、ステートメントと句の種類、式、ビルト
イン関数および演算子に分けて説明します。ここで取り上げるトピックは次のとおりです。

• SQL 構文全般••

データ操作ステートメント（SELECT、INSERT、UPDATE および DELETE）
データ定義ステートメント（テーブル、インデックス、ビューおよびトリガーの CREATE ステートメント、ALTER ス
テートメントおよび DROP ステートメント）•

特殊な文と句•

ビルトイン関数（集計関数、スカラ関数、および日付 / 時刻書式設定関数）

•

演算子

•

パラメーター•

サポートされていない SQL 機能•

追加の SQL 機能

SQL 構文全般
各種の文と式に関する具体的な構文に加えて、SQL 構文には一般に次のような規則があります。
大文字と小文字の区別 SQL ステートメント（オブジェクト名を含む）では、大文字と小文字は区別されません。ただし、SQL 文では SQL キーワードが大文字で表記されることが多いので、このドキュメントでもこの表記規則を使用します。
SQL シンタックスでは大文字と小文字が区別されませんが、SQL のリテラルテキスト値は大文字と小文字が区別され、比較およびソート操作では、列または操作に対して定義されている照合シーケンスの指定に従って大文字と小文字を区別できます。詳しくは、「COLLATE」を参照してください。
空白 SQL ステートメントでは、個々の単語を区切るために空白文字（スペース、タブ、改行など）を使用する必要があります。ただし、単語と記号の間の空白はオプションです。SQL ステートメントに含まれる空白文字の種類と個数は意味を持ちません。インデントや改行などの空白文字を使用して SQL 文を読みやすいように整形できます。書式を整形しても、SQL 文の意味は変わりません。

データ操作文
データ操作文は最もよく使用する SQL 文です。データ操作文は、データベーステーブルのデータの取得、追加、変更、および削除に使用します。サポートされているデータ操作ステートメントは、SELECT、INSERT、UPDATE および

DELETE です。
SELECT
SELECT 文は、データベースに問い合わせるときに使用します。SELECT 文の結果は、それぞれ固定数の列を持つ 0 行以上のデータ行です。結果として返される列の数は、SELECT とオプションの FROM キーワードとの間に列名または式リスト（下記の result）で指定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1069

ローカルデータベースでの SQL サポート

sql-statement::=

resultresult-column
table-list
table

::=
::=
::=
::=

join-opjoin-args
compound-op
sort-expr-list
sort-ordercollation-name

::=
::=
::=
::=
::=
::=

SELECT [ALL | DISTINCT] result[FROM table-list][WHERE expr][GROUP BY expr-list][HAVING expr][compound-op select-statement]*[ORDER BY sort-expr-list][LIMIT integer [( OFFSET | , ) integer]]
result-column [, result-column]** | table-name . * | expr [[AS] string]table [ join-op table join-args ]*table-name [AS alias] |( select ) [AS alias], | [NATURAL] [LEFT | RIGHT | FULL] [OUTER | INNER | CROSS] JOIN
[ON expr] [USING ( id-list )]UNION | UNION ALL | INTERSECT | EXCEPT
expr [sort-order] [, expr [sort-order]]*[COLLATE collation-name] [ASC | DESC]
BINARY | NOCASE

結果（result）には任意の式を使用できます。結果の式が * の場合は、その 1 つの式がすべてのテーブルのすべての列に置き換えられます。テーブル名の後に .* を続けて指定すると、その 1 つのテーブルのすべての列が返されます。

DISTINCT キーワードを指定すると、結果行の重複しないサブセットが返されます。NULL 値はすべて同じものとして扱われます。デフォルトでは、すべての結果行が返されます。これを明示的に指定するには、キーワード ALL を使用します。
クエリは FROM キーワードの後に指定した 1 つ以上のテーブルに対して実行されます。複数のテーブル名をカンマで区切
ると、各テーブルがクロス結合されます。JOIN 構文を使用して、テーブルの結合方法を指定することもできます。外部結合の種類としては、LEFT OUTER JOIN のみがサポートされています。join-args 内の ON 句の式はブール値に解決される必要があります。FROM 句のテーブルとして、括弧で囲んだサブクエリを使用できます。FROM 句全体を省略することもできます。この場合は、result 式リストの値で構成された 1 つの行が返されます。

WHERE 句は、クエリで取得する行数を限定する場合に使用します。WHERE 句の式はブール値に解決される必要があります。WHERE 句によるフィルタリングはグループ化の前に行われるので、WHERE 句の式に集計関数を含めることはできません。

GROUP BY 句を使用すると、1 行以上の結果が集約されて 1 行の出力行になります。GROUP BY 句は、結果に集約関数が含まれている場合に特に役立ちます。GROUP BY 句の式は、SELECT 式リストに含まれていなくてもかまいません。
HAVING 句は、ステートメントによって返される行を制限するという点で WHERE と同様です。ただし、HAVING 句
は、GROUP BY 句によって指定されたグループ化が行われた後に適用されます。したがって、HAVING 式は、集約関数
を含む値を参照できます。HAVING 句の式は、SELECT リストに含まれていなくてもかまいません。WHERE 句の式と同様に、HAVING 句の式もブール値に解決される必要があります。
ORDER BY 句を使用すると、出力行がソートされます。ORDER BY 句の sort-expr-list 引数には、ソートキーとして使用する式のリストを指定します。これらの式は、単純な SELECT 文では結果に含まれていなくてもかまいませんが、複合
SELECT 文（いずれかの compound-op 演算子を使用した SELECT 文）では、各ソート式が結果の列の 1 つに正確に対応する必要があります。各ソートキーの後にはオプションで sort-order 句を付けることができます。この句には、
COLLATE キーワードとテキストの並べ替えに使用する照合関数の名前およびソート順序を指定するキーワード ASC（昇順）または DESC（降順）を指定できます。sort-order を省略すると、デフォルト（昇順）が使用されます。COLLATE
句と照合関数の定義については、「COLLATE」を参照してください。
LIMIT 句は、結果で返される行数の上限を設定します。負の LIMIT は上限がないことを示します。LIMIT の後にオプションの OFFSET を付けると、結果セットの先頭から指定した行数がスキップされます。複合 SELECT ステートメントでは、LIMIT 句は必ず最後の SELECT ステートメントの後に付けますが、上限はクエリ全体に適用されます。LIMIT 句で
OFFSET キーワードを使用すると、最初の整数が上限になり、2 番目の整数がオフセットになります。OFFSET キーワードの代わりにカンマを使用すると、最初の数がオフセットになり、2 番目の数が上限になります。この見かけの違いは意図的なもので、古い SQL データベースシステムとの互換性を最大限確保することを目的としています。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1070

ローカルデータベースでの SQL サポート

複合 SELECT ステートメントは、UNION、UNION ALL、INTERSECT、EXCEPT のいずれかの演算子で接続された複数の単純な SELECT ステートメントで構成されます。複合 SELECT ステートメントでは、構成するすべての SELECT ス
テートメントで同じ数の結果列を指定する必要があります。最後の SELECT ステートメントの後（また、単一の LIMIT 句が指定されている場合はその前）には、単一の ORDER BY 句のみを指定できます。UNION 演算子と UNION ALL 演算
子はどちらも、前と後の SELECT ステートメントの結果を 1 つのテーブルに結合します。違いは、UNION ではすべての結果行が異なり、UNION ALL では重複する可能性があることです。INTERSECT 演算子は、前と後の SELECT ステート
メントの結果の共通部分をとります。EXCEPT は、前の SELECT 文の結果から後の SELECT 文の結果を除去します。3 つ以上の SELECT 文を接続すると、最初から順に結果が結合されます。
指定可能な式の定義については、「式」を参照してください。

AIR 2.5 以降では、BLOB データを ActionScript ByteArray オブジェクトに変換するための読み取りの際に、SQL CAST
演算子がサポートされます。例えば、次のコードは AMF 形式で格納されていない未処理のデータを読み取って、
ByteArray オブジェクトに格納します。
stmt.text = "SELECT CAST(data AS ByteArray) AS data FROM pictures;";stmt.execute();var result:SQLResult = stmt.getResult();
var bytes:ByteArray = result.data[0].data;

INSERT
INSERT はテーブルにデータを格納するために使用する SQL 文で、次の 2 つの基本形式があります。
sql-statement ::=(value-list) |INSERT [OR conflict-algorithm] INTO [database-name.] table-name [(column-list)] VALUESINSERT [OR conflict-algorithm] INTO [database-name.] table-name [(column-list)] select-statement
REPLACE INTO [database-name.] table-name [(column-list)] VALUES (value-list) |REPLACE INTO [database-name.] table-name [(column-list)] select-statement

VALUES キーワードを使用する最初の形式では、既存のテーブルに新しい行が 1 行作成されます。column-list を指定しない場合は、テーブルの列と同じ数の値を指定する必要があります。column-list を指定する場合は、指定した列と同じ数の値を指定する必要があります。列リストに含まれないテーブルの列には、テーブルの作成時に定義されたデフォルト値が格納されます。デフォルト値が定義されていない場合は NULL が格納されます。

2 番目の形式の INSERT ステートメントは、SELECT ステートメントからデータを取得します。column-list を指定しない
場合は、SELECT 文の結果に含まれる列の数とテーブルの列の数が一致する必要があります。column-list を指定する場合
は、そこで指定した列の数と SELECT 文の結果に含まれる列の数が一致する必要があります。SELECT 文の結果行ごとに、
テーブル内に新しいエントリが 1 つ作成されます。SELECT 文は単純な SELECT と複合 SELECT のどちらでもかまいません。指定可能な SELECT 文の定義については、「SELECT」を参照してください。
オプションの conflict-algorithm では、この特定のコマンドで使用する制約競合解決アルゴリズムを指定します。conflict-algorithm の説明および定義については、1077 ページの「特殊な文と句」を参照してください。
2 つの REPLACE INTO 形式は、標準の INSERT [OR conflict-algorithm] 形式を REPLACE 競合アルゴリズムと共に使用する（つまり、INSERT OR REPLACE... 形式を使用する）のと同じです。
2 つの REPLACE INTO 形式は、標準の INSERT [OR conflict-algorithm] 形式を REPLACE 競合アルゴリズムと共に使用する（つまり、INSERT OR REPLACE... 形式を使用する）のと同じです。
UPDATEUPDATE コマンドは、テーブル内の既存のレコードを変更します。
sql-statement::=

UPDATE [database-name.] table-name SET column1=value1, column2=value2,... [WHERE expr]

このコマンドは、UPDATE キーワードの後に、レコードを更新する対象のテーブルの名前を指定します。SET キーワードの後に、変更する列名と変更後の値を、カンマ区切りリストとして指定します。WHERE 句の式には、レコードが更新される行（複数の場合もあり）を指定します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1071

ローカルデータベースでの SQL サポート

DELETE
DELETE 文は、テーブルからレコードを削除するときに使用します。
sql-statement::=

DELETE FROM [database-name.] table-name [WHERE expr]

このコマンドでは、DELETE FROM キーワードの後に、レコードを削除する対象のテーブルの名前を指定します。

WHERE 句を省略すると、テーブルのすべての行が削除されます。WHERE 句を指定すると、式に一致する行のみが削除されます。WHERE 句の式はブール値に解決される必要があります。指定可能な式の定義については、「式」を参照してください。

データ定義文
データ定義文は、テーブル、ビュー、インデックス、トリガーなどのデータベースオブジェクトを作成、変更、および削除するときに使用します。次のデータ定義文がサポートされています。

•

テーブル：

• CREATE TABLE• ALTER TABLE• DROP TABLE•

インデックス：• CREATE INDEX• DROP INDEX•ビュー：• CREATE VIEWS• DROP VIEWS
•

トリガー：

• CREATE TRIGGERS• DROP TRIGGERSCREATE TABLE
CREATE TABLE ステートメントでは、キーワード CREATE TABLE の後に新しいテーブルの名前を指定し、その後に列定義と列制約のリストを括弧で囲んで記述します。テーブル名には、識別子またはストリングを使用できます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1072

ローカルデータベースでの SQL サポート

sql-statement::=sql-statement
column-def
type
column-constraint

::=
::=
::=
::=

constraint::=

conflict-clauseconflict-algorithm
default-value
sort-ordercollation-namecolumn-list

::=
::=
::=
::=
::=
::=

CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [database-name.] table-name( column-def [, column-def]* [, constraint]* )CREATE [TEMP | TEMPORARY] TABLE [database-name.] table-name AS select-statement
name [type] [[CONSTRAINT name] column-constraint]*
typename | typename ( number ) | typename ( number , number )NOT NULL [ conflict-clause ] |PRIMARY KEY [sort-order] [ conflict-clause ] [AUTOINCREMENT] |UNIQUE [conflict-clause] |CHECK ( expr ) |DEFAULT default-value |COLLATE collation-name
PRIMARY KEY ( column-list ) [conflict-clause] |UNIQUE ( column-list ) [conflict-clause] |CHECK ( expr )ON CONFLICT conflict-algorithm
ROLLBACK | ABORT | FAIL | IGNORE | REPLACENULL | string | number | CURRENT_TIME | CURRENT_DATE | CURRENT_TIMESTAMPASC | DESC
BINARY | NOCASE
column-name [, column-name]*

各列定義は、列名とその列のデータ型、およびオプションで 1 つ以上の列制約を並べたものです。列のデータ型は、その列に格納できるデータを制限します。異なるデータ型の列に値を格納しようとすると、可能な場合にはランタイムによって値が適切な型に変換され、可能でない場合にはエラーが発生します。詳しくは、「データ型のサポート」を参照してください。

NOT NULL 列制約は、その列に NULL 値を格納できないことを示します。
UNIQUE 制約を指定すると、指定された 1 つまたは複数の列にインデックスが作成されます。このインデックスには、一意キーが含まれている必要があります。つまり、任意の行と任意の別の行の間で、指定された列の値、または指定された複数列の値の組み合わせが必ず異なっていなくてはなりません。CREATE TABLE ステートメントには複数の UNIQUE 制約
を含めることができます。列定義内の複数の列に UNIQUE 制約を指定できるほか、複数テーブルレベルで UNIQUE 制約を設定することもできます。

CHECK 制約では、行のデータを挿入または更新する際の条件となる式を定義します。この式が true に評価された場合のみ、行のデータが挿入または更新されます。CHECK 制約の式の結果はブール値として解決される必要があります。
列定義内の COLLATE 句は、列のテキストエントリを比較するときに使用するテキスト照合関数を指定します。デフォル
トでは、BINARY 照合関数が使用されます。COLLATE 句と照合関数について詳しくは、「COLLATE」を参照してくだ
さい。

DEFAULT 制約では、INSERT の実行時に使用するデフォルト値を指定します。値は、NULL、ストリング定数、または数値にすることができます。また、状況に依存しない特殊なキーワード CURRENT_TIME、CURRENT_DATE、CURRENT_TIMESTAMP のいずれかを指定することもできます。値が NULL、ストリング定数、または数値の場合は、INSERT ステートメントで列の値が指定されていない場合に、これらがそのまま列に挿入されます。値がCURRENT_TIME、CURRENT_DATE、または CURRENT_TIMESTAMP の場合は、現在の UTC 日付と時刻の一方
または両方が列に挿入されます。CURRENT_TIME の書式は HH:MM:SS です。CURRENT_DATE の書式は YYYYMM-DD です。CURRENT_TIMESTAMP の書式は YYYY-MM-DD HH:MM:SS です。
PRIMARY KEY を指定すると、通常は対応する 1 つまたは複数の列に UNIQUE インデックスが作成されます。ただし、データ型が INTEGER（または int などのシノニムのいずれか）である単一の列に PRIMARY KEY 制約を指定すると、データベースではその列がテーブルの実際の主キーとして使用されます。これは、その列に一意の整数値しか格納できないことを意味します多くの SQLite 実装では、内部主キーとして使用するために指定できる列の型は、INTEGER だけです。
ただし、Adobe AIR では、INTEGER のシノニム（int など）は同様にこの動作を指定できます。
テーブルに INTEGER PRIMARY KEY 列がない場合は、行が挿入されたときに整数キーが自動的に生成されます。行の主キーには、ROWID、OID、_ROWID_ のいずれかの特殊名を使用していつでもアクセスできます。これらの名前は、

INTEGER PRIMARY KEY で明示的に宣言されているか、内部的に生成された値であるかに関係なく使用できます。ただし、テーブルに明示的な INTEGER PRIMARY KEY がない場合、結果データの列の名前は、特殊名ではなく、実際の列名になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1073

ローカルデータベースでの SQL サポート

INTEGER PRIMARY KEY 列には、キーワード AUTOINCREMENT も指定できます。AUTOINCREMENT キーワー
ドを使用する場合、データベースは、列に明示的な値を指定しない INSERT ステートメントの実行時に、順番にインクリメ
ントされる整数キーを自動生成して INTEGER PRIMARY KEY 列内に挿入します。
CREATE TABLE ステートメントには PRIMARY KEY 制約を 1 つだけ含めることができます。これは、ある列の定義の一部または単一のテーブルレベル PRIMARY KEY 制約にすることができます。主キー列は暗黙的に NOT NULL になります。
いくつかの制約の後にオプションの conflict-clause を続けると、その制約に対するデフォルトの制約競合解決アルゴリズムを指定できます。デフォルトは ABORT です。同じテーブル内の異なる制約に対して、異なるデフォルト競合解決アルゴリ
ズムを指定することも可能です。INSERT ステートメントまたは UPDATE ステートメントで異なる競合解決アルゴリズムが指定された場合は、CREATE TABLE ステートメントで指定されたアルゴリズムの代わりにそのアルゴリズムが使用されます。詳しくは、1077 ページの「特殊な文と句」の「ON CONFLICT」を参照してください。

FOREIGN KEY 制約などの追加の制約を指定してもエラーにはなりませんが、実行時に無視されます。
TEMP または TEMPORARY キーワードが CREATE と TABLE の間にある場合、作成されるテーブルは、同じデータ
ベース接続（SQLConnection インスタンス）内でのみ参照できます。データベース接続が終了すると、自動的に削除されます。一時テーブルでは、作成されたインデックスも一時的です。一時テーブルと一時インデックスは、メインのデータ
ベースファイルとは別のファイルに格納されます。
オプションの database-name 接頭辞を指定すると、指定されたデータベース（データベース名を指定して attach() メソッ
ドを呼び出すことによって SQLConnection インスタンスに接続されたデータベース）内にテーブルが作成されます。
database-name 接頭辞と TEMP キーワードを両方とも指定すると、（database-name 接頭辞が temp である場合を除き）
エラーになります。データベース名が指定されておらず、TEMP キーワードが存在しない場合は、メインデータベース（open() または openAsync() メソッドを使用して SQLConnection インスタンスに接続されたデータベース）にテーブルが作成されます。
列数またはテーブル内の制約数に恣意的な制限はありません。1 行のデータ量にも恣意的な制限はありません。

CREATE TABLE AS 形式は、クエリの結果セットでテーブルを定義します。結果に含まれる列の名前がテーブル列の名前になります。
オプションの IF NOT EXISTS 句があり、同じ名前の別のテーブルが既に存在する場合、データベースは CREATETABLE コマンドを無視します。
テーブルは DROP TABLE ステートメントを使用して削除できます。また、ALTER TABLE ステートメントを使用して、限られた範囲で変更を加えることができます。

ALTER TABLE
ALTER TABLE コマンドを使用すると、テーブルの名前を変更したり、既存のテーブルに新しい列を追加したりできます。
テーブルから列を削除することはできません。
sql-statement ::= ALTER TABLE [database-name.] table-name alteration
alteration::= RENAME TO new-table-namealteration::= ADD [COLUMN] column-def

RENAME TO 構文は、[database-name.] table-name で指定されたテーブルの名前を new-table-name に変更します。このコマンドはあくまでも同じデータベース内でテーブル名を変更するためのもので、アタッチされたデータベース間でテーブルを移動することはできません。
名前変更されるテーブルにトリガーまたはインデックスがある場合、それらはテーブル名が変更された後もテーブルにアタッチされたままになります。ただし、名前変更されるテーブルを参照するトリガーによって実行されたビュー定義またはステートメントがある場合は、新しいテーブル名を使用するように自動的に変更されることはありません。名前変更された
テーブルにビューまたはトリガーが関連付けられている場合は、新しいテーブル名を使用してトリガーまたはビュー定義を手動で削除し、再作成する必要があります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1074

ローカルデータベースでの SQL サポート

ADD [COLUMN] 構文は、既存のテーブルに新しい列を追加するときに使用します。新しい列は常に、既存の列リストの最後に追加されます。column-def 句では CREATE TABLE ステートメントで許可されるすべての形式を使用できますが、次のような制限があります。

•

列に PRIMARY KEY 制約または UNIQUE 制約を設定することはできません。

•

列のデフォルト値を CURRENT_TIME、CURRENT_DATE、または CURRENT_TIMESTAMP にすることはできません。

• NOT NULL 制約を指定する場合は、列のデフォルト値を NULL 以外にする必要があります。
ALTER TABLE 文の実行時間は、テーブルに含まれるデータ量には関係ありません。
DROP TABLE
DROP TABLE ステートメントは、CREATE TABLE ステートメントで追加されたテーブルを削除します。削除するテーブルの名前を table-name で指定します。指定したテーブルは、データベースおよびディスクファイルから完全に削除されます。テーブルを復元することはできません。テーブルに関連付けられたインデックスもすべて削除されます。
sql-statement::=

DROP TABLE [IF EXISTS] [database-name.] table-name

デフォルトでは、DROP TABLE 文を実行してもデータベースファイルのサイズは小さくなりません。データベース内に空の領域が保持され、後続の INSERT 操作でその領域が使用されます。データベース内の空き領域を削除するには、

SQLConnection.clean() メソッドを使用します。データベースが最初に作成されたときに autoClean パラメーターが trueに設定された場合は、領域が自動的に解放されます。
オプションの IF EXISTS 句を指定すると、テーブルが存在しない場合に通常発生するエラーが抑制されます。

CREATE INDEXCREATE INDEX コマンドでは、キーワード CREATE INDEX の後に新しいインデックスの名前、キーワード ON および
インデックスの作成対象となる作成済みのテーブルの名前を指定し、その後にインデックスキーに使用するテーブル内の列
名のリストを括弧で囲んで記述します。
sql-statement::=

column-name::=

CREATE [UNIQUE] INDEX [IF NOT EXISTS] [database-name.] index-nameON table-name ( column-name [, column-name]* )name [COLLATE collation-name] [ASC | DESC]

各列名の後にはソート順序を指定する ASC または DESC キーワードを続けることができますが、ソート順序の指定はラン
タイムでは無視されます。ソートは常に昇順で行われます。
各列の後の COLLATE 句は、その列のテキスト値で使用する照合順序を定義します。デフォルトの照合順序は、CREATETABLE 文でその列に定義された照合順序です。照合順序が指定されていない場合は、BINARY 照合順序が使用されます。
COLLATE 句と照合関数の定義については、「COLLATE」を参照してください。

1 つのテーブルにアタッチできるインデックス数に恣意的な制限はありません。インデックス内の列数にも制限はありません。

DROP INDEXDROP INDEX 文は、CREATE INDEX 文で追加されたインデックスを削除します。指定したインデックスは、データ
ベースファイルから完全に削除されます。インデックスを復元する唯一の方法は、適切な CREATE INDEX コマンドを再度発行することです。
sql-statement ::= DROP INDEX [IF EXISTS] [database-name.] index-name

デフォルトでは、DROP INDEX 文を実行してもデータベースファイルのサイズは小さくなりません。データベース内に空の領域が保持され、後続の INSERT 操作でその領域が使用されます。データベース内の空き領域を削除するには、

SQLConnection.clean() メソッドを使用します。データベースが最初に作成されたときに autoClean パラメーターが trueに設定された場合は、領域が自動的に解放されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1075

ローカルデータベースでの SQL サポート

CREATE VIEW
CREATE VIEW コマンドは、あらかじめ定義された SELECT ステートメントに名前を割り当てます。この新しく割り当てた名前は、別の SELECT ステートメントの FROM 句でテーブル名の代わりに使用できます。通常、ビューは、複雑な（および最近使用された）データのセットを他の操作で使用できる構造に結合することで、クエリーを単純化するために使用されます。
sql-statement ::= CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [database-name.] view-name AS selectstatement

CREATE と VIEW の間に TEMP または TEMPORARY キーワードを指定すると、作成されたビューはデータベースを開いた SQLConnection インスタンスからのみ見えるようになり、データベースが閉じると自動的に削除されます。
[database-name] を指定すると、指定されたデータベース（name 引数を指定した attach() メソッドを使用して
SQLConnection インスタンスに接続されたデータベース）内にビューが作成されます。[database-name] と TEMP キー
ワードを両方とも指定すると、（[database-name] が temp である場合を除き）エラーになります。データベース名が指定されておらず、TEMP キーワードが存在しない場合は、メインデータベース（open() または openAsync() メソッドを使用
して SQLConnection インスタンスに接続されたデータベース）にビューが作成されます。
ビューは読み取り専用です。対応するタイプのトリガー（INSTEAD OF DELETE、INSTEAD OF INSERT、INSTEAD
OF UPDATE）が少なくとも 1 つ定義されていない限り、ビューに対して DELETE ステートメント、INSERT ステートメ
ント、または UPDATE ステートメントを使用することはできません。ビューに対するトリガーの作成について詳しくは、「CREATE TRIGGER」を参照してください。
ビューをデータベースから削除するには、DROP VIEW 文を使用します。

DROP VIEW
DROP VIEW ステートメントは、CREATE VIEW ステートメントで作成されたビューを削除します。
sql-statement ::= DROP VIEW [IF EXISTS] view-name

削除するビューの名前を view-name で指定します。ビューはデータベースから削除されますが、基になるテーブルのデー
タは変更されません。

CREATE TRIGGER
CREATE TRIGGER 文は、データベーススキーマにトリガーを追加するときに使用します。トリガーとは、指定されたデータベースイベント（database-event）が発生したときに自動的に実行されるデータベース操作（trigger-action）のことです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1076

ローカルデータベースでの SQL サポート

sql-statement::=sql-statement::=

database-event::=

trigger-action::=

trigger-step::=column-list::=

CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] [database-name.] trigger-name[BEFORE | AFTER] database-event
ON table-nametrigger-action
CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] [database-name.] trigger-name
INSTEAD OF database-event
ON view-nametrigger-action
DELETE |INSERT |UPDATE |UPDATE OF column-list[FOR EACH ROW] [WHEN expr]
BEGIN
trigger-step ;[ trigger-step ; ]*END
update-statement |insert-statement |delete-statement |select-statement
column-name [, column-name]*

トリガーは、特定のデータベーステーブルに対して DELETE、INSERT、または UPDATE が発生したときや、テーブルの指定された 1 つ以上の列に対して UPDATE が行われたときにその都度実行されるよう指定できます。トリガーは、

TEMP または TEMPORARY キーワードが使用されていない限り永続的です。その場合、トリガーは、SQLConnection
インスタンスのメインデータベース接続が終了すると削除されます。タイミング（BEFORE または AFTER）が指定されていない場合、デフォルトのタイミングは BEFORE になります。
FOR EACH ROW トリガーのみがサポートされているので、FOR EACH ROW キーワードはオプションです。FOREACH ROW トリガーでは、WHEN 句の式が true に評価された場合、トリガーの起動元のステートメントによって挿入、更新または削除された各データベース行に対して、trigger-step ステートメントが実行されます。
WHEN 句を指定すると、WHEN 句が true に評価された行に対してのみ、trigger-steps として指定した SQL 文が実行されます。WHEN 句を指定しなければ、すべての行に対して SQL 文が実行されます。
トリガーの本文内で（trigger-action 句）、特別なテーブル名 OLD および NEW を使用して、影響を受けるテーブルの変更
前および変更後の値を使用できます。OLD テーブルと NEW テーブルの構造は、トリガーを作成するテーブルの構造と一致します。OLD テーブルには、トリガーを発生させた文によって変更または削除された行の、操作が行われる前の状態が含まれます。NEW テーブルには、トリガーを発生させた文によって変更または作成された行の、操作が行われた後の状態が含まれます。WHEN 句と trigger-step ステートメントのどちらからも、NEW.column-name および OLD.column-

name（column-name はトリガーが関連付けられているテーブルの列の名前）の形式の参照を使用して、挿入、削除、または更新される（された）行の値にアクセスできます。OLD テーブルと NEW テーブルの参照を使用できるかどうかは、トリガーが処理する database-event の種類によって決まります。

• INSERT – NEW 参照が有効です。
• UPDATE – NEW および OLD 参照が有効です。
• DELETE – OLD 参照が有効です。
タイミングの指定（BEFORE、AFTER、または INSTEAD OF）は、trigger-step ステートメントが、関連する行の挿入
時、変更時、または削除時を基準としていつ実行されるかを決定します。trigger-step 内の UPDATE ステートメントまたは INSERT ステートメントの一部として ON CONFLICT 句を指定することもできますが、トリガーを発生させた文の一部として ON CONFLICT 句が指定されている場合は、代わりにその競合処理ポリシーが使用されます。
テーブルのトリガーに加えて、INSTEAD OF トリガーをビューに対して作成できます。1 つ以上の INSTEAD OF

INSERT、INSTEAD OF DELETE、または INSTEAD OF UPDATE トリガーがビューに定義されている場合は、対応するタイプのステートメント（INSERT、DELETE、または UPDATE）をビューで実行してもエラーとは見なされません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1077

ローカルデータベースでの SQL サポート

その場合は、INSERT、DELETE、または UPDATE をビューで実行すると、対応するトリガーが発生します。トリガーはINSTEAD OF トリガーなので、ビューの基礎となるテーブルは、トリガーが起動する原因となったステートメントによって変更されません。ただし、トリガーは、基礎となるテーブルに対して変更操作を実行するために使用できます。

INTEGER PRIMARY KEY 列を持つテーブルにトリガーを作成するときは、注意すべき重要な問題があります。トリガーを起動したステートメントによって更新される行の INTEGER PRIMARY KEY 列が BEFORE トリガーによって変更された場合は、更新が行われません。この問題を回避するには、INTEGER PRIMARY KEY 列の代わりに PRIMARY KEY 列を持つテーブルを作成します。
トリガーは DROP TRIGGER 文を使用して削除できます。テーブルまたはビューが削除されると、そのテーブルまたは
ビューに関連付けられたトリガーもすべて自動的に削除されます。

RAISE() 関数
特殊な SQL 関数である RAISE() は、トリガーの trigger-step ステートメントの中で使用できます。この関数の構文は次のとおりです。
raise-function::=

RAISE ( ABORT, error-message ) |RAISE ( FAIL, error-message ) |RAISE ( ROLLBACK, error-message ) |RAISE ( IGNORE )最初の 3 つの形式の 1 つがトリガーの実行中に呼び出されると、指定された ON CONFLICT 処理アクション（ABORT、

FAIL、または ROLLBACK）が実行され、現在のステートメントの実行が終了します。ROLLBACK はステートメントの実行エラーと見なされるため、execute() メソッドが実行された SQLStatement インスタンスによって error（SQLErrorEvent.ERROR）イベントが送出されます。送出されたイベントオブジェクトの error プロパティ内にある

SQLError オブジェクトの details プロパティは、RAISE() 関数で指定された error-message に設定されています。
RAISE(IGNORE) を呼び出すと、現在のトリガーの残りの部分、トリガーを発生させた文、および通常であれば引き続き実行されるはずの別のトリガーがすべて中止されます。データベースの変更はロールバックされません。トリガーを発生させた文自体がトリガーの一部である場合、そのトリガープログラムは次のステップの最初から再開されます。競合解決アルゴリズムについて詳しくは、「ON CONFLICT（競合アルゴリズム）」を参照してください。

DROP TRIGGER
DROP TRIGGER 文は、CREATE TRIGGER 文で作成されたトリガーを削除します。
sql-statement::=

DROP TRIGGER [IF EXISTS] [database-name.] trigger-name

トリガーはデータベースから削除されます。関連付けられたテーブルが削除されたときにも、トリガーは自動的に削除されます。

特殊な文と句
この節では、SQL の拡張機能としてランタイムによって提供されるいくつかの句と、多くの文で使用できる 2 つの言語要素（コメントと式）について説明します。

COLLATECOLLATE 句は、値の比較またはソート時に使用する比較アルゴリズムを指定するために、SELECT ステートメント、
CREATE TABLE ステートメントおよび CREATE INDEX ステートメントで使用します。
sql-statement
collation-name

::=
::=

COLLATE collation-name
BINARY | NOCASE

列のデフォルトの照合タイプは BINARY です。TEXT 格納クラスの値で BINARY 照合を使用すると、テキストがどのようにしてエンコードされているかにかかわらず、値を表すメモリ内のバイトを比較することによってバイナリ照合が行われます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1078

ローカルデータベースでの SQL サポート

NOCASE 照合シーケンスは、TEXT 格納クラスの値に対してのみ適用されます。NOCASE 照合を使用すると、大文字と小文字を区別せずに比較されます。

NULL、BLOB、INTEGER、REAL 型の格納クラスでは、照合シーケンスは使用されません。
BINARY 以外の照合タイプを列で使用するには、CREATE TABLE ステートメントの列定義の一部として COLLATE 句を指定する必要があります。2 つの TEXT 値を比較するときは常に、照合順序を使用し、次の規則に従って比較結果が決定
されます。

•

二項比較演算子では、一方のオペランドが列である場合、その列のデフォルトの照合タイプによって、比較で使用される照合シーケンスが決まります。両方のオペランドが列である場合は、左のオペランドの照合タイプによって、使用される照合順序が決まります。どちらのオペランドも列でない場合は、BINARY 照合順序が使用されます。

• BETWEEN...AND 演算子は、2 つの式に対して >= 演算子と <= 演算子を使用するのと同じです。例えば、xBETWEEN y AND z という式は x >= y AND x <= z と同じです。したがって、BETWEEN...AND 演算子も上記の規則に従って照合シーケンスが決定されます。

• IN 演算子は、使用する照合シーケンスを決定するという点では、= 演算子と同じように動作します。例えば、x IN (y,z) という式で使用される照合シーケンスは、x が列の場合は x のデフォルトの照合タイプになります。それ以外の場合
は、BINARY 照合が使用されます。
• SELECT ステートメントでは、ORDER BY 句の中で、ソート操作で使用する照合シーケンスを明示的に指定できます。
その場合は、明示的に指定した照合順序が常に使用されます。それ以外の場合は、ORDER BY 句によってソートされる
式が列の場合には、その列のデフォルトの照合タイプを使用してソート順序が決定されます。式が列でない場合は、

BINARY 照合順序が使用されます。
EXPLAIN
EXPLAIN コマンド修飾子は、SQL の非標準の拡張機能です。
sql-statement::=

EXPLAIN sql-statement

SQL ステートメントの前に EXPLAIN キーワードを付けると、コマンドを実際に実行する代わりに、EXPLAIN キーワー
ドを指定せずにコマンドを実行した場合に使用される一連の仮想マシン命令が報告されます。この高度な EXPLAIN 機能を使用すると、SQL ステートメントのテキストを調整してパフォーマンスを最適化したり、適切に機能しない SQL ステート
メントをデバッグしたりできます。

ON CONFLICT（競合アルゴリズム）
ON CONFLICT 句は独立した SQL コマンドではありません。これは他の多くの SQL コマンドで使用できる非標準の句です。
conflict-clauseconflict-clauseconflict-algorithm

::=
::=
::=

ON CONFLICT conflict-algorithm
OR conflict-algorithm
ROLLBACK |ABORT |
FAIL |IGNORE |REPLACE

最初の形式の、キーワード ON CONFLICT を使用する ON CONFLICT 句は、CREATE TABLE ステートメントで使用します。INSERT ステートメントまたは UPDATE ステートメントでは、構ステートメントがより自然に見えるように、
ON CONFLICT が OR に置き換えられた 2 番目の形式を使用します。例えば、INSERT ON CONFLICT IGNORE は
INSERT OR IGNORE になります。キーワードは異なりますが、句の意味はどちらの形式でも同じです。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1079

ローカルデータベースでの SQL サポート

ON CONFLICT 句は、制約競合の解決に使用するアルゴリズムを指定します。指定できるアルゴリズムは、
ROLLBACK、ABORT、FAIL、IGNORE、REPLACE の 5 種類です。デフォルトのアルゴリズムは ABORT です。これら 5 種類の競合アルゴリズムについて以下に説明します。
ROLLBACK 制約違反が発生すると、直ちに ROLLBACK が実行され、現在のトランザクションが終了します。コマンドは中止され、SQLStatement インスタンスによって error イベントが送出されます。トランザクションがアクティブでない
場合（すべてのコマンドについて作成される暗黙的なトランザクションを除く）、このアルゴリズムは ABORT と同じです。
ABORT 制約違反が発生すると、そのコマンドによる変更がすべて取り消され、SQLStatement インスタンスによって
error イベントが送出されます。ROLLBACK は実行されないので、トランザクション内の前のコマンドで行われた変更はそのまま残ります。ABORT はデフォルトの動作です。
FAIL 制約違反が発生すると、コマンドが中止され、SQLStatement によって error イベントが送出されます。ただし、制約違反が発生する前にそのステートメントによってデータベースに加えられた変更は取り消されずにそのまま残ります。例
えば、UPDATE ステートメントの実行時に更新対象の 100 行目で制約違反が発生した場合、それまでの 99 行の変更はそのまま残りますが、100 行目以降の変更は行われません。

IGNORE 制約違反が発生したとき、制約違反を含む 1 行は挿入も変更もされません。行が無視されるという点を除き、コ
マンドは通常どおり続行されます。制約違反が発生した行の前後の行は通常どおり挿入または更新されます。エラーは返されません。

REPLACE UNIQUE 制約違反が発生すると、制約違反の原因となる既存の行が削除された後で、現在の行が挿入または更新されます。したがって、挿入または更新は常に実行され、コマンドは通常どおり続行されます。エラーは返されません。

NOT NULL 制約違反が発生した場合は、NULL 値がその列のデフォルト値で置き換えられます。列にデフォルト値がない
場合は、ABORT アルゴリズムが使用されます。CHECK 制約違反が発生した場合は、IGNORE アルゴリズムが使用されます。この競合解決方法により、制約を満たすために行が削除されたときは、それらの行に対する削除トリガーは呼び出されません。

INSERT ステートメントまたは UPDATE ステートメントの OR 句で指定されたアルゴリズムは、CREATE TABLE ス
テートメントで指定されたアルゴリズムよりも優先されます。CREATE TABLE ステートメントおよび実行中の INSERT
ステートメントまたは UPDATE ステートメントのどちらでもアルゴリズムが指定されていない場合は、ABORT アルゴリ
ズムが使用されます。

REINDEXREINDEX コマンドは、1 つ以上のインデックスを削除して再作成するときに使用します。このコマンドは、照合シーケンスの定義が変更されたときに便利です。
sql-statementsql-statement

::=
::=

REINDEX collation-name
REINDEX [database-name .] ( table-name | index-name )最初の形式では、アタッチされたデータベース内の指定された照合順序を使用するすべてのインデックスが再作成されます。

2 番目の形式では、table-name を指定した場合、そのテーブルに関連付けられたすべてのインデックスが再構築されます。
index-name を指定した場合は、指定したインデックスのみが削除され、再作成されます。
コメント
コメントは SQL コマンドではありませんが、SQL クエリの中に記述できます。コメントはランタイムでは空白として扱われます。コメントは、空白が許可される任意の場所（複数行にわたる式の内部など）に記述できます。
comment::=

single-line-comment ::=block-comment::=

single-line-comment |block-comment-- single-line/* multiple-lines or block [*/]

単一行のコメントには 2 つのダッシュを使用します。単一行コメントでは、その行の末尾までがコメントになります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1080

ローカルデータベースでの SQL サポート

ブロックコメントは、任意の行数にわたることも、単一行に埋め込むこともできます。コメントの終わりを示す区切り記号がない場合は、入力の最後までがコメントになります。これはエラーとして扱われません。新しい SQL 文は、ブロックコメ
ントが終了した後の行から開始できます。ブロックコメントは、空白が許可される任意の場所（式の内部など）のほか、他の SQL 文の中にも埋め込むことができます。ブロックコメントはネストされません。ブロックコメントの中に単一行コメン
トを記述しても無視されます。
式
式は他の SQL ブロック内のサブコマンドです。SQL 文で使用する式の有効な構文を次に示します。
expr

::=

expr binary-op expr |expr [NOT] like-op expr [ESCAPE expr] |unary-op expr |( expr ) |column-name |table-name.column-name |database-name.table-name.column-name |literal-value |parameter |function-name( expr-list | * ) |expr ISNULL |expr NOTNULL |expr [NOT] BETWEEN expr AND expr |expr [NOT] IN ( value-list ) |expr [NOT] IN ( select-statement ) |expr [NOT] IN [database-name.] table-name |[EXISTS] ( select-statement ) |CASE [expr] ( WHEN expr THEN expr )+ [ELSE expr] END |CAST ( expr AS type ) |expr COLLATE collation-namelike-op::= LIKE | GLOB
binary-op::= see Operators
unary-op::= see Operators
parameter::= :param-name | @param-name | ?
value-list::= literal-value [, literal-value]*
literal-value::= literal-string | literal-number | literal-boolean | literal-blob | literal-nullliteral-string ::= 'string value'
literal-number ::= integer | number
literal-boolean ::= true | false
literal-blob ::= X'string of hexadecimal data'
literal-null ::= NULL

式とは、単一の値に解決できる値と演算子の任意の組み合わせを指します。式はブール値（true または false）に解決されるものと、非ブール値に解決されるものの 2 種類に大別されます。

WHERE 句、HAVING 句、JOIN 句の中の ON 式、CHECK 式などで使用する式は、ブール値に解決される必要があります。この条件を満たす式の種類は次のとおりです。

• ISNULL• NOTNULL• IN ()• EXISTS ()• LIKE• GLOB•

いくつかの関数•

いくつかの演算子（具体的には比較演算子）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1081

ローカルデータベースでの SQL サポート

リテラル値
リテラルの数値は、整数または浮動小数点数として記述します。科学的表記法もサポートされます。小数点には常に .（ピリオド）を使用します。
ストリングリテラルを示すときは、ストリングを一重引用符（'）で囲みます。ストリングの中に一重引用符を含めるには、'' のように一重引用符を行で 2 つ重ねます。
ブールリテラルの値は true または false で示します。リテラルブール値は、列のデータ型が Boolean の場合に使用します。

BLOB リテラルは 16 進数データを含むストリングリテラルで、1 つの x または X を先頭に付けます（X'53514697465' など）。
リテラル値にはトークン NULL も使用できます。
列名
列名には、CREATE TABLE ステートメントで定義されたいずれかの名前、または特殊識別子の ROWID、OID、_ROWID_ のいずれかを使用できます。これらの特殊識別子はすべて、各テーブルのすべての行に関連付けられた一意のランダムな整数キー（" 行キー "）を表します。特殊識別子は、CREATE TABLE 文で同じ名前を持つ実際の列が定義されていない場合のみ、行キーを参照します。行キーは読み取り専用列のように動作します。行キーは通常の列が使用できる場所
であればどこでも使用できますが、行キーの値を UPDATE ステートメントまたは INSERT ステートメントで変更することはできません。SELECT * FROM table 文で返される結果セットには、行キーは含まれません。

SELECT 文
IN 演算子の右オペランド、スカラ量（単一の結果値）、または EXISTS 演算子のオペランドとして式を使用するときは、
SELECT ステートメントを使用できます。スカラ量または IN 演算子のオペランドとして使用する場合、SELECT 文で返すことができるのは 1 つの列のみです。複合 SELECT ステートメント（UNION や EXCEPT などのキーワードで接続された
SELECT ステートメント）も使用できます。EXISTS 演算子では、SELECT 文の結果セットに含まれる列は無視され、行が1 行以上存在する場合は TRUE、結果セットが空の場合は FALSE が返されます。SELECT 式のどの項も外側のクエリの値を参照しない場合、式は他の処理が実行される前に 1 回だけ評価され、その結果が必要に応じて再利用されます。SELECT式に外部クエリからの変数が含まれる場合（これを相関サブクエリと呼びます）、SELECT 文は必要になるたびに再評価されます。

SELECT ステートメントが IN 演算子の右オペランドである場合、IN 演算子は、左オペランドの結果が SELECT ステート
メントの結果セットに含まれるいずれかの値と等しい場合に TRUE を返します。IN 演算子の前に NOT キーワードを付けると、テストの意味が逆になります。

IN 演算子の右オペランド以外の式で SELECT 文を使用する場合は、SELECT 文の結果の 1 行目が値として使用されます。
SELECT ステートメントが複数行の結果を返す場合、2 行目以降の行はすべて無視されます。SELECT 文が行を 1 行も返さない場合、SELECT 文の値は NULL になります。
CAST 式CAST 式は、指定された値のデータ型を別の指定されたデータ型に変更します。指定できるデータ型は、CREATE TABLE
文の列定義でデータ型として使用できる空でない型名です。詳しくは、「データ型のサポート」を参照してください。
その他の式要素
式で使用できるその他の SQL 要素は以下のとおりです。

•

ビルトイン関数：集計関数、スカラ関数、および日付 / 時刻書式設定関数

•

演算子

•

パラメーター

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1082

ローカルデータベースでの SQL サポート

ビルトイン関数
ビルトイン関数は次の 3 種類に大別されます。

•

集計関数

•

スカラ関数

•

日時関数

これらの関数に加えて、特殊関数の RAISE() もあります。これは、トリガーの実行時にエラー通知を提供するために使用します。この関数は、CREATE TRIGGER 文の本体でのみ使用できます。RAISE() 関数について詳しくは、「CREATE
TRIGGER」の「RAISE()」を参照してください。

SQL のすべてのキーワードと同様に、関数名も大文字と小文字は区別されません。
集計関数
集計関数は、複数行の値に対して演算を実行します。これらは主に SELECT ステートメントの中で GROUP BY 句と一緒に使用します。
AVG(X)

グループ内の NULL でないすべての X の平均値を返します。数値に見えないストリング値およびBLOB 値は 0 と見なされます。AVG() の結果は、入力がすべて整数であっても、常に浮動小数点値
COUNT(X)
COUNT(*)
MAX(X)MIN(X)です。
最初の形式は、グループ内で X が NULL でない回数を返します。* 引数の付いた 2 番目の形式は、グループ内の行の総数を返します。
グループ内のすべての値の最大値を返します。通常のソート順序を使用して最大値が決定されます。
グループ内のすべての値のうち、NULL でない最小の値を返します。通常のソート順序を使用して最小値が決定されます。グループ内の値がすべて NULL の場合は、NULL が返されます。

SUM(X)TOTAL(X)

グループ内の NULL でないすべての値の合計を返します。値がすべて NULL の場合には、SUM() は

NULL を返し、TOTAL() は 0.0 を返します。TOTAL() の結果は常に浮動小数点値です。SUM() の結果は、NULL 以外の入力がすべて整数の場合は整数値になります。SUM() への入力に整数でもNULL でもない値が含まれている場合、SUM() は浮動小数点値を返しますが、この値は正確な合計の近似値である場合があります。

上記の集計関数のうち引数を 1 つ受け取るものはいずれも、その引数の前にキーワード DISTINCT を付けることができます。その場合は、重複した要素が除外されてから集計関数に渡されます。例えば、関数が COUNT(DISTINCT x) を呼び出すと、列 x の NULL でない値の総数ではなく、列 X の互いに異なる値の数が返されます。
スカラ関数
スカラ関数は一度に 1 つの行の値に作用します。
ABS(X)
COALESCE(X, Y, ...)

引数 X の絶対値を返します。

NULL でない最初の引数のコピーを返します。引数がすべて NULL の場合は、NULL が返されます。
引数は 2 つ以上指定する必要があります。

GLOB(X, Y)
IFNULL(X, Y)
HEX(X)
LAST_INSERT_ROWID()

この関数は、X GLOB Y 構文を実装するために使用されます。
NULL でない最初の引数のコピーを返します。引数がどちらも NULL の場合は、NULL が返されます。この関数の動作は COALESCE() と同じです。
引数は BLOB 格納型の値と解釈されます。その値の内容の 16 進数表現が返されます。
現在の SQLConnection を通じてデータベースに最後に挿入された行の行識別子（生成された主キー）を返します。この値は、SQLConnection.lastInsertRowID プロパティによって返される値と同じです。

LENGTH(X)
LIKE(X, Y [, Z])

LOWER(X)LTRIM(X) LTRIM(X, Y)

X のストリングの長さ（文字数）を返します。
この関数は、SQL の X LIKE Y [ESCAPE Z] 構文を実装するために使用されます。オプションの
ESCAPE 句を指定すると、3 つの引数を使用して関数が呼び出されます。それ以外の場合は、2 つの引数のみを使用して関数が呼び出されます。
ストリング X の、すべての文字が小文字に変換されたコピーを返します。

X の左側からスペースを除去したストリングを返します。Y 引数を指定すると、Y に含まれるいずれかの文字が X の左側から除去されます。

MAX(X, Y, ...)

引数の中の最大値を返します。引数には、数字だけでなくストリングも指定できます。最大値は、定義されたソート順序に従って決定されます。MAX() は、引数が 2 個以上ある場合は単純な関数ですが、引数が 1 つだけの場合は集計関数になります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1083

ローカルデータベースでの SQL サポートMIN(X, Y, ...)

引数の中の最小値を返します。引数には、数字だけでなくストリングも指定できます。最小値は、定義されたソート順序に従って決定されます。MIN() は、引数が 2 個以上ある場合は単純な関数で

NULLIF(X, Y)
QUOTE(X)

引数が異なる場合は最初の引数を返し、それ以外の場合は NULL を返します。

すが、引数が 1 つだけの場合は集計関数になります。
このルーチンは、引数の値を別の SQL 文に挿入するのに適した形に変更したストリングを返します。ストリングは一重引用符で囲まれ、必要に応じて内部引用符がエスケープされます。BLOB 格
納クラスは 16 進数のリテラルとしてエンコードされます。この関数は、元に戻す / 繰り返し機能を実装するためのトリガーを記述する場合に役立ちます。

RANDOM(*)-9223372036854775808 から 9223372036854775807 までの疑似乱数（整数）を返します。こRANDOMBLOB(N)

れは暗号的に強い乱数ではありません。
疑似ランダムバイトを含む N バイトの BLOB を返します。N は正の整数である必要があります。これは暗号的に強いランダム値ではありません。N の値が負の場合は、単一のバイトが返されます。

ROUND(X) ROUND(X,Y)
RTRIM(X) RTRIM(X, Y)

数値 X を小数第 Y 位に四捨五入します。Y 引数を省略すると、0 が使用されます。

X の右側からスペースを除去したストリングを返します。Y 引数を指定すると、Y に含まれるいずれかの文字が X の右側から除去されます。

SUBSTR(X, Y, Z)

入力ストリング X の Y 番目の文字から Z 個の文字を取り出したサブストリングを返します。X の一番左の文字のインデックス位置は 1 です。Y が負の場合は、サブストリングの開始位置が左からでTRIM(X) TRIM(X, Y)

はなく右からカウントされます。
X の右側からスペースを除去したストリングを返します。Y 引数を指定すると、Y に含まれるいずれ

TYPEOF(X)

式 X の型を返します。有効な戻り値は、「null」、「integer」、「real」、「text」および「blob」でかの文字が X の右側から除去されます。

UPPER(X)ZEROBLOB(N)す。データ型について詳しくは、「データ型のサポート」を参照してください。
ストリング X の、すべての文字が大文字に変換されたコピーを返します。

N バイトの 0x00 を含む BLOB を返します。

日付 / 時刻書式設定関数
日付 / 時刻書式設定関数は、書式設定された日付および時刻データの作成に使用するスカラ関数のグループです。これらはストリング値および数値を引数とし、ストリング値および数値を返します。DATE データ型に対して使用するものではありません。DATE データ型で宣言された列のデータを使用する場合、これらの関数は期待どおりに動作しません。
DATE(T, ...)DATE() 関数は、YYYY-MM-DD 形式の日付を含むストリングを返します。最初のパラメーター（T）では、「時刻書式」で示された書式の時刻ストリングを指定します。時刻ストリングの後に任意TIME(T, ...)の数の修飾子を指定できます。修飾子については、「修飾子」を参照してください。
TIME() 関数は、HH:MM:SS 形式の時刻を含むストリングを返します。最初のパラメーター（T）では、「時刻書式」で示された書式の時刻ストリングを指定します。時刻ストリングの後に任意の数の修飾子を指定できます。修飾子については、「修飾子」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1084

ローカルデータベースでの SQL サポート

DATETIME(T, ...)DATETIME() 関数は、YYYY-MM-DD HH:MM:SS 形式の日時を含むストリングを返します。最初のパラメーター（T）では、「時刻書式」で示された書式の時刻ストリングを指定します。時刻ストリ

JULIANDAY(T, ...)

ングの後に任意の数の修飾子を指定できます。修飾子については、「修飾子」を参照してください。
JULIANDAY() 関数は、グリニッジでの紀元前 4714 年 11 月 24 日の正午から指定された日付までの日数を示す数字を返します。最初のパラメーター（T）では、「時刻書式」で示された書式の時刻

STRFTIME(F, T, ...)

ストリングを指定します。時刻ストリングの後に任意の数の修飾子を指定できます。修飾子については、「修飾子」を参照してください。
STRFTIME() ルーチンは、最初の引数 F で指定された書式ストリングに従って書式設定された日付を返します。書式ストリングでは、次の置換がサポートされます。

%d - 月の日にち%f - 秒の端数（SS.SSS）%H - 時間（00 〜 24）%j - 1 月 1 日からの日数（001 〜 366）
%J - ユリウス日%m - 月（01 〜 12）%M - 分（00 〜 59）%s - 1970 年 1 月 1 日からの秒数%S - 秒（00 〜 59）%w - 曜日（0 〜 6、日曜日 = 0）
%W - 1 月 1 日からの週数（00 〜 53）%Y - 年（0000 〜 9999）%% - %
2 番目のパラメーター（T）では、「時刻書式」で示された書式の時刻ストリングを指定します。時刻ストリングの後に任意の数の修飾子を指定できます。修飾子については、「修飾子」を参照してく
ださい。

時刻書式
時刻ストリングには、次のいずれかの書式を使用できます。
YYYY-MM-DD
YYYY-MM-DD HH:MMYYYY-MM-DD HH:MM:SSYYYY-MM-DD HH:MM:SS.SSS
YYYY-MM-DDTHH:MMYYYY-MM-DDTHH:MM:SSYYYY-MM-DDTHH:MM:SS.SSS
HH:MM
HH:MM:SS
HH:MM:SS.SSS
now
DDDD.DDDD

2007-06-15
2007-06-15 07:30
2007-06-15 07:30:59
2007-06-15 07:30:59.152
2007-06-15T07:30
2007-06-15T07:30:59
2007-06-15T07:30:59.152
07:30（日付は 2000-01-01）
07:30:59（日付は 2000-01-01）
07:30:59:152（日付は 2000-01-01）
現在の日時（世界標準時）
ユリウス日（浮動小数点数）

上記の書式に含まれる T は、日付と時間を区切るリテラル文字の "T" です。時刻のみを含む書式では、日付は 2001-01-01と見なされます。
修飾子
時刻ストリングの後に修飾子を 0 個以上続けることで、日付または日付の解釈を変更できます。使用できる修飾子は次のとおりです。
NNN days
NNN hours
NNN minutes
NNN.NNNN seconds

時刻に加算する日数です。
時刻に加算する時間数です。
時刻に加算する分数です。
時刻に加算する秒数およびミリ秒数です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1085

ローカルデータベースでの SQL サポート

時刻に加算する月数です。

NNN months
NNN years
start of monthstart of year
start of day
weekday N
localtime
utc

時刻に加算する年数です。
時刻を月の初めに戻します。
時刻を年の初めに戻します。
時刻を日の初めに戻します。
時刻を指定した曜日に進めます（0 = 日曜日、1 = 月曜日など）。
日付をローカル時間に変換します。
日付を世界標準時に変換します。

演算子
SQL は様々な演算子をサポートしており、ほとんどのプログラミング言語に存在する一般的な演算子のほか、SQL に固有の演算子もあります。
一般的な演算子
次のリストは、SQL ブロックで使用できる二項演算子を優先順位の高い順に並べたものです。
*/%+<< >> & |
< >=
> >=
=
==
!=
AND
OR

<> IN

単項前置演算子は次のものがサポートされています。
!

~

NOT

COLLATE 演算子は単項後置演算子と見なすことができます。COLLATE 演算子は優先順位が最も高く、常に他のどの前置単項演算子や二項演算子よりも強く結び付きます。
等号演算子と不等号演算子はそれぞれ 2 種類あります。等号演算子は = または ==、不等号演算子は != または <> です。

|| はストリングを連結する演算子で、そのオペランドである 2 つのストリングを 1 つにつなげます。
% 演算子は、右オペランドを法とする左オペランドの剰余を返します。
二項演算子の結果は数値です。ただし、|| 連結演算子だけは例外で、結果がストリングになります。

SQL 演算子
LIKE
LIKE 演算子は、パターンマッチングによる比較を行います。
expr
pattern::=::=(column-name | expr) LIKE pattern'[ string | % | _ ]'LIKE 演算子の右オペランドにはパターンを指定し、左オペランドにはそのパターンと照合するストリングを指定します。
パターン内のパーセント記号（%）はワイルドカード文字で、ストリング内の 0 個以上連続した文字に一致します。パターン内のアンダースコア（_）はストリング内の任意の 1 文字に一致します。その他の文字はすべて、その文字そのものとして、大文字と小文字を区別せずに照合されます。（メモ：データベースエンジンでは、7 ビットラテン文字の大文字と小文字のみが理解されます。したがって、8 ビット iso8859 文字または UTF-8 文字では、LIKE 演算子は大文字と小文字を区別します。例えば、'a' LIKE 'A' という式は TRUE になりますが、'æ' LIKE 'Æ' は FALSE になります）。ラテン文字の大文字と小文字を区別するかどうかを切り替えるには、SQLConnection.caseSensitiveLike プロパティを使用します。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1086

ローカルデータベースでの SQL サポート

オプションの ESCAPE 句を指定する場合、ESCAPE キーワードの後に続く式は、1 文字で構成されるストリングに評価される必要があります。この文字は、LIKE パターンの中で、リテラルのパーセントまたはアンダースコア文字を照合するために使用できます。パターン内でエスケープ文字の後にパーセント記号、アンダースコア、またはエスケープ文字自体を記述すると、それらはそれぞれ、ストリング内のリテラルのパーセント記号、アンダースコア、またはエスケープ文字に一致
します。

GLOB
GLOB 演算子は LIKE と似ていますが、ワイルドカードとして UNIX のファイルグロビング構文を使用します。LIKE とは異なり、GLOB では大文字と小文字は区別されます。
IN
IN 演算子は、左オペランドが、右オペランド（括弧で囲まれた値のリスト）内のいずれかの値と等しいかどうかを返します。
in-expr::=value-list::=

expr [NOT] IN ( value-list ) |expr [NOT] IN ( select-statement ) |expr [NOT] IN [database-name.] table-nameliteral-value [, literal-value]*

右オペランドには複数のリテラル値をカンマで区切って記述するか、SELECT 文を記述します。IN 演算子の右オペランド
として SELECT ステートメントを使用する際の説明と制限については、「式」の「SELECT ステートメント」を参照してく
ださい。

BETWEEN...AND
BETWEEN...AND 演算子は、2 つの式に対して >= 演算子と <= 演算子を使用するのと同じです。例えば、x BETWEENy AND z という式は x >= y AND x <= z と同じです。
NOT
NOT は否定の演算子です。GLOB、LIKE および IN 演算子の前に NOT キーワードを付けると、テストの意味が逆になります（つまり、値が指定のパターンと一致しないことが確認されます）。

パラメーター
パラメーターは、式の中でリテラル値を表すためのプレースホルダーを指定します。このプレースホルダーには、

SQLStatement.parameters 結合配列に値を設定することで、実行時に値が格納されます。パラメーターは次の 3 つの形式をとります。
?

疑問符はインデックス付きのパラメーターを示します。この形式のパラメーターには、SQL ステー
トメントに登場した順に数値インデックス値が割り当てられます。インデックス値は 0 から始まり

:AAAA

ます。
コロンの後に識別子名が付いた形式は、AAAA という名前の名前付きパラメーター用の場所を保持@AAAA

乱を避けるために、名前付きパラメーターとインデックス付きパラメーターを混在させないことをお勧めします。
"@" はコロンと同じです。

します。名前付きパラメーターにも、SQL 文に登場した順に数値インデックスが付けられます。混

サポートされていない SQL 機能
Adobe AIR でサポートされていない標準 SQL 要素は次のとおりです。
FOREIGN KEY 制約 FOREIGN KEY 制約は、解析はされますが適用されません。
トリガー FOR EACH STATEMENT トリガーはサポートされていません（トリガーはすべて FOR EACH ROW にする
必要があります）。INSTEAD OF トリガーはテーブルではサポートされていません（INSTEAD OF トリガーはビューに対してのみ使用できます）。再帰トリガー（自分自身をトリガーするトリガー）はサポートされていません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1087

ローカルデータベースでの SQL サポート

ALTER TABLE ALTER TABLE コマンドでは、RENAME TABLE バリアントと ADD COLUMN バリアントのみがサポートされています。その他の種類の ALTER TABLE 操作（DROP COLUMN、ALTER COLUMN、ADD

CONSTRAINT など）は無視されます。
ネストされたトランザクション 単一のアクティブトランザクションのみが許可されます。

RIGHT および FULL OUTER JOIN RIGHT OUTER JOIN または FULL OUTER JOIN はサポートされていません。
更新可能なビュー ビューは読み取り専用です。ビューに対して DELETE ステートメント、INSERT ステートメント、または UPDATE ステートメントは実行できません。ビューを DELETE、INSERT、または UPDATE しようとしたときに起動される INSTEAD OF トリガーはサポートされており、このトリガーの本体で基になるテーブルを更新できます。

GRANT と REVOKE データベースは通常のディスクファイルです。つまり、アクセス許可として適用できるのは、基になるオペレーティングシステムの通常のファイルアクセス許可のみです。クライアント / サーバー型の RDBMS でよく見られる GRANT コマンドと REVOKE コマンドは実装されていません。
次に示す SQL 要素と SQLite 機能は、一部の SQLite 実装ではサポートされていますが、Adobe AIR ではサポートされていません。これらの機能のほとんどは、SQLConnection クラスのメソッドを通じて使用できます。
トランザクション関連の SQL 要素（BEGIN、END、COMMIT、ROLLBACK）この機能は SQLConnection クラスのトラ
ンザクション関連メソッド（SQLConnection.begin()、SQLConnection.commit() および SQLConnection.rollback()）
を通じて使用できます。

ANALYZE この機能は SQLConnection.analyze() メソッドを通じて使用できます。
ATTACH この機能は SQLConnection.attach() メソッドを通じて使用できます。
COPY このステートメントはサポートされていません。
CREATE VIRTUAL TABLE このステートメントはサポートされていません。
DETACH この機能は SQLConnection.detach() メソッドを通じて使用できます。
PRAGMA このステートメントはサポートされていません。
VACUUM この機能は SQLConnection.compact() メソッドを通じて使用できます。
システムテーブルにはアクセスできません システムテーブル（sqlite_master や、「sqlite_」接頭辞の付いたその他のテー
ブルなど）は、SQL ステートメントでは使用できません。ランタイムには、オブジェクト指向的な方法でスキーマデータにアクセスできるスキーマ API が含まれています。詳しくは、「SQLConnection.loadSchema() メソッド」を参照してください。
正規表現関数（MATCH() と REGEX()） これらの関数は、SQL ステートメントでは使用できません。
次の機能は、多くの SQLite の実装と Adobe AIR とで違いがあります。
ステートメントパラメーターのインデックス 多くの実装では、ステートメントパラメーターのインデックスは 1 から始まります。それに対して、Adobe AIR の場合、ステートメントパラメーターのインデックスは 0 から始まります（最初のパラメーターのインデックス値は 0、2 番目のパラメーターのインデックス値は 1 というようになります）。

INTEGER PRIMARY KEY 列定義 多くの実装では、INTEGER PRIMARY KEY として正確に定義されている列だけが、テーブルの実際の主キー列として使用されます。このような実装では、別のデータ型（通常は int などの、INTEGER のシノニム）を使用した場合、その列は内部主キーとして使用されません。ただし、Adobe AIR では、int データ型（および他の INTEGER のシノニム）は、INTEGER と完全に同等とみなされます。したがって、int PRIMARY KEY として定義された列は、テーブルの内部の主キーとして使用されます。詳しくは、「CREATE TABLE」および「列親和型」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1088

ローカルデータベースでの SQL サポート

追加の SQL 機能
次の列親和型は、SQLite ではデフォルトでサポートされていませんが、Adobe AIR ではサポートされています（SQL のす
べてのキーワードと同様に、これらのデータ型の名前では大文字と小文字が区別されません）。

Boolean Boolean クラスに対応します。
Date Date クラスに対応します。
int int クラスに対応します（INTEGER 列親和型に相当）。
Number Number クラスに対応します（REAL 列親和型に相当）。
Object Object クラスまたは AMF3 を使用して直列化および非直列化することが可能なすべてのサブクラスに対応します（これには、カスタムクラスを含む多くのクラスが含まれますが、表示オブジェクトまたは表示オブジェクトをプロパティとして持つオブジェクトは含まれません）。

String String クラスに対応します（TEXT 列親和型に相当）。
XML ActionScript（E4X）XML クラスに対応します。
XMLList ActionScript（E4X）XMLList クラスに対応します。
次のリテラル値は、SQLite ではデフォルトでサポートされていませんが、Adobe AIR ではサポートされています。

true BOOLEAN 型の列に使用するリテラルブール値 true を表します。
false BOOLEAN 型の列に使用するリテラルブール値 false を表します。

データ型のサポート
ほとんどの SQL データベースとは異なり、Adobe AIR の SQL データベースエンジンでは、テーブルの列に特定の型の値を格納する必要はなく、特定の型が強制されることもありません。その代わりに、格納クラスと列親和型という 2 つの概念を使用してデータ型が管理されます。この節では、格納クラスと列親和型について説明し、様々な条件下でデータ型の違いがどのように解決されるのかを示します。

• 1088 ページの「格納クラス」• 1089 ページの「列親和型」• 1091 ページの「データ型と比較演算子」• 1092 ページの「データ型と数値演算子」• 1092 ページの「データ型とソート」• 1092 ページの「データ型とグループ化」• 1092 ページの「データ型と複合 SELECT 文」

格納クラス
格納クラスは、データベースへの値の格納に使用される実際のデータ型を表します。次の格納クラスがデータベースで使用されます。

NULL 値は NULL 値です。
INTEGER 値は符号付き整数です。
REAL 値は浮動小数点数値です。
TEXT 値はテキストストリングです（256 MB に制限されます）。
BLOB 値はバイナリラージオブジェクト（BLOB）です。生のバイナリデータとも呼ばれ、256 MB に制限されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1089

ローカルデータベースでの SQL サポート

SQL 文に埋め込まれたリテラルとしてデータベースに渡される値、またはパラメーターを使用して SQL 文にバインドされた値はすべて、SQL 文が実行される前に格納クラスに割り当てられます。
SQL 文に含まれるリテラルは、一重引用符または二重引用符で囲まれている場合は格納クラス TEXT に、引用符で囲まれておらず、小数点または指数のない数字として指定されている場合は INTEGER に、引用符で囲まれておらず、小数点または指数の付いた数字として指定されている場合は REAL に、値が NULL の場合は NULL に、それぞれ割り当てられます。
リテラルを BLOB に割り当てるには、X'ABCD' 表記を使用します。詳しくは、「式」の「リテラル値」を参照してください。

SQLStatement.parameters 結合配列を使用してパラメーターとして提供された値は、バインドされたネイティブのデータ型に最も近い格納クラスに割り当てられます。例えば、int 値は INTEGER 格納クラスに、Number 値は REAL 格納クラスに、String 値は TEXT 格納クラスに、ByteArray オブジェクトは BLOB 格納クラスに、それぞれ割り当てられます。

列親和型
列の親和型は、その列に格納するデータに推奨される型です。INSERT ステートメントまたは UPDATE ステートメントで値を列に格納すると、ランタイムはその値のデータ型を指定された親和型に変換しようとします。例えば、TEXT を親和型とする列に Date 型の値（ActionScript または JavaScript の Date インスタンス）を挿入すると、Date 型の値は String 表
現に変換されます。これは、データベースに格納する前にオブジェクトの toString() メソッドを呼び出した場合に相当します。値を指定された親和型に変換できない場合はエラーが発生し、処理は行われません。SELECT ステートメントを使用してデータベースから値を取得すると、格納時に別のデータ型から変換されているかどうかに関係なく、親和型に対応するクラスのインスタンスが返されます。

NULL 値を受け入れる列の場合、ActionScript または JavaScript の値 null をパラメーター値として指定し、列に NULLを格納することができます。NULL 格納クラスの値を SELECT ステートメントで取得すると、列の親和型に関係なく、常に ActionScript または JavaScript の null 値が返されます。NULL 値を受け入れる列の場合、null を許容しない Number
や Boolean などの型に値をキャストする前に、その列から取得した値が null かどうか必ず確認されます。
データベースの各列には、次のいずれかの親和型が割り当てられます。

• TEXT（または String）• NUMERIC• INTEGER（または int）
• REAL（または Number）• Boolean• Date• XML• XMLLIST• Object• NONETEXT（または String）
TEXT または String 親和型の列には、記憶クラス NULL、TEXT、または BLOB を使用してすべてのデータが格納されます。数値データを TEXT 親和型の列に挿入すると、データがテキスト形式に変換されてから格納されます。

NUMERICNUMERIC 親和型の列には、記憶クラス NULL、REAL、または INTEGER を使用して値が格納されます。テキストデー
タを NUMERIC 列に挿入すると、データを格納する前に整数または実数への変換が試みられます。変換に成功した場合は、
INTEGER または REAL 記憶クラスを使用して値が格納されます（例えば、値 '10.05' は REAL 記憶クラスに変換されてから格納されます）。変換できない場合は、エラーが発生します。NULL 値の変換は行われません。NUMERIC 列から取得し最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1090

ローカルデータベースでの SQL サポート

た値は、値に適した最も具体的な数値型のインスタンスとして返されます。つまり、値が正の整数または 0 の場合、uint イ
ンスタンスが返され、負の整数の場合、int インスタンスが返されます。また、値に浮動小数点部分（非整数）がある場合、

Number インスタンスが返されます。
INTEGER（または int）
INTEGER 親和型を使用する列は、NUMERIC 親和型の列と同じように動作します。相違点は、浮動小数点部分のない実
数値（Number インスタンスなど）または浮動小数点部分のない実数値に変換できるテキスト値を挿入した場合に、値が整数に変換され、INTEGER 記憶クラスを使用して格納される点のみです。浮動小数点部分のある実数値を格納しようとすると、エラーが発生します。

REAL（または Number）
REAL 親和型または NUMBER 親和型の列も NUMERIC 親和型の列と同じように動作しますが、整数値が強制的に浮動小数点表現に変更される点が異なります。REAL 型の列の値は、データベースから常に Number インスタンスとして返されます。

BooleanBoolean 親和型の列には、true または false の値が格納されます。Boolean 列は、値として ActionScript または
JavaScript の Boolean インスタンスを受け入れます。コードで String 型の値が格納される際には、長さが 0 より大きいスト
リングの場合は true、空のストリングの場合は false と判別されます。コードで数値データが格納される際には、格納される値が 0 以外の場合は true、0 の場合は false と判別されます。SELECT ステートメントを使用して BOOLEAN 値を取得す
ると、その値は Boolean インスタンスとして返されます。NULL 以外の値は INTEGER 記憶クラスを使用して格納され（false の場合は 0、true の場合は 1）、データの取得時に Boolean オブジェクトに変換されます。
Date
Date 親和型の列には、日付と時刻の値が格納されます。Date 列は値として ActionScript または JavaScript の Date イン
スタンスを受け入れるように設計されており、Date 列に String 値を格納しようとすると、ランタイムでユリウス日付に変換されます。変換に失敗するとエラーが発生します。コードで Number、int、または uint の値を格納しようとした場合、日付の検証は行われず、有効なユリウス日付値と見なされます。SELECT ステートメントを使用して Date 値を取得すると自動的に Date インスタンスに変換されます。Date 値は REAL 記憶クラスを使用してユリウス日付値として格納されるので、ソート操作や比較操作も期待どおりに動作します。

XML または XMLList
XML または XMLList 親和型を使用する列には、XML 構造が格納されます。コードで SQLStatement パラメーターを使用
して XML 列にデータを格納すると、ランタイムでは ActionScript の XML() または XMLList() 関数を使用して値の変換と検証が行われます。値を有効な XML に変換できない場合、エラーが発生します。リテラル SQL テキスト値（例：INSERTINTO (col1) VALUES ('Invalid XML (no closing tag)'）を使用してデータを格納すると値の解析や検証は行われず、正しい形式と判断されます。無効な値を格納した場合、その値の取得時に空の XML オブジェクトが返されます。XML および
XMLList のデータは TEXT 記憶クラスまたは NULL 記憶クラスを使用して格納されます。
ObjectObject 親和型の列には、Object クラスインスタンスおよび Object サブクラスインスタンスなど（例：Array インスタンス
やカスタムクラスインスタンスなど）の ActionScript または JavaScript の複合オブジェクトを格納します。Object 列のデータは AMF3 形式で直列化され、BLOB 記憶クラスを使用して格納されます。値の取得時に AMF3 形式から非直列化され、格納されていたクラスのインスタンスとして返されます。表示オブジェクトなど一部の ActionScript クラスは、元のデータ型のインスタンスとして非直列化できません。カスタムクラスインスタンスの場合、格納する前にflash.net.registerClassAlias() メソッドを使用して（または Flex でクラス宣言に [RemoteObject] メタデータを追加して）、
クラスのエイリアスを登録する必要があります。また、このデータを取得する前に、クラスに対して同じエイリアスを登録する必要があります。本質的に非直列化できないクラスであるため、あるいはクラスのエイリアスが未指定または不一致であるために適切に非直列化できないデータは、格納されている元のインスタンスに対応するプロパティと値を持つ匿名オブジェクト（Object クラスインスタンス）として返されます。

NONE
最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1091

ローカルデータベースでの SQL サポート

NONE 親和型の列には、優先される格納クラスはありません。データを挿入する前にデータの変換は行われません。
親和型の決定列の親和型は、CREATE TABLE 文で列に対して宣言された型によって決まります。親和型を決定する際は、次の規則が適用されます（大文字と小文字は区別されません）。

•

列のデータ型に "CHAR"、"CLOB"、"STRING"、"TEXT" のいずれかのストリングが含まれている場合は、

TEXT/String 親和型になります。VARCHAR 型にはストリング "CHAR" が含まれているので、TEXT 親和型が割り当
てられることに注意してください。

•

列のデータ型にストリング "BLOB" が含まれている場合、またはデータ型が指定されていない場合、NONE 親和型になります。

•

列のデータ型にストリング "XMLL" が含まれている場合は、XMLList 親和型になります。

•

列のデータ型がストリング "XML" の場合は、XML 親和型になります。

•

列のデータ型にストリング "OBJE" が含まれている場合は、Object 親和型になります。

•

列のデータ型にストリング "BOOL" が含まれている場合は、Boolean 親和型になります。

•

列のデータ型にストリング "DATE" が含まれている場合は、Date 親和型になります。

•

列のデータ型にストリング "INT" が含まれている場合は（"UINT" など）、INTEGER/int 親和型が列に割り当てられます。

•

列のデータ型に "REAL"、"NUMB"、"FLOA"、"DOUB" のいずれかのストリングが含まれている場合は、

REAL/Number 親和型になります。

•

上記以外の場合は、NUMERIC 親和型になります。

• CREATE TABLE t AS SELECT... ステートメントを使用してテーブルを作成する場合は、どの列にもデータ型が指定されていないので、すべての列が NONE 親和型になります。

データ型と比較演算子
比較操作では、二項比較演算子の =、<、<=、>= および != がサポートされています。また、複数の値のいずれかに一致す
るかどうかをチェックする IN 演算子と、三項比較演算子の BETWEEN も使用できます。これらの演算子について詳しくは、「演算子」を参照してください。
比較の結果は、比較する 2 つの値の格納クラスによって異なります。2 つの値を比較するときは、次の規則が適用されます。

•

格納クラス NULL の値は、他のどの値（格納クラス NULL の別の値も含む）よりも小さいと見なされます。

• INTEGER 値または REAL 値は、どの TEXT 値または BLOB 値よりも小さいと見なされます。INTEGER またはREAL を別の INTEGER または REAL と比較したときは、数値による比較が行われます。
• TEXT 値は BLOB 値より小さいと見なされます。2 つの TEXT 値を比較するときは、二項比較が行われます。
• 2 つの BLOB 値を比較した結果は、常に二項比較を使用して決定されます。
三項演算子 BETWEEN は常に、同等の二項表現として再構成されます。例えば、a BETWEEN b AND c は a >= b AND
a <= c に再構成されます。この処理は、この式を評価するために必要なそれぞれの比較において a に異なる親和型が適用される場合でも変わりません。

a IN (SELECT b ....) という形式の式も、上記の二項比較に関する 3 つの規則に従って（つまり、a = b と同じように）処理されます。例えば、b が列の値で a が式の場合は、比較が行われる前に、b の親和型が a に適用されます。式 a IN (x, y, z) は
a = +x OR a = +y OR a = +z として再構成されます。IN 演算子の右の値（この例では x、y および z の値）は、たとえそれが列の値であっても、式と見なされます。IN 演算子の左の値が列の場合は、その列の親和型が使用されます。左の値が式の場合は、変換は行われません。
また、COLLATE 句を使用して比較方法を変更することもできます。詳しくは、「COLLATE」を参照してください。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1092

ローカルデータベースでの SQL サポート

データ型と数値演算子
サポートされている数値演算子（*、/、%、+ および -）のいずれを使用するときも、式を評価する前に演算子の各オペラン
ドに数値親和型が適用されます。どのオペランドも NUMERIC 記憶クラスに変換できない場合、その式は NULL に評価されます。
連結演算子 || を使用するときは、式が評価される前に各オペランドが TEXT 格納クラスに変換されます。どのオペランドもTEXT 記憶クラスに変換できない場合、その式の結果は NULL になります。このように、値を変換できない状況は次の 2 つの場合に起こります。1 つはオペランドの値が NULL の場合、もう 1 つはオペランドの値が TEXT 以外の記憶クラスを含む

BLOB である場合です。

データ型とソート
ORDER BY 句によって値をソートしたときの並び順は、最初が記憶クラス NULL の値、次が数字順に INTEGER 値とREAL 値、その次がバイナリ順または指定された照合順序（BINARY または NOCASE）に基づく TEXT 値、最後がバイ
ナリ順の BLOB 値です。ソートの前に格納クラスの変換は行われません。

データ型とグループ化
GROUP BY 句を使用して値をグループ化するとき、記憶クラスの異なる値は別のものと見なされます。ただし、
INTEGER 値と REAL 値は、数値的に等しい場合には同じと見なされます。GROUP BY 句の結果として、値に親和型が適用されることはありません。

データ型と複合 SELECT 文
複合 SELECT 演算子の UNION、INTERSECT および EXCEPT は、値どうしを暗黙的に比較します。これらの比較が行われる前に、それぞれの値に親和型が適用される場合があります。可能であれば、複合 SELECT 文の結果セットの 1 つの列で返されるすべての値に同じ親和型が適用されます。適用される親和型は、その位置に（他の種類の式ではなく）列値を持
つ最初の構成 SELECT 文によって返される列の親和型です。特定の複合 SELECT 列について、どの構成 SELECT ステート
メントも列値を返さない場合、その列では親和型を適用せずに値の比較が行われます。

最終更新日 2015/10/14

1093

第 67 章：SQL エラー詳細メッセージ、ID、および引数
SQLError クラスは、Adobe AIR ローカル SQL データベースでの作業中に発生する可能性のある様々なエラーを表します。発生した各例外用に、SQLError インスタンスには、英語のエラーメッセージを含む details プロパティが用意されています。さらに、各エラーメッセージには SQLError オブジェクトの detailID プロパティで使用できる関連する一意の識別子があります。detailID プロパティを使用して、アプリケーションは特定の details エラーメッセージを識別できます。アプリ
ケーションは、エンドユーザーのロケールの言語で、代替テキストをエンドユーザーに提供できます。detailArguments 配列の引数の値は、エラーメッセージ列の適切な場所と置き換えることができます。これは、アプリケーションで特定のロケー
ルのエンドユーザーに、直接エラーの details プロパティエラーメッセージを表示する場合に便利です。
次の表に、detailID 値の一覧と、関連するエラーメッセージの内容を示します。メッセージのプレースホルダーテキストは

detailArguments 値がランタイムによって置き換えられる場所を示しています。この一覧は SQL データベース操作で発生する可能性のあるエラーメッセージをローカライズする際のソースとして使用できます。
SQLErrordetailID
1001
1102
1003
1004
1005
1006
1007

エラー詳細メッセージおよびパラメーター
接続が閉じられました。
この操作を実行するにはデータベースが開いている必要があります。

%s [,|and %s] パラメーター名がパラメーターのプロパティで見つかりましたが、指定された SQL では見つかりませんでした。
パラメーター数が一致しません。SQL では指定された %d が、またパラメータのプロパ
ティでは設定された %d 値が見つかりました。%s [,|and %s] の値が必要です。
自動最適化をオンにできませんでした。

pageSize 値を設定できませんでした。
'%s' という名前（'%s' 型、データベース '%s'）のスキーマオブジェクトが見つかりませ
んでした。

1008
1009
1010
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023

'%s' という名前のスキーマオブジェクトがデータベース '%s' で見つかりませんでした。
'%s' 型（データベース '%s'）のスキーマオブジェクトが見つかりませんでした。
データベース '%s' でスキーマオブジェクトが見つかりませんでした。
パーサーのスタックオーバーフロー
関数 '%s' の引数の数が多すぎます。
'%s' に近い：シンタックスエラー'%s' という名前の別のテーブルまたはインデックスが既に存在します。
SQL では PRAGMA は許可されていません。
書き込みできないディレクトリです。
不明なまたはサポートされていない結合のタイプ：'%s %s %s'
RIGHT および FULL OUTER JOIN は現在サポートされていません。
NATURAL 結合に ON または USING 句がない可能性があります。
同じ結合に ON 句および USING 句の両方を持つことはできません。
列 '%s' を使用して結合できません - どちらのテーブルにも列がありません。
式の一部である SELECT には 1 つの結果しか許可されていません。
テーブル '[%s.]%s' が存在しません。
指定されたテーブルがありません。
結果セットの列数が多すぎます |'%s' の列数が多すぎます。
%s ORDER|GROUP BY 項が範囲外です。1 〜 %d である必要があります。
ORDER BY 句に項が多すぎます。
%s ORDER BY 項が範囲外です。1 〜 %d である必要があります。
%r ORDER BY 項が結果セットのどの列とも一致しません。
ORDER BY 句は '%s' の前ではなく後に来る必要があります。
LIMIT 句は '%s' の前ではなく後に来る必要があります。
'%s' の左および右にある SELECT に、結果列数と同じ列数がありません。
HAVING の前に GROUP BY 句が必要です。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1094

SQL エラー詳細メッセージ、ID、および引数

2024
2025
2026
2027
2028
2030
2032
2033
2034
2035
2036
2037
2043
2044
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2058
2060
2061
2062
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2092
2093
2094

GROUP BY 句では集約関数は使用できません。
集約の DISTINCT の後に式が続く必要があります。
複合 SELECT の項が多すぎます。
ORDER|GROUP BY 句の項が多すぎます。
一時トリガーに修飾名がない可能性があります。
トリガー '%s' は既に存在します。
'%s' ビューに BEFORE|AFTER トリガーを作成することはできません。
テーブル '%s' に INSTEAD OF トリガーを作成することはできません。
トリガー '%s' が存在しません。
再帰トリガーはサポートされていません（'%s'）。
列 %s[.%s[.%s]] が存在しません。
SQL では VACUUM は許可されていません。
テーブル '%s': インデックス処理関数で無効なプランが返されました。
結合に最大 %d のテーブルがあります。
PRIMARY KEY 列を追加できません。
UNIQUE 列を追加できません。
デフォルト値が NULL の NOT NULL 列は追加できません。
デフォルト値が定数でない列は追加できません。
ビューに列を追加することはできません。

SQL では ANALYZE は許可されていません。
無効な名前：'%s'
SQL では ATTACH は許可されていません。
%s '%s' はデータベース '%s' のオブジェクトを参照できません。
'[%s.]%s.%s' へのアクセスは禁止されています。
許可されていません。
ビュー '[%s.]%s' が存在しません。
一時テーブル名は無修飾である必要があります。
テーブル '%s' は既に存在します。
'%s' という名前のインデックスは既に存在します。
列の名前 '%s' が重複しています。
テーブル '%s' に主キーが 2 つ以上あります。
AUTOINCREMENT は INTEGER PRIMARY KEY でのみ許可されています。
照合シーケンス '%s' が存在しません。
ビューでパラメーターが有効ではありません。
ビュー '%s' が循環的に定義されています。
テーブル '%s' が削除されていない可能性があります。
DROP VIEW を使用してビュー '%s' を削除します。
DROP TABLE を使用してテーブル '%s' を削除します。
'%s' の外部キーはテーブル '%s' の 1 列のみを参照している必要があります。
外部キーの列数が参照されているテーブルの列数と一致していません。
外部キー定義の列 '%s' が不明です。
テーブル '%s' がインデックス付けされていない可能性があります。
ビューがインデックス付けされていない可能性があります。
競合した ON CONFLICT 句が指定されています。
インデックス '%s' が存在しません。
UNIQUE または PRIMARY KEY 制約と関連付けられたインデックスは削除できません。
SQL では BEGIN は許可されていません。
SQL では COMMIT は許可されていません。
SQL では ROLLBACK は許可されていません。
一時テーブルを格納するための一時データベースファイルを開くことができません。
再度インデックス付けするオブジェクトを識別できません。
テーブル '%s' は変更されていない可能性があります。
'%s' はビューであるため変更できません。
変数は ?0 〜 ?%d の間である必要があります。
エイリアス処理された集約 '%s' が誤って使用されています。
列の名前 '[%s.[%s.]]%s' があいまいです。
関数 '%s' が存在しません。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1095

SQL エラー詳細メッセージ、ID、および引数

2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2108
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2300
2301
2302
2303
2304
2305
2306
2307
2309
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2501
2508
2510
2511

関数 '%s' の引数の数が間違っています。
CHECK 制約ではサブクエリは禁止されています。
CHECK 制約ではパラメーターは禁止されています。
式のツリーが大きすぎます（最大の深さ %d）。
RAISE() はトリガープログラム内でのみ使用できます。
テーブル '%s' の %d 列に %d 値が設定されていませんでした。
データベーススキーマがロックされています：'%s'
ステートメントが長すぎます。
アクティブなステートメントがあるため照合シーケンスを削除 / 変更できません。
アタッチされているデータベースが多すぎます。最大数は %d です。
トランザクション内ではデータべースの ATTACH はできません。
データベース '%s' は既に使用されています。
アタッチされたデータベースでは、メインデータベースと同じテキストエンコードを使用する必要があります。
メモリ不足です。
データベースを開くことができません。
トランザクション内ではデータベースの DETACH はできません。
データベース '%s' をデタッチできません。
データベース '%s' がロックされています。
データベースの読み取りロックを取得できません。
列 '%s'[,'%s'] が一意ではありません。
不正なデータベーススキーマ
サポートされていないファイル形式
認識できないトークン：'%s'
テキスト値を数値に変換できませんでした。
ストリング値を日付に変換できませんでした。
データが失われることなく、浮動小数値を整数に変換できませんでした。
トランザクションをロールバックできません。SQL ステートメントが実行中です。
トランザクションをコミットできません。SQL ステートメントが実行中です。
データベーステーブルがロックされています：'%s'
読み取り専用テーブル
ストリングまたは BLOB が大きすぎます。
インデックス付けされた列を書き込み用に開くことができません。
型 %s の値を開くことができません。
rowid %s が存在しません。
内部的な使用のために予約されたオブジェクト名：'%s'
ビュー '%s' を変更することはできません。
列 '%s' のデフォルト値が定数ではありません。
関数 '%s' の使用が許可されていません。
集約関数 '%s' が誤って使用されています。
集約 '%s' が誤って使用されています。
データベース '%s' が存在しません。
テーブル '%s' に '%s' という名前の列がありません。
モジュール '%s' が存在しません。
セーブポイント '%s' が存在しません。
ロールバックできません。アクティブなトランザクションがありません。
コミットできません。アクティブなトランザクションがありません。

最終更新日 2015/10/14

1096

第 68 章：Adobe Graphics Assembly

Language（AGAL）
AGAL は、頂点およびフラグメントをレンダリングするプログラムを定義するためのシェーダー言語です。AGAL プログ
ラムは、このドキュメントで説明するバイナリのバイトコード形式で、レンダリングコンテキストにアップロードする必要があります。

AGAL のバイトコード形式
AGAL のバイトコードは、Endian.LITTLE_ENDIAN 形式を使用する必要があります。
バイトコードのヘッダー

AGAL バイトコードは、7 バイトのヘッダーで始める必要があります。
A0 01000000 A1 00 -- for a vertex program
A0 01000000 A1 01 -- for a fragment program
オフセット（バイト）

サイズ（バイト） 名前

説明

0

1

magic

必ず 0xa0

1

4

バージョン

必ず 1

5

1

シェーダータイプ

必ず 0xa1

ID
6

シェーダータイプ

1

頂点プログラムの場合は 0、フラグメントプログラムの場合は

1

トークン
ヘッダーの直後に任意数のトークンが続きます。すべてのトークンは 192 ビット（24 バイト）のサイズであり、必ず次の形
式に従います。

[opcode][destination][source1][source2 or sampler]
オペコードによっては、これらのフィールドすべてを使用しない場合もあります。未使用のフィールドには 0 を設定する必要があります。
オペレーションコード

[opcode] フィールドは 32 ビットのサイズであり、次のいずれかの値を設定できます。
名前

オペコー
ド

処理

説明

mov

0x00

移動

同じ成分ごとに、source1 から destination にデータを移動します

add

0x01

追加

destination = source1 + source2、同じ成分ごと

sub

0x02

減算

destination = source1 - source2、同じ成分ごと

mul

0x03

乗算

destination = source1 * source2、同じ成分ごと

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1097

Adobe Graphics Assembly Language（AGAL）

名前

オペコー
ド

処理

説明

div

0x04

除算

destination = source1 / source2、同じ成分ごと

rcp

0x05

逆数

destination = 1/source1、同じ成分ごと

min

0x06

最小

destination = minimum(source1,source2)、同じ成分ごと

max

0x07

最大

destination = maximum(source1,source2)、同じ成分ごと

frc

0x08

少数

destination = source1 - (float)floor(source1)、同じ成分ごと

sqt

0x09

平方根

destination = sqrt(source1)、同じ成分ごと

rsq

0x0a

逆数平方根

destination = 1/sqrt(source1)、同じ成分ごと

pow

0x0b

累乗

destination = pow(source1,source2)、同じ成分ごと

log

0x0c

自然対数

destination = log_2(source1)、同じ成分ごと

exp

0x0d

指数

destination = 2^source1、同じ成分ごと

nrm

0x0e

正規化

destination = normalize(source1)、同じ成分ごと（3 成分の結果だけを生成、destination は .xyz 以下にマスクすることが必要）

sin

0x0f

正弦波

destination = sin(source1)、同じ成分ごと

cos

0x10

余弦波

destination = cos(source1)、同じ成分ごと

crs

0x11

クロス積

destination.x = source1.y * source2.z - source1.z * source2.y
destination.y = source1.z * source2.x - source1.x * source2.z
destination.z = source1.x * source2.y - source1.y * source2.x（3 つの成分の結果のみを生成、destination には .xyz またはそれより小さいマスクを適用することが必要）

dp3

0x12

ドット積

destination = source1.x*source2.x + source1.y*source2.y +source1.z*source2.z

dp4

0x13

ドット積

destination = source1.x*source2.x + source1.y*source2.y +source1.z*source2.z + source1.w*source2.w

abs

0x14

絶対

destination = abs(source1)、同じ成分ごと

neg

0x15

ネゲート

destination = -source1、同じ成分ごと

sat

0x16

飽和

destination = maximum(minimum(source1,1),0)、同じ成分ごと

m33

0x17

マトリックス乗算

destination.x = (source1.x * source2[0].x) + (source1.y *source2[0].y) + (source1.z * source2[0].z)

3x3

destination.y = (source1.x * source2[1].x) + (source1.y *source2[1].y) + (source1.z * source2[1].z)
destination.z = (source1.x * source2[2].x) + (source1.y *source2[2].y) + (source1.z * source2[2].z)（3 つの成分の結果のみを生成、destination には .xyz またはそれより小さいマスクを適用することが必要）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1098

Adobe Graphics Assembly Language（AGAL）

名前

オペコー
ド

m44

0x18

処理

説明

マトリックス乗算

destination.x = (source1.x * source2[0].x) + (source1.y *source2[0].y) + (source1.z * source2[0].z) + (source1.w *source2[0].w)

4x4

destination.y = (source1.x * source2[1].x) + (source1.y *source2[1].y) + (source1.z * source2[1].z) + (source1.w *source2[1].w)
destination.z = (source1.x * source2[2].x) + (source1.y *source2[2].y) + (source1.z * source2[2].z) + (source1.w *source2[2].w)
destination.w = (source1.x * source2[3].x) + (source1.y *source2[3].y) + (source1.z * source2[3].z) + (source1.w *source2[3].w)
m34

0x19

マトリックス乗算

3x4

destination.x = (source1.x * source2[0].x) + (source1.y *source2[0].y) + (source1.z * source2[0].z) + (source1.w *source2[0].w)
destination.y = (source1.x * source2[1].x) + (source1.y *source2[1].y) + (source1.z * source2[1].z) + (source1.w *source2[1].w)
destination.z = (source1.x * source2[2].x) + (source1.y *source2[2].y) + (source1.z * source2[2].z) + (source1.w *source2[2].w)（3 つの成分の結果のみを生成、destination には .xyz またはそれより小さいマスクを適用することが必要）

kil

0x27

停止／破棄（フラグメントシェーダーのみ）source のスカラー成分の 1 つが 0 未満の場合、フラグメントは破棄され、フレームバッファーには描画されません（destination のレジスタは。
すべて 0 に設定する必要があります）

tex

0x28

テクスチャサンプル（フラグメント
シェーダーのみ）

destination は、座標 source1 でテクスチャ source2 から読み込む値と等しくなります。この場合、source2 は sampler 形式で指定する必要が
あります。

sge

0x29

以上を設定

destination = source1 >= source2 ? 1 : 0、同じ成分ごと

slt

0x2a

未満を設定

destination = source1 < source2 ? 1 : 0、同じ成分ごと

seq

0x2c

等しいを設定destination = source1 == source2 ? 1 : 0、同じ成分ごと

sne

0x2d

等しくないを設定

destination = source1 != source2 ? 1 : 0、同じ成分ごと

AGAL2 には次のオペコードが導入されています。
名前

オペコー
ド

処理

説明

ddx

0x1a

X における偏微分source1 の X における偏微分を destination に読み込みます。

ddy

0x1b

Y における偏微分source1 の Y における偏微分を destination に読み込みます。

ife

0x1c

等しい

source1 が source2 に等しい場合にジャンプします。

ine

0x1d

等しくない

source1 が source2 に等しくない場合にジャンプします。

ifg

0x1e

以上

source1 が source2 以上の場合にジャンプします。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1099

Adobe Graphics Assembly Language（AGAL）

名前

オペコー
ド

処理

説明

ifl

0x1f

未満

source1 が source2 未満の場合にジャンプします。

els

0x20

else

else ブロック

eif

0x21

Endif

if ブロックまたは else ブロックを終了します。

destination フィールドのフォーマット
[destination] フィールドのサイズは 32 ビットです。
31.............................0----TTTT----MMMMNNNNNNNNNNNNNNNN

T = レジスタタイプ（4 ビット）M = 書き込みマスク（4 ビット）N = レジスタ番号（16 ビット）- = 未定義、必ず 0source フィールドのフォーマット
[source] フィールドのサイズは 64 ビットです。
63.............................................................0
D-------------QQ----IIII----TTTTSSSSSSSSOOOOOOOONNNNNNNNNNNNNNNN

D = 直接は 0 ／間接は 1、直接の場合 Q と I は無視（1 ビット）
Q = インデックスレジスタのコンポーネント選択（2 ビット）I = インデックスレジスタのタイプ（4 ビット）T = レジスタタイプ（4 ビット）S = スウィズル（8 ビット、コンポーネントあたり 2 ビット）O = 間接オフセット（8 ビット）N = レジスタ番号（16 ビット）- = 未定義、必ず 0
サンプラーフィールドのフォーマット

tex オペコードの 2 番目の source フィールドは、サイズ 64 ビットの [sampler] フォーマットでなければなりません。
63.............................................................0
FFFFMMMMWWWWSSSSDDDD--------TTTT--------BBBBBBBBNNNNNNNNNNNNNNNN

N = サンプラーレジスタ番号（16 ビット）B = テクスチャの level-of-detail（LOD）バイアス、符号付き整数、スケール 8。使用される浮動小数点値は b/8.0（8 ビット）

T = レジスタタイプ、必ず 5、サンプラー（4 ビット）F = フィルター（0 = 最も近いもの、1 = リニア）（4 ビット）M = ミップマップ（0 = 無効、1 = 最も近いもの、2 = リニア）
W = 折り返し（0 = クランプ、1 = 繰り返し）
S = 特殊フラグビット（必ず 0）

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1100

Adobe Graphics Assembly Language（AGAL）

D = 次元（0 = 2 次元、1 = 3 次元）プログラムレジスタ
使用するレジスタの数は、使用する Context3D プロファイルによって異なります。レジスタの数とその使用方法を次の表に示します。
名前

値

AGAL

AGAL2
AGAL3
使用方法
フラグメン
トプログラ
ムあたりの
数

フラグメン
トプログラ
ムあたりの
数

頂点プログ
ラムあたり
の数

頂点プログ
ラムあたり
の数
フラグメン
トプログラ
ムあたりの
数
頂点プログ
ラムあたり
の数
コンテキス
ト 3D プロ

標準以下

ファイルサ
ポート
標準
標準を拡張

SWF バー

25 未満

ジョン

25
28 以上
属性

0

N/A

8

N/A
8
N/A
16
頂点シェー
ダー入力。

Context3
D.setVertexBufferAt() を使用し
て、指定さ
れた頂点
バッファー
から読み取
ります。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1101

Adobe Graphics Assembly Language（AGAL）

名前

値

AGAL

1

28

128

2

8

8

3

1

1

AGAL2
AGAL3
使用方法
定数

64
250
200
250
シェーダー
入力。

Context3
D.setProgr
amConstants() 関数
ファミリー
を使用して
設定しま
す。
一時

26
26
26
26
計算のため
の一時レジ
スタ。プロ
グラム外か
らはアクセ
スできませ
ん。
出力

1
1
1
1
シェーダー
出力。頂点
プログラム
では、出力
はクリップ
空間の位
置。フラグ
メントプロ
グラムで
は、出力は
カラー。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1102

Adobe Graphics Assembly Language（AGAL）

名前

値

AGAL

4

8

AGAL2
AGAL3
使用方法
可変

8

10
10
10
10
頂点シェー
ダーとフラ
グメント
シェーダー
の間で補間
データを転
送します。
頂点プログ
ラムの変化
するレジス
タが、フラ
グメントプ
ログラムへ
の入力とし
て適用され
ます。値
は、三角形
の頂点から
の距離に基
づいて補間
されます。

最終更新日 2015/10/14

ACTIONSCRIPT 3.0 開発ガイド

1103

Adobe Graphics Assembly Language（AGAL）

名前

値

AGAL

5

8

N/A

6

N/A

N/A

AGAL2
AGAL3
使用方法
サンプラー

16
N/A
16
N/A
フラグメン
トシェー
ダー入力。

Context3
D.setText
ureAt() を
使用して、
指定された
テクスチャ
から読み取
ります。
フラグメン
トレジスタ

1
N/A
1
N/A
書き込み専
用であり、
頂点シェー
ダーに書き
込まれた z
値（深度
値）を書き
直すために
使用しま
す。
トークン

200

1024
2048

最新の AGAL Mini Assembler は このページで入手できます。

最終更新日 2015/10/14