@doubao-apps/ai 0.0.26 → 0.0.27

package/dist/contexts/doubao-apps-dev/.ai/reference/components-quick-ref.md

@@ -0,0 +1,103 @@
+# 组件库快速参考
+
+所有组件均已编译为全局变量，**无需任何 import**，直接像 `<view>`、`<text>` 一样使用小写标签即可。
+
+---
+
+## 组件列表
+
+| 组件标签 | 用途 | 关键属性 |
+|---------|------|----------|
+| `<button>` | 按钮交互 | `text`, `type`, `size`, `loading`, `disabled`, `openType`, `onClick` |
+| `<switch>` | 开关切换 | `checked`, `defaultChecked`, `disabled`, `onChange` |
+| `<slider>` | 滑块选择 | `value`(必填), `min`, `max`, `showValue`, `onChange` |
+| `<swiper>` | 轮播容器 | `data`, `itemWidth`, `itemHeight`, `loop`, `duration`, `onChange` |
+| `<swiper-item>` | 轮播项 | `index`, `realIndex` |
+
+---
+
+## button 按钮
+
+```tsx
+<button
+  text="提交"
+  type="primary"       // primary | default | plain
+  size="default"       // default | small | large
+  loading={false}
+  disabled={false}
+  icon={<IconNode />}
+  throttle={500}       // 节流时间(ms)
+  onClick={() => {}}
+/>
+
+{/* 开放能力 */}
+<button
+  openType="getPhoneNumber"
+  onGetPhoneNumber={(e) => console.log(e)}
+/>
+```
+
+---
+
+## switch 开关
+
+```tsx
+{/* 非受控 */}
+<switch defaultChecked onChange={(checked) => {}} />
+
+{/* 受控 */}
+<switch checked={value} onChange={(checked) => setChecked(checked)} />
+```
+
+> `onChange` 回调直接接收 `boolean` 值，而非事件对象。
+
+---
+
+## slider 滑块
+
+```tsx
+const [value, setValue] = useState(50);
+
+<slider
+  value={value}      // 必填，只支持受控
+  min={0}
+  max={100}
+  showValue={true}
+  onChange={(value) => setValue(value)}
+/>
+```
+
+> `onChange` 回调直接接收 `number` 值，而非事件对象。
+
+---
+
+## swiper 轮播
+
+```tsx
+<swiper
+  data={[{ img: 'url1' }, { img: 'url2' }]}
+  itemWidth={300}
+  itemHeight={200}
+  loop={true}
+  duration={500}
+  onChange={(index) => console.log(index)}
+>
+  {({ item, index }) => (
+    <swiper-item index={index} key={index}>
+      <image src={item.img} />
+    </swiper-item>
+  )}
+</swiper>
+```
+
+> `onChange` 回调直接接收当前 `index: number`，而非事件对象。
+
+---
+
+## 注意事项
+
+1. **无需 import**：所有组件直接使用小写标签，不需要从任何包导入
+2. **onChange 回调签名**：switch/slider/swiper 的 `onChange` 直接接收值（boolean/number/number），不是事件对象
+3. **Lynx 不支持 CSS 继承**：组件样式自包含，不依赖父元素样式
+4. **受控/非受控**：switch 支持两种模式，slider 只支持受控模式
+5. **节流处理**：button 内置 500ms 节流，可通过 `throttle` 自定义

package/dist/contexts/doubao-apps-dev/.ai/reference/framework-api-quick-ref.md

@@ -0,0 +1,537 @@
+# Framework API 快速参考
+
+---
+
+# 框架 API 列表
+## app 和 视图
+
+| API | 用途 | 示例 |
+|-----|------|------|
+| `definePage()` | 定义 Page 组件 | `definePage({ aiMeta: {...}, render() {...} })` |
+| `defineWidget()` | 定义 Widget 组件 | `defineWidget({ aiMeta: {...}, render() {...} })` |
+| `defineApp()` | 定义 App 入口 | `defineApp({ onLaunch() {...} })` |
+
+---
+
+## Page 生命周期
+
+| 钩子 | 触发时机 | 用途 |
+|------|---------|------|
+| `onCreated()` | View 创建时 | 初始化数据结构、注册订阅/监听 |
+| `onMounted()` | 首次渲染后（仅一次） | 首次请求、埋点上报、启动一次性任务 |
+| `onShow()` | 首次显示/再次显示时 | 刷新数据、恢复状态、恢复轮询/订阅 |
+| `onHide()` | 页面隐藏时 | 暂停任务、保存草稿、停止轮询/订阅 |
+| `onDestroy()` | 页面销毁时 | 清理资源、取消订阅、释放计时器 |
+| `onError(e)` | 发生错误时 | 错误兜底、上报监控、提示用户 |
+
+---
+
+## Widget 生命周期
+
+| 钩子 | 触发时机 | 用途 |
+|------|---------|------|
+| `onShow()` | 卡片显示时 | 刷新数据、恢复状态 |
+| `onHide()` | 卡片隐藏时 | 暂停操作、保存草稿 |
+| `onForeground()` | 应用回到前台 | 恢复订阅、刷新可见内容 |
+| `onBackground()` | 应用进入后台 | 暂停任务、释放资源 |
+| `onMounted()` | 卡片首次渲染后 | 初始化数据、订阅事件 |
+| `onDestroy()` | 卡片销毁时 | 清理资源、取消订阅 |
+
+---
+
+## Hook
+
+| Hook | 用途 | 示例 |
+|------|------|------|
+| `useState(initial)` | 状态管理 | `const [count, setCount] = useState(0)` |
+| `useEffect(fn, deps)` | 副作用处理 | `useEffect(() => { fetchData() }, [id])` |
+| `useReducer(reducer, initial)` | 复杂状态 | `const [state, dispatch] = useReducer(reducer, {})` |
+| `useCallback(fn, deps)` | 缓存函数 | `const handleClick = useCallback(() => {...}, [])` |
+| `useMemo(fn, deps)` | 缓存计算 | `const value = useMemo(() => compute(), [data])` |
+| `useContext(Context)` | 跨组件状态 | `const theme = useContext(ThemeContext)` |
+| `createContext(default)` | 创建 Context | `const ThemeContext = createContext('light')` |
+
+---
+
+## View Context APIs
+
+| API | 用途 | 返回类型 |
+|-----|------|---------|
+| `getViewContext()` | 获取视图上下文信息 | `AIViewContext` |
+| `getViewData<T>()` | 获取视图数据（泛型） | `T` |
+
+**使用示例**：
+
+```typescript
+import type { AIViewContext } from '@doubao-apps/framework';
+import { getViewContext, getViewData } from '@doubao-apps/framework';
+
+// 获取视图上下文
+const context = getViewContext();
+console.log(context.pageName);    // 页面名称
+console.log(context.lang);        // 语言设置
+console.log(context.appSettings); // 应用配置
+
+// 获取视图数据（类型安全）
+interface MyData {
+  title: string;
+  count: number;
+}
+const data = getViewData<MyData>();
+console.log(data.title, data.count);
+```
+
+**AIViewContext 类型**：
+```typescript
+import type { AIViewContext } from '@doubao-apps/framework';
+```
+
+## 存储 Storage
+
+引入依赖
+
+```ts
+import { setStorage, getStorage, removeStorage, clearStorage, getStorageInfo } from '@doubao-apps/framework/api';
+```
+
+### API 列表
+
+| API | 功能 | 示例 |
+|-----|------|------|
+| `setStorage({ key, data })` | 写入本地缓存 | `setStorage({ key: 'profile', data: { name: 'Tom' } })` |
+| `getStorage({ key })` | 读取本地缓存 | `getStorage<T>({ key: 'profile' })` → `{ data: T }` |
+| `removeStorage({ key })` | 删除指定缓存 | `removeStorage({ key: 'profile' })` |
+| `clearStorage()` | 清空所有缓存 | `clearStorage()` |
+| `getStorageInfo()` | 获取缓存信息 | `getStorageInfo()` → `{ keys, currentSize, limitSize }` |
+
+### 使用示例
+
+```ts
+import { setStorage, getStorage, removeStorage, getStorageInfo } from '@doubao-apps/framework/api';
+
+// 写入数据
+await setStorage({
+  key: 'profile',
+  data: { name: 'Tom', age: 18 },
+});
+
+// 读取数据（支持泛型）
+const result = await getStorage<{ name: string; age: number }>({
+  key: 'profile',
+});
+console.log(result.data.name, result.data.age);
+
+// 删除数据
+await removeStorage({ key: 'profile' });
+
+// 获取缓存信息
+const info = await getStorageInfo();
+console.log(info.keys, info.currentSize, info.limitSize);
+```
+
+# 端能力（系统能力）API
+
+端能力 API 推荐从 `@doubao-apps/framework/api` 引入（运行时调用 + 类型），以 IDE 类型提示为准。
+
+## 引入依赖
+
+```ts
+import { getLocation, getPhoneNumber, navigateTo, navigateBack, request, showToast, setStorage, getStorage } from '@doubao-apps/framework/api';
+```
+
+## 使用示例
+
+```ts
+await showToast({ message: '保存成功' });
+
+await navigateTo({ url: 'detail?id=123' });
+await navigateBack();
+
+const res = await request({ url: '/api/data', method: 'GET' });
+
+const location = await getLocation();
+const phone = await getPhoneNumber();
+```
+## API 速查（节选）
+
+以下为常用端能力 API 的节选，完整以 `@doubao-apps/framework/api` 类型定义为准。
+
+### navigateTo
+
+**参数**:
+```typescript
+{
+  /** 跳转目标，填写页面的 pageId，可拼接 query，如 'detail?id=123' */
+  url: string;
+}
+```
+
+**返回值**: Promise
+
+### redirectTo
+
+**参数**:
+```typescript
+{
+  /** 跳转目标，填写页面的 pageId，如 'settings' */
+  url: string;
+}
+```
+
+**返回值**: Promise
+
+### reLaunch
+
+**参数**:
+```typescript
+{
+  /** 跳转目标，填写页面的 pageId，如 'home' */
+  url: string;
+}
+```
+
+**返回值**: Promise
+
+### navigateBack
+
+**参数**:
+```typescript
+{
+  /** 返回的页面数，默认为 1 */
+  delta?: number;
+}
+```
+
+**返回值**: Promise
+
+> `close()` 已废弃，公开路由场景请优先使用 `navigateBack()`。
+>
+> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`，该值一般与页面的 `aiMeta.id` 一致；需要传参时可直接拼接 query string。
+
+### showToast
+
+**参数**:
+```typescript
+{
+  /** 提示的内容 */
+  message: string;
+  /** Toast 的类型 */
+  type?: 'success' | 'error';
+  /** 图标，通常和 Toast 类型这个选项二选一 */
+  icon?: 'success' | 'error' | 'warn';
+  /** 自定义图标的 URL 或 base64 字符串 */
+  customIcon?: string;
+  /** 提示的延迟时间,单位毫秒 */
+  duration?: number;
+}
+```
+
+**返回值**: 无（空对象）
+
+### showModal
+
+**参数**:
+```typescript
+{
+  /** 模态对话框的标题 */
+  title?: string;
+  /** 模态对话框的内容 */
+  content: string;
+  /** 是否显示取消按钮，默认为 true */
+  showCancel?: boolean;
+  /** 取消按钮的文字，默认为“取消” */
+  cancelText?: string;
+  /** 确认按钮的文字，默认为“确定” */
+  confirmText?: string;
+  /** 是否允许点击蒙层关闭对话框，默认为 false */
+  tapMaskToDismiss?: boolean;
+}
+```
+
+**返回值**:
+```typescript
+{
+  /** 用户点击的行为：'confirm' 表示点击确认按钮，'cancel' 表示点击取消按钮，'mask' 表示点击蒙层 */
+  action: 'confirm' | 'cancel' | 'mask';
+}
+```
+
+### setTitleBar
+
+**参数**:
+```typescript
+{
+  /** 是否隐藏TitleBar。 true: 隐藏， false:显示 */
+  hideTitleBar?: boolean;
+  /** 设置TitleBar的样式， light: 返回按钮为黑色，文字为黑色， dark: 返回按钮为黑色，文字为白色 */
+  mode?: 'light' | 'dark';
+  /** 标题 */
+  title?: string;
+  /** 背景颜色值，有效值为十六进制颜色, 例如 "#ffffff"，  "#00ffffff" (带透明度) */
+  backgroundColor?: string;
+  /** 是否隐藏返回按钮。 true: 隐藏， false:显示 */
+  hideBackButton?: boolean;
+}
+```
+
+> 注：所有字段留空表示不改变
+
+**返回值**: 无（空对象）
+
+---
+
+## 网络请求
+
+| API | 功能 | 示例 |
+|-----|------|------|
+| `request(options)` | 发起请求 | `request({ url: '/api/data', method: 'GET' })` |
+
+### request
+
+**参数**:
+```typescript
+{
+  url: string;
+  header?: Record<string, string>;
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  data?: Record<string, any> | string | ArrayBuffer;
+  dataType?: 'json' | 'string';
+}
+```
+
+> 注：`data` 会根据 `header['content-type']` 自动序列化（`application/json` 会做 JSON 序列化；`application/x-www-form-urlencoded` 会编码为 query string）。
+
+**返回值**:
+```typescript
+{
+  statusCode: number;
+  header: Record<string, string>;
+  data?: string | ArrayBuffer | Record<string, any>;
+}
+```
+
+---
+
+## 系统能力
+
+| API | 功能 | 示例 |
+|-----|------|------|
+| `getLocation(params)` | 获取位置 | `getLocation() → { enable, latitude, longitude }` |
+| `getPhoneNumber()` | 获取手机号 | - |
+| `openApp(params)` | 跳转外部应用 | - |
+
+### getLocation
+
+**参数**: 无
+
+**返回值**:
+```typescript
+{
+  /**
+   * 是否有定位功能和权限
+   */
+  enable: boolean;
+  /**
+   * 纬度
+   */
+  latitude?: number;
+  /**
+   * 经度
+   */
+  longitude?: number;
+}
+```
+
+### getPhoneNumber
+
+**参数**: 无
+
+**返回值**:
+```typescript
+{
+  /** List of phone infos; key name follows Android bridge */
+  phone_info_list: {
+    phoneNumber: string;
+    purePhoneNumber: string;
+    countryCode: number;
+  }[];
+}
+```
+
+### openApp
+
+**参数**:
+```typescript
+{
+  /** Target URI to open, e.g. scheme://path?query */
+  uri: string;
+  /** Optional target package name for Android */
+  targetPackage?: string;
+  /** Optional fallback URL when deep link fails */
+  fallbackUrl?: string;
+}
+```
+
+**返回值**:
+```typescript
+{
+  /** Execution status from client */
+  status: 'deep_link' | 'market' | 'browser';
+}
+```
+
+---
+
+## 消息交互
+
+| API | 功能 | 示例 |
+|-----|------|------|
+| `sendQueryMessage(params)` | 发送用户消息 | `sendQueryMessage({ content: '查询天气', type: 'text' })` |
+| `setAdditionalContext(params)` | 设置上下文 | `setAdditionalContext({ additionalContext: '...' })` |
+
+### sendQueryMessage
+
+**参数**:
+```typescript
+{
+  /** 要发送的消息。根据类型不同，序列化方式可能不同 */
+  content: string;
+
+  /** 消息类型，目前仅支持 text */
+  type: 'text';
+}
+```
+
+**返回值**: 无（空对象）
+
+### setAdditionalContext
+
+**参数**:
+```typescript
+{
+  /** 上下文内容 */
+  additionalContext: string;
+  /** 指定 bot id */
+  botId?: string;
+}
+```
+
+**返回值**: 无（空对象）
+
+---
+
+## 悬浮窗
+
+| API | 功能 | 示例 |
+|-----|------|------|
+| `closeFloatingWindow()` | 关闭悬浮窗 | `closeFloatingWindow()` |
+| `setFloatingWindowVisible(visible)` | 显示/隐藏 | `setFloatingWindowVisible(false)` |
+
+### closeFloatingWindow
+
+**参数**:
+```typescript
+{
+  /** 目标悬浮窗，传空表示当前悬浮窗 */
+  viewId?: string;
+}
+```
+
+**返回值**: 无（空对象）
+
+### setFloatingWindowVisible
+
+**参数**:
+```typescript
+{
+  /** 目标悬浮窗，传空表示当前悬浮窗 */
+  viewId?: string;
+
+  /** 是否显示悬浮窗 */
+  visible: boolean;
+}
+```
+
+**返回值**: 无（空对象）
+
+
+
+
+---
+
+# 常用类型
+
+```typescript
+// Page Input
+interface PageInput {
+  [key: string]: any;  // URL 参数
+}
+
+// src/app.config.ts 中的 metadata 配置
+interface PageAIMeta {
+  id: string;                      // 页面唯一标识
+  title?: string;                  // 页面标题
+  description?: string;            // 页面描述
+}
+
+interface WidgetAIMeta {
+  id: string;                      // 卡片唯一标识
+  name?: string;                   // 卡片名称
+  description?: string;            // 卡片描述
+  boxType?: 'inbox' | 'full_box';  // 卡片类型
+  border?: boolean;                // 是否显示边框
+  keywords?: string[];             // 搜索关键词
+  titleType?: 'none' | 'normal' | 'float';
+}
+
+// Widget 渲染数据类型
+interface WidgetViewData {
+  title: string;
+  content?: string;
+}
+```
+
+---
+
+# 快速示例
+
+
+## 最小 App
+
+```tsx
+import { defineApp } from "@doubao-apps/framework";
+
+// Define AI Metadata
+export default defineApp({
+  aiMeta: {
+    package: "com.doubao.react-lynx-template",
+    name: "Doubao Apps SDK Template",
+    description: "React Lynx 开发模板",
+    keywords: ["react", "lynx", "template", "doubao"],
+  },
+  onLaunch() {
+    console.log("App launched");
+  },
+
+  onPageOpened({ viewId }: { viewId: string }) {
+    console.log("On page opened: ", viewId);
+  },
+
+  onForeground() {
+    console.log("On foreground");
+  },
+
+  onBackground() {
+    console.log("On background");
+  },
+
+  onDestroy() {
+    console.log("On destroyed");
+  },
+});
+```
+
+
+---
+
+**详细指南**: `../guides/component-development.md`