# @cdx-ui/native 中文文档

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

版本：0\.3\.12
npm 元数据更新时间：2026-11-04T15:33:45.855Z
中文译文更新时间：2026-11-09T15:44:32.175Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cdx-ui/native
原文对照：https://npmcn.com/package/%40cdx-ui/native/?lang=original
项目主页：https://github.com/dfh-candescent/forge-design-system#readme
源码仓库：https://github.com/dfh-candescent/forge-design-system

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

- 包体积（解压后）：96.7 kB，53 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：expo \>=52\.0\.0，react ^18\.2\.0 \|\| ^19\.0\.0，uniwind \>=1\.0\.0，metro-config \>=0\.80\.0，react-native \>=0\.76\.0
- 首次发布：2026-08-19T13:52:42.814Z
- 最新版本发布：2026-11-04T15:33:45.660Z
- 近 30 天下载量：2332（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 63 个）

## 中文简介

![coverage](https://unpkg.com/@cdx-ui/native/coverage.svg)

## 安装

```sh
npm install @cdx-ui/native
```

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

## README

# @cdx-ui/ 本地语

![coverage](https://unpkg.com/@cdx-ui/native/coverage.svg)

Forge UI的原生(Metro/ Expo)平台集成——嵌入了Forge的Expo配置插件 字体和Metro配置包。 保留 `@cdx-ui/styles` 财务报告和审定财务报表 `@cdx-ui/components` 平台中立,所以网络主机从不偶然地拉出博览会或字体二进制.

## 没有根导出 — 仅是子路径

这个包裹船 **没有 `.` 条目**。一个赤裸的 `import '@cdx-ui/native'` 解析失败 设计:每个子路径拥有自己的依赖生命周期,而根管将重新聚合 它们进入了这个软件包要删除的完全的阻塞点.

| 条目 | 出口 | 依赖寿命周期 |
| --- | --- | --- |
| `@cdx-ui/native` (配置插件) | Expo 配置插件, 通过 `app.plugin.js` | **构建时间** —— 说 `expo/config-plugins` (可选对等点),字体文件 |
| `@cdx-ui/native/metro` | `withForgeMetroConfig`, (中文(简体) ), `ForgeMetroConfigOptions` | **构建时间** —— 说 `metro-config`, (中文(简体) ), `uniwind/metro` (可选同伴) |
| `@cdx-ui/native/fonts` | `useForgeFonts` (折旧) | **运行时间** 无 |

构建时间依赖被宣布为可选的对等方, 永远不要根 `dependencies`所以没有 此软件包将构建工具拖入运行时间安装中.

存储器的架构文件记录了下面的全部决定 "平面融合包".

## 安装

```bash
npm install @cdx-ui/native
```

同伴依赖性 — 安装您使用的子路径 。 以下平台同行 可选; `react` 需要(`^18.2.0 || ^19.0.0`) (中文(简体) ).

| 端点 | 版本 | 要求为: | 可选 |
| --- | --- | --- | --- |
| `react` | `^18.2.0 || ^19.0.0` | `@cdx-ui/native/fonts` | 没有 |
| `expo` | `>=52.0.0` | 配置插件 | 对 |
| `react-native` | `>=0.76.0` | 配置插件的本地代码 | 对 |
| `metro-config` | `>=0.80.0` | `@cdx-ui/native/metro` | 对 |
| `uniwind` | `>=1.0.0` | `@cdx-ui/native/metro` | 对 |

## 字体 — 配置插件

将插件添加到您的 Expo 配置并重建本地应用程序( E)`npx expo prebuild`,或任何 `expo run:*` / EAS 建筑:

```json
{
  "expo": {
    "plugins": ["@cdx-ui/native"]
  }
}
```

它嵌入了每个字体家族, Forge 符号可以命名——每个可选择的显示家族,以及 Android单人家庭——每个家庭登记为 **一个家庭带着所有的脸**,这是 怎样 `font-medium`, (中文(简体) ), `font-semibold`, (中文(简体) ), `font-bold` 财务报告和审定财务报表 `italic` 选择真实的相貌 :

-   **iOS系统** ——面相文件被捆绑并列出于 `UIAppFonts`iOS通过家庭将他们分类 每个文件中的名称,所以 React Industrial 从 `fontFamily`, (中文(简体) ), `fontWeight` 财务报告和审定财务报表 `fontStyle`。 。 。 .
-   **机器人** – 每个家族成为用 React Indust 字体注册的 XML 字体家族 管理器, React Industrial 唯一将数值重和斜体重应用于自定义的路径 字体。 系统 `Roboto` 家庭登记方式相同 所以 `font-medium` 财务报告和审定财务报表 `font-semibold` 达到真正的系统加权数,而不是倒入正轨.

IOS上的身体和单个家族是系统字体,不需要嵌入. 字体为 cSS 变量层在 `@cdx-ui/styles`,包括a `ThemeOverride` 开关 运行时显示家族——插件没有FI配置意识.

插件需要开发构建; Expo Go 无法装入配置插件 。 它写着它的Android 自行登记 `MainApplication` 块,所以它与一个 `expo-font` 插件条目 为应用程序自己的字体配置 .

网络不受影响。 浏览器应用程序注册字体 `@cdx-ui/styles/fonts` 并且不应安装 这个包裹.

### 从 `useForgeFonts`

`useForgeFonts` 运行时已装入字体 `expo-font`,将每张相片登记为 分出家族——一种在Android上无法携带重量或斜体的形状. 它现在已贬值 总是报告 `{ loaded: true, error: null }`。添加插件,重建,并删除钩和任何 打开闸门 `loaded`。 。 。 .

## `@cdx-ui/native/metro`

`withForgeMetroConfig` 用Forge UI的造型层配置来包裹地铁配置. 它必须 成为 **最外侧** 如果你编了多个地铁配置包,请打包.

```js
const { getDefaultConfig } = require('expo/metro-config');
const { withForgeMetroConfig } = require('@cdx-ui/native/metro');

const config = getDefaultConfig(__dirname);

module.exports = withForgeMetroConfig(config, {
  cssEntryFile: './global.css',
  generatedTypesFile: './uniwind-types.d.ts',
});
```

| 选项 | 类型 | 目的 |
| --- | --- | --- |
| `cssEntryFile` | `string` | CSS 条目文件的路径( 例如 ). `'./global.css'`) (中文(简体) ). |
| `generatedTypesFile` | `string` | 生成 Tailwind 类定义的可选路径 . |

今天是Uniwind的代表。 如果造型层被换掉, 只有这个的内部 函数变化 — 消费 Metro 配置保持不变.

## 网络主机

通过 Metro 的 Expo web 捆绑, 所以一个 Expo-web 构建导入 `@cdx-ui/native/metro`这是一个 已接受的平台轴后果。 非 Expo 网络主机( Vite, Next.js) 不需要 子路径: 他们必须通过自己的网页字体路径加载字体( name`@font-face` 规则或网络字体 直接配置 Tailwind .

## 相关软件包

| 软件包 | 拥有 |
| --- | --- |
| `@cdx-ui/styles` | 设计代号、CSS文物、主题工具(平台中立) |
| `@cdx-ui/components` | 有样式的跨平台组件(平台中性) |

## 常见问题

### 如何安装 @cdx-ui/native？

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

### @cdx-ui/native 支持 TypeScript 吗？

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

### @cdx-ui/native 支持 ESM 还是 CommonJS？

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

### @cdx-ui/native 可以商用吗？

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

### @cdx-ui/native 的下载量有多少？

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

### @cdx-ui/native 还在维护吗？

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