@acanto/frontend 中文文档教程

发布于 4年前 浏览 20 项目主页 更新于 3年前

Acanto Frontend

npm (scoped)

工具库、实用程序、组件e altro per lo sviluppo frontend dei siti di Acanto @acanto/frontend

L'idea è quella di avere piccoli componenti facilmente riutilizzabili senza dover sovrascrivere comportamenti CSS o JS nei singoli progetti。 Tutto ciò che 包括 questa libreria deve quindi essere scarno e generico e buttar fuori il minor codice possibile。

Quando utilizzi questa libreria è bene quindi selezionare con cura i vari componenti e parti di componenti che si vogliono includesre nel progetto in corso.

Struttura

Styles

Tutta la parte di CSS è scritta in SCSS prediligendo mixin e placeholder di modo che anche se inclusi non generino codice fino al loro utilizzo esplicito。

Scripts

Il JavaScript di questa libreria deve rimanere in codice nativo, senza framework o librerie troppo complesse。 Nel moment in cui queste sono necessarile l'importante è scrivere la libreria di modo che il tree shaking elimini la possibilità di inclusione involontaria di librerie e grossi blocchi di codice inutili。

Templates

我组件 che hanno bisogno di un template da usare in October usano qui un file .twig (o .php se necessario) d'esempio in quanto non possono essere integrati in maniera automatica nel progetto all'interno del CMS。 Sarà quindi necessario copiare/incollare/modificare a piacimento il template nella cartella /frontend/components/ o /frontend/core (quest'ultimi possono essere sincronizzati in quest'ultima tramite @acanto/workflow con il comando acanto core-sync)。 关于使用嵌套子项组合 .twig 组件,请参阅建议的解决方案SO/ em>

Code conventions

Class names

core

Core 元素非常通用并且具有常见的用例。 它们通常在同一页面和同一网站中重复使用。 它们的灵活性应该允许在不同项目中使用它们,即使没有改变。 他们实际上应该负责基本和常见的元素和 UI,例如 formsimagesbuttonstypography、 ECC。 他们的类命名遵循以下模式:

.myClass
.myClassInner
.myClass--modifier

components

Components 是非常具体的 UI 片段,通常在同一项目中重复使用,并且可以但不一定需要在不同项目中重复使用。 他们应该负责特定的功能,并且应该可以从外部进行配置,以允许在同一个项目中重复使用。 组件的常见用例是 UI 片段,例如 HeaderFooterCardSlider、 ECC。 它们的类命名遵循以下模式:

.Mycomponent:
.Mycomponent:block
.Mycomponent:block--modifier
.Mycomponent:block__element
.Mycomponent:block__elementInner
.Mycomponent:block__element--modifier

routes

Routes 包含始终限定范围并仅输出到其特定模板的代码。 所以这里写的JS和SCSS代码默认是不能干扰其他路由/页面的。 将页面划分为多个部分并为它们命名以组织代码通常很方便。 页面的部分通常类似于 .intro:.details:.products:.featured:等。它们的类命名遵循以下模式:

.pagesection:
.pagesection:block
.pagesection:block--modifier
.pagesection:block__element
.pagesection:block__elementInner
.pagesection:block__element--modifier

Notes

Class names for state and behaviour

表示状态或行为的类名更短且具有描述性,例如:

.is-visible
.has-link
.has-img
.is-doubled
.is-even
.when-vertical
etc.

Regarding the use of column :

SCSS 中,: 需要用反斜杠转义Mycomponent\:,而在 JS 中使用 $$$escape处理 DOM 选择器的函数 : 列自动转义。 否则它需要像 querySelector(".Mycomponent\\:") 一样被转义。

Note per lo sviluppo di progetti con @acanto/frontend

GSAP

Per usare GSAP premium inanzitutto scaricare lo zip GSAP with Shockingly Green bonus dalla dashboard di greensock.com

  • scompattare lo zip, trovare e copiare il file gsap-bonus.tgz così com'è nel progetto in corso. Possibilmente copiarlo nel path frontend/vendor/gsap-bonus.tgz
  • nelle dependencies del package.json del progetto in corso aggiungere questa voce con il path giusto:
"dependencies": {
  ...
  "gsap": "file:frontend/vendor/gsap-bonus.tgz"
}
  • lanciare npm install o npm i
  • nel file JavaScript dove si intende usarlo fare un normale import e registrare i plugin che si vuole utilizzare per evitare problemi di tree shaking nella futura build di production. Ad esempio:
import gsap from "gsap";
import CSSPlugin from "gsap/CSSPlugin";
import SplitText from "gsap/SplitText";

gsap.registerPlugin(CSSPlugin, SplitText);
  • a posto.

公证 è che il 文件 frontend/vendor/gsap-bonus.tgz deve rimanere nel repository e su git altrimenti la CI non sa dove andarlo a prendere non essendo pubblica questa libreria .

Note riguardo allo sviluppo interno di questa libreria

  • To develop and use the library locally (through npm link) and get the Intellisense of VScode to work first install npm install -g linklocal then cd into-your-project and run linklocal -r, see related issue
  • About tree shacking, sideEffects and unused modules see webpack's side-effects, harmony-unused and see this issue with css imports
  • About GreenShock premium plugin being on npm, see this thread
  • We might use SimpleStateManager to use media queries in javascript, populating its states with the exported sass variables.
  • Parallax scrolling well done with CSS variables basicScroll or Rellax
  • For masonry like grid infiniteGrid seems ok.
  • For simple SSR components abstraction see gia
  • For SPA like behaviour try Stimulus with Turbolinks
  • TODO:
  • use new isType functions where appropriate
  • Maybe use https://www.npmjs.com/package/throttle-debounce instead of lodash ones
  • Incorporate autocomplete in library as abstraction

Documentazione

  • Aggiungere descrizione del modulo visibile quando fai hover sull import /// <reference path='./index.d.ts' />

Acanto Frontend

npm (scoped)

Libreria di strumenti, utility, componenti e altro per lo sviluppo frontend dei siti di Acanto @acanto/frontend.

L'idea è quella di avere piccoli componenti facilmente riutilizzabili senza dover sovrascrivere comportamenti CSS o JS nei singoli progetti. Tutto ciò che include questa libreria deve quindi essere scarno e generico e buttar fuori il minor codice possibile.

Quando utilizzi questa libreria è bene quindi selezionare con cura i vari componenti e parti di componenti che si vogliono includere nel progetto in corso.

Struttura

Styles

Tutta la parte di CSS è scritta in SCSS prediligendo mixin e placeholder di modo che anche se inclusi non generino codice fino al loro utilizzo esplicito.

Scripts

Il JavaScript di questa libreria deve rimanere in codice nativo, senza framework o librerie troppo complesse. Nel momento in cui queste sono necessarie l'importante è scrivere la libreria di modo che il tree shaking elimini la possibilità di inclusione involontaria di librerie e grossi blocchi di codice inutili.

Templates

I componenti che hanno bisogno di un template da usare in October usano qui un file .twig (o .php se necessario) d'esempio in quanto non possono essere integrati in maniera automatica nel progetto all'interno del CMS. Sarà quindi necessario copiare/incollare/modificare a piacimento il template nella cartella /frontend/components/ o /frontend/core (quest'ultimi possono essere sincronizzati in quest'ultima tramite @acanto/workflow con il comando acanto core-sync). About composing .twig components with nested children see the solution suggested on SO

Code conventions

Class names

core

Core elements are very generic and of common use case. They are usually used repeatedly in the same page and across the same website. Their flexibility should allow to use them even without alteration across different projects. They should be in fact responsible of basic and common elements and UI like forms, images, buttons, typography, ecc. Their class naming follows this pattern:

.myClass
.myClassInner
.myClass--modifier

components

Components are quite specific pieces of UI that are usually reused within the same project and can, but not necessarily need, to be reused accross different projects. They should be responsible of specific functionalities and should be configurable from outside enought to allow their reuse in the same project. Usual use cases for components are pieces of UI like the Header, the Footer, Cards, Sliders, ecc. Their class naming follows this pattern:

.Mycomponent:
.Mycomponent:block
.Mycomponent:block--modifier
.Mycomponent:block__element
.Mycomponent:block__elementInner
.Mycomponent:block__element--modifier

routes

Routes contain code that is always scoped and outputted only to its specific template. So by default JS and SCSS code written here cannot interfere with other routes/pages. It's often handy to divide a page in sections and namespace them to organize the code. Sections of a page often look like .intro:, .details:, .products:, .featured:, etc. Their class naming follows this pattern:

.pagesection:
.pagesection:block
.pagesection:block--modifier
.pagesection:block__element
.pagesection:block__elementInner
.pagesection:block__element--modifier

Notes

Class names for state and behaviour

Class names that denote states or behaviour are shorter and descriptive like:

.is-visible
.has-link
.has-img
.is-doubled
.is-even
.when-vertical
etc.

Regarding the use of column :

In SCSS the : needs to be escaped by a backslash as such Mycomponent\:, while in JS using the $ or $$ or escape functions to deal with DOM selectors the column : is automatically escaped. Otherwise it needs to be escaped as such querySelector(".Mycomponent\\:").

Note per lo sviluppo di progetti con @acanto/frontend

GSAP

Per usare GSAP premium inanzitutto scaricare lo zip GSAP with Shockingly Green bonus dalla dashboard di greensock.com

  • scompattare lo zip, trovare e copiare il file gsap-bonus.tgz così com'è nel progetto in corso. Possibilmente copiarlo nel path frontend/vendor/gsap-bonus.tgz
  • nelle dependencies del package.json del progetto in corso aggiungere questa voce con il path giusto:
"dependencies": {
  ...
  "gsap": "file:frontend/vendor/gsap-bonus.tgz"
}
  • lanciare npm install o npm i
  • nel file JavaScript dove si intende usarlo fare un normale import e registrare i plugin che si vuole utilizzare per evitare problemi di tree shaking nella futura build di production. Ad esempio:
import gsap from "gsap";
import CSSPlugin from "gsap/CSSPlugin";
import SplitText from "gsap/SplitText";

gsap.registerPlugin(CSSPlugin, SplitText);
  • a posto.

Da notare è che il file frontend/vendor/gsap-bonus.tgz deve rimanere nel repository e su git altrimenti la CI non sa dove andarlo a prendere non essendo pubblica questa libreria.

Note riguardo allo sviluppo interno di questa libreria

  • To develop and use the library locally (through npm link) and get the Intellisense of VScode to work first install npm install -g linklocal then cd into-your-project and run linklocal -r, see related issue
  • About tree shacking, sideEffects and unused modules see webpack's side-effects, harmony-unused and see this issue with css imports
  • About GreenShock premium plugin being on npm, see this thread
  • We might use SimpleStateManager to use media queries in javascript, populating its states with the exported sass variables.
  • Parallax scrolling well done with CSS variables basicScroll or Rellax
  • For masonry like grid infiniteGrid seems ok.
  • For simple SSR components abstraction see gia
  • For SPA like behaviour try Stimulus with Turbolinks
  • TODO:
  • use new isType functions where appropriate
  • Maybe use https://www.npmjs.com/package/throttle-debounce instead of lodash ones
  • Incorporate autocomplete in library as abstraction

Documentazione

  • Aggiungere descrizione del modulo visibile quando fai hover sull import /// <reference path='./index.d.ts' />
    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文