Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases
開発
設計と開発
公開
リファレンス
サポート

@amazon-devices/kepler-a11y-settings-interface-turbo

@amazon-devices/kepler-a11y-settings-interface-turbo

概要

@amazon-devices/kepler-a11y-settings-interface-turboは、Keplerアプリ向けにユーザー補助機能の設定APIとUIスケーリング用のフックを提供します。

開始の手順

インストール

package.jsonファイルに、依存関係として@amazon-devices/kepler-a11y-settings-interface-turboパッケージを追加します。

コマンドラインから以下を実行します。

クリップボードにコピーしました。

npm install @amazon-devices/kepler-a11y-settings-interface-turbo

または、次に示すようにpackage.jsonファイルを手動で編集することもできます。

クリップボードにコピーしました。

"dependencies": {
  ...
  "@amazon-devices/kepler-a11y-settings-interface-turbo": "~1.0.0", // または最新のメジャーバージョン
  ...
}

次に、npm installを実行します。

使用方法

設定のゲッター、セッター、リスナー

設定の読み取り

現在のユーザー補助機能の設定を照会するには、KeplerA11ySettingsInterfaceを使用します。すべてのゲッターメソッドはPromiseを返します。

クリップボードにコピーしました。

import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';

// 現在の設定を取得します(ゲッターメソッドはPromiseを返します)
KeplerA11ySettingsInterface.isScreenReaderEnabled().then(isEnabled => {
  console.log('スクリーンリーダーの有効状態:', isEnabled);
});

KeplerA11ySettingsInterface.getUiScaleSetting().then(scale => {
  console.log('現在のUIスケール:', scale);
});

KeplerA11ySettingsInterface.getColorCorrectionMode().then(mode => {
  console.log('色補正モード:', mode);
});

KeplerA11ySettingsInterface.getCaptionPreferences().then(captionPrefs => {
  console.log('現在の字幕の設定:', captionPrefs);
});

変化のリッスン

ユーザー補助機能の設定の変更に対応するリスナーを追加します。リスナーの登録メソッドと削除メソッドは非同期でPromiseを返します。

クリップボードにコピーしました。

import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';

// スクリーンリーダーの状態の変化をリッスンします
const handleScreenReaderChange = (enabled: boolean) => {
  console.log(`スクリーンリーダーは${enabled ? '有効' : '無効'}`);
  // スクリーンリーダーの状態に応答します
};

const success = await KeplerA11ySettingsInterface.addScreenReaderStateListener(handleScreenReaderChange);
if (!success) {
  console.warn('スクリーンリーダーのリスナーの登録に失敗しました');
}

// コンポーネントがアンマウントされたら、必ずリスナーを削除します
await KeplerA11ySettingsInterface.removeScreenReaderStateListener();

設定の書き込み(システムアプリのみ)

セッターメソッドには、システムアプリ専用のcom.amazon.devconf.privilege.accessibility.writeパーミッションが必要です。サードパーティ製アプリはこのパーミッションを宣言することができません。

クリップボードにコピーしました。

import KeplerA11ySettingsInterface, { CaptioningProps } from '@amazon-devices/kepler-a11y-settings-interface-turbo';

await KeplerA11ySettingsInterface.setScreenReaderEnabled(true);
await KeplerA11ySettingsInterface.setUiScaleSetting(3);
await KeplerA11ySettingsInterface.setColorCorrectionMode('deuteranomaly');

const newPrefs: CaptioningProps = {
  textSize: 'large',
  textColor: 'white',
  textFont: 'sans_serif',
  textEdgeStyle: 'drop_shadowed',
  textOpacity: 'percent_100'
};

await KeplerA11ySettingsInterface.setCaptionPreferences(newPrefs);

UIスケール設定のフック

動的スケーリング用のReactフック

提供されているフックを使用して、スケール設定の変更に自動的に適応するレスポンシブなUIを作成します。これらのフックは、関連するUI要素をスケーリングする必要がある場合に、UIサイズが定義されている場所で必要です。

既にこれらのフックで事前定義されたサイズをラップしているUI要素を使用している場合は、アプリ定義をUiScaleSettingContextProviderでラップするだけで済みます。

アプリ開発者は、アプリに組み込まれたUI要素のサイズが変化しても、アプリがそれを適切に処理できるようにする責任があります。たとえば、アプリ開発者は、デフォルトのスケールでは不要であっても、コンテナをスクロール可能にしたり、テキストコンポーネントにオーバーフロー動作を定義しておくことが必要になる場合があります。

クリップボードにコピーしました。

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { 
  UiScaleSettingContextProvider, 
  useScaledSize, 
  useScalingMultiplier,
  useUiScaleSetting 
} from '@amazon-devices/kepler-a11y-settings-interface-turbo';

const CONTENT_WIDTH_DEFAULT_BASE = 144;
const CONTENT_HEIGHT_DEFAULT_BASE = 80;
const LOGO_DEFAULT_WIDTH = 57;
const LOGO_DEFAULT_HEIGHT = 24;

const styles = StyleSheet.create({
  viewStyle: {
    marginLeft: 8,
    alignItems: 'center',
    zIndex: 0,
  },
  text: {
    fontSize: 14,
    color: '#666',
    fontFamily: 'sans-serif',
  },
});

const App = () => {
  // スケール設定の変更に応じて自動的に更新されるスケール済みの寸法を取得します
  const contentWidthDefault = useScaledSize(CONTENT_WIDTH_DEFAULT_BASE, { 
    itemType: 'medium_upscale' 
  });
  const contentHeightDefault = useScaledSize(CONTENT_HEIGHT_DEFAULT_BASE, { 
    itemType: 'medium_upscale' 
  });
  
  // 関連する寸法に適用するスケーリング倍率を取得します
  const assetScalingMultiplier = useScalingMultiplier(LOGO_DEFAULT_WIDTH, { 
    itemType: 'image' 
  });

  // スタイルシートをメモ化して、contentWidthDefaultまたはcontentHeightDefaultが
  // useScaledSizeフックによって変更された場合にのみ更新されるようにします。
  const viewStyle = React.useMemo(
    () => ({
      ...styles.viewStyle,
      width: contentWidthDefault,
      height: contentHeightDefault,
    }),
    [contentWidthDefault, contentHeightDefault],
  );

  // スタイルシートをメモ化して、assetScalingMultiplierが
  // useScalingMultiplierフックによって変更された場合にのみ更新されるようにします。
  const assetStyle = React.useMemo(
    () => ({
      width: LOGO_DEFAULT_WIDTH * assetScalingMultiplier,
      height: LOGO_DEFAULT_HEIGHT * assetScalingMultiplier,
      marginRight: 12,
    }),
    [assetScalingMultiplier],
  );

  // 下で表示する現在のスケール係数を取得します
  const currentScale = useUiScaleSetting();

  return (
    <View style={viewStyle}>
      <Image style={assetStyle} source={logoSource} />
      <Text style={styles.text}>Current scale: {currentScale}</Text>
    </View>
  );
};

// アプリをプロバイダーでラップします。 これにより、useScaledSizeフックと
// useScalingMultiplierフックを利用するすべてのUI要素が、UiScaleSettingの設定変更に
// 動的に応答するようになります。これは、UI要素が別のライブラリからインポートされている
// 場合でも同様です。
const AppWithProvider = () => (
  <UiScaleSettingContextProvider>
    <App />
  </UiScaleSettingContextProvider>
);

export default AppWithProvider;

スケーリングタイプ

このライブラリは、さまざまなUI要素の異なるスケーリング動作をサポートしています。

  • 'low_upscale' - スケーリングが最小限の大型のアイテム(カードなど)
  • 'medium_upscale' - 中程度にスケーリングされる標準的なUI要素
  • 'large_upscale' - 大幅なスケーリングが必要な小型の要素(ボタンなど)
  • 'low_downscale' - スケール設定が大きくなると減少する空白
  • 'large_downscale' - スケール設定が大きくなると大幅に減少する大きいパディング
  • 'text' - 対応する行間もスケーリングされるテキスト要素
  • 'image' - 画像とビジュアルアセット

高度なスケーリングオプション

オプションのパラメーターを使用してスケーリング制限を制御します。

クリップボードにコピーしました。

const scaledWidth = useScaledSize(100, {
  itemType: 'medium_upscale',
  maxSize: 200,  // 200ユニットを超えないようにします
  minSize: 50    // 50ユニットを下回らないようにします
});

密度非依存ピクセル(DIP)

スケーリングAPI(useScaledSizeuseScalingMultipliergetScaledSizegetScalingMultiplier)は、アプリがreact-native.config.js内でPLATFORM_DENSITY_INDEPENDENT_PIXELランタイム機能フラグを有効にしているかどうかに応じて、密度非依存ピクセル(DIP)入力と物理解像度ピクセル入力の両方をサポートします。

  • DIPが有効の場合PLATFORM_DENSITY_INDEPENDENT_PIXEL: true): スケーリングAPIに渡すサイズ値は密度非依存ピクセルで指定する必要があります。
  • DIPが有効ではない場合: サイズ値は物理解像度ピクセルで指定する必要があります。

APIリファレンス

クラス

インターフェイス

型エイリアス

  • CaptionColor - 字幕の色の値。
  • CaptionEdgeStyle - 字幕のエッジスタイルの値。
  • CaptionFont - 字幕のフォントの値。
  • CaptionOpacity - 字幕の不透明度の値。
  • CaptionTextSize - 字幕のテキストサイズの値。
  • ColorCorrectionMode - 色覚特性に対応するための色補正モード。
  • ItemScalingType - スケーリングできるアイテムのタイプ。オブジェクトのタイプが異なれば、拡大縮小率も異なります。
  • TimeoutMultiplier - タイムアウト時間を調整するためのタイムアウト乗数値。
  • UiScaleSetting - この列挙型は、アプリとUIフレームワークのスケール設定を定義します。

関数

  • UiScaleSettingContextProvider - UIスケール設定コンテキストを子コンポーネントに提供するプロバイダーコンポーネント。
  • useScaledSize - 元のサイズとスケーリングプロパティに基づいて、UIのスケーリングされたサイズ値を取得するためのフック。
  • useScalingMultiplier - 元のサイズとスケーリングプロパティに基づいて、UIのスケーリング倍率の値を取得するためのフック。
  • useUiScaleSetting - 現在のUIスケール設定にアクセスするためのフック。
  • useUiScaleSettingLoading - UIスケール設定を取得中かどうかを確認するためのフック。

変数

  • SCALING_PROP_IMAGE_TYPE - maxSize/minSizeが不要な場合の画像スケーリングに便利なScalingPropsオブジェクト
  • SCALING_PROP_LARGE_DOWNSCALE_TYPE - maxSize/minSizeが不要な場合に、縮小率の大きなアイテムとして便利なScalingPropsオブジェクト
  • SCALING_PROP_LARGE_UPSCALE_TYPE - maxSize/minSizeが不要な場合に、拡大率の大きなアイテムとして便利なScalingPropsオブジェクト
  • SCALING_PROP_LOW_DOWNSCALE_TYPE - maxSize/minSizeが不要な場合に、縮小率の小さなアイテムとして便利なScalingPropsオブジェクト
  • SCALING_PROP_LOW_UPSCALE_TYPE - maxSize/minSizeが不要な場合に、拡大率の小さなアイテムとして便利なScalingPropsオブジェクト
  • SCALING_PROP_MEDIUM_UPSCALE_TYPE - maxSize/minSizeが不要な場合に、中程度の拡大率のアイテムとして便利なScalingPropsオブジェクト
  • SCALING_PROP_TEXT_TYPE - maxSize/minSizeが不要な場合に、テキストのスケーリング(拡大・縮小)に便利なScalingPropsオブジェクト
  • UiScaleSettingMode - 公開されているレベル名から数値のUiScaleSetting値へのマッピング

Last updated: 2026年7月22日