# PopMenus - 弹出菜单

## 说明

近手弹出的单选菜单，通过 ref 调用 `showFrom(triggerRef)` 从触发元素附近弹出。每个菜单项支持标题、副标题、左侧图标和选中态（勾选图标 + 高亮色）。作为单选组件，`data` 中最多只应有一个 `selected: true`（开发环境下多选会 `console.warn`）。点击任一项触发 `onSelect` 并自动关闭。

通过 `forwardRef` 暴露 `PopMenusRef`，需配合触发元素的 ref 使用（如 `Drawer` 的 `rightIconRef`）。

## 属性

| 属性 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|--------|------|
| **data** | 菜单项列表 | `PopMenusItem[]` | - | 是 |
| **colorType** | 选中态色系 | `ColorType` | `'green'` | 否 |
| **onSelect** | 选择回调 | `(item: PopMenusItem) => void` | - | 否 |
| **onShow** | 菜单弹出回调 | `() => void` | - | 否 |
| **onDismiss** | 菜单关闭回调 | `() => void` | - | 否 |
| **accessible** | 无障碍：是否启用 | `boolean` | `true` | 否 |

### PopMenusItem

| 字段 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|--------|------|
| **id** | 唯一标识 | `string \| number` | - | 是 |
| **title** | 标题文字（最多 2 行） | `string` | - | 是 |
| **subtitle** | 副标题文字（最多 2 行） | `string` | - | 否 |
| **leadingIcon** | 左侧图标，支持 SVG 组件或 Image | `React.ReactNode` | - | 否 |
| **disabled** | 是否禁用 | `boolean` | `false` | 否 |
| **selected** | 是否显示选中态（勾选图标 + 高亮色） | `boolean` | `false` | 否 |

### PopMenusRef

| 方法 | 说明 | 类型 |
|------|------|------|
| **showFrom** | 从触发元素附近弹出菜单 | `(triggerRef: any) => void` |

> `ColorType` 可选值：`'blue' \| 'green' \| 'wathet' \| 'purple' \| 'orange'`。

## 使用示例

```tsx
import { PopMenus } from 'miot/ui/hyperOSUI';
import type { PopMenusRef } from 'miot/ui/hyperOSUI';
import { useRef, useState } from 'react';

const popRef = useRef<PopMenusRef>(null);
const triggerRef = useRef(null);
const [selectedId, setSelectedId] = useState('cn');

<>
  <View ref={triggerRef} collapsable={false}>
    <IconButton onPress={() => popRef.current?.showFrom(triggerRef.current)} />
  </View>

  <PopMenus
    ref={popRef}
    colorType="blue"
    data={[
      { id: 'cn', title: '简体中文', subtitle: 'Chinese', selected: selectedId === 'cn' },
      { id: 'en', title: 'English', selected: selectedId === 'en' },
      { id: 'jp', title: '日本語', disabled: true },
    ]}
    onSelect={(item) => setSelectedId(String(item.id))}
  />
</>
```

## 注意事项

- 触发元素所在的 View 需设置 `collapsable={false}`，否则无法正确测量弹出锚点位置。
- 单选组件，`data` 中最多一个 `selected: true`；超过一个时开发环境会打印告警。
- 选中态下，SVG 图标会被覆盖为 `colorType` 对应颜色；未选中时保留图标自身颜色。
- 点击任意菜单项后菜单都会自动关闭。

## 修改记录

| 日期 | 版本 | 修改内容 | 修改原因 | 关联 |
|------|------|----------|----------|------|
| 2026-09-16 | v1.19.0 | 优化弹出菜单样式 | — | 5c32b71c |
| 2026-09-14 | v1.19.0 | 对齐排版与几何尺寸 | — | ba3cb569 |
| 2026-09-14 | v1.19.0 | 同步组件视觉 Token | — | 5a99f324 |
| 2026-08-20 | v1.19.0 | 调整组件参数 | — | bc81b51f |
| 2026-07-20 | v1.18.17 | 118 版本组件更新 | — | feef8025 |
| 2026-05-26 | v1.18.9 | 控制文案字体缩放 | — | 50526bcc |
| 2026-05-19 | v1.18.8 | 设计走查问题修复 | — | 3f6c6ff7 |
| 2026-05-13 | v1.18.8 | 弹窗优化 | — | 9e88cdb3 |
| 2026-05-12 | v1.18.7 | 修复菜单相关问题 | — | 0c6e89f9 |
| 2026-05-07 | v1.18.7 | 弹窗优化 | — | 0655ed31 |
| 2026-04-25 | v1.18.6 | TS 类型定义规范化 | — | 1c59cbd5 |
| 2026-04-20 | v1.18.5-alpha.0 | 修复图标位置问题 | — | bf9ba937 |