Grid
리스트 형태의 표를 렌더링하는 컴포넌트입니다. 가장 많이 접하는 형태의 컴포넌트로, 컬럼의 정의를 통해서 쉽게 구현이 가능합니다. 또한 내부적으로 VirtualList 컴포넌트를 사용하고 있으므로 뛰어난 스크롤 성능을 보여줍니다.
export function GridBasic(){
const [ data ] = useState(Array.from(Array(10000)).map((_, idx)=>({item1:idx, item2:idx, item3:idx})))
return <Frame>
<Flex flexHeight="200px">
데이터 갯수 : {data.length}
<Grid
headers={[
{label:'항목1', targetId:'item1'},
{label:'항목2', targetId:'item2'},
{label:'항목3', targetId:'item3'},
]}
data={data}
/>
</Flex>
</Frame>
}
data 속성
data
data = T[]
그리드에 표시할 소스 데이터를 지정합니다. Object 의 배열형태입니다. Object 의 필드 중 표시할 데이터를 headers 에 지정하면 간단히 표시할 수 있습니다.
setData
setData = (data:T[])=>void
그리드의 컬럼에 formType 을 지정하는경우 Form 컴포넌트와 동일하게 setData 를 통해서 데이터를 업데이트 받을 수 있습니다.
headers 기본 속성
headers = GridHeader<T>[]
headers 는 그리드에 렌더링될 컬럼을 정의합니다.
label
label = string
헤더에 표시될 내용을 정의합니다.
targetId
targetId = keyof T
data 상에 표시할 항목을 지정합니다. 값은 T Object 의 속성명입니다.
headers Form 속성
(optional) formType
formType = GridFormItemType = 'input' | 'select' | 'check' | 'radio'
컬럼을 일반 텍스트가 아닌 form 으로 처리합니다. 특성은 Form 과 동일합니다.
(optional) required
required = GridValue<T, boolean> | boolean
form 의 required 속성을 지정합니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) disabled
disabled = GridValue<T, boolean> | boolean
form 의 disabled 속성을 지정합니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) editable
editable = GridValue<T, boolean> | boolean
form 의 편집가능 여부를 지정합니다. 이 값을 false 로 하면 formType 이 지정되더라도 일반 텍스트로 렌더링됩니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) item
item = GridValue<T, SelectItem<unknown>[]> | SelectItem<unknown>[];
formType 이 select 일때 option 을 정의합니다. Select 컴포넌트의 item 과 동일합니다.
GridValue 으로 조건부 처리가 가능합니다.
(optional) selectType
selectType = SelectType
formType 이 select 일때 렌더링 타입을 지정합니다. Select 컴포넌트의 type 과 동일합니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) maxLength
maxLength = GridValue<T, number> | number
form 의 maxLength 속성을 지정합니다. GridValue 으로 조건부 처리가 가능합니다.
headers 스타일 속성
(optional) width
width = number|string
컬럼의 폭을 지정합니다. 기본적으로 픽셀이고, widthUnit='percentage' 로 지정하면 퍼센트로 지정할 수 있습니다.
컬럼 각각의 폭은 전체 그리드 폭을 균등하게 나눠 갖습니다. 이 width 값을 지정하면 다른 컬럼보다 우선적으로 폭을 부여받습니다. 이후 width 값이 없는 컬럼들이 나머지 폭을 균등하게 나눠 갖습니다.
이러한 특성을 잘 고려하여 컬럼의 폭을 정해야합니다.
(optional) widthUnit
width = GridColumnWidthUnit = 'pixel'|'percentage'
width 의 단위를 정합니다. 기본값은 pixel 입니다.
(optional) minWidth
minWidth = number
컬럼의 최소폭을 지정합니다. 컬럼은 그리드의 폭에 따라 작아지게 되는데 이때 이 값 이하로는 작아지지 않게 됩니다.
(optional) renderer
renderer = GridRenderFunction<T> = (header: GridHeader<T>, item: T, headers: GridHeader<T>[], data: T[]) => JSX.Element
이 함수를 이용해서 그리드의 컬럼을 커스텀 렌더링 할 수 있습니다.
파라미터는 다음과 같습니다.
파라미터 | 타입 | 설명 |
---|---|---|
header | GridHeader | 현재 컬럼의 header 정보 |
item | T | 현재 컬럼이 속해있는 row data 정보 |
headers | GridHeader[] | 전체 headers 정보 |
data | T[] | 전체 data 정보 |
(optional) headerRenderer
headerRenderer = GridHeaderRenderFunction<T> = (header: GridHeader<T>, headers: GridHeader<T>[]) => JSX.Element
이 함수를 이용해서 그리드의 헤더정보를 커스텀 렌더링 할 수 있습니다.
파라미터는 다음과 같습니다.
파라미터 | 타입 | 설명 |
---|---|---|
header | GridHeader | 현재 컬럼의 header 정보 |
headers | GridHeader[] | 전체 headers 정보 |
(optional) enableCheckAll
enableCheckAll = boolean
이 값을 true 로 설정하면 header 의 formType 이 "check" 일때 헤더에 전체 체크기능이 생깁니다.
(optional) onChange
onChange = (param: GridEventParam<T>) => void
특정 컬럼의 값이 변경되었을때 호출됩니다. 이벤트의 파라미터는 여기를 참조하세요.
(optional) defaultTextValue
defaultTextValue = GridValue<T, string> | string
헤더에 대한 필드에 값이 없을때 기본으로 나오는 텍스트를 지정합니다. 타입은 string 과 GridValue 으로 조건부 처리가 가능합니다.
(optional) textFormat
interface GridFormatType {
searchValue:RegExp;
replaceValue:string;
}
textFormat = GridValue<T, GridFormatType | string> | GridFormatType
주어진 조건으로 텍스트를 포맷팅 합니다. 타입은 GridFormatType 과 GridValue 으로 조건부 처리가 가능합니다.
GridValue 함수에서 string 을 리턴하면 이 값으로 대체되고, GridFormatType 으로 리턴하면 searchValue 를 찾아서 replaceValue 로 String.replace 처리합니다.
(optional) ellipsis
ellipsis = GridValue<T, boolean> | boolean
텍스트의 ellipsis 처리여부입니다. 타입은 boolean 과 GridValue 으로 조건부 처리가 가능합니다.
(optional) textAlign
GridTextAlign = 'left' | 'center' | 'right'
textAlign = GridValue<T, GridTextAlign> | GridTextAlign
텍스트의 정렬 설정입니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) color
color = GridValue<T, CSSProperties['color']> | CSSProperties['color']
텍스트의 색상 설정입니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) fontSize
fontSize = GridValue<T, CSSProperties['fontSize']> | CSSProperties['fontSize'];
텍스트의 fontSize 설정입니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) fontWeight
fontWeight = GridValue<T, CSSProperties['fontWeight']> | CSSProperties['fontWeight']
텍스트의 색상 설정입니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) whiteSpace
whiteSpace = GridValue<T, CSSProperties['whiteSpace']> | CSSProperties['whiteSpace']
텍스트의 fontWeight 설정입니다. GridValue 으로 조건부 처리가 가능합니다.
(optional) textStyle
textStyle = GridValue<T, CSSProperties> | CSSProperties
텍스트의 style 설정입니다. GridValue 으로 조건부 처리가 가능합니다.
headers 엑셀 속성
(optional) excludeInExcel
excludeInExcel = boolean
해당 헤더를 엑셀 export 대상에서 제외합니다.
(optional) optionValueInExcel
optionValueInExcel = boolean
엑셀 export 시에 formType 이 select 인 컬럼의 처리방식을 조정합니다. 기본적으로는 option 의 label 값이 export 됩니다. 이 값을 true 로 주면 label 대신 value 가 export 됩니다.
Grid 속성
(optional) headerDraggable
headerDraggable = boolean
이 값을 true 로 설정하면 헤더를 드래그해서 헤더간 위치를 바꿀 수 있습니다.
(optional) headerWidthChangeable
headerWidthChangeable = boolean
이 값을 true 로 설정하면 헤더의 사이즈를 조절할 수 있습니다. 헤더의 경계 부근에서 마우스로 드래그하여 사이즈를 조절합니다.
(optional) rowHeightExtensible
rowHeightExtensible = boolean
이 값을 true 로 설정하면 row 의 높이가 컨텐츠의 크기에 따라 늘어납니다. 기본적으로는 row 높이는 고정되어 있습니다.
이 옵션을 사용하면 높이가 가변적이 되어서 가상스크롤이 적용되지 않습니다. 몇천건 이상의 많은 데이터를 사용하는 경우에는 적합하지 않습니다.
(optional) disableVirtualScroll
disableVirtualScroll = boolean
이 값을 true 로 설정하면 가상스크롤이 적용되지 않습니다. 가상스크롤을 사용하지 않아야 할때 이 옵션을 사용할 수 있습니다.
Form 처리를 하는경우에는 가상스크롤 적용시 모든 row 가 렌더링 되지 않기때문에 Form Context 내에서 처리하는 form validate 등이 정상적으로 동작하지 않을 수 있습니다.
(optional) onBodyScroll
onBodyScroll = React.UIEventHandler<HTMLDivElement>
그리드의 데이터부분이 스크롤될때 이벤트를 발생시킵니다.
(optional) onRowClick
onRowClick = (param: GridEventParam<T>) => boolean | void
특정 row 가 클릭되었을때 이벤트를 발생시킵니다. 이벤트의 파라미터는 여기를 참조하세요.
(optional) checkWhenRowClick
checkWhenRowClick = boolean
체크 타입의 컬럼이 있는 경우 이 옵션을 true 로 설정하면 row 를 클릭했을때 행 선택처리가 됩니다.
(optional) onCellClick
onCellClick = (param: GridEventParam<T>) => boolean | void
특정 컬럼이 클릭되었을때 이벤트를 발생시킵니다. 이벤트의 파라미터는 여기를 참조하세요.
(optional) onLoad
onLoad = (param: GridControlParam) => void
컴포넌트가 준비되면 실행됩니다. 이때 주어지는 그리드의 컨트롤 파라미터를 이용해서 여러 기능을 실행할 수 있습니다.
GridControlParam 설명
이름 | 타입 | 설명 |
---|---|---|
exportData | (option?:GridExcelExportOption) => void | 그리드 데이터를 엑셀로 export 합니다. |
importData | (file: File) => void | 엑셀파일을 그리드로 import 합니다. |
scrollTo | (index: number) => void | 특정 row index 로 스크롤 합니다. |
scrollAround | (index: number) => void | 특정 row index 로 스크롤 합니다. index 에 해당하는 row 가 보일때까지만 스크롤합니다. |
getVisibleRange | () => (number | undefined)[] | 현재 화면에 보여지는 행의 from ~ to index 를 리턴합니다. |
GridExcelExportOption 에는 다음의 옵션이 있습니다.
- fileName : 파일의 이름을 설정합니다. title 값보다 우선합니다.
- sheetName : sheet 의 이름을 설정합니다.
- includeIndex : export 할 대상 컬럼의 index 를 지정합니다. 이 값이 없으면 모든 컬럼을 export 합니다. 예) [0, 1, 2]
(optional) title
엑셀로 export 했을때 파일의 이름을 지정합니다. 이 값이 없으면 기본값(download_data)이 적용됩니다.
Grid 스타일
(optional) className
className = string
Grid 가장 상위에 className 을 지정합니다.
(optional) rowClassName
rowClassName = GridValue<T, string> | string
row 단위로 className 을 지정합니다. 타입은 string 과 GridValue 으로 조건부 처리가 가능합니다.
(optional) headerHeight
headerHeight = string
헤더의 높이를 지정합니다.
(optional) rowHeight
rowHeight = string
row 의 높이를 지정합니다.
(optional) minWidth
minWidth = string
그리드의 최소 폭을 지정합니다.
(optional) columnMinWidth
columnMinWidth = number
컬럼의 최소폭을 지정합니다. 컬럼이 지정된 폭 이하로 줄어들지 않습니다.
(optional) emptyText
emptyText = string
데이터가 하나도 없을때 표시되는 텍스트를 지정합니다.
(optional) borderless
borderless = boolean
그리드의 기본 border 가 사라집니다.
(optional) headerSpan
interface HeaderSpan {
label: string;
spanCount?: number;
}
headerSpan = HeaderSpan[][]
설정에 따라 헤더를 합쳐서 보여줍니다.
- label : 합쳐진 헤더의 label 값입니다.
- spanCount : 합칠 갯수입니다.
HeaderSpan[][] 의 첫번쨰 배열은 헤더 1 row 의 설정입니다. 만약 2개의 배열이면 2개의 헤더 row 가 추가됩니다. (총 3개)
두번째 배열은 각 헤더의 span 설정입니다. 배열의 순서대로 spanCount 를 참조하여 합쳐나갑니다. 이 로직에는 몇가지 제약조건이 존재합니다.
- span 대상 컬럼은 width 값이 존재해야합니다. 아니면 병합된 컬럼의 폭이 계산되지 않아서 레이아웃이 올바르게 나오지 않을 수 있습니다.
- 맨 마지막 컬럼은 spanCount 정의 없는 컬럼으로 끝나야 합니다. 이 컬럼은 span 처리되고 남은 나머지 폭을 채우는 역할을 합니다.
export function GridHeaderSpan(){
const [ data ] = useState(Array.from(Array(10)).map((_, idx)=>({item1:idx, item2:idx, item3:idx})))
return <Frame>
<Flex flexHeight="200px">
데이터 갯수 : {data.length}
<Grid
headers={[
{label:'항목1', targetId:'item1', width:100},
{label:'항목2', targetId:'item2', width:150},
{label:'항목3', targetId:'item3'},
]}
data={data}
gridStyle={{
headerHeight: '90px',
headerSpan: [
[
{ label: '전체 병합' },
],
[
{ spanCount: 2, label: '항목1 과 항목2' },
{ label: '항목3' },
],
],
}}
/>
</Flex>
</Frame>
}
타입 설명
GridEventParam<T>
이름 | 타입 | 설명 |
---|---|---|
header | GridHeader<T> | 헤더 정보 |
item | T | 현재 row 의 데이터 |
targetId | keyof T | 현재 컬럼의 속성명 |
rowIndex | number | 현재 row index |
colIndex | number | 현재 컬럼 index |
headers | GridHeader<T>[] | 헤더 전체 정보 |
data | T[] | 전체 데이터 |
GridValue
GridValue<T, R> = (item: T, header: GridHeader<T>) => R
item 과 header 정보를 가지고 특정 리턴값 (R) 을 조건부 처리할 수 있습니다.
예를들어 rowClassName 을 지정할때 string 이 아니라 GridValue 타입으로 다음과 같이 처리할 수 있습니다.
rowClassName = (item, header) => {
return item.selected ? 'row-selected' : 'row';
}