@open-wxa/wxa-runner-core 0.8.1 → 0.9.0

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { IncomingMessage, ServerResponse } from 'http';
 import { ResolvedBaseLib } from '@open-wxa/wxa-runner-extractor';
 import { D as DeviceProfile, F as ForwardConsole } from './setup-Bac8XdhR.mjs';
 export { A as ApiContext, a as ApiHandler, b as ApiResult, c as AppInfo, M as MockConfig, d as MockRequest, e as MockResponse, f as MockValue, N as NetworkConfig, R as RouteHandler, S as SetupApi, g as SetupConfig, h as SetupContext, i as SetupDefinition } from './setup-Bac8XdhR.mjs';
@@ -124,6 +125,10 @@ interface BuildResult {
     components: string[];
     durationMs: number;
 }
+interface AppBuilderOptions {
+    /** wxml 交给 wcc 前的转换，见 DevServerOptions.wxmlTransform */
+    wxmlTransform?: (code: string, file: string) => string;
+}
 declare class AppBuilder {
     readonly project: MiniProgram;
     private version;
@@ -134,7 +139,13 @@ declare class AppBuilder {
     private dirty;
     private wxmlCache;
     private wxssCache;
-    constructor(project: MiniProgram);
+    /** 设置了 wxmlTransform 时才有 */
+    private readonly wxmlMirror;
+    constructor(project: MiniProgram, options?: AppBuilderOptions);
+    /** wxmlTransform 的镜像目录；没有设置转换或还没编译过时为 null */
+    get wxmlMirrorDir(): string | null;
+    /** 删除 wxmlTransform 的镜像目录，开发服务器关闭时调用 */
+    dispose(): void;
     /** 根据变化的文件标记需要重新构建的部分；返回 true 表示需要刷新 */
     invalidate(changedFiles?: string[]): boolean;
     /**
@@ -158,6 +169,41 @@ declare class AppBuilder {
     private createServiceBootstrap;
 }
 
+/**
+ * 开发服务器扩展：检查器这类开发工具把要用的扩展点打包成一个扩展，
+ * 由 DevServer 的 extensions 选项或命令行的 --extension 加载。runner 只认这个约定，不认识具体的工具。
+ *
+ * （「插件」在 runner 里指小程序插件，见 plugins.ts，所以这里叫扩展）
+ */
+
+interface DevServerExtension {
+    /** 出现在报错和启动信息里 */
+    name: string;
+    /** 开发服务器构造时调用一次 */
+    setup(context: ExtensionContext): ExtensionSetup;
+}
+interface ExtensionContext {
+    /** 项目目录（DevServer 的 projectPath，绝对路径） */
+    projectPath: string;
+    /** 小程序代码根目录，已考虑 project.config.json 的 miniprogramRoot */
+    root: string;
+}
+interface ExtensionSetup {
+    webviewScripts?: WebviewScript[];
+    middlewares?: DevServerMiddleware[];
+    wxmlTransform?: (code: string, file: string) => string;
+    /** 扩展自己的页面：启动信息里打印，命令行 --open 时打开 */
+    entry?: {
+        label: string;
+        path: string;
+    };
+}
+interface ExtensionEntry {
+    name: string;
+    label: string;
+    path: string;
+}
+
 /**
  * 开发服务器
  *
@@ -179,9 +225,31 @@ declare class AppBuilder {
  *   /__wxa__/region/<kind>     地区选择器用的行政区划数据（districts / streets），取自本机开发者工具
  *   /__wxa__/api/*             --devtools-login：wx.login 的 code、手机号，服务市场、插件的请求转发，只允许本机访问
  *   /__wxa__/ws                文件变化通知：热更新（hot）或整页刷新（reload）；开启 forwardConsole 时浏览器从这里发来报错
+ *   middlewares / 扩展挂载的路径  排在 runner 自己的路由之前
  *   其余路径                    小程序目录下的静态资源
  */
 
+/** 注入每个渲染层页面的脚本，src 与 content 二选一 */
+type WebviewScript = ({
+    src: string;
+    content?: never;
+} | {
+    content: string;
+    src?: never;
+}) & {
+    /**
+     * 'head'：在基础库（WAWebview.js）之前执行，用于要赶在基础库之前注册事件监听的脚本，执行时还没有 document.body；
+     * 'body'（默认）：在 <body> 开头、页面开始渲染之前执行。不能放在 <body> 末尾：基础库渲染时会换掉 body，
+     *   之后才解析到的脚本落在脱离文档的旧 body 里，不会执行
+     */
+    position?: 'head' | 'body';
+};
+/** 挂在开发服务器上的中间件：按前缀匹配，handler 收到的 req.url 已去掉 path 这段前缀 */
+interface DevServerMiddleware {
+    /** 以 / 开头的字面量路径前缀，如 /__tool__；不能是 /，不能含通配符和参数，也不能落在 runner 保留的前缀下（见 RESERVED_PREFIXES） */
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
+}
 interface DevServerOptions {
     projectPath: string;
     /** 不传时从 3000 起找空闲的端口；指定的端口被占用时启动失败；传 0 使用随机端口 */
@@ -212,6 +280,17 @@ interface DevServerOptions {
      * 默认不转发；命令行默认 'errors'，检测到编程助手时 'all'
      */
     forwardConsole?: ForwardConsole;
+    /** 注入每个渲染层页面（含插件页面、跳转后新建的页面）的脚本，供检查器等开发工具使用 */
+    webviewScripts?: WebviewScript[];
+    /** 挂在开发服务器上的中间件，供开发工具提供自己的页面和接口 */
+    middlewares?: DevServerMiddleware[];
+    /**
+     * wxml 交给 wcc 编译前的转换，file 是相对小程序根目录的路径（如 pages/index/index.wxml）。
+     * 不能改变行数，编译错误和热更新才能对应到源文件；相同输入要返回相同输出。源文件不会被修改
+     */
+    wxmlTransform?: (code: string, file: string) => string;
+    /** 开发服务器扩展：把上面几个扩展点打包在一起的开发工具，按顺序合并在直接给出的选项之后，见 extensions.ts */
+    extensions?: DevServerExtension[];
     logger?: Pick<Console, 'log' | 'warn' | 'error'>;
 }
 declare const DEFAULT_DEVICE: DeviceProfile;
@@ -222,6 +301,8 @@ declare class DevServer {
     readonly baseLib: ResolvedBaseLib;
     /** 生效的 setup 文件绝对路径，没有时为 null */
     readonly setupFile: string | null;
+    /** 扩展提供的页面，按扩展的顺序 */
+    readonly extensionEntries: ExtensionEntry[];
     private readonly setupEnv;
     private readonly device;
     private readonly logger;
@@ -237,6 +318,9 @@ declare class DevServer {
     /** 开启 --devtools-login 时才有 */
     private readonly ticketSource;
     private readonly plugins;
+    /** 选项里直接给出的扩展点与各个扩展合并后的结果 */
+    private readonly webviewScripts;
+    private readonly middlewares;
     constructor(options: DevServerOptions);
     /** 本机访问的地址 */
     get url(): string;
@@ -271,4 +355,4 @@ interface WxConfigInput {
 }
 declare function createWxConfig(input: WxConfigInput): Record<string, any>;
 
-export { AppBuilder, type AppJson, type BuildResult, DEFAULT_DEVICE, DevServer, type DevServerOptions, DeviceProfile, ForwardConsole, MiniProgram, type UnitJson, createWxConfig };
+export { AppBuilder, type AppBuilderOptions, type AppJson, type BuildResult, DEFAULT_DEVICE, DevServer, type DevServerExtension, type DevServerMiddleware, type DevServerOptions, DeviceProfile, type ExtensionContext, type ExtensionEntry, type ExtensionSetup, ForwardConsole, MiniProgram, type UnitJson, type WebviewScript, createWxConfig };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { IncomingMessage, ServerResponse } from 'http';
 import { ResolvedBaseLib } from '@open-wxa/wxa-runner-extractor';
 import { D as DeviceProfile, F as ForwardConsole } from './setup-Bac8XdhR.js';
 export { A as ApiContext, a as ApiHandler, b as ApiResult, c as AppInfo, M as MockConfig, d as MockRequest, e as MockResponse, f as MockValue, N as NetworkConfig, R as RouteHandler, S as SetupApi, g as SetupConfig, h as SetupContext, i as SetupDefinition } from './setup-Bac8XdhR.js';
@@ -124,6 +125,10 @@ interface BuildResult {
     components: string[];
     durationMs: number;
 }
+interface AppBuilderOptions {
+    /** wxml 交给 wcc 前的转换，见 DevServerOptions.wxmlTransform */
+    wxmlTransform?: (code: string, file: string) => string;
+}
 declare class AppBuilder {
     readonly project: MiniProgram;
     private version;
@@ -134,7 +139,13 @@ declare class AppBuilder {
     private dirty;
     private wxmlCache;
     private wxssCache;
-    constructor(project: MiniProgram);
+    /** 设置了 wxmlTransform 时才有 */
+    private readonly wxmlMirror;
+    constructor(project: MiniProgram, options?: AppBuilderOptions);
+    /** wxmlTransform 的镜像目录；没有设置转换或还没编译过时为 null */
+    get wxmlMirrorDir(): string | null;
+    /** 删除 wxmlTransform 的镜像目录，开发服务器关闭时调用 */
+    dispose(): void;
     /** 根据变化的文件标记需要重新构建的部分；返回 true 表示需要刷新 */
     invalidate(changedFiles?: string[]): boolean;
     /**
@@ -158,6 +169,41 @@ declare class AppBuilder {
     private createServiceBootstrap;
 }
 
+/**
+ * 开发服务器扩展：检查器这类开发工具把要用的扩展点打包成一个扩展，
+ * 由 DevServer 的 extensions 选项或命令行的 --extension 加载。runner 只认这个约定，不认识具体的工具。
+ *
+ * （「插件」在 runner 里指小程序插件，见 plugins.ts，所以这里叫扩展）
+ */
+
+interface DevServerExtension {
+    /** 出现在报错和启动信息里 */
+    name: string;
+    /** 开发服务器构造时调用一次 */
+    setup(context: ExtensionContext): ExtensionSetup;
+}
+interface ExtensionContext {
+    /** 项目目录（DevServer 的 projectPath，绝对路径） */
+    projectPath: string;
+    /** 小程序代码根目录，已考虑 project.config.json 的 miniprogramRoot */
+    root: string;
+}
+interface ExtensionSetup {
+    webviewScripts?: WebviewScript[];
+    middlewares?: DevServerMiddleware[];
+    wxmlTransform?: (code: string, file: string) => string;
+    /** 扩展自己的页面：启动信息里打印，命令行 --open 时打开 */
+    entry?: {
+        label: string;
+        path: string;
+    };
+}
+interface ExtensionEntry {
+    name: string;
+    label: string;
+    path: string;
+}
+
 /**
  * 开发服务器
  *
@@ -179,9 +225,31 @@ declare class AppBuilder {
  *   /__wxa__/region/<kind>     地区选择器用的行政区划数据（districts / streets），取自本机开发者工具
  *   /__wxa__/api/*             --devtools-login：wx.login 的 code、手机号，服务市场、插件的请求转发，只允许本机访问
  *   /__wxa__/ws                文件变化通知：热更新（hot）或整页刷新（reload）；开启 forwardConsole 时浏览器从这里发来报错
+ *   middlewares / 扩展挂载的路径  排在 runner 自己的路由之前
  *   其余路径                    小程序目录下的静态资源
  */
 
+/** 注入每个渲染层页面的脚本，src 与 content 二选一 */
+type WebviewScript = ({
+    src: string;
+    content?: never;
+} | {
+    content: string;
+    src?: never;
+}) & {
+    /**
+     * 'head'：在基础库（WAWebview.js）之前执行，用于要赶在基础库之前注册事件监听的脚本，执行时还没有 document.body；
+     * 'body'（默认）：在 <body> 开头、页面开始渲染之前执行。不能放在 <body> 末尾：基础库渲染时会换掉 body，
+     *   之后才解析到的脚本落在脱离文档的旧 body 里，不会执行
+     */
+    position?: 'head' | 'body';
+};
+/** 挂在开发服务器上的中间件：按前缀匹配，handler 收到的 req.url 已去掉 path 这段前缀 */
+interface DevServerMiddleware {
+    /** 以 / 开头的字面量路径前缀，如 /__tool__；不能是 /，不能含通配符和参数，也不能落在 runner 保留的前缀下（见 RESERVED_PREFIXES） */
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
+}
 interface DevServerOptions {
     projectPath: string;
     /** 不传时从 3000 起找空闲的端口；指定的端口被占用时启动失败；传 0 使用随机端口 */
@@ -212,6 +280,17 @@ interface DevServerOptions {
      * 默认不转发；命令行默认 'errors'，检测到编程助手时 'all'
      */
     forwardConsole?: ForwardConsole;
+    /** 注入每个渲染层页面（含插件页面、跳转后新建的页面）的脚本，供检查器等开发工具使用 */
+    webviewScripts?: WebviewScript[];
+    /** 挂在开发服务器上的中间件，供开发工具提供自己的页面和接口 */
+    middlewares?: DevServerMiddleware[];
+    /**
+     * wxml 交给 wcc 编译前的转换，file 是相对小程序根目录的路径（如 pages/index/index.wxml）。
+     * 不能改变行数，编译错误和热更新才能对应到源文件；相同输入要返回相同输出。源文件不会被修改
+     */
+    wxmlTransform?: (code: string, file: string) => string;
+    /** 开发服务器扩展：把上面几个扩展点打包在一起的开发工具，按顺序合并在直接给出的选项之后，见 extensions.ts */
+    extensions?: DevServerExtension[];
     logger?: Pick<Console, 'log' | 'warn' | 'error'>;
 }
 declare const DEFAULT_DEVICE: DeviceProfile;
@@ -222,6 +301,8 @@ declare class DevServer {
     readonly baseLib: ResolvedBaseLib;
     /** 生效的 setup 文件绝对路径，没有时为 null */
     readonly setupFile: string | null;
+    /** 扩展提供的页面，按扩展的顺序 */
+    readonly extensionEntries: ExtensionEntry[];
     private readonly setupEnv;
     private readonly device;
     private readonly logger;
@@ -237,6 +318,9 @@ declare class DevServer {
     /** 开启 --devtools-login 时才有 */
     private readonly ticketSource;
     private readonly plugins;
+    /** 选项里直接给出的扩展点与各个扩展合并后的结果 */
+    private readonly webviewScripts;
+    private readonly middlewares;
     constructor(options: DevServerOptions);
     /** 本机访问的地址 */
     get url(): string;
@@ -271,4 +355,4 @@ interface WxConfigInput {
 }
 declare function createWxConfig(input: WxConfigInput): Record<string, any>;
 
-export { AppBuilder, type AppJson, type BuildResult, DEFAULT_DEVICE, DevServer, type DevServerOptions, DeviceProfile, ForwardConsole, MiniProgram, type UnitJson, createWxConfig };
+export { AppBuilder, type AppBuilderOptions, type AppJson, type BuildResult, DEFAULT_DEVICE, DevServer, type DevServerExtension, type DevServerMiddleware, type DevServerOptions, DeviceProfile, type ExtensionContext, type ExtensionEntry, type ExtensionSetup, ForwardConsole, MiniProgram, type UnitJson, type WebviewScript, createWxConfig };