@doubao-apps/create 0.0.33 → 0.0.34

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

@@ -1,589 +0,0 @@
-# 常用开发模式
-
-API 集成、状态管理、页面导航的常用开发模式和最佳实践。
-
----
-
-## 📋 目录
-
-1. [API 集成模式](#api-集成模式)
-2. [状态管理模式](#状态管理模式)
-3. [页面导航模式](#页面导航模式)
-
----
-
-## 🌐 API 集成模式
-
-### Bridge API 调用
-
-使用 Bridge API 访问系统能力（网络请求、存储、设备功能等）。
-
-```tsx
-import { useState } from '@doubao-apps/framework';
-import { getLocation, getPhoneNumber, request } from '@doubao-apps/framework/api';
-
-function DataFetchExample() {
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-
-  // 1. 网络请求
-  const fetchData = async () => {
-    try {
-      setLoading(true);
-      setError(null);
-
-      const response = await request({
-        url: 'https://api.example.com/data',
-        method: 'GET',
-        header: {
-          'Content-Type': 'application/json'
-        }
-      });
-
-      setData(response.data);
-    } catch (err) {
-      setError(err.message);
-    } 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>}
-    </view>
-  );
-}
-```
-
-### POST 请求示例
-
-```tsx
-const submitForm = async (formData: any) => {
-  try {
-    const response = await request({
-      url: 'https://api.example.com/submit',
-      method: 'POST',
-      header: {
-        'Content-Type': 'application/json'
-      },
-      data: formData
-    });
-
-    if (response.statusCode >= 200 && response.statusCode < 300) {
-      console.log('提交成功');
-    }
-  } catch (err) {
-    console.error('提交失败:', err);
-  }
-};
-```
-
-### 请求拦截和错误处理
-
-```tsx
-interface ApiError {
-  code: number;
-  message: string;
-}
-
-async function apiRequest<T>(url: string, options: any): Promise<T> {
-  try {
-    const response = await request({
-      url,
-      ...options
-    });
-
-    // 检查响应状态
-    if (response.statusCode >= 400) {
-      throw {
-        code: response.statusCode,
-        message: response.data?.message || '请求失败'
-      } as ApiError;
-    }
-
-    return response.data as T;
-  } catch (err) {
-    // 统一错误处理
-    if (err.code === 401) {
-      console.error('未授权，请登录');
-    } else if (err.code === 404) {
-      console.error('资源不存在');
-    } else {
-      console.error('请求错误:', err.message);
-    }
-    throw err;
-  }
-}
-
-// 使用示例
-async function fetchUserData(userId: string) {
-  try {
-    const data = await apiRequest<User>(`/api/users/${userId}`, {
-      method: 'GET'
-    });
-    return data;
-  } catch (err) {
-    // 业务逻辑错误处理
-    return null;
-  }
-}
-```
-
----
-
-## 📊 状态管理模式
-
-### 1. 本地状态 (useState)
-
-适用于组件内部状态管理。
-
-```tsx
-import { useState } from '@doubao-apps/framework';
-
-function Counter() {
-  const [count, setCount] = useState(0);
-
-  return (
-    <view>
-      <text>计数: {count}</text>
-      <button onClick={() => setCount(count + 1)}>增加</button>
-      <button onClick={() => setCount(count - 1)}>减少</button>
-      <button onClick={() => setCount(0)}>重置</button>
-    </view>
-  );
-}
-```
-
-### 2. 副作用管理 (useEffect)
-
-适用于数据获取、订阅、定时器等副作用。
-
-```tsx
-import { useState, useEffect } from '@doubao-apps/framework';
-import { request } from '@doubao-apps/framework/api';
-
-function DataLoader() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    // 数据获取
-    const fetchData = async () => {
-      try {
-        const response = await request({
-          url: '/api/data',
-          method: 'GET'
-        });
-        setData(response.data);
-      } catch (error) {
-        console.error('获取数据失败:', error);
-      }
-    };
-
-    fetchData();
-
-    // 清理函数
-    return () => {
-      console.log('组件卸载，清理资源');
-    };
-  }, []); // 空依赖数组表示只在挂载时执行一次
-
-  return <view>{data ? <text>{data}</text> : <text>加载中...</text>}</view>;
-}
-```
-
-### 3. 复杂状态 (useReducer)
-
-适用于复杂状态逻辑。
-
-```tsx
-import { useReducer } from '@doubao-apps/framework';
-
-// 定义状态和动作类型
-interface State {
-  count: number;
-  step: number;
-}
-
-type Action =
-  | { type: 'increment' }
-  | { type: 'decrement' }
-  | { type: 'setStep'; step: number }
-  | { type: 'reset' };
-
-// Reducer 函数
-function reducer(state: State, action: Action): State {
-  switch (action.type) {
-    case 'increment':
-      return { ...state, count: state.count + state.step };
-    case 'decrement':
-      return { ...state, count: state.count - state.step };
-    case 'setStep':
-      return { ...state, step: action.step };
-    case 'reset':
-      return { count: 0, step: 1 };
-    default:
-      return state;
-  }
-}
-
-function ComplexCounter() {
-  const [state, dispatch] = useReducer(reducer, { count: 0, step: 1 });
-
-  return (
-    <view>
-      <text>计数: {state.count}</text>
-      <text>步长: {state.step}</text>
-      <button onClick={() => dispatch({ type: 'increment' })}>增加</button>
-      <button onClick={() => dispatch({ type: 'decrement' })}>减少</button>
-      <button onClick={() => dispatch({ type: 'setStep', step: 5 })}>
-        设置步长为 5
-      </button>
-      <button onClick={() => dispatch({ type: 'reset' })}>重置</button>
-    </view>
-  );
-}
-```
-
-### 4. 跨组件状态共享 (Context)
-
-适用于全局或跨组件状态。
-
-```tsx
-import { createContext, useContext, useState } from '@doubao-apps/framework';
-
-// 1. 创建 Context
-interface ThemeContextValue {
-  theme: 'light' | 'dark';
-  toggleTheme: () => void;
-}
-
-const ThemeContext = createContext<ThemeContextValue | null>(null);
-
-// 2. Provider 组件
-function ThemeProvider({ children }) {
-  const [theme, setTheme] = useState<'light' | 'dark'>('light');
-
-  const toggleTheme = () => {
-    setTheme(prev => (prev === 'light' ? 'dark' : 'light'));
-  };
-
-  return (
-    <ThemeContext.Provider value={{ theme, toggleTheme }}>
-      {children}
-    </ThemeContext.Provider>
-  );
-}
-
-// 3. 使用 Context
-function ThemedButton() {
-  const context = useContext(ThemeContext);
-  if (!context) throw new Error('必须在 ThemeProvider 内使用');
-
-  const { theme, toggleTheme } = context;
-
-  return (
-    <button
-      className={theme === 'light' ? 'light-button' : 'dark-button'}
-      onClick={toggleTheme}
-    >
-      切换主题
-    </button>
-  );
-}
-
-// 4. 应用中使用
-function App() {
-  return (
-    <ThemeProvider>
-      <view>
-        <ThemedButton />
-      </view>
-    </ThemeProvider>
-  );
-}
-```
-
-### 5. 自定义 Hook
-
-封装可复用的状态逻辑。
-
-```tsx
-import { useState, useEffect } from '@doubao-apps/framework';
-import { request } from '@doubao-apps/framework/api';
-
-// 自定义 Hook：数据获取
-function useFetch<T>(url: string) {
-  const [data, setData] = useState<T | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    const fetchData = async () => {
-      try {
-        setLoading(true);
-        setError(null);
-        const response = await request({ url, method: 'GET' });
-        setData(response.data as T);
-      } catch (err) {
-        setError(err.message);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchData();
-  }, [url]);
-
-  return { data, loading, error };
-}
-
-// 使用自定义 Hook
-function UserProfile({ userId }) {
-  const { data: user, loading, error } = useFetch<User>(`/api/users/${userId}`);
-
-  if (loading) return <text>加载中...</text>;
-  if (error) return <text>错误: {error}</text>;
-  if (!user) return <text>无数据</text>;
-
-  return (
-    <view>
-      <text>{user.name}</text>
-      <text>{user.email}</text>
-    </view>
-  );
-}
-```
-
----
-
-## 🧭 页面导航模式
-
-### 1. 打开新页面
-
-```tsx
-import { navigateTo, redirectTo, reLaunch } from '@doubao-apps/framework/api';
-
-// 保留当前页面，打开详情页
-function openFullPage() {
-  navigateTo({
-    url: 'user-profile?userId=12345'
-  });
-}
-
-// 替换当前页面
-function openSettingsPage() {
-  redirectTo({
-    url: 'settings'
-  });
-}
-
-// 清空页面栈并回到首页
-function relaunchHome() {
-  reLaunch({
-    url: 'home'
-  });
-}
-```
-
-这里的 `url` 直接使用目标页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如
-`src/pages/detail/index.tsx` 默认为 `detail`。如需传参，可继续拼接 query string。
-
-### 2. 页面间传参
-
-```tsx
-import { navigateTo } from '@doubao-apps/framework/api';
-
-function buildPageUrl(pageId: 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;
-}
-
-// 发送方
-function navigateWithParams() {
-  navigateTo({
-    url: buildPageUrl('detail-page', {
-      id: '123',
-      name: '商品名称',
-      price: 99.99
-    })
-  });
-}
-
-// 接收方 (detail-page)
-import { getViewData } from '@doubao-apps/framework';
-
-interface DetailPageData {
-  id: string;
-  name: string;
-  price: number;
-}
-
-export default definePage({
-  render() {
-    // getViewData() 直接返回传入页面的最终对象
-    const { id, name, price } = getViewData<DetailPageData>();
-
-    return (
-      <view>
-        <text>ID: {id}</text>
-        <text>名称: {name}</text>
-        <text>价格: {price}</text>
-      </view>
-    );
-  }
-});
-```
-
-### 3. 返回上一页
-
-```tsx
-import { navigateBack } from '@doubao-apps/framework/api';
-
-function closeCurrentPage() {
-  navigateBack();
-}
-```
-
-### 4. 页面栈管理
-
-```tsx
-import { navigateBack } from '@doubao-apps/framework/api';
-
-// 场景 1: 返回上一页
-function goBack() {
-  navigateBack();
-}
-
-// 场景 2: 返回多级页面
-function goBackTwoPages() {
-  navigateBack({ delta: 2 });
-}
-```
-
-### 5. 页面生命周期导航处理
-
-```tsx
-export default definePage({
-  onShow() {
-    // 页面显示时调用（包括从其他页面返回）
-    console.log('页面显示');
-    // 可以在这里刷新数据
-  },
-  onHide() {
-    // 页面隐藏时调用
-    console.log('页面隐藏');
-    // 可以在这里暂停视频、保存草稿等
-  },
-  onDestroy() {
-    // 页面销毁时调用
-    console.log('页面销毁');
-    // 清理资源、取消订阅等
-  },
-  render() {
-    return <view>页面内容</view>;
-  }
-});
-```
-
-### 6. 九宫格页面导航
-
-```tsx
-import { navigateTo } from '@doubao-apps/framework/api';
-
-// 打开九宫格页面
-function openGridPage() {
-  navigateTo({
-    url: 'app-grid'
-  });
-}
-
-// 九宫格页面定义
-export default definePage({
-  render() {
-    const apps = [
-      { id: 'app1', name: '应用1', icon: '🎯' },
-      { id: 'app2', name: '应用2', icon: '📱' },
-      { id: 'app3', name: '应用3', icon: '⚡' }
-    ];
-
-    return (
-      <view className="grid-container">
-        {apps.map(app => (
-          <view
-            key={app.id}
-            className="grid-item"
-            onClick={() => navigateTo({ url: app.id })}
-          >
-            <text className="icon">{app.icon}</text>
-            <text className="name">{app.name}</text>
-          </view>
-        ))}
-      </view>
-    );
-  }
-});
-```
-
----
-
-## 🎯 最佳实践
-
-### API 集成
-
-1. **统一错误处理** - 封装 API 请求函数，统一处理错误
-2. **请求取消** - 组件卸载时取消未完成的请求
-3. **缓存策略** - 合理使用缓存减少网络请求
-4. **加载状态** - 始终提供加载和错误状态反馈
-
-### 状态管理
-
-1. **最小化状态** - 只存储必要的状态，能计算的不存储
-2. **状态提升** - 共享状态提升到最近的公共父组件
-3. **避免过度渲染** - 使用 useMemo、useCallback 优化性能
-4. **状态持久化** - 重要状态考虑持久化到本地存储
-
-### 页面导航
-
-1. **合理的页面层级** - 避免页面栈过深（建议不超过 3-4 层）
-2. **参数验证** - 接收页面参数时进行验证和默认值处理
-3. **返回结果** - 关闭页面时返回必要的结果数据
-4. **生命周期管理** - 合理使用生命周期钩子管理资源
-
----
-
-## 📚 延伸阅读
-
-- **组件基础** → [./component-basics.md](./component-basics.md)
-- **组件开发完整指南** → [../guides/component-development.md](../guides/component-development.md)
-- **API 参考** → [../reference/framework-api-quick-ref.md](../reference/framework-api-quick-ref.md)
-- **最佳实践** → [../guides/best-practices.md](../guides/best-practices.md)