H5 调用 Android 接口扫描手机图片：TaoToken 统一 Key 配置与联调骨架-平芜编程栈

1. H5 调用 Android 接口扫描手机图片：先搞清楚要解决什么

H5 调用 Android 接口扫描手机图片，本质是让网页里的 JavaScript 通过 WebView 提供的桥接能力，去调用 Android 原生的 MediaStore 查询接口，把本地相册里的图片路径、名称、尺寸、拍摄时间等元数据回传给前端渲染。它适合混合开发场景：你有一个已经跑在 WebView 里的 H5 页面，不想重写原生界面，但又需要读取用户手机里的图片列表。核心难点不在“查图片”本身，而在三件事：运行时权限申请、跨线程回调桥接、以及把散落的接口调用收敛到一套可维护的配置里。

我试过直接在 H5 里用plus.android那套写法，能跑通，但一旦项目里出现多个原生能力（扫码、定位、文件、图片），每个页面各写一份 importClass，维护起来很痛苦。所以这篇给的是一个更工程化的骨架：Android 侧用addJavascriptInterface暴露一个受控接口，H5 侧只认一个全局对象；同时把模型/接口调用需要的统一 Key 放进config.toml，让联调阶段不用来回改代码。下面从权限片段开始，一路给到真机验证扫描回调的完整步骤。

2. TaoToken 统一 Key 前置：为什么联调阶段要先把它配好

扫描图片只是本地能力，为什么还要提 TaoToken？因为真实项目里，H5 拿到图片列表后往往紧接着要做识别、分类、生成描述这类模型调用。如果本地扫描和模型调用是两套 Key、两套地址，联调时你会花大量时间在“到底是权限没给还是 Key 没配对”之间反复横跳。TaoToken 提供的是统一入口，把模型对话、编码计划、控制台、API Key 管理收敛到一处，H5 和 Android 侧共用同一份配置即可。

你需要先拿到一个可用的 Key，入口在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。拿到之后不要硬编码进 H5，而是写进工程根目录的config.toml，由构建脚本注入或由原生侧读取后通过桥接传给 H5。这样做的直接好处是：换环境只改一个文件，扫描回调里带的调试信息也能统一带上请求标识，排查时一眼能对上。

接口基地址统一用 https://taotoken.net/api ，注意这个地址不带任何查询参数，拼接路径时自己补全。模型对话的调试页面在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，联调扫描结果后想顺手验证一下模型能不能吃这些图片元数据，可以直接在那里试。长期做编码和 Agent 类任务的，看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

config.toml示例，字段名按你项目习惯改，关键是分层清晰：

[app] name = "h5-android-scan" debug = true [taotoken] base_url = "https://taotoken.net/api" api_key = "sk-你的Key" timeout_ms = 30000 [scan] # 单次扫描最多返回多少张，防止大相册卡死 WebView max_items = 500 # 是否在回调里附带缩略图 base64，真机联调建议先关 with_thumbnail = false

注意：api_key不要提交到公开仓库，用.gitignore排除config.toml，仓库里放一份config.example.toml。

3. 可复制配置：AndroidManifest 权限片段与 WebView 桥接骨架

3.1 权限片段

Android 13（API 33）之后读媒体权限拆分了，图片要用READ_MEDIA_IMAGES；低版本仍用READ_EXTERNAL_STORAGE。两个都写上，用maxSdkVersion控制生效范围：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" /> <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

如果你还要读视频或音频，再补READ_MEDIA_VIDEO、READ_MEDIA_AUDIO。别偷懒写MANAGE_EXTERNAL_STORAGE，那个权限审核很麻烦，图片场景用不上。

3.2 WebView 与 addJavascriptInterface 骨架

原生侧暴露一个类，方法上必须加@JavascriptInterface，否则 H5 调不到。查询放到子线程，结果通过webView.post回主线程再evaluateJavascript回调，避免在 JS 桥线程里做耗时 IO：

public class ScanBridge { private final Context ctx; private final WebView webView; public ScanBridge(Context ctx, WebView webView) { this.ctx = ctx; this.webView = webView; } @JavascriptInterface public void scanImages(final String callbackId) { new Thread(() -> { List<Map<String, Object>> list = new ArrayList<>(); String[] projection = { MediaStore.Images.Media._ID, MediaStore.Images.Media.DISPLAY_NAME, MediaStore.Images.Media.DATA, MediaStore.Images.Media.DATE_TAKEN, MediaStore.Images.Media.WIDTH, MediaStore.Images.Media.HEIGHT }; try (Cursor c = ctx.getContentResolver().query( MediaStore.Images.Media.EXTERNAL_CONTENT_URI, projection, null, null, MediaStore.Images.Media.DATE_TAKEN + " DESC")) { if (c != null) { int max = 500; while (c.moveToNext() && list.size() < max) { Map<String, Object> item = new HashMap<>(); item.put("name", c.getString(c.getColumnIndexOrThrow( MediaStore.Images.Media.DISPLAY_NAME))); item.put("path", c.getString(c.getColumnIndexOrThrow( MediaStore.Images.Media.DATA))); item.put("date", c.getLong(c.getColumnIndexOrThrow( MediaStore.Images.Media.DATE_TAKEN))); item.put("width", c.getInt(c.getColumnIndexOrThrow( MediaStore.Images.Media.WIDTH))); item.put("height", c.getInt(c.getColumnIndexOrThrow( MediaStore.Images.Media.HEIGHT))); list.add(item); } } } String json = new Gson().toJson(list); webView.post(() -> webView.evaluateJavascript( "window.__onScanResult('" + callbackId + "', " + json + ")", null)); }).start(); } }

注册桥接时给一个固定名字，H5 侧就认这个名字：

webView.getSettings().setJavaScriptEnabled(true); webView.addJavascriptInterface(new ScanBridge(this, webView), "AndroidScan");

3.3 H5 侧调用与回调

H5 不再直接 importClass，而是调用桥接对象，用 callbackId 做请求配对，避免多次扫描结果串台：

let seq = 0; const pending = {}; window.__onScanResult = function (callbackId, list) { const cb = pending[callbackId]; if (cb) { cb(list); delete pending[callbackId]; } }; function scanImages() { return new Promise((resolve) => { const id = 'scan_' + (++seq); pending[id] = resolve; if (window.AndroidScan && window.AndroidScan.scanImages) { window.AndroidScan.scanImages(id); } else { resolve([]); // 非 Android 环境降级 } }); } document.getElementById('btn').addEventListener('click', async () => { const list = await scanImages(); document.getElementById('result').innerText = JSON.stringify(list, null, 2); });

3.4 运行时权限申请

Manifest 声明只是“有资格申请”，真正读之前还要动态申请。在调用scanImages前先检查并请求：

if (Build.VERSION.SDK_INT >= 33) { requestPermissions(new String[]{Manifest.permission.READ_MEDIA_IMAGES}, 1001); } else { requestPermissions(new String[]{Manifest.permission.READ_EXTERNAL_STORAGE}, 1001); }

H5 侧最好在按钮点击后先触发一次权限检查，原生把结果通过另一个桥接方法回传，再决定是否发起扫描。这样用户拒绝权限时，页面能给出明确提示，而不是拿到一个空数组干瞪眼。

4. 验证请求与成功结果：真机扫描回调怎么确认跑通

配置写完，别急着接模型，先把扫描链路单独验证。步骤按顺序来：

第一步，真机安装后打开 H5 页面，点击“获取所有图片”按钮。此时如果权限没给，系统会弹窗，允许后再次点击。

第二步，看 Android Studio 的 Logcat，过滤chromium或你自己的 TAG，确认evaluateJavascript被调用。如果没有任何输出，八成是addJavascriptInterface没注册成功，或者方法漏了@JavascriptInterface。

第三步，看页面#result区域。成功时应该是一段 JSON 数组，每项包含name、path、date、width、height。真机上通常能看到几十到几百条，按拍摄时间倒序。

第四步，验证回调配对。快速连点三次按钮，观察结果是否每次都正确刷新，没有出现旧结果覆盖新结果。如果串台，检查callbackId是否每次递增且pending正确删除。

第五步，把扫描结果里的一条path拿去模型对话页面做一次简单调用，确认config.toml里的base_url和api_key生效。模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。这一步能同时验证本地扫描和统一 Key 两条链路，联调效率最高。

成功结果的特征很明确：Logcat 无SecurityException，页面 JSON 非空，连续点击结果稳定，模型调用返回正常。四个都满足，骨架就算立住了。

5. 本篇常见错排查：扫描为空、回调不触发、权限被拒

扫描结果为空数组。最常见原因是权限没真正授予，或者 Android 13 上只声明了READ_EXTERNAL_STORAGE而没声明READ_MEDIA_IMAGES。先在系统设置里确认应用有“照片和视频”权限，再检查 Manifest 合并结果。另一个原因是查询用了DATA字段，部分新机型上该字段可能为空，改用_ID拼content://media/external/images/media/{id}更稳。

H5 调用后回调不触发。先确认addJavascriptInterface的对象名和 H5 里写的一致，大小写敏感。再确认方法签名是public且带@JavascriptInterface。如果用了混淆，记得给桥接类加 keep 规则，否则方法名被改掉，H5 调不到。还有一种情况是evaluateJavascript里的 JSON 字符串包含单引号导致拼接断裂，用Gson序列化后做一次转义，或者改用JSONObject.quote。

权限弹窗不出现。检查是否在onCreate之外过早调用，或者requestPermissions的 requestCode 被其他地方复用。另外用户勾选“不再询问”后，再次请求不会弹窗，需要引导去设置页。H5 侧要能区分“用户拒绝”和“系统不再询问”，前者可以重试，后者只能跳设置。

大相册导致 WebView 卡顿。一次回传几百条带 base64 缩略图的数据，主线程会明显掉帧。config.toml里的with_thumbnail默认关掉，max_items限制在 500 以内。需要缩略图就分页拉取，别一次性全塞。

Key 配置不生效。确认config.toml被正确读取，base_url结尾没有多余斜杠，api_key没有前后空格。如果 H5 侧也要用，通过桥接把配置传过去，别在 JS 里再写一份。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，字段和错误码对照着看更快。

6. 把扫描骨架接进你的工程：下一步怎么走

到这里，权限片段、桥接骨架、config.toml、真机验证步骤都齐了。你可以先把扫描链路单独跑通，确认 JSON 结构符合预期，再往上叠模型调用。统一 Key 的价值在联调后期才明显：当扫描、识别、生成描述三条链路共用一份配置时，换环境、换 Key、加超时都只动一个文件。

如果你主要在做接入和排障，先把 API Keys 和接入文档过一遍：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 和 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。如果你要验证模型对图片元数据的处理效果，去模型对话页面直接试：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。长期做编码和 Agent 的，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

最后给一个实用技巧：把callbackId的生成规则和日志 TAG 统一，扫描回调里带上callbackId和耗时，出问题时 Logcat 一搜就能定位是权限、查询还是回调环节。这个习惯在混合开发里能省掉大量“猜”的时间。