lmc/spirit-web-twig-bundle

这是一个使用Twig实现Spirit设计系统组件的Symfony扩展包,并扩展了类似于HTML的语法。

安装数: 11 678

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 12

分支: 0

开放问题: 18

语言:Twig

类型:symfony-bundle

3.4.0 2024-09-09 09:41 UTC

README

这是一个使用Twig实现Spirit设计系统组件的Symfony扩展包,并扩展了类似JSX的语法。

要求

  • PHP >= 8.1
  • Symfony 4.4+ || 5.4+ || ^6.1
  • Twig >=2.12.5 || 3+

变更日志

CHANGELOG

如何安装

步骤 1

使用 composer 下载

安装包

composer require lmc/spirit-web-twig-bundle

步骤 2

SpiritWebTwigBundle 添加到包(在 all 包下)。如果你使用Symfony flex,它将自动配置。

bundles.php

    return [
        ...,
        Lmc\SpiritWebTwigBundle\SpiritWebTwigBundle::class => ['all' => true],
    ];

步骤 3(可选)

如果你想要更改默认设置,创建一个配置文件

config/packages/spirit_web_twig.yml

# all parameters are optional
spirit_web_twig:
  # define one or more paths to expand or overload components (uses glob patterns)
  paths:
    - '%kernel.project_dir%/templates/components'
  paths_alias: 'jobs-ui' # default is 'spirit'
  html_syntax_lexer: false # default is true
  spirit_css_class_prefix: 'jobs' # default is null
  icons: # optional settings for svg assets
    paths:
      - '%kernel.project_dir%/assets/icons' # define paths for svg icons set
    alias: 'jobs-icons' # default is 'icons-assets'

用法

有关详细用法,请参阅 TwigX 包

未转义的属性

所有内部使用 raw 过滤器的属性都以前缀 UNSAFE_ 开头。这被认为是一种传递HTML字符串的方式。

<Checkbox UNSAFE_helperText="<strong>Help!</strong>" />

Spirit 组件

有关可用组件,请参阅 components 目录

如果你想要扩展这些组件,示例指南见 这里。如果你想要贡献,请阅读指南 这里

附加属性

所有组件都接受传递给组件根元素的附加属性。这对于添加自定义事件处理器、无障碍属性或其他不支持组件API的属性很有用。

ℹ️ 如果你需要将事件处理器传递给我们的表单组件中的原生日元素,可以使用 inputProps 属性。

支持的属性有

  • on*(例如 onclick
  • data-*
  • aria-*
  • id

如果组件为这些属性中的任何一个设置了值,传入的值将被覆盖。

样式

Spirit 组件旨在在所有 Alma Career 应用程序中保持一致性。它们包括经过精心考虑和广泛测试的内置样式。一般来说,不建议自定义Spirit设计,但大多数组件都提供对布局和其他方面的控制。此外,你可以使用Spirit定义的设计令牌来确保你的应用程序符合你的设计要求,并适应平台缩放和配色方案。

样式属性

所有Spirit组件都接受一组属性,可以用来控制它们的间距。这些属性包括

  • margin
  • marginTop
  • marginRight
  • marginBottom
  • marginLeft
  • marginX
  • marginY

这些属性接受一个间距令牌(例如 space-100)、auto 或一个包含断点键和间距令牌值的对象或 auto。我们使用这些属性在组件的根元素上设置全局CSS实用工具类。

示例

<Alert marginBottom="space-100" />

<Button marginX="{{ { mobile: 'space-100', tablet: 'space-200' } }}" />

<Button marginLeft="{{ { mobile: 'space-100', tablet: 'space-200', desktop: 'auto' } }}" />

如果您需要更多控制组件的样式,可以使用逃生舱

逃生舱

虽然我们鼓励团队直接使用Spirit设计,但我们意识到有时可能需要特定产品的定制化。在这些情况下,我们鼓励您或您的设计师与我们沟通。我们可能能提出替代实现策略,或者您的设计可能有助于提出未来的Spirit新增功能。

尽管Spirit Web Twig组件不支持传统的类和样式属性,但有两种逃生舱供您在自行承担风险的情况下使用。这些是UNSAFE_className和UNSAFE_style。使用这些属性应被视为最后的手段。它们可以用来解决Spirit Web Twig中的错误或限制,但不应该长期使用。

原因在于,Spirit设计的未来更新可能会在不经意间导致产品出现破坏性更改。如果Spirit Web Twig组件的内部DOM结构或CSS属性发生变化,这可能会导致与产品中的CSS覆盖冲突。因此,className和style是不安全的,如果您使用它们,请知道您是在自行承担风险。

请参阅Web包文档获取更多样式信息。

弃用

此包使用弃用警告,用于props、函数和组件,这些将在下一个主要版本中删除或替换。检查您的Symfony控制台或日志,看您是否使用了任何已弃用的功能。

Deprecations in Symfony's console