纷享销客开发者手册

简体中文

English

detail.head_info.render.before

约 1202 字大约 4 分钟

2025-12-16

遵循 Promise风格

该钩子在详情页标题栏组件渲染之前触发，允许开发者在页面显示前执行额外的业务逻辑或干预 UI 展示。

用途

在详情页标题栏渲染前进行自定义操作，主要功能包括但不限于：

  • 自定义按钮：新增、删除或重置标题栏的操作按钮。
  • 数据干预：修改或注入详情页组件所需的数据。

接口定义

1. 输入参数

functional用于注册Hook回调函数。执行该Hook时，宿主会向回调函数传入以下参数：

参数名说明类型可选值默认值
context事件上下文，包含通用参数Object----
plugin当前插件运行信息，业务逻辑通常不需要使用Object----
context.component当前标题栏组件配置，插件可读取后通过返回值覆盖其中部分属性Object----

2. 返回结果 (Response)

钩子可以返回对象或Promise<Object>，返回对象包含以下可选属性：

普通同步回调直接throw时，异常会由PWC适配层捕获并记录，宿主按Hook未返回结果继续处理。当前Detail包装层不会处理Hook返回rejected Promise的情况（包括async回调中抛出异常），会使标题栏一直等待。Hook中执行可能失败的异步操作时，应在Hook内部捕获并上报异常，再resolve可用的返回结果。

属性说明类型示例
buttons对象操作按钮的配置，支持增/删/改Object跳转至示例
component需要浅合并到当前标题栏组件配置的属性Object跳转至示例

数据结构说明

buttons 对象结构

用于定义如何操作标题栏按钮：

属性说明类型默认值
add批量添加自定义按钮Array<IButton>--
del批量删除指定按钮（传入按钮的 action 编码）Array<string>--
reset批量重置已有按钮的名称、行为或参数解析Array<IButton>--

IButton 接口定义 (buttonInfo)

自定义按钮或重置按钮的具体配置项：

参数说明类型add必填reset必填
action按钮唯一标识；reset通过该值匹配已有按钮string是是
label按钮显示名称string是否
attrs按钮样式属性，仅消费class、icon和typeObject否否
beforeAction内置按钮API执行前的参数处理函数，签名为beforeAction(params)(params: Object) => Promise<Object>否否
parseParambeforeAction的历史兼容名称，建议新代码使用beforeAction(params: Object) => Promise<Object>否否
callback点击按钮后的自定义动作，签名为callback({ next })Function否否

beforeAction(params)接收内置按钮将要提交的完整API参数，必须返回Promise<Object>；resolve的对象会浅合并到原参数后再调用内置API。

beforeAction的Promise会被宿主等待；reject会阻止内置API继续执行，且宿主不会自动处理该异常。

callback({ next })中的next(options)用于继续执行该按钮原有的内置逻辑。可选的options会浅合并到当前按钮参数；不调用next时不会执行内置逻辑。对于没有内置逻辑的全新自定义action，callback应自行完成业务处理。

新增自定义按钮需要可点击行为时必须提供callback。宿主不会消费callback返回值，也不会等待或捕获其返回的Promise；异步逻辑需要在callback内部完成异常处理。

代码示例

1. 基础用法

展示如何注册该钩子并返回基础的 Promise。

export default class Plugin {
  apply() {
    return [{
      event: 'detail.head_info.render.before',
      functional: this.renderBefore.bind(this)
    }];
  }

  renderBefore(context, plugin) {
    // 执行业务逻辑...
    return Promise.resolve();
  }
}

2. 自定义按钮示例

演示如何同时进行按钮的删除、添加和重置。

export default class Plugin {
  apply() {
    return [{
      event: 'detail.head_info.render.before',
      functional: this.renderBefore.bind(this)
    }];
  }

  renderBefore(context, plugin) {
    return Promise.resolve({
      buttons: {
        // 1. 删除指定编码的按钮 (例如：删除变更负责人按钮)
        del: ['ChangeOwner'],

        // 2. 添加新按钮
        add: [{
          action: 'cancel',
          label: '取消',
          callback() {
            alert('点击了取消按钮');
          }
        }],

        // 3. 重置已有按钮
        reset: [{
          action: 'Edit',
          label: '编辑(来自插件)',
          beforeAction(params) {
            return Promise.resolve({
              fromPlugin: true
            });
          }
        }, {
          action: 'Clone',
          label: '复制',
          callback({ next }) {
            alert('执行自定义复制逻辑');
            next(); // 继续执行标准逻辑
          }
        }]
      }
    });
  }
}

3. 组件数据示例

将上下文中的组件信息进行处理并返回。

export default class Plugin {
  apply() {
    return [{
      event: 'detail.head_info.render.before',
      functional: this.renderBefore.bind(this)
    }];
  }

  renderBefore(context, plugin) {
    return Promise.resolve({
      component: {
        ...context.component,
        exposedButton: 4
      }
    });
  }
}

注意事项

  1. 触发时机：详情页刷新时，也会重新触发此钩子的执行，请注意逻辑的幂等性。
  2. 内置逻辑：在 callback 中，可以通过参数中的 next 方法触发系统标准的内置业务逻辑。