# kaitify-react

**Repository Path**: so-better/kaitify-react

## Basic Information

- **Project Name**: kaitify-react
- **Description**: 基于React18+版本的web端富文本编辑器
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.so-better.cn/docs/kaitify-react/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-20
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# @kaitify/react

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

[![npm version](https://img.shields.io/npm/v/@kaitify/react)](https://www.npmjs.com/package/@kaitify/react)
[![license](https://img.shields.io/npm/l/@kaitify/react)](https://github.com/so-better/kaitify-react/blob/main/LICENSE)
[![npm downloads](https://img.shields.io/npm/dm/@kaitify/react)](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)

</div>

---

## 简介

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

---

## 快速上手

```tsx
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` 实现受控模式。

```tsx
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` 中。

```tsx
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` 的插槽中使用。

```tsx
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

分隔线组件。

```tsx
import { Divider } from '@kaitify/react'

;<Divider />
```

### Checkbox

复选框组件。

```tsx
import { Checkbox } from '@kaitify/react'

;<Checkbox />
```

### Tabs

选项卡组件。

```tsx
import { Tabs } from '@kaitify/react'

;<Tabs />
```

### Icon

图标组件。

```tsx
import { Icon } from '@kaitify/react'

;<Icon name="solar:home-bold-duotone" />
```

---

## useEditor Hook

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

```tsx
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` | 日语 |

```tsx
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 文档、组件详情、进阶用法等内容，请访问[官方文档](https://www.so-better.cn/docs/kaitify-react/)。

---

## 更新日志

查看[更新日志](./docs/changelog.md)

---

## License

[MIT](./LICENSE) © [so-better](https://github.com/so-better)