Module java.desktop
Package java.awt

Class Robot

java.lang.Object
java.awt.Robot
public class Robot extends Object
这个类用于生成原生系统输入事件，用于测试自动化、自运行演示和其他需要控制鼠标和键盘的应用程序。Robot的主要目的是促进对Java平台实现的自动化测试。

使用该类生成输入事件与将事件发布到AWT事件队列或AWT组件不同，因为事件是在平台的原生输入队列中生成的。例如，Robot.mouseMove实际上会移动鼠标光标，而不仅仅是生成鼠标移动事件。

请注意，一些平台需要特殊权限或扩展来访问低级输入控制。如果当前平台配置不允许输入控制，则在尝试构造Robot对象时将抛出AWTException异常。例如，如果X-Window系统不支持（或未启用）XTEST 2.2标准扩展，则会抛出异常。

除了自我测试之外，使用Robot的应用程序应该优雅地处理这些错误条件。

平台和桌面环境可能对Robot类中所需的访问权限施加限制或限制。例如：

  • 阻止访问桌面的任何部分或桌面上不属于运行应用程序的窗口的内容。
  • 将窗口装饰视为非所有者内容。
  • 忽略或限制特定请求以操作窗口。
  • 忽略或限制与键盘和鼠标等Robot生成的（合成的）事件相关的特定请求。
  • 要求对窗口内容的任何访问或甚至对事件的有限合成具有特定或全局权限。
Robot API规范要求对这些内容进行批准以实现完全操作。如果未获得批准，API将会降级，如本文所述。相关的特定API方法可能会记录更具体的限制和要求。根据桌面环境的政策，上述批准可能会：
  • 每次都需要
  • 或在应用程序的生命周期内持久
  • 或在多个用户桌面会话中持久
  • 是细粒度的权限
  • 与特定二进制应用程序或一类二进制应用程序相关联。
当需要交互地给出这些批准时，可能会妨碍应用程序的正常运行，如果批准被拒绝或不可能，或无法持久化，则会降低该类的功能性，进而影响依赖于它的应用程序操作的任何部分。
自JDK版本:
1.3

  • Constructor Details

  • Method Details

    • mouseMove

      public void mouseMove(int x, int y)
      将鼠标指针移动到给定的屏幕坐标。

      在某些平台上，鼠标指针可能不会在视觉上移动，而后续的mousePress和mouseRelease可以传递到正确的位置

      参数:
      x - X位置
      y - Y位置

    • mousePress

      public void mousePress(int buttons)
      按下一个或多个鼠标按钮。应使用mouseRelease(int)方法释放鼠标按钮。
      参数:
      buttons - 按钮掩码；一个或多个鼠标按钮掩码的组合。

      只允许使用有效值的组合作为buttons参数。有效组合包括InputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK和由InputEvent.getMaskForButton(button)方法返回的值。有效组合还取决于Toolkit.areExtraMouseButtonsEnabled()的值，如下所示：

      • 如果Java禁用了对扩展鼠标按钮的支持，则只允许使用以下标准按钮掩码：InputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK。
      • 如果Java启用了对扩展鼠标按钮的支持，则允许使用标准按钮掩码和现有扩展鼠标按钮的掩码，如果鼠标有超过三个按钮。这样，可以使用与范围从1到MouseInfo.getNumberOfButtons()的按钮对应的按钮掩码。
        建议使用InputEvent.getMaskForButton(button)方法通过其编号获取任何鼠标按钮的掩码。

      还接受以下标准按钮掩码：

      • InputEvent.BUTTON1_MASK
      • InputEvent.BUTTON2_MASK
      • InputEvent.BUTTON3_MASK
      但建议使用InputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK。扩展的_DOWN_MASK或旧的_MASK值应该被使用，但这两种模型不应混合使用。
      抛出:
      IllegalArgumentException - 如果buttons掩码包含额外鼠标按钮的掩码，并且Java禁用了对扩展鼠标按钮的支持
      IllegalArgumentException - 如果buttons掩码包含鼠标上不存在的额外鼠标按钮的掩码，并且Java启用了对扩展鼠标按钮的支持
      参见:

    • mouseRelease

      public void mouseRelease(int buttons)
      释放一个或多个鼠标按钮。
      参数:
      buttons - 按钮掩码；一个或多个鼠标按钮掩码的组合。

      只允许使用有效值的组合作为buttons参数。有效组合包括InputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK和由InputEvent.getMaskForButton(button)方法返回的值。有效组合还取决于Toolkit.areExtraMouseButtonsEnabled()值如下：

      • 如果Java禁用了对扩展鼠标按钮的支持，则只允许使用以下标准按钮掩码：InputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK。
      • 如果Java启用了对扩展鼠标按钮的支持，则允许使用标准按钮掩码和现有扩展鼠标按钮的掩码，如果鼠标有超过三个按钮。这样，可以使用对应于从1到MouseInfo.getNumberOfButtons()的按钮的按钮掩码。
        建议使用InputEvent.getMaskForButton(button)方法通过其编号获取任何鼠标按钮的掩码。

      还接受以下标准按钮掩码：

      • InputEvent.BUTTON1_MASK
      • InputEvent.BUTTON2_MASK
      • InputEvent.BUTTON3_MASK
      但建议使用InputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK。扩展的_DOWN_MASK或旧的_MASK值应该被使用，但这两种模式不应混合使用。
      抛出:
      IllegalArgumentException - 如果buttons掩码包含额外鼠标按钮的掩码，并且Java禁用了对扩展鼠标按钮的支持
      IllegalArgumentException - 如果buttons掩码包含鼠标上不存在的额外鼠标按钮的掩码，并且Java启用了对扩展鼠标按钮的支持
      参见:

    • mouseWheel

      public void mouseWheel(int wheelAmt)
      旋转配备滚轮的鼠标上的滚轮。
      参数:
      wheelAmt - 移动鼠标滚轮的“凹槽”数量。负值表示向上/远离用户的移动，正值表示向下/靠近用户的移动。
      自1.4版本起:
      1.4

    • keyPress

      public void keyPress(int keycode)
      按下给定的键。应使用keyRelease方法释放该键。

      与多个物理键关联的键代码（例如KeyEvent.VK_SHIFT可能表示左或右Shift键）将映射到左键。

      参数:
      keycode - 要按下的键（例如KeyEvent.VK_A）
      抛出:
      IllegalArgumentException - 如果keycode不是有效键
      参见:

    • keyRelease

      public void keyRelease(int keycode)
      释放给定的键。

      与多个物理键关联的键代码（例如KeyEvent.VK_SHIFT可能表示左或右Shift键）将映射到左键。

      参数:
      keycode - 要释放的键（例如KeyEvent.VK_A）
      抛出:
      IllegalArgumentException - 如果keycode不是有效键
      参见:

    • getPixelColor

      public Color getPixelColor(int x, int y)
      返回给定屏幕坐标处像素的颜色。

      如果桌面环境要求授予权限以捕获屏幕内容，并且未授予所需权限，则可能会抛出SecurityException，或者返回的Color的内容未定义。

      API注释:
      建议避免在AWT事件分发线程上调用此方法，因为屏幕捕获可能是一个耗时的操作，特别是如果需要获取权限并涉及用户交互。
      参数:
      x - 像素的X位置
      y - 像素的Y位置
      返回:
      像素的颜色
      抛出:
      SecurityException - 如果未授予readDisplayPixels权限，或者桌面环境拒绝访问屏幕

    • createScreenCapture

      public BufferedImage createScreenCapture(Rectangle screenRect)
      创建包含从屏幕读取的像素的图像。

      如果桌面环境要求授予权限以捕获屏幕内容，并且未授予所需权限，则可能会抛出SecurityException，或者返回的BufferedImage的内容未定义。

      API注释:
      建议避免在AWT事件分发线程上调用此方法，因为屏幕捕获可能是一个耗时的操作，特别是如果需要获取权限并涉及用户交互。
      参数:
      screenRect - 屏幕坐标中要捕获的矩形
      返回:
      捕获的图像
      抛出:
      IllegalArgumentException - 如果screenRect的宽度和高度不大于零
      SecurityException - 如果未授予readDisplayPixels权限，或者桌面环境拒绝访问屏幕
      参见:

    • createMultiResolutionScreenCapture

      public MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)
      创建包含从屏幕读取的像素的图像。如果用户空间到屏幕（设备）空间存在缩放变换，则可以使用此方法。通常这意味着显示器是高分辨率屏幕，尽管严格来说，这意味着存在这样的变换。返回一个MultiResolutionImage。

      对于非缩放显示，MultiResolutionImage将具有一个图像变体：

      • 用户指定大小的基本图像。

      对于存在缩放变换的高分辨率显示，MultiResolutionImage将具有两个图像变体：

      • 用户指定大小的基本图像。这是从屏幕缩放的。
      • 具有设备大小像素的本机设备分辨率图像。

      示例：

      
      Image nativeResImage;
      MultiResolutionImage mrImage = robot.createMultiResolutionScreenCapture(frame.getBounds());
      List<Image> resolutionVariants = mrImage.getResolutionVariants();
      if (resolutionVariants.size() > 1) {
          nativeResImage = resolutionVariants.get(1);
      } else {
          nativeResImage = resolutionVariants.get(0);
      }
      参数:
      screenRect - 屏幕坐标中要捕获的矩形
      返回:
      捕获的图像
      抛出:
      IllegalArgumentException - 如果screenRect的宽度和高度不大于零
      SecurityException - 如果未授予readDisplayPixels权限，或者桌面环境拒绝访问屏幕
      自9版本起:
      9
      参见:

    • isAutoWaitForIdle

      public boolean isAutoWaitForIdle()
      返回此Robot在生成事件后是否自动调用waitForIdle。
      返回:
      是否自动调用waitForIdle

    • setAutoWaitForIdle

      public void setAutoWaitForIdle(boolean isOn)
      设置此Robot在生成事件后是否自动调用waitForIdle。
      参数:
      isOn - 是否自动调用waitForIdle

    • getAutoDelay

      public int getAutoDelay()
      返回此Robot在生成事件后睡眠的毫秒数。
      返回:
      毫秒为单位的延迟持续时间

    • setAutoDelay

      public void setAutoDelay(int ms)
      设置此Robot在生成事件后睡眠的毫秒数。
      参数:
      ms - 延迟持续时间（以毫秒为单位）
      抛出:
      IllegalArgumentException - 如果ms不在0到60,000毫秒（包括）之间

    • delay

      public void delay(int ms)
      休眠指定的时间。

      如果调用线程在等待时被中断，则将立即返回并设置中断状态。如果已经设置了中断状态，则此方法将立即返回并设置中断状态。

      参数:
      ms - 以毫秒为单位的休眠时间
      抛出:
      IllegalArgumentException - 如果ms不在0到60,000毫秒（包括）之间

    • waitForIdle

      public void waitForIdle()
      等待直到当前事件队列中的所有事件都被处理完毕。
      抛出:
      IllegalThreadStateException - 如果在AWT事件分派线程上调用

    • toString

      public String toString()
      返回此Robot的字符串表示形式。
      覆盖:
      toString 在类 Object
      返回:
      字符串表示形式。