# DataGroup

数据展示容器组件，横向排列 1–3 个 `DataItem`，各列等宽平分可用宽度。支持右侧自定义内容区（`customContainer`）。

> 文件：`src/hyperOS/IotComponents/dataGroup/DataGroup.tsx`

## 导入

```ts
import { DataGroup } from '@hyperOS/IotComponents/dataGroup';
```

## 基础用法

```tsx
<DataGroup
  items={[
    { title: '25°C', subtitle: '当前温度' },
    { title: '60%', subtitle: '当前湿度' },
  ]}
/>
```

## 1–3 列

`items` 数组长度决定列数（1–3），各列等宽平分内部可用宽度。

```tsx
// 单列
<DataGroup items={[{ title: '25°C', subtitle: '温度' }]} />

// 三列
<DataGroup
  items={[
    { title: '25°C', subtitle: '温度' },
    { title: '60%', subtitle: '湿度' },
    { title: '1013', subtitle: '气压 hPa' },
  ]}
/>
```

## DataItem 各 prop 独立配置

每个 item 可独立设置所有 `DataItem` Props。

```tsx
<DataGroup
  items={[
    { title: '运行中', subtitle: '设备状态', stringMode: true },
    { title: '25°C', subtitle: '查看记录', colorType: 'accent', onPress: () => {} },
    { title: '--', subtitle: '暂无数据', disabled: true },
  ]}
/>
```

## 右侧自定义内容（customContainer）

传入 `customContainer` 后，右侧固定预留 120pt 宽度渲染自定义内容，与数据列底部对齐。数据列宽度自动扣减。

```tsx
<DataGroup
  items={[
    { title: '25°C', subtitle: '温度' },
    { title: '60%', subtitle: '湿度' },
  ]}
  customContainer={<SomeWidget />}
/>
```

## Props

### DataGroup Props

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `items` | `DataGroupItem[]` | — | 数据项数组（必填），1–3 个 |
| `containerWidth` | `number` | — | 手动指定容器宽度，不传则自动通过 `onLayout` 获取 |
| `customContainer` | `ReactNode` | — | 右侧自定义渲染区域，最大宽度 120pt |
| `accessible` | `boolean` | `true` | 无障碍开关 |
| `accessibilityLabel` | `string` | — | 无障碍标签 |
| `accessibilityHint` | `string` | — | 无障碍提示 |

**兼容旧版 props（待移除，不建议使用）：**

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `titleColor` | `string` | — | 主标题颜色，建议改用各 item 的 `colorType` |
| `subtitleColor` | `string` | — | 副标题颜色 |
| `padding` | `number` | `4` | 水平内边距 |
| `backgroundColor` | `string` | `'transparent'` | 背景色，建议由外层 `CardContainer` 控制 |
| `borderRadius` | `number` | `0` | 圆角，建议由外层 `CardContainer` 控制 |

### DataGroupItem（items 数组元素）

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | — | 主标题文本（必填） |
| `subtitle` | `string` | — | 副标题文本 |
| `size` | `'small' \| 'medium'` | `'medium'` | 主标题尺寸 |
| `stringMode` | `boolean` | `false` | `false` 用数字字体，`true` 用系统字体 |
| `align` | `'left' \| 'center'` | `'left'` | 文本对齐方式 |
| `onPress` | `() => void` | — | 点击回调，有值时显示右箭头图标 |
| `colorType` | `ColorType` | — | 主标题颜色类型，对应色系 Content 文字色；不传则使用默认内容色 |
| `disabled` | `boolean` | `false` | 禁用态 |

## 注意事项

1. `items` 为空数组时组件返回 `null`，不渲染任何内容。
2. 列间距固定为 12pt（Figma 规范值），不可通过 props 调整。
3. 传入 `customContainer` 后，数据列总宽度会自动扣减 120pt，列数越多每列越窄。
4. 背景样式（圆角、背景色）建议由外层 `CardContainer` 统一控制，兼容 props 将在后续版本移除。
5. `containerWidth` 通常不需要手动传入，组件会通过 `onLayout` 自动测量宽度。

## 迁移自 InformationArea

`InformationArea` 已标记为 `@deprecated`，建议按如下方式迁移：

```tsx
// 旧写法
<InformationArea
  items={[{ title: '25°C', subtitle: '温度' }]}
  align="center"
  showSubtitleIcon
  onSubtitleIconPress={(item, index) => {}}
/>

// 新写法
<DataGroup
  items={[{
    title: '25°C',
    subtitle: '温度',
    align: 'center',
    onPress: () => {},
  }]}
/>
```