# @flipdish/ui-library 中文文档

规范地址：https://npmcn.com/package/%40flipdish/ui-library/

版本：0\.52\.0
npm 元数据更新时间：2026-11-15T17:53:42.873Z
中文译文更新时间：2026-11-15T17:55:54.033Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40flipdish/ui-library
原文对照：https://npmcn.com/package/%40flipdish/ui-library/?lang=original
源码仓库：https://github.com/flipdishbytes/flipdish-design-system

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

- 包体积（解压后）：6.2 MB，2474 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：zod ^4\.4\.0，react ^19\.0\.0，shiki ^4\.2\.0，motion ^12\.40\.0，recharts ^3\.8\.1，input-otp ^1\.4\.2，react-dom ^19\.0\.0，@tiptap/pm ^3\.27\.1，nativewind ^5\.0\.0-rc\.0，react-aria 3\.50\.0，@tiptap/core ^3\.27\.1，lightningcss \>=1\.27\.0 \<1\.33\.1，react-native \>=0\.81\.0，react-router ^7\.0\.0，@tiptap/react ^3\.27\.1，tailwind-merge ^3\.6\.0，qr-code-styling ^1\.9\.2，react-hook-form ^7\.91\.0，react-native-css ^3\.1\.0-rc\.0，react-native-svg \>=15\.0\.0，@expo/metro-config \>=54\.0\.0，react-hotkeys-hook ^5\.3\.2，@hookform/resolvers ^7\.0\.5，@tiptap/starter-kit ^3\.27\.1，embla-carousel-react ^8\.6\.0，react-aria-components 1\.19\.0，@tiptap/extension-image ^3\.27\.1，postcss-prefix-selector ^2\.1\.1，@react-native-aria/focus \>=0\.2\.7，hast-util-to-jsx-runtime ^2\.3\.6，@tiptap/extension-text-align ^3\.27\.1，@tiptap/extension-text-style ^3\.27\.1，@tiptap/extension-placeholder ^3\.27\.1，@react-native-aria/interactions \>=0\.2\.7
- 首次发布：2026-06-22T11:35:10.398Z
- 最新版本发布：2026-11-15T17:53:42.681Z
- 近 30 天下载量：9276（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：122（近 12 个月 122 个）

## 中文简介

Flipdish Design System — 原子-设计组件库(Tailwind v4 + 无标题UI + React Aria).

## 安装

```sh
npm install @flipdish/ui-library
```

也可以使用：`pnpm add @flipdish/ui-library`、`yarn add @flipdish/ui-library`、`bun add @flipdish/ui-library`

## README

# `@flipdish/ui-library`

Flipdish 产品的再设计组件库 **尾风 CSS v4**, (中文(简体) ), [无标题 UI](https://www.untitledui.com/) 原始人,还有 [反射 Aria 组件](https://react-spectrum.adobe.com/react-aria/)。今天,Web-first,与回放土著(通过 [原生窗口](https://www.nativewind.dev/)支持每个部分的推广.

> **内部设计体系,公开发布.** 这个软件包是为Flipdish的品牌和工具而构建和调制的. 它在公用npm注册号上,这样它就可以被分享到Flipdish微前端和app上——它不是作为通用的UI工具包.

**Flipdish设计系统的一部分:**

| 软件包 | 目的 |
| --- | --- |
| [`@flipdish/ui-tokens`](https://www.npmjs.com/package/@flipdish/ui-tokens) | 设计符号——颜色、类型尺度、间隔 |
| [`@flipdish/ui-icons`](https://www.npmjs.com/package/@flipdish/ui-icons) | 图标集 |
| **`@flipdish/ui-library`** | 组件( 本套件) |
| [`@flipdish/ui-connected`](https://www.npmjs.com/package/@flipdish/ui-connected) | API 连接组件 |

## 安装

```bash
pnpm add @flipdish/ui-library @flipdish/ui-tokens @flipdish/ui-icons
```

关于完整的设置行走(Vite 配置、 CSS 条目、 提供者、 第一个组件),见 [开始安装](https://flipdishbytes.github.io/flipdish-design-system/?path=/docs/getting-started-installation--docs)。 。 。 .

### 同伴依赖关系

**共享——要求在每个平台:**

| 软件包 | 版本 |
| --- | --- |
| `react` | `^19.0.0` |
| `tailwind-merge` | `^3.6.0` |

**网络 :**

| 软件包 | 版本 |
| --- | --- |
| `react-dom` | `^19.0.0` |
| `react-aria` | `3.50.0` |
| `react-aria-components` | `1.19.0` |
| `react-router` | `^7.0.0` |

**原生反应 :**

| 软件包 | 版本 |
| --- | --- |
| `react-native` | `>=0.81.0` |
| `nativewind` | `^5.0.0-preview.4` |
| `react-native-css` | `^3.0.7` |
| `lightningcss` | `>=1.27.0 <1.30.2` |
| `@expo/metro-config` | `>=54.0.0` |
| `@react-native-aria/interactions` | `>=0.2.7` |
| `@react-native-aria/focus` | `>=0.2.7` |

> **`lightningcss` 必须被钉住 `1.30.1`。 。 。 .** 本地窗口 v5 + `react-native-css` 可以击出 `failed to deserialize` 版本错误 `>=1.30.2` (见《大会正式记录,第五十八届会议,补编第6号》) [本地窗口安装指南](https://www.nativewind.dev/v5/getting-started/installation)) (中文(简体) ). 这只会影响 __ 应用软件的安装 —— 图书馆自己的版本针不能向消费者传播 —— 所以把这个添加到您的应用软件中 `package.json`数字 :
> 
> ```json
> { "overrides": { "lightningcss": "1.30.1" } }
> ```
> 
> (单位:千美元)`pnpm` 工程: 在顶层嵌入 `"pnpm"` 键代替 - `{ "pnpm": { "overrides": { "lightningcss": "1.30.1" } } }`. ) (中文(简体) )

### 具体组成部分的同行依赖性

少数部分由较大的第三方图书馆作为后盾 **选项** 同行——导入 `Button` 永远不要在图表或丰富文本堆栈中拉出。 只为您实际使用的组件安装对等点; 缺失的对等点会导致构建/运行时间出错 .

| 构成部分 | 所需对等点 |
| --- | --- |
| `Charts` | `recharts` |
| `CodeSnippet` | `shiki`, (中文(简体) ), `hast-util-to-jsx-runtime` |
| `TextEditor` | `@tiptap/core`, (中文(简体) ), `@tiptap/pm`, (中文(简体) ), `@tiptap/react`, (中文(简体) ), `@tiptap/starter-kit`, (中文(简体) ), `@tiptap/extension-image`, (中文(简体) ), `@tiptap/extension-placeholder`, (中文(简体) ), `@tiptap/extension-text-align`, (中文(简体) ), `@tiptap/extension-text-style` |
| `Carousel` | `embla-carousel-react` |
| `QRCode` | `qr-code-styling` |
| `VerificationCodeInput` | `input-otp` |
| `CommandMenu` | `react-hotkeys-hook` |
| `FileUpload`, (中文(简体) ), `SidebarNavigation` | `motion` |
| `forms/*` (除外) `FormSection`(中文(简体) ) | `react-hook-form`· ; `forms/validation` 需求 `zod` 财务报告和审定财务报表 `@hookform/resolvers` 还有 |

## 尾风设置

从您的 CSS 条目导入库共享运行时间 **在这个精确的层顺序中**数字 :

```css
@layer theme, base, components, utilities;

@import 'tailwindcss/theme.css' layer(theme);
@import '@flipdish/ui-tokens/css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import '@flipdish/ui-library/styles';
@import 'tailwindcss/utilities.css' layer(utilities);
```

## 原生反应

组成部分是: **网络首选,并选择每个组件**。在React上有一个组件 只有在有 `.native.tsx` 执行;其余仅限网页,而且 故意无法从 RN 应用程序中解析 .

用于全博览会的走通(Metro Cfig, 土著Wind CSS条目, TypeScript, 第一部) 见 [开始 —— 安装( 反应) (原始内容)](https://flipdishbytes.github.io/flipdish-design-system/?path=/docs/getting-started-installation-react-native--docs)。 。 。 . 下文概述要点.

**可在今天的土著反应中找到:** `Avatar`, (中文(简体) ), `Button`,加上 `cx`, (中文(简体) ), `testIdUtils` 财务报告和审定财务报表 `isReactComponent` 公用事业。 故事书是现场参考:每个组件的docs页面 携带一个 **原生反应** 部分详细列出平台支持的道具,以及 页:1 **平台** 在工具栏中切换将它的故事与 React 原生重现 执行.

各个平台的导入路径相同——地铁通过 `react-native` [出口条件](https://metrobundler.dev/docs/package-exports)数字 :

```tsx
// Resolves to the web build under Vite/webpack, the native build under Metro.
import { Avatar } from '@flipdish/ui-library/components/atoms/Avatar';
```

> `react-native >= 0.81` 是有负载的, 不只是一个版本的地板。 每一个公众的子路径 此包通过通配符曝光 `exports` 地图, 而 Metro 只咨询 `exports` 并启用软件包导出 — 从 Metro 0.82 / RN 0.79 继续默认。 打开 任何更古老的, 这个包的子路径 根本没有解决.

### 尾风设置( NativeWind)

使用 **`styles.native`** 条目,不 `styles`。网络运行时间宣布 Tailwind 插件, `::-webkit-scrollbar` 水电费 `html`编号 :`input` 重新使用在 NEVIND 下, 联 合 国 `@source` 为类扫描网页构建输出.

在你的应用 `global.css` —— 从根组件和点导入的文件 [`withNativewind`](https://www.nativewind.dev/v5/api/with-nativewind) 时值 `metro.config.js`数字 :

```css
@import 'tailwindcss/theme.css' layer(theme);
@import '@flipdish/ui-tokens/css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);

/* NativeWind's own theme variables — required by its Metro transformer. */
@import 'nativewind/theme';

@import '@flipdish/ui-library/styles.native';
@import 'tailwindcss/utilities.css';
```

`styles.native` 贡献了一件事: `@source "./native"`,它告诉 Tailwind 到 扫描此软件包的 React Circuit 构建输出, 以便内部的类字符串 `Avatar`, (中文(简体) ), `Button` (和每个) (b) 产生公用事业。 没有它,这些部件就变成无型 -- 尾风忽略 `node_modules` 除非一个来源被明确宣布.

暗模式通过 Nerifind 遵循设备颜色方案 `useColorScheme`. (网络 运行时间代替再映射 `dark:` 打开 `[data-theme="dark"]`,它没有RN等同物. )

> 这个 `@source` 镜像什么 `./styles` 已经在网上做了,在其中证明 生产。 准确 **上方的导入顺序** 仿照了NeignWind v5的文献记录 安装且尚未针对真正的 Expo 应用程序执行 (a) 下述预先核查.

### 类型脚本设置

添加数据 `react-native` 应用程序的条件 `tsconfig.json` 因此 TypeScript 解析 同样的文件 Metro 做 :

```jsonc
{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "node16" / "nodenext"
    "customConditions": ["react-native"],
  },
}
```

没有它,你得到 **网络** 类型定义 - `Avatar` 似乎会接受 `src` 财务报告和审定财务报表 `badge`(b) 既非当地执行所支持的`initials` 页:1 由本地支持).

### 导入尚未可用的组件

TypeScript和Metro都拒绝,因此错误无法到达设备:

```text
error TS2305: Module '"@flipdish/ui-library/components/atoms/Button"'
              has no exported member 'Button'.
```

```text
Unable to resolve module .../dist/native/components/atoms/Button/index.js
```

## 将 Tailwind CSS 扫描到子树

当您的应用程序不拥有整个页面时——一个部件,一个嵌入器,一个故事本预览,一个多用户主机,或者一个微前端——它的Tailwind v4输出(用户) **财务报告和审定财务报表** Preflight resets)可以渗入或与周围的CSS相冲突. 固定是把每个被排放的选取者 都放入应用程序的单个元素之下: `UIProvider`是因为 `scopeId` 邮票 `data-mfe-scope` 上面的标本根。 绝不进入主机集装箱代号(`#flipdish-micro-frontend`)或身份证明的结合;几个应用软件共享这些容器,因此规则在它们之间漏出.

`@flipdish/ui-library/utilities/cssScopeUtils` 船舶 `createScopedPrefixTransform`一个小型工厂 [`postcss-prefix-selector`](https://www.npmjs.com/package/postcss-prefix-selector) 合并范围界定规则(范围) `:root`编号 :`html` 这样 `@theme` 只有树下才有标志和底打字级联,请离开 `:host` 财务报告和审定财务报表 `@keyframes` 单步,从不双前缀等),所以您会写出一行来代替复制的活字化转换.

安装同伴插件( 可选的端口) :

```bash
pnpm add -D postcss-prefix-selector
```

然后添加到您的 PostCSS 配置中 :

```js
// postcss.config.mjs
import prefixSelector from 'postcss-prefix-selector';
import { createScopedPrefixTransform } from '@flipdish/ui-library/utilities/cssScopeUtils';

// Your Portal microFrontendWindowName; must match <UIProvider scopeId="sale-service">.
const SCOPE = '[data-mfe-scope="sale-service"]';

export default {
  plugins: [
    prefixSelector({
      prefix: SCOPE,
      transform: createScopedPrefixTransform(SCOPE),
    }),
  ],
};
```

尾风的输出变得平淡 `[data-mfe-scope="sale-service"] .px-4 { … }`,每个下游工具(Vite,闪电)都会理解.

### 选项

`createScopedPrefixTransform(scopeSelector, options?)`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `shouldScope` | `(filePath: string | undefined) => boolean` | `() => true` | 返回时 `false` 以保留一个文件的选取器而不受影响(例如第三方 CSS,你不希望前缀). |
| `scopeBody` | `boolean` | `false` | 范围 `body` 重置为挂载选择器而不是离开 `body` 全球。 当主机页面不能继承重置时启用 . |
| `matchRootElement` | `boolean` | `true` | 同时发射一个化合物选择器,使范围根本身符合类和属性选择器; `[data-theme="dark"]` 根部需要这个. |

```js
createScopedPrefixTransform('[data-tailwind]', {
  shouldScope: (file) => !file || !file.includes('node_modules'),
  scopeBody: true,
});
```

> **为什么是PostCSS而不是Tailwind的 `important(#selector)`? 吗?** 尾风v4's `important(...)` 语法释放出非标准 `@media important(...)` 闪电在微分化过程中无法解析的块,所以范围界定是作为PostCSS通过Tailwind输出完成的.

微前端为一用例;同样的变换适用于部件,嵌入式,故事本和多租户UI.

## 文档

完整组件文件、互动实例和设计指南在 [故事书](https://flipdishbytes.github.io/flipdish-design-system/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/flipdishbytes/flipdish-design-system/blob/main/packages/ui-library/CHANGELOG.md) 为释放历史.

## 捐款

这个包裹住在 [`flipdish-design-system`](https://github.com/flipdishbytes/flipdish-design-system) 单相机 贡献者文件——文件夹常规,无标题的UI组件如何被调整,网络/本地文件分割,依赖性规则——与源并存.

## 常见问题

### @flipdish/ui-library 是什么？

Flipdish Design System — 原子-设计组件库\(Tailwind v4 \+ 无标题UI \+ React Aria\)\.

### 如何安装 @flipdish/ui-library？

在项目目录运行 npm install @flipdish/ui-library，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、tailwind-merge（^3\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flipdish/ui-library 支持 TypeScript 吗？

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

### @flipdish/ui-library 支持 ESM 还是 CommonJS？

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

### @flipdish/ui-library 可以商用吗？

@flipdish/ui-library 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @flipdish/ui-library 的下载量有多少？

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

### @flipdish/ui-library 还在维护吗？

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