# @bettercms-ai/ui 中文文档

规范地址：https://npmcn.com/package/%40bettercms-ai/ui/

版本：0\.27\.0
npm 元数据更新时间：2026-11-02T11:05:32.070Z
中文译文更新时间：2026-11-08T00:33:58.485Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40bettercms-ai/ui
原文对照：https://npmcn.com/package/%40bettercms-ai/ui/?lang=original

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

- 包体积（解压后）：2.3 MB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-06-30T11:07:50.420Z
- 最新版本发布：2026-11-02T11:05:31.894Z
- 近 30 天下载量：3179（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

在React中渲染页面块 json(dashboard builder preview + 无头站点)的更好CMS块组件 + register/ refer.

## 安装

```sh
npm install @bettercms-ai/ui
```

也可以使用：`pnpm add @bettercms-ai/ui`、`yarn add @bettercms-ai/ui`、`bun add @bettercms-ai/ui`

## README

# 翻译:

> Npm上公布为 `@bettercms-ai/ui`。 。 。 .

共享页面构建器块组件用于BetterCMS. 包含 7 个核心块类型的演示文稿仅反应组件: **标题**, (中文(简体) ), **文本**, (中文(简体) ), **图像**, (中文(简体) ), **按钮**, (中文(简体) ), **空间器**, (中文(简体) ), **列数**,以及 **视频**。 。 。 .

这些组成部分是故意的 **哑巴** (只介绍)——没有选择状态,没有工具栏,没有内含编辑. 这种逻辑存在于管理应用程序中(`bettercms-admin`) (中文(简体) ).

## 设计哲学

此套件跟随 **shadcn/ui工作室** 模式 :

-   每个街区都有 **多样式变体** 财务报告和审定财务报表 **动画预设** 它可以组成.
-   组件归你所有——复制,修改,自由延伸.
-   包是一个 **起点**,而不是锁定的依赖.
-   动画和风格变化工作船 **后MVP**。 。 。 .

## 块类型

| 类型 | 构成部分 | 目的 |
| --- | --- | --- |
| `heading` | `Heading` | H1-H3 文本标题 |
| `text` | `Text` | 丰富文本 / HTML 内容 |
| `image` | `Image` | 带有其它文本标题的图像( C) |
| `button` | `Button` | 带有变体的 CTA 按钮 |
| `spacer` | `Spacer` | 垂直间距块 |
| `columns` | `Columns` | 有嵌入区块的多栏布局 |
| `video` | `Video` | YouTube、Vimeo或本地视频嵌入 |

## 使用量

```tsx
import { BlocksRenderer } from "@bettercms-ai/ui";
import type { ContentBlock } from "@bettercms-ai/types";

// Use with @bettercms-ai/types block JSON
const blocks: ContentBlock[] = [
  { type: "heading", id: "1", props: { text: "Hello", level: 1 } },
  { type: "text",   id: "2", props: { html: "<p>Welcome!</p>" } },
];

export function Page() {
  return <BlocksRenderer blocks={blocks} />;
}
```

## 带有自定义块渲染器( 如 admin app 添加选择状态)

```tsx
import { BlockRenderer } from "@bettercms-ai/ui";

function AdminCanvas({ block, isSelected, onSelect }) {
  return (
    <div
      onClick={() => onSelect(block.id)}
      className={isSelected ? "ring-2 ring-primary" : ""}
    >
      <BlockRenderer block={block} />
    </div>
  );
}
```

## 添加新块

1.  创建 `src/blocks/MyBlock.tsx`
2.  导出自 `src/blocks/index.ts`
3.  添加条目到 `src/registry.ts`
4.  更新 `src/index.ts`

## 添加动画变体(后MVP)

每个区块最终应暴露:

-   `animation` 道具(例如, `"fade-in"`, (中文(简体) ), `"slide-up"`, (中文(简体) ), `"stagger"`(中文(简体) )
-   `duration` 螺旋桨(毫秒)
-   `delay` 螺旋桨(毫秒)

这些是通过 Tailwind 键框在 `tailwind.config.ts`。 。 。 .

## 发展

```bash
# Install dependencies (run from backend root)
bun install

# Type-check
bun run --filter @bettercms-ai/ui typecheck

# Add a new shadcn/ui component
cd packages/ui && npx shadcn@latest add -p ../../ button
```

## 关于 npm 出版的说明

发布至npm. 管理器和网页重置器使用自己的本地shadcn/ui拷贝用于非页面构建器UI(Dialog, Sheet, Table等);这个包搭载了页面构建器块和渲染器.

## 常见问题

### @bettercms-ai/ui 是什么？

在React中渲染页面块 json\(dashboard builder preview \+ 无头站点\)的更好CMS块组件 \+ register/ refer\.

### 如何安装 @bettercms-ai/ui？

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

### @bettercms-ai/ui 支持 TypeScript 吗？

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

### @bettercms-ai/ui 支持 ESM 还是 CommonJS？

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

### @bettercms-ai/ui 可以商用吗？

@bettercms-ai/ui 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bettercms-ai/ui 的下载量有多少？

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

### @bettercms-ai/ui 还在维护吗？

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