---
title: "Viewports 参考 | Tajo"
description: "Stripe App UI 可以渲染的 Stripe Dashboard viewports 完整参考"
url: https://tajo.io/zh-cn/docs/stripe-apps/viewports/
markdown: https://tajo.io/zh-cn/docs/stripe-apps/viewports.md
lang: zh-CN
author: "Set Noa"
author_url: https://tajo.io/zh-cn/set-noa/
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Viewports 参考

[Set Noa](https://tajo.io/zh-cn/set-noa/)

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

Caution

**状态：计划中，尚未构建。** Tajo 没有 Stripe App，因此本章中的任何内容目前都无法安装。本页中的 app 标识、URL 和凭据都是用于示意的占位值，而不是可用的线上端点。

## Viewports 的工作原理

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

```json
{
  "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：

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

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

  // objectContext contains the current Stripe object
  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 提供最大价值：

```json
{
  "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。