クイックスタート
mdui のコンポーネントはすべて標準の Web Components です。<div> タグと同じように mdui コンポーネントを使用できます。各コンポーネントのドキュメントには、属性、メソッド、イベント、スロット、CSS Part、CSS カスタムプロパティなど、完全な API が詳しく記載されています。
この章では、Web Components の使用方法を紹介します。
属性
属性には HTML 属性と JavaScript プロパティがあり、通常は一対一に対応し、同期されます。つまり、HTML 属性の値を更新すると JavaScript プロパティの値も更新され、その逆も同様です。
HTML 属性はコンポーネントの HTML 文字列で直接設定でき、getAttribute メソッドと setAttribute メソッドで読み書きできます：
<mdui-button variant="text">クリック</mdui-button>
<script>
const button = document.querySelector('mdui-button');
// HTML 属性を変更
button.setAttribute('variant', 'outlined');
// HTML 属性を読み取り
console.log(button.getAttribute('variant')); // outlined
</script>
JavaScript プロパティは、コンポーネントインスタンスのプロパティ値を直接読み書きできます：
<mdui-button variant="text">クリック</mdui-button>
<script>
const button = document.querySelector('mdui-button');
// JavaScript プロパティを設定
button.variant = 'outlined';
// JavaScript プロパティを読み取り
console.log(button.variant); // outlined
</script>
一部のプロパティの値は boolean 型です。これらのプロパティの HTML 属性が存在する場合は JavaScript プロパティが true になり、存在しない場合は false になります。ただし、一部のフレームワークとの互換性のため、mdui は文字列の false 値も boolean 値の false と判定します。
<!-- このコンポーネントには disabled 属性が存在するため、デフォルトの disabled プロパティ値は true です -->
<mdui-button disabled></mdui-button>
<script>
const button = document.querySelector('mdui-button');
button.removeAttribute('disabled'); // button.disabled = false; と同等
button.setAttribute('disabled', ''); // button.disabled = true; と同等
// 例外：文字列の 'false' 値を設定すると、boolean 値の false を設定するのと同等になります
button.setAttribute('disabled', 'false'); // button.disabled = false; と同等
</script>
属性値が配列、オブジェクト、または関数の場合、対応する HTML 属性はなく、JavaScript プロパティのみが存在します。例えば、<mdui-slider> コンポーネントの labelFormatter プロパティは関数であり、このプロパティは JavaScript でのみ設定できます：
<mdui-slider></mdui-slider>
<script>
const slider = document.querySelector('mdui-slider');
slider.labelFormatter = (value) => `${value}%`;
</script>
以下、<mdui-slider> コンポーネントの属性ドキュメントの一部を例に説明します：
| HTML 属性 | JavaScript プロパティ | reflect |
|---|---|---|
name |
name |
|
value |
value |
|
labelFormatter |
このコンポーネントの name 属性には HTML 属性と JavaScript プロパティがあり、reflect 欄は JavaScript プロパティを更新すると HTML 属性も同期更新されることを示しています。value プロパティは JavaScript プロパティを更新しても HTML 属性は更新されません。labelFormatter プロパティは JavaScript プロパティのみです。
メソッド
一部のコンポーネントはパブリックメソッドを提供しており、これらのメソッドを呼び出すことでさまざまな機能を実現できます。例えば、<mdui-text-field> コンポーネントの focus() メソッドは、テキストフィールドにフォーカスを当てることができます。
<mdui-text-field></mdui-text-field>
<script>
const textField = document.querySelector('mdui-text-field');
textField.focus();
</script>
各コンポーネントのドキュメントページで、使用可能なすべてのメソッドとそのパラメーターを確認できます。
イベント
一部のコンポーネントは、特定の操作を実行したときにイベントを発火させます。例えば、<mdui-dialog> コンポーネントは開くときに open イベントを発火させます。このイベントをリッスンしてカスタム操作を実行できます。
<mdui-dialog>Dialog</mdui-dialog>
<script>
const dialog = document.querySelector('mdui-dialog');
dialog.addEventListener('open', () => {
console.log('ダイアログが開き始めるときに、このイベントが発生します');
});
</script>
各コンポーネントのドキュメントページで、使用可能なすべてのイベントとそのパラメーターを確認できます。
Vue、React、Angular などの他のフレームワークで mdui を使用する場合、そのフレームワークが提供する構文を使用してイベントをバインドできます。ただし、React などの一部のフレームワークのイベントバインディング構文は標準イベント（click イベントなど）のバインディングにしか使用できず、カスタムイベント（open イベントなど）のバインディングには使用できません。したがって、React でカスタムイベントをバインドするには、まず要素の参照を取得し、addEventListener メソッドを使用してイベントをバインドする必要があります。
React で mdui を使用する詳細については、フレームワーク連携 - React を参照してください。
スロット
多くのコンポーネントはスロットを提供しており、カスタムの HTML コンテンツをコンポーネント内部に挿入できます。
最も一般的なのはデフォルトスロットで、コンポーネント内部の通常の HTML またはプレーンテキストです。例えば、<mdui-button> コンポーネントのデフォルトスロットはボタンのテキストを設定します。例の「クリック」がデフォルトスロットの内容です：
<mdui-button>クリック</mdui-button>
一部のコンポーネントは名前付きスロットも提供しています。名前付きスロットを使用するには、HTML の slot 属性でスロット名を指定する必要があります。次の例では、<mdui-icon> コンポーネントが slot="start" を指定しています。これは start という名前の名前付きスロットであり、このアイコンがコンポーネント内部の左側に挿入されることを意味します：
<mdui-button>
<mdui-icon slot="start" name="settings"></mdui-icon>
設定
</mdui-button>
コンポーネントが複数の名前付きスロットを使用する場合、各名前付きスロットの順序は重要ではありません。それらがコンポーネント内部にあれば、ブラウザは自動的にそれらを正しい位置に配置します。
各コンポーネントのドキュメントページで、サポートされているすべてのスロットを確認できます。
CSS カスタムプロパティ
CSS カスタムプロパティは CSS 内の変数です。mdui は一連のグローバル CSS カスタムプロパティを定義しており、これらのプロパティは各コンポーネント内部で使用されています。したがって、これらの CSS カスタムプロパティを変更することで、mdui コンポーネントのスタイルをグローバルに変更できます。
例えば、以下のコードはすべてのコンポーネントの角丸のサイズを小さくします：
:root {
--mdui-shape-corner-extra-small: 0.125rem;
--mdui-shape-corner-small: 0.25rem;
--mdui-shape-corner-medium: 0.375rem;
--mdui-shape-corner-large: 0.5rem;
--mdui-shape-corner-extra-large: 0.875rem;
}
また、ローカルスコープで CSS カスタムプロパティを変更することもできます。例えば、以下のコードは class="sharp" を含む要素とその子要素内でのみ角丸のサイズを小さくします：
.sharp {
--mdui-shape-corner-extra-small: 0.125rem;
--mdui-shape-corner-small: 0.25rem;
--mdui-shape-corner-medium: 0.375rem;
--mdui-shape-corner-large: 0.5rem;
--mdui-shape-corner-extra-large: 0.875rem;
}
一部のコンポーネントは、そのコンポーネント固有の CSS カスタムプロパティも提供しています。これらのプロパティのスコープは特定のコンポーネントであるため、--mdui プレフィックスは含まれません。例えば、以下のコードは <mdui-dialog> コンポーネントの --z-index プロパティを変更することで、z-index スタイルを変更します：
mdui-dialog {
--z-index: 3000;
}
各コンポーネントのドキュメントページで、コンポーネントがサポートする CSS カスタムプロパティを確認できます。
CSS Part
mdui コンポーネントは Shadow DOM を使用してスタイルと動作をカプセル化していますが、通常の CSS セレクターでは Shadow DOM 内部の要素を選択できません。そのため、一部のコンポーネントは Shadow DOM 要素に part 属性を追加しており、::part CSS セレクターを使用して対応する要素を選択し、スタイルの一部を上書きできます。
例えば、以下のコードは button part を使用してボタンの内側のパディングを変更し、label、icon、end-icon part を使用してテキストと左右のアイコンの色をそれぞれ変更しています：
<mdui-button class="custom-button" icon="explore" end-icon="flight">Button</mdui-button>
<style>
.custom-button::part(button) {
padding: 0 2rem;
}
.custom-button::part(label) {
color: blue;
}
.custom-button::part(icon) {
color: red;
}
.custom-button::part(end-icon) {
color: yellow;
}
</style>コンポーネントの Shadow DOM 要素の構造とデフォルトのスタイルについては、ブラウザの開発者ツールを開いて確認できます。
CSS Part を使用する前に、まずグローバル CSS カスタムプロパティやコンポーネント固有の CSS カスタムプロパティを使用することでニーズを満たせるかどうかを判断してください。満たせる場合は、CSS カスタムプロパティを優先してスタイルをカスタマイズすることをお勧めします。
各コンポーネントのドキュメントページで、コンポーネントが公開するすべての part 属性を確認できます。
コンポーネントの更新メカニズム
mdui コンポーネントは Lit をベースに開発されています。Lit は軽量なライブラリで、Web Components の開発をより簡単にします。mdui コンポーネントを使用する際には、そのレンダリングと更新のメカニズムを理解しておく必要があるかもしれません。
mdui コンポーネントのプロパティを変更すると、コンポーネントは再レンダリングされます。ただし、この再レンダリングプロセスは同期的に実行されるわけではありません。複数のプロパティ値を同時に変更した場合、Lit はこれらの変更をキャッシュし、次の更新サイクルまで保持します。これにより、プロパティ値を何回変更しても、各コンポーネントは一度だけ再レンダリングされます。また、Shadow DOM 内で実際に変更された部分のみが再レンダリングされます。
以下の例では、ボタンの disabled JavaScript プロパティの値を true に設定し、すぐにその HTML 属性をクエリしています。しかし、この時点ではコンポーネントがまだ再レンダリングされていないため、クエリされる HTML 属性は依然として false です：
const button = document.querySelector('mdui-button');
button.disabled = true;
console.log(button.hasAttribute('disabled')); // false
プロパティ値の変更後の再レンダリングが完了するのを待つには、コンポーネントの updateComplete プロパティを使用できます。このプロパティは Promise を返し、Promise が resolve された時点でコンポーネントの再レンダリングが完了したことを示します：
const button = document.querySelector('mdui-button');
button.disabled = true;
button.updateComplete.then(() => {
console.log(button.hasAttribute('disabled')); // true
});