开发者控制台
登录
登录
开发者控制台

亚马逊Input SDK

亚马逊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文件作为库导入。

  1. 在Android Studio中打开您的项目。使用Project文件夹结构视图。
  2. 如果app文件夹下不存在libs文件夹，则创建一个。将AAR文件复制到app/libs文件夹中。
  3. 右键单击Project文件夹，然后选择Open Module Settings（打开模块设置）。
  4. 在侧栏上，单击Dependencies（依赖关系），然后选择应用程序模块（或等效模块）。
  5. 单击Declared Dependencies（已声明依赖项）下的加号，并提供SDK AAR位置的路径：libs/inputmapping-[x].aar这样会自动将依赖项添加到build.gradle文件。
  6. 单击OK（确定）。​

  7. 验证依赖项是否已添加至应用级别build.gradle文件，如该示例中所示。

     dependencies {
     implementation files('libs/inputmapping-1.0.1.aar')
 }
  8. 将以下两个依赖项添加到应用级别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

  1. 将亚马逊Input SDK添加到应用级别build.gradle文件的依赖项部分，如下所示。
  dependencies {
      ...
      implementation 'com.amazon.device.inputmapping:inputmapping:1.0.1'
  }
  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 SDK InputControls类中的常量。

定义输入组

输入组是由多个输入操作组成的一组。输入组具有组标签和属于该组的一系列输入操作。每个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日