1. 简介

表单中的按钮操作逻辑为三类，分为内置按钮、接口按钮和在线编码。
按钮有前、中、后置三种执行逻辑，前置可以对表单数据做逻辑处理后，在中置按钮做数据请求，后置按钮可以基于数据请求后的结果做异常提醒。

联动相比事件缺少了data和btnConfig。utils，context，relation参数保持一致，extra 在事件和联动中会略有不同

1.1 按钮通用属性介绍

2. 内置按钮

内置按钮，封装了平台常用的按钮，比如保存、新增、删除、关联新增

3. 接口按钮

接口按钮，顾名思义，就是调用我们专门开发的业务接口。

3.1 注册接口服务

不同环境的域名配置，意味着不同环境下调用的接口是不一样的，特别说明：URI只能到域名级别
访问：https://csb.gz.cvte.cn ，建议让技术经理来配置，具体参考【转发服务】

3.2 配置接口按钮

3.2.1 请求路径介绍

请求地址构成：https:// + 路由编码 + 服务路径

路径上配置的是3.1 中配置的路由编码，比如：配置了dp_rc
编写请求地址的时候，就是https://dp_rc/api/config/:name/deploy ，在dev环境代表请求的真实地址就是：https://rctest.cvte.com/api/config/:name/deploy
另外，在请求后端的具体服务时，天舟云代理服务会把当前的iac token和用户的jwt token都转发给对应的后端服务。

3.2.2 请求路径占位符参数传递

当URI上有 :占位 参数时，我们可以通过请求参数来表示真实的数据，比如 https://dp_rc/api/config/:name/deploy ,
为了保证URI上的 :name 我们需要再请求参数上配置 name 对应的参数

3.2.3 请求头、请求参数或请求body，需要加载当前表单或明细表的数据

• 主表单按钮

data 表示当前表单的主表数据对象
data.[主表属性]，如：${data.RESOURCE_NAME}

preData：上一次数据处理结果，用于按钮前、中、后置场景
extraData：额外的数据，一般存有当行的数据record，视图的entity
url：当前路由参数
form：可以获取组件的实例，一个Map，键是组件对应的code，值是组件暴露的方法,比如获取选中的值：form['someCode'].selectKeys
page: 获取页面配置，比如获取当前表单id: page.id

• 明细表按钮

data 表示当前表单的主表数据对象
data.[主表属性]
data.[]
form.[明细表].selectedRows[0].[行属性] , 如：${form.T_RESOURCE_ITEM.selectedRows[0].RESOURCE_ITEM_VERSION}
extraData.record.ID 表示行上按钮，获取主键

• 请求头或请求参数

• 请求Body

4. 在线编码

4.1 在线编码说明

指在线写代码，写的内容会直接运行，全局已经定义了configs的变量，所有的数据通过configs获取。

通用参数解释

变量	说明
formCode	组件的formCode ，
attrCode	组件的code，

4.1.1 context 上下文

4.1.2 data 数据

4.1.3 relation 联动

4.1.4 utils 工具类

4.1.5 extra 联动额外数据

4.2 示例

当请求成功后，我们希望按钮可以弹出对应提示信息，我们可以通过后置事件，配置在线编码

const preData = configs.data.preData;
if(preData.status!=="0"){
    configs.utils.notification.error({message:preData.message,content:preData.message});
}else{
    configs.utils.notification.success({message:"更新成功",content:"更新成功"});
}
const pageId = configs.context.globalContext.pageTools.getDetailPageId(configs.context.config);
configs.context.globalContext.pageTools.refresh(pageId);

获取元素/组件的值

方法一

const formData = configs.context.getFormData();
const aValue = formData?.['a'];

方法二

const aValue = configs.data.allData?.['a'];

设置元素/组件的值

仅改变值

configs.context.setFormData({ a: 123 });
configs.relation.emit({ attrCode: 'a', formCode: 'formCode', actionCode: 'change' }, { id: '如果是明细表，需要明细表行id', index: 0 });

仅改变值后会自动触发联动的做法

// 明细表的formCode一般是没有，所以formCode填空字符串
const aRef = configs.context.getCompRef({ formCode: `123`, attrCode: '12' });
aRef.onChange(123);

设置元素/组件可编辑状态

正常元素/组件

// 1 表示可编辑，0 表示不可编辑
configs.context.setBaseConfig({ formCode: `123`, attrCode: '12', attr: 'isEditable', value: '1' });
configs.context.refreshConfigs(true);

如果是明细表，需要加上id和index

configs.context.setBaseConfig({ formCode: `111`, attrCode: '12', attr: 'isEditable', value: '1', extra: { id: '123', index: 1} });
configs.context.refreshConfigs(true);

设置元素校验规则

// attr 有 | 'required' 'max' 'min' 'maxLength' 'minLength'  'len' 'special'  'compare' 'pattern' 'accuracy'
// 开启必填
configs.context.setRuleConfig({ formCode: '', attrCode: '', attr: 'required', value: '1', extra: { id: '如果是针对明细表某一行，需要写id，如果是主表对明细表操作，不写', index: '如果是针对明细表某一行，需要写index，如果是主表对明细表操作，不写' } })

设置元素/组件禁用状态

正常元素/组件

// 1 表示可用，0 表示禁用
configs.context.setBaseConfig({ formCode: `123`, attrCode: '12', attr: 'isEnabled', value: '1' });
configs.context.refreshConfigs(true);

如果是明细表，需要加上id和index

configs.context.setBaseConfig({ formCode: `111`, attrCode: '12', attr: 'isEnabled', value: '1', extra: { id: '123', index: 1} });
configs.context.refreshConfigs(true);

设置元素/组件隐藏显示状态

正常元素/组件

// 1 表示显示，0 表示隐藏
configs.context.setBaseConfig({ formCode: `123`, attrCode: '12', attr: 'isVisible', value: '1' });
configs.context.refreshConfigs(true);

如果是明细表，需要加上id和index

configs.context.setBaseConfig({ formCode: `111`, attrCode: '12', attr: 'isVisible', value: '1', extra: { id: '123', index: 1} });
configs.context.refreshConfigs(true);

设置按钮禁用状态

// formCode填按钮所在容器的formCode，attrCode填容器的code，btnCode填按钮的code，比如按钮所在容器是在card里面，点击设计器的card后，在设计配置可以看到对应的code，鼠标放上去可以看到对应的formCode。2.4版本后formCode可以在高级属性->表单组编码看到，如果没有，则填空字符串
// 如果是表单属性配置的表单按钮，formCode填空字符串，attrCode填'BTN_BLOCK_GLOBAL';
const btnConfig = configs.context.getBtnConfig({ formCode: ``, attrCode: '容器的code', btnCode: '按钮code'});
if (!btnConfig.config.uiConfig) {
     btnConfig.config.uiConfig = {}
 }
 if (!btnConfig.config.uiConfig.attr) {
     btnConfig.config.uiConfig.attr = {}
 }
 // true 表示禁用，false 表示可用
btnConfig.config.uiConfig.attr.disabled = true;
configs.context.refreshBtnConfigs({ formCode: ``, attrCode: '容器的code' });

设置按钮隐藏

// formCode填按钮所在容器的formCode，attrCode填容器的code，btnCode填按钮的code，比如按钮所在容器是在card里面，点击设计器的card后，在设计配置可以看到对应的code，鼠标放上去可以看到对应的formCode。2.4版本后formCode可以在高级属性->表单组编码看到，如果没有，则填空字符串
// 如果是表单属性配置的表单按钮，formCode填空字符串，attrCode填'BTN_BLOCK_GLOBAL';
const btnConfig = configs.context.getBtnConfig({ formCode: ``, attrCode: '容器的code', btnCode: '按钮code'});
// 1 表示显示，0 表示隐藏
btnConfig.config.baseConfig.isVisible = '1';
configs.context.refreshBtnConfigs({ formCode: ``, attrCode: '容器的code' });

明细表

• 明细表是表单的一种元素，数据格式是数组，每一行数组都是一个对象，每一组对象都有ID的key，如果是新增一行数据，在当行数据需要加__add: true。
• 如果是个树形的明细表，每一行的数据中都有children的key，children表示是子行，值是一个数组，数据格式明细表一样。
• 如果有子行或者行数据中有children字段，说明是树形明细表。
  新增一行数据，利用context.getCompRef的能力实现新增一行并可以执行联动

  明细表新增一行

  const { context, data } = configs;
  const tableCode = '明细表的code';
  let tableData = context.getFormData()?.[tableCode];
  if (!Array.isArray(tableData)) {
  tableData = [];
  }
  const id = +new Date()
  tableData.push({ ID: `${id}`, __add: true, ...其他数据 });
  context.setFormData?.({ [tableCode]: [...tableData] });

  明细表新增一行，并在子行插入其他元素的数据

  const { context, data } = configs;
  const tableCode = '明细表的code';
  let tableData = context.getFormData()?.[tableCode];
  if (!Array.isArray(tableData)) {
  tableData = [];
  }
  const id = +new Date()
  const newRow = { ID: `${id}`, __add: true, children: [] };
  const aValue = ['1','2','3'];
  aValue?.forEach((_a) => {
  newRow.children.push({ ID: `${Math.random()}`, __add: true, aValue: _a})
  })
  tableData.push(newRow);
  context.setFormData?.({ [tableCode]: [...tableData] });

  弹窗点击确定

const { context } = configs;

// 通过弹窗等待用户确认
const isConfirmed = await new Promise(rs => {
configs.utils.confirm({
    title: '确认是否做什么事情',
    content: '',
    okText: '确认',
    cancelText: '取消',
    onOk: () => {
      // 确认
      rs(true);
    },
    onCancel() {
      // 取消
      rs(false)
    }
  })
});
if (isConfirmed) {
  // 做一些事情
}

弹窗提示

configs.utils.message.warning('message');

获取表单数据

例子1：

const formData = configs.context.getFormData();

例子2：

// allData 是表单上所有数据
const { allData } = configs.data;

获取用户信息

const userInfo = context.getContext()?.session?.user ?? {};
// 一般有账号，邮箱，用户id，名称，电话
const { account, email, id, name, telephone } = userInfo;

校验，可阻止后续事件执行

const { context } = configs;
const formData = context.getFormData();

const a = formData?.['a'];

if (a === 1) {
    // 后续事件可以拿到response内容，后续事件configs?.data的preData就是response
    response = { success: true, data1: { ttt: 1111 } }
} else {
    // success为false时，后续事件不继续执行
    response = { success: false }
}

跳转到对应tab

// 获取tab的ref，tab是没有formCode，所以填空字符串即可
const tabRef = context.getCompRef({ formCode: '', attrCode: 'TAB_62136AC9079FC'});
// 跳转到对应tab签
tabRef?.setTabKey?.('TABPANE_9AE31CDE5A86E');

按钮跳转事件/列字段跳链配置

跳转参数可以携带上下文，跳转目标如果是天舟云详情页面，可以从上下文数据中消费。

上下文参数字段metaConfig，上下文参数值为JSON字符串，JSON中字段参数说明

调用天舟云内置保存事件

const saveHandler = configs.utils?.cache?.getCache?.()?.['FORMREGISTER']?.["__commonSave"]?.eventHandler;
console.log('--saveHandler', saveHandler);
const currentData = configs?.context?.getFormData?.();
const resp = await saveHandler?.({
    context: configs.context,
    data:{
        currentData,
        allData: currentData,
    },
    btnConfig: {
        scope: ['__GLOBAL_SCOPE'],
    }
})

组件调用天舟云内置保存事件

import CirCache from '@cvte/cir-cache';

const Page = () => {
  const cirCacheRef = useRef(new CirCache({ storage: 'memory' }));
  const detailRef = useRef()

  const handleSave = async () => {
    const context = detailRef.current?.RenderRef?.current?.getContext() ?? {};
    const saveHandler = (cirCacheRef.current?.getCache?.() as any)?.FORMREGISTER
      ?.__commonSave?.eventHandler;
    if (!saveHandler) {
      throw new Error('unexpected savehandler');
    }
    if (!context) {
      throw new Error('unexpected context');
    }
    const currentData = context.getFormData?.();
    const resp = await saveHandler({
      context,
      data: {
        currentData,
        allData: currentData
      },
      btnConfig: {
        scope: ['__GLOBAL_SCOPE']
      }
    });
    return resp;
  };

  return <DetailTemp ref={detailRef} {...其他参数} />

}

调用天舟云内置校验事件

const validateFn = configs.utils?.cache?.getCache?.()?.['FORMREGISTER']?.["__commonGetFormDetailData"]?.eventHandler;
// 会先校验，再返回保存的格式数据
const validatedFormData = await validateFn?.(configs);
// 如果能拿到数据，说明校验成功，如果失败，返回undefined

储存外部工具

// 系统里面储存内容
import CirCache from '@cvte/cir-cache';
const cache = new CirCache({ storage: 'memory' })
cache.setValue('your tool name', 123);

// 在线代码消费内容
const tool = configs.utils.cache.getValue('your tool name');
// tool()

调用history

// 前端2.4版本前
const { cache } = configs.utils || {};
cache.getValue('history-cache').push('/your/url');
// 前端2.4版本后内置history
const { extra } = configs.utils || {};
extra.getValue('history').push('/your/url');

调用搜索

// 说明是谁调用事件，方便排查链路
const owner = 'test';
// 获取事件总线
const subjectEventBus = configs.utils?.getSubjectEventBus?.();
// 调用搜索事件，
subjectEventBus.publishEvent({ owner, eventName: 'form:onSearch' ， data: { name: '模糊查询的值，和code二选一', code: '精确查询的值，和name二选一', formCode: '目标字段的formCode', attrCode: '目标字段的attrCode', afterSearchOperate: 'firstOption或者noValue, 搜索后连接器判断noValue的话，不会执行连接器配置的联动，firstOption暂时没支持', id: '如果目标在明细表中，需要行id', index: '如果目标在明细表中，需要行序号'  }});

模板调用渲染上下文

// 列表和详情调用不一样
// 详情
const context = ref.current?.RenderRef?.current?.getContext() ?? {};
// 列表
const context = ref.current?.getRef?.()?.getRenderRef?.()?.getContext?.() ?? {};

请求映射

// 表单按钮接口请求
{
    // 表单数据
    data: {},
    // 表单配置
    page: {
        classId,
        layout: [],
        code,
        id,
    },
    // 获取组织和用户信息
    session: {
        org: {
            orgCode,
            id,
            orgName
        },
        user: {
            account,
            name,
        },
    },
    // 获取url上的query
    url: {}
    // 前置事件数据
    preData: {}
}
// 例子：${data.字段}：${page.id}
// 联动请求
{
response,
formData
}
// 列表
{
    extraData: {
        entity,
        ref: {
            selectedKeys,
            selectedRows
        }
    },
    page: {
        layout: [],
        pageCode,
        id,
    },
    preData,
    session: {
        org: {
            orgCode,
            id,
            orgName
        },
        user: {
            account,
            name,
        },
        url: {

        }
    }
}

明细表获取选择行数据

const tableRef = configs.context.getCompRef({ formCode: '', attrCode: '明细表code' });
const { selectedRows, selects } = tableRef?.getSelects?.() || {}

触发联动

configs.relation.emit({
    formCode: '', // 主表/明细表编码；
    attrCode: '', // 属性字段编码；
    actionCode: 'change' // 内置联动触发动作编码：'blur'  | 'focus' | 'change' | 'search' | 'create' | 'edit' | 'destroyOnCreate' | 'destroyOnEdit'
},{
    index: 0, // 触发明细表中的字段需要的所在行序号
    id: '',  // 触发明细表中的字段需要的所在行的ID
    // 此处还可以增加触发联动时需要携带的额外数据参数
})

监听联动

relation?.on?.(
      {
        // 监听当前设置选项映射的属性，发生选项值改变时
        // 则将配置了返回字段的属性值，改为该选项中映射字段的值
        actionCode: 'change',
        attrCode: '', // 属性字段编码；如果是监听明细表，那么此处要写明细表编码
        formCode: '', // 主表/明细表编码；如果是监听明细表，那么此处要写undefined
      },
      {
        // 内置联动id如果每次不唯一，那么每次都会增加无效的联动
        id: relationId,
        cbParams: {
            // 传给回调方法的参数
        },
        cb: async (relationCtx: IRelationClassOnConfigsFnCtx) => {
            // TODO
            const {
                cbParams, // 传给回调方法的参数
                id: relatedRowId, // 当前联动的行id
                index: relatedRowIndex, // 当前联动的行索引
                value: changedValue, // 当前触发联动的值内容
            } = relationCtx.extra || ({} as any);
        }
      },
    );

获取内置方法

// 前端tz-render@1.0.1.10版本后内置history,download,upload
const { extra } = configs.utils || {};
extra.getValue('history').push('/your/url');
extra.getValue('download')({ fileName: '文件名称', noTime: 是否加上时间, blob: 文件流 });
 const files = await extra.getValue('upload')({ fileType: 'file', fileAccept: '.xlsx,.xls,.et' });

调用模板

const { loadCmp } = configs?.utils || {};
// 调用列表模板
const Page = loadCmp({ sourceName: 'tz-render', exposesKey: 'Page'  });
// 调用表单模板
const Detail = loadCmp({ sourceName: 'tz-render', exposesKey: 'Detail'  });
// 参数参考：https://docs.cvte.com/docs/tzv16/216

保存前处理数据

// 前置事件
const data = configs?.context?.getFormData();
data.test = 1;
response = { success, data };

自定义联动/按钮事件中实现请求

// 前端请求
const resp = await configs.utils.fetch({
    // 内置服务有lcpCore对应core，lcpApp对应app，lcpHub对应 hub，lcpGw对应gw，lcpData对应data， lcpLog对应log
    url: '/apis/common/proxy/服务/接口',
    method: 'post', // 可以 put, get,
    data, // 如果method是 post，或者put，用data传输数据
    params, // 如果是method是get，用params传输数据
})