操作全局数据

本文介绍如何在表单中使用 API 方法来操作全局数据源、全局变量和调用全局事件。这些 API 方法让您可以在运行时动态地获取、修改和触发全局数据，实现更灵活的表单交互。

获取 API

在使用全局数据 API 之前，您需要先获取 API 对象。API 对象可以通过事件、验证函数、钩子函数等方式获取。

详细说明请查看：如何获取 API

API 方法类型定义

// 触发全局事件
type emitGlobalData = (id: string, ...args: any[]) => any;

// 修改全局变量
type setGlobalVar = (id: string, val: any) => any;

// 修改全局数据源
type setGlobalData = (id: string, val: any) => any;

// 获取数据（包括全局变量）
type getData = (id: string, default?: any) => any;

// 获取全局数据源（返回 Promise）
type getGlobalData = (id: string) => Promise<any>;

调用全局事件

通过 api.emitGlobalData 方法可以触发已定义的全局事件。全局事件通常用于执行一些通用的业务逻辑，如数据同步、状态更新等。

基本用法

// 在事件中触发全局事件
function handleClick($inject) {
  const api = $inject.api;

  // 触发全局事件，传入事件 ID 和参数
  api.emitGlobalData('event_Feq4lui56zxbabc', '参数1', '参数2');
}

使用示例

1. 在按钮点击事件中触发全局事件：

{
  type: 'button',
  field: 'syncBtn',
  title: '同步数据',
  on: {
    click: function($inject) {
      const api = $inject.api;

      // 触发数据同步全局事件
      api.emitGlobalData('event_syncData', {
        formData: api.formData(),
        timestamp: Date.now()
      });
    }
  }
}

2. 在表单提交时触发多个全局事件：

{
  type: 'button',
  field: 'submitBtn',
  title: '提交',
  on: {
    click: async function($inject) {
      const api = $inject.api;

      // 验证表单
      const valid = await api.validate();
      if (!valid) {
        return;
      }

      // 触发提交前事件
      api.emitGlobalData('event_beforeSubmit', api.formData());

      // 执行提交逻辑
      try {
        await api.fetch({
          action: '/api/submit',
          method: 'POST',
          data: api.formData()
        });

        // 触发提交成功事件
        api.emitGlobalData('event_submitSuccess');
      } catch (error) {
        // 触发提交失败事件
        api.emitGlobalData('event_submitError', error);
      }
    }
  }
}

操作全局变量

全局变量是可以在表单中动态计算和使用的变量。通过 api.setGlobalVar 可以修改全局变量的值，通过 api.getData('$var.xxx') 可以获取全局变量的值。

获取全局变量

// 在事件中获取全局变量
function handleClick($inject) {
  const api = $inject.api;

  // 获取全局变量的值
  const token = api.getData('$var.var_Fppdlz6gytmzb1c');
  console.log('Token:', token);
}

修改全局变量

重要警告

使用 api.setGlobalVar 修改全局变量会覆盖原来的计算特性。

一旦通过 api.setGlobalVar 设置了全局变量的值，该变量将不再使用原有的 handle 函数进行计算，而是直接使用设置的值。这意味着：

原有的计算逻辑将失效
变量将变为静态值，不再响应依赖数据的变化
如果需要恢复计算特性，需要重新设置全局变量配置

建议：仅在确实需要覆盖计算逻辑时使用 api.setGlobalVar，否则应通过修改全局变量的依赖数据来触发重新计算。

// 在事件中修改全局变量
function handleChange($inject) {
  const api = $inject.api;

  // 修改全局变量的值（会覆盖计算特性）
  api.setGlobalVar('var_Fppdlz6gytmzb1c', '新的值');

  // 等同于
  api.setData('$var.var_Fppdlz6gytmzb1c', '新的值');
}

使用示例

1. 根据表单数据动态更新全局变量：

{
  type: 'input',
  field: 'username',
  title: '用户名',
  on: {
    change: function($inject) {
      const api = $inject.api;
      const username = api.getValue('username');

      // 更新全局变量
      api.setGlobalVar('var_username', username);

      // 触发相关事件
      api.emitGlobalData('event_usernameChanged', username);
    }
  }
}

2. 在验证函数中使用全局变量：

{
  type: 'input',
  field: 'amount',
  title: '金额',
  validate: [
    {
      required: true,
      message: '请输入金额'
    },
    {
      validator: function(val) {
        const api = this.api;

        // 获取最大金额限制（全局变量）
        const maxAmount = api.getData('$var.var_maxAmount', 10000);

        if (val > maxAmount) {
          return `金额不能超过 ${maxAmount}`;
        }

        return true;
      }
    }
  ]
}