字段联动示例

字段联动系统概览

实现智能表单字段联动逻辑,构建动态响应的用户交互体验

此示例演示如何使用kinlink API实现字段间的联动关系。通过监听字段变化条件逻辑处理自动数据更新,创建智能化的表单交互系统,提升用户操作的便利性和准确性。

字段联动核心功能

  • 🔗 依赖关系:基于主字段值控制从字段的状态和内容
  • 🎯 条件显示:根据选择动态显示或隐藏相关字段
  • 🔄 自动填充:主字段变化时自动更新关联字段值
  • 📋 选项过滤:动态筛选下拉菜单或选择项内容
  • 实时响应:即时响应用户操作,无延迟更新
  • 🎨 状态同步:保持多个字段间的数据一致性

关键功能

  • 监听字段值变化事件
  • 基于条件控制字段显示和隐藏
  • 根据选择动态设置字段值
  • 实现复杂的字段依赖逻辑

代码示例

/**
* 示例7: 字段联动示例
* 功能:实现表单字段间的联动逻辑
*/
(function () {
kinlink.events.on(kinlink.FormEvents.FORM_LOADED, () => {
  try {
    // 监听性别字段变化,控制相关字段显示
    kinlink.events.on(kinlink.FormEvents.FIELD_VALUE_CHANGED, (data) => {
      const { fieldCode, value } = data;

      // 根据性别控制称谓字段的选项
      if (fieldCode === '单选框_0') {
        handleGenderChange(value);
      }

      // 根据国家选择控制城市字段
      if (fieldCode === '下拉菜单') {
        handleCountryChange(value);
      }

      // 根据证件类型控制证件号码字段
      if (fieldCode === '下拉菜单_1') {
        handleDocumentTypeChange(value);
      }
    });

    // 处理性别变化的联动逻辑
    function handleGenderChange(gender) {
      const titleField = '下拉菜单_2'; // 假设这是称谓字段
      
      if (gender === '男') {
        // 为男性设置对应的称谓选项
        kinlink.formApi.setFieldOptions(titleField, [
          { value: 'Mr', text: '先生 (Mr.)' },
          { value: 'Dr', text: '博士 (Dr.)' },
          { value: 'Prof', text: '教授 (Prof.)' }
        ]);
        kinlink.formApi.setFieldValue(titleField, 'Mr');
      } else if (gender === '女') {
        // 为女性设置对应的称谓选项
        kinlink.formApi.setFieldOptions(titleField, [
          { value: 'Ms', text: '女士 (Ms.)' },
          { value: 'Mrs', text: '夫人 (Mrs.)' },
          { value: 'Dr', text: '博士 (Dr.)' },
          { value: 'Prof', text: '教授 (Prof.)' }
        ]);
        kinlink.formApi.setFieldValue(titleField, 'Ms');
      } else {
        // 其他情况清空称谓字段
        kinlink.formApi.setFieldValue(titleField, '');
      }
    }

    // 处理国家变化的联动逻辑
    function handleCountryChange(country) {
      const cityField = '单行文本框_12'; // 假设这是城市字段
      
      // 根据国家自动填充常见城市
      const cityMappings = {
        'A': '东京',
        'B': '北京',
        'C': '纽约',
        'D': '伦敦'
      };

      const defaultCity = cityMappings[country] || '';
      kinlink.formApi.setFieldValue(cityField, defaultCity);

      // 如果选择了特定国家,显示城市字段
      if (country && country !== '') {
        kinlink.formApi.showField(cityField);
      } else {
        kinlink.formApi.hideField(cityField);
      }
    }

    // 处理证件类型变化的联动逻辑
    function handleDocumentTypeChange(docType) {
      const docNumberField = '单行文本框_11'; // 证件号码字段
      const expiryField = '日期_2'; // 有效期字段

      // 根据证件类型设置字段标签和验证规则
      if (docType === 'passport') {
        kinlink.formApi.setFieldLabelText(docNumberField, '护照号码');
        kinlink.formApi.setFieldPlaceholder(docNumberField, '请输入护照号码');
        kinlink.formApi.showField(expiryField);
        kinlink.formApi.setFieldLabelText(expiryField, '护照有效期');
      } else if (docType === 'id_card') {
        kinlink.formApi.setFieldLabelText(docNumberField, '身份证号码');
        kinlink.formApi.setFieldPlaceholder(docNumberField, '请输入身份证号码');
        kinlink.formApi.hideField(expiryField); // 身份证通常不需要有效期
      } else if (docType === 'driver_license') {
        kinlink.formApi.setFieldLabelText(docNumberField, '驾驶证号码');
        kinlink.formApi.setFieldPlaceholder(docNumberField, '请输入驾驶证号码');
        kinlink.formApi.showField(expiryField);
        kinlink.formApi.setFieldLabelText(expiryField, '驾驶证有效期');
      } else {
        // 清空所有相关字段
        kinlink.formApi.setFieldValue(docNumberField, '');
        kinlink.formApi.setFieldValue(expiryField, '');
        kinlink.formApi.hideField(expiryField);
      }
    }

    // 初始化时设置默认联动状态
    const initialGender = kinlink.formApi.getFieldValue('单选框_0');
    const initialCountry = kinlink.formApi.getFieldValue('下拉菜单');
    const initialDocType = kinlink.formApi.getFieldValue('下拉菜单_1');

    if (initialGender) handleGenderChange(initialGender);
    if (initialCountry) handleCountryChange(initialCountry);
    if (initialDocType) handleDocumentTypeChange(initialDocType);

  } catch (error) {
    console.error('字段联动设置失败:', error);
  }
});
})();

使用说明

要使用此功能,只需将代码复制到您的kinlink自定义JavaScript中。根据您的表单字段,修改代码中的字段代码和联动逻辑。您可以根据业务需求设计复杂的字段依赖关系。

完整代码请下载查看:

7-字段联动示例.js

注意事项

字段联动可能会触发多次事件,请确保联动逻辑能够正确处理循环依赖和递归调用的情况。建议在复杂联动中添加防护机制。

API参考

此示例使用了以下kinlink API:
  • kinlink.events.on(eventName, callback) - 注册事件监听器

  • kinlink.FormEvents.FORM_LOADED - 表单加载完成事件

  • kinlink.FormEvents.FIELD_VALUE_CHANGED - 字段值变化事件

  • kinlink.formApi.setFieldOptions(fieldCode, options) - 设置字段选项

  • kinlink.formApi.setFieldPlaceholder(fieldCode, placeholder) - 设置字段占位符

  • kinlink.formApi.getFieldValue(fieldCode) - 获取字段值

  • kinlink.formApi.setFieldValue(fieldCode, value) - 设置字段值