辛宝Otto 的玄酒清谈

This article is equivalent to reading the purpose and structure of the @dcloudio/uni-nvue-styler project, and explains how to verify the actual effect.

The example given is an example of uni-app-x on the iOS platform, and the steps for operating on the actual Android platform and nvue platform are the same.

Platform Limitations#

When dealing with cross-platform CSS processing, there are some requirements that are different from web pages:

• Cross-platform does not fully support all CSS syntax, it is a subset of CSS rules.
• The default CSS values ​​brought by cross-platform need to align with web and mini programs.
• Cross-platform CSS needs to consider class definitions, style definitions, and style runtime switching definitions.
• Cross-platform child element styles cannot inherit parent element styles.

Here, we explain how the iOS part of uni-app-x parses styles. Styles are an important and special logical part.

Technically speaking, the essence is still some custom postcss plugins to parse the styles passed by the user, and cooperate with the client platform to rewrite and modify some special styles.

Source Code Location#

uni-app repository refers to the next branch on GitHub.

There is the @dcloudio/uni-nvue-styler package.

• Style test file packages/uni-nvue-styler/__tests__/normalize.spec.ts
• Main logic packages/uni-nvue-styler/src/index.ts

The main logic part is the logic entry file

export { expand } from './expand'
export { normalize } from './normalize'
export { objectifier } from './objectifier'
export { parse } from './parse'

A wonderful journey of converting a CSS rule!

Technically explained:

• Two custom postcss plugins expand and normalize are defined and handed over to postcss for processing.
• The result is handed over to objectifier to convert it into an object type accepted by the client.

parse String Parsing#

This is the core main method, which converts the syntax through postcss into an object.

expand Unfolding#

One of the two postcss plugins. Common CSS logic abbreviations are expanded into multiple minimal rules.

For example, border/background/transition, and so on.

For example, the style transition: margin-top 500ms ease-in-out 1s needs to be expanded into multiple rules.

normalize Standardization#

One of the two postcss plugins. It follows the previous split CSS rules and further adjusts the values, such as length units and handling illegal values.

For example, width:200px -> remove unit 200
For example, width: a -> illegal values will be ignored and warned For example, color: #f00 -> complete #ff0000
For example, transition/font-face

objectifier String to Object#

The processed CSS rules are converted into objects, forming a collection of style rules under the current page or component.

For example, the string .abc{color:red} will be converted into an object similar to the following. The empty string here is to support other CSS selectors, such as descendant selectors .a .b. For example, direct descendant selector > and so on.

For example, add ! in front of specific styles to handle !important

var abc = {
  "":{
    color:'red'
  },
  ".bar ":{
    left: 2
  }
}

Understanding the Source Code#

If you encounter a bug during daily use and need to fix the problem or add new features, you need to read and debug the source code.

Because this part of the logic is relatively abstract, the best solution is to read the test cases to further understand the purpose of each step.

How to Verify if it Works#

Sometimes when making feature/fix changes, if you have completed the code changes and added corresponding unit tests, how do you verify the effect of the changes?

Here is a summary of the process:

• Build the @dcloudio/uni-nvue-styler artifact.
• Replace the artifact in HBuilderX.
• Verify the effect.

Build Artifact#

To modify uni-nvue-styler, you need to execute the build, you can directly execute

pnpm run build nvue-styler

Get the artifact package and locate the dist folder.

Replace Artifact#

Open the package contents of HBuilderX, note that I am using the internal -Dev version here:

/Applications/HBuilderX-Dev.app/Contents/HBuilderX/plugins/uniapp-cli-vite/node_modules/@dcloudio/uni-nvue-styler/dist

Replace the dist files just now, there should be three files.

After restarting and recompiling, you should be able to see the modified effect.

Conclusion#

Explains the purpose of the @dcloudio/uni-nvue-styler project in the uni-app project's next branch.

And explains how to understand, debug, and validate.