@clue_nidapp/form-core v2.0.1-alpha.3

线索通表单 SDK

线索通表单 SDK 为线索通表单组件核心逻辑SDK，包含表单从初始化到最终销毁全生命周期数据流转，仅作为核心逻辑的封装不侵入UI交互。目前该 SDK 支持 h5，lynx，字节小程序环境。使用该 SDK，开发者可以不依靠橙子建站，搭建自己的表单落地页。

安装

yarn add @clue_nidapp/form-core
# or
npm install @clue_nidapp/form-core

使用

step1 引入

需引入 sdk 本体和对应环境的网络请求插件，注意，表单 sdk 必须配合对应环境的网络请求插件使用

import { Core, FormOptions } from '@clue_nidapp/form-core/web';
import { API } from '@clue_nidapp/plugin-api-h5' // 引入网络请求插件

step2 引入 convertSDK

// 字节小程序环境
import convertSDK from '@clue_nidapp/mini-convert-sdk'
// h5 环境
import convertSDK from '@clue_nidapp/h5-convert-sdk'

step3 实例化 sdk

登录线索通，新建表单，并获取表单 instanceId advId 以及 clueAccountId

// 场景一：SDK 内部加载数据
let options:FormMetaData = {
  // formId是表单的instanceId
  data: { formId: 0, advId: 0, clueAccountId: 0 },
  // 注册插件，sdk 必须注册对应环境的网络请求插件后使用
  plugins: [new API()],
  externalSetting: {
    scenarioType: FormScenarioType // SDK接入场景，小程序为 25，h5 为 28，更多场景值可以查看 FormScenarioType
  }
};
const formCore = new Core(options, convertSDK);

初始化参数说明

表单归属信息

额外配置

表单配置

step4 使用 sdk

1. 订阅 FormLifeCycleEvent.DetailReady 方法，获取你在青鸟线索通上创建的表单的数据，然后用这些数据作为你的表单字段的默认值（如果你的表单字段是有默认值的场景）

2. 在你表单字段值修改时，调用 formCore.reportBehavior 方法向 sdk 上报修改后的值（必须）

3. 调用 formCore.submitForm 方法提交表单

4. 接收提交表单后的回调事件

完整生命周期

以下方法挂载在 FormLifeCycleEvent 枚举上

生命周期图

插件机制介绍

线索通表单 SDK 中只提供了一些基础能力，其余能力的扩展都是引入插件，注册插件来完成的。以网络请求插件为例

import { Core, FormOptions } from '@clue_nidapp/form-core/web';
import { API } from '@clue_nidapp/plugin-api-h5' // 引入网络请求插件
const options: FormOptions = {
  data: { formId: 0, advId: 0, clueAccountId: 0, },
  // 注册插件
  plugins: [new API()]
}
const formCore = new Core(
  options,
);

注册完成后，就可以使用 sdk 发送网络请求了

formCore.request.get(url, options).then((res) => {});

官方插件列表

定制你的插件

我们允许使用方定制自己的插件，然后将其注册到表单 sdk 中使用。

插件的实现并不复杂，只需要实现抽象类 IPlugin 中的 plugIn 方法和 plugOff 方法即可

plugIn 方法是插件的注册方法，接收一个参数为表单 sdk 的实例，它将会在插件注册时触发

plugOff 方法是插件的销毁方法，它将在插件卸载时触发

import { IPlugin } from '@clue_nidapp/shared';
import { Core } from '@clue_nidapp/form-core';

export class Api implements IPlugin {
  name = 'your plugin name'

  public plugIn(coreInstance: Core) {
    // add your code
  }

  public plugOff() {
    // add your code
  }
}

实现完你的插件之后，将它注册到表单 sdk 即可，我们提供了两种方法来注册

方法一

在表单 sdk 实例化时就注册，这也是我们推荐的方法

const formCore = new Core({
  detailData: formData,
  // 注册插件
  plugins: [new API()]
}, convertSDK);

方法二

在表单 sdk 实例后注册，需要确保表单 sdk 实例化时不依赖这些插件，否则表单 sdk 会实例化失败

const formCore = new Core();
formCore.registerPlugin(new Plugin());

静态方法和实例上方法、属性

除去使用发布订阅方法调用 sdk 方法外，sdk 还提供了静态方法和普通方法，列表如下

ICustomField

interface ICustomField {
  k: string;
  v: any;
}

生命周期返回值及方法参数说明

表单detail加载成功返回值(FormCoreData)

表单字段配置详情(FEFormElement)

FormElementExpand

interface FormElementExpand {
  subType: FormElementExpandSubType; // 子类型
  fieldSubType: FormElementExpandFieldSubType; // 子类型
  dpaId: number;
  multiple: boolean; // 是否是多选组件
  optionNumber?: number; // 多选时有，多选最大数量
}

enum FormElementExpandSubType {
  carOneSelect = 1, // 汽车行业一级下拉
  carTwoSelect = 2, // 汽车行业二级下拉
  carDistributorSelect = 3, // 汽车行业经销商下拉
  carCustomSelect = 4, // 汽车行业经销商下拉 - 自定义csv上传
  carOptimizedRetailerSelect = 5, //汽车行业优选经销商
  carDcdSelect = 6, // 懂车帝下拉
}

enum FormElementExpandFieldSubType {
  default = 0,
  carOneSelect = 101, // 汽车行业一级下拉
  carTwoSelect = 102, // 汽车行业二级下拉
  carDistributorSelect = 103, // 汽车行业经销商下拉
  carCustomSelect = 104, // 汽车行业自定义下拉
  carOptimizedRetailerSelect = 105, // 汽车行业优选经销商
  intentionBuyCarCity = 106, // 企业号车云店意向城市优选
  carDcdSelect = 107, // 懂车帝下拉
  interactiveRadio = 111, // 对话表单对话选项
}

填写表单校验结果返回值(IFieldValidateResult)

IValidateResult

IAfterSubmitForm

修改表单字段字入参(IReportBehavior)

用户行为(BehaviorEvent)

字段类型说明(FormElementType)

字段值说明

字段默认值获取

单选

let defaultValue = '';
const defaultArray = element.dataSource.filter(({isDefault})=>isDefault).map(({name}) => name);
if(defaultArray.length > 0){
  defaultValue = defaultArray[0]
}

多选

const defaultValue = element.dataSource.filter(({isDefault})=>isDefault).map(({name}) => name);

下拉

import { FEFormElement, BehaviorMap, getSelectLevelOptions, getSelectFieldDefaultValue, formatSelectFieldValue } from '@clue_nidapp/form-core';

// 获取下拉选项默认值数,据结构为TreeDataItem[][]
const selectItems = getSelectFieldDefaultValue(element.dataSource);
// 格式化默认值， 数据结构string[][]
const defaultValue = formatSelectFieldValue(selectItems);

Tips：下拉字段传值

下拉字段支持单选和多选两种格式，单选时每一级仅支持选择一个选项，多选时仅支持优选经销商进行多选(需要在青鸟线索通中进行配置)

代码示例

小程序

常见问题

Q: 表单提交后，能收到表单提交成功的回调，但是在飞鱼看不到提交的线索

A: 在测试时，如果短时间内多次提交，表单提交生成的线索极有可能被反作弊系统拦截，这种情况下线索不会进入到飞鱼，可以更换手机号、设备重新提交尝试，或在一定时间（一般为 24h）后再次尝试

Q: 在字节小程序中编译报错 TypeError: Converting circular structure to JSON / 在字节小程序中无法将 formCore 实例作为 props 传递给子组件

A: 小程序对 props 的序列化使用 JSON.parse，formCore 实例继承自 EventEmitter3 对象，是无法被这样序列化的，故而推荐使用 provide inject 来传递 formCore 实例