@doubao-apps/create 0.0.33 → 0.0.34

package/dist/template-empty/references/rules/dos-and-donts.md

@@ -1,467 +0,0 @@
-# 开发规则 - Do's and Don'ts
-
-Doubao Apps SDK 框架的开发规则和最佳实践。
-
----
-
-## ✅ 推荐做法（Do's）
-
-### 项目管理
-
-#### ✅ 使用 pnpm 包管理器
-```bash
-# 推荐
-pnpm install
-pnpm add @doubao-apps/framework
-
-# 不推荐（除非项目已使用 npm）
-npm install
-npm install @doubao-apps/framework
-```
-
-
-### 组件开发
-
-#### ✅ 在 app.config.ts 配置 App 元信息
-```ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用'
-});
-```
-
-#### ✅ 需要稳定首页时在 app.config.ts 明确入口
-```ts
-// ✅ pages 数组第一项会作为首页（appletEntry）
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: [
-    {
-      entry: 'pages/home/index',
-      id: 'home',
-      title: '首页',
-      description: '应用默认打开的页面'
-    }
-  ]
-});
-```
-
-一级页面目录不写进 `pages` 也会自动发现；如果首页不是历史默认的 `index`，或需要固定首页顺序，建议显式配置 `pages`
-数组第一项。
-
-#### ✅ 需要补充展示信息时在 app.config.ts 定义 metadata
-```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: '展示和编辑用户个人资料'
-    }
-  ]
-});
-```
-
-```ts
-// ❌ 不好的做法：缺少 title、description 等信息
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: [
-    {
-      entry: 'pages/user-profile/index',
-      id: 'page1'
-    }
-  ]
-});
-```
-
-#### ✅ 多级目录必须显式声明 entry
-```ts
-// src/pages/account/demo/index.tsx
-// src/widgets/order/detail/index.tsx
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  pages: [
-    // 只声明入口、不补 metadata 时，可以直接写字符串
-    'pages/account/demo/index',
-    {
-      entry: 'pages/account/settings/index',
-      id: 'account-settings',
-      title: '账号设置页'
-    }
-  ],
-  widgets: [
-    'widgets/order/detail/index',
-    {
-      entry: 'widgets/order/summary/index',
-      id: 'order-summary',
-      name: '订单摘要卡片'
-    }
-  ]
-});
-```
-
-如果不配置 `id`，默认取入口最后一级目录名：`pages/account/demo/index` 默认为 `demo`，`widgets/order/detail/index`
-默认为 `detail`。
-
-#### ✅ 分离样式文件
-```tsx
-// ✅ 好的做法
-// index.tsx
-import './index.scss';
-
-export default definePage({
-  // ...
-});
-```
-
-```scss
-// index.scss
-.container {
-  padding: 16px;
-  background: #fff;
-}
-```
-
-```tsx
-// ❌ 不好的做法
-export default definePage({
-  render() {
-    return (
-      <view style={{ padding: '16px', background: '#fff' }}>
-        内容
-      </view>
-    );
-  }
-});
-```
-
-#### ✅ 使用 TypeScript 类型定义
-```tsx
-// ✅ 好的做法
-interface UserInfo {
-  name: string;
-  age: number;
-  avatar?: string;
-}
-
-export default defineWidget({
-  render() {
-    const viewData = getViewData<UserInfo>();
-    return <view>{viewData.name}</view>;
-  }
-});
-```
-
-```ts
-// ✅ 把 metadata 写到 src/app.config.ts
-import { defineAppConfig } from '@doubao-apps/kit';
-
-export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
-  name: '我的豆包应用',
-  widgets: [
-    {
-      entry: 'widgets/user-card/index',
-      id: 'user-card',
-      name: '用户卡片',
-      description: '用户信息卡片'
-    }
-  ]
-});
-```
-
-```tsx
-// ❌ 不好的做法
-export default defineWidget({
-  render() {
-    const viewData = getViewData<any>();  // 使用 any 类型，失去类型检查
-    return <view>{viewData.name}</view>;
-  }
-});
-```
-
-#### ✅ 使用生命周期钩子
-```tsx
-// ✅ 好的做法
-export default definePage({
-  onShow() {
-    console.log('Page shown');
-  },
-
-  onHide() {
-    console.log('Page hidden');
-  },
-
-  onDestroy() {
-    console.log('Page destroyed');
-  },
-
-  render() {
-    return <view>内容</view>;
-  }
-});
-```
-
-
-#### ✅ 错误处理和边界情况
-```tsx
-// ✅ 好的做法
-export default defineWidget({
-  render() {
-    const viewData = getViewData<{ items: string[] }>();
-    // 处理空数据
-    if (!viewData.items || viewData.items.length === 0) {
-      return <view>暂无数据</view>;
-    }
-
-    return (
-      <view>
-        {viewData.items.map((item, index) => (
-          <view key={index}>{item}</view>
-        ))}
-      </view>
-    );
-  }
-});
-```
-
-```tsx
-// ❌ 不好的做法
-export default defineWidget({
-  render() {
-    const viewData = getViewData<any>();
-    // 没有检查 viewData.items 是否存在
-    return (
-      <view>
-        {viewData.items.map(item => <view>{item}</view>)}
-      </view>
-    );
-  }
-});
-```
-
-
-
-## ❌ 禁止做法（Don'ts）
-
-### 样式相关
-
-#### ❌ 内联样式长度值必须带单位
-
-Lynx CSS encoder 要求：**所有 CSS 长度值必须显式带单位**，裸数字（无单位）会触发运行时错误 `CSS length need units (except 0)`。
-
-```tsx
-// ❌ 错误：裸数字（无单位）
-<view style={{ width: 100, height: 56, fontSize: 14 }} />
-
-// ✅ 正确：带单位字符串
-<view style={{ width: '100px', height: '56px', fontSize: '14px' }} />
-
-// ✅ 例外：以下属性可以使用裸数字（无单位）
-// flex, opacity, zIndex, fontWeight, aspectRatio
-<view style={{ flex: 1, opacity: 0.5, zIndex: 10 }} />
-```
-
-#### ❌ 不写内联样式
-```tsx
-// ❌ 错误
-export default definePage({
-  render() {
-    return (
-      <view style={{ padding: 16, background: '#fff' }}>
-        内容
-      </view>
-    );
-  }
-});
-```
-
-```tsx
-// ✅ 正确
-import './index.scss';
-
-export default definePage({
-  render() {
-    return (
-      <view className="container">
-        内容
-      </view>
-    );
-  }
-});
-```
-
-### 异步操作
-
-#### ❌ 不在 render 中发起请求
-```tsx
-// ❌ 错误 - 每次渲染都会发请求
-export default definePage({
-  render() {
-    fetch('/api/data').then(data => {
-      // 处理数据
-    });
-
-    return <view>内容</view>;
-  }
-});
-```
-
-```tsx
-// ✅ 推荐 - 使用 Hook 管理请求和状态
-import { useEffect, useState } from '@doubao-apps/framework';
-
-function UserPage() {
-  const [userData, setUserData] = useState<{ name?: string } | null>(null);
-
-  useEffect(() => {
-    fetch('/api/data')
-      .then(res => res.json())
-      .then(data => {
-        setUserData(data);
-      });
-  }, []);
-
-  return <view>{userData?.name}</view>;
-}
-
-export default definePage({
-  render() {
-    return <UserPage />;
-  }
-});
-```
-
-### 组件结构
-
-#### ❌ 不过度嵌套组件
-```tsx
-// ❌ 错误 - 过度嵌套
-export default definePage({
-  render() {
-    return (
-      <view>
-        <view>
-          <view>
-            <view>
-              <view>
-                <view>
-                  内容
-                </view>
-              </view>
-            </view>
-          </view>
-        </view>
-      </view>
-    );
-  }
-});
-```
-
-```tsx
-// ✅ 正确 - 扁平结构
-export default definePage({
-  render() {
-    return (
-      <view className="page">
-        <view className="header">头部</view>
-        <view className="content">内容</view>
-        <view className="footer">底部</view>
-      </view>
-    );
-  }
-});
-```
-
-### 类型使用
-
-#### ❌ 不忽略 TypeScript 类型
-```tsx
-// ❌ 错误
-export default defineWidget({
-  render() {
-    const viewData = getViewData<any>();
-    // @ts-ignore
-    return <view>{viewData.unknownProperty}</view>;
-  }
-});
-```
-
-```tsx
-// ✅ 正确
-interface UserInfo {
-  name: string;
-  age: number;
-}
-
-export default defineWidget({
-  render() {
-    const viewData = getViewData<UserInfo>();
-    return <view>{viewData.name}</view>;
-  }
-});
-```
-
-### 状态管理
-
-#### ❌ 不在全局作用域定义状态
-```tsx
-// ❌ 错误 - 全局变量会在多个实例间共享
-let count = 0;
-
-export default defineWidget({
-  render() {
-    count++;  // 所有实例共享这个 count
-    return <view>Count: {count}</view>;
-  }
-});
-```
-
-```tsx
-// ✅ 推荐 - 使用组件内状态，实例之间互不影响
-import { useState } from '@doubao-apps/framework';
-
-function CounterWidget() {
-  const [count, setCount] = useState(0);
-
-  return (
-    <view
-      onClick={() => {
-        setCount(prev => prev + 1);
-      }}
-    >
-      Count: {count}
-    </view>
-  );
-}
-
-export default defineWidget({
-  render() {
-    return <CounterWidget />;
-  }
-});
-```
-
-## 📚 相关文档
-
-- [组件开发指南](../guides/component-development.md)
-- [最佳实践](../guides/best-practices.md)
-- [性能优化](../guides/performance-optimization.md)