Skip to content

内核 skinsuite ​

纯内核:零依赖、零 DOM、零框架。任何前端(Vue / React / Node / SSR)可用。

常量与白名单 ​

导出说明
THEME_ID_RE目录名 / id 白名单 /^[a-z0-9-]+$/(包名、设备、页面、配色、部件共用)
DEFAULT_THEME_ID空记录占位配色 id('default')
DEFAULT_THEME_PACKAGE内置默认包 id('default',eager 首屏零请求)
DEFAULT_THEME_COLOR默认配色 id('white')
DEFAULT_THEME_DARK_COLOR默认暗系配色 id('black')
THEME_DIR_LEVELS取值目录段 ['pkg','device','page','colorId']
THEME_COLORS_SEGMENT配色固定字面段('colors')
THEME_PARTS_SEGMENT部件固定字面段('parts')
THEME_COLOR_STYLE_FILE附加样式文件名('theme.scss')
THEME_DEF_FILE_CANDIDATES定义文件形态 ['index.ts','index.js'](并存 .ts 优先)

明暗与系别 ​

导出说明
MODE_CYCLE切换循环序 ['system','light','dark']
MODE_LABELS明暗文案(跟随系统 / 明 / 暗)
isThemeMode(v) / normalizeMode(raw)校验 / 归一(trim+小写,非法返回 null)
THEME_TONES / TONE_LABELS系别集合与文案(白系 / 黑系)
isThemeTone(v) / normalizeTone(raw)同上,无 system(系别是配色自带属性)
ThemeMode / ThemeTone类型 'system'|'light'|'dark' / 'light'|'dark'

token 安全校验 ​

ts
import { sanitizeOverrides, isSafeTokenEntry } from 'skinsuite';

const { tokens, rejected } = sanitizeOverrides(payload);
// tokens: 通过白名单的键值对;rejected: 被拒项("name=值前40字符"),逐条丢弃不整体拒绝
导出说明
isSafeTokenName(name)名字必须 --mauth-<短横线>
isSafeTokenValue(value)白名单:hex / rgb() / hsl() / 长度 / var(--mauth-*) / 关键字;拒 url()、颜色名、规则闭合字符
isSafeTokenEntry(name, value)键值对校验(--mauth-font-family 字体栈特例放宽)
sanitizeOverrides(input)逐条过滤,返回 SanitizeResult
ThemeTokenOverridesRecord<string, string>(扁平、不分明暗档)
ThemeTokenLayers{ theme?, external? } 注入分层

注册表(构建 + 查询) ​

ts
import { buildThemeRegistry, installThemeRegistry, getThemeRecord } from 'skinsuite';
import * as virtualTheme from 'virtual:theme';   // 通常经副作用 import 自动装配

installThemeRegistry(buildThemeRegistry(virtualTheme));
导出说明
buildThemeRegistry(modules, onWarn?)三张加载表 → Map<'pkg/device/page/colorId', MauthThemeRecord>;重名先到先得并告警
installThemeRegistry(registry)装入模块级单例(宿主启动时调一次;virtual:theme 自动装配)
getThemeRecord({id, device, pkg?, page})回退链:精确 → 同系别首套 → 兜底色 → 空记录
getDefaultThemeId({device, page, pkg?})范围兜底色(white 优先,无则字母序第一;空范围 null)
listThemes(device?)当前有哪些配色(可选按设备过滤)
listColorsOf(device, page, pkg)某范围全部配色(按 id 去重排序)
toneOfColor(id, device, page, pkg)某配色的系别;未登记 null
toneOfAnyScope(id)某配色系别(任意登记处,路径序第一份)
listColorIdsOfTone(device, page, pkg, tone)某范围某系别的全部配色 id
resolveThemeId(raw, device?, page?, pkg?)归一化并校验外部传入的配色 id(URL / 后端下发)
isKnownTheme(id, ...)包装 resolveThemeId 返回布尔
listColorViews(device, page)某设备某页下登记过配色的包集合
ThemeAssetModules虚拟模块三张加载表的形态
MauthThemeMeta/Package/Color/Record契约类型(文档注释即规格)

设备维度 URL 参数 ​

导出说明
readDeviceParam(query, name, deviceKey)单设备取值:专属键 → 通用键 → undefined(原样不校验;空串 = 未指定)
readUrlViewIntent(query, viewParam?, devices?)全设备一次读入版式意图 { deviceView, viewIntent }
viewParamsSnapshot(query, ...)th* 键白名单快照(不含配色键)——「仅当原始值变化才同步」的判等用
sameViewSnapshot(a, b)快照判等
DEFAULT_VIEW_PARAM / DEVICE_SCOPED_PARAMS'th' / ['th','th_color']
DeviceScopedParam / DeviceViewIntent类型

静默失败审计 ​

ts
import { parseThemeParams, collectWarnings, effectiveViewRaw } from 'skinsuite';

const params = parseThemeParams(routeQuery, { debugQuery: 'debug' }); // 触发键跟随清单配置
const warnings = collectWarnings(params, ctx);  // 人类可读警告列表(空 = 没问题)
导出说明
parseThemeParams(query, { debugQuery? })白名单键归位:th / th_color / device / 调试键 / 设备专属键;重复键进 repeated 带首值
effectiveViewRaw(params, urlKey)某设备生效的版式原始值(专属 > 通用 > null)
collectWarnings(params, ctx)四类静默失败显影(未知设备 / 版式值不存在 / 其它设备专属键 / 重复键);配色合法性不检
WarningContext判定输入全部显式注入(hasView / devices / listViews …),纯函数可单测
ThemeUrlParams / RepeatedParam / ParamAuditDevice类型

主题域清单 ​

ts
import { defineThemeManifest } from 'skinsuite';

export default defineThemeManifest({
  debug: { enabled: 'url', query: 'debug', value: 'theme' }
});
导出说明
defineThemeManifest(manifest?)声明并校验清单;非法档位 / 空键名启动即抛
resolveThemeManifest(manifest?)null 兜底机制默认(url 档),不让应用起不来
isThemeDebugVisible(debug, query)off→false;always→true;url→任一元素 === value(对齐 vue-router LocationQuery)
installThemeManifest(m) / themeManifest()清单单例装入 / 读取
ThemeManifest / ResolvedThemeManifest / ThemeDebugMode / ResolvedThemeDebug类型

其它 ​

导出说明
normalizeRemoteThemeConfig(data)外部下发配置形状归一({ theme?, mode?, tokens? };全空返回 null;只归一形状,不碰网络)
RemoteThemeConfig / DeviceVocab类型

基于 MIT 许可发布