# @appica/ui-react 中文文档
规范地址：https://npmcn.com/package/%40appica/ui-react/
版本：1\.4\.0
npm 元数据更新时间：2026-11-01T18:49:02.853Z
中文译文更新时间：2026-11-06T11:30:23.108Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40appica/ui-react
原文对照：https://npmcn.com/package/%40appica/ui-react/?lang=original
项目主页：https://appica.dev/ui
源码仓库：https://github.com/appica-dev/appica-ui
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：5.4 MB，612 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：16 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，tailwindcss ^4\.0\.0，@types/react ^19\.0\.0
- 首次发布：2026-07-09T19:57:49.091Z
- 最新版本发布：2026-11-01T18:49:02.693Z
- 近 30 天下载量：19698（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）
## 中文简介
用于 React 应用程序的 Appica UI 组件库
## 安装
```sh
npm install @appica/ui-react
```
也可以使用：`pnpm add @appica/ui-react`、`yarn add @appica/ui-react`、`bun add @appica/ui-react`
## README
[](https://appica.dev/ui)
[](https://www.npmjs.com/package/@appica/ui-react) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://www.figma.com/community/file/1657080448204231925)
现代 React 组件库 - 70+ 可访问、可主题的组件 [基础UI](https://base-ui.com/) 原始人,动画 [动议](https://motion.dev/),并使用 Tailwind CSS v4 设计符号来命名.
**[文档](https://appica.dev/ui) • 妇女 [安装指南](https://appica.dev/ui/docs/react/installation) • 妇女 [构成部分](https://appica.dev/ui/components/react/button)**
## 先决条件
| 依赖性 | 版本 |
| --- | --- |
| 反应 | `>= 19` |
| 反应 DOM | `>= 19` |
| 尾风 CSS | `>= 4.0` |
反应19是一个硬性要求 - 组件使用现代 ref-as-prop API 没有 `forwardRef` 嘘 Tailwind v4 必须先在您的工程中设置和编译; Appica UI 依赖您的工程的 Tailwind来编译组件样式 .
## 安装
```bash
npm install @appica/ui-react
# or
yarn add @appica/ui-react
# or
pnpm add @appica/ui-react
# or
bun add @appica/ui-react
```
## 配置尾风
在您的全局样式表中导入 Tailwind 后的设计符号, 并添加一个 `@source` 指令所以 Tailwind 扫描编译库的类名 :
```css
@import 'tailwindcss';
@import '@appica/ui-react/styles.css';
@source '../node_modules/@appica/ui-react/dist';
```
> **别跳过 `@source` - 并给它一个真正的路径.**
>
> 尾风忽略 `node_modules` 默认。 没有 `@source` 指令不会生成编译组件中使用的实用类,它们会变成不风格.
>
> `@source` 选择路径或阴影 **相对于包含它的样式表**而不是一个赤裸的包名 - `@source '@appica/ui-react'` 不解而无声地扫描任何东西。 数 `../` 需要达到 `node_modules` 从您的 CSS 文件: 深为一层的样式表( S)`app/globals.css`, (中文(简体) ), `src/index.css`)需要单人 `../`;更深处(`src/styles/app.css`需求 `../../`。这符合 Tailwind 自己的 [`@source` 文档](https://tailwindcss.com/docs/functions-and-directives#source-directive),其实例是 `@source '../node_modules/@my-company/ui-lib';`。 。 。 .
## 没有尾风
Appica UI建于Tailwind上,上面的源扫描设置是推荐路径. 如果您的工程不使用 Tailwind, 请跳过该步骤并导入预建的样式表 - 一个包含每个组件的样式和完整符号系统编译的自定义文件 :
```css
@import '@appica/ui-react/css';
```
没有捆绑? 从 CDN 直接链接( 为缓存稳定性选择一个版本) :
```html
```
尾风保持了可选的对等依赖性,所以在您走这条路径时,没有任何东西代表您安装. 设计符号仍为 CSS 变量, 因此它们仍然以同样的方式工作 - 导入后重新定义变量 :
```css
:root {
--primary: oklch(60% 0.25 150);
}
```
> **别同时装货.**
>
> 预建的文件捆绑了Tailwind的"飞行前"重置,只有象征变量(颜色,字体,光线,阴影)仍然可以压倒一切——在发布时结构的公用设施被冻结. 如果您已经运行 Tailwind, 请使用 [配置尾风](https://npmcn.com/package/%40appica/ui-react/#readme-configure-tailwind) 换成是,否则你会两次运送重置和公用事业.
## 添加提供者
将您的应用程序包入 `ThemeProvider` 以启用主题和暗模式,而不闪出错误的主题:
```tsx
import { ThemeProvider } from '@appica/ui-react/providers/theme-provider'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
## 使用组件
从它们的子路径导入组件以获取最小的捆绑 :
```tsx
import { Button } from '@appica/ui-react/button'
export default function App() {
return
}
```
见 [安装指南](https://appica.dev/ui/docs/react/installation) 用于特定框架注释(Next.js、Vite、TanStack Start、Remix、Astro),以及 [他们](https://appica.dev/ui/docs/react/theming) 要定制颜色,光度,和符号.
## 对于人工智能特工
如果您是一个编码代理从读取 `node_modules`,正确写入 Appica UI 代码的规则 [`agent-rules.md`](https://npmcn.com/package/%40appica/ui-react/agent-rules.md),在此文件旁边。 在写入任何组件或CSS前读取. 它能防止的两个错误是昂贵的: 一个缺失 `@source` 指令使每个部件都不再被套用,而且以公共设施为主(`bg-gray-100`)绕过符号系统.
每个文件页都作为干净的标记 `.md` - 获取 `https://appica.dev/ui/components/react/button.md`,而不是 HTML 页面。 完整的索引,有一个指令块,在 [`https://appica.dev/ui/react/llms.txt`](https://appica.dev/ui/react/llms.txt)。 。 。 .
如果你是人 设置一个项目: 将这些规则 粘入你自己 `AGENTS.md` 所以,你的经纪人装满他们的每一场课。 见 [设置您的编码代理](https://appica.dev/ui/docs/react/agents) 一个复制块.
## 更改日志
每一版中的变化都发生在 [`CHANGELOG.md`](https://npmcn.com/package/%40appica/ui-react/CHANGELOG.md),在此文件旁边,并打开 [appica.dev/ui/changelog (中文(简体) )](https://appica.dev/ui/changelog) 与随同运出的文件和Figma更新一起.
## 图像设计文件
每一个部分都可以免费使用 [图像设计文件](https://www.figma.com/community/file/1657080448204231925) - 变体,尺寸,和状态 反射一对一与代码,基于相同的设计符号。 设计和开发来自一个单一的真理来源.
## 随时更新
跟随 [@ Appica dev](https://x.com/Appica_dev) 发布公告和更新.
## 许可证
麻省理工学院 [阿皮卡语Name](https://appica.dev/)
可在个人和商业项目中自由使用.
## 常见问题
### @appica/ui-react 是什么？
用于 React 应用程序的 Appica UI 组件库
### 如何安装 @appica/ui-react？
在项目目录运行 npm install @appica/ui-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @appica/ui-react 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @appica/ui-react 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @appica/ui-react 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @appica/ui-react 可以商用吗？
@appica/ui-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @appica/ui-react 的下载量有多少？
根据 npm 官方下载统计，@appica/ui-react 在 2026/10/07 – 2026/11/05 这 30 天内被下载 19,698 次，日均约 657 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @appica/ui-react 还在维护吗？
最新版本 1\.4\.0 发布于 2026/11/02（6 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/07/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。