小程序图鉴类应用开发：从数据索引到列表渲染的完整实践

简介：宝可梦图鉴游戏小程序源码包，定位为面向安卓开发初学者和宝可梦爱好者的开源示例项目，解决快速查阅宝可梦名称、属性、种族值、技能、进化链等详细数据的需求，也可作为课程设计与毕业设计的参考蓝本。压缩包共981个文件，整体体积仅2.44MB，其中920张PNG图片构成视觉素材主体，23个JS脚本承载查询逻辑，12个JSON文件保存宝可梦条目，并配合WXML/WXSS页面描述文件呈现交互界面，资源、逻辑、数据、界面层次分明。已有333人浏览学习。通过研读源码，可学习SQLite或网络API的数据获取、RecyclerView列表展示、搜索过滤、动画交互等安卓常用实现；项目按安卓工程规范组织，包含Manifest配置、Gradle脚本、src源码、res资源等模块，还附带README说明，便于快速上手与排错。开发者可替换或扩充JSON数据，打造自定义宝可梦图鉴，适合练手、课程设计或二次开发。

1. 做宝可梦图鉴，先从数据模型开始

做图鉴小程序，最常见的尴尬是数据全拉下来了，列表却卡成 PPT。console 没红字，滚动一顿一顿，拆开看基本都栽在同一处：setData 把上千条完整对象一次性丢给渲染层，白屏不是网速问题，是数据通道被撑爆了。

“宝可梦图鉴（游戏小程序）”这个标题，图鉴是产品形态，“游戏”对应捕捉、收集和图鉴完成度这类交互。要做顺，得先把数据模型定清：编号怎么索引，属性怎么筛选，捕捉进度存哪里。这几件事想明白，页面才不至于互相拖累。

下文按数据建模、列表渲染、捕捉收集、启动适配四条线把可复现的路径讲完，代码和参数可直接抄进项目里改。适合写过基础小程序页面、想往数据密集型场景走一档的开发者。

2. 宝可梦图鉴的数据结构与索引设计

这里的复杂度不在于单条记录字段多，而在于查询路径多：按编号、按名字、按属性、按进化链，每一项都是一个检索入口。如果每个入口都循环一遍数组，页面一多必然卡。先把索引建起来，让查询变成 Map 查找，是整个项目最划算的一笔投资。

2.1 图鉴数据的 JSON 组织与字段取舍

先定一份最小可用的图鉴记录结构：

[ { "id": 1, "name": "妙蛙种子", "en": "Bulbasaur", "types": ["草", "毒"], "base": { "hp": 45, "atk": 49, "def": 49, "spa": 65, "spd": 65, "spe": 45 }, "captureRate": 45, "growthRate": "medium-slow", "evolvesFrom": null, "entry": "出生时就带着一颗种子……" } ]

id 用全国图鉴编号，从 1 开始，跨世代不重复，后续做捕捉位图正好可以拿它当下标。types 用数组，因为不少宝可梦是双属性，后面做属性倒排索引时直接遍历拼数组就行。captureRate 是捕捉概率计算的关键参数，growthRate 用于展示成长曲线，evolvesFrom 记录进化前编号，详情页展开进化链时不用二次查名字。

字段取舍上，entry 这种两三百字的长文本不要跟列表数据放同一个对象里。列表页只需要 id、name、types 三个字段参与渲染，entry 放进独立 map 按需读取。这样做不是因为存储贵，而是因为 setData 的 diff 和序列化成本会随字段长度增长，长文本进渲染层会拖低滚动帧率。

2.2 用 Map 建编号与属性倒排索引

原生小程序对 ES6 Map、Set 的支持没问题，可以在模块初始化时把索引建好，页面 onLoad 里直接 require 这个模块拿索引。

const pokemonList = require('../../data/pokedex.json'); const byId = new Map(); const byName = new Map(); const byType = new Map(); for (const pkm of pokemonList) { byId.set(pkm.id, pkm); byName.set(pkm.name, pkm); for (const t of pkm.types) { if (!byType.has(t)) byType.set(t, []); byType.get(t).push(pkm.id); } } function search({ keyword = '', types = [] }) { let ids = types.length ? types .map((t) => byType.get(t) || []) .reduce((acc, arr) => intersect(acc, arr)) : [...byId.keys()]; if (keyword) { ids = ids.filter((id) => { const p = byId.get(id); return p.name.includes(keyword) || p.en.toLowerCase().includes(keyword.toLowerCase()) || String(id) === keyword; }); } return ids.map((id) => byId.get(id)); } function intersect(a, b) { const setB = new Set(b); return a.filter((x) => setB.has(x)); } module.exports = { byId, byName, byType, search };

逻辑说明：由类型到 id 的索引用数组做倒排，属性筛选时对每个选中属性取 id 列表，再逐个做交集。这样是并行取集合，而不是遍历全量数据判断 in，在数据量过万之后差距很明显。keyword 部分无所谓索引，名称检索本质是子串匹配，走过滤而不是精确查找。

参数说明：search 的 types 是“且”语义，选草加毒会返回同时含这两个属性的记录；如果产品设计要“或”，把 reduce 里的 intersect 换成数组去重合并即可。返回的 ids 数组可以直接传给列表页做分页源，避免列表页再维护一份业务过滤逻辑。

2.3 本地数据与远程更新的边界

pokedex.json 放代码包里，用 require 同步读取，启动没有异步白屏，是图鉴类小程序最低成本的方案。但它占用代码包体积，主包 2M 限制下不建议把全部世代的 JSON 都塞进主包。常见做法是：数据文件放分包，或用静态托管存数据文件，启动时拉版本号判断要不要增量更新。

2.4 版本号字段与启动校验

无论走哪种远程方案，都建议在 data 目录放一个 version.json：{"version": 1}。启动时拿本地 storage 里的版本号和它比对，一致就跳过请求，不一致再拉最新 JSON。这样不会每次冷启动都等网络返回，列表页能先拿本地数据画出首屏，远程数据到了之后再决定是否替换。

这里版本号比较的对象是远程的版本标识，而不是 JSON 本身，避免把大文件拉下来之后才发现没变化。对宝可梦图鉴这种低频更新但数据量大的场景，这一层校验能省下大部分启动流量。

3. 小程序列表页：scroll-view 分批渲染、防抖搜索与多条件筛选

3.1 scroll-view 分批加载，避免一次 setData 拉垮渲染

页面结构上用 scroll-view 包列表，bindscrolltolower 触发加载。核心代码在 appendChunk，每次只往渲染层追加一页数据：

const PAGE_SIZE = 20; let allIds = []; Page({ data: { list: [], loadedCount: 0, hasMore: true }, onLoad() { const index = require('../../utils/index.js'); allIds = [...index.byId.keys()]; this.appendChunk(); }, appendChunk() { if (this.loadingMore) return; if (!this.data.hasMore) return; this.loadingMore = true; const start = this.data.loadedCount; const chunk = allIds.slice(start, start + PAGE_SIZE); const patch = { loadedCount: start + chunk.length, hasMore: start + chunk.length < allIds.length }; chunk.forEach((id, i) => { patch[`list[${start + i}]`] = index.byId.get(id); }); this.setData(patch, () => { this.loadingMore = false; }); } });

逻辑说明：这里刻意没有用this.data.list.concat(chunk)，因为 concat 会生成一个全新数组，setData 拿到新数组后会整体 diff，前面已经渲染过的内容也要重新比对一遍。用下标 key 做增量写入，渲染层只收到新增的 20 条变更，diff 范围小很多。

PAGE_SIZE 取 20 是经验值。小屏手机一屏大约显示 6 到 8 个图鉴条目，20 条刚好覆盖首屏加一个滑动余量，不会在滑动时频繁触发加载，也不会让首次进入页面等待太久。

3.2 300ms 防抖 + 多属性筛选的组合查询

搜索框输入时不可能每敲一个字符都查一次，尤其是拼音输入法联想阶段，输入框的 value 变化非常频繁。用 300ms 防抖把查询压缩到停顿后执行：

let debounceTimer = null; onSearchInput(e) { clearTimeout(debounceTimer); const keyword = e.detail.value.trim(); debounceTimer = setTimeout(() => { const result = search({ keyword, types: this.data.selectedTypes }); const slice = result.slice(0, PAGE_SIZE); this.setData({ list: slice, loadedCount: slice.length, hasMore: result.length > PAGE_SIZE }); }, 300); }

search 函数就是 2.2 里那个索引查询，它返回排序后的完整结果集，列表页只关心前 20 条，通过 hasMore 决定后续是否继续 appendChunk。这里 setData 用的是整数组替换，因为搜索本身就是一次上下文切换，用户期待的是新结果集，增量写入反而会在瞬间显示上一批的残留。

参数说明：搜索状态下的 PAGE_SIZE 可以比浏览态大一些，比如 30。搜索场景用户会快速按返回键清理筛选，结果集往往小于 30，一次给完更干脆。防抖时间 300ms 对中文输入够用，如果只按英文名检索可缩到 200ms，具体以连续输入不触发中间态为准。

3.3 过滤结果为空、上拉加载中的 UI 状态处理

空结果要单独给视图，不能只显示一个空白列表。我一般会在 wxml 里用wx:if="{{list.length === 0 && loaded == true}}"渲染空状态组件，文案提示“没有找到该属性组合下的宝可梦”，旁边放一个“清除筛选”按钮，直接重置 selectedTypes 和 keyword。

加载更多的锁要放在数据层而不是按钮层。bindscrolltolower 在 iOS 上触发很频繁，如果只在 setData 里维护 loading 字段，有可能在 setData 回调之前又进来一次。上面代码里的this.loadingMore是实例属性，不走渲染层，锁的粒度更细且不会带来额外 setData 开销。

提示：空状态组件建议用 CSS 动画做淡入，不要用 display:none 切换。iOS 上 display 切换后的首帧渲染偶发白屏，淡入可以把这个窗口遮过去。

3.4 setData 体积与渲染开销的关系

setData 的开销跟传输数据量和 diff 范围强相关，这里用一个直观对照说明：

如果数据规模继续往上走，比如包含全形态、Mega、地区形态的完整图鉴超过两万条，普通 scroll-view 也会兜不住，这时候要考虑回收列表方案，通过组件复用来限制实际渲染节点数，代价是列表项高度必须可控或者通过 onScroll 动态计算，实现成本高不少。

4. 捕捉与图鉴收集：位图存储、捕捉率计算与反连点

4.1 用位图字符串记录已捕捉编号

图鉴进度是“游戏小程序”区别于普通展示页的核心功能。已捕捉状态如果存成数组[1, 2, 3]，条目一多每次读取都要做 includes 判断，写入还要去重。换成位图字符串更省事：第 i 位是 0 或 1，代表编号 i+1 是否已捕捉。

const STORAGE_KEY = 'caught_map_v1'; function readCaughtMap() { return wx.getStorageSync(STORAGE_KEY) || ''; } function markCaught(id) { const current = readCaughtMap(); const idx = id - 1; let arr = current.split(''); arr[idx] = '1'; wx.setStorageSync(STORAGE_KEY, arr.join('')); } function isCaught(id) { return readCaughtMap()[id - 1] === '1'; }

逻辑说明：全国图鉴编号从 1 开始连续递增，编号直接映射字符串下标，省掉一层 HashMap。5000 条记录对应 5000 字节，远低于小程序本地存储的单键上限。读取时不涉及序列化，用下标取字符比数组 includes 快得多。

参数说明：这里位图的一位对应一个编号，如果游戏里要做形态区分，比如同一编号的不同形态独立计数，就把位图键改成 shapeId 而不是 id，字符串长度不变，只是业务层映射关系多一层。storage key 带 v1 是为了将来做进度迁移，数据格式有破坏性变化时直接换 key 而不必兼容旧数据。

4.2 捕捉率公式与精灵球权重参数

捕捉判定可以近似官方公式：

const BALL = { normal: 1, super: 1.5, ultra: 2, master: 255 }; const STATUS = { normal: 1, sleep: 2, paralysis: 1.5 }; function tryCatch(pkm, ball, status) { const rate = Math.max(1, Math.min(255, pkm.captureRate * BALL[ball] * STATUS[status])); const chance = Math.pow(rate / 255, 0.75); return Math.random() < chance; }

公式里 0.75 次方的作用是压缩低概率区间的差距：captureRate 为 255 时概率是 1，为 45 时约 8%，为 3 时约 1%。这样御三家不会太难抓，也不会让传说级宝可梦变成纯粹看运气。

注意这里 Math.random 只在客户端判定，只适合做演示和单机体验。正式线上版本要把随机数生成放到云函数，客户端把行为上报，服务端返回结果，避免改 storage 就能解锁全图鉴。

4.3 捕捉动画期间的按钮锁定

捕捉按钮最常见的 bug 是连续点击导致重复判定，一只宝可梦抓出两只。处理方式是动画期间把按钮状态置为 busy：

onCatchTap() { if (this.data.catching) return; this.setData({ catching: true }); this.setAnimationStep('throwing'); setTimeout(() => { const ok = tryCatch(this.data.currentPkm, this.data.ballType, this.data.status); if (ok) markCaught(this.data.currentPkm.id); this.setData({ catching: false }); this.setAnimationStep(ok ? 'caught' : 'escape'); }, 1500); }

状态锁加在 setData 之前，而不是在 setTimeout 回调里，能挡住同一次交互中连续触发的两次点击。动画时长 1500ms 要和精灵球晃动动画一致，动画没到绑定时间就解锁会让玩家觉得“球还在晃结果已经显示了”。

长时间运行后，建议把捕捉流程抽成状态机：idle、throwing、caught、escape 四态，throwing 期间任何操作都返回，避免 setData 和动画控制器里出现竞态。

5. 启动加载页、动态设置标题与导航栏高度适配

5.1 修改刚进入的加载页面

首次进入加载页最怕的是白屏等数据。常见做法是把首页配成轻量欢迎页，只渲染品牌和加载动画，核心索引数据在 onLoad 里直接 require 本地 JSON，不进网络。app.json 里首页路径指向 loading，onReady 后 wx.redirectTo 到列表页。

远程更新只是启动时的一个附加动作，不要阻塞首屏。数据拉完通过全局事件通知列表页刷新，拉失败就继续用本地缓存，保证用户先进得来。

5.2 用 wx.setNavigationBarTitle 动态设置标题

列表页显示“宝可梦图鉴”，详情页显示宝可梦名字，捕捉中显示捕捉进度，这些都要靠 wx.setNavigationBarTitle：

wx.setNavigationBarTitle({ title: `宝可梦图鉴 · ${caughtCount}/${totalCount}` });

在 uni-app 工程里对应的是 uni.setNavigationBarTitle，HBuilderX 下直接写 uni 前缀，代码结构一样。标题长度要注意，iOS 会截断超长文本，进度数字写在前面比写在后面稳。

5.3 胶囊按钮与顶部导航栏高度计算

自定义导航栏在 iPhone 灵动岛上最容易顶到胶囊。动态计算高度的方法是拿胶囊按钮的位置反推：

const win = wx.getWindowInfo(); const menu = wx.getMenuButtonBoundingClientRect(); const navBarHeight = (menu.top - win.statusBarHeight) * 2 + menu.height;

这段计算要在启动加载页 onReady 后执行，结果存到 globalData，列表页、详情页直接取用。menu.height 与状态栏高度共同决定上下留白，胶囊顶部到状态栏底部的差值乘 2 加胶囊高度，正好覆盖标题栏完整区域。上面拿到 navBarHeight 后，再定义一个通用的 paddingTop 样式变量，所有自定义导航栏的页面统一引用，比每个页面各写一份安全区适配要省心得多。

本文还有配套的精品资源，点击获取