From 2ae398d7bd9e7c1983da7ea49be77c5e083d3516 Mon Sep 17 00:00:00 2001 From: Lyra <1170158548@qq.com> Date: Fri, 19 Sep 2025 21:11:44 +0800 Subject: [PATCH] feat(theme): [motion] refine the configuration md --- examples/sites/demos/pc/menus.js | 5 + .../pc/webdoc/motion-configuration-en.md | 183 ++++++++++++++ .../demos/pc/webdoc/motion-configuration.md | 183 ++++++++++++++ .../src/motion/configuration-maintenance.md | 147 ------------ .../theme/src/motion/global-configuration.md | 225 ------------------ 5 files changed, 371 insertions(+), 372 deletions(-) create mode 100644 examples/sites/demos/pc/webdoc/motion-configuration-en.md create mode 100644 examples/sites/demos/pc/webdoc/motion-configuration.md delete mode 100644 packages/theme/src/motion/configuration-maintenance.md delete mode 100644 packages/theme/src/motion/global-configuration.md diff --git a/examples/sites/demos/pc/menus.js b/examples/sites/demos/pc/menus.js index 66d4c44f7c..f87701e0b6 100644 --- a/examples/sites/demos/pc/menus.js +++ b/examples/sites/demos/pc/menus.js @@ -42,6 +42,11 @@ const docMenusChildren = [ 'titleEn': 'theme-dark', 'key': 'theme-dark' }, + { + 'title': '全局动效配置', + 'titleEn': 'motion-configuration', + 'key': 'motion-configuration' + }, { 'title': '智能化', 'titleEn': 'mcp', diff --git a/examples/sites/demos/pc/webdoc/motion-configuration-en.md b/examples/sites/demos/pc/webdoc/motion-configuration-en.md new file mode 100644 index 0000000000..ce81d36bd2 --- /dev/null +++ b/examples/sites/demos/pc/webdoc/motion-configuration-en.md @@ -0,0 +1,183 @@ +# TinyVue Global Motion Configuration + +This solution provides **global motion configuration** for TinyVue, based on **LESS and CSS variables**, with the following goals: + +1. **Unified Management**: All motions are centrally maintained to avoid scattered definitions and redundant work. +2. **Global Control**: Use CSS variables to control motion duration, delay, speed, and other parameters. +3. **Component Integration**: Components can directly use the unified motion class names or `@keyframes`. +4. **Dynamic Adjustability**: Switch motion styles for different scenarios simply by overriding CSS variables. + +## Global Configuration + +### Global Variable Definition + +Define motion variables in `/packages/theme/src/base/vars.less`: + +```less +:root { + /* Ants (marching border) related config */ + --tv-motion-ants-shift: 8px; + --tv-motion-ants-speed: 0.8s; + + /* Other motion parameters... */ +} +``` + +Developers can override these variables in the component theme file: + +```css +.copyed-borders { + --tv-motion-ants-shift: 12px; + --tv-motion-ants-speed: 1.2s; +} +``` + +Or create a `motion-theme.less` file under `/packages/theme/src/base/` to switch global motion styles: + +```less +:root { + --tv-motion-ants-shift: 12px; + --tv-motion-ants-speed: 1.2s; +} +``` + +## Motion Categories & Directory Structure + +All motions are stored in `/packages/theme/src/motion/`, organized by type: + +``` +motion/ + ├─ fade.less // Fade in/out + ├─ slide.less // Slide + ├─ zoom.less // Zoom + ├─ rotate.less // Rotate + ├─ bounce.less // Bounce + ├─ scroll.less // Scroll + ├─ stroke.less // Stroke + ├─ shine.less // Shine + ├─ ants.less // Ants (marching border) + ├─ arrow.less // Arrow + ├─ tab.less // Tab switching + ├─ progress.less // Progress bar + └─ index.less // Unified import +``` + +## Motion Examples + +### 1. Fade (fade.less) + +```less +@keyframes fade-in { + 0% { opacity: 0; } + 100% { opacity: 1; } +} + +@keyframes fade-out { + 0% { opacity: 1; } + 100% { opacity: 0; } +} +``` + +Component usage example: + +```less +.@{fade-prefix-cls} { + &-enter-active { + animation: var(--tv-motion-fade-speed) fade-in ease-out both; + } + &-leave-active { + animation: var(--tv-motion-fade-speed) fade-out ease-in both; + } +} +``` + +### 2. Slide (slide.less) + +```less +@keyframes slide-left-in { + 0% { opacity: 0; transform: translateX(var(--tv-motion-slide-offset-left)); } + 50% { opacity: var(--tv-motion-slide-opacity-mid); transform: translateX(var(--tv-motion-slide-offset-left-mid)); } + 100% { opacity: 1; transform: translateX(0%); } +} + +@keyframes slide-left-out { + 0% { opacity: 1; transform: translateX(0%); } + 50% { opacity: var(--tv-motion-slide-opacity-mid); transform: translateX(var(--tv-motion-slide-offset-left-mid)); } + 100% { opacity: 0; transform: translateX(var(--tv-motion-slide-offset-left)); } +} +``` + +Component usage example: + +```less +.drawer-slide-left-enter-active { + animation: slide-left-in var(--tv-motion-slide-speed) linear; +} +.drawer-slide-left-leave-active { + animation: slide-left-out var(--tv-motion-slide-speed) linear; +} +``` + +### 3. Ants (ants.less, configurable) + +```less +@keyframes ants-x { + 0% { background-position: 0 0; } + 100% { background-position: var(--tv-motion-ants-shift, 8px) 0; } +} + +@keyframes ants-x-rev { + 0% { background-position: 0 0; } + 100% { background-position: calc(-1 * var(--tv-motion-ants-shift, 8px)) 0; } +} +``` + +Component usage example: + +```less +.@{grid-prefix-cls}-copyed-borders { + --tv-motion-ants-shift: 13px; + + .@{grid-prefix-cls}-border-top { + animation: ants-x var(--tv-motion-ants-speed) linear infinite; + } + .@{grid-prefix-cls}-border-right { + animation: ants-y var(--tv-motion-ants-speed) linear infinite; + } + .@{grid-prefix-cls}-border-bottom { + animation: ants-x-rev var(--tv-motion-ants-speed) linear infinite; + } + .@{grid-prefix-cls}-border-left { + animation: ants-y-rev var(--tv-motion-ants-speed) linear infinite; + } +} +``` + +## Component Integration + +1. **Global Import** + All `@keyframes` are maintained in `transition.less` and `motion/*`, and loaded together. + +2. **Local Usage** + Components can use the motions via `className` or `animation`. + +3. **Configurable Parameters** + Developers can override `:root` variables to adjust motion duration, speed, and other parameters. + +## Extension & Maintenance + +1. **Naming Convention** + + * Use `{type}-{direction}-{state}` format, e.g., `slide-left-in`. + * Ensure global uniqueness to avoid conflicts. + +2. **Category Management** + + * Motions must be written in the corresponding category file (e.g., slide → `slide.less`). + * New variables must be declared in `index.less` first, then used in the specific file. + +3. **Documentation & Comments** + + * Each motion category should provide example code and usage instructions. + * Add comments before `@keyframes` to indicate purpose and source. + * Group related motions together for easier lookup and maintenance. diff --git a/examples/sites/demos/pc/webdoc/motion-configuration.md b/examples/sites/demos/pc/webdoc/motion-configuration.md new file mode 100644 index 0000000000..b7bb0e7717 --- /dev/null +++ b/examples/sites/demos/pc/webdoc/motion-configuration.md @@ -0,0 +1,183 @@ +# TinyVue 全局动效配置 + +为 TinyVue 提供 **全局动效配置能力**，基于 **LESS 与 CSS 变量**，实现以下目标： + +1. **统一管理**：所有动效集中维护，避免分散定义与重复工作。 +2. **全局可控**：通过 CSS 变量统一控制动效的持续时间、延迟、速度等参数。 +3. **组件集成**：组件可直接调用统一的动效类名或 `@keyframes`。 +4. **动态可调**：通过覆盖 CSS 变量即可在不同场景下切换动效风格。 + +## 全局配置 + +### 全局变量定义 + +在 `/packages/theme/src/base/vars.less` 中统一定义动效变量： + +```less +:root { + /* 蚂蚁线相关配置 */ + --tv-motion-ants-shift: 8px; + --tv-motion-ants-speed: 0.8s; + + /* 其他动效参数... */ +} +``` + +开发者可在组件主题文件中覆盖这些变量： + +```css +.copyed-borders { + --tv-motion-ants-shift: 12px; + --tv-motion-ants-speed: 1.2s; +} +``` + +也可通过在 `/packages/theme/src/base/` 下创建 `motion-theme.less` 来切换全局动效风格： + +```less +:root { + --tv-motion-ants-shift: 12px; + --tv-motion-ants-speed: 1.2s; +} +``` + +## 动效分类与目录结构 + +所有动效存放在 `/packages/theme/src/motion/` 目录下，按类型拆分： + +``` +motion/ + ├─ fade.less // 淡入淡出 + ├─ slide.less // 滑动 + ├─ zoom.less // 缩放 + ├─ rotate.less // 旋转 + ├─ bounce.less // 弹跳 + ├─ scroll.less // 滚动 + ├─ stroke.less // 描边 + ├─ shine.less // 闪烁 + ├─ ants.less // 蚂蚁线 + ├─ arrow.less // 箭头 + ├─ tab.less // Tab 切换 + ├─ progress.less // 进度条 + └─ index.less // 统一引入 +``` + +## 动效示例 + +### 1. 淡入淡出 (fade.less) + +```less +@keyframes fade-in { + 0% { opacity: 0; } + 100% { opacity: 1; } +} + +@keyframes fade-out { + 0% { opacity: 1; } + 100% { opacity: 0; } +} +``` + +组件调用示例： + +```less +.@{fade-prefix-cls} { + &-enter-active { + animation: var(--tv-motion-fade-speed) fade-in ease-out both; + } + &-leave-active { + animation: var(--tv-motion-fade-speed) fade-out ease-in both; + } +} +``` + +### 2. 滑动 (slide.less) + +```less +@keyframes slide-left-in { + 0% { opacity: 0; transform: translateX(var(--tv-motion-slide-offset-left)); } + 50% { opacity: var(--tv-motion-slide-opacity-mid); transform: translateX(var(--tv-motion-slide-offset-left-mid)); } + 100% { opacity: 1; transform: translateX(0%); } +} + +@keyframes slide-left-out { + 0% { opacity: 1; transform: translateX(0%); } + 50% { opacity: var(--tv-motion-slide-opacity-mid); transform: translateX(var(--tv-motion-slide-offset-left-mid)); } + 100% { opacity: 0; transform: translateX(var(--tv-motion-slide-offset-left)); } +} +``` + +组件调用示例： + +```less +.drawer-slide-left-enter-active { + animation: slide-left-in var(--tv-motion-slide-speed) linear; +} +.drawer-slide-left-leave-active { + animation: slide-left-out var(--tv-motion-slide-speed) linear; +} +``` + +### 3. 蚂蚁线 (ants.less，可配置) + +```less +@keyframes ants-x { + 0% { background-position: 0 0; } + 100% { background-position: var(--tv-motion-ants-shift, 8px) 0; } +} + +@keyframes ants-x-rev { + 0% { background-position: 0 0; } + 100% { background-position: calc(-1 * var(--tv-motion-ants-shift, 8px)) 0; } +} +``` + +组件调用示例： + +```less +.@{grid-prefix-cls}-copyed-borders { + --tv-motion-ants-shift: 13px; + + .@{grid-prefix-cls}-border-top { + animation: ants-x var(--tv-motion-ants-speed) linear infinite; + } + .@{grid-prefix-cls}-border-right { + animation: ants-y var(--tv-motion-ants-speed) linear infinite; + } + .@{grid-prefix-cls}-border-bottom { + animation: ants-x-rev var(--tv-motion-ants-speed) linear infinite; + } + .@{grid-prefix-cls}-border-left { + animation: ants-y-rev var(--tv-motion-ants-speed) linear infinite; + } +} +``` + +## 组件集成方式 + +1. **全局引入** + 所有 `@keyframes` 在 `transition.less` 与 `motion/*` 中集中维护，统一加载。 + +2. **局部调用** + 组件可通过 `className` 或 `animation` 调用指定动效。 + +3. **可配置参数** + 开发者可通过覆盖 `:root` 变量调整动效时长、速度等参数。 + +## 扩展与维护 + +1. **命名规范** + + * 采用 `{type}-{direction}-{state}` 格式，例如 `slide-left-in`。 + * 保证命名全局唯一，避免冲突。 + +2. **分类管理** + + * 动效必须写在对应分类文件中（如滑动类 → `slide.less`）。 + * 新增变量需先在 `index.less` 中声明，再在具体文件中调用。 + +3. **文档与注释** + + * 每类动效提供示例代码和调用方式说明。 + * 在 `@keyframes` 前添加注释，标注用途和来源。 + * 同类动效按分组书写，便于快速查找与维护。 diff --git a/packages/theme/src/motion/configuration-maintenance.md b/packages/theme/src/motion/configuration-maintenance.md deleted file mode 100644 index 50cf9fea8f..0000000000 --- a/packages/theme/src/motion/configuration-maintenance.md +++ /dev/null @@ -1,147 +0,0 @@ -# TinyVue 全局动效配置维护 - -## 1. 目的 - -本手册用于指导 TinyVue 开发者如何 **新增、修改和维护全局动效配置**。 - 目标是确保动效在 **全局统一管理、可配置、可扩展** 的前提下，保持 **一致性和易维护性**。 - ------- - -## 2. 目录与文件结构 - -动效统一存放在 `/packages/theme/src/motion/` 目录下，按类型拆分： - -``` -motion/ - ├─ fade.less // 淡入淡出 - ├─ slide.less // 滑动 - ├─ zoom.less // 缩放 - ├─ rotate.less // 旋转 - ├─ bounce.less // 弹跳 - ├─ scroll.less // 滚动 - ├─ stroke.less // 描边 - ├─ shine.less // 闪烁 - ├─ ants.less // 蚂蚁线 - ├─ arrow.less // 箭头 - ├─ tab.less // Tab 切换 - ├─ progress.less // 进度条 - └─ index.less // 全局变量定义 -``` - ------- - -## 3. 全局变量管理 - -全局变量统一在 `index.less` 中定义： - -```less -:root { - /* 蚂蚁线相关配置 */ - --tv-motion-ants-shift: 8px; - --tv-motion-ants-speed: 0.8s; - ... -} -``` - ------- - -## 4. 动效命名规范 - -格式： - -``` -{type}-{direction}-{state} -``` - -示例： - -- `fade-in` / `fade-out` -- `slide-left-in` / `slide-left-out` -- `zoom-in-scale` / `zoom-out-scale` -- `ants-x` / `ants-x-rev` - -👉 规则： - -- **type**：动效类型（fade/slide/zoom/ants/...） -- **direction**：方向或轴向（left/right/up/down/x/y/scale） -- **state**：状态（in/out/rev/pulse 等） - ------- - -## 5. 新增动效流程 - -### Step 1. 创建 keyframes - -在对应 `motion/*.less` 文件中新增动效，示例： - -```less -@keyframes fade-in-up { - 0% { - transform: translate3d(0, -20p, 0); - opacity: 0; - } - 100% { - transform: translate3d(0, 0, 0); - opacity: 1; - } -} -``` - -### Step 2. （可选）使用变量替代固定值 - -```less -@keyframes fade-in-up { - 0% { - transform: translate3d(0, calc(-1 * var(--tv-motion-fade-offset-y, 20px)), 0); - opacity: 0; - } - 100% { - transform: translate3d(0, 0, 0); - opacity: 1; - } -} -``` - -### Step 3. 在组件中绑定 - -```less -.dialog-fade-enter-active { - animation: fade-in-up var(--tv-motion-fade-speed); -} -``` - -### Step 4. 更新文档 - -- 在 **对应 `.less` 文件顶部注释** 动效用途 -- 在 PR 描述中说明：类别 / 动效名 / 用法示例 - ------- - -## 6. 动效扩展与维护 - -### 6.1 扩展原则 - -1. 动效必须写在对应分类文件中（如滑动类 → `slide.less`）。 -2. 保持命名唯一性，避免与现有动效冲突。 -3. 需要新变量时，先在 `index.less` 中声明，再调用。 - -### 6.2 维护规范 - -- **代码注释**：在 `@keyframes` 前标注用途和来源。 -- **文件内分组**：同类动效写在一起，便于查找。 - ------- - -## 7. 组件集成方式 - -1. **全局引入** - 所有动效在 `motion/*` 中维护，并在组件中通过className或者animation使用。 -3. **覆盖参数** - 用户可覆盖变量来自定义速度/时长。 - ------- - -## 8. 常见问题 - -- **不同组件能否自定义时长？** - 可以，在组件作用域覆盖变量。 \ No newline at end of file diff --git a/packages/theme/src/motion/global-configuration.md b/packages/theme/src/motion/global-configuration.md deleted file mode 100644 index 9211710491..0000000000 --- a/packages/theme/src/motion/global-configuration.md +++ /dev/null @@ -1,225 +0,0 @@ -# TinyVue 全局动效配置 - -## 1. 背景与目标 - -在应用开发中，统一的动效配置有助于提升整体用户体验和产品一致性。 - 本方案为 TinyVue 提供 **全局动效配置能力**，仅依赖 **LESS 与 CSS 变量**，实现以下目标： - -1. **统一管理**：所有动效集中管理，避免分散定义和重复维护。 -2. **全局可控**：通过 CSS 变量统一控制动效的持续时间、延迟、速度等参数。 -3. **组件集成**：组件可直接调用统一的动效类名或 `@keyframes`。 -4. **动态可调**：通过覆盖 CSS 变量即可在不同场景下切换动效风格。 - ------- - -## 2. 全局配置 - -### 2.1 全局变量定义 - -在 `/packages/theme/src/motion/index.less` 中统一定义： - -```less -:root { - /* 蚂蚁线相关配置 */ - --tv-motion-ants-shift: 8px; - --tv-motion-ants-speed: 0.8s; - ... -} -``` - -开发者可在组件主题文件中覆盖这些变量： - -```css -.copyed-borders { - --tv-motion-ants-shift: 12px; - --tv-motion-ants-speed: 1.2s; -} -``` - ------- - -## 3. 动效分类与使用 - -动效统一存放在 `/packages/theme/src/motion/` 目录下，按类型拆分： - -``` -motion/ - ├─ fade.less // 淡入淡出 - ├─ slide.less // 滑动 - ├─ zoom.less // 缩放 - ├─ rotate.less // 旋转 - ├─ bounce.less // 弹跳 - ├─ scroll.less // 滚动 - ├─ stroke.less // 描边 - ├─ shine.less // 闪烁 - ├─ ants.less // 蚂蚁线 - ├─ arrow.less // 箭头 - ├─ tab.less // Tab 切换 - ├─ progress.less // 进度条 - └─ index.less // 全局变量定义 -``` - ------- - -## 3. 全局变量管理 - -### 3.1 示例：淡入淡出 (fade.less) - -```less -@keyframes fade-in { - 0% { - opacity: 0; - } - - 100% { - opacity: 1; - } -} - -@keyframes fade-out { - 0% { - opacity: 1; - } - - 100% { - opacity: 0; - } -} -``` - -组件调用示例： - -```less -.@{fade-prefix-cls} { - &-enter-active { - animation: var(--tv-motion-fade-speed) fade-in both ease-out; - } - - &-leave-active { - animation: var(--tv-motion-fade-speed) fade-out both ease-in; - } -} -``` - ---- - -### 3.2 示例：滑动 (slide.less) - -```less -/* ============ 左滑 ============ */ -@keyframes slide-left-in { - 0% { - opacity: 0; - transform: translateX(var(--tv-motion-slide-offset-left)); - } - 50% { - opacity: var(--tv-motion-slide-opacity-mid); - transform: translateX(var(--tv-motion-slide-offset-left-mid)); - } - 100% { - opacity: 1; - transform: translateX(0%); - } -} - -@keyframes slide-left-out { - 0% { - opacity: 1; - transform: translateX(0%); - } - 50% { - opacity: var(--tv-motion-slide-opacity-mid); - transform: translateX(var(--tv-motion-slide-offset-left-mid)); - } - 100% { - opacity: 0; - transform: translateX(var(--tv-motion-slide-offset-left)); - } -} -``` - -组件调用示例： - -```less -.drawer-slide-left-enter-active { - animation: slide-left-in var(--tv-motion-slide-speed) linear; -} - -.drawer-slide-left-leave-active { - animation: slide-left-out var(--tv-motion-slide-speed) linear; -} -``` - -### 3.3 示例：蚂蚁线 (ants.less，可配置) - -```less -@keyframes ants-x { - 0% { - background-position: 0 0; - } - 100% { - background-position: var(--tv-motion-ants-shift, 8px) 0; - } -} - -@keyframes ants-x-rev { - 0% { - background-position: 0 0; - } - 100% { - background-position: calc(-1 * var(--tv-motion-ants-shift, 8px)) 0; - } -} -``` - -组件调用示例： - -```less - .@{grid-prefix-cls}-copyed-borders { - --tv-motion-ants-shift: 13px; - - .@{grid-prefix-cls}-border-top { - animation: ants-x var(--tv-motion-ants-speed) linear infinite; - } - .@{grid-prefix-cls}-border-right { - animation: ants-y var(--tv-motion-ants-speed) linear infinite; - } - .@{grid-prefix-cls}-border-bottom { - animation: ants-x-rev var(--tv-motion-ants-speed) linear infinite; - } - .@{grid-prefix-cls}-border-left { - animation: ants-y-rev var(--tv-motion-ants-speed) linear infinite; - } - } -``` - ------- - -## 4. 组件集成方式 - -1. **全局引入** - 所有 `@keyframes` 集中在 `transition.less` 和 `motion/*` 中。 -2. **局部调用** - 组件通过 className 或 `-enter-active / -leave-active` 绑定。 -3. **可配置参数** - 开发者可通过覆盖 `:root` 变量修改动效时长、速度等。 - -示例动效： - -```less -.drawer-slide-left-enter-active { - animation: slide-left-in var(--tv-motion-slide-speed) linear; -} -``` - ------- - -## 5. 扩展与维护 - -1. **命名规范**： - - 使用 `{type}-{direction}-{state}` 格式，例如 `slide-left-in`。 - - 保证全局唯一性，避免冲突。 -2. **文档补充**： - - 每类动效提供示例代码与调用方式说明。 -3. **未来扩展**： - - 支持引入方便引入其他动效资源，增强 TinyVue 动效生态。