Skip to content

Field 输入框/表单项 ​

介绍 ​

输入框用于用户输入或编辑文字内容,同时也作为表单项使用,可以搭配 Form 组件实现表单相关功能。

导入 ​

js
import Field from '@/components/form/Field.vue'

用法 ​

基础用法 ​

vue
<template>
  <Field v-model="value1" label="文本" placeholder="请输入文本" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value1 = ref('');
</script>

自定义类型 ​

支持多种输入类型,如整数、小数、电话、邮箱和密码等。

vue
<template>
  <Field v-model="value3" label="整数" type="number" placeholder="请输入整数" />
  <Field v-model="value4" label="数字" type="decimal" placeholder="请输入数字(小数)" />
  <Field v-model="value5" label="电话" type="tel" placeholder="请输入电话" />
  <Field v-model="value6" label="邮箱" type="email" placeholder="请输入邮箱" />
  <Field v-model="value11" label="密码" type="password" placeholder="请输入密码" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value3 = ref('');
const value4 = ref('');
const value5 = ref('');
const value6 = ref('');
const value11 = ref('');
</script>

禁用状态 ​

可以设置只读或禁用状态。

vue
<template>
  <Field v-model="value8" label="只读" readonly placeholder="输入框只读" />
  <Field v-model="value1" label="禁用" disabled placeholder="输入框已禁用" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value8 = ref('只读的内容');
const value1 = ref('');
</script>

错误提示 ​

可以设置必填标识和错误提示。

vue
<template>
  <Field v-model="value6" label="用户名" required showRequiredBadge placeholder="请输入用户名" error />
  <Field v-model="value7" label="用户名" required showRequiredBadge placeholder="请输入用户名" errorMessage="请输入用户名" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value6 = ref('');
const value7 = ref('');
</script>

带清除按钮 ​

可以添加清除按钮,方便用户快速清空输入内容。

vue
<template>
  <Field v-model="value18" clearButton clearButtonMode="unless-editing" placeholder="请输入文字" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value18 = ref('我是文字,点击按钮清除');
</script>

自定义样式 ​

可以自定义各种样式,包括无标签、自定义标签与输入框宽度占比等。

vue
<template>
  <Field v-model="value12" placeholder="无左侧标签" />
  <Field v-model="value12" label="我是标签我是标签我是标签" placeholder="自定义标签与输入框宽度占比" :labelFlex="2" :inputFlex="3" />
  <Field v-model="value17" label="无冒号" :colon="false" placeholder="请输入文本" />
  <FlexCol :padding="10" :gap="20">
    <Field v-model="value12" placeholder="自定义样式1" :fieldStyle="{
      paddingVertical: '10rpx',
      paddingHorizontal: '20rpx',
      borderBottomColor: themeContext.resolveThemeColor('border.input'),
      borderBottomWidth: '4rpx',
      backgroundColor: themeContext.resolveThemeColor('white'),
    }" :activeFieldStyle="{
      borderBottomColor: themeContext.resolveThemeColor('primary'),
    }" />
  </FlexCol>
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';
import FlexCol from '@/components/layout/FlexCol.vue';
import { useTheme } from '@/components/theme/ThemeDefine';

const value12 = ref('');
const value17 = ref('');
const themeContext = useTheme();
</script>

输入文本右对齐+后缀 ​

可以设置输入文本右对齐并添加后缀。

vue
<template>
  <Field
    v-model="value13" 
    label="身高"
    :colon="false"
    type="number"
    inputAlign="right"
    placeholder="请输入身高"
  > 
    <template #suffix> 
      <Text :width="30" align="right" color="black" text="cm" />
    </template>
  </Field>
  <Field
    v-model="value14" 
    label="体重"
    :colon="false"
    type="number"
    inputAlign="right"
    placeholder="请输入体重"
  >
    <template #suffix> 
      <Text :width="30" align="right" color="black" text="kg" />
    </template>
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';
import Text from '@/components/basic/Text.vue';

const value13 = ref('');
const value14 = ref('');
</script>

插入按钮 ​

可以在输入框中插入按钮,例如发送验证码按钮。

vue
<template>
  <Field
    v-model="value6" 
    label=""
    required
    center
    placeholder="请输入短信验证码"
  >
    <template #rightButton> 
      <Button size="small" type="primary" @click="onClick">发送验证码</Button>
    </template>
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';
import Button from '@/components/basic/Button.vue';

function onClick() {
  uni.showToast({
    title: '点击了',
    icon: 'none',
  });
}

const value6 = ref('');
</script>

添加图标 ​

可以在输入框中添加图标,增强视觉效果。

vue
<template>
  <Field
    v-model="value15" 
    center
    placeholder="请输入手机号"
  >
    <template #leftIcon> 
      <Icon icon="pad" :innerStyle="{ marginRight: '20rpx' }" />        
    </template>
  </Field>
  <Field
    v-model="value16" 
    center
    placeholder="请输入短信验证码"
  >
    <template #leftIcon> 
      <Icon icon="lock" :innerStyle="{ marginRight: '20rpx' }" />        
    </template>
    <template #rightButton> 
      <Button size="small" type="primary" @click="onClick">发送验证码</Button>
    </template>
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';
import Icon from '@/components/basic/Icon.vue';
import Button from '@/components/basic/Button.vue';

function onClick() {
  uni.showToast({
    title: '点击了',
    icon: 'none',
  });
}

const value15 = ref('');
const value16 = ref('');
</script>

标签输入 ​

设置 tags 属性后,输入框会以标签形式展示内容。用户输入文字后按确认键即可添加标签,点击标签的关闭按钮可删除标签。标签之间默认使用 , 连接,可通过 tagJoinType 自定义分隔符。

vue
<template>
  <Field v-model="value19" label="标签" tags placeholder="输入后按确认键添加" />
  <Field v-model="value20" label="自定义分隔符" tags tagJoinType="|" placeholder="使用 | 分隔标签" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value19 = ref('标签1,标签2,标签3');
const value20 = ref('苹果|香蕉|葡萄');
</script>

modelValue 的值为标签通过分隔符连接后的字符串,例如 "标签1,标签2,标签3"。

多行文字 ​

可以设置为多行文本输入模式。

vue
<template>
  <Field v-model="value9" label="多行文字" multiline placeholder="请输入" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value9 = ref('我发现很多混得不好的人看得都很开。也不知道他们是因为看得透彻而不屑于世俗的成功,还是因为不成功而不得不看得开。');
</script>

显示字数统计 ​

可以显示输入内容的字数统计。

vue
<template>
  <Field v-model="value10" label="多行文字" multiline placeholder="请输入" showWordLimit :maxLength="100" />
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';

const value10 = ref('殷勤花下同携手。更尽杯中酒。美人不用敛蛾眉。');
</script>

API 参考 ​

Field ​

输入框组件,同时也作为表单项使用。

Props ​

名称说明类型必填默认值
modelValue
绑定值
any-undefined
label输入框左侧文本string-''
name名称,作为提交表单时的标识符string--
touchable是否可点击,可以作为一个纯点击条目boolean-false
type输入框类型'text'|'tel'|'number'|'password'|'email'|'decimal'-'text'
maxLength输入的最大字符数number-100
placeholder输入框占位提示文字string--
disabled是否禁用输入框boolean-false
readonly是否只读boolean-false
center是否内容垂直居中boolean-true
colon是否在 label 后面添加冒号boolean-true
required是否必填boolean-false
multiline多行文字boolean-false
autoHeight多行文字下是否自动调整高度boolean-false
showRequiredBadge是否显示表单必填星号boolean-true
clearButton是否启用清除图标boolean-false
clearButtonProps清除图标的自定义属性IconProps--
clearButtonMode清除图标的显示模式'always'|'while-editing'|'unless-editing'-'always'
labelWidth左侧文本的宽度string|number--
labelAlign左侧文本对齐'left'|'center'|'right'-'left'
labelPosition左侧文本的位置'top'|'left'-'left'
labelFlex左侧文本的flex占比number--
inputFlex输入框的flex占比number-5
labelStyle左侧文本的样式TextStyle--
labelColor左侧文本的颜色string-'text'
labelDisableColor左侧文本的禁用颜色string-'grey'
inputStyle输入框样式TextStyle--
activeInputStyle激活时的外壳样式TextStyle--
inputColor输入框颜色string-'text'
inputAlign输入框文本对齐'left'|'center'|'right'-'left'
inputDisableColor输入框禁用颜色string-'grey'
fieldStyle外壳样式ViewStyle--
activeFieldStyle激活时的外壳样式ViewStyle--
errorFieldStyle错误时的外壳样式ViewStyle--
errorTextColor错误时的文字颜色string-'danger'
placeholderTextColor文本框水印文字颜色string-'text.second'
formatter输入内容格式化函数(text: string) => string--
formatTrigger格式化函数触发的时机'blur'|'input'-'input'
validateTrigger设置字段校验的时机'blur'|'change'|'submit'-'submit'
error是否将输入内容标红boolean-false
errorIcon错误提示的图标string-'prompt'
errorIconProps错误提示图标的自定义属性IconProps--
errorMessage底部错误提示文案string--
resetErrorOnClick点击输入框是否重置错误状态boolean-true
showWordLimit是否显示字数统计boolean-false
showLabel是否显左边标题boolean-true
showRightArrow是否显右边箭头boolean-false
showBottomBorder是否显示底部边框boolean-true
rightArrowProps右边箭头的自定义属性IconProps--
rules当前条目的校验规则RuleItem[]--
tags是否启用标签输入模式boolean-false
tagJoinType标签输入模式下标签之间的连接符string-','

Events ​

名称说明参数
update:modelValue绑定值变化事件string
click点击事件$event
blur失去焦点事件$event
focus获得焦点事件$event
clear清除按钮点击事件$event

Slots ​

名称说明
default自定义输入内容
label自定义标签内容
leftIcon左侧图标
prefix输入框前缀
leftButton左侧按钮
control自定义控制器
suffix输入框后缀
rightButton右侧按钮
check错误图标

Methods ​

名称说明参数
focus获取输入框焦点无
blur取消输入框焦点无
clear清空输入框无
isFocused返回值表明当前输入框是否获得了焦点无
clearValidate清除当前条目的校验状态无

主题变量 ​

名称类型默认值说明
FieldBackgroundColorstring'background.cell'表单项背景颜色
FieldPaddingVerticalnumber16表单项垂直内边距
FieldPaddingHorizontalnumber20表单项水平内边距
FieldBorderBottomWidthnumber1表单项底部边框宽度
FieldBorderBottomColorstring'border.cell'表单项底部边框颜色
FieldVerticalGapnumber20垂直布局下表单项间距
FieldRequiredMarknumber28必填标记大小
FieldRequiredMarkPaddingVerticalnumber8必填标记垂直内边距
FieldRequiredMarkMarginHorizontalnumber8必填标记水平外边距
FieldLabelMarginRightnumber20标签右侧外边距
FieldLabelFontSizenumber28标签字体大小
FieldLabelPaddingVerticalnumber8标签垂直内边距
FieldInputPaddingVerticalnumber0输入框垂直内边距
FieldInputPaddingHorizontalnumber0输入框水平内边距
FieldErrorMessageFontSizenumber24错误信息字体大小
FieldErrorMessageColorstring'danger'错误信息颜色
FieldErrorMessageMarginTopnumber12错误信息顶部外边距
FieldWordLimitTextFontSizenumber24字数统计字体大小
FieldWordLimitTextColorstring'text.second'字数统计颜色
FieldWordLimitTextWidthnumber'100%'字数统计宽度
FieldWordLimitTextTextAlignstring'right'字数统计对齐方式
FieldClearIconWidthnumber60清除图标宽度
FieldPressedColorstring'pressed.white'按下时颜色
FieldRightArrowSizenumber30右侧箭头大小
FieldErrorIconSizenumber40错误图标大小
FieldErrorIconstring'prompt'错误图标
FieldLabelColorstring'text.content'标签颜色
FieldLabelDisableColorstring'grey'标签禁用颜色
FieldLabelFlexnumber2标签flex占比
FieldInputFlexnumber5输入框flex占比
FieldInputColorstring'text.content'输入框颜色
FieldInputDisableColorstring'grey'输入框禁用颜色
FieldPlaceholderTextColorstring'text.second'占位符颜色
FieldErrorTextColorstring'danger'错误文本颜色
FieldResetErrorOnClickbooleantrue点击是否重置错误状态
FieldFieldStyleobject{}表单项样式
FieldActiveFieldStyleobject{}激活表单项样式
FieldErrorFieldStyleobject{}错误表单项样式
FieldLabelStyleobject{}标签样式
FieldInputStyleobject{}输入框样式
FieldActiveInputStyleobject{}激活输入框样式
FieldErrorIconPropsobject{}错误图标属性