@doubao-apps/create 0.0.33 → 0.0.34

package/dist/template-starter/references/examples/component-basics.md

@@ -1,526 +0,0 @@
-# 组件基础示例
-
-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      # 组件样式
-```
-
-### app.config.ts
-
-`app.config.ts` 需要配置 `appId` 和 `name`。这里额外配置 `pages` 是为了补充标题和描述，并确保
-`user-profile` 作为页面 ID 使用。
-
-```ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: [
-    {
-      entry: 'pages/user-profile/index',
-      id: 'user-profile',
-      title: '用户资料',
-      description: '显示用户个人信息和统计数据'
-    }
-  ]
-});
-```
-
-### 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({
-  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 WeatherWidgetData {
-  city: string;
-}
-
-function WeatherCard({ city }: WeatherWidgetData) {
-  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 viewData = getViewData<WeatherWidgetData>();
-    return <WeatherCard city={viewData.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. **页面配置（可选 pages）**
-   - 一级目录不写进 `pages` 也会自动发现，默认 `id` 是目录名
-   - 需要 `title`、`description`、固定首页或多级目录时再配置
-   - 多级目录需要显式写 `entry`
-
-3. **状态管理**
-   - 使用 React Hooks（useState, useEffect）
-   - 处理加载、错误、数据状态
-
-4. **用户交互**
-   - 按钮点击、表单提交
-   - 页面跳转、数据更新
-
-### Widget 开发要点
-
-1. **卡片生命周期**
-   - `onShow()` / `onHide()` - 卡片显示/隐藏
-   - `onForeground()` / `onBackground()` - 应用前后台切换
-   - `onMounted()` / `onDestroy()` - 挂载/销毁
-
-2. **ViewData 定义**
-   - 使用 TypeScript 类型定义 `getViewData<T>()` 的 viewData 结构
-   - 对可选字段和空数据做兜底处理
-   - 避免直接使用 `any`
-
-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)