[React] - React에 ‘CKEditor5’ 적용하기(예제코드 포함, CKEditor5 흰색 화면오류 해결, CKEditor5 커스텀 파일 적용 방법, base64 이미지 적용)

💁🏻‍♂️ 소개

CKEditor5는 텍스트 편집기(블로그 에디터) 라이브러리이다.

텍스트 에디터 중에서도 공식 문서가 잘 정리되어 있어 많이 사용되고 있다.

 

⚒️ CKEditor 5 종류

종류는 Classic 부터 ~ Super까지 존재한다.

각 빌드 종류에 따라 지원하는 기능들이 다르다.(빌드 별 지원기능)

 

 

무료 버전은 아래와 같다.

 

 

👉🏻 적용 방법 (3가지)

공식 페이지에서 버전을 선택한 후 적용 방법(3가지)을 선택하여 적용할 수 있다.

Zip package 방법은 직접 커스텀하여(플러그인 등) 만들 수도 있다.(진행 방법 하단에 작성)

1. Command line
2. CDN
3. * Zip package

🧑🏻‍💻 Zip package 방법 적용(커스텀 방식)

1. 공식 빌드 커스텀 페이지 접속 (https://ckeditor.com/ckeditor-5/online-builder/)
2. 에디터 타입(디자인) 선택

 

3. 사용할 플러그인 선택 → (우측 상단) [Next step] 클릭

• (중요) React(Next.js)에서 사용 시 [Watchdog] plug in은 선택 X.
  • (공식문서 해석) React 통합에는 워치독 기능이 이미 코어에 통합되어 있습니다.

• 이후 [(⭐️ PREMIUM) 유료] 표시가 없는 원하는 플러그인들을 선택.
• 만일 유료기능 1개 이상 선택 시 30일만 사용 가능
• (브라우저 번역 사용) 한글 번역 시 플러그인 ‘[추가] 버튼’ 미동작 ([제거] 버튼은 동작).
• (중요) 기본적으로 BASE 64 어뎁터 선택 불가. 따라서 file manager 역할을 하는 (유료) CK BOX를 제거해야 ‘선택 가능’으로 변경된다.

 

4. 툴바 커스텀 → (우측 상단) [Next step] 클릭

• Available toolbar items 영역 : 사용 가능한 플러그인 목록
  • 추가 : 클릭(툴바로 이동)
  • 클릭(추가) 하지 않은 플러그인 목록들은 추후 추가가 가능.
• Picked toolbar items 영역 : 에디터에서 사용할 플러그인 들을 사용자가 직접 커스텀하여 배치하는 영역
  • 위치 조정 : 플러그인 아이콘 ‘드래그’
  • 삭제 : 플러그인 아이콘 ‘클릭’
  • 추후 코드 수정으로 ‘세로선 추가’, ‘삭제’, ‘추가’, ‘위치 조정’ 등이 가능
  • 단 Available toolbar items 영역에 없는 플러그인은 코드로도 추가 불가.

 

 

(커스텀 완료 결과)

 

5. 언어 선택 → (우측 상단) [Next step] 클릭

 

6. [Start] 클릭 → (파일 생성 완료 후) → [Downlad your custom CKEditor 5 build] 클릭하여 다운

 

 

 

7. 다운받은 파일 압축 해제 후 ckeditor5로 이름 변경

• 이름변경 필수 X

 

8. VS Code 실행 → 리액트 프로젝트 열기 → 압축 폴더 리액트 프로젝트로 이동

• React 프로젝트 내에서 다음과 같이 src 폴더와 같은 선상에 ckeditor5 폴더를 이동

 

9. React용 ckeditor 구성 요소를 설치 및 추가

• 아래 명령어를 순차적으로 실행한다.

npm install @ckeditor/ckeditor5-build-classic
npm install @ckeditor/ckeditor5-react
npm add file:./ckeditor5

 

 

 

10. TextEditor.js 파일 생성 후 작성(CKEditor 구성요소 초기화)

• 이 파일에서 ckeditor 구성 요소를 가져온다.
• 먼저 사용할 아이템(plugins)들을 가져오는 코드 작성. (🧑🏻‍💻 예제코드)

// <path-to-your-build>/src/ckeditor.ts or file containing editor configuration if you are integrating an editor from source.

// The editor creator to use.
import  Editor  from 'ckeditor5-custom-build/build/ckeditor';
import { CKEditor } from '@ckeditor/ckeditor5-react';


const TextEditor = ({setData}) => {
    const edrtorConfiguration = {
		toolbar: {
			items: [
				'heading',
				'|',
				'bold',
				'italic',
				'link',
				'bulletedList',
				'numberedList',
				'|',
				'outdent',
				'indent',
				'imageUpload',
				'blockQuote',
				'|',
				'insertTable',
				'mediaEmbed',
				'undo',
				'redo',
				'alignment',
				'codeBlock',
				'code',
				'findAndReplace',
				'fontBackgroundColor',
				'fontColor',
				'fontSize',
				'fontFamily',
				'highlight',
				'horizontalLine',
				'htmlEmbed',
				'imageInsert',
				'pageBreak',
				'selectAll',
				'removeFormat',
				'sourceEditing',
				'specialCharacters',
				'strikethrough',
				'restrictedEditingException',
				'subscript',
				'style',
				'superscript',
				'textPartLanguage',
				'todoList',
				'underline'
			]
		},
		language: 'ko',
		image: {
			toolbar: [
				'imageTextAlternative',
				'toggleImageCaption',
				'imageStyle:inline',
				'imageStyle:block',
				'imageStyle:side',
				'linkImage'
			]
		},
		table: {
			contentToolbar: [
				'tableColumn',
				'tableRow',
				'mergeTableCells',
				'tableCellProperties',
				'tableProperties'
			]
		}
    };

    return (
        <CKEditor 
        editor={Editor}
        config={edrtorConfiguration}
        data = "<p> 이곳에 내용을 작성해 주세요!</p>"
        onChange={(event, editor) => {
            setData(editor.getData()); // 에디터 작성 내용 저장 
        }}
        />
    )
}

export default TextEditor;

• 이후 ckeditor.ts 파일 속 toolbar {} 코드를 TextEditor.js파일 속 toolbar {} 코드로 변경
  • ckeditor5 → src → ckeditor.ts 속 toolbar 코드 복붙

툴바 명령어 코드 확인 방법(2가지) (더 보기 참고)

툴바 명령어 코드 확인 방법(2가지)

1. 공식문서에서 확인하기 

2. 커스텀 툴바에서 마우스 커서로 확인 후 코드에 카멜케이스 형식으로 입력하여 수정

(번외) 아이템 명령어 코드 삭제 (전, 후) 비교 결과 (더 보기 참고)

(번외) 아이템 명령어 코드 삭제 (전, 후) 비교 결과

1. 이미지, 테이블 플러그인 주석 처리하기

2. 주석 처리 결과 (전, 후)

 

11. 마지막으로 App.js 파일로 TextEditor 구성 요소를 가져오기 → npm start 명령어 실행.

import React from "react";
import TextEditor from "./components/TextEditor";
import { useState } from "react";

const App = () => {
  // 에디터 속 내용을 담을 변수
  const [data, setData] = useState("");

  return (
    <>
      <TextEditor setData={setData} />

      <div style={{ display: "flex" }}>
        <div className="ck ck-editor__main" 
        style={{ width : "100%"}}>
          <div
            className="ck ck-content ck-editor__editable ck-rounded-corners ck-editor__editable_inline ck-blurred"
            dangerouslySetInnerHTML={{ __html: data }} // 결과 확인 
          />
        </div>
      </div>
    </>
  );
};

export default App;

 

 

👀 결과

정상적으로 동작하는 것을 확인할 수 있다.

Base 64 또한 동작이 잘 되는 것을 확인

 

 

 

💁🏻‍♂️ 커스텀 파일 수정 후 적용 방법

• 기존 커스텀 파일(ckeditor5)를 수정한(새로만든) 커스텀 파일로 수정하여 적용하는 과정
  1. 커스텀 후 zip 파일 다운로드
  2. 폴더 이름 변경 → ckeditor5
  3. 프로젝트 상단(src, public과 같은 위치)에 (기존) ckeditor5 삭제 후 새로 다운로드 한 파일 넣기
  4. vs code 열기 → 터미널 열기 → npm add file:./ckeditor5 명령어 실행
  5. ckeditor5 → src → ckeditor.ts 속 toolbar 코드 복사
  6. ckeditor.ts 파일 속 toolbar {} 코드를 TextEditor.js파일 속 toolbar {} 코드로 변경
  7. npm start 실행