[VUE] Custom theme styles and namespaces of ArcoDesign

Foreword

What is Arco Design?

Arco Design is a complete design and development solution front-end component library for enterprise-level products launched by ByteDance.

Official website address: https://arco.design/

It also provides a set of out-of-the-box middle and back-end front-end solutions: Arco Design Pro(https://pro.arco.design/)

The Arco Design style is based on the less technology stack, but it is also the same as the ElementPlus default theme. The CSS naming adopts the BEM style, which is convenient User override style.
The default namespace provided by Arco Design is empty. In special cases, we need to customize the namespace.

Official documentation:

【ArcoDesign | Custom theme】

The following demonstration is performed in on-demand import mode.

1. Environment

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

2. Directory structure

|- public
|- src
   #...
   |- styles # The new directory contains the following files
      |- arco
         |- index.less # Used for subsequent special style configuration entry for Arco Design
      |- base.less # for project global extensions
   #...
|- vite.config.ts # or vite.config.js

3. Less custom theme configuration

3.1. Install related dependencies

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

3.2, `arco/index.less`Configuration

The component library less style file can be imported into @arco-design/web-vue/dist/arco.less or @arco-design/web-vue/es/index.less
If you use the on-demand loading method to introduce components, make sure that the import of less style files is enabled in the on-demand loading plug-in.

/**
 * @file: src/styles/arco/index.less
 *
 * Global Token of the component library. You can view the built-in design variables and defaults of the component library here.
 * @link https://arco.design/vue/docs/token
 */
 
/* Set the main color */
@arcoblue-6: #165dff;

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

3.3, `base.less`Configuration

/**
 * Introduce arco less style
 */
@import (reference) "./arco/index.less";

3.4, `vite.config.[ts|js]`Configuration

You can choose one of the following options:

3.4.1, Plan 1

This solution requires @arco-plugins/vite-vue dependencies
The Vite plug-in officially provided by Arco performs on-demand loading and component library style configuration. The @arco-plugins/vite-vue plug-in will automatically load the component style.
@link “On-demand loading and component library themes (Arco plug-in)”

Dependencies

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

Configuration

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

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

    return defineConfig(viteConfig);
}

3.4.2, Plan 2

This solution requires unplugin-auto-import and unplugin-vue-components dependencies

Note:

This method will not handle components manually imported by users in scripts, such as Message components. Users still need to manually import the style files corresponding to the components, such as @arco-design/web-vue/es/message/style/ css.js.

Dependencies

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

Configuration

// ...
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: {<!-- -->
//Introduce `base.less`
hack: `true; @import (reference) "${<!-- -->path.resolve('./src/styles/base.less')}";`
},
javascriptEnabled: true,
}
            },
        },
        // ...
    };

    return defineConfig(viteConfig);
}

ok, now that the basic configuration is done, you can start customizing the required theme styles in arco/index.less

4. Custom namespace configuration

The Arco namespace is divided into three parts

css-vars-prefix prefix,
Default: empty

ClassName prefix (arco component style class naming prefix name,
Default:
)

Component prefix (the prefix name when calling the arco component,
Default: )

4.1 Set `css-vars-prefix`prefix

Based on the demo code of Step 3, add: @arco-vars-prefix variable

Complete style:

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

/* Set the main color */
@arcoblue-6: #165dff;

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

before fixing:

After modification:

4.2 Set `ClassName` prefix

Based on the demo code of Step 3, add: @prefix variable

Open the file: src/styles/arco/index.less, add @prefix variable settings:

@prefix: 'class-name-prefix';

/* Set the main color */
@arcoblue-6: #165dff;

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

Open the file: src/App.vue

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

before fixing:

After modification:

4.3 Set `Component` calling prefix

The following is implemented based on the officially provided Vite plug-in (@arco-plugins/vite-vue)

Open the file: vite.config.[ts|js]
Find the plugins configuration item:

// ...
plugins: [
    // ...
    vitePluginForArco({<!-- -->
        componentPrefix: "arco-ui", // Custom component prefix name
    })
],
// ...