用于读取和写入全局样式数据结构（theme.json 格式）的通用库。

概述

这是一个与框架无关的工具库，提供了用于操作全局样式对象的函数。它处理 theme.json 格式的复杂嵌套结构，包括特定于块（block）的样式和设置。

API

读取数据

getStyle(globalStyles, path, blockName?, shouldDecodeEncode?)

从全局样式对象中获取样式值。

// 获取全局文本颜色
const textColor = getStyle( globalStyles, 'color.text' );

// 获取按钮背景色
const buttonBg = getStyle( globalStyles, 'color.background', 'core/button' );

// 获取原始值，不进行 CSS 变量解析
const rawValue = getStyle( globalStyles, 'color.text', undefined, false );

getSetting(globalStyles, path, blockName?)

获取具有回退层级（特定于块 → 全局）的设置值。

// 获取全局调色板
const colors = getSetting( globalStyles, 'color.palette' );

// 获取段落特定的字体大小
const fontSizes = getSetting(
    globalStyles,
    'typography.fontSizes',
    'core/paragraph'
);

写入数据

setStyle(globalStyles, path, newValue, blockName?)

不可变地设置样式值。返回一个新的全局样式对象。

// 设置全局文本颜色
const updated = setStyle( globalStyles, 'color.text', '#333333' );

// 设置按钮背景色
const updated = setStyle(
    globalStyles,
    'color.background',
    '#0073aa',
    'core/button'
);

setSetting(globalStyles, path, newValue, blockName?)

不可变地设置值。返回一个新的全局样式对象。

// 设置全局调色板
const updated = setSetting( globalStyles, 'color.palette', newPalette );

// 设置特定于块的设置
const updated = setSetting(
    globalStyles,
    'typography.fontSizes',
    sizes,
    'core/heading'
);

工具函数

getPalettes(globalStyles)

按来源（主题、自定义、默认）提取调色板。

generateGlobalStyles(globalStyles)

从全局样式对象生成 CSS。

mergeGlobalStyles(base, user)

合并多个全局样式对象，并确保正确的优先级。

数据结构

全局样式对象遵循 theme.json 架构：

{
  styles: {
    color: { text: '#000', background: '#fff' },
    typography: { fontSize: '16px' },
    elements: {
      button: { color: { background: 'blue' } }
    },
    blocks: {
      'core/paragraph': { color: { text: '#333' } }
    }
  },
  settings: {
    color: { palette: [...] },
    typography: { fontSizes: [...] },
    blocks: {
      'core/paragraph': { color: { text: true } }
    }
  }
}

功能特性

  • 不可变更新：所有设置器函数都返回新对象
  • 类型安全：完整的 TypeScript 支持
  • CSS 变量解析：自动解析 CSS 自定义属性
  • 特定于块的样式：支持块和元素特定的样式
  • 回退层级：智能地从块 → 全局 → 默认设置进行回退
  • 与框架无关：不依赖 React、WordPress 或其他框架

用法

本库旨在作为任何全局样式编辑界面的基础。它提供核心数据操作功能，同时保持完全通用和可重用。

使用前必须确保块及其样式已全局注册，因为块样式是从全局块存储中获取的。