CKEditor5 기본 문법 정리

[ CKEditor5 기본 문법 정리 ]

커스텀 빌드를 생성할 때 알아두면 좋은

기본 문법들과 플러그인 요소들을 정리해보았다.

 

1. CKEditor5 기본 문법

1-1. HTML / JSP 기본 구조

<textarea id="editor" name="content"></textarea>

• textarea 또는 div 요소를 대상으로 에디터가 생성된다
• name 속성은 서버로 전송될 파라미터 이름이 된다

1-2. 에디터 생성 기본 문법

ClassicEditor.create(document.querySelector('#editor'))
    .then(editor => {
        console.log('에디터 생성 완료');
    })
    .catch(error => {
        console.error(error);
    });

• ClassicEditor는 가장 일반적인 문서형 에디터
• create()는 Promise 기반으로 동작한다

1-3. 설정 객체를 포함한 생성 문법

ClassicEditor.create(document.querySelector('#editor'), {
    language: 'en',
    toolbar: {
        items: ['bold', 'italic', 'link']
    }
});

• 두 번째 인자는 에디터 설정 객체
• 툴바, 업로드, 언어 설정 등이 여기서 주입된다

---

2. 이미지 업로드 기본 문법 (SimpleUploadAdapter)

2-1. JSP에서의 업로드 설정

ClassicEditor.create(document.querySelector('#editor'), {
    simpleUpload: {
        uploadUrl: '<%=request.getContextPath()%>/uploadImage.do'
    }
});

이 설정은 다음 역할만 한다.

• 업로드 기능을 “추가”하지 않는다
• 커스텀 빌드에 포함된 SimpleUploadAdapter에게
  업로드 요청 URL을 알려준다

즉,
→ 어댑터는 빌드 단계에서 포함되고
→ URL 설정은 JSP에서 이루어진다

 

2-2. 서버 응답 형식 (중요)

서버는 반드시 아래 JSON 형식으로 응답해야 한다.

{
  "url": "/upload/editor/sample.png"
}

이 형식이 맞지 않으면

• 파일은 서버에 저장되지만
• 에디터에 이미지가 표시되지 않는다

---

3. 커스텀 빌드에서 자주 사용하는 유용한 플러그인

3-1. 기본 문서 편집 플러그인 (필수)

플러그인	설명
Essentials	undo / redo 등 기본 기능
Heading	제목(h1~h6)
Bold / Italic	텍스트 스타일
BlockQuote	인용문
List	번호 / 불릿 리스트
Link	링크 삽입

3-2. 이미지 업로드 & 표시 관련 플러그인 (실무 핵심)

이미지 기능은 플러그인 조합이 매우 중요하다.

플러그인	역할
Image	이미지 기능의 기본
ImageUpload	이미지 업로드 버튼
ImageToolbar	이미지 클릭 시 툴바
ImageStyle	이미지 정렬
ImageCaption	이미지 설명

※ 이미지 업로드 필수 조합

Image
+ ImageUpload
+ UploadAdapter(SimpleUploadAdapter)

 

3-3. 이미지 크기 조절 (Resize)

기본 빌드에는 이미지 크기 조절 기능이 없다.
커스텀 빌드에서 아래 플러그인을 추가해야 한다.

import ImageResize from
'@ckeditor/ckeditor5-image/src/imageresize';

 

기능 특징

• 이미지 선택 후 드래그로 크기 조절
• 퍼센트 기반 리사이즈
• 반응형 레이아웃에 유리

→ 게시판 / CMS 환경에서는 사실상 필수 기능이다.

 

3-4. 이미지 정렬 및 레이아웃 제어

image: {
    toolbar: [
        'imageStyle:full',
        'imageStyle:side',
        '|',
        'imageTextAlternative'
    ]
}

• 본문 가득(full)
• 좌우 배치(side)
• 문서 흐름 제어 가능

3-5. 이미지 대체 텍스트 (접근성)

'imageTextAlternative'

 

• 시각 장애인 접근성 지원
• SEO에 긍정적 영향
• 공공·관리자 페이지에서 요구되는 경우 많음

3-6. 미디어 및 문서 확장 플러그인

1) MediaEmbed

• 유튜브, 영상 URL 자동 임베드
• 콘텐츠형 게시판에 유용

2) Table / TableToolbar

• 테이블 작성
• 행/열 추가 및 병합
• 관리자 페이지, 공지 작성에 적합

3) PasteFromOffice

• Word / 한글 문서 복붙 시 스타일 정리
• 실무에서 체감도가 매우 높음

---

4. 왜 커스텀 빌드가 필요한가?

프로젝트마다 다음 요소는 모두 다르다.

• 이미지 저장 위치
• 파일명 규칙
• 접근 권한
• 서버 응답 JSON 구조

이미지 업로드는 단순한 UI 기능이 아니라
서버 비즈니스 로직과 강하게 결합된 기능이기 때문에

 

업로드 URL, 저장 방식, 응답 형식을

직접 제어할 수 있는 커스텀 빌드 방식이 필요하다.

---

5. 추천 플러그인 세트

일반적인 게시판 / CMS / 관리자 페이지용

Essentials
+ Heading
+ Bold / Italic
+ List / Link
+ Image
+ ImageUpload
+ ImageToolbar
+ ImageStyle
+ ImageResize
+ ImageCaption
+ SimpleUploadAdapter
+ Table / TableToolbar
+ PasteFromOffice
+ MediaEmbed

각 플러그인의 역할과 사용 이유는 다음과 같다.

 

① Essentials

에디터의 기본 동작을 담당하는 필수 플러그인

• undo / redo
• 선택, 포커스, 키보드 동작 등
• 에디터의 최소 동작 단위

② Heading

문서 구조를 만드는 플러그인

• 제목(h1 ~ h6) 제공
• 문단을 의미 단위로 구분

③ Bold / Italic

텍스트 강조를 위한 기본 스타일 플러그인

• 굵게 / 기울임
• 가장 자주 사용되는 서식

④ List / Link

정보 정리와 연결을 담당하는 플러그인

• 번호 / 불릿 리스트
• 외부 링크 삽입

⑤ Image

이미지 기능의 기본 뼈대

• 이미지 요소 자체를 처리
• 다른 이미지 플러그인의 기반

⑥ ImageUpload

이미지 업로드 버튼을 활성화하는 플러그인

• 툴바에 이미지 업로드 버튼 제공
• 업로드 흐름의 시작점

⑦ ImageToolbar

이미지 선택 시 편집 툴바 제공

• 이미지 클릭 시 옵션 표시
• 스타일, 대체 텍스트, 크기 조절 접근점

⑧ ImageStyle

이미지 정렬 및 레이아웃 제어

• 본문 전체(full)
• 좌/우 배치(side)

⑨ ImageResize

이미지 크기 조절 기능

• 드래그 기반 리사이즈
• 퍼센트 단위 크기 조절

⑩ ImageCaption

이미지 설명(캡션) 기능

• 이미지 하단 설명 텍스트
• 콘텐츠 전달력 향상

⑪ SimpleUploadAdapter

서버 직접 업로드를 담당하는 핵심 플러그인

• multipart/form-data 방식 업로드
• JSP / Servlet 환경과 잘 맞음
• 서버 응답 { "url": "경로" } 기반

⑫ Table / TableToolbar

테이블 작성 및 편집 기능

• 행/열 추가
• 셀 병합
• 테이블 전용 툴바

⑬ PasteFromOffice

문서 복사/붙여넣기 안정화 플러그인

• Word / 한글 문서 복붙 시
• 불필요한 스타일 제거

⑭ MediaEmbed

외부 미디어 자동 임베드

• 유튜브 URL 붙여넣기
• iframe 자동 변환