# ボタンコンポーネント Button

ボタンは主に、メールの送信、ドキュメントの共有、コメントの「いいね！」など、いくつかの操作を実行するために使用されます。

## 使用方法 {#usage}

コンポーネントを必要に応じてインポートします：

```js
import 'mdui/components/button.js';
```

コンポーネントの TypeScript 型を必要に応じてインポートします：

```ts
import type { Button } from 'mdui/components/button.js';
```

使用例：

```html
<mdui-button>Button</mdui-button>
```

## 例 {#examples}

### 形状 {#example-variant}

`variant` 属性を使用してボタンの形状を設定します。

```html
<mdui-button variant="elevated">Elevated</mdui-button>
<mdui-button variant="filled">Filled</mdui-button>
<mdui-button variant="tonal">Tonal</mdui-button>
<mdui-button variant="outlined">Outlined</mdui-button>
<mdui-button variant="text">Text</mdui-button>
```

### 全幅 {#example-full-width}

`full-width` 属性を追加すると、ボタンが親要素の全幅を占めるようにできます。

```html
<mdui-button full-width>Button</mdui-button>
```

### アイコン {#example-icon}

`icon`、`end-icon` 属性を設定すると、ボタンの左側、右側にそれぞれ Material Icons アイコンを追加できます。`icon`、`end-icon` スロットを通じてボタンの左側、右側に要素を追加することもできます。

```html
<mdui-button icon="search" end-icon="arrow_forward">Icon</mdui-button>
<mdui-button>
  Slot
  <mdui-icon slot="icon" name="downloading"></mdui-icon>
  <mdui-icon slot="end-icon" name="attach_file"></mdui-icon>
</mdui-button>
```

### リンク {#example-link}

`href` 属性を設定すると、ボタンをリンクにできます。この場合、リンク関連の属性 `download`、`target`、`rel` も使用できます。

```html
<mdui-button href="https://www.mdui.org" target="_blank">Link</mdui-button>
```

### 無効およびローディング状態 {#example-disabled}

`disabled` 属性を追加するとボタンを無効にできます；`loading` 属性を追加するとボタンにローディング状態を追加できます。

```html
<mdui-button disabled>Disabled</mdui-button>
<mdui-button loading>Loading</mdui-button>
<mdui-button loading disabled>Loading & Disabled</mdui-button>
```

## mdui-button API

### プロパティ

<table>
<thead>
  <tr>
    <th>HTML 属性</th>
    <th>JavaScript プロパティ</th>
    <th>Reflect</th>
    <th>型</th>
    <th>デフォルト値</th>
    <th>説明</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>variant</td>
    <td>variant</td>
    <td>true</td>
    <td>&#39;elevated&#39; | &#39;filled&#39; | &#39;tonal&#39; | &#39;outlined&#39; | &#39;text&#39;</td>
    <td>'filled'</td>
    <td><p>ボタンの形状です。次の値を指定します：</p>
<ul>
<li><code>elevated</code>：影付きボタン。ボタンを背景から視覚的に分離したい場合に適しています。</li>
<li><code>filled</code>：視覚的な強調度が高く、「保存」や「確認」など、重要なフローの最終操作に適しています。</li>
<li><code>tonal</code>：<code>filled</code> と <code>outlined</code> の中間の視覚的強調度です。フロー中の「次へ」など、中～高優先度の操作に適しています。</li>
<li><code>outlined</code>：枠線付きボタン。「戻る」など、中優先度で二次的な操作に適しています。</li>
<li><code>text</code>：テキストボタン。最も低い優先度の操作に適しています。</li>
</ul>
</td>
  </tr>
  <tr>
    <td>full-width</td>
    <td>fullWidth</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>親要素の幅いっぱいに広げるかどうかを指定します。</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>左側に表示するMaterial Iconsのアイコン名です。<code>slot=&quot;icon&quot;</code> で設定することもできます。</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td>endIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>右側に表示するMaterial Iconsのアイコン名です。<code>slot=&quot;end-icon&quot;</code> で設定することもできます。</p>
</td>
  </tr>
  <tr>
    <td>href</td>
    <td>href</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>リンク先のURLです。</p>
<p>この属性を設定すると、コンポーネント内部は <code>&lt;a&gt;</code> 要素としてレンダリングされ、リンク関連の属性が使用可能になります。</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>ダウンロードリンクの対象ファイル名です。</p>
<p><strong>注</strong>：<code>href</code> 属性が設定されている場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>target</td>
    <td>target</td>
    <td>true</td>
    <td>&#39;_blank&#39; | &#39;_parent&#39; | &#39;_self&#39; | &#39;_top&#39;</td>
    <td></td>
    <td><p>リンクの開き方です。次の値を指定します：</p>
<ul>
<li><code>_blank</code>：新しいウィンドウで開く</li>
<li><code>_parent</code>：親フレームで開く</li>
<li><code>_self</code>：デフォルト。現在のフレームで開く</li>
<li><code>_top</code>：最上位のウィンドウで開く</li>
</ul>
<p><strong>注</strong>：<code>href</code> 属性が設定されている場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>rel</td>
    <td>rel</td>
    <td>true</td>
    <td>&#39;alternate&#39; | &#39;author&#39; | &#39;bookmark&#39; | &#39;external&#39; | &#39;help&#39; | &#39;license&#39; | &#39;me&#39; | &#39;next&#39; | &#39;nofollow&#39; | &#39;noreferrer&#39; | &#39;opener&#39; | &#39;prev&#39; | &#39;search&#39; | &#39;tag&#39;</td>
    <td></td>
    <td><p>現在のドキュメントとリンク先ドキュメントの関係です。次の値を指定します：</p>
<ul>
<li><code>alternate</code>：現在のドキュメントの代替バージョン</li>
<li><code>author</code>：現在のドキュメントまたは記事の作成者</li>
<li><code>bookmark</code>：直近の祖先セクションへのパーマリンク</li>
<li><code>external</code>：参照先ドキュメントが現在のサイトとは異なるサイトにあることを示します</li>
<li><code>help</code>：関連するヘルプドキュメントへのリンク</li>
<li><code>license</code>：現在のドキュメントのメインコンテンツが、参照先ファイルの著作権ライセンスの対象であることを示します</li>
<li><code>me</code>：現在のドキュメントがリンク先コンテンツの所有者を表します</li>
<li><code>next</code>：現在のドキュメントがシリーズの一部であり、参照先ドキュメントがシリーズの次のドキュメントです</li>
<li><code>nofollow</code>：現在のドキュメントの作成者または発行者が、参照先ファイルを推奨していないことを示します</li>
<li><code>noreferrer</code>：<code>Referer</code> ヘッダーを含めません。<code>noopener</code> と同様の効果です</li>
<li><code>opener</code>：ハイパーリンクが最上位のブラウジングコンテキストを作成する場合（つまり <code>target</code> 属性値が <code>_blank</code>）、補助ブラウジングコンテキストを作成します</li>
<li><code>prev</code>：現在のドキュメントがシリーズの一部であり、参照先ドキュメントがシリーズの前のドキュメントです</li>
<li><code>search</code>：現在のファイルとその関連ページを検索するために使用できるリソースへのリンクを提供します</li>
<li><code>tag</code>：現在のドキュメントに適用されるタグ（指定されたアドレスで識別される）を提供します</li>
</ul>
<p><strong>注</strong>：<code>href</code> 属性が指定されている場合にのみ使用できます。</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>ページ読み込み完了後、自動的にフォーカスを取得するかどうかを指定します。</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>Tab キーによるフォーカス移動時の、要素の順序を指定します。</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>無効状態にするかどうかを指定します。</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td>loading</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>読み込み中状態にするかどうかを指定します。</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>ボタンの名前です。フォームデータと共に送信されます。</p>
<p><strong>注</strong>：<code>href</code> 属性が設定されていない場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>ボタンの初期値です。フォームデータと共に送信されます。</p>
<p><strong>注</strong>：<code>href</code> 属性が設定されていない場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>type</td>
    <td>type</td>
    <td>true</td>
    <td>&#39;submit&#39; | &#39;reset&#39; | &#39;button&#39;</td>
    <td>'button'</td>
    <td><p>ボタンのタイプです。デフォルトのタイプは <code>button</code> です。次のタイプを指定します：</p>
<ul>
<li><code>submit</code>：ボタンをクリックするとフォームデータがサーバーに送信されます</li>
<li><code>reset</code>：ボタンをクリックするとフォーム内のすべてのフィールドが初期値にリセットされます</li>
<li><code>button</code>：このタイプのボタンにはデフォルトの動作はありません</li>
</ul>
<p><strong>注</strong>：<code>href</code> 属性が指定されていない場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>関連付ける <code>&lt;form&gt;</code> 要素です。この属性値には、同一ページ内の <code>&lt;form&gt;</code> 要素の <code>id</code> を指定する必要があります。</p>
<p>この属性が指定されていない場合、この要素は <code>&lt;form&gt;</code> 要素の子要素である必要があります。この属性を使用すると、要素を <code>&lt;form&gt;</code> 要素の子要素だけでなく、ページ上の任意の場所に配置できます。</p>
<p><strong>注</strong>：<code>href</code> 属性が指定されていない場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>formaction</td>
    <td>formAction</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>フォーム送信先のURLを指定します。</p>
<p>この属性が指定されている場合、<code>&lt;form&gt;</code> 要素の <code>action</code> 属性は上書きされます。</p>
<p><strong>注</strong>：<code>href</code> 属性が指定されておらず、かつ <code>type=&quot;submit&quot;</code> の場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>formenctype</td>
    <td>formEnctype</td>
    <td>true</td>
    <td>&#39;application/x-www-form-urlencoded&#39; | &#39;multipart/form-data&#39; | &#39;text/plain&#39;</td>
    <td></td>
    <td><p>サーバーにフォームを送信する際のコンテンツタイプを指定します。次の値を指定します：</p>
<ul>
<li><code>application/x-www-form-urlencoded</code>：この属性が指定されていない場合のデフォルト値</li>
<li><code>multipart/form-data</code>：フォームに <code>&lt;input type=&quot;file&quot;&gt;</code> 要素が含まれる場合に使用します</li>
<li><code>text/plain</code>：HTML5で追加された、デバッグ用</li>
</ul>
<p>この属性が指定されている場合、<code>&lt;form&gt;</code> 要素の <code>enctype</code> 属性は上書きされます。</p>
<p><strong>注</strong>：<code>href</code> 属性が指定されておらず、かつ <code>type=&quot;submit&quot;</code> の場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>formmethod</td>
    <td>formMethod</td>
    <td>true</td>
    <td>&#39;post&#39; | &#39;get&#39;</td>
    <td></td>
    <td><p>フォーム送信時に使用するHTTPメソッドを指定します。次の値を指定します：</p>
<ul>
<li><code>post</code>：フォームデータはフォームコンテンツに含まれてサーバーに送信されます</li>
<li><code>get</code>：フォームデータは <code>?</code> 区切りでフォームのURI属性に追加され、生成されたURIがサーバーに送信されます。フォームに副作用がなく、ASCII文字のみを含む場合にこのメソッドを使用します</li>
</ul>
<p>この属性が設定されている場合、<code>&lt;form&gt;</code> 要素の <code>method</code> 属性は上書きされます。</p>
<p><strong>注</strong>：<code>href</code> 属性が設定されておらず、かつ <code>type=&quot;submit&quot;</code> の場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>formnovalidate</td>
    <td>formNoValidate</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>この属性が設定されている場合、フォーム送信時にフォーム検証は実行されません。</p>
<p>この属性が設定されている場合、<code>&lt;form&gt;</code> 要素の <code>novalidate</code> 属性は上書きされます。</p>
<p><strong>注</strong>：<code>href</code> 属性が設定されておらず、かつ <code>type=&quot;submit&quot;</code> の場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>formtarget</td>
    <td>formTarget</td>
    <td>true</td>
    <td>&#39;_self&#39; | &#39;_blank&#39; | &#39;_parent&#39; | &#39;_top&#39;</td>
    <td></td>
    <td><p>フォーム送信後に受信したレスポンスを表示する場所を指定します。次の値を指定します：</p>
<ul>
<li><code>_self</code>：デフォルトのオプション。現在のフレームで開きます</li>
<li><code>_blank</code>：新しいウィンドウで開きます</li>
<li><code>_parent</code>：親フレームで開きます</li>
<li><code>_top</code>：最上位のウィンドウで開きます</li>
</ul>
<p>この属性が設定されている場合、<code>&lt;form&gt;</code> 要素の <code>target</code> 属性は上書きされます。</p>
<p><strong>注</strong>：<code>href</code> 属性が設定されておらず、かつ <code>type=&quot;submit&quot;</code> の場合にのみ有効です。</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validity</td>
    <td>false</td>
    <td>ValidityState</td>
    <td></td>
    <td><p>フォーム検証ステータスを表す <code>ValidityState</code> オブジェクトです。詳細は <a href="https://developer.mozilla.org/ja/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a> を参照してください。</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>フォーム検証に合格しなかった場合、このプロパティにはエラーメッセージが設定されます。検証に合格した場合は空の文字列になります。</p>
</td>
  </tr>
</tbody>
</table>

### メソッド

<table>
<thead>
  <tr>
    <th>名前</th>
    <th>説明</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>要素のマウスクリックをシミュレートします。</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>現在の要素にフォーカスを設定します。</p>
<p>オプションとして、以下のプロパティを持つオブジェクトを渡すことができます：</p>
<ul>
<li><code>preventScroll</code>：デフォルトでは、要素がフォーカスを取得すると、その要素がビュー内に表示されるようにページがスクロールします。ページのスクロールを防ぐには、このプロパティを <code>true</code> に設定します。</li>
</ul>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>現在の要素からフォーカスを外します。</p>
</td>
  </tr>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>フォームフィールドが検証に合格するかどうかをチェックします。合格しない場合は <code>false</code> を返し、<code>invalid</code> イベントをトリガーします。合格した場合は <code>true</code> を返します。</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>フォームフィールドが検証に合格するかどうかをチェックします。合格しない場合は <code>false</code> を返し、<code>invalid</code> イベントをトリガーします。合格した場合は <code>true</code> を返します。</p>
<p>検証に合格しなかった場合は、コンポーネントに検証失敗のエラーメッセージも表示されます。</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>カスタムのエラーメッセージを設定します。このテキストが空でない限り、フィールドが検証に合格していないと見なされます。</p>
</td>
  </tr>
</tbody>
</table>

### イベント

<table>
<thead>
  <tr>
    <th>名前</th>
    <th>説明</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>フォーカスを取得したときに発生します。</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>フォーカスを失ったときに発生します。</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>フォームフィールドの検証に合格しなかったときに発生します。</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>名前</th>
    <th>説明</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>デフォルト</td>
    <td><p>ボタンのテキスト</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>ボタン左側の要素</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>ボタン右側の要素</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>名前</th>
    <th>説明</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>button</td>
    <td><p>内部の <code>&lt;button&gt;</code> または <code>&lt;a&gt;</code> 要素</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>ボタンのテキスト</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>ボタン左側のアイコン</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>ボタン右側のアイコン</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td><p>読み込み中状態の <code>&lt;mdui-circular-progress&gt;</code> 要素</p>
</td>
  </tr>
</tbody>
</table>

### CSS カスタムプロパティ

<table>
<thead>
  <tr>
    <th>名前</th>
    <th>説明</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>コンポーネントの角丸のサイズ。ピクセル値で直接指定できますが、<a href="/ja/docs/2/styles/design-tokens#shape-corner">デザイントークン</a>を参照することをお勧めします。</p>
</td>
  </tr>
</tbody>
</table>