设备#

Device 命名空间提供对当前设备硬件、系统环境、语言区域、屏幕信息、电池状态、方向感知、接近传感器以及网络接口等信息的访问能力，并提供相关状态变化的监听接口。

该 API 主要用于根据设备环境动态调整 UI、行为逻辑或系统能力使用方式。

#Orientation

表示设备当前的物理朝向。

type Orientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscapeLeft"
  | "landscapeRight"
  | "faceUp"
  | "faceDown"
  | "unknown"

#说明

• portrait：竖屏，Home 键在下（或标准竖屏方向）
• portraitUpsideDown：竖屏倒置
• landscapeLeft：横屏，设备向左旋转
• landscapeRight：横屏，设备向右旋转
• faceUp：设备平放，屏幕朝上
• faceDown：设备平放，屏幕朝下
• unknown：无法确定方向

#NetworkInterface

描述单个网络接口地址的信息。

type NetworkInterface = {
  address: string
  netmask: string | null
  family: "IPv4" | "IPv6"
  mac: string | null
  isInternal: boolean
  cidr: string | null
}

#字段说明

• address：IP 地址
• netmask：子网掩码
• family：地址族，IPv4 或 IPv6
• mac：MAC 地址（部分系统或接口可能为 null）
• isInternal：是否为内部接口（如 loopback）
• cidr：CIDR 表示形式，例如 192.168.1.10/24

#BatteryState

表示当前电池状态。

type BatteryState = "full" | "charging" | "unplugged" | "unknown"

#说明

• full：电量已充满
• charging：正在充电
• unplugged：未连接电源
• unknown：无法确定状态

#Device Information

#model

const model: string

设备型号，例如 "iPhone"、"iPad"。

#localizedModel

const localizedModel: string

本地化后的设备型号名称。

#systemVersion

const systemVersion: string

当前操作系统版本号，例如 "18.2"。

#systemName

const systemName: string

操作系统名称，例如 "iOS"、"iPadOS"、"macOS"。

#isiPad / isiPhone

const isiPad: boolean
const isiPhone: boolean

指示当前设备是否为 iPad 或 iPhone。

#screen

const screen: {
  width: number
  height: number
  scale: number
}

屏幕信息：

• width：屏幕宽度（逻辑像素）
• height：屏幕高度（逻辑像素）
• scale：屏幕缩放比例（如 2、3）

#Battery & Sensors

#batteryState

const batteryState: BatteryState

当前电池状态。

#batteryLevel

const batteryLevel: number

当前电量百分比，范围为 0.0 到 1.0。

#proximityState

const proximityState: boolean

接近传感器状态，true 表示设备靠近用户（例如通话时贴近耳朵）。

#Orientation & Layout

#isLandscape / isPortrait / isFlat

const isLandscape: boolean
const isPortrait: boolean
const isFlat: boolean

• isLandscape：是否处于横屏
• isPortrait：是否处于竖屏
• isFlat：设备是否平放（face up / face down）

#orientation

const orientation: Orientation

当前设备物理方向。

#Appearance & Environment

#colorScheme

const colorScheme: ColorScheme

当前系统颜色模式，例如浅色或深色模式。

#isiOSAppOnMac

const isiOSAppOnMac: boolean

指示当前进程是否为运行在 macOS 上的 iPhone / iPad App（Mac Catalyst 或 iOS App on Mac）。

#Locale & Language

#systemLocale

const systemLocale: string

当前系统 Locale，例如 "en_US"。

#preferredLanguages

const preferredLanguages: string[]

用户偏好的语言列表，例如：

["en-US", "zh-Hans-CN"]

#systemLocales（已废弃）

const systemLocales: string[]

已废弃，请使用 preferredLanguages。

#systemLanguageTag

const systemLanguageTag: string

语言标签，例如 "en-US"。

#systemLanguageCode

const systemLanguageCode: string

语言代码，例如 "en"。

#systemCountryCode

const systemCountryCode: string | undefined

国家代码，例如 "US"。

#systemScriptCode

const systemScriptCode: string | undefined

书写系统代码，例如 "Hans"（简体中文）。

#Wake Lock

#isWakeLockEnabled

const isWakeLockEnabled: Promise<boolean>

查询当前是否启用了屏幕唤醒锁定（防止设备自动锁屏）。

#setWakeLockEnabled

function setWakeLockEnabled(enabled: boolean): void

启用或禁用 Wake Lock。

说明：

• 仅在 Scripting App 内可用
• 启用后可防止设备自动休眠

#Battery Listeners

#addBatteryStateListener

function addBatteryStateListener(
  callback: (state: BatteryState) => void
): void

监听电池状态变化。

#removeBatteryStateListener

function removeBatteryStateListener(
  callback?: (state: BatteryState) => void
): void

移除电池状态监听器。

• 未传入 callback 时将移除所有监听器

#addBatteryLevelListener

function addBatteryLevelListener(
  callback: (level: number) => void
): void

监听电量变化。

#removeBatteryLevelListener

function removeBatteryLevelListener(
  callback?: (level: number) => void
): void

移除电量监听器。

#Orientation Listeners

#addOrientationListener

function addOrientationListener(
  callback: (orientation: Orientation) => void
): void

开始监听设备方向变化。

注意事项：

• 必须先调用该方法才能接收方向变化
• 系统方向锁开启时不会生效

#removeOrientationListener

function removeOrientationListener(
  callback?: (orientation: Orientation) => void
): void

移除方向监听器。

• 未传入 callback 时将停止所有方向监听并结束观察

#Proximity Listeners

#addProximityStateListener

function addProximityStateListener(
  callback: (state: boolean) => void
): void

监听接近传感器状态变化。

#removeProximityStateListener

function removeProximityStateListener(
  callback?: (state: boolean) => void
): void

移除接近传感器监听器。

#Network

#networkInterfaces

function networkInterfaces(): Record<string, NetworkInterface[]>

获取当前设备的网络接口信息。

返回值说明：

• Key：接口名称（如 en0、lo0）
• Value：该接口对应的地址信息数组

适用于网络诊断、本地 IP 获取、调试用途。