Device - 设备
<p>[TOC]</p>
<h1>Device</h1>
<blockquote>
<p>Stability: 2 - Stable</p>
</blockquote>
<p>device模块提供了与设备有关的信息与操作，例如获取设备宽高，内存使用率，IMEI，调整设备亮度、音量等。</p>
<p>此模块的部分函数，例如调整音量，需要"修改系统设置"的权限。如果没有该权限，会抛出<code>SecurityException</code>并跳转到权限设置界面。</p>
<h2>device.width</h2>
<ul>
<li>{number}</li>
</ul>
<p>设备屏幕分辨率宽度。例如1080。</p>
<h2>device.height</h2>
<ul>
<li>{number}</li>
</ul>
<p>设备屏幕分辨率高度。例如1920。</p>
<h2>device.buildId</h2>
<ul>
<li>{string}</li>
</ul>
<p>Either a changelist number, or a label like "M4-rc20".</p>
<p>修订版本号，或者诸如"M4-rc20"的标识。</p>
<h2>device.broad</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the underlying board, like "goldfish".</p>
<p>设备的主板(?)型号。</p>
<h2>device.brand</h2>
<ul>
<li>{string}</li>
</ul>
<p>The consumer-visible brand with which the product/hardware will be associated, if any.</p>
<p>与产品或硬件相关的厂商品牌，如"Xiaomi", "Huawei"等。</p>
<h2>device.device</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the industrial design.</p>
<p>设备在工业设计中的名称。</p>
<h2>deivce.model</h2>
<ul>
<li>{string}</li>
</ul>
<p>The end-user-visible name for the end product.</p>
<p>设备型号。</p>
<h2>device.product</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the overall product.</p>
<p>整个产品的名称。</p>
<h2>device.bootloader</h2>
<ul>
<li>{string}</li>
</ul>
<p>The system bootloader version number.</p>
<p>设备Bootloader的版本。</p>
<h2>device.hardware</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the hardware (from the kernel command line or /proc).</p>
<p>设备的硬件名称(来自内核命令行或者/proc)。</p>
<h2>device.fingerprint</h2>
<ul>
<li>{string}</li>
</ul>
<p>A string that uniquely identifies this build. Do not attempt to parse this value.</p>
<p>构建(build)的唯一标识码。</p>
<h2>device.serial</h2>
<ul>
<li>{string}</li>
</ul>
<p>A hardware serial number, if available. Alphanumeric only, case-insensitive.</p>
<p>硬件序列号。</p>
<h2>device.sdkInt</h2>
<ul>
<li>{number}</li>
</ul>
<p>The user-visible SDK version of the framework; its possible values are defined in Build.VERSION_CODES.</p>
<p>安卓系统API版本。例如安卓4.4的sdkInt为19。</p>
<h2>device.incremental</h2>
<ul>
<li>{string}</li>
</ul>
<p>The internal value used by the underlying source control to represent this build. E.g., a perforce changelist number or a git hash.</p>
<h2>device.release</h2>
<ul>
<li>{string}</li>
</ul>
<p>The user-visible version string. E.g., "1.0" or "3.4b5".</p>
<p>Android系统版本号。例如"5.0", "7.1.1"。</p>
<h2>device.baseOS</h2>
<ul>
<li>{string}</li>
</ul>
<p>The base OS build the product is based on.</p>
<h2>device.securityPatch</h2>
<ul>
<li>{string}</li>
</ul>
<p>The user-visible security patch level.</p>
<p>安全补丁程序级别。</p>
<h2>device.codename</h2>
<ul>
<li>{string}</li>
</ul>
<p>The current development codename, or the string "REL" if this is a release build.</p>
<p>开发代号，例如发行版是"REL"。</p>
<h2>device.getIMEI()</h2>
<ul>
<li>{string}</li>
</ul>
<p>返回设备的IMEI.</p>
<h2>device.getAndroidId()</h2>
<ul>
<li>{string}</li>
</ul>
<p>返回设备的Android ID。</p>
<p>Android ID为一个用16进制字符串表示的64位整数，在设备第一次使用时随机生成，之后不会更改，除非恢复出厂设置。</p>
<h2>device.getMacAddress()</h2>
<ul>
<li>{string}</li>
</ul>
<p>返回设备的Mac地址。该函数需要在有WLAN连接的情况下才能获取，否则会返回null。</p>
<p><strong>可能的后续修改</strong>：未来可能增加有root权限的情况下通过root权限获取，从而在没有WLAN连接的情况下也能返回正确的Mac地址，因此请勿使用此函数判断WLAN连接。</p>
<h2>device.getBrightness()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回当前的(手动)亮度。范围为0~255。</p>
<h2>device.getBrightnessMode()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回当前亮度模式，0为手动亮度，1为自动亮度。</p>
<h2>device.setBrightness(b)</h2>
<ul>
<li><code>b</code> {number} 亮度，范围0~255</li>
</ul>
<p>设置当前手动亮度。如果当前是自动亮度模式，该函数不会影响屏幕的亮度。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.setBrightnessMode(mode)</h2>
<ul>
<li><code>mode</code> {number} 亮度模式，0为手动亮度，1为自动亮度</li>
</ul>
<p>设置当前亮度模式。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.getMusicVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回当前媒体音量。</p>
<h2>device.getNotificationVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回当前通知音量。</p>
<h2>device.getAlarmVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回当前闹钟音量。</p>
<h2>device.getMusicMaxVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回媒体音量的最大值。</p>
<h2>device.getNotificationMaxVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回通知音量的最大值。</p>
<h2>device.getAlarmMaxVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回闹钟音量的最大值。</p>
<h2>device.setMusicVolume(volume)</h2>
<ul>
<li><code>volume</code> {number} 音量</li>
</ul>
<p>设置当前媒体音量。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.setNotificationVolume(volume)</h2>
<ul>
<li><code>volume</code> {number} 音量</li>
</ul>
<p>设置当前通知音量。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.setAlarmVolume(volume)</h2>
<ul>
<li><code>volume</code> {number} 音量</li>
</ul>
<p>设置当前闹钟音量。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.getBattery()</h2>
<ul>
<li>{number} 0.0~100.0的浮点数</li>
</ul>
<p>返回当前电量百分比。</p>
<h2>device.isCharging()</h2>
<ul>
<li>{boolean}</li>
</ul>
<p>返回设备是否正在充电。</p>
<h2>device.getTotalMem()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回设备内存总量，单位字节(B)。1MB = 1024 * 1024B。</p>
<h2>device.getAvailMem()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回设备当前可用的内存，单位字节(B)。</p>
<h2>device.isScreenOn()</h2>
<ul>
<li>返回 {boolean}</li>
</ul>
<p>返回设备屏幕是否是亮着的。如果屏幕亮着，返回<code>true</code>; 否则返回<code>false</code>。</p>
<p>需要注意的是，类似于vivo xplay系列的息屏时钟不属于"屏幕亮着"的情况，虽然屏幕确实亮着但只能显示时钟而且不可交互，此时<code>isScreenOn()</code>也会返回<code>false</code>。</p>
<h2>device.wakeUp()</h2>
<p>唤醒设备。包括唤醒设备CPU、屏幕等。可以用来点亮屏幕。</p>
<h2>device.wakeUpIfNeeded()</h2>
<p>如果屏幕没有点亮，则唤醒设备。</p>
<h2>device.keepScreenOn([timeout])</h2>
<ul>
<li><code>timeout</code> {number} 屏幕保持常亮的时间, 单位毫秒。如果不加此参数，则一直保持屏幕常亮。</li>
</ul>
<p>保持屏幕常亮。</p>
<p>此函数无法阻止用户使用锁屏键等正常关闭屏幕，只能使得设备在无人操作的情况下保持屏幕常亮；同时，如果此函数调用时屏幕没有点亮，则会唤醒屏幕。</p>
<p>在某些设备上，如果不加参数timeout，只能在Auto.js的界面保持屏幕常亮，在其他界面会自动失效，这是因为设备的省电策略造成的。因此，建议使用比较长的时长来代替"一直保持屏幕常亮"的功能，例如<code>device.keepScreenOn(3600 * 1000)</code>。</p>
<p>可以使用<code>device.cancelKeepingAwake()</code>来取消屏幕常亮。</p>
<pre><code>//一直保持屏幕常亮
device.keepScreenOn()</code></pre>
<h2>device.keepScreenDim([timeout])</h2>
<ul>
<li><code>timeout</code> {number} 屏幕保持常亮的时间, 单位毫秒。如果不加此参数，则一直保持屏幕常亮。</li>
</ul>
<p>保持屏幕常亮，但允许屏幕变暗来节省电量。此函数可以用于定时脚本唤醒屏幕操作，不需要用户观看屏幕，可以让屏幕变暗来节省电量。</p>
<p>此函数无法阻止用户使用锁屏键等正常关闭屏幕，只能使得设备在无人操作的情况下保持屏幕常亮；同时，如果此函数调用时屏幕没有点亮，则会唤醒屏幕。</p>
<p>可以使用<code>device.cancelKeepingAwake()</code>来取消屏幕常亮。</p>
<h2>device.cancelKeepingAwake()</h2>
<p>取消设备保持唤醒状态。用于取消<code>device.keepScreenOn()</code>, <code>device.keepScreenDim()</code>等函数设置的屏幕常亮。</p>
<h2>device.vibrate(millis)</h2>
<ul>
<li><code>millis</code> {number} 震动时间，单位毫秒</li>
</ul>
<p>使设备震动一段时间。</p>
<pre><code>//震动两秒
device.vibrate(2000);</code></pre>
<h2>device.cancelVibration()</h2>
<p>如果设备处于震动状态，则取消震动。</p>
<h1>Device</h1>
<blockquote>
<p>Stability: 2 - Stable</p>
</blockquote>
<p>device模块提供了与设备有关的信息与操作，例如获取设备宽高，内存使用率，IMEI，调整设备亮度、音量等。</p>
<p>此模块的部分函数，例如调整音量，需要"修改系统设置"的权限。如果没有该权限，会抛出<code>SecurityException</code>并跳转到权限设置界面。</p>
<h2>device.width</h2>
<ul>
<li>{number}</li>
</ul>
<p>设备屏幕分辨率宽度。例如1080。</p>
<h2>device.height</h2>
<ul>
<li>{number}</li>
</ul>
<p>设备屏幕分辨率高度。例如1920。</p>
<h2>device.buildId</h2>
<ul>
<li>{string}</li>
</ul>
<p>Either a changelist number, or a label like "M4-rc20".</p>
<p>修订版本号，或者诸如"M4-rc20"的标识。</p>
<h2>device.broad</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the underlying board, like "goldfish".</p>
<p>设备的主板(?)型号。</p>
<h2>device.brand</h2>
<ul>
<li>{string}</li>
</ul>
<p>The consumer-visible brand with which the product/hardware will be associated, if any.</p>
<p>与产品或硬件相关的厂商品牌，如"Xiaomi", "Huawei"等。</p>
<h2>device.device</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the industrial design.</p>
<p>设备在工业设计中的名称。</p>
<h2>deivce.model</h2>
<ul>
<li>{string}</li>
</ul>
<p>The end-user-visible name for the end product.</p>
<p>设备型号。</p>
<h2>device.product</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the overall product.</p>
<p>整个产品的名称。</p>
<h2>device.bootloader</h2>
<ul>
<li>{string}</li>
</ul>
<p>The system bootloader version number.</p>
<p>设备Bootloader的版本。</p>
<h2>device.hardware</h2>
<ul>
<li>{string}</li>
</ul>
<p>The name of the hardware (from the kernel command line or /proc).</p>
<p>设备的硬件名称(来自内核命令行或者/proc)。</p>
<h2>device.fingerprint</h2>
<ul>
<li>{string}</li>
</ul>
<p>A string that uniquely identifies this build. Do not attempt to parse this value.</p>
<p>构建(build)的唯一标识码。</p>
<h2>device.serial</h2>
<ul>
<li>{string}</li>
</ul>
<p>A hardware serial number, if available. Alphanumeric only, case-insensitive.</p>
<p>硬件序列号。</p>
<h2>device.sdkInt</h2>
<ul>
<li>{number}</li>
</ul>
<p>The user-visible SDK version of the framework; its possible values are defined in Build.VERSION_CODES.</p>
<p>安卓系统API版本。例如安卓4.4的sdkInt为19。</p>
<h2>device.incremental</h2>
<ul>
<li>{string}</li>
</ul>
<p>The internal value used by the underlying source control to represent this build. E.g., a perforce changelist number or a git hash.</p>
<h2>device.release</h2>
<ul>
<li>{string}</li>
</ul>
<p>The user-visible version string. E.g., "1.0" or "3.4b5".</p>
<p>Android系统版本号。例如"5.0", "7.1.1"。</p>
<h2>device.baseOS</h2>
<ul>
<li>{string}</li>
</ul>
<p>The base OS build the product is based on.</p>
<h2>device.securityPatch</h2>
<ul>
<li>{string}</li>
</ul>
<p>The user-visible security patch level.</p>
<p>安全补丁程序级别。</p>
<h2>device.codename</h2>
<ul>
<li>{string}</li>
</ul>
<p>The current development codename, or the string "REL" if this is a release build.</p>
<p>开发代号，例如发行版是"REL"。</p>
<h2>device.getIMEI()</h2>
<ul>
<li>{string}</li>
</ul>
<p>返回设备的IMEI.</p>
<h2>device.getAndroidId()</h2>
<ul>
<li>{string}</li>
</ul>
<p>返回设备的Android ID。</p>
<p>Android ID为一个用16进制字符串表示的64位整数，在设备第一次使用时随机生成，之后不会更改，除非恢复出厂设置。</p>
<h2>device.getMacAddress()</h2>
<ul>
<li>{string}</li>
</ul>
<p>返回设备的Mac地址。该函数需要在有WLAN连接的情况下才能获取，否则会返回null。</p>
<p><strong>可能的后续修改</strong>：未来可能增加有root权限的情况下通过root权限获取，从而在没有WLAN连接的情况下也能返回正确的Mac地址，因此请勿使用此函数判断WLAN连接。</p>
<h2>device.getBrightness()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回当前的(手动)亮度。范围为0~255。</p>
<h2>device.getBrightnessMode()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回当前亮度模式，0为手动亮度，1为自动亮度。</p>
<h2>device.setBrightness(b)</h2>
<ul>
<li><code>b</code> {number} 亮度，范围0~255</li>
</ul>
<p>设置当前手动亮度。如果当前是自动亮度模式，该函数不会影响屏幕的亮度。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.setBrightnessMode(mode)</h2>
<ul>
<li><code>mode</code> {number} 亮度模式，0为手动亮度，1为自动亮度</li>
</ul>
<p>设置当前亮度模式。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.getMusicVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回当前媒体音量。</p>
<h2>device.getNotificationVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回当前通知音量。</p>
<h2>device.getAlarmVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回当前闹钟音量。</p>
<h2>device.getMusicMaxVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回媒体音量的最大值。</p>
<h2>device.getNotificationMaxVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回通知音量的最大值。</p>
<h2>device.getAlarmMaxVolume()</h2>
<ul>
<li>{number} 整数值</li>
</ul>
<p>返回闹钟音量的最大值。</p>
<h2>device.setMusicVolume(volume)</h2>
<ul>
<li><code>volume</code> {number} 音量</li>
</ul>
<p>设置当前媒体音量。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.setNotificationVolume(volume)</h2>
<ul>
<li><code>volume</code> {number} 音量</li>
</ul>
<p>设置当前通知音量。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.setAlarmVolume(volume)</h2>
<ul>
<li><code>volume</code> {number} 音量</li>
</ul>
<p>设置当前闹钟音量。</p>
<p>此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。</p>
<h2>device.getBattery()</h2>
<ul>
<li>{number} 0.0~100.0的浮点数</li>
</ul>
<p>返回当前电量百分比。</p>
<h2>device.isCharging()</h2>
<ul>
<li>{boolean}</li>
</ul>
<p>返回设备是否正在充电。</p>
<h2>device.getTotalMem()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回设备内存总量，单位字节(B)。1MB = 1024 * 1024B。</p>
<h2>device.getAvailMem()</h2>
<ul>
<li>{number}</li>
</ul>
<p>返回设备当前可用的内存，单位字节(B)。</p>
<h2>device.isScreenOn()</h2>
<ul>
<li>返回 {boolean}</li>
</ul>
<p>返回设备屏幕是否是亮着的。如果屏幕亮着，返回<code>true</code>; 否则返回<code>false</code>。</p>
<p>需要注意的是，类似于vivo xplay系列的息屏时钟不属于"屏幕亮着"的情况，虽然屏幕确实亮着但只能显示时钟而且不可交互，此时<code>isScreenOn()</code>也会返回<code>false</code>。</p>
<h2>device.wakeUp()</h2>
<p>唤醒设备。包括唤醒设备CPU、屏幕等。可以用来点亮屏幕。</p>
<h2>device.wakeUpIfNeeded()</h2>
<p>如果屏幕没有点亮，则唤醒设备。</p>
<h2>device.keepScreenOn([timeout])</h2>
<ul>
<li><code>timeout</code> {number} 屏幕保持常亮的时间, 单位毫秒。如果不加此参数，则一直保持屏幕常亮。</li>
</ul>
<p>保持屏幕常亮。</p>
<p>此函数无法阻止用户使用锁屏键等正常关闭屏幕，只能使得设备在无人操作的情况下保持屏幕常亮；同时，如果此函数调用时屏幕没有点亮，则会唤醒屏幕。</p>
<p>在某些设备上，如果不加参数timeout，只能在Auto.js的界面保持屏幕常亮，在其他界面会自动失效，这是因为设备的省电策略造成的。因此，建议使用比较长的时长来代替"一直保持屏幕常亮"的功能，例如<code>device.keepScreenOn(3600 * 1000)</code>。</p>
<p>可以使用<code>device.cancelKeepingAwake()</code>来取消屏幕常亮。</p>
<pre><code>//一直保持屏幕常亮
device.keepScreenOn()</code></pre>
<h2>device.keepScreenDim([timeout])</h2>
<ul>
<li><code>timeout</code> {number} 屏幕保持常亮的时间, 单位毫秒。如果不加此参数，则一直保持屏幕常亮。</li>
</ul>
<p>保持屏幕常亮，但允许屏幕变暗来节省电量。此函数可以用于定时脚本唤醒屏幕操作，不需要用户观看屏幕，可以让屏幕变暗来节省电量。</p>
<p>此函数无法阻止用户使用锁屏键等正常关闭屏幕，只能使得设备在无人操作的情况下保持屏幕常亮；同时，如果此函数调用时屏幕没有点亮，则会唤醒屏幕。</p>
<p>可以使用<code>device.cancelKeepingAwake()</code>来取消屏幕常亮。</p>
<h2>device.cancelKeepingAwake()</h2>
<p>取消设备保持唤醒状态。用于取消<code>device.keepScreenOn()</code>, <code>device.keepScreenDim()</code>等函数设置的屏幕常亮。</p>
<h2>device.vibrate(millis)</h2>
<ul>
<li><code>millis</code> {number} 震动时间，单位毫秒</li>
</ul>
<p>使设备震动一段时间。</p>
<pre><code>//震动两秒
device.vibrate(2000);</code></pre>
<h2>device.cancelVibration()</h2>
<p>如果设备处于震动状态，则取消震动。</p>