4 篇博文 含有标签「WordPress」

TL;DR​

WordPress FSE Group 块的 layout 属性会自动生成 is-layout-* CSS 类，这些类的样式优先级高于普通自定义 CSS，导致尺寸设置失效。解决方案：1) 块注释中使用 "layout":{"type":"default"} 避免生成额外布局类；2) CSS 中使用 !important 强制覆盖；3) 关键：添加 padding: 0 !important 清除 Group 块默认内边距。

问题现象​

Timeline 组件的年份圆点应显示为 80px 正圆，实际却呈现为椭圆：

<!-- 块注释中的尺寸设置 -->
<!-- wp:group {"style":{"dimensions":{"width":"80px","height":"80px"}},"layout":{"type":"flex",...}} -->

/* 自定义 CSS */
.cclee-timeline-dot {
    width: 80px;
    height: 80px;
    border-radius: 50%;
}

无论调整 CSS 还是块属性，圆点始终被拉伸变形。

根因​

WordPress FSE 的 Group 块会根据 layout 属性自动添加布局相关的 CSS 类：

<div class="wp-block-group cclee-timeline-dot is-layout-flow">

这些 is-layout-* 类来自 WordPress 核心样式表，其样式规则会覆盖自定义 CSS。同时，Group 块存在默认 padding，会撑大元素导致尺寸计算偏差。

关键问题点：

1. layout: {"type": "flex"} 生成 is-layout-flex 类，子元素受 flexbox 拉伸影响
2. 块注释中的 style.dimensions 转为 inline style，但被布局类样式覆盖
3. Group 块默认 padding 增加了元素实际尺寸

解决方案​

1. 修改块注释，使用 default layout​

<!-- wp:group {"className":"cclee-timeline-dot","style":{"border":{"radius":"50%"}},"backgroundColor":"accent","textColor":"base","layout":{"type":"default"}} -->
<div class="wp-block-group cclee-timeline-dot has-base-color has-accent-background-color has-text-color has-background" style="border-radius:50%">

移除 style.dimensions 和复杂的 flex layout，改用 "layout":{"type":"default"}。

2. CSS 强制覆盖 + 清除默认 padding​

/* Timeline: Fixed circle dot */
.wp-block-group.cclee-timeline-dot {
    width: 80px !important;
    height: 80px !important;
    min-width: 80px !important;
    min-height: 80px !important;
    flex-shrink: 0 !important;
    aspect-ratio: unset !important;
    border-radius: 50% !important;
    display: flex !important;
    align-items: center !important;
    justify-content: center !important;
    align-self: center !important;
    box-sizing: border-box !important;
    text-align: center !important;
    padding: 0 !important;  /* 关键：清除默认 padding */
}

.wp-block-group.cclee-timeline-dot p {
    margin: 0 !important;
    white-space: nowrap !important;
    line-height: 1 !important;
    overflow: visible !important;
}

3. 使用 :has() 控制父容器​

防止父级 Column 被 flexbox 拉伸：

.wp-block-columns .wp-block-column:has(.cclee-timeline-dot) {
    flex-shrink: 0 !important;
    flex-basis: 100px !important;
    width: 100px !important;
}

关键发现​

padding: 0 !important 是最终解决方案。Group 块的默认 padding 会撑大元素，即使设置了 width/height，实际渲染尺寸仍会超出预期。

对类似需求感兴趣？联系合作

在为客户开发 WordPress FSE 企业主题时，发现 Footer 区块在多个 Style Variation 下文字几乎不可见。本文记录从 WCAG 对比度诊断到引入语义色、处理全局样式覆盖的完整修复过程。

TL;DR​

问题：FSE 主题的 contrast 颜色 token 语义混乱，浅色主题中 contrast ≈ 浅灰 ≈ base（白色），导致 Footer 对比度仅 1.05:1。

解法：

1. 引入 surface 语义色，专用于深色区块背景
2. 删除 wp_global_styles 中的覆盖样式
3. 所有 Style Variations 同步添加 surface 定义

结果：对比度从 1.05:1 提升至 15.8:1（WCAG AAA 级）。

问题现象​

Footer 区块使用 backgroundColor="contrast" + textColor="base"：

<!-- wp:group {"backgroundColor":"contrast","textColor":"base"} -->
<div class="has-base-color has-contrast-background-color">
  Footer 内容
</div>

在默认主题下，Footer 文字几乎不可见：

WCAG AA 标准要求普通文字对比度 ≥ 4.5:1，当前状态远不达标。

根因分析​

1. contrast 语义混乱​

contrast 的设计意图是"与 base 形成对比的背景色"，但在不同主题模式下语义矛盾：

Footer Pattern 假设 contrast 是深色背景，但 5/6 的 Style Variations 中它是浅色。

2. 颜色语义缺乏明确用途定义​

原设计系统只有 contrast 一个"对比色"，没有区分：

• 浅色对比区块（CTA Banner 等强调区域）
• 深色对比区块（Footer、暗色 Hero 等）

解决方案​

Step 1：引入 surface 语义色​

在 theme.json 中新增 surface token，专用于深色区块背景：

{
  "slug": "surface",
  "color": "#0f172a",
  "name": "Surface"
}

Step 2：更新所有 Style Variations​

每个 variation 定义自己的 surface 色（通常等于 primary）：

// styles/commerce.json
{ "slug": "surface", "color": "#1f2937", "name": "Surface" }

// styles/nature.json
{ "slug": "surface", "color": "#14532d", "name": "Surface" }

// styles/tech.json（深色主题）
{ "slug": "surface", "color": "#1e1e2e", "name": "Surface" }

Step 3：修改 Footer 模板​

<!-- wp:group {"backgroundColor":"surface","textColor":"base"} -->
<div class="has-base-color has-surface-background-color">
  Footer 内容
</div>

Step 4：删除全局样式覆盖​

修改 theme.json 后颜色仍不生效？检查全局样式：

# 检查是否存在全局样式
docker exec wp_cli wp post list --post_type=wp_global_styles --fields=ID,post_title --allow-root

# 删除全局样式
docker exec wp_cli wp post delete <ID> --force --allow-root
docker exec wp_cli wp cache flush --allow-root

原因：wp_global_styles 中的 color.palette 会完全覆盖（非合并）theme.json 的调色板。

修复结果​

颜色语义总结​

对类似需求感兴趣？联系合作

在为客户开发 WordPress FSE 主题时，频繁遇到 Block Pattern 验证失败问题。本文总结 5 种常见原因与解决方案。

TL;DR​

块验证失败通常是以下原因之一：颜色 slug 未定义、JSON 重复 key、Style Variation 调色板覆盖、HTML 属性与块注释不一致、全局样式覆盖 theme.json。逐一排查即可解决。

问题现象​

编辑器中 Pattern 显示红色警告：

Block contains unexpected or invalid content

尝试恢复块内容后，可能暂时正常，但刷新后问题复现。

原因一：颜色 slug 未定义​

根因​

Pattern 块属性引用了 theme.json 中不存在的颜色 slug：

<!-- 错误：neutral-text 不存在 -->
<!-- wp:paragraph {"textColor":"neutral-text"} -->
<p class="has-neutral-text-color">...</p>

解决方案​

1. 打开 theme.json，检查 settings.color.palette 定义的所有颜色
2. 将 Pattern 中的无效 slug 替换为有效值

# 批量替换示例
cd patterns/
sed -i 's/"neutral-text"/"neutral-500"/g' *.php
sed -i 's/has-neutral-text-color/has-neutral-500-color/g' *.php

有效 slug 参考： primary, secondary, accent, base, contrast, neutral-50 ~ neutral-900

原因二：JSON 重复 key​

根因​

块注释 JSON 中同一层级出现重复 key（常见于复制粘贴）：

// 错误：两个 style
{"style":{"typography":{...}},"style":{"spacing":{...}}}

JSON 规范不允许重复 key，解析器行为未定义。

解决方案​

合并为单一 key：

// 正确
{"style":{"typography":{...},"spacing":{...}}}

排查命令：

# 搜索可能重复的 key
grep -n ',"style":{' patterns/*.php | head -20

原因三：Style Variation 覆盖调色板​

根因​

styles/*.json 中的 color.palette 会完全覆盖（非合并）父主题调色板。

当 Pattern 引用 neutral-500，但当前 Style Variation 未定义该颜色时，验证失败。

解决方案​

每个 Style Variation 必须包含完整的 neutral 系列：

// styles/ocean.json
{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0d9488", "name": "Primary" },
        { "slug": "secondary", "color": "#0f766e", "name": "Secondary" },
        { "slug": "accent", "color": "#f59e0b", "name": "Accent" },
        { "slug": "base", "color": "#f8fafc", "name": "Base" },
        { "slug": "contrast", "color": "#0f172a", "name": "Contrast" },
        { "slug": "neutral-50", "color": "#fafafa", "name": "Neutral 50" },
        { "slug": "neutral-100", "color": "#f5f5f5", "name": "Neutral 100" },
        { "slug": "neutral-200", "color": "#e5e5e5", "name": "Neutral 200" },
        { "slug": "neutral-300", "color": "#d4d4d4", "name": "Neutral 300" },
        { "slug": "neutral-400", "color": "#a3a3a3", "name": "Neutral 400" },
        { "slug": "neutral-500", "color": "#737373", "name": "Neutral 500" },
        { "slug": "neutral-600", "color": "#525252", "name": "Neutral 600" },
        { "slug": "neutral-700", "color": "#404040", "name": "Neutral 700" },
        { "slug": "neutral-800", "color": "#262626", "name": "Neutral 800" },
        { "slug": "neutral-900", "color": "#171717", "name": "Neutral 900" }
      ]
    }
  }
}

关键： neutral 系列色值必须与 theme.json 完全一致，只改变品牌色。

原因四：HTML 属性与块注释不一致​

根因​

这是最隐蔽的问题。WordPress save 函数对生成的 HTML 有严格要求。

问题 4.1：class 顺序错误​

WordPress 生成 class 的固定顺序：

has-border-color has-{slug}-border-color has-{slug}-background-color has-background

手写 HTML 时顺序错误会导致验证失败。

问题 4.2：背景色属性混用​

背景色只能用 backgroundColor 属性，不可在 style.color.background 中声明：

<!-- 错误：混用导致 inline style 生成非法 CSS -->
<!-- wp:group {"style":{"color":{"background":"#f5f5f5"}}} -->

<!-- 正确 -->
<!-- wp:group {"backgroundColor":"neutral-100"} -->

问题 4.3：border style 属性顺序​

border-width 必须在 border-style 之前：

<!-- 正确 -->
<div style="border-width:1px;border-style:solid;border-radius:8px;">

解决方案​

最佳实践：从编辑器复制块代码，不要手写 HTML class 和 style。

1. 在编辑器中配置好块
2. 切换到代码编辑器视图
3. 复制完整的块注释 + HTML
4. 粘贴到 Pattern 文件

正确示例：

<!-- wp:group {"backgroundColor":"accent","borderColor":"neutral-200","style":{"border":{"radius":"8px","width":"1px","style":"solid"}}} -->
<div class="wp-block-group has-border-color has-neutral-200-border-color has-accent-background-color has-background" style="border-width:1px;border-style:solid;border-radius:8px;">
  <!-- content -->
</div>
<!-- /wp:group -->

原因五：全局样式覆盖 theme.json​

根因​

Site Editor 保存的自定义样式存储在 wp_global_styles CPT 中，优先级高于 theme.json。

修改 theme.json 后前端仍显示旧值，是因为全局样式覆盖了主题默认设置。

排查​

# 检查是否存在全局样式
wp post list --post_type=wp_global_styles --fields=ID,post_title --allow-root

# 查看全局样式内容
wp post get <ID> --fields=post_content --allow-root

解决方案​

# 删除全局样式
wp post delete <ID> --force --allow-root

# 清除缓存
wp cache flush --allow-root

预防： 开发阶段避免使用 Site Editor 自定义样式，所有配置通过 theme.json 管理。

排查流程总结​

块验证失败
    │
    ├─→ 检查颜色 slug 是否在 theme.json 中定义
    │
    ├─→ 检查 JSON 是否有重复 key
    │
    ├─→ 检查所有 Style Variation 是否包含完整调色板
    │
    ├─→ 检查 HTML class/style 是否与块注释一致
    │
    └─→ 检查 wp_global_styles 是否覆盖了 theme.json

对类似需求感兴趣？联系合作

TL;DR​

官方 WordPress Docker 镜像不含 WP-CLI。在 docker-compose.yml 中添加 command 配置，容器启动时自动下载安装 WP-CLI，无需手动进入容器操作。

问题现象​

在 WordPress Docker 容器内执行 wp 命令：

docker exec -it wordpress_container wp --version

报错：

bash: wp: command not found

根因​

WordPress 官方 Docker 镜像基于 php:apache 构建，设计目标是保持镜像精简。WP-CLI 是独立的命令行工具，需要额外安装，不在默认镜像中。

解决方案​

在 docker-compose.yml 的 WordPress 服务中添加 command，容器启动时自动安装 WP-CLI：

services:
  wordpress:
    image: wordpress:latest
    volumes:
      - ./wordpress:/var/www/html
    command: >
      bash -c "curl -sO https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar &&
               chmod +x wp-cli.phar &&
               mv wp-cli.phar /usr/local/bin/wp &&
               docker-entrypoint.sh apache2-foreground"

关键点：

1. curl -sO - 静默下载 WP-CLI phar 包
2. chmod +x - 添加执行权限
3. mv ... /usr/local/bin/wp - 移动到 PATH 目录，使命令全局可用
4. docker-entrypoint.sh apache2-foreground - 执行原镜像的默认入口点，启动 Apache

重启容器后验证：

docker-compose down
docker-compose up -d
docker exec -it wordpress_container wp --version
# 输出: WP-CLI 2.x.x

对类似需求感兴趣？联系合作