Viewports 参考

Viewports 定义了 Stripe App 的 UI 组件在 Stripe Dashboard 中出现的位置。每个 viewport 对应一个特定的 Dashboard 页面或位置，您的应用可以在那里渲染视图。

Viewports 的工作原理

在应用 manifest 中声明视图时，您将 React 组件映射到 viewport：

{
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.customer.detail",
        "component": "CustomerDetailView"
      }
    ]
  }
}

当用户导航到相应的 Dashboard 页面并打开应用时，组件会在应用 drawer（侧边面板）中渲染。

全局 Viewport 与页面特定 Viewport

全局 Viewport

这些 viewport 在 Stripe Dashboard 的每个页面上都可用：

Viewport ID	描述
`stripe.dashboard.drawer.default`	默认 drawer 视图，可通过任何 Dashboard 页面的应用图标访问
`stripe.dashboard.home.overview`	主页概览，显示在 Dashboard 落地页
`stripe.dashboard.settings`	应用设置页面，可从应用的设置菜单访问
`stripe.dashboard.onboarding`	引导流程，应用安装后显示

Tip

drawer.default viewport 充当后备选项。如果用户在您未声明特定 viewport 的页面上打开应用，drawer.default 视图将代替渲染。

页面特定 Viewport

这些 viewport 仅在用户位于相应 Dashboard 页面时渲染：

支付

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.payment.list`	支付列表	`/payments`	,
`stripe.dashboard.payment.detail`	支付详情	`/payments/:id`	PaymentIntent
`stripe.dashboard.charge.detail`	Charge 详情	`/payments/:id` (legacy)	Charge

客户

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.customer.list`	客户列表	`/customers`	,
`stripe.dashboard.customer.detail`	客户详情	`/customers/:id`	Customer

产品与价格

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.product.list`	产品列表	`/products`	,
`stripe.dashboard.product.detail`	产品详情	`/products/:id`	Product
`stripe.dashboard.price.detail`	价格详情	`/prices/:id`	Price

发票

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.invoice.list`	发票列表	`/invoices`	,
`stripe.dashboard.invoice.detail`	发票详情	`/invoices/:id`	Invoice

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.subscription.list`	订阅列表	`/subscriptions`	,
`stripe.dashboard.subscription.detail`	订阅详情	`/subscriptions/:id`	Subscription

Checkout

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.checkout.session.list`	Checkout Sessions 列表	`/checkout/sessions`	,
`stripe.dashboard.checkout.session.detail`	Checkout Session 详情	`/checkout/sessions/:id`	CheckoutSession
`stripe.dashboard.payment-link.list`	Payment Links 列表	`/payment-links`	,
`stripe.dashboard.payment-link.detail`	Payment Link 详情	`/payment-links/:id`	PaymentLink

Connect

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.connect.account.list`	关联账户列表	`/connect/accounts`	,
`stripe.dashboard.connect.account.detail`	关联账户详情	`/connect/accounts/:id`	Account
`stripe.dashboard.transfer.list`	转账列表	`/connect/transfers`	,
`stripe.dashboard.transfer.detail`	转账详情	`/connect/transfers/:id`	Transfer

账单

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.coupon.list`	优惠券列表	`/coupons`	,
`stripe.dashboard.coupon.detail`	优惠券详情	`/coupons/:id`	Coupon
`stripe.dashboard.quote.list`	报价列表	`/quotes`	,
`stripe.dashboard.quote.detail`	报价详情	`/quotes/:id`	Quote
`stripe.dashboard.credit-note.detail`	信用票据详情	`/credit-notes/:id`	CreditNote

Payouts

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.payout.list`	Payout 列表	`/payouts`	,
`stripe.dashboard.payout.detail`	Payout 详情	`/payouts/:id`	Payout

争议

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.dispute.list`	争议列表	`/disputes`	,
`stripe.dashboard.dispute.detail`	争议详情	`/disputes/:id`	Dispute

Terminal

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.terminal.reader.list`	读卡器列表	`/terminal/readers`	,
`stripe.dashboard.terminal.reader.detail`	读卡器详情	`/terminal/readers/:id`	TerminalReader
`stripe.dashboard.terminal.location.list`	位置列表	`/terminal/locations`	,
`stripe.dashboard.terminal.location.detail`	位置详情	`/terminal/locations/:id`	TerminalLocation

Issuing

Viewport ID	页面	URL 模式	对象类型
`stripe.dashboard.issuing.card.list`	卡片列表	`/issuing/cards`	,
`stripe.dashboard.issuing.card.detail`	卡片详情	`/issuing/cards/:id`	IssuingCard
`stripe.dashboard.issuing.cardholder.list`	持卡人列表	`/issuing/cardholders`	,
`stripe.dashboard.issuing.cardholder.detail`	持卡人详情	`/issuing/cardholders/:id`	IssuingCardholder
`stripe.dashboard.issuing.transaction.list`	交易列表	`/issuing/transactions`	,
`stripe.dashboard.issuing.authorization.list`	授权列表	`/issuing/authorizations`	,

访问对象 Context

当应用在 detail viewport 中渲染时，它会接收相关的 Stripe 对象作为 context：

import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';

const CustomerDetailView = ({ environment }: ExtensionContextValue) => {
  const { objectContext } = environment;

  // objectContext 包含当前 Stripe 对象
  const customerId = objectContext?.id; // "cus_xxxxx"
  const customerEmail = objectContext?.email;

  return (
    <Box>
      <Inline>Customer: {customerEmail}</Inline>
      <Inline>Brevo Sync Status: checking...</Inline>
    </Box>
  );
};

List 与 Detail Context 对比

Viewport 类型	Object Context	使用场景
List（例如 `customer.list`）	不可用, 未选择特定对象	显示汇总数据、摘要视图或批量操作
Detail（例如 `customer.detail`）	当前页面的完整 Stripe 对象	显示对象特定数据、操作和集成

Tajo Brevo 集成推荐 Viewport

对于 Tajo Brevo 集成应用，这些 viewport 提供最大价值：

{
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.customer.detail",
        "component": "CustomerDetailView"
      },
      {
        "viewport": "stripe.dashboard.customer.list",
        "component": "CustomerListView"
      },
      {
        "viewport": "stripe.dashboard.payment.detail",
        "component": "PaymentDetailView"
      },
      {
        "viewport": "stripe.dashboard.subscription.detail",
        "component": "SubscriptionDetailView"
      },
      {
        "viewport": "stripe.dashboard.home.overview",
        "component": "OverviewView"
      },
      {
        "viewport": "stripe.dashboard.drawer.default",
        "component": "DrawerView"
      },
      {
        "viewport": "stripe.dashboard.settings",
        "component": "SettingsView"
      },
      {
        "viewport": "stripe.dashboard.onboarding",
        "component": "OnboardingView"
      }
    ]
  }
}

组件	用途
CustomerDetailView	显示特定客户的 Brevo 联系人信息、同步状态和参与数据
CustomerListView	显示批量同步控件和聚合 Brevo 同步统计
PaymentDetailView	显示此支付触发了哪些 Brevo 事件
SubscriptionDetailView	显示此订阅的 Brevo 自动化状态
OverviewView	Dashboard 主页小部件，显示同步健康状况和关键 Brevo 指标
DrawerView	通用应用 drawer，提供快速操作和状态概览
SettingsView	配置 Brevo API 密钥、同步偏好和字段映射
OnboardingView	引导新用户完成 Brevo 账户连接

Viewport 可用性

并非所有 viewport 在所有 Stripe Dashboard 模式下都可用：

模式	可用 Viewports
Live 模式	所有 viewports
Test 模式	所有 viewports（使用测试数据）
Sandbox	所有 viewports（如果 `sandbox_install_compatible: true`）

Caution

如果 manifest 声明了不存在的 viewport，应用上传将无法通过验证。请始终根据此参考验证 viewport ID。