convert-xlsx-to-json

convert-xslx-to-json은 xlsx 파일을 특정한 형태의 JSON 파일로 변환하기 위한 CLI 도구 등을 제공합니다.

목차

• convert-xlsx-to-json
  • 목차
  • 설치
    • NPM
    • yarn
  • CLI 도구로 사용시
    • npx로 실행
    • 전역 설치 후 실행
    • gen 메서드
    • 매개변수 종류
    • 기본 사용법
    • 파일 경로에 관한 TIP
    • 특정 열 제외하기
    • 앞부분 일부만 포함시키기
    • 첫번째 열을 헤더로 사용하는 경우
    • 헤더가 없는 경우
    • 특정 범위를 지정하고 싶을 때
    • 특정 시트를 지정하고 싶을 때
  • xlsx 변환 api로 사용시
    • 매개변수 정보

설치

NPM

# CLI만 사용시 전역 설치를 권장합니다.
npm i -g convert-xlsx-to-json

# 내부 api를 사용하고자 하면 로컬로 설치해주세요.
npm i convert-xlsx-to-json

yarn

# CLI만 사용시 전역 설치를 권장합니다.
yarn global add convert-xlsx-to-json

# 내부 api를 사용하고자 하면 로컬로 설치해주세요.
yarn add convert-xlsx-to-json

CLI 도구로 사용시

npx로 실행

CLI 도구만 사용하길 희망하신다면 npx convert-xlsx-to-json ...params로 설치 없이 사용하실 수 있습니다.

전역 설치 후 실행

혹시 npm 혹은 yarn을 이용해 해당 패키지를 전역 설치 하셨다면, 아래의 명령어들을 콘솔상에서 직접 사용하실 수도 있습니다.

convert-xlsx-to-json gen -f ./target.json -p age name

# 같은 동작을 합니다.
xlsx-to-json gen -f ./target.json -p age name

gen 메서드

현재 오직 gen 메서드 하나만을 지원합니다.
이 메서드는 xlsx 파일로부터 json 파일을 생성해 저장하는 동작을 담당합니다.

매개변수 종류

gen 메서드에는 아래의 매개변수들이 추가로 전달될 수 있습니다.

Parameter	Alias	required?	default	Description	Example
--from	-f	✅		변환할 xlsx 파일의 경로	-f ./target.xlsx
--to	-t		현재 경로/[xslx파일명].json	저장될 JSON 파일의 경로	-t ./json/out.json
--propKeys	-p	✅		propKey로 사용될 리스트. _로 표시된 순번은 결과물에 포함하지 않는다.	-p name age _ ext
--sheetIndex	-i		0	변환할 시트 인덱스 (0부터 시작)	-i 1
--omitHeader	-o		true	첫번째 행 혹은 열을 생략할지 여부	-o
--columnEntity	-c		false	데이터를 열 단위로 해석할지의 여부	-c
--range	-r			A1 스타일로 표현된 해석할 셀의 범위. omitHeader 옵션은 무시된다.	-r A1 or -r A1:C8

기본 사용법

아래와 같은 내용의 xlsx 파일이 있다고 가정하겠습니다.

이름	나이	국적	기타 설명
BitYoungjae	30	South Korea	잡다한 것 만들기를 좋아한다.
Kakarot	39	Vegeta	Munchkin

다음의 명령어를 통해 위 내용의 xlsx 데이터를 JSON 파일로 저장할 수 있습니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --to ./data.json --propKeys name age country etc

from 매개변수로 전달된 ./data.xlsx는 변환의 대상이 되는 xlsx 파일의 경로이며,
to 매개변수로 전달된 ./data.json은 출력물인 JSON 파일이 저장될 경로입니다.

xlsx 상에서 각각의 행으로 표현된 entity들은 propKeys 매개변수로 전달된 키들을 속성명으로 삼아 JSON Object로 변환이 됩니다.

변환된 data.json의 내용물은 아래와 같습니다.

[
  {
    "name": "BitYoungjae",
    "age": 30,
    "country": "South Korea",
    "etc": "잡다한 것 만들기를 좋아한다."
  },
  {
    "name": "Kakarot",
    "age": 39,
    "country": "Vegeta",
    "etc": "Munchkin"
  }
]

파일 경로에 관한 TIP

파일 경로는 상대경로와 절대경로 두가지 방법으로 지정하실 수 있습니다.
상대경로로 지정할 경우 convert-xlsx-to-json 명령어를 호출한 경로를 기준삼아 파일 경로를 계산합니다.

to 매개변수의 경우 생략이 될 수 있습니다.
생략될 경우 xlsx 파일의 파일명에 따라 json 파일명이 자동으로 지정됩니다.
존재하지 않는 경로일 경우 강제로 생성합니다.

아래의 명령어 예시의 경우 data.xlsx 파일로부터 data.json 파일을 생성합니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --propKeys name age country etc

특정 열 제외하기

역시 같은 데이터가 xlsx 파일로 준비되어 있다고 가정하겠습니다.

이름	나이	국적	기타 설명
BitYoungjae	30	South Korea	잡다한 것 만들기를 좋아한다.
Kakarot	39	Vegeta	Munchkin

이 중에서 우리는 이름과 국적에 해당하는 데이터만 JSON으로 추출하고 싶습니다.
그럴 때는 propKeys 매개변수에 _를 사용하여 해당하는 위치의 데이터를 결과물에서 제외할 수 있습니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --to ./data.json --propKeys name _ country _

나이와 기타 설명에 해당하는 두번째와 네번째 위치에 _를 사용했음을 확인하실 수 있습니다.

출력된 ./data.json의 내용물은 아래와 같습니다.

[
  {
    "name": "BitYoungjae",
    "country": "South Korea"
  },
  {
    "name": "Kakarot",
    "country": "Vegeta"
  }
]

앞부분 일부만 포함시키기

이번에도 같은 데이터가 xlsx 파일로 준비되어 있다고 가정하겠습니다.

이름	나이	국적	기타 설명
BitYoungjae	30	South Korea	잡다한 것 만들기를 좋아한다.
Kakarot	39	Vegeta	Munchkin

만약 propKeys로 주어진 속성명의 갯수가 xlsx 상의 특정 entity의 실제 컬럼 갯수보다 작을 경우,
주어진 속성명 갯수 이후의 데이터는 결과물에서 자동으로 무시됩니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --to ./data.json --propKeys name age

propKeys 매개변수로 주어진 속성명들이 name과 age 뿐이므로 국적과 기타 설명에 해당하는 xlsx 상의 데이터는 무시됩니다.

출력된 ./data.json의 내용물은 아래와 같습니다.

[
  {
    "name": "BitYoungjae",
    "age": 30
  },
  {
    "name": "Kakarot",
    "age": 39
  }
]

첫번째 열을 헤더로 사용하는 경우

이번에는 xlsx 데이터의 구성이 조금 다른 형태라고 가정해보겠습니다.

이름	BitYoungjae	Kakarot
나이	30	39
국적	South Korea	Vegeta
기타 설명	잡다한 것 만들기를 좋아한다.	Munchkin

첫번째 열이 테이블 헤더의 역할을 하고, 이후의 열들이 각각의 entity를 구성하는 형태입니다.
이런 형태의 데이터는 --columnEntity 매개변수를 추가하여 의도한대로 변환이 가능합니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --to ./data.json --propKeys name age country etc --columnEntity 

저장된 data.json의 내용물은 아래와 같습니다.

[
  {
    "name": "BitYoungjae",
    "age": 30,
    "country": "South Korea",
    "etc": "잡다한 것 만들기를 좋아한다."
  },
  {
    "name": "Kakarot",
    "age": 39,
    "country": "Vegeta",
    "etc": "Munchkin"
  }
]

헤더가 없는 경우

아래와 같이 Entity를 열 단위로 구성하였으며, 별도의 헤더가 없는 데이터라고 가정해보겠습니다.

BitYoungjae	Kakarot
30	39
South Korea	Vegeta
잡다한 것 만들기를 좋아한다.	Munchkin

이런 형태의 데이터는 --omitHeader 매개변수를 false 로 지정하여 의도한대로 변환이 가능합니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --to ./data.json --propKeys name age country etc --omitHeader false

저장된 data.json의 내용물은 아래와 같습니다.

[
  {
    "name": "BitYoungjae",
    "age": 30
  },
  {
    "name": "Kakarot",
    "age": 39
  }
]

특정 범위를 지정하고 싶을 때

기본적으로 convert-xlsx-to-json은 A1 셀부터 시작되는 데이터 테이블이 있음을 전제로 동작합니다.
하지만 혹시 특정 범위의 셀 영역을 변환하고 싶으시다면 --range 매개변수를 이용해 지정하실수도 있습니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --to ./data.json --propKeys name age --range C5:Z9

특정 시트를 지정하고 싶을 때

convert-xlsx-to-json은 별도의 설정이 없으면 첫번째 시트의 데이터만을 변환합니다.
만약 특정 시트를 지정하여 변환하고자 한다면 --sheetIndex 매개변수를 이용해 특정 시트를 지정하실 수 있습니다.

시트의 이름이 아닌 몇번째 시트인지를 가리키는 index값을 매개변수의 값으로 전달해주셔야 합니다.
시트의 index는 0-based numbering을 따릅니다.

즉, 첫번째 시트는 숫자 0으로 지정할 수 있으며 두번째는 1 세번째는 2로 지정해주셔야만 합니다.

아래는 세번째 시트의 데이터만을 변환하는 내용의 명령어 예시 입니다.

npx convert-xlsx-to-json gen --from ./data.xlsx --propKeys name age --sheetIndex 2

xlsx 변환 api로 사용시

혹시 xlsx 파일을 JSON 파일로 저장하는 것에는 관심이 없고,
위와 같은 규칙으로 단순 xlsx 파일을 자바스크립트 데이터로 변환만하고 싶으시다면

아래처럼 활용도 가능합니다.

단, 이 경우 convert-xlsx-to-json 패키지가 로컬로 설치가 되어 있어야만 합니다.

import path from 'path';
import { xlsxToJSON } from 'convert-xlsx-to-json';

const xlsxPath = "~/documents/data.xlsx";
const entities = xlsxToJSON(xlsxPath, ["name", "age", "_", "etc"], 0, true, false);

매개변수 정보

name	type	required?	default
xlsxPath	string	✅	-
propKeys	string[]	✅	-
sheetIndex	integer		0
omitHeader	boolean		true
columnEntity	boolean		false
range	string		-

자세한 정보는 매개변수 종류를 참고해주세요.