Android WebView 开发指南：AgentWeb 完整使用

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 开发的各种烦恼，打造更优秀的混合应用体验！