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

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

## 快速开始

### 基本用法
```typescript
import { DeviceTypeSelector } from '@/client/admin/components/DeviceTypeSelector';

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

### 带图片的高级用法
```typescript
<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` | 是否在选项中显示设备类型图片 |

## 完整示例

### 在表单中使用
```typescript
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>
```

### 在表格筛选中使用
```typescript
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集成
```typescript
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验证集成
```typescript
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. 错误处理
```typescript
<DeviceTypeSelector
  value={selectedTypeId}
  onChange={(id) => {
    try {
      setSelectedTypeId(id);
    } catch (error) {
      console.error('选择设备类型失败:', error);
      toast.error('选择失败，请重试');
    }
  }}
/>
```

### 2. 性能优化
```typescript
// 使用防抖处理频繁的选择变化
import { debounce } from 'lodash-es';

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

<DeviceTypeSelector
  onChange={debouncedTypeChange}
/>
```

### 3. 无障碍访问
```typescript
<DeviceTypeSelector
  placeholder="选择设备类型（按回车键打开选项）"
  // 添加ARIA标签
  aria-label="设备类型选择器"
/>
```

## 常见问题

### Q: 选择器不显示图片怎么办？
A: 确保API路由配置了正确的relations参数：
```typescript
// 在 src/server/api/device-types/index.ts 中
relations: ['imageFile']  // 必须包含这个配置
```

### Q: 如何自定义选项的显示格式？
A: 可以修改选择器组件中的渲染逻辑，或者创建自定义的选择器变体。

### Q: 选择器加载失败如何处理？
A: 组件内置了错误处理，但可以在onChange回调中添加额外的错误处理逻辑。

## 相关组件

- [`UserSelector`](src/client/admin/components/UserSelector.tsx) - 用户选择器
- [`DeviceSelector`](src/client/admin/components/DeviceSelector.tsx) - 设备选择器  
- [`FileSelector`](src/client/admin/components/FileSelector.tsx) - 文件选择器

## 版本历史

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

## 技术支持

如果在使用过程中遇到问题，请检查：
1. API服务是否正常运行
2. 设备类型数据是否存在
3. 网络连接是否正常
4. 用户权限是否足够