# @e-burgos/tucu-ui 中文文档

规范地址：https://npmcn.com/package/%40e-burgos/tucu-ui/

版本：3\.10\.1
npm 元数据更新时间：2026-11-13T13:29:54.105Z
中文译文更新时间：2026-11-14T12:35:02.534Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40e-burgos/tucu-ui
原文对照：https://npmcn.com/package/%40e-burgos/tucu-ui/?lang=original
项目主页：https://ui.estebanburgos.com.ar/
源码仓库：https://github.com/e-burgos/tucu-ui

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

- 包体积（解压后）：6.2 MB，525 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：17 个
- peer 依赖：next \>=16，react \>=18\.0\.0，react-dom \>=18\.0\.0，tailwindcss \>=4\.0\.0
- 首次发布：2025-11-10T15:56:26.632Z
- 最新版本发布：2026-11-13T13:29:53.658Z
- 近 30 天下载量：2043（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 41 个）

## 中文简介

Tucu UI 图书馆

## 安装

```sh
npm install @e-burgos/tucu-ui
```

也可以使用：`pnpm add @e-burgos/tucu-ui`、`yarn add @e-burgos/tucu-ui`、`bun add @e-burgos/tucu-ui`

## README

# 图克UI

一个现代React组件库由TypeScript和Tailwind CSS v4所建造——自动布局,macOS设计系统(Sonoma & Tahoe),高级路由(Standolone & MFE),形式系统,图表,5000+图标,块链组件,以及WCAG 2.1 AA合规.

**📚 [现场医生](https://ui.estebanburgos.com.ar/) • 妇女 [国家预防机制](https://www.npmjs.com/package/@e-burgos/tucu-ui)**

* * *

## 特征

| 特性 | 说明 | 文档 |
| --- | --- | --- |
| 🎨 **布局系统** | 经典、 最小、 无、 macOS Sonoma & Tahoe | [版式](https://ui.estebanburgos.com.ar/design-system/layout-system) |
| 🎭 **他们** | 34+ 颜色预设, 暗/光, RTL, CSS vars | [主题指南](https://ui.estebanburgos.com.ar/design-system/theming-guide) |
| 📝 **表单** | 反应 Hook 格式集成, 验证, 所有输入类型 | [表格系统](https://ui.estebanburgos.com.ar/form-system/example) |
| 💻 **马科斯·索诺马** | 半透明侧边栏、工具栏、活性效应 | [索诺玛](https://ui.estebanburgos.com.ar/macos/sonoma) |
| 🪟 **马可斯塔霍** | 液态玻璃码头、被冰冻的板子、9个口音包 | [塔荷尔](https://ui.estebanburgos.com.ar/macos/tahoe) |
| 🧩 **UI 组件** | 95+ 组件:模式,抽屉,卡片,工具提示 | [构成部分](https://ui.estebanburgos.com.ar/components/ui-components) |
| ⌨️ **输入组件** | 所有有验证和可访问性的形式输入 | [投入](https://ui.estebanburgos.com.ar/components/inputs-components) |
| 📊 **图表** | 巴图 线图 地区图 皮克图 雷达 编成 | [图表](https://ui.estebanburgos.com.ar/components/charts) |
| 🪙 **区链** | DeFi, NFT, 密码钱包组件 | [区链](https://ui.estebanburgos.com.ar/components/blockchain) |
| 🎯 **图标** | 5000+ Lucide + 97 个习惯(crypto, social, UI) | [图标](https://ui.estebanburgos.com.ar/features/icons-system) |
| 🌐 **路线** | 独立(自动)和MFE(显性)模式 | [路线](https://ui.estebanburgos.com.ar/features/routing-system) |
| ♿ **无障碍** | WCAG 2.1 AA, ARIA, 键盘导航 | [A11y (英语)](https://ui.estebanburgos.com.ar/features/accessibility) |
| 🪝 **钩子 Utils** | 使用Theme, 使用 Breakpoint, 还有更多 | [钩子](https://ui.estebanburgos.com.ar/features/hooks-utilities) |
| 🎨 **尾风 CSS v4** | 所有公用事业预配置, 零额外设置 | [尾风](https://ui.estebanburgos.com.ar/tailwind-utilities/layout-utilities) |
| ▲ **下一个.js 16** | 通过 App 路由器 `@e-burgos/tucu-ui/next`, (中文(简体) ), `'use client'` 每个模块,静态导出 | [下一节.j](https://npmcn.com/package/%40e-burgos/tucu-ui/#readme-nextjs-app-router) |
| 🤖 **MCP 服务器** | 通过示范背景协议实现AI代理一体化 | [MCP 服务器](https://ui.estebanburgos.com.ar/mcp-server) |

* * *

## 安装

```bash
npm install @e-burgos/tucu-ui
# or
pnpm add @e-burgos/tucu-ui
```

在您的 CSS 主文件中 :

```css
@import '@e-burgos/tucu-ui/styles';
```

> 包括完整的Tailwind CSS v4——不需要额外的Tailwind设置.

### 在您的项目中已经使用 Tailwind CSS v4 了 ?

不要进口 `./styles` 和你自己一样 `@import 'tailwindcss'` 那个.. 在同一页中运行两个独立的 Tailwind 构造,它们的分层可以 无法预料地相互超越 使用 `./theme` 代号: 仅包含组件样式, 没有捆绑的 Tailwind, 因此您自己的构建生成 每一个功用等级(你的和图克UI的) 从一个实例.

```css
@import 'tailwindcss';
@import '@e-burgos/tucu-ui/theme';
@source '../node_modules/@e-burgos/tucu-ui/**/*.mjs';
```

只扫描 `**/*.mjs`:即班名所住之处. 指点 `@source` 在整个包中还扫描 CJS 捆绑( 内含) `tailwind-merge`班级表, `index.css`, (中文(简体) ), `.d.ts` 和 Docs, 将 ~100 KB 未使用的公用事业添加到您的 CSS 中。 这个 `theme` 条目已经包括了Swiper, carousel, 数据表和棱镜样式; 包中没有 JS 文件导入了样式表 .

这三行之间的导入顺序不重要——你自己的效用 课堂总是胜过Tucu UI的默认 无论是哪种方式.

* * *

## Next.js (App路由器) (英语)

要求数 `next >=16` (可选同伴依赖)和回放19.

```bash
pnpm add @e-burgos/tucu-ui next react react-dom
```

`app/layout.tsx` —— 说 `NextThemeProvider` 从 `/next` 条目和使用 `next/navigation` 财务报告和审定财务报表 `next/link`; 不需要您的路由器 :

```tsx
import { LucideIcons } from '@e-burgos/tucu-ui';
import { NextThemeProvider, ThemeModeScript } from '@e-burgos/tucu-ui/next';
import './globals.css';

const menuItems = [
  { name: 'Dashboard', path: '/', icon: <LucideIcons.LayoutDashboard /> },
  { name: 'Reports', path: '/reports', icon: <LucideIcons.Table /> },
];

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeModeScript defaultMode="system" />
      </head>
      <body>
        <NextThemeProvider logo={{ name: 'My App' }} layout="admin" menuItems={menuItems}>
          {children}
        </NextThemeProvider>
      </body>
    </html>
  );
}
```

`app/globals.css` (Tailwind v4 — 使用) (中文(简体) ) `theme`没有 `styles`点 `@source` 在包裹 `.mjs` 文件数 :

```css
@import 'tailwindcss';
@import '@e-burgos/tucu-ui/theme';
@source '../node_modules/@e-burgos/tucu-ui/**/*.mjs';
```

`ThemeModeScript` (服务器组件,接受) `nonce`设置 `dark`编号 :`light` 课开始 `<html>` 在水合之前,所以没有错误模式的闪光.

-   **服务器/客户端边界 :** 每艘tucu-ui舱舰 `'use client'`,因此可以从服务器组件中导入组件。 函数不能跨越边界——a `DataTable` 栏 `cell`,一个 `onClick` 或者任何物料必须生活在 `'use client'` 您的应用程序组件,然后由服务器组件制作.
-   **静态导出 :** `output: 'export'` 工作;外壳先发.
-   **只显示 :** 页:1 `react-router` 命名空间和路由钩( r)`ThemeProvider` 拥有自己的路由器, `RouterProvider`, 路由帮助器)是用于Vite应用程序. 在"Next"中,路由是App路由器的文件系统.
-   一个完整的例子存在于 [`apps/next-demo`](https://npmcn.com/package/%40e-burgos/tucu-ui/apps/next-demo)。 。 。 .

* * *

## 主题预设和范围

6个内置预设`glass`, (中文(简体) ), `classic`, (中文(简体) ), `elegant`, (中文(简体) ), `fresh`, (中文(简体) ), `minimal`, (中文(简体) ), `vibrant`)自己通过 `registerThemePresets`,以及 `ThemeScope` 以子树为主题。 在范围(Modal, Drawer, Select)内打开的重叠在范围本身的门户主机上挂载并保留其主题.

```tsx
import { ThemeProvider, ThemeScope, registerThemePresets, resolveThemePreset } from '@e-burgos/tucu-ui';

registerThemePresets({ name: 'acme', accent: '#e11d48', radius: 'lg', cards: 'solid' });

const preset = resolveThemePreset({
  host: window.location.host,
  rules: [{ host: '*.acme.com', preset: 'acme' }],
  fallback: 'glass',
});

<ThemeProvider preset={preset} defaultMode="system" menuItems={menuItems} />

<ThemeScope preset="vibrant" mode="light">
  <Card>Scoped</Card>
</ThemeScope>
```

预设写入 `--tucu-accent`, (中文(简体) ), `--tucu-radius`, (中文(简体) ), `--tucu-card-*` 财务报告和审定财务报表 `data-tucu-*` 属性. `dark:` 公用设施尊重一种水平的相向式筑巢.

### 较小的 CSS : `styles-core`

如果你不使用macOS主题, `@import '@e-burgos/tucu-ui/styles-core';` 相同型号的舰只,大小约为一半(~356 KB vs~717 KB); 使用自有的尾风 `@e-burgos/tucu-ui/theme-core`。 。 。 .

* * *

## 增加于3.9.0

-   MCP:资源 `tucu://design-guide`时速 `design-review`,以及 `style` 编号 : `motion` 编号 : `density` 参数加 `marketing` 财务报告和审定财务报表 `auth` 显示布局 `generate_page` 编号 : `generate_component`
-   `tucu-ui-design` 用 MCP 套件运出代理技能 : `npx -p @e-burgos/tucu-ui-mcp tucu-ui-skill install` (单位:千美元)`--dir <path>`, (中文(简体) ), `--force`· ; `tucu-ui-skill path` 打印文件夹)
-   `ThemeProvider` 编号 : `NextThemeProvider` 将应用程序包入 `MotionConfig reducedMotion="user"`; 覆盖到 `motion={{ reducedMotion }}`
-   `DataTable` `columnSizing` (单位:千美元)`'fixed' | 'fill-leftover' | 'fill'`和 `getRowLabel` (行、牌和行动作的可访问名称)
-   `FilterBar` 每个过滤器的可访问名称( x)`label`, (中文(简体) ), `aria-label`, (中文(简体) ), `id`和 `data-testid`

* * *

## 增加为3.8.0

-   `MarketingLayout`, (中文(简体) ), `MarketingNav`, (中文(简体) ), `MarketingFooter`: 路由器-不可知公共站点外壳,有活性链接,可访问移动菜单和 `transparentUntilScroll`
-   `SplitAuthLayout`: 品牌栏+形式栏 (:`variant` 分头行动, `brandPosition`, (中文(简体) ), `surface`, (中文(简体) ), `breakpoint`(中文(简体) )
-   `DataTable` `mobileCards`:行在中断点( CSS- switched) 下制成有动作、 选择和紧凑相接的相接相接的相接相
-   新建符号组 : `--tucu-marketing-*`, (中文(简体) ), `--tucu-auth-*`, (中文(简体) ), `--tucu-datatable-card-*`

* * *

## 3.7.0中添加的组成部分

-   `SplitModal`, (中文(简体) ), `SplitModalWizard` (同步) `validateStep`, (中文(简体) ), `ConfirmDialog`
-   `GlassPanel`, (中文(简体) ), `StateBadge`, (中文(简体) ), `InlineNotice`, (中文(简体) ), `MoneyText`, (中文(简体) ), `StatCard`, (中文(简体) ), `SafeImage` (和 `Image` 倒置道具)
-   `SegmentedControl`, (中文(简体) ), `FilterPill`, (中文(简体) ), `FilterBar`, (中文(简体) ), `AnimatedTabs`
-   `EmptyState`, (中文(简体) ), `ErrorState`, (中文(简体) ), `SystemStatePage`, (中文(简体) ), `Lightbox`
-   `Badge` `struck` (一) 绿色/橙色/红色/钢质/纯色; `Modal` `role`编号 :`aria-labelledby`· ; `Select` `menuWidth`, (中文(简体) ), `maxMenuHeight`, (中文(简体) ), `renderValue`, (中文(简体) ), `triggerLabel` 更多
-   新建符号组 : `--tucu-split-modal-*`, (中文(简体) ), `--tucu-glass-*`, (中文(简体) ), `--tucu-state-*`, (中文(简体) ), `--tucu-segmented-*`, (中文(简体) ), `--tucu-state-view-*`, (中文(简体) ), `--tucu-lightbox-*`

* * *

## 快速启动

```tsx
import { ThemeProvider, LucideIcons } from '@e-burgos/tucu-ui';

const menuItems = [
  {
    name: 'Dashboard',
    href: '/',
    icon: <LucideIcons.LayoutDashboard />,
    component: <Dashboard />,
  },
];

export default function App() {
  return (
    <ThemeProvider
      logo={{ name: 'My App' }}
      layout="minimal"
      brandColor="Blue"
      menuItems={menuItems}
      isAuthenticated={true}
    />
  );
}
```

• 运行、导航、主题和应答布局是自动产生的.

关于全面的API参考、模式和实例,请参见 **[现场文件](https://ui.estebanburgos.com.ar/)**。 。 。 .

* * *

## 技术堆栈

反射 19 相机 相机 相机 CSS v4 相机 相机 相机 相机 相机 相机 相机 相机 相机 相机

## 许可证

麻省理工学院 [电子汉堡](https://github.com/e-burgos)

## 常见问题

### @e-burgos/tucu-ui 是什么？

Tucu UI 图书馆

### 如何安装 @e-burgos/tucu-ui？

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

### @e-burgos/tucu-ui 支持 TypeScript 吗？

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

### @e-burgos/tucu-ui 支持 ESM 还是 CommonJS？

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

### @e-burgos/tucu-ui 可以商用吗？

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

### @e-burgos/tucu-ui 的下载量有多少？

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

### @e-burgos/tucu-ui 还在维护吗？

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