From 9437dac07668b856d94e3d42030a9b0a3462ad64 Mon Sep 17 00:00:00 2001 From: wangcuijuan Date: Wed, 17 Jun 2026 10:17:47 +0800 Subject: [PATCH 1/4] =?UTF-8?q?=E8=A1=A5=E5=85=85mpx2web=20=E5=85=88?= =?UTF-8?q?=E6=8F=90=E4=BA=A4=E4=B8=80=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/mpx2web/SKILL.md | 269 +++++++++ .../mpx2web/references/conditional-compile.md | 159 ++++++ .../references/single-file-component.md | 123 +++++ .../mpx2web/references/web-api-reference.md | 58 ++ .../mpx2web/references/web-hybrid-dev.md | 35 ++ .../mpx2web/references/web-json-reference.md | 34 ++ .../mpx2web/references/web-routing-deploy.md | 46 ++ .../references/web-script-reference.md | 59 ++ .../mpx2web/references/web-style-practice.md | 36 ++ .../mpx2web/references/web-style-reference.md | 40 ++ .../references/web-template-reference.md | 63 +++ .../mpx2web/scripts/compile-validate.js | 515 ++++++++++++++++++ .../scripts/strip-using-components-loader.js | 54 ++ 13 files changed, 1491 insertions(+) create mode 100644 .agents/skills/mpx2web/SKILL.md create mode 100644 .agents/skills/mpx2web/references/conditional-compile.md create mode 100644 .agents/skills/mpx2web/references/single-file-component.md create mode 100644 .agents/skills/mpx2web/references/web-api-reference.md create mode 100644 .agents/skills/mpx2web/references/web-hybrid-dev.md create mode 100644 .agents/skills/mpx2web/references/web-json-reference.md create mode 100644 .agents/skills/mpx2web/references/web-routing-deploy.md create mode 100644 .agents/skills/mpx2web/references/web-script-reference.md create mode 100644 .agents/skills/mpx2web/references/web-style-practice.md create mode 100644 .agents/skills/mpx2web/references/web-style-reference.md create mode 100644 .agents/skills/mpx2web/references/web-template-reference.md create mode 100644 .agents/skills/mpx2web/scripts/compile-validate.js create mode 100644 .agents/skills/mpx2web/scripts/strip-using-components-loader.js diff --git a/.agents/skills/mpx2web/SKILL.md b/.agents/skills/mpx2web/SKILL.md new file mode 100644 index 0000000000..f6555fd3cc --- /dev/null +++ b/.agents/skills/mpx2web/SKILL.md @@ -0,0 +1,269 @@ +--- +name: mpx2web +description: Mpx 跨端输出 Web（简称 Mpx2Web）的开发适配指南，覆盖模板、脚本、样式、JSON 配置四大维度，以及路由部署、SEO/SSR、H5 生态混合开发等 Web 专属能力。当用户要求对已有 Mpx 组件进行 Web 跨端适配改造、创建符合 Web 跨端兼容规范的 Mpx 组件、排查 Mpx2Web 编译报错或查询某项能力（模板指令、基础组件、样式属性、生命周期、环境 API、JSON 字段、路由/部署等）在 Web 平台的支持情况时强制调用。当用户问题不涉及 Mpx 跨端输出 Web 时不应调用，如小程序原生开发问题、纯前端 Vue 开发问题、RN 端适配问题等。 +metadata: + version: "1.0.0" + author: wangcuijuan +--- + +# Mpx 跨端输出 Web 开发与适配指南 + +## 背景介绍 + +Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展支持的跨端开发框架，支持将同一套代码输出到小程序（微信、支付宝、百度等）、Web 和 React Native 平台。其中 **Web（`mode === 'web'`）是 Mpx 起步最早、能力最完整、与小程序原平台语义最接近的输出端**：编译产物基于 **Vue 2.7**，经 webpack / vue-loader 生成真实 DOM 应用，绝大多数小程序模板、样式、逻辑写法可直接等效运行。 + +正因为 Web 兼容度高，本 SKILL 的核心**不是**罗列"Web 不支持什么"的长清单，而是聚焦三类真正需要处理的问题： + +1. **小程序专属能力在 Web 的降级 / 缺失**（如 `onShareAppMessage`、`open-data`、部分依赖原生硬件的 API/组件）。 +2. **Web 独有且必须正确配置的能力**（路由模式与部署路径、`rpx` 单位换算、SEO/SSR、移动端适配）。 +3. **跨平台兼容约束**：产物须在原平台与 Web 平台均能正常运行，避免引入只在 Web 生效、却破坏小程序原平台的写法。 + +本 SKILL 面向以下两类任务： + +1. **任务一**：对已有的 Mpx 组件进行 Web 跨端适配改造（已基于小程序规范编写、需补齐 Web 兼容性）。 +2. **任务二**：从零创建一个符合 Web 跨端兼容规范的 Mpx 组件。 + +## 知识库索引 + +| 知识库 | 说明 | +| --- | --- | +| [Mpx 单文件组件](./references/single-file-component.md) | Mpx 单文件组件的基本结构与语法，开发任意 `.mpx` 文件前读取 | +| [条件编译](./references/conditional-compile.md) | 模板、脚本、样式、JSON 等不同部分的条件编译语法，遇到无法跨端等效实现需分平台处理时读取 | +| [跨端输出 Web 模板能力参考](./references/web-template-reference.md) | 模板部分跨端能力详情：数据绑定、模板指令、事件、Slot、WXML 模板、i18n、无障碍访问、基础组件清单及其属性/事件在 Web 的支持与降级情况 | +| [跨端输出 Web 脚本能力参考](./references/web-script-reference.md) | 脚本部分跨端能力详情：构造选项、生命周期、实例方法/属性、组合式 API、运行时导出、状态管理 | +| [跨端输出 Web 样式能力参考](./references/web-style-reference.md) | 样式部分跨端能力详情：选择器、单位（含 `rpx` 换算）、颜色、媒体查询、动画、背景图与逐项样式属性支持情况 | +| [跨端输出 Web 样式开发最佳实践](./references/web-style-practice.md) | 移动端适配、`rpx`/`px` 单位策略、1px 边框、安全区域等 Web 端样式实践 | +| [跨端输出 Web 环境 API 参考](./references/web-api-reference.md) | `@mpxjs/api-proxy` 提供的环境 API 在 Web（H5 实现）的支持情况，涉及网络、存储、界面、设备、媒体、位置等及其浏览器限制 | +| [跨端输出 Web JSON 配置参考](./references/web-json-reference.md) | 应用、页面、组件三层 JSON 配置在 Web 平台的支持范围与差异（含 `tabBar`、分包、路由相关字段） | +| [Web 路由、部署与 SEO/SSR](./references/web-routing-deploy.md) | Web 专属：路由模式（history/hash）、`publicPath` 部署路径、页面标题、SEO 与服务端渲染（SSR）注意事项 | +| [Mpx 与 H5 生态混合开发](./references/web-hybrid-dev.md) | 在 `.mpx` 内使用原生 DOM、第三方 H5 SDK / Vue 组件的方式与跨端隔离方案 | + +### 知识库使用建议 + +参考文档体量较大，**不要一次性预读全部参考**，按需取用即可： + +1. **入口只读本 SKILL.md**：完整读完本文档（含下方通用约束与任务流程）足以覆盖大多数常见场景的判断；不要在动笔前预读 references 目录。 +2. **触发式读取**：只在任务流程或通用约束中**明确指向**某份参考时读取，且仅读取与当前问题相关的小节（参考文档均含目录与章节锚点，使用 grep / 锚点跳读，不要整文件 Read）。 +3. **典型任务的最小阅读集**（仅当本 SKILL.md 已无法判断时再补充）： + - 已有组件 Web 跨端适配改造：Web 兼容度高，多数情况无需改动模板/样式主体；识别问题维度后再读对应能力参考的相关小节（如 API 降级查 `web-api-reference.md`、单位/适配查 `web-style-practice.md`）。 + - 新建 Web 跨端兼容组件：先按本 SKILL.md 的通用约束起手，遇到能力存疑（某 API 是否存在、某组件是否降级）时再点查对应参考。 + - 排查特定编译报错：直接定位到报错维度的能力参考相关小节。 +4. **何时读取 `single-file-component.md`**：仅当不熟悉 Mpx SFC 基本结构时读取；已熟悉 SFC 写法可跳过。 + +## 通用约束与适配原则 + +无论是适配改造还是新建组件，跨端兼容均需严格遵循以下通用约束。**Web 输出与小程序原平台语义高度一致，几乎不需要为兼容而改写小程序原有写法，约束主要集中在"小程序专属能力在 Web 的降级"与"Web 专属能力的正确配置"两侧。** + +### 跨平台兼容约束 + +产物代码须在原平台（小程序）与 Web 平台均能正常运行。引入「Web 支持但小程序不支持」的写法（如直接使用 DOM API、`window` 对象、第三方 H5 SDK 等）时，**不要替换小程序已有写法**，而应： + +- 用条件编译将该 Web 写法限定在 Web 平台输出（模板属性后缀 `@web`、样式与脚本 `@mpx-if` 包裹等）； +- 同步用条件编译保留小程序原有写法，避免改造引入小程序行为退化。 + +该原则贯穿模板 / 脚本 / 样式 / JSON 四个维度。 + +### 模板（template）约束 + +1. **基础组件优先**：使用 [模板能力参考 · 基础组件](./references/web-template-reference.md#基础组件) 中标注 Web 支持的基础组件与其支持属性/事件。多数小程序基础组件在 Web 有等效实现，但少数**依赖原生硬件或小程序开放能力**的组件（如 `camera` / `live-player` / `live-pusher` / `open-data` / `official-account` / `ad` 等）在 Web 不支持或仅部分降级，需查参考确认；`web-view` 在 Web 渲染为 `iframe`，行为与小程序有差异。 +2. **页面滚动**：Web 页面默认可滚动，`onPageScroll` / `onReachBottom` / `onPullDownRefresh` 等页面滚动相关生命周期在 Web **支持**（由 Mpx Web 运行时实现，行为与小程序对齐）；具体差异见 [脚本能力参考 · 生命周期](./references/web-script-reference.md#生命周期)。 +3. **模板内方法调用**：跨端通用约束下，模板 Mustache 表达式应避免普通方法调用，需通过 `computed` / `wxs` 实现（i18n 翻译函数除外），以保持与其他平台一致。 +4. **i18n**：组合式 API 中 `useI18n()` 解构出的翻译函数须以原名 `t` / `tc` / `te` / `tm` 暴露至模板的 `return`，禁止重命名。 +5. **事件传参**：传递自定义参数给事件处理器时，优先使用事件内联传参语法（如 `bindtap="handleTap('param')"`），而不是通过 `data-` dataset 属性传参，以保持跨端一致。 +6. **对象字面量 key 禁止加引号**：在模板插值（`wx:style` / `wx:class` 等）中使用对象字面量时，key **不允许**使用单引号或双引号包裹，否则会导致微信小程序模板编译报错。应使用 camelCase 形式的无引号 key。 + - **Bad Example**: `wx:style="{{{'background-image': '...'}}}"` + - **Good Example**: `wx:style="{{{backgroundImage: '...'}}}"` +7. **文字使用 `text` 包裹**：保持与小程序及其他端一致，文字内容优先使用 `text` 组件显式包裹，避免依赖平台隐式行为。 + +### 脚本（script）约束 + +1. **生命周期 / 构造选项**：仅使用 [脚本能力参考](./references/web-script-reference.md) 中标注 Web 支持的生命周期与构造选项；小程序专属的分享与 tab 相关生命周期（`onShareAppMessage` / `onShareTimeline` / `onAddToFavorites` / `onTabItemTap` 等）在 Web 无等效，须用条件编译隔离或确认可降级。 +2. **环境 API**：通过 `@mpxjs/api-proxy` 提供的统一 `mpx.xxx` API 调用环境能力，避免直接使用 `wx.xxx` / `my.xxx`；Web 端由 api-proxy 映射为 H5 实现，部分依赖原生硬件的能力（蓝牙、NFC、部分传感器等）受浏览器限制不可用或需降级，具体支持范围见 [环境 API 参考](./references/web-api-reference.md)；如用户通过 `custom` 配置扩充拓展了环境 API 能力，以用户说明为准。 +3. **路由跳转统一使用 Mpx 导航 API**：Mpx 自带一套与微信小程序对齐的跨端路由逻辑，页面跳转统一使用 `mpx.navigateTo` / `mpx.redirectTo` / `mpx.switchTab` / `mpx.navigateBack` / `mpx.reLaunch`（编译到 Web 时由 Mpx 内部映射到 Web 路由）。**禁止在 `.mpx` 中直接引入 `vue-router` 或手写 Web 路由跳转**，以免破坏跨端一致性。详见 [Web 路由、部署与 SEO/SSR](./references/web-routing-deploy.md)。 +4. **直接使用浏览器能力须隔离**：直接访问 `window` / `document` / DOM、第三方 H5 SDK 等仅 Web 可用的能力时，必须用条件编译限定在 Web 平台，并保留小程序侧等效逻辑，详见 [H5 生态混合开发](./references/web-hybrid-dev.md)。 +4. **selector API**：`selectComponent` / `createSelectorQuery` 等在 Web 的 selector 语法与微信小程序保持一致（ID、class、子元素 `>`、后代、跨组件后代 `>>>`、并集 `,` 等），直接基于真实 DOM 查询即可。详见 [脚本能力参考 · 实例方法与属性](./references/web-script-reference.md#页面--组件实例方法与属性)。 + +### 样式（style）约束 + +> **样式兼容度**：Web 基于真实 CSS 引擎，小程序中使用的复合选择器、伪类、伪元素、`grid` / `float`、媒体查询等 CSS 写法在 Web 均可直接使用，**无需为兼容而改写**。Web 样式约束主要集中在 `rpx` 单位换算与移动端适配。 + +1. **样式能力判断口径**：样式属性支持情况以 [样式能力参考](./references/web-style-reference.md) 为准。绝大多数 CSS 属性与选择器在 Web 可直接使用，无需改写。 +2. **`rpx` 单位换算**：Web 端 `rpx` 会换算为视口单位 `vw`（以 750rpx 对应 100vw 为基准），详见 [样式开发最佳实践 · 单位与适配](./references/web-style-practice.md#单位与适配)。 +3. **优先使用模板指令进行动态样式绑定**：使用 `wx:class` / `wx:style` 指令，避免在 `class` / `style` 属性内拼接 `{{}}` 插值表达式（跨端通用约束）。 + - **Bad Example**: `` + - **Good Example**: `` +4. **保留单位注释**：保留原始样式中的 `/*use rpx*/` 与 `/*use px*/` 注释，编译期会据此批量切换样式单位。 +5. **Web 专属写法须隔离**：若使用仅 Web 生效、小程序不支持的 CSS（如 `position: fixed` 在小程序的差异、`::-webkit-scrollbar` 伪元素、`vh`/`vw` 视口单位等），按需用样式条件编译隔离，并保留小程序侧等效写法，避免破坏原平台。常见兼容方案见 [样式开发最佳实践](./references/web-style-practice.md)。 + +### JSON 配置约束 + +1. **支持范围**：应用、页面、组件三级 JSON 配置在 Web 平台的字段支持详情见 [JSON 配置参考](./references/web-json-reference.md)。小程序中常用的 `tabBar` 在 Web **支持**（Mpx 渲染等效 tabbar）；但部分小程序专属字段（如 `workers`、`plugins`、云开发相关）在 Web 不支持，须通过条件编译隔离。 +2. **路由与部署相关字段**：`pages`、`subPackages`、页面 `navigationBar*` 等在 Web 有对应行为，但与路由模式 / 部署路径耦合，详见 [Web 路由、部署与 SEO/SSR](./references/web-routing-deploy.md)。 +3. **动态生成配置**：当需要分平台或分环境定义 JSON 配置时，使用 ` +``` diff --git a/.agents/skills/mpx2web/references/single-file-component.md b/.agents/skills/mpx2web/references/single-file-component.md new file mode 100644 index 0000000000..3396f3ac48 --- /dev/null +++ b/.agents/skills/mpx2web/references/single-file-component.md @@ -0,0 +1,123 @@ +# 单文件开发 {#single-file-development} + +小程序规范中每个页面和组件都是由四个文件描述组成的，wxml/js/wxss/json，分别描述了组件/页面的视图模板，执行逻辑，样式和配置，由于这四个部分彼此之间存在相关性，比如模板中的组件需要在 json 中注册，数据需要在 js 中定义，这种离散的文件结构在实际开发的时候体验并不理想；受 Vue 单文件开发的启发，Mpx 也提供了类似的单文件开发模式，拓展名为.mpx。 + +Mpx 单文件组件（SFC）格式 `.mpx` 是一种将组件的视图模板、组件逻辑、组件样式和组件配置封装在一个文件中的开发模式。每个 `.mpx` 文件都包含了以下几个部分： + +- template 区块：定义组件的视图结构，基于微信小程序的基础模板语法，结合 Mpx 拓展支持的类 Vue 模版指令，如 `wx:style`、`wx:class`、`wx:model`、`wx:ref` 等，对应微信小程序的 `.wxml` 部分 +- script 区块：定义组件的逻辑，基于微信小程序的基础组件语法，结合 Mpx 拓展支持的类 Vue 组件语法，如 数据响应、组合式 API 等，对应微信小程序的 `.js` 部分 +- style 区块：定义组件的样式，支持 CSS 预处理（如 Stylus、Sass、Less 等），跨端输出 RN 时存在较强约束限制，对应微信小程序的 `.wxss` 部分 +- json 区块：定义组件的配置，支持微信小程序的组件配置选项，对应微信小程序的 `.json` 部分 + +示例如下： + +```html + + + + + + + +``` diff --git a/.agents/skills/mpx2web/references/web-api-reference.md b/.agents/skills/mpx2web/references/web-api-reference.md new file mode 100644 index 0000000000..348ec1196b --- /dev/null +++ b/.agents/skills/mpx2web/references/web-api-reference.md @@ -0,0 +1,58 @@ +# 跨端输出 Web 环境 API 参考 + +> **填充说明（待补充，删除本块后正式发布）**：本文件为骨架。`@mpxjs/api-proxy` 在 Web 端将 `mpx.xxx` 映射为 H5 实现。填充时**重点标注受浏览器限制不可用或需降级**的 API（多为设备硬件类）。可参考 `mpx2rn/references/rn-api-reference.md` 的分类与表格形态，但支持结论须按 Web（H5）实际重写。 + +## 使用说明 + +通过 `@mpxjs/api-proxy` 提供的统一 `mpx.xxx` 调用环境能力，避免直接使用 `wx.xxx` / `my.xxx`。Web 端由 api-proxy 映射为浏览器（H5）实现。如用户通过 `custom` 配置扩充了 API 能力，以用户说明为准。 + +## 目录 + +- [基础](#基础) +- [路由](#路由) +- [界面](#界面) +- [网络](#网络) +- [数据缓存](#数据缓存) +- [媒体](#媒体) +- [位置](#位置) +- [设备](#设备) + +--- + +## 基础 + +TODO：`getSystemInfo` / `getLaunchOptions` 等在 Web 的实现与字段差异。 + +## 路由 + +TODO：`navigateTo` / `redirectTo` / `switchTab` / `navigateBack` / `reLaunch` 在 Web（基于路由）的映射与差异，参见 [Web 路由、部署与 SEO/SSR](./web-routing-deploy.md)。 + +## 界面 + +TODO：`showToast` / `showModal` / `showLoading` / `showActionSheet` / `setNavigationBarTitle` / `pageScrollTo` 等在 Web 的支持。 + +## 网络 + +TODO：`request` / `uploadFile` / `downloadFile` / `connectSocket` 在 Web 的支持（跨域 / CORS 注意事项）。 + +## 数据缓存 + +TODO：`setStorage` / `getStorage`（映射到 localStorage）同步异步在 Web 的支持与容量限制。 + +## 媒体 + +TODO：`chooseImage` / `previewImage` / `chooseMedia` / 音视频 API 在 Web 的支持与降级。 + +## 位置 + +TODO：`getLocation` / `chooseLocation` 在 Web（浏览器 Geolocation，需 HTTPS 与授权）。 + +## 设备 + +> **本节为重点**：标注受浏览器限制的硬件能力。 + +TODO： +- 网络状态 `getNetworkType` —— TODO +- 剪贴板 `setClipboardData` —— TODO +- 振动 `vibrateShort` —— TODO +- **蓝牙 / NFC / 部分传感器 / 扫码等**：Web 多数不支持或需特定降级 —— 重点标注 diff --git a/.agents/skills/mpx2web/references/web-hybrid-dev.md b/.agents/skills/mpx2web/references/web-hybrid-dev.md new file mode 100644 index 0000000000..3fea0e3f6e --- /dev/null +++ b/.agents/skills/mpx2web/references/web-hybrid-dev.md @@ -0,0 +1,35 @@ +# Mpx 与 H5 生态混合开发 + +> **填充说明（待补充，删除本块后正式发布）**：本文件对应 RN skill 的 `rn-hybrid-dev.md`，但内容是 **Web 侧**：在 `.mpx` 内使用原生 DOM、第三方 H5 SDK / Vue 生态库，及跨端隔离方案。 + +## 目录 + +- [使用原生 DOM 能力](#使用原生-dom-能力) +- [引入第三方 H5 SDK](#引入第三方-h5-sdk) +- [使用 Vue 生态组件 / 指令](#使用-vue-生态组件--指令) +- [跨端兼容隔离](#跨端兼容隔离) + +--- + +## 使用原生 DOM 能力 + +TODO： +- 在脚本中访问 `window` / `document` / DOM 节点的方式（须用条件编译限定 Web 平台）。 +- 通过 `wx:ref` / selector 获取节点后操作 DOM 的建议。 + +## 引入第三方 H5 SDK + +TODO： +- 引入第三方 H5 库（如埋点、支付、地图 SDK）的方式。 +- 仅 Web 依赖的隔离，避免小程序构建解析。 + +## 使用 Vue 生态组件 / 指令 + +TODO： +- Web 输出基于 Vue 2.7，能否/如何在 `.mpx` 中复用 Vue 组件与指令。 +- 与 Mpx 组件机制的边界与注意事项。 + +## 跨端兼容隔离 + +TODO： +- Web 与小程序差异通常很小，对差异片段使用 `@mode` / `@_mode` / `mpxTagName@mode` / 脚本 `__mpx_mode__` 隔离少量 Web 专属节点或逻辑即可。 diff --git a/.agents/skills/mpx2web/references/web-json-reference.md b/.agents/skills/mpx2web/references/web-json-reference.md new file mode 100644 index 0000000000..d3a08efbc4 --- /dev/null +++ b/.agents/skills/mpx2web/references/web-json-reference.md @@ -0,0 +1,34 @@ +# 跨端输出 Web JSON 配置参考 + +> **填充说明（待补充，删除本块后正式发布）**：本文件为骨架。填充时**重点标注小程序专属、Web 不支持的字段**（如 `workers` / `plugins` / 云开发相关），以及与路由部署耦合的字段。注意 `tabBar` 在 Web **支持**（Mpx 渲染等效 tabbar）。 + +## 目录 + +- [应用配置](#应用配置) +- [页面配置](#页面配置) +- [组件配置](#组件配置) +- [分包与分包异步化](#分包与分包异步化) + +--- + +## 应用配置 + +TODO 表格（字段 | Web 支持 | 说明）： +- `pages` —— ✅（与路由耦合，详见 [Web 路由、部署与 SEO/SSR](./web-routing-deploy.md)） +- `window`（`navigationBarTitleText` 等）—— TODO +- `tabBar` —— ✅ **Web 支持（Mpx 渲染等效 tabbar）** +- `subPackages` / `preloadRule` —— TODO（Web 打包行为） +- `networkTimeout` / `debug` —— TODO +- `workers` / `plugins` / 云开发 / `useExtendedLib` —— **小程序专属，Web 不支持，需隔离** + +## 页面配置 + +TODO：`navigationBarTitleText`（→ document.title / 页面头部）/ `enablePullDownRefresh` / `onReachBottomDistance` / `disableScroll` / `backgroundColor` 等在 Web 的支持。 + +## 组件配置 + +TODO：`component: true` / `usingComponents` / `componentGenerics`（抽象节点）在 Web 的支持。 + +## 分包与分包异步化 + +TODO：分包在 Web 的打包/加载行为，异步分包 `async` 引用的支持。 diff --git a/.agents/skills/mpx2web/references/web-routing-deploy.md b/.agents/skills/mpx2web/references/web-routing-deploy.md new file mode 100644 index 0000000000..b0aca2a330 --- /dev/null +++ b/.agents/skills/mpx2web/references/web-routing-deploy.md @@ -0,0 +1,46 @@ +# Web 路由、部署与 SEO/SSR + +> **填充说明（待补充，删除本块后正式发布）**：本文件为 **Web 专属能力**参考（RN/小程序无对应），mpx2rn skill 中没有同类文档。填充时参考 `docs-vitepress/guide/advance/ssr.md`、`custom-output-path.md` 等仓库文档。 + +## 目录 + +- [路由模式](#路由模式) +- [部署路径 publicPath](#部署路径-publicpath) +- [页面标题与 meta](#页面标题与-meta) +- [SEO](#seo) +- [服务端渲染 SSR](#服务端渲染-ssr) + +--- + +## 路由模式 + +> **重要**：Mpx 自带一套与微信小程序对齐的跨端路由逻辑。开发者**统一使用 `mpx.navigateTo` / `mpx.redirectTo` / `mpx.switchTab` / `mpx.navigateBack` / `mpx.reLaunch` 进行跳转**，由 Mpx 在编译到 Web 时内部映射到 Web 路由。**不要在 `.mpx` 中直接引入 `vue-router` 或手写 Web 路由跳转。** + +TODO： +- Web 输出底层基于路由（history / hash 模式）实现页面跳转——属于框架内部机制，业务无需直接接触。 +- 路由模式的配置位置与默认值。 +- Mpx 导航 API（`navigateTo` 等）在 Web 的行为与小程序的差异（如 `switchTab` 与 tabBar 的关系）。 + +## 部署路径 publicPath + +TODO： +- `publicPath` / 部署子路径配置，资源引用与路由 base 的关系。 +- 非根路径部署的注意事项。 + +## 页面标题与 meta + +TODO： +- 页面 `navigationBarTitleText` → `document.title` 的映射。 +- 自定义 ``、分享卡片信息（小程序 `onShareAppMessage` 在 Web 的替代）。 + +## SEO + +TODO： +- CSR 下的 SEO 局限与建议。 +- 关键 meta / 结构化数据注入方式。 + +## 服务端渲染 SSR + +TODO： +- Mpx 对 Web SSR 的支持（参见仓库 `docs-vitepress/guide/advance/ssr.md`）。 +- SSR 下需规避的浏览器专属 API（`window` / `document` 直接访问）与生命周期注意事项。 diff --git a/.agents/skills/mpx2web/references/web-script-reference.md b/.agents/skills/mpx2web/references/web-script-reference.md new file mode 100644 index 0000000000..598c8422b1 --- /dev/null +++ b/.agents/skills/mpx2web/references/web-script-reference.md @@ -0,0 +1,59 @@ +# 跨端输出 Web 脚本能力参考 + +> **填充说明（待补充，删除本块后正式发布）**：本文件为骨架。Web 脚本能力（基于 Vue 2.7）与小程序高度一致，填充时**重点标注差异项**：小程序专属生命周期/方法在 Web 的缺失与降级。可参考 `mpx2rn/references/rn-script-reference.md` 的形态。 + +## 目录 + +- [构造选项](#构造选项) +- [数据响应](#数据响应) +- [组合式 API](#组合式-api) +- [生命周期](#生命周期) +- [页面 / 组件实例方法与属性](#页面--组件实例方法与属性) +- [Mpx 运行时导出](#mpx-运行时导出) +- [全局 API](#全局-api) +- [环境 API](#环境-api) +- [状态管理](#状态管理) + +--- + +## 构造选项 + +TODO：`data` / `properties` / `methods` / `computed` / `watch` / `mixins` 等在 Web 的支持。 + +## 数据响应 + +TODO：响应式系统（Vue 2.7 reactivity）、`setData` 兼容、`$set` 等。 + +## 组合式 API + +TODO：` + + + + +``` + +上述四个区块在 Web 输出下的具体跨端能力与差异，分别见下方知识库索引中的模板 / 脚本 / 样式 / JSON 能力参考。 + ## 知识库索引 | 知识库 | 说明 | | --- | --- | -| [Mpx 单文件组件](./references/single-file-component.md) | Mpx 单文件组件的基本结构与语法，开发任意 `.mpx` 文件前读取 | | [条件编译](./references/conditional-compile.md) | 模板、脚本、样式、JSON 等不同部分的条件编译语法，遇到无法跨端等效实现需分平台处理时读取 | | [跨端输出 Web 模板能力参考](./references/web-template-reference.md) | 模板部分跨端能力详情：数据绑定、模板指令、事件、Slot、WXML 模板、i18n、无障碍访问、基础组件清单及其属性/事件在 Web 的支持与降级情况 | | [跨端输出 Web 脚本能力参考](./references/web-script-reference.md) | 脚本部分跨端能力详情：构造选项、生命周期、实例方法/属性、组合式 API、运行时导出、状态管理 | @@ -48,7 +85,6 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展 - 已有组件 Web 跨端适配改造：Web 兼容度高，多数情况无需改动模板/样式主体；识别问题维度后再读对应能力参考的相关小节（如 API 降级查 `web-api-reference.md`、单位/适配查 `web-style-practice.md`）。 - 新建 Web 跨端兼容组件：先按本 SKILL.md 的通用约束起手，遇到能力存疑（某 API 是否存在、某组件是否降级）时再点查对应参考。 - 排查特定编译报错：直接定位到报错维度的能力参考相关小节。 -4. **何时读取 `single-file-component.md`**：仅当不熟悉 Mpx SFC 基本结构时读取；已熟悉 SFC 写法可跳过。 ## 通用约束与适配原则 diff --git a/.agents/skills/mpx2web/references/single-file-component.md b/.agents/skills/mpx2web/references/single-file-component.md deleted file mode 100644 index 3396f3ac48..0000000000 --- a/.agents/skills/mpx2web/references/single-file-component.md +++ /dev/null @@ -1,123 +0,0 @@ -# 单文件开发 {#single-file-development} - -小程序规范中每个页面和组件都是由四个文件描述组成的，wxml/js/wxss/json，分别描述了组件/页面的视图模板，执行逻辑，样式和配置，由于这四个部分彼此之间存在相关性，比如模板中的组件需要在 json 中注册，数据需要在 js 中定义，这种离散的文件结构在实际开发的时候体验并不理想；受 Vue 单文件开发的启发，Mpx 也提供了类似的单文件开发模式，拓展名为.mpx。 - -Mpx 单文件组件（SFC）格式 `.mpx` 是一种将组件的视图模板、组件逻辑、组件样式和组件配置封装在一个文件中的开发模式。每个 `.mpx` 文件都包含了以下几个部分： - -- template 区块：定义组件的视图结构，基于微信小程序的基础模板语法，结合 Mpx 拓展支持的类 Vue 模版指令，如 `wx:style`、`wx:class`、`wx:model`、`wx:ref` 等，对应微信小程序的 `.wxml` 部分 -- script 区块：定义组件的逻辑，基于微信小程序的基础组件语法，结合 Mpx 拓展支持的类 Vue 组件语法，如 数据响应、组合式 API 等，对应微信小程序的 `.js` 部分 -- style 区块：定义组件的样式，支持 CSS 预处理（如 Stylus、Sass、Less 等），跨端输出 RN 时存在较强约束限制，对应微信小程序的 `.wxss` 部分 -- json 区块：定义组件的配置，支持微信小程序的组件配置选项，对应微信小程序的 `.json` 部分 - -示例如下： - -```html - - - - - - - -``` diff --git a/.agents/skills/mpx2web/references/web-api-reference.md b/.agents/skills/mpx2web/references/web-api-reference.md index 348ec1196b..ac3d24bd40 100644 --- a/.agents/skills/mpx2web/references/web-api-reference.md +++ b/.agents/skills/mpx2web/references/web-api-reference.md @@ -1,11 +1,17 @@ # 跨端输出 Web 环境 API 参考 -> **填充说明（待补充，删除本块后正式发布）**：本文件为骨架。`@mpxjs/api-proxy` 在 Web 端将 `mpx.xxx` 映射为 H5 实现。填充时**重点标注受浏览器限制不可用或需降级**的 API（多为设备硬件类）。可参考 `mpx2rn/references/rn-api-reference.md` 的分类与表格形态，但支持结论须按 Web（H5）实际重写。 - ## 使用说明 通过 `@mpxjs/api-proxy` 提供的统一 `mpx.xxx` 调用环境能力，避免直接使用 `wx.xxx` / `my.xxx`。Web 端由 api-proxy 映射为浏览器（H5）实现。如用户通过 `custom` 配置扩充了 API 能力，以用户说明为准。 +支持状态图例： + +- ✓ Web 已实现，可直接使用 +- ⚠️ Web 已实现但有差异 / 部分字段缺失 / 受浏览器条件限制 +- ✗ Web **未实现**，调用会报错 `web环境不支持xxx方法`（api-proxy 默认实现回退到 `envError`），改造时需用条件编译降级或避免使用 + +> 一条贯穿性结论：**凡依赖原生硬件 / 系统能力的 API（蓝牙、NFC、扫码、振动、剪贴板、屏幕亮度、拨打电话、登录、支付、Wi-Fi 等）在 Web 基本均为 ✗**，见文末「Web 未实现 API 一览」。 + ## 目录 - [基础](#基础) @@ -16,43 +22,118 @@ - [媒体](#媒体) - [位置](#位置) - [设备](#设备) +- [Web 未实现 API 一览](#web-未实现-api-一览) --- ## 基础 -TODO：`getSystemInfo` / `getLaunchOptions` 等在 Web 的实现与字段差异。 +| API | 状态 | Web 实现与差异 | +| --- | --- | --- | +| `getSystemInfo` / `getSystemInfoSync` | ⚠️ | 基于 `navigator` / `window.screen` / `document` 拼装。`pixelRatio`、`screenWidth/Height`、`windowWidth/Height`、`language`、`platform` 等有效；`brand` / `model` 由 UA 猜测，`system` 由 UA 解析。**大量字段恒为 `null`**：`version`、`SDKVersion`、`fontSizeSetting`、`benchmarkLevel`、`statusBarHeight`、`safeArea`、各类 `*Authorized`、`bluetoothEnabled` / `locationEnabled` / `wifiEnabled`、`abi` / `cpuType` / `memorySize`。需要状态栏高度 / 安全区域时应改用 CSS（见 `web-style-practice.md`）。 | +| `getDeviceInfo` | ⚠️ | 同上，`brand`/`model`/`system` 由 UA 推断，精度有限。 | +| `getWindowInfo` | ⚠️ | 有效返回 `pixelRatio`、`screenWidth/Height`、`windowWidth/Height`；`statusBarHeight`、`safeArea`、`screenTop` 恒为 `null`。 | +| `getLaunchOptionsSync` / `getEnterOptionsSync` | ⚠️ | 返回 `global.__mpxLaunchOptions` / `__mpxEnterOptions`，无对应数据时返回 `{}`。**无异步版 `getLaunchOptions`**。 | +| `base64ToArrayBuffer` / `arrayBufferToBase64` | ✓ | 纯 JS 实现，无差异。 | ## 路由 -TODO：`navigateTo` / `redirectTo` / `switchTab` / `navigateBack` / `reLaunch` 在 Web（基于路由）的映射与差异，参见 [Web 路由、部署与 SEO/SSR](./web-routing-deploy.md)。 +| API | 状态 | Web 实现与差异 | +| --- | --- | --- | +| `navigateTo` | ✓ | 基于内部 `vue-router`（`global.__mpxRouter.push`）。支持 `events` / `eventChannel` 页面间通信；目标为 tabBar 页会 fail。 | +| `redirectTo` | ✓ | `router.replace`；目标为 tabBar 页会 fail。 | +| `navigateBack` | ✓ | `router.go(-delta)`，`delta` 会被栈深度收敛。 | +| `reLaunch` | ✓ | 支持额外 `delta` 参数，用于宿主 webview 内页面跳转无法统计时由用户手动校正跳转层数。 | +| `switchTab` | ✓ | 仅可切到 tabBar 页，否则 fail。 | + +> 路由模式（history / hash）、`publicPath` 部署路径等配置见 [Web 路由、部署与 SEO/SSR](./web-routing-deploy.md)。 ## 界面 -TODO：`showToast` / `showModal` / `showLoading` / `showActionSheet` / `setNavigationBarTitle` / `pageScrollTo` 等在 Web 的支持。 +| API | 状态 | Web 实现与差异 | +| --- | --- | --- | +| `showToast` / `hideToast` | ✓ | 内置 DOM 组件渲染。 | +| `showLoading` / `hideLoading` | ✓ | 同上，`duration: -1` 常驻。 | +| `showModal` | ✓ | 内置 DOM 弹窗。 | +| `showActionSheet` | ✓ | 内置 DOM 组件。 | +| `setNavigationBarTitle` | ✓ | 设置 `document.title`。 | +| `setNavigationBarColor` | ⚠️ | 仅插入 ``，普通浏览器多无视觉效果。 | +| `hideHomeButton` | ✗ | `envError`。 | +| `pageScrollTo` | ✓ | 经 `nextTick` 后调用内部滚动管理器，需页面已挂载。 | +| `startPullDownRefresh` / `stopPullDownRefresh` | ⚠️ | 需当前页面开启了下拉刷新（页面 JSON `enablePullDownRefresh`）才生效，否则静默无效。 | +| `setTabBarItem` / `setTabBarStyle` / `showTabBar` / `hideTabBar` | ⚠️ | 操作内置 `global.__tabBar`；**自定义 tabBar（`custom: true`）下 set 类调用会 fail**，需自行管理。 | +| `onWindowResize` / `offWindowResize` | ✓ | 监听 `window.resize`。 | ## 网络 -TODO：`request` / `uploadFile` / `downloadFile` / `connectSocket` 在 Web 的支持（跨域 / CORS 注意事项）。 +| API | 状态 | Web 实现与差异 | +| --- | --- | --- | +| `request` | ⚠️ | 基于 `axios`。**受同源策略约束，跨域需服务端正确配置 CORS**；`GET` 自动拼 query，`application/x-www-form-urlencoded` 的 `POST` 自动序列化。返回结果中 `cookies` / `profile` / `exception` 为不支持字段（访问会告警）。返回 `RequestTask` 可 `abort()`。 | +| `connectSocket` | ⚠️ | 基于浏览器 `WebSocket`，返回 `SocketTask`。**请通过 `socketTask.send/close/onOpen/onMessage/onError/onClose` 操作**；全局式 `sendSocketMessage` / `closeSocket` / `onSocketXxx` 仅打印告警、不工作。 | +| `uploadFile` / `downloadFile` | ✗ | Web 无实现（`envError`）。如需上传/下载请用条件编译，在 Web 端改用 `FormData` + `fetch` / `` 等原生方案。 | ## 数据缓存 -TODO：`setStorage` / `getStorage`（映射到 localStorage）同步异步在 Web 的支持与容量限制。 +| API | 状态 | Web 实现与差异 | +| --- | --- | --- | +| `setStorage` / `setStorageSync` | ✓ | 映射 `localStorage`，值经 `JSON.stringify` 存储。 | +| `getStorage` / `getStorageSync` | ✓ | 取不到时异步版 fail、同步版返回 `''`。 | +| `removeStorage` / `removeStorageSync` | ✓ | `localStorage.removeItem`。 | +| `clearStorage` / `clearStorageSync` | ✓ | `localStorage.clear`。 | +| `getStorageInfo` / `getStorageInfoSync` | ⚠️ | 返回 `keys`，但 `limitSize` / `currentSize` 恒为 `null`。 | + +> 限制：`localStorage` 仅存字符串、容量约 5MB、同步阻塞，且隐私模式 / 禁用 Cookie 时可能不可用。 ## 媒体 -TODO：`chooseImage` / `previewImage` / `chooseMedia` / 音视频 API 在 Web 的支持与降级。 +| API | 状态 | Web 实现与差异 | +| --- | --- | --- | +| `previewImage` | ✓ | 内置 DOM 预览组件。 | +| `getImageInfo` | ⚠️ | 通过 `new Image()` 加载，仅返回 `width` / `height`；`path` / `orientation` / `type` 为不支持字段。 | +| `compressImage` | ✗ | `envError`。 | +| `chooseMedia` | ✗ | `envError`。Web 选图请用条件编译，改用 ``。 | +| `chooseImage` | ✗ | api-proxy 未导出该 API（同上用原生 `input`）。 | +| `createInnerAudioContext` | ⚠️ | 基于 HTML `Audio`，支持 `play/pause/stop/seek/destroy` 及 `src/autoplay/loop/volume/duration/currentTime` 等属性；`obeyMuteSwitch`、`startTime` 等为占位。 | +| `createVideoContext` | ⚠️ | 操作页面内 `