d8d-vite-starter/docs/mobile-home-icon-scroll-layout.md

移动端首页图标分类滚动布局实现方案

需求概述

将移动端首页图标分类区域修改为水平滚动、固定2行显示的布局，提升小屏设备的图标展示效率。

当前布局分析

当前图标分类使用网格布局(grid grid-cols-3 gap-3)实现，代码位于src/client/mobile/pages/NewHomePage.tsx第392行：

<div className="grid grid-cols-3 gap-3">
  {categories.map((category, index) => (
    <button
      key={index}
      onClick={() => navigate(category.path || '/')}
      className="flex flex-col items-center p-4 rounded-xl transition-all duration-300 hover:shadow-lg backdrop-blur-sm"
      style={{
        backgroundColor: 'rgba(255,255,255,0.7)',
        border: `1px solid ${COLORS.ink.medium}`,
        color: COLORS.text.primary
      }}
    >
      {/* 图标和文字内容 */}
    </button>
  ))}
</div>

实现方案

1. HTML结构修改

将网格布局容器修改为水平滚动容器，保留按钮元素结构不变：

<div className="relative">
  {/* 水平滚动容器 */}
  <div className="flex space-x-3 overflow-x-auto pb-4 snap-x snap-mandatory hide-scrollbar">
    {categories.map((category, index) => (
      <button
        key={index}
        onClick={() => navigate(category.path || '/')}
        className="flex-shrink-0 w-24 flex flex-col items-center p-4 rounded-xl transition-all duration-300 hover:shadow-lg backdrop-blur-sm snap-start"
        style={{
          backgroundColor: 'rgba(255,255,255,0.7)',
          border: `1px solid ${COLORS.ink.medium}`,
          color: COLORS.text.primary
        }}
      >
        {/* 原有图标内容 */}
        <div
          className="w-14 h-14 rounded-full flex items-center justify-center shadow-sm"
          style={{ backgroundColor: COLORS.accent.blue, color: 'white' }}
        >
          <img
            src={category.image || '/images/placeholder.jpg'}
            alt={category.name}
            className="w-8 h-8 object-cover rounded-full"
            onError={(e) => {
              (e.target as HTMLImageElement).style.display = 'none';
              (e.target as HTMLImageElement).parentElement!.innerHTML = '📱';
            }}
          />
        </div>
        <span className={`${FONT_STYLES.caption} mt-2 line-clamp-1`}>{category.name}</span>
      </button>
    ))}
  </div>
  
  {/* 可选：添加渐变遮罩指示可滚动 */}
  <div className="absolute right-0 top-0 bottom-0 w-8 bg-gradient-to-l from-ink-light to-transparent pointer-events-none"></div>
</div>

2. 核心CSS样式

需要添加以下CSS样式实现固定2行布局和水平滚动：

/* 隐藏滚动条但保留滚动功能 */
.hide-scrollbar::-webkit-scrollbar {
  display: none;
}
.hide-scrollbar {
  -ms-overflow-style: none;
  scrollbar-width: none;
}

/* 固定两行高度计算 */
.fixed-two-rows {
  height: calc( (按钮高度) * 2 + (间距) );
}

/* 按钮样式调整 */
.category-button {
  /* 确保按钮宽度一致 */
  width: 24vw;
  max-width: 120px;
}

3. 关键修改点说明

1. 容器修改：

   • 将grid grid-cols-3改为flex space-x-3 overflow-x-auto
   • 添加pb-4提供底部内边距避免裁剪
   • 使用snap-x和snap-mandatory增强滚动体验

2. 按钮样式调整：

   • 添加flex-shrink-0防止按钮被压缩
   • 固定按钮宽度为24vw(约4个按钮/屏)
   • 使用snap-start确保滚动对齐

3. 两行高度控制：

   • 精确计算容器高度为(按钮高度 + 间距) * 2
   • 建议按钮高度设为120px(含内边距)

4. 适配与兼容性

• 小屏设备：确保按钮最小宽度不小于80px
• 触摸反馈：保留原有的hover:shadow-lg效果
• 加载状态：维持现有骨架屏逻辑

实施步骤

1. 修改src/client/mobile/pages/NewHomePage.tsx第392行的容器 className
2. 添加滚动相关CSS样式至全局样式表
3. 调整按钮宽度和内边距
4. 添加渐变遮罩指示可滚动区域
5. 在不同设备上测试滚动流畅度

测试要点

• 验证在320px-428px宽度设备上均可正常显示2行
• 测试水平滚动流畅度，无卡顿现象
• 确保图标和文字不被截断
• 验证点击跳转功能正常
• 检查在深色/浅色模式下的显示一致性