Быстрый старт
Компоненты mdui — это стандартные веб-компоненты (Web Components). Вы можете использовать их как обычные теги <div>. В документации каждого компонента подробно описан его полный API, включая атрибуты, методы, события, слоты, CSS Part и пользовательские CSS-свойства.
Эта глава познакомит вас с основами использования 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' как булево 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' эквивалентна булеву false
button.setAttribute('disabled', 'false'); // эквивалентно button.disabled = false;
</script>
Иногда значения атрибутов могут быть массивами, объектами или функциями. В этом случае существует только JavaScript-свойство, и соответствующего HTML-атрибута нет. Например, у компонента <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-свойство.
Методы
Некоторые компоненты предоставляют публичные методы. Вы можете вызывать их для реализации различных функций. Например, метод focus() компонента <mdui-text-field> устанавливает фокус на текстовое поле.
<mdui-text-field></mdui-text-field>
<script>
const textField = document.querySelector('mdui-text-field');
textField.focus();
</script>
Все доступные методы и их параметры можно посмотреть на странице документации каждого компонента.
События
Некоторые компоненты генерируют события при выполнении определённых действий. Например, компонент <mdui-dialog> генерирует событие open при открытии. Вы можете прослушивать это событие для выполнения пользовательских действий.
<mdui-dialog>Диалог</mdui-dialog>
<script>
const dialog = document.querySelector('mdui-dialog');
dialog.addEventListener('open', () => {
console.log('Событие генерируется при начале открытия диалога');
});
</script>
Список всех доступных событий и их параметров можно посмотреть на странице документации каждого компонента.
Если вы используете mdui в других фреймворках (например, Vue, React, Angular), вы можете использовать синтаксис фреймворка для привязки событий. Однако некоторые фреймворки (например, React) поддерживают привязку только стандартных событий (например, click), но не пользовательских (например, open). Поэтому в React для привязки пользовательских событий необходимо получить ссылку на элемент и использовать метод addEventListener.
Дополнительную информацию об использовании mdui с React см. в разделе Интеграция с фреймворками - React.
Слоты (Slot)
Многие компоненты предоставляют слоты для вставки пользовательского HTML-содержимого внутрь компонента.
Самый распространённый — это слот по умолчанию (default slot), который представляет собой обычный HTML или текст внутри компонента. Например, слот по умолчанию компонента <mdui-button> используется для установки текста кнопки. В примере "Нажми меня" — это содержимое слота по умолчанию:
<mdui-button>Нажми меня</mdui-button>
Некоторые компоненты также предоставляют именованные слоты. Для именованного слота необходимо указать атрибут slot с именем слота. В следующем примере компонент <mdui-icon> указывает slot="start", что означает использование именованного слота start, который вставит иконку внутрь компонента слева:
<mdui-button>
<mdui-icon slot="start" name="settings"></mdui-icon>
Настройки
</mdui-button>
Если компонент использует несколько именованных слотов, порядок их следования не важен, браузер автоматически разместит их в нужных местах.
Список всех поддерживаемых слотов можно посмотреть на странице документации каждого компонента.
Пользовательские CSS-свойства
Пользовательские CSS-свойства — это переменные в CSS. mdui определяет ряд глобальных пользовательских 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-свойства в локальной области видимости. Например, следующий код уменьшит скругление углов только внутри элемента с классом 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. Например, следующий код изменяет свойство --z-index компонента <mdui-dialog>, чтобы изменить его z-index:
mdui-dialog {
--z-index: 3000;
}
Список поддерживаемых пользовательских CSS-свойств для каждого компонента можно посмотреть на его странице документации.
CSS Part
Компоненты mdui используют Shadow DOM для изоляции стилей и поведения. Обычные CSS-селекторы не могут выбирать элементы внутри Shadow DOM. Поэтому некоторые компоненты добавляют атрибут part к элементам в Shadow DOM. Вы можете использовать CSS-селектор ::part для выбора этих элементов и переопределения их стилей.
Например, следующий код использует part button для изменения внутренних отступов кнопки, а также part label, icon, end-icon для изменения цвета текста, левой и правой иконок соответственно:
<mdui-button class="custom-button" icon="explore" end-icon="flight">Кнопка</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.
В следующем примере мы устанавливаем JavaScript-свойство disabled кнопки в true, а затем сразу проверяем HTML-атрибут. Но поскольку перерисовка ещё не произошла, полученный HTML-атрибут всё ещё false:
const button = document.querySelector('mdui-button');
button.disabled = true;
console.log(button.hasAttribute('disabled')); // false
Чтобы дождаться завершения перерисовки после изменения свойства, можно использовать свойство updateComplete компонента. Это свойство возвращает Promise, который разрешается (resolve) после того, как компонент завершит перерисовку:
const button = document.querySelector('mdui-button');
button.disabled = true;
button.updateComplete.then(() => {
console.log(button.hasAttribute('disabled')); // true
});