PythonIDE Docs
中文
简体中文

iOS 原生能力

相册、联系人、权限、相机、控制台和安全存储。

iOS 原生 Python 模块总入口:按任务选模块、组合调用、权限与真机要求速查。

边界:这是 能力索引页,不是 import 名。具体 API 见各模块文档;系统面板、硬件扫描、权限申请必须由按钮或菜单触发,不要在 AppUI body() 或模块导入时自动执行。

#模块概览

说明
导入按任务 import 对应模块(如 import photos
适合做什么相册、定位、通知、蓝牙、健康、网络等系统能力
调用时机按钮/刷新/选择器触发;body() 只展示 State
敏感数据token/密钥 → keychain;普通设置 → storage
文档导航schema navigation.iosNative 投影;见下方 文档导航
下一步按场景配方选模块 → 打开模块页 → 复制 AppUI 示例

#快速开始

相册、剪贴板、HUD 与钥匙串组合(函数式,适合脚本调试):

python
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 示例

设备信息、本地快照与通知提醒组合;原生调用均在按钮回调里。

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 参考

#先选模块

目标首选模块注意
查询或申请权限permission只在用户点击后申请
选择、拍照、保存图片photos取消返回 None,要先判断
保存 token、密码keychain不要写到 storage 或日志
保存普通设置storage主题、开关、筛选条件
弹窗、HUD、输入console / dialogs短反馈用 HUD
定位、运动、健康、蓝牙、NFC对应模块先展示用途再请求
网络、WebSocketnetwork / websocket勿在 body() 发请求
快捷指令、Live Activityshortcuts / live_activity需明确用户动作

#入口模型

所有原生能力入口由同一套能力清单统一定义(App 内与 Agent 共用)。先判断入口类型,再打开对应文档。

入口类型第一行写什么文档入口
Python 模块import <module>API 参考 › Python 模块
AppUI 原生组件import appui + 组件名API 参考 › AppUI 原生组件
专题页见专题页「首选入口」API 参考 › 专题页
参考见参考页说明c_extensions

#Python 模块

完整 Python import 模块表(含类型与呈现方式):

模块类型呈现分类权限能力
alarmPython 模块Python API系统服务alarm_schedule, alarm_cancel
assistantPython 模块Python API系统服务assistant_tools, device_context_answers
audio_recorderPython 模块Python API媒体与视觉microphonemicrophone_capture, recording_control, level_metering
audio_sessionPython 模块Python API媒体与视觉audio_session_category, audio_route_query
avplayerPython 模块Python API媒体与视觉audio_video_load, playback_control, native_player
backgroundPython 模块Python API网络与连接background_task, remaining_time, app_state
background_downloadPython 模块Python API网络与连接background_download, download_progress
biometricPython 模块系统表单设备与传感器biometricface_id, touch_id, passcode_fallback
ble_peripheralPython 模块Python API网络与连接ble_peripheral_advertising, ble_characteristic_update
bluetoothPython 模块Python API网络与连接bluetoothble_scan, ble_connect, read, write
c_extensions参考参考清单网络与连接扩展清单, 兼容性说明
calendar_eventsPython 模块系统选择器系统服务calendar, reminderscalendar_read, calendar_write, reminders
clipboardPython 模块Python API系统服务read_clipboard, write_clipboard, clear_clipboard
consolePython 模块系统表单系统服务hud, alerts, input_dialogs
contactsPython 模块系统选择器系统服务contactscontacts_read, contacts_picker, contacts_edit
coremlPython 模块Python API媒体与视觉model_listing, model_loading, image_prediction
databasePython 模块Python API系统服务sqlite, native_sqlite_bridge, collections, transactions
devicePython 模块Python API设备与传感器device_state, screen, battery, thermal_state
dialogsPython 模块系统表单系统服务native_dialogs, forms, pickers
font_pickerPython 模块系统表单系统服务font_picker_ui
foundation_modelsPython 模块Python API系统服务on_device_generation, summarization, error_explanation
hapticsPython 模块Python API设备与传感器impact_feedback, notification_feedback, core_haptics
healthPython 模块Python API设备与传感器healthsteps, heart_rate, sleep, body_metrics
http_serverPython 模块Python API网络与连接local_http_server, file_serving
keyboardPython 模块Python API自动化与扩展toolbar_buttons, insert_text, set_buttons
keychainPython 模块Python API系统服务secure_password_storage, service_listing
live_activityPython 模块Python API系统服务dynamic_island, lock_screen_activity
locationPython 模块Python API设备与传感器locationgps, heading, geocoding
mailPython 模块撰写界面系统服务mail_compose, attachment_send
media_composerPython 模块Python API媒体与视觉video_merge, audio_mux, media_export
messagePython 模块撰写界面系统服务sms_compose, imessage_compose
motionPython 模块Python API设备与传感器motionaccelerometer, gyroscope, attitude, barometer
musicPython 模块Python API媒体与视觉music_playback, catalog_search
music_playerPython 模块Python API媒体与视觉music_queue, playback_control, play_mode, now_playing_metadata, remote_commands, playback_restore, progress_events, queue_preload, preload_events
networkPython 模块Python API网络与连接http, download, connectivity
nfcPython 模块系统选择器系统服务nfcndef_scan, ndef_write
notificationPython 模块Python API系统服务notificationslocal_notifications, badges, scheduled_alerts
now_playingPython 模块Python API媒体与视觉now_playing_metadata, playback_progress
objc_utilPython 模块Python API自动化与扩展Objective-C 运行时, 系统框架访问
pdfPython 模块Python API媒体与视觉pdf_creation, text_extraction, page_rendering, quicklook_preview
permissionPython 模块Python API系统服务permission_status, permission_request
photosPython 模块Python API媒体与视觉photos, cameraphoto_picker, camera_capture, photo_save, video_save, asset_read
qrcodePython 模块Python API媒体与视觉qr_generation, png_export
shazamPython 模块Python API媒体与视觉microphonemusic_identification, microphone_recognition, file_recognition
shortcutsPython 模块Python API自动化与扩展run_shortcut, open_url, open_settings
soundPython 模块Python API媒体与视觉sound_effects, audio_player
speechPython 模块Python API媒体与视觉speechtext_to_speech, voice_listing
speech_recognitionPython 模块Python API媒体与视觉speech, microphonelive_transcription, file_transcription, locale_listing
sshPython 模块Python API网络与连接ssh_exec, sftp_upload, sftp_download
storagePython 模块Python API系统服务user_defaults, json_values
storekitPython 模块Python API系统服务iap_purchase, subscription_status, product_catalog
translationPython 模块Python API系统服务on_device_translation, language_listing
video_recorderPython 模块Python API媒体与视觉cameravideo_recording
visionPython 模块Python API媒体与视觉ocr
vision_helperPython 模块Python API媒体与视觉face_detection, barcode_detection, rectangle_detection, classification
weatherPython 模块Python API网络与连接locationcurrent_conditions, daily_forecast, hourly_forecast
websocketPython 模块Python API网络与连接websocket_connect, send, receive, close

#AppUI 原生组件入口

无独立 import 的系统 UI,通过 AppUI 组件触发:

组件入口AppUI 组件文档关联模块
camera_pickerCameraPickercamera-modulephotos
file_importerFileImporterfile-picker-module
map_viewMapViewlocation-modulelocation, permission
photo_pickerPhotoPickerphotos-modulephotos
player_controllerPlayerControllerappui-ref-mediaavplayer
share_linkShareLinkshare-module
video_playerVideoPlayerappui-ref-mediaavplayer
web_viewWebViewappui-ref-media

#专题页

同一能力的双入口说明(脚本模块 vs AppUI 组件):

专题首选入口文档说明
cameraphotoscamera-moduleCamera capture via photos.capture_image or AppUI CameraPicker.
file_pickerappuifile-picker-moduleFile selection has no import module; use AppUI FileImporter.
shareappuishare-moduleSystem 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_utilObjective-C Runtime 底层访问
c_extensions内置 C 扩展清单与替代路线
全部模块总览按导入名浏览完整模块表

#平台与权限矩阵

能力真机要求权限用户动作推荐入口
相册、拍照推荐真机photos / cameraphotos
定位、运动真机location / motionlocationmotion
HealthKit真机healthhealth
BLE真机bluetoothbluetooth
NFC真机且支持 NFCnfcnfc
本地通知真机/模拟器部分可测notificationsnotification
Vision / Core ML视系统能力通常是visioncoreml
WebSocket需网络websocket
Keychain / StorageApp 环境剪贴板推荐用户动作keychainstorage

#常见错误

错误写法后果修正
body() 里调系统 API刷新时反复弹窗/扫描放进按钮回调
权限被拒后循环申请体验差、可能被拒显示状态与设置入口
用户取消未处理 None崩溃或脏 UI保留原状态并提示
token 写入日志或 storage隐私风险keychain
真机能力在模拟器硬测误判不可用查平台矩阵,真机验证

#相关文档

文档用途
permission统一权限(侧边栏「基础与权限」)
photos相册与相机(「媒体 › 采集」)
notification本地通知(「界面与系统」)
live_activity锁屏实时活动(「界面与系统」)
shortcuts快捷指令(自动化与扩展)
全部模块总览完整模块字母/分类表(补充索引)

#完整工作流示例

  1. 在 AppUI 页面用命名按钮触发原生能力。
  2. import 对应模块并检查权限/可用性。
  3. 根据返回值更新 State,给用户可见反馈。
  4. 失败时保留当前页面并提示下一步。

#发布前检查

  • 每个敏感能力都有权限说明与用户触发点
  • 离线、取消、拒绝路径已覆盖
  • API 名与 schema / 模块文档一致

#预期效果

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