react quill
v1.1.0
Komponen Quill untuk React.
Lihat demo langsung atau Codepen.
Ini adalah dokumentasi untuk ReactQuill v2 — Rilisan sebelumnya: v1
? ReactQuill v2
ReactQuill 2 telah hadir, sayang! Dan ini menghadirkan port lengkap ke TypeScript dan React 16+, sistem build yang telah difaktorkan ulang, dan pengetatan logika internal secara umum.
Kami bekerja keras untuk menghindari perubahan perilaku apa pun. Pada sebagian besar kasus, migrasi tidak diperlukan sama sekali. Namun, dukungan untuk props yang sudah lama tidak digunakan lagi, ReactQuill Mixin, dan komponen Toolbar telah dihapus. Pastikan untuk membaca panduan migrasi.
Kami berharap rilis ini merupakan upgrade drop-in – jika bukan itu masalahnya, harap ajukan masalah dengan label v2 .
Pastikan Anda memiliki react dan react-dom , dan beberapa cara untuk memuat gaya, seperti style-loader. Lihat dokumentasi tema untuk informasi lebih lanjut.
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 > Dalam mode terkontrol, komponen seharusnya mencegah perubahan stateful lokal, dan hanya membuat perubahan tersebut terjadi melalui onChange dan value .
Karena Quill menangani perubahannya sendiri, dan tidak mengizinkan pencegahan pengeditan, ReactQuill harus memilih gabungan antara mode terkontrol dan tidak terkontrol. Ini tidak dapat mencegah perubahan, namun akan tetap menimpa konten setiap kali value berbeda dari keadaan saat ini.
Jika Anda sering perlu memanipulasi DOM atau menggunakan Quill API secara mendesak, Anda mungkin mempertimbangkan untuk beralih ke mode yang sepenuhnya tidak terkontrol. ReactQuill akan menginisialisasi editor menggunakan defaultValue , tetapi tidak akan mencoba mengatur ulang setelah itu. Callback onChange akan tetap berfungsi seperti yang diharapkan.
Baca selengkapnya tentang komponen yang tidak terkontrol di dokumen React.
Anda dapat meneruskan Quill Delta, alih-alih string HTML, sebagai properti value dan defaultValue . Delta memiliki sejumlah keunggulan dibandingkan string HTML, jadi Anda mungkin ingin menggunakannya. Namun perlu diingat bahwa membandingkan Delta untuk perubahan lebih mahal dibandingkan membandingkan string HTML, jadi mungkin ada baiknya untuk membuat profil pola penggunaan Anda.
Perhatikan bahwa peralihan value dari string HTML ke Delta, atau sebaliknya, akan memicu perubahan, terlepas dari apakah nilai tersebut mewakili dokumen yang sama, jadi Anda mungkin ingin tetap menggunakan format dan terus menggunakannya secara konsisten.
delta yang Anda terima dari acara onChange sebagai value . Objek ini tidak berisi dokumen lengkap, tetapi hanya modifikasi terakhir, dan hal ini kemungkinan besar akan memicu loop tak terbatas di mana perubahan yang sama diterapkan berulang kali. Gunakan editor.getContents() selama acara untuk mendapatkan Delta dari dokumen lengkap. ReactQuill akan mencegah Anda melakukan kesalahan seperti itu, namun jika Anda benar-benar yakin bahwa ini yang Anda inginkan, Anda dapat meneruskan objek melalui new Delta() lagi untuk menghilangkan nodanya.
Editor Quill mendukung tema. Ini mencakup tema lengkap, yang disebut salju , yang merupakan tampilan standar Quill, dan tema gelembung yang mirip dengan editor sebaris di Medium. Paling tidak, tema inti harus disertakan agar modul seperti toolbar atau tooltip dapat berfungsi.
Untuk mengaktifkan tema, teruskan nama tema ke prop theme . Berikan nilai palsu (mis. null ) untuk menggunakan tema inti.
< ReactQuill theme = "snow" . . . / >Lalu, impor stylesheet untuk tema yang ingin Anda gunakan.
Ini mungkin berbeda tergantung bagaimana aplikasi disusun, direktori atau lainnya. Misalnya, jika Anda menggunakan pra-prosesor CSS seperti SASS, Anda mungkin ingin mengimpor stylesheet tersebut ke dalam stylesheet Anda sendiri. Stylesheet ini dapat ditemukan di distribusi Quill, namun untuk kenyamanan, stylesheet ini juga ditautkan ke folder dist ReactQuill.
Berikut ini contoh penggunaan style-loader untuk Webpack, atau create-react-app , yang secara otomatis akan memasukkan gaya pada halaman:
import 'react-quill/dist/quill.snow.css' ;Gaya juga tersedia melalui CDN:
< link
rel =" stylesheet "
href =" https://unpkg.com/[email protected]/dist/quill.snow.css "
/>API Modul Quill Toolbar menyediakan cara mudah untuk mengonfigurasi ikon toolbar default menggunakan serangkaian nama format.
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 ; Anda juga dapat menyediakan toolbar HTML/JSX Anda sendiri dengan elemen khusus yang bukan bagian dari tema Quill.
Lihat contoh ini langsung di Codepen: Contoh Toolbar Kustom
/*
* 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' )
) ;Komponen memiliki dua jenis format:
formats . Semua format diaktifkan secara default. 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 }
/ >
) ;
}
} Jika Anda membuat instance ReactQuill tanpa anak, itu akan membuat <div> untuk Anda, untuk digunakan sebagai area pengeditan untuk Quill. Jika mau, Anda dapat menentukan elemen Anda sendiri untuk digunakan ReactQuill. Perhatikan bahwa <textarea> s tidak didukung oleh Quill saat ini.
Catatan: Area pengeditan khusus kehilangan fokus saat menggunakan React 16 sebagai peer dep saat ini (bug).
class MyComponent extends React . Component {
render ( ) {
return (
< ReactQuill >
< div className = "my-editing-area" / >
< / ReactQuill >
) ;
}
} ) ; Mengupgrade ke ReactQuill v2 semudah memperbarui ketergantungan Anda. Namun, ini juga menghapus dukungan untuk props yang sudah lama tidak digunakan lagi, ReactQuill Mixin, dan komponen Toolbar.
Dukungan untuk toolbar , styles , opsi pollInterval Quill telah lama dinonaktifkan. Mulai rilis ini, ReactQuill tidak akan memperingatkan Anda lagi jika Anda mencoba menggunakannya.
ReactQuill Mixin memungkinkan memasukkan fungsionalitas inti yang membuat ReactQuill cocok ke dalam komponen Anda sendiri, dan membuat versi yang sangat disesuaikan.
Mixin telah lama dianggap sebagai anti-pola, jadi kami memutuskan untuk menyelesaikan penghentian penggunaannya.
Tidak ada jalur peningkatan. Jika Anda memiliki kasus penggunaan yang mengandalkan Mixin, Anda dianjurkan untuk membuka masalah, dan kami akan mencoba memberi Anda fitur baru untuk memungkinkannya, atau dukungan khusus untuk bermigrasi keluar dari masalah tersebut.
Quill telah lama menyediakan dukungan bawaan untuk toolbar kustom, yang menggantikan komponen Toolbar ReactQuill (yang cukup tidak fleksibel).
Gunakan Modul Toolbar atau fitur Toolbar HTML sebagai gantinya.
// ES6
import ReactQuill , { Quill } from 'react-quill' ;
// CommonJS
const ReactQuill = require ( 'react-quill' ) ;
const { Quill } = ReactQuill ; Quill : Namespace Quill yang dapat Anda panggil register .
id : ID yang akan diterapkan ke elemen DOM.
className : Kelas yang akan diterapkan ke elemen DOM.
value : Nilai untuk editor sebagai komponen yang dikontrol. Dapat berupa string yang berisi HTML, instance Quill Delta, atau objek biasa yang mewakili Delta. Perhatikan bahwa karena keterbatasan dalam Quill, ini sebenarnya adalah mode semi-terkontrol , artinya pengeditan tidak dicegah, namun perubahan value akan tetap menggantikan konten. Perhatikan juga bahwa meneruskan Quill Delta di sini, lalu string HTML, atau sebaliknya, akan selalu memicu perubahan, terlepas dari apakah keduanya mewakili dokumen yang sama.delta dari acara onChange sebagai value , karena akan menyebabkan perulangan. Lihat Menggunakan Delta untuk detailnya.
defaultValue : Nilai awal untuk editor sebagai komponen yang tidak terkontrol. Dapat berupa string yang berisi HTML, Quill Delta, atau objek biasa yang mewakili Delta.
readOnly : Jika benar, editor tidak akan mengizinkan perubahan konten. Membungkus API disable Quill.
placeholder : Nilai default untuk editor kosong. Catatan: Quill API tidak mendukung perubahan nilai ini secara dinamis. Gunakan referensi dan atribut data sebagai gantinya (lihat #340).
modules : Objek yang menentukan modul mana yang diaktifkan, dan konfigurasinya. Toolbar editor adalah modul yang umumnya dikustomisasi. Lihat bagian modul pada dokumentasi Quill untuk informasi lebih lanjut tentang modul apa saja yang tersedia.
formats : Serangkaian format yang akan diaktifkan selama pengeditan. Semua format yang diterapkan diaktifkan secara default. Lihat Format untuk daftarnya. Format khusus tidak boleh disertakan dalam array pada versi 1.0.0. Sebaliknya mereka harus dibuat melalui Perkamen dan didaftarkan dengan ekspor Quill modul.
style : Sebuah objek dengan aturan CSS khusus untuk diterapkan pada wadah editor. Aturan harus menggunakan gaya penamaan "camelCased" React.
theme : Nama tema yang akan diterapkan pada editor. Defaultnya adalah snow , tema standar Quill. Berikan null untuk menggunakan tema inti minimal. Lihat dokumen tentang tema untuk informasi lebih lanjut tentang penyertaan stylesheet yang diperlukan.
tabIndex : Urutan fokus editor, di antara kontrol lain di halaman, selama navigasi keyboard.
bounds : Pemilih atau elemen DOM yang digunakan oleh Quill untuk membatasi posisi popup. Defaultnya adalah document.body .
children : Satu elemen React yang akan digunakan sebagai area pengeditan untuk Quill sebagai pengganti elemen default, yaitu <div> . Perhatikan bahwa Anda tidak dapat menggunakan <textarea> , karena ini bukan target yang didukung. Perhatikan juga bahwa memperbarui anak-anak itu mahal, karena akan menyebabkan editor Quill dibuat ulang. Tetapkan value prop jika Anda ingin mengontrol konten html editor.
onChange(content, delta, source, editor) : Dipanggil kembali dengan konten baru editor setelah perubahan. Ini akan meneruskan konten HTML editor, objek delta yang menyatakan perubahan, sumber perubahan, dan akhirnya proxy read-only ke pengakses editor seperti getHTML() .delta ini sebagai value , karena akan menyebabkan perulangan. Gunakan editor.getContents() sebagai gantinya. Lihat Menggunakan Delta untuk detailnya.
onChangeSelection(range, source, editor) : Dipanggil kembali dengan rentang baru yang dipilih, atau null saat tidak fokus. Ini akan meneruskan rentang pilihan, sumber perubahan, dan akhirnya proksi hanya-baca ke pengakses editor seperti getBounds() .
onFocus(range, source, editor) : Dipanggil ketika editor menjadi fokus. Ini akan menerima rentang pilihan baru.
onBlur(previousRange, source, editor) : Dipanggil ketika editor kehilangan fokus. Ia akan menerima rentang pilihan yang dimilikinya tepat sebelum kehilangan fokus.
onKeyPress(event) : Dipanggil setelah tombol ditekan dan dilepaskan. : Perhatikan bahwa, seperti padanan aslinya, ini tidak akan dipanggil untuk kunci khusus seperti shift atau enter . Jika Anda membutuhkannya, sambungkan ke onKeyDown atau onKeyUp .
onKeyDown(event) : Dipanggil setelah tombol ditekan, namun sebelum dilepaskan. : Perhatikan bahwa, karena cara kerja Quill, ada kemungkinan Anda tidak akan menerima event untuk kunci seperti enter , backspace atau delete . Jika demikian, coba sambungkan ke onKeyUp saja.
onKeyUp(event) : Dipanggil setelah kunci dilepaskan.
preserveWhitespace : Jika benar, tag pre digunakan untuk area editor, bukan tag div default. Hal ini mencegah Quill menciutkan spasi terus-menerus pada pasta. Masalah terkait.
Jika Anda memiliki referensi ke node ReactQuill, Anda dapat menjalankan metode berikut:
focus() : Memfokuskan editor.
blur() : Menghapus fokus dari editor.
getEditor() : Mengembalikan instance Quill yang mendukung editor. Meskipun Anda dapat dengan bebas menggunakan ini untuk mengakses metode seperti getText() , harap hindari memanipulasi instance secara imperatif, untuk menghindari ketidaksinkronan ReactQuill dan Quill. Editor tanpa hak istimewa yang jauh lebih aman tersedia sebagai penggantinya.
Lihat contoh ini di 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 : Membuat editor yang tidak memiliki hak istimewa. Berikan metode ini referensi ke instance Quill dari getEditor . Biasanya Anda tidak perlu menggunakan metode ini karena editor yang diekspos ke event handler sudah tidak memiliki hak istimewa.
const editor = this . reactQuillRef . getEditor ( ) ;
const unprivilegedEditor = this . reactQuillRef . makeUnprivilegedEditor ( editor ) ;
// You may now use the unprivilegedEditor proxy methods
unprivilegedEditor . getText ( ) ; Selama event, ReactQuill akan membuat subset terbatas dari Quill API tersedia sebagai argumen editor . Hal ini mencegah akses ke metode destruktif, yang mungkin menyebabkan ReactQuill tidak sinkron dengan komponen. Ini menyediakan metode berikut, yang sebagian besar merupakan proksi dari metode Quill yang ada:
getLength() : Mengembalikan panjang konten editor, dalam karakter, bukan inc
