TextInput Props

名称	类型	默认值	说明
modelValue	string	必需	输入框的当前值，一般通过 v-model 绑定。
label	string	必需	字段的可见标签。即使被隐藏，也会作为控件的名称提供给辅助技术。
isLabelHidden	boolean	false	在视觉上隐藏标签与说明，同时保留它们与控件的无障碍关联。
description	string	—	显示在标签下方、控件上方的补充说明文字。
isDisabled	boolean	false	禁用输入框。被禁用的字段不参与表单提交。
isOptional	boolean	false	显示“可选”提示。与 isRequired 同时设置时，isOptional 优先。
isRequired	boolean	false	显示“必填”提示，组件同时会设置 aria-required。
labelIcon	Component	—	显示在标签前的图标组件。与 labelIcon 插槽同时使用时，插槽优先。
labelTooltip	string	—	在标签旁显示信息按钮，悬停、键盘聚焦或点击都可以查看提示。
optionalLabel	string	Optional	“可选”提示的显示文字，用于本地化。
requiredLabel	string	Required	“必填”提示的显示文字，用于本地化。
id	string	自动生成	原生 input 的 ID。设置后会同步更新标签与说明的关联。
type	'text' | 'password' | 'email'	text	输入框类型。多行内容请改用 TextArea。
size	'sm' | 'md' | 'lg'	md	输入框高度。Neutral 主题下三档分别为 28、32、36px。
isReadOnly	boolean	false	内容不可编辑，但输入框保留焦点、正常显示，值仍会参与表单提交。
disabledMessage	string	—	说明禁用原因。设置后改用 aria-disabled 与 readonly 保留焦点，方便用户查看原因；字段仍不可修改，也不会随表单提交。
startIcon	Component	—	显示在输入框前端的装饰图标。与 icon 插槽同时使用时，插槽优先。
status	TextInputStatus	—	设置 error、warning 或 success 校验状态，可附带 message 和 messageId。错误状态会设置 aria-invalid。
statusVariant	'attached' | 'detached' | 'tooltip'	attached	状态消息的展示方式：紧贴控件、分离显示，或收进图标提示。三种方式均与输入框保持关联。
changeAction	(value: string, event: TextInputChangeEvent) => void | Promise<void>	—	在值变化后执行的动作。返回 Promise 时，组件会显示加载状态。
isLoading	boolean	false	手动控制加载状态。存在未完成的异步操作时也会显示加载，期间输入框仍可编辑。
placeholder	string	—	输入为空时显示的提示文字，不能替代 label。
width	number | string	auto	整个字段的宽度。数字按像素处理，CSS 字符串按原样使用。
hasClear	boolean	false	在有内容且可编辑时显示清除按钮，点击清除后焦点会回到输入框。
hasAutoFocus	boolean	false	组件挂载后自动聚焦原生 input。
htmlName	string	—	原生 input 的 name 属性，优先于通过原生属性传入的 name。字段禁用时会被移除。
autoComplete	string	—	原样透传给原生 input 的 autocomplete 属性。
clearLabel	string	Clear {label}	清除按钮的无障碍名称，用于本地化。
loadingLabel	string	Loading	加载指示器的无障碍名称，用于本地化。

状态类型

interface TextInputStatus {
  type: 'error' | 'warning' | 'success'
  message?: string
  messageId?: string
}

TextInput 插槽

名称	类型	默认值	说明
icon	() => VNode[]	—	前端装饰图标，覆盖 startIcon。避免放入可交互控件。
end	() => VNode[]	—	尾部内容，可以放按钮。使用方负责其无障碍名称。
labelIcon	() => VNode[]	—	标签前的装饰图标，覆盖 labelIcon 属性。

TextInput 事件

名称	类型	默认值	说明
update:modelValue	value: string	—	v-model 更新。先于 change 与 changeAction。
change	value: string, event: TextInputChangeEvent	—	每次有效修改与清除后触发。event.preventDefault() 只阻止 changeAction，不撤回 v-model 更新。
enter	event: KeyboardEvent	—	非输入法提交的 Enter。keydown 被取消时不触发。
keydown	event: KeyboardEvent	—	原生按键事件。调用 preventDefault() 可阻止 enter。
clear	event: MouseEvent	—	清除按钮被激活后触发。仍会发出 update:modelValue 和 change，并运行未取消的 action。
actionError	error: unknown, value: string, event: TextInputChangeEvent	—	同步异常或 Promise 拒绝后触发。组件自动清除该操作的加载状态。

TextInputChangeEvent

type TextInputChangeEvent = CustomEvent<{
  value: string
  originalEvent: Event
}>

• 原生 input 事件通常无法取消。
• change 提供可以取消的组件事件。
• event.detail.value 保存修改后的值。
• event.detail.originalEvent 保存原始事件。
• changeAction 和 actionError 接收同一个组件事件。

原始事件的类型取决于操作：

操作	类型
输入文字	InputEvent
提交输入法候选词	CompositionEvent
点击清除按钮	MouseEvent

异步操作

changeAction 接收修改后的值和组件事件。返回 Promise 时，组件会显示加载状态。

• 输入：保存期间仍可编辑。清除内容也会运行 changeAction。
• 加载状态：存在未完成的操作时，aria-busy 为 true。所有操作结束后清除加载状态，失败的操作也会计入。
• 值更新：父组件传入的新值优先于组件临时显示的值。
• 并发保存：由应用取消旧请求或检查请求序号，避免过期结果覆盖新值。
• 失败处理：通过 @action-error 展示错误。需要回滚时，由应用更新 v-model 绑定值。

模板引用

模板引用公开以下属性和方法：

• element: HTMLInputElement | null：原生输入元素。挂载前为 null。
• focus(options?: FocusOptions)：聚焦输入框。
• blur()：移除输入框焦点。
• select()：选中全部输入内容。

原生属性

• maxlength、minlength、pattern、required、form、aria-*、data-* 和原生事件监听器传入原生 input。
• class 和 style 作用于输入框外层。width 作用于整个 Field。
• value、type、disabled、readonly、autofocus 与核心 ARIA 状态由组件管理，请使用对应的组件属性。
• aria-describedby 和 aria-labelledby 会与组件内部的关联 ID 合并。

禁用与只读

• 禁用且无原因说明：使用原生 disabled，无法编辑、聚焦或提交该字段。
• 禁用且有 disabledMessage：使用 aria-disabled 和 readonly 保留焦点，以便查看原因。同时移除 name，阻止修改和清除。
• 只读：保留焦点，允许复制，值仍包含在 FormData 中。
• 同时设置禁用和只读时，禁用优先。

主题

为组件添加类名，即可覆盖主题变量：

<TextInput v-model="email" class="my-input" label="邮箱" />

.my-input {
  --astryx-input-focus: #10b981;
  --astryx-radius-element: 8px;
}

外观与尺寸

• --astryx-input-background：输入框背景色。
• --astryx-input-border：默认边框色。
• --astryx-input-focus：无校验状态时的焦点边框色。
• --astryx-radius-element：输入框圆角。
• --astryx-input-height-sm：小尺寸高度，Neutral 默认 28px。
• --astryx-input-height-md：中尺寸高度，Neutral 默认 32px。
• --astryx-input-height-lg：大尺寸高度，Neutral 默认 36px。

校验状态

每种状态提供三个变量，分别控制边框与图标、消息文字、消息背景：

• 错误：--astryx-input-error、--astryx-input-error-foreground、--astryx-input-error-background。
• 警告：--astryx-input-warning、--astryx-input-warning-foreground、--astryx-input-warning-background。
• 成功：--astryx-input-success、--astryx-input-success-foreground、--astryx-input-success-background。

在包含整个字段的父元素上覆盖状态变量，可同时调整输入框和状态消息。

明暗模式

• Neutral 根据 CSS color-scheme 自动选择配色。
• 在根元素或主题容器上设置 data-astryx-color-mode="light"，可固定使用浅色模式。
• 设置 data-astryx-color-mode="dark"，可固定使用暗色模式。