SButton <s-button>

触发一个操作或进行导航，支持 primary、secondary、tertiary 变体、图标和加载状态。 SButton 是 Shopify Polaris <s-button> web component 的带类型 Vue 3 wrapper。

import { SButton } from 'polaris-vue-elements'

最佳实践

• 使用清晰的动词作为标签。 准确说明按钮的作用，例如“保存”“编辑”或“添加标签”。使用句子大小写，省略“a”“the”等冗余词，并且不要加标点。
• tone="critical" 只用于破坏性操作。 仅当操作难以或无法撤销时才使用它；一般来说，色调应与操作的重要程度相匹配。
• 让层级一目了然。 为主要操作设置 variant="primary"，为辅助操作设置 variant="secondary"，为补充操作设置 variant="tertiary"，让商家能分辨出哪个操作最重要。
• 保持按钮位置一致。 在整个应用中将按钮放在相同的位置，让商家知道去哪里找它们。
• 为仅含图标的按钮添加标签。 如果按钮只有图标没有文字，请为其设置 accessibilityLabel，告诉屏幕阅读器用户它的作用。

<SButton icon="edit" accessibilityLabel="Edit product" />

参阅 Shopify 关于 <s-button> 的最佳实践（英文）以获取完整指南。

示例

PrimarySecondaryTertiaryCritical

LoadingDisabled

Clicked 0 times

<script setup>
import { ref } from 'vue'
import { SButton } from 'polaris-vue-elements'

const clicks = ref(0)
</script>

<template>
  <div style="display: flex; gap: 8px; flex-wrap: wrap; align-items: center;">
    <SButton variant="primary">Primary</SButton>
    <SButton variant="secondary">Secondary</SButton>
    <SButton variant="tertiary">Tertiary</SButton>
    <SButton tone="critical">Critical</SButton>
  </div>
  <div style="display: flex; gap: 8px; flex-wrap: wrap; align-items: center; margin-top: 8px;">
    <SButton loading>Loading</SButton>
    <SButton disabled>Disabled</SButton>
  </div>
  <div style="margin-top: 8px;">
    <SButton @click="clicks++">Clicked {{ clicks }} times</SButton>
  </div>
</template>

Props

Prop	类型	说明
accessibilityLabel	string	为屏幕阅读器等辅助技术描述组件用途或内容的标签。当仅凭可见内容无法清楚传达组件用途时，可用它提供额外的上下文。
command	"--auto" | "--show" | "--hide" | "--toggle" | "--copy"	设置此可点击元素被激活时 commandFor 应执行的操作。有关各组件支持的操作，请参阅相应组件的文档。 - --auto：目标组件的默认操作。 - --show：显示目标组件。 - --hide：隐藏目标组件。 - --toggle：切换目标组件。 - --copy：复制目标 ClipboardItem。
commandFor	string	应响应此组件上激活操作（例如点击）的组件 ID。有关如何控制目标的行为，请参阅 command。
disabled	boolean	禁用 Button，使其无法被点击或获得焦点。
download	string	使浏览器将链接的 URL 视为下载，并以该字符串作为文件名。下载仅适用于同源 URL 或 blob: 和 data: 协议。
href	string	要链接到的 URL。 - 如果设置，在执行 click 事件后会导航到 href 指定的位置。 - 如果设置了 commandFor，则会执行 command 而不是导航。
icon	"color" | "info" | "adjust" | "affiliate" | "airplane" | "alert-bubble" | "alert-circle" | "alert-diamond" … (553 more)	显示在按钮内部的图标，通常位于按钮文本之前。使用图标可以帮助用户快速识别按钮的操作，或提高可扫读性。接受图标库中的任意图标名称或自定义字符串标识符。
inlineSize	"auto" | "fill" | "fit-content"	Button 的显示内联宽度。 - auto：按钮尺寸取决于所在界面和上下文。 - fill：按钮占据 100% 的可用内联尺寸。 - fit-content：按钮占据容纳其内容所需的最小内联尺寸。
interestFor	string	应响应此组件上关注操作（例如悬停和聚焦）的组件 ID。
lang	string	文本内容的语言。当文本所用语言与页面其余部分不同时使用，以便屏幕阅读器等辅助技术采用正确的发音。该值应为 IANA 语言子标签注册表中的有效语言子标签。
loading	boolean	在执行后台操作期间，用加载指示器替换内容。这也会禁用 Button。
target	"auto" | "_blank" | "_self" | "_parent" | "_top"	指定在何处显示链接的 URL。
tone	"auto" | "neutral" | "critical"	组件的语义含义和配色处理。 - critical：紧急问题或破坏性操作。 - auto：根据上下文自动确定。 - neutral：无特定意图的一般信息。
type	"button" | "reset" | "submit"	Button 的行为。 - submit：表示组件充当提交按钮，即会提交最近的表单。 - button：表示组件充当普通按钮，即没有默认操作。 - reset：表示组件充当重置按钮，即会重置最近的表单（将字段恢复为默认值）。如果组件支持 href 或 commandFor/command 并且设置了其中之一，则此属性会被忽略。
variant	"auto" | "primary" | "secondary" | "tertiary"	按钮组件的视觉外观。 - auto：根据按钮组件的上下文自动确定变体。 - primary：高强调按钮，用于页面上的主操作，应谨慎使用。 - secondary：中等强调按钮，用于次要操作。 - tertiary：低强调按钮，用于不太重要的操作。

为便于阅读，上面部分类型列已被截断；完整的联合类型见库中生成的 TypeScript 类型（src/lib/generated/types.ts）。

Events

Event	类型
blur	FocusEvent
click	MouseEvent
focus	FocusEvent

在 <SButton> 上使用 @blur 形式的监听器来监听这些事件。

Slots

Slot	说明
default	按钮组件中显示的标签文本或元素，用于描述点击时将执行的操作。