指南组件

Field 字段

用于包装各种表单组件，并提供标签、描述文本、错误显示等功能的字段组件

sKy
@skiyee
Source 
<template>
  <div class="p-4 w-full">
    <SkField label="用户名">
      <SkInput placeholder="请输入用户名" />
    </SkField>
  </div>
</template>

用法

通常与 SkForm 组件配合使用，前往获取该组件更多信息

Name 标识名

配合 SkForm 使用时，name 属性是必填项，单独使用 name 属性是可选的
Prop类型默认值描述
namestring-设置字段标识名。用于表单识别、验证
<template>
  <div class="p-4 w-full">
    <SkField name="username" label="用户名">
      <SkInput placeholder="请输入用户名" />
    </SkField>
  </div>
</template>

Label 标签文本

Prop类型默认值描述
labelstring-设置字段标签文本
Slot描述
label自定义标签内容 (会使 Required属性 效果无效)
<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
const note = ref('')
</script>

<template>
  <div class="w-full p-4 flex flex-col gap-4">
    <SkField label="姓名">
      <SkInput v-model="name" placeholder="请输入您的姓名" />
    </SkField>
    <SkField>
      <template #label>
        <div class="flex items-center">
          <span>性别</span>
          <SkIcon name="i-lucide:pencil-line" clax="sk-unit:ml-4 text-danger" />
        </div>
      </template>
      <SkInput v-model="note" placeholder="备注信息（无标签字段）" />
    </SkField>
  </div>
</template>

Description 描述信息

Prop类型默认值描述
descriptionstring-设置字段描述内容文本
Slot描述
description自定义描述文本内容
<script setup lang="ts">
import { ref } from 'vue'

const username = ref('')
const apiKey = ref('')
</script>

<template>
  <div class="p-4 w-full space-y-4">
    <!-- 基础帮助文本 -->
    <SkField label="用户名" description="用户名只能包含字母、数字和下划线，长度3-20个字符">
      <SkInput v-model="username" placeholder="请输入用户名" />
    </SkField>

    <!-- 自定义帮助文本插槽 -->
    <SkField label="API密钥">
      <SkInput v-model="apiKey" placeholder="请输入API密钥" password />
      <template #description>
        <span class="text-brand">如何获取API密钥？</span>
        <span class="ml-2 text-success">查看文档</span>
      </template>
    </SkField>
  </div>
</template>

Required 必填效果

Prop类型默认值描述
requiredbooleanfalse设置字段是否显示必填效果 (只是一个展示标识，不与表单验证关联)
<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
</script>

<template>
  <div class="p-4 w-full">
    <SkField label="姓名" required>
      <SkInput v-model="name" placeholder="请输入您的姓名" />
    </SkField>
  </div>
</template>

Error 错误显示

Prop类型默认值描述
errorstring-设置字段静态错误信息（优先级高于表单验证后抛出的错误）
Slot描述
error自定义错误文本内容
<script setup lang="ts">
import { ref } from 'vue'

const email = ref('invalid-email')
const customError = ref('')
const showCustomError = ref(false)

function toggleCustomError() {
  showCustomError.value = !showCustomError.value
}
</script>

<template>
  <div class="p-4 w-full flex flex-col gap-4">
    <SkField label="邮箱" error="请输入有效的邮箱地址">
      <SkInput v-model="email" placeholder="请输入邮箱" />
    </SkField>

    <SkField label="自定义错误样式">
      <SkInput placeholder="这个字段有自定义错误样式" />
      <template #error>
        <div class="flex items-center text-danger">
          <span>🚨</span>
          <span>这是使用插槽自定义的错误信息</span>
        </div>
      </template>
    </SkField>

    <div class="mt-2">
      <SkButton size="small" @click="toggleCustomError">
        {{ showCustomError ? '清除动态错误' : '显示动态错误' }}
      </SkButton>
    </div>

    <SkField label="动态错误" :error="showCustomError ? '这是一个动态显示的错误信息' : ''">
      <SkInput v-model="customError" placeholder="输入任意内容" />
    </SkField>
  </div>
</template>

Orientation 布局方向

Prop类型默认值描述
orientation{Orientation}vertical设置布局方式
Orientation描述
vertical垂直布局
horizontal水平布局
<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
const email = ref('')
const phone = ref('')
const address = ref('')
</script>

<template>
  <div class="p-4 w-full space-y-4">
    <SkField label="姓名" orientation="vertical" description="垂直布局，标签在上方" required>
      <SkInput v-model="name" placeholder="请输入姓名" />
    </SkField>

    <SkField label="邮箱地址" orientation="vertical" description="标签和输入框垂直排列">
      <SkInput v-model="email" placeholder="请输入邮箱" />
    </SkField>

    <SkField label="手机号" orientation="horizontal" description="水平布局，标签在左侧">
      <SkInput v-model="phone" placeholder="请输入手机号" />
    </SkField>

    <SkField
      label="地址"
      orientation="horizontal"
      description="标签和输入框水平排列"
      error="一些错误信息展示"
      required
    >
      <SkInput v-model="address" placeholder="请输入地址" />
    </SkField>
  </div>
</template>

LabelWidth 标签宽度

该属性仅在 orientation="horizontal" 布局时有效
Prop类型默认值描述
labelWidthstring | number140设置标签的宽度 (如果未填写单位，默认为 rpx，否则原样输出)
<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
const mountain = ref('')
</script>

<template>
  <div class="p-4 w-full space-y-4">
    <SkField label="姓名" orientation="horizontal">
      <SkInput v-model="name" placeholder="请输入姓名" />
    </SkField>
    <SkField label="三山五岳" orientation="horizontal" label-width="100px">
      <SkInput v-model="mountain" placeholder="请输入三山五岳" />
    </SkField>
  </div>
</template>

Size 尺寸大小

Prop类型默认值描述
size{Size}medium设置被包裹组件尺寸大小 (优先级小于被包裹组件的 size 属性)
Size描述
small小型
medium中型
large大型
<script setup lang="ts">
import { ref } from 'vue'

const smallValue = ref('')
const mediumValue = ref('')
const largeValue = ref('')
</script>

<template>
  <div class="p-4 w-full space-y-6">
    <SkField label="小尺寸输入框" description="适用于紧凑的界面布局" size="small">
      <SkInput v-model="smallValue" placeholder="小尺寸输入框" size="small" />
    </SkField>
    <SkField label="中等尺寸输入框" description="默认尺寸，适用于大多数场景" size="medium">
      <SkInput v-model="mediumValue" placeholder="中等尺寸输入框" />
    </SkField>
    <SkField label="大尺寸输入框" description="适用于重要的输入字段或宽松的布局" size="large">
      <SkInput v-model="largeValue" placeholder="大尺寸输入框" size="large" />
    </SkField>
  </div>
</template>

Disabled 禁用状态

Prop类型默认值描述
disabledbooleanfalse设置字段是否禁用
<script setup lang="ts">
import { ref } from 'vue'

const isDisabled = ref(true)
const value = ref('')
</script>

<template>
  <div class="w-full p-4">
    <SkButton size="small" clax="mb-4" @click="isDisabled = !isDisabled">
      切换{{ isDisabled ? '启用' : '禁用' }}状态
    </SkButton>

    <SkField label="昵称" description="可以是圆也可以是方的" :disabled="isDisabled">
      <SkInput v-model="value" placeholder="请输入昵称" />
    </SkField>
  </div>
</template>

接口

Props

属性名类型默认值描述
namestring-详见 Name 标识名
labelstring-详见 Label 标签文本
descriptionstring-详见 Description 描述信息
requiredbooleanfalse详见 Required 必填效果
errorstring-详见 Error 错误显示
labelWidthstring | number140详见 LabelWidth 标签宽度
orientation{Orientation}'vertical'详见 Orientation 布局
size{Size}'medium'详见 Size 尺寸大小
disabledbooleanfalse详见 Disabled 禁用状态

Slots

插槽名属性描述
default-字段内容
label-自定义标签内容
description-自定义描述文本内容
error-自定义错误信息内容
点颗星星 打赏项目