【RFC】应用级 CSSinJS 解决方案 | CSSinJS solution for Application

[arvinxx]

概述 Summary

为应用级研发提供结合 antd V5 Token System 的 css-in-js 解决方案。

We will provide a CSS-in-JS solution combined with the antd V5 token system for application-level development.

动机 Motivation

距 antd 发布已经 3 月有余，逐步有新的应用开始接入 antd v5, antd 作为一个组件库的职责和边界只在于提供高品质的基础组，应用层如何消费 antd 并不限制。但目前来看，无论是内部落地应用，还是社区的相关反馈来看，关于 antd v5 token 系统如何使用、less 怎么迁移、应用如何集成 cssinjs 等问题都让应用开发者较难享受到 cssinjs 所带来的红利。

It has been more than three months since the release of antd v5, and new applications are gradually starting to integrate with antd v5. As a component library, antd's responsibility and boundaries are only to provide high-quality basic components, and the application development is not restricted in how to consume antd. However, based on internal application implement and community feedback, it is difficult for application developers to enjoy the dividends brought by CSS-in-JS technology because of issues such as how to use antd v5 token system, how to migrate from Less, and how to integrate CSS-in-JS into applications.

所以为了将 token 系统的推行变得更加顺利，我们需要提供一个使用 antd token 系统的最佳实践，帮助应用开发者更低门槛地集成 cssinjs 方案，享受新技术所带来的红利。

Therefore, to make the promotion of the token system more smooth, we need to provide a best practice for using the antd token system to help application developers integrate the CSS-in-JS solution with lower barriers and enjoy the benefits of new technology.

于是 antd-style 应运而生。

That's why antd-style born.

核心问题与解决手法 Core Problems and Solutions

目前我们看下来和 antd token 体系集成存在最大的几个问题：

• 如何快速实现 antd 的主题切换？
• antd 的 token 如何使用？
• 旧项目（less）如何迁移？
• 自定义主题如何集成？
• cssinjs 的应用层面最佳实践是怎么样的？

Currently, there are several major problems with integrating the antd token system:

• How to quickly implement theme switching in antd?
• How to use antd's tokens?
• How to migrate from the old project (Less)?
• How to integrate custom themes?
• What is the best practice for applying CSS-in-JS at the application layer?

antd-style 需要逐一回答上述问题，解决思路如下：

• 针对应用级主题相关切换诉求：在 antd-style 中提供一个 high-level 的 Provider，只负责主题相关的功能（基于CP封装），提供一键切换亮暗色主题、自定义 Token 的统一入口，使得应用开发者可以一键完成主题切换；
• 针对应用级 CSSinJS 的样式诉求：提供一个 high-level 的样式创建方法，可以用 css-in-js 的方式完成样式书写。在应用级功能上做到 less 低成本迁移、 token 取用、响应式工具函数、主题模式等功能。在底层实现上复用现有css-in-js 生态工具链，并尽量与某个「具体」的 CSSinJS 库解耦。

antd-style needs to answer the above questions one by one, and the solution is as follows:

• For application-level theme switching requirements: Provide a high-level Provider in antd-style, which is only responsible for theme-related functions (based on ConfigProvider), providing a unified entry for one-click switching between light and dark themes and custom tokens, allowing application developers to complete theme switching with one click;
• For application-level CSS-in-JS style requirements: Provide a high-level method for creating styles, which can complete style writing in CSS-in-JS. Achieve low-cost migration from Less, token usage, responsive utility functions, theme mode, and other functions at the application level. Reuse the existing CSS-in-JS ecosystem toolchain at the implementation level and try to decouple it from a specific CSS-in-JS library.

“解耦 ”这件事情可以展开说说。在 CSSinJS 生态中，目前已经固化的两个通用 api 是 styled 和 css。前者用于创建样式组件，后者用于创建样式片段。antd-style 要做的事情就是基于 styled 和 css 两个 api 做一层 high-level 的封装，进而集成 antd 的 token 体系，或者做进一步的性能优化等等。这样的一个好处就是，如果未来某个 CSSinJS 库就有了更加好的性能或者更强的能力（比如构建时抽取css），上层应用的使用方式不用做任何变化，只需修改 antd-style 的 css、styled 的引入库即可接入。甚至可以让用户自行指定 css 、styled 方法使用哪个 CSSinJS 库。

Let's talk about "decoupling". In the CSS-in-JS ecosystem, the two universal APIs that have been solidified are styled and css. The former is used to create style components, and the latter is used to create style fragments. What antd-style needs to do is to encapsulate styled and css APIs at a high level, and then integrate the antd token system or further performance optimization. The advantage of this is that if a CSS-in-JS library has better performance or stronger capabilities in the future (such as extracting CSS during build time), the usage of the upper application does not need to change at all, and only the css and styled introduction libraries of antd-style need to be modified. Users can even specify which CSS-in-JS library to use for css and styled methods.

API

基于上述思路 antd-style 所提供的两个核心 API： ThemeProvider 和 createStyles。

Based on the above ideas, antd-style provides two core APIs: ThemeProvider and createStyles.

ThemeProvider ：

用于全局管理主题变量的容器。基于 CP封装 且提供一键切换亮暗色主题、自定义主题、应用级作用域样式的统一入口。文档 ->

a container for globally managing theme variables. Based on CP encapsulation, it provides a unified entry for one-click switching between light and dark themes, custom themes, and application-level scoped styles. Documentation ->

import { ThemeProvider } from 'antd-style';

export default () => {
  return (
    // 一键实现亮暗色自动切换
    <ThemeProvider themeMode={'auto'}>
      <App />
    </ThemeProvider>
  );
};

createStyles：

对标 css modules 的应用样式方案，可以创建具有局部作用域的样式。 文档 ->

An application style solution that is similar to CSS modules and can create styles with local scope. Documentation ->

import { createStyles } from 'antd-style';

const useStyles = createStyles(({ token, css }) => ({
  container: css`
    background-color: ${token.colorBgLayout};
    padding: 24px;
  `,
}));

const App = () => {
  const { styles } = useStyles();

  return (
    <div className={styles.container}>
      <Space>
        <Button title={'功能按钮的说明'} icon={<SmileOutlined />} />
        操作按钮
      </Space>
    </div>
  );
};

除此之外，由于 antd-style 是 css-in-js based 。因此还有一些配套的 hooks: useTheme、useThemeMode、useResponsive 等，后续会在文档中阐释。

In addition, because antd-style is css-in-js based, there are also some related hooks: useTheme, useThemeMode, useResponsive, etc., which will be explained in the documentation later.

文档 Documentation ->

进展

2023.06.10

发布正式版

介绍文章：https://www.yuque.com/ant-design/ant-design/me6sc23d3thgysxt
知乎： https://zhuanlan.zhihu.com/p/636143897

2023.02.27 更新

欢迎使用 beta 验证（核心 API 已经稳定，边界场景的个别方法存在 Breaking Change 可能性）

Beta verification is welcome (the core API is stable, but some methods in boundary scenarios may have breaking changes).

npm i -S antd-style@beta

功能部分：当前已完成所有基础功能研发，同时 dog fooding 了文档站主题（Landing）。还需要做个性能的 benchmark。

文档部分：进度 90%，还缺三篇： stylish 和 babel 插件、SSR 集成。

落地验证部分：已在内部4个应用落地测试，待进一步在 Ant Design 官网和 Ant Design Pro 中验证。

后续增强计划：

• ssr 支持(https://ant-design-antd-style-preview-pr-19.surge.sh/guide/ssr)
• 基础 CSSinJS 库插装 (https://ant-design-antd-style-preview-pr-19.surge.sh/guide/styled)
• Babel 插件（className 定位、TreeShaking 优化）
• benchmark、缓存与性能优化（cssinjs-benchmark.arvinx.app）
• 微应用性能优化（待和 qiankun 讨论）

Functionality: All basic functionality has been developed and the documentation site theme has been dogfooded ( [Landing] (https://ant-design-antd-style-preview-pr-19.surge.sh/)). Performance benchmarking is still needed.

Documentation: 90% completed, still missing three articles: stylish and babel plugins, SSR integration.

Validation: Tested in four internal applications and further validation is needed on the Ant Design website and Ant Design Pro.

Future Enhancement Plan:

• SSR support (https://ant-design-antd-style-preview-pr-19.surge.sh/guide/ssr)
• Basic CSSinJS library plugin (https://ant-design-antd-style-preview-pr-19.surge.sh/guide/styled)
• Benchmarking, caching, and performance optimization (cssinjs-benchmark.arvinx.app)
• Babel Plugin（dev-className、TreeShaking）
• Microfrontend performance optimization (To be discussed with qiankun)

[jacob-lcs]

有个疑问，改成 antd-style 方案之后能够实现对样式代码 tree-shaking 吗

[arvinxx]

感觉如果要做 TreeShaking 可能需要在编译时搞了，比如用babel 识别使用的部分。然后没使用的话就移除？

[jacob-lcs]

嗯嗯，我觉得 css in js 的一大优势就是可以对样式代码进行 tree shaking，现有的 css module 开发方式中，引入一个 css 文件就会将文件中的所有代码打包，哪怕 jsx 代码中并没有使用

[jacob-lcs]

要做 tree shaking 的话我也认为是在编译时做

[arvinxx]

要做 tree shaking 的话我也认为是在编译时做

其实如果是用 styled-component 的那种写法。不用额外处理就能默认支持 TreeShaking。原因是每个样式块都是一个样式组件。没有引用就直接会被 tree-shaking。

但如果是 createStyles 这种写法，就需要做引用分析了，这个会有额外的工具成本在，用户可能需要多配一个 babel 插件才能实现。

[jacob-lcs]

是的，我觉得针对 antd-style 可以单独有一个 babel 插件解决 tree shaking 的问题，不然就是将其改成 webpack 能够默认处理的写法

[wkylin]

基于Antd5 自己实现了一个ProThemeProvider...
github: https://github.com/wkylin/pro-react-admin

[wood3n]

dumi 这个站点主题比以前好看多了 😆

[arvinxx]

用antd-style用自定义了一波~

[arvinxx]

主题站点单独抽了个包 ：dumi-theme-antd-style

[anuoua]

这个通过 jss-react 把 token 注入到 ThemeProvider 就可以做到，感觉不需要单独做这个了。

[arvinxx]

你想少了，建议看看文档再说

[anuoua]

可能是我没其他需求把，这种也算是最简单的应用级的利用 token 写 css 方式了。