v0.21

フロントエンドコンポーネント

dframework には、フロントエンドバンドルに自動コンパイルされる依存ゼロの高性能カスタムwebコンポーネントライブラリが標準搭載されています。仮想DOM、外部トランスパイル、ビルド手順を必要としない標準カスタム要素として実装されており、サーバー起動時に public/js/components/ 内のコンポーネントが自動的に検出・バンドルされます。

すべての組み込みコンポーネントは、英語と日本語の辞書を備えたネイティブなクライアント側ローカライズ(this.t())を標準でサポートしています。言語切り替えや文言のカスタマイズ方法については、多言語化ガイド を参照してください。

コンポーネント一覧

各コンポーネントは機能ごとに個別のドキュメントファイルに分割されており、構造、ライブ使用例、属性、プログラムAPI、イベント、キーボード操作の仕様が詳しく記載されています。

レイアウトとナビゲーション

フォームと入力

オーバーレイとフィードバック

データと表示

アクションとコントロール

組み込みコンポーネントのオーバーライド

組み込みコンポーネントのすべての動作はアプリケーションコードによってカスタマイズ、拡張、または完全に上書きできます。組み込みコンポーネントをオーバーライドするには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 `
14 <span class="label">${this.label}</span>
15 <button class="dec" type="button">−</button>
16 <span class="value">${this.value}</span>
17 <button class="inc" type="button">+</button>
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);

ライフサイクルメソッド

メソッド タイミング 説明
template() マウント前 内部DOMを構築するための初期HTML文字列を返却
mount() 初回接続時 コンポーネントロジックを初期化しエフェクトを登録
mountSync() 手動/即時 RAF遅延を待たずに即時同期マウントを実行
connected() 接続ごと 要素がドキュメントにアタッチされるたびに呼び出し
render() ステート/プロパティ変更時 局所的なDOMノード更新を実行
onPropChanged(name, old, new) プロパティ変更時 特定のプロパティの変更に反応
syncForm() フォーム/手動 ElementInternalsのフォーム値を同期(独自ルールでオーバーライド可能)
onscreen() ビューポート進入時 コンポーネントがビューポートに入ったときに呼び出し
offscreen() ビューポート退出時 コンポーネントがビューポートから出たときに呼び出し
destroy() 切断時 要素がDOMから削除されたときに呼び出される破棄フック
NOTE

`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()内で局所的に適用されます。

IMPORTANT

`render()`内で`this.state`を変更してはいけません。無限更新ループを防止するため`render()`内でのステート変更はブロックされます。

バッチ化マイクロタスク更新キュー

プロパティの変更とステートの変更はすべてのアクティブコンポーネントにわたって自動的にまとめられ、静的な3フェーズマイクロタスクフラッシュに統合されます:

  1. フェーズ1(属性同期): 変更されたプロパティの監視対象HTML属性を同期します。
  2. フェーズ2(レンダリング): 一時的なレンダーリスナーをクリアし更新されたコンポーネントごとにrender()を一度実行します。
  3. フェーズ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.originalChildren
2this.originalHTML
3this.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' });