重力高通卡
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>
);
}
在整页或特定元素上附加悬牌,请使用 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 →ContactSend moneySorry, 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.EmailHome PhoneWork PhoneCell PhoneContact FormCalendar
这个 i18n 选项是一个从英文文本映射到您选择的语言(甚至另一个英文短语,如果您想修改文本的话).
翻译被作为纯文本处理:其中的任何HTML都是被逃脱而不是被提供. 传递未脱逃字符串( 例如 WordPress ) __() 而不是说 esc_html__())或实体,例如: ' 将按字面意思显示.
{
'Edit your profile →': 'Modifier votre profil →'
}
贡献给 Gravatar 车卡
我们欢迎为这一项目提供捐款。 请遵循本报告概述的准则 捐款额 文档.
许可证
Gravatar Hovercards公司根据下列规定获得许可证: GNU 通用公共许可证 v2( 或以后)。 。 。 .