@emoo-ai/ui-react

中文文档
0.1.7发布于 2026/11/05MITTypeScriptES Module近 30 天下载 1959

React 19 编译交付包:预编译样式 + 组件。宿主不需要 Tailwind、Sass 或任何 Vue/EP 工具链。

原始使用文档
文档目录4 节
  1. 使用
  2. Tailwind 4 共存
  3. 主题和 portal
  4. 组件族

@emoo-ai/ui-react

React 19 编译交付包:预编译样式 + 组件。宿主不需要 Tailwind、Sass 或任何 Vue/EP 工具链。

使用

import '@emoo-ai/brand/tokens.css'
import '@emoo-ai/ui-react/styles.css'
import { Button, Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription } from '@emoo-ai/ui-react'

不需要 Tailwind、Sass、扫描 node_modules 或安装 Vue/EP。JS 不注入样式,CSS 必须显式导入。React/React DOM 为 peers,Radix、图标和工具依赖按 package.json 安装。

Button 保留原生 ref/props、asChild、variant/size/shape 和 data-slot;buttonVariants 可独立生成同样的预编译工具类。Dialog 提供 Root、Trigger、Portal、Close、Overlay、Content、Header、Footer、Title、Description;Title/Description 必须由调用方按语义提供。

Tailwind 4 共存

组件使用包内预编译的 Tailwind 工具类(utilities layer),最小原生基线放在 components layer。必须先建立 layer 顺序,否则后加载的 preflight base 层可能压过库样式:

/* 先于组件 CSS 引入;可作为应用统一 CSS 入口。 */
@layer theme, base, components, utilities;
@import 'tailwindcss';
@import '@emoo-ai/brand/tokens.css';
@import '@emoo-ai/ui-react/styles.css';
/* 宿主覆盖最后;同为 utility 层时后写规则胜,cn 处理组件自身 className 冲突。 */

也可先导入只声明上述顺序的 layers.css,再从 JS 分别导入样式。库本身不带 preflight,所需工具类已预编译,不要求宿主扫描源码,不写全局 reset;cn/twMerge 不替代正确的 CSS 级联。

主题和 portal

宿主在 html 切换 .dark,或覆盖相应 --emoo-*;库不管理系统主题/localStorage。实心按钮使用 --emoo-btn-solid-bg/color,焦点使用品牌强调色,不把全部 primary 机械改为紫色。Dialog 使用不透明 --emoo-card-solid-bg。

默认 Portal 到 body,继承根 token;局部白标变量必须把 <DialogContent container={element}> 放进主题容器,保证继承。局部容器只覆盖指定变量,不代表 brand 自动支持嵌套 .dark。closeLabel 可注入本地化文案。

组件族

  • 基础:Button/ButtonGroup、Input/Textarea/NativeSelect、Field/InputGroup、Checkbox/RadioGroup/Switch/Slider/Select、Toggle/Tabs/Accordion。
  • 反馈:Alert/Badge/Empty/EmptyValue、Skeleton/Spinner/Progress/LoadingOverlay、Avatar、Toaster/toast。
  • 浮层:Dialog/AlertDialog/Sheet/Drawer(Vaul)/Popover/Tooltip/HoverCard/DropdownMenu/ContextMenu/Command。
  • 复合件:Chips/Segmented/TagsInput/ValueDiff/HistoryList;表单字段(DatePicker/AmountInput/SpecField)、Upload、DataTable(TanStack Table 封装,支持虚拟滚动)、SearchBox、NavMenu/NavSegmented、SidebarShell、GhostButton/ActionPill。
  • 框架原语:Direction/AspectRatio/Resizable/ScrollArea/InputOTP、Card/Item/Kbd/Separator/Pagination/Attachment。

Progress 向 Radix 传递真实 value/max,非有限值为不确定态;CommandDialog 自带 cmdk 根上下文。Select clearable 维持受控清空与 placeholder 协议,disabled 不可清空。浮层 Content 可选 container。

Toaster 可传 theme,缺省观察根 .dark,不保存偏好。Sonner/Vaul 等第三方组件可能自行注入其上游运行时样式;本包 Tailwind 样式仍须显式导入。默认文案暂为中文/英文两套,不宣称完整 i18n。

本包以编译产物方式发布,源码不随包。

版本与发布记录

@emoo-ai/ui-react 共发布 10 个版本,首次发布于 2026/10/29;过去 12 个月发布了 10 个版本。

版本发布日期距今
0.1.7latest2026/11/0511 天前
0.1.62026/11/0213 天前
0.1.52026/11/0214 天前
0.1.42026/11/0114 天前
0.1.32026/11/0114 天前
0.1.22026/11/0114 天前

其他发布通道:alpha → 0.1.0-alpha.1。

关于 @emoo-ai/ui-react 的常见问题

@emoo-ai/ui-react 是什么?

React 19 编译交付包:预编译样式 + 组件。宿主不需要 Tailwind、Sass 或任何 Vue/EP 工具链。

如何安装 @emoo-ai/ui-react?

在项目目录运行 npm install @emoo-ai/ui-react,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^19.2.8)、react-dom(^19.2.8)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@emoo-ai/ui-react 支持 TypeScript 吗?

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

@emoo-ai/ui-react 支持 ESM 还是 CommonJS?

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

@emoo-ai/ui-react 可以商用吗?

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

@emoo-ai/ui-react 的下载量有多少?

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

@emoo-ai/ui-react 还在维护吗?

最新版本 0.1.7 发布于 2026/11/05(11 天前);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/10/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。