ใช้การแสดงภาพซ้อนภาพ (PIP)

ลองใช้วิธีแบบ Compose

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

การแสดงภาพซ้อนภาพ →

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

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

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

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

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

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

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

• แตะสองครั้งที่หน้าต่างเพื่อสลับระหว่างขนาด PiP ปัจจุบันกับขนาด PiP สูงสุดหรือต่ำสุด เช่น การแตะสองครั้งที่หน้าต่างที่ขยายใหญ่สุดจะย่อขนาดหน้าต่าง และในทางกลับกันก็เช่นกัน

• ซ่อนหน้าต่างโดยลากไปที่ขอบด้านซ้ายหรือขวา หากต้องการนำหน้าต่างที่ซ่อนไว้ออกมา ให้แตะส่วนที่มองเห็นได้ของหน้าต่างที่ซ่อนไว้หรือลากออกมา

• ปรับขนาดหน้าต่าง PIP โดยใช้การบีบเพื่อซูม

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

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

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

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

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

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

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

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

Implement PiP with Jetpack

Use the Jetpack Picture-in-Picture library to implement picture-in-picture experience as it streamlines integration and reduces common in-app issues. Refer to our platform sample app to see an example of its usage. However, if you prefer to implement PiP using the platform APIs, refer to the following documentation.

เปลี่ยนกิจกรรมเป็น PiP

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

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

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

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

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

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

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

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

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

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

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

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

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

ทำตามขั้นตอนต่อไปนี้เพื่อทำการเปลี่ยนแปลง

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

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

Note: When `setAutoEnterEnabled` is enabled, you don't need to explicitly
call [`enterPictureInPictureMode`][5] in [`onUserLeaveHint`][6].

1. โทรหา setPictureInPictureParams พร้อมข้อมูลล่าสุด PictureInPictureParams ก่อนเวลา แอปจะไม่รอ Callback onUserLeaveHint (เหมือนที่เคยทำใน Android 11)

   เช่น คุณอาจต้องการเรียกใช้ setPictureInPictureParams ในการเล่นครั้งแรกและการเล่นครั้งต่อๆ ไปหากมีการเปลี่ยนแปลงสัดส่วนภาพ

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

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

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

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

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

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

val mOnLayoutChangeListener =
    OnLayoutChangeListener { v: View?, left: Int,
            top: Int, right: Int, bottom: Int, oldLeft: Int, oldTop:
            Int, oldRight: Int, oldBottom: Int ->
        val sourceRectHint = Rect()
        mYourVideoView.getGlobalVisibleRect(sourceRectHint)
        val builder = PictureInPictureParams.Builder()
            .setSourceRectHint(sourceRectHint)
        setPictureInPictureParams(builder.build())
    }

mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener)

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

// 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()
        )
    }
}

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

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

วิธีเปิดใช้การปรับขนาดเนื้อหาวิดีโออย่างราบรื่น

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

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

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

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

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

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

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

override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
    if (!isInPictureInPictureMode) {
        // Unhide UI elements.
    }
}

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

ลบล้าง Callback เหล่านี้เพื่อวาดองค์ประกอบ 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 (ระดับ API 24) ขึ้นไป คุณควรหยุดเล่นวิดีโอชั่วคราวและเล่นต่อเมื่อระบบเรียกใช้ onStop() และ onStart() ของกิจกรรม การทำเช่นนี้จะช่วยให้คุณไม่ต้องตรวจสอบว่าแอปอยู่ในโหมด PiP ใน onPause() หรือไม่ และเล่นต่ออย่างชัดเจน

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

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

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

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

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

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

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

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

รองรับ PiP สำหรับแอปกล้อง

หากต้องการเปิดใช้ PiP สำหรับแอปกล้อง คุณควรตรวจสอบว่ากล้องยังคงทำงานอยู่ในโหมด PiP โดยไม่ปิดกล้องเมื่อมีการเรียกใช้ onPause() ดังนี้

override fun onPause() {
    super.onPause()
    // Don't close the camera if the app is entering PiP mode
    if (!isInPictureInPictureMode) {
        closeCamera()
    }
}

เช่นเดียวกับกรณีการใช้งานอื่นๆ ให้ซ่อนองค์ประกอบ UI ที่ไม่จำเป็น (เช่น ตัวควบคุมและโอเวอร์เลย์) และเพิ่มการดำเนินการที่กำหนดเองเพื่อควบคุมกล้อง (เช่น หยุดบันทึกหรือพลิกกล้อง)

คำนวณ sourceRectHint เพื่อให้การเปลี่ยนผ่านเป็นไปอย่างราบรื่น

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

val previewView = findViewById<View>(R.id.preview_view)
val globalRect = Rect()
// Ensure the view is laid out before calling getGlobalVisibleRect() to get valid screen coordinates.
previewView.getGlobalVisibleRect(globalRect)
val params = PictureInPictureParams.Builder()
    .setSourceRectHint(globalRect)
    .build()
setPictureInPictureParams(params)

ข้อพิจารณาเพิ่มเติม

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

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

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

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

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

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

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