textarea 要素

4.10.13 textarea 要素

カテゴリー
フロー・コンテンツ
フレージング・コンテンツ
インタラクティブ・コンテンツ
リスト化要素で、ラベル付け可能で、サブミット可能リセット可能フォーム関連要素
この要素を使うことができるコンテキスト:
フレージング・コンテンツが期待される場所
コンテンツ・モデル:
テキスト
コンテンツ属性:
グローバル属性
autofocus
cols
dirname
disabled
form
maxlength
name
placeholder
readonly
required
rows
wrap
DOM インタフェース:
interface HTMLTextAreaElement : HTMLElement {
           attribute boolean autofocus;
           attribute unsigned long cols;
           attribute DOMString dirName;
           attribute boolean disabled;
  readonly attribute HTMLFormElement form;
           attribute long maxLength;
           attribute DOMString name;
           attribute DOMString placeholder;
           attribute boolean readOnly;
           attribute boolean required;
           attribute unsigned long rows;
           attribute DOMString wrap;

  readonly attribute DOMString type;
           attribute DOMString defaultValue;
           attribute DOMString value;
  readonly attribute unsigned long textLength;

  readonly attribute boolean willValidate;
  readonly attribute ValidityState validity;
  readonly attribute DOMString validationMessage;
  boolean checkValidity();
  void setCustomValidity(in DOMString error);

  readonly attribute NodeList labels;

  void select();
           attribute unsigned long selectionStart;
           attribute unsigned long selectionEnd;
           attribute DOMString selectionDirection;
  void setSelectionRange(in unsigned long start, in unsigned long end, in optional DOMString direction);
};

textarea 要素は、この要素の生データ値に対するマルチラインのプレーンテキスト編集コントロールを表します。 このコントロールのコンテンツは、そのコントロールのデフォルト値を表します。

textarea コントロールの生データ値は、 初期においては 空文字列でなければいけません。

textarea 要素、そして、その生データ値の中にある改行は、Unicode 双方向アルゴリズムという目的においては、段落に分離しなければいけません。この要件は、スタイル・レイヤーを通して、間接的に実装しても構いません。例えば、HTML+CSS ユーザーエージェントは、CSS の 'unicode-bidi' プロパティを実装することで、これらの要件を実装することができるでしょう。[BIDI] [CSS]

readonly 属性は、論理属性です。ユーザーがそのテキストを編集できるかどうかをコントロールするために使います。

制約バリデーションreadonly 属性が textarea 要素に指定されているなら、その要素は制約バリデーションから除外されます。

textarea 要素が無効でもなく readonly 属性も指定されていないなら、それはミュータブルであるといいます。

textareaミュータブルのとき、その生データ値は、ユーザーによって編集できるようにするべきです。ユーザーエージェントは、ユーザーがテキストを編集、挿入、削除できるようにし、U+000A LINE FEED (LF) 文字の形式で改行を挿入したり削除したりできるようにするべきです。ユーザーがこの要素の生データ値を変更したときは常に、ユーザーエージェントは、その textarea 要素で input という名前のバブリングするシンプルなイベントを発出するためのタスクをキューイングしなければいけません。ユーザーエージェントは、ユーザーが操作している間は適切な間隔をおいてから、そのタスクをキューイングすることができます。例えば、ユーザーエージェントは、キーが押されるたびではなく、ユーザーがキーを押してから 100ms だけ待ち、その間にユーザーが何もしなければイベントを発出するのです。

textarea 要素は汚染値フラグを持ちます。これは、初期においては false にセットされなければいけません。そして、ユーザーがこのコントロールを操作することで生データ値が変更されたら true にセットされなければいけません。

textarea 要素の textContent IDL 属性が値を変更するとき、この要素の汚染値フラグが false なら、この要素の生データ値は、この要素の textContent IDL 属性の値にセットされなければいけません。

textarea 要素に対するリセット・アルゴリズムは、この要素のを、この要素の textContent IDL 属性の値にセットすることです。

この要素がミュータブルなら、ユーザーエージェントは、ユーザーがこの要素の書式方向を変更できるようにするべきです。左から右向きの書式方向、または、右から左向きの書式方向のいずれかです。ユーザーがそうしたなら、ユーザーエージェントは次の手順を実行しなければいけません:

  1. ユーザーが左から右向きの書式方向を選択したら、この要素の dir 属性を "ltr" にセットし、右から左向きの書式方向を選択したら、"rtl" にセットします。

  2. この textarea 要素で、input という名前のバブリングするシンプルなイベントを発出するタスクをキューイングします。

cols 属性は、行ごとの期待最大文字数を指定します。cols 属性が指定されたら、その値は 0 より大きい妥当な非負整数でなければいけません。この属性値に非負整数をパースする規則を適用した結果が 0 より大きい数字なら、この要素の文字幅はその値となります。そうでなければ 20 となります。

ユーザーエージェントは、textarea 要素の文字幅を、サーバーが求める行ごとの文字数がいくつなのかをユーザーに知らせるヒントとして使うことができます(ビジュアル・ユーザーエージェントでは、このコントロールの幅を、その文字数に合わせることができます)。ビジュアル・レンダリングでは、ユーザーエージェントは、レンダリングにおいては、ユーザーの入力を折り返して、それぞれの行がこの文字数より広くならないようにするべきです。

rows 属性は、表示する行数を指定します。rows 属性が指定されたら、その値は 0 より大きい妥当な非負整数でなければいけません。この属性値に非負整数をパースする規則を適用した結果が 0 より大きい数字なら、この要素の文字高はその値となります。そうでなければ 2 となります。

ビジュアル・ユーザーエージェントは、このコントロールの高さを、文字高によって指定された行数にセットするべきです。

wrap 属性は、2 つのキーワードと状態を持った列挙属性です。soft キーワードは Soft 状態に対応し、hard キーワードは Hard 状態に対応します。指定がなかった場合のデフォルトSoft 状態です。

Soft 状態とは、textarea の中のテキストがサブミット時に折り返されないことを意味します(レンダリングにおいては折り返されているかもしれません)。

Hard 状態とは、textarea の中のテキストがサブミット時にそのテキストが折り返されるようユーザーエージェントによって改行が追加されることを意味します。

この要素の wrap 属性が Hard 状態にあるなら、cols 属性が指定されていなければいけません。

この要素のは、この要素の生データ値に次の変換を適用したものとして定義されます:

  1. 直後に U+000A LINE FEED (LF) 文字が来ない U+000D CARRIAGE RETURN (CR) 文字、および、直前に U+000D CARRIAGE RETURN (CR) 文字が来ない U+000A LINE FEED (LF) 文字はすべて、U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) 文字ペアから成る 2 文字の文字列に置き換えます。

  2. この要素の wrap 属性が Hard 状態にあるなら、それぞれの行の文字が文字幅より大きくならないよう、ユーザーエージェント定義のアルゴリズムを使って、該当の文字列に U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) 文字ペアを挿入します。この要件の目的においては、文字列の最初、文字列の最後、U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) 文字ペアで行が区切られます。

maxlength 属性は、textarea 要素の汚染値フラグによってコントロールされるフォーム・コントロール maxlength 属性です。

textarea 要素が最大許容データ長を持つなら、この要素の子は、この要素の textContent IDL 属性の値のコード・ポイント長が、この要素の最大許容データ長に等しいか小さい状態でなければいけません。

required 属性は論理属性です。指定されたら、ユーザーエージェントは、フォームをサブミットする前に、値の入力を求めるでしょう。

制約バリデーション: この要素に required 属性が指定され、そして、この要素がミュータブルで、かつ、この要素のが空文字列なら、この要素は未入力状態に陥っていることになります。

placeholder 属性は、ユーザーがデータを入力する際の助けとなるようなヒント(単語または短いフレーズ)を表します。ヒントは、入力例や、どんな形式で入力させたいかを簡単に説明したものとなるでしょう。この属性は、指定されたら、U+000A LINE FEED (LF) または U+000D CARRIAGE RETURN (CR) 文字を含まない値でなければいけません。

もっと長いヒントや別の助言を表すテキストなら、title 属性の方が適切です。

placeholder 属性は、label の代わりとして使うべきではありません。

ユーザーエージェントは、この要素のが空文字列で、このコントロールにフォーカスが当たっていないときに、このヒントから改行を取り除いたうえでユーザーにそれを提供するべきです(例えば、空でフォーカスが当たっていないコントロールの中にそれを表示します)。

dirname 属性は、フォーム・コントロール dirname 属性です。

form 属性は、textarea 要素を明示的にフォーム・オーナーと関連づけるために使います。name 属性は、この要素の名前を表します。disabled 属性は、このコントロールを非インタラクティブにして、その値がサブミットされないようにするために使います。autofocus 属性はフォーカスをコントロールします。

textarea . type

文字列 "textarea" を返します。

textarea . value

この要素の現在の値を返します。

セットして値を変更することができます。

cols, placeholder, required, rows, wrap 属性は、それぞれ、同じ名前のコンテンツ属性を反映しなければいけません。colsrows 属性は、0 より大きい非負数のみに限定されます。cols 属性のデフォルト値は 20 です。rows 属性のデフォルト値は 2 です。dirName IDL 属性は、dirname コンテンツ属性を反映しなければいけません。maxLength IDL 属性は、maxlength コンテンツ属性を反映しなければいけません。ただし、非負数のみに限定されます。readOnly IDL 属性は、readonly コンテンツ属性を反映しなければいけません。

type IDL 属性は "textarea" という値を返さなければいけません。

defaultValue IDL 属性は、この要素の textContent IDL 属性と同様に作用しなければいけません。

value 属性は、取得時においては、この要素の生データ値を返さなければいけません。セット時においては、この要素の生データ値を新たな値にセットしなければいけません。

textLength IDL 属性は、この要素のコード・ポイント長を返さなければいけません。

willValidate, validity, validationMessage 属性、そして、checkValidity()setCustomValidity() メソッドは、制約バリデーション API の一部です。labels 属性は、この要素の label のリストを提供します。select(), selectionStart, selectionEnd, selectionDirection, setSelectionRange() メソッドおよび属性は、この要素のテキストの選択範囲にアクセスすることができます。autofocus, disabled, form, name IDL 属性は、この要素の forms API の一部です。

これは、フォームで textarea を制限なしの自由記入のテキスト入力に使われている例です:

<p>If you have any comments, please let us know: <textarea cols=80 name=comments></textarea></p>

コメントの最大長を指定するために、maxlength 属性を使うことができます:

<p>If you have any short comments, please let us know: <textarea cols=80 name=comments maxlength=200></textarea></p>

デフォルト値を与えるために、この要素の中にテキストを入れておくことができます:

<p>If you have any comments, please let us know: <textarea cols=80 name=comments>You rock!</textarea></p>

値に合わせてこの要素の書式方向をブラウザーにサブミットさせるために、dirname 属性を指定することができます:

<p>If you have any comments, please let us know (you may use either English or Hebrew for your comments):
<textarea cols=80 name=comments dirname=comments.dir></textarea></p>

※ 原文:http://www.w3.org/TR/2011/WD-html5-20110525/the-button-element.html#the-textarea-element