@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/lynx/best-practices.md

@@ -0,0 +1,720 @@
+# Lynx 前端开发最佳实践
+
+## 性能优化
+
+### 布局性能
+
+#### 1. 选择合适的布局类型
+
+```css
+/* ✅ 简单列表使用 Linear（性能最好） */
+.simple-list {
+  /* 默认就是 linear，无需设置 display */
+  padding: 16px;
+}
+
+/* ✅ 复杂弹性布局使用 Flex */
+.complex-layout {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
+}
+
+/* ❌ 避免在简单场景使用 Flex */
+.simple-column {
+  display: flex;
+  flex-direction: column; /* 不如直接用 Linear */
+}
+```
+
+#### 2. 减少布局层级
+
+```jsx
+// ❌ 层级过多
+<view className="wrapper">
+  <view className="container">
+    <view className="inner">
+      <view className="content">
+        <text>内容</text>
+      </view>
+    </view>
+  </view>
+</view>
+
+// ✅ 扁平化结构
+<view className="content">
+  <text>内容</text>
+</view>
+```
+
+#### 3. 避免动态改变布局类型
+
+```jsx
+// ❌ 避免在运行时切换 display 类型
+const [isGrid, setIsGrid] = useState(false);
+
+<view style={{ display: isGrid ? 'grid' : 'flex' }}>
+  {/* 内容 */}
+</view>
+
+// ✅ 使用 opacity 或 transform 替代
+<view className="flex-container">
+  <view className="flex-view" style={{ opacity: isGrid ? 0 : 1 }} />
+  <view className="grid-view" style={{ opacity: isGrid ? 1 : 0 }} />
+</view>
+```
+
+### 样式计算优化
+
+#### 4. 使用 CSS 类而非内联样式
+
+```jsx
+// ❌ 内联样式每次渲染都重新计算
+<view style={{
+  width: 100,
+  height: 200,
+  backgroundColor: '#fff'
+}} />
+
+// ✅ CSS 类只解析一次
+<view className="card" />
+```
+
+```css
+.card {
+  width: 100px;
+  height: 200px;
+  background-color: #fff;
+}
+```
+
+#### 5. 避免复杂的 CSS 选择器
+
+```css
+/* ❌ 复杂选择器增加匹配开销 */
+.container > .wrapper .item:nth-child(2n + 1) .content {
+  color: red;
+}
+
+/* ✅ 使用简单类选择器 */
+.item-odd {
+  color: red;
+}
+```
+
+#### 6. GPU 加速优化
+
+```css
+/* ✅ 使用 transform 和 opacity 实现自动 GPU 加速 */
+.animated-element {
+  transition: transform 0.3s ease, opacity 0.3s ease;
+}
+
+/* ✅ 动画结束后无需手动清理，Lynx 自动管理 */
+```
+
+> **注意**：Lynx 会自动对 `transform` 和 `opacity` 属性启用 GPU 加速，无需手动声明。
+
+### 渲染优化
+
+#### 7. 图片优化
+
+```css
+/* ✅ 指定图片尺寸，避免布局抖动 */
+.product-image {
+  width: 200px;
+  height: 200px;
+  /* 或者只设置一边，保持比例 */
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+```jsx
+// ✅ 使用懒加载
+<list>
+  {items.map((item) => (
+    <list-item key={item.id}>
+      <image src={item.image} lazy-load={true} placeholder="placeholder.png" />
+    </list-item>
+  ))}
+</list>
+```
+
+#### 8. 列表优化
+
+```jsx
+// ✅ 使用 list 组件替代 scroll-view + 多个 view
+<list className="item-list" scroll-y>
+  {items.map((item) => (
+    <list-item key={item.id} item-key={item.id}>
+      <view className="item">
+        <text>{item.title}</text>
+      </view>
+    </list-item>
+  ))}
+</list>
+```
+
+```css
+/* ✅ 为 list-item 设置固定高度（如果可以） */
+list-item {
+  height: 80px;
+}
+```
+
+#### 9. 控制同时渲染的元素数量
+
+```jsx
+// ❌ 一次渲染太多元素
+{
+  items.map((item) => <HeavyComponent key={item.id} data={item} />);
+}
+
+// ✅ 分页或虚拟列表
+<list>
+  {visibleItems.map((item) => (
+    <list-item key={item.id}>
+      <HeavyComponent data={item} />
+    </list-item>
+  ))}
+</list>;
+```
+
+## 布局最佳实践
+
+### Flex 布局模式
+
+#### 10. 响应式布局
+
+```css
+/* 移动端/默认 */
+.container {
+  display: flex;
+  flex-direction: column;
+}
+
+/* 注意：Lynx 不支持 @media，请使用 JavaScript 动态调整或视口单位 */
+/* JavaScript: if (viewportWidth >= 768) { setLayout('row') } */
+```
+
+#### 11. 弹性项比例
+
+```css
+/* ✅ 使用 flex 简写 */
+.item {
+  flex: 1; /* flex-grow: 1, flex-shrink: 1, flex-basis: 0% */
+}
+
+.item-large {
+  flex: 2; /* 占据两倍空间 */
+}
+
+/* ❌ 不推荐单独设置 */
+.item {
+  flex-grow: 1;
+  flex-shrink: 1;
+  /* 缺少 flex-basis 可能导致意外行为 */
+}
+```
+
+#### 12. 间距处理
+
+```css
+/* ✅ 使用 gap 属性 */
+.grid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+}
+
+/* 传统方式（需要处理边距） */
+.grid-item {
+  width: calc(33.33% - 11px);
+  margin-right: 16px;
+  margin-bottom: 16px;
+}
+
+.grid-item:nth-child(3n) {
+  margin-right: 0;
+}
+```
+
+### Grid 布局模式
+
+**注意**：Lynx **不支持** `@media` 媒体查询。
+
+## 样式组织
+
+### CSS 架构
+
+#### 15. BEM 命名约定
+
+```css
+/* Block */
+.card {
+}
+
+/* Element */
+.card__title {
+}
+.card__content {
+}
+.card__button {
+}
+
+/* Modifier */
+.card--featured {
+}
+.card__button--primary {
+}
+.card__button--disabled {
+}
+```
+
+#### 16. CSS 变量（主题系统）
+
+完整的主题变量（颜色、间距、字体、圆角、阴影）及暗色主题切换示例见 `patterns/theming.md`。使用 CSS 变量管理主题有以下建议：
+
+- **命名规范**: `--category-property` 格式（如 `--color-primary`）
+- **分层定义**: 颜色、间距、字体分开定义
+- **语义化**: 使用 `--color-primary` 而非 `--color-red`
+- **默认值**: 提供 fallback: `var(--prop, default)`
+
+#### 17. 组件样式隔离
+
+```css
+/* 每个组件独立文件 */
+/* Button.css */
+.button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 12px 24px;
+}
+
+/* Card.css */
+.card {
+  display: flex;
+  flex-direction: column;
+  padding: 16px;
+}
+
+/* 避免全局污染 */
+/* ❌ 不推荐 */
+view {
+  box-sizing: border-box;
+}
+
+/* ✅ 使用类选择器 */
+.reset-box {
+  box-sizing: border-box;
+}
+```
+
+## 响应式设计
+
+### 适配策略
+
+#### 18. 使用 rem + vw 适配（推荐）
+
+> **推荐方案**：使用 `rem` 配合 `vw` 设置根字体大小，实现响应式适配。
+
+```css
+/* 在根元素设置基准字体大小 */
+page {
+  font-size: calc(100vw / 23.4375); /* 1rem = 16px @ 375px 宽度 */
+}
+
+/* 使用 rem 进行屏幕适配 */
+.container {
+  width: 100%; /* 全宽 */
+  padding: 2rem; /* 左右各 2rem ≈ 32px @ 375px */
+}
+
+.card {
+  width: 21.4rem; /* 约一半宽度，减去间距 */
+  margin-bottom: 1.5rem;
+}
+```
+
+**rpx 说明**：`rpx` 是 Lynx 特有单位，功能完整且自动适配屏幕宽度，但缺乏 Web 兼容性。使用 `rem` + `vw` 是更标准的跨平台响应式方案。
+
+#### 19. 安全区域适配
+
+```css
+/* iPhone 刘海屏适配 */
+.safe-area {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+}
+
+/* 底部固定按钮 */
+.fixed-bottom {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  padding-bottom: env(safe-area-inset-bottom);
+  background-color: #fff;
+}
+```
+
+#### 20. 字体适配
+
+⚠️ **注意**：Lynx **不支持** `@media`，请使用以下替代方案：
+
+**方案 1：使用 rem（推荐）**
+
+```css
+/* 在根元素设置基准字体大小 */
+page {
+  font-size: calc(100vw / 23.4375); /* 1rem = 16px @ 375px 宽度 */
+}
+
+/* 使用 rem 自动适配 */
+.title {
+  font-size: 1.125rem; /* 约 18px @ 375px 屏幕 */
+}
+
+.body {
+  font-size: 0.875rem; /* 约 14px @ 375px 屏幕 */
+}
+```
+
+**方案 2：使用 vw 直接设置**
+
+```css
+/* 直接使用 vw */
+.title {
+  font-size: 4.8vw; /* 约 18px @ 375px 屏幕 */
+}
+
+.body {
+  font-size: 3.73vw; /* 约 14px @ 375px 屏幕 */
+}
+```
+
+**方案 3：使用 JavaScript 动态调整**
+
+```javascript
+// 根据屏幕宽度动态计算字体大小
+const baseFontSize = viewportWidth >= 768 ? 18 : 16;
+// 设置根元素字体大小
+```
+
+## 动画与过渡
+
+### 性能优先的动画
+
+#### 21. 使用 transform 和 opacity
+
+```css
+/* ✅ 性能友好的属性 */
+.animated {
+  transition: transform 0.3s ease, opacity 0.3s ease;
+}
+
+.animated:hover {
+  transform: scale(1.1);
+  opacity: 0.8;
+}
+
+/* ❌ 避免动画这些属性 */
+.animated-bad {
+  transition: width 0.3s, height 0.3s, margin 0.3s;
+}
+```
+
+#### 22. 硬件加速
+
+```css
+/* 启用 GPU 加速 */
+.gpu-accelerated {
+  transform: translateZ(0);
+  /* 或 */
+  transform: translate3d(0, 0, 0);
+}
+```
+
+#### 23. 关键帧动画
+
+```css
+@keyframes slideIn {
+  from {
+    transform: translateX(100%);
+    opacity: 0;
+  }
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
+}
+
+.slide-in {
+  animation: slideIn 0.3s ease-out;
+}
+```
+
+## 可访问性
+
+#### 24. 足够的触摸目标
+
+```css
+/* ✅ 最小 44x44 触摸区域 */
+.button {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 12px 24px;
+}
+```
+
+#### 25. 颜色对比度
+
+```css
+/* ✅ 确保足够的对比度 */
+.text-primary {
+  color: #333333; /* 在白色背景上对比度 12.6:1 */
+}
+
+.text-secondary {
+  color: #666666; /* 对比度 5.7:1 */
+}
+
+/* ❌ 对比度不足 */
+.text-weak {
+  color: #cccccc; /* 对比度 1.9:1，难以阅读 */
+}
+```
+
+## 调试技巧
+
+调试用的 CSS 代码片段请参考 `quick-reference.md`。
+
+#### 27. 性能监控
+
+```jsx
+// 测量渲染性能
+import { useEffect, useRef } from '@lynx-js/react';
+
+function PerformanceMonitor({ children }) {
+  const startTime = useRef(performance.now());
+
+  useEffect(() => {
+    const endTime = performance.now();
+    console.log(`Render time: ${endTime - startTime.current}ms`);
+  });
+
+  return children;
+}
+```
+
+## 常见陷阱与解决方案
+
+### 陷阱 1：Text 不换行
+
+```css
+/* 问题：Text 默认不换行 */
+text {
+  /* 默认 white-space: nowrap */
+}
+
+/* 解决 */
+text {
+  white-space: normal;
+  /* 或 */
+  max-width: 200px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  overflow: hidden;
+}
+```
+
+### 陷阱 2：图片不显示
+
+```css
+/* 问题：Image 必须设置尺寸 */
+image {
+  /* 没有尺寸不会显示 */
+}
+
+/* 解决 */
+image {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 16 / 9;
+  /* 或固定尺寸 */
+  width: 200px;
+  height: 200px;
+}
+```
+
+### 陷阱 3：Flex 子元素被压缩
+
+```css
+/* 问题：子元素被压缩到 0 */
+.flex-container {
+  display: flex;
+}
+
+.flex-item {
+  /* 可能被压缩 */
+}
+
+/* 解决 */
+.flex-item {
+  flex-shrink: 0; /* 不压缩 */
+  /* 或 */
+  min-width: 0; /* 允许压缩 */
+  overflow: hidden; /* 配合 ellipsis */
+}
+```
+
+### 陷阱 3 补充：内容项在 Lynx 和 Web 的主轴收缩下限不同
+
+```css
+/* row 方向宽度不足，或 column 方向高度不足时，Lynx 可能继续压缩内容项 */
+.row {
+  display: flex;
+  width: 80px;
+}
+
+.row .content-item {
+  width: 120px;
+  flex-shrink: 1;
+}
+
+.column {
+  display: flex;
+  flex-direction: column;
+  height: 80px;
+}
+
+.column .content-item {
+  height: 120px;
+  flex-shrink: 1;
+}
+```
+
+```css
+/* Web 预览页：取消主轴方向自动最小尺寸，贴近 Lynx 表现 */
+.row .content-item {
+  min-width: 0;
+}
+
+.column .content-item {
+  min-height: 0;
+}
+
+/* Lynx：如果希望内容项不要被压缩，显式保护它 */
+.content-item {
+  flex-shrink: 0;
+  /* 或设置主轴方向明确的 min-width / min-height */
+}
+```
+
+### 陷阱 4：Sticky 不生效
+
+```css
+/* 问题：Sticky 需要正确的父容器 */
+.container {
+  /* 没有设置高度 */
+}
+
+.sticky-element {
+  position: sticky;
+  top: 0;
+}
+
+/* 解决 */
+.container {
+  height: 100vh; /* 或固定高度 */
+  overflow: scroll; /* 需要滚动 */
+}
+
+.sticky-element {
+  position: sticky;
+  top: 0;
+  z-index: 10; /* 确保在最上层 */
+}
+```
+
+### Trap 5: z-index Causes Scroll Not to Follow
+
+```css
+/* Problem: In fold-view/scroll-view, child elements with z-index don't follow scroll */
+fold-view-header .overlay {
+  position: absolute;
+  z-index: 100; /* Promoted to compositing layer, stays fixed in viewport during scroll */
+}
+
+/* Solution: Add z-index to parent container to establish the same stacking context */
+fold-view-header {
+  position: relative;
+  z-index: 0; /* Key: Make header a stacking context */
+}
+
+fold-view-header .overlay {
+  position: absolute;
+  z-index: 100; /* Now correctly follows fold-view-header scroll */
+}
+```
+
+**Other Solutions**:
+
+```css
+/* Option 1: Remove unnecessary z-index */
+.header-item {
+  /* No longer set z-index, control hierarchy via DOM order */
+}
+
+/* Option 2: Move z-index up to the container */
+fold-view-header {
+  position: relative;
+  z-index: 10; /* Control hierarchy at container level */
+}
+
+/* Option 3: For Android platform use android-header-over-slot */
+/* <fold-view android-header-over-slot={true}> */
+```
+
+### 陷阱 6：百分比高度不生效
+
+```css
+/* 问题：百分比高度需要父元素有高度 */
+.parent {
+  /* 没有高度 */
+}
+
+.child {
+  height: 50%; /* 不生效 */
+}
+
+/* 解决 */
+.parent {
+  height: 400px; /* 或 */
+  display: flex;
+  flex-direction: column;
+}
+
+.child {
+  height: 50%;
+  /* 或 Flex 方式 */
+  flex: 1;
+}
+```
+
+## 代码检查清单
+
+在提交代码前，检查以下项目：
+
+- [ ] 使用了合适的布局类型（Linear/Flex/Grid/Relative）
+- [ ] 避免过深的嵌套层级（建议不超过 5 层）
+- [ ] 图片设置了明确的尺寸
+- [ ] 文本内容放在 Text 组件中
+- [ ] 使用了 CSS 类而非大量内联样式
+- [ ] 动画使用了 transform 和 opacity
+- [ ] 列表使用了 list 组件
+- [ ] 触摸目标足够大（最小 44x44）
+- [ ] 颜色对比度足够
+- [ ] 在真机上测试过性能