后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载导读html_classes是 Twig 的HtmlExtensiontwig/html-extra扩展包提供的一个模板函数用于根据运行时条件动态拼接 HTML class 名称并返回字符串。它非常适合在组件化模板按钮、卡片、弹窗等中按状态选中、错误、加载中等组合 CSS 类名。读完本文你将掌握html_classes的完整用法、它与html_attr/html_attr_merge/html_attr_type等兄弟工具的分工配合以及其在 HtmlExtension.php 中的底层实现原理。安装与启用 HtmlExtensionhtml_classes属于HtmlExtension默认不在 Twig 核心中启用Twig 核心只自带src/Resources/core.php中的基础函数。需要先安装扩展包$ composer require twig/html-extra在 Symfony 项目中再安装官方 bundle 以自动注册扩展$ composer require twig/extra-bundle其他框架或纯 PHP 环境下则需手动把扩展挂到 Twig 环境上use Twig\Extra\Html\HtmlExtension; $twig new \Twig\Environment(...); $twig-addExtension(new HtmlExtension());从 extra/html-extra/composer.json 可以看到该包的依赖约束要求php 8.1.0、twig/twig ^3.13|^4.0并依赖symfony/mime与symfony/deprecation-contracts扩展通过Twig\Extra\Html\HtmlExtension注册html_classes、html_cva、html_attr三个函数以及html_attr_merge、html_attr_type等过滤器见 HtmlExtension.php。html_classes基础用法函数签名从 HtmlExtension.php 的实现可确认是变参的html_classes(...$args): string接收任意数量的参数并返回空格分隔、去重后的 class 字符串。最简单的用法是直接传入多个 class 名p class{{ html_classes(a-class, another-class, { errored: object.errored, finished: object.finished, pending: object.pending, }) }}How are you doing?/p这里字符串参数如a-class、another-class无条件输出而映射参数数组中的每一项键为 class 名、值为布尔条件只有条件为真时才输出对应的 class。于是object.errored、object.finished、object.pending这三个状态可以自由叠加组合。条件化 class 绑定映射语法详解映射mapping参数是html_classes最常用的形态写法为{{ html_classes({ is-active: user.isActive, is-admin: user.isAdmin }) }}其行为要点均可从源码 HtmlExtension::htmlClasses 逐行验证字符串 /Markup参数直接追加为 class数组参数遍历每个key condition当condition为真truthy时把key追加为 class否则跳过非法键若键不是字符串如数字键会抛出RuntimeError提示第 N 个参数键 N应为字符串非法参数类型参数既不是字符串也不是数组时同样抛出RuntimeError最终归一化结果经array_filter剔除空字符串与array_unique去重后用单个空格implode拼接。这意味着{{ html_classes(btn, btn, {}) }}输出btn重复项被去重而{{ html_classes(123) }}会直接抛错。函数的这一宽容输入、严格校验设计让模板作者可以安全地混合静态与条件 class。源码级实现剖析html_classes的实际逻辑集中在 HtmlExtension::htmlClasses核心代码如下为便于理解做了等价改写public static function htmlClasses(...$args): string { $classes []; foreach ($args as $i $arg) { if (\is_string($arg) || $arg instanceof Markup) { $classes[] (string) $arg; } elseif (\is_array($arg)) { foreach ($arg as $class $condition) { if (!\is_string($class)) { throw new RuntimeError(...); } if (!$condition) { continue; } $classes[] $class; } } else { throw new RuntimeError(...); } } return implode( , array_unique(array_filter($classes, static fn ($v) ! $v))); }几个值得注意的实现细节接受Markup如果传入的是已被标记为安全 HTML 的Twig\Markup对象同样会被转成字符串参与拼接便于与escape策略配合错误信息带参数下标异常消息会指明第 N 个参数方便在模板中定位问题空字符串会被过滤不会进入最终字符串避免产生多余空格去重是全局的无论 class 来自静态字符串还是条件映射重复项只保留一个。另外twig/html-extra在 Resources/functions.php 中还保留了一个internal的twig_html_classes(...)桥接函数自 3.9.0 起被标记为弃用仅转发到HtmlExtension::htmlClasses——模板中请直接使用html_classes函数不要依赖内部函数。与html_attr函数配合整段属性条件化html_classes只管 class 字符串本身如果需要同时按条件输出多个属性class、disabled、aria-* 等应使用同一扩展提供的html_attr函数Twig 3.24 起见 doc/functions/html_attr.rstbutton {{ html_attr({class: [btn], disabled: isDisabled}) }} Click me /buttonhtml_attr与html_classes的分工在于html_classes返回纯字符串适合嵌入class...或与既有字符串拼接html_attr返回完整渲染好的属性片段含引号转义适合直接{{ }}输出。html_attr的底层同样位于 HtmlExtension::htmlAttr它先调用htmlAttrMerge合并多个属性映射再逐属性用html_attr_relaxed策略转义属性名、用默认策略转义属性值。其属性值处理规则见 HtmlExtension::htmlAttrValue包括值类型行为null/false整个属性被省略aria-*例外见下true输出attrXHTML 兼容HTML5 中等价于无值简写数组/可迭代对象转为空格分隔的 token 列表style属性例外aria-*的布尔值转为字符串true/falsedata-*的非标量值JSON 编码Stringable对象除外因此若模板中有按钮在 loading 时附加disabled和aria-busy同时切换 class的需求html_attr一行即可完成而html_classes更适合纯 class 拼接场景。进阶html_attr_merge与html_attr_typeHtmlExtension还提供了两个与属性构建深度绑定的过滤器能让条件化属性组合更优雅html_attr_merge条件化合并属性映射该过滤器把多个属性映射从左到右合并false / null / 空数组参数会被自动忽略非常适合配合三元运算符做条件组合详见 doc/filters/html_attr_merge.rst{% set button_attrs { type: button, class: [btn] }|html_attr_merge( variant primary ? { class: [btn-primary] }, size large ? { class: [btn-lg] }, disabled ? { disabled: true, class: [btn-disabled] }, ) %}合并规则实现见 HtmlExtension::htmlAttrMerge标量后者覆盖前者数组按 PHParray_merge语义——数字键追加、字符串键替换实现MergeableInterface的对象可自定义合并行为如SeparatedTokenList会把两个 class 数组合并而非覆盖。html_attr_type自定义属性值渲染类型该过滤器把数组包装成具有专属渲染逻辑的对象支持三种类型见 doc/filters/html_attr_type.rstsst默认空格分隔 token 列表适合class、aria-labelledbycst逗号分隔适合srcset、sizesstyle内联 CSS 样式映射按key: value;输出序列按声明字符串输出。img {{ html_attr({ srcset: [small.jpg 480w, large.jpg 1200w]|html_attr_type(cst) }) }} {# 输出: img srcsetsmall.jpg 480w, large.jpg 1200w #}这些类型的实现类位于 extra/html-extra/HtmlAttr 目录SeparatedTokenListsst/cst与InlineStylestyle都同时实现了AttributeValueInterface与MergeableInterface因此既能在html_attr中自定义渲染也能在html_attr_merge中实现智能合并。高级扩展点AttributeValueInterface若默认规则仍不够用属性值可以是实现AttributeValueInterface的对象见 AttributeValueInterface.php。只需实现getValue(): ?string方法即可自定义该值在html_attr中的最终渲染返回null表示省略该属性其优先级高于本文前述所有规则返回的字符串仍会自动做 HTML 属性上下文转义。同理MergeableInterface见 MergeableInterface.php允许对象自定义在html_attr_merge中的合并行为接口 docblock 中明确说明了mergeInto()右侧值主导与appendFrom()右侧普通值时被追加两种合并方向的语义。安全与最佳实践html_classes只做字符串拼接与去重不做 HTML 转义class 名若来自用户输入应先自行过滤或经由escape处理html_attr的style属性含html_attr_type(style)不做 CSS 层面的额外转义官方文档明确警告不要用它传递不可信的、用户提供的数据键或值都不行见 doc/functions/html_attr.rst 的 warning 说明属性名统一走html_attr_relaxed转义策略属性值走默认转义策略这是html_attr内置的安全保障多值属性class、srcset、aria-describedby等建议始终使用可迭代值单值属性id、href等使用非可迭代值这样能最大化利用html_attr_merge的合并语义避免混淆官方文档原话建议见 doc/functions/html_attr.rst。相关资源函数文档doc/functions/html_classes.rst、doc/functions/html_attr.rst过滤器文档doc/filters/html_attr_merge.rst、doc/filters/html_attr_type.rst核心实现HtmlExtension.php值类型实现extra/html-extra/HtmlAttr测试覆盖HtmlAttrTest.php、HtmlAttrMergeTest.php、CvaTest.php赞分享后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载相关推荐Twig HTML 扩展twig/html-extra实战指南data_uri、html_classes 与 html_cva 详解Twig HTML 扩展twig/html extra实战指南data_uri、html_classes 与 html_cva 详解 Twig 官方维护的后端Hugo 模板函数 transform.Markdownify 完全指南在模板中将 Markdown 渲染为 HTMLHugo 模板函数 transform.Markdownify 完全指南在模板中将 Markdown 渲染为 HTML 导读 transform.Markdo开发工具前端CLIbash-guide权威指南函数定义与条件语句完全解析bash guide权威指南函数定义与条件语句完全解析 你是否还在为Bash脚本中的函数复用和逻辑判断烦恼本文将从实际应用场景出发带你系统掌握Bash函数教程上一篇daisyUI 如何用>下一篇uWebSockets版本发布清单测试、文档与通知检查创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Twig `html_classes` 函数：在模板中条件化拼接 HTML class 的权威指南
后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载导读html_classes是 Twig 的HtmlExtensiontwig/html-extra扩展包提供的一个模板函数用于根据运行时条件动态拼接 HTML class 名称并返回字符串。它非常适合在组件化模板按钮、卡片、弹窗等中按状态选中、错误、加载中等组合 CSS 类名。读完本文你将掌握html_classes的完整用法、它与html_attr/html_attr_merge/html_attr_type等兄弟工具的分工配合以及其在 HtmlExtension.php 中的底层实现原理。安装与启用 HtmlExtensionhtml_classes属于HtmlExtension默认不在 Twig 核心中启用Twig 核心只自带src/Resources/core.php中的基础函数。需要先安装扩展包$ composer require twig/html-extra在 Symfony 项目中再安装官方 bundle 以自动注册扩展$ composer require twig/extra-bundle其他框架或纯 PHP 环境下则需手动把扩展挂到 Twig 环境上use Twig\Extra\Html\HtmlExtension; $twig new \Twig\Environment(...); $twig-addExtension(new HtmlExtension());从 extra/html-extra/composer.json 可以看到该包的依赖约束要求php 8.1.0、twig/twig ^3.13|^4.0并依赖symfony/mime与symfony/deprecation-contracts扩展通过Twig\Extra\Html\HtmlExtension注册html_classes、html_cva、html_attr三个函数以及html_attr_merge、html_attr_type等过滤器见 HtmlExtension.php。html_classes基础用法函数签名从 HtmlExtension.php 的实现可确认是变参的html_classes(...$args): string接收任意数量的参数并返回空格分隔、去重后的 class 字符串。最简单的用法是直接传入多个 class 名p class{{ html_classes(a-class, another-class, { errored: object.errored, finished: object.finished, pending: object.pending, }) }}How are you doing?/p这里字符串参数如a-class、another-class无条件输出而映射参数数组中的每一项键为 class 名、值为布尔条件只有条件为真时才输出对应的 class。于是object.errored、object.finished、object.pending这三个状态可以自由叠加组合。条件化 class 绑定映射语法详解映射mapping参数是html_classes最常用的形态写法为{{ html_classes({ is-active: user.isActive, is-admin: user.isAdmin }) }}其行为要点均可从源码 HtmlExtension::htmlClasses 逐行验证字符串 /Markup参数直接追加为 class数组参数遍历每个key condition当condition为真truthy时把key追加为 class否则跳过非法键若键不是字符串如数字键会抛出RuntimeError提示第 N 个参数键 N应为字符串非法参数类型参数既不是字符串也不是数组时同样抛出RuntimeError最终归一化结果经array_filter剔除空字符串与array_unique去重后用单个空格implode拼接。这意味着{{ html_classes(btn, btn, {}) }}输出btn重复项被去重而{{ html_classes(123) }}会直接抛错。函数的这一宽容输入、严格校验设计让模板作者可以安全地混合静态与条件 class。源码级实现剖析html_classes的实际逻辑集中在 HtmlExtension::htmlClasses核心代码如下为便于理解做了等价改写public static function htmlClasses(...$args): string { $classes []; foreach ($args as $i $arg) { if (\is_string($arg) || $arg instanceof Markup) { $classes[] (string) $arg; } elseif (\is_array($arg)) { foreach ($arg as $class $condition) { if (!\is_string($class)) { throw new RuntimeError(...); } if (!$condition) { continue; } $classes[] $class; } } else { throw new RuntimeError(...); } } return implode( , array_unique(array_filter($classes, static fn ($v) ! $v))); }几个值得注意的实现细节接受Markup如果传入的是已被标记为安全 HTML 的Twig\Markup对象同样会被转成字符串参与拼接便于与escape策略配合错误信息带参数下标异常消息会指明第 N 个参数方便在模板中定位问题空字符串会被过滤不会进入最终字符串避免产生多余空格去重是全局的无论 class 来自静态字符串还是条件映射重复项只保留一个。另外twig/html-extra在 Resources/functions.php 中还保留了一个internal的twig_html_classes(...)桥接函数自 3.9.0 起被标记为弃用仅转发到HtmlExtension::htmlClasses——模板中请直接使用html_classes函数不要依赖内部函数。与html_attr函数配合整段属性条件化html_classes只管 class 字符串本身如果需要同时按条件输出多个属性class、disabled、aria-* 等应使用同一扩展提供的html_attr函数Twig 3.24 起见 doc/functions/html_attr.rstbutton {{ html_attr({class: [btn], disabled: isDisabled}) }} Click me /buttonhtml_attr与html_classes的分工在于html_classes返回纯字符串适合嵌入class...或与既有字符串拼接html_attr返回完整渲染好的属性片段含引号转义适合直接{{ }}输出。html_attr的底层同样位于 HtmlExtension::htmlAttr它先调用htmlAttrMerge合并多个属性映射再逐属性用html_attr_relaxed策略转义属性名、用默认策略转义属性值。其属性值处理规则见 HtmlExtension::htmlAttrValue包括值类型行为null/false整个属性被省略aria-*例外见下true输出attrXHTML 兼容HTML5 中等价于无值简写数组/可迭代对象转为空格分隔的 token 列表style属性例外aria-*的布尔值转为字符串true/falsedata-*的非标量值JSON 编码Stringable对象除外因此若模板中有按钮在 loading 时附加disabled和aria-busy同时切换 class的需求html_attr一行即可完成而html_classes更适合纯 class 拼接场景。进阶html_attr_merge与html_attr_typeHtmlExtension还提供了两个与属性构建深度绑定的过滤器能让条件化属性组合更优雅html_attr_merge条件化合并属性映射该过滤器把多个属性映射从左到右合并false / null / 空数组参数会被自动忽略非常适合配合三元运算符做条件组合详见 doc/filters/html_attr_merge.rst{% set button_attrs { type: button, class: [btn] }|html_attr_merge( variant primary ? { class: [btn-primary] }, size large ? { class: [btn-lg] }, disabled ? { disabled: true, class: [btn-disabled] }, ) %}合并规则实现见 HtmlExtension::htmlAttrMerge标量后者覆盖前者数组按 PHParray_merge语义——数字键追加、字符串键替换实现MergeableInterface的对象可自定义合并行为如SeparatedTokenList会把两个 class 数组合并而非覆盖。html_attr_type自定义属性值渲染类型该过滤器把数组包装成具有专属渲染逻辑的对象支持三种类型见 doc/filters/html_attr_type.rstsst默认空格分隔 token 列表适合class、aria-labelledbycst逗号分隔适合srcset、sizesstyle内联 CSS 样式映射按key: value;输出序列按声明字符串输出。img {{ html_attr({ srcset: [small.jpg 480w, large.jpg 1200w]|html_attr_type(cst) }) }} {# 输出: img srcsetsmall.jpg 480w, large.jpg 1200w #}这些类型的实现类位于 extra/html-extra/HtmlAttr 目录SeparatedTokenListsst/cst与InlineStylestyle都同时实现了AttributeValueInterface与MergeableInterface因此既能在html_attr中自定义渲染也能在html_attr_merge中实现智能合并。高级扩展点AttributeValueInterface若默认规则仍不够用属性值可以是实现AttributeValueInterface的对象见 AttributeValueInterface.php。只需实现getValue(): ?string方法即可自定义该值在html_attr中的最终渲染返回null表示省略该属性其优先级高于本文前述所有规则返回的字符串仍会自动做 HTML 属性上下文转义。同理MergeableInterface见 MergeableInterface.php允许对象自定义在html_attr_merge中的合并行为接口 docblock 中明确说明了mergeInto()右侧值主导与appendFrom()右侧普通值时被追加两种合并方向的语义。安全与最佳实践html_classes只做字符串拼接与去重不做 HTML 转义class 名若来自用户输入应先自行过滤或经由escape处理html_attr的style属性含html_attr_type(style)不做 CSS 层面的额外转义官方文档明确警告不要用它传递不可信的、用户提供的数据键或值都不行见 doc/functions/html_attr.rst 的 warning 说明属性名统一走html_attr_relaxed转义策略属性值走默认转义策略这是html_attr内置的安全保障多值属性class、srcset、aria-describedby等建议始终使用可迭代值单值属性id、href等使用非可迭代值这样能最大化利用html_attr_merge的合并语义避免混淆官方文档原话建议见 doc/functions/html_attr.rst。相关资源函数文档doc/functions/html_classes.rst、doc/functions/html_attr.rst过滤器文档doc/filters/html_attr_merge.rst、doc/filters/html_attr_type.rst核心实现HtmlExtension.php值类型实现extra/html-extra/HtmlAttr测试覆盖HtmlAttrTest.php、HtmlAttrMergeTest.php、CvaTest.php赞分享后端【免费下载链接】TwigTwig, the flexible, fast, and secure template language for PHP项目地址https://gitcode.com/gh_mirrors/tw/Twig点击查看免费下载相关推荐Twig HTML 扩展twig/html-extra实战指南data_uri、html_classes 与 html_cva 详解Twig HTML 扩展twig/html extra实战指南data_uri、html_classes 与 html_cva 详解 Twig 官方维护的后端Hugo 模板函数 transform.Markdownify 完全指南在模板中将 Markdown 渲染为 HTMLHugo 模板函数 transform.Markdownify 完全指南在模板中将 Markdown 渲染为 HTML 导读 transform.Markdo开发工具前端CLIbash-guide权威指南函数定义与条件语句完全解析bash guide权威指南函数定义与条件语句完全解析 你是否还在为Bash脚本中的函数复用和逻辑判断烦恼本文将从实际应用场景出发带你系统掌握Bash函数教程上一篇daisyUI 如何用>下一篇uWebSockets版本发布清单测试、文档与通知检查创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
