301 lines
7.4 KiB
Markdown
301 lines
7.4 KiB
Markdown
# AutocompleteSearchInput 컴포넌트 사용 가이드
|
|
|
|
## 📌 이 컴포넌트는 무엇인가요?
|
|
|
|
검색 가능한 드롭다운 선택 박스입니다.
|
|
거래처, 품목, 직원 등을 검색해서 선택할 때 사용합니다.
|
|
|
|
---
|
|
|
|
## ⚙️ 패널 설정 방법
|
|
|
|
### 1. 기본 검색 설정 (필수)
|
|
|
|
#### 테이블명
|
|
- **의미**: 어디서 검색할 것인가?
|
|
- **예시**: `customer_mng` (거래처 테이블)
|
|
|
|
#### 표시 필드
|
|
- **의미**: 사용자에게 무엇을 보여줄 것인가?
|
|
- **예시**: `customer_name` → 화면에 "삼성전자" 표시
|
|
|
|
#### 값 필드
|
|
- **의미**: 실제로 어떤 값을 가져올 것인가?
|
|
- **예시**: `customer_code` → "CUST-0001" 가져오기
|
|
|
|
#### 검색 필드 (선택)
|
|
- **의미**: 어떤 컬럼으로 검색할 것인가?
|
|
- **예시**: `customer_name`, `customer_code` 추가
|
|
- **동작**: 이름으로도 검색, 코드로도 검색 가능
|
|
|
|
---
|
|
|
|
### 2. 값 필드 저장 위치 (고급, 선택)
|
|
|
|
#### 저장 테이블
|
|
- **기본값**: 화면의 연결 테이블에 자동 저장
|
|
- **변경 시**: 다른 테이블에 저장 가능
|
|
|
|
#### 저장 컬럼
|
|
- **기본값**: 컴포넌트의 바인딩 필드
|
|
- **변경 시**: 다른 컬럼에 저장 가능
|
|
|
|
> 💡 **대부분은 기본값을 사용하면 됩니다!**
|
|
|
|
---
|
|
|
|
## 📖 사용 예제
|
|
|
|
### 예제 1: 거래처 선택 (가장 일반적)
|
|
|
|
#### 패널 설정
|
|
```
|
|
테이블명: customer_mng
|
|
표시 필드: customer_name
|
|
값 필드: customer_code
|
|
검색 필드: customer_name, customer_code
|
|
플레이스홀더: 거래처명 또는 코드 입력
|
|
```
|
|
|
|
#### 동작
|
|
```
|
|
사용자 입력: "삼성"
|
|
드롭다운 표시: "삼성전자", "삼성물산", ...
|
|
선택: "삼성전자"
|
|
저장 값: "CUST-0001" (customer_code)
|
|
```
|
|
|
|
#### 결과
|
|
```
|
|
order_mng 테이블
|
|
┌───────────┬───────────────┐
|
|
│ order_id │ customer_code │
|
|
├───────────┼───────────────┤
|
|
│ ORD-0001 │ CUST-0001 │ ✅
|
|
└───────────┴───────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
### 예제 2: 거래처명을 직접 저장
|
|
|
|
#### 패널 설정
|
|
```
|
|
테이블명: customer_mng
|
|
표시 필드: customer_name
|
|
값 필드: customer_name ← 이름을 가져옴
|
|
플레이스홀더: 거래처명 입력
|
|
```
|
|
|
|
#### 동작
|
|
```
|
|
사용자 선택: "삼성전자"
|
|
저장 값: "삼성전자" (customer_name)
|
|
```
|
|
|
|
#### 결과
|
|
```
|
|
order_mng 테이블
|
|
┌───────────┬───────────────┐
|
|
│ order_id │ customer_name │
|
|
├───────────┼───────────────┤
|
|
│ ORD-0001 │ 삼성전자 │ ✅
|
|
└───────────┴───────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
### 예제 3: 품목 선택 (추가 정보 표시)
|
|
|
|
#### 패널 설정
|
|
```
|
|
테이블명: item_mng
|
|
표시 필드: item_name
|
|
값 필드: item_code
|
|
검색 필드: item_name, item_code, category
|
|
플레이스홀더: 품목명, 코드, 카테고리로 검색
|
|
|
|
추가 정보 표시: ON
|
|
추가 필드: item_code, unit_price
|
|
```
|
|
|
|
#### 동작
|
|
```
|
|
드롭다운:
|
|
┌────────────────────────────┐
|
|
│ 삼성 노트북 │
|
|
│ item_code: ITEM-0123 │
|
|
│ unit_price: 1,500,000 │
|
|
├────────────────────────────┤
|
|
│ LG 그램 노트북 │
|
|
│ item_code: ITEM-0124 │
|
|
│ unit_price: 1,800,000 │
|
|
└────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 필드 선택 가이드
|
|
|
|
### 언제 표시 필드 ≠ 값 필드 인가?
|
|
|
|
**대부분의 경우 (권장)**
|
|
```
|
|
표시 필드: customer_name (이름 - 사람이 읽기 쉬움)
|
|
값 필드: customer_code (코드 - 데이터베이스에 저장)
|
|
|
|
이유:
|
|
✅ 외래키 관계 유지
|
|
✅ 데이터 무결성
|
|
✅ 이름이 바뀌어도 코드는 그대로
|
|
```
|
|
|
|
### 언제 표시 필드 = 값 필드 인가?
|
|
|
|
**특수한 경우**
|
|
```
|
|
표시 필드: customer_name
|
|
값 필드: customer_name
|
|
|
|
사용 케이스:
|
|
- 이름 자체를 저장해야 할 때
|
|
- 외래키가 필요 없을 때
|
|
- 간단한 참조용 데이터
|
|
```
|
|
|
|
---
|
|
|
|
## 💡 자주 묻는 질문
|
|
|
|
### Q1. 저장 위치를 설정하지 않으면?
|
|
|
|
**A**: 자동으로 화면의 연결 테이블에 바인딩 필드로 저장됩니다.
|
|
|
|
```
|
|
화면: 수주 등록 (연결 테이블: order_mng)
|
|
컴포넌트 바인딩 필드: customer_code
|
|
|
|
→ order_mng.customer_code에 자동 저장 ✅
|
|
```
|
|
|
|
---
|
|
|
|
### Q2. 값 필드와 저장 위치의 차이는?
|
|
|
|
**A**:
|
|
- **값 필드**: 검색 테이블에서 무엇을 가져올지
|
|
- **저장 위치**: 가져온 값을 어디에 저장할지
|
|
|
|
```
|
|
값 필드: customer_mng.customer_code (어떤 값?)
|
|
저장 위치: order_mng.customer_code (어디에?)
|
|
```
|
|
|
|
---
|
|
|
|
### Q3. 검색 필드는 왜 여러 개 추가하나요?
|
|
|
|
**A**: 여러 방법으로 검색할 수 있게 하기 위해서입니다.
|
|
|
|
```
|
|
검색 필드: [customer_name, customer_code]
|
|
|
|
사용자가 "삼성" 입력 → customer_name에서 검색
|
|
사용자가 "CUST" 입력 → customer_code에서 검색
|
|
```
|
|
|
|
---
|
|
|
|
### Q4. 추가 정보 표시는 언제 사용하나요?
|
|
|
|
**A**: 선택할 때 참고할 정보를 함께 보여주고 싶을 때 사용합니다.
|
|
|
|
```
|
|
추가 정보 표시: ON
|
|
추가 필드: [address, phone]
|
|
|
|
드롭다운:
|
|
┌────────────────────────────┐
|
|
│ 삼성전자 │
|
|
│ address: 서울시 서초구 │
|
|
│ phone: 02-1234-5678 │
|
|
└────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 빠른 시작
|
|
|
|
### 1단계: 기본 설정만 입력
|
|
|
|
```
|
|
테이블명: [검색할 테이블]
|
|
표시 필드: [사용자에게 보여줄 컬럼]
|
|
값 필드: [저장할 컬럼]
|
|
```
|
|
|
|
### 2단계: 화면 디자이너에서 바인딩 필드 설정
|
|
|
|
```
|
|
컴포넌트 ID: customer_search
|
|
바인딩 필드: customer_code
|
|
```
|
|
|
|
### 3단계: 완료!
|
|
|
|
이제 사용자가 선택하면 자동으로 저장됩니다.
|
|
|
|
---
|
|
|
|
## ✅ 체크리스트
|
|
|
|
설정 전:
|
|
- [ ] 어느 테이블에서 검색할지 알고 있나요?
|
|
- [ ] 사용자에게 무엇을 보여줄지 정했나요?
|
|
- [ ] 어떤 값을 저장할지 정했나요?
|
|
|
|
설정 후:
|
|
- [ ] 검색이 정상적으로 되나요?
|
|
- [ ] 드롭다운에 원하는 항목이 보이나요?
|
|
- [ ] 선택 후 값이 저장되나요?
|
|
|
|
---
|
|
|
|
## 📊 설정 패턴 비교
|
|
|
|
| 패턴 | 표시 필드 | 값 필드 | 사용 케이스 |
|
|
|------|----------|---------|------------|
|
|
| 1 | customer_name | customer_code | 이름 표시, 코드 저장 (일반적) |
|
|
| 2 | customer_name | customer_name | 이름 표시, 이름 저장 (특수) |
|
|
| 3 | item_name | item_code | 품목명 표시, 품목코드 저장 |
|
|
| 4 | employee_name | employee_id | 직원명 표시, ID 저장 |
|
|
|
|
---
|
|
|
|
## 🎨 실전 팁
|
|
|
|
### 1. 검색 필드는 2-3개가 적당
|
|
```
|
|
✅ 좋음: [name, code]
|
|
✅ 좋음: [name, code, category]
|
|
❌ 과함: [name, code, address, phone, email, ...]
|
|
```
|
|
|
|
### 2. 플레이스홀더는 구체적으로
|
|
```
|
|
❌ "검색..."
|
|
✅ "거래처명 또는 코드 입력"
|
|
✅ "품목명, 코드, 카테고리로 검색"
|
|
```
|
|
|
|
### 3. 추가 정보는 선택에 도움되는 것만
|
|
```
|
|
✅ 도움됨: 가격, 주소, 전화번호
|
|
❌ 불필요: 등록일, 수정일, ID
|
|
```
|
|
|
|
---
|
|
|
|
이 가이드로 autocomplete-search-input 컴포넌트를 쉽게 사용할 수 있습니다! 🎉
|
|
|