Back to Details

shopify-extensions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify Extensions Guide

Shopify Extensions 开发指南

This skill provides a comprehensive guide to building Shopify Extensions. Extensions allow you to integrate your app's functionality directly into Shopify's user interfaces (Admin, Checkout, Online Store, POS) and backend logic.
本教程提供了构建Shopify Extensions的完整指南。扩展允许你将应用功能直接集成到Shopify的用户界面（Admin、Checkout、在线商店、POS）和后端逻辑中。

📚 Official References (Latest)

📚 最新官方参考资料

🛠️ Prerequisites

🛠️ 前置要求

  • Shopify CLI: Ensure you are using the latest version of Shopify CLI.
    bash
    npm install -g @shopify/cli@latest
  • Shopify App: Extensions must be part of a Shopify App.
  • Shopify CLI: 确保你使用的是最新版本的Shopify CLI。
    bash
    npm install -g @shopify/cli@latest
  • Shopify 应用: 扩展必须属于某个Shopify应用的一部分。

🚀 Common Extension Types

🚀 常见扩展类型

1. Admin UI Extensions

1. Admin UI 扩展

Embed your app into the Shopify Admin interface.
  • Action Extensions: Add transactional workflows (modals) to resource pages (Orders, Products, Customers).
    • Usage: "More actions" menu.
  • Block Extensions: Embed contextual information as cards directly on resource pages.
    • Usage: Inline cards on Product/Order details.
  • Configuration: Defined in 
    shopify.extension.toml
    .
    toml
    [[extensions]]
type = "ui_extension"
name = "product-action"
handle = "product-action"

[[extensions.targeting]]
target = "admin.product-details.action.render"
module = "./src/ActionExtension.jsx"
将你的应用嵌入Shopify Admin界面。
  • 操作扩展: 为资源页面（订单、商品、客户）添加事务工作流（弹窗）。
    • 使用场景: "更多操作"菜单。
  • 区块扩展: 以卡片形式将上下文信息直接嵌入资源页面。
    • 使用场景: 商品/订单详情页的内嵌卡片。
  • 配置: 在
    shopify.extension.toml
    中定义。
    toml
    [[extensions]]
type = "ui_extension"
name = "product-action"
handle = "product-action"

[[extensions.targeting]]
target = "admin.product-details.action.render"
module = "./src/ActionExtension.jsx"

2. Checkout UI Extensions

2. Checkout UI 扩展

Customize the checkout flow (requires Shopify Plus for some features).
  • Targets: Information, Shipping, Payment, Order Summary, Thank You Page, Order Status Page.
  • Capabilities:
    • Show banners/upsells.
    • Collect additional data (attributes).
    • Validate input.
  • UI Components: Use Shopify's restricted component library (Banner, Button, TextField, etc.) for security and performance.
  • Example Configuration:
    toml
    [[extensions]]
type = "ui_extension"
name = "checkout-banner"
handle = "checkout-banner"

[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./src/CheckoutBanner.jsx"
自定义结账流程（部分功能需要Shopify Plus版本支持）。
  • 挂载目标: 信息页、配送页、支付页、订单摘要、感谢页、订单状态页。
  • 能力:
    • 展示横幅/加购推荐。
    • 收集额外数据（属性）。
    • 验证输入内容。
  • UI组件: 使用Shopify的受限组件库（Banner、Button、TextField等）保障安全和性能。
  • 配置示例:
    toml
    [[extensions]]
type = "ui_extension"
name = "checkout-banner"
handle = "checkout-banner"

[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./src/CheckoutBanner.jsx"

3. Theme App Extensions

3. 主题应用扩展

Integrate with Online Store 2.0 themes without modifying theme code.
  • App Blocks: Reusable UI blocks merchants can add to templates.
  • App Embed Blocks: Floating elements or global scripts/styles (e.g., chat widgets).
  • Assets: CSS/JS files are scoped to the extension.
无需修改主题代码即可与Online Store 2.0主题集成。
  • 应用区块: 商家可添加到模板的可复用UI区块。
  • 应用嵌入区块: 浮动元素或全局脚本/样式（例如聊天组件）。
  • 资源: CSS/JS文件的作用域仅限当前扩展。

4. specialized Extensions

4. 特殊扩展

  • Shopify Functions: Backend logic for discounts, shipping, and payment methods (replaces Shopify Scripts).
  • Post-Purchase Extensions: Add pages between checkout and thank you page (e.g., one-click upsells).
  • Web Pixels: Securely subscribe to behavioral events for analytics.
  • POS UI Extensions: Custom tiles and modals for Shopify POS.
  • Shopify Functions: 用于实现折扣、配送和支付方式的后端逻辑（替代Shopify Scripts）。
  • 购后扩展: 在结账页和感谢页之间添加自定义页面（例如一键加购）。
  • Web Pixels: 安全订阅用户行为事件用于数据分析。
  • POS UI 扩展: 为Shopify POS自定义磁贴和弹窗。

💻 CLI Extension Creation

💻 用CLI创建扩展

The 
shopify app generate extension
command is the primary way to create new extensions.
shopify app generate extension
命令是创建新扩展的主要方式。

Basic Usage

基础用法

bash
shopify app generate extension
This runs an interactive wizard where you select the extension type and name.
bash
shopify app generate extension
该命令会启动交互式向导，你可以选择扩展类型和名称。

Non-Interactive Usage (CI/CD or Scripts)

非交互式用法（适用于CI/CD或脚本）

You can bypass prompts by providing flags:
bash
shopify app generate extension --name "my-extension" --template <template_type> --flavor <flavor>
  • --name
    : The name of your extension.
  • --template
    : The type of extension to generate (e.g., 
    checkout_ui
    , 
    product_subscription
    , 
    theme_app_extension
    ).
  • --flavor
    : The language/framework to use (e.g., 
    react
    , 
    typescript
    , 
    vanilla-js
    ). Note: Not all extensions support all flavors.
你可以通过传入参数跳过交互提示：
bash
shopify app generate extension --name "my-extension" --template <template_type> --flavor <flavor>
  • --name
    : 扩展的名称。
  • --template
    : 要生成的扩展类型（例如
    checkout_ui
    、
    product_subscription
    、
    theme_app_extension
    ）。
  • --flavor
    : 使用的语言/框架（例如
    react
    、
    typescript
    、
    vanilla-js
    ）。注意：不是所有扩展都支持所有技术栈。

Examples

示例

Create a Checkout UI Extension (React):
bash
shopify app generate extension --template checkout_ui --name "checkout-upsell" --flavor react
Create a Theme App Extension:
bash
shopify app generate extension --template theme_app_extension --name "trust-badges"
Create a Shopify Function (Product Discount - Rust):
bash
shopify app generate extension --template product_discounts --name "volume-discount" --flavor rust
创建Checkout UI扩展（React版本）:
bash
shopify app generate extension --template checkout_ui --name "checkout-upsell" --flavor react
创建主题应用扩展:
bash
shopify app generate extension --template theme_app_extension --name "trust-badges"
创建Shopify Function（商品折扣 - Rust版本）:
bash
shopify app generate extension --template product_discounts --name "volume-discount" --flavor rust

Useful Flags

常用参数

  • --client-id <value>
    : Explicitly link to a specific app Client ID.
  • --path <path>
    : Run the command in a specific directory.
  • --reset
    : Reset the project configuration.
  • --client-id <value>
    : 显式关联到指定应用的Client ID。
  • --path <path>
    : 在指定目录下执行命令。
  • --reset
    : 重置项目配置。

📝 Development Workflow

📝 开发工作流

  1. Generate Extension:
    bash
    shopify app generate extension
    Select the extension type from the list.
  2. Develop:
    • Edit source files (React/JS/TS).
    • Configure 
      shopify.extension.toml
      .
    • Use 
      shopify app dev
      to preview.
  3. Deploy:
    bash
    shopify app deploy
    This publishes the extension version to Shopify Partners.
  4. Publish:
    • Go to Partner Dashboard > App > Extensions.
    • Publish the uploaded version.
  1. 生成扩展:
    bash
    shopify app generate extension
    从列表中选择扩展类型。
  2. 开发:
    • 编辑源代码文件（React/JS/TS）。
    • 配置
      shopify.extension.toml
      文件。
    • 使用
      shopify app dev
      命令预览效果。
  3. 部署:
    bash
    shopify app deploy
    该命令会将扩展版本发布到Shopify Partners后台。
  4. 发布:
    • 进入合作伙伴后台 > 应用 > 扩展页面。
    • 发布已上传的扩展版本。

💡 Best Practices

💡 最佳实践

  • Performance: UI extensions run in a web worker (Checkout/Admin). Avoid heavy computations.
  • Design: Use Polaris components (Admin) or provided UI components (Checkout) to match Shopify's look and feel.
  • API Usage: Use the 
    useApi()
    hook in React extensions to access valid APIs and data for the current context.
  • Versioning: Always test new extension versions in a development store before promoting to production.
  • 性能: UI扩展在Web Worker中运行（Checkout/Admin端），避免执行 heavy 计算逻辑。
  • 设计: 使用Polaris组件（Admin端）或官方提供的UI组件（Checkout端）来匹配Shopify的视觉风格和交互体验。
  • API使用: 在React扩展中使用
    useApi()
    钩子获取当前上下文下可用的API和数据。
  • 版本管理: 上线到生产环境前，务必在开发商店中测试新版本扩展。