# @newtone-dev/ui-react-web 中文文档

规范地址：https://npmcn.com/package/%40newtone-dev/ui-react-web/

版本：0\.42\.0
npm 元数据更新时间：2026-11-01T22:14:41.543Z
中文译文更新时间：2026-11-02T00:18:16.998Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40newtone-dev/ui-react-web
原文对照：https://npmcn.com/package/%40newtone-dev/ui-react-web/?lang=original
项目主页：https://github.com/joshuaallenmx/newtone_ui_react-web#readme
源码仓库：https://github.com/joshuaallenmx/newtone_ui_react-web

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

- 包体积（解压后）：1.5 MB，909 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18 \|\| ^19
- 首次发布：2026-09-20T14:23:41.005Z
- 最新版本发布：2026-11-01T22:14:41.356Z
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

用于web的React组件，构建在Newtone令牌层上。

## 安装

```sh
npm install @newtone-dev/ui-react-web
```

也可以使用：`pnpm add @newtone-dev/ui-react-web`、`yarn add @newtone-dev/ui-react-web`、`bun add @newtone-dev/ui-react-web`

## README

# newtone\_ui\_react-web

Newtone的web React组件库。

> 这个回购的权威描述是 `~/gallina/newtone/ui_react-web/_blueprint/index.md`和这里的分量 放电 `~/gallina/newtone/_blueprint/contracts/`． 如果本自述文件与其他文件不一致， 他们赢了。

## 这是什么？

**~26~ 34个组件和一个彩色端口** (讲述 `ls src/*/index.ts` 2026-09-25，当六个图表部分到达时 `0.6.0`;这二十六个人在他们面前已经变质了)。 `ls src/*/index.ts` 完整的公共API是什么 JavaScript可以达到； `package.json`的 `exports` Map是包含样式表的完整的Map。 **这张表是书脊，不是名单** -上面的蓝图包含所有组件。

|  |  |
| --- | --- |
| `Surface` | 拥有其内容读取的上下文： `theme`， `elevation`， `mode` |
| `Button` | 排放 `contracts/button.md`． 三个变体，五种状态， **三种尺寸的梯级** |
| `Text` | 排放 `contracts/typography.md`. `font`， `weight`， `case`， `figures`， `ligatures` |
| `Navbar` | 排放 `contracts/navbar.md`． 零件和旋钮；安排属于现场 |
| `Desktop` | 排放 `contracts/desktop.md`． 一个操作系统框架：窗口，启动器，面板，工作表（没有菜单栏或dock：主机有它们）；消费者保留布局 |
| `Identity` | 一个有作用域的种子集：为一个子树重新派生颜色 |
| `color.ts` | 的港口 `contracts/color-derivation.md` -运行时标识的一半 |

### 控制尺寸

**这里的每个控制都是5个高度中的一个——36、40、44、48、56——在两个类型对中的一个， 14/20或16/24。** 一、 `size` 道具选择一个横档，横档携带它的高度，它的类型对，它的 字形和它的填充在一起；没有第二条轴。 `contracts/button.md`， _大小_.

|  | `sm` | `md` | `lg` | `xl` |
| --- | --- | --- | --- | --- |
| `Control` | 36 | 40 | 44 | 48 |
| `Button`， `Navbar` | 40 | 44 | 48 | \- - - - - - |
| `Action`， `QuickAction` | 48 | \- - - - - - | 56 | \- - - - - - |

**一、 `Control` 位于a的下一级 `Button` 在前三个位置，和 `xl` 是例外。** 它的存在是为了控制站在一张照片上 `Gallery`的箭头, `VideoLightbox`离这儿很近 没有一个页面的主要动作可以与它们竞争。

## 举个例子

```tsx
import { Surface, Button } from '@newtone-dev/ui-react-web'
import '@newtone-dev/ui-tokens/newtone.css'
import '@newtone-dev/ui-react-web/button.css'

<Surface theme="emphasis">
  <Button>Primary</Button>
</Surface>
```

那个按钮变成了一个带有品牌标签的光填充，然后 **没有任何东西传递给它。**

**组件不携带facet。** 否 `theme`， `mode` 或者 `elevation` 把道具放在巴顿身上。它的 令牌指向角色，角色解析它所在的Surface。一个 `theme` Prop会将24路上下文产品放回到每个组件上，这正是 角色层的存在是为了防止什么。

## 作用域的身份

```tsx
<Identity seeds={{ system: { accent: { h: 35, c: 0.78 } } }}>
  {/* this subtree wears another brand over the site's own neutrals */}
</Identity>
```

`seeds` 形状像代币回购吗 `seed.json` -组，然后调色板，然后色调和 饱和。 **种子不是颜色，也没有亮度**，因为轻盈是一种 颜色所做的工作的属性，直到角色要求时才知道该工作。 `c` 是在该明度和色调下，可达到的最丰富色彩的比率，从0到1， 所以 `c: 1` 是色域边界而不是错误，相同的数字意味着相同 请求黄色或蓝色。

只有核心颜色层是与身份相关的，因此每个层写入51个自定义属性 调色板命名，没有其他内容。以下所有内容都是参考，并自行遵循。 未命名的调色板从封闭范围继承，因此可以自由嵌套 继承是CSS自己的。

推导是计算出来的，而不是表出来的：51步均匀地间隔在CIE L\*中，用 色度取自Display P3天花板。 `src/color.ts` 还有代币回购 `compute/` 是一个合约的两个实现，必须产生相同的字节。

## 构建

`npm run build` - - - - - - `tsc` 来 `dist/`,然后 `copy-styles.mjs`，它会走路 `src` 复制所有29个 样式表跨逐字因为 `tsc` 不发出CSS。 `dist/` 是否忽略并建立在发布的基础上 由 `prepublishOnly`;没有捆绑者。

**这一节说 _没有构建_ 直到2026-09-21**从建筑开始，他就错了 登陆。 `tsconfig.json` 集合 `"module": "NodeNext"`这就是为什么这里的每一种相对进口都带有 显式扩展-解析的打包器 `from './button'` 而Node ESM则没有。

## 消费

**发布到npm `@newtone-dev/ui-react-web`.** 它声明 `react` 作为同行(`^18 || ^19`） ,也 **不** 取决于 `@newtone-dev/ui-tokens`：每个组件读取 `--newtone-*` 自定义 属性的名称，并提供它们是消费站点的工作。

```sh
npm install @newtone-dev/ui-react-web @newtone-dev/ui-tokens
```

```ts
import { Surface, Button } from '@newtone-dev/ui-react-web'
import '@newtone-dev/ui-react-web/button.css'
```

**每个组件一次导入一个样式表**，消费者可以导入的每个路径都是 输入 `exports` 地图。 `sideEffects` 的名字 `**/*.css` 所以一个捆绑商保管它们。

**这一节说 _没有任何东西被发布到npm_ 直到2026-09-21**，三周后 `publishConfig.access` 和 `prepublishOnly` 是补充道。

## 常见问题

### @newtone-dev/ui-react-web 是什么？

用于web的React组件，构建在Newtone令牌层上。

### 如何安装 @newtone-dev/ui-react-web？

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

### @newtone-dev/ui-react-web 支持 TypeScript 吗？

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

### @newtone-dev/ui-react-web 支持 ESM 还是 CommonJS？

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

### @newtone-dev/ui-react-web 可以商用吗？

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

### @newtone-dev/ui-react-web 还在维护吗？

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