On this page
フロントエンドコンポーネント
dframework には、フロントエンドバンドルに自動コンパイルされる依存ゼロの高性能カスタムwebコンポーネントライブラリが標準搭載されています。仮想DOM、外部トランスパイル、ビルド手順を必要としない標準カスタム要素として実装されており、サーバー起動時に public/js/components/ 内のコンポーネントが自動的に検出・バンドルされます。
すべての組み込みコンポーネントは、英語と日本語の辞書を備えたネイティブなクライアント側ローカライズ(this.t())を標準でサポートしています。言語切り替えや文言のカスタマイズ方法については、多言語化ガイド を参照してください。
コンポーネント一覧
各コンポーネントは機能ごとに個別のドキュメントファイルに分割されており、構造、ライブ使用例、属性、プログラムAPI、イベント、キーボード操作の仕様が詳しく記載されています。
レイアウトとナビゲーション
d-sidebar: オフキャンバス開閉、アイコン縮小、モバイルドロワーに対応したサイドバー。d-navmenu: アニメーションインジケーターとビューポートを備えたレスポンシブナビゲーションメニュー。d-breadcrumb: 中間項目の自動省略とカスタム区切り文字に対応したパンくずリスト。d-drawer: スワイプ解除や端部固定に対応したスライディングドロワー。d-hamburger: 自動階層ドリルダウンを備えたモバイルドロワーメニュー。d-menubar: 矢印キーナビゲーションに対応したデスクトップアプリケーションメニューバー。d-link: モーフィング画面遷移を行う宣言型クライアントルーターリンク。
フォームと入力
d-text-input: クリアボタンとフローティングラベルを備えたテキスト入力フィールド。d-combobox: 非同期検索とキーボード操作に対応した絞り込みセレクトボックス。d-toggle: スライドアクティブインジケーターを備えたセグメント切り替えスイッチ。d-checkbox: アニメーションチェックマークを備えた3状態対応チェックボックス。d-radiobutton: キーボードグループ移動に対応した単一選択ラジオボタン。d-datepicker: 日付フォーマットとポップアップカレンダーを備えた日付入力。d-calendar: 単一・範囲・複数日選択に対応したインタラクティブカレンダーグリッド。d-color-picker: hex・rgb・hsl入力に対応した視覚的カラーピッカー。d-file-input: プログレス表示を備えたドラッグ&ドロップファイル入力。d-image-input: プレビューとアスペクト比固定に対応した画像アップロード入力。d-slider: ツールチップバブルとステップスナップを備えた数値スライダー。d-otp: 自動フォーカス移動とクリップボード貼り付けに対応したワンタイム認証コード入力。d-form: 自動エラー処理と読み込み状態管理を備えたリアクティブajaxフォーム。
オーバーレイとフィードバック
d-modal: バックドロップ解除とエスケープキーに対応したダイアログオーバーレイ。d-popover: ビューポート自動位置調整を備えたアンカー固定ポップオーバー。d-notification: スタック表示と自動消去タイマーを備えたトースト通知。d-tooltip: ホバーおよびフォーカス時にショートカットバッジを表示するツールチップ。d-context-menu: 階層サブメニューに対応した右クリックコンテキストメニュー。d-dropdown: キーボード選択に対応したドロップダウントリガーおよびメニュー。
データと表示
d-codeblock: 行番号とコピーボタンを備えたシンタックスハイライトコードブロック。d-skeleton: カスタム寸法に対応したコンテンツ読み込みプレースホルダー。d-progress: 確定および不確定モードに対応した進捗インジケーター。d-virtual-list: 大規模データセット向けの高パフォーマンス仮想スクローラー。d-key: OS別キーボードシンボル自動変換に対応したショートカットバッジ。d-loader: 非同期状態を示すスピナーおよびパルスアニメーションローダー。
アクションとコントロール
d-buttongroup: 共通角丸と境界線を備えたボタン連結ツールバー。d-hold-button: 円形プログレスリングによる長押し確認ボタン。d-icon-button: アイコンフォントに最適化された正方形アクセシブルボタン。d-morph: 要素間のスムーズな形状変化を実現するモーフィングコンテナ。d-questionnaire: フォーム検証を備えた複数ステップ対話ウィザード。
組み込みコンポーネントのオーバーライド
組み込みコンポーネントのすべての動作はアプリケーションコードによってカスタマイズ、拡張、または完全に上書きできます。組み込みコンポーネントをオーバーライドするにはpublic/js/components/配下にまったく同じコンポーネントファイル名でファイルを配置します(例: public/js/components/dCheckbox.js)。
フロントエンドバンドルのコンパイル時にコンパイラはユーザーファイルを自動検出し組み込みコンポーネントの実装をその場で置き換えます。
1class dCheckbox extends dComponent {2 static form = true;3 static get tag() { return 'd-checkbox'; }4}5 6dComponent.define(dCheckbox);
イミュータブルな基底クラス
すべてのカスタム要素およびオーバーライドはdComponentを継承します。UIコンポーネントとは異なりdComponentはリアクティビティ、リフレクション、ライフサイクル管理を提供するイミュータブルなフレームワーク基底クラスです。コンパイラは常にバンドルのルートにコアのdComponent実装を保持するため、すべてのコンポーネントが一貫してこれを継承します。
dComponent(基底クラス)
dComponentはdframeworkにおけるすべてのカスタムwebコンポーネントのオーサリング基底クラスです。プロパティリフレクション、リアクティブプロキシステート、フォーム統合、局所的DOMレンダリング、自動メモリクリーンアップを提供します。
1class dCounter extends dComponent {2 static tag = 'd-counter';3 static form = true;4 5 static props = {6 value: { type: 'number', default: 0, form: true },7 step: { type: 'number', default: 1 },8 disabled: { type: 'boolean', default: false },9 label: { type: 'string', default: 'count' }10 };11 12 template() {13 return `[object Object]>14 <span class="label">${this.label}</span>[object Object]>15 <button class="dec" type="button">−</button>[object Object]>16 <span class="value">${this.value}</span>[object Object]>17 <button class="inc" type="button">+</button>[object Object]>18 `;19 }20 21 mount() {22 this.effect(() => {23 document.title = `count: ${this.state.value ?? this.value}`;24 return () => { document.title = 'app'; };25 });26 }27 28 render() {29 this.refs('.value')[0].textContent = this.state.value ?? this.value;30 this.refs('button.dec')[0].disabled = this.disabled;31 this.refs('button.inc')[0].disabled = this.disabled;32 33 this.listen(this.refs('button.dec')[0], 'click', () => this.decrement());34 this.listen(this.refs('button.inc')[0], 'click', () => this.increment());35 }36 37 onPropChanged(name, oldVal, newVal) {38 }39 40 increment() {41 this.setState(s => { s.value = (s.value ?? this.value) + this.step; });42 }43 44 decrement() {45 this.setState(s => { s.value = (s.value ?? this.value) - this.step; });46 }47}48 49dComponent.define(dCounter);
コンポーネントの定義と登録
dComponent.define(Class)を使用してコンポーネントを登録します:
1dComponent.define(dCounter);- 型変換(
number、boolean、string、object、array)を伴うゲッターおよびセッタープロパティをプロトタイプ上に自動定義します。 - 監視対象属性をプロパティセッターにバインドします。
Class.tagを使用してcustomElements.defineに登録します。
ライフサイクルメソッド
| メソッド | タイミング | 説明 |
|---|---|---|
template() |
マウント前 | 内部DOMを構築するための初期HTML文字列を返却 |
mount() |
初回接続時 | コンポーネントロジックを初期化しエフェクトを登録 |
mountSync() |
手動/即時 | RAF遅延を待たずに即時同期マウントを実行 |
connected() |
接続ごと | 要素がドキュメントにアタッチされるたびに呼び出し |
render() |
ステート/プロパティ変更時 | 局所的なDOMノード更新を実行 |
onPropChanged(name, old, new) |
プロパティ変更時 | 特定のプロパティの変更に反応 |
syncForm() |
フォーム/手動 | ElementInternalsのフォーム値を同期(独自ルールでオーバーライド可能) |
onscreen() |
ビューポート進入時 | コンポーネントがビューポートに入ったときに呼び出し |
offscreen() |
ビューポート退出時 | コンポーネントがビューポートから出たときに呼び出し |
destroy() |
切断時 | 要素がDOMから削除されたときに呼び出される破棄フック |
`mount()`の初期化は初回DOM接続時に`requestAnimationFrame`を介してバッチ処理されます。これによりライトDOM内で解析されたすべての子ノードが`mount()`実行前に存在し利用可能であることが保証されます。プログラムから動的に子カスタム要素を生成した場合や、生成直後に即座に同期初期化が必要な場合は、`element.mountSync()`または`dComponent.mountSync(element)`を呼び出します。テンプレートコンポーネントの場合テンプレートマークアップは定義時に事前解析されキャッシュされた`cloneNode(true)`を介して適用されます。その後のプロパティおよびステートの更新は静的な3フェーズマイクロタスクフラッシュにバッチ処理されます。
フラグメントキャッシュと一括マウント
動的コンテンツの生成、内部マークアップの設定、またはコンポーネントリストのマウント時において、最大のスループットとXSS安全性を確保するために、dComponentはテンプレートキャッシュユーティリティと安全なDOM置換機能を提供します:
1const frag = dComponent.fragment('<div class="list-item"><span>title</span></div>');2dComponent.appendMany(container, frag1, frag2, '<div class="extra">item</div>');3this.setChildren('<div class="card"><span class="title"></span></div>');
レンダリング戦略と局所的更新
dComponentは仮想DOMのオーバーヘッドを回避します。DOMノードはtemplate()またはmount()で一度だけ作成され動的な更新はrender()内で局所的に適用されます。
`render()`内で`this.state`を変更してはいけません。無限更新ループを防止するため`render()`内でのステート変更はブロックされます。
バッチ化マイクロタスク更新キュー
プロパティの変更とステートの変更はすべてのアクティブコンポーネントにわたって自動的にまとめられ、静的な3フェーズマイクロタスクフラッシュに統合されます:
- フェーズ1(属性同期): 変更されたプロパティの監視対象HTML属性を同期します。
- フェーズ2(レンダリング): 一時的なレンダーリスナーをクリアし更新されたコンポーネントごとに
render()を一度実行します。 - フェーズ3(エフェクトとフォーム同期): リアクティブエフェクトを再評価しrefsキャッシュを無効化しフォーム内部を同期して集約されたdebugbarイベントを送出します。
1this.state.title = 'new title';2this.state.count = 42;
リアクティブステート
1this.setState({ active: true });2this.setState(s => { s.count++; s.updatedAt = Date.now(); });3this.setState({ timer: Date.now() }, false);
エフェクトと依存関係追跡
1this.effect(() => {2 console.log('value updated:', this.state.value);3 return () => console.log('cleaning up effect');4});5 6this.effect(() => {7 fetchData(this.query);8}, () => [this.query]);
自動クリーンアップapi
これらのメソッドはコンポーネントがDOMから削除されたときにリスナー、タイマー、およびアニメーションフレーム要求を自動的にクリーンアップします:
1const off = this.listen(element, 'click', (e) => this.handleClick(e));2off();3 4const offAll = this.listenAll(elements, 'click', (e) => this.handleClick(e));5offAll();6 7this.unlisten(element, 'click', handler);8 9this.setTimeout(() => this.tick(), 1000);10this.setInterval(() => this.refresh(), 5000);11 12this.requestAnimationFrame((time) => this.draw(time));
domキャッシュとrefs
this.refs(selector)はレンダリング間でクエリされた要素配列をキャッシュし、繰り返されるDOMクエリのオーバーヘッドを排除します:
1const [inputEl] = this.refs('input.search');
内部コンテンツの取得
template()実行前にカスタム要素に渡された元のライトDOMノードにアクセスします:
1this.originalChildren2this.originalHTML3this.cloneChildren()
フォーム統合
static form = trueの場合、dComponentは親<form>要素と統合されform: trueとマークされたプロパティを送信します:
1static form = true;2static props = {3 value: { type: 'string', default: '', form: true }4};5 6console.log(this.form);単一の値、ファイルインスタンス(File)、ファイル配列(File[])、および複数のフォームプロパティを自動的にサポートします。
独自のフォーム送信ロジック(未チェック状態のチェックボックスやラジオボタンの除外、無効化時の値のクリアなど)を実装する場合は、syncForm()をオーバーライドします:
1syncForm() {2 if (!this._internals) return;3 if (this.checked && !this.disabled) {4 this._internals.setFormValue(this.value || 'on');5 } else {6 this._internals.setFormValue(null);7 }8}
属性リフレクションとプログラムによる更新
再帰的なattributeChangedCallbackのトリガーを回避しながら安全にホストDOM要素へ属性を即時反映するには、this.reflectAttribute(name, value)を使用します:
1// ホスト要素に安全に属性を即時反映2this.reflectAttribute('placement', 'before');プロパティの更新がスクリプトやonPropChanged()を介したプログラムによる更新かどうかを判定するには、this.isProgrammaticUpdateを参照します:
1if (this.isProgrammaticUpdate) return;
内部イベントエミッター
1const off = this.on('custom-event', (data) => console.log(data));2off();3 4this.off('custom-event', handler);5 6this.emit('custom-event', { id: 123 });
websocket統合
1this.wire('chat:send', { message: 'hello' });
