@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/components/overview.md

@@ -0,0 +1,43 @@
+# 豆包应用插件组件 API
+
+## 核心规则
+
+所有组件使用**小写标签**，`components-loader` 在构建时自动注入 import，业务代码不需要手动 import 运行时组件：
+
+```tsx
+// ✅ 直接使用小写标签
+<view><text>你好</text><button text="提交" /></view>
+
+// ❌ 不要手动 import 运行时组件
+import { View, Button } from '@doubao-dev/framework/components';
+```
+
+类型标注可以 import：
+
+```tsx
+import type { ButtonProps, SwiperRef, VideoRef, PopupRef } from '@doubao-dev/framework/components';
+```
+
+## 参考文档
+
+| 类别 | 文件 | 涵盖标签 |
+|------|------|---------|
+| 滚动与列表 | [scroll-list.md](scroll-list.md) | `scroll-view` `list` `list-item` `swiper` `swiper-item` |
+| 容器与覆层 | [container-overlay.md](container-overlay.md) | `view` `popup` `movable-area` `movable-view` `theme-provider` |
+| 文本与媒体 | [text-media.md](text-media.md) | `text` `image` `svg` `video` `long-image` `web-view` |
+| 交互控件 | [interactive-controls.md](interactive-controls.md) | `button` `switch` `slider` `radio` `radio-group` |
+| 表单控件 | [form-controls.md](form-controls.md) | `input` `textarea` `picker-view` `picker-column` `picker-divider` |
+| 地图与画布 | [map-canvas.md](map-canvas.md) | `map` `map-marker` `canvas` |
+
+## 常见错误
+
+| 错误 | 修正 |
+|------|------|
+| 手动 import 运行时组件 | 直接用小写标签，loader 自动注入 |
+| `<list>` 没设置 height | 必须 `style={{ height: '...' }}`，list 不支持自适应高度 |
+| `list-item` 没传 `item-key` | item-key 是必填项（原生 Lynx 元素，连字符属性名） |
+| `picker-view` 高度只写在 CSS class | 必须同时写 `style={{ height: '...' }}` |
+| `slider` 不传 value | slider 仅支持受控用法 |
+| `image` 没设置 width/height 也没设 autoSize | 不满足条件图片不显示 |
+| `popup` 没传 scrollContainerId | scrollContainerId 是必填项 |
+| `long-image` 接外部滚动容器直接传外层 scrollTop | 有 header 时需减去 header 高度 |

package/dist/skills/doubao-plugin-app/references/frontend/components/scroll-list.md

@@ -0,0 +1,149 @@
+# 滚动与列表组件
+
+## `<scroll-view>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| scrollOrientation | `'vertical' \| 'horizontal'` | `'vertical'` | 滚动方向 |
+| bounces | boolean | true | iOS 弹性回弹 |
+| enableScroll | boolean | true | 是否允许滚动 |
+| scrollBarEnable | boolean | true | 是否显示滚动条 |
+| upperThreshold | number | 0 | 触发 onScrollToUpper 的距离阈值 (px) |
+| lowerThreshold | number | 0 | 触发 onScrollToLower 的距离阈值 (px) |
+| initialScrollOffset | number | 0 | 初始滚动偏移 (px)，仅首屏有效 |
+| onScrollToUpper | (e: ScrollToUpperEvent) => void | - | 滚动到顶/左 |
+| onScrollToLower | (e: ScrollToLowerEvent) => void | - | 滚动到底/右 |
+| onScroll | (e: ScrollEvent) => void | - | 滚动中 |
+| onScrollEnd | (e: ScrollEndEvent) => void | - | 滚动结束 |
+| onContentSizeChanged | (e: ContentSizeChangedEvent) => void | - | 内容尺寸变化 |
+
+```tsx
+// 垂直滚动 + 上拉加载
+<scroll-view
+  style={{ height: '100vh' }}
+  lowerThreshold={50}
+  onScrollToLower={() => loadMore()}
+>
+  {items.map(item => <view key={item.id}>{/* ... */}</view>)}
+</scroll-view>
+
+// 水平滚动
+<scroll-view scrollOrientation="horizontal" style={{ width: '100%' }}>
+  {images.map(img => <image key={img.id} src={img.url} style={{ width: '100px', height: '100px' }} />)}
+</scroll-view>
+```
+
+---
+
+## `<list>` / `list-item`
+
+高性能列表，支持多列/瀑布流。
+
+**`<list>` 必须显式指定 height**，不支持自适应高度。
+
+`list-item` 是原生 Lynx 元素，属性名使用连字符（`item-key`、`sticky-top`），不是驼峰。
+
+### list 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| style | CSSProperties | - | **必须包含 height** |
+| scrollOrientation | `'vertical' \| 'horizontal'` | `'vertical'` | 方向 |
+| listType | `'single' \| 'flow' \| 'waterfall'` | `'single'` | 布局类型 |
+| spanCount | number | 1 | 列数，flow/waterfall 时有效 |
+| enableScroll | boolean | true | 是否允许滚动 |
+| bounces | boolean | true | iOS 弹性回弹 |
+| initialScrollIndex | number | 0 | 渲染后自动滚动到的节点位置 |
+| lowerThresholdItemCount | number | 0 | 触发底部事件的剩余子节点数阈值 |
+| upperThresholdItemCount | number | 0 | 触发顶部事件的剩余子节点数阈值 |
+| scrollEventThrottle | number | 200 | 滚动事件节流间隔 (ms) |
+| onScroll | (e: ListScrollEvent) => void | - | 滚动 |
+| onScrollToUpper | (e: ListScrollToUpperEvent) => void | - | 滚动到顶部 |
+| onScrollToLower | (e: ListScrollToLowerEvent) => void | - | 滚动到底部 |
+| onLayoutComplete | (e: ListLayoutCompleteEvent) => void | - | 首屏渲染完成 |
+
+### list-item 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| item-key | string | - | **必填**，唯一标识 |
+| sticky-top | boolean | false | 吸顶 |
+| sticky-bottom | boolean | false | 吸底 |
+| full-span | boolean | false | 多列时占满一行 |
+| estimated-main-axis-size-px | number | -1 | 预估主轴尺寸 (px)，瀑布流时建议填 |
+| recyclable | boolean | true | 是否可回收 |
+
+```tsx
+// 基础列表
+<list style={{ height: '400px' }}>
+  {data.map(item => (
+    <list-item key={item.id} item-key={item.id}>
+      <view style={{ padding: '16px' }}><text>{item.title}</text></view>
+    </list-item>
+  ))}
+</list>
+
+// 吸顶 header
+<list style={{ height: '400px' }}>
+  <list-item item-key="header" sticky-top>
+    <view style={{ padding: '12px', background: '#f5f5f5' }}><text>吸顶标题</text></view>
+  </list-item>
+  {data.map(item => (
+    <list-item key={item.id} item-key={item.id}>
+      <view style={{ padding: '16px' }}><text>{item.title}</text></view>
+    </list-item>
+  ))}
+</list>
+
+// 瀑布流
+<list style={{ height: '100vh' }} listType="waterfall" spanCount={2}>
+  {items.map(item => (
+    <list-item key={item.id} item-key={item.id} estimated-main-axis-size-px={item.height}>
+      <view style={{ height: `${item.height}px` }}><text>{item.title}</text></view>
+    </list-item>
+  ))}
+</list>
+```
+
+---
+
+## `<swiper>` / `<swiper-item>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | T[] | - | 轮播数据 |
+| itemWidth | number | - | 每项宽度 |
+| itemHeight | number \| `'auto'` | - | 每项高度 |
+| children | (prop: RenderFunctionProps\<T\>) => ReactElement | - | 渲染函数，返回 swiper-item |
+| containerWidth | number | screenWidth | 容器宽度 |
+| initialIndex | number | 0 | 初始索引，仅首屏有效 |
+| loop | boolean | false | 循环 |
+| duration | number | 500 | 动画时长 (ms) |
+| onChange | (current: number) => void | - | 索引变化 |
+| onSwipeStart | (current: number) => void | - | 开始滑动 |
+| onSwipeStop | (current: number) => void | - | 停止滑动 |
+
+### swiper-item 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| index | number | - | 当前索引 |
+| real-index | number | index | 真实索引，循环模式下与 index 不同 |
+| style | CSSProperties | - | 样式 |
+| overlap | boolean | false | 透明度有问题时使用 |
+
+```tsx
+<swiper
+  data={images}
+  itemWidth={375}
+  itemHeight={200}
+  loop
+  onChange={(current) => console.log('current:', current)}
+>
+  {({ item, index }) => (
+    <swiper-item index={index}>
+      <image src={item.url} style={{ width: '100%', height: '100%' }} mode="aspectFill" />
+    </swiper-item>
+  )}
+</swiper>
+```

package/dist/skills/doubao-plugin-app/references/frontend/components/text-media.md

@@ -0,0 +1,209 @@
+# 文本与媒体组件
+
+## `<text>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+| textMaxline | string | - | 最大行数，超出省略号 |
+| tailColorConvert | boolean | false | 省略号颜色跟随外层 text 样式 |
+| textSingleLineVerticalAlign | `'normal' \| 'bottom' \| 'center' \| 'top'` | `'normal'` | 单行垂直对齐，inline 文本不支持 |
+| textSelection | boolean | false | 是否可选择文本 |
+| customContextMenu | boolean | false | 开启文本选择后使用自定义菜单 |
+| onClick | (e: TouchEvent) => void | - | 点击 |
+| onLayout | (e: LayoutEvent) => void | - | 布局完成 |
+| onSelectionChange | (e: SelectionChangeEvent) => void | - | 文本选区变化（需开启 textSelection） |
+
+```tsx
+<text textMaxline="2">超出两行显示省略号的长文本...</text>
+<text textSelection>可以被用户选择复制的文本</text>
+```
+
+---
+
+## `<image>`
+
+**必须设置非空 src，且满足以下任意一条，否则图片不显示：**
+- 设置 width + height > 0
+- 设置 `autoSize`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| src | string | - | **必填**，图片地址（http/https/base64） |
+| mode | `'scaleToFill' \| 'aspectFit' \| 'aspectFill' \| 'center'` | `'scaleToFill'` | 缩放模式 |
+| placeholder | string | - | 占位图，用法同 src |
+| autoSize | boolean | false | 加载成功后自动调整为原图尺寸 |
+| flatten | boolean | true | false 时走 Lynx 自定义解码链路，可缓解 Android 大图降采样 |
+| subsample | boolean | true | 是否启用降采样，仅在 `flatten=false` 时可设为 false |
+| onLoad | (e: LoadEvent) => void | - | 加载成功，事件包含宽高 |
+| onError | (e: ErrorEvent) => void | - | 加载失败 |
+| onClick | (e: TouchEvent) => void | - | 点击 |
+
+**mode 说明：**
+
+| 值 | 说明 |
+|----|------|
+| scaleToFill | 拉伸填满，不保持比例 |
+| aspectFit | 保持比例，长边完全显示 |
+| aspectFill | 保持比例，短边完全显示（常用于头像/封面） |
+| center | 不缩放，只显示中间区域 |
+
+**Android 大图说明：** `flatten={false}` 走 Lynx 解码链路，可缓解 Fresco 默认纹理限制导致的超大图片降采样。`subsample={false}` 关闭降采样，超大图存在 OOM 风险，谨慎使用。
+
+```tsx
+<image
+  src="https://example.com/photo.jpg"
+  mode="aspectFill"
+  style={{ width: '200px', height: '200px', borderRadius: '50%' }}
+  onLoad={(e) => console.log('尺寸:', e.detail.width, e.detail.height)}
+/>
+```
+
+---
+
+## `<svg>`
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| className | string | 样式类名 |
+| style | CSSProperties | 内联样式 |
+
+SVG 内容作为子节点传入，使用标准 SVG 元素。
+
+---
+
+## `<video>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| ref | ForwardedRef\<VideoRef\> | - | 实例 ref，可调用播放控制方法 |
+| playUrl | string | - | 播放地址 |
+| poster | string | - | 海报图 |
+| autoPlay | boolean | false | 资源就绪后自动播放 |
+| mute | boolean | true | 静音 |
+| loop | boolean | false | 循环 |
+| objectfit | `'aspectFit' \| 'aspectFill' \| 'scaleToFill'` | `'aspectFit'` | 缩放模式 |
+| style | CSSProperties | - | 设置宽高和圆角 |
+
+### VideoRef 方法
+
+| 方法 | 说明 |
+|------|------|
+| play(callback?) | 播放 |
+| pause(callback?) | 暂停 |
+| stop(callback?) | 停止 |
+| seek(position, play, callback?) | 跳转到指定时间 |
+| replay(play, callback?) | 重新播放 |
+
+```tsx
+import type { VideoRef } from '@doubao-dev/framework/components';
+import { useRef } from '@doubao-dev/framework';
+
+const videoRef = useRef<VideoRef>(null);
+
+<video
+  ref={videoRef}
+  playUrl="https://example.com/video.mp4"
+  poster="https://example.com/poster.jpg"
+  objectfit="aspectFill"
+  style={{ width: '100%', height: '220px', borderRadius: '12px' }}
+/>
+<button onClick={() => videoRef.current?.play()}>播放</button>
+<button onClick={() => videoRef.current?.pause()}>暂停</button>
+```
+
+---
+
+## `<long-image>`
+
+长图分段解码，提供两种用法。
+
+### 简单用法（内置滚动容器）
+
+```tsx
+<long-image
+  src="https://example.com/long.jpg"
+  style={{ height: '70vh' }}
+  onStateChange={(state) => {
+    // state: 'measuring' | 'loading-meta' | 'ready' | 'error'
+    console.log(state);
+  }}
+/>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| src | string | - | **必填** |
+| id | string | 自动生成 | 根节点 id |
+| reloadToken | number | 0 | 变化时重新初始化 |
+| segmentDisplayHeight | number | 600 | 单段目标高度 (px) |
+| decodeOverscanScreens | number | 1 | 预加载屏数 |
+| maxActiveSegments | number | 8 | 同时激活解码上限 |
+| placeholderColor | string | 'transparent' | 非激活段占位背景色 |
+| style | CSSProperties | - | 未设 height 时默认 100vh |
+| onStateChange | (state: LongImageState) => void | - | 状态回调 |
+| onMetricsChange | (metrics: LongImageMetrics) => void | - | 指标回调 |
+
+### Hook 用法（接入外部滚动容器）
+
+```tsx
+import { useLongImage, renderLongImageSegments } from '@doubao-dev/framework/components';
+
+const longImageResult = useLongImage({ src });
+
+<view id={longImageResult.containerId} style={{ height: '70vh' }} onLayoutChange={longImageResult.handleContainerLayoutChange}>
+  <list style={{ width: '100%', height: '100%' }} onScroll={longImageResult.handleScroll}>
+    {renderLongImageSegments(longImageResult, { mode: 'list' })}
+  </list>
+</view>
+```
+
+**⚠️ 长图前有 header 时必须修正 scrollTop：**
+
+```tsx
+const HEADER_HEIGHT = 120;
+const handlePageScroll = (event) => {
+  longImageResult.handleScroll({
+    ...event,
+    detail: { ...event.detail, scrollTop: Math.max(0, event.detail.scrollTop - HEADER_HEIGHT) }
+  });
+};
+```
+
+`handleScroll` 期望接收的 scrollTop 语义是"可视区域顶部相对于长图内容顶部的偏移"，如果长图前有其他内容，外层 scrollTop 需减去该内容高度。
+
+---
+
+## `<web-view>`
+
+Web 模拟器中的 `<web-view>` 通过本地代理承载 H5 页面，页面脚本读取到的
+`location.origin` / `location.host` 可能是调试器本地域名，而不是真机 WebView 中的业务域名。
+如果 H5 依赖 `location.origin` 或 `location.host` 判断测试环境、线上环境、白名单或鉴权逻辑，
+Web 模拟器结果可能与真机不一致，请使用真机调试确认。
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| src | string | 网页地址 |
+| onLoad | (event: { src: string }) => void | 加载成功 |
+| onError | (event: { errorMsg: string; errorCode: number; url: string }) => void | 加载失败 |
+| onMessage | (event: { data: unknown }) => void | 网页向应用 postMessage |
+| ref | Ref&lt;WebViewRef&gt; | 获取 WebView 实例，可调用 `postMessage(data)` 向网页发送消息 |
+
+```tsx
+import { useRef } from '@doubao-dev/framework';
+import type { WebViewRef } from '@doubao-dev/framework/components';
+
+const webViewRef = useRef<WebViewRef>(null);
+
+<>
+  <web-view
+    ref={webViewRef}
+    src="https://example.com"
+    onLoad={(event) => console.log('网页加载成功:', event.src)}
+    onError={(event) => console.log('加载错误:', event.errorMsg, event.url)}
+    onMessage={(event) => console.log('收到消息:', event.data)}
+  />
+  <button text="向网页发送消息" onClick={() => webViewRef.current?.postMessage({ type: 'ping' })} />
+</>
+```