Pencil To Miniprogram

Pencil → 微信小程序 标准工作流

前置条件

• Pencil MCP 已加载目标 .pen 文件
• 已通过 mcp__pencil__get_editor_state 确认设计稿处于活动状态
• 已知目标页面的 frame 节点 ID（如 RweGQ）

核心工具

流程总览

① 读取设计稿 → ② 提取信息 → ③ 编写 WXML → ④ 编写 WXSS → ⑤ 对接 JS → ⑥ 走查验证
   editor_state    batch_get      结构还原      像素级样式     交互/数据      截图对比
   +batch_get      +snapshot      +image标签     +rpx换算      +默认值       +坑点复查
   +screenshot     +variables     +层级关系      +阴影换算

① 读取设计稿数据（不可缩减）

以下 5 个调用缺一不可，必须并行调用：

// 1. 确认文件状态和获取顶层节点 ID
mcp__pencil__get_editor_state({ include_schema: true })

// 2. 读取目标页面完整节点树（⚠️ resolveVariables: true 必须开启）
mcp__pencil__batch_get({
  filePath: ".../new.pen",
  nodeIds: ["RweGQ"],
  readDepth: 6,          // 深入到叶子节点，避免漏读
  resolveVariables: true  // ⚠️ 必须：获取解析后的 hex 值，否则拿到的可能是 $primary 引用
})

// 3. 获取精确布局（用于间距计算）
mcp__pencil__snapshot_layout({
  filePath: ".../new.pen",
  parentId: "RweGQ",
  maxDepth: 4             // 足够看到所有区域层
})

// 4. 获取截图（⚠️ 第一步就获取，全程对照，不是最后才看）
mcp__pencil__get_screenshot({
  filePath: ".../new.pen",
  nodeId: "RweGQ"
})

// 5. 获取设计变量（确保 token 值一致）
mcp__pencil__get_variables({ filePath: ".../new.pen" })

⚠️ 常见错误：

• resolveVariables: true 忘了传 → 拿到 "$primary" 字符串而非 "#2D3E5F"
• readDepth 设太浅（3）→ 遗漏深层文本/图标节点
• 截图放在最后才获取 → 应该第一步获取，写入代码时随时对照

② 提取关键信息（防止遗漏）

必须提取的六类信息

间距交叉计算表（⚠️ 必须执行）

提取所有 section 的 y 和 height，计算相邻 gap。不计算直接写 margin 必出错。

Section          y(px)  h(px)  bottom(px)  y(rpx)  h(rpx)  bottom(rpx)  gap(rpx)
Header            0      96      96          0      192      192          -
HeroCard         100    160     260        200     320      520          520-192=8
QuickActions     274     82     356        548     164      712          712-520=28  (用 snapshot_layout!)
ProgressSection  366    152     518        732     304     1036         1036-712=20
RecommendSection 524    182     706       1048     364     1412         1412-1036=12
TabBar           728     84     812       1456     168     1624         1624-1412=48

⚠️ 关键：batch_get 返回的 x/y 是设计值（可能有 0.5px 偏移），snapshot_layout 返回的才是实际渲染位置。间距大时优先用 snapshot_layout 数据。

阴影透明度换算表

Hex alpha 最后两位 → rgba 小数：

图标处理决策树（⚠️ 高频出错点）

设计稿中的 icon 节点
  ├── library: "lucide" / "feather" 等矢量图标库
  │     └── ⚠️ 小程序无法直接使用！必须导出为 PNG
  │           1. mcp__pencil__export_nodes({ nodeIds: [iconFrameId], scale: 2 })
  │           2. 保存到 /assets/images/icons/
  │           3. 用 <image> 标签引用
  │           ❌ 禁止：用 deco 通用装饰图替代
  │           ❌ 禁止：用 emoji 替代（渲染不一致）
  │
  ├── type: "image" fill（已生成图片）
  │     └── 直接使用 url 指向的图片路径
  │
  └── 纯 CSS 可实现（简单几何形状）
        └── 用 WXSS 绘制

尺寸换算规则（px → rpx）

微信小程序以 iPhone 6/7/8 的 375px 宽度为基准，换算关系：

1 px = 2 rpx

阴影换算规则

设计稿: blur:20, color:#2D3E5F25, offset:{x:0, y:6}
→ WXSS: box-shadow: 0 12rpx 40rpx rgba(45, 62, 95, 0.15);

规则: offsetX×2, offsetY×2, blur×2, 颜色不变

③ 编写 WXML

核心原则

1. <image> 标签代替 WXSS background-image

   ⚠️ 关键限制：微信小程序 WXSS 中不能使用本地资源路径作为 background-image。必须改用 <image> 标签。

   <!-- ❌ 错误：WXSS 中不能使用 -->
   <!-- .card { background-image: url('/assets/images/bg.png'); } -->
   
   <!-- ✅ 正确：使用 <image> 标签绝对定位 -->
   <view class="card">
     <image class="bg-image" src="/assets/images/bg/bg_card.png" mode="aspectFill" />
     <view class="card-content">
       <!-- 内容 -->
     </view>
   </view>
   

   .card {
     position: relative;
     overflow: hidden;
   }
   .bg-image {
     position: absolute;
     top: 0;
     left: 0;
     width: 100%;
     height: 100%;
     z-index: 0;
   }
   .card-content {
     position: relative;
     z-index: 1;
   }
   

2. 结构分层：每个需要背景图的容器都使用 position: relative + overflow: hidden，内部用 .bg-image + .card-content

3. 装饰元素：使用 position: absolute 精确定位，添加 pointer-events: none 和 z-index: 2

4. scroll-view 注意事项：

   • padding 放在 inner 容器上，不要直接放在 scroll-view 上
   • 如果装饰元素需要跟随滚动，放在 scroll-inner 内；如果固定，放在 scroll-view 外

④ 编写 WXSS

逐属性对照表

字体栈映射

⑤ 对接 JS 和交互

必须处理的三个问题

1. 默认数据：如果设计稿中某区域有静态内容（如推荐卡片），但 API 可能返回空，需要在 data 或 catch 中设置默认值

2. 事件绑定：所有可点击元素必须绑定 bindtap，包括：

   • 按钮/标签（如"继续学习"、"详情 ›"）
   • 卡片（如 HeroCard、RecCard）
   • Tab 切换

3. 共享组件：TabBar 等共享组件修改需谨慎，保持与项目现有路由一致

⑥ 走查验证（不可跳过）

三遍走查法

第 1 遍：WXML 核对

• 所有设计稿中的文本段落都在 WXML 中有对应
• 容器嵌套层次与设计稿一致
• <image> 标签已替代所有 WXSS background-image
• 所有图标节点已正确处理（lucide 导出 PNG / image fill 直接引用）
• 条件渲染逻辑正确

第 2 遍：WXSS 核对

• 每个 background-color 都从设计稿精确提取
• border-radius 精确换算为 rpx
• box-shadow 按规则换算（offset×2, blur×2, 颜色透明度查表）
• 所有 px 值都已换算为 rpx
• 没有遗漏的 background-image 在 WXSS 中
• 区域间距已与交叉计算表核对（最容易出错）
• 装饰元素位置已与 snapshot_layout 坐标核对

第 3 遍：截图对照

• 打开微信开发者工具预览
• 对照 design-screenshot.png 检查：
  • 背景图是否正确显示
  • 颜色氛围是否一致
  • 各区域间距是否合理
  • 字体大小层级是否正确
  • 图标是否与设计稿一致（不是通用替代图）
  • 装饰元素是否可见

高频缺陷自查清单

常见坑点速查

文件存放规范

pages/{page}/
├── {page}.wxml          # WXML 模板
├── {page}.wxss          # WXSS 样式
├── {page}.js            # JS 逻辑
├── {page}.json          # 页面配置
└── design-screenshot.png # 设计稿截图（用于走查）

示例：HeroCard 背景图改造

设计稿属性

• type: frame, width: 327, height: 162
• fill: { mode:"fill", type:"image", url:"../../assets/images/bg/bg_hero_card.png" }
• cornerRadius: 16

错误写法（WXSS background-image）

.hero-card {
  background-image: url('/assets/images/bg/bg_hero_card.png');
  background-size: cover;
}

正确写法（ 标签）

<view class="hero-card">
  <image class="bg-image" src="/assets/images/bg/bg_hero_card.png" mode="aspectFill" />
  <view class="card-content">
    <text class="hero-title">Python 基础 · 第3章</text>
  </view>
</view>

.hero-card {
  position: relative;
  width: calc(100% - 96rpx);
  height: 324rpx;
  border-radius: 32rpx;
  overflow: hidden;
}
.bg-image {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 0;
}
.card-content {
  position: relative;
  z-index: 1;
  padding: 40rpx;
}

复刻案例复盘：2026-06-12 主页 (RweGQ)

背景

对主页 (RweGQ) 进行 1:1 复刻，首轮完成后用户反馈两个问题：

1. QuickActions 图标未复刻
2. 整体并非完美 1:1

首轮缺陷清单

流程改进（已更新到上文各节）

1. 图标决策树：新增加入 ② 提取阶段 → 图标处理决策树
2. 间距交叉计算表：新增加入 ② 提取阶段 → 必须生成 gap 计算表
3. 阴影换算表：新增加入 ② 提取阶段 → hex alpha→rgba 对照
4. resolveVariables 强制：在 ① 读取阶段标注 ⚠️ must
5. readDepth 建议值：3→6，避免节点信息截断
6. 自查清单：在 ⑥ 走查阶段新增 checkbox 清单
7. 截图时机：从"最终对照"改为"第一步获取，全程对照"

关键教训

不要用通用资源替代精确资源。 deco 图片只用于装饰元素（背景波浪/圆点/星星），功能图标必须从设计稿导出。每个 type: "icon" 节点都必须经过"判断→导出→引用"流程。

间距永远用计算值，不用估算值。 snapshot_layout 给出精确坐标，交叉计算表给出精确 gap，直接填入 margin。目测必出错。

5 个工具调用缺一不可。 editor_state + batch_get(resolveVariables=true) + snapshot_layout + screenshot + variables，并行调用不省任何一个。