excel-export

Excel 파일 생성 및 다운로드를 위한 TypeScript 라이브러리입니다. React Hook을 포함하여 간편하게 사용할 수 있습니다.

설치

# npm
npm install excel-export-ts

# pnpm
pnpm add excel-export-ts

# yarn
yarn add excel-export-ts

기본 사용법

Vanilla JavaScript/TypeScript

import { exportToExcel } from 'excel-export-ts';

interface UserData {
  name: string;
  phone: string;
  age: number;
  department: string;
  isActive: boolean;
  createdAt: Date;
}

const userData: UserData[] = [
  {
    name: '홍길동',
    phone: '010-1234-5678',
    age: 30,
    department: '개발팀',
    isActive: true,
    createdAt: new Date('2024-01-15'),
  },
  // ... 더 많은 데이터
];

const columns = [
  {
    key: 'name',
    header: '이름',
    getValue: (row: UserData) => row.name,
    width: 15,
  },
  {
    key: 'phone',
    header: '전화번호',
    getValue: (row: UserData) => row.phone,
    width: 20,
  },
  {
    key: 'age',
    header: '나이',
    getValue: (row: UserData) => row.age,
    width: 10,
  },
  {
    key: 'department',
    header: '부서',
    getValue: (row: UserData) => row.department,
    width: 15,
  },
  {
    key: 'isActive',
    header: '활성 상태',
    getValue: (row: UserData) => (row.isActive ? '활성' : '비활성'),
    width: 15,
  },
  {
    key: 'createdAt',
    header: '생성일',
    getValue: (row: UserData) => row.createdAt.toLocaleDateString('ko-KR'),
    width: 15,
  },
];

exportToExcel({
  data: userData,
  columns,
  fileName: 'users.xlsx',
  sheetName: '사용자 목록',
  onBeforeExport: (workbook) => {
    console.log('워크북 생성 완료:', workbook.SheetNames);
  },
  onAfterExport: () => {
    console.log('✅ 엑셀 파일 생성 완료');
  },
  onError: (error) => {
    console.error('❌ 에러 발생:', error.message);
  },
});

React Hook 사용

import { useExcelExport } from 'excel-export-ts';
import { useCallback } from 'react';

function UserList() {
  const { download, isExporting, error } = useExcelExport({
    data: userData,
    columns,
    fileName: 'users.xlsx',
    sheetName: '사용자 목록',
    onAfterExport: () => {
      console.log('다운로드 완료');
    },
    onError: (error) => {
      console.error('에러:', error.message);
    },
  });

  return (
    <div>
      <button onClick={download} disabled={isExporting}>
        {isExporting ? '다운로드 중...' : '엑셀 다운로드'}
      </button>
      {error && <div>에러: {error.message}</div>}
    </div>
  );
}

API 문서

exportToExcel<TData>(options: ExportOptions<TData>): void

엑셀 파일을 생성하고 다운로드합니다.

파라미터

• data: TData[] - 엑셀로 내보낼 데이터 배열
• columns: ExcelColumnDef<TData>[] - 컬럼 정의 배열
• fileName: string - 다운로드될 파일명 (예: 'users.xlsx')
• sheetName?: string - 시트 이름 (기본값: 'Sheet1')
• onBeforeExport?: (workbook: WorkBook) => void - 엑셀 생성 후 다운로드 전 호출되는 훅
• onAfterExport?: () => void - 다운로드 완료 후 호출되는 훅
• onError?: (error: Error) => void - 에러 발생 시 호출되는 핸들러

useExcelExport<TData>(options: ExportOptions<TData>): UseExcelExportReturn

React 컴포넌트에서 사용할 수 있는 Hook입니다.

반환값

• download: () => void - 엑셀 다운로드를 실행하는 함수
• isExporting: boolean - 현재 다운로드 진행 중인지 여부
• error: Error | null - 에러 발생 시 에러 객체

ExcelColumnDef<TData>

컬럼 정의 인터페이스입니다.

interface ExcelColumnDef<TData> {
  /** 컬럼 고유 키 */
  key: string;
  
  /** 헤더 텍스트 (이미 번역된 값) */
  header: string;
  
  /** 데이터에서 셀 값을 추출하는 함수 */
  getValue: (row: TData) => CellValue;
  
  /** 컬럼 너비 (선택) */
  width?: number;
}

CellValue

셀에 들어갈 수 있는 값의 타입입니다.

type CellValue = string | number | boolean | Date | null | undefined;

특징

• ✅ TypeScript 완전 지원
• ✅ React Hook 제공
• ✅ 커스터마이징 가능한 컬럼 정의
• ✅ 컬럼 너비 설정 지원
• ✅ 엑셀 생성 전/후 훅 지원
• ✅ 에러 핸들링 지원
• ✅ CommonJS 및 ES Module 지원

라이선스

MIT