progress 要素

4.10.14 progress 要素

カテゴリー:
フロー・コンテント
フレージング・コンテント
ラベル付け可能要素
パルパブル・コンテント
この要素を使うことができるコンテキスト:
フレージング・コンテントが期待される場所
コンテントモデル:
フレージング・コンテント。しかし、子孫に progress 要素を入れることはできません。
コンテント属性:
グローバル属性
value - 要素の現在値
max - 範囲の上限
text/html におけるタグの省略:
どちらのタグも省略できません。
指定可能な ARIA role 属性 の値:
progressbar (デフォルト - 指定不要).
指定可能な ARIA ステートとプロパティ属性:
グローバル aria-* 属性
許可ロールに該当する aria-* 属性
DOM インタフェース:
interface HTMLProgressElement : HTMLElement {
           attribute double value;
           attribute double max;
  readonly attribute double position;
  readonly attribute NodeList labels;
};

progress 要素は、タスクが完了するまでの進捗を表します。その進捗が確定できない場合もあります。それは、進捗しているものの、そのタスクが完了するまでに、どれだけの作業が残っているのかが、はっきりしないことを表します(例えば、そのタスクはリモートホストの応答を待っているといった理由から)。また、その進捗は、0 から最大値の範囲の数字をとることもあります。その数字とは、その時点までで完了した作業の割合のことです。

この要素で表される現在のタスクの完了度を決定する 2 つの属性があります。 value 属性には、タスクがどれだけ完了したかを指定します。max 属性には、そのタスクが完了するために合計でどれだけの作業が必要なのかを指定します。単位は任意で、指定はありません。

value 属性に現在の進捗(0.0 から 1.0 までの数値、もしくは、max 属性が指定されているなら、0 から max 属性の値までの数値)を指定することで、確定プログレスバーを作ることができます。value 属性を削除すれば、未確定プログレスバーを作ることができます。

ウェブ制作者は現在値と最大値をその要素の中にテキストとしてインラインで入れ、古いユーザーエージェントのユーザーでも、その進捗を把握できるようにすることが推奨されます。

これは、自動化タスクの進捗を表示するウェブアプリケーションです:

<section>
 <h2>タスクの進捗</h2>
 <p>進捗: <progress id="p" max=100><span>0</span>%</progress></p>
 <script>
  var progressBar = document.getElementById('p');
  function updateProgress(newValue) {
    progressBar.value = newValue;
    progressBar.getElementsByTagName('span')[0].textContent = newValue;
  }
 </script>
</section>

(この例の updateProgress() メソッドは、同じページの別のコードから呼び出され、タスクの進捗に従って実際にプログレスバーを更新することになります。)

valuemax 属性が存在すれば、それらの値は妥当な浮動小数点数でなければいけません。value 属性が存在すれば、その値は 0 以上でなければいけません。max 属性が存在すれば、value 属性の値は max 属性値以下でなければいけません。存在しなければ、value 属性の値は 1.0 以下でなければいけません。max 属性が存在すれば、その値は 0 より大きい値でなければいけません。

progress 要素を、タスクの進捗ではなく、まさにゲージとなるようなものに使うのは正しくありません。例えば、ディスク使用量を progress 要素を使って表示するのは適切ではないでしょう。この場合は、meter 要素が使えます。

ユーザーエージェントの要件: value 属性が省略されたら、そのプログレスバーは未確定プログレスバーとなります。そうでなければ、確定プログレスバーとなります。

プログレスバーが確定プログレスバーで、その要素に max 属性があれば、ユーザーエージェントは、浮動小数点数値パース規則に従って、その max 属性の値をパースしなければいけません。この結果がエラーにはならず、パースした値が 0 より大きければ、そのプログレスバーの最大値は、その値となります。一方、その要素が max 属性を持たない、または、持つけれども、それをパースしたらエラーになる、または、パースした値が 0 以下となる場合は、そのプログレスバーの最大値は 1.0 となります。

プログレスバーが確定プログレスバーなら、ユーザーエージェントは、浮動小数点数値パース規則に従って、その value 属性の値をパースしなければいけません。この結果がエラーにはならず、パースした値が最大値より小さく 0 より大きければ、そのプログレスバーの現在値は、そのパースした値となります。一方、パースした値が最大値より大きい、または、等しいなら、そのプログレスバーの現在値は、そのプログレスバーの最大値となります。value 属性の値がパースエラーになったり、0 以下の数値になったら、そのプログレスバーの現在値は 0 となります。

プログレスバー表示に対するユーザーエージェントの要件: progress 要素をユーザーに表示するとき、ユーザーエージェントは、それが確定プログレスバーなのか未確定プログレスバーなのかを示すべきです。そして、前者の場合は、最大値に対する現在値の位置を示すべきです。

progress . position

確定プログレスバー(現在値と最大値が分かっている)に対して、現在値を最大値で割った結果を返します。

未確定プログレスバーに対しては、-1 を返します。

プログレスバーが未確定プログレスバーなら、position IDL 属性は -1 を返さなければいけません。そうでなければ、現在値最大値で割った値を返さなければいけません。

プログレスバーが未確定プログレスバーなら、value IDL 属性は、取得時においては、0 を返さなければいけません。そうでなければ、現在値を返さなければいけません。セット時においては、指定された値を浮動小数点数としての最良数値表現に変換しなければいけません。それから、value コンテント属性に、その文字列をセットしなければいけません。

value IDL 属性に、そのコンテント属性が存在しないときに、その値をセットすると、そのプログレスバーは、未確定プログレスバーから、進捗が一切ない確定プログレスバーに変更されることになります。

max IDL 属性は、同じ名前のコンテント属性を反映しなければいけません。ただし、0 より大きい数値に限定されます。max 属性のデフォルト値は 1.0 です。

labels IDL 属性は、該当の要素の label のリストを提供します。


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