以下是编辑器的所有属性列表

属性名

类型

说明

value

EditorState

编辑器的内容

defaultValue

EditorState

编辑器的初始化内容,仅首次传入生效

placeholder

String

指定Placeholder文本

readOnly

Boolean

指定编辑器是否只读

language

String

编辑器的语言

controls

Array[String|Object]

编辑器的工具栏控件列表

excludeControls

Array[String]

不在工具栏显示的控件列表

extendControls

Array[Object]

自定义的控件列表

componentBelowControlBar

React Component

在工具栏和编辑区域之间显示的组件

media

Object

编辑器的多媒体功能配置,包括上传功能

imageResizable

Boolean

是否允许拖动调整图片尺寸,默认为true

imageControls

Array[String|Object]

编辑器内的图片工具栏控件

colors

Array[String]

编辑器可用颜色列表

fontSizes

Array[Number]

编辑器可用的字号列表

fontFamilies

Array[Object]

编辑器可用的字体列表

lineHeights

Array[Number]

编辑器可用的行高列表

textAligns

Array[String]

编辑器可用的文本对齐方式

letterSpacings

Array[Number]

编辑器可用的字间距列表

emojis

Array[String]

编辑器可用的Emoji列表

textBackgroundColor

Boolean

是否允许设置文字背景颜色

stripPastedStyles

Boolean

是否以纯文本模式粘贴内容,默认为false

className

String

编辑器的样式名

style

Object

编辑器的内联样式

controlBarClassName

String

编辑器工具栏的样式名

controlBarStyle

Object

编辑器工具栏的内联样式

contentClassName

String

编辑器编辑区域容器的样式名

contentStyle

Object

编辑器编辑区域容器的内联样式

draftProps

Object

直接传给DraftJS的Editor组件的属性

onChange

Function(editorState)

编辑器状态(内容、选区等)发生变化时的回调函数

onFocus

Function

编辑器获得焦点时触发的函数

onBlur

Function

编辑器失去焦点时触发的函数

onTab

Function

在编辑器内按下Tab键时触发的函数

onDelete

Function

在编辑器内按下删除键时触发的函数

onSave

Function

在编辑器内按下Command/Ctrl + s时触发的函数

hooks

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

链接插入工具

headings

段落类型(标题1-6、常规)

list-ul

无序列表

list-ol

有序列表

blockquote

引用段落

code

代码块

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

在从本地选择文件插入到媒体库之前执行的钩子函数

set-image-link

设置图片链接时执行的钩子函数

set-image-link-target

设置图片链接目标时执行的钩子函数

set-image-size

设置图片尺寸时执行的钩子函数

set-image-float

设置图片浮动方式时执行的钩子函数

set-image-alignment

设置图片对齐方式时执行的钩子函数