just-event.js/README.md

Modern, lightweight event utility with jQuery-like API.

# just-event.js

[![npm](https://img.shields.io/npm/v/just-event.js)](https://www.npmjs.com/package/just-event.js)
[![cdn version](https://data.jsdelivr.com/v1/package/npm/just-event.js/badge)](https://www.jsdelivr.com/package/npm/just-event.js)
[![codecov](https://codecov.io/gh/ajiho/just-event.js/graph/badge.svg?token=G2P1AI238H)](https://codecov.io/gh/ajiho/just-event.js)
[![codecov-test](https://img.shields.io/github/actions/workflow/status/ajiho/just-event.js/test.yml?label=codecov-test&branch=main)](https://github.com/ajiho/just-event.js/actions/workflows/test.yml)

---

受[jQuery](https://github.com/jquery/jquery)启发的现代、轻量的事件工具，具有类似 jQuery 的 API

## 为什么?

如果你热衷于开发JavaScript插件，想摆脱jQuery，但也喜欢它对事件绑定的语法，那么这个库对你来说非常有用，这也是它的主要用例

## 特性

- 零依赖,体积极小(gzipped: <= 2KB)
- 事件命名空间
- 批量绑定、解绑事件
- 轻松的事件委托
- 真实的DOM事件

## 快速开始

### NPM

```bash
$ npm i -D just-event.js
```

```js
// esm
import event from "just-event.js"
event(selector).on("click", handler)

// 或者您也喜欢直接使用方法
import { on, off, one } from "just-event.js"

on(selector, "click", handler)
one(selector, "click", handler)
off(selector, "click")

// cjs
const event = require("just-event.js")
event(selector).on("click", handler)

// 支持链式调用
event(selector).one("mouseover", handler).on("click", handler)
```

### 浏览器脚本引入

```html
<script src="https://unpkg.com/just-event.js@latest/dist/just-event.browser.min.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/just-event.js@latest/dist/just-event.browser.min.js"></script>
```

可以在[unpkg](https://unpkg.com/just-event.js@latest/dist/),[jsdelivr](https://cdn.jsdelivr.net/npm/just-event.js@latest/dist/)找到固定版本替换`@latest`

```js
// 全局变量名称 "event" 是固定的
event(selector).on("click", handler)
```

### AMD

如果您是使用AMD 模块化开发请使用下面的脚本

```html
<script src="https://unpkg.com/just-event.js@latest/dist/just-event.amd.min.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/just-event.js@latest/dist/just-event.amd.min.js"></script>
```

## 上下文和事件属性及方法

| jQuery                  | just-event.js           | 说明                              |
| ----------------------- | ----------------------- | --------------------------------- |
| this                    | this                    | 当前触发事件的 DOM 元素           |
| event.target            | event.target            | 最初调度事件的元素                |
| event.delegateTarget    | event.delegateTarget    | 绑定事件处理函数的元素            |
| event.currentTarget     | event.currentTarget     | 当前触发事件的 DOM 元素与this相同 |
| event.stopPropagation() | event.stopPropagation() | 阻止事件进一步传递                |
| event.preventDefault()  | event.preventDefault()  | 阻止事件默认行为                  |

> 完全保持了和jQuery相同的行为

## API

### on

```js
// 基本形式
event(selector).on("click", handler)

// 批量绑定事件
event(selector).on("click mousedown", handler)

// 事件委托
event(selector).on("click", ".foo", handler)
event(selector).on("click mousedown", ".foo", handler)

// 支持命名空间
event(selector).on("click.app", handler)
event(selector).on("click.app1 click.app2", handler)
event(selector).on("click.app mousedown.app", handler)
event(selector).on("click.app mousedown.app", ".foo", handler)
```

### off

```js
// 移除.app命名空间的点击事件
event(selector).off("click.app")

// 移除.app命名空间下的所有事件
event(selector).off(".app")

// click.app1 click.app2 移除所有的点击事件
event(selector).off("click")

// 都支持批量操作
event(selector).off("click mousedown")
event(selector).off(".app1 .app2")
event(selector).off("click.app1 click.app2")
```

### one

```js
event(selector).one("click", handler)

//委托
event(selector).one("click", ".foo", handler)
```

### trigger

与`jQuery(selector).trigger()`有所不同,`event(selector).trigger()`分发的是[CustomEvent](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomEvent)构造函数创建的真实的事件实例,可以通过`addEventListener()`进行监听

```js
event(selector).on("click.app1 click.app2", handler)

// 触发所有的点击事件
event(selector).trigger("click")
// 只触发携带.app1命名空间的点击事件
event(selector).trigger("click.app1")
// 携带参数
event(selector).trigger("click", { foo: "bar" })
event(selector).trigger("click.app1", { foo: "bar" })

// 触发自定义事件
event(selector).on("foo-bar-event", (event) => {
  console.log(event.detail.type) // "my-event"
})

event(selector).trigger("foo-bar-event", {
  type: "my-event",
  foo: "bar",
})
```

## 浏览器支持

具体可以查看[.browserslistrc](https://github.com/ajiho/just-event.js/blob/main/.browserslistrc)文件。

## 变更日志

每个版本的详细更改记录在[CHANGELOG.md](https://github.com/ajiho/just-event.js/blob/main/CHANGELOG.md)中.

## License

[MIT](https://github.com/ajiho/just-event.js/blob/master/LICENSE)

Copyright (c) 2025-present, ajiho