@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/reference/framework-api-quick-ref.md

@@ -91,23 +91,42 @@ import type { AIViewContext } from '@doubao-apps/framework';
 引入依赖
 
 ```ts
-import { setStorage, getStorage, removeStorage, clearStorage, getStorageInfo } from '@doubao-apps/framework/api';
+import {
+  setStorage,
+  setStorageSync,
+  getStorage,
+  getStorageSync,
+  removeStorage,
+  removeStorageSync,
+  clearStorage,
+  clearStorageSync,
+  getStorageInfo,
+  getStorageInfoSync
+} from '@doubao-apps/framework/api';
 ```
 
+`setStorage` / `setStorageSync` 支持写入 JSON 可序列化数据；`getStorage<T>` / `getStorageSync<T>` 会返回
+`{ data: T }`，SDK 会在写入和读取时处理 JSON 编码与解析。
+
 ### API 列表
 
 | API | 功能 | 示例 |
 |-----|------|------|
 | `setStorage({ key, data })` | 写入本地缓存 | `setStorage({ key: 'profile', data: { name: 'Tom' } })` |
+| `setStorageSync({ key, data })` | 同步写入本地缓存 | `setStorageSync({ key: 'profile', data: { name: 'Tom' } })` |
 | `getStorage({ key })` | 读取本地缓存 | `getStorage<T>({ key: 'profile' })` → `{ data: T }` |
+| `getStorageSync({ key })` | 同步读取本地缓存 | `getStorageSync<T>({ key: 'profile' })` → `{ data: T }` |
 | `removeStorage({ key })` | 删除指定缓存 | `removeStorage({ key: 'profile' })` |
+| `removeStorageSync({ key })` | 同步删除指定缓存 | `removeStorageSync({ key: 'profile' })` |
 | `clearStorage()` | 清空所有缓存 | `clearStorage()` |
+| `clearStorageSync()` | 同步清空所有缓存 | `clearStorageSync()` |
 | `getStorageInfo()` | 获取缓存信息 | `getStorageInfo()` → `{ keys, currentSize, limitSize }` |
+| `getStorageInfoSync()` | 同步获取缓存信息 | `getStorageInfoSync()` → `{ keys, currentSize, limitSize }` |
 
 ### 使用示例
 
 ```ts
-import { setStorage, getStorage, removeStorage, getStorageInfo } from '@doubao-apps/framework/api';
+import { getStorage, getStorageInfo, getStorageSync, removeStorage, setStorage } from '@doubao-apps/framework/api';
 
 // 写入数据
 await setStorage({
@@ -127,31 +146,87 @@ await removeStorage({ key: 'profile' });
 // 获取缓存信息
 const info = await getStorageInfo();
 console.log(info.keys, info.currentSize, info.limitSize);
+
+// 同步读取只适合少量、即时读取场景
+const cachedProfile = getStorageSync<{ name: string; age: number }>({ key: 'profile' });
+console.log(cachedProfile.data.name);
 ```
 
 # 端能力（系统能力）API
 
-端能力 API 推荐从 `@doubao-apps/framework/api` 引入（运行时调用 + 类型），以 IDE 类型提示为准。
+端能力 API 从 `@doubao-apps/framework/api` 引入（运行时调用 + 类型），以 IDE 类型提示为准。
 
 ## 引入依赖
 
 ```ts
-import { getLocation, getPhoneNumber, navigateTo, navigateBack, request, showToast, setStorage, getStorage } from '@doubao-apps/framework/api';
+import { getLocation, navigateTo, navigateBack, request, showToast, setStorage, getStorage } from '@doubao-apps/framework/api';
 ```
 
+## 调用位置
+
+`request`、`getLocation`、`setStorage`、`getStorage`、`setStorageSync`、`getStorageSync`、`showToast`、
+`navigateTo` 等异步或系统 API
+不要直接写在 `render()` 中。首次加载放在 `useEffect` 或生命周期钩子；用户动作放在事件处理函数；
+同时保留 loading、error、success 等可见状态。
+
+按钮触发端能力时，内置 `button` 使用 `onClick` 绑定事件函数，不要写 `onTap`、`bindtap` 或 `catchtap`。
+
 ## 使用示例
 
 ```ts
 await showToast({ message: '保存成功' });
 
-await navigateTo({ url: 'detail?id=123' });
+await navigateTo({ url: '/pages/detail/index?id=123' });
 await navigateBack();
 
-const res = await request({ url: '/api/data', method: 'GET' });
+const res = await request({ url: 'https://api.example.com/data', method: 'GET' });
+console.log(res.statusCode, res.data);
 
 const location = await getLocation();
-const phone = await getPhoneNumber();
+console.log(location.latitude, location.longitude, location.timestamp);
 ```
+
+```tsx
+import { definePage, getViewData, useState } from '@doubao-apps/framework';
+import { navigateTo, showToast } from '@doubao-apps/framework/api';
+
+interface NavigationData {
+  title: string;
+  targetUrl: string;
+}
+
+function NavigationPage() {
+  const viewData = getViewData<NavigationData>();
+  const [status, setStatus] = useState<'idle' | 'running' | 'success' | 'error'>('idle');
+
+  const handleNavigate = async () => {
+    setStatus('running');
+    try {
+      await showToast({ message: '准备跳转' });
+      await navigateTo({ url: viewData.targetUrl });
+      setStatus('success');
+    } catch {
+      setStatus('error');
+      await showToast({ message: '跳转失败' });
+    }
+  };
+
+  return (
+    <view>
+      <text>{viewData.title}</text>
+      <text>{status}</text>
+      <button text="显示提示并跳转" onClick={handleNavigate} />
+    </view>
+  );
+}
+
+export default definePage({
+  render() {
+    return <NavigationPage />;
+  }
+});
+```
+
 ## API 速查（节选）
 
 以下为常用端能力 API 的节选，完整以 `@doubao-apps/framework/api` 类型定义为准。
@@ -161,7 +236,7 @@ const phone = await getPhoneNumber();
 **参数**:
 ```typescript
 {
-  /** 跳转目标，填写页面的 pageId，可拼接 query，如 'detail?id=123' */
+  /** 跳转目标，填写 Page 路径，可拼接 query，如 '/pages/detail/index?id=123' */
   url: string;
 }
 ```
@@ -173,7 +248,7 @@ const phone = await getPhoneNumber();
 **参数**:
 ```typescript
 {
-  /** 跳转目标，填写页面的 pageId，如 'settings' */
+  /** 跳转目标，填写 Page 路径，如 '/pages/settings/index' */
   url: string;
 }
 ```
@@ -185,7 +260,7 @@ const phone = await getPhoneNumber();
 **参数**:
 ```typescript
 {
-  /** 跳转目标，填写页面的 pageId，如 'home' */
+  /** 跳转目标，填写 Page 路径，如 '/pages/home/index' */
   url: string;
 }
 ```
@@ -204,9 +279,9 @@ const phone = await getPhoneNumber();
 
 **返回值**: Promise
 
-> `close()` 已废弃，公开路由场景请优先使用 `navigateBack()`。
+> 公开路由场景优先使用 `navigateBack()`。
 >
-> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如 `src/pages/detail/index.tsx` 默认为 `detail`。需要传参时可直接拼接 query string。
+> 常规页面跳转场景下，`url` 使用目标 Page 路径，通常和 `src/pages/<page-name>/index.tsx` 对应，例如 `/pages/detail/index`。需要传参时可直接拼接 query string。
 
 ### showToast
 
@@ -216,7 +291,7 @@ const phone = await getPhoneNumber();
   /** 提示的内容 */
   message: string;
   /** Toast 的类型 */
-  type?: 'success' | 'error';
+  type?: 'default' | 'success' | 'error' | 'warning';
   /** 图标，通常和 Toast 类型这个选项二选一 */
   icon?: 'success' | 'error' | 'warn';
   /** 自定义图标的 URL 或 base64 字符串 */
@@ -226,7 +301,9 @@ const phone = await getPhoneNumber();
 }
 ```
 
-**返回值**: 无（空对象）
+**返回值**: `Promise<object>`（无业务字段）
+
+提示文案字段是 `message`；不需要图标时省略 `icon`。
 
 ### showModal
 
@@ -256,35 +333,14 @@ const phone = await getPhoneNumber();
 }
 ```
 
-### 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(options)` | 发起请求 | `request({ url: 'https://api.example.com/data', method: 'GET' })` |
+
+`request` 不接受泛型参数，不要写 `request<T>()`。需要业务数据类型时，先接收返回值，再对 `response.data`
+做类型收窄或断言。
 
 ### request
 
@@ -294,7 +350,7 @@ const phone = await getPhoneNumber();
   url: string;
   header?: Record<string, string>;
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-  data?: Record<string, any> | string | ArrayBuffer;
+  data?: Record<string, unknown> | string | ArrayBuffer;
   dataType?: 'json' | 'string';
 }
 ```
@@ -316,45 +372,42 @@ const phone = await getPhoneNumber();
 
 | API | 功能 | 示例 |
 |-----|------|------|
-| `getLocation(params)` | 获取位置 | `getLocation() → { enable, latitude, longitude }` |
-| `getPhoneNumber()` | 获取手机号 | - |
+| `getLocation(params)` | 获取位置 | `getLocation() → { latitude, longitude, timestamp, speed, accuracy }` |
 | `openApp(params)` | 跳转外部应用 | - |
 
 ### getLocation
 
-**参数**: 无
+参数包含 `source`、`mode`、`timeoutMs`、`maxCacheMs`。`mode` 为数字枚举：`0` 低功耗、`1` 仅设备、`2`
+高精度（默认）。返回值中的 `timestamp` 是字符串。
+连续位置更新需要坐标系时使用 `startLocationUpdate({ type: 'wgs84' | 'gcj02' })`。
 
-**返回值**:
+**参数**:
 ```typescript
 {
-  /**
-   * 是否有定位功能和权限
-   */
-  enable: boolean;
-  /**
-   * 纬度
-   */
-  latitude?: number;
-  /**
-   * 经度
-   */
-  longitude?: number;
+  /** 调用业务方 */
+  source?: string;
+  /** 定位模式：0 低功耗、1 仅设备、2 高精度（默认） */
+  mode?: number;
+  /** 超时时间，单位毫秒，默认 30000 */
+  timeoutMs?: number;
+  /** 缓存时间，单位毫秒，默认 0 */
+  maxCacheMs?: number;
 }
 ```
 
-### getPhoneNumber
-
-**参数**: 无
-
 **返回值**:
 ```typescript
 {
-  /** List of phone infos; key name follows Android bridge */
-  phone_info_list: {
-    phoneNumber: string;
-    purePhoneNumber: string;
-    countryCode: number;
-  }[];
+  /** 纬度 */
+  latitude: number;
+  /** 经度 */
+  longitude: number;
+  /** 时间戳 */
+  timestamp: string;
+  /** 行进速度，单位：米/秒 */
+  speed: number;
+  /** 定位精度，单位：米 */
+  accuracy: number;
 }
 ```
 
@@ -402,7 +455,7 @@ const phone = await getPhoneNumber();
 }
 ```
 
-**返回值**: 无（空对象）
+**返回值**: 无返回值
 
 ### setAdditionalContext
 
@@ -416,43 +469,7 @@ const phone = await getPhoneNumber();
 }
 ```
 
-**返回值**: 无（空对象）
-
----
-
-## 悬浮窗
-
-| API | 功能 | 示例 |
-|-----|------|------|
-| `closeFloatingWindow()` | 关闭悬浮窗 | `closeFloatingWindow()` |
-| `setFloatingWindowVisible(visible)` | 显示/隐藏 | `setFloatingWindowVisible(false)` |
-
-### closeFloatingWindow
-
-**参数**:
-```typescript
-{
-  /** 目标悬浮窗，传空表示当前悬浮窗 */
-  viewId?: string;
-}
-```
-
-**返回值**: 无（空对象）
-
-### setFloatingWindowVisible
-
-**参数**:
-```typescript
-{
-  /** 目标悬浮窗，传空表示当前悬浮窗 */
-  viewId?: string;
-
-  /** 是否显示悬浮窗 */
-  visible: boolean;
-}
-```
-
-**返回值**: 无（空对象）
+**返回值**: `Promise<object>`（无业务字段）
 
 
 
@@ -461,13 +478,14 @@ const phone = await getPhoneNumber();
 
 # 常用类型
 
-`src/app.config.ts` 需要配置 `appId` 和 `name`。Page / Widget metadata 使用可选的 `pages`、`widgets` 数组声明：
+`src/app.config.ts` 需要配置 `appId` 和 `name`，`appId` 使用开放平台 `db_xxxxxx` 风格。AI 生成 Page / Widget metadata 时使用
+`pages`、`widgets` 数组写法；entry 写到 `index`，不要省略入口文件名：
 
 ```typescript
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
   pages: [
     'pages/home/index',
@@ -509,7 +527,7 @@ export default defineAppConfig({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.doubao.react-lynx-template',
+  appId: 'db_xxxxxx',
   name: 'Doubao Apps SDK Template',
   description: 'React Lynx 开发模板',
   keywords: ['react', 'lynx', 'template', 'doubao']

package/dist/skills/doubao-apps-dev/references/reference/open-api/01-/345/237/272/347/241/200.md

@@ -0,0 +1,136 @@
+# Open API: 基础
+
+账号、授权、宿主基础信息、窗口信息和能力可用性。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getAccountInfo](#getaccountinfo) | 异步获取账号信息。 |
+| [getAccountInfoSync](#getaccountinfosync) | 同步获取账号信息。<br><br>同步 API。 |
+| [authorize](#authorize) | 初始化授权。 |
+| [canIUse](#caniuse) | 检测当前宿主是否支持指定 API 或能力。 |
+
+## API 详情
+
+<a id="getaccountinfo"></a>
+### getAccountInfo()
+
+异步获取账号信息。
+
+## 代码示例
+
+```typescript
+import { getAccountInfo } from '@doubao-apps/framework/api';
+
+const result = await getAccountInfo();
+console.log(result.miniProgram.appId);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<GetAccountInfoResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|miniProgram|`DoubaoAppAccountInfo`|豆包 App账号信息|
+|miniProgram.appId|`string`|豆包 App appId|
+|miniProgram.envVersion|`"develop" \| "trial" \| "release"`|豆包 App 运行环境。<br><br>- develop: 开发版<br>- trial: 体验版<br>- release: 正式版|
+|miniProgram.version|`string`|线上豆包 App 版本号。|
+|plugin|`PluginAccountInfo`|插件账号信息（仅在插件中调用时包含）|
+|plugin.appId|`string`|插件 appId|
+|plugin.version|`string`|插件版本号，'a.b.c' 形式|
+
+<a id="getaccountinfosync"></a>
+### getAccountInfoSync()
+
+同步获取账号信息。
+
+## 代码示例
+
+```typescript
+import { getAccountInfoSync } from '@doubao-apps/framework/api';
+
+const result = getAccountInfoSync();
+console.log(result.miniProgram.appId, result.miniProgram.envVersion, result.miniProgram.version);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `GetAccountInfoResult`。
+
+|字段名|类型|说明|
+|---|---|---|
+|miniProgram|`DoubaoAppAccountInfo`|豆包 App账号信息|
+|miniProgram.appId|`string`|豆包 App appId|
+|miniProgram.envVersion|`"develop" \| "trial" \| "release"`|豆包 App 运行环境。<br><br>- develop: 开发版<br>- trial: 体验版<br>- release: 正式版|
+|miniProgram.version|`string`|线上豆包 App 版本号。|
+|plugin|`PluginAccountInfo`|插件账号信息（仅在插件中调用时包含）|
+|plugin.appId|`string`|插件 appId|
+|plugin.version|`string`|插件版本号，'a.b.c' 形式|
+
+<a id="authorize"></a>
+### authorize()
+
+初始化授权
+
+## 代码示例
+
+```typescript
+import { authorize } from '@doubao-apps/framework/api';
+
+await authorize({ scope: 'scope.userLocation' });
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|scope|`Scope`|是|授权范围|
+
+**类型说明**
+
+- `Scope`: `"scope.userLocation" | "scope.userFuzzyLocation" | "scope.userLocationBackground" | "scope.payment" | "scope.record" | "scope.bluetooth" | "scope.camera" | "scope.addPhoneContact" | "scope.addPhoneCalendar"`
+
+## 返回值
+
+Promise 对象，授权成功时会返回授权结果
+
+<a id="caniuse"></a>
+### canIUse()
+
+检测当前宿主是否支持指定 API 或能力。
+
+## 代码示例
+
+```typescript
+import { canIUse } from '@doubao-apps/framework/api';
+
+const { result } = await canIUse({ schema: 'doubao.getLocation' });
+
+console.log(result);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|schema|`string`|是|-|
+
+## 返回值
+
+返回 `Promise<CanIUseResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|result|`boolean`|-|