@graphcms/html-to-slate-ast

中文文档
0.14.2发布于 2025/12/12MITTypeScriptESM + CJS近 30 天下载 5710

Convert HTML to Hygraph's RichTextAST (slate)

原始使用文档
文档目录5 节
  1. ⚡ Usage
  2. 1. Install
  3. 2. Convert your data
  4. 3. Use it in your Content API mutations
  5. 📝 License

@graphcms/html-to-slate-ast

HTML to Slate AST converter for the Hygraph's RichTextAST format.

⚠️ This converter outputs the custom flavour of Slate AST that is used at Hygraph, and will most likely not produce an output compatible with your own Slate implementation. But feel free to fork it and adapt it to your needs.

⚡ Usage

Note: If you're using this package with Node.js, you'll need to use version 18 or higher.

1. Install

This package needs to have the packages slate and slate-hyperscript installed, and jsdom as well if you need to run the converter in Node.js.

npm install [email protected] [email protected] @graphcms/html-to-slate-ast

# for Node.js or isomorphic usage, jsdom is required
npm install jsdom

2. Convert your data

If you are using Node.js, you will need to use the htmlToSlateAST function, which returns a Promise. If you are using this package in the browser, you can use the htmlToSlateASTSync function, which is synchronous and doesn't require jsdom.

import { htmlToSlateAST } from '@graphcms/html-to-slate-ast';
// Or if you are using this package in the browser
import { htmlToSlateASTSync } from '@graphcms/html-to-slate-ast';

async function main() {
  const htmlString = '<div><p>test</p></div>'; // or import from a file or database
  const ast = await htmlToSlateAST(htmlString);
  console.log(JSON.stringify(ast, null, 2));
}

main()
  .then(() => process.exit(0))
  .catch(e => console.error(e));

3. Use it in your Content API mutations

The output of this converstion is compatible with our RichTextAST GraphQL type and can be used to import content in your Rich Text fields. Here's a mutation example:

mutation newArticle($title: String!, $content: RichTextAST) {
  createArticle(data: { title: $title, content: $content }) {
    id
    title
    content {
      html
      raw
    }
  }
}

The output generated by htmlToSlateAST will represent the children array of the Slate editor object. However, when creating or updating the value of a Rich text field, you are setting the value of the editor node itself. This means that the output should be transformed into a Rich text compatible object, for example:

const data = await client.request(newArticleQuery, {
  title: 'Example title for an article',
  content: { children: ast },
});

Here, in terms of Slate, $content is the editor node, so the $ast array must be assigned to the children key in that object. If you don't assign it to the children key, the mutation will fail with the following error.

ClientError: could not transform richText: Values should be an array of objects containing raw rich text values.

You can see the full example using graphql-request to mutate the data into Hygraph here.

See the docs about the Rich Text field type and Content Api mutations.

📝 License

Licensed under the MIT License.


Made with 💜 by Hygraph 👋 join our community!

版本与发布记录

@graphcms/html-to-slate-ast 共发布 32 个版本,首次发布于 2021/06/23;过去 12 个月发布了 1 个版本。

版本发布日期距今
0.14.2latest2025/12/1211 个月前
0.14.12024/01/312 年前
0.14.02023/12/062 年前
0.14.0-canary.5canary2023/12/062 年前
0.14.0-canary.42023/12/062 年前
0.14.0-canary.32023/12/062 年前

关于 @graphcms/html-to-slate-ast 的常见问题

@graphcms/html-to-slate-ast 是什么?

Convert HTML to Hygraph's RichTextAST (slate)

如何安装 @graphcms/html-to-slate-ast?

在项目目录运行 npm install @graphcms/html-to-slate-ast,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:slate(^0.66.1)、slate-hyperscript(^0.67.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphcms/html-to-slate-ast 支持 TypeScript 吗?

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

@graphcms/html-to-slate-ast 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@graphcms/html-to-slate-ast 可以商用吗?

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

@graphcms/html-to-slate-ast 的下载量有多少?

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

@graphcms/html-to-slate-ast 还在维护吗?

最新版本 0.14.2 发布于 2025/12/12(11 个月前);至今共发布 32 个版本,其中过去 12 个月发布了 1 个;首次发布于 2021/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。