# HyperOS 组件 API 参考

> HyperOS 组件 API 知识库，覆盖公共导出、常用组件 Props 摘要、设计 Token 与维护检查清单。

## 公共导出概览

当前 HyperOS 入口 `src/hyperOS/index.ts` 导出 75 个公开符号，其中 70 个为运行时导出、5 个为 type-only 导出，包含组件、Token、Provider、工具函数和部分类型。按需加载路径由 `importMap.js` 维护。

### 基础组件

| 导出 | 路径 | 说明 |
|---|---|---|
| `ActionSheet` | `components/actionSheet` | 底部动作面板 |
| `Badge` | `components/badge` | 红点徽标 |
| `BlockButton` | `components/blockButton` | 块级按钮 |
| `Button` | `components/button` | 通用按钮 |
| `ButtonGroup` | `components/buttonGroup` | 按钮组 |
| `Checkbox` | `components/checkbox` | 复选框 |
| `Radio` | `components/radio` | 单选框 |
| `Drawer` | `components/drawer` | 抽屉容器 |
| `EmptyState` / `EmptyImageType` | `components/emptyState` | 空状态 |
| `Input` | `components/input` | 输入框 |
| `ListCard` | `components/listCard` | 列表卡片 |
| `ListItem` / `ListItemWithWidget` / `ActionListItem` | `components/listItem` | 列表项体系 |
| `LoadingToast` | `components/loadingToast` | 加载提示 |
| `Menus` | `components/menus` | 菜单 |
| `PopMenus` | `components/popMenus` | 弹出菜单 |
| `NavigationBar` | `components/navigationBar` | 顶部导航栏 |
| `NoticeBar` | `components/noticeBar` | 通知条 |
| `PullRefresh` | `components/pullRefresh` | 下拉刷新 |
| `SegmentedControls` | `components/segmentedControls` | 分段控制器 |
| `SelectList` | `components/selectList` | 选择列表 |
| `Separator` / `ColumnSeparator` | `components/separator` | 分割线 |
| `Spin` | `components/spin` | 加载动画 |
| `Description` | `components/description` | 描述文本 |
| `SubtitleGroup` | `components/subtitleGroup` | 副标题组 |
| `Switch` | `components/switch` | 开关 |
| `TouchableView` | `components/touchableView` | 统一按压容器 |

### Dialog 组件

| 导出 | 路径 | 说明 |
|---|---|---|
| `CommonDialog` | `components/dialog` | 常规弹窗 |
| `MessageDialog` | `components/dialog` | 文本消息弹窗，支持 checkbox |
| `ActionCustomDialog` | `components/dialog` | 自定义内容弹窗 |
| `InputDialog` | `components/dialog` | 输入弹窗 |
| `CustomDialog` | `components/dialog` | 完全自定义弹窗 |
| `PickerDialog` | `components/dialog` | 滚轮选择弹窗 |

> `BaseDialog` 是 dialog 目录内部基础壳，不从 `src/hyperOS/index.ts` 直接导出。

### IoT 组件

| 导出 | 路径 | 说明 |
|---|---|---|
| `ActionBlock` | `IotComponents/actionBlock` | 动作块 |
| `CardContainer` | `IotComponents/cardContainer` | 卡片容器 |
| `CardHeader` | `IotComponents/cardHeader` | 卡片头部 |
| `CircularButton` | `IotComponents/circularButton` | 圆形按钮 |
| `ContainerWithGap` | `IotComponents/containerWithGap` | 间距容器 |
| `DataGroup` | `IotComponents/dataGroup` | 数据组 |
| `DataItem` | `IotComponents/dataItem` | 数据项 |
| `LargeListEntrance` / `MediumListEntrance` / `SmallGridEntrance` | `IotComponents/entrance` | 入口组件 |
| `LargeListToggle` / `MediumListToggle` / `SmallGridToggle` | `IotComponents/IotToggle` | Toggle 组件 |
| `LargeTriggerSelect` | `IotComponents/IotSelect` | 大尺寸触发选择 |
| `MediumTriggerSelect` | `IotComponents/mediumTriggerSelect` | 中尺寸触发选择 |
| `MediumImageButton` | `IotComponents/mediumImageButton` | 中尺寸图文按钮 |
| `SmallImageButton` | `IotComponents/smallImageButton` | 小尺寸图文按钮 |
| `Slider` / `SliderWithToggle` | `IotComponents/slider` | 滑杆和带开关滑杆 |
| `SmallGridContainer` | `IotComponents/smallGridContainer` | 小宫格容器 |
| `StatusAlert` | `IotComponents/statusAlert` | 状态告警 |
| `Stepper` | `IotComponents/stepper` | 步进器 |

### 布局、Token 与工具

| 导出 | 路径 | 说明 |
|---|---|---|
| `PageLayout` | `layoutComponents/pageLayout` | 一级页布局 |
| `SubpageLayout` | `layoutComponents/subpageLayout` | 二级页布局 |
| `colorToken` / `defaultColorToken` | `styles/color` | 颜色 Token |
| `radiusToken` | `styles/radius` | 圆角 Token |
| `Fonts` | `styles/fonts` | 字体 Token |
| `spaceToken` | `styles/space` | 间距 Token |
| `ConfigContext` / `ConfigProvider` | `components/configProvider` | 主题上下文 |
| `defaultTheme` | `styles/themes/default` | 默认主题 |
| `showToast` | `native/mihome` | 原生 Toast |
| `useCollapsibleTitle` | `hooks/useCollapsibleTitle` | 折叠标题 hook |

## 常用组件 API 摘要

### ActionSheet

```tsx
<ActionSheet visible title="更多操作" options={[{ label: '删除', type: 'warning', onPress }]} onCancel={onCancel} />
```

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `visible` | `boolean` | `false` | 是否显示 |
| `title` | `string` | - | 顶部标题 |
| `options` | `ActionSheetOption[]` | - | 操作项，2-4 个 |
| `cancelText` | `string` | `'取消'` | 取消按钮文案 |
| `onCancel` | `() => void` | - | 点击取消或遮罩回调 |

`ActionSheetOption`：`label`、`type?: 'default' | 'warning' | 'emphasis'`、`colorType?`、`disabled?`、`onPress?`。

### Button / BlockButton / ButtonGroup

| 组件 | 关键 Props | 说明 |
|---|---|---|
| `Button` | `title`、`type`、`size`、`colorType`、`disabled`、`onPress`、`onLongPress` | 通用按钮 |
| `BlockButton` | `title`、`type`、`colorType`、`disabled`、`onPress`、`onLongPress` | 全宽块按钮 |
| `ButtonGroup` | `buttons`、`layout` | 按钮组，`buttons` 为必填 |

### Dialog

`BaseDialogPropsType` 是 Dialog 体系的基础类型，常用属性包括：

| 属性 | 类型 | 说明 |
|---|---|---|
| `visible` | `boolean` | 是否显示 |
| `title` | `string` | 标题 |
| `titleIcon` / `titleIconStyle` | `ReactNode` / `StyleProp<ViewStyle>` | 标题图标及容器样式 |
| `colorDepth` | `'base' | 'low'` | 弹窗底色深度 |
| `buttons` | `AbstractDialogButtonType[]` | 底部按钮 |
| `canDismiss` / `cancelable` | `boolean` | 遮罩和返回键关闭控制 |
| `onDismiss` / `onModalShow` / `onModalHide` | `() => void` | 生命周期回调 |

`MessageDialog` 使用 `contentText`、`label`、`checkboxChecked`、`onCheckboxChange` 管理正文与 checkbox。正文单行时居中、多行时自然对齐（按 `onTextLayout` 返回的实际行数判断，双端一致）；有 checkbox 时正文始终自然对齐。

### Input

```tsx
<Input
  value={value}
  onChangeText={setValue}
  placeholder="请输入"
  keyboardType="numeric"
  maxLength={6}
  feedbackType="notice"
  feedbackText="提示文案"
/>
```

| 属性 | 类型 | 说明 |
|---|---|---|
| `value` | `string` | 受控输入值 |
| `onChangeText` | `(text: string) => void` | 输入变化 |
| `placeholder` | `string` | 占位文本 |
| `type` | `'normal' | 'password'` | 输入类型 |
| `keyboardType` | `KeyboardTypeOptions` | 键盘类型；密码模式固定为 `ascii-capable`，普通模式未传时为 `default` |
| `maxLength` | `number` | 最大可输入字符数，透传给 RN `TextInput` |
| `colorDepth` | `'base' | 'low'` | 底色深度 |
| `prefix` | `ReactElement` | 左侧前缀 |
| `showClear` | `boolean` | 是否显示清除按钮 |
| `feedbackText` / `feedbackType` / `feedbackIconType` | `string` / `'normal' | 'notice' | 'warning'` / `'none' | 'alert' | 'help' | 'info'` | 反馈提示 |

### ListItem / ListItemWithWidget / ActionListItem

| 组件 | 关键 Props | 说明 |
|---|---|---|
| `ListItem` | `title`、`subtitle`、`value`、`onPress`、`onLongPress`、`actionType`、`badge`、`leadingIcon`、`customRender` | 普通列表项，`onPress` 为必填 |
| `ListItemWithWidget` | `widgetType`、`checked`、`onChange`、`buttonOption`、`switchOption`、`circularButtonOption`、`onLongPress` | 右侧带 Switch/Button/CircularButton/自定义控件 |
| `ActionListItem` | `title`、`status`、`colorType`、`onPress`、`disabled` | 操作项，支持 normal/warning 状态 |

`actionType` 取值：`'navigate' | 'select' | 'none' | 'custom'`。
`widgetType` 取值：`'switch' | 'button' | 'circularButton' | 'custom'`。

### NavigationBar

```tsx
<NavigationBar title="设备详情" left={{ key: 'back', onPress: goBack }} right={{ key: 'more', onPress: openMenu }} />
```

| 属性 | 类型 | 说明 |
|---|---|---|
| `title` | `string | ReactElement` | 标题 |
| `titleSize` | `'normal' | 'large'` | 标题尺寸 |
| `showBrandLogo` | `boolean` | normal 模式下自动展示品牌图标 |
| `isRounded` | `boolean` | 品牌图是否使用圆角描边，默认 `false`；开启时使用 20 × 20、1px 边框和 5px 圆角的透明容器，内部图片为 18 × 18、4px 圆角；关闭时不使用圆角边框。品牌图使用 `contain` 避免裁切 |
| `left` | `LeftButtonConfig` | 左侧按钮 |
| `right` | `RightButtonConfig` | 右侧配置；标准图标使用对应 `key`，自定义内容使用 `key: 'custom'` 和 `customRender` |
| `colorStrategy` | `'auto' | 'forceDark'` | 沉浸模式主题 |
| `backgroundColor` | `string` | 背景色 |
| `collapseTitle` / `titleVisible` / `titleOpacity` | `boolean` / `boolean` / `number | AnimatedInterpolation` | 折叠标题模式 |

`NavigationBar.ICON` 当前包含：`BACK`、`CANCEL`、`CONFIRM`、`MORE`、`PREFERENCES`、`PREFERENCES_SELECTED`、`LISTCHECK`、`ADD`、`INFO`、`DELETE`、`HELP`、`SEARCH`、`CUSTOM`。

右侧自定义内容示例：

```tsx
<NavigationBar
  title="设备"
  right={{
    key: 'custom',
    customRender: <TouchableView onPress={openSettings}>...</TouchableView>,
  }}
/>
```

### Description

```tsx
<Description desc="底部提示信息" />
```

`Description` 是描述文本组件，样式与 `ListCard.footer` 一致。单行文本默认居中，多行文本使用系统自然对齐方式；`ListCard` 的 `footer` 已通过该组件渲染。

| 属性 | 类型 | 说明 |
|---|---|---|
| `desc` | `string` | 描述文本；为空时不渲染 |
| `highlights` | `{ onPress: () => void }[]` | 与描述文本中的 `[序号文案]` 占位符对应的高亮按压回调 |
| `singleLine` | `'center' | 'left'` | 单行对齐方式，默认 `center`；超过一行时使用自然对齐 |
| `bracketType` | `string` | 占位符开始和结束字符；未传入或长度小于 2 时不解析 |
| `colorType` | `ColorType` | 高亮文案颜色类型，默认 `green` |
| `disabled` | `boolean` | 禁用态；正文使用 `contentDisabledPrimary`，高亮文案不可按压，默认 `false` |
| `accessible` / `accessibilityRole` / `accessibilityLabel` / `accessibilityHint` | `boolean` / `AccessibilityRole` / `string` / `string` | 无障碍配置 |
| `accessibilityState` / `accessibilityValue` / `focusable` | `AccessibilityState` / `AccessibilityValue` / `boolean` | 无障碍状态、值和焦点配置 |

### NoticeBar

| 属性 | 类型 | 说明 |
|---|---|---|
| `title` | `string` | 通知文本，必填 |
| `status` | `'default' | 'emphasis' | 'notice' | 'warning'` | 状态 |
| `leadingIcon` | `ReactElement` | 左侧图标 |
| `actionType` | `'none' | 'navigate' | 'close'` | 右侧交互类型 |
| `colorType` | `ColorType` | emphasis 色系 |
| `onPress` / `onClose` | `() => void` | 导航或关闭回调 |

### SegmentedControls

```tsx
<SegmentedControls options={[{ label: '自动', value: 'auto' }]} activeValue={mode} onChange={setMode} />
```

| 属性 | 类型 | 说明 |
|---|---|---|
| `options` | `{ label: string; value: string }[]` | 选项，2-5 个 |
| `activeValue` | `string` | 当前选中值 |
| `onChange` | `(value: string) => void` | 切换回调 |

### StatusAlert

```tsx
<StatusAlert alerts={[{ title: '设备离线', leadingIconType: 'offline', actionType: 'navigate', onPress }]} />
```

| 属性 | 类型 | 说明 |
|---|---|---|
| `alerts` | `StatusAlertItemProps[]` | 告警数据，单条直接渲染，多条自动堆叠；`loading=true` 时可不传 |
| `loading` | `boolean` | 加载态，优先渲染单条加载状态，不依赖 `alerts` 有数据 |
| `loadingText` | `string` | 加载态文案，仅 `loading=true` 时生效；未传时回退到首条告警标题 |
| `stackTitle` | `string` | 多条堆叠标题 |
| `accessibilityTitle` | `AccessibilityPropsType` | 堆叠标题无障碍配置 |
| `onPress` | `() => void` | 堆叠预览或首条告警的点击回调 |
| `onNavigationPress` | `() => void` | 右侧导航箭头点击 |

`StatusAlertItemProps` 关键属性：`overline`、`title`、`subtitle`、`presentation`、`warning`、`loading`、`leadingIconType`、`leadingIcon`、`actionType`、`actionPlacement`、`buttons`、`trailingNavigate`、`customAction`、`onPress`、`onNavigationPress`。

当 `actionType='buttonGroup'` 时，`actionPlacement` 支持 `'below' | 'inlineEnd'`，默认 `'below'`。`below` 将按钮组放在正文下方，`inlineEnd` 将按钮组放在正文尾部；两种模式都最多展示前两个按钮。

### CircularButton / IotToggle

`CircularButton` 是 `SmallGridToggle` 和 `MediumListToggle` 共用的圆形图标按钮；`size` 会控制按钮尺寸：

| 组件 | 关键 Props | 说明 |
|---|---|---|
| `CircularButton` | `icon`、`checked`、`disabled`、`colorType`、`onChange`、`size` | `size` 为 `'small' \| 'medium'`，尺寸分别为 40 和 44 |
| `LargeListToggle` | `title`、`subtitle`、`checked`、`disabled`、`toggleType`、`onChange`、`colorType`、`switchOption`、`circularButtonOption` | 大型列表开关，右侧支持 `Switch` 或固定 `small` 尺寸的 `CircularButton` |
| `MediumListToggle` | `title`、`subtitle`、`icon`、`checked`、`disabled`、`onPress`、`onChange`、`colorType`、`size` | 中型列表开关，`size` 透传给 `CircularButton` |
| `SmallGridToggle` | `title`、`checked`、`disabled`、`onChange`、`colorType`、`icon`、`onPress`、`size` | 小型网格开关，`size` 透传给 `CircularButton`，默认 `'small'` |

Toggle 的开关状态使用 `checked`，状态回调使用 `onChange`；`size="medium"` 时圆形按钮尺寸为 44，默认尺寸为 40。

`LargeListToggle` 默认使用 `Switch`，`switchOption` 会透传给内部开关。设置 `toggleType="circularButton"` 后使用固定 `small` 尺寸的 `CircularButton`，可通过 `circularButtonOption.icon` 覆盖默认 `IcIotPower`；`checked`、`disabled`、`colorType` 和 `onChange` 始终由 `LargeListToggle` 统一控制。`MediumListToggle` 和 `SmallGridToggle` 的接口目前仍声明了 `switchOption`，但当前实现不会使用该参数。

### Stepper

```tsx
<Stepper value={26} min={16} max={30} step={1} symbolType="degree" onChange={setValue} />
```

| 属性 | 类型 | 说明 |
|---|---|---|
| `value` | `number | string | null` | 当前值 |
| `onChange` | `(value) => void` | 值变化 |
| `min` / `max` / `step` | `number | string` | 范围与步长 |
| `digits` | `number` | 小数位 |
| `formatter` | `(value) => string` | 展示格式化 |
| `prefix` / `suffix` / `suffixSubscript` | `ReactNode` / `ReactNode` / SVG 或 Image | 前后缀 |
| `iconType` | `'plusMinus' | 'leftRight'` | 操作图标类型 |
| `symbolType` | `'percent' | 'degree' | 'custom'` | 符号类型 |
| `stringMode` | `boolean` | 字符串值模式 |

### Slider / SliderWithToggle

| 组件 | 关键 Props | 说明 |
|---|---|---|
| `Slider` | `color`、`min`、`max`、`value`、`step`、`disabled`、`active`、`isPercent`、`mark`、`pattern`、`discrete`、`onChange`、`onAfterChange`、`showLabel` | 滑杆 |
| `SliderWithToggle` | `sliderProps`、`buttonProps`、`style`、`spacing` | 滑杆 + 右侧 VariantSwitch |

`buttonProps` 里的开关状态使用 `checked`，回调使用 `onChange`。

### ImageButton

| 组件 | 关键 Props | 说明 |
|---|---|---|
| `MediumImageButton` | `title`、`subtitle`、`actionType`、`disabled`、`active`、`leadingIcon`、`onPress`、`colorType` | 中尺寸图文按钮 |
| `SmallImageButton` | `title`、`actionType`、`disabled`、`active`、`custom`、`onPress`、`colorType` | 小尺寸图文按钮 |

`actionType` 取值：`'button' | 'toggle'`。

### PageLayout / SubpageLayout

布局组件采用 slot 组合：

```tsx
<PageLayout>
  <PageLayout.Background>{background}</PageLayout.Background>
  <PageLayout.Navigation>{navigation}</PageLayout.Navigation>
  <PageLayout.Header>{header}</PageLayout.Header>
  <PageLayout.AlertContainer>{alerts}</PageLayout.AlertContainer>
  <PageLayout.Content>{content}</PageLayout.Content>
  <PageLayout.Footer>{footer}</PageLayout.Footer>
</PageLayout>
```

| 组件 | Slots | Props |
|---|---|---|
| `PageLayout` | `Background`、`Navigation`、`Header`、`AlertContainer`、`Content`、`Footer` | `children`、`scrollRef`、`onScroll` |
| `SubpageLayout` | `Background`、`Navigation`、`Header`、`Content`、`Footer` | `children`、`scrollRef`、`onScroll` |

底部安全区逻辑统一依赖 `src/constants/layout.ts`。

## 设计 Token

| 导出 | 说明 |
|---|---|
| `colorToken` / `defaultColorToken` | HyperOS 语义色 |
| `radiusToken` | 圆角 Token |
| `Fonts` | 字体 Token |
| `spaceToken` | 间距 Token |
| `ConfigProvider` / `ConfigContext` | 主题上下文 |

## 维护检查清单

新增或修改组件 API 后，至少检查：

1. `src/hyperOS/{components|IotComponents|layoutComponents}/{component}/interface.ts`
2. `src/hyperOS/{...}/{component}/index.ts(x)`
3. `src/hyperOS/index.ts`
4. `importMap.js`
5. 组件目录 `*.zh-CN.md`
6. `docs/components.md` 和必要时的 `docs/architecture.md`
7. demo 项目的 SDK barrel 与示例页面