# 标题 · Heading

- 页面: https://jiguang132.com/zh/resources/astryx/docs/heading
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

标题用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **标题 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **标题 · 交互示例 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **标题 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **标题 · 交互示例 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Heading

语义化标题组件，渲染带主题样式的 h1–h6 元素，支持可选的编辑风格比例和行截断。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| level * | 1 \| 2 \| 3 \| 4 \| 5 \| 6 |  | 标题级别。决定语义 HTML 元素（h1–h6）和来自主题的样式（除非设置了 `type`）。 |
| type | 'display-1' \| 'display-2' \| 'display-3' |  | 展示类型变体。用展示级别的大小（更大、更轻的字重、更紧的行高）覆盖来自 `level` 的视觉样式。主题可以添加自定义视觉类型。`level` 仍然决定用于无障碍的 HTML 元素。用于英雄横幅、营销标题和数据提示。 |
| weight | 'normal' \| 'medium' \| 'semibold' \| 'bold' |  | 显式字重覆盖。优先于所选视觉类型或标题级别的默认值。 |
| children * | ReactNode |  | 标题内容。 |
| accessibilityLevel | 1 \| 2 \| 3 \| 4 \| 5 \| 6 |  | 无障碍级别覆盖。当设置且与 `level` 不同时，应用 `aria-level` 使文档大纲与视觉样式不同。 |
| color | 'primary' \| 'secondary' \| 'disabled' \| 'placeholder' \| 'accent' \| 'inherit' | 'primary' | 文本颜色。主题可添加自定义颜色。 |
| display | 'inline' \| 'block' | 'block' | 显示类型。当 maxLines > 0 或 hasCapsize 为 true 时，会静默覆盖为 'block'。 |
| maxLines | number | 0 | 截断前的最大行数。0 表示不截断。设置后，如果内容被截断，悬停时会显示工具提示。 |
| hasTruncateTooltip | boolean \| 'above' \| 'below' \| 'start' \| 'end' | true | 控制截断文本的工具提示行为。true 在默认位置显示工具提示，false 禁用它，或者放置字符串 ('above' \| 'below' \| 'start' \| 'end') 设置特定位置。 |
| wordBreak | 'break-word' \| 'break-all' |  | 截断时的断词行为。单行截断默认为 'break-all'，其他情况默认为 'break-word'。 |
| textWrap | 'wrap' \| 'nowrap' \| 'balance' \| 'pretty' |  | 文本换行行为。 |
| justify | 'start' \| 'center' \| 'end' | 'start' | 文本对齐（两端对齐）。使用逻辑值（start/end）以兼容 i18n/RTL。 |
| hasCapsize | boolean | false | 使用 text-box-trim 启用光学对齐。强制块级显示。 |
| hasStrikethrough | boolean | false | 应用删除线文本装饰。 |
| id | string |  | HTML id 属性。 |

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-heading",
      "visualProps": [
        "level",
        "color",
        "type",
        "weight"
      ]
    }
  ]
}
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt