# 행 상세

마스터·상세는 주문 목록에서 한 주문의 품목이나 배송 이력을 펼쳐 보는 구성입니다. 상위 행은 요약이고 그 아래 전체 폭의 패널이 상세 내용을 담습니다.

Canonical: https://grid.syidax.com/ko/docs/features/master-detail/

<a id="understand"></a>

## 동작 원리와 선택 기준

단순 설명은 detailCellRenderer, 별도의 표가 필요하면 detailGridOptions와 getDetailRowData를 사용합니다. 펼침 상태를 유지하려면 getRowId로 안정적인 ID를 제공하세요.

이 기능을 제품에서 사용하려면 Pro 패키지와 유효한 라이선스가 필요합니다. 설정 이름이 같더라도 Community에서 Pro 기능이 활성화되는 것은 아닙니다.

코드의 grid는 설치와 연결 장에서 준비한 Grid 요소입니다. 예제마다 필요한 데이터·설정을 확인하고, 코드에서 소개하는 앱 함수와 서버 주소는 프로젝트에 맞게 구현하세요.

- [설치와 연결 · 공통 예제 데이터](https://grid.syidax.com/ko/docs/guides/getting-started.md)

<a id="example-1"></a>

## 예제 1. 문자 설명 패널

품목 표가 필요 없는 간단한 메모는 안전한 텍스트 출력으로 구성합니다.

```javascript
grid.masterDetail = true;
grid.detailRowHeight = 120;
grid.detailCellRenderer = ({ row }) => ({
  kind: 'text', text: String(row.memo ?? '등록된 메모가 없습니다.'),
});
```

결과 확인: 주문을 펼치면 해당 행의 메모가 표시됩니다. 패널은 별도 원본 주문이나 페이지 행 수로 취급하지 않습니다.

<a id="example-2"></a>

## 예제 2. 주문 품목을 하위 표로 표시

각 원본 행에 items 배열이 있는 경우입니다. 사용자 정의 렌더러를 해제한 뒤 하위 표 옵션을 지정합니다.

```javascript
grid.detailCellRenderer = undefined;
grid.detailGridOptions = {
  columnDefs: [
    { field: 'product', headerName: '품목' },
    { field: 'quantity', headerName: '수량' },
  ], height: '180px',
};
grid.getDetailRowData = ({ row }) => row.items ?? [];
grid.detailRowHeight = 200;
```

결과 확인: 부모 주문마다 해당 items만 하위 Grid에 전달됩니다. 부모의 모든 설정이 자식에게 자동으로 복사되지는 않습니다.

<a id="example-3"></a>

## 예제 3. 펼칠 때 서버에서 읽기

getDetailRowData에서 Promise를 반환하면 요청 동안 하위 표가 로딩 상태를 보여 줍니다. 앱 서버가 제공하는 상세 조회 함수와 연결하고, 실패 메시지와 재시도를 앱에서 설계합니다.

결과 확인: 한 번 펼치는 동안 결과를 재사용하고 접으면 캐시가 해제됩니다. 전체 펼치기는 많은 상세 요청을 발생시킬 수 있으므로 데이터 양을 고려하세요.

<a id="pitfalls"></a>

## 조합할 때와 문제를 해결할 때

detailCellRenderer가 있으면 선언형 하위 Grid보다 우선합니다. 두 방식을 동시에 켜 놓고 하위 표가 생기기를 기대하지 마세요.

중첩 상세는 깊이 제한이 있습니다. 재귀적인 자기 참조 옵션을 만들지 말고 실제 업무에 필요한 단계까지만 구성합니다.

<a id="related-api"></a>

## 이 기능에 사용하는 API

- [masterDetail](https://grid.syidax.com/ko/docs/options/masterDetail.md) — 주문 아래 품목처럼 원본 행을 펼쳐 전체 폭의 상세 패널을 표시합니다.
- [detailRowHeight](https://grid.syidax.com/ko/docs/options/detailRowHeight.md) — 펼친 상세 패널의 높이를 픽셀로 정합니다.
- [detailCellRenderer](https://grid.syidax.com/ko/docs/options/detailCellRenderer.md) — 상세 패널의 내용을 text·html·vnode 계약으로 만듭니다. 선언형 하위 Grid보다 우선합니다.
- [detailGridOptions](https://grid.syidax.com/ko/docs/options/detailGridOptions.md) — 상세 패널에 자동으로 생성할 하위 Grid의 열과 옵션입니다. getDetailRowData와 함께 사용합니다.
- [getDetailRowData](https://grid.syidax.com/ko/docs/options/getDetailRowData.md) — 펼친 부모 행에 해당하는 상세 행을 배열 또는 Promise로 반환합니다. 한 번 펼치는 동안 결과를 재사용합니다.
- [detailNestingLevel](https://grid.syidax.com/ko/docs/options/detailNestingLevel.md) — 중첩 상세 Grid의 깊이입니다. 자동 생성된 하위 Grid는 부모가 설정하며 재귀 깊이 제한에 사용됩니다.
- [setDetailRowExpanded](https://grid.syidax.com/ko/docs/methods/setDetailRowExpanded.md) — 안정적인 부모 행 ID로 상세 패널을 펼치거나 접습니다.
- [expandAllDetailRows](https://grid.syidax.com/ko/docs/methods/expandAllDetailRows.md) — 현재 필터를 통과한 전체 페이지의 상세 행을 펼칩니다. 지연 조회를 사용하는 경우 요청량을 고려하세요.
- [collapseAllDetailRows](https://grid.syidax.com/ko/docs/methods/collapseAllDetailRows.md) — 열린 상세 행을 모두 접고 해당 패널의 자원을 정리합니다.
- [detailRowToggled](https://grid.syidax.com/ko/docs/events/detailRowToggled.md) — 부모 행의 상세 패널 펼침 상태가 바뀌었을 때 발생합니다.
- [detailRowCreated](https://grid.syidax.com/ko/docs/events/detailRowCreated.md) — 부모 행의 상세 패널이 생성되었을 때 발생합니다. 행 ID와 부모 데이터로 앱 자원을 연결할 수 있습니다.
- [detailRowDestroyed](https://grid.syidax.com/ko/docs/events/detailRowDestroyed.md) — 상세 패널이 해제되었을 때 발생합니다. 앱에서 연결한 자원도 해당 rowId 기준으로 정리합니다.

<a id="next"></a>

## 함께 읽기

- [행·열·ID의 관계](https://grid.syidax.com/ko/docs/guides/concepts.md)
- [결과와 이벤트 연결](https://grid.syidax.com/ko/docs/guides/data-event-access.md)
- [Features에서 살펴보기](https://grid.syidax.com/grid/master-detail) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.