Appearance
Overlay Scroll
오버레이 스크롤(Overlay Scroll) 컴포넌트는 기본 브라우저 스크롤바를 대체하여 사용자 정의 스크롤바를 제공하는 UI 요소입니다. 이 컴포넌트는 브라우저의 기본 스크롤 기능을 유지하면서 OS 및 브라우저 환경과 무관하게 시각적으로 일관된 사용자 경험을 제공합니다.
기본 사용법
vue
<template>
<div style="height: 300px; width: 100%;">
<OverlayScroll @scroll="handleScroll">
<div>
<!-- 스크롤 가능한 콘텐츠 -->
<p v-for="i in 20" :key="i">스크롤 콘텐츠 라인 {{ i }}</p>
</div>
</OverlayScroll>
</div>
</template>
<script setup lang="ts">
import { OverlayScroll } from '@jennifersoft/vue-components-v2';
const handleScroll = (e) => {
console.log('Scroll event:', e);
};
</script>Example
동적 콘텐츠 예시
아래 예시는 콘텐츠 양이 변경될 때 스크롤 썸(thumb)의 크기와 위치가 자동으로 조정되는 것을 보여줍니다. 버튼을 클릭하여 아이템 개수를 늘리거나 줄여보세요.
vue
<template>
<div>
<div style="margin-bottom: 16px;">
<button @click="addItems" style="margin-right: 8px;">
아이템 늘리기
</button>
<button @click="removeItems">아이템 줄이기</button>
<span style="margin-left: 16px;"
>현재 아이템 개수: {{ itemCount }}</span
>
</div>
<div
style="height: 400px; width: 100%; border: 1px solid #ddd; border-radius: 4px;"
>
<OverlayScroll>
<div style="padding: 16px;">
<p
v-for="i in itemCount"
:key="i"
style="margin-bottom: 8px;"
>
아이템 {{ i }}
</p>
</div>
</OverlayScroll>
</div>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { OverlayScroll } from '@jennifersoft/vue-components-v2';
const itemCount = ref(30);
const MIN_ITEMS = 30;
const MAX_ITEMS = 300;
const addItems = () => {
if (itemCount.value + 30 <= MAX_ITEMS) {
itemCount.value += 30;
} else {
window.alert('더이상 추가할 수 없습니다.');
}
};
const removeItems = () => {
if (itemCount.value - 30 >= MIN_ITEMS) {
itemCount.value -= 30;
} else {
window.alert('더이상 삭제할 수 없습니다.');
}
};
</script>현재 아이템 개수: 30
가로 스크롤 예시
가로 스크롤이 필요한 경우에도 OverlayScroll 컴포넌트를 활용할 수 있습니다. 컴포넌트는 자동으로 콘텐츠의 가로 너비를 감지하여 필요한 경우 가로 스크롤바를 표시합니다.
vue
<template>
<div
style="height: 200px; width: 100%; border: 1px solid #ddd; border-radius: 4px;"
>
<OverlayScroll>
<div style="padding: 16px; width: 1200px;">
<div style="display: flex; gap: 16px;">
<div
v-for="i in 10"
:key="i"
style="min-width: 100px; height: 150px; background-color: #f0f0f0; border-radius: 4px; display: flex; justify-content: center; align-items: center;"
>
항목 {{ i }}
</div>
</div>
</div>
</OverlayScroll>
</div>
</template>
<script setup lang="ts">
import { OverlayScroll } from '@jennifersoft/vue-components-v2';
</script>동작 원리
오버레이 스크롤 컴포넌트는 다음과 같은 방식으로 동작합니다:
- 실제 스크롤은 브라우저의 기본 스크롤 메커니즘을 사용합니다.
- 기본 스크롤바는 CSS를 통해 시각적으로 숨겨집니다.
- 사용자 정의 스크롤 트랙과 썸(thumb)이 오버레이로 표시됩니다.
- 스크롤 이벤트가 발생하면 사용자 정의 썸의 위치가 실제 스크롤 위치에 맞게 업데이트됩니다.
- ResizeObserver를 사용하여 콘텐츠 크기 변경을 감지하고 썸 크기와 위치를 자동으로 조정합니다.
구성 요소
컴포넌트는 다음과 같은 주요 요소로 구성됩니다:
- 스크롤 래퍼(Wrapper): 전체 컴포넌트를 감싸는 컨테이너
- 스크롤 트랙(Track): 사용자 정의 스크롤바가 움직이는 영역
- 스크롤 썸(Thumb): 사용자가 볼 수 있는 스크롤바 핸들
- 스크롤 박스(Box): 실제 스크롤이 적용되는 영역
- 스크롤 콘텐츠(Content): 사용자가 제공하는 실제 콘텐츠가 들어가는 영역
Events
| 이벤트 이름 | 파라미터 | 설명 |
|---|---|---|
| scroll | event: Event | 스크롤이 발생했을 때 트리거됨. 네이티브 이벤트 그대로 전파 |
스타일링
오버레이 스크롤 컴포넌트는 다음과 같은 CSS 클래스를 사용합니다:
.js-overlay-scroll-wrapper: 전체 컴포넌트 래퍼.js-overlay-scroll-track: 스크롤 트랙.js-overlay-scroll-thumb: 스크롤 썸(핸들).js-overlay-scroll-box: 스크롤 박스.js-overlay-scroll-content: 스크롤 콘텐츠
마우스 인터랙션
오버레이 스크롤 컴포넌트는 다음과 같은 마우스 관련 기능을 제공합니다:
스크롤 썸 드래그: 사용자는 스크롤 썸(thumb)을 클릭한 상태로 드래그하여 스크롤 위치를 조정할 수 있습니다.
스크롤 트랙 클릭: 사용자가 스크롤 트랙을 클릭하면 클릭한 위치에 따라 페이지 단위로 스크롤됩니다.
주의사항
- 컴포넌트가 제대로 작동하려면 부모 요소에 명시적인 높이가 지정되어야 합니다.
- 스크롤 콘텐츠의 높이가 스크롤 박스보다 클 때만 스크롤바가 표시됩니다.
- 스크롤 이벤트는 성능을 위해
requestAnimationFrame을 사용하여 최적화되어 있습니다.