Field 输入框/表单项

介绍

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

导入

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>

多行文字

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

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`
rightArrowProps	右边箭头的自定义属性	`IconProps`	-	-

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	清除当前条目的校验状态	无

主题变量

名称	类型	默认值	说明
FieldBackgroundColor	string	`'background.cell'`	表单项背景颜色
FieldPaddingVertical	number	`16`	表单项垂直内边距
FieldPaddingHorizontal	number	`20`	表单项水平内边距
FieldBorderBottomWidth	number	`1`	表单项底部边框宽度
FieldBorderBottomColor	string	`'border.cell'`	表单项底部边框颜色
FieldVerticalGap	number	`20`	垂直布局下表单项间距
FieldRequiredMark	number	`28`	必填标记大小
FieldRequiredMarkPaddingVertical	number	`8`	必填标记垂直内边距
FieldRequiredMarkMarginHorizontal	number	`8`	必填标记水平外边距
FieldLabelMarginRight	number	`20`	标签右侧外边距
FieldLabelFontSize	number	`28`	标签字体大小
FieldLabelPaddingVertical	number	`8`	标签垂直内边距
FieldInputPaddingVertical	number	`0`	输入框垂直内边距
FieldInputPaddingHorizontal	number	`0`	输入框水平内边距
FieldErrorMessageFontSize	number	`24`	错误信息字体大小
FieldErrorMessageColor	string	`'danger'`	错误信息颜色
FieldErrorMessageMarginTop	number	`12`	错误信息顶部外边距
FieldWordLimitTextFontSize	number	`24`	字数统计字体大小
FieldWordLimitTextColor	string	`'text.second'`	字数统计颜色
FieldWordLimitTextWidth	number	`'100%'`	字数统计宽度
FieldWordLimitTextTextAlign	string	`'right'`	字数统计对齐方式
FieldClearIconWidth	number	`60`	清除图标宽度
FieldPressedColor	string	`'pressed.white'`	按下时颜色
FieldRightArrowSize	number	`30`	右侧箭头大小
FieldErrorIconSize	number	`40`	错误图标大小
FieldErrorIcon	string	`'prompt'`	错误图标
FieldLabelColor	string	`'text'`	标签颜色
FieldLabelDisableColor	string	`'grey'`	标签禁用颜色
FieldLabelFlex	number	`2`	标签flex占比
FieldInputFlex	number	`5`	输入框flex占比
FieldInputColor	string	`'text'`	输入框颜色
FieldInputDisableColor	string	`'grey'`	输入框禁用颜色
FieldPlaceholderTextColor	string	`'text.second'`	占位符颜色
FieldErrorTextColor	string	`'danger'`	错误文本颜色
FieldResetErrorOnClick	boolean	`true`	点击是否重置错误状态
FieldFieldStyle	object	`{}`	表单项样式
FieldActiveFieldStyle	object	`{}`	激活表单项样式
FieldErrorFieldStyle	object	`{}`	错误表单项样式
FieldLabelStyle	object	`{}`	标签样式
FieldInputStyle	object	`{}`	输入框样式
FieldActiveInputStyle	object	`{}`	激活输入框样式
FieldErrorIconProps	object	`{}`	错误图标属性

Field 输入框/表单项 ​

介绍 ​

导入 ​

用法 ​

基础用法 ​

自定义类型 ​

禁用状态 ​

错误提示 ​

带清除按钮 ​

自定义样式 ​

输入文本右对齐+后缀 ​

插入按钮 ​

添加图标 ​

多行文字 ​

显示字数统计 ​

API 参考 ​

Field ​

Props ​

Events ​

Slots ​

Methods ​

主题变量 ​