# @craftjs/core 中文文档

规范地址：https://npmcn.com/package/%40craftjs/core/

版本：0\.2\.12
npm 元数据更新时间：2025-02-14T09:25:26.914Z
中文译文更新时间：2026-11-10T22:57:16.434Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40craftjs/core
原文对照：https://npmcn.com/package/%40craftjs/core/?lang=original
项目主页：https://github.com/prevwong/craft.js/
源码仓库：https://github.com/prevwong/craft.js

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

- 包体积（解压后）：483 kB，58 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react ^16\.8\.0 \|\| ^17 \|\| ^18 \|\| ^19
- 首次发布：2019-12-31T20:46:16.647Z
- 最新版本发布：2025-02-14T09:25:26.719Z
- 近 30 天下载量：326707（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 0 个）

## 中文简介

用于构建可扩展拖放页面编辑器的反应框架

## 安装

```sh
npm install @craftjs/core
```

也可以使用：`pnpm add @craftjs/core`、`yarn add @craftjs/core`、`bun add @craftjs/core`

## README

# 技术.js

 [![](https://img.shields.io/npm/v/@craftjs/core?color=%232680eb&label=NPM&logo=npm&logoColor=%232680eb&style=for-the-badge)](https://www.npmjs.com/package/@craftjs/core)![](https://img.shields.io/npm/l/@craftjs/core?color=%23000&style=for-the-badge)

![](https://user-images.githubusercontent.com/16416929/72202590-4d05f500-349c-11ea-9e43-1da1cb0c30e9.gif)

**[现场直播](https://craft.js.org/)**

页面编辑是提供优秀用户体验的好方法. 然而,建造一个往往是一个相当可怕的任务.

已有的库会带出一个完整的工作页编辑器出框,并带有用户界面和可编辑组件. 然而,如果您想要做自定义,比如修改用户界面及其行为,那么最肯定的就是修改库本身.

Craft.js通过模块化页面编辑器的构件来解决这个问题. 它携带拖放系统,处理用户组件的提供、更新和移动方式,等等。 有了这个,你就能建立自己的页面编辑器 确切地说,你希望它看起来和行为.

## 文档

-   [核心概念](https://craft.js.org/docs/concepts/nodes)
-   [教学](https://craft.js.org/docs/guides/basic-tutorial)
-   [API 参考](https://craft.js.org/docs/api/editor-state)

## 实例

这些例子应该可以让你了解Craft.js的灵活性.

这两个例子看起来彼此非常不同,UI也非常不同. 但他们都是手工业者

-   [着陆](https://craft.js.org/)
-   [基础](https://craft.js.org/examples/basic)

## 特征: 火:

### 只是反应

不需要复杂的插件系统 。 从上到下设计您的编辑器的方式与您在React中设计其他前端应用程序的方式相同.

简单的用户组件很容易被定义为:

```jsx
import { useNode } from "@craftjs/core";

const TextComponent = ({ text }) => {
  const {
    connectors: { connect, drag },
  } = useNode();

  return (
    <div ref={(ref) => connect(drag(ref))}>
      <h2>{text}</h2>
    </div>
  );
};

```

你页面编辑器的整个UI都是用反应构建的.

```jsx
import React from "react";
import { Editor, Frame, Element  } from "@craftjs/core";
const App = () => {
  return (
    <div>
      <header>Some fancy header or whatever</header>
      <Editor>
        // Editable area starts here
        <Frame resolver={{ TextComponent, Container }}>
          <Element canvas is={TextComponent} text="I'm already rendered here" />
        </Frame>
      </Editor>
    </div>
  );
};
```

### 控制您组件的编辑方式

对页面编辑器的一个明显要求是,它们需要允许用户编辑组件. Craft.js 中,您控制这些组件的编辑过程 .

在下面的例子中,当用户点击一个组件时,我们将显示一种模式,要求用户输入该组件的值 `text` 道具 (英语). 随着输入值的改变,该组件会用更新道具重新发回.

```jsx
import { useNode } from "@craftjs/core";

const TextComponent = ({ text }) => {
  const {
    connectors: { connect, drag },
    isClicked,
    actions: { setProp },
  } = useNode((state) => ({
    isClicked: state.events.selected,
  }));

  return (
    <div ref={(dom) => connect(drag(dom))}>
      <h2>{text}</h2>
      {isClicked ? (
        <Modal>
          <input
            type="text"
            value={text}
            onChange={(e) => setProp(e.target.value)}
          />
        </Modal>
      ) : null}
    </div>
  );
};
```

有了这个功能,您可以轻松地执行内容可编辑的文本或拖放到大小的组件,就像任何现代的页面编辑器一样.

### 有可下降区域的用户组件

假设我们需要一个"容器"组件,用户可以掉入编辑器. 此外,我们还希望它们能够把其他部件拖入集装箱.

在Craft.js语中,它和叫作 `<Canvas />`

```jsx
import {useNode} from "@craftjs/core";
const Container = () => {
  const { connectors: {drag} } = useNode();

  return (
    <div ref={drag}>
      <Canvas id="drop_section">
         // Now users will be able to drag/drop components into this section
        <TextComponent />
      </Canvas>
    </div>
  )
}
```

### 广泛

Craft.js提供一种表达式的API,可以方便地读取并操纵编辑器状态. 假设您想要执行一个组件的复制功能:

```jsx
import {useEditor, useNode} from "@craftjs/core";
const Container = () => {
  const { actions: {add}, query: { createNode, node } } = useEditor();
  const { id, connectors: {drag, connect} } = useNode();
  return (
    <div ref={dom => connect(drag(dom))}>
      ...
      <a onClick={() => {
        const { data: {type, props}} = node(id).get();
        add(
          createNode(React.createElement(type, props));
        );
      }}>
        Make a copy of me
      </a>
    </div>
  )
}

```

### 序列状态

编辑器的状态可以被序列化为JSON,然后可以应用你选择的压缩技术来存储.

```jsx
const SaveButton = () => {
  const { query } = useEditor();
  return <a onClick={() => console.log(query.serialize()) }>Get JSON</a>
}
```

当然,Craft.js也能从JSON字符串中再现出整个状态.

```jsx
const App = () => {
  const jsonString = /* retrieve JSON from server */
  return (
    <Editor>
      <Frame json={jsonString}>
        ...
      </Frame>
    </Editor>
  )
}
```

## 这是谁的

你应该用这个,如果:

-   您想要按照您自己的UI 规格设计您的页面编辑器 。 有了Craft.js,你几乎控制了页面编辑器的外观和感觉的每一个方面.
-   你喜欢反应生态系统 作为一个反应框架,你不仅可以公开地构建自己的用户界面,还可以扩展到数千个用于页面编辑器的现有反应组件.
-   你是班上最酷的小孩

您不应使用此选项 :

-   你需要一个在盒子里工作的页面编辑器 craft.js是一个抽象的,您可以执行自己的页面编辑器。 例如,它没有现成的用户界面.
    -   不过,你还可以考虑使用 [实例](https://github.com/prevwong/craft.js/tree/develop/examples) 作为起点.

## 附加套件: tada :

-   **[@ craftjs/ layers (英语)](https://github.com/prevwong/craft.js/tree/develop/packages/layers)** 类似相机的层面板

## 致谢:升起的手:

-   **[反应-dnd](https://github.com/react-dnd/react-dnd)** React 拖放库 . 虽然它实际上没有在这里使用,但Craft.js的许多方面都是用反应-dnd来写作,作为参考,同时还借用了一些公用事业和功能.
-   **[Grape.js (英语)](https://github.com/artf/grapesjs)** HTML网络构建器框架. 这为Craft.js提供了灵感。 Craft.js中使用的元素定位逻辑取自Grape.js
-   **[使用方法](https://github.com/pelotom/use-methods)** 处理减员时的超手钩. craft.js使用稍作修改的版本 `use-methods` 更适合我们的API.

## 获取帮助: wave :

如果你有问题,或者有事情想讨论(例如:贡献),请到我们那里去 [解析器](https://discord.gg/sPpF7fX) 服务器.

## 赞助商:心 装饰:

Craft.js 现根据 [麻省理工学院许可证](https://github.com/prevwong/craft.js/blob/master/LICENSE) 以百分百的爱建造 如果您认为它有用并愿意确保它的持续发展,请考虑成为支持者/赞助者,或通过下列途径一次性捐款: [Github 发起人](https://github.com/sponsors/prevwong), (中文(简体) ), [开放集体](https://opencollective.com/craftjs/contribute) 或者说 [高飞](https://ko-fi.com/prevwong)。 。 。 .

![](https://opencollective.com/craftjs/sponsors.svg?width=890) ![](https://opencollective.com/craftjs/backers.svg?width=890)

### 发起人

-   [双眼平方](https://github.com/eye-square)
-   [api4ui 密码](https://github.com/api4ui)

### 备份

-   [特克斯特·基达努](https://opencollective.com/guest-1703f486)
-   [CORS 数字](https://opencollective.com/cors-digital)
-   [物质混合](https://opencollective.com/mattermix)
-   [变种人](https://github.com/muttenzer)
-   [铁道中心](https://github.com/ITCuw)
-   [维克多·瓦内加斯](https://github.com/vicvans20)
-   [安德烈亚斯·托尔克](https://github.com/andreasthoelke)
-   [盐](https://github.com/saltcorn)

## 常见问题

### @craftjs/core 是什么？

用于构建可扩展拖放页面编辑器的反应框架

### 如何安装 @craftjs/core？

在项目目录运行 npm install @craftjs/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.8\.0 \|\| ^17 \|\| ^18 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @craftjs/core 支持 TypeScript 吗？

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

### @craftjs/core 支持 ESM 还是 CommonJS？

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

### @craftjs/core 可以商用吗？

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

### @craftjs/core 的下载量有多少？

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

### @craftjs/core 还在维护吗？

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