这是一个正在开发的简易的富文本编辑器,适用于浏览器平台。
仓库中附带的 CSS 样式仅用于预览,不追求美观,不会发布到 npm 仓库,若非样式存在影响使用的问题,请勿提交与 CSS 样式有关的 issue 和 pr。
目前实现了如下功能:
- 正文、各级标题的切换
- 引用块、有序列表、无序列表、代办列表
- 超链接、加粗、下划线、斜体、删除线、内敛代码块、上标、下标、前景色、背景色
- 分割线、图像
- 橡皮擦按钮
- 代码块
- 快捷键
- 粘贴、节点拖动
- 历史记录(撤回和重做)
等待实现的功能:
- 表情
- 表格
shift enter
: 在当前行下方创建一个新行并将光标移动到新行中,不会将原始光标后方的内容移动到下一行ctrl enter
: 在距离最近的顶层元素的下方添加一个新行,在非代码块中动作与shift
一致ctrl shift enter
: 在距离最近的顶层元素的上方添加一个新行并将光标移动到新行中ctrl Z
: 撤回ctrl shift Z
: 重做列表结尾空行中按 enter
: 删除列表最后一行,在列表下方创建新行并将光标移动到新行other
: 具体见按钮悬浮时显示的内容
- NodeJs >= 18.0.0
- npm >= 8.0.0
- 使用 git 指令克隆仓库:
git clone git@github.com:EmptyDreams/krich.git
一般使用 ssh 连接会更加稳定,不会被墙,如果 git 没有登录的话只能使用 https 连接克隆:git clone https://github.com/EmptyDreams/krich.git
- 在仓库根目录下启动命令提示符
- 执行
npm install
- 执行
npm install rollup -g
- 执行
rollup -c
- 在浏览器中打开
http://localhost:3000
如果 3000
与您的其它应用的端口号冲突,可以在 rollup 配置文件中修改这个端口号。
在项目根目录执行 git pull
即可更新项目,如果您不是通过 git 克隆的仓库,那么该指令很可能将无法工作。
更新后推荐使用 npm install
指令更新依赖,避免由于依赖更新导致运行失败。
项目已经发布到 npm 仓库,您可以使用 jsdelivr
等 CDN 将 JS 文件引入到网站中。
下面为引用示例,从中选区一个方法即可(尖括号表示需要用户替换填写内容,圆括号为可选项):
- 传统脚本:
<script (defer/async) src="https://<YourCdnDomain>/npm/krich@<version>/dist/krich(.min).js"></script>
- ESMAScript:
<script type="module" (defer/async) src="https://<YourCdnDomain>/npm/krich@<version>/dist/krich-es(.min).js"></script>
建议在本地开发、调试时使用未压缩的版本,压缩版本中删除了所有的 console.assert
语句。
导入脚本并执行后,krich 将会声明一个名为 KRich
的全局函数,使用 window.KRich
或 KRich
即可获取到对象。
对于 ESMAScript,krich 会使用 export default
导出 KRich 对象,可以使用如下代码接收:
import KRich from './krich-es.js'
用于构造 krich 对象,在调用该函数时,krich
会自动向容器对象中写入 html 并完成初始化,参数中指定的容器对象必须为空。
参数类型:string|Element
string
:一个 CSS 选择表达式,用于从document
中选择容器对象Element
:手动指定容器对象
示例代码:
const krich = KRich('#krich')
用于注销 krich
,krich
会在 document
对象上注册事件,如果您的网站为单页应用且转移页面后需要重新初始化或移除 krich
,则必须调用该函数以移除 krich
注册的事件监听器。
用于设置历史记录功能最多存储的步数,默认为 25。 注意该值不要设置的过大,否则可能会导致极大的内存占用。
参数类型:number
调用示例:
krich.setHistorySize(25)
用于检查拉取到的图片是否可用。
当用户通过 URL 插入图片时,krich
会检查插入的图片是否可以访问,内置的检查算法仅检查状态码,但是部分图床在遇到错误时(404、403 等)也会返回 200,同时通过其它方法传递错误信息,该函数允许用户添加自定义的检查算法。
参数类型:function(response: Response): boolean
调用示例:
krich.setImgStatusChecker(response => !response.url.includes('403'))
用于设置图片映射器。
当用户通过本地上传的方法插入图片时,krich
会直接将 base64 存储到 html 中,当使用代码导出 html 数据时,krich
会尝试将使用 base64 编码的图片转换为 url
。
该函数就是用于将 base64 转换为 url
,注意该函数应当返回一个完整的、可访问的 URL,同时应当满足以下特征:
- 唯一性:对于不同的 base64 数据,应当返回不同的结果
- 不变性:对于相同的 base64 数据,多次调用应当返回相同的结果
- 可控性:返回的 URL 长度应当可控,在大部分浏览器允许的长度范围内
注意:不应当在该函数内处理图片的上传操作!
参数类型:function(data: string): string|Promise<string>
调用示例:
krich.setImgMapper(data => `https://example.com/img/${md5(data)}`)
用于设置实现代码高亮的函数。
krich 内置了代码块的支持,但并没有实现代码高亮的功能,需要自行通过该函数设置相应的支持。
规定:pre
使用 class
记录当前代码块的高亮类型,格式为:language-[value]
,value
的含义见下文。
参数类型:
highlighter
:function(pre: Element): Promise<void>
该参数用于实现代码高亮,其接收的pre
对象为准备进行高亮的代码块的对象,该函数应当直接修改pre
中的值(不要将pre
从 DOM 中移除或修改其在 DOM 中的位置)。 注意:pre
中一定有且只有一个code
标签,请勿将该标签移除。- 函数应当在完成高亮后再返回
languages
:function(): Array<[name: string, value: string]>
该参数用于获取代码高亮支持的语言列表,返回的每个一维数组中下标为 0 的值表示显示在浏览器页面中的语言名称,下表为 1 的值表示代码层面表示语言名称的值。 注意:- 为了方便更新语言支持列表,
krich
不会缓存该函数的返回值 krich
不会对返回的列表进行去重,注意不要返回重复的数据- 返回的
value
值krich
会统一添加language-
前缀
- 为了方便更新语言支持列表,
调用示例:
krich.setHighlight(
async pre => {
const code = pre.firstChild
const content = code.textContent
const result = await doSomething(content)
code.innerHTML = result
},
() => [
['普通文本', 'txt'],
['JavaScript', 'js'],
['Kotlin', 'kt']
]
)
用于导出编辑器数据(无参)。
返回值类型:
Promise<{
html: Element,
image?: {
upload: Map<string, string>,
remove: Set<string>
}
}>
其中 html
的是编辑区 HTML 的拷贝,可以使用 innerHTML
读取字符串格式的 HTML。
image
用于标记需要上传和需要删除的图片信息,对于 upload
,使用 key
表示 URL,value
表示 base64 数据;对于 remove
,存储的是需要删除的图片的 URL 列表。
remove
信息是通过导入的数据计算出来的,若一个 URL 在导入的数据中存在而在导出的数据中不存在,则会将其放置到 remove
中。
用于导入已有的数据。
参数类型:string
注意:该函数仅允许在编辑区域为空时使用!
调用示例:
krich.importData('<p>hello world</p>')