tiny-vue_version0/examples/sites/demos/pc/webdoc/theme.md

15 KiB
Raw Permalink Blame History

主题配置

TinyVue 多主题采用的是 css 变量,并定义了一系列全局/组件的样式变量,你可以根据需求进行相应调整。

主题涉及到的变量,查看方式:

源码:basic-var.less

基础样式变量 npm 仓库路径:@opentiny/vue-theme/theme

使用预定义主题和动态切换主题

目前官方提供 4 套主题:

  • 默认主题
  • 无限主题 tinyInfinityTheme
  • 欧若拉主题 tinyAuroraTheme
  • XDesign 主题 tinySmbTheme

通过 alias 使用预定义主题【目前仅支持:欧若拉主题 和 XDesign 主题】

vue.config.js 定义

chainWebpack: (config) => {
  // XDesign 主题
  config.resolve.alias.set('@opentiny/vue-theme', '@opentiny/vue-theme/smb-theme')
  // aurora 主题 则是将以上smb主题中的'smb'字符全替换成 'aurora'即可
}

vite.config.js 定义

resolve: {
  alias: [
    // XDesign 主题
    {
      find: /\@opentiny\/vue-theme\/(?!(smb))/,
      replacement: '@opentiny/vue-theme/smb-theme/'
    }
  ]
}

主题初始化和动态切换主题的具体使用方式如下文所示,在 main.ts 文件中增加以下代码。

import TinyThemeTool from '@opentiny/vue-theme/theme-tool'

import { tinySmbTheme } from '@opentiny/vue-theme/theme'

// 导入主题

new TinyThemeTool(tinySmbTheme, 'tinyStyleSheetId') // 初始化主题

如果你需要动态切换主题,可以将主题实例对象 theme 挂载到 Vue 实例中,然后在需要切换主题的地方,调用 theme 对象的 changeTheme 方法。

在 main.ts 文件中增加以下代码:

const theme = new TinyThemeTool(tinySmbTheme, 'tinyStyleSheetId') // 初始化主题
app.config.globalProperties.theme = theme // 将 theme 对象挂到 vue 实例中

在需要切换主题的组件中调用 changeTheme 方法进行主题切换。

import { getCurrentInstance } from 'vue'
import { tinySmbTheme } from '@opentiny/vue-theme/theme'

const theme = getCurrentInstance().appContext.config.globalProperties.theme

const changeTheme = (value) => {
  theme.changeTheme(tinySmbTheme)
}

如果你需要自定义自己的主题,可以通过以下方式定义主题对象。

// 自定义主题数据格式要求
const tinyTestTheme = {
  id: 'tiny-test-theme', // 主题的唯一id每个主题必须唯一
  name: 'testTheme', // 主题的英文名称
  cnName: '测试主题', // 主题的中文名称
  data: { 'ti-base-color': '#f2f2f3' } //  主题数据
}

初始化主题或者切换主题时都可以使用该主题对象。

// 初始化主题
new TinyThemeTool(tinyTestTheme, 'tinyStyleSheetId')

// 切换主题
theme.changeTheme(tinyTestTheme)

配置 Design Config

有部分组件在不同主题下的图标或者交互不同,需要配置相应的 Design Config。

在 App.vue 文件中增加以下代码:

<script setup lang="ts">
  import { ConfigProvider } from '@opentiny/vue'
  import designSmbConfig from '@opentiny/vue-design-smb'
</script>

<template>
  <config-provider :design="designSmbConfig">
    <my-app></my-app>
  </config-provider>
</template>

主题定制高阶使用方法

在全局作用域下添加自定义 css 变量。

:root {
  --ti-base-color-white: #fefefe;
}

出于性能原因,更推荐你在类名下添加自定义 css 变量,而不是在全局的 :root 下。

.tiny-test-class {
  --ti-base-color-white: #fefefe;
}

如果你只想自定义一个特定的组件,只需为某些组件单独添加内联样式。

<tiny-button style="--ti-base-color-white: #fefefe">Button</tiny-button>

如果您想要通过 js 控制 css 变量,可以这样做:

const el = document.documentElement

// 获取 css 变量
getComputedStyle(el).getPropertyValue('--ti-base-color-white')
// 设置 css 变量
el.style.setProperty('--ti-base-color-white', '#fefefe')

主题变量规范化整改,主题配置变量实现新旧变量名替换

整改背景:由于 tiny-vue 要对接主题化配置系统,tiny-vue 组件库在 3.5.0 版本之后,自定义变量的名称发生了变化;

例如:--ti-base-color-selected-font-color 已整改为--ti-base-color-selected-text-color --ti-alert-radius 已整改为 --ti-alert-border-radius;

如果项目中使用了旧的 css 变量来调整样式,那么升级为 tiny-vue 新版本可能会无法生效,所以给出以下批量替换变量名的方法,解决新旧变量替换问题;使用步骤如下:

以替换项目中src目录下所有的旧变量名为例: 实现新旧变量名的替换

步骤一、点击下载新旧变量的映射表newVars.json和替换脚本replaceVar.js

newVars.json 文件replaceVar.js 文件

步骤二、将 newVars.jsonreplaceVar.js 放到项目根目录下,与 src 目录同级;



步骤三、在项目根目录下,执行以下命令进行替换;

node replaceVar.js

特殊情况:需手动替换的情况,如何查看哪些变量需要手动替换,细心往下看;

手动替换的背景:在映射表 newVars.json 中,key 是旧变量,value 是新变量;如果使用了类似于--ti-button-padding的旧变量,比较特殊,称为特殊变量;因为其拆分成了两个或以上的新变量,所以对应的 value 是一个数组,这种情况脚本无法自动化替换,需要自己手动替换;如何替换?

步骤一、取消 replaceVar.js 文件第 20 行注释,再重复以上步骤三;即可知道哪些地方的变量需要手动替换(末尾有附上特殊变量表)

// console.log('需要手动替换的文件路径是', statPath, '需要手动替换的变量是', key)

步骤二、根据打印的文件路径和变量,找到变量进行修改,大致有以下几种例子,可以覆盖所有需要手动替换的情况:

普通情况

例 1查特殊变量表可知类似于--ti-button-padding的旧变量拆分成了2个新变量,--ti-button-padding-vertical--ti-button-padding-horizontal,按字面意思,分别为垂直方向水平方向的 padding

若项目原来的样式是:padding: var(--ti-button-padding);需手动替换成:padding: var(--ti-button-padding-vertical) var(--ti-button-padding-horizontal);

例 2类似于--ti-pager-primary-color的旧变量拆分成了3个新变量,--ti-pager-primary-bg-color--ti-pager-primary-text-color--ti-pager-primary-border-color ,按字面意思,分别为背景颜色文本颜色边框颜色

若原来的样式是:--ti-pager-primary-colorred;需手动替换成:--ti-pager-primary-bg-color red; --ti-pager-primary-text-color: red; --ti-pager-primary-border-color: red;

特殊情况

例 3查特殊变量表可知: 类似于:含有border字段的旧变量,如果拆分成的新变量分别包含:border-weight边框厚度,border-style边框样式,border-color边框颜色,比如--ti-tabs-item-active-border拆成--ti-tabs-item-active-border-weight--ti-tabs-item-active-border-style--ti-tabs-item-active-border-color;

若原来的样式是--ti-tabs-item-active-border: 1px solid red;需手动替换成:--ti-tabs-item-active-border-weight: 1px; --ti-tabs-item-active-border-style: solid; --ti-tabs-item-active-border-color: red;

例 4类似于--ti-radio-button-checked-hover-color拆分成的变量中有包含box-shadow字段的,需要单独写box-shadow样式。

若原来的样式是:--ti-radio-button-checked-hover-colorred需手动替换成:--ti-radio-button-checked-hover-bg-colorred; --ti-radio-button-checked-hover-border-color: red; --ti-radio-button-checked-hover-box-shadow: -1px 0 0 0 red(box-shadow 的值像正常写样式一样,可以自定义)

最后附上特殊变量的映射表,newVars.json 里的特殊变量共有 48 个,如下所示;

{
  "--ti-button-padding": ["--ti-button-padding-vertical", "--ti-button-padding-horizontal"],
  "--ti-carousel-indicator-padding": [
    "--ti-carousel-indicator-padding-vertical",
    "--ti-carousel-indicator-padding-horizontal"
  ],
  "--ti-cascader-menu-list-padding": [
    "--ti-cascader-menu-list-padding-vertical",
    "--ti-cascader-menu-list-padding-horizontal"
  ],
  "--ti-cascader-node-disabled-color": [
    "--ti-cascader-node-disabled-text-color",
    "--ti-cascader-node-disabled-bg-color"
  ],
  "--ti-cascader-node-label-padding": [
    "--ti-cascader-node-label-padding-vertical",
    "--ti-cascader-node-label-padding-horizontal"
  ],
  "--ti-cascader-panel-node-label-padding": [
    "--ti-cascader-panel-node-label-padding-vertical",
    "--ti-cascader-panel-node-label-padding-right",
    "--ti-cascader-panel-node-label-padding-vertical",
    "--ti-cascader-panel-node-label-padding-left"
  ],
  "--ti-collapse-item-header-padding": [
    "--ti-collapse-item-header-padding-vertical",
    "--ti-collapse-item-header-padding-horizontal"
  ],
  "--ti-dialogbox-head-padding": [
    "--ti-dialogbox-head-padding-top",
    "--ti-dialogbox-head-padding-horizontal",
    "--ti-dialogbox-head-padding-bottom"
  ],
  "--ti-dialogbox-box-body-padding": [
    "--ti-dialogbox-box-body-padding-vertical",
    "--ti-dialogbox-box-body-padding-horizontal"
  ],
  "--ti-dropdown-menu-item-padding": [
    "--ti-dropdown-menu-item-padding-vertical",
    "--ti-dropdown-menu-item-padding-horizontal"
  ],
  "--ti-dropdown-menu-padding": ["--ti-dropdown-menu-padding-vertical", "--ti-dropdown-menu-padding-horizontal"],
  "--ti-fallmenu-slot-color": ["--ti-fallmenu-slot-text-color", "--ti-fallmenu-slot-bg-color"],
  "--ti-form-item-error-color": ["--ti-form-item-error-text-color", "--ti-form-item-error-border-color"],
  "--ti-table-td-padding": ["--ti-table-td-padding-vertical", "--ti-table-td-padding-horizontal"],
  "--ti-milestone-color": ["--ti-milestone-text-color", "--ti-milestone-bg-color"],
  "--ti-modal-header-padding": [
    "--ti-modal-header-padding-top",
    "--ti-modal-header-padding-horizontal",
    "--ti-modal-header-padding-bottom"
  ],
  "--ti-modal-body-padding": [
    "--ti-modal-body-padding-top",
    "--ti-modal-body-padding-horizontal",
    "--ti-modal-body-padding-bottom"
  ],
  "--ti-modal-footer-padding": [
    "--ti-modal-footer-padding-top",
    "--ti-modal-footer-padding-horizontal",
    "--ti-modal-footer-padding-bottom"
  ],
  "--ti-notify-info-background": ["--ti-notify-info-bg-color", "--ti-notify-bg-color"],
  "--ti-notify-title-margin": [
    "--ti-notify-title-margin-top",
    "--ti-notify-title-margin-horizontal",
    "--ti-notify-title-margin-bottom"
  ],
  "--ti-notify-message-margin": [
    "--ti-notify-message-margin-vertical",
    "--ti-notify-message-margin-right",
    "--ti-notify-message-margin-vertical",
    "--ti-notify-message-margin-left"
  ],
  "--ti-pager-primary-color": [
    "--ti-pager-primary-bg-color",
    "--ti-pager-primary-text-color",
    "--ti-pager-primary-border-color"
  ],
  "--ti-pager-list-padding": ["--ti-pager-poplist-item-padding-vertical", "--ti-pager-poplist-item-padding-horizontal"],
  "--ti-date-table-td-padding": ["--ti-date-table-td-padding-vertical", "--ti-date-table-td-padding-horizontal"],
  "--ti-time-panel-btn-padding": ["--ti-time-panel-btn-padding-vertical", "--ti-time-panel-btn-padding-horizontal"],
  "--ti-popover-placement-margin": [
    "--ti-popover-placement-margin-vertical",
    "--ti-popover-placement-margin-horizontal"
  ],
  "--ti-popover-padding": ["--ti-popover-padding-vertical", "--ti-popover-padding-horizontal"],
  "--ti-radio-input-checked-disabled-color": [
    "--ti-radio-input-checked-disabled-bg-color",
    "--ti-radio-input-checked-disabled-border-color"
  ],
  "--ti-radio-button-checked-normal-color": [
    "--ti-radio-button-checked-normal-bg-color",
    "--ti-radio-button-checked-normal-border-color",
    "--ti-radio-button-checked-normal-box-shadow"
  ],
  "--ti-radio-button-checked-hover-color": [
    "--ti-radio-button-checked-hover-bg-color",
    "--ti-radio-button-checked-hover-border-color",
    "--ti-radio-button-checked-hover-box-shadow"
  ],
  "--ti-search-inputinner-height": ["--ti-search-input-btn-width", "--ti-search-input-btn-line-height"],
  "--ti-select-dropdown-list-padding": [
    "--ti-select-dropdown-list-padding-top",
    "--ti-select-dropdown-list-padding-horizontal",
    "--ti-select-dropdown-list-padding-bottom"
  ],
  "--ti-select-dropdown-item-padding": [
    "--ti-select-dropdown-item-padding-vertical",
    "--ti-select-dropdown-item-padding-horizontal"
  ],
  "--ti-select-dropdown-line-margin": [
    "--ti-select-dropdown-line-margin-vertical",
    "--ti-select-dropdown-line-margin-horizontal"
  ],
  "--ti-slider-progress-box-middleline-normal": [
    "--ti-slider-progress-box-middleline-border-color",
    "--ti-slider-progress-box-middleline-icon-color"
  ],
  "--ti-slider-handle-color-hover": ["--ti-slider-handle-text-color-hover", "--ti-slider-handle-border-color-hover"],
  "--ti-slider-handle-margin": [
    "--ti-slider-handle-margin-top",
    "--ti-slider-handle-margin-horizontal",
    "--ti-slider-handle-margin-bottom"
  ],
  "--ti-slider-tips-bgcolor": ["--ti-slider-tips-bg-color", "--ti-slider-tips-border-color"],
  "--ti-slider-vertical-margin": [
    "--ti-slider-margin-vertical",
    "--ti-slider-margin-right",
    "--ti-slider-margin-vertical",
    "--ti-slider-margin-left"
  ],
  "--ti-split-trigger-size": [
    "--ti-split-trigger-size",
    "--ti-split-trigger-bar-margin-left",
    "--ti-split-trigger-bar-margin-top"
  ],
  "--ti-switch-checked-disabled-bgcolor": [
    "--ti-switch-checked-disabled-bg-color",
    "--ti-switch-checked-disabled-border-color"
  ],
  "--ti-switch-dot-size": ["--ti-switch-dot-size-height-width", "--ti-switch-dot-position-left"],
  "--ti-tabs-item-active-border": [
    "--ti-tabs-item-active-border-weight",
    "--ti-tabs-item-active-border-style",
    "--ti-tabs-item-active-border-color"
  ],
  "--ti-tabs-item-border-bottom": [
    "--ti-tabs-item-bottom-border-weight",
    "--ti-tabs-item-bottom-border-style",
    "--ti-tabs-item-bottom-border-color"
  ],
  "--ti-tabs-icon-close-margin": [
    "--ti-tabs-icon-close-margin-vertical",
    "--ti-tabs-icon-close-margin-right",
    "--ti-tabs-icon-close-margin-left"
  ],
  "--ti-tooltip-padding": ["--ti-tooltip-padding-vertical", "--ti-tooltip-padding-horizontal"],
  "--ti-upload-list-picture-card-item-bgcolor": [
    "--ti-upload-list-picture-card-item-bg-color",
    "--ti-upload-list-picture-card-item-text-color"
  ],
  "--ti-user-account-padding": ["--ti-user-account-padding-vertical", "--ti-user-account-padding-horizontal"]
}