@gravity-ui/uikit-themer ! (简体中文)

用于操作主题的库 @gravity-ui/uikit 图书馆。 允许您使用方便的 API 分析已有主题并生成新主题 .
特征
- 🎨 主题生成 - 为重力UI创建新主题
- 📖 主题解析 - 以CSS和JSON格式分析现有主题
- 🔄 改划 - 转换CSS和JSON格式
- 🎨 色彩管理 - 使用私人和公用事业的颜色
- ✍️ 类型 - 配置字体和文本样式
- 📏 边框 - 管理边界半径
安装
npm install @gravity-ui/uikit-themer
基本用途
主题生成
主题生成函数需要一个完整的主题对象. 为了方便,你可以使用 DEFAULT_THEME 并覆盖必要的参数.
⚠️ 说明: 当修改底色时, 使用 updateBaseColor 而不是直接操纵,以确保私人颜色得到适当的再生.
import { generateCSS, generateJSON, updateBaseColor, DEFAULT_THEME } from '@gravity-ui/uikit-themer';
// Recommended: Use updateBaseColor for modifying colors
const themeWithCustomColors = updateBaseColor({
theme: DEFAULT_THEME,
colorToken: 'brand',
value: {
dark: '#007AFF',
light: '#007AFF'
}
});
// Generate CSS theme
const cssTheme = generateCSS({
theme: themeWithCustomColors
});
// Generate JSON theme with typography changes
const jsonTheme = generateJSON({
theme: {
...DEFAULT_THEME,
typography: {
...DEFAULT_THEME.typography,
fontFamilies: {
...DEFAULT_THEME.typography.fontFamilies,
sans: {
mainFont: 'SF Pro Text',
fallbackFonts: ['Arial'],
},
}
}
}
});
分析已存在的主题
import { parseCSS, parseJSON } from '@gravity-ui/uikit-themer';
// Parse CSS theme to internal GravityTheme
const parsedCssTheme = parseCSS(cssString);
// Parse JSON theme to internal GravityTheme
const parsedJsonTheme = parseJSON(jsonString);
在格式之间转换
import { convertCSStoJSON, convertJSONtoCSS } from '@gravity-ui/uikit-themer';
// Convert CSS to JSON
const jsonFromCss = convertCSStoJSON(cssTheme);
// Convert JSON to CSS
const cssFromJson = convertJSONtoCSS(jsonTheme);
API 参考
默认主题
图书馆提供 DEFAULT_THEME 常数,包含一个完整的重力UI主题的所有默认值。 这是创建自定义主题的建议起点.
⚠️ 重要: 修改时 baseColors,使用 updateBaseColor 函数,而不是直接操作,以确保适当再生成私人颜色.
import { DEFAULT_THEME, updateBaseColor } from '@gravity-ui/uikit-themer';
import type { GravityTheme } from '@gravity-ui/uikit-themer';
// Recommended: Use updateBaseColor for base color changes
const customTheme: GravityTheme = updateBaseColor({
theme: DEFAULT_THEME,
colorToken: 'brand',
value: {
dark: '#FF3B30',
light: '#FF3B30'
}
});
// For other theme parts, direct modification is fine
const themeWithCustomTypography: GravityTheme = {
...customTheme,
typography: {
...customTheme.typography,
// typography modifications...
}
};
彩色公用事业
import {
isColorCssVariable,
isUtilityColorCssVariable,
isPrivateColorCssVariable,
parsePrivateColorCssVariable,
createPrivateColorCssVariable,
createUtilityColorCssVariable,
getUtilityColorTypeFromCssVariable,
updateBaseColor
} from '@gravity-ui/uikit-themer';
// Check CSS variable type
const isColor = isColorCssVariable('--g-color-base-brand');
const isUtility = isUtilityColorCssVariable('--g-color-text-primary');
const isPrivate = isPrivateColorCssVariable('--g-private-color-red-500');
// Parse private color variable
const {mainColorToken, privateColorToken} = parsePrivateColorCssVariable('--g-private-color-red-500');
// Create color variables
createPrivateColorCssVariable('brand', '200-solid') === '--g-color-private-brand-200-solid'
createUtilityColorCssVariable('text-link-visited') === '--g-color-text-link-visited'
// Get utility color type
getUtilityColorTypeFromCssVariable('--g-color-text-link-hover') === 'text-link-hover'
更新底色
⚠️ 重要: 总是使用 updateBaseColor 当修改底色以确保私人颜色的正确再生时.
import { updateBaseColor, DEFAULT_THEME } from '@gravity-ui/uikit-themer';
// Update base color for a single theme variant
const updatedTheme = updateBaseColor({
theme: DEFAULT_THEME,
colorToken: 'brand',
themeVariant: 'light',
value: '#007AFF',
});
// Update base color for both theme variants
const updatedBothThemes = updateBaseColor({
theme: DEFAULT_THEME,
colorToken: 'brand',
value: {
light: '#007AFF',
dark: '#0056CC',
},
});
// Create a new color token
const newColorTheme = updateBaseColor({
theme: DEFAULT_THEME,
colorToken: 'custom-accent',
value: {
light: '#FF6B35',
dark: '#FF8C5A',
},
});
这个 updateBaseColor 函数 :
- 更新基准颜色
baseColors - 自动再生相应的私有颜色
- 保持主题不可改变性( 返回新主题对象)
- 处理已有和新的颜色符号
- 支持同时更新单个主题变量或两个变量
为什么用 updateBaseColor? 吗?
直接修改 baseColors 不重生出私人色彩,会导致主题不一致. 私用颜色由底色来计算,并在整个UI组件中使用. 这个 updateBaseColor 函数确保:
- 适当更新了底色
- 使用新基色重新生成私有颜色
- 主题在内部保持不变
- 所有颜色依赖关系都得到维护
类型
使用字体和文字样式.
import {
isTextCssVariable,
isFontCssVariable,
createFontCssVariable,
createTextCssVariable,
getKeyFromCssFontVariable,
parseTextCssVariable,
generateCssFontFamily,
TEXT_VARIANTS,
TEXT_GROUP_PROPERTIES,
TEXT_VARIANT_PROPERTIES
} from '@gravity-ui/uikit-themer';
import type {
TypographyOptions,
TextGroup,
TextVariant,
FontOptions
} from '@gravity-ui/uikit-themer';
// Check typography CSS variables
const isText = isTextCssVariable('--g-text-body-1-font-size');
const isFont = isFontCssVariable('--g-font-family-sans');
// Create typography variables
createFontCssVariable('additional') === '--g-font-family-additional';
createTextCssVariable({
variant: 'body-1',
property: 'font-size'
}) === '--g-text-body-1-font-size'
// Utilities
getKeyFromCssFontVariable('--g-font-family-sans') === 'sans'
parseTextCssVariable('--g-text-body-1-font-size') === {
"group": "body",
"variant": "body-1",
"property": "font-size"
}
generateCssFontFamily({
"mainFont": "SF Pro Text",
"fallbackFonts": ["Arial", "sans-serif"]
}) === "'SF Pro Text', 'Arial', 'sans-serif'"
// Constants
console.log(TEXT_VARIANTS); // All available text variants
console.log(TEXT_GROUP_PROPERTIES); // Text group properties
console.log(TEXT_VARIANT_PROPERTIES); // Text variant properties
类型 :
TypographyOptions- 打印选项TextGroup- 文本组(机构、标题、显示等)TextVariant- 文本变体TextBodyVariant, (中文(简体) ),TextCaptionVariant, (中文(简体) ),TextHeaderVariant- 具体变体FontOptions- 字体选项
边框
以边界半径工作.
import {
isBorderRadiusCssVariable,
createBorderRadiusCssVariable,
BORDER_SIZES
} from '@gravity-ui/uikit-themer';
import type { BorderSize } from '@gravity-ui/uikit-themer';
// Check border radius variable
const isBorderRadius = isBorderRadiusCssVariable('--g-border-radius-m');
// Create border radius variable
const borderVar = createBorderRadiusCssVariable('m');
// Available border sizes
console.log(BORDER_SIZES); // ['xs', 's', 'm', 'l', 'xl']
与 JSON 主题合作
import {
generateJSON,
parseJSON,
isValueWithReference,
isThemizedValueWithReference
} from '@gravity-ui/uikit-themer';
import type {
JsonTheme,
ThemizedValueWithReference,
ValueWithReference
} from '@gravity-ui/uikit-themer';
// Check values with references
const hasRef = isValueWithReference(value);
const hasThemizedRef = isThemizedValueWithReference(value);
JSON类型:
JsonTheme- JSON代表主题ThemizedValueWithReference- 与实录参考值ValueWithReference- 参考值
核心类型
import type {
GravityTheme,
PrivateColorOptions,
PrivateColors,
BaseColors,
ThemizedColorOptions,
ColorOptions,
Theme
} from '@gravity-ui/uikit-themer';
GravityTheme- 主要内部重力UI主题类型PrivateColorOptions- 私人颜色选项PrivateColors- 私人颜色BaseColors- 基准颜色ThemizedColorOptions- 主题化颜色选项ColorOptions- 常规颜色选项Theme- 通用主题类型(light|dark(中文(简体) )
实例
创建自定义主题
import { generateCSS, updateBaseColor, DEFAULT_THEME } from '@gravity-ui/uikit-themer';
// Recommended: Use updateBaseColor to modify base colors
const themeWithCustomBrand = updateBaseColor({
theme: DEFAULT_THEME,
colorToken: 'brand',
value: {
dark: '#007AFF',
light: '#007AFF'
}
});
const customTheme = generateCSS({
theme: {
...themeWithCustomBrand,
typography: {
...themeWithCustomBrand.typography,
fontFamilies: {
...themeWithCustomBrand.typography.fontFamilies,
sans: {
mainFont: 'SF Pro Text',
fallbackFonts: ['Arial'],
},
},
variants: {
...themeWithCustomBrand.typography.variants,
'body-1': {
'font-size': '13px',
'line-height': '18px',
}
}
}
}
});
分析并修改已存在的主题
import { parseCSS, generateCSS, updateBaseColor } from '@gravity-ui/uikit-themer';
// Parse existing theme
const existingTheme = parseCSS(cssString);
// Recommended: Use updateBaseColor to modify brand color
const modifiedTheme = updateBaseColor({
theme: existingTheme,
colorToken: 'brand',
value: {
dark: '#FF3B30',
light: '#FF3B30'
}
});
// Generate new CSS
const newCSS = generateCSS({theme: modifiedTheme});
使用特定主题部件
import { generateCSS, DEFAULT_THEME } from '@gravity-ui/uikit-themer';
// Override only typography
const typographyOnlyTheme = generateCSS({
theme: {
...DEFAULT_THEME,
typography: {
...DEFAULT_THEME.typography,
fontFamilies: {
...DEFAULT_THEME.typography.fontFamilies,
'custom-font': {
mainFont: 'SF Pro Text',
fallbackFonts: ['Arial'],
},
},
groups: {
...DEFAULT_THEME.typography.groups,
body: {
'font-family': 'custom-font',
'font-weight': 400,
},
}
}
}
});