【VUE】ArcoDesign之自定义主题样式和命名空间

前言

Arco Design是什么？

Arco Design 是由字节跳动推出的企业级产品的完整设计和开发解决方案前端组件库

• 官网地址：https://arco.design/
• 同时也提供了一套开箱即用的中后台前端解决方案：Arco Design Pro(https://pro.arco.design/)

Arco Design样式基于less技术栈，但也同ElementPlus默认主题，CSS 命名采用 BEM风格，方便使用者覆盖样式。
Arco Design 提供的默认命名空间为是空的。 在特殊情况下，我们需要自定义命名空间。

官方文档：

• 【ArcoDesign | 自定义主题】

---

以下演示按照按需导入模式下进行

1、环境

• vue： ^3.3.4
• vite：^4.4.11
• @arco-design/web-vue： ^2.52.1
• @arco-plugins/vite-vue：^1.4.5

2、目录结构

|- public
|- src
   # ...
   |- styles # 新增目录包含以下文件
      |- arco
         |- index.less # 用于后续对Arco Design的专门样式配置入口
      |- base.less # 用于项目全局的扩展
   # ...
|- vite.config.ts # or vite.config.js

3、Less自定义主题配置

3.1、安装相关依赖

npm install -D less
# or
yarn add -D less
# or
pnpm add -D less

3.2、arco/index.less配置

• 组件库 less 样式文件可以引入 @arco-design/web-vue/dist/arco.less 或者 @arco-design/web-vue/es/index.less
• 如果使用了按需加载的方式引入组件，请确保在按需加载插件中开启了 less 样式文件的导入。

/**
 * @file: src/styles/arco/index.less
 * 
 * 组件库的全局 Token，可以在此查看组件库内置的设计变量以及默认
 * @link https://arco.design/vue/docs/token
 */
 
/* 设置主色调 */
@arcoblue-6: #165dff;

/* 引入arco less库 */
@import "@arco-design/web-vue/es/index.less";

3.3、base.less配置

/**
 * 引入arco less样式
 */
@import (reference) "./arco/index.less";

3.4、vite.config.[ts|js]配置

以下方案二选一即可

3.4.1、方案一

该方案需要@arco-plugins/vite-vue依赖
由Arco 官方提供的 Vite 插件进行按需加载和组件库样式配置，@arco-plugins/vite-vue 插件会自动加载组件样式
@link 《按需加载与组件库主题（Arco 插件）》

依赖

npm install -D @arco-plugins/vite-vue
# or
yarn add -D @arco-plugins/vite-vue
# or
pnpm add -D @arco-plugins/vite-vue

配置

// ...
import path from 'node:path';
import {vitePluginForArco} from '@arco-plugins/vite-vue'
// ...

export default ()=>{
    const viteConfig:UserConfig = {
        // ...
        plugins: [
            // ...
            vitePluginForArco({})
        ],
        // ...
        css: {
            preprocessorOptions: {
                less: {
	                modifyVars: {
	                    // 引入`base.less`
	                    hack: `true; @import (reference) "${path.resolve('./src/styles/base.less')}";`
	                },
	                javascriptEnabled: true,
	            }
            },
        },
        // ...
    };

    return defineConfig(viteConfig);
}

3.4.2、方案二

该方案需要unplugin-auto-import、unplugin-vue-components依赖

注意：

这种方法并不会处理用户在 script 中手动导入的组件，比如 Message 组件，用户仍需要手动导入组件对应的样式文件，例如 @arco-design/web-vue/es/message/style/css.js。

依赖

npm install -D unplugin-auto-import unplugin-vue-components
# or
yarn add -D unplugin-auto-import unplugin-vue-components
# or
pnpm add -D unplugin-auto-import unplugin-vue-components

配置

// ...
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite';
import { ArcoResolver } from 'unplugin-vue-components/resolvers';
// ...

export default ()=>{
    const viteConfig:UserConfig = {
        // ...
        plugins: [
            // ...
            AutoImport({
		      resolvers: [ArcoResolver()],
		    }),
		    Components({
		      resolvers: [
		        ArcoResolver({
		          sideEffect: true
		        })
		      ]
		    })
        ],
        // ...
        css: {
            preprocessorOptions: {
                less: {
	                modifyVars: {
	                    // 引入`base.less`
	                    hack: `true; @import (reference) "${path.resolve('./src/styles/base.less')}";`
	                },
	                javascriptEnabled: true,
	            }
            },
        },
        // ...
    };

    return defineConfig(viteConfig);
}

ok，至此基本配置搞定，可以开始在arco/index.less中自定义需要的主题样式了

4、自定义命名空间配置

命名空间Arco划分为三个部分

• css-vars-prefix前缀，
  默认：空
• ClassName前缀 (arco组件样式class命名前缀名称，
  默认：<div class="arco-${componentName}"/>)
• Component前缀 (arco组件调用时的前缀名称，
  默认：<a-${componentName} />)

4.1 设置css-vars-prefix前缀

步骤三的demo代码基础上加上：@arco-vars-prefix变量

完整样式：

/**
 * @file src/styles/arco/index.less
 */
@arco-vars-prefix: 'css-vars-prefix-name';

/* 设置主色调 */
@arcoblue-6: #165dff;

@import "@arco-design/web-vue/es/index.less";

---

修改前：

修改后：

4.2 设置ClassName前缀

步骤三的demo代码基础上加上：@prefix变量

打开文件：src/styles/arco/index.less,增加@prefix变量设置：

@prefix: 'class-name-prefix';

/* 设置主色调 */
@arcoblue-6: #165dff;

@import "@arco-design/web-vue/es/index.less";

打开文件：src/App.vue

<!-- App.vue -->
<template>
  <a-config-provider prefix-cls="class-name-prefix">
    <!-- ... -->
  </a-config-provider>
</template>

---

修改前：

修改后：

4.3 设置 Component调用前缀

以下基于官方提供的 Vite 插件(@arco-plugins/vite-vue)实现

打开文件：vite.config.[ts|js]
找到plugins配置项：

// ...
plugins: [
    // ...
    vitePluginForArco({
        componentPrefix: "arco-ui", // 自定义组件前缀名称
    })
],
// ...

修改前：

修改后：