@doubao-apps/ai 0.0.35-rc.0 → 0.0.35

package/dist/public/skills/doubao-components-api/references/reference/form.md

@@ -0,0 +1,146 @@
+# 表单组件
+
+## `<input>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| ref | Ref\<InputRef\> | - | 实例 ref |
+| value | string | - | 受控值 |
+| defaultValue | string | - | 非受控默认值 |
+| placeholder | string | - | 占位文本 |
+| type | `'text' \| 'number' \| 'digit' \| 'password' \| 'tel' \| 'email'` | `'text'` | 输入类型 |
+| maxlength | number | 140 | 最大长度 |
+| disabled | boolean | false | 禁用 |
+| readonly | boolean | false | 只读 |
+| confirmType | `'send' \| 'search' \| 'go' \| 'done' \| 'next'` | `'send'` | 键盘确认按钮类型 |
+| showSoftInputOnFocus | boolean | true | 聚焦时是否显示软键盘 |
+| onInput | (e: BaseEvent\<'bindinput', InputInputEvent\>) => void | - | 输入变化，取值 `e.detail.value` |
+| onFocus | (e: BaseEvent\<'bindfocus', InputFocusEvent\>) => void | - | 聚焦 |
+| onBlur | (e: BaseEvent\<'bindblur', InputBlurEvent\>) => void | - | 失焦 |
+| onConfirm | (e: BaseEvent\<'bindconfirm', InputConfirmEvent\>) => void | - | 点击确认按钮 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+### InputRef 方法
+
+| 方法 | 类型 | 说明 |
+|------|------|------|
+| setValue | (value: string) => Promise\<void\> | 设置值 |
+| getValue | () => Promise\<{ value: string; selectionStart: number; selectionEnd: number }\> | 获取值和选区 |
+| focus | () => Promise\<void\> | 聚焦 |
+| blur | () => Promise\<void\> | 失焦 |
+
+```tsx
+import type { InputRef } from '@doubao-apps/framework/components';
+import { useState, useRef } from '@byted-lynx/react';
+
+// 受控
+const [val, setVal] = useState('');
+<input value={val} onInput={(e) => setVal(e.detail.value)} placeholder="请输入" />
+
+// 通过 ref 控制
+const inputRef = useRef<InputRef>(null);
+<input ref={inputRef} placeholder="请输入" />
+<button onClick={() => inputRef.current?.focus()}>聚焦</button>
+
+// 密码输入
+<input type="password" maxlength={20} placeholder="请输入密码" />
+```
+
+---
+
+## `<textarea>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| placeholder | string | - | 占位文本 |
+| maxlength | number | 140 | 最大长度 |
+| maxlines | number | - | 最大行数 |
+| lineSpacing | number \| `${number}px` \| `${number}rpx` | - | 行间距 |
+| disabled | boolean | false | 禁用 |
+| readonly | boolean | false | 只读 |
+| confirmType | `'send' \| 'search' \| 'go' \| 'done' \| 'next'` | `'done'` | 确认按钮类型 |
+| showSoftInputOnFocus | boolean | true | 聚焦时显示软键盘 |
+| bounces | boolean | true | iOS 弹性效果 |
+| onInput | (e: TextAreaInputEvent) => void | - | 输入变化 |
+| onFocus | (e: TextAreaFocusEvent) => void | - | 聚焦 |
+| onBlur | (e: TextAreaBlurEvent) => void | - | 失焦 |
+| onConfirm | (e: TextAreaConfirmEvent) => void | - | 点击确认按钮 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+<textarea
+  placeholder="请输入内容"
+  maxlength={500}
+  maxlines={5}
+  onInput={(e) => console.log(e.detail.value)}
+/>
+```
+
+---
+
+## `<picker-view>` / `<picker-column>` / `<picker-divider>`
+
+嵌入页面的滚动选择器。
+
+**关键约束：**
+- `picker-view` 高度必须用 **inline `style.height`** 传入，不能只写在 CSS class 中，否则内部 JS 无法同步读取高度，offset 回退为 108px
+- `itemHeight` 要与 `style.height` 配合设置
+
+### picker-view 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| style | CSSProperties | - | **height 必须 inline 传入** |
+| itemHeight | number | 36 | 单个选项高度 (px) |
+| theme | `'light' \| 'dark'` | - | 未传时跟随宿主主题 |
+| onChange | (values: (string \| number)[], options: PickerColumnOption[]) => void | - | 所有列选中项变化 |
+| className | string | - | 样式类名 |
+
+### picker-column 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| options | `{ label: string; value: string \| number; disabled?: boolean }[]` | 列数据 |
+| value | string \| number | 受控当前值 |
+| defaultValue | string \| number | 非受控默认值 |
+| onChange | (value: string \| number, option: PickerColumnOption) => void | 当前列变化 |
+| className | string | 列的类名 |
+| style | CSSProperties | 列的样式 |
+
+### picker-divider 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| text | string | 展示文本 |
+| children | ReactNode | 自定义内容，优先级高于 text |
+| className | string | 类名 |
+| style | CSSProperties | 样式 |
+
+`picker-divider` 不参与值计算，不会出现在 `onChange` 的 values/options 中。
+
+```tsx
+const hours = Array.from({ length: 24 }, (_, i) => ({ label: String(i).padStart(2, '0'), value: i }));
+const minutes = ['00', '15', '30', '45'].map(v => ({ label: v, value: v }));
+
+// 时间选择器（带分隔符）
+<picker-view
+  style={{ height: '216px' }}
+  itemHeight={36}
+  onChange={(values) => console.log('选中:', values)}
+>
+  <picker-column options={hours} defaultValue={10} />
+  <picker-divider text=":" />
+  <picker-column options={minutes} defaultValue="00" />
+</picker-view>
+
+// 年月日选择器
+const years = Array.from({ length: 10 }, (_, i) => ({ label: `${2020 + i}年`, value: 2020 + i }));
+const months = Array.from({ length: 12 }, (_, i) => ({ label: `${i + 1}月`, value: i + 1 }));
+
+<picker-view style={{ height: '216px' }} itemHeight={36}>
+  <picker-column options={years} defaultValue={2024} />
+  <picker-column options={months} defaultValue={1} />
+</picker-view>
+```

package/dist/public/skills/doubao-components-api/references/reference/interactive.md

@@ -0,0 +1,120 @@
+# 交互控件组件
+
+## `<button>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| text | string | - | 按钮文字 |
+| type | `'primary' \| 'default' \| 'plain'` | `'primary'` | 样式类型 |
+| size | `'default' \| 'large' \| 'mini'` | `'default'` | 尺寸 |
+| disabled | boolean | false | 禁用 |
+| loading | boolean | false | 加载中状态 |
+| icon | ReactNode | - | 文字前的图标 |
+| children | ReactNode | - | 自定义内容，优先级高于 icon/text |
+| throttle | number | 500 | onClick 节流时间 (ms) |
+| onClick | (e?: TouchEvent) => void | - | 点击回调 |
+| onDisabledClick | (e?: TouchEvent) => void | - | 禁用状态下点击回调 |
+| openType | `'getPhoneNumber' \| 'agreePrivacyAuthorization' \| 'agreePrivacyAuthorization\|getPhoneNumber'` | - | 开放能力 |
+| onGetPhoneNumber | (e: GetPhoneNumberResult) => void | - | 获取手机号回调，openType 包含 getPhoneNumber 时有效 |
+| onAgreePrivacyAuthorization | (e: AgreePrivacyResult) => void | - | 隐私授权回调，openType 包含 agreePrivacyAuthorization 时有效 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+// 基础按钮
+<button text="提交" type="primary" onClick={() => handleSubmit()} />
+
+// 加载状态
+<button text="加载中" loading />
+
+// 自定义内容
+<button>
+  <image src="icon.png" style={{ width: '16px', height: '16px' }} />
+  <text>自定义按钮</text>
+</button>
+
+// 开放能力：获取手机号
+<button
+  openType="getPhoneNumber"
+  onGetPhoneNumber={(e) => console.log(e)}
+/>
+```
+
+---
+
+## `<switch>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| checked | boolean | - | 受控值；设置后 defaultChecked 被忽略 |
+| defaultChecked | boolean | false | 非受控默认值 |
+| disabled | boolean | false | 禁用 |
+| size | `'default' \| 'large'` | `'large'` | 尺寸 |
+| onChange | (checked: boolean) => void | - | 状态变化，直接接收 boolean，不是事件对象 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+// 非受控
+<switch defaultChecked onChange={(checked) => console.log(checked)} />
+
+// 受控
+const [on, setOn] = useState(false);
+<switch checked={on} onChange={setOn} />
+```
+
+---
+
+## `<slider>`
+
+**仅支持受控用法，必须传 `value`。**
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| value | number | - | **必填**，当前值 |
+| min | number | 0 | 最小值 |
+| max | number | 100 | 最大值 |
+| showValue | boolean | true | 是否显示当前数值 |
+| disabled | boolean | false | 禁用 |
+| onChange | (value: number) => void | - | 数值变化，直接接收 number |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+const [volume, setVolume] = useState(50);
+<slider value={volume} min={0} max={100} onChange={setVolume} />
+```
+
+---
+
+## `<radio-group>` / `<radio>`
+
+```tsx
+const [selected, setSelected] = useState('a');
+
+<radio-group value={selected} onChange={(v) => setSelected(v)}>
+  <radio value="a">选项 A</radio>
+  <radio value="b">选项 B</radio>
+  <radio value="c" disabled>选项 C（禁用）</radio>
+</radio-group>
+```
+
+### radio-group 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | string \| number | 当前选中值（受控） |
+| defaultValue | string \| number | 默认值（非受控） |
+| onChange | (value: string \| number) => void | 选中变化回调 |
+| className | string | 样式类名 |
+| style | CSSProperties | 内联样式 |
+
+### radio 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | string \| number | 该项的值 |
+| disabled | boolean | 禁用 |
+| children | ReactNode | 标签内容 |
+| className | string | 样式类名 |
+| style | CSSProperties | 内联样式 |

package/dist/public/skills/doubao-components-api/references/reference/layout-overlay.md

@@ -0,0 +1,131 @@
+# 容器与覆层组件
+
+## `<view>`
+
+基础布局容器，最常用。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+| flatten | boolean | true | 扁平化节点，避免创建真实渲染对象，提升性能 |
+| onClick | (e: TouchEvent) => void | - | 点击 |
+| onLongPress | (e: TouchEvent) => void | - | 长按 |
+| onTouchStart / onTouchEnd / onTouchMove | (e: TouchEvent) => void | - | 触摸事件 |
+| onAppear | (e: UIAppearanceEvent) => void | - | 进入可视区域 |
+| onDisappear | (e: UIAppearanceEvent) => void | - | 离开可视区域 |
+
+---
+
+## `<popup>`
+
+支持拖拽、多位置停靠的弹窗。
+
+```tsx
+import type { PopupRef } from '@doubao-apps/framework/components';
+import { useRef } from '@doubao-apps/framework';
+
+const popupRef = useRef<PopupRef>(null);
+
+// 打开弹窗
+popupRef.current?.open();   // 默认中心
+popupRef.current?.open(1);  // 顶部
+popupRef.current?.open(-1); // 底部
+popupRef.current?.close();
+
+<popup
+  ref={popupRef}
+  scrollContainerId="popup-scroll"
+  maxHeight={lynx.__globalProps.screenHeight}
+  closeOnMaskClick
+  enableDrag
+  onPopupPositionChange={(pos) => {
+    // 0=中心, 1=顶部, -1=底部, 4=关闭
+  }}
+>
+  {({ 'main-thread:gesture': gesture }) => (
+    <view id="popup-scroll" style={{ height: '100%' }}>
+      <text>弹窗内容</text>
+    </view>
+  )}
+</popup>
+```
+
+### PopupRef 方法
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| open | position?: 0 \| 1 \| -1 | 打开弹窗。0 中心 / 1 顶部 / -1 底部，默认中心 |
+| close | - | 关闭弹窗 |
+| translateTo | position: number \| string | 移动到指定位置，支持数字或 "px" / "%" / "rpx" |
+
+### PopupProps
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| scrollContainerId | string | - | **必填**，内部滚动容器 ID |
+| children | (prop: RenderFunction) => ReactElement | - | 渲染函数 |
+| autoHeight | boolean | false | 根据内容高度自动调整 |
+| contentId | string | - | autoHeight 为 true 时需要设置 |
+| enableDrag | boolean | true | 启用拖拽 |
+| enableBounces | boolean | true | 松手回弹 |
+| closeOnMaskClick | boolean | true | 点击遮罩关闭 |
+| maxHeight | number | screenHeight | 最大高度 |
+| heightPercent | HeightPercent | - | `{ init, top, bottom, boundaryArea, flingThreshold }` |
+| bottomNode | ReactElement | - | 固定在弹窗底部的节点，不受拖动影响 |
+| enterDuration / exitDuration | number | 300 | 进入/退出动画时长 (ms) |
+| onPopupPositionChange | (position: number) => void | - | 位置变化回调 |
+| onPopupTopChange | (height: number) => void | - | 高度变化回调 |
+
+---
+
+## `<movable-area>` / `<movable-view>`
+
+```tsx
+<movable-area style={{ width: '100%', height: '300px' }}>
+  <movable-view direction="all" scale outOfBounds inertia friction={2} damping={20}>
+    <text>拖我 / 双指缩放</text>
+  </movable-view>
+</movable-area>
+```
+
+### movable-view 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| direction | `'all' \| 'vertical' \| 'horizontal' \| 'none'` | `'all'` | 移动方向 |
+| disabled | boolean | false | 禁用 |
+| x / y | number | 0 | 初始偏移 |
+| scale | boolean | false | 双指缩放 |
+| scaleValue | number | 1 | 初始缩放值 |
+| scaleMin / scaleMax | number | 0.5 / 10 | 缩放范围 |
+| outOfBounds | boolean | false | 允许超出区域（松手回弹） |
+| animation | boolean | true | 回弹动画 |
+| damping | number | 20 | 阻尼系数，值越大回弹越快 |
+| inertia | boolean | false | 惯性滑动 |
+| friction | number | 2 | 摩擦系数，值越大越快停止（必须 > 0） |
+| onDrag | (x: number, y: number) => void | - | 拖拽回调 |
+| onScale | (scale: number) => void | - | 缩放回调 |
+
+---
+
+## `<theme-provider>`
+
+让子树消费 `--bg-*` / `--neutral-*` / `--primary-*` 等 CSS 变量时跟随宿主主题（light/dark）。
+
+内置组件会自动应用主题，只在业务自定义内容需要主题变量时才需要包裹。
+
+```tsx
+<theme-provider>
+  <view style={{ background: 'var(--bg-1)' }}>
+    <text style={{ color: 'var(--neutral-text-1)' }}>跟随主题的文字</text>
+  </view>
+</theme-provider>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | ReactNode | - | 子元素 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+| flatten | boolean | false | 默认 false，因为该容器需作为 CSS 变量作用域 |

package/dist/public/skills/doubao-components-api/references/reference/layout-scroll.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/public/skills/doubao-components-api/references/reference/map-canvas.md

@@ -0,0 +1,107 @@
+# 地图与画布组件
+
+## `<map>` / `<map-marker>`
+
+完整文档见 SDK 的 `map.md`。
+
+### map 核心属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| ref | Ref\<MapRef\> | - | 实例 ref |
+| center | `{ longitude: number; latitude: number }` | - | 地图中心 |
+| scale | number | 16 | 缩放级别（3-20） |
+| minScale / maxScale | number | 3 / 20 | 缩放范围 |
+| polyline | Polyline[] | [] | 路线数组 |
+| polygons | Polygon[] | [] | 多边形数组 |
+| circles | Circle[] | [] | 圆数组 |
+| rotate | number | 0 | 旋转角度（度） |
+| showScale | boolean | false | 显示比例尺 |
+| enableScale | boolean | true | 允许缩放 |
+| enableDrag | boolean | true | 允许拖动 |
+| enableRotate | boolean | false | 允许旋转 |
+| mapStyle | `'normal-light' \| 'normal-dark' \| 'simple-light' \| 'simple-dark'` | `'normal-light'` | 地图主题 |
+| onClick | (e: { point: { latitude: number; longitude: number } }) => void | - | 点击地图 |
+| onMapLoaded | () => void | - | 地图加载完成 |
+| onRegionChange | (e) => void | - | 视野变化 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+### MapRef 方法
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| setCenter | (center, scale?) | 设置中心点 |
+| getCenter | () | 获取当前中心点 |
+| getScale | () | 获取当前缩放级别 |
+| setScale | (scale) | 设置缩放级别 |
+| getBound | () | 获取可见区域边界 |
+| setBound | (bounds) | 设置可见区域边界 |
+| fitPoints | (points, padding?) | 视野适配点集，padding 顺序 `[left, right, top, bottom]` |
+| setAnchor | (position) | 设置地图锚点 |
+
+### map-marker 核心属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| position | `{ longitude: number; latitude: number }` | - | 坐标（必填） |
+| children | ReactNode | - | 自定义标记点 UI（必填） |
+| anchor | [number, number] | [0.5, 1] | 经纬度在图标上的锚点 |
+| alpha | number | 1 | 透明度（0-1） |
+| rotation | number | 0 | 旋转角度（0-360） |
+| clickable | boolean | true | 是否可点击 |
+| draggable | boolean | false | 是否可拖拽 |
+| onClick | () => void | - | 点击回调 |
+
+```tsx
+import type { MapRef } from '@doubao-apps/framework/components';
+import { useRef } from '@doubao-apps/framework';
+
+const mapRef = useRef<MapRef>(null);
+
+<map
+  ref={mapRef}
+  center={{ longitude: 116.397, latitude: 39.916 }}
+  scale={15}
+  style={{ width: '100%', height: '300px' }}
+  onMapLoaded={() => mapRef.current?.fitPoints([
+    { longitude: 116.39, latitude: 39.91 },
+    { longitude: 116.40, latitude: 39.92 },
+  ])}
+>
+  <map-marker position={{ longitude: 116.397, latitude: 39.916 }} onClick={() => console.log('clicked')}>
+    <view style={{ width: '24px', height: '24px', background: '#FF3B30', borderRadius: '50%' }} />
+  </map-marker>
+</map>
+```
+
+---
+
+## `<canvas>`
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| ref | Ref\<CanvasRef\> | 实例 ref，获取绘图上下文 |
+| style | CSSProperties | 内联样式（设置宽高） |
+| className | string | 样式类名 |
+| onResize | (e: CanvasResizeEvent) => void | 尺寸变化回调 |
+
+### CanvasRef 方法
+
+通过 ref 获取实例后调用 `getContext('2d')` 获取 2D 绘图上下文，API 与 Web Canvas 基本一致。
+
+```tsx
+import type { CanvasRef } from '@doubao-apps/framework/components';
+import { useRef, useEffect } from '@doubao-apps/framework';
+
+const canvasRef = useRef<CanvasRef>(null);
+
+useEffect(() => {
+  const ctx = canvasRef.current?.getContext('2d');
+  if (!ctx) return;
+  ctx.fillStyle = '#FF3B30';
+  ctx.fillRect(10, 10, 100, 100);
+}, []);
+
+<canvas ref={canvasRef} style={{ width: '300px', height: '300px' }} />
+```