as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
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和用户界面缩放挂钩。

开始使用

安装

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(useScaledSizeuseScalingMultipliergetScaledSizegetScalingMultiplier)支持与密度无关的像素 (DIP) 以及物理像素这两类输入,具体取决于使用输入的应用是否在其react-native.config.js中启用了PLATFORM_DENSITY_INDEPENDENT_PIXEL运行时功能标记。

  • 启用了DIP (PLATFORM_DENSITY_INDEPENDENT_PIXEL: true): 传递给缩放API的大小值应以与密度无关的像素为单位。
  • 未启用DIP: 大小值应以物理像素为单位。

API参考

接口

类型别名

函数

变量


Last updated: 2026年7月22日