亚马逊Input SDK
利用亚马逊Input SDK,您可以向用户显示帮助对话框,解释如何用键盘和鼠标使用应用。那些通常不用键盘和鼠标与应用交互的用户将通过这项功能,获得愉悦而有益的体验。在遵照本指南之前,请确保您已在应用中启用键盘和鼠标支持。如果在为应用添加键盘和鼠标支持时需要帮助,请参阅Windows兼容性指南中的输入控件。
如果您在使用Unity,请参阅适用于Unity的亚马逊Input SDK。
要求
亚马逊Input SDK要求Android SDK版本为API级别19或更高。
将Input SDK添加到您的项目
此处可下载亚马逊Input SDK。
下载的内容中包括AAR文件、Javadocs和一个示例应用。
选项1: 手动添加SDK
要将亚马逊Input SDK添加到您的项目中,请使用以下步骤将AAR文件作为库导入。
- 在Android Studio中打开您的项目。使用Project文件夹结构视图。
- 如果app文件夹下不存在libs文件夹,则创建一个。将AAR文件复制到app/libs文件夹中。
- 右键单击Project文件夹,然后选择Open Module Settings(打开模块设置)。
- 在侧栏上,单击Dependencies(依赖关系),然后选择应用程序模块(或等效模块)。
- 单击Declared Dependencies(已声明依赖项)下的加号,并提供SDK AAR位置的路径:libs/inputmapping-[x].aar这样会自动将依赖项添加到build.gradle文件。
- 单击OK(确定)。
-
验证依赖项是否已添加至应用级别build.gradle文件,如该示例中所示。
dependencies { implementation files('libs/inputmapping-1.0.1.aar') }
- 将以下两个依赖项添加到应用级别build.gradle文件中:
implementation 'com.android.support.constraint:constraint-layout:2.0.4' implementation 'com.android.support:recyclerview-v7:28.0.0'
选项2: 使用Maven Central添加SDK
- 将亚马逊Input SDK添加到应用级别build.gradle文件的依赖项部分,如下所示。
dependencies {
...
implementation 'com.amazon.device.inputmapping:inputmapping:1.0.1'
}
- 请确保项目的顶级build.gradle文件已定义Maven Central存储库,否则请按以下方式添加它:
allprojects {
repositories {
mavenCentral()
}
dependencies {
...
}
}
创建输入映射
通过亚马逊Input SDK,您可以将关键事件和鼠标点击映射到输入操作,将这些操作划分到输入组中,并从输入组创建输入映射,如下图所示。
定义输入操作
输入操作是与应用操作对应的事件。输入操作可以映射到一个键或键的组合。在以下示例中,Jump(跳跃)操作映射到空格键,Move(移动)操作映射为鼠标移动。
InputAction jumpInputAction = InputAction.create(
"Jump",
MyGameActions.JUMP, //此处MyGameActions是游戏中的枚举
InputControls.create(
Collections.singletonList(KeyEvent.KEYCODE_SPACE),
Collections.emptyList()
)
);
InputAction cmbMove = InputAction.create(
"Move",
MyGameActions.MOVE,
InputControls.create(
Collections.emptyList(),
Collections.singletonList(InputControls.MOUSE_MOVEMENT)
)
);
val jumpInputAction = InputAction.create(
"Jump",
MyGameActions.JUMP.ordinal, // 此处的MyGameActions是游戏中的枚举
InputControls.create(
listOf(KeyEvent.KEYCODE_SPACE),
emptyList()
)
)
val move = InputAction.create(
"移动",
MyGameActions.MOVE.ordinal,
InputControls.create(
emptyList(),
listOf(InputControls.MOUSE_MOVEMENT)
)
)
示例中使用的Input SDK方法:
InputAction.create(String actionLabel, int uniqueId, InputControls inputControls)
- 注意事项:
- 对于
uniqueId
,使用枚举。
- 对于
- 注意事项:
InputControls.create(List<Integer> keyboardActions, List<Integer> mouseActions)
- 注意事项:
- 对于
keyboardActions
,使用Android框架KeyEvent
类中的键码常量。 - 对于
mouseActions
,使用亚马逊Input SDKInputControls
类中的常量。
- 对于
- 注意事项:
定义输入组
输入组是由多个输入操作组成的一组。输入组具有组标签和属于该组的一系列输入操作。每个InputAction
必须与InputGroup
关联。以下示例显示了使用上一节中定义的输入操作创建的Basic Movement(基本移动)输入组。
InputGroup movementInputGroup = InputGroup.create("Basic Movement",
Arrays.asList(jumpInputAction, move));
var movementGroup = InputGroup.create("Basic Movement",
listOf(move, jumpInputAction)
)
示例中使用的Input SDK方法:
InputGroup.create(String groupName, List<InputAction> actions)
构建输入映射
输入映射是应用的输入组的集合。输入映射还包含适用于应用的鼠标设置。在定义了所有输入操作并将它们划分到输入组之后,如本例所示创建输入映射。
return InputMap.create(
Arrays.asList(movementInputGroup, specialInputGroup),
MouseSettings.create(true, true));
return InputMap.create(
listOf(moveGroup, gameControls),
MouseSettings.create(true, true)
)
示例中使用的Input SDK方法:
InputMap.create(List<InputGroup> inputGroups, MouseSettings mouseSettings)
MouseSettings.create(boolean adjustableSensitivity, boolean invertedYAxis)
创建输入映射提供方
要根据请求提供输入映射,请实现InputMappingProvider
接口。当用户请求帮助屏幕时,亚马逊Input SDK会引用输入映射提供方。
public class CustomInputMapProvider implements InputMappingProvider {
@Override
public InputMap onProvideInputMap() {
//返回输入映射
}
}
class CustomInputMapProvider: InputMappingProvider {
override fun onProvideInputMap(): InputMap {
//返回输入映射
}
}
注册输入映射提供方
一次只能有一个有效的输入映射。当用户访问帮助屏幕时,会向他们显示当前有效的输入映射。通过input静态类将输入映射提供方注册为有效输入映射提供方,如以下示例所示。
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
inputMappingClient.setInputMappingProvider(new CustomInputMapProvider());
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val inputMappingClient = Input.getInputMappingClient(this)
inputMappingClient.inputMappingProvider = CustomInputMapProvider();
}
有效输入映射提供方在各类活动中保持不变,不受生命周期事件的影响。但是,您可以使用InputMappingClient
并设置不同的输入映射提供方来更改有效的输入映射。
显示帮助屏幕
要显示帮助屏幕,亚马逊应用商店建议向用户显示一个视觉元素,在单击该元素时会打开帮助屏幕。您可以将视觉指示器放置在游戏窗口中,也可以放置在单独的屏幕中,例如首选项或控件页面。使用TriggerHandler.showHelp()
方法显示帮助屏幕,如以下所示。
TriggerHandler.getInstance().showHelp(this, "My App");
TriggerHandler.getInstance().showHelp(this, "My App");
亚马逊Input SDK的API参考
浏览本节,了解有关亚马逊Input SDK中一些API的介绍。有关完整的API参考,请参阅亚马逊Input SDK API参考。
InputControls
InputControls.create(List<Integer> keyboardActions, List<Integer> mouseActions)
InputControls
对象包含一系列键盘操作和一系列鼠标操作。该对象使用静态方法InputControls.create()
创建。
InputControls.create()
方法返回新的InputControls
对象。使用InputControls
对象创建InputAction
。
InputAction
InputAction.create(String actionLabel, int uniqueId, InputControls inputControls)
InputAction
对象包含标签、唯一的ID和InputControls
对象。该对象使用静态方法InputAction.create()
创建。
InputAction.create()
方法返回新的InputAction
对象。使用InputAction
对象创建InputGroup
。
InputGroup
InputGroup.create(String groupName, List<InputAction> actions)
InputGroup
对象包含名称和一系列InputAction
对象。该对象使用静态方法InputGroup.create()
创建。
InputGroup.create()
方法返回新的InputGroup
对象。将InputGroup
结合MouseSettings
使用,创建InputMap
。
MouseSettings
MouseSettings.create(boolean adjustableSensitivity, boolean invertedYAxis)
MouseSettings
对象包含可调整灵敏度和反转y轴的布尔值鼠标设置。该对象使用静态方法MouseSettings.create()
创建。
MouseSettings.create()
方法返回新的MouseSettings
对象。将MouseSettings
结合InputGroup
使用,创建InputMap
。
InputMap
InputMap.create(List<InputGroup> inputGroups, MouseSettings mouseSettings)
InputMap
对象包含一系列InputGroup
对象,以及一个MouseSettings
对象。该对象使用静态方法InputMap.create()
创建。
InputMap.create()
方法返回新的InputMap
对象。从您的InputMappingProvider
实现返回InputMap
。
InputMappingProvider
InputMappingProvider
接口提供onProvideInputMap()
方法。在您的实现中,覆盖该方法以返回InputMap
。当用户访问帮助屏幕时,将显示InputMap
数据。
InputMappingClient
InputMappingClient
可让您管理InputMappingProvider
并提供以下方法:
setInputMappingProvider(InputMappingProvider inputMappingProvider)
:将InputMappingProvider
分配至InputMappingClient
的该实例。clearInputMappingProvider()
:删除当前分配的InputMappingProvider
并使其为null。getInputMappingProvider()
:返回当前分配的InputMappingProvider
。
Input
该类用于实例化InputMappingClient
并提供以下方法:
getInputMappingClient(Activity activity)
:返回InputMappingClient
的singleton实例。
TriggerHandler
该类提供一个显示帮助对话框的方法,并包含以下方法:
getInstance()
:返回TriggerHandler
的singleton实例。showHelp(Activity activity, String title)
:显示输入帮助对话框。使用来自注册的InputMap
的数据来填写对话框。使用以下参数。activity
- 包含帮助对话框的活动。title
- 要在对话框上显示的应用程序的标题
showHelp(Activity activity, String title, UIMode uiMode)
:显示具有指定主题(浅色或深色)的输入帮助对话框。使用以下参数。activity
- 包含帮助对话框的活动。title
- 要在对话框上显示的应用程序的标题uiMode
- 主题设置,有效值为UIMode.AUTO
、UIMode.LIGHT
、UIMode.DARK
setUiMode(UIMode uiMode)
:设置对话框的主题。使用以下参数。uiMode
- 主题设置,有效值为UIMode.AUTO
、UIMode.LIGHT
、UIMode.DARK
UIMode
这是一个枚举,定义可用于设置帮助对话框主题的常量。常量包括:
AUTO
- 沿用系统主题DARK
- 使用深色主题LIGHT
- 使用浅色主题
Last updated: 2024年3月5日