基础事件

本章节介绍平台内置的各种事件及其使用方法。

事件系统

平台的事件系统基于发布-订阅模式，支持全局事件和控件事件。

事件分类

分类	说明
页面事件	页面加载、关闭、刷新等
控件事件	按钮点击、值变化、获得焦点等
表格事件	行选中、单元格点击、数据变化等
数据事件	数据加载、保存、删除等
系统事件	登录、登出、消息通知等

页面事件

页面初始化

// 页面加载完成
onPageLoad(function() {
  console.log('页面加载完成');
  initFormData();
});

// 页面销毁前
onPageUnload(function() {
  console.log('页面即将关闭');
  saveDraft();
});

// 页面显示
onPageShow(function() {
  console.log('页面显示');
  refreshData();
});

// 页面隐藏
onPageHide(function() {
  console.log('页面隐藏');
});

页面参数

// 页面加载时获取参数
onPageLoad(function() {
  var mode = getParam('mode');     // 'view' / 'edit' / 'add'
  var id = getParam('id');         // 数据ID
  
  if (mode === 'view') {
    setPageState('view');
  } else if (mode === 'edit') {
    setPageState('edit');
    loadData(id);
  } else {
    setPageState('add');
  }
});

控件事件

通用事件

// 控件值变化
onControlChange('textbox1', function(newValue, oldValue) {
  console.log('值从 ' + oldValue + ' 变为 ' + newValue);
  validateValue(newValue);
});

// 控件获得焦点
onControlFocus('textbox1', function() {
  console.log('控件获得焦点');
});

// 控件失去焦点
onControlBlur('textbox1', function(value) {
  console.log('控件失去焦点，当前值：' + value);
});

// 控件点击
onControlClick('button1', function() {
  console.log('按钮被点击');
  saveData();
});

// 控件双击
onControlDblClick('label1', function() {
  console.log('控件被双击');
  startEdit();
});

按钮事件

// 保存按钮
onClick('btn_save', function() {
  if (validateForm()) {
    saveData(function(result) {
      if (result.success) {
        showMessage('success', '保存成功');
        closePage();
      }
    });
  }
});

// 删除按钮
onClick('btn_delete', function() {
  showConfirm('确认删除', '删除后数据不可恢复，确认删除吗？', function(result) {
    if (result) {
      deleteData();
    }
  });
});

// 取消按钮
onClick('btn_cancel', function() {
  if (hasUnsavedChanges()) {
    showConfirm('提示', '有未保存的修改，确认退出吗？', function(result) {
      if (result) closePage();
    });
  } else {
    closePage();
  }
});

输入框事件

// 输入框值变化
onChange('text_phone', function(value) {
  // 手机号格式校验
  if (value && !/^1[3-9]\d{9}$/.test(value)) {
    showMessage('warning', '手机号格式不正确');
  }
});

// 回车键触发
onEnter('text_keyword', function(value) {
  console.log('用户输入了：' + value);
  doSearch();
});

// 实时搜索（带防抖）
var searchTimer = null;
onInput('text_search', function(value) {
  clearTimeout(searchTimer);
  searchTimer = setTimeout(function() {
    doSearch(value);
  }, 300);
});

下拉选择器事件

// 选择变化
onChange('select_category', function(value, text) {
  console.log('选中：' + text + '(' + value + ')');
  loadProductsByCategory(value);
});

// 多选模式
onChange('select_tags', function(values) {
  console.log('选中的标签：' + values.join(','));
});

表格事件

行操作事件

// 行点击
onTableRowClick('table1', function(row, rowIndex) {
  console.log('点击了第 ' + rowIndex + ' 行', row);
  showDetail(row);
});

// 行双击
onTableRowDblClick('table1', function(row) {
  console.log('双击行', row);
  openEditPage(row.id);
});

// 行选中
onTableRowSelect('table1', function(rows) {
  console.log('选中了 ' + rows.length + ' 行');
  updateButtonState();
});

单元格事件

// 单元格点击
onTableCellClick('table1', function(rowIndex, field, value) {
  console.log('单元格：' + field + ' = ' + value);
});

// 单元格值变化（编辑模式）
onTableCellChange('table1', function(rowIndex, field, newValue, oldValue) {
  console.log(field + ' 从 ' + oldValue + ' 变为 ' + newValue);
  calculateRowAmount(rowIndex);
});

// 单元格编辑前
onTableCellBeforeEdit('table1', function(rowIndex, field) {
  var row = getTableRow('table1', rowIndex);
  if (row.status === 'approved') {
    showMessage('warning', '已审核的数据不能修改');
    return false;  // 阻止编辑
  }
  return true;
});

表格数据事件

// 数据加载前
onTableBeforeLoad('table1', function(params) {
  console.log('加载参数', params);
  params.status = 'active';  // 追加参数
});

// 数据加载完成
onTableLoad('table1', function(data) {
  console.log('加载了 ' + data.length + ' 条数据');
  updateSummary(data);
});

// 数据加载失败
onTableLoadError('table1', function(error) {
  console.error('加载失败', error);
  showMessage('error', '数据加载失败');
});

数据事件

数据保存事件

// 保存前
onBeforeSave(function(data) {
  console.log('准备保存', data);
  if (!validateData(data)) {
    return false;  // 阻止保存
  }
  return true;
});

// 保存成功
onSaveSuccess(function(result) {
  console.log('保存成功', result);
  showMessage('success', '保存成功');
});

// 保存失败
onSaveError(function(error) {
  console.error('保存失败', error);
  showMessage('error', '保存失败：' + error.message);
});

数据删除事件

// 删除前
onBeforeDelete(function(ids) {
  console.log('准备删除：' + ids.join(','));
  return true;
});

// 删除成功
onDeleteSuccess(function(result) {
  showMessage('success', '删除成功');
  refreshTable('table1');
});

系统事件

登录事件

// 用户登录
onLogin(function(userInfo) {
  console.log('用户登录：' + userInfo.name);
  loadUserSettings();
});

// 用户登出
onLogout(function() {
  console.log('用户登出');
  clearLocalCache();
});

消息事件

// 收到新消息
onNewMessage(function(message) {
  console.log('收到消息：' + message.title);
  updateMessageBadge();
});

// 消息已读
onMessageRead(function(messageIds) {
  console.log('已读消息：' + messageIds.join(','));
});

全局事件

// 窗口大小变化
onWindowResize(function(width, height) {
  console.log('窗口大小：' + width + ' x ' + height);
  adjustLayout();
});

// 网络状态变化
onNetworkChange(function(status) {
  if (status === 'offline') {
    showMessage('warning', '网络连接已断开');
  } else {
    showMessage('success', '网络已恢复');
  }
});

// 键盘快捷键
onKeyPress('Ctrl+S', function(e) {
  e.preventDefault();
  saveData();
});

onKeyPress('Esc', function() {
  closePage();
});

事件解绑

// 绑定事件
var handler = onChange('textbox1', function(value) {
  console.log(value);
});

// 解绑指定事件
offChange('textbox1', handler);

// 解绑控件所有事件
offAll('textbox1');

// 解绑所有事件
offAll();

自定义事件

// 注册自定义事件
on('my-custom-event', function(data) {
  console.log('收到自定义事件', data);
});

// 触发自定义事件
emit('my-custom-event', { type: 'refresh', target: 'table1' });

// 订阅一次（执行后自动解绑）
once('my-custom-event', function(data) {
  console.log('只执行一次');
});

注意事项

1. 事件处理函数中避免执行耗时操作，以免阻塞界面
2. 页面关闭时记得解绑手动绑定的事件，避免内存泄漏
3. 事件回调中的 this 指向触发事件的控件
4. 复杂的事件处理建议封装为独立函数
5. 避免循环触发事件（如 A 变化触发 B，B 变化又触发 A）