tui-grid
Version:
TOAST UI Grid : Powerful data grid control supported by TOAST UI
327 lines (253 loc) • 9.48 kB
Markdown
## 개요
해당 문서는 TOAST UI Grid 3.0 버전 업데이트에 대한 마이그레이션 가이드로, 쉽고 빠르게 3.0 버전으로 업그레이드 할 수 있도록 도와주고 새롭게 추가된 기능들을 소개합니다.
그동안 TOAST UI 브랜드 강화를 위해 애플리케이션 제품군에 대해 대대적인 디자인 개편이 있었습니다. 그리드 또한 3.0 버전 업데이트를 통해 그리드만의 디자인을 적용하게 되었습니다.
새로운 디자인에 맞게 더 세부적으로 스타일을 설정할 수 있도록 테마 API의 옵션이 추가되었으며, 트리 형태로 데이터를 표현할 수 있는 기능도 추가되었습니다.
하단 내용을 참조해 3.0 버전으로 업그레이드 해보세요!
## 1. 새로운 디자인 적용하기
이제 보다 더 눈에 띄는 디자인으로 데이터를 쉽게 확인할 수 있습니다.
특별한 작업은 필요하지 않습니다.
그리드의 자바스크립트 및 CSS 파일만 변경하면 됩니다.
_`bower` 또는 `CDN`을 사용하는 경우, 반드시 [`tui-code-snippet`](https://github.com/nhnent/tui.code-snippet) **1.4.0 버전**으로 함께 업데이트 합니다._
### `npm` 사용 예
* `package.json` 디펜던시 버전 업데이트
``` js
{
"dependencies": {
"tui-grid": "^3.0.0"
}
}
```
### CDN 사용 예
``` html
<link rel="stylesheet" href="https://uicdn.toast.com/tui-grid/v3.0.0/tui-grid.css" />
...
...
<script src="https://uicdn.toast.com/tui-grid/v3.0.0/tui-grid.js"></script>
```
### 참고 사항
변경된 디자인에 따라 행 높이와 관련된 옵션의 기본 값이 변경되었습니다.
| 옵션명 | 변경 전 | 변경 후 |
| --- | ---- | ---- |
| `minRowHeight` | `35px` | `40px` |
| `header.height` | `27px` | `40px` |
디자인 최적화를 위해 기본 값 또는 그 이상의 값을 설정하는 것을 권장하나, 미만 값을 설정하고 싶을 경우 다음과 같이 처리할 수 있습니다.
그리드 생성 옵션 중 `minRowHeight` 값을 설정한 후, css 스타일을 오버라이드하여 셀 패딩 값을 조정하여 변경합니다.
``` js
var options = {
minRowHeight: 27
};
```
``` css
.tui-grid-cell .tui-grid-cell-content {
padding: 3px 12px;
}
```
## 2. 테마 API 옵션
기존 그리드의 레이아웃이 폐쇄형이었다면, 3.0 버전에서는 개방형 레이아웃으로 변경되었습니다.
이에 따라 테마 API 호출 시 사용하는 옵션 중 불필요한 옵션이 제거되고, 더 세밀하게 스타일을 조정할 수 있도록 옵션이 추가되었습니다.
```js
var Grid = require('tui-grid');
Grid.applyTheme('striped');
Grid.applyTheme('clean');
Grid.applyTheme('default', {
// theme options
});
```
### 제거된 옵션
* `grid` : 공통 보더와 영역 구분이 사라져 디프리케이트 되었습니다.
```js
{
grid: {
background: '#fff',
border: '#ccc',
text: '#444'
}
}
```
### 추가된 옵션
#### 1. 레이아웃 관련 옵션
* `outline` : 테이블의 외곽선 스타일을 변경합니다.
```js
{
outline: {
border: 'red',
showVerticalBorder: true
}
}
```
* `frozenBorder` : 고정 컬럼 영역을 구분하는 보더 색상을 변경합니다.
```js
{
frozenBorder: {
border: 'red'
}
}
```
* `scrollbar.border` : 스크롤바 영역에 대한 보더 색상을 변경합니다.
* `scrollbar.emptySpace `: 스크롤바 영역을 제외한 나머지 영역에 대한 배경색을 변경합니다.
```js
{
scrollbar: {
border: 'red',
emptySpace: 'pink'
}
}
```
#### 2. 영역 관련 옵션
* `area` : 헤더, 바디, 서머리 영역에 대한 보더 및 배경색을 변경합니다.
```js
{
area: {
header: {
border: 'blue',
background: 'skyblue'
},
body: {
background: 'yellow'
},
summary: {
border: 'red',
background: 'pink'
}
}
}
```
#### 3. 셀 관련 옵션
* `cell.rowHead` : 메타 컬럼 영역의 셀 스타일을 변경합니다.
* `cell.selectedRowHead` : 현재 선택된 메타 컬럼 영역의 셀 스타일을 변경합니다.
* `cell.summary` : 서머리 영역의 셀 스타일을 변경합니다.
```js
{
cell: {
rowHead: {
background: 'pink',
border: 'red',
text: 'red',
showVerticalBorder: true,
showHorizontalBorder: true
},
selectedRowHead: {
background: '#e5f6ff'
},
summary: {
background: 'pink',
border: 'red',
text: 'red',
showVerticalBorder: true
}
}
}
```
## 3. 트리 컬럼
### 기능 설명
* 트리 컬럼을 설정하면 특정 컬럼의 데이터를 트리 형태로 보여줍니다.
* 트리 요소 및 기능
* 뎁스 : 부모 - 자식 행의 계층적 관계를 표현합니다. 최소 뎁스는 `1`부터 시작합니다.
* 접기/펴기 버튼 : 이 버튼은 자식 행을 가지는 부모 행에 생성되며, 자식 행을 보여주거나 숨김 처리 할 수 있습니다.
* 아이콘 : 자식 행 유무 상태를 보여주는 아이콘을 사용할 수 있습니다.
### 사용 방법
#### 1. 트리 데이터 세팅
* 기존 그리드 데이터와 동일하게 행 데이터(`{}`)를 배열(`[]`)에 담아 초기화 합니다.
* 자식 행이 존재하는 경우, 부모 행 데이터의 프로퍼티 중 `_children`에 자식 행에 대한 행 데이터를 추가합니다.
* `_children` 프로퍼티를 `boolean` 값으로 설정하면 동적 로딩(Dynamic Loading)을 처리할 수 있습니다.
* `_extraData.treeState` 프로퍼티로 자식 행에 대한 접기/펴기 초기 상태를 설정할 수 있습니다. 설정되어 있지 않을 경우 기본 값은 접힘 상태(`COLLAPSE`) 입니다.
```js
var data = [
{
c1: 'foo',
c2: 'bar',
_extraData: {
treeState: 'EXPAND' // 'COLLAPSE'
},
_children: [
{
c1: 'baz',
c2: 'qux'
},
{
c1: 'quux',
c2: 'corge',
_children: true
},
// ...
]
},
// ...
];
```
#### 2. 트리 컬럼 활성화
* 그리드 생성 옵션에 트리를 생성할 컬럼에 대한 옵션을 추가합니다.
| 옵션명 | 설명 |
| --- | --- |
| `name` | 트리 데이터를 보여줄 컬럼명 설정 |
| `useIcon` | 아이콘 사용 유무 설정 |
| `useCascadingCheckbox` | 부모-자식 관계를 유지한 상태로 체크박스 상태를 변경할지 여부 설정 |
``` js
var options = {
treeColumnOptions: {
name: 'c1',
useIcon: true,
useCascadingCheckbox: true
},
// ...
}
```
### 신규 추가된 API
#### 1. 메서드
```js
// Example
grid.expandAll();
```
| 메서드명 | 설명 |
| --- | --- |
| `expand` | 특정 행의 자식 행을 펼침 상태로 변경 |
| `expandAll` | 모든 자식 행을 펼침 상태로 변경 |
| `collapse` | 특정 행의 자식 행을 접힘 상태로 변경 |
| `collapseAll` | 모든 자식 행을 접힘 상태로 변경 |
| `getAncestors` | 모든 조상 행의 키 값 반환 |
| `getDescendants` | 모든 자손 행의 키 값 반환 |
| `getParent` | 부모 행의 키 값 반환 |
| `getChildren` | 자식 행의 키 값 반환 |
| `getDepth` | 현재 행의 뎁스 값 반환 |
#### 2. 커스텀 이벤트
```js
// Example
grid.on('expanded', function(ev) {
console.log(ev.rowKey);
});
```
| 이벤트명 | 설명 |
| --- | --- |
| `expanded` | 특정 행의 자식 행이 펼침 상태로 변경될 때 발생 |
| `expandedAll` | 모든 자식 행이 펼침 상태로 변경될 때 발생 |
| `collapseed` | 특정 행의 자식 행이 닫힘 상태로 변경될 때 발생 |
| `collapseedAll` | 모든 자식 행이 펼침 상태로 변경될 때 발생 |
#### 3. `appendRow` API 파라미터
```js
// Example
var options = {
parentRowKey: 3,
offset: 0,
// ...
};
grid.appendRow(row, options);
```
| 옵션명 | 설명 |
| --- | --- |
| `parentRowKey` | 자식이 추가될 행의 키 값 |
| `offset` | 이미 부모가 자식 행을 가지고 있을 경우 몇 번째 위치에 추가할지 결정 |
### 트리 컬럼 활성화 시 동작이 변경되는 API
| 메서드명 | 설명 |
| --- | --- |
| `appendRow` | 현재 행 이하에 자식 행 생성 |
| `prependRow` | 현재 행 이하에 자식 행 생성 |
| `removeRow` | 자식 행을 가지고 있는 경우 함께 삭제 |
| `check` | `useCascadingCheckbox: true` 설정된 경우, 부모-자식 관계 유지된 상태로 체크박스 선택 |
| `uncheck` | `useCascadingCheckbox: true` 설정된 경우, 부모-자식 관계 유지된 상태로 체크박스 선택 취소 |
### 주의 사항
* 트리 컬럼을 사용할 경우 **정렬**, **행 병합**, **페이지네이션** 기능 사용에 제약이 있습니다.
### 참고 문서
더 자세한 사용 방법은 아래 링크에서 확인하실 수 있습니다.
* [Example](https://nhnent.github.io/tui.grid/latest/tutorial-example14-tree.html)
* [APIs](https://nhnent.github.io/tui.grid/latest/Grid.html)