تخطَّ إلى المحتوى

رموز التصميم

الرمز (token) هو تمثيل لغة التصميم في متغيرات: تُسمَّى الألوان وأحجام الخطوط والمسافات وزوايا الاستدارة والظلال ومدد التحريك بمتغيرات CSS على الصيغة --lh-*، فيستهلك المكوّن الأسماء فقط دون كتابة القيم حرفيًا. وتبديل السمة هو تبديل الرموز.

الطبقة الموقع العدد وقت التقييم القابلية للتجاوز
متغيرات CSS · فاتح :root في styles/theme/common/var.scss 185 عنصرًا وقت التشغيل ✅ تجاوز حر
متغيرات CSS · داكن [data-theme='dark'], .dark في styles/theme/common/var-dark.scss 118 عنصرًا وقت التشغيل ✅
متغيرات SCSS styles/theme/common/variables.scss 183 متغيرًا وقت الترجمة ⚠️ لا يغيَّر إلا بتعديل المصدر وإعادة الترجمة

رموز الوضع الفاتح (var.scss)

Section titled “رموز الوضع الفاتح (var.scss)”
:root {
--lh-primary-color: #2B4C7C;
--lh-text-primary: rgba(0, 0, 0, 0.88);
--lh-bg-color: #FAF6F0;
--lh-border-color: #e5e6eb;
--lh-radius-base: 6px;
--lh-spacing-base: 8px;
// ... 185 عنصرًا
}

تجاوزات الوضع الداكن (var-dark.scss)

Section titled “تجاوزات الوضع الداكن (var-dark.scss)”
[data-theme='dark'],
.dark {
--lh-bg-color: #2A2520;
--lh-text-primary: #E8E0D8;
--lh-border-color: #3A3530;
// ... 118 عنصرًا
}

الوضع الداكن طبقة تجاوز لا مجموعة مستقلة: تُكتب الـ 118 عنصرًا التي تحتاج إلى الانقلاب فقط، ويُفرَض الباقي عن القيم الفاتحة.

$lh-primary-color: #2B4C7C !default;
$lh-border-radius-base: 6px !default;
// ... 183 متغيرًا

وظيفة متغيرات SCSS هي المشاركة في حسابات وقت الترجمة: مزج الألوان (mix() / shade())، وتركيب الظلال (جمع ظلال متعددة) — وهي أمور لا تقدر عليها متغيرات CSS. وثمن ذلك الخبز في وقت الترجمة — فلا تنقلب تلقائيًا في الوضع الداكن.

للرموز ثلاث درجات، أولاهما في ملف السمة العام والثالثة في نمط كل مكوّن:

// 1. متغيرات SCSS (variables.scss، وقت الترجمة)
$lh-primary: #2B4C7C !default;
$lh-text-primary: #2C2C2C !default;
// 2. متغيرات CSS العامة (:root في var.scss، 190 عنصرًا)
--lh-primary-color: #{$lh-primary};
--lh-text-primary: #{$lh-text-primary};
--lh-bg-color: #FAF6F0;
// 3. متغيرات على مستوى المكوّن (في scss المكوّن، نطاقها جذر BEM للمكوّن)
.lh-card {
--lh-card-bg: var(--lh-bg-color, #FAF6F0);
--lh-card-border-radius: calc(var(--lh-border-radius-base, 2px) + 2px);
}

الآليات الرئيسية:

  • بين الدرجتين 1 و2 إقحام في وقت الترجمة، لا سلسلة إشارة var(): تُخبَز قيمة --lh-primary-color من $lh-primary في وقت البناء، فلا فائدة من تغيير متغير SCSS في وقت التشغيل (بل تجب إعادة الترجمة). ولا توجد طبقة وسيطة «لوحة ألوان أساسية» في المشروع — فلا توجد متغيرات لسلالم الألوان مثل --lh-blue-6، وتُولَّد الرموز الدلالية مباشرةً من متغيرات SCSS.
  • نقطتا ارتكاز لتبديل السمة: تغيير متغيرات SCSS في variables.scss وإعادة الترجمة (يؤثر في كل الرموز الدلالية)، أو تجاوز متغيرات CSS على :root في وقت التشغيل (وهو طريق themeVars في ConfigProvider، يفعّل فورًا).
  • تشير الدرجة الثالثة افتراضيًا إلى الدرجة الثانية: تكون القيمة الافتراضية لمتغير المكوّن عادةً إشارة var() إلى الرمز العام (مع fallback)، فيحافظ على الارتباط مع السمة، ويتيح في الوقت نفسه تجاوز مكوّن واحد بشكل موجَّه عبر themeVars.

المجالات الدلالية الرئيسية (التقسيم الكامل في جدول الرموز أدناه):

المجال رموز نموذجية الاستخدام
اللون الرئيسي --lh-primary-color / -hover / -active / -bg / -border خماسية اللون الرئيسي للعلامة
النص --lh-text-primary / -secondary / -tertiary / -disabled أربع مستويات لطبقة النص
الخلفية --lh-bg-color / -page / -secondary / -overlay الصفحة / الحاوية / الغطاء
الحدود --lh-border-color / -light / -dark الإطارات
الحالات --lh-success-color / -warning / -error / -danger / -info خمسة ألوان دلالية
زاوية الاستدارة --lh-radius-small / -base / -large / -circle أربع درجات لزوايا الاستدارة
المسافات --lh-spacing-* مقياس على أساس 8px
حجم الخط --lh-font-size-* سُلَّم أحجام الخطوط
الظل --lh-shadow-* مستويات الظل
التحريك --lh-animation-duration-* / -timing-function إيقاع الانتقالات
الزخرفة --lh-decoration-color لون الزخرفة الصينية

主色与衍生语义

令牌明色暗色SCSS 源备注
--lh-primary-color #3D649E$lh-primary
--lh-primary-color-hover #5078AB$lh-primary-hover
--lh-primary-color-active #2B4C7C$lh-primary-active
--lh-primary-color-bg color-mix(in srgb, var(--lh-primary-color) 25%, transparent)$lh-primary-light
--lh-primary-color-border #2A3A4A$lh-primary-lighter
--lh-color-on-primary #fff$lh-on-primary

状态

令牌明色暗色SCSS 源备注
--lh-hover-bg-color rgba(255, 255, 255, 0.08)$lh-hover-bg
--lh-selected-color color-mix(in srgb, var(--lh-primary-color) 40%, #fff)—

功能色

令牌明色暗色SCSS 源备注
--lh-success-color #6FA36E$lh-success
--lh-success-color-hover #82B581$lh-success-hover
--lh-success-color-active #5B8C5A$lh-success-active
--lh-success-color-bg #1A2A1A$lh-success-light
--lh-warning-color #D4B76F$lh-warning
--lh-warning-color-hover #E0C680$lh-warning-hover
--lh-warning-color-active #C4A35A$lh-warning-active
--lh-warning-color-bg #2A251A$lh-warning-light
--lh-danger-color #C45050$lh-danger
--lh-danger-color-hover #D46060$lh-danger-hover
--lh-danger-color-active #B23A3A$lh-danger-active
--lh-danger-color-bg #2A1A1A$lh-danger-light
--lh-info-color #8F8F8F$lh-info
--lh-info-color-hover #A0A0A0$lh-info-hover
--lh-info-color-active #7A7A7A$lh-info-active
--lh-info-color-bg #1A1A1A$lh-info-light

国风装饰色

令牌明色暗色SCSS 源备注
--lh-gold-color #D4A843$lh-gold
--lh-gold-color-hover #E8C35C$lh-gold-hover
--lh-gold-color-active #B8860B$lh-gold-active
--lh-gold-color-bg #2A241A$lh-gold-light
--lh-gold-color-border #3A2E1A$lh-gold-lighter
--lh-vermilion-color #E85D4A$lh-vermilion
--lh-vermilion-color-hover #FF7B6B$lh-vermilion-hover
--lh-vermilion-color-active #C43A31$lh-vermilion-active
--lh-vermilion-color-bg #2A1A18$lh-vermilion-light
--lh-jade-color #7AAE7A$lh-jade
--lh-jade-color-hover #9CC89C$lh-jade-hover
--lh-jade-color-active #5B8C5A$lh-jade-active
--lh-jade-color-bg #1A2A1A$lh-jade-light
--lh-decoration-color rgba(212, 168, 67, 0.08)$lh-decoration-color

文本

令牌明色暗色SCSS 源备注
--lh-text-primary #E8E0D8$lh-text-primary
--lh-text-regular #C8C0B8$lh-text-regular
--lh-text-secondary #A09890$lh-text-secondary
--lh-text-placeholder #7A7270$lh-text-placeholder
--lh-text-disabled #5A5250$lh-text-disabled

边框

令牌明色暗色SCSS 源备注
--lh-border-color-base #3A3530$lh-border-color-base
--lh-border-color-light #302B28$lh-border-color-light
--lh-border-color-lighter #2A2520$lh-border-color-lighter
--lh-border-color-extra-light #242018$lh-border-color-extra-light

圆角

令牌明色暗色SCSS 源备注
--lh-border-radius-base 沿用明色$lh-border-radius-base
--lh-border-radius-small 沿用明色$lh-border-radius-small
--lh-border-radius-round 沿用明色$lh-border-radius-round
--lh-border-radius-circle 沿用明色$lh-border-radius-circle

背景

令牌明色暗色SCSS 源备注
--lh-bg-color #2A2520$lh-bg-color
--lh-bg-color-page #1E1A16$lh-bg-color-page
--lh-bg-color-disabled #242018$lh-bg-color-disabled
--lh-bg-color-overlay rgba(10, 8, 6, 0.7)$lh-bg-color-overlay

阴影

令牌明色暗色SCSS 源备注
--lh-box-shadow-base 0 2px 12px 0 rgba(0, 0, 0, 0.5)$lh-box-shadow-base
--lh-box-shadow-light 0 2px 4px 0 rgba(0, 0, 0, 0.4)$lh-box-shadow-light
--lh-box-shadow-lighter 0 0 4px 0 rgba(0, 0, 0, 0.3)$lh-box-shadow-lighter

字体

令牌明色暗色SCSS 源备注
--lh-font-family 沿用明色$lh-font-family
--lh-font-size-extra-large 沿用明色$lh-font-size-extra-large
--lh-font-size-large 沿用明色$lh-font-size-large
--lh-font-size-medium 沿用明色$lh-font-size-medium
--lh-font-size-base 沿用明色$lh-font-size-base
--lh-font-size-small 沿用明色$lh-font-size-small
--lh-font-size-extra-small 沿用明色$lh-font-size-extra-small
--lh-font-weight-primary 沿用明色$lh-font-weight-primary
--lh-font-weight-bold 沿用明色$lh-font-weight-bold
--lh-font-line-height-primary 沿用明色$lh-font-line-height-primary

组件级 · control

令牌明色暗色SCSS 源备注
--lh-control-height-mini 沿用明色$lh-control-height-mini
--lh-control-height-small 沿用明色$lh-control-height-small
--lh-control-height-medium 沿用明色$lh-control-height-medium
--lh-control-height-large 沿用明色$lh-control-height-large
--lh-control-height-x-large 沿用明色$lh-control-height-x-large

间距

令牌明色暗色SCSS 源备注
--lh-spacing-xs 沿用明色$lh-spacing-xs
--lh-spacing-sm 沿用明色$lh-spacing-sm
--lh-spacing-md 沿用明色$lh-spacing-md
--lh-spacing-base 沿用明色$lh-spacing-base
--lh-spacing-lg 沿用明色$lh-spacing-lg
--lh-spacing-xl 沿用明色$lh-spacing-xl
--lh-spacing-xxl 沿用明色$lh-spacing-xxl

层级

令牌明色暗色SCSS 源备注
--lh-z-index-normal 沿用明色$lh-z-index-normal
--lh-z-index-dropdown 沿用明色$lh-z-index-dropdown
--lh-z-index-sticky 沿用明色$lh-z-index-sticky
--lh-z-index-fixed 沿用明色$lh-z-index-fixed
--lh-z-index-modal-backdrop 沿用明色$lh-z-index-modal-backdrop
--lh-z-index-modal 沿用明色$lh-z-index-modal
--lh-z-index-popover 沿用明色$lh-z-index-popover
--lh-z-index-tooltip 沿用明色$lh-z-index-tooltip

过渡

令牌明色暗色SCSS 源备注
--lh-transition-duration-fast 沿用明色$lh-transition-duration-fast
--lh-transition-duration-base 沿用明色$lh-transition-duration-base
--lh-transition-duration-slow 沿用明色$lh-transition-duration-slow
--lh-transition-function-ease-in-out 沿用明色$lh-transition-function-ease-in-out

禁用态

令牌明色暗色SCSS 源备注
--lh-disabled-bg-color #242018$lh-disabled-bg-color
--lh-disabled-text-color #5A5250$lh-disabled-text-color
--lh-disabled-border-color #302B28$lh-disabled-border-color
--lh-disabled-opacity 0.5$lh-disabled-opacity

组件级 · popover

令牌明色暗色SCSS 源备注
--lh-popover-bg-color #2A2520$lh-popover-bg-color
--lh-popover-border-color #3A3530$lh-popover-border-color
--lh-popover-border-radius 沿用明色$lh-popover-border-radius
--lh-popover-padding 沿用明色$lh-popover-padding
--lh-popover-title-color #E8E0D8$lh-popover-title-color
--lh-popover-content-color #C8C0B8$lh-popover-content-color
--lh-popover-arrow-size 沿用明色$lh-popover-arrow-size

组件级 · popconfirm

令牌明色暗色SCSS 源备注
--lh-popconfirm-padding 沿用明色$lh-popconfirm-padding
--lh-popconfirm-icon-size 沿用明色$lh-popconfirm-icon-size

组件级 · drawer

令牌明色暗色SCSS 源备注
--lh-drawer-bg-color #2A2520$lh-drawer-bg-color
--lh-drawer-border-color #3A3530$lh-drawer-border-color
--lh-drawer-header-padding 沿用明色$lh-drawer-header-padding
--lh-drawer-body-padding 沿用明色$lh-drawer-body-padding
--lh-drawer-footer-padding 沿用明色$lh-drawer-footer-padding
--lh-drawer-title-color #E8E0D8$lh-drawer-title-color
--lh-drawer-close-size 沿用明色$lh-drawer-close-size

组件级 · dropdown

令牌明色暗色SCSS 源备注
--lh-dropdown-bg-color #2A2520$lh-dropdown-bg-color
--lh-dropdown-border-color #3A3530$lh-dropdown-border-color
--lh-dropdown-border-radius 沿用明色$lh-dropdown-border-radius
--lh-dropdown-padding 沿用明色$lh-dropdown-padding
--lh-dropdown-item-height 沿用明色$lh-dropdown-item-height
--lh-dropdown-item-padding 沿用明色$lh-dropdown-item-padding
--lh-dropdown-item-color #C8C0B8$lh-dropdown-item-color
--lh-dropdown-item-hover-bg-color var(--lh-hover-bg-color)$lh-dropdown-item-hover-bg-color
--lh-dropdown-divider-color #302B28$lh-dropdown-divider-color

组件级 · message

令牌明色暗色SCSS 源备注
--lh-message-bg #2A2520$lh-message-bg-color
--lh-message-border #3A3530$lh-message-border-color
--lh-message-color #C8C0B8$lh-message-content-color
--lh-message-shadow 沿用明色$lh-message-shadow

组件级 · notification

令牌明色暗色SCSS 源备注
--lh-notification-bg #2A2520$lh-notification-bg-color
--lh-notification-border #3A3530$lh-notification-border-color
--lh-notification-title-color #E8E0D8$lh-notification-title-color
--lh-notification-content-color #C8C0B8$lh-notification-content-color
--lh-notification-width 沿用明色$lh-notification-width
--lh-notification-gap 沿用明色$lh-notification-gap
--lh-notification-shadow 沿用明色$lh-notification-shadow

组件级 · loading

令牌明色暗色SCSS 源备注
--lh-loading-bg rgba(10, 8, 6, 62%)$lh-loading-bg-color
--lh-loading-text-color #C8C0B8$lh-loading-text-color

组件级 · timeline

令牌明色暗色SCSS 源备注
--lh-timeline-line #302B28$lh-timeline-line
--lh-timeline-dot var(--lh-info-color)$lh-timeline-dot
--lh-timeline-timestamp var(--lh-text-secondary)$lh-timeline-timestamp

组件级 · collapse

令牌明色暗色SCSS 源备注
--lh-collapse-border #302B28$lh-collapse-border

组件级 · rate

令牌明色暗色SCSS 源备注
--lh-rate-active var(--lh-warning-color)$lh-rate-active

组件级 · segmented

令牌明色暗色SCSS 源备注
--lh-segmented-bg #242018$lh-segmented-bg

组件级 · calendar

令牌明色暗色SCSS 源备注
--lh-calendar-border var(--lh-border-color-lighter)$lh-calendar-border

组件级 · affix

令牌明色暗色SCSS 源备注
--lh-affix-z-index 沿用明色$lh-affix-z-index

组件级 · backtop

令牌明色暗色SCSS 源备注
--lh-backtop-z-index 沿用明色$lh-backtop-z-index

组件级 · menu

令牌明色暗色SCSS 源备注
--lh-menu-bg #242018$lh-menu-bg
--lh-menu-padding 沿用明色$lh-menu-padding
--lh-menu-border #302B28$lh-menu-border
--lh-menu-height 沿用明色$lh-menu-height
--lh-menu-collapse-width 沿用明色$lh-menu-collapse-width
--lh-menu-item-height 沿用明色$lh-menu-item-height
--lh-menu-item-padding 沿用明色$lh-menu-item-padding
--lh-menu-item-color var(--lh-text-primary)$lh-menu-item-color
--lh-menu-item-hover-bg #302B28$lh-menu-item-hover-bg
--lh-menu-item-active-color var(--lh-selected-color)$lh-menu-item-active-color
--lh-menu-item-active-bg var(--lh-primary-color-bg)$lh-menu-item-active-bg
--lh-menu-arrow-color var(--lh-text-secondary)$lh-menu-arrow-color
--lh-menu-z-index 沿用明色$lh-menu-z-index

组件级 · table

令牌明色暗色SCSS 源备注
--lh-table-bg #242018$lh-table-bg
--lh-table-color var(--lh-text-regular)$lh-table-color
--lh-table-header-bg #2A2420$lh-table-header-bg
--lh-table-header-color var(--lh-text-primary)$lh-table-header-color
--lh-table-border #302B28$lh-table-border
--lh-table-row-hover-bg #2A2420$lh-table-row-hover-bg
--lh-table-stripe-bg color-mix(in srgb, var(--lh-bg-color-page) 60%, transparent)$lh-table-stripe-bg
--lh-table-cell-padding 沿用明色$lh-table-cell-padding

组件级 · layout

令牌明色暗色SCSS 源备注
--lh-layout-header-height 沿用明色$lh-layout-header-height
--lh-layout-header-bg #242018$lh-layout-header-bg
--lh-layout-aside-width 沿用明色$lh-layout-aside-width
--lh-layout-aside-bg #242018$lh-layout-aside-bg
--lh-layout-main-bg #1C1815$lh-layout-main-bg
--lh-layout-border #302B28$lh-layout-border

组件级 · row

令牌明色暗色SCSS 源备注
--lh-row-gutter 沿用明色$lh-row-gutter

组件级 · tree

令牌明色暗色SCSS 源备注
--lh-tree-color #D8D0C8$lh-tree-color
--lh-tree-padding 沿用明色$lh-tree-padding
--lh-tree-node-height 沿用明色$lh-tree-node-height
--lh-tree-node-hover-bg #2A2420$lh-tree-node-hover-bg
--lh-tree-node-selected-color var(--lh-selected-color)$lh-tree-node-selected-color
--lh-tree-node-selected-bg var(--lh-primary-color-bg)$lh-tree-node-selected-bg
--lh-tree-arrow-color var(--lh-text-secondary)$lh-tree-arrow-color

组件级 · transfer

令牌明色暗色SCSS 源备注
--lh-transfer-panel-width 沿用明色$lh-transfer-panel-width
--lh-transfer-panel-height 沿用明色$lh-transfer-panel-height
--lh-transfer-bg #242018$lh-transfer-bg
--lh-transfer-border #302B28$lh-transfer-border

组件级 · upload

令牌明色暗色SCSS 源备注
--lh-upload-bg #242018$lh-upload-bg
--lh-upload-border var(--lh-border-color-base)$lh-upload-border
--lh-upload-trigger-padding 沿用明色$lh-upload-trigger-padding

组件级 · anchor

令牌明色暗色SCSS 源备注
--lh-anchor-color var(--lh-text-regular)$lh-anchor-color

组件级 · image

令牌明色暗色SCSS 源备注
--lh-image-viewer-mask rgba(0, 0, 0, 80%)—

无障碍焦点环

令牌明色暗色SCSS 源备注
--lh-focus-color #7FA6D9$lh-primary
--lh-focus-ring-width 沿用明色—
--lh-focus-ring-offset 沿用明色—

(تُولَّد البيانات بواسطة scripts/gen-docs-data.mjs الذي يحلِّل ملفات الرموز الثلاثة، مع تأكيدات على الأعداد: 190 فاتحًا و118 داكنًا و188 SCSS، ويُخطئ عند عدم التطابق.)

في وقت التشغيل (موصى به)

Section titled “في وقت التشغيل (موصى به)”
// themeVars في ConfigProvider (تُضاف البادئة --lh- للمفاتيح المختصرة تلقائيًا)
<lh-config-provider :theme-vars="{ 'primary-color': '#1677ff' }">

أو كتابة CSS في مدخل التطبيق:

:root {
--lh-primary-color: #1677ff;
--lh-primary-color-hover: #4096ff;
--lh-primary-color-active: #0958d9;
}

لمزيد من التفاصيل انظر التخصيص في وقت التشغيل.

في وقت الترجمة (متغيرات SCSS)

Section titled “في وقت الترجمة (متغيرات SCSS)”
// في scss مدخل المشروع، يُتجاوز قبل @use
$lh-primary-color: #1677ff;
@use '@lh-ui/share/styles';

دلالة !default هي «لا يُكتب فوقه إذا كان له قيمة”، فالإسناد قبل @use يكفي. ملاحظة: يؤثر هذا في الجزء المخبوز في وقت الترجمة فقط، أما متغيرات CSS في وقت التشغيل فتحتاج إلى تجاوز منفصل.

الفجوات المعروفة في الرموز

Section titled “الفجوات المعروفة في الرموز”

لقد هبط «مشروع رموز الارتفاع» (إضافة --lh-control-height-mini/small/medium/large/x-large، وتحويل button / select / input-number / cascader / tree-select / date-picker / time-picker / input للاعتماد على الرموز، وتحويل input من الاشتقاق من padding إلى ارتفاع ثابت، وإصلاح padding-top غير المتماثل للحقول ذات العنوان padding-top: 16px، وإزاحة علامة الصح الثابتة في checkbox، وتكرار الترميز الجامد translate(-50%,-50%) في switch معًا). وما يزال معلقًا:

  1. عدم اتساق درجات الحجم بين spinner وicon (small 16 مقابل 14، medium 24 مقابل 16، إلخ). وتغيير أي جانب يمتد لكل المكتبة (message / notification / loading / جميع الأيقونات)، وشرط إطلاقه: شكوى بصرية حول خلط LhIcon / LhSpinner في المنفذ نفسه، وحينها يُفتح مشروع مستقل.
  2. درجات size غير موزونة: select / switch بثلاث درجات فقط، وضيِّق validator في date / time-picker، وtree-select / rate / segmented / pagination بلا size، و mini و x-large بالكاد رُسِما في طبقة CSS (x-large موجود فقط في avatar في المكتبة بأكملها). وهذا تغيير في طبقة API، مفكوك الارتباط مع رموز الارتفاع.
  • لا يُصرَّح للمكوّنات بتعريف --lh-* بأنفسها: لا تستهلك إلا عبر var(--lh-*, fallback) (خط أحمر في AGENTS.md الجذري). وتُضاف الرموز الجديدة في var.scss.
  • يجب كتابة fallback: var(--lh-primary-color, #1677ff) — فعند غياب الرمز تبقى قيمة افتراضية مقبولة، ويتولى حراسة ذلك البند الثاني من verify:styles (var fallback).
  • اكتمال الوضع الداكن: اسأل عند إضافة رمز «هل يجب أن ينقلب في الوضع الداكن؟»، فإن نعم فأضِف تجاوزًا في var-dark.scss، ويتولى حراسته البند السابع من verify:styles.
  • الرموز ذات القيم #{$lh-foo} مخبوزة في وقت الترجمة: لا تنقلب تلقائيًا في الوضع الداكن، ويجب إعادة توجيهها صراحةً (لمزيد من التفاصيل انظر الوضع الداكن).

Copyright © 2024-2026 FengMo WenXue