872 lines
30 KiB
Markdown
872 lines
30 KiB
Markdown
|
# 步骤 03：服务器配置页
|
|||
|
|
|
|||
|
|
> 实现服务器配置页 UI，包括输入验证、连接按钮状态机、最近连接列表。
|
|||
|
|
> 对应流程：01 连接服务器（初始化配置部分）
|
|||
|
|
> 依赖步骤：02（Bridge 层）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、目标
|
|||
|
|
|
|||
|
|
- [ ] ServerConfigScreen 三段式页面布局（品牌区 / 输入区 / 最近连接）
|
|||
|
|
- [ ] 输入框组件（地址、昵称、密码）
|
|||
|
|
- [ ] 输入验证逻辑（必填校验、格式校验）
|
|||
|
|
- [ ] 连接按钮状态机（空闲 → 连接中 → 成功/失败/超时）
|
|||
|
|
- [ ] 最近连接列表（DataStore 持久化，快速连接）
|
|||
|
|
- [ ] ServerViewModel 状态管理
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、任务清单
|
|||
|
|
|
|||
|
|
### 3.1 数据模型
|
|||
|
|
|
|||
|
|
**文件**：`android/app/src/main/java/com/tsmobile/app/data/Models.kt`
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
import kotlinx.serialization.Serializable
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 服务器连接配置。
|
|||
|
|
* 用于 ViewModel 状态和最近连接列表持久化。
|
|||
|
|
*/
|
|||
|
|
@Serializable
|
|||
|
|
data class ServerConfig(
|
|||
|
|
val address: String = "", // 服务器地址（域名/IP/TSDNS）
|
|||
|
|
val nickname: String = "", // 昵称
|
|||
|
|
val password: String = "", // 服务器密码（可选）
|
|||
|
|
val defaultChannel: String = "", // 默认频道（可选）
|
|||
|
|
val defaultChannelPassword: String = "", // 默认频道密码（可选）
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 最近连接记录。
|
|||
|
|
* 点击可快速连接（复用 address/nickname/password）。
|
|||
|
|
*/
|
|||
|
|
@Serializable
|
|||
|
|
data class RecentConnection(
|
|||
|
|
val address: String,
|
|||
|
|
val nickname: String,
|
|||
|
|
val password: String = "",
|
|||
|
|
val lastConnectedAt: Long = 0L, // 最后连接时间戳（epoch ms）
|
|||
|
|
val lastSucceeded: Boolean = false, // 上次连接是否成功
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 最近连接存储
|
|||
|
|
|
|||
|
|
**文件**：`android/app/src/main/java/com/tsmobile/app/data/RecentConnectionsStore.kt`
|
|||
|
|
|
|||
|
|
使用 Jetpack DataStore Preferences 持久化最近连接列表。
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
import android.content.Context
|
|||
|
|
import androidx.datastore.core.DataStore
|
|||
|
|
import androidx.datastore.preferences.core.*
|
|||
|
|
import androidx.datastore.preferences.preferencesDataStore
|
|||
|
|
import kotlinx.coroutines.flow.Flow
|
|||
|
|
import kotlinx.coroutines.flow.map
|
|||
|
|
import kotlinx.serialization.encodeToString
|
|||
|
|
import kotlinx.serialization.json.Json
|
|||
|
|
|
|||
|
|
// Context 扩展属性
|
|||
|
|
private val Context.recentConnectionsDataStore: DataStore<Preferences>
|
|||
|
|
by preferencesDataStore(name = "recent_connections")
|
|||
|
|
|
|||
|
|
class RecentConnectionsStore(private val context: Context) {
|
|||
|
|
|
|||
|
|
companion object {
|
|||
|
|
private const val MAX_RECENT = 10
|
|||
|
|
private val RECENTS_KEY = stringPreferencesKey("recents_json")
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 观察最近连接列表（按 lastConnectedAt 倒序）。
|
|||
|
|
*/
|
|||
|
|
fun observeRecents(): Flow<List<RecentConnection>> {
|
|||
|
|
return context.recentConnectionsDataStore.data.map { prefs ->
|
|||
|
|
val json = prefs[RECENTS_KEY] ?: return@map emptyList()
|
|||
|
|
try {
|
|||
|
|
Json.decodeFromString<List<RecentConnection>>(json)
|
|||
|
|
.sortedByDescending { it.lastConnectedAt }
|
|||
|
|
} catch (_: Exception) {
|
|||
|
|
emptyList()
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 记录一次连接（成功或失败）。
|
|||
|
|
* 相同 address + nickname 去重，保留最新记录。
|
|||
|
|
*/
|
|||
|
|
suspend fun addRecent(recent: RecentConnection) {
|
|||
|
|
context.recentConnectionsDataStore.edit { prefs ->
|
|||
|
|
val current = try {
|
|||
|
|
Json.decodeFromString<List<RecentConnection>>(prefs[RECENTS_KEY] ?: "[]")
|
|||
|
|
} catch (_: Exception) {
|
|||
|
|
emptyList()
|
|||
|
|
}.toMutableList()
|
|||
|
|
|
|||
|
|
// 去重：移除相同 address + nickname 的旧记录
|
|||
|
|
current.removeAll { it.address == recent.address && it.nickname == recent.nickname }
|
|||
|
|
current.add(0, recent) // 插入到头部
|
|||
|
|
|
|||
|
|
// 限制最多 MAX_RECENT 条
|
|||
|
|
val trimmed = current.take(MAX_RECENT)
|
|||
|
|
prefs[RECENTS_KEY] = Json.encodeToString(trimmed)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 删除单条记录。
|
|||
|
|
*/
|
|||
|
|
suspend fun removeRecent(address: String, nickname: String) {
|
|||
|
|
context.recentConnectionsDataStore.edit { prefs ->
|
|||
|
|
val current = try {
|
|||
|
|
Json.decodeFromString<List<RecentConnection>>(prefs[RECENTS_KEY] ?: "[]")
|
|||
|
|
} catch (_: Exception) {
|
|||
|
|
emptyList()
|
|||
|
|
}.toMutableList()
|
|||
|
|
|
|||
|
|
current.removeAll { it.address == address && it.nickname == nickname }
|
|||
|
|
prefs[RECENTS_KEY] = Json.encodeToString(current)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 清空所有记录。
|
|||
|
|
*/
|
|||
|
|
suspend fun clearAll() {
|
|||
|
|
context.recentConnectionsDataStore.edit { prefs ->
|
|||
|
|
prefs.remove(RECENTS_KEY)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**存储方案选择**：
|
|||
|
|
|
|||
|
|
| 方案 | 优缺点 | 结论 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| SharedPreferences | 简单，但已弃用 | ❌ |
|
|||
|
|
| DataStore Preferences | 现代、协程友好、类型安全 | ✅ 采用 |
|
|||
|
|
| Room DB | 过重，数据量小（最多 10 条） | ❌ |
|
|||
|
|
|
|||
|
|
### 3.3 页面布局
|
|||
|
|
|
|||
|
|
**文件**：`android/app/src/main/java/com/tsmobile/app/ui/screens/ServerConfigScreen.kt`
|
|||
|
|
|
|||
|
|
#### 三段式结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────┐
|
|||
|
|
│ 上：品牌区 │
|
|||
|
|
│ [Logo] │
|
|||
|
|
│ TeamSpeak Mobile │
|
|||
|
|
│ 连接到你的 TeamSpeak 服务器 │
|
|||
|
|
│ [🌙 主题] │ ← 右上角主题切换
|
|||
|
|
├──────────────────────────────┤
|
|||
|
|
│ 中：输入区 │
|
|||
|
|
│ 服务器地址 │
|
|||
|
|
│ ┌──────────────────────────┐│
|
|||
|
|
│ │ ts.example.com ││
|
|||
|
|
│ └──────────────────────────┘│
|
|||
|
|
│ 昵称 │
|
|||
|
|
│ ┌──────────────────────────┐│
|
|||
|
|
│ │ 我的昵称 ││
|
|||
|
|
│ └──────────────────────────┘│
|
|||
|
|
│ 密码（可选） │
|
|||
|
|
│ ┌──────────────────────────┐│
|
|||
|
|
│ │ •••••• ││
|
|||
|
|
│ └──────────────────────────┘│
|
|||
|
|
│ ┌──────────────────────────┐│
|
|||
|
|
│ │ 连接服务器 ││ ← 按钮状态见 3.5
|
|||
|
|
│ └──────────────────────────┘│
|
|||
|
|
├──────────────────────────────┤
|
|||
|
|
│ 下：最近连接 │
|
|||
|
|
│ 最近连接 │
|
|||
|
|
│ ┌──────────────────────────┐│
|
|||
|
|
│ │ 🟢 ts.myserver.com ││ ← 点击快速连接
|
|||
|
|
│ │ MyNickname · 2小时前 ││
|
|||
|
|
│ ├──────────────────────────┤│
|
|||
|
|
│ │ 🔴 ts.other.com ││
|
|||
|
|
│ │ Bob · 昨天 ││
|
|||
|
|
│ └──────────────────────────┘│
|
|||
|
|
│ [清空最近记录] │ ← 长按删除单条
|
|||
|
|
└──────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### Compose 结构
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
@Composable
|
|||
|
|
fun ServerConfigScreen(
|
|||
|
|
viewModel: ServerViewModel,
|
|||
|
|
onNavigateToChannelList: () -> Unit, // 连接成功后跳转
|
|||
|
|
) {
|
|||
|
|
val state by viewModel.state.collectAsState()
|
|||
|
|
val recents by viewModel.recents.collectAsState()
|
|||
|
|
|
|||
|
|
Column(modifier = Modifier.fillMaxSize()) {
|
|||
|
|
// 上：品牌区
|
|||
|
|
BrandSection(
|
|||
|
|
onToggleTheme = { viewModel.toggleTheme() }
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 中：输入区
|
|||
|
|
InputSection(
|
|||
|
|
address = state.address,
|
|||
|
|
nickname = state.nickname,
|
|||
|
|
password = state.password,
|
|||
|
|
onAddressChange = viewModel::updateAddress,
|
|||
|
|
onNicknameChange = viewModel::updateNickname,
|
|||
|
|
onPasswordChange = viewModel::updatePassword,
|
|||
|
|
connectState = state.connectState,
|
|||
|
|
errorMessage = state.errorMessage,
|
|||
|
|
onConnect = { viewModel.connect() },
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 下：最近连接
|
|||
|
|
RecentConnectionsSection(
|
|||
|
|
recents = recents,
|
|||
|
|
onConnectRecent = { recent -> viewModel.quickConnect(recent) },
|
|||
|
|
onRemoveRecent = { recent -> viewModel.removeRecent(recent) },
|
|||
|
|
onClearAll = { viewModel.clearRecents() },
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 连接成功后自动跳转
|
|||
|
|
LaunchedEffect(state.connectState) {
|
|||
|
|
if (state.connectState == ConnectState.SUCCESS) {
|
|||
|
|
onNavigateToChannelList()
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 品牌区组件
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
@Composable
|
|||
|
|
private fun BrandSection(onToggleTheme: () -> Unit) {
|
|||
|
|
Box(modifier = Modifier.fillMaxWidth().padding(top = 48.dp)) {
|
|||
|
|
Column(
|
|||
|
|
modifier = Modifier.align(Alignment.Center),
|
|||
|
|
horizontalAlignment = Alignment.CenterHorizontally,
|
|||
|
|
) {
|
|||
|
|
// Logo（使用 drawable 资源或 placeholder）
|
|||
|
|
Icon(
|
|||
|
|
imageVector = Icons.Default.Dns, // 临时图标
|
|||
|
|
contentDescription = "TeamSpeak",
|
|||
|
|
modifier = Modifier.size(72.dp),
|
|||
|
|
tint = MaterialTheme.colorScheme.primary,
|
|||
|
|
)
|
|||
|
|
Spacer(Modifier.height(12.dp))
|
|||
|
|
Text(
|
|||
|
|
text = "TeamSpeak Mobile",
|
|||
|
|
style = MaterialTheme.typography.headlineMedium,
|
|||
|
|
fontWeight = FontWeight.Bold,
|
|||
|
|
)
|
|||
|
|
Text(
|
|||
|
|
text = "连接到你的 TeamSpeak 服务器",
|
|||
|
|
style = MaterialTheme.typography.bodyMedium,
|
|||
|
|
color = MaterialTheme.colorScheme.onSurfaceVariant,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
// 主题切换按钮（右上角）
|
|||
|
|
IconButton(
|
|||
|
|
onClick = onToggleTheme,
|
|||
|
|
modifier = Modifier.align(Alignment.TopEnd).padding(end = 8.dp),
|
|||
|
|
) {
|
|||
|
|
Icon(Icons.Default.DarkMode, contentDescription = "切换主题")
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 输入区组件
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
@Composable
|
|||
|
|
private fun InputSection(
|
|||
|
|
address: String,
|
|||
|
|
nickname: String,
|
|||
|
|
password: String,
|
|||
|
|
onAddressChange: (String) -> Unit,
|
|||
|
|
onNicknameChange: (String) -> Unit,
|
|||
|
|
onPasswordChange: (String) -> Unit,
|
|||
|
|
connectState: ConnectState,
|
|||
|
|
errorMessage: String?,
|
|||
|
|
onConnect: () -> Unit,
|
|||
|
|
) {
|
|||
|
|
Column(
|
|||
|
|
modifier = Modifier
|
|||
|
|
.fillMaxWidth()
|
|||
|
|
.padding(horizontal = 24.dp, vertical = 16.dp),
|
|||
|
|
) {
|
|||
|
|
// 服务器地址
|
|||
|
|
OutlinedTextField(
|
|||
|
|
value = address,
|
|||
|
|
onValueChange = onAddressChange,
|
|||
|
|
label = { Text("服务器地址") },
|
|||
|
|
placeholder = { Text("ts.example.com") },
|
|||
|
|
singleLine = true,
|
|||
|
|
isError = connectState == ConnectState.FAILED && address.isBlank(),
|
|||
|
|
modifier = Modifier.fillMaxWidth(),
|
|||
|
|
keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
Spacer(Modifier.height(12.dp))
|
|||
|
|
|
|||
|
|
// 昵称
|
|||
|
|
OutlinedTextField(
|
|||
|
|
value = nickname,
|
|||
|
|
onValueChange = onNicknameChange,
|
|||
|
|
label = { Text("昵称") },
|
|||
|
|
placeholder = { Text("我的昵称") },
|
|||
|
|
singleLine = true,
|
|||
|
|
isError = connectState == ConnectState.FAILED && nickname.isBlank(),
|
|||
|
|
modifier = Modifier.fillMaxWidth(),
|
|||
|
|
keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
Spacer(Modifier.height(12.dp))
|
|||
|
|
|
|||
|
|
// 密码（可选）
|
|||
|
|
OutlinedTextField(
|
|||
|
|
value = password,
|
|||
|
|
onValueChange = onPasswordChange,
|
|||
|
|
label = { Text("密码（可选）") },
|
|||
|
|
placeholder = { Text("••••••") },
|
|||
|
|
singleLine = true,
|
|||
|
|
visualTransformation = PasswordVisualTransformation(),
|
|||
|
|
modifier = Modifier.fillMaxWidth(),
|
|||
|
|
keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
Spacer(Modifier.height(24.dp))
|
|||
|
|
|
|||
|
|
// 连接按钮（状态机驱动）
|
|||
|
|
ConnectButton(
|
|||
|
|
state = connectState,
|
|||
|
|
errorMessage = errorMessage,
|
|||
|
|
onClick = onConnect,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 最近连接组件
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
@Composable
|
|||
|
|
private fun RecentConnectionsSection(
|
|||
|
|
recents: List<RecentConnection>,
|
|||
|
|
onConnectRecent: (RecentConnection) -> Unit,
|
|||
|
|
onRemoveRecent: (RecentConnection) -> Unit,
|
|||
|
|
onClearAll: () -> Unit,
|
|||
|
|
) {
|
|||
|
|
if (recents.isEmpty()) return
|
|||
|
|
|
|||
|
|
Column(
|
|||
|
|
modifier = Modifier
|
|||
|
|
.fillMaxWidth()
|
|||
|
|
.padding(horizontal = 24.dp, vertical = 8.dp),
|
|||
|
|
) {
|
|||
|
|
Text(
|
|||
|
|
text = "最近连接",
|
|||
|
|
style = MaterialTheme.typography.titleSmall,
|
|||
|
|
color = MaterialTheme.colorScheme.onSurfaceVariant,
|
|||
|
|
)
|
|||
|
|
Spacer(Modifier.height(8.dp))
|
|||
|
|
|
|||
|
|
recents.forEach { recent ->
|
|||
|
|
RecentConnectionItem(
|
|||
|
|
recent = recent,
|
|||
|
|
onClick = { onConnectRecent(recent) },
|
|||
|
|
onLongClick = { onRemoveRecent(recent) },
|
|||
|
|
)
|
|||
|
|
Spacer(Modifier.height(4.dp))
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
Spacer(Modifier.height(8.dp))
|
|||
|
|
TextButton(
|
|||
|
|
onClick = onClearAll,
|
|||
|
|
modifier = Modifier.align(Alignment.CenterHorizontally),
|
|||
|
|
) {
|
|||
|
|
Text("清空最近记录")
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@OptIn(ExperimentalFoundationApi::class)
|
|||
|
|
@Composable
|
|||
|
|
private fun RecentConnectionItem(
|
|||
|
|
recent: RecentConnection,
|
|||
|
|
onClick: () -> Unit,
|
|||
|
|
onLongClick: () -> Unit,
|
|||
|
|
) {
|
|||
|
|
Card(
|
|||
|
|
modifier = Modifier
|
|||
|
|
.fillMaxWidth()
|
|||
|
|
.combinedClickable(onClick = onClick, onLongClick = onLongClick),
|
|||
|
|
) {
|
|||
|
|
Row(
|
|||
|
|
modifier = Modifier.padding(12.dp),
|
|||
|
|
verticalAlignment = Alignment.CenterVertically,
|
|||
|
|
) {
|
|||
|
|
// 状态指示灯
|
|||
|
|
Box(
|
|||
|
|
modifier = Modifier
|
|||
|
|
.size(8.dp)
|
|||
|
|
.background(
|
|||
|
|
color = if (recent.lastSucceeded)
|
|||
|
|
MaterialTheme.colorScheme.primary
|
|||
|
|
else
|
|||
|
|
MaterialTheme.colorScheme.error,
|
|||
|
|
shape = CircleShape,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
Spacer(Modifier.width(12.dp))
|
|||
|
|
Column {
|
|||
|
|
Text(
|
|||
|
|
text = recent.address,
|
|||
|
|
style = MaterialTheme.typography.bodyMedium,
|
|||
|
|
fontWeight = FontWeight.Medium,
|
|||
|
|
)
|
|||
|
|
Text(
|
|||
|
|
text = "${recent.nickname} · ${formatRelativeTime(recent.lastConnectedAt)}",
|
|||
|
|
style = MaterialTheme.typography.bodySmall,
|
|||
|
|
color = MaterialTheme.colorScheme.onSurfaceVariant,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.4 输入验证逻辑
|
|||
|
|
|
|||
|
|
**验证规则**（依据 UI 架构设计 2.1 节）：
|
|||
|
|
|
|||
|
|
| 字段 | 必填 | 验证规则 | 错误提示 |
|
|||
|
|
| --- | --- | --- | --- |
|
|||
|
|
| 服务器地址 | 是 | 非空，格式合法（域名/IP/TSDNS） | "请输入有效的服务器地址" |
|
|||
|
|
| 昵称 | 是 | 非空，满足服务器命名规则 | "请输入昵称" |
|
|||
|
|
| 密码 | 否 | 仅当服务器需要密码时必填 | "该服务器需要密码"（连接时由服务端返回） |
|
|||
|
|
|
|||
|
|
**验证时机**：用户点击"连接"时一次性校验，不实时校验（避免打断输入流）。
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
data class ValidationErrors(
|
|||
|
|
val address: String? = null,
|
|||
|
|
val nickname: String? = null,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
fun validate(config: ServerConfig): ValidationErrors {
|
|||
|
|
val errors = ValidationErrors()
|
|||
|
|
|
|||
|
|
// 地址验证：非空 + 基本格式（包含字母或数字，含可选端口）
|
|||
|
|
if (config.address.isBlank()) {
|
|||
|
|
errors.copy(address = "请输入服务器地址")
|
|||
|
|
} else if (!isValidServerAddress(config.address)) {
|
|||
|
|
errors.copy(address = "请输入有效的服务器地址")
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 昵称验证：非空
|
|||
|
|
if (config.nickname.isBlank()) {
|
|||
|
|
errors.copy(nickname = "请输入昵称")
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return errors
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 服务器地址格式验证。
|
|||
|
|
* 支持：域名、IP（v4/v6）、TSDNS、带端口号。
|
|||
|
|
*/
|
|||
|
|
private fun isValidServerAddress(address: String): Boolean {
|
|||
|
|
val trimmed = address.trim()
|
|||
|
|
if (trimmed.isBlank()) return false
|
|||
|
|
|
|||
|
|
// 允许格式：
|
|||
|
|
// - example.com
|
|||
|
|
// - example.com:9987
|
|||
|
|
// - 192.168.1.1
|
|||
|
|
// - 192.168.1.1:9987
|
|||
|
|
// - [::1]:9987
|
|||
|
|
// - _ts3._udp.example.com (TSDNS SRV)
|
|||
|
|
val ip4Pattern = Regex("""^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?$""")
|
|||
|
|
val domainPattern = Regex("""^[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?)*(:\d+)?$""")
|
|||
|
|
val ip6Pattern = Regex("""^\[?[a-fA-F0-9:]+\]?(:\d+)?$""")
|
|||
|
|
|
|||
|
|
return ip4Pattern.matches(trimmed) ||
|
|||
|
|
domainPattern.matches(trimmed) ||
|
|||
|
|
ip6Pattern.matches(trimmed)
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.5 连接按钮状态机
|
|||
|
|
|
|||
|
|
**状态定义**（依据 UI 架构设计 5.1 节）：
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
enum class ConnectState {
|
|||
|
|
IDLE, // 空闲：等待用户输入并点击
|
|||
|
|
CONNECTING, // 连接中：Connect + WaitConnected 进行中
|
|||
|
|
SUCCESS, // 连接成功：跳转频道列表页
|
|||
|
|
FAILED, // 连接失败：显示错误信息和重试
|
|||
|
|
TIMEOUT, // 连接超时：显示超时提示
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**按钮外观对应**：
|
|||
|
|
|
|||
|
|
| 状态 | 按钮文本 | 样式 | 可点击 |
|
|||
|
|
| --- | --- | --- | --- |
|
|||
|
|
| `IDLE` | "连接服务器" | Primary Filled | ✅ |
|
|||
|
|
| `CONNECTING` | "连接中..." | Outlined + loading indicator | ❌ |
|
|||
|
|
| `SUCCESS` | — | 自动跳转，按钮不显示 | — |
|
|||
|
|
| `FAILED` | "连接失败，点击重试" | Error container 色 | ✅ |
|
|||
|
|
| `TIMEOUT` | "连接超时，点击重试" | Orange container 色 | ✅ |
|
|||
|
|
|
|||
|
|
**错误信息分类**：
|
|||
|
|
|
|||
|
|
| 错误类型 | 判断方式 | 提示信息 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| 密码错误 | 含 "password" 或 "密码" | "服务器密码错误" |
|
|||
|
|
| 昵称冲突 | 含 "nickname" 或 "昵称" | "昵称已被使用，请更换" |
|
|||
|
|
| 网络不可达 | 含 "timeout"、"unreachable"、"network" | "无法连接到服务器，请检查网络" |
|
|||
|
|
| 地址无效 | 含 "resolve"、"dns"、"lookup" | "服务器地址无法解析" |
|
|||
|
|
| 服务器满 | 含 "full"、"limit" | "服务器已满" |
|
|||
|
|
| 其他 | 默认 | 原始错误信息 |
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
@Composable
|
|||
|
|
fun ConnectButton(
|
|||
|
|
state: ConnectState,
|
|||
|
|
errorMessage: String?,
|
|||
|
|
onClick: () -> Unit,
|
|||
|
|
) {
|
|||
|
|
Button(
|
|||
|
|
onClick = onClick,
|
|||
|
|
enabled = state != ConnectState.CONNECTING,
|
|||
|
|
modifier = Modifier.fillMaxWidth().height(48.dp),
|
|||
|
|
colors = when (state) {
|
|||
|
|
ConnectState.FAILED -> ButtonDefaults.buttonColors(
|
|||
|
|
containerColor = MaterialTheme.colorScheme.errorContainer,
|
|||
|
|
contentColor = MaterialTheme.colorScheme.onErrorContainer,
|
|||
|
|
)
|
|||
|
|
ConnectState.TIMEOUT -> ButtonDefaults.buttonColors(
|
|||
|
|
containerColor = Color(0xFFFFF3E0), // 橙色背景
|
|||
|
|
contentColor = Color(0xFFE65100),
|
|||
|
|
)
|
|||
|
|
else -> ButtonDefaults.buttonColors()
|
|||
|
|
},
|
|||
|
|
) {
|
|||
|
|
when (state) {
|
|||
|
|
ConnectState.IDLE -> Text("连接服务器")
|
|||
|
|
ConnectState.CONNECTING -> {
|
|||
|
|
CircularProgressIndicator(
|
|||
|
|
modifier = Modifier.size(20.dp),
|
|||
|
|
strokeWidth = 2.dp,
|
|||
|
|
color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f),
|
|||
|
|
)
|
|||
|
|
Spacer(Modifier.width(8.dp))
|
|||
|
|
Text("连接中...")
|
|||
|
|
}
|
|||
|
|
ConnectState.SUCCESS -> { /* 不会到达，自动跳转 */ }
|
|||
|
|
ConnectState.FAILED -> {
|
|||
|
|
Text(errorMessage ?: "连接失败，点击重试")
|
|||
|
|
}
|
|||
|
|
ConnectState.TIMEOUT -> Text("连接超时，点击重试")
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.6 ViewModel 状态管理
|
|||
|
|
|
|||
|
|
**文件**：`android/app/src/main/java/com/tsmobile/app/viewmodel/ServerViewModel.kt`
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
import android.app.Application
|
|||
|
|
import androidx.lifecycle.AndroidViewModel
|
|||
|
|
import androidx.lifecycle.viewModelScope
|
|||
|
|
import kotlinx.coroutines.flow.*
|
|||
|
|
import kotlinx.coroutines.launch
|
|||
|
|
|
|||
|
|
data class ServerScreenState(
|
|||
|
|
val address: String = "",
|
|||
|
|
val nickname: String = "",
|
|||
|
|
val password: String = "",
|
|||
|
|
val connectState: ConnectState = ConnectState.IDLE,
|
|||
|
|
val errorMessage: String? = null,
|
|||
|
|
val validationErrors: ValidationErrors = ValidationErrors(),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
class ServerViewModel(application: Application) : AndroidViewModel(application) {
|
|||
|
|
|
|||
|
|
private val recentStore = RecentConnectionsStore(application)
|
|||
|
|
|
|||
|
|
// 页面状态
|
|||
|
|
private val _state = MutableStateFlow(ServerScreenState())
|
|||
|
|
val state: StateFlow<ServerScreenState> = _state.asStateFlow()
|
|||
|
|
|
|||
|
|
// 最近连接列表
|
|||
|
|
val recents: StateFlow<List<RecentConnection>> =
|
|||
|
|
recentStore.observeRecents()
|
|||
|
|
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
|
|||
|
|
|
|||
|
|
// --- 输入更新 ---
|
|||
|
|
|
|||
|
|
fun updateAddress(value: String) {
|
|||
|
|
_state.update { it.copy(address = value, errorMessage = null) }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fun updateNickname(value: String) {
|
|||
|
|
_state.update { it.copy(nickname = value, errorMessage = null) }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fun updatePassword(value: String) {
|
|||
|
|
_state.update { it.copy(password = value) }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// --- 连接 ---
|
|||
|
|
|
|||
|
|
fun connect() {
|
|||
|
|
val current = _state.value
|
|||
|
|
if (current.connectState == ConnectState.CONNECTING) return
|
|||
|
|
|
|||
|
|
// 输入验证
|
|||
|
|
val config = ServerConfig(
|
|||
|
|
address = current.address.trim(),
|
|||
|
|
nickname = current.nickname.trim(),
|
|||
|
|
password = current.password,
|
|||
|
|
)
|
|||
|
|
val errors = validate(config)
|
|||
|
|
if (errors.address != null || errors.nickname != null) {
|
|||
|
|
_state.update { it.copy(
|
|||
|
|
validationErrors = errors,
|
|||
|
|
connectState = ConnectState.IDLE,
|
|||
|
|
errorMessage = errors.address ?: errors.nickname,
|
|||
|
|
)}
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 进入连接中状态
|
|||
|
|
_state.update { it.copy(
|
|||
|
|
connectState = ConnectState.CONNECTING,
|
|||
|
|
errorMessage = null,
|
|||
|
|
validationErrors = ValidationErrors(),
|
|||
|
|
)}
|
|||
|
|
|
|||
|
|
// 异步连接（调用 TSBridge）
|
|||
|
|
viewModelScope.launch {
|
|||
|
|
val result = TSBridge.connect(
|
|||
|
|
host = config.address,
|
|||
|
|
nickname = config.nickname,
|
|||
|
|
password = config.password,
|
|||
|
|
callbacks = createBridgeCallbacks(),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
if (result.isEmpty()) {
|
|||
|
|
// 连接成功（实际成功由 onConnected 回调确认）
|
|||
|
|
// 此处 Connect 已成功启动，等待 WaitConnected
|
|||
|
|
} else {
|
|||
|
|
// 连接失败
|
|||
|
|
val errorMsg = classifyError(result)
|
|||
|
|
_state.update { it.copy(
|
|||
|
|
connectState = ConnectState.FAILED,
|
|||
|
|
errorMessage = errorMsg,
|
|||
|
|
)}
|
|||
|
|
|
|||
|
|
// 记录到最近连接（标记失败）
|
|||
|
|
recentStore.addRecent(RecentConnection(
|
|||
|
|
address = config.address,
|
|||
|
|
nickname = config.nickname,
|
|||
|
|
password = config.password,
|
|||
|
|
lastConnectedAt = System.currentTimeMillis(),
|
|||
|
|
lastSucceeded = false,
|
|||
|
|
))
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 最近连接快速连接。
|
|||
|
|
* 自动填充所有字段并触发连接。
|
|||
|
|
*/
|
|||
|
|
fun quickConnect(recent: RecentConnection) {
|
|||
|
|
_state.update { it.copy(
|
|||
|
|
address = recent.address,
|
|||
|
|
nickname = recent.nickname,
|
|||
|
|
password = recent.password,
|
|||
|
|
)}
|
|||
|
|
connect()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fun removeRecent(recent: RecentConnection) {
|
|||
|
|
viewModelScope.launch {
|
|||
|
|
recentStore.removeRecent(recent.address, recent.nickname)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fun clearRecents() {
|
|||
|
|
viewModelScope.launch {
|
|||
|
|
recentStore.clearAll()
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// --- Bridge 回调 ---
|
|||
|
|
|
|||
|
|
private fun createBridgeCallbacks(): TSBridge.Callbacks = object : TSBridge.Callbacks {
|
|||
|
|
override fun onConnected() {
|
|||
|
|
_state.update { it.copy(connectState = ConnectState.SUCCESS) }
|
|||
|
|
|
|||
|
|
// 记录到最近连接（标记成功）
|
|||
|
|
viewModelScope.launch {
|
|||
|
|
recentStore.addRecent(RecentConnection(
|
|||
|
|
address = _state.value.address.trim(),
|
|||
|
|
nickname = _state.value.nickname.trim(),
|
|||
|
|
password = _state.value.password,
|
|||
|
|
lastConnectedAt = System.currentTimeMillis(),
|
|||
|
|
lastSucceeded = true,
|
|||
|
|
))
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
override fun onDisconnected(message: String) {
|
|||
|
|
// 连接阶段断开视为失败
|
|||
|
|
if (_state.value.connectState == ConnectState.CONNECTING) {
|
|||
|
|
_state.update { it.copy(
|
|||
|
|
connectState = ConnectState.FAILED,
|
|||
|
|
errorMessage = classifyError(message),
|
|||
|
|
)}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
override fun onTextMessage(msg: TextMsg) { /* 此阶段不处理 */ }
|
|||
|
|
override fun onClientEnter(client: Client) { /* 此阶段不处理 */ }
|
|||
|
|
override fun onClientLeave(id: Int, reasonMsg: String) { /* 此阶段不处理 */ }
|
|||
|
|
override fun onClientMoved(id: Int, targetChannelID: String) { /* 此阶段不处理 */ }
|
|||
|
|
override fun onKicked(reason: String) { /* 此阶段不处理 */ }
|
|||
|
|
override fun onVoiceData(clientID: Int, data: ByteArray, codec: Int) { /* 此阶段不处理 */ }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// --- 错误分类 ---
|
|||
|
|
|
|||
|
|
private fun classifyError(raw: String): String {
|
|||
|
|
val lower = raw.lowercase()
|
|||
|
|
return when {
|
|||
|
|
"password" in lower || "密码" in lower -> "服务器密码错误"
|
|||
|
|
"nickname" in lower || "昵称" in lower -> "昵称已被使用，请更换"
|
|||
|
|
"timeout" in lower || "unreachable" in lower || "network" in lower ->
|
|||
|
|
"无法连接到服务器，请检查网络"
|
|||
|
|
"resolve" in lower || "dns" in lower || "lookup" in lower ->
|
|||
|
|
"服务器地址无法解析"
|
|||
|
|
"full" in lower || "limit" in lower -> "服务器已满"
|
|||
|
|
else -> raw
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.7 相对时间格式化
|
|||
|
|
|
|||
|
|
```kotlin
|
|||
|
|
/**
|
|||
|
|
* 格式化时间戳为相对时间描述。
|
|||
|
|
* 例：刚刚、5分钟前、2小时前、昨天、3天前、2024-01-15
|
|||
|
|
*/
|
|||
|
|
fun formatRelativeTime(timestamp: Long): String {
|
|||
|
|
if (timestamp <= 0) return ""
|
|||
|
|
val now = System.currentTimeMillis()
|
|||
|
|
val diff = now - timestamp
|
|||
|
|
|
|||
|
|
return when {
|
|||
|
|
diff < 60_000L -> "刚刚"
|
|||
|
|
diff < 3_600_000L -> "${diff / 60_000}分钟前"
|
|||
|
|
diff < 86_400_000L -> "${diff / 3_600_000}小时前"
|
|||
|
|
diff < 172_800_000L -> "昨天"
|
|||
|
|
diff < 604_800_000L -> "${diff / 86_400_000}天前"
|
|||
|
|
else -> {
|
|||
|
|
val sdf = java.text.SimpleDateFormat("yyyy-MM-dd", java.util.Locale.getDefault())
|
|||
|
|
sdf.format(java.util.Date(timestamp))
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、连接流程数据流
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
用户点击 "连接服务器"
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
ServerViewModel.connect()
|
|||
|
|
│
|
|||
|
|
├─ validate(config)
|
|||
|
|
│ ├─ 失败 → 显示验证错误，状态保持 IDLE
|
|||
|
|
│ └─ 通过 ↓
|
|||
|
|
│
|
|||
|
|
├─ state → CONNECTING（按钮显示 "连接中..."，禁用）
|
|||
|
|
│
|
|||
|
|
├─ TSBridge.connect(host, nickname, password, callbacks)
|
|||
|
|
│ │
|
|||
|
|
│ ▼
|
|||
|
|
│ Go: TSClient.Connect(...)
|
|||
|
|
│ │
|
|||
|
|
│ ├─ 返回 ""（启动成功）→ 等待回调
|
|||
|
|
│ │ ├─ callbacks.onConnected() → state → SUCCESS → 跳转频道列表页
|
|||
|
|
│ │ └─ callbacks.onDisconnected(msg) → state → FAILED → 显示错误
|
|||
|
|
│ │
|
|||
|
|
│ └─ 返回 "error msg"（启动失败）→ state → FAILED → 显示错误
|
|||
|
|
│
|
|||
|
|
├─ 记录到 RecentConnectionsStore
|
|||
|
|
│ └─ 成功：lastSucceeded = true（绿色）
|
|||
|
|
│ └─ 失败：lastSucceeded = false（红色）
|
|||
|
|
│
|
|||
|
|
└─ 用户可重试（点击按钮，state 回到 IDLE → 重新走连接流程）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、文件清单
|
|||
|
|
|
|||
|
|
| 文件 | 说明 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| `data/Models.kt` | ServerConfig、RecentConnection 数据类 |
|
|||
|
|
| `data/RecentConnectionsStore.kt` | DataStore 持久化最近连接 |
|
|||
|
|
| `ui/screens/ServerConfigScreen.kt` | 页面 Composable（品牌区 + 输入区 + 最近连接） |
|
|||
|
|
| `ui/components/ConnectButton.kt` | 连接按钮状态机组件 |
|
|||
|
|
| `viewmodel/ServerViewModel.kt` | 状态管理、验证、连接、错误分类 |
|
|||
|
|
| `ui/navigation/NavGraph.kt` | 导航路由（步骤 01 已建，此处补充配置页路由） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、验收标准
|
|||
|
|
|
|||
|
|
| # | 验证项 | 验证方法 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| 1 | 页面布局正确 | 启动应用，确认三段式布局（品牌/输入/最近连接） |
|
|||
|
|
| 2 | 输入验证生效 | 地址为空点击连接 → 提示 "请输入服务器地址"；昵称为空 → 提示 "请输入昵称" |
|
|||
|
|
| 3 | 按钮状态机正确 | 点击连接 → 按钮变为 "连接中..." 并禁用 → 成功跳转 / 失败显示错误 |
|
|||
|
|
| 4 | 错误信息分类正确 | 输入错误密码连接 → 显示 "服务器密码错误" |
|
|||
|
|
| 5 | 最近连接记录 | 连接成功/失败后返回配置页，列表显示对应记录 |
|
|||
|
|
| 6 | 最近连接快速连接 | 点击最近连接条目 → 自动填充并触发连接 |
|
|||
|
|
| 7 | 最近连接删除 | 长按条目 → 删除；点击 "清空" → 全部清空 |
|
|||
|
|
| 8 | 最多 10 条记录 | 连接超过 10 个不同服务器，列表只保留最新 10 条 |
|
|||
|
|
| 9 | 状态灯颜色 | 成功的记录显示绿色，失败的显示红色 |
|
|||
|
|
| 10 | 主题切换 | 点击右上角 🌙 → 主题切换，状态持久化 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、参考文档
|
|||
|
|
|
|||
|
|
- `docs/UI架构设计.md` — 2.1 服务器配置页（布局、验证规则、最近连接）
|
|||
|
|
- `docs/流程/01_连接服务器.md` — 初始化配置、状态树、连接时序
|
|||
|
|
- `docs/implementation/02_Bridge层实现.md` — TSBridge API 接口
|