# AndroidScreenMatch

**Repository Path**: yemesoft/android-screen-match

## Basic Information

- **Project Name**: AndroidScreenMatch
- **Description**: 零负担适配常用设备屏幕
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Android Screen Match 屏幕适配方案

本项目采用基于 **Smallest Width (sw)** 的 Android 屏幕适配方案，通过脚本生成多套 dimens 资源，实现不同宽度设备的等比布局与字体适配。

按设计稿宽度提供 **4 个互斥模块**，按需二选一接入即可（不可同时依赖多个，否则 `dl_dp_*` 资源名冲突）：

| 模块 | 设计稿宽度 | 本地依赖 | 远程 artifact |
|------|------------|----------|---------------|
| `screenmatch1200` | **1200px** | `project(':screenmatch1200')` | `android-screen-match-1200` |
| `screenmatch1080` | **1080px** | `project(':screenmatch1080')` | `android-screen-match-1080` |
| `screenmatch750` | **750px** | `project(':screenmatch750')` | `android-screen-match-750` |
| `screenmatch720` | **720px** | `project(':screenmatch720')` | `android-screen-match-720` |

## 快速开始

### 方式一：模块依赖（推荐本地联调）

```groovy
dependencies {
    // 按设计稿宽度四选一（示例为 1200）
    implementation project(':screenmatch1200')
    // implementation project(':screenmatch1080')
    // implementation project(':screenmatch750')
    // implementation project(':screenmatch720')
}
```

### 方式二：远程依赖（JitPack / Gitee）

根目录 `settings.gradle`（或旧版根 `build.gradle`）添加仓库：

```groovy
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

业务模块：

```groovy
dependencies {
    // 按设计稿宽度选择其一
    implementation 'com.gitee.yemesoft:android-screen-match-1200:1.8' // 1200
    // implementation 'com.gitee.yemesoft:android-screen-match-1080:1.8' // 1080
    // implementation 'com.gitee.yemesoft:android-screen-match-750:1.8'  // 750
    // implementation 'com.gitee.yemesoft:android-screen-match-720:1.8'  // 720
}
```

> 各模块发布配置分别写在对应 `build.gradle`（`maven-publish`）。打 Tag `1.8` 后即可由 JitPack 构建。

## 设计图尺寸与 Dimen 对应关系

**一句话总结：** 将设计图缩放到所选模块的设计宽度，标注尺寸 xxx，对应 `@dimen/dl_dp_xxx` / `@dimen/dl_sp_xxx`。

### 转换示例（以 1200 模块、sw360dp 为例）

| 设计图标注（1200px 宽度） | Dimen 引用 | 实际值（sw360dp） |
|--------------------------|------------|-------------------|
| 10px | `@dimen/dl_dp_10` | 3.00dp |
| 20px | `@dimen/dl_dp_20` | 6.00dp |
| 100px | `@dimen/dl_dp_100` | 30.00dp |
| 200px | `@dimen/dl_dp_200` | 60.00dp |
| -10px | `@dimen/dl_dp_m_10` | -3.00dp |
| 28px（字体） | `@dimen/dl_sp_28` | 8.40sp |

### 各设计宽下同一标注的 sw360 对照

| 标注 xxx | 1200 模块 | 1080 模块 | 750 模块 | 720 模块 |
|----------|-----------|-----------|----------|----------|
| `dl_dp_10` | 3.00dp | 3.33dp | 4.80dp | 5.00dp |
| `dl_dp_100` | 30.00dp | 33.33dp | 48.00dp | 50.00dp |
| `dl_sp_28` | 8.40sp | 9.33sp | 13.44sp | 14.00sp |

### 在布局文件中使用

```xml
<Button
    android:layout_width="@dimen/dl_dp_200"
    android:layout_height="@dimen/dl_dp_96"
    android:padding="@dimen/dl_dp_32"
    android:textSize="@dimen/dl_sp_28"
    android:text="确认" />
```

### 在代码中使用

```kotlin
// getDimension / getDimensionPixelSize 返回的是 px
val widthPx = resources.getDimensionPixelSize(R.dimen.dl_dp_200)
val textPx = resources.getDimension(R.dimen.dl_sp_28)

// 若需要 dp/sp 数值：
val widthDp = widthPx / resources.displayMetrics.density
val textSp = textPx / resources.displayMetrics.scaledDensity
```

## 适配原理

### 基准

- 设计稿宽度：按所选模块（1200 / 1080 / 750 / 720）
- 基准 smallest width：**sw360dp**
- **dp 与 sp 使用同一缩放比例**，避免大屏「控件变大、字号仍停在 360」的问题

### 缩放公式

```
实际值 = 设计标注 xxx × 目标 sw ÷ 设计稿宽度
```

示例（1200 模块）：

| sw | dl_dp_10 | dl_sp_28 |
|----|----------|----------|
| 360 | 3.00dp | 8.40sp |
| 411 | 3.42dp | 9.59sp |
| 480 | 4.00dp | 11.20sp |
| 1024 | 8.53dp | 23.89sp |

## Dimen 命名规则

```
设计图缩放到所选模块的设计宽度
标注 xxx 像素 → @dimen/dl_dp_xxx / @dimen/dl_sp_xxx
负值：@dimen/dl_dp_m_xxx
精度：两位小数
```

## 已生成的分辨率（92 档）

各模块共用同一套 sw 档位：

- **常规**：sw320dp～sw1200dp，每 **10dp** 一档
- **特殊机型**：sw411dp、sw811dp、sw1024dp（公式与其它档位一致：`xxx×sw/设计宽`，且含同步缩放的 sp）

设备会匹配 **不超过自身 sw 的最大档位**。例如 sw415 → sw411，sw625 → sw620。

## 尺寸范围

| 类型 | xxx 范围 | 说明 |
|------|----------|------|
| dp | 1～3920（含负值 `_m_`） | 各模块按各自设计宽缩放 |
| sp | 1～400 | 与 dp 同比例 |

## 资源生成与校验

仓库内脚本（需 Python 3）：

```bash
# 重新生成全部模块 dimens，并删除过时 sw 目录
python scripts/generate_dimens.py generate

# 只生成 / 校验某一设计宽模块
python scripts/generate_dimens.py all --module screenmatch1200
python scripts/generate_dimens.py all --module screenmatch1080
python scripts/generate_dimens.py all --module screenmatch750
python scripts/generate_dimens.py all --module screenmatch720

# 校验公式、sp 是否齐全
python scripts/generate_dimens.py verify

# 生成 + 校验（全部模块）
python scripts/generate_dimens.py all
```

修改设计宽度、档位列表或尺寸范围时，请只改 `scripts/generate_dimens.py` 后重新生成，避免手工改 XML。

## 版本说明

- **1.8**：模块 `screenmatch` 重命名为 `screenmatch1200`；新增 1080 / 750 / 720 设计宽模块；artifact 统一为 `android-screen-match-{设计宽}`
- **1.7**：统一全部 sw（含 411/811/1024）为 `xxx×sw/设计宽`；各档同步缩放 sp；保留 sw320～1200 每 10dp 全量档位；提供生成/校验脚本
- 从旧版（720 设计宽或错误特殊档）升级时，同一 `@dimen` 在部分机型上实际 dp/sp 会变化，请回归布局
- 从 1.7 升级到 1.8：本地依赖由 `:screenmatch` 改为 `:screenmatch1200`；远程 artifact 由 `android-screen-match` 改为 `android-screen-match-1200`

## Demo

`app` 模块展示当前设备 `smallestScreenWidthDp`、抽样 dimen 的 px/dp/sp，以及固定设计尺寸色块，便于多设备对比（默认依赖 1200 的 `screenmatch1200`）。