Intent 与组件通信

// Intent 的核心字段（简化示意，非完整源码）
class Intent : Parcelable {
    // ---- 路由信息 ----
    private var mAction: String? = null       // 动作标识，如 "android.intent.action.VIEW"
    private var mData: Uri? = null            // 数据 URI，如 "https://example.com"
    private var mType: String? = null         // MIME 类型，如 "image/png"
    private var mComponent: ComponentName? = null  // 显式指定的目标组件
    private var mCategories: HashSet<String>? = null // 类别集合，如 "android.intent.category.DEFAULT"
    
    // ---- 附加数据 ----
    private var mExtras: Bundle? = null       // 键值对形式的额外数据
    
    // ---- 行为控制 ----
    private var mFlags: Int = 0               // 标志位，控制启动模式、任务栈行为等
    
    // ---- 包过滤 ----
    private var mPackage: String? = null      // 限定目标应用的包名
}

// 查看某个数据（最通用的 Action 之一）
// 例如：查看网页、查看联系人、查看图片
Intent.ACTION_VIEW       // = "android.intent.action.VIEW"
 
// 编辑某个数据
Intent.ACTION_EDIT       // = "android.intent.action.EDIT"
 
// 发送/分享数据给其他应用
Intent.ACTION_SEND       // = "android.intent.action.SEND"
 
// 拨打电话（直接拨出，需要权限）
Intent.ACTION_CALL       // = "android.intent.action.CALL"
 
// 打开拨号盘（不直接拨出，不需要权限）
Intent.ACTION_DIAL       // = "android.intent.action.DIAL"
 
// 应用的主入口（Launcher 图标点击时触发）
Intent.ACTION_MAIN       // = "android.intent.action.MAIN"
 
// 搜索
Intent.ACTION_SEARCH     // = "android.intent.action.SEARCH"
 
// 从相机或图库中选取内容
Intent.ACTION_PICK       // = "android.intent.action.PICK"

// 自定义 Action 示例
// 命名规范：包名 + 动作描述
const val ACTION_SHOW_PROFILE = "com.example.myapp.action.SHOW_PROFILE"
const val ACTION_PROCESS_ORDER = "com.example.myapp.action.PROCESS_ORDER"

// 最常见的 Category
Intent.CATEGORY_DEFAULT    // = "android.intent.category.DEFAULT"
Intent.CATEGORY_LAUNCHER   // = "android.intent.category.LAUNCHER"
Intent.CATEGORY_BROWSABLE  // = "android.intent.category.BROWSABLE"

<!-- 在 AndroidManifest.xml 中声明 IntentFilter 的 data 匹配规则 -->
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    
    <!-- URI 匹配：scheme 为 https，host 为 example.com，path 前缀为 /article -->
    <data
        android:scheme="https"
        android:host="example.com"
        android:pathPrefix="/article" />
</intent-filter>

// ========== 发送方：构造一个隐式 Intent ==========
 
// 场景：用户点击一个链接，想要查看一篇网页文章
fun openArticle(url: String) {
    // 创建 Intent，设置 Action 为 VIEW（查看）
    val intent = Intent(Intent.ACTION_VIEW).apply {
        // 设置 Data 为文章的 URL
        // Uri.parse() 将字符串解析为 URI 对象
        data = Uri.parse(url)  // 例如 "https://example.com/article/123"
        
        // 注意：我们没有手动添加 CATEGORY_DEFAULT
        // 因为 startActivity() 会自动添加
    }
    
    // 安全检查：确认系统中有能处理这个 Intent 的组件
    // resolveActivity() 会执行一次 Intent Resolution
    // 如果返回 null，说明没有任何应用能处理
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)  // 系统自动添加 CATEGORY_DEFAULT，然后发送给 AMS
    } else {
        // 没有应用能处理，给用户友好提示
        Toast.makeText(this, "没有找到可以打开链接的应用", Toast.LENGTH_SHORT).show()
    }
}

<!-- ========== 接收方：在 AndroidManifest.xml 中声明 IntentFilter ========== -->
 
<!-- 这个 Activity 声明自己能够处理 "查看 https://example.com/article/* 链接" 的请求 -->
<activity android:name=".ArticleDetailActivity"
    android:exported="true">  <!-- exported=true 允许其他应用启动 -->
    
    <intent-filter>
        <!-- Action 匹配：我能处理 VIEW 动作 -->
        <action android:name="android.intent.action.VIEW" />
        
        <!-- Category 匹配：必须包含 DEFAULT，否则隐式 Intent 永远匹配不到 -->
        <category android:name="android.intent.category.DEFAULT" />
        <!-- BROWSABLE 允许从浏览器链接点击启动 -->
        <category android:name="android.intent.category.BROWSABLE" />
        
        <!-- Data 匹配：scheme 为 https，host 为 example.com，路径以 /article 开头 -->
        <data
            android:scheme="https"
            android:host="example.com"
            android:pathPrefix="/article" />
    </intent-filter>
</activity>

<intent-filter>
    <action android:name="android.intent.action.SEND" />
    <data android:mimeType="text/plain" />
</intent-filter>

val intent = Intent(Intent.ACTION_SEND).apply {
    type = "text/plain"
    putExtra(Intent.EXTRA_TEXT, "要分享的文本内容")
}
startActivity(intent)

<activity
    android:name=".ShareActivity"
    android:exported="true">  <!-- Android 12+ 要求显式 exported -->
 
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />  <!-- 必须加这一行 -->
        <data android:mimeType="text/plain" />
    </intent-filter>
 
    <!-- 如果还想支持多条文本（SEND_MULTIPLE），可以再加一个 Filter -->
    <intent-filter>
        <action android:name="android.intent.action.SEND_MULTIPLE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>

// ========== 方式一：构造函数直接传入 Context 和目标 Class ==========
// 这是最常见、最简洁的写法
// 内部实现：从 context 中提取包名，从 DetailActivity::class.java 中提取类全名
// 然后构造 ComponentName(packageName, className)
val intent1 = Intent(this, DetailActivity::class.java)
 
// ========== 方式二：手动创建 ComponentName 并设置 ==========
// 适用于需要启动其他应用中的组件（跨应用显式调用）
// 第一个参数：目标应用的包名
// 第二个参数：目标组件的完整类名（包含包路径）
val componentName = ComponentName(
    "com.example.otherapp",                    // 目标应用的包名
    "com.example.otherapp.ui.PaymentActivity"  // 目标 Activity 的全限定类名
)
val intent2 = Intent().apply {
    component = componentName  // 将 ComponentName 设置到 Intent 中
}
 
// ========== 方式三：通过 setClassName() 设置 ==========
// 本质上也是创建 ComponentName，只是 API 更简洁
val intent3 = Intent().apply {
    setClassName(
        "com.example.otherapp",                    // 目标包名
        "com.example.otherapp.ui.PaymentActivity"  // 目标类全名
    )
}
 
// ========== 方式四：通过 setClass() 设置（仅限同应用内） ==========
// 等价于方式一，只是拆成了两步
val intent4 = Intent().apply {
    setClass(this@MainActivity, DetailActivity::class.java)
}

<!-- 静态注册示例：声明一个能处理"分享纯文本"的 Activity -->
<activity
    android:name=".ShareReceiverActivity"
    android:exported="true">  <!-- 响应隐式 Intent 的组件必须 exported=true -->
    
    <!-- 一个组件可以声明多个 intent-filter -->
    <!-- 每个 intent-filter 是一组独立的匹配规则 -->
    <intent-filter>
        <!-- 声明能处理的 Action：接收分享内容 -->
        <action android:name="android.intent.action.SEND" />
        
        <!-- 必须声明 DEFAULT Category（隐式 Intent 的硬性要求） -->
        <category android:name="android.intent.category.DEFAULT" />
        
        <!-- 声明能处理的数据类型：纯文本 -->
        <data android:mimeType="text/plain" />
    </intent-filter>
    
    <!-- 第二个 intent-filter：还能处理图片分享 -->
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="image/*" />  <!-- 通配符匹配所有图片类型 -->
    </intent-filter>
</activity>

// 动态注册 BroadcastReceiver 的 IntentFilter
// 创建 IntentFilter 对象，添加要监听的 Action
val filter = IntentFilter().apply {
    addAction(Intent.ACTION_BATTERY_LOW)      // 监听电量低广播
    addAction(Intent.ACTION_POWER_CONNECTED)  // 监听充电器连接广播
}
 
// 创建 Receiver 实例
val batteryReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        // 根据不同的 Action 执行不同的逻辑
        when (intent.action) {
            Intent.ACTION_BATTERY_LOW -> showLowBatteryWarning()
            Intent.ACTION_POWER_CONNECTED -> dismissLowBatteryWarning()
        }
    }
}
 
// 注册 Receiver（在 Activity 的 onResume 中）
registerReceiver(batteryReceiver, filter)
 
// 取消注册（在 Activity 的 onPause 中，避免内存泄漏）
unregisterReceiver(batteryReceiver)

// Action Test 的伪代码逻辑
fun matchAction(intentAction: String?, filterActions: List<String>): Boolean {
    // 如果 Filter 没有声明任何 Action
    if (filterActions.isEmpty()) {
        // 只有 Intent 也没有 Action 时才匹配
        return intentAction == null
    }
    // 如果 Intent 没有设置 Action，自动通过
    // （因为 Intent 没有限定动作，任何动作都可以）
    if (intentAction == null) {
        return true
    }
    // 否则，Intent 的 Action 必须在 Filter 的 Action 列表中
    return intentAction in filterActions
}

// Category Test 的伪代码逻辑
fun matchCategories(
    intentCategories: Set<String>?,  // Intent 携带的 Category 集合
    filterCategories: Set<String>    // Filter 声明的 Category 集合
): Boolean {
    // 如果 Intent 没有任何 Category，直接通过
    if (intentCategories.isNullOrEmpty()) {
        return true
    }
    // Intent 的每个 Category 都必须在 Filter 中存在
    for (category in intentCategories) {
        if (category !in filterCategories) {
            return false  // 有一个不匹配就失败
        }
    }
    return true
}

// 创建分享 Intent
val shareIntent = Intent(Intent.ACTION_SEND).apply {
    type = "text/plain"                          // 设置 MIME 类型为纯文本
    putExtra(Intent.EXTRA_TEXT, "分享的内容")      // 设置分享的文本内容
}
 
// 使用 createChooser() 包装，强制弹出选择器
// 即使用户已经设置了默认分享应用，也会弹出选择器
val chooserIntent = Intent.createChooser(
    shareIntent,           // 原始 Intent
    "选择分享方式"          // 选择器对话框的标题
)
 
// 启动选择器
startActivity(chooserIntent)

// 安全发送隐式 Intent 的标准模式
fun safeStartActivity(intent: Intent) {
    // 方式一：使用 resolveActivity() 检查
    // 返回值不为 null 说明至少有一个组件能处理
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    } else {
        // 优雅降级：提示用户或执行备选方案
        Toast.makeText(this, "没有应用可以处理此操作", Toast.LENGTH_SHORT).show()
    }
    
    // 方式二：使用 try-catch 捕获异常（不推荐作为主要手段）
    // try {
    //     startActivity(intent)
    // } catch (e: ActivityNotFoundException) {
    //     // 处理异常
    // }
}

<manifest>
    <!-- 声明你的应用需要查询哪些类型的 Intent -->
    <queries>
        <!-- 方式一：声明具体的 Intent 签名 -->
        <intent>
            <action android:name="android.intent.action.SEND" />
            <data android:mimeType="image/*" />
        </intent>
        
        <!-- 方式二：声明具体的包名 -->
        <package android:name="com.example.otherapp" />
    </queries>
    
    <!-- 或者使用 QUERY_ALL_PACKAGES 权限（Google Play 审核严格） -->
    <!-- <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" /> -->
</manifest>

// Android Framework 源码（简化）
// 位于 Instrumentation.java
public ActivityResult execStartActivity(..., Intent intent, ...) {
    // ...
    // 如果 Intent 没有显式指定 Component，且没有设置 CATEGORY_DEFAULT
    // 系统会自动添加
    if (intent.getComponent() == null) {
        intent.addCategory(Intent.CATEGORY_DEFAULT);
    }
    // ...
}

<!-- ❌ 错误示例：忘记声明 CATEGORY_DEFAULT -->
<activity android:name=".BadActivity" android:exported="true">
    <intent-filter>
        <action android:name="com.example.action.SHOW_DETAIL" />
        <!-- 缺少 <category android:name="android.intent.category.DEFAULT" /> -->
        <!-- 结果：隐式 Intent 永远匹配不到这个 Activity -->
    </intent-filter>
</activity>
 
<!-- ✅ 正确示例：包含 CATEGORY_DEFAULT -->
<activity android:name=".GoodActivity" android:exported="true">
    <intent-filter>
        <action android:name="com.example.action.SHOW_DETAIL" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- 现在隐式 Intent 可以正确匹配到这个 Activity -->
    </intent-filter>
</activity>

// 混合策略示例：优先用显式 Intent 打开特定应用，fallback 到隐式 Intent
fun openMap(latitude: Double, longitude: Double) {
    // 构造地图 URI
    val geoUri = Uri.parse("geo:$latitude,$longitude")
    
    // 尝试显式启动 Google Maps
    val explicitIntent = Intent(Intent.ACTION_VIEW, geoUri).apply {
        setPackage("com.google.android.apps.maps")  // 限定包名（半显式）
    }
    
    if (explicitIntent.resolveActivity(packageManager) != null) {
        // Google Maps 已安装，直接启动
        startActivity(explicitIntent)
    } else {
        // Google Maps 未安装，使用隐式 Intent 让用户选择其他地图应用
        val implicitIntent = Intent(Intent.ACTION_VIEW, geoUri)
        if (implicitIntent.resolveActivity(packageManager) != null) {
            startActivity(implicitIntent)
        } else {
            // 没有任何地图应用，fallback 到 WebView
            openInWebView("https://maps.google.com/?q=$latitude,$longitude")
        }
    }
}

<activity android:name=".ViewerActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <action android:name="android.intent.action.EDIT" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="example.com" />
    </intent-filter>
</activity>

val intent = Intent(Intent.ACTION_VIEW).apply {
    data = Uri.parse("https://example.com/page")
    addCategory(Intent.CATEGORY_BROWSABLE)
}
startActivity(intent)

// BaseBundle 核心字段（简化）
class BaseBundle {
    // "活跃态"：键值对存储在内存中的 ArrayMap
    ArrayMap<String, Object> mMap;
    
    // "传输态"：序列化后的 Parcel 数据（跨进程传输用）
    Parcel mParcelledData;
    
    // 延迟解包：首次读取时才将 Parcel 反序列化为 ArrayMap
    void unparcel() {
        // 如果 mParcelledData 不为空，说明数据还在 Parcel 中
        if (mParcelledData != null) {
            // 从 Parcel 中逐个读取键值对，填充到 mMap
            // 读取完成后将 mParcelledData 置空，释放 Parcel 内存
            mMap = new ArrayMap<>();
            mParcelledData.readArrayMapInternal(mMap, ...);
            mParcelledData.recycle();
            mParcelledData = null;
        }
    }
}

// Intent.putExtra() 的简化实现逻辑
fun putExtra(name: String, value: String): Intent {
    // 如果 mExtras 尚未初始化，先创建一个空 Bundle
    if (mExtras == null) {
        mExtras = Bundle()
    }
    // 委托给 Bundle 的 putString() 方法
    mExtras!!.putString(name, value)
    // 返回 this 以支持链式调用
    return this
}

// 定义一个专门管理 Intent Extra Key 的常量对象
object UserExtras {
    // Key 常量：统一命名，避免拼写错误
    const val KEY_USER_ID = "com.example.extra.USER_ID"       // Long 类型
    const val KEY_USER_NAME = "com.example.extra.USER_NAME"   // String 类型
    const val KEY_USER_AGE = "com.example.extra.USER_AGE"     // Int 类型
 
    // 封装写入方法：确保类型正确
    fun Intent.putUserData(id: Long, name: String, age: Int): Intent {
        // 使用明确的类型方法写入，避免类型混淆
        putExtra(KEY_USER_ID, id)       // putExtra(String, Long)
        putExtra(KEY_USER_NAME, name)   // putExtra(String, String)
        putExtra(KEY_USER_AGE, age)     // putExtra(String, Int)
        return this
    }
 
    // 封装读取方法：确保类型正确，提供默认值
    fun Intent.getUserId(): Long {
        // getLongExtra 第二个参数是默认值，key 不存在时返回 -1L
        return getLongExtra(KEY_USER_ID, -1L)
    }
 
    fun Intent.getUserName(): String? {
        // getStringExtra 返回 nullable，调用方需处理 null
        return getStringExtra(KEY_USER_NAME)
    }
 
    fun Intent.getUserAge(): Int {
        // getIntExtra 第二个参数是默认值
        return getIntExtra(KEY_USER_AGE, 0)
    }
}

// 异常定义（Android Framework 源码简化）
public class TransactionTooLargeException extends RemoteException {
    // 当 Binder 事务的数据或返回值超过缓冲区限制时抛出
    // The Binder transaction buffer has a limited fixed size,
    // currently 1MB, which is shared by all transactions in
    // progress for the process.
}

// 反面示例：在 Intent 中传递大量数据（危险！）
fun startDetailActivity(context: Context, hugeList: List<UserProfile>) {
    val intent = Intent(context, DetailActivity::class.java)
    // ❌ 错误：将大列表直接放入 Intent
    // 如果 hugeList 包含数百个对象，序列化后可能超过 1MB
    intent.putParcelableArrayListExtra(
        "user_list",
        ArrayList(hugeList) // 每个 UserProfile 序列化后可能有几KB
    )
    // 这里可能抛出 TransactionTooLargeException
    context.startActivity(intent)
}
 
// 正面示例：只传递 ID，让目标页面自行加载数据
fun startDetailActivitySafely(context: Context, userId: Long) {
    val intent = Intent(context, DetailActivity::class.java)
    // ✅ 正确：只传递轻量级的标识符
    // Long 类型仅占 8 字节，远低于 Binder 缓冲区限制
    intent.putExtra("user_id", userId)
    context.startActivity(intent)
}
 
// 目标 Activity 通过 Repository/ViewModel 加载完整数据
class DetailActivity : AppCompatActivity() {
    // 使用 ViewModel 管理数据加载，避免在 Intent 中传递大对象
    private val viewModel: DetailViewModel by viewModels()
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 从 Intent 中只取出轻量级的 ID
        val userId = intent.getLongExtra("user_id", -1L)
        // 委托 ViewModel 从数据库/网络加载完整数据
        viewModel.loadUser(userId)
    }
}

// 反面示例：在 onSaveInstanceState 中保存大量数据
override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    // ❌ 错误：保存完整的列表数据
    // 当列表很长时，序列化后的数据量可能非常大
    outState.putParcelableArrayList("cached_items", ArrayList(adapter.items))
}
 
// 正面示例：只保存必要的恢复信息
override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    // ✅ 正确：只保存恢复所需的最小信息
    // 列表的滚动位置（几个字节）
    outState.putInt("scroll_position", layoutManager.findFirstVisibleItemPosition())
    // 当前的筛选条件（几十个字节）
    outState.putString("filter_query", currentQuery)
    // 完整数据由 ViewModel（进程内存活）或 Repository（持久化）管理
}

// 工具方法：估算 Bundle 序列化后的字节大小
fun Bundle.estimateSizeInBytes(): Int {
    // 创建一个 Parcel 对象用于模拟序列化
    val parcel = Parcel.obtain()
    try {
        // 将 Bundle 写入 Parcel（触发完整序列化）
        writeToParcel(parcel, 0)
        // Parcel 的 dataSize() 返回已写入数据的字节数
        val sizeInBytes = parcel.dataSize()
        return sizeInBytes
    } finally {
        // 必须回收 Parcel 对象，避免内存泄漏
        // Parcel 内部使用对象池（object pool）复用实例
        parcel.recycle()
    }
}
 
// 在 Debug 模式下使用
override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    // 保存必要状态...
    outState.putString("query", currentQuery)
 
    // Debug 模式下检查 Bundle 大小
    if (BuildConfig.DEBUG) {
        val size = outState.estimateSizeInBytes()
        // 如果超过 500KB，输出警告日志
        if (size > 500 * 1024) {
            Log.w("BundleSize",
                "onSaveInstanceState Bundle 过大: ${size / 1024}KB，" +
                "存在 TransactionTooLargeException 风险！")
        }
    }
}

// ActivityThread 中的相关逻辑（Android 8.0+，简化）
// 当 Activity 停止时，系统会检查 onSaveInstanceState 的 Bundle 大小
private void callActivityOnStop(ActivityClientRecord r, boolean saveState) {
    // ... 调用 onStop 和 onSaveInstanceState ...
    if (saveState) {
        // 执行状态保存
        performSaveInstanceState(r);
        // Android 8.0+ 新增：检查保存的状态大小
        // 如果超过限制，直接抛出异常而非静默忽略
        checkStateSizeForTooLarge(r);
    }
}
 
// 检查方法：将 Bundle 序列化为 Parcel 并检查大小
private void checkStateSizeForTooLarge(ActivityClientRecord r) {
    // 如果 Bundle 不为空，计算其序列化大小
    if (r.state != null) {
        Parcel p = Parcel.obtain();
        r.state.writeToParcel(p, 0);
        int size = p.dataSize();
        p.recycle();
        // 超过阈值时抛出 TransactionTooLargeException
        // 注意：实际阈值由 Binder 缓冲区决定，这里是简化表示
        if (size > TRANSACTION_SIZE_LIMIT) {
            throw new TransactionTooLargeException(
                "Bundle size: " + size + " bytes exceeds limit"
            );
        }
    }
}

// ❌ 反面示例：一个看似无害但暗藏杀机的实现
class NewsListActivity : AppCompatActivity() {
    // 适配器持有所有已加载的新闻数据
    private val newsList = mutableListOf<NewsItem>() // NewsItem 实现了 Parcelable
 
    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        // 看起来很合理：保存列表数据，恢复时不用重新加载
        // 但如果用户已经滚动加载了 500 条新闻，每条约 2KB
        // 总大小 = 500 × 2KB = 1000KB ≈ 1MB → 💥 崩溃！
        outState.putParcelableArrayList("news_list", ArrayList(newsList))
    }
}
 
// ✅ 正面示例：正确的架构设计
class NewsListActivity : AppCompatActivity() {
    // 使用 ViewModel 持有数据，配置变更（如旋转屏幕）时不会丢失
    private val viewModel: NewsListViewModel by viewModels()
 
    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        // 只保存恢复所需的最小信息
        outState.putInt("page", viewModel.currentPage)           // 4 字节
        outState.putInt("scroll_pos", getScrollPosition())       // 4 字节
        outState.putString("category", viewModel.currentCategory) // 几十字节
        // 总计不到 100 字节，完全安全
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (savedInstanceState != null) {
            // 从 savedInstanceState 恢复页码和分类
            val page = savedInstanceState.getInt("page", 1)
            val category = savedInstanceState.getString("category", "all")
            // 让 ViewModel 重新加载数据（可能从本地缓存中快速恢复）
            viewModel.restoreState(page, category)
        }
        // 观察 ViewModel 的数据流，更新 UI
        viewModel.newsItems.observe(this) { items ->
            adapter.submitList(items)
        }
    }
}

┌─────────────────────────────────────────────────────┐
│           Binder Transaction Buffer (1MB)           │
│                   进程级别共享                        │
│  ┌───────────────────────────────────────────────┐  │
│  │  系统服务通信开销（生命周期、窗口、输入事件）        │  │
│  │  ≈ 动态变化，不可预测                            │  │
│  ├───────────────────────────────────────────────┤  │
│  │  Intent 元数据（Action, Category, Flags...）    │  │
│  │  ≈ 几百字节到几KB                               │  │
│  ├───────────────────────────────────────────────┤  │
│  │  Bundle Extras（你放入的数据）                   │  │
│  │  ← 你能控制的部分，尽量保持在 100KB 以内           │  │
│  ├───────────────────────────────────────────────┤  │
│  │  Parcel 序列化开销（类型标记、对齐填充）           │  │
│  │  ≈ 数据量的 10%~30%                            │  │
│  ├───────────────────────────────────────────────┤  │
│  │  其他并发 Binder 事务占用                        │  │
│  │  ≈ 不可预测                                    │  │
│  └───────────────────────────────────────────────┘  │
│  实际可用空间 << 1MB，安全阈值建议 ≤ 500KB              │
└─────────────────────────────────────────────────────┘

// 实现 Serializable 的标准写法
class UserProfile : Serializable {
 
    // 显式声明 serialVersionUID，防止类结构变化导致反序列化失败
    // 这个值在类首次定义时设定，后续版本迭代中保持不变
    companion object {
        private const val serialVersionUID: Long = 1L
    }
 
    // 普通字段：会被自动序列化
    var userName: String = ""
 
    // 普通字段：会被自动序列化
    var age: Int = 0
 
    // transient 标记的字段：不参与序列化，反序列化后为默认值（null）
    // 适用于缓存、临时计算结果等不需要持久化的数据
    @Transient
    var cachedAvatar: Bitmap? = null
 
    // 自定义序列化逻辑：可以覆盖默认的反射行为
    // 当需要加密、压缩、或兼容旧版本数据格式时使用
    private fun writeObject(out: java.io.ObjectOutputStream) {
        // 先调用默认的序列化逻辑，处理所有非 transient 字段
        out.defaultWriteObject()
        // 可以在这里追加自定义数据
        out.writeUTF("extra_data_v2")
    }
 
    // 自定义反序列化逻辑：与 writeObject 配对使用
    private fun readObject(input: java.io.ObjectInputStream) {
        // 先调用默认的反序列化逻辑，恢复所有非 transient 字段
        input.defaultReadObject()
        // 读取自定义追加的数据
        val extra = input.readUTF()
    }
}

// 一个表示地理位置信息的数据类，需要通过 Intent 在组件间传递
class LocationInfo : Parcelable {
 
    // 纬度
    var latitude: Double = 0.0
 
    // 经度
    var longitude: Double = 0.0
 
    // 位置名称，可能为 null
    var placeName: String? = null
 
    // 时间戳
    var timestamp: Long = 0L
 
    // 是否为精确定位
    var isPrecise: Boolean = false
 
    // 标签列表
    var tags: List<String> = emptyList()
 
    // 主构造函数：常规创建对象时使用
    constructor(
        latitude: Double,
        longitude: Double,
        placeName: String?,
        timestamp: Long,
        isPrecise: Boolean,
        tags: List<String>
    ) {
        this.latitude = latitude
        this.longitude = longitude
        this.placeName = placeName
        this.timestamp = timestamp
        this.isPrecise = isPrecise
        this.tags = tags
    }
 
    // Parcel 构造函数：从 Parcel 中恢复对象时使用
    // 读取顺序必须与 writeToParcel() 的写入顺序完全一致
    constructor(parcel: Parcel) {
        // 读取 Double 类型的纬度（对应 writeDouble）
        latitude = parcel.readDouble()
        // 读取 Double 类型的经度（对应 writeDouble）
        longitude = parcel.readDouble()
        // 读取可空 String（对应 writeString）
        // readString() 能正确处理 null 值，写入时如果是 null 会写入 -1 作为长度标记
        placeName = parcel.readString()
        // 读取 Long 类型的时间戳（对应 writeLong）
        timestamp = parcel.readLong()
        // Parcel 没有 readBoolean()（API 29 之前），通常用 readInt() 模拟
        // 0 表示 false，非 0 表示 true（API 29+ 可直接用 readBoolean()）
        isPrecise = parcel.readInt() != 0
        // 读取 String 列表（对应 writeStringList）
        // createStringArrayList() 会创建新的 ArrayList 并填充数据
        tags = parcel.createStringArrayList() ?: emptyList()
    }
 
    // 将对象的字段逐个写入 Parcel
    // flags 参数通常为 0，当对象包含文件描述符时为 PARCELABLE_WRITE_RETURN_VALUE
    override fun writeToParcel(dest: Parcel, flags: Int) {
        // 写入 Double 类型的纬度，占 8 字节
        dest.writeDouble(latitude)
        // 写入 Double 类型的经度，占 8 字节
        dest.writeDouble(longitude)
        // 写入可空 String，内部会先写入字符串长度（int），再写入 UTF-16 编码的字符数据
        // 如果为 null，只写入 -1 作为长度标记
        dest.writeString(placeName)
        // 写入 Long 类型的时间戳，占 8 字节
        dest.writeLong(timestamp)
        // 写入 Boolean，转换为 Int（true=1, false=0），占 4 字节
        dest.writeInt(if (isPrecise) 1 else 0)
        // 写入 String 列表，内部会先写入列表长度，再逐个写入每个 String
        dest.writeStringList(tags)
    }
 
    // 描述特殊对象类型，通常返回 0
    // 如果对象包含文件描述符（FileDescriptor），需要返回 CONTENTS_FILE_DESCRIPTOR
    override fun describeContents(): Int = 0
 
    // CREATOR 是 Parcelable 协议的核心：一个静态工厂对象
    // Android 框架通过这个工厂来创建对象实例，而不是通过反射
    companion object CREATOR : Parcelable.Creator<LocationInfo> {
 
        // 从 Parcel 中创建单个对象实例
        // 框架在反序列化时调用此方法
        override fun createFromParcel(parcel: Parcel): LocationInfo {
            // 委托给 Parcel 构造函数
            return LocationInfo(parcel)
        }
 
        // 创建指定大小的对象数组
        // 框架在反序列化 Parcelable 数组时调用此方法
        override fun newArray(size: Int): Array<LocationInfo?> {
            // 返回一个元素全为 null 的数组，框架会逐个填充
            return arrayOfNulls(size)
        }
    }
}

// 假设 LocationInfo 已经实现了 Parcelable
class TravelRecord : Parcelable {
 
    // 旅行名称
    var tripName: String = ""
 
    // 出发地点：嵌套的 Parcelable 对象
    var departure: LocationInfo? = null
 
    // 目的地点：嵌套的 Parcelable 对象
    var destination: LocationInfo? = null
 
    constructor()
 
    constructor(parcel: Parcel) {
        // 读取旅行名称
        tripName = parcel.readString() ?: ""
        // 读取嵌套的 Parcelable 对象
        // 必须传入 ClassLoader，否则在某些情况下（如跨进程）会找不到类
        // LocationInfo::class.java.classLoader 获取加载 LocationInfo 的类加载器
        departure = parcel.readParcelable(LocationInfo::class.java.classLoader)
        // 同样方式读取第二个嵌套对象
        destination = parcel.readParcelable(LocationInfo::class.java.classLoader)
    }
 
    override fun writeToParcel(dest: Parcel, flags: Int) {
        // 写入旅行名称
        dest.writeString(tripName)
        // 写入嵌套的 Parcelable 对象
        // writeParcelable 内部会先写入类名（用于反序列化时定位 CREATOR），
        // 然后调用对象的 writeToParcel() 方法
        dest.writeParcelable(departure, flags)
        // 写入第二个嵌套对象
        dest.writeParcelable(destination, flags)
    }
 
    override fun describeContents(): Int = 0
 
    companion object CREATOR : Parcelable.Creator<TravelRecord> {
        override fun createFromParcel(parcel: Parcel): TravelRecord = TravelRecord(parcel)
        override fun newArray(size: Int): Array<TravelRecord?> = arrayOfNulls(size)
    }
}

// 优化写法：跳过类名写入，直接序列化
override fun writeToParcel(dest: Parcel, flags: Int) {
    dest.writeString(tripName)
    // 先写入一个标记位表示对象是否为 null（1=非null, 0=null）
    dest.writeInt(if (departure != null) 1 else 0)
    // 如果非 null，直接调用其 writeToParcel，不写入类名
    departure?.writeToParcel(dest, flags)
    // 同样处理 destination
    dest.writeInt(if (destination != null) 1 else 0)
    destination?.writeToParcel(dest, flags)
}
 
// 优化读法：直接通过 CREATOR 创建，不需要反射查找
constructor(parcel: Parcel) {
    tripName = parcel.readString() ?: ""
    // 读取标记位判断是否为 null
    departure = if (parcel.readInt() != 0) {
        // 直接调用 CREATOR，无反射开销
        LocationInfo.CREATOR.createFromParcel(parcel)
    } else null
    destination = if (parcel.readInt() != 0) {
        LocationInfo.CREATOR.createFromParcel(parcel)
    } else null
}

// build.gradle.kts (Module level)
plugins {
    // Android 应用插件
    id("com.android.application")
    // Kotlin Android 插件
    id("org.jetbrains.kotlin.android")
    // Parcelize 编译器插件：启用 @Parcelize 注解处理
    // 这个插件会在编译期扫描 @Parcelize 注解并生成 Parcelable 实现代码
    id("kotlin-parcelize")
}

import android.os.Parcelable
import kotlinx.parcelize.Parcelize
 
// @Parcelize 注解告诉编译器：为这个类自动生成 Parcelable 实现
// 要求：必须是 data class 或普通 class，且主构造函数的所有参数都必须是属性（val/var）
@Parcelize
data class LocationInfo(
    // 主构造函数中的每个属性都会被自动序列化
    val latitude: Double,       // 纬度
    val longitude: Double,      // 经度
    val placeName: String?,     // 位置名称，支持可空类型
    val timestamp: Long,        // 时间戳
    val isPrecise: Boolean,     // 是否精确定位
    val tags: List<String>      // 标签列表，支持常见集合类型
) : Parcelable
// 就这样！不需要手写 writeToParcel()、CREATOR、Parcel 构造函数

// 编译器自动生成的 writeToParcel 方法（反编译后的 Java 代码）
@Override
public void writeToParcel(Parcel dest, int flags) {
    // 按主构造函数属性声明顺序逐个写入
    dest.writeDouble(this.latitude);    // 第 1 个属性
    dest.writeDouble(this.longitude);   // 第 2 个属性
    dest.writeString(this.placeName);   // 第 3 个属性（自动处理 null）
    dest.writeLong(this.timestamp);     // 第 4 个属性
    dest.writeInt(this.isPrecise ? 1 : 0); // 第 5 个属性（Boolean 转 Int）
    dest.writeStringList(this.tags);    // 第 6 个属性（String 列表）
}
 
// 编译器自动生成的 CREATOR 对象
public static final Parcelable.Creator<LocationInfo> CREATOR =
    new Parcelable.Creator<LocationInfo>() {
 
        @Override
        public LocationInfo createFromParcel(Parcel in) {
            // 按完全相同的顺序读取，然后调用主构造函数
            return new LocationInfo(
                in.readDouble(),                    // latitude
                in.readDouble(),                    // longitude
                in.readString(),                    // placeName
                in.readLong(),                      // timestamp
                in.readInt() != 0,                  // isPrecise
                in.createStringArrayList()          // tags
            );
        }
 
        @Override
        public LocationInfo[] newArray(int size) {
            return new LocationInfo[size];
        }
    };

@Parcelize
data class UserProfile(
    // 主构造函数中的属性：参与序列化
    val userId: String,
    val displayName: String,
    val email: String
) : Parcelable {
 
    // @IgnoredOnParcel 标记的属性不参与序列化
    // 反序列化后该属性会使用这里的默认值（null）
    @IgnoredOnParcel
    var cachedAvatarBitmap: android.graphics.Bitmap? = null
 
    // 计算属性天然不参与序列化（没有 backing field）
    val initials: String
        get() = displayName.take(2).uppercase()
}

import kotlinx.parcelize.Parceler
import kotlinx.parcelize.Parcelize
import kotlinx.parcelize.TypeParceler
import java.time.Instant
 
// 为 Instant 类型定义自定义序列化器
// Parceler<T> 接口要求实现 create() 和 T.write() 两个方法
object InstantParceler : Parceler<Instant> {
 
    // 从 Parcel 中读取数据并创建 Instant 对象
    override fun create(parcel: Parcel): Instant {
        // Instant 可以用 epochSecond + nano 两个 Long 值精确表示
        val epochSecond = parcel.readLong()
        val nano = parcel.readLong()
        return Instant.ofEpochSecond(epochSecond, nano)
    }
 
    // 将 Instant 对象写入 Parcel
    override fun Instant.write(parcel: Parcel, flags: Int) {
        // 将 Instant 拆解为两个 Long 值写入
        parcel.writeLong(epochSecond)
        parcel.writeLong(nano.toLong())
    }
}
 
// 使用 @TypeParceler 注解将自定义序列化器绑定到特定属性
@Parcelize
// 类级别的 @TypeParceler：该类中所有 Instant 类型的属性都使用 InstantParceler
@TypeParceler<Instant, InstantParceler>
data class EventRecord(
    val eventName: String,
    // 这个 Instant 属性会自动使用 InstantParceler 进行序列化
    val createdAt: Instant,
    // 这个也是
    val updatedAt: Instant
) : Parcelable

@Parcelize
data class MixedRecord(
    val name: String,
    // 仅对这个属性使用自定义序列化器
    @TypeParceler<Instant, InstantParceler>
    val timestamp: Instant
) : Parcelable

// 密封类作为基类，标记 @Parcelize
@Parcelize
sealed class PaymentMethod : Parcelable {
 
    // 子类也需要标记 @Parcelize
    @Parcelize
    data class CreditCard(
        val cardNumber: String,    // 卡号
        val expiryDate: String,    // 有效期
        val holderName: String     // 持卡人姓名
    ) : PaymentMethod()
 
    @Parcelize
    data class BankTransfer(
        val bankName: String,      // 银行名称
        val accountNumber: String  // 账号
    ) : PaymentMethod()
 
    @Parcelize
    data object Cash : PaymentMethod()  // 现金支付，无额外属性
}
 
// 使用时可以直接通过 Intent 传递多态对象
// intent.putExtra("payment", PaymentMethod.CreditCard("1234...", "12/25", "Zhang San"))
// val method = intent.getParcelableExtra<PaymentMethod>("payment")
// when (method) {
//     is PaymentMethod.CreditCard -> { /* 处理信用卡 */ }
//     is PaymentMethod.BankTransfer -> { /* 处理银行转账 */ }
//     is PaymentMethod.Cash -> { /* 处理现金 */ }
// }

@Parcelize
data class EventInfo(
    val title: String,
    val date: java.time.LocalDate,  // 注意：未提供 TypeParceler
    val priority: Int
) : Parcelable

// PendingIntentRecord 内部关键字段（简化表示）
// 这不是你能直接访问的 API，而是 Framework 内部结构
class PendingIntentRecord {
    // 创建者的 uid（用于权限校验，执行时以此身份执行）
    val callingUid: Int
    // 创建者的包名
    val callingPackage: String
    // 操作类型：INTENT_SENDER_ACTIVITY / BROADCAST / SERVICE
    val type: Int
    // 原始 Intent 数组（可以包含多个 Intent）
    val requestIntents: Array<Intent>
    // 请求码（requestCode）
    val requestCode: Int
    // Flag 标志位
    val flags: Int
    // Key 对象——用于判断两个 PendingIntent 是否"相同"
    val key: Key
}

// Android 12+ 必须显式指定可变性
 
// 推荐：不可变 PendingIntent（绝大多数场景应使用这个）
// 外部进程无法修改 Intent 的任何字段
val immutablePending = PendingIntent.getActivity(
    context,                          // 上下文，用于确定创建者身份
    requestCode,                      // 请求码，参与 PendingIntent 相等性判断
    intent,                           // 要执行的原始 Intent
    PendingIntent.FLAG_IMMUTABLE      // 标记为不可变，外部无法篡改
)
 
// 特殊场景：可变 PendingIntent（如内联回复通知需要填充用户输入）
// 仅在确实需要外部进程填充数据时使用
val mutablePending = PendingIntent.getBroadcast(
    context,                          // 上下文
    requestCode,                      // 请求码
    intent,                           // 原始 Intent
    PendingIntent.FLAG_MUTABLE        // 标记为可变，允许外部通过 fillIn() 修改
)

// 场景：聊天通知，每次更新携带最新消息 ID
fun buildChatNotificationPendingIntent(
    context: Context,
    chatId: String,       // 聊天会话 ID
    latestMessageId: String // 最新消息 ID
): PendingIntent {
    // 构建目标 Intent
    val intent = Intent(context, ChatActivity::class.java).apply {
        // Action 和 Data 参与 Key 相等性判断
        action = "com.example.OPEN_CHAT"          // 固定 Action
        putExtra("chat_id", chatId)               // Extra 不参与相等性判断
        putExtra("message_id", latestMessageId)   // 但会被 FLAG_UPDATE_CURRENT 更新
    }
 
    return PendingIntent.getActivity(
        context,
        chatId.hashCode(),    // 用 chatId 的 hashCode 作为 requestCode
                              // 不同会话产生不同的 PendingIntent
        intent,
        // FLAG_UPDATE_CURRENT：复用已有 Token，更新 Extras
        // FLAG_IMMUTABLE：禁止外部修改（Android 12+ 必须指定）
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )
}

// 场景：安全敏感操作，确保旧 Token 彻底失效
val securePending = PendingIntent.getActivity(
    context,
    SECURE_REQUEST_CODE,              // 固定请求码
    secureIntent,                     // 目标 Intent
    // FLAG_CANCEL_CURRENT：作废所有旧 Token，创建全新 Token
    // 旧 Token 持有者再调用 send() 会收到 CanceledException
    PendingIntent.FLAG_CANCEL_CURRENT or PendingIntent.FLAG_IMMUTABLE
)

// 场景：检查某个闹钟是否已经注册
fun isAlarmSet(context: Context, alarmIntent: Intent): Boolean {
    // FLAG_NO_CREATE：仅查询，不创建
    // 如果返回 null，说明该 PendingIntent 不存在（闹钟未设置）
    val existing = PendingIntent.getBroadcast(
        context,
        ALARM_REQUEST_CODE,           // 与注册时相同的请求码
        alarmIntent,                  // 与注册时 filterEquals 相同的 Intent
        PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE
    )
    return existing != null           // 非 null 表示已存在
}

// 场景：一次性验证操作，防止重放攻击
val oneTimePending = PendingIntent.getBroadcast(
    context,
    ONE_TIME_REQUEST_CODE,            // 请求码
    verificationIntent,               // 验证 Intent
    // FLAG_ONE_SHOT：只能触发一次，之后自动作废
    PendingIntent.FLAG_ONE_SHOT or PendingIntent.FLAG_IMMUTABLE
)

// ❌ 错误写法：所有通知共享同一个 PendingIntent
fun showNewsNotification(context: Context, newsId: String, title: String) {
    val intent = Intent(context, NewsDetailActivity::class.java).apply {
        action = "com.example.VIEW_NEWS"  // 所有通知的 Action 相同
        putExtra("news_id", newsId)       // 只有 Extra 不同
    }
 
    // 问题：requestCode 固定为 0
    // 所有通知的 Key 都相同（type + requestCode + filterEquals 全部一致）
    val pendingIntent = PendingIntent.getActivity(
        context,
        0,                                // ← 固定 requestCode = 0
        intent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )
 
    // 发送通知（使用不同的 notificationId 确保多条通知共存）
    val notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setContentTitle(title)           // 标题不同
        .setContentIntent(pendingIntent)  // 但 PendingIntent 相同！
        .setSmallIcon(R.drawable.ic_news)
        .build()
 
    // notificationId 不同，所以通知栏会显示多条通知
    NotificationManagerCompat.from(context)
        .notify(newsId.hashCode(), notification)
}

// ✅ 正确写法：每条通知使用不同的 requestCode
fun showNewsNotification(context: Context, newsId: String, title: String) {
    val intent = Intent(context, NewsDetailActivity::class.java).apply {
        action = "com.example.VIEW_NEWS"  // Action 可以相同
        putExtra("news_id", newsId)       // Extra 携带具体数据
    }
 
    // 关键：使用 newsId 的 hashCode 作为 requestCode
    // 不同新闻 → 不同 requestCode → 不同 Key → 独立的 PendingIntent
    val pendingIntent = PendingIntent.getActivity(
        context,
        newsId.hashCode(),                // ← 每条新闻不同的 requestCode
        intent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )
 
    val notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setContentTitle(title)
        .setContentIntent(pendingIntent)  // 每条通知有独立的 PendingIntent
        .setSmallIcon(R.drawable.ic_news)
        .setAutoCancel(true)              // 点击后自动取消通知
        .build()
 
    NotificationManagerCompat.from(context)
        .notify(newsId.hashCode(), notification)
}

// ✅ 另一种正确写法：通过 Data URI 区分
val intent = Intent(context, NewsDetailActivity::class.java).apply {
    // 不同的 Data URI → filterEquals() 返回 false → 不同的 Key
    data = Uri.parse("myapp://news/$newsId")  // 每条新闻有唯一 URI
    putExtra("news_id", newsId)
}
 
// 即使 requestCode 相同，Data 不同也会产生独立的 PendingIntent
val pendingIntent = PendingIntent.getActivity(
    context,
    0,                                        // requestCode 可以都是 0
    intent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
)

// 取消已注册的闹钟
fun cancelAlarm(context: Context) {
    val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
 
    // 必须构造一个与注册时 Key 相同的 PendingIntent
    val intent = Intent(context, AlarmReceiver::class.java).apply {
        action = "com.example.DAILY_ALARM"    // 与注册时相同的 Action
    }
 
    val pendingIntent = PendingIntent.getBroadcast(
        context,
        DAILY_ALARM_REQUEST_CODE,             // 与注册时相同的 requestCode
        intent,
        PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE
        // FLAG_NO_CREATE：如果不存在就返回 null，避免无谓创建
    )
 
    // 如果 PendingIntent 存在，取消闹钟并作废 Token
    pendingIntent?.let {
        alarmManager.cancel(it)               // 从 AlarmManager 中移除
        it.cancel()                           // 从 AMS 中作废 Token
    }
}

// Android 12+ 兼容写法
val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    // Android 12+ 必须显式指定
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
} else {
    // Android 12 以下可以不指定，但推荐也加上 FLAG_IMMUTABLE
    PendingIntent.FLAG_UPDATE_CURRENT
}
 
val pendingIntent = PendingIntent.getActivity(
    context,
    requestCode,
    intent,
    flags
)

/**
 * 每日提醒管理器
 * 综合演示 PendingIntent 在 AlarmManager 和 Notification 中的使用
 */
class DailyReminderManager(private val context: Context) {
 
    companion object {
        // 闹钟 PendingIntent 的请求码（用于唯一标识这个闹钟）
        private const val ALARM_REQUEST_CODE = 1001
        // 通知点击 PendingIntent 的请求码
        private const val NOTIFICATION_REQUEST_CODE = 2001
        // 通知渠道 ID
        private const val CHANNEL_ID = "daily_reminder"
        // 广播 Action
        const val ACTION_ALARM_TRIGGERED = "com.example.ACTION_DAILY_REMINDER"
    }
 
    /**
     * 设置每日提醒闹钟
     * @param hour 小时（24小时制）
     * @param minute 分钟
     */
    fun setDailyReminder(hour: Int, minute: Int) {
        // 获取 AlarmManager 系统服务
        val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
 
        // 构建闹钟触发时要发送的广播 Intent
        val alarmIntent = Intent(context, ReminderAlarmReceiver::class.java).apply {
            action = ACTION_ALARM_TRIGGERED        // 设置 Action，参与 Key 判断
            putExtra("hour", hour)                 // 附加提醒时间信息
            putExtra("minute", minute)             // Extra 不参与 Key 判断
        }
 
        // 创建闹钟用的 PendingIntent（类型为 Broadcast）
        // FLAG_UPDATE_CURRENT：如果已有相同闹钟，更新其 Extras
        // FLAG_IMMUTABLE：禁止外部修改（Android 12+ 强制要求）
        val alarmPendingIntent = PendingIntent.getBroadcast(
            context,
            ALARM_REQUEST_CODE,                    // 固定请求码，确保同一个闹钟可被更新/取消
            alarmIntent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )
 
        // 计算下一次触发的时间戳
        val calendar = Calendar.getInstance().apply {
            set(Calendar.HOUR_OF_DAY, hour)        // 设置目标小时
            set(Calendar.MINUTE, minute)            // 设置目标分钟
            set(Calendar.SECOND, 0)                 // 秒数归零
            set(Calendar.MILLISECOND, 0)            // 毫秒归零
            // 如果目标时间已过（今天的这个时刻已经过去），则推迟到明天
            if (timeInMillis <= System.currentTimeMillis()) {
                add(Calendar.DAY_OF_YEAR, 1)
            }
        }
 
        // Android 12+ 需要检查精确闹钟权限
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            if (alarmManager.canScheduleExactAlarms()) {
                // 有权限，设置精确重复闹钟
                alarmManager.setExactAndAllowWhileIdle(
                    AlarmManager.RTC_WAKEUP,       // 使用实际时间，到时唤醒设备
                    calendar.timeInMillis,          // 触发时间戳
                    alarmPendingIntent              // 触发时发送的 PendingIntent
                )
            } else {
                // 无权限，引导用户去设置页面授权
                // 实际项目中应该弹出对话框引导用户
                val settingsIntent = Intent(
                    Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
                )
                settingsIntent.flags = Intent.FLAG_ACTIVITY_NEW_TASK
                context.startActivity(settingsIntent)
            }
        } else {
            // Android 12 以下直接设置
            alarmManager.setExactAndAllowWhileIdle(
                AlarmManager.RTC_WAKEUP,
                calendar.timeInMillis,
                alarmPendingIntent
            )
        }
    }
 
    /**
     * 取消每日提醒
     */
    fun cancelDailyReminder() {
        val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
 
        // 构造与注册时 Key 相同的 Intent
        val alarmIntent = Intent(context, ReminderAlarmReceiver::class.java).apply {
            action = ACTION_ALARM_TRIGGERED        // 必须与注册时一致
        }
 
        // FLAG_NO_CREATE：仅查询是否存在，不创建新的
        val existingPending = PendingIntent.getBroadcast(
            context,
            ALARM_REQUEST_CODE,                    // 必须与注册时一致
            alarmIntent,
            PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE
        )
 
        // 如果存在，执行取消操作
        existingPending?.let { pending ->
            alarmManager.cancel(pending)           // 从 AlarmManager 移除闹钟
            pending.cancel()                       // 从 AMS 中作废 Token
        }
    }
 
    /**
     * 检查每日提醒是否已设置
     */
    fun isReminderSet(): Boolean {
        val alarmIntent = Intent(context, ReminderAlarmReceiver::class.java).apply {
            action = ACTION_ALARM_TRIGGERED
        }
 
        // FLAG_NO_CREATE 返回 null 表示不存在
        return PendingIntent.getBroadcast(
            context,
            ALARM_REQUEST_CODE,
            alarmIntent,
            PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE
        ) != null
    }
}
 
/**
 * 闹钟触发时的广播接收器
 * 负责接收闹钟广播并弹出通知
 */
class ReminderAlarmReceiver : BroadcastReceiver() {
 
    override fun onReceive(context: Context, intent: Intent) {
        // 验证 Action 是否匹配
        if (intent.action != DailyReminderManager.ACTION_ALARM_TRIGGERED) return
 
        // 创建通知渠道（Android 8.0+ 必须）
        createNotificationChannel(context)
 
        // 构建点击通知后要打开的 Activity Intent
        val clickIntent = Intent(context, ReminderDetailActivity::class.java).apply {
            // 设置 FLAG_ACTIVITY_NEW_TASK：从非 Activity 上下文启动 Activity 时必须
            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
            putExtra("triggered_at", System.currentTimeMillis())  // 附加触发时间
        }
 
        // 为通知点击创建 PendingIntent
        val clickPendingIntent = PendingIntent.getActivity(
            context,
            2001,                                  // 通知点击的请求码
            clickIntent,
            // FLAG_ONE_SHOT：通知只能点击一次（防止重复触发）
            // FLAG_IMMUTABLE：禁止外部修改
            PendingIntent.FLAG_ONE_SHOT or PendingIntent.FLAG_IMMUTABLE
        )
 
        // 构建并发送通知
        val notification = NotificationCompat.Builder(context, "daily_reminder")
            .setSmallIcon(R.drawable.ic_reminder)  // 小图标（必须设置）
            .setContentTitle("每日提醒")            // 通知标题
            .setContentText("点击查看今日提醒详情")   // 通知正文
            .setPriority(NotificationCompat.PRIORITY_HIGH)  // 高优先级（弹出横幅）
            .setContentIntent(clickPendingIntent)  // 设置点击行为
            .setAutoCancel(true)                   // 点击后自动消失
            .build()
 
        // 发送通知
        NotificationManagerCompat.from(context)
            .notify(1001, notification)            // notificationId 固定，新通知覆盖旧通知
 
        // 重新设置明天的闹钟（因为 setExactAndAllowWhileIdle 不会自动重复）
        val hour = intent.getIntExtra("hour", 9)
        val minute = intent.getIntExtra("minute", 0)
        DailyReminderManager(context).setDailyReminder(hour, minute)
    }
 
    /**
     * 创建通知渠道（Android 8.0+）
     */
    private fun createNotificationChannel(context: Context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel(
                "daily_reminder",                  // 渠道 ID
                "每日提醒",                         // 用户可见的渠道名称
                NotificationManager.IMPORTANCE_HIGH // 重要性级别（弹出横幅）
            ).apply {
                description = "每日定时提醒通知"     // 渠道描述
            }
            val manager = context.getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(channel)
        }
    }
}

// 使用 TaskStackBuilder 构建带完整返回栈的 PendingIntent
fun buildDeepLinkPendingIntent(
    context: Context,
    newsId: String
): PendingIntent {
    // 目标页面的 Intent
    val detailIntent = Intent(context, NewsDetailActivity::class.java).apply {
        putExtra("news_id", newsId)
    }
 
    // 使用 TaskStackBuilder 构建返回栈
    // 返回栈顺序：MainActivity → NewsListActivity → NewsDetailActivity
    return TaskStackBuilder.create(context)
        .addNextIntentWithParentStack(detailIntent)
        // addNextIntentWithParentStack 会自动读取 AndroidManifest.xml 中
        // 声明的 android:parentActivityName 来构建完整的父级链
        // 如果没有在 Manifest 中声明 parentActivity，需要手动添加：
        // .addNextIntent(Intent(context, MainActivity::class.java))
        // .addNextIntent(Intent(context, NewsListActivity::class.java))
        // .addNextIntent(detailIntent)
        .getPendingIntent(
            newsId.hashCode(),                     // 不同新闻不同的请求码
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )!!  // TaskStackBuilder 保证非 null（除非 FLAG_NO_CREATE）
}

val intent = Intent(context, ChatActivity::class.java)
intent.action = "OPEN_CHAT"
intent.putExtra("chat_id", chatId)
 
val pi = PendingIntent.getActivity(
    context, 0, intent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
)

// ========== Activity A：发起请求 ==========
class ActivityA : AppCompatActivity() {
 
    // 定义请求码常量，用于在 onActivityResult 中区分不同请求
    companion object {
        private const val REQUEST_PICK_CONTACT = 1001
    }
 
    // 启动 Activity B 并期望获取返回结果
    private fun pickContact() {
        // 创建显式 Intent，指向目标 Activity
        val intent = Intent(this, ContactPickerActivity::class.java)
        // 调用 startActivityForResult，传入 Intent 和请求码
        // 系统会在 AMS 中记录"A 等待来自 ContactPickerActivity 的结果"
        startActivityForResult(intent, REQUEST_PICK_CONTACT)
    }
 
    // 系统回调：当目标 Activity finish 后，结果会通过此方法传回
    override fun onActivityResult(
        requestCode: Int,   // 发起请求时传入的请求码
        resultCode: Int,    // 目标 Activity 通过 setResult 设置的结果码
        data: Intent?       // 目标 Activity 回传的数据载体，可能为 null
    ) {
        // 必须调用 super，确保 Fragment 等组件也能收到结果
        super.onActivityResult(requestCode, resultCode, data)
 
        // 通过 requestCode 判断这个结果对应哪个请求
        when (requestCode) {
            REQUEST_PICK_CONTACT -> {
                // 通过 resultCode 判断操作是否成功
                if (resultCode == RESULT_OK) {
                    // 从 data Intent 中提取回传的数据
                    val contactName = data?.getStringExtra("contact_name")
                    val contactPhone = data?.getStringExtra("contact_phone")
                    // 使用回传数据更新 UI
                    updateContactInfo(contactName, contactPhone)
                }
                // 如果 resultCode == RESULT_CANCELED，说明用户取消了选择
            }
        }
    }
 
    private fun updateContactInfo(name: String?, phone: String?) {
        // 更新界面显示逻辑
    }
}