@doubao-apps/create 0.0.33 → 0.0.34

package/dist/template-starter/references/guides/component-development.md

@@ -1,891 +0,0 @@
-# 组件开发指南
-
-Page（页面）和 Widget（卡片）组件的完整开发指南。
-
----
-
-## 🎯 Page 开发指南
-
-### App 配置、可选入口与多级目录
-
-`src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`。`pages` / `widgets` 是可选的显式入口配置。
-一级页面目录会自动发现，例如 `src/pages/home/index.tsx` 会产出 `pageId: 'home'`；不配置到 `pages` 时仍可构建，
-但 `title`、`description` 等页面 metadata 为空。
-
-需要补 metadata、固定首页顺序或声明多级目录时，再配置 `pages` 数组。`pages` 是有序数组，第一项会作为应用首页
-（最终 manifest 的 `appletEntry`）；如果希望 `home` 是默认打开页面，把 `pages/home/index` 放在第一项。
-数组项可以是字符串，也可以是 `{ entry, ...metadata }` 对象：只声明入口时用字符串；需要补 metadata 时用对象。
-
-如果不配置 `pages` / `widgets`，一级 Page / Widget 仍会按目录产出；Page / Widget 的默认 ID 取入口最后一级目录名，
-页面/卡片 metadata 字段为空，Widget 的 `boxType` 默认为 `inbox`。没有显式 `pages` 顺序时，首页入口会走构建兜底/历史默认
-`index`；首页不是 `index` 时建议配置 `pages` 第一项。
-
-多级目录不会被一级扫描自动发现，例如 `src/pages/account/demo/index.tsx` 需要显式写
-`entry: 'pages/account/demo/index'`。如果不配置 `id`，默认 `pageId` 是最后一级目录名 `demo`。
-
-```ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: [
-    'pages/home/index',
-    'pages/account/demo/index',
-    {
-      entry: 'pages/profile/index',
-      id: 'profile',
-      title: '资料页',
-      description: '补充 metadata 的页面示例'
-    }
-  ]
-});
-```
-
-### 基本结构
-
-```tsx
-import { definePage, getViewData, useState, useEffect } from '@doubao-apps/framework';
-import './index.scss';
-
-export default definePage({
-  // 1. 生命周期钩子
-  onShow() {
-    // 页面显示时调用（包括从其他页面返回）
-    console.log('页面显示');
-  },
-
-  onHide() {
-    // 页面隐藏时调用
-    console.log('页面隐藏');
-  },
-
-  onDestroy() {
-    // 页面销毁时调用
-    console.log('页面销毁');
-  },
-
-  // 2. 渲染函数
-  render() {
-    // 使用 getViewData() 和 getViewContext() 获取数据和上下文
-    const viewData = getViewData();
-
-    return <MyPageComponent {...viewData} />;
-  }
-});
-```
-
-### 页面布局示例
-
-**1. 默认页面布局**
-
-```tsx
-export default definePage({
-  render() {
-    return (
-      <view className="full-page">
-        <view className="header">头部</view>
-        <view className="content">内容区域</view>
-        <view className="footer">底部</view>
-      </view>
-    );
-  }
-});
-```
-
-**2. 九宫格布局示例**
-
-```tsx
-export default definePage({
-  render() {
-    const items = [
-      { id: '1', title: '应用1', icon: '🎯' },
-      { id: '2', title: '应用2', icon: '📱' },
-      { id: '3', title: '应用3', icon: '⚡' }
-    ];
-
-    return (
-      <view className="grid-container">
-        {items.map(item => (
-          <view key={item.id} className="grid-item">
-            <text className="icon">{item.icon}</text>
-            <text className="title">{item.title}</text>
-          </view>
-        ))}
-      </view>
-    );
-  }
-});
-```
-
-### 页面参数接收
-
-```tsx
-interface PageViewData {
-  userId: string;
-  tab?: string;
-}
-
-export default definePage({
-  render() {
-    const viewData = getViewData<PageViewData>();
-    const { userId, tab = 'profile' } = viewData;
-
-    return (
-      <view>
-        <text>用户 ID: {userId}</text>
-        <text>当前标签: {tab}</text>
-      </view>
-    );
-  }
-});
-```
-
-### 页面导航
-
-```tsx
-import { navigateTo, redirectTo, reLaunch } from '@doubao-apps/framework/api';
-
-// 保留当前页面，打开新页面
-navigateTo({
-  url: 'user-detail?userId=123&tab=profile'
-});
-
-// 替换当前页面
-redirectTo({
-  url: 'settings'
-});
-
-// 关闭所有页面并回到首页
-reLaunch({
-  url: 'home'
-});
-```
-
-`url` 在常规页面跳转里填写页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如
-`src/pages/detail/index.tsx` 默认为 `detail`。
-
-页面内可继续通过 `getViewData<PageViewData>()` 读取 URL 中传入的参数。
-
-### 常用模式
-
-**1. 数据加载**
-
-```tsx
-import { useEffect, useState } from '@doubao-apps/framework';
-import { request } from '@doubao-apps/framework/api';
-
-function MyPage({ userId }: { userId: string }) {
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  useEffect(() => {
-    const fetchData = async () => {
-      try {
-        setLoading(true);
-        const result = await request({
-          url: `/api/users/${userId}`,
-          method: 'GET'
-        });
-        setData(result.data);
-      } catch (err) {
-        setError(err.message);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchData();
-  }, [userId]);
-
-  if (loading) return <text>加载中...</text>;
-  if (error) return <text>错误: {error}</text>;
-  if (!data) return <text>无数据</text>;
-
-  return <view>{/* 渲染数据 */}</view>;
-}
-```
-
-**2. 表单提交**
-
-```tsx
-import { useState } from '@doubao-apps/framework';
-import { navigateBack, request, showToast } from '@doubao-apps/framework/api';
-
-function FormPage() {
-  const [formData, setFormData] = useState({
-    name: '',
-    email: ''
-  });
-  const [submitting, setSubmitting] = useState(false);
-
-  const handleSubmit = async () => {
-    try {
-      setSubmitting(true);
-      await request({
-        url: '/api/submit',
-        method: 'POST',
-        data: formData
-      });
-      showToast({ message: '提交成功' });
-      navigateBack(); // 返回上一页
-    } catch (err) {
-      showToast({ message: '提交失败' });
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  return (
-    <view>
-      <input
-        value={formData.name}
-        onInput={e => setFormData({ ...formData, name: e.detail.value })}
-        placeholder="姓名"
-      />
-      <input
-        value={formData.email}
-        onInput={e => setFormData({ ...formData, email: e.detail.value })}
-        placeholder="邮箱"
-      />
-      <button onClick={handleSubmit} disabled={submitting}>
-        {submitting ? '提交中...' : '提交'}
-      </button>
-    </view>
-  );
-}
-```
-
----
-
-## 🎴 Widget 开发指南
-
-### 可选 Widgets 配置
-
-一级 Widget 目录会自动发现，例如 `src/widgets/my-widget/index.tsx` 会产出 `widgetId: 'my-widget'`。不配置
-`widgets` 时仍可构建，但 `name`、`description` 等 metadata 为空，`boxType` 默认是 `inbox`。
-
-需要补 metadata 或声明多级目录时，再配置 `widgets` 数组。多级目录如 `src/widgets/order/detail/index.tsx`
-需要显式写 `entry: 'widgets/order/detail/index'`；如果不配置 `id`，默认 `widgetId` 是最后一级目录名 `detail`。
-数组项可以是字符串，也可以是 `{ entry, ...metadata }` 对象：只声明入口时用字符串；需要补 metadata 时用对象。
-
-```ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  widgets: [
-    'widgets/simple-card/index',
-    'widgets/order/detail/index',
-    {
-      entry: 'widgets/my-widget/index',
-      id: 'my-widget',                 // 卡片唯一标识
-      name: '我的卡片',                 // 卡片名称
-      description: '卡片功能描述',       // 卡片描述
-      boxType: 'inbox',                // 卡片类型: inbox | full_box
-      border: true,
-      keywords: ['demo', 'widget'],
-      titleType: 'normal'
-    }
-  ]
-});
-```
-
-### 基本结构
-
-```tsx
-import { defineWidget, getViewData } from '@doubao-apps/framework';
-import './index.scss';
-
-interface MyWidgetData {
-  title: string;
-  content?: string;
-}
-
-export default defineWidget({
-  onShow() {
-    console.log('卡片显示');
-  },
-
-  onHide() {
-    console.log('卡片隐藏');
-  },
-
-  onForeground() {
-    console.log('应用回到前台');
-  },
-
-  onBackground() {
-    console.log('应用进入后台');
-  },
-
-  onMounted() {
-    // 卡片挂载时调用
-    console.log('卡片挂载');
-  },
-
-  onDestroy() {
-    console.log('卡片销毁');
-  },
-
-  render() {
-    const viewData = getViewData<MyWidgetData>();
-    return <MyWidgetComponent {...viewData} />;
-  }
-});
-```
-
-### 卡片类型 (boxType)
-
-**1. inbox - 普通卡片**
-
-默认卡片类型，适用于绝大多数场景（信息展示、结果回显、轻量交互）。
-
-推荐使用场景：
-- 内容相对简短：标题/摘要/列表/状态提示等
-- 不需要占用整行宽度，希望保持对话流的紧凑阅读体验
-- 交互以按钮、简单表单项为主
-
-```ts
-// src/app.config.ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  widgets: [
-    {
-      entry: 'widgets/info-card/index',
-      id: 'info-card',
-      name: '信息卡片',
-      boxType: 'inbox'
-    }
-  ]
-});
-```
-
-```tsx
-export default defineWidget({
-  render() {
-    const viewData = getViewData<{ title: string; content: string }>();
-
-    return (
-      <view className="info-card">
-        <text className="title">{viewData.title}</text>
-        <text className="content">{viewData.content}</text>
-      </view>
-    );
-  }
-});
-```
-
-**2. full_box - 全宽卡片**
-
-适用于需要更大展示空间的卡片（例如图表、图片墙、复杂表单等）。
-
-```ts
-// src/app.config.ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  widgets: [
-    {
-      entry: 'widgets/user-action-card/index',
-      id: 'user-action-card',
-      name: '全宽卡片示例',
-      boxType: 'full_box'
-    }
-  ]
-});
-```
-
-```tsx
-export default defineWidget({
-  render() {
-    const viewData = getViewData<{ action: string; result: string }>();
-    return (
-      <view className="user-action-card">
-        <text>操作: {viewData.action}</text>
-        <text>结果: {viewData.result}</text>
-      </view>
-    );
-  }
-});
-```
-
-### ViewData 类型
-
-Widget viewData 通过 `getViewData<T>()` 的泛型参数和 TypeScript 接口表达。
-
-```tsx
-interface ProductCardData {
-  name: string;
-  price: number;
-  images?: string[];
-  category: '电子' | '服装' | '食品' | '图书';
-  inStock: boolean;
-  specs?: {
-    color?: string;
-    size?: string;
-  };
-}
-
-export default defineWidget({
-  render() {
-    const viewData = getViewData<ProductCardData>();
-    return (
-      <view className="product-card">
-        <text className="name">{viewData.name}</text>
-        <text className="price">¥{viewData.price}</text>
-        {viewData.images && (
-          <view className="images">
-            {viewData.images.map((img, idx) => (
-              <image key={idx} src={img} />
-            ))}
-          </view>
-        )}
-        <text className="category">{viewData.category}</text>
-        {!viewData.inStock && <text className="out-of-stock">缺货</text>}
-      </view>
-    );
-  }
-});
-```
-
-### 常用模式
-
-**1. 数据获取和展示**
-
-```tsx
-import { useEffect, useState } from '@doubao-apps/framework';
-import { request } from '@doubao-apps/framework/api';
-
-function WeatherWidget({ city }: { city: string }) {
-  const [weather, setWeather] = useState(null);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    const fetchWeather = async () => {
-      try {
-        const response = await request({
-          url: `/api/weather?city=${city}`,
-          method: 'GET'
-        });
-        setWeather(response.data);
-      } catch (err) {
-        console.error('获取天气失败:', err);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchWeather();
-  }, [city]);
-
-  if (loading) return <text>加载中...</text>;
-  if (!weather) return <text>无数据</text>;
-
-  return (
-    <view className="weather-widget">
-      <text className="city">{weather.city}</text>
-      <text className="temp">{weather.temperature}°C</text>
-      <text className="condition">{weather.condition}</text>
-    </view>
-  );
-}
-```
-
-**2. 用户交互**
-
-```tsx
-import { sendQueryMessage } from '@doubao-apps/framework/api';
-
-function InteractiveWidget({ initialCount }: { initialCount: number }) {
-  const [count, setCount] = useState(initialCount);
-
-  const handleIncrement = () => {
-    setCount(count + 1);
-    // 发送一条用户消息到当前会话
-    sendQueryMessage({
-      content: `计数增加到 ${count + 1}`,
-      type: 'text'
-    });
-  };
-
-  return (
-    <view className="interactive-widget">
-      <text>当前计数: {count}</text>
-      <button onClick={handleIncrement}>增加</button>
-    </view>
-  );
-}
-```
-
-**3. 打开页面**
-
-```tsx
-import { navigateTo } from '@doubao-apps/framework/api';
-
-function ActionWidget({ itemId }: { itemId: string }) {
-  const handleViewDetail = () => {
-    navigateTo({
-      url: `item-detail?id=${itemId}`
-    });
-  };
-
-  return (
-    <view>
-      <button onClick={handleViewDetail}>查看详情</button>
-    </view>
-  );
-}
-```
-
----
-
-## 🎨 样式开发
-
-### SCSS 文件组织
-
-```scss
-// 样式变量
-$primary-color: #1890ff;
-$text-color: #333;
-$bg-color: #f5f5f5;
-$border-radius: 8px;
-$spacing: 16px;
-
-// 容器样式
-.container {
-  padding: $spacing;
-  background-color: $bg-color;
-
-  .header {
-    font-size: 36px;
-    color: $text-color;
-    margin-bottom: $spacing;
-  }
-
-  .content {
-    background-color: #fff;
-    border-radius: $border-radius;
-    padding: $spacing;
-  }
-}
-
-// 响应式布局
-.responsive-layout {
-  display: flex;
-  flex-wrap: wrap;
-  gap: $spacing;
-
-  .item {
-    flex: 1 1 calc(50% - #{$spacing});
-    min-width: 200px;
-  }
-}
-```
-
-### 常用布局模式
-
-**1. Flex 布局**
-
-```scss
-.flex-container {
-  display: flex;
-  flex-direction: row;      // row | column
-  justify-content: center;  // flex-start | center | flex-end | space-between
-  align-items: center;      // flex-start | center | flex-end | stretch
-  gap: 16px;
-}
-```
-
-**2. Grid 布局**
-
-```scss
-.grid-container {
-  display: grid;
-  grid-template-columns: repeat(3, 1fr);
-  gap: 16px;
-  padding: 16px;
-}
-```
-
-**3. 卡片布局**
-
-```scss
-.card {
-  background-color: #fff;
-  border-radius: 8px;
-  padding: 24px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  margin-bottom: 16px;
-}
-```
-
----
-
-## 🔌 View Context APIs
-
-在 Page 和 Widget 开发中，有时需要访问视图的上下文信息和数据。Framework 提供了两个核心 API：
-
-### `getViewContext()`
-
-获取当前视图的上下文信息，包含页面环境、配置和语言设置。
-
-**类型定义**：
-```typescript
-import type { AIViewContext } from '@doubao-apps/framework';
-import { getViewContext } from '@doubao-apps/framework';
-
-// AIViewContext 的字段以实际类型定义为准，这里仅展示常用字段：
-// - viewId / pageName / lang / appSettings / replyFor
-```
-
-**使用场景**：
-
-1. **多语言支持**：
-```tsx
-import { getViewContext } from '@doubao-apps/framework';
-
-function GreetingWidget() {
-  const context = getViewContext();
-
-  const greeting = context.lang === 'zh-CN' ? '你好' : 'Hello';
-
-  return <text>{greeting}!</text>;
-}
-```
-
-2. **访问应用配置**：
-```tsx
-function ThemeAwareComponent() {
-  const context = getViewContext();
-  const theme = context.appSettings.theme || 'light';
-
-  return <view className={`theme-${theme}`}>...</view>;
-}
-```
-
-3. **调试和日志**：
-```tsx
-function MyPage() {
-  const context = getViewContext();
-
-  useEffect(() => {
-    console.log('当前页面:', context.pageName);
-    console.log('View ID:', context.viewId);
-  }, []);
-
-  return <view>...</view>;
-}
-```
-
-### `getViewData<T>()`
-
-获取当前视图的数据，支持泛型类型定义，确保类型安全。
-
-**类型定义**：
-```typescript
-import { getViewData } from '@doubao-apps/framework';
-
-function getViewData<T extends Record<string, any>>(): T
-```
-
-**使用场景**：
-
-1. **在非 render 函数中获取数据**：
-```tsx
-import { defineWidget, getViewData } from '@doubao-apps/framework';
-
-interface TodoData {
-  tasks: string[];
-}
-
-export default defineWidget({
-  onMounted() {
-    // 在生命周期钩子中访问数据
-    const viewData = getViewData<TodoData>();
-    console.log('任务列表:', viewData.tasks);
-  },
-
-  render() {
-    // render 函数中使用 getViewData() 获取数据
-    const viewData = getViewData<TodoData>();
-    return <view>{viewData.tasks.length} 个任务</view>;
-  }
-});
-```
-
-2. **在自定义函数中访问数据**：
-```tsx
-interface WeatherData {
-  city: string;
-  temperature: number;
-}
-
-function WeatherWidget() {
-  const loadWeatherIcon = () => {
-    const viewData = getViewData<WeatherData>();
-    return viewData.temperature > 25 ? '☀️' : '❄️';
-  };
-
-  return (
-    <view>
-      <text>{loadWeatherIcon()}</text>
-    </view>
-  );
-}
-```
-
-**注意事项**：
-- ✅ **推荐**：在 render 函数中使用 `getViewData()` 获取数据
-- ✅ **推荐**：在生命周期钩子和自定义函数中使用 `getViewData()` 获取数据
-- 🔒 **类型安全**：始终定义明确的 TypeScript 接口并传递给泛型参数
-
-### 使用 `getViewData()` 和 `getViewContext()`
-
-render 函数不再通过参数接收 viewData 和 context，请使用以下方法获取数据和上下文：
-
-**推荐做法**：
-```tsx
-// ✅ 推荐：render 函数中使用 getViewData()
-render() {
-  const viewData = getViewData<WeatherData>();
-  return <text>{viewData.city}: {viewData.temperature}°C</text>;
-}
-
-// ✅ 推荐：生命周期钩子中使用 getViewData()
-onMounted() {
-  const viewData = getViewData<WeatherData>();
-  // 处理数据...
-}
-
-// ✅ 推荐：同时获取数据和上下文
-render() {
-  const viewData = getViewData<WeatherData>();
-  const context = getViewContext();
-  return <text>{viewData.city} - {context.lang}</text>;
-}
-```
-
----
-
-## 🔧 开发最佳实践
-
-### 1. TypeScript 类型定义
-
-```tsx
-// 定义 props 类型
-interface ComponentProps {
-  title: string;
-  count?: number;
-  onAction: (value: string) => void;
-}
-
-// 定义 state 类型
-interface ComponentState {
-  loading: boolean;
-  data: DataType | null;
-  error: string | null;
-}
-
-function MyComponent({ title, count = 0, onAction }: ComponentProps) {
-  const [state, setState] = useState<ComponentState>({
-    loading: false,
-    data: null,
-    error: null
-  });
-
-  return <view>{/* 组件内容 */}</view>;
-}
-```
-
-### 2. 错误处理
-
-```tsx
-try {
-  // 异步操作
-  const result = await someAsyncOperation();
-  setData(result);
-} catch (err) {
-  // 记录错误
-  console.error('操作失败:', err);
-
-  // 显示用户友好的错误消息
-  setError('操作失败，请重试');
-
-  // 可选：上报错误
-  reportAppLog({
-    level: 'error',
-    message: err.message,
-    context: { operation: 'someAsyncOperation' }
-  });
-}
-```
-
-### 3. 性能优化
-
-```tsx
-import { useMemo, useCallback } from '@doubao-apps/framework';
-
-function OptimizedComponent({ data, onSelect }) {
-  // 缓存计算结果
-  const processedData = useMemo(() => {
-    return data.map(item => ({
-      ...item,
-      computed: expensiveComputation(item)
-    }));
-  }, [data]);
-
-  // 缓存回调函数
-  const handleClick = useCallback((id: string) => {
-    onSelect(id);
-  }, [onSelect]);
-
-  return (
-    <view>
-      {processedData.map(item => (
-        <view key={item.id} onClick={() => handleClick(item.id)}>
-          {item.computed}
-        </view>
-      ))}
-    </view>
-  );
-}
-```
-
-### 4. 生命周期管理
-
-```tsx
-useEffect(() => {
-  // 订阅
-  const subscription = subscribeEvent('data-update', handleDataUpdate);
-
-  // 定时器
-  const timer = setInterval(() => {
-    fetchData();
-  }, 5000);
-
-  // 清理函数
-  return () => {
-    unsubscribeEvent(subscription);
-    clearInterval(timer);
-  };
-}, []);
-```
-
----
-
-## 📚 延伸阅读
-
-- **组件示例** → [../examples/component-basics.md](../examples/component-basics.md)
-- **常用模式** → [../examples/common-patterns.md](../examples/common-patterns.md)
-- **最佳实践** → [best-practices.md](./best-practices.md)
-- **性能优化** → [performance-optimization.md](./performance-optimization.md)
-- **故障排查** → [troubleshooting.md](./troubleshooting.md)
-- **API 参考** → [../reference/framework-api-quick-ref.md](../reference/framework-api-quick-ref.md)