# @godxjp/block-editor 中文文档

规范地址：https://npmcn.com/package/%40godxjp/block-editor/

版本：33\.30\.5
npm 元数据更新时间：2026-11-13T16:01:29.212Z
中文译文更新时间：2026-11-16T18:08:49.614Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40godxjp/block-editor
原文对照：https://npmcn.com/package/%40godxjp/block-editor/?lang=original
项目主页：https://github.com/godx-jp/godxjp-ui#readme
源码仓库：https://github.com/godx-jp/godxjp-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：133 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：14 个
- peer 依赖：react \>=19\.0\.0，react-dom \>=19\.0\.0，@godxjp/ui ~33\.30\.5，@godxjp/markdown ~33\.30\.5
- 首次发布：2026-10-05T04:52:20.164Z
- 最新版本发布：2026-11-13T16:01:28.863Z
- 近 30 天下载量：10771（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：124（近 12 个月 124 个）

## 中文简介

Tiptap上的 GODX apps (Notion / note.com style) 的块编辑器: slash 菜单,块控点,浮动格式工具栏;通过 @godxjp/markdown/codec, IME-safe, ja / en/vi来读取并写入Markdown.

## 安装

```sh
npm install @godxjp/block-editor
```

也可以使用：`pnpm add @godxjp/block-editor`、`yarn add @godxjp/block-editor`、`bun add @godxjp/block-editor`

## README

# @ godxjp/ 块编辑器

在Tiptap v3(仅限麻省理工学院部分)上,GODX应用的一款Notion / note.com风格块编辑器. 它读和 写入 **标记**: 文档是 `@godxjp/markdown/codec`那又怎样 `onValueChange` 返回为 字节换字节 `normalize(body)` ——同名克能克组成一个服务器,用同名克能克来计算.

```tsx
import { BlockEditor } from "@godxjp/block-editor";

<BlockEditor
  aria-label="本文"
  value={body}
  onValueChange={setBody}
  upload={async (file, { signal }) => ({ url: await media.put(file, { signal }), name: file.name })}
  pickMedia={() => media.pick()}
  suggestWikilinks={(query) => pages.search(query)}
  renderEmbed={(target) => <PageEmbed target={target} />}
  resolveUrl={(url) => (url.startsWith("asset:") ? media.url(url) : undefined)}
/>;
```

## 它会做什么

-   **`/` 块菜单** 在护身符上(也) `／` 从日本键盘取出:文本、标题、列表、, 待办、 引文、 呼号、 代码、 分隔符、 图像、 表格、 切换、 列—— 按键过滤 (单位:千美元)`h2`, (中文(简体) ), `ｈ２`, (中文(简体) ), `見出し`),"输入Esc. 主机行经 `actions`。 。 。 .
-   **++ 处理和+** 在指针下方的地块旁边(护身符的地块在触摸上):拖去移动, 单击可转换为 / 重复 / 移动 / 删除 。 从键盘: Alt+Shift+↑/↓移动一个块, Mod+/ 打开菜单 .
-   **格式工具栏** 在选中位置: 粗体、 斜体、 切换、 代码、 链接( 只标记 Markdown) ——没有下划线.
-   **下标快捷键** (单位:千美元)`#` , (中文(简体) ), `-` , (中文(简体) ), `1.` , (中文(简体) ), `>` , (中文(简体) ), ` ``` `, (中文(简体) ), `---`, (中文(简体) ), `[[x]]`)和简洁文本 贴被读作"Markdown".
-   **上传**: 粘贴 / 放下 / 选择一个文件 / 一个内含的占位符, 并有进展; 失败报价 重试/ 删除; 删除占位符中止主机 `signal`。 。 。 .
-   **指令块**: 包件没有模型的容器指令(`:::poll[…]{…}`, (中文(简体) ), `::::form`)是 One 原子块——被拖走,被删除并插入整个块——显示主机的预览 名称(`directives`),或它的源;"编辑源"编辑它的Markdown. 一个主机 `/` 横行 插入一个 `api.insertMarkdown(skeleton)`。 。 。 .
-   **无损失**: 编辑器没有模型的任何东西(raw HTML、脚注、错误的切换或 栏行)是显示其源的生块,可以作为源编辑.
-   **IME 安全** (菜单读到承诺的文件), **日/时/六**,名称 `textbox` 与 WAI -ARIA 弹出线布置在 `/` 财务报告和审定财务报表 `[[` 列表中,工具包的Prose作为编辑表面.

## 合同

| 道具 |  |
| --- | --- |
| `value` 编号 : `defaultValue` 编号 : `onValueChange` | 马克倒入,克尼克倒出 |
| `upload(file, { signal })` | `→ { url, name? }` ——形状与 `MarkdownEditor` |
| `pickMedia()` | `→ { url, name? } | null` ——主机图书馆 |
| `suggestWikilinks(query)` | `→ { target, label?, heading?, description? }[]` |
| `renderEmbed(target)` | 嵌入块 `![[target]]` |
| `resolveUrl(url)` | 显示存储的 URL (E)`asset:<id>`(中文(简体) ) |
| `directives` | `{ [name]: (block, controls) => ReactNode | undefined }` 预览 |
| `actions`, (中文(简体) ), `labels`, (中文(简体) ), `disabled`, (中文(简体) ), `readOnly`, (中文(简体) ), `autoFocus`, (中文(简体) ), `aria-*`, (中文(简体) ), `id` |  |

```tsx
// A poll is a block: the host previews it and inserts its skeleton from the `/` menu.
<BlockEditor
  value={body}
  onValueChange={setBody}
  directives={{
    // block: { name, label, attributes, source, body } — the codec's canonical Markdown
    poll: (block) => <PollPreview question={block.label} options={block.body} />,
  }}
  actions={[
    {
      key: "poll",
      label: "Poll",
      icon: <ListChecks />,
      run: (api) => api.insertMarkdown(":::poll[Question]{id=poll-1}\n- Option A\n- Option B\n:::"),
    },
  ]}
/>
```

预览可以更改自己的块(gh#1479): `controls.update(markdown)` 替换块的 源与“编辑源”完全相同 —— 完成(仍一个指令:同一个块,一个倒出步骤; 任何其它东西都会取代它, `controls.remove()` 删除它,并 `controls.editable` 在一个 只读或已禁用编辑器。 一个主机的拾取者或配置形式以这种方式将结果写回:

```tsx
directives={{
  card: (block, { update, editable }) => (
    <CardPreview id={block.attributes.card} onPick={editable ? (id) => update(`:::card{card=${id}}\n:::`) : undefined} />
  ),
}}
```

它的读写语法在 `@godxjp/markdown`读取("Grammar v1"和 代码"。 编辑器的图案通过测试 来绕行每个固定点: `serialize(editor.getJSON()) === normalize(markdown)`。 。 。 .

## RichText编辑器和直译RichText — HTML 字段

对于已经持有的列 **HTML 语言** (库存前置产品描述),包件 并且使用固定工具栏——粗体、斜体、击打、内含码 —— H1-H3 发子弹 / 编号列表, 引用 \\\\ 撤消、 重做 —— 及其每个地方的形式 (gh# 1365).

```tsx
import { RichTextEditor, TranslatableRichText } from "@godxjp/block-editor";
import { FormField } from "@godxjp/ui/data-entry";

<FormField label="説明" required>
  <TranslatableRichText value={description} onValueChange={setDescription} errors={errors} />
</FormField>;
```

-   计划是疗养: `value` (和一贴) 被解为,和 `onValueChange` 发射,只有 `p br h1 h2 h3 ul ol li blockquote strong em s code` (单位:千美元)`RICH_TEXT_ALLOWED_TAGS`无 除整数以外的属性 `start` 打开 `<ol>`。其他任何文字——脚本、链接、图像、样式、h4-h6表——都保留为正文. 一个空的躯体 `""`。 。 。 .
-   A 类 `value` 从外部( 重设、 本地化标签) 替换文档而不调用 `onValueChange`,而永远不要当一个IME组成是开放的.
-   它需要Form Field的车 `id` 编号 : `aria-*` 可编辑的; `status` 编号 : `aria-invalid` 画出相框.
-   `TranslatableRichText` 装箱的 `TranslatableField` 发动机绕着它——与 `TranslatableInput`: 来自 AppProvider 的地块和第一个标签 `contentLocales`,每个地点出错 标记、 窗体字段中的活性错误, 以及作为空地块的倒回方格文字 占位符 .

## 常见问题

### @godxjp/block-editor 是什么？

Tiptap上的 GODX apps \(Notion / note\.com style\) 的块编辑器: slash 菜单,块控点,浮动格式工具栏;通过 @godxjp/markdown/codec, IME-safe, ja / en/vi来读取并写入Markdown\.

### 如何安装 @godxjp/block-editor？

在项目目录运行 npm install @godxjp/block-editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.0\.0）、react-dom（\>=19\.0\.0）、@godxjp/ui（~33\.30\.5）、@godxjp/markdown（~33\.30\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @godxjp/block-editor 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @godxjp/block-editor 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @godxjp/block-editor 可以商用吗？

@godxjp/block-editor 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @godxjp/block-editor 的下载量有多少？

根据 npm 官方下载统计，@godxjp/block-editor 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,771 次，日均约 359 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @godxjp/block-editor 还在维护吗？

最新版本 33\.30\.5 发布于 2026/11/14（3 天前）；至今共发布 124 个版本，其中过去 12 个月发布了 124 个；首次发布于 2026/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

