Skip to content

fallenner/braft-extensions

BranchesTags
 
 

Repository files navigation

Braft Editor 扩展模块包

目前包含的模块列表

  1. 表格模块 Table
  2. Markdown 语法支持 Markdown
  3. 代码高亮模块 CodeHighlighter
  4. 高级取色器模块 ColorPicker
  5. 表情包扩展模块 Emoticon
  6. Mention 模块 Mention （感谢ninesunsabiu的贡献）
  7. 输入字数限制模块 MaxLength
  8. 标题区块(h1-h6)id 模块 HeaderId

这个 fork 版本修复了以下问题

  1. 引入marked作为处理粘贴的 markdown 文本的插件，修复之前 markdown 插件不会处理粘贴文本中的 markdown 语法。

安装

npm install @starfall/braft-extensions --save
# 或者
yarn add @starfall/braft-extensions

使用

需要分别 import 本模块包下面的各个模块，参见下方各模块的基本使用介绍

注意事项

如果在使用扩展模块时，指定了 includeEditors 或 excludeEditors 属性，则通过 BraftEditor.createEditorState 创建初始化内的时候，需要传入一个 editorId 属性来指明创建的 editorState 是给哪个 BraftEditor 组件用的：

// 以使用表格扩展为例
BraftEditor.use(Table({
  includeEditors: ['editor-1']
}))

// 使用BraftEditor.createEditorState创建编辑器数据
const initialValue = BraftEditor.createEditorState('xxxxxx', { editorId: 'editor-1' })

// 将数据传入编辑器
<BraftEditor value={initialValue} id="editor-1"/>

表格模块

支持添加/删除行列、合并/拆分单元格等基本操作

基本使用

import "braft-editor/dist/index.css";
import "braft-extensions/dist/table.css";

import BraftEditor from "braft-editor";
import Table from "braft-extensions/dist/table";

const options = {
  defaultColumns: 3, // 默认列数
  defaultRows: 3, // 默认行数
  withDropdown: false, // 插入表格前是否弹出下拉菜单
  columnResizable: false, // 是否允许拖动调整列宽，默认false
  exportAttrString: "", // 指定输出HTML时附加到table标签上的属性字符串
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
};

BraftEditor.use(Table(options));

使用注意事项

  • 使用表格模块，请升级 braft-editor、braft-convert 和 braft-utils 至最新版本
  • 暂不支持在表格中插入图片等媒体资源，因为 draftjs 不支持嵌套 block，而每一个单元格和图片等都是一个单独的 block，所以无法实现
  • 每个表格前后都需要有一个空行才能正常展示，有疑问的请自行查阅源码
  • 请勿在表格内进行过于复杂的操作，例如任性合并/拆分单元格等，以免进入程序死角导致报错
  • 调整列宽的功能会在后续版本中支持
  • 输出表格默认不带边框，如果需要边框，设置参数exportAttrString为'border="1" style="border-collapse: collapse"'即可

Markdown 语法支持模块

移植自draft-js-markdown-shortcuts-plugin，可以在编辑器中使用 markdown 语法快捷输入内容

基本使用

import "braft-editor/dist/index.css";

import BraftEditor from "braft-editor";
import Markdown from "braft-extensions/dist/markdown";

const options = {
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
};

BraftEditor.use(Markdown(options));

使用注意事项

  • 该模块仅支持部分 markdown 语法，对于 draft-js 和 braft-editor 本身没有的样式和功能，本模块也无法支持
  • 该模块暂时不支持 markdown 表格语法

代码高亮模块

使用prismjs和draft-js-prism开发的一个代码高亮模块，能在编辑器中实现代码高亮编辑功能，内置 html、js 和 css 语言支持，可扩展更多语言，在线演示

安装依赖

npm install prismjs draft-js-prism --save
# 或者
yarn add prismjs draft-js-prism

基本使用

import "braft-editor/dist/index.css";
import "braft-extensions/dist/code-highlighter.css";

import BraftEditor from "braft-editor";
import CodeHighlighter from "braft-extensions/dist/code-highlighter";

const options = {
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
};

BraftEditor.use(CodeHighlighter(options));

扩展语言支持

请访问PrismJs 官网查看全部支持的语言

// 首先需要从prismjs中引入需要扩展的语言库
import "prismjs/components/prism-java";
import "prismjs/components/prism-php";

// 通过opitons.
const options = {
  syntaxs: [
    {
      name: "JavaScript",
      syntax: "javascript",
    },
    {
      name: "HTML",
      syntax: "html",
    },
    {
      name: "CSS",
      syntax: "css",
    },
    {
      name: "Java",
      syntax: "java",
    },
    {
      name: "PHP",
      syntax: "php",
    },
  ],
};

BraftEditor.use(CodeHighlighter(options));

使用其他 Prism 配色主题

该功能将在后续版本中支持

使用注意事项

  • 使用该模块，必须引入 braft-extensions/dist/code-highlighter.css 文件
  • 该模块仅用于对编辑器内的代码块进行高亮展示，并不会更改编辑器输出的实际内容，如果需要在展示页面进行代码高亮，请单独使用 Prism.js 或其他代码高亮方案进行处理
  • 在展示页使用 PrismJS 进行代码高亮的时候，需要参考PrismJS/prism#598做一下处理

高级取色器模块

使用react-color来替换编辑器自身的颜色选择模块，设置颜色更自由！在线演示

安装依赖

npm install react-color --save
# 或者
yarn add react-color

基本使用

import "braft-editor/dist/index.css";
import "braft-extensions/dist/color-picker.css";

import BraftEditor from "braft-editor";
import ColorPicker from "braft-extensions/dist/color-picker";

const options = {
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
  theme: "light", // 指定取色器样式主题，支持dark和light两种样式
};

BraftEditor.use(ColorPicker(options));

使用注意事项

  • 使用该模块，必须引入 braft-extensions/dist/color-picker.css 文件

表情包扩展模块

替换内置的 emoji 组件，可以插入图片形式的表情，在线演示

基本使用

import "braft-editor/dist/index.css";
import BraftEditor from "braft-editor";

// 引入表情包扩展模块样式文件
import "braft-extensions/dist/emoticon.css";
// 引入表情包扩展模块和默认表情包列表
import Emoticon, { defaultEmoticons } from "braft-extensions/dist/emoticon";

// 转换默认表情包列表，让webpack可以正确加载到默认表情包中的图片，请确保已对png格式的文件配置了loader
// 如果你使用的webpack版本不支持动态require，或者使用的其他打包工具，请勿使用此写法
const emoticons = defaultEmoticons.map((item) =>
  require(`braft-extensions/dist/assets/${item}`),
);

// 也可以使用自己的表情包资源，不受打包工具限制
// const emoticons = ['http://path/to/emoticon-1.png', 'http://path/to/emoticon-2.png', 'http://path/to/emoticon-3.png', 'http://path/to/emoticon-4.png', ...]

const options = {
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
  emoticons: emoticons, // 指定可用表情图片列表，默认为空
  closeOnBlur: false, // 指定是否在点击表情选择器之外的地方时关闭表情选择器，默认false
  closeOnSelect: false, // 指定是否在选择表情后关闭表情选择器，默认false
};

BraftEditor.use(Emoticon(options));

默认表情图片来自https://www.iconfinder.com/iconsets/emoji-18 [CC BY 3.0]，由Bukeicon创建

使用注意事项

  • 使用该模块，必须引入 braft-extensions/dist/emoticon.css 文件

Mention 模块

为编辑器增加 mention(提及)功能

基本使用

import "braft-editor/dist/index.css";
import BraftEditor from "braft-editor";

// 引入Mention扩展模块
import Mention, {
  defaultSuggestionsFilter,
} from "braft-extensions/dist/mention";
// 取出Mention扩展和Mention列表组件
const [mentionExtension, MentionSuggestions] = Mention();

// 使用扩展
BraftEditor.use(mentionExtension);

class MentionDemo extends React.Component {
  state = {
    editorState: BraftEditor.createEditorState(),
    // 在state中维护一个mention列表(这个数据可以从外部获取)
    mentions: [
      {
        id: "Matthew Russell",
        name: "Matthew Russell",
        link: "https://twitter.com/mrussell247",
        avatar:
          "https://pbs.twimg.com/profile_images/517863945/mattsailing_400x400.jpg",
      },
      {
        id: "Julian Krispel-Samsel",
        name: "Julian Krispel-Samsel",
        link: "https://twitter.com/juliandoesstuff",
        avatar: "https://avatars2.githubusercontent.com/u/1188186?v=3&s=400",
      },
      {
        id: "Jyoti Puri",
        name: "Jyoti Puri",
        link: "https://twitter.com/jyopur",
        avatar: "https://avatars0.githubusercontent.com/u/2182307?v=3&s=400",
      },
      {
        id: "Max Stoiber",
        name: "Max Stoiber",
        link: "https://twitter.com/mxstbr",
        avatar:
          "https://pbs.twimg.com/profile_images/763033229993574400/6frGyDyA_400x400.jpg",
      },
    ],
    // 再维护一个mention列表搜索关键字
    mentionKeyword: null,
  };

  // 定义mention列表的搜索处理函数
  handleMentionFilter = ({ value: mentionKeyword }) => {
    this.setState({ mentionKeyword });
  };

  handleChange = (editorState) => {
    this.setState({ editorState });
  };

  render() {
    const { mentionKeyword, editorState, mentions } = this.state;

    return (
      <div>
        <BraftEditor value={editorState} onChange={this.handleChange} />
        {/**MentionSuggestions组件需要单独渲染，并传入正确的属性**/}
        <MentionSuggestions
          onSearchChange={this.handleMentionFilter}
          suggestions={defaultSuggestionsFilter(mentionKeyword, mentions)}
        />
      </div>
    );
  }
}

输入字数限制模块

为编辑器增加 maxLength 和 onReachMaxLength 属性，用于限制输入字数

基本使用

import "braft-editor/dist/index.css";
import BraftEditor from "braft-editor";
import MaxLength from "braft-extensions/dist/max-length";

const options = {
  defaultValue: 100, // 指定默认限制数，如不指定则为Infinity(无限)
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
};

BraftEditor.use(MaxLength(options));

使用 MaxLength 扩展之后，可为编辑器组件传入 maxLength 和 onReachMaxLength:

<BraftEditor
  maxLength={100}
  onReachMaxLength={() => console.log("不能再输入了！")}
/>

该模块实现思路来自于https://stackoverflow.com/a/46071494，如有更好的解决办法，欢迎 PR！

使用注意事项

  • 粘贴内容时如果超过了限制字数，则整个粘贴内容都不会被粘贴到编辑器
  • 对于富文本编辑器，限制输入字符数并不是一个很适合的做法
  • 可通过 editorState.toText().length 获取到内容长度再进行友好提示

标题区块(h1-h6)id 模块

为标题区块(h1-h6)增加随机的 id，便于在展示页支持锚点跳转功能

基本使用

import "braft-editor/dist/index.css";

import BraftEditor from "braft-editor";
import HeaderId from "braft-extensions/dist/header-id";

const options = {
  includeEditors: ["editor-id-1"], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ["editor-id-2"], // 指定该模块对哪些BraftEditor无效
};

BraftEditor.use(HeaderId(options));

Mention 模块

基于 draft-js-mention 实现的 Mention 功能
options 除了可以使用 includeEditors 和 excludeEditors 指定和排除 editor 外，其余的参数请参考 draft-js-mention 的参数配置 可参考 https://www.draft-js-plugins.com/plugin/mention

基本使用

import Mention from 'braft-extensions/dist/mention'

interface MentionData {
    link?: string;
    avatar?: string;
    name: string;
    id?: null | string | number;
}

interface MentionSuggestionsPubProps {
    suggestions: MentionData[];
    open: boolean;
    onOpenChange(open: boolean): void;
    onSearchChange(event: { value: string }): void;
    onAddMention(Mention: MentionData): void;
}

const options = {
  includeEditors: ['editor-id-1'], // 指定该模块对哪些BraftEditor生效，不传此属性则对所有BraftEditor有效
  excludeEditors: ['editor-id-2'],  // 指定该模块对哪些BraftEditor无效
  mentionTrigger: '@'               // 可选参数。设置触发 mention 的符号，默认为 '@'
}

// Mention 方法返回一个二元祖
// 第一个是 braft-extension 所用插件数据
// 第二个是 控制 mention suggestions 的组件
//          类型为 React.ComponentType<MentionSuggestionsPubProps>
const [mentionExtension, MentionSuggestions] = Mention(options)
BraftEditor.use(mentionExtension)


const DemoEditor = (props) => {
  // ... 省略

  return (
    <div>
      <BraftEditor ... />
      <MentionSuggestions ... />
    </div>
  )
}

About

Braft Editor扩展模块包

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 89.8%
  • SCSS 10.1%
  • HTML 0.1%