@gentleduck/primitives

中文文档
0.5.1发布于 2026/10/20MITTypeScriptES Module近 30 天下载 3321

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

中文使用文档
文档目录6 节
  1. 为什么原始人
  2. 构成部分
  3. 快速启动
  4. 特征
  5. 文档
  6. 许可证

@gentleduck/primitives

@ gentleduck/ 原始内容

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

麻省理工学院 - 说吧 更改日志 - 说吧 捐款 - 说吧 文档

npm downloads MIT


未被风格化,可访问性第一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模块和非模式对话框窗口
directionRTL/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移动各组的标签索引焦点管理
selectListbox 样式选择, 并按字头和滚动按钮
sheet滑出面板(再导出对话框内部)
slider带单指或多指拇指的区域滑动器
slot将道具和校正合并到儿童元素上(asChild 发动机)
toggle二态切换按钮
toggle-group单个或多选择的切换组
tooltip可访问的工具提示, 提供者级别延迟
visibility-hidden屏幕阅读器可视隐藏元素

快速启动

npm install @gentleduck/primitives
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 (英语)

许可证

麻省理工学院

版本与发布记录

@gentleduck/primitives 共发布 57 个版本,首次发布于 2025/09/02;过去 12 个月发布了 26 个版本。

版本发布日期距今
0.5.1latest2026/10/2026 天前
0.5.02026/10/131 个月前
0.4.02026/10/111 个月前
0.3.12026/06/254 个月前
0.3.02026/05/305 个月前
0.2.142026/05/205 个月前

关于 @gentleduck/primitives 的常见问题

@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 和提交记录判断。