@doubao-apps/create 0.0.28 → 0.0.29

package/dist/template-empty/references/reference/framework-api-quick-ref.md

@@ -7,8 +7,8 @@
 
 | API | 用途 | 示例 |
 |-----|------|------|
-| `definePage()` | 定义 Page 组件 | `definePage({ aiMeta: {...}, render() {...} })` |
-| `defineWidget()` | 定义 Widget 组件 | `defineWidget({ aiMeta: {...}, render() {...} })` |
+| `definePage()` | 定义 Page 组件 | `definePage({ render() {...} })` |
+| `defineWidget()` | 定义 Widget 组件 | `defineWidget({ render() {...} })` |
 | `defineApp()` | 定义 App 入口 | `defineApp({ onLaunch() {...} })` |
 
 ---
@@ -77,8 +77,8 @@ interface MyData {
   title: string;
   count: number;
 }
-const data = getViewData<MyData>();
-console.log(data.title, data.count);
+const viewData = getViewData<MyData>();
+console.log(viewData.title, viewData.count);
 ```
 
 **AIViewContext 类型**：
@@ -206,7 +206,7 @@ const phone = await getPhoneNumber();
 
 > `close()` 已废弃，公开路由场景请优先使用 `navigateBack()`。
 >
-> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`，该值一般与页面的 `aiMeta.id` 一致；需要传参时可直接拼接 query string。
+> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如 `src/pages/detail/index.tsx` 默认为 `detail`。需要传参时可直接拼接 query string。
 
 ### showToast
 
@@ -461,36 +461,41 @@ const phone = await getPhoneNumber();
 
 # 常用类型
 
-```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';
-}
+`src/app.config.ts` 需要配置 `appId` 和 `name`。Page / Widget metadata 使用可选的 `pages`、`widgets` 数组声明：
 
-// Widget 渲染数据类型
-interface WidgetViewData {
-  title: string;
-  content?: string;
-}
+```typescript
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    'pages/home/index',
+    {
+      entry: 'pages/account/demo/index',
+      id: 'account-demo',
+      title: '账号示例页',
+      description: '多级目录页面示例'
+    }
+  ],
+  widgets: [
+    'widgets/user-card/index',
+    {
+      entry: 'widgets/order/detail/index',
+      id: 'order-detail',
+      name: '订单详情卡片',
+      description: '多级目录卡片示例',
+      boxType: 'inbox',
+      border: true,
+      keywords: ['order'],
+      titleType: 'normal'
+    }
+  ]
+});
 ```
 
+字符串数组项只声明入口，不补 metadata；对象数组项用于同时声明入口和 metadata。
+
 ---
 
 # 快速示例
@@ -498,17 +503,25 @@ interface WidgetViewData {
 
 ## 最小 App
 
+### src/app.config.ts
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.doubao.react-lynx-template',
+  name: 'Doubao Apps SDK Template',
+  description: 'React Lynx 开发模板',
+  keywords: ['react', 'lynx', 'template', 'doubao']
+});
+```
+
+### src/app.ts
+
 ```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");
   },

package/dist/template-empty/references/reference/open-api/01-/345/237/272/347/241/200-/350/264/246/345/217/267-/347/263/273/347/273/237.md

@@ -482,7 +482,7 @@ showToast({
 ```ts
 expiredWidget({
   widgetInstanceId: 'instance_123',
-  schema: '${pageId}?key=value'
+  url: '${pageId}?key=value'
 });
 ```
 
@@ -1851,18 +1851,28 @@ mcp入参，如果expectedAction里预期要调用工具，需要在这里写明
 
 点击失效卡要跳转的页面 detailText
 
-##### schema?
+##### ~~schema?~~
 
 > `optional` **schema**: `string`
 
 点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同
 
+###### Deprecated
+
+使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段
+
 ##### title?
 
 > `optional` **title**: `string`
 
 点击失效卡要跳转的页面 title
 
+##### url?
+
+> `optional` **url**: `string`
+
+点击失效卡要跳转的页面 url 或 sslocal schema
+
 ##### widgetInstanceId
 
 > **widgetInstanceId**: `string`

package/dist/template-empty/references/reference/open-api/10-/350/256/276/345/244/207-/350/256/276/345/244/207/346/226/271/345/220/221.md

@@ -10,6 +10,7 @@
 | --- | --- |
 | [startDeviceMotionListening](#startdevicemotionlistening) | 开始监听设备方向变化。<br><br>需配对调用 stopDeviceMotionListening。 |
 | [stopDeviceMotionListening](#stopdevicemotionlistening) | 停止监听设备方向变化。 |
+| [onDeviceMotionChange](#ondevicemotionchange) | 监听设备方向变化事件。<br><br>返回取消监听函数。 |
 
 ## API 详情
 
@@ -47,6 +48,39 @@
 
 `Promise`\<`object`\>
 
+<a id="ondevicemotionchange"></a>
+### onDeviceMotionChange()
+
+> **onDeviceMotionChange**(`handler`): () => `void`
+
+监听设备方向变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onDeviceMotionChange } from '@doubao-apps/framework/api';
+
+const off = onDeviceMotionChange(({ alpha, beta, gamma }) => {
+  console.log(alpha, beta, gamma);
+});
+
+off();
+```
+
 ## 相关类型
 
 <a id="startdevicemotionlisteningparams"></a>

package/dist/template-empty/references/reference/open-api/README.md

@@ -15,7 +15,7 @@
 | 设备 / 加速度计 | 加速度计监听能力。 | 3 | [查看](./07-设备-加速度计.md) |
 | 设备 / iBeacon | iBeacon 搜索和结果读取能力。 | 3 | [查看](./08-设备-ibeacon.md) |
 | 设备 / 罗盘 | 罗盘监听能力。 | 3 | [查看](./09-设备-罗盘.md) |
-| 设备 / 设备方向 | 设备方向监听能力。 | 2 | [查看](./10-设备-设备方向.md) |
+| 设备 / 设备方向 | 设备方向监听能力。 | 3 | [查看](./10-设备-设备方向.md) |
 | 设备 / 陀螺仪 | 陀螺仪监听能力。 | 3 | [查看](./11-设备-陀螺仪.md) |
 | UI / 输入 | 键盘和输入框选区能力。 | 1 | [查看](./12-ui-输入.md) |
 | 设备 / 网络 | 网络类型和本机局域网 IP。 | 3 | [查看](./13-设备-网络.md) |

package/dist/template-empty/references/reference/open-api.md

@@ -450,7 +450,7 @@ closePage();
 ```ts
 expiredWidget({
   widgetInstanceId: 'instance_123',
-  schema: '${pageId}?key=value'
+  url: '${pageId}?key=value'
 });
 ```
 
@@ -1537,6 +1537,40 @@ off();
 
 ***
 
+### onDeviceMotionChange()
+
+> **onDeviceMotionChange**(`handler`): () => `void`
+
+监听设备方向变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onDeviceMotionChange } from '@doubao-apps/framework/api';
+
+const off = onDeviceMotionChange(({ alpha, beta, gamma }) => {
+  console.log(alpha, beta, gamma);
+});
+
+off();
+```
+
+***
+
 ### onGyroscopeChange()
 
 > **onGyroscopeChange**(`handler`): () => `void`
@@ -3841,6 +3875,35 @@ Wi-Fi SSID。
 
 ***
 
+### DeviceMotionChangeEvent
+
+设备方向变化事件。
+
+#### Properties
+
+##### alpha
+
+> **alpha**: `number`
+
+当手机坐标 X/Y 和地球坐标 X/Y 重合时，绕 Z 轴转动的夹角。
+范围为 [0, 2π)，逆时针转动为正。
+
+##### beta
+
+> **beta**: `number`
+
+当手机坐标 Y/Z 和地球坐标 Y/Z 重合时，绕 X 轴转动的夹角。
+范围为 [-π, π)。
+
+##### gamma
+
+> **gamma**: `number`
+
+当手机坐标 X/Z 和地球坐标 X/Z 重合时，绕 Y 轴转动的夹角。
+范围为 [-π/2, π/2)。
+
+***
+
 ### DispatchActionDirectiveParams
 
 下发动作指令的请求参数。
@@ -3945,18 +4008,28 @@ mcp入参，如果expectedAction里预期要调用工具，需要在这里写明
 
 点击失效卡要跳转的页面 detailText
 
-##### schema?
+##### ~~schema?~~
 
 > `optional` **schema**: `string`
 
 点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同
 
+###### Deprecated
+
+使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段
+
 ##### title?
 
 > `optional` **title**: `string`
 
 点击失效卡要跳转的页面 title
 
+##### url?
+
+> `optional` **url**: `string`
+
+点击失效卡要跳转的页面 url 或 sslocal schema
+
 ##### widgetInstanceId
 
 > **widgetInstanceId**: `string`
@@ -6305,6 +6378,22 @@ iBeacon 距离等级。
 
 ***
 
+### DeviceMotionChangeListener()
+
+> **DeviceMotionChangeListener**: (`event`) => `void`
+
+设备方向变化事件监听函数。
+
+#### Parameters
+
+• **event**: [`DeviceMotionChangeEvent`](doubao-apps-sdk-open-api.md#devicemotionchangeevent)
+
+#### Returns
+
+`void`
+
+***
+
 ### DeviceOrientation
 
 > **DeviceOrientation**: `"portrait"` \| `"landscape"`

package/dist/template-empty/references/rules/dos-and-donts.md

@@ -22,29 +22,105 @@ npm install @doubao-apps/framework
 
 ### 组件开发
 
-#### ✅ 定义完整的 aiMeta
-```tsx
+#### ✅ 在 app.config.ts 配置 App 元信息
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用'
+});
+```
+
+#### ✅ 需要稳定首页时在 app.config.ts 明确入口
+```ts
+// ✅ pages 数组第一项会作为首页（appletEntry）
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/home/index',
+      id: 'home',
+      title: '首页',
+      description: '应用默认打开的页面'
+    }
+  ]
+});
+```
+
+一级页面目录不写进 `pages` 也会自动发现；如果首页不是历史默认的 `index`，或需要固定首页顺序，建议显式配置 `pages`
+数组第一项。
+
+#### ✅ 需要补充展示信息时在 app.config.ts 定义 metadata
+```ts
 // ✅ 好的做法
-export default definePage({
-  aiMeta: {
-    id: 'user-profile',
-    title: '用户资料',
-    description: '展示和编辑用户个人资料'
-  },
-  // ...
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/user-profile/index',
+      id: 'user-profile',
+      title: '用户资料',
+      description: '展示和编辑用户个人资料'
+    }
+  ]
 });
 ```
 
-```tsx
-// ❌ 不好的做法
-export default definePage({
-  aiMeta: {
-    id: 'page1'  // 缺少 title、description 等信息
-  },
-  // ...
+```ts
+// ❌ 不好的做法：缺少 title、description 等信息
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/user-profile/index',
+      id: 'page1'
+    }
+  ]
+});
+```
+
+#### ✅ 多级目录必须显式声明 entry
+```ts
+// src/pages/account/demo/index.tsx
+// src/widgets/order/detail/index.tsx
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    // 只声明入口、不补 metadata 时，可以直接写字符串
+    'pages/account/demo/index',
+    {
+      entry: 'pages/account/settings/index',
+      id: 'account-settings',
+      title: '账号设置页'
+    }
+  ],
+  widgets: [
+    'widgets/order/detail/index',
+    {
+      entry: 'widgets/order/summary/index',
+      id: 'order-summary',
+      name: '订单摘要卡片'
+    }
+  ]
 });
 ```
 
+如果不配置 `id`，默认取入口最后一级目录名：`pages/account/demo/index` 默认为 `demo`，`widgets/order/detail/index`
+默认为 `detail`。
+
 #### ✅ 分离样式文件
 ```tsx
 // ✅ 好的做法
@@ -88,8 +164,8 @@ interface UserInfo {
 
 export default defineWidget({
   render() {
-    const input = getViewData<UserInfo>();
-    return <view>{input.name}</view>;
+    const viewData = getViewData<UserInfo>();
+    return <view>{viewData.name}</view>;
   }
 });
 ```
@@ -99,13 +175,16 @@ export default defineWidget({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  widgets: {
-    'widgets/user-card': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/user-card/index',
       id: 'user-card',
       name: '用户卡片',
       description: '用户信息卡片'
     }
-  }
+  ]
 });
 ```
 
@@ -113,8 +192,8 @@ export default defineAppConfig({
 // ❌ 不好的做法
 export default defineWidget({
   render() {
-    const input = getViewData<any>();  // 使用 any 类型，失去类型检查
-    return <view>{input.name}</view>;
+    const viewData = getViewData<any>();  // 使用 any 类型，失去类型检查
+    return <view>{viewData.name}</view>;
   }
 });
 ```
@@ -123,8 +202,6 @@ export default defineWidget({
 ```tsx
 // ✅ 好的做法
 export default definePage({
-  aiMeta: { /* ... */ },
-
   onShow() {
     console.log('Page shown');
   },
@@ -149,15 +226,15 @@ export default definePage({
 // ✅ 好的做法
 export default defineWidget({
   render() {
-    const input = getViewData<{ items: string[] }>();
+    const viewData = getViewData<{ items: string[] }>();
     // 处理空数据
-    if (!input.items || input.items.length === 0) {
+    if (!viewData.items || viewData.items.length === 0) {
       return <view>暂无数据</view>;
     }
 
     return (
       <view>
-        {input.items.map((item, index) => (
+        {viewData.items.map((item, index) => (
           <view key={index}>{item}</view>
         ))}
       </view>
@@ -170,11 +247,11 @@ export default defineWidget({
 // ❌ 不好的做法
 export default defineWidget({
   render() {
-    const input = getViewData<any>();
-    // 没有检查 input.items 是否存在
+    const viewData = getViewData<any>();
+    // 没有检查 viewData.items 是否存在
     return (
       <view>
-        {input.items.map(item => <view>{item}</view>)}
+        {viewData.items.map(item => <view>{item}</view>)}
       </view>
     );
   }
@@ -321,24 +398,24 @@ export default definePage({
 // ❌ 错误
 export default defineWidget({
   render() {
-    const input = getViewData<any>();
+    const viewData = getViewData<any>();
     // @ts-ignore
-    return <view>{input.unknownProperty}</view>;
+    return <view>{viewData.unknownProperty}</view>;
   }
 });
 ```
 
 ```tsx
 // ✅ 正确
-interface Input {
+interface UserInfo {
   name: string;
   age: number;
 }
 
 export default defineWidget({
   render() {
-    const input = getViewData<Input>();
-    return <view>{input.name}</view>;
+    const viewData = getViewData<UserInfo>();
+    return <view>{viewData.name}</view>;
   }
 });
 ```

package/dist/template-starter/package.json

@@ -6,10 +6,10 @@
     "build": "doubao build"
   },
   "dependencies": {
-    "@doubao-apps/framework": "^0.0.28"
+    "@doubao-apps/framework": "^0.0.29"
   },
   "devDependencies": {
-    "@doubao-apps/kit": "^0.0.28",
+    "@doubao-apps/kit": "^0.0.29",
     "typescript": "5.5.3"
   },
   "version": "0.0.16"

package/dist/template-starter/references/examples/common-patterns.md

@@ -412,7 +412,8 @@ function relaunchHome() {
 }
 ```
 
-这里的 `url` 直接使用目标页面的 `pageId`，与页面的 `aiMeta.id` 一致；如需传参，可继续拼接 query string。
+这里的 `url` 直接使用目标页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如
+`src/pages/detail/index.tsx` 默认为 `detail`。如需传参，可继续拼接 query string。
 
 ### 2. 页面间传参
 
@@ -441,20 +442,16 @@ function navigateWithParams() {
 // 接收方 (detail-page)
 import { getViewData } from '@doubao-apps/framework';
 
-interface DetailPageInput {
+interface DetailPageData {
   id: string;
   name: string;
   price: number;
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'detail-page',
-    title: '详情页'
-  },
   render() {
     // getViewData() 直接返回传入页面的最终对象
-    const { id, name, price } = getViewData<DetailPageInput>();
+    const { id, name, price } = getViewData<DetailPageData>();
 
     return (
       <view>
@@ -497,10 +494,6 @@ function goBackTwoPages() {
 
 ```tsx
 export default definePage({
-  aiMeta: {
-    id: 'my-page',
-    title: '我的页面'
-  },
   onShow() {
     // 页面显示时调用（包括从其他页面返回）
     console.log('页面显示');
@@ -536,10 +529,6 @@ function openGridPage() {
 
 // 九宫格页面定义
 export default definePage({
-  aiMeta: {
-    id: 'app-grid',
-    title: '应用中心'
-  },
   render() {
     const apps = [
       { id: 'app1', name: '应用1', icon: '🎯' },