建材产品可视化器

一款面向地板、墙板和栅栏产品的轻量级可视化选型页面。客户可以依次选择产品类别、系列、型号和纹理颜色，通过项目场景大图直观查看不同产品的应用效果，并进一步申请免费样品或项目报价。

项目使用纯 HTML + CSS + JavaScript 开发，无 React、TypeScript、Node.js 依赖和构建工具。解压后即可本地预览，也可以作为 WordPress 页面模板或动态产品系统的前端基础。

项目特点

• 支持地板、墙板、栅栏三类产品
• 支持产品系列、型号、颜色和场景联动
• 内置 7 个产品系列和 21 个演示型号
• 每个型号可独立配置 2–9 种颜色
• 每种颜色可独立配置 1–4 张项目场景图
• 场景大图、缩略图和全屏预览同步切换
• 1–4 张缩略图始终保持统一宽度，不会自动拉伸
• 支持复制当前产品选择链接
• 包含免费样品和项目报价演示表单
• 适配电脑端、平板端和手机端
• 产品数据、页面样式和交互逻辑相互分离

当前版本包含 88 张 PNG 产品场景图。加上 3 张分类图和 9 张色卡图，整个项目共使用 100 张图片素材。

产品结构

产品类别	产品系列	演示型号
地板	共挤系列	DF-01、DF-02、DF-03
地板	3D 木纹系列	DW-01、DW-02、DW-03
墙板	共挤系列	CW-01、CW-02、CW-03
墙板	3D 木纹系列	WW-01、WW-02、WW-03
墙板	磨砂系列	MW-01、MW-02、MW-03
栅栏	隐私围栏	PF-01、PF-02、PF-03
栅栏	栅栏门	FG-01、FG-02、FG-03

当前型号、产品说明、颜色名称及图片均为演示内容，正式使用前请替换为真实产品资料。

技术栈

• HTML5
• CSS3
• 原生 JavaScript
• PNG 产品场景图
• SVG 分类图与纹理色卡

项目不依赖第三方前端框架，也不需要安装任何软件包。

目录结构

product-visualizer-html-v1.4.1/
├── index.html
├── README.md
├── css/
│   └── visualizer.css
├── js/
│   ├── visualizer-data.js
│   └── visualizer.js
└── images/
    ├── categories/              # 产品分类图片
    ├── swatches/                # 纹理色卡图片
    └── products/                # 产品场景图片
        └── 型号ID/
            └── 颜色ID/
                ├── project01.png
                ├── project02.png
                └── ...

本地预览

方法一：直接打开

解压项目后，双击根目录中的 index.html。

方法二：使用本地服务器

在项目根目录运行：

python -m http.server 8080

然后在浏览器访问：

http://localhost:8080

如果浏览器限制本地文件加载，建议使用第二种方式。

产品图片管理

图片目录规则

每张项目场景图按“型号 ID / 颜色 ID / 图片序号”存放：

images/products/型号ID/颜色ID/project序号.png

例如：

images/products/df-01/teak/project01.png
images/products/df-01/teak/project02.png

推荐图片规格：

项目	建议值
图片格式	PNG
图片尺寸	960 × 540 px
图片比例	16:9
文件名称	project01.png～project04.png
单个颜色图片数量	1–4 张

替换现有图片

如果图片数量不变，直接使用新的 PNG 图片覆盖同名文件即可，不需要修改 HTML、CSS 或 JavaScript。

增加或减少图片

如果某个颜色的图片数量发生变化，需要同时修改 js/visualizer-data.js 中对应颜色的 projects：

{
  id: "df-01",
  name: "DF-01",
  profile: "宽板地板",
  colors: [
    { id: "teak", projects: 2 },
    { id: "coffee", projects: 1 },
    { id: "cedar", projects: 2 }
  ]
}

字段说明：

字段	作用
id	颜色 ID，必须与全局 finishes 中的颜色 ID 一致
projects	当前颜色拥有的项目场景图数量，可设置为 1–4

例如：

{ id: "teak", projects: 2 }

表示需要准备：

images/products/df-01/teak/project01.png
images/products/df-01/teak/project02.png

图片必须从 project01.png 开始连续编号，中间不能缺号。

修改产品图片根目录

产品图片根目录在 js/visualizer-data.js 中统一设置：

productImageBase: "images/products"

如果以后将图片迁移到其他目录或 CDN，只需修改这一项。

修改产品数据

产品类别、系列、型号、颜色、场景顺序和颜色筛选项统一保存在：

js/visualizer-data.js

新增型号

在对应系列的 models 数组中添加型号，并为该型号配置实际拥有的颜色：

{
  id: "df-04",
  name: "DF-04",
  profile: "新款地板",
  colors: [
    { id: "teak", projects: 2 },
    { id: "stone-grey", projects: 1 }
  ]
}

然后创建对应图片目录：

images/products/df-04/teak/
images/products/df-04/stone-grey/

页面会根据当前型号自动显示其实际配置的颜色，并根据 projects 自动生成 1–4 张缩略图。

程序结构支持每个型号配置 2–9 种颜色；当前演示数据根据实际素材精简为每个型号 2–3 种颜色。

修改分类图片

修改对应类别的 image：

{
  id: "decking",
  name: "地板",
  image: "images/categories/decking.svg"
}

修改色卡图片

修改 finishes 中对应颜色的 image：

{
  id: "teak",
  name: "柚木色",
  sku: "09",
  groups: ["browns", "neutrals"],
  color: "#a96f45",
  image: "images/swatches/teak.svg"
}

其中：

• name：前台显示的颜色名称
• groups：颜色所属筛选分组
• color：图片加载失败时可使用的基础颜色值
• image：色卡图片路径
• sku：预留给表单或后端的数据字段，当前色卡界面不显示色号

核心文件说明

文件	作用	后期是否常改
index.html	页面结构和弹窗容器	较少
css/visualizer.css	页面样式与响应式布局	按设计调整
js/visualizer-data.js	产品数据、颜色配置和图片根目录	经常
js/visualizer.js	页面联动、图片切换、链接和表单逻辑	较少
images/categories/	产品分类图片	按需替换
images/swatches/	纹理色卡图片	按需替换
images/products/	产品项目场景图	经常

部署到普通网站

将完整项目目录上传到网站，例如：

/product-visualizer/

然后访问：

https://www.example.com/product-visualizer/

上传时必须保留现有目录结构，否则 CSS、JavaScript 和图片路径会失效。

WordPress 接入

当前版本已将 HTML、CSS、产品数据、交互逻辑和图片素材分离，适合作为 WordPress 页面模板、模板部件或短代码的前端基础。

建议按以下顺序改造：

1. 将 index.html 的页面主体放入 WordPress 页面模板。
2. 使用 wp_enqueue_style() 引入 CSS。
3. 先引入 visualizer-data.js，再引入 visualizer.js。
4. 将产品数据迁移到自定义文章类型、分类法或 ACF 字段。
5. 使用 wp_localize_script() 或 REST API 输出相同结构的数据。
6. 将样品和报价表单接入 WordPress AJAX 或 REST API。

functions.php 资源引入示例

function enqueue_product_visualizer_assets() {
    $theme_uri = get_template_directory_uri();

    wp_enqueue_style(
        'product-visualizer',
        $theme_uri . '/product-visualizer/css/visualizer.css',
        array(),
        '1.4.1'
    );

    wp_enqueue_script(
        'product-visualizer-data',
        $theme_uri . '/product-visualizer/js/visualizer-data.js',
        array(),
        '1.4.1',
        true
    );

    wp_enqueue_script(
        'product-visualizer',
        $theme_uri . '/product-visualizer/js/visualizer.js',
        array('product-visualizer-data'),
        '1.4.1',
        true
    );
}
add_action('wp_enqueue_scripts', 'enqueue_product_visualizer_assets');

实际目录不在当前主题中时，请根据部署位置调整 $theme_uri 和资源路径。

表单说明

免费样品和项目报价表单目前仅用于演示前端交互，提交后不会发送邮件，也不会写入数据库。

正式上线前至少需要补充：

• 后端提交接口
• 服务端字段验证和数据清理
• WordPress Nonce 校验
• 邮件通知或询盘入库
• 防垃圾提交和提交频率限制
• 隐私政策及用户授权说明

不要仅依赖浏览器端验证处理正式询盘数据。

使用注意事项

• 当前产品场景图由 SVG 示意场景转换为 PNG，仅用于功能演示。
• 删除图片前，应先检查 visualizer-data.js 中是否仍在引用。
• 型号 ID、颜色 ID、目录名称和 projects 数量必须保持一致。
• 屏幕显示颜色会受到设备、亮度及色彩设置影响，最终颜色应以实物样品为准。
• 嵌入 WordPress 后，应检查主题全局 CSS 是否影响本页面。
• 更新 CSS 或 JavaScript 后，可同步修改 WordPress 资源版本号以刷新浏览器缓存。

版本说明

当前版本：v1.4.1

本版主要完成：

• 保留 21 个演示型号
• 支持每个型号独立配置 2–9 种颜色
• 支持每种颜色独立配置 1–4 张项目场景图
• 产品场景图由 756 张精简为 88 张
• 全项目图片素材控制为 100 张
• 场景图统一使用 project01.png～project04.png 命名
• 删除场景名称、序号和前台颜色编号等冗余文字
• 固定桌面端缩略图宽度
• 手机端缩略图使用固定宽度并支持横向滑动

许可说明

本项目可用于学习、内部测试和企业网站二次开发。正式商用前，请确认品牌名称、产品资料、图片和纹理素材拥有合法使用权限。