如何通过Checkout UI Extensions在Shopify订单提交前添加Metafield/属性

我想把通过Checkout UI Extensions实现的自定义内容（比如代码里的增值税号）作为元字段（Metafield）或订单属性添加到订单中，让它显示在订单的附加详情区域。下面是我当前的自定义代码，请问该怎么实现这个需求？

import React, { useState } from 'react';
import {
  useExtensionApi,
  render,
  TextField,
} from '@shopify/checkout-ui-extensions-react';

render('Checkout::Dynamic::Render', () => <App />);

function App() {
  const { extensionPoint } = useExtensionApi();
  const [vatNumber, setVatNumber] = useState('');

  const handleVatNumberChange = (val) => {
    setVatNumber(val)
  }

  return (
    <>
      <TextField
        label="VAT Number (Optional)"
        name="vat_number"
        value={vatNumber}
        onChange={(val) => handleVatNumberChange(val)}
      />
    </>
  );
}

可以实现，以下是两种可行方案： #

方案1：存入订单属性（推荐，自动显示在附加详情区）

订单属性会自动同步到最终订单，且默认显示在Shopify后台订单的「附加详情」区域，无需额外配置。修改代码如下：

import React, { useState } from 'react';
import {
  useCart,
  render,
  TextField,
} from '@shopify/checkout-ui-extensions-react';

render('Checkout::Dynamic::Render', () => <App />);

function App() {
  const { updateAttributes } = useCart();
  const [vatNumber, setVatNumber] = useState('');

  const handleVatNumberChange = (val) => {
    setVatNumber(val);
    // 将输入值同步为购物车属性，最终会带入订单
    updateAttributes({ vat_number: val || undefined });
  };

  return (
    <>
      <TextField
        label="增值税号（可选）"
        name="vat_number"
        value={vatNumber}
        onChange={(val) => handleVatNumberChange(val)}
      />
    </>
  );
}

关键说明：

• 引入useCart钩子获取updateAttributes方法，用于修改购物车属性
• 输入值变化时，调用updateAttributes将vat_number作为属性存入购物车，购物车属性会自动同步到生成的订单中
• 清空输入时传入undefined，避免存入空值

方案2：存入订单元字段

如果需要使用元字段存储，需先完成前置配置：

1. 登录Shopify后台，进入「设置」→「元字段」→「订单」，创建新的元字段定义：
   • 命名空间：比如custom
   • 键：vat_number
   • 类型：单行文本
   • 勾选在订单详情页显示

修改代码如下：

import React, { useState } from 'react';
import {
  useCart,
  render,
  TextField,
} from '@shopify/checkout-ui-extensions-react';

render('Checkout::Dynamic::Render', () => <App />);

function App() {
  const { updateMetafields } = useCart();
  const [vatNumber, setVatNumber] = useState('');

  const handleVatNumberChange = (val) => {
    setVatNumber(val);
    // 更新订单元字段，需匹配后台创建的命名空间和键
    updateMetafields([
      {
        namespace: 'custom',
        key: 'vat_number',
        value: val || '',
        type: 'string',
      },
    ]);
  };

  return (
    <>
      <TextField
        label="增值税号（可选）"
        name="vat_number"
        value={vatNumber}
        onChange={(val) => handleVatNumberChange(val)}
      />
    </>
  );
}

关键说明：

• 元字段需要先在后台配置定义，否则无法写入
• 使用updateMetafields方法传入元字段数组，需严格匹配后台设置的命名空间、键和类型
• 若要在订单详情显示，必须在后台配置时勾选对应选项

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