@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/contexts/doubao-apps-dev/references/guides/performance-optimization.md

@@ -1,402 +0,0 @@
-# 性能优化
-
-Doubao Apps SDK 应用的性能优化指南和最佳实践。
-
----
-
-## ⚡ 渲染性能优化
-
-### 1. 避免不必要的渲染
-
-#### 使用 useMemo 缓存计算结果
-
-```tsx
-// ✅ 好的做法 - 缓存昂贵的计算
-function DataList({ items, filter }: Props) {
-  // 只在 items 或 filter 改变时重新计算
-  const filteredAndSorted = useMemo(() => {
-    console.log('Computing filtered list...');
-    return items
-      .filter(item => item.type === filter)
-      .sort((a, b) => b.score - a.score);
-  }, [items, filter]);
-
-  return (
-    <list>
-      {filteredAndSorted.map(item => (
-        <ItemCard key={item.id} {...item} />
-      ))}
-    </list>
-  );
-}
-
-// ❌ 不好的做法 - 每次渲染都重新计算
-function DataList({ items, filter }: Props) {
-  // 每次组件渲染都会执行
-  const filteredAndSorted = items
-    .filter(item => item.type === filter)
-    .sort((a, b) => b.score - a.score);
-
-  return <list>{/* ... */}</list>;
-}
-```
-
-#### 使用 useCallback 稳定函数引用
-
-```tsx
-// ✅ 好的做法 - 稳定的回调函数
-function ParentComponent({ items }: Props) {
-  const [selectedId, setSelectedId] = useState<string | null>(null);
-
-  // 函数引用保持稳定，子组件不会因此重新渲染
-  const handleSelect = useCallback((id: string) => {
-    setSelectedId(id);
-    console.log('Selected:', id);
-  }, []);
-
-  return (
-    <view>
-      {items.map(item => (
-        <ItemCard
-          key={item.id}
-          item={item}
-          onSelect={handleSelect}  // 函数引用不变
-        />
-      ))}
-    </view>
-  );
-}
-
-// ❌ 不好的做法 - 每次渲染创建新函数
-function ParentComponent({ items }: Props) {
-  const [selectedId, setSelectedId] = useState<string | null>(null);
-
-  return (
-    <view>
-      {items.map(item => (
-        <ItemCard
-          key={item.id}
-          item={item}
-          onSelect={(id) => setSelectedId(id)}  // 每次创建新函数
-        />
-      ))}
-    </view>
-  );
-}
-```
-
-### 2. 列表渲染优化
-
-#### 虚拟列表
-
-```tsx
-// ✅ 好的做法 - 使用 Lynx list 组件的虚拟滚动
-function VirtualList({ items }: { items: Item[] }) {
-  return (
-    <list
-      className="virtual-list"
-      list-type="single"
-      span-count={1}
-      scroll-orientation="vertical"
-      enable-nested-scroll={true}
-      // Lynx 会自动复用不可见的列表项
-    >
-      {items.map(item => (
-        <list-item key={item.id} item-key={item.id}>
-          <ItemCard item={item} />
-        </list-item>
-      ))}
-    </list>
-  );
-}
-
-// ❌ 不好的做法 - 渲染所有项
-function AllItemsList({ items }: { items: Item[] }) {
-  // 如果有 1000+ 项，会严重影响性能
-  return (
-    <scroll-view>
-      {items.map(item => (
-        <ItemCard key={item.id} item={item} />
-      ))}
-    </scroll-view>
-  );
-}
-```
-
-#### 分页加载
-
-```tsx
-// ✅ 好的做法 - 分页加载大量数据
-function InfiniteList() {
-  const [items, setItems] = useState<Item[]>([]);
-  const [page, setPage] = useState(1);
-  const [hasMore, setHasMore] = useState(true);
-  const [loading, setLoading] = useState(false);
-
-  const loadMore = async () => {
-    if (loading || !hasMore) return;
-
-    setLoading(true);
-    try {
-      const newItems = await fetchItems(page, 20);
-      setItems(prev => [...prev, ...newItems]);
-      setPage(prev => prev + 1);
-      setHasMore(newItems.length === 20);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <list onScrollToLower={loadMore}>
-      {items.map(item => (
-        <list-item key={item.id}>
-          <ItemCard item={item} />
-        </list-item>
-      ))}
-      {loading && <LoadingIndicator />}
-    </list>
-  );
-}
-```
-
-### 3. 图片优化
-
-#### 懒加载
-
-```tsx
-// ✅ 好的做法 - 图片懒加载
-function LazyImage({ src, placeholder }: Props) {
-  const [loaded, setLoaded] = useState(false);
-
-  return (
-    <view className="lazy-image">
-      {!loaded && <image src={placeholder} className="lazy-image__placeholder" />}
-      <image
-        src={src}
-        className="lazy-image__actual"
-        style={{ display: loaded ? 'block' : 'none' }}
-        onLoad={() => setLoaded(true)}
-        onError={() => console.error('Failed to load image')}
-      />
-    </view>
-  );
-}
-```
-
-#### 图片尺寸优化
-
-```tsx
-// ✅ 好的做法 - 使用合适尺寸的图片
-interface ImageProps {
-  src: string;
-  size: 'thumbnail' | 'medium' | 'large';
-}
-
-function OptimizedImage({ src, size }: ImageProps) {
-  const sizeParams = {
-    thumbnail: '?w=200&h=200&q=80',
-    medium: '?w=600&h=600&q=85',
-    large: '?w=1200&h=1200&q=90'
-  };
-
-  return <image src={`${src}${sizeParams[size]}`} />;
-}
-
-// ❌ 不好的做法 - 加载原图后缩小
-function UnoptimizedImage({ src }: Props) {
-  // 加载 5MB 的原图，然后显示为 100x100
-  return <image src={src} style={{ width: '100rpx', height: '100rpx' }} />;
-}
-```
-
----
-
-## 🧠 内存优化
-
-### 1. 及时清理资源
-
-```tsx
-// ✅ 好的做法 - 清理定时器和订阅
-function TimerComponent() {
-  const [count, setCount] = useState(0);
-  const timerRef = useRef<any>(null);
-
-  useEffect(() => {
-    // 创建定时器
-    timerRef.current = setInterval(() => {
-      setCount(c => c + 1);
-    }, 1000);
-
-    // 清理函数
-    return () => {
-      if (timerRef.current) {
-        clearInterval(timerRef.current);
-        timerRef.current = null;
-      }
-    };
-  }, []);
-
-  return <text>Count: {count}</text>;
-}
-
-// ❌ 不好的做法 - 忘记清理
-function TimerComponent() {
-  const [count, setCount] = useState(0);
-
-  useEffect(() => {
-    setInterval(() => {
-      setCount(c => c + 1);
-    }, 1000);
-    // 没有清理！组件卸载后定时器仍在运行
-  }, []);
-
-  return <text>Count: {count}</text>;
-}
-```
-
-### 2. 避免内存泄漏
-
-```tsx
-// ✅ 好的做法 - 检查组件是否已卸载
-function DataFetcher() {
-  const [data, setData] = useState(null);
-  const mountedRef = useRef(true);
-
-  useEffect(() => {
-    const fetchData = async () => {
-      try {
-        const result = await api.getData();
-        // 只在组件仍挂载时更新状态
-        if (mountedRef.current) {
-          setData(result);
-        }
-      } catch (error) {
-        console.error(error);
-      }
-    };
-
-    fetchData();
-
-    return () => {
-      mountedRef.current = false;
-    };
-  }, []);
-
-  return <view>{/* render data */}</view>;
-}
-```
-
-### 3. 大数据处理
-
-```tsx
-// ✅ 好的做法 - 分批处理大数据
-async function processBigData(data: any[]) {
-  const BATCH_SIZE = 100;
-  const results = [];
-
-  for (let i = 0; i < data.length; i += BATCH_SIZE) {
-    const batch = data.slice(i, i + BATCH_SIZE);
-    const processed = await processBatch(batch);
-    results.push(...processed);
-
-    // 让出主线程，避免阻塞 UI
-    await new Promise(resolve => setTimeout(resolve, 0));
-  }
-
-  return results;
-}
-
-// ❌ 不好的做法 - 一次性处理所有数据
-async function processBigData(data: any[]) {
-  // 如果数据量大，会阻塞 UI
-  return data.map(item => expensiveOperation(item));
-}
-```
-
----
-
-## 📦 包体积优化
-
-### 1. 代码分割
-
-```tsx
-// ✅ 好的做法 - 动态导入大组件
-function HeavyFeature() {
-  const [Component, setComponent] = useState<any>(null);
-
-  useEffect(() => {
-    // 只在需要时加载
-    import('./HeavyComponent').then(module => {
-      setComponent(() => module.default);
-    });
-  }, []);
-
-  if (!Component) {
-    return <LoadingSpinner />;
-  }
-
-  return <Component />;
-}
-```
-
-
-## 📱 启动性能优化
-
-### 1. 延迟非关键代码
-
-```tsx
-// ✅ 好的做法 - 优先渲染关键内容
-export default definePage({
-  onShow() {
-    // 先显示页面骨架
-    this.showSkeleton = true;
-
-    // 延迟加载非关键数据
-    setTimeout(() => {
-      this.loadAnalytics();
-      this.loadRecommendations();
-    }, 1000);
-
-    // 优先加载关键数据
-    this.loadMainContent();
-  },
-
-  render() {
-    return this.showSkeleton ? <Skeleton /> : <Content />;
-  }
-});
-```
-
-### 2. 预加载关键资源
-
-```tsx
-// ✅ 好的做法 - 预加载下一页可能需要的数据
-function ListPage({ items }: Props) {
-  const [nextPageData, setNextPageData] = useState<Item[]>([]);
-
-  useEffect(() => {
-    // 预加载下一页数据
-    const prefetchNextPage = async () => {
-      try {
-        const data = await fetchItems(2);
-        setNextPageData(data);
-      } catch (error) {
-        console.error('Prefetch failed:', error);
-      }
-    };
-
-    // 在用户可能操作前预加载
-    const timer = setTimeout(prefetchNextPage, 2000);
-    return () => clearTimeout(timer);
-  }, []);
-
-  return <ItemList items={items} />;
-}
-```
-
-## 🔗 相关文档
-
-- [最佳实践](./best-practices.md) - 代码规范
-- [组件开发完整指南](./component-development.md) - Page 和 Widget 开发
-- [故障排查](./troubleshooting.md) - 常见问题

package/dist/contexts/doubao-apps-dev/references/guides/troubleshooting.md

@@ -1,287 +0,0 @@
-# 故障排查指南
-
-Doubao Apps SDK 开发中常见问题的诊断和解决方案。 迭代过程中的新问题建议随时添加到该文档，方便团队内共享
-
----
-
-## 🔍 问题诊断流程
-
-### 系统化排查步骤
-
-1. **复现问题** - 确定问题的触发条件
-2. **查看日志** - 检查控制台错误信息
-3. **隔离问题** - 缩小问题范围
-4. **查找文档** - 搜索相关文档和示例
-5. **尝试方案** - 逐一测试可能的解决方案
-
----
-
-## 🐛 常见错误类型
-
-### 1. 组件渲染错误
-
-#### 问题：页面白屏或组件不显示
-
-**症状**：
-```
-页面显示空白，控制台无错误
-或者提示：Cannot read property 'xxx' of undefined
-```
-
-**可能原因**：
-- 数据未加载完成就尝试渲染
-- 必需的 props 未传递
-- 条件渲染逻辑错误
-
-**解决方案**：
-
-```tsx
-// ❌ 错误写法
-function UserProfile({ user }: Props) {
-  return (
-    <view>
-      <text>{user.name}</text>  {/* user 可能为 null */}
-    </view>
-  );
-}
-
-// ✅ 正确写法 - 添加安全检查
-function UserProfile({ user }: Props) {
-  if (!user) {
-    return <LoadingView />;
-  }
-
-  return (
-    <view>
-      <text>{user.name}</text>
-    </view>
-  );
-}
-
-// ✅ 或使用可选链
-function UserProfile({ user }: Props) {
-  return (
-    <view>
-      <text>{user?.name || '未知用户'}</text>
-    </view>
-  );
-}
-```
-
-#### 问题：组件频繁重新渲染
-
-**症状**：
-```
-控制台大量渲染日志
-页面卡顿，性能下降
-```
-
-**诊断方法**：
-
-```tsx
-// 添加渲染追踪
-function MyComponent({ data }: Props) {
-  const renderCount = useRef(0);
-
-  useEffect(() => {
-    renderCount.current += 1;
-    console.log(`Render count: ${renderCount.current}`);
-  });
-
-  return <view>{/* ... */}</view>;
-}
-```
-
-**解决方案**：
-
-```tsx
-// ✅ 使用 useMemo 缓存计算
-const processedData = useMemo(() => {
-  return heavyComputation(data);
-}, [data]);
-
-// ✅ 使用 useCallback 稳定函数引用
-const handleClick = useCallback(() => {
-  console.log('clicked');
-}, []);
-```
-
-### 2. 生命周期问题
-
-#### 问题：onShow 未触发
-
-**可能原因**：
-- 没有正确定义生命周期方法
-- 页面未正确注册
-- 路由配置错误
-
-**解决方案**：
-
-```tsx
-// ❌ 错误写法 - 没有在正确位置定义
-export default definePage({
-  render() {
-    // ❌ 不能在这里定义
-    const onShow = () => {
-      console.log('show');
-    };
-
-    return <view>...</view>;
-  }
-});
-
-// ✅ 正确写法
-export default definePage({
-  onShow() {
-    console.log('Page shown');
-  },
-
-  onHide() {
-    console.log('Page hidden');
-  },
-
-  render() {
-    return <view>...</view>;
-  }
-});
-```
-
-#### 问题：内存泄漏 - 组件卸载后仍在更新状态
-
-**症状**：
-```
-Warning: Can't perform a React state update on an unmounted component
-```
-
-**解决方案**：
-
-```tsx
-// ✅ 使用 cleanup 函数
-function DataFetcher() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    let mounted = true;
-
-    const fetchData = async () => {
-      const result = await api.getData();
-      if (mounted) {  // 检查组件是否仍挂载
-        setData(result);
-      }
-    };
-
-    fetchData();
-
-    return () => {
-      mounted = false;  // cleanup
-    };
-  }, []);
-
-  return <view>{/* ... */}</view>;
-}
-
-// ✅ 清理定时器
-useEffect(() => {
-  const timer = setInterval(() => {
-    console.log('tick');
-  }, 1000);
-
-  return () => {
-    clearInterval(timer);  // cleanup
-  };
-}, []);
-```
-
-### 3. 样式问题
-
-#### 问题：样式不生效
-
-**可能原因**：
-- 样式文件未导入
-- 选择器权重不够
-- Lynx 不支持的 CSS 属性
-- rpx 单位使用错误
-
-**解决方案**：
-
-```tsx
-// ✅ 确保导入样式文件
-import './index.scss';  // 必须导入
-
-export default definePage({
-  // ...
-});
-```
-
-```scss
-// ✅ 检查选择器
-.my-component {
-  padding: 32rpx;  // ✅ 使用 rpx
-  color: #333;
-
-  &__title {
-    font-size: 36rpx;
-  }
-}
-
-// ❌ 避免使用不支持的属性
-.my-component {
-  position: sticky;  // ❌ Lynx 可能不支持
-  backdrop-filter: blur(10px);  // ❌ 不支持
-}
-```
-
-### 4. 数据请求问题
-
-#### 问题：接口调用失败
-
-**症状**：
-```
-Network Error
-Request failed with status 400/401/404/500
-```
-
-**诊断步骤**：
-
-```tsx
-// ✅ 添加详细的错误日志
-import { request } from '@doubao-apps/framework/api';
-
-async function fetchData() {
-  try {
-    const response = await request({
-      url: 'https://api.example.com/data',
-      method: 'GET'
-    });
-
-    console.log('Response status:', response.statusCode);
-    console.log('Response headers:', response.header);
-
-    if (response.statusCode >= 400) {
-      console.error('Error response:', response.data);
-      throw new Error(`HTTP ${response.statusCode}: ${JSON.stringify(response.data)}`);
-    }
-
-    return response.data;
-  } catch (error) {
-    console.error('Request error:', error);
-    throw error;
-  }
-}
-```
-
-
-
-## 🔧 常见解决方案速查
-
-### 快速修复方案
-
-| 问题 | 快速解决方案 |
-|-----|-------------|
-| 组件不显示 | 检查数据加载和空值处理 |
-| 样式不生效 | 确认导入样式文件 |
-| 内存泄漏 | 添加 cleanup 函数 |
-| 网络请求失败 | 检查 URL、参数和错误处理 |
-| 类型错误 | 添加可选链或类型守卫 |
-| 页面卡顿 | 使用虚拟列表和分页 |
-| 图片加载慢 | 使用懒加载和合适尺寸 |