fusion
本文主要介绍在 icejs 项目中如何正确的引入 fusion 组件即 @alifd/next
。
#
使用 fusion 组件关于 fusion 组件按需引入的说明:
- 脚本代码按需引入:不推荐使用 babel-plugin-import,社区主流工具 Webpack/Vite 等都已支持 tree-shaking,构建时默认都会做按需的引入。
- 样式代码按需引入:结合社区讨论 issue,大多数场景下样式按需引入并无太大意义,反而会引入其他工程问题,因此推荐组件样式在项目级全量引入。
综合上述观点,我们不再推荐项目中使用 babel-plugin-import 做脚本按需引入以及样式自动&按需引入,而推荐全量引入组件样式 + 通过内置的 tree-shaking 进行脚本按需打包。
#
不需要定制组件主题在 src/global.css
中引入对应主题包的全量 CSS:
如果有用到
@icedesign/container
之类的 NPM 包,内部可能有一些不合理的语法导致样式重复引入影响构建速度,请结合 build-plugin-ignore-style 解决该问题。
#
使用 CSS Vars 定制主题fusion 组件通过 fusion.design 在线配置主题包,配置完成后会产生一个 npm 包,这里以 @alifd/theme-design-pro
这个主题包为例,首先通过 npm 安装主题包依赖:
接下来在 src/global.css
中引入对应主题包的全量 CSS:
#
使用 Sass 变量定制主题(不推荐)比如需要自定义 css-prefix 的场景,通过 CSS Vars 目前无法实现,此时推荐使用 Sass 方式定制。
在 build.json 中引入插件:
在 src/global.css
中引入组件全量的 sass:
#
按需引入组件样式(不推荐)在 build.json
中添加插件:
#
插件介绍#
Install在 build.json 中引入插件:
#
OptionsthemePackage
Fusion 组件主题包配置,如果设置为数组则启动多主题能力themeConfig
主题配置,通过设置 sass 变量对现有主题进行覆盖uniteBaseComponent
如果项目里依赖了多个不同名称的基础包,可以通过 uniteBaseComponent 来统一基础包,减少重复的代码importOptions
同babel-plugin-import
参数,默认为{ style: true, libraryDirectory: 'es'}
根据用户设置项将进行合并externalNext
配合externals
配置,将 Next 组件作为外部依赖引入usePx2Vw
配合 postcss 插件,将 css 样式单位 px 转化为 vw ,默认为 false 不开启, true 为开启px2vwOptions
传递参数给 postcss 插件,默认为{ viewportWidth: 750 }
根据用户设置项将进行合并componentOptions
值为对象,修改业务组件的引入路径,推荐用在 PC 跨 H5 的项目中,给业务组件指定 H5 的渲染组件enableColorNames
默认为false
,如果开启默认将提取transparent
、red
、blue
等色值名称themeConfig.nextPrefix
仅修改@alifd/next
里的 css-prefix,一般用于 0.x&1.x 共存的场景cssVariable
默认为false
,如果开启后将默认使用 css variables 的样式方案替换 sass 方案disableModularImport
禁用babel-plugin-import
按需加载能力,推荐引入全量样式,JS 将在压缩阶段通过tree-shaking
移除未使用组件
#
常见场景#
通过主题包定制组件样式ICE 脚手架中默认使用了 @alifd/theme-design-pro
这个主题包,如果不能满足需求则可以让设计师配置业务需要的主题包:配置组件主题样式 ,每个主题包对应一个 npm 包。
在 build.json
中配置主题包:
在配置主题包时,可以通过 iconfont 导入一些自定义的 icon,这些 icon 在项目代码里通过基础组件 Icon 即可使用:
#
业务代码支持主题切换在项目中也可以使用主题包的变量,这样未来如果需要更换主题,业务代码就不需要做任何改动了,可以使用的变量列表请参考 Fusion Design Tokens,使用方式如下:
#
配置 externals项目开发中希望将 @alifd/next
作为外部扩展不打包到 bundle 中,除了需要配置 externals
外,还需要将通过插件能力分析业务组件依赖中按需加载的 Next 组件:
#
修改 prefixfusion 组件的默认 class 前缀是 next-
,在微前端等场景下可能需要修改 prefix:
上面只是修改了 CSS 产物里的 prefix,同时还需要修改 js 里的 prefix 才能保证最终的一致性:
#
动态切换主题Vite 模式下不支持
build-plugin-fusion 结合 fusion 自身可以配置主题包的能力,支持多个主题包的配置,大大简化多主题切换的成本,通过 css 变量能力实现动态主题的切换,核心实现思路如下:
- 提取主题包中的 scss 变量(色值变量)
- 将 scss 变量具体内容转换为 css 变量,即
$color-brand1-1: #E2EDFF; => $color-brand1-1: var(--color-brand-1);
- 注入新的 scss 变量值(如
$color-brand1-1: var(--color-brand-1)
)进行编译 - 在 window 下注入
__changeTheme__
方法,实现不同主题包全局 css 变量声明的切换
通过数组的方式配置多个主题,实现多主题内容的注入。
build.json 中完成多主题包配置后,业务代码中可以直接调用 __changeTheme__
方法在多个主题包之间进行切换:
#
使用 css variables 样式在 build.json
中开启 cssVariable
配置:
开启后 css 样式中用可以使用如下 css variables 变量:
使用须知:
如果开启 cssVariable
主题包需要为新版主题包,即需要包含 variable.css 文件(文件内定义 css variables 变量)。不符合要求的主题包,在 fusion 官网生成最新版本主题包即可。
该属性在 build-plugin-fusion 0.1.14 版本以上开始支持
#
跨端用法#
API- 增加
componentOptions
API,该接口值为对象,可接受bizComponent
customPath
componentMap
等参数 - 增加
usePx2Vw
API,跨端模式下请开启
#
componentOptions 详解用来自定义业务组件的引用路径及入口
#
bizComponent 需要自定义路径的组件类型为数组,与 customPath
共同作用生效
bizComponent: ['@alifd/anchor', '@alifd/pro-components']
customPath: '/es/mobile'
#
customPath 自定义的路径结合 bizComponent
一起生效,用法参考 bizComponent
文档。
#
componentMap 组件路径映射类型为对象,表示路径映射的 mapping ,若与 bizComponent
冲突,则以 componentMap
为优先