準確獲取螢幕幾何信息、系統 UI 高度、文字測量數據是適配佈局、自定義 View、彈窗定位、沉浸式設計的基礎。本文匯總標準 API、兼容性處理、Kotlin 擴展函數封裝,解決「不同 API 版本行為不一致、刘海屏/水滴屏適配、多窗口模式」等實戰難題。
| API 版本 | 推薦獲取螢幕尺寸方式 | 棄用/不推薦 |
|---|---|---|
| API 1-12 | Display.getWidth()/getHeight() | - |
| API 13-29 | DisplayMetrics / WindowManager | Display.getWidth/Height (棄用) |
| API 30+ (R) | WindowMetricsCalculator / WindowInsets | DisplayMetrics (部分屬性不可靠) |
object ScreenUtils {
/** 螢幕寬度 (px) - 包含狀態欄、導航欄、系統飾邊 */
fun getScreenWidth(context: Context): Int {
return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
val metrics = WindowMetricsCalculator.getOrCreate()
.computeCurrentWindowMetrics((context as Activity).windowManager.currentWindowToken!!)
.bounds()
metrics.width()
} else {
context.resources.displayMetrics.widthPixels
}
}
/** 螢幕高度 (px) */
fun getScreenHeight(context: Context): Int {
return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
val metrics = WindowMetricsCalculator.getOrCreate()
.computeCurrentWindowMetrics((context as Activity).windowManager.currentWindowToken!!)
.bounds()
metrics.height()
} else {
context.resources.displayMetrics.heightPixels
}
}
/** 狀態欄高度 (px) - 兼容刘海屏、水滴屏 */
fun getStatusBarHeight(context: Context): Int {
var result = 0
val resourceId = context.resources.getIdentifier("status_bar_height", "dimen", "android")
if (resourceId > 0) {
result = context.resources.getDimensionPixelSize(resourceId)
}
// 兜底:WindowInsets (API 20+)
if (result == 0 && Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT_WATCH) {
val window = (context as Activity).window
val insets = window.decorView.rootWindowInsets
if (insets != null) {
result = insets.getInsets(WindowInsets.Type.statusBars()).top
}
}
return result
}
/** 導航欄高度 (px) - 手勢導航模式下可能為 0 */
fun getNavigationBarHeight(context: Context): Int {
var result = 0
val resourceId = context.resources.getIdentifier("navigation_bar_height", "dimen", "android")
if (resourceId > 0) {
result = context.resources.getDimensionPixelSize(resourceId)
}
if (result == 0 && Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT_WATCH) {
val window = (context as Activity).window
val insets = window.decorView.rootWindowInsets
if (insets != null) {
result = insets.getInsets(WindowInsets.Type.navigationBars()).bottom
}
}
return result
}
/** 可用內容區域高度 (扣除狀態欄、導航欄、系統飾邊) */
fun getContentHeight(activity: Activity): Int {
val window = activity.window
val decorView = window.decorView
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
val metrics = WindowMetricsCalculator.getOrCreate()
.computeCurrentWindowMetrics(windowManager.currentWindowToken!!)
val bounds = metrics.bounds()
val insets = metrics.windowInsets
val statusBar = insets.getInsets(WindowInsets.Type.statusBars()).top
val navBar = insets.getInsets(WindowInsets.Type.navigationBars()).bottom
val ime = insets.getInsets(WindowInsets.Type.ime()).bottom
return bounds.height() - statusBar - max(navBar, ime)
} else {
val rect = Rect()
decorView.getWindowVisibleDisplayFrame(rect)
val screenHeight = resources.displayMetrics.heightPixels
val statusBar = rect.top
val navBar = screenHeight - rect.bottom
return screenHeight - statusBar - navBar
}
}
/** 螢幕物理尺寸 (英寸) - 基於 DPI 計算 */
fun getScreenInches(context: Context): Double {
val dm = context.resources.displayMetrics
val widthInches = dm.widthPixels / dm.xdpi
val heightInches = dm.heightPixels / dm.ydpi
return Math.hypot(widthInches, heightInches)
}
/** 文字寬度 (px) - 使用 Paint.measureText */
fun measureTextWidth(paint: Paint, text: String): Float {
return paint.measureText(text)
}
/** 文字高度 (px) - 使用 FontMetrics */
fun measureTextHeight(paint: Paint): Float {
val fm = paint.fontMetrics
return (fm.bottom - fm.top).ceilToInt().toFloat()
}
/** TextView 實際測量寬高 (需 layout 完成後調用) */
fun measureTextView(textView: TextView): Pair {
val paint = textView.paint
val width = paint.measureText(textView.text.toString()).ceilToInt()
val height = measureTextHeight(paint).ceilToInt()
return Pair(width, height)
}
}
public class ScreenUtils {
// 獲取螢幕寬高
public static int getScreenWidth(Context context) {
DisplayMetrics dm = context.getResources().getDisplayMetrics();
return dm.widthPixels;
}
public static int getScreenHeight(Context context) {
DisplayMetrics dm = context.getResources().getDisplayMetrics();
return dm.heightPixels;
}
// 獲取狀態欄高度
public static int getStatusBarHeight(Context context) {
int result = 0;
int resourceId = context.getResources().getIdentifier("status_bar_height", "dimen", "android");
if (resourceId > 0) {
result = context.getResources().getDimensionPixelSize(resourceId);
}
return result;
}
// 獲取導航欄高度
public static int getNavigationBarHeight(Context context) {
int result = 0;
int resourceId = context.getResources().getIdentifier("navigation_bar_height", "dimen", "android");
if (resourceId > 0) {
result = context.getResources().getDimensionPixelSize(resourceId);
}
return result;
}
// 文字寬度
public static float measureTextWidth(TextView textView, String text) {
TextPaint paint = textView.getPaint();
return paint.measureText(text);
}
// 文字高度
public static float measureTextHeight(TextView textView) {
TextPaint paint = textView.getPaint();
Paint.FontMetrics fm = paint.getFontMetrics();
return fm.bottom - fm.top;
}
// 螢幕尺寸 (英寸)
public static double getScreenInches(Context context) {
DisplayMetrics dm = context.getResources().getDisplayMetrics();
double w = Math.pow(dm.widthPixels / dm.xdpi, 2);
double h = Math.pow(dm.heightPixels / dm.ydpi, 2);
return Math.sqrt(w + h);
}
}
// Kotlin
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
window.decorView.systemUiVisibility = View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
window.statusBarColor = Color.TRANSPARENT
// 導航欄透明 (可選)
window.navigationBarColor = Color.TRANSPARENT
}
// 佈局根節點設置 fitsSystemWindows="true" 或手動 padding
rootView.setOnApplyWindowInsetsListener { view, insets ->
val statusBar = insets.getInsets(WindowInsets.Type.statusBars()).top
val navBar = insets.getInsets(WindowInsets.Type.navigationBars()).bottom
view.setPadding(0, statusBar, 0, navBar)
insets
}
val dialog = BottomSheetDialog(this)
dialog.setContentView(R.layout.dialog_bottom)
val behavior = BottomSheetBehavior.from(dialog.window.decorView.findViewById(com.google.android.material.R.id.design_bottom_sheet))
behavior.state = BottomSheetBehavior.STATE_EXPANDED
// 監聽鍵盤/導航欄變化調整位置
WindowCompat.setDecorFitsSystemWindows(dialog.window, false)
ViewCompat.setOnApplyWindowInsetsListener(dialog.window.decorView) { view, insets ->
val imeInset = insets.getInsets(WindowInsets.Type.ime()).bottom
val navInset = insets.getInsets(WindowInsets.Type.navigationBars()).bottom
val bottomPadding = max(imeInset, navInset)
view.setPadding(view.paddingLeft, view.paddingTop, view.paddingRight, bottomPadding)
insets
}
override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
val text = "示例文字"
val textWidth = paint.measureText(text).ceilToInt()
val fm = paint.fontMetrics
val textHeight = (fm.bottom - fm.top).ceilToInt()
val desiredWidth = textWidth + paddingLeft + paddingRight
val desiredHeight = textHeight + paddingTop + paddingBottom
setMeasuredDimension(
resolveSize(desiredWidth, widthMeasureSpec),
resolveSize(desiredHeight, heightMeasureSpec)
)
}
| 錯誤現象 | 根本原因 | 正確做法 |
|---|---|---|
| getWidth()/getHeight() 返回 0 | View 未完成 layout (onCreate/onResume 中調用) | ViewTreeObserver.OnGlobalLayoutListener / doOnPreDraw / onWindowFocusChanged |
| 狀態欄高度獲取為 0 | 沉浸式模式下系統不佔用空間、資源 ID 變更 | WindowInsets API 兜底、資源 ID 反射兜底 |
| 螢幕尺寸包含導航欄導致佈局溢出 | 使用 displayMetrics 而非 WindowMetrics (API 30+) | WindowMetricsCalculator.computeCurrentWindowMetrics() |
| 文字測量高度不準 | 使用 getTextSize() 而非 FontMetrics | FontMetrics.bottom - top (含上行/下行間距) |
| 多窗口/分屏模式尺寸錯誤 | 假設全屏尺寸 | WindowMetrics 基於當前窗口 Token 獲取 |
// Compose 中自動處理內邊距
Box(modifier = Modifier
.fillMaxSize()
.windowInsetsPadding(WindowInsets.systemBars) // 自動避開狀態欄/導航欄
.imePadding() // 自動避開鍵盤
) { /* 內容 */ }
// View 系統中使用 Insetter (github.com/google/accompanist/insets)
Insetter(view) { insets ->
val statusBar = insets[WindowInsets.Type.statusBars()].top
val navBar = insets[WindowInsets.Type.navigationBars()].bottom
// 應用 padding/margin
}
掌握螢幕幾何信息獲取的版本演進與最佳實踐,是 Android UI 適配能力的核心指標。建議項目中統一接入 ScreenUtils 單例,配合 WindowInsets 機制,徹底解決適配焦慮。