> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/dev-guide/dev-start/markdown/mui-x.md).
# 데이터 그리드 (Mui-X)
X2BEE BO(BackOffice) 템플릿은 목록 조회 및 데이터 관리(입력/수정/삭제)를 효율적으로 처리하기 위해 [MUI-X 데이터 그리드](https://mui.com/x/react-data-grid/)를 활용합니다. 이 템플릿은 BO 프로그램 전반에 걸쳐 폭넓게 사용되며, MUI를 확장하여 추가 기능을 제공함으로써 개발 편의성을 크게 향상시킵니다.
***
## X2beeDataGrid
{% stepper %}
{% step %}
### 데이터 그리드 파일 구조
* 파일 위치는 `/src/lib/x2bee-data-grid/*`입니다.
| **파일명** | **설명** |
| -------------------------------- | ------------------------------------------------------------------------- |
| **x2bee-data-grid.tsx** | 화면에 그려지는 그리드 컴포넌트입니다. |
| **x2bee-data-grid-utils.ts** | 그리드 컴포넌트에서 사용되는 함수들로, 다회 사용되거나 분리가능하고 상대적으로 긴 코드들을 컴포넌트에서 분리해 둔 유틸 파일입니다. |
| **x2bee-data-grid-constants.ts** | 그리드에서 사용되는 상수들을 관리하는 파일입니다. |
| **x2bee-data-grid-types.ts** | 그리드에서 사용되는 타입들을 관리하는 파일입니다. |
| **x2bee-grid-date-picker.tsx** | 그리드에서 사용되는 date picker 관련 파일입니다. |
| **use-x2bee-data-grid.ts** | 그리드에 관련된 hook이 선언된 파일입니다. |
| **x2bee-data-grid-context.tsx** | 그리드를 감싼 컴포넌트로 dataRef를 주입해줍니다. |
| {% endstep %} | |
{% step %}
### 데이터 그리드 컴포넌트 제공 옵션
* [MUI 그리드 옵션](https://mui.com/x/api/data-grid/data-grid-premium/)에서 MUI 제공 옵션에 대해 자세하게 확인할 수 있습니다.
* X2beeDataGrid 컴포넌트에서 추가적으로 제공하는 옵션은 다음과 같습니다.
| **옵션** | **설명** |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dataRef | MUI에서 제공되는 API(apiRef) 외에 추가적으로 제공되는 함수들을 포함한 ref 객체입니다. [소스](https://gitlab.x2bee.com/team-project/ec3-1/bo-mui/-/blob/main/src/lib/x2bee-data-grid/x2bee-data-grid-types.ts) 페이지의 X2beeDataGridDataRefType에서 제공되는 기능들을 확인할 수 있습니다. 대표적으로 그리드에서 관리되는 CUD의 row state별로 row 리스트를 가져올 수 있으며, 버튼의 행 관리 기능도 함수로 제공됩니다. |
| hideDeleteRow | Row 삭제 시 그리드에서 노출 여부를 설정합니다. 기본값은 false입니다. |
| enableRowState | Row의 상태(CUD)를 표시할지 여부를 설정합니다. 기본값은 false입니다. |
| fetchSave | Row의 저장 버튼에 대한 콜백 함수입니다. 선언 시 저장 버튼이 노출됩니다. |
| paginationProps | 페이지네이션을 구현하기 위해, 필요하지 않은 경우 MUI 데이터 그리드의 기본 속성 `rows`를 간단히 사용할 수 있습니다. 기본값으로 최소한 빈 배열을 제공하는 것이 필수적입니다. `paginationProps`가 없으면 `rows`는 필수로 지정되어야 합니다. 이 접근 방식은 MUI의 페이지네이션 구현에 의존하지 않고 X2beeDataGrid 내에서 모든 상태를 내부적으로 관리합니다. 입력 타입은 `X2beeSimplePagination`이며, `paginationProps`, 기존의 `rows`, `pagination`, `pageSizeOptions`와 동시에 사용할 수 없습니다. `paginationProps` 내의 `pageSizeOptions`는 옵션으로 지정할 수 있으며, 제공되지 않을 경우 기본값은 `[100, 500, 1000, 5000, 10000]`입니다. |
| enableNoColumn | 이 옵션은 기본 열 "No"의 가시성을 설정할 수 있게 해줍니다. 기본값은 true입니다. |
| {% endstep %} | |
{% step %}
### 컴포넌트 사용 가이드
X2beeDataGrid 컴포넌트는 DataGridPremium 컴포넌트를 감싸, 내부적으로 MUI에서 제공하지 않는 추가, 수정, 삭제 상태를 관리하는 역할을 합니다.
* 그리드는 자체적으로 공간을 가지지 않으므로, 반드시 상위 태그 및 컴포넌트에서 공간을 확보해야 정상적으로 렌더링됩니다. 참고:
* 필수로 입력해야 하는 옵션값은 `columns`와 `rows` 또는 `paginationProps`입니다. `paginationProps`와 `rows`는 반드시 둘 중 하나만 입력해야 합니다.
예시:
{% code title="사용 예시" %}
```jsx
columns.map((el) => el.field) },
baseCheckbox: { disabled: baseCheckboxDisable }
}}
slots={{
toolbar: () => CustomButtons({
changeCheckBoxSelectable: (value) => setBaseCheckboxDisable(!value)
})
}}
// pagination용 추가가 필요한 props
paginationProps={{ fetch: async (paginationModel) => fetch(paginationModel.page, paginationModel.pageSize) }}
/>
```
{% endcode %}
{% endstep %}
{% endstepper %}
***
## 그리드 API
{% stepper %}
{% step %}
### 1. 커스텀 그리드 API(dataRef)
* MUI에서 제공되는 그리드 API는 [MUI apiRef 정보](https://mui.com/x/api/data-grid/grid-api/)에서 자세하게 확인할 수 있습니다.
* X2beeDataGrid 컴포넌트 내부의 상태값등에 접근하며, 커스텀 기능들을 호출가능하게 해주는 API 객체입니다.
| **기능** | **설명** |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| useDataRef() | 이 훅은 `dataRef`에 대한 객체를 제공합니다. 예: const dataRef = useDataRef(); \ |
| dataRef.current.all() | 오브젝트는 `update`, `create`, `delete`라는 세 가지 프로퍼티를 포함하여 반환됩니다. 각 프로퍼티는 수정된 행, 추가된 행, 삭제된 행을 배열 형태로 제공합니다. |
| dataRef.current.grid() |
다음은 반환되는 함수 목록 입니다. selectClear, selectDelete, allClear, addRow, setUpdateRows export type X2beeDataGridDataRefGridFnType = { selectClear: () => void // 선택 행 변경취소 selectDelete: () => void // 선택 행 삭제 allClear: () => void // 전체 행 변경취소 addRow: () => void // 행 추가 save: () => void // fetchSave 호출 validation: ValidationFunction // update 및 create 행 valid asyncValidation: AsyncValidationFunction // update 및 create 행 valid를 비동기로 시행 setUpdateRows: (ids: GridRowId\[]) => void // updateRowId를 직접 추가 }
|
| dataRef.current.fetch() | 수동으로 grid에 fetch를 진행할때 사용됩니다. `paginationProps`을 사용하여 fetch를 구현한경우 반드시 해당 기능으로 fetch를 진행해야 합니다. |
| dataRef.current.create() / dataRef.current.update() / dataRef.current.delete() | `dataRef.current.all()`에서 제공되는 값들을 별도로 제공하는 함수입니다. |
| dataRef.current.validation() | 그리드의 모든 editRow에대해 validation을 진행합니다. |
| {% endstep %} | |
{% step %}
### 2. API 객체 활용 가이드
MUI에서는 그리드를 제어할 수 있는 API 객체를 제공합니다. X2beeDataGrid에서도 그리드의 등록, 수정, 삭제 관련 기능 및 데이터를 API 객체를 통해 활용할 수 있습니다.
예시:
{% code title="사용 예시" %}
```jsx
const dataRef = useDataRef();
const apiRef = useGridApiRef();
return (
<>
데이터 출력{JSON.stringify(showData)} {
const errorMessage = validation();
if (errorMessage) alert(errorMessage);
}}
/>
);
```
{% endcode %}
{% endstep %}
{% endstepper %}
***
## X2beeDataColDef
{% stepper %}
{% step %}
#### 1. 그리드 컬럼 제공 옵션
* MUI에서 제공하는 옵션은 [MUI 컬럼 옵션](https://mui.com/x/api/data-grid/grid-col-def/) 에서 확인 할 수 있습니다.
* X2beeGridColDef 에서 제공하는 추가옵션은 다음과 같습니다.
| **옵션명** | **타입** | **설명** |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visible | boolean | 열이 초기에 노출될지 여부를 설정 가능합니다. initialState의 column hide를 단순화 한 옵션입니다. |
| defaultValue | any | 열 추가시 기본으로 지정되는 값입니다. |
| validBlank | boolean | 셀 수정시, 빈값을 허용할지 여부를 설정 가능합니다. |
| validation | X2beeGridValidation\[] | 셀 수정시, 값 검증을 위해 사용됩니다. `valid`와 `message`를 prop으로 가지며, `valid`의 리턴값이 `false`일 경우, 셀에서 `message`가 오류로 출력됩니다. 제공되는 params는 다음과 같습니다. { id, value, field, row, otherProps, apiRef } |
| dateEditor | Object | 셀 수정시, DatePicker 사용할 옵션을 설정합니다. `type`을 통해 노출할 달력 형식을 지정할 수 있으며 결과 값을 `dateFormat`을 통해 지정할 수 있습니다. 제공되는 params는 다음과 같습니다. { type: 'date' \| 'dateTime', dateFormat: string, minDate: string, maxDate: string } |
| dynamicEditable | [코드 참조](https://gitlab.x2bee.com/team-project/ec3-1/bo-mui/-/blob/main/src/lib/x2bee-data-grid/x2bee-data-grid-types.ts)`X2beeGridColDef`의 `dynamicEditable`참조. | 다른 셀의 값에 의해 해당 셀의 `editable`여부가 동적으로 변경되는 옵션입니다. 사용시 `editable`은 따로 선언해주지 않으셔도 됩니다. 제공되는 params는 다음과 같습니다. { otherProps: GridValidRowModel, apiRef: MutableRefObject, dataRef: MutableRefObject\ } 리턴으로 돌려줘야하는 값은 다음과 같습니다. { editable: boolean, value?: string } |
| {% endstep %} | | |
{% step %}
#### 2. 확장된 컬럼 타입 정의 및 유효성 검증 가이드
MUI 에서 제공하는 `GridColDef` 타입을 상속 받아 옵션을 추가한 컬럼 타입입니다. 기존의 MUI의 기능 및 X2beeDataGrid에서 추가적으로 제공하는 기능들을 정의 가능합니다.
예시:
{% code title="cols 예시" %}
```ts
const cols: X2beeGridColDef[] = [
{
headerName: '상품번호',
field: 'goodsNo',
editable: true,
width: 150,
validBlank: '상품번호를 입력해 주세요',
validation: [
{
valid: (params) => {
if (params.otherProps.goodsType === '묶음상품') {
const typeInt = parseInt(params.value as string, 10) ?? 1000
return typeInt >= 1000
}
return true
},
message: '묶음상품인경우 상품번호가 1000보다 커야합니다'
},
{
valid: (params) => {
if (params.otherProps.goodsType === '일반상품') {
const typeInt = parseInt(params.value as string, 10) ?? 1000
return typeInt < 1000
}
return true
},
message: '일반상품인경우 상품번호가 1000보다 작아야합니다'
}
]
},
{
headerName: '상품명',
field: 'goodsNm',
type: 'string',
editable: true,
width: 150,
validBlank: true,
validation: [
{
valid: (params) => {
const allRow = params.apiRef.current.getRowModels()
const allRowIds = params.apiRef.current.getAllRowIds()
return allRowIds.every(
(id) => params.id === id || allRow.get(id)?.[params.field] !== params.value
)
},
message: '중복된 상품명은 사용할수 없습니다.'
}
]
},
{
headerName: '상품타입',
field: 'goodsType',
type: 'singleSelect',
valueOptions: [...GoodsTypeArr],
defaultValue: GoodsTypeArr[0],
editable: true,
width: 150
},
{
headerName: '가격',
field: 'price',
type: 'number',
editable: true,
width: 150,
validation: [
{
valid: (params) => (params.value as number) > 0,
message: '가격은 0보다 커야합니다'
}
]
},
{
headerName: '등록일',
field: 'regDate',
editable: true,
width: 150,
defaultValue: dayjs().format(),
dateEditor: {
type: 'date',
dateFormat: 'YYYYMMDD',
minDate: dayjs().format(),
maxDate: '2050-12-31'
}
}
]
```
{% endcode %}
{% endstep %}
{% endstepper %}
***
## Common-toolbar
{% stepper %}
{% step %}
#### 1. 툴바 및 버튼 컴포넌트 구조
| **컴포넌트** | **타입** | **설명** |
| ----------------- | -------- | ------------------------------------- |
| Toolbar.Container | | |
| Toolbar.Button | add | 행 추가 기능입니다. |
| | remove | 행 삭제 기능입니다. |
| | reset | 선택한 행 초기화 기능입니다. |
| | resetAll | 모든 행에대한 초기화 기능입니다. |
| | save | 데이터 그리드에 fetchSave로 입력한 함수를 실행합니다. |
| | excel | 엑셀 다운로드 기능을 제공합니다. |
| | custom | 커스텀 버튼을 제공합니다. 버튼 자체로는 기능을 제공하지 않습니다. |
| {% endstep %} | | |
{% step %}
#### 2. 툴바 확장 및 커스터마이징 가이드
이 가이드는 MUI에서 제공하는 `GridToolbarContainer`를 감싸 기능을 추가한 컴포넌트를 상세히 설명합니다.
그리드에 필요한 기본 기능인 열 추가, 삭제, 초기화 외에도 커스텀 버튼 및 엑셀 다운로드 버튼을 추가할 수 있는 방법을 안내합니다.
예시:
{% code title="툴바 슬롯 예시" %}
```jsx
(
console.log('등록 팝업')} />
console.log('일괄 변경')} />
}
rightSlot={
<>
console.log('복사')} />
}
/>
)
}}
/>
```
{% endcode %}
{% endstep %}
{% endstepper %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://tech.x2bee.com/dev-guide/dev-start/markdown/mui-x.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.