Cross-platform compatibility

uni-app has encapsulated commonly used components and JS API into the framework. Developers can ensure multi-platform compatibility by developing according to uni-app specification, and most businesses can be directly satisfied.

Each platform has its own characteristics, so there will be some situations that can not be cross-platform.

• Writing a lot of if else may cause low performance in code execution and management confusion.
• Second modification after compiling to different projects will make the subsequent upgrade troublesome.

In C language, different codes are compiled for windows , mac and other os, by means of #ifdef and #ifndef. uni-app refers to this idea, provides a conditional compilation method for uni-app, and elegantly completes the platform personalized realization in a project.

Conditional compilation

Conditional compilation is marked with special comments which are the basic of compiling the code inside these comments to different platforms during compilation.

**Writing: **Start with #ifdef or #ifndef plus %PLATFORM% and end with #endif.

• #ifdef: if defined only exists on a certain platform.
• #ifndef: if not defined exists except for a certain platform.
• %PLATFORM%: platform name

Writing method of conditional compilation	Instruction
#ifdef APP Code that requires conditional compilation #endif	Code that only appears on the App platform
#ifndef H5 Code that requires conditional compilation #endif	Codes that exist on all platforms except the H5 platform
#ifdef H5 || APP Code that requires conditional compilation #endif	The code that exists on the H5 platform or App platform (There is only || but not &&, because there is no intersection)

The possible values of %PLATFORM% are as follows:

Value	Effective conditions
VUE3	HBuilderX 3.2.0+ details (opens new window)
APP	App
APP-NVUE	App nvue
H5	H5

Supported files

• .vue
• .js
• .css
• pages.json
• Precompiled language files, such as .scss, .less, .stylus, .ts, .pug

Notice:

• Conditional compilation is realized by annotations. In different grammars, annotations are written differently. js uses // Comments, css uses /* Comments */, and vue/nvue template uses <!-- Comments -->;
• Conditional compilation APP includes APP-NVUE and APP-VUE;
• When using conditional compilation, please ensure the correctness of the Pre-compilation and Post-compilation files, for example, there should be no extra commas in the json file;
• VUE3 needs to configure "vueVersion" : "3" at the root node of the project's manifest.json file

Conditional compilation of API

// #ifdef  %PLATFORM%
...
// #endif

For example, the following codes only appear on App:

For example, the following codes will not appear on the H5 platform:

In addition to conditional compilation on a single platform, it also supports simultaneous compilation on multiple platforms. Use || to separate the platform names.

For example, the following codes will appear on App and H5 platforms:

Conditional compilation of components

<!--  #ifdef  %PLATFORM% -->
...
<!--  #endif -->

For example, the following components will only appear on App:

<view>
    <view>
        <!-- #ifdef APP -->
		        <my-test></my-test>
		    <!-- #endif -->
    </view>
</view>

Conditional Compilation of style

/*  #ifdef  %PLATFORM%  */
...
/*  #endif  */

Notice: For style conditional compilation, whether it is css or sass/scss/less/stylus and other pre-compiled languages, you must use the wording of /*Comments*/.

Correct writing

Wrong writing

Conditional compilation of pages.json

The following pages will only be compiled when running to App.

Specific functions of different platforms can be better implemented with conditional compilation of pages.json. In this way, no extra resources will be generated on other platforms so as to reduce the package size.

For conditional compilation of json, if the key names of different platforms are the same, the verifiers installed by developers under cli project will report errors, and the verification rules of these verifiers for the same key of json need to be closed by themselves. If the verifier of HBuilderX is used, there is no need to care about this problem, because the syntax verifier of HBuilderX has been optimized for this purpose.

Conditional compilation of static directory

In different platforms, there may be differences in the referenced static resources. This problem can be solved by conditional compilation of static. Create a dedicated directory for different platforms under the static directory (the directory name is the same as the %PLATFORM% value range, but the letters are all lowercase)), the static resources in the dedicated directory will only be compiled on a specific platform.

As shown in the following directory structure, a.png will be compiled only on the App platform, and b.png will be compiled on all platforms.

	
┌─static                
│  ├─app-plus
│  │  └─a.png     
│  └─b.png
├─main.js        
├─App.vue      
├─manifest.json 
└─pages.json     
	

Conditional compilation of whole directories

If you want to separate the page files of each platform more thoroughly, you can also create a platforms directory in the root directory of the uni-app project, and then create further subdirectories such as app-plus below to store files of different platforms.

Notice

• The platforms directory only supports the placement of page files (that is, page vue files). If conditional compilation of other resources is required, it is recommended to use conditional compilation in the static directory (opens new window)

HBuilderX support

HBuilderX provides rich support for conditional compilation of uni-app:

Code block support

When developing uni-app in HBuilderX, you can quickly generate code fragments for conditional compilation by entering ifdef

Syntax highlighting

HBuilderX provides syntax highlighting for the code comment part of conditional comments, which can distinguish whether the writing mode is correct or not, making the code clearer (For standalone js files, you need to switch the javascript es6+ editor in the lower right corner of the editor. Standalone css files do not support highlighting, which does not affect the use effect)

Correct comment and quick selection

In HBuilderX, ctrl+alt+/ can generate correct comments (js: // Comments, css: /* Comments */, vue/nvue template: <!-- Comments -->).

Click ifdef or endif to quickly select the conditional compilation part; Click the folding icon on the left to collapse part of the conditional compilation code.

Notice

• It is not supported to distinguish Android and iOS platforms through conditional compilation. If you need to distinguish them, please call uni.getSystemInfo to get the platform information. Supports ifios, ifAndroid code blocks, which is convenient for writing and judging.
• Some cross-side tools can provide conditional compilation or polymorphism of js, but it is far from enough for actual development. uni-app does not only deal with js, but can also perform multi-end conditional compilation on any code to truly solve the cross-side problem in real projects. In addition, the so-called polymorphism will cause plenty of redundant code in actual development, which is not conducive to reuse and maintenance.
• Some companies operate their products with different requirements for different platforms, but that is no reason to reject uni-App. The key lies in whether there is more reusable code or more personalized code in the project. Normally, there shall be more reusable codes, so it should still be multi-side. Personalized codes are placed in directories of different platforms for differentiated maintenance.