# Excel 가져오기

XLSX 가져오기는 파일을 워크북으로 읽고 선택한 시트를 Grid용 열·행 스냅샷으로 변환합니다. 워크북 전체 파싱 결과와 화면용 스냅샷은 다른 데이터입니다.

Canonical: https://grid.syidax.com/ko/docs/features/xlsx-import/

<a id="understand"></a>

## 동작 원리와 선택 기준

importDataFromXlsx의 반환값은 XlsxImportResult입니다. Grid에 사용할 snapshot은 xlsxImported 이벤트의 detail에서 읽습니다. 표 적용 여부를 앱에서 명시적으로 처리해 기존 편집 데이터를 실수로 덮어쓰지 않게 합니다.

코드의 grid는 설치와 연결 장에서 준비한 Grid 요소입니다. 예제마다 필요한 데이터·설정을 확인하고, 코드에서 소개하는 앱 함수와 서버 주소는 프로젝트에 맞게 구현하세요.

- [설치와 연결 · 공통 예제 데이터](https://grid.syidax.com/ko/docs/guides/getting-started.md)

<a id="example-1"></a>

## 예제 1. 선택한 파일 읽기

file은 사용자가 파일 입력으로 선택한 File 객체입니다.

```javascript
const parsed = await grid.importDataFromXlsx(await file.arrayBuffer());
console.log(parsed.workbook, parsed.sheets);
```

결과 확인: 반환값에서 원본 워크북과 시트 정보를 확인합니다. parsed.snapshot이라는 반환 필드는 없습니다.

<a id="example-2"></a>

## 예제 2. 변환된 시트를 표에 적용

가져오기를 실행하기 전에 완료 이벤트를 구독합니다.

```javascript
grid.addEventListener('xlsxImported', event => {
  const { snapshot, sheetName } = event.detail;
  grid.columnDefs = [...snapshot.columnDefs];
  grid.rowData = [...snapshot.rowData];
  console.log(sheetName, snapshot.rowData.length);
});
```

결과 확인: 이벤트가 제공한 변환 결과를 새 배열로 전달해 표에 표시합니다. 기존 작업의 교체 여부를 결정한 뒤 이 구독을 실행하세요.

<a id="example-3"></a>

## 예제 3. 지정한 시트 선택

워크북에 Orders라는 시트가 있는 경우 선택합니다.

```javascript
await grid.importDataFromXlsx(await file.arrayBuffer(), { sheetName: 'Orders' });
```

결과 확인: 선택한 시트만 화면용 스냅샷으로 변환됩니다. 시트 존재 여부·열 구조·지원하는 수식 및 스타일 변환 범위를 파일별로 확인합니다.

<a id="pitfalls"></a>

## 조합할 때와 문제를 해결할 때

Excel 화면과 모든 서식·수식·병합이 완전히 같은 모양으로 재현된다고 가정하지 마세요. 변환 결과를 확인하고 필요한 열 설정을 다시 적용합니다.

대용량 파일을 처리하는 동안 로딩과 오류 상태를 제공하고, 이벤트 구독이 중복되어 한 번의 가져오기가 여러 번 적용되지 않게 정리합니다.

<a id="related-api"></a>

## 이 기능에 사용하는 API

- [importDataFromXlsx](https://grid.syidax.com/ko/docs/methods/importDataFromXlsx.md) — 파일 바이트를 워크북으로 파싱합니다. 반환값은 XlsxImportResult이며 Grid용 snapshot은 xlsxImported 이벤트에서 읽습니다.
- [xlsxImported](https://grid.syidax.com/ko/docs/events/xlsxImported.md) — XLSX 파싱 후 선택한 시트의 Grid용 snapshot을 전달합니다. 필요하면 snapshot.columnDefs와 snapshot.rowData를 앱에서 적용합니다.

<a id="next"></a>

## 함께 읽기

- [행·열·ID의 관계](https://grid.syidax.com/ko/docs/guides/concepts.md)
- [결과와 이벤트 연결](https://grid.syidax.com/ko/docs/guides/data-event-access.md)
- [Features에서 살펴보기](https://grid.syidax.com/grid/xlsx-import) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.