# @flipova/foundation 中文文档

规范地址：https://npmcn.com/package/%40flipova/foundation/

版本：3\.1\.0
npm 元数据更新时间：2026-11-16T11:32:56.426Z
中文译文更新时间：2026-11-16T12:56:09.663Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flipova/foundation
原文对照：https://npmcn.com/package/%40flipova/foundation/?lang=original
项目主页：https://github.com/flipova/foundation#readme
源码仓库：https://github.com/flipova/foundation

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

- 包体积（解压后）：4.1 MB，349 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：33 个
- peer 依赖：expo \>=55\.0\.0，react \>=18\.0\.0，react-dom \>=18\.0\.0，nativewind \>=4\.1\.23，lucide-react \>=0\.400\.0，react-native \>=0\.72\.0，@tamagui/core \>=3\.0\.0，expo-glass-effect \>=55\.0\.0，react-native-paper \>=5\.15\.0，@rn-primitives/switch \>=1\.0\.0
- 首次发布：2026-06-13T12:43:53.795Z
- 最新版本发布：2026-11-16T11:32:56.083Z
- 近 30 天下载量：2328（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

Flipova设计系统的基础:一个供应商-不可知的UI合同(57个组件),五个供应商(flipova,胶囊,可再用,纸张,tamagui),以及一个注册驱动的具有本地图形用户界面的工具链.

## 安装

```sh
npm install @flipova/foundation
```

也可以使用：`pnpm add @flipova/foundation`、`yarn add @flipova/foundation`、`bun add @flipova/foundation`

## README

# @flipova/创建

[![npm version](https://img.shields.io/npm/v/@flipova/foundation.svg)](https://www.npmjs.com/package/@flipova/foundation) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

用于反应原生(iOS,Android)和Web的UI组件 **一个设计适用于一切**。 。 。 . 写入 `<Button>` 一次; 选择哪个库可以创建它( Flipova 属于自己的, 粘合层, React Introduct ) 在一行中可重复使用, React Environment paper, Tamagui);外观来自您自己的 XML 主题, 用于视觉编辑的 `npx flipova-design gui`。 。 。 .

## 快开始

```bash
npm install @flipova/foundation
npx flipova-design adopt     # copies the neutral starter themes into your project, writes theme/provider.tsx
npx flipova-design gui       # edit colours, scales and themes visually (or edit design/*.xml by hand)
npm run design:gen           # -> theme/design-theme.ts (+ Tailwind artifacts)
```

```tsx
import { AppThemeProvider } from './theme/provider';
import { Button, Card, Heading, Input, Select, Tabs } from '@flipova/foundation';

export default () => (
  <AppThemeProvider mode="system">
    <Card>
      <Heading>Sign in</Heading>
      <Input placeholder="Email" />
      <Button onPress={signIn}>Continue</Button>
    </Card>
  </AppThemeProvider>
);
```

`theme/provider.tsx` 是您的: 它命名了库,并将您生成的主题交给组件.

```tsx
<FlipovaProvider adapter={flipova} theme={designTheme} mode={mode}>
```

通过更改切换库 `flipova` 改为 `paper`, (中文(简体) ), `tamagui`, (中文(简体) ), `reusables` 或者说 `gluestack` (每个进口自 `@flipova/foundation/providers/<name>`) (中文(简体) ). 没有什么变化.

## 东西在哪里

```
components/
  theme/          design-theme.ts       generated from your XML: every colour of every theme, every scale
  contract/       what a component is   props (types.ts) + recipes/ (one pure function per component: the exact
                                        colours, radii, spacings, sizes) + theme resolution
  providers/
    provider.tsx  <FlipovaProvider>     mounts one library with one theme
    rn-base/      React Native's own components, shared by every adapter
    flipova/      Flipova's own         all 57 components, built from react-native only, styled only by the recipes
    gluestack/    gluestack-ui         adapter (31 native) + ui/ (the whole gluestack catalogue, as it was)
    reusables/    React Native Reusables  adapter (31 native), NativeWind classes
    paper/        React Native Paper      adapter (31 native)
    tamagui/      Tamagui                 adapter (32 native)
  ui/             the unified components   import { Button } from '@flipova/foundation' (or '/ui')
design/           the XML registries, the schema, and the toolchain (tools/: CLI, generator, checker, GUI)
```

**统一 `ui`** 使每个部分的选定图书馆提供的设计 应用。 当图书馆没有的时候 **flipova 提供者** 供养它(当没有供养者的时候) 完全挂载, flipova 与捆绑的中性主题),所以从没有孔.

合同是 **整个胶囊目录:57个组件**. filpova 执行全部; 所有其他 提供者以本地方式执行图书馆真正拥有的东西,测试可以核实,其余则由 费波娃 准确的表格是 [`COMPONENTS.md`](https://npmcn.com/package/%40flipova/foundation/COMPONENTS.md) (生成),以及 `coverageOf(adapter)` 用密码说.

| 提供者 | 土著 | 其中,图书馆自己的 | 其中反应土著(共享) | 服务于花花公子 |
| :-- | :-- | :-- | --: | --: |
| 费洛娃 | 页:1 | 第43条 | 页:1 | 0 个 |
| 胶层 | 31个 | 31个 | 0 个 | 第 26 条 |
| 可重复使用的项目 | 31个 | 第 19 条 | 第12条 | 第 26 条 |
| 纸张 | 31个 | 页:1 | 页:1 | 第 26 条 |
| 塔马吉 | 第32条 | 20国 | 第12条 | 第25条 |

每个适配器都是土生土长的,为合同的一半以上. "反应原生"是反应的14个组件 本地人本身(View, ScrollView, 平板电脑, sectionList, 虚拟化List, SafeAreaView, 键盘AvoidingView, ), 状态栏,刷新控制,输入存取视频,图像,图像背景,可压缩,盒:没有库替换它们, 所以他们住过一次 `providers/rn-base` 每个适配器不包 自己的服务.

**对齐检查** (单位:千美元)`components/alignment.test.ts`,该部分 `npm test`:胶囊目录的每一个目录 必须绘制成合同名称(一个新的名称失败,直到到期),该绘图为一对一 `UI_NAMES`,菲尔多瓦 每个名字都有文件 统一 `ui` 出口每个名称,适配方只申报合同名称 `COMPONENTS.md` 最新数据(`npm run components:doc` 重写).

诚实限制: 四个粘合层模块( 下表、 取日期、 图像查看器、 滑行器) 无法装入 测试环境(只有本地或缺失的依赖关系),所以没有为他们宣布胶纸包装。 这个 动画库粘接器( react-native-reanimated, @legendapp/motion)在测试中被替换为 待命人员 `test-support/` (平面观点,无动画):所验证的是胶层组件及其 包装,不是动画。 相接相接相接相接相接相接( Accordion, Menu, Popover, Select,, Tabs, Toast, Tooltip...)在COMPONENTS.md中以理由列出;添加了包装器是: 在适配器中写入, 把它加进它的 `components`, (中文(简体) ), `npm run components:doc`。 。 。 .

每个供应商的道具相同(`components/contract/types.ts`) (中文(简体) ). 图标是文本格言( 无 SVG ) 依赖、日历和日期`YYYY-MM-DD`),以及 `Portal` 内容由 法尔波娃供应商主机.

直接到一个图书馆的组件,从它的子路径导入 (单位:千美元)`@flipova/foundation/providers/paper`, (中文(简体) ), `.../providers/gluestack/ui` 整个胶囊目录,... 只有副路径 导入库,这是一个 **可选同伴依赖**: 根头, `/ui`, (中文(简体) ), `/contract`, (中文(简体) ), `/providers` 财务报告和审定财务报表 `/providers/flipova` 不需要任何东西 `react` 财务报告和审定财务报表 `react-native`。 。 。 .

| 子路径 | 图书馆 | 可选对等点 |
| :-- | :-- | :-- |
| `@flipova/foundation` , (中文(简体) ), `/ui` | 统一构成部分 | 无 |
| `@flipova/foundation/providers/flipova` | 菲尔波娃自己的 | 无 |
| `@flipova/foundation/providers/gluestack` | 胶袋- ui | `nativewind` |
| `@flipova/foundation/providers/reusables` | 反应原生再使用 | `@rn-primitives/switch` |
| `@flipova/foundation/providers/paper` | 反应原生纸 | `react-native-paper` |
| `@flipova/foundation/providers/tamagui` | 塔马吉 | `@tamagui/core` |

## 设计是你的

货船 **没有品牌和主题名称**: 只有中性启动器( q)`light` 财务报告和审定财务报表 `dark`) (中文(简体) ). `adopt` 复制到 `design/` 从那时起,你们在天经地经中, 这个 组件读取颜色 **角色** (单位:千美元)`primary`, (中文(简体) ), `card`, (中文(简体) ), `border`, (中文(简体) ), `success`,... ),从来没有主题ids,所以 自由重命名、添加和再颜色主题; 浅/暗对共享 a `variant` (单位:千美元)`<FlipovaProvider variant="brand">`) (中文(简体) ). 主题必须确定各组成部分的作用 (单位:千美元)`REQUIRED_ROLES`); 图形用户界面, `flipova-design check` 中,所有缺失的选项.

-   **键** (单位:千美元)`design/tokens.xml`:彩色调色板,相距相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相.
-   **主题** (单位:千美元)`design/themes.xml`:每个主题地图角色到调色板颜色(`$ref.tokens.color.primary.600`)或为一字色.

### `npx flipova-design gui`

本地编辑器( 没有任何东西离开您的机器; 它会用一次性符号在127. 0.0.1 上收听 ):

-   **预览**:每个组件,取自真实的食谱,在您选择的主题中,在您编辑时更新.
-   **颜色**: 编辑任意阴影; 从一色构建整个调色板; 添加或去除颜色.
-   **缩放**:间隔,弧度,字体大小,重量,行高,不透明,持续时间,z-index,断点.
-   **主题**: 添加(副本),重命名,更改模式/变体,删除;将每个角色都映射为带有取取色器的颜色.
-   编辑在工作副本中直播. **保存** 首先验证( 决定规则, XSD, 需要的角色), 然后写 您的 XML、 犬科索引和生成的文件. **还原** 丢弃工作副本.
-   预览需要已构建的软件包 (`dist/`);出版的软件包有.

编辑在XML的文本中制作(评论和布局保存),因此diff是小心的手编辑会给出的.

## XML 工具链

平地节点( QQ, 无依赖, 无 Python) : `npx flipova-design <command>`。 。 。 .

| 命令 | 它会做什么 |
| :-- | :-- |
| `init` | 注入应用级接线(Tailwind/PostCSS/CSS文件, `design:*` 脚本; 从未覆盖 |
| `adopt` | 将登记册复制到项目中,将产出重写到 `theme/`,写入 `theme/provider.tsx` |
| `gui [--port N] [--no-open]` | 视觉编辑器(如果项目没有采用,首先采用) |
| `gen [--check]` | 将登记册汇编成 `design-theme.ts`, (中文(简体) ), `config.ts`, (中文(简体) ), `tokens.js` |
| `check`, (中文(简体) ), `verify`, (中文(简体) ), `canonical`, (中文(简体) ), `lint` | 确定性规则、犬科索引、 XSD |
| `pipeline` | gen, 检查, 校验, 刷新 |
| `where` | 打印已解析的路径 |

`design/schema.xsd` 由一个内置验证器验证登记册使用的 XML Schema 子集; 使用其他任何东西的图案在装入时被拒绝,而不是半检查。 永远不要手剪 生成的文件;以及 `tailwind.config.js` 没有设计值: 它只有电线 `theme/tokens`。 。 。 .

```js
// tailwind.config.js (only needed for the gluestack / reusables providers, which use NativeWind classes)
const tokens = require('./theme/tokens');
module.exports = { presets: [require('nativewind/preset')], theme: { extend: tokens.theme } };
```

Flipova, paper and Tamagui 供应商读到 `theme/design-theme.ts` 直接; 胶层和可再使用 提供者在运行时从您传递到的同一主题构建他们的 CSS 变量 `<FlipovaProvider>`。 。 。 .

## 如何测试“相同”

对等在于解析的样式值,而不是像素. `npm test` 运行工具链测试(包括真实的) 通过,一个真正的 GUI 服务器驱动过 HTTP, 以及 XML 编辑, 边界检查和组件测试 : 重用类解回数字和颜色,并与配方进行比较; 交给的道具 纸张; Tamagui 配置; 每个主题的每一个配方( 没有未定义或 NaN 值); 57 flipova 通过反应-内在-网络(交互、无障碍属性、应用程序本身的主题)提供组件 已应用,其源代码中没有彩字; 四个库的6个共享组件 光和暗;每个图书馆都通过它的适配器获得土生土长。 未覆盖:在设备上渲染,内部纸张用自己的按钮和 切换(ripple,开关几何):能保证的就是传递给他们的.

## 前端的边界

基金会是堆栈的底部:原始人和设计. 布局、区域、认证屏幕、模型 而效果则活在前端套件中,基础则不取决于其他 `@flipova/*` 软件包. `npm run boundary` (运行于 `npm test` 和 CI 读取导入的并失效 : `@flipova/*` 导入; a 前端文件夹在下面 `components/`; 层上导入一个(`theme` < `contract` < `providers` < `ui`时 `ui` 只到达 flipova 提供者; 提供者导入另一个提供者; 可选导入的对等端 在自己的供应商之外; flipova 供应商进口除 `react` 财务报告和审定财务报表 `react-native`。 。 。 .

## 从 2.x 移动

-   `@flipova/foundation` 财务报告和审定财务报表 `/ui` 现在导出 **统一** (单位:千美元)`Button`, (中文(简体) ), `Card`(中文(简体) ). 胶囊 目录(`Box`, (中文(简体) ), `VStack`, (中文(简体) ), `Accordion`,)移动到 `@flipova/foundation/providers/gluestack/ui`。 。 。 .
-   `createGluestackUIProvider` 财务报告和审定财务报表 `GluestackUIProvider` 也存在; `<FlipovaProvider adapter={gluestack}>` 替换为新代码.
-   包裹不再载运 `spring` 主题; 用图形界面添加自己的主题.
-   `@flipova/foundation/tokens` 不变.

## 文档

-   [DOCS. md (英语)](https://npmcn.com/package/%40flipova/foundation/DOCS.md):维护者指南(设置,架构,测试,放出,符合).
-   [构成部分.md](https://npmcn.com/package/%40flipova/foundation/COMPONENTS.md):五个供应商生成的覆盖表.
-   公开文件: `documentation/v1.0/` (法文,取自 `flipova.assets` 与 `corral docs`)作为Docusaurus网站出版,来自 `website/` (单位:千美元)`corral docs docusaurus --repo foundation`) (中文(简体) ).
-   `npm run docs:check` 保持上述所有内容与代码一致(参见 [DOCS. md (英语)](https://npmcn.com/package/%40flipova/foundation/DOCS.md#11-public-documentation)) (中文(简体) ).

## 许可证

麻省理工学院 弗利波娃 参与受下列规定制约: [行为守则](https://npmcn.com/package/%40flipova/foundation/.github/CODE_OF_CONDUCT.md)。 。 。 .

## 常见问题

### @flipova/foundation 是什么？

Flipova设计系统的基础:一个供应商-不可知的UI合同\(57个组件\),五个供应商\(flipova,胶囊,可再用,纸张,tamagui\),以及一个注册驱动的具有本地图形用户界面的工具链\.

### 如何安装 @flipova/foundation？

在项目目录运行 npm install @flipova/foundation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-native（\>=0\.72\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 flipova-design，可以用 npx flipova-design 直接运行。

### @flipova/foundation 支持 TypeScript 吗？

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

### @flipova/foundation 支持 ESM 还是 CommonJS？

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

### @flipova/foundation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flipova/foundation 可以商用吗？

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

### @flipova/foundation 的下载量有多少？

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

### @flipova/foundation 还在维护吗？

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

