agentsclimarketplace

Next2taro

Skill weiyi88/cc-code/skills/next2taro

将 Next.js (App Router + Tailwind + shadcn/ui) 的 UI 页面/组件转换为 Taro 小程序 (View/Text + SCSS + PNG)。当用户说"next2taro"、"转换页面"、"Next转Taro"、"页面迁移" 时触发。From its SKILL.md

Install
npx -y skills add weiyi88/cc-code --skill next2taro

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

19.9 KB, as published. Nobody here has run it

Next.js → Taro UI 转换技能

将 Next.js (App Router + Tailwind CSS + shadcn/ui) 的 UI 精确还原为 Taro 小程序 (View/Text + 手写 SCSS + PNG 图片),遵循转换宪法规则。

适用场景

  • Next.js 项目迁移到微信/支付宝/抖音小程序
  • 已有 Next.js UI 设计稿,需要在小程序端还原
  • Taro 项目中某个页面/组件需要对照 Next.js 原版修正

转换宪法(铁律)

§1 标签映射

铁律Next.jsTaro说明
1.1<div><View>所有块级容器
1.2<span> / <p> / <h1>~<h6><Text>所有文本,必须用 Text 包裹
1.3<svg> / 内联 SVG<Image> + PNGSVG 必须导出为 PNG,禁止内联
1.4<img><Image mode="aspectFit">图片组件,必须设置 mode
1.5<a> / <Link href>Taro.navigateTo / switchTab路由跳转(见 §6)
1.6<button><View> + onClick按钮用 View 模拟
1.7<input> / <textarea><Input> / 自定义 <Input type="textarea">表单组件
1.8<label> / <form><View> 模拟无语义标签
1.9<header> / <main> / <footer><View>语义标签 → View

§2 样式系统

铁律规则原因
2.1单一 class 选择器(.foo),禁止嵌套/后代/标签选择器RN 兼容 + 小程序样式隔离
2.2只用 px 单位,禁止 rpx / rem / empxtransform 自动转换
2.3禁止 grid 布局,只用 flexRN 不支持 grid
2.4禁止伪类/伪元素(:hover / ::before / ::after)RN 不支持,用额外 View 模拟
2.5box-shadow 小程序可用,RN 需用 elevation 替代跨端兼容
2.6transition 小程序可用,RN 需用 Animated 替代跨端兼容
2.7所有值引用 variables.scss,禁止魔法数字可维护性
2.8禁止 calc() 表达式,用 width:50% + padding 间距替代小程序兼容性差
2.9Taro <Text> 多行文字必须设 word-break: break-word + line-height: $leading-loose防止文字重叠(实战踩坑)
2.10渐变背景容器的子元素需 overflow: hidden + border-radius: 9999px防止渐变在方圆角下溢出(实战踩坑)

§3 设计像素体系(designWidth:750)

SCSS 中的 px 值 = 实际像素 × 2
例:14px 实际 → SCSS 写 28px
原因:designWidth:750 下 pxtransform 按 1:1 转换 rpx
     而 750 设计稿中 1rpx = 0.5 物理像素

常用映射表:

实际像素SCSS 值Tailwind 对应
12px24pxtext-xs
14px28pxtext-sm
16px32pxtext-base / p-4
18px36pxtext-lg
20px40pxtext-xl
24px48pxtext-2xl
30px60pxtext-3xl
8px16pxgap-2 / p-2
10px20pxgap-2.5 / p-2.5
12px24pxgap-3 / p-3
16px32pxgap-4 / p-4
20px40pxgap-5 / p-5
24px48pxgap-6 / p-6
4px8pxrounded-sm
8px16pxrounded-md
16px32pxrounded-lg
20px40pxrounded-xl
24px48pxrounded-2xl

§4 颜色转换

规则说明示例
oklch → hex必须精确转换,使用在线工具或公式oklch(0.98 0.01 80) → #faf9f7
Tailwind 色板 → hex引用 variables.scss 扩展色板bg-rose-100 → $color-rose-100 → #FFE4E6
渐变 → linear-gradient小程序支持,135deg 为常用角度from-rose-50 to-amber-50 → linear-gradient(135deg, $color-rose-50, $color-amber-50)
半透明色 → rgba用于边框、背景半透明等border-border/50 → rgba($color-border, 0.5)
CSS 变量 → SCSS 变量bg-[--tag-cold-war] → $color-tag-cold-war统一归入 variables.scss

关键实战经验:页面底色必须加深

Next.js 使用 bg-background (#faf9f7 近白色) 作为页面底色,白色卡片在近白底上对比度极差。转换时必须:

Next.js:  bg-background (#faf9f7)  →  Taro: $gradient-page-xxx (#FEEADB → #FFDFDF 暖橙渐变)
Next.js:  bg-background (#faf9f7)  →  Taro: $color-page-bg (#FFF0E8 暖橙纯色)

§5 SVG → PNG 转换流程

1. 分析 Next.js SVG 组件,确定 type × status 组合矩阵
2. 为每个组合创建独立 SVG 文件(含渐变定义)
3. 用 rsvg-convert 批量渲染为 4x 分辨率 PNG:
   rsvg-convert -w 400 -h 400 input.svg -o output.png
4. PNG 放入 src/assets/monsters/ (或对应目录)
5. 组件中用 require('@/assets/xxx.png') 引用
6. 删除旧的手绘 View/Text 图标代码

实战踩坑:MonsterIcon 渐变溢出

Next.js 使用 rounded-2xl (方圆角),Taro 中渐变背景会在圆角处溢出显示底色。修复:

// ❌ 错误:方圆角,渐变在角落溢出
.monster-icon { border-radius: 32px; }

// ✅ 正确:正圆 + overflow hidden,完全裁剪渐变
.monster-icon { border-radius: 9999px; overflow: hidden; }

命名规范: {type}_{status}.png,如 attitude_wild.png、happy_tamed.png

§6 路由映射

Next.jsTaro说明
<Link href="/page">Taro.navigateTo({url: '/pages/page/index'})普通页面
tabBar 页面跳转Taro.switchTab({url: '/pages/tab/index'})底部导航页
router.back()Taro.navigateBack()返回
router.push('/page?id=1')Taro.navigateTo({url: '/pages/page/index?id=1'})带参跳转
app/dex/[id]/page.tsx (动态路由)Taro.navigateTo({url: '/pages/detail/index?id=xxx'})详情页
useParams()Taro.getCurrentInstance().router.params获取路由参数

§7 shadcn/ui 组件拆解规则

Next.js 使用 56 个 shadcn/ui Radix 组件,Taro 中全部替换为 <View> + <Text> + SCSS。核心拆解模式:

shadcn/ui 组件Taro 替换方案说明
<Card> / <CardContent> / <CardHeader> / <CardTitle><View className="xxx-card">每张卡片一个顶层 View,内部直接排布
<Button variant="outline" size="sm"><View className="xxx-btn"> + onClick移除 variant/size,手写 SCSS 状态
<Badge variant="secondary"><Text className="xxx-badge">badge 降级为 Text + 背景色
<Textarea rows={4}><Input type="textarea" className="xxx-textarea">shadcn → Taro Input
<Avatar> / <AvatarFallback>自定义 <Avatar> 组件渐变色首字母头像

拆解原则:

  1. Card → View:shadcn Card 的 border-0 shadow-lg 等属性全部转入 SCSS class
  2. Button → View+onClick:移除 variant/size/className 体系,每个按钮写独立 SCSS
  3. Badge → Text:badge 的 variant 通过不同 class 实现(如 .tag-badge-wild、.tag-badge-tamed)
  4. 不引入任何 UI 库:Taro 端全部手写,保持零依赖

§8 lucide 图标 → emoji 映射表

lucide-react SVG 图标在小程序中不可用,全部替换为 Text emoji。本项目的完整映射:

lucide 图标emoji用途
Heart♥ / ❤️ / 💚爱心(不同场景用不同变体)
ArrowLeft←返回(通常用原生导航栏)
Snowflake❄️冷战标签
Home🏠家务标签
Frown😤态度标签
EyeOff🙈忽视标签
HelpCircle❓其他标签
PartyPopper🎉开心标签
MessageCircleHeart💕心动标签 / 暖心话语选项
Star⭐想你标签
Gift🎁感谢标签 / 送礼物选项
Sparkles✨AI 翻译标识 / 温柔版本
Wand2🪄AI 翻译按钮
CheckCircle✅成功页面
Send💌发送按钮
Clock⏰时间线标题
MessageCircle💬消息时间线 / 暖心话语选项
Check✓ (白色文字)时间线已查看事件
Hand🤝求抱抱选项
Coffee☕约会邀请选项
Music🎵一首歌选项
Share2📤分享按钮
Calendar📅天数统计
Zap⚡连续天数
BookOpen📖图鉴标题
Settings⚙️设置菜单
LogOut🚪退出登录
ChevronRight›菜单箭头(文字符号)
Share2📤分享卡片

替换原则:

  1. 功能图标(导航、操作)→ 选择语义最接近的 emoji
  2. 装饰图标(标签、徽章)→ 选视觉辨识度高的 emoji
  3. 动画图标(animate-spin、animate-pulse)→ emoji 无法做动画,移除或用文字替代
  4. 箭头/方向 → 优先用文字符号 › ← →,而非 emoji

§9 Taro 特有视觉陷阱与修复

基于实战踩坑总结,以下问题在转换中极易出现:

陷阱 1:Taro Text 多行文字重叠

现象: 长文本在 Taro <Text> 组件中换行后行与行重叠。

修复: 所有多行 Text 必须显式设置行高和断词:

.translated-text {
  font-size: $text-sm;
  line-height: $leading-loose;   // 1.75,比 Next.js 的 leading-relaxed(1.625) 更宽松
  word-break: break-word;        // 强制长词断行
}

适用场景: 翻译结果、原始文本、任意可能多行的 Text 内容。

陷阱 2:渐变背景容器溢出

现象: 容器使用渐变 background + border-radius 非圆形时,渐变在角落溢出。

修复: 渐变背景容器必须 overflow: hidden,圆角图标用正圆:

// 方圆角容器 — 加 overflow
.card-header-gradient {
  background: $gradient-detail-header;
  overflow: hidden;
}

// 圆形图标 — 用 9999px 正圆
.monster-icon {
  border-radius: 9999px;  // 不是 $radius-2xl
  overflow: hidden;
}

// 白色圆圈包裹渐变图标 — 也要 overflow
.card-monster-circle {
  border-radius: $radius-full;
  overflow: hidden;
}

陷阱 3:calc() 兼容性差

现象: width: calc(50% - 8px) 在部分小程序版本渲染异常。

修复: 用 flex + width + padding + 内层 View 替代:

// ❌ 错误
.option-item { width: calc(50% - 8px); margin: 4px; }

// ✅ 正确:外层 50% 宽 + padding 间距,内层实际内容
.option-item {
  width: 50%;
  box-sizing: border-box;
  padding: $space-1;
}
.option-item-inner {
  background-color: $color-option-bg;
  border-radius: $radius-xl;
  padding: $space-2_5;
  // 实际内容
}
// JSX 结构必须加内层 View
<View className="option-item">
  <View className="option-item-inner">
    <View className="option-icon-bg">...</View>
    <Text className="option-name">...</Text>
  </View>
</View>

陷阱 4:页面底色对比度不足

现象: Next.js bg-background (#faf9f7) 几乎纯白,白色卡片浮不起来。

修复: 所有页面底色加深为暖橙渐变,见 §4 颜色转换。

陷阱 5:日期未格式化

现象: 直接显示 ISO 字符串 "2024-01-15T14:30:00"。

修复: 必须使用 formatDate() 工具函数:

export function formatDate(dateString: string): string {
  const date = new Date(dateString)
  const month = date.getMonth() + 1
  const day = date.getDate()
  const hours = date.getHours().toString().padStart(2, '0')
  const minutes = date.getMinutes().toString().padStart(2, '0')
  return `${month}月${day}日 ${hours}:${minutes}`
}

陷阱 6:阴影不够立体

现象: Tailwind shadow-sm 太弱,卡片看起来"贴在纸面上"。

修复: 使用双层阴影变量,分场景选用:

// variables.scss 中定义
$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);           // 内嵌子元素微浮
$shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);             // 小型交互元素
$shadow-card: 0 8px 24px rgba(0, 0, 0, 0.08),         // 标准卡片浮起
             0 2px 8px rgba(0, 0, 0, 0.04);
$shadow-card-lg: 0 12px 32px rgba(0, 0, 0, 0.1),      // 主卡片/大卡片
                0 4px 12px rgba(0, 0, 0, 0.05);

选用规则:

  • 内嵌子元素(today-monster、recent-item)→ $shadow-sm
  • 普通卡片(dex monster、stats、menu、sweet-words)→ $shadow-card
  • 主卡片/详情卡(detail monster、resolve section)→ $shadow-card-lg
  • 带色彩辉光(couple-card、today-card)→ 专用 $shadow-couple / $shadow-today

§10 底部导航转换规则

Next.jsTaro说明
<BottomNav> 自定义组件 (fixed + usePathname)app.config.ts tabBar 原生配置原生 tabBar 性能更好
lucide 图标 (Home/PlusCircle/BookOpen/User)PNG 图片 (home.png / capture.png / dex.png / profile.png)每个图标需 normal + active 两态
<Link> 跳转原生自动切换无需手写跳转逻辑
usePathname() 高亮当前原生自动高亮无需手写判断

TabBar PNG 图标配额:

src/assets/tabbar/
├── home.png          # 首页-未选中
├── home-active.png   # 首页-选中
├── capture.png       # 捕获-未选中
├── capture-active.png # 捕获-选中
├── dex.png           # 图鉴-未选中
├── dex-active.png    # 图鉴-选中
├── profile.png       # 我的-未选中
├── profile-active.png # 我的-选中

§11 数据层转换规则

Next.jsTaro说明
lib/data.ts + data/mock-data.json 分离src/data/mock.ts 内联数据小程序不便读取 JSON 文件
export function getUser() 等函数式取数export const mockUser 等常量导出简化,去掉间接层
formatDistanceToNow() 相对时间formatDate() 绝对日期小程序场景绝对时间更实用
服务端数据获取 (Server Component)纯客户端数据Taro 无服务端组件

数据模型差异注意:

Next.js Monster: complaintText, capturedAt, resolved, resolveMethod, resolutionNote, emotion
Taro Monster:    mode, mediaList
→ 两者共享核心字段 (id, tag, status, intensity, originalText, translatedText, createdAt)
→ 各自有扩展字段,转换时需同步 types/index.ts

§12 API 转换规则

Next.jsTaro说明
fetch('/api/translate')Taro.request() 或云函数服务端路由 → 云函数
window.localStorageTaro.setStorageSync() / getStorageSync本地存储
router.push()Taro.navigateTo()路由
useParams()Taro.getCurrentInstance().router.params路由参数
alert()Taro.showModal() 或 Taro.showToast()弹窗
Vercel AI SDK云函数 + AI APIAI 功能

§13 页面结构转换规则

Next.js 模式Taro 模式说明
自定义 <header> (sticky + backdrop-blur)移除,用原生导航栏小程序原生导航栏更稳定
<main className="max-w-md mx-auto">移除 max-w-md,小程序全宽小程序无桌面端宽度限制
<BottomNav /> 每页引入app.config.ts tabBar 全局配置原生 tabBar
pb-20 底部留白padding-bottom: $space-20 (tabBar) 或 120px~180px (固定按钮)按场景调整
space-y-5 垂直间距gap: $space-5 (flex) 或各元素 margin-bottom小程序无 Tailwind space 工具

转换工作流

Phase 1: 审计对照

  1. 读取 Next.js 源页面/组件 TSX + CSS
  2. 读取 Taro 目标页面/组件 TSX + SCSS
  3. 列出所有宪法违规项(按 §1-§13 逐条检查)
  4. 输出差异报告:合规率 + 具体违规列表

Phase 2: 变量基建

  1. 检查 variables.scss 是否覆盖所需色板、间距、阴影
  2. 补充缺失的 Tailwind 色板变量(rose/amber/sky/indigo/emerald 等)
  3. 补充渐变定义($gradient-xxx)
  4. 补充语义透明色($color-border-light, $color-card-semi 等)
  5. 补充双层/彩色阴影变量($shadow-card, $shadow-card-lg 等)
  6. 补充页面底色渐变($gradient-page-xxx,注意加深对比度)

Phase 3: 组件转换

按以下优先级逐个转换:

  1. 标签替换:div→View, span→Text, img→Image, a→navigateTo
  2. shadcn/ui 拆解:Card→View, Button→View+onClick, Badge→Text, Textarea→Input
  3. lucide→emoji:按 §8 映射表替换所有图标
  4. SVG→PNG:内联 SVG 导出为 PNG,组件改用 Image
  5. 样式重写:
    • 嵌套选择器 → 扁平单一 class
    • rpx/rem → px
    • grid → flex(grid-cols-2 → flex + width:50% + padding + inner View)
    • calc() → width:50% + padding 间距(见 §9 陷阱3)
    • 伪类/伪元素 → 额外 View 模拟
    • 魔法数字 → variables 引用
    • 多行 Text → 加 line-height + word-break(见 §9 陷阱1)
    • 渐变容器 → 加 overflow:hidden(见 §9 陷阱2)
  6. 路由替换:Link → Taro.navigateTo/switchTab
  7. API 替换:fetch → Taro.request, localStorage → Taro.setStorageSync 等
  8. 页面底色加深:bg-background → $gradient-page-xxx 暖橙渐变
  9. 阴影升级:shadow-sm → $shadow-card / $shadow-card-lg

Phase 4: 立体感还原

Next.js 中常见但 Taro 易丢失的视觉效果:

视觉效果Next.js 原版Taro 还原方式
双层阴影shadow-md shadow-smbox-shadow: 0 10px 15px rgba(...), 0 4px 6px rgba(...)
彩色辉光渐变卡片 + shadowbox-shadow: 0 10px 25px rgba(rose, 0.12), 0 4px 10px rgba(amber, 0.08)
ring 光环ring-1 ring-borderborder: 1px solid $color-border-light
border-left 状态条border-l-4 border-l-red-500border-left: 6px solid $color-monster-wild + 动态 class
渐变背景bg-gradient-to-br from-rose-50 to-amber-50background: linear-gradient(135deg, $color-rose-50, #FFF, $color-amber-50)
圆形辉光shadow + ring 组合box-shadow: 0 8px 24px rgba(...), 0 0 0 3px rgba(...)
带色彩按钮投影无box-shadow: 0 8px 24px rgba(232, 93, 93, 0.3)

Phase 5: 自检清单

转换完成后逐项验证:

  • 所有 div → View, span/p → Text
  • SVG 内联 → PNG Image
  • shadcn/ui Card/Button/Badge/Textarea 全部拆解为 View/Text/Input
  • lucide 图标全部替换为 emoji
  • 无嵌套/后代/标签选择器
  • 无 rpx/rem,只用 px
  • 无 grid,只用 flex
  • 无 calc(),用 width+padding 替代
  • 无伪类/伪元素
  • 无魔法数字,全部引用 variables
  • 路由用 Taro API
  • 阴影/渐变/ring 还原
  • px 值为实际像素 × 2(designWidth:750)
  • 颜色精确转换(oklch→hex)
  • 页面底色已加深(非近白色)
  • 卡片阴影使用 $shadow-card / $shadow-card-lg
  • 多行 Text 设 line-height + word-break
  • 渐变容器设 overflow:hidden
  • 圆角图标用 border-radius: 9999px(非 2xl)
  • 日期使用 formatDate() 格式化
  • 编译通过无错误

输出规范

转换时必须输出:

  1. 差异报告:列出所有违规项(审计阶段)
  2. 变更清单:每个文件的修改说明(执行阶段)
  3. 自检结果:逐项勾选自检清单(验证阶段)
  4. 编译验证:npm run build:weapp 结果

注意事项

  • 优先还原视觉 fidelity,其次追求代码优雅
  • 遇到宪法规则与视觉效果冲突时,优先遵守宪法(如伪类不可用则用 View 模拟)
  • 每个页面/组件转换后立即编译验证,不要攒一批再验证
  • PNG 图片建议 4x 分辨率(400×400 for 100×100 渲染尺寸)
  • 渐变色值必须与 Next.js 原版一致,不能凭感觉调
  • 所有 Taro <Text> 多行内容必须加 word-break: break-word + line-height: $leading-loose
  • 所有渐变背景容器必须加 overflow: hidden
  • 页面底色绝对不能用近白色,必须加深到暖橙渐变以形成卡片对比度

Keep looking

Skills are one crate of 610,220. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.