# @goodfellow-cms/registry 中文文档

规范地址：https://npmcn.com/package/%40goodfellow-cms/registry/

版本：0\.9\.0
npm 元数据更新时间：2026-11-01T04:45:17.862Z
中文译文更新时间：2026-11-01T06:35:18.849Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40goodfellow-cms/registry
原文对照：https://npmcn.com/package/%40goodfellow-cms/registry/?lang=original
项目主页：https://goodfellow-cms.github.io/goodfellow-cms/docs/block-registries
源码仓库：https://github.com/goodfellow-cms/goodfellow-cms

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

- 包体积（解压后）：198 kB，34 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1
- 运行依赖：0 个
- 首次发布：2026-10-09T05:32:59.876Z
- 最新版本发布：2026-11-01T04:45:17.609Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Goodfellow CMS的块注册表：用shadcn/ui构建的块，站点从管理面板安装。

## 安装

```sh
npm install @goodfellow-cms/registry
```

也可以使用：`pnpm add @goodfellow-cms/registry`、`yarn add @goodfellow-cms/registry`、`bun add @goodfellow-cms/registry`

## README

# @goodfellow-cms /注册表

古德费罗的块注册表：用 [shadcn / ui](https://ui.shadcn.com/)，和一些建设与顺风仅为一些网站，其中一个网站的管理员添加和删除的管理面板的 **块** 屏幕，没有开发人员。它也是任何发布使用另一个组件库构建的Goodfellow块注册表的人的参考。

| 块 | 类别 | 推荐 |
| --- | --- | --- |
| 英雄 | 页面部分 | 是 |
| 卡片 | 页面部分 | 是 |
| 号召行动 | 页面部分 | 是 |
| 奖状 | 页面部分 | 是 |
| 请注意 | 页面部分 | 是 |
| 定价表 | 页面部分 |  |
| 常见问题解答 | 互动 | 是 |
| 选项卡 | 互动 | 是 |
| 新闻提要 | 页面部分 |  |
| 地图 | 页面部分 |  |
| 社会联系 | 页面部分 |  |
| 面板 | 页面部分 |  |
| 图像旋转木马 | 互动 |  |
| 带有快速链接的幻灯片 | 互动 |  |
| 带有节链接的内容 | 导航 |  |
| 人 | 页面部分 |  |
| 标志 | 页面部分 |  |
| 数字 | 页面部分 |  |
| 时间轴 | 页面部分 |  |
| 倒计时 | 互动 |  |
| 评论 | 互动 |  |
| 自定义HTML | 先进的 |  |

新网站由 `create-goodfellow` 从推荐的块开始，除非管理员选择“仅内置块”。

## 一个区块是如何进入一个站点的

添加块将其代码复制到站点中，如 `npx shadcn add` 他曾在一篇文章中写道：

-   块自己的文件到 `blocks/installed/<name>/`；
-   它使用的shadcn组件 `components/ui/`，以及任何其他共享代码 `components/`， `lib/` 或者 `hooks/`，除非网站已经有；
-   记录添加的内容， `blocks/installed/installed.json`，包含写入的每个文件的散列；
-   `blocks/installed/index.ts`，该网站是 `goodfellow.config.tsx` 并列出每个已安装的块。

编辑器在网站用它重新构建后提供块，主机在发布(和 `goodfellow dev` 或者 `next dev` 马上做)。当任何页面，集合页面设计，页眉或页脚使用它时，删除块被拒绝。删除会删除它所添加的文件，除非有人更改了这些文件，或者另一个已安装的块使用了这些文件。

管理面板安装与自己的注册表匹配的版本： `https://cdn.jsdelivr.net/npm/@goodfellow-cms/registry@<version>/r/{name}.json`． 在开发中, `goodfellow dev` 和 `next dev` 在网站上提供副本 `node_modules`.

## 发布您自己的注册表

Goodfellow块注册表是一个 [shadcn注册表](https://ui.shadcn.com/docs/registry) 它的块项遵循一些额外的规则。用 `npx shadcn build` 并将文件托管在任何允许浏览器请求（CORS）的地方，比如GitHub Pages，通过jsdeliver的npm，或者你自己的网站。

### 项目

block是一个 `registry:block` 项与 `meta.goodfellow`：

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "acme-gallery",
  "type": "registry:block",
  "title": "Gallery",
  "description": "Pictures in a grid that open larger when clicked.",
  "registryDependencies": ["@acme/dialog"],
  "dependencies": ["radix-ui"],
  "files": [
    { "path": "blocks/acme-gallery/block.tsx", "type": "registry:block", "content": "…" },
    { "path": "blocks/acme-gallery/gallery-grid.tsx", "type": "registry:component", "content": "…" }
  ],
  "meta": {
    "goodfellow": {
      "category": "Pictures",
      "recommended": false,
      "image": "images/acme-gallery.png",
      "version": "1.2.0"
    }
  }
}
```

-   **`name`** 成为网站内容中的块键，因此一旦发布就不要更改它。使用小写字母，数字和破折号，并以注册表自己的前缀开始名称，这样它们就不会与其他注册表的块冲突。
-   **`title`** 和 **`description`** 是管理员在Blocks屏幕上看到的。为非开发人员编写它们。
-   **`meta.goodfellow.category`** 是块在块屏幕和编辑器中列出的组。 `recommended` 一个新的网站应该从标记块开始。 `image` 是块的图片，相对于项目的地址。 `version` 在添加块时记录在站点中。
-   **文件:** 这个项目只有一个 `registry:block` 文件，其默认导出是块的Puck `ComponentConfig`． 每个项目的其他文件也会进入块的文件夹(`blocks/installed/<name>/`)，所以用相对路径(`./gallery-grid`）. 项目没有 `meta.goodfellow`，例如共享组件，都是依赖项：它们的文件将转到 `components/ui/` （`registry:ui`)， `components/` （`registry:component`)， `lib/` （`registry:lib`)或 `hooks/` （`registry:hook`)，并阻止它们导入为 `@/components/ui/dialog` 等等......。一个文件的 `target` 可以在这些文件夹中指定另一个位置。其他文件类型以及站点其他位置的文件将被拒绝。
-   **`registryDependencies`** 将项目命名为 `@namespace/name`，或者作为shadcn/ui自己的组件的普通名称(`"button"`)，与shadcn CLI一样。
-   **`registry.json`**，地址与项目(`…/r/registry.json` 用于 `…/r/{name}.json`)，列出它们，因此块屏幕可以显示它们，而无需加载每个项目。

### 包

管理面板不能安装npm包，所以每个站点都包含相同的包，block只能使用这些包。除了 `react`， `@goodfellow-cms/core`， `@goodfellow-cms/react` 和 `@puckeditor/core`，这是每个网站都有的 `class-variance-authority`， `clsx`， `cn`， `embla-carousel-react`， `lucide-react`， `radix-ui`， `tailwind-merge` 和 `tw-animate-css`． 一个项目 `dependencies` 其他任何名称都不能添加。要为列表建议一个包，请打开issue。

### 编写块

注册表块遵循与任何Goodfellow块相同的规则(参见 [AGENTS.md](https://github.com/goodfellow-cms/goodfellow-cms/blob/master/AGENTS.md#blocks)):

-   每个街区都有 `className` 支持(`className: classNameField`)，应用于其最外层的元素并与 `cx()` 从 `@goodfellow-cms/react`,最后一次。
-   使用主题的类(`bg-primary`， `text-muted-foreground`， `rounded-lg`)， shadcn的组件也使用它，所以块遵循网站的颜色和字体。
-   **给它一些文字让它被发现** 在编辑器的块搜索中，除了它的标签： `export default withKeywords(block, ["faq", "questions"])` 从 `@goodfellow-cms/react`小写。它可以包装 `withParts()`，或者反过来。
-   **命名块的部分**，所以网站的主题可以重新设计它们的样式。 `const part = useParts()` 在开始的时候 `render`,然后 `className={part("gf-my-block-title", "text-xl font-bold", className)}` 在每个部分（块自己的类，然后编辑器选择的任何东西）， `className` 最后)，并将它们与所有者的称呼一起声明： `export default withParts(block, { "gf-my-block-title": "Title" })`． 每个名字都以 `gf-` 以及项目的名称，这样它们就不会与另一个区块的名称冲突，并且一旦发布，就不会重命名或删除一个区块，因为主题会引用它们。客户端组件从块中以普通道具的形式获取其部件的类，如 `shadcn-faq` 所做的。
-   渲染链接和图像 `SiteLink` 和 `SiteImage` 从 `@goodfellow-cms/react`，和图像字段 `mediaField()`． 要将链接样式化为按钮，请给出 `SiteLink` shadcn的课程 `buttonVariants()`.
-   标签和选项是针对非技术人员的：“上面和下面的空间”，而不是“填充”。
-   `render` 除此之外不使用任何钩子 `useSite()`． 交互式部件放在一个文件中，以 `"use client"`，它获取普通值和内容(`children`（富文本）。
-   **每个交互部件一个客户端组件。** 的网站 `goodfellow build` 将块渲染的每个客户端组件作为自己的小React应用（孤岛）运行，而孤岛不共享React上下文。组件的各个部分通过上下文相互通信，如Radix的组件 `Accordion`， `AccordionItem` 和 `AccordionContent` 做，一定都要放在一个里面吗 `"use client"` 文件，块将其内容呈现为props。看到 `site/blocks/installed/shadcn-faq/` 在这里。
-   **将内容留在页面中。** 隐藏的内容，如封闭的答案或其他选项卡，应该仍然在HTML （Radix的） `forceMount`（用CSS隐藏），因此搜索引擎和没有JavaScript的访问者可以看到它。
-   在HTML和CSS足够的地方更喜欢它们 `<details>` 元素而不是客户端组件，因为带有客户端组件的页面会加载React。
-   **当客户端组件与Preact一起工作时**, `export const worksWithPreact = true` 在其 `"use client"` 文件，一旦你在那里尝试过。那些客户端组件都这么说的网站用Preact的组件运行它们 `preact/compat` 而不是React，只有它的十分之一大小；一个不把网站放在React上的网站。这里的每个交互块都是这样说的，Goodfellow的测试用Preact对每个块都进行了测试。

### 让一个网站使用它

管理员只能从网站开发者信任的注册表中添加块，因为块的代码在编辑器访问网站的管理面板中运行。把你的添加到网站中 `goodfellow.config.tsx`，它的积木出现在Goodfellow旁边的积木屏幕上：

```tsx
export default defineConfig({
  blocks: { ...blocks, ...installedBlocks },
  registries: { "@acme": "https://acme.example/r/{name}.json" },
});
```

### 让它很容易找到

调用注册中心的存储库 `goodfellow-blocks-<name>` 然后给它 `goodfellow-blocks` 主题在GitHub或GitLab，所以搜索要么找到它，作为 `goodfellow-plugin-<name>` 和 `goodfellow-theme-<name>` 做插件和主题。你也可以要求把它列在 [Shadcn的注册表目录](https://ui.shadcn.com/docs/directory)． 这个注册表是个例外，因为它是与Goodfellow一起发布的。

## 使用此注册表

-   `registry.json` 列出文件所在的块 `site/blocks/installed/`，就像他们会在一个地点一样。
-   `site/components/ui/` 和 `shadcn.json` 是块使用的shadcn/ui组件的快照，所以一个发布总是安装相同的代码。 `pnpm --filter @goodfellow-cms/registry update-shadcn` （`scripts/snapshot.mjs`)再取；检查并提交它所写的内容。不要手动编辑快照。
-   `pnpm build` （`scripts/build.mjs`)写道 `r/`，这是发布的内容：每个块和组件的项，以及它的文件 `r/registry.json`.
-   测试检查每个项是否有效，只使用允许的包，与它导入的每个文件一起安装，并呈现。

shadcn/ui组件为©shadcn，受MIT许可 `LICENSE-shadcn.md`.

## 常见问题

### @goodfellow-cms/registry 是什么？

Goodfellow CMS的块注册表：用shadcn/ui构建的块，站点从管理面板安装。

### 如何安装 @goodfellow-cms/registry？

在项目目录运行 npm install @goodfellow-cms/registry，或使用 pnpm add / yarn add / bun add。

### @goodfellow-cms/registry 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodfellow-cms\_\_registry 是否存在。

### @goodfellow-cms/registry 支持 ESM 还是 CommonJS？

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

### @goodfellow-cms/registry 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @goodfellow-cms/registry 可以商用吗？

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

### @goodfellow-cms/registry 还在维护吗？

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