# Компонент кнопки

Кнопки в основном используются для выполнения действий, таких как отправка электронных писем, публикация документов или оценка комментариев.

## Использование {#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>Атрибут</th>
    <th>Свойство</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>id</code> элемента <code>&lt;form&gt;</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>action</code> элемента <code>&lt;form&gt;</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>enctype</code> элемента <code>&lt;form&gt;</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> — данные формы добавляются к URI формы после символа <code>?</code>, и полученный URI отправляется на сервер. Используется, если форма не имеет побочных эффектов и содержит только ASCII-символы.</li>
</ul>
<p>Если это свойство задано, оно переопределяет атрибут <code>method</code> элемента <code>&lt;form&gt;</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>novalidate</code> элемента <code>&lt;form&gt;</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>target</code> элемента <code>&lt;form&gt;</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/ru/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="/ru/docs/2/styles/design-tokens#shape-corner">дизайн-токены</a>.</p>
</td>
  </tr>
</tbody>
</table>