利用 Google Chart API 生成 QR Code 名片：完整實現與 vCard 規範解析

QR Code（快速響應碼）作為矩陣式二維碼，憑藉大容量、強容錯、支持中文等優勢，成為行業標準。本文展示如何調用 Google Chart API 快速生成包含 vCard 格式聯繫信息的二維碼，並深入解析 vCard 結構與中文編碼陷阱。

重要提示：Google Chart API（chart.apis.google.com）已於 2019 年正式停止服務。生產環境請改用本地庫（如 BaconQrCode、Endroid QrCode）或其他可用 API 服務。本文代碼僅供學習 vCard 結構與參數含義參考。

核心生成函數

<?php
/**
 * 生成 Google Chart API QR Code 圖片標籤（教學用）
 * @param string $chl 編碼後的內容
 * @param int $size 圖片寬高(像素)
 * @param string $ec_level 容錯級別 L|M|Q|H
 * @param int $margin 邊距
 * @return string img 標籤
 */
function generateQRfromGoogle($chl, $size = 150, $ec_level = 'L', $margin = 0) {
    $params = http_build_query([
        'chs' => "{$size}x{$size}",
        'cht' => 'qr',
        'chld' => "{$ec_level}|{$margin}",
        'chl' => $chl,
    ]);
    return '<img src="https://chart.googleapis.com/chart?' . $params . '" alt="QR Code" width="' . $size . '" height="' . $size . '" />';
}

// === vCard 3.0 標準構建 ===
$vcard = [
    'FN' => '張三豐',           // 全名
    'TEL;TYPE=CELL,VOICE' => '138-0000-0000', // 手機
    'TEL;TYPE=WORK,VOICE' => '010-88888888',  // 座機
    'EMAIL;TYPE=PREF,INTERNET' => 'zhangsf@example.com',
    'URL' => 'https://example.com',
    'ORG' => '武當派',
    'TITLE' => '掌門',
    'ADR;TYPE=WORK,POSTAL' => '湖北十堰武當山; ; ; ; 442000; 中國',
    'NOTE' => '道法自然',
];

// 組裝 vCard 字符串（每行以 \n 分隔，最後需 END:VCARD）
$vcardLines = ['BEGIN:VCARD', 'VERSION:3.0'];
foreach ($vcard as $key => $val) {
    $vcardLines[] = $key . ':' . $val;
}
$vcardLines[] = 'END:VCARD';
$vcardString = implode("\n", $vcardLines);

// URL 編碼（關鍵！必須 UTF-8 → urlencode）
$encoded = urlencode($vcardString);

// 輸出圖片
echo generateQRfromGoogle($encoded, 200, 'M', 1);
?>

vCard 關鍵字段對照表

容錯級別選擇指南

• L (Low, 7%)：默認，適合乾淨環境（屏幕展示、打印質量高）。
• M (Medium, 15%)：推薦通用，兼顧容量與容錯。
• Q (Quartile, 25%)：有 Logo 覆蓋、戶外貼紙、可能污損場景。
• H (High, 30%)：極端惡劣環境，但數據容量最小。

中文編碼陷阱與解決

Windows 記事本默認 ANSI（GBK），直接保存 PHP 文件會導致中文在 urlencode() 時產生錯誤編碼，掃描出來亂碼。

• 解決：編輯器統一設置為 UTF-8 無 BOM 保存（VS Code、PhpStorm、Sublime 均默認支持）。
• 驗證：生成二維碼後用手機掃描，檢查聯繫人姓名、地址是否正確顯示中文。

本地化替代方案推薦

<?php
// 使用 Endroid QrCode (composer require endroid/qr-code)
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;

$qrCode = new QrCode($vcardString);
$qrCode->setSize(300)
       ->setMargin(10)
       ->setErrorCorrectionLevel('M');

$writer = new PngWriter();
$result = $writer->write($qrCode);

// 直接輸出圖片
header('Content-Type: ' . $result->getMimeType());
echo $result->getString();

// 或保存文件
// $result->saveToFile(__DIR__ . '/vcard.png');
?>

本地庫優勢：無外部依賴、支持 Logo 嵌入、可自定義顏色/圓點樣式、生成 SVG/EPS 矢量格式、無請求頻率限制。