flyeditor

v1.6.3

Published

3 days ago

A lightweight react webeditor, flyeditor

0High
0Medium
0Low

disketch

react lightweight flyeditor webeditor wysiwyg editor

FlyEditor

FlyEditor는 React 환경에서 간편하게 사용할 수 있는 위지윅(WYSIWYG) 웹에디터 컴포넌트입니다.
손쉽게 편집 및 뷰어 모드 전환, 파일 업로드, 커스텀 도구모음 등을 지원합니다.

에디터 미리보기

아래 링크에서 FlyEditor 의 동작 및 기능을 테스트해 보실 수 있습니다.

FlyEditor 미리보기

flyeditor image

주요 기능 (Features)

자유로운 모드 전환: editable 속성을 통해 편집 모드와 읽기 전용(Viewer) 모드를 손쉽게 전환할 수 있습니다.
다양한 이미지 업로드 방식 지원:
- 단일 및 다중 파일 업로드 콜백 지원 (onUploadImage, onUploadImages)
- 에디터 내 직접 드래그 앤 드롭(Drag & Drop) 업로드 지원
- 외부 상태(insertImageSource)를 통한 동적 이미지 URL 직접 삽입 기능
자유로운 커스텀 툴바 (Toolbar): 가로(toolsH) 및 세로(toolsV) 툴바 항목을 원하는 구성으로 자유롭게 배치 및 제한할 수 있습니다.
커스텀 폰트 & 크기 설정: 기본 글꼴 및 크기 지정은 물론, 사용자가 사용할 폰트 목록(userFontFamilyList)과 크기 목록(userFontSizeList)을 커스텀 정의할 수 있습니다.
노트 줄 배경 모드: useNoteLine 옵션을 활성화하여 공책/노트 형태의 배경 라인 스타일을 적용할 수 있습니다.
다국어 및 UX 편의기능: 한국어/영어 UI 언어 셋(lang), 툴바 툴팁, 자동 포커스, 단축키(Ctrl+S / Cmd+S) 저장 콜백을 지원합니다.

설치 (Installation)

npm i flyeditor

빠른 시작 (Quick Start)

가장 기본적인 형태로 FlyEditor를 사용하는 방법입니다.

import React, { useState } from 'react';
import FlyEditor from 'flyeditor';
import 'flyeditor/dist/flyeditor.css';

const MyEditor = () => {
    const [initContent, setInitContent] = useState('<p>안녕하세요!</p>');
    const [content, setContent] = useState('');
    const [isEditable, setIsEditable] = useState(true);

    return (
        <FlyEditor
            value={initContent}
            editable={isEditable}
            onChange={setContent}
        />
    );
};

export default MyEditor;

주요 예제 (Usage Examples)

1. 콘텐츠 저장

에디터에 입력된 내용을 저장하는 간단한 방법 입니다.

import React, { useState } from 'react';
import FlyEditor from 'flyeditor';
import 'flyeditor/dist/flyeditor.css';

const MyEditor = () => {
    const [initContent, setInitContent] = useState('<p>안녕하세요!</p>');
    const [content, setContent] = useState('');
    const [isEditable, setIsEditable] = useState(true);

    // 1. 사용자 버튼으로 직접 저장
    const saveContent = async () => {
        // 예시: 서버에 저장 처리 API 호출
        const formData = new FormData();
        formData.append('content', content);
        const res = await api.saveContent(formData);
        console.log('저장되었습니다.');
    };

    // 2. 에디터 내부에서 저장 실행 시
    const onSaveContent = async (htmlContent: string) => {
        // 예시: 서버에 저장 처리 API 호출
        const formData = new FormData();
        formData.append('content', htmlContent);
        const res = await api.saveContent(formData);
        console.log('저장되었습니다.');
    };

    return (
        <div>
            <button onClick={saveContent}>Save</button>
            <FlyEditor
                value={initContent}
                editable={isEditable}
                onChange={setContent}
                onSave={onSaveContent}
            />
        </div>
    );
};

export default MyEditor;

2. 이미지 업로드 처리 (단일)

onUploadImage 속성을 통해 서버 업로드 로직을 연동할 수 있습니다.

import FlyEditor, { IImageAttr } from 'flyeditor';

...

const MyEditor = () => {

    const [initContent, setInitContent] = useState('<p>안녕하세요!</p>');
    const [content, setContent] = useState('');

    // 단일 이미지 업로드 핸들러
    const handleUploadImage = async (file: File): Promise<IImageAttr> => {
        // 예시: 서버 업로드 처리 API 호출
        // const formData = new FormData();
        // formData.append('file', file);
        // const res = await api.upload(formData);

        return {
            url: 'https://example.com/images/sample.png',
            name: file.name,
            alt: '업로드 이미지',
        };
    };

    // 컴포넌트 적용
    return (
        <FlyEditor
            value={initContent}
            editable={true}
            onChange={setContent}
            onUploadImage={handleUploadImage} // 단일 업로드
            // multiUploadImage={true}        // 다중 업로드 사용 시 true
            // onUploadImages={handleUploadImages}
        />
    );
    ...

}

3. 외부 버튼을 통한 이미지 URL 직접 삽입

외부 상태(insertImageSource)를 통해 에디터 내부에 이미지를 동적으로 삽입할 수 있습니다. 삽입 완료 후 onImageInserted 콜백에서 상태를 초기화합니다.

...

const [imageSource, setImageSource] = useState<string | IImageAttr | null>(
    null,
);

const insertImage = () => {
    setImageSource({
        url: 'https://example.com/flower.png',
        name: 'flower',
        alt: '꽃 이미지',
    });
};

return (
    <>
        <button onClick={insertImage}>이미지 삽입</button>
        <FlyEditor
            value={initContent}
            editable={true}
            onChange={setContent}
            insertImageSource={imageSource}
            onImageInserted={() => setImageSource(null)} // 처리 후 null로 리셋 필수
        />
    </>
);

...

4. 콘텐츠 뷰어 설정

에디터에서 작성된 html 콘텐츠를 저장 후 보여주는 화면에서는 아래와 같이 사용 합니다.
(flyeditor.css 를 삽입하고, 뷰 앨리먼트에 FlyView 콤포넌트 추가)

import { FlyView } from 'flyeditor';
import 'flyeditor/dist/flyeditor.css';
...

const MyViewer = () => {

    const [dbContent, setDbContent] = useState('');

    useEffect(()=>{
         // 예시: 서버 데이터 조회 API 호출
        const res = await api.getContent();
        setDbContent(res);
    }, [])

    return (
        <div className="my-viewer-container">
            <FlyView value={dbContent} />
        </div>
    );
    ...

}

FlyEditor Props API Reference

FlyEditor 컴포넌트에서 지원하는 주요 속성 목록입니다. (모든 항목은 선택 옵션이며 설정하지 않으면 기본값으로 동작 합니다.)

인터페이스 (Interfaces)

`IImageAttr`

이미지 삽입 및 업로드 반환 시 사용되는 객체 타입입니다.

export interface IImageAttr {
    url: string; // 이미지 접근 가능한 URL (필수)
    name?: string; // 파일명 또는 식별용 이름
    alt?: string; // 대체 텍스트 (alt 속성)
}

`IFontFamilyItem`

폰트 선택 드롭다운 옵션 타입입니다.

export interface IFontFamilyInfo {
    label: string; // 사용자 화면에 표시될 이름
    value: string; // 실제 CSS font-family 값
}

FlyEditor Custom Toolbar Configuration

toolsH 및 toolsV 속성을 활용하면 필요한 버튼만 커스텀하여 툴바를 배치할 수 있습니다.

toolsH 및 toolsV 항목을 설정하지 않으면 전체 툴바가 모두 삽입되며, 빈 배열([]) 을 할당하면 해당 툴바 영역 자체가 제거됩니다.

toolsH : 가로 배치형 툴바
toolsV : 세로 배치형 툴바
모든 툴바는 가로/세로에 자유롭게 배치 가능하나, 예외적으로 fontsize, fontfamily, letterspacing, lineheight 항목은 가로 배치만 가능합니다.

<FlyEditor
    toolsH={[
        'save',
        'history',
        'fontsize',
        'fontfamily',
        .
        .
        .
    ]}
    toolsV={[
        'left',
        'center',
        'right',
        'justify',
        .
        .
        .
    ]}
/>

FlyEditor Toolbar Items Reference

toolsH 및 toolsV 옵션 배열에 사용할 수 있는 전체 툴 아이콘 목록 및 설명입니다.

1. 가로 툴바 (`toolsH`) - 글자 서식 및 스타일, 저장, 이미지 삽입

2. 세로 툴바 (`toolsV`) - 문단 서식 및 이동

3. 부가 툴바 - 특별한 기능이 없는 툴바 입니다. 툴바 레이아웃 조정을 위해 사용됩니다.

FlyView Props API Reference

FlyView 컴포넌트에서 지원하는 주요 속성 목록입니다. (value 는 필수 항목이며, 그외 모든 항목은 선택 옵션입니다.)

License

MIT License