rich markdown editor

리치 마크다운 편집기

개요를 강화하고 읽기 전용 방식으로 콘텐츠를 표시하는 데에도 사용할 수 있는 React 및 Prosemirror 기반 편집기입니다. 편집기는 WYSIWYG이며 마크다운 바로가기를 인라인으로 작성하고 일반 마크다운을 출력하는 기능을 유지하면서 서식 지정 도구를 포함합니다. 라이브 데모 스토리북을 참조하세요.

중요 참고 사항: 이 프로젝트는 다목적 마크다운 편집기가 되려고 시도하지 않습니다 . 이는 아웃라인 지식 기반을 위해 구축되었으며 다른 사람들이 자신의 제품에서 이 패키지를 포크하거나 사용하는 것을 환영하지만 개발 결정은 아웃라인의 요구 사항을 중심으로 이루어집니다.

용법

설치하다

yarn add rich-markdown-editor

또는

npm install rich-markdown-editor

react , react-dom 및 styled-components 필수 피어 종속성입니다.

수입

 import Editor from "rich-markdown-editor" ;

< Editor
  defaultValue = "Hello world!"
/>

이 저장소를 복제하고 yarn start 로 Storybook을 실행하면 다양한 예제 사용법을 볼 수 있습니다.

소품

id

로컬 저장소에 설정을 유지하는 데 사용되는 이 편집기의 고유 ID입니다. id 전달되지 않으면 편집기는 기본적으로 위치 경로 이름을 사용합니다.

defaultValue

편집기의 초기 값을 나타내는 마크다운 문자열입니다. 사용자가 계속 편집할 수 있도록 이전에 저장된 콘텐츠를 복원하는 데 사용합니다.

value

편집기의 값을 나타내는 마크다운 문자열입니다. 이 소품을 사용하여 마운트된 편집기의 값을 변경하면 전체 편집기가 다시 렌더링되므로 readOnly 모드에 있는 경우에만 적합합니다. onChange 값을 value 로 다시 파이프하지 마십시오. 편집기는 자체 내부 상태를 유지하므로 예상치 못한 부작용이 발생합니다.

placeholder

자리 표시자를 재정의할 수 있습니다. 기본값은 "좋은 내용을 작성하세요..."입니다.

readOnly

readOnly false 로 설정하면 편집기가 구성에 최적화됩니다. true 인 경우 편집기를 사용하여 이전에 작성된 콘텐츠를 표시할 수 있습니다. 제목에 앵커가 생기고 링크를 클릭할 수 있게 됩니다.

readOnlyWriteCheckboxes

readOnlyWriteCheckboxes 를 true 로 설정하면 readOnly true 로 설정되고 편집기를 편집할 수 없는 동안 특수한 경우로 확인란을 선택하거나 선택 취소할 수 있습니다.

autoFocus

readOnly false 로 설정하고 true 로 설정하면 자동으로 문서 끝에 초점이 맞춰집니다.

maxLength

설정하면 마크다운 구문을 포함하지 않고 문서에 최대 문자 길이가 적용됩니다.

extensions

추가 Prosemirror 플러그인을 기본 Prosemirror 인스턴스에 전달할 수 있습니다.

disableExtensions

비활성화할 포함된 확장 이름 목록입니다. 해당 메뉴 항목과 명령을 제거합니다. 예를 들어 기울임꼴 텍스트와 인용문을 비활성화하려면 ["em", "blockquote"] 로 설정하세요.

theme

내장된 테마를 재정의하여 편집기를 브랜드화할 수 있습니다. 예를 들어 자신의 글꼴과 브랜드 색상을 사용하여 편집기를 애플리케이션에 맞추도록 할 수 있습니다. 제공되어야 하는 키의 예는 내장 테마를 참조하세요.

dictionary

예를 들어 편집기를 국제화하기 위해 내장된 복사본 사전을 재정의할 수 있습니다. 제공되어야 하는 키의 예는 내장 사전을 참조하세요.

dark

dark true 로 설정하면 편집기는 포함된 기본 어두운 테마를 사용합니다. 여기에서 소스를 참조하세요.

dir

기본값: auto

문서의 방향을 제어합니다. 가능한 값은 다음과 같습니다.

• ltr : 편집기 레이아웃은 LTR 문서에 최적화되어 있으며 콘텐츠는 명시적으로 LTR로 표시됩니다.
• rtl : 편집기 레이아웃은 RTL 문서에 최적화되어 있으며 콘텐츠는 명시적으로 RTL로 표시됩니다.
• auto : 편집기 레이아웃은 문서 내용에 따라 브라우저에 의해 결정됩니다.

tooltip

선택적 도구 설명이 있는 항목을 감싸는 React 구성 요소입니다. 이를 사용하여 자신만의 툴팁 라이브러리를 편집기에 삽입할 수 있습니다. 구성 요소에는 다음 소품이 전달됩니다.

• tooltip : 툴팁 내용이 포함된 React 노드
• placement : 열거형 top , bottom , left , right
• children : 도구 설명이 래핑하는 구성 요소를 렌더링해야 합니다.

headingsOffset

여러 수준으로 문서 제목을 오프셋하는 숫자입니다. 예를 들어, 기본 h1 제목 아래에 편집기를 이미 중첩한 경우 사용자가 h2 제목 이하만 생성할 수 있도록 할 수 있습니다. 이 경우 소품을 1 로 설정합니다.

scrollTo

제목 앵커를 나타내는 문자열 – 제목이 뷰포트에 표시되도록 문서가 부드럽게 스크롤됩니다.

embeds

선택적으로 matcher 함수가 정확한 값을 반환할 때 링크 대신 삽입될 삽입을 정의합니다. matcher 메서드의 반환 값은 props.attrs.matches 아래 구성 요소에서 사용할 수 있습니다. title 과 icon 제공되면 포함된 내용이 블록 메뉴에도 나타납니다.

 < Editor
  embeds = { [
    {
      title : "Google Doc" ,
      keywords : "google docs gdocs" ,
      icon : < GoogleDocIcon /> ,
      defaultHidden : false ,
      matcher : href => href . matches ( / docs.google.com / i ) ,
      component : GoogleDocEmbed
    }
  ] }
/>

콜백

uploadImage(file: Blob): Promise<string>

편집기가 이미지를 지원하도록 하려면 이 콜백을 제공해야 합니다. 콜백은 단일 File 객체를 허용하고 이미지가 저장 위치(예: S3)에 업로드되면 URL로 확인되는 약속을 반환해야 합니다. 예:

 < Editor
  uploadImage = { async file => {
    const result = await s3 . upload ( file ) ;
    return result . url ;
  } }
/> 

onBlur(): void

이 콜백은 사용자가 편집기 contenteditable 및 블록 메뉴 및 부동 도구 모음과 같은 모든 관련 UI 요소에 초점을 잃을 때 트리거됩니다. 콘텐츠 편집 가능 영역 에서만 블러 이벤트를 수신하려면 handleDOMEvents 소품을 사용하세요.

onFocus(): void

이 콜백은 사용자가 편집기 콘텐츠 편집 가능 또는 블록 메뉴나 부동 도구 모음과 같은 관련 UI 요소에 초점을 얻을 때 트리거됩니다. 콘텐츠 편집 가능 영역 에서만 포커스 이벤트를 수신하려면 handleDOMEvents 소품을 사용하세요.

onSave({ done: boolean }): void

이 콜백은 사용자가 키보드 단축키 Cmd+S 또는 Cmd+Enter 사용하여 명시적으로 저장을 요청할 때 트리거됩니다. 이를 신호로 사용하여 문서를 원격 서버에 저장할 수 있습니다.

onCancel(): void

이 콜백은 편집기 내에서 Cmd+Escape 누르면 트리거됩니다. 편집을 취소하는 데 사용할 수 있습니다.

onChange(() => value): void

이 콜백은 일반적으로 키 입력이나 서식 옵션 사용과 같은 사용자 입력으로 인해 편집기의 내용이 변경될 때 트리거됩니다. 이를 사용하여 편집자 상태를 로컬로 유지할 수 있습니다.

호출 시 문서의 현재 텍스트 값을 반환하는 함수를 반환합니다. 이 최적화는 모든 변경 이벤트에서 문서 상태를 텍스트로 직렬화하는 것을 방지하여 호스트 앱이 직렬화된 값이 필요할 때 선택할 수 있도록 하기 위해 이루어졌습니다.

onImageUploadStart(): void

이 콜백은 uploadImage 전에 트리거되며 업로드가 진행 중임을 나타내는 일부 UI를 표시하는 데 사용될 수 있습니다.

onImageUploadStop(): void

이미지 업로드가 성공하거나 실패하면 트리거됩니다.

onSearchLink(term: string): Promise<{ title: string, subtitle?: string, url: string }[]>

편집기는 서식 도구 모음에서 삽입할 링크를 검색하는 기능을 제공합니다. 이 콜백이 제공되면 검색어를 유일한 매개변수로 허용하고 객체 배열로 확인되는 프라미스를 반환해야 합니다. 예:

 < Editor
  onSearchLink = { async searchTerm => {
    const results = await MyAPI . search ( searchTerm ) ;

    return results . map ( result => {
      title : result . name ,
      subtitle : `Created ${ result . createdAt } ` ,
      url : result . url
    } )
  } }
/> 

onCreateLink(title: string): Promise<string>

편집기는 즉각적인 문서 생성을 위해 서식 도구 모음에서 링크를 생성하는 기능을 제공합니다. 이 콜백이 제공되면 링크 "제목"을 유일한 매개변수로 허용하고 생성된 링크에 대한 URL을 확인하는 약속을 반환해야 합니다. 예:

 < Editor
  onCreateLink = { async title => {
    const url = await MyAPI . create ( {
      title
    } ) ;

    return url ;
  } }
/> 

onShowToast(message: string, type: ToastType): void

편집자가 사용자에게 메시지를 표시하려고 할 때 트리거됩니다. 앱의 알림 시스템에 연결하거나 간단하게 window.alert(message) 사용하세요. 두 번째 매개변수는 토스트 유형('error' 또는 'info')입니다.

onClickLink(href: string, event: MouseEvent): void

이 콜백을 사용하면 링크 처리를 재정의할 수 있습니다. 외부 링크가 새 창을 열도록 하고 내부 링크가 react-router 와 같은 것을 사용하여 탐색하도록 하는 경우가 종종 있습니다. 콜백이 제공되지 않으면 새 탭을 여는 기본 동작이 모든 링크에 적용됩니다. 예:

 import { history } from "react-router" ;

< Editor
  onClickLink = { ( href , event ) => {
    if ( isInternalLink ( href ) ) {
      history . push ( href ) ;
    } else {
      window . location . href = href ;
    }
  } }
/> 

onHoverLink(event: MouseEvent): boolean

이 콜백을 사용하면 사용자가 문서의 링크 위로 마우스를 가져가는 것을 감지할 수 있습니다.

 < Editor
  onHoverLink = { event => {
    console . log ( `Hovered link ${ event . target . href } ` ) ;
  } }
/> 

onClickHashtag(tag: string, event: MouseEvent): void

이 콜백을 사용하면 문서 텍스트의 해시태그 클릭을 처리할 수 있습니다. 콜백이 제공되지 않으면 해시태그가 일반 텍스트로 렌더링되므로 이 prop을 전달하여 해시태그 지원 여부를 선택할 수 있습니다.

 import { history } from "react-router" ;

< Editor
  onClickHashtag = { tag => {
    history . push ( `/hashtags/ ${ tag } ` ) ;
  } }
/> 

handleDOMEvents: {[name: string]: (view: EditorView, event: Event) => boolean;}

이 객체는 이벤트 이름( focus , paste , touchstart 등)을 콜백 함수에 매핑합니다.

 < Editor
  handleDOMEvents = { {
    focus : ( ) => console . log ( "FOCUS" ) ,
    blur : ( ) => console . log ( "BLUR" ) ,
    paste : ( ) => console . log ( "PASTE" ) ,
    touchstart : ( ) => console . log ( "TOUCH START" ) ,
  } }
/>

인터페이스

Editor 구성 요소는 탑재된 편집기와 상호 작용하기 위한 몇 가지 방법을 공개합니다.

focusAtStart(): void

문서의 시작 부분에 커서를 놓고 초점을 맞춥니다.

focusAtEnd(): void

문서 끝에 커서를 놓고 초점을 맞춥니다.

getHeadings(): { title: string, level: number, id: string }[]

문서에 있는 모든 제목의 텍스트 콘텐츠, 계층 구조의 해당 수준 및 앵커 ID가 포함된 개체 배열을 반환합니다. v10에서는 toc 옵션이 제거되었으므로 자신만의 목차를 구성하는 데 유용합니다.

기여

이 프로젝트에서는 Yarn을 사용하여 종속성을 관리합니다. npm을 사용할 수 있지만 Yarn 잠금 파일을 존중하지 않으며 약간 다른 버전을 설치할 수 있습니다.

 yarn install

개발 중에 실행할 때 Storybook은 핫 리로딩을 통해 예제 편집기에 포함됩니다. 종속성을 설치한 후에는 yarn start 실행하여 시작하세요.

yarn link 사용하여 개발할 때 yarn watch 사용하여 변경 사항이 있을 때 dist 로 변경 사항을 지속적으로 다시 빌드할 수 있습니다.

특허

이 프로젝트는 BSD 라이센스를 받았습니다.