SwInput

SwInput 是文字輸入框：原生 <input> 的薄封裝，價值在「統一基線盒子」而非功能增強——與 SwSelect 觸發器同款盒模型（--control-height / --control-font-size / --input 邊框 / --radius），讓 SwInput / SwSelect / SwSegmented 同行混排預設等高等字號，applier 不必再手寫 input 盒子樣式。

未聲明的原生屬性（placeholder / maxlength / autocomplete / name / readonly …）與原生事件監聽自動落到內層 <input> 上（inheritAttrs: false + v-bind="$attrs"），無需逐一聲明——根是 .sw-input wrapper（承載盒樣式與尾部圖示鈕），對呼叫方的透傳行為與單根版一致。

iOS 聚焦縮放對策：iOS Safari 對 font-size < 16px 的文字輸入框聚焦時會自動放大頁面。SwInput 在觸摸設備（hover: none + pointer: coarse）下預設字號抬回 1rem，高度不變仍 32px；顯式覆蓋 --sw-input-font-size 時兩端同值生效。

基礎用法

v-model + 原生屬性透傳

加载中...
<script setup lang="ts">
const keyword = ref('')
</script>

<template>
  <SwInput v-model="keyword" placeholder="搜尋關鍵詞" maxlength="50" />
</template>

配 SwFormField（錯誤態）

錯誤文案不歸 SwInput——配 SwFormField 就近顯示；SwInput 的 error 只管 destructive 描邊 + aria-invalid：

SwFormField 簡單模式 + error 描邊 / 禁用

加载中...
<SwFormField label="郵箱" required :error="emailError">
  <SwInput v-model="email" type="email" :error="!!emailError" />
</SwFormField>

vee-validate 模式用 v-bind="field" 注入：

<SwFormField name="email" label="郵箱" v-slot="{ field, error }">
  <SwInput v-bind="field" type="email" :error="!!error" />
</SwFormField>

一鍵清除與密碼可見性

clearable 在值非空時於尾部顯示清除鈕（清空 + 聚焦回 input + emit clear）；revealable 僅對 type="password" 生效，切換明/密文（其他 type 傳了靜默忽略）。兩鈕開啟即右側常駐留位（值出現 / 清空不擠動文字），自帶觸摸熱區（sw-hit-area）與三語 aria-label：

clearable 清除 + revealable 密碼切換

加载中...
<SwInput v-model="keyword" clearable placeholder="搜尋" @clear="onCleared" />
<SwInput v-model="password" type="password" clearable revealable />

表單控件族等高混排

SwInput + SwSelect + SwSegmented 預設等高

加载中...

Props

名稱類型必填預設值說明
modelValue（v-model）string | number''受控值；輸入時 emit string（type="number" 亦 emit string，業務自轉）
type'text' | 'password' | 'search' | 'email' | 'tel' | 'url' | 'number''text'原生 type
disabledbooleanfalse禁用態
errorbooleanfalse錯誤態（destructive 描邊 + aria-invalid），布林（對齊 Vuetify）；錯誤文案配 SwFormField 顯示——SwFormField 的 error 是字串文案，聯動寫 :error="!!field.error"
clearablebooleanfalse一鍵清除鈕：值非空且未禁用時顯示；點擊=清空 + emit update:modelValue('') + emit clear + 聚焦回 input
revealablebooleanfalse密碼明/密文切換鈕，僅 type="password" 生效（其他 type 靜默忽略 + dev warn）；切換只改內部顯示，不改 type prop

其餘原生屬性一律 fallthrough 透傳，無需組件聲明。

Events

名稱攜帶說明
update:modelValuevalue: string輸入時觸發
clear—點清除鈕時觸發（在 update:modelValue('') 之後）

原生事件（focus / blur / change …）經 fallthrough 直接監聽即可。

樣式定制 Token

Token預設值作用點
--sw-input-min-heightvar(--control-height)最小高
--sw-input-padding0.25rem 0.75rem內邊距
--sw-input-bordervar(--input)描邊色
--sw-input-radiusvar(--radius)圓角
--sw-input-bgvar(--background)底色
--sw-input-colorvar(--foreground)文字色
--sw-input-font-sizevar(--control-font-size)（觸摸設備 1rem）字號
--sw-input-error-bordervar(--destructive)錯誤態描邊色
--sw-input-placeholder-colorvar(--muted-foreground)placeholder 文字色

高度 / 字號預設吃表單控件族語義 token --control-height（32px）/ --control-font-size（14px）——覆蓋這兩個 token 全站控件同步縮放，元件級 token 優先級更高。

注意事項

  • 拿原生 DOM / 命令式聚焦：根是 wrapper（$el 不再是 <input>），走 defineExpose 的 focus() / blur() / select()：inputRef.value?.focus()。
  • 錯誤文案不歸本組件：error 只管視覺描邊，文案用 SwFormField 的 error prop / vee-validate 就近顯示。
  • 多行文字不適用：本組件只封裝單行 <input>；<textarea> 場景暫用原生元素（SwTextarea 形態預留、等真實需求）。
  • 表單裡的提交按鈕對齊：SwButton 維持零樣式（不吃 --control-height），表單內按鈕由業務寫 height: var(--control-height) 與控件對齊。

相關