@gcsc/vue-lists-gc

Vue List Component

Vue 3 기반의 다용도 목록 컴포넌트입니다. 기본 리스트, 드래그 가능한 리스트, 트리 리스트을 지원합니다.

1. 설치

# npm
npm install @gcsc/vue-lists-gc sass vuedraggable@next

# yarn
yarn add @gcsc/vue-lists-gc sass vuedraggable@next

2. 사용 방법

2-1) 기본 사용법

<template>
  <BaseList
      :items="items"
      :checkable="true"
      @item-click="handleItemClick"
      @check="handleCheck"
      @check-all="handleCheckAll"
  />
</template>

<script setup lang="ts">
import {BaseList} from '@gcsc/vue-lists-gc';
import '@gcsc/vue-lists-gc/style';
import {ref} from "vue";

const selectedIds = ref<number[]>([]);

const items = [
  {
    id: 1,
    title: '제목 1',
    preview: '미리보기 텍스트입니다.',
    time: new Date(),
    imageUrl: 'https://picsum.photos/100/100?random=1'
  },
// ...
];
const handleItemClick = (item) => {
  console.log('클릭된 아이템:', item);
};

const handleCheck = (checkedItems: number[]) => {
  selectedIds.value = checkedItems;
};

const handleCheckAll = (checked: boolean) => {
  if (checked) {
    selectedIds.value = basicItems.value.map(item => item.id);
  } else {
    selectedIds.value = [];
  }
};

2-2) 슬롯을 사용한 커스터마이징

<template>
  <BaseList
      :items="items"
      :checkable="true"
      @item-click="handleItemClick"
      @check="handleCheck"
      @check-all="handleCheckAll"
  >
    <!-- 전체 선택 헤더 커스터마이징 -->
    <template #header-checkbox-content>
      전체 선택 ({{ selectedIds.length }}/{{ items.length }})
    </template>

    <!-- 이미지 커스터마이징 -->
    <template #item-image="{ item }">
      <div class="custom-image">
        <img :src="item.imageUrl" :alt="item.title"/>
        <span class="image-badge">New</span>
      </div>
    </template>

    <!-- 제목 커스터마이징 -->
    <template #item-title="{ item }">
      <h3 class="custom-title">
        {{ item.title }}
        <span v-if="item.isNew" class="new-badge">NEW</span>
      </h3>
    </template>

    <!-- 시간 표시 커스터마이징 -->
    <template #item-time="{ item }">
      <time :datetime="item.time" class="custom-time">
        {{ formatCustomTime(item.time) }}
      </time>
    </template>

    <!-- 미리보기 커스터마이징 -->
    <template #item-preview="{ item }">
      <div class="custom-preview">
        <p>{{ item.preview }}</p>
        <div class="preview-footer">
          <span class="category">{{ item.category }}</span>
          <span class="views">조회수: {{ item.views }}</span>
        </div>
      </div>
    </template>
  </BaseList>
</template>

<script setup lang="ts">
import {BaseList} from '@gcsc/vue-lists-gc';
import '@gcsc/vue-lists-gc/style';
import {ref} from "vue";

const selectedIds = ref<number[]>([]);

const items = [
  {
    id: 1,
    title: '커스텀 제목',
    preview: '커스텀 미리보기 텍스트',
    time: new Date(),
    imageUrl: '/custom-image.jpg',
    isNew: true,
    category: '기술',
    views: 1234
  }
];

const formatCustomTime = (time) => {
  // 커스텀 시간 포맷팅 로직
  return new Date(time).toLocaleDateString();
};

const handleItemClick = (item) => {
  console.log('클릭된 아이템:', item);
};

const handleCheck = (checkedItems: number[]) => {
  selectedIds.value = checkedItems;
};

const handleCheckAll = (checked: boolean) => {
  if (checked) {
    selectedIds.value = basicItems.value.map(item => item.id);
  } else {
    selectedIds.value = [];
  }
};
</script>

3. 전역 등록

// main.ts
import '@mdi/font/css/materialdesignicons.css';
import '@gcsc/vue-lists-gc/style'

4. 샘플 데이터 사용방법

import { sampleListItems, sampleTreeItems } from '@gcsc/vue-lists-gc';

const items = ref([...sampleListItems.value]); // 베이직, 드래그 리스트 샘플 데이터
const treeItems = ref([...sampleTreeItems.value]); // 트리 리스트 샘플 데이터

5. Props

Prop 이름	타입	기본값	설명
items	ListItem[]	required	리스트에 표시할 아이템 배열
checkable	boolean	false	체크박스 기능 활성화 여부
draggable	boolean	false	드래그 앤 드롭 기능 활성화 여부
tree	boolean	false	트리 구조 활성화 여부

6. Events

이벤트 이름	파라미터	설명
item-click	(item: ListItem)	아이템 클릭 시 발생
check	(checkedItems: number[])	체크박스 상태 변경 시 발생
check-all	(checked: boolean)	전체 선택 상태 변경 시 발생

7. Slots

슬롯 이름	Props	설명
header-checkbox-content	-	전체 선택 체크박스 레이블 커스터마이징
item-checkbox	{ item, checked }	개별 아이템 체크박스 커스터마이징
item-image	{ item }	아이템 이미지 커스터마이징
item-title	{ item }	아이템 제목 커스터마이징
item-preview	{ item }	아이템 미리보기 커스터마이징
item-time	{ item }	아이템 시간 표시 커스터마이징

8. Type

interface ListItem {
id: number;
imageUrl: string;
title: string;
preview: string;
time: string | Date;
checked?: boolean;
children?: ListItem[];  // 트리뷰 사용
isOpen?: boolean;  // 트리뷰 사용
}

9. 스타일 커스터마이징

컴포넌트의 스타일은 class를 통해 scss 문법으로 사용할 수 있습니다.

.custom-class {
    .list-container {
        width: 100px
    }
}

10. 브라우저 지원

• 모든 최신 브라우저 지원
• Vue 3.0.0 이상 필요
• TypeScript 지원

11. License

• Jeongin Choi_