677 lines
19 KiB
Markdown
677 lines
19 KiB
Markdown
# 데이터 바인딩 및 표현식
|
|
|
|
> **관련 문서**: [index.md](index.md) | [layout-json.md](layout-json.md) | [data-sources.md](data-sources.md)
|
|
|
|
---
|
|
|
|
## TL;DR (5초 요약)
|
|
|
|
```text
|
|
1. API 데이터: {{user.name}}, URL 파라미터: {{route.id}}
|
|
2. 상태 접근: {{_global.xxx}}, {{_local.xxx}}, {{_isolated.xxx}}
|
|
3. Optional Chaining: {{user?.profile?.name ?? '기본값'}}
|
|
4. 파이프 함수: {{created_at | date}}, {{name | truncate(50)}}
|
|
5. $get 헬퍼: {{$get(obj, ['key1', 'key2'], fallback)}}
|
|
```
|
|
|
|
---
|
|
|
|
## 분리된 문서
|
|
|
|
이 문서는 가독성을 위해 다음과 같이 분리되었습니다:
|
|
|
|
| 문서 | 내용 |
|
|
|------|------|
|
|
| **data-binding.md** (현재) | 기본 문법, 데이터 바인딩 표현식, Optional Chaining, 반복 컨텍스트 |
|
|
| [data-binding-i18n.md](data-binding-i18n.md) | $localized() 헬퍼, 다국어 처리, 지연 번역, 모듈/플러그인 다국어 병합, 컴포넌트 다국어 처리 |
|
|
| [rawMarkers.ts](../../resources/js/core/template-engine/rawMarkers.ts) | `raw:` 마커 — 번역 면제 바인딩 (`{{raw:expression}}`) |
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [기본 문법](#기본-문법)
|
|
2. [데이터 바인딩 표현식 (engine-v1.1.0+)](#데이터-바인딩-표현식-v110)
|
|
3. [Optional Chaining & Nullish Coalescing](#optional-chaining--nullish-coalescing-v110)
|
|
4. [파이프 함수 (engine-v1.9.0+)](#파이프-함수-v190)
|
|
5. [$get 헬퍼 함수 (engine-v1.9.0+)](#get-헬퍼-함수-v190)
|
|
6. [$switch 표현식 (engine-v1.9.0+)](#switch-표현식-v190)
|
|
7. [반복 컨텍스트에서의 표현식](#반복-컨텍스트에서의-표현식-v120)
|
|
8. [text 속성 복합 바인딩](#text-속성-복합-바인딩-v120)
|
|
|
|
---
|
|
|
|
## 기본 문법
|
|
|
|
레이아웃 JSON에서 동적 데이터를 참조할 때 사용하는 문법입니다.
|
|
|
|
### 데이터 바인딩 유형
|
|
|
|
| 문법 | 설명 | 예시 |
|
|
|------|------|------|
|
|
| `{{data.field}}` | API 데이터 바인딩 | `{{user.name}}` |
|
|
| `{{route.param}}` | URL 파라미터 | `/users/:id`의 `{{route.id}}` |
|
|
| `{{query.key}}` | 쿼리 스트링 | `?category=electronics`의 `{{query.category}}` |
|
|
| `{{state.value}}` | 컴포넌트 상태 | `{{state.isOpen}}` |
|
|
| `{{_global.property}}` | 전역 상태 (engine-v1.1.0+) | `{{_global.sidebarOpen}}` |
|
|
| `{{_local.property}}` | 로컬 상태 | `{{_local.formData}}` |
|
|
| `{{_isolated.property}}` | 격리된 상태 (engine-v1.14.0+) | `{{_isolated.selectedItems}}` |
|
|
| `{{raw:expression}}` | 번역 면제 바인딩 (engine-v1.27.0+) | `{{raw:item.jsonData}}` |
|
|
|
|
### 기본 예시
|
|
|
|
```json
|
|
{
|
|
"props": {
|
|
"title": "{{user.name}}",
|
|
"email": "{{user.email}}",
|
|
"userId": "{{route.id}}",
|
|
"category": "{{query.category_id}}",
|
|
"sidebarOpen": "{{_global.sidebarOpen}}",
|
|
"formData": "{{_local.form}}",
|
|
"selectedCount": "{{_isolated.selectedItems?.length ?? 0}}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 격리된 상태 바인딩 (engine-v1.14.0+)
|
|
|
|
`_isolated` 상태는 `isolatedState` 속성이 정의된 컴포넌트 내에서만 접근 가능합니다.
|
|
|
|
```json
|
|
{
|
|
"type": "Div",
|
|
"isolatedState": { "selectedId": null, "items": [] },
|
|
"children": [
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"text": "선택됨: {{_isolated.selectedId ?? '없음'}}"
|
|
},
|
|
{
|
|
"type": "basic",
|
|
"name": "Div",
|
|
"iteration": { "source": "{{_isolated.items}}", "item": "item" },
|
|
"props": {
|
|
"className": "{{_isolated.selectedId === item.id ? 'bg-blue-100' : 'bg-white'}}"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 데이터 바인딩 표현식 (engine-v1.1.0+)
|
|
|
|
DataBindingEngine은 `{{}}` 내부에서 다양한 표현식을 지원합니다.
|
|
|
|
### 1. 변수 참조
|
|
|
|
```json
|
|
{
|
|
"text": "{{user.name}}",
|
|
"count": "{{products.total}}"
|
|
}
|
|
```
|
|
|
|
### 2. 삼항 연산자
|
|
|
|
```json
|
|
{
|
|
"className": "{{isActive ? 'bg-blue-500' : 'bg-gray-500'}}",
|
|
"text": "{{count > 0 ? count + ' items' : 'No items'}}",
|
|
"props": {
|
|
"variant": "{{user.isPremium ? 'premium' : 'standard'}}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 논리 연산자
|
|
|
|
```json
|
|
{
|
|
// AND 연산자
|
|
"if": "{{isAdmin && hasPermission}}",
|
|
|
|
// OR 연산자
|
|
"className": "{{isLoggedIn || isGuest ? 'visible' : 'hidden'}}",
|
|
|
|
// NOT 연산자
|
|
"text": "{{!isEmpty ? 'Has data' : 'Empty'}}"
|
|
}
|
|
```
|
|
|
|
### 4. 비교 연산자
|
|
|
|
```json
|
|
{
|
|
"if": "{{count >= 10}}",
|
|
"className": "{{price > 100 ? 'expensive' : 'affordable'}}",
|
|
"text": "{{status == 'active' ? 'Active' : 'Inactive'}}",
|
|
"disabled": "{{stock <= 0}}"
|
|
}
|
|
```
|
|
|
|
**지원되는 비교 연산자**:
|
|
|
|
| 연산자 | 설명 |
|
|
|--------|------|
|
|
| `==` | 같음 |
|
|
| `!=` | 다름 |
|
|
| `>` | 크다 |
|
|
| `<` | 작다 |
|
|
| `>=` | 크거나 같다 |
|
|
| `<=` | 작거나 같다 |
|
|
|
|
### 5. 리터럴 값
|
|
|
|
```json
|
|
{
|
|
// 문자열 리터럴
|
|
"className": "{{isOpen ? 'translate-x-0' : '-translate-x-full'}}",
|
|
|
|
// 숫자 리터럴
|
|
"count": "{{count || 0}}",
|
|
|
|
// boolean 리터럴
|
|
"enabled": "{{status == 'ready' ? true : false}}",
|
|
|
|
// null 리터럴
|
|
"value": "{{data || null}}"
|
|
}
|
|
```
|
|
|
|
### 6. 복합 표현식
|
|
|
|
```json
|
|
{
|
|
// 동적 CSS 클래스 생성
|
|
"className": "{{_global.sidebarOpen ? 'translate-x-0' : '-translate-x-full'}} fixed inset-y-0 left-0 z-50 w-64 transition-transform lg:relative lg:translate-x-0",
|
|
|
|
// 조건부 텍스트
|
|
"text": "{{user.isOnline && user.status == 'active' ? 'Online' : 'Offline'}}",
|
|
|
|
// 중첩 삼항 연산자
|
|
"variant": "{{score >= 90 ? 'excellent' : score >= 70 ? 'good' : 'poor'}}"
|
|
}
|
|
```
|
|
|
|
### 사용 가능 위치
|
|
|
|
- `props.*`: 모든 props 속성
|
|
- `className`: 동적 CSS 클래스
|
|
- `text`: 텍스트 내용
|
|
- `if`: 조건부 렌더링
|
|
- `actions[].payload.*`: 액션 payload
|
|
|
|
---
|
|
|
|
## Optional Chaining & Nullish Coalescing (engine-v1.1.0+)
|
|
|
|
데이터 로드 전/후 안전한 접근을 위해 Optional Chaining(`?.`)과 Nullish Coalescing(`??`)을 지원합니다.
|
|
|
|
```json
|
|
{
|
|
// Optional Chaining - null/undefined 안전 접근
|
|
// 데이터가 없어도 에러 발생 안 함
|
|
"text": "{{users?.data?.pagination?.total}}",
|
|
|
|
// Nullish Coalescing - 기본값 설정
|
|
// null 또는 undefined인 경우 기본값 반환
|
|
"count": "{{users?.data?.total ?? 0}}",
|
|
|
|
// 복합 사용 - 안전한 접근 + 기본값
|
|
"info": "{{products?.items?.length ?? 0}} items"
|
|
}
|
|
```
|
|
|
|
### 사용 사례 - API 데이터 로드 전후 처리
|
|
|
|
```json
|
|
{
|
|
// 데이터 로드 전: users가 undefined → 0 표시
|
|
// 데이터 로드 후: users.data.pagination.total 값 표시
|
|
"text": "$t:admin.users.pagination_info|total={{users?.data?.pagination?.total ?? 0}}|from={{users?.data?.pagination?.from ?? 0}}|to={{users?.data?.pagination?.to ?? 0}}"
|
|
}
|
|
```
|
|
|
|
### 동작 원리
|
|
|
|
- 데이터 소스가 로드되기 전: 변수가 `undefined`로 처리되어 `??` 이후의 기본값 반환
|
|
- 데이터 소스가 로드된 후: 실제 값으로 자동 업데이트 (리렌더링)
|
|
|
|
### 주의사항
|
|
|
|
```text
|
|
✅ API 데이터 접근 시 항상 `?.`와 `??` 함께 사용 권장
|
|
✅ 초기 렌더링 시 에러 방지를 위해 기본값 필수
|
|
✅ 간결한 표현식 사용 권장 (한 줄)
|
|
✅ 복잡한 로직은 API에서 처리 후 결과만 바인딩
|
|
깊은 중첩 경로에서도 안전하게 작동
|
|
에러 발생 시 빈 문자열 또는 기본값 반환
|
|
과도한 중첩은 가독성 저하
|
|
```
|
|
|
|
### 실제 사용 사례 - 반응형 레이아웃
|
|
|
|
```json
|
|
{
|
|
"id": "mobile_sidebar",
|
|
"type": "basic",
|
|
"name": "Div",
|
|
"props": {
|
|
"className": "{{_global.sidebarOpen ? 'translate-x-0' : '-translate-x-full'}} fixed inset-y-0 left-0 z-50 w-64 transition-transform duration-300 lg:relative lg:translate-x-0 bg-white"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 파이프 함수 (engine-v1.9.0+)
|
|
|
|
파이프 함수를 사용하면 데이터를 체이닝 방식으로 변환할 수 있습니다.
|
|
|
|
### 기본 문법
|
|
|
|
```json
|
|
{
|
|
"text": "{{created_at | date}}",
|
|
"text": "{{product.name | truncate(50)}}",
|
|
"text": "{{description | stripHtml | truncate(100)}}"
|
|
}
|
|
```
|
|
|
|
### 내장 파이프 함수
|
|
|
|
| 파이프 | 설명 | 예시 |
|
|
|--------|------|------|
|
|
| `default(value)` | null/undefined/빈값 시 대체 | `{{name \| default('Unknown')}}` |
|
|
| `fallback(value)` | null/undefined 시 대체 | `{{data \| fallback([])}}` |
|
|
| `date(format)` | 날짜 포맷 | `{{created_at \| date('YYYY-MM-DD')}}` |
|
|
| `datetime(format)` | 날짜시간 포맷 | `{{created_at \| datetime}}` |
|
|
| `relativeTime` | 상대 시간 | `{{created_at \| relativeTime}}` → "3일 전" |
|
|
| `number(decimals)` | 숫자 포맷 | `{{price \| number(2)}}` |
|
|
| `truncate(len, suffix)` | 문자열 자르기 | `{{text \| truncate(100, '...')}}` |
|
|
| `stripHtml` | HTML 태그 제거 | `{{content \| stripHtml}}` |
|
|
| `json` | JSON 문자열 변환 | `{{object \| json}}` |
|
|
| `keys` | 객체 키 배열 | `{{object \| keys}}` |
|
|
| `values` | 객체 값 배열 | `{{object \| values}}` |
|
|
| `first` | 배열 첫 요소 | `{{items \| first}}` |
|
|
| `last` | 배열 마지막 요소 | `{{items \| last}}` |
|
|
| `join(separator)` | 배열 문자열 결합 | `{{tags \| join(', ')}}` |
|
|
| `localized` | 다국어 객체 → 현재 로케일 값 | `{{title \| localized}}` |
|
|
|
|
### 파이프 체이닝
|
|
|
|
여러 파이프를 연결하여 순차적으로 변환할 수 있습니다:
|
|
|
|
```json
|
|
{
|
|
"text": "{{content | stripHtml | truncate(100) | default('내용 없음')}}"
|
|
}
|
|
```
|
|
|
|
### 주의사항
|
|
|
|
```text
|
|
✅ 파이프는 순수 함수로 동작 (side-effect 없음)
|
|
✅ 단일 | = 파이프, || = OR 연산자 (혼동 주의)
|
|
✅ 파이프 인자는 괄호 안에 작성
|
|
배열 파이프(first, last, join)는 배열 입력 필수
|
|
잘못된 입력 시 fallback 값 반환
|
|
```
|
|
|
|
---
|
|
|
|
## $get 헬퍼 함수 (engine-v1.9.0+)
|
|
|
|
동적 키를 포함한 깊은 객체 경로 접근과 폴백 값을 지원합니다.
|
|
|
|
### 기본 문법
|
|
|
|
```json
|
|
{
|
|
"text": "{{$get(object, path, fallback)}}"
|
|
}
|
|
```
|
|
|
|
- `object`: 접근할 객체
|
|
- `path`: 문자열 또는 문자열 배열 형태의 경로
|
|
- `fallback`: 값이 없을 때 반환할 기본값 (선택)
|
|
|
|
### 사용 예시
|
|
|
|
**다중 통화 가격 접근**:
|
|
|
|
```json
|
|
{
|
|
"text": "{{$get(product.multi_currency_price, [currency, 'formatted'], product.price_formatted)}}"
|
|
}
|
|
```
|
|
|
|
**다국어 객체 접근**:
|
|
|
|
```json
|
|
{
|
|
"text": "{{$get(product.name, _global.locale, product.name.ko)}}"
|
|
}
|
|
```
|
|
|
|
**중첩 설정 접근**:
|
|
|
|
```json
|
|
{
|
|
"value": "{{$get(_global.settings, ['drivers', 'mail', 'host'], 'localhost')}}"
|
|
}
|
|
```
|
|
|
|
**동적 키 접근**:
|
|
|
|
```json
|
|
{
|
|
"price": "{{$get(prices, [selectedPlan, 'monthly'], 0)}}"
|
|
}
|
|
```
|
|
|
|
### 비교: 기존 방식 vs $get
|
|
|
|
**기존 (복잡)**:
|
|
|
|
```json
|
|
{
|
|
"text": "{{item.multi_currency_unit_price[_global.preferredCurrency ?? 'KRW']?.formatted ?? item.unit_price_formatted}}"
|
|
}
|
|
```
|
|
|
|
**개선 (단순)**:
|
|
|
|
```json
|
|
{
|
|
"text": "{{$get(item.multi_currency_unit_price, [_global.preferredCurrency ?? 'KRW', 'formatted'], item.unit_price_formatted)}}"
|
|
}
|
|
```
|
|
|
|
### 주의사항
|
|
|
|
```text
|
|
✅ 순수 함수로 동작 (입력 객체 변경 없음)
|
|
✅ null/undefined 경로에서 안전하게 폴백 반환
|
|
✅ 배열 형태 경로로 동적 키 접근 가능
|
|
경로가 빈 배열이면 원본 객체 반환
|
|
```
|
|
|
|
---
|
|
|
|
## $switch 표현식 (engine-v1.9.0+)
|
|
|
|
다단계 중첩 삼항 연산자를 선언적 switch-case 패턴으로 대체합니다.
|
|
|
|
### 기본 문법
|
|
|
|
```json
|
|
{
|
|
"icon": {
|
|
"$switch": "{{tab}}",
|
|
"$cases": {
|
|
"products": "shopping-bag",
|
|
"contents": "book-open",
|
|
"policies": "file-check"
|
|
},
|
|
"$default": "file-text"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 필드 설명
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|------|------|
|
|
| `$switch` | string | ✅ | 평가할 표현식 |
|
|
| `$cases` | object | ✅ | 키-값 매핑 (키가 일치하면 해당 값 반환) |
|
|
| `$default` | any | ❌ | 일치하는 케이스가 없을 때 기본값 |
|
|
|
|
### 비교: 기존 방식 vs $switch
|
|
|
|
**기존 (복잡)**:
|
|
|
|
```json
|
|
{
|
|
"icon": "{{tab === 'products' ? 'shopping-bag' : tab === 'contents' ? 'book-open' : tab === 'policies' ? 'file-check' : 'file-text'}}"
|
|
}
|
|
```
|
|
|
|
**개선 (단순)**:
|
|
|
|
```json
|
|
{
|
|
"icon": {
|
|
"$switch": "{{tab}}",
|
|
"$cases": {
|
|
"products": "shopping-bag",
|
|
"contents": "book-open",
|
|
"policies": "file-check"
|
|
},
|
|
"$default": "file-text"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 사용 위치
|
|
|
|
- 모든 props 속성
|
|
- `text` 속성
|
|
- `className` 속성
|
|
- computed 속성 (레이아웃 수준)
|
|
|
|
### 주의사항
|
|
|
|
```text
|
|
✅ $cases 키와 $switch 결과가 정확히 일치해야 함 (===)
|
|
✅ $default가 없고 일치하는 케이스가 없으면 undefined 반환
|
|
✅ iteration/cellChildren 컨텍스트에서 각 아이템별 독립 평가
|
|
$cases 값에 추가 표현식 바인딩 불가 (정적 값만)
|
|
```
|
|
|
|
---
|
|
|
|
## 반복 컨텍스트에서의 표현식 (engine-v1.2.0+)
|
|
|
|
DataGrid의 `cellChildren`, 리스트 아이템 등 **반복 렌더링 컨텍스트**에서도 복잡한 표현식을 사용할 수 있습니다.
|
|
|
|
```json
|
|
{
|
|
"columns": [
|
|
{
|
|
"key": "status",
|
|
"label": "$t:user.status",
|
|
"cellChildren": [
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"props": {
|
|
"className": "{{row.status_variant === 'success' ? 'bg-green-100 text-green-800' : row.status_variant === 'danger' ? 'bg-red-100 text-red-800' : 'bg-gray-100 text-gray-800'}} px-2.5 py-0.5 rounded-full text-xs font-medium"
|
|
},
|
|
"text": "{{row.status_label}}"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 지원 기능
|
|
|
|
| 기능 | 설명 | 예시 |
|
|
|------|------|------|
|
|
| 삼항 연산자 | 조건부 값 선택 | `{{row.active ? 'active' : 'inactive'}}` |
|
|
| 중첩 삼항 | 다중 조건 처리 | `{{a ? 'x' : b ? 'y' : 'z'}}` |
|
|
| 논리 연산자 | AND/OR 조건 | `{{row.class \|\| 'default'}}` |
|
|
| 문자열 리터럴 | 따옴표 내 특수문자 | `{{active ? 'px-2.5' : 'px-1'}}` |
|
|
|
|
### 반복 컨텍스트 변수
|
|
|
|
- `row`: 현재 행 데이터 (DataGrid)
|
|
- `value` / `$value`: 현재 셀 값
|
|
- `item`: 현재 리스트 아이템 (ul/li 패턴)
|
|
- `index`: 현재 인덱스
|
|
|
|
### 내부 동작
|
|
|
|
템플릿 엔진은 반복 렌더링 시 `G7Core.renderItemChildren` 헬퍼를 사용하여 각 아이템마다 독립적으로 표현식을 평가합니다. 캐싱으로 인한 데이터 중복 문제를 방지하기 위해 `skipCache` 옵션이 자동으로 적용됩니다.
|
|
|
|
---
|
|
|
|
## text 속성 복합 바인딩 (engine-v1.2.0+)
|
|
|
|
`text` 속성에서 데이터 바인딩과 다국어(`$t:`)를 조합한 복합 표현식을 사용할 수 있습니다.
|
|
|
|
```json
|
|
{
|
|
"id": "error_message",
|
|
"type": "basic",
|
|
"name": "P",
|
|
"text": "{{_global.errorMessage || $t:common.error_occurred}}"
|
|
}
|
|
```
|
|
|
|
### 동작 방식
|
|
|
|
1. `_global.errorMessage`가 설정되어 있으면 해당 값 표시
|
|
2. 설정되지 않으면 `$t:common.error_occurred` 번역 키의 값 표시
|
|
|
|
### 삼항 연산자와 $t: 조합
|
|
|
|
```json
|
|
{
|
|
"text": "{{isError ? $t:common.error : $t:common.success}}"
|
|
}
|
|
```
|
|
|
|
### 주요 특징
|
|
|
|
```text
|
|
✅ $t: 토큰은 따옴표로 감싸지 않아도 자동으로 문자열로 처리됨
|
|
✅ 표현식 평가 후 $t: 결과가 자동으로 번역됨
|
|
✅ ||, &&, ? : 등 모든 JavaScript 표현식 사용 가능
|
|
```
|
|
|
|
---
|
|
|
|
## 컨텍스트 변수 레퍼런스 (engine-v1.11.0+)
|
|
|
|
레이아웃 JSON 표현식에서 사용 가능한 **특수 컨텍스트 변수** 목록입니다. 각 변수는 특정 스코프에서만 접근 가능합니다.
|
|
|
|
### 상태 접근 변수
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `_global` | 전역 상태 (앱 전체 공유, 페이지 이동 시 유지) | 어디서나 |
|
|
| `_local` | 로컬 상태 (현재 레이아웃 내) | 어디서나 |
|
|
| `_isolated` | 격리된 상태 (`isolatedState` 컴포넌트 내) | isolatedState 영역 |
|
|
| `_computed` | 계산된 속성 (computed 정의 기반) | 어디서나 |
|
|
|
|
### 이벤트/콜백 변수
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `$event` | DOM 이벤트 객체 (`type` 필드 사용 시) | 액션 핸들러 params |
|
|
| `$args` | 커스텀 콜백 인자 배열 (`event` 필드 사용 시) | 액션 핸들러 params |
|
|
| `$eventData` | 컴포넌트 이벤트 데이터 (engine-v1.11.0+) | onComponentEvent 핸들러 |
|
|
|
|
### 계층 접근 변수 (engine-v1.16.0+)
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `$parent` | 부모 컴포넌트의 상태 접근 | 모달, expandChildren |
|
|
| `$root` | 루트 컴포넌트의 상태 접근 | 중첩 레이아웃 |
|
|
|
|
```json
|
|
// 모달에서 부모 _local 접근
|
|
{ "text": "{{$parent._local.selectedUser?.name}}" }
|
|
|
|
// expandChildren에서 부모 전역 상태 접근
|
|
{ "value": "{{$parent._global.currency}}" }
|
|
```
|
|
|
|
```text
|
|
$parent._local은 모달 마운트 시 스냅샷 — 모달 열린 후 부모 _local 변경 시 반영 안됨
|
|
✅ 리액티브 데이터 필요 시: setState로 모달 자체 _local에 저장 후 사용
|
|
✅ setState target: "$parent._local" 또는 "$parent._global"로 부모 상태 직접 수정 가능
|
|
```
|
|
|
|
### 반복/정렬 컨텍스트 변수
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `row` | 현재 행 데이터 | DataGrid cellChildren, subRowChildren |
|
|
| `item` / `$item` | 현재 반복 아이템 | iteration, sortable itemTemplate |
|
|
| `index` / `$index` | 현재 반복 인덱스 | iteration, sortable itemTemplate |
|
|
| `$value` | 현재 셀 값 | DataGrid cellChildren |
|
|
| `$sortedItems` | 정렬 완료 후 재배열된 배열 (engine-v1.14.0+) | sortable onSortEnd 이벤트 |
|
|
| `$oldIndex` / `$newIndex` | 정렬 전/후 인덱스 (engine-v1.14.0+) | sortable onSortEnd 이벤트 |
|
|
| `$activeId` | 드래그 중인 아이템 ID (engine-v1.14.0+) | sortable onSortStart 이벤트 |
|
|
|
|
### sequence 핸들러 컨텍스트 변수
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `$prev` | 직전 액션의 결과값 (직접 참조) | sequence 내부 액션 |
|
|
| `$results` | 모든 이전 액션 결과 배열 | sequence 내부 액션 |
|
|
|
|
```json
|
|
{
|
|
"handler": "sequence",
|
|
"actions": [
|
|
{
|
|
"handler": "apiCall",
|
|
"target": "/api/products/{{row.id}}",
|
|
"params": { "method": "GET" }
|
|
},
|
|
{
|
|
"handler": "setState",
|
|
"params": {
|
|
"target": "local",
|
|
"productDetail": "{{$prev.data}}"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### onSuccess/onError 콜백 변수
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `response` | API 성공 응답 전체 | onSuccess 콜백 |
|
|
| `response.data` | API 응답 data 필드 | onSuccess 콜백 |
|
|
| `result` | `response`와 동일 (하위 호환) | onSuccess 콜백 |
|
|
| `error.message` | 번역된 에러 메시지 | onError 콜백 |
|
|
| `error.status` | HTTP 상태 코드 | onError 콜백 |
|
|
| `error.errors` | 필드별 에러 (422) | onError 콜백 |
|
|
| `error.data` | 전체 API 응답 | onError 콜백 |
|
|
|
|
```text
|
|
필수: response 사용 ($response 사용 금지 — $ 접두사 없음)
|
|
❌ "{{$response.data}}" → undefined
|
|
✅ "{{response.data}}" → 정상 동작
|
|
```
|
|
|
|
### URL/라우트 변수
|
|
|
|
| 변수 | 설명 | 사용 범위 |
|
|
|------|------|----------|
|
|
| `route` | URL 경로 파라미터 (예: `/users/:id` → `route.id`) | 어디서나 |
|
|
| `query` | 쿼리 스트링 파라미터 (예: `?page=1` → `query.page`) | 어디서나 |
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [다국어 처리](data-binding-i18n.md) - $localized(), $t:, 컴포넌트 다국어 처리
|
|
- [g7core-api.md](g7core-api.md) - G7Core 전역 API 레퍼런스
|
|
- [index.md](index.md) - 프론트엔드 가이드 인덱스
|
|
- [layout-json.md](layout-json.md) - 레이아웃 JSON 스키마
|
|
- [data-sources.md](data-sources.md) - 데이터 소스 시스템
|
|
- [state-management.md](state-management.md) - 전역 상태 관리
|