# CSV 가져오기

CSV 가져오기는 구분자로 나뉜 텍스트를 새 열과 행으로 바꿉니다. 기존 표에 일부 행을 추가하는 트랜잭션과 달리 importCsvText는 columnDefs와 rowData를 교체합니다.

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

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

## 동작 원리와 선택 기준

열 제목이 있는지, 구분자가 무엇인지 먼저 확인합니다. CSV 문자열의 숫자·날짜가 업무상 어떤 타입이어야 하는지와 필수 열 검증은 가져오기 과정에서 함께 설계해야 합니다.

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

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

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

## 예제 1. 머리글이 있는 CSV

데이터를 교체해도 되는 새 Grid에서 실행합니다.

```javascript
const result = await grid.importCsvText('product,quantity\nAtlas,24\nBeacon,36', { hasHeader: true });
console.log(result.rowCount, result.columnCount);
```

결과 확인: 제품과 수량에 해당하는 열 및 두 개의 데이터 행이 생깁니다. 기존 열 너비·편집기 설정은 필요하면 새 열에 다시 적용합니다.

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

## 예제 2. 탭으로 구분된 파일

스프레드시트에서 복사한 탭 구분 텍스트를 전달합니다.

```javascript
await grid.importCsvText('product\tquantity\nAtlas\t24', { delimiter: '\t', hasHeader: true });
```

결과 확인: 쉼표가 포함된 문자열을 잘못 나누지 않도록 실제 파일 형식과 구분자를 맞춥니다.

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

## 예제 3. 교체 전 확인 흐름

사용자가 파일을 고른 뒤 파일명·예상 열·필수 필드 오류를 먼저 안내합니다. 기존 작업이 있으면 데이터 스냅샷이나 앱 저장을 완료한 뒤 교체합니다.

결과 확인: 가져오기 완료 이벤트 csvImported에서 행·열 수를 읽어 결과를 안내합니다. 단순 추가가 목적이면 파싱·검증한 행을 applyTransaction({add: …})로 전달하는 별도 흐름을 구성합니다.

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

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

가져오기는 서버 저장이 아닙니다. 표에 표시된 데이터를 서버에 반영하는 별도 승인·저장 단계를 앱에서 만듭니다.

행 ID 열을 검증하지 않고 같은 ID의 행을 여러 개 만들면 이후 선택·수정·메모 연결이 불안정해집니다.

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

## 이 기능에 사용하는 API

- [csvImport](https://grid.syidax.com/ko/docs/options/csvImport.md) — CSV 가져오기 버튼과 열 매핑 흐름을 제공합니다. 가져오기로 기존 열·데이터가 교체되는지 사용자에게 안내하세요.
- [importCsvText](https://grid.syidax.com/ko/docs/methods/importCsvText.md) — CSV 텍스트를 파싱해 열과 원본 데이터를 교체합니다. 행 추가가 목적이면 별도의 파싱 후 트랜잭션 흐름을 구성하세요.
- [csvImported](https://grid.syidax.com/ko/docs/events/csvImported.md) — CSV 가져오기를 마쳤을 때 발생합니다. 실제 적용된 행 수와 열 수를 사용자에게 안내합니다.

<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/csv-import) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.