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 属性设置文本框的形状。

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

<br/><br/>

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

源码

辅助文本

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

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

源码

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

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

源码

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

Supporting text

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

<mdui-text-field label="Text Field">
  <span slot="helper" style="color: blue">Supporting text</span>
</mdui-text-field>

<mdui-text-field label="Text Field" helper="Supporting text" helper-on-focus></mdui-text-field>

源码

可清空

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

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

源码

文本右对齐

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

<mdui-text-field end-aligned label="Text Field" value="Input Text"></mdui-text-field>

源码

前后文本及图标

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

<mdui-text-field icon="search" end-icon="mic" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field label="Text Field">
  <mdui-button-icon slot="icon" icon="search"></mdui-button-icon>
  <mdui-button-icon slot="end-icon" icon="mic"></mdui-button-icon>
</mdui-text-field>

源码

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

$ /100

<mdui-text-field prefix="$" suffix="/100" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field label="Text Field">
  <span slot="prefix" style="color: blue">$</span>
  <span slot="suffix" style="color: blue">/100</span>
</mdui-text-field>

源码

只读模式

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

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

源码

禁用状态

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

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

源码

多行文本框

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

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

源码

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

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

<br/><br/>

<mdui-text-field autosize min-rows="2" max-rows="5" label="Text Field"></mdui-text-field>

源码

字数统计

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

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

源码

密码框

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

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

源码

API

属性

HTML 属性	JavaScript 属性	类型	默认值
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
文本框的形状。默认为 `filled`。可选值包括： `filled`：带背景色的文本框，视觉效果较强 `outlined`：带边框的文本框，视觉效果较弱
`type`	`type`	`'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`：用于输入以年和周数组成的日期，不带时区
`name`	`name`	`string`	`''`
文本框名称，将与表单数据一起提交
`value`	`value`	`string`	`''`
文本框的值，将与表单数据一起提交
	`defaultValue`	`string`	`''`
默认值。在重置表单时，将重置为该默认值。该属性只能通过 JavaScript 属性设置
`label`	`label`	`string`	-
标签文本
`placeholder`	`placeholder`	`string`	-
占位符文本
`helper`	`helper`	`string`	-
文本框底部的帮助文本。也可以通过 `slot="helper"` 设置
`helper-on-focus`	`helperOnFocus`	`boolean`	`false`
是否仅在获得焦点时，显示底部的帮助文本
`clearable`	`clearable`	`boolean`	`false`
是否可清空文本框内容
`clear-icon`	`clearIcon`	`string`	-
可清空文本框时，显示在文本框右侧的清空按钮的 Material Icons 图标名。也可以通过 `slot="clear-icon"` 设置
`end-aligned`	`endAligned`	`boolean`	`false`
是否将文本右对齐
`prefix`	`prefix`	`string`	-
文本框的前缀文本。只在文本框聚焦或有值时显示。也可以通过 `slot="prefix"` 设置
`suffix`	`suffix`	`string`	-
文本框的后缀文本。只在文本框聚焦或有值时显示。也可以通过 `slot="suffix"` 设置
`icon`	`icon`	`string`	-
文本框的前缀图标的 Material Icons 图标名。也可以通过 `slot="icon"` 设置
`end-icon`	`endIcon`	`string`	-
文本框的后缀图标的 Material Icons 图标名。也可以通过 `slot="end-icon"` 设置
`error-icon`	`errorIcon`	`string`	-
表单字段验证失败时，显示在文本框右侧的 Material Icons 图标名。也可以通过 `slot="error-icon"` 设置
`form`	`form`	`string`	-
关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
`readonly`	`readonly`	`boolean`	`false`
是否为只读模式
`disabled`	`disabled`	`boolean`	`false`
是否禁用输入框
`required`	`required`	`boolean`	`false`
提交表单时，是否必须填写该字段
`rows`	`rows`	`number`	-
文本框的固定显示行数
`autosize`	`autosize`	`boolean`	`false`
是否根据输入内容自动调整文本框高度
`min-rows`	`minRows`	`number`	-
`autosize` 为 `true` 时，文本框的最小行数
`max-rows`	`maxRows`	`number`	-
`autosize` 为 `true` 时，文本框的最大行数
`minlength`	`minlength`	`number`	-
允许输入的最小字符数
`maxlength`	`maxlength`	`number`	-
允许输入的最大字符数
`counter`	`counter`	`boolean`	`false`
是否显示字数统计，只在 `maxlength` 被指定时有效
`min`	`min`	`number`	-
当 `type` 为 `number` 时，允许输入的最小数值
`max`	`max`	`number`	-
当 `type` 为 `number` 时，允许输入的最大数值
`step`	`step`	`number`	-
`type` 为 `number` 时，数值增减的步长
`pattern`	`pattern`	`string`	-
用于表单验证的正则表达式
`toggle-password`	`togglePassword`	`boolean`	`false`
`type` 为 `password` 时，设置此属性会添加一个切换按钮，用于在明文和密文之间切换
`show-password-icon`	`showPasswordIcon`	`string`	-
密码切换按钮的 Material Icons 图标，当密码为明文时显示。也可以通过 `slot="show-password-icon"` 设置
`hide-password-icon`	`hidePasswordIcon`	`string`	-
密码切换按钮的 Material Icons 图标，当密码为密文时显示。也可以通过 `slot="hide-password-icon"` 设置
`autocapitalize`	`autocapitalize`	`'none' \| 'sentences' \| 'words' \| 'characters'`	-
iOS 的非标准属性，用于控制文本首字母是否自动大写。在 iOS5 及以后的版本上有效。可选值包括： `none`：禁用首字母大写 `sentences`：句子首字母大写 `words`：单词首字母大写 `characters`：所有字母大写
`autocorrect`	`autocorrect`	`string`	-
`input` 元素的 `autocorrect` 属性
`autocomplete`	`autocomplete`	`string`	-
`input` 元素的 `autocomplete` 属性
`enterkeyhint`	`enterkeyhint`	`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`	-
`input` 元素的 `enterkeyhint` 属性，用于定制虚拟键盘上的 Enter 键的显示文本或图标。具体显示效果取决于用户使用的设备和语言。可选值包括： `enter`：插入新行 `done`：完成输入，关闭虚拟键盘 `go`：导航到输入文本的目标 `next`：移动到下一个输入项 `previous`：移动到上一个输入项 `search`：导航到搜索结果 `send`：发送文本信息
`spellcheck`	`spellcheck`	`boolean`	`false`
是否启用拼写检查
`inputmode`	`inputmode`	`'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`	-
`input` 元素的 `inputmode` 属性，用于定制虚拟键盘的类型。可选值包括： `none`：无虚拟键盘。在需要实现自己的键盘输入控件时很有用 `text`：标准文本输入键盘 `decimal`：小数输入键盘，除了数字之外可能会有小数点 `.` 或者千分符逗号 `,` `numeric`：显示 0-9 的数字键盘 `tel`：手机数字键盘，包含 0-9 数字、星号 `*` 或者井号 `#` 键 `search`：为搜索输入优化的虚拟键盘，提交按钮通常会显示 `search` 或者 “搜索” `email`：为邮件地址输入优化的虚拟键盘，通常会有 `@ .` 等键 `url`：为 URL 输入优化的虚拟键盘，通常会有 `. / #` 等键
	`validity`	`ValidityState`	-
表单验证状态对象，具体参见 `ValidityState`
	`validationMessage`	`string`	-
如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
	`valueAsNumber`	`number`	-
获取当前值，并转换为 `number` 类型；或设置一个 `number` 类型的值。如果值无法被转换为 `number` 类型，则会返回 `NaN`。
`autofocus`	`autofocus`	`boolean`	`false`
是否在页面加载完成后自动获取焦点
`tabindex`	`tabIndex`	`number`	-
元素在使用 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`
底部右侧的字数统计

Tabs 选项卡

Tooltip 工具提示