@doubao-dev/framework 0.0.40 → 0.0.42

package/dist/components.d.ts

@@ -49,7 +49,9 @@ import type { UIAppearanceEvent } from '@lynx-js/types';
 import type { XOverlayNGProps } from '@byted-lynx/type-lynx';
 
 export declare interface AgreePrivacyResult {
-    /** Whether the save was successful */
+    /**
+     * 用户是否同意隐私协议授权。
+     */
     result: boolean;
 }
 
@@ -126,24 +128,24 @@ declare interface BounceConfig {
  * @remarks
  * ## 使用建议
  *
- * 由于 Lynx 组件不开启 CSS 继承，Button 的文本样式不会自动应用到 children。
+ * 由于组件不开启 CSS 继承，button 的文本样式不会自动应用到 children。
  * 因此提供了以下明确的 API 用法：
  *
- * - `text` prop：传入字符串，按钮会应用默认文本样式
- * - `icon` + `text` prop：组合使用，显示图标和文字
+ * - `text`：传入字符串，按钮会应用默认文本样式
+ * - `icon` + `text`：组合使用，显示图标和文字
  * - `children`：完全自定义内容，**不会**应用按钮的默认文本样式
  *
  * ```tsx
- * // 简单文字：用 text prop（推荐）
- * <Button text="确定" />
+ * // 简单文字：用 text（推荐）
+ * <button text="确定" />
  *
  * // 图标+文字：用 icon + text
- * <Button icon={<Icon />} text="提交" />
+ * <button icon={<Icon />} text="提交" />
  *
  * // 完全自定义：用 children（无默认样式）
- * <Button>
+ * <button>
  *   <text style={{ color: 'red' }}>自定义</text>
- * </Button>
+ * </button>
  * ```
  */
 export declare interface ButtonProps {
@@ -233,7 +235,7 @@ export declare interface ButtonProps {
      *
      * @example
      * ```tsx
-     * <Button
+     * <button
      *   openType="openSetting"
      *   onOpenSetting={({ detail }) => {
      *     if (detail.errMsg === 'openSetting:ok') {
@@ -971,7 +973,7 @@ export declare interface InputRef {
      */
     setValue: (value: string) => Promise<void>;
     /**
-     * 获取输入框的值和选择区域
+     * 获取输入框的值和选区起止位置，返回 `{ value, selectionStart, selectionEnd }`。
      */
     getValue: () => Promise<{
         value: string;
@@ -1427,6 +1429,20 @@ export declare type LongImageState = {
 declare type Map_2 = ForwardRefExoticComponent<MapProps & RefAttributes<MapRef>>;
 export { Map_2 as Map }
 
+/**
+ * 地图可视区域，由对角两点的经纬度确定。
+ */
+export declare interface MapBounds {
+    /**
+     * 东北角（右上角）经纬度。
+     */
+    northeast: LatLng;
+    /**
+     * 西南角（左下角）经纬度。
+     */
+    southwest: LatLng;
+}
+
 export declare type MapMarker = ForwardRefExoticComponent<MapMarkerProps & RefAttributes<MapMarkerRef>>;
 
 export declare interface MapMarkerAnimate {
@@ -1467,6 +1483,9 @@ export declare interface MapMarkerAnimationConfig {
  * 地图标记点组件，作为 Map 的子组件使用，支持自定义图标和动画。
  */
 export declare interface MapMarkerProps {
+    /**
+     * 用于获取组件实例的 ref
+     */
     ref?: Ref<MapMarkerRef>;
     /**
      * React key 属性
@@ -1497,7 +1516,7 @@ export declare interface MapMarkerProps {
      */
     animate?: MapMarkerAnimate;
     /**
-     * 标记点在自定义布局中的容器位置。
+     * 标记点在自定义布局中的容器位置，使用像素坐标 `{ x, y }`。
      */
     containerPosition?: {
         x: number;
@@ -1539,6 +1558,9 @@ export declare type MapMarkerRef = {
  * 地图展示组件，支持标记点、路线、多边形等覆盖物，以及平移、缩放等交互。
  */
 export declare interface MapProps {
+    /**
+     * 用于获取组件实例的 ref
+     */
     ref?: Ref<MapRef>;
     /**
      * 组件的样式。
@@ -1549,7 +1571,7 @@ export declare interface MapProps {
      */
     className?: string;
     /**
-     * 子元素。一般与 `<MapMarker />` 搭配使用。
+     * 子元素。一般与 `<map-marker />` 搭配使用。
      */
     children?: ReactNode;
     /**
@@ -1637,12 +1659,16 @@ export declare interface MapProps {
      */
     enableTilt?: boolean;
     /**
-     * 是否允许原生交互。控制平台层触摸事件的处理，影响平台层手势。
+     * 是否允许底层地图处理触摸事件。关闭后，地图不会响应拖动、缩放等手势。
      * @defaultValue true
      */
     enableNativeInteraction?: boolean;
     /**
-     * 点击地图时触发。
+     * 透传给底层地图实现的扩展参数。仅在豆包提供具体参数约定时使用。
+     */
+    extraParams?: Record<string, unknown>;
+    /**
+     * 点击地图时触发。回调参数的 `point` 为点击位置的经纬度。
      */
     onClick?: (event: {
         point: LatLng;
@@ -1652,22 +1678,11 @@ export declare interface MapProps {
      */
     onMapLoaded?: () => void;
     /**
-     * 视野发生变化时触发。
+     * 视野开始或结束变化时触发。回调参数包含变化阶段 `type`，以及可选的缩放级别、中心点和可视区域等信息。
      */
-    onRegionChange?: (event: {
-        type: 'begin' | 'end';
-        rotate?: number;
-        scale?: number;
-        center?: LatLng;
-        region?: {
-            northeast: LatLng;
-            southwest: LatLng;
-        };
-        causedBy?: 'drag' | 'scale';
-        triggeredBy?: 'user' | 'api';
-    }) => void;
+    onRegionChange?: (event: MapRegionChangeEvent) => void;
     /**
-     * 点击路线时触发。
+     * 点击路线时触发。回调参数的 `id` 为被点击路线的 ID。
      */
     onPolylineClick?: (event: {
         id: string;
@@ -1692,19 +1707,13 @@ export declare interface MapRef {
      */
     setScale: (scale: number, animationOptions?: MapViewportAnimationOptions) => void;
     /**
-     * 获取当前地图边界。
+     * 获取当前地图边界，返回西南角 `southwest` 和东北角 `northeast` 的经纬度。
      */
-    getBound: () => Promise<{
-        southwest: LatLng;
-        northeast: LatLng;
-    }>;
+    getBound: () => Promise<MapBounds>;
     /**
-     * 设置地图边界。
+     * 设置地图边界。`bounds` 包含西南角 `southwest` 和东北角 `northeast` 的经纬度。
      */
-    setBound: (bounds: {
-        northeast: LatLng;
-        southwest: LatLng;
-    }, animationOptions?: MapViewportAnimationOptions) => void;
+    setBound: (bounds: MapBounds, animationOptions?: MapViewportAnimationOptions) => void;
     /**
      * 使地图视图适合给定的点。
      * @param points - 要适配的点数组
@@ -1713,7 +1722,7 @@ export declare interface MapRef {
      */
     fitPoints: (points: LatLng[], padding?: number[], animationOptions?: MapViewportAnimationOptions) => void;
     /**
-     * 设置地图锚点（地图坐标对齐的屏幕像素位置）。
+     * 设置地图锚点（地图坐标对齐的屏幕像素位置），`position` 包含像素坐标 `x` 和 `y`。
      * 默认情况下，setCenter() 将坐标对齐到视口中心。
      * 调用 setAnchor(x, y) 后，setCenter() 会将坐标对齐到屏幕的 (x, y) 像素位置。
      * @param position.x - 屏幕 x 坐标像素（0 = 左边缘）
@@ -1731,14 +1740,14 @@ export declare interface MapRef {
         y: number;
     }) => void;
     /**
-     * 将地图经纬度转换为屏幕像素坐标。
+     * 将地图经纬度转换为屏幕像素坐标，返回 `{ x, y }`。
      */
     latLngToPx: (latLng: LatLng) => Promise<{
         x: number;
         y: number;
     }>;
     /**
-     * 将屏幕像素坐标转换为地图经纬度。
+     * 将屏幕像素坐标 `{ x, y }` 转换为地图经纬度。
      */
     pxToLatLng: (point: {
         x: number;
@@ -1746,6 +1755,42 @@ export declare interface MapRef {
     }) => Promise<LatLng>;
 }
 
+/**
+ * 地图视野变化事件的数据。
+ *
+ * 除 `type` 外均为可选：具体带哪些字段由平台和触发方式决定。
+ */
+export declare interface MapRegionChangeEvent {
+    /**
+     * 变化阶段，`begin` 为开始变化，`end` 为变化结束。
+     */
+    type: 'begin' | 'end';
+    /**
+     * 当前地图旋转角度。
+     */
+    rotate?: number;
+    /**
+     * 当前缩放级别。
+     */
+    scale?: number;
+    /**
+     * 当前地图中心点经纬度。
+     */
+    center?: LatLng;
+    /**
+     * 当前可视区域。
+     */
+    region?: MapBounds;
+    /**
+     * 引起本次变化的手势类型。
+     */
+    causedBy?: 'drag' | 'scale';
+    /**
+     * 本次变化由用户操作还是 API 调用引起。
+     */
+    triggeredBy?: 'user' | 'api';
+}
+
 export declare interface MapViewportAnimationOptions {
     /**
      * 是否开启地图视野变化动画。
@@ -1760,21 +1805,57 @@ export declare interface MapViewportAnimationOptions {
     duration?: number;
 }
 
+/**
+ * 打字机动画每步结束时的事件数据。
+ */
 export declare interface MarkdownAnimationStepEvent {
+    /**
+     * 当前已完成的动画步数。
+     */
     animationStep: number;
+    /**
+     * 全部内容对应的总动画步数。
+     */
     maxAnimationStep: number;
 }
 
+/**
+ * 暂停打字机动画的结果。
+ */
 export declare interface MarkdownAnimationStepResult {
+    /**
+     * 暂停时已完成的动画步数，可传给 `resumeAnimation` 从该步继续。
+     */
     animationStep: number;
 }
 
+/**
+ * 相对组件左上角的包围盒。
+ */
 export declare interface MarkdownBoundingRect {
+    /**
+     * 左边界的 x 坐标。
+     */
     left: number;
+    /**
+     * 上边界的 y 坐标。
+     */
     top: number;
+    /**
+     * 右边界的 x 坐标。
+     */
     right: number;
+    /**
+     * 下边界的 y 坐标。
+     */
     bottom: number;
+    /**
+     * 包围盒宽度。
+     */
     width: number;
+    /**
+     * 包围盒高度。
+     */
     height: number;
 }
 
@@ -1791,72 +1872,207 @@ export declare interface MarkdownContentRangeOptions {
     end?: number;
 }
 
+/**
+ * 获取已解析内容的结果。
+ */
 export declare interface MarkdownContentResult {
+    /**
+     * 指定区间内已解析出的文本内容。
+     */
     content: string;
 }
 
+/**
+ * Markdown 的额外渲染效果配置。
+ */
 export declare type MarkdownEffect = Record<string, unknown>;
 
+/**
+ * Markdown 组件事件的通用外壳，`detail` 为各事件自己的数据。
+ */
 export declare type MarkdownEvent<EventType extends string = string, Detail = unknown> = BaseEvent<EventType, Detail>;
 
+/**
+ * 获取图片地址的结果。
+ */
 export declare interface MarkdownImagesResult {
+    /**
+     * Markdown 内容中出现的所有图片地址，按出现顺序排列。
+     */
     images: string[];
 }
 
+/**
+ * 点击图片事件的数据。
+ */
 export declare interface MarkdownImageTapEvent {
+    /**
+     * 被点击图片的地址。
+     */
     url: string;
 }
 
+/**
+ * 标注边框的线条样式。
+ */
 export declare interface MarkdownLineStyle {
+    /**
+     * 线条类型，实线或虚线。
+     */
     lineType: 'solid' | 'dashed';
+    /**
+     * 线条颜色。
+     */
     color: string;
+    /**
+     * 线条粗细。
+     */
     width: number;
+    /**
+     * 虚线时单段线的长度，实线可不传。
+     */
     elementSize?: number;
+    /**
+     * 虚线时相邻两段线之间空隙的长度，实线可不传。
+     */
     emptySize?: number;
 }
 
+/**
+ * 点击链接事件的数据。
+ */
 export declare interface MarkdownLinkEvent {
+    /**
+     * 链接地址。
+     */
     url: string;
+    /**
+     * 链接的文本内容。
+     */
     content: string;
 }
 
+/**
+ * 一段文本标注，用于给指定区间的文本加高亮或边框。
+ */
 export declare interface MarkdownMarkAttachment {
+    /**
+     * 标注区间的起始索引，含该位置。
+     */
     startIndex: number;
+    /**
+     * 标注区间的结束索引，不含该位置。
+     */
     endIndex: number;
+    /**
+     * 索引的计量方式：`char` 按渲染后的字符计，`source` 按 Markdown 源码计。
+     */
     indexType: 'char' | 'source';
+    /**
+     * 标注区域是否可点击。点击后通过 `onTextClick` 回传本条标注的 `id`。
+     */
     clickable?: boolean;
+    /**
+     * 标注标识，会在 `onTextClick` 中回传，用于区分是哪一条标注。
+     */
     id?: string;
+    /**
+     * 标注绘制在文本的下层还是上层。
+     */
     layer?: 'background' | 'foreground';
+    /**
+     * 标注的样式。
+     */
     style: MarkdownMarkStyle;
 }
 
+/**
+ * 文本标注的样式，用于绘制高亮块和四周边框。
+ */
 export declare interface MarkdownMarkStyle {
+    /**
+     * 标注块的圆角半径。
+     */
     radius?: number;
+    /**
+     * 标注块相对文本左侧的额外内边距。
+     */
     left?: number;
+    /**
+     * 标注块相对文本右侧的额外内边距。
+     */
     right?: number;
+    /**
+     * 标注块相对文本顶部的额外内边距。
+     */
     top?: number;
+    /**
+     * 标注块相对文本底部的额外内边距。
+     */
     bottom?: number;
+    /**
+     * 标注块的填充色。
+     */
     color?: string;
+    /**
+     * 左边框样式。
+     */
     borderLeft?: MarkdownLineStyle;
+    /**
+     * 上边框样式。
+     */
     borderTop?: MarkdownLineStyle;
+    /**
+     * 右边框样式。
+     */
     borderRight?: MarkdownLineStyle;
+    /**
+     * 下边框样式。
+     */
     borderBottom?: MarkdownLineStyle;
 }
 
+/**
+ * UI 方法调用失败时的结果。
+ */
 export declare interface MarkdownMethodFailResult {
+    /**
+     * 错误码。
+     */
     code: number;
+    /**
+     * 错误信息。
+     */
     data: string;
 }
 
+/**
+ * 文本溢出事件的数据。
+ */
 export declare interface MarkdownOverflowEvent {
+    /**
+     * 溢出的处理方式：`ellipsis` 显示省略号，`clip` 直接截断。
+     */
     type: 'ellipsis' | 'clip';
 }
 
+/**
+ * 解析结束事件的数据。
+ */
 export declare interface MarkdownParseEndEvent {
+    /**
+     * 触发解析的内容标识，对应 `contentId`。
+     */
     id: string;
 }
 
+/**
+ * 获取标签源码区间的结果。
+ */
 export declare interface MarkdownParseResult {
+    /**
+     * 以标签名为 key，值为该标签在源码中出现的所有区间。
+     */
     result: Map<string, MarkdownSourceRange[]>;
 }
 
@@ -1868,7 +2084,7 @@ export declare interface MarkdownParseResultOptions {
 }
 
 /**
- * Markdown 渲染组件，基于 Lynx `x-markdown` 渲染 Markdown 内容。
+ * Markdown 渲染组件，用于渲染 Markdown 内容，支持打字机动画、文本选择和文本标注。
  */
 export declare interface MarkdownProps {
     /**
@@ -1900,9 +2116,9 @@ export declare interface MarkdownProps {
      */
     contentId?: string;
     /**
-     * Markdown 内部元素样式表。该对象会直接透传给 Lynx 原生 `x-markdown` 的 `markdown-style`，
-     * 不是普通 CSS style；颜色使用不带 `#` 的十六进制字符串（如 `'151515'`），尺寸使用 number
-     *（如 `fontSize: 15`、`lineHeight: 22`），不要传 `var(--color)`、`'#151515'` 或 `'15px'`。
+     * Markdown 内部元素样式表。它不是普通的 CSS style：颜色使用不带 `#` 的十六进制字符串
+     *（如 `'151515'`），尺寸使用 number（如 `fontSize: 15`、`lineHeight: 22`），
+     * 不要传 `var(--color)`、`'#151515'` 或 `'15px'`。
      * @defaultValue {}
      */
     markdownStyle?: MarkdownStyle;
@@ -2057,27 +2273,69 @@ export declare interface MarkdownResumeAnimationOptions {
     animationStep?: number;
 }
 
+/**
+ * 获取选中文本的结果。
+ */
 export declare interface MarkdownSelectedTextResult {
+    /**
+     * 当前选中的文本，没有选区时为空字符串。
+     */
     selectedText: string;
 }
 
+/**
+ * 文本选区变化事件的数据。
+ */
 export declare interface MarkdownSelectionChangeEvent {
+    /**
+     * 选区起始字符索引。
+     */
     start: number;
+    /**
+     * 选区结束字符索引。
+     */
     end: number;
+    /**
+     * 选区的延展方向。
+     */
     direction: 'forward' | 'backward';
 }
 
+/**
+ * 选区两端的拖拽手柄位置，可用于自绘选区光标。
+ */
 export declare interface MarkdownSelectionHandle {
+    /**
+     * 手柄圆心的 x 坐标。
+     */
     x: number;
+    /**
+     * 手柄圆心的 y 坐标。
+     */
     y: number;
+    /**
+     * 手柄的半径。
+     */
     radius: number;
 }
 
+/**
+ * 标签在 Markdown 源码中的位置区间。
+ */
 export declare interface MarkdownSourceRange {
+    /**
+     * 起始索引，含该位置。
+     */
     start: number;
+    /**
+     * 结束索引，不含该位置。
+     */
     end: number;
 }
 
+/**
+ * Markdown 内部元素的样式表，写法见 `markdownStyle` 属性说明。
+ */
 export declare type MarkdownStyle = Record<string, unknown>;
 
 export declare interface MarkdownTextBoundingRectOptions extends MarkdownContentRangeOptions {
@@ -2088,12 +2346,27 @@ export declare interface MarkdownTextBoundingRectOptions extends MarkdownContent
     indexType?: 'source' | 'char';
 }
 
+/**
+ * 获取文本包围盒的结果。
+ */
 export declare interface MarkdownTextBoundingRectResult {
+    /**
+     * 指定区间整体的包围盒。
+     */
     boundingRect: MarkdownBoundingRect;
+    /**
+     * 指定区间逐行的包围盒，跨行时有多个。
+     */
     boxes: MarkdownBoundingRect[];
 }
 
+/**
+ * 点击标注文本事件的数据。
+ */
 export declare interface MarkdownTextClickEvent {
+    /**
+     * 被点击标注的标识，对应 `MarkdownMarkAttachment.id`。
+     */
     id: string;
 }
 
@@ -2116,9 +2389,21 @@ export declare interface MarkdownTextSelectionOptions {
     endY: number;
 }
 
+/**
+ * 设置文本选区的结果。
+ */
 export declare interface MarkdownTextSelectionResult {
+    /**
+     * 整个选区的包围盒。
+     */
     boundingRect: MarkdownBoundingRect;
+    /**
+     * 选区逐行的包围盒，跨行选择时有多个。
+     */
     boxes: MarkdownBoundingRect[];
+    /**
+     * 选区起点和终点的手柄位置。
+     */
     handles: {
         start: MarkdownSelectionHandle;
         end: MarkdownSelectionHandle;
@@ -2247,7 +2532,7 @@ export declare interface NavigationBarBackEvent {
 /**
  * 页面顶部导航栏组件。
  *
- * 用于隐藏宿主默认标题栏后的自定义页面导航，自动适配状态栏和平台导航规格。
+ * 用于隐藏豆包默认标题栏后的自定义页面导航，自动适配状态栏和平台导航规格。
  */
 export declare interface NavigationBarProps {
     /** 组件样式。 */
@@ -2342,7 +2627,7 @@ declare interface OnDragCallback {
 }
 
 /**
- * Button 通过 `openType="openSetting"` 打开授权设置页后的回调事件。
+ * button 通过 `openType="openSetting"` 打开授权设置页后的回调事件。
  */
 export declare interface OpenSettingEvent {
     /**
@@ -2371,6 +2656,9 @@ export declare type OpenSettingEventDetail = {
 } | {
     /**
      * 回调状态，失败时格式为 `openSetting:fail ${错误信息}`。
+     *
+     * 错误信息由客户端返回，没有固定枚举，例如 `openSetting:fail Applet bridge unavailable`；
+     * 客户端未返回原因时为 `openSetting:fail unknown error`。
      */
     errMsg: `openSetting:fail ${string}`;
 };
@@ -2424,10 +2712,16 @@ export declare interface PickerColumnProps {
 }
 
 export declare interface PickerColumnRef {
+    /**
+     * 获取当前选中项的值和完整选项数据。
+     */
     getValue: () => {
         value: string | number;
         option: PickerColumnOption;
     };
+    /**
+     * 滚动到指定值对应的选项。
+     */
     setValue: (value: string | number) => void;
 }
 
@@ -2466,7 +2760,7 @@ export declare interface PickerViewProps {
      */
     className?: string;
     /**
-     * 组件主题。未传时跟随宿主应用主题；传入后固定使用指定主题。
+     * 组件主题。未传时跟随豆包当前主题；传入后固定使用指定主题。
      */
     theme?: Theme;
     /**
@@ -2484,8 +2778,17 @@ export declare interface PickerViewProps {
 }
 
 export declare interface PickerViewRef {
+    /**
+     * 按列顺序获取各列当前选中项的值。
+     */
     getValues: () => (string | number)[];
+    /**
+     * 按列顺序获取各列当前选中项的完整选项数据。
+     */
     getOptions: () => PickerColumnOption[];
+    /**
+     * 按列顺序把各列滚动到指定值对应的选项。
+     */
     setValues: (values: (string | number)[]) => void;
 }
 
@@ -3037,44 +3340,44 @@ export declare interface RenderLongImageSegmentsOptions {
     listItemReuseIdentifierPrefix?: string;
 }
 
-/** An allowlisted HTML element in a rich-text node tree. */
+/** 节点树中的 HTML 元素节点，仅支持白名单内的标签。 */
 export declare interface RichTextElementNode {
-    /** Optional mini-program-compatible element node discriminator. */
+    /** 节点类型标识，用于兼容小程序写法，可省略。 */
     type?: 'node';
-    /** Name of the allowlisted HTML element to render. */
+    /** 要渲染的 HTML 标签名，需在白名单内。 */
     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. */
+/** 富文本组件，支持 HTML 字符串或结构化节点，并自动同步内容高度。写法与小程序 rich-text 兼容。 */
 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.
+     * 要渲染的内容，可传 HTML 字符串或结构化节点数组。
+     * 白名单外的节点和属性会先被移除，再交给底层渲染。
      */
     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. */
+/** 文本中连续空格的转换方式，与小程序 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. */
+    /** 节点类型标识，文本节点固定为 `text`。 */
     type: 'text';
-    /** Plain text rendered at this position in the node tree. */
+    /** 在该位置渲染的纯文本内容。 */
     text: string;
 }
 
@@ -3393,17 +3696,17 @@ declare interface SwiperProps_2<T> {
      * 子元素，应该是一个函数，返回 SwiperItem
      * @example
      * ```tsx
-     * <Swiper
+     * <swiper
      *    data={items}
      *   itemWidth={350}
      *  >
      *    {({ index, item }) => (
-     *      <SwiperItem index={index} key={index}>
+     *      <swiper-item index={index} key={index}>
      *        <image class="image" src={`${item}`}></image>
      *        <text class="image-text">Number.{index}</text>
-     *      </SwiperItem>
+     *      </swiper-item>
      *    )}
-     *  </Swiper>
+     *  </swiper>
      * ```
      */
     children: (prop: RenderFunctionProps<T>) => ReactElement_2;
@@ -3827,34 +4130,39 @@ export declare interface TextProps {
     bindtap?: (event: TouchEvent_2) => void;
 }
 
+/**
+ * 组件主题：`light` 为浅色，`dark` 为深色。
+ */
 export declare type Theme = 'light' | 'dark';
 
 /**
- * 主题配置组件，为其包裹的子组件统一设置主题样式（颜色、圆角等 CSS 变量）。
+ * 主题配置组件，为其包裹的子组件统一指定豆包的浅色 / 深色模式。
+ *
+ * 只影响颜色相关的 CSS 变量，不涉及圆角、间距、字号等其他样式。
  */
 export declare interface ThemeProviderProps {
     /**
-     * Theme for the provider subtree. Defaults to the nearest provider theme or host app theme.
+     * 子树使用的主题。未传时跟随最近的上层 theme-provider；没有上层 theme-provider 时，跟随豆包当前主题。
      */
     theme?: Theme;
     /**
-     * Child nodes that should inherit Doubao theme CSS variables.
+     * 子元素，会继承本组件设置的豆包主题颜色变量。
      */
     children?: ReactNode;
     /**
-     * Container style.
+     * 容器样式
      */
     style?: CSSProperties;
     /**
-     * Container class name.
+     * 容器类名
      */
     className?: string;
     /**
-     * Container id.
+     * 容器 id
      */
     id?: string;
     /**
-     * Whether to flatten the provider view. Defaults to false because the view is used as a CSS variable scope.
+     * 是否展平容器 view。默认 false，因为该 view 需要作为 CSS 变量的作用域存在。
      *
      * @defaultValue false
      */
@@ -4686,10 +4994,11 @@ declare interface WebGLContextAttributes_2 {
  * 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>
+ * <script src="https://lf3-static.bytednsdoc.com/obj/eden-cn/msvdeh7pfhpquly/doubao-jssdk-0.0.41.js"></script>
  * ```
  *
- * 构建型项目也可以安装 `@doubao-dev/webview-jssdk` 后导入，导入时会同时挂载全局 `window.doubao`：
+ * H5 项目如果用 npm 管理依赖，也可以安装 `@doubao-dev/webview-jssdk` 后导入，
+ * 导入时会同时挂载全局 `window.doubao`：
  *
  * ```js
  * import doubao from '@doubao-dev/webview-jssdk';
@@ -4699,10 +5008,10 @@ declare interface WebGLContextAttributes_2 {
  * 应用侧：`src` 指向 H5 地址，`ref` 用于拿到 `postMessage`，`onMessage` 接收 H5 消息。
  *
  * ```tsx
- * import { definePage, useRef } from '@doubao-dev/framework';
+ * import { useRef } from '@doubao-dev/framework';
  * import type { WebViewRef } from '@doubao-dev/framework/components';
  *
- * function WebViewPage() {
+ * export default function WebViewPage() {
  *   const webViewRef = useRef<WebViewRef>(null);
  *
  *   return (
@@ -4722,8 +5031,6 @@ declare interface WebGLContextAttributes_2 {
  *     />
  *   );
  * }
- *
- * export default definePage({ render: () => <WebViewPage /> });
  * ```
  *
  * H5 侧：`doubao.onMessage` 接收应用消息并返回注销函数，`doubao.postMessage` 发送消息给应用。
@@ -4752,6 +5059,8 @@ declare interface WebGLContextAttributes_2 {
  *
  * 除消息通道外，H5 还可以调用 `doubao.setTitle({ title })` 同步应用侧 WebView 头部标题。
  *
+ * ## Web 模拟器差异
+ *
  * Web 模拟器中的 `<web-view>` 通过本地代理承载 H5 页面，页面脚本读取到的
  * `location.origin` / `location.host` 可能是调试器本地域名，而不是真机 WebView 中的业务域名。
  * 如果 H5 依赖 `location.origin` 或 `location.host` 判断测试环境、线上环境、白名单或鉴权逻辑，