@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 证书.

安装

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() 当用户点击时.

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 拒绝访问。 连接错误拒绝调用 。 处理你的应用程序中的错误。 在服务器渲染过程中导入软件包是安全的. 打开对话框需要浏览器 .

选择面板和外观

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

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

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

挂载内行

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

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 菜单或对话框时有此属性 .

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

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

没有对话框就使用 API 调用

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

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

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

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

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

请求使用当前来源和会话 。 他们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 计划改变时,比如这个动作.

处理反馈和错误

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

使用服务台捆绑

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

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

什么需要释放

释放

提升 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 存储器中运行 :

.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 失败。 国家留作纪念. 比尔林没有真正的指控。 其他试点业务仍然使用真正的本地长凳. 停止模拟器,完成后恢复原终点.