SwButton

SwButton 是框架提供的基礎按鈕元件。在原生 <button> 的基礎上封裝了 loading 狀態機（含預設 spinner）、停用狀態和 icon 渲染邏輯，所有 HTML 屬性（class、style、aria-*）透過 inheritAttrs 自動透傳到原生 <button>，API 完全跟 vue idiom 對齊：標準 @click event + :loading / :disabled props。

非同步必配 :loading：SwButton 不內建節流（跟業界對齊），非同步場景用 @click event + 父元件 :loading 狀態機防 double-submit（詳見 standards/usage-review-rules.md Rule SB-001）。

基礎用法

透過標準 @click event 綁定點擊回呼。

非同步操作（必配 ）

异步 handler 期间，父组件必须管 :loading 狀態機，否则用户能在 await 期间再点 → double-submit。

停用狀態

透過 :disabled="true" 禁用按钮。停用狀態下按钮不可点击，disabled 屬性也会同步到原生 <button>，CSS :disabled 伪类选择器可正常使用。

語意類型

透過 type prop 传入語意類型，组件会输出为 data-type HTML 屬性，不內建任何顏色样式。專案透過 CSS 屬性选择器自行定義各类型的視覺風格：

<SwButton type="primary" @click="submit">提交</SwButton>
<SwButton type="danger" @click="remove">刪除</SwButton>

/* 專案自訂样式（applier CSS token） */
.sw-button[data-type="primary"] { background: var(--primary); }
.sw-button[data-type="danger"]  { background: var(--destructive); }

Form 提交按钮

透過 native-type="submit" 让 button 觸發 form submit 行为（原生 HTML5 表單驗證、Enter 鍵提交等）。

<form @submit.prevent="onLogin">
  <input v-model="username" required>
  <input v-model="password" type="password" required>
  <SwButton native-type="submit" :loading="submitting" type="primary">
    登录
  </SwButton>
</form>

图标按钮

透過 :icon prop 传入 Vue 组件作为左侧图标，loading 时會被 spinner 自動替換。

<script setup>
import { PhFloppyDisk, PhTrash } from '@phosphor-icons/vue'
</script>

<template>
  <SwButton :icon="PhFloppyDisk" @click="save" :loading="saving">保存</SwButton>
  <SwButton :icon="PhTrash" type="danger" @click="remove">刪除</SwButton>
</template>

也可以用 #icon slot（跟 :icon prop 互斥，prop 优先）：

<SwButton @click="next">
  下一步
  <template #icon-right>→</template>
</SwButton>

Loading Spinner

:loading="true" 时显示預設 spinner（約 10 行 CSS，框架功能性必需的最小視覺）。spinner 使用 1em 尺寸 + currentColor 顏色，自动跟随按钮文字大小和顏色，無需 applier 額外適配。

不滿意預設 spinner 視覺？兩種 override 方式：

1. CSS override（改顏色 / 大小 / 动画）：

.sw-button-spinner {
  border-color: #fff #fff transparent;  /* 改成白色 spinner */
  width: 1.2em;                          /* 改尺寸 */
  animation-duration: 0.5s;              /* 改動畫速度 */
}

2. #loading slot 完全替換：

<SwButton @click="upload" :loading="uploading">
  <template #loading>
    <MyCustomSpinner />
  </template>
  上传
</SwButton>

點擊埋點（:track）

:track 是 opt-in 內建點擊埋點（不傳零行為）：{ click: { event, payload } } 點擊時經 useTracker 上報，disabled / loading 期不觸發；event 限 WebSdkEvent 聯合型別（typo 被 TS 攔）。自有打點 SDK 直接用 @click（逃生艙）。業務欄位口徑與 SwLink :track 一致（同元素曝光 / 點擊欄位須一致，見 standards SL-003）。

<SwButton
  :track="{ click: { event: 'appPageitemClick', payload: {
    item_id: '123', item_type: 'video', item_name: '片名',
    parent_item_id: '', position: 1, page_key: 'home', page_name: '首頁',
  } } }"
  @click="play"
>
  播放
</SwButton>

Props

Events

Slots

注意事項

• API 是標準 vue event：<SwButton @click="fn"> 跟原生 <button @click="fn"> 一致，不再吞掉 @click。
• 异步必配 :loading：framework 不再內建節流（业界主流不做），async 期间防 double-submit 的責任由父元件管 :loading 狀態機。standards/usage-review-rules.md Rule SB-001 強制要求。
• form 提交按钮必傳 native-type="submit"：預設 'button' 不觸發 form submit。詳見 Rule SB-002。
• 纯样式 prop 不內建：size / plain / round / circle / color 等 el-button 視覺装饰 prop 都不做，applier 用 CSS class 自管（如 <SwButton class="text-sm rounded-full">）。