@zhenryx/react-editor 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,169 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # @zhenryx/react-editor
2
+
3
+ 基于 contentEditable 的 React 19 富文本编辑器,内容以 **Markdown** 为唯一数据源:
4
+
5
+ - 普通编辑器:标题 / 加粗 / 斜体 / 删除线 / 列表 / 引用 / 代码块 / 表格 / 图片 / 链接 / 分割线
6
+ - 左侧目录自动收集 h1~h4,可收起为吸附按钮
7
+ - 工具栏溢出横向滚动,不换行
8
+ - 提供「切换到 Markdown 编辑器」可选入口
9
+ - 编辑结果通过 `onChange` 回传 Markdown,方便继续兼容 Markdown 存储
10
+
11
+ ## 安装
12
+
13
+ ```bash
14
+ npm install @zhenryx/react-editor
15
+ ```
16
+
17
+ ```tsx
18
+ import { RichTextEditor } from '@zhenryx/react-editor'
19
+ import '@zhenryx/react-editor/style.css'
20
+ ```
21
+
22
+ ## 基本用法
23
+
24
+ ```tsx
25
+ import { useState } from 'react'
26
+ import { RichTextEditor } from '@zhenryx/react-editor'
27
+ import { renderMarkdown } from './your-markdown-renderer'
28
+ import '@zhenryx/react-editor/style.css'
29
+
30
+ export default function Editor() {
31
+ const [markdown, setMarkdown] = useState('')
32
+
33
+ return (
34
+ <RichTextEditor
35
+ markdown={markdown}
36
+ onChange={setMarkdown}
37
+ renderMarkdown={renderMarkdown}
38
+ onUploadImage={async (file) => {
39
+ const form = new FormData()
40
+ form.append('file', file)
41
+ const res = await fetch('/api/upload', { method: 'POST', body: form })
42
+ const data = await res.json()
43
+ return data.url
44
+ }}
45
+ onSwitchToMarkdown={() => {
46
+ // 由调用方切换自己的 Markdown 编辑器
47
+ }}
48
+ />
49
+ )
50
+ }
51
+ ```
52
+
53
+ ## Props
54
+
55
+ | 属性 | 类型 | 必填 | 说明 |
56
+ | --- | --- | --- | --- |
57
+ | `markdown` | `string` | 是 | 当前内容(Markdown) |
58
+ | `onChange` | `(markdown: string) => void` | 是 | 内容变化时回传 Markdown |
59
+ | `onUploadImage` | `(file: File) => Promise<string>` | 是 | 上传图片并返回可访问 URL |
60
+ | `renderMarkdown` | `(markdown: string) => string` | 否 | Markdown → HTML 渲染器;建议传入,不传时退化为纯文本段落 |
61
+ | `onSwitchToMarkdown` | `() => void` | 否 | 显示「使用 Markdown 编辑器」按钮并触发该回调 |
62
+ | `switchLabel` | `string` | 否 | 切换按钮文案,默认「使用 Markdown 编辑器」 |
63
+ | `placeholder` | `string` | 否 | 正文占位文案,默认「开始写正文…」 |
64
+ | `className` | `string` | 否 | 追加到根节点 `.rre-root` |
65
+ | `features` | `RichTextEditorFeatures` | 否 | 按按钮控制功能开关,不传 = 全部开启 |
66
+
67
+ ### features 字段
68
+
69
+ 每个字段传 `false` 即可隐藏对应按钮;分组内按钮全部隐藏时,分隔线自动消失。
70
+
71
+ | 字段 | 对应按钮 |
72
+ | --- | --- |
73
+ | `undo` / `redo` | 撤销 / 重做 |
74
+ | `format` | 格式下拉(正文 / 标题一~四) |
75
+ | `bold` / `italic` / `strike` | 加粗 / 斜体 / 删除线 |
76
+ | `list` / `orderedList` | 无序 / 有序列表 |
77
+ | `quote` / `hr` | 引用 / 水平线 |
78
+ | `code` / `table` | 代码块 / 表格 |
79
+ | `image` / `link` | 图片 / 链接 |
80
+ | `toc` | 左侧目录与收起吸附按钮 |
81
+ | `history` | 历史快照 |
82
+ | `color` / `background` | 文字颜色 / 背景色 |
83
+ | `other` | 其他样式(倾斜 / 下划线 / 删除线) |
84
+ | `align` | 对齐(左 / 中 / 右 / 两端) |
85
+ | `video` / `formula` | 视频 / LaTeX 公式 |
86
+ | `template` | 模板 |
87
+ | `wide` | 宽屏 |
88
+ | `todo` | 待办清单(Markdown 编辑器) |
89
+ | `codeRun` | 代码运行(JS 沙箱) |
90
+ | `save` | 保存草稿按钮 |
91
+ | `sidebar` / `outline` / `syntax` | Markdown 右侧栏 / 目录 / 语法 |
92
+ | `importMd` / `exportMd` | Markdown 导入 / 导出(更多操作) |
93
+
94
+ ```tsx
95
+ <RichTextEditor
96
+ markdown={markdown}
97
+ onChange={setMarkdown}
98
+ renderMarkdown={renderMarkdown}
99
+ onUploadImage={upload}
100
+ features={{
101
+ image: false,
102
+ table: false,
103
+ toc: false,
104
+ }}
105
+ />
106
+ ```
107
+
108
+ ## Markdown 编辑器
109
+
110
+ 同时导出 `MarkdownEditor` 和 `MarkdownRichEditor`:
111
+
112
+ ```tsx
113
+ import { MarkdownRichEditor } from '@zhenryx/react-editor'
114
+
115
+ <MarkdownRichEditor
116
+ markdown={markdown}
117
+ onChange={setMarkdown}
118
+ renderMarkdown={renderMarkdown}
119
+ onUploadImage={upload}
120
+ onSave={saveDraft}
121
+ fileBaseName="article"
122
+ />
123
+ ```
124
+
125
+ - 顶部 Markdown / 比对 / 预览 / 使用普通编辑器
126
+ - 列表:无序 / 有序 / 待办
127
+ - 代码块:语言选择
128
+ - 更多格式:引用 / 代码运行(仅 JavaScript,iframe 沙箱)
129
+ - 更多插入:视频 / 表格
130
+ - 更多操作:撤销 / 重做 / 导入 md / 导出 md
131
+ - 右侧栏:收起 / 目录 / 语法(不含 AI、营销组件)
132
+ - 按要求不实现模板与资源绑定
133
+
134
+ 富文本的颜色 / 背景 / 对齐 / 下划线 / 视频会以受限内联 HTML 写入 Markdown;渲染器需放行 `<u>`、`<span style="color/background-color/text-align/display">` 和 `<video src controls>`。
135
+
136
+ ## 样式
137
+
138
+ 必须引入:
139
+
140
+ ```ts
141
+ import '@zhenryx/react-editor/style.css'
142
+ ```
143
+
144
+ 组件根类名为 `.rre-root`,内部样式均以 `rre-` 前缀隔离,不依赖宿主项目的 CSS 变量。
145
+
146
+ ## 数据约定
147
+
148
+ - `onChange` 输出的始终是 Markdown。
149
+ - 普通编辑器支持的格式都可逆转换为 Markdown:标题、粗体、斜体、删除线、列表、任务清单、引用、代码块(保留语言)、表格、链接、图片、分割线。
150
+ - 颜色、对齐、公式、视频等 Markdown 无法表达的样式不会写入数据。
151
+ - 代码块兼容知识库 `renderMarkdown` 输出的 `.kb-code` / `.kb-code-lang` 包装。
152
+
153
+ ## 本地开发
154
+
155
+ ```bash
156
+ npm install
157
+ npm run dev # tsdown --watch
158
+ npm run typecheck
159
+ npm run build # dist/:esm + cjs + d.ts + style.css + sourcemap
160
+ ```
161
+
162
+ ## 发布
163
+
164
+ ```bash
165
+ npm run build
166
+ npm publish --access public
167
+ ```
168
+
169
+ 发布后把宿主项目的依赖从本地 `file:` 改成 `^0.1.0` 即可。