Colorfully
使用 Colorfully 来定义你的界面主题吧!
✨特性
Colorfully 的核心功能就是使用 JavaScript 控制 CSS Variable 以及 HTML Attrbute,来达到动态主题的效果。
强大:局部主题灵活:编程式创建、动态导入导出配置激发:自定义主题包友好:TypeScript 类型支持、CSS Variable 智能提示迅速:快速接入主流组件库、脚手架快速创建主题包包容:小程序支持、自定义渲染
安装
npm i colorfully
使用
Colorfully 的使用方式有很多种,这也使得它足以支撑大多数应用场景的原因。
初始化
初始化创建主题,具有更好的类型支持。
你可以使用它:自定义主题包。
创建样式
首先我们创建一个色彩样式,同时定义其下样式类型以及样式变量。
import { CSSStyle } from 'colorfully';
export const color = new CSSStyle('色彩', 'color', {
light: {
name: '浅色',
code: 'light',
variables: {
'--color-1': {
name: '',
code: '--color-1',
value: '#e6fffb'
},
'--color-2': {
name: '',
code: '--color-2',
value: '#b5f5ec'
},
...{ /* more */}
}
},
dark: {
name: '深色',
code: 'dark',
variables: {
'--color-1': {
name: '',
code: '--color-1',
value: '#112123'
},
'--color-2': {
name: '',
code: '--color-2',
value: '#113536'
},
...{ /* more */}
}
}
})
你还可以创建更多,如:shadow 、space、…
统一导出样式
import { CSSStyle } from 'colorfully';
import { color } from './color';
import { shadow } from './shadow';
import { space } from './space';
export const defaultStyleMap = { color, space, shadow };
如果你想在创建方案时有更友好的提示,你可以这样做:
export type DefaultStyleMap
[K in keyof T]: T[K] extends CSSStyle
};
创建方案
接下来我们创建一个主题方案:
import { DefaultStyleMap } from '../style';
import { CSSSchema } from 'colorfully';
export const lightSchema = new CSSSchema
color: 'light',
shadow: 'default',
space: 'default'
});
你还可以创建更多,如:darkSchema 、defaultSchema、…
统一导出方案
import { defaultSchema } from './default';
import { darkSchema } from './dark';
import { lightSchema } from './light';
export const defaultSchemaMap = { default: defaultSchema, dark: darkSchema, light: lightSchema };
实例化
创建好了主题和方案之后,我们就可以去实例化 Colorfully 类了。
import { Colorfully } from 'colorfully';
import { defaultStyleMap } from './style';
import { defaultSchemaMap } from './schema';
const theme = new Colorfully({ styleMap: defaultStyleMap, schemaMap: defaultSchemaMap });
导出实例化类
实例化后便可以导出使用了。
export default theme;
同时你也可以导出主题类型:
export type ThemeType = typeof theme;
它可以在你只需要类型提示时使用。
到现在为止,你就拥有了初始化创建主题,它具有良好的开发类型提示,这使你在使用 theme.schema API 时具有良好的类型提示。
编程式
使用编程式 API 创建主题,具有更好的可编程性。
你可以使用它:动态创建方案、动态创建样式、动态修改变量、…
甚至还可以将主题的控制权交给用户。
实例化
与初始化创建不同的是,编程式创建需要先进行 Colorfully 的实例化。
const theme = new Colorfully();
导出实例化类
将实例化类进行导出。
export default theme
创建样式
同样的我们以色彩样式示例:
import theme from "./theme";
theme.style.create('色彩', 'color', {
light: {
name: '浅色',
code: 'light',
variables: {
'--color-1': {
name: '',
code: '--color-1',
value: '#e6fffb'
},
'--color-2': {
name: '',
code: '--color-2',
value: '#b5f5ec'
},
...{ /* more */}
}
},
dark: {
name: '深色',
code: 'dark',
variables: {
'--color-1': {
name: '',
code: '--color-1',
value: '#112123'
},
'--color-2': {
name: '',
code: '--color-2',
value: '#113536'
},
...{ /* more */}
}
}
})
同样的,你还可以创建更多,如:shadow 、space、…
创建方案
接下来使用 API 创建一个方案:
import theme from "./theme";
theme.schema.create('浅色主题', 'light', { color: 'light', shadow: 'default', space: 'default' });
你还可以创建更多,如:darkSchema 、defaultSchema、…
配置化
与其他使用方案不同的是,在配置化中,你可以很灵活的自由导出导出主题配置。
你可以用它实现:远程加载主题、动态导入主题、主题分享、…
实例化
同样与初始化创建不同的是,配置化创建需要先进行 Colorfully 的实例化。
const theme = new Colorfully();
导出实例化类
将实例化类进行导出。
export default theme
导入配置(创建样式及方案)
使用 theme.import API 可以统一导入样式及方案。
import theme from "./theme";
const config: ColorfullyConfig = {
styles: [
{
name: '色彩',
code: 'color',
types: [
{
name: '浅色',
code: 'light',
variables: [{ name: '', code: '--color-1', value: '#e6fffb' }]
}
/* ... */
]
}
/* ... */
],
schemas: [
{ name: '浅色主题', code: 'light', map: { color: 'light', shadow: 'default', space: 'default' } }
/* ... */
]
};
theme.import(config);
导出配置
使用 theme.export API 可以统一导出样式及方案。
import theme from "./theme";
const config = theme.export()
引入使用
在使用主题时你可以使用 theme.use 方法指定主题方案。
import { theme } from "./theme"
theme.use('default')
使用参数
如果你在 new Colorfully 时未传入 UseParams 或你使用的是主题包时,可以使用 theme.updateDefaultUseParams 更新你的 UseParams。
UseParams 具体参数如下:
/**
* 使用参数
*/
export interface UseParams
/**
* 主题根节点
* @default html
* @description 也是选择器的挂载点。
*/
root?: HTMLElement;
/**
* 模式
* @default "css"
* @description ‘css’ 模式也就是 'all in' 所有 css 都会提前生成挂载,'js' 模式也就是 'Import on demand' 所有的 css 都会被 js 按需导入。
*/
mode?: 'css' | 'js';
/**
* 选择器模式
* @description 决定挂载器是属性模式还是类名模式。
*/
selectorMode?: 'attr' | 'class';
/**
* 自定义挂载
* @description 对不支持 dom 操作的情况提供自定义渲染支持。
*/
customMount?: {
/**
* 选择器
* @param themeMap { groupCode: typeCode }
*/
selector: (themeMap: Record
/**
* 样式
* @param styleList 样式列表
*/
style: (styleList: {
code: string;
css: string;
/**
* mode === 'js' 时才会有
*/
variables?: Array
}[],
/**
* mode === 'js' 时才会有
*/
styleMap?: ExtractVariableMap
};
}
通过上述属性达到更高的兼容性以及扩展性。
场景
接下来给出不同场景下的,解决方案。
对接组件库
Q:在我们的日常开发中,避免不了使用各式各样的组件库,那么我们如何快速接入呢?
A:因为设计原因,我们的选择器优先级大于大部分组件库的声明选择器,所以我们可以直接对接组件库的变量名,从而达到覆盖的目的。
我们就拿 antd 来进行示例。
我们首先在项目调试窗口查看其变量命名,分析过后得出其变量命名的规则。
同时在查阅 Ant Design 的设计语言后,分析出其使用 @ant-design/colors 快速生成十个色阶,并对各类行为规定了对应的色阶号。
由此可得:
import { generate } from "@ant-design/colors"
const getAntdColor = ({ color, name, dark, emitColors }: { color: string, name: string, dark?: boolean, emitColors?: boolean }) => {
const colors = generate(color, { "theme": dark ? "dark" : "default" })
const alias = [{ name: '', value: 6 }, { name: 'hover', value: 5 }, { name: 'active', value: 7 }, { name: 'outline', value: 1 }]
const aliasMap = alias.reduce((map, item) => {
const code = `--ant-${name}-color${item.name ? `-${item.name}` : ''}`
const value = colors[item.value - 1]
map[code] = {
name: '',
code,
value
}
return map
}, {} as Record
return {
...aliasMap, ...(emitColors ? colors.reduce((map, item, index) => {
const code = `--ant-${name}-${index + 1}`
const value = item
map[code] = {
name: '',
code,
value
}
return map
}, {} as Record
}
}
有了这个方法我们就可以快速的创建与其对应的变量。
export const color = new CSSStyle('色彩', 'color', {
light: {
name: '浅色',
code: 'light',
variables: {
...getAntdColor({ "color": '#13c2c2', "name": 'primary', "emitColors": true }),
...getAntdColor({ "color": '#1890ff', "name": 'info' }),
...getAntdColor({ "color": '#52c41a', "name": 'success' }),
...getAntdColor({ "color": '#faad14', "name": 'warning' }),
...getAntdColor({ "color": '#ff4d4f', "name": 'error' })
}
},
dark: {
name: '深色',
code: 'dark',
variables: {
...getAntdColor({ "color": '#13a8a8', "name": 'primary', "emitColors": true, dark: true }),
...getAntdColor({ "color": '#177ddc', "name": 'info', dark: true }),
...getAntdColor({ "color": '#49aa19', "name": 'success', dark: true }),
...getAntdColor({ "color": '#d89614', "name": 'warning', dark: true }),
...getAntdColor({ "color": '#a61d24', "name": 'error', dark: true })
}
}
});
这样在项目中就可以自由的使用 Colorfully 的功能了。
自适应主题
Q:什么是自适应主题呢?
A:自适应是指根据环境因素的不同有不同的展现。
接下来我们来看一个实例,你一定见过跟随系统的明暗主题,即在系统中设置浅色或深色时界面随之改变。
Windows 下的明暗设置可以在其设置的颜色设置中找到(选择模式)进行设置。
那么我们如何在代码中获取到这个设置呢?
在 CSS 中,我们可以通过 @media 获取到,也就是当 @media (prefers-color-scheme: light) 时为浅色模式,为 @media (prefers-color-scheme: dark) 时为深色模式。
那么我们就可以思考如何将它集成进我们的 color CSSStyle 中。
首先我们添加一个 color 的类型为 default 表示跟随系统的变化而变化,然后我们继承类 CSSStyle 改写其 parcel 方法。
class ColorCSSStyle
parcel(type: T | (string & Record
if (type === 'default') {
return this.getAll()
.filter(type => type.code !== 'default')
.map(
type => `@media (prefers-color-scheme: ${type.code}) {
*[ data-theme-color = 'default' ] {
${this.toTypeString(type.code)}
}
}`
)
.join('\n');
}
return super.parcel(type, value);
}
}
export const color = new ColorCSSStyle('色彩', 'color', {
default: { name: '默认', code: 'default', variables: {} },
light: {/*...*/},
dark: {/*...*/},
})
虽然 default 的 variables 值为空对象,但是这并不影响其 CSS 样式的生成,因为我们已经改写了 color 的 parcel 方法,使其检测到类型为 default 时,自动生成自适应的 @media 选择器。
以上方案在不复杂的场景下适用。
但是由于配置的自由度比较高,所以在我们重新创建 CSSStyle 后,我们使用的并不是 ColorCSSStyle,这会带来一定的问题。
因此我们内置了它,当 type 为 default 时,且 variables 为 {},我们将会在内部为你自动提供媒体查询功能。
可直接写为:
export const color = new CSSStyle('色彩', 'color', {
default: { name: '默认', code: 'default', variables: {} },
light: {/*...*/},
dark: {/*...*/},
})
范围主题
Q:什么是范围主题?
A:这其实就是字面意思,想象一下我们并不想让部分元素跟随主题变化,而是拥有其独特的属性存在,这就是范围主题的诞生。
我们只需要给使用范围指定主题的元素加上 data-theme-color 属性并给到指定值 dark 就可以指定其 color 样式为深色。
Q:这是基础的控制,那么我们可以像 theme 一样管理它吗?
A:也是可以的,你只需要初始化一个新的 Colorfully 并且传递其 root 参数为你需要使用范围主题的元素就可以了。
如果你不想再重新设置一遍,也可以直接从 theme 中使用 theme.derive 方法派生出一个实例,同样的你也需要指定其 root 参数。
theme.derive({ root: dom });
支持小程序
Q:小程序如何使用 Colorfully 呢?
A:由于小程序不支持操作 dom,所以我们只能通过 data 配合自定义渲染的形式进行挂载。
首先我们 pageStyle 一个 data,并将他挂载在标签的 style 属性上,然后通过 theme.updateDefaultUseParams 进行自定义渲染配置。
onLoad() {
theme.updateDefaultUseParams({
"mode": 'js',
"selectorMode": 'class',
"customMount": {
"selector": _themeMap => {},
"style": (styleList) => {
let pageStyle = '';
styleList.forEach(style => {
style.variables?.forEach(variable => {
pageStyle += `${variable.code}: ${variable.value};`;
});
});
this.setData({ pageStyle });
}
}
})
theme.use('light')
}
这样我们就算是接入了 Colorfully 的主题管理系统了。
对于小程序的监听系统主题改变,可以使用 wx.onThemeChange 方法自行实现。
每个页面都这样,那可就太麻烦了,所以我们结合混入来快速实现每个页面同样一致的效果:
Object.assign(globalThis, {
Page: function (params: Parameters
const onLoad = params.onLoad;
params.onLoad = function (...args) {
theme.updateDefaultUseParams({
mode: 'js',
selectorMode: 'class',
customMount: {
selector: _themeMap => {},
style: styleList => {
let pageStyle = '';
styleList.forEach(style => {
style.variables?.forEach(variable => {
pageStyle += `${variable.code}: ${variable.value};`;
});
});
this.setData({ pageStyle });
}
}
});
theme.use('light');
return onLoad?.call(this, ...args);
};
_Page(params);
}
});
然后我们在首页引入这个混入操作,同时在需要使用 CSS Variable 的页面包裹一个:
这样就达到了我们想要的效果。
支持 React Native
Q:React Native 如何使用 Colorfully 呢?
A:在 React Native 中并没有 CSS,因为它采用的是类似CSS的概念,且只能从组件的 style 注入。我们可以将 Colorfully 的主题通过变量这个载体传入。
接下来让我们看看如何实现吧。
我们首先把 style 交给 Mobx 进行状态管理:
import theme from '@xxx/theme';
import { makeAutoObservable, runInAction } from 'mobx';
class ThemeStore {
// 推断 styleMap 类型
style = {} as Exclude<
Parameters
undefined
>;
constructor() {
makeAutoObservable(this);
}
init() {
theme.updateDefaultUseParams({
mode: 'js',
customMount: {
selector: () => null,
style: (_, styleMap) => {
if (styleMap)
runInAction(() => {
this.style = styleMap;
});
}
}
});
theme.use('light');
}
}
const themeStore = new ThemeStore();
export default themeStore;
我们在声明 style 时,给到它类型推断,这样你在使用 style 时就可以得到类型提示了。
然后在组件中使用它:
import React, { useEffect } from 'react';
import { useColorScheme } from 'react-native';
import theme from '@xxx/theme';
import themeStore from './store/theme';
// 初始化主题
themeStore.init();
export function App() {
const systemTheme = useColorScheme() ?? 'light';
useEffect(() => {
// 自适应系统深浅色主题
theme.use(systemTheme);
}, [systemTheme]);
return (
{/* 使用主题 */}
{() =>
测试
}
);
}
registerRootComponent(App);
这样就可以了,可以开心的使用 Colorfully 了。
你一定很好奇为什么要这样写 themeStore.style.color['--color-text-primary'],其中 color 的 key 是你自己定义的。
你可以在定义主题时这样写:
import { CSSStyle } from 'colorfully';
export const color = new CSSStyle('色彩', 'color', {
light: {
name: '浅色',
code: 'light',
variables: {
textPrimary: {
name: '',
code: '--color-text-primary',
value: '#262626'
},
...{ /* more */}
}
},
dark: {
name: '深色',
code: 'dark',
variables: {
textPrimary: {
name: '',
code: '--color-text-primary',
value: '#dbdbdb'
},
...{ /* more */}
}
}
})
那么对于的使用:
{() =>
测试
}
这样看起来顺眼多了对吧。
再告诉你一个小技巧,按照以下形式写将会得到类型提示的描述:
import { CSSStyle } from 'colorfully';
/**
* 样式变量
*/
export interface IStyleVariable
/**
* 名称
*/
name: string;
/**
* 代码
*/
code: string;
/**
* 值
*/
value: T;
}
/**
* 颜色变量
*/
interface IColorVariable {
/**
* 主要文本
*/
textPrimary: IStyleVariable;
[k: string]: any;
}
export const color = new CSSStyle('色彩', 'color', {
light: {
name: '浅色',
code: 'light',
variables: {
textPrimary: {
name: '',
code: '--color-text-primary',
value: '#262626'
}
} as IColorVariable
},
dark: {
name: '深色',
code: 'dark',
variables: {
textPrimary: {
name: '',
code: '--color-text-primary',
value: '#dbdbdb'
}
} as IColorVariable
}
});
这样约束 variables 的同时,你也可以得到类型提示的描述了。
主题包
当你有多个项目时,如何复用就显得尤为重要了。
你可以将你预设好的主题,打包发布到 NPM 方便其他项目复用。
你只需包含基于 CommonJS 规范的 lib/index.js 并提供默认导出 theme 以供接下来的智能提示使用即可。
智能提示
既然创建了主题,那么必然有使用主题的时候。
我们在使用 CSS 变量的时候,是没有智能提示的,那也就代表着我们处于一个摸黑的状态。
那么如何打破这个黑暗就显得尤为重要了。
我们只需要安装 VSCode 中的 CSS Smart 插件即可解决这个问题。
具体查看 CSS Smart 中的介绍使用。
我们在插件中实现了主题包的智能提示解决方案,也就是动态执行 lib/index.js 得到其所有变量值来进行提示。
我们也会考虑后续执行本地暴露文件的可能性。
接口
这里不介绍具体 API 了,TypeScript 开发的懂得都懂,且以上示例比较全面。
ThemeParameters
/**
* 主题参数
*/
export interface ThemeParameters
/**
* 样式配置图
*/
styleMap?: StyleMap;
/**
* 主题配置图
*/
schemaMap?: SchemaMap;
/**
* 默认使用参数
*/
defaultUseParams?: UseParams;
}
ColorfullyConfig
配置格式。
/**
* 主题配置
*/
export interface ColorfullyConfig {
/**
* 样式
*/
styles: Array<{
/**
* 名称
*/
name: string;
/**
* 代码
*/
code: string;
/**
* 类型
*/
types: Array<{
/**
* 名称
*/
name: string;
/**
* 代码
*/
code: string;
/**
* 变量
*/
variables: Array<{
/**
* 名称
*/
name: string;
/**
* 代码
*/
code: string;
/**
* 值
*/
value: string;
}>;
}>;
}>;
/**
* 方案
*/
schemas: Array<{
/**
* 名称
*/
name: string;
/**
* 代码
*/
code: string;
/**
* { 样式 : 类型 }
*/
map: Record
}>;
}
参考链接
发表评论