Ark UI Vue 4.1.0 版本中 createListCollection 的正确使用方法

Ark UI 是一个现代化的 UI 组件库，最近发布的 4.1.0 版本为 Vue 用户带来了新的 createListCollection 功能。这个功能主要用于处理 Select 组件中的选项集合，但在实际使用过程中，开发者可能会遇到一些导入和使用上的问题。

正确导入方式

在 Ark UI Vue 中，createListCollection 并不是从主包导出的，而是需要从特定的组件模块中导入。这是 Ark UI 采用模块化设计的结果，有助于减小最终打包体积。

错误导入方式：

import { Field, Select, createListCollection } from '@ark-ui/vue'

正确导入方式：

import { Select, createListCollection } from '@ark-ui/vue/select'
import { Field } from '@ark-ui/vue/field'

这种模块化的导入方式可以让开发者只引入实际需要的功能，避免不必要的代码被打包进项目。

createListCollection 的正确使用

createListCollection 函数需要接收一个特定格式的参数对象，而不是直接传入数组。这是为了提供更灵活的配置选项，为未来可能的扩展预留空间。

错误使用方式：

const collection = createListCollection(myArray)

正确使用方式：

const collection = createListCollection({ items: myArray })

其中，myArray 应该是一个包含 label 和 value 属性的对象数组，例如：

const options = [
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' }
]

完整示例

下面是一个完整的 Select 组件使用示例：

<template>
  <Select.Root v-model="selectedValue" :collection="collection">
    <Select.Label>选择一个选项</Select.Label>
    <Select.Control>
      <Select.Trigger>打开选择器</Select.Trigger>
    </Select.Control>
    <Select.Positioner>
      <Select.Content>
        <Select.Item v-for="item in collection.items" :key="item.value" :item="item">
          <Select.ItemText>{{ item.label }}</Select.ItemText>
        </Select.Item>
      </Select.Content>
    </Select.Positioner>
  </Select.Root>
</template>

<script setup>
import { Select, createListCollection } from '@ark-ui/vue/select'

const options = [
  { label: '苹果', value: 'apple' },
  { label: '香蕉', value: 'banana' },
  { label: '橙子', value: 'orange' }
]

const collection = createListCollection({ items: options })
const selectedValue = ref()
</script>

常见问题解决

1. 导入错误：如果遇到"does not provide an export named 'createListCollection'"错误，请检查是否从正确的路径导入。

2. 参数格式错误：确保传递给 createListCollection 的是一个包含 items 属性的对象，而不是直接传递数组。

3. 选项格式：集合中的每个项目必须包含 label 和 value 属性，这是 Select 组件能够正常工作的前提。

Ark UI 的这种设计虽然初次使用可能需要适应，但它提供了更好的类型安全和更清晰的组件边界。通过遵循这些最佳实践，开发者可以充分利用 Ark UI Vue 的强大功能，构建出高效、可维护的用户界面。