# @contentrain/astro-kit 中文文档

规范地址：https://npmcn.com/package/%40contentrain/astro-kit/

版本：0\.50\.9
npm 元数据更新时间：2026-11-05T10:42:55.933Z
中文译文更新时间：2026-11-10T16:54:11.403Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40contentrain/astro-kit
原文对照：https://npmcn.com/package/%40contentrain/astro-kit/?lang=original
项目主页：https://ai.contentrain.io/packages/astro-kit
源码仓库：https://github.com/Contentrain/ai

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

- 包体积（解压后）：1.3 MB，146 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-25T09:07:57.487Z
- 最新版本发布：2026-11-05T10:42:55.555Z
- 近 30 天下载量：7744（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 103 个）

## 中文简介

复制 Contentrain 站点的 Astro 组件( Shadcn 模型):输入道具,尾风变量,默认为零 JavaScript —— 有机器可读目录

## 安装

```sh
npm install @contentrain/astro-kit
```

也可以使用：`pnpm add @contentrain/astro-kit`、`yarn add @contentrain/astro-kit`、`bun add @contentrain/astro-kit`

## README

# @ contentrain/ astro- kit (英语)

复制 Contentrain 网站的 Astro 组件, 阴影模型: 一个网站 接收组件源并自此拥有。 这里什么都没有 网站的运行时间依赖性。 包装部件,a 机器可读目录、 构建器绘图表和一个小 API 复制 包含到项目中.

这些组件是为 [`templates/astro-starter`](https://npmcn.com/package/templates/astro-starter)。 。 。 . 他们读了它的设计标语,然后通过它的大门: `astro check` 与 `strictest` 预设, knip, 一个单一样式表和零 JavaScript 默认.

## 构成部分

| 编号 | 这是什么 | Java 脚本 |
| --- | --- | --- |
| `header` | 品牌、导航、可选行动呼吁 | 无; 制作 `nav` |
| `nav` | 带有子菜单的内置菜单; popover 抽屉或 `<details>` 电话 | 无; 当菜单有子菜单时有几行 |
| `footer` | 品牌、链接栏或链接行、社交链接、版权 | 无 |
| `hero` | 页面打开器:标题、文本、点、动作、图像 | 无 |
| `card-grid` | 卡片网格(专题、服务、团队) | 无 |
| `post-card` | 列表中的一个 | 无 |
| `cta` | 呼叫行动带 | 无 |
| `faq` | 问题作为 `<details>`,可选的 FAQPage JSON-LD | 无 |
| `tabs` | 有标签的面板; 可读取为标题部分, 不包含 JavaScript | Zag.js (法语) |
| `testimonial` | 有作者和角色的引文 | 无 |
| `gallery` | 图像网格; 点击打开本地 popover 或 灯盒查看器 | 无 `lightbox` 选项添加几行,不依赖 |
| `slider` | 卷轴-snap行上的卡路索:图像,视频(仅按请求播放的文件,或仅点击后加载的YouTube/Vimeo链接)或文本卡幻灯片 | 爱布拉 |
| `contact-form` | Contentrain 工作室表格在一个区域 | 工作室运行时间 |
| `newsletter` | 注册直接张贴到列表提供者(Mailchimp, Kit, MallerLite, Brevo, 按键) | 无 |
| `embed` | 视频、地图或播放器点击后加载; 在此之前的提供者链接( YouTube通过 nocookie) | 几行,无依赖 |
| `pagination` | 文字新闻风格 `/page/N/` 链接 | 无 |
| `breadcrumb` | 祖先,然后是当前页面,可选 JSON-LD | 无 |
| `band` | 样式后退部分:标题、铅、图像、项的网格(图、标题、细节、文本、点、链接)和按钮,在被测量的框架中 | 无 |
| `dialog` | 弹出访客打开:按钮和模式 `<dialog>` 带有文本、按钮和 a `form` 插槽; 从不自行打开 | 几行,无依赖 |
| `behavior` | 行为岛:没有组件携带的源部件(滑行器、分页器、手风琴、计数器、切换器、过滤器、内页对话框、锚地链接、图像灯盒、一个视频播放器作为海报链接保存,在点击时播放),作为自己的标记并被一个香草模块接通;静态且可读而不读 | `_shared/behaviors.ts`,无依赖 |
| `announcement` | 标题上方的一行通知,可选链接;通过一个链接关闭 `<details>` | 无 |
| `consent` | Cookie 接受和拒绝同意; 拒绝同意直到访客接受 | 几行,无依赖 |
| `contact-details` | 电子邮件、电话、邮政地址、开放时间和地图链接,无表格 | 无 |
| `feature-list` | 简短的特性, 每个标题和有图标或检查的一行文字 | 无 |
| `language-switcher` | 链接到网站其他语言中的同一页,作为列表或一个 `<details>` 菜单 | 无 |
| `logo-cloud` | 客户端或合伙人标识为网格、行或无尽条 | 无 |
| `post-list` | 作为纸牌的帖子列表:网格,叠行,被显示的第一个帖子或紧凑的列表 | 无 |
| `pricing` | 价格计划与特色计划并存 | 无 |
| `prose` | 编辑所写的丰富文本的正文, 由 Tailwind Typography 取来; 未映射元素的倒置 | 无 |
| `search-box` | 将访客送到 `/search?q=…` | 无 |
| `social-links` | 链接网站在其他网络上的简介 | 无 |
| `split` | 文本和按钮块旁的图像 | 无 |
| `stats` | 每个标签一行数字; 在视图中可选择计算一次 | 数行数, 不依赖 |
| `steps` | 顺序步骤, 作为列表或行 | 无 |
| `team` | 每个人的相貌、姓名、角色和生物 | 无 |

每个部分都生活在 `components/<id>/`数字 :

-   `<Name>.astro`: 组件。 使用的备选案文 `tailwind-variants`,道具被键入,每个可选道具也接受 `undefined`。 。 。 .
-   `meta.json`:它的目录条目. 道具为Contentrain `FieldDef`s 有描述;条目还列出了变体,槽,JavaScript,npm依赖, `sources` (它取代的构建器元素)和无障碍说明.
-   `fixtures.json`:视觉后退的病例. 每个变种选项都包括在内.

`components/_shared/` 持有 `Section`, (中文(简体) ), `Button`, (中文(简体) ), `KitImage`, (中文(简体) ), `measured.ts` 和数值类型 (单位:千美元)`ImageInput`, (中文(简体) ), `LinkInput`, (中文(简体) ), `ActionInput`, (中文(简体) ), `NavItem`, (中文(简体) ), `MeasuredStyle`) (中文(简体) ).

## 测量样式

迁移可以将其在源页面所测量的样式交给一节: `measured: MeasuredStyle` (与 `MeasuredStyle` 内 `@contentrain/types`: 相框宽度( )`containerPx`),贴(`padY`, (中文(简体) ), `padX`),背景(第1条)`bg.color`, (中文(简体) ), `bg.image` 与 `overlay`, (中文(简体) ), `size`, (中文(简体) ), `position`),390,768和1280 px(工具包的基座, `md` 财务报告和审定财务报表 `lg`;失踪的768取2和1280个值中较小的部分,再取390个值;失踪的1280取768个值,再取390个值;失踪的390为1),项目 `gap`,则文本 `tone` (单位:千美元)`dark` = 暗带上发光文字;没有它,便有填充本身的光度 决定)`align`数字 : `start`, (中文(简体) ), `center`, (中文(简体) ), `end`),该牌 `radius` (单位:千美元) `minHeight`。 。 。 .

缺席时,有一节会像以前一样取取网站的地标. 现在,它赢了 页:1 `tone` 财务报告和审定财务报表 `columns` 变相. `Section` 把它变成内置自定义 属性( e)`--kit-cols-390/768/1280`, (中文(简体) ), `--kit-gap`, (中文(简体) ), `--radius-card`, (中文(简体) ), `--container-page`, (中文(简体) ), `--spacing-gutter`和它自己的垫子, 高度和填充; 组件的项目网格读取它们 `measuredGrid(measured)`先检查每个值 (单位:千美元)`components/_shared/measured.ts`: 数字超出范围,颜色是 不是六分法, rgb(a), hsl(a), `transparent`, (中文(简体) ), `white` 或者说 `black` (重叠可能 也可以是这种颜色的线性或射线梯度,而不是http(s)或 root- relative, 或其关键字以外的位置被丢弃, 从未写入 成为样式属性.

## 键

组件使用颜色角色和宽度,从不使用原始值. 一个网站定义它们 内 `@theme` (启动者已经做了): `--color-surface`, (中文(简体) ), `--color-surface-muted`, (中文(简体) ), `--color-ink`, (中文(简体) ), `--color-ink-muted`, (中文(简体) ), `--color-line`, (中文(简体) ), `--color-accent`, (中文(简体) ), `--color-accent-ink`, (中文(简体) ), `--color-accent-text`, (中文(简体) ), `--color-accent-text-inverse`, (中文(简体) ), `--font-sans`, (中文(简体) ), `--container-prose`, (中文(简体) ), `--container-page`, (中文(简体) ), `--container-wide` 财务报告和审定财务报表 `--radius-card`。 。 。 .

重音文字( 有眉毛, 有分类链接) 读取 `--color-accent-text`永远 `--color-accent`:为填充而选取的口音对页面上文字来说可能太轻. 启动器将其设定为口音;其口音不超过4.5:1的站点在其上 表面设置一个可读的。 阴暗部分( A)`tone="inverse"`)读取 `--color-accent-text-inverse` 换个位置.

更安静的文本(一个入声,一个标题,一个角色,一个脚步链接)是一个彩色角色,永远不会 不透明:暗淡的文字在乐队上铺上颜色,在倒下的一个中调乐队上铺上颜色 在4.5:1之下。 写着 `--color-ink-muted` 在一个光带, `--color-ink-muted-inverse` 黑暗的一面(启动器将地表搅拌到墨水上;没有了墨水,乐队自己的 文本颜色)和填充器在口音或品牌乐队上自有的墨水. 里面的光线 带(一张卡片、一张表格面板、一张菜单)已恢复 `--color-ink-muted`。这些课程是 内 `_shared/muted.ts`。 。 。 .

### 区钩

每个部分的根都有一个 `id` 财务报告和审定财务报表 `data-kit-section="<component id>"` (单位:千美元)`hero`, (中文(简体) ), `card-grid`, (中文(简体) ), `slider`),所以一个站点的主题或设计层可以样式一个 那种部分,或者一个部分, 不接触组件。 ID是那个 页面,或每页所计的组件 id(`hero`,则 `hero-2`),同样的 每一个建筑.

迁移后的网站也带有主题类型和形状,组件读取 所以没有它们的网站看起来 不变:

-   `--font-weight-heading`:各节标题可追溯到700个,项目标题可追溯到600个.
-   `--font-weight-body`, (中文(简体) ), `--text-body`, (中文(简体) ), `--leading-body` 财务报告和审定财务报表 `--leading-heading`数字 : 身体和丰富的文字类型。 这些是在启动器的CSS.
-   `--radius-control`:按钮和窗体控件.
-   `--radius-image`: 图像, 回落到 `--radius-card`。 。 。 .
-   `--spacing-gutter`: 页面框的侧贴, 折回到 1rem 电话和2雷姆 `md` 起来.

主题的类型尺度和节奏不由组件来读取. 现场 主题应用到工具箱的标记上,只有当网站设置时:

-   `--text-heading-1` 改为 `--text-heading-3`: 标题 `main`。 。 。 .
-   `--text-body`数字 : `[data-kit-text]`,标题和正文段落 部分组件.
-   `--text-nav`: 信头导航, `[data-cr-part="nav-header"]`。 。 。 .
-   `--text-footer`:页脚的文本和链接, `[data-kit-footer]` (装备箱) 自有大小为 `text-sm`) (中文(简体) ).
-   `--spacing-section`:连续两节之间的相距;每节 `[data-kit-section]` 得到一半作为垂直垫,但 地点 `data-kit-spacing="none"`。 。 。 .
-   `data-kit-brand` (页眉和页脚的站名)和 `data-kit-tagline` (Footer)取取主题本身的大小:取其所坐位置的名称(body in 标题、页脚中的标题、标记线.

完整名单在 `catalog.json` 下级 `tokens`。 。 。 .

## API 密码

```bash
pnpm add -D @contentrain/astro-kit
```

```ts
import { copyComponents, KIT_COMPONENTS_DIR, loadCatalog, loadMapping, planCopy, rulesFor } from '@contentrain/astro-kit'

const catalog = await loadCatalog()
const plan = planCopy(catalog, ['header', 'card-grid']) // adds the components they render (nav, search-box), the shared files and the npm packages needed
await copyComponents(plan, KIT_COMPONENTS_DIR, '/path/to/site') // → src/components/kit/<id>/…
// install plan.dependencies in the site

const gutenberg = await loadMapping('gutenberg')
rulesFor(gutenberg, 'core/cover') // → the rule that turns a cover block into a hero, with its prop sources
```

`validateCatalog`, (中文(简体) ), `componentsForSource`, (中文(简体) ), `validateMapping` 财务报告和审定财务报表 `unmappedSources` 检查目录和绘图表.

## 绘图表

`mapping/<builder>.json` (单位:千美元)`gutenberg`, (中文(简体) ), `elementor`, (中文(简体) ), `divi`, (中文(简体) ), `classic`() 地图 构件元素到组件,每个道具来自小型闭合器 一组表达式(参见 `src/mapping.ts`) (中文(简体) ). 它们是版本和元素 没有规则可以保留丰富的文本(`fallback: "prose"`) (中文(简体) ). 当一条规则匹配 元素,最外端匹配拥有其子树. `defaults` 列表属性 值 构建者在数据默认时离开其数据 (元素保存否) `video_type` 为YouTube视频服务; `when.attr` 财务报告和审定财务报表 `attr:` 通过它们阅读(`attrsOf`) (中文(简体) ).

## 发展

```bash
pnpm --filter @contentrain/astro-kit catalog   # regenerate catalog.json from meta.json files
pnpm --filter @contentrain/astro-kit test      # catalog, mapping and starter-copy checks
node packages/astro-kit/scripts/visual.mjs --local-sdk [--only <id>] [--update]
```

`visual.mjs` 复制启动器并安装其中的每个组件。 这个 使每个固定在 `/kit/<id>/`,对照 组件道具,然后运行 `astro check` 和一个建筑。 最后,比较一下 390、768和1280 px的截图 `visual/<platform>/`启动器 携带一些工具包组件 `src/components/kit/`,测试保存这些 复制本与这里的来源完全相同.

## Contentrain生态系统的一部分

Contentrain是团队和人工智能代理商的一个内容治理生态系统;代理商通过 [MCP 服务器](https://ai.contentrain.io/packages/mcp)。这个包是 [开源工具](https://github.com/Contentrain/ai) (单位:千美元)[文档](https://ai.contentrain.io/))和将 WordPress 站点移动到 Astro 的构件 [迁移](https://migrate.contentrain.io/) 提供有偿服务. [工作室](https://github.com/Contentrain/studio) 是审查的团队表面和角色(并运行后面的表格) `contact-form`(三); [桥](https://github.com/Contentrain/wordpress-bridge) 是一个免费 WordPress 插件,将一个站点导出为 Contentrain 商店 .

## 许可证

麻省理工学院

## 常见问题

### @contentrain/astro-kit 是什么？

复制 Contentrain 站点的 Astro 组件\( Shadcn 模型\):输入道具,尾风变量,默认为零 JavaScript —— 有机器可读目录

### 如何安装 @contentrain/astro-kit？

在项目目录运行 npm install @contentrain/astro-kit，或使用 pnpm add / yarn add / bun add。

### @contentrain/astro-kit 支持 TypeScript 吗？

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

### @contentrain/astro-kit 支持 ESM 还是 CommonJS？

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

### @contentrain/astro-kit 可以商用吗？

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

### @contentrain/astro-kit 的下载量有多少？

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

### @contentrain/astro-kit 还在维护吗？

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