ReactQuill
React的Quill分量。
2025注
您可能不需要此库将Quill与React一起使用。请参阅https://**quilljs.c*om/playground/reeact
查看现场演示或Codepen。
- 快速开始
- 使用webpack或创建反应应用
- 使用浏览器捆绑包
- 用法
- 升级到ReactQuill V2
- 弃用道具
- ReactQuill Mixin
- 工具栏组件
- API参考
- 出口
- 道具
- 方法
- 无私人的编辑
- 建筑和测试
- 浏览器支持
- ChangElog
- 贡献者
- 执照
这是ReactQuill V2的文档 – 先前的版本:V1
ReactQuill V2
ReactQuill 2在这里,宝贝!它为打字稿和反应16+,重构构建系统以及内部逻辑的一般拧紧。
我们努力避免引入任何行为变化。对于绝大多数案件,根本不需要迁移。但是,已删除了对长期剥夺的道具,反应Quill混合蛋白和工具栏组件的支持。确保阅读《迁移指南》。
我们预计此版本将是一个插入升级 – 如果不是这种情况,请提交V2标签问题。
快速开始
使用webpack或创建反应应用
确保您有反应和反应 – 以及某种方式加载样式(例如样式加载器)。有关更多信息,请参见主题的文档。
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://unpk*g*.*com/react-quill@1.3.3/dist/quill.snow.css \" />
< script src =\" https://unpkg.*co**m/react@16/umd/react.development.js \" crossorigin > </ script > < script src =\" https://un*pkg.*c*om/react-dom@16/umd/react-dom.development.js \" crossorigin > </ script > < script src =\" https://un*p*kg*.com/react-quill@1.3.3/dist/react-quill.js \" > </ script > < script src =\" https://unpk*g.c**om/babel-standalone@6/babel.min.js \" > </ script > < script type =\" text/babel \" src =\" /my-scripts.js \" > </ script >
用法
控制模式警告
在受控模式下,组件应该可以防止局部状态变化,而只能通过onchange和value进行。
由于Quill可以处理自己的更改,并且不允许预防编辑,因此ReactQuill必须在受控模式和不受控制的模式之间定居。它不能阻止更改,但是每当价值与当前状态不同时,仍然会覆盖内容。
如果您经常需要操纵DOM或迫切使用Quill API,则可以考虑切换到完全不受控制的模式。 ReactQuill将使用DefaultValue初始化编辑器,但此后不会尝试将其重置。 Onchange回调仍然可以按预期工作。
阅读有关React文档中不受控制的组件的更多信息。
使用三角洲
您可以将Quill Delta(而不是HTML字符串)传递为值和DefaultValue属性。与HTML字符串相比,增量具有许多优势,因此您可能需要使用它们。但是请注意,比较Deltas进行更改要比比较HTML字符串要昂贵,因此可能值得介绍您的使用模式。
请注意,将值从HTML字符串转换为三角洲(反之亦然),无论它们是否代表同一文档,都会触发更改,因此您可能需要遵守格式并在整个过程中继续使用它。
配x请勿将您从Onchange事件收到的Delta对象用作值。该对象不包含完整文档,而只包含最后一个修改,并且这样做很可能会触发无限循环,其中一遍又一遍地应用相同的更改。事件期间使用editor.getContents()获得完整文档的三角洲。 ReactQuill将阻止您犯这样的错误,但是,如果您绝对确定这是您想要的,则可以再次通过New Delta()将对象传递给它以不对。
主题
奎尔编辑器支持主题。它包括一个成熟的主题,称为Snow ,即Quill的标准外观,并且与Medium上的Inline Editor相似。至少,必须包括工具栏或工具提示的模块,必须包括核心主题。
要激活主题,请将主题的名称传递给主题道具。传递虚假值(例如null)以使用核心主题。
< ReactQuill theme = \"snow\" . . . / >
然后,导入要使用的主题的样式表。
这可能取决于应用程序的结构,目录或其他方式。例如,如果您使用CSS预处理器(例如Sass),则可能需要在自己的内部导入该样式。这些样式表可以在Quill分布中找到,但是为了方便起见,它们也可以在ReactQuill的Dist文件夹中链接。
这是使用用于WebPack的样式加载程序或Create-react-app的示例,该示例将自动注入页面上的样式:
import \'react-quill/dist/quill.snow.css\' ;
该样式也可以通过CDN获得:
< link rel =\" stylesheet \" href =\" https://unpk*g*.*com/react-quill@1.3.3/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 ;
HTML工具栏
您还可以提供自己的HTML/JSX工具栏,其中包含不属于Quill主题的自定义元素。
请参阅该示例在Codepen上实时:自定义工具栏示例
示例代码
/* * Custom \"star\" icon for the toolbar using an Octicon * https://octicons.gith***ub.io */ const CustomButton = ( ) => < span className = \"octicon octicon-star\" /> ; /* * Event handler to be attached using Quill toolbar module * http://qu*i*lljs.c*om/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://qu*il*ljs.*com/docs/modules/ for complete options */ Editor . modules = { toolbar : { container : \'#toolbar\' , handlers : { insertStar : insertStar , } , } , } ; /* * Quill editor formats * See http://q*uil*ljs.co*m/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\' ) ) ;
自定义格式
该组件具有两种类型的格式:
- 使用格式prop启用/禁用的默认羽毛笔格式。默认情况下启用所有格式。
- 使用羊皮纸创建并在您的组件的Quill实例上注册的自定义格式
示例代码
import ReactQuill , { Quill } from \'react-quill\' ; // ES6 const ReactQuill = require ( \'react-quill\' ) ; // CommonJS
/* * Example Parchment format from * https://q*ui*ll*js.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,它将为您创建一个<div>,以用作Quill的编辑区域。如果愿意,可以指定自己的元素以供reactquill使用。请注意,目前Quill不支持<textarea>。
注意:使用React 16作为同行DEP(错误)时,自定义编辑区域会失去焦点。
class MyComponent extends React . Component { render ( ) { return ( < ReactQuill > < div className = \"my-editing-area\" /> </ ReactQuill > ) ; } } ) ;
升级到ReactQuill V2
升级到ReactQuill V2应该与更新依赖关系一样简单。但是,它还消除了对长期剥夺的道具,反应Quill Mixin和工具栏组件的支持。
弃用道具
对工具栏,样式,Pollinterval Quill选项的支持长期以来一直禁用。从此版本开始,如果您尝试使用它们,ReactQuill将不再警告您。
ReactQuill Mixin
ReactQuill Mixin允许注入核心功能,使ReactQuill勾选到您自己的组件中,并创建深入定制的版本。
Mixin很长一段时间以来一直被认为是一种反模式,因此我们决定最终确定其贬值。
没有升级路径。如果您有依赖Mixin的用例,则鼓励您打开一个问题,我们将尝试为您提供一项新功能,以使其成为可能,或者专门的支持以迁移。
工具栏组件
长期以来,Quill为定制工具栏提供了内置支持,该工具栏取代了ReactQuill的工具栏组件(非常僵化)。
改用工具栏模块或HTML工具栏功能。
API参考
出口
// ES6 import ReactQuill , { Quill } from \'react-quill\' ; // CommonJS const ReactQuill = require ( \'react-quill\' ) ; const { Quill } = ReactQuill ;
Quill:您可以在其上调用寄存器的Quill名称空间。
道具
ID:要应用于DOM元素的ID。
className:要应用于DOM元素的类。
值:编辑器作为受控组件的值。可以是包含HTML,Quill Delta实例或代表三角洲的普通对象的字符串。请注意,由于Quill的限制,这实际上是一个半控制模式,这意味着不能预防编辑,但是更改值仍将替代内容。另请注意,在此处通过Quill Delta,然后将HTML字符串或反之亦然,无论它们是否代表同一文档,都将始终触发更改。配x不要从onchange事件作为值传递delta对象,因为它会导致循环。有关详细信息,请参见使用三角洲。
DefaultValue:编辑器作为不受控制的组件的初始值。可以是包含HTML,鹅毛笔增量或代表三角洲的普通对象的字符串。
ReadOnly:如果为true,编辑器将不允许更改其内容。包裹Quill禁用API。
占位符:空编辑器的默认值。注意:Quill API不支持动态更改此值。改用Refs和Data-Atributes(请参阅#340)。
模块:指定启用哪些模块及其配置的对象。编辑器工具栏是一个常用的模块。有关Quill文档的“模块”部分,以获取有关可用哪些模块的更多信息。
格式:在编辑过程中启用一系列格式。默认情况下启用了所有实施格式。请参阅列表的格式。从1.0.0版本开始,自定义格式不应包含在数组中。相反,它们应该通过羊皮纸创建,并在模块的Quill导出中注册。
样式:具有自定义CSS规则的对象,可应用于编辑器的容器上。规则应采用React的“骆驼”命名风格。
主题:适用于编辑的主题的名称。默认为Snow,Quill的标准主题。通过NULL使用最小核心主题。有关更多信息,请参见主题上的文档。
TabIndex:在键盘导航期间,在页面中的其他控件中,编辑器专注的顺序。
边界:Quill使用的选择器或DOM元素来约束弹出窗口的位置。默认为document.body。
儿童:一个单一的反应元素将用作羽毛笔代替默认值的编辑区域,即<div>。请注意,您不能使用<textarea>,因为它不是受支持的目标。另请注意,更新儿童是昂贵的,因为这将导致重新创建Quill Editor。如果要控制编辑器的HTML内容,请设置值支柱。
OnChange(内容,Delta,Source,Editor):更改后与编辑器的新内容一起回电。它将通过编辑器的HTML内容,一个表达更改的三角洲对象,更改的来源,最后是读取器访问者(例如Gethtml())。配x请勿将此增量对象用作值,因为它会导致循环。而是使用editor.getContents()。有关详细信息,请参见使用三角洲。
OnChangeSelection(范围,来源,编辑器):与新选择的范围回电,或者在未关注时为NULL。它将通过选择范围,更改的来源,最后是读取器登录器(例如getBounds())。
onfocus(范围,来源,编辑器):编辑器聚焦时调用。它将获得新的选择范围。
Onblur(preatange,source,editor):编辑器失去焦点时调用。它将在失去焦点之前获得其恰到好处的选择范围。
OnKeyPress(事件):按下键并释放键后打电话。 :请注意,与本地对应物一样,这不会被要求使用诸如Shift或Enter之类的特殊键。如果需要的话,请挂在Onkeydown或Onkeyup上。
OnKeyDown(事件):按下键后,但在发布之前呼叫。 :请注意,由于奎尔的工作原理,您可能不会收到诸如Enter , Backspace或Delete之类的键的事件。如果是这种情况,请尝试挂在Onkeyup上。
Onkeyup(事件):键发布后打电话。
preservewhitespace:如果为true,则将预先标签用于编辑区域,而不是默认的DIV标签。这样可以防止羽毛笔在糊状上崩溃。相关问题。
方法
如果您对ReactQuill节点有参考,则可以调用以下方法:
焦点():焦点编辑器。
Blur():从编辑器中删除焦点。
geteditor():返回返回编辑器的Quill实例。虽然您可以自由地使用它来访问诸如getText()之类的方法,但请避免迫切地操纵实例,以免获得ReactQuill和Quill Out-nof Sync。可以作为替代品提供了备受宽松的无私人编辑器。
例子
在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的限制子集。这样可以防止访问破坏性方法,这可能会导致ReactQuill与组件变得不同步。它提供以下方法,这些方法主要是现有Quill方法的代理:
getLength():以字符为单位,返回编辑器内容的长度,而不包括任何HTML标签。
getText():返回编辑器的字符串内容,而不包括任何HTML标签。
GetHtml():返回编辑器的完整HTML内容。
getContents():返回完整文档的鹅毛笔三角洲。
getSelection():返回当前选择范围,或者如果编辑器未关注,则返回null。
getBounds():在给定位置,相对于编辑器容器的编辑容器和选择的尺寸,返回像素位置。
建筑和测试
您可以构建Libs,类型和捆绑包:
npm build # or watch
您还可以运行自动测试套件:
npm test
更多任务可作为软件包脚本提供:
| 脚本 | 描述 |
|---|---|
| NPM运行构建 | 建造Lib和浏览器捆绑包 |
| NPM Run手表 | 重建源代码更改 |
| NPM运行测试 | 运行单位测试和覆盖范围 |
| NPM运行干净 | 清洁制造工件 |
| NPM运行演示 | 提供简单的ReactQuill测试应用程序 |
浏览器支持
请检查浏览器支持表的上游鹅毛笔依赖性。反应Quill可分布本身与ES5兼容。
