@doubao-apps/create 0.0.26 → 0.0.27

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

@@ -399,6 +399,35 @@ closePage();
 
 ***
 
+### expiredWidget()
+
+> **expiredWidget**(`__namedParameters`): `Promise`\<`object`\>
+
+更新过期的 widget 为固定卡片
+
+#### Parameters
+
+• **\_\_namedParameters**: [`ExpiredWidgetParams`](doubao-apps-sdk-open-api.md#expiredwidgetparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+#### Description
+
+用于将状态已经过期的 widget 实例转换为固定的卡片
+
+#### Example
+
+```ts
+expiredWidget({
+  widgetInstanceId: 'instance_123',
+  schema: '${pageId}?key=value'
+});
+```
+
+***
+
 ### getAccountInfo()
 
 > **getAccountInfo**(`params`?): `Promise`\<[`GetAccountInfoResult`](doubao-apps-sdk-open-api.md#getaccountinforesult)\>
@@ -947,8 +976,6 @@ console.log(result.networkType);
 
 #### Remarks
 
-data 会 JSON 反序列化。
-
 #### Example
 
 ```typescript
@@ -1043,8 +1070,6 @@ console.log(result.keys, result.currentSize, result.limitSize);
 
 #### Remarks
 
-data 会 JSON 反序列化。
-
 #### Example
 
 ```typescript
@@ -1354,6 +1379,74 @@ Widget 登录参数。
 
 ***
 
+### onAccelerometerChange()
+
+> **onAccelerometerChange**(`handler`): () => `void`
+
+监听加速度数据变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onAccelerometerChange } from '@doubao-apps/framework/api';
+
+const off = onAccelerometerChange(({ x, y, z, timestamp }) => {
+  console.log(x, y, z, timestamp);
+});
+
+off();
+```
+
+***
+
+### onBatteryInfoChange()
+
+> **onBatteryInfoChange**(`handler`): () => `void`
+
+监听电池信息变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onBatteryInfoChange } from '@doubao-apps/framework/api';
+
+const off = onBatteryInfoChange(({ isLowPowerModeEnabled }) => {
+  console.log(isLowPowerModeEnabled);
+});
+
+off();
+```
+
+***
+
 ### onCompassChange()
 
 > **onCompassChange**(`handler`): () => `void`
@@ -1388,6 +1481,40 @@ off();
 
 ***
 
+### onGyroscopeChange()
+
+> **onGyroscopeChange**(`handler`): () => `void`
+
+监听陀螺仪数据变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onGyroscopeChange } from '@doubao-apps/framework/api';
+
+const off = onGyroscopeChange(({ x, y, z, timestamp }) => {
+  console.log(x, y, z, timestamp);
+});
+
+off();
+```
+
+***
+
 ### onKeyboardHeightChange()
 
 > **onKeyboardHeightChange**(`handler`): () => `void`
@@ -1935,8 +2062,6 @@ await sendSms({
 
 #### Remarks
 
-data 会 JSON 序列化。
-
 #### Example
 
 ```typescript
@@ -1974,8 +2099,6 @@ await setStorage({
 
 #### Remarks
 
-data 会 JSON 序列化。
-
 #### Example
 
 ```typescript
@@ -2522,6 +2645,38 @@ value 需要是 ArrayBuffer。
 
 ## Interfaces
 
+### AccelerometerChangeEvent
+
+加速度数据变化事件。
+
+#### Properties
+
+##### timestamp
+
+> **timestamp**: `number`
+
+数据采集时间戳，单位纳秒。
+
+##### x
+
+> **x**: `number`
+
+X 轴加速度，单位 m/s²。
+
+##### y
+
+> **y**: `number`
+
+Y 轴加速度，单位 m/s²。
+
+##### z
+
+> **z**: `number`
+
+Z 轴加速度，单位 m/s²。
+
+***
+
 ### AddPhoneCalendarParams
 
 添加系统日历事件的请求参数。
@@ -2910,6 +3065,20 @@ value 需要是 ArrayBuffer。
 
 ***
 
+### BatteryInfoChangeEvent
+
+电池信息变化事件。
+
+#### Properties
+
+##### isLowPowerModeEnabled
+
+> **isLowPowerModeEnabled**: `boolean`
+
+是否处于省电模式。
+
+***
+
 ### BeaconInfo
 
 iBeacon 设备信息。
@@ -3548,6 +3717,24 @@ Wi-Fi SSID。
 
 ***
 
+### ExpiredWidgetParams
+
+#### Properties
+
+##### schema?
+
+> `optional` **schema**: `string`
+
+点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同
+
+##### widgetInstanceId
+
+> **widgetInstanceId**: `string`
+
+卡片实例 ID，在卡片环境通过getWidgetInstanceId来获取，其他环境（比如页面）需要通过传参或通信的方式传递过去
+
+***
+
 ### GetAccountInfoResult
 
 获取当前账号信息。
@@ -4287,6 +4474,38 @@ Wi-Fi 的系统开关
 
 ***
 
+### GyroscopeChangeEvent
+
+陀螺仪数据变化事件。
+
+#### Properties
+
+##### timestamp
+
+> **timestamp**: `number`
+
+数据采集时间戳，单位纳秒。
+
+##### x
+
+> **x**: `number`
+
+绕 X 轴旋转的角速度，单位 rad/s。
+
+##### y
+
+> **y**: `number`
+
+绕 Y 轴旋转的角速度，单位 rad/s。
+
+##### z
+
+> **z**: `number`
+
+绕 Z 轴旋转的角速度，单位 rad/s。
+
+***
+
 ### HideInteractionParams
 
 隐藏交互提示框的公共参数。
@@ -5566,6 +5785,38 @@ Wi-Fi SSID。
 
 ## Type Aliases
 
+### AccelerometerChangeListener()
+
+> **AccelerometerChangeListener**: (`event`) => `void`
+
+加速度数据变化事件监听函数。
+
+#### Parameters
+
+• **event**: [`AccelerometerChangeEvent`](doubao-apps-sdk-open-api.md#accelerometerchangeevent)
+
+#### Returns
+
+`void`
+
+***
+
+### BatteryInfoChangeListener()
+
+> **BatteryInfoChangeListener**: (`event`) => `void`
+
+电池信息变化事件监听函数。
+
+#### Parameters
+
+• **event**: [`BatteryInfoChangeEvent`](doubao-apps-sdk-open-api.md#batteryinfochangeevent)
+
+#### Returns
+
+`void`
+
+***
+
 ### BeaconProximity
 
 > **BeaconProximity**: `0` \| `1` \| `2` \| `3`
@@ -5668,6 +5919,22 @@ iBeacon 距离等级。
 
 ***
 
+### GyroscopeChangeListener()
+
+> **GyroscopeChangeListener**: (`event`) => `void`
+
+陀螺仪数据变化事件监听函数。
+
+#### Parameters
+
+• **event**: [`GyroscopeChangeEvent`](doubao-apps-sdk-open-api.md#gyroscopechangeevent)
+
+#### Returns
+
+`void`
+
+***
+
 ### ImageOrientation
 
 > **ImageOrientation**: `"up"` \| `"up-mirrored"` \| `"down"` \| `"down-mirrored"` \| `"left-mirrored"` \| `"right"` \| `"right-mirrored"` \| `"left"`

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

@@ -87,19 +87,6 @@ interface UserInfo {
 }
 
 export default defineWidget({
-  aiMeta: {
-    id: 'user-card',
-    name: '用户卡片',
-    input: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', title: '姓名' },
-        age: { type: 'number', title: '年龄' },
-        avatar: { type: 'string', title: '头像' }
-      },
-      required: ['name', 'age']
-    }
-  },
   render() {
     const input = getViewData<UserInfo>();
     return <view>{input.name}</view>;
@@ -107,6 +94,21 @@ export default defineWidget({
 });
 ```
 
+```ts
+// ✅ 把 metadata 写到 src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/user-card': {
+      id: 'user-card',
+      name: '用户卡片',
+      description: '用户信息卡片'
+    }
+  }
+});
+```
+
 ```tsx
 // ❌ 不好的做法
 export default defineWidget({
@@ -247,20 +249,26 @@ export default definePage({
 ```
 
 ```tsx
-// ✅ 正确 - 在生命周期钩子中请求
-export default definePage({
-  data: {
-    userData: null
-  },
+// ✅ 推荐 - 使用 Hook 管理请求和状态
+import { useEffect, useState } from '@doubao-apps/framework';
 
-  onShow() {
-    fetch('/api/data').then(data => {
-      this.setData({ userData: data });
-    });
-  },
+function UserPage() {
+  const [userData, setUserData] = useState<{ name?: string } | null>(null);
+
+  useEffect(() => {
+    fetch('/api/data')
+      .then(res => res.json())
+      .then(data => {
+        setUserData(data);
+      });
+  }, []);
 
+  return <view>{userData?.name}</view>;
+}
+
+export default definePage({
   render() {
-    return <view>{this.data.userData?.name}</view>;
+    return <UserPage />;
   }
 });
 ```
@@ -351,21 +359,26 @@ export default defineWidget({
 ```
 
 ```tsx
-// ✅ 正确 - 使用实例状态
+// ✅ 推荐 - 使用组件内状态，实例之间互不影响
+import { useState } from '@doubao-apps/framework';
+
+function CounterWidget() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <view
+      onClick={() => {
+        setCount(prev => prev + 1);
+      }}
+    >
+      Count: {count}
+    </view>
+  );
+}
+
 export default defineWidget({
-  data: {
-    count: 0
-  },
   render() {
-    return (
-      <view
-        onClick={() => {
-          this.setData({ count: this.data.count + 1 });
-        }}
-      >
-        Count: {this.data.count}
-      </view>
-    );
+    return <CounterWidget />;
   }
 });
 ```

package/dist/template-empty/AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md - Doubao Apps SDK AI 开发指南
+# Doubao Apps SDK AI 开发指南
 
 本文件专供 AI coding agents（如 Claude、Copilot、Cursor）和开发者使用，提供 Doubao Apps SDK 框架的快速入门、开发规则和文档导航。
 
@@ -31,7 +31,6 @@ pnpm install
 
 # 启动开发
 pnpm dev
-
 ```
 
 **开发服务器命令**：
@@ -66,9 +65,9 @@ my-doubao-app/
 
 - **优先使用 pnpm** 作为包管理器
 - **分离样式文件**：每个组件使用独立的 `.scss` 文件
-- **定义 aiMeta**：为 Page 和 Widget 提供完整的元数据
+- **在 `src/app.config.ts` 中配置 metadata**：为 App、Page 和 Widget 统一配置元数据
 - **使用生命周期钩子**：合理使用 `onShow`、`onMounted` 等
-- **TypeScript 类型**：为 props 和 state 提供类型定义
+- **TypeScript 类型**：使用 `getViewData<T>()`、为 props 和 state 提供类型定义
 - **错误处理**：处理边界情况和错误状态
 
 ### 禁止做法
@@ -92,22 +91,37 @@ my-doubao-app/
 
 Page 是全屏 UI 组件，支持九宫格、浮窗等变体。
 
-**基础结构**：
+**metadata 配置**：
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  pages: {
+    'pages/home': {
+      id: 'my-page',
+      title: '我的页面',
+      description: '页面功能描述'
+    }
+  }
+});
+```
+
+**页面实现**：
 ```tsx
 import { definePage, getViewData } from '@doubao-apps/framework';
 import './index.scss';
 
+interface HomePageData {
+  title: string;
+}
+
 export default definePage({
-  aiMeta: {
-    id: 'my-page',
-    title: '我的页面',
-  },
   onShow() {
     // 页面显示时触发
   },
   render() {
-    const input = getViewData();
-    return <view>页面内容</view>;
+    const input = getViewData<HomePageData>();
+    return <view>{input.title}</view>;
   }
 });
 ```
@@ -118,28 +132,38 @@ export default definePage({
 
 Widget 是聊天流中的卡片组件，在对话中展示。
 
-**基础结构**：
+**metadata 配置**：
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/my-widget': {
+      id: 'my-widget',
+      name: '我的卡片',
+      description: '卡片功能描述',
+      boxType: 'inbox',
+      border: true
+    }
+  }
+});
+```
+
+**卡片实现**：
 ```tsx
 import { defineWidget, getViewData } from '@doubao-apps/framework';
 import './index.scss';
 
+interface MyWidgetData {
+  title: string;
+}
+
 export default defineWidget({
-  aiMeta: {
-    id: 'my-widget',
-    name: '我的卡片',
-    boxType: 'inbox',
-    input: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', title: '标题' }
-      }
-    }
-  },
   onMounted() {
     // 卡片挂载后触发
   },
   render() {
-    const input = getViewData();
+    const input = getViewData<MyWidgetData>();
     return <view>{input.title}</view>;
   }
 });
@@ -208,7 +232,6 @@ API 参考文档
 - **[组件库](.ai/reference/components-quick-ref.md)** - SDK 内置组件速查
 - **[Open API](.ai/reference/open-api/README.md)** - 系统能力 API 目录与详细文档
 
-
 ### 依赖包
 
 - **Framework**：`@doubao-apps/framework` - 核心框架
@@ -243,10 +266,10 @@ API 参考文档
 
 ```
 项目根目录/
-├── AGENTS.md   # 主入口文档（AI Agent 必读）
-└── .ai/                # 详细文档目录
-    ├── guides/         # 开发指南
-    ├── rules/          # 开发规则
-    ├── examples/       # 代码示例
-    └── reference/      # API 参考
+├── AGENTS.md            # 主入口文档（AI Agent 必读）
+└── .ai/                 # 详细文档目录
+    ├── guides/          # 开发指南
+    ├── rules/           # 开发规则
+    ├── examples/        # 代码示例
+    └── reference/       # API 参考
 ```

package/dist/template-empty/README.md

@@ -1,6 +1,6 @@
 # Empty Doubao Apps Template
 
-A minimal template for creating Doubao Apps without example pages.
+A minimal Doubao Apps template for starting from scratch.
 
 ## Getting Started
 
@@ -14,24 +14,71 @@ pnpm dev
 
 ## Project Structure
 
-```
+```text
 src/
-├── app.ts       # App entry point with lifecycle hooks
-└── pages/       # Add your pages here
+├── app.config.ts  # App, Page, and Widget metadata
+├── app.ts         # App lifecycle entry
+└── pages/         # Add your pages here
+```
+
+## Metadata Entry
+
+Use `src/app.config.ts` as the metadata source of truth.
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.demo',
+  name: 'Demo App',
+  pages: {
+    'pages/home': {
+      id: 'home',
+      title: 'Home',
+      description: 'Home page'
+    }
+  }
+});
 ```
 
 ## Creating Pages
 
-Create a new file in `src/pages/` directory:
+1. Create a page file under `src/pages/`.
+2. Register its metadata in `src/app.config.ts`.
 
 ```tsx
-// src/pages/my-page/index.tsx
+// src/pages/home/index.tsx
 import { definePage } from '@doubao-apps/framework';
 
-export default definePage(() => {
-  return <view>
-    <text>Hello World!</text>
-  </view>;
+import './index.scss';
+
+function HomePage() {
+  return (
+    <view>
+      <text>Hello World!</text>
+    </view>
+  );
+}
+
+export default definePage({
+  render() {
+    return <HomePage />;
+  }
+});
+```
+
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  pages: {
+    'pages/home': {
+      id: 'home',
+      title: 'Home',
+      description: 'Home page'
+    }
+  }
 });
 ```