Unvus Docs

Appearance

nv-grid-col ​

nv-grid 안에서 컬럼을 선언하는 컴포넌트로, slot 을 이용한 커스텀 셀 렌더링 기능을 제공합니다.

이 컴포넌트는 렌더되지 않습니다. 부모인 nv-grid 가 기본 슬롯의 VNode 를 읽어 ag-grid 의 ColDef 로 변환합니다. 덕분에 다음이 자연스럽게 동작합니다.

  • 컬럼 순서 = 템플릿에 쓴 순서 (마운트 순서에 의존하지 않음)
  • v-if / v-for 로 컬럼을 붙였다 뗐다 해도 중복·누락이 없음
  • :header-name="label" 처럼 반응형 속성이 그대로 반영됨

props ​

이름타입기본값설명
headerNamestringag-grid 클래스 이름 지정
fieldstringag-grid 옵션 객체
widthnumber컬럼 너비
minWidthnumber컬럼 최소 너비
flexnumberFlexbox 기능 설정
cellStylestring컬럼 스타일
pinnedstring열 고정 여부('left', 'right')
sortKeystring컬럼 정렬 기능 활성화 + 서버에 보낼 정렬 키
sortstring초기 정렬 방향('asc' / 'desc')
sortablebooleanfalsesortKey 없이 정렬만 켤 때. 이 경우 정렬 키는 field 가 된다
noRowClickbooleanfalse이 컬럼을 눌러도 @nv-row-clicked 가 발생하지 않는다

Emits ​

이름설명
cell-click이 컬럼의 셀 클릭 시 (rowData, cellEvent) 로 호출. 행 클릭 대신 실행된다

행 클릭 동작 (nv-grid 의 @nv-row-clicked) ​

기본은 "어느 셀을 눌러도 행 클릭" 입니다. 컬럼 단위로 이렇게 바꿉니다.

html
<!-- 이 컬럼만 다른 액션 (예: 게시판 목록의 회원아이디 → 회원 상세 팝업) -->
<nv-grid-col header-name="작성자" field="loginId" @cell-click="openUserModal" />

<!-- 이 컬럼은 아무 일도 하지 않는다 -->
<nv-grid-col header-name="비고" field="memo" no-row-click />

핸들러는 (rowData, cellEvent) 로 호출됩니다. 다른 엔터티의 식별자를 꺼내 쓰는 식입니다.

html
<nv-grid-col header-name="등록자" field="createdBy" :width="100"
             @cell-click="(row) => openAdmin(row.createdBy)">
  <template #render="{params}">{{ params.data.createdUser.loginId }}</template>
</nv-grid-col>

셀 안에 <a href> 나 <button> 을 넣지 마세요

nv-grid 는 셀 안의 버튼·링크 클릭을 "그 컨트롤의 동작" 으로 보고 걸러내므로, @cell-click 이 아예 발동하지 않습니다.

대신 @cell-click 컬럼에는 nv-cell-clickable 클래스가 자동으로 붙어 포인터 커서와 링크 색이 적용됩니다. 별도 마크업이 필요 없습니다.

붙이지 않아도 되는 경우

  • pinned="right" 컬럼: Action 컬럼 관례이므로 nv-grid 가 자동으로 행 클릭에서 제외한다
  • 셀 안의 버튼·링크·입력요소: 자동 제외된다. 커스텀 요소는 .no-row-click 클래스를 주면 된다

자세한 규칙은 nv-grid 의 Row Click 참고.

정렬은 sortKey 를 준 컬럼에만 붙는다

sortKey(또는 명시적인 sortable) 가 없는 컬럼은 nv-grid 가 sortable: false 로 내려서 헤더에 정렬 아이콘이 나오지 않는다.

AG Grid 는 v31 부터 colDef.sortable 기본값이 false → true 로 바뀌었기 때문에(colDef.sortable ?? true), nv-grid 가 이렇게 명시적으로 꺼주지 않으면 "번호", "Action" 처럼 정렬하면 안 되는 컬럼까지 정렬이 걸린다.

sortKey 에 정렬 방향을 넣지 말 것

html
<!-- ❌ 틀림 -->
<nv-grid-col field="id" sort-key="b.id:DESC" sort="desc"/>

<!-- ✅ 맞음 -->
<nv-grid-col field="id" sort-key="b.id" sort="desc"/>

nv-grid 는 서버로 sortBy={sortKey}:{방향} 을 보내고, 백엔드(PagingFilter)는 : 로 잘라 두 번째 조각을 방향으로 읽는다. sort-key="b.id:DESC" 로 쓰면 b.id:DESC:asc 가 만들어져 백엔드가 항상 DESC 로 읽고, 헤더를 눌러도 정렬 방향이 바뀌지 않는다.

초기 정렬 방향은 sort 속성으로만 준다.

TIP

Column Definitions 의 경우 정의된 props 이외에 AG Grid 에서 기본 제공되는 설정도 전달이 가능합니다.

자세한 설정은 AG Grid Docs 참고

예제 ​

width ​

컬럼의 너비는 :width 속성에 숫자로 조정합니다.#

:width 속성이 설정 된 경우 아래와 같이 빈 공간이 생길 수 있습니다.

html
  <nv-grid ref="UserGrid"
    :rowData="list"
    :gridOptions="grid.option"
    :keepColumnState="true">
    <nv-grid-col headerName="번호" field="positionIdx" :cellStyle="grid.style.end" width="50"></nv-grid-col>
    <nv-grid-col headerName="제목" field="title" :width="150"></nv-grid-col>
    <nv-grid-col headerName="정렬필드" field="sortField"></nv-grid-col>
    <nv-grid-col headerName="언버스" field="field1"></nv-grid-col>
  </nv-grid>

flex, minWidth ​

만약 특정 컬럼이 전체 그리드 너비의 나머지 여유분을 차지하게 하고 싶으면

:flex="1" 과 :minWidth 속성의 조합으로 구성합니다.

html
<nv-grid ref="UserGrid"
         :rowData="list"
         :gridOptions="grid.option"
         :keepColumnState="true">
    <nv-grid-col headerName="번호" field="positionIdx" :cellStyle="grid.style.end" :width="50"></nv-grid-col>
    <nv-grid-col headerName="제목" field="title" :minwidth="150" :flex="1"></nv-grid-col>
    <nv-grid-col headerName="정렬필드" field="sortField"></nv-grid-col>
    <nv-grid-col headerName="언버스" field="field1"></nv-grid-col>
</nv-grid>

TIP

하나의 그리드에 적어도 한 컬럼은 이 처럼 여분 컬럼으로 사용해야 합니다.

  • flex="1" 의 의미는 나머지 공간의 차지하는 비율을 의미합니다.

만약 하나 이상의 컬럼이 flex 속성을 가지고 각각 1 과 2 라는 값을 가진다면 그 비율만큼 나머지 공간을 분할해서 차지하게 됩니다.

pinned ​

특정 컬럼을 좌, 우 기준으로 고정

html
<nv-grid ref="UserGrid"
         :rowData="list"
         :gridOptions="grid.option"
         :keepColumnState="true">
    <nv-grid-col headerName="번호" field="positionIdx" :cellStyle="grid.style.end" :width="50"></nv-grid-col>
    <nv-grid-col headerName="제목" field="title" :minWidth="50" :flex="1"></nv-grid-col>
    <nv-grid-col headerName="정렬필드" field="sortField"></nv-grid-col>
    <nv-grid-col headerName="언버스" field="field1" pinned="right"></nv-grid-col>
</nv-grid>

sortKey ​

컬럼 sort 기능 활성화. sortKey 를 준 컬럼에만 정렬 아이콘이 붙고, 클릭 시 pagination.query.sortBy 가 `${sortKey}:${asc|desc}` 로 만들어져 서버로 나간다.

아래 예제에서 "정렬필드" 컬럼에만 정렬이 걸리고 나머지 컬럼은 헤더를 눌러도 반응하지 않는다.

html
<nv-grid ref="UserGrid"
         :rowData="list"
         :gridOptions="grid.option"
         :keepColumnState="true">
    <nv-grid-col headerName="번호" field="positionIdx" :cellStyle="grid.style.end" :width="50"></nv-grid-col>
    <nv-grid-col headerName="제목" field="title" :minWidth="50" :flex="1"></nv-grid-col>
    <nv-grid-col headerName="정렬필드" field="sortField" sortKey="sortField"></nv-grid-col>
    <nv-grid-col headerName="언버스" field="field1"></nv-grid-col>
</nv-grid>