uni-app x 组件指南ad-custom 模板广告组件广告单元、自动刷新与事件回调【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本文以 docs/component/ad-custom.md 为核心结合仓库内 ad 组件文档、App 端广告模块配置与示例页面源码系统讲解 uni-app x 中ad-custom模板广告组件的平台支持、属性配置、事件处理与实战接入方式。读完本文你将能够在微信小程序端正确配置unit-id广告单元、设置自动刷新间隔并通过load/error事件完成广告加载状态管理与错误兜底。ad-custom是 uni-app x 提供的模板广告组件用于在页面中嵌入由微信小程序流量主平台渲染的原生模板广告。与常规的ad信息流 / banner 广告组件不同ad-custom通过广告单元 idunit-id绑定广告位并支持按设定的时间间隔自动刷新广告内容适合在内容流页面、列表场景中长期驻留展示广告。下文以当前仓库文档与源码为依据逐一拆解该组件的使用要点。一、组件定位与适用场景ad-custom的核心定位是模板广告广告的视觉样式与渲染逻辑由小程序平台侧的模板能力承载页面开发者只需声明广告单元并把控刷新节奏与加载结果反馈。这一点从文档属性表中可以得到印证——ad-intervals的描述明确写着该参数不传入时 模板 广告不会自动刷新说明自动刷新是模板广告区别于普通静态广告位的关键机制。适用场景典型包括信息流 / 内容列表中的插入式广告位需要周期性更换展示内容的常驻广告区域需要精确控制广告单元与刷新策略的微信小程序页面。需要特别说明的是该组件本质上是微信小程序平台的开放能力属性unit-id需要在小程序管理后台流量主模块中新建广告单元后获得这与 uni-ad 体系下 App 端通过adpid申请广告位是两套不同的流程详见下文与 ad 组件的关系与选择。二、平台兼容性ad-custom的平台支持范围非常明确仅微信小程序端可用。仓库文档 docs/component/ad-custom.md 中给出的兼容性矩阵如下| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | x | x | x |要点解读微信小程序 4.41 起支持ad-custom组件Web、Android、iOS、HarmonyOS 平台均不支持表格中标注为x因此在编写页面时应使用条件编译将ad-custom限定在微信小程序平台避免在其他平台渲染时报错。条件编译写法可参考仓库示例页 src/pages/component/ad/ad.uvue 中的!-- #ifdef MP --/!-- #ifndef MP --用法。三、属性详解ad-custom的属性全部集中在小程序端的广告位配置上。文档定义的完整属性表如下| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | unit-id | string | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 广告单元 id可在小程序管理后台的流量主模块新建 | | ad-intervals | number | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 广告自动刷新的间隔时间单位为秒参数值必须大于等于 30该参数不传入时模板广告不会自动刷新 | | load | eventhandle | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 广告加载成功的回调 | | error | eventhandle | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 广告加载失败的回调event.detail {errCode: 1002} |3.1 unit-id广告单元 idunit-id是ad-custom绑定的广告单元标识类型为string必填属性。广告单元需要在小程序管理后台的流量主模块中新建新建后即可获得对应的单元 id。需要注意广告单元 id 与广告位是绑定的切换页面或更换广告位时需要同步更新unit-id不同小程序主体、不同广告位对应不同的unit-id应避免复用或写死测试值。3.2 ad-intervals自动刷新间隔ad-intervals用于控制模板广告的自动刷新频率类型为number单位为秒。约束与行为如下参数值必须大于等于 30即刷新间隔最短 30 秒更小的值不会被接受不传入该参数时模板广告不会自动刷新只会展示首次加载的广告内容需要周期性更新广告内容时务必显式设置该属性并满足 ≥ 30 秒的约束避免因高频刷新影响用户体验或触发平台限制。3.3 全局属性补充ad-custom作为 uni-app x 组件同样支持组件通用属性id、style、class、ref、data-*等与通用触摸事件详见 docs/component/common.md 中组件的全局属性和事件章节。例如可以通过style控制广告区域的宽度通过class管理广告容器的间距与背景。四、事件与错误处理ad-custom提供两个与广告加载生命周期直接相关的事件。4.1 load加载成功回调广告加载成功时触发类型为eventhandle。可在回调中执行埋点上报、加载状态置位等逻辑。4.2 error加载失败回调广告加载失败时触发事件对象event.detail {errCode: 1002}即错误事件携带errCode字段文档明确给出的示例错误码为1002。开发者应至少做两件事在回调中读取event.detail.errCode用于区分错误类型与排查对广告区域做降级处理如隐藏广告容器、展示占位提示避免页面出现空白或异常布局。从仓库中 ad 组件的错误事件定义见 docs/component/ad.md 的UniAdErrorEvent可以推断uni-app x 的广告类组件在错误事件上保持了相似的errCode机制错误码为number类型用于标识广告位为空、广告位无效、广告未开通、缺少广告模块、广告加载失败等具体情形。ad-custom的errCode: 1002即属于这一错误码体系的微信小程序端取值具体到每个码值的业务含义应以小程序平台的错误码说明为准。4.3 事件对象结构参考load/error均为eventhandle类型事件对象基于 uni-app x 的UniEvent体系具备type、target、currentTarget、timeStamp等通用属性并支持stopPropagation()阻止事件冒泡、preventDefault()阻止默认行为详见 docs/component/common.md 的UniEvent章节。error额外通过detail携带错误信息即上文所述的{errCode: 1002}。五、使用示例由于ad-custom仅支持微信小程序平台建议使用条件编译包裹组件标签并配合状态变量管理加载结果。以下为基于文档属性定义整理的示意用法uvue 页面script setup languts语法与仓库示例 src/pages/component/ad/ad.uvue 保持一致template view page-head title模板广告示例/page-head !-- #ifdef MP -- ad-custom unit-id你的广告单元id :ad-intervals30 stylewidth: 100%; loadonLoad erroronError /ad-custom !-- #endif -- !-- #ifndef MP -- view classuni-centerad-custom 仅支持微信小程序平台/view !-- #endif -- view v-iferrorTips classuni-center广告加载失败请稍后重试。/view /view /template script setup languts const errorTips ref(false) const onLoad () { errorTips.value false uni.showToast({ position: bottom, title: 广告加载成功 }) } const onError (e : UniAdErrorEvent) { errorTips.value true console.log(广告加载失败 errCode:, e.detail.errCode) } /script使用要点unit-id换成你在小程序流量主模块申请到的真实广告单元 idad-intervals传入 ≥ 30 的数值单位为秒控制自动刷新不传则不会自动刷新error中读取e.detail.errCode进行错误分类与兜底展示微信小程序平台的测试与上线需要流量主资质审核通过后才能真正产生收益。六、开通与配置流程ad-custom对应的广告能力开通流程与 uni-app 的广告体系一致分平台有所差异微信小程序端ad-custom 的适用平台在小程序管理后台的流量主模块开通流量主能力、创建广告单元取得unit-id后填入组件。这是ad-custom的唯一前置条件。App 端uni-ad 体系供ad组件使用如需在 App 端展示信息流 / banner / 开屏等广告则需在 uni-ad 后台基础模块uni-ad-release.aar / uni-ad-dom2-release.aar 等为必选渠道 SDK 按开通情况选择性集成。需要强调的是ad-custom本身不支持 App 端兼容性表格中 Android / iOS 均为 x上文 App 端配置仅用于说明 uni-ad 广告体系的全貌帮助开发者理解ad-custom小程序模板广告与 uni-adApp 广告两套能力各自的使用边界。七、与 ad 组件的关系与选择仓库中还有功能相近的ad组件见 docs/component/ad.md两者容易混淆区别如下| 维度 | ad-custom本文 | ad | | :- | :- | :- | | 组件类型 | 模板广告 | banner / 信息流广告 | | 广告位标识 |unit-id小程序流量主广告单元 id |adpiduni-ad 后台申请 | | 自动刷新 |ad-intervals≥ 30 秒不传不刷新 |ad-intervals≥ 30 秒不传不刷新Banner 广告 | | 平台支持 | 仅微信小程序4.41 | 微信小程序4.41App Android / iOS4.31 | | 主要事件 | load / error | load / close / error / clicked | | 附加能力 | - |ad-typevideo / grid、ad-theme|选择建议目标是微信小程序平台、需要原生模板化渲染与周期性刷新的广告 → 使用ad-custom目标包含App 端Android / iOS需要信息流、banner、视频贴片等广告 → 使用ad组件并配合 uni-ad 后台与 docs/native/modules/android/uni-ad.md 完成 SDK 配置。两者的ad-intervals语义一致都必须 ≥ 30 秒、不传不自动刷新上手时可复用同一套刷新策略心智模型。八、常见问题与排查建议| 现象 | 排查方向 | | :- | :- | | 广告一直不展示load 与 error 均未触发 | 检查页面是否运行在微信小程序平台其他平台不支持确认unit-id已正确传入 | | error 触发detail.errCode 为 1002 | 广告加载失败按小程序平台的错误码说明对照处理常见于广告位未开通、网络异常或资质问题可稍后重试并做好降级展示 | | 广告不会自动刷新 | 确认ad-intervals已传入且值 ≥ 30文档明确该参数不传入时模板广告不会自动刷新 | | 其他平台编译报错或渲染异常 | 用!-- #ifdef MP --条件编译包裹ad-custom参考仓库示例 src/pages/component/ad/ad.uvue 的平台分支写法 |小结ad-custom是 uni-app x 面向微信小程序流量主场景的模板广告组件核心配置项为unit-id广告单元 id与ad-intervals≥ 30 秒的自动刷新间隔加载结果通过load/error事件暴露其中error的detail.errCode如 1002是错误排查的关键入口。使用时牢记三点仅微信小程序 4.41 支持、广告单元需在流量主模块开通、不传ad-intervals即不自动刷新。如需在 App 端投放广告请转向ad组件与 uni-ad 体系避免跨平台能力混淆。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考