@amazon-devices/kepler-a11y-settings-interface-turbo
概览
@amazon-devices/kepler-a11y-settings-interface-turbo为Kepler应用提供无障碍功能设置API和用户界面缩放挂钩。
开始使用
安装
在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", // or latest major version
...
}
然后运行npm install。
用法
设置的Getter方法、Setter方法和侦听器
读取设置
使用KeplerA11ySettingsInterface查询当前无障碍功能设置。所有Getter方法都会返回Promise。
import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';
// 获取当前设置(Getter方法会返回Promise)
KeplerA11ySettingsInterface.isScreenReaderEnabled().then(isEnabled => {
console.log('屏幕阅读器已启用:', isEnabled);
});
KeplerA11ySettingsInterface.getUiScaleSetting().then(scale => {
console.log('当前用户界面缩放比例:', 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();
写入设置(仅限系统应用)
Setter方法需要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);
用户界面缩放设置挂钩
用于动态缩放的React挂钩
使用提供的挂钩创建可自动适应缩放设置更改的响应式用户界面。定义用户界面大小时,必须使用这些挂钩来处理关联用户界面元素应缩放的情况。
如果您使用的用户界面元素已经使用这些挂钩封装了底层预定义大小,那么只需将应用定义封装在UiScaleSettingContextProvider中即可。
应用开发者有责任确保其应用能够妥善处理所载入用户界面元素的大小变化。例如,应用开发者可能需要确保容器可滚动,或是确保定义了文本组件的溢出行为,即使在默认缩放比例下这些属性并非必需。
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'
});
// 记忆样式表,使其仅在通过useScaledSize挂钩更改
// contentWidthDefault或contentHeightDeafault时更新。
const viewStyle = React.useMemo(
() => ({
...styles.viewStyle,
width: contentWidthDefault,
height: contentHeightDefault,
}),
[contentWidthDefault, contentHeightDefault],
);
// 记忆样式表,使其仅在通过useScalingMultiplier挂钩
// 更改assetScalingMultiplier时更新。
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挂钩来动态响应
// UiScaleSetting设置更改,即使用户界面元素是从另一个
// 库导入的。
const AppWithProvider = () => (
<UiScaleSettingContextProvider>
<App />
</UiScaleSettingContextProvider>
);
export default AppWithProvider;
缩放类型
该库支持各种用户界面元素的不同缩放行为:
'low_upscale'- 尽可能小幅放大的大尺寸项目(例如卡片)'medium_upscale'- 缩放比例适中的标准用户界面元素'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)支持与密度无关的像素 (DIP) 以及物理像素这两类输入,具体取决于使用输入的应用是否在其react-native.config.js中启用了PLATFORM_DENSITY_INDEPENDENT_PIXEL运行时功能标记。
- 启用了DIP (
PLATFORM_DENSITY_INDEPENDENT_PIXEL: true): 传递给缩放API的大小值应以与密度无关的像素为单位。 - 未启用DIP: 大小值应以物理像素为单位。
API参考
类
接口
- CaptioningProps — 字幕属性,用于描述字幕首选项。
- KeplerA11ySettingsInterfaceTurbo
- ScalingProps — 缩放属性,用于描述要缩放的项目。
类型别名
- CaptionColor — 字幕的颜色值。
- CaptionEdgeStyle — 字幕的边缘样式值。
- CaptionFont — 字幕的字体值。
- CaptionOpacity — 字幕的不透明度值。
- CaptionTextSize — 字幕的文本大小值。
- ColorCorrectionMode — 用于解决色觉缺陷问题的色彩校正模式。
- ItemScalingType — 可缩放的项目类型。不同类型的对象以不同速率缩放。
- TimeoutMultiplier — 用于调整超时持续时间的超时系数。
- UiScaleSetting — 此枚举定义了应用和用户界面框架的缩放设置
函数
- UiScaleSettingContextProvider — 提供程序组件,为子组件提供用户界面缩放设置上下文
- useScaledSize — 挂钩,用于根据原始大小和缩放属性检索用户界面缩放后大小值。
- useScalingMultiplier — 用于根据原始大小和缩放属性检索用户界面缩放系数值的挂钩。
- useUiScaleSetting — 用于访问当前用户界面缩放设置的挂钩。
- useUiScaleSettingLoading — 用于检查应用是否仍在获取用户界面缩放设置的挂钩。
变量
- 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日

