react quill
v1.1.0
React용 Quill 구성요소입니다.
라이브 데모 또는 Codepen을 확인하세요.
이것은 ReactQuill v2에 대한 문서입니다 — 이전 릴리스: v1
? ReactQuill v2
ReactQuill 2가 출시되었습니다! 또한 TypeScript 및 React 16+에 대한 전체 포트, 리팩터링된 빌드 시스템 및 내부 로직의 전반적인 강화를 제공합니다.
우리는 행동 변화를 피하기 위해 열심히 노력했습니다. 대부분의 경우 마이그레이션이 전혀 필요하지 않습니다. 그러나 오랫동안 사용되지 않는 props, ReactQuill Mixin 및 Toolbar 구성 요소에 대한 지원이 제거되었습니다. 마이그레이션 가이드를 꼭 읽어보세요.
이번 릴리스는 드롭인 업그레이드가 될 것으로 예상됩니다. 그렇지 않은 경우 v2 레이블로 문제를 제출하세요.
react 및 react-dom 이 있는지 확인하고 스타일 로더와 같은 스타일을 로드할 수 있는 방법이 있는지 확인하세요. 자세한 내용은 테마 문서를 참조하세요.
npm install react-quill --save import React , { useState } from 'react' ;
import ReactQuill from 'react-quill' ;
import 'react-quill/dist/quill.snow.css' ;
function MyComponent ( ) {
const [ value , setValue ] = useState ( '' ) ;
return < ReactQuill theme = "snow" value = { value } onChange = { setValue } / > ;
} < link
rel =" stylesheet "
href =" https://unpkg.com/[email protected]/dist/quill.snow.css "
/> < script
src =" https://unpkg.com/react@16/umd/react.development.js "
crossorigin
> </ script >
< script
src =" https://unpkg.com/react-dom@16/umd/react-dom.development.js "
crossorigin
> </ script >
< script src =" https://unpkg.com/[email protected]/dist/react-quill.js " > </ script >
< script src =" https://unpkg.com/babel-standalone@6/babel.min.js " > </ script >
< script type =" text/babel " src =" /my-scripts.js " > </ script > 제어 모드에서 구성 요소는 로컬 상태 저장 변경을 방지하고 대신 onChange 및 value 통해서만 발생하도록 합니다.
Quill은 자체 변경 사항을 처리하고 편집 방지를 허용하지 않기 때문에 ReactQuill은 제어 모드와 비제어 모드 간의 하이브리드에 만족해야 합니다. 변경을 방지할 수는 없지만 value 현재 상태와 다를 때마다 내용을 재정의합니다.
DOM을 자주 조작해야 하거나 Quill API를 명령적으로 사용해야 하는 경우 완전히 제어되지 않는 모드로 전환하는 것을 고려할 수 있습니다. ReactQuill은 defaultValue 사용하여 편집기를 초기화하지만 그 이후에는 재설정을 시도하지 않습니다. onChange 콜백은 예상대로 계속 작동합니다.
React 문서에서 제어되지 않는 구성 요소에 대해 자세히 알아보세요.
HTML 문자열 대신 Quill Delta를 value 및 defaultValue 속성으로 전달할 수 있습니다. 델타는 HTML 문자열에 비해 여러 가지 장점이 있으므로 대신 사용할 수 있습니다. 그러나 변경 사항에 대해 델타를 비교하는 것은 HTML 문자열을 비교하는 것보다 비용이 더 많이 들기 때문에 사용 패턴을 프로파일링하는 것이 가치가 있을 수 있습니다.
value HTML 문자열에서 Delta로 또는 그 반대로 전환하면 동일한 문서를 나타내는지 여부에 관계없이 변경이 트리거되므로 형식을 고수하고 전체적으로 일관되게 사용하는 것이 좋습니다.
onChange 이벤트에서 받은 delta 객체를 value 로 사용하지 마세요. 이 개체에는 전체 문서가 포함되지 않고 마지막 수정 사항만 포함되므로 동일한 변경 사항이 계속해서 적용되는 무한 루프가 발생할 가능성이 높습니다. 대신 전체 문서의 델타를 얻으려면 이벤트 중에 editor.getContents() 사용하십시오. ReactQuill은 이러한 실수를 방지해 주지만 이것이 원하는 것이라고 확신하는 경우 new Delta() 통해 객체를 다시 전달하여 오염을 제거할 수 있습니다.
Quill 편집기는 테마를 지원합니다. 여기에는 Quill의 표준 모양인 snow 라는 본격적인 테마와 Medium의 인라인 편집기와 유사한 버블 테마가 포함되어 있습니다. 도구 모음이나 도구 설명과 같은 모듈이 작동하려면 최소한 핵심 테마가 포함되어야 합니다.
테마를 활성화하려면 테마 이름을 theme prop에 전달하세요. 핵심 테마를 사용하려면 잘못된 값(예: null )을 전달하세요.
< ReactQuill theme = "snow" . . . / >그런 다음 사용하려는 테마의 스타일시트를 가져옵니다.
이는 애플리케이션의 구조, 디렉토리 또는 기타 방식에 따라 달라질 수 있습니다. 예를 들어 SASS와 같은 CSS 전처리기를 사용하는 경우 해당 스타일시트를 자체 스타일시트로 가져올 수 있습니다. 이러한 스타일시트는 Quill 배포판에서 찾을 수 있지만 편의상 ReactQuill의 dist 폴더에도 연결되어 있습니다.
다음은 페이지에 스타일을 자동으로 삽입하는 Webpack용 스타일 로더 또는 create-react-app 사용하는 예입니다.
import 'react-quill/dist/quill.snow.css' ;스타일은 CDN을 통해서도 사용할 수 있습니다.
< link
rel =" stylesheet "
href =" https://unpkg.com/[email protected]/dist/quill.snow.css "
/>Quill 도구 모음 모듈 API는 형식 이름 배열을 사용하여 기본 도구 모음 아이콘을 구성하는 쉬운 방법을 제공합니다.
class MyComponent extends Component {
constructor ( props ) {
super ( props ) ;
this . state = {
text : "" ,
}
}
modules = {
toolbar : [
[ { 'header' : [ 1 , 2 , false ] } ] ,
[ 'bold' , 'italic' , 'underline' , 'strike' , 'blockquote' ] ,
[ { 'list' : 'ordered' } , { 'list' : 'bullet' } , { 'indent' : '-1' } , { 'indent' : '+1' } ] ,
[ 'link' , 'image' ] ,
[ 'clean' ]
] ,
} ,
formats = [
'header' ,
'bold' , 'italic' , 'underline' , 'strike' , 'blockquote' ,
'list' , 'bullet' , 'indent' ,
'link' , 'image'
] ,
render ( ) {
return (
< div className = "text-editor" >
< ReactQuill theme = "snow"
modules = { this . modules }
formats = { this . formats } >
< / ReactQuill >
< / div >
) ;
}
}
export default MyComponent ; Quill 테마의 일부가 아닌 사용자 정의 요소를 사용하여 자신만의 HTML/JSX 도구 모음을 제공할 수도 있습니다.
Codepen에서 실시간으로 이 예제를 확인하세요: 사용자 정의 도구 모음 예제
/*
* Custom "star" icon for the toolbar using an Octicon
* https://octicons.github.io
*/
const CustomButton = ( ) => < span className = "octicon octicon-star" / > ;
/*
* Event handler to be attached using Quill toolbar module
* http://quilljs.com/docs/modules/toolbar/
*/
function insertStar ( ) {
const cursorPosition = this . quill . getSelection ( ) . index ;
this . quill . insertText ( cursorPosition , '★' ) ;
this . quill . setSelection ( cursorPosition + 1 ) ;
}
/*
* Custom toolbar component including insertStar button and dropdowns
*/
const CustomToolbar = ( ) => (
< div id = "toolbar" >
< select
className = "ql-header"
defaultValue = { '' }
onChange = { ( e ) => e . persist ( ) }
>
< option value = "1" > < / option >
< option value = "2" > < / option >
< option selected > < / option >
< / select >
< button className = "ql-bold" > < / button >
< button className = "ql-italic" > < / button >
< select className = "ql-color" >
< option value = "red" > < / option >
< option value = "green" > < / option >
< option value = "blue" > < / option >
< option value = "orange" > < / option >
< option value = "violet" > < / option >
< option value = "#d0d1d2" > < / option >
< option selected > < / option >
< / select >
< button className = "ql-insertStar" >
< CustomButton / >
< / button >
< / div >
) ;
/*
* Editor component with custom toolbar and content containers
*/
class Editor extends React . Component {
constructor ( props ) {
super ( props ) ;
this . state = { editorHtml : '' } ;
this . handleChange = this . handleChange . bind ( this ) ;
}
handleChange ( html ) {
this . setState ( { editorHtml : html } ) ;
}
render ( ) {
return (
< div className = "text-editor" >
< CustomToolbar / >
< ReactQuill
onChange = { this . handleChange }
placeholder = { this . props . placeholder }
modules = { Editor . modules }
/ >
< / div >
) ;
}
}
/*
* Quill modules to attach to editor
* See http://quilljs.com/docs/modules/ for complete options
*/
Editor . modules = {
toolbar : {
container : '#toolbar' ,
handlers : {
insertStar : insertStar ,
} ,
} ,
} ;
/*
* Quill editor formats
* See http://quilljs.com/docs/formats/
*/
Editor . formats = [
'header' ,
'font' ,
'size' ,
'bold' ,
'italic' ,
'underline' ,
'strike' ,
'blockquote' ,
'list' ,
'bullet' ,
'indent' ,
'link' ,
'image' ,
'color' ,
] ;
/*
* PropType validation
*/
Editor . propTypes = {
placeholder : React . PropTypes . string ,
} ;
/*
* Render component on page
*/
ReactDOM . render (
< Editor placeholder = { 'Write something or insert a star ★' } / > ,
document . querySelector ( '.app' )
) ;구성요소에는 두 가지 유형의 형식이 있습니다.
formats prop을 사용하여 활성화/비활성화되는 기본 Quill 형식입니다. 모든 형식은 기본적으로 활성화되어 있습니다. import ReactQuill , { Quill } from 'react-quill' ; // ES6
const ReactQuill = require ( 'react-quill' ) ; // CommonJS /*
* Example Parchment format from
* https://quilljs.com/guides/cloning-medium-with-parchment/
* See the video example in the guide for a complex format
*/
let Inline = Quill . import ( 'blots/inline' ) ;
class BoldBlot extends Inline { }
BoldBlot . blotName = 'bold' ;
BoldBlot . tagName = 'strong' ;
Quill . register ( 'formats/bold' , BoldBlot ) ;
const formats = [ 'bold' ] ; // add custom format name + any built-in formats you need
/*
* Editor component with default and custom formats
*/
class MyComponent extends React . Component {
constructor ( props ) {
this . formats = formats ;
this . state = { text : '' } ;
}
handleChange ( value ) {
this . setState ( { text : value } ) ;
}
render ( ) {
return (
< ReactQuill
value = { this . state . text }
onChange = { this . handleChange }
formats = { this . formats }
/ >
) ;
}
} 자식 없이 ReactQuill을 인스턴스화하면 Quill의 편집 영역으로 사용할 <div> 생성됩니다. 원하는 경우 ReactQuill에서 사용할 고유한 요소를 지정할 수 있습니다. <textarea> 는 현재 Quill에서 지원되지 않습니다.
참고: 현재 React 16을 동료 개발자로 사용하면 사용자 정의 편집 영역이 초점을 잃습니다(버그).
class MyComponent extends React . Component {
render ( ) {
return (
< ReactQuill >
< div className = "my-editing-area" / >
< / ReactQuill >
) ;
}
} ) ; ReactQuill v2로 업그레이드하는 것은 종속성을 업데이트하는 것만큼 간단해야 합니다. 그러나 오랫동안 사용되지 않는 props, ReactQuill Mixin 및 Toolbar 구성 요소에 대한 지원도 제거됩니다.
toolbar , styles , pollInterval Quill 옵션에 대한 지원은 오랫동안 비활성화되었습니다. 이번 릴리스부터 ReactQuill을 사용하려고 하면 더 이상 경고하지 않습니다.
ReactQuill Mixin을 사용하면 ReactQuill을 자체 구성 요소에 적용하는 핵심 기능을 주입하고 심층적으로 사용자 정의된 버전을 만들 수 있습니다.
Mixin은 오랫동안 안티 패턴으로 간주되어 왔기 때문에 우리는 Mixin의 지원 중단을 마무리하기로 결정했습니다.
업그레이드 경로가 없습니다. Mixin에 의존하는 사용 사례가 있는 경우 문제를 공개하는 것이 좋습니다. 이를 가능하게 하는 새로운 기능이나 마이그레이션을 위한 전담 지원을 제공하려고 노력할 것입니다.
Quill은 오랫동안 ReactQuill의 (매우 유연하지 않은) Toolbar 구성 요소를 대체하는 사용자 정의 도구 모음에 대한 내장 지원을 제공해 왔습니다.
대신 도구 모음 모듈이나 HTML 도구 모음 기능을 사용하세요.
// ES6
import ReactQuill , { Quill } from 'react-quill' ;
// CommonJS
const ReactQuill = require ( 'react-quill' ) ;
const { Quill } = ReactQuill ; Quill : register 호출할 수 있는 Quill 네임스페이스입니다.
id : DOM 요소에 적용할 ID입니다.
className : DOM 요소에 적용할 클래스입니다.
value : 제어되는 구성 요소로서의 편집기에 대한 값입니다. HTML을 포함하는 문자열, Quill Delta 인스턴스 또는 Delta를 나타내는 일반 개체일 수 있습니다. Quill의 제한으로 인해 이는 실제로 반 제어 모드입니다. 즉, 편집이 금지되지는 않지만 value 변경하면 내용이 계속 대체됩니다. 또한 여기에 Quill Delta를 전달한 다음 HTML 문자열을 전달하거나 그 반대로 전달하면 동일한 문서를 나타내는지 여부에 관계없이 항상 변경이 트리거됩니다.onChange 이벤트의 delta 객체를 value 로 전달하지 마십시오. 자세한 내용은 델타 사용을 참조하세요.
defaultValue : 제어되지 않는 구성 요소인 편집기의 초기 값입니다. HTML, Quill Delta를 포함하는 문자열 또는 Delta를 나타내는 일반 개체일 수 있습니다.
readOnly : true인 경우 편집기에서 내용 변경을 허용하지 않습니다. Quill disable API를 래핑합니다.
placeholder : 빈 편집기의 기본값입니다. 참고: Quill API는 이 값을 동적으로 변경하는 것을 지원하지 않습니다. 대신 참조 및 데이터 속성을 사용하세요(#340 참조).
modules : 활성화된 모듈과 해당 구성을 지정하는 개체입니다. 편집기 도구 모음은 일반적으로 사용자 정의된 모듈입니다. 어떤 모듈을 사용할 수 있는지에 대한 자세한 내용은 Quill 문서의 모듈 섹션을 참조하세요.
formats : 편집 중에 활성화할 형식의 배열입니다. 구현된 모든 형식은 기본적으로 활성화됩니다. 목록은 형식을 참조하세요. 버전 1.0.0부터는 사용자 정의 형식이 배열에 포함되어서는 안 됩니다. 대신 Parchment를 통해 생성하고 모듈의 Quill 내보내기에 등록해야 합니다.
style : 편집기의 컨테이너에 적용할 사용자 정의 CSS 규칙이 있는 객체입니다. 규칙은 React의 "camelCased" 명명 스타일을 따라야 합니다.
theme : 편집기에 적용할 테마의 이름입니다. 기본값은 Quill의 표준 테마인 snow 입니다. 최소 핵심 테마를 사용하려면 null 전달하세요. 필수 스타일시트 포함에 대한 자세한 내용은 테마 문서를 참조하세요.
tabIndex : 키보드 탐색 중에 페이지의 다른 컨트롤 중에서 편집기에 초점이 맞춰지는 순서입니다.
bounds : 팝업 위치를 제한하기 위해 Quill에서 사용하는 선택기 또는 DOM 요소입니다. 기본값은 document.body 입니다.
children : 기본값인 <div> 대신 Quill의 편집 영역으로 사용될 단일 React 요소입니다. <textarea> 는 지원되는 대상이 아니므로 사용할 수 없습니다. 또한 하위 항목을 업데이트하면 Quill 편집기가 다시 생성되므로 비용이 많이 듭니다. 편집기의 html 콘텐츠를 제어하려면 value prop을 설정하세요.
onChange(content, delta, source, editor) : 변경 후 편집기의 새 내용으로 다시 호출됩니다. 편집기의 HTML 콘텐츠, 변경 사항을 표현하는 델타 객체, 변경 소스, 마지막으로 getHTML() 과 같은 편집기 접근자에 대한 읽기 전용 프록시가 전달됩니다.delta 객체를 value 로 사용하지 마십시오. 대신 editor.getContents() 사용하세요. 자세한 내용은 델타 사용을 참조하세요.
onChangeSelection(range, source, editor) : 새로 선택한 범위로 다시 호출되거나 초점이 맞지 않으면 null입니다. 선택 범위, 변경 소스, 마지막으로 getBounds() 와 같은 편집기 접근자에게 읽기 전용 프록시가 전달됩니다.
onFocus(range, source, editor) : 편집기에 포커스가 있을 때 호출됩니다. 새로운 선택 범위를 받게 됩니다.
onBlur(previousRange, source, editor) : 편집기가 포커스를 잃을 때 호출됩니다. 포커스를 잃기 직전의 선택 범위를 받게 됩니다.
onKeyPress(event) : 키를 눌렀다가 놓은 후에 호출됩니다. : 기본 대응과 마찬가지로 Shift 또는 Enter 와 같은 특수 키에 대해서는 호출되지 않습니다. 필요한 경우 onKeyDown 또는 onKeyUp 에 연결하세요.
onKeyDown(event) : 키를 누른 후, 놓기 전에 호출됩니다. : Quill의 작동 방식으로 인해 enter , backspace 또는 delete 와 같은 키에 대한 이벤트를 수신하지 못할 수도 있습니다. 그렇다면 대신 onKeyUp 에 연결해 보세요.
onKeyUp(event) : 키를 놓은 후 호출됩니다.
preserveWhitespace : true인 경우 기본 div 태그 대신 pre 태그가 편집기 영역에 사용됩니다. 이렇게 하면 Quill이 붙여넣기에서 연속 공백을 축소하는 것을 방지할 수 있습니다. 관련 문제.
ReactQuill 노드에 대한 참조가 있는 경우 다음 메서드를 호출할 수 있습니다.
focus() : 편집기에 초점을 맞춥니다.
blur() : 편집기에서 포커스를 제거합니다.
getEditor() : 편집기를 지원하는 Quill 인스턴스를 반환합니다. 이를 자유롭게 사용하여 getText() 와 같은 메소드에 액세스할 수 있지만 ReactQuill 및 Quill이 동기화되지 않는 것을 방지하려면 인스턴스를 명령적으로 조작하지 마십시오. 훨씬 더 안전한 비권한 편집기를 대체할 수 있습니다.
Codepen에서 이 예제 보기
class Editor extends React . Component {
constructor ( props ) {
super ( props ) ;
this . quillRef = null ; // Quill instance
this . reactQuillRef = null ; // ReactQuill component
}
componentDidMount ( ) {
this . attachQuillRefs ( ) ;
}
componentDidUpdate ( ) {
this . attachQuillRefs ( ) ;
}
attachQuillRefs = ( ) => {
if ( typeof this . reactQuillRef . getEditor !== 'function' ) return ;
this . quillRef = this . reactQuillRef . getEditor ( ) ;
} ;
insertText = ( ) => {
var range = this . quillRef . getSelection ( ) ;
let position = range ? range . index : 0 ;
this . quillRef . insertText ( position , 'Hello, World! ' ) ;
} ;
render ( ) {
return (
< div >
< ReactQuill
ref = { ( el ) => {
this . reactQuillRef = el ;
} }
theme = { 'snow' }
/ >
< button onClick = { this . insertText } > Insert Text < / button >
< / div >
) ;
}
} makeUnprivilegedEditor : 권한이 없는 편집기를 생성합니다. 이 메서드에 getEditor 의 Quill 인스턴스에 대한 참조를 전달합니다. 일반적으로 이벤트 핸들러에 노출된 편집기에는 이미 권한이 없으므로 이 방법을 사용할 필요가 없습니다.
const editor = this . reactQuillRef . getEditor ( ) ;
const unprivilegedEditor = this . reactQuillRef . makeUnprivilegedEditor ( editor ) ;
// You may now use the unprivilegedEditor proxy methods
unprivilegedEditor . getText ( ) ; 이벤트 중에 ReactQuill은 Quill API의 제한된 하위 집합을 editor 인수로 사용할 수 있도록 만듭니다. 이렇게 하면 ReactQuill이 구성 요소와 동기화되지 않을 수 있는 파괴적인 메서드에 대한 액세스가 방지됩니다. 이는 대부분 기존 Quill 메서드의 프록시인 다음 메서드를 제공합니다.
getLength() : 편집기 내용의 길이를 inc가 아닌 문자 단위로 반환합니다.
