@dataemergencia/emergency

中文文档
0.7.0发布于 2026/11/10MITTypeScriptESM + CJS构建来源已验证近 30 天下载 1971

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

中文使用文档
文档目录14 节
  1. 文档
  2. 所需资源
  3. 安装
  4. 反应/无害环境管理快速启动
  5. 香草/IIFE 快速启动
  6. 挂载选项
  7. 客户端 API
  8. 活动
  9. BFF合同
  10. 标致和视觉合同
  11. 无障碍
  12. 发展
  13. 释放
  14. 许可证

@ dataemergencia/ 紧急情况

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

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

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

文档

BFF是一个单独的包: dataemergencia/emergency-bff。 。 。 .

所需资源

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

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

安装

pnpm add @dataemergencia/emergency

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

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 快速启动

<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/[email protected]/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。 。 。 .

挂载选项

选项类型页:1
rootHTMLElement | string主机集装箱. 在山上验证.
bffBaseUrlstring完整 BFF 路由前缀,包括 /de-bff/emergency。 。 。 .
codestring由宿主提供6个特征身份代码.
triggerstring | HTMLElement | (open) => void | (() => void)可选的 单击打开面板.
fallback{ phone, label }可选的 接收 emergency:fallback 用于主机UI.
themeEmergencyThemeCSS变量覆盖(参见Theming).
localestring默认为 es; 用于时间格式化.
geolocationTimeoutMsnumber默认为 8000。 。 。 .
requestTimeoutMsnumber默认为 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

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,以及 每条规则都带有文字倒置:

: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 挂载选项以禁用加载或 选择家族;参见 配置。 。 。 .

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

无障碍

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

发展

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

实例和视觉实验室:

# 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.jsIIFE与回放捆绑并注入CSS.

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

释放

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

整个本子是 释放客户简短 版本 :

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文物.

见 释放客户 财务报告和审定财务报表 变动情况。 。 。 .

许可证

麻省理工学院

版本与发布记录

@dataemergencia/emergency 共发布 11 个版本,首次发布于 2026/10/30;过去 12 个月发布了 11 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.7.0latest2026/11/106 天前
0.6.22026/11/079 天前
0.6.12026/11/079 天前
0.6.02026/11/079 天前
0.5.02026/11/0610 天前
0.4.02026/11/0511 天前

关于 @dataemergencia/emergency 的常见问题

@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 和提交记录判断。