# 버튼 컴포넌트 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>: 시각적 강조 효과가 높으며 &quot;저장&quot;, &quot;확인&quot; 등 중요 프로세스의 최종 작업에 적합합니다.</li>
<li><code>tonal</code>: <code>filled</code>와 <code>outlined</code>의 중간 정도 시각적 강조 효과를 가지며, 프로세스 중 &quot;다음&quot;과 같은 중간~높은 우선순위 작업에 적합합니다.</li>
<li><code>outlined</code>: 테두리가 있는 버튼으로, &quot;뒤로&quot;와 같이 중간 우선순위이면서 보조적인 작업에 적합합니다.</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에 추가되어 서버로 전송됩니다. 폼에 부작용이 없고 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>폼 유효성 검사 상태 객체입니다. 자세한 내용은 <a href="https://developer.mozilla.org/ko/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="/ko/docs/2/styles/design-tokens#shape-corner">디자인 토큰</a>을 참조하는 것을 권장합니다.</p>
</td>
  </tr>
</tbody>
</table>