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

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

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 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"
    ...

ใช้ PIP ด้วย Jetpack

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

เปลี่ยนกิจกรรมเป็นโหมด 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
• การปิดใช้การปรับขนาดอย่างราบรื่นสำหรับเนื้อหาที่ไม่ใช่วิดีโอ

ดูตัวอย่าง Picture-in-Picture ของ 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 ตั้งแต่เนิ่นๆ แอปจะไม่รอ onUserLeaveHintการเรียกกลับ (ซึ่งจะเกิดขึ้นใน Android 11)

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

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

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

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

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

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

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

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 เป็นไปอย่างราบรื่นยิ่งขึ้นเมื่อ เข้าสู่โหมด PIP ซึ่งจะเป็นประโยชน์สำหรับแอปที่มีองค์ประกอบ UI ซ้อนทับอยู่ด้านบนของ UI หลักซึ่งจะเข้าสู่โหมด PIP

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

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

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 จะราบรื่นและไม่กะพริบ

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

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

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