canvas 要素

4.11.4 canvas 要素

カテゴリー:
フロー・コンテント
フレージング・コンテント
エンベッディッド・コンテント
パルパブル・コンテント
この要素を使うことができるコンテキスト:
エンベッディッド・コンテントが期待される場所
コンテントモデル:
トランスペアレント
コンテント属性:
グローバル属性
width - 横幅の寸法
height - 縦幅の寸法
text/html におけるタグの省略:
どちらのタグも省略できません。
指定可能な ARIA role 属性 の値:
あらゆるロールの値
指定可能な ARIA ステートとプロパティ属性:
グローバル aria-* 属性
許可ロールに該当する aria-* 属性
width
height
DOM インタフェース:
typedef (CanvasRenderingContext2D or WebGLRenderingContext) RenderingContext;

interface HTMLCanvasElement : HTMLElement {
           attribute unsigned long width;
           attribute unsigned long height;

  RenderingContext? getContext(DOMString contextId, any... arguments);

  DOMString toDataURL(optional DOMString type, any... arguments);
  void toBlob(FileCallback? _callback, optional DOMString type, any... arguments);
};

canvas 要素は、スクリプトに解像度依存のビットマップキャンバスを提供し、グラフ、ゲームグラフィックス、アートなど、ビジュアルイメージをその場でレンダリングするために使うことができます。

ウェブ制作者は、もっと適切な要素が利用できるなら、そのドキュメントで canvas 要素を使うべきではありません。例えば、ページの見出しをレンダリングするために canvas 要素を使うのは不適切です。もし、その見出しをグラフィックに重点をおいた表現にしたいなら、適切な要素(通常は h1)を使ってマークアップし、それから、CSS や XBL のようなサポートテクノロジーを使ってスタイリングするべきです。

ウェブ制作者が canvas 要素を使うときは、コンテンツも提供しなければいけません。そのコンテンツとは、それがユーザーに提供されるとき、canvas のビットマップと同じ働きや目的を本質的に伝達するものです。このコンテンツは、canvas 要素のコンテンツとして配置することができます。canvas 要素のコンテンツは、もしあれば、その要素のフォールバックコンテントとなります。


インタラクティブなビジュアルメディアでは、canvas 要素に対してスクリプティングが有効であり、かつ、canvas 要素のサポートが有効になっているのであれば、その canvas 要素は、動的に生成されたイメージから構成されるエンベッディッド・コンテント表します。

非インタラクティブで静的なビジュアルメディアでは、canvas 要素がレンダリング・コンテキストと以前に関連付けられていたなら(例えば、もしページがインタラクティブなビジュアルメディアで見られ、今、印刷されているなら、または、ページレイアウト処理の途中で実行していたいくつかのスクリプトが、その要素上に描画したなら)、その canvas 要素はその要素の現在のビットマップとサイズを持ったエンベッディッド・コンテント表します。そうでなければ、この要素は代わりにフォールバック・コンテントを表します。

非ビジュアルメディア、そして、canvas 要素に対してスクリプティングが無効となっている、または、canvas 要素のサポートが無効になっているビジュアルメディアでは、canvas 要素は代わりにフォールバック・コンテント表します。

canvas 要素がエンベッディッド・コンテントを表すときでも、ユーザーはその canvas 要素の子孫(フォールバック・コンテントの中)にフォーカスすることができます。要素がフォーカスされたとき、それは、キーボード・インタラクション・イベントのターゲットになります(その要素そのものは見ることすらできませんが)。これによって、ウェブ制作者は、インタラクティブな canvas を、キーボードからアクセスできるようにすることができます。ウェブ制作者は、フォールバック・コンテントにあるフォーカス可能な要素に、インタラクティブな領域を 1 対 1 に対応付けするべきです。(フォーカスは、マウス・インタラクション・イベントには何も影響を与えません。) [DOMEVENTS]


canvas 要素は、その要素のビットマップのサイズを制御する 2 つの属性を持ちます: widthheight です。これらの属性は、指定するとき、妥当な非負整数となる値でなければいけません。それらの数値を取得するために、非負整数パース規則を使わなければいけません。属性が指定されなかった、または、その値をパースしたらエラーになったら、代わりにデフォルト値を使わなければいけません。width 属性のデフォルトは 300 で、height 属性のデフォルトは 150 です。

canvas 要素の本来の寸法は、それがエンベッディッド・コンテント表すとき、その要素のビットマップの寸法に同じになります。

canvas 要素は、スタイルシートで任意のサイズにすることができます。そのとき、そのビットマップは 'object-fit' CSS プロパティに従います。 [CSSIMAGES]


canvas 要素のビットマップは、HTML Canvas 2D Context 仕様 [CANVAS2D] で説明されているようなレンダリング・コンテキストのビットマップと同様に、origin-clean フラグを持ちます。これは、true か false にセットできます。canvas 要素が生成される初期段階では、そのビットマップの origin-clean フラグは true にセットされなければいけません。

canvas のビットマップは、後述の CanvasRenderingContext2D のセクションで説明されている通り、ヒットリージョンのリストも持ちます。

canvas 要素は、それにバインドされたレンダリングコンテキストを持つことができます。当初それにはレンダリングコンテキストはバインドされません。それがレンダリングコンテキストを持つかどうか、そして、それがどんな種類のレンダリングコンテキストなのかの経過を追うために、canvas 要素は canvas context mode も持ちます。これは当初は none ですが、本仕様で定義されているアルゴリズムによって、direct-2d, direct-webgl, indirect, proxied のいずれかに変更することができます。

その canvas context modenone のとき、canvas 要素はレンダリングコンテキストを持たず、そのビットマップは、完全に透明な黒で、その固有の横幅はその要素の width 属性の数値に等しく、その固有の縦幅はその要素の height 属性の数値に等しくなければいけません。これらの値は CSS ピクセルで解釈され、それら属性がセットされたり変更されたり削除されたりしたら、アップデートされなければいけません。

canvas 要素がエンベッディッド・コンテントを表すとき、それはペイントソースを提供します。その横幅は該当の要素の固有の横幅となり、その縦幅は該当の要素の固有の縦幅となり、その見え方は該当の要素のビットマップとなります。

widthheight コンテント属性がセット、削除、変更されたり、すでにそれらにセットされている値にもう一度セットされるとき、その canvas context modedirect-2d なら、ユーザーエージェントは、widthheight 属性の数値に、ビットマップ寸法をセットしなければいけません。

widthheight IDL 属性は、それぞれ同じ名前のコンテント属性を反映しなければいけません。デフォルトも同じです。

canvas 要素で使われるビットマップは、任意のピクセル密度を持つことができます。通常は、その密度はユーザーのスクリーンの密度に一致するでしょう。


context = canvas . getContext(contextId [, ... ])

canvas に描画するための API にアクセスできるようにするオブジェクトを返します。第 1 引数には、"2d" または "webgl" のいずれかで、必要な API を指定します。後続の引数は、その API によって扱われます。

定義済みコンテキストのリストは、WHATWG Wiki CanvasContexts ページに掲載されています。 [WHATWGWIKI]

コンテキストの例としては、"2d" [CANVAS2D] と "webgl" [WEBGL] コンテキストがあります。

指定のコンテキスト ID が未サポート、または、その canvas がすでに別の(互換性がない)コンテキストタイプで初期化されたのであれば(例えば、"webgl" コンテキストを取得した後に、"2d" コンテキストを取得しようとした場合)、null を返します。

レンダリングコンテキストはそれぞれ context bitmap mode を持ちます。これは fixed, unbound, bound のいずれかひとつです。初期ではレンダリングコンテキストは unbound モードでなければいけません。


canvas 要素の getContext(contextId, arguments...) メソッドは、呼び出されたら、次の表のセルにある手順を実行しなければいけません。列見出しには canvas 要素の canvas context mode が、行見出しにはこのメソッドの第 1 引数が記述されています。

none direct-2d direct-webgl indirect proxied
"2d" canvas 要素の context modedirect-2d にセットし、HTML Canvas 2D Context 仕様 [CANVAS2D] で定義された CanvasRenderingContext2D オブジェクトを取得し、その取得した CanvasRenderingContext2D オブジェクトの context bitmap modefixed にセットし、その CanvasRenderingContext2D オブジェクトを返します。 このメソッドが同じ引数で最後に呼び出された時に返したのと同じオブジェクトを返します。 null を返します。 InvalidStateError 例外を投げます。 InvalidStateError例外を投げます
"webgl", ユーザーエージェントの設定で WebGL 機能が使える状態の場合 WebGL 仕様の Context Creation のセクションの指示に従って、WebGLRenderingContext または null が得られます。返ってきた値が null なら、null を返し、これらの手順を中止します。そうでなければ、canvas 要素の context modedirect-webgl にセットし、新たな WebGLRenderingContext オブジェクトの context bitmap modefixed にセットし、その WebGLRenderingContext オブジェクトを返します。‡ [WEBGL] null を返します このメソッドが同じ引数で最後に呼び出された時に返したのと同じオブジェクトを返します。 InvalidStateError例外を投げます。 InvalidStateError例外を投げます。
ベンダー独自の拡張* その拡張に定義されたとおりに振る舞います。 その拡張に定義されたとおりに振る舞います。 その拡張に定義されたとおりに振る舞います。 InvalidStateError例外を投げます。 InvalidStateError例外を投げます。
未サポートの値† null を返します null を返します null を返します InvalidStateError例外を投げます。 InvalidStateError例外を投げます。

* ベンダーは、たとえば moz-3d のように vendorname-context の構文を使って実験的なコンテキストを定義することができます。

† たとえば、"webgl" という値を指定すると、ユーザーエージェントがグラフィクスハードウェアの能力を消耗させてしまったり、ソフトウェアによるフォールバックを実装していない場合。

‡ このメソッドに 第 2 引数 (後続の引数も含む) があれば、それは、この場合除いて、無視されます。詳細は WebGL 仕様を参照のこと。

url = canvas . toDataURL( [ type, ... ] )

canvas のイメージの data: URL を返します。

第 1 引数が与えられたら、それは、返されるべきイメージのタイプを制御します(PNG や JPEG など)。デフォルトは image/png です。このタイプは、指定されたタイプがサポートされなかった場合にも採用されます。他の引数は、タイプに特化したものとなり、下表の通り、イメージ生成方法を制御します。

"image/png" 以外のタイプを使おうとするとき、ウェブ制作者は、そのイメージが、文字列 "data:image/png," か "data:image/png;" で始まる文字列を返すかどうかをチェックすることで、リクエストしたフォーマットで本当に返されたかどうかをチェックすることができます。もしそうなら、そのイメージは PNG です。そして、ゆえに、リクエストされたタイプはサポートされていなかったということになります。(これには例外がひとつあります。それは canvas が高さも幅も持たない場合です。この場合、"data:," だけという結果になります。)

toDataURL() メソッドは、96dpi の解像度のデータを返します。

canvas . toBlob(callback [, type, ... ])

canvas のイメージを含んだファイルを表す Blob オブジェクトを生成し、そのオブジェクトへのハンドルを付けて callback を呼び出します。

第 2 引数が指定されたら、それは、返されるべきイメージのタイプを制御します(例えば PNG や JPEG)。デフォルトは image/png です。このタイプは、指定されたタイプがサポートされていなかったときにも使われます。他の引数は、タイプに特化したもので、下表の通り、イメージ生成方法を制御します。

toBlob() メソッドは、96dpi の解像度のデータを提供します。

toDataURL()メソッドは次の手順を実行しなければいけません:

  1. canvas 要素のビットマップの origin-clean フラグが false にセットされているなら、SecurityError 例外を投げ、これらの手順を中止します。

  2. canvas 要素のビットマップにピクセルがなければ(つまり、縦または横のいずれかの寸法が 0)、文字列 "data:," を返し、これらの手順を中止します。(これは最短の data: URL で、text/plain リソースでは空文字列を表します)

  3. file を、このメソッドの引数(もしあれば)を arguments として使って、canvas 要素のビットマップをファイルとしたシリアライゼーションとします。

  4. file を表す data: URL を返します。 [RFC2397]

toBlob()メソッドは次の手順を実行しなければいけません:

  1. canvas 要素のビットマップの origin-clean フラグが false にセットされているなら、SecurityError 例外を投げ、これらの手順を中止します。

  2. callback を第 1 引数とします。

  3. arguments を、第 2 引数と、後続の引数があれば、それも加えたものとします。

  4. canvas 要素のビットマップにピクセルがなければ(つまり、縦または横のいずれかの寸法が 0)、result を null とします。

    そうでなければ、arguments を使って、result を、canvas 要素のビットマップをファイルとしたシリアライゼーションを表す Blob オブジェクトとします。 [FILEAPI]

  5. 返します。しかし、非同期にこれらの手順を続けます。

  6. callback が null なら、これらの手順を中止します。

  7. result を引数にして、FileCallback callback を呼び出すタスクをキューイングします。このタスクに対するタスクソースは、canvas blob シリアライゼーション・タスクソースです。

4.11.4.1 色空間と色補整

canvas API の色補正は 2 箇所だけで実行されなければいけません:まず、canvas 自身が持つガンマ補整と色空間情報を使って ビットマップ上にイメージをレンダリングするときです。これは、イメージをそのビットマップで使われている色空間に変換するためです(例えば、HTMLImageElement オブジェクトを使って、2D コンテキストの drawImage() メソッドを使うなどして)。もうひとつは、出力デバイスに実際の canvas ビットマップをレンダリングするときです。

ゆえに、2D コンテキストでは、canvas 上に図形を描くために使われる色は、getImageDataHD() メソッドを通して得られた色に正確に一致します。

toDataURL() メソッドは、それが返すリソースに色空間情報を含めてはいけません。出力フォーマットがそれを許す場合、toDataURL() によって生成されたリソース内のピクセルの色は、getImageData() メソッドによって返されるピクセルに一致しなければいけません。

CSS をサポートするユーザーエージェントでは、canvas 要素に使われる色空間は、その要素に対して CSS で扱う色を処理するために使われる色空間に一致しなければいけません。

イメージのガンマ補整と色空間情報は、img 要素を使って直接的にレンダリングされるイメージが、canvas 要素上に描画されるものと同じ色を使う、といった方法で扱われなければいけません。さらに、色補正情報を持たないイメージのレンダリング(toDataURL() メソッドによって返される情報など)は、色補正なしにレンダリングされなければいけません。

4.11.4.2 ビットマップからファイルへのシリアライゼーション

ユーザーエージェントは、ファイルとしてイメージのシリアライゼーションを生成することになったとき、オプションで指定された arguments を使いますが、arguments の最初の値によって指定されたフォーマットでイメージファイルを生成しなければいけません。arguments がなければ PNG フォーマットとなります。 [PNG]

ビットマップが座標空間単位につき 1 ピクセルになるなら、そのイメージファイルは、そのビットマップと同じピクセルデータ (妥当なら圧縮前) を持たなければいけません。そして、使われるファイル形式が解像度メタデータのエンコードをサポートしているなら、そのビットマップの解像度 (座標空間単位ごとのデバイスピクセルが、CSS ピクセルごとのイメージピクセルとして解釈される) も与えられなければいけません。

そうでなければ、そのイメージファイルのピクセルデータは、座標空間単位ごとに 1 イメージピクセルにスケールされたビットマップのピクセルデータでなければいけません。そして、もし使われるファイル形式が解像度メタデータのエンコーディングをサポートするなら、その解像度は 96dpi (CSS ピクセルごとに 1 イメージピクセル) として与えられなければいけません。

arguments が空でなければ、その最初の値は、採用フォーマットを与える MIME タイプとして解釈されなければいけません。そのタイプにパラメータがあれば、それはサポートされないものとして扱われなければいけません。

例えば、値が "image/png" なら PNG イメージを生成することを意味するでしょうし、値が "image/jpeg" なら JPEG イメージを生成することを意味するでしょう。そして、値が "image/svg+xml" なら SVG イメージを生成することを意味するでしょう(ただし、この場合、ユーザーエージェントはどうやってビットマップが生成されたかを追跡しなければいけませんので、これは想定されにくい機能かもしれませんが、もしできたら、それはすごいことです)。

ユーザーエージェントは PNG ("image/png")をサポートしなければいけません。ユーザーエージェントは他のタイプをサポートすることができます。もしユーザーエージェントがリクエストされたタイプをサポートしていないのであれば、PNG フォーマットを使ってファイルを生成しなければいけません。 [PNG]

ユーザーエージェントは、指定されたタイプを小文字に変換してから、そのタイプをサポートしているかどうかを確定しなければいけません。

アルファチャネルをサポートしないイメージタイプに対してシリアル化されるイメージは、source-over オペレーターを使って無地の黒の背景の上に合成されたビットマップイメージでなければいけません。

arguments の第 1 引数が次表の最初のカラムのタイプの 1 つに一致するタイプであり、かつ、ユーザーエージェントがそのタイプをサポートするなら、それ以降に引数は、もしあれば、その行の 2 番目のセルで説明された通りに扱われなければいけません。

シリアライゼーションメソッドの引数
タイプ 他の引数 リファレンス
image/jpeg 第 2 引数は、0.0 以上 1.0 以下の範囲の数値なら、品質レベルとして扱われなければいけません。もし数値でなかったり、該当の範囲外なら、ユーザーエージェントは、その引数が省略されたかのように、デフォルト値を使わなければいけません。 [JPEG]

これらの手順の目的においては、引数は、それが Web IDL 仕様で any というタイプの引数を扱う規則によって IDL double 値に変換されるなら、数値であると判断されます。 [WEBIDL]

他の引数は無視されなければならず、ユーザーエージェントが例外を発出するようなことがあってはいけません。本仕様の将来のバージョンでは、ウェブ制作者が、圧縮設定やイメージのメタデータなど、より入念に制御できるよう、これらのメソッドに引き渡せるパラメータが他にも定義されるかもしれないでしょう。

4.11.4.3 canvas 要素のセキュリティー

このセクションは非規定です。

あるオリジンのスクリプトが、他のオリジン(同一でないオリジン)のイメージの情報にアクセス(例:ピクセルを読み取る)することができてしまうと、情報漏洩が発生する可能性が出てきてしまいます。

これを低減するために、canvas 要素で使われるビットマップは、それらが origin-clean かどうかを表すフラグを持つよう定義されています。すべてのビットマップは origin-clean を true にセットした状態で始まります。このフラグは、クロスオリジンのイメージやフォントが使われたときに false にセットされます。

toDataURL(), toBlob(), getImageData(), getImageDataHD() メソッドはこのフラグをチェックし、クロスオリジンデータを漏洩するのではなく、SecurityError 例外を投げるでしょう。

このフラグは、ある状況でリセットされることがあります。たとえば、CanvasRenderingContext2D が新たな canvas にバインドされたとき、ビットマップが生成され、そのフラグはリセットされます。


※ 原文:http://www.w3.org/TR/2014/REC-html5-20141028/scripting-1.html#the-canvas-element

canvas 要素の 2D コンテキストの詳細につきましては、当サイトの「Canvas」コーナーをご覧ください。