Field Props

名称	类型	默认值	说明
label	string	必需	字段的可见标签；即使视觉上隐藏，也仍作为控件的无障碍名称。
isLabelHidden	boolean	false	在视觉上隐藏标签和说明，但保留它们与控件的无障碍关联。
description	string	—	显示在标签下方、控件上方的补充说明。
isDisabled	boolean	false	禁用状态。Field 和 FieldLabel 只调整标签样式，控件本身由使用方禁用。
isOptional	boolean	false	显示“可选”提示；与 isRequired 同时设置时优先。
isRequired	boolean	false	显示“必填”提示；在 TextInput 中还会同时设置 aria-required。
labelIcon	Component	—	显示在标签前的 Vue 图标组件；labelIcon 插槽优先于该属性。
labelTooltip	string	—	标签旁的信息按钮，提示内容支持悬停、键盘聚焦和点击查看。
optionalLabel	string	Optional	“可选”提示的本地化文字。
requiredLabel	string	Required	“必填”提示的本地化文字。
inputId	string	必需	被标记控件的 ID，必须与内部控件的 id 一致。
labelId	string	{inputId}-label	标签自身的 ID；作为分组标签时，由分组容器通过 aria-labelledby 引用。
descriptionId	string	{inputId}-description	说明文字的 ID，控件通过 aria-describedby 引用它。
isGroupLabel	boolean	false	为 radiogroup 等分组输出 span 而不是 label，避免把分组当作单个控件。
status	FieldStatusInput	—	字段状态，包含状态类型、可选的消息文本和自定义 messageId。
statusVariant	'attached' | 'detached' | 'tooltip'	attached	tooltip 隐藏行内消息框，但保留描述与屏幕阅读器播报，提示按钮由内部控件自行提供。
width	number | string	auto	整个字段的宽度，传入数字时按像素处理。

FieldLabel Props

名称	类型	默认值	说明
label	string	必需	可见标签。隐藏时仍为控件提供名称。
isLabelHidden	boolean	false	视觉上隐藏标签和说明，保留无障碍关联。
description	string	—	标签下方、控件上方的补充说明。
isDisabled	boolean	false	禁用状态。Field/FieldLabel 只改变标签样式，控件由使用方禁用。
isOptional	boolean	false	显示可选提示。与 isRequired 同时设置时优先。
isRequired	boolean	false	显示必填提示。TextInput 同时设置 aria-required。
labelIcon	Component	—	标签前的 Vue 图标组件。labelIcon 插槽优先。
labelTooltip	string	—	标签旁的信息按钮，支持悬停、键盘聚焦和点击。
optionalLabel	string	Optional	可选提示的本地化文字。
requiredLabel	string	Required	必填提示的本地化文字。
inputId	string	必需	被标记控件的 ID。必须与控件 id 相同。
labelId	string	{inputId}-label	标签自身 ID。分组使用 aria-labelledby 引用。
descriptionId	string	{inputId}-description	说明 ID。控件通过 aria-describedby 引用。
isGroupLabel	boolean	false	为 radiogroup 等分组输出 span，避免把分组当作单个控件。

FieldStatus Props

名称	类型	默认值	说明
type	'error' | 'warning' | 'success'	必需	状态语义与配色。
message	string	必需	状态文字。空字符串不显示消息框。
variant	'attached' | 'detached'	attached	attached 与有边框的控件重叠。detached 适合滑块、开关等。
isVisuallyHidden	boolean	false	只保留无障碍描述和播报，用于控件自行提供 tooltip 的场景。

插槽

Field 的 default 为必需插槽，接收以下参数：

interface FieldSlotProps {
  inputId: string
  labelId: string
  descriptionId?: string
  statusId?: string
  describedBy?: string
}

• Field 和 FieldLabel 提供 labelIcon 插槽。
• labelIcon 插槽覆盖同名属性。
• 图标只作装饰用途。
• FieldStatus 不提供插槽。文字通过 message 传入。

状态消息

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

播报规则

• error 使用 aria-live="assertive" 区域。
• warning 使用 aria-live="polite" 区域。
• success 使用 aria-live="polite" 区域。
• 消息变化时，组件重新播报消息。
• 消息为空时，组件清空播报区域。
• 视觉消息不重复设置 aria-live。

消息布局

• attached：消息紧贴控件。必须放在 Field 内有边框的控件下方。
• detached：消息与控件分离。消息包含状态图标。
• Field 的 tooltip 模式：隐藏文字仍用于描述和播报。内部控件负责提供提示按钮。

独立使用 FieldStatus 时，使用 detached。

事件

这三个组件不声明自定义事件。

模板引用

每个组件都公开 element：

组件	元素
Field	字段根 div。
FieldLabel	标签元素或分组 span。
FieldStatus	视觉消息元素。

挂载前，element 为 null。 没有消息时，FieldStatus.element 为 null。

原生属性

组件	属性接收位置
Field	字段根元素。
FieldLabel	标签组。
FieldStatus	消息元素。

以下内容必须直接传给内部控件：

• name。
• required。
• disabled。
• 控件事件监听器。

导入

import type { FieldProps, FieldSlotProps, FieldStatusInput } from '@astryx-vue/core/Field'
import { Field, FieldLabel, FieldStatus } from '@astryx-vue/core/Field'
import '@astryx-vue/themes/neutral.css'

主题

• --astryx-spacing-1：字段内容间距。
• --astryx-spacing-2：分离状态消息的内边距。
• --astryx-radius-element：状态消息圆角。
• --astryx-color-text-secondary：辅助文字颜色。
• --astryx-text-label-size：标签字号。
• --astryx-text-supporting-size：说明与状态消息字号。

状态颜色与 TextInput 共用变量。完整列表见 TextInput 校验状态。