# @dataemergencia/emergency 中文文档

规范地址：https://npmcn.com/package/%40dataemergencia/emergency/

版本：0\.7\.0
npm 元数据更新时间：2026-11-09T19:28:58.745Z
中文译文更新时间：2026-11-16T00:29:09.810Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：872 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：3 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2026-10-29T19:46:37.810Z
- 最新版本发布：2026-11-09T19:28:58.398Z
- 近 30 天下载量：1971（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

DataEmergencia 的框架不可知紧急情况客户端,设有可挂载回放面板和IIFE架构.

## 安装

```sh
npm install @dataemergencia/emergency
```

也可以使用：`pnpm add @dataemergencia/emergency`、`yarn add @dataemergencia/emergency`、`bun add @dataemergencia/emergency`

## README

# @ dataemergencia/ 紧急情况

数据紧急流量客户端。 它拥有发生的一切 sOS触发后:面板,紧急生命周期,公共实时 更新和地理定位倒数反馈.

上游 DataEcommerdencia API 从未从浏览器调用. 唯一一个 后端合同是紧急BFF(`/de-bff/emergency`),用于验证 身份代码,发送WhatsApp消息并代理上游状态.

-   框架-不可知类型Script核心(类型,状态机,BFF客户端,存储).
-   反应19个显示层,带有无障碍面板组件.
-   香草页可挂载的 IIFE 捆绑:没有主机反应或构建步骤.
-   用于反应应用的无害环境管理/CJS捆绑,并保留外部反应.
-   没有 `localStorage`: BFF是真理的来源并恢复使用 `GET /current`。 。 。 .

## 文档

-   [文件索引](https://npmcn.com/package/%40dataemergencia/emergency/docs/README.md)
-   [客户端快速启动](https://npmcn.com/package/%40dataemergencia/emergency/docs/client/quickstart.md)
-   [香草,不建导线](https://npmcn.com/package/%40dataemergencia/emergency/docs/client/vanilla.md)
-   [他们](https://npmcn.com/package/%40dataemergencia/emergency/docs/client/theming.md)
-   [解决问题](https://npmcn.com/package/%40dataemergencia/emergency/docs/client/troubleshooting.md)
-   [释放](https://npmcn.com/package/%40dataemergencia/emergency/docs/release/releasing.md)

BFF是一个单独的包: [`dataemergencia/emergency-bff`](https://github.com/The-BoxHead-Guy/emergency-bff)。 。 。 .

## 所需资源

-   节点.js 22或更新. CI和释放使用被绑定的LTS `.nvmrc` (24.22.2) (中文(简体) ).
-   pnpm 10+(单体目前运行pnpm 12.8.1).
-   Vite+ 1.4.0用于本包的构建和测试命令.

反应19是无害环境管理/CJS切入点的同行依赖。 IIFE条目 所以香草消费者不需要什么.

## 安装

```bash
pnpm add @dataemergencia/emergency
```

## 反应/无害环境管理快速启动

```tsx
import { mount } from '@dataemergencia/emergency';
import '@dataemergencia/emergency/styles.css';

const client = mount({
  root: '#emergency-root',
  bffBaseUrl: 'https://api.dataemergencia.com/de-bff/emergency',
  code: 'DABC12',
  trigger: '#sos-button', // selector, element, or callback receiving open()
  fallback: {
    phone: '+57 300 123 4567',
    label: 'Línea de emergencia',
  },
  onEvent: (event, payload) => {
    console.log(event, payload);
  },
});

// Later, or from your own UI:
client.open();
client.destroy();
```

`mount()` 从来没有自动打开面板。 主持人决定何时打电话 `open()` 或者说 电线触发器. `destroy()` 卸载 React,去掉触发听器, 取消飞行中的请求,断开Pusher并清除商店.

## 香草/IIFE 快速启动

```html
<div id="emergency-root"></div>
<button id="sos">SOS</button>

<!-- Pin the version in production; see docs/client/installation.md for SRI. -->
<script src="https://cdn.jsdelivr.net/npm/@dataemergencia/emergency@0.1.0/dist/iife/emergency.iife.global.js"></script>
<script>
  window.DataEmergenciaEmergency.mount({
    root: '#emergency-root',
    bffBaseUrl: 'https://api.dataemergencia.com/de-bff/emergency',
    code: 'DABC12',
    trigger: '#sos',
    fallback: { phone: '+57 300 123 4567', label: 'Línea de emergencia' },
    realtime: { key: 'your-public-pusher-key', cluster: 'us2' },
  });
</script>
```

IIFE曝光时 `window.DataEmergenciaEmergency.mount`。反应和反应DOM是 包含在捆绑中; 主机页面不需要构建步骤.

在逐州审查时,有一个实验室页面通过 维特(HMR,CSS模块)取而代之的是已建成的IIFE. 它驱动每一个固定 对模拟的BFF:见 [`examples/vanilla/README.md`](https://npmcn.com/package/%40dataemergencia/emergency/examples/vanilla/README.md)。 。 。 .

## 挂载选项

| 选项 | 类型 | 页:1 |
| --- | --- | --- |
| `root` | `HTMLElement | string` | 主机集装箱. 在山上验证. |
| `bffBaseUrl` | `string` | 完整 BFF 路由前缀,包括 `/de-bff/emergency`。 。 。 . |
| `code` | `string` | 由宿主提供6个特征身份代码. |
| `trigger` | `string | HTMLElement | (open) => void | (() => void)` | 可选的 单击打开面板. |
| `fallback` | `{ phone, label }` | 可选的 接收 `emergency:fallback` 用于主机UI. |
| `theme` | `EmergencyTheme` | CSS变量覆盖(参见Theming). |
| `locale` | `string` | 默认为 `es`; 用于时间格式化. |
| `geolocationTimeoutMs` | `number` | 默认为 `8000`。 。 。 . |
| `requestTimeoutMs` | `number` | 默认为 `15000`。 。 。 . |
| `realtime` | `{ key, cluster, channelPattern? }` | 由主机提供的公推器设置 . |
| `onEvent` | `(name, payload) => void` | 类型生命周期事件. |

实时是可选的。 通过公共推手 `key` 财务报告和审定财务报表 `cluster` (加上a) 选项 `channelPattern`,默认为 `whatsapp.{phone}`)以订阅 直接到API的频道;省略块以保持拉动模式. API( API ) bFF从不持有Pusher证书.

无效的根或代码不会丢入主机页面 . `mount()` 报告a `configuration` 错误通过 `onEvent('emergency:failed', …)`,记录它,和 返回惰性客户端.

## 客户端 API

```ts
client.open(reason?)     // Opens the panel
client.close(reason?)    // Closes the panel
client.ensureSession()   // POST /session once; safe to repeat
client.resume()          // GET /current and exposes resumeAvailable
client.activate()        // Requests geolocation, then POST /activate
client.simulate()        // Requests geolocation, then POST /simulacrum
client.refresh()         // POST /{id}/refresh
client.abort()           // DELETE /{id} after confirmation
client.getState()
client.subscribe(listener)
client.on(event, handler)
client.destroy()
```

激活立即打开面板, 请求地理定位, 只报告 bFF确认后成功. 如果拒绝地理定位, 不可用, 则时间中断 或不支持,客户端会显示五张可以排除的错误反馈卡 秒 绝不意味着紧急情况是在没有地点的情况下发出的.

模拟之前还要求地理定位 `POST /simulacrum`如果捕获 失败, 它遵循与激活相同的回落路径, 不调用 BFF (英语). 通过 `emergency:location`两者 `emergency:activated` 财务报告和审定财务报表 `emergency:simulated` 包括俘虏 坐标.

中止需要确认 : `requestAbortConfirmation()` 设置状态: 用于“保持活动 / 取消紧急” 步骤的 UI,以及 `abort()` 行为 这个.

模拟被禁用,而真正的紧急情况正在发生.

## 活动

`session:ready`, (中文(简体) ), `emergency:location`, (中文(简体) ), `emergency:activated`, (中文(简体) ), `emergency:simulated`, (中文(简体) ), `emergency:resumed`, (中文(简体) ), `emergency:updated`, (中文(简体) ), `emergency:aborted`, (中文(简体) ), `emergency:failed`, (中文(简体) ), `emergency:fallback`, (中文(简体) ), `panel:opened`, (中文(简体) ), `panel:closed`。 。 。 .

事件输入 `EmergencyEventMap` (单位:千美元)`src/core/types.ts`由该物质排放 客户端自己的发送器,而不是 DOM 自定义事件 .

## BFF合同

客户期望紧急BFF记录 `packages/emergency-bff`数字 :

| 方法 | 路线 | 目的 |
| --- | --- | --- |
| `GET` | `/config` | 首个CSRF标志. |
| `POST` | `/session` | `{ code }` + 会话 + 旋转 CSRF 令牌. |
| `GET` | `/current` | 如果有的话,会场有紧急事件. |
| `POST` | `/activate` | `{ geolocation: { latitude, longitude } }`。 。 。 . |
| `POST` | `/simulacrum` | `{ geolocation: { latitude, longitude } }`没有造成紧急情况. |
| `POST` | `/{id}/refresh` | 调和快照和响应器状态 . |
| `DELETE` | `/{id}` | 中止并通知联系人 . |

每个突变请求都会发送 CSRF 令牌 `X-CSRF-Token`默认值 策略将符号保存在内存中并从中更新 `/config` 财务报告和审定财务报表 `/session`。 。 。 . 对于一个 Laravel 兼容性 `XSRF-TOKEN` 饼干,通过 `createCookieCsrfStrategy()` 结束 `createBffClient()` (先进用法).

`createBffClient()` 将出错规范为 `EmergencyError` 在保留 HTTP 状态、 BFF 错误代码、 消息和 `request_id`。 。 。 .

## 标致和视觉合同

面板复制 `bp.scaem.app` 紧急水面 这是简单的CSS 模块:反应和香草整形器不需要Tailwind、PostCSS、, FontAwesome 或图标包 .

本地类名称保留 BEM 名称, 例如 `.emergency-panel`, (中文(简体) ), `.emergency-panel__header`, (中文(简体) ), `.emergency-panel__button--emergency`, (中文(简体) ), `.emergency-status__row` 财务报告和审定财务报表 `.emergency-resume-notification-overlay`. CSS 模块在构建时前缀 时间(`de-emergency-emergency-panel-<hash>`),因此,将稳定BEM后缀设定在 覆盖而不是生成的散列 .

所有主题值都是 CSS 自定义属性 `src/styles/tokens.css`,以及 每条规则都带有文字倒置:

```css
:root {
  --de-emergency-red: #ff0000;
  --de-emergency-red-hover: #ff3535;
  --de-emergency-blue: #00adf6;
  --de-emergency-blue-hover: #29bfff;
  --de-emergency-primary: #007bff;
  --de-emergency-text: #3d4461;
  --de-emergency-white: #fff;
  --de-emergency-white-soft: #f7f7f7;
  --de-emergency-gray: #555;
  --de-emergency-radius: 0.75rem;
  --de-emergency-font: 'Poppins', ui-sans-serif, system-ui, sans-serif;
}
```

这个 `theme` 选项映射 `accent`, (中文(简体) ), `accentContrast`, (中文(简体) ), `surface`, (中文(简体) ), `text`, (中文(简体) ), `muted` 财务报告和审定财务报表 `radius` 打开 `--de-emergency-red`, (中文(简体) ), `--de-emergency-on-red`, (中文(简体) ), `--de-emergency-white`, (中文(简体) ), `--de-emergency-text`, (中文(简体) ), `--de-emergency-text-secondary` 财务报告和审定财务报表 `--de-emergency-radius`。 。 。 .

客户端为Google Sans、蒙特塞拉特和 在无害环境管理/CJS和IIFE的构建中,在挂载时的弹出机,所以主机不 添加字体 `<link>` 标签。 使用 `fontLoading` 挂载选项以禁用加载或 选择家族;参见 [配置](https://npmcn.com/package/%40dataemergencia/emergency/docs/client/configuration.md#fonts)。 。 。 .

IIFE 捆绑将这个样式表嵌入单个注入 `<style>` 标签和 当最后一个挂载被摧毁时, 将它删除 。 使用 IIFE 的主机不能装入 一份CSS的第二份副本. 进口的无害环境管理/CJS消费者 `styles.css` 一次 一次吗.

## 无障碍

小组认为: `role="dialog"` 与 `aria-modal`, (中文(简体) ), `aria-labelledby`页:1 焦点陷阱,从逃出到关闭,焦点还原到触发. 确认 步骤是取消和确认动作的明确对话框。 所有控件都是 带有可见焦点的本地按钮, 图标是内置 SVG 的 `aria-hidden`状态表面 `role="status"` 或者说 `role="alert"`。 。 。 .

## 发展

```bash
pnpm install
pnpm run check      # format + lint + type checks
pnpm run lint
pnpm run fmt
pnpm run typecheck
pnpm run test
pnpm run build
pnpm run pack       # npm pack --dry-run
```

实例和视觉实验室:

```bash
# Terminal 1: deterministic mock BFF on :8787
pnpm run example:vanilla:mock

# Terminal 2: build, copy the IIFE and serve the vanilla demo
pnpm run example:vanilla

# Or the HMR lab only (serves the package root)
pnpm run lab
```

构建产出 :

| 路径 | 目录 |
| --- | --- |
| `dist/index.js` 编号 : `dist/index.cjs` | 无害环境管理/CJS捆绑,外部反应. |
| `dist/index.d.ts` 编号 : `dist/index.d.cts` | 申报. |
| `dist/styles.css` | 为无害环境管理/CJS消费者提取的CSS模块. |
| `dist/iife/emergency.iife.global.js` | IIFE与回放捆绑并注入CSS. |

IIFE gzip预算为150KB(当前建设:~115KB).

## 释放

这个包裹住在 `libs/emergency` 在数据Emergencia 单列波中,为 从公共分割存储器中发布 `The-BoxHead-Guy/emergency` 作为 `@dataemergencia/emergency` 页:1 `dataemergencia`) (中文(简体) ).

整个本子是 [释放客户](https://npmcn.com/package/%40dataemergencia/emergency/docs/release/releasing.md)简短 版本 :

```bash
cd libs/emergency
pnpm bump 0.2.1                 # package.json only; commit the bump
pnpm run check && pnpm run test && pnpm run build
git tag -a emergency-client-v0.2.1 -m "release: 0.2.1"
git push origin emergency-client-v0.2.1
```

标签推出拆分工作流程,该工作流程将此目录映射到拆分 根,重生一个独立 `pnpm-lock.yaml`,并按下拆分标签。 礛 运行 **发布到 npm** 从拆分寄存器.

-   Monorepo 标签为工程范围 : `emergency-client-v0.2.1`。 。 。 .
-   拆分仓库标签 : `v0.2.1`。 。 。 .
-   `scripts/split.sh <version> [--push] [--publish]` 执行相同的镜像 手动操作, 并且是无法操作时的倒计时 .
-   `scripts/release.sh <version> [--publish]` 核实承诺的版本和 更改日志条目,然后在 npm 之前运行检查、测试和构建 出版.
-   出版使用 npm 从拆分寄存器中信任的出版; 原件 `0.1.0` 手动出版.

公布的柏油丸包含 `dist/`, (中文(简体) ), `README.md`, (中文(简体) ), `LICENSE` 财务报告和审定财务报表 `package.json`· ; `dist/**/*.map` 文件不包括在内。 源地图留在 储存库和CI文物.

见 [释放客户](https://npmcn.com/package/%40dataemergencia/emergency/docs/release/releasing.md) 财务报告和审定财务报表 [变动情况](https://npmcn.com/package/%40dataemergencia/emergency/CHANGELOG.md)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @dataemergencia/emergency 是什么？

DataEmergencia 的框架不可知紧急情况客户端,设有可挂载回放面板和IIFE架构\.

### 如何安装 @dataemergencia/emergency？

在项目目录运行 npm install @dataemergencia/emergency，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dataemergencia/emergency 支持 TypeScript 吗？

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

### @dataemergencia/emergency 支持 ESM 还是 CommonJS？

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

### @dataemergencia/emergency 需要什么版本的 Node\.js？

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

### @dataemergencia/emergency 可以商用吗？

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

### @dataemergencia/emergency 的下载量有多少？

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

### @dataemergencia/emergency 还在维护吗？

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

