prwohun7f
/
minotes-lyzx
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Labels Milestones
New Pull Request

加 #6

Merged
prwohun7f merged 1 commits from zhaoxin_branch into master 5 hours ago
Conversation 0 Commits 1 Files Changed 17
17 changed files with 2701 additions and 2316 deletions
Show Stats Download Patch File Download Diff File

229
src/Notes-master/src/net/micode/notes/ui/AlarmAlertActivity.java
Unescape View File

@ -14,245 +14,260 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，作为便签提醒触发时的核心弹窗页面
// 包声明：归属小米便签UI模块，便签提醒功能的最终展示页，是提醒触发时用户感知的核心页面
package net.micode.notes.ui;
// 导入安卓Activity核心类：页面基础类
// 安卓页面核心基类，所有页面的父类，提供页面生命周期、窗口管理、组件交互等基础能力
import android.app.Activity;
// 导入安卓对话框类：展示便签提醒内容和操作按钮
// 安卓系统对话框核心类，用于展示标准化的弹窗，承载提醒内容与交互按钮，是本页面的核心展示载体
import android.app.AlertDialog;
// 导入安卓上下文类：访问系统服务、资源
// 安卓上下文核心类，提供系统服务获取、资源访问、组件通信等基础能力
import android.content.Context;
// 导入安卓对话框事件类：处理按钮点击、对话框关闭
// 安卓对话框事件回调相关类，处理按钮点击、对话框关闭等交互事件，实现页面的核心交互逻辑
import android.content.DialogInterface;
import android.content.DialogInterface.OnClickListener;
import android.content.DialogInterface.OnDismissListener;
// 导入安卓意图类：跳转便签编辑页、接收提醒所属便签ID
// 安卓意图核心类，用于页面跳转、数据传递，此处用于跳转便签编辑页并携带便签ID
import android.content.Intent;
// 导入安卓音频管理类：控制提醒铃声的音频流类型
// 安卓音频管理核心类，用于指定音频流类型，适配系统音量与静音规则，控制提醒铃声的播放策略
import android.media.AudioManager;
// 导入安卓媒体播放类：播放提醒铃声（系统闹钟铃声）
// 安卓媒体播放核心类，用于加载、播放、停止系统铃声资源，实现提醒音效的播放功能
import android.media.MediaPlayer;
// 导入安卓铃声管理类：获取系统默认闹钟铃声
// 安卓铃声管理核心类，用于获取系统默认的闹钟铃声Uri，统一访问系统铃声资源
import android.media.RingtoneManager;
// 导入安卓URI类：标识铃声资源、便签ID
// 安卓统一资源标识类，用于标记铃声资源地址、便签数据的唯一标识
import android.net.Uri;
// 导入安卓Bundle类：保存页面状态（此处未使用）
// 安卓页面状态保存类，用于横竖屏切换等场景的页面数据恢复，本页面未使用
import android.os.Bundle;
// 导入安卓电源管理类：判断屏幕是否亮屏，控制屏幕唤醒
// 安卓电源管理核心类，用于获取设备屏幕的亮灭状态，判断当前是亮屏/熄屏/锁屏状态
import android.os.PowerManager;
// 导入安卓系统设置类：获取铃声静音模式配置
// 安卓系统设置核心类，用于读取系统的铃声静音模式配置，适配不同的系统音频策略
import android.provider.Settings;
// 导入安卓窗口相关类：设置窗口标记（唤醒屏幕、锁屏显示等）
// 安卓窗口管理相关类，用于配置页面窗口的显示属性，实现锁屏显示、屏幕唤醒、常亮等核心功能
import android.view.Window;
import android.view.WindowManager;
// 导入小米便签资源类：引用字符串、布局等资源
// 小米便签资源常量类，引用字符串、布局、颜色等本地资源，统一管理资源ID
import net.micode.notes.R;
// 导入便签数据常量类：定义便签类型、ContentURI等
// 便签应用核心数据常量类，定义便签类型、ContentURI等全局常量，用于数据合法性校验
import net.micode.notes.data.Notes;
// 导入数据工具类：查询便签摘要、判断便签是否存在
// 便签数据工具类，封装数据库查询相关的通用方法，提供便签摘要查询、便签存在性校验等能力
import net.micode.notes.tool.DataUtils;
// 导入IO异常类：处理媒体播放器的IO错误
// Java IO异常类，捕获媒体播放器加载铃声资源时的IO错误，保证程序健壮性
import java.io.IOException;
/**
* 便签提醒弹窗页面
* 核心职责：
* 1. 屏幕唤醒与显示控制：
* - 锁屏/熄屏时唤醒屏幕、保持屏幕常亮，确保提醒弹窗可见；
* - 亮屏时仅展示弹窗，不额外修改屏幕状态；
* 2. 提醒内容展示：
* - 从Intent中解析提醒所属便签ID，查询并裁剪便签摘要（最大60字符）；
* - 弹窗展示便签摘要，提供“确认”“进入便签”按钮；
* 3. 提醒铃声播放：
* - 播放系统默认闹钟铃声，适配系统静音模式，铃声循环播放；
* - 对话框关闭时停止铃声并释放媒体资源；
* 4. 交互处理：
* - “确认”按钮：关闭弹窗，停止铃声；
* - “进入便签”按钮（仅亮屏时显示）：跳转到便签编辑页；
* 关键说明：
* - 仅当便签仍存在于数据库中时，才展示弹窗和播放铃声；
* - 页面生命周期与对话框绑定，对话框关闭即结束页面。
* 便签提醒功能核心弹窗页面【提醒展示最终页、用户感知唯一页】
* 继承：Activity 安卓页面基类，具备页面生命周期与窗口管理能力
* 实现：OnClickListener + OnDismissListener 对话框交互监听器，处理按钮点击与弹窗关闭事件
* 核心定位：小米便签「提醒功能」的终点站，是整个提醒流程的最终展示载体，也是用户能直接感知到的核心页面，所有提醒逻辑最终都汇聚于此，是便签提醒功能的核心价值体现
* 核心设计意义：作为提醒触发后的唯一展示页面，承担「强提醒+友好交互+精准跳转」的核心职责，既要保证用户不会错过提醒，又要提供便捷的后续操作，兼顾提醒的强制性与使用的人性化
* 核心职责（四大核心模块，逻辑闭环完整）：
* 一、屏幕状态智能管控【优先级最高，保障提醒可见性】
* 1. 精准判断设备当前屏幕状态：亮屏/熄屏/锁屏；
* 2. 熄屏/锁屏场景：自动唤醒屏幕、保持屏幕常亮、允许锁屏时显示窗口、适配系统装饰布局，确保弹窗能穿透锁屏界面直接展示，用户无需解锁即可看到提醒，核心保障「提醒必见」；
* 3. 亮屏场景：仅展示弹窗，不修改任何屏幕状态，避免干扰用户当前操作，兼顾使用体验；
* 4. 统一隐藏原生页面标题栏，仅展示核心的提醒弹窗，页面极简无冗余。
* 二、提醒数据解析与合法性校验【数据安全，避免无效展示】
* 1. 从跳转Intent中解析出绑定的便签ID：该ID由AlarmReceiver透传而来，是当前提醒的核心标识；
* 2. 根据便签ID查询数据库，获取便签的文本摘要内容，用于弹窗展示；
* 3. 摘要内容规范化处理：超过60字符自动裁剪并添加省略号，保证弹窗展示美观、无内容溢出；
* 4. 关键合法性校验：通过工具类判断该便签是否真实存在于数据库中（用户可能已删除该便签），仅当便签有效时才展示弹窗和播放铃声，无效则直接关闭页面，无任何无效操作。
* 三、系统铃声智能播放【听觉提醒，保障提醒感知】
* 1. 自动获取系统默认的闹钟铃声Uri，统一使用系统级铃声资源，适配用户的个性化铃声设置；
* 2. 适配系统静音模式：读取系统铃声流配置，自动选择合适的音频流类型，遵循系统的音量与静音规则，不强制发声干扰用户；
* 3. 铃声播放策略：循环播放提醒铃声，直到用户点击按钮关闭弹窗，确保用户能听到提醒；
* 4. 异常兜底处理：捕获播放器初始化、资源加载的各类异常，打印日志不崩溃，保证页面稳定性；
* 5. 资源安全释放：弹窗关闭时立即停止播放并释放媒体播放器资源，杜绝内存泄漏与音频残留。
* 四、人性化交互设计【便捷操作，闭环提醒流程】
* 1. 弹窗内容极简清晰：标题为应用名称，内容为便签摘要，核心信息一目了然；
* 2. 按钮动态适配：亮屏时展示「确认」+「进入便签」双按钮，熄屏/锁屏时仅展示「确认」单按钮，贴合不同场景的用户操作习惯；
* 3. 精准交互逻辑：「确认」按钮仅关闭弹窗，「进入便签」按钮跳转至该便签的编辑页面，直接定位到对应内容，无需用户手动查找；
* 4. 弹窗关闭统一处理：无论点击按钮还是手动关闭弹窗，均触发统一的收尾逻辑，停止铃声并关闭页面，逻辑闭环无遗漏。
* 核心特性&关键技术要点：
* 1. 优先级保障：窗口标记配置为最高优先级，能穿透锁屏、熄屏界面展示，是安卓系统中「强提醒」的标准实现方式；
* 2. 资源安全：所有系统服务、媒体播放器资源均做了精准的创建与释放，无内存泄漏、无资源残留，符合安卓开发最佳实践；
* 3. 异常健壮：对数据解析、数据库查询、媒体播放等所有可能出现异常的环节均做了捕获处理，程序容错性极强，不会因单一异常导致崩溃；
* 4. 体验友好：所有逻辑均围绕「用户感知」设计，既保证提醒的强制性，又兼顾使用的人性化，无过度打扰、无无效操作；
* 5. 生命周期极简：页面的生命周期与弹窗强绑定，弹窗展示则页面存活，弹窗关闭则页面立即销毁，无后台残留，内存占用极低。
* 完整业务流程闭环（提醒功能最终链路）：
* AlarmManager触发广播 → AlarmReceiver接收广播 → 启动本页面 → 屏幕唤醒+解析便签数据 → 校验便签有效 → 播放铃声+展示弹窗 → 用户点击按钮 → 停止铃声+关闭弹窗 → 页面销毁 / 跳转便签编辑页。
* 核心业务约束：
* - 仅处理有效便签的提醒：便签已删除/类型非法时，直接关闭页面，不展示任何内容；
* - 严格遵循系统规则：铃声播放、屏幕唤醒均遵循安卓系统的安全与权限规则，无越权操作；
* - 页面无残留：弹窗关闭即页面销毁，无任何后台进程或服务残留，性能友好。
*/
public class AlarmAlertActivity extends Activity implements OnClickListener, OnDismissListener {
// 提醒所属便签的ID：从Intent的Data字段解析，标识当前提醒对应的便签
// ======================== 成员变量区 ========================
/** 当前提醒绑定的便签唯一ID，核心标识，所有数据操作均基于此ID */
private long mNoteId;
// 便签摘要文本：用于弹窗展示，最大长度限制为60字符
/** 便签的文本摘要内容，用于弹窗展示，做了长度限制处理 */
private String mSnippet;
// 便签摘要预览最大长度：超过该长度则裁剪并添加省略标记
/** 便签摘要预览的最大字符长度，超过该长度自动裁剪并添加省略号，保证展示美观 */
private static final int SNIPPET_PREW_MAX_LEN = 60;
// 媒体播放器：用于播放系统闹钟铃声，循环播放提醒音
/** 媒体播放器实例，用于加载和播放系统闹钟铃声，实现听觉提醒 */
MediaPlayer mPlayer;
/**
* 页面创建核心方法：初始化屏幕状态、解析便签ID、播放铃声、展示弹窗
* @param savedInstanceState 页面状态保存对象（此处未使用）
* 页面创建核心回调方法，页面生命周期的入口，承载所有初始化逻辑
* 本页面的所有核心功能均在该方法中完成初始化，逻辑清晰、步骤明确、无冗余处理
* @param savedInstanceState 页面状态保存对象，本页面未使用该参数
*/
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// 隐藏页面标题栏：仅展示对话框，无需原生标题栏
// 核心配置：隐藏原生的页面标题栏，本页面仅展示对话框，无需标题栏，极简展示
requestWindowFeature(Window.FEATURE_NO_TITLE);
// 1. 窗口显示控制：确保弹窗在锁屏/熄屏时可见
// ========== 第一步：窗口属性配置，实现锁屏显示、屏幕唤醒等核心能力 ==========
final Window win = getWindow();
// 添加标记：锁屏时仍显示窗口（基础可见性）
// 必加窗口标记：允许窗口在设备锁屏状态下依然显示，是锁屏提醒的基础配置
win.addFlags(WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED);
// 熄屏状态下：额外添加唤醒/常亮标记
// 智能判断屏幕状态：仅在熄屏时添加额外的唤醒与常亮标记，亮屏时不做修改
if (!isScreenOn()) {
win.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON // 保持屏幕常亮
| WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON // 唤醒屏幕
| WindowManager.LayoutParams.FLAG_ALLOW_LOCK_WHILE_SCREEN_ON // 允许屏幕锁定时显示
| WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR); // 适配装饰布局
win.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON); // 保持屏幕常亮，直到弹窗关闭
win.addFlags(WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON); // 强制唤醒熄屏的屏幕，核心保障用户能看到提醒
win.addFlags(WindowManager.LayoutParams.FLAG_ALLOW_LOCK_WHILE_SCREEN_ON);// 允许屏幕在亮屏状态下依然保持锁定，兼顾安全性
win.addFlags(WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR); // 适配系统的装饰布局，避免弹窗内容被遮挡
}
// 2. 解析Intent，获取提醒所属便签ID并查询摘要
// ========== 第二步：解析Intent数据，获取便签ID并查询摘要内容 ==========
Intent intent = getIntent();
try {
// 从Intent的Data字段解析便签ID（Data格式：content://notes/note/[id]）
// 核心解析逻辑：从Intent的Data字段中解析出便签ID，Data字段的格式为 content://notes/note/[id]
mNoteId = Long.valueOf(intent.getData().getPathSegments().get(1));
// 根据便签ID查询摘要文本
// 根据便签ID查询数据库，获取便签的文本摘要
mSnippet = DataUtils.getSnippetById(this.getContentResolver(), mNoteId);
// 摘要长度裁剪：超过60字符则截取前60位并添加省略标记
// 摘要内容规范化处理：超过60字符则截取前60位，并添加省略号，保证弹窗展示效果
mSnippet = mSnippet.length() > SNIPPET_PREW_MAX_LEN ? mSnippet.substring(0,
SNIPPET_PREW_MAX_LEN) + getResources().getString(R.string.notelist_string_info)
: mSnippet;
} catch (IllegalArgumentException e) {
// 解析ID失败（如格式错误）：打印异常并结束页面
// 异常处理：ID解析失败（如格式错误、数据异常），打印日志并直接返回，不展示任何内容
e.printStackTrace();
return;
}
// 3. 初始化媒体播放器，判断便签是否存在并执行后续逻辑
// ========== 第三步：初始化媒体播放器，校验便签有效性并执行核心逻辑 ==========
mPlayer = new MediaPlayer();
// 仅当便签仍存在于数据库中时，展示弹窗并播放铃声
// 关键校验：仅当该便签真实存在于数据库且为普通便签类型时，才展示弹窗和播放铃声
if (DataUtils.visibleInNoteDatabase(getContentResolver(), mNoteId, Notes.TYPE_NOTE)) {
showActionDialog(); // 展示提醒弹窗
playAlarmSound(); // 播放提醒铃声
showActionDialog(); // 展示提醒弹窗，核心交互载体
playAlarmSound(); // 播放系统闹钟铃声，核心听觉提醒
} else {
// 便签已删除：直接结束页面，不展示任何内容
// 便签已被删除或类型非法：直接关闭页面，无任何展示与播放，避免无效操作
finish();
}
}
/**
* 判断屏幕是否处于亮屏状态
* @return boolean：true=亮屏，false=熄屏/锁屏
* 私有工具方法：判断当前设备的屏幕是否处于亮屏状态
* @return boolean true=屏幕亮屏（解锁/未解锁但亮屏） false=屏幕熄屏/锁屏
*/
private boolean isScreenOn() {
// 获取电源管理系统服务
// 获取系统电源管理服务实例
PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
// 返回屏幕亮屏状态
// 返回当前屏幕的亮灭状态
return pm.isScreenOn();
}
/**
* 播放系统默认闹钟铃声
* 核心逻辑：
* - 获取系统默认闹钟铃声URI；
* - 适配系统静音模式，设置音频流类型；
* - 初始化媒体播放器，循环播放铃声。
* 核心功能方法：初始化并播放系统默认的闹钟铃声，实现听觉提醒
* 完整逻辑：获取系统铃声Uri → 适配系统静音模式 → 初始化播放器 → 循环播放 → 异常捕获，全链路健壮处理
*/
private void playAlarmSound() {
// 获取系统默认闹钟铃声的URI
// 第一步：获取系统默认的闹钟铃声Uri，使用系统级铃声资源，适配用户个性化设置
Uri url = RingtoneManager.getActualDefaultRingtoneUri(this, RingtoneManager.TYPE_ALARM);
// 获取系统静音模式配置：判断闹钟流是否受静音影响
// 第二步：读取系统铃声静音模式配置，判断闹钟音频流是否受静音规则影响，适配系统策略
int silentModeStreams = Settings.System.getInt(getContentResolver(),
Settings.System.MODE_RINGER_STREAMS_AFFECTED, 0);
// 设置音频流类型：适配静音模式
// 第三步：设置音频流类型，核心适配逻辑，保证铃声播放遵循系统音量规则
if ((silentModeStreams & (1 << AudioManager.STREAM_ALARM)) != 0) {
mPlayer.setAudioStreamType(silentModeStreams);
} else {
// 默认使用闹钟音频流（STREAM_ALARM），优先级高于普通媒体流
// 默认使用闹钟专属音频流，优先级高于普通媒体流，不会被媒体音量影响
mPlayer.setAudioStreamType(AudioManager.STREAM_ALARM);
}
// 初始化并启动媒体播放器
// 第四步：初始化媒体播放器并启动循环播放，捕获所有可能的异常，保证程序稳定
try {
mPlayer.setDataSource(this, url); // 设置铃声数据源
mPlayer.prepare(); // 准备播放器（同步）
mPlayer.setLooping(true); // 设置循环播放（持续提醒）
mPlayer.start(); // 启动播放
mPlayer.setDataSource(this, url); // 设置铃声资源的数据源
mPlayer.prepare(); // 同步准备播放器，加载铃声资源
mPlayer.setLooping(true); // 核心配置：循环播放铃声，直到用户手动关闭
mPlayer.start(); // 启动铃声播放，触发听觉提醒
} catch (IllegalArgumentException e) {
// 参数错误异常：打印堆栈，不中断流程
e.printStackTrace();
} catch (SecurityException e) {
// 权限异常（如铃声文件无访问权限）：打印堆栈
e.printStackTrace();
} catch (IllegalStateException e) {
// 播放器状态异常（如重复prepare）：打印堆栈
e.printStackTrace();
} catch (IOException e) {
// IO异常（如铃声文件不存在）：打印堆栈
e.printStackTrace();
}
}
/**
* 展示便签提醒弹窗
* 核心逻辑：
* - 标题为应用名称，内容为便签摘要；
* - 亮屏时显示“确认”+“进入便签”按钮，熄屏时仅显示“确认”按钮；
* - 绑定对话框关闭监听器，关闭时停止铃声并结束页面。
* 核心功能方法：创建并展示便签提醒的核心弹窗，是页面的核心展示载体
* 弹窗设计：标题为应用名，内容为便签摘要，按钮动态适配屏幕状态，绑定交互监听器，实现核心交互逻辑
*/
private void showActionDialog() {
AlertDialog.Builder dialog = new AlertDialog.Builder(this);
dialog.setTitle(R.string.app_name); // 弹窗标题：应用名称
dialog.setMessage(mSnippet); // 弹窗内容：便签摘要
dialog.setPositiveButton(R.string.notealert_ok, this); // 确认按钮
dialog.setTitle(R.string.app_name); // 弹窗标题：固定为应用名称，简洁明了
dialog.setMessage(mSnippet); // 弹窗核心内容：便签的文本摘要，展示提醒的核心信息
dialog.setPositiveButton(R.string.notealert_ok, this); // 确认按钮，绑定点击事件监听器
// 亮屏状态下：额外显示“进入便签”按钮（负向按钮）
// 智能按钮适配：仅在屏幕亮屏时展示「进入便签」按钮，熄屏/锁屏时不展示，贴合操作场景
if (isScreenOn()) {
dialog.setNegativeButton(R.string.notealert_enter, this);
}
// 展示弹窗并绑定关闭监听器
// 展示弹窗并绑定关闭监听器，无论何种方式关闭弹窗，均触发统一的收尾逻辑
dialog.show().setOnDismissListener(this);
}
/**
* 对话框按钮点击事件处理
* @param dialog 触发点击的对话框实例
* @param which 点击的按钮类型（BUTTON_POSITIVE/ NEGATIVE）
* 对话框按钮点击事件回调方法，实现弹窗的核心交互逻辑
* @param dialog 触发点击事件的对话框实例
* @param which 点击的按钮类型，区分「确认」和「进入便签」按钮
*/
public void onClick(DialogInterface dialog, int which) {
switch (which) {
case DialogInterface.BUTTON_NEGATIVE:
// “进入便签”按钮：跳转到便签编辑页，传递便签ID
// 点击「进入便签」按钮：跳转至该便签的编辑页面，精准定位到对应内容
Intent intent = new Intent(this, NoteEditActivity.class);
intent.setAction(Intent.ACTION_VIEW); // 设置动作：查看/编辑便签
intent.putExtra(Intent.EXTRA_UID, mNoteId); // 传递便签ID
intent.setAction(Intent.ACTION_VIEW); // 设置跳转动作：查看/编辑便签
intent.putExtra(Intent.EXTRA_UID, mNoteId); // 传递便签ID，目标页面根据ID查询并展示内容
startActivity(intent);
break;
default:
// “确认”按钮：无额外操作（对话框关闭由OnDismissListener处理）
// 点击「确认」按钮：无额外业务逻辑，仅关闭弹窗，收尾逻辑由OnDismissListener统一处理
break;
}
}
/**
* 对话框关闭事件处理：停止铃声，结束页面
* @param dialog 关闭的对话框实例
* 对话框关闭事件回调方法，页面的统一收尾逻辑入口
* 无论通过何种方式关闭弹窗（点击按钮、手动关闭），均执行该方法，保证逻辑闭环无遗漏
* @param dialog 被关闭的对话框实例
*/
public void onDismiss(DialogInterface dialog) {
stopAlarmSound(); // 停止提醒铃声，释放媒体资源
finish(); // 结束页面
stopAlarmSound(); // 核心收尾：停止铃声播放并释放媒体资源，杜绝内存泄漏与音频残留
finish(); // 关闭当前页面，释放所有资源，页面生命周期结束
}
/**
* 停止提醒铃声并释放媒体播放器资源
* 核心逻辑：停止播放、释放播放器，避免资源泄漏
* 私有工具方法：停止铃声播放并安全释放媒体播放器资源
* 核心作用：资源清理，是安卓媒体播放的强制规范，避免内存泄漏和音频通道占用
*/
private void stopAlarmSound() {
if (mPlayer != null) {
mPlayer.stop(); // 停止播放
mPlayer.release(); // 释放播放器资源
mPlayer = null; // 置空引用，便于GC回收
mPlayer.stop(); // 立即停止铃声播放
mPlayer.release(); // 释放播放器的所有资源，包括音频通道、内存等
mPlayer = null; // 置空引用，便于GC回收，彻底杜绝内存泄漏
}
}
}

126
src/Notes-master/src/net/micode/notes/ui/AlarmInitReceiver.java
Unescape View File

@ -14,100 +14,128 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，作为便签提醒的初始化广播接收器
// 包声明：归属小米便签UI模块，便签提醒功能的初始化核心广播接收器，负责重启恢复所有未过期提醒
package net.micode.notes.ui;
// 导入安卓闹钟管理类：用于注册/设置便签提醒闹钟
// 安卓系统闹钟服务核心类，用于注册、设置、取消定时闹钟，是便签提醒的核心调度组件
import android.app.AlarmManager;
// 导入安卓延迟意图类：封装广播Intent，供AlarmManager触发
// 安卓延迟意图核心类，封装广播/页面跳转意图，交由AlarmManager在指定时间触发，核心桥梁类
import android.app.PendingIntent;
// 导入安卓广播接收器核心类：接收初始化广播（如开机/应用启动）
// 安卓广播核心基类，继承此类实现广播监听与处理能力，为本类的核心父类
import android.content.BroadcastReceiver;
// 导入安卓ContentURI工具类：拼接便签ID到Intent的Data字段，标识提醒所属便签
// 安卓ContentURI拼接工具类，用于将Uri和数据ID拼接，生成唯一标识Uri，便于数据精准匹配
import android.content.ContentUris;
// 导入安卓上下文类：提供ContentResolver、系统服务等访问能力
// 安卓上下文核心类，提供系统服务获取、内容解析器访问、组件通信等基础能力
import android.content.Context;
// 导入安卓意图类：创建指向AlarmReceiver的广播意图
// 安卓意图核心类，组件间通信的核心载体，用于封装广播意图并携带数据
import android.content.Intent;
// 导入安卓数据库游标类：查询未过期的便签提醒数据
// 安卓数据库游标核心类，用于遍历查询数据库返回的结果集，读取便签提醒数据
import android.database.Cursor;
// 导入便签数据常量类：定义ContentURI、字段、便签类型等核心常量
// 便签应用核心数据常量类，定义数据库Uri、便签类型、字段名等全局常量，统一管理
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.NoteColumns;
/**
* 便签提醒初始化广播接收器
* 便签提醒初始化专属广播接收器【提醒恢复核心类】
* 继承：BroadcastReceiver 安卓系统广播接收器基类，具备监听并处理广播事件的核心能力
* 核心定位：小米便签「提醒功能」的保障类，解决「设备重启/应用进程被杀」后提醒丢失的核心问题，是便签提醒可靠性的关键支撑
* 核心设计意义：安卓系统的AlarmManager注册的闹钟，在设备重启后会全部失效，应用进程被系统回收后也可能丢失未触发的闹钟，本类就是为了解决该问题，实现提醒的持久化保障
* 核心职责：
* 1. 接收系统/应用的初始化广播（如设备开机、应用重启），重新初始化所有未过期的便签提醒；
* 2. 查询数据库中所有“提醒时间未过期”的普通便签，将其重新注册到AlarmManager；
* 3. 确保设备重启/应用重启后，未过期的便签提醒不会丢失，仍能按时触发；
* 关键说明：
* - 仅处理普通便签（TYPE_NOTE）的提醒，排除文件夹/系统项；
* - 使用AlarmManager.RTC_WAKEUP类型，确保提醒触发时唤醒设备，避免漏提醒。
* 1. 监听系统/应用的初始化类广播，包含「设备开机完成广播、应用启动广播、系统刷新广播」等核心触发时机；
* 2. 接收到广播后，通过ContentResolver查询便签数据库中所有符合条件的有效提醒数据；
* 3. 精准筛选：仅查询「提醒时间戳大于当前时间（未过期）」+「便签类型为普通便签TYPE_NOTE」的记录，排除文件夹/系统项/已过期提醒，无无效处理；
* 4. 遍历有效提醒数据，为每一条记录重新创建广播意图与延迟意图，通过AlarmManager完成闹钟的重新注册；
* 5. 保证所有未过期的便签提醒，在设备重启/应用重启后都能恢复如初，按时触发，无任何遗漏。
* 核心特性&关键技术要点：
* 1. 精准数据筛选：查询条件双重过滤，既保证时效性（未过期），又保证数据合法性（普通便签），避免无效数据处理，降低性能损耗；
* 2. 轻量查询设计：自定义投影数组仅查询「便签ID、提醒时间戳」两个核心字段，不查询冗余内容，减少数据库IO开销与内存占用；
* 3. 唯一标识绑定：通过ContentUris拼接便签ID到Intent的Data字段，为每个提醒生成唯一的意图标识，精准绑定提醒与对应便签，无串号风险；
* 4. 强力唤醒保障：使用AlarmManager.RTC_WAKEUP闹钟类型，基于系统绝对时间，触发时会强制唤醒休眠的设备（亮屏/唤醒CPU），确保提醒必达，不会因设备休眠漏提醒；
* 5. 资源安全释放：查询数据库后及时关闭Cursor游标，释放数据库连接与内存资源，杜绝内存泄漏风险，符合安卓开发最佳实践；
* 6. 无状态极简设计：本类无成员变量、无复杂逻辑、无内存占用，仅在广播触发时执行一次性初始化逻辑，执行完成后立即释放资源，性能友好。
* 核心业务约束：
* - 不处理已过期的提醒：提醒时间小于当前时间的记录直接过滤，无需注册，避免无效操作；
* - 不处理非普通便签：仅对TYPE_NOTE类型生效，文件夹（TYPE_FOLDER）等无提醒功能的类型直接排除；
* - 不处理无提醒的便签：仅查询ALERTED_DATE字段大于0的记录，无提醒的便签不会进入查询结果。
* 完整业务闭环：
* 便签设置提醒 → AlarmManager注册闹钟 → 设备重启/应用重启 → 本接收器接收初始化广播 → 查询数据库有效提醒 → 重新注册所有闹钟 → 提醒时间到达 → AlarmReceiver触发 → 展示提醒弹窗。
*/
public class AlarmInitReceiver extends BroadcastReceiver {
/**
* 数据库查询投影数组：仅查询核心字段，减少IO开销
* 字段说明：
* - NoteColumns.ID：便签唯一ID（用于标识提醒所属便签）；
* - NoteColumns.ALERTED_DATE：便签的提醒时间戳（>0表示有提醒）。
* 数据库查询投影数组【按需查询，性能优化】
* 设计目的：指定本次数据库查询仅需要返回的字段，不查询冗余字段，减少数据库IO传输数据量，降低内存消耗，提升查询效率
* 字段说明：仅包含两个核心必要字段，满足业务需求的最小化查询
*/
private static final String [] PROJECTION = new String [] {
NoteColumns.ID, // 0: 便签ID
NoteColumns.ALERTED_DATE // 1: 提醒时间戳
NoteColumns.ID, // 数组索引0：便签的唯一主键ID，用于绑定提醒与便签、生成唯一Intent标识
NoteColumns.ALERTED_DATE // 数组索引1：便签设置的提醒时间戳，毫秒级，用于设置闹钟的触发时间
};
// 投影数组对应的列索引常量：简化Cursor取值，避免硬编码索引
private static final int COLUMN_ID = 0; // 便签ID列索引
private static final int COLUMN_ALERTED_DATE = 1; // 提醒时间戳列索引
// 投影数组列索引常量【硬编码优化】
// 设计目的：将数组索引封装为常量，替代代码中的硬编码数字，提升代码可读性、可维护性，避免索引写错导致的程序异常
private static final int COLUMN_ID = 0; // 对应PROJECTION[0]，便签ID列索引
private static final int COLUMN_ALERTED_DATE = 1; // 对应PROJECTION[1]，提醒时间戳列索引
/**
* 广播接收核心方法：初始化未过期的便签提醒，重新注册到AlarmManager
* @param context 广播接收器上下文：用于访问ContentResolver、系统服务
* @param intent 触发广播的Intent（如开机完成广播、应用启动广播）
* 广播接收核心回调方法，广播触发时由安卓系统自动调用
* 本类的唯一核心方法，承载了「查询有效提醒+重新注册闹钟」的全部核心逻辑，逻辑清晰、步骤明确、无冗余处理
* @param context 广播接收器的运行上下文对象，不可为空，核心作用：获取ContentResolver查询数据库、获取AlarmManager系统服务、创建Intent意图
* @param intent 触发本次广播的意图对象，携带广播的触发类型信息，本类无需解析该意图内容，仅做触发执行
*/
@Override
public void onReceive(Context context, Intent intent) {
// 1. 获取当前时间戳：作为筛选“未过期提醒”的阈值（仅处理提醒时间>当前时间的便签）
// 第一步：获取当前系统时间戳，作为筛选「未过期提醒」的核心阈值，只处理提醒时间在当前时间之后的记录
long currentDate = System.currentTimeMillis();
// 2. 查询ContentResolver，获取所有未过期的普通便签提醒
// 查询条件：提醒时间>当前时间 + 便签类型为普通便签（TYPE_NOTE）
// 第二步：通过ContentResolver查询便签数据库，获取所有符合条件的有效提醒数据
// 核心查询参数说明：
// 1. uri：查询地址 → Notes.CONTENT_NOTE_URI 普通便签的专属Uri，精准定位查询表
// 2. projection：查询字段 → 自定义的PROJECTION数组，仅查ID和提醒时间戳
// 3. selection：查询条件 → 双重过滤：提醒时间>当前时间 且 便签类型为普通便签，精准筛选有效数据
// 4. selectionArgs：条件参数 → 传入当前时间戳的字符串形式，防止SQL注入，符合安卓安全规范
// 5. sortOrder：排序规则 → null，使用数据库默认排序，无需额外排序，提升查询效率
Cursor c = context.getContentResolver().query(Notes.CONTENT_NOTE_URI,
PROJECTION, // 要查询的字段
NoteColumns.ALERTED_DATE + ">? AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE, // 查询条件
new String[] { String.valueOf(currentDate) }, // 条件参数（当前时间戳）
null); // 排序规则（默认）
PROJECTION,
NoteColumns.ALERTED_DATE + ">? AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE,
new String[] { String.valueOf(currentDate) },
null);
// 3. 遍历Cursor，为每个未过期的提醒注册闹钟
if (c != null) {
// 游标移动到第一条数据（有未过期提醒时进入循环）
// 第三步：遍历查询结果，为每个有效提醒重新注册闹钟
if (c != null) { // 游标非空校验：避免查询结果为空时的空指针异常，代码健壮性保障
// 游标移动到第一条数据，存在有效提醒时进入循环遍历逻辑
if (c.moveToFirst()) {
do {
// 3.1 获取当前便签的提醒时间戳和ID
long alertDate = c.getLong(COLUMN_ALERTED_DATE); // 提醒触发时间
long noteId = c.getLong(COLUMN_ID); // 便签唯一ID
// 3.1 从游标中读取当前行的核心数据：便签ID、提醒触发时间戳
long alertDate = c.getLong(COLUMN_ALERTED_DATE); // 该便签的提醒触发时间，毫秒级
long noteId = c.getLong(COLUMN_ID); // 该便签的唯一主键ID
// 3.2 创建广播Intent：指向AlarmReceiver（提醒触发时的处理接收器）
// 3.2 创建广播意图：指定意图的目标为AlarmReceiver，即提醒时间到达时，需要触发的广播接收器
Intent sender = new Intent(context, AlarmReceiver.class);
// 将便签ID附加到Intent的Data字段：标识该提醒所属的便签，便于AlarmReceiver识别
// 核心关键：将便签ID拼接至Intent的Data字段，生成唯一的Uri标识，精准绑定该提醒与对应便签
// 作用：AlarmReceiver接收到广播时，可通过该Uri解析出便签ID，进而查询便签详情展示提醒内容，无串号风险
sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId));
// 3.3 创建PendingIntent：封装广播Intent，供AlarmManager触发
// 参数说明：context=上下文，requestCode=请求码（此处为0），intent=广播意图，flags=标记（默认）
// 3.3 创建PendingIntent延迟意图：封装上述广播意图，交由AlarmManager管理，在指定时间触发广播
// PendingIntent.getBroadcast参数说明：上下文、请求码(此处传0即可)、待封装的广播意图、flags标记(默认0)
// 核心作用：PendingIntent是一种授权意图，允许系统在未来的指定时间，以当前应用的身份发送该广播，是闹钟触发的核心载体
PendingIntent pendingIntent = PendingIntent.getBroadcast(context, 0, sender, 0);
// 3.4 获取AlarmManager系统服务，注册提醒闹钟
// 3.4 获取系统AlarmManager服务实例，系统级的闹钟调度核心服务
AlarmManager alermManager = (AlarmManager) context
.getSystemService(Context.ALARM_SERVICE);
// 设置闹钟：RTC_WAKEUP（基于系统时间，触发时唤醒设备）、提醒时间、PendingIntent
// 3.5 核心操作：重新注册闹钟，完成提醒恢复
// alermManager.set参数说明：
// 1. type → AlarmManager.RTC_WAKEUP 最核心的闹钟类型，基于系统绝对时间，触发时唤醒设备CPU/屏幕，保证提醒必达
// 2. triggerAtTime → 闹钟触发的具体时间，即从数据库读取的提醒时间戳alertDate
// 3. operation → 待触发的PendingIntent延迟意图，触发时发送广播至AlarmReceiver
alermManager.set(AlarmManager.RTC_WAKEUP, alertDate, pendingIntent);
} while (c.moveToNext()); // 遍历所有未过期的提醒
} while (c.moveToNext()); // 循环遍历游标，处理所有有效提醒数据
}
// 4. 关闭Cursor：释放数据库资源，避免内存泄漏
// 第四步：必须关闭游标，释放数据库资源与内存，杜绝内存泄漏，安卓数据库操作的强制规范
c.close();
}
}

44
src/Notes-master/src/net/micode/notes/ui/AlarmReceiver.java
Unescape View File

@ -14,38 +14,50 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，作为便签提醒功能的核心广播接收器
// 包声明：归属小米便签UI模块，便签提醒功能的广播接收核心类，承接闹钟触发逻辑
package net.micode.notes.ui;
// 导入安卓广播接收器核心类：接收系统/应用发送的广播事件
// 安卓广播核心基类，继承此类实现广播接收能力，监听系统/应用发送的广播事件
import android.content.BroadcastReceiver;
// 导入安卓上下文类：提供应用运行环境（启动Activity）
// 安卓上下文核心类，提供应用运行环境、组件启动、资源访问等基础能力
import android.content.Context;
// 导入安卓意图类：用于启动提醒页面，传递数据
// 安卓意图核心类，用于组件间通信、页面跳转、数据传递的核心载体
import android.content.Intent;
/**
* 便签提醒广播接收器
* 便签提醒功能专属广播接收器【轻量级广播处理类】
* 继承：BroadcastReceiver 安卓系统广播接收器基类，具备监听并处理广播的核心能力
* 核心定位：小米便签「提醒功能」的核心中转类，是闹钟触发与提醒弹窗展示的唯一桥梁，无任何业务逻辑，只做事件转发
* 核心职责：
* 1. 接收便签设置的提醒闹钟广播（由AlarmManager发送）；
* 2. 接收到广播后，启动提醒弹窗页面（AlarmAlertActivity），展示便签提醒内容；
* 关键说明：
* - 广播接收器中启动Activity必须添加FLAG_ACTIVITY_NEW_TASK标记（无任务栈上下文）；
* 典型使用场景：便签设置的提醒时间到达时，触发该接收器，弹出提醒窗口。
* 1. 监听由系统AlarmManager定时发送的闹钟广播，该广播在用户设置的便签提醒时间到达时触发；
* 2. 接收到广播后，无缝承接Intent中携带的便签提醒数据（便签ID、标题、内容等）；
* 3. 对Intent做标准化配置，指定跳转目标页面并补充必要的启动标记；
* 4. 启动便签提醒弹窗页面，完成提醒事件的最终展示，触发用户感知。
* 核心特性&关键注意点：
* 1. 无状态设计：该类无任何成员变量、无初始化逻辑、无复杂处理，是纯功能性的极简类，内存占用极低；
* 2. 必加启动标记：BroadcastReceiver 属于四大组件之一，运行时无独立的Activity任务栈上下文，启动Activity时必须添加 FLAG_ACTIVITY_NEW_TASK 标记，否则会抛出运行时异常，这是安卓的硬性规范；
* 3. 数据透传：广播携带的所有Intent数据会完整透传给目标页面，无任何数据丢失或修改，保证提醒内容的正确性；
* 4. 生命周期极简：广播接收器的onReceive方法执行时间被系统严格限制，本类逻辑极致轻量化，可在瞬时完成执行，无超时风险；
* 5. 唯一触发源：该接收器只响应便签应用自身注册的闹钟广播，不接收其他任何广播事件，功能单一无干扰。
* 典型业务流程闭环：
* 便签编辑页设置提醒时间 → 后台通过AlarmManager注册定时闹钟 → 提醒时间到达，系统发送广播 → 本接收器接收广播 → 启动AlarmAlertActivity → 展示便签提醒弹窗，响铃/震动提醒用户。
* 典型使用场景：唯一用途就是接收便签的提醒广播，无其他任何业务场景。
*/
public class AlarmReceiver extends BroadcastReceiver {
/**
* 广播接收核心方法：处理提醒广播，启动提醒页面
* @param context 广播接收器的上下文：用于启动Activity（需添加新任务标记）
* @param intent 触发广播的Intent：携带提醒相关数据（如便签ID、内容等）
* 广播接收核心回调方法，广播触发时系统自动调用该方法
* 该方法是本类的唯一核心方法，承载了所有的广播处理逻辑，极简且高效
* @param context 广播接收器的运行上下文对象，不可为空，用于启动目标Activity组件
* @param intent 触发本次广播的意图对象，内部携带了完整的便签提醒数据，也是页面跳转的核心数据载体
*/
@Override
public void onReceive(Context context, Intent intent) {
// 1. 修改Intent的目标类为提醒弹窗页面（AlarmAlertActivity）
// 第一步：为当前Intent指定跳转的目标页面，将广播意图转为页面跳转意图
intent.setClass(context, AlarmAlertActivity.class);
// 2. 添加新任务标记：BroadcastReceiver无Activity任务栈，必须添加该标记才能启动Activity
// 第二步：添加必选的新任务启动标记，解决广播无任务栈启动Activity的上下文问题，规避运行时异常
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
// 3. 启动提醒弹窗页面，展示便签提醒内容
// 第三步：启动提醒弹窗页面，完成广播事件的最终转发，展示便签提醒内容
context.startActivity(intent);
}
}

517
src/Notes-master/src/net/micode/notes/ui/DateTimePicker.java
Unescape View File

@ -14,157 +14,176 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，自定义日期时间选择控件核心类
// 包声明：归属小米便签UI模块，日期时间选择的核心自定义复合控件，供弹窗调用
package net.micode.notes.ui;
// 导入日期格式化工具类：处理星期/日期的文本展示
// Java文本格式化工具类，获取系统的上午/下午文本标识，适配多语言环境
import java.text.DateFormatSymbols;
// 导入日历类：核心的日期时间管理，处理年/月/日/时/分的计算与联动
// Java核心日历工具类，全局唯一的时间数据载体，处理所有年月日时分的计算、联动、转换逻辑
import java.util.Calendar;
// 导入资源类：引用布局文件（datetime_picker.xml）
// 小米便签资源文件引用，获取布局、字符串等资源ID常量
import net.micode.notes.R;
// 导入安卓上下文类：创建控件、加载资源
// 安卓系统核心类 - 上下文，提供控件创建、资源加载、布局填充的运行环境
import android.content.Context;
// 导入日期格式化工具：判断系统24小时制设置
// 安卓系统日期格式化工具类，提供系统24小时制判断、日期文本格式化能力
import android.text.format.DateFormat;
// 导入视图相关类：布局容器、视图可见性控制
// 安卓视图体系核心类，视图基础属性配置、可见性控制、布局容器核心父类
import android.view.View;
import android.widget.FrameLayout;
// 导入数字选择器：核心的日期/时间选择UI组件
// 安卓数字滚轮选择器，本控件的核心子组件，实现年月日时分的滚轮滑动选择UI
import android.widget.NumberPicker;
/**
* 自定义日期时间选择控件
* 核心特性：
* 1. 布局组成：集成日期（近7天）、小时、分钟、上午/下午（AM/PM）四个NumberPicker；
* 2. 时间联动：处理时间选择的边界联动（如分钟59→0时小时+1、小时23→0时日期+1）；
* 3. 制式适配：支持24小时制/12小时制切换，自动适配系统默认设置；
* 4. 回调通知：时间选择变化时触发回调，传递最新的年/月/日/时/分；
* 5. 状态控制：支持整体启用/禁用所有选择器，统一管理交互状态；
* 典型使用场景：便签提醒时间设置的DateTimePickerDialog中作为核心选择UI。
* 自定义日期时间复合选择控件【核心基础UI控件】
* 继承：FrameLayout 帧布局，作为复合控件的根布局容器，承载多个子选择器
* 核心定位：小米便签「提醒时间设置」功能的底层核心控件，被DateTimePickerDialog弹窗集成使用
* 核心设计理念：将「日期选择+小时选择+分钟选择+上下午选择」整合为统一控件，封装所有时间联动逻辑、格式适配逻辑、数据处理逻辑，对外提供极简的调用与通信接口
* 核心特性与职责：
* 1. 布局整合：内置日期、小时、分钟、上下午共4个NumberPicker滚轮选择器，形成一体化的时间选择UI；
* 2. 数据闭环：基于Calendar类做全局唯一的时间数据管理，所有选择操作最终同步至该对象，保证数据一致性；
* 3. 智能联动：完美处理所有时间边界联动场景，如分钟59→0时小时+1、小时23→0时日期+1、12小时制跨上下午切换等，无数据断层；
* 4. 系统适配：自动识别并适配系统的24小时制/12小时制设置，支持手动强制切换，两种制式无缝兼容，交互无感知；
* 5. 日期展示：固定展示近7天的日期列表，格式为「月.日 星期」，满足便签短周期提醒的业务需求；
* 6. 状态统一：支持控件整体启用/禁用，一键同步所有子选择器的交互状态，无需单独配置；
* 7. 标准化通信：提供时间变化的回调接口，选择操作实时触发回调，向外传递标准化的年月日时分数据；
* 8. 细节优化：分钟选择器支持长按快速滚动、上下午文本适配系统多语言、时间数值边界校验等细节体验优化；
* 9. 防抖动处理：初始化阶段屏蔽回调触发，避免初始化时的无效数据通知，提升性能与稳定性。
* 核心优势：控件内聚性极强，所有时间相关的逻辑全部封装内部，外部调用方只需关心「设置初始时间」「获取选中时间」「监听时间变化」三个核心操作，完全无需处理内部复杂逻辑。
* 典型业务场景：唯一使用场景为DateTimePickerDialog弹窗的核心内容视图，支撑便签的提醒时间选择功能。
*/
public class DateTimePicker extends FrameLayout {
// ======================== 基础常量 - 控件默认状态 ========================
/** 控件默认启用状态：初始为启用 */
// ======================== 基础常量区 - 控件默认配置与固定数值 ========================
/** 控件默认启用状态：初始化时默认所有选择器均可交互 */
private static final boolean DEFAULT_ENABLE_STATE = true;
// ======================== 常量 - 时间数值范围 ========================
/** 半天的小时数：12小时制的核心数值（AM/PM分界） */
// ======================== 常量区 - 时间单位核心数值 ========================
/** 半天小时数：12小时制的核心分界值，上午/下午的小时数上限 */
private static final int HOURS_IN_HALF_DAY = 12;
/** 全天的小时数：24小时制的核心数值 */
/** 全天小时数：24小时制的核心数值，一天的总小时数 */
private static final int HOURS_IN_ALL_DAY = 24;
/** 一周的天数：日期选择器展示近7天 */
/** 一周天数：日期选择器固定展示的天数，不可修改，适配短周期提醒业务 */
private static final int DAYS_IN_ALL_WEEK = 7;
// ======================== 常量 - NumberPicker取值范围 ========================
/** 日期选择器最小值：0（对应近7天的起始索引） */
// ======================== 常量区 - NumberPicker滚轮选择器 取值范围约束 ========================
/** 日期选择器-最小值：固定为0，对应近7天列表的第一条数据 */
private static final int DATE_SPINNER_MIN_VAL = 0;
/** 日期选择器最大值：6（对应近7天的结束索引，DAYS_IN_ALL_WEEK - 1） */
/** 日期选择器-最大值：固定为6，对应近7天列表的最后一条数据，数值等于天数减1 */
private static final int DATE_SPINNER_MAX_VAL = DAYS_IN_ALL_WEEK - 1;
/** 24小时制-小时选择器最小值：0（凌晨0点） */
/** 24小时制-小时选择器-最小值：凌晨0点，时间起点 */
private static final int HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW = 0;
/** 24小时制-小时选择器最大值：23（深夜23点） */
/** 24小时制-小时选择器-最大值：深夜23点，时间终点 */
private static final int HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW = 23;
/** 12小时制-小时选择器最小值：1（上午/下午1点） */
/** 12小时制-小时选择器-最小值：上午/下午的1点，无0点概念 */
private static final int HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW = 1;
/** 12小时制-小时选择器最大值：12（上午/下午12点） */
/** 12小时制-小时选择器-最大值：上午/下午的12点，封顶数值 */
private static final int HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW = 12;
/** 分钟选择器最小值：0（整点） */
/** 分钟选择器-最小值：整点0分，分钟起点 */
private static final int MINUT_SPINNER_MIN_VAL = 0;
/** 分钟选择器最大值：59（整点前1分钟） */
/** 分钟选择器-最大值：整点前1分钟，59分，分钟终点 */
private static final int MINUT_SPINNER_MAX_VAL = 59;
/** 上午/下午选择器最小值：0（AM/上午） */
/** 上下午选择器-最小值：0，对应上午/AM */
private static final int AMPM_SPINNER_MIN_VAL = 0;
/** 上午/下午选择器最大值：1（PM/下午） */
/** 上下午选择器-最大值：1，对应下午/PM */
private static final int AMPM_SPINNER_MAX_VAL = 1;
// ======================== 成员变量 - UI组件 ========================
/** 日期选择器：展示近7天的日期（格式如“12.23 星期二”） */
// ======================== 成员变量区 - UI核心组件【所有子选择器，全局持用避免重复查找】 ========================
/** 日期滚轮选择器：核心展示近7天的格式化日期文本，如「01.15 周四」，支持滑动切换日期 */
private final NumberPicker mDateSpinner;
/** 小时选择器：根据24/12小时制展示不同范围的小时数 */
/** 小时滚轮选择器：根据24/12小时制展示对应范围的小时数，核心时间选择组件 */
private final NumberPicker mHourSpinner;
/** 分钟选择器：0~59的分钟数选择 */
/** 分钟滚轮选择器：固定0~59的分钟数选择，支持长按快速滚动，核心时间选择组件 */
private final NumberPicker mMinuteSpinner;
/** 上午/下午选择器：仅12小时制显示，0=AM/上午，1=PM/下午 */
/** 上下午滚轮选择器：仅12小时制显示，0=上午/AM，1=下午/PM，适配12小时制的时间展示 */
private final NumberPicker mAmPmSpinner;
// ======================== 成员变量 - 日期时间状态 ========================
/** 核心日历对象：存储当前选中的日期时间，处理所有时间计算/联动 */
// ======================== 成员变量区 - 核心状态与数据载体【全局核心数据，控件的大脑】 ========================
/** 核心日历对象：全局唯一的时间数据载体，存储当前选中的完整年月日时分信息，所有选择操作最终同步至此，所有外部获取操作均来源于此，保证数据唯一可信 */
private Calendar mDate;
/** 日期选择器展示文本数组：存储近7天的格式化日期文本（如“12.23 星期二”） */
/** 日期展示文本数组：缓存近7天的格式化日期文本，供日期选择器展示使用，避免重复计算 */
private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK];
/** 上午/下午标记：true=AM/上午，false=PM/下午（仅12小时制有效） */
/** 上下午状态标记：true=上午/AM，false=下午/PM，仅在12小时制下生效，控制时间计算与展示 */
private boolean mIsAm;
/** 24小时制标记：true=24小时制，false=12小时制 */
/** 24小时制状态标记：true=启用24小时制，隐藏上下午选择器；false=启用12小时制，显示上下午选择器 */
private boolean mIs24HourView;
/** 控件启用状态：true=启用，false=禁用所有选择器 */
/** 控件整体启用状态标记：true=所有选择器可交互，false=所有选择器禁用，统一管控交互权限 */
private boolean mIsEnabled = DEFAULT_ENABLE_STATE;
/** 初始化标记：true=控件正在初始化，避免初始化时触发不必要的回调 */
/** 初始化状态标记：true=控件正在初始化，屏蔽所有回调触发；false=初始化完成，正常响应所有操作与回调，防止初始化阶段的无效数据通知 */
private boolean mInitialising;
// ======================== 成员变量 - 回调监听 ========================
/** 日期时间变化回调监听器：外部实现，接收时间变化通知 */
// ======================== 成员变量区 - 回调通信接口 ========================
/** 日期时间变化的回调监听器：外部实现该接口，接收控件的时间变化通知，是控件与外部通信的唯一桥梁 */
private OnDateTimeChangedListener mOnDateTimeChangedListener;
// ======================== 成员变量 - NumberPicker值变化监听器 ========================
/** 日期选择器值变化监听器：处理日期切换，更新日历对象并触发回调 */
// ======================== 成员变量区 - 滚轮选择器 值变化监听器【所有选择器的核心交互逻辑，内部闭环】 ========================
/**
* 日期选择器 值变化监听器：处理日期滑动切换的核心逻辑
* 核心能力：监听日期选择器的数值变化，计算日期偏移量，同步更新核心日历对象的日期，刷新日期展示文本，最终触发时间变化回调
* 无边界特殊处理：日期选择器固定展示近7天，滑动仅在7天内切换，无需处理跨月跨年的复杂逻辑
*/
private NumberPicker.OnValueChangeListener mOnDateChangedListener = new NumberPicker.OnValueChangeListener() {
@Override
public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
// 调整日历的天数（新值-旧值为天数偏移量）
// 计算日期偏移量：新值-旧值 即为需要增减的天数，直接同步至核心日历对象
mDate.add(Calendar.DAY_OF_YEAR, newVal - oldVal);
// 更新日期选择器的展示文本
// 刷新日期选择器的展示文本，保证文本与选中日期一致
updateDateControl();
// 触发日期时间变化回调
// 触发全局时间变化回调，向外通知日期已更新
onDateTimeChanged();
}
};
/** 小时选择器值变化监听器：处理小时切换，包含边界联动（小时→日期）和12/24小时制适配 */
/**
* 小时选择器 值变化监听器：处理小时滑动切换的核心逻辑【最复杂的联动逻辑】
* 核心能力：兼容24/12小时制的小时选择，处理所有小时边界的联动场景，包含「小时→日期」「小时→上下午」的双层联动，同步更新核心日历对象
* 核心处理场景：
* 1. 12小时制：下午11点→12点 → 日期+1；上午12点→11点 → 日期-1；小时11↔12时自动切换上下午状态；
* 2. 24小时制：23点→0点 → 日期+1；0点→23点 → 日期-1；无上下切换逻辑；
* 3. 所有场景下，最终将选中的小时数适配转换为24小时制，同步至核心日历对象，保证数据统一。
*/
private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() {
@Override
public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
boolean isDateChanged = false; // 日期是否变化标记
Calendar cal = Calendar.getInstance();
boolean isDateChanged = false; // 日期是否发生变化的标记位，默认无变化
Calendar cal = Calendar.getInstance(); // 临时日历对象，用于处理日期偏移
// 12小时制下的小时边界处理
// ========== 12小时制 小时边界特殊处理 ==========
if (!mIs24HourView) {
// 场景1：下午11点→12点 → 日期+1
// 场景1：下午状态下，小时从11→12，触发日期+1（跨天）
if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) {
cal.setTimeInMillis(mDate.getTimeInMillis());
cal.add(Calendar.DAY_OF_YEAR, 1);
isDateChanged = true;
}
// 场景2：上午12点→11点 → 日期-1
// 场景2：上午状态下，小时从12→11，触发日期-1（跨天）
else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
cal.setTimeInMillis(mDate.getTimeInMillis());
cal.add(Calendar.DAY_OF_YEAR, -1);
isDateChanged = true;
}
// 小时11→12 或 12→11 时，切换上午/下午标记
// 场景3：小时在11和12之间切换时，自动翻转上下午状态（核心联动逻辑）
if (oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY ||
oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
mIsAm = !mIsAm;
updateAmPmControl(); // 更新上午/下午选择器
updateAmPmControl(); // 同步刷新上下午选择器的选中状态
}
}
// 24小时制下的小时边界处理
// ========== 24小时制 小时边界特殊处理 ==========
else {
// 场景1：23点→0点 → 日期+1
// 场景1：小时从23→0，触发日期+1（跨天，一天的结束）
if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) {
cal.setTimeInMillis(mDate.getTimeInMillis());
cal.add(Calendar.DAY_OF_YEAR, 1);
isDateChanged = true;
}
// 场景2：0点→23点 → 日期-1
// 场景2：小时从0→23，触发日期-1（跨天，一天的开始）
else if (oldVal == 0 && newVal == HOURS_IN_ALL_DAY - 1) {
cal.setTimeInMillis(mDate.getTimeInMillis());
cal.add(Calendar.DAY_OF_YEAR, -1);
@ -172,13 +191,13 @@ public class DateTimePicker extends FrameLayout {
}
}
// 计算并设置最终的小时数（适配12/24小时制）
// ========== 统一处理：将选中的小时数转换为24小时制，同步至核心日历对象 ==========
int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY);
mDate.set(Calendar.HOUR_OF_DAY, newHour);
// 触发时间变化回调
// 触发全局时间变化回调，向外通知小时已更新
onDateTimeChanged();
// 日期变化时，更新日历的年/月/日
// ========== 日期发生变化时，同步更新核心日历对象的年月日 ==========
if (isDateChanged) {
setCurrentYear(cal.get(Calendar.YEAR));
setCurrentMonth(cal.get(Calendar.MONTH));
@ -187,218 +206,232 @@ public class DateTimePicker extends FrameLayout {
}
};
/** 分钟选择器值变化监听器：处理分钟切换，包含边界联动（分钟→小时→日期） */
/**
* 分钟选择器 值变化监听器：处理分钟滑动切换的核心逻辑【分钟→小时→日期 三层联动】
* 核心能力：监听分钟选择器的数值变化，处理分钟的边界联动场景，是最基础也是最核心的时间联动逻辑
* 核心处理场景：分钟从59→0 触发小时+1；分钟从0→59 触发小时-1；小时变化后可能触发日期变化，自动联动处理
* 附加能力：小时变化后，自动同步更新上下午状态与选择器，保证12小时制的展示一致性
*/
private NumberPicker.OnValueChangeListener mOnMinuteChangedListener = new NumberPicker.OnValueChangeListener() {
@Override
public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
int minValue = mMinuteSpinner.getMinValue();
int maxValue = mMinuteSpinner.getMaxValue();
int offset = 0; // 小时偏移量
int offset = 0; // 小时偏移量，默认无偏移
// 场景1：59分→0分 → 小时+1
// 场景1：分钟从59→0，触发小时+1（分钟到顶，进位到小时）
if (oldVal == maxValue && newVal == minValue) {
offset += 1;
}
// 场景2：0分→59分 → 小时-1
// 场景2：分钟从0→59，触发小时-1（分钟到底，退位到小时）
else if (oldVal == minValue && newVal == maxValue) {
offset -= 1;
}
// 小时需要偏移时，调整日历并更新相关选择器
// ========== 小时需要偏移时，执行联动逻辑 ==========
if (offset != 0) {
mDate.add(Calendar.HOUR_OF_DAY, offset); // 调整小时
mHourSpinner.setValue(getCurrentHour()); // 更新小时选择器
updateDateControl(); // 更新日期选择器（小时偏移可能导致日期变化）
mDate.add(Calendar.HOUR_OF_DAY, offset); // 同步更新核心日历对象的小时数
mHourSpinner.setValue(getCurrentHour()); // 刷新小时选择器的选中值
updateDateControl(); // 刷新日期选择器，小时偏移可能导致日期变化
// 根据新小时数更新上午/下午标记
// 根据新的小时数，更新上下午状态标记
int newHour = getCurrentHourOfDay();
if (newHour >= HOURS_IN_HALF_DAY) {
mIsAm = false;
} else {
mIsAm = true;
}
updateAmPmControl(); // 更新上午/下午选择器
mIsAm = newHour < HOURS_IN_HALF_DAY;
updateAmPmControl(); // 同步刷新上下午选择器的选中状态
}
// 设置最终的分钟数
// ========== 统一处理：将选中的分钟数同步至核心日历对象 ==========
mDate.set(Calendar.MINUTE, newVal);
// 触发时间变化回调
// 触发全局时间变化回调，向外通知分钟已更新
onDateTimeChanged();
}
};
/** 上午/下午选择器值变化监听器：切换上午/下午，调整小时数（±12小时） */
/**
* 上下午选择器 值变化监听器：处理上下午切换的核心逻辑【仅12小时制生效】
* 核心能力：监听上下午选择器的切换操作，翻转上下午状态标记，同步调整核心日历对象的小时数（±12小时）
* 核心逻辑：上午→下午，小时+12；下午→上午，小时-12，保证时间数值的正确性，无数据误差
*/
private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() {
@Override
public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
// 切换上午/下午标记
// 翻转上下午状态标记
mIsAm = !mIsAm;
// 调整小时数：上午→下午 +12小时，下午→上午 -12小时
// 根据新状态，调整核心日历对象的小时数，保证时间正确
if (mIsAm) {
mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY);
} else {
mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY);
}
// 更新上午/下午选择器展示
// 刷新上下午选择器的展示状态
updateAmPmControl();
// 触发时间变化回调
// 触发全局时间变化回调，向外通知上下午已切换
onDateTimeChanged();
}
};
// ======================== 回调接口 - 日期时间变化通知 ========================
// ======================== 内部回调接口 - 日期时间变化通知【标准化通信协议】 ========================
/**
* 日期时间变化回调接口
* 由外部（如DateTimePickerDialog）实现，接收控件选中的最新日期时间
* 日期时间变化回调接口：控件对外提供的唯一通信接口，所有时间选择操作的最终数据出口
* 设计原则：解耦控件内部逻辑与外部业务逻辑，控件只负责提供时间选择能力，不处理任何业务逻辑
* 调用时机：日期、小时、分钟、上下午任一选择器发生变化时，均会触发该接口的回调方法，实时传递最新的时间数据
*/
public interface OnDateTimeChangedListener {
/**
* 日期时间变化回调方法
* @param view 当前的DateTimePicker控件实例
* @param year 选中的年份
* @param month 选中的月份（Calendar.MONTH，0=1月，11=12月）
* @param dayOfMonth 选中的日期（当月的第几天）
* @param hourOfDay 选中的小时（24小时制，0~23）
* @param minute 选中的分钟（0~59）
* 日期时间变化的回调方法，传递标准化的时间数据
* @param view 当前的DateTimePicker控件实例，外部可通过该实例获取更多信息或执行操作
* @param year 选中的年份，如 2026
* @param month 选中的月份，遵循Calendar规范，0代表1月，11代表12月
* @param dayOfMonth 选中的日期，当月的第几天，如 15
* @param hourOfDay 选中的小时，固定为24小时制数值，0~23，外部无需做格式转换，直接使用
* @param minute 选中的分钟，0~59，标准化数值
*/
void onDateTimeChanged(DateTimePicker view, int year, int month,
int dayOfMonth, int hourOfDay, int minute);
}
// ======================== 构造方法 ========================
// ======================== 构造方法区 - 三级重载构造，满足不同初始化需求【核心初始化入口】 ========================
/**
* 构造方法1：默认初始化（使用当前系统时间，适配系统24小时制）
* @param context 应用上下文
* 构造方法1：最简初始化，无参重载
* 核心能力：使用系统当前时间作为初始值，自动适配系统的24小时制设置，一键创建控件
* @param context 应用上下文对象，不可为空
*/
public DateTimePicker(Context context) {
this(context, System.currentTimeMillis());
}
/**
* 构造方法2：指定初始时间，适配系统24小时制
* @param context 应用上下文
* @param date 初始时间戳（毫秒级）
* 构造方法2：指定初始时间初始化
* 核心能力：传入指定的毫秒级时间戳作为初始值，自动适配系统的24小时制设置，灵活适配业务需求
* @param context 应用上下文对象，不可为空
* @param date 初始选中的时间戳，单位：毫秒，支持任意合法的时间戳
*/
public DateTimePicker(Context context, long date) {
this(context, date, DateFormat.is24HourFormat(context));
}
/**
* 构造方法3：指定初始时间和24小时制状态，核心初始化逻辑
* @param context 应用上下文
* @param date 初始时间戳（毫秒级）
* @param is24HourView 是否使用24小时制
* 构造方法3：全参数核心初始化，控件的最终初始化入口，所有构造方法最终均调用此方法
* 核心能力：一站式完成「上下文初始化+核心数据初始化+布局填充+子选择器初始化+监听器绑定+状态配置+初始时间设置」，无需外部执行任何额外配置，开箱即用
* @param context 应用上下文对象，用于加载布局、创建控件、获取系统配置
* @param date 初始选中的时间戳，单位：毫秒，控件打开时默认展示的时间
* @param is24HourView 是否启用24小时制，true=启用，false=启用12小时制
*/
public DateTimePicker(Context context, long date, boolean is24HourView) {
super(context);
mDate = Calendar.getInstance(); // 初始化核心日历对象
mInitialising = true; // 标记进入初始化阶段（避免触发不必要的回调）
// 初始化上午/下午标记：根据当前小时数判断（≥12为下午）
mDate = Calendar.getInstance(); // 初始化核心日历对象，默认加载系统当前时间
mInitialising = true; // 标记进入初始化阶段，屏蔽所有回调触发，防止无效数据通知
// 初始化上下午状态标记：根据当前小时数判断，≥12为下午，<12为上午
mIsAm = getCurrentHourOfDay() >= HOURS_IN_HALF_DAY;
// 加载控件布局（datetime_picker.xml）
// 第一步：填充控件的核心布局，将xml布局文件加载至当前FrameLayout根容器
inflate(context, R.layout.datetime_picker, this);
// 初始化日期选择器
// 第二步：初始化所有子滚轮选择器，绑定控件ID，配置基础属性与监听器
// 初始化日期选择器：配置取值范围+绑定值变化监听器
mDateSpinner = (NumberPicker) findViewById(R.id.date);
mDateSpinner.setMinValue(DATE_SPINNER_MIN_VAL);
mDateSpinner.setMaxValue(DATE_SPINNER_MAX_VAL);
mDateSpinner.setOnValueChangedListener(mOnDateChangedListener);
// 初始化小时选择器
// 初始化小时选择器：仅绑定值变化监听器，取值范围在24/12小时制设置时动态配置
mHourSpinner = (NumberPicker) findViewById(R.id.hour);
mHourSpinner.setOnValueChangedListener(mOnHourChangedListener);
// 初始化分钟选择器
// 初始化分钟选择器：配置取值范围+设置长按快速滚动间隔+绑定值变化监听器，细节体验优化
mMinuteSpinner = (NumberPicker) findViewById(R.id.minute);
mMinuteSpinner.setMinValue(MINUT_SPINNER_MIN_VAL);
mMinuteSpinner.setMaxValue(MINUT_SPINNER_MAX_VAL);
mMinuteSpinner.setLongPressUpdateInterval(100); // 长按快速调整的间隔（100ms）
mMinuteSpinner.setLongPressUpdateInterval(100); // 长按滚动间隔100ms，滚动更快更流畅
mMinuteSpinner.setOnValueChangedListener(mOnMinuteChangedListener);
// 初始化上午/下午选择器
String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings(); // 获取系统AM/PM文本（适配多语言）
// 初始化上下午选择器：配置取值范围+加载系统原生的AM/PM文本（适配多语言）+绑定值变化监听器
String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings();
mAmPmSpinner = (NumberPicker) findViewById(R.id.amPm);
mAmPmSpinner.setMinValue(AMPM_SPINNER_MIN_VAL);
mAmPmSpinner.setMaxValue(AMPM_SPINNER_MAX_VAL);
mAmPmSpinner.setDisplayedValues(stringsForAmPm); // 设置AM/PM展示文本
mAmPmSpinner.setDisplayedValues(stringsForAmPm);
mAmPmSpinner.setOnValueChangedListener(mOnAmPmChangedListener);
// 更新控件到初始状态
// 第三步：刷新所有子选择器的初始展示状态，保证UI与初始数据一致
updateDateControl();
updateHourControl();
updateAmPmControl();
// 设置24小时制状态
// 第四步：配置24/12小时制状态，完成制式适配
set24HourView(is24HourView);
// 设置初始时间
// 第五步：设置控件的初始选中时间，同步至所有选择器与核心日历对象
setCurrentDate(date);
// 设置控件启用状态
// 第六步：配置控件的整体启用状态，默认启用
setEnabled(isEnabled());
// 初始化完成，取消标记
// 第七步：初始化完成，解除初始化标记，控件进入正常工作状态，可响应所有操作与回调
mInitialising = false;
}
// ======================== 重写方法 - 控件启用/禁用 ========================
// ======================== 重写父类方法 - 控件整体启用/禁用【统一状态管控】 ========================
/**
* 设置控件整体启用/禁用状态
* @param enabled true=启用（所有选择器可交互），false=禁用（所有选择器不可交互）
* 重写FrameLayout的setEnabled方法，实现控件整体的启用/禁用控制
* 核心能力：一键同步所有子滚轮选择器的交互状态，无需单独配置每个选择器，保证状态一致性
* 优化点：状态未变化时直接返回，避免重复执行无效操作，提升性能
* @param enabled true=启用，所有选择器可滑动选择；false=禁用，所有选择器不可交互，灰显
*/
@Override
public void setEnabled(boolean enabled) {
if (mIsEnabled == enabled) {
return; // 状态未变化，直接返回
return;
}
super.setEnabled(enabled);
// 同步所有选择器的启用状态
// 同步所有子选择器的启用状态
mDateSpinner.setEnabled(enabled);
mMinuteSpinner.setEnabled(enabled);
mHourSpinner.setEnabled(enabled);
mAmPmSpinner.setEnabled(enabled);
// 更新启用状态标记
// 更新全局启用状态标记
mIsEnabled = enabled;
}
/**
* 获取控件整体启用状态
* @return true=启用，false=禁用
* 重写FrameLayout的isEnabled方法，获取控件的整体启用状态
* @return true=控件已启用，false=控件已禁用
*/
@Override
public boolean isEnabled() {
return mIsEnabled;
}
// ======================== 公共方法 - 日期时间获取/设置 ========================
// ======================== 公共方法区 - 日期时间 取值/赋值 标准化API【外部核心调用接口，最全】 ========================
/**
* 获取当前选中的日期时间戳（毫秒级）
* @return 选中时间的毫秒数
* 获取当前选中的完整时间戳，外部最常用的取值方法
* @return 选中时间的毫秒级时间戳，可直接用于存储、传输、转换，标准化输出
*/
public long getCurrentDateInTimeMillis() {
return mDate.getTimeInMillis();
}
/**
* 设置当前选中的日期时间（通过时间戳）
* @param date 要设置的时间戳（毫秒级）
* 设置当前选中的时间，通过毫秒级时间戳赋值，外部最常用的赋值方法
* 核心能力：自动解析时间戳为年月日时分，同步至核心日历对象与所有子选择器，无需手动拆分
* @param date 要设置的时间戳，单位：毫秒，支持任意合法的时间戳
*/
public void setCurrentDate(long date) {
Calendar cal = Calendar.getInstance();
cal.setTimeInMillis(date);
// 解析时间戳为年/月/日/时/分，调用重载方法设置
// 解析时间戳为标准化的年月日时分，调用重载方法完成赋值
setCurrentDate(cal.get(Calendar.YEAR), cal.get(Calendar.MONTH), cal.get(Calendar.DAY_OF_MONTH),
cal.get(Calendar.HOUR_OF_DAY), cal.get(Calendar.MINUTE));
}
/**
* 设置当前选中的日期时间（通过年/月/日/时/分）
* @param year 年份
* @param month 月份（Calendar.MONTH，0=1月）
* @param dayOfMonth 日期（当月的第几天）
* @param hourOfDay 小时（24小时制，0~23）
* @param minute 分钟（0~59）
* 设置当前选中的时间，通过标准化的年月日时分赋值，最底层的赋值方法
* 核心能力：精细化控制每个时间维度的数值，同步至核心日历对象与所有子选择器，数据完全可控
* @param year 年份，如 2026
* @param month 月份，Calendar规范，0=1月
* @param dayOfMonth 日期，当月的第几天，1~31
* @param hourOfDay 小时，24小时制，0~23
* @param minute 分钟，0~59
*/
public void setCurrentDate(int year, int month,
int dayOfMonth, int hourOfDay, int minute) {
@ -411,7 +444,7 @@ public class DateTimePicker extends FrameLayout {
/**
* 获取当前选中的年份
* @return 年份（如2025）
* @return 年份数值，如 2026
*/
public int getCurrentYear() {
return mDate.get(Calendar.YEAR);
@ -419,21 +452,21 @@ public class DateTimePicker extends FrameLayout {
/**
* 设置当前选中的年份
* @param year 要设置的年份（如2025）
* 优化点：初始化阶段或数值未变化时直接返回，避免无效操作与回调触发
* @param year 要设置的年份，如 2026
*/
public void setCurrentYear(int year) {
// 初始化中或年份未变化时，直接返回
if (!mInitialising && year == getCurrentYear()) {
return;
}
mDate.set(Calendar.YEAR, year);
updateDateControl(); // 更新日期选择器展示
onDateTimeChanged(); // 触发时间变化回调
updateDateControl();
onDateTimeChanged();
}
/**
* 获取当前选中的月份
* @return 月份（Calendar.MONTH，0=1月，11=12月）
* @return 月份数值，遵循Calendar规范，0代表1月，11代表12月
*/
public int getCurrentMonth() {
return mDate.get(Calendar.MONTH);
@ -441,216 +474,212 @@ public class DateTimePicker extends FrameLayout {
/**
* 设置当前选中的月份
* @param month 要设置的月份（Calendar.MONTH，0=1月）
* 优化点：初始化阶段或数值未变化时直接返回，避免无效操作与回调触发
* @param month 要设置的月份，Calendar规范，0=1月
*/
public void setCurrentMonth(int month) {
// 初始化中或月份未变化时，直接返回
if (!mInitialising && month == getCurrentMonth()) {
return;
}
mDate.set(Calendar.MONTH, month);
updateDateControl(); // 更新日期选择器展示
onDateTimeChanged(); // 触发时间变化回调
updateDateControl();
onDateTimeChanged();
}
/**
* 获取当前选中的日期（当月的第几天）
* @return 日期（1~31）
* 获取当前选中的日期
* @return 日期数值，当月的第几天，1~31
*/
public int getCurrentDay() {
return mDate.get(Calendar.DAY_OF_MONTH);
}
/**
* 设置当前选中的日期（当月的第几天）
* @param dayOfMonth 要设置的日期（1~31）
* 设置当前选中的日期
* 优化点：初始化阶段或数值未变化时直接返回，避免无效操作与回调触发
* @param dayOfMonth 要设置的日期，1~31
*/
public void setCurrentDay(int dayOfMonth) {
// 初始化中或日期未变化时，直接返回
if (!mInitialising && dayOfMonth == getCurrentDay()) {
return;
}
mDate.set(Calendar.DAY_OF_MONTH, dayOfMonth);
updateDateControl(); // 更新日期选择器展示
onDateTimeChanged(); // 触发时间变化回调
updateDateControl();
onDateTimeChanged();
}
/**
* 获取当前选中的小时（24小时制，0~23）
* @return 小时数（0~23）
* 获取当前选中的小时数，固定返回24小时制数值，标准化输出，外部无需转换
* @return 小时数值，0~23
*/
public int getCurrentHourOfDay() {
return mDate.get(Calendar.HOUR_OF_DAY);
}
/**
* 内部方法：获取适配当前制式的小时数（24/12小时制）
* @return 24小时制返回0~23，12小时制返回1~12
* 内部私有方法：获取适配当前制式的小时数
* 核心能力：根据24/12小时制，返回对应范围的小时数，供内部选择器赋值使用，不对外暴露
* @return 24小时制返回0~23，12小时制返回1~12，适配选择器的取值范围
*/
private int getCurrentHour() {
if (mIs24HourView){
return getCurrentHourOfDay(); // 24小时制直接返回
return getCurrentHourOfDay();
} else {
// 12小时制转换：0点→12点，13点→1点，依此类推
int hour = getCurrentHourOfDay();
if (hour > HOURS_IN_HALF_DAY) {
return hour - HOURS_IN_HALF_DAY;
} else {
return hour == 0 ? HOURS_IN_HALF_DAY : hour;
}
// 12小时制特殊转换：0点→12点，13点→1点，保证选择器展示正确
return hour > HOURS_IN_HALF_DAY ? hour - HOURS_IN_HALF_DAY : (hour == 0 ? HOURS_IN_HALF_DAY : hour);
}
}
/**
* 设置当前选中的小时（24小时制，0~23）
* @param hourOfDay 要设置的小时数（0~23）
* 设置当前选中的小时数，接收24小时制数值，标准化输入，内部自动适配转换
* 核心能力：自动处理24/12小时制的转换逻辑，同步更新上下午状态与选择器，数据无误差
* 优化点：初始化阶段或数值未变化时直接返回，避免无效操作与回调触发
* @param hourOfDay 要设置的小时数，24小时制，0~23
*/
public void setCurrentHour(int hourOfDay) {
// 初始化中或小时未变化时，直接返回
if (!mInitialising && hourOfDay == getCurrentHourOfDay()) {
return;
}
mDate.set(Calendar.HOUR_OF_DAY, hourOfDay);
// 12小时制下，更新上午/下午标记和选择器
// 12小时制下的特殊处理：转换小时数+更新上下午状态
if (!mIs24HourView) {
if (hourOfDay >= HOURS_IN_HALF_DAY) {
mIsAm = false; // ≥12为下午
if (hourOfDay > HOURS_IN_HALF_DAY) {
hourOfDay -= HOURS_IN_HALF_DAY; // 转换为12小时制（13→1，14→2...）
}
mIsAm = false;
hourOfDay = hourOfDay > HOURS_IN_HALF_DAY ? hourOfDay - HOURS_IN_HALF_DAY : hourOfDay;
} else {
mIsAm = true; // <12为上午
if (hourOfDay == 0) {
hourOfDay = HOURS_IN_HALF_DAY; // 0点→12点
}
mIsAm = true;
hourOfDay = hourOfDay == 0 ? HOURS_IN_HALF_DAY : hourOfDay;
}
updateAmPmControl(); // 更新上午/下午选择器
updateAmPmControl();
}
// 设置小时选择器的值
mHourSpinner.setValue(hourOfDay);
// 触发时间变化回调
onDateTimeChanged();
}
/**
* 获取当前选中的分钟
* @return 分钟数（0~59）
* 获取当前选中的分钟数
* @return 分钟数值，0~59
*/
public int getCurrentMinute() {
return mDate.get(Calendar.MINUTE);
}
/**
* 设置当前选中的分钟
* @param minute 要设置的分钟数（0~59）
* 设置当前选中的分钟数
* 优化点：初始化阶段或数值未变化时直接返回，避免无效操作与回调触发
* @param minute 要设置的分钟数，0~59
*/
public void setCurrentMinute(int minute) {
// 初始化中或分钟未变化时，直接返回
if (!mInitialising && minute == getCurrentMinute()) {
return;
}
mMinuteSpinner.setValue(minute); // 设置分钟选择器的值
mDate.set(Calendar.MINUTE, minute); // 更新日历对象
onDateTimeChanged(); // 触发时间变化回调
mMinuteSpinner.setValue(minute);
mDate.set(Calendar.MINUTE, minute);
onDateTimeChanged();
}
// ======================== 公共方法 - 24小时制适配 ========================
// ======================== 公共方法区 - 24小时制适配【系统级适配能力】 ========================
/**
* 判断当前是否为24小时制
* 判断当前控件是否启用24小时制
* @return true=24小时制，false=12小时制
*/
public boolean is24HourView () {
return mIs24HourView;
}
public boolean is24HourView () {
return mIs24HourView;
}
/**
* 设置24小时制/12小时制
* @param is24HourView true=24小时制（隐藏AM/PM选择器），false=12小时制（显示AM/PM选择器）
* 设置控件的时间展示制式，手动强制切换24/12小时制，优先级高于系统配置
* 核心能力：切换制式时，自动刷新小时选择器的取值范围、上下午选择器的可见性、当前小时数的展示值，无缝切换无感知
* 优化点：状态未变化时直接返回，避免无效操作
* @param is24HourView true=启用24小时制，隐藏上下午选择器；false=启用12小时制，显示上下午选择器
*/
public void set24HourView(boolean is24HourView) {
if (mIs24HourView == is24HourView) {
return; // 状态未变化，直接返回
}
mIs24HourView = is24HourView;
// 显示/隐藏上午/下午选择器
public void set24HourView(boolean is24HourView) {
if (mIs24HourView == is24HourView) {
return;
}
mIs24HourView = is24HourView;
// 控制上下午选择器的可见性
mAmPmSpinner.setVisibility(is24HourView ? View.GONE : View.VISIBLE);
// 获取当前小时数（用于重置选择器）
int hour = getCurrentHourOfDay();
// 更新小时选择器的取值范围
// 刷新小时选择器的取值范围
updateHourControl();
// 重新设置小时数（适配新的制式）
// 重新适配并设置小时数，保证展示正确
setCurrentHour(hour);
// 更新上午/下午选择器状态
// 刷新上下午选择器的状态
updateAmPmControl();
}
}
// ======================== 内部方法 - 控件更新 ========================
// ======================== 内部私有方法区 - 控件UI刷新【核心UI更新逻辑，内部闭环】 ========================
/**
* 更新日期选择器的展示文本：生成近7天的格式化日期（如“12.23 星期二”）
* 刷新日期选择器的展示文本与选中状态
* 核心能力：重新计算并生成近7天的格式化日期文本，更新至日期选择器，保证展示的日期与核心日历对象一致
* 展示格式：固定为「MM.dd EEEE」，即「月.日 星期」，如「01.15 星期四」
*/
private void updateDateControl() {
Calendar cal = Calendar.getInstance();
cal.setTimeInMillis(mDate.getTimeInMillis());
// 计算近7天的起始日期（当前日期 - 4天，确保中间为当前日期）
// 计算近7天的起始日期：当前日期向前推4天，保证选中日期在列表中间位置，交互更友好
cal.add(Calendar.DAY_OF_YEAR, -DAYS_IN_ALL_WEEK / 2 - 1);
mDateSpinner.setDisplayedValues(null); // 清空原有展示文本
// 生成近7天的格式化日期文本
mDateSpinner.setDisplayedValues(null); // 清空原有文本，避免残留
// 循环生成7天的格式化日期文本
for (int i = 0; i < DAYS_IN_ALL_WEEK; ++i) {
cal.add(Calendar.DAY_OF_YEAR, 1);
// 格式化：月.日 星期（如“12.23 星期二”）
mDateDisplayValues[i] = (String) DateFormat.format("MM.dd EEEE", cal);
}
// 设置日期选择器的展示文本
// 将生成的文本数组设置到日期选择器
mDateSpinner.setDisplayedValues(mDateDisplayValues);
// 设置默认选中中间项（当前日期）
// 默认选中列表中间项，即当前日期
mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2);
mDateSpinner.invalidate(); // 刷新选择器UI
mDateSpinner.invalidate(); // 强制刷新UI，保证展示生效
}
/**
* 更新上午/下午选择器的状态：设置选中项、控制可见性
* 刷新上下午选择器的选中状态与可见性
* 核心能力：根据当前的24小时制状态与上下午标记，同步更新上下午选择器的展示，保证UI与数据一致
*/
private void updateAmPmControl() {
if (mIs24HourView) {
mAmPmSpinner.setVisibility(View.GONE); // 24小时制隐藏
mAmPmSpinner.setVisibility(View.GONE);
} else {
// 设置选中项：0=AM/上午，1=PM/下午
// 设置选中项：0=上午/AM，1=下午/PM
int index = mIsAm ? Calendar.AM : Calendar.PM;
mAmPmSpinner.setValue(index);
mAmPmSpinner.setVisibility(View.VISIBLE); // 12小时制显示
mAmPmSpinner.setVisibility(View.VISIBLE);
}
}
/**
* 更新小时选择器的取值范围：适配24/12小时制
* 刷新小时选择器的取值范围
* 核心能力：根据当前的24小时制状态，动态配置小时选择器的最小值与最大值，适配不同制式的展示需求
*/
private void updateHourControl() {
if (mIs24HourView) {
// 24小时制：0~23
mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW);
mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW);
} else {
// 12小时制：1~12
mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW);
mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW);
}
}
// ======================== 公共方法 - 回调设置 ========================
private void updateHourControl() {
if (mIs24HourView) {
mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW);
mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW);
} else {
mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW);
mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW);
}
}
// ======================== 公共方法区 - 回调监听器绑定【通信入口】 ========================
/**
* 设置日期时间变化回调监听器
* @param callback 外部实现的监听器（null则不触发回调）
* 设置日期时间变化的回调监听器，外部通过此方法绑定业务逻辑
* @param callback 外部实现的OnDateTimeChangedListener接口实例，传null则取消监听
*/
public void setOnDateTimeChangedListener(OnDateTimeChangedListener callback) {
mOnDateTimeChangedListener = callback;
}
// ======================== 内部方法 - 回调触发 ========================
// ======================== 内部私有方法区 - 回调触发【核心通信逻辑，内部闭环】 ========================
/**
* 触发日期时间变化回调：传递最新的年/月/日/时/分
* 触发日期时间变化的回调方法，所有选择操作的最终数据出口
* 核心能力：从核心日历对象中读取标准化的年月日时分数据，调用外部绑定的监听器，完成数据传递
* 优化点：监听器为null时直接返回，避免空指针异常
*/
private void onDateTimeChanged() {
if (mOnDateTimeChangedListener != null) {

124
src/Notes-master/src/net/micode/notes/ui/DateTimePickerDialog.java
Unescape View File

@ -14,144 +14,160 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，封装日期时间选择对话框，集成DateTimePicker控件
// 包声明：归属小米便签UI模块，日期时间选择弹窗的核心封装类，集成自定义时间选择控件
package net.micode.notes.ui;
// 导入日历类：管理选中的日期时间，处理年/月/日/时/分的设置
// Java日历工具类，核心时间处理载体，存储用户选中的年月日时分秒，提供时间的赋值与转换能力
import java.util.Calendar;
// 导入小米便签资源类：引用对话框按钮文本、布局等资源
// 小米便签资源文件引用，获取字符串、布局等资源ID常量
import net.micode.notes.R;
// 导入自定义日期时间选择控件：核心的日期时间选择UI
// 自定义日期时间选择核心控件，本弹窗的核心内容视图，提供年月日时分滚轮选择UI
import net.micode.notes.ui.DateTimePicker;
import net.micode.notes.ui.DateTimePicker.OnDateTimeChangedListener;
// 导入安卓对话框相关类：基础AlertDialog、对话框点击事件
// 安卓系统弹窗核心类，本类的父类，提供弹窗的基础展示与按钮配置能力
import android.app.AlertDialog;
import android.content.Context;
import android.content.DialogInterface;
import android.content.DialogInterface.OnClickListener;
// 导入安卓日期格式化工具类：判断24小时制、格式化日期时间文本
// 安卓系统日期格式化工具类，提供24小时制判断、时间戳转友好文本的格式化能力
import android.text.format.DateFormat;
import android.text.format.DateUtils;
/**
* 日期时间选择对话框封装类
* 继承自AlertDialog，核心职责：
* 1. 集成自定义DateTimePicker控件，提供统一的日期时间选择UI；
* 2. 管理选中的日期时间（Calendar对象），处理时间变化的实时更新；
* 3. 适配系统24小时制设置，动态更新对话框标题（格式化显示选中的日期时间）；
* 4. 提供选择完成的回调接口，返回最终选中的时间戳；
* 典型使用场景：便签添加/编辑页面的“设置提醒时间”功能。
* 日期时间选择弹窗封装类【功能型弹窗核心类】
* 继承：AlertDialog 安卓原生弹窗基类，具备系统弹窗的所有基础特性
* 核心定位：小米便签「设置便签提醒时间」功能的专属弹窗，整合自定义DateTimePicker控件实现完整的时间选择能力
* 核心设计思想：将「时间选择控件+弹窗载体+时间数据处理+回调通信」全部封装，对外提供极简调用API
* 核心职责：
* 1. 集成自定义DateTimePicker滚轮选择控件，作为弹窗的核心内容视图，提供年月日时分的可视化选择；
* 2. 统一管理选中的时间数据，基于Calendar类存储完整时间信息，自动处理时间联动更新逻辑；
* 3. 适配系统全局的24小时制/12小时制显示规则，自动切换时间展示格式，保证与系统行为一致；
* 4. 实时更新弹窗标题为当前选中的格式化时间文本，给用户直观的选择反馈；
* 5. 封装标准化的回调接口，选择完成后向外传递最终的毫秒级时间戳，解耦业务逻辑；
* 6. 固化弹窗的按钮交互逻辑：确定按钮触发回调、取消按钮关闭弹窗无操作，交互统一；
* 7. 时间精度控制：仅保留到分钟级，自动置空秒数，符合便签提醒的业务使用场景。
* 典型业务场景：便签编辑页的「添加提醒」「修改提醒时间」功能弹窗，是便签日程提醒的核心交互载体。
*/
public class DateTimePickerDialog extends AlertDialog implements OnClickListener {
// 选中的日期时间对象：存储用户选择的年/月/日/时/分，秒固定为0
// 核心时间数据载体：存储用户当前选中的完整日期时间，初始化时获取系统当前时间，秒数固定置0
private Calendar mDate = Calendar.getInstance();
// 是否使用24小时制：适配系统设置，影响时间显示格式
// 24小时制标记位：适配系统设置，决定时间的展示格式（24小时/12小时带上午下午）
private boolean mIs24HourView;
// 日期时间选择完成的回调监听器：外部实现，接收最终选中的时间戳
// 时间选择完成的回调监听器：外部实现该接口接收最终选中的时间戳，核心通信桥梁
private OnDateTimeSetListener mOnDateTimeSetListener;
// 核心日期时间选择控件：承载年/月/日/时/分的选择UI
// 自定义日期时间选择控件：本弹窗的核心内容视图，提供滚轮式年月日时分选择UI，业务核心控件
private DateTimePicker mDateTimePicker;
/**
* 日期时间选择完成的回调接口
* 由外部（如NoteEditActivity）实现，接收对话框返回的选中时间戳
* 日期时间选择完成的回调接口【标准化通信接口】
* 设计原则：解耦弹窗内部逻辑与外部业务逻辑，弹窗只负责提供选择能力，不处理业务逻辑
* 调用时机：用户点击弹窗的「确定」按钮后，触发该接口的回调方法，传递选中的时间数据
*/
public interface OnDateTimeSetListener {
/**
* 选择完成回调方法
* @param dialog 当前的日期时间选择对话框（可用于关闭/操作对话框）
* @param date 选中的日期时间戳（毫秒级，秒已置为0）
* 时间选择完成的回调方法
* @param dialog 当前的日期时间选择弹窗实例，外部可通过该实例做弹窗关闭等操作
* @param date 用户最终选中的时间戳，单位：毫秒，秒数已固定置为0，精度到分钟级
*/
void OnDateTimeSet(AlertDialog dialog, long date);
}
/**
* 构造方法：初始化日期时间选择对话框
* @param context 应用上下文：用于创建对话框、加载资源、适配系统设置
* @param date 初始时间戳：对话框打开时默认选中的时间（毫秒级）
* 构造方法：初始化日期时间选择弹窗的全部核心配置【一站式初始化】
* 核心能力：传入上下文和初始时间戳后，自动完成「控件创建+视图绑定+数据初始化+事件绑定+按钮配置+标题更新」
* 无需外部执行任何额外配置，开箱即用，调用简洁
* @param context 应用上下文对象，用于创建弹窗、加载资源、适配系统设置，不可为空
* @param date 弹窗初始化时的默认选中时间戳，单位：毫秒，支持传入指定时间做默认值展示
*/
public DateTimePickerDialog(Context context, long date) {
super(context);
// 1. 创建自定义日期时间选择控件，设置为对话框的核心视图
// 第一步：创建自定义的日期时间选择控件，作为弹窗的核心内容视图，替换原生弹窗的默认布局
mDateTimePicker = new DateTimePicker(context);
setView(mDateTimePicker);
// 2. 绑定DateTimePicker的时间变化监听：实时更新选中的Calendar对象
// 第二步：为时间选择控件绑定实时变化监听器，核心联动逻辑
// 监听用户在滚轮上的每一次选择操作，实时同步选中的时间数据到Calendar对象中
mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() {
public void onDateTimeChanged(DateTimePicker view, int year, int month,
int dayOfMonth, int hourOfDay, int minute) {
// 更新Calendar对象的年/月/日/时/分
// 实时更新核心时间载体：将滚轮选中的年月日时分赋值到Calendar对象
mDate.set(Calendar.YEAR, year);
mDate.set(Calendar.MONTH, month);
mDate.set(Calendar.DAY_OF_MONTH, dayOfMonth);
mDate.set(Calendar.HOUR_OF_DAY, hourOfDay);
mDate.set(Calendar.MINUTE, minute);
// 实时更新对话框标题（格式化显示当前选中的时间）
// 实时更新弹窗标题：将最新选中的时间格式化后展示在弹窗顶部，给用户即时反馈
updateTitle(mDate.getTimeInMillis());
}
});
// 3. 初始化选中的日期时间：设置初始时间戳，秒固定为0（仅保留到分钟级）
// 第三步：初始化选中的时间数据，设置默认选中的时间戳，统一时间精度
mDate.setTimeInMillis(date);
mDate.set(Calendar.SECOND, 0);
// 将初始时间设置到DateTimePicker控件
mDate.set(Calendar.SECOND, 0); // 强制置空秒数，仅保留到分钟级，符合业务使用场景
// 将初始化的时间数据同步到时间选择控件，保证弹窗打开时展示正确的默认时间
mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());
// 4. 设置对话框按钮：确认（触发回调）、取消（无操作）
setButton(context.getString(R.string.datetime_dialog_ok), this); // 确认按钮绑定当前类的onClick
setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null); // 取消按钮无操作
// 第四步：配置弹窗的底部按钮，固化交互逻辑，符合用户操作习惯
setButton(context.getString(R.string.datetime_dialog_ok), this); // 确定按钮，绑定当前类的点击事件
setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null); // 取消按钮，无业务逻辑，点击仅关闭弹窗
// 5. 适配系统24小时制设置：获取系统是否启用24小时制，设置到对话框
// 第五步：适配系统全局的时间显示规则，自动获取系统是否开启24小时制，保证体验一致性
set24HourView(DateFormat.is24HourFormat(this.getContext()));
// 6. 初始化对话框标题：格式化显示初始时间
// 第六步：初始化弹窗标题，将默认时间格式化后展示，完成弹窗的最终初始化
updateTitle(mDate.getTimeInMillis());
}
/**
* 设置是否使用24小时制显示时间
* @param is24HourView true=24小时制，false=12小时制（上午/下午）
* 公有配置方法：手动设置弹窗的时间显示格式
* 补充能力：支持外部手动覆盖系统的24小时制设置，按需指定显示规则，适配特殊业务场景
* @param is24HourView true=强制使用24小时制展示时间，false=强制使用12小时制展示时间
*/
public void set24HourView(boolean is24HourView) {
mIs24HourView = is24HourView;
}
/**
* 设置日期时间选择完成的回调监听器
* @param callBack 外部实现的OnDateTimeSetListener（如NoteEditActivity）
* 公有绑定方法：设置时间选择完成的回调监听器
* 核心作用：为弹窗绑定外部的业务逻辑处理类，是弹窗向外传递数据的唯一入口
* @param callBack 外部实现的OnDateTimeSetListener接口实例，接收最终选中的时间戳
*/
public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) {
mOnDateTimeSetListener = callBack;
}
/**
* 私有方法：更新对话框标题，格式化显示选中的日期时间
* @param date 要显示的时间戳（毫秒级）
* 私有工具方法：更新弹窗标题文本【核心格式化方法】
* 核心职责：将毫秒级的时间戳，按照指定的格式规则，转换为用户友好的日期时间文本
* 设计亮点：通过格式化标记位组合，灵活配置展示内容，无需手写格式化字符串，适配性更强
* @param date 需要格式化展示的时间戳，单位：毫秒
*/
private void updateTitle(long date) {
// 定义日期时间格式化标记：显示年、日期、时间
// 定义时间格式化的标记位组合，指定需要展示的时间维度：年 + 月日 + 时分
int flag =
DateUtils.FORMAT_SHOW_YEAR | // 显示年份
DateUtils.FORMAT_SHOW_DATE | // 显示日期（月/日）
DateUtils.FORMAT_SHOW_TIME; // 显示时间（时/分）
// 适配24小时制：覆盖标记（FORMAT_24HOUR无论true/false，仅控制显示格式）
DateUtils.FORMAT_SHOW_YEAR | // 强制展示年份，如「2026年」
DateUtils.FORMAT_SHOW_DATE | // 强制展示日期，如「1月15日」
DateUtils.FORMAT_SHOW_TIME; // 强制展示时间，如「15:30」或「下午3:30」
// 根据24小时制标记位，追加对应的格式化规则，自动切换显示格式
flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_24HOUR;
// 格式化时间戳为文本，设置为对话框标题
// 将时间戳格式化后，设置为弹窗的标题文本，完成UI更新
setTitle(DateUtils.formatDateTime(this.getContext(), date, flag));
}
/**
* 对话框确认按钮点击事件处理
* 触发日期时间选择完成的回调，返回最终选中的时间戳
* @param arg0 对话框实例（DialogInterface）
* @param arg1 按钮索引（确认按钮为DialogInterface.BUTTON_POSITIVE）
* 弹窗确定按钮的点击事件处理【核心交互方法】
* 实现OnClickListener接口的核心方法，仅响应确定按钮的点击行为
* 核心逻辑：判断是否绑定了回调监听器，若绑定则触发回调，传递选中的时间戳，完成数据通信
* @param arg0 触发点击事件的弹窗对话框实例
* @param arg1 被点击按钮的索引标识，对应确定/取消等按钮类型
*/
public void onClick(DialogInterface arg0, int arg1) {
// 有回调监听器时，触发回调并传递选中的时间戳
// 空值安全校验：避免未绑定回调监听器时触发空指针异常
if (mOnDateTimeSetListener != null) {
// 触发外部回调，传递弹窗实例和最终选中的时间戳，完成时间选择的业务闭环
mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis());
}
}

90
src/Notes-master/src/net/micode/notes/ui/DropdownMenu.java
Unescape View File

@ -14,95 +14,109 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，封装下拉菜单的核心逻辑，简化PopupMenu的使用
// 包声明：归属小米便签UI模块，下拉菜单功能的统一封装工具类，全局复用
package net.micode.notes.ui;
// 导入安卓上下文类：提供应用运行环境（创建PopupMenu、加载资源）
// 安卓系统核心类 - 上下文，提供资源加载、控件创建的运行环境，必须依赖项
import android.content.Context;
// 导入安卓菜单相关类：管理下拉菜单的选项和菜单项
// 安卓菜单体系核心类，Menu管理菜单整体结构，MenuItem表示单个菜单项
import android.view.Menu;
import android.view.MenuItem;
// 导入安卓视图相关类：处理按钮点击事件
// 安卓视图体系核心类，处理视图点击事件、视图基础属性配置
import android.view.View;
import android.view.View.OnClickListener;
// 导入安卓按钮控件类：作为下拉菜单的触发按钮
// 安卓按钮控件，作为下拉菜单的触发载体，本类核心绑定控件
import android.widget.Button;
// 导入安卓PopupMenu类：核心的下拉菜单控件
// 安卓原生下拉菜单核心控件，实现弹窗式菜单展示，本类封装的核心原生控件
import android.widget.PopupMenu;
// 安卓下拉菜单的菜单项点击事件监听器，监听菜单选项的点击行为
import android.widget.PopupMenu.OnMenuItemClickListener;
// 导入小米便签资源类：引用下拉按钮的背景资源
// 小米便签资源文件引用，获取图标、布局等资源ID常量
import net.micode.notes.R;
/**
* 下拉菜单封装类
* 核心职责：
* 1. 封装安卓PopupMenu和触发按钮（Button），简化下拉菜单的创建与使用；
* 2. 统一设置下拉按钮的样式（背景图标）；
* 3. 封装菜单加载、点击事件绑定、菜单项查找、按钮文本设置等核心逻辑；
* 典型使用场景：便签应用中排序、筛选、操作选项等下拉菜单场景（如列表页的更多操作）。
* 下拉菜单功能封装工具类【全局复用型UI工具类】
* 核心设计模式：封装模式，对Android原生PopupMenu+触发Button进行一站式封装
* 核心定位：小米便签内所有下拉菜单场景的统一实现方案，抽离通用逻辑，避免重复开发
* 核心价值：
* 1. 屏蔽原生PopupMenu的复杂创建流程，对外提供极简的调用API，一行代码即可创建下拉菜单；
* 2. 统一应用内所有下拉菜单的视觉样式（触发按钮背景图标、菜单展示位置），保证UI一致性；
* 3. 封装菜单资源加载、点击事件绑定、菜单项查找、按钮文本更新等全套核心逻辑；
* 4. 解耦下拉菜单的「创建-展示-事件处理」逻辑，外部无需关心内部实现细节；
* 5. 轻量化封装，无冗余逻辑，仅做功能整合，不侵入业务代码，适配所有下拉菜单使用场景。
* 典型业务场景：便签列表页的排序方式选择、文件夹操作菜单、更多功能选项、筛选条件下拉框等。
*/
public class DropdownMenu {
// 下拉菜单的触发按钮：点击该按钮显示下拉菜单，统一设置背景样式
// 下拉菜单的触发按钮，全局持用引用：点击该按钮即可弹出下拉菜单，统一配置背景样式
private Button mButton;
// 核心下拉菜单控件：承载菜单选项，控制菜单的显示/隐藏
// Android原生下拉菜单核心控件，本类封装的核心对象：负责菜单的弹出、收起、承载菜单项
private PopupMenu mPopupMenu;
// PopupMenu对应的Menu对象：用于查找菜单项、管理菜单内容
// PopupMenu对应的菜单容器对象：用于动态查找、修改、管理菜单项的状态（显示/隐藏/禁用等）
private Menu mMenu;
/**
* 构造方法：初始化下拉菜单（绑定触发按钮+加载菜单布局）
* @param context 应用上下文：用于创建PopupMenu、加载菜单资源
* @param button 触发下拉菜单的按钮控件：统一设置背景为下拉图标
* @param menuId 菜单布局资源ID：如R.menu.xxx，定义下拉菜单的选项列表
* 构造方法：初始化下拉菜单的全部核心配置【一站式初始化】
* 核心能力：传入必要参数后，自动完成「按钮样式配置+下拉菜单创建+菜单资源加载+点击触发绑定」
* 无需外部执行任何额外初始化操作，极简调用，开箱即用
* @param context 上下文对象，用于创建PopupMenu、加载菜单资源、获取应用运行环境，不可为空
* @param button 触发下拉菜单的按钮控件，菜单会锚定该按钮在下方弹出，与菜单强绑定
* @param menuId 菜单布局的资源ID（如R.menu.menu_sort），定义下拉菜单的所有选项列表
*/
public DropdownMenu(Context context, Button button, int menuId) {
// 保存触发按钮引用
// 保存触发按钮的全局引用，供后续设置文本、复用控件使用
mButton = button;
// 设置按钮背景为下拉图标（统一样式）
// 统一设置触发按钮的背景样式：加载内置的下拉箭头图标，保证所有下拉按钮视觉统一
mButton.setBackgroundResource(R.drawable.dropdown_icon);
// 创建PopupMenu：关联上下文和触发按钮（菜单显示在按钮下方）
// 创建原生PopupMenu对象，绑定上下文和触发按钮，指定菜单弹出的锚点位置
mPopupMenu = new PopupMenu(context, mButton);
// 获取PopupMenu对应的Menu对象，用于后续菜单管理
// 获取PopupMenu内部的Menu容器对象，缓存引用，供后续菜单项查找使用，避免重复获取
mMenu = mPopupMenu.getMenu();
// 加载菜单布局资源到Menu中（初始化下拉菜单的选项）
// 通过菜单解析器，将指定的菜单布局资源加载到Menu容器中，完成菜单项的初始化展示
mPopupMenu.getMenuInflater().inflate(menuId, mMenu);
// 绑定按钮点击事件：点击按钮显示下拉菜单
// 为触发按钮绑定点击事件监听器：点击按钮时，自动弹出下拉菜单，核心触发逻辑
mButton.setOnClickListener(new OnClickListener() {
public void onClick(View v) {
mPopupMenu.show(); // 显示下拉菜单
// 弹出下拉菜单，菜单默认展示在触发按钮的下方，对齐方式由系统原生适配
mPopupMenu.show();
}
});
}
/**
* 设置下拉菜单项的点击监听器
* 监听器由外部实现，处理不同菜单项的点击逻辑（如排序、删除、移动等）
* @param listener 菜单项点击监听器（OnMenuItemClickListener）
* 对外提供的事件绑定方法：设置下拉菜单项的点击事件监听器
* 核心设计：事件逻辑完全交由外部实现，本类只做事件转发，无任何业务逻辑侵入，高度解耦
* 外部可根据菜单项的ID，分别处理不同选项的点击业务（如排序、筛选、删除、移动等）
* @param listener 菜单项点击事件监听器，外部实现该接口的onMenuItemClick方法处理具体逻辑
*/
public void setOnDropdownMenuItemClickListener(OnMenuItemClickListener listener) {
// 仅当PopupMenu初始化完成时，绑定监听器
// 空值安全校验：避免PopupMenu未初始化完成时绑定监听器导致空指针异常
if (mPopupMenu != null) {
// 将外部传入的监听器绑定到PopupMenu，所有菜单项的点击事件都会回调该监听器
mPopupMenu.setOnMenuItemClickListener(listener);
}
}
/**
* 根据菜单项ID查找对应的MenuItem
* 用于外部动态修改菜单项状态（如隐藏/禁用/设置图标）
* @param id 菜单项的资源ID（如R.id.menu_sort_by_time）
* @return MenuItem：找到的菜单项（未找到返回null）
* 工具方法：根据菜单项的资源ID查找对应的MenuItem对象
* 核心用途：支持外部动态修改菜单项的状态，如「隐藏/显示菜单项」「禁用/启用菜单项」「修改菜单项文本/图标」等
* 是实现菜单动态化配置的核心入口，满足复杂业务场景的菜单定制需求
* @param id 目标菜单项的资源ID（如R.id.menu_sort_by_time、R.id.menu_move_folder）
* @return MenuItem 找到的菜单项对象，未找到时返回null
*/
public MenuItem findItem(int id) {
// 直接通过缓存的Menu对象查找菜单项，高效无冗余
return mMenu.findItem(id);
}
/**
* 设置下拉触发按钮的显示文本
* 用于动态更新按钮文本（如“排序方式”“当前文件夹”等）
* @param title 按钮要显示的文本内容
* 工具方法：动态设置下拉菜单触发按钮的显示文本
* 核心业务价值：支持按钮文本的动态更新，适配「当前选中状态展示」场景
* 比如：排序菜单按钮显示「按时间排序」、文件夹菜单按钮显示「当前文件夹：工作」等
* @param title 按钮需要展示的文本内容，支持字符串常量、动态拼接字符串
*/
public void setTitle(CharSequence title) {
// 直接为触发按钮设置文本内容，更新UI展示
mButton.setText(title);
}
}

155
src/Notes-master/src/net/micode/notes/ui/FoldersListAdapter.java
Unescape View File

@ -14,137 +14,162 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，作为文件夹列表（如“移动便签”弹窗）的核心适配器
// 包声明：归属小米便签UI模块，是文件夹列表展示的核心数据适配器
package net.micode.notes.ui;
// 导入安卓上下文类：提供应用运行环境（创建列表项、加载资源）
// 安卓系统核心类 - 上下文，提供资源加载、视图创建的运行环境
import android.content.Context;
// 导入安卓数据库游标类：存储文件夹数据库查询结果
// 安卓数据库游标类，承载文件夹的数据库查询结果集，适配器的核心数据源
import android.database.Cursor;
// 导入安卓视图相关类：创建/绑定列表项视图
// 安卓视图体系核心类，用于创建和装载列表子项视图
import android.view.View;
import android.view.ViewGroup;
// 导入安卓Cursor适配器类：适配Cursor数据的列表适配器基类
// 安卓游标适配器基类，适配Cursor数据源的列表专用适配器，本类核心父类
import android.widget.CursorAdapter;
// 导入安卓线性布局类：作为文件夹列表项的根布局
// 安卓线性布局，作为自定义列表项的根布局容器
import android.widget.LinearLayout;
// 导入安卓文本视图类：展示文件夹名称
// 安卓文本控件，用于展示文件夹名称文本内容
import android.widget.TextView;
// 导入小米便签资源类：引用布局、字符串资源（根文件夹显示文本）
// 小米便签资源文件引用，获取布局、字符串等资源id
import net.micode.notes.R;
// 导入便签数据常量类：定义文件夹ID（根文件夹）、字段等常量
// 小米便签核心数据常量，定义文件夹id、数据库字段名等全局常量
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.NoteColumns;
/**
* 文件夹列表核心适配器类
* 继承自安卓CursorAdapter，核心职责：
* 1. 定义文件夹数据库查询的投影字段（仅ID和名称），减少查询冗余；
* 2. 将文件夹Cursor数据绑定到自定义列表项（FolderListItem）；
* 3. 特殊适配根文件夹：将根文件夹的名称替换为“移动到上级文件夹”（而非原始名称）；
* 4. 提供工具方法，根据列表位置获取文件夹名称（适配根文件夹规则）。
* 典型使用场景：便签“移动到文件夹”弹窗的文件夹列表展示。
* 文件夹列表专用数据适配器【核心功能适配器】
* 继承：CursorAdapter 安卓原生游标适配器，完美适配数据库查询的Cursor结果集
* 核心定位：小米便签中「移动便签到文件夹」弹窗的核心适配器，负责文件夹列表的数据绑定与视图渲染
* 核心职责：
* 1. 定义文件夹查询的精简投影字段，只查必要数据，减少数据库IO开销，提升列表加载效率；
* 2. 实现Cursor数据与列表子项视图的绑定逻辑，规范数据渲染流程；
* 3. 对「根文件夹」做特殊文本适配，将系统根文件夹名称替换为业务友好的文本提示；
* 4. 封装文件夹名称获取工具方法，对外提供统一的名称读取接口，解耦外部调用逻辑；
* 5. 内置自定义列表项布局，封装视图创建与控件绑定，避免外部多次 findViewById 性能损耗。
* 核心特点：轻量高效、职责单一，仅处理文件夹列表的「数据-视图」映射关系，无业务逻辑侵入。
*/
public class FoldersListAdapter extends CursorAdapter {
/**
* 文件夹数据库查询投影数组：仅包含核心字段，减少IO开销
* 字段说明：
* - NoteColumns.ID：文件夹唯一ID（根文件夹为Notes.ID_ROOT_FOLDER）
* - NoteColumns.SNIPPET：文件夹名称（根文件夹的SNIPPET无业务意义，需特殊替换）
* 文件夹数据库查询投影数组【核心常量】
* 设计原则：按需查询，只获取列表展示所需的核心字段，不查冗余字段，降低内存占用和查询耗时
* 字段组成：仅包含文件夹的唯一标识和展示名称，满足列表所有业务需求
*/
public static final String [] PROJECTION = {
NoteColumns.ID, // 0: 文件夹唯一ID
NoteColumns.SNIPPET // 1: 文件夹名称
NoteColumns.ID, // 数组索引0 - 文件夹的唯一ID，数据库主键
NoteColumns.SNIPPET // 数组索引1 - 文件夹的名称，用于列表展示
};
// 投影数组对应的列索引常量：简化Cursor取值，避免硬编码索引
public static final int ID_COLUMN = 0; // 文件夹ID列索引
public static final int NAME_COLUMN = 1; // 文件夹名称列索引
/**
* 投影字段对应的列索引常量
* 设计目的：封装索引数值，避免代码中出现硬编码数字，提升代码可读性和可维护性
* 作用：通过常量直接取值，Cursor.getInt(ID_COLUMN) 比 Cursor.getInt(0) 语义更清晰
*/
public static final int ID_COLUMN = 0; // 文件夹ID对应的游标列索引
public static final int NAME_COLUMN = 1; // 文件夹名称对应的游标列索引
/**
* 构造方法：初始化文件夹列表适配器
* @param context 应用上下文，传递给父类（用于创建列表项、加载资源）
* @param c 包含文件夹数据的Cursor（已查询完成，包含ID和名称字段）
* 父类传参：将上下文和游标数据源传递给CursorAdapter基类，完成适配器初始化
* @param context 上下文对象，用于加载资源、创建视图，不可为空
* @param c 数据库查询返回的游标，封装了所有文件夹的ID和名称数据，游标已完成查询定位
*/
public FoldersListAdapter(Context context, Cursor c) {
super(context, c);
// TODO Auto-generated constructor stub
}
/**
* 重写创建新视图方法：创建文件夹列表项视图
* @param context 应用上下文
* @param cursor 当前位置的Cursor（未使用，仅遵循父类接口）
* @param parent 列表项的父容器（ListView）
* @return View：新创建的FolderListItem自定义列表项
* 重写父类方法：创建列表子项的空白视图
* 生命周期：列表滚动时，为屏幕外新进入的位置创建全新的视图对象，复用性低
* 核心逻辑：仅创建视图容器，不做任何数据绑定，数据绑定由bindView方法完成
* @param context 上下文对象，用于创建视图
* @param cursor 当前位置对应的游标数据，本方法中暂未使用，仅遵循父类接口规范
* @param parent 列表子项的父容器，即承载所有文件夹项的ListView
* @return View 新建的、未绑定数据的文件夹列表子项视图
*/
@Override
public View newView(Context context, Cursor cursor, ViewGroup parent) {
// 创建自定义文件夹列表项视图（FolderListItem）
// 创建自定义的文件夹列表项视图，内部已完成布局加载和控件绑定
return new FolderListItem(context);
}
/**
* 重写绑定视图方法：将文件夹Cursor数据绑定到列表项UI
* 核心逻辑：
* - 根文件夹：名称替换为“移动到上级文件夹”；
* - 普通文件夹：使用Cursor中的原始名称；
* - 将处理后的名称绑定到列表项的文本控件。
* @param view 要绑定的列表项视图（FolderListItem）
* @param context 应用上下文（加载根文件夹的显示文本）
* @param cursor 当前位置的Cursor，包含文件夹ID和名称
* 重写父类核心方法：为列表子项视图绑定对应的数据【核心业务方法】
* 生命周期：列表首次加载/滚动复用视图时调用，所有数据渲染逻辑均在此实现
* 核心业务规则：
* 1. 根文件夹（ID=Notes.ID_ROOT_FOLDER）：不展示原始名称，替换为业务文本「移动到上级文件夹」；
* 2. 普通文件夹：直接展示数据库中存储的文件夹名称；
* 3. 类型安全校验：只处理自定义的FolderListItem视图，防止视图类型异常导致崩溃。
* @param view 待绑定数据的列表子项视图，可为newView创建的新视图，也可为复用的旧视图
* @param context 上下文对象，用于加载字符串资源
* @param cursor 当前列表位置对应的游标，已定位到对应行，可直接读取字段值
*/
@Override
public void bindView(View view, Context context, Cursor cursor) {
// 仅处理FolderListItem类型的视图（防止类型错误）
// 视图类型校验，保证类型安全，避免视图强转异常
if (view instanceof FolderListItem) {
// 处理文件夹名称：根文件夹替换为“移动到上级文件夹”，普通文件夹用原始名称
String folderName = (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context
.getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
// 调用列表项的bind方法，设置文件夹名称
// 读取当前游标中的文件夹ID，判断是否为根文件夹
long folderId = cursor.getLong(ID_COLUMN);
String folderName;
// 根文件夹特殊处理：替换展示文本；普通文件夹使用原始名称
if (folderId == Notes.ID_ROOT_FOLDER) {
folderName = context.getString(R.string.menu_move_parent_folder);
} else {
folderName = cursor.getString(NAME_COLUMN);
}
// 调用自定义视图的绑定方法，将处理后的文件夹名称设置到文本控件
((FolderListItem) view).bind(folderName);
}
}
/**
* 工具方法：根据列表位置获取文件夹名称（适配根文件夹规则）
* 用于外部（如弹窗逻辑）快速获取指定位置的文件夹名称，无需手动解析Cursor
* @param context 应用上下文（加载根文件夹的显示文本）
* @param position 列表项位置
* @return String：处理后的文件夹名称（根文件夹为“移动到上级文件夹”）
* 对外提供的工具方法：根据列表位置获取对应的文件夹名称
* 封装价值：外部调用方无需操作游标，直接传入位置即可获取名称，隐藏游标操作细节，解耦调用逻辑
* 业务规则：与bindView保持完全一致，根文件夹返回「移动到上级文件夹」，保证数据一致性
* @param context 上下文对象，用于加载根文件夹的业务文本
* @param position 列表中的目标位置索引，从0开始
* @return String 处理后的文件夹展示名称
*/
public String getFolderName(Context context, int position) {
// 获取指定位置的Cursor
// 根据位置获取对应的游标对象，游标已自动定位到对应行
Cursor cursor = (Cursor) getItem(position);
// 同bindView逻辑：根文件夹替换名称，普通文件夹用原始名称
return (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context
.getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
long folderId = cursor.getLong(ID_COLUMN);
// 根文件夹判断与名称适配，逻辑与bindView完全一致
return folderId == Notes.ID_ROOT_FOLDER ? context.getString(R.string.menu_move_parent_folder)
: cursor.getString(NAME_COLUMN);
}
/**
* 内部类：文件夹列表项自定义布局
* 继承自LinearLayout，核心职责：初始化列表项布局和文本控件，提供名称绑定方法。
* 私有内部类：文件夹列表的自定义子项视图【视图封装核心类】
* 继承：LinearLayout 线性布局，作为子项的根布局
* 设计思想：视图控件封装化，将列表项的布局加载、控件绑定、数据绑定全部封装在内部
* 核心优势：外部无需关心视图内部结构，只需调用bind方法即可完成数据渲染，符合封装原则
* 访问权限：private 私有，仅当前适配器可创建使用，不对外暴露，保证视图安全性
*/
private class FolderListItem extends LinearLayout {
// 文件夹名称文本控件：展示处理后的文件夹名称
// 列表项核心控件：展示文件夹名称的文本控件，全局缓存避免重复查找
private TextView mName;
/**
* 构造方法：初始化列表项布局和控件
* @param context 应用上下文，用于加载布局和查找控件
* 构造方法：初始化自定义列表项视图
* 核心逻辑：加载布局文件 + 绑定内部控件，只执行一次，视图创建时完成初始化
* @param context 上下文对象，用于加载布局资源和查找控件
*/
public FolderListItem(Context context) {
super(context);
// 加载文件夹列表项布局（res/layout/folder_list_item.xml）到当前LinearLayout
// 将文件夹列表项的布局文件，填充到当前的LinearLayout根布局中
inflate(context, R.layout.folder_list_item, this);
// 初始化文件夹名称文本控件
// 查找并缓存文件夹名称文本控件，后续直接复用，提升性能
mName = (TextView) findViewById(R.id.tv_folder_name);
}
/**
* 绑定方法：设置文件夹名称到文本控件
* @param name 处理后的文件夹名称（根文件夹为“移动到上级文件夹”）
* 视图数据绑定方法：为文本控件设置文件夹名称
* 核心作用：作为适配器与自定义视图的通信桥梁，只做单一的文本赋值操作
* @param name 处理后的文件夹展示名称（根文件夹/普通文件夹）
*/
public void bind(String name) {
mName.setText(name);

972
src/Notes-master/src/net/micode/notes/ui/NoteEditActivity.java
View File

File diff suppressed because it is too large Load Diff

277
src/Notes-master/src/net/micode/notes/ui/NoteEditText.java
Unescape View File

@ -14,309 +14,324 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，自定义EditText适配便签编辑的特殊交互逻辑
// 包声明：归属小米便签的UI模块，该类是便签编辑页的核心自定义输入控件
package net.micode.notes.ui;
// 导入安卓上下文类：提供应用运行环境
// 安卓系统上下文：提供应用运行环境与系统服务访问能力
import android.content.Context;
// 导入安卓图形矩形类：用于焦点变化时的区域计算
// 安卓图形矩形类：用于焦点切换时的焦点区域坐标计算与传递
import android.graphics.Rect;
// 导入安卓文本布局类：处理文本的行/列定位（触摸光标定位）
// 安卓文本布局核心类：管理文本的排版、行高、行列定位，核心支撑触摸光标精准定位
import android.text.Layout;
// 导入安卓文本选择类：控制文本光标位置
// 安卓文本选择工具类：用于手动设置文本光标位置、选中文本区域
import android.text.Selection;
// 导入安卓富文本类：处理包含URLSpan的富文本
// 安卓富文本标记接口：标识带格式的文本（如包含链接、颜色的文本），本类核心处理该类型文本
import android.text.Spanned;
// 导入安卓文本工具类：判空等文本操作
// 安卓文本工具类：提供字符串判空、文本处理等安全高效的工具方法
import android.text.TextUtils;
// 导入安卓URLSpan类：处理文本中的链接（电话/网页/邮箱）
// 安卓文本链接样式类：封装文本中的超链接数据，包含链接地址与点击事件
import android.text.style.URLSpan;
// 导入安卓属性集类：自定义View构造参数
// 安卓属性集类：承载布局xml中配置的控件属性，自定义View必备构造参数
import android.util.AttributeSet;
// 导入安卓日志类：输出编辑框相关日志
// 安卓日志工具类：输出编辑框相关的调试日志，便于问题排查
import android.util.Log;
// 导入安卓上下文菜单类：自定义链接的上下文菜单
// 安卓上下文菜单类：构建长按文本弹出的菜单容器
import android.view.ContextMenu;
// 导入安卓按键事件类：处理回车/删除等按键交互
// 安卓按键事件类：封装物理按键/软键盘按键的事件信息，用于监听回车、删除键
import android.view.KeyEvent;
// 导入安卓菜单项类：构建上下文菜单的选项
// 安卓菜单项类：上下文菜单中的单个选项对象
import android.view.MenuItem;
import android.view.MenuItem.OnMenuItemClickListener;
// 导入安卓触摸事件类：处理触摸定位光标
// 安卓触摸事件类：封装屏幕触摸的坐标、动作类型，用于重写触摸定位光标逻辑
import android.view.MotionEvent;
// 导入安卓编辑框类：自定义EditText的父类
// 安卓原生编辑框：本自定义控件的父类，继承所有原生EditText基础能力
import android.widget.EditText;
// 导入小米便签资源类：引用字符串资源（链接菜单文本）
// 小米便签资源类：引用项目中的字符串、图片等资源文件，此处核心用链接菜单的文本资源
import net.micode.notes.R;
// 导入集合类：存储scheme与菜单文本的映射关系
// Java集合类：HashMap存储链接协议与菜单文本的映射关系，实现协议与文案解耦
import java.util.HashMap;
import java.util.Map;
/**
* 便签编辑页自定义EditText类
* 继承自安卓EditText，核心扩展职责：
* 1. 适配便签编辑的按键交互：
* - 删除键：光标在起始位置且非首个编辑框时，回调删除当前编辑框；
* - 回车键：分割文本并回调新增编辑框；
* 2. 自定义触摸事件：精准定位触摸位置的光标，优化富文本编辑体验；
* 3. 处理富文本链接（电话/网页/邮箱）：长按链接弹出自定义上下文菜单，支持跳转；
* 4. 焦点变化回调：编辑框失焦且为空时，回调隐藏相关选项；
* 5. 管理编辑框索引：支持多编辑框的增删交互。
* 小米便签 编辑页核心自定义EditText控件
* 核心定位：继承原生Android EditText，基于便签编辑业务做深度定制扩展，无侵入式修改原生逻辑
* 核心设计原则：重写系统回调方法实现定制化需求，所有扩展逻辑均通过回调接口解耦给上层Activity处理
* 核心扩展能力（六大核心职责）：
* 1. 定制化按键交互：重写回车/删除键逻辑，适配多编辑框联动的核心业务；
* 2. 精准触摸光标定位：修复原生触摸光标偏移问题，优化富文本编辑的触摸体验；
* 3. 富文本链接专属处理：长按识别文本中的链接，弹出自定义上下文菜单并支持一键跳转；
* 4. 焦点状态联动回调：编辑框获焦/失焦时，根据文本是否为空回调上层控制功能按钮显隐；
* 5. 多编辑框索引管理：维护自身在编辑框列表中的索引，支撑增删联动逻辑；
* 6. 完整兼容原生能力：所有重写方法最终都会调用父类实现，保留原生EditText全部功能。
*/
public class NoteEditText extends EditText {
// 日志标签：用于编辑框相关日志输出
// 日志打印的TAG标识：固定值，便于过滤该控件的所有日志信息
private static final String TAG = "NoteEditText";
// 当前编辑框在多编辑框列表中的索引（用于增删回调）
// 核心成员变量：当前编辑框在【多编辑框列表】中的索引值
// 作用：用于向Activity回调增删操作时，标识当前操作的编辑框位置，核心支撑多框联动
private int mIndex;
// 删除键按下前的光标起始位置（用于判断是否触发编辑框删除）
// 核心成员变量：删除键按下瞬间的光标起始位置
// 作用：在onKeyDown中记录、onKeyUp中校验，判断是否触发「删除当前编辑框」的业务逻辑
private int mSelectionStartBeforeDelete;
// 链接Scheme常量：匹配文本中的不同类型链接
private static final String SCHEME_TEL = "tel:" ; // 电话链接前缀
private static final String SCHEME_HTTP = "http:" ; // 网页链接前缀
private static final String SCHEME_EMAIL = "mailto:" ;// 邮箱链接前缀
// ========== 常量区：文本链接的协议头（Scheme）常量 ==========
// 定义安卓原生支持的三大核心链接协议前缀，用于匹配文本中的URLSpan链接类型
private static final String SCHEME_TEL = "tel:"; // 电话链接协议头 → 匹配电话号码链接
private static final String SCHEME_HTTP = "http:"; // 网页链接协议头 → 匹配http/https网页链接
private static final String SCHEME_EMAIL = "mailto:";// 邮箱链接协议头 → 匹配邮件发送链接
/**
* Scheme与上下文菜单文本资源的映射表
* 用于根据链接类型（电话/网页/邮箱）显示对应的菜单文本
* 静态不可变映射表：链接协议头(Scheme) → 上下文菜单文本的资源ID
* 设计模式：静态代码块初始化的常量映射，全局唯一，避免多次创建对象造成内存浪费
* 核心作用：根据识别到的链接协议，自动匹配对应的菜单文本，实现协议与文案的解耦管理
*/
private static final Map<String, Integer> sSchemaActionResMap = new HashMap<String, Integer>();
static {
// 初始化映射关系：Scheme -> 菜单文本资源ID
sSchemaActionResMap.put(SCHEME_TEL, R.string.note_link_tel); // 电话链接 → “拨打电话”
sSchemaActionResMap.put(SCHEME_HTTP, R.string.note_link_web); // 网页链接 → “打开网页”
sSchemaActionResMap.put(SCHEME_EMAIL, R.string.note_link_email);// 邮箱链接 → “发送邮件”
// 初始化映射关系：协议头 → 对应的菜单文本资源ID
sSchemaActionResMap.put(SCHEME_TEL, R.string.note_link_tel); // 电话链接 → 展示「拨打电话」
sSchemaActionResMap.put(SCHEME_HTTP, R.string.note_link_web); // 网页链接 → 展示「打开网页」
sSchemaActionResMap.put(SCHEME_EMAIL, R.string.note_link_email); // 邮箱链接 → 展示「发送邮件」
}
/**
* 编辑框状态变化回调接口
* 由NoteEditActivity实现，处理编辑框的增删、文本变化交互
* 编辑框状态变化 回调接口【核心解耦设计】
* 设计思想：将所有业务逻辑（增删编辑框、控制显隐）完全抽离到接口中，由上层NoteEditActivity实现
* 核心价值：该控件只负责「触发事件」，不负责「处理事件」，彻底解耦UI控件与业务逻辑，符合单一职责
*/
public interface OnTextViewChangeListener {
/**
* 删除当前编辑框的回调
* 触发条件：按下删除键 + 光标在起始位置 + 非首个编辑框
* @param index 当前编辑框的索引
* @param text 当前编辑框的文本内容
* 删除当前编辑框的回调方法
* 触发时机：按下删除键 + 光标在文本起始位 + 当前编辑框不是第一个编辑框
* @param index 当前触发删除的编辑框索引
* @param text 当前编辑框中的文本内容，供上层做数据保存
*/
void onEditTextDelete(int index, String text);
/**
* 新增编辑框的回调
* 触发条件：按下回车键
* @param index 新增编辑框的目标索引（当前索引+1）
* @param text 分割后的文本（回车后的内容）
* 新增编辑框的回调方法
* 触发时机：按下回车键时，自动分割文本并回调上层新增编辑框
* @param index 新增编辑框应该插入的目标索引（当前索引+1）
* @param text 回车光标后的分割文本，作为新增编辑框的初始化内容
*/
void onEditTextEnter(int index, String text);
/**
* 文本变化/焦点变化的回调
* 用于控制编辑框相关选项的显示/隐藏
* 文本/焦点状态变化的回调方法
* 触发时机：编辑框获焦/失焦、文本内容变化时
* @param index 当前编辑框的索引
* @param hasText 是否有文本（true=显示选项，false=隐藏选项）
* @param hasText 当前编辑框是否有文本内容 → true显示功能按钮，false隐藏功能按钮
*/
void onTextChange(int index, boolean hasText);
}
// 编辑框状态变化监听器（由Activity实现）
// 成员变量：回调接口的实例对象，由上层Activity通过set方法注入
private OnTextViewChangeListener mOnTextViewChangeListener;
/**
* 构造方法：初始化单个编辑框（无属性集）
* @param context 应用上下文
* 构造方法一：代码中手动创建控件时调用（无布局属性）
* @param context 应用上下文对象，必传参数
*/
public NoteEditText(Context context) {
super(context, null);
// 默认索引为0（首个编辑框）
mIndex = 0;
mIndex = 0; // 默认索引为0，代表首个编辑框，后续可通过setIndex重新赋值
}
/**
* 设置当前编辑框的索引
* @param index 多编辑框列表中的索引
* 对外提供的设置方法：为当前编辑框绑定在列表中的索引值
* @param index 多编辑框列表中的位置索引
*/
public void setIndex(int index) {
mIndex = index;
}
/**
* 设置编辑框状态变化监听器
* @param listener 实现OnTextViewChangeListener的监听器（通常为NoteEditActivity）
* 对外提供的设置方法：注入状态变化的回调监听器
* @param listener 实现了OnTextViewChangeListener接口的实例（上层Activity）
*/
public void setOnTextViewChangeListener(OnTextViewChangeListener listener) {
mOnTextViewChangeListener = listener;
}
/**
* 构造方法：带属性集的初始化（布局文件引用时调用）
* 构造方法二：布局xml中引用该控件时自动调用（带布局属性）
* 安卓自定义View的标准构造方法，适配布局文件中的属性配置
* @param context 应用上下文
* @param attrs 布局属性集
* @param attrs 布局xml中配置的控件属性集
*/
public NoteEditText(Context context, AttributeSet attrs) {
super(context, attrs, android.R.attr.editTextStyle);
}
/**
* 构造方法：带属性集和默认样式的初始化
* 构造方法三：带默认样式的构造方法，适配主题样式定制场景
* 安卓自定义View的完整构造方法，满足所有创建场景，无业务逻辑，仅做父类调用
* @param context 应用上下文
* @param attrs 布局属性集
* @param defStyle 默认样式
* @param defStyle 默认样式资源ID
*/
public NoteEditText(Context context, AttributeSet attrs, int defStyle) {
super(context, attrs, defStyle);
// TODO Auto-generated constructor stub
}
/**
* 重写触摸事件：精准定位触摸位置的光标
* 核心逻辑：将触摸坐标转换为文本的行/列偏移，设置光标位置
* @param event 触摸事件
* @return boolean：是否消费触摸事件（此处返回父类处理结果）
* 重写触摸事件处理方法：核心优化【触摸光标精准定位】
* 原生EditText痛点：触摸文本时光标位置容易偏移，尤其富文本编辑时体验差
* 本方法核心逻辑：将触摸的屏幕坐标，精准转换为文本的行列偏移量，手动设置光标位置
* @param event 触摸事件对象，包含触摸坐标、动作类型等信息
* @return boolean 事件消费标记：返回父类处理结果，不拦截原生触摸逻辑
*/
@Override
public boolean onTouchEvent(MotionEvent event) {
switch (event.getAction()) {
case MotionEvent.ACTION_DOWN:
// 1. 计算触摸的相对坐标（扣除内边距，加上滚动偏移）
case MotionEvent.ACTION_DOWN: // 只处理「按下」动作，是触摸的起始事件
// 步骤1：计算触摸点的【文本相对坐标】- 修正内边距与滚动偏移的影响
int x = (int) event.getX();
int y = (int) event.getY();
x -= getTotalPaddingLeft();
y -= getTotalPaddingTop();
x += getScrollX();
y += getScrollY();
x -= getTotalPaddingLeft(); // 减去左侧总内边距，得到文本区域内的X坐标
y -= getTotalPaddingTop(); // 减去顶部总内边距，得到文本区域内的Y坐标
x += getScrollX(); // 加上横向滚动偏移，适配文本横向滚动的场景
y += getScrollY(); // 加上纵向滚动偏移，适配文本纵向滚动的场景
// 2. 根据坐标获取文本的行和偏移量
Layout layout = getLayout();
int line = layout.getLineForVertical(y); // 触摸位置的文本行
int off = layout.getOffsetForHorizontal(line, x); // 该行的水平偏移量
// 步骤2：通过文本布局对象，将坐标转换为文本的行列信息
Layout layout = getLayout(); // 获取当前编辑框的文本布局管理器
int line = layout.getLineForVertical(y); // 根据Y坐标获取触摸到的文本行号
int off = layout.getOffsetForHorizontal(line, x); // 根据行号+X坐标获取该行的字符偏移量
// 3. 设置光标到触摸位置
// 步骤3：手动设置光标到精准的触摸位置，核心修复原生偏移问题
Selection.setSelection(getText(), off);
break;
}
// 交给父类处理剩余触摸逻辑（如滑动、长按）
// 必须调用父类方法：保留原生的滑动、长按、双击等所有触摸逻辑，只做增量优化
return super.onTouchEvent(event);
}
/**
* 重写按键按下事件：预处理回车/删除键
* @param keyCode 按键码（KEYCODE_ENTER/KEYCODE_DEL等）
* @param event 按键事件
* @return boolean：是否消费按键事件
* 重写按键按下事件：预处理核心按键（回车/删除），做事件标记，不做业务逻辑处理
* 核心设计：按键按下时「只记录状态」，按键抬起时「执行业务逻辑」，符合安卓按键事件的处理规范
* 原因：按下事件可能有长按重复触发，抬起事件只会触发一次，保证业务逻辑只执行一次
* @param keyCode 按键码：标识按下的是哪个按键（回车/删除/字母等）
* @param event 按键事件对象，包含按键动作、重复次数等信息
* @return boolean 事件消费标记：false=不消费，交给onKeyUp处理；true=消费，拦截后续处理
*/
@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
switch (keyCode) {
case KeyEvent.KEYCODE_ENTER:
// 有监听器时返回false，交给onKeyUp处理（分割文本+新增编辑框）
// 回车键按下：有监听器则返回false，交给onKeyUp处理分割+新增逻辑，无则走原生逻辑
if (mOnTextViewChangeListener != null) {
return false;
}
break;
case KeyEvent.KEYCODE_DEL:
// 记录删除键按下前的光标位置，用于onKeyUp判断是否触发删除编辑框
// 删除键按下：记录此时的光标起始位置，供onKeyUp校验是否触发删除编辑框逻辑
mSelectionStartBeforeDelete = getSelectionStart();
break;
default:
break;
}
// 交给父类处理其他按键逻辑
// 调用父类方法：处理所有其他按键的原生逻辑，无侵入式修改
return super.onKeyDown(keyCode, event);
}
/**
* 重写按键抬起事件：处理回车/删除键的核心交互逻辑
* 重写按键抬起事件：核心业务逻辑处理入口【重中之重】
* 该方法是本控件的核心，集中处理「回车新增编辑框」「删除当前编辑框」两大核心业务逻辑
* 所有业务逻辑执行完毕后，均调用父类方法，保证原生按键功能不受影响
* @param keyCode 按键码
* @param event 按键事件
* @return boolean：是否消费按键事件
* @param event 按键事件对象
* @return boolean 事件消费标记：true=已处理业务逻辑，拦截原生行为；false=未处理，走原生逻辑
*/
@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
switch(keyCode) {
case KeyEvent.KEYCODE_DEL:
// 有监听器时处理删除逻辑
// ========== 删除键抬起：处理「删除编辑框」核心逻辑 ==========
if (mOnTextViewChangeListener != null) {
// 触发条件：光标在起始位置 + 非首个编辑框（索引≠0）
// 触发条件【三重校验，缺一不可】：
// 1. 光标在文本的起始位置（0）；2. 当前编辑框不是第一个编辑框（索引≠0）；3. 有回调监听器
if (0 == mSelectionStartBeforeDelete && mIndex != 0) {
// 回调删除当前编辑框
// 回调上层Activity：执行删除当前编辑框的逻辑，并传递当前文本内容
mOnTextViewChangeListener.onEditTextDelete(mIndex, getText().toString());
return true; // 消费事件，避免父类处理
return true; // 消费事件，避免原生删除逻辑执行，防止文本内容错乱
}
} else {
// 无监听器时输出日志提示
// 无监听器时打印日志，便于调试排查问题
Log.d(TAG, "OnTextViewChangeListener was not seted");
}
break;
case KeyEvent.KEYCODE_ENTER:
// 有监听器时处理回车逻辑
// ========== 回车键抬起：处理「分割文本+新增编辑框」核心逻辑 ==========
if (mOnTextViewChangeListener != null) {
// 获取光标起始位置
int selectionStart = getSelectionStart();
// 分割文本：光标后的内容作为新增编辑框的文本
int selectionStart = getSelectionStart(); // 获取当前光标位置
// 步骤1：分割文本 → 光标后的内容作为新增编辑框的初始化文本
String text = getText().subSequence(selectionStart, length()).toString();
// 保留光标前的内容在当前编辑框
// 步骤2：更新当前编辑框文本 → 只保留光标前的内容，完成文本分割
setText(getText().subSequence(0, selectionStart));
// 回调新增编辑框（索引为当前+1）
// 步骤3：回调上层Activity → 在当前索引+1的位置新增编辑框，并传递分割后的文本
mOnTextViewChangeListener.onEditTextEnter(mIndex + 1, text);
} else {
// 无监听器时输出日志提示
Log.d(TAG, "OnTextViewChangeListener was not seted");
}
break;
default:
break;
}
// 交给父类处理其他按键逻辑
// 调用父类方法：处理其他按键的原生抬起逻辑，兼容所有原生功能
return super.onKeyUp(keyCode, event);
}
/**
* 重写焦点变化事件：回调文本状态（控制选项显示/隐藏）
* @param focused 是否获取焦点
* @param direction 焦点变化方向
* @param previouslyFocusedRect 之前的焦点区域
* 重写焦点变化事件：处理「焦点联动功能按钮显隐」的业务逻辑
* 触发时机：编辑框获取焦点/失去焦点时自动调用
* 核心逻辑：失焦时如果文本为空，回调隐藏功能按钮；其他情况回调显示功能按钮
* 设计亮点：只关心「失焦+空文本」的特殊场景，其他场景统一回调显示，逻辑简洁高效
* @param focused 当前是否获取到焦点：true=获焦，false=失焦
* @param direction 焦点变化的方向，系统传递的参数，无实际业务用途
* @param previouslyFocusedRect 上一个焦点控件的矩形区域，系统传递的参数
*/
@Override
protected void onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) {
if (mOnTextViewChangeListener != null) {
// 失焦且文本为空：回调隐藏选项；否则回调显示选项
// 核心判断：失焦 并且 文本为空 → 回调隐藏按钮；否则回调显示按钮
if (!focused && TextUtils.isEmpty(getText())) {
mOnTextViewChangeListener.onTextChange(mIndex, false);
} else {
mOnTextViewChangeListener.onTextChange(mIndex, true);
}
}
// 交给父类处理焦点变化
// 调用父类方法：执行原生的焦点变化逻辑，如光标显示/隐藏、背景色变化等
super.onFocusChanged(focused, direction, previouslyFocusedRect);
}
/**
* 重写上下文菜单创建方法：自定义链接的上下文菜单
* 核心逻辑：识别选中区域的URLSpan，根据Scheme显示对应的菜单选项，点击触发链接跳转
* @param menu 上下文菜单对象
* 重写上下文菜单创建方法：核心实现「富文本链接的自定义菜单」功能
* 触发时机：长按编辑框中的文本时，系统自动调用该方法创建上下文菜单
* 核心业务逻辑：识别长按区域是否包含链接 → 是则添加自定义链接菜单 → 点击菜单触发链接跳转
* 原生兼容：识别不到链接时，自动调用父类方法创建默认菜单（复制/粘贴/全选等）
* @param menu 系统传入的上下文菜单容器，用于添加自定义菜单项
*/
@Override
protected void onCreateContextMenu(ContextMenu menu) {
// 仅处理富文本（Spanned）类型的文本
// 前置判断：只有文本是【富文本(Spanned)】类型时，才处理链接识别逻辑
if (getText() instanceof Spanned) {
// 获取光标选中的起始/结束位置
// 步骤1：获取当前光标选中的文本区域，兼容正选/反选两种情况
int selStart = getSelectionStart();
int selEnd = getSelectionEnd();
int min = Math.min(selStart, selEnd); // 选中区域的起始位置
int max = Math.max(selStart, selEnd); // 选中区域的结束位置
// 修正选中范围（确保min≤max）
int min = Math.min(selStart, selEnd);
int max = Math.max(selStart, selEnd);
// 获取选中区域内的所有URLSpan（链接）
// 步骤2：从选中区域中提取所有的URLSpan链接对象
final URLSpan[] urls = ((Spanned) getText()).getSpans(min, max, URLSpan.class);
// 仅处理单个链接的情况（避免多链接冲突）
// 步骤3：仅处理「单个链接」的场景，避免多链接冲突，保证菜单的唯一性
if (urls.length == 1) {
// 默认菜单文本资源ID（未知链接）
int defaultResId = 0;
// 匹配链接的Scheme，获取对应的菜单文本
int defaultResId = 0; // 初始化菜单文本资源ID
// 步骤4：遍历协议映射表，匹配当前链接的协议类型，获取对应的菜单文本
for(String schema: sSchemaActionResMap.keySet()) {
if(urls[0].getURL().indexOf(schema) >= 0) {
defaultResId = sSchemaActionResMap.get(schema);
@ -324,23 +339,23 @@ public class NoteEditText extends EditText {
}
}
// 未匹配到已知Scheme：使用“其他链接”文本
// 兜底处理：未匹配到已知协议时，显示「其他链接」的默认文本
if (defaultResId == 0) {
defaultResId = R.string.note_link_other;
}
// 添加菜单选项并设置点击事件
// 步骤5：向菜单中添加自定义选项，并绑定点击事件
menu.add(0, 0, 0, defaultResId).setOnMenuItemClickListener(
new OnMenuItemClickListener() {
public boolean onMenuItemClick(MenuItem item) {
// 触发URLSpan的点击事件（跳转链接：拨打电话/打开网页/发送邮件）
// 核心逻辑：触发URLSpan原生的点击事件 → 自动跳转对应链接（拨打电话/打开网页/发送邮件）
urls[0].onClick(NoteEditText.this);
return true;
return true; // 消费菜单点击事件，避免后续处理
}
});
}
}
// 交给父类创建默认上下文菜单
// 必须调用父类方法：无链接时创建原生默认菜单（复制、粘贴、剪切、选择全部等），完整兼容原生功能
super.onCreateContextMenu(menu);
}
}

325
src/Notes-master/src/net/micode/notes/ui/NoteItemData.java
Unescape View File

@ -14,174 +14,187 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，作为便签列表项的核心数据模型，解析并封装Cursor中的便签数据
// 包声明：归属小米便签UI模块，为列表页提供标准化的便签/文件夹数据模型，封装数据库游标解析逻辑
package net.micode.notes.ui;
// 导入安卓上下文类：用于获取ContentResolver、查询联系人信息
// 安卓上下文：提供系统服务访问能力，用于联系人查询、内容解析器获取
import android.content.Context;
// 导入安卓数据库游标类：存储便签数据库查询结果，作为数据解析源
// 安卓数据库游标：承载数据库查询结果集，是本类核心的数据解析源
import android.database.Cursor;
// 导入安卓文本工具类：处理字符串判空、替换等操作
// 安卓文本工具类：提供字符串判空、文本处理等安全操作方法
import android.text.TextUtils;
// 导入联系人数据类：根据手机号查询联系人名称
// 联系人数据工具类：根据手机号匹配系统通讯录中的联系人姓名
import net.micode.notes.data.Contact;
// 导入便签数据常量类：定义便签类型、特殊文件夹ID（通话记录文件夹）等常量
// 便签核心常量类：定义便签类型、文件夹ID、字段名等全局常量
import net.micode.notes.data.Notes;
// 便签数据库列名常量：数据库表的字段名称枚举，避免硬编码字符串
import net.micode.notes.data.Notes.NoteColumns;
// 导入数据工具类：获取通话记录手机号、格式化数据等
// 便签数据工具类：提供通话记录手机号查询、数据格式化等通用能力
import net.micode.notes.tool.DataUtils;
/**
* 便签列表项核心数据模型类
* 便签列表项核心数据模型类【小米便签核心类】
* 核心定位：MVC架构中的Model层，纯数据载体，无任何UI渲染逻辑
* 核心职责：
* 1. 定义便签数据库查询的投影字段（PROJECTION），指定需要解析的核心字段；
* 2. 从Cursor中解析便签/文件夹的所有核心数据（ID、类型、背景色、时间、摘要等）；
* 3. 适配通话记录项：解析手机号并查询对应的联系人名称；
* 4. 判断当前项在列表中的位置状态（首/尾/唯一项、文件夹后的便签项类型）；
* 5. 提供数据访问方法（getter），封装数据逻辑（如是否有提醒、是否为通话记录）。
* 1. 定义数据库查询的投影字段，精准指定查询列，规避全表查询的性能损耗；
* 2. 从数据库Cursor中解析并封装所有便签/文件夹的业务数据；
* 3. 对通话记录类便签做专属适配，自动关联手机号和联系人名称；
* 4. 智能判断列表项的位置状态，为UI背景样式渲染提供数据支撑；
* 5. 提供只读的getter方法和业务判断方法，对外屏蔽数据细节，保证数据安全；
* 设计原则：单一职责 + 完全封装 + 只读数据 + 业务内聚，解耦性极强
*/
public class NoteItemData {
/**
* 数据库查询投影数组：指定需要解析的便签核心字段，减少查询冗余
* 覆盖便签/文件夹的基础属性、时间属性、关联属性（小部件、文件夹）、扩展属性（附件、提醒）
* 数据库查询投影数组：指定本次查询需要返回的数据库列
* 投影设计原则：按需查询，只获取业务需要的字段，减少内存占用和IO开销
* 字段覆盖：便签/文件夹的基础属性、时间属性、关联属性、扩展属性四大类
*/
static final String [] PROJECTION = new String [] {
NoteColumns.ID, // 0: 便签/文件夹唯一ID
NoteColumns.ALERTED_DATE, // 1: 提醒时间戳（0表示无提醒）
NoteColumns.BG_COLOR_ID, // 2: 背景色ID
NoteColumns.CREATED_DATE, // 3: 创建时间戳
NoteColumns.HAS_ATTACHMENT, // 4: 是否有附件（0=无，1=有）
NoteColumns.MODIFIED_DATE, // 5: 最后修改时间戳
NoteColumns.NOTES_COUNT, // 6: 文件夹内便签数量（仅文件夹有效）
NoteColumns.PARENT_ID, // 7: 父文件夹ID（根文件夹为Notes.ID_ROOT_FOLDER）
NoteColumns.SNIPPET, // 8: 便签摘要/文件夹名称
NoteColumns.TYPE, // 9: 类型（Notes.TYPE_NOTE/TYPE_FOLDER/TYPE_SYSTEM）
NoteColumns.WIDGET_ID, // 10: 关联的小部件ID（无效为AppWidgetManager.INVALID_APPWIDGET_ID）
NoteColumns.WIDGET_TYPE, // 11: 关联的小部件类型（2x/4x，对应Notes.TYPE_WIDGET_2X/4X）
static final String[] PROJECTION = new String[]{
NoteColumns.ID, // 0: 便签/文件夹的唯一主键ID
NoteColumns.ALERTED_DATE, // 1: 提醒时间戳（0代表无提醒）
NoteColumns.BG_COLOR_ID, // 2: 背景色ID，用于列表项背景着色
NoteColumns.CREATED_DATE, // 3: 创建时间戳，UTC毫秒值
NoteColumns.HAS_ATTACHMENT, // 4: 是否包含附件 0-无 1-有（图片/音频等）
NoteColumns.MODIFIED_DATE, // 5: 最后修改时间戳，列表页优先展示该时间
NoteColumns.NOTES_COUNT, // 6: 文件夹内包含的便签数量，仅文件夹类型有效
NoteColumns.PARENT_ID, // 7: 父文件夹ID，根目录为Notes.ID_ROOT_FOLDER
NoteColumns.SNIPPET, // 8: 便签内容摘要/文件夹名称，短文本展示用
NoteColumns.TYPE, // 9: 数据类型，区分便签/文件夹/系统项
NoteColumns.WIDGET_ID, // 10: 关联的桌面小部件ID，无效则为默认值
NoteColumns.WIDGET_TYPE // 11: 关联小部件尺寸类型 2x/4x
};
// 投影数组对应的列索引常量：简化Cursor取值，避免硬编码索引
private static final int ID_COLUMN = 0; // 便签/文件夹ID列索引
private static final int ALERTED_DATE_COLUMN = 1; // 提醒时间列索引
private static final int BG_COLOR_ID_COLUMN = 2; // 背景色ID列索引
private static final int CREATED_DATE_COLUMN = 3; // 创建时间列索引
private static final int HAS_ATTACHMENT_COLUMN = 4; // 是否有附件列索引
private static final int MODIFIED_DATE_COLUMN = 5; // 最后修改时间列索引
private static final int NOTES_COUNT_COLUMN = 6; // 文件夹内便签数量列索引
private static final int PARENT_ID_COLUMN = 7; // 父文件夹ID列索引
private static final int SNIPPET_COLUMN = 8; // 摘要/文件夹名称列索引
private static final int TYPE_COLUMN = 9; // 类型列索引
private static final int WIDGET_ID_COLUMN = 10; // 小部件ID列索引
private static final int WIDGET_TYPE_COLUMN = 11; // 小部件类型列索引
// 核心数据字段：与投影数组一一对应
private long mId; // 便签/文件夹唯一ID
private long mAlertDate; // 提醒时间戳（>0表示有提醒）
private int mBgColorId; // 背景色ID（用于列表项背景渲染）
private long mCreatedDate; // 创建时间戳
private boolean mHasAttachment; // 是否有附件（图片/音频等）
private long mModifiedDate; // 最后修改时间戳（用于列表项时间展示）
private int mNotesCount; // 文件夹内便签数量（仅TYPE_FOLDER有效）
private long mParentId; // 父文件夹ID（通话记录项为Notes.ID_CALL_RECORD_FOLDER）
private String mSnippet; // 便签摘要/文件夹名称（清理了勾选标记后的纯文本）
private int mType; // 类型（Notes.TYPE_NOTE/TYPE_FOLDER/TYPE_SYSTEM）
private int mWidgetId; // 关联的小部件ID（无效为INVALID_APPWIDGET_ID）
private int mWidgetType; // 关联的小部件类型（2x/4x）
private String mName; // 通话记录项的联系人名称（无则显示手机号）
private String mPhoneNumber; // 通话记录项的手机号（仅父ID为通话记录文件夹有效）
// 列表位置状态字段：用于适配列表项背景渲染
private boolean mIsLastItem; // 是否为列表最后一项
private boolean mIsFirstItem; // 是否为列表第一项
private boolean mIsOnlyOneItem; // 是否为列表唯一一项
private boolean mIsOneNoteFollowingFolder; // 是否为文件夹后的唯一便签项
private boolean mIsMultiNotesFollowingFolder;// 是否为文件夹后的多个便签项的第一项
/**
* 投影数组列索引常量：与PROJECTION数组字段一一对应
* 设计目的：彻底避免硬编码数字索引，提升代码可读性+可维护性
* 核心价值：修改投影数组字段顺序时，仅需同步修改此处索引，无需改动业务解析代码
*/
private static final int ID_COLUMN = 0;
private static final int ALERTED_DATE_COLUMN = 1;
private static final int BG_COLOR_ID_COLUMN = 2;
private static final int CREATED_DATE_COLUMN = 3;
private static final int HAS_ATTACHMENT_COLUMN = 4;
private static final int MODIFIED_DATE_COLUMN = 5;
private static final int NOTES_COUNT_COLUMN = 6;
private static final int PARENT_ID_COLUMN = 7;
private static final int SNIPPET_COLUMN = 8;
private static final int TYPE_COLUMN = 9;
private static final int WIDGET_ID_COLUMN = 10;
private static final int WIDGET_TYPE_COLUMN = 11;
// ===================== 核心业务数据字段 - 与投影数组一一映射 =====================
// 访问规则：全部私有，仅通过getter方法访问，无setter，数据只读，保证一致性
private long mId; // 便签/文件夹唯一ID，数据库主键
private long mAlertDate; // 提醒时间戳，>0表示该便签设置了提醒
private int mBgColorId; // 背景色ID，对应预设的颜色值，列表项渲染用
private long mCreatedDate; // 便签创建时间戳
private boolean mHasAttachment; // 是否包含附件，数据库int转Java布尔值，贴合业务语义
private long mModifiedDate; // 最后修改时间戳，列表页展示的核心时间字段
private int mNotesCount; // 文件夹内便签数量，仅TYPE_FOLDER类型有效
private long mParentId; // 父文件夹ID，通话记录便签固定为通话记录文件夹ID
private String mSnippet; // 便签纯文本摘要/文件夹名称，已清理勾选标记
private int mType; // 数据类型：Notes.TYPE_NOTE/文件夹/系统项
private int mWidgetId; // 关联桌面小部件ID，无效则为INVALID_APPWIDGET_ID
private int mWidgetType; // 关联小部件尺寸类型，2x/4x两种规格
// ===================== 通话记录专属扩展字段 =====================
private String mName; // 通话记录联系人姓名，无则显示手机号
private String mPhoneNumber; // 通话记录对应的手机号，仅通话便签有值
// ===================== 列表位置状态字段 - 纯UI渲染支撑 =====================
// 作用：标记当前项在列表中的位置，用于适配不同的背景样式（圆角/分割线/边距等）
private boolean mIsLastItem; // 是否为列表最后一条数据
private boolean mIsFirstItem; // 是否为列表第一条数据
private boolean mIsOnlyOneItem; // 是否为列表中唯一的一条数据
private boolean mIsOneNoteFollowingFolder; // 文件夹后的唯一一条便签项
private boolean mIsMultiNotesFollowingFolder;// 文件夹后的第一条便签（后续还有更多项）
/**
* 构造方法：从Cursor解析便签/文件夹数据，初始化所有字段
* @param context 应用上下文：用于查询ContentResolver、获取联系人信息
* @param cursor 包含便签数据的Cursor（已移动到目标位置）
* 唯一构造方法：私有化核心初始化逻辑，从Cursor解析所有数据并完成对象初始化
* 设计特点：全参构造，一次性完成所有数据赋值，无空构造，保证对象完整性
* @param context 应用上下文，用于获取内容解析器、查询联系人信息，不可为空
* @param cursor 数据库查询结果游标，已移动到目标行，不可为空/已关闭
*/
public NoteItemData(Context context, Cursor cursor) {
// 1. 解析Cursor核心字段：与投影数组索引一一对应
// 第一步：解析数据库核心字段，与投影数组索引一一对应，基础数据初始化
mId = cursor.getLong(ID_COLUMN);
mAlertDate = cursor.getLong(ALERTED_DATE_COLUMN);
mBgColorId = cursor.getInt(BG_COLOR_ID_COLUMN);
mCreatedDate = cursor.getLong(CREATED_DATE_COLUMN);
// 转换int为boolean：0=无附件，>0=有附件
mHasAttachment = (cursor.getInt(HAS_ATTACHMENT_COLUMN) > 0) ? true : false;
// 数据库存储为int(0/1)，转换为业务语义更清晰的boolean类型
mHasAttachment = cursor.getInt(HAS_ATTACHMENT_COLUMN) > 0;
mModifiedDate = cursor.getLong(MODIFIED_DATE_COLUMN);
mNotesCount = cursor.getInt(NOTES_COUNT_COLUMN);
mParentId = cursor.getLong(PARENT_ID_COLUMN);
// 解析摘要文本，并清理勾选框标记标签，仅保留纯文本内容，优化展示效果
mSnippet = cursor.getString(SNIPPET_COLUMN);
// 清理摘要中的勾选标记（TAG_CHECKED/TAG_UNCHECKED），仅保留纯文本
mSnippet = mSnippet.replace(NoteEditActivity.TAG_CHECKED, "").replace(
NoteEditActivity.TAG_UNCHECKED, "");
mType = cursor.getInt(TYPE_COLUMN);
mWidgetId = cursor.getInt(WIDGET_ID_COLUMN);
mWidgetType = cursor.getInt(WIDGET_TYPE_COLUMN);
// 2. 初始化通话记录相关字段：仅父ID为通话记录文件夹时解析
// 第二步：通话记录便签专属解析逻辑，仅父文件夹为通话记录文件夹时触发
mPhoneNumber = "";
if (mParentId == Notes.ID_CALL_RECORD_FOLDER) {
// 根据便签ID查询对应的通话记录手机号
// 根据便签ID查询关联的通话手机号
mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId);
// 有手机号时，查询对应的联系人名称
// 手机号非空时，查询系统通讯录匹配联系人姓名
if (!TextUtils.isEmpty(mPhoneNumber)) {
mName = Contact.getContact(context, mPhoneNumber);
// 无联系人名称时，使用手机号作为名称
// 无匹配联系人时，手机号作为联系人名称兜底展示
if (mName == null) {
mName = mPhoneNumber;
}
}
}
// 3. 兜底：联系人名称为空时设为空字符串，避免空指针
// 第三步：空值兜底处理，防止空指针异常，生产级代码必备容错逻辑
if (mName == null) {
mName = "";
}
// 4. 判断当前项在列表中的位置状态（用于背景渲染）
// 第四步：自动判断当前项在列表中的位置状态，为UI渲染提供数据支撑
checkPostion(cursor);
}
/**
* 私有方法：判断当前项在Cursor中的位置状态，初始化位置相关字段
* 核心逻辑：
* 1. 判断是否为首/尾/唯一项；
* 2. 判断普通便签是否为文件夹后的第一项（单个/多个）。
* @param cursor 包含便签数据的Cursor（已移动到目标位置）
* 私有核心方法：解析当前Cursor所在行的列表位置状态，初始化位置标记字段
* 核心作用：为列表项的背景样式提供精准的状态标记，不同位置展示不同样式
* 设计亮点：Cursor位置移动后必回位，防止游标位置错乱导致后续解析异常
* @param cursor 数据库游标，已定位到当前数据行
*/
private void checkPostion(Cursor cursor) {
// 初始化基础位置状态
mIsLastItem = cursor.isLast() ? true : false; // 是否为最后一项
mIsFirstItem = cursor.isFirst() ? true : false; // 是否为第一项
mIsOnlyOneItem = (cursor.getCount() == 1); // 是否为唯一一项
// 初始化文件夹后便签项状态为false
// 初始化基础位置状态：首项、尾项、唯一项
mIsLastItem = cursor.isLast();
mIsFirstItem = cursor.isFirst();
mIsOnlyOneItem = cursor.getCount() == 1;
// 初始化文件夹子项状态为默认值false
mIsMultiNotesFollowingFolder = false;
mIsOneNoteFollowingFolder = false;
// 仅处理普通便签且非第一项的情况：判断是否为文件夹后的便签项
// 核心业务判断：仅处理【普通便签】且【非列表首项】的场景
if (mType == Notes.TYPE_NOTE && !mIsFirstItem) {
// 记录当前位置
int position = cursor.getPosition();
// 移动Cursor到上一项，判断上一项是否为文件夹/系统项
// 记录当前游标位置，用于后续回位，防止位置丢失
int currentPosition = cursor.getPosition();
// 游标上移一行，判断上一项是否为【文件夹】或【系统项】
if (cursor.moveToPrevious()) {
if (cursor.getInt(TYPE_COLUMN) == Notes.TYPE_FOLDER
|| cursor.getInt(TYPE_COLUMN) == Notes.TYPE_SYSTEM) {
// 上一项是文件夹/系统项：判断当前项后是否还有更多项
if (cursor.getCount() > (position + 1)) {
// 有更多项：标记为“文件夹后的多个便签项的第一项”
int prevItemType = cursor.getInt(TYPE_COLUMN);
if (prevItemType == Notes.TYPE_FOLDER || prevItemType == Notes.TYPE_SYSTEM) {
// 上一项是文件夹/系统项 → 当前项是文件夹的子项第一条
if (cursor.getCount() > currentPosition + 1) {
// 后续还有更多数据 → 标记为多子项的第一条
mIsMultiNotesFollowingFolder = true;
} else {
// 无更多项：标记为“文件夹后的唯一便签项”
// 后续无数据 → 标记为文件夹后的唯一子项
mIsOneNoteFollowingFolder = true;
}
}
// 移动Cursor回原位置，避免影响后续操作
// 游标回位到原位置，必须执行，否则会导致后续数据解析错位
if (!cursor.moveToNext()) {
// 移动失败时抛出异常，防止Cursor位置错乱
// 回位失败时主动抛异常，快速定位问题，避免隐性bug
throw new IllegalStateException("cursor move to previous but can't move back");
}
}
@ -189,178 +202,182 @@ public class NoteItemData {
}
/**
* 判断是否为文件夹后的唯一便签项
* @return boolean：true=是，false=否
* 业务判断方法：当前项是否为【文件夹后的唯一便签项】
* @return true-是 false-否
*/
public boolean isOneFollowingFolder() {
return mIsOneNoteFollowingFolder;
}
/**
* 判断是否为文件夹后的多个便签项的第一项
* @return boolean：true=是，false=否
* 业务判断方法：当前项是否为【文件夹后的第一条便签（后续还有项）】
* @return true-是 false-否
*/
public boolean isMultiFollowingFolder() {
return mIsMultiNotesFollowingFolder;
}
/**
* 判断是否为列表最后一项
* @return boolean：true=是，false=否
* 位置判断方法：当前项是否为列表最后一项
* @return true-是 false-否
*/
public boolean isLast() {
return mIsLastItem;
}
/**
* 获取通话记录项的联系人名称（无则返回手机号）
* @return String：联系人名称/手机号
* 数据访问方法：获取通话记录的联系人名称（无则返回手机号）
* @return 联系人姓名/手机号 空则返回空字符串
*/
public String getCallName() {
return mName;
}
/**
* 判断是否为列表第一项
* @return boolean：true=是，false=否
* 位置判断方法：当前项是否为列表第一项
* @return true-是 false-否
*/
public boolean isFirst() {
return mIsFirstItem;
}
/**
* 判断是否为列表唯一一项
* @return boolean：true=是，false=否
* 位置判断方法：当前项是否为列表中唯一的一项
* @return true-是 false-否
*/
public boolean isSingle() {
return mIsOnlyOneItem;
}
/**
* 获取便签/文件夹唯一ID
* @return long：ID值
* 基础数据访问：获取便签/文件夹唯一ID
* @return 数据库主键ID，long类型
*/
public long getId() {
return mId;
}
/**
* 获取提醒时间戳
* @return long：提醒时间戳（>0表示有提醒）
* 基础数据访问：获取提醒时间戳
* @return 提醒时间UTC毫秒值，0表示无提醒
*/
public long getAlertDate() {
return mAlertDate;
}
/**
* 获取创建时间戳
* @return long：创建时间戳
* 基础数据访问：获取创建时间戳
* @return 创建时间UTC毫秒值
*/
public long getCreatedDate() {
return mCreatedDate;
}
/**
* 判断是否有附件
* @return boolean：true=有，false=无
* 业务判断方法：当前便签是否包含附件（图片/音频等）
* @return true-有附件 false-无附件
*/
public boolean hasAttachment() {
return mHasAttachment;
}
/**
* 获取最后修改时间戳
* @return long：最后修改时间戳
* 基础数据访问：获取最后修改时间戳（列表页优先展示）
* @return 修改时间UTC毫秒值
*/
public long getModifiedDate() {
return mModifiedDate;
}
/**
* 获取背景色ID
* @return int：背景色ID（用于列表项背景渲染）
* 基础数据访问：获取背景色ID
* @return 预设的颜色ID值，用于列表项背景渲染
*/
public int getBgColorId() {
return mBgColorId;
}
/**
* 获取父文件夹ID
* @return long：父文件夹ID（通话记录项为Notes.ID_CALL_RECORD_FOLDER）
* 基础数据访问：获取父文件夹ID
* @return 父文件夹主键ID，通话记录为固定常量ID
*/
public long getParentId() {
return mParentId;
}
/**
* 获取文件夹内便签数量（仅TYPE_FOLDER有效）
* @return int：便签数量
* 基础数据访问：获取文件夹内便签数量
* @return 数量值，仅文件夹类型有效，便签类型返回无意义值
*/
public int getNotesCount() {
return mNotesCount;
}
/**
* 兼容方法：获取父文件夹ID（与getParentId逻辑一致，适配外部调用）
* @return long：父文件夹ID
* 兼容适配方法：等价于getParentId()，适配外部旧调用逻辑
* 设计目的：向下兼容，无侵入式修改原有业务代码
* @return 父文件夹主键ID
*/
public long getFolderId () {
public long getFolderId() {
return mParentId;
}
/**
* 获取便签/文件夹类型
* @return int：类型（Notes.TYPE_NOTE/TYPE_FOLDER/TYPE_SYSTEM）
* 基础数据访问：获取数据类型
* @return 类型值：Notes.TYPE_NOTE/文件夹/系统项
*/
public int getType() {
return mType;
}
/**
* 获取关联的小部件类型
* @return int：小部件类型（2x/4x，对应Notes.TYPE_WIDGET_2X/4X）
* 基础数据访问：获取关联小部件类型
* @return 小部件尺寸类型 2x/4x
*/
public int getWidgetType() {
return mWidgetType;
}
public int getWidgetType() {
return mWidgetType;
}
/**
* 获取关联的小部件ID
* @return int：小部件ID（无效为AppWidgetManager.INVALID_APPWIDGET_ID）
* 基础数据访问：获取关联小部件ID
* @return 小部件ID，无效则为INVALID_APPWIDGET_ID
*/
public int getWidgetId() {
return mWidgetId;
}
public int getWidgetId() {
return mWidgetId;
}
/**
* 获取清理后的便签摘要/文件夹名称
* @return String：纯文本摘要/名称
* 基础数据访问：获取清理后的纯文本摘要/文件夹名称
* @return 无勾选标记的纯文本短内容
*/
public String getSnippet() {
return mSnippet;
}
/**
* 判断是否有提醒
* @return boolean：true=有提醒（mAlertDate>0），false=无提醒
* 核心业务判断方法：当前便签是否设置了提醒
* 封装细节：屏蔽「时间戳判0」的技术细节，对外提供业务语义
* @return true-有提醒 false-无提醒
*/
public boolean hasAlert() {
return (mAlertDate > 0);
return mAlertDate > 0;
}
/**
* 判断是否为通话记录项
* @return boolean：true=父ID为通话记录文件夹且有手机号，false=否
* 核心业务判断方法：当前项是否为【通话记录便签】
* 判断条件：父文件夹是通话记录文件夹 + 手机号非空，双重校验保证准确性
* @return true-通话记录便签 false-普通便签/文件夹
*/
public boolean isCallRecord() {
return (mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber));
return mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber);
}
/**
* 静态工具方法：从Cursor中获取便签类型
* 适配外部（如NotesListAdapter）快速获取类型，无需创建NoteItemData实例
* @param cursor 包含便签数据的Cursor（已移动到目标位置）
* @return int：便签类型（Notes.TYPE_NOTE/TYPE_FOLDER/TYPE_SYSTEM）
* 静态工具方法：无需创建对象，快速从Cursor获取便签类型
* 性能优化点：避免为了单个字段创建完整对象实例，适配列表适配器高频调用场景
* 对外赋能：给外部适配器提供轻量级的类型查询能力
* @param cursor 数据库游标，已定位到目标行
* @return 便签类型值
*/
public static int getNoteType(Cursor cursor) {
return cursor.getInt(TYPE_COLUMN);

884
src/Notes-master/src/net/micode/notes/ui/NotesListActivity.java
View File

File diff suppressed because it is too large Load Diff

236
src/Notes-master/src/net/micode/notes/ui/NotesListAdapter.java
Unescape View File

@ -14,151 +14,170 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，作为便签列表页的核心适配器，绑定Cursor数据到列表项
// 包声明：小米便签 核心UI模块，该包承载应用所有可视化交互页面及配套适配器，本类为列表页核心数据适配桥梁
package net.micode.notes.ui;
// 导入安卓上下文类：提供应用运行环境
// -------------------------- 安卓系统核心依赖包 - 上下文/数据库/日志/视图/适配器能力 --------------------------
// 安卓应用全局上下文：提供资源访问、视图创建、数据解析等基础能力，适配器必备依赖
import android.content.Context;
// 导入安卓数据库游标类：存储便签数据库查询结果
// 安卓数据库游标核心类：封装数据库查询结果集，承载便签数据表的查询数据，列表展示的核心数据来源
import android.database.Cursor;
// 导入安卓日志类：输出适配器相关日志（异常/调试）
// 安卓系统日志工具类：输出适配器运行的调试/错误日志，便于问题定位与线上排查
import android.util.Log;
// 导入安卓视图相关类：创建/绑定列表项视图
// 安卓视图体系核心类：视图创建、视图容器的核心父类，适配列表项的创建与挂载
import android.view.View;
import android.view.ViewGroup;
// 导入安卓Cursor适配器类：适配Cursor数据的列表适配器基类
// 安卓游标适配器基类：专为Cursor数据设计的列表适配器，封装数据绑定、视图复用、数据变化监听等核心能力，本类的核心父类
import android.widget.CursorAdapter;
// 导入便签数据常量类：定义便签类型、特殊ID（根文件夹）等常量
// -------------------------- 小米便签业务层核心依赖 - 数据常量/集合工具 --------------------------
// 小米便签数据层核心常量类：定义便签/文件夹/小部件的类型、特殊ID、业务状态等全局核心常量
import net.micode.notes.data.Notes;
// 导入集合相关类：管理选中项的状态、统计选中数量
// Java集合框架相关类：封装选中项状态的存储、遍历、统计，支撑批量选择模式的核心逻辑
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
/**
* 便签列表页核心适配器类
* 继承自安卓CursorAdapter，核心职责：
* 1. 将便签数据库的Cursor数据绑定到自定义列表项（NotesListItem）；
* 2. 管理列表的选择模式（批量操作）：维护选中项状态、全选/取消全选、统计选中数量；
* 3. 提取选中项的核心信息（便签ID、关联的小部件属性）；
* 4. 监听数据变化，实时更新普通便签的总数。
* 小米便签 列表页核心数据适配器
* <p>
* 继承安卓系统{CursorAdapter}游标适配器，隶属于MVC架构的UI层适配桥梁，是{NotesListActivity}与数据库/Cursor数据、{NotesListItem}列表项之间的核心纽带；
* 核心设计定位：封装Cursor数据库数据与列表项视图的绑定逻辑，统一管理列表的展示规则、选择模式、数据变化监听，解耦列表页的业务逻辑与数据渲染逻辑；
* 核心业务职责：创建并复用自定义列表项视图、将Cursor数据映射为业务模型并绑定至列表项、完整支撑批量选择模式的所有操作（单选/全选/取消全选/选中状态维护）、
* 统计选中项数据与普通便签总数、提取选中项的小部件关联属性、监听数据库数据变化并实时刷新视图；
* 技术实现特点：基于安卓原生CursorAdapter实现视图复用，提升列表滑动性能；通过HashMap维护选中项状态，保证选择操作的高效性；
* 封装数据统计与业务属性提取逻辑，对外提供简洁的调用接口；自动监听数据库数据变化，保证视图与数据的一致性。
* </p>
*/
public class NotesListAdapter extends CursorAdapter {
// 日志标签：用于适配器相关日志输出，便于问题定位
/** 日志常量标签：适配器相关日志的统一标识，便于日志过滤与问题定位 */
private static final String TAG = "NotesListAdapter";
// 应用上下文：用于创建列表项、解析Cursor数据
/** 应用上下文对象：用于创建列表项视图、解析业务数据，全局复用避免多次创建 */
private Context mContext;
// 选中项状态映射：Key=列表项位置，Value=是否选中（选择模式下）
/** 选中项状态映射容器：核心数据结构，Key=列表项的索引位置，Value=该位置的选中状态，支撑选择模式的核心存储 */
private HashMap<Integer, Boolean> mSelectedIndex;
// 普通便签总数：仅统计TYPE_NOTE类型的项，用于判断是否全选
/** 普通便签数量统计：仅统计{Notes.TYPE_NOTE}类型的项，排除文件夹/通话记录等类型，用于全选状态的判定依据 */
private int mNotesCount;
// 选择模式标记：true=批量选择模式，false=普通浏览模式
/** 选择模式状态标记：true=开启批量选择模式（批量操作），false=关闭选择模式（普通浏览），控制列表项勾选框的显隐 */
private boolean mChoiceMode;
/**
* 内部静态类：存储便签关联的小部件属性
* 用于批量操作时，提取选中便签绑定的小部件ID和类型
* 内部静态数据载体类：便签关联的桌面小部件属性封装
* 核心设计目的：批量操作场景下，统一封装选中便签所绑定的桌面小部件核心属性，便于后续同步更新小部件数据，
* 静态类设计减少内存开销，无上下文引用避免内存泄漏
*/
public static class AppWidgetAttribute {
public int widgetId; // 小部件唯一标识ID
public int widgetType; // 小部件类型（2x/4x，对应Notes.TYPE_WIDGET_2X/4X）
/** 小部件系统唯一标识ID：桌面小部件的注册ID，用于精准定位目标小部件 */
public int widgetId;
/** 小部件类型标识：区分2x/4x两种尺寸的便签小部件，对应{Notes.TYPE_WIDGET_2X}/{Notes.TYPE_WIDGET_4X} */
public int widgetType;
};
/**
* 构造方法：初始化适配器核心参数
* @param context 应用上下文，传递给父类并保存
* 构造方法：适配器的初始化入口，完成核心成员变量的初始化配置
* 核心初始化逻辑：调用父类构造方法完成基础配置、初始化选中状态映射容器、保存上下文引用、重置普通便签统计数，
* 初始无绑定Cursor，后续通过{changeCursor}方法动态绑定数据库查询结果
* @param context 应用上下文对象，传递至父类并全局保存
*/
public NotesListAdapter(Context context) {
// 父类构造：上下文+初始Cursor（null，后续通过changeCursor设置）
// 父类构造：传入上下文+空Cursor，Cursor数据后续动态绑定，保证初始化灵活性
super(context, null);
// 初始化选中项状态映射（空HashMap）
// 初始化选中项状态映射容器，空HashMap保证初始无选中项
mSelectedIndex = new HashMap<Integer, Boolean>();
// 保存上下文引用
// 保存应用上下文引用，供后续视图创建与数据解析使用
mContext = context;
// 初始化普通便签总数为0
// 重置普通便签统计数量为0，初始无数据状态
mNotesCount = 0;
}
/**
* 重写创建新视图方法：创建便签列表项视图
* @param context 应用上下文
* @param cursor 当前位置的Cursor（未使用，仅遵循父类接口）
* @param parent 列表项的父容器（ListView）
* @return View：新创建的NotesListItem自定义列表项
* 重写父类核心方法：创建新的列表项视图
* 执行时机：列表首次加载、滑动时需要创建新视图的场景，遵循安卓视图复用机制
* 核心逻辑：创建自定义的{NotesListItem}列表项视图并返回，该方法仅负责视图创建，不负责数据绑定
* @param context 应用上下文对象
* @param cursor 当前位置的数据库游标（本方法未使用，仅遵循父类接口规范）
* @param parent 列表项的父容器，即承载所有列表项的ListView
* @return View 创建完成的、未绑定数据的自定义列表项视图
*/
@Override
public View newView(Context context, Cursor cursor, ViewGroup parent) {
// 创建自定义列表项视图（NotesListItem）
// 创建小米便签自定义列表项视图，作为列表的最小展示单元
return new NotesListItem(context);
}
/**
* 重写绑定视图方法：将Cursor数据绑定到列表项UI
* @param view 要绑定的列表项视图（NotesListItem）
* @param context 应用上下文
* @param cursor 当前位置的Cursor，包含便签数据
* 重写父类核心方法：数据与视图的绑定核心实现
* 执行时机：列表首次加载、视图复用、数据变化刷新时调用，是适配器的核心业务方法
* 核心逻辑：将指定位置的Cursor数据库数据，解析为业务数据模型{NoteItemData}，并调用列表项的绑定方法，
* 完成数据渲染、选择模式适配、选中状态赋值，实现「数据→模型→视图」的完整映射
* @param view 待绑定数据的列表项视图，为{NotesListItem}类型，支持视图复用
* @param context 应用上下文对象
* @param cursor 当前列表位置的数据库游标，封装了该位置的完整便签数据
*/
@Override
public void bindView(View view, Context context, Cursor cursor) {
// 仅处理NotesListItem类型的视图（防止类型错误）
// 类型安全校验：仅处理自定义的NotesListItem视图，防止视图类型错误导致崩溃
if (view instanceof NotesListItem) {
// 根据Cursor创建便签数据模型（NoteItemData）
// 将Cursor数据库数据解析为业务数据模型，封装所有展示所需的业务字段
NoteItemData itemData = new NoteItemData(context, cursor);
// 调用列表项的bind方法：绑定数据+适配选择模式+设置选中状态
// 调用列表项的核心绑定方法，完成数据渲染+选择模式适配+选中状态赋值
((NotesListItem) view).bind(context, itemData, mChoiceMode,
isSelectedItem(cursor.getPosition()));
}
}
/**
* 设置指定位置列表项的选中状态
* @param position 列表项位置
* @param checked 是否选中
* 公开业务方法：设置指定位置列表项的选中状态
* 核心作用：单选操作的核心接口，支持选择模式下的单个列表项勾选/取消勾选，
* 更新状态后主动通知列表刷新视图，保证选中状态的实时展示
* @param position 待设置状态的列表项索引位置
* @param checked 目标选中状态，true=勾选，false=取消勾选
*/
public void setCheckedItem(final int position, final boolean checked) {
// 更新选中项状态映射
// 更新选中状态映射容器，保存当前位置的选中状态
mSelectedIndex.put(position, checked);
// 通知ListView数据变化，刷新UI
// 通知列表数据发生变化，触发视图刷新，展示最新的选中状态
notifyDataSetChanged();
}
/**
* 判断当前是否为选择模式
* @return boolean：true=选择模式，false=普通模式
* 公开查询方法：获取当前列表的选择模式状态
* @return boolean true=处于批量选择模式，false=处于普通浏览模式
*/
public boolean isInChoiceMode() {
return mChoiceMode;
}
/**
* 设置选择模式
* 公开业务方法：开启/关闭列表的批量选择模式
* 核心逻辑：切换模式时自动清空所有选中状态，避免模式切换后残留选中标记，保证视图展示的一致性，
* 是选择模式的总开关接口
* @param mode true=开启选择模式，false=关闭选择模式
*/
public void setChoiceMode(boolean mode) {
// 清空原有选中项状态（切换模式时重置选择）
// 清空所有选中项状态，重置选择容器为初始状态
mSelectedIndex.clear();
// 更新选择模式标记
// 更新选择模式标记，控制后续视图绑定的逻辑分支
mChoiceMode = mode;
}
/**
* 全选/取消全选操作
* 仅对普通便签（TYPE_NOTE）生效，文件夹不参与选择
* @param checked true=全选，false=取消全选
* 公开业务方法：全选/取消全选的批量操作
* 核心规则：仅对{Notes.TYPE_NOTE}类型的普通便签生效，文件夹/通话记录等特殊类型不参与选择，
* 避免用户误操作系统特殊项，保证业务数据的安全性
* @param checked true=执行全选操作，false=执行取消全选操作
*/
public void selectAll(boolean checked) {
// 获取当前绑定的Cursor
// 获取当前绑定的数据库游标，遍历所有列表项数据
Cursor cursor = getCursor();
// 遍历所有列表项
for (int i = 0; i < getCount(); i++) {
// 移动Cursor到当前位置
// 移动游标到当前列表项的位置，匹配对应数据
if (cursor.moveToPosition(i)) {
// 仅处理普通便签类型的项
// 仅处理普通便签类型，过滤文件夹等非选择项
if (NoteItemData.getNoteType(cursor) == Notes.TYPE_NOTE) {
// 设置当前位置的选中状态
// 批量设置当前位置的选中状态
setCheckedItem(i, checked);
}
}
@ -166,22 +185,24 @@ public class NotesListAdapter extends CursorAdapter {
}
/**
* 获取选中项的便签ID集合
* @return HashSet<Long>：选中的便签ID集合（过滤根文件夹ID）
* 公开业务方法：获取所有选中项的便签ID集合
* 核心作用：批量删除/批量移动等业务操作的核心数据来源，返回去重的选中便签ID，
* 自动过滤根文件夹等无效ID并输出日志提示，保证业务数据的有效性
* @return HashSet<Long> 所有选中便签的ID集合，无选中项则返回空集合
*/
public HashSet<Long> getSelectedItemIds() {
HashSet<Long> itemSet = new HashSet<Long>();
// 遍历所有选中的位置
// 遍历所有已记录的选中状态位置
for (Integer position : mSelectedIndex.keySet()) {
// 仅处理选中状态为true的项
// 仅处理选中状态为true的有效项
if (mSelectedIndex.get(position) == true) {
// 获取当前位置的便签ID
// 获取当前位置对应的便签ID
Long id = getItemId(position);
// 过滤根文件夹ID（无效项，日志提示）
// 过滤系统根文件夹的无效ID，避免业务操作异常
if (id == Notes.ID_ROOT_FOLDER) {
Log.d(TAG, "Wrong item id, should not happen");
} else {
// 添加有效ID到集合
// 将有效ID添加至结果集合
itemSet.add(id);
}
}
@ -190,32 +211,34 @@ public class NotesListAdapter extends CursorAdapter {
}
/**
* 获取选中项关联的小部件属性集合
* @return HashSet<AppWidgetAttribute>：选中项的小部件属性集合（无效时返回null）
* 公开业务方法：获取所有选中项关联的小部件属性集合
* 核心作用：批量操作后同步更新桌面小部件的核心数据来源，提取选中便签所绑定的小部件ID与类型，
* 自动校验游标有效性，异常时输出错误日志并返回null，保证数据安全性
* @return HashSet<AppWidgetAttribute> 选中项的小部件属性集合，无效数据时返回null
*/
public HashSet<AppWidgetAttribute> getSelectedWidget() {
HashSet<AppWidgetAttribute> itemSet = new HashSet<AppWidgetAttribute>();
// 遍历所有选中的位置
// 遍历所有已记录的选中状态位置
for (Integer position : mSelectedIndex.keySet()) {
// 仅处理选中状态为true的项
// 仅处理选中状态为true的有效项
if (mSelectedIndex.get(position) == true) {
// 获取当前位置的Cursor
// 获取当前位置对应的数据库游标
Cursor c = (Cursor) getItem(position);
if (c != null) {
// 创建小部件属性对象
// 创建小部件属性对象，封装核心数据
AppWidgetAttribute widget = new AppWidgetAttribute();
// 根据Cursor创建便签数据模型
// 将游标数据解析为业务模型，提取小部件关联属性
NoteItemData item = new NoteItemData(mContext, c);
// 提取小部件ID和类型
widget.widgetId = item.getWidgetId();
widget.widgetType = item.getWidgetType();
// 添加到集合
// 添加至结果集合
itemSet.add(widget);
/**
* 此处不关闭Cursor：Cursor由适配器统一管理，外部关闭会导致数据异常
* 重要说明：此处不主动关闭Cursor
* Cursor由CursorAdapter统一管理生命周期，外部关闭会导致列表数据异常、游标越界等崩溃问题
*/
} else {
// 无效Cursor，输出错误日志并返回null
// 游标无效时输出错误日志，返回null标记异常状态
Log.e(TAG, "Invalid cursor");
return null;
}
@ -225,17 +248,17 @@ public class NotesListAdapter extends CursorAdapter {
}
/**
* 统计选中项的数量
* @return int：选中的普通便签数量
* 公开业务方法：统计当前选中的普通便签数量
* 核心作用：列表页展示选中数量、判定全选状态的核心依据，仅统计选中状态为true的有效项，保证计数准确性
* @return int 选中的普通便签数量，无选中项则返回0
*/
public int getSelectedCount() {
// 获取所有选中状态值
// 获取所有已记录的选中状态值集合
Collection<Boolean> values = mSelectedIndex.values();
// 无状态值时返回0
if (null == values) {
return 0;
}
// 遍历状态值，统计选中（true）的数量
// 遍历状态值，统计选中状态为true的项数
Iterator<Boolean> iter = values.iterator();
int count = 0;
while (iter.hasNext()) {
@ -247,61 +270,68 @@ public class NotesListAdapter extends CursorAdapter {
}
/**
* 判断是否全选
* @return boolean：true=全选（选中数>0且等于普通便签总数），false=未全选
* 公开业务方法：判断当前是否处于「全选」状态
* 核心判定规则：选中数量大于0 且 选中数量等于列表中普通便签的总数，双条件保证判定准确性，
* 避免无数据时误判为全选、选中部分项时误判为全选
* @return boolean true=已全选所有普通便签，false=未全选/无选中项/无普通便签
*/
public boolean isAllSelected() {
int checkedCount = getSelectedCount();
// 选中数非0且等于普通便签总数，判定为全选
return (checkedCount != 0 && checkedCount == mNotesCount);
}
/**
* 判断指定位置的列表项是否选中
* @param position 列表项位置
* @return boolean：true=选中，false=未选中（包括状态为null的情况）
* 公开查询方法：判断指定位置的列表项是否被选中
* 核心规则：未记录状态的位置默认视为「未选中」，避免空指针异常，保证业务逻辑的健壮性
* @param position 待查询的列表项索引位置
* @return boolean true=该位置已选中，false=该位置未选中/无状态记录
*/
public boolean isSelectedItem(final int position) {
// 状态为null时视为未选中
// 状态容器中无该位置记录时，默认返回未选中
if (null == mSelectedIndex.get(position)) {
return false;
}
// 返回当前位置的选中状态
// 返回该位置的实际选中状态
return mSelectedIndex.get(position);
}
/**
* 重写内容变化回调方法：数据变化时更新普通便签总数
* 当Cursor数据（便签数据库）发生变化时触发
* 重写父类回调方法：监听数据库内容变化的核心回调
* 触发时机：当适配器绑定的数据库表数据发生增/删/改操作时，系统自动调用该方法
* 核心逻辑：执行父类默认刷新逻辑后，重新统计普通便签数量，保证全选状态判定的准确性，
* 是视图与数据库数据一致性的核心保障
*/
@Override
protected void onContentChanged() {
super.onContentChanged();
// 重新计算普通便签总数
// 数据变化后重新统计普通便签数量
calcNotesCount();
}
/**
* 重写更换Cursor方法：更换Cursor后更新普通便签总数
* @param cursor 新的Cursor
* 重写父类核心方法：更换适配器绑定的游标数据
* 触发时机：列表页切换文件夹、刷新数据、查询条件变更时主动调用
* 核心逻辑：执行父类游标更换逻辑后，重新统计普通便签数量，适配新数据集的全选判定规则
* @param cursor 新的数据库游标，封装了新的查询结果集
*/
@Override
public void changeCursor(Cursor cursor) {
super.changeCursor(cursor);
// 重新计算普通便签总数
// 更换游标后重新统计普通便签数量
calcNotesCount();
}
/**
* 私有方法：计算列表中普通便签（TYPE_NOTE）的总数
* 用于判断全选状态，仅统计有效Cursor的普通便签项
* 私有核心方法：统计列表中普通便签的总数
* 核心业务规则：仅遍历统计{Notes.TYPE_NOTE}类型的项，排除文件夹、通话记录等非便签类型，
* 自动校验游标有效性，异常时终止统计并输出日志，保证计数准确性，是全选功能的核心支撑方法
*/
private void calcNotesCount() {
// 重置总数为0
// 重置计数为0，避免累计统计错误
mNotesCount = 0;
// 遍历所有列表项
// 遍历适配器绑定的所有列表项数据
for (int i = 0; i < getCount(); i++) {
// 获取当前位置的Cursor
// 获取当前位置对应的数据库游标
Cursor c = (Cursor) getItem(i);
if (c != null) {
// 仅统计普通便签类型的项
@ -309,7 +339,7 @@ public class NotesListAdapter extends CursorAdapter {
mNotesCount++;
}
} else {
// 无效Cursor，输出错误日志并终止计算
// 游标无效时输出错误日志，终止统计避免数据异常
Log.e(TAG, "Invalid cursor");
return;
}

153
src/Notes-master/src/net/micode/notes/ui/NotesListItem.java
Unescape View File

@ -14,64 +14,70 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，负责便签列表页的单个列表项渲染
// 包声明：小米便签 核心UI模块，该包承载应用所有可视化交互页面及自定义UI组件，本类为列表页核心子项组件
package net.micode.notes.ui;
// 导入安卓上下文类：提供应用运行环境（资源访问、样式加载）
// -------------------------- 安卓系统核心依赖包 - 上下文/视图/布局/基础控件能力 --------------------------
// 安卓应用全局上下文：提供资源访问、样式加载、布局渲染等基础能力，自定义控件必备依赖
import android.content.Context;
// 导入安卓日期工具类：格式化相对时间（如“1分钟前”“昨天”）
// 安卓系统时间格式化工具类：提供相对时间格式化能力，将时间戳转为「几分钟前/昨天/上周」等友好展示格式
import android.text.format.DateUtils;
// 导入安卓视图类：控制控件可见性、状态
// 安卓视图体系核心父类：控制控件的显示/隐藏、可见性状态、视图属性等核心操作
import android.view.View;
// 导入安卓复选框类：选择模式下展示的勾选框
// 安卓复选框控件：列表选择模式下的核心勾选组件，用于便签的批量操作场景
import android.widget.CheckBox;
// 导入安卓图片视图类：展示提醒图标、通话记录图标
// 安卓图片展示控件：承载提醒图标、通话记录图标等所有图片类展示内容
import android.widget.ImageView;
// 导入安卓线性布局类：作为列表项的根布局
// 安卓线性布局容器：本类的父布局，提供横向/纵向的线性控件排列能力，作为列表项的根布局
import android.widget.LinearLayout;
// 导入安卓文本视图类：展示标题、时间、通话名称等文本
// 安卓文本展示控件：承载所有文本类展示内容，如标题、时间、通话名称等
import android.widget.TextView;
// 导入小米便签资源类：引用布局、字符串、样式、图片等资源
// -------------------------- 小米便签业务层核心依赖 - 资源/数据/工具适配 --------------------------
// 小米便签资源常量类：统一管理布局、字符串、样式、图片等所有本地资源ID引用
import net.micode.notes.R;
// 导入便签数据常量类：定义便签/文件夹类型、特殊ID（通话记录文件夹）等常量
// 小米便签数据层核心常量类：定义便签/文件夹的类型、特殊ID、业务状态等全局核心常量
import net.micode.notes.data.Notes;
// 导入数据工具类：格式化便签摘要文本
// 小米便签数据格式化工具类：封装便签摘要文本的格式化处理逻辑，统一文本展示规则
import net.micode.notes.tool.DataUtils;
// 导入资源解析工具类：获取便签/文件夹的背景资源ID
// 小米便签资源解析工具类：封装便签/文件夹的背景资源适配逻辑，提供不同状态的背景资源获取能力
import net.micode.notes.tool.ResourceParser.NoteItemBgResources;
/**
* 便签列表项自定义布局类
* 继承自LinearLayout，作为便签列表页（NotesListActivity）的单个列表项容器，核心职责：
* 1. 初始化列表项的UI控件（提醒图标、标题、时间、通话名称、勾选框）；
* 2. 根据便签数据类型（普通便签/文件夹/通话记录文件夹/通话记录项）渲染差异化UI；
* 3. 适配选择模式（显示/隐藏勾选框）；
* 4. 根据便签状态（是否有提醒、背景色、列表位置）设置背景和图标。
* 小米便签 列表页核心自定义列表项组件
* <p>
* 继承安卓系统{LinearLayout}线性布局，隶属于MVC架构的UI层视图组件，是{NotesListActivity}列表页的最小展示单元；
* 核心设计定位：作为便签列表的标准化子项容器，封装所有列表项的UI渲染逻辑、数据绑定逻辑、样式适配逻辑，解耦列表页与子项展示逻辑；
* 核心业务职责：统一承载所有类型便签/文件夹的差异化展示、选择模式的UI适配、提醒状态的图标展示、背景样式的精准适配、通话记录的专属布局；
* 技术实现特点：基于数据驱动视图的设计思想，通过统一的bind方法完成数据与视图的绑定，内置多分支逻辑适配不同业务类型，
* 封装背景设置的复杂逻辑，对外提供简洁的调用与数据获取接口，是列表页高性能展示的核心基础组件。
* </p>
*/
public class NotesListItem extends LinearLayout {
// 提醒/类型图标：展示闹钟提醒、通话记录等图标
/** 功能图标控件：展示闹钟提醒、通话记录等业务类型图标，不同场景展示对应功能标识 */
private ImageView mAlert;
// 标题文本：展示便签摘要、文件夹名称（含数量）、通话记录标题
/** 主标题文本控件：核心文本展示区，适配展示便签摘要、文件夹名称+数量、通话记录内容等核心信息 */
private TextView mTitle;
// 时间文本：展示便签最后修改的相对时间（如“5分钟前”）
/** 时间文本控件：展示便签/文件夹的最后修改时间，统一格式化为相对友好时间格式 */
private TextView mTime;
// 通话名称文本：仅通话记录项展示来电/去电联系人名称
/** 通话名称文本控件：通话记录专属展示区，仅通话记录项展示来电/去电的联系人名称，其他场景隐藏 */
private TextView mCallName;
// 列表项绑定的便签数据模型
/** 数据模型载体：保存当前列表项绑定的业务数据，用于后续视图刷新与数据获取 */
private NoteItemData mItemData;
// 选择模式下的勾选框：批量操作时展示
/** 选择复选框控件：批量操作模式专属控件，用于勾选待操作的便签，非选择模式下默认隐藏 */
private CheckBox mCheckBox;
/**
* 构造方法：初始化列表项布局和控件
* @param context 应用上下文，用于加载布局和查找控件
* 构造方法：自定义控件的初始化入口
* 核心初始化逻辑：加载列表项的基础布局文件，完成所有子控件的视图绑定，为后续数据绑定做准备；
* 该方法仅在列表项创建时执行一次，保证控件初始化的性能最优
* @param context 应用上下文对象，用于加载布局资源与查找子控件
*/
public NotesListItem(Context context) {
super(context);
// 加载列表项布局（res/layout/note_item.xml）到当前LinearLayout
// 加载列表项的基础布局文件，将xml布局解析为当前线性布局的子视图
inflate(context, R.layout.note_item, this);
// 初始化各UI控件
// 绑定布局内所有子控件，通过ID精准获取并赋值给成员变量
mAlert = (ImageView) findViewById(R.id.iv_alert_icon);
mTitle = (TextView) findViewById(R.id.tv_title);
mTime = (TextView) findViewById(R.id.tv_time);
@ -80,14 +86,16 @@ public class NotesListItem extends LinearLayout {
}
/**
* 核心绑定方法：将便签数据绑定到列表项UI，适配不同类型/状态的展示逻辑
* @param context 应用上下文，用于资源/样式加载
* @param data 列表项对应的便签数据模型（NoteItemData）
* @param choiceMode 是否为选择模式（批量操作）
* @param checked 选择模式下是否勾选当前项
* 核心公开绑定方法：数据与视图的统一绑定入口，列表项所有展示逻辑的核心处理方法
* 核心业务能力：接收业务数据模型，根据数据类型/状态/模式完成所有视图的差异化渲染，包括控件显隐、文本赋值、图标切换、样式适配、勾选状态设置；
* 该方法为列表项的核心对外接口，列表页通过调用此方法完成所有子项的内容展示
* @param context 应用上下文，用于资源加载、样式设置、字符串格式化
* @param data 当前列表项对应的业务数据模型，承载所有展示所需的业务字段
* @param choiceMode 是否开启列表选择模式：true=批量操作模式，false=普通浏览模式
* @param checked 选择模式下当前项的勾选状态：true=已勾选，false=未勾选
*/
public void bind(Context context, NoteItemData data, boolean choiceMode, boolean checked) {
// 选择模式且为普通便签：显示勾选框并设置勾选状态；否则隐藏勾选框
// 选择模式适配逻辑：仅普通便签在选择模式下展示勾选框，其他类型/模式均隐藏，防止误操作文件夹
if (choiceMode && data.getType() == Notes.TYPE_NOTE) {
mCheckBox.setVisibility(View.VISIBLE);
mCheckBox.setChecked(checked);
@ -95,26 +103,28 @@ public class NotesListItem extends LinearLayout {
mCheckBox.setVisibility(View.GONE);
}
// 保存当前绑定的数据模型
// 缓存当前绑定的业务数据模型，供后续背景设置与外部数据获取使用
mItemData = data;
// 分支1：通话记录文件夹（特殊ID）
// ===== 分支一：通话记录专属文件夹（系统特殊固定ID），独立的展示样式 =====
if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
mCallName.setVisibility(View.GONE); // 隐藏通话名称
mAlert.setVisibility(View.VISIBLE); // 显示类型图标
mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); // 设置标题主样式
// 标题：通话记录文件夹名称 + 文件夹内文件数量（格式化）
mCallName.setVisibility(View.GONE);
mAlert.setVisibility(View.VISIBLE);
mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem);
// 标题展示规则：固定文件夹名称 + 文件夹内的通话记录数量，格式化展示
mTitle.setText(context.getString(R.string.call_record_folder_name)
+ context.getString(R.string.format_folder_files_count, data.getNotesCount()));
mAlert.setImageResource(R.drawable.call_record); // 设置通话记录图标
// 展示通话记录专属图标，明确业务类型标识
mAlert.setImageResource(R.drawable.call_record);
}
// 分支2：通话记录项（父ID为通话记录文件夹）
// ===== 分支二：通话记录子项（归属通话记录文件夹），通话类专属展示样式 =====
else if (data.getParentId() == Notes.ID_CALL_RECORD_FOLDER) {
mCallName.setVisibility(View.VISIBLE); // 显示通话名称
mCallName.setText(data.getCallName()); // 设置通话联系人名称
mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem); // 设置标题次要样式
mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); // 格式化显示便签摘要
// 有提醒：显示闹钟图标；无提醒：隐藏图标
mCallName.setVisibility(View.VISIBLE);
mCallName.setText(data.getCallName());
mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem);
// 标题展示格式化后的通话记录摘要内容，保证文本展示的规范性
mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet()));
// 提醒状态适配：有闹钟提醒则展示闹钟图标，无则隐藏
if (data.hasAlert()) {
mAlert.setImageResource(R.drawable.clock);
mAlert.setVisibility(View.VISIBLE);
@ -122,23 +132,22 @@ public class NotesListItem extends LinearLayout {
mAlert.setVisibility(View.GONE);
}
}
// 分支3：普通文件夹/普通便签（非通话记录相关）
// ===== 分支三：普通业务类型（普通文件夹/普通便签），通用展示样式 =====
else {
mCallName.setVisibility(View.GONE); // 隐藏通话名称
mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); // 设置标题主样式
mCallName.setVisibility(View.GONE);
mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem);
// 子分支3.1：普通文件夹
// 子分支1：普通文件夹类型，展示文件夹名称+包含便签数量
if (data.getType() == Notes.TYPE_FOLDER) {
// 标题：文件夹名称 + 文件夹内文件数量（格式化）
mTitle.setText(data.getSnippet()
+ context.getString(R.string.format_folder_files_count,
data.getNotesCount()));
mAlert.setVisibility(View.GONE); // 隐藏图标
mAlert.setVisibility(View.GONE);
}
// 子分支3.2：普通便签
// 子分支2：普通便签类型，展示便签核心摘要内容
else {
mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); // 格式化显示便签摘要
// 有提醒：显示闹钟图标；无提醒：隐藏图标
mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet()));
// 提醒状态适配：有闹钟提醒展示闹钟图标，无则隐藏
if (data.hasAlert()) {
mAlert.setImageResource(R.drawable.clock);
mAlert.setVisibility(View.VISIBLE);
@ -147,47 +156,51 @@ public class NotesListItem extends LinearLayout {
}
}
}
// 设置最后修改时间：格式化为相对时间（如“1小时前”）
// 统一设置最后修改时间：将时间戳转为「几分钟前/昨天」等相对友好的时间格式，提升用户体验
mTime.setText(DateUtils.getRelativeTimeSpanString(data.getModifiedDate()));
// 根据数据模型设置列表项背景
// 根据当前绑定的数据模型，完成列表项背景样式的精准适配
setBackground(data);
}
/**
* 私有方法：根据便签数据设置列表项背景
* 核心逻辑：区分普通便签/文件夹，普通便签再根据列表位置（首/中/尾/单独项）适配不同背景
* @param data 列表项对应的便签数据模型
* 私有核心方法：列表项背景样式的统一适配处理
* 核心业务逻辑：封装复杂的背景适配规则，区分普通便签与文件夹的不同背景策略；
* 普通便签根据列表中的位置（首项/中项/尾项/单独项）+ 背景色ID，匹配对应的背景资源；
* 文件夹统一使用固定背景，简化适配逻辑，保证列表样式的统一性与美观性
* @param data 当前列表项绑定的业务数据模型，提供背景色ID、类型、列表位置等适配所需字段
*/
private void setBackground(NoteItemData data) {
// 获取便签背景色ID
// 获取当前数据模型的背景色标识ID，作为背景资源匹配的核心依据
int id = data.getBgColorId();
// 普通便签：根据列表位置适配不同背景资源
// 普通便签的背景适配逻辑：多场景精准匹配，保证列表连贯的视觉效果
if (data.getType() == Notes.TYPE_NOTE) {
if (data.isSingle() || data.isOneFollowingFolder()) {
// 单独项/文件夹下唯一项：使用“单独项”背景
// 场景1：列表中唯一项 / 文件夹下的唯一项 → 使用独立完整背景
setBackgroundResource(NoteItemBgResources.getNoteBgSingleRes(id));
} else if (data.isLast()) {
// 列表最后一项：使用“最后项”背景
// 场景2：列表中的最后一项 → 使用底部收尾样式背景
setBackgroundResource(NoteItemBgResources.getNoteBgLastRes(id));
} else if (data.isFirst() || data.isMultiFollowingFolder()) {
// 列表第一项/文件夹下多项的第一项：使用“第一项”背景
// 场景3：列表中的第一项 / 文件夹下的多项首项 → 使用顶部起始样式背景
setBackgroundResource(NoteItemBgResources.getNoteBgFirstRes(id));
} else {
// 列表中间项：使用“普通项”背景
// 场景4：列表中的中间项 → 使用标准连贯样式背景
setBackgroundResource(NoteItemBgResources.getNoteBgNormalRes(id));
}
}
// 文件夹（含通话记录文件夹）：使用文件夹统一背景
// 文件夹类型统一适配逻辑：所有文件夹（含通话记录文件夹）使用固定背景样式
else {
setBackgroundResource(NoteItemBgResources.getFolderBgRes());
}
}
/**
* 获取当前列表项绑定的便签数据模型
* @return NoteItemData：当前项的数据模型
* 公开数据获取方法：获取当前列表项绑定的业务数据模型
* 核心作用：为列表页提供数据访问接口，列表页可通过该方法获取选中项、点击项的业务数据，完成跳转/删除/编辑等后续操作；
* 是视图组件与业务逻辑之间的核心数据桥梁
* @return NoteItemData 当前列表项绑定的完整业务数据模型
*/
public NoteItemData getItemData() {
return mItemData;

570
src/Notes-master/src/net/micode/notes/ui/NotesPreferenceActivity.java
Unescape View File

@ -14,149 +14,176 @@
* limitations under the License.
*/
// 包声明：归属小米便签的UI模块，负责便签应用的设置页面逻辑
// 包声明：小米便签 核心UI业务模块，承载应用所有可视化交互页面，本类为应用设置页核心实现
package net.micode.notes.ui;
// 导入安卓账号相关类：用于Google账号的获取与管理
// -------------------------- 安卓系统核心依赖包 - 账号/页面/弹窗/广播/数据存储能力 --------------------------
// 安卓账号体系核心类：封装Google账号的账号名、账号类型等基础信息载体
import android.accounts.Account;
// 安卓账号管理核心服务类：系统级账号管理器，负责设备上所有账号的查询、管理、鉴权等操作
import android.accounts.AccountManager;
// 导入安卓ActionBar类：设置顶部导航栏（返回按钮）
// 安卓顶部导航栏核心类：配置页面导航样式、返回按钮、标题等ActionBar相关属性
import android.app.ActionBar;
// 导入安卓对话框类：用于账号选择、更改确认等弹窗
// 安卓系统弹窗核心类：构建标准化的对话框，承载账号选择、确认提示等交互弹窗
import android.app.AlertDialog;
// 导入安卓广播接收器类：接收同步服务的状态广播
// 安卓广播核心组件：监听系统/应用内部的广播消息，本类用于监听同步服务状态变更广播
import android.content.BroadcastReceiver;
// 导入安卓内容值类：用于更新便签数据库的同步相关字段
// 安卓数据封装类：封装键值对数据，用于ContentProvider执行数据库字段更新操作
import android.content.ContentValues;
// 导入安卓上下文类：提供应用运行环境
// 安卓应用全局上下文：提供资源访问、组件通信、偏好设置读写等核心基础能力
import android.content.Context;
// 导入安卓对话框点击监听类：处理弹窗选项的点击事件
// 安卓对话框交互核心接口：监听弹窗选项的点击事件，处理用户选择逻辑
import android.content.DialogInterface;
// 导入安卓意图类：用于页面跳转、广播过滤
// 安卓组件通信核心类：封装页面跳转指令、广播指令、参数传递，实现跨组件通信
import android.content.Intent;
// 导入安卓意图过滤器类：筛选需要接收的广播
// 安卓广播过滤核心类：筛选需要监听的广播动作，精准匹配目标广播消息
import android.content.IntentFilter;
// 导入安卓共享偏好设置类：存储便签的偏好配置（同步账号、最后同步时间等）
// 安卓轻量级存储核心类：键值对持久化存储，用于保存应用偏好配置，非数据库存储
import android.content.SharedPreferences;
// 导入安卓Bundle类：保存Activity状态
// 安卓页面状态存储类：保存页面销毁重建时的临时数据，保证页面状态不丢失
import android.os.Bundle;
// 导入安卓偏好设置相关类：构建设置页面的UI组件
// 安卓系统偏好设置组件：构建设置页面的标准化UI控件，封装设置项的展示与交互逻辑
import android.preference.Preference;
import android.preference.Preference.OnPreferenceClickListener;
import android.preference.PreferenceActivity;
import android.preference.PreferenceCategory;
// 导入安卓文本工具类：处理字符串判空、相等判断
// 安卓文本工具类：封装字符串判空、内容对比等常用操作，避免空指针与硬编码判断
import android.text.TextUtils;
// 导入安卓日期格式化类：格式化最后同步时间
// 安卓系统日期格式化工具类：标准化格式化时间戳为指定样式的字符串，适配多语言展示
import android.text.format.DateFormat;
// 导入安卓布局填充类：加载自定义布局（设置页面header、对话框标题等）
// 安卓布局加载核心类：将xml布局文件解析为Java视图对象，加载自定义布局与弹窗样式
import android.view.LayoutInflater;
// 导入安卓菜单相关类：处理ActionBar的菜单点击
// 安卓页面菜单核心类：配置ActionBar右侧菜单的创建与点击事件处理
import android.view.Menu;
import android.view.MenuItem;
// 导入安卓视图相关类：操作按钮、文本框等UI控件
// 安卓视图体系核心类：操作所有可视化控件的父类，实现控件的点击、赋值、显隐等操作
import android.view.View;
import android.widget.Button;
import android.widget.TextView;
// 导入安卓吐司类：显示操作结果提示
// 安卓轻量级提示组件：展示短时操作结果提示，无焦点不阻塞用户交互
import android.widget.Toast;
// 导入小米便签资源类：引用字符串、布局、偏好设置xml等资源
// -------------------------- 小米便签业务层核心依赖 - 资源/数据/同步服务 --------------------------
// 小米便签资源常量类：统一管理布局、字符串、颜色、样式等所有本地资源ID引用
import net.micode.notes.R;
// 导入便签数据常量类：定义便签URI、字段等核心常量
// 小米便签数据层核心常量类：定义便签ContentProvider URI、数据表字段、业务常量等核心配置
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.NoteColumns;
// 导入GTask同步服务类：处理便签与Google Task的同步逻辑
// 小米便签核心同步服务类：封装便签与Google Task的双向同步逻辑，提供同步启停、状态查询等核心能力
import net.micode.notes.gtask.remote.GTaskSyncService;
/**
* 便签应用设置页面Activity
* 继承自安卓PreferenceActivity，核心职责：
* 1. 管理Google账号的绑定/切换/移除，支持便签与Google Task同步；
* 2. 提供手动触发同步、取消同步的按钮，展示同步状态和最后同步时间；
* 3. 存储/读取偏好设置（同步账号、最后同步时间、背景色设置等）；
* 4. 接收同步服务的广播，实时刷新同步状态UI；
* 5. 处理设置页面的导航（返回便签列表页）。
* 小米便签 应用核心设置页面Activity
* <p>
* 继承安卓系统{PreferenceActivity}，隶属于MVC架构的UI层核心业务页面，是便签应用的全局配置中心；
* 核心设计定位：统一承载应用所有用户可配置项，聚焦「Google账号绑定与GTask云同步」核心能力，兼顾基础偏好配置；
* 核心业务职责：Google账号的绑定/切换/移除管理、手动同步/取消同步操作、同步状态实时展示、同步时间持久化、
* 偏好配置读写、同步服务广播监听、页面导航与交互反馈，是便签应用云同步能力的唯一配置入口；
* 技术实现特点：通过SharedPreferences实现轻量级配置持久化，通过广播接收器实现同步状态实时刷新，
* 通过异步线程处理数据库更新避免主线程阻塞，通过系统账号管理器实现Google账号的标准化管理。
* </p>
*/
public class NotesPreferenceActivity extends PreferenceActivity {
/** 偏好设置文件名：所有便签偏好配置存储在该文件下 */
/**
* 全局常量：SharedPreferences偏好设置存储文件名，应用所有配置项均持久化存储在该文件中，单文件统一管理
*/
public static final String PREFERENCE_NAME = "notes_preferences";
/** 偏好设置Key：存储当前绑定的Google同步账号名 */
/**
* 全局常量：偏好配置存储键 - 当前绑定的Google同步账号名，核心云同步关联标识
*/
public static final String PREFERENCE_SYNC_ACCOUNT_NAME = "pref_key_account_name";
/** 偏好设置Key：存储最后一次同步的时间戳 */
/**
* 全局常量：偏好配置存储键 - 最后一次同步成功的时间戳，用于展示同步历史记录
*/
public static final String PREFERENCE_LAST_SYNC_TIME = "pref_last_sync_time";
/** 偏好设置Key：控制便签背景色是否随机显示 */
/**
* 全局常量：偏好配置存储键 - 便签背景色随机展示开关，控制新建便签的背景色展示策略
*/
public static final String PREFERENCE_SET_BG_COLOR_KEY = "pref_key_bg_random_appear";
/** 私有偏好设置Key：同步账号相关的偏好分类标识 */
/**
* 私有常量：偏好设置分类标识 - 账号同步相关配置项的分类容器Key，用于页面UI组件定位
*/
private static final String PREFERENCE_SYNC_ACCOUNT_KEY = "pref_sync_account_key";
/** 私有常量：添加账号时的权限过滤Key */
/**
* 私有常量：系统账号过滤标识 - 添加新账号时的权限过滤关键字，用于精准筛选Google账号类型
*/
private static final String AUTHORITIES_FILTER_KEY = "authorities";
/** 账号相关的偏好分类组件：承载账号选择的偏好项 */
/**
* 页面核心控件：账号同步相关的偏好设置分类容器，承载账号选择配置项的父组件
*/
private PreferenceCategory mAccountCategory;
/** 广播接收器：接收GTask同步服务的状态广播（同步中/同步完成） */
/**
* 核心广播接收器：监听GTaskSyncService的同步状态广播，实现同步中/同步完成的UI实时刷新
*/
private GTaskReceiver mReceiver;
/** 原始Google账号数组：用于对比是否新增了账号 */
/**
* 账号缓存数组：存储操作前的设备Google账号列表，用于对比判断是否新增账号
*/
private Account[] mOriAccounts;
/** 标记位：是否触发了添加新账号的操作 */
/**
* 状态标记位：标记是否触发了系统添加账号的操作，用于页面恢复时的账号自动绑定逻辑
*/
private boolean mHasAddedAccount;
/**
* Activity创建时的初始化逻辑
* 核心操作：设置ActionBar、加载偏好设置布局、初始化账号偏好组件、注册同步广播接收器、添加页面header
* @param icicle 保存Activity状态的Bundle
* 重写页面生命周期：页面创建初始化入口方法
* 执行时机：页面第一次被创建时调用，仅执行一次
* 核心初始化逻辑：配置ActionBar导航样式、加载偏好设置页面布局、初始化核心控件、注册同步状态广播接收器、
* 添加页面自定义头部布局，完成页面所有基础初始化工作，为后续交互做准备
* @param icicle 页面状态存储Bundle，恢复重建时的临时数据载体
*/
@Override
protected void onCreate(Bundle icicle) {
super.onCreate(icicle);
/* 使用应用图标作为导航：开启ActionBar的返回按钮 */
/* 配置ActionBar导航：启用左上角返回按钮，跳转回便签列表页 */
getActionBar().setDisplayHomeAsUpEnabled(true);
// 从xml资源加载偏好设置页面的UI结构（res/xml/preferences.xml）
// 从xml资源加载设置页面的标准化偏好配置UI结构，页面主体内容初始化
addPreferencesFromResource(R.xml.preferences);
// 获取账号相关的偏好分类组件
// 根据标识获取账号同步分类容器控件，完成核心控件绑定
mAccountCategory = (PreferenceCategory) findPreference(PREFERENCE_SYNC_ACCOUNT_KEY);
// 初始化同步广播接收器
// 初始化同步状态广播接收器，注册监听同步服务的状态变更广播
mReceiver = new GTaskReceiver();
IntentFilter filter = new IntentFilter();
// 过滤GTask同步服务的广播动作
filter.addAction(GTaskSyncService.GTASK_SERVICE_BROADCAST_NAME);
// 注册广播接收器，监听同步状态变化
registerReceiver(mReceiver, filter);
// 初始化原始账号数组为null
// 初始化账号缓存数组与状态标记位，默认无账号无新增操作
mOriAccounts = null;
// 加载设置页面的header布局并添加到列表顶部
mHasAddedAccount = false;
// 加载自定义页面头部布局并添加至列表顶部，丰富页面视觉层级
View header = LayoutInflater.from(this).inflate(R.layout.settings_header, null);
getListView().addHeaderView(header, null, true);
}
/**
* Activity恢复可见时的逻辑
* 核心操作：检查是否新增了Google账号，自动绑定新账号；刷新设置页面UI
* 重写页面生命周期：页面恢复可见状态回调方法
* 执行时机：页面从后台切回前台、弹窗关闭后、页面创建后首次展示时调用
* 核心业务逻辑：检测是否触发过添加账号操作，若有则自动绑定新增的Google账号；刷新页面所有UI控件状态，
* 保证页面展示的账号信息、同步按钮、同步状态均为最新数据，是页面数据一致性的核心保障
*/
@Override
protected void onResume() {
super.onResume();
// 若触发了添加账号操作，检查是否有新账号并自动绑定
// 检测添加账号标记位，处理新增账号的自动绑定逻辑
if (mHasAddedAccount) {
// 获取当前设备的Google账号列表
Account[] accounts = getGoogleAccounts();
// 对比原始账号数组，判断是否新增了账号
// 对比操作前后的账号数量，判断是否有新账号添加成功
if (mOriAccounts != null && accounts.length > mOriAccounts.length) {
for (Account accountNew : accounts) {
boolean found = false;
// 遍历原始账号，判断新账号是否已存在
// 遍历原始账号列表，过滤已存在的账号
for (Account accountOld : mOriAccounts) {
if (TextUtils.equals(accountOld.name, accountNew.name)) {
found = true;
break;
}
}
// 找到新增账号，自动绑定为同步账号
// 匹配到新增账号，自动完成绑定并终止遍历
if (!found) {
setSyncAccount(accountNew.name);
break;
@ -165,17 +192,18 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
}
// 刷新设置页面的UI（账号偏好、同步按钮、同步状态）
// 统一刷新页面所有UI组件状态，保证数据与视图一致
refreshUI();
}
/**
* Activity销毁时的清理逻辑
* 核心操作：注销广播接收器，防止内存泄漏
* 重写页面生命周期：页面销毁回收资源回调方法
* 执行时机：页面退出、被销毁时调用，仅执行一次
* 核心优化逻辑：注销已注册的广播接收器，释放系统资源，防止内存泄漏，是安卓组件开发的必做优化项
*/
@Override
protected void onDestroy() {
// 注销同步广播接收器
// 安全注销广播接收器，判空避免空指针异常
if (mReceiver != null) {
unregisterReceiver(mReceiver);
}
@ -183,34 +211,34 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 加载账号偏好项
* 核心逻辑：构建账号选择的偏好组件，设置点击事件（选择/更改账号）
* 私有核心方法：加载并初始化账号同步偏好配置项
* 核心业务逻辑：动态构建账号选择配置项，绑定点击事件，实现「未绑定账号展示选择弹窗、已绑定账号展示变更弹窗」的交互逻辑，
* 同步中禁用账号操作防止数据异常，是账号管理能力的核心实现
*/
private void loadAccountPreference() {
// 清空账号分类下的原有偏好项，避免重复添加
// 清空分类容器内原有配置项，避免重复添加导致的UI重复展示问题
mAccountCategory.removeAll();
// 创建账号选择的偏好项
// 新建账号选择偏好配置项，初始化展示文案与交互行为
Preference accountPref = new Preference(this);
// 获取当前绑定的默认同步账号
final String defaultAccount = getSyncAccountName(this);
// 设置偏好项标题和摘要
accountPref.setTitle(getString(R.string.preferences_account_title));
accountPref.setSummary(getString(R.string.preferences_account_summary));
// 设置偏好项点击事件
// 绑定配置项点击事件，处理账号选择与变更的核心交互逻辑
accountPref.setOnPreferenceClickListener(new OnPreferenceClickListener() {
public boolean onPreferenceClick(Preference preference) {
// 同步中不允许更改账号
// 同步中禁止账号操作，防止同步数据与账号信息不一致导致异常
if (!GTaskSyncService.isSyncing()) {
// 未绑定账号：显示账号选择对话框
if (TextUtils.isEmpty(defaultAccount)) {
// 未绑定账号：展示账号选择弹窗，供用户选择绑定
showSelectAccountAlertDialog();
} else {
// 已绑定账号：显示更改账号的确认对话框（提示风险）
// 已绑定账号：展示账号变更确认弹窗，提示风险并提供操作选项
showChangeAccountConfirmAlertDialog();
}
} else {
// 同步中提示无法更改账号
// 同步中操作拦截，展示友好的吐司提示
Toast.makeText(NotesPreferenceActivity.this,
R.string.preferences_toast_cannot_change_account, Toast.LENGTH_SHORT)
.show();
@ -219,25 +247,23 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
});
// 将账号偏好项添加到账号分类组件中
// 将配置项添加至分类容器，完成UI渲染
mAccountCategory.addPreference(accountPref);
}
/**
* 加载同步按钮与同步状态
* 核心逻辑：
* 1. 根据同步状态设置按钮文本（立即同步/取消同步）和点击事件；
* 2. 展示最后同步时间或同步中进度；
* 3. 无绑定账号时禁用同步按钮。
* 私有核心方法：加载并初始化同步按钮与同步状态展示控件
* 核心业务逻辑：根据同步服务的运行状态，动态切换按钮文本与点击事件（立即同步/取消同步）；
* 展示同步进度或最后同步时间；无绑定账号时禁用同步按钮，是同步能力的核心交互入口实现
*/
private void loadSyncButton() {
// 获取同步按钮和最后同步时间文本框
// 获取页面同步按钮与同步状态文本控件，完成视图绑定
Button syncButton = (Button) findViewById(R.id.preference_sync_button);
TextView lastSyncTimeView = (TextView) findViewById(R.id.prefenerece_sync_status_textview);
// 根据同步状态设置按钮状态
// 根据同步服务状态，动态配置按钮行为与文本
if (GTaskSyncService.isSyncing()) {
// 同步中：按钮文本设为“取消同步”，点击触发取消同步
// 同步中状态：按钮文本为取消同步，点击触发同步终止逻辑
syncButton.setText(getString(R.string.preferences_button_sync_cancel));
syncButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
@ -245,7 +271,7 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
});
} else {
// 未同步：按钮文本设为“立即同步”，点击触发同步
// 未同步状态：按钮文本为立即同步，点击触发同步启动逻辑
syncButton.setText(getString(R.string.preferences_button_sync_immediately));
syncButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
@ -253,33 +279,33 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
});
}
// 无绑定账号时禁用同步按钮
// 无绑定账号时禁用同步按钮，避免无账号同步的无效操作
syncButton.setEnabled(!TextUtils.isEmpty(getSyncAccountName(this)));
// 设置最后同步时间/同步进度
// 配置同步状态文本展示逻辑，区分同步中与历史同步记录
if (GTaskSyncService.isSyncing()) {
// 同步中：显示同步进度文本
// 同步中：展示实时同步进度文案
lastSyncTimeView.setText(GTaskSyncService.getProgressString());
lastSyncTimeView.setVisibility(View.VISIBLE);
} else {
// 未同步：获取最后同步时间戳
// 未同步：读取最后同步时间戳，展示格式化的历史同步记录
long lastSyncTime = getLastSyncTime(this);
if (lastSyncTime != 0) {
// 有同步记录：格式化并显示最后同步时间
lastSyncTimeView.setText(getString(R.string.preferences_last_sync_time,
DateFormat.format(getString(R.string.preferences_last_sync_time_format),
lastSyncTime)));
lastSyncTimeView.setVisibility(View.VISIBLE);
} else {
// 无同步记录：隐藏时间文本
// 无同步记录：隐藏状态文本，简化页面展示
lastSyncTimeView.setVisibility(View.GONE);
}
}
}
/**
* 刷新设置页面UI
* 核心操作：重新加载账号偏好项和同步按钮/状态
* 私有统一刷新方法：页面UI状态刷新总入口
* 核心职责：统一调用账号配置项与同步按钮的加载方法，实现页面所有核心控件的状态刷新，
* 简化多处刷新逻辑的调用成本，保证刷新行为的一致性
*/
private void refreshUI() {
loadAccountPreference();
@ -287,203 +313,179 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 显示账号选择对话框
* 核心逻辑：
* 1. 展示当前设备的Google账号列表，支持选择绑定；
* 2. 提供“添加新账号”选项，跳转系统添加账号页面；
* 3. 选择账号后自动绑定为同步账号。
* 私有弹窗方法：展示Google账号选择对话框
* 核心业务逻辑：展示设备上已有的Google账号列表供用户选择绑定；提供添加新账号入口跳转系统设置；
* 选择账号后自动完成绑定并刷新页面，是账号绑定的核心交互弹窗实现
*/
private void showSelectAccountAlertDialog() {
AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
// 加载自定义对话框标题布局
View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null);
TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title);
titleTextView.setText(getString(R.string.preferences_dialog_select_account_title));
TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle);
subtitleTextView.setText(getString(R.string.preferences_dialog_select_account_tips));
dialogBuilder.setCustomTitle(titleView);
// 隐藏默认的PositiveButton（通过单选列表选择账号）
dialogBuilder.setPositiveButton(null, null);
// 获取设备的Google账号列表
Account[] accounts = getGoogleAccounts();
// 获取当前绑定的账号
String defAccount = getSyncAccountName(this);
// 记录当前账号数组，用于后续对比是否新增账号
mOriAccounts = accounts;
// 初始化标记位：未添加新账号
mHasAddedAccount = false;
// 有Google账号时，构建单选列表
if (accounts.length > 0) {
CharSequence[] items = new CharSequence[accounts.length];
final CharSequence[] itemMapping = items;
int checkedItem = -1;
int index = 0;
// 遍历账号，构建列表项并标记当前绑定账号
for (Account account : accounts) {
if (TextUtils.equals(account.name, defAccount)) {
checkedItem = index;
}
items[index++] = account.name;
}
// 设置单选列表，选择后绑定账号并刷新UI
dialogBuilder.setSingleChoiceItems(items, checkedItem,
new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
setSyncAccount(itemMapping[which].toString());
dialog.dismiss();
refreshUI();
}
});
}
// 加载“添加新账号”的视图并添加到对话框
View addAccountView = LayoutInflater.from(this).inflate(R.layout.add_account_text, null);
dialogBuilder.setView(addAccountView);
// 显示对话框
final AlertDialog dialog = dialogBuilder.show();
// 设置“添加新账号”点击事件：跳转系统添加账号页面
addAccountView.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
// 标记触发了添加账号操作
mHasAddedAccount = true;
Intent intent = new Intent("android.settings.ADD_ACCOUNT_SETTINGS");
// 过滤仅显示Google账号添加选项
intent.putExtra(AUTHORITIES_FILTER_KEY, new String[] {
"gmail-ls"
});
// 启动添加账号页面（无返回值）
startActivityForResult(intent, -1);
dialog.dismiss();
}
});
}
private void showSelectAccountAlertDialog() {
AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
// 加载自定义弹窗标题布局，初始化弹窗头部文案
View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null);
TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title);
titleTextView.setText(getString(R.string.preferences_dialog_select_account_title));
TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle);
subtitleTextView.setText(getString(R.string.preferences_dialog_select_account_tips));
dialogBuilder.setCustomTitle(titleView);
dialogBuilder.setPositiveButton(null, null);
// 获取设备上所有Google账号，构建账号选择列表
Account[] accounts = getGoogleAccounts();
String defAccount = getSyncAccountName(this);
// 缓存当前账号列表，用于后续新增账号判断
mOriAccounts = accounts;
mHasAddedAccount = false;
// 存在Google账号时，构建单选列表供用户选择
if (accounts.length > 0) {
CharSequence[] items = new CharSequence[accounts.length];
final CharSequence[] itemMapping = items;
int checkedItem = -1;
int index = 0;
for (Account account : accounts) {
if (TextUtils.equals(account.name, defAccount)) {
checkedItem = index;
}
items[index++] = account.name;
}
// 绑定列表选择事件，选择后完成账号绑定并关闭弹窗
dialogBuilder.setSingleChoiceItems(items, checkedItem,
new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
setSyncAccount(itemMapping[which].toString());
dialog.dismiss();
refreshUI();
}
});
}
// 加载添加新账号的自定义视图，提供账号新增入口
View addAccountView = LayoutInflater.from(this).inflate(R.layout.add_account_text, null);
dialogBuilder.setView(addAccountView);
// 展示弹窗并绑定添加账号点击事件，跳转系统账号添加页面
final AlertDialog dialog = dialogBuilder.show();
addAccountView.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
mHasAddedAccount = true;
Intent intent = new Intent("android.settings.ADD_ACCOUNT_SETTINGS");
intent.putExtra(AUTHORITIES_FILTER_KEY, new String[] {
"gmail-ls"
});
startActivityForResult(intent, -1);
dialog.dismiss();
}
});
}
/**
* 显示更改账号的确认对话框
* 核心逻辑：
* 1. 提示更改账号的风险；
* 2. 提供“更改账号”“移除账号”“取消”三个选项；
* 3. 对应选项触发不同逻辑（选择新账号/移除当前账号）。
* 私有弹窗方法：展示账号变更/移除确认对话框
* 核心业务逻辑：针对已绑定账号的场景，展示风险提示与操作选项（更改账号/移除账号/取消）；
* 处理账号变更与解绑逻辑，是账号管理的核心确认交互弹窗实现
*/
private void showChangeAccountConfirmAlertDialog() {
AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
// 加载自定义对话框标题布局
View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null);
TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title);
// 标题显示当前绑定的账号名
titleTextView.setText(getString(R.string.preferences_dialog_change_account_title,
getSyncAccountName(this)));
TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle);
// 副标题提示更改账号的风险
subtitleTextView.setText(getString(R.string.preferences_dialog_change_account_warn_msg));
dialogBuilder.setCustomTitle(titleView);
// 构建对话框选项：更改账号、移除账号、取消
CharSequence[] menuItemArray = new CharSequence[] {
getString(R.string.preferences_menu_change_account),
getString(R.string.preferences_menu_remove_account),
getString(R.string.preferences_menu_cancel)
};
// 设置选项点击事件
dialogBuilder.setItems(menuItemArray, new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
if (which == 0) {
// 选择“更改账号”：显示账号选择对话框
showSelectAccountAlertDialog();
} else if (which == 1) {
// 选择“移除账号”：清理绑定的账号信息
removeSyncAccount();
refreshUI();
}
// which==2为取消，无操作
}
});
dialogBuilder.show();
}
private void showChangeAccountConfirmAlertDialog() {
AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
// 加载自定义弹窗标题布局，展示当前绑定账号与风险提示
View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null);
TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title);
titleTextView.setText(getString(R.string.preferences_dialog_change_account_title,
getSyncAccountName(this)));
TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle);
subtitleTextView.setText(getString(R.string.preferences_dialog_change_account_warn_msg));
dialogBuilder.setCustomTitle(titleView);
// 构建弹窗操作选项，绑定点击事件处理不同操作逻辑
CharSequence[] menuItemArray = new CharSequence[] {
getString(R.string.preferences_menu_change_account),
getString(R.string.preferences_menu_remove_account),
getString(R.string.preferences_menu_cancel)
};
dialogBuilder.setItems(menuItemArray, new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
if (which == 0) {
// 选择更改账号：跳转账号选择弹窗
showSelectAccountAlertDialog();
} else if (which == 1) {
// 选择移除账号：执行账号解绑逻辑
removeSyncAccount();
refreshUI();
}
}
});
dialogBuilder.show();
}
/**
* 获取设备上的Google账号列表
* @return Account[]：所有类型为“com.google”的账号
* 私有工具方法：获取设备上所有已登录的Google账号列表
* 核心实现：通过系统账号管理器，根据Google账号类型精准筛选，返回纯净的Google账号数组，
* 是账号管理能力的基础数据来源
* @return Account[] 设备上所有com.google类型的账号数组，无账号则返回空数组
*/
private Account[] getGoogleAccounts() {
AccountManager accountManager = AccountManager.get(this);
// 根据账号类型筛选Google账号
return accountManager.getAccountsByType("com.google");
}
/**
* 设置同步账号
* 核心逻辑：
* 1. 更新SharedPreferences存储的账号名；
* 2. 清理最后同步时间；
* 3. 异步清理本地便签的GTask同步相关字段（GTASK_ID、SYNC_ID）；
* 4. 提示设置成功。
* @param account 要绑定的Google账号名
* 私有核心方法：设置当前绑定的Google同步账号
* 核心业务逻辑：更新偏好配置中的账号信息、清空历史同步时间、异步清理本地便签的同步关联字段、
* 展示操作成功提示；账号未变化时不执行任何操作，避免无效处理，是账号绑定的核心业务逻辑实现
* @param account 待绑定的Google账号名
*/
private void setSyncAccount(String account) {
// 账号未变化时不执行操作
if (!getSyncAccountName(this).equals(account)) {
// 获取偏好设置编辑器
SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
SharedPreferences.Editor editor = settings.edit();
// 存储新账号名（空账号则存空字符串）
if (account != null) {
editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, account);
} else {
editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, "");
}
editor.commit();
// 清理最后同步时间
setLastSyncTime(this, 0);
// 异步清理本地便签的GTask同步信息（避免阻塞主线程）
new Thread(new Runnable() {
public void run() {
ContentValues values = new ContentValues();
// 清空GTASK_ID和SYNC_ID
values.put(NoteColumns.GTASK_ID, "");
values.put(NoteColumns.SYNC_ID, 0);
// 更新所有便签的同步字段
getContentResolver().update(Notes.CONTENT_NOTE_URI, values, null, null);
}
}).start();
// 提示账号设置成功
Toast.makeText(NotesPreferenceActivity.this,
getString(R.string.preferences_toast_success_set_accout, account),
Toast.LENGTH_SHORT).show();
}
}
private void setSyncAccount(String account) {
// 账号未发生变化时，直接返回避免无效操作
if (!getSyncAccountName(this).equals(account)) {
// 写入偏好配置，持久化存储绑定的账号名
SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
SharedPreferences.Editor editor = settings.edit();
if (account != null) {
editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, account);
} else {
editor.putString(PREFERENCE_SYNC_ACCOUNT_NAME, "");
}
editor.commit();
// 账号变更后清空历史同步时间，保证同步记录的准确性
setLastSyncTime(this, 0);
// 异步线程清理本地便签的同步关联字段，避免主线程阻塞导致页面卡顿
new Thread(new Runnable() {
public void run() {
ContentValues values = new ContentValues();
values.put(NoteColumns.GTASK_ID, "");
values.put(NoteColumns.SYNC_ID, 0);
getContentResolver().update(Notes.CONTENT_NOTE_URI, values, null, null);
}
}).start();
// 展示账号绑定成功的友好提示
Toast.makeText(NotesPreferenceActivity.this,
getString(R.string.preferences_toast_success_set_accout, account),
Toast.LENGTH_SHORT).show();
}
}
/**
* 移除同步账号
* 核心逻辑：
* 1. 从SharedPreferences中移除账号名和最后同步时间；
* 2. 异步清理本地便签的GTask同步相关字段；
* 私有核心方法：移除当前绑定的Google同步账号，完成账号解绑
* 核心业务逻辑：清理偏好配置中的账号名与同步时间、异步清理本地便签的同步关联字段，
* 彻底解除本地便签与原账号的云同步关联，是账号解绑的核心业务逻辑实现
*/
private void removeSyncAccount() {
// 获取偏好设置编辑器
// 读取偏好配置并清理账号与同步时间相关配置项
SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
SharedPreferences.Editor editor = settings.edit();
// 移除同步账号名
if (settings.contains(PREFERENCE_SYNC_ACCOUNT_NAME)) {
editor.remove(PREFERENCE_SYNC_ACCOUNT_NAME);
}
// 移除最后同步时间
if (settings.contains(PREFERENCE_LAST_SYNC_TIME)) {
editor.remove(PREFERENCE_LAST_SYNC_TIME);
}
editor.commit();
// 异步清理本地便签的GTask同步信息
// 异步线程清理本地便签的同步关联字段，释放系统资源
new Thread(new Runnable() {
public void run() {
ContentValues values = new ContentValues();
@ -495,9 +497,10 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 静态工具方法：获取当前绑定的同步账号名
* @param context 应用上下文
* @return String：绑定的账号名（无则返回空字符串）
* 公开静态工具方法：获取当前绑定的Google同步账号名
* 全局通用能力：供应用其他组件调用，获取同步账号信息，解耦配置读取逻辑
* @param context 应用上下文，用于访问偏好配置
* @return String 当前绑定的账号名，无绑定则返回空字符串
*/
public static String getSyncAccountName(Context context) {
SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
@ -506,9 +509,10 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 静态工具方法：设置最后同步时间戳
* @param context 应用上下文
* @param time 同步时间戳（毫秒）
* 公开静态工具方法：设置最后一次同步的时间戳
* 全局通用能力：供同步服务调用，持久化同步完成时间，解耦配置写入逻辑
* @param context 应用上下文，用于访问偏好配置
* @param time 同步完成的时间戳（毫秒值）
*/
public static void setLastSyncTime(Context context, long time) {
SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
@ -519,9 +523,10 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 静态工具方法：获取最后同步时间戳
* @param context 应用上下文
* @return long：最后同步时间戳（无则返回0）
* 公开静态工具方法：获取最后一次同步的时间戳
* 全局通用能力：供应用其他组件调用，读取同步历史时间，解耦配置读取逻辑
* @param context 应用上下文，用于访问偏好配置
* @return long 最后同步时间戳，无记录则返回0
*/
public static long getLastSyncTime(Context context) {
SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
@ -530,21 +535,24 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 内部广播接收器类：接收GTask同步服务的状态广播
* 核心职责：同步状态变化时刷新UI，展示同步进度
* 内部私有广播接收器类：监听GTask同步服务的状态变更广播
* 核心设计定位：页面与同步服务的通信桥梁，无耦合监听同步状态变化；
* 核心职责：接收同步中/同步完成的广播消息，触发页面UI刷新，展示实时同步进度，
* 是同步状态实时更新的核心实现，生命周期与宿主页面一致
*/
private class GTaskReceiver extends BroadcastReceiver {
/**
* 接收广播时的处理逻辑
* @param context 广播上下文
* @param intent 携带同步状态的意图
* 重写广播接收回调方法：处理同步服务的状态广播
* 核心逻辑：接收到广播后立即刷新页面UI，同步中时更新进度文本，保证页面状态与同步服务一致
* @param context 广播上下文对象
* @param intent 携带同步状态与进度的广播意图
*/
@Override
public void onReceive(Context context, Intent intent) {
// 刷新设置页面UI
// 刷新页面所有UI控件，同步最新状态
refreshUI();
// 同步中：更新同步进度文本
// 同步中状态：更新实时同步进度文本
if (intent.getBooleanExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_IS_SYNCING, false)) {
TextView syncStatus = (TextView) findViewById(R.id.prefenerece_sync_status_textview);
syncStatus.setText(intent
@ -555,17 +563,17 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
/**
* 处理ActionBar菜单点击事件
* 核心逻辑：点击返回按钮时，跳转回便签列表页并清除顶部Activity栈
* @param item 被点击的菜单项
* @return boolean：是否处理了该点击事件
* 重写ActionBar菜单点击事件处理方法
* 核心业务逻辑：处理左上角返回按钮的点击事件，跳转回便签列表主页面并清除顶部Activity栈，
* 避免返回时重复创建页面，优化用户导航体验，是页面导航的核心实现
* @param item 被点击的菜单项对象
* @return boolean 是否成功处理该点击事件
*/
public boolean onOptionsItemSelected(MenuItem item) {
switch (item.getItemId()) {
case android.R.id.home:
// 构建跳转到便签列表页的意图
// 构建返回主页面的意图，清除顶部栈保证页面唯一性
Intent intent = new Intent(this, NotesListActivity.class);
// 清除顶部Activity栈，避免返回时重复创建
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
startActivity(intent);
return true;

209
src/Notes-master/src/net/micode/notes/widget/NoteWidgetProvider.java
Unescape View File

@ -14,222 +14,231 @@
* limitations under the License.
*/
// 包声明：归属小米便签桌面小部件模块，定义所有尺寸便签小部件的通用基类
// 包声明：小米便签 桌面小部件功能模块，该包统管所有小部件基类与不同规格的实现子类
package net.micode.notes.widget;
// 导入安卓延迟意图类：用于小部件点击事件的异步意图触发
// -------------------------- 安卓系统核心依赖包 - 桌面小部件基础能力 --------------------------
// 安卓延迟意图类：小部件跨进程点击事件核心载体，桌面进程通过该类触发应用内页面跳转，异步执行意图逻辑
import android.app.PendingIntent;
// 导入安卓小部件管理器类：管理小部件的生命周期（更新、删除、创建）
// 安卓系统桌面小部件核心管理类：负责小部件的创建、更新、销毁、状态维护等全生命周期系统调度
import android.appwidget.AppWidgetManager;
// 导入安卓小部件提供者基类：所有桌面小部件的系统基类
// 安卓系统小部件基类：所有桌面小部件的标准父类，封装系统层小部件生命周期回调方法
import android.appwidget.AppWidgetProvider;
// 导入安卓内容值类：用于封装ContentProvider的更新数据
// 安卓数据封装类：封装ContentProvider的更新数据键值对，用于便签数据的字段更新操作
import android.content.ContentValues;
// 导入安卓上下文类：提供应用运行环境（资源访问、ContentResolver获取等）
// 安卓应用全局上下文：提供资源访问、ContentResolver获取、系统服务调用等核心能力，小部件核心依赖
import android.content.Context;
// 导入安卓意图类：用于组件间通信（小部件点击跳转页面）
// 安卓组件通信核心类：封装页面跳转指令与传递参数，用于小部件点击后的页面跳转逻辑
import android.content.Intent;
// 导入安卓数据库游标类：存储数据库查询结果
// 安卓数据库游标类：承载ContentProvider的查询结果集，按需读取便签数据，用完需手动释放资源
import android.database.Cursor;
// 导入安卓日志类：输出小部件相关日志（异常/调试）
// 安卓系统日志工具类：输出调试与异常日志，便于小部件功能的问题定位与线上排查
import android.util.Log;
// 导入安卓远程视图类：用于渲染桌面小部件的UI（小部件运行在桌面进程，需远程视图）
// 安卓远程视图类：小部件核心UI载体，因小部件运行在桌面系统进程，需通过该类跨进程渲染UI布局与数据
import android.widget.RemoteViews;
// 导入小米便签资源类：引用布局、字符串、图片等资源
// -------------------------- 小米便签业务层核心依赖 - 资源/数据/页面/工具 --------------------------
// 小米便签资源常量类：统一管理布局、字符串、图片、颜色等所有本地资源ID引用
import net.micode.notes.R;
// 导入便签数据常量类：定义便签URI、字段、意图参数等核心常量
// 小米便签数据层核心常量类：定义便签URI、意图参数、业务状态、小部件类型等全局核心常量，数据层与UI层通用
import net.micode.notes.data.Notes;
// 导入便签列常量子类：简化便签表字段的引用
// 小米便签数据表字段子类：简化便签数据库表的列名引用，避免硬编码，提升代码可维护性
import net.micode.notes.data.Notes.NoteColumns;
// 导入资源解析工具类：解析小部件背景资源
// 小米便签资源解析工具类：封装多规格小部件背景资源的映射适配逻辑，统一提供不同尺寸的背景资源获取能力
import net.micode.notes.tool.ResourceParser;
// 导入便签编辑页面：小部件点击跳转的目标页面
// 小米便签核心业务页面：便签新建/编辑页面，小部件点击跳转的核心目标页面
import net.micode.notes.ui.NoteEditActivity;
// 导入便签列表页面：隐私模式下小部件点击跳转的目标页面
// 小米便签核心业务页面：便签列表展示页面，隐私模式下小部件点击的跳转目标页面
import net.micode.notes.ui.NotesListActivity;
/**
* 便签桌面小部件抽象基类
* 继承自安卓系统AppWidgetProvider，封装所有尺寸便签小部件的通用核心逻辑：
* 1. 小部件删除时清理关联的便签数据；
* 2. 小部件更新时的通用UI渲染、数据查询、点击事件绑定；
* 3. 定义抽象方法，由子类（2x/4x）实现尺寸相关的布局、背景、类型适配。
* 小米便签 桌面小部件通用抽象基类
* <p>
* 继承安卓系统标准基类{AppWidgetProvider}，隶属于MVC架构的UI层核心组件，是所有尺寸规格便签小部件的父类；
* 核心设计理念：采用「模板方法设计模式」，封装所有小部件的通用核心业务逻辑与生命周期管理，下沉共性能力，
* 把与尺寸强相关的差异化适配逻辑抽离为抽象方法，交由子类{NoteWidgetProvider_2x}/{NoteWidgetProvider_4x}实现；
* 统一承载能力：小部件删除时的关联数据清理、小部件更新时的通用数据查询/UI渲染/点击事件绑定、隐私模式适配、资源释放等；
* 本类为抽象类，无法实例化，仅作为子类的标准化模板与能力基座。
* </p>
*/
public abstract class NoteWidgetProvider extends AppWidgetProvider {
/**
* 数据库查询投影数组：指定查询便签的核心字段，减少查询冗余
* 包含：便签ID、背景色ID、便签摘要（用于小部件展示）
* 数据库查询投影数组：指定查询便签表的核心业务字段，按需查询，减少无效字段的内存占用与查询耗时
* 投影字段严格匹配业务需求，仅查询小部件展示所需的核心数据，无冗余字段
*/
public static final String [] PROJECTION = new String [] {
NoteColumns.ID, // 便签唯一标识
NoteColumns.BG_COLOR_ID, // 便签背景色ID
NoteColumns.SNIPPET // 便签内容摘要
NoteColumns.ID, // 便签数据表-主键ID，唯一标识单条便签数据
NoteColumns.BG_COLOR_ID, // 便签数据表-背景色标识ID，用于匹配小部件对应背景资源
NoteColumns.SNIPPET // 便签数据表-内容摘要，小部件UI上展示的核心文本内容
};
// 投影数组对应的列索引常量，简化Cursor取值
public static final int COLUMN_ID = 0; // 便签ID列索引
public static final int COLUMN_BG_COLOR_ID = 1; // 背景色ID列索引
public static final int COLUMN_SNIPPET = 2; // 摘要列索引
// 投影数组对应的列索引常量：固化查询结果集的字段下标，简化Cursor取值逻辑，避免硬编码索引值导致的错误
public static final int COLUMN_ID = 0; // 投影数组中-便签ID的列索引
public static final int COLUMN_BG_COLOR_ID = 1; // 投影数组中-背景色ID的列索引
public static final int COLUMN_SNIPPET = 2; // 投影数组中-便签摘要的列索引
// 日志标签：用于小部件相关日志输出，便于问题定位
// 日志统一标签：小部件模块所有日志输出的固定标识，便于日志过滤与问题精准定位
private static final String TAG = "NoteWidgetProvider";
/**
* 重写小部件删除回调方法
* 当用户删除便签小部件时触发，核心逻辑：将关联便签的WIDGET_ID置为无效，清理关联关系
* @param context 应用上下文
* @param appWidgetIds 被删除的小部件ID数组
* 重写系统小部件生命周期回调：小部件删除触发方法
* 触发时机：用户在桌面手动删除任意规格的便签小部件实例时由系统回调
* 核心业务逻辑：清理当前小部件与便签的关联关系，将关联便签的WIDGET_ID字段置为无效值，
* 保证数据层的关联关系一致性，防止出现无效的脏数据关联
* @param context 应用全局上下文对象，提供ContentResolver数据操作能力
* @param appWidgetIds 被用户删除的小部件ID数组，支持批量删除处理
*/
@Override
public void onDeleted(Context context, int[] appWidgetIds) {
// 构建ContentValues：将WIDGET_ID设为无效值（INVALID_APPWIDGET_ID）
// 构建数据更新载体：封装需要更新的字段与对应值，将关联标识置为系统无效值
ContentValues values = new ContentValues();
values.put(NoteColumns.WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID);
// 遍历所有被删除的小部件ID，更新关联便签的WIDGET_ID
// 遍历所有待删除的小部件ID，逐一对关联便签执行数据更新操作
for (int i = 0; i < appWidgetIds.length; i++) {
context.getContentResolver().update(Notes.CONTENT_NOTE_URI, // 便签ContentProvider的URI
values, // 要更新的字段和值
NoteColumns.WIDGET_ID + "=?", // 更新条件：WIDGET_ID匹配当前删除的ID
new String[] { String.valueOf(appWidgetIds[i])}); // 条件参数（防止SQL注入）
context.getContentResolver().update(Notes.CONTENT_NOTE_URI,
values,
NoteColumns.WIDGET_ID + "=?",
new String[] { String.valueOf(appWidgetIds[i])});
}
}
/**
* 私有方法：根据小部件ID查询关联的便签信息
* 过滤条件：关联当前widgetId + 非回收站便签（PARENT_ID≠回收站ID）
* @param context 应用上下文，用于获取ContentResolver
* @param widgetId 目标小部件ID
* @return Cursor：包含匹配的便签信息（ID、背景色、摘要），无匹配则返回null
* 私有核心工具方法：根据小部件ID，查询其关联的有效便签数据信息
* 核心过滤条件：匹配当前小部件ID + 排除回收站中的便签数据，保证查询结果为有效展示的便签
* @param context 应用上下文，用于获取ContentResolver执行数据查询
* @param widgetId 目标小部件的唯一标识ID
* @return Cursor 匹配条件的便签数据结果集，无匹配数据时返回null；结果集需调用方手动关闭释放资源
*/
private Cursor getNoteWidgetInfo(Context context, int widgetId) {
return context.getContentResolver().query(Notes.CONTENT_NOTE_URI, // 便签查询URI
PROJECTION, // 查询的字段投影
NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?", // 查询条件
new String[] { String.valueOf(widgetId), String.valueOf(Notes.ID_TRASH_FOLER) }, // 条件参数
null); // 排序规则（无）
return context.getContentResolver().query(Notes.CONTENT_NOTE_URI,
PROJECTION,
NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?",
new String[] { String.valueOf(widgetId), String.valueOf(Notes.ID_TRASH_FOLER) },
null);
}
/**
* 对外暴露的小部件更新方法（重载）
* 默认以非隐私模式更新小部件，调用带privacyMode的核心更新方法
* @param context 应用上下文
* @param appWidgetManager 小部件管理器
* @param appWidgetIds 需要更新的小部件ID数组
* 受保护的重载更新方法：对外暴露的小部件通用更新入口
* 业务适配：默认以【非隐私模式】执行小部件的UI渲染与数据绑定，为子类提供极简的调用入口
* @param context 应用全局上下文
* @param appWidgetManager 系统小部件管理器，负责最终的UI更新调度
* @param appWidgetIds 需要执行更新操作的小部件ID数组，支持批量更新
*/
protected void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
update(context, appWidgetManager, appWidgetIds, false);
}
/**
* 核心私有更新方法：实现小部件UI渲染、数据绑定、点击事件配置的通用逻辑
* @param context 应用上下文
* @param appWidgetManager 小部件管理器，用于更新小部件UI
* @param appWidgetIds 需要更新的小部件ID数组
* @param privacyMode 是否为隐私模式（隐私模式下隐藏内容，跳转列表页）
* 私有核心业务方法：小部件通用更新逻辑的总入口，封装所有规格小部件的完整更新流程
* 核心职责：统一实现 数据查询 → 数据解析 → 视图初始化 → 内容赋值 → 点击事件绑定 → UI刷新 全链路逻辑，
* 兼容普通模式/隐私模式双场景，处理有无关联便签的分支逻辑，是整个小部件的核心业务实现方法
* @param context 应用全局上下文，支撑资源访问与数据操作
* @param appWidgetManager 系统小部件管理器，提供小部件UI更新的核心能力
* @param appWidgetIds 需要更新的小部件ID数组，支持多实例批量处理
* @param privacyMode 是否启用隐私模式：true=隐私模式(隐藏内容)，false=普通模式(展示内容)
*/
private void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds,
boolean privacyMode) {
// 遍历所有需要更新的小部件ID，逐个处理
// 遍历所有待更新的小部件ID，逐个完成独立的更新逻辑处理
for (int i = 0; i < appWidgetIds.length; i++) {
// 过滤无效的小部件ID（INVALID_APPWIDGET_ID）
// 过滤无效的小部件ID，跳过无意义的更新操作，提升执行效率
if (appWidgetIds[i] != AppWidgetManager.INVALID_APPWIDGET_ID) {
// 初始化默认背景ID（从资源解析工具获取全局默认背景）
// 初始化默认背景ID：从资源工具类获取应用全局默认的便签背景标识
int bgId = ResourceParser.getDefaultBgId(context);
// 初始化便签摘要（默认空字符串）
// 初始化便签摘要：默认空字符串，防止空指针异常
String snippet = "";
// 构建小部件点击意图：默认跳转便签编辑页
// 构建默认跳转意图：无关联便签时，跳转至便签编辑页执行新建操作
Intent intent = new Intent(context, NoteEditActivity.class);
intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP); // 防止重复创建Activity
intent.putExtra(Notes.INTENT_EXTRA_WIDGET_ID, appWidgetIds[i]); // 携带小部件ID参数
intent.putExtra(Notes.INTENT_EXTRA_WIDGET_TYPE, getWidgetType()); // 携带小部件类型（子类实现）
intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP); // 启动模式：栈顶复用，避免重复创建页面实例
intent.putExtra(Notes.INTENT_EXTRA_WIDGET_ID, appWidgetIds[i]); // 携带小部件ID参数，供编辑页关联使用
intent.putExtra(Notes.INTENT_EXTRA_WIDGET_TYPE, getWidgetType()); // 携带小部件类型，由子类实现差异化适配
// 查询当前小部件关联的便签信息
// 查询当前小部件关联的有效便签数据
Cursor c = getNoteWidgetInfo(context, appWidgetIds[i]);
if (c != null && c.moveToFirst()) {
// 异常日志：同一个widgetId关联多个便签（数据异常）
// 异常日志埋点：同一小部件ID关联多条便签数据，属于数据异常场景，输出错误日志便于排查
if (c.getCount() > 1) {
Log.e(TAG, "Multiple message with same widget id:" + appWidgetIds[i]);
c.close();
return;
}
// 从Cursor中获取便签摘要和背景色ID
// 从结果集中解析业务数据，赋值给本地变量用于后续视图渲染
snippet = c.getString(COLUMN_SNIPPET);
bgId = c.getInt(COLUMN_BG_COLOR_ID);
// 携带便签ID参数，跳转编辑页时定位到该便签
// 携带便签ID参数，跳转编辑页时直接定位到当前关联的便签内容
intent.putExtra(Intent.EXTRA_UID, c.getLong(COLUMN_ID));
// 设置意图动作：查看已有便签
// 修改意图动作：由「新建」改为「查看/编辑」已有便签
intent.setAction(Intent.ACTION_VIEW);
} else {
// 无关联便签时：显示默认提示文本
// 无关联便签数据时：展示应用默认的空内容提示文本
snippet = context.getResources().getString(R.string.widget_havenot_content);
// 设置意图动作：新建便签
// 修改意图动作：执行新建便签的业务逻辑
intent.setAction(Intent.ACTION_INSERT_OR_EDIT);
}
// 关闭Cursor，释放数据库资源
// 安全关闭游标，释放数据库连接资源，防止内存泄漏
if (c != null) {
c.close();
}
// 创建远程视图：加载子类定义的布局（2x/4x）
// 创建远程视图实例：加载子类实现的规格专属布局，完成跨进程UI初始化
RemoteViews rv = new RemoteViews(context.getPackageName(), getLayoutId());
// 设置小部件背景图：使用子类定义的背景资源（2x/4x）
// 为远程视图设置背景资源：加载子类实现的规格专属背景，完成尺寸与背景的精准适配
rv.setImageViewResource(R.id.widget_bg_image, getBgResourceId(bgId));
// 携带背景ID参数，跳转编辑页时同步背景
// 携带背景ID参数，跳转编辑页时同步使用当前小部件的背景样式
intent.putExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, bgId);
/**
* 生成小部件点击的PendingIntent（延迟意图）
* 区分隐私模式和普通模式：
* 1. 隐私模式：显示提示文本，跳转便签列表页；
* 2. 普通模式：显示便签摘要，跳转便签编辑页。
* 构建小部件点击的延迟意图：区分隐私模式与普通模式，实现差异化的交互逻辑
* PendingIntent为跨进程意图载体，是小部件点击事件的核心实现方式，保证桌面进程能触发应用内逻辑
*/
PendingIntent pendingIntent = null;
if (privacyMode) {
// 隐私模式：设置提示文本（“访问模式下隐藏内容”）
// 隐私模式逻辑：隐藏便签真实内容，展示隐私提示文本
rv.setTextViewText(R.id.widget_text,
context.getString(R.string.widget_under_visit_mode));
// 构建跳转列表页的PendingIntent
// 隐私模式跳转：点击后跳转至便签列表页面，而非编辑页
pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], new Intent(
context, NotesListActivity.class), PendingIntent.FLAG_UPDATE_CURRENT);
} else {
// 普通模式：设置便签摘要文本
// 普通模式逻辑：展示解析后的便签摘要文本
rv.setTextViewText(R.id.widget_text, snippet);
// 构建跳转编辑页的PendingIntent（FLAG_UPDATE_CURRENT：更新已有Intent的参数）
// 普通模式跳转：点击后跳转至便签编辑页，携带完整业务参数
pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], intent,
PendingIntent.FLAG_UPDATE_CURRENT);
}
// 绑定小部件文本区域的点击事件：触发上述PendingIntent
// 为小部件核心文本区域绑定点击事件，触发上述构建的延迟意图
rv.setOnClickPendingIntent(R.id.widget_text, pendingIntent);
// 通过小部件管理器更新当前小部件的UI
// 通过系统管理器完成最终的UI刷新，将渲染完成的远程视图同步至桌面小部件
appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
}
}
}
/**
* 抽象方法：获取小部件背景资源ID
* 由子类（2x/4x）实现，返回对应尺寸的背景资源ID
* @param bgId 背景色标识ID
* @return 对应尺寸的背景资源ID
* 抽象方法：获取小部件规格专属的背景资源ID
* 由子类根据自身尺寸规格实现，完成背景资源与小部件尺寸的精准适配，避免背景拉伸/变形
* @param bgId 便签数据表中定义的背景色标识ID，为全局统一的背景风格常量
* @return int 对应尺寸规格的背景Drawable资源ID
*/
protected abstract int getBgResourceId(int bgId);
/**
* 抽象方法：获取小部件布局ID
* 由子类（2x/4x）实现，返回对应尺寸的布局资源ID
* @return 对应尺寸的布局资源ID
* 抽象方法：获取小部件规格专属的布局资源ID
* 由子类根据自身尺寸规格实现，加载与桌面占位大小匹配的专属布局，保证UI展示效果
* @return int 对应尺寸规格的布局资源ID
*/
protected abstract int getLayoutId();
/**
* 抽象方法：获取小部件类型标识
* 由子类（2x/4x）实现，返回对应尺寸的类型常量（Notes.TYPE_WIDGET_2X/4X）
* @return 小部件类型标识
* 抽象方法：获取小部件的标准化业务类型标识
* 由子类根据自身尺寸规格实现，返回数据层统一定义的类型常量；
* 该标识是数据层识别小部件规格的核心依据，用于数据关联、筛选与同步，保证数据与视图的一致性
* @return int 小部件业务类型常量，取值为Notes.TYPE_WIDGET_2X / Notes.TYPE_WIDGET_4X
*/
protected abstract int getWidgetType();
}

50
src/Notes-master/src/net/micode/notes/widget/NoteWidgetProvider_2x.java
Unescape View File

@ -14,70 +14,66 @@
* limitations under the License.
*/
// 包声明：归属小米便签的桌面小部件模块
// 包声明：小米便签 桌面小部件功能模块，该包下统管所有尺寸规格的便签桌面小组件实现类
package net.micode.notes.widget;
// 导入必要的安卓系统类：用于管理桌面小部件
import android.appwidget.AppWidgetManager;
// 导入安卓上下文类：提供应用运行环境的全局信息
import android.content.Context;
// 导入小米便签的资源类：用于引用布局等资源
import net.micode.notes.R;
// 导入便签数据常量类：定义小部件类型等常量
import net.micode.notes.data.Notes;
// 导入资源解析工具类：用于解析小部件背景资源
import net.micode.notes.tool.ResourceParser;
/**
* 2x尺寸便签桌面小部件提供者类
* 继承自基础的NoteWidgetProvider，专门适配2x尺寸的小部件布局、背景和类型标识
* 小米便签 2X规格桌面小部件提供者核心实现类
* 继承抽象基类NoteWidgetProvider，作为MVC架构中UI层的桌面可视化组件，仅负责2X规格专属适配逻辑；
* 核心职责：实现基类抽象方法，为2X尺寸小部件提供专属布局、匹配的背景资源、标准化业务类型标识；
* 设计原则：通用的小部件生命周期管理、数据更新、视图渲染逻辑完全复用父类，子类只做规格差异化实现，解耦通用逻辑与尺寸适配逻辑。
*/
public class NoteWidgetProvider_2x extends NoteWidgetProvider {
/**
* 重写小部件更新方法
* 触发2x尺寸小部件的更新逻辑，调用父类的update方法完成具体更新操作
* @param context 应用上下文
* @param appWidgetManager 桌面小部件管理器
* @param appWidgetIds 需要更新的小部件ID数组
* 重写系统小部件生命周期的更新回调方法
* 触发场景：小部件首次添加至桌面、系统触发定时刷新、便签数据变更主动同步时调用
* 方法逻辑：无差异化业务处理，直接调用父类统一的update核心方法，完成2X小部件的视图刷新与便签数据绑定
* @param context 全局上下文对象，提供系统服务调用、应用资源访问的基础能力
* @param appWidgetManager 系统桌面小部件管理器，负责小部件的创建、更新、销毁等全生命周期调度
* @param appWidgetIds 待更新的2X规格小部件ID数组，支持多实例批量更新操作
*/
@Override
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
// 调用父类的update方法，执行2x尺寸小部件的更新核心逻辑
super.update(context, appWidgetManager, appWidgetIds);
}
/**
* 重写获取布局ID的方法
* 返回2x尺寸小部件对应的布局资源ID
* @return 2x小部件布局资源ID
* 重写父类抽象方法，获取2X规格小部件的专属布局资源ID
* 布局文件为固定尺寸适配，与2X桌面占位大小完全匹配，保证便签内容在该规格下的完整展示
* @return int 2X小部件专属布局资源ID，对应布局文件：R.layout.widget_2x
*/
@Override
protected int getLayoutId() {
// 返回R.layout.widget_2x：2x尺寸小部件的布局文件ID
return R.layout.widget_2x;
}
/**
* 重写获取背景资源ID的方法
* 根据传入的背景ID，解析并返回2x尺寸小部件对应的背景资源ID
* @param bgId 背景标识ID
* @return 2x尺寸小部件对应的背景资源ID
* 重写父类抽象方法，获取2X规格小部件对应的背景资源ID
* 核心适配说明：不同尺寸的小部件背景资源为独立资源文件，需根据背景主题ID精准匹配对应规格的背景；
* 避免因尺寸不一致导致的背景拉伸、变形等UI兼容问题，通过工具类封装所有背景资源的映射关系，统一管理。
* @param bgId 背景主题标识ID，为Notes模块统一定义的背景风格常量，与具体尺寸解耦
* @return int 适配2X规格的背景Drawable资源ID
*/
@Override
protected int getBgResourceId(int bgId) {
// 调用ResourceParser工具类，获取2x尺寸小部件对应的背景资源ID
return ResourceParser.WidgetBgResources.getWidget2xBgResource(bgId);
}
/**
* 重写获取小部件类型的方法
* 返回2x尺寸便签小部件的类型标识
* @return 2x小部件类型常量（Notes.TYPE_WIDGET_2X）
* 重写父类抽象方法，获取当前小部件的标准化业务类型标识
* 该标识为数据层核心常量，用于NotesProvider数据持久化、便签数据同步、小部件类型筛选的核心依据；
* 保证数据层能精准识别当前小部件的尺寸规格，返回对应规格的便签数据，实现「数据-视图」的规格一致性适配。
* @return int 2X规格小部件的业务类型常量，定值：Notes.TYPE_WIDGET_2X
*/
@Override
protected int getWidgetType() {
// 返回Notes.TYPE_WIDGET_2X：2x尺寸便签小部件的类型标识常量
return Notes.TYPE_WIDGET_2X;
}
}

56
src/Notes-master/src/net/micode/notes/widget/NoteWidgetProvider_4x.java
Unescape View File

@ -14,70 +14,70 @@
* limitations under the License.
*/
// 包声明：归属小米便签的桌面小部件模块，统一管理不同尺寸的便签小部件
// 包声明：小米便签 桌面小部件功能模块，该包统一承载所有尺寸规格的便签桌面小组件实现类
package net.micode.notes.widget;
// 导入安卓系统小部件管理类：用于管理桌面小部件的创建、更新、删除等生命周期
// 安卓系统核心依赖：桌面小部件全生命周期调度的核心管理类，负责小部件的创建、更新、销毁等系统操作
import android.appwidget.AppWidgetManager;
// 导入安卓上下文类：提供应用运行时的环境信息（如资源访问、组件通信）
// 安卓系统核心依赖：应用全局上下文，提供资源访问、系统服务调用、组件通信的基础能力，小部件初始化必备
import android.content.Context;
// 导入小米便签资源类：引用布局、颜色等本地资源
// 小米便签业务依赖：应用资源常量类，统一管理所有布局、样式等资源ID引用
import net.micode.notes.R;
// 导入便签数据常量类：定义小部件类型、便签状态等核心常量
// 小米便签业务依赖：数据层核心常量类，定义便签及小部件的类型、状态等全局业务枚举常量
import net.micode.notes.data.Notes;
// 导入资源解析工具类：专门处理小部件背景资源的解析与匹配
// 小米便签业务依赖：资源解析工具类，封装多规格小部件背景资源的映射适配逻辑，统一提供背景资源获取能力
import net.micode.notes.tool.ResourceParser;
/**
* 4x尺寸便签桌面小部件提供者类
* 继承自基础的NoteWidgetProvider抽象类，专门适配4x尺寸的桌面小部件，
* 核心职责是定义4x尺寸小部件的布局、背景资源和类型标识
* 小米便签 4X规格桌面小部件提供者核心实现类
* 继承抽象基类NoteWidgetProvider，隶属于MVC架构的UI层桌面可视化组件，专注4X规格的差异化适配；
* 核心设计职责：实现基类定义的抽象方法，为4X尺寸小部件提供专属的布局资源、匹配的背景样式资源、标准化业务类型标识；
* 设计思想遵循：父类封装所有小部件通用的生命周期、数据更新、视图渲染核心逻辑，子类仅实现当前规格的差异化配置，解耦通用逻辑与尺寸适配逻辑，提升扩展性。
*/
public class NoteWidgetProvider_4x extends NoteWidgetProvider {
/**
* 重写小部件更新回调方法
* 当4x尺寸便签小部件需要更新时触发，调用父类update方法执行具体更新逻辑
* @param context 应用上下文，用于资源访问和组件交互
* @param appWidgetManager 小部件管理器，负责小部件的更新操作
* @param appWidgetIds 需要更新的4x小部件ID数组（支持多实例）
* 重写系统小部件生命周期的更新回调方法
* 触发场景：4X小部件首次添加至桌面、系统执行定时刷新任务、便签数据变更触发主动同步时调用
* 方法核心逻辑：无4X规格的差异化业务处理，直接复用父类统一的update核心方法，完成4X小部件的视图刷新与最新便签数据绑定
* @param context 应用全局上下文对象，支撑小部件的资源访问与系统服务调用
* @param appWidgetManager 系统桌面小部件管理器，统一调度所有小部件实例的更新操作
* @param appWidgetIds 待执行更新的4X规格小部件ID数组，原生支持多小部件实例的批量更新
*/
@Override
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
// 调用父类核心更新方法，复用通用更新逻辑，适配4x尺寸小部件
super.update(context, appWidgetManager, appWidgetIds);
}
/**
* 定义4x尺寸小部件对应的布局资源ID
* （注：此处未显式标注@Override，但逻辑上是重写父类抽象方法）
* @return 4x小部件专属布局文件ID（R.layout.widget_4x）
* 实现父类抽象方法：获取4X规格小部件的专属布局资源ID
* 该布局为小米便签定制化的4X尺寸UI布局，与桌面4格占位大小精准匹配，保障便签内容完整展示无适配问题
* @return int 4X小部件专属布局资源ID，对应固定布局文件：R.layout.widget_4x
*/
protected int getLayoutId() {
// 返回widget_4x布局ID：该布局定义了4x尺寸小部件的UI结构
return R.layout.widget_4x;
}
/**
* 重写背景资源获取方法
* 根据背景标识ID，匹配并返回4x尺寸小部件对应的背景资源ID
* @param bgId 背景样式标识（不同数值对应不同背景风格）
* @return 4x尺寸小部件的背景资源ID
* 重写父类抽象方法：根据背景主题标识ID，获取4X规格小部件的专属背景资源ID
* 核心适配逻辑：不同尺寸规格的小部件对应独立的背景资源文件，避免尺寸不匹配导致的背景拉伸、变形等UI兼容问题；
* 背景资源的映射关系由工具类统一封装管理，实现业务逻辑与资源适配的解耦，便于后续扩展新的背景样式。
* @param bgId 背景主题枚举标识ID，为项目统一定义的小部件背景风格常量，与具体尺寸规格解耦
* @return int 精准匹配4X规格的背景Drawable资源ID
*/
@Override
protected int getBgResourceId(int bgId) {
// 调用工具类方法，获取4x尺寸小部件对应的背景资源ID
return ResourceParser.WidgetBgResources.getWidget4xBgResource(bgId);
}
/**
* 重写小部件类型获取方法
* 返回4x尺寸便签小部件的专属类型标识，用于区分不同尺寸的小部件
* @return 4x小部件类型常量（Notes.TYPE_WIDGET_4X）
* 重写父类抽象方法：获取当前4X规格小部件的标准化业务类型标识
* 该标识为数据层核心业务常量，是NotesProvider数据持久化、便签数据同步、小部件类型筛选的核心依据；
* 作用是让数据层能够精准识别当前小部件的尺寸规格，返回对应规格的适配数据，实现「业务数据-桌面视图」的规格一致性闭环。
* @return int 4X规格小部件的业务类型常量，定值：Notes.TYPE_WIDGET_4X
*/
@Override
protected int getWidgetType() {
// 返回Notes中定义的4x小部件类型常量，用于业务层识别小部件尺寸
return Notes.TYPE_WIDGET_4X;
}
}
Write Preview
Loading…
Cancel
Save