# StatusAlert - 状态告警

## 说明

设备状态告警组件，支持单条直接渲染和多条堆叠展示。堆叠时显示第一条告警内容，底部有层叠阴影暗示还有更多条目；多条告警的完整列表和后续跳转由业务侧通过点击回调处理。

## StatusAlert 属性

| 属性 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|--------|------|
| **alerts** | 告警数据数组，单条直接渲染，多条自动堆叠；v1.18.20 起 `loading=true` 时可不传 | `StatusAlertItemProps[]` | - | 否 |
| **loading** | 加载态，显示并持续旋转的 20×20 加载图标，优先渲染单条加载状态；**v1.18.20（待发布）新增** | `boolean` | `false` | 否 |
| **loadingText** | 加载态文案，仅 `loading=true` 时生效；未传时使用首条告警的 `title`；**v1.18.20（待发布）新增** | `string` | - | 否 |
| **stackTitle** | 堆叠标题，多条时显示在卡片上方（如"共4条异常提示"） | `string` | - | 否 |
| **accessibilityTitle** | 堆叠标题无障碍配置 | `AccessibilityPropsType` | - | 否 |
| **onPress** | 堆叠预览或首条告警的点击回调 | `() => void` | - | 否 |
| **onNavigationPress** | 堆叠右侧导航箭头点击回调 | `() => void` | - | 否 |

## StatusAlertItem 属性

| 属性 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|--------|------|
| **title** | 通知文本内容 | `string` | - | 是 |
| **overline** | 标题上方小字 | `string` | - | 否 |
| **subtitle** | 副标题 | `string \| ReactElement` | - | 否 |
| **presentation** | 展示场景 | `'page' \| 'modal'` | `'page'` | 否 |
| **warning** | 警告态（标题红色）；`loading=true` 时加载态优先 | `boolean` | `false` | 否 |
| **loading** | 加载态，显示并持续旋转的 20×20 加载图标，颜色为 contentPrimaryNormal，优先级最高；**v1.18.20（待发布）新增** | `boolean` | `false` | 否 |
| **leadingIconType** | 左侧静态图标类型 | `'warning' \| 'fault' \| 'consumable' \| 'offline' \| 'reminder' \| 'custom'` | - | 否 |
| **leadingIcon** | 自定义左侧图标 | `ReactElement` | - | 否 |
| **actionType** | 右侧交互类型 | `'none' \| 'navigate' \| 'button' \| 'buttonGroup' \| 'custom'` | `'none'` | 否 |
| **actionPlacement** | 按钮组位置，仅 `actionType='buttonGroup'` 时生效；**v1.18.20（待发布）新增** | `'below' \| 'inlineEnd'` | `'below'` | 否 |
| **buttons** | 按钮配置 | `{ text: string; onPress?: () => void }[]` | - | 否 |
| **trailingNavigate** | 单按钮右侧追加箭头 | `boolean` | `false` | 否 |
| **onPress** | 整条点击回调；未传 `onNavigationPress` 时也作为箭头点击兜底 | `() => void` | - | 否 |
| **onNavigationPress** | 右侧导航箭头点击回调，用于单独处理箭头按压 | `() => void` | - | 否 |

## 使用示例

```tsx
import { StatusAlert } from 'mhui-rn';

// 单条告警 - 导航跳转
<StatusAlert
  alerts={[{
    title: '滤芯需要更换',
    leadingIconType: 'consumable',
    actionType: 'navigate',
    onPress: () => navigateToDetail(),
    onNavigationPress: () => navigateToDetail(),
  }]}
/>

// 多条告警 - 堆叠展示
<StatusAlert
  stackTitle="共3条异常提示"
  alerts={[
    { title: '网络连接异常', leadingIconType: 'offline', actionType: 'navigate', onPress: () => goNetwork() },
    { title: '温度传感器故障', leadingIconType: 'fault', warning: true },
    { title: '滤芯寿命不足', leadingIconType: 'consumable', actionType: 'button', buttons: [{ text: '购买' }] },
  ]}
  onPress={() => openAlertList()}
/>

// 带按钮的告警
<StatusAlert
  alerts={[{
    title: '固件需要升级',
    actionType: 'button',
    buttons: [{ text: '升级', onPress: () => startUpgrade() }],
  }]}
/>

// 加载中
<StatusAlert
  loading
  loadingText="正在同步设备状态"
  alerts={[{
    title: '正在更新设备状态',
  }]}
/>

// 按钮组显示在右侧
<StatusAlert
  alerts={[{
    title: '发现可用固件',
    actionType: 'buttonGroup',
    actionPlacement: 'inlineEnd',
    buttons: [
      { text: '忽略', onPress: () => ignoreUpgrade() },
      { text: '设置', onPress: () => openSettings() },
    ],
  }]}
/>
```

## 注意事项

- `alerts` 为空或未传且 `loading=false` 时组件不渲染
- 单条（`alerts.length === 1`）直接渲染该条，不进入堆叠/抽屉逻辑
- 堆叠时仅展示第一条告警内容，多条通过底层阴影暗示
- 多条告警只渲染第一条作为堆叠预览，完整列表需要业务侧在 `onPress` 中处理
- `onPress` 负责接收堆叠预览或首条告警的点击，不会自动打开抽屉
- `onNavigationPress` 只作用于右侧导航箭头；未传时箭头点击回退到 `onPress`
- `warning=true` 时标题颜色为红色；`loading=true` 时加载态优先，显示加载图标并使用普通标题颜色
- `loading=true` 时优先渲染单条加载状态，不依赖 `alerts` 有数据；使用 20×20 的加载图标（contentPrimaryNormal）并持续旋转
- 传入 `loadingText` 时显示 loading 文案，否则回退到首条告警的 `title`；`alerts` 为空且未传 `loadingText` 时文案为空
- `actionPlacement` 仅影响 `buttonGroup`：`below` 将按钮组放在正文下方，`inlineEnd` 将按钮组放在正文尾部（LTR 为右侧、RTL 为左侧）
- `buttonGroup` 最多展示 `buttons` 中的前两个按钮
- 多语言或按钮文案较长时建议使用 `below`，避免 `inlineEnd` 压缩正文区域