README

CSS Modules for Atomic.Fusion

为什么？

Atomic.Fusion 允许你在 Neos.Fusion 中实现前端组件架构。在类似的环境（如 React 或 Vue.js）中，CSS Modules 已被证明是避免全局命名空间问题的强大解决方案，并使你的样式与组件一起便携。

启用这项技术感觉像是 Atomic.Fusion 生态系统的一个自然扩展。

CSS Modules 做什么？

简而言之：CSS Modules 将你的 CSS 类名和其他全局标识符（如 @keyframes）转换为唯一标识符。在处理你的 CSS 文件时，会创建一个 JSON 文件，将原始类名映射到新的唯一标识符。

这样就可以确保你始终可以使用在组件上下文中有意义的标识符，而不必担心潜在的命名冲突。

PackageFactory.AtomicFusion.CssModules 帮助你在正确的地方包含那些 *.json 文件。它期望它们已经与你的 Fusion 组件一起存在 - 它不会生成它们。

为了生成 CSS Module 文件，你必须相应地配置你的前端构建管道。下一个部分将给出一个示例。

设置 CSS Modules

以下描述了一个用于 postcss 和 postcss-modules 的示例设置。这不是创建此类设置的唯一方法。有关更多信息，我建议你查看 postcss-cli 和 postcss-modules 存储库。

CSS modules 需要 Node JS 和两个基本依赖。确保 Node JS 可用于你的设置，并且你已经在你的仓库的根目录（或你希望它存在的任何位置）中有一个有效的 package.json 文件。

然后安装以下包

yarn add --dev postcss postcss-modules

此示例还使用 postcss-cli

yarn add --dev postcss-cli

然后在与 package.json 相同的目录中创建一个 postcss.config.js

module.exports = {
    plugins: [
        require('postcss-modules')
    ]
}

在与 package.json 相同的目录中创建一个包含构建 CSS 脚本的 Makefile

SHELL=/bin/bash
export PATH := $(PATH):./node_modules/.bin
export SITE_PACKGE_DIR="./Packages/Sites/Vendor.Site"

build-css:
	# Build CSS with postcss
	postcss \
		${SITE_PACKGE_DIR}/Resources/Private/Fusion/**/*.css \
		--dir ${SITE_PACKGE_DIR}/Resources/Public/Styles/temp
	# Concat all built CSS files
	cat ${SITE_PACKGE_DIR}/Resources/Public/Styles/temp/* > ${SITE_PACKGE_DIR}/Resources/Public/Styles/main.css
	# Remove temporary CSS files
	rm -rf ${SITE_PACKGE_DIR}/Resources/Public/Styles/temp

当你运行 make build-css 时，所有放置在与 *.fusion 组件文件旁边的 *.css 文件都将随后附带一个包含上述映射的相应的 *.css.json 文件。

在Fusion中的使用

考虑以下CSS文件（假设为Vendor.Site/Resources/Private/Fusion/MyComponent/MyComponent.css）

.myComponent {
	display: block;
}

.isActive {
	background-color: blue;
}

运行make build-css后，应该会出现一个文件Vendor.Site/Resources/Private/Fusion/MyComponent/MyComponent.css.json。

现在，在您的Vendor.Site/Resources/Private/Fusion/MyComponent/MyComponent.fusion文件中，您可以这样访问类名

prototype(Vendor.Site:MyAwesomeComponent) < prototype(PackageFactory.AtomicFusion:Component) {
	# Fusion
	renderer = Neos.Fusion:Tag {
		attributes.class = ${AtomicFusion.classNames(styles.myComponent, props.isActive && styles.isActive)}
	}

	# AFX
	renderer = afx`
		<div
			class={AtomicFusion.classNames(
				styles.myComponent,
				props.isActive && styles.isActive
			)}
			>
		</div>
	`
}

注意，在您的组件renderer路径中，现在您可以访问一个包含类名映射的特殊styles上下文。

旁白： AtomicFusion.classNames是一个条件性地连接类名的辅助方法。更多关于这个方法的信息可以在Atomic.Fusion主仓库中找到。

CSS模块文件的发现

Fusion实际上没有关于原型定义在哪个文件中的信息。因此，为了启用与那些组件*.fusion文件并排放置的文件的发现，我们需要配置一个查找模式

PackageFactory:
  AtomicFusion:
    CssModules:
      tryFiles:
        - resource://{packageKey}/Private/Fusion/{componentPath}.css.json

根据上述配置，原型prototype(Vendor.Site:MyAwesomeComponent)的CSS模块文件将被假定为resource://Vendor.Site/Private/Fusion/MyAwesomeComponent.css.json。

{packageKey}和{componentPath}是将在运行时替换各自Fusion原型的运行时信息的变量。

以下变量将被考虑

• {prototypeName} - 完整的原型名称
• {packageKey} - 原型名称中:之前的部分
• {componentName} - 原型名称中:之后的部分
• {componentBaseName} - 如果componentName由点分隔（例如，对于Vendor.Site:Atom.Button，这将是指：Button）
• {componentPath} - 与{componentName}类似，所有点都被目录分隔符替换。

默认情况下，包会查看以下模式

resource://{packageKey}/Private/Fusion/{componentPath}.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/{componentBaseName}.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/style.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/Style.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/styles.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/Styles.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/index.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/Index.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/component.css.json
resource://{packageKey}/Private/Fusion/{componentPath}/Component.css.json

注意事项

最近，原生组件原型Neos.Fusion:Component已加入Neos.Fusion核心。遗憾的是，这个包不会与新原型一起工作，依赖于PackageFactory.AtomicFusion:Component的存在。

这可能在将来发生变化，无论是通过这个包还是Neos.Fusion的PR。

如果您仍然想使用这个包与现有的依赖于Neos.Fusion:Component的代码库一起使用，您可以将Neos.Fusion:Component的标准实现替换为PackageFactory.AtomicFusion:Component的实现。

prototype(Neos.Fusion:Component) {
    @class = 'PackageFactory\\AtomicFusion\\FusionObjects\\ComponentImplementation'
}

PackageFactory.AtomicFusion:Component与Neos.Fusion:Component完全兼容，但您仍然应该意识到

这不是绝世武功！

许可证

请参阅LICENSE.md