如何在Android中用Couchbase Lite存取数据并展示在ListView？

我明白你已经掌握了Manager、Database这些基础组件的创建，但卡在了数据加载和UI展示这一步。下面我会结合你的场景，一步步带你完成从数据存储、查询到ListView绑定与操作的完整流程。

一、先确认基础组件初始化正确 #

首先确保你的Manager和Database在合适的时机初始化（比如Activity的onCreate方法中），同时处理好Android的存储权限（6.0+需要动态申请）。这里给你一个标准的初始化模板：

public class MainActivity extends AppCompatActivity {
    final String dbname = "userdils";
    private Manager manager;
    private Database database;
    private ListView listView;
    private UserAdapter adapter;
    private List<Document> documentList = new ArrayList<>();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        listView = findViewById(R.id.list_view);

        // 初始化Couchbase Lite核心组件
        try {
            File appDir = getApplicationContext().getFilesDir();
            manager = new Manager(appDir, Manager.DEFAULT_OPTIONS);
            database = manager.getDatabase(dbname);
        } catch (IOException e) {
            Log.e("CouchbaseErr", "数据库初始化失败: " + e.getMessage());
            e.printStackTrace();
        }

        // 绑定ListView与自定义Adapter
        adapter = new UserAdapter(this, documentList);
        listView.setAdapter(adapter);

        // 加载已有数据
        loadDatabaseData();
        // 设置ListView操作监听
        setupListViewActions();
    }
}

二、实现数据的存储（新增/更新） #

不管是新增文档还是更新已有文档，核心都是构建数据Map后保存到Document中。这里写一个通用的方法：

// 新增或更新用户数据
private void saveUserData(String docId, String name, int age, String email) {
    try {
        Document targetDoc = database.getDocument(docId) != null 
            ? database.getDocument(docId) 
            : database.createDocument();

        // 构建要存储的键值对数据
        Map<String, Object> userProps = new HashMap<>();
        userProps.put("type", "user"); // 标记文档类型，方便后续过滤查询
        userProps.put("name", name);
        userProps.put("age", age);
        userProps.put("email", email);

        // 保存到数据库
        targetDoc.putProperties(userProps);
        Log.d("CouchbaseSuccess", "数据保存完成，文档ID: " + targetDoc.getId());

        // 保存后刷新ListView数据
        loadDatabaseData();
    } catch (CouchbaseLiteException e) {
        Log.e("CouchbaseErr", "数据保存失败: " + e.getMessage());
        e.printStackTrace();
    }
}

你可以在按钮点击事件中调用这个方法，比如：

findViewById(R.id.btn_add_user).setOnClickListener(v -> {
    saveUserData("user_001", "张三", 26, "zhangsan@example.com");
});

三、从数据库加载数据并绑定到ListView #

这是你卡住的核心环节，我们需要通过Query查询数据，再把结果转换成ListView能识别的数据集，最后更新Adapter。

第一步：创建自定义Adapter #

先写一个适配用户数据的Adapter，用来渲染ListView的每一项：

public class UserAdapter extends ArrayAdapter<Document> {
    private Context mContext;
    private List<Document> mDocs;

    public UserAdapter(Context context, List<Document> docs) {
        super(context, 0, docs);
        mContext = context;
        mDocs = docs;
    }

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        if (convertView == null) {
            convertView = LayoutInflater.from(mContext)
                .inflate(R.layout.item_user, parent, false);
        }

        Document userDoc = mDocs.get(position);
        Map<String, Object> props = userDoc.getProperties();

        // 绑定数据到UI控件
        TextView tvName = convertView.findViewById(R.id.tv_name);
        TextView tvAge = convertView.findViewById(R.id.tv_age);
        TextView tvEmail = convertView.findViewById(R.id.tv_email);

        tvName.setText("姓名: " + props.get("name"));
        tvAge.setText("年龄: " + props.get("age"));
        tvEmail.setText("邮箱: " + props.get("email"));

        return convertView;
    }
}

对应的item_user.xml布局（你需要自行创建）：

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical"
    android:padding="16dp">

    <TextView
        android:id="@+id/tv_name"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textSize="16sp"
        android:textStyle="bold"/>

    <TextView
        android:id="@+id/tv_age"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textSize="14sp"
        android:layout_marginTop="4dp"/>

    <TextView
        android:id="@+id/tv_email"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textSize="14sp"
        android:layout_marginTop="4dp"/>
</LinearLayout>

第二步：实现数据查询与加载 #

用你已经掌握的View来做数据索引和查询，这样性能更好：

// 从数据库加载所有用户数据
private void loadDatabaseData() {
    // 创建或获取用户数据的View
    View userView = database.getView("user_list_view");
    if (userView.getMap() == null) {
        // 定义View的Map函数，用于索引用户类型的文档
        userView.setMap(new Mapper() {
            @Override
            public void map(Map<String, Object> document, Emitter emitter) {
                // 只索引标记为user的文档
                if ("user".equals(document.get("type"))) {
                    emitter.emit(document.get("name"), document);
                }
            }
        }, "1.0"); // 版本号，修改Map逻辑时需要更新
    }

    // 执行查询并更新数据集
    Query query = userView.createQuery();
    try {
        QueryEnumerator result = query.run();
        documentList.clear();
        for (QueryRow row : result) {
            documentList.add(row.getDocument());
        }
        adapter.notifyDataSetChanged();
    } catch (CouchbaseLiteException e) {
        Log.e("CouchbaseErr", "数据查询失败: " + e.getMessage());
        e.printStackTrace();
    }
}

如果不需要复杂过滤，也可以直接用database.createAllDocumentsQuery()查询所有文档，不过View更适合后续扩展复杂查询。

四、实现ListView中的数据操作（删除/更新） #

给ListView添加事件监听，完成删除和更新操作：

private void setupListViewActions() {
    // 长按删除文档
    listView.setOnItemLongClickListener((parent, view, position, id) -> {
        Document targetDoc = documentList.get(position);
        try {
            targetDoc.delete();
            Log.d("CouchbaseSuccess", "文档删除成功: " + targetDoc.getId());
            loadDatabaseData();
        } catch (CouchbaseLiteException e) {
            Log.e("CouchbaseErr", "文档删除失败: " + e.getMessage());
            e.printStackTrace();
        }
        return true;
    });

    // 点击更新文档（示例：直接修改姓名）
    listView.setOnItemClickListener((parent, view, position, id) -> {
        Document targetDoc = documentList.get(position);
        // 这里可以弹出对话框让用户输入新数据，示例直接修改姓名
        saveUserData(
            targetDoc.getId(),
            "李四",
            (int) targetDoc.getProperty("age"),
            (String) targetDoc.getProperty("email")
        );
    });
}

五、关键注意事项 #

• 权限问题：Android 6.0及以上需要动态申请WRITE_EXTERNAL_STORAGE和READ_EXTERNAL_STORAGE权限，否则数据库初始化会失败。
• 线程优化：如果数据量较大，建议把查询操作放在子线程执行（比如用Coroutines或AsyncTask），避免阻塞UI线程。
• 异常处理：所有Couchbase Lite操作都可能抛出CouchbaseLiteException，一定要做好捕获和日志记录，方便排查问题。

内容的提问来源于stack exchange，提问作者Sarat