界面控件（ui）

壳 App / VS Code「界面设计」中的基础字段，在启动脚本前注入为只读控件对象（启动时快照；脚本内改属性不会回写界面）。设计器里把字段 key 改成合法 JS 标识符后，脚本直接用全局写法：卡密.value、demoMsg.label。TypeScript 声明见 script-typings/uiControlModule.d.ts。

字段key - 全局控件对象

interface UiControl {
 readonly key: string;
 readonly value: string;
 readonly label: string;
 readonly type: string;
}
declare const 字段key: UiControl; // 例：卡密、demoMsg

说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	字段 key 须为合法 JS 标识符，且未占用保留名（如 auto / logger），才会挂到全局

返回字段（UiControl）：

字段名	类型	是否必填	默认值	描述
key	string	是	-	设计器唯一标识，与全局变量名一致
value	string	是	-	启动时快照值；数字 / 开关等一律以字符串注入
label	string	是	''	标签文案；无元数据时为空串
type	string	是	''	控件类型（如 input / switch）；无元数据时为空串

示例：

logger.info(卡密.value);
logger.info(demoMsg.label, demoMsg.type);

---

字段key.key - 唯一标识

readonly key: string;

返回值：

类型	描述
string	与设计器「唯一标识 / key」、壳 setConfig 键一致

示例：

logger.info(卡密.key); // 如 '卡密' 或 'demoMsg'

---

字段key.value - 当前值

readonly value: string;

返回值：

类型	描述
string	启动时快照；数字 / 开关 / 多选等一律以字符串注入，脚本侧自行转换

常见取值：

字段 type	value 示例	脚本侧建议
input / textarea	'hello'	直接使用字符串
number / slider / rate	'3' / '50'	Number(x.value)
switch	'true' / 'false'	x.value === 'true'
radio / select	选项的 value 字符串	与设计器选项 value 比对
checkbox	多选值序列化字符串	按实际序列化格式解析
time / date	格式化时间字符串	按 format / valueFormat 解析

示例：

let times = Number(loopCount.value) || 0;
const on = enableLog.value === 'true';
logger.info(卡密.value);

---

字段key.label - 标签文案

readonly label: string;

返回值：

类型	描述
string	设计器中的标签；无元数据时为空串 ''

示例：

logger.info(卡密.label); // 如 '卡密'

---

字段key.type - 控件类型

readonly type: string;

返回值：

类型	描述
string	基础字段 type，如 input / select / switch；无元数据时为空串

示例：

if (enableLog.type === 'switch') {
 logger.info('开关状态:', enableLog.value);
}

---

基础字段一览

对应界面设计器左侧「基础字段」。每种字段脚本侧都可读 唯一标识.value / .key / .label / .type；下方 options 为设计器配置项（如 defaultValue 仅影响界面初始值，不是脚本属性名）。

type	名称	脚本 .value
input	单行文本	字符串
textarea	多行文本	字符串
number	数字	数字字符串，如 '3'
radio	单选框	选中项 value
checkbox	复选框	多选值序列化字符串
select	下拉框	选中项 value
time	时间	时间字符串
date	日期	日期字符串
rate	评分	分数字符串
switch	开关	'true' / 'false'
slider	滑块	数字字符串
html	富文本编辑器	HTML 字符串
cascader	级联框	选中路径值字符串
uploadfile	上传文件	文件信息序列化字符串
signature	签名	签名数据 / URL 字符串

---

input - 单行文本（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	自动生成	唯一标识；写法 唯一标识.key；请改成合法标识符
label	string	单行文本	标签文案；写法 唯一标识.label
type	string	input	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
clearable	boolean	true	是否可清空
isShowWordLimit	boolean	false	是否显示字数统计
renderType	number	1	1 文本 / 2 邮箱 / 3 身份证 / 4 手机 / 5 网址
disabled	boolean	false	是否禁用
showPassword	boolean	false	是否密码框
defaultValue	string	''	默认值
placeholder	string	''	占位提示
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
min	number 或 null	null	最小长度
max	number 或 null	null	最大长度

示例：

logger.info(卡密.value);

---

textarea - 多行文本（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
clearable	boolean	true	是否可清空
isShowWordLimit	boolean	false	是否显示字数统计
rows	number	6	可见行数
defaultValue	string	''	默认值
placeholder	string	''	占位提示
disabled	boolean	false	是否禁用
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
min	number 或 null	null	最小长度
max	number 或 null	null	最大长度

示例：

logger.info(remark.value);

---

number - 数字（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
min	number	0	最小值
max	number 或 null	null	最大值
step	number	1	步进
precision	number	0	小数精度
disabled	boolean	false	是否禁用
controls	boolean	true	是否显示加减按钮
controlsPosition	boolean	true	按钮位置（右侧）
defaultValue	number 或 null	null	默认值
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
minlength	number 或 null	null	最小长度（校验）
maxlength	number 或 null	null	最大长度（校验）

示例：

let n = Number(loopCount.value) || 0;

---

radio - 单选框（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
dataKey	string	''	选项数据源 key（关联 schema.data）
displayStyle	string	block	选项布局，如 block
defaultValue	string	''	默认选中项 value
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
disabled	boolean	false	是否禁用
required	boolean	false	是否必填

示例：

logger.info(runMode.value);

---

checkbox - 复选框（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
dataKey	string	''	选项数据源 key
displayStyle	string	block	选项布局
defaultValue	array	[]	默认选中项 value 列表
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
disabled	boolean	false	是否禁用

示例：

logger.info(tags.value);

---

select - 下拉框（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
dataKey	string	''	选项数据源 key
filterable	boolean	true	是否可搜索
multiple	boolean	false	是否多选
defaultValue	string	''	默认选中项 value
placeholder	string	''	占位提示
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
disabled	boolean	false	是否禁用
clearable	boolean	true	是否可清空
required	boolean	false	是否必填

示例：

let mode = runMode.value; // 如 'normal'

---

time - 时间（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
clearable	boolean	true	是否可清空
format	string	HH:mm:ss	显示格式
valueFormat	string	HH:mm:ss	值格式
defaultValue	string 或 null	null	默认时间
placeholder	string	''	占位提示
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
disabled	boolean	false	是否禁用

示例：

logger.info(startTime.value); // 如 '08:30:00'

---

date - 日期（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
isShowWordLimit	boolean	false	字数统计（一般不用）
clearable	boolean	true	是否可清空
format	string	YYYY-MM-DD	显示 / 值格式
defaultValue	string 或 null	null	默认日期
startTime	string 或 null	null	可选起始
endTime	string 或 null	null	可选结束
placeholder	string	''	占位提示
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
type	string	date	date / datetime / dates / daterange 等
required	boolean	false	是否必填
disabled	boolean	false	是否禁用

示例：

logger.info(birthday.value); // 如 '2026-09-04'

---

rate - 评分（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
max	number	5	最大星数
allowHalf	boolean	false	是否允许半星
defaultValue	number	0	默认分数
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
disabled	boolean	false	是否禁用

示例：

let score = Number(rating.value) || 0;

---

switch - 开关（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
defaultValue	boolean	true	默认开关状态
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
disabled	boolean	false	是否禁用

示例：

let on = enableLog.value === 'true';

---

slider - 滑块（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
min	number	0	最小值
max	number	100	最大值
step	number	1	步进
defaultValue	number	0	默认值
placeholder	string	''	占位提示
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
disabled	boolean	false	是否禁用

示例：

let speed = Number(速度.value) || 0;

---

html - 富文本编辑器（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
defaultValue	string	''	默认 HTML
placeholder	string	''	占位提示
action	string	''	上传地址等
size	number	1	相关尺寸配置
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
disabled	boolean	false	是否禁用

示例：

logger.info(content.value);

---

cascader - 级联框（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
filterable	boolean	true	是否可搜索
multiple	boolean	false	是否多选
checkStrictly	boolean	false	是否严格选中父子节点
defaultValue	string	''	默认值
placeholder	string	''	占位提示
labelWidth	number	100	标签宽度
isShowLabel	boolean	true	是否显示标签
required	boolean	false	是否必填
disabled	boolean	false	是否禁用
clearable	boolean	true	是否可清空

示例：

logger.info(region.value);

---

uploadfile - 上传文件（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
isShowLabel	boolean	true	是否显示标签
labelWidth	number	100	标签宽度
defaultValue	array	[]	默认文件列表
multiple	boolean	false	是否多选
action	string	''	上传接口
limit	number	1	最大文件数
size	number	5	单文件大小上限（MB）
accept	string	.png,.jpg	接受的扩展名
disabled	boolean	false	是否禁用
required	boolean	false	是否必填

示例：

logger.info(avatar.value);

---

signature - 签名（属性）

脚本可读属性：

属性名	类型	默认值	描述
value	string	''	当前填写值（启动快照）；写法 唯一标识.value
key	string	-	唯一标识；写法 唯一标识.key
label	string	''	标签文案；写法 唯一标识.label
type	string	-	控件类型；写法 唯一标识.type

设计器 options（非脚本属性名）：

属性名	类型	默认值	描述
required	boolean	false	是否必填
isShowLabel	boolean	true	是否显示标签
labelWidth	number	100	标签宽度
defaultValue	string	''	默认签名数据
penColor	string	rgb(0, 0, 0)	笔触颜色
action	string	''	上传地址等
disabled	boolean	false	是否禁用

示例：

logger.info(sign.value);

---

综合示例（读界面参数 → 跑流程）

示例：

async function main() {
 logger.setLoggerLevel('debug');

 const msg = demoMsg?.value ?? '';
 const loops = Number(loopCount?.value ?? '1');
 const mode = runMode?.value ?? 'normal';
 const logOn = enableLog?.value === 'true';

 if (logOn) {
 logger.info('界面参数', { msg, loops, mode, type: runMode?.type });
 }

 for (let i = 0; i < loops; i++) {
 logger.info(msg, i + 1, '/', loops);
 sleep(500);
 }
}

return main();