# @astryx-vue/richtext 中文文档

规范地址：https://npmcn.com/package/%40astryx-vue/richtext/

版本：0\.7\.14
npm 元数据更新时间：2026-11-07T17:58:28.903Z
中文译文更新时间：2026-11-07T20:10:40.121Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40astryx-vue/richtext
原文对照：https://npmcn.com/package/%40astryx-vue/richtext/?lang=original
项目主页：https://astryx-vue.pages.dev/
源码仓库：https://github.com/astryx-vue/astryx-vue

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

- 包体积（解压后）：233 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue ^3\.5\.0，lexical 0\.52\.0，@lexical/code 0\.52\.0，@lexical/html 0\.52\.0，@lexical/link 0\.52\.0，@lexical/list 0\.52\.0，@lexical/table 0\.52\.0，@lexical/utils 0\.52\.0，@astryx-vue/core ^0\.7\.14，@lexical/history 0\.52\.0，@lexical/headless 0\.52\.0，@lexical/markdown 0\.52\.0，@lexical/extension 0\.52\.0，@lexical/rich-text 0\.52\.0，@lexical/selection 0\.52\.0
- 首次发布：2026-11-01T06:29:52.862Z
- 最新版本发布：2026-11-07T17:58:28.519Z
- 近 30 天下载量：2687（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

Vue 的 Astryx 丰富文本—— Lexical 节点和无损失的 Markdown 导入/导出. 不隶属于Meta.

## 安装

```sh
npm install @astryx-vue/richtext
```

也可以使用：`pnpm add @astryx-vue/richtext`、`yarn add @astryx-vue/richtext`、`bun add @astryx-vue/richtext`

## README

# @astryx-vue/richtext

Astryx 富文本（`@astryxdesign/richtext`）的 Vue 3 移植版：基于 Lexical 的所见即所得编辑器、只读视图、工具栏，以及原样往返的 Markdown 导入导出。本项目是非官方移植，与 Meta 无关。

## 安装

```sh
pnpm add @astryx-vue/richtext
pnpm add lexical @lexical/code @lexical/extension @lexical/headless @lexical/history @lexical/html @lexical/link @lexical/list @lexical/markdown @lexical/rich-text @lexical/selection @lexical/table @lexical/utils
```

`vue` 和 `@astryx-vue/core` 是同级的必需依赖。Lexical 那一组是可选 peer 依赖，版本和上游锁在同一个次版本（现在是 `^0.52.0`），只有用到编辑器的部分才需要。

样式分文件，可以整份引入，也可以按需：

```ts
import '@astryx-vue/richtext/richtext.css'
```

> `@lexical/headless` 自己带 `happy-dom` 依赖，所以为了服务端转换装它也会装 `happy-dom`。这是 Lexical 的选择，上游也一样。

## 用法

```vue
<script setup lang="ts">
import { RichTextEditor, RichTextEditorToolbar } from '@astryx-vue/richtext'
</script>

<template>
  <RichTextEditor label="发版说明" @change="(state) => save(JSON.stringify(state.toJSON()))">
    <template #toolbar>
      <RichTextEditorToolbar />
    </template>
  </RichTextEditor>
</template>
```

`RichTextEditor` 是非受控的：`defaultValue` 只在创建时读一次，之后内容的变化通过 `@change` 交出来。通过模板引用可以拿到 `focus()`、`clear()`、`getEditorState()`、`getMarkdown()`、`getHTML()`、`getEditor()`。

只读有两套：`<RichTextEditor is-read-only>` 是带标签的表单字段；`<RichTextView :value="json">` 是纯文档内容，没有表单控件的角色，适合展示读进来的持久化内容。

## Markdown 往返

`@astryx-vue/richtext/markdown` 不引入 Vue 组件、不碰 DOM，在 Node、Worker 或者服务端渲染里都能用。

```ts
import { editorStateJSONToMarkdown, markdownToEditorStateJSON } from '@astryx-vue/richtext/markdown'

const state = markdownToEditorStateJSON('# 标题\n\n一些 *强调*。\n')
const markdown = editorStateJSONToMarkdown(state)
```

导入时保留原文：没改过的块原样导出，列表标记、缩进、转义、`&amp;` 这类字符引用、围栏的反引号个数都还在；只有改动过的块按规范写法重写。读文档用的是 core `Markdown` 组件同一套解析器，所以两边对同一篇文档的理解一致。

## 其它导出

-   `createRichTextExtension`：采用一个用 `createMarkdownPlugin` 做的 Markdown 插件，让它的节点在编辑器和只读视图里按 core `Markdown` 的方式渲染。
-   `sanitizeUrl`、`validateUrl`：链接地址的白名单检查，只放行 http、https、mailto、tel。
-   `RichTextEditorAutoLinkPlugin`：把输入或粘贴的网址、邮箱自动变成链接，可选。

## 许可证

MIT

## 常见问题

### @astryx-vue/richtext 是什么？

Vue 的 Astryx 丰富文本—— Lexical 节点和无损失的 Markdown 导入/导出\. 不隶属于Meta\.

### 如何安装 @astryx-vue/richtext？

在项目目录运行 npm install @astryx-vue/richtext，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.0）、@astryx-vue/core（^0\.7\.14）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @astryx-vue/richtext 支持 TypeScript 吗？

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

### @astryx-vue/richtext 支持 ESM 还是 CommonJS？

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

### @astryx-vue/richtext 可以商用吗？

@astryx-vue/richtext 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @astryx-vue/richtext 的下载量有多少？

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

### @astryx-vue/richtext 还在维护吗？

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