# @gravity-ai/react 中文文档

规范地址：https://npmcn.com/package/%40gravity-ai/react/

版本：1\.7\.0
npm 元数据更新时间：2026-11-15T06:19:10.727Z
中文译文更新时间：2026-11-16T23:36:28.657Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：666 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：react \>=17\.0\.0
- 首次发布：2025-11-26T23:46:33.881Z
- 最新版本发布：2026-11-15T06:19:10.525Z
- 近 30 天下载量：639083（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

渲染重力AI广告的反应组件

## 安装

```sh
npm install @gravity-ai/react
```

也可以使用：`pnpm add @gravity-ai/react`、`yarn add @gravity-ai/react`、`bun add @gravity-ai/react`

## README

# @ gravity-ai/反应

以自动印象和点击跟踪方式渲染重力广告的回放组件.

关于经主机同意的作曲插入,见 [即时行动广告](https://npmcn.com/package/%40gravity-ai/react/ACTIONS.md)。 。 。 .

## 安装

```bash
npm install @gravity-ai/react
```

> 对等依赖:反应17+

## 快速启动

```tsx
import { GravityAd } from '@gravity-ai/react';

function ChatResponse({ ads }) {
  return ads.map((ad, i) => <GravityAd key={i} ad={ad} />);
}
```

就是这样。 当响应包含服务器交付时 `renderer_spec`,组件验证并使得投放设计。 否则,它会回到被捆绑的牌。 它在广告滚动到视图时会自动放出印象像素.

## API 响应形状

组件期望重力 API 返回的对象 :

```ts
interface AdResponse {
  adText: string;
  title?: string;
  cta?: string;
  brandName?: string;
  url?: string;
  favicon?: string;
  impUrl?: string;    // impression tracking pixel
  clickUrl?: string;  // tracked click-through URL
  renderer_spec?: RendererSpec | string; // optional server-delivered placement design
}
```

## 构成部分

### `<GravityAd />`

带有自动印象/点击跟踪功能的全功能化广告渲染器. Bundled变体使用内置样式;服务器交付设计使用经验证的内置声明外加可选语义CSS变量. 不需要CSS-in-JS运行时间.

```tsx
<GravityAd
  ad={ad}
  // Leave `variant` unset to accept the placement's server-delivered design.
  showLabel={true}
  labelText="Sponsored"
  openInNewTab={true}
  onImpression={() => console.log('seen')}
  onClickTracked={() => console.log('clicked')}
/>
```

**备选案文:**

| 备选案文 | 说明 |
| --- | --- |
| `card` | 默认. 带有边框、阴影和粘贴的垂直卡. |
| `inline` | 侧边栏或工具栏的水平布局 . |
| `minimal` | 没有边框 影子 也没有背景 有主机内容的混合. |

通过 `variant` 刻意地将其中一副被捆绑的相片接上,忽略 `renderer_spec`。只有在出版商必须拥有本地版式时才使用.

### MCP 连接广告

过 `onConnect` 当您的应用程序有 MCP 客户端时 。 带有效广告的广告 `connect` 有效载荷(`type: 'mcp'`,一个 https `serverUrl`页:1 `name`,可选的 https `iconUrl`按钮复制到 `cta` 然后制作一个连接卡片:品牌、标题、身体和一个贴有标签的按钮 `cta`。该卡没有添加自己的文本.

```tsx
<GravityAd
  ad={ad}
  onConnect={(request) => connectMcpServer(request.serverUrl, request.name)}
/>
```

`onConnect` 接收 `{ id, serverUrl, name, iconUrl? }` 返回时 `{ status: 'connected' | 'declined' | 'failed' }`直接或作为承诺。 它在点击器内同步运行, 所以在任何开始前打开 OAuth 弹出 `await`。每次连接点击的背景中,跟踪点击点火。 没有网站倒退:当结果是 `declined` 或者说 `failed`,或者回调投出,没有打开,卡片保持不变,所以用户可以再次尝试. 当连接等待重用时, 重复点击 。 无 `onConnect`或带有无效有效载荷,该广告作为普通广告制作。 当广告同时带有可用即时动作和可使用连接时,连接卡只在 `onConnect` 已经设定.

此组件仅使: 声明 `supportsMcpConnect: true` 匹配您的广告请求的位置( t)`@gravity-ai/ui`自我牵引 `GravityAd` 做这个给你,当 `onConnect` 已设定).

#### 让SDK运行登录

`createMcpConnectHandler` 构建一个 `onConnect` 在浏览器中运行整个MCP授权的处理器,并将连接交给您自己MCP客户端. 它在点击中打开了弹出,发现了服务器的授权服务器(RFC 9728 保护资源元数据,后为 RFC 8414 授权服务器元数据),通过动态客户端注册在下面注册您的应用 `clientName`,将用户与PKCE(S256)一起送入广告商的同意屏幕 `state` 第8707号条例 `resource`,然后将返回的代码交换为符号.

```tsx
import { GravityAd, createMcpConnectHandler, type McpConnection } from '@gravity-ai/react';

const onConnect = createMcpConnectHandler({
  clientName: 'Acme Chat',
  redirectUri: `${window.location.origin}/mcp/callback`,
  attribution: () => ({ utm_source: 'acme-chat', utm_medium: 'chat' }),
  onConnected: async (connection: McpConnection) => {
    await mcpHub.add({
      name: connection.name,
      url: connection.serverUrl,
      headers: connection.headers,
      oauth: connection.oauth,
    });
  },
});

<GravityAd ad={ad} onConnect={onConnect} />
```

每个连接在自己的弹出中运行,只接受从弹出回调. 保护资源元数据必须命名 MCP 服务器本身( 来源相同, 服务器路径等于或低于元数据) `resource` 因此,服务器不能为另一个服务器的资源发布一个符号。 每个请求在15秒后放弃.

结果是 `connected` 一次 `onConnected` 决定, `declined` 当用户关闭弹出(在召回之前的任何时候,也取消仍在运行的请求)或拒绝同意时,以及 `failed` 否则(无 OAuth 元数据, a) `resource` 无法匹配服务器、被屏蔽的弹出、被拒绝的注册或令牌交换、a `state` 不匹配,或 `onConnected` 抛出。 该连接是:

```ts
{
  serverUrl: string;
  name: string;
  headers: { Authorization: 'Bearer …' };
  oauth: { tokenEndpoint: string; clientId: string; refreshToken?: string; expiresAt?: number; resource: string };
}
```

选项 :

| 选项 | 目的 |
| --- | --- |
| `clientName` | 你的应用软件的名字,显示在广告商的同意屏幕上. |
| `redirectUri` | 关于您自己来源的页面 `completeMcpConnectCallback()`。 。 。 . |
| `clientId` | 在广告商注册的客户身份; 跳过动态客户注册 . |
| `attribution` | 返回授权 URL 的跟踪参数。 仅 `utm_source`, (中文(简体) ), `utm_medium`, (中文(简体) ), `utm_campaign`, (中文(简体) ), `utm_content`, (中文(简体) ), `utm_term` 财务报告和审定财务报表 `grclid` ,所以它永远不能覆盖 OAuth 参数. |
| `fetch` | 替换 `fetch` 用于发现、登记和信使呼叫(见下文CORS). |
| `onConnected` | 接收连接和原始请求. |

重定向页面只需调用 `completeMcpConnectCallback()` 一旦它装入。 它发布代码, `state` 和在同一源头打开器的任何错误,从地址栏中删除并关闭弹出:

```tsx
// app/mcp/callback/page.tsx
'use client';
import { useEffect } from 'react';
import { completeMcpConnectCallback } from '@gravity-ai/react';

export default function McpCallback() {
  useEffect(() => { completeMcpConnectCallback(); }, []);
  return <p>Connecting…</p>;
}
```

在访问符前刷新 `oauth.expiresAt` 与 `refreshMcpConnection`,它使用刷新脚本授予并返回更新的连接(当没有刷新符号或服务器拒绝时它拒绝):

```ts
import { refreshMcpConnection } from '@gravity-ai/react';

if (connection.oauth.expiresAt && connection.oauth.expiresAt - Date.now() < 60_000) {
  connection = await refreshMcpConnection(connection);
  await mcpHub.update(connection);
}
```

处理器从不登录携带的符号,代码或URL. 存储 `headers` 财务报告和审定财务报表 `oauth` 你存储其他证书的方式.

**科斯特语.** 浏览器直接调用MCP服务器的元数据,注册端点和符号端点,因此它们必须允许交叉发端请求. 许多人这样做(MCP的参考服务器和Exa的符号端点做),但有些人没有: Exa的注册端点(E`https://auth.exa.ai/api/oauth/register`)不发送 CORS 头,所以从浏览器中注册失败。 对于此类服务器,通过 a `clientId` 提前登记或通过 `fetch` 通过您自己的服务器转发电话:

```ts
const relayFetch: typeof fetch = (input, init) =>
  fetch('/api/mcp-oauth-relay', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      url: String(input),
      method: init?.method ?? 'GET',
      headers: init?.headers,
      body: init?.body,
    }),
  });

const onConnect = createMcpConnectHandler({ clientName: 'Acme Chat', redirectUri, fetch: relayFetch, onConnected });
const refreshed = await refreshMcpConnection(connection, { fetch: relayFetch });
```

中继器将请求转发至 `url` 并返回上游状态, `WWW-Authenticate` 头和身体。 URL来自广告商的元数据,所以让中继器只接触到公共的https主机,而永远不要转发自己的饼干或证书.

### 服务器交付的放置设计

重力可以附加一个版本 `renderer_spec` 对广告回应。 何时 `variant` 是未设置的, `<GravityAd>`数字 :

1.  解析和结构验证光谱.
2.  确定内容具有约束力(`title`, (中文(简体) ), `adText`, (中文(简体) ), `cta`, (中文(简体) ), `brandName`, (中文(简体) ), `favicon`, (中文(简体) ), `url`) (中文(简体) ).
3.  应用出版商的语义主题变量.
4.  通过一个安全的节点白名单( R)`box`, (中文(简体) ), `text`, (中文(简体) ), `image`, (中文(简体) ), `link`) (中文(简体) ).
5.  掉回捆绑的地方 `card` 如果光谱不正确或解析为无内容,则生成器.

标准卡光谱使用一个根链接 `url`,所以整个可见的广告路线通过 `clickUrl`它从不筑起锚 光谱必须包括明显的披露,例如: `AD`, (中文(简体) ), `Sponsored`, (中文(简体) ), `Promoted`,或 `Paid`如果缺少披露,SDK会覆盖其内置的广告徽章.

网络广告请求应当发送 `specCapabilities: "web1"` (而且不能发送) `supportsSpec: false`) (中文(简体) ). 现有发送两个字段的集成仍为后相兼容,被作为出版商放置默认的可网络能力处理.

服务器设计采用这些可选主机变量,倒回SDK调色板:

| 变量 | 目的 |
| --- | --- |
| `--gravity-bg` | 纸牌/背景表面 |
| `--gravity-text` | 主要案文 |
| `--gravity-text-muted` | 副文本 |
| `--gravity-accent` | CTA/百分数 |
| `--gravity-accent-foreground` | 重音文字 |
| `--gravity-muted` | 静态表面 |
| `--gravity-border` | 边框 |
| `--gravity-radius` | 卡片半径 |

当a `--gravity-*` 变量缺失,渲染器使用匹配的主机变量(`--card`, (中文(简体) ), `--foreground`, (中文(简体) ), `--primary`等)于其字形倒置前.

### 数据绘制单位

当广告携带 `unit` 财务报告和审定财务报表 `variant` 是未设置的, `<GravityAd>` 以符合容器活宽度的布局来绘制,而当宽度跨出布局边界时会回流. 单位取出主机页面的光或暗面,文字颜色和字体; 2; `--gravity-accent` 财务报告和审定财务报表 `--gravity-radius` 设置按钮颜色和角半径. `rich_frame` 在框架主机中渲染的单位, a `action_card` 按钮运行 `onPrompt`,则a `connect_card` 按钮运行 `onConnect`。一个单位类型或版本的 SDK 并不知道绘图是纯文本卡。 印象和点击跟踪工作 相对于其他的广告,和没有 `unit` 和以前一样.

如果您自己获取广告,请在每次请求的放置中添加一个单元所需的内容 `getPlacementContext`数字 :

```ts
import { getPlacementContext } from '@gravity-ai/react';

const placements = [{
  placement: 'below_response',
  placement_id: 'main',
  ...getPlacementContext(slotRef.current, { promptAction: !!onPrompt, mcpConnect: !!onConnect }),
}];
```

它返回槽宽度、主机字体和主题以及能力 `<GravityAd>` 绘图( e)`frames` 默认为 `true`匹配 `enableFrames`) (中文(简体) ). 它从不扔出; 它只在服务器上返回 `capabilities`。 。 。 .

### 风格与 `style` 财务报告和审定财务报表 `slotProps`

以 `style` 道具 :

```tsx
<GravityAd ad={ad} style={{ maxWidth: 400, borderRadius: 16 }} />
```

以 `slotProps`数字 :

```tsx
<GravityAd
  ad={ad}
  slotProps={{
    cta: { style: { background: '#E11D48', borderRadius: 999 } },
    label: { style: { display: 'none' } },
    title: { style: { fontSize: 16 } },
  }}
/>
```

每个 `slotProps` dOM 元素的密钥映射 :

| 密钥 | 元素 | 它控制着什么 |
| --- | --- | --- |
| `container` | 外部 `<a>` | 与顶级相同 `style` 道具 |
| `inner` | 包装纸 `<div>` | 布局、 补丁、 间隙 |
| `header` | 页眉行 `<div>` | 法维康+品牌+标签行 |
| `favicon` | 法维孔 `<img>` | 大小, 边框射线 |
| `brand` | 品牌名称 `<span>` | 字体, 颜色 |
| `label` | "赞助" `<span>` | 药丸型,能见度 |
| `body` | 身体包装器 `<div>` | 标题+文本布局 |
| `title` | 标题 `<p>` | 字体, 颜色 |
| `text` | 附加文本 `<p>` | 字体, 颜色 |
| `cta` | CTA 按钮 `<span>` | 背景、 边线、 垫地 |

每个槽接受 `{ style?: CSSProperties; className?: string }`。 。 。 .

关于带有DOM结构和通用食谱的完整型式指南,见 **[击打.md](https://npmcn.com/package/%40gravity-ai/react/STYLING.md)**。 。 。 .

### `<GravityLeadFormAd />` (折旧)

铅表已退役。 服务器不再返回 `leadForm` 在广告上,和 `<GravityLeadFormAd />` 使无所事事。 使用 `<GravityAd />` 换句话说.

### `<AdText />`

无法使用的文本只渲染器 。 需要完全控制演示文稿时使用 .

```tsx
<AdText
  ad={ad}
  className="my-custom-style"
  style={{ fontSize: 14 }}
/>
```

渲染器 `ad.adText` 作为链接(如果 `clickUrl` 或间距。 没有超出内置样式 `text-decoration: none; color: inherit`。 。 。 .

## 印象跟踪

两个部件都使用 `IntersectionObserver` 点出印象像素 **只当广告实际可见时** 切换到用户(视图端的50%元素)。 这比起上山起火有了显著的改善——出版商不会报告在折叠线下所制作的广告的印象,这是从未见过的.

每条广告的印象就喷出一次 如果广告对象改变( 不同) `impUrl`),新广告的追踪重回.

比尔林不变:印象像素(`impUrl`火力和以前一样 像素仍然点出 50% 的广告进入取景口(或者在上架的地方) `IntersectionObserver` 页:1 另外,SDK将阴影可视性信标发送到同一个 URL `ev=measured`, (中文(简体) ), `sdk` 财务报告和审定财务报表 `sv` 当像素起火时查询参数,以及 `ev=viewable` 一次至少50%的广告已经查看了1个连续第二个(MRC可观印象). 信标只是测量,绝不影响计费. 投放到50%以下或隐藏标签会重新启动1秒; 没有信标发送到哪里 `IntersectionObserver` 无法使用.

要禁用自动跟踪 :

```tsx
<GravityAd ad={ad} disableImpressionTracking />
```

## 钩子

### `useAdTracking`

用于构建完整自定义广告组件的低级钩子 :

```tsx
import { useAdTracking } from '@gravity-ai/react';

function CustomAd({ ad }) {
  const { containerRef, handleClick } = useAdTracking({
    ad,
    onImpression: () => console.log('impression fired'),
    onClickTracked: () => console.log('click tracked'),
  });

  return (
    <a ref={containerRef} href={ad.clickUrl} onClick={handleClick}>
      {ad.adText}
    </a>
  );
}
```

钩子返回 :

-   `containerRef` - 附属于基于互通区观察员的印象跟踪 DOM 元素
-   `handleClick` ——点击点击启动点击跟踪回调
-   `impressionFired` ——布尔表示印象是否已经发出

## 许可证

麻省理工学院

## 常见问题

### @gravity-ai/react 是什么？

渲染重力AI广告的反应组件

### 如何安装 @gravity-ai/react？

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

### @gravity-ai/react 支持 TypeScript 吗？

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

### @gravity-ai/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gravity-ai/react 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gravity-ai/react 可以商用吗？

@gravity-ai/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ai/react 的下载量有多少？

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

### @gravity-ai/react 还在维护吗？

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

