SuperAPI AI 工具集

polaris-app-home-app-bridge

编程与开发

查看项目

更新于 10-16 10:52

技能介绍

用途

本技能是 Polaris App Home 里 App Bridge 接口的参考文档,服务于 Shopify 后台内嵌应用的开发。当代码需要调用 shopify.* API、使用 useAppBridge() Hook、添加应用顶部导航或内嵌 iframe,或配置保存栏时,可查阅本技能。它不涉及 Polaris 的 <s-page>、<s-section>、<s-button> 等标记(那属于 polaris-app-home-web-components),也不负责标题栏——标题栏通过 <s-page> 的 props 与插槽配置,并不存在 shopify.titleBar 命名空间。

主要能力

文档覆盖以下接口面:

  • React Hook:useAppBridge(),从 @shopify/app-bridge-react 导入,返回 shopify 全局对象或 SSR 安全代理;需要 @shopify/app-bridge-react@v4 以及 app-bridge.js script 标签。
  • 认证与数据 API:shopify.app.extensions()、shopify.config、shopify.environment、被拦截的 fetch()、shopify.idToken()、shopify.scopes.query/request/revoke、shopify.user()。
  • UI 与交互 API:shopify.toast.show/hide、shopify.modal.show/hide/toggle(面向 <s-modal>)、shopify.resourcePicker、shopify.picker。
  • 导航 API:基于锚点的导航与 JS API(open、history.pushState/replaceState、navigation.navigate),shopify.loading(isLoading),shopify.saveBar.show/hide/toggle/leaveConfirmation,shopify.intents.invoke,shopify.reviews.request,shopify.support.registerHandler。
  • 设备与平台 API:shopify.scanner.capture()(仅 POS)、navigator.share、print()、shopify.webVitals.onReport、shopify.pos.cart/close/device/location。
  • Web Components:<s-app-nav>(应用顶部导航,子元素为 <s-link>)与 <s-app-window>(内嵌 iframe,含 show/hide/toggle 等 DOM 实例方法与 show/hide 事件)。
  • 保存栏:声明式 <form data-save-bar>(含 data-discard-confirmation、onSubmit、onReset)与编程式 shopify.saveBar.* 两种方式。

使用方式与规则

  • React 中使用 useAppBridge(),非 React 环境使用 window.shopify;二者运行时是同一对象,React 代码优先用 Hook 以保证 SSR 安全。
  • App Bridge Web Components 无法通过 JSX 校验,<s-app-nav>、<s-app-window>、<s-link rel="home"> 会报 Property does not exist 错误,属预期行为;可用原生 HTML、React 包装组件(<NavMenu>、<TitleBar>、<SaveBar>)或接受校验警告。
  • <s-> 为当前规范,<ui-> 为旧版;旧名仍由 @shopify/app-bridge-react 包装组件输出,可运行但不在当前文档中。
  • 不存在 shopify.appWindow 命名空间,通过元素 ref 的实例方法(.show()/.hide()/.toggle())或 commandFor 控制 <s-app-window>。
  • 不存在 shopify.titleBar、shopify.action、shopify.clipboard、shopify.geolocation、shopify.nfc、shopify.share、shopify.print 命名空间;share 与 print 以标准浏览器 API navigator.share() 和 window.print() 提供,会被 App Bridge 在移动端/POS 拦截。
  • shopify.loading 是函数而非对象,调用 shopify.loading(true)/shopify.loading(false)。
  • Resource Picker 的 action 枚举为 'add' | 'select',默认 'add'。

适用场景

代码调用任意 shopify.* API(toast、modal、保存栏、scanner、idToken、picker、scopes、intents、web vitals、POS);使用 @shopify/app-bridge-react 的 useAppBridge();添加 <s-app-nav> 或 <s-app-window>;配置声明式或编程式保存栏时,适合使用本技能。

限制

本技能不用于编写 Polaris <s-page> 等标记,不用于标题栏(无 shopify.titleBar 命名空间)。校验提示若指向 Polaris 组件或属性而非上述 App Bridge 组件,需修复并重新校验,最多 2 次。部分平台能力(如 shopify.scanner.capture()、shopify.pos.*)仅限 POS 或移动端。文档中未提供收费、价格、平台兼容清单等事实,相关细节暂未提供。