빠른 시작
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>
일부 속성값은 불리언 타입입니다. 이러한 속성의 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 프로퍼티만 있습니다.
메서드
일부 컴포넌트는 공개 메서드를 제공하며, 이 메서드를 호출하여 다양한 기능을 구현할 수 있습니다. 예를 들어 <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>대화상자</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
});