@gravatar-com/quick-editor

中文文档
0.8.0发布于 2025/03/24GPL-2.0-or-laterTypeScriptESM + CJS零依赖近 30 天下载 3.3万

A lightweight library to provide seamless Gravatar profile management for third-party sites

原始使用文档
文档目录13 节
  1. Features
  2. Installation
  3. Install with NPM or Yarn
  4. Install with UNPKG
  5. Usage
  6. GravatarQuickEditor
  7. GravatarQuickEditorCore
  8. API
  9. GravatarQuickEditor API
  10. GravatarQuickEditorCore API
  11. Valid Scope Values
  12. Contribute to Gravatar Quick Editor
  13. License

Gravatar Quick Editor

Gravatar Quick Editor is a JavaScript library that allows users to integrate the Gravatar Quick Editor into their web applications, enabling easy editing of Gravatar profiles via a popup window. The library provides both a core class for advanced control and a simplified class for quick setup.

Features

  • Simple integration with your web application.
  • Core functionality for advanced usage.
  • Simplified setup for quick integration.
  • Supports real-time updates to avatar images using the PostMessage API.
  • TypeScript support for type completion and validation.

Installation

Install with NPM or Yarn

Install the package using npm or yarn:

npm install @gravatar-com/quick-editor
yarn add @gravatar-com/quick-editor

Install with UNPKG

Import the library as shown below:

<!-- Import the 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>

Replace x.x.x with the latest version number. Please refer to UNPKG's documentation for more information.

Usage

GravatarQuickEditor

The GravatarQuickEditor class simplifies the setup process by automatically setting up event handlers to open the popup and update avatar elements on the page.

Example

import { GravatarQuickEditor } from '@gravatar-com/quick-editor';

document.addEventListener( 'DOMContentLoaded', () => {
  new GravatarQuickEditor( {
    email: '[email protected]',
    editorTriggerSelector: '#edit-profile',
    avatarSelector: '#gravatar-avatar',
    scope: [ 'avatars' ],
  } );
} );

GravatarQuickEditorCore

The GravatarQuickEditorCore class provides advanced control over the Gravatar Quick Editor functionality, allowing developers to trigger popup events and set up profile update callbacks.

Core Example

import { GravatarQuickEditorCore } from '@gravatar-com/quick-editor';

document.addEventListener( 'DOMContentLoaded', () => {
  const quickEditorCore = new GravatarQuickEditorCore( {
    email: '[email protected]',
    scope: [ 'avatars', 'about' ],
    onProfileUpdated: () => {
      console.log( 'Profile updated!' );
    },
    onOpened: () => {
      console.log( 'Editor opened!' );
    },
  } );

  document.getElementById( 'edit-profile' ).addEventListener( 'click', () => {
    quickEditorCore.open();
  } );
} );

API

GravatarQuickEditor API

new GravatarQuickEditor(options: QuickEditorOptions);

QuickEditorOptions Type

type QuickEditorOptions = {
  email: string;
  editorTriggerSelector: string;
  avatarSelector?: string;
  scope?: Scope;
  locale?: string;
  avatarRefreshDelay?: number;
};
  • email: string: The email address associated with the Gravatar profile. This is used to identify the profile to be edited.

  • editorTriggerSelector: string: A CSS selector for the HTML element (e.g., button) that triggers the opening of the Gravatar Quick Editor popup.

  • avatarSelector: string: A CSS selector for the HTML image element(s) that displays the Gravatar avatar. When the avatar is updated, the image(s) will be refreshed automatically.

  • scope: Scope: An array specifying what sections of the profile can be edited in the popup. Check the list of valid scope values

  • locale: string: The locale setting for the Gravatar editor interface. This can be used to set the language for the editor UI.

  • avatarRefreshDelay: number: The delay in milliseconds before the avatar image is refreshed after an update. This can help ensure any cache can be busted before the new image is displayed.

  • utm: string: A code used to determine where the Quick Editor is being used.

While updating the avatar image, to bypass the browser's cache, the Quick Editor will add a t parameter with the current timestamp to the avatar URL.

GravatarQuickEditorCore API

new GravatarQuickEditorCore(options: QuickEditorCoreOptions);

QuickEditorCoreOptions Type

type QuickEditorCoreOptions = Partial< {
  email: string;
  scope: Scope;
  locale: string;
  onProfileUpdated: OnProfileUpdated;
  onOpened: OnOpened;
} >;
  • email: string: The email address associated with the Gravatar profile. This is used to identify the profile to be edited.

  • scope: Scope: An array specifying what sections of the profile can be edited in the popup. Check the list of valid scope values

  • locale: string: The locale setting for the Gravatar editor interface. This can be used to set the language for the editor UI.

  • onProfileUpdated: ( type: ProfileUpdatedType ) => void: A callback function that gets called when the profile is updated. This can be used to trigger additional actions in your application when the user saves changes to their profile. It will receive a parameter of type ProfileUpdatedType which can have one of the values: 'avatar_updated' | 'profile_updated'

  • onOpened: () => void: A callback function that gets called when the editor popup is opened. This can be used for logging, analytics, or other actions when the popup is triggered.

  • onClosed: () => void: A callback function that gets called when the editor popup is closed.

Public functions

  • open: ( email?: string ) => boolean: A function for triggering the Gravatar Quick Editor popup. It can receive an email address to identify the profile to be edited. true is returned if successfully opened, false otherwise.
  • close: () => void: Closes an open Gravatar Quick Editor popup.
  • isOpen: () => boolean: Return true if the popup is open, false otherwise.

Valid Scope Values

  • about
  • avatars
  • verified-accounts
  • links
  • interests
  • contact-info
  • wallet
  • photos
  • design
  • privacy

Contribute to Gravatar Quick Editor

We welcome contributions to this project. Please follow the guidelines outlined in the CONTRIBUTING.md file.

License

Gravatar Hovercards is licensed under GNU General Public License v2 (or later).

版本与发布记录

@gravatar-com/quick-editor 共发布 6 个版本,首次发布于 2024/07/02;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.8.0latest2025/03/241.6 年前
0.7.02025/03/121.7 年前
0.6.02024/08/102 年前
0.5.02024/07/062 年前
0.0.22024/07/032 年前
0.0.12024/07/022 年前

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

@gravatar-com/quick-editor 是什么?

A lightweight library to provide seamless Gravatar profile management for third-party sites

如何安装 @gravatar-com/quick-editor?

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

@gravatar-com/quick-editor 支持 TypeScript 吗?

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

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

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

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

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

@gravatar-com/quick-editor 可以商用吗?

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

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

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

@gravatar-com/quick-editor 还在维护吗?

最新版本 0.8.0 发布于 2025/03/24(1.6 年前);至今共发布 6 个版本,其中过去 12 个月发布了 0 个;首次发布于 2024/07/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。