@giphy/react-components

中文文档
10.2.0发布于 2026/11/03MITTypeScriptESM + CJS构建来源已验证近 30 天下载 65.1万

一套轻量级组件,侧重于易用和性能.

中文使用文档
文档目录17 节
  1. GIPHY React SDK 包括了我们JavascriptFetry API中列出的所有相同的端点:
  2. 关于回扣的注释
  3. 如果反应不适合您, 请检查一下我们其他的 SDK 重置器是否更合适 :
  4. 试试看:
  5. 故事书:
  6. 网格
  7. 裸骨示例
  8. 带有下个.js的安全部门改革实例
  9. 木马
  10. 遗传
  11. 搜索经验
  12. 视频
  13. 情感变化列表
  14. 吉夫重叠
  15. 归属重叠
  16. 装入器配置
  17. 吉夫事件

@ giphy/ react- 组件

This project is using Percy.io for visual regression testing.

反应组件,侧重于易用性和性能.

GIPHY React SDK 允许您和您的用户在您网站上的任何地方轻松访问世界上最大的 GIF 库. 无论是通过评论、论坛帖、评论、聊天机还是信使.

GIPHY React SDK 包括了我们JavascriptFetry API中列出的所有相同的端点:

  • 搜索: 搜索所有 Giphy GIFs 一个单词或短语. 平按:"灵枢"作平取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.
  • 趋势 获取当前在线GIFs 趋势 。 由吉菲编辑组主持. 数据还原镜像了Giphy主页上显示的GIFs.
  • GIF 通过ID 通过 ID 获取关于 GIF 的详细信息
  • GIFs 类别和子类别 获取 GIFs 类别和子类别
  • 相关 根据 GIF 的标识获取相关的 GIF
  • 随机 返回随机单个 GIF

为了在整合前尝试出来,点击下面的代码沙盒. 在Google Chrome expension或Facebook Messent bot上.

关于回扣的注释

这个SDK以回扣的形式将分析事件发回GIPHY,帮助我们提高您的用户搜索结果的质量.

如果反应不适合您, 请检查一下我们其他的 SDK 重置器是否更合适 :

试试看:

Edit @giphy/react-components

故事书:

故事书 UI组件探索者.

网格

道具类型默认说明
宽度number未定义网格宽度
获取图像(offset:number) => Promise<GifsResult>未定义返回承诺的函数 。 使用 @giphy/js-fetch-api
栏number3个网格中的列数
地沟number6个列和行之间的间距
边框拉迪乌斯number页:1用于使角四舍五入的 Gif 组件的边框半径
无结果string or JSX.Element未定义自定义“ 无结果” 消息
装填器ElementType未定义自定义加载器,默认为 GIPHY 品牌加载器
热量string[]未定义不应懒惰地装入的 ID 数组 。 用于任何属于 SSR 的 gifs
无链接boolean虚假使用一个 div 而不是一个 a gif 组件的标记,用户定义功能时使用 onGifClick
隐藏归属boolean虚假隐藏 GIF 显示的用户属性
装入器配置IntersectionObserverInit未定义启用装入器配置以比屏幕上的时间更快取取取, 从而可以更平滑地滚动
吉夫事件* 联合国* 联合国见下文

裸骨示例

见 代码和框 可运行代码

import { Grid } from '@giphy/react-components'
import { GiphyFetch } from '@giphy/js-fetch-api'
// use @giphy/js-fetch-api to fetch gifs
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')

const searchTerm = 'dogs'
// fetch 10 gifs at a time as the user scrolls (offset is handled by the grid)
// if this function changes, change the Grid key to recreate the grid and start over
// see the codesandbox for a runnable example
const fetchGifs = (offset: number) => gf.search(searchTerm, { offset, limit: 10 })
// React Component
ReactDOM.render(<Grid width={800} columns={3} gutter={6} fetchGifs={fetchGifs} key={searchTerm} />, target)

带有下个.js的安全部门改革实例

看这个 代码和框 以下个.js为例

道具类型默认说明
双重number未定义Gi和旋转木马的高度
图像number未定义Gifs 和 carousel 的宽度( 您可能想要设置 Gif. imgClassName 具有对象适应性: 覆盖来避免拉伸)
获取图像(offset:number) => Promise<GifsResult>未定义返回承诺的函数 。 使用 @giphy/js-fetch-api
地沟number6个列和行之间的间距
边框拉迪乌斯number页:1用于使角四舍五入的 Gif 组件的边框半径
无结果string or JSX.Element未定义自定义“ 无结果” 消息
无链接boolean虚假使用一个 div 而不是一个 a gif 组件的标记,用户定义功能时使用 onGifClick
隐藏归属boolean虚假隐藏 GIF 显示的用户属性
装入器配置IntersectionObserverInit未定义启用装入器配置以比屏幕上的时间更快取取取, 从而可以更平滑地滚动
吉夫事件* 联合国* 联合国见下文

见 代码和框 为可运行代码.

或者看到我们的 故事书 UI组件探索者.

import { Carousel } from '@giphy/react-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// use @giphy/js-fetch-api to fetch gifs
const gf = new GiphyFetch('your api key')
const searchTerm = 'dogs'
// fetch 10 gifs at a time as the user scrolls (offset is handled by the grid)
// if this function changes, change the Grid key to recreate the grid and start over
// see the codesandbox for a runnable example
const fetchGifs = (offset: number) => gf.search(searchTerm, { offset, limit: 10 })
// React Component
ReactDOM.render(<Carousel gifHeight={200} gutter={6} fetchGifs={fetchGifs} key={searchTerm} />, target)

遗传

显示单个 GIF 。 建筑构件 网格 财务报告和审定财务报表 木马。如果想要构建自定义布局组件, 使用这个方法可以很容易做到.

吉卜赛道具

道具类型默认说明
数字fIGif未定义要显示的图形
宽度number未定义Gi的宽度
边框拉迪乌斯number页:1边框半径使角圆形
背景颜色string随机光线颜色装入前的背景
隐藏归属boolean虚假隐藏 GIF 显示的用户属性
无链接boolean虚假使用一个 div 而不是一个 a gif 组件的标记,用户定义功能时使用 onGifClick
懒鬼boolean真实在装入图像前检查 gif 是否在屏幕上 。 服务器端提供时设置为错误
覆盖(props: GifOverlayProps):ReactType => {}未定义见下文
吉夫事件* 联合国* 联合国见下文

见 代码和框 可运行代码

import { Gif } from '@giphy/react-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// use @giphy/js-fetch-api to fetch gifs
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')
// fetch single gif
const { data } = await gf.gif('fpXxIjftmkk9y')
// React Component
ReactDOM.render(<Gif gif={data} width={300} />, target)

搜索经验

搜索体验基于一个搜索栏和一个单独的可显示内容的视觉组件,可以是 网格 或者说 木马,或自定义组件,该组件可以获取和制取一组 IGif 对象。 为了创造搜索经验,我们使用 React.Context 将搜索栏与其他部分确定为 " 儿童 " ,从而建立联系 搜索文本管理器我们建议使用 建议栏 在用户名搜索时显示趋势搜索,并允许用户名搜索(例如:. @nba) (中文(简体) ).

见 代码和框 可运行代码

import {
    Grid, // our UI Component to display the results
    SearchBar, // the search bar the user will type into
    SearchContext, // the context that wraps and connects our components
    SearchContextManager, // the context manager, includes the Context.Provider
    SuggestionBar, // an optional UI component that displays trending searches and channel / username results
} from '@giphy/react-components'

// the search experience consists of the manager and its child components that use SearchContext
const SearchExperience = () => (
    <SearchContextManager apiKey={webSDKKey}>
        <Components />
    </SearchContextManager>
)

// define the components in a separate function so we can
// use the context hook. You could also use the render props pattern
const Components = () => {
    const { fetchGifs, searchKey } = useContext(SearchContext)
    return (
        <>
            <SearchBar />
            <SuggestionBar />
            {/**
                key will recreate the component,
                this is important for when you change fetchGifs
                e.g. changing from search term dogs to cats or type gifs to stickers
                you want to restart the gifs from the beginning and changing a component's key does that
            **/}
            <Grid key={searchKey} columns={3} width={800} fetchGifs={fetchGifs} />
        </>
    )
}

搜索文本管理器

本构成部分管理 搜索语句 儿童参与其中.

它有一些初始化道具:

道具类型默认说明
键字符串未定义你的网络SDK密钥 每个平台(Android、iOS、Web)使用单独的密钥
初始任期字符串''高级用途 当组件被挂载时获取和渲染的搜索名词
应解答错误布尔真实如果没有搜索术语,请获取趋势(包括 options 相关,例如限制、类型)
应选通道布尔真实在术语更改时获取频道, 使其能在建议栏中显示 。 如果搜索名词是 @ term, 找到匹配的频道, 搜索栏将以频道模式显示
主题搜索主题默认主题搜索栏高和黑暗或光线模式等几个主题选项
选项搜索选项未定义将传递到搜索请求的搜索选项

用于 搜索经验。 。 。 .

道具类型默认说明
占位符stringSearch GIPHY未输入文本时显示的文本
主题SearchTheme默认主题见(搜索主题)[#搜索主题]
清除boolean虚假高级使用 - 清除输入,但将把术语留在搜索语句中

搜索语句

这个 SearchContext 管理搜索体验的状态。 下面的道具是您需要配置的用户界面组件的全部 。 见 (搜索经验) [#搜索-经验]. 应该用 searchKey 作为它的关键, 所以当我们有了新的搜索, 旧的内容被删除。 它需要一个 fetchGifs 以启动第一个抓取,然后用于无限滚动取取

道具类型默认说明
搜索键字符串未定义在当前搜索中独有的 ID, 用作刷新 网格
已锁定布尔虚假搜索输入是否有焦点
当前通道频道[在当前搜索术语下找到的一系列频道
获取图像(offset: number) => Promise<GifsResult>默认搜索抓取搜索请求传递给UI 组件

搜索主题

主题传递到 搜索文本管理器

道具类型默认说明
模式dark | lightlight黑暗或光线
搜索栏高度编号第42条搜索栏的高度
小搜索栏高度编号35个匹配移动媒体查询时搜索栏的高度

建议栏

显示滚动趋势搜索和用户名搜索 。 点击趋势搜索词时, 搜索输入将是 将进行搜索并完成搜索.

如果用户将用户名输入搜索栏, 如 @nba,将进行用户名搜索,所有匹配的频道将在建议栏中显示。 点击用户名时, 搜索栏将进入用户名搜索模式 .

视频

快速轻松地播放视频. 只要通过视频组件 一个有视频属性的gif对象。 这在使用时是真实的 { type: 'videos' } 输入 获取 api 类型选项。 。 。 .

如果您想要控制视频播放器, 请使用 controls 属性.

这是我们行动的组成部分 故事书

视频道具

道具类型默认说明
数字fIGif未定义包含视频数据的显示方式
宽度number未定义视频的宽度
高度number未定义视频的高度
控件boolean未定义显示传输控制
隐藏进度栏boolean未定义如果控件属实,请隐藏进度栏
隐藏穆特boolean未定义如果控件属实, 请隐藏哑巴按钮
隐藏播放暂停boolean未定义如果控件属实,请隐藏播放/暂停按钮
持久性控制boolean未定义晃来晃去时不要隐藏控制
可启用boolean虚假如果为真,则显示标题
cc 语言string'来'关闭字幕语言
用户已挂载(muted: boolean) => void未定义用户切换哑声状态时开火
运行React.ReactEventHandler<HTMLVideoElement>未定义本地语言 playing 事件: 回放开始或恢复
登录数据React.ReactEventHandler<HTMLVideoElement>未定义本地语言 loadeddata 事件: 现有框架数据
在LoadedMetata数据上React.ReactEventHandler<HTMLVideoElement>未定义本地语言 loadedmetadata 事件: 媒体元数据可用

这些回调接收回调媒体事件; 同步读取视频元素 event.currentTarget,包括: event.currentTarget.duration 内 onLoadedMetadata. 可用或不可用控制. onPlaying 可以在暂停或缓冲后恢复播放时再次开火. onLoadedData 显示当前框架数据准备状态,而不是显示一个框架已被涂入屏幕.

现有回调保留其含义: onStateChange('playing') 和第一个 onFirstPlay 通知由本地人驱动 play 事件,可在 playing。 。 。 .

import { Video } from '@giphy/react-components'
import { GiphyFetch } from '@giphy/js-fetch-api'

// use @giphy/js-fetch-api to fetch gifs
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')

const { data } = await gf.gif('D068R9Ziv1iCjezKzG')
// React Component
ReactDOM.render(<Video gif={data} width={300} controls />, target)

情感变化列表

此组件旨在显示一个给定的emoji的变体列表.

这是我们行动的组成部分 故事书

道具类型默认说明
获取变量(gifId: GifID) => Promise<NonPaginatedGifsResult>未定义自动调回应返回 emoji 变异 。 使用 @giphy/js-fetch-api
数字fIGif未定义指定要显示变量的图形
双重number未定义列表中的高地
图像number未定义列表中的 gifs 宽度
背景颜色string"#2e2e2e" (中文(简体) )设置列表的背景颜色
分页颜色string#设置分隔符的颜色
地沟number6个Gi之间的空间
装填器ElementType未定义指定装入器
无链接boolean虚假使用一个 div 而不是一个 a gif 组件的标记,用户定义功能时使用 onGifClick
变化(gifs: IGif[]) => void未定义获取变量时将调用回调
隐藏归属boolean虚假隐藏 GIF 显示的用户属性
工具GifProps未定义适用于 遗传 元素
吉夫事件* 联合国* 联合国见下文

示例数字 :

import React, { useState } from 'react'
import ReactDOM from 'react-dom'
import { GiphyFetch } from '@giphy/js-fetch-api'
import { EmojiVariationsList, Grid } from '@giphy/react-components'
import type { GifID, IGif } from '@giphy/js-types'

// use @giphy/js-fetch-api to fetch gifs
// apply for a new Web SDK key. Use a separate key for every platform (Android, iOS, Web)
const gf = new GiphyFetch('your Web SDK key')

const fetchDefaultVariations = (offset: number) => gf.emojiDefaultVariations({ offset })
const fetchVariations = (id: GifID) => gf.emojiVariations(id)

export function Example() {
    const [gif, setGif] = useState<IGif | null>(null)
    return (
        <>
            {gif ? <EmojiVariationsList fetchVariations={fetchVariations} gif={gif} gifHeight={100} /> : null}
            <Grid
                columns={3}
                fetchGifs={fetchDefaultVariations}
                hideAttribution={true}
                noLink={true}
                onGifClick={setGif}
                width={400}
            />
        </>
    )
}

ReactDOM.render(<Example />, target)

吉夫重叠

覆盖道具,在所有组件上都可以使用,它允许您用自定义的UI来覆盖一个gif,并对徘徊事件(只有桌面)作出反应.

重叠道具

道具类型默认说明
数字fIGif未定义正在显示的图形
已覆盖boolean虚假当前徘徊状态

见 代码和框 可运行代码

/* css for overlay */
.overlay {
    position: absolute;
    left: 0;
    top: 0;
    right: 0;
    bottom: 0;
    background: rgba(0, 255, 0, 0.3);
    display: flex;
    color: white;
    justify-content: center;
    align-items: center;
}
// Overlay component gets GifOverlayProps
const Overlay = ({ gif, isHovered }: GifOverlayProps) => {
    return <div className="overlay">{isHovered ? gif.id : ''}</div>
}

// React component
ReactDOM.render(<Carousel gifHeight={200} fetchGifs={fetchGifs} overlay={Overlay} />, target)

归属重叠

如果一个GIF有一个关联的用户,将会出现一个带有其外观和显示名的覆盖. 这个可以隐藏 hideAttribution 任何组件。 如果你自己提供 覆盖,属性将自动隐藏

装入器配置

如果您想在装入器出现于 Grids 和 Carousels 之前预先调试网络请求, 您可以通过配置来做到这一点 loaderConfig。这个配置实际上是传递给 交叉观察员,它负责监视装入器,并在屏幕上出现时发射一个事件。 此配置在一个名为 util 组件中 观察员

吉夫事件

道具类型说明
图像(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => void每次出现就开枪了
在吉夫赛恩(gif: IGif, boundingClientRect: ClientRect &#124; DOMRect) => void盖夫装入后发射一次 当它完全进入视野时
在吉夫克时(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => void点击 gif 时开火
右键(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => void当 gif 右键点击时开火
吉普车(gif: IGif, e: SyntheticEvent<HTMLElement, Event>) => void键被按在被键上时开火

停止字体装入设置环境变量 GIPHY_SDK_NO_FONTS=true,因此不建议这样做,因为这可能造成ui组件的不一致

版本与发布记录

@giphy/react-components 共发布 209 个版本,首次发布于 2019/06/27;过去 12 个月发布了 3 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
10.2.0latest2026/11/0313 天前
10.1.22026/04/246 个月前
10.1.12025/12/2010 个月前
10.1.02025/07/091.4 年前
0.0.0-hidden-gifs-20250701132558hidden-gifs2025/07/011.4 年前
0.0.0-hidden-gifs-202506302035092025/07/011.4 年前

其他发布通道:moat-beta → 0.3.1-alpha.1,canary → 0.0.0-canary-20230621031504,charlie → 9.5.0-charlie.0,moat-testing → 0.0.0-moat-testing-20240502211419,beta → 10.0.1-beta.0,hidden-gifs → 0.0.0-hidden-gifs-20250701132558。

关于 @giphy/react-components 的常见问题

@giphy/react-components 是什么?

一套轻量级组件,侧重于易用和性能.

如何安装 @giphy/react-components?

在项目目录运行 npm install @giphy/react-components,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(18 - 19)、styled-components(>= 5)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@giphy/react-components 支持 TypeScript 吗?

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

@giphy/react-components 支持 ESM 还是 CommonJS?

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

@giphy/react-components 可以商用吗?

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

@giphy/react-components 的下载量有多少?

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

@giphy/react-components 还在维护吗?

最新版本 10.2.0 发布于 2026/11/03(13 天前);至今共发布 209 个版本,其中过去 12 个月发布了 3 个;首次发布于 2019/06/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。