# @adsgram/react 中文文档

规范地址：https://npmcn.com/package/%40adsgram/react/

版本：1\.0\.2
npm 元数据更新时间：2025-06-18T18:53:25.537Z
中文译文更新时间：2026-11-09T19:54:30.488Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adsgram/react
原文对照：https://npmcn.com/package/%40adsgram/react/?lang=original
项目主页：https://docs.adsgram.ai/publisher/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：17.3 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16\.8\.0
- 首次发布：2025-06-13T09:07:38.244Z
- 最新版本发布：2025-06-18T18:53:25.260Z
- 近 30 天下载量：1765（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

Adsgram SDK 的回放装订. 为广告任务和全屏横幅提供组件和钩子.

## 安装

```sh
npm install @adsgram/react
```

也可以使用：`pnpm add @adsgram/react`、`yarn add @adsgram/react`、`bun add @adsgram/react`

## README

# @ adsgram/ 反应

Adsgram SDK 的回放装订. 为广告任务和全屏横幅提供组件和钩子.

## 安装

```bash
npm install @adsgram/react
# or
yarn add @adsgram/react
# or
pnpm add @adsgram/react
```

## 构成部分

### `<AdsgramTask />`

反应包装组件 `<adsgram-task>` 自定义元素。 用于 [任务](https://docs.adsgram.ai/publisher/task-examples) 广告格式.

![Task ad](https://docs.adsgram.ai/assets/native_task.Dp3rdtR0.png)

#### 道具

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `blockId` | `string` | 唯一任务块 ID( 需要) |
| `debug` | `boolean` | 启用调试模式( 可选) |
| `className` | `string` | 可选 CSS 类名( 可选) |
| `onReward` | `EventHandler` | 奖励事件召回( 可选) |
| `onError` | `EventHandler` | 错误事件召回( 可选) |
| `onBannerNotFound` | `EventHandler` | 无可用的横幅回调( 可选) |
| `onTooLongSession` | `EventHandler` | 长会话回调( 可选) |

#### 自定义

更多关于定制和槽使用的信息见 [这里](https://docs.adsgram.ai/publisher/task-integration-example#_4-customise-task-so-it-fits-your-application-design)

#### 示例

```tsx
import { JSX } from "react";
import { AdsgramTask } from '@adsgram/react';


export function Task(): JSX.Element | null {
  const handleReward = (event: CustomEvent<string>): void => {
    console.log("User earned reward:", event.detail);
  };
  
  const handleError = (event: CustomEvent<string>): void => {
    console.error("Task error:", event.detail);
  };

  return (
    <AdsgramTask blockId="task-123" className={styles.task} onReward={handleReward} onError={handleError}>
      <span slot="reward" className={styles.task__reward}>1000 coins</span>
      <div slot="button" className={styles.task__button}>go</div>
      <div slot="claim" className={styles.task__button_claim}>claim</div>
      <div slot="done" className={styles.task__button_done}>done</div>
    </AdsgramTask>
  );
}
```

### 钩子

### `useAdsgram`

管理全屏广告的回放钩. 用于 [奖励](https://docs.adsgram.ai/publisher/reward-examples) 财务报告和审定财务报表 [暂停](https://docs.adsgram.ai/publisher/interstitial-examples) 广告格式.

![Fullscreen ad](https://docs.adsgram.ai/assets/rewarded_video.CdG2Ubqt.png)

#### 道具

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `blockId` | `string` | 唯一区块ID( 需要) |
| `debug` | `boolean` | 启用调试模式( 可选) |
| `debugBannerType` | `string` | 在调试模式下强制横幅类型( 可选) |
| `onReward` | `(event: CustomEvent) => void` | 处理器 `reward` 事件(可选) |
| `onError` | `(event: CustomEvent) => void` | 处理器 `error` 事件(可选) |

#### 回返

具有控制 Adsgram 广告方法的对象 :

-   `show(): Promise<ShowPromiseResult>` ——展示广告并随结果解决.
-   `addEventListener(event: string, handler: (event: CustomEvent) => void): void` ——添加事件收听器.
-   `removeEventListener(event: string, handler: (event: CustomEvent) => void): void` 删除事件倾听器 .
-   `destroy(): void` - 摧毁广告控制器.

#### 示例

```tsx
import { JSX } from "react";
import { useAdsgram } from '@adsgram/react';

export function AdButton(): JSX.Element {
  const handleReward = (): void => {
    // user watch ad till the end
    // your code to reward user for rewarded format
  }

  const handleError = (): void => {
    // user get error during playing ad
    // do nothing or whatever you want
  },

  const { show } = useAdsgram({ blockId: '123', onReward: handleReward, onError: handleError });

  return <button onClick={show}>Show Ad</button>;
}
```

## 常见问题

### @adsgram/react 是什么？

Adsgram SDK 的回放装订\. 为广告任务和全屏横幅提供组件和钩子\.

### 如何安装 @adsgram/react？

在项目目录运行 npm install @adsgram/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @adsgram/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adsgram/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adsgram/react 可以商用吗？

@adsgram/react 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @adsgram/react 的下载量有多少？

根据 npm 官方下载统计，@adsgram/react 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,765 次，日均约 59 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adsgram/react 还在维护吗？

最新版本 1\.0\.2 发布于 2025/06/19（1\.4 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/06/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。