Admin 元件

Field

表單欄位容器。統一 label、說明、錯誤訊息排版。

安裝

Terminal

pnpm dlx shadcn-vue add @admin/field

import {  AdminField,  AdminFieldContent,  AdminFieldDescription,  AdminFieldDivider,  AdminFieldError,  AdminFieldGroup,  AdminFieldLabel,  AdminFieldLegend,  AdminFieldSet,  AdminFieldTitle,} from '@/components/admin/field'

用法

<script setup lang="ts">import { ref } from 'vue'import { AdminCheckbox } from '@/components/admin/checkbox'import {  AdminField,  AdminFieldContent,  AdminFieldDescription,  AdminFieldDivider,  AdminFieldError,  AdminFieldGroup,  AdminFieldLabel,  AdminFieldLegend,  AdminFieldSet,  AdminFieldTitle} from '@/components/admin/field'import { AdminInput } from '@/components/admin/input'import { AdminSwitch } from '@/components/admin/switch'import { AdminTextarea } from '@/components/admin/textarea'const name = ref<string | number>('王小明')const email = ref<string | number>('invalid-email')const bio = ref('')const newsletter = ref(true)const marketing = ref(false)</script><template>  <admin-field-set class="w-full max-w-md">    <admin-field-legend>個人資料</admin-field-legend>    <admin-field-group>      <admin-field orientation="vertical">        <admin-field-label>姓名</admin-field-label>        <admin-input v-model="name" placeholder="王小明" />        <admin-field-description>顯示在個人檔案上的名字。</admin-field-description>      </admin-field>      <admin-field orientation="vertical">        <admin-field-label>Email</admin-field-label>        <admin-input v-model="email" placeholder="you@example.com" type="email" is-error />        <admin-field-description>我們不會公開你的 email。</admin-field-description>        <admin-field-error>請輸入有效的 email 格式。</admin-field-error>      </admin-field>      <admin-field orientation="vertical">        <admin-field-label>自我介紹</admin-field-label>        <admin-textarea v-model="bio" placeholder="介紹一下你自己…" rows="3" />        <admin-field-description>100 字以內的簡短說明。</admin-field-description>      </admin-field>      <admin-field-divider />      <admin-field-title>通知偏好</admin-field-title>      <admin-field orientation="horizontal">        <admin-field-content>          <admin-field-label>每週電子報</admin-field-label>          <admin-field-description>每週一寄送產品更新與技術文章。</admin-field-description>        </admin-field-content>        <admin-switch v-model="newsletter" />      </admin-field>      <admin-field orientation="horizontal">        <admin-field-content>          <admin-field-label>行銷活動通知</admin-field-label>          <admin-field-description>收到限時優惠與活動邀請。</admin-field-description>        </admin-field-content>        <admin-checkbox v-model="marketing" />      </admin-field>    </admin-field-group>  </admin-field-set></template>

場景

錯誤訊息

<script setup lang="ts">import { AdminField, AdminFieldError, AdminFieldLabel } from '@/components/admin/field'import { AdminInput } from '@/components/admin/input'</script><template>  <admin-field class="w-72" orientation="vertical">    <admin-field-label>Email</admin-field-label>    <admin-input placeholder="you@example.com" is-error />    <admin-field-error>請輸入有效的 email。</admin-field-error>  </admin-field></template>

水平 Orientation

<script setup lang="ts">import { AdminField, AdminFieldDescription, AdminFieldLabel } from '@/components/admin/field'import { AdminInput } from '@/components/admin/input'</script><template>  <admin-field class="w-120" orientation="horizontal">    <admin-field-label>顯示名稱</admin-field-label>    <admin-input class="w-56" placeholder="暱稱" />    <admin-field-description>在留言區會顯示這個名字。</admin-field-description>  </admin-field></template>

API 參考

組成

<template>  <admin-field-set>    <admin-field-legend>個人資料</admin-field-legend>    <admin-field-group>      <admin-field orientation="vertical">        <admin-field-label>姓名</admin-field-label>        <admin-input v-model="name" />        <admin-field-description>顯示在個人檔案上的名字。</admin-field-description>      </admin-field>      <admin-field orientation="vertical">        <admin-field-label>Email</admin-field-label>        <admin-input v-model="email" is-error />        <admin-field-description>我們不會公開你的 email。</admin-field-description>        <admin-field-error v-if="error">{{ error }}</admin-field-error>      </admin-field>      <admin-field-divider />      <admin-field-title>通知偏好</admin-field-title>      <admin-field orientation="horizontal">        <admin-field-content>          <admin-field-label>每週電子報</admin-field-label>          <admin-field-description>每週一寄送最新消息。</admin-field-description>        </admin-field-content>        <admin-switch v-model="newsletter" />      </admin-field>    </admin-field-group>  </admin-field-set></template>

元件	角色
`admin-field-set`	表單區塊外層，對應 HTML `<fieldset>`，可巢狀使用
`admin-field-legend`	區塊標題，對應 `<legend>`，視覺上為主標題
`admin-field-group`	欄位群組容器，統一欄位間距與 `@container/field-group` 響應式斷點
`admin-field`	單一欄位容器，控制 label / 輸入欄 / 描述 / 錯誤的排版與 `orientation`
`admin-field-label`	欄位 label
`admin-field-description`	欄位輔助說明
`admin-field-error`	驗證錯誤訊息，搭配輸入欄位的 `is-error` 樣式
`admin-field-content`	在橫向欄位中包住 label + description，讓控制元件（switch / checkbox 等）對齊在右側
`admin-field-title`	群組內次標題，用於分段但不需 `legend` 語意時
`admin-field-divider`	群組內分隔線，視覺切分不同區段

admin-field

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class
`orientation`	`AdminFieldOrientation \| undefined`	—	排列方向（直向 / 橫向）

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-set

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-legend

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-group

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-label

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-content

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-description

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-error

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class
`errors`	`(string \| { message: string \| undefined; } \| undefined)[] \| undefined`	—	錯誤訊息陣列，可為字串或具 `message` 欄位之物件；單條時顯示為段落、多條時自動列表

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-title

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

Slots

名稱	Bindings	說明
`default`	`{}`	—

admin-field-divider

Props

名稱	型別	預設值	說明
`class`	`ClassValue`	—	根元素之自訂 class

更新紀錄

2026-07-07fix: 修正 description 後代 variant 並簡化 error 去重d035ecd

Dropdown Menu

點按 trigger 後彈出的選項列表；含鍵盤導航。

File Upload

多檔上傳。拖曳、驗證、File 與 URL 並存；上傳由父層監聽 upload 事件處理。