---
title: "AgentScreen 智能体屏幕"
description: "呈现智能体当前画面的定比例画框"
category: AiAgent
status: beta
since: 0.6.0
tags: [agent, screen, capture, ai]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
`state` 在画面与占位间切换，`cursor` 叠加带动作文案的指针。
:::TuffDemoWrapper{demo="AgentScreenAgentScreenDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const state = ref<'working' | 'loading'>('working')
  </script>

  <template>
    <TxAgentScreen
      :state="state"
      label="智能体的屏幕"
      :cursor="{ x: 46, y: 62, label: '正在打开「照片」' }"
    >
      <!-- 截图、canvas 或 video -->
      <canvas ref="surface" />
    </TxAgentScreen>
  </template>
---
:::

### 最佳实践

- 实时 canvas 或 video 放进默认插槽，`src` 只用于静态截图。
- `label` 写这是谁的屏幕，指针的 `label` 写它正在做什么。
- 两帧之间把 `state` 切到 `loading`，不要留着旧画面，旧画面会被读成「卡住了」。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `src` | `string` | - | 画面图片地址；默认插槽有内容时忽略。 |
| `alt` | `string` | - | 画面的无障碍描述；设置 `src` 时必填。 |
| `label` | `string` | - | 画框下方的说明；不传则不渲染。 |
| `state` | `'working' \| 'loading'` | `'working'` | 显示画面或加载占位。 |
| `cursor` | `AgentScreenCursor` | - | 指针叠层；不传则不渲染。 |
| `ratio` | `string` | `'2964 / 1856'` | 画框的 CSS `aspect-ratio`，默认取上游采集图的比例。 |
| `ariaLabel` | `string` | `'Agent screen'` | 整个区域的无障碍名称。 |
| `loadingLabel` | `string` | `'Waiting for the agent’s screen'` | 加载时朗读的文本。 |

### 插槽

| 插槽名 | 说明 |
|---|---|
| `default` | 替换画面内容，优先于 `src`。 |
| `overlay` | 画面之上、裁剪之内的叠层；加载时一并撤掉。 |
| `label` | 替换画框下方的说明。 |

### 类型

#### AgentScreenCursor

| 字段 | 类型 | 说明 |
|---|---|---|
| `x` / `y` | `number` | 相对画框的百分比（0–100），缩放后位置不变；越界会被夹住。 |
| `label` | `string` | 指针旁的一行文案，通常是当前动作。 |

## 概述

- 组件只负责画框、指针与说明；画面来自默认插槽或 `src`，两者不叠加。
- `ratio` 固定比例而非高度：宽度跟随容器，高度按比例计算。
- `state` 为 `loading`，或既无默认插槽也无 `src` 时，显示骨架占位，并撤掉画面、指针与 `overlay`。
- 根节点为 `role="group"`，以 `ariaLabel` 命名；占位带 `role="status"` 与 `aria-live="polite"`，朗读 `loadingLabel`。
- 减少动态效果时，占位停止微光。

## 技术实现

- 占位复用库内骨架条 `skeleton-surface`，底色固定为 BUI 表面色。
- 移植自 [Beautiful UI](https://www.beautifului.dev) 第 21 例 Agent Screen（© 2026 Shane Levine，MIT）。
- 源码：`packages/tuffex/packages/components/src/agent-screen/`。

<TuffDocSourceLink />