# Description - 描述文本组件

## 说明

`Description` 用于展示页面或分组底部的描述文本，样式与 `ListCard.footer` 保持一致。文本为空时组件不渲染。

单行描述文本默认居中，多行描述文本使用系统自然对齐方式，在 LTR 和 RTL 环境下均从文字起始侧对齐。

支持在文案中通过占位符标记可按压的高亮文案，适用于隐私政策、用户协议等需要跳转的场景。

## 入参

> `Description` 为 **v1.18.20（待发布）新增**的公开组件，下表中的组件参数均随该版本首次提供。

| 属性                   | 说明                                                  | 类型              | 默认值    | 必填 |
| ---------------------- | ----------------------------------------------------- | ----------------- | --------- | ---- |
| **desc**               | 描述文本，支持占位符语法如 `[1文案]`                  | `string`              | -           | 是   |
| **singleLine**         | 单行文本对齐方式，超过一行自动居左                    | `'center' \| 'left'`  | `'center'`  | 否   |
| **highlights**         | 可按压的高亮文案回调数组，索引从 1 开始对应占位符序号 | `HighlightItem[]`     | -           | 否   |
| **bracketType**        | 占位符括号字符，分别作为开始和结束标记；未传入或长度小于 2 时不解析占位符 | `string` | - | 否 |
| **colorType**          | 高亮文案颜色类型，使用对应色系的高亮色值                  | `ColorType`       | `'green'` | 否   |
| **disabled**           | 禁用态；正文使用禁用语义色，高亮文案不可按压          | `boolean`         | `false`   | 否   |
| **accessible**         | 是否启用无障碍                                        | `boolean`         | -         | 否   |
| **accessibilityLabel** | 无障碍朗读文案                                        | `string`          | -         | 否   |
| **accessibilityHint**  | 无障碍提示文案                                        | `string`          | -         | 否   |
| **accessibilityRole**  | 无障碍角色                                            | `AccessibilityRole` | - | 否 |
| **accessibilityState** | 无障碍状态                                            | `AccessibilityState` | - | 否 |
| **accessibilityValue** | 无障碍值                                              | `AccessibilityValue` | - | 否 |
| **focusable**          | 是否允许获得焦点                                      | `boolean`         | -         | 否   |

### HighlightItem

| 属性        | 说明     | 类型         | 必填 |
| ----------- | -------- | ------------ | ---- |
| **onPress** | 按压回调 | `() => void` | 是   |

## 占位符语法

在 `desc` 文本中使用 `[序号文案]` 格式标记高亮文案，序号从 1 开始，对应 `highlights` 数组中的索引：

```
"查看[1隐私政策]和[2用户协议]"
```

渲染结果：`查看` `隐私政策`(高亮可按) `和` `用户协议`(高亮可按)

传入 `bracketType` 后可自定义占位符的开始和结束字符；未传入或长度小于 2 时不解析占位符：

- `[]` → `[1文案]`
- `{}` → `{1文案}`
- `()` → `(1文案)`
- `<>` → `<1文案>`
- `$$` → `$1文案$`

## 使用示例

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

// 基础用法
<Description desc="固件版本会定期自动更新" />

// 多行描述
<Description desc="这是一段较长的描述文本，超过一行时不再居中" />

// 高亮可按压文案
<Description
  desc="开启后将自动更新，详情请查看[1隐私政策]和[2用户协议]"
  highlights={[
    { onPress: () => console.log('隐私政策') },
    { onPress: () => console.log('用户协议') },
  ]}
  bracketType="[]"
/>

// 指定颜色类型
<Description
  desc="查看[1隐私政策]"
  highlights={[{ onPress: handlePress }]}
  bracketType="[]"
  colorType="blue"
/>

// 禁用态
<Description
  desc="查看[1隐私政策]"
  highlights={[{ onPress: handlePress }]}
  bracketType="[]"
  disabled
/>

// 相同文案不同按压事件
<Description
  desc="[1测试]一下能力，[2测试]一下整体功能"
  highlights={[
    { onPress: handleFirst },
    { onPress: handleSecond },
  ]}
  bracketType="[]"
/>
```

## 注意事项

- `ListCard` 的 `footer` 已经使用 `Description` 渲染，已有 `footer` 调用方式不需要修改。
- 不传 `highlights` 或 `bracketType` 未传/长度小于 2 时，占位符原样展示，不做解析。
- `disabled` 为 `true` 时，正文使用 `contentDisabledPrimary`，高亮文案使用对应色系的 Low 色且不响应按压。
- 占位符序号从 1 开始，与 `highlights` 数组的 index 0 对应。
- 多语言场景下占位符跟随翻译文案，翻译人员可直接看到完整上下文。