react quill
v1.1.0
Eine Quill-Komponente für React.
Sehen Sie sich eine Live-Demo oder Codepen an.
Dies ist die Dokumentation für ReactQuill v2 – Frühere Versionen: v1
? ReactQuill v2
ReactQuill 2 ist da, Baby! Und es bringt eine vollständige Portierung auf TypeScript und React 16+, ein überarbeitetes Build-System und eine allgemeine Verschärfung der internen Logik.
Wir haben hart daran gearbeitet, Verhaltensänderungen zu vermeiden. In den allermeisten Fällen ist überhaupt keine Migration erforderlich. Allerdings wurde die Unterstützung für seit langem veraltete Requisiten, das ReactQuill Mixin und die Toolbar-Komponente entfernt. Lesen Sie unbedingt den Migrationsleitfaden.
Wir gehen davon aus, dass es sich bei dieser Version um ein Drop-in-Upgrade handelt. Wenn dies nicht der Fall ist, melden Sie bitte ein Problem mit dem v2 -Label.
Stellen Sie sicher, dass Sie react und react-dom sowie eine Möglichkeit zum Laden von Stilen haben, z. B. „Style-Loader“. Weitere Informationen finden Sie in der Dokumentation zu Themen.
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 > Im kontrollierten Modus sollen Komponenten lokale Zustandsänderungen verhindern und diese stattdessen nur über onChange und value durchführen.
Da Quill seine eigenen Änderungen verarbeitet und das Verhindern von Änderungen nicht zulässt, muss sich ReactQuill mit einer Mischung aus kontrolliertem und unkontrolliertem Modus zufrieden geben. Die Änderung kann zwar nicht verhindert werden, der Inhalt wird aber dennoch überschrieben, wenn value vom aktuellen Status abweicht.
Wenn Sie das DOM häufig manipulieren oder die Quill-APIs zwingend verwenden müssen, sollten Sie einen Wechsel in den vollständig unkontrollierten Modus in Betracht ziehen. ReactQuill initialisiert den Editor mit defaultValue , versucht jedoch nicht, ihn danach zurückzusetzen. Der onChange Rückruf funktioniert weiterhin wie erwartet.
Weitere Informationen zu unkontrollierten Komponenten finden Sie in den React-Dokumenten.
Sie können ein Quill Delta anstelle einer HTML-Zeichenfolge als value und defaultValue übergeben. Deltas haben gegenüber HTML-Strings eine Reihe von Vorteilen, weshalb Sie sie möglicherweise stattdessen verwenden möchten. Beachten Sie jedoch, dass der Vergleich von Deltas für Änderungen teurer ist als der Vergleich von HTML-Strings. Daher kann es sich lohnen, ein Profil Ihrer Nutzungsmuster zu erstellen.
Beachten Sie, dass der Wechsel value von einer HTML-Zeichenfolge zu einer Delta-Zeichenfolge oder umgekehrt eine Änderung auslöst, unabhängig davon, ob sie dasselbe Dokument darstellen. Daher sollten Sie bei einem Format bleiben und es durchgehend konsistent verwenden.
delta -Objekt, das Sie vom onChange Ereignis erhalten, als value . Dieses Objekt enthält nicht das gesamte Dokument, sondern nur die letzten Änderungen. Dadurch wird höchstwahrscheinlich eine Endlosschleife ausgelöst, in der dieselben Änderungen immer wieder angewendet werden. Verwenden Sie während des Ereignisses editor.getContents() um stattdessen ein Delta des vollständigen Dokuments zu erhalten. ReactQuill verhindert, dass Sie einen solchen Fehler machen. Wenn Sie jedoch absolut sicher sind, dass dies das ist, was Sie wollen, können Sie das Objekt erneut durch new Delta() leiten, um es von der Verunreinigung zu befreien.
Der Quill-Editor unterstützt Themen. Es enthält ein vollwertiges Thema namens „Snow“ , das Quills Standarderscheinung entspricht, und ein Blasenthema , das dem Inline-Editor auf Medium ähnelt. Zumindest muss das Kernthema enthalten sein, damit Module wie Symbolleisten oder Tooltips funktionieren.
Um ein Theme zu aktivieren, übergeben Sie den Namen des Themes an die theme Requisite. Übergeben Sie einen falschen Wert (z. B. null ), um das Kernthema zu verwenden.
< ReactQuill theme = "snow" . . . / >Importieren Sie dann das Stylesheet für die Themes, die Sie verwenden möchten.
Dies kann je nach Struktur der Anwendung, Verzeichnissen usw. variieren. Wenn Sie beispielsweise einen CSS-Präprozessor wie SASS verwenden, möchten Sie dieses Stylesheet möglicherweise in Ihr eigenes importieren. Diese Stylesheets sind in der Quill-Distribution zu finden, der Einfachheit halber sind sie aber auch im dist Ordner von ReactQuill verlinkt.
Hier ist ein Beispiel für die Verwendung von style-loader für Webpack oder create-react-app , das die Stile automatisch auf der Seite einfügt:
import 'react-quill/dist/quill.snow.css' ;Die Styles sind auch über CDN verfügbar:
< link
rel =" stylesheet "
href =" https://unpkg.com/[email protected]/dist/quill.snow.css "
/>Die Quill Toolbar Module API bietet eine einfache Möglichkeit, die Standard-Symbolleistensymbole mithilfe einer Reihe von Formatnamen zu konfigurieren.
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 ; Sie können auch Ihre eigene HTML/JSX-Symbolleiste mit benutzerdefinierten Elementen bereitstellen, die nicht Teil des Quill-Designs sind.
Sehen Sie sich dieses Beispiel live auf Codepen an: Beispiel für eine benutzerdefinierte Symbolleiste
/*
* 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' )
) ;Die Komponente verfügt über zwei Arten von Formaten:
formats Requisite aktiviert/deaktiviert werden. Alle Formate sind standardmäßig aktiviert. 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 }
/ >
) ;
}
} Wenn Sie ReactQuill ohne untergeordnete Elemente instanziieren, wird für Sie ein <div> erstellt, das als Bearbeitungsbereich für Quill verwendet wird. Wenn Sie möchten, können Sie Ihr eigenes Element angeben, das ReactQuill verwenden soll. Beachten Sie, dass <textarea> s derzeit von Quill nicht unterstützt werden.
Hinweis: Benutzerdefinierte Bearbeitungsbereiche verlieren derzeit den Fokus, wenn React 16 als Peer-Dep verwendet wird (Fehler).
class MyComponent extends React . Component {
render ( ) {
return (
< ReactQuill >
< div className = "my-editing-area" / >
< / ReactQuill >
) ;
}
} ) ; Das Upgrade auf ReactQuill v2 sollte so einfach sein wie das Aktualisieren Ihrer Abhängigkeit. Es entfernt jedoch auch die Unterstützung für seit langem veraltete Requisiten, das ReactQuill Mixin und die Toolbar-Komponente.
Die Unterstützung für die Optionen toolbar , styles und pollInterval Quill ist seit langem deaktiviert. Ab dieser Version warnt Sie ReactQuill nicht mehr, wenn Sie versuchen, sie zu verwenden.
Mit dem ReactQuill-Mixin konnten Sie die Kernfunktionalität, die ReactQuill ausmachte, in Ihre eigenen Komponenten integrieren und stark angepasste Versionen erstellen.
Das Mixin galt schon lange als Anti-Pattern, daher haben wir beschlossen, seine Abwertung abzuschließen.
Es gibt keinen Upgrade-Pfad. Wenn Sie einen Anwendungsfall haben, der auf Mixin basiert, werden Sie dazu ermutigt, ein Problem zu eröffnen. Wir werden dann versuchen, Ihnen eine neue Funktion zur Verfügung zu stellen, die dies ermöglicht, oder dedizierten Support für die Migration bereitzustellen.
Quill bietet seit langem integrierte Unterstützung für benutzerdefinierte Symbolleisten, die die (ziemlich unflexible) Toolbar-Komponente von ReactQuill ersetzt.
Verwenden Sie stattdessen das Toolbar-Modul oder die HTML-Toolbar-Funktion.
// ES6
import ReactQuill , { Quill } from 'react-quill' ;
// CommonJS
const ReactQuill = require ( 'react-quill' ) ;
const { Quill } = ReactQuill ; Quill : Der Quill -Namespace, in dem Sie register aufrufen können.
id : ID, die auf das DOM-Element angewendet werden soll.
className : Klassen, die auf das DOM-Element angewendet werden sollen.
value : Wert für den Editor als kontrollierte Komponente. Kann eine Zeichenfolge sein, die HTML enthält, eine Quill-Delta-Instanz oder ein einfaches Objekt, das ein Delta darstellt. Beachten Sie, dass es sich aufgrund von Einschränkungen in Quill tatsächlich um einen halbgesteuerten Modus handelt, was bedeutet, dass die Bearbeitung nicht verhindert wird, der Inhalt jedoch durch Ändern des value ersetzt wird. Beachten Sie außerdem, dass die Übergabe eines Quill Delta hier und dann einer HTML-Zeichenfolge oder umgekehrt immer eine Änderung auslöst, unabhängig davon, ob sie dasselbe Dokument darstellen.delta Objekt des onChange Ereignisses nicht als value , da dies zu einer Schleife führt. Weitere Informationen finden Sie unter Verwenden von Deltas.
defaultValue : Initialwert für den Editor als unkontrollierte Komponente. Kann eine Zeichenfolge sein, die HTML enthält, ein Quill-Delta oder ein einfaches Objekt, das ein Delta darstellt.
readOnly : Wenn true, lässt der Editor keine Änderung seines Inhalts zu. Umschließt die Quill- disable -API.
placeholder : Der Standardwert für den leeren Editor. Hinweis: Die Quill-API unterstützt keine dynamische Änderung dieses Werts. Verwenden Sie stattdessen Refs und Datenattribute (siehe #340).
modules : Ein Objekt, das angibt, welche Module aktiviert sind und wie sie konfiguriert sind. Die Editor-Symbolleiste ist ein häufig angepasstes Modul. Weitere Informationen zu den verfügbaren Modulen finden Sie im Abschnitt „Module“ in der Quill-Dokumentation.
formats : Ein Array von Formaten, die während der Bearbeitung aktiviert werden sollen. Alle implementierten Formate sind standardmäßig aktiviert. Eine Liste finden Sie unter Formate. Benutzerdefinierte Formate sollten ab Version 1.0.0 nicht mehr im Array enthalten sein. Stattdessen sollten sie über Pergament erstellt und beim Quill-Export des Moduls registriert werden.
style : Ein Objekt mit benutzerdefinierten CSS-Regeln, die auf den Container des Editors angewendet werden sollen. Regeln sollten im Namensstil „camelCased“ von React vorliegen.
theme : Der Name des Themes, das auf den Editor angewendet werden soll. Standardmäßig ist snow , das Standardthema von Quill, eingestellt. Übergeben Sie null um das minimale Kernthema zu verwenden. Weitere Informationen zum Einbinden der erforderlichen Stylesheets finden Sie in den Dokumenten zu Themes.
tabIndex : Die Reihenfolge, in der der Editor neben anderen Steuerelementen auf der Seite während der Tastaturnavigation den Fokus erhält.
bounds : Selektor oder DOM-Element, das von Quill verwendet wird, um die Position von Popups einzuschränken. Standardmäßig ist document.body .
children : Ein einzelnes React-Element, das als Bearbeitungsbereich für Quill anstelle des Standardelements verwendet wird, bei dem es sich um ein <div> handelt. Beachten Sie, dass Sie kein <textarea> verwenden können, da es sich nicht um ein unterstütztes Ziel handelt. Beachten Sie außerdem, dass das Aktualisieren untergeordneter Elemente kostspielig ist, da dadurch der Quill-Editor neu erstellt werden muss. Legen Sie den value prop fest, wenn Sie den HTML-Inhalt des Editors steuern möchten.
onChange(content, delta, source, editor) : Wird nach der Änderung mit den neuen Inhalten des Editors zurückgerufen. Es werden der HTML-Inhalt des Editors, ein Delta-Objekt, das die Änderung ausdrückt, die Quelle der Änderung und schließlich ein schreibgeschützter Proxy an Editor-Accessoren wie getHTML() übergeben.delta Objekt nicht als value , da dies zu einer Schleife führt. Verwenden Sie stattdessen editor.getContents() . Weitere Informationen finden Sie unter Verwenden von Deltas.
onChangeSelection(range, source, editor) : Wird mit dem neu ausgewählten Bereich zurückgerufen oder null, wenn der Fokus nicht vorhanden ist. Es werden der Auswahlbereich, die Quelle der Änderung und schließlich ein schreibgeschützter Proxy an Editor-Accessoren wie getBounds() übergeben.
onFocus(range, source, editor) : Wird aufgerufen, wenn der Editor fokussiert wird. Es erhält den neuen Auswahlbereich.
onBlur(previousRange, source, editor) : Wird aufgerufen, wenn der Editor den Fokus verliert. Es erhält den Auswahlbereich, den es hatte, bevor es den Fokus verlor.
onKeyPress(event) : Wird aufgerufen, nachdem eine Taste gedrückt und losgelassen wurde. : Beachten Sie, dass dies, wie sein natives Gegenstück, nicht für Sondertasten wie Shift oder Enter aufgerufen wird. Wenn Sie diese benötigen, schließen Sie sich an onKeyDown oder onKeyUp an.
onKeyDown(event) : Wird aufgerufen, nachdem eine Taste gedrückt wurde, aber bevor sie losgelassen wird. : Beachten Sie, dass es aufgrund der Funktionsweise von Quill möglich ist, dass Sie keine Ereignisse für Tasten wie enter , backspace oder delete erhalten. Wenn das der Fall ist, versuchen Sie stattdessen onKeyUp zu nutzen.
onKeyUp(event) : Wird aufgerufen, nachdem eine Taste losgelassen wurde.
preserveWhitespace : Wenn true, wird anstelle des Standard- div Tags ein pre Tag für den Editorbereich verwendet. Dies verhindert, dass Quill fortlaufende Leerzeichen beim Einfügen reduziert. Verwandtes Problem.
Wenn Sie einen Verweis auf einen ReactQuill-Knoten haben, können Sie die folgenden Methoden aufrufen:
focus() : Fokussiert den Editor.
blur() : Entfernt den Fokus vom Editor.
getEditor() : Gibt die Quill-Instanz zurück, die den Editor unterstützt. Sie können dies zwar frei verwenden, um auf Methoden wie getText() zuzugreifen, aber vermeiden Sie es bitte, die Instanz zwingend zu manipulieren, um zu vermeiden, dass ReactQuill und Quill nicht mehr synchron sind. Als Ersatz steht ein wesentlich sichererer unprivilegierter Editor zur Verfügung.
Sehen Sie sich dieses Beispiel auf Codepen an
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 : Erstellt einen nicht privilegierten Editor. Übergeben Sie dieser Methode einen Verweis auf die Quill-Instanz von getEditor . Normalerweise müssen Sie diese Methode nicht verwenden, da der Editor, der Event-Handlern ausgesetzt ist, bereits nicht privilegiert ist.
const editor = this . reactQuillRef . getEditor ( ) ;
const unprivilegedEditor = this . reactQuillRef . makeUnprivilegedEditor ( editor ) ;
// You may now use the unprivilegedEditor proxy methods
unprivilegedEditor . getText ( ) ; Bei Ereignissen stellt ReactQuill eine eingeschränkte Teilmenge der Quill-API als editor Argument zur Verfügung. Dadurch wird der Zugriff auf destruktive Methoden verhindert, was dazu führen könnte, dass ReactQuill nicht mehr mit der Komponente synchronisiert ist. Es stellt die folgenden Methoden bereit, bei denen es sich größtenteils um Proxys bestehender Quill-Methoden handelt:
getLength() : Gibt die Länge des Editorinhalts in Zeichen zurück, nicht in Inc
