Used to check for browser translation.
用于检测浏览器翻译。
ブラウザの翻訳を検出する

开发 Blocklet


启动开发#

1. 在 blocklet.yml 中配置启动命令#

scripts:
dev: npm run start

scripts.dev 可以配置为任意命令

如果 blocklet 是纯前端的,则无需设置 scripts.dev. 见 blocklet.yml: Types


2. 在项目根目录下执行 blocklet dev#

启动完成后,你将在终端中看到 blocklet 的访问地址

示例:

✔ Blocklet xxxxxxx@x.x.x was successfully started

ℹ You can access with the following URL

- http://xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.did.abtnet.io


"blocklet dev" 会先在 Server 中安装一个应用,然后将这个 blocklet 自动挂在到此应用中并启动。如果你希望将你的 blocklet 挂在到其他应用中开发,见 “将 Blocklet 挂在到应用中开发”


将 Blocklet 挂在到应用中开发#

将 Blocklet 挂在到应用中开发,要为 blocklet dev 命令添加 --app-did 和 可选的 --mount-point 参数

blocklet dev --app-did <app-did> --mount-point /xxx

BLOCKLET_DEV_APP_DID=<app-did> BLOCKLET_DEV_MOUNT_POINT=/xxx blocklet dev

  1. .env 中配置
BLOCKLET_DEV_APP_DID=<blocklet-app-did>
BLOCKLET_DEV_MOUNT_POINT=/xxx
  1. blocklet dev


--app-did 可在 blocklet 详情页中查看(使用 App DID 或 Permanent DID 均可)

image.png

--mount-point: 即 blocklet 在应用中的挂载点,比如 /, /path, /path/to


Blocklet 挂载点#

Blocklet 是应用中的组件,会挂载在站点的某个路径中 ( //xxx )。所以 Blocklet 需要关注和挂载路径有关的事项,包括 “获取挂载点”、“API”、“重定向”、“加载前端静态资源”


获取挂载点#

前端:引入 blocklet 运行时信息 后, 通过 window.blocklet.prefix 获取组件的挂载点

后端:在一次请求中, 通过请求 header 中的 x-path-prefix 获取组件的挂载点.

server.use((req, res) => {
const mountPoint = req.headers['x-path-prefix'];
});


API#

Blocklet 自己的代码中,不需要 为 Web API 添加挂载点前缀,因为客户端的请求会先经过 Blocklet Service, 当组件收到请求时,已经去掉了请求的前缀

示例:

  1. 组件声明 API: /api/foo
  2. 组件挂载在 /child
  3. 客户端请求 /child/api/foo
  4. Blocklet Service 将请求转发给组件,并去掉前缀 /child
  5. 组件收到请求 /api/foo


重定向#

我们需要支持在相对路径下后端的重定向可以正常工作

const prefix = req.headers['x-path-prefix'];

res.redirect(`${prefix}path/to`);

我们需要支持在相对路径下前端的重定向可以正常工作

const prefix = window.blocklet.prefix;

window.location.href = `${prefix}path/to`;


加载前端静态资源#

因为 Blocklet 的前端页面会在相对路径下被加载(比如 /child1/index.html),所以我们需要支持在相对路径下加载前端静态资源。

在构建应用时,将应用的前端静态资源前缀改为 /.blocklet/proxy/<blocklet did>

示例:

PUBLIC_URL='/.blocklet/proxy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' npm run build

你通常不需要手动配置。当你使用 Create Blocklet 创建一个 Blocklet 项目时,已经为你配置好了一切。


停止开发#

启动开发后,在终端中按下 CTRL + C 停止开发


清空数据#

停止开发 blocklet 后,blocklet 的持久化数据并不会被自动清空。

你可以通过 blocklet dev clear 清空 blocklet 的所有数据

如果你将 blocklet 挂在到某个应用中,可通过 blocklet dev clear --app-did <app-did> 清空数据


获取配置#

blocklet 启动后,可通过 Blocklet SDK 获取 Blocklet 当前的运行环境和配置

获取运行环境:见 Blocklet SDK: Environment

获取配置:见 Blocklet SDK: Config


声明配置#

在 blocklet.yml 中声明配置:

environments:
- name: KEY_1
description: 'description for KEY_1'
default: ''
required: false
secure: false
shared: true
  • name: 变量名
  • description: 变量描述
  • default: 默认值
  • required: 是否必填
  • shared: 对客户端和组件是否可见
  • secure: securetrue 的环境变量会被加密存储,且对被客户端和组件不可见


开发 blocklet 时,也可在项目根目录中的 .env.env.development 文件中设置环境变量

注意:.env.env.development 中只能设置 blocklet.yml 声明的环境变量

示例:

# .env

KEY_1=value1


blocklet 安装后,使用者可以在 blocklet 管理面板中配置环境变量


在页面中获取 blocklet 运行环境#

你可以通过请求 blocklet 的 __blocklet__.js 接口获取 blocklet 运行环境

通过 Create Blocklet 创建的 blocklet 项目提供开箱即用的环境,你可以通过 window.blocklet 获取运行环境
// 应用 ID
window.blocklet.appId

// 应用版本
window.blocklet.version

// 应用名称
window.blocklet.appName

// 应用描述
window.blocklet.appDescription

// 应用 Url
window.blocklet.appUrl

// 共享的环境变量
window.blocklet.<shared env>


Blocklet Scripts#

Blocklet Server 提供了 hook 功能用来在执行生命周期的过程中做一些事情。目前包含 pre-install, post-install, pre-start, post-start, pre-stop, pre-uninstall, pre-config 这几个 Hook.

blocklet.yml: Scripts


在 blocklet 环境中运行脚本#

开发 blocklet 时, 有时我们想在 blocklet 环境下执行脚本(比如建立一些测试数据)。

可以通过执行 blocklet exec 实现,比如

blocklet exec mock/test.js

// mock/test.js

const { env } = require('@blocklet/sdk');
const { getWallet } = require('@blocklet/sdk');

console.log(env);
console.log(getWallet().address);


Blocklet 组件间通信#

使用 Blocklet SDK 和应用中的其他 Blocklet 通信

const { component } = require('@blocklet/sdk');

(async () => {
await component.call(name, path, data);
})();


如何在升级期间进行迁移#

当 blocklet 的持久化存储的数据结构发生不兼容改变时,我们可以使用 migration 脚本来完成自动数据迁移。

方法:

在 blocklet 根目录下创建 migration 目录

migration 目录中创建 migration 文件,文件名为 semver version, 比如 1.0.1.js

举例:

migration 目录中有 1.0.0.js, 1.0.1.js, 1.1.0.js 3 个文件

当 blocklet 从 1.0.0 升级至 1.2.0 时,会执行 1.0.1.js, 1.1.0.js 这两个 migration scripts

警告:需要将 migration 文件夹添加到 blocklet.yml 文件中的 files 字段中,如下所示:

files:
- ...
- migration
你获得 0 积分