UIFormGroup

表單欄位容器

只負責標題、星號、警告、外框 class 與前後 slots，不綁定特定欄位元件。

一般容器

Default slot 內容

選填容器（選填）

可使用 slot-label

警告容器

warning 與 warningText

此欄位內容有誤

slot-before

自訂標題內容

Default slot 內容

slot-after

查看使用方式

<UIFormGroup label="欄位標題" star warning-text="錯誤訊息">\n  欄位內容\n</UIFormGroup>

UIFormInput

輸入框

獨立負責 v-model 與原生輸入狀態；以 status 管理 default、error、warning，並可用 size 調整高度。

Default

Warning

Readonly

Disabled

Small

查看使用方式

<UIFormInput v-model="name" placeholder="請輸入姓名" status="error" size="md" />

UIFormPassword

密碼欄位

具備顯示／隱藏密碼按鈕，支援 required、disabled、readonly 與 autocomplete。

密碼

密碼錯誤

停用密碼欄位

查看使用方式

<UIFormGroup label="密碼" star>\n  <UIFormPassword v-model="password" required />\n</UIFormGroup>

UIFormCopy

複製文字

顯示唯讀文字並提供複製按鈕，複製成功後圖示會變為勾勾。

可複製文字

停用複製文字

查看使用方式

<UIFormCopy text="可複製的文字" />

UIFormTextarea

多行輸入

支援 rows、maxlength、resize，以及 default、warning、disabled 狀態。

Default

Warning

Disabled

查看使用方式

<UIFormTextarea v-model="note" :rows="4" warning />

UIFormSelect

下拉選單

透過 options 物件陣列建立選項，支援一般、warning、disabled 狀態。

Default

Warning

Disabled

查看使用方式

<UIFormSelect v-model="location" :options="locationOptions" warning />

UIFormRadio + UIFormRadioGroup

單選選項

可手動組合單一 Radio，或用 options 產生 RadioGroup；bordered 可建立與輸入框一致的整塊點擊區域。純符號模式必須提供 aria-label。

查看使用方式

<UIFormRadio v-model="method" name="contact" value="email" label="Email" />\n<UIFormRadio v-model="enabled" name="enabled" value="yes" aria-label="啟用" />\n<UIFormRadio bordered label="Email" />\n<UIFormRadioGroup v-model="method" :options="contactOptions" />

UIFormMultiSelect

多選下拉選單

自訂多選下拉選單，預設完整顯示已選項目並將選單掛到 body，避免受到外容器裁切；支援搜尋、標籤摘要、直接輸入、底部操作、停用與警告狀態。

Default（完整顯示）

剪髮服務染髮服務燙髮服務護髮療程

最多顯示 2 個標籤

剪髮服務染髮服務+1

Warning

至少選擇一項專長

Disabled

剪髮服務護髮療程

可直接輸入文字

下拉選單底部按鈕

剪髮服務

查看使用方式

<UIFormMultiSelect
  v-model="services"
  :options="serviceOptions"
  placeholder="選擇服務項目"
  searchable
  clearable
/>

<!-- 使用摘要模式時，指定要顯示的標籤數量 -->
<UIFormMultiSelect
  v-model="services"
  :options="simpleServiceOptions"
  :max-tag-count="2"
  :searchable="false"
/>

<!-- 在欄位內輸入文字；allow-custom-value 可建立新項目 -->
<UIFormMultiSelect
  v-model="services"
  :options="simpleServiceOptions"
  editable
  allow-custom-value
/>

<!-- 下拉選單最下方的 footer slot -->
<UIFormMultiSelect v-model="services" :options="simpleServiceOptions">
  <template #footer="{ close }">
    <button type="button" @click="close">新增服務項目</button>
  </template>
</UIFormMultiSelect>

/>

UIFormCheckbox

多選選項

可獨立組合多個核取項目；bordered 可建立與輸入框一致的整塊點擊區域。不需要文字時省略 label／slot，並提供 aria-label。

查看使用方式

<UIFormCheckbox v-model="agreed" label="我同意服務條款" />\n<UIFormCheckbox v-model="enabled" aria-label="啟用通知" />\n<UIFormCheckbox bordered label="接收通知" />

UIFormMerge

合併表單欄位

以單一外框合併多個支援欄位，欄位間以左側分隔線區隔；任一項目取得焦點時，整個容器會顯示焦點狀態。

輸入框、下拉選單與按鈕

輸入框附帶單位

單位單位

日期、時間與數值

有框選項

Email電話同意條款

多選下拉選單

剪髮服務染髮服務+1

查看使用方式

<UIFormMerge>
  <UIFormDate v-model="date" />
  <UIFormTime v-model="time" />
  <UIFormNumber v-model="count" />
</UIFormMerge>

UIFormButton

輸入框旁按鈕

以 variant 選擇語意色彩，以 appearance 切換實心或外框樣式；預設為 primary 實心按鈕。

實心按鈕

外框按鈕

Disabled

範例：搜尋

查看使用方式

<UIFormButton variant="primary">主要操作</UIFormButton>
<UIFormButton variant="danger" appearance="outline">刪除資料</UIFormButton>

UIFormDate + UIFormTime + UIFormNumber + UIFormRange

日期、時間、數值與拉桿

分別封裝原生 date、time、number 與 range，保留瀏覽器輸入能力並統一樣式。

日期

時間

參與人數

造型調整幅度

40%

查看使用方式

<UIFormDate v-model="date" min="2026-08-01" />\n<UIFormRange v-model="value" :min="0" :max="100" value-suffix="%" />