HarmonyOS Web 组件实战：广告屏蔽（AdsBlock）怎么用，什么时候要用？
HarmonyOS Web 组件实战：广告屏蔽（AdsBlock）怎么用，什么时候要用？
一起来构建生态吧~
在 ArkTS 侧把异步逻辑包装成Promise，Native 侧拿到这个 Promise 对象，然后给它挂then / catch，在回调里获取异步结果或异常。
本文用一个完整示例，走一遍从 ArkTS 到 Native 的链路。
1. 整体思路
-
ArkTS 侧：
- 调用 Native 接口时，把一个 callback 传给 Native。
- Native 调用这个 callback，ArkTS 在 callback 里 返回一个 Promise 对象。
- Promise 内部用
setTimeout模拟异步，最终resolve或reject。
-
Native 侧：
- 通过
napi_call_function调用 ArkTS 传入的 callback，得到 Promise 对象。 - 用
napi_get_named_property拿到 Promise 的then和 `cat
- 通过
在真实项目里嵌入 Web 内容时，广告绝对不是“可有可无”的功能点，而是必须要管的一类体验问题。用户访问网页内容时，被各种第三方广告无端弹窗/轮播/闪烁埋在内容中，体验差、加载慢、数据流量多，甚至还可能带来安全隐患。
HarmonyOS 在它的 Web 组件能力里提供了一个叫 AdsBlock（广告屏蔽） 的机制，允许应用在加载 Web 资源时 拦截和过滤一些广告 URL、域名、规则。这篇文章不用照搬声明式规范，而是从一个开发者实际会遇到的痛点和解决流程出发，讲清楚：
- 它是什么
- 为啥要用
- 什么时候开启
- 怎样加自定义规则
- 常见策略和坑
一、什么是 HarmonyOS 的 AdsBlock？用人话理解
简单讲：
AdsBlock 就是 Web 侧的请求过滤器，当一个 Web 资源在加载前进入请求流程时，它会有机会被拦截、标记、甚至直接阻止下载。
它的核心触发在 ArkWeb 的事件回调链里：
当 Web 组件即将向网络/本地取资源的时候，可以先经过一套规则判断，哪些是“广告/不想加载的资源”，应用可以选择阻止它。
说白了就是：
✔ 拦截掉恶意/无用广告资源
✔ 节省网络流量
✔ 提升页面加载体验（速度更快、卡顿更少）
✔ 提供「白名单/黑名单/自定义规则」控制能力
二、一般什么时候你会用到它？
下面是一些很常见的场景，我是这么判断要不要启用 AdsBlock：
场景 1：你的 Web 页面是由第三方提供的，且你无法完全控制其内容
比如嵌入内容平台、某些动态页面，这类页面可能伴随弹窗广告，屏蔽效果会很明显。
场景 2：你是新闻/资讯类应用，用户产生大量 Web 浏览
在大量 Web 浏览场景下，每秒都在加载内容，加一点广告过滤体验提升非常明显。
场景 3：你想减少页面加载无关资源、节省流量
特别是对移动网络友好体验设计，过滤掉广告资源比单纯通过 CSS/JS 隐藏更好。
三、怎么开启 AdsBlock？最简单的“一句开关”
在 HarmonyOS Web 组件中，你可以通过 Web 的控制器来开启 AdsBlock 功能：
import { webview } from '@kit.ArkWeb';
this.controller.enableAdsBlock(true);
很直白，这段代码就是告诉 Web 控制器：“请启用 AdsBlock 全局功能”。
开关默认是关闭的，只有主动开启后，后续的请求才会经过 AdsBlock 判断链。
四、它对哪些资源生效？拦截并不是“盲砍”
启用 AdsBlock 不会强制阻挡所有资源——它有一套判断规则：
- 域名/URL 黑名单（如果你加过规则）
- 常见广告脚本/iframe/资源路径匹配
- 拦截返回状态码或空响应（取决设置）
也就是说当资源满足某个“广告规则条件”时，它才会被阻止。
如果你只是开启 enableAdsBlock(true)，但没有规则，它的行为也可能像“只是打开了能力但不开工”，这就是很多人误会“为什么开启了也没看到被拦截”的最常见原因。
五、自定义规则：怎么判断这个 URL 是“广告”？
这才是 AdsBlock 真正的核心力量——你可以自己写规则。
常见的规则类型包括：
1）域名黑名单
const blockedDomains = [
"ads.example.com",
"tracker.thirdparty.cn"
];
webview.WebviewController.addAdsBlockList(blockedDomains);
这段执行后，凡是请求 URL 里含有这些域名的资源都会被拦截。
2）URL 规则更细粒度匹配
如果你想做更精细的规则判断，比如：
✔ 包含 “banner” 或 “popup”
✔ 参数里有 tracking token
✔ 特定路径匹配
你可以通过添加规则时配合正则或者更复杂匹配逻辑来实现（不同 API 版本支持规则表达的能力略有差异）。
比如伪代码（示意你的匹配）：
const rules = [
/.*banner\..*/i,
/.*popup\..*/i,
];
webview.WebviewController.addAdsBlockRules(rules);
（具体 API 形式会根据你编译版本而略有不同，但思路一致：匹配 URL 特征进行拦截）
六、什么时候别启 AdsBlock？（实操经验）
虽然 AdsBlock 看起来是好东西，但有两个场景最好别随便开：
场景 A：你嵌的页面本来就很简单／没有广告内容
启了也没用，还可能不小心误拦了合法资源。
场景 B：页面存在重要第三方资源，不在你控制范围
有些第三方服务（比如聊天 SDK、支付二维码、登录二维码等）可能会被误判为“跟踪/广告脚本”，这时一定要加白名单，而不是单纯关掉 AdsBlock。
七、配合 ITP（智能跟踪防护）一起用会更稳
我在真实项目里不止一次踩过这样的问题：
- ITP 把 Cookie 拦掉了
- AdsBlock 又把某个统计资源拦掉了
- 导致登录态丢失
这两种能力其实在体验层是“同一类问题”：都是在控制“Web 资源请求”，所以我建议：
✔ 日常页面先只开 AdsBlock 过滤明显无用资源
✔ 如果要做隐私保护层面（比如防跨站追踪）再开 ITP
✔ 记得在控制台输出来看哪些资源被阻断了，再补白名单
八、最常见的坑（提前给你避开）
1）你以为“开了 AdsBlock 就等于无广告页面”
实际上它只会拦截匹配规则的请求 URL。
对于 CSS/JS 里内嵌的广告标签内容、动态 DOM 广告，它不会帮你去删 DOM——它只拦“请求”。
如果广告已经内嵌内容（比如 base64 图、SVG 代码片段），AdsBlock 是无法识别的。
2）误拦了正常资源导致页面异常
例如：
- 某个静态资源 URL 差了一个路径名
- 误判 domain 模糊匹配 hit
这种情况出现后，页面就可能白屏或样式乱掉。
解决策略：
✔ 把误判 domain 加到白名单
✔ 或者把 block 的规则从“模糊匹配”改成更严格的匹配
九、一个我实际项目里常用的完整流程
启用 AdsBlock
controller.enableAdsBlock(true);
添加广告域名黑名单
const blockList = [
'ads.example.com',
'tracker.example.net',
'pop.adservice.local'
];
webview.WebviewController.addAdsBlockList(blockList);
控制台输出每次拦截情况（用于排查）
Web({
src: 'https://example.com',
controller: controller
})
.onAdsBlockIntercept((details) => {
console.info(`拦截资源: ${details.url} 规则命中: ${details.rule}`);
});
调试期间打印日志观察哪些被拦截
对误拦资源补白名单
上线后监控体验和流量提升情况
十、写在最后：别只把 AdsBlock 当“广告拦截器”
真正的思考逻辑应该是：
AdsBlock 是你在 App 侧主动控制 Web 请求的一种能力，是体验优化与安全控制的手段，而不是“去广告神器”。
它真正的价值在于：
- 你可以拦掉噪声请求，提高主资源的加载速度
- 你可以在“你不信任”的第三方内容流里做约束
- 它和隐私/安全能力（比如 ITP）配合起来能让体验更稳定
当你把 AdsBlock 理解成“Web 组件请求控制层”的一部分，而不是单纯的“去广告”，你就能在混合开发中用它解决更多真实体验问题。
浙公网安备 33010602011771号