Files
ElderlyDialer/tools/screenmatch/README.md
T

49 lines
2.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ScreenMatch 尺寸资源生成工具
仅在开发电脑上运行,不打包进 APK,不修改 density。需要 JDK 11+;项目 Gradle 应继续使用其兼容的 JDK。
在 ElderlyDialer 根目录运行:
```powershell
# 预览:仅写入 build/screenmatch-preview/res
.\gradlew.bat screenMatchPreview
# 正式生成:覆盖/新增 app/src/main/res/values-swNNNdp/dimens.xml
.\gradlew.bat screenMatch
```
Android Studio 的 Gradle 面板中也可从 `screen match` 分组手动运行。普通构建不会触发生成。
配置文件为 `tools/screenmatch/screenmatch.properties`,不是根目录旧 IDE 插件的 `screenMatch.properties`。请勿交替使用旧插件生成同一批资源。
| 配置 | 默认值 | 作用 |
|---|---|---|
| base_dp | 360 | 默认 values/dimens.xml 的设计基准宽度 |
| min_dp / max_dp / step_dp | 240 / 600 / 2 | 手机尺寸范围及步长,可设为 1dp |
| extra_dp | 393,411 | 额外整数档位,逗号分隔 |
| qualifier | sw | 与当前项目保持一致,可选 w,但必须先迁移旧 sw 资源 |
| scale_sp | true | 是否同步缩放字体,系统字体设置仍然生效 |
| include_existing | true | 将已有相同限定符档位纳入生成,修复旧资源不同步 |
| exclude_names | 空 | 保持原尺寸的资源名称,逗号分隔 |
| res_dir | app/src/main/res | 输入及正式输出资源目录 |
以默认 `values/dimens.xml` 为唯一来源,数值乘以 `目标宽度 / base_dp`,保留四位小数。支持 dp/dip/sp、负数、小数、零;引用及其他单位保持原样,XML 属性和注释保留。正式写入前会检查所有目标文件,不允许悄悄覆盖仅存在于目标档位的自定义尺寸;需先将其合并到默认文件。文件内容相同时不重写。工具不删除任何过期文件;缩小范围或改变配置后需检查旧目录是否仍会被选中。
例如:400dp 档位下 `24sp -> 26.6667sp`,`64dp -> 71.1111dp`。
默认沿用 sw 是为了兼容现有项目:横屏时仍按最小宽度匹配。若改为按当前窗口宽度匹配,应统一迁移为 w,不能直接叠加旧 sw 文件。Android 选择不超过可用宽度的合适档位,不做插值;2dp 步长在 240~600dp 范围内宽度比例的档位误差小于约 0.84%(不含像素取整)。范围之外不保证该误差。
`include_existing=true` 会继续按原比例更新旧的平板档位,**不代表已经完成平板布局适配**。平板需要独立布局及设计基准;本工具只生成尺寸,不能解决长宽比、系统栏、大字体造成的布局空间不足。
可指定另一配置文件:
```powershell
.\gradlew.bat screenMatchPreview -PscreenMatchConfig=tools/screenmatch/custom.properties
```
也可绕过 Gradle,直接用 JDK 运行(第三个参数为预览输出目录,省略则写回正式资源):
```powershell
java tools/screenmatch/ScreenMatch.java . tools/screenmatch/screenmatch.properties build/screenmatch-preview/res
```