@wulechuan/hint-of-waiting-dancing-flower
v1.0.0-beta5
Published
吴乐川的等待提示：《舞动之花》。
Downloads
6
Readme
吴乐川的等待提示：《舞动之花》
中国人——特别是汉族人，理应坚持广泛、规范地使用汉语。凡非必要之情形不说外国话、不用外国字。此乃天经地义！然则每当必要，亦不排斥采用外国之语言。不妨 博世界之学问，养中国之精神 。
本人亦支持少数民族坚持采用自己民族的传统语言。仍须强调，凡中国人，皆应会用汉语、积极使用汉语，此乃中华各民族之大一统之必由。
NPM 页
@wulechuan/hint-of-waiting-dancing-flower
源代码仓库
| 提供仓库服务之组织 | 仓库组织之国别 | 仓库地址 | | ------------- | :----------: | ------- | | 码云 | 中华人民共和国 | https://gitee.com/nanchang-wulechuan/hint-of-waiting--dancing-flower |
简介
此乃一种【界面部件】，其可用于提示用户应等待某种过程结束。其遵循 Vuejs 3.x ， 采用 TypeScript 语言写成。其面向采用 Vuejs 3.x 编写网页程序的开发者，而非普通用户。
术语
术语概述
本文有少数概念较为关键。为减少乃至消除歧义，先为各概念约定术语。部分术语为本人之拙见，未必见于其他文章或材料。
术语表
【部件】
外国话所谓 component 。其它文章或材料多译为【组件】。但本部件及相关文档坚持称【部件】。
用法（针对开发者）
安装
npm --registry=https://registry.npmmirror.com i @wulechuan/hint-of-waiting-dancing-flower编程用法概述
本部件源代码仓库随附的完整编程示范
示例集/
注意！发布的 npm 包并不包含上述示范代码。
在线示例
简短的示例 1 ， 借助 Vuejs 框架时的用法
功能逻辑的写法示范（采用 TypeScript 语言）
import Wulechuan_HintOfWaiting_DancingFlower from '@wulechuan/hint-of-waiting-dancing-flower'类 HTML 模板的写法示范
<Wulechuan_HintOfWaiting_DancingFlower :petalsCount="7" :hasNoColorAnimations="true" :petalsColorWhenNoColorAnimations="'#ff9'" :shouldPaintPetalsFlat="true" :laysOverDarkBackground="true" />使用该部件时层叠样式表的写法
见下文《本部件内建的层叠样式表的用法》一节。
简短的示例 2 ， 故意摆脱 Vuejs 框架时的用法
HTML 骨架示例
<div class="wulechuan--hint-of-waiting--dancing-flower has-color-animations should-paint-petals-flat lays-over-dark-background" style="--wulechuan-dancing-flower--petals-total-count: 9;" > <div class="corolla"> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> <span class="petal-locator"><i class="petal"></i></span> </div> </div>引用层叠样式表
相对路径：
源/index.css。
应用编程接口（外国话所谓 API）
Vuejs 3.x 模板的完整写法
下方用于描述接口之代码采用 Vuejs 的默认模板语言撰写。
<Wulechuan_HintOfWaiting_DancingFlower
:petalsCount="9"
:hasNoColorAnimations="false"
:petalsColorWhenNoColorAnimations="'#d468b7'"
:shouldMirrorLookAndFeel="false"
:shouldBlurPetalsDuringAnimations="false"
:shouldPaintPetalsFlat="false"
:laysOverDarkBackground="false"
/>TypeScript 接口
export type 范_吴乐川的等待提示_舞动之花_Vue部件之Props = {
petalsCount?: number;
hasNoColorAnimations?: boolean;
petalsColorWhenNoColorAnimations?: string;
shouldMirrorLookAndFeel?: boolean;
shouldBlurPetalsDuringAnimations?: boolean;
shouldPaintPetalsFlat?: boolean;
laysOverDarkBackground?: boolean;
};petalsCount。顾名思义。 默认值为
9，最小值为3，最大值为36。hasNoColorAnimations。顾名思义。
默认取
false。petalsColorWhenNoColorAnimations。顾名思义。
无默认值。
shouldMirrorLookAndFeel。顾名思义。
默认取
false。shouldBlurPetalsDuringAnimations。顾名思义。
默认取
false。shouldPaintPetalsFlat。顾名思义。
默认取
false。laysOverDarkBackground。顾名思义。
默认取
false。
本部件内建的层叠样式表的用法
层叠样式表综述
本部件之主旨为设计一朵可以动态变化的花朵。故涉及 CSS 动画。
从文档对象模型层面来讲，一朵花总体分三个大的层级，依次为：
【花朵】。
此乃文档对象模型的根基对象，系一个透明无色的正方形。它视觉上不可见，但决定着花朵整体在文档中的排版占位。
又，从技术层面讲，为求方便，【花瓣相】的色彩动画也借由【花朵】来“承载”。
【花冠】。
一个【花朵】包含唯一的【花冠】。
花瓣。
一个【花冠】包含多个花瓣。
因 CSS 动画技术所限，欲设计复杂的动画，须在文档对象模型中为每片花瓣设计多重结构。 具体而言，每片花瓣有三层结构，依次如下：
所谓【花瓣辐向排布尺】，
span.petal-locator。其用于在 360 度范围内等角排布所有的【花瓣平动器】。以确保【花瓣平动器】可沿【花冠】辐向运动。
【花瓣辐向排布尺】无动画。
又，为求便捷，【花瓣辐向排布尺】还负责：
借助
:nth-child()为诸花瓣分配序号，存放在--wulechuan-dancing-flower--petal--index-from-zeroCSS 变量（实际上是常量）中。其中，
:nth-child(1)的--wulechuan-dancing-flower--petal--index-from-zero取0;:nth-child(2)的--wulechuan-dancing-flower--petal--index-from-zero取1。以此类推。根据上文分配的
--wulechuan-dancing-flower--petal--index-from-zero, 求得该片花瓣自身的--wulechuan-dancing-flower--petal--values-common-ratioCSS 变量值（实际上是常量）。该值由花瓣自身序号除以花瓣总数而得。
所谓【花瓣平动器】，
i.petal。恰因动画复杂，层次嵌套，故真正视觉上表达花瓣的并非【花瓣平动器】，而是下文的【花瓣相】。而此所谓【花瓣平动器】实则是零像素宽、零像素高的一个点。起作用是承载辐向动画。仅此而已。
【花瓣平动器】有动画。
所谓【花瓣相】，
i.petal::before。此乃花瓣的最终视觉表达。花瓣的造型、颜色均在此文档对象上体现。
【花瓣相】有较复杂的动画。其动画由以下变化合成：
- 原地翻滚（实则旋转）。
- 尺寸变化。
- 圆角曲率变化。
- 模糊程度变化。
【花瓣平动器】和【花瓣相】的动画的时间安排也是略微复杂的。 这是因为，依据设计初衷，从最终视觉效果上讲，花瓣动画的单个周期须分两个阶段：【脉动】阶段和【平静】阶段。 其中，【脉动】阶段又分两个小节：【舒展】和【收缩】。
又，为了实现所谓“【平静】阶段”，单个【花瓣平动器】的动画末尾故意留有一段时间，数值变化微小或无变化， 故实际上可见的动画效果或微弱或全无。
综上，一片花瓣的动画，单个周期总共分三个步骤：【舒展】、【收缩】和【平静】。
由此，单个【花瓣平动器】、【花瓣相】的动画均由上述 3 个阶段分割得到 4 个时刻，如下：
- Moment0 - 单个动画周期开始，亦即开始【舒展】。
- Moment1 - 【舒展】之至，开始【收缩】。
- Moment2 - 【收缩】完毕，开始所谓平静的动画。
- Moment3 - 单个动画周期结束。
又， 尽管从数学上讲 Moment0 和 Moment3 可视作同一时刻， 但从动画设计的角度讲则并非如此，二者不应混淆。
另，须知，【花瓣平动器】、【花瓣相】的动画周期时长并不相同。
注意， CSS 动画不允许在动画周期之间设计间隔期， 因此，若欲实现上述所谓平静阶段，须故意在动画周期内留有特定的时长。
本部件层叠样式表的基本用法
采用 Sass 语言加载本部件的样式集。
@use '@wulechuan/hint-of-waiting-dancing-flower/源';采用 TypeScript 语言加载本部件的样式集。
import '@wulechuan/hint-of-waiting-dancing-flower/index.scss'须知，采用 TypeScript 语言加载本部件的样式集，须用到额外的打包工具，例如
Vitejs或Webpackjs等。
本部件层叠样式表类名表
根基，凡必备者：
.wulechuan--hint-of-waiting--dancing-flower
根基，凡可按需选用者：
._allows_debugging。所谓“内部”样式表类名。用户（指开发者）一般不涉及之。
互斥组：
.has-color-animations与.has-no-color-animations顾名思义。
在采用 Vuejs 而非采用 vanillajs 时，该项受
范_吴乐川的等待提示_舞动之花_Vue部件之Props['hasNoColorAnimations']字段的控制。若字段取true，则采用.has-no-color-animations样式类名`；反之。.should-mirror-look-and-feel顾名思义。
在采用 Vuejs 而非采用 vanillajs 时，该项受
范_吴乐川的等待提示_舞动之花_Vue部件之Props['shouldMirrorLookAndFeel']字段的控制。若字段取true，则该样式类名会采用；反之。注意：当采取此项时，非但诸花瓣造型（目前仅涉及
border-radius）、运动方向、朝向等会反转，诸花瓣透明度依次分配的梯度方向也会反转。.should-blur-petals-during-animations。顾名思义。
互斥组：
.should-paint-petals-flat与.should-paint-petals-wet。- 当采用
.should-paint-petals-flat时，花瓣着色为平涂的纯色。 - 当采用
.should-paint-petals-wet时，花瓣着色好似毛笔湿画法的效果。从技术上讲，令background-color纯透明，且借助box-shadow着色。
在采用 Vuejs 而非采用 vanillajs 时，该项受
范_吴乐川的等待提示_舞动之花_Vue部件之Props['shouldPaintPetalsFlat']字段的控制。若字段取true，则采用.should-paint-petals-flat样式类名`；反之。- 当采用
互斥组：
.lays-over-light-background与.lays-over-dark-background。顾名思义。
在采用 Vuejs 而非采用 vanillajs 时，该项受
范_吴乐川的等待提示_舞动之花_Vue部件之Props['laysOverDarkBackground']字段的控制。若字段取true，则采用.lays-over-dark-background样式类名`；反之。
内层：
.corolla。 此乃【花冠】。.petal-locator。 此乃花瓣的第 1 层结构，即【花瓣辐向排布尺】。.petal。 此乃花瓣的第 2 、 3 层结构，即【花瓣平动器】和【花瓣相】。其中，所谓【花瓣相】由::before做成。
层叠样式表变量（外国话所谓 CSS Variables）表
总体变量。
--wulechuan-dancing-flower--petals-total-count。顾名思义。默认取
9。--wulechuan-dancing-flower--flower-layout-square-size。顾名思义。默认取
4rem。--wulechuan-dancing-flower--anything-length-ref-size。此为所谓【基本度量尺寸】。 它就像一个标准比例尺，花瓣的各种实用尺度，例如宽度、高度、动画偏移量、乃至模糊半径等， 都是相对于该值的比例（或曰倍数）。
这样的设计（指额外引入所谓的基本度量尺寸）便于整体控制。
默认取
--wulechuan-dancing-flower--flower-layout-square-size的一半。--wulechuan-dancing-flower--anything-transformation-common-multiplier。该变量系所谓“内部”变量。用户（指开发者）一般不涉及之。该变量要么取
1，要么取-1。--wulechuan-dancing-flower--petal-radical-travelling-duration。此乃【花瓣平动器】平动动画的时长。同时，默认情形下它也是其他动画（例如【花瓣相】的复杂动画）时长的基准值，换言之，默认情形下其他动画时长取此值之某个倍数。
默认取
8s。
【花冠】的变量。
--wulechuan-dancing-flower--corolla-rotation-animation-end-angle-abs-value。此为【花冠】在其单个动画周期结束时，旋转达到的角度。
默认值取
360deg。又，我认为该值没必要变动。因为，每若欲调节【花冠】旋转的速度， 不妨改动
--wulechuan-dancing-flower--corolla-spinning-duration一值， 而不是改动该角度。--wulechuan-dancing-flower--corolla-spinning-duration。顾名思义。
默认取
--wulechuan-dancing-flower--petal-radical-travelling-duration的0.66667倍。
花瓣的变量第 1 组：根基性的变量。
--wulechuan-dancing-flower--petal--index-from-zero。--wulechuan-dancing-flower--petal--values-common-ratio。--wulechuan-dancing-flower--petal--animation-delay-ratio-per-petal。【花瓣平动器】与其自身【花瓣相】各自有动画，且此两类动画时长不一。 为求丰富的视觉效果，还可令两类结构的动画依序有不同的动画延迟。
此变量即为动画延迟的时长比率。 在为每片花瓣的【花瓣平动器】、【花瓣相】计算动画延迟时长时， 即会用到该 CSS 变量的值。
简言之，花瓣动画的延迟是逐片递增的。 易知，若该 CSS 变量值取
0s， 则所有花瓣的动画是同步的。又，该 CSS 变量取负数为宜。 若取正数，则花朵呈现伊始，会有花瓣僵住片刻，因为这些花瓣在等待自身动画开始播放。
默认取
-0.0088。--wulechuan-dancing-flower--petal-self-complex-animation-duration。【花瓣相】的动画时长。
默认取
--wulechuan-dancing-flower--petal-radical-travelling-duration的0.5倍。
花瓣的变量第 2 组：控制细节的变量。
小组 1 ： 控制诸花瓣的颜色与透明度。
--wulechuan-dancing-flower--petals-color-when-no-color-animations。顾名思义。
默认取
#d468b7，这是一种稍淡的品红色。--wulechuan-dancing-flower--petals-colors-varying-duration。顾名思义。
默认取
--wulechuan-dancing-flower--petal-radical-travelling-duration的1.9倍。该值取非整数被，可故意令色彩变化与运动、形状的变化失步，以营造更丰富的视觉效果。 倘若令该值为整数，则【花瓣相】总是在固定的动画阶段采用固定的色彩，则视觉效果反而呆板。
--wulechuan-dancing-flower--petals-animated-colors-common-lightness。顾名思义。
无全局性的默认值。 当采用
.lays-over-light-background样式类目时，默认值取35%。 当采用.lays-over-dark-background样式类目时，默认值取55%。--wulechuan-dancing-flower--petals-animated-colors-common-saturation。顾名思义。
无全局性的默认值。 当采用
.lays-over-light-background样式类目时，默认值取100%。 当采用.lays-over-dark-background样式类目时，默认值取100%。--wulechuan-dancing-flower--petal-opacity-of-first-petal。顾名思义。
默认取
0.23。--wulechuan-dancing-flower--petal-opacity-of-last-petal。顾名思义。
默认取
0.79。
小组 2 ： 控制诸【花瓣相】的尺寸与造型。
--wulechuan-dancing-flower--petal-border-radii-at-moment0and3。顾名思义。
默认取
50%。--wulechuan-dancing-flower--petal-border-radii-at-moment1。顾名思义。
默认取
var(--wulechuan-dancing-flower--petal-border-radii-at-moment1-default-value)。 见下文。--wulechuan-dancing-flower--petal-border-radii-at-moment1-default-value。当花朵的样貌于动态配置为“应反转”时，所涉
border-radius值也须反转。 又，border-radius值须用于动画设计（@keyframes）。 为避免针对不同的样式类名反复书写动画代码（即指@keyframes），同时确保不污染外界可能“覆盖”的值， 我设计了所谓两级 CSS 变量，--????-at-moent1-default-value和--????-at-moment1。全局性的默认值为
60% 40% 60% 40%。 在采用.should-mirror-look-and-feel样式类目时，默认值为40% 60% 40% 60%。--wulechuan-dancing-flower--petal-border-radii-at-moment2。顾名思义。
默认取
var(--wulechuan-dancing-flower--petal-border-radii-at-moment2-default-value)。 见下文。--wulechuan-dancing-flower--petal-border-radii-at-moment2-default-value。当花朵的样貌于动态配置为“应反转”时，所涉
border-radius值也须反转。 又，border-radius值须用于动画设计（@keyframes）。 为避免针对不同的样式类名反复书写动画代码（即指@keyframes），同时确保不污染外界可能“覆盖”的值， 我设计了所谓两级 CSS 变量，--????-at-moent2-default-value和--????-at-moment2。全局性的默认值为
3% 97% 3% 97%。这令单片花瓣造型为橄榄型，看起来并不像花瓣，而像叶子。 在采用.should-mirror-look-and-feel样式类目时，默认值为97% 3% 97% 3%。--wulechuan-dancing-flower--petal-size-ratio-along-x-axis-at-moment0and3。顾名思义。
默认取
1。--wulechuan-dancing-flower--petal-size-ratio-along-y-axis-at-moment0and3。顾名思义。
默认取
1。--wulechuan-dancing-flower--petal-size-ratio-along-x-axis-at-moment1。顾名思义。
默认取
0.84。--wulechuan-dancing-flower--petal-size-ratio-along-y-axis-at-moment1。顾名思义。
默认取
1.08。--wulechuan-dancing-flower--petal-size-ratio-along-x-axis-at-moment2。顾名思义。
默认取
0.79。--wulechuan-dancing-flower--petal-size-ratio-along-y-axis-at-moment2。顾名思义。
默认取
0.63。
小组 3 ： 控制诸【花瓣平动器】沿【花冠】辐向的位移动画。
注：
--wulechuan-dancing-flower--petal-radical-travelling-duration一项故意未列示于此小目。 见本文《总体变量》一目。--wulechuan-dancing-flower--petal-radical-offset-ratio-at-moment0and3。顾名思义。
默认取
0.45。--wulechuan-dancing-flower--petal-radical-offset-ratio-at-moment1。顾名思义。
默认取
0.9。--wulechuan-dancing-flower--petal-radical-offset-ratio-at-moment2。顾名思义。
默认取
0.55。
小组 4 ： 控制诸【花瓣相】各自的旋转。
--wulechuan-dancing-flower--petal-spinning-degrees-at-moment0。顾名思义。
默认取
0deg。--wulechuan-dancing-flower--petal-spinning-degrees-at-moment1。顾名思义。
默认取
144deg。--wulechuan-dancing-flower--petal-spinning-degrees-at-moment2。顾名思义。
默认取
501deg。--wulechuan-dancing-flower--petal-spinning-degrees-at-moment3。顾名思义。
默认取
720deg。
小组 5 ： 控制诸花瓣在动画过程中的模糊效果。
--wulechuan-dancing-flower--petal-blur-radius-at-moment0and3。--wulechuan-dancing-flower--petal-blur-radius-at-moment1。--wulechuan-dancing-flower--petal-blur-radius-at-moment2。
未来计划
尚无。
许可证类型
WTFPL
注意：
我未研究过许可证的约束。因此姑且声明为 WTFPL 类型。但实际上该许可证类型可能与我采用的开源模块有冲突。