README

使用Symfony和Twig创建活生生的风格指南！✨

目标
安装
如何使用
开发
- CSS

目标

为项目设计提供单一的视觉源。
从风格指南提供组件和资源，以防止代码重复。
提供良好的开发者体验（DX）✨，使创建美观的风格指南变得非常容易。

安装

通过composer安装。
```
composer require zicht/htmldev-bundle
```

如何使用

设置

将包加载到您的AppKernel中。

new Zicht\Bundle\HtmldevBundle\ZichtHtmldevBundle()

配置路由。

将以下Yaml添加到应用程序的路由配置中。
```
htmldev:
   resource: "@ZichtHtmldevBundle/Resources/config/routing.yml"
```
⚠️如果您将此包与zicht/page-bundle结合使用，请确保此配置位于包含/{locale}的任何路由之上。
添加一个app/config/bundles/配置文件来配置Twig命名空间并将项目特定资源添加到风格指南中（您可以配置更多内容，请参阅下文）
```
twig:
    paths:
        "%kernel.root_dir%/../htmldev": htmldev

zicht_htmldev:
    styleguide:
        assets:
            -  type: stylesheet
               path: 'assets/main.css'
            -  type: script
               path: 'assets/main.min.js'
```
对于风格指南，有两种资源类型：样式表和脚本。对于两者，您都可以配置一个path，它将通过Twig的asset()函数传递，或者您可以配置一个URL（例如外部样式表或脚本），或者您可以配置一个body以添加内联CSS或脚本。
在htmldev/目录中创建一个data/styleguide/目录。添加一个包含以下内容的navigation.yml文件
```
-
    title: Components
    uri: /htmldev/components/buttons
```
转到风格指南的URL /htmldev（例如 https:///htmldev），您应该看到风格指南的基本设置

可选地，您可以更改风格指南的标题及其输出。

要更改风格指南标题，编辑配置并添加title: '...'元素

zicht_htmldev:
    styleguide:
        title: 'Design System'

要更改风格指南的副标题或添加（SVG）徽标，编辑配置并添加subtitle: '...'元素

zicht_htmldev:
  styleguide:
      title: 'Design System'
      subtitle: 'Zicht'

或者您可以使用原始SVG代码，但不要忘记定义不超过35px的高度

zicht_htmldev:
  styleguide:
      title: 'Design System'
      subtitle: >-
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="35px" height="35px" preserveAspectRatio="xMidYMid meet">
            <path fill="currentColor" d="M32 16c0 8.8-7.2 16-16 16S0 24.8 0 16 7.2 0 16 0s16 7.2 16 16zm-21 1.9h6.1l8.7-10.6h-14l-4.3 4.4h8.6L11 17.9zm9.7 5.9l4.3-4.4H9.8l-3.6 4.4h14.5z"/>
            </svg>

要更改风格指南输出，编辑配置并添加output: []部分

zicht_htmldev:
    styleguide:
        output: ['example', 'twig', 'html'] # or ['example', 'html'] or ['example'] or ...

默认值（未明确配置时）为output: ['example', 'twig']

默认情况下，SVG将在除了开发环境以外的每个环境中缓存。这是由于性能原因。它使用文件缓存来处理渲染的SVG文件。为了在开发环境中禁用此功能，您可能希望将其设置为数组。为了实现这一点，您可以将配置参数设置为如下
```
zicht_htmldev:
    svg_cache: array
```
其他支持选项是文件、apcu或实现PSR-16的类服务ID。

向风格指南添加内容

组件

组件是简单的Twig模板，代表项目设计的一部分，例如按钮或卡片。HtmldevBundle在htmldev/components/文件夹中寻找这些组件。在这个目录内，您可以自由地按照自己的意愿组织它们。

组件在{% strict false %}块中渲染，该块来自zicht/framework-extra-bundle，这意味着在组件内部不需要对变量进行严格的null或空检查：一个简单的{% if variable %}就足够了。

推荐：为了方便地添加条件CSS类，HtmldevBundle自动加载zicht/twig-classes辅助函数。

{% set cx = {
    article: classes({
        'u-margin--b2': image.url,
        'u-margin--b0  u-text--center': not image.url,
    })
} %}

<article class="{{ cx.article }}">
    ...
</article>

在风格指南中渲染组件

HtmldevBundle从htmldev/data/目录中的Yaml文件加载组件的示例/虚拟数据。

例如，它加载一个htmldev/data/buttons.yml。

-
    styleguide_title: Blue button
    styleguide_type: buttons/text
    text: Button
    color: blue
-
    styleguide_title: White button outline
    styleguide_type: buttons/text
    styleguide_dark: true
    outline: true
    text: Button
    color: white

这样，您可以在不输入Twig代码的情况下将组件添加到风格指南中。以styleguide_开头的键仅用于影响风格指南中组件的渲染。其他键是组件本身的属性。

风格指南中渲染的可用选项

styleguide_type 要显示的组件名称。例如，buttons/text对应于文件htmldev/components/buttons/text.html.twig。
styleguide_title 与组件一起渲染的标题。
styleguide_description 组件的额外描述，将在标题下方渲染。
styleguide_dark (true|false) 一个布尔值，指示风格指南是否应在深色背景上渲染组件，例如用于白色按钮。
styleguide_component_width 覆盖风格指南中组件的默认宽度。使用像素/百分比/视口单位更改组件的宽度，例如styleguide_component_width: 500px。或者要将在组件下方渲染代码示例，使用styleguide_component_width: full。

响应式图片组件

请参阅HTMLdev组件文件夹中的文档，了解Zicht响应式图像组件的安装和用法。

页面

该捆绑包为添加到navigation.yml的所有组件及其自己的数据Yaml文件渲染默认页面。风格指南的模板位于HtmldevBundle自己的Resources/views/styleguide/目录中，并可以在项目的htmldev/pages/目录中进行覆盖。这两个目录的结构如下。HtmldevBundle有一个基础component.html.twig模板用于所有组件。您可以在项目的htmldev/pages/目录中覆盖此模板以进行全局更改。在您的项目的htmldev/pages/目录中，您可以创建一个components/子目录，并为特定组件添加自定义模板（模板文件的基本名称部分应与Yaml文件的基本名称相同）。设计元素在HtmldevBundle中也有自己的模板，所有这些模板都基于component.html.twig模板（要么是项目htmldev/pages/目录中的模板，要么是Htmldev捆绑包中的模板）。

您还可以添加主页/介绍页，而不是在列表中的第一个组件页面上。您可以在htmldev/pages/styleguide_intro.html.twig处添加一个模板来实现这一点。然后它将被渲染为主页（在https://example.com/htmldev/ URL上）。

相对目录结构

 ./
  ├┈ (styleguide_intro.html.twig)
  ├─ component.html.twig
  ├┈ (components/)
  │  ├┈ (buttons.html.twig)
  │  ├┈ (cards.html.twig)
  │  └┈ (headers.html.twig)
  └─ design-elements/
     ├─ colors.html.twig
     ├─ icons.html.twig
     └─ typography.html.twig

添加导航

HtmldevBundle支持风格指南中的两级导航。应将构成菜单的项目添加到htmldev/data/styleguide/navigation.yml。

导航结构的示例

-
    title: Components
    uri: /htmldev/components/buttons
    items:
        -
            title: Buttons
            uri: /htmldev/components/buttons
        -
            title: Cards
            uri: /htmldev/components/cards
-
   title: Design Elements
   uri: /htmldev/design-elements/colors
   items:
       -
           title: Colors
           uri: /htmldev/design-elements/colors
       -
           title: Icons
           uri: /htmldev/design-elements/icons
       -
           title: Typography
           uri: /htmldev/design-elements/typography

颜色

HtmldevBundle风格指南页面设计元素 > 颜色将读取文件htmldev/sass/variables/_zss-overrides.scss内的颜色Sass映射，并在网格中渲染这些颜色。

该页面使用了Twig函数color_palette()，并传递了文件名_zss-overrides.scss。您可以覆盖此页面（见页面）以更改/添加它正在读取的文件。

默认颜色服务假定使用ZSS框架的变量，但您也可以使用不同的服务。请参阅自定义部分。

图标

HtmldevBundle风格指南页面“设计元素 > 图标”将在htmldev/images/icons/目录（无子目录）中渲染图标。

排版

HtmldevBundle风格指南页面“设计元素 > 字体”包含一组静态的排版元素，如<h1>、<h2>、<h3>和<h4>标题，几个<p>段落，一个带<footer>的<blockquote>引用和一些<ul>无序列表。段落和列表包含一些<a>链接。

您可以通过（见页面）覆盖此页面以自定义HTML，特别适用于您的项目。

在项目中使用风格指南

渲染组件

通过component宏（ui.component()）渲染组件已被弃用

要渲染组件，只需像下面这样使用Twig包含

这将加载具有给定属性的htmldev/components/cards/cover.html.twig

{% include '@htmldev/components/cards/cover.html.twig' with {
    title: 'Hodor',
    url: '/some/page'
} only %}

渲染SVG文件

HtmldevBundle的svg宏（ui.svg()）用于内联渲染SVG已被弃用

HtmldevBundle提供了一个inline_images过滤器，用于在字符串主题中内联渲染SVG。这允许使用currentColor和CSS轻松着色SVG。

这将渲染htmldev/images/icons/arrow--right.svg的内容

{% apply inline_images %}
    <img src="htmldev/images/icons/arrow--right.svg" width="20" height="20">
{% endapply %}

以下属性可以在<img />标签中使用

width 应设置在<svg />元素上的宽度。这将覆盖现有的width属性。过滤器假定px，因此width: 20将渲染为<svg width="20px" />。允许的值：MDN。
height 应设置在<svg />元素上的高度。这将覆盖现有的height属性。过滤器假定px，因此height: 20将渲染为<svg height="20px" />。允许的值：MDN。
viewbox-x和viewbox-y viewbox属性的x和y值。这将覆盖现有的viewbox属性。这两个参数都必须传递，否则将不会应用。例如，<img viewbox-x="20" viewbox-y="30">将渲染为<svg viewbox="0 0 20 30" />。
class 将应用到<svg />元素的CSS类列表。<img class="u-white u-block">将渲染为<svg class="u-white u-black" />。
title 这将为提高可访问性在<svg />内部添加一个<title />元素。参考：MDN
任何其他属性也将应用到<svg />元素上。这可以是任何对<svg />元素有效的属性。一些其他属性的默认值是：aria-hidden="true"和role="img"。

自定义

有几个Symfony参数可用于覆盖，以添加不同的实现。

htmldev.directory（默认：%kernel.root_dir%/../htmldev）更改风格指南目录。
htmldev.controller 处理风格指南中页面请求的控制器。
htmldev.color_service 从ZSS中的Sass变量中读取颜色的服务。要更改此工作方式，实现ColorServiceInterface类并将此参数更改为您的类。
htmldev.svg_service 返回 SVG 文件内容的程序。要更改其工作方式，请实现 SvgServiceInterface 并将此参数更改为自己的类。

替代结构

可以通过更改一些配置将所有内容从 HtmldevBundle 的默认 htmldev/ 目录移出。例如，在 Symfony 4+ 项目中遵循更行业标准化的结构

添加到 config/packages/zicht_htmldev.yaml

zicht_htmldev:
    paths:
        data: '%kernel.project_dir%/config/packages/_zicht_htmldev'
        images_icons: '%kernel.project_dir%/assets/images/icons/'
        sass_variables: '%kernel.project_dir%/assets/sass/variables/'
        svg_service_base_dir: '%kernel.project_dir%/assets/'

并相应地移动内容。

开发

CSS

此包包含一个 CSS 文件，用于为风格指南提供默认样式。

此 CSS 文件的源文件为 styleguide.scss，位于 Resources/sass 文件夹。
使用 webpack 和 node-sass 编译 Sass 文件。
使用 stylelint-config-zicht 检查 Sass 文件。

运行 npm run build 将您的功能或错误修复添加到编译的 CSS 文件中，并不要忘记将生成的文件提交到 ~/Resources/public/css。

维护者

Peter Benner (@wpbenner)
Jurg Roessen (@Hangloozz)

zicht / htmldev-bundle

维护者

详细信息