본문으로 건너뛰기

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

이 함수를 이용해서 그리드의 컬럼을 커스텀 렌더링 할 수 있습니다.

파라미터는 다음과 같습니다.

파라미터타입설명
headerGridHeader현재 컬럼의 header 정보
itemT현재 컬럼이 속해있는 row data 정보
headersGridHeader[]전체 headers 정보
dataT[]전체 data 정보

(optional) headerRenderer​

headerRenderer = GridHeaderRenderFunction<T> = (header: GridHeader<T>, headers: GridHeader<T>[]) => JSX.Element

이 함수를 이용해서 그리드의 헤더정보를 커스텀 렌더링 할 수 있습니다.

파라미터는 다음과 같습니다.

파라미터타입설명
headerGridHeader현재 컬럼의 header 정보
headersGridHeader[]전체 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>​

이름타입설명
headerGridHeader<T>헤더 정보
itemT현재 row 의 데이터
targetIdkeyof T현재 컬럼의 속성명
rowIndexnumber현재 row index
colIndexnumber현재 컬럼 index
headersGridHeader<T>[]헤더 전체 정보
dataT[]전체 데이터

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';
}