# 检查组件 ## 目的生产就绪的 Next.js UI 组件，用于将 Stripe 支付与 TypeScript、Tailwind CSS 和辅助功能集成。提供完整的结帐流程、订阅管理和付款表单组件。 ## 安全要求 **关键：API 密钥处理** 使用这些组件时： * 切勿在组件中对 Stripe 可发布密钥进行硬编码 * 始终使用环境变量：`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` * 在所有示例中使用占位符：`pk_test_your_stripe_publishable_key_here` * 切勿将实际的 API 密钥提交到 git * 始终将 `.env` 文件添加到 `.gitignore` **示例.env.local：** # 永远不要提交这个文件 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key_here STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key_here STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here ## 激活触发器 * 创建结账页面 * 实施付款方式 * 构建订阅管理UI * 添加客户门户组件 * 整合条纹元素 * 创建付款历史显示 * 设置定价表 ## 组件概述 ### 提供者组件 * **StripeProvider.tsx** \- 使用 Stripe Elements 上下文包装应用程序 ### 支付组件 * **CheckoutForm.tsx** \- 带卡输入的完整结帐表格 * **PaymentMethodForm.tsx** \- 独立支付方式输入 * **SubscriptionCard.tsx** \- 订阅显示和管理 * **PricingTable.tsx** \- 定价层比较表 * **PaymentHistory.tsx** \- 交易历史组件 ## 快速入门 ### 1\.安装依赖项 # 安装 Stripe React 库 bash 脚本/install-stripe-react.sh **安装：** * `@stripe/stripe-js` \- Stripe.js 加载器 * `@stripe/react-stripe-js` \- React Elements 组件 * TypeScript 的类型定义 ### 2\.设置 Stripe 提供程序 # 在您的应用程序中创建提供者包装器 bash 脚本/setup-stripe-provider.sh **创建：** * `lib/stripe-client.ts` \- Stripe 客户端初始化 * `components/providers/stripe-provider.tsx` \- 元素提供程序包装器 * 环境变量配置 ### 3\.生成组件 # 生成具体的支付组件 bash 脚本/generate-component.sh 结账表单 bash 脚本/generate-component.sh 订阅卡 bash 脚本/generate-component.sh 定价表 ### 4\.验证设置 # 验证组件结构和配置 bash 脚本/validate-components.sh **检查：** * 配置环境变量 * 安装依赖项 * 组件结构有效 * TypeScript 类型正确 * 无障碍合规性 ## 组件模板 ### StripeProvider 模板使用 Stripe Elements 上下文包装您的应用程序：从'@/components/providers/stripe-provider'导入{StripeProvider}；导出默认函数 RootLayout({ Children }) { 返回（ <正文> <条纹提供者> {孩子} ）； } **特点：** * 自动加载 Stripe.js * 错误边界处理 * 加载状态 * 主题定制 ### 结账表格模板输入卡并填写付款表格：从 '@/components/ payments/checkout-form' 导入 { CheckoutForm }；导出默认函数 CheckoutPage() { 返回（

完成购买

<结帐表格金额={4999} onSuccess={() => router.push('/success')} onError={(错误) => console.error(错误)} />

）； } **特征：** * 带验证的卡元素 * 实时错误显示 * 加载状态 * 成功/错误回调 * 响应式设计 * ARIA 标签 ### PaymentMethodForm 模板独立付款方式集合：从 '@/components/ payments/ payment-method-form' 导入 { PaymentMethodForm }；导出默认函数AddPaymentMethod() { 返回（ <付款方式表格 onComplete={( paymentMethodId ) => { console.log('支付方式已创建：', paymentMethodId); }} 客户ID =“cus_xxx” /> ）； } **特点：** * 保存卡片以供将来使用 * 更新现有支付方式 * 验证和错误处理 * 加载指标 ### 订阅卡模板显示和管理订阅：从 '@/components/ payments/subscription-card' 导入 { SubscriptionCard }；导出默认函数 SubscriptionPage() { 返回（ <订阅卡订阅={{ id: 'sub_xxx', 状态：'活动'， currentPeriodEnd: 新日期('2025-12-01'), 计划：{名称：'专业计划'，金额：2999 } }} onCancel={() =>handleCancellation()} onUpdate={() => handleUpdate()} /> ）； } **特点：** * 状态徽章显示 * 续订日期 * 取消/升级操作 * 使用情况跟踪 * 账单历史链接 ### 定价表模板比较定价等级：从 '@/components/ payments/pricing-table' 导入 { PricingTable } ；常量计划 = [ { id: 'price_free', 名称：“免费”，价格: 0, 功能：['10 次 API 调用/月', '基本支持'] }, { id: 'price_pro', 名称：'专业'，价格：2999， features: ['1000 API 调用/月', '优先支持', '高级功能'] } ]; 导出默认函数 Pricing() { 返回handleCheckout(planId)}/>; } **特点：** * 响应式网格布局 * 功能比较 *号召性用语按钮 * 突出显示推荐计划 * 年度/每月切换 ### PaymentHistory 模板显示交易历史：从 '@/components/ payments/ payment-history' 导入 { PaymentHistory }；导出默认函数 BillingPage() { 返回（ <付款记录客户ID =“cus_xxx” 限制={10} onLoadMore={() => loadMorePayments()} /> ）； } **特点：** * 分页交易列表 * 发票下载链接 * 状态指示灯 * 日期格式 * 搜索和过滤 ## 样式定制所有组件均使用Tailwind CSS并支持定制： ### 元素样式自定义条纹元素外观：常量外观 = { 主题：“条纹”，变量：{ 主要颜色：'#0070f3', 颜色背景: '#ffffff', 颜色文本：'#000000', colorDanger: '#df1b41', fontFamily: 'system-ui, sans-serif', 间距单位：'4px'，边框半径：'4px' } }; <元素 stripe={stripePromise} options={{ 外观 }}> <结账表格/> ### 组件类覆盖默认的 Tailwind 类： <结帐表格类名=“自定义结帐” ButtonClassName =“bg-blue-600悬停：bg-blue-700” errorClassName="text-red-600 text-sm" /> ## TypeScript 类型所有组件都包含完整的 TypeScript 支持：导入类型{ 结帐表单道具， PaymentMethodFormProps，订阅卡道具，定价表道具，付款历史道具来自“@/类型/付款”； **类型定义：** * 道具接口 * 条带对象类型 * 事件处理程序 * 错误类型 * 响应类型 ## 错误处理组件提供全面的错误处理： <结帐表格 onError={（错误）=> { 开关（错误类型）{ 案例“卡错误”： // 显示用户友好的消息 toast.error(错误.消息); 休息; 案例“验证错误”： // 处理验证错误打破；默认： // 通用错误处理控制台.错误（错误）； } }} /> **错误类型：** * 卡验证错误 * 付款处理错误 * 网络错误 * 配置错误 ## 辅助功能所有组件均遵循 WCAG 2.1 AA 标准： * 正确的 ARIA 标签 * 键盘导航支持 * 焦点管理 * 屏幕阅读器友好 * 错误公告 * 颜色对比度合规性 **示例：** <按钮类型=“提交” aria-label="完成付款" aria-disabled={正在处理} 类名=“焦点：ring-2焦点：ring-blue-500” > {正在处理？ “正在处理...”：“立即付款”} ## 测试 ### 组件测试 # 验证所有组件 bash 脚本/validate-components.sh # 测试特定组件 bash 脚本/validate-components.sh CheckoutForm ### 集成测试使用 Stripe 测试卡： 4242 4242 4242 4242 - 成功 4000 0000 0000 0002 - 拒绝 4000 0000 0000 9995 - 资金不足 ## 示例 ### 示例 1：完整结账页面带有购物车摘要的完整结账实施： // 请参阅：examples/checkout-page-example.tsx // 完整页面： // - 订单摘要 // - 结账表格 // - 成功/错误处理 // - 加载状态 // - 收据生成 ### 示例 2：订阅管理具有升级/降级功能的订阅门户： // 请参阅：examples/subscription-management-example.tsx // 完整的门户： // - 当前计划显示 // - 定价比较 // - 升级/降级流程 // - 取消处理 // - 发票历史记录 ### 示例 3：付款表单集成将付款形式集成到多步骤流程中： // 请参阅：examples/ payment-form-integration-example.tsx // 多步结帐： // - 运输信息 // - 付款详细信息 // - 订单确认 // - 进度指示器 ## 环境设置所需的环境变量： # .env.local（永远不要提交此文件） NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here STRIPE_SECRET_KEY=sk_test_your_key_here STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here # 可选 NEXT_PUBLIC_STRIPE_CURRENCY=美元 NEXT_PUBLIC_APP_URL=http://localhost:3000 添加到`.gitignore`： .env.local .env.*.local .env ## 要求 **依赖关系：** * Next.js 13+ 与 App Router *反应18+ * 打字稿 5+ *顺风CSS 3+ * @stripe/stripe-js * @stripe/react-stripe-js **条纹设置：** * Stripe账户（测试模式有效） * 可发布的密钥 * 秘钥 * 配置Webhook端点 ## 安全最佳实践 1. **永远不要在客户端暴露密钥** * 仅在组件中使用`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` * 密钥仅保留在服务器端 2. **在服务器上验证** * 始终验证支付服务器端 * 使用网络钩子进行付款确认 * 永远不要相信客户端数据 3. **在生产中使用 HTTPS** * Stripe 集成所需 * 保护传输中的支付数据 4. **实施 CSP 标头** * 允许 Stripe.js 域 * 限制其他脚本源 5. **处理 PCI 合规性** * 切勿存储卡号 * 使用 Stripe 元素（符合 SAQ A） * 让Stripe处理卡片数据 ## 故障排除 ### Stripe.js 未加载检查环境变量：回显 $NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY 验证格式以“pk_test_”或“pk_live_”开头 ### 付款意向创建失败确保服务器端 API 路由存在： // 应用程序/api/create- payment-intent/route.ts 从 '@/lib/stripe-server' 导入 { stripe } ；导出异步函数 POST(req: Request) { const { amount } = wait req.json(); const paymentIntent = 等待 stripe. paymentIntents.create({ 金额，货币：'美元'， }); 返回 Response.json({ clientSecret: paymentIntent.client_secret }); } ### 组件未渲染验证 StripeProvider 包装组件： // 必须包裹起来 <条纹提供者> <结账表格/> ## 资源 **脚本：** * `scripts/install-stripe-react.sh` \- 安装依赖项 * `scripts/setup-stripe-provider.sh` \- 配置提供商 * `scripts/generate-component.sh` \- 生成新组件 * `scripts/validate-components.sh` \- 验证设置 **模板：** * `templates/StripeProvider.tsx` \- 提供程序包装器 * `templates/CheckoutForm.tsx` \- 结账表单 * `templates/PaymentMethodForm.tsx` \- 支付方式输入 * `templates/SubscriptionCard.tsx` \- 订阅显示 * `templates/PricingTable.tsx` \- 定价比较 * `templates/PaymentHistory.tsx` \- 交易历史记录 **示例：** * `examples/checkout-page-example.tsx` \- 完成结帐 * `examples/subscription-management-example.tsx` \- 订阅 UI * `examples/ payment-form-integration-example.tsx` \- 多步骤流程 ** ** **插件：**支付 **版本：** 1.0.0 **类别：** UI 组件 **框架：** Next.js + Stripe Elements

结帐组件

包含技能