# @ctrliq/quantic-components 中文文档

规范地址：https://npmcn.com/package/%40ctrliq/quantic-components/

版本：1\.97\.0
npm 元数据更新时间：2026-10-28T22:11:28.814Z
中文译文更新时间：2026-11-11T03:59:48.850Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：30.8 MB，5856 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：astro ^7\.2\.8
- 首次发布：2026-06-02T14:45:37.235Z
- 最新版本发布：2026-10-28T22:11:28.621Z
- 近 30 天下载量：3877（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 79 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @ctrliq/quantic-components
```

也可以使用：`pnpm add @ctrliq/quantic-components`、`yarn add @ctrliq/quantic-components`、`bun add @ctrliq/quantic-components`

## README

# 量子组件

## 构成部分表

该软件包将每个被记录的组件作为静态数据发布于 `@ctrliq/quantic-components/meta.json`时生成 `static meta` 宣告每个组件。 这是普通的JSON,没有运行时间进口和装载机:

```js
const manifest = require('@ctrliq/quantic-components/meta.json');
```

```json
{
  "schemaVersion": 1,
  "generated": "2026-08-25T00:00:00.000Z",
  "components": [
    {
      "tag": "quantic-dialog",
      "description": "Modal overlay dialog with focus trap ...",
      "category": "feedback",
      "props": [
        {
          "name": "open",
          "description": "Whether the dialog is visible.",
          "type": "boolean",
          "default": "false"
        }
      ],
      "events": [{ "name": "after-close", "description": "Fired after the dialog closes ..." }],
      "slots": [{ "name": "trigger", "description": "Element that opens the dialog when clicked." }],
      "examples": ["<quantic-dialog> ... </quantic-dialog>"],
      "relatedTo": ["quantic-button"],
      "avoidWhen": [
        {
          "when": "the dialog only confirms a destructive action",
          "useInstead": "quantic-confirm-dialog"
        }
      ],
      "accessibility": {
        "providedByComponent": ["focus trap, restore on close, Escape to dismiss"],
        "requiredFromConsumer": ["a title, via quantic-dialog-title or aria-label"]
      },
      "subComponents": ["quantic-dialog-title", "quantic-dialog-actions"]
    }
  ]
}
```

道具、槽和事件是带有 `name`,则省去空字段. 没有东西被过滤: 转发的本地事件包含并标出, 所以消费者 决定是否关心。 处理缺失 `meta.json` 作为“此安装早于 而不是一个错误.

## 文件层

`meta.json` 整个的表象和太大的 无法放在上下文, 所以,一揽子 出版逐步公布的层次,由 `scripts/gen-llms.ts`数字 :

| 导出 | 这是什么 |
| --- | --- |
| `@ctrliq/quantic-components/llms.txt` | 指数:如何安装,每个组件一行 |
| `@ctrliq/quantic-components/llms/{category}-components.md` | 每个类别一个文件 |
| `@ctrliq/quantic-components/llms/components/{tag}.md` | 每个组件、道具、插槽、事件和实例一个文件 |

读取索引,然后是分类,然后是组件。 每个文件解析来自 `node_modules` 在已安装的版本中, 所以没有网络呼叫, 没有 服务器可以服务一个与已安装的软件包不一致的版本.

该指数带有安装和接线步骤,取自 `docs/getting-started.md` 而不是重报,因为正确命名组件是 无效, 无法知道要安装什么 和要装入哪个样式表 .

故事本将同样的字节复制到它的 `public/` 让他们在 `/llms.txt`, (中文(简体) ), `/llms/**` 财务报告和审定财务报表 `/components.json`。软件包是生产者;应用程序是消费者.

### 字段

除了别的事 `tag`, (中文(简体) ), `description` 财务报告和审定财务报表 `category` 是可选的,在未设定时省略, 所以读者必须将缺席视为"未说明"而非默认.

| 外地 | 类型 | 它携带着什么 |
| --- | --- | --- |
| `tag` | 字符串 | 自定义元素名称 。 反应包装器的名字是它的纸箱. |
| `description` | 字符串 | 一句或数句. 仅在生成的索引中使用了第一句. |
| `category` | 语句 | `action`, (中文(简体) ), `form`, (中文(简体) ), `display`, (中文(简体) ), `layout`, (中文(简体) ), `feedback`, (中文(简体) ), `navigation` 或者说 `data`。 。 。 . |
| `props` | 数组 | 每一个 `name`, (中文(简体) ), `type`,可选择 `description`, (中文(简体) ), `options`, (中文(简体) ), `default`, (中文(简体) ), `required`, (中文(简体) ), `copyRule`。 。 。 . |
| `slots` | 数组 | 每一个 `name` 财务报告和审定财务报表 `description`,可选择 `required`, (中文(简体) ), `copyRule`。默认槽有 `name: ""`。 。 。 . |
| `events` | 数组 | 每一个 `name`,可选择 `description`, (中文(简体) ), `detail`, (中文(简体) ), `forwarded`。 。 。 . |
| `examples` | 字符串 \[\] | Markup,取自"故事集"中建构时间的故事而不是手写. |
| `relatedTo` | 字符串 \[\] | 邻居的标签。 说他们有亲戚关系,不是选择哪一个. |
| `avoidWhen` | 数组 | 什么时候才能找到别的东西 每个条目都有 `when`,以及 `useInstead` 当有替代名称时. `useInstead` 当选项是组件时持有标签,如果不是,则使用旁白,因为答案有时是样式表. |
| `accessibility` | 对象 | `providedByComponent` 是组件实施的行为,所以消费者不得重新实施. `requiredFromConsumer` 它不能为自己提供的东西,例如一个无障碍的名称. |
| `ascii` | 字符串 | 元件解剖学图. |
| `experimental` | 布尔 | API可以在未成年人中更改或去除. 缺勤意味着得到支持。 见 `rules/promotion.md`。 。 。 . |
| `deprecated` | 对象 | `use` 命名替换, `reason` 说为什么. |
| `subComponentOf` | 字符串 | 父母的这个元素是解剖学的,只有在孩子独自惰性时才设定. |
| `subComponents` | 字符串 \[\] | 从孩子们那里得到的 `subComponentOf`,所以两者永远不能不同意. |

### 复制规则

握有 user-face 文本载体的道具或插槽 `copyRule`,指向 将表上船只编为顶级 `copyRules`数字 :

```json
{
  "copyRules": {
    "action-label": {
      "rule": "Verb phrase naming what happens, specific enough to act on without the surrounding text.",
      "good": ["Delete project", "Restart node"],
      "avoid": ["OK", "Yes", "Submit", "Continue"]
    }
  },
  "components": [
    {
      "tag": "quantic-confirm-dialog",
      "props": [{ "name": "confirmText", "type": "string", "copyRule": "action-label" }]
    }
  ]
}
```

参考内容是使规则保持一致。 占位人的措辞规则是: 6个输入相同,所以它被一次并指出6次而不是复制 然后左转去漂流 规则以文本的工作命名,而不是以组件命名 它携带它, 这就是为什么一个 `placeholder` 规则为所有人服务.

编号为: `CopyRuleId` 内 `src/shared/copy-rules.ts`,因此一个组件引用 a 不存在的规则是一个编译错误,而不是在 已公布数据。 无法找到身份证明的读者 只能说 打印身份证.

`copyRule` 只有在措辞错误是真正失败的情况下才被设定,即标签, 标题、信息和占位符。 多数道具没有带道具. 一个 `ariaLabel` 道具 永远不要:一个可访问的名称是一个可访问性要求,所以它属于 `accessibility.requiredFromConsumer`。 。 。 .

### 版本

`schemaVersion` 当一个现有读取器可能断开时被撞出:一个已删除或更名的字段, 类型已改变,或含义已改变。 添加可选字段不会碰上它,因为 忽略字段的读取器不受影响,所以工具化必须容忍键它不会 承认而不是拒绝该文件。 拒绝 a `schemaVersion` 你却不知道.

## 图标

Per-icon元素在图书馆的其余部分注册,所以 `<quantic-icon-lucide-rocket>` 在软件包的切入点以外不需要任何信息 :

```js
import '@ctrliq/quantic-components/register';
```

`@ctrliq/quantic-components/icons` 是以名称为基础的单独、 选入条目 寻找, `<quantic-icon name="Rocket">`它将每一个Lucide glyph 都刻入了一个运行时的名称 可以解析, 大约为 1 MB , 且它不在软件包的切入点 理由,你觉得呢? 偏好使用平角元素,除非名称只在运行时才真正为人所知.

## 推荐的工具

(升-插) \[[https://marketplace.visiterstudio.com/items? itemName=runem.lit-plugin 互联网档案馆的存檔,存档日期2013-12-20](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin)(VS代码)

## 常见问题

### 如何安装 @ctrliq/quantic-components？

在项目目录运行 npm install @ctrliq/quantic-components，或使用 pnpm add / yarn add / bun add。

### @ctrliq/quantic-components 支持 TypeScript 吗？

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

### @ctrliq/quantic-components 支持 ESM 还是 CommonJS？

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

### @ctrliq/quantic-components 可以商用吗？

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

### @ctrliq/quantic-components 的下载量有多少？

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

### @ctrliq/quantic-components 还在维护吗？

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