@doubao-apps/ai 0.0.26 → 0.0.27

package/dist/contexts/doubao-apps-dev/.ai/examples/component-basics.md

@@ -0,0 +1,509 @@
+# 组件基础示例
+
+Page（页面）和 Widget（卡片）组件的基础用法对比。
+
+---
+
+## 📋 核心差异
+
+| 特性 | Page | Widget |
+|------|------|--------|
+| **使用场景** | 全屏页面、九宫格、浮窗 | 聊天流中的卡片 |
+| **定义方式** | `definePage()` | `defineWidget()` |
+| **输入数据** | URL 参数、页面配置 | AI 生成的结构化数据 |
+| **显示位置** | 独立页面/窗口 | 聊天对话中 |
+| **交互方式** | 完整的页面交互 | 卡片内交互 + 消息发送 |
+| **生命周期** | `onCreated`, `onMounted`, `onShow`, `onHide`, `onDestroy`，`onError` | `onCreated`, `onMounted`, `onShow`, `onHide`, `onDestroy`，`onError`，`onForeground`, `onBackground` |
+
+---
+
+## 🎯 Page 基础示例
+
+### 用户资料页面
+
+**文件结构**：
+```
+src/pages/user-profile/
+├── index.tsx       # 组件逻辑
+└── index.scss      # 组件样式
+```
+
+### index.tsx
+
+```tsx
+import { definePage, useState, useEffect } from '@doubao-apps/framework';
+import './index.scss';
+
+interface UserProfile {
+  id: string;
+  name: string;
+  avatar: string;
+  email: string;
+  stats: {
+    posts: number;
+    followers: number;
+    following: number;
+  };
+}
+
+function UserProfilePage() {
+  const [user, setUser] = useState<UserProfile | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // 数据获取
+  const fetchUserProfile = async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      // 模拟 API 请求
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      const mockData: UserProfile = {
+        id: '12345',
+        name: '张三',
+        avatar: 'https://via.placeholder.com/150',
+        email: 'zhangsan@example.com',
+        stats: {
+          posts: 42,
+          followers: 1234,
+          following: 567
+        }
+      };
+
+      setUser(mockData);
+    } catch (err) {
+      setError('加载失败，请重试');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // 编辑按钮
+  const handleEdit = () => {
+    console.log('编辑用户资料');
+  };
+
+  // 渲染
+  if (loading) {
+    return (
+      <view className="profile-container">
+        <view className="loading">加载中...</view>
+      </view>
+    );
+  }
+
+  if (error) {
+    return (
+      <view className="profile-container">
+        <view className="error">{error}</view>
+        <button onClick={fetchUserProfile}>重试</button>
+      </view>
+    );
+  }
+
+  if (!user) {
+    return null;
+  }
+
+  return (
+    <view className="profile-container">
+      {/* 头部 */}
+      <view className="profile-header">
+        <image className="avatar" src={user.avatar} />
+        <text className="name">{user.name}</text>
+        <text className="email">{user.email}</text>
+        <button className="edit-btn" onClick={handleEdit}>
+          编辑资料
+        </button>
+      </view>
+
+      {/* 数据统计 */}
+      <view className="profile-stats">
+        <view className="stat-item">
+          <text className="stat-value">{user.stats.posts}</text>
+          <text className="stat-label">帖子</text>
+        </view>
+        <view className="stat-item">
+          <text className="stat-value">{user.stats.followers}</text>
+          <text className="stat-label">关注者</text>
+        </view>
+        <view className="stat-item">
+          <text className="stat-value">{user.stats.following}</text>
+          <text className="stat-label">关注中</text>
+        </view>
+      </view>
+    </view>
+  );
+}
+
+export default definePage({
+  aiMeta: {
+    id: 'user-profile',
+    title: '用户资料',
+    description: '显示用户个人信息和统计数据'
+  },
+  onShow() {
+    console.log('页面显示');
+  },
+  onHide() {
+    console.log('页面隐藏');
+  },
+  render() {
+    return <UserProfilePage />;
+  }
+});
+```
+
+### index.scss
+
+```scss
+.profile-container {
+  padding: 32px;
+  background-color: #f5f5f5;
+
+  .loading,
+  .error {
+    text-align: center;
+    padding: 40px;
+    font-size: 28px;
+    color: #666;
+  }
+
+  .profile-header {
+    background-color: #fff;
+    border-radius: 16px;
+    padding: 40px;
+    text-align: center;
+    margin-bottom: 32px;
+
+    .avatar {
+      width: 160px;
+      height: 160px;
+      border-radius: 80px;
+      margin-bottom: 24px;
+    }
+
+    .name {
+      font-size: 36px;
+      font-weight: bold;
+      color: #333;
+      margin-bottom: 12px;
+    }
+
+    .email {
+      font-size: 28px;
+      color: #666;
+      margin-bottom: 24px;
+    }
+
+    .edit-btn {
+      padding: 16px 48px;
+      background-color: #1890ff;
+      color: #fff;
+      border-radius: 8px;
+      font-size: 28px;
+    }
+  }
+
+  .profile-stats {
+    display: flex;
+    justify-content: space-around;
+    background-color: #fff;
+    border-radius: 16px;
+    padding: 32px;
+
+    .stat-item {
+      text-align: center;
+
+      .stat-value {
+        font-size: 36px;
+        font-weight: bold;
+        color: #333;
+        margin-bottom: 8px;
+      }
+
+      .stat-label {
+        font-size: 24px;
+        color: #999;
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🎴 Widget 基础示例
+
+### 天气卡片
+
+**文件结构**：
+```
+src/widgets/weather-card/
+├── index.tsx       # 组件逻辑
+└── index.scss      # 组件样式
+```
+
+### index.tsx
+
+```tsx
+import { defineWidget, getViewData, useState, useEffect } from '@doubao-apps/framework';
+import './index.scss';
+
+interface WeatherData {
+  city: string;
+  temperature: number;
+  condition: string;
+  humidity: number;
+  windSpeed: number;
+  icon: string;
+}
+
+interface WeatherWidgetInput {
+  city: string;
+}
+
+function WeatherCard({ city }: WeatherWidgetInput) {
+  const [weather, setWeather] = useState<WeatherData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // 获取天气数据
+  const fetchWeather = async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      // 模拟 API 请求
+      await new Promise(resolve => setTimeout(resolve, 800));
+
+      const mockData: WeatherData = {
+        city: city,
+        temperature: 22,
+        condition: '晴天',
+        humidity: 65,
+        windSpeed: 12,
+        icon: '☀️'
+      };
+
+      setWeather(mockData);
+    } catch (err) {
+      setError('获取天气失败');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchWeather();
+  }, [city]);
+
+  // 刷新按钮
+  const handleRefresh = () => {
+    fetchWeather();
+  };
+
+  // 渲染
+  if (loading) {
+    return (
+      <view className="weather-card">
+        <text className="loading">加载中...</text>
+      </view>
+    );
+  }
+
+  if (error || !weather) {
+    return (
+      <view className="weather-card">
+        <text className="error">{error || '暂无数据'}</text>
+        <button onClick={handleRefresh}>重试</button>
+      </view>
+    );
+  }
+
+  return (
+    <view className="weather-card">
+      {/* 头部 */}
+      <view className="weather-header">
+        <text className="city">{weather.city}</text>
+        <button className="refresh-btn" onClick={handleRefresh}>
+          刷新
+        </button>
+      </view>
+
+      {/* 主要信息 */}
+      <view className="weather-main">
+        <text className="icon">{weather.icon}</text>
+        <view className="temperature-section">
+          <text className="temperature">{weather.temperature}°C</text>
+          <text className="condition">{weather.condition}</text>
+        </view>
+      </view>
+
+      {/* 详细信息 */}
+      <view className="weather-details">
+        <view className="detail-item">
+          <text className="detail-label">湿度</text>
+          <text className="detail-value">{weather.humidity}%</text>
+        </view>
+        <view className="detail-item">
+          <text className="detail-label">风速</text>
+          <text className="detail-value">{weather.windSpeed} km/h</text>
+        </view>
+      </view>
+    </view>
+  );
+}
+
+export default defineWidget({
+  onMounted() {
+    console.log('卡片挂载');
+  },
+  onDestroy() {
+    console.log('卡片销毁');
+  },
+  render() {
+    const input = getViewData<WeatherWidgetInput>();
+    return <WeatherCard city={input.city} />;
+  }
+});
+```
+
+### index.scss
+
+```scss
+.weather-card {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  border-radius: 16px;
+  padding: 32px;
+  color: #fff;
+
+  .loading,
+  .error {
+    text-align: center;
+    padding: 32px;
+    font-size: 28px;
+  }
+
+  .weather-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 32px;
+
+    .city {
+      font-size: 32px;
+      font-weight: bold;
+    }
+
+    .refresh-btn {
+      padding: 12px 24px;
+      background-color: rgba(255, 255, 255, 0.2);
+      color: #fff;
+      border-radius: 8px;
+      font-size: 24px;
+    }
+  }
+
+  .weather-main {
+    display: flex;
+    align-items: center;
+    margin-bottom: 32px;
+
+    .icon {
+      font-size: 120px;
+      margin-right: 32px;
+    }
+
+    .temperature-section {
+      .temperature {
+        font-size: 72px;
+        font-weight: bold;
+        margin-bottom: 8px;
+      }
+
+      .condition {
+        font-size: 28px;
+        opacity: 0.9;
+      }
+    }
+  }
+
+  .weather-details {
+    display: flex;
+    justify-content: space-around;
+    padding-top: 24px;
+    border-top: 1px solid rgba(255, 255, 255, 0.3);
+
+    .detail-item {
+      text-align: center;
+
+      .detail-label {
+        font-size: 24px;
+        opacity: 0.8;
+        margin-bottom: 8px;
+      }
+
+      .detail-value {
+        font-size: 32px;
+        font-weight: bold;
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🔑 关键要点
+
+### Page 开发要点
+
+1. **完整的页面生命周期**
+   - `onShow()` - 页面显示时调用
+   - `onHide()` - 页面隐藏时调用
+   - `onDestroy()` - 页面销毁时调用
+
+2. **页面配置 (aiMeta)**
+   - `id` - 页面唯一标识
+   - `title` - 页面标题
+   - `description` - 页面描述
+
+3. **状态管理**
+   - 使用 React Hooks（useState, useEffect）
+   - 处理加载、错误、数据状态
+
+4. **用户交互**
+   - 按钮点击、表单提交
+   - 页面跳转、数据更新
+
+### Widget 开发要点
+
+1. **卡片生命周期**
+   - `onShow()` / `onHide()` - 卡片显示/隐藏
+   - `onForeground()` / `onBackground()` - 应用前后台切换
+   - `onMounted()` / `onDestroy()` - 挂载/销毁
+
+2. **输入数据定义 (input schema)**
+   - 使用 JSON Schema 定义输入格式
+   - AI 根据 schema 生成结构化数据
+   - 必须字段使用 `required` 数组
+
+3. **卡片类型 (boxType)**
+   - `inbox` - 普通卡片
+   - `full_box` - 全宽卡片
+
+4. **消息交互**
+   - 接收 AI 传入的数据
+   - 可以发送消息回 Bot
+   - 支持卡片内交互
+
+---
+
+## 📚 延伸阅读
+
+- **组件开发完整指南** → [../guides/component-development.md](../guides/component-development.md)
+- **常用开发模式** → [./common-patterns.md](./common-patterns.md)
+- **API 参考** → [../reference/framework-api-quick-ref.md](../reference/framework-api-quick-ref.md)