第3章 基础键盘布局实现：Grid布局、按钮组件封装、触摸反馈、按键音与震动控制

3.1 原理概述

支付安全键盘需要在用户输入时提供流畅、可靠的交互体验，同时防止屏幕录制或共享导致的密码泄露。基础键盘布局是实现安全输入的基石，核心挑战在于：等距网格、组件复用、瞬时反馈三个维度的统一。

Jetpack Compose 提供了多种网格布局方案，但支付键盘具有固定按键数量（12~16键）和严格行列对齐的特点，因此布局方案的选择直接影响性能与可维护性。

防录屏对布局的特殊要求：按键标签必须在 Compose 层级中独立控制渲染，不得使用系统键盘或 WebView 内嵌输入，以便后续叠加安全遮罩与随机乱序策略。

3.2 Grid 布局实现

基于 Column + Row 组合实现 3 列 × 4 行的数字键盘网格。关键点在于：每行使用 weight(1f) 等分宽度，通过 Arrangement.spacedBy 控制间距，并用 aspectRatio 固定按键比例。

@Composable
fun PayKeyboardGrid(
    onKeyPress: (String) -> Unit,
    modifier: Modifier = Modifier
) {
    val keys = listOf(
        listOf("1", "2", "3"),
        listOf("4", "5", "6"),
        listOf("7", "8", "9"),
        listOf("清除", "0", "确认")
    )

    Column(
        modifier = modifier.fillMaxWidth(),
        verticalArrangement = Arrangement.spacedBy(10.dp)
    ) {
        keys.forEach { row ->
            Row(
                modifier = Modifier.fillMaxWidth(),
                horizontalArrangement = Arrangement.spacedBy(10.dp)
            ) {
                row.forEach { label ->
                    KeyButton(
                        label = label,
                        onClick = { onKeyPress(label) },
                        modifier = Modifier.weight(1f)
                    )
                }
            }
        }
    }
}

• 等分布局：Modifier.weight(1f) 确保每行三键宽度一致，无需手动计算像素。
• 间距控制：Arrangement.spacedBy(10.dp) 统一行列间距，视觉对齐。
• 比例锁定：按键通过 Modifier.aspectRatio(1.5f) 固定宽高比，适配不同屏幕。

3.3 按钮组件封装

设计一个可复用的 KeyButton 组件，统一管理按键的显示样式、按压状态与点击回调。组件接口如下：

@Composable
fun KeyButton(
    label: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    isSpecial: Boolean = false,
    onLongClick: (() -> Unit)? = null
) {
    var isPressed by remember { mutableStateOf(false) }
    val scale by animateFloatAsState(
        targetValue = if (isPressed) 0.92f else 1f,
        animationSpec = spring(dampingRatio = 0.6f),
        label = "pressScale"
    )

    val bgColor = when {
        isSpecial -> MaterialTheme.colorScheme.primary
        else -> MaterialTheme.colorScheme.surfaceVariant
    }

    Box(
        modifier = modifier
            .aspectRatio(1.5f)
            .scale(scale)
            .clip(RoundedCornerShape(12.dp))
            .background(bgColor)
            .pointerInput(Unit) {
                detectTapGestures(
                    onPress = {
                        isPressed = true
                        tryAwaitRelease()
                        isPressed = false
                    },
                    onTap = { onClick() },
                    onLongPress = { onLongClick?.invoke() }
                )
            },
        contentAlignment = Alignment.Center
    ) {
        Text(
            text = label,
            style = MaterialTheme.typography.titleLarge,
            color = if (isSpecial) MaterialTheme.colorScheme.onPrimary
                    else MaterialTheme.colorScheme.onSurface
        )
    }
}

3.4 触摸反馈实现

触摸反馈包含视觉缩放与涟漪效果两层。缩放动画使用 spring 弹性曲线，模拟真实按键的按压感；涟漪效果由 Modifier.clickable 内部的 ripple 提供，但为了精确控制按压状态，此处使用 pointerInput 手动实现。

// 在 KeyButton 中集成涟漪效果
Modifier
    .pointerInput(Unit) {
        detectTapGestures(
            onPress = {
                isPressed = true
                tryAwaitRelease()
                isPressed = false
            },
            onTap = { onClick() }
        )
    }
    .drawWithContent {
        drawContent()
        if (isPressed) {
            // 绘制半透明涟漪遮罩
            drawRect(
                color = MaterialTheme.colorScheme.primary.copy(alpha = 0.12f),
                size = size,
                topLeft = Offset.Zero
            )
        }
    }

3.5 按键音与震动控制

集成系统 AudioManager 与 Vibrator 服务，在按键按下时提供同步的听觉与触觉反馈。封装为 HapticController 类，便于在 ViewModel 或 Composable 中注入。

class HapticController(private val context: Context) {
    private val audioManager =
        context.getSystemService(Context.AUDIO_SERVICE) as AudioManager

    @Suppress("DEPRECATION")
    private val vibrator: Vibrator =
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            context.getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
        } else {
            context.getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
        }

    fun playKeyClick() {
        // 播放系统按键音
        audioManager.playSoundEffect(SoundEffectConstants.CLICK)

        // 短震动反馈 (30ms)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            vibrator.vibrate(
                VibrationEffect.createOneShot(30, VibrationEffect.DEFAULT_AMPLITUDE)
            )
        } else {
            vibrator.vibrate(30)
        }
    }

    fun playError() {
        audioManager.playSoundEffect(SoundEffectConstants.ERROR)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            vibrator.vibrate(
                VibrationEffect.createOneShot(80, 200)
            )
        } else {
            vibrator.vibrate(80)
        }
    }
}

3.6 调试与常见错误

• 布局不对齐：检查 Row 的 horizontalArrangement 是否与 spacedBy 冲突，确保每行总权重之和相等。
• 触摸事件冲突：若 KeyButton 外层存在 Modifier.clickable 或 Modifier.scrollable，内层的 pointerInput 可能被拦截。使用 Modifier.pointerInput 的优先级高于 clickable，但仍需避免嵌套。
• 音效延迟：playSoundEffect 在 UI 线程调用时可能因重组卡顿导致延迟。将 HapticController 的方法放在 Dispatchers.IO 或使用 LaunchedEffect 异步触发。
• 震动无响应：检查 Manifest 中 VIBRATE 权限是否声明；部分国产 ROM 在后台可能限制震动，需引导用户开启权限。
• 缩放动画卡顿：animateFloatAsState 的 spring 曲线阻尼比建议在 0.4~0.7 之间，避免过高导致回弹过度或过低导致动画拖尾。

3.7 性能优化

• 重组范围最小化：将 isPressed 状态提升到 KeyButton 内部，避免父级重组。每个按键的状态相互独立，互不影响。
• 避免 lambda 重建：onClick 回调使用 remember 包裹或使用稳定引用，防止每次重组时创建新 lambda 导致子组件不必要的重组。
• 固定 Grid 大小：在 PayKeyboardGrid 外部使用 Modifier.heightIn 限制最大高度，避免按键随内容动态撑开。
• 预创建 HapticController：在 ViewModel 中使用 companion object 或依赖注入创建单例，避免每个按键都重复获取系统服务。

// 推荐：在 ViewModel 中预创建，通过 Composable 参数注入
class KeyboardViewModel(application: Application) : AndroidViewModel(application) {
    val hapticController = HapticController(application)
}

@Composable
fun PayKeyboardScreen(viewModel: KeyboardViewModel = viewModel()) {
    PayKeyboardGrid(
        onKeyPress = { key ->
            viewModel.hapticController.playKeyClick()
            // 处理按键逻辑
        }
    )
}