@doubao-dev/framework 0.0.39 → 0.0.40

package/dist/api.d.ts

@@ -47,6 +47,153 @@ export declare enum ActionDirectiveType {
     FORM_SUBMIT = "form_submit"
 }
 
+/**
+ * 向系统日历添加事件。
+ *
+ * @example
+ * ```typescript
+ * import { addPhoneCalendar } from '@doubao-dev/framework/api';
+ *
+ * const startTime = Math.floor(Date.now() / 1000) + 3600;
+ *
+ * await addPhoneCalendar({
+ *   title: '项目评审',
+ *   startTime,
+ *   endTime: startTime + 1800,
+ *   alarm: true,
+ *   alarmOffset: 300
+ * });
+ * ```
+ *
+ * @since 0.0.19
+ * @contractStatus verified | Android、iOS 均支持向系统日历写入一次性事件；成功通过 Promise resolve 空对象，失败通过 Promise reject。
+ * @platformSupport Android | supported | 写入系统日历事件；path 传入后按原值追加到日历备注。
+ * @platformSupport iOS | supported | 写入系统日历事件；path 传入后按原值追加到日历备注。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission applet | scope.addPhoneCalendar | required | Android,iOS | 需要在 manifest 中声明 scope.addPhoneCalendar，并由用户授权写入系统日历。
+ * @authorizationBehavior Android | 首次调用会依次申请应用日历授权和系统日历读写权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @authorizationBehavior iOS | 首次调用会依次申请应用日历授权和系统日历写入权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @precondition iOS | 设备需要存在可写入的系统日历账户。
+ * @usageNote All | startTime、endTime 使用 Unix 秒级时间戳；alarmOffset 单位为秒，Android 系统日历提醒粒度会按分钟处理。
+ * @errorCode none | - | - | Android,iOS | 当前失败通过 Promise reject 返回文本信息，未稳定返回顶层 errNo/errMsg | 根据异常信息检查授权、日历账户和时间参数
+ *
+ * @public
+ */
+export declare const addPhoneCalendar: (params: AddPhoneCalendarParams) => Promise<object>;
+
+/**
+ * 添加系统日历事件的请求参数。
+ *
+ * @public
+ */
+export declare interface AddPhoneCalendarParams {
+    /** 日历事件标题。 */
+    title: string;
+    /** 开始时间的 Unix 秒级时间戳。 */
+    startTime: number;
+    /**
+     * 是否为全天事件。
+     *
+     * @default false
+     */
+    allDay?: boolean;
+    /**
+     * 事件描述。
+     *
+     * @default -
+     */
+    description?: string;
+    /**
+     * 事件位置。
+     *
+     * @default -
+     */
+    location?: string;
+    /**
+     * 结束时间的 Unix 秒级时间戳。
+     *
+     * @default startTime
+     */
+    endTime?: number;
+    /**
+     * 是否提醒。
+     *
+     * @default true
+     */
+    alarm?: boolean;
+    /**
+     * 提前提醒时间，单位秒。0 表示开始时提醒。
+     *
+     * @default 0
+     */
+    alarmOffset?: number;
+    /**
+     * 跳转链接或客户端路由。传入后按原值追加到日历备注。
+     *
+     * @default -
+     */
+    path?: string;
+}
+
+/**
+ * 向系统日历添加重复事件。
+ *
+ * @example
+ * ```typescript
+ * import { addPhoneRepeatCalendar } from '@doubao-dev/framework/api';
+ *
+ * const startTime = Math.floor(Date.now() / 1000) + 3600;
+ *
+ * await addPhoneRepeatCalendar({
+ *   title: '每周例会',
+ *   startTime,
+ *   endTime: startTime + 1800,
+ *   repeatInterval: 'week'
+ * });
+ * ```
+ *
+ * @since 0.0.25
+ * @contractStatus verified | Android、iOS 均支持向系统日历写入重复事件；成功通过 Promise resolve 空对象，失败通过 Promise reject。
+ * @platformSupport Android | supported | 写入系统日历重复事件；repeatInterval 支持 day、week、month、year，path 行为与 addPhoneCalendar 一致。
+ * @platformSupport iOS | supported | 写入系统日历重复事件；repeatInterval 支持 day、week、month、year，path 行为与 addPhoneCalendar 一致。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission applet | scope.addPhoneCalendar | required | Android,iOS | 需要在 manifest 中声明 scope.addPhoneCalendar，并由用户授权写入系统日历。
+ * @authorizationBehavior Android | 首次调用会依次申请应用日历授权和系统日历读写权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @authorizationBehavior iOS | 首次调用会依次申请应用日历授权和系统日历写入权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @precondition iOS | 设备需要存在可写入的系统日历账户。
+ * @precondition All | repeatInterval 为 month 时，startTime 所在日期不能大于 28 日。
+ * @usageNote All | repeatInterval 默认 month；repeatEndTime 不传表示一直重复；startTime、endTime、repeatEndTime 使用 Unix 秒级时间戳。
+ * @errorCode none | - | - | Android,iOS | 当前失败通过 Promise reject 返回文本信息，未稳定返回顶层 errNo/errMsg | 根据异常信息检查授权、日历账户、重复周期和时间参数
+ *
+ * @public
+ */
+export declare const addPhoneRepeatCalendar: (params: AddPhoneRepeatCalendarParams) => Promise<object>;
+
+/**
+ * 添加重复日历事件的请求参数。
+ *
+ * @public
+ */
+export declare interface AddPhoneRepeatCalendarParams extends AddPhoneCalendarParams {
+    /**
+     * 重复周期。
+     *
+     * @default month
+     */
+    repeatInterval?: CalendarRepeatInterval;
+    /**
+     * 重复结束时间的 Unix 秒级时间戳。
+     *
+     * @default -
+     */
+    repeatEndTime?: number;
+}
+
+/** @public */
+export declare type AppAuthorizeStatus = 'authorized' | 'denied' | 'not determined';
+
 /** @public */
 export declare interface AppBaseInfoHost {
     /** 宿主 app 对应的 appId */
@@ -568,6 +715,13 @@ export declare interface BottomSheetCancelResult {
  */
 export declare type BottomSheetCancelSource = 'mask' | 'gesture' | 'hostUnavailable' | 'unknown';
 
+/**
+ * 日历重复周期。
+ *
+ * @public
+ */
+export declare type CalendarRepeatInterval = 'day' | 'week' | 'month' | 'year';
+
 /** @public */
 export declare interface CanIUseParams {
     /** 需要检测的能力标识，例如 API 名称 */
@@ -958,7 +1112,7 @@ declare type ClientEventRegistry<Params extends object = object> = (handler: (pa
  * @usageNote All | close 已废弃，推荐使用 navigateBack 返回上一页；省略 containerID 时关闭当前栈顶页面。
  * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
  *
- * @public
+ * @internal
  */
 declare const close_2: (params?: CloseParams | undefined) => Promise<object>;
 export { close_2 as close }
@@ -1898,6 +2052,167 @@ export declare interface DoubaoAppAccountInfo {
     version: string;
 }
 
+/**
+ * 下载文件，并返回可取消、可监听进度的 {@link DownloadTask}。
+ *
+ * @summary 下载文件。
+ * @param params 下载参数，字段见 {@link DownloadFileParams}。
+ * @returns 下载任务。
+ *
+ * @remarks
+ * - 下载使用 GET 请求。
+ * - HTTP 传输完成且文件写入成功后，无论 statusCode 是 2xx、4xx 还是 5xx，Promise 都会 resolve。
+ * - 域名校验失败、路径非法、超时、取消、网络异常、写入失败会使 Promise reject。
+ *
+ * @example
+ * ```typescript
+ * import { downloadFile } from '@doubao-dev/framework/api';
+ *
+ * const downloadTask = downloadFile({
+ *   url: 'https://example.com/files/report.pdf'
+ * });
+ *
+ * downloadTask
+ *   .then((result) => {
+ *     console.log(result.statusCode, result.tempFilePath ?? result.filePath);
+ *   })
+ *   .catch((error) => {
+ *     console.error(error);
+ *   })
+ *   .finally(() => {
+ *     console.log('download finished');
+ *   });
+ *
+ * downloadTask.onProgressUpdate((event) => {
+ *   console.log(`downloaded ${event.progress}%`);
+ * });
+ *
+ * downloadTask.onHeadersReceived((event) => {
+ *   console.log(event.header);
+ * });
+ * ```
+ *
+ * @since 0.0.40
+ * @contractStatus verified | Android、iOS 均支持 HTTPS GET 下载、域名校验、临时或用户目录写入、超时、取消及进度和响应头监听。
+ * @platformSupport Android | supported | 支持 HTTPS GET 下载、域名白名单校验、临时或用户目录写入、超时、取消及任务事件监听。
+ * @platformSupport iOS | supported | 支持 HTTPS GET 下载、域名白名单校验、临时或用户目录写入、超时、取消及任务事件监听。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 下载地址需通过宿主侧下载域名白名单校验，单个文件不得超过 200 MB，单个智能服务同时最多执行 10 个下载任务；指定 filePath 时仅支持临时目录或用户目录。
+ * @usageNote All | 未指定 filePath 时文件写入临时目录，并通过 Promise resolve 结果的 tempFilePath 返回；临时文件的生命周期由宿主管理。
+ * @usageNote All | 不跟随 HTTP 重定向，3xx 响应使 Promise reject；4xx、5xx 响应在文件写入成功后仍使 Promise resolve。
+ * @resultExample
+ * ```json
+ * {
+ *   "statusCode": 200,
+ *   "header": {
+ *     "content-type": "application/pdf"
+ *   },
+ *   "tempFilePath": "appletfile://temp/report.pdf"
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 下载失败会使 Promise reject，当前不提供稳定的 API 专属错误码 | 根据错误信息检查 URL、域名白名单、重定向、并发任务数、文件路径、文件大小和网络状态后重试
+ *
+ * @public
+ */
+export declare function downloadFile(params: DownloadFileParams): DownloadTask;
+
+/**
+ * 下载文件参数。
+ *
+ * @public
+ */
+export declare interface DownloadFileParams {
+    /** 下载资源地址，需为完整 HTTPS URL，并通过宿主侧下载域名白名单校验。 */
+    url: string;
+    /**
+     * 请求 Header。`referer` 和 `user-agent` 由宿主管控，业务传入值不会透传。
+     *
+     * @default -
+     */
+    header?: Record<string, string>;
+    /**
+     * 下载任务超时时间，单位 ms；不传或传入非正数时使用 60000，超过 300000 时按 300000 处理。
+     *
+     * @default 60000
+     * @constraint 有效范围为 1-300000
+     */
+    timeout?: number;
+    /**
+     * 目标文件路径，仅支持 `appletfile://temp/...` 或 `appletfile://user/...`。
+     *
+     * @default 由系统创建临时下载文件
+     */
+    filePath?: string;
+}
+
+/** @public */
+export declare interface DownloadFileProgressUpdate {
+    /** 下载进度百分比，范围 0-100。 */
+    progress: number;
+    /** 已经下载的数据长度，单位 Bytes。 */
+    totalBytesWritten: number;
+    /** 预期需要下载的数据总长度，未知时可能为 -1。 */
+    totalBytesExpectedToWrite: number;
+}
+
+/** @public */
+export declare interface DownloadFileResult {
+    /** HTTP 状态码。非 2xx 响应也会在下载写入成功后返回。 */
+    statusCode: number;
+    /** HTTP 响应头。 */
+    header: Record<string, string>;
+    /** 未指定 `filePath` 时返回的临时文件路径。 */
+    tempFilePath?: string;
+    /** 指定 `filePath` 时返回的目标文件路径。 */
+    filePath?: string;
+}
+
+/**
+ * 下载任务。
+ *
+ * @public
+ */
+export declare interface DownloadTask extends Promise<DownloadFileResult> {
+    /**
+     * 取消下载任务。
+     *
+     * 任务完成后调用不会产生额外效果；取消成功后下载 Promise 会 reject。
+     */
+    abort: () => void;
+    /**
+     * 监听下载进度变化。
+     *
+     * 同一个回调只会注册一次，可以注册多个不同回调。
+     */
+    onProgressUpdate: (callback: (event: DownloadFileProgressUpdate) => void) => void;
+    /**
+     * 取消监听下载进度变化。
+     *
+     * 传入 callback 时仅移除该回调；不传 callback 时移除当前任务的全部进度监听。
+     */
+    offProgressUpdate: (callback?: (event: DownloadFileProgressUpdate) => void) => void;
+    /**
+     * 监听 HTTP Response Header 事件。
+     *
+     * 同一个回调只会注册一次，可以注册多个不同回调。
+     */
+    onHeadersReceived: (callback: (event: DownloadTaskHeadersReceivedEvent) => void) => void;
+    /**
+     * 取消监听 HTTP Response Header 事件。
+     *
+     * 传入 callback 时仅移除该回调；不传 callback 时移除当前任务的全部 Header 监听。
+     */
+    offHeadersReceived: (callback?: (event: DownloadTaskHeadersReceivedEvent) => void) => void;
+}
+
+/** @public */
+export declare interface DownloadTaskHeadersReceivedEvent {
+    /** HTTP 响应头。 */
+    header: Record<string, string>;
+}
+
 /**
  * 允许用户录屏。
  *
@@ -2051,9 +2366,9 @@ export declare interface FileSystemManager {
     readFile: (params: ReadFileParams) => Promise<ReadFileResult>;
     /** 读取文件内容（同步）；返回 {@link ReadFileResult}，其中 data 按 encoding 为 UTF-8 或 Base64 字符串。 */
     readFileSync: (params: ReadFileParams) => ReadFileResult;
-    /** 写入文件内容（异步）。文件不存在则创建，已存在则覆盖；父目录不存在时失败。 */
+    /** 写入文件内容（异步）。文件和父目录不存在则创建，文件已存在则覆盖。 */
     writeFile: (params: WriteFileParams) => Promise<void>;
-    /** 写入文件内容（同步）。文件不存在则创建，已存在则覆盖；父目录不存在时抛出异常。 */
+    /** 写入文件内容（同步）。文件和父目录不存在则创建，文件已存在则覆盖。 */
     writeFileSync: (params: WriteFileParams) => void;
     /** 在文件末尾追加内容（异步）。文件不存在则创建，不会覆盖已有内容。 */
     appendFile: (params: AppendFileParams) => Promise<void>;
@@ -2195,6 +2510,84 @@ export declare interface GetAccountInfoResult {
  */
 export declare function getAccountInfoSync(params?: {}): GetAccountInfoResult;
 
+/**
+ * 获取宿主应用的系统授权设置。
+ *
+ * 调用只读取当前系统授权状态，不会申请权限或触发系统授权弹窗。状态字段固定返回
+ * `authorized`、`denied` 或 `not determined`。
+ *
+ * @returns 返回宿主应用相册、蓝牙、摄像头、定位、麦克风、通知和日历权限状态。
+ * @example
+ * ```typescript
+ * import { getAppAuthorizeSetting } from '@doubao-dev/framework/api';
+ *
+ * const result = getAppAuthorizeSetting();
+ * console.log(result.cameraAuthorized, result.microphoneAuthorized);
+ * console.log(result.notificationAuthorized, result.locationReducedAccuracy);
+ * ```
+ *
+ * @since 0.0.40
+ * @contractStatus verified | Android 与 iOS 均同步返回固定 11 个字段；除 locationReducedAccuracy 为 boolean 外，其余授权状态字段均限定为 authorized、denied 或 not determined，调用不会触发权限申请。
+ * @platformSupport Android | supported | 支持同步读取宿主应用授权状态。
+ * @platformSupport iOS | supported | 支持同步读取宿主应用授权状态。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件
+ * @usageNote All | 本接口查询宿主应用权限，不等同于查询当前小程序 scope 授权。
+ * @usageNote iOS | SDK 首次完成通知设置异步预热前，或应用重新激活后的刷新尚未完成时，四个通知字段可能仍为旧值或 not determined。
+ * @resultExample
+ * ```json
+ * {
+ *   "albumAuthorized": "authorized",
+ *   "bluetoothAuthorized": "denied",
+ *   "cameraAuthorized": "authorized",
+ *   "locationAuthorized": "authorized",
+ *   "locationReducedAccuracy": false,
+ *   "microphoneAuthorized": "authorized",
+ *   "notificationAuthorized": "authorized",
+ *   "notificationAlertAuthorized": "authorized",
+ *   "notificationBadgeAuthorized": "denied",
+ *   "notificationSoundAuthorized": "authorized",
+ *   "phoneCalendarAuthorized": "not determined"
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @platformNote Android | albumAuthorized 和通知分项固定返回 not determined，locationReducedAccuracy 固定返回 false 且不表示实际定位精度
+ * @platformNote Android | bluetoothAuthorized、cameraAuthorized、locationAuthorized、microphoneAuthorized、notificationAuthorized 和 phoneCalendarAuthorized 不区分尚未申请和已经拒绝，两种情况均返回 denied
+ * @platformNote Android | locationAuthorized 在粗略或精确定位任一权限已授权时返回 authorized；phoneCalendarAuthorized 仅在读、写日历权限均授权时返回 authorized
+ * @platformNote iOS | 相册 limited 映射为 authorized，通知 provisional 和 ephemeral 映射为 authorized
+ *
+ * @public
+ */
+export declare const getAppAuthorizeSetting: (params?: {} | undefined) => GetAppAuthorizeSettingResult;
+
+/** @public */
+export declare interface GetAppAuthorizeSettingResult {
+    /** 相册授权状态；Android 固定返回 not determined */
+    albumAuthorized: AppAuthorizeStatus;
+    /** 蓝牙授权状态 */
+    bluetoothAuthorized: AppAuthorizeStatus;
+    /** 摄像头授权状态 */
+    cameraAuthorized: AppAuthorizeStatus;
+    /** 定位授权状态 */
+    locationAuthorized: AppAuthorizeStatus;
+    /** 是否只能使用模糊定位；仅在 iOS 且定位已授权时具有精度含义，Android 固定返回 false */
+    locationReducedAccuracy: boolean;
+    /** 麦克风授权状态 */
+    microphoneAuthorized: AppAuthorizeStatus;
+    /** 通知总授权状态 */
+    notificationAuthorized: AppAuthorizeStatus;
+    /** 通知提醒授权状态；Android 固定返回 not determined */
+    notificationAlertAuthorized: AppAuthorizeStatus;
+    /** 通知角标授权状态；Android 固定返回 not determined */
+    notificationBadgeAuthorized: AppAuthorizeStatus;
+    /** 通知声音授权状态；Android 固定返回 not determined */
+    notificationSoundAuthorized: AppAuthorizeStatus;
+    /** 系统日历授权状态 */
+    phoneCalendarAuthorized: AppAuthorizeStatus;
+}
+
 /**
  * 获取应用基础信息。
  *
@@ -3888,8 +4281,7 @@ export declare interface GetScreenBrightnessResult {
  * ```
  *
  * @since 0.0.36
- * @contractStatus conflict | withSubscriptions 公开可传 true，但豆包 Android、iOS 当前不支持订阅模板，传入 true 会失败。
- * @contractMismatch blocking | parameter | withSubscriptions | Android,iOS | withSubscriptions 为 true 时一并返回订阅消息设置 | 传入 true 时调用直接失败，只有默认的 false 可成功返回授权设置 | 依赖订阅设置的调用无法成功 | packages/open-api/src/basic/setting.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/authorize; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/Auth/AIBridgeGetSettingMethod.swift | 补齐豆包订阅模板设置查询，或从公开参数中移除 withSubscriptions
+ * @contractStatus verified | withSubscriptions 当前仅允许 false，Android、iOS 均支持返回授权设置。
  * @platformSupport Android | supported | 支持获取用户的应用授权设置。
  * @platformSupport iOS | supported | 支持获取用户的应用授权设置。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
@@ -3915,12 +4307,12 @@ export declare const getSetting: (params?: GetSettingParams | undefined) => Prom
 /** @public */
 export declare interface GetSettingParams {
     /**
-     * 是否同时获取用户订阅消息的订阅状态，默认不获取。
+     * 是否同时获取用户订阅消息的订阅状态；当前仅支持 false。
      *
      * @default false
-     * @constraint 豆包 Android、iOS 当前不支持订阅模板，传入 true 时调用会失败
+     * @constraint 豆包 Android、iOS 当前不支持订阅模板，仅支持 false
      */
-    withSubscriptions?: boolean;
+    withSubscriptions?: false;
 }
 
 /** @public */
@@ -4611,6 +5003,17 @@ export declare const hideLoading: (params?: HideInteractionParams | undefined) =
  * await hideToast();
  * ```
  *
+ * @since 0.0.26
+ * @contractStatus verified | 无参数、无返回字段，与 Android、iOS 实现一致。
+ * @platformSupport Android | supported | 支持隐藏当前 Toast。
+ * @platformSupport iOS | supported | 支持隐藏当前 Toast。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件
+ * @usageNote All | 当前没有 Toast 时调用无副作用。
+ * @errorCode common | 102 | Android
+ *
  * @public
  */
 export declare const hideToast: (params?: HideInteractionParams | undefined) => Promise<object>;
@@ -5344,84 +5747,6 @@ export declare interface NotifyBLECharacteristicValueChangeParams {
     type?: BluetoothNotifyType;
 }
 
-/**
- * 取消注册地理位置变化回调。
- *
- * @example
- * ```typescript
- * import {
- *   offLocationChange,
- *   onLocationChange,
- *   type LocationChangeEvent
- * } from '@doubao-dev/framework/api';
- *
- * const handleLocationChange = ({ latitude, longitude }: LocationChangeEvent) => {
- *   console.log(latitude, longitude);
- * };
- *
- * onLocationChange(handleLocationChange);
- * offLocationChange(handleLocationChange);
- * ```
- * @since 0.0.32
- * @contractStatus verified | 注销指定监听和清空全部监听的行为由公开可选参数准确表达
- * @platformSupport Android | supported | 支持注销位置变化监听
- * @platformSupport iOS | supported | 支持注销位置变化监听
- * @platformSupport PC | unsupported | 暂不支持
- * @platformSupport HarmonyOS | unsupported | 暂不支持
- * @permission none | - | none | Android,iOS | 无需额外权限
- * @precondition All | 无额外前置条件
- * @usageNote All | 传入注册时使用的同一个 callback 可只取消该监听；省略 callback 会取消全部位置变化回调
- * @errorCode none | - | - | Android,iOS | 同步注销操作不产生 API 专属错误码 | 无需处理
- *
- * @public
- */
-export declare function offLocationChange(
-/**
- * 要取消的回调；省略时取消当前 API 注册的全部位置变化回调。
- *
- * @default 取消全部位置变化回调
- */
-callback?: LocationChangeListener): void;
-
-/**
- * 取消注册位置更新异常回调。
- *
- * @example
- * ```typescript
- * import {
- *   offLocationChangeError,
- *   onLocationChangeError,
- *   type LocationChangeErrorEvent
- * } from '@doubao-dev/framework/api';
- *
- * const handleLocationError = ({ errMsg, errCode }: LocationChangeErrorEvent) => {
- *   console.error(errMsg, errCode);
- * };
- *
- * onLocationChangeError(handleLocationError);
- * offLocationChangeError(handleLocationError);
- * ```
- * @since 0.0.32
- * @contractStatus verified | 注销指定监听和清空全部监听的行为由公开可选参数准确表达
- * @platformSupport Android | supported | 支持注销位置异常监听
- * @platformSupport iOS | supported | 支持注销位置异常监听
- * @platformSupport PC | unsupported | 暂不支持
- * @platformSupport HarmonyOS | unsupported | 暂不支持
- * @permission none | - | none | Android,iOS | 无需额外权限
- * @precondition All | 无额外前置条件
- * @usageNote All | 传入注册时使用的同一个 callback 可只取消该监听；省略 callback 会取消全部位置异常回调
- * @errorCode none | - | - | Android,iOS | 同步注销操作不产生 API 专属错误码 | 无需处理
- *
- * @public
- */
-export declare function offLocationChangeError(
-/**
- * 要取消的回调；省略时取消当前 API 注册的全部位置异常回调。
- *
- * @default 取消全部位置异常回调
- */
-callback?: LocationChangeErrorListener): void;
-
 /**
  * 监听加速度数据变化事件。
  *
@@ -5815,13 +6140,17 @@ export declare const onKeyboardHeightChange: ClientEventRegistry<KeyboardHeightC
 /**
  * 注册地理位置变化回调。
  *
+ * @returns 返回取消当前监听函数的函数。
+ *
  * @example
  * ```typescript
  * import { onLocationChange } from '@doubao-dev/framework/api';
  *
- * onLocationChange(({ latitude, longitude }) => {
+ * const unsubscribe = onLocationChange(({ latitude, longitude }) => {
  *   console.log(latitude, longitude);
  * });
+ *
+ * unsubscribe();
  * ```
  * @since 0.0.32
  * @contractStatus verified | 豆包 Android、iOS 成功事件均会返回必需的 latitude 和 longitude，其他字段可由公开可选类型承载
@@ -5832,7 +6161,7 @@ export declare const onKeyboardHeightChange: ClientEventRegistry<KeyboardHeightC
  * @platformSupport HarmonyOS | unsupported | 暂不支持
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；同一 callback 重复注册不会产生多个监听，不再使用时调用 `offLocationChange` 释放监听
+ * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；不再使用时调用返回的取消函数释放当前监听
  * @usageNote All | 定位信息属于敏感数据，仅在业务确有需要时监听和使用；事件回调频率不固定
  * @resultExample
  * ```json
@@ -5854,18 +6183,22 @@ export declare const onKeyboardHeightChange: ClientEventRegistry<KeyboardHeightC
  *
  * @public
  */
-export declare function onLocationChange(callback: LocationChangeListener): void;
+export declare function onLocationChange(callback: LocationChangeListener): () => void;
 
 /**
  * 注册位置更新异常回调。
  *
+ * @returns 返回取消当前监听函数的函数。
+ *
  * @example
  * ```typescript
  * import { onLocationChangeError } from '@doubao-dev/framework/api';
  *
- * onLocationChangeError(({ errMsg, errCode }) => {
+ * const unsubscribe = onLocationChangeError(({ errMsg, errCode }) => {
  *   console.log(errMsg, errCode);
  * });
+ *
+ * unsubscribe();
  * ```
  * @since 0.0.32
  * @contractStatus verified | 错误信息必返、错误码可选的公开类型可准确表达双端事件
@@ -5876,7 +6209,7 @@ export declare function onLocationChange(callback: LocationChangeListener): void
  * @platformSupport HarmonyOS | unsupported | 暂不支持
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；同一 callback 重复注册不会产生多个监听，不再使用时调用 `offLocationChangeError` 释放监听
+ * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；不再使用时调用返回的取消函数释放当前监听
  * @resultExample
  * ```json
  * {
@@ -5901,7 +6234,7 @@ export declare function onLocationChange(callback: LocationChangeListener): void
  *
  * @public
  */
-export declare function onLocationChangeError(callback: LocationChangeErrorListener): void;
+export declare function onLocationChangeError(callback: LocationChangeErrorListener): () => void;
 
 /**
  * 监听网络状态变化事件。
@@ -6296,6 +6629,26 @@ export declare interface OpenLocationParams {
  * }
  * ```
  *
+ * @since 0.0.39
+ * @contractStatus verified | withSubscriptions 当前仅允许 false，Android、iOS 均支持打开设置页并返回授权设置。
+ * @platformSupport Android | supported | 支持打开授权设置页并在关闭后返回最新授权设置。
+ * @platformSupport iOS | supported | 支持打开授权设置页并在关闭后返回最新授权设置。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件，不要求在用户点击事件中调用。
+ * @usageNote All | 豆包当前不支持订阅模板，不要传入 withSubscriptions: true。
+ * @resultExample
+ * ```json
+ * {
+ *   "authSetting": {
+ *     "scope.userLocation": true,
+ *     "scope.record": false
+ *   }
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 传入 withSubscriptions: true 等失败当前只返回文本信息，未稳定返回顶层 errNo/errMsg | 不要传入 withSubscriptions: true
+ *
  * @public
  */
 export declare const openSetting: (params?: OpenSettingOptions | undefined) => Promise<OpenSettingResult>;
@@ -6303,9 +6656,12 @@ export declare const openSetting: (params?: OpenSettingOptions | undefined) => P
 /** @public */
 export declare interface OpenSettingOptions {
     /**
-     * 是否同时获取用户订阅消息的订阅状态，默认不获取。
+     * 是否同时获取用户订阅消息的订阅状态；当前仅支持 false。
+     *
+     * @default false
+     * @constraint 豆包 Android、iOS 当前不支持订阅模板，仅支持 false
      */
-    withSubscriptions?: boolean;
+    withSubscriptions?: false;
 }
 
 /** @public */
@@ -7408,10 +7764,10 @@ export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
  * 以用户身份发送后续消息，触发新一轮对话或 API 调用。
  *
  * @param params - 要发送的后续消息内容。
- * @returns 返回一个 Promise，在消息发送成功时解析。
+ * @returns 返回一个 Promise，在消息发送请求提交后解析。
  * @remarks
- * 可在 Widget、智能服务页面或 Worker 中调用。宿主会根据调用上下文关联会话：Widget 使用其所在
- * 会话，从 Widget 打开的页面沿用该会话，其他页面和 Worker 使用主会话。
+ * 可在卡片或智能服务页面中调用，不支持在 app.ts 代码中调用。客户端会根据调用上下文关联会话：
+ * 卡片使用其所在会话，从卡片打开的页面沿用该会话，其他页面使用主会话。
  *
  * @example
  * ```typescript
@@ -7431,6 +7787,18 @@ export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
  * });
  * ```
  *
+ * @since 0.0.37
+ * @contractStatus verified | 公开参数与 Android、iOS 的消息提交行为一致。
+ * @platformSupport Android | supported | 支持在卡片或智能服务页面中发送后续消息。
+ * @platformSupport iOS | supported | 支持在卡片和智能服务页面中发送后续消息。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition Android | 在卡片或智能服务页面中调用。
+ * @precondition iOS | 在卡片或智能服务页面中调用，且当前上下文已关联有效会话。
+ * @usageNote All | Promise 解析表示发送请求已提交，不表示消息已成功送达；实际发送失败不会通过该 Promise 返回。
+ * @errorCode none | - | - | Android,iOS | 调用失败时未稳定返回 API 专属错误码 | 检查 content 与调用场景后重试
+ *
  * @public
  */
 export declare const sendFollowUpMessage: (params: SendFollowUpMessageParams) => Promise<object>;
@@ -7441,7 +7809,10 @@ export declare const sendFollowUpMessage: (params: SendFollowUpMessageParams) =>
  * @public
  */
 export declare interface SendFollowUpMessageParams {
-    /** 消息内容。 */
+    /**
+     * 消息内容。
+     * @constraint 至少包含一条 text 类型且 text 不为空白的消息；第一条符合条件的消息作为本轮用户输入。
+     */
     content: Content[];
 }
 
@@ -7476,7 +7847,7 @@ export declare interface SendFollowUpMessageParams {
  * @usageNote All | 该 API 已废弃，请改用 dispatchActionDirective 描述用户行为并约束模型后续动作。
  * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
  *
- * @public
+ * @internal
  */
 export declare const sendQueryMessage: (params: SendQueryMessageParams) => Promise<object>;
 
@@ -7579,7 +7950,7 @@ export declare type SensorInterval = 'game' | 'ui' | 'normal';
  * @usageNote All | 该 API 已废弃，请改用 updateModelContext 按任务或实体维度补充模型上下文。
  * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
  *
- * @public
+ * @internal
  */
 export declare const setAdditionalContext: (params: SetAdditionalContextParams) => Promise<object>;
 
@@ -9556,27 +9927,83 @@ export declare interface UpdateWidgetParams {
  * @param params 上传参数，字段见 {@link UploadFileParams}。
  * @returns 当前上传任务对应的 {@link UploadTask}。
  *
- * @public
- */
-export declare function uploadFile(params: UploadFileParams): UploadTask;
-
-/**
- * 文件上传失败回调结果。
+ * @remarks
+ * `uploadFile` 会同步返回可监听、可中断的 Promise 任务对象。
+ * 建议在调用后立即注册进度和响应头监听；不再需要上传时调用 `UploadTask.abort`。
+ * @example
+ * ```typescript
+ * import { uploadFile } from '@doubao-dev/framework/api';
+ *
+ * const task = uploadFile({
+ *   url: 'https://example.com/upload',
+ *   filePath: 'ttfile://temp/example.png',
+ *   name: 'file',
+ *   formData: { scene: 'profile' }
+ * });
+ *
+ * task
+ *   .then((result) => {
+ *     console.log(result.statusCode, result.data);
+ *   })
+ *   .catch((error) => {
+ *     console.error(error);
+ *   })
+ *   .finally(() => {
+ *     console.log('upload finished');
+ *   });
+ *
+ * task.onProgressUpdate((event) => {
+ *   console.log(event.progress, event.totalBytesSent);
+ * });
+ * task.onHeadersReceived((event) => {
+ *   console.log(event.header);
+ * });
+ *
+ * // 不再需要上传时中断任务。
+ * // task.abort();
+ * ```
+ *
+ * @since 0.0.39
+ * @contractStatus verified | enableProfile 当前仅允许 false，Android、iOS 均支持正常发起上传。
+ * @platformSupport Android | supported | 支持文件上传、进度监听、响应头监听和中断任务。
+ * @platformSupport iOS | supported | 支持文件上传、进度监听、响应头监听和中断任务。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | url 需命中当前智能服务的上传域名白名单，filePath 需指向当前智能服务可访问的本地文件。
+ * @usageNote All | 上传成功时 Promise resolve，上传失败或取消时 Promise reject；任务结束或不再使用时应移除监听，必要时调用 abort。
+ * @errorCode errNo | 121999 | uploadFile:fail url is invalid | Android,iOS | url 缺失或不是有效上传地址 | 传入完整的 HTTP/HTTPS URL
+ * @errorCode errNo | 121999 | uploadFile:fail name is required | Android,iOS | name 缺失或为空 | 传入服务端接收文件所使用的 form field name
+ * @errorCode errNo | 121901 | uploadFile:fail url not in domain list | Android,iOS | url 未命中上传域名白名单 | 在智能服务配置中添加上传域名后重试
+ * @errorCode errNo | 121902 | uploadFile:fail no file exist | Android,iOS | filePath 为空、文件不存在或路径不是文件 | 使用文件 API 获取当前智能服务可访问的有效文件路径
+ * @errorCode errNo | 121905 | uploadFile:fail upload file abort | Android,iOS | 调用 UploadTask.abort 中断上传 | 按业务需要处理取消状态，无需自动重试
+ * @errorCode errNo | 121906 | uploadFile:fail file path permission denied | Android,iOS | 当前智能服务无权访问 filePath | 改用当前智能服务目录内的文件
+ * @errorCode errNo | 121920 | uploadFile:fail request time out | Android,iOS | 上传超过宿主超时时间 | 检查网络或设置合理的 timeout 后重试
+ * @errorCode errNo | 121985 | uploadFile:fail network unavailable | Android,iOS | 当前网络不可用 | 恢复网络连接后重试
+ * @errorCode errNo | 121991 | uploadFile:fail network error | Android,iOS | 上传过程中发生网络错误 | 检查网络和服务端状态后重试
+ * @errorCode errNo | 121992 | uploadFile:fail enableProfile is not supported | Android,iOS | enableProfile 设置为 true | 移除 enableProfile 或设置为 false
+ * @resultExample
+ * ```json
+ * {
+ *   "statusCode": 200,
+ *   "header": {
+ *     "content-type": "application/json"
+ *   },
+ *   "data": "{\"ok\":true}"
+ * }
+ * ```
+ * @errorExample
+ * ```json
+ * {
+ *   "errMsg": "uploadFile:fail request time out",
+ *   "errNo": 121920,
+ *   "errorCode": 121920
+ * }
+ * ```
  *
  * @public
  */
-export declare interface UploadFileFailCallbackResult {
-    /** 错误信息。 */
-    errMsg: string;
-    /** 错误码，尽量对齐抖音小程序 uploadFile 错误码。 */
-    errNo?: number;
-    /** 抖音小程序风格错误码字段。 */
-    errorCode?: number;
-    /** HTTP 状态码；请求已收到响应但被判定失败时可能存在。 */
-    statusCode?: number;
-    /** HTTP 响应头；请求已收到响应但被判定失败时可能存在。 */
-    header?: Record<string, string>;
-}
+export declare function uploadFile(params: UploadFileParams): UploadTask;
 
 /**
  * 文件上传参数。
@@ -9590,28 +10017,38 @@ export declare interface UploadFileParams {
     filePath: string;
     /** 文件对应的 form field name/key，服务端通过该 key 获取文件内容；multipart filename 使用 filePath 的 basename。 */
     name: string;
-    /** HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等宿主管控字段不会被业务覆盖。 */
+    /**
+     * HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等宿主管控字段不会被业务覆盖。
+     *
+     * @default -
+     */
     header?: Record<string, string>;
-    /** 额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。 */
+    /**
+     * 额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。
+     *
+     * @default -
+     */
     formData?: Record<string, unknown>;
-    /** 超时时间，单位 ms。 */
+    /**
+     * 超时时间，单位 ms；不传时使用宿主侧默认超时配置。
+     *
+     * @default -
+     */
     timeout?: number;
-    /** 是否返回网络 profile。当前 native upload 链路暂不支持，设置为 true 会触发 fail。 */
-    enableProfile?: boolean;
-    /** 上传成功回调。 */
-    success?: (result: UploadFileSuccessCallbackResult) => void;
-    /** 上传失败回调。 */
-    fail?: (result: UploadFileFailCallbackResult) => void;
-    /** 上传完成回调，成功或失败都会触发。 */
-    complete?: (result: UploadFileSuccessCallbackResult | UploadFileFailCallbackResult) => void;
+    /**
+     * 是否返回网络 profile。当前 native upload 链路暂不支持，仅支持 false。
+     *
+     * @default false
+     */
+    enableProfile?: false;
 }
 
 /**
- * 文件上传成功回调结果。
+ * 文件上传结果。
  *
  * @public
  */
-export declare interface UploadFileSuccessCallbackResult {
+export declare interface UploadFileResult {
     /** HTTP 状态码。 */
     statusCode: number;
     /** HTTP 响应头。 */
@@ -9625,17 +10062,37 @@ export declare interface UploadFileSuccessCallbackResult {
  *
  * @public
  */
-export declare interface UploadTask {
-    /** 中断上传任务。 */
-    abort(): void;
-    /** 监听上传进度变化。 */
-    onProgressUpdate(callback: (event: UploadTaskProgressUpdateEvent) => void): void;
-    /** 取消监听上传进度变化；不传 callback 时移除当前任务的全部进度监听。 */
-    offProgressUpdate(callback?: (event: UploadTaskProgressUpdateEvent) => void): void;
-    /** 监听 HTTP Response Header 事件。 */
-    onHeadersReceived(callback: (event: UploadTaskHeadersReceivedEvent) => void): void;
-    /** 取消监听 HTTP Response Header 事件；不传 callback 时移除当前任务的全部 Header 监听。 */
-    offHeadersReceived(callback?: (event: UploadTaskHeadersReceivedEvent) => void): void;
+export declare interface UploadTask extends Promise<UploadFileResult> {
+    /**
+     * 中断当前上传任务。
+     *
+     * 中断成功后上传 Promise 会 reject；任务已经结束时调用无副作用。
+     */
+    abort: () => void;
+    /**
+     * 监听上传进度变化。
+     *
+     * 同一个任务可以注册多个回调，每次收到宿主进度事件时依次调用。
+     */
+    onProgressUpdate: (callback: (event: UploadTaskProgressUpdateEvent) => void) => void;
+    /**
+     * 取消监听上传进度变化。
+     *
+     * 传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部进度监听。
+     */
+    offProgressUpdate: (callback?: (event: UploadTaskProgressUpdateEvent) => void) => void;
+    /**
+     * 监听 HTTP Response Header 事件。
+     *
+     * 同一个任务可以注册多个回调，宿主收到上传响应头时依次调用。
+     */
+    onHeadersReceived: (callback: (event: UploadTaskHeadersReceivedEvent) => void) => void;
+    /**
+     * 取消监听 HTTP Response Header 事件。
+     *
+     * 传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部 Header 监听。
+     */
+    offHeadersReceived: (callback?: (event: UploadTaskHeadersReceivedEvent) => void) => void;
 }
 
 /**
@@ -9930,7 +10387,7 @@ export declare interface WriteBLECharacteristicValueParams {
  *
  * @remarks
  * - 如果文件不存在会自动创建；如果文件已存在则会覆盖原有内容。
- * - 父目录不存在时写入会失败，需先通过 {@link FileSystemManager.mkdir} 创建目录。
+ * - 父目录不存在时会自动创建。
  *
  * @public
  */

package/dist/components.d.ts

@@ -328,6 +328,11 @@ export declare interface CanvasProps {
      * 元素的唯一标识
      */
     id?: string;
+    /**
+     * 原生属性透传，一般由自带画布渲染的三方库使用，业务代码请改用 `ref` 上的绘图方法。
+     * 传入后画布交由外部通过 `attachToCanvasView(name)` 接管，组件不再创建自己的画布实例，`ref` 上的绘图方法随之失效。
+     */
+    name?: string;
     /**
      * 手指触摸动作开始
      * @eventProperty
@@ -3032,6 +3037,47 @@ export declare interface RenderLongImageSegmentsOptions {
     listItemReuseIdentifierPrefix?: string;
 }
 
+/** An allowlisted HTML element in a rich-text node tree. */
+export declare interface RichTextElementNode {
+    /** Optional mini-program-compatible element node discriminator. */
+    type?: 'node';
+    /** Name of the allowlisted HTML element to render. */
+    name: string;
+    /** Element attributes; unsupported attributes are removed during parsing. */
+    attrs?: Record<string, string>;
+    /** Nested text and element nodes rendered inside this element. */
+    children?: RichTextNode[];
+}
+
+/** A text or element node accepted by RichText. */
+export declare type RichTextNode = RichTextTextNode | RichTextElementNode;
+
+/** Props for the mini-program-compatible RichText adapter. */
+export declare interface RichTextProps {
+    /**
+     * An HTML string or a structured node array to render. Unsupported nodes and
+     * attributes are removed before the content is passed to Lynx UI RichText.
+     */
+    nodes?: string | RichTextNode[];
+    /** How plain spaces in text nodes are converted. */
+    space?: RichTextSpace;
+    /** Class name applied to the outer Lynx container. */
+    className?: string;
+    /** Inline style applied to the outer Lynx container. */
+    style?: CSSProperties | string;
+}
+
+/** Whitespace replacement mode compatible with mini-program rich-text. */
+export declare type RichTextSpace = '' | 'nbsp' | 'ensp' | 'emsp';
+
+/** Text content in a rich-text node tree. */
+export declare interface RichTextTextNode {
+    /** Identifies this entry as a text node. */
+    type: 'text';
+    /** Plain text rendered at this position in the node tree. */
+    text: string;
+}
+
 export declare interface RouteLabel {
     /**
      * 标签 ID。
@@ -3055,6 +3101,11 @@ export declare interface RouteLabel {
      * @defaultValue 12
      */
     fontSize?: number;
+    /**
+     * 标签文字字重。
+     * @defaultValue "normal"
+     */
+    fontWeight?: 'normal' | 'bold';
     /**
      * 标签边框颜色。
      * @defaultValue "#cccccc"
@@ -4626,6 +4677,86 @@ declare interface WebGLContextAttributes_2 {
     antialias?: boolean;
 }
 
+/**
+ * 网页视图组件，用于在智能服务页面内承载 H5 页面。
+ *
+ * @remarks
+ * ## 与 H5 双向通信
+ *
+ * H5 页面需要先引入 WebView JSSDK，才能收发消息。可以用 script 标签引入：
+ *
+ * ```html
+ * <script src="https://lf3-static.bytednsdoc.com/obj/eden-cn/msvdeh7pfhpquly/doubao-jssdk-0.0.34-canary-1022d83a-20260615035129.js"></script>
+ * ```
+ *
+ * 构建型项目也可以安装 `@doubao-dev/webview-jssdk` 后导入，导入时会同时挂载全局 `window.doubao`：
+ *
+ * ```js
+ * import doubao from '@doubao-dev/webview-jssdk';
+ * // 或按需导入：import { postMessage, onMessage } from '@doubao-dev/webview-jssdk';
+ * ```
+ *
+ * 应用侧：`src` 指向 H5 地址，`ref` 用于拿到 `postMessage`，`onMessage` 接收 H5 消息。
+ *
+ * ```tsx
+ * import { definePage, useRef } from '@doubao-dev/framework';
+ * import type { WebViewRef } from '@doubao-dev/framework/components';
+ *
+ * function WebViewPage() {
+ *   const webViewRef = useRef<WebViewRef>(null);
+ *
+ *   return (
+ *     <web-view
+ *       ref={webViewRef}
+ *       src="https://example.com/page"
+ *       // 网页加载完成后再发首条消息，H5 才接得住
+ *       onLoad={(event) => webViewRef.current?.postMessage({ type: 'ready', src: event.src })}
+ *       // H5 → 应用：event.data 就是 H5 传入的原始值
+ *       onMessage={(event) => {
+ *         const data = event.data as { type?: string };
+ *         if (data?.type === 'submit') {
+ *           webViewRef.current?.postMessage({ type: 'ack', timestamp: Date.now() });
+ *         }
+ *       }}
+ *       onError={(event) => console.error(event.errorMsg, event.errorCode)}
+ *     />
+ *   );
+ * }
+ *
+ * export default definePage({ render: () => <WebViewPage /> });
+ * ```
+ *
+ * H5 侧：`doubao.onMessage` 接收应用消息并返回注销函数，`doubao.postMessage` 发送消息给应用。
+ *
+ * ```js
+ * const off = doubao.onMessage((raw) => {
+ *   // 应用侧发送的对象会被序列化，这里统一还原
+ *   const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+ *
+ *   if (data.type === 'ready') {
+ *     // H5 → 应用：参数是 { data }，不是直接传值
+ *     doubao.postMessage({ data: { type: 'submit', payload: { name: '豆包' } } });
+ *   }
+ * });
+ *
+ * // 页面卸载或不再需要时注销
+ * // off();
+ * ```
+ *
+ * 三个容易踩的点：
+ *
+ * - 首条消息放在 `onLoad` 之后发，H5 尚未加载完成时发送的消息会丢失。
+ * - 两个方向的数据形态不同：应用 → H5 时非字符串会被 `JSON.stringify`，H5 收到的是 JSON 字符串，
+ *   需要自行 `JSON.parse`；H5 → 应用时 `onMessage` 的 `event.data` 保持 H5 传入的原始值。
+ * - 如果两侧都写成“收到就回”，务必按消息 `type` 区分，否则会无限互相回声。
+ *
+ * 除消息通道外，H5 还可以调用 `doubao.setTitle({ title })` 同步应用侧 WebView 头部标题。
+ *
+ * Web 模拟器中的 `<web-view>` 通过本地代理承载 H5 页面，页面脚本读取到的
+ * `location.origin` / `location.host` 可能是调试器本地域名，而不是真机 WebView 中的业务域名。
+ * 如果 H5 依赖 `location.origin` 或 `location.host` 判断测试环境、线上环境、白名单或鉴权逻辑，
+ * Web 模拟器结果可能与真机不一致，请使用真机调试确认。
+ */
 export declare interface WebViewProps {
     /**
      * 用于获取 WebView 实例方法

package/dist/index.d.ts

@@ -583,6 +583,13 @@ export { NamedExoticComponent }
 
 export { NewLifecycle }
 
+/**
+ * Register the runtime error handler.
+ *
+ * Calling this again replaces the previously registered handler.
+ */
+export declare function onError(callback: (error: Error) => void): void;
+
 export declare interface Page<Data extends AnyObject = AnyObject> extends DefineUIToolOptions<Data> {
     __UI__: boolean;
     __PAGE__: boolean;

package/jsx-runtime.d.ts

@@ -26,6 +26,7 @@ export namespace JSX {
     popup: import('./components.d.ts').PopupProps;
     radio: import('./components.d.ts').RadioProps;
     'radio-group': import('./components.d.ts').RadioGroupProps;
+    'rich-text': import('./components.d.ts').RichTextProps;
     slider: import('./components.d.ts').SliderProps;
     switch: import('./components.d.ts').SwitchProps;
     swiper: import('./components.d.ts').SwiperProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-dev/framework",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -68,7 +68,7 @@
     "types.d.ts"
   ],
   "dependencies": {
-    "@lynx-js/types": "4.0.0",
+    "@lynx-js/types": "4.1.0",
     "@types/react": "18.3.27"
   },
   "publishConfig": {