@heybox/hb-sdk 0.4.3 → 0.4.5

package/skill/references/api-protocol.md

@@ -38,17 +38,25 @@ export type {
 } from './protocol/types';
 export {
   AUTH_LOGIN_METHOD,
+  DEVICE_SET_CLIPBOARD_METHOD,
+  DEVICE_VIBRATE_METHOD,
   MINI_PROGRAM_PROTOCOL_CAPABILITIES,
+  NAVIGATION_CLOSE_METHOD,
+  NAVIGATION_RELOAD_METHOD,
   NETWORK_REQUEST_METHOD,
   SHARE_SCREENSHOT_METHOD,
   SHARE_SHOW_SHARE_MENU_METHOD,
   STORAGE_GET_STORAGE_METHOD,
   STORAGE_SET_STORAGE_METHOD,
+  UI_HIDE_LOADING_METHOD,
+  UI_SHOW_LOADING_METHOD,
+  UI_SHOW_TOAST_METHOD,
   USER_GET_INFO_METHOD,
   VIEWPORT_GET_WINDOW_INFO_METHOD,
   VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
 } from './protocol/capabilities';
 export type {
+  MiniProgramDeviceMethod,
   MiniProgramAuthMethod,
   MiniProgramBridgeMethod,
   MiniProgramCapabilityDefinition,
@@ -58,9 +66,11 @@ export type {
   MiniProgramCapabilityResult,
   MiniProgramCapabilityResultMap,
   MiniProgramCapabilityRisk,
+  MiniProgramNavigationMethod,
   MiniProgramNetworkMethod,
   MiniProgramShareMethod,
   MiniProgramStorageMethod,
+  MiniProgramUiMethod,
   MiniProgramUserMethod,
   MiniProgramViewportMethod,
 } from './protocol/capabilities';
@@ -104,6 +114,28 @@ export type {
   NetworkRequestPayload,
   NetworkResponsePayload,
 } from './modules/network';
+export type {
+  HideLoadingPayload,
+  HideLoadingResult,
+  MiniProgramToastStatus,
+  ShowLoadingPayload,
+  ShowLoadingResult,
+  ShowToastPayload,
+  ShowToastResult,
+} from './modules/ui';
+export type {
+  MiniProgramVibrateIntensity,
+  SetClipboardPayload,
+  SetClipboardResult,
+  VibratePayload,
+  VibrateResult,
+} from './modules/device';
+export type {
+  ClosePayload,
+  CloseResult,
+  ReloadPayload,
+  ReloadResult,
+} from './modules/navigation';
 ```
 
 ## Protocol context
@@ -136,5 +168,5 @@ Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 3 | 4 | 23 | 20 | 0 |
-| Protocol API | 0 | 1 | 21 | 32 | 14 |
+| Root API | 3 | 4 | 30 | 32 | 3 |
+| Protocol API | 0 | 1 | 25 | 47 | 21 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.4.3`
+- Version at generation time: `0.4.5`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -30,7 +30,7 @@
 export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
 export type { MiniProgramSDKOptions } from './core/client';
-export { ready, on, off, auth, user, share, viewport, storage, network } from './core/singleton';
+export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation } from './core/singleton';
 export type {
   MiniProgramEventHandler,
   MiniProgramEventName,
@@ -83,8 +83,33 @@ export type {
   NetworkRequestPayload,
   NetworkResponsePayload,
 } from './modules/network';
+export type {
+  HideLoadingPayload,
+  HideLoadingResult,
+  MiniProgramToastStatus,
+  MiniProgramUiModule,
+  ShowLoadingPayload,
+  ShowLoadingResult,
+  ShowToastPayload,
+  ShowToastResult,
+} from './modules/ui';
+export type {
+  MiniProgramDeviceModule,
+  MiniProgramVibrateIntensity,
+  SetClipboardPayload,
+  SetClipboardResult,
+  VibratePayload,
+  VibrateResult,
+} from './modules/device';
+export type {
+  ClosePayload,
+  CloseResult,
+  MiniProgramNavigationModule,
+  ReloadPayload,
+  ReloadResult,
+} from './modules/navigation';
 
-import { auth, network, off, on, ready, share, storage, viewport, user } from './core/singleton';
+import { auth, device, navigation, network, off, on, ready, share, storage, ui, viewport, user } from './core/singleton';
 
 const hbSDK = {
   ready,
@@ -96,6 +121,9 @@ const hbSDK = {
   viewport,
   storage,
   network,
+  ui,
+  device,
+  navigation,
 };
 
 export default hbSDK;
@@ -192,7 +220,7 @@ export default defineConfig({
 
 - 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
 - `package.json.version` 不是非空字符串：`vite build` 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
+- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk remote deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
 - 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
 
 `manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
@@ -327,6 +355,53 @@ await share.screenshot({
 });
 ```
 
+### 基础 UI
+
+```ts
+import { ui } from '@heybox/hb-sdk';
+
+await ui.showToast({
+  message: '保存成功',
+  status: 'success',
+});
+
+await ui.showLoading({
+  dismissible: true,
+});
+
+await ui.hideLoading();
+```
+
+`showToast()` 的 `message` 会 trim 后发送给宿主，不能为空，最长 120 个字符；`status` 只支持 `success` 和 `error`，不传时展示普通文本 toast。loading 是全局单例，多次 `showLoading()` 会覆盖当前配置，`hideLoading()` 在未展示时也会成功。
+
+### 设备能力
+
+```ts
+import { device } from '@heybox/hb-sdk';
+
+await device.vibrate({
+  intensity: 'light',
+  delay: 0,
+});
+
+await device.setClipboard({
+  text: 'hello',
+});
+```
+
+`vibrate()` 的 `intensity` 默认为 `light`，还支持 `medium` 和 `heavy`；`delay` 默认为 `0`，必须是 `0..5000` 的整数毫秒。`setClipboard()` 第一版只支持文本写入，`text` 必须是非空字符串，最长 10000 个字符，不会自动 trim 写入内容，也不提供读取或清空剪贴板能力。
+
+### 导航控制
+
+```ts
+import { navigation } from '@heybox/hb-sdk';
+
+await navigation.reload();
+await navigation.close();
+```
+
+`navigation.close()` 请求宿主关闭当前小程序容器，`navigation.reload()` 请求宿主重载当前小程序页面/容器。调用后 JS 上下文可能被宿主销毁，不保证后续代码继续执行；这两个能力不接受 `reason`、`force`、`confirm` 或 `fallbackUrl` 等扩展参数。
+
 ### 窗口信息
 
 ```ts