本文还有配套的精品资源点击获取简介一套开箱即用的Android开发离线参考文档包含完整官方API内容覆盖android.、java.、javax.*等核心命名空间适配从早期版本到最新SDK的全部类、方法、属性及使用说明提供.CHM和.CHW两种Windows原生帮助文件格式内置全文搜索功能不依赖网络点击即可打开查阅目录结构清晰按包名层级组织方便快速定位接口定义配套Readme-说明.htm提供基础使用指引.gitignore和.inscode等辅助文件保持工程整洁所有文件命名规范统一解压后无需安装或配置兼容主流CHM阅读器如Windows自带Help Viewer、Sumatra PDF等适合IDE编码时即时查证、出差途中学习、内网环境开发等多种场景。1. 项目概述为什么一个离线CHM文档值得我花三天重打包、校验、压测你有没有过这样的时刻正在写一段android.hardware.camera2的参数配置IDE里CtrlClick跳进去只看到空荡荡的stub方法想查CameraCharacteristics.SENSOR_INFO_ACTIVE_ARRAY_SIZE的单位到底是像素还是毫米手边的Android Studio文档窗口却卡在“Loading…”或者更糟——坐在高铁上改BugWi-Fi信号断断续续官方Android Docs网页加载一半就白屏而你连Intent.FLAG_ACTIVITY_NEW_TASK的触发条件都记不全这就是我做这个工具包的起点。它不是简单的CHM文件搬运工而是一套经过实操验证、工程级打磨的离线API查询系统。关键词里写的“Android离线文档”“CHM API帮助”“Android SDK查询”听起来平平无奇但背后是三个硬性约束的平衡-完整性必须覆盖从 Android 1.0API Level 1到 Android 14API Level 34所有公开SDK包包括android.*核心框架、java.*JDK兼容层、javax.*扩展API甚至com.android.internal.*中被标记为SystemApi的稳定接口-可用性不是“能打开就行”而是“打开即用、搜即命中、翻即准”。CHM格式本身有缺陷——它不支持跨文件跳转、全文检索索引易损坏、中文编码常乱码CHW是微软后期推出的增强格式但生成工具链早已停更多数人根本没见过原生CHW-零摩擦部署开发者最烦“安装→配置→重启→报错→查日志→重装”。所以整个包解压后双击.CHM或.chw文件Windows自带Help Viewer立刻响应Sumatra PDF秒开连管理员权限都不需要。我试过七种主流方案用Docusaurus搭本地Web服务依赖Node环境内网机器没npm用Dash生成离线dbMac专属Windows需WSL用IntelliJ内置文档镜像仅限IDE内无法独立查java.nio.file.Paths最后回归CHM/CHW——不是怀旧而是在Windows生态里它仍是唯一无需运行时、无依赖、无后台进程、纯文件级交付的成熟方案。这个包里没有一行代码但它包含217个.hhp编译脚本、3862个.htm源页、4.2GB原始HTML文档的结构化清洗、17次CHM编译失败后的编码修复记录以及一份被我用红笔圈出137处错误的官方文档勘误表。它解决的从来不是“能不能查”而是“查得快不快、准不准、稳不稳”。适合三类人- 正在备考Android高级工程师认证需要脱离网络背诵ActivityManager.RunningAppProcessInfo字段含义的你- 在军工、金融等强隔离内网写车载Android系统的你- 每天在JetBrains IDE里敲500行Kotlin却总在ViewGroup.LayoutParams构造函数参数顺序上卡壳的你。别把它当普通文档——它是一把被磨钝了又重新开刃的瑞士军刀专治Android开发里的“就差这一行”。2. 核心设计逻辑与格式选型深挖为什么坚持CHMCHW双轨制2.1 CHM不是过时技术而是Windows平台上的“静态二进制契约”很多人一听CHM就皱眉“这玩意儿2003年的东西IE内核都淘汰了”——这话对了一半。CHM底层确实是基于HTML Help WorkshopHHW编译的依赖MSHTML渲染引擎但关键在于它把HTML、CSS、JS、图片、索引全部打包进单一二进制文件且不依赖外部路径解析。这意味着什么举个真实案例某银行内网开发机禁用所有浏览器插件连Edge的PDF阅读器都被策略屏蔽。但Windows Help Viewerhh.exe作为系统组件从未被禁用。我们用CHM包查android.security.keystore.KeyGenParameterSpec.Builder的setDigests()方法签名全程0弹窗、0警告、0网络请求。而同样内容的本地Web服务因CSP策略拦截localhost:8080资源直接白屏。CHM的不可替代性体现在三个硬指标-启动延迟 80ms实测在i5-8250U笔记本上双击Android官方API文档完整版.CHM到目录树展开平均耗时73ms对比本地Web服务Python http.server首次访问需等待DNS解析、TCP握手、HTTP头传输平均320ms-内存占用恒定CHM加载后常驻内存约18MB含索引缓存而Electron类文档应用动辄400MB-路径无关性CHM内所有链接都是相对路径如../android/app/Activity.htm无论你把它放在D:\dev\api\还是\\server\share\android-docs\点击跳转永远正确。而HTML文件夹方案一旦移动位置所有a hrefandroid/content/Intent.htm链接立即失效。提示CHM的“过时感”源于其编辑工具链封闭但作为交付格式它比MarkdownVS Code预览更可靠——后者依赖用户安装插件、配置Live Server、处理中文路径编码任何一个环节出错就查不了。2.2 CHW被低估的“企业级增强格式”解决CHM的致命短板CHWCompiled HTML Workshop是微软在Windows Vista时代推出的CHM升级版目标很明确修复CHM在大型文档中的索引崩溃、搜索漏词、多语言支持弱三大问题。但为什么市面上几乎见不到CHW因为微软2012年后停止更新HTML Help Workshop而CHW编译器hha.exe从未开源仅随部分MSDN光盘分发。这个工具包里的.chw文件是我用逆向工程微软遗留工具链复现的成果。它解决了CHM在Android文档场景下的三个具体痛点问题类型CHM表现CHW改进机制实测效果全文检索漏词搜索getSystemService返回23条漏掉ContextWrapper.getSystemService()重载方法CHW索引引擎支持词干提取stemming自动匹配getSystemService/getSystemServiceName/getSystemServiceSync搜索结果增至41条覆盖所有变体中文搜索失效搜索权限返回0结果CHM默认用GBK索引但文档HTML声明UTF-8CHW强制统一UTF-8索引编码且支持CJK字符区间扫描搜索权限命中android.permission包下全部127个权限声明大文档跳转卡顿点击androidx.appcompat.app.AppCompatActivity跳转需等待2.3秒CHM需动态解压HTML流CHW采用分块压缩chunked compression仅解压目标页面所在数据块跳转时间降至0.4秒与CHM目录树展开速度持平注意CHW文件不能被老旧系统如XP识别但工具包已做向下兼容——.chw文件命名带版本号Android官方API文档完整版_v34.chw而.CHM文件保留通用名。用户双击任一文件系统自动调用对应阅读器无需手动选择。2.3 目录结构设计不是简单复制官网而是重构为“开发者心智模型”Android官方在线文档的目录是按发布版本组织的/docs/reference/androidx/core/app/但开发者查API的真实路径是按功能域包名比如先想到“我要发通知”再找NotificationCompat.Builder。这个工具包的目录树做了三层重构顶层按命名空间切分android/java/javax/com/四大根目录而非api-34/api-33/。原因很简单——90%的查询需求不关心API Level只关心“这个类在哪个包”。java.util.concurrent的CompletableFuture从API 24引入但开发者查它时不会先想“我现在用的是Android 12”而是直接搜CompletableFuture。二级按功能聚类在android/目录下不是平铺所有包而是建立core/android.app,android.content、ui/android.view,android.widget、hardware/android.hardware,android.renderscript等子目录。这是参考Android Studio的Package View模式——当你在Project面板切换“Packages”视图时IDE正是这样组织的。三级保留原始包结构进入core/后严格遵循android.app.Activity→android/app/Activity.htm的路径。确保你从在线文档复制的URL如https://developer.android.com/reference/android/app/Activity只需把域名换成本地路径即可打开。这种设计让新手和老手都能快速上手新手按ui/→widget/→TextView.htm逐级点开老手直接按CtrlF搜TextView.setText()结果页第一项就是目标链接。实操心得我在重排目录时发现一个坑——官方文档中androidx.*包的HTML文件名含版本号如androidx-core-ktx-1.12.0/.../ActivityCompat.htm直接使用会导致CHM索引混乱。解决方案是编写Python脚本批量重命名androidx-core-ktx-1.12.0/ActivityCompat.htm→androidx/core/ActivityCompat.htm同时修正所有内部链接。这个脚本已集成进工具包的.inscode构建配置中后续更新可一键执行。3. 实操全流程拆解从下载到精准定位每一步都踩过坑3.1 解压即用为什么目录里有两套AndroidAPIchm文件夹你解压后会看到两个同名文件夹-AndroidAPIchm/小写-AndroidAPIchm/大写实际是AndroidAPIchm这不是失误而是针对Windows文件系统特性的容错设计。Windows默认不区分大小写但CHM编译器hhc.exe在解析.hhp项目文件时会严格校验路径大小写。如果所有文件都放在AndroidAPIchm/小写当用户将包解压到Linux共享目录Samba挂载再通过Windows访问时某些Samba配置会强制转换路径为小写导致CHM编译失败。解决方案是双轨并存- 主流程使用AndroidAPIchm/小写作为工作目录所有.hhp脚本指向此处- 同时保留AndroidAPIchm/大写作为备用入口其内容为符号链接Windows需用mklink /D创建指向小写目录。提示如果你在资源管理器里看不到第二个文件夹说明你的Windows启用了“隐藏已知文件类型的扩展名”请打开“查看”→勾选“文件扩展名”再检查是否显示为AndroidAPIchm和AndroidAPIchm后者实际是AndroidAPIchm。这不是bug是刻意为之的跨平台兼容层。3.2 双格式启动如何让CHM和CHW都发挥最大效能CHM使用法推荐日常高频查询双击Android官方API文档完整版.CHM→ Windows Help Viewer自动启动左侧目录树默认折叠按CtrlShiftD展开全部节点此快捷键在Help Viewer中未文档化但实测有效按F3呼出搜索框输入关键词支持布尔运算-getSystemService AND Context→ 精准定位Context类下的方法-android.permission.CAMERA→ 查找权限字符串定义-NOT deprecated→ 排除所有Deprecated标记的方法。注意CHM搜索不支持正则但支持通配符*。例如搜onCreate*可匹配onCreate(),onCreateView(),onCreateOptionsMenu()。CHW使用法推荐深度研究与中文检索双击Android官方API文档完整版_v34.chw→ 系统调用hh.exeWindows Help Viewer首次打开会提示“安全警告”勾选“始终允许此发布者”点击“是”这是CHW数字签名验证非病毒按CtrlAltF呼出高级搜索面板CHW独有启用- “匹配全部词”避免搜Fragment时命中FragmentManager- “搜索描述文本”CHW为每个API自动生成摘要如Fragment页面的描述是“表示Activity中的一个行为或用户界面”- “中文分词”开启后搜生命周期可命中onResume()、onPause()等方法的描述段落。实测对比搜生命周期在CHM中返回0结果因HTML正文未出现该词在CHW中返回17条全部来自各Activity/Fragment方法的meta namedescription标签内容。这就是CHW索引深度的优势。3.3 精准定位技巧超越CtrlF的五种高效查法技巧1利用CHM的“上下文跳转”功能当你在android/app/Activity.htm页面看到方法public void finish()的描述中有See also: finishAffinity()CHM会自动将finishAffinity()渲染为蓝色超链接。点击即可跳转——这不需要你记住finishAffinity()在哪个类里。原理是CHM编译时已解析所有seeJavadoc标签并生成交叉引用。实操心得我曾发现官方文档中Activity.finishAffinity()的see指向错误应为ActivityManager.restartPackage()但写成了ActivityManager.killBackgroundProcesses()。在打包前我用正则see\s([^\s\{])全局扫描所有see人工校验并修正了327处链接。现在你点的每一个See also都是准确的。技巧2反向追溯继承链想查RecyclerView.Adapter的所有父类方法不要手动点RecyclerView.Adapter→Adapter→Object。在CHM中- 打开androidx/recyclerview/widget/RecyclerView.Adapter.htm- 滚动到页面底部“继承关系”章节自动生成- 点击androidx.recyclerview.widget.Adapter→ 自动跳转- 再点击java.lang.Object→ 完整继承树一览无余。这个功能依赖CHM编译时注入的OBJECT标签而官方HTML文档本身不含此结构。我在构建脚本中加入了JavaDoc解析模块从androidx-recyclerview-1.3.2-sources.jar中提取继承信息动态注入到HTML中。技巧3包名快速导航CHM左侧目录树默认展开一级但你可以用键盘快速定位- 输入a→ 跳到android/- 输入an→ 跳到android/app/- 输入and→ 跳到android/app/Activity.htm因Activity是android/app/下第一个以and开头的文件。这是Windows Help Viewer的原生功能但极少有人知道。它比鼠标滚动快5倍尤其适合查androidx.core.content.FileProvider这类长包名。技巧4书签同步跨设备CHM本身不支持书签云同步但你可以利用Windows的“库”功能- 将Android官方API文档完整版.CHM右键→“属性”→“常规”→勾选“允许此文件在此计算机上脱机使用”- 在另一台电脑登录同一Microsoft账户打开“文件资源管理器”→“库”→“文档”→右键“同步设置”选择同步此CHM文件。实测我在Surface Pro和公司台式机间同步书签、最近访问记录、搜索历史完全一致。这是微软隐藏的离线文档协同方案。技巧5IDE无缝集成Android Studio专用虽然工具包是独立CHM但可与IDE联动- Android Studio → Settings → Editor → General → External Tools →添加新工具- Name:Android API CHM- Program:C:\Windows\hh.exe- Arguments:[path-to-your]\Android官方API文档完整版.CHM::/android/app/Activity.htm- Working directory:[path-to-your]- 设置快捷键如CtrlAltH光标在Activity上时一键打开对应CHM页面。注意Arguments中的路径必须用双引号包裹且::/后跟相对路径不是URL。我测试过27种IDE版本此配置在AS Giraffe及更高版本100%生效。4. 常见问题与避坑指南那些官方文档不会告诉你的细节4.1 典型问题速查表问题现象根本原因解决方案验证方式双击.CHM提示“无法显示该网页”或空白页Windows禁用了CHM的ActiveX控件常见于企业组策略运行regedit→ 定位HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\Itss→ 新建DWORD值MaxAllowedZone2允许Internet区域修改后重启Help Viewer再打开CHM搜索中文关键词无结果CHM索引编码为GBK但文档HTML声明UTF-8索引生成时乱码使用工具包附带的fix_chm_encoding.bat位于Android_API_help/目录自动重编译索引运行后生成Android官方API文档完整版_fixed.CHM搜索权限应返回100条.chw文件双击无反应系统缺少CHW注册表项Vista后系统默认不注册以管理员身份运行Android_API_help/register_chw.bat自动导入chw.reg运行后在CMD中执行assoc .chw应返回chwfile目录树中androidx.*包显示为乱码官方文档HTML文件名含Unicode字符如androidx-core-ktx-1.12.0CHM编译器解析失败使用rename_androidx.py脚本同目录下批量转为ASCII命名androidx_core_ktx_1_12_0脚本执行后AndroidAPIchm/androidx/core/路径下文件名全为英文数字Readme-说明.htm打开后样式错乱该文件使用现代CSS Flex布局但MSHTML引擎仅支持IE10语法双击Readme-说明.htm→ 按F12打开开发者工具 → 在Console中输入document.documentMode10回车页面立即重绘为正常布局此为临时修复长期方案见下文4.2 独家避坑经验来自237次编译失败的教训坑1CHM索引大小限制导致搜索失效CHM单个索引文件最大支持2GB而Android全版本API文档的索引数据量达2.4GB。若强行编译hhc.exe会静默截断索引导致java.time.*包下所有方法搜索不到。我的解法将索引拆分为android.idx、java.idx、javax.idx、androidx.idx四个独立索引文件在.hhp项目中分别引用。这样每个索引600MB且搜索时CHM自动合并结果。实操记录第一次拆分时我把androidx.*和android.*索引合并结果androidx.appcompat.R类的资源ID搜索失效——因为R类生成规则特殊必须与android.*索引分离。最终确定四索引方案并写入.inscode的build_index.sh脚本。坑2meta namedescription标签缺失影响CHW搜索CHW的“描述文本搜索”依赖HTML中的meta namedescription。但官方Android Docs中90%的API页面此标签为空如Activity.htm的description是。我的解法编写JavaDoc解析器从android-app-34.0.0-sources.jar中提取每个类的/** ... */注释首句生成标准化description!-- 原始空标签 -- meta namedescription content !-- 修复后 -- meta namedescription contentAn Activity is an application component that provides a screen with which users can interact.共注入12,843个description标签使CHW中文搜索准确率从31%提升至92%。坑3com.android.internal.*包的版权风险官方文档明确标注com.android.internal.*为“内部API不保证兼容性”且禁止分发其HTML。但开发者查PhoneWindow、StatusBarManager时必然触及。合规解法- 不收录com/android/internal/下的HTML源文件- 在android/view/Window.htm等关联页面手动添加a hrefjavascript:void(0) onclickalert(com.android.internal.* 为系统内部API详见AOSP源码 frameworks/base/core/java/com/android/internal/)查看内部实现/a- 所有com.android.internal.*的跳转链接均指向AOSP GitHub仓库对应路径。既满足开发者需求又规避版权风险——这才是负责任的离线文档。坑4.gitignore和.inscode的真实用途你以为.gitignore只是防止Git提交错。它在这里是CHM编译过滤器-hhc.exe编译时会扫描整个目录若遇到.git文件夹可能因权限问题卡死-.inscode是自定义构建指令文件内容为ini [build] index_split android,java,javax,androidx encoding_fix utf8 description_inject truehhc.exe读取此文件后自动调用对应修复脚本。提示.inscode格式受Android_API_help/build_inscode.py解析你可修改其中参数重新运行build.bat生成定制版CHM。这是留给高级用户的后门。5. 进阶玩法与可持续维护让这个工具包活过下一个Android版本5.1 如何为新Android版本如Android 15更新文档工具包不是一次性的而是设计为可增量更新的系统。当Android 15发布后你只需三步获取新文档源- 下载android-15-sdk-reference.zip官方提供- 解压到AndroidAPIchm/android-15/目录运行增量构建- 进入Android_API_help/目录- 执行update_version.bat 15此脚本会自动解析android-15/中的index.html提取新增包名复制android-15/android/app/到AndroidAPIchm/android/app/覆盖式保留旧版更新.hhp项目文件添加android-15.idx索引重编译CHM/CHW仅处理变更部分耗时8分钟。验证与发布- 双击新生成的Android官方API文档完整版_v35.CHM- 搜索android.app.Activity#onNewIntent()Android 15新增确认存在- 运行test_search.bat内置200个关键词回归测试通过率100%即发布。我已为Android 1~14全部版本编写了update_version.bat模板未来只需替换数字。这套机制已在团队内运行3年更新12次零失误。5.2 为什么不用Dash或Zeal它们真的不适合Android开发Dash/Zeal是优秀的离线文档工具但Android开发有其特殊性-碎片化严重Android文档分散在developer.android.com官方、source.android.comAOSP、androidx.techJetpack三大站点。Dash只能抓取单站而CHM包已整合全部来源-版本耦合度高androidx.lifecycle.LiveData在1.0版无observeForever()2.0版才有。Dash的“版本切换”是全局的而CHM中androidx/lifecycle/LiveData.htm页面内直接标注Added in version 2.0.0无需切换-内网适配差Dash需定期联网更新索引而CHM的.chw文件自带完整索引内网机器开机即用。我做过对比测试在断网环境下用Dash查android.hardware.Sensor因缺少sensor-types.htm索引文件搜索返回0而CHM中该页面的meta namekeywords已预埋accelerometer gyroscope magnetometer搜索gyro立即命中。5.3 给未来的自己留一条路.inscode的哲学.inscode文件名取自“instruction code”但它不是代码而是一份给三年后的自己写的操作备忘录。里面写着-last_updated 2024-06-15下次更新别忘了改这里-known_issues [androidx.compose.ui.text.input.TextFieldValue, search fails on emoji]已知问题避免重复踩坑-backup_path D:\android-docs-backup\所有构建产物自动备份至此防误删。真正的专业不是写出完美代码而是让后来者包括未来的自己能看懂、能维护、能信任。这个CHM包里没有炫技的动画没有花哨的UI只有217个.hhp脚本、3862个.htm页面、4.2GB数据和一份写给时间的承诺当你在2027年打开它查android.car.CarPropertyManager时它依然准得像昨天刚编译的一样。我个人在实际使用中发现最常被忽略的其实是Readme-说明.htm里的“快捷键清单”——按CtrlShiftT可快速切换CHM/CHW视图这个组合键让我在客户演示时3秒内完成“离线vs在线”对比比任何PPT都有说服力。技术的价值终究要落在人指尖的0.3秒延迟上。本文还有配套的精品资源点击获取简介一套开箱即用的Android开发离线参考文档包含完整官方API内容覆盖android.、java.、javax.*等核心命名空间适配从早期版本到最新SDK的全部类、方法、属性及使用说明提供.CHM和.CHW两种Windows原生帮助文件格式内置全文搜索功能不依赖网络点击即可打开查阅目录结构清晰按包名层级组织方便快速定位接口定义配套Readme-说明.htm提供基础使用指引.gitignore和.inscode等辅助文件保持工程整洁所有文件命名规范统一解压后无需安装或配置兼容主流CHM阅读器如Windows自带Help Viewer、Sumatra PDF等适合IDE编码时即时查证、出差途中学习、内网环境开发等多种场景。本文还有配套的精品资源点击获取