# Button 按钮

> This page hasn't been translated into English yet, so the content below is in Chinese.

触发一个操作，例如提交表单、打开弹窗、跳转页面。

## 引入

```ts
import { NsButton } from '@ns/ui'
```

## 基础用法

`type` 决定颜色，共 7 种：`default`、`primary`、`success`、`warning`、`danger`、`info`、`help`。每种颜色都可以加 `plain`（朴素）、`round`（圆角）、`circle`（圆形）。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton>默认</NsButton>
      <NsButton type="primary">主要</NsButton>
      <NsButton type="success">成功</NsButton>
      <NsButton type="warning">警告</NsButton>
      <NsButton type="danger">危险</NsButton>
      <NsButton type="info">信息</NsButton>
      <NsButton type="help">帮助</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton plain>朴素</NsButton>
      <NsButton type="primary" plain>朴素</NsButton>
      <NsButton type="success" plain>朴素</NsButton>
      <NsButton type="warning" plain>朴素</NsButton>
      <NsButton type="danger" plain>朴素</NsButton>
      <NsButton type="info" plain>朴素</NsButton>
      <NsButton type="help" plain>朴素</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton round>圆角</NsButton>
      <NsButton type="primary" round>圆角</NsButton>
      <NsButton type="success" round>圆角</NsButton>
      <NsButton type="warning" round>圆角</NsButton>
      <NsButton type="danger" round>圆角</NsButton>
      <NsButton type="info" round>圆角</NsButton>
      <NsButton type="help" round>圆角</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton circle icon="search" aria-label="搜索" />
      <NsButton type="primary" circle icon="edit" aria-label="编辑" />
      <NsButton type="success" circle icon="check" aria-label="确认" />
      <NsButton type="warning" circle icon="bell" aria-label="提醒" />
      <NsButton type="danger" circle icon="trash" aria-label="删除" />
      <NsButton type="info" circle icon="mail" aria-label="消息" />
      <NsButton type="help" circle icon="star" aria-label="收藏" />
    </NsSpace>
  </NsSpace>
</template>
```

## 变体

`variant` 决定外观：`solid`（实心，默认）、`outline`（描边）、`plain`（朴素）、`text`（文字）、`link`（链接）。`plain` 属性是 `variant="plain"` 的简写。描边按钮是透明底、彩色边框，悬停时只变化底色；朴素按钮是浅色底、浅色边框（和 Tag 的浅色效果一样），悬停时变成实心按钮；文字按钮没有边框，悬停时出现浅色底；链接按钮只有文字，悬停时变淡。

下面每一行是一种变体，从左到右是 7 种颜色：

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <span class="row-label">solid</span>
      <NsButton>默认</NsButton>
      <NsButton type="primary">主要</NsButton>
      <NsButton type="success">成功</NsButton>
      <NsButton type="warning">警告</NsButton>
      <NsButton type="danger">危险</NsButton>
      <NsButton type="info">信息</NsButton>
      <NsButton type="help">帮助</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <span class="row-label">outline</span>
      <NsButton variant="outline">默认</NsButton>
      <NsButton type="primary" variant="outline">主要</NsButton>
      <NsButton type="success" variant="outline">成功</NsButton>
      <NsButton type="warning" variant="outline">警告</NsButton>
      <NsButton type="danger" variant="outline">危险</NsButton>
      <NsButton type="info" variant="outline">信息</NsButton>
      <NsButton type="help" variant="outline">帮助</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <span class="row-label">plain</span>
      <NsButton variant="plain">默认</NsButton>
      <NsButton type="primary" variant="plain">主要</NsButton>
      <NsButton type="success" variant="plain">成功</NsButton>
      <NsButton type="warning" variant="plain">警告</NsButton>
      <NsButton type="danger" variant="plain">危险</NsButton>
      <NsButton type="info" variant="plain">信息</NsButton>
      <NsButton type="help" variant="plain">帮助</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <span class="row-label">text</span>
      <NsButton variant="text">默认</NsButton>
      <NsButton type="primary" variant="text">主要</NsButton>
      <NsButton type="success" variant="text">成功</NsButton>
      <NsButton type="warning" variant="text">警告</NsButton>
      <NsButton type="danger" variant="text">危险</NsButton>
      <NsButton type="info" variant="text">信息</NsButton>
      <NsButton type="help" variant="text">帮助</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <span class="row-label">link</span>
      <NsButton variant="link">默认</NsButton>
      <NsButton type="primary" variant="link">主要</NsButton>
      <NsButton type="success" variant="link">成功</NsButton>
      <NsButton type="warning" variant="link">警告</NsButton>
      <NsButton type="danger" variant="link">危险</NsButton>
      <NsButton type="info" variant="link">信息</NsButton>
      <NsButton type="help" variant="link">帮助</NsButton>
    </NsSpace>
  </NsSpace>
</template>

<style scoped>
  .row-label {
    display: inline-block;
    width: 56px;
    color: var(--ns-text-color-secondary);
    font-size: var(--ns-font-size-sm);
  }
</style>
```

## 尺寸

`size` 可选 `large`、`default`、`small`，高度分别是 40、32、24px，带图标、圆角和圆形按钮也一样。高度来自主题变量 `--ns-component-size-large`、`--ns-component-size`、`--ns-component-size-small`，改这三个变量可以统一调整所有控件的高度。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton size="large">大型按钮</NsButton>
      <NsButton>默认按钮</NsButton>
      <NsButton size="small">小型按钮</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" size="large" icon="search">搜索</NsButton>
      <NsButton type="primary" icon="search">搜索</NsButton>
      <NsButton type="primary" size="small" icon="search">搜索</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" size="large" round>圆角按钮</NsButton>
      <NsButton type="primary" round>圆角按钮</NsButton>
      <NsButton type="primary" size="small" round>圆角按钮</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton size="large" circle icon="plus" aria-label="新增" />
      <NsButton circle icon="plus" aria-label="新增" />
      <NsButton size="small" circle icon="plus" aria-label="新增" />
      <NsButton size="large" icon="setting" aria-label="设置" />
      <NsButton icon="setting" aria-label="设置" />
      <NsButton size="small" icon="setting" aria-label="设置" />
    </NsSpace>
  </NsSpace>
</template>
```

## 形状

`round` 是圆角按钮，`circle` 是圆形按钮。圆形按钮只显示图标，不显示文字。两种形状都能和任意变体搭配。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton type="primary" round>实心圆角</NsButton>
      <NsButton type="primary" variant="outline" round>描边圆角</NsButton>
      <NsButton type="primary" plain round>朴素圆角</NsButton>
      <NsButton type="primary" round icon="upload">带图标</NsButton>
      <NsButton round dashed>虚线圆角</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" circle icon="plus" aria-label="新增" />
      <NsButton type="primary" variant="outline" circle icon="edit" aria-label="编辑" />
      <NsButton type="primary" plain circle icon="share" aria-label="分享" />
      <NsButton circle icon="heart" aria-label="喜欢" />
      <NsButton circle dashed icon="plus" aria-label="新增" />
      <NsButton type="danger" circle icon="trash" aria-label="删除" />
    </NsSpace>
  </NsSpace>
</template>
```

## 图标

`icon` 传图标名，`icon-position` 可选 `left`（默认）、`right`、`top`、`bottom`。图标在上、下时按钮竖排，高度随内容增加。各种变体都能带图标。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton type="primary" icon="arrow-left">左侧（left）</NsButton>
      <NsButton type="primary" icon="arrow-right" icon-position="right">右侧（right）</NsButton>
      <NsButton type="primary" icon="upload" icon-position="top">上方（top）</NsButton>
      <NsButton type="primary" icon="download" icon-position="bottom">下方（bottom）</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" variant="outline" icon="search">描边</NsButton>
      <NsButton type="primary" plain icon="edit">朴素</NsButton>
      <NsButton type="primary" variant="text" icon="copy">文字</NsButton>
      <NsButton type="primary" variant="link" icon="eye">链接</NsButton>
      <NsButton type="danger" icon="trash">删除</NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

只有图标、没有文字的按钮是正方形，边长等于按钮高度（large 40px、default 32px、small 24px），图标居中，根元素带 `ns-button--icon-only` 类。下面两种情况算只有图标：

- 传了 `icon`，默认插槽没有内容（只有空白也算没有内容）。
- 没传 `icon`，默认插槽里只有一个 `NsIcon`。这个图标也跟着按钮尺寸变成 18 / 16 / 14px。

`round` 只有图标时显示成圆形，和 `circle` 一样。加载中图标换成转圈，按钮仍然是正方形；显示 `loading-text` 时有文字，不算只有图标。`variant="text"` 和 `variant="link"` 不限制宽高，保持原来的内边距。在按钮组里也一样。只有图标的按钮要写 `aria-label`，屏幕阅读器才能读出按钮的用途。

```vue
<template>
  <NsSpace wrap>
    <NsButton icon="search" aria-label="搜索" />
    <NsButton type="primary" icon="plus" aria-label="添加" />
    <NsButton type="primary" variant="outline" icon="edit" aria-label="编辑" />
    <NsButton type="primary" plain icon="share" aria-label="分享" />
    <NsButton round icon="edit" aria-label="编辑" />
    <NsButton type="primary" variant="text" icon="setting" aria-label="设置" />
    <NsButton aria-label="设置"><NsIcon name="setting" /></NsButton>
    <NsButton type="primary" loading icon="refresh" aria-label="刷新" />
  </NsSpace>
</template>
```

## 加载状态

`loading` 时显示加载圈，按钮不能点击，图标隐藏。传了 `loading-text` 时显示这段文字，否则显示原来的按钮文字。`loading-progress-bar` 在按钮底边加一条进度条动画。各种颜色和变体都能加载。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton loading>默认</NsButton>
      <NsButton type="primary" loading>主要</NsButton>
      <NsButton type="success" variant="outline" loading>描边</NsButton>
      <NsButton type="warning" plain loading>朴素</NsButton>
      <NsButton type="danger" variant="text" loading>文字</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" loading loading-text="保存中...">保存</NsButton>
      <NsButton type="primary" loading loading-progress-bar>上传</NsButton>
      <NsButton type="primary" icon="upload" loading>图标被加载圈替换</NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

点击后加载 2 秒，期间不能再点：

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { NsButton } from '@ns/ui'

  const saving = ref(false)

  const save = () => {
    saving.value = true
    setTimeout(() => {
      saving.value = false
    }, 2000)
  }
</script>

<template>
  <NsButton
    type="primary"
    icon="check"
    :loading="saving"
    loading-text="保存中..."
    loading-progress-bar
    @click="save"
  >
    保存
  </NsButton>
</template>
```

## 禁用

`disabled` 后按钮变淡、不能点击，也不触发 `click`。每种颜色和变体都有对应的禁用样式；链接按钮（传了 `href`）禁用时去掉 `href`。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton disabled>默认</NsButton>
      <NsButton type="primary" disabled>主要</NsButton>
      <NsButton type="success" disabled>成功</NsButton>
      <NsButton type="warning" disabled>警告</NsButton>
      <NsButton type="danger" disabled>危险</NsButton>
      <NsButton type="info" disabled>信息</NsButton>
      <NsButton type="help" disabled>帮助</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" variant="outline" disabled>描边</NsButton>
      <NsButton type="primary" plain disabled>朴素</NsButton>
      <NsButton type="primary" variant="text" disabled>文字</NsButton>
      <NsButton type="primary" variant="link" disabled>链接</NsButton>
      <NsButton type="primary" href="https://example.com" disabled>带 href</NsButton>
      <NsButton type="primary" icon="plus" disabled>带图标</NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

## 自定义颜色

`color` 是自定义主色：实心按钮用它作底色和边框，文字白色；其他变体用它作文字颜色（描边按钮也作边框颜色，朴素按钮用它混出浅色底和浅色边框）。`text-color`、`bg-color`、`border-color` 分别单独设置文字、底色、边框，优先于 `color`。自定义颜色写在内联样式里，悬停时颜色不再变化。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton color="#626aef">实心</NsButton>
      <NsButton color="#626aef" variant="outline">描边</NsButton>
      <NsButton color="#626aef" plain>朴素</NsButton>
      <NsButton color="#626aef" variant="text">文字</NsButton>
      <NsButton color="#626aef" variant="link">链接</NsButton>
      <NsButton color="#626aef" disabled>禁用</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton color="#ff6600">实心</NsButton>
      <NsButton color="#ff6600" variant="outline">描边</NsButton>
      <NsButton color="#ff6600" plain>朴素</NsButton>
      <NsButton color="#ff6600" round icon="heart">圆角带图标</NsButton>
      <NsButton color="#ff6600" circle icon="star" aria-label="收藏" />
    </NsSpace>
    <NsSpace wrap>
      <NsButton text-color="#13c2c2" border-color="#13c2c2">自定义文字和边框</NsButton>
      <NsButton bg-color="#1f2937" text-color="#ffffff" border-color="#1f2937">深色底</NsButton>
      <NsButton type="primary" border-color="#ff4d4f">只改边框</NsButton>
      <NsButton color="#626aef" text-color="#fff7e6">color 加 text-color</NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

## 虚线和透明

`dashed` 把边框改成虚线，常用于“新增一项”这类次要操作。`transparent` 去掉底色，实心按钮的文字改用对应的主题色，适合放在有底色或图片的区域上。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton dashed>默认</NsButton>
      <NsButton type="primary" variant="outline" dashed>主要</NsButton>
      <NsButton type="success" variant="outline" dashed>成功</NsButton>
      <NsButton type="warning" variant="outline" dashed>警告</NsButton>
      <NsButton type="danger" variant="outline" dashed>危险</NsButton>
      <NsButton dashed icon="plus">新增一项</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton transparent>默认</NsButton>
      <NsButton type="primary" transparent>主要</NsButton>
      <NsButton type="success" transparent>成功</NsButton>
      <NsButton type="warning" transparent>警告</NsButton>
      <NsButton type="danger" transparent>危险</NsButton>
      <NsButton type="info" transparent>信息</NsButton>
      <NsButton type="help" transparent>帮助</NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

## 层级

`secondary`、`tertiary`、`quaternary` 把整个按钮的透明度降到 0.85、0.7、0.55，用来区分同一组按钮的主次。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton type="primary">主要</NsButton>
      <NsButton type="primary" secondary>次要（secondary）</NsButton>
      <NsButton type="primary" tertiary>第三（tertiary）</NsButton>
      <NsButton type="primary" quaternary>第四（quaternary）</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="danger" variant="outline">主要</NsButton>
      <NsButton type="danger" variant="outline" secondary>次要（secondary）</NsButton>
      <NsButton type="danger" variant="outline" tertiary>第三（tertiary）</NsButton>
      <NsButton type="danger" variant="outline" quaternary>第四（quaternary）</NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

## 宽度和高度

`width`、`height` 设置按钮的宽高，数字按 px，字符串原样使用（如 `'50%'`）。高度小于当前尺寸的最小高度时不生效。

```vue
<template>
  <NsSpace direction="vertical" fill>
    <NsSpace wrap>
      <NsButton type="primary" :width="200">宽 200px</NsButton>
      <NsButton :height="48">高 48px</NsButton>
      <NsButton type="primary" plain :width="120" :height="56" icon="upload" icon-position="top">
        上传
      </NsButton>
    </NsSpace>
    <NsButton type="primary" width="100%">宽度 100%</NsButton>
  </NsSpace>
</template>
```

## 链接按钮

传了 `href` 时渲染成 `<a>`，`target` 设置打开方式（`_blank`、`_self`、`_parent`、`_top`）。禁用或加载时去掉 `href`，并加上 `aria-disabled="true"`。`underline` 只在 `variant="link"` 时生效。

```vue
<template>
  <NsSpace direction="vertical" align="start">
    <NsSpace wrap>
      <NsButton type="primary" href="https://example.com" target="_blank">新窗口打开</NsButton>
      <NsButton type="primary" variant="outline" href="https://example.com" target="_blank">
        描边链接
      </NsButton>
      <NsButton href="https://example.com" target="_blank" disabled>禁用的链接</NsButton>
    </NsSpace>
    <NsSpace wrap>
      <NsButton type="primary" variant="link" href="https://example.com" target="_blank">
        不带下划线
      </NsButton>
      <NsButton type="primary" variant="link" href="https://example.com" target="_blank" underline>
        带下划线
      </NsButton>
      <NsButton type="danger" variant="link" href="https://example.com" target="_blank" underline>
        危险色链接
      </NsButton>
    </NsSpace>
  </NsSpace>
</template>
```

## 徽标

`badge` 在按钮角上显示徽标，内容可以是数字或文字；`badge-position` 可选 `top-right`（默认）、`top-left`、`bottom-right`、`bottom-left`；`badge-color` 改底色，默认危险色。

```vue
<template>
  <NsSpace direction="vertical" align="start" size="large">
    <NsSpace wrap size="large">
      <NsButton badge="5">右上（top-right）</NsButton>
      <NsButton badge="5" badge-position="top-left">左上（top-left）</NsButton>
      <NsButton badge="5" badge-position="bottom-right">右下（bottom-right）</NsButton>
      <NsButton badge="5" badge-position="bottom-left">左下（bottom-left）</NsButton>
    </NsSpace>
    <NsSpace wrap size="large">
      <NsButton type="primary" badge="99+">消息</NsButton>
      <NsButton badge="new" badge-color="#52c41a">更新</NsButton>
      <NsButton badge="热" badge-color="#fa8c16" plain type="warning">活动</NsButton>
      <NsButton icon="bell" badge="3" aria-label="通知，3 条未读" />
      <NsButton circle icon="mail" badge="12" aria-label="邮件，12 封未读" />
    </NsSpace>
  </NsSpace>
</template>
```

## 气泡提示

`popover` 打开按钮自带的气泡提示，内容写在 `popover-content`，标题写在 `popover-title`。`popover-trigger` 是触发方式：

- `hover`（默认）：悬停显示，移开后关闭。
- `click`：点击显示，再点一次、点按钮和提示以外的地方或按 Esc 关闭。
- `focus`：聚焦时显示（用 Tab 或点击），失去焦点后关闭。
- `manual`：不响应鼠标和焦点，用 `showPopover()`、`hidePopover()` 方法打开、关闭，按 Esc 也不关闭。

`popover-disabled` 或按钮被禁用时，提示自动收起。

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { NsButton, NsSpace } from '@ns/ui'
  import type { ButtonExpose } from '@ns/ui'

  const manualRef = ref<ButtonExpose>()
</script>

<template>
  <NsSpace wrap>
    <NsButton popover popover-content="悬停时显示，移开后关闭">悬停（hover）</NsButton>
    <NsButton
      popover
      popover-trigger="click"
      popover-title="提示"
      popover-content="点击显示，点外面或按 Esc 关闭"
    >
      点击（click）
    </NsButton>
    <NsButton popover popover-trigger="focus" popover-content="聚焦时显示，失去焦点后关闭">
      聚焦（focus）
    </NsButton>
    <NsButton
      ref="manualRef"
      popover
      popover-trigger="manual"
      popover-content="只能用 showPopover / hidePopover 控制"
    >
      手动（manual）
    </NsButton>
    <NsButton type="primary" variant="link" @click="manualRef?.showPopover()">打开</NsButton>
    <NsButton type="primary" variant="link" @click="manualRef?.hidePopover()">关闭</NsButton>
  </NsSpace>
</template>
```

`popover-placement` 是提示的位置，默认 `top`，共 12 个方向；放不下时自动翻到另一侧。把鼠标移到下面的按钮上看效果：

```vue
<template>
  <div class="placements">
    <div class="placements__row placements__row--center">
      <NsButton popover popover-placement="top-start" popover-content="top-start"
        >top-start</NsButton
      >
      <NsButton popover popover-placement="top" popover-content="top">top</NsButton>
      <NsButton popover popover-placement="top-end" popover-content="top-end">top-end</NsButton>
    </div>
    <div class="placements__row placements__row--between">
      <NsSpace direction="vertical" align="start">
        <NsButton popover popover-placement="left-start" popover-content="left-start">
          left-start
        </NsButton>
        <NsButton popover popover-placement="left" popover-content="left">left</NsButton>
        <NsButton popover popover-placement="left-end" popover-content="left-end"
          >left-end</NsButton
        >
      </NsSpace>
      <NsSpace direction="vertical" align="end">
        <NsButton popover popover-placement="right-start" popover-content="right-start">
          right-start
        </NsButton>
        <NsButton popover popover-placement="right" popover-content="right">right</NsButton>
        <NsButton popover popover-placement="right-end" popover-content="right-end">
          right-end
        </NsButton>
      </NsSpace>
    </div>
    <div class="placements__row placements__row--center">
      <NsButton popover popover-placement="bottom-start" popover-content="bottom-start">
        bottom-start
      </NsButton>
      <NsButton popover popover-placement="bottom" popover-content="bottom">bottom</NsButton>
      <NsButton popover popover-placement="bottom-end" popover-content="bottom-end">
        bottom-end
      </NsButton>
    </div>
  </div>
</template>

<style scoped>
  .placements {
    max-width: 520px;
    margin: 0 auto;
  }

  .placements__row {
    display: flex;
    gap: var(--ns-spacing-2);
  }

  .placements__row--center {
    justify-content: center;
  }

  .placements__row--between {
    justify-content: space-between;
    margin: var(--ns-spacing-3) 0;
  }
</style>
```

勾选后提示不再弹出，已经打开的会收起：

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { NsButton, NsCheckbox, NsSpace } from '@ns/ui'

  const disabled = ref(false)
</script>

<template>
  <NsSpace wrap>
    <NsCheckbox v-model="disabled">禁用气泡提示</NsCheckbox>
    <NsButton
      type="primary"
      popover
      :popover-disabled="disabled"
      popover-title="保存"
      popover-content="保存后会通知所有成员"
    >
      悬停看看
    </NsButton>
  </NsSpace>
</template>
```

## 防抖和节流

`debounce` 是防抖时间（毫秒）：连续点击时，停下来过了这段时间才触发一次 `click`。`throttle` 是节流时间：这段时间内只触发第一次点击。两者都是 0 表示不处理。

```vue
<script setup lang="ts">
  import { NsButton, NsMessage, NsSpace } from '@ns/ui'

  let searchCount = 0
  let submitCount = 0

  // 连续快速点击，停下 500 毫秒后才弹出一次
  const search = () => {
    searchCount += 1
    NsMessage(`第 ${searchCount} 次触发搜索`)
  }

  // 连续快速点击，每秒最多弹出一次
  const submit = () => {
    submitCount += 1
    NsMessage.success(`第 ${submitCount} 次触发提交`)
  }
</script>

<template>
  <NsSpace wrap>
    <NsButton type="primary" :debounce="500" @click="search">搜索（防抖 500ms）</NsButton>
    <NsButton type="primary" :throttle="1000" @click="submit">提交（节流 1s）</NsButton>
  </NsSpace>
</template>
```

## 点击波纹

`ripple` 在点击位置扩散一圈波纹，颜色跟着按钮的文字颜色。

```vue
<template>
  <NsSpace wrap>
    <NsButton ripple>默认</NsButton>
    <NsButton type="primary" ripple>主要</NsButton>
    <NsButton type="success" variant="outline" ripple>描边</NsButton>
    <NsButton type="warning" plain ripple>朴素</NsButton>
    <NsButton type="danger" variant="text" ripple>文字</NsButton>
    <NsButton type="primary" round ripple>圆角</NsButton>
  </NsSpace>
</template>
```

## 原生类型

`native-type` 是原生 `<button>` 的 `type`：`button`（默认，不提交表单）、`submit`（提交所在的表单）、`reset`（重置所在的表单）。

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { NsButton, NsSpace } from '@ns/ui'

  const result = ref('')
</script>

<template>
  <form @submit.prevent="result = '表单提交了'" @reset.prevent="result = '表单重置了'">
    <NsSpace wrap>
      <NsButton type="primary" native-type="submit">提交（submit）</NsButton>
      <NsButton native-type="reset">重置（reset）</NsButton>
      <NsButton @click="result = '只是点了按钮，表单没提交'">普通（button）</NsButton>
    </NsSpace>
  </form>
  <p style="margin-top: 12px">{{ result || '点上面的按钮试试' }}</p>
</template>
```

## 按钮组

几个相关的按钮放进 `NsButtonGroup`，相邻按钮合并边框，组上的 `type`、`size` 统一应用到组内按钮。更多用法见《ButtonGroup 按钮组》。

```vue
<template>
  <NsSpace wrap>
    <NsButtonGroup>
      <NsButton icon="arrow-left">上一页</NsButton>
      <NsButton icon="arrow-right" icon-position="right">下一页</NsButton>
    </NsButtonGroup>
    <NsButtonGroup type="primary">
      <NsButton icon="edit" aria-label="编辑" />
      <NsButton icon="share" aria-label="分享" />
      <NsButton icon="trash" aria-label="删除" />
    </NsButtonGroup>
    <NsButtonGroup size="small">
      <NsButton>日</NsButton>
      <NsButton>周</NsButton>
      <NsButton>月</NsButton>
    </NsButtonGroup>
  </NsSpace>
</template>
```

## Props

| 属性               | 类型                                                                               | 默认值        | 说明                                                               |
| ------------------ | ---------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------ |
| type               | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'help'` | `'default'`   | 类型。不传时取 ButtonGroup 的 `type`                               |
| size               | `'large' \| 'default' \| 'small'`                                                  | `'default'`   | 尺寸。不传时取 ButtonGroup 的 `size`                               |
| variant            | `'solid' \| 'outline' \| 'plain' \| 'text' \| 'link'`                              | `'solid'`     | 变体                                                               |
| disabled           | `boolean`                                                                          | `false`       | 是否禁用。不传时取 ButtonGroup 的 `disabled`                       |
| loading            | `boolean`                                                                          | `false`       | 是否加载中                                                         |
| loadingText        | `string`                                                                           | —             | 加载时显示的文字，不传时显示原来的按钮文字                         |
| loadingProgressBar | `boolean`                                                                          | `false`       | 加载时显示底部进度条                                               |
| icon               | `string`                                                                           | —             | 图标名                                                             |
| iconPosition       | `'left' \| 'right' \| 'top' \| 'bottom'`                                           | `'left'`      | 图标位置                                                           |
| plain              | `boolean`                                                                          | `false`       | 朴素按钮，等同于 `variant="plain"`                                 |
| round              | `boolean`                                                                          | `false`       | 圆角按钮                                                           |
| circle             | `boolean`                                                                          | `false`       | 圆形按钮，不显示文字                                               |
| nativeType         | `'button' \| 'submit' \| 'reset'`                                                  | `'button'`    | 原生 `button` 的 `type`                                            |
| autofocus          | `boolean`                                                                          | `false`       | 自动聚焦                                                           |
| color              | `string`                                                                           | —             | 自定义主色                                                         |
| textColor          | `string`                                                                           | —             | 自定义文字颜色                                                     |
| bgColor            | `string`                                                                           | —             | 自定义底色                                                         |
| borderColor        | `string`                                                                           | —             | 自定义边框颜色                                                     |
| dashed             | `boolean`                                                                          | `false`       | 虚线边框                                                           |
| transparent        | `boolean`                                                                          | `false`       | 透明底色                                                           |
| secondary          | `boolean`                                                                          | `false`       | 次要层级，透明度 0.85                                              |
| tertiary           | `boolean`                                                                          | `false`       | 第三层级，透明度 0.7                                               |
| quaternary         | `boolean`                                                                          | `false`       | 第四层级，透明度 0.55                                              |
| width              | `string \| number`                                                                 | —             | 宽度，数字按 px                                                    |
| height             | `string \| number`                                                                 | —             | 高度，数字按 px。小于当前尺寸的最小高度时不生效                    |
| href               | `string`                                                                           | —             | 链接地址，传了以后渲染成 `<a>`                                     |
| target             | `'_blank' \| '_self' \| '_parent' \| '_top'`                                       | —             | 链接的打开方式                                                     |
| underline          | `boolean`                                                                          | `false`       | 下划线，只在 `variant="link"` 时生效                               |
| badge              | `string \| number`                                                                 | —             | 徽标内容                                                           |
| badgeColor         | `string`                                                                           | —             | 徽标底色，默认危险色                                               |
| badgePosition      | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'`                     | `'top-right'` | 徽标位置                                                           |
| popover            | `boolean`                                                                          | `false`       | 是否带气泡提示                                                     |
| popoverContent     | `string`                                                                           | —             | 气泡提示内容                                                       |
| popoverTitle       | `string`                                                                           | —             | 气泡提示标题                                                       |
| popoverPlacement   | `PopperPlacement`                                                                  | `'top'`       | 气泡提示位置，12 个方向，放不下时自动翻转                          |
| popoverTrigger     | `'hover' \| 'click' \| 'focus' \| 'manual'`                                        | `'hover'`     | 气泡提示的触发方式。`manual` 用 `showPopover` / `hidePopover` 控制 |
| popoverDisabled    | `boolean`                                                                          | `false`       | 禁用气泡提示                                                       |
| debounce           | `number`                                                                           | `0`           | 防抖时间（毫秒）                                                   |
| throttle           | `number`                                                                           | `0`           | 节流时间（毫秒）                                                   |
| ripple             | `boolean`                                                                          | `false`       | 点击波纹                                                           |

## Events

| 事件  | 回调参数              | 说明                                                       |
| ----- | --------------------- | ---------------------------------------------------------- |
| click | `(event: MouseEvent)` | 点击时触发。禁用、加载中不触发；设了防抖、节流时按规则触发 |

## Slots

| 插槽    | 说明                                 |
| ------- | ------------------------------------ |
| default | 按钮文字。圆形按钮和加载文字时不显示 |

## 方法

| 方法        | 说明                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------- |
| focus       | 让按钮聚焦                                                                                          |
| blur        | 让按钮失去焦点                                                                                      |
| showPopover | 打开气泡提示（没开 `popover`、提示或按钮被禁用时不打开）；`popover-trigger="manual"` 时只能用它打开 |
| hidePopover | 关闭气泡提示                                                                                        |

## 类型

```ts
import type {
  ButtonType,
  ButtonSize,
  ButtonVariant,
  ButtonNativeType,
  ButtonIconPosition,
  ButtonBadgePosition,
  ButtonProps,
  ButtonExpose
} from '@ns/ui'
```

## 注意事项

- `plain` 等同于 `variant="plain"`；同时传了 `plain` 和别的 `variant` 时以 `variant` 为准。
- `underline` 只在 `variant="link"` 时生效。
- 同时设置 `debounce` 和 `throttle` 时只走防抖。
- 传了 `href` 时渲染成 `<a>`，禁用或加载时去掉 `href`。`nativeType` 和 `autofocus` 只对 `<button>` 有效。
- 按钮自带的气泡提示默认悬停触发，和 `NsPopover` 默认的点击触发不同。需要放复杂内容时用 `NsPopover` 包住按钮。
- 写在 `NsButton` 上的 `class`、`style`、`id`、`data-*`、`aria-*` 和原生事件会加到 `<button>` 或 `<a>` 上。
- 高度由 `min-height` 决定，不靠上下内边距撑开，所以自己写 `padding` 调不了高度，要改 `height` 属性或主题变量。
