Clipboard API: React에서 복사와 붙여넣기

navigator.clipboard.writeText(text)는 문자열을 시스템 클립보드에 쓰고 프라미스를 반환합니다. 이는 기존의 execCommand 방식을 대체하는 현대적인 방법입니다. 항상 프라미스를 await하고, 사용자가 클립보드 접근을 거부하는 경우처럼 발생할 수 있는 거부를 처리하십시오.

navigator.clipboard.readText()는 현재 클립보드 내용을 문자열로 읽고 프라미스를 반환합니다. 읽기에는 clipboard-read 권한이 필요하며, 브라우저가 사용자에게 권한을 허용할지 묻습니다. 일반적인 React 앱에서는 실제로 클립보드 읽기가 쓰기보다 덜 자주 사용됩니다.

브라우저는 clipboard.writeText를 클릭이나 키 입력 이벤트와 같은 사용자 동작 처리기 안에서만 호출할 수 있도록 제한합니다. useEffect 안에서 호출하거나 동작이 끝난 후 비동기적으로 호출하면 보안 오류가 발생합니다. 항상 onClick 처리기에서 직접 쓰기를 실행하십시오.

표준 패턴은 다음과 같습니다. 사용자가 복사 버튼을 클릭하면 처리기가 navigator.clipboard.writeText(value)를 호출하고, 성공하면 copied 상태를 true로 설정합니다. 그러면 버튼에 잠시 체크 표시나 "복사됨!" 레이블이 표시됩니다. 잠시 후 버튼은 원래 상태로 돌아갑니다.

로직을 useCopyToClipboard 훅으로 캡슐화하고 튜플을 반환하도록 하십시오: [copied, copyFn]. copied 불리언 값이 UI 피드백을 제어하고, copyFn은 복사할 텍스트를 받습니다. 훅이 비동기 쓰기와 모든 오류를 내부에서 처리하므로 컴포넌트를 단순하게 유지할 수 있습니다.

훅 내부에서 복사에 성공한 후 setCopied(true)를 설정하고 setTimeout(() => setCopied(false), 2000)으로 재설정하십시오. 시간 초과 ID를 저장하고 useEffect 정리 과정에서 삭제하여 마운트 해제 후 상태가 업데이트되지 않도록 하십시오. 이렇게 하면 "마운트 해제된 컴포넌트의 상태를 업데이트할 수 없습니다"라는 경고를 방지할 수 있습니다.

오래된 브라우저와 HTTPS가 아닌 페이지는 Clipboard API를 지원하지 않습니다. 기존 대체 방법은 임시 textarea를 만들고, 값을 설정하고, 본문에 추가한 다음 document.execCommand('copy')를 호출하고 요소를 제거합니다. 이 방식은 동기적으로 작동하고 어디서나 사용할 수 있지만 더 이상 사용이 권장되지 않습니다.

Clipboard API를 사용하기 전에 다음을 확인하십시오: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. 사용할 수 없으면 기존 execCommand 방식으로 대체하십시오. 이 방어적인 확인은 API가 지원되지 않는 환경에서 실행 중 오류가 발생하는 것을 방지합니다.

클립보드를 읽으려면 Permissions API를 통한 사용자 권한이 필요합니다. 현재 상태를 조회할 수 있습니다: navigator.permissions.query({ name: 'clipboard-read' })는 granted, denied, prompt 중 하나의 state를 가진 PermissionStatus를 반환합니다. readText()를 호출하면 브라우저가 자동으로 권한을 요청합니다.

Clipboard API는 보안 컨텍스트(HTTPS 또는 localhost)에서만 사용할 수 있습니다. HTTP 페이지에서는 navigator.clipboard가 undefined입니다. 클립보드 내용에는 민감한 정보가 포함될 수 있으므로 이는 보안 제한입니다. API의 메서드를 참조하기 전에 항상 사용 가능 여부를 확인하여 null 참조 오류를 방지하십시오.

Jest에서 사용하는 jsdom은 클립보드 API를 구현하지 않습니다. 테스트 설정에서 모의 객체를 만드십시오: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). 이렇게 하면 실제 브라우저 환경 없이도 컴포넌트가 올바른 인수와 함께 writeText를 호출하는지 테스트할 수 있습니다.

브라우저에서 navigator.clipboard.writeText()를 안전하게 호출할 수 있는 시점은 언제입니까?

텍스트를 복사하려면 클릭 처리기 안에서 navigator.clipboard.writeText()를 사용하십시오. 일정 시간이 지나면 재설정되는 [copied, copyFn]을 반환하는 useCopyToClipboard 훅을 작성하십시오. 항상 API 사용 가능 여부를 확인하고, 오래된 브라우저를 위해 execCommand 대체 수단을 제공하며, Jest 테스트에서는 navigator.clipboard를 모의 처리하십시오.