# @dotnaos/ui-base 中文文档

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

版本：0\.0\.28
npm 元数据更新时间：2026-09-16T13:36:07.694Z
中文译文更新时间：2026-11-12T21:57:31.603Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.6 MB，419 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-08-16T12:04:20.726Z
- 最新版本发布：2026-09-16T13:36:07.597Z
- 近 30 天下载量：4325（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

DotNaos 的通用网络 UI 基础和控制 .

## 安装

```sh
npm install @dotnaos/ui-base
```

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

## README

# @dotnaos/ ui- base (英语)

DotNaos 界面的通用网络基础, 建在共享的上方 `@dotnaos/design` 软件包.

## 安装

```bash
bun add @dotnaos/ui @dotnaos/ui-base
```

Web app 在渲染前应该导入完整的公共 UI 样式表 组件 :

```ts
import "@dotnaos/ui/styles.css";
```

## 导入

```ts
import { Button, Card, ThemeProvider } from "@dotnaos/ui-base";
```

该套件揭露出一个网络组件家族. 布局结构和原生部分生活在 自有软件包, Base 将保持小和域中立 :

```ts
import { Button, Card } from "@dotnaos/ui-base";
import { ContentPageLayout } from "@dotnaos/ui-layout";
import { NativeContainer } from "@dotnaos/ui-native";
```

严格的组件身份和有限槽合同被构建在正常组件中. 有一个 没有单独的严格模式组件树或公共 `strict` 进入点.

按钮意图和形状表示为一个组件的变体:

```tsx
<Button variant="primary" label="Save" icon="save" onPress={save} />
<Button variant="secondary" label="Cancel" onPress={cancel} />
<Button variant="ghost" label="More" iconAfter="chevronDown" onPress={open} />
<Button variant="icon" accessibilityLabel="Delete item" icon="trash" onPress={remove} />
```

公共按钮 API 只接受结构化数据. 图标必须使用 DotNaos 图标目录中的名称 .

## 自动完成

`Autocomplete` 是一个带有浮动、模糊和相配建议的控制文本输入 :

```tsx
import { Autocomplete } from "@dotnaos/ui-base";

<Autocomplete
  accessibilityLabel="Project"
  value={query}
  onValueChange={setQuery}
  options={[
    { value: "Design System", label: "Design System" },
    { value: "DevOps Client", label: "DevOps Client" },
  ]}
/>
```

设定 `keepOpenOnSelect` 用于连续完成,例如浏览相继路径段. 选择后出现新的建议, 无需按键; 逃脱和模糊仍然关闭 . 在聚焦的同时,浮面板在过滤和取取过程中会保持挂载. 装入保留 前一个结果可见但不活跃,输入中有一个小中性旋转器; 第一个 请使用安静的占位符 。 空结果显示 `No suggestions`。两个状态都无法选择. 匹配的字符在周围的文本颜色中使用了微妙的中分量,而不用下划线.

可选 `backAction` 在列表上方添加单独的导航按钮. 从来都不是 自动结果或部分箭头键包:从第一个结果开始的新 Up 按键 聚焦, Enter 激活, Down 返回到第一个结果 。 停止按压 在第一个结果。 逃出会关闭弹出并返回焦点到输入. 启用 `horizontalNavigation` 以权利接受积极结果并援引 `backAction` 在弹出打开时左转。 修改键、文本选择和组成保留 文本编辑行为; 持有水平箭头不会跳过多关.

第一个启用的结果是自动选择的 。 箭头键导航, 输入接受, 逃逸则免职。 标签通常离开输入;选择重复的 Tab 补全 `completeOnTab` (Shift+Tab 总是离开). 接受结果时 `value` 输入 和电话 `onSelect` 如果提供。 标签中的匹配字符会被突出显示.

在主机中装入远程或文件系统选项, 通过 `loading` 和弃置的状态 答复。 使用 `query` 当只匹配部分输入时, 如最后一个 路径段。 组件本身没有进行网络或文件系统访问.

## QR 代码

`QrCode` 使一个自成一体的SVG不接触外部的QR服务。 它保持了所需的四单元静区和固定的黑白对比来进行可靠的扫描.

```tsx
import { QrCode } from "@dotnaos/ui-base";

<QrCode
  accessibilityLabel="Open Devbox Mobile"
  value="https://devbox.os-pc.vpn.os-home.net/mobile"
  size={184}
/>
```

使用 `errorCorrectionLevel="H"` 当代码需要额外的破坏耐受性.

## 几何能力

四舍五入的几何通过小能力接口表达,而不是重复的特定组件 道具来. `RadiusProps` 提供 `radius="theme" | "full"`· ; `AspectProps` 提供 `aspect="auto" | "square"`; 和 : `GeometryProps` 两者兼有 默认是 `theme` 财务报告和审定财务报表 `auto`。 。 。 .

`theme` 遵循活动主题的角化处理. `full` 总是使用全圆角 独立于全局的 Squircle 或 超椭圆设置。 宽比决定了 silhouette :

```tsx
<Button variant="primary" label="Continue" radius="full" />
<Surface radius="full">Pill surface</Surface>
<Surface radius="full" aspect="square">Circular surface</Surface>
```

`Container`, (中文(简体) ), `Surface`, (中文(简体) ), `Box`,以及 `Card` 暴露两种能力。 文本按钮, `Input`, (中文(简体) ), `Textarea`, (中文(简体) ), 编辑 `Select` 仅显示触发 `radius`使用同一合同的固定轮廓部件 内部:图标按钮是 `full + square`,而芯片、滑动部件和分页药片是 `full + auto`。 。 。 . 内容和布局仅限原始出品不暴露出几何道具.

## CDN 用户

通过 npm 兼容的 CDN 使用公共 npm 软件包 :

```ts
import { Button } from "https://esm.sh/@dotnaos/ui-base@VERSION";
import { Button } from "https://cdn.jsdelivr.net/npm/@dotnaos/ui-base@VERSION/+esm";
import { Button } from "https://unpkg.com/@dotnaos/ui-base@VERSION/dist/index.js";
```

Unpkg入站点直接服务于已建成的无害环境管理文件。 因为 `react`, (中文(简体) ), `react-dom`,以及 `react/jsx-runtime` 保持对等/运行时间的导入、esm.sh和jsDelivr `+esm` 提供最平滑的浏览器 CDN 体验 .

## 构建

```bash
bun --filter @dotnaos/ui-base build
```

## 许可证发放

此套件以麻省理工学院许可发布并包含 `LICENSE` 财务报告和审定财务报表 `THIRD_PARTY_NOTICES.md` 在npm的柏油球.

软件包直接拥有其组件执行,不包或选择其他组件库.

## 常见问题

### @dotnaos/ui-base 是什么？

DotNaos 的通用网络 UI 基础和控制 \.

### 如何安装 @dotnaos/ui-base？

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

### @dotnaos/ui-base 支持 TypeScript 吗？

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

### @dotnaos/ui-base 支持 ESM 还是 CommonJS？

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

### @dotnaos/ui-base 可以商用吗？

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

### @dotnaos/ui-base 的下载量有多少？

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

### @dotnaos/ui-base 还在维护吗？

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