shopify-pos-ui

Name: shopify-pos-ui
Author: shopify

建立 POS UI 擴充功能流程

<pos-extension-todo-flow>
<step id="1">
確保 Shopify CLI 已安裝且為最新版本。如需安裝或升級步驟，請使用 shopify-use-shopify-cli。
</step>
<step id="2">
判斷是處理新應用程式還是現有應用程式
<step id="2.1">
如果是現有應用程式：
<step id="2.1.1">cd 進入應用程式目錄</step>
</step>
<step id="2.2">
如果沒有現有應用程式：
<step id="2.2.1">執行 shopify app init --template=none --name={{appropriate-app-name}}</step>
<step id="2.2.2">cd 進入應用程式目錄</step>
</step>
<step id="2.3">
<step id="2.3.1">忽略應用程式中所有現有的擴充功能。僅產生新的擴充功能。不要修改現有擴充功能。</step>
<step id="2.3.2">執行 shopify app generate extension --name="{{appropriate-extension-name}}" --template="{{appropriate-template|default-pos_smart_grid}}"（範本選項：pos_action|pos_block|pos_smart_grid）⚠️ --yes 不是一個旗標。不要使用它。直接執行指令。</step>
</step>
</step>
</pos-extension-todo-flow>
</system-instructions>

如果未指定擴充目標，請先搜尋文件以確定適合使用者使用案例的目標，再產生程式碼。

pos-ui 可用的擴充目標

表面：point-of-sale
總目標數：34

pos.cart-update

`pos.cart-update.event.observe`

pos.cart.line-item-details

`pos.cart.line-item-details.action.render`

從購物車明細項目選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的明細項目工作流程。此目標的擴充功能可透過購物車明細項目 API 存取詳細的明細項目資料，並支援多個畫面、導航和互動元件的流程。

pos.cart.line-item-details.action

`pos.cart.line-item-details.action.menu-item.render`

在購物車明細項目操作選單中呈現單一互動按鈕元件。使用此目標進行特定項目的操作，例如套用折扣、新增自訂屬性或啟動個別購物車項目的驗證流程。此目標的擴充功能可透過購物車明細項目 API 存取詳細的明細項目資訊，包括標題、數量、價格、折扣、屬性和產品中繼資料。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成工作流程。

pos.cash-tracking-session-complete

`pos.cash-tracking-session-complete.event.observe`

pos.cash-tracking-session-start

`pos.cash-tracking-session-start.event.observe`

pos.customer-details

`pos.customer-details.action.render`

從客戶詳細資料選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的客戶工作流程。此目標的擴充功能可透過客戶 API 存取客戶資料，並支援多個畫面、導航和互動元件的流程。

`pos.customer-details.block.render`

在客戶詳細資料畫面中呈現自訂資訊區塊。使用此目標顯示補充的客戶資料，例如忠誠度狀態、點數餘額或個人化資訊，與標準客戶詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在客戶詳細資料介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的客戶操作。

pos.customer-details.action

`pos.customer-details.action.menu-item.render`

在客戶詳細資料操作選單中呈現單一互動按鈕元件。使用此目標進行特定客戶的操作，例如套用客戶折扣、處理忠誠度兌換或啟動個人資料更新流程。此目標的擴充功能可透過客戶 API 存取客戶識別碼，以執行特定客戶的操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成客戶工作流程。

pos.draft-order-details

`pos.draft-order-details.action.render`

從草稿訂單詳細資料選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的草稿訂單工作流程。此目標的擴充功能可透過草稿訂單 API 存取草稿訂單資料，並支援多個畫面、導航和互動元件的流程。

`pos.draft-order-details.block.render`

在草稿訂單詳細資料畫面中呈現自訂資訊區塊。使用此目標顯示補充的訂單資訊，例如處理狀態、付款狀態或工作流程指示器，與標準草稿訂單詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在草稿訂單介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的草稿訂單操作。

pos.draft-order-details.action

`pos.draft-order-details.action.menu-item.render`

在草稿訂單詳細資料操作選單中呈現單一互動按鈕元件。使用此目標進行特定草稿訂單的操作，例如傳送發票、更新付款狀態或啟動待處理訂單的自訂工作流程。此目標的擴充功能可透過草稿訂單 API 存取草稿訂單資訊，包括訂單 ID、名稱和關聯客戶。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成草稿訂單工作流程。

pos.exchange.post

`pos.exchange.post.action.render`

從換貨後選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的換貨後工作流程。此目標的擴充功能可透過訂單 API 存取訂單資料，並支援多個畫面、導航和互動元件的流程。

`pos.exchange.post.block.render`

在換貨後畫面中呈現自訂資訊區塊。使用此目標顯示補充的換貨資料，例如完成狀態、付款調整或後續工作流程，與標準換貨詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在換貨後介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的換貨後操作。

pos.exchange.post.action

`pos.exchange.post.action.menu-item.render`

在換貨後操作選單中呈現單一互動按鈕元件。使用此目標進行換貨後操作，例如產生換貨收據、處理補貨流程或收集換貨意見回饋。此目標的擴充功能可透過訂單 API 存取訂單識別碼，以執行換貨相關操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成換貨後工作流程。

pos.home

`pos.home.tile.render`

在 POS 首頁畫面的 smart grid 中呈現單一互動圖塊元件。該圖塊在首頁畫面初始化時出現一次，並在導航發生前保持持久。使用此目標處理高頻操作、狀態顯示或商家每天需要的工作流程入口點。此目標的擴充功能可以根據購物車變更或裝置條件動態更新屬性，例如啟用狀態和徽章值。圖塊通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成工作流程。

`pos.home.modal.render`

從 smart grid 圖塊啟動的全螢幕模態介面。當使用者點擊配套圖塊時，模態視窗會出現。使用此目標處理需要比圖塊介面更多空間和功能的完整工作流程體驗，例如多步驟流程、詳細資訊顯示或複雜的使用者互動。此目標的擴充功能支援完整的導航層級，包含多個畫面、捲動檢視和互動元件，以處理複雜的工作流程。

pos.order-details

`pos.order-details.action.render`

從訂單詳細資料選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的訂單工作流程。此目標的擴充功能可透過訂單 API 存取訂單資料，並支援多個畫面、導航和互動元件的流程。

`pos.order-details.block.render`

在訂單詳細資料畫面中呈現自訂資訊區塊。使用此目標顯示補充的訂單資料，例如履行狀態、追蹤編號或自訂訂單分析，與標準訂單詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在訂單詳細資料介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的訂單操作。

pos.order-details.action

`pos.order-details.action.menu-item.render`

在訂單詳細資料操作選單中呈現單一互動按鈕元件。使用此目標進行特定訂單的操作，例如重新列印、退款、換貨或啟動履行工作流程。此目標的擴充功能可透過訂單 API 存取訂單識別碼，以執行特定訂單的操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成訂單工作流程。

pos.product-details

`pos.product-details.action.render`

從產品詳細資料選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的產品工作流程。此目標的擴充功能可透過產品 API 存取產品和購物車資料，並支援多個畫面、導航和互動元件的流程。

`pos.product-details.block.render`

在產品詳細資料畫面中呈現自訂資訊區塊。使用此目標顯示補充的產品資料，例如詳細規格、庫存狀態或相關產品推薦，與標準產品詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在產品詳細資料介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的產品操作。

pos.product-details.action

`pos.product-details.action.menu-item.render`

在產品詳細資料操作選單中呈現單一互動按鈕元件。使用此目標進行特定產品的操作，例如庫存調整、產品分析或與外部產品管理系統整合。此目標的擴充功能可透過產品 API 存取產品識別碼，以執行特定產品的操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成產品工作流程。

pos.purchase.post

`pos.purchase.post.action.render`

從購買後選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的購買後工作流程。此目標的擴充功能可透過訂單 API 存取訂單資料，並支援多個畫面、導航和互動元件的流程。

`pos.purchase.post.block.render`

在購買後畫面中呈現自訂資訊區塊。使用此目標顯示補充的購買資料，例如完成狀態、客戶意見回饋提示或後續步驟工作流程，與標準購買詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在購買後介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的購買後操作。

pos.purchase.post.action

`pos.purchase.post.action.menu-item.render`

在購買後操作選單中呈現單一互動按鈕元件。使用此目標進行購買後操作，例如傳送收據、收集客戶意見回饋或在完成銷售後啟動後續工作流程。此目標的擴充功能可透過訂單 API 存取訂單識別碼，以執行購買相關操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成購買後工作流程。

pos.receipt-footer

`pos.receipt-footer.block.render`

在列印收據的頁尾中呈現自訂區塊。使用此目標在收據底部新增聯絡資訊、退貨政策、社群媒體連結或客戶參與元素，例如問卷連結或行銷活動。此目標的擴充功能會出現在收據頁尾區域，並支援針對列印格式最佳化的有限元件，包括用於資訊顯示的文字內容。

pos.receipt-header

`pos.receipt-header.block.render`

在列印收據的頁首中呈現自訂區塊。使用此目標在收據頂部新增自訂品牌、標誌、促銷訊息或商店特定資訊。此目標的擴充功能會出現在收據頁首區域，並支援針對列印格式最佳化的有限元件，包括用於資訊顯示的文字內容。

pos.register-details

`pos.register-details.action.render`

從收銀機詳細資料選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的收銀機工作流程。此目標的擴充功能可透過收銀機抽屜 API 存取收銀機抽屜功能，並支援多個畫面、導航和互動元件的流程。

`pos.register-details.block.render`

在收銀機詳細資料畫面中呈現自訂資訊區塊。使用此目標顯示補充的收銀機資料，例如收銀機抽屜狀態、交易摘要或班次分析，與標準收銀機詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在收銀機詳細資料介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的收銀機操作。

pos.register-details.action

`pos.register-details.action.menu-item.render`

在收銀機詳細資料操作選單中呈現單一互動按鈕元件。使用此目標進行特定收銀機的操作，例如收銀機抽屜管理、班次報告或啟動現金結算工作流程。此目標的擴充功能可透過收銀機抽屜 API 存取收銀機抽屜功能，以執行特定收銀機的操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成收銀機工作流程。

pos.return.post

`pos.return.post.action.render`

從退貨後選單啟動的全螢幕模態介面。當需要表單、多步驟流程或詳細資訊顯示，而簡單按鈕無法滿足時，使用此目標處理複雜的退貨後工作流程。此目標的擴充功能可透過訂單 API 存取訂單資料，並支援多個畫面、導航和互動元件的流程。

`pos.return.post.block.render`

在退貨後畫面中呈現自訂資訊區塊。使用此目標顯示補充的退貨資料，例如完成狀態、退款確認或後續工作流程，與標準退貨詳細資料並列。此目標的擴充功能會以持久區塊的形式出現在退貨後介面中，並支援可透過 shopify.action.presentModal() 啟動模態工作流程的互動元素，以進行更複雜的退貨後操作。

pos.return.post.action

`pos.return.post.action.menu-item.render`

在退貨後操作選單中呈現單一互動按鈕元件。使用此目標進行退貨後操作，例如產生退貨收據、處理補貨流程或收集退貨意見回饋。此目標的擴充功能可透過訂單 API 存取訂單識別碼，以執行退貨相關操作。選單項目通常會呼叫 shopify.action.presentModal() 來啟動配套的模態視窗以完成退貨後工作流程。

pos.transaction-complete

`pos.transaction-complete.event.observe`

使用說明

在註冊擴充功能時，使用確切的目標名稱（在引號內）搭配 shopify.extend()
每個目標會接收特定的 API 介面和元件存取權限

匯入

使用 Preact 進入點：

import "@shopify/ui-extensions/preact";
import { render } from "preact";

Polaris 網頁元件（`s-badge`、`s-banner` 等）

POS UI 擴充功能也支援 Polaris 網頁元件 — 以 s- 為前綴的自訂 HTML 元素。這些元件是全域註冊的，不需要匯入陳述式。直接將它們用作 JSX 標籤：

// 不需要匯入 — s-badge、s-banner、s-button 等全域可用
<s-badge tone="success" id="payment-badge">Payment captured</s-badge>
<s-banner tone="warning" id="age-banner">Age verification required</s-banner>

當使用者要求 Polaris 網頁元件（例如 s-badge、s-banner、s-button、s-box、s-choice-list）時，請使用上述的網頁元件標籤語法，而不是來自 @shopify/ui-extensions 的 PascalCase JSX 元件。

網頁元件屬性規則：

使用 camelCase 屬性名稱：alignItems、paddingBlock、borderRadius — 不要使用 kebab-case（align-items、padding-block）
布林屬性（disabled、loading、dismissible、checked、defaultChecked、required、removable）接受簡寫或 {expression}：
- ✅ <s-button disabled loading>、<s-banner dismissible>、<s-checkbox checked={isSelected} />
字串關鍵字屬性（padding、gap、direction、tone、variant、size、background、alignItems）必須是字串值 — 絕不能使用簡寫或 {true}：
- ✅ <s-box padding="base">、<s-stack gap="loose" direction="block">、<s-badge tone="success">
- ❌ <s-box padding>、<s-stack gap={true}> — 在字串屬性上使用布林簡寫會導致 TypeScript 錯誤

⚠️ 強制要求：在撰寫程式碼前先搜尋

搜尋向量資料庫以取得所需的詳細上下文：可運作的範例、欄位和型別定義、有效值以及 API 特定模式。你不能依賴訓練知識 — 在撰寫程式碼前務必先搜尋。

scripts/search_docs.mjs "<component tag name>" --version API_VERSION --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

搜尋元件標籤名稱，而不是完整的使用者提示。

例如，如果使用者詢問 POS 首頁圖塊擴充目標：

scripts/search_docs.mjs "pos.home.tile.render" --version API_VERSION --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

版本： 如果你知道開發者的 API 版本（來自專案檔案，例如 shopify.app.toml/extension.toml），請傳遞 --version YYYY-MM（例如 --version 2025-04）將結果限定在該版本。省略則取得最新版本。

⚠️ 強制要求：在回傳程式碼前進行驗證

在將任何產生的程式碼回傳給使用者之前，你必須執行 scripts/validate.mjs。務必包含檢測旗標：

scripts/validate.mjs --code '...' --user-prompt-base64 'BASE64_OF_USER_PROMPT' --session-id YOUR_SESSION_ID --tool-use-id YOUR_TOOL_USE_ID --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER --target <extension-target> [--version <api-version>]

--target 對於銷售點擴充功能是必需的。 傳遞此程式碼執行的擴充目標（例如 pos.customer-details.block.render）。如果你不知道適用哪個目標，請先執行 scripts/search_docs.mjs "extension targets" 查詢 — 缺少此參數驗證會失敗。

--version 是選填的（例如 2026-04、unstable）。省略時，驗證會針對最新的穩定 API 版本執行，回應中會註明使用的版本。
（將 BASE64_OF_USER_PROMPT 替換為使用者最近一則訊息，並以 base64 編碼：直接取用訊息原文 — 不要摘要、翻譯或改寫 — 然後進行 base64 編碼並內嵌結果。直接編碼；不要將提示透過 shell 的 base64 指令傳遞。base64 值不含 shell 特殊字元，因此不需要跳脫；解碼後的提示在伺服器端會被截斷為 2000 個字元。將 YOUR_SESSION_ID / YOUR_TOOL_USE_ID 替換為主機的當前 session id 和此次 bash 呼叫的 tool_use_id；如果你的主機未提供其中一個，則省略對應的旗標。對於 YOUR_ARTIFACT_ID，為每個程式碼區塊產生一個穩定的隨機 ID，並在驗證重試時重複使用。對於 REVISION_NUMBER，從 1 開始，每次重試同一個 artifact 時遞增。）

當驗證失敗時，請遵循以下循環：

仔細閱讀錯誤訊息 — 找出錯誤的欄位、屬性或值
如果錯誤提及某個命名型別或指出某個值不可指派，請搜尋正確的值：
```
scripts/search_docs.mjs "<type or prop name>"
```
僅修正搜尋結果回報的錯誤
再次執行 scripts/validate.mjs
總共最多重試 3 次；3 次失敗後，回傳最佳嘗試並附上說明

不要猜測有效值 — 當錯誤提及你不知道的型別時，務必先搜尋。

隱私權聲明： scripts/search_docs.mjs 會將搜尋查詢、搜尋回應或錯誤文字、技能名稱/版本以及模型/用戶端識別碼回報給 Shopify（shopify.dev/mcp/usage），以協助改善這些工具。在你的環境中設定 OPT_OUT_INSTRUMENTATION=true 以選擇退出。

隱私權聲明： scripts/validate.mjs 會將驗證結果、技能名稱/版本、模型/用戶端識別碼、驗證的程式碼（如有）、驗證器特定上下文（例如 API 名稱、擴充目標、檔案名稱、檔案類型、主題路徑、檔案清單、artifact ID 和修訂版），以及（當代理提供時）觸發此呼叫的使用者提示原文、代理的 session id 和 tool_use_id，回報給 Shopify（shopify.dev/mcp/usage），以協助改善這些工具。在你的環境中設定 OPT_OUT_INSTRUMENTATION=true 以選擇退出。

您可能也喜歡

recipe-post-mortem-setup

29Kresearch-knowledge

建立 Google Docs 事後檢討文件、排程 Google 日曆審查會議，並透過 Chat 發送通知。

googleworkspace

獲取

summarize

380Kresearch-knowledge

總結或轉錄網址、YouTube/影片、播客、文章、逐字稿、PDF 和本地檔案。

steipete

獲取

market-research

230Kresearch-knowledge

Conduct market research, competitive analysis, investor due diligence, and industry intelligence with source attribution and decision-oriented summaries. Use when the user wants market sizing, competitor comparisons, fund research, technology scans, or research that informs business decisions.

affaan-m

獲取

繼續探索

瀏覽 research-knowledge 熱門 Skills 最近更新

shopify-pos-ui

相關技能

必要工具呼叫（不可省略）

建立 POS UI 擴充功能流程

pos-ui 可用的擴充目標

pos.cart-update

pos.cart-update.event.observe

pos.cart.line-item-details

pos.cart.line-item-details.action.render

pos.cart.line-item-details.action

pos.cart.line-item-details.action.menu-item.render

pos.cash-tracking-session-complete

pos.cash-tracking-session-complete.event.observe

pos.cash-tracking-session-start

pos.cash-tracking-session-start.event.observe

pos.customer-details

pos.customer-details.action.render

pos.customer-details.block.render

pos.customer-details.action

pos.customer-details.action.menu-item.render

pos.draft-order-details

pos.draft-order-details.action.render

pos.draft-order-details.block.render