# @frappe/cloud-sdk 中文文档

规范地址：https://npmcn.com/package/%40frappe/cloud-sdk/

版本：0\.7\.0
npm 元数据更新时间：2026-11-08T15:06:30.299Z
中文译文更新时间：2026-11-15T12:24:55.019Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40frappe/cloud-sdk
原文对照：https://npmcn.com/package/%40frappe/cloud-sdk/?lang=original
项目主页：https://github.com/frappe/pilot#readme
源码仓库：https://github.com/frappe/pilot

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

- 包体积（解压后）：40.6 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-13T13:46:19.420Z
- 最新版本发布：2026-11-08T15:06:29.971Z
- 近 30 天下载量：23824（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

Frappe Cloud 站点设置的 API 客户端和对话框

## 安装

```sh
npm install @frappe/cloud-sdk
```

也可以使用：`pnpm add @frappe/cloud-sdk`、`yarn add @frappe/cloud-sdk`、`bun add @frappe/cloud-sdk`

## README

# @frappe/cloud-sdk (英语)

在 Frappe 应用程序中使用 Cloud 设置 。 SDK提供打入的API呼叫和即用设置对话框. 它在Office,React,Vue,以及平版浏览器页面中工作.

使用共享对话框获取整个应用程序一致的 Cloud 设置体验 。 如果您的应用程序需要自己的用户界面, 请使用没有对话框的 API 调用 .

## 所需资源

-   一个由Cloud Settings服务器APIs管理的Pilot管理Frappe网站.
-   一个带有系统管理员角色的签名用户.
-   网站的会话饼干。 写电话也需要 `frappe.csrf_token` 或者说 `window.csrf_token`。 。 。 .

服务器检查每个电话的访问权限. 浏览器不接收 Pilot 或 Central 证书.

## 安装

```sh
npm install @frappe/cloud-sdk
```

包裹内有API的呼叫和一个小装填器. 它不持有UI。 当您打开对话框时, 装入器从现场的 Pilot 服务器中导入UI `esm/` 脚本 URL 旁边的路径 `bundle.js` 联 合 国 `get_context`。每个面板在首次显示时会加载。 因此,一个 Pilot 更新会改变每个应用程序的UI,而您的应用程序不需要新的发布. 您不需要在您的应用程序中添加 Vue, Frappe UI 或样式表 .

浏览器必须到达Pilot服务器,页面的内容安全政策必须允许从中获取脚本. 如果UI不装载, `openCloudSettings()` 以一个口信拒绝.

对话框使用Inter字体 。 如果该页面没有加载Inter,对话框在它首次打开时会将其添加到页面中.

## 打开云设置

仅在 `isCloudSettingsAvailable()` 返回时 `true`调用 `openCloudSettings()` 当用户点击时.

```ts
import { isCloudSettingsAvailable, openCloudSettings, closeCloudSettings } from '@frappe/cloud-sdk'

const available = await isCloudSettingsAvailable()

async function openSettings() {
  try {
    await openCloudSettings({ panels: ['billing', 'domains', 'advanced'] })
  } catch (error) {
    // Show this message in your app's alert or error component.
    console.error(error instanceof Error ? error.message : 'Could not open Cloud Settings.')
  }
}

// Call this when the host page or component is removed.
closeCloudSettings()
```

在反应中,使用 `onClick={openSettings}`在 Vue 中,使用 `@click="openSettings"`。在普通页面中,使用 `button.addEventListener('click', openSettings)`对话框打开时禁用按钮 .

可用性是同步的。 它回来了 `false` 拒绝访问。 连接错误拒绝调用 。 处理你的应用程序中的错误。 在服务器渲染过程中导入软件包是安全的. 打开对话框需要浏览器 .

## 选择面板和外观

```ts
await openCloudSettings({
  panels: ['billing', 'domains'],
  tab: 'domains',
  theme: 'auto',
  onClose: () => console.log('Cloud Settings closed'),
})
```

| 选项 | 目的 |
| --- | --- |
| `panels` | 选择要显示的面板 。 关闭它或使用空数组来显示全部 。 未知名称被忽略 。 此选项不更改权限 . |
| `tab` | 选择第一个面板。 默认是第一个可见的面板. |
| `theme` | 使用 `auto`, (中文(简体) ), `light`,或 `dark`自动跟踪 `html[data-theme="dark"]` 或者说 `html.dark`。 。 。 . |
| `translate` | 供应 `(message, values?) => string`。默认使用 Frappe 的翻译目录并替换已编号的值. |
| `onClose` | 对话框关闭后运行回调 . |
| `context` | 供应a `CloudContext`没有它,SDK会读取当前网站的背景. |
| `target` | 在此元素内渲染面板而不是对话框 。 见 [挂载内行](https://npmcn.com/package/%40frappe/cloud-sdk/#readme-mount-inline)。 。 。 . |
| `app` | 命名服务于此页面的应用程序, 例如 `crm`。当用户从 Complateplace 面板上卸下该应用程序时,页面已不存在,因此 Cloud 设置将用户发送给 `/desk`放在办公桌里. |

面板名称 : `billing`, (中文(简体) ), `marketplace`, (中文(简体) ), `analytics`, (中文(简体) ), `domains`, (中文(简体) ), `backups`, (中文(简体) ), `usage`, (中文(简体) ), `site-config`, (中文(简体) ), `maintenance`,以及 `advanced`。 。 。 .

对话框使用 Espresso 组件 。 在电话上,它填充了取景口,并有一个面板选择器. 当页面设定时,它远离了 Notch 和 主指示器 `viewport-fit=cover` 在其视图元标记。 在桌面上,它有一个侧边栏. 它的风格,菜单,对话框,警报,和土司都留在了阴影根中. 关闭将删除 UI 并返回焦点到按钮中 。 再次打开取代当前对话框 。 关闭也会取消一个待定的开放 .

## 挂载内行

具有自己设置页面的应用程序可以显示其内部的面板. 传递要填充的元素为 `target`。各面板填充其高度,所以给出元素一。 一个面板,UI没有侧边栏,也没有面板选择器,因此应用程序自己的导航仍然是唯一一个. 通过多块面板,侧边栏显示元素内部.

```ts
await openCloudSettings({ target: document.querySelector('#cloud-settings'), panels: ['billing'] })

// Call this when the host page or component is removed.
closeCloudSettings()
```

再次打开, 内置或作为对话框, 替换挂载的 UI 。 菜单,对话,和吐司 留在元素的阴影根.

内置的UI为分页顺序,因此Tab从主机页面移动到面板. 主机可以在自己的模式内显示内置的UI. 然后Esc,或者在打开的 Cloud 菜单或对话框外点击,关闭它,同时也关闭主机模式. 为了防止这种情况 忽略模式的接近 `fc-cloud-settings[overlay-open]` 已存在。 元素在打开 Cloud 菜单或对话框时有此属性 .

```ts
const isCloudOverlayOpen = () => !!document.querySelector('fc-cloud-settings[overlay-open]')
```

```vue
<Dialog :open="show" @update:open="(open) => (open || !isCloudOverlayOpen()) && (show = open)">
```

## 没有对话框就使用 API 调用

您可以用 API 调用来构建自己的页面、面板或控制 。 这个 `/api` 导入不会装入共享的 UI 。 您的应用程序控制布局并处理加载, 空状态, 错误, 以及成功反馈 .

```ts
import { getBilling, getDomains } from '@frappe/cloud-sdk/api'

const billing = await getBilling()
const domains = await getDomains()
```

根导入和 `/api` 导出相同的API呼叫和TypeScript模型. 使用 `/api` 当您只需要数据时.

在读取的呼叫上建立自己的UI,例如计划徽章或横幅. 对于修改,请打开右面板上的对话框,例如 `openCloudSettings({ tab: 'billing' })`。动作调用跟随对话框的流量,它们的步骤可以在版本之间变化. 付款安排就是一个例子.

| 区域 | 读取电话 | 行动呼吁 |
| --- | --- | --- |
| 站点 | `getContext`, (中文(简体) ), `getAccountUrl`, (中文(简体) ), `getTask` | 无 |
| 计费 | `getBilling`, (中文(简体) ), `getPlanOptions`, (中文(简体) ), `getBillingProfile`, (中文(简体) ), `getPaymentGateways`, (中文(简体) ), `getInvoices`, (中文(简体) ), `getInvoicePdf` | 变更计划,保存剖面,设置或去除支付方法,调节设置,支付发票(`createInvoiceCheckout`,则 `getCheckoutStatus`(中文(简体) ) |
| 应用程序 | `getMarketplaceApps` | 安装、 卸载、 更新 |
| 域数 | `getDomains` | 读取 DNS 记录、 添加、 删除、 设置主记录 |
| 备份 | `getBackups`, (中文(简体) ), `getBackupDownloadLinks` | 创建, 删除 |
| 监测 | `getAnalytics`, (中文(简体) ), `getUptime`, (中文(简体) ), `getStorage` | 刷新存储 |
| 站点配置 | `getSiteConfig` | 更新配置 |
| 维修 | 无 | 清除缓存, 迁移 |

请求使用当前来源和会话 。 他们30秒后就超时了 SDK不重试写电话.

`getBilling` 返回时 `next_bill`:这个网站的服务器在团队下一个账单中的份额,与 `amount`, (中文(简体) ), `subtotal`, (中文(简体) ), `tax`, (中文(简体) ), `tax_type`, (中文(简体) ), `charge_on`, (中文(简体) ), `days_left`,则 `lines` 后面,还有.. `blockers`团队指控失败的原因 只为阻断器显示警告 . `getInvoices` 返回此服务器在每个团队发票中的份额, 首先是最新的 . `has_pdf` 财务报告和审定财务报表 `can_pay` 只有在发票仅覆盖了这个服务器时才属实,因为发票PDF及其付款覆盖了整个团队. `getInvoicePdf(invoice)` 返回时 `{ filename, content }`,以PDF为基数64.

`changePlan(plan)` 返回时 `{ queued, resized, progress_url }`一个新的尺寸 停止网站几分钟。 何时 `progress_url` 设置, 打开它: 页面存在于中央, 并在网站准备好后将用户带回。 在一次免费审判中,呼叫会改变任何大小:中央保留计划,当支付方法转换审判时,站点会移动到它. `getPlanOptions` 然后列出审判可能采用的付费计划 `selected` 设定计划,它移动到. `getBilling` 返回时 `plan_change.progress_url` 计划改变时,比如这个动作.

## 处理反馈和错误

| 状态 | 对话框行为 |
| --- | --- |
| 正在装入 | 在面板上显示一具骨架. |
| 无数据 | 显示空信件和下一个可用的动作 . |
| 装入失败 | 用再次尝试按钮在面板上显示错误 . |
| 格式或动作失败 | 在窗体或动作旁显示错误 . |
| 动作正在运行 | 显示加载按钮并禁用相冲突动作 . |
| 行动完成 | 刷新数据或显示短暂的成功祝酒词 . |
| 任务仍在运行 | 显示背景状态消息 。 关闭UI停止投票,而不是服务器任务. |

对话框打开前的直接 API 呼叫和出错属于您的应用程序 。 接着 `CloudSettingsError` 并显示其 `message`。它也已经 `status`, (中文(简体) ), `serverMessages`,以及 `excType`二. 现况 `0` 指网络故障. 信件是纯文本 .

## 使用服务台捆绑

试点服务于同一UI的两栋建筑 `/embed/cloud-settings/`数字 :

| 路径 | 格式 | 用于 |
| --- | --- | --- |
| `cloud-settings.js` | 一个经典剧本 | 办公室,通过 `frappe.cloudSettings.show(context, options)`它也暴露了 `window.FrappeCloudSettings` 以相同的可用性,开放和接近的方法. |
| `esm/cloud-settings.js` 财务报告和审定财务报表 `esm/chunks/` | 每个面板块的ES模块 | Npm 软件包 |

两个条目文件在每个负载上重新验证,因此一个Pilot更新立即生效. 春克名称包含内容散列,因此浏览器缓存它们一年. ES文件是随 `Access-Control-Allow-Origin: *`因为一个地点是从飞行员的原产地进口的.

## 什么需要释放

| 变动 | 释放 |
| --- | --- |
| 对话框内的任何内容, 如复制、 版式、 字段、 或使用已有调用的流动 | 试点更新 |
| 回复中的新数据 | 中央部署. Frappe代理通过回复. |
| 新建或重新命名的对话框 | Frappe发布,因为白名单的代理方法生活在Frappe |
| 此套件的公开 API : `openCloudSettings` 选项,面板名称, `isCloudSettingsAvailable`,或输入的调用 `@frappe/cloud-sdk/api` | 此软件包的新版本, 然后在每个应用程序中升级 |

## 释放

提升 `version` 内 `package.json` 财务报告和审定财务报表 `package-lock.json` 在拉请求。 当它合并为 `develop`,则 `Publish Cloud SDK` 工作流程测试,构建并发布该版本到 npm. 它跳过 npm 已经拥有的版本 。 运行失败后, 手动运行工作流程以再次发布当前版本 .

npm通过可信赖的发布来信任工作流程,因此寄存器没有npm符. 软件包维护器在 npmjs.com 上设置此功能: `@frappe/cloud-sdk` 设置, 为仓库添加 GitHub 动作信任的发布器 `frappe/pilot` 和工作流程 `cloud-sdk-publish.yml`。 。 。 .

## 构建和测试

运行 `npm test` 财务报告和审定财务报表 `npm run build` 本包中。 运行 `npm run build` 内 `admin/frontend/in-app-embed` 试点产出 `admin/backend/static/in-app-embed/cloud-settings/`。该构件还检查ES运行时会输出其方法,包含其样式,并按要求加载面板.

要运行浏览器回归测试, 请在 `admin/frontend/dashboard` 财务报告和审定财务报表 `admin/frontend/in-app-embed`,然后构建此软件包并嵌入内置。 运行 `npx playwright install chromium` 财务报告和审定财务报表 `npx playwright test --config cloud-settings.config.ts` 从 `admin/frontend/dashboard`。测试检查SDK是否从 Pilot 装入 UI, 并且只有在显示、 对话框清理、 自定义反馈翻译、 任务取消和恢复以及电话布局时才装入一个面板. `cloud-settings-billing.spec.ts` 检查计费标签:审判通知及其状态,审判期间的计费细节和支付步骤,国家及印度州列表,一张未验证的卡,计划列表,移动到进度页,以及拒绝,支出限制和重试状态. `cloud-settings-marketplace.spec.ts` 检查试运行是否保留了它所要的应用程序,在未安装前的备份报价,在主机应用程序被移除后移动到桌面,任务卡的标志和位置,以及应用程序细节等指针移动. CI在MariaDB浏览器工作上运行这些测试.

要测试所有带有样本数据的面板,请构建这个软件包并嵌入应用中. 运行 `python3 -m http.server 8123` 从寄存器根。 打开 `http://localhost:8123/admin/frontend/cloud-sdk/tests/embed.html`。在此固定位置上没有真正的付款或现场操作.

要测试没有主机元数据的计费, 请从 Pilot 存储器中运行 :

```sh
.venv/bin/python -m scripts.cloud_settings_simulator --bench-root /path/to/local/bench
```

使用具有服务器 API 和按钮的本地开发站点打开对话框 。 设置网站 `pilot_endpoint` 改为 `http://127.0.0.1:8003`,然后清除其缓存。 保留其现有的站点标志. 签入为系统管理员 并打开帐单。 模拟控制在 `http://127.0.0.1:8124`。保存样本配置文件,完成本地检查,然后单击检查状态。 测试试验流程,选择 **开始免费审判** 在控制页上: 计费后显示没有发票的公开审判,完成的结账则转换. **结束自由审判** 显示一个不转换而结束的试验。 当试验转换为更大的计划时,比林会显示动作,再将浏览器发送到模拟的进度页面上,移动结束后返回站点. 启动模拟器 `--trial-app <app>` 以命名审判的应用, 和中央一样。 Marketplace面板随后将安装该应用程序,直到试验转换. 国家与GST州列表来自法官席的"Frappe"和"Central Apps", 印度INR的法案地址通过Razorpay, Razorpay Checkout需要真正的Razorpay密钥,所以模拟在那个阶段停止. 您可以重置数据或模拟 API 失败。 国家留作纪念. 比尔林没有真正的指控。 其他试点业务仍然使用真正的本地长凳. 停止模拟器,完成后恢复原终点.

## 常见问题

### @frappe/cloud-sdk 是什么？

Frappe Cloud 站点设置的 API 客户端和对话框

### 如何安装 @frappe/cloud-sdk？

在项目目录运行 npm install @frappe/cloud-sdk，或使用 pnpm add / yarn add / bun add。

### @frappe/cloud-sdk 支持 TypeScript 吗？

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

### @frappe/cloud-sdk 支持 ESM 还是 CommonJS？

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

### @frappe/cloud-sdk 可以商用吗？

@frappe/cloud-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @frappe/cloud-sdk 的下载量有多少？

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

### @frappe/cloud-sdk 还在维护吗？

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