@doubao-dev/framework 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -92,7 +92,7 @@ export declare interface Arc {
92
92
  zIndex?: number;
93
93
  }
94
94
 
95
- export declare interface AudioProps extends Omit<VideoEngineProps, 'as' | 'style' | 'poster' | 'objectfit' | 'fullscreenMode' | 'resolution' | 'onFirstFrame' | 'scene' | 'onAppear' | 'onDisappear'> {
95
+ export declare interface AudioProps extends Omit<VideoEngineProps, 'as' | 'style' | 'poster' | 'objectfit' | 'fullscreenMode' | 'resolution' | 'onFirstFrame' | 'scene' | 'onAppear' | 'onDisappear' | 'playerType' | 'preloadKey'> {
96
96
  }
97
97
 
98
98
  export declare type AudioRef = VideoEngineRef;
@@ -395,7 +395,7 @@ export { CameraError }
395
395
  * ## 临时文件
396
396
  *
397
397
  * `takePhoto` 和 `stopRecord` 返回的 `path` 是 `appletfile://temp/...` 虚拟路径。临时文件位于
398
- * 当前智能服务隔离的缓存目录,在退出时清理;如需长期保存,用
398
+ * 当前应用插件隔离的缓存目录,在退出时清理;如需长期保存,用
399
399
  * `getFileSystemManager().saveFile({ tempFilePath: path })` 转存到用户目录
400
400
  * `appletfile://user/...`,保存后的路径由返回值的 `savedFilePath` 给出。
401
401
  *
@@ -3564,6 +3564,11 @@ export declare interface RadioGroupProps {
3564
3564
  * 单选按钮,需配合 RadioGroup 使用。
3565
3565
  */
3566
3566
  export declare interface RadioProps {
3567
+ /**
3568
+ * 单选项内容,显示在内置指示器旁,点击内容也可选择该项。
3569
+ * 禁用时,指示器和内容均不可选择。
3570
+ */
3571
+ children?: ReactNode;
3567
3572
  /**
3568
3573
  * Radio 的值
3569
3574
  */
@@ -5301,7 +5306,7 @@ declare interface WebGLContextAttributes_2 {
5301
5306
  }
5302
5307
 
5303
5308
  /**
5304
- * 网页视图组件,用于在智能服务页面内承载 H5 页面。
5309
+ * 网页视图组件,用于在应用插件页面内承载 H5 页面。
5305
5310
  *
5306
5311
  * @remarks
5307
5312
  * ## 与 H5 双向通信
@@ -5326,24 +5331,25 @@ declare interface WebGLContextAttributes_2 {
5326
5331
  *
5327
5332
  * | API | 返回值 | 说明 |
5328
5333
  * | --- | --- | --- |
5329
- * | `doubao.navigateTo({ url })` | `Promise<unknown>` | 保留当前页面,跳转到智能服务内页面 |
5330
- * | `doubao.navigateBack({ delta? })` | `Promise<unknown>` | 返回智能服务内的上一页或多级页面,`delta` 默认为 `1` |
5331
- * | `doubao.redirectTo({ url })` | `Promise<unknown>` | 关闭当前页面,跳转到智能服务内页面 |
5332
- * | `doubao.reLaunch({ url })` | `Promise<unknown>` | 关闭所有页面,跳转到智能服务内页面 |
5334
+ * | `doubao.navigateTo({ url })` | `Promise<unknown>` | 保留当前页面,跳转到应用插件内页面 |
5335
+ * | `doubao.navigateBack({ delta? })` | `Promise<unknown>` | 返回应用插件内的上一页或多级页面,`delta` 默认为 `1` |
5336
+ * | `doubao.redirectTo({ url })` | `Promise<unknown>` | 关闭当前页面,跳转到应用插件内页面 |
5337
+ * | `doubao.reLaunch({ url })` | `Promise<unknown>` | 关闭所有页面,跳转到应用插件内页面 |
5333
5338
  * | `doubao.postMessage({ data })` | `Promise<unknown>` | 向应用侧的 `<web-view onMessage>` 发送消息 |
5334
5339
  * | `doubao.setTitle({ title })` | `Promise<unknown>` | 设置应用侧 WebView 头部标题 |
5335
5340
  * | `doubao.onMessage(handler)` | `() => void` | 监听应用侧消息,返回注销函数 |
5336
5341
  *
5337
- * 路由 API 的 `url` 是智能服务内页面路径,不是 H5 页面地址。
5342
+ * 路由 API 的 `url` 是应用插件内页面路径,不是 H5 页面地址。
5338
5343
  *
5339
5344
  * ## 安全限制
5340
5345
  *
5341
5346
  * 1. **URL 协议限制**:`src` 仅支持 `https://` 协议,不支持 `http://`、`file://` 等其他协议。
5342
5347
  * 2. **JSB 白名单**:白名单外的 JSB 调用会被拦截并返回错误;其他 API 调用需要通过消息通道
5343
- * 交给智能服务页面中转。
5344
- * 3. **域名校验**:需要在豆包智能服务开放平台配置域名白名单,非白名单域名的 URL 将被拒绝加载。
5348
+ * 交给应用插件页面中转。
5349
+ * 3. **域名校验**:需要在豆包应用插件开放平台配置域名白名单,非白名单域名的 URL 将被拒绝加载;
5350
+ * 更新域名白名单后,需要重启豆包 App 才能生效。
5345
5351
  *
5346
- * ## 判断是否在豆包智能服务中打开
5352
+ * ## 判断是否在豆包应用插件中打开
5347
5353
  *
5348
5354
  * H5 可通过 User-Agent 中是否包含 `DoubaoApps` 判断:
5349
5355
  *
@@ -5402,6 +5408,71 @@ declare interface WebGLContextAttributes_2 {
5402
5408
  * // off();
5403
5409
  * ```
5404
5410
  *
5411
+ * ## 隐藏标题栏
5412
+ *
5413
+ * 组件顶部的标题栏(返回按钮 + 标题)默认显示。传入 `navigationStyle="custom"`
5414
+ * 可以隐藏标题栏,让网页内容填满 `<web-view>` 的组件区域(0.4.0 起支持)。
5415
+ * 该配置不会改变组件自身尺寸,也不会自动使组件全屏:
5416
+ *
5417
+ * ```tsx
5418
+ * <web-view src="https://example.com/page" navigationStyle="custom" />
5419
+ * ```
5420
+ *
5421
+ * | navigationStyle | 表现 |
5422
+ * | --- | --- |
5423
+ * | `default`(默认,不传这个属性时就是它)| 顶部显示标题栏,网页在标题栏下方 |
5424
+ * | `custom` | 不显示标题栏,网页内容填满组件区域 |
5425
+ *
5426
+ * ### custom 模式下需要关注的三件事
5427
+ *
5428
+ * 1. **安全区**:如果组件区域延伸到屏幕边缘,需要避免内容被状态栏、刘海或底部指示条遮挡
5429
+ * (见下面「安全区」)
5430
+ * 2. **返回**:组件不再提供内置返回按钮。系统返回手势仍然可用(会先回退网页历史);
5431
+ * 如需提供页面内的退出入口,可调用 `doubao.navigateBack()`
5432
+ * 3. **标题**:没有标题栏,`doubao.setTitle` 不再有可见效果
5433
+ *
5434
+ * ### 安全区
5435
+ *
5436
+ * 当组件区域可能与系统安全区重叠时,网页需要声明 `viewport-fit=cover`:
5437
+ *
5438
+ * ```html
5439
+ * <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
5440
+ * ```
5441
+ *
5442
+ * 然后用 `var()` 和 `env()` 两层取值,四边都要写:
5443
+ *
5444
+ * ```css
5445
+ * .page {
5446
+ * padding-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
5447
+ * padding-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
5448
+ * padding-left: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
5449
+ * padding-right: var(--safe-area-inset-right, env(safe-area-inset-right, 0px));
5450
+ * }
5451
+ * ```
5452
+ *
5453
+ * 两层都要写的原因:
5454
+ *
5455
+ * | 运行环境 | `env()` | `--safe-area-inset-*` |
5456
+ * | --- | --- | --- |
5457
+ * | iOS | 有值 | 不提供 |
5458
+ * | Android WebView(Chromium 140 及以上)| 有值 | 不提供 |
5459
+ * | Android WebView(Chromium 140 以下)| 一直是 0 | 由组件提供数值 |
5460
+ *
5461
+ * - 只写 `env()`:旧版 Android WebView 上内容可能被系统安全区遮挡
5462
+ * - 只写 `var()`:iOS 上拿不到值
5463
+ * - 两层都写:三种环境都能正确取值,无需自行判断 WebView 版本
5464
+ *
5465
+ * 数值单位是 CSS px,不用换算。
5466
+ *
5467
+ * ### 注意事项
5468
+ *
5469
+ * - **只给需要避让的内容加 padding**:文字和按钮要避开安全区,背景、图片、视频、
5470
+ * 画布可以直接铺到边缘,否则边缘会出现空白
5471
+ * - **`viewport-fit=cover` 必须写**:不写的话 iOS 上安全区数值是 0,
5472
+ * 旧版 Android WebView 上组件也不会提供数值
5473
+ * - **注意右上角遮挡**:组件区域延伸到屏幕右上角时,「胶囊」按钮可能覆盖网页内容
5474
+ * - **自行处理返回交互**:`custom` 模式不显示内置返回按钮,有退出需求时需自行提供入口
5475
+ *
5405
5476
  * ## Web 模拟器差异
5406
5477
  *
5407
5478
  * Web 模拟器中的 `<web-view>` 通过本地代理承载 H5 页面,页面脚本读取到的
@@ -5415,16 +5486,18 @@ export declare interface WebViewProps {
5415
5486
  */
5416
5487
  ref?: Ref<WebViewRef>;
5417
5488
  /**
5418
- * 网页资源地址,仅支持 `https://` 协议;需要在豆包智能服务开放平台配置白名单,并通过校验
5489
+ * 网页资源地址,仅支持 `https://` 协议;需要在豆包应用插件开放平台配置白名单,并通过校验
5419
5490
  */
5420
5491
  src?: string;
5421
5492
  /**
5422
5493
  * 导航栏样式。`default` 显示组件内置标题栏并避让顶部安全区域;
5423
5494
  * `custom` 隐藏内置标题栏,网页内容填满组件区域。
5424
5495
  *
5425
- * `custom` 模式下,网页需要自行处理安全区和返回交互。
5496
+ * 当组件区域与系统安全区重叠时,网页需要自行避让;返回交互也需要按业务需要提供。
5497
+ * 具体写法见上方「隐藏标题栏」一节。
5426
5498
  *
5427
5499
  * @defaultValue 'default'
5500
+ * @since 0.4.0
5428
5501
  */
5429
5502
  navigationStyle?: 'default' | 'custom';
5430
5503
  /**
package/dist/index.d.ts CHANGED
@@ -28,6 +28,7 @@ import { ContextType } from 'react';
28
28
  import { createContext } from 'react';
29
29
  import { createElement } from 'react';
30
30
  import { createRef } from 'react';
31
+ import type { CSSProperties } from '@lynx-js/types';
31
32
  import { CustomComponentPropsWithRef } from 'react';
32
33
  import { DependencyList } from 'react';
33
34
  import { DeprecatedLifecycle } from 'react';
@@ -433,7 +434,7 @@ export declare function defineLoginApi(api: LoginApi): LoginApi;
433
434
  /**
434
435
  * 定义 MCP 登录页面
435
436
  * @param options 定义 MCP 登录页面的选项
436
- * @returns 智能服务 MCP 登录页面
437
+ * @returns 应用插件 MCP 登录页面
437
438
  */
438
439
  export declare function defineLoginPage<Data extends AnyObject>(options: Omit<DefinePageToolOptions<Data>, 'aiMeta'> & ThisType<Readonly<PageInstanceMethods<Data>>>): Page<Data>;
439
440
 
@@ -1044,6 +1045,8 @@ export declare function useForeground(callback: LifecycleCallback): void;
1044
1045
 
1045
1046
  export declare function useHide(callback: LifecycleCallback): void;
1046
1047
 
1048
+ export declare function useHostCardStyle(style?: CSSProperties): CSSProperties | undefined;
1049
+
1047
1050
  export { useImperativeHandle }
1048
1051
 
1049
1052
  export { useMemo }
@@ -1104,8 +1107,8 @@ export declare function useViewData<T extends Record<string, any> = Record<strin
1104
1107
  /**
1105
1108
  * 读取当前视图的运行时元数据。
1106
1109
  *
1107
- * 在 Page / Widget(卡片)函数组件顶层调用。宿主未接入或未提供标记时,isOpenedInChat 为 false。
1108
- * 每次调用读取当前值,不订阅宿主更新,也不会主动触发组件渲染。
1110
+ * 在 Page / Widget(卡片)函数组件顶层调用。入口标记或宿主元数据缺失时,isOpenedInChat 为 false。
1111
+ * 在页面展示形态变化时自动触发组件渲染。
1109
1112
  *
1110
1113
  * @returns 视图运行时元数据,字段见 {@link ViewMeta}。
1111
1114
  * @example
@@ -1148,6 +1151,8 @@ export declare interface ViewMeta {
1148
1151
  * 表示打开来源,不随半屏尺寸变化而改变。
1149
1152
  */
1150
1153
  readonly isOpenedInChat: boolean;
1154
+ /** 当前页面展示形态:半屏为 popup,展开后为 fullScreen;直接读取宿主字段,未下发时为 undefined。 */
1155
+ readonly presentation: 'popup' | 'fullScreen' | undefined;
1151
1156
  }
1152
1157
 
1153
1158
  export { VoidFunctionComponent }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@doubao-dev/framework",
3
- "version": "0.4.2",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "types": "./dist/index.d.ts",
6
6
  "exports": {