Zarządzanie kontrolerami TV

Urządzenia TV wymagają dodatkowego urządzenia do interakcji z aplikacjami – podstawowego pilota, pilota wskaźnikowego lub kontrolera do gier. Aby zapewnić spójne wrażenia użytkownika, aplikacja musi obsługiwać wejście z pada kierunkowego, radzić sobie z odłączaniem kontrolerów i obsługiwać wejście z wielu typów kontrolerów, w tym pilotów ze wskaźnikiem.

Minimalne sterowanie za pomocą pada kierunkowego

Domyślnym kontrolerem urządzenia TV 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, wybierania, Wstecz i Ekran główny. Jeśli Twoja aplikacja to gra, która zwykle wymaga kontrolera z dodatkowymi elementami sterującymi, spróbuj umożliwić rozgrywkę za pomocą tylko tych elementów sterujących na padzie kierunkowym. W przeciwnym razie ostrzeż użytkownika, że wymagany jest kontroler, i pozwól mu płynnie wyjść z gry za pomocą kontrolera z padem kierunkowym.

Więcej informacji o nawigacji za pomocą kontrolerów z padem kierunkowym na urządzeniach TV znajdziesz w artykule Nawigacja na telewizorze.

Postępowanie w razie odłączenia kontrolera

Piloty do telewizora często są urządzeniami 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 ponownie uruchomiona, jeśli nie jest skonfigurowana do obsługi tych zdarzeń ponownego połączenia. Może to nastąpić w tych sytuacjach:

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

Wszelka aktywność aplikacji TV, która podlega zdarzeniom odłączenia i ponownego połączenia, musi być skonfigurowana do obsługi zdarzeń ponownego połączenia w pliku manifestu aplikacji. Poniższy przykładowy kod pokazuje, jak włączyć obsługę zmian konfiguracji w aktywności, w tym podłączania, odłączania i ponownego podłączania 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 działać dalej po ponownym nawiązaniu połączenia, zamiast być ponownie uruchamianą przez platformę Android, co nie jest dobrym rozwiązaniem z punktu widzenia użytkownika.

Obsługa różnych danych wejściowych z pada kierunkowego

Użytkownicy urządzeń telewizyjnych mogą mieć więcej niż jeden typ kontrolera, którego używają z telewizorem. Użytkownik może na przykład mieć podstawowy kontroler z padem kierunkowym, pilot z wskaźnikiem lub kontroler do gier. Kody klawiszy podawane przez kontroler do gier, gdy jest on używany do funkcji pada kierunkowego, mogą się różnić od kodów klawiszy wysyłanych przez podstawowy pad kierunkowy.

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

Obsługa pilotów wskaźnikowych

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

Deklarowanie obsługi wskaźnika pilota w manifeście

Aby wskazać, że aplikacja obsługuje nawigację za pomocą wskaźnika i dotyku, skonfiguruj plik manifestu aplikacji za pomocą metadanych android.software.leanback.supports_touch ustawionych na 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>

obsługują interakcje takie jak kliknięcie, najechanie kursorem i przewijanie.

Jeśli obsługujesz piloty wskaźnikowe, upewnij się, że komponenty interfejsu reagują prawidłowo na dane wejściowe z kursora i dotyku w przypadku tych interakcji:

• Klikanie i wybieranie: wszystkie elementy interfejsu, na których można ustawić fokus i które można wybrać, muszą być klikalne za pomocą pilota ze wskaźnikiem, co odpowiada zachowaniu wyboru za pomocą pada kierunkowego (KEYCODE_DPAD_CENTER).
  • Jetpack Compose: użyj modyfikatorów Modifier.clickable() lub pointerInput. Więcej informacji znajdziesz w artykule Dotykanie i przytrzymywanie.
  • Widoki: obsługuje zdarzenia kliknięcia w widokach. Więcej informacji znajdziesz w omówieniu zdarzeń wejściowych.
• Wizualne stany najechania: zapewniają wyraźny wizualny efekt najechania, który wskazuje, kiedy kursor wskaźnika znajduje się nad elementem, który można wybrać.
  • Jetpack Compose: użyj Modifier.hoverable() lub obserwuj stany najechania kursorem za pomocą InteractionSource. Więcej informacji znajdziesz w artykule Obsługa interakcji użytkowników.
  • Widoki: zdefiniuj stany najechania kursorem za pomocą rysunków z listą stanów z atrybutem android:state_hovered="true".
• Przewijanie przez przesunięcie i szybkie przesunięcie: przewijanie w poziomie i pionie wywoływane przez przesunięcie lub szybkie przesunięcie na środkowym przycisku pada kierunkowego z funkcją dotykową musi działać płynnie w przypadku wszystkich treści, 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 z możliwością przewijania.
  • Jetpack Compose: standardowe kontenery z możliwością przewijania domyślnie obsługują przewijanie za pomocą wskaźnika i dotyku. W przypadku implementacji niestandardowych zapoznaj się z artykułem Dane wejściowe wskaźnika w Compose.
  • Widoki: standardowe widoki z możliwością przewijania obsługują przewijanie dotykowe domyślnie. 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) poprzez wskazywanie i kliknięcie, aby przejść do wcześniejszego lub późniejszego znacznika czasu, 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 wartością KeyEvent. Przeznaczeniem przycisku może być zdarzenie multimedialne, takie jak odtwarzanie, wstrzymywanie lub zatrzymywanie, albo zdarzenie związane z telewizją, takie jak wybór lub nawigacja. Aby zapewnić użytkownikom wygodę, przypisz przyciskom kontrolera spójne działanie.

Zdarzenia w interfejsie telewizora

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

Zdarzenia związane z multimediami

Gdy użytkownik ogląda multimedia, przypisz do przycisków zachowania generujące typy KeyEvent zgodnie z tabelą poniżej. Jeśli aplikacja steruje urządzeniem MediaSession, użyj elementu MediaControllerAdapter, aby wywołać jedną z metod MediaControllerCompat.TransportControls pokazanych w tabeli. Pamiętaj, że w tym przypadku przyciski wyboru działają jak przyciski odtwarzania i wstrzymywania.

Zapewnij odpowiednie działanie przycisku Wstecz

Przycisk Wstecz nigdy 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 wstecznej, w stylu ścieżki, po poprzednich ekranach, na których był gracz.

Przycisk Wstecz służy tylko do liniowej nawigacji wstecznej, więc możesz go używać do opuszczania menu w aplikacji otwartego za pomocą innego przycisku i powrotu 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 telewizyjnego > ekran główny aplikacji telewizyjnej.

Ekran główny Androida TV.

Więcej informacji o projektowaniu nawigacji znajdziesz w artykule Projektowanie nawigacji Wstecz i W górę. Więcej informacji o wdrażaniu 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 z dedykowanymi kontrolerami do gier.

Obsługa sterowania za pomocą pada kierunkowego

Zaplanuj schemat sterowania wokół pada kierunkowego, ponieważ jest on domyślnym zestawem sterowania na urządzeniach z Androidem TV. Gracz musi mieć możliwość używania 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 w grze na Androida TV nie ma odniesień do interfejsu dotykowego, np. w postaci komunikatu „Kliknij tutaj, aby kontynuować”.

Sposób, w jaki gracz wchodzi w interakcję z kontrolerem, może mieć kluczowe znaczenie dla zapewnienia mu świetnych wrażeń. Nie zapomnij o tych sprawdzonych metodach:

• Z wyprzedzeniem informuj o wymaganiach dotyczących kontrolera: w opisie w Google Play informuj graczy o wszelkich oczekiwaniach dotyczących kontrolerów. Jeśli gra lepiej nadaje się do pada do gier z joystickiem niż do pada do gier z samym padem kierunkowym, wyraźnie to zaznacz. Gracz, który używa nieodpowiedniego kontrolera, może mieć negatywne wrażenia i przyznać Twojej grze niską ocenę.
• Stosuj spójne mapowanie przycisków: intuicyjne mapowanie przycisków jest kluczowe dla dobrego wrażenia użytkownika. Na przykład przestrzegaj przyjętych zwyczajów, używając przycisku A do akceptowania i przycisku B do anulowania. Możesz też zapewnić elastyczność, umożliwiając użytkownikowi 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łanie do kontrolera zapytań o jego możliwości w celu optymalizacji dopasowania kontrolera do gry. Na przykład możesz 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ć. Wysyłaj zapytania do kontrolera i jeśli wykrywanie ruchu nie jest obsługiwane, przełącz się na alternatywny, dostępny schemat sterowania. Więcej informacji o zapytaniach dotyczących możliwości kontrolera znajdziesz w artykule Obsługa kontrolerów w różnych wersjach Androida.

Używanie odpowiednich przycisków

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

Obsługa wielu kontrolerów

Gdy w grę gra kilku graczy, każdy z własnym kontrolerem, ważne jest, aby przypisać 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 wyświetlaj też wskazówki dotyczące rozwiązywania problemów z ofertą. Możesz na przykład poprosić odtwarzacz o sprawdzenie połączenia Bluetooth. Więcej informacji o wdrażaniu obsługi urządzeń wejściowych znajdziesz w artykule Obsługa działań kontrolera i w omówieniu Bluetootha.

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.

Przykładowe zdjęcia kontrolera zgodnego z Androidem znajdziesz w szablonie gamepada Androida TV (ZIP). Zawiera biały kontroler na czarnym tle i czarny kontroler na białym tle – widoczne na ilustracji 1 – w formacie PNG i Adobe® Illustrator®.