reka-ui-skilld

Reka UI [email protected]

适用于 Vue 3 的无样式、易于访问的组件原语。要求 vue >= 3.4.0 （准备好的源文件 package.json:87-89）。文档：https://reka-ui.com

参考资料

• API 概览：入口点、每个组件部分和工具。
• 组合：asChild、属性转发、上下文注入、受控状态。
• 样式与动画：data-state、--reka- CSS 变量、通过 <Transition> 使用 force-mount。
• 新增与变更的组件：Drawer、Autocomplete、Color primitives、Month/Year pickers，以及特定版本的属性变更。
• 集成：命名空间入口、Nuxt 模块、组件解析器、使用 @internationalized/date 处理日期、虚拟化。

设置

pnpm add reka-ui   # or npm / yarn / bun

<script setup lang="ts">
import { DialogRoot, DialogTrigger, DialogPortal, DialogOverlay, DialogContent, DialogTitle } from 'reka-ui'
</script>

<template>
  <DialogRoot>
    <DialogTrigger>Edit profile</DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <DialogTitle>Edit profile</DialogTitle>
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

API 变更（2.10.x 和 2.9.x）

优先列出近期版本。基线技能覆盖至 2.9.7。

• 新增 Drawer 原语（2.10.0）：滑动关闭、吸附点、嵌套抽屉。组成部分：DrawerRoot/Trigger/Portal/Overlay/Content/Close/Title/Description/Handle/SwipeArea/Viewport/Indent/IndentBackground（已准备的源码 src/Drawer/）。发布说明：https://github.com/unovue/reka-ui/releases/tag/v2.10.0
• 新增 ConfigProvider 的 teleportTo 属性：全局默认传送目标（已准备的源码 src/ConfigProvider/ConfigProvider.vue:45）
• 新增 DialogRoot 的 unmountOnHide 属性，默认值为 true；设为 false 可在隐藏时保留已挂载的内容（已准备的源码 src/Dialog/DialogRoot.vue:20）
• 新增 SelectRoot 的 nullableValue 属性，用于为隐藏输入框设置表示空选项的值（已准备的源码 src/Select/SelectRoot.vue:18）
• 新增 HoverCardRoot 的 enableTouch 属性，默认值为 false（已准备的源码 src/HoverCard/HoverCardRoot.vue:15）
• 新增 DateFieldRoot 的 stepSnapping 属性，默认值为 false（已准备的源码 src/DateField/DateFieldRoot.vue:57）
• 新增 TreeItem 的 disabled 属性（2.10.0）：https://github.com/unovue/reka-ui/releases/tag/v2.10.0
• TabsIndicator 新增 --reka-tabs-indicator-size、--reka-tabs-indicator-thickness、--reka-tabs-indicator-position CSS 变量（已准备的源码 src/Tabs/TabsIndicator.vue:73-75）
• 改进 useEmitAsProps 和 useForwardPropsEmits 的类型推断（2.10.0）
• 新增 Autocomplete 组件（2.9.0），这是采用 Combobox 风格的输入组件，拥有自己的 Autocomplete* 部件系列。文档：https://reka-ui.com/docs/components/autocomplete
• 新增颜色原语（2.9.0）：ColorArea*、ColorField*、ColorSlider*、ColorSwatch、ColorSwatchPicker*，以及从根目录导出的颜色解析/转换工具
• 新增 TimeRangeField（2.9.0）：TimeRangeFieldRoot、TimeRangeFieldInput
• 新增月份和年份选择器（2.9.0）：MonthPicker*、YearPicker* 以及 MonthRangePicker*、YearRangePicker* 系列
• 新增 CheckboxRoot/SwitchRoot 自定义布尔值：trueValue 和 falseValue 属性取代固定的 true/false（已准备的源码 src/Checkbox/CheckboxRoot.vue:27-31）
• 新增 DropdownMenuFilter 部件，用于支持搜索的下拉菜单（2.9.0）
• 新增 Splitter 像素尺寸和约束（2.9.0）
• 新增通过 TooltipProvider 配置全局提示框内容的功能（2.9.0）
• 菜单内部实现从 reka-ui/internal 导出；该接口不稳定，可能在不遵循 semver 的情况下变更（已准备的源码 src/internal.ts:1-7）

修改较旧代码时仍需注意的早期破坏性变更：

• radix-vue 更名为 reka-ui；CSS 变量使用 --reka- 前缀，数据属性使用 data-reka-。迁移指南：https://reka-ui.com/docs/guides/migration
• Combobox 重构：移除了 filterFunction 属性；searchTerm 和 displayValue 从 Root 移至 ComboboxInput（见上述迁移指南）
• Checkbox、Toggle、MenuCheckboxItem 使用标准 v-model，不再使用 v-model:checked / v-model:pressed（见上述迁移指南）
• PaginationRoot 的 itemsPerPage 为必填项（见上述迁移指南）
• 自 2.8.0 起，Calendar/DatePicker 上的 weekStartsOn 与区域设置无关：https://github.com/unovue/reka-ui/releases/tag/v2.8.0

发布索引：https://github.com/unovue/reka-ui/releases

最佳实践

• 使用 asChild 进行组合：将 Reka 原语渲染为自己的元素或组件，同时保留其行为和无障碍性（https://reka-ui.com/docs/guides/composition）

<TooltipTrigger asChild>
  <MyButton>Hover me</MyButton>
</TooltipTrigger>

• 使用 useForwardPropsEmits 构建封装组件，让所有 props 和 emits 传递给原语（https://reka-ui.com/docs/utilities/use-forward-props-emits）

const props = defineProps<AccordionRootProps>()
const emits = defineEmits<AccordionRootEmits>()
const forwarded = useForwardPropsEmits(props, emits)
// <AccordionRoot v-bind="forwarded">

• 使用 ConfigProvider 包裹应用，以设置 dir（RTL）、locale、scrollBody 和默认的 teleportTo（https://reka-ui.com/docs/utilities/config-provider）

<ConfigProvider dir="rtl" :scroll-body="false">
  <App />
</ConfigProvider>

• 在片段（多根节点）组件中使用 useForwardExpose，使模板 refs 返回目标 DOM 元素（https://reka-ui.com/docs/utilities/use-forward-expose）

const { forwardRef } = useForwardExpose()
// <div :ref="forwardRef">...</div>

• 通过 data-state 属性设置状态样式，而不是切换类名；在作用域样式中，使用 :deep() 设置传送内容的样式（https://reka-ui.com/docs/guides/styling）

.AccordionItem[data-state="open"] { border-bottom-width: 2px; }

• 使用 <Transition> 添加动画：为内容部件添加 force-mount，并自行控制卸载（https://reka-ui.com/docs/guides/animation）

<Transition name="fade">
  <DialogContent force-mount>...</DialogContent>
</Transition>

• 使用 ComboboxVirtualizer、ListboxVirtualizer、AutocompleteVirtualizer 或 TreeVirtualizer 虚拟化长列表；为滚动容器设置固定高度（https://reka-ui.com/docs/guides/virtualization）

<ComboboxViewport class="max-h-80 overflow-y-auto">
  <ComboboxVirtualizer :options="items" :estimate-size="25" v-slot="{ option }">
    <ComboboxItem :value="option">{{ option.label }}</ComboboxItem>
  </ComboboxVirtualizer>
</ComboboxViewport>

• 使用 injectAccordionRootContext 等 injectXContext 函数，让自定义子组件访问原语的内部状态（https://reka-ui.com/docs/guides/inject-context）

• Reka UI 的 useId 按以下顺序解析 ID：传入的确定性 ID、ConfigProvider 的 useId 来源、Vue 原生 useId（Vue 3.5+），最后回退到计数器（已准备的源码 src/shared/useId.ts:26-34）。在 Vue 低于 3.5 的 Nuxt 项目中，通过 ConfigProvider 传入 Nuxt 的 useId，以避免 hydration ID 不匹配（https://reka-ui.com/docs/guides/server-side-rendering）

• 日期和时间组件接收来自 @internationalized/date（直接依赖）的 DateValue 和 TimeValue 对象，不能使用原始字符串（https://reka-ui.com/docs/guides/dates）

常见注意事项

• 每个部件都必须位于其 Root 下；大多数组件还需要将 *Content 放在 *Portal 或 Teleport 内，以确保正确的堆叠顺序。
• Presence 的 forceMount 无论打开状态如何都会渲染内容；请自行处理可见性，例如使用 :hidden（https://reka-ui.com/docs/utilities/presence）。
• 隐藏表单字段使用部件的 name 和 value props；SelectRoot 还接受 nullableValue 表示空状态。
• 从 reka-ui 导入以支持 tree-shaking，或从 reka-ui/namespaced 导入以使用 Dialog.Root 等分组部件；请参阅集成。