@doubao-apps/ai 0.0.26 → 0.0.27

package/dist/contexts/doubao-apps-dev/.ai/guides/component-development.md

@@ -0,0 +1,857 @@
+# 组件开发指南
+
+Page（页面）和 Widget（卡片）组件的完整开发指南。
+
+---
+
+## 🎯 Page 开发指南
+
+### 基本结构
+
+```tsx
+import { definePage, getViewData, useState, useEffect } from '@doubao-apps/framework';
+import './index.scss';
+
+export default definePage({
+  // 1. AI 元数据配置
+  aiMeta: {
+    id: 'my-page',                    // 页面唯一标识
+    title: '我的页面',                 // 页面标题
+    description: '页面功能描述'         // 页面描述
+  },
+
+  // 2. 生命周期钩子
+  onShow() {
+    // 页面显示时调用（包括从其他页面返回）
+    console.log('页面显示');
+  },
+
+  onHide() {
+    // 页面隐藏时调用
+    console.log('页面隐藏');
+  },
+
+  onDestroy() {
+    // 页面销毁时调用
+    console.log('页面销毁');
+  },
+
+  // 3. 渲染函数
+  render() {
+    // 使用 getViewData() 和 getViewContext() 获取数据和上下文
+    const input = getViewData();
+
+    return <MyPageComponent {...input} />;
+  }
+});
+```
+
+### 页面布局示例
+
+**1. 默认页面布局**
+
+```tsx
+export default definePage({
+  aiMeta: {
+    id: 'full-page',
+    title: '全屏页面'
+  },
+  render() {
+    return (
+      <view className="full-page">
+        <view className="header">头部</view>
+        <view className="content">内容区域</view>
+        <view className="footer">底部</view>
+      </view>
+    );
+  }
+});
+```
+
+**2. 九宫格布局示例**
+
+```tsx
+export default definePage({
+  aiMeta: {
+    id: 'grid-page',
+    title: '九宫格'
+  },
+  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 PageInput {
+  userId: string;
+  tab?: string;
+}
+
+export default definePage({
+  aiMeta: {
+    id: 'user-detail',
+    title: '用户详情'
+  },
+  render() {
+    const input = getViewData<PageInput>();
+    const { userId, tab = 'profile' } = input;
+
+    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`，与该页面的 `aiMeta.id` 一致；需要传参时可直接在后面拼接 query string。
+
+页面内可继续通过 `getViewData<PageInput>()` 读取 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 开发指南
+
+### Metadata 配置
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/my-widget': {
+      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 input = getViewData<MyWidgetData>();
+    return <MyWidgetComponent {...input} />;
+  }
+});
+```
+
+### 卡片类型 (boxType)
+
+**1. inbox - 普通卡片**
+
+默认卡片类型，适用于绝大多数场景（信息展示、结果回显、轻量交互）。
+
+推荐使用场景：
+- 内容相对简短：标题/摘要/列表/状态提示等
+- 不需要占用整行宽度，希望保持对话流的紧凑阅读体验
+- 交互以按钮、简单表单项为主
+
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/info-card': {
+      id: 'info-card',
+      name: '信息卡片',
+      boxType: 'inbox'
+    }
+  }
+});
+```
+
+```tsx
+export default defineWidget({
+  render() {
+    const input = getViewData<{ title: string; content: string }>();
+
+    return (
+      <view className="info-card">
+        <text className="title">{input.title}</text>
+        <text className="content">{input.content}</text>
+      </view>
+    );
+  }
+});
+```
+
+**2. full_box - 全宽卡片**
+
+适用于需要更大展示空间的卡片（例如图表、图片墙、复杂表单等）。
+
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/user-action-card': {
+      id: 'user-action-card',
+      name: '全宽卡片示例',
+      boxType: 'full_box'
+    }
+  }
+});
+```
+
+```tsx
+export default defineWidget({
+  render() {
+    const input = getViewData<{ action: string; result: string }>();
+    return (
+      <view className="user-action-card">
+        <text>操作: {input.action}</text>
+        <text>结果: {input.result}</text>
+      </view>
+    );
+  }
+});
+```
+
+### 输入数据类型
+
+Widget 输入数据通过 `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 input = getViewData<ProductCardData>();
+    return (
+      <view className="product-card">
+        <text className="name">{input.name}</text>
+        <text className="price">¥{input.price}</text>
+        {input.images && (
+          <view className="images">
+            {input.images.map((img, idx) => (
+              <image key={idx} src={img} />
+            ))}
+          </view>
+        )}
+        <text className="category">{input.category}</text>
+        {!input.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({
+  aiMeta: { ... },
+
+  onMounted() {
+    // 在生命周期钩子中访问数据
+    const data = getViewData<TodoData>();
+    console.log('任务列表:', data.tasks);
+  },
+
+  render() {
+    // render 函数中使用 getViewData() 获取数据
+    const input = getViewData<TodoData>();
+    return <view>{input.tasks.length} 个任务</view>;
+  }
+});
+```
+
+2. **在自定义函数中访问数据**：
+```tsx
+interface WeatherData {
+  city: string;
+  temperature: number;
+}
+
+function WeatherWidget() {
+  const loadWeatherIcon = () => {
+    const data = getViewData<WeatherData>();
+    return data.temperature > 25 ? '☀️' : '❄️';
+  };
+
+  return (
+    <view>
+      <text>{loadWeatherIcon()}</text>
+    </view>
+  );
+}
+```
+
+**注意事项**：
+- ✅ **推荐**：在 render 函数中使用 `getViewData()` 获取数据
+- ✅ **推荐**：在生命周期钩子和自定义函数中使用 `getViewData()` 获取数据
+- 🔒 **类型安全**：始终定义明确的 TypeScript 接口并传递给泛型参数
+
+### 使用 `getViewData()` 和 `getViewContext()`
+
+render 函数不再接收 input 和 context 参数，请使用以下方法获取数据和上下文：
+
+**推荐做法**：
+```tsx
+// ✅ 推荐：render 函数中使用 getViewData()
+render() {
+  const input = getViewData<WeatherData>();
+  return <text>{input.city}: {input.temperature}°C</text>;
+}
+
+// ✅ 推荐：生命周期钩子中使用 getViewData()
+onMounted() {
+  const data = getViewData<WeatherData>();
+  // 处理数据...
+}
+
+// ✅ 推荐：同时获取数据和上下文
+render() {
+  const input = getViewData<WeatherData>();
+  const context = getViewContext();
+  return <text>{input.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)