# ImeAndroidDemo

**Repository Path**: kumei/ImeAndroidDemo

## Basic Information

- **Project Name**: ImeAndroidDemo
- **Description**: 输入法Demo
- **Primary Language**: Android
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-15
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 岚庭输入法 TV

Android TV 中文输入法工程，使用 **Kotlin + Flow + Jetpack Compose + MVI**。参考常见中文输入法的「拼音预编辑 / 候选词 / QWERTY / 模式切换」交互，自行实现电视界面与离线引擎。

## 已实现

- 系统 `InputMethodService`，可在其他应用的标准文本输入框中使用。
- 遥控器四方向导航、确认输入、返回取消组合 / 收起；方向键支持长按移动，确认键避免长按重复上屏。
- 可预测的焦点图：横向相邻键、纵向按按键中心就近对齐；边界停留、禁用键跳过、动态候选焦点回退。
- 中文全拼、连续拼音词句、前缀候选、单音节选词后保留剩余拼音、六候选分页、`v` 代替 `ü`、单引号分词。
- 英文大小写、数字、常用中英文符号、删除、空格、清空拼音及编辑器搜索 / 发送 / 下一项 / 换行等动作。
- 识别数字、电话、网址、邮箱及密码输入框，选择适当初始模式。
- 带 TV Launcher 入口的引导页，支持遥控器启用 / 切换输入法及测试输入。
- 无网络权限、不上传输入、不保存密码、不读取剪贴板。

## 构建

环境：**JDK 17、Android SDK 35、Build Tools 35、Gradle 8.11.1**。Gradle Wrapper 已包含。依赖版本固定为 AGP 8.10.1、Kotlin / Compose Compiler 2.2.10、Compose BOM 2024.12.01。

1. 用 Android Studio 打开本目录。
2. 为项目设置 Gradle JDK 17；通过 SDK Manager 安装 SDK 35。
3. 在 `local.properties` 配置本机 `sdk.dir`，或设置 `ANDROID_HOME`。
4. 执行：

```powershell
.\gradlew.bat :app:assembleDebug :app:testDebugUnitTest :app:lintDebug
```

macOS / Linux：`chmod +x gradlew`，再执行 `./gradlew :app:assembleDebug :app:testDebugUnitTest :app:lintDebug`。

若 Windows 本机出现 `Unable to establish loopback connection`，可为本次构建指定工程内的短临时目录后重试（不修改系统环境变量）：

```powershell
New-Item -ItemType Directory -Force .tmp | Out-Null
$imeTemp = Join-Path $PWD.Path '.tmp'
$imePreviousJavaOptions = $env:JAVA_TOOL_OPTIONS
try {
    $env:JAVA_TOOL_OPTIONS = "$imePreviousJavaOptions -Djava.io.tmpdir=$imeTemp -Djdk.net.unixdomain.tmpdir=$imeTemp"
    .\gradlew.bat :app:assembleDebug :app:testDebugUnitTest :app:lintDebug
} finally {
    $env:JAVA_TOOL_OPTIONS = $imePreviousJavaOptions
}
```

APK 位于 `app/build/outputs/apk/debug/app-debug.apk`。最低支持 Android 6.0 / API 23；推荐 Android TV 8.0 及以上。项目也能在普通 Android 模拟器配合电脑方向键验证。

## 在电视上启用

```shell
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.example.tvime/.MainActivity
```

打开「岚庭输入法 TV」，先选择「启用输入法」，在系统设置中启用，再选择「切换输入法」。进入测试输入框按确认即可输入。部分电视固件将设置入口放在「设备偏好设置 → 键盘」。

开发设备也可用 ADB 选择（会更改该设备当前输入法）：

```shell
adb shell ime enable com.example.tvime/.ime.TvInputMethodService
adb shell ime set com.example.tvime/.ime.TvInputMethodService
```

## 遥控器操作

| 按键 / 控件 | 行为 |
| --- | --- |
| ↑ ↓ ← → | 在模式、候选、字母、功能键之间移动，边界停留 |
| OK / DPAD_CENTER / Enter | 激活焦点所在按键 |
| 返回 / Escape | 有拼音时先清除拼音，再次按下收起 |
| 删除 / 物理键盘 Delete | 优先删拼音，否则删选中文字或光标前一个 Unicode 字符 |
| 候选「上一页 / 下一页」 | 查看其他候选；也支持物理 PageUp / PageDown |
| 空格 | 有候选时选择本页首词，否则输入空格 |
| 分词 `'` | 例如 `xi'an`，区分「西安」与 `xian` |
| 顶部「切换输入法」 | 切换至下一个系统输入法，必要时打开选择器 |

## 结构

```text
app/src/main/
├── assets/pinyin.tsv                 # UTF-8 离线词库
├── java/com/example/tvime/
│   ├── MainActivity.kt               # TV 引导、启用状态、测试输入
│   ├── core/ImeContract.kt           # State / Intent / Effect
│   ├── data/PinyinEngine.kt          # 纯 Kotlin 拼音查询、有限候选组合
│   ├── store/ImeStore.kt             # Channel 串行处理 + StateFlow
│   ├── keyboard/                    # 按键布局、无 Android 依赖的焦点导航
│   ├── ime/                         # InputMethodService、EditorInfo 适配
│   └── ui/                          # Compose 键盘与主题
└── res/xml/input_method.xml          # 系统 IME 声明
```

数据流：`遥控器 / Compose → ImeIntent → ImeStore → StateFlow<ImeState> → Compose`；`ImeEffect → InputMethodService → InputConnection`。只有服务操作编辑器，UI 不直接提交文字。服务为 Compose 提供 LifecycleOwner / SavedStateRegistryOwner；每个编辑器会话使用独立 sessionId，过滤旧会话效果。

## 词库扩展与当前范围

内置 **529 条拼音项**，覆盖常用汉字、词句和电视搜索词。这是可运行的基础离线引擎，词频、词库覆盖和长句准确度仍有明显提升空间；未实现商业输入法级别的全量词库、完整简拼、模糊音、个性化学习、手写或语音识别。

修改 `assets/pinyin.tsv`，每行使用 **Tab** 分隔拼音与候选，多个候选以空格分隔，同一拼音的候选按词频从高到低排列：

```text
ni	你 尼 呢 泥
hao	好 号 浩
nihao	你好
dianshi	电视
```

示例中的 `\t` 在实际文件中应为 Tab 字符。后续可在 `PinyinEngine` 接入合法授权的大词库或成熟拼音引擎，保持 MVI / UI 契约。内置词库为本项目人工整理的基础示例。

## 验证

- 本次构建：Debug APK 生成成功；32 项 JVM 测试、3 项 Android 15 模拟器 Compose 测试全部通过；Lint 为 0 errors / 10 warnings（固定依赖版本、TV 横屏 / Banner 等提示）。
- 系统 IME 冒烟验证：原生 D-pad 右移 + OK 输入一次 `w`，返回清除；`nihao` → 上移候选 → OK 向真实 EditText 提交「你好」。验证完成后已恢复模拟器原输入法。
- JVM 测试覆盖连续拼音、断词边界、候选消耗长度、分页、会话、密码类型、MVI 效果、焦点边界及可达性。
- Compose instrumentation 测试验证真实 D-pad 焦点与单次确认输入：`./gradlew :app:connectedDebugAndroidTest`。
- 电视验收建议覆盖：720p / 1080p 显示、长按方向键、分页末页、拼音残留时切换输入框、密码 / 邮箱 / 数字输入、搜索 / 发送 / 换行、返回两次与连续启停输入区。厂商电视固件的 IME 窗口和遥控分发存在差异，仍需目标真机验证。

实现参考：[Android 输入法服务](https://developer.android.com/develop/ui/views/touch-and-input/creating-input-method)、[Compose 焦点遍历](https://developer.android.com/develop/ui/compose/touch-input/focus/focus-traversal)、[AGP 8.10 / Gradle 兼容性](https://developer.android.com/build/releases/agp-8-10-0-release-notes)。

## 模拟器截图

![TV 输入法界面及候选焦点](docs/screenshots/keyboard.png)


![引导与测试输入](docs/screenshots/setup.png)