ClipboardManager 全面解析与应用指南

1、核心体系结构

        Android剪贴板服务采用三层架构：

┌───────────────────────┐
│   Application Layer   │ ← 开发者交互层
├───────────────────────┤
│  ClipboardService     │ ← 系统服务中间层
├───────────────────────┤
│   Binder IPC Layer    │ ← 底层通信层
└───────────────────────┘

2、基础操作手册

2.1、获取系统服务

val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager

2.2、文本复制标准流程

fun copyText(content: String, label: String? = null) {
    val clipData = ClipData.newPlainText(label, content)
    clipboard.setPrimaryClip(clipData)
}

2.3、安全粘贴验证

fun pasteText(): String? {
    return if (clipboard.hasPrimaryClip() &&
        clipboard.primaryClipDescription?.hasMimeType(MIMETYPE_TEXT_PLAIN) == true) {
        clipboard.primaryClip?.getItemAt(0)?.text?.toString()
    } else null
}

3、高级内容处理

3.1、富文本数据处理

fun copyHtml(htmlText: String, plainTextFallback: String) {
    val clipData = ClipData.newHtmlText("HTML Content", plainTextFallback, htmlText)
    clipboard.setPrimaryClip(clipData)
}

3.2、Intent对象传输

fun copyIntent(targetIntent: Intent) {
    val clipData = ClipData.newIntent("Activity Intent", targetIntent)
    clipboard.setPrimaryClip(clipData)
}

3.3、自定义复杂数据

fun copyCustomData(dataBundle: Bundle) {
    val clipData = ClipData.newUri(
        context.contentResolver,
        "Custom Data",
        Uri.parse("content://${context.packageName}/custom")
    ).apply {
        this.getItemAt(0).also { it.intent = Intent().putExtras(dataBundle) }
    }
    clipboard.setPrimaryClip(clipData)
}

4、监听机制详解

4.1、传统广播监听（兼容旧版）

<!-- AndroidManifest.xml -->
<receiver android:name=".ClipboardReceiver">
    <intent-filter>
        <action android:name="android.intent.action.CLIPBOARD_CHANGED"/>
    </intent-filter>
</receiver>

4.2、现代回调监听（API 33+）

val listener = ClipboardManager.OnPrimaryClipChangedListener {
    analyzeCurrentClip()
}

// 注册监听
clipboard.addPrimaryClipChangedListener(listener)

// 注销监听
clipboard.removePrimaryClipChangedListener(listener)

5、企业级开发规范

5.1、安全防护措施

// 敏感信息过滤
fun safeCopy(text: String) {
    val filtered = text.replace(Regex("\\d{4}-\\d{2}-\\d{4}"), "***")
    copyText(filtered)
}

// 客户端加密处理
fun encryptCopy(raw: String, key: SecretKey) {
    val encrypted = CryptoUtils.aesEncrypt(raw.toByteArray(), key)
    copyText(Base64.encodeToString(encrypted, Base64.NO_WRAP))
}

5.1、性能优化方案

// 大文件URI传输替代方案
fun copyLargeFile(file: File) {
    val uri = FileProvider.getUriForFile(context, "${context.packageName}.provider", file)
    val clipData = ClipData.newUri(context.contentResolver, "Large File", uri)
    clipboard.setPrimaryClip(clipData.apply {
        intent.flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
    })
}

6、各版本适配要点

        API Level 关键变更点 适配方案

        ≤28 后台应用无法读取剪贴板 使用ContentObserver代理监控

        ≥29 限制后台访问 申请CLIPBOARD_MANAGER权限

        ≥31 剪贴板访问通知 实现ClipboardCallback接口

        ≥33 新增图像复制能力 使用newImageClip方法族

7、调试诊断技巧

        剪贴板内容检测

adb shell cmd clipboard get

        历史记录追踪

fun dumpClipHistory() {
    clipboard.primaryClip?.run {
        (0 until itemCount).forEach { i ->
            Log.d("CLIP", "Item$i: ${getItemAt(i).coerceToText(context)}")
        }
    }
}

        权限验证工具

fun checkClipPermission(): Boolean {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        clipboard.isRequestPinAppEnabled()
    } else true
}

        最佳实践建议：对于金融类应用，应采用时效性剪贴板策略，设置自动清除时间窗口（如30秒后自动清空），可通过Handler.postDelayed结合clearPrimaryClip()实现。