如何通过WordPress/WooCommerce API为购物车/订单添加自定义图片附件

核心思路 #

不用第三方插件，通过JS传递图片数据，配合WooCommerce钩子保存自定义元数据，同时可选择优化存储方式避免媒体库膨胀。

方案一：优先JavaScript实现（Base64传递+元数据存储） #

适用于图片尺寸较小的场景，直接将JS生成的图片转为Base64，关联到购物车项并同步到订单。

1. 前端JS传递图片数据到购物车
   假设你用Canvas生成图片，先转成Base64，再通过WooCommerce AJAX添加商品并附带自定义元数据：

// 获取Canvas生成的图片Base64
const customImageBase64 = document.getElementById('your-canvas').toDataURL('image/png');

// 调用WooCommerce添加购物车接口，携带自定义图片数据
jQuery.post(wc_add_to_cart_params.wc_ajax_url.replace('%%endpoint%%', 'add_to_cart'), {
    product_id: 123, // 替换为你的商品ID
    quantity: 1,
    custom_user_image: customImageBase64
}, function(res) {
    if (!res.error) {
        // 更新购物车UI
        jQuery(document.body).trigger('wc_fragment_refresh');
    }
});

2. PHP端钩子保存元数据
   添加WooCommerce钩子，接收并保存自定义数据到购物车，同步到订单：

// 保存购物车项的自定义图片数据
add_filter('woocommerce_add_cart_item_data', 'store_custom_image_cart_data', 10, 2);
function store_custom_image_cart_data($cart_item_data, $product_id) {
    if (isset($_POST['custom_user_image'])) {
        // 生成唯一键，避免相同商品合并时丢失自定义数据
        $cart_item_data['custom_image'] = [
            'data' => sanitize_text_field($_POST['custom_user_image']),
            'unique_key' => md5(microtime() . rand())
        ];
    }
    return $cart_item_data;
}

// 将购物车数据同步到订单订单项
add_action('woocommerce_checkout_create_order_line_item', 'attach_image_to_order_item', 10, 4);
function attach_image_to_order_item($item, $cart_item_key, $values, $order) {
    if (isset($values['custom_image']['data'])) {
        // 后台订单显示友好说明，如需存储原始Base64可改用隐藏元数据（_前缀）
        $item->add_meta_data('用户自定义图片', '已关联专属自定义图片', true);
        // 如需存储原始数据：$item->add_meta_data('_custom_image_base64', $values['custom_image']['data'], false);
    }
}

方案二：优化存储（避免Base64/媒体库膨胀） #

如果图片尺寸较大，可将Base64转为文件存储到服务器自定义目录，而非WordPress媒体库：

1. 前端JS上传Base64到服务器
   先发送AJAX将图片保存到服务器，拿到文件路径后再添加到购物车：

jQuery.post('/wp-admin/admin-ajax.php', {
    action: 'save_custom_image_to_server',
    image_data: customImageBase64,
    product_id: 123
}, function(res) {
    if (res.success) {
        // 用返回的文件路径添加商品到购物车
        jQuery.post(wc_add_to_cart_params.wc_ajax_url.replace('%%endpoint%%', 'add_to_cart'), {
            product_id: 123,
            quantity: 1,
            custom_image_path: res.data.path
        });
    }
});

2. PHP端处理文件存储
   创建自定义目录保存图片，返回相对路径：

add_action('wp_ajax_save_custom_image_to_server', 'save_custom_image_to_server');
add_action('wp_ajax_nopriv_save_custom_image_to_server', 'save_custom_image_to_server');
function save_custom_image_to_server() {
    if (!isset($_POST['image_data'])) {
        wp_send_json_error('缺少图片数据');
    }

    // 处理Base64数据
    $imageData = str_replace('data:image/png;base64,', '', $_POST['image_data']);
    $imageData = str_replace(' ', '+', $imageData);
    $imageBlob = base64_decode($imageData);

    // 创建自定义存储目录（wp-content/uploads/custom-images/）
    $uploadDir = wp_upload_dir();
    $customDir = $uploadDir['basedir'] . '/custom-images/';
    if (!file_exists($customDir)) mkdir($customDir, 0755, true);

    // 生成唯一文件名
    $fileName = 'user-custom-' . md5(microtime()) . '.png';
    $filePath = $customDir . $fileName;

    if (file_put_contents($filePath, $imageBlob)) {
        $relativePath = '/wp-content/uploads/custom-images/' . $fileName;
        wp_send_json_success(['path' => $relativePath]);
    } else {
        wp_send_json_error('图片保存失败');
    }
}

3. 同步文件路径到订单
   修改之前的订单钩子，存储文件路径并在后台显示：

add_action('woocommerce_checkout_create_order_line_item', 'attach_image_path_to_order', 10, 4);
function attach_image_path_to_order($item, $cart_item_key, $values, $order) {
    if (isset($values['custom_image_path'])) {
        $item->add_meta_data('自定义图片链接', '<a href="' . esc_url($values['custom_image_path']) . '" target="_blank">查看图片</a>', true);
    }
}

方案三：轻量存储（仅保存生成参数） #

如果不需要长期存储图片，可只保存用户的地理生成参数，查看订单时重新渲染图片：

• 前端JS将地理坐标、生成配置等参数传给购物车
• PHP端将参数保存到订单元数据
• 后台查看订单时，用这些参数通过JS重新生成图片展示

关键注意事项 #

• 购物车合并问题：用unique_key确保相同商品但不同自定义图片的购物车项不被合并
• 数据大小限制：Base64数据过长可能超出数据库字段限制，优先用方案二的文件存储
• 后台显示优化：可通过woocommerce_admin_order_item_values钩子自定义元数据的展示样式

内容的提问来源于stack exchange，提问作者d1nkum