# @constructor-io/constructorio-ui-components 中文文档

规范地址：https://npmcn.com/package/%40constructor-io/constructorio-ui-components/

版本：1\.8\.0
npm 元数据更新时间：2026-11-03T10:36:00.644Z
中文译文更新时间：2026-11-10T16:15:27.602Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40constructor-io/constructorio-ui-components
原文对照：https://npmcn.com/package/%40constructor-io/constructorio-ui-components/?lang=original
项目主页：https://github.com/Constructor-io/constructorio-ui-components#readme
源码仓库：https://github.com/Constructor-io/constructorio-ui-components

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

- 包体积（解压后）：292 kB，89 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：react \>=16\.12\.0，tslib ^2\.4\.0，react-dom \>=16\.12\.0
- 首次发布：2026-01-08T18:18:09.750Z
- 最新版本发布：2026-11-03T10:35:59.895Z
- 近 30 天下载量：13837（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

用于网络应用程序的构建器 UI 组件库

## 安装

```sh
npm install @constructor-io/constructorio-ui-components
```

也可以使用：`pnpm add @constructor-io/constructorio-ui-components`、`yarn add @constructor-io/constructorio-ui-components`、`bun add @constructor-io/constructorio-ui-components`

## README

# 构造器 UI 组件库

![minzipped size](https://img.shields.io/bundlephobia/minzip/@constructor-io/constructorio-ui-components?color=green) [![NPM Version](https://img.shields.io/npm/v/@constructor-io/constructorio-ui-components)](https://www.npmjs.com/package/@constructor-io/constructorio-ui-components) [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Constructor-io/constructorio-ui-components/blob/main/LICENSE)

## 导言

UI组件库是Resact组件的集合,可用于为Constructionor.io产品构建UI.

我们 [故事书 Docs](https://constructor-io.github.io/constructorio-ui-components/?path=/docs/general-introduction--variants) 全面概述每个组成部分,包括其行为、变化和配置选项.

## 所需资源

-   节点.js v22.1.8.0 (LTS Jod)
-   反应 :
-   反应 DOM QQ16.12.0

## 安装

```bash
npm i @constructor-io/constructorio-ui-components
```

## 用法图案

### 正常使用

```tsx
import { Button } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return <Button>Click me</Button>;
}
```

### 使用 `asChild`

```tsx
import { Badge } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return (
    <Badge asChild variant="outline">
      <a href="#">
        A link that looks like a badge
      </a>
    </Badge>
  );
}
```

### 组件覆盖

```tsx
import { Button } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return (
    <Button
      componentOverrides={{
        reactNode: <span>A span rendered in place of a button</span>
      }}
    >
      This will be overridden
    </Button>
  );
}
```

### 通过数据属性

```tsx
import { Button } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return <Button data-cnstrc-price={23.25}>Purchase</Button>;
}
```

### 复合组件

```tsx
import { ProductCard } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return (
    <ProductCard
      product={{
        id: 'highland-golf-pants',
        variationId: 'highland-golf-pants--navy',
        name: "Highland Golf Pants",
        imageUrl: 'https://example.com/pants.jpg',
        price: '799',
        rating: 4.8,
        reviewsCount: 203,
        description: 'Premium golf pants designed for comfort and performance on the course',
      }}
      className='overflow-hidden max-w-md'
    >
      <div className='grid grid-cols-2 gap-4 p-4'>
        <ProductCard.ImageSection />
        <div className='space-y-2'>
          <ProductCard.PriceSection />
          <ProductCard.TitleSection />
          <ProductCard.RatingSection />
        </div>
      </div>
      <ProductCard.Footer>
        <ProductCard.AddToCartButton />
      </ProductCard.Footer>
    </ProductCard>
  );
}
```

## 尾风 CSS 前缀

此库使用 Tailwind CSS v4 并带有 `cio:` 用于避免与应用程序的 Tailwind 类相冲突。 所有公用分类和CSS变量都被命名空格来保证样式不会出漏或相撞.

### 类别

代码库使用两个不同的类名空间. 它们看起来相似,但用途不同:

-   **`cio-*` (无结肠)** —— 与组件根和关键子元素相接的平版 CSS 钩/ BEM 标识符(例如, `cio-components`, (中文(简体) ), `cio-badge`, (中文(简体) ), `cio-product-card-image`, (中文(简体) ), `cio-filter-visual-swatch`) (中文(简体) ). 这些是用于外形覆盖和测试的稳定选择器;它们是 **没有** 尾风公用事业公司 **永远** 前缀为 `cio:`。 。 。 .
-   **`cio:*` (用结肠)** - 尾风 v4 功能类,由 `prefix(cio)` 导入指令(例如, `cio:flex`, (中文(简体) ), `cio:hover:bg-primary/90`) (中文(简体) ). 本节其余部分的公约适用于这些公约.

```tsx
// Both kinds appear together on the same element:
<div className="cio-badge cio:inline-flex cio:items-center cio:gap-1.5">
```

### 类别命名公约

当在此库中添加或定制 Tailwind 类时, 总是使用 `cio:` 前缀 :

```tsx
// Correct
<div className="cio:flex cio:items-center cio:gap-2">

// Incorrect - will not work
<div className="flex items-center gap-2">
```

### 备选案文和修改

前缀必须来 **在此之前** 任何变体(覆盖、焦点、响应等):

```tsx
// Correct - prefix first, then variant, then utility
<button className="cio:bg-primary cio:hover:bg-primary/90 cio:disabled:opacity-50">

// Incorrect - variant before prefix
<button className="hover:cio:bg-primary/90 disabled:cio:opacity-50">
```

### 响应断点

```tsx
// Correct
<div className="cio:p-2 cio:sm:p-4 cio:lg:p-6">

// Incorrect
<div className="cio:p-2 sm:cio:p-4 lg:cio:p-6">
```

### 任意值和选择器

```tsx
// Correct
<div className="cio:w-[200px] cio:[&_svg]:size-4">

// Incorrect
<div className="[&_svg]:cio:size-4">
```

### CSS 变量

CSS 变量的前缀为 `--cio-`数字 :

```css
:root {
  --cio-primary: oklch(0.1969 0.0101 276.49);
  --cio-background: oklch(1 0 0);
  --cio-radius: 0.625rem;
}
```

### 自定义主题

您可以通过设置应用程序中的 CSS 变量来覆盖默认主题 :

```css
:root {
  --cio-primary: #your-brand-color;
  --cio-radius: 0.5rem;
}
```

## 地方发展

### 开发脚本

```bash
npm ci                         # Install dependencies for local dev
npm run dev                    # Start a local dev server for Storybook
npm run lint                   # Run lint
npm run test                   # Run unit tests
```

### 构建脚本

```bash
npm run compile                # Compile the library, remove aliases, copy styles
npm run build-storybook        # Build Storybook
npm run serve-built-storybook  # Serve the built Storybook
```

## 捐款

-   叉出 repo 创建新分支( C) .
-   运行 npm 安装以安装依赖 .
-   提交公关审查.

## 许可证

麻省理工学院 建筑师.io

## 常见问题

### @constructor-io/constructorio-ui-components 是什么？

用于网络应用程序的构建器 UI 组件库

### 如何安装 @constructor-io/constructorio-ui-components？

在项目目录运行 npm install @constructor-io/constructorio-ui-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.12\.0）、tslib（^2\.4\.0）、react-dom（\>=16\.12\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @constructor-io/constructorio-ui-components 支持 TypeScript 吗？

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

### @constructor-io/constructorio-ui-components 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @constructor-io/constructorio-ui-components 可以商用吗？

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

### @constructor-io/constructorio-ui-components 的下载量有多少？

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

### @constructor-io/constructorio-ui-components 还在维护吗？

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