華為劉海屏手機安卓O版本適配指導

1. 背景

劉海屏指的是手機螢幕正上方由於追求極致邊框而採用的一種手機解決方案。因形似劉海兒而得名。也有一些其他叫法：挖孔屏、凹口屏等，本文件統一按照劉海屏來命名。市場上已經有越來越多的手機都支援這種螢幕形式。

谷歌在安卓P版本中已經提供了統一的適配方案，可是在安卓O版本上如何適配呢？本文將詳細介紹華為安卓O版本劉海屏適配方案。使用華為提供的劉海屏SDK進行適配，此方案也會繼承到華為安卓P版本手機上。在華為P版本手機中將同時支援兩種方案：華為O版本方案+谷歌P版本方案。另外因為安卓O版本的劉海屏手機已經在市場上大量上市，這些手機在市場上會存續2~3年。所以建議大家現在要同時適配華為O版本方案以及谷歌P版本方案。

2. 華為已經發布的劉海屏手機資訊

3. 華為劉海屏手機安卓O版本適配方案

設計理念：儘量減少APP的開發工作量

處理邏輯：

4. 華為劉海屏API介面

4.1 判斷是否劉海屏

4.1.1 介面描述

4.1.2 呼叫範例

public static boolean hasNotchInScreen(Context context) {

    boolean ret = false;

    try {

        ClassLoader cl = context.getClassLoader();

        Class HwNotchSizeUtil = cl.loadClass("com.huawei.android.util.HwNotchSizeUtil");

        Method get = HwNotchSizeUtil.getMethod("hasNotchInScreen");

        ret = (boolean) get.invoke(HwNotchSizeUtil);

    } catch (ClassNotFoundException e) {

        Log.e("test", "hasNotchInScreen ClassNotFoundException");

    } catch (NoSuchMethodException e) {

        Log.e("test", "hasNotchInScreen NoSuchMethodException");

    } catch (Exception e) {

        Log.e("test", "hasNotchInScreen Exception");

    } finally {

        return ret;

    }

}

4.2 獲取劉海尺寸

4.2.1 介面描述

4.2.2 呼叫範例

public static int[] getNotchSize(Context context) {

    int[] ret = new int[]{0, 0};

    try {

        ClassLoader cl = context.getClassLoader();

        Class HwNotchSizeUtil = cl.loadClass("com.huawei.android.util.HwNotchSizeUtil");

        Method get = HwNotchSizeUtil.getMethod("getNotchSize");

        ret = (int[]) get.invoke(HwNotchSizeUtil);

    } catch (ClassNotFoundException e) {

        Log.e("test", "getNotchSize ClassNotFoundException");

    } catch (NoSuchMethodException e) {

        Log.e("test", "getNotchSize NoSuchMethodException");

    } catch (Exception e) {

        Log.e("test", "getNotchSize Exception");

    } finally {

        return ret;

    }

}

4.3 應用頁面設定使用劉海區顯示

4.3.1 方案一

使用新增的Meta-data屬性android.notch_support，在應用的AndroidManifest.xml中增加meta-data屬性，此屬性不僅可以針對Application生效，也可以對Activity配置生效。

1. 具體方式如下所示：

<meta-data android:name="android.notch_support" android:value="true"/>

2. 對Application生效，意味著該應用的所有頁面，系統都不會做豎屏場景的特殊下移或者是橫屏場景的右移特殊處理：

<application

    android:allowBackup="true"

    android:icon="@mipmap/ic_launcher"

    android:label="@string/app_name"

    android:roundIcon="@mipmap/ic_launcher_round"

    android:testOnly="false"

    android:supportsRtl="true"

    android:theme="@style/AppTheme">

    <meta-data android:name="android.notch_support" android:value="true"/>

    <activity android:name=".MainActivity">

        <intent-filter>

            <action android:name="android.intent.action.MAIN"/>



            <category android:name="android.intent.category.LAUNCHER"/>

        </intent-filter>

    </activity>

3. 對Activity生效，意味著可以針對單個頁面進行劉海屏適配，設定了該屬性的Activity系統將不會做特殊處理：

<application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:testOnly="false"
    android:supportsRtl="true"
    android:theme="@style/AppTheme">
    <activity android:name=".MainActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN"/>

            <category android:name="android.intent.category.LAUNCHER"/>
        </intent-filter>
    </activity>
    <activity android:name=".LandscapeFullScreenActivity" android:screenOrientation="sensor">
    </activity>
    <activity android:name=".FullScreenActivity">
        <meta-data android:name="android.notch_support" android:value="true"/>
    </activity>

4.3.2 方案二

使用給window新增新增的FLAG_NOTCH_SUPPORT

1. 介面1描述：應用通過增加華為自定義的劉海屏flag，請求使用劉海區顯示：

呼叫範例參考：

對Application生效，意味著該應用的所有頁面，系統都不會做豎屏場景的特殊下移或者是橫屏場景的右移特殊處理：

/*劉海屏全屏顯示FLAG*/
public static final int FLAG_NOTCH_SUPPORT=0x00010000;
/**
 * 設定應用視窗在華為劉海屏手機使用劉海區
 * @param window 應用頁面window物件
 */
public static void setFullScreenWindowLayoutInDisplayCutout(Window window) {
    if (window == null) {
        return;
    }
    WindowManager.LayoutParams layoutParams = window.getAttributes();
    try {
        Class layoutParamsExCls = Class.forName("com.huawei.android.view.LayoutParamsEx");
        Constructor con=layoutParamsExCls.getConstructor(LayoutParams.class);
        Object layoutParamsExObj=con.newInstance(layoutParams);
        Method method=layoutParamsExCls.getMethod("addHwFlags", int.class);
        method.invoke(layoutParamsExObj, FLAG_NOTCH_SUPPORT);
    } catch (ClassNotFoundException | NoSuchMethodException | IllegalAccessException |InstantiationException 
    | InvocationTargetException e) {
        Log.e("test", "hw add notch screen flag api error");
    } catch (Exception e) {
        Log.e("test", "other Exception");
    }
}

2. 介面2描述：可以通過clearHwFlags介面清除新增的華為劉海屏Flag，恢復應用不使用劉海區顯示。

呼叫範例參考：

/*劉海屏全屏顯示FLAG*/
public static final int FLAG_NOTCH_SUPPORT=0x00010000;
/**
 * 設定應用視窗在華為劉海屏手機使用劉海區
 * @param window 應用頁面window物件
 */
public static void setNotFullScreenWindowLayoutInDisplayCutout (Window window) {
    if (window == null) {
        return;
    }
    WindowManager.LayoutParams layoutParams = window.getAttributes();
    try {
        Class layoutParamsExCls = Class.forName("com.huawei.android.view.LayoutParamsEx");
        Constructor con=layoutParamsExCls.getConstructor(LayoutParams.class);
        Object layoutParamsExObj=con.newInstance(layoutParams);
        Method method=layoutParamsExCls.getMethod("clearHwFlags", int.class);
        method.invoke(layoutParamsExObj, FLAG_NOTCH_SUPPORT);
    } catch (ClassNotFoundException | NoSuchMethodException | IllegalAccessException |InstantiationException 
    | InvocationTargetException e) {
        Log.e("test", "hw clear notch screen flag api error");
    } catch (Exception e) {
        Log.e("test", "other Exception");
    }
}

3. 華為劉海屏flag動態新增和刪除程式碼：

btn.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        if(isAdd) {//add flag
            isAdd = false;
            NotchSizeUtil.setFullScreenWindowLayoutInDisplayCutout(getWindow());           
            getWindowManager().updateViewLayout(getWindow().getDecorView(),getWindow().getDecorView().getLayoutParams());
        } else{//clear flag
            isAdd = true;
            NotchSizeUtil.setNotFullScreenWindowLayoutInDisplayCutout(getWindow());            
            getWindowManager().updateViewLayout(getWindow().getDecorView(),getWindow().getDecorView().getLayoutParams());
        }
    }
});

4. 使用和不使用劉海區效果對比：

設定使用劉海區效果圖                                                 不使用劉海區的效果圖

設定使用劉海區效果圖                                                                             不使用劉海區的效果圖

4.4 獲取預設和隱藏劉海區開關值介面

4.4.1 開關頁面介紹

1. 老版本路徑：“系統設定” > “顯示” > “顯示區域控制”。

2. 新版本路徑：“系統設定” > “顯示” > “螢幕頂部顯示”

4.4.2 隱藏開關開啟之後，顯示規格

4.4.3 讀取開關狀態呼叫範例

public static final String DISPLAY_NOTCH_STATUS = "display_notch_status";
int mIsNotchSwitchOpen = Settings.Secure.getInt(getContentResolver(),DISPLAY_NOTCH_STATUS, 0);  
// 0表示“預設”，1表示“隱藏顯示區域”

5. 谷歌P版本劉海屏適配方案

5.1 特性介紹

Android P 支援最新的全面屏以及為攝像頭和揚聲器預留空間的凹口螢幕。 通過全新的 DisplayCutout 類，可以確定非功能區域的位置和形狀，這些區域不應顯示內容。 要確定這些凹口螢幕區域是否存在及其位置，請使用 getDisplayCutout() 函式。

1. 全新的窗口布局屬性 layoutInDisplayCutoutMode 讓您的應用可以為裝置凹口螢幕周圍的內容進行佈局。 您可以將此屬性設為下列值之一：

（1）LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
（2）LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
（3）LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER

2. 您可以按如下方法在任何執行 Android P 的裝置或模擬器上模擬螢幕缺口：

（1）啟用開發者選項。
（2）在 Developer options 螢幕中，向下滾動至 Drawing 部分並選擇 Simulate a display with a cutout。
（3）選擇凹口螢幕的大小。

注意：

我們建議您通過使用執行 Android P 的裝置或模擬器測試凹口螢幕周圍的內容顯示。

5.2 介面介紹

1. 獲取劉海尺寸相關介面：

2. 設定是否延伸到劉海區顯示介面：

5.3 參考實現程式碼

1. 設定使用劉海區顯示程式碼：

getSupportActionBar().hide();
getWindow().getDecorView().setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN | 
View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN); 
//設定頁面全屏顯示
WindowManager.LayoutParams lp = getWindow().getAttributes();
lp.layoutInDisplayCutoutMode = 
       windowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES; 
//設定頁面延伸到劉海區顯示
getWindow().setAttributes(lp);

注意：如果需要應用的佈局延伸到劉海區顯示，需要設定SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN。

屬性：

不使用SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN     使用SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN

         佈局無法延伸到劉海顯示                              佈局可以正真延伸到劉海區顯示

2. 獲取劉海屏安全顯示區域和劉海尺寸資訊：

contentView = getWindow().getDecorView().findViewById(android.R.id.content).getRootView();
contentView.setOnApplyWindowInsetsListener(new View.OnApplyWindowInsetsListener() {
    @Override
    public WindowInsets onApplyWindowInsets(View view, WindowInsets windowInsets) {
        DisplayCutout cutout = windowInsets.getDisplayCutout();
        if (cutout == null) {
            Log.e(TAG, "cutout==null, is not notch screen");//通過cutout是否為null判斷是否劉海屏手機
        } else {
            List<Rect> rects = cutout.getBoundingRects();
            if (rects == null || rects.size() == 0) {
                Log.e(TAG, "rects==null || rects.size()==0, is not notch screen");
            } else {
                Log.e(TAG, "rect size:" + rects.size());//注意：劉海的數量可以是多個
                for (Rect rect : rects) {
                    Log.e(TAG, "cutout.getSafeInsetTop():" + cutout.getSafeInsetTop()
                            + ", cutout.getSafeInsetBottom():" + cutout.getSafeInsetBottom()
                            + ", cutout.getSafeInsetLeft():" + cutout.getSafeInsetLeft()
                            + ", cutout.getSafeInsetRight():" + cutout.getSafeInsetRight()
                            + ", cutout.rects:" + rect
                    );
                }
            }
        }
        return windowInsets;
    }
});

3. 說明：

（1）通過windowInsets.getDisplayCutout()是否為null判斷是否劉海屏手機，如果為null為非劉海屏：

Line 6203: 05-24 11:16:46.766 11036 11036 E Cutout_test: cutout==null, is not notch screen

（2）如果是劉海屏手機可以通過介面獲取劉海資訊：

Line 6211: 05-24 11:11:16.839 10733 10733 E Cutout_test: cutout.getSafeInsetTop():126, cutout.getSafeInsetBottom():0, 
cutout.getSafeInsetLeft():0, cutout.getSafeInsetRight():0, cutout.rects:Rect(414, 0 - 666, 126)

（3）劉海個數可以是多個：

Line 6291: 05-24 11:27:04.517 11036 11036 E Cutout_test: rect size:2
Line 6292: 05-24 11:27:04.517 11036 11036 E Cutout_test: cutout.getSafeInsetTop():84, 
cutout.getSafeInsetBottom():84, cutout.getSafeInsetLeft():0, cutout.getSafeInsetRight():0, cutout.rects:Rect(351, 0 - 729, 84)
Line 6293: 05-24 11:27:04.517 11036 11036 E Cutout_test: cutout.getSafeInsetTop():84, 
cutout.getSafeInsetBottom():84, cutout.getSafeInsetLeft():0, cutout.getSafeInsetRight():0, cutout.rects:Rect(351, 1836 - 729, 1920)

6. UI適配

通過上面的2種方案（meta-data或者Flag），應用在華為劉海屏手機上就能預設使用劉海區顯示了，為了避免UI被劉海區遮擋，應用還要進一步進行UI適配：

6.1 判斷是否為劉海屏

判斷是否為劉海屏？可以呼叫華為劉海屏API，參考4.1。

6.2 調整佈局

如果是劉海屏，調整佈局避開劉海區。

佈局原則：保證重要的文字、圖片、視訊資訊、可點選的控制元件和圖示，應用彈窗等，建議顯示在狀態列區域以下（安全區域）。如果內容不重要或者不會遮擋，佈局可以延伸到狀態列區域（危險區域）。

建議按照如下佈局原則修改：

獲取系統狀態列高度介面：

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;
}

建議視窗顯示內容在狀態列區域以下的另外一個原因：華為有一個自研的隱藏劉海的需求，可以參考章節4.4。

7. 除錯環境

7.1 真機

購買已經上市的華為劉海屏手機，如P20/P20 Pro/榮耀10/Nova 3e等。也可以求助華為三方團隊，申請華為劉海屏樣機進行適配除錯，需要提供樣機接收人資訊：公司、姓名、電話、郵編和地址，郵件反饋到：[email protected]。我們會盡快安排手機投遞。

7.2 遠端除錯

華為終端開放實驗室DevEco雲測平臺的遠端除錯已經支援華為劉海屏了。

7.2.1 新使用者註冊

先加入安卓綠色聯盟會員，然後申請開通華為終端開放實驗室DevEco雲測平臺帳號就可以了，所有服務都是免費的。

2. 使用公司郵箱進行帳號註冊。

3. 將您新申請的帳號、所在公司、個人姓名及電話、負責的應用名稱傳送至[email protected]，申請成為安卓綠色聯盟會員，通過稽核後，將為您開通使用許可權

7.2.2 遠端除錯

2. 選擇劉海屏手機，如Nova 3e。

3. 點選“立即體驗”，上傳APK進行除錯。

8. 技術支援

如果您在適配過程中遇到任何技術問題，可以發郵件至[email protected]，郵件主題：“華為劉海屏適配+APP名字”’

也可以加“安卓綠色聯盟”微訊號，加入技術支援群討論。