<alier-checkbox>

概要

<alier-checkbox>は標準のHTML要素である<input type="checkbox">を基にしたalierのカスタム要素です。

標準のHTMLチェックボックスが持つ機能に準拠しつつアイコン、ラベル、アニメーションといったUIカスタマイズをサポートします。

<alier-checkbox label-position="bottom"　variant="check" animation="fade" round=false>ラベル</alier-checkbox>

上記の例は<alier-checkbox>のシンプルな使い方を示しています。

  • アイコン・シンボルについて

    • アイコン（チェックボックスの基本形状）、シンボル（チェック時に表示される記号）はround属性、variant属性を用いて指定します。

  • ラベルについて

    • ラベルはtextcontent(Text Node)で指定します。
    • ラベルの表示位置の既定はアイコンの左側です。表示位置に関してはlabel-position属性で指定できます。
    • フォーカスの適用範囲としてラベルも含まれています。

  • アニメーションについて

    • animation属性に定義済みのアニメーション名を指定することで、チェック状態がtrueとなった場合のアニメーションを有効にできます。

子要素

子要素として与えられたエレメントはスロットとして内部ラベルに割り当てられます。

カテゴリー

このエレメントはフォーム関連要素です。<form> で値を送信できます。

構造

<alier-checkbox>の構成は以下の通りです。

# ┬─ (slot)
  └─ control(div) ┬─ symbol (span)
                  ├─ checkbox (input)
                  ├─ checked-img (img)
                  └─ unchecked-img (img)
part名 タグ名 説明
control div チェックボックスを構成する要素です。
symbol span チェック時に表示される記号を扱う要素です。
checkbox input <input type="checkbox">を表す要素です。
checked-img img チェック時に表示される画像リソースを扱う要素です。
unchecked-img img チェックされていない場合に表示される画像リソースを扱う要素です。

それぞれのノードを ::part() 疑似要素で指定するとスタイルを適用できます。

属性

ラベル位置の指定

label-position属性に対する値を指定することでラベルの表示位置を指定できます。

属性 値 説明
label-position reverse,bottom 未指定の場合、ラベルは既定でアイコンの右側に配置されます。
reverse：アイコンとラベルの並びが逆順に配置されます。
bottom：アイコンの下にラベルが配置されます。

アイコンの指定

  • 外枠の形状

    属性 有効な値 説明
    round 論理属性 アイコンが円形となる。variantの値がcheck, slash, dot, switch, tag, imgのとき有効となります。

  • アイコン・シンボルの形状

    variant属性に対する値を指定することでアイコン・シンボルの形状を指定できます。

    属性 値 説明
    variant check, slash, dot, switch, tag, img, star, heart, bell アイコンおよびシンボルの形状を指定します。指定がないときは標準の<input type="checkbox">が描画されます。
    switch: トグルスイッチ型のアイコン
    tag: 札型のアイコン
    img: 指定した画像のアイコン
    star: 星型のアイコン
    heart: ハート型のアイコン
    bell: ベルマーク型のアイコン
    check: チェックマーク型のシンボル
    slash: スラッシュ記号のシンボル
    dot: ドット型のシンボル
    src: 活性・非活性時に表示する画像
    • tagを指定した場合、ラベルはタグ内に表示されます。

  • アニメーション指定

    animation属性に対する値を指定することでアニメーションを指定できます。

    属性 値 説明
    animation none,fade,swing,ripples checkedがtrueになった時のアニメーション効果を指定します。複数指定が可能です。既定値はfadeです。
    none: アニメーションなし
    fade: チェックボックス内の変化が徐々に行われます。
    swing: チェック時にチェックボックス全体が左右に揺れます。
    ripples: チェック時にチェックボックスの周りに四角形の枠が拡大されながら数秒表示されます。

  • 画像の指定

    属性 有効な値 説明
    src 画像の URL を指定する文字列 variant="img"のとき、チェック状態のシンボル画像を指定します。
    src-uncheck 画像の URL を指定する文字列です。 variant="img"のとき、非チェック状態のシンボル画像を指定します。

  • その他コントロール

    属性 有効な値 説明
    hidden 論理属性 タグ全域について非表示にします。
    disabled 論理属性 コントロールを無効化します。formにおいても無視されます。
    プロパティを通した変更は阻害しません。
    name 任意の値 form送信時のkeyになります。
    value 任意の値 form送信時のvalueになります。
    required 論理属性 form送信時にチェック必須にします。
    checked 論理属性 指定すると初めからチェックされた状態にななります。
    ネイティブのinputのchecked属性と異なり、常に内部の値と連動します。

スタイル

<alier-checkbox>のcssでのスタイル指定には２種類の方法があります。

  1. CSS変数によるスタイルの指定。
  2. part名をによるスタイルの指定。

1. CSS変数

属性 説明
--alier-cb-size アイコンのサイズ
--alier-cb-radius アイコンの外枠の丸み
--alier-switch-length switchタイプのスライド量
--alier-switch-knob-width switchタイプのスライド方向のノブ幅
--alier-switch-margin switchタイプのノブ周囲のマージン

2. part名

alier-checkboxを構成するshadowDOMの要素には::part(foo)で指定可能なものが存在します。
part名を介して特定の要素の選択およびスタイルの設定を行うことが可能です。

part名 要素 説明
control div チェックボックスのアイコン（ラベルを除く）
symbol span チェックボックスのシンボル
checkbox input input要素のチェックボックス
checked-image img チェック時に表示される画像
variant=="image"の際に追加されます。
unchecked-img img チェックが外れている時に表示される画像
variant=="image"の際に追加されます。

CheckBox クラス

モジュールパス: /alier_sys/CheckBox.js

--- config: class: hideEmptyMembersBox: true --- classDiagram direction LR HTMLElement <|-- AlierCustomElement AlierCustomElement <|-- CheckBox

<alier-checkbox>要素が実装しているCheckboxは、チェックボックスを操作するための専用のプロパティとメソッドを提供しています。また、AlierCustomElementを継承しています。

プロパティ

checked

要素の現在のチェック状態、つまり、あるフォームコントロールがチェック済みかどうかを指定します。このプロパティは標準の HTMLInputElement インターフェースが持つ checked プロパティと同等です。

型

  • boolean

name

要素の名前を示します。このプロパティは標準のHTML要素が持つHTMLInputElementインターフェイスのnameプロパティと同等です。

型

  • string

value

要素の現在の値を文字列で表します。このプロパティは、直接設定することもできます。また、このプロパティは標準のHTML要素が持つHTMLInputElementインターフェイスのvalueプロパティと同等です。

型

  • string

disabled

このコントロールが無効であるかどうかを表します。無効である場合、クリックを受け付けません。無効化された要素は使用できず、クリックもできません。このプロパティは標準のHTML要素が持つHTMLInputElementインターフェイスのdisableプロパティと同等です。

型

  • boolean

required

フォームを送信する前にユーザーが値を入力しなければならないことを指定します。このプロパティは標準のHTML要素が持つHTMLInputElementインターフェイスのrequiredプロパティと同等です。

型

  • boolean

メソッド

toggle()

  • チェックボックスのチェック状態を切り替えます。

イベント

継承元の HTMLElement や内部に持つ <input> から送出されるイベントもあります。

change

checked状態の変化に伴って発火します。 標準の change イベントと同じ内容ですが、カスタムイベントとして送出しています。

click

直接入力に反応して発火します。disabledのとき発火しません。 標準の change イベントと同じ内容ですが、カスタムイベントとして送出しています。

visible

要素が初めて画面内に入ったとき発火します。