# @foleyjs/core 中文文档
规范地址：https://npmcn.com/package/%40foleyjs/core/
版本：2\.9\.0
npm 元数据更新时间：2026-09-15T06:08:04.834Z
中文译文更新时间：2026-11-15T04:04:16.055Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40foleyjs/core
原文对照：https://npmcn.com/package/%40foleyjs/core/?lang=original
项目主页：https://usefoley.dev/
源码仓库：https://github.com/eakbulut/foley
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：65.9 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-29T21:55:12.732Z
- 最新版本发布：2026-09-15T06:08:04.554Z
- 近 30 天下载量：28048（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）
## 中文简介
接口的音效,现场表演. 28个交互提示被Web Audio合成——零依赖,零音频文件.
## 安装
```sh
npm install @foleyjs/core
```
也可以使用：`pnpm add @foleyjs/core`、`yarn add @foleyjs/core`、`bun add @foleyjs/core`
## README
# 费利
[](https://www.npmjs.com/package/@foleyjs/core) [](https://github.com/eakbulut/foley/actions/workflows/ci.yml) [](https://npmcn.com/package/%40foleyjs/core/LICENSE)
**接口的音效,现场表演.** [播放演示](https://usefoley.dev/)
Foley是一个小的,没有依赖性的图书馆 **28个交互声音**,以电影艺术家的名字命名 他们表演脚步 和门-斜线与图片同步。 它对您的界面也一样: 每个提示在动作瞬间被Web Audio合成. 没有音频文件,没有网络请求,没有构建步骤.
- **7个家庭的28个提示** 指针、按键、切换、反馈、通知、运动、状态
- **4个主题** 默认的、软的、机械的、玻璃的,或你自己的变换,或一个完整的 [声音集](https://npmcn.com/package/%40foleyjs/core/#readme-sound-sets)
- **库斯是数据** — 编辑任意提示的分层 `getSpec()`编号 :`playSpec()`,或者在 [Cue 设计器](https://usefoley.dev/#designer)
- **7.6千贝** 整个API的精密化 + gzipped – 5.9 kB 通常 `bind` + 键 `play` + 键 `set`,因为它是树摇;零依赖,一个ES模块
- **位于空间** —— 说 `pan` 或 三维 `pos` 每场比赛,或 `set({ localize })` 将每个带宽的提示都铺到其元素在屏幕上的位置
- **标记,不接线** —— 说 `data-foley-*` 属性 `bind()` 覆盖整个页面,包括稍后的标记和键盘焦点 `observe()` 单独出现或改变状态的音效元素
- **设计防御** ——主限制器,每克可冷却60ms,±30分人性化;回路在背景分页中会安静; `stop()` 手柄、回转和鸭子
- **WAV 导出** 任意提示、任何自定义设计,或所有28作为带有相抵映射的音频图示
## 安装
```sh
npm install @foleyjs/core
```
> 现按 [foleyjs 矿石](https://www.npmjs.com/org/foleyjs) - 赤裸裸的名称 `foley` 被 npm 的软件包名称相似性规则所屏蔽。 框架约束将作为 `@foleyjs/react` 还有朋友.
或者跳过安装并销售单文件:复制 `src/foley.js` 进入你的项目.
## 快速启动
标出任何应该发出声音的东西,然后在启动时绑定一次.
```html
Docs
```
```js
import { bind, play, set } from "@foleyjs/core";
bind(); // wires every data-foley-* attribute
set({ volume: 0.7, theme: "default" });
play("success"); // programmatic cues for things the user didn't click
play("tick", { pitch: 4, volume: 0.3 });
```
浏览器需要用户手势才能启动音频; `bind()` 为您安装一次性解锁收听器,并且 `play()` 自动恢复上下文.
## 声明属性
| 属性 | 着火了 | 默认提示 |
| --- | --- | --- |
| `data-foley-hover` | `pointerenter`, (中文(简体) ), `focusin` | `tick` |
| `data-foley-press` | `pointerdown` | `press` |
| `data-foley-release` | `pointerup` | `release` |
| `data-foley-click` | `click` | `tap` |
| `data-foley-toggle` | `click` (读取) `aria-pressed`(中文(简体) ) | `on` 编号 : `off` |
| `data-foley-type` | `keydown` (进入游戏) `complete`(中文(简体) ) | `thock` |
每个属性都接受一个提示名作为值来覆盖默认值.
`bind()` 代表 `root`,所以它涵盖了尚未存在的元素—— 使一个 模式、 改变路线、 附加列表项, 它们都发出没有重新绑定的声音 。 缓冲 在键盘焦点上也点火,所以通过界面触摸听起来像在移动 通过它.
## 听上去用户没有触发
`bind()` 盖住别人做的事. `observe()` 覆盖接口在其 自己——敬酒到来,对话结束,抽屉打开:
```html
Saved
…
…
```
```js
import { bind, observe } from "@foleyjs/core";
bind(); // interaction
observe(); // appearance and state change
```
| 属性 | 当火 | 默认提示 |
| --- | --- | --- |
| `data-foley-enter` | 元素添加到 DOM 中 | `bubble` |
| `data-foley-exit` | 删除元素 | `whoosh` |
| `data-foley-change` | 它的状态属性改变 | `switch` |
一个 `MutationObserver`因此,没有生命周期钩 和州管道—— 举杯 听起来不错 这是一个单独的呼叫 从 `bind()` 目的:它监视着人类的生命 页面,大多数应用程序只想要交互声音.
- **只有点火后才有变化**,所以初始渲染是沉默的。 说吧 先画好了.
- **`-change` 监视状态属性, 不 `class`**数字 : `aria-expanded`, (中文(简体) ), `aria-selected`, (中文(简体) ), `aria-checked`, (中文(简体) ), `aria-pressed`, (中文(简体) ), `open`, (中文(简体) ), `data-state`每次盘旋时都有班级摇摆 将页面变成响起.
- **退出游戏居中** 甚至在下面 `localize` - 一个被移除的元素没有留下位置 读取.
- 列表渲染出100行火 100入; 每克可冷却的60ms倒塌 进入一个,所以你不需要节奏.
- `observe()` 返回一个停止函数,如果在同一根上调用两次,则不为操作.
## 28个提示
| 家属 | 库斯 |
| --- | --- |
| 指针 | `tick` `hover` `glide` `pop` |
| 新闻 | `press` `release` `tap` `thock` |
| 切换 | `on` `off` `switch` `latch` |
| 反馈 | `success` `error` `warning` `denied` |
| 通知 | `chime` `ping` `bell` `bubble` |
| 动议 | `swoosh` `whoosh` `drop` `rise` |
| 状态 | `loading` `ready` `complete` `sparkle` |
## API 密码
```js
import { play, bind, set, get, toWav, unlock, getAnalyser, on, cues, families, themes, version } from "@foleyjs/core";
```
- **`play(name, { pitch?, volume?, loop?, every?, pan?, pos? })`** ——播放提示;返回 `{ stop() }`与 `loop: true` 它重复到停止 —— 理想的加载状态.
- **`bind(root?)`** 全部电线 `data-foley-*` 属性 `root` (默认) `document`) (中文(简体) ). 同上,和授权:后面的加价没有重新约束.
- **`set({ volume?, transpose?, space?, muted?, hover?, theme?, duck?, localize? })`** ——更新全局设置. `duck` (0–1)暂时减轻了一切,例如当一个视频播放时. `localize` (0–1) 将每一个有束缚的提示都刻入屏幕上的元素位置. `theme` 接受名称或自定义变换对象(`{ pitch, decay, send, ... }`) (中文(简体) ).
- **`observe(root?)`** - 出现、离开或改变状态的有声元素(`data-foley-enter` 编号 : `-exit` 编号 : `-change`通过一个 `MutationObserver`。Opt-in;返回一个停止函数.
- **`panFor(el)`** - 锅 `localize` 将获得一个元素,为你自己 `play()` 打电话.
- **`get()`** ——当前设置的快照.
- **`toBuffer(name)`** —— 说 `Promise`: 相同的离线渲染,生出——用于信封图纸,仪表或自定义编码.
- **`getSpec(name)`** —— 内置提示分层分层的可编辑的深层拷贝.
- **`playSpec(spec, { id?, pitch?, volume?, pan?, pos? })`** ——播放自定义规格;首先验证并夹住.
- **`toWavSpec(spec)` 编号 : `toBufferSpec(spec)`** ——离线给自定义规格.
- **`normalizeSpec(spec)`** ——验证器本身,用于检查不可信光谱(最大为8层,全部被夹住).
- **`toSprite(gap?)`** 所有28个提示在WAV加A `{ name: { start, duration } }` 相抵映射,用于游戏引擎和音频拼接播放器.
- **`toWav(name)`** —— 说 `Promise`:离线给16位44.1克赫兹立体声WAV的提示,以纪念转接器,空间和主题. 出口是决定性的(没有人性化漂移).
- **`unlock()`** ——从用户手势恢复/创建音频Context.
- **`getAnalyser()`** - 发动机的 `AnalyserNode` 瞄准镜和仪表,或 `null` 在解锁前.
- **`on("play" | "unlock", cb)`** ——订阅引擎事件;返回未订阅的函数.
- **`cues` 编号 : `families` 编号 : `themes` 编号 : `version`** 用于建造自己拾取器和游乐场的元数据.
## 安置情况
一个提示可以来自某处. `pan` 把它放在立体声领域; `pos` 放在三维 (HRTF,反相距)用于WebXR和画布场景.
```js
play("tick", { pan: -0.7 }); // over on the left
play("ping", { pos: [1, 0, -0.5] }); // to the right, slightly in front
set({ localize: 0.6 }); // every bound cue pans to its own button
```
`pos` 从源头的收听器中测出,并减少大约1个单位 (反相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 除非你想让他们晕倒.. `[1, 0, -0.5]` 是满的,是明显的右边 `[2, 0, -3]` 实值 已经11分贝了.
一个设置和接口停止发出声音 就像它来自一个单一点——a 在右边单击工具栏,这是屏幕形状的声音 库可以做到这一点 一个游戏音频引擎从来没有打扰.
位置固定在触发器上:提示为~200ms一发,在任何东西之前 可以移动,所以没有听者, 没有锥子, 没有什么可以重新定位 中空. 动词发送保持中心——房间不平板,源头有. 出口`toWav`, (中文(简体) ), `toSprite`(a) 保持中心位置:位置是业绩的财产,而不是 声音,同样的规则 人性化遵循.
## 自己设计提示
每个提示都是数据: `tone`, (中文(简体) ), `noise`,以及 `cluster` 层。 拿一个,重塑它,播放它:
```js
import { getSpec, playSpec, toWavSpec } from "@foleyjs/core";
const mySound = getSpec("success");
mySound[2].f = 880; // raise the last note
mySound.push({ kind: "noise", at: 0.2, filter: "highpass", f: 6000,
a: 0.01, d: 0.2, peak: 0.05, send: 0.4 });
playSpec(mySound);
const wav = await toWavSpec(mySound);
```
在类型脚本中, 缩入 `kind` 在接触一层地之前.. `Spec` 是一个工会, 和集群层 `fMin`编号 :`fMax` 声调和噪音层所携带的地方 `f`数字 :
```ts
const layer = mySound[2];
if (layer.kind === "tone") layer.f = 880;
```
或者用视觉 [演示中显示设计师](https://usefoley.dev/#designer) ——用活回放来编辑,再导出.wav/.json或共享设计作为链接.
## 声音集
声音集是您产品的整体声学特性,作为一个便携式JSON对象:a global 字符变换外加最要紧提示的全置换规格.
```js
import { set, getSet } from "@foleyjs/core";
set({ theme: {
name: "Acme",
transform: { pitch: 0.9, decay: 1.3 }, // every cue, reshaped
cues: { success: [/* layers */], error: [/* layers */] } // these two, replaced
}});
get().theme; // "Acme"
getSet(); // snapshot the active identity - JSON-safe, version it in your repo
```
- **`getSet()`** 返回活动身份;通过 `set({ theme })` 毫无损失.
- 指定任何被命名的主题都取代了整个身份, 覆盖包含 .
- 覆盖像任何光谱一样被验证(未知的提示被丢出,抛出被夹住).
- 以视觉方式构建一个 [Cue 设计器](https://usefoley.dev/#designer): 设计提示, 选择 然后导出集或复制集链接.
## 主题
一个设定重塑了所有28个提示——波形,信封,亮度,噪声字符和回声:
```js
set({ theme: "glass" }); // "default" | "soft" | "mechanical" | "glass"
```
**软** 环绕每个波形并增加空间. **机械** 将瞬态和干燥空间减半——机器金属. **眼镜** 投出,把滤波器接上, 在每个声音上都长出不和谐的一面—— 使被打出玻璃的声音像玻璃一样的物理把戏.
## 免费的引擎行为
- A 类 **主限制** (DynamicsCompressor作为砖墙安全) 所以重叠的提示永远不会被剪接.
- A 类 **每克冷却60毫米** 因此,徘徊风暴和快滑道保持音乐而不是机枪.
- **人性化**:每一次性能在投出时漂移到相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相相和相和相和相和相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.
- **循环提示在背景标签中沉寂** 重现后恢复原貌 所以被遗忘了 `play("loading", { loop: true })` 无法从他们留下的标签中抹去某个人 一发子弹仍然发作——a `ping` 对于收到的消息,就是要点.
## 框架软件包
- **反应** —— 说 [`@foleyjs/react`](https://npmcn.com/package/%40foleyjs/core/packages/react)数字 : `const { play } = useFoley({ theme: "soft" })`
- **第3组** —— 说 [`@foleyjs/vue`](https://npmcn.com/package/%40foleyjs/core/packages/vue)数字 : `app.use(FoleyPlugin)` 接下来 `