iOS 原生能力
相册、联系人、权限、相机、控制台和安全存储。
iOS 原生 Python 模块总入口:按任务选模块、组合调用、权限与真机要求速查。
边界:这是 能力索引页,不是import名。具体 API 见各模块文档;系统面板、硬件扫描、权限申请必须由按钮或菜单触发,不要在 AppUIbody()或模块导入时自动执行。
#模块概览
| 项 | 说明 |
|---|---|
| 导入 | 按任务 import 对应模块(如 import photos) |
| 适合做什么 | 相册、定位、通知、蓝牙、健康、网络等系统能力 |
| 调用时机 | 按钮/刷新/选择器触发;body() 只展示 State |
| 敏感数据 | token/密钥 → keychain;普通设置 → storage |
| 文档导航 | schema navigation.iosNative 投影;见下方 文档导航 表 |
| 下一步 | 按场景配方选模块 → 打开模块页 → 复制 AppUI 示例 |
#快速开始
相册、剪贴板、HUD 与钥匙串组合(函数式,适合脚本调试):
已复制
import clipboard
import console
import keychain
import photos
def pick_photo_and_copy_size():
image = photos.pick_image(raw_data=True)
if not image:
return "已取消选择"
clipboard.set(f"picked {len(image)} bytes")
console.hud_alert("已复制图片大小", "success")
return f"已复制 {len(image)} bytes"
def save_demo_token():
ok = keychain.set_password("demo", "token", "demo-token")
return "已保存" if ok else "保存失败"
#AppUI 示例
设备信息、本地快照与通知提醒组合;原生调用均在按钮回调里。
已复制
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 参考
#先选模块
| 目标 | 首选模块 | 注意 |
|---|---|---|
| 查询或申请权限 | permission | 只在用户点击后申请 |
| 选择、拍照、保存图片 | photos | 取消返回 None,要先判断 |
| 保存 token、密码 | keychain | 不要写到 storage 或日志 |
| 保存普通设置 | storage | 主题、开关、筛选条件 |
| 弹窗、HUD、输入 | console / dialogs | 短反馈用 HUD |
| 定位、运动、健康、蓝牙、NFC | 对应模块 | 先展示用途再请求 |
| 网络、WebSocket | network / websocket | 勿在 body() 发请求 |
| 快捷指令、Live Activity | shortcuts / live_activity | 需明确用户动作 |
#入口模型
所有原生能力入口由同一套能力清单统一定义(App 内与 Agent 共用)。先判断入口类型,再打开对应文档。
| 入口类型 | 第一行写什么 | 文档入口 |
|---|---|---|
| Python 模块 | import <module> | API 参考 › Python 模块 |
| AppUI 原生组件 | import appui + 组件名 | API 参考 › AppUI 原生组件 |
| 专题页 | 见专题页「首选入口」 | API 参考 › 专题页 |
| 参考 | 见参考页说明 | c_extensions 等 |
#Python 模块
完整 Python import 模块表(含类型与呈现方式):
| 模块 | 类型 | 呈现 | 分类 | 权限 | 能力 |
|---|---|---|---|---|---|
alarm | Python 模块 | Python API | 系统服务 | 无 | alarm_schedule, alarm_cancel |
assistant | Python 模块 | Python API | 系统服务 | 无 | assistant_tools, device_context_answers |
audio_recorder | Python 模块 | Python API | 媒体与视觉 | microphone | microphone_capture, recording_control, level_metering |
audio_session | Python 模块 | Python API | 媒体与视觉 | 无 | audio_session_category, audio_route_query |
avplayer | Python 模块 | Python API | 媒体与视觉 | 无 | audio_video_load, playback_control, native_player |
background | Python 模块 | Python API | 网络与连接 | 无 | background_task, remaining_time, app_state |
background_download | Python 模块 | Python API | 网络与连接 | 无 | background_download, download_progress |
biometric | Python 模块 | 系统表单 | 设备与传感器 | biometric | face_id, touch_id, passcode_fallback |
ble_peripheral | Python 模块 | Python API | 网络与连接 | 无 | ble_peripheral_advertising, ble_characteristic_update |
bluetooth | Python 模块 | Python API | 网络与连接 | bluetooth | ble_scan, ble_connect, read, write |
c_extensions | 参考 | 参考清单 | 网络与连接 | 无 | 扩展清单, 兼容性说明 |
calendar_events | Python 模块 | 系统选择器 | 系统服务 | calendar, reminders | calendar_read, calendar_write, reminders |
clipboard | Python 模块 | Python API | 系统服务 | 无 | read_clipboard, write_clipboard, clear_clipboard |
console | Python 模块 | 系统表单 | 系统服务 | 无 | hud, alerts, input_dialogs |
contacts | Python 模块 | 系统选择器 | 系统服务 | contacts | contacts_read, contacts_picker, contacts_edit |
coreml | Python 模块 | Python API | 媒体与视觉 | 无 | model_listing, model_loading, image_prediction |
database | Python 模块 | Python API | 系统服务 | 无 | sqlite, native_sqlite_bridge, collections, transactions |
device | Python 模块 | Python API | 设备与传感器 | 无 | device_state, screen, battery, thermal_state |
dialogs | Python 模块 | 系统表单 | 系统服务 | 无 | native_dialogs, forms, pickers |
font_picker | Python 模块 | 系统表单 | 系统服务 | 无 | font_picker_ui |
foundation_models | Python 模块 | Python API | 系统服务 | 无 | on_device_generation, summarization, error_explanation |
haptics | Python 模块 | Python API | 设备与传感器 | 无 | impact_feedback, notification_feedback, core_haptics |
health | Python 模块 | Python API | 设备与传感器 | health | steps, heart_rate, sleep, body_metrics |
http_server | Python 模块 | Python API | 网络与连接 | 无 | local_http_server, file_serving |
keyboard | Python 模块 | Python API | 自动化与扩展 | 无 | toolbar_buttons, insert_text, set_buttons |
keychain | Python 模块 | Python API | 系统服务 | 无 | secure_password_storage, service_listing |
live_activity | Python 模块 | Python API | 系统服务 | 无 | dynamic_island, lock_screen_activity |
location | Python 模块 | Python API | 设备与传感器 | location | gps, heading, geocoding |
mail | Python 模块 | 撰写界面 | 系统服务 | 无 | mail_compose, attachment_send |
media_composer | Python 模块 | Python API | 媒体与视觉 | 无 | video_merge, audio_mux, media_export |
message | Python 模块 | 撰写界面 | 系统服务 | 无 | sms_compose, imessage_compose |
motion | Python 模块 | Python API | 设备与传感器 | motion | accelerometer, gyroscope, attitude, barometer |
music | Python 模块 | Python API | 媒体与视觉 | 无 | music_playback, catalog_search |
music_player | Python 模块 | Python API | 媒体与视觉 | 无 | music_queue, playback_control, play_mode, now_playing_metadata, remote_commands, playback_restore, progress_events, queue_preload, preload_events |
network | Python 模块 | Python API | 网络与连接 | 无 | http, download, connectivity |
nfc | Python 模块 | 系统选择器 | 系统服务 | nfc | ndef_scan, ndef_write |
notification | Python 模块 | Python API | 系统服务 | notifications | local_notifications, badges, scheduled_alerts |
now_playing | Python 模块 | Python API | 媒体与视觉 | 无 | now_playing_metadata, playback_progress |
objc_util | Python 模块 | Python API | 自动化与扩展 | 无 | Objective-C 运行时, 系统框架访问 |
pdf | Python 模块 | Python API | 媒体与视觉 | 无 | pdf_creation, text_extraction, page_rendering, quicklook_preview |
permission | Python 模块 | Python API | 系统服务 | 无 | permission_status, permission_request |
photos | Python 模块 | Python API | 媒体与视觉 | photos, camera | photo_picker, camera_capture, photo_save, video_save, asset_read |
qrcode | Python 模块 | Python API | 媒体与视觉 | 无 | qr_generation, png_export |
shazam | Python 模块 | Python API | 媒体与视觉 | microphone | music_identification, microphone_recognition, file_recognition |
shortcuts | Python 模块 | Python API | 自动化与扩展 | 无 | run_shortcut, open_url, open_settings |
sound | Python 模块 | Python API | 媒体与视觉 | 无 | sound_effects, audio_player |
speech | Python 模块 | Python API | 媒体与视觉 | speech | text_to_speech, voice_listing |
speech_recognition | Python 模块 | Python API | 媒体与视觉 | speech, microphone | live_transcription, file_transcription, locale_listing |
ssh | Python 模块 | Python API | 网络与连接 | 无 | ssh_exec, sftp_upload, sftp_download |
storage | Python 模块 | Python API | 系统服务 | 无 | user_defaults, json_values |
storekit | Python 模块 | Python API | 系统服务 | 无 | iap_purchase, subscription_status, product_catalog |
translation | Python 模块 | Python API | 系统服务 | 无 | on_device_translation, language_listing |
video_recorder | Python 模块 | Python API | 媒体与视觉 | camera | video_recording |
vision | Python 模块 | Python API | 媒体与视觉 | 无 | ocr |
vision_helper | Python 模块 | Python API | 媒体与视觉 | 无 | face_detection, barcode_detection, rectangle_detection, classification |
weather | Python 模块 | Python API | 网络与连接 | location | current_conditions, daily_forecast, hourly_forecast |
websocket | Python 模块 | Python API | 网络与连接 | 无 | websocket_connect, send, receive, close |
#AppUI 原生组件入口
无独立 import 的系统 UI,通过 AppUI 组件触发:
| 组件入口 | AppUI 组件 | 文档 | 关联模块 |
|---|---|---|---|
camera_picker | CameraPicker | camera-module | photos |
file_importer | FileImporter | file-picker-module | — |
map_view | MapView | location-module | location, permission |
photo_picker | PhotoPicker | photos-module | photos |
player_controller | PlayerController | appui-ref-media | avplayer |
share_link | ShareLink | share-module | — |
video_player | VideoPlayer | appui-ref-media | avplayer |
web_view | WebView | appui-ref-media | — |
#专题页
同一能力的双入口说明(脚本模块 vs AppUI 组件):
| 专题 | 首选入口 | 文档 | 说明 |
|---|---|---|---|
camera | photos | camera-module | Camera capture via photos.capture_image or AppUI CameraPicker. |
file_picker | appui | file-picker-module | File selection has no import module; use AppUI FileImporter. |
share | appui | share-module | System share sheet has no import module; use AppUI ShareLink. |
#文档导航
侧边栏分组由 schema navigation.iosNative 投影,与 App 内文档导航一致:
#场景配方
| 目标 | 推荐组合 | 说明 |
|---|---|---|
| 选图并保存设置 | 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 | 请求放刷新回调 |
#高级与扩展
以下模块在 自动化与扩展 集合,或供进阶场景使用:
| 模块 | 用途 |
|---|---|
| shortcuts | 运行快捷指令、打开 URL/设置 |
| keyboard | 脚本编辑器键盘工具栏 |
| objc_util | Objective-C Runtime 底层访问 |
| c_extensions | 内置 C 扩展清单与替代路线 |
| 全部模块总览 | 按导入名浏览完整模块表 |
#平台与权限矩阵
| 能力 | 真机要求 | 权限 | 用户动作 | 推荐入口 |
|---|---|---|---|---|
| 相册、拍照 | 推荐真机 | photos / camera | 是 | photos |
| 定位、运动 | 真机 | location / motion | 是 | location、motion |
| HealthKit | 真机 | health | 是 | health |
| BLE | 真机 | bluetooth | 是 | bluetooth |
| NFC | 真机且支持 NFC | nfc | 是 | nfc |
| 本地通知 | 真机/模拟器部分可测 | notifications | 是 | notification |
| Vision / Core ML | 视系统能力 | 无 | 通常是 | vision、coreml |
| WebSocket | 需网络 | 无 | 否 | websocket |
| Keychain / Storage | App 环境 | 无 | 剪贴板推荐用户动作 | keychain、storage |
#常见错误
| 错误写法 | 后果 | 修正 |
|---|---|---|
在 body() 里调系统 API | 刷新时反复弹窗/扫描 | 放进按钮回调 |
| 权限被拒后循环申请 | 体验差、可能被拒 | 显示状态与设置入口 |
用户取消未处理 None | 崩溃或脏 UI | 保留原状态并提示 |
token 写入日志或 storage | 隐私风险 | 用 keychain |
| 真机能力在模拟器硬测 | 误判不可用 | 查平台矩阵,真机验证 |
#相关文档
| 文档 | 用途 |
|---|---|
| permission | 统一权限(侧边栏「基础与权限」) |
| photos | 相册与相机(「媒体 › 采集」) |
| notification | 本地通知(「界面与系统」) |
| live_activity | 锁屏实时活动(「界面与系统」) |
| shortcuts | 快捷指令(自动化与扩展) |
| 全部模块总览 | 完整模块字母/分类表(补充索引) |
#完整工作流示例
- 在 AppUI 页面用命名按钮触发原生能力。
import对应模块并检查权限/可用性。- 根据返回值更新
State,给用户可见反馈。 - 失败时保留当前页面并提示下一步。
#发布前检查
- 每个敏感能力都有权限说明与用户触发点
- 离线、取消、拒绝路径已覆盖
- API 名与 schema / 模块文档一致
#预期效果
运行示例后,界面应出现文档描述的目标结果;若与预期不符,请按「失败路径」排查。