サイト内検索

toDataURL() メソッド

構文

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

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

第 1 引数を指定すると、それは、返されるイメージのタイプ (例えば、PNG や JPEG) を制御します。デフォルトは image/png です。このタイプは、指定のタイプがサポートされていない場合も適用されます。残りの引数はタイプ固有のものとなり、下表の通り、イメージが生成される方法を制御することになります。

仕様

toDataURL() メソッドは、引数がない場合は、PNG ファイルとしての画像表現を含んだ data: URI を返さなければいけません。[PNG]

canvas にピクセルがなければ(つまり、幅も高さも 0 なら)、このメソッドは文字列 "data:," を返さなければいけません。(これは、最短の data: URL で、text/plain リソースでは空文字列を表します。)

toDataURL(type)メソッドは、1 個以上の引数を伴って呼び出されると、type で指定されたフォーマットのイメージ表現を含んだ data: URL を返さなければいけません。指定可能な値は、パラメータなしの MIME タイプです。例えば、image/png, image/jpeg です。実装が canvas から SVG イメージを確実にレンダリングできる十分な情報を実際に保持しているなら、image/svg+xml も使えるかもしれません。

アルファ・チャネルをサポートできないイメージ・タイプの場合は、source-over 演算子を使って、背景を無地の黒の上に合成されなければいけません。そして、それが、data: URL を生成するために使われることになります。

image/png のサポートは必須です。ユーザーエージェントは他のタイプをサポートすることができます。ユーザーエージェントがリクエストされたタイプをサポートしていない場合、PNG フォーマットを使ってイメージを返さなければいけません。

ユーザーエージェントは、指定のタイプを小文字に変換してから、指定のタイプをサポートしているかを確認し、data: URL を生成しなければいけません。

image/png 以外のタイプを使おうとするとき、本当にリクエストしたフォーマットでイメージが返ってくるのかをチェックすることができます。返ってきた値が、正確に "data:image/png," または "data:image/png;" に前方一致するかどうかを見るのです。もし一致しれいれば、そのイメージは PNG ということになります。つまり、この場合は、リクエストしたタイプはサポートされていないということになります。(これにはひとつだけ例外があります。もし canvas の幅または高さが 0 なら、ただ単に "data:," という結果になります。)

もし、このメソッドに、下表の最初のカラムにあるタイプの一つに対応するタイプが第 1 引数に指定され、ユーザーエージェントがそのタイプをサポートしているなら、それ以降の引数があれば、それらは下表の該当の行の 2 番目のセルに記載されているとおりに扱われます。

タイプ 残りの引数
image/jpeg 第 2 引数が、0.0 ~ 1.0 の数字なら、それは品質レベルとして扱われます。もしそれが数字でなかったり、該当の範囲外であれば、ユーザーエージェントは、その引数が省略されたとしてデフォルト値を適用しなければいけません。

これらのルールの目的のため、引数は、Web IDL 仕様のタイプ any の引数のハンドリングに対するルールによって IDL double 型の値に変換されるなら、数値であると見なされます。 [WEBIDL]

上記以外の残りの引数は無視され、ユーザーエージェントは例外を発してはいけません。将来的には、この仕様で、toDataURL()に引き渡すパラメータを別に定義し、圧縮設定やイメージのメタデータなど、もっと入念に制御できるようになるかもしれません。


原文:http://www.w3.org/TR/2010/WD-html5-20100624/the-canvas-element.html#dom-canvas-todataurl

サンプル

toDataURLメソッドのサンプル

サンプルでは、まず上図のとおり、canvas 上に赤色の矩形を描画しました。そして、toDataURL() を使って、canvas に描かれた状態を PNG フォーマットに変換したデータを取得し、img 要素の src 属性にセットしてみました。また、toDataURL() を使って得られたデータを div 要素内に表示しました。その後、toDataURL("image/jpeg") でも試しました。

/* canvasに赤色の矩形を描画する */
ctx.fillStyle = "rgb(200, 0, 0)";
ctx.fillRect(20, 30, 60, 40);
/* canvasの描画結果をPNGで取り出しimg要素にセット */
try {
  var img_png_src = canvas.toDataURL();
  document.getElementById("image_png").src = img_png_src;
  document.getElementById("data_url_png").firstChild.nodeValue = img_png_src;
} catch(e) {
  document.getElementById("image_png").alt = "未対応";
}
/* canvasの描画結果をJPEGで取り出しimg要素にセット */
try {
  var img_jpeg_src = canvas.toDataURL("image/jpeg");
  document.getElementById("image_jpeg").src = img_jpeg_src;
  document.getElementById("data_url_jpeg").firstChild.nodeValue = img_jpeg_src;
} catch(e) {
  document.getElementById("image_jpeg").alt = "未対応";
}

このスクリプトを Firefox 2.0 実行すると、次の画像が生成されます。

PNGの場合 JPEGの場合

左の画像が PNG フォーマット、右の画像が JPEG フォーマットで生成された画像です。canvas では赤色の矩形しか描いていません。canvas の仕様では、描かれていない部分は黒の透明として扱われます。そのため、PNG フォーマットで生成すると、その部分は透明として生成されますが、JPEG では透明を表現できませんので、黒で塗りつぶされてしまいます。

[toDataURL() メソッドの実際のサンプル]

ブラウザ対応状況

Firefox Safari Chrome Opera IE ExplorerCanvas
2 ○
image/png
image/jpeg
2 × 1 × 9.2 ○
image/png
9 ○
image/png
image/jpeg
0002 ×
3 ○
image/png
image/jpeg
3 × 2 ○
image/png
9.5 ○
image/png
  3 ×
3.5 ○
image/png
image/jpeg
4 ○
image/png
image/jpeg
3 ○
image/png
10 ○
image/png
image/jpeg
   
3.6 ○
image/png
image/jpeg
5 ○
image/png
image/jpeg
6 ○
image/png
10.60 ○
image/png
image/jpeg
   

image/png 以外に関しては、ブラウザによって対応している画像フォーマットが異なります。