2. 项目环境搭建：Android Studio配置、Gradle依赖引入、Material 3主题设置、最低API版本要求

安全输入组件依赖完整的 Material 3 组件生态和 Android 编译链。环境搭建阶段需要精确控制 SDK 版本、Gradle 插件版本、Material 3 依赖坐标以及最低 API 门槛。任何版本错配都会导致 TextFields 样式丢失、PasswordVisualTransformation 不可用或编译时符号缺失。本章按「编辑器 → 构建系统 → 依赖 → 主题 → 验证」的链路逐一建立基线。

2.1 Android Studio 与 Gradle 配置

推荐使用 Android Studio Ladybug（2024.2.1）或更高版本，内置 K2 编译器可获得更快的 IDE 响应。项目创建后首先检查 gradle-wrapper.properties，确保 Gradle 发行版 ≥ 8.5：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

根项目 build.gradle.kts 中声明插件版本与仓库：

plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

2.2 Gradle 依赖引入——精确坐标与功能分组

安全输入组件涉及的依赖可分为三组：Material 3 基础库、图标扩展 与 可访问性工具。在模块级 build.gradle.kts 中按组引入：

// —— Material 3 基础库 ——
implementation("androidx.compose.material3:material3:1.2.1")
implementation("androidx.compose.material3:material3-window-size-class:1.2.1")

// —— 图标与视觉转换 ——
implementation("androidx.compose.material:material-icons-extended:1.6.7")

// —— Compose 编译器与运行时 ——
implementation("androidx.compose.ui:ui:1.6.7")
implementation("androidx.compose.ui:ui-tooling-preview:1.6.7")
implementation("androidx.activity:activity-compose:1.9.0")
implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.0")

// —— 可访问性：用于安全输入组件的标签与操作 ——
implementation("androidx.compose.ui:ui-test-junit4:1.6.7")
implementation("androidx.compose.ui:ui-test-manifest:1.6.7")

2.3 Material 3 主题设置——配色、形状与字体

安全输入组件的错误状态、聚焦指示器、标签动画都直接从主题槽中读取颜色令牌。在 Theme.kt 中定义基于 Material 3 的 MaterialTheme：

// Theme.kt
private val LightColorScheme = lightColorScheme(
    primary = Color(0xFF1976D2),
    onPrimary = Color.White,
    primaryContainer = Color(0xFFBBDEFB),
    error = Color(0xFFD32F2F),
    onError = Color.White,
    errorContainer = Color(0xFFFFCDD2),
    surface = Color.White,
    onSurface = Color(0xFF212121)
)

private val DarkColorScheme = darkColorScheme(
    primary = Color(0xFF90CAF9),
    onPrimary = Color(0xFF0D47A1),
    primaryContainer = Color(0xFF1565C0),
    error = Color(0xFFEF9A9A),
    onError = Color(0xFFB71C1C),
    errorContainer = Color(0xFFC62828),
    surface = Color(0xFF121212),
    onSurface = Color(0xFFE0E0E0)
)

@Composable
fun SecurityInputTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
    val colorScheme = if (darkTheme) DarkColorScheme else LightColorScheme
    MaterialTheme(
        colorScheme = colorScheme,
        shapes = Shapes(
            small = RoundedCornerShape(8.dp),
            medium = RoundedCornerShape(12.dp),
            large = RoundedCornerShape(16.dp)
        ),
        content = content
    )
}

2.4 最低 API 版本要求——minSdk 决策依据

Material 3 的 OutlinedTextField 与 PasswordVisualTransformation 在 API 24+ 上经过完整测试。低于 API 24 的设备无法保证 TextInputLayout 动画流畅，且 BiometricPrompt（安全输入可选集成）仅在 API 28+ 提供稳定 API。

在 build.gradle.kts 的 defaultConfig 块中设置：

defaultConfig {
    applicationId = "com.example.securityinput"
    minSdk = 24
    targetSdk = 34
    versionCode = 1
    versionName = "1.0.0"

    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    vectorDrawables {
        useSupportLibrary = true
    }
}

2.5 环境验证——编译检查与预览渲染

完成上述配置后执行三步验证。首先运行 Gradle 同步，确认无红色波浪线；然后执行编译检查：

./gradlew assembleDebug --daemon --build-cache

编译成功后在 MainActivity.kt 中写入最小预览代码，验证主题与组件是否正常渲染：

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            SecurityInputTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.surface
                ) {
                    OutlinedTextField(
                        value = "",
                        onValueChange = { },
                        label = { Text("密码") },
                        visualTransformation = PasswordVisualTransformation(),
                        leadingIcon = {
                            Icon(Icons.Default.Lock, contentDescription = "密码图标")
                        }
                    )
                }
            }
        }
    }
}

在模拟器（API 24+）或真机上运行，应当看到带密码掩码的输入框，点击图标区域无崩溃。如果预览报错 ComposeViewAdapter 异常，请检查 build.gradle.kts 中是否遗漏 ui-tooling-preview 依赖。

2.6 整体搭建流程

下图汇总了从 Android Studio 配置到最终验证的完整链路，每个方框对应一个可追溯的检查点：

2.7 常见错误与调试技巧

2.8 搭建后检查清单

• ☐ gradle-wrapper.properties 中 distributionUrl 指向 Gradle 8.5+
• ☐ 模块级 build.gradle.kts 包含 material3:1.2.x 与 material-icons-extended
• ☐ SecurityInputTheme 覆盖 errorContainer 和 onError 颜色令牌
• ☐ minSdk = 24 已生效，targetSdk = 34
• ☐ ./gradlew assembleDebug 编译通过
• ☐ 预览或真机运行显示密码掩码输入框，无崩溃、无图标缺失