原生能力入口 - PythonIDE Docs

主文档已合并：入口模型、Python 模块表、AppUI 原生组件入口表与侧边栏导航均由 schema 生成，请优先阅读 **iOS 原生能力**。本文仅保留历史深链，不再维护独立能力表。

MiniApp 场景下的原生能力配方：按任务选模块、组合调用、状态写回界面。

边界：这是 MiniApp 配方索引，不是可 import 的模块。完整 API 以各模块文档为准；系统调用放在按钮回调，不要写在 body() 里。

#模块概览

项	说明
导入	按场景 `import` 对应模块（如 `photos`、`storage`）
适合做什么	选图、定位、通知、持久化、网络列表等 MiniApp 常见流
调用时机	按钮、刷新、选择器触发；`body()` 只读 `State`
数据分工	设置 `storage`、记录 `database`、密钥 `keychain`
反馈	成功/取消/失败都写回 `State` 或 HUD

#快速开始

保存主题并触发触觉反馈：

python

import haptics
import storage

storage.set("demo.theme", "Dark")
if haptics.is_supported():
    haptics.notification("success")
print("已保存:", storage.get("demo.theme"))

#AppUI 示例

设备信息、快照、通知组合；所有原生调用在按钮回调里。

python

import appui
import device
import haptics
import notification
import storage

SNAPSHOT_KEY = "native.snapshot"
REMINDER_ID = "native.snapshot.reminder"

state = appui.State(
    message="就绪",
    rows=[
        {"id": "model", "title": "型号", "value": "点击刷新"},
        {"id": "battery", "title": "电量", "value": "—"},
    ],
)


def row_key(row):
    return row["id"]


def row_view(row):
    return appui.LabeledContent(row["title"], value=row["value"])


def refresh_device_info():
    state.rows = [
        {"id": "model", "title": "型号", "value": device.model()},
        {"id": "battery", "title": "电量", "value": f"{device.battery_level():.0%}"},
    ]
    state.message = "设备信息已刷新"


def save_snapshot():
    storage.set_json(SNAPSHOT_KEY, state.rows)
    if haptics.is_supported():
        haptics.notification("success")
    state.message = "快照已保存"


def remind_later():
    perm = notification.request_permission()
    if not perm.get("granted"):
        state.message = "未获得通知权限"
        return

    result = notification.schedule(
        REMINDER_ID,
        "原生快照",
        "查看已保存的设备快照",
        delay=60,
    )
    state.message = f"已调度提醒: {result}"


def body():
    return appui.NavigationStack(
        appui.List([
            appui.Section("设备", [
                appui.ForEach(state.rows, row_builder=row_view, key=row_key),
            ]),
            appui.Section("操作", [
                appui.Button("刷新设备", action=refresh_device_info),
                appui.Button("保存快照", action=save_snapshot)
                .button_style("bordered_prominent"),
                appui.Button("1 分钟后提醒", action=remind_later),
            ], footer=state.message),
        ]).navigation_title("原生能力")
    )


appui.run(body, state=state)

#API 参考

#能力入口

能力	主文档	典型用途
定位与地图	location	坐标、地理编码、指南针
相册与相机	photos	选图、拍照、保存
通知与实时活动	notification、live_activity	提醒、角标、锁屏状态
持久化	storage、database、keychain	设置、记录、密钥
设备与传感器	device、motion	屏幕、电池、传感器
触觉与声音	haptics、sound	反馈、提示音
网络	network、websocket	HTTP、实时连接
编辑器工具栏	keyboard	插入代码片段

#场景配方

目标	推荐组合	说明
选图并保存设置	`appui` + `photos` + `storage`	按钮触发 picker，路径写入 `State`
下载并存相册	`network` + `photos`	下载到本地再 `save_video`
地图展示位置	`permission` + `location` + `MapView`	先查权限再定位
健康面板	`permission` + `health` + `Chart`	拒绝时显示空状态
提醒任务	`notification` + `storage`	稳定 `identifier` 调度/取消
播放历史	`database` + `List`	大列表勿塞 `storage`
安全配置	`biometric` + `keychain` + `Form`	密钥进 keychain
传感器面板	`motion` + `haptics`	高频数据避免每帧重建 UI
远端列表	`network` + `List` + `.refreshable`	请求放刷新回调

#使用规则

权限类能力先查状态，再请求。
触觉、通知、声音不要在循环里连续触发。
写代码前打开对应模块文档，按公开 Python API 调用。

#常见错误

错误写法	后果	修正
在 `body()` 里请求权限/发通知	刷新时反复弹窗	放进按钮回调
token 写入 `storage` 或日志	泄露风险	用 `keychain`
权限拒绝后空白页	用户不知原因	显示说明与重试按钮
用户取消选择未处理	崩溃或脏状态	判断 `None` 并保留原状态
网络失败清空旧数据	体验差	保留缓存并显示错误

#相关文档

文档	用途
iOS 原生能力	入口模型、模块表与权限矩阵
全部模块总览	按分类浏览模块
运行时选择	appui / scene / widget 选型
permission	统一权限查询与申请
photos	相册与相机
notification	本地通知

#使用原则

原生能力放在用户触发的回调里，不要写在 body() 构建期
先查最小模块，再组合；避免一次 import 多个无关模块
返回值、取消和拒绝都要给用户可见反馈

#失败路径

情况	处理
权限拒绝	提示去设置开启，并保留当前页面
设备不支持	用 `is_available()` 或模块返回值判断
用户取消	不要当作成功继续写数据

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，请按「失败路径」排查。