自定义属性

自定义属性功能允许为控件添加额外的自定义配置，满足个性化需求。

什么是自定义属性

自定义属性是附加在控件上的额外配置项，可以在不修改平台核心代码的情况下扩展控件的行为。

使用场景

• 为控件添加业务标识
• 存储控件的扩展配置
• 传递自定义参数
• 实现条件渲染

添加自定义属性

在属性面板中添加

1. 双击控件打开属性面板
2. 找到"自定义属性"选项卡
3. 点击"添加"按钮
4. 输入属性名和属性值
5. 点击"确定"保存

支持的属性类型

类型	说明	示例
字符串	文本类型	"hello"
数字	数值类型	123
布尔	是/否	true
JSON 对象	复杂配置	{"key": "value"}
数组	列表数据	[1, 2, 3]

代码中获取和设置

获取自定义属性

// 获取指定控件的自定义属性
var value = getCustomProp('textbox1', 'myProp');

// 获取控件所有自定义属性
var allProps = getAllCustomProps('textbox1');

// 检查是否存在某属性
var hasProp = hasCustomProp('textbox1', 'myProp');

设置自定义属性

// 设置自定义属性
setCustomProp('textbox1', 'myProp', 'newValue');

// 设置多个属性
setCustomProps('textbox1', {
  prop1: 'value1',
  prop2: 123,
  prop3: true
});

// 删除属性
removeCustomProp('textbox1', 'myProp');

实际应用示例

示例1：业务标识

为控件添加业务标识，用于权限判断：

// 自定义属性：bizCode = 'customer_edit'

// 在按钮点击事件中判断
var bizCode = getCustomProp('btn_edit', 'bizCode');
if (!hasButtonPermission(bizCode)) {
  showMessage('warning', '您没有权限执行此操作');
  return;
}

示例2：条件显示

根据自定义属性控制控件显示：

// 自定义属性：visibleOnRole = 'admin,manager'

// 页面初始化时检查
$('input[custom-visibleOnRole]').each(function() {
  var roles = $(this).attr('custom-visibleOnRole').split(',');
  if (!hasAnyRole(roles)) {
    $(this).hide();
  }
});

示例3：数据格式化

为表格列设置自定义格式化规则：

// 列的自定义属性：format = 'amount'

// 在表格渲染时处理
function formatCell(value, column) {
  var format = getCustomProp(column.id, 'format');
  switch (format) {
    case 'amount':
      return formatAmount(value, '#,##0.00');
    case 'date':
      return formatDate(value, 'yyyy-MM-dd');
    case 'percent':
      return value + '%';
    default:
      return value;
  }
}

自定义属性与数据绑定

自定义属性支持绑定表达式，值可以动态计算：

// 自定义属性：dynamicTitle = '用户：${userName}'

// 页面加载时计算
var template = getCustomProp('label_title', 'dynamicTitle');
var title = template.replace('${userName}', getCurrentUserName());
setControlText('label_title', title);

注意事项

1. 自定义属性名建议使用有意义的英文命名，避免使用中文
2. 属性名不要以 sg- 开头，这是平台保留前缀
3. 大数据量不建议存储在自定义属性中，应使用数据表
4. 自定义属性会随页面配置一起保存和发布