React - xlsx-js-style 라이브러리로 엑셀 다운로드 구현하기

데이터 리스트 페이지를 만들고 나서 추가로 엑셀 다운로드 기능을 요청받았다.

나는 xlsx-js-style 라이브러리를 사용했는데 과정을 정리하는 겸 작성하는 글..

위 라이브러리를 사용한 이유는 javascript를 사용해 스프레드시트에 스타일을 옵션을 추가할 수 있는 장점이 있다고해서 선택했다.

현재는 워크시트 디자인을 해놓진 않았지만 추후 스타일 변경을 고려해볼 예정,,

지원되는 스타일 속성은 alignment, border, fill, font, numFmt 이고 설정이 꽤나 간편하다는 생각이 들었다.

 

🔽 공식 페이지에서 제공하는 코드

import XLSX from 'xlsx-js-style';

export default function Excel() {
    // STEP 1: 새로운 workbook을 만든다
    const wb = XLSX.utils.book_new();

    // STEP 2: 데이터 rows에 대한 value와 style을 지정해준다.
    let row = [
        { v: 'Courier: 24', t: 's', s: { font: { name: 'Courier', sz: 24 } } },
        {
            v: 'bold & color',
            t: 's',
            s: { font: { bold: true, color: { rgb: 'FF0000' } } },
        },
        {
            v: 'fill: color',
            t: 's',
            s: { fill: { fgColor: { rgb: 'E9E9E9' } } },
        },
        { v: 'line\nbreak', t: 's', s: { alignment: { wrapText: true } } },
        {
            v: 'fill: bgcolor',
            t: 's',
            s: { fill: { bgColor: { rgb: 'E9E9E9' } } },
        },
    ];

    // STEP 3: row로 worksheet를 생성한다.
    const ws = XLSX.utils.aoa_to_sheet([row, row]);

    // worksheet를 workbook에 추가한다.
    XLSX.utils.book_append_sheet(wb, ws, 'readme demo');

    return (
        <div>
            <h1>xlsx-js-style</h1>

            <button
                onClick={() => {
                    // STEP 4: Write Excel file to browser (2번째 인자에는 파일명을 지정)
                    XLSX.writeFile(wb, 'xlsx-js-style-demo.xlsx');
                }}
            >
                Download Excel File(.xlsx)
            </button>
        </div>
    );
}

 

row에 사용될 'v', 't', 's' 변수는 셀에 주어질 각각의 속성이다. 여기서는 v, t, s만 사용하려고 한다!

• v : 셀에 들어갈 값
• t : 셀의 타입('b': Boolean, 'n': Number, 'e': Error, 's': String, 'd': Date) 
• s : 셀 스타일/테마
• w : 텍스트 서식
• f : 셀 수식
• r : 서식이 있는 텍스트 인코딩
• h : 서식이 있는 텍스트의 HTML 렌더링
• c : 셀과 관련된 주석
• z : 셀과 관련된 문자 형식을 숫자열로 변환(?)
• l : 셀의 하이퍼링크 옵션

추가로 이 라이브러리에서 사용할 utils 메소드들은 데이터 패키징과 데이터 추출관련 기능들로 구성되어있다.

이외에 HTML이나 CSV 파일도 워크시트로 생성 가능하니 필요하다면 하단에 추가 링크를 참고하자.

포맷	설명
var arr = XLSX.utils.sheet_to_json(ws, opts);	워크시트에 데이터 행 생성
var ws = XLSX.utils.aoa_to_sheet(aoa, opts);	2차원 배열을 워크시트로 만들기(array of arrays)
XLSX.utils.sheet_add_aoa(ws, aoa, opts);	기존 워크시트에 2차원 배열 추가
var ws = XLSX.utils.json_to_sheet(aoo, opts);	json객체 배열을 워크시트로 만들기
XLSX.utils.sheet_add_json(ws, aoo, opts);	기존 워크시트에 json객체 데이터 추가
var ws = XLSX.utils.table_to_sheet(elt, opts); var wb = XLSX.utils.table_to_book(elt, opts);	Table 데이터를 워크시트 또는 통합 문서로 만들기
XLSX.utils.sheet_add_dom(ws, elt, opts);	기존 워크시트에 Table요소 데이터 추가
var fmla_arr = XLSX.utils.sheet_to_formulae(ws);	워크시트에서 모든 수식 추출

 

 

1. npm 설치

npm install xlsx-js-style

 

2. header 행과 body에 들어갈 데이터 타입 지정

스타일은 폰트 굵기와 사이즈 옵션만 지정했다. 바디는 기본 서체를 사용할 예정이기에 타입에서 제거!

interface HeaderDataType {
  v: string;
  t: string;
  s: {
    font: {
      bold: boolean;
      sz: string;
    };
  };
}
interface BodyDataType extends Omit<HeaderDataType, 's'> {}

 

3. header 만들기

body데이터와 매핑할 헤더를 만들어준다.

const headerData: HeaderDataType[] = [
  {
    v: '번호',
    t: 's',
    s: {
      font: {
        bold: true,
        sz: '14',
      },
    },
  },
  {
    v: '이름',
    t: 's',
    s: {
      font: {
        bold: true,
        sz: '14',
      },
    },
  },
  {
    v: '지역',
    t: 's',
    s: {
      font: {
        bold: true,
        sz: '14',
      },
    },
  },
];

 

4. 다운로드 기능 만들기

xlsx에서 제공하는 여러 메소드들은 필요 시 검색해서 덧붙였는데, 기본적으로 공식 코드를 참고해 수정한 것이니 STEP 별 흐름만 잘 이해하면 될 것 같다.

const download = async () => {
    // STEP1. 새로운 workbook 생성
    const wb = XLSX.utils.book_new();
    
    // STEP2. body에 담길 데이터 리스트 api 호출 후 body데이터 생성
    const { contactData: petList } = await getExcelData('contactPet');
    const bodyData: BodyDataType[][] = petList.map((pet) => [
      { v: pet.id, t: 's' },
      { v: pet.name, t: 's' },
      { v: pet.region, t: 's' },
    ]);
    
    // STEP3. header와 body를 2차원 배열로 변환해 worksheet를 생성한다.
    const ws = XLSX.utils.aoa_to_sheet([
      headerData.map((header) => header.v),
      ...bodyData.map((row) => row.map((cell) => cell.v)),
    ]);
    
    // 셀 값을 변경하는 코드. 여기서는 만들어놓은 headerData의 스타일을 적용함
    headerData.forEach((header, index) => {
      const cellRef = XLSX.utils.encode_cell({ c: index, r: 0 });
      ws[cellRef].s = header.s;
    });

    // STEP4. worksheet 결과물 렌더링, 3번째 인자는 워크시트 제목
    XLSX.utils.book_append_sheet(wb, ws, '펫보험 문의 리스트');
    
    // STEP5. 파일만들기, 2번째 인자는 파일명 지정
    XLSX.writeFile(wb, 'petList.xlsx');
  };

 

5. 다운로드 버튼 만들고 onClick이벤트 걸면 끝!

필요한 기능을 뚝딱뚝딱 라이브러리를 붙여서 만들어봤는데 생각보다 간단하게 끝나서 자신감이 생겼었던 작업이였다!

돌이켜 생각해보면 핀치 줌이나 이미지 크롭하기같이 비교적 복잡한 기능들은 라이브러리의 도움을 받아 해내왔던 기억이나넹,,

그래도 간단한건 직접 코드로 짜보는 연습을 하면서 너무 의존하지 않을 것을 다짐해본다......... 나중엔 어려운 것도 혼자 척척 구현할 줄 아는 개발자가 되고싶다!!

 

 

<관련 공식문서>

https://github.com/gitbrent/xlsx-js-style/

GitHub - gitbrent/xlsx-js-style: SheetJS Community Edition + Basic Cell Styles

https://docs.sheetjs.com/docs/api/utilities/

Utility Functions | SheetJS Community Edition