حالت سازگاری دستگاه

اندروید برای برنامه‌هایی که محدودیت‌های جهت‌گیری یا تغییر اندازه دارند، حالت سازگاری را فعال می‌کند. حالت سازگاری، رفتار قابل قبول برنامه را در دستگاه‌های صفحه بزرگ و تلفن‌های تاشو تضمین می‌کند، اما با قابلیت استفاده نه چندان مطلوب.

لغوهای هر برنامه ، تولیدکنندگان دستگاه، مالکان دستگاه‌های ^مجازی و کاربران را قادر می‌سازد تا رفتار برنامه را تغییر دهند تا طرح‌بندی برنامه بهبود یابد یا از خرابی برنامه‌ها در دستگاه‌های منتخب جلوگیری شود.

اندروید ۱۶

اندروید ۱۶ (سطح API ۳۶) محدودیت‌های جهت‌گیری صفحه نمایش، نسبت ابعاد و قابلیت تغییر اندازه برنامه را نادیده می‌گیرد تا طرح‌بندی برنامه‌ها را روی فرم‌فاکتورهایی با کمترین عرض >= ۶۰۰dp بهبود بخشد.

لغوهای هر برنامه زیر برای برنامه‌هایی که سطح API 36 را هدف قرار می‌دهند، غیرفعال هستند:

• تغییر اجباری برنامه
• برنامه بدون تغییر اجباری
• نرخ تبدیل حداقل-حداقل نسبت ابعاد (OVERRIDE_MIN_ASPECT_RATIO)
• فقط نسبت ابعاد تصویر (OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY)
• نرخ تبدیل متوسط ​​به بالا (OVERRIDE_MIN_ASPECT_RATIO_MEDIUM)
• مقدار بیشینه نسبت ابعادی (OVERRIDE_MIN_ASPECT_RATIO_LARGE)
• تغییر حداقل نسبت ابعاد تصویر به ترازبندی با تقسیم صفحه
• حذف حداقل نسبت ابعاد تصویر (OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN)
• هر جهت‌گیری را نادیده بگیرید
• حذف هر جهت‌گیری به کاربر
• جهت‌گیری نامشخص را به پرتره ترجیح دهید
• حسگر جهت‌گیری نامشخص را نادیده بگیرید
• جهت‌گیری_منظره_را_به_معکوس_تغییر_دهید
• فقط برای دوربین، جهت‌گیری را نادیده بگیرید
• استفاده از نمایش منظره با جهت‌گیری طبیعی را نادیده بگیرید
• OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
• درخواست تغییر مسیر هنگام تشخیص حلقه
• جهت‌گیری درخواستی فراتر از انتظار
• حذف_عنوان_از_برنامه_در_تنظیمات

انصراف

برنامه شما می‌تواند API سطح ۳۶ را هدف قرار دهد اما از رفتار اندروید ۱۶ صرف نظر کند، که در این صورت OVERRIDE_ANY_ORIENTATION_TO_USER قابل اجرا نیست.

اموال آشکار را اعلام کنید

برای انصراف از رفتار سطح 36 API، ویژگی مانیفست PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY را اعلام کنید.

برای انصراف از یک فعالیت خاص، ویژگی را در عنصر <activity> تنظیم کنید:

<activity ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</activity>

برای انصراف از کل برنامه خود، ویژگی را در عنصر <application> تنظیم کنید:

<application ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</application>

دستگاه‌های مرجع

دستگاه‌های زیر ممکن است به دلیل پیکربندی‌های غیرمعمول یا پیکربندی‌هایی که به خوبی توسط برنامه‌ها پشتیبانی نمی‌شوند، نیاز به لغو تنظیمات برای هر برنامه داشته باشند:

• تبلت‌ها: جهت طبیعی برخی از تبلت‌ها، مانند تبلت پیکسل، افقی است. یک دستگاه در جهت طبیعی خود قرار دارد وقتی که Display#getRotation() Surface.ROTATION_0 برمی‌گرداند. اگر برنامه‌ها فرض کنند ROTATION_0 عمودی است، طرح‌بندی برنامه و پیش‌نمایش دوربین می‌تواند با صفحه نمایش دستگاه مطابقت نداشته باشد.
• دستگاه‌های تاشو افقی: برخی از دستگاه‌های تاشو، مانند Pixel Fold، در حالت تا شده در جهت عمودی هستند، اما در حالت باز شده در جهت افقی قرار می‌گیرند. اگر برنامه‌ها فرض کنند که جهت باز شده عمودی است، احتمالاً حلقه‌های چشمک‌زن یا مشکلات طرح‌بندی وجود خواهد داشت.
• گوشی‌های تاشو: گوشی‌های تاشوی باز شده معمولاً در حالت عمودی هستند. اما وقتی تا می‌شوند، معمولاً یک صفحه نمایش کوچک در حالت افقی دارند. برنامه‌ها باید جهت‌های مختلف نمایشگرها را شناسایی و با آنها سازگار شوند.
• نمایشگرهای خارجی: دستگاه‌های منتخب می‌توانند یک جلسه نمایش پنجره دسکتاپ را روی نمایشگرهای خارجی متصل شروع کنند. برنامه‌ها باید از نمایشگرهای خارجی اطلاعاتی مانند اندازه صفحه نمایش و وضوح تصویر را درخواست کنند؛ در غیر این صورت، برنامه‌ها ممکن است فرضیات نادرستی در مورد نمایشگرها داشته باشند که می‌تواند منجر به رفتار نادرست برنامه شود.
• نمایشگرهای خودرو: بسیاری از نمایشگرهای خودرو، اما نه همه آنها، افقی هستند. توسعه برنامه‌های پارک شده برای نمایشگرهای خودرو مشابه توسعه برای تبلت‌ها است.

مشکلات سازگاری رایج

برنامه‌ها اغلب به دلیل محدودیت‌های جهت‌گیری برنامه، محدودیت‌های تغییر اندازه و نسبت ابعاد، مدیریت نادرست جهت‌گیری پیش‌نمایش دوربین و APIهای سوءاستفاده‌شده، با مشکلات سازگاری مواجه می‌شوند.

جعبه حروف

قرار دادن برنامه در حالت Letterboxing، آن را در مرکز صفحه نمایش یا در صفحه نمایش‌های بزرگ، در یک طرف یا طرف دیگر صفحه نمایش برای دسترسی راحت‌تر قرار می‌دهد. Mattes (نوارهای رنگی ثابت یا تصویر زمینه تار) قسمت‌های استفاده نشده صفحه نمایش را در امتداد کناره‌ها یا بالا و پایین برنامه پر می‌کنند.

لترباکسینگ اغلب در دستگاه‌های صفحه نمایش بزرگ اتفاق می‌افتد، زیرا ابعاد و نسبت ابعاد صفحه نمایش دستگاه معمولاً با تلفن‌های استاندارد که اکثر برنامه‌ها برای آنها طراحی شده‌اند، متفاوت است.

شکل ۱. برنامه محدود به حالت عمودی، در تبلت افقی با حروف بزرگ مشخص شده و قابل تاشو است.

مسئله

برنامه از همه پیکربندی‌های نمایشگر پشتیبانی نمی‌کند زیرا جهت‌گیری، نسبت ابعاد ثابت یا عدم قابلیت تغییر اندازه دارد.

تنظیمات پیکربندی که جهت‌گیری و تغییر اندازه برنامه را کنترل می‌کنند شامل موارد زیر است:

• screenOrientation : یک جهت ثابت برای یک برنامه مشخص می‌کند. برنامه‌ها همچنین می‌توانند جهت را در زمان اجرا با استفاده از Activity#setRequestedOrientation() تنظیم کنند.

• resizeableActivity : نشان می‌دهد که آیا سیستم می‌تواند اندازه برنامه‌ها را برای تناسب با پنجره‌های با ابعاد مختلف تغییر دهد یا خیر. در اندروید ۱۱ (سطح API 30) و پایین‌تر، مشخص می‌کند که آیا برنامه‌ها از حالت چند پنجره‌ای پشتیبانی می‌کنند یا خیر. در اندروید ۱۲ (سطح API 31) و بالاتر، مشخص می‌کند که آیا برنامه‌ها از حالت چند پنجره‌ای در صفحه نمایش‌های کوچک ( کلاس اندازه پنجره فشرده) پشتیبانی می‌کنند یا خیر. در اندروید ۱۲ و بالاتر، برنامه‌ها صرف نظر از این تنظیم، از حالت چند پنجره‌ای در صفحه نمایش‌های بزرگ (کلاس اندازه پنجره متوسط ​​یا گسترده) پشتیبانی می‌کنند.

• maxAspectRatio : حداکثر نسبت ابعاد پشتیبانی شده توسط برنامه را مشخص می‌کند. فقط برنامه‌هایی که resizeableActivity آنها روی false تنظیم شده باشد می‌توانند maxAspectRatio تنظیم کنند.

• minAspectRatio : حداقل نسبت ابعاد پشتیبانی شده توسط برنامه را مشخص می‌کند. فقط برنامه‌هایی که resizeableActivity آنها روی false تنظیم شده باشد می‌توانند minAspectRatio تنظیم کنند.

cancel

برنامه محدود به جهت عمودی است و در دستگاه افقی قابل استفاده نیست.

بهینه‌سازی

برنامه باید از همه جهت‌ها و اندازه‌های نمایش در دستگاه‌ها و حالت چند پنجره‌ای پشتیبانی کند. همه محدودیت‌های جهت‌گیری و نسبت ابعاد ثابت را از طرح‌بندی برنامه و فایل مانیفست برنامه خود حذف کنید.

check_circle

برنامه از همه جهت گیری های دستگاه پشتیبانی می کند.

راه حل سازگاری

اگر برنامه‌ای با جهت یا نسبت تصویر ثابت در پنجره‌ای اجرا شود که برنامه مستقیماً از اندازه یا جهت پنجره پشتیبانی نمی‌کند، اندروید برای حفظ پیوستگی، برنامه را به صورت Letterbox نمایش می‌دهد.

با شروع اندروید ۱۲ (سطح API 31) و ادامه آن با ۱۲L (سطح API 32)، این پلتفرم پیشرفت‌های متنوعی را در برنامه‌های letterboxed اعمال می‌کند. تولیدکنندگان دستگاه، پیشرفت‌های رابط کاربری را پیاده‌سازی می‌کنند. برای بهره‌مندی از این پیشرفت‌ها، نیازی به انجام هیچ توسعه اضافی برای برنامه خود ندارید.

اندروید ۱۲ (سطح API 31) بهبودهای ظاهری زیر را معرفی می‌کند که می‌توانند توسط سازندگان دستگاه پیکربندی شوند:

• گوشه‌های گرد: گوشه‌های پنجره برنامه ظاهری زیباتر دارند.
• شفافیت نوار سیستم: نوارهای وضعیت و ناوبری که برنامه را پوشش می‌دهند، نیمه‌شفاف هستند و باعث می‌شوند آیکون‌های روی نوارها همیشه در پس‌زمینه‌ی کادر حروف قابل مشاهده باشند.
• نسبت ابعاد قابل تنظیم: نسبت ابعاد برنامه را می‌توان برای بهبود ظاهر برنامه تنظیم کرد.

شکل ۲. اپلیکیشن Letterboxed با بهبودهای رابط کاربری.

12L (سطح API 32) بهبودهای عملکردی زیر را اضافه می‌کند:

• موقعیت‌یابی قابل تنظیم: در صفحه نمایش‌های بزرگ، تولیدکنندگان دستگاه می‌توانند برنامه را در سمت چپ یا راست صفحه نمایش قرار دهند و تعامل را آسان‌تر کنند.

• دکمه‌ی راه‌اندازی مجدد با طراحی جدید: تولیدکنندگان دستگاه می‌توانند برای تشخیص بهتر توسط کاربران، به دکمه‌ی راه‌اندازی مجدد برای حالت سازگاری با اندازه، ظاهری جدید بدهند.

اندروید ۱۳ (سطح API ۳۳) یک پنجره آموزش کاربر در مورد قرار دادن برنامه با کادر حروف روی صفحه یا گنجاندن کادر حروف در حالت تقسیم صفحه اضافه می‌کند:

شکل ۳. برنامه Letterboxed با پنجره آموزش کاربر.

حالت سازگاری اندازه

حالت سازگاری اندازه، نوعی جعبه حروف است که نسبت ابعاد برنامه را حفظ می‌کند و شامل یک کنترل راه‌اندازی مجدد است. این کنترل به کاربران امکان می‌دهد برنامه را مجدداً راه‌اندازی کرده و صفحه نمایش را دوباره ترسیم کنند. اندروید حالت سازگاری اندازه را برای برنامه‌هایی که قابل تغییر اندازه نیستند، فراخوانی می‌کند. هنگامی که یک فعالیت به یک ظرف نمایش منتقل می‌شود که با ابعاد فعالیت سازگار نیست، سیستم ممکن است برنامه را مجدداً مقیاس‌بندی کند تا صفحه نمایش دستگاه را حداقل در یک بعد پر کند.

تغییرات پیکربندی دستگاه که می‌توانند حالت سازگاری اندازه را فعال کنند عبارتند از:

• چرخش دستگاه
• دستگاه تاشو، قابلیت تا شدن یا باز شدن
• تغییر بین حالت‌های نمایش تمام صفحه و تقسیم صفحه

مسئله

حالت سازگاری اندازه معمولاً برای فعالیت‌هایی اعمال می‌شود که از نظر جهت‌گیری یا نسبت ابعاد محدود هستند و طوری پیکربندی شده‌اند (یا توسط سیستم تعیین می‌شوند) که قابل تغییر اندازه نباشند.

اگر برنامه شما هر یک از معیارهای زیر را داشته باشد، قابل تغییر اندازه در نظر گرفته می‌شود و در حالت سازگاری با اندازه قرار نمی‌گیرد:

• با resizeableActivity="true" قابل تغییر اندازه است
• پشتیبانی از حالت تصویر در تصویر (PIP)
• تعبیه شده است
• آیا سازنده دستگاه، FORCE_RESIZE_APP برای هر برنامه لغو می‌کند (ویژگی‌های تعیین‌شده توسط برنامه نادیده گرفته می‌شوند)

اگر برنامه شما هیچ یک از شرایط را نداشته باشد ، غیرقابل تغییر اندازه در نظر گرفته می‌شود و می‌تواند در حالت سازگاری اندازه قرار گیرد.

cancel

برنامه‌ای که قابلیت تغییر اندازه ندارد، در حالت چند پنجره‌ای از کار می‌افتد.

بهینه‌سازی

برنامه باید از تمام اندازه‌های نمایشگر پشتیبانی کند. با تنظیم ویژگی android:resizeableActivity از عنصر <activity> یا <application> به true در مانیفست برنامه، اندازه برنامه خود را تغییر دهید. طرح‌بندی‌های واکنش‌گرا/انطباقی برای برنامه خود طراحی کنید. برای اطلاعات بیشتر، به «پشتیبانی از اندازه‌های مختلف نمایشگر» و «پشتیبانی از حالت چند پنجره‌ای» مراجعه کنید.

check_circle

برنامه در تمام اندازه‌های پنجره کار می‌کند.

راه حل سازگاری

اندروید زمانی یک برنامه را در حالت سازگاری با اندازه قرار می‌دهد که سیستم تشخیص دهد نمایش برنامه با کادر حروفی می‌تواند با تغییر مقیاس برنامه برای پر کردن پنجره نمایش حداقل در یک بعد بهبود یابد. سیستم یک کنترل راه‌اندازی مجدد نمایش می‌دهد که فرآیند برنامه را از نو ایجاد می‌کند، فعالیت را دوباره ایجاد می‌کند و نمایش را دوباره ترسیم می‌کند. همچنین به مرور کلی فرآیندها و نخ‌ها مراجعه کنید.

warning

برنامه فقط عمودی در جهت افقی با حروف بزرگ نمایش داده می‌شود و با کنترل راه‌اندازی مجدد، مقیاس آن تغییر می‌کند.

حالت سازگاری نمایش

حالت سازگاری نمایشگر مانع از راه‌اندازی مجدد برنامه هنگام جابجایی برنامه بین نمایشگرهای مختلف می‌شود، که می‌تواند باعث تغییر پیکربندی مانند حالت رنگ ، در دسترس بودن صفحه لمسی یا تغییر تراکم صفحه شود.

حالت سازگاری نمایش (Display compatibility mode) به طور پیش‌فرض برای بازی‌ها (بر اساس پرچم android:appCategory ) فعال است تا پایداری و تداوم را بهبود بخشد. برخلاف حالت سازگاری اندازه، حالت سازگاری نمایش، پیکربندی برنامه را متوقف نمی‌کند. برنامه همچنان می‌تواند تمام به‌روزرسانی‌های پیکربندی را از طریق APIهایی مانند onConfigurationChanged() دریافت کند، اما از راه‌اندازی مجدد مختل‌کننده در امان می‌ماند. این بدان معناست که بازی‌هایی که به درستی از APIهایی مانند onConfigurationChanged() پشتیبانی می‌کنند، حتی اگر در حالت سازگاری نمایش باشند، می‌توانند رابط کاربری خود را به صورت واکنشی به‌روزرسانی کنند.

برای انصراف از حالت سازگاری نمایش و مدیریت تغییرات پیکربندی در برنامه خود، پشتیبانی از تغییرات پیکربندی را در فایل AndroidManifest.xml برنامه اعلام کنید و تغییرات پیکربندی را در فراخوانی onConfigurationChanged() مدیریت کنید.

<activity
    android:name=".MyGameActivity"
    android:configChanges="colorMode|touchscreen|density|...">
    ...
</activity>

حلقه‌های سوسو زننده

وقتی یک برنامه از همه جهت‌های نمایشگر پشتیبانی نمی‌کند، ممکن است هنگام تغییر پیکربندی، بارها و بارها جهت‌های جدید را درخواست کند و یک حلقه بی‌نهایت ایجاد کند که باعث می‌شود نمایشگر چشمک بزند یا برنامه بی‌وقفه بچرخد.

مسئله

در اندروید ۱۲ (سطح API 31) و بالاتر، تولیدکنندگان دستگاه می‌توانند دستگاه‌های خود را طوری پیکربندی کنند که محدودیت‌های جهت‌گیری مشخص‌شده توسط برنامه‌ها را نادیده گرفته و در عوض حالت‌های سازگاری را اعمال کنند. به عنوان مثال، یک دستگاه تاشو می‌تواند تنظیمات android:screenOrientation="portrait" یک فعالیت را هنگامی که فعالیت در صفحه داخلی دستگاه به صورت افقی و با اندازه تبلت نمایش داده می‌شود، نادیده بگیرد.

اگر محدودیت‌های جهت‌گیری یک برنامه نادیده گرفته شود، برنامه می‌تواند با فراخوانی Activity#setRequestedOrientation() به صورت برنامه‌نویسی جهت‌گیری آن را تنظیم کند. این فراخوانی در صورتی که برنامه تغییرات پیکربندی را مدیریت نکند، باعث راه‌اندازی مجدد برنامه می‌شود (به بخش مدیریت تغییرات پیکربندی مراجعه کنید). پس از راه‌اندازی مجدد، محدودیت‌های جهت‌گیری برنامه دوباره نادیده گرفته می‌شوند، برنامه فراخوانی setRequestedOrientation() را تکرار می‌کند، فراخوانی باعث راه‌اندازی مجدد برنامه می‌شود و به همین ترتیب در یک حلقه خود-دائمی ادامه می‌یابد.

یکی دیگر از مواردی که ممکن است با این مشکل مواجه شوید، زمانی است که جهت طبیعی (جهت معمول تعیین شده توسط اندروید) صفحه نمایش دستگاه افقی باشد (یعنی فراخوانی Display#getRotation() Surface.ROTATION_0 را برمی‌گرداند در حالی که دستگاه نسبت ابعاد افقی دارد). از نظر تاریخی، برنامه‌ها فرض کرده‌اند که Display.getRotation() = Surface.ROTATION_0 به این معنی است که دستگاه در جهت عمودی قرار دارد، اما این همیشه صدق نمی‌کند، به عنوان مثال، در صفحه نمایش داخلی برخی از دستگاه‌های تاشو و در برخی تبلت‌ها.

یک برنامه در جهت افقی روی یک صفحه نمایش داخلی تاشو، ممکن است چرخش صفحه را بررسی کند، مقدار ROTATION_0 را دریافت کند، فرض کند جهت طبیعی دستگاه عمودی است و برای پیکربندی مجدد طرح‌بندی برنامه، setRequestedOrientation( ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ) را فراخوانی کند. پس از راه‌اندازی مجدد برنامه (در جهت افقی)، ممکن است دوباره چرخش صفحه را بررسی کند، مقدار ROTATION_0 را دریافت کند، setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) فراخوانی کند و حلقه بی‌نهایت را ادامه دهد.

cancel

برنامه‌ای که فقط در حالت افقی (landscape) نمایش داده می‌شود، در حالت عمودی (portrait) فراخوانی‌های مکرری به Activity#setRequestedOrientation() انجام می‌دهد.

بهینه‌سازی

برنامه‌ها نباید موارد زیر را انجام دهند:

• با استفاده از Activity#setRequestedOrientation() در متد activity onCreate() یک جهت‌گیری پیش‌فرض تنظیم کنید، زیرا درخواست جهت‌گیری می‌تواند به طور غیرمنتظره‌ای توسط تغییرات پیکربندی مدیریت نشده فعال شود.
• فرض کنید جهت طبیعی دستگاه ( ROTATION_0 ) عمودی است.
• جهت‌گیری را بر اساس سیگنال‌هایی که به اندازه پنجره فعلی مرتبط نیستند، مانند Display#getRotation() ، وجود یک FoldingFeature یا APIهای منسوخ‌شده، تنظیم کنید.

check_circle

برنامه تغییر پیکربندی را مدیریت می‌کند، محدودیت جهت‌گیری ندارد، بنابراین وارد حلقه چشمک‌زن نمی‌شود.

راه حل سازگاری

اندروید در شرایط زیر فراخوانی‌های Activity#setRequestedOrientation() را نادیده می‌گیرد:

• این فعالیت از فراخوانی قبلی متد، مجدداً راه‌اندازی شده است یا قابلیت چرخش دوربین با نیروی تطبیق فعال شده است ( پیش‌نمایش دوربین را در زیر ببینید).

  تولیدکنندگان دستگاه می‌توانند این رفتار را با استفاده از OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION در یک برنامه اعمال کنند.

• این فعالیت در یک ثانیه بیش از دو درخواست جهت‌یابی ارسال کرده است، که نشان می‌دهد یک حلقه رخ داده است. از بین دو درخواست در حلقه، اندروید از درخواستی استفاده می‌کند که ناحیه نمایش برنامه را به حداکثر می‌رساند.

  تولیدکنندگان دستگاه می‌توانند این رفتار را با استفاده از OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED در یک برنامه اعمال کنند.

• مالکان دستگاه‌های مجازی، فراخوانی متد را در دستگاه‌های منتخب لغو کرده‌اند.

پیش‌نمایش دوربین

پیش‌نمایش دوربین (یا منظره‌یاب) برنامه‌های دوربین می‌تواند در تبلت‌ها، لپ‌تاپ‌ها و نمایشگرهای تاشو، ناهماهنگ یا تحریف شده باشد.

مسئله

سند تعریف سازگاری اندروید بیان می‌کند که حسگر تصویر دوربین «باید طوری جهت‌گیری شود که بُعد طولی دوربین با بُعد طولی صفحه نمایش هم‌تراز باشد».

برنامه‌ها اغلب فرض می‌کنند که جهت دستگاه و جهت حسگر دوربین عمودی است - فرضی منطقی در تلفن‌های همراه استاندارد. اما جهت طبیعی تبلت‌ها و لپ‌تاپ‌ها و حسگرهای دوربین آنها می‌تواند افقی باشد. همچنین، فرم‌فکتورهای جدید مانند گوشی‌های تاشو می‌توانند چندین جهت طبیعی و چندین حسگر دوربین در جهت‌های مختلف داشته باشند.

شروع یک فعالیت با جهت دوربینی که برنامه انتظار ندارد یا جابجایی بین دوربین‌ها یا صفحه نمایش‌های مختلف دستگاه (برای دستگاه‌های تاشو) می‌تواند باعث عدم تراز یا تحریف پیش‌نمایش دوربین شود.

cancel

پیش‌نمایش دوربین ناهم‌تراز و تحریف‌شده روی صفحه نمایش بزرگ تاشو.

بهینه‌سازی

برنامه‌های دوربین باید جهت دستگاه و جهت حسگر دوربین را به درستی شناسایی و مدیریت کنند تا پیش‌نمایش دوربین به درستی تراز و مقیاس‌بندی شده ارائه شود. برنامه‌ها باید چرخش دستگاه، چرخش حسگر و نسبت ابعاد صفحه یا پنجره را محاسبه کنند و سپس نتایج را در پیش‌نمایش دوربین اعمال کنند. برای راهنمایی دقیق، به پیش‌نمایش دوربین و معرفی منظره‌یاب دوربین مراجعه کنید.

check_circle

پیش‌نمایش دوربین به درستی در تمام جهت‌های دستگاه تراز و مقیاس‌بندی شده است.

راه حل سازگاری

یک دستگاه در جهت طبیعی خود قرار دارد وقتی که Display#getRotation() Surface.ROTATION_0 را برمی‌گرداند. سیستم CameraCharacteristics.SENSOR_ORIENTATION از جهت طبیعی دستگاه محاسبه می‌کند. اندروید پنجره عمودی برنامه‌های دارای محدودیت نمایش عمودی را با جهت طبیعی دستگاه تراز می‌کند، که همان چیزی است که اکثر برنامه‌ها انتظار دارند. اندروید همچنین تصویر حسگر دوربین را وقتی جهت حسگر افقی است و پیش‌نمایش دوربین عمودی است، برش می‌دهد. راه‌حل‌های خاص شامل موارد زیر است:

• پیش‌نمایش دوربین را برای برنامه‌های دارای محدودیت عمودی، به صورت اجباری بچرخانید: برنامه‌هایی که به جهت عمودی محدود شده‌اند، انتظار دارند جهت طبیعی دستگاه و جهت حسگر دوربین نیز عمودی باشد. با این حال، در اندروید ۱۲ (سطح API ۳۱) و بالاتر، اگر تولیدکنندگان دستگاه، مشخصات جهت‌گیری را نادیده بگیرند، برنامه‌ها می‌توانند در چندین جهت دستگاه اجرا شوند.

  وقتی یک برنامه با قابلیت نمایش عمودی به دوربین متصل می‌شود، اندروید برنامه را به زور می‌چرخاند تا پنجره عمودی برنامه با جهت طبیعی دستگاه تراز شود.

  در برخی تبلت‌ها (به دستگاه‌های مرجع مراجعه کنید)، پنجره عمودی برنامه به حالت تمام صفحه چرخانده می‌شود تا با جهت طبیعی دستگاه هماهنگ شود. برنامه پس از چرخش اجباری، تمام صفحه را اشغال می‌کند.

  

  warning

  تبلت — چرخش اجباری برنامه با محدودیت نمایش عمودی.

  در صفحه داخلی افقی دستگاه‌های تاشو (به دستگاه‌های مرجع مراجعه کنید)، فعالیت‌های فقط عمودی به حالت افقی چرخانده می‌شوند تا با جهت طبیعی باز شده هم‌تراز شوند. برنامه پس از چرخش اجباری، با حروف بزرگ مشخص می‌شود.

  

  warning

  تاشو - چرخش اجباری برنامه با محدودیت نمایش عمودی. برنامه همچنین دارای کادر حروف است.

• برش دوربین جلوی داخلی: سنسور دوربین جلوی داخلی در برخی از گوشی‌های تاشو در جهت افقی قرار دارد. علاوه بر چرخاندن اجباری پیش‌نمایش دوربین روی صفحه نمایش داخلی تاشو، اندروید میدان دید دوربین جلوی داخلی (افقی) را برش می‌دهد تا سنسور، نمایی خلاف جهت دستگاه را ثبت کند.

• به‌روزرسانی اجباری پیش‌نمایش دوربین: سیستم پس از چرخش اجباری، برای اطمینان از نمایش صحیح پیش‌نمایش دوربین، بین متدهای فعالیت onStop() و onStart() (به‌طور پیش‌فرض) یا onPause() و onResume() (که توسط override OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE برای هر برنامه اعمال می‌شود) می‌چرخد.

• مقیاس‌بندی نسبت ابعاد: سیستم به صورت پویا نسبت ابعاد پیش‌نمایش دوربین چرخانده شده با نیرو را به حداقل نسبت ابعاد بالاتر تغییر می‌دهد، که تضمین می‌کند پیش‌نمایش دوربین به درستی مقیاس‌بندی شده است.

توسعه‌دهندگان برنامه می‌توانند این راه‌حل‌های جایگزین را لغو کنند، اگر برنامه‌ها پیش‌نمایش دوربین را به درستی مدیریت کنند. به لغوهای هر برنامه مراجعه کنید.

API های رایج مورد سوءاستفاده

از آنجایی که اندروید پشتیبانی از ویژگی‌هایی مانند حالت چند پنجره‌ای و دستگاه‌هایی مانند گوشی‌های تاشو را اضافه کرده است، APIهای قدیمی منسوخ شده و با APIهای به‌روز جایگزین شده‌اند که برای همه اندازه‌های نمایشگر و فرم فکتورهای دستگاه کار می‌کنند. با این حال، APIهای منسوخ شده هنوز برای سازگاری با نسخه‌های قبلی در دسترس هستند.

برخی از رابط‌های View (API) برای اهداف خاصی طراحی شده‌اند که همیشه توسط توسعه‌دهندگان به خوبی درک نمی‌شوند.

مسئله

توسعه‌دهندگان همچنان از APIهای Display منسوخ‌شده استفاده می‌کنند و به اشتباه فرض می‌کنند که APIها به جای محدوده‌های ناحیه نمایش دستگاه، محدوده‌های برنامه را برمی‌گردانند. یا توسعه‌دهندگان به اشتباه از APIهای نمای خاص‌منظوره برای دریافت معیارهای نمایش عمومی استفاده می‌کنند. نتیجه، محاسبات اشتباه هنگام تغییر موقعیت عناصر رابط کاربری پس از رویدادهای تغییر اندازه پنجره برنامه است که باعث ایجاد مشکلات طرح‌بندی می‌شود.

API های نمایش منسوخ شده و معمولاً مورد سوء استفاده قرار می گیرند:

• getMetrics()
• getSize()
• getRealMetrics()
• getRealSize()
• getRectSize()
• getWidth()
• getHeight()

برای اطلاعات بیشتر، به پشتیبانی از حالت چند پنجره‌ای مراجعه کنید.

سوءاستفاده از APIهای view:

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

cancel

API منسوخ‌شده، محدوده‌های برنامه را اشتباه محاسبه می‌کند. محتوای برنامه از صفحه نمایش خارج می‌شود.

بهینه‌سازی

هرگز برای موقعیت‌یابی عناصر رابط کاربری به اندازه فیزیکی نمایشگر تکیه نکنید. برنامه خود را به APIهای مبتنی بر WindowMetrics ، از جمله APIهای WindowManager زیر، منتقل کنید:

• پلتفرم:

  • getCurrentWindowMetrics()
  • getMaximumWindowMetrics()

• جت‌پک:

  • WindowMetricsCalculator#computeCurrentWindowMetrics()

  • WindowMetricsCalculator#computeMaximumWindowMetrics()

check_circle

API به درستی معیارهای پنجره برنامه را محاسبه می‌کند.

راه حل سازگاری

دو override، APIهای منسوخ‌شده‌ی Display و APIهای سوءاستفاده‌شده‌ی View را برای بازگرداندن محدوده‌های برنامه تنظیم می‌کنند: ALWAYS_SANDBOX_DISPLAY_APIS برای APIهای Display ؛ OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS برای APIهای View . ALWAYS_SANDBOX_DISPLAY_APIS همچنین به‌طور پیش‌فرض برای برنامه‌هایی که واجد شرایط حالت سازگاری اندازه هستند، اعمال می‌شود.

فعالیت‌های شفاف

فعالیت‌های شفاف نتیجه‌ی سبک‌های پس‌زمینه‌ی شفاف هستند، برای مثال:

<style name="Transparent" parent="AppTheme">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
</style>

تم‌های مربوط به دیالوگ‌ها، مانند Theme.MaterialComponents.Dialog ، می‌توانند شامل سبک‌هایی باشند که فعالیت‌ها را شفاف می‌کنند.

فعالیت‌های شفاف تمام فضای نمایش موجود را پوشش نمی‌دهند، که مدیریت آنها را دشوار می‌کند زیرا فضای نمایش موجود می‌تواند بر اساس تغییرات پیکربندی مانند چرخش دستگاه، تاشو و باز شدن دستگاه و حالت چند پنجره‌ای تغییر کند.

مسئله

یک فعالیت شفاف باید با مرزهای اولین فعالیت مات زیر فعالیت شفاف در پشته فعالیت وظیفه مطابقت داشته باشد. با این حال، یک فعالیت مات که یک کادر محاوره‌ای مجوز را راه‌اندازی می‌کند می‌تواند یک ترامپولین باشد (فعالیتی که فعالیت دیگری را راه‌اندازی می‌کند و سپس ناپدید می‌شود)؛ و بنابراین، سیستم نمی‌تواند مرزهای فعالیت ترامپولینی را که فعالیت محاوره‌ای مجوز شفاف را راه‌اندازی کرده است، تعیین کند.

cancel

دیالوگ به دلیل شروع فعالیت از روی ترامپولین، اشتباه تنظیم شده بود.

بهینه‌سازی

فعالیت‌های شفاف محدودیت‌های خود را از بالاترین فعالیت مات زیر خود در پشته فعالیت یک وظیفه به ارث می‌برند. فعالیت مات باید در کل چرخه حیات فعالیت شفاف، از ایجاد فعالیت تا تخریب، در دسترس باشد. به همین دلیل، درخواست‌های مجوز را از فعالیت‌های ترامپولینی اجرا نکنید.

اگر یک اکتیویتی ترامپولین درخواست مجوزی را اجرا کند، ممکن است کاربر نتواند دیالوگ مجوز را ببیند، زیرا اکتیویتی ترامپولین قبل از اینکه کاربر فرصتی برای پاسخ به دیالوگ داشته باشد، از بین رفته است و ممکن است ابعاد و موقعیت اکتیویتی دیالوگ به اشتباه محاسبه شده باشد.

برنامه‌ها همیشه باید درخواست‌های مجوز را از فعالیت‌هایی که تا زمان تصمیم‌گیری کاربر برای مجوز، قابل مشاهده باقی می‌مانند، ارسال کنند.

گوشه‌های گرد

یک فعالیت می‌تواند به دلیل سبکی که شفافیت پس‌زمینه را مشخص می‌کند یا به دلیل اینکه محتویات فعالیت فضای نمایش موجود را پر نمی‌کند، شفاف باشد. اگر یک فعالیت شفاف فضای نمایش موجود را پر کند، سیستم به طور خودکار گوشه‌های گرد را در فعالیت اعمال می‌کند، زمانی که توسط سازنده دستگاه پیکربندی شده باشد. اما، اگر یک فعالیت شفاف (مانند یک کادر محاوره‌ای مجوز) فضای موجود را پر نکند، تصمیم گیری در مورد اعمال یا عدم اعمال گوشه‌های گرد به شما بستگی دارد.

دیالوگ‌های مجوز فضای نمایش موجود را پر نمی‌کنند، زیرا طرح‌بندی دیالوگ معمولاً از LayoutParams.WRAP_CONTENT به جای LayoutParams.MATCH_PARENT استفاده می‌کند.

check_circle

دیالوگ با گوشه‌های گرد که به درستی روی فعالیت پرتاب قابل مشاهده قرار گرفته است.

راه حل سازگاری

فعالیت‌هایی که دیالوگ را اجرا می‌کنند، تا زمانی که کاربر به دیالوگ پاسخ نداده است، قابل مشاهده نگه دارید.

این سیستم تضمین می‌کند که یک فعالیت شفاف، تمام محدودیت‌های اولین فعالیت مات زیر فعالیت شفاف در پشته فعالیت را به ارث می‌برد، از جمله محدودیت‌های مربوط به:

• حالت سازگاری اندازه
• جهت گیری
• نسبت ابعاد

بازی‌های یونیتی

بازی‌های یونیتی در اندروید به صورت تمام صفحه یا در حالت چند پنجره‌ای اجرا می‌شوند. با این حال، بسیاری از بازی‌های یونیتی وقتی برنامه در حالت چند پنجره‌ای قرار می‌گیرد، تمرکز خود را از دست می‌دهند و ترسیم محتوا متوقف می‌شود.

مسئله

یونیتی در نسخه ۲۰۱۹.۴ خود، گزینه Resizable Window را برای پشتیبانی از حالت چند پنجره‌ای در اندروید اضافه کرد. با این حال، پیاده‌سازی اولیه به درستی به چرخه حیات فعالیت در حالت چند پنجره‌ای واکنش نشان نمی‌داد و باعث می‌شد UnityPlayer هنگام از دست دادن فوکوس برنامه، پخش را متوقف کند. پخش‌کننده یک صفحه سیاه یا آخرین فریم یخ‌زده بازی را رندر می‌کرد. گیم‌پلی فقط زمانی از سر گرفته می‌شد که کاربر روی صفحه ضربه می‌زد. بسیاری از برنامه‌هایی که از موتور یونیتی استفاده می‌کنند با این مشکل مواجه هستند و در حالت چند پنجره‌ای به صورت یک پنجره سیاه رندر می‌شوند.

cancel

بازی در حالت چند پنجره‌ای فوکوس را از دست می‌دهد و به صورت یک پنجره سیاه نمایش داده می‌شود.

بهینه‌سازی

یونیتی را به نسخه ۲۰۱۹.۴.۴۰ یا بالاتر ارتقا دهید و بازی خود را دوباره اکسپورت کنید. گزینه Resizable Window را در تنظیمات Android Player تیک بزنید، در غیر این صورت بازی وقتی در حالت چند پنجره‌ای نباشد، متوقف می‌شود، حتی اگر بازی کاملاً قابل مشاهده باشد.

check_circle

بازی در حالت چند پنجره‌ای، حتی زمانی که فوکوس روی صفحه نیست، محتوا را به درستی رندر می‌کند.

راه حل سازگاری

تولیدکنندگان دستگاه می‌توانند از OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS برای هر برنامه استفاده کنند تا یک رویداد فوکوس جعلی برای یک برنامه در حالت چند پنجره‌ای ارائه دهند. این override به activity اجازه می‌دهد تا محتوا را دوباره ترسیم کند و از سیاه شدن جلوگیری شود.

پنجره‌بندی دسکتاپ

وقتی برنامه‌ها در یک محیط پنجره‌ای دسکتاپ اجرا می‌شوند، ممکن است با حالت‌های سازگاری بیشتری مواجه شوند.

برنامه‌هایی که جهت‌گیری قفل‌شده دارند، آزادانه قابل تغییر اندازه هستند. حتی اگر یک فعالیت روی جهت‌گیری عمودی قفل شده باشد، کاربران همچنان می‌توانند اندازه برنامه را به جهت‌گیری افقی تغییر دهند.

check_circle

برنامه‌هایی که جهت‌گیری قفل‌شده دارند، همچنان می‌توانند آزادانه تغییر اندازه دهند.

با این حال، اگر یک فعالیت به عنوان غیرقابل تغییر اندازه تعریف شود ( resizeableActivity = false )، رابط کاربری فعالیت با حفظ نسبت ابعاد یکسان، تغییر اندازه می‌دهد.

check_circle

فعالیت‌هایی که به عنوان غیرقابل تغییر اندازه اعلام شده‌اند، رابط کاربری‌شان مقیاس‌پذیر می‌شود.

پیش‌نمایش دوربین در پنجره دسکتاپ

وقتی برنامه‌ها در پنجره دسکتاپ پیش‌نمایش دوربین را شروع می‌کنند، رابط کاربری منظره‌یاب با حفظ نسبت ابعاد اصلی، کوچک و بزرگ می‌شود. بقیه‌ی پنجره‌ی برنامه را می‌توان آزادانه تغییر اندازه داد.

check_circle

تغییر اندازه پنجره با استفاده از منظره یاب دوربین

برنامه خود را برای مشکلات سازگاری آزمایش کنید

برای آزمایش برنامه خود و درک نحوه رفتار آن در فرم فاکتورهای مختلف، از منابع زیر استفاده کنید:

• پخش جریانی دستگاه: برای آزمایش برنامه خود روی دستگاه‌های تولیدی (از جمله دستگاه‌های مرجع ) که در مراکز داده گوگل میزبانی می‌شوند، به پخش جریانی دستگاه اندروید، ارائه شده توسط Firebase مراجعه کنید.
• شبیه‌سازها در اندروید استودیو: برای اطلاعات بیشتر در مورد ایجاد شبیه‌ساز برای دستگاه‌های مرجع، به بخش ایجاد و مدیریت دستگاه‌های مجازی مراجعه کنید.
• شبیه‌ساز اندروید استودیو با قابلیت تغییر اندازه: برای اطلاعات بیشتر در مورد دسترسی به دستگاه‌های مجازی، به بخش اجرای برنامه‌ها در شبیه‌ساز اندروید مراجعه کنید.

با حروف بزرگ نوشته شده است

تأیید کنید که هر فعالیت می‌تواند از تمام فضای نمایش موجود برای برنامه استفاده کند. ابتدا، کد زیر را در پوشه test خود اعلان کنید:

fun isLetterboxed(activity: AppCompatActivity): Boolean {
    if (isInMultiWindowMode) return false

    val wmc = WindowMetricsCalculator.getOrCreate()
    val currentBounds = wmc.computeCurrentWindowMetrics(this).bounds
    val maxBounds = wmc.computeMaximumWindowMetrics(this).bounds

    val isScreenPortrait = maxBounds.height() > maxBounds.width()

    return if (isScreenPortrait) {
        currentBounds.height() < maxBounds.height()
    } else {
        currentBounds.width() < maxBounds.width()
    }
}
DeviceCompatibilityModeKotlinSnippets.kt

public boolean isLetterboxed(AppCompatActivity activity) {
    if (activity.isInMultiWindowMode()) {
        return false;
    }

    WindowMetricsCalculator wmc = WindowMetricsCalculator.getOrCreate();
    Rect currentBounds = wmc.computeCurrentWindowMetrics(activity).getBounds();
    Rect maxBounds = wmc.computeMaximumWindowMetrics(activity).getBounds();

    boolean isScreenPortrait = maxBounds.height() > maxBounds.width();

    return (isScreenPortrait)
        ? currentBounds.height() < maxBounds.height()
        : currentBounds.width() < maxBounds.width();
}
DeviceCompatibilityModeJavaSnippets.java

سپس یک تست اجرا کنید تا رفتار را تأیید کنید و مطمئن شوید که فعالیت هدف با حروف بزرگ مشخص نشده است:

@get:Rule
val activityRule = ActivityScenarioRule(MainActivity::class.java)

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertFalse(it.isLetterboxed())
    }
}
DeviceCompatibilityModeTestKotlinSnippets.kt

@Rule
public ActivityScenarioRule<MainActivity> rule = new ActivityScenarioRule<>(MainActivity.class);

@Test
public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario =
        ActivityScenario.launch(MainActivity.class)) {
            scenario.onActivity( activity -> {
                assertFalse(activity.isLetterboxed());
            });
        }
}
DeviceCompatibilityModeTestJavaSnippets.java

در حالت ایده‌آل، این نوع تست را فقط تا زمانی که با موفقیت پشت سر گذاشته شود و تأیید کند که فعالیت‌های برنامه شما کل فضای نمایش موجود برای برنامه را اشغال کرده‌اند، اجرا کنید. برنامه خود را روی انواع دستگاه‌ها آزمایش کنید تا از رفتار سازگار آن اطمینان حاصل کنید.

لغوهای هر برنامه

اندروید overrideهایی را ارائه می‌دهد که رفتار پیکربندی‌شده‌ی برنامه‌ها را تغییر می‌دهند. برای مثال، override مربوط FORCE_RESIZE_APP به سیستم دستور می‌دهد که از حالت سازگاری اندازه عبور کند و اندازه‌ی برنامه را تغییر دهد تا با ابعاد نمایش متناسب شود، حتی اگر resizeableActivity="false" در manifest برنامه مشخص شده باشد.

تولیدکنندگان دستگاه، لغو تنظیمات را برای برنامه‌های منتخب - یا همه برنامه‌ها - در دستگاه‌های صفحه نمایش بزرگ خاص اعمال می‌کنند. در اندروید ۱۴ (سطح API ۳۴) و بالاتر، کاربران می‌توانند از طریق تنظیمات دستگاه، لغو تنظیمات را برای برنامه‌ها اعمال کنند. در اندروید ۱۶ (سطح API ۳۶) و بالاتر، مالکان دستگاه‌های مجازی، لغو تنظیمات را روی دستگاه‌های منتخبی که مالکان دستگاه‌های مجازی مدیریت می‌کنند، اعمال می‌کنند.

کاربر به ازای هر برنامه، لغو می‌کند

در اندروید ۱۴ و بالاتر، یک منوی تنظیمات به کاربران امکان می‌دهد نسبت ابعاد برنامه‌ها را تغییر دهند. دستگاه‌های صفحه نمایش بزرگ مانند دستگاه‌های مرجع، این منو را پیاده‌سازی می‌کنند.

این منو شامل لیستی از تمام برنامه‌های نصب شده روی دستگاه است. کاربران یک برنامه را انتخاب می‌کنند و سپس نسبت تصویر برنامه را روی ۳:۴، ۱:۱، تمام صفحه یا مقادیر دیگری که توسط سازنده دستگاه پیکربندی شده است، تنظیم می‌کنند. کاربران همچنین می‌توانند نسبت تصویر را به پیش‌فرض برنامه که در مانیفست برنامه مشخص شده است، بازنشانی کنند.

برنامه‌ها می‌توانند با تنظیم تگ‌های PackageManager.Property زیر، از لغو سازگاری انصراف دهند:

• سازگاری ویژگی‌ها (PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE)

  برای لغو سازگاری نسبت ابعاد کاربر، این ویژگی را به مانیفست برنامه خود اضافه کنید و مقدار آن را false قرار دهید:

  <application>
      <property
          android:name="android.window.
          PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE"
          android:value="false" />
  </application>
  

  برنامه شما از فهرست برنامه‌ها در تنظیمات دستگاه حذف خواهد شد. کاربران نمی‌توانند نسبت ابعاد برنامه را تغییر دهند.

  تنظیم ویژگی روی true هیچ تاثیری ندارد.

• سازگاری ویژگی‌ها (PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE)

  برای غیرفعال کردن گزینه تمام صفحه در مورد لغو سازگاری نسبت ابعاد کاربر، این ویژگی را به مانیفست برنامه خود اضافه کنید و مقدار آن را false قرار دهید:

  <application>
      <property
          android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE"
          android:value="false" />
  </application>
  

  گزینه تمام صفحه از فهرست گزینه‌های نسبت تصویر در تنظیمات دستگاه حذف شده است. کاربران نمی‌توانند لغو حالت تمام صفحه را در برنامه شما اعمال کنند.

  تنظیم این ویژگی روی true هیچ تاثیری ندارد.

برنامه خود را برای همه صفحه نمایش‌ها بهینه کنید: در برنامه خود محدودیت نسبت ابعاد تعیین نکنید. از کلاس‌های اندازه پنجره برای پشتیبانی از طرح‌بندی‌های مختلف بر اساس میزان فضای نمایش موجود استفاده کنید.

لغو تنظیمات دستگاه به ازای هر برنامه

تولیدکنندگان دستگاه و مالکان دستگاه‌های مجازی (برنامه‌های مورد اعتماد و ممتاز منتخب) بر اساس هر برنامه، روی دستگاه‌های خاص، از جمله تبلت‌ها، دستگاه‌های تاشو، دستگاه‌های ChromeOS و نمایشگرهای خودرو، لغوهایی را اعمال می‌کنند. دستگاه‌های مرجع ممکن است برخی از لغوها را به‌طور پیش‌فرض روی انواع برنامه‌ها اعمال کنند.

برنامه‌ها می‌توانند از اکثر لغوها انصراف دهند (به جدول لغوهای هر برنامه در زیر مراجعه کنید).

شما می‌توانید برنامه خود را با فعال یا غیرفعال کردن overrideها با استفاده از چارچوب سازگاری (به ابزارهای چارچوب سازگاری مراجعه کنید) آزمایش کنید. وقتی فعال باشند، overrideها به کل برنامه اعمال می‌شوند.

همچنین می‌توانید از Android Debug Bridge (adb) برای فعال یا غیرفعال کردن overrideها استفاده کنید و تعیین کنید که کدام overrideها برای برنامه شما اعمال می‌شوند.

فعال یا غیرفعال کردن لغوها به شرح زیر است:

adb shell am compat enable/disable <override name/id> <package>

برای دستگاه‌های مرجع ، بررسی کنید که کدام overrideها برای برنامه شما اعمال می‌شوند:

adb shell dumpsys platform_compat | grep <package name>

جدول زیر فهرستی از override های موجود به همراه راهنمایی در مورد نحوه بهینه‌سازی برنامه شما را نشان می‌دهد تا برنامه نیازی به تکیه بر override ها نداشته باشد. می‌توانید پرچم‌های ویژگی را به مانیفست برنامه خود اضافه کنید تا از برخی override ها صرف نظر کنید.

FORCE_RESIZE_APP

Forces the packages to which the override is applied to be resizable and able to enter multi‑window mode. Applies to all displays sizes.

How apps can achieve same result as override

In the app manifest, set the android:resizeableActivity attribute to true .

How to optimize apps

Use responsive/adaptive layouts to enable apps to adapt to all display sizes and aspect ratios. See Support different display sizes .

How to disable or opt out of override

Set the property flag PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

adb commands to test override

To apply the override and make app resizable:

adb shell am compat enable FORCE_RESIZE_APP <package>

To remove the override:

adb shell am compat disable FORCE_RESIZE_APP <package>

Note: The commands only temporarily apply or remove the override.

FORCE_NON_RESIZE_APP

Forces the packages to which the override is applied to be nonresizable and enter size compatibility mode on configuration changes. Applies to all display sizes.

How apps can achieve same result as override

Set both the android:resizeableActivity attribute and android.supports_size_changes metadata flag to false in the app manifest, and declare either an orientation or aspect ratio restriction.

How to optimize apps

All apps that behave well if resized should either have android:resizeableActivity or android.supports_size_changes set to true . Other apps should be improved to behave well when resized. See android:resizeableActivity .

How to disable or opt out of override

Set the property flag PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

adb commands to test override

To apply the override and make app nonresizable:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

To remove the override:

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO

The gatekeeper for all overrides that force a given minimum aspect ratio.

How apps can achieve same result as override

Set android:minAspectRatio at the activity or app level.

How to optimize apps

Don't set aspect ratio restrictions in your app. Make sure your app supports different display sizes . Use window size classes to support different layouts based on the amount of space your app has on the screen. See the Compose WindowSizeClass API and View WindowSizeClass API .

How to disable or opt out of override

Specify an aspect ratio restriction or set the property flag PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE"
  android:value="false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Restricts app settings that force a given minimum aspect ratio for activities with portrait‑only orientation. Enabled by default and only takes effect if OVERRIDE_MIN_ASPECT_RATIO is also enabled.

How apps can achieve same result as override

See OVERRIDE_MIN_ASPECT_RATIO .

How to optimize apps

See OVERRIDE_MIN_ASPECT_RATIO .

How to disable or opt out of override

See OVERRIDE_MIN_ASPECT_RATIO .

Property flags to adjust override

See OVERRIDE_MIN_ASPECT_RATIO .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO_SMALL

Sets the activity's minimum aspect ratio to a small value (4:3).

How apps can achieve same result as override

See OVERRIDE_MIN_ASPECT_RATIO .

How to optimize apps

See OVERRIDE_MIN_ASPECT_RATIO .

How to disable or opt out of override

See OVERRIDE_MIN_ASPECT_RATIO .

Property flags to adjust override

See OVERRIDE_MIN_ASPECT_RATIO .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

Sets the activity's minimum aspect ratio to a medium value (3:2).

How apps can achieve same result as override

See OVERRIDE_MIN_ASPECT_RATIO .

How to optimize apps

See OVERRIDE_MIN_ASPECT_RATIO .

How to disable or opt out of override

See OVERRIDE_MIN_ASPECT_RATIO .

Property flags to adjust override

See OVERRIDE_MIN_ASPECT_RATIO .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

Sets the activity's minimum aspect ratio to a large value (16:9).

How apps can achieve same result as override

See OVERRIDE_MIN_ASPECT_RATIO .

How to optimize apps

See OVERRIDE_MIN_ASPECT_RATIO .

How to disable or opt out of override

See OVERRIDE_MIN_ASPECT_RATIO .

Property flags to adjust override

See OVERRIDE_MIN_ASPECT_RATIO .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

Enables the use of split-screen aspect ratio. Allows an app to use all the available space in split-screen mode, avoiding letterboxing.

How apps can achieve same result as override

See OVERRIDE_MIN_ASPECT_RATIO .

How to optimize apps

See OVERRIDE_MIN_ASPECT_RATIO .

How to disable or opt out of override

See OVERRIDE_MIN_ASPECT_RATIO .

Property flags to adjust override

See OVERRIDE_MIN_ASPECT_RATIO .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

Disables the minimum aspect ratio override in portrait full screen to use all available screen space.

How apps can achieve same result as override

See OVERRIDE_MIN_ASPECT_RATIO .

How to optimize apps

See OVERRIDE_MIN_ASPECT_RATIO .

How to disable or opt out of override

See OVERRIDE_MIN_ASPECT_RATIO .

Property flags to adjust override

See OVERRIDE_MIN_ASPECT_RATIO .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

To remove the override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_ANY_ORIENTATION

Enables the following overrides to override any orientation:

• OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
• OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
• OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

How apps can achieve same result as override

Set the activity:screenOrientation manifest attribute, or use the Activity#setRequestedOrientation() API.

How to optimize apps

Your app should support all orientations. An orientation change is a configuration change, which can be handled either of two ways: letting the system destroy and recreate the app, or managing the configuration changes yourself. If you manage configuration changes yourself, the app state can be retained by using ViewModel . In very limited cases, you can decide to lock the orientation on small displays only, although doing so might not scale as well as letting the user rotate the app as needed. On Android 12L and higher versions, fixed orientation can be overridden by device configuration. For more information about handling configuration changes and supporting all orientations, see Handle configuration changes , ViewModel overview , and App orientation restricted on phones but not on large screen devices .

How to disable or opt out of override

Set the property flag PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

To remove the override:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_ANY_ORIENTATION_TO_USER

Enables app to fill the available display space. Overrides any orientation, resizability, and aspect ratio restrictions specified in the app manifest. Also ignores any calls to Activity#setRequestedOrientation() or Activity#getRequestedOrientation() .

How apps can achieve same result as override

• Do not set the android:screenOrientation manifest attribute, or set the attribute to "user" .

• Set the android:resizeableActivity manifest attribute to true .

• On small screens, to support app resizing while disabling multi‑window mode with android:resizeableActivity=false , set the android.supports_size_changes metadata flag to true . Do not set minAspectRatio and maxAspectRatio .

How to optimize apps

Enable your app to support all orientations; don't set a screenOrientation specification in your app's manifest. Support app resizability, multi‑window mode, and all display aspect ratios by setting the android:resizeableActivity attribute in your app's manifest to true . See Support different display sizes .

How to disable or opt out of override

See OVERRIDE_ANY_ORIENTATION .

Property flags to adjust override

See OVERRIDE_ANY_ORIENTATION .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION_TO_USER <package>

To remove the override:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION_TO_USER <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT

Enables portrait orientation for all activities in the package. Unless OVERRIDE_ANY_ORIENTATION is enabled, the override is used only when no other fixed orientation has been specified by the activity.

How apps can achieve same result as override

See OVERRIDE_ANY_ORIENTATION .

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

See OVERRIDE_ANY_ORIENTATION .

Property flags to adjust override

See OVERRIDE_ANY_ORIENTATION .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

To remove the override:

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR

Enables nosensor orientation for all activities in the package. Unless OVERRIDE_ANY_ORIENTATION is enabled, the override is used only when no other fixed orientation has been specified by the activity.

How apps can achieve same result as override

See OVERRIDE_ANY_ORIENTATION .

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

See OVERRIDE_ANY_ORIENTATION .

Property flags to adjust override

See OVERRIDE_ANY_ORIENTATION .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

To remove the override:

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

Enables reverseLandscape orientation for all activities in the package. Unless OVERRIDE_ANY_ORIENTATION is enabled, the override is used only when no other fixed orientation has been specified by the activity.

How apps can achieve same result as override

See OVERRIDE_ANY_ORIENTATION .

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

See OVERRIDE_ANY_ORIENTATION .

Property flags to adjust override

See OVERRIDE_ANY_ORIENTATION .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

To remove the override:

adb shell am compat disable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA

Limits OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT , OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR , and OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE overrides to take effect only when camera connection is active.

How apps can achieve same result as override

See OVERRIDE_ANY_ORIENTATION .

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

See OVERRIDE_ANY_ORIENTATION .

Property flags to adjust override

See OVERRIDE_ANY_ORIENTATION .

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

To remove the override:

adb shell am compat disable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION

Restricts display orientation to landscape natural orientation when the following conditions are met:

• Activity is full screen
• Opt out component property PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE isn't enabled
• Device manufacturer ignore orientation request setting is enabled for the display
• Natural orientation of the display is landscape

How apps can achieve same result as override

Not applicable. The problem should be solved in the application logic.

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

Set the property flag PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

To remove the override:

adb shell am compat disable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION

Enables compat policy that skips updating app orientation in response to app calling Activity#setRequestedOrientation() when app is relaunching or has an active camera compat treatment.

How apps can achieve same result as override

Set property flag PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION to true .

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

Set property flag PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION"
  android:value="true|false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

To remove the override:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED

Enables the compatibility policy that ignores an app's requested orientation in response to the app calling Activity#setRequestedOrientation() more than twice in one second if an activity is not letterboxed for fixed orientation.

How apps can achieve same result as override

Not applicable. The problem should be solved in the application logic.

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

Set property flag PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED"
  android:value="false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

To remove the override:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_RESPECT_REQUESTED_ORIENTATION

Excludes packages from ignore orientation request behavior that can be enabled by device manufacturers for a display area or the whole display.

How apps can achieve same result as override

Not applicable. The problem should be solved in the application logic.

How to optimize apps

See OVERRIDE_ANY_ORIENTATION .

How to disable or opt out of override

No opt-out. Disabling the override can be dangerous if the app is not compatible with a device that has the device manufacturer ignore orientation request setting enabled. Contact Android Developer Relations to disable the override.

Property flags to adjust override

No property flags for this override.

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

To remove the override:

adb shell am compat disable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

Note: The commands only temporarily apply or remove the override.

NEVER_SANDBOX_DISPLAY_APIS

Forces packages to never have Display API sandboxing applied for a letterboxed or size compatibility mode activity. The Display APIs continue to provide display area bounds.

How apps can achieve same result as override

Declare activities resizable by either setting the android:resizeableActivity manifest attribute to true or the android.supports_size_changes metadata flag to true .

How to optimize apps

Apps that declare they are fully resizable should never rely upon display size to position UI elements. Migrate your app to up‑to‑date APIs that provide WindowMetrics . If you are using Jetpack Compose, take advantage of the WindowSizeClass API to draw the UI based on how much screen area the app has on the current display. See Use window size classes .

How to disable or opt out of override

No opt-out. Migrate from deprecated APIs.

Property flags to adjust override

No property flags for this override.

adb commands to test override

To apply the override:

adb shell am compat enable NEVER_SANDBOX_DISPLAY_APIS <package>

To remove the override:

adb shell am compat disable NEVER_SANDBOX_DISPLAY_APIS <package>

Note: The commands only temporarily apply or remove the override.

ALWAYS_SANDBOX_DISPLAY_APIS

Forces packages to always have Display API sandboxing applied regardless of windowing mode. The Display APIs always provide the app bounds.

How apps can achieve same result as override

Declare activities nonresizable by either setting the android:resizeableActivity attribute to false or the android.supports_size_changes metadata flag to false .

How to optimize apps

Apps that declare they are fully resizable should never rely on display size to position UI elements. Migrate your app from deprecated APIs to up‑to‑date APIs that provide WindowMetrics . See WindowMetricsCalculator .

How to disable or opt out of override

No opt-out. Migrate from deprecated APIs.

Property flags to adjust override

No property flags for this override.

adb commands to test override

To apply the override:

adb shell am compat enable ALWAYS_SANDBOX_DISPLAY_APIS <package>

To remove the override:

adb shell am compat disable ALWAYS_SANDBOX_DISPLAY_APIS <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS

Forces packages to sandbox the following View APIs to activity bounds:

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

How apps can achieve same result as override

Resolve the issue in application code by using APIs that provide the bounds of the app window and offsets relative to the app window rather than the bounds of the device display and offsets relative to the device display.

How to optimize apps

Apps should use View APIs, taking into account the possibility of letterboxing and multi-window mode being applied to the app. See WindowMetricsCalculator .

How to disable or opt out of override

Set property flag PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS"
  android:value="false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

To remove the override:

adb shell am compat disable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

Disables force rotation. Improves the user experience on some apps.

How apps can achieve same result as override

Set property flag PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION to false .

How to optimize apps

Do not rely on cached camera sensor orientation or device information. For camera compatibility guidance, see Introducing Camera Viewfinder and Support resizable surfaces in your camera app .

How to disable or opt out of override

Set property flag PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION to true .

Property flags to adjust override

<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION"
  android:value="true|false"/>

adb commands to test override

To apply the override, which removes force rotation:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

To remove the override, which allows force rotation to happen:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH

Disables activity refresh after force rotation. Improves the user experience when refresh causes state loss in apps.

How apps can achieve same result as override

Set property flag PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH to false .

How to optimize apps

See OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION .

How to disable or opt out of override

Set property flag PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH to true .

Property flags to adjust override

<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH"
  android:value="true|false"/>

adb commands to test override

To apply the override, which removes activity refresh:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

To remove the override, which allows activity refresh:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE

Makes the packages it is applied to do activity refresh using an onResume() → onPause() → onResume() cycle rather than onResume() → onStop() → onResume() after camera compatibility force rotation.

How apps can achieve same result as override

Set property flag PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE to true .

How to optimize apps

See OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION .

How to disable or opt out of override

Set property flag PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE"
  android:value="true|false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

To remove the override:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT

Forces camera output to be cropped to the opposite orientation when portrait camera orientation doesn't align with the natural device orientation. Many apps don't handle this situation and display stretched images otherwise.

How apps can achieve same result as override

Set property flag PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT to true .

How to optimize apps

See OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION .

How to disable or opt out of override

Set property flag PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT to false .

Property flags to adjust override

<property android:name="android.camera.PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT"
  android:value="true|false"/>

adb commands to test override

To apply the override, which applies inner front camera cropping:

adb shell am compat enable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

To remove the override, which removes inner front camera cropping:

adb shell am compat disable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION

Prevents apps from opting out of app screen sharing (see Media projection ). Implemented when apps misuse the createConfigForDefaultDisplay() API to force full‑screen capture and jeopardize user privacy by exposing the contents of notifications, which are captured with full‑screen but not app screen sharing, and all apps regardless of windowing mode.

How apps can achieve same result as override

Allow the default media projection behavior (implemented in Android 14, API level 34, with createScreenCaptureIntent() ), which enables users to decide whether to share the full screen or a single app window regardless of windowing mode. Or call createScreenCaptureIntent(MediaProjectionConfig) with a MediaProjectionConfig argument returned from a call to createConfigForUserChoice() .

How to optimize apps

Allow users to select whether to share the entire device display or an app window during media projection, which as of Android 14 is the default behavior.

Make your app resizable ( resizeableActivity="true" ) to support multi‑window mode.

How to disable or opt out of override

Because of the seriousness of user privacy, your app cannot disable or opt out of this override.

Property flags to adjust override

هیچ کدام.

adb commands to test override

To apply the override, which cancels the app's opt out of partial screen sharing (that is, enables partial screen sharing):

adb shell am compat enable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

To remove the override, which allows the app's opt out of partial screen sharing:

adb shell am compat disable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS

Enables sending fake focus for unfocused apps in split‑screen mode. Some game engines wait to get focus before drawing the content of the app; and so, fake focus helps apps avoid staying blacked out when they are resumed and do not yet have focus.

How apps can achieve same result as override

Set property flag PROPERTY_COMPAT_ENABLE_FAKE_FOCUS to true .

How to optimize apps

You can avoid this issue if your app handles multiple orientations and configuration changes well. Make your app large screen ready by following the Large screen app quality guidelines.

If you run the Unity game engine, upgrade to version 2019.4.40 or later and re‑export your game. Keep the Resizable Window option checked in the Android Player settings.

How to disable or opt out of override

Set property flag PROPERTY_COMPAT_ENABLE_FAKE_FOCUS to false .

Property flags to adjust override

<property android:name="android.window.PROPERTY_COMPAT_ENABLE_FAKE_FOCUS"
  android:value="true|false"/>

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

To remove the override:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

Note: The commands only temporarily apply or remove the override.

OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS

When the override is enabled, the activity receives configuration coupled with caption bar insets. Normally, caption bar insets are decoupled from configuration.

How apps can achieve same result as override

Enable edge‑to‑edge display or update the app's target SDK to API level 35 or higher. See the following:

• Compose: About window insets
• Views: Display content edge-to-edge in views
• Configuration: Behavior changes: Apps targeting Android 15 or higher

How to optimize apps

You can avoid this issue if your app enables edge‑to‑edge display or targets API level 35 or higher.

How to disable or opt out of override

Enable edge‑to‑edge display or target API level 35 or higher.

Property flags to adjust override

هیچ کدام.

adb commands to test override

To apply the override:

adb shell am compat enable OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS <package>

To remove the override:

adb shell am compat disable OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS <package>

Note: The commands only temporarily apply or remove the override.

منابع اضافی

• Large screen app quality guidelines
• Core app quality guidelines