# @ambasada/miniapp 中文文档

规范地址：https://npmcn.com/package/%40ambasada/miniapp/

版本：0\.8\.19
npm 元数据更新时间：2026-11-06T08:34:46.103Z
中文译文更新时间：2026-11-07T05:15:38.370Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ambasada/miniapp
原文对照：https://npmcn.com/package/%40ambasada/miniapp/?lang=original
项目主页：https://ambasada.id/

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

- 包体积（解压后）：38.6 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-11-02T10:02:43.296Z
- 最新版本发布：2026-11-06T08:34:45.912Z
- 近 30 天下载量：4548（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

在 Ambasada 应用程序内运行您的网络应用程序作为微型应用程序: 准备( )、 外壳上下文、 安全区域、 打开链接、 杂乱无章、 通知 。 零依赖关系;a

## 安装

```sh
npm install @ambasada/miniapp
```

也可以使用：`pnpm add @ambasada/miniapp`、`yarn add @ambasada/miniapp`、`bun add @ambasada/miniapp`

## README

# @ambasada/miniapp (英语)

Ambasada app的"小苹果"外壳的页面. 打电话 `ready()` 当绘制出您的第一个屏幕时,请读取 发射环境,尊重安全区域 和主机条,开放链接和其他微型应用程序, 要求偶然性, 默签和通知。 Ambasada app外的每通电话都是安全的,所以同一页是 也有一个简单的网站。 零依赖,~3 KB.

## 安装

```sh
npm install @ambasada/miniapp
```

```ts
import { ready, context, on } from "@ambasada/miniapp";

ready(); // after the first render: the shell drops the splash
```

或,没有建设步骤 `<script>` 建立中心服务(定义) `window.ambasada`:

```html
<script src="https://hub.ambasada.id/miniapp.js" defer></script>
<script>addEventListener("DOMContentLoaded", () => window.ambasada?.ready?.())</script>
```

这个 `ambasada init` 模板将两种表格运入,以及 `ambasada check` 当一个页面没有使用时警告.

## API 密码

| 打电话 | 在应用程序里 | 外边 |
| --- | --- | --- |
| `ready()` | 告诉 shell 绘制页面( 一次; 偶数); 设置 CSS 变量 | 将 CSS 变量设置为 0 |
| `shell()` | 输入 `window.ambasadaShell` (第2版) | `null` |
| `isInAmbasada()` | `true` (也用于老建筑,只设置 `AmbasadaChat/` 用户代理) | `false` |
| `context()` | `{ app, platform, safeArea, hostBar, theme, locale, user, location }`,默认旧外壳省略的内容 | 默认值 |
| `capabilities()` | 此 shell 构建支持( 第2 版 ): `openUrl`, (中文(简体) ), `close`(中文(简体) ) | `[]` |
| `applyCssVars()` | 写入 `--ambasada-safe-area-{top,bottom,left,right}` 财务报告和审定财务报表 `--ambasada-host-bar` 打开 `<html>` 并切换 `in-ambasada` 类 | 同为零 |
| `openUrl(url)` | 系统浏览器( 已验证的应用程序) 或确认工作表 | 新标签 |
| `openApp(id, path?)` | 这个上面还有个小应用程序 | `https://ambasada.id/a/<id><path>` 在新标签中 |
| `close()` | 关闭此小应用程序 | `history.back()` |
| `share({ url?, text? })` | 系统共享表 | 网络共享 API, 或者无 |
| `haptics.impact(style?)`, (中文(简体) ), `.notification(style?)`, (中文(简体) ), `.selection()` | 杂乱 | 无 |
| `setTitle(title)` | 主机栏的标题和 `document.title` | `document.title` |
| `auth.getToken()` | a 60 s JWT (中文(简体) )`aud` =你的来源或应用id, `sub` = Ambasada 用户 id),用于已安装的应用程序,其安装获准 `identity`; 对照 `https://hub.ambasada.id/.well-known/jwks.json` (单位:千美元)`auth.verifyShellToken` 位于 @ambasada/ sdk 中 | 拒绝: 返回与安巴萨达签约 |
| `auth.signInSilently({ endpoint?, me?, timeoutMs? })` | 当没人签字时, `getToken()` 写到 `/api/auth/shell`,用于设置会话;解决用户。 每页装入一次,最多5秒 | `null`,绝不拒绝:显示"与安巴萨达签约" |
| `auth.canSignInSilently()` | 在应用中,一个薄荷的外壳,一个在 `context.user` | `false` |
| `notifications.request()` | 贝壳的许可页 → `{ enabled }`; 您的网页wook 获得 `notifications_enabled` | `{ enabled: false }` |
| `on("context", fn)` 编号 : `on("notification", fn)` | 新的环境(安全区域、主题)/通知窃听器 `{ id, url }`; 返回未订阅 | 从不放火 |
| `mockEnv(overrides?)` | 本地开发: 安装版本 3 shell, 记录 `messages`,回答请求,返回 `{ messages, emit, uninstall }` | 不变(`ambasada dev` 用它来 |

布局: 将您的第一个屏幕由 `var(--ambasada-safe-area-top, 0px) + var(--ambasada-host-bar, 0px)` 在顶端 财务报告和审定财务报表 `var(--ambasada-safe-area-bottom, 0px)` 在底层。 这个 `0px` 倒计时将页面保留在网络上.

## 桥梁协议

本地应用程序注入 `window.ambasadaShell` 页面加载前 :

```ts
{ version: 3, platform: "ios" | "android" | "web", capabilities?: Capability[],
  app: { id, tier } | null, safeArea: { top, bottom, left, right }, hostBar: number,
  theme: { accent, scheme: "light" }, locale, user: { id, name, avatar } | null, location: LaunchLocation }
```

版本 2 贝壳( 当前应用程序) 只携带 `version`, (中文(简体) ), `platform` 财务报告和审定财务报表 `safeArea`SDK掉回原点 v2 邮件 (`chrome`, (中文(简体) ), `open`为他们.

**页 应用**:每个呼叫一个JSON消息,通过 `webkit.messageHandlers.ambasada.postMessage(obj)` 在iOS上或 `window.ambasada.postMessage(json)` 在Android上显示:

| 消息 | 字段 |
| --- | --- |
| `ready` |  |
| `openUrl` | `url` |
| `openApp` | `app`, (中文(简体) ), `path?` |
| `close` |  |
| `share` | `url?`, (中文(简体) ), `text?` |
| `haptic` | `kind: impact | notification | selection`, (中文(简体) ), `style?` |
| `title` | `title` |
| `request` | `id`, (中文(简体) ), `method: auth.getToken | notifications.request` |
| `chrome` (v2级) | `header?`, (中文(简体) ), `tabs?`, (中文(简体) ), `title?`, (中文(简体) ), `back?`, (中文(简体) ), `statusBar?` |
| `open` (v2级) | `url`, (中文(简体) ), `mode: in-app | external | sheet` |

**应用 – 页**数字 : `CustomEvent`发送日期 `window`数字 :

| 活动 | `detail` |
| --- | --- |
| `ambasada:reply` | `{ id, result }` 或者说 `{ id, error }`,回答一个 `request` (SDK在15 s后放弃) |
| `ambasada:context` | a (部分)新设 `ShellContext`; SDK 将其合并为 `window.ambasadaShell` 并重新应用 CSS 变量 |
| `ambasada:notification` | `{ id, url }`,在此应用程序打开时窃听通知 |

这个 `<script>` 将合并成已有的 `window.ambasada` (Android的桥对象)而不是替换 这样 `window.ambasada.postMessage` 继续工作 `window.ambasada.ready()`。 。 。 .

## 构建

`node scripts/build.mjs` 写入 `dist/index.js` (ESM), `dist/miniapp.js` (经典脚本,全局 `ambasada`和 `dist/index.d.ts`中心提供服务 `dist/miniapp.js` 时间 `https://hub.ambasada.id/miniapp.js`。 。 。 .

(原始内容存档于2013-10-12). MIT, CENTYSO.

## 常见问题

### @ambasada/miniapp 是什么？

在 Ambasada 应用程序内运行您的网络应用程序作为微型应用程序: 准备\( \)、 外壳上下文、 安全区域、 打开链接、 杂乱无章、 通知 。 零依赖关系;a

### 如何安装 @ambasada/miniapp？

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

### @ambasada/miniapp 支持 TypeScript 吗？

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

### @ambasada/miniapp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ambasada/miniapp 可以商用吗？

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

### @ambasada/miniapp 的下载量有多少？

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

### @ambasada/miniapp 还在维护吗？

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