หน้านี้ได้รับการแปลโดย Cloud Translation API

เพิ่มวิดีโอโดยใช้การแสดงภาพซ้อนภาพ (PIP)

Jetpack Compose เป็นชุดเครื่องมือ UI ที่แนะนำสำหรับ Android ดูวิธีรองรับการแสดงภาพซ้อนภาพใน Compose

ตั้งแต่ Android 8.0 (API ระดับ 26) เป็นต้นไป Android อนุญาตให้กิจกรรมเปิดในโหมดภาพซ้อนภาพ (PiP) PiP คือโหมดหลายหน้าต่างประเภทพิเศษที่ใช้สำหรับการเล่นวิดีโอเป็นส่วนใหญ่ โดยผู้ใช้สามารถดูวิดีโอในหน้าต่างเล็กๆ ที่ตรึงไว้ที่มุมของหน้าจอขณะไปยังแอปต่างๆ หรือเรียกดูเนื้อหาบนหน้าจอหลัก

PIP ใช้ประโยชน์จาก API ของหลายหน้าต่างที่มีให้ใช้งานใน Android 7.0 เพื่อแสดงหน้าต่างวางซ้อนวิดีโอที่ปักหมุดไว้ หากต้องการเพิ่ม PIP ลงในแอป คุณต้องลงทะเบียนกิจกรรมที่รองรับ PIP, เปลี่ยนกิจกรรมเป็นโหมด PIP ตามความจำเป็น และตรวจสอบว่าองค์ประกอบ UI ซ่อนอยู่และเล่นวิดีโอต่อเมื่อกิจกรรมอยู่ในโหมด PIP

หน้าต่าง PiP จะปรากฏในเลเยอร์บนสุดของหน้าจอที่มุมที่ระบบเลือก

นอกจากนี้ PiP ยังใช้ได้กับอุปกรณ์ระบบปฏิบัติการ Android TV ที่เข้ากันได้ซึ่งใช้ Android 14 (API ระดับ 34) ขึ้นไป แม้จะมีความคล้ายคลึงกันมากมาย แต่ก็มีข้อพิจารณาเพิ่มเติมเมื่อใช้ PIP บนทีวี

วิธีที่ผู้ใช้โต้ตอบกับหน้าต่าง PIP

ผู้ใช้ลากหน้าต่าง PIP ไปยังตำแหน่งอื่นได้ ตั้งแต่ Android 12 เป็นต้นไป ผู้ใช้ยังทำสิ่งต่อไปนี้ได้

แตะหน้าต่างเดียวเพื่อแสดงการเปิด/ปิดโหมดเต็มหน้าจอ ปุ่มปิด ปุ่มการตั้งค่า และการดำเนินการที่กำหนดเองซึ่งแอปมีให้ (เช่น ตัวควบคุมการเล่น)
แตะสองครั้งที่หน้าต่างเพื่อสลับระหว่างขนาด PIP ปัจจุบันกับขนาด PIP สูงสุดหรือต่ำสุด เช่น การแตะสองครั้งที่หน้าต่างที่ขยายใหญ่สุดจะย่อหน้าต่างนั้น และในทางกลับกัน
ซ่อนหน้าต่างไว้โดยลากไปที่ขอบด้านซ้ายหรือขวา หากต้องการยกเลิกการซ่อนหน้าต่าง ให้แตะส่วนที่มองเห็นได้ของหน้าต่างที่ซ่อน หรือลากหน้าต่างออก
ปรับขนาดหน้าต่าง PIP โดยใช้การบีบเพื่อซูม

แอปจะควบคุมเมื่อกิจกรรมปัจจุบันเข้าสู่โหมด PiP ตัวอย่างเช่น

กิจกรรมสามารถเข้าสู่โหมด PIP เมื่อผู้ใช้แตะปุ่มหน้าแรกหรือปัดขึ้นเพื่อไปที่หน้าแรก วิธีนี้ช่วยให้ Google Maps แสดงเส้นทางต่อไปได้ขณะที่ผู้ใช้ทำกิจกรรมอื่นในเวลาเดียวกัน
แอปของคุณสามารถย้ายวิดีโอเข้าสู่โหมด PIP เมื่อผู้ใช้ย้อนกลับจากวิดีโอเพื่อเรียกดูเนื้อหาอื่น
แอปของคุณเปลี่ยนวิดีโอเป็นโหมด PIP ได้ขณะที่ผู้ใช้ดูเนื้อหาตอนจบ หน้าจอหลักจะแสดงข้อมูลโปรโมตหรือข้อมูลสรุปเกี่ยวกับตอนถัดไปในซีรีส์
แอปของคุณมีวิธีให้ผู้ใช้จัดคิวเนื้อหาเพิ่มเติมในขณะที่ดูวิดีโอ วิดีโอจะเล่นต่อในโหมดภาพซ้อนภาพขณะที่หน้าจอหลักแสดงกิจกรรมการเลือกเนื้อหา

ประกาศการรองรับ PIP

โดยค่าเริ่มต้น ระบบจะไม่รองรับ PiP สำหรับแอปโดยอัตโนมัติ หากต้องการรองรับ PIP ในแอป ให้ลงทะเบียนกิจกรรมวิดีโอในไฟล์ Manifest โดยตั้งค่า android:supportsPictureInPicture เป็น true นอกจากนี้ ให้ระบุว่ากิจกรรมจัดการการเปลี่ยนแปลงการกําหนดค่าเลย์เอาต์ด้วย เพื่อไม่ให้กิจกรรมเปิดขึ้นมาใหม่เมื่อมีการเปลี่ยนแปลงเลย์เอาต์ระหว่างการเปลี่ยนโหมด PIP

<activity android:name="VideoActivity"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation"
    ...

เปลี่ยนกิจกรรมเป็นโหมด PIP

ตั้งแต่ Android 12 เป็นต้นไป คุณสามารถเปลี่ยนกิจกรรมเป็นโหมด PIP ได้โดยการตั้งค่า Flag setAutoEnterEnabled เป็น true เมื่อใช้การตั้งค่านี้ กิจกรรมจะเปลี่ยนเป็นโหมด PIP โดยอัตโนมัติตามที่จำเป็นโดยไม่ต้องเรียกใช้ enterPictureInPictureMode() ใน onUserLeaveHint อย่างชัดแจ้ง และยังมีข้อดีเพิ่มเติมคือช่วยให้การเปลี่ยนเป็นไปอย่างราบรื่นยิ่งขึ้น โปรดดูรายละเอียดที่หัวข้อทําให้การเปลี่ยนไปใช้โหมด PiP ราบรื่นขึ้นจากการไปยังส่วนต่างๆ ด้วยท่าทางสัมผัส

หากคุณกําหนดเป้าหมายเป็น Android 11 หรือต่ำกว่า กิจกรรมจะต้องเรียกใช้ enterPictureInPictureMode() เพื่อเปลี่ยนเป็นโหมด PIP ตัวอย่างเช่น โค้ดต่อไปนี้จะเปลี่ยนกิจกรรมเป็นโหมด PiP เมื่อผู้ใช้คลิกปุ่มเฉพาะใน UI ของแอป

KotlinJava

override fun onActionClicked(action: Action) {
    if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
        activity?.enterPictureInPictureMode()
        return
    }
}

@Override
public void onActionClicked(Action action) {
    if (action.getId() == R.id.lb_control_picture_in_picture) {
        getActivity().enterPictureInPictureMode();
        return;
    }
    ...
}

คุณอาจต้องใส่ตรรกะที่เปลี่ยนกิจกรรมเป็นโหมด PIP แทนที่จะเปลี่ยนไปทำงานในเบื้องหลัง เช่น Google Maps จะเปลี่ยนไปใช้โหมด PIP หากผู้ใช้กดปุ่มหน้าแรกหรือล่าสุดขณะที่แอปกำลังนำทาง คุณจับกรณีนี้ได้โดยการลบล้าง onUserLeaveHint()

KotlinJava

override fun onUserLeaveHint() {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode()
    }
}

@Override
public void onUserLeaveHint () {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode();
    }
}

แนะนำ: มอบประสบการณ์การเปลี่ยน PIP ที่สมบูรณ์แบบให้แก่ผู้ใช้

Android 12 ได้เพิ่มการปรับปรุงรูปลักษณ์ที่สำคัญให้กับการเปลี่ยนภาพเคลื่อนไหวระหว่างหน้าต่างแบบเต็มหน้าจอกับหน้าต่าง PIP เราขอแนะนำอย่างยิ่งให้ทำการเปลี่ยนแปลงที่เกี่ยวข้องทั้งหมด โดยเมื่อคุณดำเนินการแล้ว การเปลี่ยนแปลงเหล่านี้จะปรับขนาดให้เหมาะกับหน้าจอขนาดใหญ่โดยอัตโนมัติ เช่น อุปกรณ์แบบพับได้และแท็บเล็ต โดยที่คุณไม่ต้องดำเนินการใดๆ เพิ่มเติม

หากแอปไม่มีการอัปเดตที่เกี่ยวข้อง การเปลี่ยน PIP จะยังคงใช้งานได้ แต่ภาพเคลื่อนไหวจะคมชัดน้อยลง เช่น การเปลี่ยนจากโหมดเต็มหน้าจอเป็นโหมด PIP อาจทำให้หน้าต่าง PIP หายไปในระหว่างการเปลี่ยนก่อนที่จะปรากฏขึ้นอีกครั้งเมื่อการเปลี่ยนเสร็จสมบูรณ์

การเปลี่ยนแปลงเหล่านี้เกี่ยวข้องกับสิ่งต่อไปนี้

เปลี่ยนจากการนำทางด้วยท่าทางสัมผัสไปยังโหมด PIP ได้อย่างราบรื่นยิ่งขึ้น
การตั้งค่า sourceRectHint ที่เหมาะสมสำหรับการเข้าและออกจากโหมด PIP
การปิดใช้การปรับขนาดเนื้อหาที่ไม่ใช่วิดีโออย่างราบรื่น

โปรดดูตัวอย่าง Kotlin PictureInPicture สำหรับ Android เพื่อใช้เป็นข้อมูลอ้างอิงสำหรับการเปลี่ยนฉากอย่างลงตัว

เปลี่ยนเป็นโหมด PIP ได้อย่างราบรื่นยิ่งขึ้นจากการไปยังส่วนต่างๆ ด้วยท่าทางสัมผัส

ตั้งแต่ Android 12 เป็นต้นไป แฟล็ก setAutoEnterEnabled จะมีภาพเคลื่อนไหวที่ลื่นไหลขึ้นมากสำหรับการเปลี่ยนเป็นเนื้อหาวิดีโอในโหมด PIP โดยใช้การไปยังส่วนต่างๆ ด้วยท่าทางสัมผัส เช่น เมื่อปัดขึ้นจากโหมดเต็มหน้าจอ

ทำตามขั้นตอนต่อไปนี้เพื่อทำการเปลี่ยนแปลงและดูตัวอย่างนี้สำหรับข้อมูลอ้างอิง

ใช้ setAutoEnterEnabled เพื่อสร้าง PictureInPictureParams.Builder:

KotlinJava

setPictureInPictureParams(PictureInPictureParams.Builder()
    .setAspectRatio(aspectRatio)
    .setSourceRectHint(sourceRectHint)
    .setAutoEnterEnabled(true)
    .build())

setPictureInPictureParams(new PictureInPictureParams.Builder()
    .setAspectRatio(aspectRatio)
    .setSourceRectHint(sourceRectHint)
    .setAutoEnterEnabled(true)
    .build());

โทรหา setPictureInPictureParams พร้อมข้อมูลล่าสุด PictureInPictureParamsตั้งแต่เนิ่นๆ แอปไม่ต้องรอการเรียกกลับ onUserLeaveHint (อย่างที่ควรจะทำใน Android 11)

เช่น คุณอาจต้องเรียกใช้ setPictureInPictureParams ในการเล่นครั้งแรก และการเล่นต่อไปนี้ หากสัดส่วนภาพมีการเปลี่ยนแปลง
โทรหา setAutoEnterEnabled(false) แต่เฉพาะในกรณีที่จำเป็นเท่านั้น เช่น คุณอาจไม่ต้องการเข้าสู่โหมด PIP หากการเล่นปัจจุบันอยู่ในสถานะหยุดชั่วคราว

ตั้งค่า `sourceRectHint` ที่เหมาะสมสำหรับการเข้าและออกจากโหมด PIP

ตั้งแต่มีการเปิดตัว PiP ใน Android 8.0 setSourceRectHint ได้ระบุพื้นที่ของกิจกรรมที่มองเห็นได้หลังจากเปลี่ยนเป็นโหมดภาพในภาพ เช่น ขอบเขตของมุมมองวิดีโอในโปรแกรมเล่นวิดีโอ

เมื่อใช้ Android 12 ระบบจะใช้ sourceRectHint เพื่อแสดงภาพเคลื่อนไหวที่ราบรื่นยิ่งขึ้นทั้งเมื่อเข้าและออกจากโหมด PIP

วิธีตั้งค่า sourceRectHint ให้ถูกต้องสำหรับการเข้าและออกจากโหมด PiP

สร้าง PictureInPictureParams โดยใช้ขอบเขตที่เหมาะสมเป็น sourceRectHint เราขอแนะนำให้แนบ Listener การเปลี่ยนเลย์เอาต์ไว้ในโปรแกรมเล่นวิดีโอด้วย

KotlinJava

val mOnLayoutChangeListener =
OnLayoutChangeListener { v: View?, oldLeft: Int,
        oldTop: Int, oldRight: Int, oldBottom: Int, newLeft: Int, newTop:
        Int, newRight: Int, newBottom: Int ->
    val sourceRectHint = Rect()
    mYourVideoView.getGlobalVisibleRect(sourceRectHint)
    val builder = PictureInPictureParams.Builder()
        .setSourceRectHint(sourceRectHint)
    setPictureInPictureParams(builder.build())
}

mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener)

private final View.OnLayoutChangeListener mOnLayoutChangeListener =
        (v, oldLeft, oldTop, oldRight, oldBottom, newLeft, newTop, newRight,
        newBottom) -> {
    final Rect sourceRectHint = new Rect();
    mYourVideoView.getGlobalVisibleRect(sourceRectHint);
    final PictureInPictureParams.Builder builder =
        new PictureInPictureParams.Builder()
            .setSourceRectHint(sourceRectHint);
    setPictureInPictureParams(builder.build());
};

mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener);

หากจำเป็น ให้อัปเดต sourceRectHint ก่อนระบบจะเริ่มการเปลี่ยนสถานะออก เมื่อระบบกำลังจะออกจากโหมด PiP ระบบจะจัดวางลําดับชั้นมุมมองของกิจกรรมไปยังการกำหนดค่าปลายทาง (เช่น เต็มหน้าจอ) แอปสามารถแนบตัวรับฟังการเปลี่ยนแปลงเลย์เอาต์กับมุมมองรูทหรือมุมมองเป้าหมาย (เช่น มุมมองวิดีโอเพลเยอร์) เพื่อตรวจหาเหตุการณ์และอัปเดต sourceRectHint ก่อนเริ่มภาพเคลื่อนไหว

KotlinJava

// Listener is called immediately after the user exits PiP but before animating.
playerView.addOnLayoutChangeListener { _, left, top, right, bottom,
                    oldLeft, oldTop, oldRight, oldBottom ->
    if (left != oldLeft
        || right != oldRight
        || top != oldTop
        || bottom != oldBottom) {
        // The playerView's bounds changed, update the source hint rect to
        // reflect its new bounds.
        val sourceRectHint = Rect()
        playerView.getGlobalVisibleRect(sourceRectHint)
        setPictureInPictureParams(
            PictureInPictureParams.Builder()
                .setSourceRectHint(sourceRectHint)
                .build()
        )
    }
}

// Listener is called right after the user exits PiP but before animating.
playerView.addOnLayoutChangeListener((v, left, top, right, bottom,
                    oldLeft, oldTop, oldRight, oldBottom) -> {
    if (left != oldLeft
        || right != oldRight
        || top != oldTop
        || bottom != oldBottom) {
        // The playerView's bounds changed, update the source hint rect to
        // reflect its new bounds.
        final Rect sourceRectHint = new Rect();
        playerView.getGlobalVisibleRect(sourceRectHint);
        setPictureInPictureParams(
            new PictureInPictureParams.Builder()
                .setSourceRectHint(sourceRectHint)
                .build());
    }
});

ปิดใช้การปรับขนาดแบบต่อเนื่องสำหรับเนื้อหาที่ไม่ใช่วิดีโอ

Android 12 เพิ่ม Flag setSeamlessResizeEnabled ซึ่งช่วยให้ภาพเคลื่อนไหวที่ค่อยๆ เปลี่ยนรูปภาพราบรื่นขึ้นมากเมื่อปรับขนาดเนื้อหาที่ไม่ใช่วิดีโอในหน้าต่าง PiP ก่อนหน้านี้ การปรับขนาดเนื้อหาที่ไม่ใช่วิดีโอในหน้าต่าง PIP อาจสร้างอาร์ติแฟกต์ภาพที่น่าสะเทือนใจ

หากต้องการปิดใช้การปรับขนาดเนื้อหาที่ไม่ใช่วิดีโออย่างราบรื่น ให้ทำดังนี้

KotlinJava

setPictureInPictureParams(PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(false)
    .build())

setPictureInPictureParams(new PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(false)
    .build());

จัดการ UI ระหว่าง PIP

เมื่อกิจกรรมเข้าหรือออกจากโหมดการแสดงภาพซ้อนภาพ (PIP) ระบบจะเรียกใช้ Activity.onPictureInPictureModeChanged() หรือ Fragment.onPictureInPictureModeChanged()

Android 15 มาพร้อมกับการเปลี่ยนแปลงที่ช่วยให้การเปลี่ยนผ่านราบรื่นยิ่งขึ้นเมื่อเข้าสู่โหมด PIP ซึ่งมีประโยชน์สำหรับแอปที่มีองค์ประกอบ UI ซ้อนทับบน UI หลัก ซึ่งจะอยู่ในรูปแบบ PIP

นักพัฒนาแอปใช้ Callback onPictureInPictureModeChanged() เพื่อกำหนดตรรกะที่สลับการเปิดเผยองค์ประกอบ UI ที่วางซ้อน Callback นี้จะทริกเกอร์เมื่อภาพเคลื่อนไหวของ PiP เข้าหรือออกเสร็จสมบูรณ์ คลาส PictureInPictureUiState จะมีสถานะใหม่เริ่มตั้งแต่ Android 15

สถานะ UI ใหม่นี้ทำให้แอปที่กำหนดเป้าหมายเป็น Android 15 พบการเรียกกลับ Activity#onPictureInPictureUiStateChanged() ด้วย isTransitioningToPip() ทันทีที่ภาพเคลื่อนไหว PIP เริ่มขึ้น มีองค์ประกอบ UI หลายอย่างที่ไม่เกี่ยวข้องกับแอปเมื่ออยู่ในโหมด PIP เช่น มุมมองหรือเลย์เอาต์ที่มีข้อมูลอย่างเช่น คำแนะนำ วิดีโอที่กำลังจะเผยแพร่ การจัดประเภท และชื่อ เมื่อแอปเข้าสู่โหมด PIP ให้ใช้ Callback onPictureInPictureUiStateChanged() เพื่อซ่อนองค์ประกอบ UI เหล่านี้ เมื่อแอปเปิดโหมดเต็มหน้าจอจากหน้าต่าง PIP ให้ใช้ Callback onPictureInPictureModeChanged() เพื่อเลิกซ่อนองค์ประกอบ ดังที่แสดงในตัวอย่างต่อไปนี้

KotlinJava

override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) {
        if (pipState.isTransitioningToPip()) {
          // Hide UI elements.
        }
    }

@Override
public void onPictureInPictureUiStateChanged(PictureInPictureUiState pipState) {
        if (pipState.isTransitioningToPip()) {
          // Hide UI elements.
        }
    }

KotlinJava

override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean) {
        if (isInPictureInPictureMode) {
          // Unhide UI elements.
        }
    }

@Override
public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
        if (isInPictureInPictureMode) {
          // Unhide UI elements.
        }
    }

การเปิด/ปิดการแสดงผลองค์ประกอบ UI ที่ไม่เกี่ยวข้องอย่างรวดเร็ว (สำหรับหน้าต่าง PiP) นี้ช่วยให้มั่นใจได้ว่าภาพเคลื่อนไหวของ PiP ที่ปรากฏจะราบรื่นและไม่มีภาพกะพริบ

ลบล้างการเรียกกลับเหล่านี้เพื่อวาดองค์ประกอบ UI ของกิจกรรมอีกครั้ง โปรดทราบว่าในโหมด PIP กิจกรรมจะแสดงในหน้าต่างเล็กๆ ผู้ใช้จะโต้ตอบกับองค์ประกอบ UI ของแอปไม่ได้เมื่อแอปอยู่ในโหมด PiP และรายละเอียดขององค์ประกอบ UI ขนาดเล็กอาจมองเห็นได้ยาก กิจกรรมการเล่นวิดีโอที่มี UI น้อยที่สุดจะให้ประสบการณ์การใช้งานที่ดีที่สุดแก่ผู้ใช้

หากแอปของคุณต้องมีการดำเนินการที่กำหนดเองสำหรับ PIP โปรดดูเพิ่มการควบคุมในหน้านี้ นำองค์ประกอบ UI อื่นๆ ออกก่อนที่กิจกรรมจะเข้าสู่โหมด PIP และกู้คืนเมื่อกิจกรรมกลับมาเป็นแบบเต็มหน้าจออีกครั้ง

เพิ่มตัวควบคุม

หน้าต่าง PIP จะแสดงตัวควบคุมเมื่อผู้ใช้เปิดเมนูของหน้าต่าง (โดยแตะหน้าต่างในอุปกรณ์เคลื่อนที่หรือเลือกเมนูจากรีโมตทีวี)

หากแอปมีเซสชันสื่อที่ใช้งานอยู่ ตัวควบคุม "เล่น" "หยุดชั่วคราว" "ถัดไป" และก่อนหน้าจะปรากฏขึ้น

คุณยังระบุการดำเนินการที่กำหนดเองอย่างชัดเจนได้ด้วยการสร้าง PictureInPictureParams ด้วย PictureInPictureParams.Builder.setActions() ก่อนเข้าสู่โหมด PIP และส่งพารามิเตอร์เมื่อคุณเข้าสู่โหมด PIP โดยใช้ enterPictureInPictureMode(android.app.PictureInPictureParams) หรือ setPictureInPictureParams(android.app.PictureInPictureParams) โปรดระมัดระวัง หากคุณพยายามเพิ่มมากกว่า getMaxNumPictureInPictureActions() คุณจะได้รับเฉพาะจำนวนสูงสุดเท่านั้น

เล่นวิดีโอต่อขณะที่อยู่ใน PIP

เมื่อกิจกรรมเปลี่ยนเป็น PIP ระบบจะวางกิจกรรมไว้ในสถานะหยุดชั่วคราวและเรียกใช้เมธอด onPause() ของกิจกรรม การเล่นวิดีโอไม่ควรหยุดชั่วคราวและควรเล่นต่อหากกิจกรรมหยุดชั่วคราวขณะเปลี่ยนเป็นโหมด PIP

ใน Android 7.0 ขึ้นไป คุณควรหยุดวิดีโอชั่วคราวและเล่นวิดีโอต่อเมื่อระบบเรียกใช้กิจกรรม onStop() และ onStart() ซึ่งจะช่วยให้คุณไม่ต้องตรวจสอบว่าแอปอยู่ในโหมด PIP ใน onPause() หรือไม่ และไม่ต้องเล่นต่ออย่างชัดแจ้ง

หากยังไม่ได้ตั้งค่าแฟล็ก setAutoEnterEnabled เป็น true และต้องการหยุดเล่นชั่วคราวในการใช้งาน onPause() ให้ตรวจหาโหมด PIP โดยการเรียกใช้ isInPictureInPictureMode() และจัดการการเล่นอย่างเหมาะสม เช่น

KotlinJava

override fun onPause() {
    super.onPause()
    // If called while in PiP mode, do not pause playback.
    if (isInPictureInPictureMode) {
        // Continue playback.
    } else {
        // Use existing playback logic for paused activity behavior.
    }
}

@Override
public void onPause() {
    // If called while in PiP mode, do not pause playback.
    if (isInPictureInPictureMode()) {
        // Continue playback.
        ...
    } else {
        // Use existing playback logic for paused activity behavior.
        ...
    }
}

เมื่อกิจกรรมออกจากโหมด PIP กลับไปเป็นโหมดเต็มหน้าจอ ระบบจะกลับมาทำกิจกรรมอีกครั้งและเรียกใช้เมธอด onResume()

ใช้กิจกรรมการเล่นรายการเดียวสำหรับ PIP

ในแอป ผู้ใช้อาจเลือกวิดีโอใหม่เมื่อเรียกดูเนื้อหาบนหน้าจอหลักขณะที่กิจกรรมการเล่นวิดีโออยู่ในโหมดภาพซ้อนภาพ เล่นวิดีโอใหม่ในกิจกรรมการเล่นที่มีอยู่ในรูปแบบเต็มหน้าจอแทนการเปิดกิจกรรมใหม่ซึ่งอาจทำให้ผู้ใช้สับสน

เพื่อให้แน่ใจว่าจะมีการใช้กิจกรรมเดียวสำหรับคำขอเล่นวิดีโอและสลับเป็นหรือออกจากโหมด PIP ตามความจำเป็น ให้ตั้งค่า android:launchMode ของกิจกรรมเป็น singleTask ในไฟล์ Manifest ดังนี้

<activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

ในกิจกรรมของคุณ ให้ลบล้าง onNewIntent() และจัดการวิดีโอใหม่โดยหยุดเล่นวิดีโอที่มีอยู่ หากจำเป็น

แนวทางปฏิบัติแนะนำ

ระบบอาจปิดใช้ PiP ในอุปกรณ์ที่มี RAM ต่ำ ก่อนที่แอปจะใช้ PiP ให้ตรวจสอบว่า PiP พร้อมใช้งานแล้วโดยเรียกใช้ hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE)

PIP มีไว้สำหรับกิจกรรมที่เล่นวิดีโอแบบเต็มหน้าจอ เมื่อเปลี่ยนกิจกรรมเป็นโหมด PIP ให้หลีกเลี่ยงการแสดงสิ่งใดก็ตามที่ไม่ใช่เนื้อหาวิดีโอ ติดตามเมื่อกิจกรรมเข้าสู่โหมด PIP และซ่อนองค์ประกอบ UI ตามที่อธิบายไว้ในการจัดการ UI ขณะใช้โหมด PIP

เมื่อกิจกรรมอยู่ในโหมด PIP กิจกรรมนั้นจะไม่ได้รับการโฟกัสอินพุตโดยค่าเริ่มต้น หากต้องการรับเหตุการณ์อินพุตขณะอยู่ในโหมด PIP ให้ใช้ MediaSession.setCallback() ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ setCallback() ได้ที่แสดงการ์ดกำลังเล่น

เมื่อแอปอยู่ในโหมด PIP การเล่นวิดีโอในหน้าต่าง PIP อาจทำให้เกิดการรบกวนเสียงกับแอปอื่น เช่น แอปโปรแกรมเล่นเพลงหรือแอปค้นหาด้วยเสียง เพื่อหลีกเลี่ยงปัญหานี้ ให้ขอโฟกัสเสียงเมื่อคุณเริ่มเล่นวิดีโอและจัดการการแจ้งเตือนการเปลี่ยนโฟกัสเสียง ตามที่อธิบายไว้ในการจัดการโฟกัสเสียง หากคุณได้รับการแจ้งเตือนว่าเสียงไม่โฟกัสเมื่ออยู่ในโหมด PIP ให้หยุดหรือหยุดเล่นวิดีโอชั่วคราว

เมื่อแอปของคุณใกล้จะเข้าสู่โหมดภาพในภาพ โปรดทราบว่าเฉพาะกิจกรรมด้านบนเท่านั้นที่จะเข้าสู่โหมดภาพในภาพ ในบางสถานการณ์ เช่น บนอุปกรณ์หลายหน้าต่าง กิจกรรมด้านล่างอาจแสดงขึ้นและกลับมาแสดงอีกครั้งพร้อมกับกิจกรรม PIP ได้ คุณควรจัดการเคสนี้ รวมถึงกิจกรรมด้านล่างที่ได้รับ onResume() หรือ Callback onPause() นอกจากนี้ยังเป็นไปได้ว่าผู้ใช้อาจโต้ตอบกับกิจกรรม ตัวอย่างเช่น หากคุณมีกิจกรรมรายการวิดีโอแสดงอยู่และกิจกรรมการเล่นวิดีโอในโหมด PIP ผู้ใช้อาจเลือกวิดีโอใหม่จากรายการ และกิจกรรม PIP ควรอัปเดตตามการเปลี่ยนแปลงนี้

โค้ดตัวอย่างเพิ่มเติม

หากต้องการดาวน์โหลดแอปตัวอย่างที่เขียนด้วย Kotlin โปรดดูตัวอย่างโหมดภาพซ้อนภาพใน Android (Kotlin)

เพิ่มวิดีโอโดยใช้การแสดงภาพซ้อนภาพ (PIP)

วิธีที่ผู้ใช้โต้ตอบกับหน้าต่าง PIP

ประกาศการรองรับ PIP

เปลี่ยนกิจกรรมเป็นโหมด PIP

แนะนำ: มอบประสบการณ์การเปลี่ยน PIP ที่สมบูรณ์แบบให้แก่ผู้ใช้

เปลี่ยนเป็นโหมด PIP ได้อย่างราบรื่นยิ่งขึ้นจากการไปยังส่วนต่างๆ ด้วยท่าทางสัมผัส

ตั้งค่า sourceRectHint ที่เหมาะสมสำหรับการเข้าและออกจากโหมด PIP

ปิดใช้การปรับขนาดแบบต่อเนื่องสำหรับเนื้อหาที่ไม่ใช่วิดีโอ

จัดการ UI ระหว่าง PIP

เพิ่มตัวควบคุม

เล่นวิดีโอต่อขณะที่อยู่ใน PIP

ใช้กิจกรรมการเล่นรายการเดียวสำหรับ PIP

แนวทางปฏิบัติแนะนำ

โค้ดตัวอย่างเพิ่มเติม

ตั้งค่า `sourceRectHint` ที่เหมาะสมสำหรับการเข้าและออกจากโหมด PIP