ASAM UI
v1.0.0

数据组件

数据表单 AsamForm

使用类型化 schema 与控件注册表组合字段、依赖和数据来源。

数据表单 ​

使用类型化 schema 与控件注册表组合字段、依赖和数据来源。

基础用法 ​

示例通过 createAsamSchema() 绑定模型与 asamFormControls，使用字段插槽和 actions 插槽。模型更新由 v-model 返回新的对象。

类型化 Schema 与插槽

展开源码

Schema 与控件覆盖 ​

schema 配合 registry 使用；createAsamSchema 的 field 校验字段名、模型类型和对应控件。 完整说明。

内置控件已自动注册。asamFormControls 提供给 createAsamSchema 做类型检查，不作为 registry prop 再传一次；registry 只接收由 defineAsamControl 创建的新 custom: 名称，不能覆盖内置控件。

表单标量日期与时间 ​

注册表的 DatePicker、TimePicker 和 TimeSelect 使用 string|null 协议。 完整说明。

表单标量日期、时间与空值

展开源码

依赖与隐藏规则 ​

dependsOn 声明前置字段；resolveDataSource 从只读模型派生来源。 完整说明。

插槽与实例 ​

field-字段名 插槽提供 field、model、value、update 和 updateValue；使用更新函数写回对应字段。 完整说明。

默认与布局 ​

本组件设置 inline=true、labelWidth=auto、showSearch=true、showReset=true、labelMode=visible，searchText 为“搜 索”、resetText 为“重置”。基础表单能力通过显式公开类型关联；model 由 modelValue 接管。

本站继承关系 ​

  • AsamBaseForm：适用的基础展示、交互与公开 API。

本页数据来源、模型、事件和实例的覆盖规则优先；本站链接不扩大本组件公开契约。尺寸使用基础组件的 ASAM 尺寸规则，示例使用 default。

依赖来源、隐藏与重置 ​

完整示例按地区派生成员 API 来源，在地区变化时清除旧成员；隐藏备注时清除备注并暂停其验证，重新显示后恢复 required 规则。 完整说明。

同一示例可切换 onDependencyChange 与 onHide 的 retain／clear 策略：retain 保留当前模型，clear 使用注册控件的空值。 完整说明。

成员字段也可独立切换必填、枚举规则、布尔／函数隐藏和禁用；固定来源与派生来源使用相同字段策略。 完整说明。

成员显示配置可切换 schema 的 label 与 componentProps.placeholder，并恢复原标签和占位文案。 完整说明。

固定来源分支禁止再传 resolveDataSource，派生来源分支禁止再传 dataSource；类型检查会拒绝这两种组合。绕过类型后同时传入两者时，Form 在挂载控件或发起请求前显示互斥配置错误，并保留原模型。只传固定来源或只传 resolver 均可正常建立字段。

依赖来源、隐藏清除与校验重置

展开源码

布局、自定义注册和兼容字段 ​

完整示例用 custom:status 注册真正只发出 yes/no 的包装控件，componentProps.caption 为必填；宽 Input 不能代替窄枚举控件。 完整说明。

新表单使用带类型检查的 schema；旧 fields 仅用于兼容，不与 schema 同时提供。 完整说明。

完整布局场景记录四个公开事件：update:modelValue、search、reset 保留具体模型快照，validate 保留字段、布尔结果和消息。 完整说明。

在同一模型下切换布局、标签和尺寸，并控制内置操作按钮。 完整说明。

布局、兼容字段与自定义窄枚举

展开源码

滚动区域将字段放在视口下方，便于观察校验失败后的定位。 完整说明。

同一完整示例在 schema 和兼容 fields 两种模式中保留具体实例控制。 完整说明。

可切换标签后缀、必填标记、错误显示、状态图标与禁用状态。 完整说明。

原生 Form 的 model 由 ASAM 的具体类型 v-model／modelValue 承接，不能再传 model 绕过事务。 完整说明。

原生标签位置可直接选择 left、right、top 并恢复 right；姓名模型不受布局变化影响。clearValidate 接受无参数、字符串字段或字段数组；数组按钮清除 name 与 status 的验证显示，保留模型，之后再次 validate 仍能发现原无效姓名。

原生 rules 可为字段提供单条规则或规则数组。 完整说明。

validate 的有效模型返回 fulfilled，无效模型返回 rejected；示例记录真实 Promise 终态。 完整说明。

通过 fields 与 getField 读取字段上下文，并按字段或整表触发校验。 完整说明。

嵌套 FormItem 示例通过默认插槽追加 profile.nickname；字符串和分段数组路径均注册到同一表单。 完整说明。

嵌套字段支持点分字符串与路径数组，字段上下文随当前模型更新。 完整说明。

组合演示交叉校验、异步数字校验与 number 模型转换。 完整说明。

FormItem 自动标签宽度和必填继承：在布局示例启用嵌套字段后，可将表单和字段的 label-width 同时设为 auto，并切换短、长标签，原生标签包装器根据实际标签宽度更新对齐。 完整说明。

可分别设置表单与字段的标签位置，字段空值继承表单配置。 完整说明。

上述对齐与可访问性纵向组合显式设置 inline=false；ASAM Form 默认 inline=true，不能依赖原生 Form 的 false 默认。

动态字段组合采用 Email 的 required/type:email 规则与 domains.index.value 嵌套必填路径。 完整说明。

resetFields 保留原生字段在本次模型更新中的校验暂停，重置后不重新触发 change 规则并留下 success 状态。受控模型的嵌套值不被原生重置直接修改；schema 工厂默认值、兼容字段默认值及默认插槽字段的原生初值仍按各自基线恢复。

原生基础表单组合保留活动名称、两个区域、日期/时间、即时配送、四种活动类型、两种资源、活动正文以及 Create/Cancel。 完整说明。

表单尺寸向子控件传递；切换尺寸和标签位置不重置模型。 完整说明。

完整原生规则组合保留初始 Hello、姓名 required/3到5长度、区域/数量、原生 Date 型日期和时间、地点、非空数组活动类型、资源及正文。 完整说明。

原生 FormItem 校验成功时，validateState 为 success、validate 事件消息为空，公开 validateMessage 仍可保留上一条错误文字；成功时错误区域不显示。 完整说明。

控件注册示例通过 defineAsamControl 创建 custom:code，声明字符串模型、无数据源、必填 placeholder、独立 emptyValue 工厂及可选 suspendable。 完整说明。

公开 AsamSchemaField 除固定／派生来源联合，还根据注册控件的必填属性决定 componentProps 是否可省略。 完整说明。

AsamComponentProps 保留非保留属性的类型约束，保留属性由表单统一管理。 完整说明。

AsamControlSource 是四类工厂来源的 opaque 公共类型；只有 kind 的对象不能替代工厂来源。 完整说明。

AsamDataRuntime 与 createAsamDataRuntime 是应用局部的数据协调契约。 完整说明。

reportError 只处理当前 context，保留 kind/message/cause，给报告附上当前 requestId 并冻结。 完整说明。

确定性模拟示例完整使用公开 AsamMockStep、AsamMockCall、AsamMockProviderOptions、AsamMockProvider 和 createAsamMockProvider。 完整说明。

AsamDataFailure 表达数据失败类型、原因及通知状态；取消请求不作为失败。 完整说明。

AsamMockStep 的结构联合不会在静态或运行时强制 data/error 二选一；同时存在时 error 分支优先，error:undefined 也作为原始拒绝原因保留。示例单独验证这两点，不虚构互斥校验。

通过公开工具规范化选项和分页数据，并处理标签缓存与未解析值。 完整说明。

选择规则按单选、多选、对象和值存储方式组合，非法分支不能混用。 完整说明。

page 要有 own list/total；list 是实际对象数组，稀疏 holes 也拒绝，total 为非负安全整数，total0 时 list 必须为空，正 total 可有空 list。 完整说明。

TS/JS 完整示例包含 13 个状态组，含 27 个 response、3 个字符串 token、18 个配置、17 个 page 形状拒绝，及原始 cause、两种公开重载、adapter/transform 优先级和宿主快照的真实观察；不以静态字段存在或仅挂载代替函数行为证据。

完整来源工厂示例通过公开 defineAsamOptions、defineAsamDictSource 和 resolveAsamOptions 展示 static/api/request/dict 四类来源。 完整说明。

工厂构造不发送请求。 完整说明。

构造配置必须是非数组对象，options/data/api/request/dictType/dataSource 中恰好一个已定义来源且匹配当前工厂，匹配值不能 null。 完整说明。

API 接收原始 params 对象与请求上下文。 完整说明。

resolveAsamOptions 只完成单次管线：必须传入 context，可附 provider、tree、valuePolicy、separator。 完整说明。

已取消的 context 立即以 signal.reason 拒绝且四类来源均零 IO；请求中取消及时拒绝，后端忽略取消时迟到成功和迟到失败都不能触发 transform 或恢复结果。 完整说明。

状态组合函数提供选项、加载、错误、选择及实例控制状态。 完整说明。

选项状态支持响应式来源和策略配置，运行时仍需由宿主提供。 完整说明。

缓存按完整来源身份去重；来源、参数或策略变化时重新计算身份。 完整说明。

字典共享同一 runtime 的来源 identity；force 需要 provider.dict.refresh，缺失时返回 config 错误。 完整说明。

远程搜索应同时在响应式 source 参数中表达当前搜索词，并提供 searchText；连续改变搜索词时取消旧等待，用最后输入发请求。 完整说明。

完整 TS/JS 分段实测29组观察，包括真实250ms默认防抖、25ms配置防抖/0、200ms TTL命中/过期、共享请求、force、刷新失败与恢复、identity、策略和生命周期。 完整说明。

选项值与字段映射的公开类型 ​

类型 完整约束与对应示例
AsamValue string、number、true、false；空字符串、0、负小数都合法。null/undefined 属于其他选择模型的空值约定，不属于本类型，object、array、bigint、symbol 也不属于本类型。规范化示例保留数字1与字符串“1”的类型区别；TypeScript number 包含 NaN/Infinity，有限数字限制由运行时检查。
AsamRecord 只读字符串索引的 unknown 值记录。读取后需要收窄，不能按已知数字使用，也不能赋值给索引。它不在静态类型层保证 plain object、深冻结或业务字段；规范化结果的 raw 深复制和冻结由对应运行时管线负责，不改变宿主输入。
AsamOption<V, I> label 为字符串、value 保持 V、raw 保持 I，三者必需；disabled 为可选 boolean，children 为可选只读同类型选项数组。公开属性只读；默认 I 为 AsamRecord。树、空 children、可选 disabled、raw 元数据和宿主快照由规范化示例实际观察。
AsamDictEntry label/string、value/AsamValue 必需，disabled/boolean 与递归只读 children 可选；额外字符串字段类型为 unknown。已声明属性与额外字符串索引均只读，读取 unknown 字段需先收窄；静态类型不保证嵌套对象深冻结。字典输入原值与转换后的规范化 value 分别保留，不把两者混为同一泛型。
AsamDictValueType、AsamDictValue<T> 前者是 string/number/boolean 三种字符串判别值；后者分别推导 string、number、boolean，联合 T 按分支分发。实际字典转换按严格运行时规则处理数字字符串、布尔别名、非法值和重复值；静态条件类型不执行转换。
AsamKeysOfType<I, V> 只选择实际存在且其完整字段类型可赋给 V 的字符串字段名。number 字段不能作 string label；可选 string 含 undefined，所以不被仅 string 的匹配包含。数字或符号键不由最终字符串键类型暴露。
AsamFieldNames<I, V> label 匹配 string 字段、value 匹配 V 字段且两者必需；disabled 可选并匹配 boolean/undefined 字段，children 可选并匹配 readonly I[]/undefined 字段，所有映射属性只读。字段名是直接键，含点的键不会当成路径，字典固定字段与普通自定义映射分别演示。

完整 layout-registry TS/JS 示例中的规范化与来源分段承接上述类型：展示所有标量类型、原始记录和元数据快照、树与直接字段映射，以及三种字典值转换、非法形状与配置拒绝。 完整说明。

请求、字典与通用控制的公开协议 ​

AsamRequestContext 提供只读 signal/AbortSignal、requestId/number、scope/string 和 epoch/number。 完整说明。

AsamApiRequest<P, R> 是 (params: P, context: AsamRequestContext) => Promise<R>。 完整说明。

请求配置声明地址、方法与参数；取消、分页和查询意图由请求上下文传递。 完整说明。

数据错误保留失败类型、消息与原因；数据来源同时声明缓存及转换元数据。 完整说明。

字典 provider 异步返回字典条目；统一 runtime 管理请求与字典状态。 完整说明。

AsamDataControls<T> 只包含只读 reload 和 cancel 方法引用。 完整说明。

控件注册的内部边界 ​

应用使用公开 AsamControl、defineAsamControl 和 createAsamSchema；合法注册对象由工厂创建。 完整说明。

注册子控件的局部请求错误 ​

Form 通过既有控件注册与字段模型承接高级子控件的 error 插槽。 完整说明。

Form 不新增根请求、根 error 插槽或根 reload；FormItem 的原生校验 error 插槽继续 保持字段校验作用。完整 TS/JS 多文件例使用独立 provider，并在卸载时关闭子应用。

注册子控件的局部请求错误

展开源码

API

属性 AsamFormProps

属性名说明类型默认值
modelValue—M—
fields—readonly AsamFormField[] | undefined—
schema—readonly AsamFormSchemaEntry<M>[] | undefined—
registry—object | undefined—
inline行内表单模式boolean | undefinedtrue
labelWidth标签宽度，例如 '50px'。可以使用 auto。string | number | undefined'auto'
showSearch—boolean | undefinedtrue
showReset—boolean | undefinedtrue
searchText—string | undefined'搜 索'
resetText—string | undefined'重置'
labelMode—enum"visible" | "sr-only"完整类型：AsamFormLabelMode | undefined'visible'
disabled是否禁用表单中的全部控件；设为 true 时覆盖内部组件的 disabled。boolean | undefinedfalse
size表单项大小enum"large" | "big" | "default" | "small"完整类型：AsamControlSize | undefined—
scrollIntoViewOptions校验失败时，根据 scrollIntoView 配置滚动到首个错误字段。boolean | ScrollIntoViewOptions | undefinedtrue
rules表单验证规则, 具体配置见下表, 更多内容可以参考async-validator(AsamFormProps<M>)["rules"]—
labelPosition表单域标签的位置，当设置为 left 或 right 时，则也需要设置 label-width 属性enum"top" | "right" | "left"完整类型："top" | "right" | "left" | undefined—
requireAsteriskPosition星号的位置。enum"right" | "left"完整类型："right" | "left" | undefined—
labelSuffix表单域标签的后缀string | undefined—
inlineMessage是否在行内显示校验信息boolean | undefinedfalse
statusIcon是否在输入框中显示校验结果反馈图标boolean | undefinedfalse
showMessage是否显示校验错误信息boolean | undefinedfalse
validateOnRuleChange是否在 rules 属性改变后立即触发一次验证boolean | undefinedfalse
hideRequiredAsterisk是否隐藏必填字段标签旁边的红色星号。boolean | undefinedfalse
scrollToError当校验失败时，滚动到第一个错误表单项boolean | undefinedfalse

事件 AsamFormEmits

属性名说明类型默认值
validate—(AsamFormEmits<M>)["validate"]—
update:modelValue—[model: M]—
search—[model: M]—
reset—[model: M]—

插槽 AsamFormSlots

属性名说明类型默认值
default—(() => unknown) | undefined—
actions—((scope: { search: () => void; reset: () => void; }) => unknown) | undefined—
append—(() => unknown) | undefined—

实例方法与状态 AsamFormExpose

属性名说明类型默认值
validate验证表单项(AsamFormExpose<M>)["validate"]—
clearValidate清除指定字段的校验消息。(AsamFormExpose<M>)["clearValidate"]—
resetFields—(AsamFormExpose<M>)["resetFields"]—
setFieldsValue—(patch: Partial<M>) => void—
validateField验证具体的某个字段。(AsamFormExpose<M>)["validateField"]—
scrollToField滚动到指定的字段(AsamFormExpose<M>)["scrollToField"]—
getField获取字段的 context(AsamFormExpose<M>)["getField"]—
fields全部字段的上下文。(AsamFormExpose<M>)["fields"]—
setInitialValues设置表单字段的初始值。当调用 resetFields 时，字段将重置为这些值。(initModel: Record<string, any>) => void—

类型 AsamSchemaField

属性名说明类型默认值
field—K—
component—C—
label—string | undefined—
required—boolean | undefined—
rules—(AsamSchemaField<M, R, K, C>)["rules"]—
defaultValue—(() => M[K]) | undefined—
dependsOn—readonly (keyof M & string)[] | undefined—
hidden—boolean | ((model: Readonly<M>) => boolean) | undefined—
disabled—boolean | ((model: Readonly<M>) => boolean) | undefined—
onDependencyChange—enum"clear" | "retain"完整类型："clear" | "retain" | undefined—
onHide—enum"clear" | "retain"完整类型："clear" | "retain" | undefined—
componentProps—(AsamSchemaField<M, R, K, C>)["componentProps"]—
dataSource—(AsamSchemaField<M, R, K, C>)["dataSource"] | undefined—
resolveDataSource—undefined | (AsamSchemaField<M, R, K, C>)["resolveDataSource"]—

用法与契约补充说明 ​

Schema 与控件覆盖 ​

schema 配合 registry 使用；createAsamSchema 的 field 校验字段名、模型类型和对应控件。componentProps 不能接管 modelValue、来源属性或值策略保留字段。数据来源在 dataSource 与 resolveDataSource 中二选一；静态与异步来源须符合控件注册的 sourceKinds。

表单标量日期与时间 ​

注册表的 DatePicker、TimePicker 和 TimeSelect 使用 string|null 协议。Form 自有适配器为前两者显式传入 YYYY-MM-DD、HH:mm:ss；componentProps.valueFormat 可指定其他字符串格式。原生清空结果在 Form 适配器中映射为 null，reset 使用字段 defaultValue 或 emptyValue。基础日期组件仍保留原生默认值、模型联合与清空行为；需要 Date、数组或范围模型时使用范围控件、字段插槽或自定义注册控件。

依赖与隐藏规则 ​

dependsOn 声明前置字段；resolveDataSource 从只读模型派生来源。onDependencyChange 和 onHide 分别使用 retain 或 clear，按实际规则保留或清除模型。hidden、disabled 可以是布尔值或只读模型函数；回调不得修改模型。动态数据控件的暂停和旧请求取消由控件及表单生命周期协作处理。

插槽与实例 ​

field-字段名 插槽提供 field、model、value、update 和 updateValue；使用更新函数写回对应字段。actions 提供 search 与 reset 回调，二者返回 void；search/reset 事件携带当前模型，使用事件监听读取模型。append 用于追加内容，validate 使用基础表单事件。setFieldsValue 接收 Partial，validate、clearValidate、resetFields 与基础表单实例契约关联。fields 兼容入口不作为类型化 schema 的新示例。

依赖来源、隐藏与重置 ​

完整示例按地区派生成员 API 来源，在地区变化时清除旧成员；隐藏备注时清除备注并暂停其验证，重新显示后恢复 required 规则。使用 setFieldsValue 事务更新模型，validate 的拒绝由调用方处理，读取 fields/getField 并通过 setInitialValues + resetFields 设置重置目标。defaultValue 工厂用于 schema 字段的默认重置值；actions 的事件用于读取提交模型。接口只在演示内部运行。

依赖来源、隐藏与重置 ​

同一示例可切换 onDependencyChange 与 onHide 的 retain／clear 策略：retain 保留当前模型，clear 使用注册控件的空值。hidden 和 disabled 分别提供布尔及只读模型函数形式；禁用控件保留当前值，隐藏字段暂停验证，重新显示后恢复规则。固定成员来源通过 dataSource 传入预建 API 来源，依赖成员来源通过 resolveDataSource 派生，两者互斥；清空地区时 resolver 返回 undefined，暂停请求并保留过期选项快照，恢复地区后重新加载并可再次选择。追加长度规则与 required 同时生效；清空显式初始值再重置时，备注使用 defaultValue 工厂的非空默认值，随后隐藏并 clear 仍清为空值。

依赖来源、隐藏与重置 ​

成员字段也可独立切换必填、枚举规则、布尔／函数隐藏和禁用；固定来源与派生来源使用相同字段策略。隐藏后暂停成员验证，重新显示恢复必填；禁用保留值并继续验证，不能用禁用跳过必填。非空成员默认值仅用于 schema 重置，隐藏清值仍使用 Select 的 null 空值。固定来源下改变地区时，依赖 retain／clear 控制当前成员值，来源仍保持原预建 API。

依赖来源、隐藏与重置 ​

成员显示配置可切换 schema 的 label 与 componentProps.placeholder，并恢复原标签和占位文案。成员仍使用注册的 RemoteSelect，选择只更新 member 字段，保留地区及备注；读取成员配置可确认 getField('member') 与 fields 中的同一公开字段上下文、原生 prop 和字段总数。

布局、自定义注册和兼容字段 ​

完整示例用 custom:status 注册真正只发出 yes/no 的包装控件，componentProps.caption 为必填；宽 Input 不能代替窄枚举控件。布局按钮切换 inline、labelPosition、labelMode 和两档表单尺寸，sr-only 保留可访问名称。校验使用基础 rules 与 scrollToError，拒绝由调用方处理，validate 事件保留字段及结果。append 插槽放置字段后的内容。

布局、自定义注册和兼容字段 ​

完整布局场景记录四个公开事件：update:modelValue、search、reset 保留具体模型快照，validate 保留字段、布尔结果和消息。default 无scope且位于生成字段之前；append 无scope；actions 提供零参数 search/reset，在示例中显式调用，不把 MouseEvent 当作字段参数。schema 和兼容 fields 都可检查上述行为。

布局、自定义注册和兼容字段 ​

滚动区域将字段放在视口下方，便于观察校验失败后的定位。scrollToError 控制校验是否自动滚到首个无效字段，省略时默认 false；scrollIntoViewOptions 接受 true、false 或原生 ScrollIntoViewOptions 对象，省略或设为 undefined 时使用默认 true。对象示例使用 behavior=auto、block=center；布尔 false 是原生滚动对齐参数，不是关闭滚动。关闭自动校验滚动后仍可调用 scrollToField('name')，不存在的字段不触发滚动。resetFields(['name']) 或 resetFields('name') 只重置姓名并保留状态，resetFields() 重置全部字段；actions.reset 是无参数回调，reset 事件返回模型。

布局、自定义注册和兼容字段 ​

同一完整示例在 schema 和兼容 fields 两种模式中保留具体实例控制。 validate() 的无回调拒绝由调用者处理；validate(callback) 将 valid 与无效字段集合传给回调， 可以观察失败的 name 与成功时的空集合。clearValidate('name') 或 clearValidate() 清除对应 验证显示并保留当前模型；它不会把无效输入改成有效值。setFieldsValue({ name: 'Patched' }) 仅更新姓名并保留状态，后续仍可校验或按子集/全部重置。

布局、自定义注册和兼容字段 ​

原生 Form 的 model 由 ASAM 的具体类型 v-model／modelValue 承接，不能再传 model 绕过事务。inline 可开启并恢复非行内，labelWidth 支持数字和文本宽度，size 使用 ASAM 四档并传给原生输入。validate 事件保留字段、布尔有效性和错误文字；default 插槽无参数，位于生成字段之前且不替换字段。公开 validate 同时保留 Promise 与 callback：无回调的失败拒绝由调用者处理，回调失败带无效字段集合，成功带空集合。

布局、自定义注册和兼容字段 ​

原生 rules 可为字段提供单条规则或规则数组。原数组保留 required 与 min=2，切换单条规则使用 min=5。validateOnRuleChange=true 时规则切换立即触发原生校验；false 时既有错误与模型保持，手动 validate 仍按当前规则工作。恢复数组规则和自动校验后，无效／有效状态按当前模型恢复；此开关不禁用输入变化或手动校验。

布局、自定义注册和兼容字段 ​

嵌套 FormItem 示例通过默认插槽追加 profile.nickname；字符串和分段数组路径均注册到同一表单。控件使用显式 for/id、标签与错误作用域插槽；可独立调整标签位置/宽度、四档尺寸、required/rules、showMessage/inlineMessage、外部 error 与 validateStatus。单条 blur 规则和数组 blur/change 规则演示 trigger 过滤；公开实例 validate 的 Promise 与回调、validateState/validateMessage/size、clearValidate、setInitialValue/resetField 以及表单嵌套初始值/重置均可操作。关闭后恢复原 name/status 模型和字段数，不影响原默认示例。

布局、自定义注册和兼容字段 ​

FormItem 自动标签宽度和必填继承：在布局示例启用嵌套字段后，可将表单和字段的 label-width 同时设为 auto，并切换短、长标签，原生标签包装器根据实际标签宽度更新对齐。required=false 会覆盖规则中的 required=true，空值仍可通过；required=true 即使没有 rules 也会生成必填校验。传入 undefined 或完全省略 required 都继承已有规则。示例分别提供显式、undefined、省略三种绑定，并显示是否存在 required 自有键；字段无回调校验记录 Promise，回调校验记录 valid 和字段键，读取状态可查看原生字段状态和消息。

布局、自定义注册和兼容字段 ​

动态字段组合采用 Email 的 required/type:email 规则与 domains.index.value 嵌套必填路径。新增与删除按稳定 key 管理，索引变化后由当前公开 FormItem prop 重新对应字段。submit 记录真实无回调 Promise 或回调 valid/fields；resetFields 重置当前仍挂载字段的初值，不重建已经删除的数组成员。示例可读取 fields/getField 的公开状态与分段路径身份，空数组时只校验邮件字段。

布局、自定义注册和兼容字段 ​

原生基础表单组合保留活动名称、两个区域、日期/时间、即时配送、四种活动类型、两种资源、活动正文以及 Create/Cancel。文本域由独立 AsamTextarea 承接，其他输入均用公开 ASAM 控件；本组合显式设置 value-format=""，日期和时间保持原生 Date 模型；基础日期/时间控件未设置 value-format 时使用原生 Date 模型，schema 的标量日期/时间注册项由 Form 显式配置字符串格式，Create 记录具体提交快照，Cancel 沿原例不添加业务动作。行内组合保留 Approved by、区域、日期和 Query，三个控件都可实际清除；本行内组合保留原生清空结果，不将基础空值统一改写为 null，查询记录清除后的当前模型。两个组合均在原默认示例之外单独启用。

布局、自定义注册和兼容字段 ​

完整原生规则组合保留初始 Hello、姓名 required/3到5长度、区域/数量、原生 Date 型日期和时间、地点、非空数组活动类型、资源及正文。数量由公开 AsamSelectV2 消费 10000 个规范化选项，地点由 AsamSegmented 承接；Date/时间显式 value-format=""，文本域继续使用独立 AsamTextarea。Create 记录 callback 的 valid/fields 与实际 Promise 终态，成功才保存当前提交快照；额外按钮观察无回调拒绝，Reset 恢复挂载时 Hello 与其余空基线并清除字段校验。配送无必填规则，false 不列入无效字段。

布局、自定义注册和兼容字段 ​

原生 FormItem 校验成功时，validateState 为 success、validate 事件消息为空，公开 validateMessage 仍可保留上一条错误文字；成功时错误区域不显示。clearValidate/resetFields 才清除公开消息和校验状态，不应把事件消息与实例的最后错误文字混为一项。

布局、自定义注册和兼容字段 ​

控件注册示例通过 defineAsamControl 创建 custom:code，声明字符串模型、无数据源、必填 placeholder、独立 emptyValue 工厂及可选 suspendable。注册配置与复制的 sourceKinds/requiredProps 数组被冻结；调用者数组后续改变不影响注册对象。createAsamSchema<Model>()(registry) 负责匹配模型与注册控件类型，field 返回同一配置对象，不能代替 AsamForm 的运行时校验。实际表单示例输入、校验和 reset 到 Default；约束检查演示无效注册配置产生 config 错误。isAsamControl 与 RuntimeControl 属于内部实现，当前不作为根入口公开 API 使用。

布局、自定义注册和兼容字段 ​

公开 AsamSchemaField 除固定／派生来源联合，还根据注册控件的必填属性决定 componentProps 是否可省略。联合分支示例用 Input 和 custom:code 展示可省略／必填属性各自的固定与 resolver 四种组合：无数据源控件可省略来源或 resolver 返回 undefined，仍正常输入、校验和按工厂重置；必填注册属性不能因改用 resolver 而省略。明确 undefined 的可选来源字段不构成两个有效来源冲突；非 undefined 的来源／resolver 互斥，Prepared API 来源与只读依赖、保留／清除、暂停恢复等完整路径继续见依赖示例。

布局、自定义注册和兼容字段 ​

AsamControlSource 是四类工厂来源的 opaque 公共类型；只有 kind 的对象不能替代工厂来源。控件来源类型示例在独立 runtime/context 中真实解析 static、api、request、dict，保留实际来源和不可变结果，再由表单 Select 消费解析快照，真实选择、校验和默认重置。它不会自动让自定义控件具备来源加载器，组件仍需实现自己的消费路径。AsamSourceKindTuple<K> 在 K=never 时是空元组，非空联合时恰好覆盖每个种类一次且可任意排序；示例公开注册四类全 24 种顺序、空/单项/双项元组，验证冻结复制及重复/未知/非数组的运行时拒绝。运行时注册看不到泛型 K，缺项约束由静态元组检查承担，不把合法子集误报为运行时非法。

布局、自定义注册和兼容字段 ​

AsamDataRuntime 与 createAsamDataRuntime 是应用局部的数据协调契约。完整运行时示例通过公开入口真实运行默认构造、延迟安装、同对象重复安装、禁止替换、只读 provider/scope/epoch、冻结 context、身份检查、独立取消、scope 切换、epoch 失效、订阅与取消订阅、错误报告和回收；构造与这些协调动作不会发起 transport。scope 必须是非空字符串；provider 的 request/upload/adaptOptions/adaptPage/onError/isErrorNotified、dict 与 pagination 在构造和 install 中同样验证。重复 setScope 不失效，变更 scope 和 invalidate 同步中止所有当前 context；release 可重复，结构相同的外部 context 不会成为本 runtime 的当前请求。

布局、自定义注册和兼容字段 ​

reportError 只处理当前 context，保留 kind/message/cause，给报告附上当前 requestId 并冻结。相同错误在同一 epoch 内跨 context 去重，invalidate 清空该缓存。宿主 isErrorNotified 返回 true 或输入已标记 notified 时跳过 onError；当前错误在调用 onError 前登记以阻止递归。没有通知钩子时仍返回标准化未通知结果；过期或外部 context 返回输入原对象且不触发钩子。示例没有吞掉产品控制台错误：抛错的失效订阅者及抛错/异步的通知钩子另外在真实普通安装包的隔离 Node 故障测试中观测，验证其他订阅者继续执行、原始失败保全、同步回调边界、递归与去重和零未处理 Promise 拒绝。异步 onError 返回在 TypeScript 的 void 回调兼容规则下可能可赋值，运行时依然要求同步完成；不把静态类型描述成其没有实现的拒绝能力。

布局、自定义注册和兼容字段 ​

确定性模拟示例完整使用公开 AsamMockStep、AsamMockCall、AsamMockProviderOptions、AsamMockProvider 和 createAsamMockProvider。request 路由键是“method URL”（省略 method 时为 get），dictionary 用类型键，refresh 只有显式提供队列才存在；空队列表示存在但已耗尽。每步 data/error 可带 Promise 等待门；排队数组在创建时复制，不隐式重复，不使用计时器、随机数据或网络。响应和 request 配置深复制冻结，calls 每次返回新的冻结数组和冻结 call，context 仍链接真实请求生命周期。错误步骤和等待门拒绝返回原始原因；等待中取消立即结束且已取走该步，已取消 context 在取步前拒绝，不消耗队列。示例真实验证数据/错误/耗尽、显式 method、缺失路由、字典/刷新、门释放/拒绝、取消前后消费及上下文回收。

布局、自定义注册和兼容字段 ​

page 要有 own list/total；list 是实际对象数组，稀疏 holes 也拒绝，total 为非负安全整数，total0 时 list 必须为空，正 total 可有空 list。不会猜测 data/rows 等未知包装或把非法响应变成空列表。结果及列表/raw 元数据深复制冻结。resolveAsamPage 的公开重载分别是 response+同步 transform 两参数，或 response+undefined+可选 provider 三参数；无 transform/adapter 时验证原响应，显式 transform 负责解包装，否则可用 provider.adaptPage。动态不受类型约束的三参数组合中 transform 优先于 adapter，但示例不把该组合描述成合法静态重载。同步 transform 抛错保留原 cause 并标记 transform，adapter/默认响应错误标记 response；无效返回保持对应阶段且附带规范化失败。异步 transform/adapter 按同步规则拒绝，以同步守卫失败为 cause，并处理 Promise 拒绝以免泄漏 unhandled rejection；真实普通安装包的四个隔离 Node 故障场景另行验证此边界。

布局、自定义注册和兼容字段 ​

完整来源工厂示例通过公开 defineAsamOptions、defineAsamDictSource 和 resolveAsamOptions 展示 static/api/request/dict 四类来源。无泛型工厂使用 AsamValue/AsamRecord，允许默认 label/value；显式 value/raw 泛型工厂要求字段映射，API 和 URL 还要求同步 transform。API 的 params 和 transform 输入由 API 函数推断，不能用其他字段扩大它们；URL transform 收到 unknown，宿主负责可靠地收窄。dictValueType 缺省 string，显式 number/boolean 改变解析结果 value 的静态类型，raw 保留字典原始值。AsamSourceKind 是四种来源的封闭联合。

布局、自定义注册和兼容字段 ​

工厂构造不发送请求。每个来源只有冻结的 kind 可见，类型品牌隐藏在类型层，实际执行身份由工厂登记；手写 kind 对象、展开复制和 Proxy 包装均不能代替原来源。AsamSourceDescriptor 是公开只读类型，其 identity 为对象或字符串，input、transform、fields、cache、dictType、dictValueType 均有明确类型；内部描述符读取函数在包根仅作为类型导出，不是可调用的根值 API。不要通过扩展包根或给来源对象添加 loader 来绕开工厂。

布局、自定义注册和兼容字段 ​

构造配置必须是非数组对象，options/data/api/request/dictType/dataSource 中恰好一个已定义来源且匹配当前工厂，匹配值不能 null。额外非 undefined 键拒绝；额外 undefined 键允许，当前构造器也接受继承的来源属性，示例将此与规范化数据必须有 own 字段的规则分别呈现。cache 仅用于 API/URL，ttlMs 为正安全整数，key 若提供必须是函数；static/dict 不接受 cache。自定义远程 fieldNames 必须伴随 transform，即使 provider 有 adaptOptions 也先执行这项构造校验。fieldNames 构造时复制冻结；params、request、cache 与静态 options 保留宿主引用，不深冻结宿主。static 每次解析读取当前 options，并返回独立的深冻结快照，构造不会提前验证 options 列表内容。

布局、自定义注册和兼容字段 ​

API 接收原始 params 对象与请求上下文。 URL 先验证非空 url、get/post/put/delete 方法及非数组对象 params；缺省方法 get，get 不能有 data。解析时再次验证宿主 request，发送浅复制配置，保留 params/data 引用和原 context。URL 必须有 provider.request；字典必须有 provider.dict.get，并传递原 dictType（非空白但不主动 trim）和 context。API/URL 的显式 transform 优先于 provider.adaptOptions，否则使用原响应；字典使用其固定字段和严格值转换，不借用远程 adapter。

布局、自定义注册和兼容字段 ​

resolveAsamOptions 只完成单次管线：必须传入 context，可附 provider、tree、valuePolicy、separator。远程规则先于 IO 验证；provider 能力缺失和无效配置不会发出 transport。API/provider 必须返回带 then/catch 的 Promise 接口，不能直接返回数组；同步 transport 抛错和 Promise 拒绝记为 request 并保留原 cause，非 Promise 返回记为 response。显式 transform 失败记为 transform，adapter/原响应/字典转换失败记为 response；static 规范化错误记为 config。异步 transform/adapter 会被同步守卫拒绝并消费其 Promise 拒绝；这些错误不是成功空列表。

布局、自定义注册和兼容字段 ​

已取消的 context 立即以 signal.reason 拒绝且四类来源均零 IO；请求中取消及时拒绝，后端忽略取消时迟到成功和迟到失败都不能触发 transform 或恢复结果。cache 元数据不使此函数自动缓存，重复调用仍发两次 IO，也不调用 cache.key；cache/share、响应式来源替换、stale、错误恢复、模型同步和资源释放由状态消费者负责。完整 TS/JS 示例含 16 个观察组、61 个构造拒绝、9 个传输错误、8 个解析分支和两种迟到回包；原有 Form 和所有公开来源组合保持可运行。

布局、自定义注册和兼容字段 ​

字典共享同一 runtime 的来源 identity；force 需要 provider.dict.refresh，缺失时返回 config 错误。一次刷新成功后重新加载受影响的字典，等待同次刷新的消费者不重复刷新。失败保留旧快照、标记 stale，并向有效消费者交付一次已报告的结构化错误；中途加入的新字典组保留同一报告与 notified 标记。失败交付先登记消费者，再调用 onError，因此本地回调内重新加载、先前等待者加入新组和互相触发的有限重试不会重复交付同次错误。示例覆盖旧组、新组、取消、epoch 切换、成功刷新及恢复；旧普通包的重复回调故障记录保留，修复后的正常本地安装候选已通过这些 DEV 检查。

布局、自定义注册和兼容字段 ​

远程搜索应同时在响应式 source 参数中表达当前搜索词，并提供 searchText；连续改变搜索词时取消旧等待，用最后输入发请求。debounceMs 是非负安全整数，缺省250ms，0立即请求；reload 可直接触发本次加载，cancel/active 切换/销毁清除当前等待。scope 或 epoch 失效清空快照/错误/成功标记与缓存键，再按当前配置建立新请求，旧回包不能回写。onSuccess 接收完整规范化选项且与当前 data 是同一成功快照，onError 接收当前结构化错误。AsamReloadResult 分为 success(data/fromCache)、error(error) 和 cancelled，无 pending 分支。

布局、自定义注册和兼容字段 ​

完整 TS/JS 分段实测29组观察，包括真实250ms默认防抖、25ms配置防抖/0、200ms TTL命中/过期、共享请求、force、刷新失败与恢复、identity、策略和生命周期。TS、JS与实际 Form Layout Story均在修复后的正常本地安装包上执行29组相同结果，包括真实挂载注入与卸载；隔离Node执行其中28组并检查未处理拒绝，9条刷新重入回归另行执行。这里记录本角色DEV验证，整卡独立QA与ACC仍按原完整15组件范围进行。

选项值与字段映射的公开类型 ​

完整 layout-registry TS/JS 示例中的规范化与来源分段承接上述类型：展示所有标量类型、原始记录和元数据快照、树与直接字段映射，以及三种字典值转换、非法形状与配置拒绝。公开类型夹具为每项提供明确的合法赋值和不合法用法；类型检查不代替这些已有的真实运行时观察，也不把静态可表达的 NaN 当成运行时合法选项。

请求、字典与通用控制的公开协议 ​

AsamRequestContext 提供只读 signal/AbortSignal、requestId/number、scope/string 和 epoch/number。createContext() 创建真实冻结对象，序号在所属 runtime 内递增；释放、scope 切换和显式失效会终止所属 signal。结构上相同的外来对象不能代替该 runtime 登记的 context。API 与 provider 接收原 context，不复制或改写它；类型只约束形状，不能用静态 number/string 字段证明运行时归属。

请求、字典与通用控制的公开协议 ​

AsamApiRequest<P, R> 是 (params: P, context: AsamRequestContext) => Promise<R>。P/R 保留宿主泛型，P 不限于某个业务对象；直接同步返回响应不符合契约。来源管线还会检查实际 Promise 接口、同步抛错、拒绝和取消，并将迟到回包隔离；参数对象身份与 context 身份由示例实际验证。API 回调不会因声明泛型而自动转换响应。

请求、字典与通用控制的公开协议 ​

AsamDataControls<T> 只包含只读 reload 和 cancel 方法引用。reload 接收可选 { force?: boolean }，返回 Promise<AsamReloadResult<T>>；cancel 无参数且返回 void，不把取消结果作为它的返回值。完整选项状态示例将等待中的 reload 结算为 cancelled，并检查回包、回调与保留快照；这些状态生命周期由具体消费者提供，不能仅从通用控制类型推断额外状态成员。

控件注册的内部边界 ​

应用使用公开 AsamControl、defineAsamControl 和 createAsamSchema；合法注册对象由工厂创建。内部 isAsamControl 依赖私有 WeakSet，不是可公开复用的结构判断；RuntimeControl 是运行时内部形状，根入口既不导出该类型，也不导出上述判断函数。内部 Schema 深路径不在包 exports 中，应用不应通过深路径绕过品牌或注册。完整示例通过公开工厂与实际表单消费这一边界。

注册子控件的局部请求错误 ​

Form 通过既有控件注册与字段模型承接高级子控件的 error 插槽。本例注册 RequestSelect 子控件，在其 RemoteSelect 内定制 { error, stale, retry }；错误对象 沿用子控件原 AsamDataError，无参数 retry 返回其强刷 reload 的 Promise。 初次失败与保留旧数据后的更新失败均局部展示，等待 success/error/cancelled 后更新 结果说明，不把请求失败写成字段校验错误，也不改变父模型。

更多参数与事件说明 ​

布局、自定义注册和兼容字段 ​

兼容按钮在独立实例之间切换 schema 和 fields：旧 fields 使用 key/type/options，仍支持输入、选择、验证及重置；它不提供 createAsamSchema 的字段和控件双向类型检查，新表单继续使用 schema。两种模式均由同一 v-model 管理真实模型，不同时提供 schema 和 fields。

布局、自定义注册和兼容字段 ​

顶层配置在 schema／registry 与兼容 fields 两种方式下共同演示 v-model、inline、数字／文本 labelWidth、visible／sr-only labelMode 和 large／big／default／small 四档尺寸；尺寸由表单传给未单独设尺寸的输入控件。勾选使用内置操作后移除 actions 插槽，showSearch／showReset 独立控制两个按钮，searchText／resetText 切换默认与自定义文案；查询在配置有效时直接发出当前模型，不自动验证字段；需要验证时由调用方显式调用 validate。重置恢复初始模型。取消内置操作后恢复原 actions 插槽。

布局、自定义注册和兼容字段 ​

原布局示例还可独立切换原生 labelSuffix、hideRequiredAsterisk、requireAsteriskPosition、showMessage、inlineMessage、statusIcon 和 disabled。这些属性由 AsamForm 统一交给其 AsamBaseForm 实例：隐藏错误文字不取消校验失败，状态图标跟随真实校验结果，取消禁用后原生姓名输入继续更新当前模型。自定义注册控件应自行消费表单上下文或明确的 disabled 契约；示例中的窄枚举原生 radio 不声明此能力。

布局、自定义注册和兼容字段 ​

示例另记录无回调 validate() 的实际 Promise 终态：有效模型 fulfilledValue=true，无效模型 settledKind=rejected 并保留 rejectionFields 中的 name。invalid 状态文字本身不能区分 fulfilled false 与 rejected；上述终态记录用于确认公开 Promise 契约，不改变原 callback 的 valid/fields 记录。

布局、自定义注册和兼容字段 ​

原生实例按钮读取 fields 与 getField 的公开字段上下文：字符串 name 和分段路径数组指向同一上下文，不存在的路径返回 undefined，字段列表仍包含当前 name/status，fieldValue 跟随模型。validateField 可按字符串、字段数组或省略参数校验；无回调的有效模型 fulfilled true，无效模型 rejected 并记录 name。回调返回 valid/fields，失败回调 false/name 后 Promise fulfilled false，成功为 true/空集合。setInitialValues 只设置后续 resetFields 的基线，不立即修改当前模型；重置采用新基线，随后可恢复原空姓名/no 基线。

布局、自定义注册和兼容字段 ​

原生表单方法的嵌套补充通过 AsamForm 公开 receiver 操作 profile.nickname：getField 点分字符串与多段数组返回同一当前上下文，缺失嵌套路径返回 undefined；validateField 的字符串和嵌套分段数组选择器仅校验目标，排除的无效兄弟字段保持原错误/状态且不发该字段的新校验事件，validateField() 则拒绝准确全部无效字段。无回调 Promise 与回调 valid/fields 分别记录实际终态。setInitialValues 的映射分两类：schema/兼容 fields 管理字段的遗漏项在 resetFields 时继续按已确认 ASAM defaultValue 工厂/emptyValue 或兼容默认值恢复；默认插槽注册的原生字段由 native setInitialValues 设置基线，遗漏的 slot 字段基线为 undefined，slotResetPatch 在重置时读取它。混合提供与遗漏场景不立即修改模型，重置采用相应基线，再恢复完整初始值；不把 native 遗漏 undefined 强加给 ASAM 管理字段。

布局、自定义注册和兼容字段 ​

自定义校验与数字校验示例通过 AsamForm + AsamFormItem 组合：密码/确认密码交叉规则、修改密码后重新校验确认字段、异步整数与成年年龄回调；数字输入沿 Vue .number 的 parseFloat 语义转换，空值/非数字保留原字符串供 required/type:number 报错。无回调提交记录实际 Promise，回调提交记录 valid/fields，字段状态可读取，resetFields 恢复原基线。原默认例子不启用此区域；native slot profile.nickname 类型允许遗漏值，匹配前轮已经验证的 undefined 初始值语义。

布局、自定义注册和兼容字段 ​

标签对齐组合示例包含两个位置选择器和 姓名、活动区域、活动形式 三字段：Form left/right/top 与 FormItem 空值继承、left/right/top 可组合；两个选择器的字段标签固定 right，独立于表单位置。可访问性组合中，完整姓名 自动关联单一 AsamInput；您的信息 在多输入时由原生 FormItem 生成 group/aria-labelledby，每个 AsamInput 分别设置 名字、姓氏 aria-label，placeholder 仅为输入提示，不替代名称。

布局、自定义注册和兼容字段 ​

原生尺寸组合通过公开 RadioGroup/RadioButton 切换 large/big/default/small 与 left/right/top；表单传递密度到输入、选择、日期/时间、复选按钮、带 border 的单选和操作按钮。保留两个活动类型和两种资源，Date/时间显式 value-format=""；改变尺寸和标签位置不重置当前模型，Create 记录具体快照，Cancel 保持原例行为。

布局、自定义注册和兼容字段 ​

AsamComponentProps<P> 保留 P 的非保留属性、必填和 readonly 约束；十三个 AsamReservedControlProp 为 modelValue、update:modelValue、onUpdate:modelValue、options、api、request、dictType、dataSource、transform、multiple、valueMode、multipleValueMode、separator，全部禁止通过 componentProps 注入。控件属性边界示例逐项把外部原始 schema 的保留键交给公开 AsamForm，配置错误出现前不会挂载控件或调用来源解析，当前模型保持不变；恢复合法 placeholder、maxlength、clearable 后可继续真实输入、校验和默认重置。不要用原始 schema 的宽松输入类型替代 createAsamSchema 的静态安全约束。

布局、自定义注册和兼容字段 ​

AsamDataFailure 是 Error 子类，保留 config/request/response/transform/upload 类型、message、可选原 cause，name=AsamDataFailure 且 notified 初始 false；readonly 是公开类型约束，构造实例本身不会自动冻结。低层失败是否通知仍由当前 runtime/context 的报告规则决定，模拟器不擅自通知宿主。Body 与 TS/JS 源码明确这些边界，不把 Error 构造器描述成运行时 kind 验证器。

布局、自定义注册和兼容字段 ​

选项与分页规范化示例完整调用公开 normalizeAsamOptions、normalizeAsamPage、resolveAsamPage，并提供 AsamMapping 与 AsamOptionRules 的完整类型/实际配置。mapping 的 label/value 必需，disabled/children 可选，字段名是直接 own key，“name.label”不表示路径；字段名本身只要求非空字符串，label/value 可映射同一个键。数据 option 必须是对象，label 为字符串，value 为 string/boolean/有限 number；空 label/value 在普通模式合法。disabled 只能 boolean 或 undefined，children 只能数组或 undefined；非空 children 需要 tree 模式。值按类型保留，整棵树全局去重并拒绝祖先循环；空 children 可用于平面 options。规范化深复制/冻结结果和 raw，不冻结或改变宿主输入。

布局、自定义注册和兼容字段 ​

规则支持 single value/object、multiple value array/string、multiple object array 五种合法策略；single 不能带 multipleValueMode，object multiple 不能 string。separator 为非空字符串，string 模式按完整 separator 检查，不按字符拆解；拒绝空 token、包含完整 separator 和 String(value) 碰撞，数字1与字符串“1”在普通模式不同而在 string 模式冲突。dictionary string/number/boolean 转换使用严格规则并保留 raw 的原始值；number 不接受空白/任意字符串或 boolean，boolean 只接受 true/1/“true”/“1”及对应 false/0 形式。各 boolean 别名单独转换有效，合并后重复值仍被拒绝。TypeScript number 无法表达有限性，运行时还会拒绝 NaN/Infinity；unknown 输入的形状由规范化器验证，不把其静态参数误称为已经验证的数据。

布局、自定义注册和兼容字段 ​

选项状态分段通过 useAsamRemoteOptions/useAsamDictOptions 展示 AsamOptionsState 的完整 data、loading、error、stale、hasSucceeded、empty、dataKey、requestKey、reload 和 cancel。公开引用和方法在类型上只读，宿主不应修改 value；成功的规范化 data/raw 自身是独立深冻结快照。初始尚未成功不算 empty；成功空列表才算 empty，加载中或有错误不算 empty。失败保留最近成功数据并标记 stale，成功重试清除 error/stale；取消和销毁终结等待中的 reload，不产生迟到成功回调。配置错误先于 IO 处理，相同 kind/message 的连续无效来源不重复发布本地错误回调；有效来源恢复后可重新加载。

布局、自定义注册和兼容字段 ​

AsamOptionsStateConfig.source 可用原来源、ref 或同步 getter；active、valuePolicy、separator、searchText、debounceMs 同样支持相应值/ref/getter。remote 仅接受 api/request，dict 仅接受 dict；static 来源由静态消费者处理。runtime 可显式提供，在组件 setup 内也可使用 provideAsamData 关联的 app runtime；组件外没有显式 runtime 会拒绝。immediate 缺省启动，false 只建立来源/请求键并等待 reload；active=false 取消请求并保留成功快照为 stale，inactive reload 返回 cancelled，恢复 active 后按 immediate 规则接续。tree 要在选项规范化时处理整棵树，策略或 separator 变化形成新的键；字符串 token 歧义是 response 错误，不把保留数据误作当前成功数据。

布局、自定义注册和兼容字段 ​

source 的缓存元数据在这里生效：同 runtime、scope、epoch、来源/参数/映射/transform/策略/tree/separator 等完整 identity 的带缓存远程消费者共享请求与结果，单个 cancel 不终止其他消费者；未带缓存的远程消费者保持隔离。缓存 key 默认序列化输入，带缓存时 Date/Map/循环等非普通可序列化输入拒绝，也可由同步自定义 key 返回非空字符串；无缓存时无法序列化输入退回来源对象 identity。TTL 为真实时间期限，普通 reload 在期限内可返回 fromCache=true，过期或 force 重新请求。force 取代旧普通请求，同次进行中的强制请求可被后继消费者共享。

请求、字典与通用控制的公开协议 ​

AsamRequestConfig 必需 url/string，可选 method/get/post/put/delete、params/AsamRecord 和 data/unknown，公开字段只读，缺省 method 为 get。类型不表达非空 URL 或 GET 不带 data 的规则；来源在 IO 前验证这些规则以及 params 的实际形状。data 为 unknown，宿主仍需可靠收窄；URL 管线发送浅复制配置并保持原 params/data 和 context，不伪造业务 payload。

请求、字典与通用控制的公开协议 ​

AsamDataError 必需 kind/config-request-response-transform-upload、message/string、cause/unknown 和 notified/boolean，requestId/number 可选；所有已声明字段只读。cause 保留原原因，读取前需收窄。当前 runtime 对有效 context 的同一错误去重、按宿主通知责任更新 notified，并提供真实 requestId 和冻结的报告；过期或外来 context 不触发新通知。此结构类型不执行错误阶段验证，也不意味着原 cause 对象被深冻结，upload kind 的存在不代替上传功能验证。

请求、字典与通用控制的公开协议 ​

AsamDictionaryProvider.get(dictType: string, context) 必需返回 Promise<readonly AsamDictEntry[]>；refresh 可选，若提供则为 (context) => Promise<void>。get/refresh 是方法成员，其类型不声明方法引用只读。字典来源验证非空 dictType，保留原类型键与 context，使用固定 label/value 字段和严格值转换。普通读取可不具备 refresh；force 在缺少 refresh 时返回配置错误，同次刷新、失败交付、恢复与取消由选项状态分段完整验证。

继承能力

本入口的独有 API 见上表，基础能力见本站对应页面。

基础表单 AsamBaseForm
表单项 AsamFormItem远端选择器 AsamRemoteSelect字典选择器 AsamDictSelect
参数与事件补充说明

参数与事件说明

modelValue

必填：是；声明来源：ASAM 声明。

fields

必填：否；声明来源：ASAM 声明。

schema

必填：否；声明来源：ASAM 声明。

registry

必填：否；声明来源：ASAM 声明。

inline

必填：否；声明来源：ASAM 声明。

inline 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
true（源码表达式；ASAM 声明）
labelWidth

必填：否；声明来源：ASAM 声明。

默认值与来源
'auto'（源码表达式；ASAM 声明）
showSearch

必填：否；声明来源：ASAM 声明。

showSearch 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
true（源码表达式；ASAM 声明）
showReset

必填：否；声明来源：ASAM 声明。

showReset 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
true（源码表达式；ASAM 声明）
searchText

必填：否；声明来源：ASAM 声明。

默认值与来源
'搜 索'（源码表达式；ASAM 声明）
resetText

必填：否；声明来源：ASAM 声明。

默认值与来源
'重置'（源码表达式；ASAM 声明）
labelMode

必填：否；声明来源：ASAM 声明。

labelMode 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："visible" / "sr-only"

默认值与来源
'visible'（源码表达式；ASAM 声明）
disabled

必填：否；声明来源：上游声明。

disabled 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：false（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

size

必填：否；声明来源：ASAM 声明。

size 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："large" / "big" / "default" / "small"

scrollIntoViewOptions

必填：否；声明来源：上游声明。

scrollIntoViewOptions 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

  • scrollIntoViewOptions.block: ScrollLogicalPosition | undefined — 依赖声明

    枚举："start" / "center" / "end" / "nearest"

  • scrollIntoViewOptions.inline: ScrollLogicalPosition | undefined — 依赖声明

    枚举："start" / "center" / "end" / "nearest"

  • scrollIntoViewOptions.behavior: ScrollBehavior | undefined — 依赖声明

    枚举："auto" / "smooth" / "instant"

默认值与来源
true（源码表达式；ASAM 声明）

固定上游文档默认：true（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码默认表达式：true（2.14.7；源码事实，未作为 ASAM 运行实测）

rules

必填：否；声明来源：上游声明。

默认值与来源
未知 / 未声明

固定上游文档默认：未声明（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码未声明 default（2.14.7；源码事实，未作为 ASAM 运行实测）

labelPosition

必填：否；声明来源：上游声明。

labelPosition 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："top" / "right" / "left"

默认值与来源
未知 / 未声明

固定上游文档默认：right（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码默认表达式：'right'（2.14.7；源码事实，未作为 ASAM 运行实测）

requireAsteriskPosition

必填：否；声明来源：上游声明。

requireAsteriskPosition 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："right" / "left"

默认值与来源
未知 / 未声明

固定上游文档默认：left（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码默认表达式：'left'（2.14.7；源码事实，未作为 ASAM 运行实测）

labelSuffix

必填：否；声明来源：上游声明。

默认值与来源
未知 / 未声明

固定上游文档默认：''（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码默认表达式：''（2.14.7；源码事实，未作为 ASAM 运行实测）

inlineMessage

必填：否；声明来源：上游声明。

inlineMessage 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：false（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

statusIcon

必填：否；声明来源：上游声明。

statusIcon 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：false（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

showMessage

必填：否；声明来源：上游声明。

showMessage 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：true（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码默认表达式：true（2.14.7；源码事实，未作为 ASAM 运行实测）

validateOnRuleChange

必填：否；声明来源：上游声明。

validateOnRuleChange 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：true（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

固定上游源码默认表达式：true（2.14.7；源码事实，未作为 ASAM 运行实测）

hideRequiredAsterisk

必填：否；声明来源：上游声明。

hideRequiredAsterisk 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：false（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

scrollToError

必填：否；声明来源：上游声明。

scrollToError 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

默认值与来源
false（隐式 Boolean 默认；已安装组件）

固定上游文档默认：false（2.14.7；文档事实，实际默认以 ASAM 源码 / 安装包为准）

AsamFormProps 公开类型视图
ts
import type { AsamFormProps, AsamFormModel, AsamFormField, AsamFormSchemaEntry, AsamFormActionsProps, AsamFormSectionProps, AsamFormLabelMode, AsamControlSize } from '@asam-ui/ui';

type PublicMember<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? T[K] : never : never;

// AsamFormProps
type PublicContract<M extends object = AsamFormModel> = {
	"modelValue": M;
	"fields"?: readonly AsamFormField[] | undefined;
	"schema"?: readonly AsamFormSchemaEntry<M>[] | undefined;
	"registry"?: object | undefined;
	"inline"?: boolean | undefined;
	"labelWidth"?: string | number | undefined;
	"showSearch"?: boolean | undefined;
	"showReset"?: boolean | undefined;
	"searchText"?: string | undefined;
	"resetText"?: string | undefined;
	"labelMode"?: AsamFormLabelMode | undefined;
	"disabled"?: boolean | undefined;
	"size"?: AsamControlSize | undefined;
	"scrollIntoViewOptions"?: boolean | ScrollIntoViewOptions | undefined;
	"rules"?: (AsamFormProps<M>)["rules"];
	"labelPosition"?: "top" | "right" | "left" | undefined;
	"requireAsteriskPosition"?: "right" | "left" | undefined;
	"labelSuffix"?: string | undefined;
	"inlineMessage"?: boolean | undefined;
	"statusIcon"?: boolean | undefined;
	"showMessage"?: boolean | undefined;
	"validateOnRuleChange"?: boolean | undefined;
	"hideRequiredAsterisk"?: boolean | undefined;
	"scrollToError"?: boolean | undefined;
};

参数与事件说明

validate

必填：是；声明来源：ASAM 声明。

update:modelValue

必填：是；声明来源：ASAM 声明。

search

必填：是；声明来源：ASAM 声明。

reset

必填：是；声明来源：ASAM 声明。

AsamFormEmits 公开类型视图
ts
import type { AsamFormEmits, AsamFormModel } from '@asam-ui/ui';

// AsamFormEmits
type PublicContract<M extends object = AsamFormModel> = {
	"validate": (AsamFormEmits<M>)["validate"];
	"update:modelValue": [model: M];
	"search": [model: M];
	"reset": [model: M];
};

参数与事件说明

default

必填：否；声明来源：ASAM 声明。

default 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(): unknown

actions

必填：否；声明来源：ASAM 声明。

actions 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(scope: { search: () => void; reset: () => void; }): unknown

append

必填：否；声明来源：ASAM 声明。

append 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(): unknown

AsamFormSlots 公开类型视图
ts
import type { AsamFormSlots, AsamFormModel } from '@asam-ui/ui';

// AsamFormSlots
type PublicContract<M extends object = AsamFormModel> = {
	"default"?: (() => unknown) | undefined;
	"actions"?: ((scope: { search: () => void; reset: () => void; }) => unknown) | undefined;
	"append"?: (() => unknown) | undefined;
};

参数与事件说明

validate

必填：是；声明来源：ASAM 声明。

validate 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(callback?: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["validate"]>, (...args: never[]) => unknown>>[0]): ReturnType<Extract<NonNullable<(AsamFormExpose<M>)["validate"]>, (...args: never[]) => unknown>>

clearValidate

必填：是；声明来源：ASAM 声明。

clearValidate 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(props?: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["clearValidate"]>, (...args: never[]) => unknown>>[0]): void

resetFields

必填：是；声明来源：ASAM 声明。

resetFields 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(props?: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["resetFields"]>, (...args: never[]) => unknown>>[0]): void

setFieldsValue

必填：是；声明来源：ASAM 声明。

setFieldsValue 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(patch: Partial<M>): void

validateField

必填：是；声明来源：上游声明。

validateField 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(props?: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["validateField"]>, (...args: never[]) => unknown>>[0], callback?: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["validateField"]>, (...args: never[]) => unknown>>[1]): ReturnType<Extract<NonNullable<(AsamFormExpose<M>)["validateField"]>, (...args: never[]) => unknown>>

scrollToField

必填：是；声明来源：上游声明。

scrollToField 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(prop: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["scrollToField"]>, (...args: never[]) => unknown>>[0]): void

getField

必填：是；声明来源：上游声明。

getField 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(prop: Parameters<Extract<NonNullable<(AsamFormExpose<M>)["getField"]>, (...args: never[]) => unknown>>[0]): ReturnType<Extract<NonNullable<(AsamFormExpose<M>)["getField"]>, (...args: never[]) => unknown>>

fields

必填：是；声明来源：上游声明。

fields 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

嵌套展开边界：框架 / 平台类型；完整类型见公开类型视图。

setInitialValues

必填：是；声明来源：上游声明。

setInitialValues 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(initModel: Record<string, any>): void

AsamFormExpose 公开类型视图
ts
import type { AsamFormExpose, AsamFormModel } from '@asam-ui/ui';

// AsamFormExpose
type PublicContract<M extends object = AsamFormModel> = {
	"validate": (AsamFormExpose<M>)["validate"];
	"clearValidate": (AsamFormExpose<M>)["clearValidate"];
	"resetFields": (AsamFormExpose<M>)["resetFields"];
	"setFieldsValue": (patch: Partial<M>) => void;
	"validateField": (AsamFormExpose<M>)["validateField"];
	"scrollToField": (AsamFormExpose<M>)["scrollToField"];
	"getField": (AsamFormExpose<M>)["getField"];
	"fields": (AsamFormExpose<M>)["fields"];
	"setInitialValues": (initModel: Record<string, any>) => void;
};

组合契约按分支生效；请同时查看公开类型。

参数与事件说明

field

必填：是；声明来源：ASAM 声明。

component

必填：是；声明来源：ASAM 声明。

label

必填：否；声明来源：ASAM 声明。

required

必填：否；声明来源：ASAM 声明。

required 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

rules

必填：否；声明来源：ASAM 声明。

defaultValue

必填：否；声明来源：ASAM 声明。

defaultValue 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(): M[K]

dependsOn

必填：否；声明来源：ASAM 声明。

hidden

必填：否；声明来源：ASAM 声明。

hidden 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

事件参数：(model: Readonly<M>): boolean

disabled

必填：否；声明来源：ASAM 声明。

disabled 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举：false / true

事件参数：(model: Readonly<M>): boolean

onDependencyChange

必填：否；声明来源：ASAM 声明。

onDependencyChange 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："clear" / "retain"

onHide

必填：否；声明来源：ASAM 声明。

onHide 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："clear" / "retain"

componentProps

必填：否；声明来源：ASAM 声明。

dataSource

必填：否；声明来源：ASAM 声明。

resolveDataSource

必填：否；声明来源：ASAM 声明。

resolveDataSource 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(model: Readonly<M>): ReturnType<Extract<NonNullable<(AsamSchemaField<M, R, K, C>)["resolveDataSource"]>, (...args: never[]) => unknown>>

AsamSchemaField 公开类型视图
ts
import type { AsamSchemaField, AsamCompatibleKey, AsamFormSectionProps, AsamFormActionsProps, AsamComponentProps } from '@asam-ui/ui';

// AsamSchemaField
type PublicContract<M, R, K extends keyof M & string, C extends AsamCompatibleKey<M, R, K>> = AsamSchemaField<M, R, K, C>;

搜索文档

Tab 选择结果 Enter 打开 Esc 关闭