> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Button

## Button

可点击按钮，可绑定启动器动作或函数。

## 签名

```xml theme={null}
<Button Text="启动" Size="Md" Variant="Default"
        OnClick="Launch" />

<Button OnClick="Navigate" To="Instances">
  实例管理
</Button>
```

## 属性

| 属性 | 类型 | 默认 | 说明 |
| :- | :- | :- | :- |
| `Name` | identifier | — | 供 Click 触发器定位 |
| `Text` | string | 必填 | 按钮文字 |
| `Variant` | `Default` / `Secondary` / `Outline` / `Ghost` / `Destructive` / `Link` | `Default` | 样式 |
| `Size` | `Sm` / `Md` / `Lg` | `Md` | 尺寸 |
| `OnClick` | action | — | 点击动作 |

动作参数直接作为属性/属性元素写在 `Button` 上，见[动作参考](https://docs.qomicex.top/guide/custom-widget/reference/actions.md)。

### Size / Variant 可选值

| 属性 | 值 | 效果 |
| :- | :- | :- |
| `Size` | `Sm` | 小按钮，适合列表项和紧凑工具栏 |
| `Size` | `Md` | 默认尺寸 |
| `Size` | `Lg` | 大按钮，适合主要操作 |
| `Variant` | `Default` | 主按钮，实心强调色 |
| `Variant` | `Secondary` | 次级按钮，弱强调 |
| `Variant` | `Outline` | 描边按钮 |
| `Variant` | `Ghost` | 无背景，悬停才显示 |
| `Variant` | `Destructive` | 危险操作，红色 |
| `Variant` | `Link` | 文字链接样式 |

`Button.Size` 只接受 `Sm` / `Md` / `Lg`；`Text.Size` 的 `Xs`–`2Xl` 不适用于按钮。完整值表见[属性值参考](https://docs.qomicex.top/guide/custom-widget/reference/values.md)。

## ShortcutKeys

```xml theme={null}
<Button Text="快捷操作" OnClick="Refresh">
  <Button.ShortcutKeys>
    <ShortcutKey Key="Alt" />
    <ShortcutKey Key="L" />
  </Button.ShortcutKeys>
</Button>
```

* 支持 `Alt` / `Ctrl` / `Shift` / `Meta` 修饰键和一个主键。
* 也可以写 `<ShortcutKey Key="Alt+L" />`。
* 多个 `ShortcutKey` 组合成一个快捷键。
* 输入框聚焦时不会触发。
* 快捷键执行与点击按钮相同的 `OnClick` / `Click` 触发器。

## Effects

按钮支持与其它可视节点相同的 `<Button.Effects>`：

```xml theme={null}
<Button Text="强调">
  <Button.Effects>
    <ShadowEffect Radius="8" Color="Black" />
  </Button.Effects>
</Button>
```

效果类型与 Trigger 设置见 [Effect 效果](https://docs.qomicex.top/guide/custom-widget/advanced/effects.md)。

## 内容语法

```xml theme={null}
<Button OnClick="Refresh">刷新</Button>
```

等价于 `Text="刷新"`。

## 运行时行为

* 渲染启动器 `Button` 组件。
* `OnClick` 为空时按钮可点击但无动作。
* 点击时先触发同 `Name` 的 `Click` 触发器，再执行 `OnClick`。
* 预览模式下 `RunCommand` / `PluginApi` 不执行。

## 示例

```xml theme={null}
<Row Gap="2">
  <Button Text="启动" OnClick="Launch" />
  <Button Text="实例" Variant="Outline" OnClick="Navigate" To="Instances" />
  <Button Text="更多" Variant="Ghost" OnClick="OpenUrl" Url="https://example.com" />
</Row>
```

## 坑

* `OnClick` 的动作参数必须属于该动作；写错会被 XML 校验拒绝。
* 按钮文字过长会撑宽；需要换行时用 `Text` + 自定义容器，或缩短文字。
* `Name` 不是显示文本，只是触发器定位键。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.