自定义变量

自定义变量功能允许在页面和程序中定义和使用可配置的变量，便于统一管理和灵活配置。

什么是自定义变量

自定义变量是全局或页面级别的可配置参数，可以在程序代码、控件属性、SQL 语句中引用。

变量类型

类型	作用域	说明
系统变量	全局	平台内置，如当前用户ID、当前时间等
全局变量	全局	管理员配置，所有页面可用
页面变量	页面级	只在当前页面可用
临时变量	运行时	程序运行过程中临时创建

系统变量

平台内置的系统变量，无需定义即可使用：

变量名	说明	示例
${userId}	当前用户ID	1001
${userName}	当前用户名称	张三
${deptId}	当前用户部门ID	10
${deptName}	当前用户部门名称	研发部
${now}	当前日期时间	2026-07-22 14:30:00
${today}	当前日期	2026-07-22
${timestamp}	当前时间戳	1784689200000

全局变量

全局变量在系统管理中配置，适用于所有页面。

配置方式

1. 进入 系统管理 → 系统配置 → 全局变量
2. 点击"新增变量"
3. 输入变量名、变量值、说明
4. 点击"保存"

常用全局变量示例

变量名	变量值	说明
systemName	速构平台	系统名称
uploadPath	/data/uploads	文件上传路径
pageSize	20	列表默认分页大小
fileMaxSize	50	文件上传最大大小(MB)

页面变量

页面变量只在当前页面中有效。

定义页面变量

在页面设计器中：

1. 打开页面属性
2. 找到"变量定义"选项卡
3. 添加变量名和默认值

在代码中使用

// 定义页面变量
setPageVar('customerId', 123);
setPageVar('customerName', '测试客户');
setPageVar('orderStatus', 'pending');

// 获取页面变量
var customerId = getPageVar('customerId');
var customerName = getPageVar('customerName');

// 获取所有页面变量
var allVars = getAllPageVars();

// 检查变量是否存在
var hasVar = hasPageVar('customerId');

// 删除变量
removePageVar('customerId');

临时变量

临时变量在程序运行过程中使用，页面关闭后自动清除。

// 定义临时变量
setTempVar('processing', true);
setTempVar('selectedIds', [1, 2, 3]);

// 获取临时变量
var isProcessing = getTempVar('processing');

// 清除临时变量
clearTempVars();

在 SQL 中使用变量

变量可以直接在 SQL 语句中引用：

-- 使用系统变量
SELECT * FROM t_order 
WHERE create_user = '${userId}'
  AND create_time >= '${today}'

-- 使用全局变量
SELECT * FROM t_file 
WHERE file_size <= ${fileMaxSize} * 1024 * 1024

-- 使用页面变量
SELECT * FROM t_customer 
WHERE id = ${customerId}

-- 多个变量组合
SELECT * FROM t_order_detail 
WHERE order_id = ${orderId}
  AND status = '${orderStatus}'
  AND create_user = '${userId}'

在控件属性中使用变量

变量可以绑定到控件属性：

控件	属性	绑定值
标签	文本	当前用户：${userName}
输入框	默认值	${deptName}
表格	分页大小	${pageSize}
日期	最小值	${today}

变量作用域优先级

当变量名相同时，按以下优先级取值（高优先级覆盖低优先级）：

1. 临时变量（运行时）
2. 页面变量（页面级）
3. 全局变量（全局）
4. 系统变量（内置）

注意事项

1. 变量名建议使用有意义的英文命名，使用驼峰或下划线风格
2. 变量名区分大小写，${UserId} 和 ${userId} 是不同的变量
3. 敏感信息（如密码）不建议存储在变量中
4. 全局变量修改后需要刷新页面生效