水晶手链定制插件-完整使用教程

一、安装与基础准备

准备好插件安装包 crystal-bracelet-customizer.zip，并使用具有插件安装权限的 WordPress 管理员账号登录后台。插件声明的最低环境是 WordPress 6.3、PHP 7.4；这只是最低要求，正式站还应结合主机与商城要求使用受支持的版本。

1. 进入 WordPress 后台的插件 → 安装插件 → 上传插件。
2. 选择 ZIP 文件，点击现在安装。不用提前解压。
3. 安装完成后点击启用插件。
4. 确认左侧出现首饰定制菜单，并在插件列表或插件设置页确认版本为 2.2.0。

已经装过旧版，怎样更新？

先备份网站文件与数据库，再上传新版 ZIP。如果后台提示该插件已经存在，选择使用上传的插件替换当前插件。新版继续读取已有材料、价格、Logo、颜色与文案设置；更新后清理页面缓存和 CDN 缓存，再刷新前端。2.1 版草稿里散开的珠子，会按保留的顺序重新排列成环。

后台菜单分别做什么？

二、创建并绑定一个下单商品

需要在线收款时，先启用 WooCommerce，完成店铺货币、支付和配送的基础配置。接下来创建一个供定制器使用的简单产品，例如“我的定制水晶手链”。顾客的每种设计会作为这个基础商品的独立定制购物车项目保存。

1. 在后台进入产品 → 新增产品，填写商品名称与必要说明。
2. 将产品类型设为简单产品，不要选可变产品。
3. 填写常规价格，可以填 0，不要留空。定制商品的材料价格由插件按所选珠子重新计算。
4. 确认商品已发布，并且有货、可以购买。按实际业务配置库存。
5. 销售实体手链时，不要勾选“虚拟”，并设置配送区域与配送方式；免运费业务也应配置相应配送方式。
6. 可以将目录可见性设为隐藏，让顾客通过定制页面进入购买流程。商品应保持已发布。
7. 记录产品 ID，进入首饰定制 → 插件设置，填写到“WooCommerce 产品 ID”，点击保存设置。

产品 ID 可以从商品编辑页地址中的 post=123 判断，这里的 123 就是 ID。界面形式不同的后台，也可以从产品列表的 ID 信息查找。不要把商品名称、SKU 或商品链接填进产品 ID 输入框。

产品类型、价格与配送字段可参考 WooCommerce 官方产品编辑说明。具体界面文字可能随后台版本和语言有所不同。

三、添加水晶、图片、尺寸与价格

进入首饰定制 → 水晶管理，点击＋ 添加水晶。每种水晶是一张可以展开、折叠的管理卡片。

1. 填写名称与唯一 ID

名称是顾客看到的材料名称，例如“紫水晶”或“Amethyst”。新水晶填写名称后，会尝试自动生成 ID；也可以手动使用 amethyst 这样的英文标识。每种水晶的 ID 必须唯一，建议使用小写英文字母、数字、短横线或下划线。

已有 ID 不会因为修改名称而自动改变。开始使用后尽量保持 ID 稳定，因为草稿和购物车靠它识别材料。界面切换英文时，材料名称不会自动翻译，应直接填写适合目标顾客的名称。

2. 上传单颗珠子图片

点击媒体库，选择或上传单颗水晶珠子的图片。建议使用透明背景 PNG 或 WebP，让珠子居中，四周保留少量透明留白。不要用整条手链的照片代替单颗珠子，否则每次添加都会重复显示整张手链图。

图片建议先裁切成比例接近正方形的素材，统一拍摄角度和明暗，避免大面积白底、过多留白或过大的原图。没有图片时，可以通过“无图片时的颜色”“高光”“暗部”生成示意珠子；已经配置但加载失败的图片需要修复，才可正常导出并下单。

优先使用本站媒体库图片。如果图片经由其他域名或 CDN 提供，需允许浏览器跨域读取，否则可能出现“页面能看见图片，但无法导出设计图”的情况。

3. 添加尺寸与单颗价格

点击＋ 添加尺寸，逐行填写规格和价格。尺寸写成 6mm、8mm 或 6.5mm，不要只填写“8”或“8 毫米”。同一种水晶内不要重复填写同一规格。

价格输入框只填数字，货币以店铺设置为准。它代表这一规格每一颗珠子的价格，不是整条手链价格。当前版本同一种水晶的不同尺寸共用一张图片；需要不同图片时，可按业务需要建立不同材料条目。

4. 保存并核对前端

全部填写完成后，点击底部保存水晶，看到保存成功提示再离开。刷新设计页，检查图片、名称、规格和价格是否正确。添加、删除尺寸或删除水晶后，也需要点击保存才能正式生效。

材料价格修改后，已有购物车会按当前材料价格重新计算；删除材料或规格可能让旧购物车无法结账。大幅调整材料前，先核对待处理订单和正在使用的配置。插件没有独立的“每种珠子库存自动扣减”功能，基础商品库存与珠子原料库存应分开管理。

四、把定制器放到网站页面

创建一个专门的页面，例如“设计你的手链”，在需要显示定制器的位置插入下面的短代码：

[crystal_bracelet]

使用 Elementor

1. 打开目标页面并使用 Elementor 编辑。
2. 添加短代码（Shortcode）组件。
3. 粘贴上面的短代码，更新页面。
4. 打开页面的实际前台地址，检查材料列表、画布和设计明细。

使用 WordPress 区块编辑器

添加短代码区块，把同一段短代码粘贴进去，再发布或更新页面。可以输入 /shortcode 快速寻找该区块。编辑器预览不代表实际前台效果，发布后应打开页面核对。

为定制器保留足够宽度，避免放进很窄的侧栏。Elementor 可以调整外围容器、宽度和间距；插件内部的标题、按钮和尺寸说明，应通过“首饰定制”的后台设置修改。

区块操作参考：WordPress 官方 Shortcode 区块说明。

五、修改文案、颜色、字体和 Logo

1. 选择前端语言

进入首饰定制 → 插件设置 → 前端语言，选择 English 或简体中文并保存。默认语言是英文。当前语言由后台统一选择，并不是顾客可自行切换的多语言按钮，也不会自动翻译水晶名称。

2. 修改标题、按钮与尺寸说明

进入首饰定制 → 前端文案。常用文案中可以修改顶部小标题、主标题、副标题、材料区域标题、画布提示、尺寸说明标题与正文，以及预览按钮等内容。“其他按钮、状态及提示”中还能修改保存、加载和错误提示。

英文和中文各有一列，编辑与前端当前语言对应的一列，点击保存前端文案。留空会恢复默认文字，不能借此隐藏该区域。这里接受纯文本与正文换行，不用于插入 HTML 标签。

3. 设置整体颜色

进入首饰定制 → 颜色设置，可调整主色调、文字和主要按钮、整体背景、边框、辅助强调色、画布背景。使用拾色器选择颜色后，点击保存颜色。颜色搭配应保证文字清晰，浅色背景配较深的正文色通常更容易阅读。

4. 分别设置电脑与手机字体

进入首饰定制 → 字体设置。这里提供 26 类文字配置，每一行可以填写电脑字号、手机字号和文字颜色。

例如，可以把“页面主标题”设置为电脑 36px、手机 24px，颜色填 #292B28。字号框只需输入数字；颜色可以使用拾色器，也可以填写 #RRGGBB 或 #RGB 格式。

• 字号和颜色留空，表示使用插件默认值。
• 自定义电脑字号范围是 8–72px，手机字号范围是 8–48px；搜索筛选与目标长度输入框的自定义字号最低为 16px。
• 手机字号在定制工作台自身宽度不超过 630px时生效。因此，电脑端很窄的容器也可能使用紧凑布局。
• 文字颜色在电脑和手机共用；设置过某一类文字颜色后，该类别优先使用这里的颜色。
• 点击保存字体设置生效；点击恢复全部默认字体可重置本页配置。

手机字体不宜一次调得过大，否则卡片、按钮和说明文字会占用更多高度。字体设置不会改变手机端原有的区域显示规则，也不会自动展开隐藏的设计明细。

5. 修改画布中心 Logo

进入首饰定制 → Logo设置，选择“显示文字”“显示图片Logo”或“不显示”。文字可以输入品牌名，并用换行或 \n 分成多行；图片可通过“选择图片”从媒体库上传，建议使用透明背景素材。完成后点击保存Logo设置。

Logo 也会出现在导出的设计图中。中心品牌文字不属于前述 26 类网页文字，内容应在 Logo 设置中修改。每次修改外观后，都建议清缓存并分别查看电脑与手机前台。

六、顾客如何设计一条手链

第 1 步：搜索并添加水晶

顾客可以输入名称或尺寸关键词，再通过水晶类型和尺寸下拉框筛选。这里的“分类”实际按已配置的水晶条目筛选，不是 WooCommerce 的商品分类树。点击一个规格卡片，会添加一颗对应尺寸的珠子；需要多颗时，可以继续点击。

第 2 步：设置目标长度

在“我的设计”中，通过数字输入框或滑块设置目标珠子长度，可选 10–25cm。系统同时显示实际珠子总长度、颗数，以及距目标还差多少或超出多少。

第 3 步：拖动换位，自动排列

1. 按住画布上的一颗珠子，鼠标或手指移动时，珠子会跟随抓取位置移动。
2. 把珠子拖到圆形轨道附近，看到绿色插入位置提示后松开。
3. 系统将珠子插入相应顺序，并根据各颗珠子的大小重新分配圆周间距，避免相互重叠。
4. 如果在圆心、轨道外或画布外松开，珠子会回到原来的位置；操作被中断时也会回位。

松手后的最终位置由圆周排列计算，不保存任意散落坐标。画布会把珠子排列成环；珠子较多时可能整体缩小显示，但实际规格、总长度与价格不变。效果图用于确认搭配和顺序，不是按真实比例测量腕围的图纸。

第 4 步：使用编辑工具

电脑端让画布获得焦点后，也可以使用键盘左右方向键选择珠子，再按 Delete 或 Backspace 删除选中珠子。

第 5 步：查看明细与预估价格

系统会按“材料 + 尺寸”汇总数量，自动计算材料小计。沿用前面的示例，10 颗单价 12 元的紫水晶，加上 10 颗单价 10 元的粉水晶，材料基础合计为 220 元。页面的含税展示取决于店铺设置，最终税费、运费与优惠以结账页为准。

第 6 步：保存、下载或下单

设计过程中会自动保存本机草稿，电脑布局还提供“保存草稿”按钮。草稿保存在当前浏览器，并与当前站点和定制页面相关；不会自动同步到另一部手机或账号，清除浏览器数据后也可能丢失。退出页面前可下载一张设计图作为留存。

点击预览设计，检查设计图、颗数、长度与金额。点击下载设计图可保存 1200 × 1200 像素的 PNG。点击加入购物车会提交当前设计；点击立即购买则在成功加入购物车后前往结账页。打开预览本身不会创建订单或提交购物车。

七、手机端如何操作

手机端采用紧凑布局：上方是设计画布与工具，下方左侧放搜索、分类和尺寸筛选，右侧是可以独立上下滚动的水晶卡片，底部显示总价、设计明细入口和预览按钮。

1. 在下方左侧筛选水晶类型和尺寸。
2. 滚动右侧材料列表，点击想添加的珠子规格。
3. 在上方画布按住珠子，拖到圆轨道的新位置松开。
4. 点击底部设计明细，展开目标长度、材料清单与尺寸说明；再次点击可收起。
5. 点击预览设计，在弹窗中下载图片、加入购物车或立即购买。

手机端的长说明和部分信息默认收起，避免选珠操作被挤到很长的页面下方。桌面上的“保存草稿”按钮不在紧凑布局中单独显示，但自动保存仍然工作。实际一屏能看到多少内容，还会受手机高度、网站顶部导航、文案长度和字号设置影响。

八、购物车、结账与后台订单处理

设计图在哪里查看？

成功加入购物车时，插件将本次设计图保存到网站媒体库，并关联到对应的购物车项目。经典购物车、结账与订单页面已接入设计图展示；区块购物车与区块结账的图片适配使用 WooCommerce 9.6 及以上版本提供的接口。第三方主题若自行改写这些区域，需在实际页面确认显示效果。

每款设计使用自己的图片，不会把基础商品在产品库里的主图永久改成某个顾客的设计。同一购物车中的不同设计也应分别显示对应图片。

商家怎样读取制作信息？

进入WooCommerce → 订单，打开对应订单，在商品项目下核对设计缩略图及以下信息。部分字段以英文名称显示：

制作前应同时核对材料数量、尺寸、排列顺序和完整设计图，并确认顾客的佩戴尺寸、付款状态与配送信息。只看缩略图容易遗漏相似颜色或不同规格的珠子。

结账页出现两张设计图怎么办？

如果主题本身已经显示商品图片，而插件又在商品名称旁补充了缩略图，进入首饰定制 → 前端文案，取消“在经典结账页的商品名称旁显示设计缩略图”并保存。此开关只控制经典结账页的补充图片，不关闭购物车和后台订单图片替换。

九、上线检查与日常维护

完成配置后，建议用一条简单设计走通完整流程，再开放给顾客使用。至少检查以下项目：

• 材料：名称、图片、尺寸和单价正确，没有未替换的演示数据。
• 拖动：电脑鼠标与手机手指都能操作；有效位置能插入，拖出轨道能回位。
• 外观：手机搜索框没有溢出，文字未遮挡按钮，设计明细可以展开。
• 草稿与图片：同一浏览器刷新后能恢复草稿，设计图可以正常下载。
• 购物车：两款不同设计可以同时保留，材料、金额和图片对应正确。
• 结账：用游客与登录账号分别测试，核对配送信息、运费、优惠券和税费。
• 订单：完成测试下单后，后台能够看到设计图、材料清单和排列顺序；确认支付与订单状态按店铺预期流转。

使用缓存插件时，按 WooCommerce 要求排除购物车和结账等动态页面。定制页若长期缓存，可能导致加入购物车的验证信息过期；出现此类问题时，先清除定制页缓存并刷新页面，再调整该页的缓存策略。本站实际主题、支付插件与配送设置仍需要实站验证。

当前版本的几个范围限制

十、常见问题解答

1. 页面直接显示短代码，没有定制器？

先确认插件已经启用，短代码没有拼写错误。Elementor 使用“短代码”组件，WordPress 使用“短代码”区块，不要放进只展示代码的代码区块。清缓存后打开实际前台检查。

2. 能设计，但加入购物车按钮不可用？

依次检查 WooCommerce 是否启用、产品 ID 是否正确、绑定产品是否为已发布的简单产品、价格是否已填写，以及是否有货且可以购买。只安装定制插件，没有完成商城配置时，设计与下载仍可使用。

3. 页面图片正常，为什么下载或下单失败？

先等待材料图片加载完成。若持续失败，检查珠子图片和 Logo 是否仍可访问，是否受到跨域、图片防盗链或 CDN 限制。优先换成本站媒体库图片再试。图像数据过大、服务器上传受限或空间不足，也可能影响加入购物车时的设计图保存。

4. 拖动之后为什么又回去了？

这是圆轨道约束的正常行为。把珠子拖到圆形轨道附近，看到绿色插入提示后松手；在圆心或轨道之外松手，会回到原位置。需要微调顺序时，也可以选中珠子后使用左右移动按钮。

5. 为什么材料比较少，也会排成完整一圈？

画布以完整圆环展示当前搭配，并分配剩余间距。它不会根据空白距离推算缺少多少颗珠子。请以明细中的实际颗数和总长度为准，再由商家确认成品尺寸。

6. 顶部标题或右下角尺寸说明在哪里改？

改内容到“前端文案”；改字号与文字颜色到“字体设置”。还要确认修改的是前端当前使用的语言列。画布中心品牌字则在“Logo设置”中修改。

7. 修改了手机字号，为什么电脑预览没变化？

电脑字号与手机字号分开保存，手机设置只在工作台宽度不超过 630px 时使用。把页面切换到较窄的实际视口检查，同时确认保存成功并清除了缓存。

8. 购物车或后台订单仍显示默认商品图片？

先确认已经更新到 2.2.0，并使用新加入购物车的设计进行测试。检查订单中的 Design Image 链接是否可以打开，相关媒体图片是否仍存在，再核对 WooCommerce 版本和主题的购物车、结账、订单模板。第三方模板完全绕开标准图片接口时，需要针对该模板适配。

9. 旧订单只有设计图链接，能显示缩略图吗？

插件会尝试从已有 Design Image 链接读取图片；图片仍可访问、模板使用对应输出接口时，可以用于显示设计缩略图。已经被删除的设计图片不能仅凭链接恢复。

10. 换手机后为什么没有原来的草稿？

草稿保存在原来的浏览器，不会跨设备同步。可以回到原设备继续编辑；需要留存外观时，先下载设计图片。当前版本没有把设计图片重新导入并还原为可编辑珠子的功能。

11. 为什么改了基础商品价格，定制总价没按预期增加？

定制价格按水晶管理里的单颗价格合计，基础商品价格不会作为额外费用加入。请核对材料单价；如果业务需要固定加工费、包装费或复杂加价规则，应另行配置或开发相应功能。

12. 插件会给所有页面都加载设计器吗？

前端脚本和样式只在输出定制短代码的页面加载。定制页实际体验仍与材料图片大小、服务器速度、主题脚本和设备性能有关。控制素材体积，并在自己的站点上测试真实加载和拖动体验。