# @bmsuisse/app-native 中文文档

规范地址：https://npmcn.com/package/%40bmsuisse/app-native/

版本：0\.5\.0
npm 元数据更新时间：2026-10-12T12:59:02.148Z
中文译文更新时间：2026-11-08T09:20:20.296Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bmsuisse/app-native
原文对照：https://npmcn.com/package/%40bmsuisse/app-native/?lang=original
项目主页：https://github.com/bmsuisse/bmsapp-native/tree/main/packages/app-native#readme
源码仓库：https://github.com/bmsuisse/bmsapp-native

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

- 包体积（解压后）：118 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-05T12:17:20.178Z
- 最新版本发布：2026-10-12T12:59:01.705Z
- 近 30 天下载量：2446（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

BMS应用程序的Web App侧:打入呼叫窗口. BMSNative(色调,土司,分享,扫描,部件,活活活动,批准,本土形式和内容) 有浏览器倒置.

## 安装

```sh
npm install @bmsuisse/app-native
```

也可以使用：`pnpm add @bmsuisse/app-native`、`yarn add @bmsuisse/app-native`、`bun add @bmsuisse/app-native`

## README

# @bmsuisse/app-inative

BMS 应用的 Web 应用侧: 打入呼叫 `window.BMSNative`,该 app注入到每个网络应用中——有浏览器倒回,所以同一页 也运行在应用程序之外。 没有依赖关系, 不需要反应 .

后端对应 : [`bmsdna-app-native`](https://npmcn.com/package/python/app-native) (毕. 每个专题的详细指南: [`docs/`](https://npmcn.com/package/docs),用于当地形式和 内容 [土地平面导线(md)](https://npmcn.com/package/docs/native-surfaces-guide.md)。 。 。 .

## 安装

```bash
npm install @bmsuisse/app-native
# or
bun add @bmsuisse/app-native
```

## 实例

```ts
import {
  isNativeApp,
  can,
  on,
  setChrome,
  toast,
  haptic,
  share,
  biometricConfirm,
  scanBarcode,
  scanBarcodes,
  scanText,
  setWidgets,
  getAccessToken,
  navigate,
  addReminder,
  saveContact,
  callPhone,
  toIsoWithOffset,
  canShowNativeForms,
  isNativeSurfaceUnsupported,
  showForm,
  showContent,
} from '@bmsuisse/app-native'

// Is the page running in the app? Does it have a given capability?
if (isNativeApp() && can('customChrome')) {
  setChrome({
    scope: 'route',
    menu: [{ items: [{ id: 'new-order', label: 'New order', icon: 'plus' }] }],
    actionButtons: [{ id: 'search', icon: 'magnifyingglass' }],
  })
}

// Taps in the native menu — instead of setting window.onNativeMenuSelect yourself
const off = on('menuSelect', (id) => navigate(`/${id}`))

// Feedback
toast('Saved', 'success')
haptic('success')

// Share: app → native share sheet, browser → Web Share API / clipboard
await share({ title: 'Order 123', url: location.href })

// Face ID before a critical action (UX only, no proof for the backend)
const { ok } = await biometricConfirm('Approve order?')

// Scan a barcode; the result arrives as an event
on('barcodeScanned', (value) => lookup(value))
await scanBarcode()

// Or let the promise carry the result: several codes, or text from a label
// (docs/scan-guide.md). Keep a way to type the value in.
const codes = await scanBarcodes({ formats: ['ean13', 'qr'], max: 20 })
const serial = await scanText({ pattern: '[A-Z]{2}-\d{4,}' })

// Widgets on the native dashboard
await setWidgets([{ id: 'open-orders', kind: 'kpi', title: 'Open', data: { value: 12 } }])

// Entra token of the app's sign-in. Only needed where the browser cannot set a
// header (WebSocket, EventSource, …): fetch/XHR to your own backend get it automatically.
const session = await getAccessToken()
if (session.ok) socket.send(JSON.stringify({ token: session.token }))

// Other apps on the iPhone: route, reminder, contact, phone call
await navigate({ destination: { name: 'Müller AG', address: 'Industriestrasse 5, 4600 Olten' } })
await addReminder({ title: 'Call Mr. Meier back', due: toIsoWithOffset(new Date(2026, 9, 2, 9)) })
await saveContact({ givenName: 'Anna', organization: 'Müller AG', phones: ['+41 44 000 00 00'] })
await callPhone({ number: '+41 44 000 00 00' })

// Native form (an iOS sheet). The form stays open until your handler settles:
// `{ fieldErrors }` or a thrown error marks fields and lets the user correct.
if (canShowNativeForms()) {
  const res = await showForm(
    {
      id: 'new-customer',
      title: 'New customer',
      fields: [
        { id: 'name', type: 'text', label: 'Company name', required: true },
        { id: 'email', type: 'email', label: 'Email', required: true },
        { id: 'card', type: 'photo', label: 'Business card', max: 1 },
      ],
    },
    { onSubmit: async (values) => await api.createCustomer(values) }
  )
  if (!res.ok && isNativeSurfaceUnsupported(res)) openWebForm() // old app, no capability
} else {
  openWebForm()
}

// Native content: info with blocks and buttons
const shown = await showContent({
  title: 'Miller Ltd',
  blocks: [
    { type: 'facts', items: [{ label: 'Phone', value: '+41 44 000 00 00', kind: 'phone' }] },
  ],
  actions: [{ id: 'new-order', label: 'New order', style: 'primary' }],
})
```

## 应用程序外的行为

| 函数 | 浏览器 |
| --- | --- |
| `toast`, (中文(简体) ), `haptic`, (中文(简体) ), `setBadge`, (中文(简体) ), `setChrome` | 无所作为 |
| `share` | Web 共享 API, 否则剪贴板(`'copied'`(中文(简体) ) |
| `openExternal` | 新建标签 |
| `biometricConfirm` | `{ ok: true }` (网络流量继续) |
| `navigate` | 在新标签中的 Google 地图 |
| `callPhone` | `tel:` 链接 |
| `showForm`, (中文(简体) ), `showContent`, (中文(简体) ), `closeSurface` | `{ ok: false, error: 'unavailable' }` - 保持您的网络用户界面`canShowNativeForms()`(中文(简体) ) |
| 所有其他(`setWidgets`, (中文(简体) ), `startLiveActivity`, (中文(简体) ), `scanDocument`, (...) (中文(简体) ) | `{ ok: false, error: 'unavailable' }` |

## 答复和错误

有回复的呼叫 `{ ok: true, … }` 或者说 `{ ok: false, error }`。 。 。 . 常见错误 : `capability` (该应用程序尚未赋予该能力) 网络应用程序, `invalid`, (中文(简体) ), `cancelled`, (中文(简体) ), `unavailable`, (中文(简体) ), `notConfigured`; 用于 `getAccessToken` (单位:千美元) `forbidden` 财务报告和审定财务报表 `notSignedIn`; 设备动作 `denied`; 用于 `showForm`编号 :`showContent` (单位:千美元) `forbidden`, (中文(简体) ), `busy` 财务报告和审定财务报表 `tooLarge`。 。 。 . 一个在呼叫答案之前的应用程序 `unknownAction`: 对待它像 `unavailable`。 。 。 . `can(capability)` 但应用程序总是检查它的 拥有的.

## 概览

| 区域 | 职能 | 能力 |
| --- | --- | --- |
| 检测 | `isNativeApp`, (中文(简体) ), `nativeInfo`, (中文(简体) ), `can` | – 说吧 – |
| 活动 | `on('menuSelect' | 'actionButtonTap' | 'bottomBarTap' | 'barcodeScanned' | 'barcodesScanned' | 'textScanned', …)` | – 说吧 – |
| 颜色 | `setChrome`, (中文(简体) ), `centerProminentEntry` | `customChrome`, (中文(简体) ), `customBottomBar` |
| 反馈 | `toast`, (中文(简体) ), `haptic`, (中文(简体) ), `setBadge` | – 说吧 – |
| 系统 | `share`, (中文(简体) ), `openExternal`, (中文(简体) ), `biometricConfirm` | – 说吧 – |
| 相机 | `scanDocument`, (中文(简体) ), `scanBarcode`, (中文(简体) ), `scanBarcodes`, (中文(简体) ), `scanText`, (中文(简体) ), `canScan` (单位:千美元)[指南](https://npmcn.com/package/docs/scan-guide.md)(中文(简体) ) | `camera` |
| 部件 | `setWidgets`, (中文(简体) ), `updateWidget`, (中文(简体) ), `removeWidgets`, (中文(简体) ), `refreshWidgets` | `dashboardWidgets` |
| 现场活动 | `startLiveActivity`, (中文(简体) ), `updateLiveActivity`, (中文(简体) ), `endLiveActivity`, (中文(简体) ), `getLiveActivities` | `liveActivities` |
| 核准 | `refreshApprovals` | `approvals` |
| 签名 | `getAccessToken` | `identity` |
| 其他应用程序 | `navigate`, (中文(简体) ), `callPhone`, (中文(简体) ), `addReminder`, (中文(简体) ), `saveContact`, (中文(简体) ), `toIsoWithOffset` | `deviceApps` (警报,联系) |
| 土著形式 | `showForm`, (中文(简体) ), `canShowNativeForms`, (中文(简体) ), `formLimitWarnings` | `nativeForms` (+ 数) `camera` (用于相机字段) |
| 原生内容 | `showContent`, (中文(简体) ), `canShowNativeContent`, (中文(简体) ), `contentLimitWarnings` | `nativeContent` (+ 数) `deviceApps` 页:1 `saveContact`编号 :`addReminder` 步骤) |
| 表面 | `closeSurface`, (中文(简体) ), `surfaceResult`, (中文(简体) ), `isNativeSurfaceUnsupported`, (中文(简体) ), `on('surfaceAction', …)`, (中文(简体) ), `onSurfaceAction` | `nativeForms` 或者说 `nativeContent` |
| 测试 | `sendTestNotification` | `notifications` |
| 原始接入 | `call`, (中文(简体) ), `post`, (中文(简体) ), `send` | – 说吧 – |

## 许可证

[麻省理工学院](https://npmcn.com/package/%40bmsuisse/app-native/LICENSE)

## 常见问题

### @bmsuisse/app-native 是什么？

BMS应用程序的Web App侧:打入呼叫窗口\. BMSNative\(色调,土司,分享,扫描,部件,活活活动,批准,本土形式和内容\) 有浏览器倒置\.

### 如何安装 @bmsuisse/app-native？

在项目目录运行 npm install @bmsuisse/app-native，或使用 pnpm add / yarn add / bun add。

### @bmsuisse/app-native 支持 TypeScript 吗？

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

### @bmsuisse/app-native 支持 ESM 还是 CommonJS？

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

### @bmsuisse/app-native 可以商用吗？

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

### @bmsuisse/app-native 的下载量有多少？

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

### @bmsuisse/app-native 还在维护吗？

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