Android WebView 开发指南:AgentWeb 完整使用
痛点场景:为什么需要 AgentWeb?
传统 WebView 开发中的常见问题:
- 进度监控难:WebView 的 onProgressChanged 回调不稳定,进度条显示异常
- 权限管理乱:位置、摄像头等权限请求处理逻辑复杂
- 文件选择器失效:不同 Android 版本的文件选择 API 差异导致功能异常
- JavaScript 对话框丑陋:原生对话框样式与 App 风格不协调
- 第三方跳转混乱:scheme 链接跳转缺少用户确认环节
- SSL 证书错误:HTTPS 页面加载时的证书验证问题
一键配置:快速集成 AgentWeb
基础依赖配置
在项目的 build.gradle 中添加依赖:
dependencies {
implementation 'io.github.justson:agentweb-core:v5.1.1-androidx'
implementation 'io.github.justson:agentweb-filechooser:v5.1.1-androidx' // 文件选择功能
}
核心初始化代码
在 Activity 中初始化 AgentWeb:
public class MainActivity extends AppCompatActivity {
private AgentWeb mAgentWeb;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
FrameLayout container = findViewById(R.id.container);
mAgentWeb = AgentWeb.with(this)
.setAgentWebParent(container, new ViewGroup.LayoutParams(-1, -1))
.useDefaultIndicator() // 使用默认进度条
.createAgentWeb()
.ready()
.go("https://www.example.com");
}
}
核心功能:AgentWeb 的强大特性
智能进度条控制
AgentWeb 通过 IndicatorController 实现精确的进度监控:
// 自动处理进度条显示逻辑
mAgentWeb = AgentWeb.with(this)
.setAgentWebParent(container, layoutParams)
.useDefaultIndicator() // 内置进度条
.setWebChromeClient(mWebChromeClient) // 自定义 ChromeClient
.setWebViewClient(mWebViewClient) // 自定义 ViewClient
.createAgentWeb()
.ready()
.go("https://www.baidu.com");
统一权限管理
处理 WebView 中的权限请求:
// 权限拦截器配置
mAgentWeb.getWebCreator().getWebView()
.setWebChromeClient(new DefaultChromeClient(this) {
@Override
public void onGeolocationPermissionsShowPrompt(String origin, GeolocationPermissions.Callback callback) {
// 自定义权限处理逻辑
handleLocationPermission(origin, callback);
}
});
文件选择器适配
AgentWeb 解决了 Android 各版本文件选择 API 的兼容性问题:
// 自动适配不同版本的文件选择 API
mAgentWeb.getWebCreator().get()
.setWebChromeClient(new DefaultChromeClient(this) {
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Override
public boolean onShowFileChooser(WebView webView, ValueCallback<Uri[]> filePathCallback, FileChooserParams fileChooserParams) {
// 处理文件选择
return openFileChooserAboveL(webView, filePathCallback, fileChooserParams);
}
});
架构解析:AgentWeb 的核心设计
AgentWeb 采用模块化设计,核心组件包括:
- AgentWeb:总控制器,协调各模块工作
- WebCreator:WebView 创建工厂,负责 WebView 的实例化
- IndicatorController:进度指示器管理
- WebSecurityController:Web 安全控制
- JsEntraceAccess:JavaScript 交互入口
中间件扩展机制
AgentWeb 通过中间件模式实现功能扩展:
// 自定义 WebChromeClient 中间件
public class CustomChromeMiddleware extends MiddlewareWebChromeBase {
@Override
public void onProgressChanged(WebView view, int newProgress) {
super.onProgressChanged(view, newProgress);
// 添加自定义逻辑
updateCustomProgress(newProgress);
}
}
高级应用:实际开发场景解决方案
下载功能集成
AgentWeb 内置了强大的下载管理功能:
// 启用下载功能
mAgentWeb.getWebCreator().get()
.setWebViewClient(new DefaultWebClient(this) {
@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
if (url.endsWith(".apk") || url.endsWith(".zip")) {
// 处理下载链接
handleDownload(url);
return true;
}
return super.shouldOverrideUrlLoading(view, url);
}
});
页面跳转控制
处理第三方 App 跳转:
mAgentWeb.getWebCreator().get()
.setWebViewClient(new DefaultWebClient(this) {
@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
// 处理 intent scheme
if (url.startsWith("intent://")) {
showJumpConfirmDialog(url);
return true;
}
return super.shouldOverrideUrlLoading(view, url);
}
});
性能优化方案
与 Sonic 框架集成提升页面加载速度:
// Sonic 框架配置
mAgentWeb = AgentWeb.with(this)
.setAgentWebParent(container, layoutParams)
.useDefaultIndicator()
.setWebViewClient(new SonicWebViewClient()) // Sonic 客户端
.createAgentWeb()
.ready()
.go("https://www.example.com");
最佳实践:避免常见陷阱
内存泄漏防护
@Override
protected void onPause() {
mAgentWeb.getWebLifeCycle().onPause();
super.onPause();
}
@Override
protected void onResume() {
mAgentWeb.getWebLifeCycle().onResume();
super.onResume();
}
@Override
protected void onDestroy() {
mAgentWeb.getWebLifeCycle().onDestroy();
super.onDestroy();
}
安全配置建议
// WebView 安全设置
WebSettings settings = mAgentWeb.getWebCreator().getWebView().getSettings();
settings.setJavaScriptEnabled(true);
settings.setAllowFileAccess(false); // 禁止文件访问
settings.setAllowContentAccess(false);
错误处理机制
mAgentWeb.getWebCreator().get()
.setWebViewClient(new DefaultWebClient(this) {
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
// 自定义错误页面处理
showErrorPage(errorCode, description);
}
});
总结:为什么选择 AgentWeb?
AgentWeb 通过精心设计的架构和丰富的功能特性,为 Android WebView 开发提供了完整的解决方案:
✅ 开箱即用:简单配置即可获得完整的 WebView 功能 ✅ 版本兼容:完美适配 Android 各版本 API 差异 ✅ 功能全面:进度控制、权限管理、文件选择一应俱全 ✅ 性能优异:内置多种优化策略提升加载速度 ✅ 扩展灵活:中间件模式支持自定义功能扩展
通过本文的完整指南,你已经掌握了 AgentWeb 的核心使用方法和最佳实践。立即开始使用 AgentWeb,告别 WebView 开发的各种烦恼,打造更优秀的混合应用体验!

