以下是编辑器的所有属性列表
属性名
类型
说明
EditorState
编辑器的内容
EditorState
编辑器的初始化内容,仅首次传入生效
placeholder
String
指定Placeholder文本
readOnly
Boolean
指定编辑器是否只读
String
编辑器的语言
Array[String|Object]
编辑器的工具栏控件列表
Array[String]
不在工具栏显示的控件列表
Array[Object]
自定义的控件列表
React Component
在工具栏和编辑区域之间显示的组件
Object
编辑器的多媒体功能配置,包括上传功能
Array[String|Object]
编辑器内的图片工具栏控件
Array[String]
编辑器可用颜色列表
Array[Number]
编辑器可用的字号列表
Array[Object]
编辑器可用的字体列表
Array[Number]
编辑器可用的行高列表
Array[String]
编辑器可用的文本对齐方式
Array[Number]
编辑器可用的字间距列表
Array[String]
编辑器可用的Emoji列表
textBackgroundColor
Boolean
是否允许设置文字背景颜色
stripPastedStyles
Boolean
是否以纯文本模式粘贴内容,默认为false
className
String
编辑器的样式名
style
Object
编辑器的内联样式
controlBarClassName
String
编辑器工具栏的样式名
controlBarStyle
Object
编辑器工具栏的内联样式
contentClassName
String
编辑器编辑区域容器的样式名
contentStyle
Object
编辑器编辑区域容器的内联样式
Object
直接传给DraftJS的Editor组件的属性
onChange
Function(editorState)
编辑器内容发生变化时的回调函数
onFocus
Function
编辑器获得焦点时触发的函数
onBlur
Function
编辑器失去焦点时触发的函数
onTab
Function
在编辑器内按下Tab键时触发的函数
onDelete
Function
在编辑器内按下删除键时触发的函数
onSave
Function
在编辑器内按下Command/Ctrl + s时触发的函数
Object
编辑器的行为钩子属性

value

value属性用于指定编辑器的内容,需要传入一个editorState对象,可以通过下面的方式来创建editorState对象:
import BraftEditor from 'braft-editor'
// 定义一段HTML字符串
const htmlString = `<p>Hello <b>World!</b></p>`
// 将HTML字符串转换为编辑器所需要的EditorState实例
const editorState = BraftEditor.createEditorState(htmlString)
//上面创建的变量editorState即可传给编辑器的value属性
render () {
    return (
        <BraftEditor value={editorState}/>
    )
}

defaultValue

defaultValue属性与value属性类似,但是它只在首次传入有效editorState时生效,用于指定编辑器的默认内容。如果需要异步或动态修改编辑器的内容,推荐使用value属性。

language

指定编辑器的显示语言,目前支持zh、zh-hant和en,即简体中文、繁体中文和英文,默认为简体中文。
此外language属性还支持传入一个函数,用于更自由的定制语言:
const languageFn = (languages, context) => {

  // languages参数中可以拿到编辑器内置的所有语言数据
 ​ // context参数则表明时哪一个组件在调用此函数,目前的可能值为braft-editor或braft-finder
  // braft-finder是编辑器的媒体库组件,它使用独立的语言配置文件,为此需要在此处根据context区分

  if (context === 'braft-editor') {
    languages.zh.controls.clear = '清空'
    return languages.zh
  }

}

controls

指定编辑器工具栏的控件列表,默认值如下:
[
    'undo', 'redo', 'separator',
    'font-size', 'line-height', 'letter-spacing', 'separator',
    'text-color', 'bold', 'italic', 'underline', 'strike-through', 'separator',
    'superscript', 'subscript', 'remove-styles', 'emoji',  'separator', 'text-indent', 'text-align', 'separator',
    'headings', 'list-ul', 'list-ol', 'blockquote', 'code', 'separator',
    'link', 'separator', 'hr', 'separator',
    'media', 'separator',
    'clear'
]
下表为编辑器的所有内置控件名称:
名称
说明
font-size
文字字号选择器
font-family
文字字体选择器
line-height
文字行高选择器
letter-spacing
文字字间距选择器
text-color
文字颜色选择器,包含文字背景颜色设置
bold
设置文字加粗
italic
设置文字斜体
underline
设置文字下划线
strike-through
设置文字删除线
superscript
设置文字为上标
subscript
设置文字为下标
remove-styles
清除文字样式
emoji
Emoji表情选择器
text-align
文字对齐方式工具,可通过textAligns属性来指定可以使用哪些对齐方式
text-indent
段落缩进工具,最多可缩进6级
link
链接插入工具
hr
水平线工具
media
多媒体插入工具
clear
内容清除工具
undo
撤销操作
redo
重做操作
separator
分割线,连续的多个separator将只显示为1个
controls数组的元素除了可以是上表中的控件名称外,还可以是一个对象,通过这个对象可以更加自由地定制控件,示例:
const controls = [
    'undo', 'redo', 'separator',
    {
        key: 'bold', // 使用key来指定控件类型
        title: '加粗选中文字哦', // 自定义控件title
        text: '点我加粗', // 使用自定义文案来代替默认图标(B),此处也可传入jsx
    },
    'italic', 'underline', 'strike-through'
]
通过下面的示例可以自定义默认控件中的某一项:
const controls = BraftEditor.defaultProps.controls.map(item => {
  return item === 'bold' ? {
    key: 'bold', // 使用key来指定控件类型
    title: '加粗选中文字哦', // 自定义控件title
    text: '点我加粗', // 使用自定义文案来代替默认图标(B),此处也可传入jsx
  } : item
})
// 通过BraftEditor.defaultProps可以获取到编辑器的默认属性,在很多场景都有用处
<BraftEditor controls={controls}/>

excludeControls

指定不需要展示的控件,示例:
// 不显示加粗控件、斜体控件和下划线控件
const excludeControls = ['bold', 'italic', 'underline']
<BraftEditor excludeControls={excludeControls}/>

extendControls

指定自定义的控件,目前支持button、dropdown、modal和component这四种类型,具体配置请见下方示例。
自定义的控件将会紧随内置控件展示在编辑器的工具栏上。此外,在extendControls也可使用separator来显示分割线。

button

在工具栏中新增一个按钮,其文案和点击行为都可自定义:
const extendControls = [
    'separator',
    {
        key: 'my-button', // 控件唯一标识,必传
        type: 'button',
        title: '这是一个自定义的按钮', // 指定鼠标悬停提示文案
        className: 'my-button', // 指定按钮的样式名
        html: null, // 指定在按钮中渲染的html字符串
        text: 'Hello', // 指定按钮文字,此处可传入jsx,若已指定html,则text不会显示
        onClick: () => {
            console.log('Hello World!');
        },
    }
]

dropdown

在工具栏中新增一个下拉组件触发按钮,点击之后可弹出一个下拉组件:
const extendControls = [
    'separator',
    {
        key: 'my-dropdown',
        type: 'dropdown',
        title: '这是一个自定义的下拉组件', // 指定鼠标悬停提示文案
        className: 'my-dropdown', // 指定下拉组件容器的样式名
        html: null, // 指定在按钮中渲染的html字符串
        text: 'Hello', // 指定按钮文字,此处可传入jsx,若已指定html,则text不会显示
        showArrow: true, // 指定是否显示下拉组件顶部的小三角形
        arrowActive: false, // 指定是否高亮下拉组件顶部的小三角形
        autoHide: true, // 指定是否在失去焦点时自动隐藏下拉组件
        component: <MyComponent />, // 指定在下拉组件中显示的内容组件
    }
]

modal

在工具栏中新增一个弹窗组件触发按钮,点击之后可弹出一个弹窗组件:
const extendControls = [
    'separator',
    {
        key: 'my-modal',
        type: 'modal',
        title: '这是一个自定义的下拉组件', // 指定鼠标悬停提示文案
        className: 'my-modal', // 指定触发按钮的样式名
        html: null, // 指定在按钮中渲染的html字符串
        text: 'Hello', // 指定按钮文字,此处可传入jsx,若已指定html,则text不会显示    
        onClick: () => {}, // 指定触发按钮点击后的回调函数
        modal: {
            id: 'my-modal', // 必选属性,传入一个唯一字符串即可
            title: '我的弹窗', // 指定弹窗组件的顶部标题
            className: 'my-modal', // 指定弹窗组件样式名
            width: 500, // 指定弹窗组件的宽度
            height: 500, // 指定弹窗组件的高度
            showFooter: true, // 指定是否显示弹窗组件底栏
            showCancel: true, // 指定是否显示取消按钮
            showConfirm: true, // 指定是否显示确认按钮
            confirmable: true, // 指定确认按钮是否可用
            showClose: true, // 指定是否显示右上角关闭按钮
            closeOnBlur: true, // 指定是否在点击蒙层后关闭弹窗(v2.1.24)
            closeOnConfirm: true, // 指定是否在点击确认按钮后关闭弹窗(v2.1.26)
            closeOnCancel: true, // 指定是否在点击取消按钮后关闭弹窗(v2.1.26)
            cancelText: '取消', // 指定取消按钮文字
            confirmText: '确定', // 指定确认按钮文字
            bottomText: null, // 指定弹窗组件底栏左侧的文字,可传入jsx
            onConfirm: () => {}, // 指定点击确认按钮后的回调函数
            onCancel: () => {}, // 指定点击取消按钮后的回调函数
            onClose: () => {}, // 指定弹窗被关闭后的回调函数
            onBlur: () => {}, // 指定蒙层被点击时的回调函数
            children: <MyComponent/>, // 指定弹窗组件的内容组件
        }
    }
]

component

在工具栏中增加一个完全自定义的React组件:
const extendControls = [
    'separator',
    {
        key: 'my-component',
        type: 'component',
        component: <MyComponent />
    }
]

controls与extendControls混合使用

你可以在controls属性中使用extendControls的配置规则,以此来将你的自定义控件插入到某个内置控件之前:
const controls = [
    'undo', 'redo', 'separator', 'bold', 'italic',
    {
        key: 'my-dropdown',
        type: 'dropdown',
        title: '这是一个自定义的下拉组件',
        className: 'my-dropdown',
        text: 'Hello', // 指定按钮文字,此处可传入jsx,若已指定html,则text不会显示
        showArrow: true, // 指定是否显示下拉组件顶部的小三角形
        component: <MyComponent />, // 指定在下拉组件中显示的内容组件
    },
    'underline', 'strike-through'
]

componentBelowControlBar

指定一个显示在编辑器工具栏和编辑器区域之间的React组件

media

该属性为一个对象,用于配置编辑器媒体库相关的功能,该对象所有属性见下表:
名称
类型
说明
uploadFn
Function
指定媒体库上传函数,见下文示例
validateFn
Function
指定媒体库验证函数,见下文示例
accepts
Object
配置允许上传的媒体类型
accepts.image
String|false
指定可选取的图片文件类型,设置为false则禁止上传图片
accepts.video
String|false
指定可选取的视频文件类型,设置为false则禁止上传视频,上传视频需要指定uploadFn
accepts.audio
String|false
指定可选取的音频文件类型,设置为false则禁止上传音频,上传音频需要指定uploadFn
externals
Object
配置允许插入的外部媒体的类型
externals.image
Boolean
是否允许插入外部图片,默认为true
externals.video
Boolean
是否允许插入外部视频,默认为true
externals.audio
Boolean
是否允许插入外部音频,默认为true
externals.embed
Boolean
是否允许插入嵌入式媒体,例如embed和iframe标签等,默认为true
onInsert
Function
指定从媒体库插入图片到编辑器时的回调函数
onChange
Function
指定媒体库内容发生变化时的回调函数
pasteImage
Boolean
是否允许粘贴图片到编辑器
accepts
Object
指定媒体库允许上传的媒体MIME类型

media.uploadFn

编辑器自身不带有上传功能,具体的上传功能需要通过uploadFn指定。编辑器在调用media.uploadFn时,会传入一个包含文件体、文件在媒体库的ID、进度回调、成功回调和失败回调的对象作为参数:
{
  file: [File Object],
  progress: function (progress) {
    // progress为0到100
  },
  libraryId: 'XXXXX',
  success: function (res) {
    // res须为一个包含已上传文件url属性的对象:
  },
  error: function (err) {

  }
}
uploadFn的实现规则很简单,通过param.file获取到要上传的文件,然后使用XMLHttpRequest或者你常用的网络请求库将文件上传到服务器,将服务器返回的文件url通过param.success函数回传给编辑器即可;如果能监控到文件上传进度,也可以通过param.progress函数将上传进度告知编辑器,编辑器会友好的以进度条的形式展示出来;如果上传出现问题,则需要通过param.error函数告知编辑器。
一个简单的uploadFn示例如下:
const myUploadFn = (param) => {

  const serverURL = 'http://upload-server'
  const xhr = new XMLHttpRequest
  const fd = new FormData()

  const successFn = (response) => {
    // 假设服务端直接返回文件上传后的地址
    // 上传成功后调用param.success并传入上传后的文件地址
    param.success({
      url: xhr.responseText,
      meta: {
        id: 'xxx',
        title: 'xxx',
        alt: 'xxx',
        loop: true, // 指定音视频是否循环播放
        autoPlay: true, // 指定音视频是否自动播放
        controls: true, // 指定音视频是否显示控制栏
        poster: 'http://xxx/xx.png', // 指定视频播放器的封面
      }
    })
  }

  const progressFn = (event) => {
    // 上传进度发生变化时调用param.progress
    param.progress(event.loaded / event.total * 100)
  }

  const errorFn = (response) => {
    // 上传发生错误时调用param.error
    param.error({
      msg: 'unable to upload.'
    })
  }

  xhr.upload.addEventListener("progress", progressFn, false)
  xhr.addEventListener("load", successFn, false)
  xhr.addEventListener("error", errorFn, false)
  xhr.addEventListener("abort", errorFn, false)

  fd.append('file', param.file)
  xhr.open('POST', serverURL, true)
  xhr.send(fd)

}
<BraftEditor media={{uploadFn: myUploadFn}}/>
如果未指定uploadFn,添加到媒体库的图片将会自动转换为base64的形式,而视频和音频则无法被添加到媒体库。

media.validateFn

该函数用于校验从本地选择的媒体文件,可以是一个普通函数,也可以是一个Promise对象,校验不通过的媒体文件将不会被添加到媒体库中。
使用同步函数时,需要返回一个布尔值来表明校验是否通过,示例如下:
// 不允许添加尺寸大于100KB的文件
const myValidateFn = (file) => {
    return file.size < 1024 * 100
}
使用Promise对象的验证函数示例:
const myValidateFn = (file) => {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            file.size < 1024 * 100 ? resolve() : reject()
        }, 2000)
    })
}
<BraftEditor media={{
    uploadFn: myUploadFn,
    validateFn: myValidateFn
}}/>

media.accepts

指定媒体库允许选择的本地文件的MIME类型,默认值如下:
{
  image: 'image/png,image/jpeg,image/gif,image/webp,image/apng,image/svg',
  video: 'video/mp4',
  audio: 'audio/mp3'
}
可以指定其中某一项为false来禁止上传对于类型的文件。
注意:对于粘贴、拖放媒体文件到编辑器或者媒体库的操作,本属于暂时不会生效

imageControls

指定编辑器内的图片工具栏的可用控件,默认值如下:
[
    'float-left', // 设置图片左浮动
    'float-right', // 设置图片右浮动
    'align-left', // 设置图片居左
    'align-center', // 设置图片居中
    'align-right', // 设置图片居右
    'link', // 设置图片超链接
    'size', // 设置图片尺寸
    'remove' // 删除图片
]
除了上述配置项目,你还可以在imageControls加入自定义控件:
const imageControls = [
    'float-left',
    'float-right',
    {
        text: 'Foo', // 指定控件文字,可传入jsx
        render: (mediaData) => {}, // 控件渲染函数,该属性指定时,text和onClick属性将被忽略
        onClick: (block) => {} // 指定控件点击后的回调,参数为当前图片的block对象
    },
    'link',
    'size',
    'remove'
]

colors

指定编辑器可用的颜色列表,仅支持16进制颜色字符串,默认值如下:
[
    '#000000', '#333333', '#666666', '#999999', '#cccccc', '#ffffff',
    '#61a951', '#16a085', '#07a9fe', '#003ba5', '#8e44ad', '#f32784',
    '#c0392b', '#d35400', '#f39c12', '#fdda00', '#7f8c8d', '#2c3e50'
]
注意,如果粘贴了一段带颜色的文字到编辑器里面,并且编辑器的可用颜色列表不包含该颜色,那么编辑器会自动将该颜色临时加入到可用颜色列表。

fontSizes

指定编辑器可用的字号列表,仅支持数字,默认值如下:
[
    12, 14, 16, 18, 20, 24,
    28, 30, 32, 36, 40, 48,
    56, 64, 72, 96, 120, 144
]

fontFamilies

指定编辑器可用的字体列表,默认值如下:
[
    {
        name: 'Araial',
        family: 'Arial, Helvetica, sans-serif'
    }, {
        name: 'Georgia',
        family: 'Georgia, serif'
    }, {
        name: 'Impact',
        family: 'Impact, serif'
    }, {
        name: 'Monospace',
        family: '"Courier New", Courier, monospace'
    }, {
        name: 'Tahoma',
        family: 'tahoma, arial, "Hiragino Sans GB", 宋体, sans-serif'
    }
]
考虑到系统平台之间的差异,实际上不太推荐在富文本中设置文字字体,所以编辑器默认不展示字体选择器控件。

lineHeights

指定编辑器可用的行高列表,仅支持数字,默认值如下:
[1, 1.2, 1.5, 1.75, 2, 2.5, 3, 4]

textAligns

指定文本对齐方式,默认值如下:
['left', 'center', 'right', 'justify']
注意,传入不在上面数组中的值将不会有任何效果

letterSpacings

指定编辑器可用的字间距,仅支持数字,默认值如下:
[0, 1, 2, 3, 4, 5, 6]

emojis

指定编辑器可用的Emoji表情,默认值如下:
[
    '🤣', '🙌', '💚', '💛', '👏', '😉', '💯',
    '💕', '💞', '💘', '💙', '💝', '🖤', '💜',
    '❤️', '😍', '😻', '💓', '💗', '😋', '😇',
    '😂', '😹', '😘', '💖', '😁', '😀', '🤞',
    '😲', '😄', '😊', '👍', '😌', '😃', '😅',
    '✌️', '🤗', '💋', '😗', '😽', '😚', '🤠',
    '😙', '😺', '👄', '😸', '😏', '😼', '👌',
    '😎', '😆', '😛', '🙏', '🤝', '🙂', '🤑',
    '😝', '😐', '😑', '🤤', '😤', '🙃', '🤡',
    '😶', '😪', '😴', '😵', '😓', '👊', '😦',
    '😷', '🤐', '😜', '🤓', '👻', '😥', '🙄',
    '🤔', '🤒', '🙁', '😔', '😯', '☹️', '☠️',
    '😰', '😩', '😖', '😕', '😒', '😣', '😢',
    '😮', '😿', '🤧', '😫', '🤥', '😞', '😬',
    '👎', '💀', '😳', '😨', '🤕', '🤢', '😱',
    '😭', '😠', '😈', '😧', '💔', '😟', '🙀',
    '💩', '👿', '😡', '😾', '🖕'
],

draftProps

可以通过draftProps来直接给编辑器所用的DraftJS Editor组件传递属性,详细信息请参见https://draftjs.org/docs/api-reference-editor#props

hooks

为了增加编辑器的可扩展性,同时避免传入一大堆onXxxx之类的属性,编辑器增加了hooks属性,通过该属性来指定编辑器的行为钩子,编辑在会在指定行为执行之前调用对应的钩子函数。
在钩子函数中,可以通过函数的参数获取到当前行为的数据,甚至可以通过返回被修改的数据来改变行为的结果,例如通过下面的钩子函数可以实现在设置文字链接时自动补全协议:
const hooks = {
    'toggle-link': ({ href, target }) => {
        href = href.indexOf('http') === 0 ? href : `http://${href}`
        return { href, target }
    }
}
<BraftEditor hooks={hooks}/>
如果钩子函数返回布尔值false,则该行为将会被中止,如果没有返回有效的值,该行为将会按默认方式继续。
编辑器目前支持下列行为钩子:
名称
说明
toggle-link
在设置文字链接前执行的钩子函数
open-braft-finder
在打开媒体库之前执行的钩子函数
toggle-inline-style
在设置文字基本样式之前执行的钩子函数
change-block-type
在更改光标所在行的区块类型之前执行的钩子函数
exec-editor-command
在执行编辑器指令之前执行的钩子函数
insert-emoji
在插入Emoji表情之前执行的钩子函数
toggle-font-family
在设置文字字体之前执行的钩子函数
toggle-font-size
在设置文字字号之前执行的钩子函数
toggle-letter-spacing
在设置文字字间距之前执行的钩子函数
toggle-line-height
在设置文字行高之前执行的钩子函数
toggle-text-alignment
在设置文本对齐方式之前执行的钩子函数
toggle-text-color
在设置文字颜色之前执行的钩子函数
toggle-text-background-color
在设置文字背景颜色之前执行的钩子函数
select-medias
在选择媒体库文件之前执行的钩子函数
deselect-medias
在取消选择媒体库文件之前执行的钩子函数
remove-medias
在删除媒体库文件之前执行的钩子函数
insert-medias
在从媒体库插入文件到编辑器之前执行的钩子函数
select-files
在从本地选择文件插入到媒体库之前执行的钩子函数