wdh_gitpracticed

软件工程实验 吴彦2祖 小米便签 Git实验

小米便签 (Xiaomi Notes) 配置指南

目录

• 1. 项目概述
• 2. 环境要求
• 3. 开发环境搭建
• 4. 项目结构说明
• 5. Gradle 构建配置
• 6. AndroidManifest 权限与组件配置
• 7. 数据库配置
• 8. Google Tasks 同步配置
• 9. 应用内设置项配置
• 10. 桌面小部件配置
• 11. 多语言配置
• 12. 构建与安装
• 13. 常见问题

---

1. 项目概述

小米便签是小米开源社区 (MiCode) 发布的一款 Android 笔记应用，采用 Apache License 2.0 协议。

核心功能：

• 文本笔记的创建、编辑、删除
• 文件夹分类管理
• 5 种笔记背景色（黄、蓝、白、绿、红）
• 4 种字体大小（小、中、大、超大）
• 清单/待办模式
• 笔记提醒闹钟
• 桌面小部件（2x2、4x4）
• Google Tasks 云端同步
• 全文搜索
• 导出笔记为文本文件
• 将笔记发送到桌面快捷方式
• 通话记录笔记
• 分享笔记到其他应用

---

2. 环境要求

需求项	说明
操作系统	Windows / macOS / Linux
JDK	Java 11 或更高
Gradle	9.3.1（项目自带 Gradle Wrapper，无需手动安装）
Android SDK	API 36（Android 15），最低支持 API 24（Android 7.0）
Android Studio	推荐使用最新版（Hedgehog 或更高）
内存	Gradle 构建需分配 2GB+ JVM 内存

---

3. 开发环境搭建

3.1 安装 Android Studio

1. 从 developer.android.com 下载并安装 Android Studio
2. 启动 Android Studio，通过 SDK Manager 安装以下组件：
   • Android SDK Platform 36
   • Android SDK Build-Tools 36.x
   • Android SDK Platform-Tools
   • Android Emulator（如需要在模拟器中运行）

3.2 配置 Android SDK 路径

项目根目录下的 local.properties 文件中指定 SDK 路径（首次用 Android Studio 打开项目时会自动生成）：

# local.properties
sdk.dir=C\:\\Users\\<你的用户名>\\AppData\\Local\\Android\\Sdk

如果是 macOS：

sdk.dir=/Users/<你的用户名>/Library/Android/sdk

3.3 导入项目

1. 打开 Android Studio
2. 选择 File → Open
3. 选择项目根目录 wdh_gitpracticed
4. 等待 Gradle Sync 完成

---

4. 项目结构说明

wdh_gitpracticed/
├── build.gradle                  # 顶层构建文件（声明 Android 插件）
├── settings.gradle               # 项目设置（模块声明、仓库配置）
├── gradle.properties             # Gradle JVM 配置
├── gradlew / gradlew.bat         # Gradle Wrapper 脚本
├── local.properties              # Android SDK 路径（本地配置）
├── gradle/
│   ├── wrapper/                  # Gradle Wrapper 文件
│   └── libs.versions.toml        # 版本目录（集中管理依赖版本）
├── app/
│   ├── build.gradle              # 应用级构建配置
│   └── src/main/
│       ├── AndroidManifest.xml   # 应用清单文件
│       ├── res/                  # 资源文件
│       │   ├── layout/           # 布局 XML（14个）
│       │   ├── drawable/         # 图标和图形资源
│       │   ├── menu/             # 菜单 XML
│       │   ├── values/           # 字符串、颜色、尺寸、样式
│       │   ├── values-zh-rCN/    # 简体中文翻译
│       │   ├── values-zh-rTW/    # 繁体中文翻译
│       │   ├── xml/              # preferences.xml、widget 信息等
│       │   └── raw/              # 首次使用介绍文本
│       └── java/net/micode/notes/
│           ├── data/             # 数据层（ContentProvider、数据库、联系人）
│           ├── model/            # 模型层（Note、WorkingNote）
│           ├── ui/               # UI 层（Activity、Adapter、闹钟）
│           ├── widget/           # 桌面小部件
│           ├── tool/             # 工具类（导出、数据工具、资源解析）
│           └── gtask/            # Google Tasks 同步模块
│               ├── data/         # 同步数据模型
│               ├── remote/       # HTTP 客户端、同步服务
│               └── exception/    # 异常定义
└── build/                        # 构建输出目录

---

5. Gradle 构建配置

5.1 版本目录 gradle/libs.versions.toml

依赖版本集中管理，修改此处即可统一升级：

[versions]
agp = "9.1.1"                # Android Gradle Plugin 版本
junit = "4.13.2"             # JUnit 测试框架
junitVersion = "1.3.0"       # AndroidX Test JUnit
espressoCore = "3.7.0"       # Espresso UI 测试
appcompat = "1.7.1"          # AndroidX AppCompat
material = "1.13.0"          # Material Design 组件
activity = "1.13.0"          # AndroidX Activity
constraintlayout = "2.1.4"   # ConstraintLayout

[libraries]
# 此处定义所有依赖库及其版本引用

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }

5.2 应用构建配置 app/build.gradle

android {
    namespace 'net.micode.notes'        // 应用命名空间
    compileSdk {
        version = release(36) {
            minorApiLevel = 1            // 编译 SDK 版本（Android 15 + minor API 1）
        }
        useLibrary 'org.apache.http.legacy'  // 使用旧版 Apache HTTP 库
    }

    defaultConfig {
        applicationId "net.micode.notes"    // 应用唯一标识
        minSdk 24                            // 最低 Android 7.0
        targetSdk 36                         // 目标 Android 15
        versionCode 1                        // 版本号
        versionName "1.0"                    // 版本名
    }

    buildTypes {
        release {
            minifyEnabled false              // 发布版不混淆代码
            proguardFiles 'proguard-android-optimize.txt', 'proguard-rules.pro'
        }
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
}

关键配置说明：

配置项	值	说明
namespace	net.micode.notes	应用命名空间，代码中 R 类的包路径
compileSdk	36 + minorApiLevel 1	编译使用的 SDK 版本
minSdk	24	最低支持 Android 7.0
targetSdk	36	目标适配 Android 15
useLibrary	org.apache.http.legacy	Google Tasks 同步依赖旧版 Apache HTTP

5.3 Gradle 内存配置 gradle.properties

org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
# org.gradle.parallel=true          # 如需加速构建可取消注释

调整建议：

• 如果构建缓慢或 OOM，可将 -Xmx2048m 改为 -Xmx4096m
• 在多模块项目中可启用 org.gradle.parallel=true 并行构建

5.4 仓库配置 settings.gradle

pluginManagement {
    repositories {
        google()        // Android 官方插件仓库
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()        // AndroidX 等依赖
        mavenCentral()
    }
}

注意： 由于网络原因，国内用户可能需要配置镜像仓库（参见常见问题）。

---

6. AndroidManifest 权限与组件配置

6.1 权限列表

权限	用途
WRITE_EXTERNAL_STORAGE	导出笔记到 SD 卡
INTERNET	Google Tasks 网络同步
READ_CONTACTS	读取联系人（通话笔记功能）
MANAGE_ACCOUNTS	管理 Google 账户
AUTHENTICATE_ACCOUNTS	账户认证
GET_ACCOUNTS	获取设备上的账户列表
USE_CREDENTIALS	使用已存储的凭证
RECEIVE_BOOT_COMPLETED	开机后重新注册闹钟提醒
INSTALL_SHORTCUT	将笔记发送到桌面

6.2 主要组件

Activity

Activity	说明
NotesListActivity	启动页：笔记列表主页，支持文件夹导航、批量操作、搜索、导出
NoteEditActivity	编辑页：笔记编辑，支持富文本、清单模式、背景色、字体、提醒
AlarmAlertActivity	闹钟提醒全屏弹窗
NotesPreferenceActivity	设置页：同步账户管理、背景色随机开关

Service

Service	说明
GTaskSyncService	后台执行 Google Tasks 同步任务

BroadcastReceiver

Receiver	说明
NoteWidgetProvider_2x	2x2 桌面小部件
NoteWidgetProvider_4x	4x4 桌面小部件
AlarmInitReceiver	开机广播 → 重新注册所有笔记闹钟
AlarmReceiver	闹钟触发广播（独立进程 :remote）

ContentProvider

Provider	说明
NotesProvider	数据提供者，authorities="micode_notes"，供搜索建议和其他应用访问

---

7. 数据库配置

7.1 数据库文件

应用使用 SQLite 数据库，文件位于 NotesDatabaseHelper.java，数据库名为 note.db，版本号为 4。

7.2 表结构

note 表

列名	类型	说明
_id	INTEGER PRIMARY KEY	唯一 ID
parent_id	BIGINT NOT NULL	父文件夹 ID（0=根目录, -2=通话记录, -3=回收站）
type	INTEGER	类型：0=笔记, 1=文件夹, 2=系统文件夹
created_date	BIGINT	创建时间戳
modified_date	BIGINT	修改时间戳
alerted_date	BIGINT	提醒时间戳
bg_color_id	INTEGER	背景色 ID（0-4）
snippet	TEXT	笔记摘要
widget_id	INTEGER	关联的桌面小部件 ID
widget_type	INTEGER	关联的桌面小部件类型
gtask_id	TEXT	Google Task ID
sync_id	INTEGER	同步状态标记
origin_parent_id	BIGINT	原始父文件夹 ID
version	BIGINT	版本号

data 表

列名	类型	说明
_id	INTEGER PRIMARY KEY	唯一 ID
mime_type	TEXT NOT NULL	MIME 类型（text_note / call_note）
note_id	BIGINT NOT NULL	所属 note 的 ID
content_type	INTEGER	内容类型
content	TEXT	内容数据（JSON 格式）
data1 ~ data4	BIGINT	扩展数据字段

7.3 关键 Content URI

content://micode_notes/note          # 笔记表 URI
content://micode_notes/data          # 数据表 URI
content://micode_notes/search        # 搜索建议 URI

---

8. Google Tasks 同步配置

8.1 同步架构

[Android AccountManager]
        ↓ 获取 Google 账户 & AuthToken
[GTaskClient]  ← HTTP 请求 →  Google Tasks API
        ↓ JSON
[GTaskManager]  ← 对比本地/远程 →  执行同步动作
        ↓
[SqlNote / SqlData]  ←→  ContentProvider  ←→  SQLite

8.2 同步任务类型

同步动作	说明
ADD_LOCAL	远程有而本地没有 → 下载到本地
ADD_REMOTE	本地有而远程没有 → 上传到远程
DEL_LOCAL	远程已删除 → 删除本地
DEL_REMOTE	本地已删除 → 删除远程
UPDATE_LOCAL	远程已修改 → 更新本地
UPDATE_REMOTE	本地已修改 → 更新远程
UPDATE_CONFLICT	双方均修改 → 冲突处理
SYNC_CONFLICT	同步方向冲突

8.3 配置同步账户

1. 在设备上登录 Google 账户
2. 打开小米便签 → 菜单 → Settings
3. 在 Sync account 中选择 Google 账户
4. 点击 Sync immediately 立即同步

8.4 网络要求

• 设备需要能够访问 Google 服务（可能需要科学上网）
• 同步使用 https://mail.google.com/tasks/ 相关的 API 端点

---

9. 应用内设置项配置

9.1 设置页面 res/xml/preferences.xml

<PreferenceScreen>
    <!-- 同步账户管理 -->
    <PreferenceCategory android:key="pref_sync_account_key">
        <!-- 代码中动态添加账户选择、同步按钮等 -->
    </PreferenceCategory>

    <!-- 通用设置 -->
    <PreferenceCategory>
        <CheckBoxPreference
            android:key="pref_key_bg_random_appear"
            android:title="New note background color random"
            android:defaultValue="false" />
    </PreferenceCategory>
</PreferenceScreen>

9.2 背景色配置

背景色定义在 ResourceParser.java 中，支持 5 种颜色：

颜色常量	对应颜色
YELLOW (0)	黄色（默认）
BLUE (1)	蓝色
WHITE (2)	白色
GREEN (3)	绿色
RED (4)	红色

勾选 "New note background color random" 后，新建笔记时会随机选取背景色。

9.3 字体大小配置

字体大小定义在 ResourceParser.java 中，支持 4 种：

常量	对应样式
SMALL (0)	小号字体
MEDIUM (1)	中号字体（默认）
LARGE (2)	大号字体
SUPER (3)	超大字体

---

10. 桌面小部件配置

10.1 小部件尺寸

小部件	尺寸	配置文件
NoteWidgetProvider_2x	2x2	res/xml/widget_2x_info.xml
NoteWidgetProvider_4x	4x4	res/xml/widget_4x_info.xml

10.2 小部件行为

• 点击小部件 → 打开关联笔记进入编辑
• 未关联笔记时 → 提示创建新笔记
• 隐私模式下 → 隐藏笔记内容，显示提示文字
• 支持 APPWIDGET_UPDATE 和 APPWIDGET_DELETED 广播

---

11. 多语言配置

项目支持三种语言，通过 res/ 下的 values 目录区分：

目录	语言
res/values/	英语（默认/回退）
res/values-zh-rCN/	简体中文
res/values-zh-rTW/	繁体中文

应用会自动根据系统语言选择合适的资源。如需添加新语言：

1. 在 res/ 下新建 values-<语言代码>/ 目录
2. 复制 values/strings.xml 并翻译
3. 重新构建即可

---

12. 构建与安装

12.1 命令行构建

# 进入项目目录
cd wdh_gitpracticed

# 检查 Gradle Wrapper 权限（macOS/Linux）
chmod +x gradlew

# 编译 Debug 版本
./gradlew assembleDebug

# 编译 Release 版本
./gradlew assembleRelease

# 安装到已连接的设备（Debug 版本）
./gradlew installDebug

# 清理构建产物
./gradlew clean

Windows 系统使用 gradlew.bat：

gradlew.bat assembleDebug
gradlew.bat installDebug

12.2 运行测试

# 运行单元测试
./gradlew test

# 运行 UI 测试（需要连接设备或模拟器）
./gradlew connectedAndroidTest

12.3 APK 输出位置

app/build/outputs/apk/debug/app-debug.apk
app/build/outputs/apk/release/app-release-unsigned.apk

---

13. 常见问题

13.1 Gradle Sync 失败（国内网络）

原因： 无法访问 Google 和 Maven Central 仓库。

解决方案： 在 settings.gradle 中添加国内镜像：

repositories {
    maven { url 'https://maven.aliyun.com/repository/google' }
    maven { url 'https://maven.aliyun.com/repository/central' }
    maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
    google()
    mavenCentral()
    gradlePluginPortal()
}

13.2 local.properties 缺失

如果出现 SDK location not found 错误，在项目根目录创建 local.properties：

# Windows
sdk.dir=C\:\\Users\\<用户名>\\AppData\\Local\\Android\\Sdk

# macOS
sdk.dir=/Users/<用户名>/Library/Android/sdk

# Linux
sdk.dir=/home/<用户名>/Android/Sdk

13.3 编译提示找不到 org.apache.http.legacy

原因： compileSdk 需要使用 release() 写法才能正确包含该库。

确认： app/build.gradle 中的 compileSdk 使用了如下写法（已在项目中配置好）：

compileSdk {
    version = release(36) {
        minorApiLevel = 1
    }
    useLibrary 'org.apache.http.legacy'
}

13.4 Java 版本不匹配

项目需要 Java 11。检查当前 Java 版本：

java -version

如需切换版本，在 Android Studio 中：File → Settings → Build → Build Tools → Gradle → Gradle JDK，选择 JDK 11。

13.5 同步功能无法使用

• 确认设备已登录 Google 账户
• 确认设备可以访问 Google 服务
• 在 设置 → Sync account 中确认已选择账户
• 查看 Logcat 过滤 GTask 相关日志排查问题

13.6 APK 安装提示签名冲突

如果设备上已安装签名不一致的同一应用，需要先卸载旧版本：

adb uninstall net.micode.notes

---

附录：关键文件索引

文件	用途
app/build.gradle	应用构建配置（SDK 版本、依赖）
gradle/libs.versions.toml	依赖版本管理
settings.gradle	仓库与模块配置
gradle.properties	Gradle 运行参数
app/src/main/AndroidManifest.xml	权限、组件声明
res/xml/preferences.xml	设置页面布局
res/values/strings.xml	英文字符串资源
app/src/main/java/net/micode/notes/data/NotesDatabaseHelper.java	数据库模式定义
app/src/main/java/net/micode/notes/data/NotesProvider.java	ContentProvider 实现
app/src/main/java/net/micode/notes/tool/ResourceParser.java	背景色和字体资源映射
app/src/main/java/net/micode/notes/gtask/remote/GTaskManager.java	同步逻辑核心