---
name: frontend-conventions
description: 前端 UI 组件使用规范。用于本仓库前端页面开发时，统一下拉组件、只读字段展示方式，避免原生控件导致交互和样式不一致。
---

# 前端组件规范

## 下拉控件

- 必须使用 `CustomSelect`
- 禁止直接写原生 `<select>/<option>`
- `options.value` 统一用字符串；如需数字，在回调里转换

## 搜索控件

- 边缘侧或云端前端所有的搜索输入框，必须使用封装的 `SearchInput` 组件
- 禁止直接使用原生的 `<input type="search">` 或是手写带放大镜图标的输入框
- `SearchInput` 组件需统一具备清除按钮和 `onChange` 的直接值映射
- 已集成在 `src/components/common/` 目录下

## 组件复用优先级

- 页面开发前先检查现有组件：`frontend/config_app/src/components/common/`、`frontend/cloud_app/src/components/common/`
- 已有自定义组件必须优先复用，禁止在页面中重复实现同类 UI 逻辑
- 仅当现有组件无法满足需求时才允许新增组件，并优先沉淀到各自工程的 `src/components/common/`
- 新增或改造组件时，保持 API 向后兼容，避免一次改动引发多页面回归

示例：

```jsx
<CustomSelect
  value={value}
  onChange={setValue}
  options={[
    { value: "", label: "请选择..." },
    { value: "a", label: "选项 A" },
  ]}
/>
```

## 只读字段

- 禁止使用 `<input readOnly>` 伪装只读
- 使用 `<span>` 或 `<div>` + 只读样式类

## 设计目标

- 保持交互行为一致
- 保持视觉样式一致
- 降低页面间重复实现