1. ListView 三种适配器到底怎么选从字符串列表到数据库游标的真实场景ListView 是 Android 里最经典的列表控件它本身只负责“把一行行数据从上往下排好”真正决定每一行长什么样、数据从哪来全靠适配器。你可以把 ListView 想成一个书架适配器就是那个“把书按顺序摆上去”的人书是字符串、是 Map、还是数据库游标摆法完全不同。我见过太多项目在选型上翻车明明只是显示一个城市列表却硬上 SimpleCursorAdapter明明要从 SQLite 读几百条记录却用 ArrayAdapter 手动拼字符串。结果要么代码臃肿要么性能拉胯。这篇就把 ArrayAdapter、SimpleAdapter、SimpleCursorAdapter 三种适配器的适用边界讲清楚每种都给可复制的布局 XML 和 Java/Kotlin 初始化代码最后再把模型调用的 endpoint 统一改到 TaoToken 管理 Key用日志和列表渲染结果验证绑定是否生效。先说结论方便你对号入座适配器数据源每行能显示典型场景ArrayAdapter数组 / List单行文本或重写 getView 自定义简单字符串列表、设置项SimpleAdapterListMapString,?多字段映射到多个 View名片、图文混排、静态多列SimpleCursorAdapterCursor数据库列映射到 ViewSQLite 查询结果、通讯录选型的核心判断只有一句话数据是不是来自数据库游标是就用 SimpleCursorAdapter不是但每行要显示多个字段用 SimpleAdapter只是单行文字ArrayAdapter 最省事。这里有个容易被忽略的点ArrayAdapter 默认调用对象的toString()来显示。如果你直接塞 Person 对象进去屏幕上会出现Person [name..., age...]这种调试字符串非常难看。所以要么重写toString()要么继承 ArrayAdapter 重写getView()。后者才是生产环境的做法因为你能完全控制每一行的布局。再补一个性能常识ListView 有“懒加载 视图复用”机制。一屏只能显示 4 行系统就只创建 4 个 Item View滑动时把划出屏幕的 View 拖回来复用只替换里面的内容。所以getView()里的convertView参数一定要用配合 ViewHolder 模式缓存子 View 引用避免每次都findViewById。这个优化不做几百条数据滑动就会明显卡顿。下面进入实操。我会先讲 TaoToken 的前置准备因为后面要演示把模型调用 endpoint 统一过去再逐个给三种适配器的完整代码然后是验证和排错。你可以按顺序跟做也可以直接跳到你需要的那一种。2. TaoToken 前置准备统一管理模型调用 Key 与 endpoint在写适配器代码之前先把模型调用的接入层准备好。很多同学在 Android 项目里到处硬编码 API Key散落在各个 Activity 里改一次要全局搜索非常痛苦。TaoToken 的思路是提供一个统一的 endpoint 和 Key 管理入口你只需要在配置里写一次 Base URL 和 Key所有模型调用都走这里。TaoToken 是什么、能做什么它是一个大模型 API 的统一接入网关把不同模型的调用收敛到一套兼容 OpenAI 风格的接口上。适合谁需要在 App 里集成模型能力、又不想为每个模型单独维护 Key 和地址的 Android 开发者。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 这个不加 UTM。你需要准备三样东西我把它叫做“三件套”后面所有配置都围绕它Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-xxxxModel ID比如gpt-4o-mini、claude-3-5-sonnet这类模型标识获取 Key 的入口在控制台的 API Keys 页面地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。创建后复制出来只显示一次丢了就重新建一个。如果你只是想先验证模型能不能通可以用模型对话页面直接试 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。长期做编码或 Agent 类任务建议看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。在 Android 项目里我建议把三件套写进local.properties或BuildConfig不要提交到 Git。下面是一个gradle.properties的示例配置路径和字段名你可以按项目实际情况调整# gradle.properties TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_MODEL_IDgpt-4o-mini然后在build.gradle里读取并注入 BuildConfigandroid { defaultConfig { buildConfigField String, TAOTOKEN_BASE_URL, \${TAOTOKEN_BASE_URL}\ buildConfigField String, TAOTOKEN_API_KEY, \${TAOTOKEN_API_KEY}\ buildConfigField String, TAOTOKEN_MODEL_ID, \${TAOTOKEN_MODEL_ID}\ } }这样代码里就能用BuildConfig.TAOTOKEN_BASE_URL拿到地址Key 也不会明文出现在源码里。注意gradle.properties要加进.gitignore团队协作时每人本地配一份。如果你用的是 Claude Code 这类命令行工具做辅助开发它的配置方式略有不同需要设置环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。Android 项目本身不依赖它但如果你用 Claude Code 帮忙写适配器代码配好会更顺。前置准备到这里就够了。核心记住Base URL、Key、Model ID 三件套写一次全局复用。接下来进入适配器实战。3. 三种适配器可复制配置布局 XML 与 Java/Kotlin 初始化代码这一节是全文的技术核心每种适配器我都给完整的布局 XML 和初始化代码你复制过去改改包名就能跑。3.1 ArrayAdapter单行字符串列表最快落地先建 Activity 的布局只放一个 ListView?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:orientationvertical android:layout_widthmatch_parent android:layout_heightmatch_parent ListView android:idid/list1 android:layout_widthmatch_parent android:layout_heightmatch_parent / /LinearLayoutJava 初始化代码public class MainActivity extends Activity { private final String[] data new String[]{ 第一章, 第二章, 第三章, 第四章, 第五章 }; Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); ListView lv findViewById(R.id.list1); ArrayAdapterString adapter new ArrayAdapter( this, android.R.layout.simple_list_item_1, data ); lv.setAdapter(adapter); } }Kotlin 版本更简洁class MainActivity : Activity() { private val data arrayOf(第一章, 第二章, 第三章, 第四章, 第五章) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.main) val lv findViewByIdListView(R.id.list1) lv.adapter ArrayAdapter( this, android.R.layout.simple_list_item_1, data ) } }android.R.layout.simple_list_item_1是系统自带的单行布局里面只有一个 TextViewid 是android.R.id.text1。这就是为什么 ArrayAdapter 只能显示一行字——布局里就一个 TextView。如果要显示多字段就得自定义 Item 布局并继承 ArrayAdapter 重写getView()。先建list_item_person.xml?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:orientationvertical android:layout_widthmatch_parent android:layout_heightwrap_content android:padding12dp TextView android:idid/person_name android:textSize20sp android:layout_widthwrap_content android:layout_heightwrap_content / TextView android:idid/person_age android:layout_widthwrap_content android:layout_heightwrap_content / TextView android:idid/person_email android:layout_widthwrap_content android:layout_heightwrap_content / TextView android:idid/person_address android:layout_widthwrap_content android:layout_heightwrap_content / /LinearLayout自定义 Adapter 加 ViewHolder 优化public class PersonAdapter extends ArrayAdapterPerson { private final LayoutInflater inflater; private final int resourceId; public PersonAdapter(Context context, int resourceId, ListPerson objects) { super(context, resourceId, objects); this.resourceId resourceId; this.inflater LayoutInflater.from(context); } static class ViewHolder { TextView name; TextView age; TextView email; TextView address; } Override public View getView(int position, View convertView, ViewGroup parent) { ViewHolder holder; if (convertView null) { convertView inflater.inflate(resourceId, parent, false); holder new ViewHolder(); holder.name convertView.findViewById(R.id.person_name); holder.age convertView.findViewById(R.id.person_age); holder.email convertView.findViewById(R.id.person_email); holder.address convertView.findViewById(R.id.person_address); convertView.setTag(holder); } else { holder (ViewHolder) convertView.getTag(); } Person person getItem(position); if (person ! null) { holder.name.setText(person.name); holder.age.setText(String.valueOf(person.age)); holder.email.setText(person.email); holder.address.setText(person.address); } return convertView; } }注意inflater.inflate(resourceId, parent, false)的第三个参数传false这是标准写法避免布局参数被错误应用。3.2 SimpleAdapterMap 数据绑定多字段SimpleAdapter 的数据源是ListMapString,?每个 Map 对应一行Map 的 key 映射到布局里的 View id。它不需要你自定义对象类适合字段不固定或临时拼装的场景。沿用上面的list_item_person.xml初始化代码public class SimpleAdapterDemo extends ListActivity { Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_list_demo); ListMapString, Object data new ArrayList(); MapString, Object map new HashMap(); map.put(name, 蔡志坤); map.put(age, 25); map.put(email, ffczk86example.com); map.put(address, 厦门市); data.add(map); map new HashMap(); map.put(name, 李杰华); map.put(age, 25); map.put(email, aabb.com); map.put(address, 漳州市); data.add(map); SimpleAdapter adapter new SimpleAdapter( this, data, R.layout.list_item_person, new String[]{name, age, email, address}, new int[]{R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address} ); setListAdapter(adapter); } }Kotlin 版本class SimpleAdapterDemo : ListActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_list_demo) val data mutableListOfMapString, Any() data.add(mapOf( name to 蔡志坤, age to 25, email to ffczk86example.com, address to 厦门市 )) data.add(mapOf( name to 李杰华, age to 25, email to aabb.com, address to 漳州市 )) val adapter SimpleAdapter( this, data, R.layout.list_item_person, arrayOf(name, age, email, address), intArrayOf(R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address) ) listAdapter adapter } }关键点from数组和to数组必须顺序一一对应。from[0]的值映射到to[0]的 View写反了就会出现名字显示到年龄框里的尴尬。SimpleAdapter 还支持图片只要 Map 里放的是资源 idint映射到 ImageView 的 id 上就行。这也是它比 ArrayAdapter 扩展性好的地方。3.3 SimpleCursorAdapter数据库游标直接映射SimpleCursorAdapter 专门对接 Cursor最典型的场景是从 SQLite 或 ContentProvider 查询后直接展示。它要求 Cursor 里必须有一个名为_id的列否则会报错。先建数据库帮助类public class DbHelper extends SQLiteOpenHelper { public DbHelper(Context context) { super(context, demo.db, null, 1); } Override public void onCreate(SQLiteDatabase db) { db.execSQL(CREATE TABLE person ( _id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, email TEXT, address TEXT)); db.execSQL(INSERT INTO person (name, age, email, address) VALUES (蔡志坤, 25, ffczk86example.com, 厦门市), (李杰华, 25, aabb.com, 漳州市), (张亮, 25, ccexample.com, 厦门市)); } Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { db.execSQL(DROP TABLE IF EXISTS person); onCreate(db); } }查询并用 SimpleCursorAdapter 绑定public class CursorAdapterDemo extends ListActivity { Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_list_demo); DbHelper helper new DbHelper(this); SQLiteDatabase db helper.getReadableDatabase(); Cursor cursor db.rawQuery( SELECT _id, name, age, email, address FROM person, null ); startManagingCursor(cursor); SimpleCursorAdapter adapter new SimpleCursorAdapter( this, R.layout.list_item_person, cursor, new String[]{name, age, email, address}, new int[]{R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address}, 0 ); setListAdapter(adapter); } }注意最后那个0是 flags 参数新版本 API 要求传CursorAdapter.FLAG_REGISTER_CONTENT_OBSERVER或 0。老教程里没有这个参数直接编译会报错这是很多人踩的坑。Kotlin 版本class CursorAdapterDemo : ListActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_list_demo) val helper DbHelper(this) val db helper.readableDatabase val cursor db.rawQuery( SELECT _id, name, age, email, address FROM person, null ) startManagingCursor(cursor) val adapter SimpleCursorAdapter( this, R.layout.list_item_person, cursor, arrayOf(name, age, email, address), intArrayOf(R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address), 0 ) listAdapter adapter } }三种适配器的配置到这里就齐了。你会发现它们的布局可以复用区别只在数据源和构造参数。选型时先看数据源形态再决定用哪个。4. 验证请求与成功结果日志与列表渲染双重确认代码写完不代表绑定生效必须验证。我习惯用两个手段Logcat 日志 列表实际渲染结果。先看日志验证。在getView()里加一行日志确认它被调用了、position 和 convertView 状态符合预期Override public View getView(int position, View convertView, ViewGroup parent) { Log.d(AdapterDebug, getView position position convertView (convertView null ? null : reused)); // ... 原有逻辑 }运行后观察 Logcat你会看到类似输出D/AdapterDebug: getView position0 convertViewnull D/AdapterDebug: getView position1 convertViewnull D/AdapterDebug: getView position2 convertViewnull D/AdapterDebug: getView position3 convertViewnull D/AdapterDebug: getView position4 convertViewreused D/AdapterDebug: getView position5 convertViewreused前几条convertViewnull说明系统在创建新 View后面变成reused说明复用机制生效了。如果一直是null说明你的getView()没有正确返回 convertView或者布局参数有问题。再看列表渲染。ArrayAdapter 的字符串列表应该从上到下依次显示“第一章”到“第五章”每行一行文字。SimpleAdapter 和 SimpleCursorAdapter 应该显示四行字段名字、年龄、邮箱、地址且顺序和from/to数组一致。如果列表是空的先检查三件事数据源是不是空集合、setAdapter有没有调用、ListView 的 id 有没有找对。如果显示的是Person [name...]这种字符串说明你用了 ArrayAdapter 但没重写getView()系统调了默认的toString()。模型调用 endpoint 的验证单独说。如果你在 App 里集成了模型调用把 Base URL 指向 TaoToken 后发一个最小请求确认连通curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里如果有choices数组且message.content有内容说明 Key 和 endpoint 都通了。这一步和适配器本身无关但它是你后续在列表里展示模型返回结果的前提。验证通过后你会看到列表正常渲染Logcat 里复用日志符合预期模型请求返回 200。三者都对上才算真正落地。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把真实会遇到的报错列出来对照排查。401 Unauthorized最常见。原因通常是 Key 没带、Key 写错、或者Authorization头格式不对。正确格式是Bearer sk-xxxx注意Bearer和 Key 之间有一个空格。如果你把 Key 写进了gradle.properties但没重新 syncBuildConfig 里可能是旧值clean 后重新 build 一次。local proxy failed / connection refused这个报错说明请求根本没发出去卡在本地网络层。检查你的 Base URL 是不是写成了https://taotoken.net/api/多了一个斜杠或者端口写错。Android 模拟器访问外部地址不需要额外配置但如果你在代码里手动设了代理要去掉。真机调试时确认设备网络正常。reading choices 相关报错通常是响应体解析失败。比如你期望返回 JSON但实际返回了 HTML 错误页解析器读到就崩了。先打印原始响应体确认。另一种情况是模型名写错服务端返回了错误结构你的代码却按成功结构去读choices[0]自然读不到。把 Model ID 和 TaoToken 文档里的可用模型列表核对一遍。OAuth / 鉴权失败如果你用的是 Claude Code 或类似工具报 OAuth 错误通常是环境变量没设对。需要同时设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY只设一个会失败。文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 里面有完整的环境变量清单。适配器相关的报错Cursor must include an _id columnSimpleCursorAdapter 要求查询结果必须包含_id列SQL 里显式写出来。The constructor SimpleCursorAdapter(...) is undefined新版 API 需要 flags 参数补上0或CursorAdapter.FLAG_REGISTER_CONTENT_OBSERVER。NullPointerException在getView()getItem(position)可能返回 null加判空。列表点击无响应如果 Item 里有 ButtonButton 会抢焦点给 Button 设android:focusablefalse。Key 管理相关的坑不要把 Key 硬编码在 Java 文件里一旦提交到 Git 就等于泄露。用gradle.propertiesBuildConfig的方式并且把gradle.properties加进.gitignore。团队协作时新成员拉代码后需要自己配一份本地 Key。排查顺序建议先看 Logcat 完整堆栈定位是网络层、解析层还是 UI 层网络层问题用 curl 单独验证 endpointUI 层问题用日志确认getView()调用情况。分层排查比盲目改代码快得多。6. 把 Key 统一到 TaoToken适配器项目里的接入收尾回到这篇的主线三种适配器负责把数据渲染到 ListViewTaoToken 负责把模型调用的 Key 和 endpoint 统一管理。两者在项目里的关系是——适配器管“显示”TaoToken 管“数据来源中的模型部分”。如果你要在列表里展示模型返回的内容比如一个“AI 建议列表”数据流是这样的先通过 TaoToken 的 endpoint 拿到模型返回解析成 List 或 Cursor再交给对应的适配器渲染。ArrayAdapter 适合单字段的模型输出SimpleAdapter 适合多字段结构化输出SimpleCursorAdapter 适合把模型结果落库后再展示。统一 Key 的好处在这里体现得很明显你不需要在每个 Activity 里重复配置 Base URL 和 Key改一次全局生效。三件套Base URL Key Model ID写进gradle.properties通过 BuildConfig 注入代码里只引用常量。需要创建或管理 Key去 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。想先验证模型通不通用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。长期做编码或 Agent 任务看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。接入细节和参数说明在文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。最后给一个实用技巧在 Adapter 的getView()里做数据绑定时如果某个字段来自模型调用且可能为空先给一个占位符再异步更新避免列表闪烁。模型调用是异步的适配器的notifyDataSetChanged()要在主线程调用数据更新后刷新列表。这样列表渲染和模型请求就能配合得很顺。
1. ListView 三种适配器到底怎么选从字符串列表到数据库游标的真实场景ListView 是 Android 里最经典的列表控件它本身只负责“把一行行数据从上往下排好”真正决定每一行长什么样、数据从哪来全靠适配器。你可以把 ListView 想成一个书架适配器就是那个“把书按顺序摆上去”的人书是字符串、是 Map、还是数据库游标摆法完全不同。我见过太多项目在选型上翻车明明只是显示一个城市列表却硬上 SimpleCursorAdapter明明要从 SQLite 读几百条记录却用 ArrayAdapter 手动拼字符串。结果要么代码臃肿要么性能拉胯。这篇就把 ArrayAdapter、SimpleAdapter、SimpleCursorAdapter 三种适配器的适用边界讲清楚每种都给可复制的布局 XML 和 Java/Kotlin 初始化代码最后再把模型调用的 endpoint 统一改到 TaoToken 管理 Key用日志和列表渲染结果验证绑定是否生效。先说结论方便你对号入座适配器数据源每行能显示典型场景ArrayAdapter数组 / List单行文本或重写 getView 自定义简单字符串列表、设置项SimpleAdapterListMapString,?多字段映射到多个 View名片、图文混排、静态多列SimpleCursorAdapterCursor数据库列映射到 ViewSQLite 查询结果、通讯录选型的核心判断只有一句话数据是不是来自数据库游标是就用 SimpleCursorAdapter不是但每行要显示多个字段用 SimpleAdapter只是单行文字ArrayAdapter 最省事。这里有个容易被忽略的点ArrayAdapter 默认调用对象的toString()来显示。如果你直接塞 Person 对象进去屏幕上会出现Person [name..., age...]这种调试字符串非常难看。所以要么重写toString()要么继承 ArrayAdapter 重写getView()。后者才是生产环境的做法因为你能完全控制每一行的布局。再补一个性能常识ListView 有“懒加载 视图复用”机制。一屏只能显示 4 行系统就只创建 4 个 Item View滑动时把划出屏幕的 View 拖回来复用只替换里面的内容。所以getView()里的convertView参数一定要用配合 ViewHolder 模式缓存子 View 引用避免每次都findViewById。这个优化不做几百条数据滑动就会明显卡顿。下面进入实操。我会先讲 TaoToken 的前置准备因为后面要演示把模型调用 endpoint 统一过去再逐个给三种适配器的完整代码然后是验证和排错。你可以按顺序跟做也可以直接跳到你需要的那一种。2. TaoToken 前置准备统一管理模型调用 Key 与 endpoint在写适配器代码之前先把模型调用的接入层准备好。很多同学在 Android 项目里到处硬编码 API Key散落在各个 Activity 里改一次要全局搜索非常痛苦。TaoToken 的思路是提供一个统一的 endpoint 和 Key 管理入口你只需要在配置里写一次 Base URL 和 Key所有模型调用都走这里。TaoToken 是什么、能做什么它是一个大模型 API 的统一接入网关把不同模型的调用收敛到一套兼容 OpenAI 风格的接口上。适合谁需要在 App 里集成模型能力、又不想为每个模型单独维护 Key 和地址的 Android 开发者。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 这个不加 UTM。你需要准备三样东西我把它叫做“三件套”后面所有配置都围绕它Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-xxxxModel ID比如gpt-4o-mini、claude-3-5-sonnet这类模型标识获取 Key 的入口在控制台的 API Keys 页面地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。创建后复制出来只显示一次丢了就重新建一个。如果你只是想先验证模型能不能通可以用模型对话页面直接试 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。长期做编码或 Agent 类任务建议看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。在 Android 项目里我建议把三件套写进local.properties或BuildConfig不要提交到 Git。下面是一个gradle.properties的示例配置路径和字段名你可以按项目实际情况调整# gradle.properties TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_MODEL_IDgpt-4o-mini然后在build.gradle里读取并注入 BuildConfigandroid { defaultConfig { buildConfigField String, TAOTOKEN_BASE_URL, \${TAOTOKEN_BASE_URL}\ buildConfigField String, TAOTOKEN_API_KEY, \${TAOTOKEN_API_KEY}\ buildConfigField String, TAOTOKEN_MODEL_ID, \${TAOTOKEN_MODEL_ID}\ } }这样代码里就能用BuildConfig.TAOTOKEN_BASE_URL拿到地址Key 也不会明文出现在源码里。注意gradle.properties要加进.gitignore团队协作时每人本地配一份。如果你用的是 Claude Code 这类命令行工具做辅助开发它的配置方式略有不同需要设置环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。Android 项目本身不依赖它但如果你用 Claude Code 帮忙写适配器代码配好会更顺。前置准备到这里就够了。核心记住Base URL、Key、Model ID 三件套写一次全局复用。接下来进入适配器实战。3. 三种适配器可复制配置布局 XML 与 Java/Kotlin 初始化代码这一节是全文的技术核心每种适配器我都给完整的布局 XML 和初始化代码你复制过去改改包名就能跑。3.1 ArrayAdapter单行字符串列表最快落地先建 Activity 的布局只放一个 ListView?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:orientationvertical android:layout_widthmatch_parent android:layout_heightmatch_parent ListView android:idid/list1 android:layout_widthmatch_parent android:layout_heightmatch_parent / /LinearLayoutJava 初始化代码public class MainActivity extends Activity { private final String[] data new String[]{ 第一章, 第二章, 第三章, 第四章, 第五章 }; Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); ListView lv findViewById(R.id.list1); ArrayAdapterString adapter new ArrayAdapter( this, android.R.layout.simple_list_item_1, data ); lv.setAdapter(adapter); } }Kotlin 版本更简洁class MainActivity : Activity() { private val data arrayOf(第一章, 第二章, 第三章, 第四章, 第五章) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.main) val lv findViewByIdListView(R.id.list1) lv.adapter ArrayAdapter( this, android.R.layout.simple_list_item_1, data ) } }android.R.layout.simple_list_item_1是系统自带的单行布局里面只有一个 TextViewid 是android.R.id.text1。这就是为什么 ArrayAdapter 只能显示一行字——布局里就一个 TextView。如果要显示多字段就得自定义 Item 布局并继承 ArrayAdapter 重写getView()。先建list_item_person.xml?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:orientationvertical android:layout_widthmatch_parent android:layout_heightwrap_content android:padding12dp TextView android:idid/person_name android:textSize20sp android:layout_widthwrap_content android:layout_heightwrap_content / TextView android:idid/person_age android:layout_widthwrap_content android:layout_heightwrap_content / TextView android:idid/person_email android:layout_widthwrap_content android:layout_heightwrap_content / TextView android:idid/person_address android:layout_widthwrap_content android:layout_heightwrap_content / /LinearLayout自定义 Adapter 加 ViewHolder 优化public class PersonAdapter extends ArrayAdapterPerson { private final LayoutInflater inflater; private final int resourceId; public PersonAdapter(Context context, int resourceId, ListPerson objects) { super(context, resourceId, objects); this.resourceId resourceId; this.inflater LayoutInflater.from(context); } static class ViewHolder { TextView name; TextView age; TextView email; TextView address; } Override public View getView(int position, View convertView, ViewGroup parent) { ViewHolder holder; if (convertView null) { convertView inflater.inflate(resourceId, parent, false); holder new ViewHolder(); holder.name convertView.findViewById(R.id.person_name); holder.age convertView.findViewById(R.id.person_age); holder.email convertView.findViewById(R.id.person_email); holder.address convertView.findViewById(R.id.person_address); convertView.setTag(holder); } else { holder (ViewHolder) convertView.getTag(); } Person person getItem(position); if (person ! null) { holder.name.setText(person.name); holder.age.setText(String.valueOf(person.age)); holder.email.setText(person.email); holder.address.setText(person.address); } return convertView; } }注意inflater.inflate(resourceId, parent, false)的第三个参数传false这是标准写法避免布局参数被错误应用。3.2 SimpleAdapterMap 数据绑定多字段SimpleAdapter 的数据源是ListMapString,?每个 Map 对应一行Map 的 key 映射到布局里的 View id。它不需要你自定义对象类适合字段不固定或临时拼装的场景。沿用上面的list_item_person.xml初始化代码public class SimpleAdapterDemo extends ListActivity { Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_list_demo); ListMapString, Object data new ArrayList(); MapString, Object map new HashMap(); map.put(name, 蔡志坤); map.put(age, 25); map.put(email, ffczk86example.com); map.put(address, 厦门市); data.add(map); map new HashMap(); map.put(name, 李杰华); map.put(age, 25); map.put(email, aabb.com); map.put(address, 漳州市); data.add(map); SimpleAdapter adapter new SimpleAdapter( this, data, R.layout.list_item_person, new String[]{name, age, email, address}, new int[]{R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address} ); setListAdapter(adapter); } }Kotlin 版本class SimpleAdapterDemo : ListActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_list_demo) val data mutableListOfMapString, Any() data.add(mapOf( name to 蔡志坤, age to 25, email to ffczk86example.com, address to 厦门市 )) data.add(mapOf( name to 李杰华, age to 25, email to aabb.com, address to 漳州市 )) val adapter SimpleAdapter( this, data, R.layout.list_item_person, arrayOf(name, age, email, address), intArrayOf(R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address) ) listAdapter adapter } }关键点from数组和to数组必须顺序一一对应。from[0]的值映射到to[0]的 View写反了就会出现名字显示到年龄框里的尴尬。SimpleAdapter 还支持图片只要 Map 里放的是资源 idint映射到 ImageView 的 id 上就行。这也是它比 ArrayAdapter 扩展性好的地方。3.3 SimpleCursorAdapter数据库游标直接映射SimpleCursorAdapter 专门对接 Cursor最典型的场景是从 SQLite 或 ContentProvider 查询后直接展示。它要求 Cursor 里必须有一个名为_id的列否则会报错。先建数据库帮助类public class DbHelper extends SQLiteOpenHelper { public DbHelper(Context context) { super(context, demo.db, null, 1); } Override public void onCreate(SQLiteDatabase db) { db.execSQL(CREATE TABLE person ( _id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, email TEXT, address TEXT)); db.execSQL(INSERT INTO person (name, age, email, address) VALUES (蔡志坤, 25, ffczk86example.com, 厦门市), (李杰华, 25, aabb.com, 漳州市), (张亮, 25, ccexample.com, 厦门市)); } Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { db.execSQL(DROP TABLE IF EXISTS person); onCreate(db); } }查询并用 SimpleCursorAdapter 绑定public class CursorAdapterDemo extends ListActivity { Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_list_demo); DbHelper helper new DbHelper(this); SQLiteDatabase db helper.getReadableDatabase(); Cursor cursor db.rawQuery( SELECT _id, name, age, email, address FROM person, null ); startManagingCursor(cursor); SimpleCursorAdapter adapter new SimpleCursorAdapter( this, R.layout.list_item_person, cursor, new String[]{name, age, email, address}, new int[]{R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address}, 0 ); setListAdapter(adapter); } }注意最后那个0是 flags 参数新版本 API 要求传CursorAdapter.FLAG_REGISTER_CONTENT_OBSERVER或 0。老教程里没有这个参数直接编译会报错这是很多人踩的坑。Kotlin 版本class CursorAdapterDemo : ListActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_list_demo) val helper DbHelper(this) val db helper.readableDatabase val cursor db.rawQuery( SELECT _id, name, age, email, address FROM person, null ) startManagingCursor(cursor) val adapter SimpleCursorAdapter( this, R.layout.list_item_person, cursor, arrayOf(name, age, email, address), intArrayOf(R.id.person_name, R.id.person_age, R.id.person_email, R.id.person_address), 0 ) listAdapter adapter } }三种适配器的配置到这里就齐了。你会发现它们的布局可以复用区别只在数据源和构造参数。选型时先看数据源形态再决定用哪个。4. 验证请求与成功结果日志与列表渲染双重确认代码写完不代表绑定生效必须验证。我习惯用两个手段Logcat 日志 列表实际渲染结果。先看日志验证。在getView()里加一行日志确认它被调用了、position 和 convertView 状态符合预期Override public View getView(int position, View convertView, ViewGroup parent) { Log.d(AdapterDebug, getView position position convertView (convertView null ? null : reused)); // ... 原有逻辑 }运行后观察 Logcat你会看到类似输出D/AdapterDebug: getView position0 convertViewnull D/AdapterDebug: getView position1 convertViewnull D/AdapterDebug: getView position2 convertViewnull D/AdapterDebug: getView position3 convertViewnull D/AdapterDebug: getView position4 convertViewreused D/AdapterDebug: getView position5 convertViewreused前几条convertViewnull说明系统在创建新 View后面变成reused说明复用机制生效了。如果一直是null说明你的getView()没有正确返回 convertView或者布局参数有问题。再看列表渲染。ArrayAdapter 的字符串列表应该从上到下依次显示“第一章”到“第五章”每行一行文字。SimpleAdapter 和 SimpleCursorAdapter 应该显示四行字段名字、年龄、邮箱、地址且顺序和from/to数组一致。如果列表是空的先检查三件事数据源是不是空集合、setAdapter有没有调用、ListView 的 id 有没有找对。如果显示的是Person [name...]这种字符串说明你用了 ArrayAdapter 但没重写getView()系统调了默认的toString()。模型调用 endpoint 的验证单独说。如果你在 App 里集成了模型调用把 Base URL 指向 TaoToken 后发一个最小请求确认连通curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里如果有choices数组且message.content有内容说明 Key 和 endpoint 都通了。这一步和适配器本身无关但它是你后续在列表里展示模型返回结果的前提。验证通过后你会看到列表正常渲染Logcat 里复用日志符合预期模型请求返回 200。三者都对上才算真正落地。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把真实会遇到的报错列出来对照排查。401 Unauthorized最常见。原因通常是 Key 没带、Key 写错、或者Authorization头格式不对。正确格式是Bearer sk-xxxx注意Bearer和 Key 之间有一个空格。如果你把 Key 写进了gradle.properties但没重新 syncBuildConfig 里可能是旧值clean 后重新 build 一次。local proxy failed / connection refused这个报错说明请求根本没发出去卡在本地网络层。检查你的 Base URL 是不是写成了https://taotoken.net/api/多了一个斜杠或者端口写错。Android 模拟器访问外部地址不需要额外配置但如果你在代码里手动设了代理要去掉。真机调试时确认设备网络正常。reading choices 相关报错通常是响应体解析失败。比如你期望返回 JSON但实际返回了 HTML 错误页解析器读到就崩了。先打印原始响应体确认。另一种情况是模型名写错服务端返回了错误结构你的代码却按成功结构去读choices[0]自然读不到。把 Model ID 和 TaoToken 文档里的可用模型列表核对一遍。OAuth / 鉴权失败如果你用的是 Claude Code 或类似工具报 OAuth 错误通常是环境变量没设对。需要同时设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY只设一个会失败。文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 里面有完整的环境变量清单。适配器相关的报错Cursor must include an _id columnSimpleCursorAdapter 要求查询结果必须包含_id列SQL 里显式写出来。The constructor SimpleCursorAdapter(...) is undefined新版 API 需要 flags 参数补上0或CursorAdapter.FLAG_REGISTER_CONTENT_OBSERVER。NullPointerException在getView()getItem(position)可能返回 null加判空。列表点击无响应如果 Item 里有 ButtonButton 会抢焦点给 Button 设android:focusablefalse。Key 管理相关的坑不要把 Key 硬编码在 Java 文件里一旦提交到 Git 就等于泄露。用gradle.propertiesBuildConfig的方式并且把gradle.properties加进.gitignore。团队协作时新成员拉代码后需要自己配一份本地 Key。排查顺序建议先看 Logcat 完整堆栈定位是网络层、解析层还是 UI 层网络层问题用 curl 单独验证 endpointUI 层问题用日志确认getView()调用情况。分层排查比盲目改代码快得多。6. 把 Key 统一到 TaoToken适配器项目里的接入收尾回到这篇的主线三种适配器负责把数据渲染到 ListViewTaoToken 负责把模型调用的 Key 和 endpoint 统一管理。两者在项目里的关系是——适配器管“显示”TaoToken 管“数据来源中的模型部分”。如果你要在列表里展示模型返回的内容比如一个“AI 建议列表”数据流是这样的先通过 TaoToken 的 endpoint 拿到模型返回解析成 List 或 Cursor再交给对应的适配器渲染。ArrayAdapter 适合单字段的模型输出SimpleAdapter 适合多字段结构化输出SimpleCursorAdapter 适合把模型结果落库后再展示。统一 Key 的好处在这里体现得很明显你不需要在每个 Activity 里重复配置 Base URL 和 Key改一次全局生效。三件套Base URL Key Model ID写进gradle.properties通过 BuildConfig 注入代码里只引用常量。需要创建或管理 Key去 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。想先验证模型通不通用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。长期做编码或 Agent 任务看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。接入细节和参数说明在文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。最后给一个实用技巧在 Adapter 的getView()里做数据绑定时如果某个字段来自模型调用且可能为空先给一个占位符再异步更新避免列表闪烁。模型调用是异步的适配器的notifyDataSetChanged()要在主线程调用数据更新后刷新列表。这样列表渲染和模型请求就能配合得很顺。
 Ubuntu 系统部署教程：把 settings 改到 TaoToken 打通微信接入)
