ph-utils 0.12.8 → 0.13.0

package/lib/dom.d.ts

@@ -196,26 +196,33 @@ export declare function formatClass(classObj: (boolean | string | undefined | nu
  */
 export declare function formatStyle(styleObj: FormatStyleParam): string;
 /**
- * 对指定的 HTML 元素应用显示过渡效果。
- * @param target - 要应用过渡效果的 HTML 元素。
- * @param properties - 包含要改变的 CSS 属性及其目标值的数组。eg. [['opacity', '0.5']]
- * @param duration - 过渡效果的持续时间，如果不传, 则不会应用 transition-style, 可以自己在 css 中进行定义。
- * 该方法首先将元素的 display 属性设置为 "none"，然后设置过渡属性，
- * 在下一个 DOM 更新周期后显示元素并移除设置的属性，从而实现过渡效果。
+ * 执行元素的过渡动画。
  *
- * ```
- * startTransition($msg, [
-    ["opacity", "0"],
-    ["transform", "translate3d(-50%, -100%, 0)"],
-  ]);
- * ```
- */
-export declare function startTransition(target: HTMLElement, properties: [string, string][], duration?: string): void;
-/**
- * 结束元素的过渡效果，并在过渡结束后隐藏元素。
- * @param target - 要操作的 HTML 元素。
- * @param properties - 包含要设置的 CSS 属性和值的数组。
- * @param finish - 过渡结束后可选的回调函数。
+ * 如果是名称类似于 Vue.js 的过渡动画，通过添加 `*-active`、`*-from|to` class 类名。
+ *
+ * @param el - 需要执行过渡动画的 HTML 元素。
+ * @param nameOrProperties - 过渡动画的名称或属性数组。可以是字符串表示的动画名称，或者是包含属性名称、初始值或目标值、持续时间。eg. [['opacity', '0.5']] | 'nt-opacity'
+ * @param dir - 过渡动画的方向，"leave" 表示离开，"enter" 表示进入。默认值为 "enter"。
+ * @param finish - 过渡动画结束时的回调函数。
+ *
+ * @example <caption>执行 `nt-opacity` 名称动画</caption>
+ * // css
+ * .nt-opacity-enter-active,
+ * .nt-opacity-leave-active {
+ *  transition: opacity 0.3s ease;
+ * }
+ * .nt-opacity-enter-from,
+ * .nt-opacity-leave-to {
+ *   opacity: 0;
+ * }
+ * // js
+ * transition($el, "nt-opacity", "enter");
+ *
+ * @example <caption>执行 `style` 属性动画</caption>
+ * transition($el, [["opacity", "0", "0.3s"]], "enter");
+ *
+ * @example <caption>动画结束后移除节点</caption>
+ * transition($el, [["opacity", "0", "0.3s"]], "leave", () => {  $el.remove(); });
  */
-export declare function endTransition(target: HTMLElement, properties: [string, string][], finish?: () => void): void;
+export declare function transition(el: HTMLElement, nameOrProperties: string | [string, string, string][], dir?: "leave" | "enter", finish?: () => void): void;
 export {};

package/lib/dom.js

@@ -396,58 +396,115 @@ export function formatStyle(styleObj) {
     }
     return styleStr;
 }
+function toggleCssProperty(el, properties, method = "set") {
+    for (let i = 0, len = properties.length; i < len; i++) {
+        const rec = properties[i];
+        if (method === "set") {
+            el.style.setProperty(rec[0], rec[1]);
+        }
+        else {
+            el.style.removeProperty(rec[0]);
+        }
+    }
+}
 /**
- * 对指定的 HTML 元素应用显示过渡效果。
- * @param target - 要应用过渡效果的 HTML 元素。
- * @param properties - 包含要改变的 CSS 属性及其目标值的数组。eg. [['opacity', '0.5']]
- * @param duration - 过渡效果的持续时间，如果不传, 则不会应用 transition-style, 可以自己在 css 中进行定义。
- * 该方法首先将元素的 display 属性设置为 "none"，然后设置过渡属性，
- * 在下一个 DOM 更新周期后显示元素并移除设置的属性，从而实现过渡效果。
+ * 执行元素的过渡动画。
+ *
+ * 如果是名称类似于 Vue.js 的过渡动画，通过添加 `*-active`、`*-from|to` class 类名。
+ *
+ * @param el - 需要执行过渡动画的 HTML 元素。
+ * @param nameOrProperties - 过渡动画的名称或属性数组。可以是字符串表示的动画名称，或者是包含属性名称、初始值或目标值、持续时间。eg. [['opacity', '0.5']] | 'nt-opacity'
+ * @param dir - 过渡动画的方向，"leave" 表示离开，"enter" 表示进入。默认值为 "enter"。
+ * @param finish - 过渡动画结束时的回调函数。
  *
- * ```
- * startTransition($msg, [
-    ["opacity", "0"],
-    ["transform", "translate3d(-50%, -100%, 0)"],
-  ]);
- * ```
+ * @example <caption>执行 `nt-opacity` 名称动画</caption>
+ * // css
+ * .nt-opacity-enter-active,
+ * .nt-opacity-leave-active {
+ *  transition: opacity 0.3s ease;
+ * }
+ * .nt-opacity-enter-from,
+ * .nt-opacity-leave-to {
+ *   opacity: 0;
+ * }
+ * // js
+ * transition($el, "nt-opacity", "enter");
+ *
+ * @example <caption>执行 `style` 属性动画</caption>
+ * transition($el, [["opacity", "0", "0.3s"]], "enter");
+ *
+ * @example <caption>动画结束后移除节点</caption>
+ * transition($el, [["opacity", "0", "0.3s"]], "leave", () => {  $el.remove(); });
  */
-export function startTransition(target, properties, duration) {
-    target.style.setProperty("display", "none");
+export function transition(el, nameOrProperties, dir = "enter", finish) {
+    const p = dir === "enter" ? "from" : "to";
+    let nameClass = "", activeClass = "";
     const trans = [];
-    for (let i = 0, len = properties.length; i < len; i++) {
-        const rec = properties[i];
-        target.style.setProperty(rec[0], rec[1]);
-        trans.push(`${rec[0]} ${duration}`);
+    if (typeof nameOrProperties === "string") {
+        nameClass = `${nameOrProperties}-${dir}-${p}`;
+        activeClass = `${nameOrProperties}-${dir}-active`;
     }
-    if (duration) {
-        target.style.setProperty("transition", trans.join(", "));
+    else {
+        for (let i = 0, len = nameOrProperties.length; i < len; i++) {
+            const rec = nameOrProperties[i];
+            if (rec.length >= 3) {
+                trans.push(`${rec[0]} ${rec[2]}`);
+            }
+        }
     }
-    target.style.removeProperty("display");
-    requestAnimationFrame(() => {
-        for (let i = 0, len = properties.length; i < len; i++) {
-            const rec = properties[i];
-            target.style.removeProperty(rec[0]);
+    if (dir === "enter") {
+        if (nameClass) {
+            el.classList.add(nameClass, activeClass);
         }
-    });
-}
-/**
- * 结束元素的过渡效果，并在过渡结束后隐藏元素。
- * @param target - 要操作的 HTML 元素。
- * @param properties - 包含要设置的 CSS 属性和值的数组。
- * @param finish - 过渡结束后可选的回调函数。
- */
-export function endTransition(target, properties, finish) {
-    for (let i = 0, len = properties.length; i < len; i++) {
-        const rec = properties[i];
-        target.style.setProperty(rec[0], rec[1]);
+        else {
+            toggleCssProperty(el, nameOrProperties, "set");
+            if (trans.length > 0) {
+                el.style.setProperty("transition", trans.join(", "));
+            }
+        }
+        requestAnimationFrame(() => {
+            if (nameClass) {
+                el.classList.remove(nameClass);
+            }
+            else {
+                toggleCssProperty(el, nameOrProperties, "remove");
+            }
+        });
     }
-    target.addEventListener("transitionend", () => {
-        target.style.display = "none";
-        for (let i = 0, len = properties.length; i < len; i++) {
-            const rec = properties[i];
-            target.style.removeProperty(rec[0]);
+    else {
+        if (nameClass) {
+            el.classList.add(activeClass);
+            requestAnimationFrame(() => {
+                el.classList.add(nameClass);
+            });
+        }
+        else {
+            if (trans.length > 0) {
+                el.style.setProperty("transition", trans.join(", "));
+            }
+            requestAnimationFrame(() => {
+                toggleCssProperty(el, nameOrProperties, "set");
+            });
+        }
+    }
+    el.addEventListener("transitionend", () => {
+        if (nameClass) {
+            el.classList.remove(activeClass);
+            requestAnimationFrame(() => {
+                el.classList.remove(nameClass);
+            });
+        }
+        else {
+            if (trans) {
+                el.style.removeProperty("transition");
+            }
+            requestAnimationFrame(() => {
+                requestAnimationFrame(() => {
+                    toggleCssProperty(el, nameOrProperties, "remove");
+                });
+            });
         }
-        if (finish != null) {
+        if (finish) {
             finish();
         }
     }, { once: true });

package/lib/theme.d.ts

@@ -18,9 +18,10 @@ export declare function getTheme(): string;
  * 应用主题
  * @param theme 待应用的主题
  * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
  * @returns 应用的主题
  */
-export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean): Promise<unknown>;
+export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean, transition?: boolean): Promise<unknown>;
 /** 获取当前主题色 */
 export declare function getColorTheme(defaultValue?: string): string | undefined;
 /**

package/lib/theme.js

@@ -88,13 +88,14 @@ export function getTheme() {
  * 应用主题
  * @param theme 待应用的主题
  * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
  * @returns 应用的主题
  */
-export async function applyTheme(theme, cache = true) {
+export async function applyTheme(theme, cache = true, transition = true) {
     if (cache === true) {
         localStorage.setItem("web-theme-appearance", theme == null ? "auto" : theme);
     }
-    return toggleTheme(theme);
+    return toggleTheme(theme, transition);
 }
 /** 获取当前主题色 */
 export function getColorTheme(defaultValue) {

package/package.json

@@ -68,7 +68,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.12.8",
+  "version": "0.13.0",
   "type": "module",
   "repository": {
     "type": "git",