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系统服务alarmsalarm_list, alarm_schedule, alarm_cancel
archivePython 模块Python API系统服务无zip_inspection, zip_extraction, zip_creation, native_archive_bridge, zip64, archive_entry_read, archive_entry_extract, archive_atomic_update, archive_progress, archive_cancellation, archive_metadata
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, background_upload, download_progress, transfer_pause_resume, durable_task_center, checksum_validation
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, blob_parameters, blob_results
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, loopback_only, http_get_head, http_single_range, bounded_file_streaming, session_isolated_server
keyboardPython 模块Python API自动化与扩展无toolbar_buttons, insert_text, set_buttons
keychainPython 模块Python API系统服务无secure_password_storage, service_listing
live_activityPython 模块Python API系统服务live_activitydynamic_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
native_imagePython 模块Python API媒体与视觉无image_inspection, native_image_processing, resize, thumbnail, crop, rotate, core_image_filters
networkPython 模块Python API网络与连接无http, http_streaming, server_sent_events, 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

#完整 Python 符号

模块公开 Python 符号
alarmis_available、request_authorization、schedule、cancel、list_alarms、AlarmError
archiveArchiveError、inspect、list、extract、read_entry、extract_entry、create、update、transaction、ArchiveTransaction、add、replace、remove、cancel、progress、new_operation_id
assistantis_available、list_tools、run、AssistantError
audio_recorderstart、stop、pause、resume、cancel、status、is_recording、duration、metering、AudioRecorderError
audio_sessionset_category、set_active、current_route、AudioSessionError
avplayerPlayer、load、play、pause、stop、seek、duration、current_time、is_playing、set_volume、set_rate、present_video、on_progress、stop_progress、on_end、cleanup
backgroundbegin_task、end_task、remaining_time、app_state、start_keep_alive、stop_keep_alive、schedule_refresh、schedule_processing
background_downloaddownload、upload、status、list、cancel、pause、resume、retry、BackgroundDownloadError
biometricbiometric_type、is_available、authenticate、authenticate_with_passcode
ble_peripheralstart_advertising、stop_advertising、status、update_value、BlePeripheralError
bluetoothstate、scan、stop_scan、connect、disconnect、discover_services、read、write
calendar_eventsauthorization_status、request_access、get_calendars、get_events、create_event、delete_event、request_reminder_access、get_reminders、create_reminder、complete_reminder、delete_reminder
clipboardget、set、clear、get_text、set_text
consolealert、hud_alert、input_alert、login_alert、password_alert、set_color、set_font、clear、write_link
contactsPERSON、ORGANIZATION、ContactsError、Person、Group、Container、PropertySelection、authorization_status、capabilities、is_authorized、request_access、get_all_people、get_person、get_me、find、find_by_phone、find_by_email、add_person、remove_person、save、revert、get_all_groups、get_group、add_group、remove_group、get_all_containers、get_default_container、get_people_in_group、get_people_in_container、get_groups_in_container、pick_contact、pick_contacts、pick_property、show_person、edit_person、new_person、export_vcards、import_vcards、get_change_history、manage_limited_access、localized_label
coremllist_models、load_model、predict_image、model_info
databaseDatabaseError、Database、Collection、open、connect、default_database、collection、database_path、close_default_database、close_all
devicename、model、system_name、system_version、identifier_for_vendor、battery_level、battery_state、orientation、screen_width、screen_height、screen_size、screen_scale、screen_brightness、set_screen_brightness、total_memory、processor_count、system_uptime、thermal_state、is_low_power_mode、locale、timezone、preferred_languages
dialogsalert、input_alert、list_dialog、form_dialog、date_dialog、hud_alert、editor
font_pickerpick、FontPickerError
foundation_modelsis_available、respond、summarize、explain_error、FoundationModelsError
hapticsimpact、notification、selection、success、warning、error、light、medium、heavy、is_supported、play、stop
healthis_available、request_authorization、authorization_status、query_steps、query_heart_rate、query_weight、save_weight、query_workouts、query_sleep、query_quantity、query_blood_pressure、summarize_blood_pressure
http_serverstart、stop、status、HttpServerError
keyboardadd_button、add_group、remove_button、clear、insert_text、insert_snippet、move_cursor、Button、set_buttons
keychainget_password、set_password、delete_password、get_services
live_activitystart、update、end、is_supported
locationauthorization_status、is_authorized、request_access、start_updates、stop_updates、get_location、start_heading、stop_heading、get_heading、reverse_geocode、geocode
mailcan_send、compose、MailError
media_composermerge_videos、merge_audio、export、MediaComposerError
messagecan_send、compose、MessageError
motionis_available、start_updates、stop_updates、start_accelerometer、stop_accelerometer、start_gyroscope、stop_gyroscope、start_magnetometer、stop_magnetometer、start_altimeter、stop_altimeter、get_acceleration、get_gravity、get_rotation_rate、get_magnetic_field、get_attitude、get_altitude
musicauthorization_status、request_authorization、play、play_song、play_songs、play_search_result、pause、skip_to_next、skip_to_previous、current_track、search、MusicError
music_playerPLAY_MODE_SEQUENCE、PLAY_MODE_REPEAT_ALL、PLAY_MODE_REPEAT_ONE、PLAY_MODE_SHUFFLE、MusicPlayerError、configure、set_queue、queue、current、add、remove、move、clear、prepare、prefetch_next、preload_state、play、pause、toggle、stop、next、previous、seek、set_play_mode、set_volume、set_rate、state、restore、on_event、off_event
native_imageinspect、process、resize、thumbnail、crop、rotate、NativeImageError
networkis_connected、connection_type、is_expensive、is_constrained、request、get、post、put、delete、patch、stream、download、Response、StreamResponse、StreamError
nfcis_available、scan、write
notificationrequest_permission、authorization_status、schedule、schedule_at_date、remove_pending、remove_all_pending、pending_count、pending_identifiers、set_badge
now_playingset_info、update_elapsed、clear、NowPlayingError
objc_utilc、LP64、CGFloat、NSInteger、NSUInteger、NSNotFound、NSUTF8StringEncoding、NS_UTF8、CGPoint、CGSize、CGVector、CGRect、CGAffineTransform、UIEdgeInsets、NSRange、sel、ObjCClass、ObjCInstance、ObjCClassMethod、ObjCInstanceMethod、NSObject、NSArray、NSMutableArray、NSDictionary、NSMutableDictionary、NSSet、NSMutableSet、NSString、NSMutableString、NSData、NSMutableData、NSNumber、NSURL、NSEnumerator、NSThread、NSBundle、UIColor、UIImage、UIBezierPath、UIApplication、UIView、ObjCBlock、ns、nsurl、retain_global、release_global、on_main_thread、create_objc_class、Structure、sizeof、byref、c_void_p、c_char、c_byte、c_char_p、c_double、c_float、c_int、c_longlong、c_short、c_bool、c_long、c_int32、c_ubyte、c_uint、c_ushort、c_ulong、c_ulonglong、POINTER、pointer、load_framework、nsdata_to_bytes、uiimage_to_png、autoreleasepool
pdfcreate_from_text、create_from_images、from_html、extract_text、info、page_image、preview、PDFError
permissionstatus、request、status_all、MODULES
photospick_image、capture_image、save_image、save_video、get_assets、pick_asset、get_image、Asset、AssetCollection、get_albums、get_smart_albums、get_moments、create_album、get_screenshots_album、get_recently_added_album、get_selfies_album、pick_image_base64、capture_image_base64、image_to_base64、base64_to_image、get_favorites、get_count、get_recent_images、get_image_size、get_metadata、is_available
qrcodegenerate、generate_base64、save、QRCodeError
shazamis_available、status、recognize、recognize_file、cancel、ShazamError
shortcutsrun_shortcut、open_url、open_settings
soundplay_effect、stop_effect、stop_all_effects、Player、MIDIPlayer、set_volume、set_honors_silent_switch、get_volume
speechsay、stop、pause、resume、is_speaking、available_voices
speech_recognitionis_available、supported_locales、start、status、text、is_listening、stop、cancel、recognize_file、SpeechRecognitionError
sshconnect、execute、upload、download、disconnect、SSHError
storageget、set、get_int、set_int、get_float、set_float、get_bool、set_bool、get_json、set_json、remove、has_key、all_keys、shared
storekitload_products、purchase、restore、subscription_status、show_manage_subscriptions、StoreKitError
translationis_available、supported_languages、translate、TranslationError
video_recorderstart、stop、cancel、status、VideoRecorderError
visionsetup_vision_framework、is_vision_available、recognize_text_from_image_data
vision_helpersetup_vision_framework、is_vision_available、detect_faces、detect_face_landmarks、detect_barcodes、classify_image、detect_rectangles、async_request、poll_result
weathercurrent、current_location、daily、hourly、WeatherError
websocketconnect、WebSocket

#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 / camera是photos
定位、运动真机location / motion是location、motion
HealthKit真机health是health
BLE真机bluetooth是bluetooth
NFC真机且支持 NFCnfc是nfc
本地通知真机/模拟器部分可测notifications是notification
Vision / Core ML视系统能力无通常是vision、coreml
WebSocket需网络无否websocket
Keychain / StorageApp 环境无剪贴板推荐用户动作keychain、storage

#常见错误

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

#相关文档

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

#完整工作流示例

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

#发布前检查

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

#预期效果

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