Zarządzanie kontrolerami TV

Telewizory wymagają dodatkowego urządzenia do interakcji z aplikacjami – podstawowego pilota, pilota ze wskaźnikiem lub kontrolera do gier. Aby zapewnić spójne wrażenia użytkownika, aplikacja musi obsługiwać wprowadzanie danych za pomocą pada kierunkowego, obsługiwać kontrolery przechodzące w tryb offline i obsługiwać wprowadzanie danych z różnych typów kontrolerów, w tym pilotów ze wskaźnikiem.

Minimalne elementy sterujące pada kierunkowego

Domyślnym kontrolerem na telewizorze jest pad kierunkowy. Ogólnie aplikacja musi być obsługiwana za pomocą pilota, który ma tylko przyciski w górę, w dół, w lewo, w prawo, Wybierz, Wstecz i Ekran główny. Jeśli Twoja aplikacja jest grą, która zwykle wymaga kontrolera do gier z dodatkowymi elementami sterującymi, spróbuj umożliwić rozgrywkę tylko za pomocą pada kierunkowego. W przeciwnym razie ostrzeż użytkownika, że kontroler jest wymagany, i pozwól mu wyjść z gry za pomocą pada kierunkowego.

Więcej informacji o nawigacji za pomocą padów kierunkowych na telewizorach znajdziesz w artykule Nawigacja na telewizorze.

Postępowanie w razie odłączenia kontrolera

Kontrolery do telewizorów to często urządzenia Bluetooth, które mogą próbować oszczędzać energię, okresowo przechodząc w tryb uśpienia i odłączając się od telewizora. Oznacza to, że aplikacja może zostać przerwana lub uruchomiona ponownie, jeśli nie jest skonfigurowana do obsługi tych zdarzeń ponownego połączenia. Może się tak zdarzyć w tych sytuacjach:

  • Podczas odtwarzania filmu, który trwa kilka minut, pad kierunkowy lub kontroler do gier może przejść w tryb uśpienia, odłączyć się od telewizora i połączyć się z nim ponownie później.
  • Podczas rozgrywki nowy gracz może dołączyć do gry, używając kontrolera do gier, który nie jest jeszcze połączony.
  • Podczas rozgrywki gracz może opuścić grę i odłączyć kontroler do gier.

Każda aktywność aplikacji TV, która podlega zdarzeniom rozłączenia i ponownego połączenia, musi być skonfigurowana w pliku manifestu aplikacji do obsługi zdarzeń ponownego połączenia. Poniższy przykładowy kod pokazuje, jak włączyć aktywność, aby obsługiwać zmiany konfiguracji, w tym podłączanie, odłączanie lub ponowne podłączanie klawiatury lub urządzenia nawigacyjnego:

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

Ta zmiana konfiguracji pozwala aplikacji kontynuować działanie po ponownym połączeniu, zamiast być ponownie uruchamianą przez platformę Androida, co nie jest dobrym rozwiązaniem dla użytkownika.

Obsługa różnych sposobów wprowadzania danych za pomocą pada kierunkowego

Użytkownicy telewizorów mogą mieć więcej niż 1 rodzaj kontrolera, którego używają z telewizorem. Użytkownik może na przykład mieć podstawowy pad kierunkowy, pilota ze wskaźnikiem lub kontroler do gier. Kody klawiszy wysyłane przez kontroler do gier, gdy jest on używany do obsługi funkcji pada kierunkowego, mogą się różnić od kodów wysyłanych przez podstawowy pad kierunkowy.

Obsługuj różne rodzaje danych wejściowych z pada kierunkowego, aby użytkownik nie musiał przełączać kontrolerów podczas korzystania z aplikacji. Więcej informacji o obsłudze różnych rodzajów danych wejściowych znajdziesz w artykule Przetwarzanie danych wejściowych z pada kierunkowego.

Obsługa pilotów ze wskaźnikiem

Niektóre telewizory obsługują piloty ze wskaźnikiem, takie jak myszy powietrzne lub piloty z czułymi na dotyk padami kierunkowymi (trackpadami). Obsługa pilotów ze wskaźnikiem umożliwia użytkownikom interakcję z aplikacją za pomocą gestów wskazywania i klikania, najeżdżania, przesuwania i przeciągania. Zapewnia to płynniejsze działanie na zgodnym sprzęcie przy zachowaniu pełnej zgodności z padem kierunkowym.

Deklarowanie w pliku manifestu obsługi zdalnej wskaźnika

Aby wskazać, że po aplikacji można poruszać się za pomocą wskaźnika i dotykowego wprowadzania danych, skonfiguruj plik manifestu aplikacji, ustawiając android.software.leanback.supports_touch <property> na true w elemencie <application> (lub w poszczególnych elementach <activity>, aby skonfigurować obsługę poszczególnych aktywności):

<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" />
    <application ...>
        <!-- Signal whether the app supports pointer remotes -->
        <property
            android:name="android.software.leanback.supports_touch"
            android:value="true" />
        ...
    </application>
</manifest>

obsługują interakcje polegające na kliknięciu, najechaniu kursorem i przewijaniu;

Jeśli obsługujesz piloty ze wskaźnikiem, upewnij się, że komponenty interfejsu odpowiednio reagują na kursor i dotykowe wprowadzanie danych w przypadku tych interakcji:

  • Klikanie i wybieranie: wszystkie elementy interfejsu, które można zaznaczyć i na których można ustawić kursor, muszą być klikalne za pomocą pilota ze wskaźnikiem, co odpowiada zachowaniu wyboru za pomocą pada kierunkowego (KEYCODE_DPAD_CENTER).
  • Wizualne stany najechania kursorem: zapewniają wyraźny efekt wizualny po najechaniu kursorem, który wskazuje, kiedy kursor znajduje się nad elementem, który można wybrać.
  • Przewijanie przez przesunięcie i szybkie przesunięcie: przewijanie w poziomie i pionie wywoływane przez przesunięcie lub szybkie przesunięcie na czułym na dotyk środkowym przycisku pada kierunkowego musi działać płynnie we wszystkich treściach, które można przewijać.
  • Przewijanie przez przeciąganie: użytkownicy muszą mieć możliwość przeciągania, aby przewijać w pionie (w górę i w dół) lub w poziomie (w lewo i w prawo) w kontenerach, które można przewijać.
    • Jetpack Compose: standardowe kontenery z możliwością przewijania domyślnie obsługują przewijanie za pomocą wskaźnika i dotyku. Informacje o implementacjach niestandardowych znajdziesz w artykule Dane wejściowe ze wskaźnika w Compose.
    • Widoki: standardowe widoki z możliwością przewijania domyślnie obsługują przewijanie dotykowe. Informacje o niestandardowej obsłudze danych wejściowych znajdziesz w sekcji Dotyk i wprowadzanie danych.
  • Przewijanie odtwarzanych multimediów: podczas odtwarzania multimediów (np. programów telewizyjnych i filmów) użytkownicy muszą mieć możliwość interakcji z paskiem postępu odtwarzania (paskiem przewijania) przez wskazywanie i klikanie, aby przejść do wcześniejszej lub późniejszej sygnatury czasowej, a także przeciąganie (przewijanie) wzdłuż paska postępu, aby przejść do określonego momentu.

Obsługa zdarzeń przycisków

Gdy użytkownik kliknie przycisk na kontrolerze, aplikacja otrzyma zdarzenie z KeyEvent. Zamierzonym działaniem przycisku może być zdarzenie multimedialne, takie jak odtwarzanie, wstrzymanie lub zatrzymanie, albo zdarzenie typu telewizyjnego, takie jak wybór lub nawigacja. Aby zapewnić użytkownikom dobre wrażenia, przypisz spójne zachowania do przycisków kontrolera.

Zdarzenia w interfejsie telewizora

Przypisz zachowanie interfejsu telewizora do przycisków, które generują typy KeyEvent, jak pokazano w tabeli poniżej:

KeyEvent Zachowanie
KEYCODE_BUTTON_B, KEYCODE_BACK Wstecz
KEYCODE_BUTTON_SELECT, KEYCODE_BUTTON_A, KEYCODE_ENTER, KEYCODE_DPAD_CENTER, KEYCODE_NUMPAD_ENTER Zaznaczenie
KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT, KEYCODE_DPAD_RIGHT Nawigacja

Zdarzenia związane z multimediami

Gdy użytkownik ogląda multimedia, przypisz zachowanie do przycisków, które generują typy KeyEvent, jak pokazano w tabeli poniżej. Jeśli aplikacja steruje obiektem MediaSession, użyj MediaControllerAdapter, aby wywołać jedną z metod MediaControllerCompat.TransportControls podanych w tabeli. Pamiętaj, że przyciski wyboru działają w tym kontekście jako przyciski odtwarzania lub wstrzymania.

KeyEvent Wywołanie TransportControls Zachowanie
BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER, KEYCODE_NUMPAD_ENTER play() Odtwórz
BUTTON_START, BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER, KEYCODE_NUMPAD_ENTER pause() Wstrzymaj
BUTTON_R1 skipToNext() Dalej
BUTTON_L1 skipToPrevious() Wstecz
DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER, AXIS_THROTTLE fastForward() Przewiń do przodu
DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER, AXIS_BRAKE rewind() Przewiń do tyłu
Nie dotyczy stop() Zatrzymaj

Zapewnij odpowiednie działanie przycisku Wstecz

Przycisk Wstecz nie może działać jako przełącznik. Nie używaj go na przykład do otwierania i zamykania menu. Używaj go tylko do nawigacji wstecz, w stylu menu okruszkowego, przez poprzednie ekrany, na których był gracz.

Przycisk Wstecz umożliwia tylko liniową nawigację wstecz, więc możesz go użyć, aby zamknąć menu w aplikacji otwarte za pomocą innego przycisku i wrócić do aplikacji. Kolejne naciśnięcia przycisku Wstecz muszą zawsze prowadzić do ekranu głównego Androida TV. Na przykład: rozgrywka > ekran wstrzymania gry > ekran główny gry > ekran główny Androida TV lub odtwarzanie programu TV > ekran główny aplikacji TV.

Ekran główny Androida TV.

Więcej informacji o projektowaniu nawigacji znajdziesz w artykule Designing Back and Up navigation (Projektowanie nawigacji Wstecz i W górę). Więcej informacji o implementacji znajdziesz w artykule Zapewnianie prawidłowego przechodzenia wstecz.

Obsługa kontrolerów do gier

Podczas tworzenia gier na Androida TV zaprojektuj schemat sterowania tak, aby działał zarówno ze standardowymi pilotami do telewizora, jak i dedykowanymi kontrolerami do gier.

Obsługa pada kierunkowego

Zaplanuj schemat sterowania wokół pada kierunkowego, ponieważ ten zestaw elementów sterujących jest domyślny na urządzeniach z Androidem TV. Gracz musi mieć możliwość korzystania z pada kierunkowego we wszystkich aspektach gry – nie tylko do sterowania rozgrywką, ale także do poruszania się po menu i reklamach. Dlatego upewnij się, że gra na Androida TV nie odnosi się do interfejsu dotykowego, np. „Kliknij tutaj, aby kontynuować”.

Sposób, w jaki gracz korzysta z kontrolera, może mieć kluczowe znaczenie dla zapewnienia mu doskonałych wrażeń. Nie zapomnij o tych sprawdzonych metodach:

  • Z góry poinformuj o wymaganiach dotyczących kontrolera: w opisie w Google Play poinformuj gracza o wszelkich oczekiwaniach dotyczących kontrolerów. Jeśli gra lepiej działa z padem do gier z joystickiem niż z padem kierunkowym, wyraźnie o tym poinformuj. Gracz, który używa nieodpowiedniego kontrolera, może mieć złe wrażenia z rozgrywki i wystawić grze niską ocenę.
  • Używaj spójnego mapowania przycisków: intuicyjne mapowanie przycisków jest kluczowe dla wygody użytkowników. Na przykład przestrzegaj przyjętych zwyczajów, używając przycisku A do akceptowania i przycisku B do anulowania. Możesz też zapewnić użytkownikom elastyczność, umożliwiając im zmianę mapowania przycisków. Więcej informacji o mapowaniu przycisków znajdziesz w artykule Obsługa działań kontrolera.
  • Wykrywanie możliwości kontrolera i odpowiednie dostosowywanie: wysyłaj zapytania do kontrolera o jego możliwości, aby zoptymalizować dopasowanie kontrolera do gry. Możesz na przykład chcieć, aby gracz sterował obiektem, machając kontrolerem w powietrzu, ale jeśli kontroler gracza nie ma akcelerometru i żyroskopu, machanie nie będzie działać. Sprawdź kontroler i jeśli nie obsługuje wykrywania ruchu, przełącz się na alternatywny, dostępny schemat sterowania. Więcej informacji o sprawdzaniu możliwości kontrolera znajdziesz w artykule o obsłudze kontrolerów w różnych wersjach Androida.

Używanie odpowiednich przycisków

Nie wszystkie kontrolery do gier mają przyciski Start, Szukaj lub Menu. Upewnij się, że interfejs nie zależy od użycia tych przycisków.

Obsługa wielu kontrolerów

Gdy w grze uczestniczy wielu graczy, z których każdy ma własny kontroler, ważne jest, aby zmapować każdą parę gracz–kontroler. Informacje o tym, jak wdrożyć identyfikację numeru kontrolera, znajdziesz w artykule getControllerNumber().

Postępowanie w razie odłączenia kontrolera

Jeśli kontroler zostanie odłączony w trakcie rozgrywki, wstrzymaj grę i wyświetl okno z prośbą o ponowne podłączenie kontrolera.

W oknie dialogowym podaj też wskazówki dotyczące rozwiązywania problemów. Możesz na przykład poprosić gracza o sprawdzenie połączenia Bluetooth. Więcej informacji o implementowaniu obsługi urządzeń wejściowych znajdziesz w artykule Obsługa działań kontrolera i omówieniu Bluetooth.

Pokaż instrukcje dotyczące kontrolera

Jeśli Twoja gra zawiera wizualne instrukcje sterowania, użyj obrazu kontrolera bez elementów marki i uwzględnij tylko przyciski zgodne z Androidem.

Aby zobaczyć przykładowe obrazy kontrolera zgodnego z Androidem, pobierz szablon pada do gier na Androida TV (ZIP). Zawiera on biały kontroler na czarnym tle i czarny kontroler na białym tle (jak na rysunku 1) w formacie PNG i Adobe® Illustrator®.

**Rysunek 1.** Przykładowe instrukcje dotyczące kontrolera z użyciem szablonu pada do gier na Androida TV.
Wstecz
Obsługa sprzętu telewizyjnego
Dalej
Klawiatura ekranowa