React Native + Expo 安卓快速开发实战：expo-sqlite、React Native Paper 与手势处理

前言#

想快速做一个安卓 App？Expo 是目前最低门槛的 React Native 开发方案——无需配置 Android Studio 的 NDK、无需手动链接原生模块，一条命令启动，扫码即可在真机预览。

本文以一个本地持久化 Todo 应用为例，串联以下四个核心库：

Expo — 托管工作流 + EAS Build
expo-sqlite — 设备本地 SQLite 数据库
React Native Paper — Material Design 3 UI 组件库
react-native-gesture-handler — 原生级手势（滑动删除等）

阅读完本文，你将拥有一个可以直接打包为 APK 的完整 App 骨架。

一、环境准备#

1.1 必装工具#

工具	版本要求	说明
Node.js	>= 18	推荐 LTS
pnpm / npm	任意	包管理器
Expo CLI	最新	`npm i -g expo`
EAS CLI	最新	云端打包用，`npm i -g eas-cli`

调试安卓有两条路：

真机：下载 Expo Go，扫码即可（最省事）
模拟器：安装 Android Studio，创建 AVD（需要 16 GB+ 内存推荐）

1.2 创建项目#

1
npx create-expo-app@latest TodoApp --template blank-typescript
2
cd TodoApp

二、安装依赖#

1
# SQLite
2
npx expo install expo-sqlite
3

4
# UI 组件库
5
npx expo install react-native-paper react-native-safe-area-context
6

7
# 手势处理（Paper 内部也依赖它）
8
npx expo install react-native-gesture-handler

npx expo install 会自动匹配与当前 Expo SDK 兼容的版本，不要用 npm install 替代。

三、项目结构#

1
TodoApp/
2
├── app/               # Expo Router 页面（或直接用 App.tsx）
3
├── components/
4
│   ├── TodoItem.tsx   # 单条 Todo（支持滑动删除）
5
│   └── AddTodoBar.tsx # 底部输入栏
6
├── db/
7
│   └── database.ts    # SQLite 初始化 & CRUD
8
├── App.tsx            # 入口，Provider 挂载
9
└── app.json

四、配置入口文件#

4.1 `App.tsx` — 挂载 Provider#

React Native Paper 和手势处理都需要在应用最外层包裹 Provider。

1
import { GestureHandlerRootView } from "react-native-gesture-handler";
2
import { PaperProvider, MD3LightTheme } from "react-native-paper";
3
import { StyleSheet } from "react-native";
4
import HomeScreen from "./components/HomeScreen";
5

6
export default function App() {
7
  return (
8
    <GestureHandlerRootView style={styles.root}>
9
      <PaperProvider theme={MD3LightTheme}>
10
        <HomeScreen />
11
      </PaperProvider>
12
    </GestureHandlerRootView>
13
  );
14
}
15

16
const styles = StyleSheet.create({
17
  root: { flex: 1 },
18
});

关键点：

GestureHandlerRootView 必须是最外层，否则手势无法正常工作。
flex: 1 确保它撑满全屏。

五、expo-sqlite 数据库层#

5.1 初始化数据库#

1
import * as SQLite from "expo-sqlite";
2

3
export interface Todo {
4
  id: number;
5
  text: string;
6
  done: number; // SQLite 没有 boolean，用 0/1
7
}
8

9
// openDatabaseSync 是 expo-sqlite v14+ 的同步 API
10
const db = SQLite.openDatabaseSync("todos.db");
11

12
export function initDB() {
13
  db.execSync(`
14
    CREATE TABLE IF NOT EXISTS todos (
15
      id   INTEGER PRIMARY KEY AUTOINCREMENT,
16
      text TEXT    NOT NULL,
17
      done INTEGER NOT NULL DEFAULT 0
18
    );
19
  `);
20
}
21

22
export function getTodos(): Todo[] {
23
  return db.getAllSync<Todo>("SELECT * FROM todos ORDER BY id DESC;");
24
}
25

26
export function addTodo(text: string): void {
27
  db.runSync("INSERT INTO todos (text, done) VALUES (?, ?);", text, 0);
28
}
29

30
export function toggleTodo(id: number, done: number): void {
31
  db.runSync("UPDATE todos SET done = ? WHERE id = ?;", done ? 0 : 1, id);
32
}
33

34
export function deleteTodo(id: number): void {
35
  db.runSync("DELETE FROM todos WHERE id = ?;", id);
36
}

expo-sqlite v14 引入了 同步 API（execSync / runSync / getAllSync），在主逻辑中使用更直观；若数据量大，改用异步版 runAsync / getAllAsync 避免阻塞 UI。

六、UI 组件#

6.1 `AddTodoBar.tsx` — 输入栏#

1
import { useState } from "react";
2
import { View, StyleSheet } from "react-native";
3
import { TextInput, IconButton } from "react-native-paper";
4

5
interface Props {
6
  onAdd: (text: string) => void;
7
}
8

9
export default function AddTodoBar({ onAdd }: Props) {
10
  const [text, setText] = useState("");
11

12
  const handleAdd = () => {
13
    const trimmed = text.trim();
14
    if (!trimmed) return;
15
    onAdd(trimmed);
16
    setText("");
17
  };
18

19
  return (
20
    <View style={styles.container}>
21
      <TextInput
22
        style={styles.input}
23
        mode="outlined"
24
        label="新增待办..."
25
        value={text}
26
        onChangeText={setText}
27
        onSubmitEditing={handleAdd}
28
        returnKeyType="done"
29
      />
30
      <IconButton
31
        icon="plus-circle"
32
        size={32}
33
        onPress={handleAdd}
34
        disabled={!text.trim()}
35
      />
36
    </View>
37
  );
38
}
39

40
const styles = StyleSheet.create({
41
  container: {
42
    flexDirection: "row",
43
    alignItems: "center",
44
    paddingHorizontal: 12,
45
    paddingBottom: 8,
46
  },
47
  input: { flex: 1 },
48
});

6.2 `TodoItem.tsx` — 滑动删除#

这里用 react-native-gesture-handler 的 Swipeable 实现左滑删除。

1
import { useRef } from "react";
2
import { View, StyleSheet } from "react-native";
3
import Swipeable from "react-native-gesture-handler/Swipeable";
4
import { List, Checkbox, IconButton, useTheme } from "react-native-paper";
5
import type { Todo } from "../db/database";
6

7
interface Props {
8
  item: Todo;
9
  onToggle: (id: number, done: number) => void;
10
  onDelete: (id: number) => void;
11
}
12

13
export default function TodoItem({ item, onToggle, onDelete }: Props) {
14
  const swipeRef = useRef<Swipeable>(null);
15
  const theme = useTheme();
16

17
  const renderRightActions = () => (
18
    <View style={[styles.deleteBox, { backgroundColor: theme.colors.error }]}>
19
      <IconButton icon="trash-can-outline" iconColor="#fff" size={28} />
20
    </View>
21
  );
22

23
  return (
24
    <Swipeable
25
      ref={swipeRef}
26
      renderRightActions={renderRightActions}
27
      onSwipeableOpen={() => {
28
        onDelete(item.id);
29
        swipeRef.current?.close();
30
      }}
31
      rightThreshold={80}
32
    >
33
      <List.Item
34
        title={item.text}
35
        titleStyle={item.done ? styles.done : undefined}
36
        left={() => (
37
          <Checkbox
38
            status={item.done ? "checked" : "unchecked"}
39
            onPress={() => onToggle(item.id, item.done)}
40
          />
41
        )}
42
        style={styles.item}
43
      />
44
    </Swipeable>
45
  );
46
}
47

48
const styles = StyleSheet.create({
49
  item: { backgroundColor: "#fff" },
50
  done: { textDecorationLine: "line-through", opacity: 0.5 },
51
  deleteBox: {
52
    justifyContent: "center",
53
    alignItems: "center",
54
    width: 80,
55
  },
56
});

6.3 `HomeScreen.tsx` — 主页面#

1
import { useEffect, useState } from "react";
2
import { FlatList, StyleSheet, View } from "react-native";
3
import { Appbar, Divider, Text } from "react-native-paper";
4
import { SafeAreaView } from "react-native-safe-area-context";
5
import {
6
  initDB,
7
  getTodos,
8
  addTodo,
9
  toggleTodo,
10
  deleteTodo,
11
  type Todo,
12
} from "../db/database";
13
import TodoItem from "./TodoItem";
14
import AddTodoBar from "./AddTodoBar";
15

16
export default function HomeScreen() {
17
  const [todos, setTodos] = useState<Todo[]>([]);
18

19
  const refresh = () => setTodos(getTodos());
20

21
  useEffect(() => {
22
    initDB();
23
    refresh();
24
  }, []);
25

26
  const handleAdd = (text: string) => {
27
    addTodo(text);
28
    refresh();
29
  };
30

31
  const handleToggle = (id: number, done: number) => {
32
    toggleTodo(id, done);
33
    refresh();
34
  };
35

36
  const handleDelete = (id: number) => {
37
    deleteTodo(id);
38
    refresh();
39
  };
40

41
  return (
42
    <SafeAreaView style={styles.container}>
43
      <Appbar.Header>
44
        <Appbar.Content title="我的待办" />
45
      </Appbar.Header>
46

47
      {todos.length === 0 ? (
48
        <View style={styles.empty}>
49
          <Text variant="bodyLarge">暂无待办，添加一条吧 🎉</Text>
50
        </View>
51
      ) : (
52
        <FlatList
53
          data={todos}
54
          keyExtractor={(item) => String(item.id)}
55
          ItemSeparatorComponent={Divider}
56
          renderItem={({ item }) => (
57
            <TodoItem
58
              item={item}
59
              onToggle={handleToggle}
60
              onDelete={handleDelete}
61
            />
62
          )}
63
        />
64
      )}
65

66
      <AddTodoBar onAdd={handleAdd} />
67
    </SafeAreaView>
68
  );
69
}
70

71
const styles = StyleSheet.create({
72
  container: { flex: 1, backgroundColor: "#f5f5f5" },
73
  empty: { flex: 1, justifyContent: "center", alignItems: "center" },
74
});

七、本地运行与真机调试#

1
npx expo start

终端会显示一个二维码：

安卓手机安装 Expo Go
打开 App 扫描二维码
修改代码 → 自动热更新，无需重启

如果和电脑不在同一 Wi-Fi，改用 Tunnel 模式：npx expo start --tunnel（需要安装 @expo/ngrok）

八、打包 APK（EAS Build）#

本地不需要安装 Android Studio，直接云端构建：

8.1 初始化 EAS#

1
eas login          # 登录 Expo 账号
2
eas build:configure

8.2 构建调试版 APK#

1
eas build -p android --profile preview

eas.json 中 preview 配置默认输出 APK（而非 AAB），适合直接安装到设备测试：

1
{
2
  "build": {
3
    "preview": {
4
      "android": {
5
        "buildType": "apk"
6
      }
7
    },
8
    "production": {}
9
  }
10
}

构建完成后 EAS 会给出下载链接，直接安装到安卓设备即可。

8.3 构建正式版（上架 Google Play）#

1
eas build -p android --profile production

正式版输出 AAB 格式，用于上传 Google Play Console。

九、常见问题#

`GestureHandlerRootView` 忘记包裹#

现象：滑动手势完全无响应。
解决：确保它是应用最外层组件，style={{ flex: 1 }} 不能省略。

expo-sqlite 同步 API 报错#

openDatabaseSync 在 expo-sqlite < 14 中不存在。
解决：npx expo install expo-sqlite 重新安装对齐版本，或查看 package.json 确认版本 >= 14.0.0。

Paper 组件样式在安卓上显示异常#

部分 Material 3 组件需要 react-native-safe-area-context 的 SafeAreaProvider。
解决：在 App.tsx 最外层加上：

1
import { SafeAreaProvider } from "react-native-safe-area-context";
2
// 包裹 PaperProvider
3
<SafeAreaProvider>
4
  <PaperProvider>...</PaperProvider>
5
</SafeAreaProvider>

真机扫码后白屏#

通常是 Metro Bundler 还未就绪。等待终端出现 Bundle loaded 后再刷新 App。

十、技术栈小结#

层次	技术	核心职责
开发框架	Expo (Managed Workflow)	零配置启动、EAS 云构建
本地存储	expo-sqlite	设备本地 SQL 数据库，离线可用
UI 组件	React Native Paper	Material Design 3，开箱即用
手势交互	react-native-gesture-handler	原生线程手势，流畅无卡顿

这套组合的优势在于全部走 Expo 生态，依赖版本自动对齐，几乎不会遇到原生链接问题，非常适合快速验证产品想法或独立开发者出品。

前言#