📚 课程目录第4章自定义防截屏TextField核心设计

4. 自定义防截屏TextField核心设计：组件职责、外部接口、状态管理、安全策略注入

本章聚焦防截屏TextField的核心设计层次，明确组件职责边界、外部接口契约、内部状态管理方案以及安全策略的注入机制。所有设计方案均面向Jetpack Compose运行时特性，确保组件在SurfaceView、FLAG_SECURE、平台截屏监听等多重安全策略下可灵活切换，同时保持TextField标准的输入、焦点、光标操作体验。

4.1 组件职责与分层架构

防截屏TextField由三层职责构成，各层之间通过Compose的Modifier链和状态提升进行解耦。下表列出各层角色与对外暴露能力：

层	职责	关键接口 / 类型
交互层	处理输入事件、焦点管理、光标控制	`TextFieldValue`, `FocusRequester`, `KeyboardActions`
安全策略层	注入防截屏策略（FLAG_SECURE / SurfaceView / 定时截屏检测）	`ScreenCaptureStrategy`, `Modifier.screenCaptureSafe()`
视觉层	绘制安全水印、着色器遮盖、截屏时遮盖	`SecureVisualTransformation`, `Modifier.secureOverlay()`

  核心原则：交互层不依赖任何安全逻辑，安全策略层通过组合Modifier插入到Compose tree中，视觉层仅在激活截屏保护时生效，三者通过CompositionLocal共享安全状态。

4.2 外部接口设计

组件对外暴露一个顶层可组合函数SecureTextField，它封装了所有内部实现。调用方只需传入输入状态和策略参数：

@Composable
fun SecureTextField(
    value: TextFieldValue,
    onValueChange: (TextFieldValue) -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    readOnly: Boolean = false,
    textStyle: TextStyle = TextStyle.Default,
    label: @Composable (() -> Unit)? = null,
    placeholder: @Composable (() -> Unit)? = null,
    leadingIcon: @Composable (() -> Unit)? = null,
    trailingIcon: @Composable (() -> Unit)? = null,
    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
    keyboardActions: KeyboardActions = KeyboardActions.Default,
    singleLine: Boolean = false,
    maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
    visualTransformation: VisualTransformation = VisualTransformation.None,
    screenCaptureStrategy: ScreenCaptureStrategy = ScreenCaptureStrategy.FLAG_SECURE,
    securityLevel: SecurityLevel = SecurityLevel.STANDARD
)

其中ScreenCaptureStrategy是一个密封类，定义了三种内置策略：

sealed class ScreenCaptureStrategy {
    object FLAG_SECURE : ScreenCaptureStrategy()
    data class SurfaceWindow(val surfaceWidth: Int, val surfaceHeight: Int) : ScreenCaptureStrategy()
    data class Custom(val block: (CompositionContext) -> Unit) : ScreenCaptureStrategy()
}

enum class SecurityLevel {
    STANDARD,   // 仅FLAG_SECURE + 基础水印
    HIGH,       // SurfaceView + 随机遮盖像素
    MAXIMUM     // 全屏定时截屏检测 + 强制清除剪贴板
}

接口设计要点：visualTransformation参数保留给外部自定义输入过滤器，组件内部会利用Compose的VisualTransformation链式组合，将安全遮盖转换追加到用户提供的转换之后。调用方无需感知底层安全实现。

4.3 状态管理

组件采用局部状态 + 全局安全状态的双层状态模型：

局部状态：TextFieldValue（输入文本、选择范围、组合键）、FocusState、ImeAction，由remember { mutableStateOf(...) }管理，通过onValueChange回传。
全局安全状态：通过CompositionLocalProvider注入SecureState，包含当前截屏检测标记、遮盖层可见性、策略激活状态。所有子组件通过LocalSecureState.current读取。

data class SecureState(
    val isScreenCapturing: Boolean = false,
    val overlayAlpha: Float = 0f,
    val strategy: ScreenCaptureStrategy = ScreenCaptureStrategy.FLAG_SECURE,
    val lastCaptureTime: Long = 0L
)

val LocalSecureState = staticCompositionLocalOf { SecureState() }

状态更新由内部ScreenCaptureDetector协程监听系统截屏广播和像素缓冲变化触发，具体流程图见本章SVG。

4.4 安全策略注入机制

策略注入采用Compose的Modifier.composed设计模式：

fun Modifier.screenCaptureSafe(
    strategy: ScreenCaptureStrategy,
    securityLevel: SecurityLevel
): Modifier = composed {
    val secureState = LocalSecureState.current
    val context = LocalContext.current

    // 1. FLAG_SECURE注入（在Activity或Dialog窗口）
    if (strategy is ScreenCaptureStrategy.FLAG_SECURE) {
        DisposableEffect(context) {
            val window = (context as? Activity)?.window
            window?.setFlags(WindowManager.LayoutParams.FLAG_SECURE,
                WindowManager.LayoutParams.FLAG_SECURE)
            onDispose {
                window?.clearFlags(WindowManager.LayoutParams.FLAG_SECURE)
            }
        }
    }

    // 2. SurfaceView替换（用于输入区域包裹）
    if (strategy is ScreenCaptureStrategy.SurfaceWindow) {
        val surfaceView = remember {
            SurfaceView(context).apply {
                setWillNotDraw(false)
                layoutParams = ViewGroup.LayoutParams(
                    strategy.surfaceWidth, strategy.surfaceHeight
                )
            }
        }
        AndroidView(factory = { surfaceView })
    }

    // 3. 遮盖层注入
    if (secureState.isScreenCapturing) {
        this.then(Modifier.secureOverlay(securityLevel))
    } else {
        this
    }
}

稳定性和内存泄漏风险：FLAG_SECURE设置必须在DisposableEffect中保证Dispose时清除。SurfaceView方案中需要手动管理ViewGroup的addView/removeView生命周期。建议结合LifecycleEventEffect兜底。

4.5 内联SVG：防截屏TextField状态管理流程

下图展示从用户输入到安全策略拦截的完整状态流转，包含局部状态、全局安全状态和策略注入节点：

4.6 调试与常见错误

核心设计阶段易出现的错误及其快速定位方法：

错误表现	根本原因	调试手段
输入框无法获取焦点	SurfaceView覆盖导致`FocusRequester`未正确传递	检查`Modifier.focusRequester()`是否在`composed`外部
FLAG_SECURE泄漏到其他组件	`DisposableEffect`未在`Dispose`时清除策略	在`onDispose`中添加断点确认`clearFlags`被调用
遮盖层在截屏结束后仍显示	安全状态未能及时回退	打印`State`快照日志，检查协程作用域

4.7 性能与稳定性优化

  关键优化点：策略注入采用Modifier.composed可避免重组时重复创建策略对象；全局安全状态使用staticCompositionLocalOf减少不必要的子组件重组；截屏检测使用callbackFlow配合snapshotFlow做线程安全的状态同步。

将ScreenCaptureDetector的协程生命周期绑定到rememberLifecycleEvent，避免后台持续监听。
使用derivedStateOf对isScreenCapturing做节流，防止遮盖层alpha值每帧抖动。
SurfaceView方案中，通过AndroidView的update回调复用已有View实例，避免频繁addView/removeView。

实际集成测试时，建议在Android模拟器上使用adb shell screencap -p /sdcard/screenshot.png触发截屏，结合Logcat过滤“SecureTextField”标签验证策略触发时序。