按钮 (Button)

v-btn 组件用满足 material design 主题的，拥有多种可选项的按钮组件来替换标准的 html 按钮。任何色彩辅助类都可以用来改变背景或文字的颜色。

使用

最简单的按钮包含大写文本、轻微的仰角、悬停效果和单击时的波纹效果。

API

组件	描述
v-btn	主要组件

组件结构

v-btn 中元素的推荐放置是：

• 将文本置于其中
• 在容器文字的周围增加可见内容

元素 / 区域	描述
1. 容器	除了文本以外，按钮容器通常还可以包含v-icon 组件
2. 图标 (可选)	使用图标形式提高文字的可读性
3. 文字	显示文本和其他内联元素的内容区域

指南

v-btn 组件通常贯穿整个 Vuetify ，是任何应用程序的常用组件。它可以用于导航和表单提交几乎所有情景，而且可以有很多不同的样式。

下面的代码片段是一个基础的只包含文本的 v-btn 组件示例：

<v-btn>Button</v-btn>

属性 (Props)

很多属性可以用于修改 v-btn 的默认样式。其中 prepend-icon 和 append-icon 属性通常用于提供直接插入图标，而 block 和 stacked 常被使用来管理组件的形式。

间距 (Density)

density 属性用于控制按钮垂直方向所占的空间。

尺寸 (Size)

其中 size 属性用来控制按钮的大小和随着间距调整的缩放程度。默认的尺寸是 undefined，会被转化为 medium

块级按钮 (Block)

块级按钮会扩展至其父容器的最大宽度。这一点在想要创建充满卡片或者对话框宽度的按钮时十分有用。

INFO

当 Block 设定为 width: 100% 在 flex 容器中会导致宽度溢出容器的问题。

圆角 (Rounded)

使用 rounded 属性来控制边框的圆角。

强调效果 (Elevation)

elevation 属性可以提供24层级的阴影深度，默认的值为 2dp。

波纹 (Ripple)

ripple 属性决定了按钮是否拥有 v-ripple 效果。

变化形式 (Variant)

variant 属性可以让按钮具有不同的风格。允许的变化形式有：elevated（default）、flat、tonal、outlined、text 和plain。

值	示例	描述
elevated		使用按钮的阴影强调
flat		移除按钮的阴影效果
tonal		按钮的背景颜色被设为文字颜色的高透明度版本
outlined		以当前文字颜色绘制细边框
text		移除背景颜色和阴影
plain		移除背景颜色并且在未悬停时降低透明度

图标 (Icon)

图标可以用作按钮的主要内容。这种按钮常用于 v-toolbar 和 v-app-bar 组件中。

加载效果 (Loaders)

使用 loading 属性，您可以通知用户正在进行处理。默认行为是使用 v-progress-circular 组件，但这可以通过 loader 插槽进行定制。

栏 (Bar) 中的按钮

一个常见的用例是在 v-toolbar 或 v-app-bar 组件中使用带有 icon 属性的 v-btn。

插槽 (Slots)

v-btn 组件提供了插槽，使您可以自定义由其属性创建的内容，或添加额外的内容。

插槽	描述
1. Default	默认插槽
2. Prepend	默认插槽前面的内容
3. Append	默认插槽后面的内容
4. Loader	当 loading 值为 true 时显示的内容

插槽为您提供了更大的控制权，可以自定义 v-btn 组件的内容，同时仍然可以利用易于使用的 props。

图标颜色

当您将 prepend-icon 和 append-icon 属性与相应的插槽 prepend 或 append 结合使用时，您可以放置一个 v-icon，该组件会自动注入指定的图标。

自定义加载器

loader 插槽允许您自定义加载指示器。在这个例子中，我们使用 v-progress-linear 组件来创建一个跨越按钮整个宽度的加载进度条。

示例

下面的示例集展示了更多 v-btn 组件的高级的、真实的用法。

Discord 事件

在这个示例中，我们使用多个不同的按钮变体和样式来创建一个 Discord 事件卡片的副本。

评价组

除了搭配按钮组中使用，v-btn 组件还可以和 v-item-group搭配使用。下面的例子展示了我们创建了一组按钮用于获得某个评价的分数，它使用了自定义样式的 active 状态。

税务表确认

在下面的例子中使用了 v-text-field 组件来收集数据，在提交数据时使用了 v-btn 的 loading 属性表示过程进行中。

对话框操作

按钮通常用于触发 v-dialog 中的操作。在此示例中，我们使用 outlined 变体和 color 属性来创建一个在视觉上与其他按钮不同的按钮

Cookie 设置

在此示例中，我们使用 v-banner 组件来显示自定义 cookie 同意横幅。点击“管理Cookies”按钮将提示一个v-dialog组件。

只读按钮

在此示例中，我们根据“订阅”状态更改 v-btn 的属性。当用户订阅时，我们希望disabled与按钮的交互，但不改变其外观；这是使用禁用属性时发生的情况。

全局配置

使用Global configuration修改默认值并为所有v-btn组件设置默认样式。这有助于保持您的应用程序的一致性，并允许您在将来以最小的努力对其进行更改。

import { createVuetify } from 'vuetifyjs'

export default createVuetify({
  defaults: {
    VBtn: {
      color: 'primary',
      variant: 'outlined',
      rounded: true,
    },
  },
})

别名

使用the component aliasing 生成从 v-btn 组件派生的虚拟组件的功能。在处理设计规范中的大量按钮变化或开发基于 Vuetify 的自定义库时，这被证明是有价值的。

import { createVuetify } from 'vuetifyjs'
import { VBtn } from 'vuetifyjs/components'

export createVuetify({
  aliases: {
    VBtnSecondary: VBtn,
    VBtnTertiary: VBtn,
  },
  defaults: {
    VBtn: {
      color: 'primary',
      variant: 'text',
    },
    VBtnSecondary: {
      color: 'secondary',
      variant: 'flat',
    },
    VBtnTertiary: {
      rounded: true,
      variant: 'plain',
    },
  },
})

SASS 变量

通过修改 v-btn SASS variables 变量进行微调。当您想要更改默认按钮高度或填充时，这非常有用。

@use 'vuetify/settings' with (
  $button-banner-actions-padding: 16px,
  $button-height: 32px,
);

其中一些值也可以使用 Global configuration 进行修改，并且优先于 SASS 变量。例如，height 属性可用于更改默认按钮高度，而无需修改 SASS 变量。

默认副作用

在某些情况下，会注入一组默认属性或将自定义样式应用于v-btn。这可能有多种原因，但最常见的是：

• 匹配设计规范
• 根据上下文提供更好的视觉外观
• 避免创建专有组件；例如： v-bottom-navigation-btn 和 v-card-btn

横幅 (Banners)

v-banner-actions 组件应用text 变体和 slim 属性，将按钮 x 轴填充减少到 8px。

开发文档	API
横幅(Banners)	v-banner-actions

在 v-banner-actions 组件中使用时，以下属性会被修改：

属性	值
color	由 v-banner-actions 提供
density	由 v-banner-actions 提供
slim	true
variant	text

底部导航栏（Bottom navigation）

v-bottom-navigation 组件排除了所有先前提供的默认值并应用其自己的默认值。这是为了避免在Global configuration中对 v-btn 进行更改 。按钮会自动注册到 v-bottom-navigation 的组，并在单击时更新model。

开发文档	API
Bottom navigation(底部导航栏)	v-bottom-navigation

在 v-bottom-navigation 组件中使用时，会修改以下属性：

属性	值
color	有 v-bottom-navigation 提供
density	有 v-bottom-navigation 提供
stacked	当 v-bottom-navigation 的 mode 属性是 shift 时，为 true
variant	text

按钮组（Button groups）

v-btn-group 组件对 v-btn 组件进行了多项更改。

开发文档	API
Button groups(按钮组)	v-btn-group

在 v-btn-group 组件中使用时，以下属性会被修改：

属性	值
color	由 v-btn-group 提供
height	auto
density	由 v-btn-group 提供
flat	true
variant	由 v-btn-group 提供

卡片（Cards）

v-card-actions 组件应用 text 变体和 slim 属性，将按钮 x 轴填充减少到 8px，并为所有兄弟应用起始边距。这是为了确保按钮中的文本与卡片的文本和标题对齐，并且其操作之间有空格。

开发文档	API
Cards(卡片)	v-card-actions

在 v-card-actions 组件中使用时，会修改以下属性

属性	值
slim	true
variant	text

消息条 (Snackbars)

v-snackbar 组件应用text变体 slim 属性，并消除所有 v-btn 组件中的波纹。

开发文档	API
消息条(Snackbars)	v-snackbar

在 v-snackbar 组件的 actions 槽中使用时，以下属性会被修改：

属性	值
slim	true
ripple	false
variant	text

工具栏和应用栏

v-toolbar 组件将text变体应用于所有 v-btn 组件。此外，v-toolbar-items 组件用于创建填充工具栏高度的一组按钮。

开发文档	API
Toolbars(工具栏)	v-toolbar

INFO

v-app-bar 组件使用 v-toolbar内部。应用全局默认值时，必须以 v-toolbar 组件为目标。

export default createVuetify({
  defaults: {
    VToolbar: {
      VBtn: { variant: 'flat' },
    },
  },
})

在 v-toolbar 或 v-toolbar-items 组件中使用时，会修改以下属性：

属性	值
height	由 v-toolbar-items 提供
variant	text

无障碍

v-btn 组件是本机 button 元素的扩展，支持所有相同的辅助功能。

ARIA 属性

默认情况下， v-btn 组件包含相关的 WAI-ARIA属性以增强可访问性。该组件会自动分配 type="button" 属性，这表明其作为辅助技术按钮的用途。

快捷键

v-btn 组件本身是可聚焦的，并响应键盘事件，例如按

Enter

或

Space

键来触发按钮的操作。这可确保用户仅使用键盘即可导航您的应用程序并与之交互。

可访问标签

使用 v-icon 时在 v-btn 组件中（例如，使用 icon 属性），为屏幕阅读器用户提供文本替代方案至关重要。您可以添加带有描述性标签的 aria-label 属性，以确保所有用户都清楚该按钮的用途。

<v-btn
  aria-label="Refresh"
  icon="mdi-refresh"
></v-btn>

触屏目标大小

确保您的按钮具有足够的触摸目标尺寸，尤其是在触摸设备上。对于有运动障碍的用户或使用小屏幕的用户来说，较大的触摸目标可以提高按钮的可用性。您可以使用 size 属性的 large 或 x-large 值来增加按钮大小：

<v-btn size="large">
  Large Button
</v-btn>

<v-btn size="x-large">
  Extra Large Button
</v-btn>