Dee Editor 매뉴얼

Dee Editor는 외부 의존성 없이 순수 JavaScript로 구현된 WYSIWYG 웹 에디터입니다. 이 문서는 설치부터 고급 기능 연동까지 전체 API를 설명합니다.

1. 빠른 시작

1-1. 파일 로드

아래 두 파일을 HTML에 포함합니다. Word 가져오기가 필요한 경우 추가 플러그인을 로드하세요.

<!-- 스타일시트 -->
<link rel="stylesheet" href="dist/webeditor.min.css">

<!-- 코어 번들 -->
<script src="dist/webeditor.min.js"></script>

<!-- Word 가져오기 기능이 필요한 경우 (선택) -->
<script src="dist/plugins/wordimport-native.min.js"></script>

<!-- 한글 HWPX 가져오기 기능이 필요한 경우 (선택) -->
<script src="dist/plugins/hwpximport-native.min.js"></script>

1-2. 기본 초기화

<div id="editor"></div>

<script>
const editor = new WebEditor('#editor', {
  height: '400px'
});
</script>

1-3. 데이터 읽기/쓰기

// 본문 HTML 가져오기 (폼 submit 시 사용)
const html = editor.getHTML();

// 본문 설정 (기존 데이터 불러올 때)
editor.setHTML('<p>저장된 내용</p>');

// 순수 텍스트만 가져오기
const text = editor.getText();

2. 초기화 옵션

2-1. uploadHandler 사용 예

new WebEditor('#editor', {
  uploadHandler: async (file) => {
    const form = new FormData();
    form.append('file', file);
    const res = await fetch('/api/upload', {
      method: 'POST',
      body: form
    });
    const data = await res.json();
    return data.url; // 업로드된 이미지 URL 반환
  }
});

2-2. UI 설정(config) — 설정 페이지로 만들기·적용

툴바·메뉴바·너비 등 UI 구성을 코드로 직접 쓰는 대신, 설정 페이지에서 시각적으로 구성해 config 파일로 저장할 수 있습니다. 설정 허브: demo/settings.html

UI config 형식 — 초기화 옵션과 동일한 구조입니다.

window.DEEDITOR_UI_CONFIG = {
  menubar: true,          // 메뉴바 표시 여부
  statusbar: true,        // 상태표시줄
  width: "100%",          // "100%" 또는 숫자(px)
  toolbar: [               // 행(단)별 명령 배열, '|' = 그룹 구분선
    ["newDocument", "save", "|", "undo", "redo" /* …1단… */],
    ["paragraphStyle", "fontFamily", "|", "bold" /* …2단… */]
  ]
};

적용 — config 파일을 포함하고 옵션으로 전달합니다.

<script src="webeditor-ui-config.js"></script>
<script>
var cfg = window.DEEDITOR_UI_CONFIG || {};
var editor = new WebEditor('#editor', {
  menubar: cfg.menubar, toolbar: cfg.toolbar, plugins: [/* 전체 */]
});
if (cfg.statusbar === false) editor.showStatusBar(false);
if (cfg.width) editor.setWidth(cfg.width);
</script>

2-3. 문서 템플릿 · 표 레이아웃 (DeeDocTools) v2.6.0.0

공용 모듈 doc-tools.js를 로드하고 DeeDocTools.attach(editor) 한 줄이면 파일 ▸ 템플릿(기본 문서 양식)과 파일 ▸ 레이아웃(표 구조)이 메뉴에 추가됩니다. 코어와 무관한 opt-in 모듈이라 미로드 시 영향이 없습니다.

<script src="dist/webeditor.min.js"></script>
<script src="doc-tools.js"></script>

const editor = new WebEditor('#editor', { menubar: true });
DeeDocTools.attach(editor);   // 파일 ▸ 템플릿 / 레이아웃 메뉴 추가

3. 인스턴스 메서드

대부분의 setter 메서드는 this를 반환하여 메서드 체이닝이 가능합니다.

3-1. 콘텐츠 I/O

const html = editor.getHTML();
// '<p>안녕하세요</p><p>반갑습니다</p>'

editor.setHTML('<p>새 내용</p>');

const text = editor.getText();
// '안녕하세요\n반갑습니다'

editor.appendHTML('<p>추가된 단락</p>');

editor.insertHTML('<strong>굵은 텍스트</strong>');

const selected = editor.getSelectedHTML();

const text = editor.getSelectedText();

editor.clear();

btn.addEventListener('click', () => editor.pasteFromClipboard());

3-2. 상태 제어

editor.setReadOnly(true);   // 읽기 전용
editor.setReadOnly(false);  // 편집 가능

if (editor.isReadOnly()) {
  console.log('읽기 전용 모드입니다');
}

window.addEventListener('beforeunload', (e) => {
  if (editor.isModified()) {
    e.preventDefault();
  }
});

editor.resetModified();

editor.setHeight(600);
editor.setHeight('80vh');

const h = editor.getHeight(); // 600

editor.setWidth('100%');
editor.setWidth(800);

editor.setTab(1);          // HTML 소스 보기
editor.setTab('preview');  // 이름으로도 전환

editor.getActiveTab();      // 0
editor.getActiveTab(true);  // 'edit'

editor.showToolbar(false);   // 툴바 숨김
editor.showMenuBar(false);   // 메뉴바 숨김

3-3. 이미지

editor.insertImage('https://example.com/photo.jpg');
editor.insertImage('data:image/png;base64,...');

const urls = editor.getImages();
// ['https://...', 'data:image/png;...']

<figure class="we-img-figure">
  <img src="...">
  <figcaption contenteditable="true">캡션 텍스트</figcaption>
</figure>

// 캡션 없이
<a href="https://example.com" target="_blank" rel="noopener noreferrer" data-we-img-link="1">
  <img src="...">
</a>

// 캡션 있을 때 — <a>는 <img>만 감쌈
<figure class="we-img-figure">
  <a href="..." data-we-img-link="1"><img src="..."></a>
  <figcaption contenteditable="true">캡션</figcaption>
</figure>

3-4. 콘텐츠 정제

editor.clearFormat();

editor.clearCSSFormat();

editor.removeTag('span');    // <span style="...">텍스트</span> → 텍스트
editor.removeTag('strong');

3-5. 런타임 설정

editor.setDefaultFont('Arial');
editor.setDefaultFont('Noto Sans KR');

editor.setDefaultFontSize(16);

editor.setDefaultLineHeight('1.6');
editor.setEditorDefaults({ font: 'Georgia', fontSize: 16, lineHeight: '2' });
editor.getEditorDefaults();  // { font:'Georgia', fontSize:16, lineHeight:'2' }

editor.setContentCSS(`
  p { line-height: 1.8; }
  img { max-width: 100%; }
`);

3-6. 생명주기

editor.focus();

editor.destroy();

3-7. Word · HWPX 가져오기

// 파일 input에서
document.getElementById('fileInput').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) await editor.importWordFile(file);
});

// 드롭 이벤트에서
dropZone.addEventListener('drop', async (e) => {
  e.preventDefault();
  const file = e.dataTransfer.files[0];
  await editor.importWordFile(file);
});

const editor = new WebEditor('#editor', { plugins: ['format', 'table', 'hwpximport'] });
await editor.importHwpxFile(file, { mode: 'replace', maxTableWidth: 740 });

3-8. v2.4 신규 메서드

const safe = editor.getSafeHTML({ allowedTags: ['p','b','a'], allowedAttrs: ['href'] });

const editor = new WebEditor('#editor', {
  autoSave: { interval: 30000, unloadWarning: true }
});
const saved = editor.getAutoSaved();
if (saved) { editor.setHTML(saved); editor.clearAutoSaved(); }

const r = await editor.validate();   // { profanity:[...], privacy:[...] }
await editor.maskSensitiveData();      // 본문 전체 마스킹
await editor.reviewSensitiveData();    // 결과 팝업(선택 마스킹)

await editor.setDocumentBackground({ image: file, color: '#fff7e6', repeat: 'no-repeat', attachment: 'scroll' });
editor.getDocumentBackground();   // { image, color, repeat, attachment, mode, store }
editor.removeDocumentBackground();

editor.setUITemplate('ribbon');
editor.getUITemplate();   // 'ribbon'

editor.setIconTheme('vivid');
editor.getIconTheme();   // 'vivid'

editor.toggleToolbar();   // 툴바 표시/숨김 토글 (Ctrl+[)
editor.toggleMenuBar();   // 메뉴바 표시/숨김 토글 (Ctrl+])

editor.setTableBorderColor('#888888');
editor.getTableBorderColor();   // '#888888'

4. 이벤트 시스템

// 변경 감지
editor.on('change', (html) => {
  console.log('변경됨:', html.length, '자');
});

// 탭 변경 감지
editor.on('tabChange', (index) => {
  const names = ['편집', 'HTML', '미리보기'];
  console.log('탭 전환:', names[index]);
});

// 포커스 관리
editor.on('focus', () => { document.title = '편집 중...'; });
editor.on('blur',  () => { document.title = '완료'; });

5. 정적(전역) API

전역 클래스 WebEditor 또는 WebEditor에서 직접 호출합니다.

5-1. 라이선스

라이선스는 초기화 옵션 license(코드 입력)로만 적용합니다. 상태는 onLicenseValid/onLicenseInvalid 콜백으로 확인합니다(§6 참조).

new WebEditor('#editor', {
  license: 'WED2-XXXX-XXXX-...',
  onLicenseValid: (info) => { console.log(info); }
});
// localStorage 저장 방식·전역 setLicense API·팝업 키 적용은 제공하지 않습니다.

5-2. 플러그인 등록

// 전역 플러그인 등록 (이후 생성되는 모든 인스턴스에 적용)
WebEditor.registerPlugin('wordImport', WordImportPlugin);
WebEditor.registerPlugin('myPlugin',   MyCustomPlugin);

5-3. 인스턴스 접근

// ID로 인스턴스의 API 모델 획득
const model = WebEditor.getAPIModelById('editor-id');

// 인덱스로 획득 (생성 순서)
const model = WebEditor.getAPIModelByIndex(0);

// 모든 인스턴스 목록
const models = WebEditor.getAllAPIModels();

// 버전 확인
console.log(WebEditor.version);  // '2.6.0.0'

5-4. 노출 클래스

WebEditor.LicenseValidator     // 라이선스 검증 클래스
WebEditor.LicenseManager       // 라이선스 관리 클래스
WebEditor.DomainMatcher        // 도메인 매칭 유틸
WebEditor.EvaluationModal      // 평가판 안내 모달
WebEditor.LicenseI18n          // 다국어 문자열

6. 라이선스 API

6-1. 초기화 시 라이선스 적용

new WebEditor('#editor', {
  license: 'WED-XXXX-XXXX-XXXX-XXXX',
  licenseLang: 'ko',

  onLicenseValid: (info) => {
    console.log('라이선스 유효:', info.customer, info.expiry);
  },

  onLicenseInvalid: (state) => {
    // state.reason: 'unlicensed' | 'invalid' | 'expired' | 'mismatch'
    console.warn('라이선스 오류:', state.reason);
  }
});

6-2. 키 포맷

WED-{CUSTOMER}-{DOMAIN_HASH}-{EXPIRY}-{SIGNATURE}

• HMAC-SHA256 서명 기반
• 마스터 시크릿은 tools/secret.json에 보관 (.gitignore)
• 키 발급: tools/license-generator.html (사내 전용)

6-4. 도메인 매칭 규칙

7. DOM API (WebEditorAPIModel)

7-1. 모델 획득

// 방법 1: 인스턴스에서
const model = editor.getAPIModel();

// 방법 2: ID로
const model = WebEditor.getAPIModelById('my-editor');

// 방법 3: 인덱스로
const model = WebEditor.getAPIModelByIndex(0);

// 방법 4: 전체 목록
const models = WebEditor.getAllAPIModels();

7-2. 메서드 체이닝

대부분의 setter 메서드는 this를 반환하므로 체이닝이 가능합니다.

WebEditor.getAPIModelByIndex(0)
  .setReadOnly(false)
  .setHeight(600)
  .setDefaultFont('Noto Sans KR')
  .setHTML('<p>초기 내용</p>')
  .focus();

7-3. 전체 메서드 목록

// 콘텐츠 I/O
model.getHTML()               → string
model.setHTML(html)           → this
model.getText()               → string
model.appendHTML(html)        → this
model.insertHTML(html)        → this
model.getSelectedHTML()       → string
model.getSelectedText()       → string
model.clear()                 → this

// 상태 제어
model.setReadOnly(bool)       → this
model.isReadOnly()            → boolean
model.isModified()            → boolean
model.resetModified()         → this
model.setHeight(val)          → this
model.getHeight()             → number
model.setWidth(val)           → this
model.getWidth()              → number
model.setTab(index)           → this
model.getActiveTab()          → number
model.showToolbar(bool)       → this

// 이미지
model.insertImage(url)        → this
model.getImages()             → string[]

// 콘텐츠 정제
model.clearFormat()           → this
model.clearCSSFormat()        → this
model.removeTag(name)         → this

// 런타임 설정
model.setDefaultFont(name)    → this
model.setDefaultFontSize(pt)  → this
model.setContentCSS(css)      → this

// 이벤트
model.on(event, handler)      → this

// 생명주기
model.focus()                 → void
model.destroy()              → void

8. 플러그인 시스템

8-1. 플러그인 인터페이스

class MyPlugin {
  constructor(editor) {
    this.editor = editor;
  }

  /** 에디터 초기화 완료 후 호출. 툴바 버튼 등록, 이벤트 바인딩 등 수행. */
  init() {}

  /** 툴바/메뉴 명령 처리 */
  execute(command, value) {}

  /** 툴바 버튼 활성화 상태 반환 → { [command]: boolean } */
  queryState() { return {}; }

  /** 에디터 제거 시 호출. 이벤트 리스너 해제 등. */
  destroy() {}
}

8-2. 전역 등록 vs 인스턴스 등록

// 방법 1: 전역 등록 (모든 인스턴스에 적용)
WebEditor.registerPlugin('myPlugin', MyPlugin);

// 방법 2: 인스턴스별 등록
new WebEditor('#editor', {
  plugins: { myPlugin: MyPlugin }
});

8-3. 플러그인에서 에디터 API 사용

class MyPlugin {
  init() {
    const html = this.editor.getHTML();
    this.editor.insertHTML('<mark>하이라이트</mark>');

    // 선택 저장/복원 (팝업 열기 전후)
    this.editor.saveSelection();
    // ... 팝업 표시 ...
    this.editor.restoreSelection();

    this.editor.on('change', (html) => {
      console.log('변경:', html);
    });
  }
}

9. MS Word 가져오기 API

9-1. 기본 사용법

<script src="dist/webeditor.min.js"></script>
<script src="dist/plugins/wordimport-native.min.js"></script>

const editor = new WebEditor('#editor');

document.getElementById('import-btn').addEventListener('click', () => {
  const input = document.createElement('input');
  input.type = 'file';
  input.accept = '.docx';
  input.onchange = async (e) => {
    const file = e.target.files[0];
    if (file) await editor.importWordFile(file);
  };
  input.click();
});

9-2. 드래그앤드롭

const dropZone = document.getElementById('drop-zone');

dropZone.addEventListener('dragover', (e) => {
  e.preventDefault();
  dropZone.classList.add('drag-over');
});

dropZone.addEventListener('drop', async (e) => {
  e.preventDefault();
  dropZone.classList.remove('drag-over');
  const file = e.dataTransfer.files[0];
  if (file && file.name.endsWith('.docx')) {
    await editor.importWordFile(file);
  }
});

9-3. EngineRegistry (고급)

const engines = EngineRegistry.all();
const engine  = EngineRegistry.best();
const native  = EngineRegistry.byName('native');
EngineRegistry.register('custom', MyEngine, { priority: 30 });

9-4. 지원 변환 항목

9-A. 한글 HWPX 가져오기 API v2.6.0.0 보강

9-A-1. 기본 사용법

<script src="dist/webeditor.min.js"></script>
<script src="dist/plugins/hwpximport-native.min.js"></script>

const editor = new WebEditor('#editor', {
  plugins: ['format', 'table', 'link', 'hwpximport']
});

document.getElementById('import-btn').addEventListener('click', () => {
  const input = document.createElement('input');
  input.type = 'file';
  input.accept = '.hwpx';
  input.onchange = async (e) => {
    const file = e.target.files[0];
    if (file) await editor.importHwpxFile(file, { mode: 'replace', maxTableWidth: 740 });
  };
  input.click();
});

9-A-2. 드래그앤드롭

const dropZone = document.getElementById('drop-zone');

dropZone.addEventListener('drop', async (e) => {
  e.preventDefault();
  const file = e.dataTransfer.files[0];
  if (file && file.name.endsWith('.hwpx')) {
    await editor.importHwpxFile(file);
  }
});

9-A-3. importHwpxFile 옵션

9-A-4. 지원 변환 항목 (OWPML → HTML)

9-A-5. 제한 사항

• 미지원: 수식, SmartArt·복합 그리기 그룹의 정밀 레이아웃, 머리글/꼬리글, 각주·미주 본문, 텍스트 감싸기(도형 주변 흐름), 도형 회전.
• 글머리·번호 목록과 하이퍼링크는 텍스트로 보존됩니다(리스트/링크 구조는 미반영).
• 벡터 도형은 정점 기반 근사이며, 채움/선이 없으면 기본 회색으로 가시화합니다(원본 색과 다를 수 있음). 곡선(curve)은 제어점 없이 정점만 연결.
• 구 바이너리 .hwp 파일은 지원하지 않습니다(.hwpx(OWPML) 표준 포맷만 대상). 미지원 요소는 텍스트 보존 + 경고로 처리됩니다.

9-B. 마크다운 문서 뷰어/편집 API

9-B-1. 기본 사용법

<script src="dist/webeditor.min.js"></script>
<script src="dist/plugins/markdown-native.min.js"></script>

const editor = new WebEditor('#editor', {
  plugins: ['format', 'image', 'table', 'link', 'markdown']
});

9-B-2. 공개 API

9-B-3. 예제

// 마크다운 → 본문
editor.setMarkdown('# 제목\n\n**굵게** 와 [링크](https://example.com)\n\n- 항목');
editor.setMarkdown(md, { mode: 'append', baseUrl: '/docs/' });

// 본문 → 마크다운 (왕복)
const md = editor.getMarkdown();

// 삽입 없이 안전 HTML만 렌더 (뷰어용)
const { html, warnings } = editor.viewMarkdown(mdText);
previewEl.innerHTML = html;

// .md 파일 가져오기
input.onchange = (e) => editor.importMarkdownFile(e.target.files[0], { mode: 'cursor' });

9-B-4. 옵션

9-B-5. 지원 문법 (GFM)

9-B-6. 보안

9-B-7. 독립 뷰어 데모

10. MenuBar API

에디터 초기화 시 자동 생성되며 src/menubar.js에서 관리됩니다.

10-1. 메뉴 구조

파일   > MS Word 가져오기 / 한글 HWPX 가져오기
편집   > 실행 취소 / 다시 실행 / 복사 / 자르기 / 붙여넣기
보기   > 편집 보기 / HTML 보기 / 미리보기
삽입   > 이미지 / 동영상 / 링크 / 표
서식   > 굵게 / 이탤릭 / 밑줄 / 취소선 / 글자색 / 배경색 / 서식 지우기
도구   > (추후 확장)
도움말 > 에디터 정보 (About)

10-2. About 다이얼로그 표시

// 프로그래밍 방식으로 표시
editor._menubar.showAboutDialog();

표시 정보: 로고, 제품명, 버전, 라이선스 키(앞 8자리), 적용 도메인, 만료일 및 유형

10-3. 커스텀 메뉴 구성 (menubar config)

options.menubar에 배열을 넘기면 그 구성대로 메뉴바가 만들어집니다. 배열은 menubar-config.html 설정 페이지에서 시각적으로 구성해 webeditor-menubar-config.js로 다운로드할 수 있습니다.

window.DEEDITOR_MENUBAR_CONFIG = [
  {
    label: '파일',
    items: [
      { label: '새 문서', cmd: 'newDocument', icon: 'icon-file-new', shortcut: 'Ctrl+N' },
      { sep: true },                              // 구분선
      { label: '저장', cmd: 'save', icon: 'icon-save', shortcut: 'Ctrl+S' }
    ]
  }
  // … 편집 / 보기 / 사용자 정의 메뉴
];

new WebEditor('#editor', { menubar: window.DEEDITOR_MENUBAR_CONFIG });

11. TypeScript 타입 정의

dist/webeditor.d.ts에서 전체 타입을 참조할 수 있습니다.

interface WebEditorOptions {
  height?: string | number;
  placeholder?: string;
  defaultFont?: string;
  defaultFontSize?: number;
  defaultLineHeight?: string | number;
  contentCSS?: string;
  readOnly?: boolean;
  autofocus?: boolean;
  enterKey?: 'p' | 'br';
  undoGranularity?: 'char' | 'group';
  documentBackground?: { mode?: 'auto' | 'base64' | 'upload'; inlineThreshold?: number; store?: 'auto' | 'wrapper' | 'meta'; onTooLargeWithoutUploader?: 'fallback' | 'block' };
  uiTemplate?: 'classic' | 'ribbon';
  iconTheme?: string;
  iconThemePath?: string;
  maxImageWidth?: number;
  pastePlainText?: boolean;
  showTableGuide?: boolean;
  logoUrl?: string;
  license?: string;
  licenseLang?: 'ko' | 'en' | null;
  uploadHandler?: (file: File, headers?: Record<string, string>) => Promise<string>;
  plugins?: string[] | Record<string, PluginClass>;
  menubar?: boolean | MenuBarGroup[];
  onInit?: (editor: WebEditor) => void;
  onKeyDown?: (e: KeyboardEvent) => boolean | void;
  onKeyUp?: (e: KeyboardEvent) => void;
  onBeforeCommand?: (cmd: string) => boolean | void;
  onTabChange?: (index: number) => boolean | void;
  onMenuCommand?: (cmd: string, editor: WebEditor, item: any) => boolean | void;
  onLicenseValid?: (info: LicenseInfo) => void;
  onLicenseInvalid?: (state: LicenseState) => void;
  // v2.4.0
  autoSave?: { interval?: number; storageKey?: string; unloadWarning?: boolean; unloadMessage?: string; onSave?: (html: string) => boolean | void } | null;
  inlineToolbar?: boolean | string[];
  hyperLinkDefaultTarget?: '_self' | '_blank' | '_top' | '_parent';
  privacy?: { detect?: string[]; onDetect?: (m: any[]) => void } | null;
  profanity?: { words?: string[] | string; onDetect?: (m: any[]) => void; maskChar?: string } | null;
  uploadHeaders?: Record<string, string> | null;
  csrfCookie?: string | null;
  evaluationWatermark?: boolean;
}

interface LicenseInfo {
  valid: boolean;
  domains: string[];
  expiry: number;  // UNIX timestamp (0 = 영구)
  type: 'perm' | 'year' | 'trial30' | 'trial180' | 'custom';
  customer: string | null;
}

interface DocumentBackground {
  image: string | null;   // data URL 또는 업로드 URL
  color: string;          // ''=색 없음
  repeat: 'no-repeat' | 'repeat-x' | 'repeat-y' | 'repeat';
  attachment: 'scroll' | 'fixed';
  mode: 'base64' | 'upload' | null;  // 실제 적용된 이미지 처리
  store: 'wrapper' | 'meta';      // 배경 보존 위치
}

declare class WebEditor {
  static version: string;
  static registerPlugin(name: string, plugin: PluginClass): void;
  static getAPIModelById(id: string): WebEditor | null;
  static getAPIModelByIndex(index: number): WebEditor | null;
  static getAllAPIModels(): WebEditor[];

  constructor(selector: string | Element, options?: WebEditorOptions);

  getHTML(): string;
  setHTML(html: string): this;
  getText(): string;
  appendHTML(html: string): this;
  insertHTML(html: string): this;
  getSelectedHTML(): string;
  getSelectedText(): string;
  clear(): this;
  setReadOnly(readonly: boolean): this;
  isReadOnly(): boolean;
  isModified(): boolean;
  resetModified(): this;
  setHeight(height: number | string): this;
  getHeight(): number;
  setWidth(width: number | string): this;
  getWidth(): number;
  setTab(n: 0 | 1 | 2 | 'edit' | 'html' | 'preview'): this;
  getActiveTab(asName?: boolean): 0 | 1 | 2 | 'edit' | 'html' | 'preview';
  showToolbar(visible: boolean): this;
  insertImage(url: string): this;
  getImages(): string[];
  clearFormat(): this;
  clearCSSFormat(): this;
  removeTag(tagName: string): this;
  setDefaultFont(name: string): this;
  setDefaultFontSize(size: number): this;
  setDefaultLineHeight(lh: string | number): this;
  setEditorDefaults(opts: { font?: string; fontSize?: number; lineHeight?: string | number }): this;
  getEditorDefaults(): { font: string; fontSize: number | null; lineHeight: string };
  setDocumentBackground(opts: { image?: File | Blob | string | null; color?: string; repeat?: 'no-repeat' | 'repeat-x' | 'repeat-y' | 'repeat'; attachment?: 'scroll' | 'fixed' }): Promise<DocumentBackground>;
  removeDocumentBackground(): this;
  getDocumentBackground(): DocumentBackground | null;
  showMenuBar(bool: boolean): this;
  toggleToolbar(): this;   // Ctrl+[
  toggleMenuBar(): this;   // Ctrl+]
  setUITemplate(name: 'classic' | 'ribbon'): this;
  getUITemplate(): 'classic' | 'ribbon';
  setIconTheme(name: string): this;
  getIconTheme(): string;
  setTableBorderColor(color: string): this;
  getTableBorderColor(): string;
  setContentCSS(css: string): this;
  importWordFile(file: File): Promise<void>;
  importHwpxFile(file: File, options?: { mode?: 'cursor'|'append'|'replace'; silent?: boolean; maxTableWidth?: number; showLog?: boolean }): Promise<void>;
  pasteFromClipboard(): Promise<boolean>;
  // v2.4.0 신규
  isEmpty(): boolean;
  getSafeHTML(options?: { stripScript?: boolean; allowedTags?: string[]; allowedAttrs?: string[]; imageRewriter?: (src: string) => string }): string;
  getAutoSaved(): string | null;
  clearAutoSaved(): this;
  saveNow(): this;
  saveToPDF(options?: { title?: string; hideToolbar?: boolean; css?: string }): void;
  saveToPDFInWindow(options?: { title?: string; css?: string }): void;
  setZoom(ratio: number): this;
  getZoom(): number;
  validate(): Promise<{ profanity: any[]; privacy: any[] }>;
  maskSensitiveData(): Promise<number>;
  reviewSensitiveData(): Promise<number>;
  showMenuBar(bool: boolean): void;
  setFullscreen(bool: boolean): void;
  on(event: 'change', handler: (html: string) => void): this;
  on(event: 'tabChange', handler: (index: number) => void): this;
  on(event: 'focus' | 'blur' | 'selectionchange', handler: () => void): this;
  on(event: 'imageInserted' | 'imageUploaded', handler: (d: { src: string; file: File | null; node: HTMLImageElement }) => void): this;
  on(event: 'zoom', handler: (d: { ratio: number }) => void): this;
  on(event: 'error', handler: (d: { context: string; error: Error }) => void): this;
  off(event?: string, handler?: Function): this;
  focus(): void;
  destroy(): void;
}

12. 콜백 옵션 레퍼런스

onInit(editor)

에디터 초기화 완료 후 1회 호출됩니다.

onInit: (editor) => {
  editor.setHTML(savedContent);
  editor.resetModified();
}

onKeyDown(e) → boolean | void

키다운 이벤트 발생 시 호출. return false 시 기본 동작을 차단합니다.

onKeyDown: (e) => {
  if (e.key === 'Tab') {
    return false;  // Tab 키 차단
  }
}

onBeforeCommand(command) → boolean | void

에디터 내부 커맨드 실행 직전 호출. return false 시 커맨드를 차단합니다.

onBeforeCommand: (cmd) => {
  if (cmd === 'insertTable') {
    return false;  // 표 삽입 차단
  }
}

onTabChange(index) → boolean | void

탭 전환 직전 호출. return false 시 전환을 취소합니다.

onTabChange: (index) => {
  if (index === 1 && !userIsAdmin) {
    alert('HTML 편집 권한이 없습니다.');
    return false;
  }
}

uploadHandler(file) → Promise<string>

이미지 서버 업로드 처리. string URL을 반환해야 합니다.

uploadHandler: async (file) => {
  if (file.size > 10 * 1024 * 1024) {
    throw new Error('파일 크기는 10MB 이하여야 합니다.');
  }
  const form = new FormData();
  form.append('upload', file);
  const res = await fetch('/api/file/upload', {
    method: 'POST',
    headers: { 'X-CSRF-Token': getCSRFToken() },
    body: form
  });
  if (!res.ok) throw new Error('업로드 실패');
  const { url } = await res.json();
  return url;
}

13. 크로스브라우저 이슈 및 해결책

14. 게시판 예제

게시판 글쓰기 페이지

<!DOCTYPE html>
<html lang="ko">
<head>
  <link rel="stylesheet" href="/dist/webeditor.min.css">
</head>
<body>
  <form id="post-form">
    <input type="text" name="title" placeholder="제목">
    <div id="editor"></div>
    <input type="hidden" name="content" id="content-field">
    <button type="submit">등록</button>
  </form>

  <script src="/dist/webeditor.min.js"></script>
  <script src="/dist/plugins/wordimport-native.min.js"></script>
  <script>
    const editor = new WebEditor('#editor', {
      height: '500px',
      defaultFont: 'Malgun Gothic',
      defaultFontSize: 14,
      showTableGuide: true,
      license: 'WED-XXXX-XXXX-...',

      uploadHandler: async (file) => {
        const form = new FormData();
        form.append('file', file);
        const res = await fetch('/api/upload', { method: 'POST', body: form });
        return (await res.json()).url;
      },

      onInit: (ed) => {
        const existing = document.getElementById('existing-content');
        if (existing) { ed.setHTML(existing.innerHTML); ed.resetModified(); }
      }
    });

    document.getElementById('post-form').addEventListener('submit', (e) => {
      document.getElementById('content-field').value = editor.getHTML();
    });

    window.addEventListener('beforeunload', (e) => {
      if (editor.isModified()) e.preventDefault();
    });
  </script>
</body>
</html>

게시판 파일 첨부 · 문서 미리보기 (데모 패턴)

게시글 작성 화면(에디터 하단)에 파일 첨부(드래그앤드롭·다중)를 붙이고, 첨부한 .docx·.hwpx·.md 는 메뉴바·아이콘바 없는 에디터 새창으로 열어 미리보는 패턴입니다. 데모(demo/write.html·demo/view.html·demo/doc-preview.html)에서 사용합니다.

// 1) 첨부파일: 파일을 data URL(base64)로 읽어 게시글과 함께 저장
const reader = new FileReader();
reader.onload = e => attachments.push({ name: file.name, size: file.size, type: file.type, data: e.target.result });
reader.readAsDataURL(file);
// 저장: localStorage.setItem(KEY, JSON.stringify({ ...post, attachments }))

// 2) 미리보기 창(doc-preview.html) — 메뉴바·아이콘바 없는 에디터
const editor = new WebEditor('#pv-editor', {
  menubar: false,                                  // 드롭다운 메뉴바 없음
  plugins: ['format','image','table','link','wordimport','hwpximport','markdown'],
});
editor.showToolbar(false);                          // 아이콘(툴바) 숨김
editor.setHeight(window.innerHeight - 46);          // 고정 높이 + 내부 스크롤 (필수)

// 3) data URL → File 복원 후 형식별 import → 완료 후 읽기 전용으로 잠금
const blob = await (await fetch(dataUrl)).blob();
const file = new File([blob], name, { type: mime });
if (/\.hwpx$/i.test(name))          await editor.importHwpxFile(file, { silent: true, mode: 'replace' });
else if (/\.(md|markdown)$/i.test(name)) await editor.importMarkdownFile(file, { mode: 'replace' });
else                              await editor.importWordFile(file, { silent: true, mode: 'replace' });

editor.setReadOnly(true);   // 편집·상단 메뉴바·표/이미지 컨텍스트 메뉴·리사이즈 모두 차단 (v2.6.0.0)

// 4) 부모 → 미리보기 창 데이터 전달: 동일 출처 postMessage 핸드셰이크
// 미리보기는 기본 너비 1000px 팝업(새 창)으로 연다
const w = window.open('doc-preview.html', '_blank', 'width=1000,height=860,resizable=yes,scrollbars=yes');
window.addEventListener('message', e => {
  if (e.source === w && e.data.type === 'docPreviewReady')
    w.postMessage({ type: 'docPreviewFile', name, mime, dataUrl }, location.origin);
});

미리보기 창(doc-preview.html) 내부 구현

미리보기 창은 부모 창에 준비(ready) 신호를 보내고, 부모가 전달한 파일 데이터를 받아 위 2·3단계(에디터 생성 → import → setReadOnly(true))를 수행합니다. 편집이 목적이 아니므로 하단 '편집/HTML/미리보기' 탭바를 만드는 sourceview 플러그인은 제외합니다.

// doc-preview.html — 미리보기 전용 창(자식)
// (1) 로드되면 부모(opener)에 준비 신호 전송
if (window.opener)
  window.opener.postMessage({ type: 'docPreviewReady' }, location.origin);

// (2) 부모가 보낸 파일 데이터 수신 — 동일 출처 + opener 검증
window.addEventListener('message', async e => {
  if (e.origin !== location.origin) return;              // 동일 출처만 허용
  if (window.opener && e.source !== window.opener) return;
  if (!e.data || e.data.type !== 'docPreviewFile') return;

  const { name, mime, dataUrl } = e.data;
  // 뷰어 에디터 생성 — 메뉴바·툴바 없음, sourceview(탭바) 제외
  const ed = new WebEditor('#pv-editor', {
    menubar: false,
    plugins: ['format','image','table','link','wordimport','hwpximport','markdown'],
  });
  ed.showToolbar(false);
  ed.setHeight(window.innerHeight - 46);

  const blob = await (await fetch(dataUrl)).blob();
  const file = new File([blob], name, { type: mime });
  if (/\.hwpx$/i.test(name))          await ed.importHwpxFile(file, { silent: true, mode: 'replace', maxTableWidth: 960 });
  else if (/\.(md|markdown)$/i.test(name)) await ed.importMarkdownFile(file, { mode: 'replace' });
  else                              await ed.importWordFile(file, { silent: true, mode: 'replace' });

  ed.setReadOnly(true);   // 편집 완전 차단(뷰어)
});

다중 인스턴스

// 라이선스는 각 인스턴스 초기화 옵션 license로 적용
const editor1 = new WebEditor('#editor-1', { height: '300px', license: 'WED2-...' });
const editor2 = new WebEditor('#editor-2', { height: '300px', readOnly: true, license: 'WED2-...' });

// 첫 번째 에디터 내용을 두 번째로 복사
const html = WebEditor.getAPIModelByIndex(0).getHTML();
WebEditor.getAPIModelByIndex(1).setHTML(html);

부록 — 단축키 목록

부록 — 파일 구조

dist/
├── webeditor.js              UMD 개발용 번들
├── webeditor.min.js          UMD 운영용 번들 ⭐
├── webeditor.esm.js          ES Module 번들
├── webeditor.css             스타일시트
├── webeditor.min.css         스타일시트 (최소화) ⭐
├── webeditor.d.ts            TypeScript 타입 정의
└── plugins/
    ├── wordimport-native.js       Word 가져오기 플러그인
    ├── wordimport-native.min.js   최소화 버전 ⭐
    ├── hwpximport-native.js       한글 HWPX 가져오기 플러그인
    └── hwpximport-native.min.js   최소화 버전 ⭐

src/
├── editor.js                 에디터 코어 + DOM 생성
├── editor.css                전체 스타일
├── toolbar.js                툴바 렌더링
├── menubar.js                드롭다운 메뉴바
├── license/                  라이선스 시스템
│   ├── domain-matcher.js
│   ├── validator.js
│   ├── i18n.js
│   ├── evaluation-modal.js
│   └── manager.js
└── plugins/
    ├── format.js             Bold/Italic/Underline/색상/크기
    ├── image.js              이미지 삽입/업로드
    ├── table.js              표 생성/편집/리사이즈/멀티셀
    ├── link.js               하이퍼링크
    ├── video.js              YouTube Lite Embed
    ├── wordimport/
    │   ├── index.js          WordImportPlugin 진입점
    │   ├── core/
    │   │   └── DocxReader.js ZIP 파싱
    │   ├── engines/
    │   │   ├── EngineRegistry.js
    │   │   └── NativeEngine.js  OOXML → HTML
    │   └── ui/
    │       ├── ImportDialog.js
    │       └── ProgressDialog.js
    └── hwpximport/           한글 HWPX 가져오기
        ├── index.js          HwpxImportPlugin 진입점
        ├── core/
        │   └── ZipReader.js  HWPX(ZIP) 파싱
        └── engines/
            └── OwpmlEngine.js  OWPML → HTML

© 2024-2026 DEXTSOLUTION Inc. All Rights Reserved.