122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# 智绘微刻小程序 - 遮罩尺寸配置指南
|
||
|
||
## 📌 概述
|
||
|
||
本小程序的 DIY 工作台使用**遮罩层（Mask）**来模拟实际产品的雕刻区域。用户在画布上看到的半透明黑色区域之外的部分，即为该产品的实际外形轮廓；白色/透明区域则是激光雕刻的可用范围。
|
||
|
||
当你们确定了各品类的真实尺寸后，**只需修改一个配置文件**，所有页面的渲染就会自动更新。
|
||
|
||
---
|
||
|
||
## 🎯 修改位置
|
||
|
||
**文件路径：**
|
||
```
|
||
src/utils/productConfig.ts
|
||
```
|
||
|
||
此文件导出一个 `PRODUCTS` 数组，每个品类对象中都有一个 `mask` 属性，就是遮罩的配置。
|
||
|
||
---
|
||
|
||
## 📐 尺寸单位说明
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| 单位 | `px`（像素） |
|
||
| 基准 | 基于 **750px 宽度** 的设计稿 |
|
||
| 换算建议 | 实际尺寸（mm）÷ 实物最大宽度（mm）× 画布宽度（px） |
|
||
|
||
### 举例
|
||
假设铜质杯垫实际直径为 **90mm**，画布区域在手机上显示为 **300px 宽**：
|
||
```
|
||
先量出杯垫实际直径对应的像素比例：
|
||
90mm ÷ 90mm × 280 = 280px
|
||
（如果直接按1:1在画布上展示，就填280）
|
||
```
|
||
|
||
**更简单的方式**：等真实的样品拿到后，直接用手机截图量一下在 375px 逻辑像素下应该占多大，然后把数值填进去即可。
|
||
|
||
---
|
||
|
||
## 🔧 遮罩类型
|
||
|
||
### 1. 矩形遮罩（rect）
|
||
适用于：笔记本、笔盒、书本灯等方形/圆角矩形产品
|
||
|
||
```typescript
|
||
mask: {
|
||
type: 'rect',
|
||
width: 300, // 遮罩宽度（px）
|
||
height: 420, // 遮罩高度（px）
|
||
radius: 8 // 圆角半径（px），不需要圆角填 0
|
||
}
|
||
```
|
||
|
||
### 2. 圆形遮罩（circle）
|
||
适用于：杯垫、徽章等圆形产品
|
||
|
||
```typescript
|
||
mask: {
|
||
type: 'circle',
|
||
width: 280, // 椭圆外接矩形宽度（px）
|
||
height: 280 // 椭圆外接矩形高度（px）
|
||
}
|
||
```
|
||
|
||
> 如果 `width === height`，即为正圆；如果不相等，则为椭圆。
|
||
|
||
---
|
||
|
||
## 📋 当前品类与待填尺寸
|
||
|
||
| 品类ID | 品类名称 | 当前尺寸 | 状态 |
|
||
|---|---|---|---|
|
||
| `notebook-small` | 微雕笔记本（小） | 300 × 420 px | 占位待改 |
|
||
| `notebook-large` | 微雕笔记本（大） | 340 × 480 px | 占位待改 |
|
||
| `coaster` | 铜质杯垫 | 280 px 直径 | 占位待改 |
|
||
| `penbox` | 竹制笔盒 | 320 × 160 px | 占位待改 |
|
||
| `booklamp` | 书本型灯 | 320 × 240 px | 占位待改 |
|
||
|
||
---
|
||
|
||
## 💡 修改步骤
|
||
|
||
1. 测量实际样品的雕刻区域尺寸（建议用卡尺精确到 mm）
|
||
2. 在手机上打开小程序 DIY 页面，截图量出画布的实际显示像素
|
||
3. 按比例换算：`(实际尺寸 mm / 画布对应的实际物理宽度 mm) × 画布像素宽度`
|
||
4. 打开 `src/utils/productConfig.ts`
|
||
5. 修改对应产品 `mask` 对象的 `width`、`height`、`radius` 数值
|
||
6. 保存文件，重新编译小程序即可看到效果
|
||
|
||
---
|
||
|
||
## 🎨 效果说明
|
||
|
||
遮罩在 UI 上的表现：
|
||
- 遮罩区域：**透明/白色**，可看到用户上传的图片，表示这是雕刻范围
|
||
- 遮罩外部：**半透明黑色蒙层**，提示用户图片在这个范围之外的部分不会被雕刻到产品上
|
||
- 遮罩边框：**白色虚线框**，清晰标识边界
|
||
|
||
用户上传图片后，可以通过**拖拽**调整图片在遮罩内的位置，通过**缩放按钮**调整图片大小，确保想要雕刻的内容落在白色遮罩区域内。
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **修改后需重新编译**：Taro 会热更新，但在微信开发者工具中建议点击「编译」确保生效
|
||
2. **尺寸不宜过大**：遮罩面积建议不超过画布面积的 80%，否则用户难以感受到「边缘」
|
||
3. **留足边距**：设计时建议遮罩四周至少留出 20px 的安全边距，避免用户把图片贴得太边
|
||
4. **圆形产品**：如果杯垫等产品有固定内圈雕刻区域（而非整个圆面），可以将 `width/height` 设小一点，模拟内圈
|
||
|
||
---
|
||
|
||
## 🔗 相关文件
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `src/utils/productConfig.ts` | 品类与遮罩配置（修改这里） |
|
||
| `src/types/index.ts` | 类型定义（一般不需要改） |
|
||
| `src/pages/diy/index.tsx` | DIY 工作台页面（读取配置自动渲染） |
|
||
| `src/pages/diy/index.scss` | 遮罩样式（一般不需要改） |
|