简介

¥Introduction

用于构建高质量、可访问的设计系统和 Web 应用的开源 UI 组件库。

Radix Primitives 是一个底层 UI 组件库，专注于可访问性、可定制性和开发者体验。你可以将这些组件用作设计系统的基础层，也可以逐步采用它们。

¥Radix Primitives is a low-level UI component library with a focus on accessibility, customization and developer experience. You can use these components either as the base layer of your design system, or adopt them incrementally.

视觉

¥Vision

我们大多数人对常见的 UI 模式（例如手风琴折叠面板、复选框、组合框、对话框、下拉菜单、选择、滑块和工具提示）有着类似的定义。这些 UI 模式符合 由 WAI-ARIA 记录 标准，并且已被社区广泛接受。

¥Most of us share similar definitions for common UI patterns like accordion, checkbox, combobox, dialog, dropdown, select, slider, and tooltip. These UI patterns are documented by WAI-ARIA and generally understood by the community.

然而，Web 平台提供给我们的实现并不完善。它们要么不存在，要么功能不足，要么无法充分定制。

¥However, the implementations provided to us by the web platform are inadequate. They're either non-existent, lacking in functionality, or cannot be customized sufficiently.

因此，开发者被迫构建自定义组件；一项极其艰巨的任务。因此，网络上的大多数组件都无法访问、性能低下，并且缺少重要功能。

¥So, developers are forced to build custom components; an incredibly difficult task. As a result, most components on the web are inaccessible, non-performant, and lacking important features.

我们的目标是创建一个资金充足的开源组件库，社区可以使用它来构建可访问的设计系统。

¥Our goal is to create a well-funded, open-source component library that the community can use to build accessible design systems.

主要功能

¥Key Features

可访问

¥Accessible

组件尽可能遵循 WAI-ARIA 设计模式 标准。我们处理了许多与可访问性相关的复杂实现细节，包括 aria 和角色属性、焦点管理和键盘导航。在我们的 accessibility 概述中了解更多信息。

¥Components adhere to the WAI-ARIA design patterns where possible. We handle many of the difficult implementation details related to accessibility, including aria and role attributes, focus management, and keyboard navigation. Learn more in our accessibility overview.

无样式

¥Unstyled

组件本身不带样式，让你可以完全控制外观和感觉。组件可以使用任何样式方案进行样式设置。在我们的 styling 指南中了解更多信息。

¥Components ship without styles, giving you complete control over the look and feel. Components can be styled with any styling solution. Learn more in our styling guide.

已打开

¥Opened

Radix Primitives 旨在根据你的需求进行定制。我们的开放组件架构为你提供了对每个组件部分的精细访问，因此你可以封装它们并添加自己的事件监听器、props 或 refs。

¥Radix Primitives are designed to be customized to suit your needs. Our open component architecture provides you granular access to each component part, so you can wrap them and add your own event listeners, props, or refs.

不受控制

¥Uncontrolled

在适用的情况下，组件默认不受控制，但也可以进行控制。所有行为连接均在内部处理，因此你可以尽可能顺畅地启动和运行，而无需创建任何本地状态。

¥Where applicable, components are uncontrolled by default but can also be controlled, alternatively. All of the behavior wiring is handled internally, so you can get up and running as smoothly as possible, without needing to create any local states.

开发者体验

¥Developer experience

我们的主要目标之一是提供最佳的开发者体验。Radix Primitives 提供全类型 API。所有组件共享类似的 API，从而提供一致且可预测的体验。我们还实现了 asChild prop，让用户完全控制渲染元素。

¥One of our main goals is to provide the best possible developer experience. Radix Primitives provides a fully-typed API. All components share a similar API, creating a consistent and predictable experience. We've also implemented an asChild prop, giving users full control over the rendered element.

增量采用

¥Incremental adoption

我们建议安装 radix-ui 包并导入你需要的基础组件。这是最简单的入门方法，可以避免版本冲突或重复，并易于管理更新。该软件包可进行 tree-shake，因此你应该只发布你使用的组件。

¥We recommend installing the radix-ui package and importing the primitives you need. This is the simplest way to get started, prevent version conflicts or duplication, and makes it easy to manage updates. The package is tree-shakeable, so you should only ship the components you use.

npm install radix-ui

import { Dialog, DropdownMenu, Tooltip } from "radix-ui";

或者，每个图元都可以单独安装：

¥Alternatively, each primitive can be installed individually:

npm install @radix-ui/react-dialog
npm install @radix-ui/react-dropdown-menu
npm install @radix-ui/react-tooltip

import * as Dialog from "@radix-ui/react-dialog";
import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
import * as Tooltip from "@radix-ui/react-tooltip";

单独安装时，我们建议同时更新所有 Radix 软件包，以防止共享依赖重复并减小软件包大小。

¥When installing separately, we recommend updating all Radix packages together to prevent duplication of shared dependencies and keep your bundle size down.

社区

¥Community

要加入 Radix 社区、提出问题并分享技巧，加入我们的 Discord。

¥To get involved with the Radix community, ask questions and share tips, Join our Discord.

要接收有关新基元、公告、博客文章和 Radix 常用技巧的更新，请关注 Bluesky 或 Twitter。

¥To receive updates on new primitives, announcements, blog posts, and general Radix tips, follow along on Bluesky or Twitter.

要提交问题、请求功能和做出贡献，请查看我们的 GitHub。

¥To file issues, request features, and contribute, check out our GitHub.

• GitHub 代码库

  ¥GitHub repo

• 行为准则

  ¥Code of conduct