迁移指南 - 从 Radix Vue 到 Reka UI ​

安装 ​

首先，您需要安装最新版本的 reka-ui。

$ npm add reka-ui

恭喜！🎉 完成上述包安装后，让我们开始迁移！前两个步骤相对简单，只需按以下变更进行全局搜索和替换即可。

导入语句变更 ​

导入的主要变动是将 radix-vue 替换为 reka-ui。

<script setup lang="ts">
import { TooltipPortal, TooltipRoot, TooltipTrigger } from 'radix-vue'
import { TooltipPortal, TooltipRoot, TooltipTrigger } from 'reka-ui'
</script>

命名规范变更 ​

CSS 变量及数据属性名称已更新，使用 reka 前缀替代 radix。

  --radix-accordion-content-width: 300px; 
  --reka-accordion-content-width: 300px; 

  [data-radix-collection-item] {} 
  [data-reka-collection-item] {} 

组件重大变更 ​

组合框 (Combobox) ​

• 移除 filter-function 属性 - Combobox 已重构优化，支持更好的自定义筛选功能。了解更多。

  vue

  <template>
    <ComboboxRoot :filter-function="customFilter" />  
  </template>

• 将 Root 的 searchTerm 属性替换为 Input 的 v-model

• 将 displayValue 属性从 Root 移至 Input

  vue

  <template>
    <ComboboxRoot v-model:search-term="search" :display-value="(v) => v.name" /> 
    <ComboboxRoot>
      <ComboboxInput v-model="search" :display-value="(v) => v.name" /> 
    </ComboboxRoot>
  </template>

箭头 (Arrow) ​

• 优化箭头多边形 - 修改 SVG 多边形以实现更佳的样式控制。

表单组件 (Form) ​

• 重命名受控状态为 v-model - 为表单组件使用更熟悉的 API，替换 v-model:checked、v-model:pressed。

<template>
  <CheckboxRoot v-model:checked="value" /> 
  <CheckboxRoot v-model="value" /> 
</template>

• 重新定位 VisuallyHidden - 此前 VisuallyHidden 位于根节点，导致作用域样式无法应用。

菜单复选框项 (Menu CheckboxItem) ​

• 与表单组件的变更类似，CheckboxItem 的绑定 API 已从 v-model:checked 改为 v-model。

<template>
  <DropdownMenuCheckboxItem v-model:checked="value" /> 
  <DropdownMenuCheckboxItem v-model="value" /> 

  <DropdownMenuCheckboxItem checked /> 
  <DropdownMenuCheckboxItem :model-value="true" /> 
</template>

分页 (Pagination) ​

• 必需 itemsPerPage 属性 - 不再提供默认的 itemsPerPage 值，现需显式指定以明确提示页面大小。

  vue

  <template>
    <PaginationRoot :items-per-page="10" />  
  </template>

日历 (Calendar) ​

• 移除已弃用的 step 属性 - 使用 prevPage/nextPage 属性实现更精细的控制。

  vue

  <script setup lang="ts">
  function pagingFunc(date: DateValue, sign: -1 | 1) { 
    if (sign === -1) 
      return date.subtract({ years: 1 }) 
    return date.add({ years: 1 }) 
  } 
  </script>
  
  <template>
    <CalendarPrev step="year" /> 
    <CalendarPrev :prev-page="(date: DateValue) => pagingFunc(date, -1)" /> 
  
    <CalendarNext step="year" /> 
    <CalendarNext :next-page="(date: DateValue) => pagingFunc(date, 1)" /> 
  </template>

选择器 (Select) ​

• SelectValue 不再渲染传送元素 - 之前的 SelectValue 实现会通过传送片段渲染选中的 SelectItem，这会导致 SSR 闪烁且带来不必要的计算开销。

  vue

  <template>
    <SelectValue>
      <!-- 渲染内容类似于 `SelectItem` -->
    </SelectValue>
  </template>

存在状态 (Presence) ​

为更好地支持 SSR 内容，我们还修改了使用 forceMount 的组件逻辑（这些组件利用 Presence 功能）：

• Accordion
• Collapsible
• Tabs
• NavigationMenu

forceMount 现在会渲染组件，即使状态为未激活。您现在需要手动处理组件的可见性逻辑。

<template>
  <TabsRoot
    v-slot="{ modelValue }"
    default-value="tab1"
  >
    <TabsContent
      value="tab1"
      force-mount
      :hidden="modelValue !== 'tab1'"
    >
      …
    </TabsContent>
    <TabsContent
      value="tab2"
      force-mount
      :hidden="modelValue !== 'tab2'"
    >
      …
    </TabsContent>
  </TabsRoot>
</template>

对于 Nuxt 模块用户 ​

若您使用 Nuxt，需要更新模块导入。

// nuxt.config.ts
export default defineNuxtConfig({
 modules: [
   'radix-vue/nuxt' <!-- [!code --] -->
   'reka-ui/nuxt' <!-- [!code ++] -->
 ],
})