@godxjp/block-editor

中文文档
33.30.5发布于 2026/11/14Apache-2.0TypeScriptES Module近 30 天下载 1.1万

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

中文使用文档
文档目录3 节
  1. 它会做什么
  2. 合同
  3. RichText编辑器和直译RichText — HTML 字段

@ godxjp/ 块编辑器

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

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, (中文(简体) ), 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
// 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 在一个 只读或已禁用编辑器。 一个主机的拾取者或配置形式以这种方式将结果写回:

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).

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 共发布 124 个版本,首次发布于 2026/10/05;过去 12 个月发布了 124 个版本。

版本发布日期距今
33.30.5latest2026/11/143 天前
33.30.42026/11/133 天前
33.30.32026/11/133 天前
33.28.62026/11/106 天前
33.28.42026/11/106 天前
33.28.32026/11/106 天前

关于 @godxjp/block-editor 的常见问题

@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 和提交记录判断。