API

@newtil/drawing 의 export 전부. 타입은 소스 그대로다.

import {
  openDrawing, DrawingBoard, type OpenOptions, type OpenResult,
  renderToPng, blobToDataURL, loadImage,
  emptyDrawing, bounds, type Drawing, type Shape, type Fill, type ToolName,
  messagesKo, messagesEn, type Messages, type Lang,
  VERSION,
} from "@newtil/drawing";

그림판

openDrawing

function openDrawing(opts?: OpenOptions): Promise<OpenResult | null>

그림판 팝업을 연다. 완료면 OpenResult, 취소면 null. 내부적으로 new DrawingBoard(opts).open() 이다.

OpenOptions

interface OpenOptions {
  /** 다시 고칠 그림. 없으면 빈 판 */
  initial?: Drawing | null;
  /** 시작 배경 — 캡처 파일(Blob) 또는 같은 출처 이미지 주소. initial 이 있으면 무시 */
  background?: Blob | string | null;
  /** 완료 때 부른다 — 저장하고 문서에 넣을 주소 등을 돌려준다. 던지면 팝업이 열린 채 이유를 보인다 */
  save?: (png: Blob, data: Drawing) => Promise<string | void>;
  /** 열 때 잠깐 보일 안내 */
  notice?: string;
  lang?: string;
  messages?: Partial<Messages>;
  /** 팝업을 붙일 자리. 기본 document.body */
  mount?: HTMLElement;
}

필드	설명
initial	이전 결과의 data. 복제해서 쓰므로 원본은 바뀌지 않는다. 저장 훅
background	긴 변 1600px 로 줄여 data URL 로 굽는다. 실패하면 배경 없이 연다. 교차 출처 주소는 canvas 를 오염시켜 실패한다
save	저장 훅
notice	6초간 판 위에 보이는 안내 문구
lang	메시지 언어. 다국어
messages	메시지 일부 덮어쓰기
mount	팝업 호스트 엘리먼트(div.newtil-drawing, shadow root 포함)를 붙일 부모

OpenResult

interface OpenResult { data: Drawing; png: Blob; /** save 가 돌려준 값(주소 등) */ saved?: string }

DrawingBoard

class DrawingBoard {
  constructor(opts: OpenOptions);
  open(): Promise<OpenResult | null>;
}

openDrawing 이 쓰는 클래스. open() 은 mount(기본 document.body)에 팝업을 붙이고 닫힐 때까지 기다린다. 그 밖의 멤버는 private 이다.

렌더링

renderToPng

function renderToPng(data: Drawing): Promise<Blob>

Drawing 전체를 width × height PNG Blob 으로 굽는다. 흰 바탕 → 배경 → 도형 순. 팝업의 화면(SVG)과 같은 규칙.

blobToDataURL

function blobToDataURL(blob: Blob): Promise<string>

FileReader.readAsDataURL 래퍼.

loadImage

function loadImage(src: string): Promise<HTMLImageElement>

data URL 또는 같은 출처 주소를 Image 로 로드한다. 실패하면 Error("image load failed").

데이터

타입

type ToolName = "select" | "pen" | "highlighter" | "line" | "arrow" | "arrow2" | "rect" | "ellipse" | "text" | "badge";
type Fill = "translucent" | "solid";

interface ShapeBase {
  id: string;
  color: string;
  stroke: number;
  /** 채우기 — 사각형·타원·배지 */
  fill?: Fill | null;
  /** 점선 */
  dashed?: boolean;
  /** 전체 투명도 0~1. 없으면 1 */
  opacity?: number;
}
type Shape =
  | (ShapeBase & { type: "rect"; x1: number; y1: number; x2: number; y2: number; radius?: number })
  | (ShapeBase & { type: "ellipse"; x1: number; y1: number; x2: number; y2: number })
  | (ShapeBase & { type: "line" | "arrow" | "arrow2"; x1: number; y1: number; x2: number; y2: number })
  | (ShapeBase & { type: "pen" | "highlighter"; points: number[] })
  | (ShapeBase & { type: "text"; x: number; y: number; text: string; size: number })
  | (ShapeBase & { type: "badge"; x: number; y: number; n: number; size: number });

interface Drawing {
  version: 1;
  width: number;
  height: number;
  /** 배경 캡처 — data URL. 없으면 흰 판 */
  background: string | null;
  shapes: Shape[];
}

ShapeBase 자체는 export 되지 않는다(Shape 에 녹아 있다). 필드 의미는 데이터 형식.

emptyDrawing

function emptyDrawing(width?: number, height?: number): Drawing   // 기본 800 × 450

bounds

function bounds(s: Shape): { x: number; y: number; w: number; h: number }

도형의 바깥 상자. 글자는 글자 폭 0.6em 가정의 어림값. 반환 타입 Box 는 export 되지 않는다.

메시지

type Lang = "ko" | "en";

interface Messages {
  title: string;
  toolSelect: string; toolPen: string; toolHighlighter: string; toolLine: string; toolArrow: string; toolArrow2: string;
  toolRect: string; toolEllipse: string; toolText: string; toolBadge: string;
  color: string; customColor: string; strokeWidth: string;
  fillNone: string; fillTranslucent: string; fillSolid: string; dashed: string; opacity: string;
  undo: string; redo: string; delete: string; duplicate: string; bringForward: string; sendBackward: string;
  background: string; clearBackground: string; zoomFit: string;
  done: string; cancel: string; saving: string;
  textPrompt: string; pasteHint: string; discardConfirm: string; exportFailed: string; saveFailed: (reason: string) => string;
}

const messagesKo: Messages;
const messagesEn: Messages;

키별 의미와 기본값은 다국어.

버전

const VERSION = "0.1.0";