Yamato DaiwaFrontend (2.0.0-beta.12)
English
日本語
Русский

TextBox

テキストボックスは、ボタンコンポーネント（Button）と並び、グラフィカルユーザーインターフェースにおいて最も基本的かつ頻繁に利用されるコンポーネントの一つだ。 ここで扱うのは書式設定なし（太字や斜体などがない）のテキスト入力であり、書式設定に対応したテキストエディタは、これとは別のより複雑なトピックとなる。 書式設定はないものの、名前、住所、各種タイトルなど、このコンポーネントを通じてユーザーから受け取るデータは多岐にわたる。 さらに「テキスト」とは、単に完結した文章の集まりだけを指すのではなく、文字の連なりとして表現できるあらゆる情報を意味する：

  • メールアドレス
  • パスワード
  • リンク

また、このコンポーネントは数値データの入力に使われることもあるが、多くの場合、それらは「数値」そのものではなく、補助記号が混ざった数字の羅列だ：

  • 電話番号
  • 郵便番号
  • クレジットカード番号

多くの場合、このコンポーネントは改行を想定しておらず、入力された文字数が多いときはその一部のみが表示される（矢印キーによるスクロールは可能）。 しかし、ユーザーに完結した文章（あるいは段落）の入力を求める場合には改行が必要となり、これは一種の単純なテキスト書式設定とみなせることもある。 HTMLの観点では、複数行テキストには別の要素が使われ（当初は高さの自動調整機能も備わっていない）、一方でYDFでは、対応するオプションを指定するだけで複数行モードをサポートでき、高さの自動調整も利用可能だ。

ボタンと同様、テキストフィールドの単純さは見かけによらない。 第一に、テキスト入力フィールドは バリデーション対応コンポーネントであり、そのため入力データのバリデーション（検証）という課題の複雑さが、このコンポーネントに直接関係してくる。 YDFにおけるテキスト入力フィールドは、 ValidatableControlShellコンポーネントにラップされた他のコンポーネントと同様、ラベル、注釈、バリデーションエラー一覧などのオプションの補助要素を含んでいるが、HTMLの観点ではこれらはすべて個別の要素となる。

テキスト入力フィールドには多くの状態がある。 視覚的に区別されるべき状態は、少なくとも以下の通りだ：

:hover
マウスカーソルが重なったときに有効になる。システムがユーザーの操作に反応していること、およびクリックすれば入力を開始できることをユーザーに伝える。
:focus
テキストフィールドがフォーカスを得たときに有効になる。つまり、キーボード入力がこのテキストフィールド内で受け付けられる状態であることを示す。
:readonly/:disabled
入力フィールドが読み取り専用のときに有効になる。 多くのアプリケーションには閲覧モードと編集モードがあるため、この機能は決して珍しいものではない。
バリデーションエラー（Invalid）状態
入力された値が有効でないとき、および有効性の表示モードが有効な場合にアクティブになる。 入力フィールドが初期状態で空かつ必須入力である場合、その空の値は最初から無効だが、まだ何もしていないユーザーに対してフィールドを赤く強調したりエラーを通知したりする前に、まずは入力を許可すべきだ。そして、ユーザーが入力フィールドからフォーカスを外したときに初めて、有効性の表示モードを有効にできる。 なお、このような概念はHTML/CSSの観点では存在しない。そのため、required や minlength といったHTML属性、および 疑似クラス :invalid を使ってバリデーションを定義すると、ユーザーが空のフィールドに入力を開始したかどうかにかかわらず、これらのスタイルが適用されてしまう。

さらに、これらの状態の一部は同時に発生し得る。 例えば、hover 状態は focus と同時に発生することがあり、これら両方の状態が invalid の上に重なって発生することもある。 ここでスタイルの優先順位という問題が生じる。

また、実務において入力フィールドには以下のような追加機能が求められる：

  • デザインに応じて左側または右側に配置できるアイコン
  • パスワードの表示/非表示の切り替えボタン
  • 入力された値をコピーするためのボタン

これらすべての機能は、TextBox コンポーネントで利用可能だ。

概要

Pugミクスイン
TextBox--YDF
PugミクスインのLive template (IntelliJ IDEAファミリー結合開発環境専用正式的プラグイン)
オートコンプリート系
TextBox--YDF
省略
tb-ydf
Loading Placeholder
スタイル生成専用Stylusミクスイン
TextBox--YDF-generateStyles
用意済みのテーマ
TextBox__YDF.Themes.regular
標準（規定）
用意済みの幾何学的変形
TextBox__YDF.GeometricVariations.regular
標準（規定）
TextBox__YDF.GeometricVariations.small
小型
TextBox__YDF.GeometricVariations.labelLike
一般ラベル外見
幾何学的修飾子
TextBox__YDF.GeometricModifiers.noRoundings
面取り無し
用意済みの修飾的変形
TextBox__YDF.DecorativeVariations.regular
標準（規定）
TextBox__YDF.DecorativeVariations.labelLike
一般ラベル外見
ローディングプレースホルダ
無し

利用

マークアップ

プロジェクトへの取り組み

当GUIコンポーネントのマークアップは Pugミクスインの TextBox--YDFに依り確保される。 取り組み方法は 通常 即ちComponents.pugと言うPugファイルの 含め 。 但し其の前Functionality.pugファイルも含めなければいけないが、ページのテンプレート の場合、Functionality.pugは含め済みで、 重複し含めてるとエラーが発生するのだ。

Pug混入のTextBox--YDF

TextBox--YDF
(
1パラメーター目
必須
一般技術名
properties
日本語名
プロパティ
型
Properties
2パラメーター目
任意
一般技術名
statesSimulations
日本語名
状態のシミュレーション
型
StatesSimulations
):void
TextBox.propertiesSpecification
{
HTML_Type
日本語名
HTMLタイプ
型
string
undefinedの代替
"text"
nullは不可か
はい
利用可能な選択肢
  • TextBox__YDF.HTML_Types.regular
  • TextBox__YDF.HTML_Types.email
  • TextBox__YDF.HTML_Types.number
  • TextBox__YDF.HTML_Types.password
  • TextBox__YDF.HTML_Types.phoneNumber
  • TextBox__YDF.HTML_Types.URI
label
日本語名
キャプション
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
guidance
日本語名
説明文
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
accessibilityGuidance
日本語名
アクセシビリティ技術専用説明文
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
externalLabelHTML_ID
日本語名
外部ヘッダーラベルのHTML ID
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
placeholder
日本語名
空入力の時表示本文
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
autocomplete
日本語名
「autocomplete」属性の値
型
string
undefinedは不可か
いいえ
nullは不可か
はい
value
日本語名
初期値
型
string
undefinedの代替
""
nullは不可か
はい
multiline
日本語名
複数行サポートの要否
型
boolean
undefinedの代替
false
nullは不可か
はい
autoResizingForMultilineMode
日本語名
複数行モードでの高さ自動調整の要否
型
boolean
undefinedの代替
true
nullは不可か
はい
disabled
日本語名
非活性状態の真偽
型
boolean
undefinedは不可か
いいえ
nullは不可か
はい
readonly
日本語名
読み込み専用か
型
boolean
undefinedは不可か
いいえ
nullは不可か
はい
required
日本語名
入力が必須か
型
boolean
undefinedの代替
false
nullは不可か
はい
mustDisplayAppropriateBadgeIfInputIsRequired
日本語名
入力が必須な時「必須」バッジの表示が要るか
型
boolean
undefinedの代替
false
nullは不可か
はい
mustDisplayAppropriateBadgeIfInputIsOptional
日本語名
入力が任意な時「任意」バッジの表示が要るか
型
boolean
undefinedの代替
false
nullは不可か
はい
mustAddInvisibleBadgeForHeightEqualizingWhenNoBadge
日本語名
バッジ表示が不要な時、高さ調整の為見えないバッジの追加が要るか
型
boolean
undefinedの代替
false
nullは不可か
はい
minimalCharactersCount
日本語名
最小文字数
型
number
undefinedは不可か
いいえ
nullは不可か
はい
数の集合
正の整数・0
maximalCharactersCount
日本語名
最大文字数
型
number
undefinedは不可か
いいえ
nullは不可か
はい
数の集合
正の整数・0
minimalNumericValue
日本語名
最小数値
型
number
undefinedは不可か
いいえ
nullは不可か
はい
数の集合
正の整数・0
maximalNumericValue
日本語名
最大数値
型
number
undefinedは不可か
いいえ
nullは不可か
はい
数の集合
正の整数・0
hasValueCopyingButton
日本語名
値コピーボタンの要否
型
boolean
undefinedの代替
false
nullは不可か
はい
hasPasswordDisplayingToggle
日本語名
パスワード表示切り替えボタンの要否
型
boolean
undefinedの代替
false
nullは不可か
はい
instanceID_UniqueDynamicPart
日本語名
インスタンス識別子の唯一な動的部分
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
HTML_IDs
日本語名
HTML識別子の揃い
型
固定スキーマのオブジェクト
undefinedは不可か
いいえ
nullは不可か
はい
スキーマ
{
inputOrTextArea
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
label
型
string
undefinedは不可か
いいえ
nullは不可か
はい
最小文字数
1
}
theme
日本語名
テーマ
型
string
undefinedの代替
TextBox__YDF.Themes.regular
nullは不可か
はい
利用可能な選択肢
  • TextBox__YDF.Themes.regular
  • (`TextBox__YDF.defineThemes(themesNames)`で定義された中から何れか)
areThemesCSS_ClassesCommon
日本語名
テーマCSSクラスは共通真偽
型
boolean
undefinedの代替
TextBox__YDF.areThemesCSS_ClassesCommon
nullは不可か
はい
geometricVariation
日本語名
幾何学的変形
型
string
undefinedの代替
TextBox__YDF.GeometricVariations.regular
nullは不可か
はい
利用可能な選択肢
  • TextBox__YDF.GeometricVariations.regular
  • TextBox__YDF.GeometricVariations.small
  • TextBox__YDF.GeometricVariations.labelLike
  • (`TextBox__YDF.defineGeometricVariations(geometricVariationsNames)`で定義された中から何れか)
geometricModifiers
日本語名
幾何学的改変
型
指数配列
undefinedの代替
[]
nullは不可か
はい
undefined要素可否
はい
null要素可否
はい
配列の要素
型
string
利用可能な選択肢
  • TextBox__YDF.GeometricModifiers.pillShape
  • TextBox__YDF.GeometricModifiers.squareShape
  • TextBox__YDF.GeometricModifiers.squareShapeUnlessOverflowed
  • TextBox__YDF.GeometricModifiers.singleLine
  • TextBox__YDF.GeometricModifiers.noLeftBorderAndRoundings
  • TextBox__YDF.GeometricModifiers.noRightBorderAndRoundings
  • TextBox__YDF.GeometricModifiers.noTopBorderAndRoundings
  • TextBox__YDF.GeometricModifiers.noBottomBorderAndRoundings
  • TextBox__YDF.GeometricModifiers.noRoundings
  • TextBox__YDF.GeometricModifiers.horizontallyShrinkable
decorativeVariation
日本語名
修飾的変形
型
string
undefinedの代替
TextBox__YDF.DecorativeVariations.regular
nullは不可か
はい
利用可能な選択肢
  • Button__YDF.DecorativeVariations.regular
  • Button__YDF.DecorativeVariations.labelLike
  • (`TextBox__YDF.defineDecorativeVariations(decorativeVariationsNames)`で定義された中から何れか)
}
TextBox.statesSimulations
{
invalidInputHighlightingIfAnyValidationErrorsMessages
日本語名
入力妥当性確認のメッセージが１件以上の時不正入力ファイライトが要るか
型
boolean
undefinedの代替
false
nullは不可か
はい
validValueHighlightingIfNoValidationErrorsMessages
日本語名
入力妥当性確認のメッセージが０件の時妥当入力ファイライトが要るか
型
boolean
undefinedの代替
false
nullは不可か
はい
validationErrorsMessages
日本語名
入力妥当性確認エラーメッセージ
型
多形性
undefinedの代替
false
nullは不可か
はい
選択肢
  • 型
    指数配列
    undefined要素可否
    はい
    null要素可否
    はい
    配列の要素
    型
    string
    最小文字数
    1
  • 型
    boolean
asynchronousValidationsStatuses
日本語名
入力非同期妥当性確認状態
型
多形性
undefinedの代替
false
nullは不可か
はい
選択肢
  • 型
    指数配列
    undefined要素可否
    はい
    null要素可否
    はい
    配列の要素
    型
    固定スキーマのオブジェクト
    スキーマ
    {
    ID
    型
    string
    undefinedは不可か
    はい
    nullは不可か
    はい
    利用可能な選択肢
    • IN_PROGRESS
    • FINISHED_AND_VALID
    • FINISHED_BUT_INVALID
    • MALFUNCTION
    message
    型
    string
    undefinedは不可か
    はい
    nullは不可か
    はい
    最小文字数
    1
    }
  • 型
    boolean
}

© 2023 Yamato Daiwa Co., Ltd.