9.3 KiB
9.3 KiB
sirsoft-admin_basic 핸들러
템플릿 식별자:
sirsoft-admin_basic(type: admin) 관련 문서: 액션 핸들러 개요 | 컴포넌트 | 레이아웃
TL;DR (5초 요약)
1. setLocale: 앱 언어 변경 (locale 파라미터)
2. setTheme/initTheme: 다크/라이트 모드 전환 및 초기화
3. scrollToSection: 특정 섹션으로 스크롤 이동 (offset 지원)
4. initMenuFromUrl: URL 기반 메뉴 활성 상태 초기화
5. filterVisibility 4종: 필터 패널 가시성 저장/토글/초기화
6. multilingualTag 3종: 다국어 태그 저장/취소/업데이트
목차
setLocale
앱 언어를 변경합니다. 번역 파일을 다시 로드하고 UI를 갱신합니다.
소스: src/handlers/setLocaleHandler.ts
{
"type": "click",
"handler": "setLocale",
"params": {
"locale": "en"
}
}
params
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
locale |
string | ✅ | 변경할 로케일 코드 (예: "ko", "en", "ja") |
동작
1. 로케일 변경 → 번역 파일 다시 로드
2. _global.locale 자동 업데이트
3. 모든 $t: 표현식 재평가
사용 예시
{
"id": "lang_en_btn",
"type": "basic",
"name": "Button",
"props": {
"text": "English"
},
"actions": [
{
"type": "click",
"handler": "setLocale",
"params": {
"locale": "en"
}
}
]
}
setTheme / initTheme
setTheme
다크/라이트 모드를 전환합니다.
소스: src/handlers/setThemeHandler.ts
{
"type": "click",
"handler": "setTheme",
"params": {
"theme": "dark"
}
}
setTheme params
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
theme |
string | ✅ | "light", "dark", "auto" (시스템 설정 따름) |
동작
1. localStorage에 테마 설정 저장
2. document.documentElement에 class 적용 (dark/light)
3. Tailwind dark: variant 활성화/비활성화
initTheme
앱 시작 시 저장된 테마 설정을 적용합니다. 주로 init_actions에서 사용합니다.
{
"init_actions": [
{
"handler": "initTheme"
}
]
}
params 없이 호출합니다. localStorage에 저장된 테마 설정을 복원합니다.
사용 예시
{
"id": "theme_toggle",
"type": "composite",
"name": "ThemeToggle",
"actions": [
{
"type": "click",
"handler": "setTheme",
"params": {
"theme": "{{_global.theme === 'dark' ? 'light' : 'dark'}}"
}
}
]
}
scrollToSection
특정 섹션으로 스크롤합니다. 오프셋 지원에 특화되어 있습니다.
소스: src/handlers/scrollToSectionHandler.ts
{
"type": "click",
"handler": "scrollToSection",
"params": {
"selector": "#features",
"offset": -80
}
}
params
| 필드 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
selector |
string | ✅ | - | CSS 선택자 (예: "#section-id", ".class-name") |
offset |
number | ❌ | 0 |
스크롤 오프셋 (음수: 위로, 양수: 아래로). 고정 헤더 높이 보상에 사용 |
동작
1. document.querySelector(selector)로 대상 요소 검색
2. 요소의 위치 계산 + offset 적용
3. window.scrollTo({ top, behavior: 'smooth' })로 부드러운 스크롤
사용 예시
{
"id": "nav_features",
"type": "basic",
"name": "A",
"props": {
"text": "$t:common.features",
"className": "cursor-pointer"
},
"actions": [
{
"type": "click",
"handler": "scrollToSection",
"params": {
"selector": "#features",
"offset": -80
}
}
]
}
initMenuFromUrl
현재 URL을 기반으로 사이드바/네비게이션 메뉴의 활성 상태를 초기화합니다. 주로 관리자 템플릿의 init_actions에서 사용합니다.
소스: src/handlers/initMenuFromUrlHandler.ts
{
"init_actions": [
{
"handler": "initMenuFromUrl"
}
]
}
params
없음. 현재 URL 경로를 메뉴 항목과 매칭하여 활성 메뉴를 자동 설정합니다.
동작
1. 현재 URL 경로 (window.location.pathname) 추출
2. 사이드바 메뉴 데이터에서 URL 매칭
3. 매칭된 메뉴 항목의 is_active 상태 설정
4. 부모 메뉴도 자동으로 펼침 상태 설정
사용 예시 (_admin_base.json)
{
"init_actions": [
{ "handler": "initTheme" },
{ "handler": "initMenuFromUrl" }
]
}
필터 가시성 핸들러
목록 화면에서 필터 패널의 가시성(표시/숨김)을 관리합니다. localStorage에 상태를 저장하여 새로고침 후에도 유지합니다.
소스: src/handlers/filterVisibilityHandler.ts
initFilterVisibility
저장된 필터 가시성 상태를 _local에 복원합니다.
{
"init_actions": [
{
"handler": "initFilterVisibility"
}
]
}
saveFilterVisibility
현재 필터 가시성 상태를 localStorage에 저장합니다.
{
"handler": "saveFilterVisibility",
"params": {
"filters": "{{_local.filterVisibility}}"
}
}
toggleFilterVisibility
특정 필터 키의 가시성을 토글합니다.
{
"type": "click",
"handler": "toggleFilterVisibility",
"params": {
"key": "advancedFilters"
}
}
resetFilterVisibility
모든 필터 가시성을 초기 상태로 리셋합니다.
{
"type": "click",
"handler": "resetFilterVisibility"
}
핸들러 params 요약
| 핸들러 | params | 설명 |
|---|---|---|
initFilterVisibility |
없음 | localStorage → _local 복원 |
saveFilterVisibility |
{ filters } |
_local → localStorage 저장 |
toggleFilterVisibility |
{ key } |
특정 키 토글 |
resetFilterVisibility |
없음 | 전체 초기화 |
사용 예시 (목록 페이지)
{
"init_actions": [
{ "handler": "initFilterVisibility" }
],
"components": [
{
"id": "filter_toggle_btn",
"type": "basic",
"name": "Button",
"props": {
"text": "$t:common.toggle_filters"
},
"actions": [
{
"type": "click",
"handler": "toggleFilterVisibility",
"params": { "key": "advancedFilters" }
}
]
},
{
"id": "filter_section",
"type": "basic",
"name": "Div",
"if": "{{_local.filterVisibility?.advancedFilters}}",
"children": [
{ "comment": "필터 컴포넌트들" }
]
}
]
}
다국어 태그 핸들러
다국어 입력 컴포넌트(MultilingualInput)에서 사용하는 태그 관리 핸들러입니다.
소스: src/handlers/multilingualTagHandler.ts
saveMultilingualTag
다국어 태그를 저장합니다.
{
"handler": "saveMultilingualTag",
"params": {
"field": "tags",
"locale": "{{_global.locale}}"
}
}
cancelMultilingualTag
다국어 태그 편집을 취소합니다.
{
"handler": "cancelMultilingualTag"
}
updateMultilingualTagValue
다국어 태그 값을 업데이트합니다.
{
"handler": "updateMultilingualTagValue",
"params": {
"field": "tags",
"locale": "ko",
"value": "{{$event.target.value}}"
}
}
태그 핸들러 params 요약
| 핸들러 | params | 설명 |
|---|---|---|
saveMultilingualTag |
{ field, locale } |
태그 저장 |
cancelMultilingualTag |
없음 | 편집 취소 |
updateMultilingualTagValue |
{ field, locale, value } |
값 업데이트 |
핸들러 소스 파일 매핑
| 핸들러명 | 소스 파일 | 등록 함수 |
|---|---|---|
setLocale |
src/handlers/setLocaleHandler.ts |
setLocaleHandler |
setTheme, initTheme |
src/handlers/setThemeHandler.ts |
initTheme |
scrollToSection |
src/handlers/scrollToSectionHandler.ts |
scrollToSectionHandler |
initMenuFromUrl |
src/handlers/initMenuFromUrlHandler.ts |
initMenuFromUrlHandler |
initFilterVisibility, saveFilterVisibility, toggleFilterVisibility, resetFilterVisibility |
src/handlers/filterVisibilityHandler.ts |
initFilterVisibilityHandler |
saveMultilingualTag, cancelMultilingualTag, updateMultilingualTagValue |
src/handlers/multilingualTagHandler.ts |
saveMultilingualTagHandler |
주의사항
이 핸들러들은 sirsoft-admin_basic 템플릿에서만 등록됨 (다른 템플릿에서 미지원 가능)
범용 핸들러(navigate, apiCall, setState 등)와 달리 템플릿 의존적
✅ 커스텀 핸들러이므로 template.json의 핸들러 등록 확인 필요
✅ 범용 핸들러는 actions-handlers.md 참조