<div style="text-align: center;padding: 10px;margin-bottom: 50px;"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/5c608e5e-8ee1-4c10-a6ac-fa3cbd66f586.svg" /> <div id="badges"> <img alt="Static Badge" src="https://img.shields.io/badge/Microsoft_Edge-121.0-green"> <img alt="Static Badge" src="https://img.shields.io/badge/Chrome-122.0-green"> <img alt="Static Badge" src="https://img.shields.io/badge/Firefox-123.0-green"> <img alt="Static Badge" src="https://img.shields.io/badge/Safari-17.3-green"> <img alt="NPM Version" src="https://img.shields.io/npm/v/minditor"> <img alt="GitHub License" src="https://img.shields.io/github/license/minditor/minditor"> <a href="https://github.com/minditor/minditor"> <img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/minditor/minditor"> </a> </div> <div id="languages"> <a href="/README.md">English</a> <a href="/README-zh_CN.md">中文</a> </div> </div>

1. Minditor是什么

Minditor是一款注重终端用户编辑体验和开发者体验的块级富文本编辑器。它具有以下特点：

提供基础组件和插件，如图片上传和markdown命令，官方团队会持续完善。目标是默认提供与专业编辑工具相匹配的用户体验。
支持内联插入的InlineBlock。
编辑器的Block/InlineBlock可以使用任何框架的组件实现。
除了常见的事件和API外，插件系统还默认为开发者提供了一组重要的响应式状态，简化了插件的开发。

我们的官方网站首页就是使用Minditor制作和渲染的。你可以在首页上体验几乎所有的功能。快来看看吧。

2. 编辑功能

2.1 复制/粘贴/剪切/重做/撤销

默认支持右键菜单和键盘快捷键进行复制、粘贴、剪切、撤销和重做操作。

2.2 markdown命令

Minditor提供以下命令以便快速编辑：

输入#加空格插入标题，#的数量决定标题级别。
在标题中输入1.加空格插入自动编号。
在段落开头输入-加空格插入无序列表。
在段落开头输入1.加空格插入有序列表。
输入+[任意字符]+插入行内代码。
在段落开头输入```+[语言名称]插入代码编辑器。

2.3 范围工具插件

鼠标悬停在选中的文本上会显示一个浮动工具栏，可以更改字体样式或创建链接。

2.4 插入建议插件

输入"/"会触发一个下拉菜单，提供可插入的组件。如果在空行开头输入"/"，可插入的Block和InlineBlock会同时出现。

2.5 块工具插件

鼠标移到任何Block上会在左侧显示一个浮动工具栏，提供默认的删除、复制、粘贴和插入Block的工具。

2.6 目录插件

Minditor支持在文档外显示由标题组成的大纲，如官网首页左侧所示。

2.7 图片块

Minditor的图片组件允许用户将图片上传到指定接口或AWS S3存储桶，或者使用URL.createObjectURL将图片直接编码保存到文档中。Minditor已经包含了一个默认组件InlineImageBlock，用于将图片编码并保存到文档中。

<div> <img src="https://yellow-cdn.veclightyear.com/835a84d5/43f34d1d-db2a-40be-8396-98c6c55e9d4a.gif" alt="建议插件" width="978"/> </div> 你也可以使用`createImageBlock`并提供适当的参数来创建一个将图片上传到指定地址的组件：

import {createImageBlock} from 'minditor'
// @params
// - type: 'xhr'|'aws'
// - config: Uppy.XHRConfig|Uppy.AWS3Config
const ImageBlock = createImageBlock(
'xhr',
{endpoint: 'https://your-domain.com/upload'}
)

图片块使用Uppy作为上传工具。更多配置选项请参考https://uppy.io/docs/xhr-upload/。

2.8 网格块

网格块中的单元格支持所有文档功能，相当于一个嵌入的小型文档。你可以在空段落使用左侧的块工具插入网格。也可以通过在段落开头输入"/"使用插入建议插件获取。网格支持的功能包括：

我们目前正在开发一个更强大的电子表格工具，包括增强的布局和数据处理能力。这个工具未来也会作为一个组件集成到Minditor中，所以目前的网格没有大规模的增强计划。

2.9 代码块

Minditor使用CodeMirror 6作为其代码组件。默认支持以下语言：

• javascript (别名 js/jsx) • typescript (别名 ts/tsx) • python • php • cpp • java • sql • json • rust • css • html • sass • less • xml • yaml

你可以在段落开头输入 ``` + [语言名称]来插入特定语言的代码块。也可以使用块工具或建议工具插入。

3. 开发

3.1 安装和初始化

npm i minditor

Minditor本身可以在任何DOM节点中渲染，不需要任何外部布局或样式要求。如果你只是用它来渲染最简单的文本，可以直接使用以下方法渲染：

import {
    Code,
    Grid,
    Heading,
    InlineImageBlock,
    InlineCode,
    Link,
    OLItem,
    Paragraph,
    Text,
    ULItem,
    InlineImageBlock
} from "minditor";

const rootElement = document.getElementById('root')! const types = { Paragraph, Text, Heading, OLItem, ULItem, InlineCode, Code, Link, Grid, Image: InlineImageBlock } const data = { name: 'MyDoc', children: [{ type: 'Paragraph', content: [{type:'Text', value: '这是我的第一个文档。'}] }] }

const doc = new Document(rootElement, data, types) doc.render()

对于需要完整插件且视图高度自动适应外部容器的场景，我们建议使用`scaffold`创建视图：

```typescript

import {
    Code,
    createBlockTool,
    createRangeTool,
    createSuggestionTool,
    defaultBlockWidgets,
    defaultFormatWidgets,
    defaultMarkdownPlugins,
    defaultSuggestionWidgets,
    Grid,
    Heading,
    InlineImageBlock,
    InlineCode,
    Link,
    OLItem,
    Paragraph,
    scaffold,
    Text,
    ULItem,
    createTOCTool
} from "minditor";

const root= document.getElementById('root')!
const types = {
    Paragraph,
    Text,
    Heading,
    OLItem,
    ULItem,
    InlineCode,
    Code,
    Link,
    Grid,
    Image: InlineImageBlock
}

const plugins = [
    ...defaultMarkdownPlugins,
    createBlockTool(defaultBlockWidgets),
    createRangeTool( defaultFormatWidgets ),
    createSuggestionTool(defaultSuggestionWidgets),
    createTOCTool()
]
const result = scaffold(root, {data: jsonData, types, plugins}, { debug: true })
result.render()

3.2 开发InlineBlock

InlineBlock可以内联嵌入，开发InlineBlock非常简单。让我们以InlineCode为例：

export class InlineCode extends InlineComponent {
    static displayName = 'InlineCode'
    constructor(public data: InlineCodeData) {
        super();
    }
    render()  {
        return <span style={{display:'inline-block', background:'#eee', padding:'4px 8px'}}>{this.data.value}</span>
    }
    toText() {
        return this.data.value
    }
}

有了InlineBlock后，需要提供用户使用的方法。有三种方式：

在Minditor的SuggestionTool中显示一个Widget。当用户输入/时，会出现一个下拉菜单，显示这个Block，用户可以点击使用。
实现一个Plugin，监听特定的用户输入，当输入满足某些条件时插入一个InlineBlock，类似markdown。

作为示例，让我们看看如何创建一个Range Tool的Widget，用于添加字体颜色和背景颜色：

class ColorWidget extends RangeWidget {
    static displayName = `ColorRangeWidget`
    useColor = (color: string) => {
        this.document.view.formatCurrentRange({color})
    }
    useBackgroundColor = (backgroundColor: string) => {
        this.document.view.formatCurrentRange({backgroundColor})
    }

    render() {
        const hover = atom(false)

        const pickerStyle = () => {
            return ({
                display: hover() ? 'block' : 'none',
                position: 'absolute',
                top: '100%',
                left: 0,
                transform: 'translateX(-50%)',
            })
        }

        const picker = (
            <div style={pickerStyle}>
                <ColorPicker onColorClick={this.useColor} onBackgroundColorClick={this.useBackgroundColor}/>
            </div>
        )
        return (
            <div style={{display:'flex', position:'relative', width:24, height:24, alignItems: 'center',justifyContent: 'center'}}
                 onmouseenter={() => hover(true)}
                 onmouseleave={() => hover(false)}
            >
                <span style={{cursor: 'pointer',marginLeft:8, fontSize:18}}>A</span>
                {picker}
            </div>
        )
    }
}

有了这个widget，你可以通过将它传入createRangeTool函数来使用它：

const plugins = [
    //...  其他插件
    createRangeTool( [...defaultFormatWidgets, ColorWidget] ),
]

关于Plugin的开发，下面会提供更详细的示例。

3.3 开发Block

开发Block组件在本质上与开发Inline组件相似。不同之处在于如何使其可供用户使用；它被注册在BlockTool或Insert Suggestion Tool中供用户访问。注意，BlockTool中的Widget和Insert Suggestion Tool中的Widget是可以互换的。为了进一步简化Widget的开发，Minditor提供了一个createSuggestionWidget函数来协助快速开发widget。这里，我们以插入Code Widget为例：

type CommonInsertHandleProps = {
    insert: (initialData: InlineData|BlockData) => void
}

function CodeInsertHandle({insert}: CommonInsertHandleProps) {
    const onGridChange = (lang: string) => {
        insert({type: 'Code', language:lang, value: '', content: []})
        activated(false)
    }
    const activated = atom(false)

    const languages = Object.keys(CodeBlock.langToPlugin)

    return (
        <div
            style={{
                position: 'relative',
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'flex-start',
                cursor: 'pointer',
                width: '100%'
            }}
            onmouseenter={() => activated(true)}
            onmouseleave={() => activated(false)}
        >
            <Code size={18}/>
            <span style={{marginLeft: 8, fontSize: 14,  whiteSpace:'nowrap'}}>+ 代码</span>
            <Right size={18}/>

            <div style={() => ({
                display: activated() ? 'block' : 'none',
                position: 'absolute',
                left: 'calc(100% - 8px)',
                top: 0,
                transform: 'translateY(-50%)',
                paddingLeft: 18,
                background: 'transparent',
            })}
            >
                <div style={{
                    border: '1px solid #eee',
                    background: '#fff',
                    boxShadow: '2px 2px 5px #dedede',
                    maxHeight: 400,
                    overflowY: 'auto'
                }}
                >
                    <CodeLanguagePicker onChange={onGridChange} languages={languages}/>
                </div>
            </div>
        </div>
    )
} 

const CodeBlockWidget = createSuggestionWidget(CodeInsertHandle, 'Code', true)

3.3.1 使用React开发Block

我们将演示如何使用React开发Block，以创建一个日历块为例。

import { Component } from 'minditor'
import { createElement } from 'react';
import { createRoot } from 'react-dom/client';

class Calendar extends Component {
    static displayName = 'Calendar'
    render() {
        const container = document.createElement('div')
        container.contentEditable = 'false'
        const root = createRoot(container);
        root.render(createElement(DayPicker, {mode: 'single'}));
        return container
    }
}

3.4 开发Plugin

在Minditor中，Plugin具有控制整个文档的能力，可以实现几乎任何需求。它可以根据用户输入执行一次性命令，也可以拥有自己独立的界面以支持更复杂的操作。

3.4.1 执行一次性命令

让我们以markdown添加标题的能力为例，看看如何开发一个Plugin。

class Plugin extends Plugin{
  public static displayName = `createHeading`
  public static activateEvents = {
    inputChar: onInputKey(' ')
  }
  run({} : PluginRunArgv) : boolean | undefined{
    const initialCharacters = '#'
    const { view, history } = this.document
    const startRange = view.state.selectionRange()
    const { startText,  startBlock,  isEndFull,isCollapsed, endText } = startRange!
    //  1. 标题只能在段落内容中生成。
    if (!(startBlock instanceof Paragraph || startBlock instanceof Heading)) return false
    // 2. 只能在段落开头。
    if (startBlock.firstChild !== startText) return false
    // 3. startText中的文本应该匹配#
    if (startText.data.value.slice(0, initialCharacters.length) !== initialCharacters) return false

    // 4. 删除最后的空格
    const textToMatch = startText.data.value.slice(0, startText.data.value.length - 1)
    const matchedText = reversMatchStr(textToMatch, initialCharacters)
    if (matchedText === false) return false

    // 开始替换
    history.openPacket(startRange)
    // 1. 删除startText中的initialCharacters和空格
    const newTextAfterCursor = startText.data.value.slice(initialCharacters.length + 1)
    view.updateText(newTextAfterCursor, startText)
    // 2. 获取中间的所有文本
    const titleTextFrag = view.deleteBetween(startText, null, startBlock)
    // 3. 用新的Heading块替换
    const newBlock = createBlock.call(this, titleTextFrag)
    view.replace(newBlock, startBlock, this.document.content)
    view.setCursor(newBlock, 0)
    const endRange = new DocRange(newBlock, newBlock.firstChild!, 0, newBlock, newBlock.firstChild!, 0, )
    history.closePacket(endRange)
    return true
  }
}

3.4.2 渲染UI

插件使用一个轻量级的响应式前端框架Axii来渲染UI。开发者只需要记住以下基本用法：

用atom()包裹需要响应式访问和操作的数据。
用computed包裹计算数据。
对于需要维护响应式DOM结构/属性，使用函数来表示它们，不需要computed包裹。

让我们以Range Tool为例，看看如何使用Axii和系统提供的响应式状态来构建一个响应式界面。

class OneRangeTool extends RangeTool {
    public rangeWidgets: RangeWidget[]

    constructor(public document: Document) {
        super(document);
        this.rangeWidgets = RangeWidgets.map(RangeWidgetClass => {
            return new RangeWidgetClass(this.document)
        })
    }
    calculatePosition(outsideDocBoundary: boolean) {
        const {visibleRangeRect, lastMouseUpPositionAfterRangeChange, selectionRange, hasRange} = this.document.view.state

        const positionAttrs = {
            position: 'fixed'
        } as any

        positionAttrs.position = 'fixed'
        // 根据最后鼠标位置决定模态框位置
        if (lastMouseUpPositionAfterRangeChange()!.top > (visibleRangeRect.raw!.top + visibleRangeRect.raw!.height / 2)) {
            positionAttrs.top = visibleRangeRect.raw!.top + visibleRangeRect.raw!.height
            positionAttrs.bottom = undefined 
        } else {
            positionAttrs.top = undefined 
            positionAttrs.bottom = -(visibleRangeRect.raw!.top)
        }
        positionAttrs.left = lastMouseUpPositionAfterRangeChange()!.left

        // 如果插件UI在内容同一个容器中，使用absolute定位
        if(!outsideDocBoundary) {
            const boundaryRect = this.document.view.getContainerBoundingRect()!
            positionAttrs.position = 'absolute'
            if (lastMouseUpPositionAfterRangeChange()!.top > (visibleRangeRect.raw!.top + visibleRangeRect.raw!.height / 2)) {
                positionAttrs.top -= boundaryRect.top
            } else {
                positionAttrs.bottom += boundaryRect.top
            }
            positionAttrs.left -= boundaryRect.left

        }
        return positionAttrs
    }
    render(outsideDocBoundary: boolean) {
        const style = () => {
            const { lastMouseUpPositionAfterRangeChange, hasRange} = this.document.view.state
            if (!lastMouseUpPositionAfterRangeChange() || !hasRange()){
                return {display: 'none'}
            }

            const positionAttrs = this.calculatePosition(outsideDocBoundary)

            return {
                display: 'block',
                ...positionAttrs,
            }
        }

        return <div style={style} data-testid="rangeTool-container">
            <div style={{display:'flex', whiteSpace: 'nowrap'}}>
                {() => this.rangeWidgets.map((widget: RangeWidget) => {
                    return widget.render()
                })}
            </div>
        </div>
    }
}