file-starter/.roo/commands/shadcn-使用设备类型选择器.md

---

description: "使用设备类型选择器指令"

描述

本指令指导如何在管理后台页面中使用设备类型选择器组件（DeviceTypeSelector），包括基本用法、高级配置和最佳实践。

快速开始

基本用法

import { DeviceTypeSelector } from '@/client/admin/components/DeviceTypeSelector';

// 在组件中使用
<DeviceTypeSelector
  value={selectedTypeId}
  onChange={(id) => setSelectedTypeId(id)}
  placeholder="选择设备类型"
/>

带图片的高级用法

<DeviceTypeSelector
  value={selectedTypeId}
  onChange={(id) => setSelectedTypeId(id)}
  includeImage={true}
  onlyEnabled={true}
  placeholder="选择启用的设备类型（带图片）"
/>

参数说明

参数	类型	默认值	描述
value	number	undefined	当前选中的设备类型ID
onChange	(value: number) => void	undefined	选择变化时的回调函数
placeholder	string	"选择设备类型"	选择框占位符文本
disabled	boolean	false	是否禁用选择器
onlyEnabled	boolean	true	是否只显示启用的设备类型
includeImage	boolean	false	是否在选项中显示设备类型图片

完整示例

在表单中使用

import { useForm } from 'react-hook-form';
import { Form, FormField, FormItem, FormLabel, FormControl } from '@/client/components/ui/form';
import { DeviceTypeSelector } from '@/client/admin/components/DeviceTypeSelector';

const form = useForm({
  defaultValues: {
    deviceTypeId: undefined as number | undefined
  }
});

<Form {...form}>
  <FormField
    control={form.control}
    name="deviceTypeId"
    render={({ field }) => (
      <FormItem>
        <FormLabel>设备类型</FormLabel>
        <FormControl>
          <DeviceTypeSelector
            value={field.value}
            onChange={field.onChange}
            placeholder="请选择设备类型"
            includeImage={true}
          />
        </FormControl>
      </FormItem>
    )}
  />
</Form>

在表格筛选中使用

import { useState } from 'react';
import { DeviceTypeSelector } from '@/client/admin/components/DeviceTypeSelector';

const [filters, setFilters] = useState({
  typeId: undefined as number | undefined,
  keyword: ''
});

const handleTypeChange = (typeId: number) => {
  setFilters(prev => ({ ...prev, typeId }));
  // 触发数据重新加载
  refetch();
};

<DeviceTypeSelector
  value={filters.typeId}
  onChange={handleTypeChange}
  placeholder="按设备类型筛选"
  onlyEnabled={true}
/>

状态管理集成

与React Query集成

import { useQuery } from '@tanstack/react-query';
import { deviceTypesClient } from '@/client/api';

// 如果需要获取选中的设备类型详情
const { data: selectedDeviceType } = useQuery({
  queryKey: ['deviceType', selectedTypeId],
  queryFn: async () => {
    if (!selectedTypeId) return null;
    const res = await deviceTypesClient[':id'].$get({
      param: { id: selectedTypeId.toString() }
    });
    if (res.status === 200) return await res.json();
    return null;
  },
  enabled: !!selectedTypeId
});

与Zod验证集成

import { z } from 'zod';

const formSchema = z.object({
  deviceTypeId: z.number({
    required_error: "请选择设备类型",
    invalid_type_error: "设备类型ID必须是数字"
  }).int().positive()
});

// 在表单提交时验证
const onSubmit = (data: z.infer<typeof formSchema>) => {
  // 处理表单提交
};

最佳实践

1. 错误处理

<DeviceTypeSelector
  value={selectedTypeId}
  onChange={(id) => {
    try {
      setSelectedTypeId(id);
    } catch (error) {
      console.error('选择设备类型失败:', error);
      toast.error('选择失败，请重试');
    }
  }}
/>

2. 性能优化

// 使用防抖处理频繁的选择变化
import { debounce } from 'lodash-es';

const debouncedTypeChange = debounce((id: number) => {
  setSelectedTypeId(id);
}, 300);

<DeviceTypeSelector
  onChange={debouncedTypeChange}
/>

3. 无障碍访问

<DeviceTypeSelector
  placeholder="选择设备类型（按回车键打开选项）"
  // 添加ARIA标签
  aria-label="设备类型选择器"
/>

常见问题

Q: 选择器不显示图片怎么办？

A: 确保API路由配置了正确的relations参数：

// 在 src/server/api/device-types/index.ts 中
relations: ['imageFile']  // 必须包含这个配置

Q: 如何自定义选项的显示格式？

A: 可以修改选择器组件中的渲染逻辑，或者创建自定义的选择器变体。

Q: 选择器加载失败如何处理？

A: 组件内置了错误处理，但可以在onChange回调中添加额外的错误处理逻辑。

相关组件

• UserSelector - 用户选择器
• DeviceSelector - 设备选择器
  
• FileSelector - 文件选择器

版本历史

• v1.0.0 (2024-01-15): 初始版本，支持基本设备类型选择
• v1.1.0 (2024-01-20): 添加图片显示支持
• v1.2.0 (2024-01-25): 增加启用状态过滤选项

技术支持

如果在使用过程中遇到问题，请检查：

1. API服务是否正常运行
2. 设备类型数据是否存在
3. 网络连接是否正常
4. 用户权限是否足够