# @g2crowd/widget 中文文档

规范地址：https://npmcn.com/package/%40g2crowd/widget/

版本：2\.3\.1
npm 元数据更新时间：2025-06-05T14:03:03.285Z
中文译文更新时间：2026-11-15T20:16:59.428Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40g2crowd/widget
原文对照：https://npmcn.com/package/%40g2crowd/widget/?lang=original
项目主页：https://github.com/g2crowd/widget#readme
源码仓库：https://github.com/g2crowd/widget

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

- 包体积（解压后）：13.4 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2019-02-12T01:37:43.518Z
- 最新版本发布：2024-03-20T20:20:01.012Z
- 近 30 天下载量：3037（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 0 个）

## 中文简介

方便铁路的插件包装器

## 安装

```sh
npm install @g2crowd/widget
```

也可以使用：`pnpm add @g2crowd/widget`、`yarn add @g2crowd/widget`、`bun add @g2crowd/widget`

## README

# 虚拟

vvidget是用于创建统一的JavaScript插件的抽象.

它创建了能处理几个问题的插件:

-   使用单一的命名和选择公约定义所有部件
    -   帮助避免通过代码喷出大量随机选择器
    -   你总是知道哪些DOM元素携带着这些部件之一
-   可靠地绑定在准备和页面更新的事件上,以初始化ajax装入的元素一次并只一次.
    -   帮助管理 PJAX 重装和 HTML 碎片注入
    -   嵌入式部件可以容易和安全地被激活
-   从数据属性加载选项 .
    -   命名空间不会发生相撞, 因此单个 DOM 元素可以安全地托管多个部件

## 基本用途

以您首选的配置创建插件构建器实例 :

```javascript
import widgetSetup from 'widget';

const widget = widgetSetup({ attr: 'ue', data: 'ue-widget' }, 'page-refreshed', 'fragment-refreshed');
// DOM elements with selector of `ue`, or `data-ue-widget` will activate widgets created with this
// config
```

这个配置让我们在数据属性中描述部件并传递选项:

```html
<div class='simple-widget'
     data-ue-widget='widget-name'
     data-widget-name-option-one='option1'
     data-widget-name-option-two='option2'>
```

这将映射到我们用匹配名称创建的插件 :

```javascript
widget('widget-name', function(opts, ready) {
  $el = this;

  ready(() => {
    // teardown
  });
}, {
  defaults: {},
  init: 'nextTick'
});
```

### 多个部件

您可以将多个部件附加到同一个 DOM 元素中, 由 分隔带有空格字符的部件名称.

示例

```html
<div data-ue-widget='widget-1 widget-2'></div>
```

这相当于:

```html
<div ue='widget-1 widget-2'></div>
```

### 刷新页面事件

有一个遗留的事件驱动模式,需要触发事件来初始化部件. 这对PJAX和其他页面更新系统有用.

```javascript
widget('remote-resource', function(opts, ready) {
  fetch('/example').then((htmlFragment) => {
    this.append(htmlFragment);
    this.trigger('fragment-refreshed');

    // any widgets nested within the HTML fragment will be activated
  });

  this.addEventListener('click', fetchData);

  ready(() => {
    this.removeEventListener('click', fetchData);
  });
})
```

### DOM 变异观察员

您也可以选择选择使用突变观察员来检测何时 dOM中增加了新的元素.

```javascript
import widgetSetup from 'widget';

const widget = widgetSetup({ attr: 'ue', data: 'ue-widget' }, 'page-refreshed', 'fragment-refreshed');

widget.stopWatchingEvents();
widget.startWatchingDOM();
```

## 常见问题

### @g2crowd/widget 是什么？

方便铁路的插件包装器

### 如何安装 @g2crowd/widget？

在项目目录运行 npm install @g2crowd/widget，或使用 pnpm add / yarn add / bun add。

### @g2crowd/widget 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/g2crowd\_\_widget 是否存在。

### @g2crowd/widget 支持 ESM 还是 CommonJS？

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

### @g2crowd/widget 可以商用吗？

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

### @g2crowd/widget 的下载量有多少？

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

### @g2crowd/widget 还在维护吗？

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