548 lines
17 KiB
Markdown
548 lines
17 KiB
Markdown
|
# UVC.UIToolkit 컴포넌트 라이브러리
|
||
|
|
|
||
|
|
본 문서는 `Assets/Scripts/UVC/UIToolkit` 폴더의 UI Toolkit 컴포넌트 라이브러리에 대한 참조 가이드입니다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1) 폴더 구조
|
||
|
|
|
||
|
|
```
|
||
|
|
Assets/Scripts/UVC/UIToolkit/
|
||
|
|
├── Button/ # 버튼 컴포넌트
|
||
|
|
│ ├── UTKButton.cs # 메인 버튼 (9가지 variant)
|
||
|
|
│ ├── UTKCheckBox.cs # 체크박스
|
||
|
|
│ ├── UTKToggle.cs # 토글 스위치
|
||
|
|
│ ├── UTKRadioButton.cs # 라디오 버튼
|
||
|
|
│ └── UTKToggleButtonGroup.cs # 토글 버튼 그룹
|
||
|
|
├── Card/
|
||
|
|
│ └── UTKCard.cs # 카드 컨테이너
|
||
|
|
├── Common/ # 공통 유틸리티
|
||
|
|
│ ├── UTKCodeBlock.cs # 코드 블록 표시
|
||
|
|
│ ├── UTKFoldout.cs # 접이식 컨테이너
|
||
|
|
│ ├── UTKHelpBox.cs # 도움말/정보 박스
|
||
|
|
│ ├── UTKImage.cs # 이미지 로더 (내부/URL)
|
||
|
|
│ ├── UTKImageIcons.cs # 이미지 아이콘 레지스트리
|
||
|
|
│ ├── UTKMaterialIcons.cs # Material Symbols (4102개)
|
||
|
|
│ ├── UTKScrollView.cs # 커스텀 스크롤 뷰
|
||
|
|
│ └── UTKTooltipManager.cs # 툴팁 시스템
|
||
|
|
├── Dropdown/
|
||
|
|
│ ├── UTKDropdown.cs # 일반 드롭다운
|
||
|
|
│ └── UTKEnumDropDown.cs # Enum 전용 드롭다운
|
||
|
|
├── Input/ # 입력 필드
|
||
|
|
│ ├── UTKBoundsField.cs # Bounds 입력
|
||
|
|
│ ├── UTKDoubleField.cs # Double 입력
|
||
|
|
│ ├── UTKFloatField.cs # Float 입력
|
||
|
|
│ ├── UTKInputField.cs # 텍스트 입력
|
||
|
|
│ ├── UTKIntegerField.cs # Integer 입력
|
||
|
|
│ ├── UTKLongField.cs # Long 입력
|
||
|
|
│ ├── UTKNumberStepper.cs # 숫자 스테퍼 (+/-)
|
||
|
|
│ ├── UTKRectField.cs # Rect 입력
|
||
|
|
│ ├── UTKVector2Field.cs # Vector2 입력
|
||
|
|
│ ├── UTKVector3Field.cs # Vector3 입력
|
||
|
|
│ └── UTKVector4Field.cs # Vector4 입력
|
||
|
|
├── Label/
|
||
|
|
│ └── UTKLabel.cs # 커스텀 레이블
|
||
|
|
├── List/ # 리스트/트리 컴포넌트
|
||
|
|
│ ├── UTKAccordionList.cs # 아코디언 리스트 (섹션+그리드)
|
||
|
|
│ ├── UTKAccordionListItemData.cs
|
||
|
|
│ ├── UTKComponentList.cs # 컴포넌트 리스트
|
||
|
|
│ ├── UTKComponentListItemData.cs
|
||
|
|
│ ├── UTKImageList.cs # 이미지 그리드 리스트
|
||
|
|
│ ├── UTKImageListItemData.cs
|
||
|
|
│ ├── UTKListView.cs # 일반 리스트 뷰
|
||
|
|
│ ├── UTKMultiColumnListView.cs # 다중 컬럼 리스트
|
||
|
|
│ ├── UTKMultiColumnTreeView.cs # 다중 컬럼 트리
|
||
|
|
│ ├── UTKTreeListItemData.cs
|
||
|
|
│ └── UTKTreeView.cs # 트리 뷰
|
||
|
|
├── Modal/ # 모달/다이얼로그
|
||
|
|
│ ├── UTKAlert.cs # 알림 다이얼로그
|
||
|
|
│ ├── UTKColorPicker.cs # 색상 선택기
|
||
|
|
│ ├── UTKDatePicker.cs # 날짜 선택기
|
||
|
|
│ ├── UTKModal.cs # 기본 모달
|
||
|
|
│ ├── UTKModalBlocker.cs # 모달 배경 블로커
|
||
|
|
│ ├── UTKNotification.cs # 알림 토스트
|
||
|
|
│ ├── UTKPanel.cs # 패널 컨테이너
|
||
|
|
│ └── UTKToast.cs # 토스트 알림
|
||
|
|
├── Property/ # 프로퍼티 에디터 시스템
|
||
|
|
│ ├── Core/ # 핵심 인터페이스
|
||
|
|
│ │ ├── IUTKPropertyEntry.cs
|
||
|
|
│ │ ├── IUTKPropertyGroup.cs
|
||
|
|
│ │ ├── IUTKPropertyItem.cs
|
||
|
|
│ │ ├── UTKPropertyGroup.cs
|
||
|
|
│ │ ├── UTKPropertyType.cs
|
||
|
|
│ │ └── UTKPropertyValueChangedEventArgs.cs
|
||
|
|
│ ├── Data/ # 데이터 타입
|
||
|
|
│ │ ├── UTKColorState.cs
|
||
|
|
│ │ └── UTKRangeValue.cs
|
||
|
|
│ ├── Items/ # 프로퍼티 아이템 (16종)
|
||
|
|
│ │ ├── Base/UTKPropertyItemBase.cs
|
||
|
|
│ │ ├── UTKBoolPropertyItem.cs
|
||
|
|
│ │ ├── UTKColorPropertyItem.cs
|
||
|
|
│ │ ├── UTKColorStatePropertyItem.cs
|
||
|
|
│ │ ├── UTKDatePropertyItem.cs
|
||
|
|
│ │ ├── UTKDateRangePropertyItem.cs
|
||
|
|
│ │ ├── UTKDateTimePropertyItem.cs
|
||
|
|
│ │ ├── UTKDateTimeRangePropertyItem.cs
|
||
|
|
│ │ ├── UTKDropdownPropertyItem.cs
|
||
|
|
│ │ ├── UTKEnumPropertyItem.cs
|
||
|
|
│ │ ├── UTKFloatPropertyItem.cs
|
||
|
|
│ │ ├── UTKFloatRangePropertyItem.cs
|
||
|
|
│ │ ├── UTKIntPropertyItem.cs
|
||
|
|
│ │ ├── UTKIntRangePropertyItem.cs
|
||
|
|
│ │ ├── UTKRadioPropertyItem.cs
|
||
|
|
│ │ ├── UTKStringPropertyItem.cs
|
||
|
|
│ │ ├── UTKVector2PropertyItem.cs
|
||
|
|
│ │ └── UTKVector3PropertyItem.cs
|
||
|
|
│ ├── UTKPropertyList.cs # 프로퍼티 리스트 컨테이너
|
||
|
|
│ └── UTKPropertyWindow.cs # 프로퍼티 윈도우
|
||
|
|
├── Slider/
|
||
|
|
│ ├── UTKMinMaxSlider.cs # 범위 슬라이더
|
||
|
|
│ ├── UTKProgressBar.cs # 프로그레스 바
|
||
|
|
│ └── UTKSlider.cs # 단일 슬라이더
|
||
|
|
├── Tab/
|
||
|
|
│ ├── UTKTab.cs # 개별 탭
|
||
|
|
│ └── UTKTabView.cs # 탭 컨테이너
|
||
|
|
├── Window/ # 윈도우 컴포넌트
|
||
|
|
│ ├── UTKAccordionListWindow.cs
|
||
|
|
│ ├── UTKComponentListWindow.cs
|
||
|
|
│ ├── UTKComponentTabListWindow.cs
|
||
|
|
│ ├── UTKImageListWindow.cs
|
||
|
|
│ └── UTKTreeListWindow.cs
|
||
|
|
├── UTKStyleGuide.cs # 스타일 상수 및 색상
|
||
|
|
└── UTKThemeManager.cs # 테마 관리 (Light/Dark)
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2) 핵심 시스템
|
||
|
|
|
||
|
|
### 테마 관리 (UTKThemeManager)
|
||
|
|
|
||
|
|
라이트/다크 테마 전환을 관리하는 싱글톤입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
// 테마 등록 및 전환
|
||
|
|
UTKThemeManager.Instance.RegisterRoot(rootVisualElement);
|
||
|
|
UTKThemeManager.Instance.SetTheme(UTKTheme.Dark);
|
||
|
|
UTKThemeManager.Instance.ToggleTheme();
|
||
|
|
|
||
|
|
// 테마 변경 이벤트 구독
|
||
|
|
UTKThemeManager.OnThemeChanged += OnThemeChanged;
|
||
|
|
|
||
|
|
// 관리 USS 파일
|
||
|
|
// - UTKVariables.uss (CSS 변수)
|
||
|
|
// - UTKThemeDark.uss / UTKThemeLight.uss (테마별 스타일)
|
||
|
|
// - UTKComponents.uss (컴포넌트 공통 스타일)
|
||
|
|
```
|
||
|
|
|
||
|
|
### 스타일 가이드 (UTKStyleGuide)
|
||
|
|
|
||
|
|
색상, 간격, 폰트, 컴포넌트 크기 등의 상수를 정의합니다.
|
||
|
|
|
||
|
|
| 카테고리 | 설명 |
|
||
|
|
|----------|------|
|
||
|
|
| Base Colors | Base01~Base21 기본 색상 팔레트 |
|
||
|
|
| Accent Colors | Blue, Red, Green, Purple, Yellow, Orange, Gray, Seti |
|
||
|
|
| Semantic Colors | Text, Background, Border, Button, Calendar, State, Scrollbar |
|
||
|
|
|
||
|
|
### 아이콘 시스템
|
||
|
|
|
||
|
|
**1순위: Material Icons (UTKMaterialIcons)**
|
||
|
|
```csharp
|
||
|
|
// 폰트 로드
|
||
|
|
await UTKMaterialIcons.LoadFontAsync();
|
||
|
|
|
||
|
|
// 아이콘 적용
|
||
|
|
var icon = UTKMaterialIcons.GetIcon("settings");
|
||
|
|
UTKMaterialIcons.ApplyIconStyle(label, fontSize: 24);
|
||
|
|
|
||
|
|
// 버튼에 아이콘 설정
|
||
|
|
button.SetMaterialIcon(UTKMaterialIcons.Home);
|
||
|
|
```
|
||
|
|
|
||
|
|
**2순위: Image Icons (UTKImageIcons)**
|
||
|
|
```csharp
|
||
|
|
// 필요한 아이콘이 Material에 없는 경우에만 사용
|
||
|
|
var texture = UTKImageIcons.LoadTexture("path/to/icon");
|
||
|
|
button.SetImageIcon(UTKImageIcons.CustomIcon);
|
||
|
|
```
|
||
|
|
|
||
|
|
> **참고**: Material Icons는 4,102개의 아이콘을 제공하며, 폰트 기반으로 메모리 효율이 높습니다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3) 주요 컴포넌트
|
||
|
|
|
||
|
|
### UTKButton
|
||
|
|
|
||
|
|
다양한 스타일과 크기를 지원하는 버튼 컴포넌트입니다.
|
||
|
|
|
||
|
|
**Variants:**
|
||
|
|
- Normal, Primary, Secondary, Ghost, Danger
|
||
|
|
- OutlineNormal, OutlinePrimary, OutlineDanger, Text
|
||
|
|
|
||
|
|
**Sizes:** Small, Medium, Large
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var button = new UTKButton("확인", UTKButton.Variant.Primary, UTKButton.Size.Medium);
|
||
|
|
button.SetMaterialIcon(UTKMaterialIcons.Check);
|
||
|
|
button.OnClicked += () => Debug.Log("Clicked!");
|
||
|
|
|
||
|
|
// UXML 사용
|
||
|
|
<utk:UTKButton text="확인"
|
||
|
|
icon="check"
|
||
|
|
variant="Primary"
|
||
|
|
size="Medium"
|
||
|
|
icon-only="false" />
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKAccordionList
|
||
|
|
|
||
|
|
섹션별 접기/펼치기가 가능한 아코디언 리스트입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var accordionList = new UTKAccordionList();
|
||
|
|
accordionList.SetData(sections); // List<UTKAccordionListItemData>
|
||
|
|
accordionList.Search("검색어");
|
||
|
|
accordionList.ExpandAll();
|
||
|
|
accordionList.CollapseAll();
|
||
|
|
|
||
|
|
// 이벤트
|
||
|
|
accordionList.OnItemClick += (item) => { };
|
||
|
|
accordionList.OnDragExitList += (item) => { };
|
||
|
|
accordionList.OnSectionToggled += (section, expanded) => { };
|
||
|
|
```
|
||
|
|
|
||
|
|
**특징:**
|
||
|
|
- TreeView 기반 가상화
|
||
|
|
- 검색 필터링
|
||
|
|
- 드래그 앤 드롭 지원
|
||
|
|
- 비동기 이미지 로딩 및 캐싱
|
||
|
|
- 그리드 레이아웃 (2열)
|
||
|
|
|
||
|
|
### UTKTreeView / UTKTreeListWindow
|
||
|
|
|
||
|
|
계층 구조 데이터를 트리 형태로 표시합니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var treeView = new UTKTreeView();
|
||
|
|
treeView.SetData(rootItems); // List<UTKTreeListItemData>
|
||
|
|
|
||
|
|
// TreeListWindow 사용
|
||
|
|
var window = new UTKTreeListWindow();
|
||
|
|
window.SetData(items);
|
||
|
|
window.OnItemSelected += (item) => { };
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKModal / UTKColorPicker / UTKDatePicker
|
||
|
|
|
||
|
|
모달 다이얼로그 및 특수 선택기입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
// 기본 모달
|
||
|
|
var modal = new UTKModal("제목");
|
||
|
|
modal.AddContent(contentElement);
|
||
|
|
modal.AddToFooter(confirmButton);
|
||
|
|
modal.Show();
|
||
|
|
modal.OnClosed += () => { };
|
||
|
|
|
||
|
|
// 색상 선택기
|
||
|
|
var colorPicker = new UTKColorPicker();
|
||
|
|
colorPicker.Color = Color.red;
|
||
|
|
colorPicker.OnColorChanged += (color) => { };
|
||
|
|
|
||
|
|
// 날짜 선택기
|
||
|
|
var datePicker = new UTKDatePicker();
|
||
|
|
datePicker.SelectedDate = DateTime.Now;
|
||
|
|
datePicker.OnDateSelected += (date) => { };
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKImage
|
||
|
|
|
||
|
|
내부 리소스 및 외부 URL에서 이미지를 로드합니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var image = new UTKImage();
|
||
|
|
|
||
|
|
// Resources 로드
|
||
|
|
await image.LoadAsync("UIToolkit/Icons/sample");
|
||
|
|
|
||
|
|
// HTTP/HTTPS 로드
|
||
|
|
await image.LoadAsync("https://example.com/image.png");
|
||
|
|
|
||
|
|
// 이벤트
|
||
|
|
image.OnImageLoaded += (texture) => { };
|
||
|
|
image.OnImageFailed += (error) => { };
|
||
|
|
|
||
|
|
// 스케일 모드
|
||
|
|
image.ScaleMode = ScaleMode.ScaleToFit; // ScaleToFit, ScaleAndCrop, StretchToFill
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4) 프로퍼티 에디터 시스템
|
||
|
|
|
||
|
|
Inspector 스타일의 프로퍼티 편집 시스템입니다.
|
||
|
|
|
||
|
|
### 아키텍처
|
||
|
|
|
||
|
|
```
|
||
|
|
IUTKPropertyEntry (기본 인터페이스)
|
||
|
|
├── IUTKPropertyItem<T> # 개별 프로퍼티
|
||
|
|
│ ├── OnValueChanged event
|
||
|
|
│ ├── GetValue() / SetValue()
|
||
|
|
│ └── CreateUI() / BindUI() / UnbindUI()
|
||
|
|
└── IUTKPropertyGroup # 프로퍼티 그룹
|
||
|
|
├── Items 컬렉션
|
||
|
|
├── AddItem() / RemoveItem()
|
||
|
|
└── OnExpandedChanged event
|
||
|
|
```
|
||
|
|
|
||
|
|
### 프로퍼티 타입 (16종)
|
||
|
|
|
||
|
|
| 타입 | 클래스 | 설명 |
|
||
|
|
|------|--------|------|
|
||
|
|
| String | UTKStringPropertyItem | 텍스트 입력 |
|
||
|
|
| Int | UTKIntPropertyItem | 정수 (슬라이더 옵션) |
|
||
|
|
| Float | UTKFloatPropertyItem | 실수 (슬라이더 옵션) |
|
||
|
|
| Bool | UTKBoolPropertyItem | 토글 스위치 |
|
||
|
|
| Vector2 | UTKVector2PropertyItem | 2D 벡터 |
|
||
|
|
| Vector3 | UTKVector3PropertyItem | 3D 벡터 |
|
||
|
|
| Color | UTKColorPropertyItem | 색상 선택기 |
|
||
|
|
| Date | UTKDatePropertyItem | 날짜 선택 |
|
||
|
|
| DateTime | UTKDateTimePropertyItem | 날짜+시간 선택 |
|
||
|
|
| Enum | UTKEnumPropertyItem | Enum 드롭다운 |
|
||
|
|
| Dropdown | UTKDropdownPropertyItem | 문자열 드롭다운 |
|
||
|
|
| Radio | UTKRadioPropertyItem | 라디오 버튼 그룹 |
|
||
|
|
| IntRange | UTKIntRangePropertyItem | 정수 범위 (Min/Max) |
|
||
|
|
| FloatRange | UTKFloatRangePropertyItem | 실수 범위 |
|
||
|
|
| DateRange | UTKDateRangePropertyItem | 날짜 범위 |
|
||
|
|
| DateTimeRange | UTKDateTimeRangePropertyItem | 날짜+시간 범위 |
|
||
|
|
| ColorState | UTKColorStatePropertyItem | 색상+상태 (커스텀) |
|
||
|
|
|
||
|
|
### 사용 예시
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
// 프로퍼티 윈도우 생성
|
||
|
|
var propertyWindow = new UTKPropertyWindow("설정");
|
||
|
|
|
||
|
|
// 그룹 생성
|
||
|
|
var generalGroup = new UTKPropertyGroup("일반 설정");
|
||
|
|
|
||
|
|
// 프로퍼티 아이템 추가
|
||
|
|
generalGroup.AddItem(new UTKStringPropertyItem("이름", "기본값"));
|
||
|
|
generalGroup.AddItem(new UTKIntPropertyItem("레벨", 1, minValue: 1, maxValue: 100));
|
||
|
|
generalGroup.AddItem(new UTKBoolPropertyItem("활성화", true));
|
||
|
|
generalGroup.AddItem(new UTKColorPropertyItem("색상", Color.white));
|
||
|
|
|
||
|
|
// 그룹을 윈도우에 추가
|
||
|
|
propertyWindow.PropertyList.AddGroup(generalGroup);
|
||
|
|
|
||
|
|
// 값 변경 이벤트
|
||
|
|
generalGroup.OnValueChanged += (sender, args) => {
|
||
|
|
Debug.Log($"{args.PropertyName}: {args.OldValue} → {args.NewValue}");
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
**특징:**
|
||
|
|
- 디바운스 지원 (기본 300ms)
|
||
|
|
- 읽기 전용 모드
|
||
|
|
- 툴팁 지원
|
||
|
|
- IDisposable 패턴으로 메모리 관리
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5) Window 컴포넌트
|
||
|
|
|
||
|
|
### UTKAccordionListWindow
|
||
|
|
|
||
|
|
아코디언 리스트를 포함한 윈도우입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var window = new UTKAccordionListWindow();
|
||
|
|
window.SetTitle("아이템 목록");
|
||
|
|
window.SetData(sections);
|
||
|
|
window.OnItemSelected += (item) => { };
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKComponentListWindow
|
||
|
|
|
||
|
|
컴포넌트 리스트 윈도우입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var window = new UTKComponentListWindow();
|
||
|
|
window.SetData(components);
|
||
|
|
window.OnComponentSelected += (component) => { };
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKTreeListWindow
|
||
|
|
|
||
|
|
트리 구조 데이터를 표시하는 윈도우입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var window = new UTKTreeListWindow();
|
||
|
|
window.SetData(treeItems);
|
||
|
|
window.OnItemSelected += (item) => { };
|
||
|
|
window.ExpandAll();
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKImageListWindow
|
||
|
|
|
||
|
|
이미지 그리드를 표시하는 윈도우입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var window = new UTKImageListWindow();
|
||
|
|
window.SetData(images);
|
||
|
|
window.OnImageSelected += (image) => { };
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 6) 입력 필드
|
||
|
|
|
||
|
|
### 기본 입력 필드
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
// 정수 입력
|
||
|
|
var intField = new UTKIntegerField("수량");
|
||
|
|
intField.Value = 10;
|
||
|
|
intField.OnValueChanged += (value) => { };
|
||
|
|
|
||
|
|
// 실수 입력
|
||
|
|
var floatField = new UTKFloatField("크기");
|
||
|
|
floatField.Value = 1.5f;
|
||
|
|
|
||
|
|
// 벡터 입력
|
||
|
|
var vector3Field = new UTKVector3Field("위치");
|
||
|
|
vector3Field.Value = Vector3.zero;
|
||
|
|
```
|
||
|
|
|
||
|
|
### UTKNumberStepper
|
||
|
|
|
||
|
|
증가/감소 버튼이 있는 숫자 입력 필드입니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
var stepper = new UTKNumberStepper();
|
||
|
|
stepper.Value = 5;
|
||
|
|
stepper.Min = 0;
|
||
|
|
stepper.Max = 100;
|
||
|
|
stepper.Step = 1;
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 7) UXML 속성 규칙
|
||
|
|
|
||
|
|
Unity 6 소스 생성기 기반의 `[UxmlElement]`와 `[UxmlAttribute]`를 사용합니다.
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
[UxmlElement]
|
||
|
|
public partial class UTKCustomComponent : VisualElement
|
||
|
|
{
|
||
|
|
[UxmlAttribute("title")]
|
||
|
|
public string Title { get; set; }
|
||
|
|
|
||
|
|
[UxmlAttribute("is-enabled")]
|
||
|
|
public bool IsEnabled { get; set; }
|
||
|
|
|
||
|
|
[UxmlAttribute("border-width")]
|
||
|
|
public int BorderWidth { get; set; }
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**UXML 사용:**
|
||
|
|
```xml
|
||
|
|
<utk:UTKCustomComponent title="제목" is-enabled="true" border-width="2" />
|
||
|
|
```
|
||
|
|
|
||
|
|
**주의사항:**
|
||
|
|
- 클래스는 반드시 `partial`로 선언
|
||
|
|
- 속성명은 케밥 케이스(kebab-case) 소문자 사용
|
||
|
|
- 레거시 `UxmlFactory`/`UxmlTraits` 방식 사용 금지
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 8) 네이밍 규칙
|
||
|
|
|
||
|
|
| 항목 | 규칙 | 예시 |
|
||
|
|
|------|------|------|
|
||
|
|
| 클래스 | UTK 접두사 + PascalCase | `UTKButton`, `UTKAccordionList` |
|
||
|
|
| UXML 파일 | `{ComponentName}.uxml` | `UTKAccordionListWindow.uxml` |
|
||
|
|
| USS 파일 | `{ComponentName}Uss.uss` | `UTKAccordionListWindowUss.uss` |
|
||
|
|
| Public 멤버 | PascalCase | `OnClicked`, `Value` |
|
||
|
|
| Private 필드 | _camelCase | `_button`, `_labelCache` |
|
||
|
|
| 이벤트 | On 접두사 | `OnValueChanged`, `OnClicked` |
|
||
|
|
|
||
|
|
> **중요**: UXML과 USS 파일명을 다르게 지정해야 `Resources.Load<T>()` 충돌을 방지할 수 있습니다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 9) 메모리 관리 패턴
|
||
|
|
|
||
|
|
### 이벤트 구독/해제
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
private EventCallback<ClickEvent>? _onClick;
|
||
|
|
|
||
|
|
void OnEnable()
|
||
|
|
{
|
||
|
|
_onClick = OnButtonClick;
|
||
|
|
_button?.RegisterCallback(_onClick);
|
||
|
|
UTKThemeManager.OnThemeChanged += OnThemeChanged;
|
||
|
|
}
|
||
|
|
|
||
|
|
void OnDisable()
|
||
|
|
{
|
||
|
|
_button?.UnregisterCallback(_onClick);
|
||
|
|
UTKThemeManager.OnThemeChanged -= OnThemeChanged;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### IDisposable 패턴
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
public void Dispose()
|
||
|
|
{
|
||
|
|
UnregisterEvents();
|
||
|
|
_cts?.Cancel();
|
||
|
|
_cts?.Dispose();
|
||
|
|
_cts = null;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 체크리스트
|
||
|
|
|
||
|
|
- [ ] `RegisterCallback<T>` ↔ `UnregisterCallback<T>` 대칭 확인
|
||
|
|
- [ ] `UTKThemeManager.OnThemeChanged` 구독 해제
|
||
|
|
- [ ] `CancellationTokenSource` 정리 (`Cancel` → `Dispose`)
|
||
|
|
- [ ] 람다/클로저 캡처로 인한 누수 점검
|
||
|
|
- [ ] 이미지 캐시 정리 (해당 시)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 10) 주요 API 요약
|
||
|
|
|
||
|
|
| 카테고리 | 클래스 | 주요 메서드 |
|
||
|
|
|----------|--------|-------------|
|
||
|
|
| **테마** | UTKThemeManager | `RegisterRoot`, `SetTheme`, `ToggleTheme` |
|
||
|
|
| **버튼** | UTKButton | `SetMaterialIcon`, `SetImageIcon`, `OnClicked` |
|
||
|
|
| **리스트** | UTKAccordionList | `SetData`, `Search`, `ExpandAll`, `OnItemClick` |
|
||
|
|
| **트리** | UTKTreeView | `SetData`, `ExpandAll`, `CollapseAll` |
|
||
|
|
| **프로퍼티** | UTKPropertyWindow | `LoadProperties`, `AddGroup`, `UpdatePropertyValue` |
|
||
|
|
| **모달** | UTKModal | `Show`, `Close`, `AddContent`, `AddToFooter` |
|
||
|
|
| **이미지** | UTKImage | `LoadAsync`, `SetTexture`, `ClearImage` |
|
||
|
|
| **입력** | UTK*Field | `Value`, `OnValueChanged` |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 11) 참조 리소스
|
||
|
|
|
||
|
|
| 경로 | 설명 |
|
||
|
|
|------|------|
|
||
|
|
| `Assets/Resources/UIToolkit/Style/` | USS 스타일 파일 |
|
||
|
|
| `Assets/Resources/UIToolkit/Common/` | 공통 UXML 컴포넌트 |
|
||
|
|
| `Assets/Resources/UIToolkit/Window/` | 윈도우 UXML 템플릿 |
|
||
|
|
| `Assets/Resources/UIToolkit/Modal/` | 모달 UXML 템플릿 |
|
||
|
|
| `Assets/Resources/UIToolkit/List/` | 리스트 UXML 템플릿 |
|
||
|
|
| `Assets/Resources/UIToolkit/Property/` | 프로퍼티 UXML 템플릿 |
|