@doubao-apps/create 0.0.28 → 0.0.29-rc.0

package/dist/template-starter/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-starter/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-starter/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-starter/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/src/app.config.ts

@@ -3,33 +3,7 @@ import { defineAppConfig } from '@doubao-apps/kit';
 export default defineAppConfig({
   appId: '<%= appId %>',
   name: '<%= name %>',
-  pages: {
-    'pages/home': {
-      id: 'home',
-      title: 'Doubao Apps SDK',
-      description: 'Doubao Apps SDK 欢迎页面'
-    },
-    'pages/react-lynx': {
-      id: 'react-lynx',
-      title: 'React Lynx',
-      description: '基于 React 的 UI 开发框架介绍'
-    },
-    'pages/lynx': {
-      id: 'lynx',
-      title: 'Lynx',
-      description: '高性能跨平台 UI 引擎介绍'
-    },
-    'pages/applet': {
-      id: 'applet',
-      title: 'Applet',
-      description: '小程序开发模板介绍'
-    }
-  },
-  widgets: {
-    'widgets/weather-card': {
-      id: 'weather-card',
-      name: 'Weather Card',
-      description: '显示当前天气信息的卡片组件'
-    }
-  }
+  pages: [
+    'pages/home/index' // 首页入口
+  ]
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-apps/create",
-  "version": "0.0.28",
+  "version": "0.0.29-rc.0",
   "description": "Create Doubao Apps projects with a single command",
   "type": "module",
   "bin": {