# @gentleduck/primitives 中文文档

规范地址：https://npmcn.com/package/%40gentleduck/primitives/

版本：0\.5\.1
npm 元数据更新时间：2026-10-20T08:56:15.544Z
中文译文更新时间：2026-11-16T04:08:04.903Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gentleduck/primitives
原文对照：https://npmcn.com/package/%40gentleduck/primitives/?lang=original
项目主页：https://gentleduck.org/duck-ui
源码仓库：https://github.com/gentleeduck/gentleduck

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

- 包体积（解压后）：499 kB，654 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：4 个
- peer 依赖：react \>=18\.0\.0，tabbable 6\.2\.0，react-dom \>=18\.0\.0
- 首次发布：2025-09-02T11:43:05.086Z
- 最新版本发布：2026-10-20T08:56:14.690Z
- 近 30 天下载量：3321（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 26 个）

## 中文简介

未被风格化,可访问性第一UI原始作"回放".

## 安装

```sh
npm install @gentleduck/primitives
```

也可以使用：`pnpm add @gentleduck/primitives`、`yarn add @gentleduck/primitives`、`bun add @gentleduck/primitives`

## README

![@gentleduck/primitives](https://npmcn.com/package/public/logo-dark.svg)

# @ gentleduck/ 原始内容

未被风格化,可访问性第一UI原始作"回放".

[麻省理工学院](https://npmcn.com/package/LICENSE) - 说吧 [更改日志](https://npmcn.com/package/CHANGELOG.md) - 说吧 [捐款](https://npmcn.com/package/CONTRIBUTING.md) - 说吧 [文档](https://gentleduck.org/duck-ui)

[![npm](https://img.shields.io/npm/v/@gentleduck/primitives.svg)](https://www.npmjs.com/package/@gentleduck/primitives) [![downloads](https://img.shields.io/npm/dm/@gentleduck/primitives.svg)](https://www.npmjs.com/package/@gentleduck/primitives) [![MIT](https://img.shields.io/npm/l/@gentleduck/primitives.svg)](https://npmcn.com/package/LICENSE)

* * *

未被风格化,可访问性第一UI原始作"回放".

## 为什么原始人

-   **比拉迪克斯小50-92%** - 提醒对话框: 1.6 KB vs 18.6 KB. 波波弗: 2.4 KB vs 19.6 KB. Dialog: 3.1 KB vs 10.6 KB. 共享内装(槽,存在,波波,焦点范围)一次而不再被每包复制.
-   **完全键盘导航 + ARIA 合规出框** - 每一个有正确角色,状态,键盘相互作用的组件船,所以你不必自己给它们接线.
-   **化合物组件模式** - 写作 `Root`, (中文(简体) ), `Trigger`, (中文(简体) ), `Content`朋友们来建造你需要的UI.
-   **与 Radix API 兼容** - 同一个名字,同一个 `asChild` 模式,不变 `data-state` 属性。 从 Radix 迁移是您进口的命名空间变化 .

## 构成部分

| 初级 | 说明 |
| --- | --- |
| `alert-dialog` | 需要用户识别的模块对话框 |
| `arrow` | 为浮动元素定位箭头 |
| `avatar` | 有图像和倒置支持的用户外观 |
| `calendar` | 有键盘导航和多视图支持的日期网格 |
| `checkers` | 复选框和切换到原始 |
| `command` | 带有搜索过滤器的命令调色板 |
| `context-menu` | 右键单击带有子菜单的上下文菜单 |
| `dialog` | 模块和非模式对话框窗口 |
| `direction` | RTL/LTR 方向提供者 |
| `dismissable-layer` | 在外部互动上忽略的层 |
| `dropdown-menu` | 带有子菜单、复选框和收音机项目的下放菜单 |
| `focus-scope` | 在边界内陷阱并管理焦点 |
| `hover-card` | 由悬空/ 关闭延迟触发的牌 |
| `input-otp` | 有插槽和分隔器的一次性密码输入 |
| `menu` | 下拉、上下文和菜单栏所用的原始基本菜单 |
| `menubar` | 带键盘导航的横向菜单栏 |
| `mount` | 推迟装入周期回调 |
| `navigation-menu` | 有动画指示器和取景口的站点导航 |
| `pagination` | 页面导航控制 |
| `popover` | 浮动内容锁定触发器 |
| `popper` | 通过浮动 UI 定位低等浮式元素 |
| `portal` | 将儿童送入DOM门户网站 |
| `presence` | 动态挂载/卸载过渡 |
| `primitive-elements` | 基础 `Primitive` 部件厂(`asChild` 支助) |
| `progress` | 确定和不确定进度指标 |
| `radio-group` | 具有巡回焦点的无线电按钮组 |
| `roving-focus` | 移动各组的标签索引焦点管理 |
| `select` | Listbox 样式选择, 并按字头和滚动按钮 |
| `sheet` | 滑出面板(再导出对话框内部) |
| `slider` | 带单指或多指拇指的区域滑动器 |
| `slot` | 将道具和校正合并到儿童元素上(`asChild` 发动机) |
| `toggle` | 二态切换按钮 |
| `toggle-group` | 单个或多选择的切换组 |
| `tooltip` | 可访问的工具提示, 提供者级别延迟 |
| `visibility-hidden` | 屏幕阅读器可视隐藏元素 |

## 快速启动

```bash
npm install @gentleduck/primitives
```

```tsx
import * as Dialog from '@gentleduck/primitives/dialog'

function Demo() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Title>Heading</Dialog.Title>
          <Dialog.Description>Body text here.</Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}
```

## 特征

-   **`asChild` / 间隙** - 使任何原始元素成为你自己的元素 `asChild` 道具,电源 `Slot` 函数.
-   **`createContextScope`** - 防止交叉内幕泄漏的反相上下文工厂.
-   **`forwardRef` 到处都是** - 每一个组成部分都向后推移,以证明必须进入和组成.
-   **`data-slot` 属性** - 每个元件根都发出a `data-slot` 用于没有类名的样式目标.
-   **存在动画** - 那个 `Presence` 原始的允许您在卸载前进行动画的出/入过渡 .
-   **焦点陷阱** - 说吧 `FocusScope` 锁在模式、对话框和可配置循环行为的弹出器内.
-   **解除层** - 说吧 `DismissableLayer` 手柄外部点击、 逃逸键和嵌入层堆放.

## 文档

[温和duck.org/docs/packages/duck-primitives (英语)](https://gentleduck.org/docs/packages/duck-primitives)

## 许可证

[麻省理工学院](https://npmcn.com/package/%40gentleduck/primitives/LICENSE)

## 常见问题

### @gentleduck/primitives 是什么？

未被风格化,可访问性第一UI原始作"回放"\.

### 如何安装 @gentleduck/primitives？

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

### @gentleduck/primitives 支持 TypeScript 吗？

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

### @gentleduck/primitives 支持 ESM 还是 CommonJS？

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

### @gentleduck/primitives 需要什么版本的 Node\.js？

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

### @gentleduck/primitives 可以商用吗？

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

### @gentleduck/primitives 的下载量有多少？

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

### @gentleduck/primitives 还在维护吗？

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

