React에서 SunEditor 사용하기

Install

해당 구성 요소에는 SunEditor 엔진도 필요합니다(피어 종속성, 3.4.1 이상).

npm install suneditor @suneditor/suneditor-react

Usage

import SunEditor from '@suneditor/suneditor-react';
import 'suneditor/css/editor';
import 'suneditor/css/contents';

export default function App() {
  return (
    <SunEditor
      options={(se) => ({
        plugins: [se.plugins.link, se.plugins.image, se.plugins.table],
        buttonList: [
          ['undo', 'redo'],
          ['bold', 'italic', 'underline'],
          ['table', 'link', 'image'],
        ],
        height: '400px',
      })}
    />
  );
}

options은 suneditor.create()에 그대로 전달되므로 모든 옵션, 플러그인, 버튼, 이벤트 및 언어는 엔진 자체의 것입니다.
이 README 파일은 React 컴포넌트가 추가하는 내용만 다룹니다. 옵션 자체에 대한 자세한 내용은 SunEditor 문서 또는 suneditor 패키지를 참조하십시오.

options는 지연 로드되는 suneditor 모듈(se.plugins, se.langs, se.interfaces, ...)을 받습니다.
Next.js에서 이 형식을 선호합니다. 클라이언트 구성 요소에서 suneditor을 정적으로 가져오면 엔진이 가져올 때 window을 건드리기 때문에 서버 렌더링이 실패합니다.
일반 객체는 서버 렌더링을 사용하지 않거나 엔진 가져오기가 필요 없는 옵션의 경우에도 작동합니다.
언어 팩은 일반 객체이며 항상 정적으로 가져올 수 있습니다: import ko from 'suneditor/langs/ko'.

제어된 값

const [html, setHtml] = useState('<p>Hello</p>');

<SunEditor value={html} onChange={setHtml} options={...} />

value을 마지막 onChange 결과가 아닌 다른 값으로 변경하면 편집기 콘텐츠가 바뀝니다. 제어되지 않는 편집기를 사용하려면 value을 생략하고 필요할 때 해당 인스턴스에서 콘텐츠를 읽으십시오.

인스턴스 액세스

const ref = useRef<SunEditorInstance | null>(null);

<SunEditor ref={ref} options={...} />

ref.current?.$.html.get();
ref.current?.$.html.set('<p>new</p>');
ref.current?.resetOptions({ height: '600px' });

ref는 suneditor.create()에서 반환된 객체이므로 전체 엔진 API를 사용할 수 있습니다.

Events

핸들러를 options.events을 통해 전달합니다. 핸들러는 렌더링될 때마다 다시 동기화되므로 React 상태를 안전하게 닫을 수 있습니다.

<SunEditor
	options={(se) => ({
		plugins: [se.plugins.image],
		events: {
			onSave: async () => { await save(html); return true; },
			onImageUploadBefore: ({ info, handler }) => { ... },
		},
	})}
/>

다른 요소의 툴바 또는 상태 표시줄

DOM 요소를 인수로 받는 엔진 옵션은 options 함수가 마운트 후에 실행되기 때문에 refs와 함께 작동합니다.

const toolbarRef = useRef<HTMLDivElement>(null);

<div ref={toolbarRef} />
<SunEditor options={(se) => ({ plugins: [se.plugins.link], toolbar_container: toolbarRef.current })} />

Multi-root

하나의 엔진 인스턴스(툴바, 플러그인, 이벤트, 테마)에 여러 개의 편집 가능한 영역이 있습니다. 각 영역마다 <SunEditorGroup> 안에 <SunEditorRoot>을 넣으세요. 그 사이에 다른 JSX 요소를 넣을 수 있습니다. 이 그룹은 자체적으로 어떤 요소도 렌더링하지 않습니다.

const toolbarRef = useRef<HTMLDivElement>(null);

<SunEditorGroup options={(se) => ({ plugins: [se.plugins.link], toolbar_container: toolbarRef.current })}>
  <div ref={toolbarRef} />
  <h2>Title</h2>
  <SunEditorRoot name='header' value={header} onChange={setHeader} options={{ height: '80px' }} />
  <SunEditorRoot name='body' value={body} onChange={setBody} readOnly={locked} />
</SunEditorGroup>;

• name는 엔진 rootKey(ref.current.changeFrameContext('body'), html.get({ rootKey: 'body' }))입니다.
• 각 루트에는 자체 value / onChange, readOnly, disabled 및 프레임 options (height, placeholder, iframe, ...)이 있습니다.
• 엔진은 공유 툴바를 위해 toolbar_container이 필요합니다. 단, mode이 inline 또는 balloon인 경우는 예외입니다.
• 루트는 그룹이 마운트될 때 수집됩니다. 엔진은 나중에 루트를 추가하거나 제거할 수 없으므로, 다른 루트로 그룹을 다시 생성하려면 그룹의 key 값을 변경하십시오.

Props

events 및 theme 이외의 옵션은 편집기를 생성할 때 적용됩니다. 나중에 변경하려면 다른 key로 다시 마운트하거나 ref.current.resetOptions()를 호출하십시오.

Types

import type {
  SunEditorProps,
  SunEditorGroupProps,
  SunEditorRootProps,
  SunEditorInstance,
  SunEditorOptions,
  SunEditorFrameOptions,
  SunEditorEvents,
} from '@suneditor/suneditor-react';

모든 엔진 유형은 suneditor/types에서도 이용 가능합니다.

Next.js 메모

• 해당 구성 요소는 클라이언트 모듈("use client"은 빌드 출력에 포함됨)이며 브라우저에서만 엔진을 로드하므로 서버 구성 요소에서 직접 렌더링할 수 있습니다.
• 클라이언트 구성 요소의 정적 가져오기에서 suneditor을 제외하세요. se.plugins에 접근하려면 options={(se) => ...} 형식을 사용하세요.
• CSS 가져오기(suneditor/css/editor, suneditor/css/contents, suneditor/src/themes/*.css)는 App Router와 Pages Router 모두에서 작동합니다.