@godxjp/block-editor

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

Block editor for GoDX apps (Notion / note.com style) on Tiptap: slash menu, block handles, floating format toolbar; reads and writes Markdown through @godxjp/markdown/codec, IME-safe, ja / en / vi.

原始使用文档
文档目录3 节
  1. What it does
  2. Contract
  3. RichTextEditor and TranslatableRichText — HTML fields

@godxjp/block-editor

A Notion / note.com style block editor for GoDX apps, on Tiptap v3 (MIT parts only). It reads and writes Markdown: the document is @godxjp/markdown/codec's, so what onValueChange returns is byte-for-byte normalize(body) — the same canonical form a server computes with the same codec.

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)}
/>;

What it does

  • / block menu at the caret (also / from a Japanese keyboard): text, headings, lists, to-do, quote, callout, code, divider, image, table, toggle, columns — filtered as you type (h2, h2, 見出し), ↑↓ Enter Esc. Host rows through actions.
  • ⋮⋮ handle and + beside the block under the pointer (the caret's block on touch): drag to move, click for turn into / duplicate / move / delete. From the keyboard: Alt+Shift+↑/↓ moves a block, Mod+/ opens its menu.
  • Format toolbar on a selection: bold, italic, strikethrough, code, link (only marks Markdown can store — there is no underline).
  • Markdown shortcuts (# , - , 1. , > , ```, ---, [[x]]), and plain-text paste is read as Markdown.
  • Uploads: paste / drop / pick a file → an inline placeholder with progress; failure offers Retry / Remove; deleting the placeholder aborts the host's signal.
  • Directive blocks: a container directive the kit does not model (:::poll[…]{…}, ::::form) is ONE atomic block — dragged, deleted and inserted whole — showing the host's preview for its name (directives), or its source; "Edit source" edits its Markdown. A host / row inserts one with api.insertMarkdown(skeleton).
  • Lossless: anything else the editor does not model (raw HTML, footnotes, a malformed toggle or column row) is a raw block showing its source, editable as source.
  • IME-safe (menus read the committed document), ja / en / vi, a named textbox with the WAI-ARIA popup wiring on the / and [[ lists, the kit's Prose as the editing surface.

Contract

prop
value / defaultValue / onValueChangeMarkdown in, canonical Markdown out
upload(file, { signal })→ { url, name? } — the same shape as MarkdownEditor
pickMedia()→ { url, name? } | null — the host's library
suggestWikilinks(query)→ { target, label?, heading?, description? }[]
renderEmbed(target)a block embed ![[target]]
resolveUrl(url)display URL for a stored one (asset:<id>)
directives{ [name]: (block, controls) => ReactNode | undefined } previews
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:::"),
    },
  ]}
/>

A preview can change its own block (gh#1479): controls.update(markdown) replaces the block's source exactly like "Edit source" → Done (still one directive: the same block, one undo step; anything else takes its place), controls.remove() deletes it, and controls.editable is false in a read-only or disabled editor. A host's picker or config form writes its result back this way:

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

The grammar it reads and writes is specified in @godxjp/markdown's README ("Grammar v1 and the codec"). The editor's schema is tested to round-trip every fixture exactly: serialize(editor.getJSON()) === normalize(markdown).

RichTextEditor and TranslatableRichText — HTML fields

For columns that already hold HTML (a product description a storefront renders), the package also ships a form field with a fixed toolbar — bold, italic, strike, inline code · H1–H3, bulleted / numbered list, quote · undo, redo — and its per-locale form (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>;
  • The schema is the sanitiser: value (and a paste) is parsed into, and onValueChange emits, only p br h1 h2 h3 ul ol li blockquote strong em s code (RICH_TEXT_ALLOWED_TAGS) with no attributes except an integer start on <ol>. Anything else — script, links, images, styles, h4–h6, tables — is kept as its text. An empty body is "".
  • A value from outside (a reset, a locale tab) replaces the document without calling onValueChange, and never while an IME composition is open.
  • It takes FormField's id / aria-* on the editable; status / aria-invalid paint the frame.
  • TranslatableRichText is the kit's TranslatableField engine around it — the same contract as TranslatableInput: locales and first tab from AppProvider contentLocales, per-locale error marks, the active error in FormField, and the fallback locale's text as an empty locale's placeholder.

版本与发布记录

@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 是什么?

Block editor for GoDX apps (Notion / note.com style) on Tiptap: slash menu, block handles, floating format toolbar; reads and writes Markdown through @godxjp/markdown/codec, IME-safe, ja / en / vi.

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