如何在网站上添加实时金价小组件

您要嵌入的是什么

MetalAPI 小组件是由 MetalAPI 为您托管的小型价格看板。您只需在控制台中配置一次，将两行代码片段粘贴到页面中，访问者就能看到黄金、白银、铂金、钯金、工业金属、能源、货币或加密货币的当前价格。小组件在由 metalapi.com 提供的 iframe 中渲染。您无需编写后端代码，HTML 中不会出现 API 密钥，价格变动时您这边也无需做任何更新。

因此，对于希望在自身内容旁边显示当前价格的内容网站、珠宝和贵金属商店、新闻页面和博客来说，小组件是最快捷的方案。如果您需要在自己的页面结构中使用价格，或者要用价格进行计算，REST API 会更合适。本文最后一节会介绍这种情况。

小组件的流量由 MetalAPI 的小组件端点提供，而不经过您的 API 密钥，因此页面浏览不会消耗您的每月请求配额。您的套餐决定了可以保存多少个小组件以及价格的新鲜程度，下文会分别介绍。

在控制台中创建小组件

所有套餐都包含小组件，Free 套餐也不例外。创建账户后，在控制台中打开 Widgets 并点击 New widget。构建器会在表单旁边显示实时预览，方便您在保存之前尝试各种选项：

有两个细节容易被忽略。如果单位保持为金衡盎司，工业金属会改用其市场惯用单位显示，因此铜按磅计价，而黄金仍按金衡盎司计价。另外，克或千克单位只会换算金属：货币、能源和加密货币保持各自的单位。如果不确定访问者习惯哪种重量单位，可以参阅单位换算指南，其中解释了各单位之间的区别。

保存后，小组件会获得一个公开 ID，例如 w_abc123。嵌入代码只引用这个 ID，配置保存在 MetalAPI 的服务器上。之后当您修改品种、颜色或布局时，所有嵌入了该小组件的页面在下次加载时都会显示新版本，网站上的代码片段无需任何改动。小组件列表中还有一个 Live 开关，可以在不删除小组件的情况下将其下线，并且每个小组件都有浏览次数统计。

逐行解读嵌入代码

保存后，构建器会显示嵌入代码：

<div id="metalapi-widget-w_abc123"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

该脚本是一个小型加载器，压缩前约 4 KB。它读取 data-widget，查找 id 为 metalapi-widget-<id> 的元素，并在其中填入一个加载 https://metalapi.com/embed/<id> 的 iframe。如果找不到容器，加载器会直接在 script 标签之前创建一个。框架内的小组件会通过 postMessage 报告自身高度，加载器据此调整 iframe 的大小，因此即使表格从三行增加到六行，也绝不会出现滚动条。

即使 script 标签在页面中出现多次，加载器也只会运行一次。如需在同一页面中显示多个小组件，只引入一次脚本，并为每个容器添加 data-metalapi-widget 属性来代替 id：

<div data-metalapi-widget="w_abc123"></div>
<div data-metalapi-widget="w_def456"></div>

<script src="https://metalapi.com/js/widget.js" async></script>

加载器只在页面加载完成时查找一次这些容器，之后由客户端 JavaScript 添加的容器（例如单页应用中切换路由之后添加的容器）它是看不到的。在这种情况下，或者在完全无法添加脚本的地方，请直接嵌入框架：

<iframe
  src="https://metalapi.com/embed/w_abc123"
  title="Live gold price"
  loading="lazy"
  style="border:0;width:100%;height:220px"
></iframe>

没有加载器时，iframe 无法自动调整大小，因此请为它设置一个适合所选布局的高度。仍在使用上一代小组件生成器中 new MetalAPIWidget({...}) 代码片段的页面可以继续正常工作：已保存的小组件按其 ID 渲染，旧代码片段中残留的 API 密钥会被忽略。

纯 HTML、WordPress 和 Shopify

纯 HTML。 将代码片段粘贴到小组件应显示的位置，例如侧边栏或价格页面顶部。由于带有 async 属性，加载器在下载期间绝不会阻塞页面其余部分的渲染。

WordPress。 在区块编辑器中添加一个 Custom HTML（自定义 HTML）区块并粘贴代码片段。如果要在每个页面上显示小组件，可以把它放在侧边栏或页脚小工具区域的 Custom HTML 小工具中，或者放进主题的模板文件里。有些环境（例如多站点网络或受限的主机套餐）会从内容中移除 <script> 标签。如果发布后小组件没有出现，请查看页面源代码；如果其中缺少 script 标签，请改用无需脚本的 iframe 版本。

Shopify。 在主题编辑器（Online Store → Themes → Customize）中，向需要显示小组件的模板添加一个 Custom Liquid（自定义 Liquid）分区或区块，然后粘贴代码片段。如果只想在商品页面上显示，请将该区块添加到商品模板中。编辑主题代码时，您也可以直接把代码片段放进分区文件中。

其他建站工具。 带有 HTML 或嵌入元素的建站工具用法相同，例如 Webflow 的代码嵌入或 Squarespace 的代码块。有些建站工具会把自定义 HTML 再包裹在它们自己的 iframe 中，这时自动调整高度的功能将无法穿透。在这种情况下，请为嵌入元素设置固定高度。

套餐限制、时效性与品牌标识

已保存的小组件所显示价格的时效性取决于其所有者的套餐，并且会自行轮询新数据。轮询间隔跟随套餐的更新间隔，但最短不少于 30 秒，最长不超过 15 分钟：

在 Free 和 Lite 套餐中，小组件检查新数据的频率高于价格变化的频率，因此无需刷新页面就能获取每次更新。每个小组件都会在底部以 UTC 时间显示数据时间，让访问者了解价格的新鲜程度。各套餐的完整功能列表请参见定价页面。

性能与布局偏移

小组件对页面的影响微乎其微：

• 非阻塞脚本。 加载器以 async 方式加载，并设置了一小时的浏览器缓存，因此回访用户通常无需重新下载。
• 延迟加载框架。 加载器创建 iframe 时使用 loading="lazy"，因此位于页面下方的小组件只有在访问者滚动到附近时才会加载。
• 相互隔离。 小组件运行在独立的框架中。您的样式表无法破坏它，它的代码也无法触及您的页面。
• 可放心使用页面缓存。 代码片段永远不变，价格在框架内部加载。WordPress 缓存插件、Shopify 的 CDN 或任何其他整页缓存都可以随意长时间缓存您的 HTML，而不会把价格冻结住。

唯一需要提前考虑的是布局偏移。框架初始高度为 120 像素，随后会增长到小组件的实际高度，这可能会把下方的内容往下推。请参照构建器预览中显示的高度，为容器设置最小高度，提前预留空间：

<div id="metalapi-widget-w_abc123" style="min-height:240px"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

滚动行情条所需的空间远小于包含八种金属的表格，因此请为每个小组件单独设置这个值，而不是使用全站统一的默认值。

何时改用 API

小组件是一个现成的组件。当您需要小组件做不到的事情时，请使用 API：

• 在您自己的 HTML 中显示价格。 iframe 中的文本属于另一个文档，搜索引擎可能不会将其视为您页面的一部分。如果价格应当成为页面内容的一部分，请在服务器端渲染。
• 自定义设计。 小组件提供四种布局、主题和强调色。超出这些范围的需求，请编写您自己的页面结构。
• 计算。 基于重量和纯度的商品价格、回购报价和换算都应在您的服务器上完成。首饰价格计算器教程对此进行了完整演示。
• 在应用中使用数据。 图表、历史数据和价格存储需要使用 API 文档中介绍的历史价格和时间区间端点。

请从服务器调用 API，并按您套餐的更新间隔缓存每个响应。在 WordPress 中，一个带 transient 缓存的短代码只需几行就能同时做到这两点：

<?php
// 在 wp-config.php 中：define('METALAPI_KEY', 'mk_live_...');
add_shortcode('gold_price', function ($atts) {
    $a = shortcode_atts(['currency' => 'USD', 'unit' => 'troy_oz'], $atts);
    $currency = strtoupper(preg_replace('/[^A-Za-z]/', '', $a['currency']));
    $unit = sanitize_key($a['unit']);
    $cache_key = "metalapi_xau_{$currency}_{$unit}";

    $data = get_transient($cache_key);
    if ($data === false) {
        $url = add_query_arg(
            ['base' => $currency, 'currencies' => 'XAU', 'unit' => $unit],
            'https://metalapi.com/api/v1/latest'
        );
        $res = wp_remote_get($url, ['headers' => ['X-API-Key' => METALAPI_KEY], 'timeout' => 10]);
        if (is_wp_error($res)) return '';
        $data = json_decode(wp_remote_retrieve_body($res), true);
        if (empty($data['success'])) return '';
        set_transient($cache_key, $data, 10 * MINUTE_IN_SECONDS); // 您套餐的更新间隔
    }

    $price = $data['rates'][$currency . 'XAU'] ?? null;
    if ($price === null) return '';
    return sprintf(
        '<span class="gold-price">%s %s / %s</span>',
        esc_html(number_format_i18n($price, 2)),
        esc_html($currency),
        esc_html(str_replace('_', ' ', $unit))
    );
});

在任意文章或页面中以 [gold_price currency="EUR" unit="gram"] 的形式使用即可。响应中的键名是基础货币加上品种代码，因此 rates.EURXAU 就是每克黄金的欧元价格。每次缓存未命中会消耗 1 次请求，因此对于您显示的每种货币和单位组合，10 分钟的 transient 缓存每月最多约消耗 4,500 次请求，Standard 套餐完全够用。

如果必须从浏览器调用 API，请先按照身份验证指南中的说明，将密钥限制为仅供您自己的域名使用。不过，如果只是单纯显示价格，小组件仍然是更简单的选择：无需密钥，无需管理缓存，以后更换品种时也无需任何维护。