# 범위 복사와 붙여넣기

직사각형 범위의 값을 복사하고 같은 행·열 배치로 붙여넣습니다. 시작 셀을 기준으로 대상이 결정되며 편집 불가·권한·검증 규칙을 함께 적용합니다.

Canonical: https://grid.syidax.com/ko/docs/features/range-clipboard/

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

## 동작 원리와 선택 기준

복사 형식이 같아도 대상 열의 숫자·날짜·선택값 계약에 따라 붙여넣기 결과가 달라질 수 있습니다. 작은 범위부터 확인하세요.

이 기능을 제품에서 사용하려면 Pro 패키지와 유효한 라이선스가 필요합니다. 설정 이름이 같더라도 Community에서 Pro 기능이 활성화되는 것은 아닙니다.

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

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

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

## 예제 1. 선택 범위 복사

범위를 선택한 뒤 사용자 버튼에서 복사합니다.

```javascript
grid.rangeSelection = true;
console.log(await grid.copyRangeToClipboard());
```

결과 확인: 선택된 셀 배치가 클립보드에 들어갑니다. 범위가 없거나 브라우저가 거절한 경우도 결과로 확인합니다.

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

## 예제 2. 스프레드시트의 수량 붙여넣기

복사한 숫자 두세 개를 수량 열 시작점에 붙여 넣습니다.

```javascript
// 사용자 붙여넣기 버튼에서 호출
console.log(await grid.pasteFromClipboard());
```

결과 확인: 대상 수량과 계산 열이 갱신됩니다. 형식이 틀리거나 편집 불가인 대상은 모두 같은 방식으로 적용되지 않을 수 있습니다.

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

## 예제 3. 붙여넣기 후 되돌리기

처리 결과를 읽고 잘못된 변경은 실행 취소로 되돌립니다.

```javascript
grid.addEventListener('clipboardPasted', event => console.log(event.detail));
// 사용자가 실행 취소를 요청했을 때
await grid.undo();
```

결과 확인: 실제로 바뀐 셀과 제외된 셀을 구분합니다. 서버로 이미 저장했다면 서버 되돌리기는 앱에서 따로 처리해야 합니다.

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

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

병합 셀과 고정 행이 있는 범위는 일반 영역과 다를 수 있습니다. 범위 크기만으로 적용한 행 수를 계산하지 말고 반환 보고서를 사용하세요.

보호된 열에 대한 복사·붙여넣기는 UI뿐 아니라 API 경로에서도 동일하게 거절되는지 확인합니다.

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

## 이 기능에 사용하는 API

- [copyRangeToClipboard](https://grid.syidax.com/ko/docs/methods/copyRangeToClipboard.md) — 현재 선택 범위를 클립보드에 복사하고 성공 여부를 반환합니다. 브라우저 권한과 사용자 동작 조건을 확인합니다.
- [pasteFromClipboard](https://grid.syidax.com/ko/docs/methods/pasteFromClipboard.md) — 클립보드 내용을 현재 대상에 붙여넣습니다. 결과 이벤트에서 적용·건너뛴 셀을 확인합니다.
- [clipboardCopied](https://grid.syidax.com/ko/docs/events/clipboardCopied.md) — 클립보드 복사가 완료되었을 때 발생합니다. 출력 텍스트와 범위를 확인할 수 있으므로 민감 정보 로그를 주의합니다.
- [clipboardPasted](https://grid.syidax.com/ko/docs/events/clipboardPasted.md) — 붙여넣기 처리 결과를 알립니다. 적용 수·건너뛴 수·시작 위치·실제 변경 목록을 함께 확인합니다.

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