react quill
v1.1.0
React の Quill コンポーネント。
ライブデモまたは Codepen をご覧ください。
これは ReactQuill v2 のドキュメントです — 以前のリリース: v1
? ReactQuill v2
ReactQuill 2 が登場しました、ベイビー!また、TypeScript と React 16+ への完全な移植、リファクタリングされたビルド システム、および内部ロジックの全般的な強化が実現します。
私たちは行動の変化を避けるために懸命に取り組みました。ほとんどの場合、移行はまったく必要ありません。ただし、長い間非推奨となっていたプロパティ、ReactQuill Mixin、および Toolbar コンポーネントのサポートは削除されました。移行ガイドを必ずお読みください。
このリリースはドロップイン アップグレードになると予想されます。そうでない場合は、 v2ラベルで問題を提出してください。
reactとreact-dom 、および style-loader などのスタイルをロードする何らかの方法があることを確認してください。詳細については、テーマに関するドキュメントを参照してください。
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 文字列からデルタに、またはその逆に切り替えると、それらが同じドキュメントを表しているかどうかに関係なく、変更がトリガーされることに注意してください。そのため、フォーマットにこだわり、一貫してそれを使用し続けることをお勧めします。
onChangeイベントから受け取ったdeltaオブジェクトをvalueとして使用しないでください。このオブジェクトにはドキュメント全体が含まれるのではなく、最後の変更のみが含まれます。これを行うと、同じ変更が何度も適用される無限ループが発生する可能性が高くなります。代わりに、イベント中にeditor.getContents()使用して、ドキュメント全体のデルタを取得します。 ReactQuill はそのような間違いを防ぐことができますが、これが望んでいることであると確信している場合は、オブジェクトを再度new Delta()に渡して汚染を解除することができます。
Quill エディタはテーマをサポートしています。これには、 Quill の標準的な外観であるSnowと呼ばれる本格的なテーマと、Medium のインライン エディターに似たバブルテーマが含まれています。ツールバーやツールヒントなどのモジュールが機能するには、少なくともコアテーマが含まれている必要があります。
テーマをアクティブにするには、テーマの名前をtheme prop に渡します。コアテーマを使用するには、偽の値 (例: null ) を渡します。
< ReactQuill theme = "snow" . . . / >次に、使用するテーマのスタイルシートをインポートします。
これは、アプリケーションの構造、ディレクトリなどによって異なる場合があります。たとえば、SASS などの CSS プリプロセッサを使用している場合、そのスタイルシートを独自のスタイルシート内にインポートすることができます。これらのスタイルシートは Quill ディストリビューションにありますが、便宜上、ReactQuill のdistフォルダーにもリンクされています。
Webpack の style-loader または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' )
) ;コンポーネントには 2 種類の形式があります。
formatsプロパティを使用して有効/無効にするデフォルトの 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 に依存したユースケースがある場合は、問題をオープンすることをお勧めします。それを可能にする新機能、またはそこから移行するための専用サポートを提供するよう努めます。
Quill は長い間、ReactQuill の (非常に柔軟性に欠ける) ツールバー コンポーネントを置き換えるカスタム ツールバーの組み込みサポートを提供してきました。
代わりに、ツールバー モジュールまたは 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 は、この値の動的変更をサポートしていません。代わりに refs と data-attributes を使用してください (#340 を参照)。
modules : 有効にするモジュールとその構成を指定するオブジェクト。エディターのツールバーは、一般的にカスタマイズされるモジュールです。利用可能なモジュールの詳細については、Quille ドキュメントのモジュール セクションを参照してください。
formats : 編集中に有効になるフォーマットの配列。実装されているすべての形式はデフォルトで有効になっています。リストについては、「形式」を参照してください。バージョン 1.0.0 では、カスタム形式を配列に含めないでください。代わりに、Parchment を通じて作成し、モジュールの Quill エクスポートに登録する必要があります。
style : エディターのコンテナーに適用するカスタム CSS ルールを含むオブジェクト。ルールは React の「キャメルケース」命名スタイルである必要があります。
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 ではなく文字数で返します。
