@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/examples/common-patterns.md

@@ -14,24 +14,30 @@ API 集成、状态管理、页面导航的常用开发模式和最佳实践。
 
 ## 🌐 API 集成模式
 
-### Bridge API 调用
+### Open API / 端能力调用
 
-使用 Bridge API 访问系统能力（网络请求、存储、设备功能等）。
+使用 Open API 访问端能力时，先确定调用位置和状态反馈。具体 API 的参数和返回类型以
+[Open API 目录](../reference/open-api/README.md) 为准。
+`request` 本身不是泛型函数，不要写 `request<T>()`；如果需要业务返回类型，先接收 `response`，再对
+`response.data` 做类型收窄或断言。
 
 ```tsx
 import { useState } from '@doubao-apps/framework';
-import { getLocation, getPhoneNumber, request } from '@doubao-apps/framework/api';
+import { request } from '@doubao-apps/framework/api';
+
+function getErrorMessage(error: unknown, fallback: string) {
+  return error instanceof Error ? error.message : fallback;
+}
 
 function DataFetchExample() {
-  const [data, setData] = useState(null);
+  const [data, setData] = useState<Record<string, unknown> | string | ArrayBuffer | null>(null);
   const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
+  const [error, setError] = useState('');
 
-  // 1. 网络请求
   const fetchData = async () => {
     try {
       setLoading(true);
-      setError(null);
+      setError('');
 
       const response = await request({
         url: 'https://api.example.com/data',
@@ -41,39 +47,18 @@ function DataFetchExample() {
         }
       });
 
-      setData(response.data);
+      const responseData = response.data;
+      setData(responseData ?? null);
     } catch (err) {
-      setError(err.message);
+      setError(getErrorMessage(err, '获取数据失败'));
     } finally {
       setLoading(false);
     }
   };
 
-  // 2. 获取手机号（需要用户授权）
-  const fetchPhoneNumber = async () => {
-    try {
-      const result = await getPhoneNumber();
-      console.log('手机号信息:', result);
-    } catch (err) {
-      console.error('获取手机号失败:', err);
-    }
-  };
-
-  // 3. 获取地理位置
-  const fetchLocation = async () => {
-    try {
-      const location = await getLocation();
-      console.log('位置:', location);
-    } catch (err) {
-      console.error('获取位置失败:', err);
-    }
-  };
-
   return (
     <view>
       <button onClick={fetchData}>获取数据</button>
-      <button onClick={fetchPhoneNumber}>获取手机号</button>
-      <button onClick={fetchLocation}>获取位置</button>
       {loading && <text>加载中...</text>}
       {error && <text>错误: {error}</text>}
       {data && <text>数据: {JSON.stringify(data)}</text>}
@@ -85,7 +70,7 @@ function DataFetchExample() {
 ### POST 请求示例
 
 ```tsx
-const submitForm = async (formData: any) => {
+const submitForm = async (formData: Record<string, unknown>) => {
   try {
     const response = await request({
       url: 'https://api.example.com/submit',
@@ -113,7 +98,25 @@ interface ApiError {
   message: string;
 }
 
-async function apiRequest<T>(url: string, options: any): Promise<T> {
+interface ApiRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  header?: Record<string, string>;
+  data?: Record<string, unknown> | string | ArrayBuffer;
+  dataType?: 'json' | 'string';
+}
+
+function getResponseMessage(data: unknown) {
+  if (typeof data === 'object' && data !== null && 'message' in data) {
+    return String(data.message);
+  }
+  return '请求失败';
+}
+
+function isApiError(error: unknown): error is ApiError {
+  return typeof error === 'object' && error !== null && 'code' in error && 'message' in error;
+}
+
+async function apiRequest<T>(url: string, options: ApiRequestOptions): Promise<T> {
   try {
     const response = await request({
       url,
@@ -124,19 +127,19 @@ async function apiRequest<T>(url: string, options: any): Promise<T> {
     if (response.statusCode >= 400) {
       throw {
         code: response.statusCode,
-        message: response.data?.message || '请求失败'
+        message: getResponseMessage(response.data)
       } as ApiError;
     }
 
     return response.data as T;
   } catch (err) {
     // 统一错误处理
-    if (err.code === 401) {
+    if (isApiError(err) && err.code === 401) {
       console.error('未授权，请登录');
-    } else if (err.code === 404) {
+    } else if (isApiError(err) && err.code === 404) {
       console.error('资源不存在');
     } else {
-      console.error('请求错误:', err.message);
+      console.error('请求错误:', getErrorMessage(err, '请求失败'));
     }
     throw err;
   }
@@ -145,7 +148,7 @@ async function apiRequest<T>(url: string, options: any): Promise<T> {
 // 使用示例
 async function fetchUserData(userId: string) {
   try {
-    const data = await apiRequest<User>(`/api/users/${userId}`, {
+    const data = await apiRequest<User>(`https://api.example.com/users/${userId}`, {
       method: 'GET'
     });
     return data;
@@ -156,7 +159,10 @@ async function fetchUserData(userId: string) {
 }
 ```
 
----
+### Open API 使用配方
+
+`common-patterns.md` 只保留通用调用结构。`getLocation`、Storage 等具体端能力的组合示例见
+[open-api-recipes.md](./open-api-recipes.md)；完整参数和返回类型见 [Open API 目录](../reference/open-api/README.md)。
 
 ## 📊 状态管理模式
 
@@ -190,23 +196,25 @@ import { useState, useEffect } from '@doubao-apps/framework';
 import { request } from '@doubao-apps/framework/api';
 
 function DataLoader() {
-  const [data, setData] = useState(null);
+  const [data, setData] = useState<Record<string, unknown> | string | ArrayBuffer | null>(null);
+  const [error, setError] = useState('');
 
   useEffect(() => {
     // 数据获取
     const fetchData = async () => {
       try {
+        setError('');
         const response = await request({
-          url: '/api/data',
+          url: 'https://api.example.com/data',
           method: 'GET'
         });
-        setData(response.data);
+        setData(response.data ?? null);
       } catch (error) {
-        console.error('获取数据失败:', error);
+        setError(error instanceof Error ? error.message : '获取数据失败');
       }
     };
 
-    fetchData();
+    void fetchData();
 
     // 清理函数
     return () => {
@@ -214,7 +222,11 @@ function DataLoader() {
     };
   }, []); // 空依赖数组表示只在挂载时执行一次
 
-  return <view>{data ? <text>{data}</text> : <text>加载中...</text>}</view>;
+  if (error) {
+    return <view>{error}</view>;
+  }
+
+  return <view>{data ? <text>{JSON.stringify(data)}</text> : <text>加载中...</text>}</view>;
 }
 ```
 
@@ -342,31 +354,31 @@ import { request } from '@doubao-apps/framework/api';
 function useFetch<T>(url: string) {
   const [data, setData] = useState<T | null>(null);
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  const [error, setError] = useState('');
 
   useEffect(() => {
     const fetchData = async () => {
       try {
         setLoading(true);
-        setError(null);
+        setError('');
         const response = await request({ url, method: 'GET' });
         setData(response.data as T);
       } catch (err) {
-        setError(err.message);
+        setError(err instanceof Error ? err.message : '请求失败');
       } finally {
         setLoading(false);
       }
     };
 
-    fetchData();
+    void fetchData();
   }, [url]);
 
   return { data, loading, error };
 }
 
 // 使用自定义 Hook
-function UserProfile({ userId }) {
-  const { data: user, loading, error } = useFetch<User>(`/api/users/${userId}`);
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, loading, error } = useFetch<User>(`https://api.example.com/users/${userId}`);
 
   if (loading) return <text>加载中...</text>;
   if (error) return <text>错误: {error}</text>;
@@ -393,45 +405,45 @@ import { navigateTo, redirectTo, reLaunch } from '@doubao-apps/framework/api';
 // 保留当前页面，打开详情页
 function openFullPage() {
   navigateTo({
-    url: 'user-profile?userId=12345'
+    url: '/pages/user-profile/index?userId=12345'
   });
 }
 
 // 替换当前页面
 function openSettingsPage() {
   redirectTo({
-    url: 'settings'
+    url: '/pages/settings/index'
   });
 }
 
 // 清空页面栈并回到首页
 function relaunchHome() {
   reLaunch({
-    url: 'home'
+    url: '/pages/home/index'
   });
 }
 ```
 
-这里的 `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。
 
 ### 2. 页面间传参
 
 ```tsx
 import { navigateTo } from '@doubao-apps/framework/api';
 
-function buildPageUrl(pageId: string, params: Record<string, string | number | boolean>) {
+function buildPageUrl(pagePath: string, params: Record<string, string | number | boolean>) {
   const query = Object.entries(params)
     .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
     .join('&');
 
-  return query ? `${pageId}?${query}` : pageId;
+  return query ? `${pagePath}?${query}` : pagePath;
 }
 
 // 发送方
 function navigateWithParams() {
   navigateTo({
-    url: buildPageUrl('detail-page', {
+    url: buildPageUrl('/pages/detail/index', {
       id: '123',
       name: '商品名称',
       price: 99.99
@@ -439,7 +451,7 @@ function navigateWithParams() {
   });
 }
 
-// 接收方 (detail-page)
+// 接收方 (src/pages/detail/index.tsx)
 import { getViewData } from '@doubao-apps/framework';
 
 interface DetailPageData {
@@ -450,7 +462,7 @@ interface DetailPageData {
 
 export default definePage({
   render() {
-    // getViewData() 直接返回传入页面的最终对象
+    // getViewData<T>() 直接返回传入页面的最终对象
     const { id, name, price } = getViewData<DetailPageData>();
 
     return (
@@ -523,7 +535,7 @@ import { navigateTo } from '@doubao-apps/framework/api';
 // 打开九宫格页面
 function openGridPage() {
   navigateTo({
-    url: 'app-grid'
+    url: '/pages/app-grid/index'
   });
 }
 
@@ -531,9 +543,9 @@ function openGridPage() {
 export default definePage({
   render() {
     const apps = [
-      { id: 'app1', name: '应用1', icon: '🎯' },
-      { id: 'app2', name: '应用2', icon: '📱' },
-      { id: 'app3', name: '应用3', icon: '⚡' }
+      { id: 'app1', name: '应用1', icon: '🎯', path: '/pages/app1/index' },
+      { id: 'app2', name: '应用2', icon: '📱', path: '/pages/app2/index' },
+      { id: 'app3', name: '应用3', icon: '⚡', path: '/pages/app3/index' }
     ];
 
     return (
@@ -542,7 +554,7 @@ export default definePage({
           <view
             key={app.id}
             className="grid-item"
-            onClick={() => navigateTo({ url: app.id })}
+            onClick={() => navigateTo({ url: app.path })}
           >
             <text className="icon">{app.icon}</text>
             <text className="name">{app.name}</text>
@@ -585,5 +597,7 @@ export default definePage({
 
 - **组件基础** → [./component-basics.md](./component-basics.md)
 - **组件开发完整指南** → [../guides/component-development.md](../guides/component-development.md)
+- **Open API 使用配方** → [./open-api-recipes.md](./open-api-recipes.md)
+- **内置组件使用配方** → [./component-recipes.md](./component-recipes.md)
 - **API 参考** → [../reference/framework-api-quick-ref.md](../reference/framework-api-quick-ref.md)
 - **最佳实践** → [../guides/best-practices.md](../guides/best-practices.md)

package/dist/skills/doubao-apps-dev/references/examples/component-basics.md

@@ -37,7 +37,7 @@ src/pages/user-profile/
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
   pages: [
     {
@@ -53,9 +53,14 @@ export default defineAppConfig({
 ### index.tsx
 
 ```tsx
-import { definePage, useState, useEffect } from '@doubao-apps/framework';
+import { definePage, getViewData, useEffect, useState } from '@doubao-apps/framework';
 import './index.scss';
 
+interface UserProfilePageData {
+  userId?: string;
+  title?: string;
+}
+
 interface UserProfile {
   id: string;
   name: string;
@@ -69,6 +74,7 @@ interface UserProfile {
 }
 
 function UserProfilePage() {
+  const viewData = getViewData<UserProfilePageData>();
   const [user, setUser] = useState<UserProfile | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -83,7 +89,7 @@ function UserProfilePage() {
       await new Promise(resolve => setTimeout(resolve, 1000));
 
       const mockData: UserProfile = {
-        id: '12345',
+        id: viewData.userId || '12345',
         name: '张三',
         avatar: 'https://via.placeholder.com/150',
         email: 'zhangsan@example.com',
@@ -107,6 +113,10 @@ function UserProfilePage() {
     console.log('编辑用户资料');
   };
 
+  useEffect(() => {
+    void fetchUserProfile();
+  }, [viewData.userId]);
+
   // 渲染
   if (loading) {
     return (
@@ -133,6 +143,7 @@ function UserProfilePage() {
     <view className="profile-container">
       {/* 头部 */}
       <view className="profile-header">
+        <text className="page-title">{viewData.title || '用户资料'}</text>
         <image className="avatar" src={user.avatar} />
         <text className="name">{user.name}</text>
         <text className="email">{user.email}</text>
@@ -195,6 +206,14 @@ export default definePage({
     text-align: center;
     margin-bottom: 32px;
 
+    .page-title {
+      display: block;
+      font-size: 32px;
+      font-weight: 600;
+      color: #222;
+      margin-bottom: 24px;
+    }
+
     .avatar {
       width: 160px;
       height: 160px;
@@ -523,4 +542,6 @@ export default defineWidget({
 
 - **组件开发完整指南** → [../guides/component-development.md](../guides/component-development.md)
 - **常用开发模式** → [./common-patterns.md](./common-patterns.md)
+- **Open API 使用配方** → [./open-api-recipes.md](./open-api-recipes.md)
+- **内置组件使用配方** → [./component-recipes.md](./component-recipes.md)
 - **API 参考** → [../reference/framework-api-quick-ref.md](../reference/framework-api-quick-ref.md)

package/dist/skills/doubao-apps-dev/references/examples/component-recipes.md

@@ -0,0 +1,71 @@
+# 内置组件使用配方
+
+本文件放内置组件和 Page / Widget 状态组合的示例。组件的完整 props 和事件签名以
+[组件库快速参考](../reference/components-quick-ref.md) 为准；这里重点展示受控状态、事件处理和保存态如何组合。
+
+---
+
+## Settings Page
+
+内置组件用小写标签直接写 JSX，不要 import 组件。需要按钮、开关和滑块时，三个标签都要直接出现在 TSX 中：
+`button` 用 `onClick`；`switch` / `slider` 的 `onChange` 直接接收值，不是事件对象。
+
+```tsx
+import { definePage, getViewData, useState } from '@doubao-apps/framework';
+import './index.scss';
+
+interface SettingsPanelData {
+  title: string;
+  enabled: boolean;
+  volume: number;
+}
+
+function SettingsPanel() {
+  const viewData = getViewData<SettingsPanelData>();
+  const [enabled, setEnabled] = useState(viewData.enabled);
+  const [volume, setVolume] = useState(viewData.volume);
+  const [saving, setSaving] = useState(false);
+  const [message, setMessage] = useState('');
+
+  const handleSave = async () => {
+    setSaving(true);
+    setMessage('');
+    try {
+      await Promise.resolve();
+      setMessage(`已保存: ${enabled ? '开启' : '关闭'} / ${volume}`);
+    } catch {
+      setMessage('保存失败，请重试');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <view className="settings-panel">
+      <text className="settings-title">{viewData.title}</text>
+      <button
+        text={saving ? '保存中' : '保存'}
+        type="primary"
+        loading={saving}
+        disabled={saving}
+        onClick={handleSave}
+      />
+      <switch checked={enabled} onChange={(checked: boolean) => setEnabled(checked)} />
+      <slider
+        value={volume}
+        min={0}
+        max={100}
+        showValue={true}
+        onChange={(nextVolume: number) => setVolume(nextVolume)}
+      />
+      {message && <text className="settings-message">{message}</text>}
+    </view>
+  );
+}
+
+export default definePage({
+  render() {
+    return <SettingsPanel />;
+  }
+});
+```