TextField 文本框

文本框组件允许用户在页面中输入文本,通常用于表单和对话框。

使用方法

按需导入组件:

import 'mdui/components/text-field.js';

按需导入组件的 TypeScript 类型:

import type { TextField } from 'mdui/components/text-field.js';

使用示例:

<mdui-text-field label="Text Field"></mdui-text-field>

示例

形状

通过 variant 属性设置文本框的形状。

辅助文本

通过 label 属性设置文本框上方的标签文本。

通过 placeholder 属性设置无值时的占位文本。

通过 helper 属性设置文本框底部的帮助文本。也可以使用 helper slot 来设置帮助文本。添加 helper-on-focus 属性则仅在输入框聚焦时显示帮助文本。

可清空

添加 clearable 属性后,当文本框有值时,会在右侧添加清空按钮。

文本右对齐

添加 end-aligned 属性可以使文本右对齐。

前后文本及图标

通过设置 iconend-icon 属性,可以在文本框的左侧和右侧添加 Material Icons 图标。也可以通过 iconend-icon slot 在文本框的左侧和右侧添加元素。

通过设置 prefixsuffix 属性,可以在文本框的左侧和右侧添加文本。也可以通过 prefixsuffix slot 在文本框的左侧和右侧添加文本元素。这些文本只有在文本框聚焦或有值时才会显示。

只读模式

通过添加 readonly 属性,可以将文本框设置为只读模式。

禁用状态

通过添加 disabled 属性,可以禁用文本框。

多行文本框

通过 rows 属性,可以设置多行文本框的行数。

也可以添加 autosize 属性,使文本框能根据输入内容的长度自动调整高度。通过 min-rowsmax-rows 属性,可以指定自动调整高度时的最小行数和最大行数。

字数统计

当通过 maxlength 属性设置了最大字数时,可以添加 counter 属性在文本框下方显示字数统计。

密码框

type="password" 时,添加 toggle-password 属性可以在文本框右侧添加切换密码可见性的按钮。

API

属性

HTML 属性JavaScript 属性Reflect类型默认值
variantvariant'filled' | 'outlined''filled'

文本框的形状。默认为 filled。可选值包括:

  • filled:带背景色的文本框,视觉效果较强
  • outlined:带边框的文本框,视觉效果较弱
typetype'text' | 'number' | 'password' | 'url' | 'email' | 'search' | 'tel' | 'hidden' | 'date' | 'datetime-local' | 'month' | 'time' | 'week''text'

文本框输入类型。默认为 text。可选值包括:

  • text:默认值。文本字段
  • number:只能输入数字。拥有动态键盘的设备上会显示数字键盘
  • password:用于输入密码,其值会被遮盖
  • url:用于输入 URL,会验证 URL 格式。在支持动态键盘的设备上有相应的键盘
  • email:用于输入邮箱地址,会验证邮箱格式。在支持动态键盘的设备上有相应的键盘
  • search:用于搜索框。拥有动态键盘的设备上的回车图标会变成搜索图标
  • tel:用于输入电话号码。拥有动态键盘的设备上会显示电话数字键盘
  • hidden:隐藏该控件,但其值仍会提交到服务器
  • date:输入日期的控件(年、月、日,不包括时间)。在支持的浏览器激活时打开日期选择器或年月日的数字滚轮
  • datetime-local:输入日期和时间的控件,不包括时区。在支持的浏览器激活时打开日期选择器或年月日的数字滚轮
  • month:输入年和月的控件,没有时区
  • time:用于输入时间的控件,不包括时区
  • week:用于输入以年和周数组成的日期,不带时区
namenamestring''

文本框名称,将与表单数据一起提交

valuevaluestring''

文本框的值,将与表单数据一起提交

defaultValuestring''

默认值。在重置表单时,将重置为该默认值。该属性只能通过 JavaScript 属性设置

labellabelstring-

标签文本

placeholderplaceholderstring-

占位符文本

helperhelperstring-

文本框底部的帮助文本。也可以通过 slot="helper" 设置

helper-on-focushelperOnFocusbooleanfalse

是否仅在获得焦点时,显示底部的帮助文本

clearableclearablebooleanfalse

是否可清空文本框内容

clear-iconclearIconstring-

可清空文本框时,显示在文本框右侧的清空按钮的 Material Icons 图标名。也可以通过 slot="clear-icon" 设置

end-alignedendAlignedbooleanfalse

是否将文本右对齐

prefixprefixstring-

文本框的前缀文本。只在文本框聚焦或有值时显示。也可以通过 slot="prefix" 设置

suffixsuffixstring-

文本框的后缀文本。只在文本框聚焦或有值时显示。也可以通过 slot="suffix" 设置

iconiconstring-

文本框的前缀图标的 Material Icons 图标名。也可以通过 slot="icon" 设置

end-iconendIconstring-

文本框的后缀图标的 Material Icons 图标名。也可以通过 slot="end-icon" 设置

error-iconerrorIconstring-

表单字段验证失败时,显示在文本框右侧的 Material Icons 图标名。也可以通过 slot="error-icon" 设置

formformstring-

关联的 <form> 元素。此属性值应为同一页面中的一个 <form> 元素的 id

如果未指定此属性,则该元素必须是 <form> 元素的子元素。通过此属性,你可以将元素放置在页面的任何位置,而不仅仅是 <form> 元素的子元素。

readonlyreadonlybooleanfalse

是否为只读模式

disableddisabledbooleanfalse

是否禁用输入框

requiredrequiredbooleanfalse

提交表单时,是否必须填写该字段

rowsrowsnumber-

文本框的固定显示行数

autosizeautosizebooleanfalse

是否根据输入内容自动调整文本框高度

min-rowsminRowsnumber-

autosizetrue 时,文本框的最小行数

max-rowsmaxRowsnumber-

autosizetrue 时,文本框的最大行数

minlengthminlengthnumber-

允许输入的最小字符数

maxlengthmaxlengthnumber-

允许输入的最大字符数

countercounterbooleanfalse

是否显示字数统计,只在 maxlength 被指定时有效

minminnumber-

typenumber 时,允许输入的最小数值

maxmaxnumber-

typenumber 时,允许输入的最大数值

stepstepnumber-

typenumber 时,数值增减的步长

patternpatternstring-

用于表单验证的正则表达式

toggle-passwordtogglePasswordbooleanfalse

typepassword 时,设置此属性会添加一个切换按钮,用于在明文和密文之间切换

show-password-iconshowPasswordIconstring-

密码切换按钮的 Material Icons 图标,当密码为明文时显示。也可以通过 slot="show-password-icon" 设置

hide-password-iconhidePasswordIconstring-

密码切换按钮的 Material Icons 图标,当密码为密文时显示。也可以通过 slot="hide-password-icon" 设置

autocapitalizeautocapitalize'none' | 'sentences' | 'words' | 'characters'-

iOS 的非标准属性,用于控制文本首字母是否自动大写。在 iOS5 及以后的版本上有效。可选值包括:

  • none:禁用首字母大写
  • sentences:句子首字母大写
  • words:单词首字母大写
  • characters:所有字母大写
autocorrectautocorrectstring-

input 元素的 autocorrect 属性

autocompleteautocomplete'off' | 'on'-

是否使用浏览器的自动填充功能。可选值包括:

  • off:禁用浏览器的自动填充,使用者必须输入他们想要输入的所有内容。或者网页提供了自己的自动填充方法
  • on:浏览器根据用户之前输入的内容或者习惯,在用户输入的时候给出相应输入提示
enterkeyhintenterkeyhint'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'-

input 元素的 enterkeyhint 属性,用于定制虚拟键盘上的 Enter 键的显示文本或图标。具体显示效果取决于用户使用的设备和语言。可选值包括:

  • enter:插入新行
  • done:完成输入,关闭虚拟键盘
  • go:导航到输入文本的目标
  • next:移动到下一个输入项
  • previous:移动到上一个输入项
  • search:导航到搜索结果
  • send:发送文本信息
spellcheckspellcheckbooleanfalse

是否启用拼写检查

inputmodeinputmode'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'-

input 元素的 inputmode 属性,用于定制虚拟键盘的类型。可选值包括:

  • none:无虚拟键盘。在需要实现自己的键盘输入控件时很有用
  • text:标准文本输入键盘
  • decimal:小数输入键盘,除了数字之外可能会有小数点 . 或者千分符逗号 ,
  • numeric:显示 0-9 的数字键盘
  • tel:手机数字键盘,包含 0-9 数字、星号 * 或者井号 #
  • search:为搜索输入优化的虚拟键盘,提交按钮通常会显示 search 或者 “搜索”
  • email:为邮件地址输入优化的虚拟键盘,通常会有 @ . 等键
  • url:为 URL 输入优化的虚拟键盘,通常会有 . / # 等键
validityValidityState-

表单验证状态对象,具体参见 ValidityState

validationMessagestring-

如果表单验证未通过,此属性将包含提示信息。如果验证通过,此属性将为空字符串

valueAsNumbernumber-

获取当前值,并转换为 number 类型;或设置一个 number 类型的值。 如果值无法被转换为 number 类型,则会返回 NaN

autofocusautofocusbooleanfalse

是否在页面加载完成后自动获取焦点

tabindextabIndexnumber-

元素在使用 Tab 键切换焦点时的顺序

方法

名称参数返回值
select
void

选中文本框中的文本

setSelectionRange
  • start: number
  • end: number
  • direction: 'forward' | 'backward' | 'none'
void

选中文本框中特定范围的内容

setRangeText
  • replacement: string
  • start: number
  • end: number
  • selectMode: 'select' | 'start' | 'end' | 'preserve'
void

将文本框中特定范围的文本替换为新的文本

checkValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

reportValidity
boolean

检查表单字段是否通过验证。如果未通过,返回 false 并触发 invalid 事件;如果通过,返回 true

如果验证未通过,还会在组件上显示验证失败的提示。

setCustomValidity
  • message: string
void

设置自定义的错误提示文本。只要这个文本不为空,就表示字段未通过验证

click
void

模拟鼠标点击元素

focus
  • options: FocusOptions (可选)
void

将焦点设置到当前元素。

可以传入一个对象作为参数,该对象的属性包括:

  • preventScroll:默认情况下,元素获取焦点后,页面会滚动以将该元素滚动到视图中。如果不希望页面滚动,可以将此属性设置为 true
blur
void

移除当前元素的焦点

事件

名称
focus

获得焦点时触发

blur

失去焦点时触发

change

在文本框的值变更,且失去焦点时触发

input

在文本框的值变更时触发

invalid

表单字段验证不通过时触发

clear

在点击由 clearable 属性生成的清空按钮时触发。可以通过调用 event.preventDefault() 阻止清空文本框

Slots

名称
icon

左侧图标

end-icon

右侧图标

error-icon

验证失败状态的右侧图标

prefix

左侧文本

suffix

右侧文本

clear-button

清空按钮

clear-icon

清空按钮中的图标

toggle-password-button

密码显示状态切换按钮

show-password-icon

显示密码状态下,密码显示状态切换按钮中的图标

hide-password-icon

隐藏密码状态下,密码显示状态切换按钮中的图标

helper

底部的帮助文本

CSS Parts

名称
container

文本框容器

icon

左侧图标

end-icon

右侧图标

error-icon

验证失败状态的右侧图标

prefix

左侧文本

suffix

右侧文本

label

上方的标签文本

input

内部的 <input><textarea> 元素

clear-button

清空按钮

clear-icon

清空按钮中的图标

toggle-password-button

密码显示状态切换按钮

show-password-icon

显示密码状态下,密码显示状态切换按钮中的图标

hide-password-icon

隐藏密码状态下,密码显示状态切换按钮中的图标

supporting

底部辅助信息容器,包括 helper、error、counter

helper

底部的帮助文本

error

底部的错误描述文本

counter

底部右侧的字数统计

MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
概述 安装 快速入门 TypeScript 支持 IDE 支持 本地化 常见问题
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
React Vue Angular
组件
Button 按钮ButtonIcon 图标按钮Fab 浮动操作按钮SegmentedButton 分段按钮Chip 纸片Card 卡片Checkbox 复选框Radio 单选框Switch 开关切换Slider 滑块RangeSlider 范围滑块List 列表Collapse 折叠面板Tabs 选项卡Dropdown 下拉组件Menu 菜单Select 选择框TextField 文本框LinearProgress 线性进度指示器CircularProgress 圆形进度指示器Dialog 对话框Divider 分割线Avatar 头像Badge 徽标Icon 图标Tooltip 工具提示Snackbar 消息条NavigationBar 底部导航栏NavigationDrawer 侧边抽屉栏NavigationRail 侧边导航栏BottomAppBar 底部应用栏TopAppBar 顶部应用栏Layout 布局
工具函数
jq 工具库 dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
独立包
@mdui/icons 图标组件库