hyva-child-theme

Hyvä 子主题创建器

此技能可创建完整的 Hyvä 子主题，包括适当的目录结构、配置文件和 Tailwind CSS 构建设置。

命令执行： 对于需要在开发环境中运行的命令（例如 bin/magento），请使用 hyva-exec-shell-cmd 技能来检测环境并确定合适的命令包装器。

工作流

步骤 1：收集主题信息

提示用户提供以下信息：

供应商名称：供应商／公司的命名空间（例如，“Acme”“MyCompany”）

• 必须采用 PascalCase 格式
• 用于 composer 包名称和目录结构
• 如果 app/design/frontend 或 app/code 中已有供应商名称文件夹，请以小写形式提供这些名称供用户参考

主题名称：主题名称（例如，“customTheme”“StoreTheme”）

• 必须采用 PascalCase 或 camelCase 格式
• 用于主题注册和目录名称
• 不得已作为子目录存在于 app/design/frontend 中

步骤 2：检测父主题

如果用户指定了父主题，请使用该主题。父主题可以是：

• Hyvä 默认主题：Hyva/default-csp 或 Hyva/default
• 现有 Hyvä 子主题：app/design/frontend/ 中的 {Vendor}/{ThemeName}

如果用户未指定父主题，请调用 hyva-theme-list 技能，查找项目中的所有 Hyvä 主题，并发现可用选项。

向用户列出可供选择的父主题：

• Hyvä 默认主题：Hyva/default-csp（如果已安装）或 Hyva/default
• 现有 Hyvä 子主题：将技能返回的主题列为 {Vendor}/{ThemeName}

后续步骤所需的父主题路径：

• Hyvä 默认主题：vendor/hyva-themes/magento2-default-theme-csp 或 vendor/hyva-themes/magento2-default-theme
• 子主题：app/design/frontend/{Vendor}/{ThemeName}

步骤 3：创建主题目录结构

在 app/design/frontend/<Vendor>/<themeName>/ 下创建主题目录，其中包含：

app/design/frontend/<Vendor>/<themeName>/
├── registration.php
├── theme.xml
├── composer.json
└── web/
    └── tailwind/
        └── (copied from parent theme)

步骤 4：创建配置文件

registration.php

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register( ComponentRegistrar::THEME, 'frontend/<Vendor>/<themeName>', __DIR__);

theme.xml

<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Example Store Theme</title>
    <parent>Hyva/default-csp</parent>
</theme>

标题格式： 将 PascalCase 主题名称拆分为多个单词（例如，StoreTheme → Store Theme）。标题应采用 <Vendor> <Theme Name Words> 格式（例如，Example/StoreTheme → Example Store Theme）。

根据所选父主题调整 <parent>：

• Hyvä 默认主题使用 Hyva/default-csp 或 Hyva/default
• 子主题父主题使用 {ParentVendor}/{ParentThemeName}（例如，Example/baseTheme）

composer.json

{
    "name": "<vendor-lowercase>/<package-name>",
    "description": "Example Store Theme based on Hyvä",
    "type": "magento2-theme",
    "license": "proprietary",
    "require": {
        "hyva-themes/magento2-default-theme-csp": "*"
    },
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

包名称规则：

• 将 <ThemeName> 转换为 kebab-case 格式（例如，StoreTheme → store-theme）
• 仅当主题名称不以“theme”结尾时，才追加 -theme 后缀
• 示例：
  • StoreTheme → store-theme（已以“theme”结尾，不追加后缀）
  • CustomStore → custom-store-theme（追加后缀）
  • myTheme → my-theme（已以“theme”结尾，不追加后缀）

调整 require 依赖以匹配父主题：

• Hyvä 默认主题：hyva-themes/magento2-default-theme-csp 或 hyva-themes/magento2-default-theme
• 子主题父主题：使用父主题的 composer 包名称（从其 composer.json 中获取）；如果父主题不是 composer 包，则省略该依赖

步骤 5：复制并配置 Tailwind

创建 web 目录，并从父主题复制 tailwind 文件夹，但排除 node_modules（复制的 node_modules 包含损坏的符号链接，必须重新安装）：

mkdir -p app/design/frontend/<Vendor>/<ThemeName>/web
rsync -a --exclude='node_modules' <parent_theme_path>/web/tailwind app/design/frontend/<Vendor>/<ThemeName>/web/

其中 <parent_theme_path> 为：

• Hyvä default-csp 对应 vendor/hyva-themes/magento2-default-theme-csp
• Hyvä default 对应 vendor/hyva-themes/magento2-default-theme
• 子主题的父主题对应 app/design/frontend/{ParentVendor}/{ParentTheme}

更新 web/tailwind/hyva.config.json，将父主题路径添加到 Tailwind 内容扫描配置中。

对于 Hyvä default theme 父主题：

{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

对于子主题父主题： 同时包含直接父主题和根 Hyvä 主题，以确保扫描所有模板类：

{
    "tailwind": {
        "include": [
            { "src": "app/design/frontend/{ParentVendor}/{ParentTheme}" },
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

如果子主题父主题的 hyva.config.json 中已有其他包含路径，请复制这些路径，以保留完整的继承链。

步骤 6：安装依赖并构建 CSS

使用 hyva-compile-tailwind-css 技能，为新创建的 app/design/frontend/<Vendor>/<ThemeName>/ 主题安装依赖并构建 CSS。

步骤 7：启用主题

告知用户可以通过以下方式启用主题：

1. Magento Admin：Content > Design > Configuration
2. 或通过 CLI：bin/magento config:set design/theme/theme_id <theme_id>

运行 setup upgrade 以注册主题：

bin/magento setup:upgrade
bin/magento cache:flush

故障排查

未找到 Hyvä 主题（步骤 2）

原因：项目中未安装 Hyvä 主题包。 解决方案：通过 Composer 安装 Hyvä 主题：composer require hyva-themes/magento2-default-theme 或 hyva-themes/magento2-default-theme-csp。

父主题路径不存在（步骤 5）

原因：所选父主题目录缺失或路径不正确。 解决方案：运行 rsync 前确认父主题存在。检查 Composer 包是否已正确安装：composer install。

父主题中缺少 Tailwind 文件夹（步骤 5）

原因：父主题没有 web/tailwind 目录（旧版或自定义主题可能会出现这种情况）。 解决方案：改为从 vendor/hyva-themes/magento2-default-theme-csp/web/tailwind 复制 tailwind 文件夹。

npm install 失败（步骤 6）

原因：Node 版本不匹配、网络问题或 package-lock.json 损坏。 解决方案：

• 检查 Node 版本（需要 Node 16+）：node --version
• 删除 node_modules 和 package-lock.json，然后重试 npm install

npm build 失败（步骤 6）

原因：hyva.config.json 中的路径无效或缺少清除目标。 解决方案：

• 确认 hyva.config.json 中的所有路径均存在于项目中
• 检查配置文件是否存在 JSON 语法错误
• 确保父主题路径正确

输出

创建成功后，提供以下摘要：

• 主题位置：app/design/frontend/<Vendor>/<ThemeName>/
• 父主题：所选父主题（例如 Hyva/default-csp、Hyva/default 或 {Vendor}/{ThemeName}）
• 后续自定义步骤：
  • 创建对应路径以覆盖模板
  • 在 web/tailwind/tailwind-source.css 中自定义 Tailwind
  • 开发时运行 npm run watch
  • 部署前运行 npm run build