[React] 화면(DOM) 캡쳐 및 저장 기능 구현하기 (feat. html2canvas, file-saver)

[React] 화면(DOM) 캡쳐,저장 기능 구현하기 (feat. html2canvas, file-saver)

📖 들어가며

React에서 화면 (DOM)를 캡처, 저장하는 기능에 대해서 알아보려 합니다.

작은 토이 프로젝트를 하면서 여러가지 문제를 맞이 했었는데, 결과적으로 성공한 방법들로 포스팅하게 됩니다.

캡쳐(스크린샷)을 도와주는 라이브러리들

대표적으로 html2canvas, dom-to-image, html-to-image 등이 있습니다.

기능을 구현하면서 html2canvas와 dom-to-image를 모두 사용해 봤습니다.

 

제가 사용해 본 두 가지 라이브러리에 대해서는 일반적으로 두 라이브러리 모두 영역을 정확하게 캡처하고 DOM 요소에 적용된 CSS 스타일을 캡처하는 데 큰 문제는 없었습니다.

 

그러나 dom-to-image가 html2canvas보다 더 빠르고 안정적이라고 하는 사용자도 있다고 합니다.

또한, dom-to-image는 더 작은 번들 크기(약 14kb)를 갖는 반면 html2canvas는 더 큰 번들 크기(약 140kb)를 갖는다는 것을 고려해 볼 수 있습니다.

 

따라서 번들 크기가 중요한 경우 dom-to-image를 사용하는 것이 더 좋을 수 있습니다.

그러나 두 라이브러리의 큰 차이점 중 하나는 라이브러리가 처리하는 기능의 범위입니다.

html2canvas는 SVG 및 Canvas 요소도 캡처할 수 있으므로 더 다양한 요소에 대한 캡처 기능을 제공합니다.

반응형

실제로, 개발하면서 DOM요소 안에 img 파일이 포함되어 있는 상황에서 dom-to-image는 img파일을 인식하지 못하여 img파일이 깨져서 캡처되는 결과를 볼 수 있어서 dom-to-image에서 html2canvas로 변경했습니다.

 

SVG 및 Canvas를 포함한 다양한 요소에 대한 캡처가 필요한 경우 html2canvas를 선택하는 것이 최선이라고 할 수 있습니다.

그것이 아니라면 가볍고 빠른 dom-to-image를 선택하는 것이 최선인 것 같습니다.

 

html2canvas와 dom-to-image로 코드를 작성하는 부분은 매우 유사하고 쉽기 때문에 다른 걱정은 하지 않아도 됩니다.

 

그래도 html2canvas가 현재는 압도적으로 많이 사용되고 있습니다.

NPM 다운로드 순위 비교

html2canvas

사용자 브라우저에서 직접 웹 페이지 또는 그 일부의 "스크린샷"을 찍을 수 있다. 스크린샷은 DOM을 기반으로 한다.

캡처할 영역 (DOM)을 지정하고 해당 영역에 대한 스크린샷을 찍을 수 있도록 도와주는 라이브러리입니다.

https://html2canvas.hertzen.com/

html2canvas - Screenshots with JavaScript

설치 방법

npm install html2canvas
or
yarn add html2canvas

기본적인 사용 방법 예시

const saveAsImageHandler = () => {
    const target = document.getElementById('content');
    if (!target) {
      return alert('결과 저장에 실패했습니다.');
    }
    html2canvas(target).then((canvas) => {
      const link = document.createElement('a');
      document.body.appendChild(link);
      link.href = canvas.toDataURL('image/png');
      link.download = 'result.png';
      link.click();
      document.body.removeChild(link);
    });
  };

html2canvas에 대한 사용 방법을 찾아보면 보통 이런 식으로 많이 기능을 작성하는 예제를 많이 찾아볼 수 있습니다.

 

하지만 이렇게 a tag를 통해서 코드를 작성했을 때 PC에서는 전혀 문제가 없었으나, IPhone 기준 Safari 브라우저 외에 모두 작동하지 않았습니다.

 

Android에서는 테스트를 해볼 수가 없어서 비슷한 상황으로 구글링을 해본 결과 Samsung Phone에서 자동 다운로드를 차단해 놓은 것으로 확인 됐습니다.

file-saver

위에서 말한 문제점을 해결하기 위해 클라이언트에서 파일 저장을 도와주는 라이브러리 file-saver가 있습니다.

 

file-saver를 사용하면 PC, Mobile 각 환경과 웬만한 브라우저 모두 호환이 되도록 해주는 기능을 해주고 있고, 간단한 코드로 파일을 blob, file, url 형식에 대한 파일로 저장하는 것을 저장할 수 있도록 도와주고 있습니다.

 

https://www.npmjs.com/package/file-saver

file-saver

설치 방법

npm install file-saver --save
or
yarn add file-saver

타입스크립트 환경에서는 타입 정의도 따로 설치를 해줘야 합니다.

npm install @types/file-saver --save-dev
or
yarn add @types/file-saver -D

 

출처: https://github.com/eligrey/FileSaver.js#readme

html2canvas + file-saver

그럼 이제 html2canvas와 file-saver를 통해서 어떻게 저장 기능을 구현할지 알아보겠습니다.

먼저 개발 환경은 React + TypeScript 환경입니다.

예시 코드

import "./styles.css";
import html2canvas from "html2canvas";
import saveAs from "file-saver";
import { useRef } from "react";

export default function App() {
  const divRef = useRef<HTMLDivElement>(null);

  const handleDownload = async () => {
    if (!divRef.current) return;

    try {
      const div = divRef.current;
      const canvas = await html2canvas(div, { scale: 2 });
      canvas.toBlob((blob) => {
        if (blob !== null) {
          saveAs(blob, "result.png");
        }
      });
    } catch (error) {
      console.error("Error converting div to image:", error);
    }
  };

  return (
    <div className="App">
      <div
        ref={divRef}
        style={{ backgroundColor: "lime", width: "300px", height: "200px" }}
      >
        <h1>Hello CodeSandbox</h1>
        <h2>Start editing to see some magic happen!</h2>
      </div>
      <button onClick={handleDownload}>다운로드</button>
    </div>
  );
}

html2canvas의 떠돌아다니는 기본 예제에는 querySelector로 DOM요소를 잡아주는데,

React 환경에서는 useRef DOM요소를 다루는 것이 일반적이기 때문에 useRef로 캡처 영역을 지정해 주었습니다.

 

React에서 querySelector 대신 useRef로 DOM을 다뤄야 하는 이유

1. React 선언적 방식에 적합: useRef는 React의 선언적 방식에 보다 적합합니다. React에서는 UI를 작성할 때 선언적인 코드 스타일을 사용하므로, useRef를 사용하면 코드의 일관성이 유지되고 리액트적인 개발 습관을 지킬 수 있습니다.
2. 직접 조작 최소화: React는 컴포넌트의 상태와 렌더링의 관리를 도와주는 라이브러리입니다. querySelector와 같은 순수 JavaScript 코드를 사용하면, 직접 DOM 조작이 필요하므로 리액트의 철학에 어긋납니다. useRef는 DOM에 대한 참조를 효과적으로 관리할 수 있어 상태 변경 시 React가 수행하는 렌더링 최적화를 방해하지 않습니다.
3. 리렌더링에 안전: querySelector는 렌더링 시마다 호출되어야 하며, 결과적으로 여러 번 DOM을 찾아야 하는 반면, useRef는 한 번만 DOM을 찾아서 계속 참조하므로 리렌더링에 안전하고 성능에 더 이점을 줍니다.
4. 컴포넌트의 생명주기 전반에 사용 가능: useRef는 React의 다양한 생명주기와 관련 Hook들, 예를 들어 useEffect, useState, useCallback 등과 함께 사용할 수 있습니다. 이로 인해 더 유연하게 코드를 구성할 수 있으며, 컴포넌트의 생명주기와 상태에 따라 참조값을 업데이트하거나 이벤트를 처리하는 데 도움이 됩니다.

이러한 이유로 인해, React에서 DOM 요소를 다룰 때 useRef를 사용하는 것이 좋습니다. 물론 필요한 경우(확인 전용 용도 등) querySelector를 사용하는 것이 어쩔 수 없지만, 가능한 한 React 컴포넌트의 상태와 생명주기를 지킬 수 있는 useRef를 사용하는 것이 좋습니다.

 

캡처할 영역을 지정해 주고 html2canvas에 넘겨주고 html2canvas가 캡처해 준 것 blob으로 변환한 다음 file-saver를 통해서 저장되도록 해주었습니다.

 

라이브러리를 사용해서 기능을 구현하는 코드 자체가 매우 직관적인 것을 볼 수 있습니다.

📕 마무리

html2canvas와 file-saver 라이브러리와 사용하는 방법에 대해서 알아봤습니다.

 

각 라이브러리들에 대해 다양한 옵션들도 있으니 각 라이브러리에 대한 문서를 참고 하시면 됩니다.