@tomjs/vite-plugin-hbuilderx
v1.3.0
Published
为 HBuilderX 开发插件提供 vite 插件，可以使用 vue/react 开发 webview 的视图等
Maintainers
tomgao365Readme
@tomjs/vite-plugin-hbuilderx
为 HBuilderX 开发 插件 提供 vite 插件，可以用
vue/react来开发 WebView视图 和 WebView页面的对话框。
在开发模式时，使用 iframe 加载 vue/react 服务，在 iframe 和 parent 之间模拟 hbuilderx.postMessage等方法，用来支持 HMR；生产构建时，将最终生成的 index.html 代码注入到 插件代码 中，减少工作量。
特性
安装
# pnpm
pnpm add -D @tomjs/vite-plugin-hbuilderx
# yarn
yarn add -D @tomjs/vite-plugin-hbuilderx
# npm
npm add -D @tomjs/vite-plugin-hbuilderx使用说明
推荐约定
设置 recommended 参数为 true 会修改一些预置配置，详细查看 PluginOptions 和 recommended 参数说明。
目录结构
- 默认情况下，
recommended:true会根据如下目录结构作为约定
|--extension // extension code
| |--index.ts
|--src // front-end code
| |--App.vue
| |--main.ts
|--index.html- 零配置，默认 dist 输出目录
|--dist
| |--extension
| | |--index.js
| | |--index.js.map
| |--webview
| | |--index.html- 如果你想修改
extension源码目录为src，可以设置{ extension: { entry: 'src/index.ts' } }
|--src // extension code
| |--index.ts
|--webview // front-end code
| |--App.vue
| |--main.ts
|--index.htmlextension
tsconfig.json
{
"compilerOptions": {
"types": [
"@tomjs/hbuilderx/types",
"@tomjs/vite-plugin-hbuilderx/types"
]
}
}代码片段，更多配置看示例
import { ExtensionContext, WebviewPanel } from 'hbuilderx';
import { getWebviewHtml } from 'virtual:hbuilderx';
function createWebView(webviewPanel: WebViewPanel, context: ExtensionContext) {
// vite 开发模式和生产模式注入不同的webview代码，减少开发工作
webviewPanel.webview.html = getWebviewHtml({
// vite 开发模式 iframe 嵌入页面
serverUrl: process.env.VITE_DEV_SERVER_URL,
// vite 生产模式 将html代码注入到插件中
// 来自插件激活时的上下文
context,
inputName: 'index',
// 向 head 元素的结束前注入代码 <head>--inject--
injectCode: `<script>window.__FLAG1__=666;window.__FLAG2__=888;</script>`,
});
}
const panel = window.createWebView('showHelloWorld', {
enableScripts: true,
});
createWebView(panel, context);package.json
{
"main": "dist/extension/index.js"
}vue
vite.config.ts
import hbuilderx from '@tomjs/vite-plugin-hbuilderx';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
vue(),
hbuilderx(),
// 修改插件源码入口路径，同时修改`index.html`入口文件路径
// hbuilderx({ extension: { entry: 'src/index.ts' } }),
],
build: {
// 将图片等静态资源文件转换为 base64
assetsInlineLimit: 1024 * 100,
},
});react
vite.config.ts
import hbuilderx from '@tomjs/vite-plugin-hbuilderx';
import react from '@vitejs/plugin-react-swc';
import { defineConfig } from 'vite';
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react(), hbuilderx()],
});多页面
多页面应用
可查看 ext-web-vue-multiple 示例
vite.config.ts
import path from 'node:path';
import hbuilderx from '@tomjs/vite-plugin-hbuilderx';
export default defineConfig({
plugins: [hbuilderx()],
build: {
rollupOptions: {
// https://cn.vitejs.dev/guide/build.html#multi-page-app
input: [path.resolve(__dirname, 'index.html'), path.resolve(__dirname, 'index2.html')],
// 也可自定义名称
// input:{
// 'index': path.resolve(__dirname, 'index.html'),
// 'index2': path.resolve(__dirname, 'index2.html'),
// }
},
},
});- 页面一
import { ExtensionContext, WebviewPanel } from 'hbuilderx';
import { getWebviewHtml } from 'virtual:hbuilderx';
function createWebView(webviewPanel: WebViewPanel, context: ExtensionContext) {
webviewPanel.webview.html = getWebviewHtml({
serverUrl: process.env.VITE_DEV_SERVER_URL,
context,
});
}- 页面二
import { ExtensionContext, WebviewPanel } from 'hbuilderx';
import { getWebviewHtml } from 'virtual:hbuilderx';
function createWebView(webviewPanel: WebViewPanel, context: ExtensionContext) {
webviewPanel.webview.html = getWebviewHtml({
serverUrl: process.env.VITE_DEV_SERVER_URL,
context,
// 页面input名称
inputName: 'index2',
});
}单页面传参
单个页面通过 URL 传参和注入代码实现传参，前端需要做兼容处理
- 插件代码
extension.ts
import { ExtensionContext, WebviewPanel } from 'hbuilderx';
import { getWebviewHtml } from 'virtual:hbuilderx';
function createWebView(webviewPanel: WebViewPanel, context: ExtensionContext) {
webviewPanel.webview.html = getWebviewHtml({
injectCode: `<script>window.__id__=666;</script>`,
serverUrl: `${process.env.VITE_DEV_SERVER_URL}?id=666`,
context,
});
}- 页面简易实现，根据实际情况自行实现
import qs from 'query-string';
export function getParams(key: string) {
return window[`__${key}__`] || qs.parse(location.search)[key];
}virtual:hbuilderx 说明
interface WebviewHtmlOptions {
/**
* `[vite serve]` vite开发服务器的url, 请用 `process.env.VITE_DEV_SERVER_URL`
*/
serverUrl?: string;
/**
* `[vite build]` 插件的 ExtensionContext 实例
*/
context: ExtensionContext;
/**
* `[vite build]` vite build.rollupOptions.input 设置的名称. 默认 `index`.
*/
inputName?: string;
/**
* `[vite build]` 向 head 元素的结束前注入代码 <head>--inject--
*/
injectCode?: string;
}参数
PluginOptions
| 参数名 | 类型 | 默认值 | 说明 |
| ----------- | -------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| recommended | boolean | true | 这个选项是为了提供推荐的默认参数和行为 |
| extension | ExtensionOptions | | hbuilderx extension 可选配置 |
| webview | boolean | string | WebviewOption | __getWebviewHtml__ | 注入 html 代码 |
| devtools | boolean | false | 注入 script 代码用于 react-devtools 或 vue-devtools 调试 |
Notice
recommended 选项用于设置默认配置和行为，几乎可以达到零配置使用，默认为 true 。如果你要自定义配置，请设置它为false。以下默认的前提条件是使用推荐的 项目结构。
输出目录根据
vite的build.outDir参数， 将extension、src分别输出到dist/extension、dist/webview其他待实现的行为
devtools
开发阶段，支持 react 和 vue 的独立开发工具应用，默认不开启。
react: 注入<script src="http://localhost:8097"></script>，支持 react-devtoolsvue: 注入<script src="http://localhost:8098"></script>，支持 vue-devtools
ExtensionOptions
继承自 tsdown 的 Options，添加了一些默认值，方便使用。
| 参数名 | 类型 | 默认值 | 说明 |
| ---------- | -------------------- | --------------------- | ------------------------ |
| entry | string | extension/index.ts | 入口文件 |
| outDir | string | dist-extension/main | 输出文件夹 |
| watchFiles | string/string[] | `` | 开发时监听插件代码的文件 |
WebviewOption
| 参数名 | 类型 | 默认值 | 说明 |
| ---------- | -------- | -------------------------- | ------ |
| refreshKey | string | 开发模式时刷新页面的快捷键 | "F6" |
补充说明
extension未配置相关参数时的默认值，目前HBuilderX 插件不支持sourcemap
| 参数 | 开发模式默认值 | 生产模式默认值 |
| --------- | -------------- | -------------- |
| sourcemap | true | false |
| minify | false | true |
环境变量
hbuilderx extension 使用
development模式
| 变量 | 描述 |
| --------------------- | ------------------- |
| VITE_DEV_SERVER_URL | vite开发服务器的url |
production模式
| 变量 | 描述 |
| ------------------- | ------------------------- |
| VITE_WEBVIEW_DIST | vite webview 页面输出路径 |
Debug
查看官网的如何调试插件？
网页调试
- 可以使用 react-devtools 和 vue-devtools 的独立应用调试
webview vue项目可以使用 vite-plugin-vue-devtools 这个vite插件直接在页面调试- 可以使用
Google Chrome，在地址栏输入chrome://inspect/#devices访问。如果Remote Target不显示，打开HBuilderX调试插件的控制台，查看会看到DevTools listening on ws://127.0.0.1:9500/devtools/browser/e964a967-04da-48f2-8656-9ba933f39e59, 配置Discover network targets对应的localhost:9500即可。
示例
先执行以下命令安装依赖，并生成库文件：
pnpm install
pnpm build打开 examples 目录，有 vue 和 react 示例。
- ext-web-react: 使用 vite + typescript + react 创建
webview插件 - ext-web-vue: 使用 vite + typescript + vue 创建
webview插件
关联
- @tomjs/hbuilderx: 为 HBuilderX 的 插件 开发提供所需的
types、API，方便结合 typescript、tsdown、vite 等现代化工具使用。 - @tomjs/hbuilderx-cli: 为 HBuilderX 开发 插件 提供便利的
cli工具，根据package.json中的contributes配置，为hbuilderx的命令、视图等API提供id提示。