@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(useScaledSize、useScalingMultiplier、getScaledSize、getScalingMultiplier)は、アプリがreact-native.config.js内でPLATFORM_DENSITY_INDEPENDENT_PIXELランタイム機能フラグを有効にしているかどうかに応じて、密度非依存ピクセル(DIP)入力と物理解像度ピクセル入力の両方をサポートします。
- DIPが有効の場合(
PLATFORM_DENSITY_INDEPENDENT_PIXEL: true): スケーリングAPIに渡すサイズ値は密度非依存ピクセルで指定する必要があります。 - DIPが有効ではない場合: サイズ値は物理解像度ピクセルで指定する必要があります。
APIリファレンス
クラス
インターフェイス
- CaptioningProps - 字幕サポートの設定を説明する字幕サポートプロパティ。
- KeplerA11ySettingsInterfaceTurbo
- ScalingProps - スケーリングされるアイテムを説明するスケーリングプロパティ。
型エイリアス
- 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日

