@kaitify/react

基于 React 构建的富文本编辑器 UI 库

官方文档 · GitHub · 更新日志

---

简介

kaitify-react 是基于 @kaitify/core 开发的 React 富文本编辑器 UI 库，使用 React 进行视图渲染，提供开箱即用的编辑器组件与内置菜单。

• 最低支持 React 18，与 React 生态深度结合
• ReactNode 视图渲染，响应式状态管理
• 丰富的内置组件：提供 Wrapper、Bubble、Menu 等核心组件，以及大量开箱即用的内置菜单
• Bubble 气泡栏：跟随光标浮动显示，提供上下文工具栏
• useEditor Hook：在子组件中便捷访问编辑器状态
• 多语言支持：内置中文简体、英文、韩语、日语多语言环境

---

安装

npm / yarn / pnpm

# npm
npm install @kaitify/react

# yarn
yarn add @kaitify/react

# pnpm
pnpm add @kaitify/react

CDN

<!-- UMD 版本（全局变量方式） -->
<script src="https://unpkg.com/@kaitify/react/lib/kaitify-react.umd.js"></script>

---

快速上手

import { useState } from 'react'
import { Wrapper } from '@kaitify/react'

export default function App() {
  const [content, setContent] = useState('<p>hello</p>')
  return <Wrapper value={content} onChange={v => setContent(v)} options={{ placeholder: '输入正文内容...' }}></Wrapper>
}

---

核心组件

Wrapper

编辑器核心组件，自动创建编辑器实例，通过 value / onChange 实现受控模式。

import { useState } from 'react'
import { Wrapper } from '@kaitify/react'

export default function App() {
  const [content, setContent] = useState('<p>hello</p>')
  return <Wrapper value={content} onChange={v => setContent(v)} options={{ placeholder: '输入正文内容...' }}></Wrapper>
}

主要 Props：

属性	类型	说明
value	string	编辑器内容
onChange	(value: string) => void	内容变化事件
locale	LocaleType	语言环境，默认 zh-CN
before	ReactNode | ((state: StateType) => ReactNode)	编辑器前面的内容
after	ReactNode | ((state: StateType) => ReactNode)	编辑器后面的内容
children	ReactNode | ((state: StateType) => ReactNode)	用于渲染气泡栏
options	Omit<EditorConfigureOptionType, 'el' | 'value' | 'onChange' | 'onUpdateView'>	编辑器配置

Bubble

气泡栏组件，跟随编辑器光标浮动显示，必须放置在 Wrapper 的 children 中。

import { useState } from 'react'
import { Wrapper, Bubble } from '@kaitify/react'

export default function App() {
  const [content, setContent] = useState('<p>hello</p>')
  return (
    <Wrapper value={content} onChange={v => setContent(v)} options={{ placeholder: '输入正文内容...' }}>
      <Bubble visible={true}>我是气泡栏</Bubble>
    </Wrapper>
  )
}

Menu

菜单按钮组件，提供统一的 UI 样式，必须在 Wrapper 的插槽中使用。

import { useState } from 'react'
import { Wrapper, Menu } from '@kaitify/react'

export default function App() {
  const [content, setContent] = useState('<p>hello</p>')
  return <Wrapper value={content} onChange={v => setContent(v)} options={{ placeholder: '输入正文内容...' }} before={<Menu>菜单按钮</Menu>}></Wrapper>
}

Divider

分隔线组件。

import { Divider } from '@kaitify/react'

;<Divider />

Checkbox

复选框组件。

import { Checkbox } from '@kaitify/react'

;<Checkbox />

Tabs

选项卡组件。

import { Tabs } from '@kaitify/react'

;<Tabs />

Icon

图标组件。

import { Icon } from '@kaitify/react'

;<Icon value="icon-name" />

---

useEditor Hook

在 Wrapper 的子组件中，可通过 useEditor Hook 获取编辑器上下文数据。

import { useEditor } from '@kaitify/react'

function Toolbar() {
  const { state, wrapperRef, isMouseDown } = useEditor()
  const editor = state.editor.value

  return <button onClick={() => editor?.commands.setBold()}>加粗</button>
}

返回值说明：

属性	类型	说明
state	StateType	编辑器状态（含 editor.value 和 selection.value）
wrapperRef	MutableRefObject<HTMLDivElement | null>	编辑器 DOM 元素
isMouseDown	boolean	编辑器内鼠标是否按下
t	(key: string) => string	国际化翻译函数

---

内置菜单

可直接从 @kaitify/react 引入以下内置菜单组件使用：

AlignCenterMenu AlignJustifyMenu AlignLeftMenu AlignRightMenu AttachmentMenu BackColorMenu BlockquoteMenu BoldMenu ClearFormatMenu CodeMenu CodeBlockMenu CodeBlockLanguagesMenu ColorMenu DecreaseIndentMenu EmojiMenu FontFamilyMenu FontSizeMenu FullScreenMenu HeadingMenu HorizontalMenu ImageMenu IncreaseIndentMenu ItalicMenu LineHeightMenu LinkMenu LinkUnsetMenu MathMenu OrderedListMenu RedoMenu StrikethroughMenu SubscriptMenu SuperscriptMenu TableMenu TableUnsetMenu TableDeleteRowMenu TableDeleteColumnMenu TableAddRowMenu TableAddColumnMenu TableMergeCellMenu TaskMenu UnderlineMenu UndoMenu UnorderedListMenu VideoMenu VideoControlsMenu VideoMutedMenu VideoLoopMenu WrapDownMenu WrapUpMenu

---

国际化

通过 Wrapper 组件的 locale 属性设置语言环境，支持以下取值：

值	语言
zh-CN	中文简体（默认）
en-US	英文
ko-KR	韩语
ja-JP	日语

import { useState } from 'react'
import { Wrapper } from '@kaitify/react'

export default function App() {
  const [content, setContent] = useState('<p>hello</p>')
  return <Wrapper locale='en-US' value={content} onChange={v => setContent(v)} options={{ placeholder: '输入正文内容...' }}></Wrapper>
}

---

更多内容

完整的 API 文档、组件详情、进阶用法等内容，请访问官方文档。

---

更新日志

查看更新日志

---

License

MIT © so-better