# @ekanos/ui 中文文档

规范地址：https://npmcn.com/package/%40ekanos/ui/

版本：0\.27\.0
npm 元数据更新时间：2026-11-11T21:37:47.281Z
中文译文更新时间：2026-11-13T23:59:44.115Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ekanos/ui
原文对照：https://npmcn.com/package/%40ekanos/ui/?lang=original
项目主页：https://sdk.ekanos.dev/ui/overview

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

- 包体积（解压后）：1.4 MB，91 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：next ^16\.0\.0，react ^19\.2\.8，next-intl ^4\.14\.7，react-dom ^19\.2\.8，react-hook-form ^7\.68\.0，@hookform/resolvers ^5\.2\.2 \|\| ^7\.0\.0
- 首次发布：2026-08-31T03:55:57.104Z
- 最新版本发布：2026-11-11T21:37:47.060Z
- 近 30 天下载量：2794（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

埃克诺斯被称作UI原始人,用于在单列波外建造埃克诺斯集成. 内部的@kit/ui图书馆被整理并出版的片段.

## 安装

```sh
npm install @ekanos/ui
```

也可以使用：`pnpm add @ekanos/ui`、`yarn add @ekanos/ui`、`bun add @ekanos/ui`

## README

# @ekanos/ui (英语)

Ekanos 风格的用于构建 Ekanos 集成的 UI 原始 **外部** 页:1 单相机。 这是出版的同伴 `@ekanos/sdk`: 拼图片 内部 `@kit/ui` 库,从 SDK 的再出口中选择 组件和示例集成包实际导入.

**文档 :** [sdk.ekanos.dev/ui/概览](https://sdk.ekanos.dev/ui/overview)。 。 。 .

在单簧管内部,继续导入 `@kit/ui/*` 直接 - 此软件包存在 给不能合作的合伙人.

## 出口的东西

每个组件一个子路径,反射 `@kit/ui` 名称 :

| 子路径 | 目录 |
| --- | --- |
| `@ekanos/ui/alert` | `Alert`, (中文(简体) ), `AlertTitle`, (中文(简体) ), `AlertDescription`, (中文(简体) ), `AlertAction` |
| `@ekanos/ui/button` | `Button`, (中文(简体) ), `ButtonProps`, (中文(简体) ), `buttonVariants` |
| `@ekanos/ui/card` | `Card`, (中文(简体) ), `CardHeader`, (中文(简体) ), `CardTitle`, (中文(简体) ), `CardDescription`, (中文(简体) ), `CardContent`, (中文(简体) ), `CardFooter`,, , , , , , , , |
| `@ekanos/ui/badge` | `Badge`, (中文(简体) ), `badgeVariants` |
| `@ekanos/ui/status-badge` | `StatusBadge` (中性药丸+调子点), `StatusTone` |
| `@ekanos/ui/stat` | `Stat`, (中文(简体) ), `StatLabel`, (中文(简体) ), `StatFigure`, (中文(简体) ), `StatValue`, (中文(简体) ), `StatChange`, (中文(简体) ), `StatDetail` |
| `@ekanos/ui/page` | `PageBody`, (中文(简体) ), `PageRail`, (中文(简体) ), `PageTitleSection`, (中文(简体) ), `PageToolbar`, (中文(简体) ), `PageToolbarActions`, (中文(简体) ), `PageRailTabs`, (中文(简体) ), `PageRailSubTabs`, (中文(简体) ), `PageBackButton`, (中文(简体) ), `PageRangeSwitch`, (中文(简体) ), `PageViewModeToggle` |
| `@ekanos/ui/dialog` | `Dialog`, (中文(简体) ), `DialogTrigger`, (中文(简体) ), `DialogContent`, (中文(简体) ), `DialogHeader`, (中文(简体) ), `DialogTitle`, (中文(简体) ), `DialogDescription`, (中文(简体) ), `DialogFooter`,, , , , , , , , |
| `@ekanos/ui/separator` | `Separator` |
| `@ekanos/ui/tooltip` | `Tooltip`, (中文(简体) ), `TooltipTrigger`, (中文(简体) ), `TooltipContent`, (中文(简体) ), `TooltipProvider` |
| `@ekanos/ui/select` | `Select`, (中文(简体) ), `SelectTrigger`, (中文(简体) ), `SelectValue`, (中文(简体) ), `SelectContent`, (中文(简体) ), `SelectItem`,, , , , , , , , |
| `@ekanos/ui/form` | `Form`, (中文(简体) ), `FormField`, (中文(简体) ), `FormItem`, (中文(简体) ), `FormLabel`, (中文(简体) ), `FormControl`, (中文(简体) ), `FormDescription`, (中文(简体) ), `FormMessage`, (中文(简体) ), `useFormField` |
| `@ekanos/ui/input` | `Input` |
| `@ekanos/ui/textarea` | `Textarea` |
| `@ekanos/ui/switch` | `Switch` |
| `@ekanos/ui/dropdown-menu` | `DropdownMenu`, (中文(简体) ), `DropdownMenuTrigger`, (中文(简体) ), `DropdownMenuContent`, (中文(简体) ), `DropdownMenuItem`,, , , , , , , , |
| `@ekanos/ui/label` | `Label` |
| `@ekanos/ui/skeleton` | `Skeleton` |
| `@ekanos/ui/icon` | `Icon`, (中文(简体) ), `renderIcon`, (中文(简体) ), `resolveIcon`, (中文(简体) ), `IconStyleOverrideProvider`名称助手 |
| `@ekanos/ui/utils` | `cn()`, (中文(简体) ), `isRouteActive()`, (中文(简体) ), `checkIfRouteIsActive()` |
| `@ekanos/ui/if` | `If` 有条件的渲染器 |
| `@ekanos/ui/trans` | `Trans` (下层;需要 `NextIntlClientProvider`(中文(简体) ) |
| `@ekanos/ui/spinner` | `Spinner` |
| `@ekanos/ui/ai-prompt-input` | `PromptInput` aI 询问表面的复合组件 |
| `@ekanos/ui/table` | `Table`, (中文(简体) ), `TableHeader`, (中文(简体) ), `TableBody`, (中文(简体) ), `TableRow`, (中文(简体) ), `TableHead`, (中文(简体) ), `TableCell`,.(静态表上的事实) |
| `@ekanos/ui/data-table` | `DataTable`, (中文(简体) ), `DataTableColumn` 及其类型/呼号类型(房屋表格:排序、呼号、行点击) |
| `@ekanos/ui/empty-state` | `EmptyState`, (中文(简体) ), `EmptyMedia`, (中文(简体) ), `EmptyStateHeading`, (中文(简体) ), `EmptyStateText`, (中文(简体) ), `EmptyStateButton` (整个空地表) |
| `@ekanos/ui/empty-note` | `EmptyNote` (一张空卡或有人居住的地表内的部分) |
| `@ekanos/ui/tabs` | `Tabs`, (中文(简体) ), `TabsList`, (中文(简体) ), `TabsTrigger`, (中文(简体) ), `TabsContent` |
| `@ekanos/ui/sheet` | `Sheet`, (中文(简体) ), `SheetTrigger`, (中文(简体) ), `SheetContent`, (中文(简体) ), `SheetHeader`, (中文(简体) ), `SheetTitle`,, , , , , , , , |
| `@ekanos/ui/confirm-dialog` | `ConfirmDialog` |
| `@ekanos/ui/search-field` | `SearchField` |
| `@ekanos/ui/avatar` | `Avatar`, (中文(简体) ), `AvatarImage`, (中文(简体) ), `AvatarFallback`, (中文(简体) ), `AvatarGroup`, (中文(简体) ), `AvatarGroupCount`, (中文(简体) ), `AvatarBadge`, (中文(简体) ), `PersonAvatar` (图片或名字缩写), `initialsFromName` |
| `@ekanos/ui/charts` | `Sparkline`, (中文(简体) ), `ProgressRing`, (中文(简体) ), `BarSeries` (部件用手绘的小图表,以 `--chart-*` 及其几何辅助工具 |

大部分源文件是内部的薄再导出 `@kit/ui` 图书馆——用于 这些, `@kit/ui` 保持唯一的真相来源。 在建设时间,代码是 内入 `dist/` 因此,公布的文物没有工作空间依赖性; `pnpm --filter @ekanos/ui pack:test` 失败的构建( 如果有) `@kit/` 规格 漏入柏油丸.

五个子路径—— `if`, (中文(简体) ), `trans`, (中文(简体) ), `spinner`, (中文(简体) ), `empty-state` 财务报告和审定财务报表 `data-table` —— 说 加号 `PageBody` 内 `page`,转而在这里本土实施. 其内部对应方是Makerkit授权的密码,来自 商业涡轮启动器 这个单列波是建立在; 发布在这个下 包的麻省理工学院的许可 将意图授予 我们没有的再利用权。 这个 这里运出的执行是原始的,以及 `pack:test` 失败的构建如果 任何由 Makerkit 撰写的源被内入 `dist/`。 。 。 .

## 样式

每一个组件都发出 Tailwind 类字符串 绑定在 Ekanos 的语义设计上 指针( a)`bg-primary`, (中文(简体) ), `text-muted-foreground`, (中文(简体) ), `border-border`, (中文(简体) ), `shadow-ring`, (中文(简体) ), 所以,一定有东西来定义这些。 这个CSS的货船.

选择 **一个** 两条路 装入两者意味着每个工具的两本.

### 您不使用 Tailwind — 导入已编译的样式表

```ts
import '@ekanos/ui/styles.css';
```

自成一体:"泰风"作"先行","设计符"作"轻而暗"作"并" 每一个工具类都释放出这个软件包中的组件——全部被预编译. 没有其他的安装, 没有建设步骤, 没有配置。 在Next.js、Vite、CRA工作, 一个平面 `<link rel="stylesheet">`任何东西.

### 您确实使用 Tailwind v4 — 导入预设

```css
@import 'tailwindcss';
@import '@ekanos/ui/theme.css';
```

登记符号地图( A)`--color-primary` → `--primary`,则 `--radius-*` 缩放, `shadow-ring`),两个主题的符号值,基础规则 `dark:` 变体,和一个 `@source` 指着这个包裹的捆绑,所以你 尾风建筑本身就产生部件的公用事业。 然后,你得到这个 Ekanos 符号 **你们自己** 阶级弦也.

同时出版的,如果您想要将棋子分开: `@ekanos/ui/tokens.css` (只是自定义属性,没有 Tailwind at -rules)和 `@ekanos/ui/base.css` (基本规则).

### 什麽 `styles.css` 没有,也没有

里面有公用设施 **此软件包的组件** 发射——由 编译在已建捆绑中找到的每个类字符串。 这不是一本 尾风.

这么说吧 `<Button>` 财务报告和审定财务报表 `<Card>` 正确转换,但有尾风课 _你们_ 写入 __ 构成部分`p-8`, (中文(简体) ), `grid-cols-3`, (中文(简体) ), `h-5 w-5`)没有规则,并且会 没什么 这是内在的: 预编的样式表无法知道类名 这还不存在。 两个选择,都很好:

-   样式,并带有简单的 CSS 或内线样式,或
-   沿着尾风去,这就是埃克诺斯自己的工作方式.

`styles.css` 包括Tailwind's Preflight,这是一个全球重置——它将 在整个页面中规范边距、标题和窗体控件。 如果是这样 是不受欢迎的, 使用 Tailwind 路径 和控制层你自己.

### 页面背景和暗模式

样式表不会在未邀请的情况下重新油漆您的页面 。 通过 Ekanos 的页面 表面——这就是使暗模式看起来正确而不是暗卡的原因 漂浮在白页上——添加选入类:

```html
<body class="ekanos-root">
```

暗模式在3个状态下解决,按此顺序:

| 状态 | 结果 |
| --- | --- |
| 无设置 | 光线 |
| `@media (prefers-color-scheme: dark)` | 阴暗 |
| `.dark` 或者说 `[data-theme='dark']` 祖先 | 黑暗, 打动媒体查询 |
| `.light` 或者说 `[data-theme='light']` 打开 `:root` | 轻而易举,击败媒体查询 |

因此,一个没有主题切换的合作伙伴应用程序仍然跟随OS,一个与 a 切换( 下个主题, 或者你自己的) 通过设置类来工作 。 埃卡诺斯本身就是 类; 在此添加没有切换器的应用程序的媒体查询 .

### Tokens:由Ekanos设计系统生成

`tokens.css` 由 Ekanos 的基础主题生成 Ekanos应用软件本身使用的符号样式表),因此它带有完整的语义集: 表面、品牌、状况 `-strong` 文本步骤、图表、边栏、, 整个海平面和 `--radius`只有 页眉和伙伴字体堆栈是手写; 下方所有 `GENERATED` 标记重写为:

```bash
pnpm --filter @ekanos/ui sync:tokens          # after changing a token in the app
pnpm --filter @ekanos/ui sync:tokens --check  # what CI's gate runs
```

管理设计系统页面在保存时为您运行同步 。 从不编辑 数值在 `tokens.css` 直接: 下一次同步覆盖它, 在此之前 构建和包件测试失败 .

汇编 `styles.css` 仍然可以精确地计算出组件所用的符号.

### 字体

Ekanos 设置文本为 **间**,包括助理的答复 标题 **城市主义者** 在400至500时`font-heading` 与 `font-heading-bold` 或者说 `font-heading-semibold`),两者均通过 `next/font`。仅此套件 给他们起名字 `--font-sans` 编号 : `--font-heading` 编号 : `--font-voice`,然后是 a system fall back堆栈——没有捆绑或取回webfont。 准确 打印等价, 自己装入 :

```html
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&family=Urbanist:wght@300..700&display=swap"
/>
```

没有它们,一切都会变成你平台的UI字体.

### 图标:含磷脂

`Icon` 绘制一个 [磷酸盐](https://phosphoricons.com/) glyph( 麻省理工学院) `<svg>` 持有图标字体的字符,所以 shadcn `[&_svg]` 选择器大小. 字体运入 `dist/fonts/` 财务报告和审定财务报表 `styles.css` 编号 : `base.css` 宣布他们,所以 没有什么可以安装的。 您的捆绑者必须处理 `.woff2` `url()`单位 CSS, Next.js, Vite 和 Webpack 5 从框中跳出( 需要建构) `--loader:.woff2=file`) (中文(简体) ). 浏览器只下载一页所绘制的权重 .

命名图标方式为phosphoricons.com: `"house"`, (中文(简体) ), `"caret-down"`, (中文(简体) ), `"github-logo"`。一个已填充的状态格(选定恒星)是 `"star:fill"`; 内容 保持每个样式的填充。 将低于一分的每样东西都重新做为一分:

```tsx
import { IconStyleOverrideProvider } from '@ekanos/ui/icon';

<IconStyleOverrideProvider value="bold">{children}</IconStyleOverrideProvider>;
```

风格是 `light`, (中文(简体) ), `regular`, (中文(简体) ), `bold`, (中文(简体) ), `solid` (Phosphor的填充重量) 财务报告和审定财务报表 `duotone`。移动前的字体优美名称(`"fa-house"`, (中文(简体) ), `"fa-brands fa-github"`) 仍然绘制出其等同的磷酸盐,以及一个名称 匹配不绘制图标 `shapes` 而不是消失。 检查名称 `isRenderableIconName()`。 。 。 .

一个图标是 16px, 除非是大小类(`size-5`,或组件的 `[&_svg]` 规则)或 `--icon-glyph-size` 在一个容器上说,不然。 就像一个明亮 图标, `Icon` 取 SVG 道具( R)`aria-label`, (中文(简体) ), `role`, (中文(简体) ), `data-icon`) (中文(简体) ).

## 运行时间笔记

-   **原始是基础UI,而不是Radix.** 所有弹出形状都是建立在 `@base-ui/react` (宣布的依赖关系)。 没有 `asChild` ——多形态部分取用 (单位:千美元) `render` 道具 : `<DropdownMenuTrigger render={<Button />}>Menu</DropdownMenuTrigger>`。 。 。 .
    
-   **`Trans` 解析与主机的下一封信件相悖.** 是个客户 用于读取下层上下文的组件,因此它必须在 `NextIntlClientProvider`Ekanos主机在它的根上挂起一个并 `@ekanos/harness`是因为 `RootLayout` 为您挂载; 其它任何地方( a) 故事本,裸出单元测试)将树包成一. 空信件为 足够了,因为缺失的密钥使 `defaults`数字 :
    
    ```tsx
    <NextIntlClientProvider locale="en" messages={{}} timeZone="UTC">
      <Trans i18nKey="myIntegration:connect" defaults="Connect {{service}}" values={{ service: 'Drive' }} />
    </NextIntlClientProvider>
    ```
    
    密钥保存 `ns:key` 形状和 `defaults` 保留 `{{var}}` 内插. 当主机消息存在时, 密钥会解决它; 否则 `defaults` (内插,与 `components`,则 `children`,然后键本身. 完全没有供货商, `Trans` 掷出. 旧反应- i18next 构建 却让孩子沉默不语.
    
-   **`Spinner` 是自成一体的.** 它绘制一个内线 SVG 而不是字体 伟大的甘油,所以不像 `Icon` 它不需要图标网络字体——只有 Tailwind 公共事业`animate-spin`, (中文(简体) ), `size-*`, (中文(简体) ), `text-*`) (中文(简体) ). 它的荣誉 `prefers-reduced-motion` 通过 `motion-reduce:animate-none`,冻结弧 变成一个静态的忙碌的甘油.
    
-   **`'use client'` 被保存下来.** 客户条目`icon`, (中文(简体) ), `form`, (中文(简体) ), `tooltip`, (中文(简体) ), `label`, (中文(简体) ), `select`, (中文(简体) ), `dropdown-menu`, (中文(简体) ), `ai-prompt-input`, (中文(简体) ), `dialog`, (中文(简体) ), `separator`(中文(简体) ) 以指令为首的飞船. `utils`, (中文(简体) ), `if`, (中文(简体) ), `trans`, (中文(简体) ), 财务报告和审定财务报表 `spinner` 服务器安全且不带指令, 所以 `cn()` 保留 从服务器组件中可使用 .
    
-   **`ai` 是一个只属于类型的依赖.** `@ekanos/ui/ai-prompt-input` 用途 `ChatStatus` 编号 : `FileUIPart` 类型 `ai` 其公共道具中的包件; 没有 `ai` 代码在运行时导入.
    
-   **基础 UI 补丁差异( 小) .** 单曲补丁 `@base-ui/react@1.6.0` 以拓宽触发拖动边距抵消 (单位:千美元)`BOUNDARY_OFFSET` 2 — 菜单/选取/相框触发器中的24个). 发表 文物解析了 npm 的未批发软件包, 因此合伙人端菜单保留 上游的"新闻和垃圾选择"边界略为收紧. 只有化妆品.
    

## 同伴依赖关系

提供: `react` 编号 : `react-dom` (^19), (中文(简体) ), `react-hook-form` 财务报告和审定财务报表 `@hookform/resolvers` (用于表格使用). 所有其它部件需要的 运行时间是此软件包宣布的依赖 .

## 大楼/核查

```bash
pnpm --filter @ekanos/ui build      # tsdown → dist/, then the CSS build → the stylesheets
pnpm --filter @ekanos/ui pack:test  # clean-room publish gate
```

建筑分两个阶段运行,依此顺序,原因如下: `tsdown` 捆绑 组件,然后 CSS 构建扫描 _已建成_ `dist/*.js` 为类 通过 Tailwind 编译 。 驱动工具集 从构建输出而不是一个手垫列表 使得不可能 添加其类无 CSS 的组件.

剧本有四个致命的门:

-   **摇摆** ——每个 `var(--x)` 必须定义到达的符号地图.
-   **覆盖范围** ——同一类的弦被重新编译来对抗埃克诺斯的满分 符号映射, 如果组件开始使用符号, 则构建失败 包裹不载运。 没有它,这种效用只会悄悄地释放 没什么.
-   **锁定步骤** —— 说 `tokens.css` 将其暗值拼出两次( 媒体查询) 和一个明确的选择者,因为CSS不能在他们之间共享一个块) 必须保持一致.
-   **来源均等** ——每个值 `tokens.css` 必须等于Ekanos的 `@kit/ui/styles/tokens.css`,以及 `theme.css` 必须绘制每一种颜色、阴影、半径和 ekanos 字体条目 `@theme`覆盖证明姓名存在;这证明 数值匹配. `src/styles/__tests__/token-parity.test.ts` 运行相同 检查包测试.

`pack:test` 装入焦油球, 声称只装有零星内容, 任何内容失败 `@kit/` 泄漏,声称 `'use client'` 保存,然后安装沥青球 进入工作空间和排字检查以外的临时项目 (单位:千美元)`skipLibCheck: false`\+ 由消费者进口每个子路径.

它也打开了样式表: 所有四个必须飞船, 清除一个大小的地板,仍然 包含已知的公用事业和两个主题状态,通过建设解决: `@ekanos/ui/styles.css`,并携带 **没有** 图标字体数据 - `@font-face`页:1 网络font 引用或格言表格 `dist/` 失败的构造, 同样 许可理由 : 存在 Makerkit 家族检查 .

`prepack` 经营建筑,所以出版商 永远不能运送一个 stale 或缺失 `dist/`。 。 。 .

## 常见问题

### @ekanos/ui 是什么？

埃克诺斯被称作UI原始人,用于在单列波外建造埃克诺斯集成\. 内部的@kit/ui图书馆被整理并出版的片段\.

### 如何安装 @ekanos/ui？

在项目目录运行 npm install @ekanos/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2\.8）、next-intl（^4\.14\.7）、react-dom（^19\.2\.8）、react-hook-form（^7\.68\.0）、@hookform/resolvers（^5\.2\.2 \|\| ^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ekanos/ui 支持 TypeScript 吗？

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

### @ekanos/ui 支持 ESM 还是 CommonJS？

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

### @ekanos/ui 可以商用吗？

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

### @ekanos/ui 的下载量有多少？

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

### @ekanos/ui 还在维护吗？

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