device - PythonIDE Docs

读取当前 iPhone/iPad 的设备、系统、屏幕、电池、内存、温度、区域和语言信息。

边界：用于界面适配、环境诊断和状态展示。identifier_for_vendor() 不是登录或支付凭据；改亮度要有明确用户动作。

#模块概览

项	说明
导入	`import device`
适合做什么	设备信息页、布局适配、电量/低电量模式判断、诊断面板
调用时机	放在按钮回调或启动时读一次；不要写在 AppUI `body()` 里反复调用
推荐顺序	用户点击刷新 → 读取 `model` / `screen_size` 等 → 写回 `State`
特殊值	`battery_level()` 不可用时返回 `-1.0`，不要格式化成百分比

#快速开始

下面脚本打印设备型号、系统版本、屏幕和电量信息：

python

import device

print("设备:", device.name(), device.model())
print("系统:", device.system_name(), device.system_version())
width, height = device.screen_size()
print(f"屏幕: {width:.0f}×{height:.0f}  scale={device.screen_scale()}")

level = device.battery_level()
if level < 0:
    print("电量: 不可用")
else:
    print(f"电量: {level:.0%}  状态: {device.battery_state()}")

print("热状态:", device.thermal_state())
print("低电量模式:", device.is_low_power_mode())
print("区域:", device.locale(), device.timezone())

#AppUI 示例

设备信息由按钮触发读取，结果写进 State；不要在 body() 里直接调用 device.*。

python

import appui
import device

state = appui.State(
    model="—",
    system="—",
    screen="—",
    battery="—",
    battery_state="—",
    thermal="—",
    low_power="—",
    message="点击按钮刷新",
)


def format_battery(level):
    if level < 0:
        return "不可用"
    return f"{level:.0%}"


def format_memory(bytes_value):
    if bytes_value <= 0:
        return "—"
    gb = bytes_value / (1024 ** 3)
    return f"{gb:.1f} GB"


def refresh_device_info():
    width, height = device.screen_size()
    state.batch_update(
        model=device.model(),
        system=f"{device.system_name()} {device.system_version()}",
        screen=f"{width:.0f}×{height:.0f} @ {device.screen_scale():.0f}x",
        battery=format_battery(device.battery_level()),
        battery_state=device.battery_state(),
        thermal=device.thermal_state(),
        low_power="是" if device.is_low_power_mode() else "否",
        message=f"内存 {format_memory(device.total_memory())} · 运行 {device.system_uptime():.0f}s",
    )


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("设备", [
                appui.LabeledContent("型号", value=state.model),
                appui.LabeledContent("系统", value=state.system),
                appui.LabeledContent("屏幕", value=state.screen),
            ]),
            appui.Section("电源", [
                appui.LabeledContent("电量", value=state.battery),
                appui.LabeledContent("充电状态", value=state.battery_state),
                appui.LabeledContent("低电量模式", value=state.low_power),
                appui.LabeledContent("热状态", value=state.thermal),
            ]),
            appui.Section("操作", [
                appui.Button("刷新设备信息", action=refresh_device_info)
                .button_style("bordered_prominent"),
                appui.Text(state.message).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("设备信息")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`name()` / `model()`	设备名称 / 型号
`system_name()` / `system_version()`	系统名称与版本
`screen_size()` / `screen_scale()`	屏幕尺寸与 scale
`battery_level()` / `battery_state()`	电量与充电状态
`thermal_state()` / `is_low_power_mode()`	热状态与低电量模式
`total_memory()` / `processor_count()`	物理内存与 CPU 核心数
`screen_brightness()` / `set_screen_brightness(v)`	读取 / 设置亮度
`locale()` / `timezone()` / `preferred_languages()`	区域、时区与语言

#设备与系统

API	返回	说明
`name()`	`str`	用户设置的设备名称
`model()`	`str`	设备型号标识
`system_name()`	`str`	如 `iOS`
`system_version()`	`str`	系统版本号
`identifier_for_vendor()`	`str`	开发者维度设备 ID；重装可能变化
`system_uptime()`	`float`	开机以来秒数
`orientation()`	`str`	当前屏幕方向

python

print(device.model(), device.system_version())
print(device.identifier_for_vendor())

#屏幕与亮度

API	返回	说明
`screen_width()` / `screen_height()`	`float`	屏幕点数宽高
`screen_size()`	`tuple`	`(width, height)`
`screen_scale()`	`float`	Retina scale
`screen_brightness()`	`float`	当前亮度 0.0–1.0
`set_screen_brightness(value)`	`None`	设置亮度，需用户动作触发

python

width, height = device.screen_size()
device.set_screen_brightness(0.6)  # 仅在按钮回调里调用

#电源与性能

API	返回	说明
`battery_level()`	`float`	0.0–1.0；不可用为 `-1.0`
`battery_state()`	`str`	`unknown` / `unplugged` / `charging` / `full`
`thermal_state()`	`str`	`nominal` / `fair` / `serious` / `critical`
`is_low_power_mode()`	`bool`	是否低电量模式
`total_memory()`	`int`	物理内存字节数
`processor_count()`	`int`	CPU 核心数

python

level = device.battery_level()
if level >= 0:
    print(f"{level:.0%}", device.battery_state())
if device.is_low_power_mode():
    print("低电量模式，可降低刷新频率")

#区域与语言

API	返回	说明
`locale()`	`str`	当前区域标识
`timezone()`	`str`	时区
`preferred_languages()`	`list[str]`	用户首选语言列表

python

print(device.locale(), device.timezone())
print(device.preferred_languages())

#常见错误

错误写法	后果	修正
在 `body()` 里读 `device.*`	每次刷新都重复调用	放进按钮回调或启动时读一次
`battery_level()` 为 `-1.0` 仍格式化成 %	显示异常百分比	显示「不可用」
脚本自动 `set_screen_brightness`	改变用户设备体验	仅在明确按钮动作里调用
把 `identifier_for_vendor()` 当登录凭据	不安全、可能变化	仅作设备区分，不作鉴权

#相关文档

文档	用途
storage	本地数据存储
permission	系统权限状态
原生能力入口	MiniApp 场景配方

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。