# @kaitify/react
**基于 React 构建的富文本编辑器 UI 库**
[](https://www.npmjs.com/package/@kaitify/react)
[](https://github.com/so-better/kaitify-react/blob/main/LICENSE)
[](https://www.npmjs.com/package/@kaitify/react)
[官方文档](https://www.so-better.cn/docs/kaitify-react/) · [GitHub](https://github.com/so-better/kaitify-react) · [更新日志](./docs/changelog.md)
---
## 简介
`kaitify-react` 是基于 `@kaitify/core` 开发的 React 富文本编辑器 UI 库，使用 `React` 进行视图渲染，提供开箱即用的编辑器组件与内置菜单。
- **最低支持 React 18**，与 React 生态深度结合
- **ReactNode 视图渲染**，响应式状态管理
- **丰富的内置组件**：提供 `Wrapper`、`Bubble`、`Menu` 等核心组件，以及大量开箱即用的内置菜单
- **Bubble 气泡栏**：跟随光标浮动显示，提供上下文工具栏
- **useEditor Hook**：在子组件中便捷访问编辑器状态
- **多语言支持**：内置中文简体、英文、韩语、日语多语言环境
---
## 安装
### npm / yarn / pnpm
```bash
# npm
npm install @kaitify/react
# yarn
yarn add @kaitify/react
# pnpm
pnpm add @kaitify/react
# 安装指定版本
npm install @kaitify/react@0.0.1-beta.17
```
### CDN
```html
```
---
## 快速上手
```tsx
import { useState } from 'react'
import { Wrapper } from '@kaitify/react'
export default function App() {
const [content, setContent] = useState('hello
')
return setContent(v)} options={{ placeholder: '输入正文内容...' }}>
}
```
---
## 核心组件
### Wrapper
编辑器核心组件，自动创建编辑器实例，通过 `value` / `onChange` 实现受控模式。
```tsx
import { useState } from 'react'
import { Wrapper } from '@kaitify/react'
export default function App() {
const [content, setContent] = useState('hello
')
return setContent(v)} options={{ placeholder: '输入正文内容...' }}>
}
```
**主要 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` | 编辑器配置 |
### Bubble
气泡栏组件，跟随编辑器光标浮动显示，必须放置在 `Wrapper` 的 `children` 中。
```tsx
import { useState } from 'react'
import { Wrapper, Bubble } from '@kaitify/react'
export default function App() {
const [content, setContent] = useState('hello
')
return (
setContent(v)} options={{ placeholder: '输入正文内容...' }}>
我是气泡栏
)
}
```
### Menu
菜单按钮组件，提供统一的 UI 样式，必须在 `Wrapper` 的插槽中使用。
```tsx
import { useState } from 'react'
import { Wrapper, Menu } from '@kaitify/react'
export default function App() {
const [content, setContent] = useState('hello
')
return setContent(v)} options={{ placeholder: '输入正文内容...' }} before={}>
}
```
### Divider
分隔线组件。
```tsx
import { Divider } from '@kaitify/react'
;
```
### Checkbox
复选框组件。
```tsx
import { Checkbox } from '@kaitify/react'
;
```
### Tabs
选项卡组件。
```tsx
import { Tabs } from '@kaitify/react'
;
```
### Icon
图标组件。
```tsx
import { Icon } from '@kaitify/react'
;
```
---
## useEditor Hook
在 `Wrapper` 的子组件中，可通过 `useEditor` Hook 获取编辑器上下文数据。
```tsx
import { useEditor } from '@kaitify/react'
function Toolbar() {
const { state, wrapperRef, isMouseDown } = useEditor()
const editor = state.editor.value
return
}
```
**返回值说明：**
| 属性 | 类型 | 说明 |
|------|------|------|
| `state` | `StateType` | 编辑器状态（含 `editor.value` 和 `selection.value`） |
| `wrapperRef` | `MutableRefObject` | 编辑器 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` | 日语 |
```tsx
import { useState } from 'react'
import { Wrapper } from '@kaitify/react'
export default function App() {
const [content, setContent] = useState('hello
')
return setContent(v)} options={{ placeholder: '输入正文内容...' }}>
}
```
---
## 更多内容
完整的 API 文档、组件详情、进阶用法等内容，请访问[官方文档](https://www.so-better.cn/docs/kaitify-react/)。
---
## 更新日志
查看[更新日志](./docs/changelog.md)
---
## License
[MIT](./LICENSE) © [so-better](https://github.com/so-better)