フォーカス管理

​

フォーカス管理の概要のビデオ

​

フォーカス管理戦略

1. デカルトフォーカス管理： これがデフォルト／暗黙のフォーカス動作です。多くのユースケースではこれで十分です。
2. フォーカスプロパティとメソッド： アプリ内の特定のコンポーネントでデフォルトのフォーカス動作をオーバーライドする必要がある場合、Vegaでは、フォーカスに関連するさまざまなプロパティとターボモジュールメソッドがサポートされています。これらは、デフォルトの動作が適さない特殊なケースを定義するために使用できます。
3. 専用のフォーカスコンポーネント： 場合によっては、デフォルトのデカルト動作とは体系的に異なる動作が必要になることがあります（たとえば、よく使用されるものにTVFocusGuideViewがあります）。このセクションには、Vegaでサポートされているカスタムコンポーネント（TVFocusGuideViewを含む）の一覧が含まれています。

​

Vegaでの基本的なフォーカス処理

​

フォーカスを示す方法

​

フォーカス状態での表示がすぐに使用できるコンポーネント

コンポーネント	フォーカスなし（デフォルトの状態）	フォーカスあり（不透明度が変更）

​

Vegaでのフォーカスへの応答

const FocusablePressable = () => {
  const [isFocused, setIsFocused] = useState(false); // 状態を使用してフォーカスを追跡します。

  return (
    <Pressable
      style={[styles.button, isFocused && styles.buttonFocused]} // フォーカスの状態に基づいてスタイルを適用します。
      onFocus={() => setIsFocused(true)} // onFocus()でフォーカス状態を設定します。
      onBlur={() => setIsFocused(false)} // onBlur()でフォーカス状態の設定を解除します。
    >
      <Text style= {[styles.text]} >
        {'Presssable'}
      </Text>
    </Pressable>
  );
};

const styles = StyleSheet.create({
  button: {
    padding: 10,
    backgroundColor: 'gray', // デフォルトの境界色を指定します。
    borderRadius: 5,
  },
  buttonFocused: {
    borderWidth: 2,
    borderColor: 'blue', // フォーカスがあるときに境界の色を青に変更します。

  },
});

​

コンポーネントをフォーカス可能にする方法

• よく使用されるのは、TouchableHighlight、TouchableOpacity、TouchableWithoutFeedback、Button、Pressableどのタッチ可能なコンポーネントのグループです。これらには、コンポーネントが「押された」とき（リモコンの選択ボタンやキーボードのEnterキーが押されたとき）のハンドラーを定義するプロパティが用意されているためです。
• ScrollView``FlatList基本的なフォーカスマネジメントのサポートも含まれています。インデックスベースのナビゲーションが使用され、フォーカス可能な次のアイテムが画面の外またはScrollViewの境界外にある場合にのみリストがスクロールされます。

​

フォーカスを命令的に設定する方法

const focusableComponent = () => {
  const focusTargetRef = React.useRef(null);

  const focusOnTarget = () => focusTargetRef.current?.focus();

  return (
          <View>
            <TouchableOpacity
                    ref={focusTargetRef}
                    onPress={() => {}}>
              <Text>フォーカスターゲット</Text>
            </TouchableOpacity>
          </View>
  );
};

​

Vegaにおけるコンポーネントのフォーカスの可否

​

Vegaでのフォーカスナビゲーションの動作

​

デカルトフォーカス管理

• 下ボタンを押すと、すぐ下のアイテムにフォーカスが移動します。
• 右ボタンを押すと、隣接するアイテムにフォーカスが水平に移動します。

​

さまざまなレイアウトでのデカルトフォーカスナビゲーションアルゴリズムの事例

​

事例1： 下ボタンを押してもフォーカスが真下のアイテムに移動しないケース

[ 上アイテム ] [上サイドアイテム]
      |
      v
            [サイドアイテム]
[ 下アイテム ]

• [上アイテム] から下ボタンを押した場合：
  • フォーカスが [Small Item] に移動します。
• これは、[Small Item] の下端と [Bottom Item] の上端が水平方向で重なり合っていないためです。

• 同様のコンポーネント配置で、代わりに [Bottom Item] にフォーカスが移動します。
• このように動作が異なるのは、[Small Item] の下端が [Bottom Item] の上端と水平方向で重なり合っているためです。

• [上アイテム] から下ボタンを押した場合：
  • フォーカスが [Small Item] に移動します。
• これは、[Small Item] の左端が [Top Item] の右端と垂直方向で重なり合っているためです。

• 同様のコンポーネント配置の場合： 代わりに [Bottom Item] にフォーカスが移動します。
• これは、[Small Item] の左端が [Top Item] の右端と垂直方向で重なり合っていないためです。

• コンポーネント間のエッジの重なりも考慮されます。
• 次のフォーカス可能な要素までの距離も考慮されます。
• コンポーネントの配置はナビゲーションパスに大きく影響します。

• FocusManager.setNextFocus()メソッド。
• nextFocusUp/nextFocusDown/nextFocusLeft/nextFocusRightプロパティ。
• FocusManager.focus()プログラムで特定の要素にフォーカスを割り当てることができます。
• コンテナ内に移動するときにフォーカスを制御する<TVFocusGuideView>のdestinationプロパティ

​

事例2： 縦に並んだ異なる幅のアイテム間を移動するときに、全幅の要素にフォーカスが移動しないケース

[ アイテム1 ]
[ 全幅アイテム ]
[アイテム3] [アイテム4] [アイテム5]

• 下ボタンを押すと、強制的に [アイテム1] から [全幅アイテム] にフォーカスが移動します。
• [アイテム3] から [全幅アイテム] への上方向のナビゲーション
• [全幅アイテム] から [アイテム3] への下方向のナビゲーション

​

Vegaにおけるフォーカス動作

​

異なる行のアイテム間のフォーカスの処理

​

フォーカスの復元

• @amazon-devices/react-navigation__stack
  • ❌ フォーカスの自動復元なし
• @amazon-devices/react-navigation__native-stack
  • ❌ フォーカスの自動復元なし

​

フォーカスを復元するための実装オプション

• 各画面について、最近フォーカスされた要素への参照を保存します。
• useFocusEffect()ユーザーが画面に戻ったことを検出するために使用します。
• useFocusEffect()内部では、FocusManager.setFocus()保存されている参照を呼び出して、正しい要素にフォーカスを戻します。

​

初期フォーカスの構成

• hasTVPreferredFocusプロップは、コンポーネントの初期マウント時にフォーカスを設定します。このプロパティは初期のレンダリング段階でのみ機能します。
• useEffectやuseFocusEffect（React Navigationに含まれる）をFocusManager.setFocus()と組み合わせると、特にアプリがReact Navigationで構築された複数ページのアプリ内でフォーカス状態をアクティブに復元する必要がある場合に、より動的なアプローチが可能になります。このアプローチでは、初回のマウント段階以降もフォーカスの動作をより柔軟に細かく制御できます。

​

非表示のビュー

• hasTVPreferredFocusプロパティが設定されたコンポーネントがない場合、フォーカスは、ユーザーがいずれかのコンポーネントに移動するまで（D-padキーを押すなど）、画面上のどのコンポーネントにも与えられません。
• フォーカスが失われた場合（現在フォーカスのあるコンポーネントをマウント解除した場合など）、フォーカスは、ユーザーがいずれかのコンポーネントに移動するまで、どのコンポーネントにも自動的には与えられません。
• 前の画面に戻ったとき、フォーカスはどのコンポーネントにも自動的には与えられません。

​

非表示のビューに関する開発者向けガイドライン

• pointerEvents: 'none' - あらゆる種類のポインターイベントを無効にして、フォーカス検索ロジックとタッチベースのイベントのヒットテストが実行されないようにします。これにより、ビューがタッチイベントとフォーカスイベントのターゲットになるのを防ぐことができます。
• accessibilityElementsHidden: true - コンテナは存在していてもユーザーには表示されないため、フォーカス処理に関して、マウントされているコンポーネントをビュー階層から削除します。フォーカス検索ロジックは、このプロパティを使用して非表示のコンテナへのフォーカスを禁止します。

• display: 'none' - コンテナが非表示になるように、内部的にアクセシビリティ状態を設定します。それがフォーカス検索ロジックの計算に利用されます。

​

フォーカス動作のカスタマイズ

• フォーカスプロパティとメソッド： アプリ内の特定のコンポーネントでデフォルトのフォーカス動作をオーバーライドする必要がある場合、Vegaでは、フォーカスに関連するさまざまなプロパティとTurboModuleメソッドがサポートされています。これらは、デフォルトの動作が適さない特殊なケースを定義するために使用できます。
• 専用のフォーカスコンポーネント： 場合によっては、デフォルトのデカルト動作とは体系的に異なる動作が必要になることがあります（たとえば、よく使用されるものにTVFocusGuideViewがあります）。このセクションには、Vegaでサポートされているカスタムコンポーネント（TVFocusGuideViewを含む）の一覧が含まれています。

​

フォーカスプロパティとメソッド

• nextFocusUp
• nextFocusDown
• nextFocusLeft
• nextFocusRight

• 値をundefinedに設定すると、指定した方向のボタンを押したときのデフォルトのデカルト動作が再び有効になります。
• 命令型APIを使用する場合は、FocusManager``TurboModuleに、フォーカスプロパティと同じ動作をする関数が用意されています。フォーカスがコンポーネントまたはその子から離れないようにするsetFocusRootAPIもあります。詳細については、Focus Manager（英語のみ）を参照してください。

const useNodeHandle = (ref) => {
  <number | null>const [ノードハンドル、セットノードハンドル] = React.useState (null);
  React.useEffect(() => {
    if (ref.current) {
      setNodeHandle(findNodeHandle(ref.current));
    }
  }, [ref.current]);
  return nodeHandle;
};

const focusableComponent = () => {
  const ref1 = React.useRef(null);
  const ref2 = React.useRef(null);
  const ref3 = React.useRef(null);

  const ref1Handle = useNodeHandle(ref1);
  const ref2Handle = useNodeHandle(ref2);
  const ref3Handle = useNodeHandle(ref3);

  // フォーカス可能な3つのコンポーネントで、一部またはすべての方向に対する
  // オーバーライドを定義します。次のフォーカスを同じコンポーネントに設定する
  // オーバーライドは、実質的にボタンの押下をブロックします。コンポーネントで
  // 方向が明示的に宣言されていないかundefinedに設定されている場合は、
  // フォールバック動作としてデカルトフォーカス戦略が実行されます。
  return (
          <View>
            <TouchableOpacity
                    ref={ref1}
                    onPress={() => {}}
                    // 「上」の押下をブロックします。
                    nextFocusUp={ref1Handle || undefined}
                    // 「右」の押下をブロックします。
                    nextFocusRight={ref1Handle || undefined}
                    // 「左」を押したときに、コンポーネント2に明示的にフォーカスを設定します。
                    nextFocusLeft={ref2Handle || undefined}
                    // 「下」を押したときに、コンポーネント3に明示的にフォーカスを設定します。
                    次のフォーカスダウン = {ref3</TouchableOpacity> ハンドル || 未定義} > コンポーネント 1
            <TouchableOpacity
                    ref={ref2}
                    onPress={() => {}}
                    // 「右」を押したときに、コンポーネント1に明示的にフォーカスを設定します。
                    次のフォーカス (右) = {ref1 ハンドル || 未定義</TouchableOpacity>} > コンポーネント 2
            <TouchableOpacity
                    ref={ref3}
                    onPress={() => {}}
                    // 「上」を押したときに、コンポーネント1に明示的にフォーカスを設定します。
                    次のフォーカスアップ = {ref1</TouchableOpacity> ハンドル || 未定義} > コンポーネント 3
          </View>
  );
};

​

FocusManagerターボモジュール

• setNextFocus() -
• clearNextFocus() -
• setFocusRoot()
• focus() -
• blur()
• getFocused()

​

専用のフォーカスコンポーネント

​

TVFocusGuideView

​

同期フォーカスイベントのディスパッチ

• アプリがフォーカスを受け取ったときにアイテムのzIndexを更新すると、zIndexの変更により、アイテムの削除と再挿入が行われます。その結果、アイテムのフォーカスが解除され、フォーカスが失われます。別の状況では、アイテムが<TVFocusGuideView>の内部に配置されている場合、フォーカスが失われる代わりに、TVFocusGuideによって最初の子にフォーカスが復元されます。

​

アプリで同期フォーカスを有効にする必要がある場合

• フォーカスが<TVFocusGuideVIew/>内の最初のアイテムにリセットされる問題が発生している。
• 固有のUI要件により、アイテムへのフォーカスの設定または解除に伴うすべての問題を、フォーカスが別のアイテムに移動する前に厳密に適用する必要がある。

• 使用はできるだけ最小限に抑えます。
• 不要な再レンダリングを避けるために、アプリを最適化し、アプリのパフォーマンスに関するベストプラクティスに従う必要があります。
• onFocus()とはonBlur()できるだけ軽量に保ち、UIスレッドが必要以上に長くブロックされないようにします。

​

既知の影響と解決策

​

キーをすばやく連打すると長いアニメーションがスキップされる

​

不要な再レンダリングによりアプリで遅延が発生する

​

フォーカスイベントまたはフォーカス解除イベントのディスパッチ時に進行中のアニメーションでフレーム落ちが発生する

​

同期フォーカスイベントを有効にする方法

• が true enableSynchronousFocusEventsVega に設定されている場合。アプリのonFocus()とonBlur()の実装内では、フォーカスをプログラムによって変更するメソッドを呼び出さないようにする必要があります。このようなメソッドには以下が含まれます。
  • requestTVFocus()
  • FocusManager.Focus()および.Blur()
  • ref.focus()およびref.blur()
• enableSynchronousFocusEventsVega最初のレンダリング後にの値を変更しないでください。
• enableSynchronousFocusEventsVega共通の親コンテナで値の異なるコンポーネントを混在させることはお勧めしません。 たとえば、コンポーネントの enableSynchronousFocusEventsVega for の使用法が混在するような次のようなパターンは避けてください。

<View>
  <Pressable enableSynchronousFocusEventsVega>
  <Pressable >
  <Pressable enableSynchronousFocusEventsVega>
<View>

<PageContainer>
  <Navbar>
    <TouchableOpacity enableSynchronousFocusEventsVega>
    <TouchableOpacity enableSynchronousFocusEventsVega>
  </Navbar>
  <HomeContent>
    <Pressable >
    <Pressable >
  </HomeContent>
</PageContainer>

<View
   focusable
   enableSynchronousFocusEventsVega
   onFocus={() => { console.log('view-onfocus'); }}
   onBlur={()=> { console.log('view-onBlur');}}
>
   <Text>
       {`onBlur/onFocusを同期的に受け取るViewを作成するサンプル`}
   </Text>
</View>

<TouchableOpacity
   enableSynchronousFocusEventsVega
   onPress={() => { console.log("touchableOpacity-pressed"); }}
   onFocus={() => { console.log('touchableOpacity-onfocus'); }}
   onBlur={()=> { console.log('touchableOpacity-onBlur'); }}
>
   <Text>
       {`onBlur/onFocusを同期的に受け取るTouchableOpacityを作成するサンプル`}
   </Text>
</TouchableOpacity>

​

マルチスクリーンでのフォーカスに関するベストプラクティス

​

react-native、react-native-tvos、react-native-kepler

​

関連トピック

• Vega TV Interfacesサンプルアプリ
• AI 用 Amazon デバイスビルダーツールを使ってみる