@tomjs/vite-plugin-hbuilderx

v2.1.1

Published

13 days ago

为 HBuilderX 开发插件提供 vite 插件，可以使用 vue/react 开发 webview 的视图等

0High
0Medium
0Low

tomgao365

vite plugin hbuilderx html hmr extension webview

@tomjs/vite-plugin-hbuilderx

node-current (scoped) license

为 HBuilderX 开发插件提供 vite 插件，可以用 vue/react 来开发 WebView视图和 WebView页面的对话框。

在开发模式时，使用 iframe 加载 vue/react 服务，在 iframe 和 parent 之间模拟 hbuilderx.postMessage等方法，用来支持 HMR；生产构建时，将最终生成的 index.html 代码注入到 插件代码 中，减少工作量。

特性

使用 vite 快速构建 插件代码
配置简单，专注业务
支持 webview HMR
支持多页面应用
支持 vue 、react 等其他 vite 支持的框架

安装

# pnpm
pnpm add -D @tomjs/vite-plugin-hbuilderx

# yarn
yarn add -D @tomjs/vite-plugin-hbuilderx

# npm
npm add -D @tomjs/vite-plugin-hbuilderx

使用说明

extension

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 代码 | | strict | boolean | true | 是否启用严格模式，启用后会检测必须在 hbuilderx 的 webview 环境中运行，可通过 VITE_HBUILDERX_STRICT 环境变量覆盖（优先级更高） | | 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-devtools
vue: 注入 <script src="http://localhost:8098"></script>，支持 vue-devtools

ExtensionOptions

继承自 vite 的 UserConfig，添加了一些默认值，方便使用。

| 参数名 | 类型 | 默认值 | 说明 | | ----------- | ------------------------------------------- | --------------------------------------------- | ------------------------------ | | entry | string | extension/index.ts | 入口文件 | | outDir | string | dist-extension | 输出文件夹 | | format | 'cjs'/'esm' | package.json 的 type | 编译格式 | | external | string/RegExp/function | ['hbuilderx'] | 不打进产物中的模块 | | clean | boolean | true | 构建前清空输出目录 | | treeshake | boolean | 生产 true | 是否启用 tree-shaking | | target | string/string[]/false | 见补充说明 | 构建目标 | | sourcemap | boolean/'inline'/'hidden' | 见补充说明 | 是否生成 sourcemap | | minify | boolean/'oxc'/'terser'/'esbuild' | 见补充说明 | 压缩输出 | | watchFiles | string/string[] | | 开发时额外监听插件代码的文件 | | ignoreWatch | `string`\/`RegExp`\/`string[]` | `['.history','.temp','.tmp','.cache','dist']` | 开发时忽略监听的文件 | | onSuccess | `string`\/`function` | | 每次构建成功后执行的命令或回调 |

WebviewOption

| 参数名 | 类型 | 默认值 | 说明 | | ---------- | -------- | ------ | -------------------------- | | refreshKey | string | "F6" | 开发模式时刷新页面的快捷键 |

补充说明

extension 未配置相关参数时的默认值

| 参数 | 开发模式默认值 | 生产模式默认值 | | --------- | ------------------------------------------ | -------------- | | sourcemap | true | false | | minify | false | true | | target | ['es2019','node16']（esm 为 'node20'） | 同开发模式 |

环境变量

插件配置

以下环境变量由插件自身在启动时读取

| 变量 | 描述 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | | VITE_HBUILDERX_STRICT | 是否启用严格模式，优先级高于插件配置的 strict 参数，'true' 启用，'false' 禁用，支持通过 vite .env 文件配置 |

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 提示。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tomjs/vite-plugin-hbuilderx

特性

安装

使用说明

推荐约定

目录结构

extension

vue

react

多页面

多页面应用

单页面传参

参数

PluginOptions

Notice

devtools

ExtensionOptions

WebviewOption

补充说明

环境变量

插件配置

Debug

网页调试

示例

关联