KernelSU 模块 WebUI 开发指南用 webroot JavaScript API 为模块构建交互界面【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSUKernelSU 的模块不仅能执行开机脚本、修改系统文件还能通过webroot目录提供 HTML CSS JavaScript 页面由 KernelSU Manager 以 WebView 方式加载并展示给用户。本文以 website/docs/ja_JP/guide/module-webui.md 为骨架结合仓库内kernelsunpm 库源码与 Manager 端 WebView 实现完整讲解 webroot 目录规范、JS API 的使用方法以及这些能力在 KernelSU 内部是如何被支撑起来的读完即可为模块编写可交互的 WebUI。webroot目录模块页面的存放规范目录结构与入口文件Web 资源文件必须放在模块根目录下的webroot子目录中且其中必须存在一个名为index.html的文件它是模块页面的入口。包含 Web 界面的最简单模块结构如下❯ tree . . |-- module.prop -- webroot -- index.html页面所需的 CSS、JavaScript 等静态资源同样需要放在webroot目录内。该约定在 ksud 源码中被定义为常量userspace/ksud/src/defs.rs第 32 行声明pub const MODULE_WEB_DIR: str webroot;Manager 端在 WebViewHelper.kt 中也是按{modDir}/webroot拼接模块 Web 根目录的其中modDir形如/data/adb/modules/模块ID。权限与 SELinux 上下文的自动配置重要警告::: warning 安装模块时KernelSU 会自动设置webroot目录的权限与 SELinux 上下文。如果你不清楚自己在做什么不要自行修改该目录的权限 :::这一点在 Manager 端有对应的实现佐证WebView 通过 root shell 读取webroot下的文件见下文SuFilePathHandler因此目录权限与 SELinux 上下文必须与 KernelSU 的读取方式匹配。自行设置权限一旦与 KernelSU 的预期不一致轻则页面资源加载失败重则影响模块整体安装结果。Manager 端如何加载 WebUIWebView 与资源加载原理为了理解后面的 JS API先了解 Manager 侧的大致实现。当用户在 KernelSU Manager 中打开某个模块的 WebUI 时会启动 WebUIActivity.kt通过 intent 的id查询参数定位模块activity.intent.data?.getQueryParameter(id)模块不存在或未启用/存在更新时直接提示错误并关闭在 WebViewHelper.kt 中创建 WebView并开启javaScriptEnabled与domStorageEnabled同时关闭allowFileAccess禁止页面直接访问本地文件系统使用WebViewAssetLoader将域名mui.kernelsu.org映射到模块的webroot目录所有页面资源都通过该虚拟域名加载而非file://协议。其中负责读取文件的是 SuFilePathHandler.java它借助 root shell 下的SuFile/SuFileInputStream以 root 权限读取webroot内的文件并根据扩展名推断 MIME 类型。它还会特殊处理两个内置资源internal/insets.css返回由当前窗口 insets刘海屏、状态栏、导航栏区域动态生成的 CSS供页面实现边到边edge-to-edge适配internal/colors.css在 Manager 使用 Material 主题或动态取色Monet时返回主题色 CSS 变量让 WebUI 与 Manager 视觉风格保持一致。此外Manager 还会拦截ksu://icon/包名形式的请求返回对应应用图标PNG供模块在页面中展示应用图标。JavaScript API让页面获得系统能力单纯的展示页与普通网页没有区别关键在于 KernelSU 通过 WebViewInterface.kt 以addJavascriptInterface(webviewInterface, ksu)注入了一组系统 API并以 npm 包的形式封装成 JavaScript 库供模块页面调用。安装KernelSU 官方在 js/package.json 中维护了一个名为kernelsu的 npm 包当前仓库内版本为 3.0.2在模块前端项目中安装yarn add kernelsuAPI 的类型声明与完整说明见仓库内的 js/index.d.ts 和 js/README.md页面中按需import即可。exec执行 shell 命令exec会以root身份启动一个 shell 并执行指定命令命令执行完毕后返回一个 Promise包含errno、stdout、stderr。官方文档示例import { exec } from kernelsu; const { errno, stdout } exec(getprop ro.product.model);更完整的用法来自 js/README.mdimport { exec } from kernelsu; const { errno, stdout, stderr } await exec(ls -l, { cwd: /tmp }); if (errno 0) { // success console.log(stdout); }参数说明参数类型说明commandstring要执行的命令参数以空格分隔options.cwdstring子进程的工作目录options.envObject环境变量键值对从 WebViewInterface.kt 的实现可以看出cwd会被拼装为cd cwd;前缀env中的每个键值对会被拼装为export keyvalue;前缀然后通过 root shell 执行最终以callbackFunc(errno, stdout, stderr)的形式回传给页面中注册的 JS 回调封装细节见 js/index.js。也就是说exec适合一次性获取结果如读取属性、查询配置的场景。spawn流式执行命令与exec返回整体结果不同spawn返回一个ChildProcess实例可以实时监听stdout、stderr数据流和退出事件适合耗时较长或需要持续输出进度的命令。示例import { spawn } from kernelsu; const ls spawn(ls, [-lh, /data]); ls.stdout.on(data, (data) { console.log(stdout: ${data}); }); ls.stderr.on(data, (data) { console.log(stderr: ${data}); }); ls.on(exit, (code) { console.log(child process exited with code ${code}); });参数说明参数类型说明commandstring要执行的命令argsstring[]命令行参数列表省略时默认为空数组options.cwdstring子进程的工作目录options.envObject环境变量键值对ChildProcess支持的事件与属性exit事件进程正常结束时触发回调参数code为退出码进程未能启动时code为 nullerror事件进程无法被启动或无法被终止时触发回调参数为errstdout可读流代表子进程的标准输出stderr可读流代表子进程的标准错误输出。在 Manager 端spawn通过 root shell 的newJob().add(...).to(stdout, stderr).enqueue()异步执行见 WebViewInterface.kt每产生一行输出就通过emit(data, ...)推送回页面进程结束后再触发exit事件若退出码非 0还会额外触发error事件。fullScreen全屏显示请求 WebView 进入或退出全屏模式import { fullScreen } from kernelsu; fullScreen(true);Manager 端实现WebViewInterface.kt会通过WindowInsetsControllerCompat隐藏/显示系统栏适合需要沉浸式展示内容的页面。enableEdgeToEdge边到边沉浸式适配请求 WebView 将内边距设为 0 或按安全区域safe drawing insets适配import { enableEdgeToEdge } from kernelsu; enableEdgeToEdge(true);默认不启用但如果你引用了内置的internal/insets.css资源该能力会被自动启用。启用方式二选一在 CSS 中import https://mui.kernelsu.org/internal/insets.css;在 HTML 中link relstylesheet typetext/css href/internal/insets.css /对应地Manager 在 SuFilePathHandler.java 中拦截internal/insets.css返回按当前窗口 insets 动态生成的 CSS 变量并在 WebViewHelper.kt 中于页面导航时持续注入最新 insets 的 JS保证旋转屏幕或弹出系统栏后样式依然正确。toast弹出提示在页面上方弹出原生 Toast 消息import { toast } from kernelsu; toast(Hello, world!);moduleInfo获取模块信息获取当前模块的信息如模块 ID、版本等示例import { moduleInfo } from kernelsu; // print moduleId in console console.log(moduleInfo());Manager 端实现WebViewInterface.kt会先列出所有模块信息再按当前modDir对应的模块 ID 匹配并返回该模块的完整属性 JSON。listPackages列出已安装应用按类型列出已安装应用的包名返回包名数组import { listPackages } from kernelsu; // list user packages const packages listPackages(user);type取值值含义user仅用户安装的应用system仅系统应用含FLAG_SYSTEMall全部应用从源码看该 API 基于 Manager 的应用列表过滤并排序后返回WebViewInterface.kt。提示当listPackages可用时你还可以通过ksu://icon/{packageName}获取应用图标img.src ksu://icon/ packageName;Manager 会在shouldInterceptRequest中拦截该 scheme 并返回 PNG 图片见 WebViewHelper.kt非常适合做应用选择器之类的界面。getPackagesInfo获取应用详情批量获取一组包名的详细信息返回PackagesInfo对象数组import { getPackagesInfo } from kernelsu; const packages getPackagesInfo([com.android.settings, com.android.shell]);PackagesInfo包含的字段与 js/index.d.ts 中声明的接口一致字段类型说明packageNamestring应用包名versionNamestring应用版本名versionCodenumber应用版本号appLabelstring应用显示名称isSystemboolean是否为系统应用uidnumber应用的 UID对于不存在的包名返回对象会带有error字段Package not found or inaccessible因此调用方需要对返回结果做容错处理。exit退出当前 WebUI关闭当前 WebUI 页面Activityimport { exit } from kernelsu; exit();开发提示数据存储你可以像普通网页一样使用localStorage保存数据但需要注意Manager 应用被卸载后这些数据会丢失。如果需要持久保存请自行将数据写入模块自己的目录例如/data/adb/modules/模块ID/下的某个数据文件。构建工具对于简单的页面推荐使用 parceljs 打包零配置、开箱即用如果你对前端构建工具比较熟悉或有个人偏好也可以自由选择 Vite、webpack 等任何你喜欢的工具。样式适配想让页面与 Manager 整体观感一致可以引用内置的internal/colors.css获取主题色变量在 Manager 使用 Material 主题或动态取色时生效配合internal/insets.css处理全面屏安全区域。调试在 Manager 设置中开启 Web 调试后WebView.setWebContentsDebuggingEnabled见 WebViewHelper.kt可通过 Chrome DevTools 远程调试页面。总结KernelSU 的 Module WebUI 机制可以概括为三层约定webroot/index.html入口、加载Manager 通过 WebViewAssetLoader root shell 读取模块资源、能力kernelsunpm 库封装的exec、spawn、fullScreen、enableEdgeToEdge、toast、moduleInfo、listPackages、getPackagesInfo、exit等系统 API。其中 API 的类型签名、参数与事件行为以仓库内 js/README.md 与 js/index.d.ts 为权威参考Manager 端的具体实现则可在 WebViewInterface.kt、WebViewHelper.kt 与 SuFilePathHandler.java 中进一步研读。掌握了这些你就可以为自己的模块开发出功能完整的图形化设置界面。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
KernelSU 模块 WebUI 开发指南：用 webroot + JavaScript API 为模块构建交互界面
KernelSU 模块 WebUI 开发指南用 webroot JavaScript API 为模块构建交互界面【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSUKernelSU 的模块不仅能执行开机脚本、修改系统文件还能通过webroot目录提供 HTML CSS JavaScript 页面由 KernelSU Manager 以 WebView 方式加载并展示给用户。本文以 website/docs/ja_JP/guide/module-webui.md 为骨架结合仓库内kernelsunpm 库源码与 Manager 端 WebView 实现完整讲解 webroot 目录规范、JS API 的使用方法以及这些能力在 KernelSU 内部是如何被支撑起来的读完即可为模块编写可交互的 WebUI。webroot目录模块页面的存放规范目录结构与入口文件Web 资源文件必须放在模块根目录下的webroot子目录中且其中必须存在一个名为index.html的文件它是模块页面的入口。包含 Web 界面的最简单模块结构如下❯ tree . . |-- module.prop -- webroot -- index.html页面所需的 CSS、JavaScript 等静态资源同样需要放在webroot目录内。该约定在 ksud 源码中被定义为常量userspace/ksud/src/defs.rs第 32 行声明pub const MODULE_WEB_DIR: str webroot;Manager 端在 WebViewHelper.kt 中也是按{modDir}/webroot拼接模块 Web 根目录的其中modDir形如/data/adb/modules/模块ID。权限与 SELinux 上下文的自动配置重要警告::: warning 安装模块时KernelSU 会自动设置webroot目录的权限与 SELinux 上下文。如果你不清楚自己在做什么不要自行修改该目录的权限 :::这一点在 Manager 端有对应的实现佐证WebView 通过 root shell 读取webroot下的文件见下文SuFilePathHandler因此目录权限与 SELinux 上下文必须与 KernelSU 的读取方式匹配。自行设置权限一旦与 KernelSU 的预期不一致轻则页面资源加载失败重则影响模块整体安装结果。Manager 端如何加载 WebUIWebView 与资源加载原理为了理解后面的 JS API先了解 Manager 侧的大致实现。当用户在 KernelSU Manager 中打开某个模块的 WebUI 时会启动 WebUIActivity.kt通过 intent 的id查询参数定位模块activity.intent.data?.getQueryParameter(id)模块不存在或未启用/存在更新时直接提示错误并关闭在 WebViewHelper.kt 中创建 WebView并开启javaScriptEnabled与domStorageEnabled同时关闭allowFileAccess禁止页面直接访问本地文件系统使用WebViewAssetLoader将域名mui.kernelsu.org映射到模块的webroot目录所有页面资源都通过该虚拟域名加载而非file://协议。其中负责读取文件的是 SuFilePathHandler.java它借助 root shell 下的SuFile/SuFileInputStream以 root 权限读取webroot内的文件并根据扩展名推断 MIME 类型。它还会特殊处理两个内置资源internal/insets.css返回由当前窗口 insets刘海屏、状态栏、导航栏区域动态生成的 CSS供页面实现边到边edge-to-edge适配internal/colors.css在 Manager 使用 Material 主题或动态取色Monet时返回主题色 CSS 变量让 WebUI 与 Manager 视觉风格保持一致。此外Manager 还会拦截ksu://icon/包名形式的请求返回对应应用图标PNG供模块在页面中展示应用图标。JavaScript API让页面获得系统能力单纯的展示页与普通网页没有区别关键在于 KernelSU 通过 WebViewInterface.kt 以addJavascriptInterface(webviewInterface, ksu)注入了一组系统 API并以 npm 包的形式封装成 JavaScript 库供模块页面调用。安装KernelSU 官方在 js/package.json 中维护了一个名为kernelsu的 npm 包当前仓库内版本为 3.0.2在模块前端项目中安装yarn add kernelsuAPI 的类型声明与完整说明见仓库内的 js/index.d.ts 和 js/README.md页面中按需import即可。exec执行 shell 命令exec会以root身份启动一个 shell 并执行指定命令命令执行完毕后返回一个 Promise包含errno、stdout、stderr。官方文档示例import { exec } from kernelsu; const { errno, stdout } exec(getprop ro.product.model);更完整的用法来自 js/README.mdimport { exec } from kernelsu; const { errno, stdout, stderr } await exec(ls -l, { cwd: /tmp }); if (errno 0) { // success console.log(stdout); }参数说明参数类型说明commandstring要执行的命令参数以空格分隔options.cwdstring子进程的工作目录options.envObject环境变量键值对从 WebViewInterface.kt 的实现可以看出cwd会被拼装为cd cwd;前缀env中的每个键值对会被拼装为export keyvalue;前缀然后通过 root shell 执行最终以callbackFunc(errno, stdout, stderr)的形式回传给页面中注册的 JS 回调封装细节见 js/index.js。也就是说exec适合一次性获取结果如读取属性、查询配置的场景。spawn流式执行命令与exec返回整体结果不同spawn返回一个ChildProcess实例可以实时监听stdout、stderr数据流和退出事件适合耗时较长或需要持续输出进度的命令。示例import { spawn } from kernelsu; const ls spawn(ls, [-lh, /data]); ls.stdout.on(data, (data) { console.log(stdout: ${data}); }); ls.stderr.on(data, (data) { console.log(stderr: ${data}); }); ls.on(exit, (code) { console.log(child process exited with code ${code}); });参数说明参数类型说明commandstring要执行的命令argsstring[]命令行参数列表省略时默认为空数组options.cwdstring子进程的工作目录options.envObject环境变量键值对ChildProcess支持的事件与属性exit事件进程正常结束时触发回调参数code为退出码进程未能启动时code为 nullerror事件进程无法被启动或无法被终止时触发回调参数为errstdout可读流代表子进程的标准输出stderr可读流代表子进程的标准错误输出。在 Manager 端spawn通过 root shell 的newJob().add(...).to(stdout, stderr).enqueue()异步执行见 WebViewInterface.kt每产生一行输出就通过emit(data, ...)推送回页面进程结束后再触发exit事件若退出码非 0还会额外触发error事件。fullScreen全屏显示请求 WebView 进入或退出全屏模式import { fullScreen } from kernelsu; fullScreen(true);Manager 端实现WebViewInterface.kt会通过WindowInsetsControllerCompat隐藏/显示系统栏适合需要沉浸式展示内容的页面。enableEdgeToEdge边到边沉浸式适配请求 WebView 将内边距设为 0 或按安全区域safe drawing insets适配import { enableEdgeToEdge } from kernelsu; enableEdgeToEdge(true);默认不启用但如果你引用了内置的internal/insets.css资源该能力会被自动启用。启用方式二选一在 CSS 中import https://mui.kernelsu.org/internal/insets.css;在 HTML 中link relstylesheet typetext/css href/internal/insets.css /对应地Manager 在 SuFilePathHandler.java 中拦截internal/insets.css返回按当前窗口 insets 动态生成的 CSS 变量并在 WebViewHelper.kt 中于页面导航时持续注入最新 insets 的 JS保证旋转屏幕或弹出系统栏后样式依然正确。toast弹出提示在页面上方弹出原生 Toast 消息import { toast } from kernelsu; toast(Hello, world!);moduleInfo获取模块信息获取当前模块的信息如模块 ID、版本等示例import { moduleInfo } from kernelsu; // print moduleId in console console.log(moduleInfo());Manager 端实现WebViewInterface.kt会先列出所有模块信息再按当前modDir对应的模块 ID 匹配并返回该模块的完整属性 JSON。listPackages列出已安装应用按类型列出已安装应用的包名返回包名数组import { listPackages } from kernelsu; // list user packages const packages listPackages(user);type取值值含义user仅用户安装的应用system仅系统应用含FLAG_SYSTEMall全部应用从源码看该 API 基于 Manager 的应用列表过滤并排序后返回WebViewInterface.kt。提示当listPackages可用时你还可以通过ksu://icon/{packageName}获取应用图标img.src ksu://icon/ packageName;Manager 会在shouldInterceptRequest中拦截该 scheme 并返回 PNG 图片见 WebViewHelper.kt非常适合做应用选择器之类的界面。getPackagesInfo获取应用详情批量获取一组包名的详细信息返回PackagesInfo对象数组import { getPackagesInfo } from kernelsu; const packages getPackagesInfo([com.android.settings, com.android.shell]);PackagesInfo包含的字段与 js/index.d.ts 中声明的接口一致字段类型说明packageNamestring应用包名versionNamestring应用版本名versionCodenumber应用版本号appLabelstring应用显示名称isSystemboolean是否为系统应用uidnumber应用的 UID对于不存在的包名返回对象会带有error字段Package not found or inaccessible因此调用方需要对返回结果做容错处理。exit退出当前 WebUI关闭当前 WebUI 页面Activityimport { exit } from kernelsu; exit();开发提示数据存储你可以像普通网页一样使用localStorage保存数据但需要注意Manager 应用被卸载后这些数据会丢失。如果需要持久保存请自行将数据写入模块自己的目录例如/data/adb/modules/模块ID/下的某个数据文件。构建工具对于简单的页面推荐使用 parceljs 打包零配置、开箱即用如果你对前端构建工具比较熟悉或有个人偏好也可以自由选择 Vite、webpack 等任何你喜欢的工具。样式适配想让页面与 Manager 整体观感一致可以引用内置的internal/colors.css获取主题色变量在 Manager 使用 Material 主题或动态取色时生效配合internal/insets.css处理全面屏安全区域。调试在 Manager 设置中开启 Web 调试后WebView.setWebContentsDebuggingEnabled见 WebViewHelper.kt可通过 Chrome DevTools 远程调试页面。总结KernelSU 的 Module WebUI 机制可以概括为三层约定webroot/index.html入口、加载Manager 通过 WebViewAssetLoader root shell 读取模块资源、能力kernelsunpm 库封装的exec、spawn、fullScreen、enableEdgeToEdge、toast、moduleInfo、listPackages、getPackagesInfo、exit等系统 API。其中 API 的类型签名、参数与事件行为以仓库内 js/README.md 与 js/index.d.ts 为权威参考Manager 端的具体实现则可在 WebViewInterface.kt、WebViewHelper.kt 与 SuFilePathHandler.java 中进一步研读。掌握了这些你就可以为自己的模块开发出功能完整的图形化设置界面。【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 原理及 curr-domain 配置实战)
