Lzh on GitHub

迁移

本指南提供了开发者将其项目从 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 props - Combobox 已重构和改进以支持更好的自定义过滤。阅读更多。
<template>
-  <ComboboxRoot :filter-function="customFilter" />
</template>
  • 将 Root 的 searchTerm props 替换为 Input 的 v-model
  • 将 displayValue props 从 Root 移动到 Input
<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 多边形以允许更好的样式。

表单组件

  • 将受控状态重命名为 v-model - 将 v-model:checked、v-model:pressed 替换为表单组件更熟悉的 API。
<template>
-  <CheckboxRoot v-model:checked="value" />
+  <CheckboxRoot v-model="value" />
</template>
  • 重新定位 VisuallyHidden - 以前，VisuallyHidden 定位在根节点，导致样式作用域无法应用。

菜单复选框项

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

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

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

分页

  • 必需的 itemsPerPage prop - 现在要求提供 itemsPerPage prop，而不是默认值，以便更明确地提示页面大小。
<template>
+  <PaginationRoot :items-per-page="10" />
</template>

日历

  • 移除已废弃的 step prop - 使用 prevPage/nextPage props 进行更精细的控制。
<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>

选择

  • SelectValue 不再渲染传送元素 - SelectValue 以前的实现将通过传送片段渲染选定的 SelectItem。这会导致 SSR 闪烁，并且是不必要的计算。
<template>
  <SelectValue>
+  <!-- render the content similar to `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',
+    'reka-ui/nuxt' 
  ],
})