---
title: "GuideState 引导状态"
description: "引导用户完成初始设置的状态视图"
category: Status
status: beta
since: 0.3.4
tags: [empty, state, guide, onboarding]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
外围页面已说明上下文时，使用预设的标题与说明。
::::TuffDemoWrapper{demo="GuideStateBasicDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGuideState
      :primary-action="{ label: '开始配置', type: 'primary' }"
      :secondary-action="{ label: '查看指南' }"
    />
  </template>
---
::::

### 自定义文案
引导独立出现在页面或面板中时，覆盖文案并设置 `surface="card"`。
::::TuffDemoWrapper{demo="GuideStateCustomDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGuideState
      title="创建第一个工作区"
      description="工作区帮助你整理项目、成员和自动化流程。按照引导完成初始配置。"
      surface="card"
      size="large"
      :primary-action="{ label: '创建工作区', type: 'primary' }"
    />
  </template>
---
::::

### 最佳实践

- 用于首次使用、设置提示或「从这里开始」面板；数据缺失用 `TxNoData`。
- 标题写出下一步，而不是描述空屏。
- 位于后台内容之间时用 `surface="card"`；已有外框的面板内保持 `plain`。
- 操作文案要具体，例如「创建工作区」「连接账号」，不写「继续」。
- 预设插画或生成按钮表达不了目标操作时，才传插槽。

## API 参考

继承 [TxEmptyState](./empty-state.zh.mdc) 除 `variant` 外的全部属性、事件与插槽；`variant` 固定为 `guide`。

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `title` | `string` | `'Start here'` | 覆盖预设标题。 |
| `description` | `string` | `'Follow the steps to get started.'` | 覆盖预设说明。 |
| `icon` | `TxIconSource \| string \| null` | guide 插画 | 替换插画；`null` 隐藏图标区。 |
| `iconSize` | `number` | 尺寸预设 | 图标或 spinner 尺寸（px）。 |
| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | 布局方向。 |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 内容对齐。 |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 视觉尺寸。 |
| `surface` | `'plain' \| 'card'` | `'plain'` | `card` 添加卡片表面。 |
| `primaryAction` | `EmptyStateAction` | - | 生成主操作，点击触发 `primary`。 |
| `secondaryAction` | `EmptyStateAction` | - | 生成次操作，点击触发 `secondary`。 |
| `actionSize` | `TxButtonProps['size']` | `'sm'` | 生成按钮的默认尺寸。 |
| `loading` | `boolean` | `false` | 无 `icon` 插槽或属性时显示 spinner。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `primary` | `()` | 点击生成的主操作按钮时触发。 |
| `secondary` | `()` | 点击生成的次操作按钮时触发。 |

### 插槽

| 插槽名 | Props | 说明 |
|------|-------|------|
| `icon` | - | 替换 guide 插画。 |
| `title` | - | 替换标题。 |
| `description` | - | 替换说明。 |
| `actions` | - | 替换生成的主/次操作按钮。 |

## 技术实现

- 源码：`packages/tuffex/packages/components/src/guide-state/`。

<TuffDocSourceLink />