Canvas API 기본 내용 정리 / React에서 사용법

캔버스 기본 세팅 for React

---

💡 캔버스는 HTML 요소 중 하나로 스크립트 언어로 그림을 그리는데 사용한다.

 

canvas를 사용하기 위해선 캔버스 context에 DOM으로 접근해야 한다. React에선 useRef()를 사용해서 Ref 객체를 만들고 접근하고 싶은 DOM의 ref 값으로 설정해주면 된다. 그럼 Ref 객체의 .current 값은 해당 DOM을 가리킨다.

 

캔버스 엘리먼트 생성 및 useRef 설정

import React, { useRef, useEffect, useState } from 'react';
import styled from 'styled-components';

const Canvas = () => {
  const canvasRef = useRef(null);

  // 생략
  return <DrawingArea ref={canvasRef} />;
};

/* ----- 스타일 영역 ----- */
const DrawingArea = styled.canvas`
  // 생략
`;

 

캔버스 사이즈 설정 및 드로잉 컨텍스트 참조

canvasRef의 기본값은 null이기 때문에 컴포넌트가 마운트 된 후 코드를 실행하도록 useEffect 안에다 코드를 작성한다.

 

아직 경험하진 못했지만 컴포넌트가 렌더되고 가끔 useRef 참조값이 null인 경우가 있다고. useState를 활용해 드로잉 컨텍스트를 상태로 저장하면 이런 경우를 방지할 수 있다고 함.

const Canvas = () => {
  const canvasRef = useRef(null);
  const [ctx, setCtx] = useState();

  useEffect(() => {
    // 캔버스 사이즈 설정
    const canvas = canvasRef.current;
    canvas.width = window.innerHeight; // 혹은 원하는 사이즈 px없이 숫자만 입력
    canvas.height = window.innerWidth; // 혹은 원하는 사이즈 px없이 숫자만 입력

    // 캔버스 context 접근 후 기본 설정
    const context = canvas.getContext('2d'); // "그리기 메서드와 속성을 갖는" 2차원 드로잉 컨텍스트 참조
    context.strokeStyle = 'black'; // line 색
    context.lineWidth = 3; // line 굵기
    context.lineJoin = 'round'; // 선 연결 모양(기본 값 miter 일반 모양)
    context.lineCap = 'round'; // 선 끝 모양
    context.save(); // 드로잉 컨텍스트 설정 저장
    setCtx(context); // 설정한 드로잉 컨텍스트를 상태로 저장
  }, []);
};

 

마우스 이벤트 핸들러 설정

💡 offset 좌표는 이벤트가 걸려 있는 DOM 객체를 기준으로 좌표를 출력한다. canvas 요소에 이벤트를 걸었다면 브라우저 화면이 아닌 canvas 요소가 기준이 된다. offset 좌표의 기본값은 왼쪽 상단 (0, 0)

 

캔버스에서 마우스로 그림을 그릴 때 이벤트 대상의 x(가로), y(세로) 좌표를 반환하는 offsetX offsetY가 필요하다. 리액트에선 성능 최적화를 위해 래핑된 합성 이벤트(Synthetic Event)를 전달하며 재사용된다.

 

하지만 이 합성 이벤트에선 offset 좌표를 사용할 수 없다. 핸들러에서 이벤트 객체를 콘솔로 찍어보면 offsetX, offsetY를 찾을 수 없다. — 참고 글

 

리액트에서 offset 좌표를 사용하려면 event.nativeEvent를 통해 브라우저의 고유 이벤트에 접근해야 한다. 매개변수 구조분해를 이용해 ({ nativeEvent })이런식으로 명시하면 사용하기 편하다.

const Canvas = () => {
  const [isDrawing, setIsDrawing] = useState(false); // 그리기 상태 설정
  const [path, setPath2D] = useState(new Path2D()); // path 객체 생성

  const startDrawing = ({ nativeEvent }) => {};
  const drawing = ({ nativeEvent }) => {};
  const finishDrawing = ({ nativeEvent }) => {};

  return (
    <DrawingArea
      ref={canvasRef}
      onMouseDown={startDrawing}
      onMouseUp={finishDrawing}
      onMouseMove={drawing}
      // onMouseLeave={finishDrawing} // 마우스가 이벤트 영역 벗어났을 때
    />
  );
};

 

1. 캔버스 위에서 마우스를 움직이면 시작점을 마우스가 위치한 좌표로 이동
   ctx.moveTo(x, y)
2. 마우스를 클릭하면 그리기 상태롤 true로 변경하고
3. 클릭한 상태에서 마우스를 드래그하면 선을 그린다.
   ctx.lineTo(x, y) ctx.stroke(x, y)
4. 클릭 버튼을 떼면 그리기 상태를 false로 변경하고 path를 닫고, 마지막 path까지 선을 그린다.
   ctx.closePath(x, y) ctx.stroke(x, y)

 

그리기 시작 startDrawing

캔버스에서 마우스를 클릭하면 그리기 상태를 true로 변경한다

// 마우스를 클릭하면 실행되는 핸들러
const startDrawing = ({ nativeEvent }) => {
  const { offsetX, offsetY } = nativeEvent;
  setIsDrawing(true); // 그리기 상태 변경
  console.log('start offset: ', offsetX, offsetY);
};

 

그리는 중 drawing

캔버스에서 마우스를 클릭하지 않고 움직이기만 하면 마우스가 위치한 좌표로 시작점을 이동한다. 마우스를 클릭한 후(startDrawing 핸들러 호출 → 그리기 상태 true로 변경) 드래그하면 시작점부터 현재 마우스 좌표까지 선을 긋는다.

// 마우스를 캔버스 위에서 움직이면(혹은 드래그) 실행되는 핸들러
const drawing = ({ nativeEvent }) => {
  // offsetX, offsetY는 이벤트가 걸려있는 DOM 객체를 기준으로 좌표 출력
  const { offsetX, offsetY } = nativeEvent;
  if (ctx) {
    if (!isDrawing) {
      // 클릭하지 않은 상태라면
      path.moveTo(offsetX, offsetY); // 시작점 설정
    } else {
      // 클릭한 상태라면
      path.lineTo(offsetX, offsetY); // 시작점에서(혹은 현재 좌표) 이어질 부분 설정
      ctx.stroke(path); // 선 긋기(화면 출력)
    }
  }
};

 

그리기 종료 finishDrawing

마우스 클릭(onMouseUp)을 떼면 finishDrawing 핸들러가 실행되고, 그리기 상태는 false로 변경된다. path는 닫히면서 시작점과 끝점을 자동으로 연결하고, 다음 그릴 도형을 위해 새로운 path 객체를 생성한다.

// 마우스 클릭을 해제하면 실행되는 핸들러
const finishDrawing = () => {
  setIsDrawing(false); // 그리기 상태 변경
  path.closePath(); // 선 종료 선언(시작점과 끝점을 자동으로 연결한다)
  setPath2D(new Path2D()); // 새로운 path 객체 생성
};

 

(다각형)도형 저장 및 다시 그리기

Path2D 객체를 사용하지 않았을 때

도형마다 모든 offset 좌표를 저장해서 필요 시 해당 도형의 좌표를 이용해 다시 그릴 수 있다. 1개 도형을 그릴 때 마다 좌표 정보를 임시로 저장하는 상태도 필요하다.

// Canvas.js
const Canvas = () => {
  // 여러 도형의 좌표 정보를 저장하는 상태 [[...], [...], [...]]
  const [savedPolygon, setSavedPolygon] = useState([]);
  // 1개 도형을 그릴 때 좌표 정보를 임시로 담아두는 상태 [...]
  const [drawingOffset, setDrawingOffset] = useState([]);

  const startDrawing = ({ nativeEvent }) => {
    const { offsetX, offsetY } = nativeEvent;
    // 생략
    setDrawingOffset([offsetX, offsetY]);
  };

  const drawing = ({ nativeEvent }) => {
    const { offsetX, offsetY } = nativeEvent;
    if (ctx) {
      if (!isDrawing) {
        // 생략(클릭하지 않은 상태에서 마우스 무브)
      } else {
        // 생략(클릭한 상태에서 드래그)
        setDrawingOffset([...drawingOffset, offsetX, offsetY]);
      }
    }
  };

  const finishDrawing = () => {
    // 생략
    setSavedPolygon([...savedPolygon, drawingOffset]); // 완성한 도형의 좌표 정보를 배열에 저장
    setDrawingOffset([]); // 임시 좌표 정보 상태 초기화
  };
};

 

// reDraw.js
export default (ctx, savedPolygon) => {
  savedPolygon.forEach((polygon) => {
    const copied = polygon.slice();

    ctx.beginPath();
    ctx.moveTo(copied.shift(), copied.shift());
    // shift/pop 메소드는 제거한 요소를 반환한다.

    while (copied.length) {
      ctx.lineTo(copied.shift(), copied.shift());
    }
    
    ctx.closePath();
    ctx.stroke();
  });
};

 

Path2D 객체를 사용했을 때(더 간단함)

각 도형의 좌표 정보를 저장할 상태 배열을 만든 후 도형을 완성할 때마다 이 상태에 저장한다. reDraw 함수에선 ctx와 각 도형의 path 정보가 담긴 savedPolygon 배열을 받아서 화면에 그린다. Path2D 인스턴스에 담긴 path 정보는 ctx.stroke(path) 명령어 한 번으로 해당 path의 모든 좌표를 그려주기 때문에 더 깔끔하다.

// Canvas.js
const Canvas = () => {
  const [savedPolygon, setSavedPolygon] = useState([]);
  // savedPolygon [{ path }, { path }, { path }]

  const finishDrawing = () => {
    // 생략
    setSavedPolygon([...savedPolygon, path]); // 그린 도형 상태 배열에 저장
  };
};

 

// reDraw.js
export default (ctx, savedPolygon) => {
  savedPolygon.forEach((path) => ctx.stroke(path));
};

 

기타 참고 내용

• 캔버스 사이즈 기본값은 width 300(px), height 150(px)
• 캔버스에서 1단위는 1픽셀
• 윈도우 사이즈 관련 (참고 링크)
  • window.innerWidth window.innerHeight
  • 스크롤바가 차지하는 공간 포함
  • document.body.clientWidth/clientHeight (body)
    document.documentElement.clientWidth/clientHeight (html)
  • 스크롤바가 차지하는 공간 제외
  • getBoundingClientRect() 메서드로 엘리먼트의 사이즈 정보를 참조할 수 있다.

 

그리기 관련

---

캔버스의 기본 좌상단 좌표는(원점) 0, 0이다. 브라우저가 아닌 캔버스 엘리먼트의 원점인 것 주의. X축(가로)은 오른쪽으로, Y축(세로)은 아래쪽으로 증가하는 데카르트 좌표계를 사용한다.

 

선 Stroke

💡 `lineTo()`는 직선을 그은 후 현재 좌표를 끝점으로 옮긴다. `moveTo()`를 호출하지 않아도 `lineTo()`를 계속 호출하여 이어진 다각형을 그릴 수 있다.

 

기본적으로 캔버스에서 선을 그리는 순서는 아래와 같다. 외각선을 그린 후 fill()을 이용해 안쪽 색상을 채울 수도 있다. 이때 fillStyle = 'lightgray' 등으로 색상을 미리 지정해줘야 한다. fill()을 사용하면 path가 닫혀있지 않았을 경우 자동으로 닫은 후 채운다.

ctx.beginPath(); // 빈 경로 생성
ctx.moveTo(x, y); // 시작점 설정(좌표만 이동)
ctx.lineTo(x, y); // 시작점(현재 좌표)에서 x, y 좌표까지 선 긋기(좌표만 기록)
ctx.closePath(); // path를 닫는다(시작점과 끝점 연결)
ctx.stroke(); // 외곽선 "그리기"(화면 출력)

 

Path2D 인스턴스 객체를 새로 생성하여 그리는 방법도 있다. Path2D는 따로 beginPath() 메소드를 갖지 않는걸 봐선 빈 경로를 수동으로 생성할 필요가 없나보다. Path2D 객체를 이용해 그린 외곽선은 fill()을 이용해 안쪽 색상을 채울 수 없다(참고 링크)

const path = new Path2D() // 새로운 Path 객체 생성
path.moveTo(x, y) // 시작점 설정(좌표만 이동)
path.lineTo(x, y) // 시작점(현재 좌표)에서 x, y 좌표까지 선 긋기(좌표만 기록)
path.closePath() // path를 닫는다(시작점과 끝점 연결)
ctx.stroke(path) // 외곽선 "그리기"(화면 출력)

 

선을 그릴 때 마다 매번 위 같은 코드를 작성하기 번거롭기 때문에 보통 x, y 좌표를 받아 선을 그리는 drawLine 같은 함수를 선언해서 사용한다(드로잉 컨텍스트가 전역이 아니어서 접근할 수 없다면 ctx도 매개변수로 넘겨야 한다)

// 채워지지 않은 다각형 그리기 예제
ctx.beginPath();
ctx.moveTo(170, 110);
ctx.lineTo(220, 110);
ctx.lineTo(220, 160);
ctx.closePath();
ctx.stroke();

 

 

// 색상이 채워진 다각형 그리기 예제
ctx.fillStyle = 'lightgray'; // 채우기 색상 지정
ctx.beginPath();
ctx.moveTo(170, 110);
ctx.lineTo(220, 110);
ctx.lineTo(220, 160);
ctx.closePath();
ctx.fill();

 

 

사각형 Rect

x, y 좌표를 넘긴 곳 부터 width, height의 크기를 가지는 사각형을 그린다. clearRect()도 같은 원리로 캔버스에 그린 사각형을 지우는데 캔버스에 그린 모든 도형을 지우고 싶을 때 유용하다. 이때 x, y는 0을 width, height는 캔버스의 크기를 넘기면 된다.

ctx.strokeRect(x, y, width, height); // 채워지지 않은 사각형(외곽선만 있는)
ctx.fillRect(x, y, width, height); // 채워진 사각형
ctx.clearRect(x, y, width, height); // 사각형 삭제

 

원 Arc

기본 사용법

arc(x, y, r, st, ed, anticlockwise);
// x, y : 원의 중심점
// r : 반지름
// st, ed : 시작각과 끝각(3시 방향으로 0도하여 시계 방향으로 증가하는 라디안 값)
// anticlockwise : 원을 그리는 방향 true는 반시계, false는 시계(기본값) 방향

 

원 그리기 예제. 원 전체를 그리므로 원 방향은 명시하지 않아도 된다(어느 쪽이든 원 전체가 그려짐). 

ctx.beginPath();
ctx.arc(200, 200, 100, 0, 2 * Math.PI);
ctx.stroke();

 

원을 그릴 때 시작/끝 각은 라디안(호도법; 弧度) 값이다. 라디안은 반지름과 호(弧)의 길이가 같아지는 각도를 의미하는데 일반적으로 라디안보단 각도°에 익숙하므로 각도 * Math.PI/180으로 대신 계산할 수 있다.

 

• 1 * Math.PI 180도
• 2 * Math.PI 360도

 

 

곡선 / 호

자세한 내용은 한글 링크 참고.

quadraticCurveTo(cpx, cpy, x, y); // 곡선 그리기
arcTo(x1, y1, x2, y2, radius); // 제어점 사이의 호/곡선 그리기

 

현재 좌표가 도형/선 안에 있는지 확인

---

 

ctx.isPointInPath([path], x, y)

인자로 전달한 x, y 캔버스 좌표가 도형의 안쪽 영역에 있는지 확인한 후 Boolean 값을 반환한다. Path2D 객체를 이용했다면 첫번째 인자에 path를 넘겨야 한다. 

 

아래는 클릭한 좌표가 도형의 안쪽이라면 해당 도형을 삭제하는 예제.

// onMouseDown 마우스 클릭 핸들러
const deleteHandler = ({ nativeEvent: e }) => {
  const x = e.offsetX;
  const y = e.offsetY;

  // 저장한 도형 path를 하나씩 검사한다
  savedPolygon.forEach((polygon, index) => {
    if (ctx.isPointInPath(polygon, x, y)) {
      const remaningPolygons = [
        ...savedPolygon.slice(0, index),
        ...savedPolygon.slice(index + 1),
      ];
      setSavedPolygon(remaningPolygons);
      reDraw(ctx, remaningPolygons, canvasSize);
    }
  });
};

 

ctx.isPointInStroke([path], x, y)

인자로 전달한 x, y 캔버스 좌표가 Stroke 영역의 안쪽인지 확인한 후 Boolean 값을 반환한다.  Path2D 객체를 이용했다면 첫번째 인자에 path를 넘겨야 한다.

 

아래는 좌표가 선 위에 있다면 커서가 grab으로 바뀌는 예제. 

// onMouseMove 마우스 이동 핸들러
if (ctx.isPointInStroke(x, y)) {
  e.target.style.cursor = 'grab';
} else {
  e.target.style.cursor = '';
}

 

캔버스 이미지 포맷 변환 / 다운로드 / 그리기

---

이미지 다운로드

캔버스에 그린 내용들을 canvas.toDataURL(type, option)을 이용해 원하는 포맷으로 변환한 후 다운로드할 수 있다. type에는 이미지 포맷을 입력하고, option에는 0과 1사이에 숫자를 입력하여 이미지의 퀄리티를 지정할 수 있다(높을 수록 좋은 퀄리티). option 파라미터에 아무것도 입력하지 않으면 0.92가 기본값

 

• toDataURL('image/png') 기본값(파라미터를 따로 명시하지 않으면 기본값)
• "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9C..."
• toDataURL('image/webp')
• toDataURL('image/jpg')

 

// 다운로드 버튼 클릭시 이미지 다운로드
export default (canvasRef) => {
  const image = canvasRef.current
    .toDataURL('image/png') // 기본값
    .replace('image/png', 'image/octet-stream'); // 2진 데이터 표현
  // window.location.href = image;
  
  const a = document.createElement('a'); // a태그 생성
  a.style.display = 'none'; // (선택)화면에서 보이지 않도록 display 설정
  a.href = image; // 외부 리소스의 URL 할당
  a.download = 'yourImage.png'; // 다운로드 진행 시 기본값으로 지정할 파일명
  a.click(); // 클릭 이벤트
};

 

💡 만약 이미지가 Blob 객체라면 window.URL.createObjectURL()을 이용해 url(DOM String)로 바꿀 수 있다. 변환한 url은 window 창이 사라지면 함께 사라지므로 다른 window에서 재사용할 수 없다. (참고 블로그)

// blob:http://localhost:1234/28ff8746-94eb-4dbe-9d6c-2443b581dd30
const url = window.URL.createObjectURL(blob);
a.href = url;

 

이미지 데이터 그리기

반대로 이미지 DataURL을 캔버스에 그리려면 onload 속성을 이용해야 한다. 이미지는 텍스트에 비해 용량이 크다. 용량이 크므로 로드 속도도 느리다. 비동기로 작동하는 특성 때문에 이미지를 완전히 로드할 때까지 기다리지 않고, 화면에 이미지 태그를 먼저 표시한 후, 이미지 데이터는 따로 읽는다.

 

onload 속성을 사용하면 DOM 트리뿐만 아니라 이미지, 스타일시트 같은 외부 리소스를 모두 로드했을 때 특정 작업을 수행하도록 할 수 있다. 즉 아래 코드는 이미지가 모두 로드된 후에 ctx.drawImage()가 실행된다. 만약 onload 속성을 사용하지 않았다면 ctx.drawImage()를 호출했을 시점에 이미지가 모두 로드되지 않았다면 화면 출력은 실패한다. — 참고1, 참고2

const image = new Image();
image.onload = function () {
  ctx.drawImage(image, 0, 0);
};
image.src = correctAnswer;

// 위 코드는 아래와 같다
// <image src={correctAnswer} onload={() => ctx.drawImage(image, 0, 0)} />

 

실행 취소 기능 / imageData

---

캔버스 전체 혹은 일부 픽셀 정보를 imageData 객체로 반환하는 getImageData()를 이용해 실행 취소 기능을 구현할 수도 있다. 마우스 클릭 → 드래그 → 마우스 클릭 해제 작업을 반복할 때마다 캔버스 전체를 imageData로 저장하고, 실행 취소 버튼을 누르면 putImageData()를 이용해 바로 이전 imageData 객체를 캔버스에 복원하는 방식.

 

• ctx.createImageData(width, height)
  • 빈 imageData 생성
  • width, height : imageData의 가로/세로 크기
• ctx.createImageData(imageData)
  • 사본 imageData 생성
• ctx.getImageData(x, y, width, height)
  • x, y : 이동할 좌표 거리
  • x, y 둘다 0을 입력하고 캔버스의 width, height를 입력하면 캔버스 전체를 저장한다.
• ctx.putImageData(imageData, x, y, [dx], [dy], [dw], [dh])
  • x, y : 이동할 좌표 거리
  • (옵션) dx, dy : imageData의 x, y 좌표
  • (옵션) dw, dh : imageData의 가로, 세로 크기
  • dx, dy, dw, dh : 원본 이미지의 일부를 잘라서 사용할 때 유용하다

 

💡 ctx.getImageData(x, y, 1, 1).data 를 통해 현재 좌표의 RGBA 색상값을 확인할 수 있다.

 

imageData 객체엔 data, width, height 속성을 갖는다. data 속성엔 래스터(픽셀 정보) 정보가 담겨 있다. 1개 픽셀엔 R(红) G(绿) B(蓝) A(Alpha) 4개의 값을 가진다. RGB 값의 범위는 0~255의 숫자이며, 투명도를 나타내는A는 0에 가까울 수록 투명해진다.

 

이미지 출처 - seon

 

const imageData = ctx.createImageData(300, 300);
console.log(imageData);
// {data: Uint8ClampedArray(360000), width: 300, height: 300}

for (let i = 0; i < imageData.data.length; i += 3) {
  // ['R','G','B','A','R','G','B','A']
  // RGB ARG BAR GBA 순서를 반복한다
  imageData.data[i + 0] = 100; // R/A/B/G...
  imageData.data[i + 1] = 0; // G/R/A/B...
  imageData.data[i + 2] = 0; // B/G/R/A...
}
ctx.putImageData(imageData, 300, 300);

 

 

캔버스 설정값 저장/복원

---

캔버스 상태는 ctx.save()로 저장하고, ctx.restore()로 복원할 수 있다. 캔버스에 그린 선/도형이나 이미지를 저장하는게 아닌 캔버스의 matrix, strokeStyle 등의 속성을 저장한다.

 

ctx.restore()는 가장 최근의 저장한 캔버스 상태를 복원한다. save()를 3번하고 restore()를 3번하면 마지막 save()부터 차례대로 복원한다. 마지막 save()까지 모두 복원한 후 restore()를 한 번 더 하면 첫번째로 저장한 save() 값을 불러온다(참고 링크).

ctx.save(); // 1번 저장
ctx.save(); // 2번 저장
ctx.save(); // 3번 저장
ctx.restore(); // 3번 복구
ctx.restore(); // 2번 복구
ctx.restore(); // 1번 복구
ctx.restore(); // 1번 복구

 

캔버스 그리기 비활성화

---

캔버스 엘리먼트 CSS에 아래 속성을 추가한다.

cursor: not-allowed; /* 요청된 작업을 수행하지 않음을 나타내는 커서 */
pointer-events: none; /* 마우스 포인터 옵션(클릭, hover, 커서 드래그 등) 비활성화 */

 

레퍼런스

---

• MDN Canvas 캔버스 튜토리얼 (한글)
• HTML Canvas Reference (캔버스 활용 레퍼런스)
• Canvas 参考手册 (중문)
• 하보니 캔버스 Canvas 기초 가이드 (한글)
• SoEn 캔버스 Canvas 가이드 (한글)  

 

---

글 수정사항은 노션 페이지에 가장 빠르게 반영됩니다. 링크를 참고해 주세요