@gravatar-com/hovercards

中文文档
0.17.0发布于 2026/10/30GPL-2.0-or-laterTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 5247

在 Gravatar 图像中添加配置悬浮卡 .

中文使用文档
文档目录14 节
  1. 目录
  2. 安装
  3. 用国家防范机制或Yarn安装
  4. 用 UNPKG 安装
  5. 香草 Java 脚本
  6. 使用量
  7. API 密码
  8. 反应
  9. 反应组件
  10. 反应钩
  11. 类型脚本
  12. 翻译
  13. 贡献给 Gravatar 车卡
  14. 许可证

重力高通卡

npm build release package size downloads downloads

Gravatar Hovercards是一个方便使用的图书馆,它带来 重力 访问您的网站。 它能转换静态 重力图像,或带有 data-gravatar-hash 属性 进入交互式悬牌.

目录

安装

这个Gravatar Hovercards 库既支持 Vanilla JavaScript (包括 类型脚本和 反应。通过 雅伦, (中文(简体) ), 国家预防机制,或直接通过 联科办 疾控网.

用国家防范机制或Yarn安装

将软件包添加到您的工程中 :

npm install @gravatar-com/hovercards

或者说

yarn add @gravatar-com/hovercards

反应,也添加 react 财务报告和审定财务报表 react-dom (单位:千美元)v16.8.0 或以上:

npm install add react react-dom @gravatar-com/hovercards

用 UNPKG 安装

对于香草JavaScript,导入库如下:

<!-- Import the hovercard styles -->
<link rel="stylesheet" href="https://unpkg.com/@gravatar-com/[email protected]/dist/style.css">

<!-- Import the hovercards library -->
<script src="https://unpkg.com/@gravatar-com/[email protected]" defer></script>

<script>
  // The library is accessible as a global variable
  console.log( Gravatar );
</script>

对于反应,导入库如下:

<link rel="stylesheet" href="https://unpkg.com/@gravatar-com/[email protected]/dist/style.css">

<!-- Ensure React and ReactDOM are imported before the library -->
<script src="https://unpkg.com/[email protected]" defer></script>
<script src="https://unpkg.com/[email protected]" defer></script>
<!-- Import the React hovercards library -->
<script src="https://unpkg.com/@gravatar-com/[email protected]/dist/index.react.umd.js" defer></script>

<script>
  console.log( Gravatar );
</script>

替换 x.x.x 带有最新版本编号。 请参看UNPKG的 文档 更多信息.

香草 Java 脚本

使用量

您可以使用已有的Gravatar 图像, 或者在任意元素中添加一个数据属性, 在您的页面中添加悬浮卡 .

1. 引力图像

确保您的页面包含 Gravatar 图像 。 这些图像的URL应当包含散列的电子邮件地址. 欲了解更多信息,请参考 gravatar 图像执行指南。 。 。 .

例如:

<div id="container">
    <img id="avatar-1" src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image">
    <img id="avatar-2" src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image">

    <!-- Image URL with specified parameters -->
    <img id="avatar-3" src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>?s=250&d=retro&r=pg" alt="Gravatar Image">
</div>

这些可以变成悬牌:

import { Hovercards } from '@gravatar-com/hovercards';
// Import the hovercard styles
import '@gravatar-com/hovercards/dist/style.css';

document.addEventListener( 'DOMContentLoaded', () => {
    // Start the hovercards feature with your preferred settings
    const hovercards = new Hovercards( { /* Options */ } );

    // Make hovercards work on a specific Gravatar image
    hovercards.attach( document.getElementById( 'avatar-1' ) );

    // Alternatively, make hovercards work on all Gravatar images within a specific container
    hovercards.attach( document.getElementById( 'container' ) );

    // If you want hovercards on all Gravatar images across the entire page, use `document.body` as the target
    hovercards.attach( document.body );

    // You can exclude certain Gravatar images from hovercards by using `ignoreSelector`
    hovercards.attach( document.body, { ignoreSelector: '.ignore img[src*="gravatar.com/avatar/"]' } );
} );

2. 具备下列条件的要件: data-gravatar-hash 属性

或者,使用 data-gravatar-hash 属性以指定任意元素的重力散列。 这将自动转换成交互式悬牌 .

注意:数据属性优先于图像 URL.

例如:

<div id="container">
    <div id="ref-1" data-gravatar-hash="<HASHED_EMAIL_ADDRESS>">@Meow</div>
    <div id="ref-2" data-gravatar-hash="<HASHED_EMAIL_ADDRESS>">@Woof</div>

    <!-- A hash with specified parameters -->
    <div id="ref-3" data-gravatar-hash="<HASHED_EMAIL_ADDRESS>?s=250&d=retro&r=pg">@Haha</div>
</div>

要将这些元素转换成交互式悬牌:

import { Hovercards } from '@gravatar-com/hovercards';
import '@gravatar-com/hovercards/dist/styles.css';

document.addEventListener( 'DOMContentLoaded', () => {
    // Start the hovercards feature with your preferred settings
    const hovercards = new Hovercards( { /* Options */ } );

    // Attach hovercards on a specific image
    hovercards.attach( document.getElementById( 'ref-1' ) );

    // Attach to all images within a container
    hovercards.attach( document.getElementById( 'container' ) );

    // Attach to all images on the page
    hovercards.attach( document.body );
} );

API 密码

选项

您可以将选项对象传递到 Hovercards 用于定制您悬牌的行为的构造器 。 有以下备选方案:

placement: string = 'right-start'

相对于目标元素的悬牌位置. 可能值为 top, (中文(简体) ), bottom, (中文(简体) ), left, (中文(简体) ), right, (中文(简体) ), top-start, (中文(简体) ), top-end, (中文(简体) ), bottom-start, (中文(简体) ), bottom-end, (中文(简体) ), left-start, (中文(简体) ), left-end, (中文(简体) ), right-start,以及 right-end。 。 。 .

autoFlip: boolean = true

确定在显示空间不足时,悬牌的位置是否应当自动翻转 .

autoShift: boolean = true

确定在显示空间不足时,徘徊卡的位置是否应当自动转移.

hideOnTargetClick: boolean = false

当触发元素被点击时隐藏悬牌.

offset: number = 10

相对于目标元素的悬牌相抵,以像素为单位.

delayToShow: number = 500

显示悬牌前以毫秒计的延迟.

delayToHide: number = 300

悬牌被隐藏之前以毫秒计的延迟.

i18n: Record< string, string >

翻译文本字符串以代替默认的英语 .

additionalClass: string = ''

在悬牌最外侧元素中添加额外的类名. 这对于自定义悬牌的外形很有用.

myHash: string = ''

它能够使悬浮卡特性具有个性化 当前用户当用户的“关于我”字段空出时,它允许显示“编辑您的配置”等定制选项 重力编辑页面。 。 。 .

onQueryHovercardRef: ( ref: HTMLElement ) => HTMLElement

当库查询到一个悬浮卡回路(或Gravatar 图像)时,此回路功能被触发,允许您自定义回路元素 。 该函数作为参数收到 ref 元素,并应当返回该元素的修改后版本.

onFetchProfileStart: ( hash: string ) => void

当库开始获取Gravatar profile时会触发这个回调功能. 它以"重力散列"为参数. 注意,由于缓存机制,此函数只执行一次.

onFetchProfileSuccess: ( hash: string, profileData: ProfileData ) => void

当库成功获取Gravatar配置文件时会触发这个回调功能. 它以"重力散列"和剖面数据作为参数. 注意,由于缓存机制,此函数只执行一次.

这个 profileData 参数是一个包含以下属性的对象:

interface ProfileData {
    hash: string;
    avatarUrl: string;
    profileUrl: string;
    displayName: string;
    location?: string;
    description?: string;
    jobTitle?: string;
    company?: string;
    headerImage?: string;
    hideDefaultHeaderImage?: boolean;
    backgroundColor?: string;
    verifiedAccounts?: Record< 'label' | 'icon' | 'url' | 'type', string >[];
    contactInfo?: ContactInfo;
    payments?: Payments;
}
onFetchProfileFailure: ( hash: string, error: FetchProfileError ) => void

当库无法获取Gravatar profile时会触发这个回调功能. 它以"重力散列"和"错误"作为参数. 注意由于缓存机制, 此函数只执行一次 .

这个 error 参数是一个包含以下属性的对象:

interface FetchProfileError {
    code: number;
    message: string;
}
onHovercardShown: ( hash: string, hovercard: HTMLDivElement ) => void

显示悬牌时会触发这个回调功能. 它以"重力散列"和"悬浮卡"元素作为参数.

onHovercardHidden: ( hash: string, hovercard: HTMLDivElement ) => void

当悬牌被隐藏时会触发这个回调功能. 它以"重力散列"和"悬浮卡"元素作为参数.

onCanShowHovercard: ( hash: string ) => bool

这个回调功能是在显示悬牌之前触发的,在运行时会给予您对卡片的控制. 它需要重力散列并返回布尔值。 如果返回的值是 false 然后卡片就不会显示.

方法

这个 Hovercards 分类提供以下方法:

(static) createHovercard( profileData: ProfileData, options?: { additionalClass?: string; myHash?: string, i18n?: Record< string, string > } ): HTMLDivElement

这种方法利用所提供的剖面数据生成了悬浮卡元素. 它接受 profileData 参数,它代表了弹出悬浮卡所需的数据,以及一个可选选项对象,可以包含诸如 additionalClass, (中文(简体) ), myHash 财务报告和审定财务报表 i18n。当您想要在您的网站上显示静态悬浮卡时,它很有用.

import { Hovercards } from '@gravatar-com/hovercards';

const hovercard = Hovercards.createHovercard( {
    hash: '...',
    avatarUrl: '...',
    profileUrl: '...',
    displayName: '...',
    description: '...',
    location: '...',
    jobTitle: '...',
    company: '...',
    verifiedAccounts = [ {
        label: '...',
        icon: '...',
        url: '...',
        type: '...',
    } ],
} );

document.getElementById( 'container' ).appendChild( hovercard );
(static) createHovercardSkeleton( options?: { additionalClass?: string } ): HTMLDivElement

这种方法生成了骨架悬浮卡元素. 它接受一个可选选项对象,可以包含 additionalClass 属性。 当您想要在获取 Gravatar 配置文件时显示装入状态时有用 .

import { Hovercards } from '@gravatar-com/hovercards';

const hovercardSkeleton = Hovercards.createHovercardSkeleton();

document.getElementById( 'container' ).appendChild( hovercardSkeleton );
(static) createHovercardError( avatarUrl: string, message: string, options?: { additionalClass?: string; avatarAlt?: string; additionalMessage?: string } ): HTMLDivElement

这种方法生成了错误的悬浮卡元素. 它接受 avatarUrl 参数,它代表外观图像的 URL,即 message 参数,它代表错误消息,和一个可选选项对象,可以包含属性,例如 additionalClass, (中文(简体) ), avatarAlt (默认 : 'Avatar', 特别是, 如果您想要在获取 Gravatar 配置文件失败时显示错误消息, 则有用 .

message 财务报告和审定财务报表 avatarAlt 作为纯文本( HTML 已逃出) 提供,同时 additionalMessage 被插入到 HTML 中,所以只能通过信任的标记.

import { Hovercards } from '@gravatar-com/hovercards';

const hovercardError = Hovercards.createHovercardError( 'https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>', 'Error message' );

document.getElementById( 'container' ).appendChild( hovercardError );
attach( target: HTMLElement, options?: { dataAttributeName?: string; ignoreSelector?: string } ): void

这种方法将悬浮卡附加到指定的目标元素上,从而使悬浮卡的功能得以实现. 它接受 target 参数,它代表了挂起悬牌的目标元素,以及一个可选选项对象,可以包含诸如 dataAttributeName 财务报告和审定财务报表 ignoreSelector。 。 。 .

  • dataAttributeName (默认 : 'gravatar-hash'- 名称 data-* 包含重力散列的属性。 当您想要使用自定义属性名称时, 此选项是有用的 data-gravatar-hash。如果您想要禁用 data-* 属性特性,您可以将此选项设置为空字符串.
  • ignoreSelector (默认 : '') - 一个查询选择器,指定了显示悬浮卡时要排除的元素. 当您想要防止某些元素触发徘徊卡时,此选项是有用的 .

注:每个 attach() 调用从当前目标上自动解开悬牌,然后将其附加到新目标上.

detach(): void

这种方法将悬浮卡从目前的目标元素中解开,从而使悬浮卡功能失效.

反应

这个库提供了反应组件和一个钩子,它们的操作类似于 香草 Java 脚本 版本.

反应组件

使用量

以下是一个基本的例子:

// Import the React component
import { Hovercards } from '@gravatar-com/hovercards/react';
// Import the hovercard styles
import '@gravatar-com/hovercards/dist/style.css';

function App() {
    // ...

    return (
        <Hovercards>
            { /* Work with Gravatar images */ }
            <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />
            <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />

            { /* Work with elements having `data-gravatar-hash` attribute */ }
            <div data-gravatar-hash="<HASHED_EMAIL_ADDRESS>">@Meow</div>
            <div data-gravatar-hash="<HASHED_EMAIL_ADDRESS>">@Woof</div>
        </Hovercards>
    );
}

注:该部分将创建一个 div 包装所有孩子的容器元素。 您可以使用 className 或者说 style 道具来.

在整页或特定元素上附加悬牌,请使用 attach 道具 :

import { Hovercards } from '@gravatar-com/hovercards/react';
import '@gravatar-com/hovercards/dist/style.css';

function App() {
    // ...

    return (
        <>
            <div>
                <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />
                <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />
                <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />
            </div>
            { /* Attach hovercards to the entire page */ }
            <Hovercards attach={ document.body } />
        </>
    );
}

道具

这个 Hovercards 组件接受下列道具:

attach?: HTMLElement

此道具指定了挂起悬牌的目标元素 。 想要在一整页上附加悬牌时有用.

dataAttributeName?: string = 'gravatar-hash'

此道具指定了名称 data-* 包含重力散列的属性。 当您想要使用自定义属性名称而不是 data-gravatar-hash。如果您想要禁用 data-* 属性特性,您可以将此道具设置为空字符串.

ignoreSelector?: string = ''

此道具指定一个查询选择器,指定了显示悬牌时要排除的元素. 当想防止某些元素触发悬浮卡时有用.

className?: string

此道具允许您指定要添加到容器元素中的类名, 由组件创建, 以包接所有的孩子 .

style?: React.CSSProperties

此道具允许您指定要添加到容器元素中的样式, 由组件创建, 将所有的孩子包起来 .

其余道具请参考 选项 节.

反应钩

使用量

以下是一些如何使用反应钩的基本例子:

import { useEffect, useRef } from 'react';
// Import the React hook
import { useHovercards } from '@gravatar-com/hovercards/react';
// Import the hovercard styles
import '@gravatar-com/hovercards/dist/style.css';

function App() {
    const { attach } = useHovercards( { /* Options */ } );
    const containerRef = useRef();

    useEffect( () => {
        if ( containerRef.current ) {
            attach( containerRef.current );
        }
    }, [ attach ] );

    return (
        <div ref={ containerRef }>
            { /* Work with Gravatar images */ }
            <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />
            <img src="https://www.gravatar.com/avatar/<HASHED_EMAIL_ADDRESS>" alt="Gravatar Image" />

            { /* Work with elements having `data-gravatar-hash` attribute */ }
            <div data-gravatar-hash="<HASHED_EMAIL_ADDRESS>">@Meow</div>
            <div data-gravatar-hash="<HASHED_EMAIL_ADDRESS>">@Woof</div>
        </div>
    );
}

注意:当组件被卸载后,钩子会自动从目标元素中去除悬浮卡.

您也可以使用钩子创建自定义组件 :

import sha256 from 'js-sha256';
import { useEffect, useRef } from 'react';
import { useHovercards } from '@gravatar-com/hovercards/react';
import '@gravatar-com/hovercards/dist/style.css';

// A custom Avatar component for convenience
function Avatar( { email } ) {
    const { attach } = useHovercards();
    const imgRef = useRef();

    useEffect( () => {
        if ( imgRef.current ) {
            attach( imgRef.current );
        }
    }, [ attach ] );

    return (
        <img ref={ imgRef } src={ `https://www.gravatar.com/avatar/${ sha256( email ) }` } alt="Gravatar Image" />
    );
}

备选办法和方法

钩子接受与 Hovercards 课。 请参看 API 密码 详细情况.

类型脚本

这个库用TypeScript来书写,并带有类型定义. 您可以检查以下可用类型的文件 :

翻译

显示悬牌时会使用一些文字项目. 图书馆默认包含英语,但您可以通过使用该语言提供自己的翻译 i18n 选项.

使用了以下短语:

  • Edit your profile →
  • View profile →
  • Contact
  • Send money
  • Sorry, we are unable to load this Gravatar profile.
  • Gravatar not found.
  • This profile is private.
  • Too Many Requests.
  • Internal Server Error.
  • Is this you?
  • Claim your free profile.
  • Email
  • Home Phone
  • Work Phone
  • Cell Phone
  • Contact Form
  • Calendar

这个 i18n 选项是一个从英文文本映射到您选择的语言(甚至另一个英文短语,如果您想修改文本的话).

翻译被作为纯文本处理:其中的任何HTML都是被逃脱而不是被提供. 传递未脱逃字符串( 例如 WordPress ) __() 而不是说 esc_html__())或实体,例如: &#039; 将按字面意思显示.

{
  'Edit your profile →': 'Modifier votre profil →'
}

贡献给 Gravatar 车卡

我们欢迎为这一项目提供捐款。 请遵循本报告概述的准则 捐款额 文档.

许可证

Gravatar Hovercards公司根据下列规定获得许可证: GNU 通用公共许可证 v2( 或以后)。 。 。 .

版本与发布记录

@gravatar-com/hovercards 共发布 41 个版本,首次发布于 2023/08/02;过去 12 个月发布了 2 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.17.0latest2026/10/3018 天前
0.16.02026/03/188 个月前
0.15.02025/08/261.2 年前
0.14.02025/06/301.4 年前
0.13.02025/05/011.5 年前
0.12.02025/04/231.6 年前

关于 @gravatar-com/hovercards 的常见问题

@gravatar-com/hovercards 是什么?

在 Gravatar 图像中添加配置悬浮卡 .

如何安装 @gravatar-com/hovercards?

在项目目录运行 npm install @gravatar-com/hovercards,或使用 pnpm add / yarn add / bun add。

@gravatar-com/hovercards 支持 TypeScript 吗?

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

@gravatar-com/hovercards 支持 ESM 还是 CommonJS?

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

@gravatar-com/hovercards 需要什么版本的 Node.js?

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

@gravatar-com/hovercards 可以商用吗?

@gravatar-com/hovercards 使用 GPL-2.0-or-later 许可。强 Copyleft:分发包含该代码的软件时,整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括,不构成法律意见,请以许可原文为准。

@gravatar-com/hovercards 的下载量有多少?

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

@gravatar-com/hovercards 还在维护吗?

最新版本 0.17.0 发布于 2026/10/30(18 天前);至今共发布 41 个版本,其中过去 12 个月发布了 2 个;首次发布于 2023/08/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。