mpx-rn-style-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mpx 跨端输出 RN 样式开发指南

Mpx Cross-Platform Output to RN Style Development Guide

背景介绍

Background Introduction

Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展支持的跨端开发框架，支持将同一套代码输出到小程序（微信、支付宝、百度等）、Web 和 React Native 平台。尽管 Mpx 在编译时和运行时对样式能力进行了一定程度的跨平台抹平，但在输出 RN 时在样式能力支持上仍与小程序和 Web 平台存在较大差异，本文档详细描述了 Mpx 输出 RN 时的样式能力支持情况，以及跨平台开发时样式兼容的最佳实践。

Mpx 采用类 Vue 的单文件组件（SFC）格式

.mpx

进行组件与页面定义，详情查看：Mpx 单文件组件

Mpx is a cross-platform development framework based on WeChat Mini Program syntax with Vue-like syntax extension support. It supports outputting the same set of code to mini programs (WeChat, Alipay, Baidu, etc.), Web, and React Native platforms. Although Mpx has achieved a certain degree of cross-platform unification of style capabilities at compile time and runtime, there are still significant differences in style capability support when outputting to RN compared to mini programs and Web platforms. This document details the style capability support when Mpx outputs to RN, as well as best practices for style compatibility during cross-platform development.

Mpx uses Vue-like single-file component (SFC) format

.mpx

for component and page definition. For details, see: Mpx Single-File Component

知识库指引

Knowledge Base Guidelines

根据具体场景读取以下参考文件：

样式能力参考：当用户询问 Mpx2RN 样式能力支持详情，遇到样式不生效、样式报错等问题，或进行跨端样式适配开发时，读取跨端输出 RN 样式能力支持详情
开发最佳实践：当用户询问 Mpx2RN 样式开发的最佳实践，查询如何实现某项样式效果，或查询不支持的样式能力是否存在兼容方案时，读取跨端输出 RN 样式开发最佳实践

Read the following reference documents according to specific scenarios:

Style Capability Reference: When users ask about details of Mpx2RN style capability support, encounter issues such as styles not taking effect or style errors, or conduct cross-platform style adaptation development, read Cross-Platform Output to RN Style Capability Support Details
Development Best Practices: When users ask about Mpx2RN style development best practices, inquire how to achieve a certain style effect, or check if there is a compatibility solution for unsupported style capabilities, read Cross-Platform Output to RN Style Development Best Practices

跨端输出 RN 样式适配改造

Cross-Platform Output to RN Style Adaptation Transformation

当用户要求对已有 Mpx 组件进行跨端输出 RN 样式适配改造时，遵循以下流程与约束。

When users require style adaptation transformation of existing Mpx components for cross-platform output to RN, follow the following processes and constraints.

输入

Input

基于小程序技术规范编写的

{name}.mpx

组件。

{name}.mpx

component written based on mini program technical specifications.

输出

Output

以用户指示为准，若无特殊指示则默认在原文件

{name}.mpx

中进行修改。在输出修改后的代码时，应输出完整的组件代码，避免使用省略号，确保用户可以直接复制或应用修改。

Follow the user's instructions. If there are no special instructions, modify the original

{name}.mpx

file by default. When outputting the modified code, output the complete component code, avoid using ellipsis, and ensure that users can directly copy or apply the modifications.

约束指引

Constraint Guidelines

进行样式适配改造时需严格遵循以下约束指引：

选择器单类化（示例）：禁止使用复合选择器（如
```
.list .item
```
），必须转换为单类名等效实现（如
```
.list-item
```
），并确保同步修改
```
<template>
```
结构和
```
<script>
```
（如
```
createSelectorQuery
```
）中的对应引用。

Bad Example:

<style> .list .item { color: red; } </style>

Good Example:

<style> .list-item { color: red; } </style>

模板样式类名动态绑定尽可能使用
```
wx:style
```
和
```
wx:class
```
模版指令，尽量避免在
```
style
```
和
```
class
```
属性中使用
```
{{}}
```
插值表达式进行动态绑定。

Bad Example:

<view class="item {{isActive ? 'active' : ''}}">

Good Example:

<view class="item" wx:class="{{ {active: isActive} }}">

非必要尽可能减少条件编译的使用，优先使用跨平台兼容的实现方式，避免出现大面积连续的条件编译，因为这会严重破坏代码的可读性和后期维护性。
保留原始样式定义中的
/*use rpx*/
和
/*use px*/
注释，此类注释用于编译期间批量切换样式单位

Strictly follow the following constraint guidelines during style adaptation transformation:

Single Class Selector (Example): Compound selectors (e.g.,
```
.list .item
```
) are prohibited. They must be converted to equivalent implementations with single class names (e.g.,
```
.list-item
```
), and ensure that corresponding references in the
```
<template>
```
structure and
```
<script>
```
(such as
```
createSelectorQuery
```
) are updated synchronously.

Bad Example:

<style> .list .item { color: red; } </style>

Good Example:

<style> .list-item { color: red; } </style>

For dynamic binding of template style class names, use
```
wx:style
```
and
```
wx:class
```
template directives as much as possible, and avoid using
```
{{}}
```
interpolation expressions for dynamic binding in
```
style
```
and
```
class
```
attributes.

Bad Example:

<view class="item {{isActive ? 'active' : ''}}">

Good Example:

<view class="item" wx:class="{{ {active: isActive} }}">

Reduce the use of conditional compilation unless necessary, prioritize cross-platform compatible implementations, avoid large areas of continuous conditional compilation as this will seriously damage code readability and maintainability.
Retain the
/*use rpx*/
and
/*use px*/
comments in the original style definitions. Such comments are used to batch switch style units during compilation.

任务流程

Task Process

选择器适配改造：

分析组件的
```
<style>
```
部分，对于
```
sass
```
、
```
less
```
、
```
stylus
```
等支持嵌套选择器写法的预处理语言，先将原代码中所有的嵌套选择器写法展开铺平为传统的选择器写法，便于后续进行选择器的兼容性判断及适配改造。
- Bad Example (嵌套选择器未展开):
  less
```
.list {
  .item {
    color: red;
    &.active {
      color: blue;
    }
  }
}
```
- Good Example (嵌套选择器已展开铺平):
  less
```
.list .item { color: red; }
.list .item.active { color: blue; }
```

分析组件的

<style>

部分，参考 Mpx 跨端输出 RN 样式开发最佳实践#选择器使用建议，将 RN 平台不支持的选择器替换为单类选择器等效实现，并同步更新

<template>

和

<script>

中对应的类名引用。

Good Example (单类选择器等效实现):

html

<!-- 推荐：直接使用等效的单类名并使用 wx:class 进行动态绑定 -->
<view class="list-item" wx:class="{{ { 'list-item-active': isActive } }}">
  <text class="title">标题</text>
</view>

css

/* 推荐使用单类选择器，避免使用后代选择器和交集选择器 */
.list-item { padding: 20rpx; }
.list-item-active { color: red; }

对于无法替换为单类选择器等效实现的选择器，使用原平台条件编译对该选择器样式片段进行局部包裹，保留在原平台输出产物中，并添加
```
todo
```
注释记录不兼容 RN 平台的详情。
- Good Example (局部条件编译):
  css
```
/* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
/* todo: RN 不支持同级相邻选择器，仅在原平台保留 */
.item + .item { margin-top: 10rpx; }
/* @mpx-endif */
```

样式属性适配改造：

参考跨端输出 RN 样式能力支持详情，对

<style>

、

<template>

和

<script>

中定义的样式属性进行分析，对于 RN 平台不支持的样式属性，结合 Mpx 跨端输出 RN 样式开发最佳实践将其替换为跨端兼容的等效实现。

Good Example (display: none 跨端等效实现):

css

.mask {
  /* @mpx-if (__mpx_mode__ === 'ios' || __mpx_mode__ === 'android' || __mpx_mode__ === 'harmony') */
  flex: 0;
  height: 0;
  width: 0;
  padding: 0;
  margin: 0;
  overflow: hidden;
  /* @mpx-else */
  display: none;
  /* @mpx-endif */
}

对于无法进行跨端兼容等效实现的样式属性，使用原平台条件编译对该样式属性进行局部包裹，保留在原平台输出产物中，并添加

todo

注释记录不兼容 RN 平台的详情。

Good Example (局部条件编译):

css

.animation-box {
  /* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
  /* todo: RN 不支持 keyframes 动画，仅在原平台保留 */
  animation: slideIn 0.5s ease-in-out;
  /* @mpx-endif */
}

检查与确认：

检查确保
```
<style>
```
中不存在任何嵌套选择器写法。
检查确保
```
<style>
```
中所有 RN 平台不支持的选择器都已被替换为单类选择器等效实现，或被原平台条件编译所包裹，输出到 RN 的部分不包含复合选择器。
检查确保
```
<style>
```
、
```
<template>
```
和
```
<script>
```
中所有 RN 平台不支持的样式属性都已被替换为跨端兼容的等效实现，或被原平台条件编译所包裹，输出到 RN 的部分不包含不支持的样式属性。
检查确保
```
<style>
```
、
```
<template>
```
和
```
<script>
```
中不存在大面积的条件编译，所有添加的条件编译仅最小包裹不兼容的样式片段。

Selector Adaptation Transformation:

Analyze the
```
<style>
```
part of the component. For preprocessors that support nested selectors such as
```
sass
```
,
```
less
```
,
```
stylus
```
, first expand all nested selector syntax in the original code into traditional selector syntax to facilitate subsequent compatibility judgment and adaptation transformation.
- Bad Example (Nested Selectors Not Expanded):
  less
```
.list {
  .item {
    color: red;
    &.active {
      color: blue;
    }
  }
}
```
- Good Example (Nested Selectors Expanded):
  less
```
.list .item { color: red; }
.list .item.active { color: blue; }
```

Analyze the

<style>

part of the component, refer to Mpx Cross-Platform Output to RN Style Development Best Practices#Selector Usage Recommendations, replace selectors not supported by the RN platform with equivalent implementations using single class selectors, and update corresponding class name references in

<template>

and

<script>

synchronously.

Good Example (Equivalent Implementation with Single Class Selector):

html

<!-- Recommended: Directly use equivalent single class names and use wx:class for dynamic binding -->
<view class="list-item" wx:class="{{ { 'list-item-active': isActive } }}">
  <text class="title">Title</text>
</view>

css

/* Recommended to use single class selectors, avoid descendant selectors and intersection selectors */
.list-item { padding: 20rpx; }
.list-item-active { color: red; }

For selectors that cannot be replaced with equivalent implementations using single class selectors, use platform-specific conditional compilation to locally wrap the selector style fragment, retain it in the original platform output product, and add a
```
todo
```
comment to record details of incompatibility with the RN platform.
- Good Example (Local Conditional Compilation):
  css
```
/* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
/* todo: RN does not support adjacent sibling selectors, retained only in the original platform */
.item + .item { margin-top: 10rpx; }
/* @mpx-endif */
```

Style Property Adaptation Transformation:

Refer to Cross-Platform Output to RN Style Capability Support Details, analyze the style properties defined in
```
<style>
```
,
```
<template>
```
and
```
<script>
```
. For style properties not supported by the RN platform, replace them with cross-platform compatible equivalent implementations combined with Mpx Cross-Platform Output to RN Style Development Best Practices.
- Good Example (Cross-Platform Equivalent Implementation of display: none):
  css
```
.mask {
  /* @mpx-if (__mpx_mode__ === 'ios' || __mpx_mode__ === 'android' || __mpx_mode__ === 'harmony') */
  flex: 0;
  height: 0;
  width: 0;
  padding: 0;
  margin: 0;
  overflow: hidden;
  /* @mpx-else */
  display: none;
  /* @mpx-endif */
}
```
For style properties that cannot be replaced with cross-platform compatible equivalent implementations, use platform-specific conditional compilation to locally wrap the style property, retain it in the original platform output product, and add a
```
todo
```
comment to record details of incompatibility with the RN platform.
- Good Example (Local Conditional Compilation):
  css
```
.animation-box {
  /* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
  /* todo: RN does not support keyframe animations, retained only in the original platform */
  animation: slideIn 0.5s ease-in-out;
  /* @mpx-endif */
}
```

Inspection and Confirmation:

Check to ensure that there are no nested selector syntax in
```
<style>
```
.
Check to ensure that all selectors not supported by the RN platform in
```
<style>
```
have been replaced with equivalent implementations using single class selectors, or wrapped with platform-specific conditional compilation, and the output to RN does not contain compound selectors.
Check to ensure that all style properties not supported by the RN platform in
```
<style>
```
,
```
<template>
```
and
```
<script>
```
have been replaced with cross-platform compatible equivalent implementations, or wrapped with platform-specific conditional compilation, and the output to RN does not contain unsupported style properties.
Check to ensure that there are no large areas of conditional compilation in
```
<style>
```
,
```
<template>
```
and
```
<script>
```
, and all added conditional compilation only minimally wraps incompatible style fragments.