TextField
TextField 涵盖 Material 3 的基础输入场景，包括辅助文本、验证、装饰内容和多行输入。
TextField 始终使用字符串模型，包括 type="number" 时也是如此。数字输入仍保留原生数字键盘、验证行为和文本形式的 input.value；将模型解析为数值由应用负责。
字段间距由外围布局负责；请保留其预期密度，不要将所有字段组统一为相同间距。labelClearance 接受 CSS 长度，用于设置局部块起始方向的间距，也可从 fieldContextKey 继承子树默认值；该间距会叠加到父级间距上。请参阅浮动标签间距指南。
标签遵循共享的 fieldLabelBehavior 默认值（floating；compact 中为 external）。可用 label-behavior 覆盖。External 模式不显示内置标签和描边缺口，不应用 labelClearance，且仅将 label 用作无障碍名称的回退值。自定义标签布局请参阅字段布局。
示例
尺寸与工具栏对齐
单行字段支持 extra-small（32px）、small（40px）和 medium（56px），与 Button 的尺寸名称一致。size 属性优先于 fieldContextKey 中的 size，内置回退值为 medium。可在 M3VuePlugin 中设置 fieldSize 作为应用默认值，或通过上下文配置子树。详见组件默认值。前置和后置图标插槽会保持相应的容器高度。多行字段始终使用 medium；最终高度仍由内容和 rows 决定。
前缀和后缀内容使用输入文本的排版，并保持所选单行字段的高度。
如需可交互的装饰内容，可将 IconButton 直接放入 leading 或 trailing 插槽。TextField 会自动调整并对齐其触控区域，同时保持字段高度不变；普通图标和文本不受影响。
描边控件对比
TextField 和描边 Button 使用相同的静止描边颜色、匹配尺寸的描边宽度、方形轮廓和容器高度。TextField 保留原生浮动标签缺口，以及字段专属的聚焦、错误和禁用状态。
extra-smallsmallmedium默认
配置
密码可见性
参考
结构
| 元素 | 部件 | 选择器 |
|---|---|---|
<div> | root | [data-scope="text-field"][data-part="root"]鼠标左键单击复制 |
<div> | container | [data-scope="text-field"][data-part="container"]鼠标左键单击复制 |
<label> | label条件显示 | [data-scope="text-field"][data-part="label"]鼠标左键单击复制 |
<span> | content | [data-scope="text-field"][data-part="content"]鼠标左键单击复制 |
<span> | leading条件显示 | [data-scope="text-field"][data-part="leading"]鼠标左键单击复制 |
<span> | prefix条件显示 | [data-scope="text-field"][data-part="prefix"]鼠标左键单击复制 |
<textarea> | input条件显示 | [data-scope="text-field"][data-part="input"]鼠标左键单击复制 |
<span> | suffix条件显示 | [data-scope="text-field"][data-part="suffix"]鼠标左键单击复制 |
<span> | trailing条件显示 | [data-scope="text-field"][data-part="trailing"]鼠标左键单击复制 |
<fieldset> | outline | [data-scope="text-field"][data-part="outline"]鼠标左键单击复制 |
<div> | supporting条件显示 | [data-scope="text-field"][data-part="supporting"]鼠标左键单击复制 |
属性
| 名称 | 说明 | 默认值 | 控件 |
|---|---|---|---|
label可选 | Floating label, or accessible-name fallback in external mode. Otherwise supply an external label or ARIA name. string | undefined | undefined | |
labelBehavior可选 | Floating label or externally arranged visible label; label remains an accessible-name fallback. FieldLabelBehavior | undefined | - | - |
id可选 | Optional explicit id for native control element. string | undefined | undefined | |
type可选 | Native input type. Date and datetime-local use DatePicker. Time uses TimePicker. string | undefined | "text" | |
shape可选 | The shape of the text field. Matches Button shape sizes. M3Shape | undefined | undefined | - |
labelClearance可选 | CSS length reserved at block-start for the floating label. Overrides FieldContext. string | undefined | undefined | |
rows可选 | Rows when rendered as textarea. number | undefined | 3 | - |
supportingText可选 | Supporting text shown below the field when not in error state. string | undefined | undefined | |
error可选 | Error text shown below the field. When provided, field is invalid. string | undefined | undefined | |
disabled可选 | Whether the control is disabled. boolean | undefined | false | |
required可选 | Whether the control is required. boolean | undefined | false | |
readonly可选 | Whether the control is readonly. boolean | undefined | false | |
name可选 | Name attribute for form submissions. string | undefined | undefined | |
min可选 | Minimum value for compatible input types. string | undefined | undefined | |
max可选 | Maximum value for compatible input types. string | undefined | undefined | |
placeholder可选 | Placeholder shown when value is empty. string | undefined | undefined | |
alwaysFloatLabel可选 | Always float the label when labelBehavior is floating. boolean | undefined | false | |
visuallyFocused可选 | Forces the visual focused state without requiring DOM focus. boolean | undefined | false | |
datePickerVariant可选 | DatePicker variant when type is date or datetime-local. DatePickerVariant | undefined | "auto" | - |
timePickerVariant可选 | TimePicker variant when type is time. TimePickerVariant | undefined | "auto" | - |
timePickerFormat可选 | TimePicker format when type is time. TimePickerFormat | undefined | undefined | - |
timePickerInputMode可选 | TimePicker input mode when type is time. TimePickerInputMode | undefined | undefined | - |
as可选 | Render either a single-line input or multiline textarea. inputtextarea | "input" | - |
size可选 | The field height. Matches the 32px, 40px, and 56px Button sizes. Multiline fields only support medium; TextFieldMultilineProps expresses that constraint for typed wrappers. extra-smallsmallmedium | undefined | |
modelValue必填 | - string | - |
事件6
| 名称 | 类型 | 说明 |
|---|---|---|
update:modelValue | [value: string] | - |
input | [event: Event] | - |
change | [event: Event] | - |
focus | [event: FocusEvent] | - |
blur | [event: FocusEvent] | - |
keydown | [event: KeyboardEvent] | - |
插槽5
| 名称 | 参数 | 说明 |
|---|---|---|
leading | - | - |
prefix | - | - |
suffix | - | - |
trailing | - | - |
supporting | - | - |
样式77
| Token | 说明 |
|---|---|
--md-outlined-text-field-caret-colorColor回退值 var(--md-sys-color-primary) | Controls text field caret color. |
--md-outlined-text-field-container-shapeShape回退值 var(--md-shape-field-square) | Controls text field container shape. |
--md-outlined-text-field-disabled-input-text-colorDisabled回退值 var(--md-sys-color-on-surface) | Controls text field disabled input text color. |
--md-outlined-text-field-disabled-input-text-opacityDisabled回退值 0.38 | Controls text field disabled input text opacity. |
--md-outlined-text-field-disabled-label-text-colorDisabled回退值 var(--md-sys-color-on-surface) | Controls text field disabled label text color. |
--md-outlined-text-field-disabled-label-text-opacityDisabled回退值 0.38 | Controls text field disabled label text opacity. |
--md-outlined-text-field-disabled-leading-icon-colorDisabled回退值 var(--md-sys-color-on-surface) | Controls text field disabled leading icon color. |
--md-outlined-text-field-disabled-leading-icon-opacityDisabled回退值 0.38 | Controls text field disabled leading icon opacity. |
--md-outlined-text-field-disabled-outline-colorDisabled回退值 var(--md-sys-color-on-surface) | Controls text field disabled outline color. |
--md-outlined-text-field-disabled-outline-opacityDisabled回退值 0.12 | Controls text field disabled outline opacity. |
--md-outlined-text-field-disabled-outline-widthDisabled回退值 0.0625rem | Controls text field disabled outline width. |
--md-outlined-text-field-disabled-supporting-text-colorDisabled回退值 var(--md-sys-color-on-surface) | Controls text field disabled supporting text color. |
--md-outlined-text-field-disabled-supporting-text-opacityDisabled回退值 0.38 | Controls text field disabled supporting text opacity. |
--md-outlined-text-field-disabled-trailing-icon-colorDisabled回退值 var(--md-sys-color-on-surface) | Controls text field disabled trailing icon color. |
--md-outlined-text-field-disabled-trailing-icon-opacityDisabled回退值 0.38 | Controls text field disabled trailing icon opacity. |
--md-outlined-text-field-error-focus-caret-colorFocus回退值 var(--md-sys-color-error) | Controls text field error focus caret color. |
--md-outlined-text-field-error-focus-input-text-colorFocus回退值 var(--md-sys-color-on-surface) | Controls text field error focus input text color. |
--md-outlined-text-field-error-focus-label-text-colorFocus回退值 var(--md-sys-color-error) | Controls text field error focus label text color. |
--md-outlined-text-field-error-focus-leading-icon-colorFocus回退值 var(--md-sys-color-on-surface-variant) | Controls text field error focus leading icon color. |
--md-outlined-text-field-error-focus-outline-colorFocus回退值 var(--md-sys-color-error) | Controls text field error focus outline color. |
--md-outlined-text-field-error-focus-supporting-text-colorFocus回退值 var(--md-sys-color-error) | Controls text field error focus supporting text color. |
--md-outlined-text-field-error-focus-trailing-icon-colorFocus回退值 var(--md-sys-color-error) | Controls text field error focus trailing icon color. |
--md-outlined-text-field-error-hover-input-text-colorState回退值 var(--md-sys-color-on-surface) | Controls text field error hover input text color. |
--md-outlined-text-field-error-hover-label-text-colorState回退值 var(--md-sys-color-on-error-container) | Controls text field error hover label text color. |
--md-outlined-text-field-error-hover-leading-icon-colorState回退值 var(--md-sys-color-on-surface-variant) | Controls text field error hover leading icon color. |
--md-outlined-text-field-error-hover-outline-colorState回退值 var(--md-sys-color-on-error-container) | Controls text field error hover outline color. |
--md-outlined-text-field-error-hover-supporting-text-colorState回退值 var(--md-sys-color-error) | Controls text field error hover supporting text color. |
--md-outlined-text-field-error-hover-trailing-icon-colorState回退值 var(--md-sys-color-on-error-container) | Controls text field error hover trailing icon color. |
--md-outlined-text-field-error-input-text-colorColor回退值 var(--md-sys-color-on-surface) | Controls text field error input text color. |
--md-outlined-text-field-error-label-text-colorColor回退值 var(--md-sys-color-error) | Controls text field error label text color. |
--md-outlined-text-field-error-leading-icon-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field error leading icon color. |
--md-outlined-text-field-error-outline-colorColor回退值 var(--md-sys-color-error) | Controls text field error outline color. |
--md-outlined-text-field-error-supporting-text-colorColor回退值 var(--md-sys-color-error) | Controls text field error supporting text color. |
--md-outlined-text-field-error-trailing-icon-colorColor回退值 var(--md-sys-color-error) | Controls text field error trailing icon color. |
--md-outlined-text-field-focus-input-text-colorFocus回退值 var(--md-sys-color-on-surface) | Controls text field focus input text color. |
--md-outlined-text-field-focus-label-text-colorFocus回退值 var(--md-sys-color-primary) | Controls text field focus label text color. |
--md-outlined-text-field-focus-leading-icon-colorFocus回退值 var(--md-sys-color-on-surface-variant) | Controls text field focus leading icon color. |
--md-outlined-text-field-focus-outline-colorFocus回退值 var(--md-sys-color-primary) | Controls text field focus outline color. |
--md-outlined-text-field-focus-outline-widthFocus回退值 0.1875rem | Controls text field focus outline width. |
--md-outlined-text-field-focus-supporting-text-colorFocus回退值 var(--md-sys-color-on-surface-variant) | Controls text field focus supporting text color. |
--md-outlined-text-field-focus-trailing-icon-colorFocus回退值 var(--md-sys-color-on-surface-variant) | Controls text field focus trailing icon color. |
--md-outlined-text-field-hover-input-text-colorState回退值 var(--md-sys-color-on-surface) | Controls text field hover input text color. |
--md-outlined-text-field-hover-label-text-colorState回退值 var(--md-sys-color-on-surface) | Controls text field hover label text color. |
--md-outlined-text-field-hover-leading-icon-colorState回退值 var(--md-sys-color-on-surface-variant) | Controls text field hover leading icon color. |
--md-outlined-text-field-hover-outline-colorState回退值 var(--md-sys-color-on-surface) | Controls text field hover outline color. |
--md-outlined-text-field-hover-outline-widthState回退值 0.0625rem | Controls text field hover outline width. |
--md-outlined-text-field-hover-supporting-text-colorState回退值 var(--md-sys-color-on-surface-variant) | Controls text field hover supporting text color. |
--md-outlined-text-field-hover-trailing-icon-colorState回退值 var(--md-sys-color-on-surface-variant) | Controls text field hover trailing icon color. |
--md-outlined-text-field-input-text-colorColor回退值 var(--md-sys-color-on-surface) | Controls text field input text color. |
--md-outlined-text-field-input-text-fontTypography回退值 body-medium-font (extra-small/small); body-large-font (medium) | Controls text field input text font. |
--md-outlined-text-field-input-text-line-heightTypography回退值 body-medium-line-height (extra-small/small); body-large-line-height (medium) | Controls text field input text line height. |
--md-outlined-text-field-input-text-placeholder-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field input text placeholder color. |
--md-outlined-text-field-input-text-prefix-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field input text prefix color. |
--md-outlined-text-field-input-text-sizeLayout回退值 body-medium-size (extra-small/small); body-large-size (medium) | Controls text field input text size. |
--md-outlined-text-field-input-text-suffix-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field input text suffix color. |
--md-outlined-text-field-input-text-trackingTypography回退值 body-medium-tracking (extra-small/small); body-large-tracking (medium) | Controls text field input text tracking. |
--md-outlined-text-field-input-text-weightTypography回退值 body-medium-weight (extra-small/small); body-large-weight (medium) | Controls text field input text weight. |
--md-outlined-text-field-label-text-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field label text color. |
--md-outlined-text-field-label-text-fontTypography回退值 body-medium-font (extra-small/small); body-large-font (medium) | Controls text field label text font. |
--md-outlined-text-field-label-text-line-heightTypography回退值 body-medium-line-height (extra-small/small); body-large-line-height (medium) | Controls text field label text line height. |
--md-outlined-text-field-label-text-populated-line-heightTypography回退值 var(--md-sys-typescale-body-small-line-height) | Controls text field label text populated line height. |
--md-outlined-text-field-label-text-populated-sizeLayout回退值 var(--md-sys-typescale-body-small-size) | Controls text field label text populated size. |
--md-outlined-text-field-label-text-sizeLayout回退值 body-medium-size (extra-small/small); body-large-size (medium) | Controls text field label text size. |
--md-outlined-text-field-label-text-trackingTypography回退值 body-medium-tracking (extra-small/small); body-large-tracking (medium) | Controls text field label text tracking. |
--md-outlined-text-field-label-text-weightTypography回退值 body-medium-weight (extra-small/small); body-large-weight (medium) | Controls text field label text weight. |
--md-outlined-text-field-leading-icon-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field leading icon color. |
--md-outlined-text-field-leading-icon-sizeLayout回退值 Typography, density and icon scale (20dp / body-medium for extra-small and small; 24dp / body-large for medium) | Controls text field leading icon size. |
--md-outlined-text-field-outline-colorColor回退值 var(--md-sys-color-outline) | Controls text field outline color. |
--md-outlined-text-field-outline-widthLayout回退值 0.0625rem | Controls text field outline width. |
--md-outlined-text-field-supporting-text-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field supporting text color. |
--md-outlined-text-field-supporting-text-fontTypography回退值 var(--md-sys-typescale-body-small-font) | Controls text field supporting text font. |
--md-outlined-text-field-supporting-text-line-heightTypography回退值 var(--md-sys-typescale-body-small-line-height) | Controls text field supporting text line height. |
--md-outlined-text-field-supporting-text-sizeLayout回退值 var(--md-sys-typescale-body-small-size) | Controls text field supporting text size. |
--md-outlined-text-field-supporting-text-trackingTypography回退值 var(--md-sys-typescale-body-small-tracking) | Controls text field supporting text tracking. |
--md-outlined-text-field-supporting-text-weightTypography回退值 var(--md-sys-typescale-body-small-weight) | Controls text field supporting text weight. |
--md-outlined-text-field-trailing-icon-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls text field trailing icon color. |
--md-outlined-text-field-trailing-icon-sizeLayout回退值 Typography, density and icon scale (20dp / body-medium for extra-small and small; 24dp / body-large for medium) | Controls text field trailing icon size. |