@heybox/hb-sdk 0.9.3-alpha.5 → 0.9.3-alpha.7

package/types/index.d.ts

@@ -3017,6 +3017,81 @@ interface MiniProgramUserModule {
     getSteamGameList(options?: GetSteamGameListOptions): Promise<GetSteamGameListResult>;
 }
 
+/** 可选择的媒体类型。 */
+type MediaType = 'image' | 'video';
+/**
+ * 系统选择器的媒体类型筛选。
+ *
+ * `all` 只表示图片与视频，**不包含音频或任意文件**。
+ */
+type MediaSelectionType = MediaType | 'all';
+/**
+ * `media.pick()` 的选择选项。
+ *
+ * @remarks
+ * 省略 options 或传 `{}` 等同于 `{ source: 'album', mediaType: 'all', maxCount: 1 }`。
+ * `camera` 分支最多只能选择一项，因此 `maxCount` 只能是 `1` 或省略。
+ */
+type PickMediaOptions = {
+    /** 媒体来源，缺省 `'album'` 打开系统图库。 */
+    source?: 'album';
+    /** 媒体类型筛选，缺省 `'all'`。 */
+    mediaType?: MediaSelectionType;
+    /** 最多可选数量，缺省 `1`，取值范围为 1–20 的安全整数。 */
+    maxCount?: number;
+} | {
+    /** 打开系统相机，成功时恰好返回一项。 */
+    source: 'camera';
+    /** 媒体类型筛选，缺省 `'all'`；`all` 表示用户可在系统界面内选择拍照或录像。 */
+    mediaType?: MediaSelectionType;
+    /** 相机最多只能选择一项，只能为 `1` 或省略。 */
+    maxCount?: 1;
+};
+interface MediaItemBase {
+    /** 对应的文件句柄，`mode` 固定为 `read`。 */
+    readonly file: FileHandle;
+    /** 实际交付的媒体表示对应的 MIME type，非空。 */
+    readonly mimeType: string;
+    /** 文件字节数，非负安全整数。 */
+    readonly size: number;
+    /** 已考虑方向信息后的显示宽度（像素），正安全整数。 */
+    readonly width: number;
+    /** 已考虑方向信息后的显示高度（像素），正安全整数。 */
+    readonly height: number;
+    /** 受控、绑定当前会话的预览地址，非空。 */
+    readonly previewUrl: string;
+}
+/** 选择的图片项。 */
+interface MediaImageItem extends MediaItemBase {
+    readonly type: 'image';
+}
+/** 选择的视频项，额外携带时长。 */
+interface MediaVideoItem extends MediaItemBase {
+    readonly type: 'video';
+    /** 视频时长（毫秒），非负安全整数。 */
+    readonly durationMs: number;
+}
+/** 单次媒体选择的返回项。 */
+type MediaItem = MediaImageItem | MediaVideoItem;
+/** 当前 SDK session 的媒体选择模块。 */
+interface MediaModule {
+    /**
+     * 打开系统图库或相机并返回用户确认的媒体文件。
+     *
+     * @param options - 媒体来源、类型筛选与数量上限，省略时使用全部缺省值。
+     * @returns 冻结的只读媒体项数组；每项的 `file` 是只读 `FileHandle` 代理。
+     * @since 0.9.3
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbClient android numeric-dot \>= 1.3.398
+     * @hbClient ios numeric-dot \>= 1.3.398
+     * @hbClient ohos numeric-dot \>= 1.3.396
+     * @experimental
+     */
+    pick(options?: PickMediaOptions): Promise<readonly MediaItem[]>;
+}
+
 /**
  * 小程序可选分享渠道。
  *
@@ -3685,6 +3760,13 @@ interface MiniProgramViewportModule {
     /**
      * 设置当前小程序的窗口方向和全屏状态。
      *
+     * SDK `1.0.0` 计划将本方法调整为 `Promise<void>`：设置完成时正常返回，不支持时抛出明确错误；
+     * 切换失败、超时或取消仍抛出对应错误。当前仍返回 `{ supported: boolean }`，现有行为保持不变。
+     *
+     * 请提前补齐 `try/catch`，过渡期保留 `supported: false` 判断，并先检查返回值是否存在再读取该字段；
+     * 避免直接解构返回值或将未来的空返回值当作失败。仅在确认设置成功后继续依赖该设置的操作。
+     * 不支持时的错误码与适配期限会在 `1.0.0` 正式发布前公告，并提供预发布版本验证。
+     *
      * @param options - 方向与全屏目标，至少提供一个字段；省略的字段保持当前目标值。
      * @returns Host 完成原生方向与胶囊设置、布局稳定后返回 `{ supported: true }`；能力缺失或
      * 请求不受支持时返回 `{ supported: false }`，调用方仍应按实际窗口与安全区布局。
@@ -7738,6 +7820,8 @@ declare const storage: MiniProgramStorageModule;
 declare const network: MiniProgramNetworkModule;
 /** 默认 SDK 实例的 files 模块。 */
 declare const files: FilesModule;
+/** 默认 SDK 实例的 media 模块。 */
+declare const media: MediaModule;
 /** 默认 SDK 实例的 UI 模块。 */
 declare const ui: MiniProgramUiModule;
 /** 默认 SDK 实例的 device 模块。 */
@@ -7764,6 +7848,7 @@ declare const hbSDK: {
     viewport: MiniProgramViewportModule;
     storage: MiniProgramStorageModule;
     files: FilesModule;
+    media: MediaModule;
     network: MiniProgramNetworkModule;
     ui: MiniProgramUiModule;
     device: MiniProgramDeviceModule;
@@ -7774,5 +7859,5 @@ declare const hbSDK: {
     workspaceCards: WorkspaceCardsModule;
 };
 
-export { HbMiniProgramNetworkError, HbMiniProgramSDKError, auth, cloud, companion, hbSDK as default, device, environment, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport, workspaceCards };
-export type { ClosePayload, CloseResult, CompanionAttachments, CompanionExitHandler, CompanionNotification, CompanionNotifications, CompanionOutputHandler, CompanionOwnershipLostHandler, CompanionPrepareOptions, CompanionSession, CompanionState, CompanionStateChangeHandler, CompanionStdio, CopyLinkPayload, CopyLinkResult, CreateOptions, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, ListOptions, LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAppPageTarget, MiniProgramAuthModule, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, MiniProgramCloudStorageModule, MiniProgramCompanionModule, MiniProgramCopyLinkOptions, MiniProgramDeviceModule, MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramEventHandler, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationModule, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler, MiniProgramSafeArea, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramSetNavigationBarStyleOptions, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, MiniProgramStorageModule, MiniProgramToastStatus, MiniProgramUiModule, MiniProgramUserModule, MiniProgramVibrateIntensity, MiniProgramViewportModule, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPageOptions, OpenGameDetailAppPagePayload, OpenMiniProgramAppPageOptions, OpenMiniProgramAppPagePayload, OpenPostDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenUserDetailAppPageOptions, OpenUserDetailAppPagePayload, PathRoot, PickDirectoryOptions, PickFilesOptions, ReloadPayload, ReloadResult, RemoveOptions, RevokeAuthorizationPayload, RevokeAuthorizationResult, SaveFileOptions, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UploadBaseOptions, UploadOptions, UploadProgress, UploadResponse, VibratePayload, VibrateResult, WorkspaceCardsModule };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, auth, cloud, companion, hbSDK as default, device, environment, files, getHandshakeState, media, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport, workspaceCards };
+export type { ClosePayload, CloseResult, CompanionAttachments, CompanionExitHandler, CompanionNotification, CompanionNotifications, CompanionOutputHandler, CompanionOwnershipLostHandler, CompanionPrepareOptions, CompanionSession, CompanionState, CompanionStateChangeHandler, CompanionStdio, CopyLinkPayload, CopyLinkResult, CreateOptions, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, ListOptions, LoginOptions, LoginPayload, LoginResult, LoginScope, MediaImageItem, MediaItem, MediaModule, MediaSelectionType, MediaType, MediaVideoItem, MiniProgramAppPageTarget, MiniProgramAuthModule, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, MiniProgramCloudStorageModule, MiniProgramCompanionModule, MiniProgramCopyLinkOptions, MiniProgramDeviceModule, MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramEventHandler, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationModule, MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler, MiniProgramSafeArea, MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramSetNavigationBarStyleOptions, MiniProgramShareChannel, MiniProgramShareExtraValue, MiniProgramShareModule, MiniProgramSharePostOptions, MiniProgramShowShareMenuOptions, MiniProgramStorageModule, MiniProgramToastStatus, MiniProgramUiModule, MiniProgramUserModule, MiniProgramVibrateIntensity, MiniProgramViewportModule, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPageOptions, OpenGameDetailAppPagePayload, OpenMiniProgramAppPageOptions, OpenMiniProgramAppPagePayload, OpenPostDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenUserDetailAppPageOptions, OpenUserDetailAppPagePayload, PathRoot, PickDirectoryOptions, PickFilesOptions, PickMediaOptions, ReloadPayload, ReloadResult, RemoveOptions, RevokeAuthorizationPayload, RevokeAuthorizationResult, SaveFileOptions, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UploadBaseOptions, UploadOptions, UploadProgress, UploadResponse, VibratePayload, VibrateResult, WorkspaceCardsModule };

package/types/miniapp-publish/index.d.ts

@@ -222,7 +222,7 @@ declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
     window?: MiniappWindowDeclaration | undefined;
     workspaceCards?: WorkspaceCardsManifest | undefined;
     companions?: MiniappCompanionManifestDeclarations | undefined;
-    permissions?: Partial<Record<"storage" | "workspaceCards" | "userInfo" | "steamLibrary" | "share" | "cloud_storage" | "filesystem" | "clipboard" | "leaderboard" | "companion" | "appProtocol", SimpleMiniappPermissionDeclaration> & {
+    permissions?: Partial<Record<"storage" | "workspaceCards" | "userInfo" | "steamLibrary" | "share" | "cloud_storage" | "filesystem" | "media" | "clipboard" | "leaderboard" | "companion" | "appProtocol", SimpleMiniappPermissionDeclaration> & {
         network: NetworkMiniappPermissionDeclaration;
     }> | undefined;
     platforms: readonly ("windows" | "macos" | "android" | "ios" | "ohos" | "linux")[];

package/types/protocol.d.ts

@@ -1,5 +1,5 @@
 import { MiniProgramEventName, MiniProgramEventPayloadMap, LoginScope as LoginScope$1 } from '@heybox/hb-sdk-protocol';
-export { AUTH_GET_ACCOUNT_STATE_METHOD, AUTH_LOGIN_METHOD, AccountState, AuthorizedUserInfo, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, CLOUD_STORAGE_GET_KEYS_METHOD, CLOUD_STORAGE_GET_STORAGE_METHOD, CLOUD_STORAGE_REMOVE_ITEM_METHOD, CLOUD_STORAGE_SET_STORAGE_METHOD, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, GetAccountStatePayload, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, MiniProgramAuthMethod, MiniProgramBridgeCancelMessage, MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeMethod, MiniProgramBridgeProgressMessage, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDisplayState, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMethod, MiniProgramFileMode, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramFilesMethod, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramOrientationMode, MiniProgramPathRootRef, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionEntry, MiniProgramRuntimePermissionStatus, MiniProgramRuntimePermissionsSnapshot, MiniProgramSafeArea, MiniProgramSandboxRootRef, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_UPLOAD_METHOD, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, NetworkUploadPayload, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenMiniProgramAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, ParsedMiniProgramRuntimePermissions, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, RUNTIME_LOCATION_PROBE_METHOD, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, SaveFilePayload, SaveFileResult, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetDisplayPayload, SetDisplayResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, UploadProgressPayload, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, VibratePayload, VibrateResult, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions } from '@heybox/hb-sdk-protocol';
+export { AUTH_GET_ACCOUNT_STATE_METHOD, AUTH_LOGIN_METHOD, AccountState, AuthorizedUserInfo, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, CLOUD_STORAGE_GET_KEYS_METHOD, CLOUD_STORAGE_GET_STORAGE_METHOD, CLOUD_STORAGE_REMOVE_ITEM_METHOD, CLOUD_STORAGE_SET_STORAGE_METHOD, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, GetAccountStatePayload, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MEDIA_PICK_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, MediaPickImageItem, MediaPickItem, MediaPickItemBase, MediaPickPayload, MediaPickResult, MediaPickVideoItem, MiniProgramAuthMethod, MiniProgramBridgeCancelMessage, MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeMethod, MiniProgramBridgeProgressMessage, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDisplayState, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMethod, MiniProgramFileMode, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramFilesMethod, MiniProgramMediaMethod, MiniProgramMediaSelectionType, MiniProgramMediaSource, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramOrientationMode, MiniProgramPathRootRef, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionEntry, MiniProgramRuntimePermissionStatus, MiniProgramRuntimePermissionsSnapshot, MiniProgramSafeArea, MiniProgramSandboxRootRef, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_UPLOAD_METHOD, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, NetworkUploadPayload, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenMiniProgramAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, ParsedMiniProgramRuntimePermissions, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, RUNTIME_LOCATION_PROBE_METHOD, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, SaveFilePayload, SaveFileResult, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetDisplayPayload, SetDisplayResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, UploadProgressPayload, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, VibratePayload, VibrateResult, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramMediaPickItem, isMiniProgramMediaPickPayload, isMiniProgramMediaPickResult, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions } from '@heybox/hb-sdk-protocol';
 
 /**
  * 小程序生命周期或业务事件监听函数。
@@ -1884,6 +1884,81 @@ interface GetSteamGameListOptions {
     includeHidden?: boolean;
 }
 
+/** 可选择的媒体类型。 */
+type MediaType = 'image' | 'video';
+/**
+ * 系统选择器的媒体类型筛选。
+ *
+ * `all` 只表示图片与视频，**不包含音频或任意文件**。
+ */
+type MediaSelectionType = MediaType | 'all';
+/**
+ * `media.pick()` 的选择选项。
+ *
+ * @remarks
+ * 省略 options 或传 `{}` 等同于 `{ source: 'album', mediaType: 'all', maxCount: 1 }`。
+ * `camera` 分支最多只能选择一项，因此 `maxCount` 只能是 `1` 或省略。
+ */
+type PickMediaOptions = {
+    /** 媒体来源，缺省 `'album'` 打开系统图库。 */
+    source?: 'album';
+    /** 媒体类型筛选，缺省 `'all'`。 */
+    mediaType?: MediaSelectionType;
+    /** 最多可选数量，缺省 `1`，取值范围为 1–20 的安全整数。 */
+    maxCount?: number;
+} | {
+    /** 打开系统相机，成功时恰好返回一项。 */
+    source: 'camera';
+    /** 媒体类型筛选，缺省 `'all'`；`all` 表示用户可在系统界面内选择拍照或录像。 */
+    mediaType?: MediaSelectionType;
+    /** 相机最多只能选择一项，只能为 `1` 或省略。 */
+    maxCount?: 1;
+};
+interface MediaItemBase {
+    /** 对应的文件句柄，`mode` 固定为 `read`。 */
+    readonly file: FileHandle;
+    /** 实际交付的媒体表示对应的 MIME type，非空。 */
+    readonly mimeType: string;
+    /** 文件字节数，非负安全整数。 */
+    readonly size: number;
+    /** 已考虑方向信息后的显示宽度（像素），正安全整数。 */
+    readonly width: number;
+    /** 已考虑方向信息后的显示高度（像素），正安全整数。 */
+    readonly height: number;
+    /** 受控、绑定当前会话的预览地址，非空。 */
+    readonly previewUrl: string;
+}
+/** 选择的图片项。 */
+interface MediaImageItem extends MediaItemBase {
+    readonly type: 'image';
+}
+/** 选择的视频项，额外携带时长。 */
+interface MediaVideoItem extends MediaItemBase {
+    readonly type: 'video';
+    /** 视频时长（毫秒），非负安全整数。 */
+    readonly durationMs: number;
+}
+/** 单次媒体选择的返回项。 */
+type MediaItem = MediaImageItem | MediaVideoItem;
+/** 当前 SDK session 的媒体选择模块。 */
+interface MediaModule {
+    /**
+     * 打开系统图库或相机并返回用户确认的媒体文件。
+     *
+     * @param options - 媒体来源、类型筛选与数量上限，省略时使用全部缺省值。
+     * @returns 冻结的只读媒体项数组；每项的 `file` 是只读 `FileHandle` 代理。
+     * @since 0.9.3
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbClient android numeric-dot \>= 1.3.398
+     * @hbClient ios numeric-dot \>= 1.3.398
+     * @hbClient ohos numeric-dot \>= 1.3.396
+     * @experimental
+     */
+    pick(options?: PickMediaOptions): Promise<readonly MediaItem[]>;
+}
+
 /**
  * 小程序可选分享渠道。
  *
@@ -2105,4 +2180,4 @@ interface MiniProgramSetNavigationBarStyleOptions {
     foregroundStyle: MiniProgramNavigationBarForegroundStyle;
 }
 
-export type { CreateOptions, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GetSteamGameListOptions, ListOptions, LoginOptions, MiniProgramEventHandler, MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramScreenshotOptions, MiniProgramSetNavigationBarStyleOptions, MiniProgramShowShareMenuOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions };
+export type { CreateOptions, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GetSteamGameListOptions, ListOptions, LoginOptions, MediaImageItem, MediaItem, MediaModule, MediaSelectionType, MediaType, MediaVideoItem, MiniProgramEventHandler, MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramScreenshotOptions, MiniProgramSetNavigationBarStyleOptions, MiniProgramShowShareMenuOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, PickMediaOptions, RemoveOptions, SaveFileOptions };