WInputNumber 组件

A2UI Protocol JSON Schema

数字输入框组件，基于 WinDesignNext InputNumber 封装，用于输入数值，支持步进按钮、精度控制、最大最小值限制及数据绑定。

与 WInput 的区别：WInputNumber 专用于数值输入，绑定值为 数字类型；支持 min/max/step/precision 等数值约束，并可通过 path 动态引用 dataModel。

基础用法

Props API

属性名	类型	默认值	说明
id	string	-	组件唯一标识（必填）
component	string	WInputNumber	组件类型（必填）
modelValue	object	-	绑定值（A2UI 数据绑定，支持 path）
min	number/object	-	最小值（支持 path）
max	number/object	-	最大值（支持 path）
step	number/object	1	步长（支持 path）
precision	number/object	-	小数精度（支持 path）
size	string	default	输入框尺寸
disabled	boolean	false	是否禁用
readonly	boolean	false	是否只读
controls	boolean	true	是否显示增减按钮
controlsPosition	string	right	按钮位置（right 或空）
stepStrictly	boolean	false	是否只能输入 step 的倍数
valueOnClear	number/string/null	null	清空时的默认值（可为 min/max）
placeholder	string	-	占位文本
name	string	-	原生 name 属性
align	string	center	内容对齐方式
inputmode	string	-	移动端键盘类型
disabledScientific	boolean	false	是否禁用科学计数法
status	string	-	验证状态样式
tips	string	-	提示文本
validateEvent	boolean	true	是否触发表单验证
action	object	-	A2UI v0.9 事件定义

path 支持说明

通用绑定格式见 path 数据绑定速查。

属性	支持 path	说明
modelValue	✅	双向绑定数值（数字类型）
min / max / step / precision	✅	动态数值约束
action.event.context[].value	✅	事件上下文可引用 dataModel
action.event.api.constParams[].value	✅	API 固定参数可引用 dataModel
placeholder / disabled / size 等	❌	静态配置

min / max / step / precision 绑定示例：

{
  "min": { "path": "/dosageMin" },
  "max": { "path": "/dosageMax" },
  "step": { "literalNumber": 0.5 },
  "precision": { "path": "/numberPrecision" },
  "modelValue": { "path": "/dosage" }
}

通过 updateDataModel 动态调整范围：

{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/dosageMax",
    "value": 20
  }
}

modelValue 数据绑定

modelValue 将数值绑定到 dataModel，变化后写回对应 path。

{ "modelValue": { "path": "/quantity" } }

modelValue 绑定规则：

• 绑定值类型为 数字（如 5、2.5），不是字符串
• 可通过 literalNumber 设置初始值：{ "literalNumber": 10 }
• 清空后值为 null

action 定义

数值变化并确认时触发（失焦、回车或点击步进按钮），默认 type 为 change：

{
  "action": {
    "event": {
      "name": "onQuantityChange",
      "type": "change",
      "context": [
        { "key": "quantity", "value": { "path": "/quantity" } }
      ]
    }
  }
}

数据同步机制

WInputNumber 在数值确认变化后会自动将值同步到 dataModel：

1. Agent 发送 updateComponents 定义组件，modelValue.path 指向 dataModel 路径
2. Agent 发送 updateDataModel 初始化数值和约束
3. 用户修改数值后，渲染器自动调用 setData 更新 dataModel
4. 若配置了 action，同时触发 A2UI 事件

使用场景

场景	推荐配置
整数数量	step: 1 + min/max
小数剂量	step: 0.5 + precision: 1
动态范围	min/max 使用 path 绑定
隐藏步进按钮	controls: false
严格步进	stepStrictly: true

注意事项

• 绑定值为数字类型，与 WInput 的字符串不同
• 默认在 change 事件（失焦/回车/步进）时同步 dataModel，非每次按键
• valueOnClear 可设为 "min" 或 "max"，清空时恢复为对应边界值