README

为片段和模板提供更好的属性API

此插件将Vue.js/Laravel-Blade类似的属性组合引入到您的Kirby项目模板中。这是对更好的嵌套片段和组件的HTML属性处理的探索。

要求

• Kirby 4.0+（对于Kirby 3安装，请使用版本1.x）
• PHP 8.1（因为需要枚举支持）

安装

建议使用Composer进行安装。

composer require fabianmichael/kirby-template-attributes

另外，您也可以下载插件，并将其手动复制到您的网站site/plugins/文件夹中进行安装。

用法

基本用法

使用attributes()辅助函数生成属性字符串

<button <?= attributes([
  'role' => 'button',
  'aria-expanded' => 'false',
]) ?>>[…]</button>

如果您更喜欢更简洁的语法，也可以使用命名参数。请注意，这仅在您的属性名称中不包含破折号时才有效

<img <?= attributes(
  class: 'icon',
  width: 16,
  height: 16,
  src: $image->url(),
	alt: 'The funniest donkey ever!',
) ?>>

或者，如果您只有属性字符串，也可以将其提供给attributes()辅助函数

<?php

// get image dimensions as height="yyy" width="xxx" 
$src  = 'img.png';
$size = getimagesize($src)[3];

?>

<img <?= attributes($size)->merge([
	'src' => $src,
	'alt' => '',
]) ?>>

⚠️ 如果您需要XML兼容的属性，请始终调用$attributes->toXml()而不是仅仅回显Attributes对象，因为否则所有属性都将转换为小写。

在许多情况下，您需要设置不同的类。classes()辅助函数是一个提高可读性的好方法

<button <?= classes([
  'button',
  'button--red' => $color === 'red', // class will only appear in class attribute, if condition is true
]) ?>>[…]</button>

classes()辅助函数非常灵活，也接受多个参数，每个参数可以是字符串或数组（但请确保代码可读性），

<button <?= classes('button', [
  'button--red' => $color === 'red',
], 'absolute', 'top-0 left-0') ?>>[…]</button>

合并属性

# site/snippets/button.php

<button <?= attributes([
  'class' => 'button',
  'role' => 'button',
  'aria-expanded' => 'false',
  'style' => '--foo: bar',
])->merge($attr ?? []) ?>>[…]</button>

# site/templates/default.php

<?php snippet('button', [
  'attr' => [
    'role' => 'unicorn', // attributes can be overridden
    'onclick' => 'alert("everyone likes alerts!!!")',
    'class' => 'absolute top-0 left-0
      md:left-4
      xl:left-8', // classes are automatically appended to the existing attribute value and surplus whitespace is trimmed
    'style' => '--bar: foo', // style attribute value is also appended to the original value
  ],
]) ?>

前后

您可以通过使用相应的方法设置$before和$after，就像Kirby的Html::attr()辅助函数一样

attributes(class: 'foo')->before(' ');
attributes(class: 'foo')->after(' ');

示例

一个按钮组件作为site/snippets/button.php中的片段存在

<button class="button"><?= html($text ?? 'Button text') ?></button>

一个常见的场景是在调用snippet('button')辅助函数类时需要添加属性，例如class、data-*、title、aria-*等。开发者无法为每个组件处理每个可能的属性。之前的attributes()辅助函数可以在这里帮助

<button <?= attributes($attr ?? []) ?> class="button"><?= html($text ?? 'Button text') ?></button>

这效果更好，但我们仍然无法轻松扩展class属性。引入新的attributes()辅助函数

<button <?= attributes([
    'class' => 'button',
])->merge($attr ?? []) ?>><?= html($text ?? 'Button text') ?></button>

更简洁

<button <?= classes('button')->merge($attr ?? []) ?>><?= html($text ?? 'Button text') ?></button>

这变得更加酷，因为类可以按条件作为数组分配

<?php

$text ??= 'Button text';
$size ??= 'normal';
$theme ??= null;
$attr ??= [];

?>
<button <?= attributes([
    'role' => 'button',
    'style' => [
      'font-size: 2rem;' => ($size === 'large'),
    ],
])->class([
    'button',
    "button--{$size}",
    "button--{$theme}" => $theme, // will only be merged, if $theme is trueish
])->merge($attr) ?>><?= html($text) ?></button>

这已经非常酷，使处理片段的属性变得更加容易，例如，如果我们使用按钮在site/snippets/menu.php

<nav class="menu">
    […]
    <?php snippet('button', [
        'text' => 'Toggle Menu',
        'attr' => [
            'class' => 'menu__button',
            'aria-controls' => 'menu-popup',
            'aria-expanded' => false,
            'role' => 'teapot', // overrrides the default attribute
        ],
    ]) ?>
</nav>

许可证

MIT（但如果此软件有助于您支付账单，强烈建议您❤️ 赞助我）。