mpx-rn-style-guide

Mpx Cross-Platform Output to RN Style Development Guide

Background Introduction

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

Mpx uses a Vue-like single-file component (SFC) format .mpx for component and page definitions. For details, see:Mpx Single-File Components

Knowledge Base Index

Knowledge Base	Description
Mpx Single-File Components	Describes the basic structure and syntax of Mpx single-file components and provides simple examples. Read when developing Mpx single-file components.
Conditional Compilation	Describes the conditional compilation syntax in Mpx for different parts including templates, scripts, styles, and configuration. Read when cross-platform adaptation development encounters compatibility issues that need to be handled per platform.
Cross-Platform Output to RN Style Capability Reference	Describes detailed style capability support when Mpx outputs to RN. Read when checking whether a certain style capability is supported, or when encountering issues such as styles not taking effect or style errors.
Best Practices for Cross-Platform Output to RN Style Development	Describes cross-platform compatibility solutions and style development best practices for commonly used selectors and style properties when Mpx outputs to RN. Read when adapting existing components for cross-platform styles or developing cross-platform styles for new components.

Cross-Platform Output to RN Style Adaptation Refactoring

When the user requests cross-platform output to RN style adaptation refactoring for existing Mpx components, follow the process and constraints below.

Input

Based on mini program technical specifications {name}.mpx components.

Output

Subject to the user's instructions. If there are no special instructions, by default modify in the original file {name}.mpx . When outputting the modified code, output the complete component code and avoid using ellipses to ensure that the user can directly copy or apply the modifications.

Constraint Guidelines

The following constraint guidelines must be strictly followed when performing style adaptation refactoring:

1. Single-class selectors (example): Compound selectors are prohibited (such as .list .item), and must be converted to equivalent implementations using a single class name (such as .list-item), and ensure that corresponding references are updated in the <template> structure and <script>(such as createSelectorQuery).

• Bad Example: <style> .list .item { color: red; } </style>
• Good Example: <style> .list-item { color: red; } </style>

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

• Bad Example: <view class="item {{isActive ? 'active' : ''}}">
• Good Example: <view class="item" wx:class="{{ {active: isActive} }}">

1. For selectors and style properties that have cross-platform compatible solutions, readBest Practices for Cross-Platform RN Output Style Development, and prioritize refactoring them to cross-platform compatible solutions for easier future maintenance.

• Cross-Platform Compatible Solutions for Selectors:
  • Compound selectors (descendant/intersection, etc.) → equivalent single-class selectors:Reference
  • Child element pseudo-classes (:first-child / :last-child / :nth-child) → use wx:class + index to determine:Reference
  • Pseudo-element selectors (::before / ::after) → replace with real nodes:Reference
  • Active state pseudo-class (:active) → use hover-class/hover-stay-time：Reference
• Cross-Platform Compatible Solutions for Style Properties:
  • Hairline border: original platform 1rpx, RN uses hairlineWidth and switches via conditional compilation:Reference
  • Unit compatibility:rem/em → use rpx：Reference
  • Font weight: avoid numeric font-weight, use normal/bold：Reference
  • Text overflow:white-space/text-overflow → keep the style on the original platform, RN uses numberOfLines template attribute conditional compilation:Reference
  • Hidden elements: avoid display: none, use zeroed dimensions with overflow: hidden and other combined styles:Reference
  • Layout properties: avoid grid/float, use Flex layout uniformly:Reference Reference

1. Reduce the use of conditional compilation when not necessary,avoid large areas of continuous conditional compilation, because this severely harms code readability and later maintainability.
2. Preserve the /*use rpx*/ and /*use px*/ comments in the original style definitions; such comments are used to batch-switch style units during compilation.

Task Flow

1. Selector Adaptation and Refactoring：

• Analyze the component's <style> section. For sass、less、stylus and other preprocessor languages that support nested selector syntax, first expand and flatten all nested selector syntax in the original code into traditional selector syntax, to facilitate subsequent selector compatibility assessment and adaptation refactoring.
  • Bad Example (nested selectors not expanded):

    .list {
      .item {
        color: red;
        &.active {
          color: blue;
        }
      }
    }
    

  • Good Example (nested selectors expanded and flattened):

    .list .item { color: red; }
    .list .item.active { color: blue; }
    

• Read Best Practices for Mpx Cross-Platform RN Output Style Development · Selector Usage Recommendations, analyze the component's <style> section, refactor selectors not supported by the RN platform into cross-platform compatible equivalent implementations, and synchronously update the corresponding class name references in <template> and <script> .
• For selectors that cannot be implemented as cross-platform compatible equivalents, use the original platform conditional compilation to locally wrap that selector's style fragment, keep it in the original platform output artifact, and add a todo comment recording the details of RN platform incompatibility.
  • Good Example (local conditional compilation):

    /* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
    /* todo: RN 不支持 ::-webkit-scrollbar 伪元素，仅在原平台保留 */
    .scroll-view::-webkit-scrollbar { display: none; }
    /* @mpx-endif */
    

1. Style Property Adaptation and Refactoring：

• Read Details of Style Capability Support for Cross-Platform RN Output, for <style>、<template> and <script> Analyze the style properties defined in, and check whether there are any style properties not supported by the RN platform.
• For style properties not supported by the RN platform, read Mpx Cross-Platform Output RN Style Development Best Practices, and refactor them into cross-platform compatible equivalent implementations.
• For style properties that cannot be refactored into cross-platform compatible equivalent implementations, use the original platform conditional compilation to locally wrap the style property, retain it in the original platform output artifact, and add a todo comment recording the details of incompatibility with the RN platform.
  • Good Example (local conditional compilation):

    .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 */
    }
    

1. Check and Confirm：

• Check to ensure that <style> does not contain any nested selector syntax.
• Check to ensure that <style>、<template> and <script> all selectors and style properties in have cross-platform compatibility solutions and have been refactored into cross-platform compatible equivalent implementations.
• Check to ensure that <style>、<template> and <script> all selectors and style properties in that are not supported by the RN platform have been wrapped by original platform conditional compilation.
• Check to ensure that <style>、<template> and <script> there is no large-scale conditional compilation in, and all added conditional compilation only minimally wraps the incompatible style fragments.
• Check to ensure that <style> after conditional compilation processing, there are no empty selectors (selectors with no style content) in the output artifact.