@open-wxa/wxa-runner-core 0.8.2 → 0.10.0

package/dist/index.d.mts

@@ -1,8 +1,34 @@
+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';
 export { F as FrameError, P as PageSnapshot, R as RecordedRequest, W as WxaTestApi } from './testApi-DHuEW5Cl.mjs';
 
+/**
+ * 样式预处理：project.config.json 的 setting.useCompilerPlugins 开启 less / sass 时，
+ * 按开发者工具（summer 编译器的 summer-less、summer-sass 插件）的规则把 .less / .scss / .sass 编译成同名的 .wxss
+ *
+ * - 同一路径有多种源文件时，预处理文件覆盖 .wxss；less 和 sass 都开启时，在 useCompilerPlugins 里排在后面的优先，.scss 优先于 .sass
+ * - 除公共文件本身外，每个 .less 先引用小程序根目录的 app.less（lessSetting.commonUseFilePath），
+ *   每个 .scss / .sass 先 @use global.scss 或 global.sass（sassSetting）；公共文件不存在时跳过
+ * - @import "x.wxss"; 原样保留，由 wcsc 处理
+ * - 编译器优先用项目里安装的 less / sass，没装时用 wxa-runner 自带的（开发者工具也自带编译器）
+ *
+ * wcsc 只接收文件路径、自己从磁盘读文件：和 WxmlMirror 一样，把编译结果和原有的 .wxss 写进临时目录，让 wcsc 在这里编译。
+ */
+
+type StylePluginName = 'less' | 'sass';
+interface StyleSetting {
+    /** 开启的样式插件，按 useCompilerPlugins 里的顺序 */
+    plugins: StylePluginName[];
+    /** ["less", { globalVars }] 写法给出的 less 全局变量 */
+    lessGlobalVars: Record<string, string>;
+    /** 相对小程序根目录 */
+    lessCommonFile: string;
+    sassCommonFile: string;
+    scssCommonFile: string;
+}
+
 /**
  * 小程序项目结构解析
  *
@@ -10,6 +36,7 @@ export { F as FrameError, P as PageSnapshot, R as RecordedRequest, W as WxaTestA
  * - app.json 的全局 usingComponents 展开到每个页面和组件（miniprogram_npm 内除外）
  * - 每个页面/组件 json 都保证有 usingComponents 字段
  */
+
 interface AppJson {
     pages: string[];
     entryPagePath?: string;
@@ -53,6 +80,8 @@ declare class MiniProgram {
     readonly root: string;
     readonly appid: string;
     constructor(projectPath: string);
+    /** project.config.json 里与 less / sass 编译插件有关的设置；每次重新读取，开发中修改了也能生效 */
+    get styleSetting(): StyleSetting;
     readAppJson(): AppJson;
     subPackages(app: AppJson): {
         [key: string]: any;
@@ -98,7 +127,8 @@ declare class MiniProgram {
  *
  * 渲染层（page-frame）:
  *   1. 完整版 $gwx（wcc -cc）与每个页面/组件的 __wxAppCode__ json / wxml（pageTemplates）
- *   2. wcsc 的公共样式运行时 + app.wxss，与每个页面/组件的 __wxAppCode__ wxss（pageStyles）
+ *   2. wcsc 的公共样式运行时 + app.wxss，与每个页面/组件的 __wxAppCode__ wxss（pageStyles）。
+ *      开启 less / sass 编译插件时，先把 .less / .scss / .sass 编译成 .wxss（见 StyleMirror）
  *   两部分在热更新时分别下发
  *   样式和模板里的 env(safe-area-inset-*) 改写成 CSS 变量，见 rewriteSafeAreaInsets
  *
@@ -124,6 +154,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 +168,15 @@ declare class AppBuilder {
     private dirty;
     private wxmlCache;
     private wxssCache;
-    constructor(project: MiniProgram);
+    /** 设置了 wxmlTransform 时才有 */
+    private readonly wxmlMirror;
+    /** 开启了 less / sass 编译插件时才有；插件设置变了就换一个 */
+    private styleMirror;
+    constructor(project: MiniProgram, options?: AppBuilderOptions);
+    /** wxmlTransform 的镜像目录；没有设置转换或还没编译过时为 null */
+    get wxmlMirrorDir(): string | null;
+    /** 删除 wxmlTransform 和样式预处理的镜像目录，开发服务器关闭时调用 */
+    dispose(): void;
     /** 根据变化的文件标记需要重新构建的部分；返回 true 表示需要刷新 */
     invalidate(changedFiles?: string[]): boolean;
     /**
@@ -153,11 +195,47 @@ declare class AppBuilder {
     private compileTemplates;
     /** 与开发者工具一致，项目里的 wxss 全部交给 wcsc：被 @import 的文件（如 uni-app 的 common/main.wxss）也要在列表里 */
     private compileStyles;
+    private currentStyleMirror;
     /** $gwx 加上各页面、组件的 json / wxml 注册；逻辑层用裁剪版 $gwx，渲染层用完整版 */
     private createTemplates;
     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 +257,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 +312,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 +333,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 +350,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 +387,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,8 +1,34 @@
+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';
 export { F as FrameError, P as PageSnapshot, R as RecordedRequest, W as WxaTestApi } from './testApi-BOZSXSnV.js';
 
+/**
+ * 样式预处理：project.config.json 的 setting.useCompilerPlugins 开启 less / sass 时，
+ * 按开发者工具（summer 编译器的 summer-less、summer-sass 插件）的规则把 .less / .scss / .sass 编译成同名的 .wxss
+ *
+ * - 同一路径有多种源文件时，预处理文件覆盖 .wxss；less 和 sass 都开启时，在 useCompilerPlugins 里排在后面的优先，.scss 优先于 .sass
+ * - 除公共文件本身外，每个 .less 先引用小程序根目录的 app.less（lessSetting.commonUseFilePath），
+ *   每个 .scss / .sass 先 @use global.scss 或 global.sass（sassSetting）；公共文件不存在时跳过
+ * - @import "x.wxss"; 原样保留，由 wcsc 处理
+ * - 编译器优先用项目里安装的 less / sass，没装时用 wxa-runner 自带的（开发者工具也自带编译器）
+ *
+ * wcsc 只接收文件路径、自己从磁盘读文件：和 WxmlMirror 一样，把编译结果和原有的 .wxss 写进临时目录，让 wcsc 在这里编译。
+ */
+
+type StylePluginName = 'less' | 'sass';
+interface StyleSetting {
+    /** 开启的样式插件，按 useCompilerPlugins 里的顺序 */
+    plugins: StylePluginName[];
+    /** ["less", { globalVars }] 写法给出的 less 全局变量 */
+    lessGlobalVars: Record<string, string>;
+    /** 相对小程序根目录 */
+    lessCommonFile: string;
+    sassCommonFile: string;
+    scssCommonFile: string;
+}
+
 /**
  * 小程序项目结构解析
  *
@@ -10,6 +36,7 @@ export { F as FrameError, P as PageSnapshot, R as RecordedRequest, W as WxaTestA
  * - app.json 的全局 usingComponents 展开到每个页面和组件（miniprogram_npm 内除外）
  * - 每个页面/组件 json 都保证有 usingComponents 字段
  */
+
 interface AppJson {
     pages: string[];
     entryPagePath?: string;
@@ -53,6 +80,8 @@ declare class MiniProgram {
     readonly root: string;
     readonly appid: string;
     constructor(projectPath: string);
+    /** project.config.json 里与 less / sass 编译插件有关的设置；每次重新读取，开发中修改了也能生效 */
+    get styleSetting(): StyleSetting;
     readAppJson(): AppJson;
     subPackages(app: AppJson): {
         [key: string]: any;
@@ -98,7 +127,8 @@ declare class MiniProgram {
  *
  * 渲染层（page-frame）:
  *   1. 完整版 $gwx（wcc -cc）与每个页面/组件的 __wxAppCode__ json / wxml（pageTemplates）
- *   2. wcsc 的公共样式运行时 + app.wxss，与每个页面/组件的 __wxAppCode__ wxss（pageStyles）
+ *   2. wcsc 的公共样式运行时 + app.wxss，与每个页面/组件的 __wxAppCode__ wxss（pageStyles）。
+ *      开启 less / sass 编译插件时，先把 .less / .scss / .sass 编译成 .wxss（见 StyleMirror）
  *   两部分在热更新时分别下发
  *   样式和模板里的 env(safe-area-inset-*) 改写成 CSS 变量，见 rewriteSafeAreaInsets
  *
@@ -124,6 +154,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 +168,15 @@ declare class AppBuilder {
     private dirty;
     private wxmlCache;
     private wxssCache;
-    constructor(project: MiniProgram);
+    /** 设置了 wxmlTransform 时才有 */
+    private readonly wxmlMirror;
+    /** 开启了 less / sass 编译插件时才有；插件设置变了就换一个 */
+    private styleMirror;
+    constructor(project: MiniProgram, options?: AppBuilderOptions);
+    /** wxmlTransform 的镜像目录；没有设置转换或还没编译过时为 null */
+    get wxmlMirrorDir(): string | null;
+    /** 删除 wxmlTransform 和样式预处理的镜像目录，开发服务器关闭时调用 */
+    dispose(): void;
     /** 根据变化的文件标记需要重新构建的部分；返回 true 表示需要刷新 */
     invalidate(changedFiles?: string[]): boolean;
     /**
@@ -153,11 +195,47 @@ declare class AppBuilder {
     private compileTemplates;
     /** 与开发者工具一致，项目里的 wxss 全部交给 wcsc：被 @import 的文件（如 uni-app 的 common/main.wxss）也要在列表里 */
     private compileStyles;
+    private currentStyleMirror;
     /** $gwx 加上各页面、组件的 json / wxml 注册；逻辑层用裁剪版 $gwx，渲染层用完整版 */
     private createTemplates;
     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 +257,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 +312,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 +333,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 +350,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 +387,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 };