TDesign CSS變量說(shuō)明文檔

概述

--td-font-body-medium 等CSS變量是TDesign設計系統提供的預定義樣式變量，用于保持整個(gè)項目的設計一致性。

CSS變量定義位置

主要定義文件

node_modules/tdesign-vue-next/es/style/index.css

這個(gè)文件包含了TDesign所有的CSS變量定義，在項目中通過(guò)以下方式引入：

// main.ts 或 vite.config.ts 中
import 'tdesign-vue-next/es/style/index.css'

字體相關(guān)CSS變量

1. 字體家族變量

:root {
  --td-font-family: PingFang SC, Microsoft YaHei, Arial Regular;
  --td-font-family-medium: PingFang SC, Microsoft YaHei, Arial Medium;
}

2. 字體大小變量

:root {
  /* 鏈接字體大小 */
  --td-font-size-link-small: 12px;
  --td-font-size-link-medium: 14px;
  --td-font-size-link-large: 16px;
  
  /* 正文字體大小 */
  --td-font-size-body-small: 12px;
  --td-font-size-body-medium: 14px;
  --td-font-size-body-large: 16px;
  
  /* 標題字體大小 */
  --td-font-size-title-small: 14px;
  --td-font-size-title-medium: 16px;
  --td-font-size-title-large: 18px;
  --td-font-size-title-extraLarge: 20px;
  
  /* 大標題字體大小 */
  --td-font-size-headline-small: 24px;
  --td-font-size-headline-medium: 28px;
  --td-font-size-headline-large: 36px;
  
  /* 展示字體大小 */
  --td-font-size-display-medium: 48px;
  --td-font-size-display-large: 64px;
}

3. 行高變量

:root {
  --td-line-height-link-small: 20px;
  --td-line-height-link-medium: 22px;
  --td-line-height-link-large: 24px;
  --td-line-height-body-small: 20px;
  --td-line-height-body-medium: 22px;
  --td-line-height-body-large: 24px;
  /* ... 更多行高變量 */
}

4. 組合字體變量（重點(diǎn)）

這些是最常用的字體變量，包含了字體大小、行高和字體家族的完整定義：

:root {
  /* 鏈接字體 */
  --td-font-link-small: var(--td-font-size-link-small) / var(--td-line-height-link-small) var(--td-font-family);
  --td-font-link-medium: var(--td-font-size-link-medium) / var(--td-line-height-link-medium) var(--td-font-family);
  --td-font-link-large: var(--td-font-size-link-large) / var(--td-line-height-link-large) var(--td-font-family);
  
  /* 正文字體 */
  --td-font-body-small: var(--td-font-size-body-small) / var(--td-line-height-body-small) var(--td-font-family);
  --td-font-body-medium: var(--td-font-size-body-medium) / var(--td-line-height-body-medium) var(--td-font-family);
  --td-font-body-large: var(--td-font-size-body-large) / var(--td-line-height-body-large) var(--td-font-family);
  
  /* 標題字體 */
  --td-font-title-small: 600 var(--td-font-size-title-small) / var(--td-line-height-title-small) var(--td-font-family);
  --td-font-title-medium: 600 var(--td-font-size-title-medium) / var(--td-line-height-title-medium) var(--td-font-family);
  --td-font-title-large: 600 var(--td-font-size-title-large) / var(--td-line-height-title-large) var(--td-font-family);
  --td-font-title-extraLarge: 600 var(--td-font-size-title-extraLarge) / var(--td-line-height-title-extraLarge) var(--td-font-family);
  
  /* 大標題字體 */
  --td-font-headline-small: 600 var(--td-font-size-headline-small) / var(--td-line-height-headline-small) var(--td-font-family);
  --td-font-headline-medium: 600 var(--td-font-size-headline-medium) / var(--td-line-height-headline-medium) var(--td-font-family);
  --td-font-headline-large: 600 var(--td-font-size-headline-large) / var(--td-line-height-headline-large) var(--td-font-family);
  
  /* 展示字體 */
  --td-font-display-medium: 600 var(--td-font-size-display-medium) / var(--td-line-height-display-medium) var(--td-font-family);
  --td-font-display-large: 600 var(--td-font-size-display-large) / var(--td-line-height-display-large) var(--td-font-family);
}

具體的 --td-font-body-medium 解析

--td-font-body-medium: var(--td-font-size-body-medium) / var(--td-line-height-body-medium) var(--td-font-family);

展開(kāi)后等價(jià)于：

--td-font-body-medium: 14px / 22px PingFang SC, Microsoft YaHei, Arial Regular;

這意味著(zhù)：

• 字體大小: 14px
• 行高: 22px
• 字體家族: PingFang SC, Microsoft YaHei, Arial Regular

顏色相關(guān)CSS變量

1. 文字顏色變量

:root {
  /* 淺色主題 */
  --td-font-gray-1: rgba(0, 0, 0, 0.9);     /* 主要文字 */
  --td-font-gray-2: rgba(0, 0, 0, 0.6);     /* 次要文字 */
  --td-font-gray-3: rgba(0, 0, 0, 0.4);     /* 占位符文字 */
  --td-font-gray-4: rgba(0, 0, 0, 0.26);    /* 禁用文字 */
  
  /* 深色主題 */
  --td-font-white-1: rgba(255, 255, 255, 0.9);   /* 主要文字 */
  --td-font-white-2: rgba(255, 255, 255, 0.55);  /* 次要文字 */
  --td-font-white-3: rgba(255, 255, 255, 0.35);  /* 占位符文字 */
  --td-font-white-4: rgba(255, 255, 255, 0.22);  /* 禁用文字 */
}

2. 語(yǔ)義化文字顏色

:root {
  --td-text-color-primary: var(--td-font-gray-1);
  --td-text-color-secondary: var(--td-font-gray-2);
  --td-text-color-placeholder: var(--td-font-gray-3);
  --td-text-color-disabled: var(--td-font-gray-4);
  --td-text-color-anti: #fff;
  --td-text-color-brand: var(--td-brand-color-7);
  --td-text-color-link: var(--td-brand-color-7);
}

其他常用CSS變量

1. 品牌色變量

:root {
  --td-brand-color-1: #f2f3ff;
  --td-brand-color-2: #d9e1ff;
  --td-brand-color-3: #b5c7ff;
  --td-brand-color-4: #8eabff;
  --td-brand-color-5: #618dff;
  --td-brand-color-6: #366ef4;
  --td-brand-color-7: #0052d9;  /* 主品牌色 */
  --td-brand-color-8: #003cab;
  --td-brand-color: var(--td-brand-color-7);
}

2. 間距變量

:root {
  --td-comp-margin-s: 8px;
  --td-comp-margin-m: 16px;
  --td-comp-margin-l: 24px;
  --td-comp-margin-xl: 32px;
  --td-comp-margin-xxl: 40px;
  --td-comp-margin-xxxl: 48px;
  
  --td-comp-paddingTB-xxl: 40px;
  --td-comp-paddingLR-xxl: 40px;
}

3. 背景色變量

:root {
  --td-bg-color-page: #f5f5f5;
  --td-bg-color-container: #fff;
  --td-bg-color-container-hover: #f8f8f8;
  --td-bg-color-container-active: #f0f0f0;
  --td-bg-color-component: #fff;
  --td-bg-color-component-hover: #f8f8f8;
  --td-bg-color-component-disabled: #f5f5f5;
}

在項目中的使用方法

1. 在Less/CSS文件中使用

// src/pages/login/index.less
.login-tip {
  font: var(--td-font-body-medium);
  color: var(--td-text-color-secondary);
  margin: var(--td-comp-margin-l);
}

.login-title {
  font: var(--td-font-headline-large);
  color: var(--td-text-color-primary);
}

2. 在Vue組件中使用

<template>
  <div class="custom-text">自定義文本</div>
</template>

<style scoped>
.custom-text {
  font: var(--td-font-body-medium);
  color: var(--td-brand-color);
}
</style>

3. 動(dòng)態(tài)使用CSS變量

<template>
  <div :style="{ font: 'var(--td-font-title-large)', color: 'var(--td-brand-color)' }">
    動(dòng)態(tài)樣式文本
  </div>
</template>

自定義CSS變量

1. 覆蓋默認變量

/* 在你的全局樣式文件中 */
:root {
  --td-font-family: 'Custom Font', PingFang SC, Microsoft YaHei, Arial;
  --td-brand-color-7: #your-brand-color;
}

2. 添加自定義變量

:root {
  --my-custom-font: 16px / 24px var(--td-font-family);
  --my-custom-color: #your-color;
}

主題切換

TDesign支持明暗主題切換，相關(guān)變量會(huì )自動(dòng)適配：

/* 淺色主題 */
:root,
:root[theme-mode="light"] {
  --td-text-color-primary: var(--td-font-gray-1);
}

/* 深色主題 */
:root[theme-mode="dark"] {
  --td-text-color-primary: var(--td-font-white-1);
}

常見(jiàn)問(wèn)題

1. 變量不生效

原因: 可能沒(méi)有正確引入TDesign的樣式文件 解決: 確保在main.ts中引入了樣式：

import 'tdesign-vue-next/es/style/index.css'

2. 自定義變量覆蓋無(wú)效

原因: CSS優(yōu)先級問(wèn)題 解決: 確保自定義變量在TDesign樣式之后引入

3. 在打包后變量丟失

原因: 構建工具可能移除了未使用的CSS 解決: 檢查構建配置，確保CSS變量被正確處理

參考資源

• TDesign 設計令牌文檔
• TDesign Vue Next 官方文檔
• CSS 自定義屬性 (變量) - MDN

最后更新: 2025/10/2