کنترل کننده های تلویزیون را مدیریت کنید

دستگاه‌های تلویزیون برای تعامل با برنامه‌ها به یک دستگاه سخت‌افزاری ثانویه نیاز دارند - یک کنترل از راه دور ساده، کنترل از راه دور اشاره‌گر یا کنترل بازی. برای ارائه یک تجربه کاربری سازگار، برنامه شما باید از ورودی پد جهت‌دار (D-pad) پشتیبانی کند، کنترل‌کننده‌ها را در حالت آفلاین مدیریت کند و از ورودی انواع مختلف کنترل‌کننده، از جمله کنترل از راه دور اشاره‌گر، پشتیبانی کند.

حداقل کنترل‌های D-pad

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

برای اطلاعات بیشتر در مورد ناوبری با کنترل‌کننده‌های D-pad برای دستگاه‌های تلویزیون، به ناوبری تلویزیون مراجعه کنید.

قطع شدن کنترل کننده دسته

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

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

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

<activity
  android:name="com.example.android.TvActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|navigation"
  android:theme="@style/Theme.Leanback">

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
  </intent-filter>
  ...
</activity>

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

مدیریت تغییرات ورودی D-pad

کاربران دستگاه‌های تلویزیون ممکن است بیش از یک نوع دسته بازی داشته باشند که با تلویزیون خود از آنها استفاده می‌کنند. برای مثال، یک کاربر ممکن است یک دسته بازی ساده، یک ریموت کنترل اشاره‌گر یا یک دسته بازی داشته باشد. کدهای کلیدی ارائه شده توسط دسته بازی هنگام استفاده از عملکردهای دسته بازی ممکن است با کدهای کلیدی ارسال شده توسط یک دسته بازی ساده متفاوت باشد.

تغییرات ورودی D-pad را مدیریت کنید تا کاربر برای اجرای برنامه شما مجبور به تغییر کنترلر نباشد. برای اطلاعات بیشتر در مورد مدیریت تغییرات ورودی، به Process directional pad input مراجعه کنید.

پشتیبانی از ریموت‌های اشاره‌گر

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

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

برای نشان دادن اینکه برنامه شما با اشاره گر و ورودی لمسی قابل پیمایش است، مانیفست برنامه خود را با فراداده android.software.leanback.supports_touch که روی true تنظیم شده است، پیکربندی کنید:

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <!-- Signal whether the app supports pointer remotes -->
    <meta-data
        android:name="android.software.leanback.supports_touch"
        android:value="true" />
    <application ...>
        ...
    </application>
</manifest>

پشتیبانی از تعاملات کلیک، شناور و پیمایش

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

  • کلیک و انتخاب: تمام عناصر رابط کاربری قابل فوکوس و انتخاب باید با ریموت اشاره‌گر قابل کلیک باشند و با رفتار انتخاب با D-pad ( KEYCODE_DPAD_CENTER ) مطابقت داشته باشند.
    • نوشتن با Jetpack: Modifier.clickable() یا اصلاح‌کننده‌های pointerInput استفاده کنید. برای جزئیات بیشتر، به Tap and press مراجعه کنید.
    • نماها: رویدادهای کلیک را در نماها مدیریت می‌کند. برای جزئیات بیشتر، به نمای کلی رویدادهای ورودی مراجعه کنید.
  • حالت‌های شناور بصری: یک جلوه شناور بصری واضح ارائه می‌دهد تا نشان دهد چه زمانی مکان‌نما روی یک مورد قابل انتخاب قرار می‌گیرد.
    • Jetpack Compose: Modifier.hoverable() استفاده کنید یا با استفاده از InteractionSource حالت‌های شناور را مشاهده کنید. برای جزئیات بیشتر، به Handle user interactions مراجعه کنید.
    • نماها: حالت‌های شناور را با استفاده از drawableهای لیست وضعیت با android:state_hovered="true" تعریف کنید.
  • پیمایش با کشیدن انگشت و چرخاندن: پیمایش افقی و عمودی که با کشیدن انگشت یا چرخاندن انگشت روی دکمه‌ی مرکزی D-pad حساس به لمس انجام می‌شود، باید در تمام محتوای قابل پیمایش به راحتی کار کند.
  • پیمایش با کشیدن: کاربران باید بتوانند با کشیدن، به صورت عمودی (بالا و پایین) یا افقی (چپ و راست) در میان بخش‌های قابل پیمایش پیمایش کنند.
    • Jetpack Compose: کانتینرهای استاندارد قابل پیمایش به طور پیش‌فرض از پیمایش اشاره‌گر و لمسی پشتیبانی می‌کنند. برای پیاده‌سازی‌های سفارشی، به ورودی اشاره‌گر در Compose مراجعه کنید.
    • نماها: نماهای استاندارد قابل پیمایش به طور پیش‌فرض از پیمایش لمسی پشتیبانی می‌کنند. برای مدیریت ورودی سفارشی، به بخش «لمس و ورودی» مراجعه کنید.
  • جابجایی پخش رسانه: در حین پخش رسانه (مانند برنامه‌های تلویزیونی و فیلم‌ها)، کاربران باید بتوانند با اشاره و کلیک برای پرش به یک نشانگر زمانی گذشته یا آینده، و همچنین کشیدن (جابجایی) در امتداد نوار پیشرفت برای جستجو به یک زمان خاص، با نوار پیشرفت پخش (نوار جستجو) تعامل داشته باشند.

مدیریت رویدادهای دکمه

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

رویدادهای رابط کاربری تلویزیون

رفتار رابط کاربری تلویزیون را به دکمه‌هایی که انواع KeyEvent تولید می‌کنند، همانطور که در جدول زیر نشان داده شده است، اختصاص دهید:

KeyEvent رفتار
KEYCODE_BUTTON_B ، KEYCODE_BACK برگشت
KEYCODE_BUTTON_SELECT ، KEYCODE_BUTTON_A ، KEYCODE_ENTER ، KEYCODE_DPAD_CENTER ، KEYCODE_NUMPAD_ENTER انتخاب
KEYCODE_DPAD_UP ، KEYCODE_DPAD_DOWN ، KEYCODE_DPAD_LEFT ، KEYCODE_DPAD_RIGHT ناوبری

رویدادهای رسانه‌ای

وقتی کاربر در حال تماشای رسانه است، رفتاری را به دکمه‌هایی که انواع KeyEvent تولید می‌کنند، همانطور که در جدول زیر نشان داده شده است، اختصاص دهید. اگر برنامه شما یک MediaSession کنترل می‌کند، از MediaControllerAdapter برای فراخوانی یکی از متدهای MediaControllerCompat.TransportControls نشان داده شده در جدول استفاده کنید. توجه داشته باشید که دکمه‌های انتخاب در این زمینه به عنوان دکمه‌های پخش یا مکث عمل می‌کنند.

KeyEvent فراخوانی TransportControls رفتار
BUTTON_SELECT ، BUTTON_A ، ENTER ، DPAD_CENTER ، KEYCODE_NUMPAD_ENTER play() بازی
BUTTON_START ، BUTTON_SELECT ، BUTTON_A ، ENTER ، DPAD_CENTER ، KEYCODE_NUMPAD_ENTER pause() مکث
BUTTON_R1 skipToNext() رفتن به بعدی
BUTTON_L1 skipToPrevious() پرش به قبلی
DPAD_RIGHT ، BUTTON_R2 ، AXIS_RTRIGGER ، AXIS_THROTTLE fastForward() سریع به جلو
DPAD_LEFT ، BUTTON_L2 ، AXIS_LTRIGGER ، AXIS_BRAKE rewind() عقب بردن
ناموجود stop() توقف

رفتار مناسب دکمه برگشت را فراهم کنید

دکمه‌ی «بازگشت» هرگز نباید به عنوان یک دکمه‌ی تغییر وضعیت عمل کند. برای مثال، از آن برای باز کردن و بستن همزمان یک منو استفاده نکنید. فقط از آن برای حرکت به عقب، به سبک «مسیریاب» (breadcrumb)، در صفحات قبلی که پخش‌کننده در آن‌ها بوده است، استفاده کنید.

از آنجایی که دکمه برگشت فقط پیمایش خطی و رو به عقب را انجام می‌دهد، می‌توانید از آن برای باز کردن یک منوی درون‌برنامه‌ای توسط یک دکمه دیگر و بازگشت به برنامه استفاده کنید. فشردن متوالی دکمه برگشت باید در نهایت همیشه به صفحه اصلی Android TV منجر شود. به عنوان مثال: پخش بازی > صفحه مکث بازی > صفحه اصلی بازی > صفحه اصلی Android TV یا پخش برنامه تلویزیونی > صفحه اصلی برنامه تلویزیونی

صفحه اصلی تلویزیون اندروید.

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

دسته‌های بازی را کنترل کنید

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

پشتیبانی از کنترل‌های D-pad

طرح کنترل خود را بر اساس کنترل D-pad برنامه‌ریزی کنید، زیرا این مجموعه کنترل به طور پیش‌فرض برای دستگاه‌های Android TV است. بازیکن باید بتواند از D-pad برای تمام جنبه‌های بازی استفاده کند - نه تنها کنترل گیم‌پلی اصلی، بلکه پیمایش منوها و تبلیغات. به همین دلیل، مطمئن شوید که بازی Android TV شما به رابط لمسی با زبانی مانند "برای ادامه اینجا را لمس کنید " اشاره نمی‌کند.

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

  • الزامات مربوط به دسته بازی را از قبل به بازیکن اطلاع دهید: از توضیحات گوگل پلی خود برای بیان انتظارات خود در مورد دسته بازی استفاده کنید. اگر یک بازی برای دسته بازی با جوی استیک مناسب‌تر از دسته بازی فقط با D-pad است، این موضوع را روشن کنید. بازیکنی که از دسته بازی نامناسب برای بازی استفاده می‌کند، ممکن است تجربه ضعیفی داشته باشد و به بازی شما امتیاز بدی بدهد.
  • از نگاشت دکمه‌های ثابت استفاده کنید: نگاشت دکمه‌های شهودی کلید یک تجربه کاربری خوب است. برای مثال، با استفاده از دکمه A برای پذیرش و دکمه B برای لغو ، به آداب و رسوم پذیرفته شده پایبند باشید. همچنین می‌توانید با اجازه دادن به کاربر برای تغییر نگاشت دکمه‌ها، انعطاف‌پذیری ارائه دهید. برای اطلاعات بیشتر در مورد نگاشت دکمه‌ها، به Handle controller actions مراجعه کنید.
  • قابلیت‌های کنترلر را تشخیص داده و بر اساس آن تنظیم کنید: از کنترلر در مورد قابلیت‌های آن سوال کنید تا تطابق بین کنترلر و بازی بهینه شود. به عنوان مثال، ممکن است قصد داشته باشید که یک بازیکن با تکان دادن کنترلر در هوا، یک شیء را هدایت کند، اما اگر کنترلر بازیکن فاقد سخت‌افزار شتاب‌سنج و ژیروسکوپ باشد، تکان دادن کار نمی‌کند. از کنترلر سوال کنید و اگر تشخیص حرکت پشتیبانی نمی‌شود، به یک طرح کنترل جایگزین و موجود بروید. برای اطلاعات بیشتر در مورد قابلیت های کنترلر، به بخش پشتیبانی از کنترلرها در نسخه‌های مختلف اندروید مراجعه کنید.

استفاده از دکمه‌های مناسب

همه دسته‌های بازی دکمه‌های شروع، جستجو یا منو را ارائه نمی‌دهند. مطمئن شوید که رابط کاربری شما به استفاده از این دکمه‌ها وابسته نباشد.

مدیریت چندین کنترلر

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

قطع شدن کنترل کننده دسته

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

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

نمایش دستورالعمل‌های کنترلر

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

برای مشاهده تصاویر نمونه از یک دسته بازی سازگار با اندروید، قالب دسته بازی اندروید تی‌وی (ZIP) را دانلود کنید. این قالب شامل یک دسته بازی سفید با پس‌زمینه مشکی و یک دسته بازی مشکی با پس‌زمینه سفید - همانطور که در شکل ۱ نشان داده شده است - در قالب یک فایل PNG و یک فایل Adobe® Illustrator® است.

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