TON Exchange SDK - TonAdBanner 组件文档

📋 简介

TonAdBanner 是一个为 TON 生态系统设计的广告横幅组件，支持多种尺寸、深色模式、智能容器管理等功能。

🚀 安装

npm install ton-exchange-sdk
# 或
yarn add ton-exchange-sdk

📦 引入

import { TonAdBanner } from 'ton-exchange-sdk'
import 'ton-exchange-sdk/dist/index.css'

🎯 基础使用

最简单的使用方式

<div style={{ width: 500, height: 150 }}>
  <TonAdBanner blockId="your-block-id" />
</div>

完整使用示例

import React, { useState } from 'react'
import { TonAdBanner } from 'ton-exchange-sdk'
import 'ton-exchange-sdk/dist/index.css'

function App() {
  const [darkMode, setDarkMode] = useState(false)

  return (
    <div>
      {/* 标准广告位 */}
      <div id="main-ad" style={{ width: 500, height: 150 }}>
        <TonAdBanner
          blockId="your-block-id"
          darkMode={darkMode}
          containerId="main-ad"
          onClick={(ad) => {
            console.log('广告被点击:', ad)
          }}
          onVerifySuccess={(options) => {
            console.log('广告验证成功:', options)
          }}
        />
      </div>
    </div>
  )
}

🔧 Props 参数

| 参数 | 类型 | 是否必填 | 默认值 | 说明 | |------|------|---------|--------|------| | blockId | string | ✅ | - | 广告位ID，用于获取对应的广告内容 | | onClick | (ad: TonAdProps) => void | ❌ | - | 广告点击回调函数 | | onVerifySuccess | (options: OnAdVerifyOptions) => void | ❌ | - | 广告验证成功回调 | | style | React.CSSProperties | ❌ | - | 自定义样式 | | darkMode | boolean | ❌ | false | 是否启用深色模式 | | containerId | string | ❌ | - | 容器元素ID，无广告时会自动隐藏该容器 |

🎨 主题模式

亮色模式（默认）

<TonAdBanner blockId="your-block-id" />

深色模式

<TonAdBanner blockId="your-block-id" darkMode={true} />

动态切换主题

const [isDark, setIsDark] = useState(false)

<TonAdBanner blockId="your-block-id" darkMode={isDark} />

📱 推荐尺寸

标准尺寸 (500x150)

适合桌面端和平板设备

<div style={{ width: 500, height: 150 }}>
  <TonAdBanner blockId="your-block-id" />
</div>

宽屏尺寸 (600x120)

适合宽屏布局

<div style={{ width: 600, height: 120 }}>
  <TonAdBanner blockId="your-block-id" />
</div>

紧凑尺寸 (400x100)

适合侧边栏或内容区域

<div style={{ width: 400, height: 100 }}>
  <TonAdBanner blockId="your-block-id" />
</div>

移动端尺寸 (320x80)

适合移动端设备

<div style={{ width: 320, height: 80 }}>
  <TonAdBanner blockId="your-block-id" />
</div>

🎯 智能容器管理

使用 containerId 参数可以实现智能容器管理：当获取不到广告时，指定的容器会被自动隐藏，避免占用页面空间。

<!-- HTML 容器 -->
<div id="ad-section" style={{ width: 500, height: 150, border: '1px solid #ddd' }}>
  <TonAdBanner
    blockId="your-block-id"
    containerId="ad-section"
  />
</div>

效果说明：

• ✅ 有广告：容器正常显示，广告渲染在其中
• ❌ 无广告：整个容器被隐藏 (display: none)
• ❌ 获取失败：容器也会被自动隐藏

📝 事件处理

点击事件

<TonAdBanner
  blockId="your-block-id"
  onClick={(ad) => {
    console.log('广告信息:', ad.text)
    console.log('广告ID:', ad.adId)
    console.log('广告图片:', ad.image)
    // 自定义点击逻辑
  }}
/>

验证成功回调

<TonAdBanner
  blockId="your-block-id"
  onVerifySuccess={(options) => {
    console.log('验证成功:', options)
    // 处理验证成功后的逻辑
  }}
/>

🎨 自定义样式

通过 style 属性

<TonAdBanner
  blockId="your-block-id"
  style={{
    borderRadius: '16px',
    boxShadow: '0 4px 12px rgba(0,0,0,0.15)'
  }}
/>

通过 CSS 类名覆盖

/* 自定义广告容器样式 */
.ton-ad-banner-container {
  border-radius: 20px !important;
}

/* 自定义按钮样式 */
.ton-ad-go-button {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4) !important;
}

📱 响应式设计

组件内置了响应式设计，会根据容器尺寸自动调整：

• > 120px 高度：标准布局
• < 120px 高度：紧凑布局，减少内边距
• < 100px 高度：超紧凑布局，单行标题
• < 90px 高度：极紧凑布局，最小化所有元素

🔄 初始化配置

在使用组件前，需要先初始化 SDK：

import { TonAdInit } from 'ton-exchange-sdk'

// 在应用启动时调用
TonAdInit({
  appKey: 'your-app-key',
  baseUrl: 'https://api.example.com'
})

⚠️ 注意事项

1. 容器尺寸：确保为广告组件提供明确的宽高
2. CSS 引入：不要忘记引入组件的 CSS 文件
3. blockId：确保使用有效的广告位ID
4. 初始化：在使用组件前先调用 TonAdInit
5. 深色模式：深色模式需要手动控制，不会自动检测系统主题

🎪 完整示例

import React, { useState, useEffect } from 'react'
import { TonAdBanner, TonAdInit } from 'ton-exchange-sdk'
import 'ton-exchange-sdk/dist/index.css'

function AdPage() {
  const [darkMode, setDarkMode] = useState(false)

  useEffect(() => {
    // 初始化 SDK
    TonAdInit({
      appKey: 'your-app-key',
      baseUrl: 'https://your-api-domain.com'
    })
  }, [])

  return (
    <div style={{
      padding: 20,
      backgroundColor: darkMode ? '#1f2937' : '#ffffff',
      minHeight: '100vh'
    }}>
      <h1>我的广告页面</h1>

      {/* 主题切换 */}
      <label>
        <input
          type="checkbox"
          checked={darkMode}
          onChange={(e) => setDarkMode(e.target.checked)}
        />
        深色模式
      </label>

      {/* 主要广告位 */}
      <div id="main-ad" style={{
        width: 500,
        height: 150,
        margin: '20px 0',
        border: '1px solid #ddd',
        borderRadius: 12
      }}>
        <TonAdBanner
          blockId="main-banner"
          darkMode={darkMode}
          containerId="main-ad"
          onClick={(ad) => {
            console.log('主广告被点击:', ad)
          }}
        />
      </div>

      {/* 侧边栏广告位 */}
      <div id="sidebar-ad" style={{
        width: 300,
        height: 100,
        border: '1px solid #ddd',
        borderRadius: 8
      }}>
        <TonAdBanner
          blockId="sidebar-banner"
          darkMode={darkMode}
          containerId="sidebar-ad"
        />
      </div>
    </div>
  )
}

export default AdPage

🛠️ 类型定义

interface TonAdProps {
  adId: string
  text: string
  image: string
  icon: string
  popupImage?: string
  // ... 其他属性
}

interface OnAdVerifyOptions {
  // 验证选项的类型定义
}

🐛 故障排除

广告不显示

1. 检查 blockId 是否正确
2. 确认已正确调用 TonAdInit
3. 查看浏览器控制台是否有错误信息
4. 检查网络连接是否正常

样式问题

1. 确认已引入 CSS 文件
2. 检查容器是否有明确的宽高
3. 查看是否有其他 CSS 样式冲突

容器未隐藏

1. 确认 containerId 参数正确
2. 检查对应 ID 的元素是否存在
3. 查看浏览器控制台的日志信息