# @frontlit/page-builder 中文文档

规范地址：https://npmcn.com/package/%40frontlit/page-builder/

版本：0\.1\.0-alpha\.9
npm 元数据更新时间：2026-11-15T09:51:48.985Z
中文译文更新时间：2026-11-15T23:43:41.079Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40frontlit/page-builder
原文对照：https://npmcn.com/package/%40frontlit/page-builder/?lang=original
项目主页：https://github.com/codelitdev/frontlit/tree/main/packages/page-builder
源码仓库：https://github.com/codelitdev/frontlit

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

- 包体积（解压后）：5.3 MB，150 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：23 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-08-19T15:16:34.579Z
- 最新版本发布：2026-11-15T09:49:26.022Z
- 近 30 天下载量：1990（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

基于块的 WYSIWYG 页面构建器和渲染器

## 安装

```sh
npm install @frontlit/page-builder
```

也可以使用：`pnpm add @frontlit/page-builder`、`yarn add @frontlit/page-builder`、`bun add @frontlit/page-builder`

## README

# @ frontlit/ 页面构建器

基于块的页面构建器和渲染器用于React. 自成一体——无后端和框架锁定. 主题,块,以及WYSIWYG建设者都运行客户端.

**你和你的探员可以在同一页上合作.** 人们在WYSIWYG的构建器中进行视觉编辑. AI代理编辑同页数据,即平面JSON(块外加他们的设置),没有涉及截图或浏览器自动化. 两种编辑方式都经过同一份草稿并发布流出,这样可以在一个代理在开始直播前审查一个构建者的变化,而一个代理可以拾取你留下的地方.

-   **在前线**,代理使用 MCP 服务器的页面和主题工具: `list_pages`, (中文(简体) ), `get_page`, (中文(简体) ), `create_page`, (中文(简体) ), `update_page`, (中文(简体) ), `publish_page`, (中文(简体) ), `discard_page_draft`, (中文(简体) ), `list_themes`, (中文(简体) ), `create_theme`, (中文(简体) ), `update_theme` 和匹配的删除工具.
-   **教一个编码代理写好 FrontLit 页面**,安装 [前置技能](https://github.com/codelitdev/frontlit-skills)。 。 。 .
-   **在自己的应用中**,构建器的布局通过 `onChange` 和你经纪人读和写的JSON一样 见 [`docs/ai-editing.md`](https://npmcn.com/package/%40frontlit/page-builder/docs/ai-editing.md) 用于计划中的建设者AI编辑设计.

丰富的文本编辑和渲染 [`@frontlit/text-editor`](https://www.npmjs.com/package/@frontlit/text-editor),该软件包依赖并自动安装.

## 安装

```sh
npm i @frontlit/page-builder
# or
pnpm add @frontlit/page-builder
```

同伴依赖性 : `react` 财务报告和审定财务报表 `react-dom` (^18或^19) (中文(简体) ). 下一个J是 **没有** 所需经费。 尾风是 **没有** 需要 - 导入已编译的样式表 :

```ts
import "@frontlit/page-builder/styles.css";
```

文件包括公用设施、默认符号、取出主题的字体(Inter、Playfair和其余),以及来自TipTap的道具样式 `@frontlit/text-editor`。已经通过 `next/font` 继续工作 : `--font-inter` 在文档中仍然获胜.

**未来:** 将选择主题者的脸从 `styles.css` 进入选入 `@frontlit/page-builder/fonts.css`。已经装入 Inter、 Playfair 和 其余的主机(例如通过 `next/font`)可以跳过该文件;其他人在旁边导入该文件 `styles.css`。 。 。 . `--font-*` 和系统反弹 `theme.css` 保持原样.

如果主机已经运行了 Tailwind CSS v4, 您可以跳过 `styles.css` 并扫描包代替。 导入内容丰富且代码块

```css
@import "@frontlit/page-builder/theme.css";
@import "@frontlit/text-editor/prose.css";
@source "./node_modules/@frontlit/page-builder";
@source "./node_modules/@frontlit/text-editor";
```

## 使用量

```tsx
import {
    PageRenderer,
    PageBuilder,
    createDefaultLayout,
    getDefaultTheme,
} from "@frontlit/page-builder";
import "@frontlit/page-builder/styles.css";

// Read-only rendering (a published page, a marketing site, a preview):
<PageRenderer
    layout={createDefaultLayout()}
    theme={getDefaultTheme()}
    pageData={{ pageType: "landing" }}
/>;

// The interactive editor — persist however you like:
<PageBuilder
    onChange={({ layout, theme }) => {
        /* save */
    }}
/>;
```

两者 `PageRenderer` 财务报告和审定财务报表 `PageBuilder` 是客户部件(该包船带有 `"use client"` 关于UI条目的指示).

### 可选:客户端路由

内部 `/...` 链接变为本地 `<a>` 默认标记,所以包在Vite,Remix,Astro,或任何其他反应主机中工作. next.js(或任何其他路由器)可以注入自己的链接:

```tsx
import Link from "next/link";
import {
    PageRenderer,
    type PageBuilderLinkProps,
} from "@frontlit/page-builder";

function AppLink(props: PageBuilderLinkProps) {
    return <Link {...props} />;
}

<PageRenderer layout={layout} theme={theme} linkComponent={AppLink} />;
```

`PageBuilder` 接受相同的建议 `linkComponent` 道具并转发到直播预览.

### 服务器渲染( React Server 组件)

`PageRenderer` 是客户端组件。 要在服务器上渲染已公布的页面, 请使用 `ServerPageRenderer` 从 `@frontlit/page-builder/server`:静态块在服务器上渲染并发送无JavaScript;只有交互部分(移动菜单,marquee,电子邮件/支持表,复制按钮,链接)是客户端岛屿.

```tsx
import { ServerPageRenderer } from "@frontlit/page-builder/server";
import { resolveTheme } from "@frontlit/page-builder/theme";

const theme = resolveTheme(themeId, themeStyle);

<ServerPageRenderer layout={layout} theme={theme} pageData={pageData} />;
```

因为没有任何东西作为函数跨越服务器/客户端边界,所以不需要回调. 相反:

-   **链接** ——将页面包装在客户端组件中,使 `PageBuilderLinkProvider` (从) `@frontlit/page-builder/islands/nav-link`用你的路由器链接.
-   **轻/暗控制** ——通过即时客户要素作为 `themeSwitcher` (例如,以 `@frontlit/page-builder/islands/theme-mode-switcher`);在页脚中显示.
-   **图像** - 打电话 `setImageAttributesResolver` 在启动时交换图像 `src`编号 :`srcSet` 用于您优化器的 URL( 网站应用程序使用 Next ) `getImageProps`) (中文(简体) ).
-   **黑暗模式** 区域背景与 `dark` 在祖先的类,所以服务器不需要颜色模式.

服务器构建与主捆绑分开( Name`tsup.server.config.ts`:其客户岛屿列于 `tsup.islands.ts`,用一个 `"use client"` ,并按服务器条目导入 。 需要状态或效果的块要么必须生活在该列表中,要么被拆分,这样只有它的互动部分才会这样做. 服务器渲染器所用的块搜索是 `src/server/registry.ts`; 保持与 `src/registry.ts` 当添加块时.

## 里面的东西

| 子路径 | 出口的东西 |
| --- | --- |
| `@frontlit/page-builder` | 底下的东西,从一个地方再出口 |
| `@frontlit/page-builder/models` | `Theme`, (中文(简体) ), `WidgetInstance`, (中文(简体) ), `Widget<T>`, (中文(简体) ), `Page`, (中文(简体) ), `Media`等(再出口) `TextEditorContent` 从 `@frontlit/text-editor`(中文(简体) ) |
| `@frontlit/page-builder/primitives` | 主题 UI 原子 (`Button`, (中文(简体) ), `Header1-4`, (中文(简体) ), `Section`, (中文(简体) ), `PageCard`,.)+内置主题 |
| `@frontlit/page-builder/components` | 共享演示文稿位 : `Image`, (中文(简体) ), `NavLink`, (中文(简体) ), `VideoWithPreview` (再出口) `TextRenderer` 从 `@frontlit/text-editor`(中文(简体) ) |
| `@frontlit/page-builder/blocks` | 块库:头,英雄,内容,地物,Faq,定价,Banner,EmailForm,Foder, |
| `@frontlit/page-builder/renderer` | `PageRenderer` - 做一个页面的 `WidgetInstance[]` 布局,带有 `editing` 用于构建器内部的模式 |
| `@frontlit/page-builder/builder` | `PageBuilder` ——完整的WYSIWYG编辑器(添加/再移动/重排块,编辑设置,切换主题) |
| `@frontlit/page-builder/data-slots` | 服务器安全帮助主机在渲染前解析命名的数据槽 |
| `@frontlit/page-builder/server` | `ServerPageRenderer`, (中文(简体) ), `setImageAttributesResolver` ——服务器组件页面渲染(见上文) |
| `@frontlit/page-builder/theme` | `resolveTheme`, (中文(简体) ), `themes`, (中文(简体) ), `generateThemeStyles` ——服务器可调用,对客户端组件来说足够轻 |
| `@frontlit/page-builder/primitives/server` | 从服务器组件调取的无钩原始 |
| `@frontlit/page-builder/islands/*` | 小岛屿`nav-link`, (中文(简体) ), `theme-mode-switcher`) 主机可以在没有完整客户端捆绑的情况下导入 |

`createDefaultLayout()` 编号 : `getDefaultTheme()` (从根口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口.

`header` 财务报告和审定财务报表 `footer` 需要布局级块。 建造者通过添加来修复遗留物或空出初始布局,使其保持在外缘上,绝不允许移动或删除.

## 许可证

麻省理工学院

## 常见问题

### @frontlit/page-builder 是什么？

基于块的 WYSIWYG 页面构建器和渲染器

### 如何安装 @frontlit/page-builder？

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

### @frontlit/page-builder 支持 TypeScript 吗？

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

### @frontlit/page-builder 支持 ESM 还是 CommonJS？

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

### @frontlit/page-builder 可以商用吗？

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

### @frontlit/page-builder 的下载量有多少？

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

### @frontlit/page-builder 还在维护吗？

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

