PhotoView 搬上 Android TV:遥控器导航与焦点框改造

【免费下载链接】PhotoViewImplementation of ImageView for Android that supports zooming, by various touch gestures.项目地址: https://gitcode.com/gh_mirrors/ph/PhotoView

客厅里,你坐在沙发上,手里只有一台遥控器,却想放大这张家里的合影看细节。手机上两根手指一搓就完成的事,在电视大屏上得靠方向键一步步做。PhotoView 是 Android 上现成的图片缩放组件;要把它搬上 Android TV,补的就是按键导航和焦点反馈。

电视和手机的“距离”:两米视距差在哪

同样是一张图,手机和电视对它的要求差得不少:

手机上靠手完成的缩放、平移、定位,到电视上全要换成键和焦点来表达。所以要改三类东西:程序声明、按键交互、焦点反馈,下面动手做。

🔧 动手改:从特性声明到焦点适配

五步走完,遥控器就能接管 PhotoView 的平移和缩放。

在 Manifest 里声明电视特性

电视没有触摸屏,不声明 touchscreen 可选,应用可能从电视列表里被过滤掉;leanback 特性则表明这是 TV 应用,写法可对照 sample 的 Manifest。

<uses-feature android:name="android.hardware.touchscreen" android:required="false" /> <uses-feature android:name="android.software.leanback" android:required="true" />

装到真机,电视主页的应用列表里会出现这个应用,手机上运行则不受影响。

把 PhotoView 依赖引进来

PhotoView 是第三方库,系统里没有,按坐标引入即可,版本沿用 2.3.0。

dependencies { implementation 'com.github.chrisbanes:photoview:2.3.0' }

想跑官方示例,执行git clone https://gitcode.com/gh_mirrors/ph/PhotoView后打开 sample 模块;同步完成后,项目里可以直接引用 PhotoView 这个类。

给布局加上焦点属性

方向键移动的是焦点而不是手指,不可聚焦的视图收不到按键事件,焦点属性必须显式打开。

<com.github.chrisbanes.photoview.PhotoView android:id="@+id/photo_view" android:layout_width="match_parent" android:layout_height="match_parent" android:scaleType="centerInside" android:focusable="true" android:focusableInTouchMode="true"/>

真机上按方向键,焦点会停在图片上,系统默认高亮一闪而过,两米外根本看不出来——下一步自己画。

让方向键和 ± 键驱动平移与缩放

PhotoView 的手势体系只监听触摸事件,遥控器不产生触摸,按键就得手动翻译成矩阵操作:方向键做平移,± 键做缩放。

private static final float ZOOM_STEP = 1.2f; // 每按一次放大的倍数 private static final float PAN_STEP = 120f; // 每按一次平移的像素 photoView.setOnKeyListener((v, keyCode, event) -> { if (event.getAction() != KeyEvent.ACTION_DOWN) { return false; } Matrix m = new Matrix(); photoView.getSuppMatrix(m); float dx = 0, dy = 0; switch (keyCode) { case KeyEvent.KEYCODE_DPAD_UP: dy = -PAN_STEP; break; case KeyEvent.KEYCODE_DPAD_DOWN: dy = PAN_STEP; break; case KeyEvent.KEYCODE_DPAD_LEFT: dx = PAN_STEP; break; case KeyEvent.KEYCODE_DPAD_RIGHT: dx = -PAN_STEP; break; case KeyEvent.KEYCODE_PLUS: photoView.setScale(photoView.getScale() * ZOOM_STEP, true); return true; case KeyEvent.KEYCODE_MINUS: photoView.setScale(photoView.getScale() / ZOOM_STEP, true); return true; default: return false; } m.postTranslate(dx, dy); return photoView.setDisplayMatrix(m); });

真机连按方向键,图片跟着走;按 + 和 − 平滑缩放,到边界会被自动夹住,不会把图拉出屏幕。

把焦点框画出来

两米外看不见系统默认的浅淡高亮,焦点边框要自己画粗。

<selector xmlns:android="http://schemas.android.com/apk/res/android"> <item android:state_focused="true"> <shape android:shape="rectangle"> <stroke android:width="4dp" android:color="@color/focused_color" /> <corners android:radius="8dp" /> </shape> </item> <item> <shape android:shape="rectangle"> <stroke android:width="0dp" android:color="@color/transparent" /> </shape> </item> </selector>

文件放进 res/drawable/,再给 PhotoView 加一行android:focusBackground指向它;焦点进来时 4dp 边框亮起,移开后边框消失。

🖼️ 让大图在 4K 屏上不卡

大屏图片浏览里,分辨率一高,加载和翻页就是第一个瓶颈。

• 现象:多图页启动时把所有远程图一次性拉下来,首帧要等很久。处理:等页面真要显示才发起网络请求,参考 Coil 示例页 中 Activity 创建时才load并开crossfade的做法。收益:首帧更快,后续翻页直接吃缓存。
• 现象:浏览时间一长,内存越涨越高。处理:在 PagerAdapter 里用instantiateItem按需创建、destroyItem移除离屏视图,ViewPager 示例页 就是翻页时逐页移除 PhotoView 的。收益:连续翻页时内存保持平稳。
• 现象:4K 屏上缩放动画掉帧。处理:开启硬件加速,给图片加载库设合理的内存缓存大小,大图先降采样到显示尺寸再解码。收益:缩放与平移动画保持流畅。

❓ 遥控器按不动时,先查这五处

• 焦点框不显示:确认focusable设了、focusBackground的 selector 在state_focused分支里画了东西;父容器若是自定义 ViewGroup,查它是否拦截了焦点。
• 遥控器无响应:按键事件被父布局消费,或焦点根本不在 PhotoView 上。先把焦点挪到图片上,再检查监听里有没有return true。
• Back 键行为:默认 Back 直接退出。建议放大时按 Back 先复位——当前缩放不等于getMinimumScale()时调setScale(getMinimumScale(), true),已复位再按才退出。
• 大图加载慢:网络图走加载库并降采样,加载中用占位图顶着,别让用户对着黑屏等。
• 多机型翻车:至少找一台 1080p 和一台 4K 的电视(或用 TV 模拟器改分辨率),把下面的验收动作完整走一遍。

照着打勾的验收动作

• 运行 sample 模块的 LauncherActivity,按遥控器 OK 键,示例列表应能选中并进入。
• 电视主页应用列表里能找到该应用,说明 leanback 特性声明生效。
• 进入 Simple Sample 页面,按上下左右方向键,图片应跟着平移。
• 放大状态下按 + 和 −,图片应平滑缩放且不出屏。
• 焦点移到 PhotoView 上,边框应亮起;焦点移开,边框消失。
• 放大后按 Back,应先复位到适配大小,再按一次才退出页面。
• 连续翻页六张,观察内存曲线应基本平稳,翻页不掉帧。
• 在 1080p 与 4K 各一台设备上重复以上动作,焦点大小和图片清晰度应正常。

家庭相册应用要的是放大看细节,商业展示屏要的是翻页稳、焦点看得清。清单里这些动作走一遍,PhotoView 在电视上就真正能用起来。

【免费下载链接】PhotoViewImplementation of ImageView for Android that supports zooming, by various touch gestures.项目地址: https://gitcode.com/gh_mirrors/ph/PhotoView