该钩子在详情页图片字段预览前调用

预览图片前执行额外的业务逻辑：

• 根据当前记录或字段信息决定是否允许预览
• 阻止宿主的默认图片预览

参数

functional用于注册Hook回调函数。执行该Hook时，宿主会向回调函数传入以下参数。图片预览参数和通用参数均位于context中。

参数	说明	类型	可选值	默认值
context	图片预览事件上下文	Object	—	—
plugin	当前插件运行信息，业务逻辑通常不需要使用	Object	—	—

context

参数	说明	类型	可选值	默认值
context.objectApiname	当前详情对象apiName的历史兼容字段	String	—	—
context.fieldName	当前图片字段apiName	String	—	—
context.data	当前图片字段解析后的图片对象数组	Object[]	—	—
context.objectData	当前记录解析后的完整详情数据；未就绪时为空	Object | null	—	—
context.startIndex	本次点击图片在data中的索引，从0开始	Number	—	—
context.field	当前图片字段描述	Object	—	—

通用参数中的context.objectApiName与事件历史字段context.objectApiname当前值相同。新代码优先使用规范命名context.objectApiName；仅在兼容既有插件代码时使用objectApiname。

context.data数组项来自图片字段解析结果，常用字段如下。字段是否存在取决于图片数据来源，生成代码时应先判断可选字段。

参数	说明	类型
smallUrl	缩略图地址	String
path	图片路径	String
is_recapture	是否为重新采集图片	Boolean
scene_error	图片场景异常信息	Any
describe_api_name	图片所属对象apiName	String

返回结果

Hook可以返回结果对象，也可以返回Promise<Object>。宿主等待Promise resolve后判断是否继续默认预览。

参数	说明	类型	可选值	默认值
stopPreView	是否阻止宿主默认图片预览	Boolean	—	false

返回{ stopPreView: true }时阻止默认预览；未返回结果、未返回stopPreView或该值为false时继续默认预览。宿主不会使用其他返回字段替换预览图片或预览组件。

普通同步回调直接throw时，异常会由PWC适配层捕获并记录，宿主按Hook未返回结果继续默认预览。Hook返回rejected Promise时（包括async回调中抛出异常），当前Detail包装层不会处理该rejection，默认预览不会打开。异步业务失败时应在Hook内部捕获并上报异常，再根据业务策略resolve{ stopPreView: false }继续预览，或resolve{ stopPreView: true }明确阻止预览。

示例

根据当前图片状态阻止预览

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

    previewBefore(context, plugin) {
        const currentImage = context.data[context.startIndex];
        const shouldStop = Boolean(currentImage?.scene_error);

        return Promise.resolve({
            stopPreView: shouldStop
        });
    }
}

读取当前图片信息

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

    previewBefore(context, plugin) {
        const currentImage = context.data[context.startIndex];

        if (currentImage) {
            console.log(context.fieldName, currentImage.path);
        }

        return Promise.resolve({
            stopPreView: false
        });
    }
}

注意事项

1. 需要阻止默认预览时应返回stopPreView: true，不要通过主动throw或返回reject状态的Promise表达正常的预览取消。

2. Hook中的异步调用需要自行处理失败状态，避免未捕获的异常意外中断预览。

3. objectData是当前详情数据的读取结果，不应通过修改该对象更新详情页。