shopify-pos

用途

该资料用于指导开发者为 Shopify POS（销售点）构建 UI 扩展，将自定义功能集成到 Shopify 在 iOS 和 Android 设备上的零售界面中。

前置条件

根据资料，构建 POS UI 扩展需要：

最新版 Shopify CLI
启用 POS 的 Shopify App
带 POS Pro 订阅的开发商店
启用 POS 嵌入：在 Partner Dashboard > App > Configuration 中，将 "Embed app in Shopify POS" 设置为 True。

扩展架构

POS UI 扩展由三个相互关联的部分组成：

Targets：扩展出现的位置（磁贴、弹窗、区块、菜单项）
Target APIs：数据与功能访问（Cart、Customer、Session 等）
Components：原生 UI 构建块（Button、Screen、List 等）

创建扩展

资料给出的生成命令为：

shopify app generate extension --template pos_ui --name "my-pos-extension"

配置文件 shopify.extension.toml 示例：

api_version = "2025-10"

[[extensions]]
type = "ui_extension"
name = "my-pos-extension"
handle = "my-pos-extension"

[[extensions.targeting]]
module = "./src/Tile.tsx"
target = "pos.home.tile.render"

[[extensions.targeting]]
module = "./src/Modal.tsx"
target = "pos.home.modal.render"

Targets

资料列出四类 Target 类型：

Tile：首页智能网格按钮，例如 pos.home.tile.render
Modal：全屏界面，例如 pos.home.modal.render
Block：内联内容区块，例如 pos.product-details.block.render
Menu Item：操作菜单按钮，例如 pos.customer-details.action.menu-item.render

资料给出了首页磁贴、弹窗、区块三种常见模式的 React 代码示例，并说明更多 Target 可参见 references/targets.md。

Components

资料列出主要组件类别：

布局与结构：Screen、Navigator、ScrollView、Section、Stack、List
操作：Button、Tile、Selectable
表单：TextField、TextArea、NumberField、EmailField、DateField、DatePicker、RadioButtonList、Stepper、PinPad
反馈：Banner、Dialog、Badge
媒体：Icon、Image、CameraScanner

更多组件可参见 references/components.md。

APIs

通过 useApi 访问，核心 API 包括：

Cart API：修改购物车内容（添加行项目、应用购物车折扣、获取购物车）
Session API：认证与会话数据（获取会话令牌、获取当前员工）
Customer API：客户数据访问
Toast API：显示通知
Navigation API：屏幕导航（关闭弹窗、跳转屏幕）
Scanner API：条码扫描
Print API：小票打印

资料还说明，针对 2025-07 或更高版本的扩展（需要 POS 10.6.0+）可直接访问 GraphQL API，通过 fetch('shopify:admin/api/graphql.json', ...) 发起请求，并在 shopify.app.toml 中声明所需 scopes：

[access_scopes]
scopes = "read_products,write_products,read_customers"

开发工作流

本地开发：shopify app dev，在设备上打开 Shopify POS 应用并连接开发商店
测试：在开发商店安装应用、打开 POS 应用、在智能网格（首页）查看磁贴、点击磁贴测试弹窗、在相关屏幕（产品、客户、订单）测试区块/操作 Target
部署：shopify app deploy

最佳实践

资料列出以下最佳实践：

性能优先：扩展运行在商家关键工作流中，尽量减少 API 调用与计算
离线考虑：对需要离线持久化的数据使用 Storage API
原生体验：使用提供的组件以匹配 POS 设计系统
错误处理：始终优雅地处理 API 失败并向用户反馈
加载状态：在异步操作期间显示加载指示

离线存储

通过 Storage API 存储与读取数据：

const { storage } = useApi<'pos.home.modal.render'>();
await storage.setItem('key', JSON.stringify(data));
const stored = await storage.getItem('key');
const data = stored ? JSON.parse(stored) : null;

完整示例：忠诚度积分扩展

资料提供了一个完整示例，包含 Tile.tsx（首页磁贴）与 Modal.tsx（弹窗），弹窗中使用 Cart、Session、Navigation、Toast API，通过 useState 与 useEffect 管理积分与加载状态，从后端获取积分、兑换积分（应用固定金额折扣）、显示提示并关闭弹窗。

限制

资料未提供关于收费、价格、平台支持范围、性能数据或效果承诺等信息。适用范围、支持的 POS 版本除已提及内容外，暂未提供更多细节。