shopify-metafields

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Metafields

Metafields allow you to store additional data on Shopify resources (Products, Orders, Customers, Shops) that aren't included in the default schema (e.g., "washing instructions" for a product).

Metafields允许你在Shopify资源（商品、订单、客户、店铺）上存储默认架构中不包含的额外数据（例如商品的「洗涤说明」）。

1. Concepts

1. 基本概念

Namespace: Grouping folder (e.g.,
```
my_app
```
,
```
global
```
).
Key: Specific field name (e.g.,
```
washing_instructions
```
).

Type: Data type (e.g.,

single_line_text_field

number_integer

json

Owner: The resource attaching the data (Product ID, Shop ID).

命名空间（Namespace）：分组文件夹，例如
```
my_app
```
、
```
global
```
。
键（Key）：具体字段名，例如
```
washing_instructions
```
。
类型（Type）：数据类型，例如
```
single_line_text_field
```
、
```
number_integer
```
、
```
json
```
。
所有者（Owner）：挂载数据的资源（商品ID、店铺ID）。

2. Metafield Definitions (Standard)

2. 标准Metafield定义

Always use Metafield Definitions (pinned metafields) when possible. This integrates them into the Admin UI and ensures standard processing.

Create: Settings > Custom Data > [Resource] > Add definition.
Access:
```
namespace.key
```

尽可能使用Metafield定义（固定Metafield），这样可以将它们集成到管理后台UI中，确保处理流程标准化。

创建路径：设置 > 自定义数据 > [对应资源] > 添加定义。
访问方式：
```
namespace.key
```

3. Accessing in Liquid

3. 在Liquid中访问

To display metafield data on the Storefront:

liquid

<!-- Accessing a product metafield -->
<p>Washing: {{ product.metafields.my_app.washing_instructions }}</p>

<!-- Accessing a file/image metafield -->
{% assign file = product.metafields.my_app.size_chart.value %}
<img src="{{ file | image_url: width: 500 }}" />

<!-- Checking existence -->
{% if product.metafields.my_app.instructions != blank %}
   ...
{% endif %}

要在店铺前端展示Metafield数据：

liquid

<!-- Accessing a product metafield -->
<p>Washing: {{ product.metafields.my_app.washing_instructions }}</p>

<!-- Accessing a file/image metafield -->
{% assign file = product.metafields.my_app.size_chart.value %}
<img src="{{ file | image_url: width: 500 }}" />

<!-- Checking existence -->
{% if product.metafields.my_app.instructions != blank %}
   ...
{% endif %}

4. Reading via API (GraphQL)

4. 通过GraphQL API读取

graphql

query {
  product(id: "gid://shopify/Product/123") {
    title
    metafield(namespace: "my_app", key: "instructions") {
      value
      type
    }
  }
}

graphql

query {
  product(id: "gid://shopify/Product/123") {
    title
    metafield(namespace: "my_app", key: "instructions") {
      value
      type
    }
  }
}

5. Writing via API (GraphQL)

5. 通过GraphQL API写入

To create or update a metafield, use

metafieldsSet

graphql

mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

/* Variables */
{
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/123",
      "namespace": "my_app",
      "key": "instructions",
      "type": "single_line_text_field",
      "value": "Wash cold, tumble dry."
    }
  ]
}

要创建或更新Metafield，请使用

metafieldsSet

。

graphql

mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

/* Variables */
{
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/123",
      "namespace": "my_app",
      "key": "instructions",
      "type": "single_line_text_field",
      "value": "Wash cold, tumble dry."
    }
  ]
}

6. Private Metafields

6. 私有Metafields

If you want data to be hidden from other apps and the storefront, use Private Metafields. Note: These cannot be accessed via Liquid directly.

Use
```
privateMetafield
```
queries/mutations.
Requires explicit
```
read_private_metafields
```
/
```
write_private_metafields
```
scope (rarely used now,
```
app_data
```
metafields are preferred for app-specific valid storage).

如果你希望数据对其他应用和店铺前端隐藏，请使用私有Metafields。注意：此类Metafield无法直接通过Liquid访问。

使用
```
privateMetafield
```
查询/变更接口。
需要显式申请
```
read_private_metafields
```
/
```
write_private_metafields
```
权限（目前已很少使用，针对应用专属的可靠存储更推荐使用
```
app_data
```
类型的Metafield）。