阅读视图

发现新文章,点击刷新页面。

type-challenges(ts类型体操): 11 - 元组转换为对象

11 - 元组转换为对象

by sinoon (@sinoon) #简单 #object-keys

题目

将一个元组类型转换为对象类型,这个对象类型的键/值和元组中的元素对应。

例如:

const tuple = ['tesla', 'model 3', 'model X', 'model Y'] as const

type result = TupleToObject<typeof tuple> // expected { 'tesla': 'tesla', 'model 3': 'model 3', 'model X': 'model X', 'model Y': 'model Y'}

在 Github 上查看:tsch.js.org/11/zh-CN

代码

/* _____________ 你的代码 _____________ */

type TupleToObject<T extends readonly PropertyKey[]> = {
  [P in T[number]]: P
}

关键解释:

  • type PropertyKey = string | number | symbol
  • T extends readonly PropertyKey[] 用于限制 T 必须是一个只读的属性键元组。
  • [P in T[number]] 用于遍历元组中的每个元素,将其作为对象的键。
  • P 是元组中的元素类型,通过 T[number] 来获取。

相关知识点

extends

使用维度 核心作用 示例场景
类型维度 做类型约束或条件判断(类型编程核心) 限定泛型范围、判断类型是否兼容、提取类型片段
语法维度 做继承(复用已有结构) 接口继承、类继承
extends 做类型约束或条件判断
  1. 泛型约束:限定泛型的取值范围
// 约束 T 必须是「拥有 length 属性」的类型(比如 string/数组)
function getLength<T extends { length: number }>(arg: T): number {
  return arg.length;
}

// 合法调用(符合约束)
getLength("hello"); // ✅ string 有 length,返回 5
getLength([1, 2, 3]); // ✅ 数组有 length,返回 3

// 非法调用(超出约束)
getLength(123); // ❌ 报错:number 没有 length 属性
  1. 条件类型:类型版 三元运算符
// 基础示例:判断类型是否为字符串
type IsString<T> = T extends string ? true : false;

type A = IsString<"test">; // true(符合)
type B = IsString<123>; // false(不符合)

分布式条件类型(联合类型专用): 当 T 是联合类型时,extends 会自动拆分联合类型的每个成员,逐个判断后再合并结果。

type Union = string | number | boolean;

// 拆分逻辑:string→string,number→never,boolean→never → 合并为 string
type OnlyString<T> = T extends string ? T : never;
type Result = OnlyString<Union>; // Result = string

注意:只有泛型参数是 裸类型(没有被 []/{} 包裹)时,才会触发分布式判断:

// 包裹后不触发分布式,整体判断 [string|number] 是否兼容 [string]
type NoDist<T> = [T] extends [string] ? T : never;
type Result2 = NoDist<Union>; // never(整体不兼容)
  1. 配合 infer:提取类型片段(黄金组合)
// 提取 Promise 的返回值类型
type UnwrapPromise<T> = T extends Promise<infer V> ? V : T;

type C = UnwrapPromise<Promise<string>>; // string(提取成功)
type D = UnwrapPromise<number>; // number(不满足条件,返回原类型)
extends 做继承(复用已有结构)
  1. 接口继承:复用 + 扩展属性
// 基础接口
interface User {
  id: number;
  name: string;
}

// 继承 User,并扩展新属性
interface Admin extends User {
  role: "admin" | "super_admin"; // 新增权限属性
}

// 必须包含继承的 + 扩展的所有属性
const admin: Admin = {
  id: 1,
  name: "张三",
  role: "admin"
};

// 多接口继承
interface HasAge { age: number; }
interface Student extends User, HasAge {
  className: string; // 同时继承 User + HasAge
}
  1. 类继承:复用父类的属性 / 方法
class Parent {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
  sayHi() {
    console.log(`Hi, ${this.name}`);
  }
}

// 继承 Parent 类
class Child extends Parent {
  age: number;
  constructor(name: string, age: number) {
    super(name); // 必须调用父类构造函数(初始化父类属性)
    this.age = age;
  }
  // 重写父类方法
  sayHi() {
    super.sayHi(); // 调用父类原方法
    console.log(`I'm ${this.age} years old`);
  }
}

const child = new Child("李四", 10);
child.sayHi(); // 输出:Hi, 李四 → I'm 10 years old

补充:类实现接口用 implements(不是 extends

// 定义接口(契约:规定必须有 id、name 属性,以及 greet 方法)
interface Person {
  id: number;
  name: string;
  greet(): void; // 仅定义方法签名,无实现
}

// 类实现接口(必须严格遵守契约)
class Employee implements Person {
  // 必须实现接口的所有属性
  id: number;
  name: string;

  // 构造函数初始化属性
  constructor(id: number, name: string) {
    this.id = id;
    this.name = name;
  }

  // 必须实现接口的 greet 方法(具体实现由类自己定义)
  greet() {
    console.log(`Hi, I'm ${this.name}, ID: ${this.id}`);
  }
}

// 实例化使用
const emp = new Employee(1, "张三");
emp.greet(); // 输出:Hi, I'm 张三, ID: 1


// 接口1:基础信息
interface Identifiable {
  id: number;
  getId(): number;
}

// 接口2:可打印
interface Printable {
  printInfo(): void;
}

// 类同时实现两个接口(必须实现所有接口的成员)
class Product implements Identifiable, Printable {
  id: number;
  name: string; // 类可扩展接口外的属性

  constructor(id: number, name: string) {
    this.id = id;
    this.name = name;
  }

  // 实现 Identifiable 的方法
  getId(): number {
    return this.id;
  }

  // 实现 Printable 的方法
  printInfo() {
    console.log(`Product: ${this.name}, ID: ${this.getId()}`);
  }
}

const product = new Product(100, "手机");
console.log(product.getId()); // 100
product.printInfo(); // Product: 手机, ID: 100

readonly

  • 核心作用:标记后,目标(属性 / 数组 / 元组)只能在初始化阶段赋值(比如接口实例化、类构造函数、变量声明时),后续任何修改运算都会被 TS 编译器拦截报错;
  • 运行时特性:readonly 仅做编译时检查,不会生成任何额外 JS 代码,也无法真正阻止运行时的修改(比如通过类型断言绕开的话,运行时仍能改);
  • const 的区别:const 是变量层面的不可重新赋值(但变量指向的对象 / 数组内部属性仍可改),readonly 是属性 / 类型层面的不可修改(变量本身可重新赋值,除非变量也用 const)。

常用使用场景:

  1. 作用于接口 / 类型别名的属性(最基础)
// 定义带只读属性的接口
interface User {
  readonly id: number; // 只读属性:只能初始化赋值,后续不可改
  name: string; // 普通属性:可修改
}

// 初始化时赋值(合法)
const user: User = { id: 1, name: "张三" };

// 尝试修改只读属性(报错)
user.id = 2; // ❌ 报错:无法分配到 "id",因为它是只读属性
// 修改普通属性(合法)
user.name = "李四"; // ✅ 合法
  1. 作用于类的属性: 类中使用 readonly 标记属性,只能在声明时构造函数中赋值,后续无法修改
class Person {
  readonly id: number; // 只读属性
  name: string;

  // 构造函数中给 readonly 属性赋值(唯一合法的后续赋值方式)
  constructor(id: number, name: string) {
    this.id = id;
    this.name = name;
  }

  updateInfo() {
    this.id = 100; // ❌ 报错:id 是只读属性
    this.name = "王五"; // ✅ 合法
  }
}

const person = new Person(1, "赵六");
person.id = 2; // ❌ 报错:只读属性不可修改
  1. 作用于数组 / 元组(只读数组): readonly 可标记数组为 “只读数组”,禁止修改数组元素、调用 push/pop 等修改方法
// 方式1:使用 readonly 修饰数组类型
const arr1: readonly number[] = [1, 2, 3];
arr1.push(4); // ❌ 报错:readonly 数组不存在 push 方法
arr1[0] = 10; // ❌ 报错:无法修改只读数组的元素

// 方式2:使用 ReadonlyArray<T> 类型(等价于 readonly T[])
const arr2: ReadonlyArray<string> = ["a", "b"];
arr2.pop(); // ❌ 报错

// 作用于元组(只读元组)
type Point = readonly [number, number];
const point: Point = [10, 20];
point[0] = 30; // ❌ 报错:只读元组元素不可修改
  1. 结合 keyof + in 批量创建只读类型(映射类型)
interface Product {
  name: string;
  price: number;
  stock: number;
}

// 批量创建只读版本的 Product(TS 内置的 Readonly<T> 就是这么实现的)
type ReadonlyProduct = {
  readonly [K in keyof Product]: Product[K];
};

const product: ReadonlyProduct = { name: "手机", price: 2999, stock: 100 };
product.price = 3999; // ❌ 报错:price 是只读属性

// TS 内置了 Readonly<T>,可直接使用(无需手动写映射类型)
const product2: Readonly<Product> = { name: "电脑", price: 5999, stock: 50 };
product2.stock = 60; // ❌ 报错
  1. 只读索引签名:如果类型使用索引签名,也可以标记为 readonly,禁止通过索引修改属性
// 只读索引签名:只能读取,不能修改
type ReadonlyDict = {
  readonly [key: string]: number;
};

const dict: ReadonlyDict = { a: 1, b: 2 };
dict["a"] = 3; // ❌ 报错:索引签名是只读的
console.log(dict["b"]); // ✅ 合法:仅读取

in

in 运算符用于遍历联合类型中的每个成员,将其转换为映射类型的属性名。

例如:

interface Todo {
  title: string
  description: string
  completed: boolean
}

type TodoKeys = 'title' | 'description'

type TodoPreview = {
  [P in TodoKeys]: Todo[P]
}
// TodoPreview 类型为:
// {
//   title: string
//   completed: boolean
// }

T[number]

T[number] 索引访问类型 用于 从数组类型 / 元组类型中提取所有元素的类型,最终得到一个联合类型。

  1. 普通数组类型
// 定义普通数组类型
type StringArr = string[];
type NumberArr = number[];
type BoolArr = boolean[];

// T[number] 提取元素类型
type Str = StringArr[number]; // 结果:string
type Num = NumberArr[number]; // 结果:number
type Bool = BoolArr[number]; // 结果:boolean

// 等价于直接注解类型
let s: Str = "hello"; // 等同于 let s: string
let n: Num = 123;    // 等同于 let n: number
let b: Bool = true;  // 等同于 let b: boolean
  1. 元组类型
// 定义一个多类型的元组类型
type Tuple = [123, "TS", true, null];

// T[number] 提取所有元素的联合类型
type TupleUnion = Tuple[number]; // 结果:123 | "TS" | true | null

// 变量注解:可以是联合类型中的任意一种
let val: TupleUnion;
val = 123;    // 合法
val = "TS";   // 合法
val = true;   // 合法
val = null;   // 合法
val = false;  // ❌ 报错:不在联合类型中
  1. 字面量元组
// 字面量元组:元素是数字/字符串字面量
type StatusTuple = [200, 404, 500];
type EnvTuple = ["dev", "test", "prod"];

// 转字面量联合类型(开发中常用的枚举式类型)
type Status = StatusTuple[number]; // 结果:200 | 404 | 500
type Env = EnvTuple[number];       // 结果:"dev" | "test" | "prod"

// 严格限制变量值,避免手写错误
let code: Status = 200; // 合法
code = 404;             // 合法
code = 403;             // ❌ 报错:403 不在 200|404|500 中

let env: Env = "dev";   // 合法
env = "prod";           // 合法
env = "production";     // ❌ 报错:不在联合类型中
  1. as const + 数组 + T[number]

同时拥有数组的可遍历性 + 联合类型的严格类型约束。

// 步骤1:用 as const 断言数组为「只读字面量元组」
// 作用:让 TS 保留每个元素的字面量类型,且把数组转为只读元组(不可修改)
const EnvArr = ["dev", "test", "prod"] as const;
const StatusArr = [200, 404, 500] as const;

// 步骤2:用 typeof 获取数组的类型(只读字面量元组类型)
// 补充:typeof 是 TS 关键字,用于「从变量中提取其类型」
type EnvTuple = typeof EnvArr; // 类型:readonly ["dev", "test", "prod"]
type StatusTuple = typeof StatusArr; // 类型:readonly [200, 404, 500]

// 步骤3:用 T[number] 转成字面量联合类型
type Env = EnvTuple[number]; // 结果:"dev" | "test" | "prod"
type Status = StatusTuple[number]; // 结果:200 | 404 | 500

// 简化写法(开发中常用,省略中间元组类型)
type EnvSimplify = typeof EnvArr[number];
type StatusSimplify = typeof StatusArr[number];
  1. 泛型中使用 T[number]
// 泛型 T 约束为「只读数组」(兼容 as const 断言的数组)
function getUnionType<T extends readonly any[]>(arr: T): T[number] {
  return arr[Math.floor(Math.random() * arr.length)];
}

// 传入 as const 断言的数组,返回值自动推导为字面量联合类型
const res1 = getUnionType(["dev", "test", "prod"] as const); // res1 类型:"dev" | "test" | "prod"
const res2 = getUnionType([1, 2, 3] as const); // res2 类型:1 | 2 | 3

// 传入普通数组,返回值推导为基础类型
const res3 = getUnionType([1, 2, 3]); // res3 类型:number
  1. 支持嵌套数组 / 元组
const NestedArr = [[1, "a"], [2, "b"]] as const;
type NestedUnion = typeof NestedArr[number]; // 结果:readonly [1, "a"] | readonly [2, "b"]
type DeepUnion = typeof NestedArr[number][number]; // 结果:1 | "a" | 2 | "b"

测试用例

/* _____________ 测试用例 _____________ */
import type { Equal, Expect } from '@type-challenges/utils'

const tuple = ['tesla', 'model 3', 'model X', 'model Y'] as const
const tupleNumber = [1, 2, 3, 4] as const
const sym1 = Symbol(1)
const sym2 = Symbol(2)
const tupleSymbol = [sym1, sym2] as const
const tupleMix = [1, '2', 3, '4', sym1] as const

type cases = [
  Expect<Equal<TupleToObject<typeof tuple>, { 'tesla': 'tesla', 'model 3': 'model 3', 'model X': 'model X', 'model Y': 'model Y' }>>,
  Expect<Equal<TupleToObject<typeof tupleNumber>, { 1: 1, 2: 2, 3: 3, 4: 4 }>>,
  Expect<Equal<TupleToObject<typeof tupleSymbol>, { [sym1]: typeof sym1, [sym2]: typeof sym2 }>>,
  Expect<Equal<TupleToObject<typeof tupleMix>, { 1: 1, '2': '2', 3: 3, '4': '4', [sym1]: typeof sym1 }>>,
]

// @ts-expect-error
type error = TupleToObject<[[1, 2], {}]>

相关链接

分享你的解答:tsch.js.org/11/answer/z… 查看解答:tsch.js.org/11/solution… 更多题目:tsch.js.org/zh-CN

下面是我的公众号,欢迎关注。关注后有新的功能点会及时收到推送。

实战为王!专注于汇总各种功能点,致力于打造一系列能够帮助工程师实现各种功能的想法思路的优质文章。

前端功能点

type-challenges(ts类型体操): 10 - 元组转合集

10 - 元组转合集

by Anthony Fu (@antfu) #中等 #infer #tuple #union

题目

实现泛型TupleToUnion<T>,它返回元组所有值的合集。

例如

type Arr = ['1', '2', '3']

type Test = TupleToUnion<Arr> // expected to be '1' | '2' | '3'

在 Github 上查看:tsch.js.org/10/zh-CN

代码

/* _____________ 你的代码 _____________ */

type TupleToUnion<T> = T extends [infer F, ...infer R] ? F | TupleToUnion<R> : never

关键解释:

  • T extends [infer F, ...infer R] 用于判断元组是否为空。
  • F | TupleToUnion<R> 用于递归处理元组的剩余部分。
  • never 用于处理空元组的情况。

相关知识点

extends

使用维度 核心作用 示例场景
类型维度 做类型约束或条件判断(类型编程核心) 限定泛型范围、判断类型是否兼容、提取类型片段
语法维度 做继承(复用已有结构) 接口继承、类继承
extends 做类型约束或条件判断
  1. 泛型约束:限定泛型的取值范围
// 约束 T 必须是「拥有 length 属性」的类型(比如 string/数组)
function getLength<T extends { length: number }>(arg: T): number {
  return arg.length;
}

// 合法调用(符合约束)
getLength("hello"); // ✅ string 有 length,返回 5
getLength([1, 2, 3]); // ✅ 数组有 length,返回 3

// 非法调用(超出约束)
getLength(123); // ❌ 报错:number 没有 length 属性
  1. 条件类型:类型版 三元运算符
// 基础示例:判断类型是否为字符串
type IsString<T> = T extends string ? true : false;

type A = IsString<"test">; // true(符合)
type B = IsString<123>; // false(不符合)

分布式条件类型(联合类型专用): 当 T 是联合类型时,extends 会自动拆分联合类型的每个成员,逐个判断后再合并结果。

type Union = string | number | boolean;

// 拆分逻辑:string→string,number→never,boolean→never → 合并为 string
type OnlyString<T> = T extends string ? T : never;
type Result = OnlyString<Union>; // Result = string

注意:只有泛型参数是 裸类型(没有被 []/{} 包裹)时,才会触发分布式判断:

// 包裹后不触发分布式,整体判断 [string|number] 是否兼容 [string]
type NoDist<T> = [T] extends [string] ? T : never;
type Result2 = NoDist<Union>; // never(整体不兼容)
  1. 配合 infer:提取类型片段(黄金组合)
// 提取 Promise 的返回值类型
type UnwrapPromise<T> = T extends Promise<infer V> ? V : T;

type C = UnwrapPromise<Promise<string>>; // string(提取成功)
type D = UnwrapPromise<number>; // number(不满足条件,返回原类型)
extends 做继承(复用已有结构)
  1. 接口继承:复用 + 扩展属性
// 基础接口
interface User {
  id: number;
  name: string;
}

// 继承 User,并扩展新属性
interface Admin extends User {
  role: "admin" | "super_admin"; // 新增权限属性
}

// 必须包含继承的 + 扩展的所有属性
const admin: Admin = {
  id: 1,
  name: "张三",
  role: "admin"
};

// 多接口继承
interface HasAge { age: number; }
interface Student extends User, HasAge {
  className: string; // 同时继承 User + HasAge
}
  1. 类继承:复用父类的属性 / 方法
class Parent {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
  sayHi() {
    console.log(`Hi, ${this.name}`);
  }
}

// 继承 Parent 类
class Child extends Parent {
  age: number;
  constructor(name: string, age: number) {
    super(name); // 必须调用父类构造函数(初始化父类属性)
    this.age = age;
  }
  // 重写父类方法
  sayHi() {
    super.sayHi(); // 调用父类原方法
    console.log(`I'm ${this.age} years old`);
  }
}

const child = new Child("李四", 10);
child.sayHi(); // 输出:Hi, 李四 → I'm 10 years old

补充:类实现接口用 implements(不是 extends

// 定义接口(契约:规定必须有 id、name 属性,以及 greet 方法)
interface Person {
  id: number;
  name: string;
  greet(): void; // 仅定义方法签名,无实现
}

// 类实现接口(必须严格遵守契约)
class Employee implements Person {
  // 必须实现接口的所有属性
  id: number;
  name: string;

  // 构造函数初始化属性
  constructor(id: number, name: string) {
    this.id = id;
    this.name = name;
  }

  // 必须实现接口的 greet 方法(具体实现由类自己定义)
  greet() {
    console.log(`Hi, I'm ${this.name}, ID: ${this.id}`);
  }
}

// 实例化使用
const emp = new Employee(1, "张三");
emp.greet(); // 输出:Hi, I'm 张三, ID: 1


// 接口1:基础信息
interface Identifiable {
  id: number;
  getId(): number;
}

// 接口2:可打印
interface Printable {
  printInfo(): void;
}

// 类同时实现两个接口(必须实现所有接口的成员)
class Product implements Identifiable, Printable {
  id: number;
  name: string; // 类可扩展接口外的属性

  constructor(id: number, name: string) {
    this.id = id;
    this.name = name;
  }

  // 实现 Identifiable 的方法
  getId(): number {
    return this.id;
  }

  // 实现 Printable 的方法
  printInfo() {
    console.log(`Product: ${this.name}, ID: ${this.getId()}`);
  }
}

const product = new Product(100, "手机");
console.log(product.getId()); // 100
product.printInfo(); // Product: 手机, ID: 100

infer

infer 是 TypeScript 在条件类型中提供的关键字,用于声明一个 待推导的类型变量(类似给类型起一个临时名字),只能在 extends 子句中使用。它的核心作用是:从已有类型中提取 / 推导我们需要的部分,而无需手动硬编码类型。

infer 必须配合条件类型使用,语法结构如下:

// 基础结构:推导 T 的类型为 U,若能推导则返回 U,否则返回 never
type InferType<T> = T extends infer U ? U : never;

type Example = InferType<string>; // Example 类型为 string
type Example2 = InferType<number[]>; // Example2 类型为 number[]

高频使用场景:

1. 提取函数的返回值类型
// 定义类型工具:提取函数的返回值类型
type GetReturnType<Fn> = Fn extends (...args: any[]) => infer R ? R : never;

// 测试用函数
const add = (a: number, b: number): number => a + b;
const getUser = () => ({ name: "张三", age: 20 });

// 使用类型工具
type AddReturn = GetReturnType<typeof add>; // AddReturn 类型为 number
type UserReturn = GetReturnType<typeof getUser>; // UserReturn 类型为 { name: string; age: number }
2. 提取数组的元素类型
// 定义类型工具:提取数组元素类型
type GetArrayItem<T> = T extends (infer Item)[] ? Item : never;

// 测试
type NumberArray = GetArrayItem<number[]>; // NumberArray 类型为 number
type StringArray = GetArrayItem<string[]>; // StringArray 类型为 string
type MixedArray = GetArrayItem<[string, number]>; // MixedArray 类型为 string | number
3. 提取 Promise 的泛型参数类型
// 定义类型工具:提取 Promise 的泛型类型
type GetPromiseValue<T> = T extends Promise<infer Value> ? Value : never;

// 测试
type PromiseString = GetPromiseValue<Promise<string>>; // PromiseString 类型为 string
type PromiseUser = GetPromiseValue<Promise<{ id: number }>>; // PromiseUser 类型为 { id: number }
4. 提取函数的参数类型
// 定义类型工具:提取函数参数类型
type GetFunctionParams<Fn> = Fn extends (...args: infer Params) => any ? Params : never;

// 测试
const fn = (name: string, age: number): void => {};
type FnParams = GetFunctionParams<typeof fn>; // FnParams 类型为 [string, number]

// 进一步:提取第一个参数的类型
type FirstParam = GetFunctionParams<typeof fn>[0]; // FirstParam 类型为 string

|

| 运算符用于表示联合类型,即一个值可以是多个类型中的任意一个。

  1. 变量的联合类型注解
// 变量 a 可以是字符串 OR 数字
let a: string | number;

// 合法赋值(符合任意一种类型)
a = "TS";
a = 123;

// 非法赋值(不属于联合类型中的任何一种),TS 直接报错
a = true; // ❌ 类型 'boolean' 不能赋值给类型 'string | number'
  1. 函数参数的联合类型
// 函数接收 string 或 number 类型的参数
function printValue(val: string | number) {
  console.log(val);
}

// 合法调用
printValue("hello");
printValue(666);

// 非法调用,TS 报错
printValue(null); // ❌
  1. 数组的联合类型(注意两种写法的区别)
// 写法1:(A | B)[] —— 数组的「每个元素」可以是 A 或 B(混合数组)
let arr1: (string | number)[] = [1, "2", 3, "4"]; // 合法

// 写法2:A[] | B[] —— 「整个数组」要么全是 A 类型,要么全是 B 类型(纯数组)
let arr2: string[] | number[] = [1, 2, 3]; // 合法(全数字)
arr2 = ["1", "2", "3"]; // 合法(全字符串)
arr2 = [1, "2"]; // ❌ 报错:混合类型不符合要求

当使用联合类型的时候,访问某一个子类型的专属属性 / 方法时,需要进行类型守卫,可用的方法有 typeofinswitchinstanceof

  1. typeof
function getLength(val: string | number) {
  // 类型窄化:判断 val 是 string 类型
  if (typeof val === "string") {
    // 此分支中,TS 确定 val 是 string,可安全使用 length
    return val.length;
  } else {
    // 此分支中,TS 确定 val 是 number,执行数字相关逻辑
    return val.toString().length;
  }
}

console.log(getLength("TS")); // 2
console.log(getLength(1234)); // 4
  1. in
function printUserInfo(user: { name: string } | { age: number }) {
  // 类型窄化:判断 user 是否有 name 属性(即是否是 { name: string } 类型)
  if ("name" in user) {
    console.log(`Name: ${user.name}`);
  } else {
    // 此分支中,TS 确定 user 是 { age: number } 类型
    console.log(`Age: ${user.age}`);
  }
}
  1. switch
interface User {
  type: "user";
  name: string;
  age: number;
}
interface Admin {
  type: "admin";
  name: string;
  permission: string[];
}
// 联合类型:可以是 User 或 Admin
type Person = User | Admin;
function printPerson(p: Person) {
  switch (p.type) {
    case "user":
      console.log(p.age); // 确定是 User
      break;
    case "admin":
      console.log(p.permission); // 确定是 Admin
      break;
  }
}
  1. instanceof
// 定义两个类
class Dog {
  bark() { console.log("汪汪"); }
}
class Cat {
  meow() { console.log("喵喵"); }
}

// 联合类型:Dog 或 Cat 实例
type Animal = Dog | Cat;

// instanceof 类型守卫(针对类实例)
function animalCall(animal: Animal) {
  if (animal instanceof Dog) {
    animal.bark();
  } else {
    animal.meow();
  }
}

animalCall(new Dog()); // 汪汪
animalCall(new Cat()); // 喵喵

测试用例

/* _____________ 测试用例 _____________ */
import type { Equal, Expect } from '@type-challenges/utils'

type cases = [
  Expect<Equal<TupleToUnion<[123, '456', true]>, 123 | '456' | true>>,
  Expect<Equal<TupleToUnion<[123]>, 123>>,
]

相关链接

分享你的解答:tsch.js.org/10/answer/z… 查看解答:tsch.js.org/10/solution… 更多题目:tsch.js.org/zh-CN

下面是我的公众号,欢迎关注。关注后有新的功能点会及时收到推送。

实战为王!专注于汇总各种功能点,致力于打造一系列能够帮助工程师实现各种功能的想法思路的优质文章。

前端功能点

为网页注入灵魂:Live2D Widget看板娘,打造会动的互动伙伴!

厌倦了静态网页的冰冷与单调?Live2D Widget 能将一个生动、可爱的看板娘轻松带入你的网站。只需一行代码,这个由 TypeScript 驱动的开源项目即可为博客、个人主页或任何网页赋予灵动的生命。她不仅会眨眼、转头,还能与访客进行简单的互动,瞬间提升网站的趣味性与亲和力。无论是技术极客追求的可定制性,还是普通用户向往的轻松集成,Live2D Widget 都能满足。跟随本文,一分钟唤醒你的网页,让数字世界多一位温暖陪伴。

🎯项目介绍

  • • 页面互动:在网页中添加 Live2D 看板娘
  • • 易于集成: 核心代码由 TypeScript 编写,易于集成,只需一行代码,即可为网站添加看板娘
  • • 轻量级设计:除Live2D核心库外无额外依赖,加载迅速
  • • 高度可定制:支持多种配置选项,完美适配你的网站风格

github地址:github.com/stevenjoezh…

官网地址:www.live2d.com/en

该项目目前在github上已有 10.4k ⭐️ star

⚡快速开始:一分钟集成

对于大多数用户来说,集成过程简单得令人惊喜:

<!-- 只需在页面中添加这行代码 -->
<script src="https://fastly.jsdelivr.net/npm/live2d-widgets@1.0.0/dist/autoload.js"></script>

我的博客页面 xiuji008.github.io/ 已经集成了,家人们可以移步过去看看效果,以下是一些效果图

🎖️进阶

如果你是小白,我们通过上边介绍的那行代码就已经把看板娘集成进来了。但是如果你想让看板娘更适合你的网站,你可以通过进一步的配置及开发来完成,感兴趣的家人们可以自行研究。

相关技术博文:www.fghrsh.net/post/123.ht…

📝 总结:让网页活起来

Live2D Widget不仅仅是一个技术项目,它代表了网页交互的新可能。在这个数字化的时代,一个灵动的看板娘能够:

  • • 提升用户体验和停留时间
  • • 增加网站的特色和记忆点
  • • 展示技术实力和创意精神

无论你是技术爱好者、博主还是网站开发者,Live2D Widget都能为你的项目增添独特的魅力。立即尝试,让你的网站拥有一个随时陪伴访客的可爱伙伴吧!

让技术更有温度,让网页更有生命!🚀

大模型发展史-01

前言

2017年,一篇论文悄然发表,题为《Attention Is All You Need》。

当时没人预料到,这篇论文中提出的 Transformer 架构,会在短短几年内彻底改变人工智能的格局。

五年后的2022年11月30日,ChatGPT 发布。五天内,用户突破100万。两个月内,用户突破1亿。

这是互联网历史上增长最快的应用,也是人工智能发展史上的重要里程碑。

从默默无闻到席卷全球,大语言模型经历了怎样的进化之路?让我们一起回顾这段激动人心的技术演进史。


1. 什么是 Transformer

Transformer 是一种完全基于注意力机制的神经网络架构,于2017年由 Google 团队提出。

核心创新

特点 说明
Self-Attention 自注意力机制,捕捉长距离依赖
并行计算 可并行训练,大幅提升效率
可扩展性 为后续大模型奠定基础

核心思想

// Transformer 的核心:Self-Attention
class Transformer {
  attention(Q, K, V) {
    // Q (Query)、K (Key)、V (Value)
    const scores = Q @ K.T / Math.sqrt(d_k);  // 计算注意力分数
    const weights = softmax(scores);           // 归一化
    return weights @ V;                        // 加权求和
  }
}

重要术语

术语 解释
预训练 用大量无标注数据训练基础模型
微调 针对特定任务用小数据集优化模型
RLHF 人类反馈强化学习,对齐人类偏好
少样本学习 只需几个例子就能学会新任务

2. 案例

案例 1:GPT 系列的进化之路

让我们看看 GPT 系列是如何一步步进化的:

代际 发布时间 参数量 能力突破
GPT-1 2018.06 117M 预训练范式
GPT-2 2019.02 1.5B 零样本生成
GPT-3 2020.05 175B 少样本学习
GPT-3.5 2022.11 未知 对话能力
GPT-4 2023.03 ~1.7T 多模态+推理
GPT-4o 2024.05 未知 原生多模态

关键突破:GPT-3 的少样本学习

const prompt = `
翻译以下句子成中文:
Example 1: Hello world -> 你好世界
Example 2: How are you -> 你好吗
Input: Good morning -> ?
`;
// GPT-3: 早上好
// 没有专门训练,就能学会翻译任务

案例 2:ChatGPT 的 AI iPhone 时刻

发布时间:2022年11月30日

突破性改进

训练流程:
1. 预训练(学习知识)
   ↓
2. 有监督微调(学习指令)
   ↓
3. 奖奖模型(学习人类偏好)
   ↓
4. 强化学习(优化输出)

成果

  • 对话能力大幅提升
  • 指令遵循能力强
  • 多轮对话流畅
  • 5天用户破100万

案例 3:2023年百花齐放

闭源模型三强鼎立

模型 公司 核心优势
GPT-4 OpenAI 多模态、推理能力强
Claude 3 Anthropic 超长上下文(200K)
Gemini Google 原生多模态

开源模型快速追赶

模型 组织 参数 特点
Llama 3 Meta 8B/70B 性能强劲
Qwen 阿里云 7B/14B/72B 中文优秀
Mistral Mistral AI 7B 效率之王

中国大模型崛起

模型 公司 特色
文心一言 百度 知识图谱增强
通义千问 阿里云 开源友好
讯飞星火 科大讯飞 语音能力强
DeepSeek 幻方量化 性价比高

案例 4:2024年的三大趋势

趋势1:开源模型追平闭源

2024年初:Llama 2 70B  GPT-3.5
2024年中:Llama 3 70B 接近 GPT-4
2024年底:Qwen 2.5、DeepSeek V3 追平闭源

趋势2:多模态成为标配

  • GPT-4o:原生多模态
  • Claude 3.5:强大的视觉能力
  • Gemini:从一开始就是多模态

趋势3:智能体技术成熟

// Agent 能力的进化
2022:简单对话
2023:工具调用
2024:
  ├── 复杂任务规划
  ├── 多智能体协作
  ├── 自主学习和改进
  └── 真正的"AI 员工"

总结

  1. 规模即质量——更大的模型通常表现更好
  2. 数据是关键——高质量训练数据至关重要
  3. 架构创新——Transformer 是核心突破
  4. 开源加速——开源模型推动技术普及

什么是大语言模型-00

前言

你有没有想过,当你问 ChatGPT 一个问题时,它是如何"思考"并给出回答的?

今天天气怎么样?——抱歉,我无法获取实时天气信息。 请用 JavaScript 写一个快速排序——几秒钟内,代码就出现在屏幕上。

同样是 AI,为什么能写代码却不能查天气?大语言模型的"知识"从哪里来?它是真的"理解"我们的话吗?

这些问题,正是我们探索大语言模型(Large Language Model,LLM)世界的起点。


1. 什么是大语言模型

大语言模型(LLM) 是一种经过海量文本数据训练的深度学习模型,能够理解和生成人类语言。

关键特征

特征 说明 例子
大规模训练 使用 TB 级文本数据 GPT-4 训练了约 1 万亿 tokens
深度神经网络 数十亿到数万亿参数 GPT-3 有 1750 亿参数
通用能力 不需要专门训练就能完成多种任务 翻译、写作、编程、推理

通俗理解

想象一下:

  • 你阅读了互联网上几乎所有的文本
  • 你记住了其中的模式、规律和知识
  • 当有人问你问题时,你能根据记忆生成回答

这就是大语言模型做的事情!

核心工作原理

LLM 的本质是一个文字接龙机器

输入: "今天天气"
LLM 预测下一个词可能是:
- "真好"    (概率 30%)
- "很热"    (概率 25%)
- "怎么样"  (概率 20%)

训练流程

┌─────────────────────────────────────────┐
│            LLM 训练流程                   │
├─────────────────────────────────────────┤
│                                         │
│  1. 数据收集                             │
│     ├── 网页文本                         │
│     ├── 书籍文章                         │
│     └── 代码库                           │
│                                         │
│  2. 预训练                               │
│     ├── 学习语言模式                     │
│     ├── 学习世界知识                     │
│     └── 学习逻辑推理                     │
│                                         │
│  3. 微调                                 │
│     ├── 对齐人类偏好                     │
│     ├── 遵循指令                         │
│     └── 安全性训练                       │
│                                         │
└─────────────────────────────────────────┘

四大核心能力

1. 语言理解

  • 理解文本含义
  • 识别情感倾向
  • 提取关键信息

2. 语言生成

  • 写文章、写代码
  • 创意写作
  • 总结提炼

3. 逻辑推理

  • 数学计算
  • 逻辑推理
  • 问题解决

4. 少样本学习

  • 看几个例子就能学会新任务
  • 不需要重新训练

2. 案例

案例 1:少样本学习的神奇之处

让我们看看 LLM 如何通过几个例子学会新任务:

const prompt = `
例子1:
输入:苹果
输出:水果

例子2:
输入:胡萝卜
输出:蔬菜

输入:香蕉
输出:?
`;
// LLM 能推断:香蕉 → 水果

image.png

解析:无需重新训练,只需几个示例,LLM 就能理解分类规律并应用到新问题。

案例 2:代码生成能力

输入:"请用 JavaScript 写一个快速排序"

LLM 输出

function quickSort(arr) {
  if (arr.length <= 1) {
    return arr;
  }
  const pivot = arr[Math.floor(arr.length / 2)];
  const left = arr.filter(x => x < pivot);
  const middle = arr.filter(x => x === pivot);
  const right = arr.filter(x => x > pivot);
  return [...quickSort(left), ...middle, ...quickSort(right)];
}

解析:LLM 从训练数据中学会了编程模式和算法逻辑,能够生成可运行的代码。

案例 3:发现 LLM 的局限性

测试 1:实时信息

用户: "今天天气怎么样?"
LLM: "抱歉,我无法获取实时天气信息。"

测试 2:精确计算

用户: "12345 × 67890 = ?"
LLM: "大约是 83,000,000 左右"
实际: 838,102,050

测试 3:知识截止

用户: "谁赢得了2024年奥运会?"
LLM: "抱歉,我的知识截止到2023年..."

解析:这些测试揭示了 LLM 的三大局限——知识截止、幻觉问题、无法访问实时信息。

案例 4:实际项目中的调用

在本项目的后端代码中,LLM 调用是这样实现的:

async chat(request: {
  question: string;    // 用户的问题
  model: string;       // 使用的模型(如 qwen-plus)
  apiKey: string;      // API 密钥
}) {
  // 调用阿里云百炼的 LLM
  const response = await axios.post(
    'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
    {
      model: request.model,
      messages: [{ role: 'user', content: request.question }]
    }
  );

  return response.data.choices[0].message.content;
}

解析:通过 HTTP API 调用,将用户问题发送给 LLM,获取生成的回复。


总结

  1. LLM 是文字接龙机器——核心原理是预测下一个词
  2. LLM 有强大但有限的能力——理解、生成、推理、学习都很强,但并非万能
  3. LLM 的知识来自训练数据——它学习的是模式和规律,而非简单记忆
  4. LLM 会犯错——幻觉、知识截止、计算不精确是常见问题

Flutter最佳实践:Sliver族网络刷新组件NCustomScrollView

一、需求来源

最近需要实现嵌套和吸顶Header滚动下的下拉刷新及上拉加载。最终实现基于 CustomScrollView 的刷新视图组件。

simulator_screenshot_5C4883E4-F919-4FFD-BE3D-97E0BCD5C40D.png

二、使用示例

Widget buildBodyNew() {
  return NCustomScrollView<String>(
    onRequest: (bool isRefresh, int page, int pageSize, pres) async {
      final length = isRefresh ? 0 : pres.length;
      final list = List<String>.generate(pageSize, (i) => "item${length + i}");
      DLog.d([isRefresh, list.length]);
      return list;
    },
    headerSliverBuilder: (context, bool innerBoxIsScrolled) {
      return [
        buildPersistentHeader(),
      ];
    },
    itemBuilder: (_, i, e) {
      return ListTile(
        title: Text('Item $i'),
      );
    },
  );
}

三、源码

//
//  NCustomScrollView.dart
//  projects
//
//  Created by shang on 2026/1/28 14:41.
//  Copyright © 2026/1/28 shang. All rights reserved.
//

import 'package:easy_refresh/easy_refresh.dart';
import 'package:flutter/material.dart';
import 'package:flutter_templet_project/basicWidget/n_placeholder.dart';
import 'package:flutter_templet_project/basicWidget/n_sliver_decorated.dart';
import 'package:flutter_templet_project/basicWidget/refresh/easy_refresh_mixin.dart';
import 'package:flutter_templet_project/basicWidget/refresh/n_refresh_view.dart';

/// 基于 CustomScrollView 的下拉刷新,上拉加载更多的滚动列表
class NCustomScrollView<T> extends StatefulWidget {
  const NCustomScrollView({
    super.key,
    this.title,
    this.placeholder = const NPlaceholder(),
    this.contentDecoration = const BoxDecoration(),
    this.contentPadding = const EdgeInsets.all(0),
    required this.onRequest,
    required this.headerSliverBuilder,
    required this.itemBuilder,
    this.separatorBuilder,
    this.headerBuilder,
    this.footerBuilder,
    this.builder,
  });

  final String? title;

  final Widget? placeholder;

  final Decoration contentDecoration;

  final EdgeInsets contentPadding;

  /// 请求方法
  final RequestListCallback<T> onRequest;

  /// 列表表头
  final NestedScrollViewHeaderSliversBuilder? headerSliverBuilder;

  /// ListView 的 itemBuilder
  final ValueIndexedWidgetBuilder<T> itemBuilder;

  final IndexedWidgetBuilder? separatorBuilder;

  /// 列表表头
  final List<Widget> Function(int count)? headerBuilder;

  /// 列表表尾
  final List<Widget> Function(int count)? footerBuilder;

  final Widget Function(List<T> items)? builder;

  @override
  State<NCustomScrollView<T>> createState() => _NCustomScrollViewState<T>();
}

class _NCustomScrollViewState<T> extends State<NCustomScrollView<T>>
    with AutomaticKeepAliveClientMixin, EasyRefreshMixin<NCustomScrollView<T>, T> {
  @override
  bool get wantKeepAlive => true;

  final scrollController = ScrollController();

  @override
  late RequestListCallback<T> onRequest = widget.onRequest;

  @override
  List<T> items = <T>[];

  @override
  void didUpdateWidget(covariant NCustomScrollView<T> oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.title != oldWidget.title ||
        widget.placeholder != oldWidget.placeholder ||
        widget.contentDecoration != oldWidget.contentDecoration ||
        widget.contentPadding != oldWidget.contentPadding ||
        widget.onRequest != oldWidget.onRequest ||
        widget.itemBuilder != oldWidget.itemBuilder ||
        widget.separatorBuilder != oldWidget.separatorBuilder) {
      setState(() {});
    }
  }

  @override
  Widget build(BuildContext context) {
    super.build(context);
    if (items.isEmpty) {
      return GestureDetector(onTap: onRefresh, child: Center(child: widget.placeholder));
    }

    final child = EasyRefresh.builder(
      controller: refreshController,
      onRefresh: onRefresh,
      onLoad: onLoad,
      childBuilder: (_, physics) {
        return CustomScrollView(
          physics: physics,
          slivers: [
            ...(widget.headerBuilder?.call(items.length) ?? []),
            buildContent(),
            ...(widget.footerBuilder?.call(items.length) ?? []),
          ],
        );
      },
    );
    if (widget.headerSliverBuilder == null) {
      return child;
    }

    return NestedScrollView(
      headerSliverBuilder: widget.headerSliverBuilder!,
      body: child,
    );
  }

  Widget buildContent() {
    if (items.isEmpty) {
      return SliverToBoxAdapter(child: widget.placeholder);
    }

    return NSliverDecorated(
      decoration: widget.contentDecoration,
      sliver: SliverPadding(
        padding: widget.contentPadding,
        sliver: widget.builder?.call(items) ?? buildSliverList(),
      ),
    );
  }

  Widget buildSliverList() {
    return SliverList.separated(
      itemBuilder: (_, i) => widget.itemBuilder(context, i, items[i]),
      separatorBuilder: (_, i) => widget.separatorBuilder?.call(context, i) ?? const SizedBox(),
      itemCount: items.length,
    );
  }
}

源码:EasyRefreshMixin.dart

//
//  EasyRefreshMixin.dart
//  projects
//
//  Created by shang on 2026/1/28 14:37.
//  Copyright © 2026/1/28 shang. All rights reserved.
//

import 'package:easy_refresh/easy_refresh.dart';
import 'package:flutter/material.dart';
import 'package:flutter_templet_project/basicWidget/refresh/n_refresh_view.dart';

/// EasyRefresh刷新 mixin
mixin EasyRefreshMixin<W extends StatefulWidget, T> on State<W> {
  late final refreshController = EasyRefreshController(
    controlFinishRefresh: true,
    controlFinishLoad: true,
  );


  /// 请求方式
  late RequestListCallback<T> _onRequest;
  RequestListCallback<T> get onRequest => _onRequest;
  set onRequest(RequestListCallback<T> value) {
    _onRequest = value;
  }

  // 数据列表
  List<T> _items = [];
  List<T> get items => _items;
  set items(List<T> value) {
    _items = value;
  }

  int page = 1;
  final int pageSize = 20;
  var indicator = IndicatorResult.success;

  @override
  void dispose() {
    refreshController.dispose();
    super.dispose();
  }

  @override
  void initState() {
    super.initState();

    WidgetsBinding.instance.addPostFrameCallback((_) {
      // DLog.d([widget.title, widget.key, hashCode]);
      if (items.isEmpty) {
        onRefresh();
      }
    });
  }

  Future<void> onRefresh() async {
    try {
      page = 1;
      final list = await onRequest(true, page, pageSize, <T>[]);
      items.replaceRange(0, items.length, list);
      page++;

      final noMore = list.length < pageSize;
      if (noMore) {
        indicator = IndicatorResult.noMore;
      }
      refreshController.finishRefresh();
      refreshController.resetFooter();
    } catch (e) {
      refreshController.finishRefresh(IndicatorResult.fail);
    }
    setState(() {});
  }

  Future<void> onLoad() async {
    if (indicator == IndicatorResult.noMore) {
      refreshController.finishLoad();
      return;
    }

    try {
      final start = (items.length - pageSize).clamp(0, pageSize);
      final prePages = items.sublist(start);
      final list = await onRequest(false, page, pageSize, prePages);
      items.addAll(list);
      page++;

      final noMore = list.length < pageSize;
      if (noMore) {
        indicator = IndicatorResult.noMore;
      }
      refreshController.finishLoad(indicator);
    } catch (e) {
      refreshController.finishLoad(IndicatorResult.fail);
    }
    setState(() {});
  }
}

最后、总结

1、当页面比较复杂,需要吸顶或者嵌套滚动时就必须使用 Sliver 相关组件,否则会有滚动行文冲突。

2、NCustomScrollView 支持顶部吸顶组件自定义;底部列表头,列表尾设置,支持sliver 设置 Decoration。

3、支持下拉刷新,上拉加载更多,代码极简,使用方便。

4、刷新逻辑封装在 EasyRefreshMixin 混入里,方便多组件可共用。

github

flutter添加间隙gap源码解析

Flutter 小部件,可轻松在 Flex 小部件(如列和行)或滚动视图中添加间隙。

Gap的核心原理是使用RenderObject自定义实现布局。

Gap


class Gap extends StatelessWidget {
  const Gap(
    this.mainAxisExtent, {
    Key? key,
    this.crossAxisExtent,
    this.color,
  })  : assert(mainAxisExtent >= 0 && mainAxisExtent < double.infinity),
        assert(crossAxisExtent == null || crossAxisExtent >= 0),
        super(key: key);

  const Gap.expand(
    double mainAxisExtent, {
    Key? key,
    Color? color,
  }) : this(
          mainAxisExtent,
          key: key,
          crossAxisExtent: double.infinity,
          color: color,
        );

  final double mainAxisExtent;

  final double? crossAxisExtent;

  final Color? color;

  @override
  Widget build(BuildContext context) {
    final scrollableState = Scrollable.maybeOf(context);
    final AxisDirection? axisDirection = scrollableState?.axisDirection;
    final Axis? fallbackDirection =
        axisDirection == null ? null : axisDirectionToAxis(axisDirection);

    return _RawGap(
      mainAxisExtent,
      crossAxisExtent: crossAxisExtent,
      color: color,
      fallbackDirection: fallbackDirection,
    );
  }
}

从源码看, 它提供了两个构造方法, GapGap.expand方便用户按需使用。

_RawGap

_RawGap是核心类, 它继承了LeafRenderObjectWidget.

class _RawGap extends LeafRenderObjectWidget {
  const _RawGap(
    this.mainAxisExtent, {
    Key? key,
    this.crossAxisExtent,
    this.color,
    this.fallbackDirection,
  })  : assert(mainAxisExtent >= 0 && mainAxisExtent < double.infinity),
        assert(crossAxisExtent == null || crossAxisExtent >= 0),
        super(key: key);

  final double mainAxisExtent;

  final double? crossAxisExtent;

  final Color? color;

  final Axis? fallbackDirection;

  @override
  RenderObject createRenderObject(BuildContext context) {
    return RenderGap(
      mainAxisExtent: mainAxisExtent,
      crossAxisExtent: crossAxisExtent ?? 0,
      color: color,
      fallbackDirection: fallbackDirection,
    );
  }

  @override
  void updateRenderObject(BuildContext context, RenderGap renderObject) {
    if (kDebugMode) {
      debugPrint(
        '[Gap] updateRenderObject '
        'mainAxisExtent=$mainAxisExtent '
        'crossAxisExtent=${crossAxisExtent ?? 0} '
        'color=$color '
        'fallbackDirection=$fallbackDirection',
      );
    }
    renderObject
      ..mainAxisExtent = mainAxisExtent
      ..crossAxisExtent = crossAxisExtent ?? 0
      ..color = color
      ..fallbackDirection = fallbackDirection;
  }

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(DoubleProperty('mainAxisExtent', mainAxisExtent));
    properties.add(
        DoubleProperty('crossAxisExtent', crossAxisExtent, defaultValue: 0));
    properties.add(ColorProperty('color', color));
    properties.add(EnumProperty<Axis>('fallbackDirection', fallbackDirection));
  }
}

RenderGap

class RenderGap extends RenderBox {
  RenderGap({
    required double mainAxisExtent,
    double? crossAxisExtent,
    Axis? fallbackDirection,
    Color? color,
  })  : _mainAxisExtent = mainAxisExtent,
        _crossAxisExtent = crossAxisExtent,
        _color = color,
        _fallbackDirection = fallbackDirection {
    if (kDebugMode) {
      debugPrint(
        '🆕 RenderGap<init> '
        'mainAxisExtent=$mainAxisExtent '
        'crossAxisExtent=$crossAxisExtent '
        'color=$color '
        'fallbackDirection=$fallbackDirection',
      );
    }
  }

  double get mainAxisExtent => _mainAxisExtent;
  double _mainAxisExtent;
  set mainAxisExtent(double value) {
    if (_mainAxisExtent != value) {
      if (kDebugMode) {
        debugPrint('📏 mainAxisExtent set: $_mainAxisExtent -> $value');
      }
      _mainAxisExtent = value;
      markNeedsLayout();
    }
  }

  double? get crossAxisExtent => _crossAxisExtent;
  double? _crossAxisExtent;
  set crossAxisExtent(double? value) {
    if (_crossAxisExtent != value) {
      if (kDebugMode) {
        debugPrint('📐 crossAxisExtent set: $_crossAxisExtent -> $value');
      }
      _crossAxisExtent = value;
      markNeedsLayout();
    }
  }

  Axis? get fallbackDirection => _fallbackDirection;
  Axis? _fallbackDirection;
  set fallbackDirection(Axis? value) {
    if (_fallbackDirection != value) {
      if (kDebugMode) {
        debugPrint('🧭 fallbackDirection set: $_fallbackDirection -> $value');
      }
      _fallbackDirection = value;
      markNeedsLayout();
    }
  }

  Axis? get _direction {
    final parentNode = parent;
    if (parentNode is RenderFlex) {
      return parentNode.direction;
    } else {
      return fallbackDirection;
    }
  }

  Color? get color => _color;
  Color? _color;
  set color(Color? value) {
    if (_color != value) {
      if (kDebugMode) {
        debugPrint('🎨 color set: $_color -> $value');
      }
      _color = value;
      markNeedsPaint();
    }
  }

  @override
  double computeMinIntrinsicWidth(double height) {
    final result = _computeIntrinsicExtent(
      Axis.horizontal,
      () => super.computeMinIntrinsicWidth(height),
    )!;
    if (kDebugMode) {
      debugPrint('🔹 computeMinIntrinsicWidth(height=$height) => $result');
    }
    return result;
  }

  @override
  double computeMaxIntrinsicWidth(double height) {
    final result = _computeIntrinsicExtent(
      Axis.horizontal,
      () => super.computeMaxIntrinsicWidth(height),
    )!;
    if (kDebugMode) {
      debugPrint('🔷 computeMaxIntrinsicWidth(height=$height) => $result');
    }
    return result;
  }

  @override
  double computeMinIntrinsicHeight(double width) {
    final result = _computeIntrinsicExtent(
      Axis.vertical,
      () => super.computeMinIntrinsicHeight(width),
    )!;
    if (kDebugMode) {
      debugPrint('🔸 computeMinIntrinsicHeight(width=$width) => $result');
    }
    return result;
  }

  @override
  double computeMaxIntrinsicHeight(double width) {
    final result = _computeIntrinsicExtent(
      Axis.vertical,
      () => super.computeMaxIntrinsicHeight(width),
    )!;
    if (kDebugMode) {
      debugPrint('🔶 computeMaxIntrinsicHeight(width=$width) => $result');
    }
    return result;
  }

  double? _computeIntrinsicExtent(Axis axis, double Function() compute) {
    final Axis? direction = _direction;
    if (direction == axis) {
      final result = _mainAxisExtent;
      if (kDebugMode) {
        debugPrint(
          '📐 _computeIntrinsicExtent(axis=$axis, direction=$direction) => $result',
        );
      }
      return result;
    } else {
      if (_crossAxisExtent!.isFinite) {
        final result = _crossAxisExtent;
        if (kDebugMode) {
          debugPrint(
            '📐 _computeIntrinsicExtent(axis=$axis, direction=$direction) => $result',
          );
        }
        return result;
      } else {
        final result = compute();
        if (kDebugMode) {
          debugPrint(
            '📐 _computeIntrinsicExtent(axis=$axis, direction=$direction) => $result',
          );
        }
        return result;
      }
    }
  }

  @override
  Size computeDryLayout(BoxConstraints constraints) {
    final Axis? direction = _direction;

    if (direction != null) {
      if (direction == Axis.horizontal) {
        final s =
            constraints.constrain(Size(mainAxisExtent, crossAxisExtent!));
        if (kDebugMode) {
          debugPrint(
            '💧 computeDryLayout(constraints=$constraints, direction=$direction) => $s',
          );
        }
        return s;
      } else {
        final s =
            constraints.constrain(Size(crossAxisExtent!, mainAxisExtent));
        if (kDebugMode) {
          debugPrint(
            '💧 computeDryLayout(constraints=$constraints, direction=$direction) => $s',
          );
        }
        return s;
      }
    } else {
      throw FlutterError(
        'A Gap widget must be placed directly inside a Flex widget '
        'or its fallbackDirection must not be null',
      );
    }
  }

  @override
  void performLayout() {
    size = computeDryLayout(constraints);
    if (kDebugMode) {
      debugPrint('🛠 performLayout(constraints=$constraints) size=$size');
    }
  }

  @override
  void paint(PaintingContext context, Offset offset) {
    if (color != null) {
      final Paint paint = Paint()..color = color!;
      context.canvas.drawRect(offset & size, paint);
      if (kDebugMode) {
        debugPrint('🎨 paint(offset=$offset, size=$size, color=$color)');
      }
    } else {
      if (kDebugMode) {
        debugPrint('🎨 paint(offset=$offset, size=$size, color=null)');
      }
    }
  }

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    if (kDebugMode) {
      debugPrint('🧾 debugFillProperties()');
    }
    properties.add(DoubleProperty('mainAxisExtent', mainAxisExtent));
    properties.add(DoubleProperty('crossAxisExtent', crossAxisExtent));
    properties.add(ColorProperty('color', color));
    properties.add(EnumProperty<Axis>('fallbackDirection', fallbackDirection));
  }
}

截屏2026-01-30 19.30.39.png

真正绘制原理, RenderGapRenderBox的子类, 不需要子类, 绘制时, 只与自身sizecolor有关。

mainAxisExtentcrossAxisExtent属性set方法触发后, 会执行markNeedsLayout, 标记该渲染对象需要重新布局, 并请求(requestVisualUpdate)调度下一帧执行布局。

布局阶段,会执行computeDryLayoutperformLayout方法,更新size

绘制阶段paint,在 offset & size 的矩形内填充颜色(color 为 null 时不绘制)。

  • 矩形范围:offset & size 等价于 Rect.fromLTWH(offset.dx, offset.dy, size.width, size.height),保证绘制严格位于本组件区域。
  • 无子节点与图层:RenderGap 不 push 额外 Layer,也不绘制子内容;仅把一个矩形指令提交到当前画布。

markNeedsLayout布局阶段不同的是, markNeedsPaint绘制阶段不参与尺寸计算, 它在size确定后才执行。

与标记方法的关系:

  • markNeedsPaint:当 color 变更时由属性 setter 调用,标记本节点需要在下一帧重绘;不会触发布局。
  • markNeedsLayout:当 mainAxisExtent/crossAxisExtent/fallbackDirection 变更引起尺寸或方向变化时调用;下一帧会重新布局,布局完成后若绘制区域或内容也需更新才会出现 paint。
  • 执行链路示例:属性变更 → 标记(layout/paint)→ 布局(computeDryLayout/performLayout)→ 绘制(paint)。

React 手写实现的 KeepAlive 组件 🚀

React 手写实现的 KeepAlive 组件 🚀

引言 📝

在 React 开发中,你是否遇到过这样的场景:切换 Tab 页面后,返回之前的页面,输入的内容、计数状态却 “消失不见” 了?🤔 这是因为 React 组件默认在卸载时会销毁状态,重新渲染时会创建新的实例。而 KeepAlive 组件就像一个 “状态保鲜盒”,能让组件在隐藏时不卸载,保持原有状态,再次显示时直接复用。今天我们就结合实战代码,从零拆解 KeepAlive 组件的实现逻辑,带你吃透这一实用技能!

一、什么是 Keep-Alive? 🧩

Keep-Alive 源于 Vue 的内置组件,在 React 中并没有原生支持,但提供了组件缓存能力的第三方库react-activation,我们可以通过import {KeepAlive} from 'react-activation'; 导入KeepAlive获得状态保存能力。

现在我们来手动实现其核心功能,它本质是一个组件缓存容器,核心特性如下:

  • 缓存组件实例,避免组件频繁挂载 / 卸载,减少性能开销;
  • 保持组件状态(如 useState 数据、表单输入值等),提升用户体验;
  • 通过 “显隐控制” 替代 “挂载 / 卸载”,组件始终存在于 DOM 中,并未卸载,只是通过样式隐藏;
  • 支持以唯一标识(如 activeId)管理多个组件的缓存与切换。

简单说,Keep-Alive 就像给组件 “冬眠” 的能力 —— 不用时休眠(隐藏),需要时唤醒(显示),状态始终不变 ✨。

二、为什么需要 Keep-Alive?(作用 + 场景 + 使用)🌟

1. 核心作用

  • 状态保留:避免组件切换时丢失临时状态(如表单输入、计数、滚动位置);
  • 性能优化:减少重复渲染和生命周期函数执行(如 useEffect 中的接口请求);
  • 体验提升:切换组件时无加载延迟,操作连贯性更强。

2. 适用场景

  • Tab 切换页面:如后台管理系统的多标签页、移动端的底部导航切换;
  • 路由跳转:列表页跳转详情页后返回,保留列表筛选条件和滚动位置;
  • 高频切换组件:如表单分步填写、弹窗与页面的切换;
  • 资源密集型组件:如包含大量图表、视频的组件,避免重复初始化。

3. 基础使用方式

在我们的实战代码中,Keep-Alive 的使用非常简洁:

jsx

// 父组件中包裹需要缓存的组件,传入 activeId 控制激活状态
<KeepAlive activeId={activeTab}>
  {activeTab === 'A' ? <Counter name="A" /> : <OtherCounter name="B" />}
</KeepAlive>
  • activeId:唯一标识,用于区分当前激活的组件;
  • children:需要缓存的组件实例,支持动态切换不同组件。

三、手写 KeepAlive 组件的实现思路 🔍

1. 核心需求分析

要实现一个通用的 Keep-Alive 组件,需满足以下条件:

  • 支持多组件缓存:能同时缓存多个组件,通过 activeId 区分;
  • 自动更新缓存:新组件首次激活时自动存入缓存,已缓存组件直接复用;
  • 灵活控制显隐:只显示当前激活的组件,其余组件隐藏;
  • 兼容性强:不侵入子组件逻辑,子组件无需修改即可使用;
  • 状态稳定:缓存的组件状态不丢失,生命周期不重复执行。

2. 实现步骤拆解(结合代码讲解)

初始化一个React项目,选择JavaScript语言。

我们的 KeepAlive 组件代码位于 src/components/KeepAlive.jsx,核心分为 3 个步骤,一步步拆解如下:

步骤一:定义缓存容器 📦

核心思路:用 React 的 useState 定义一个缓存对象 cache,以 activeId 为 key,缓存对应的组件实例(children)。

jsx

import { useState, useEffect } from 'react';

const KeepAlive = ({ activeId, children }) => {
  // 定义缓存容器:key 是 activeId,value 是对应的组件实例(children)
  // 初始值为空对象,保证首次渲染时无缓存组件
  const [cache, setCache] = useState({}); 

  // 后续逻辑...
};
  • 为什么用对象作为缓存容器?对象的 key 支持字符串类型的 activeId,查询和修改效率高(O (1)),且配合 Object.entries 方便遍历;
  • Map 也可作为缓存容器(key 可支持对象类型),但本例中 activeId 是字符串,对象足够满足需求,更简洁。
步骤二:监听依赖,更新缓存 🔄

核心思路:通过 useEffect 监听 activeIdchildren 的变化,当切换组件时,若当前 activeId 对应的组件未被缓存,则存入缓存。

jsx

useEffect(() => {
  // 逻辑:如果当前 activeId 对应的组件未在缓存中,就添加到缓存
  if (!cache[activeId]) { 
    // 利用函数式更新,确保拿到最新的缓存状态(prev 是上一次的 cache)
    setCache((prev) => ({
      ...prev, // 保留已有的缓存组件
      [activeId]: children // 新增当前 activeId 对应的组件到缓存
    }))
  }
}, [activeId, children, cache]); // 依赖项:activeId 变了、组件变了、缓存变了,都要重新检查
  • 依赖项说明:

    • activeId:切换标签时触发,检查新标签对应的组件是否已缓存;
    • children:若传入的组件实例变化(如 props 改变),需要更新缓存中的组件;
    • cache:确保获取最新的缓存状态,避免覆盖已有缓存;
  • 为什么不直接 setCache({...cache, [activeId]: children})? 因为 cache 是状态,直接使用可能拿到旧值,函数式更新(prev => {...})能保证拿到最新的状态,避免缓存丢失。

步骤三:遍历缓存,控制组件显隐 🎭

核心思路:通过 Object.entries 将缓存对象转为 [key, value] 二维数组,遍历渲染所有缓存组件,通过 display 样式控制显隐(激活的组件显示,其余隐藏)。

jsx

return (
  <>
    {
      // Object.entries(cache):将缓存对象转为二维数组,格式如 [[id1, component1], [id2, component2]]
      Object.entries(cache).map(([id, component]) => (
        <div 
          key={id} // 用缓存的 id 作为 key,确保 React 正确识别组件
          // 显隐控制:当前 id 等于 activeId 时显示(block),否则隐藏(none)
          style={{ display: id === activeId ? 'block' : 'none' }}
        >
          {component} {/* 渲染缓存的组件实例 */}
        </div>
      ))
    }
  </>
);
  • 关键逻辑:所有缓存的组件都会被渲染到 DOM 中,但通过 display: none 隐藏未激活的组件,这样组件不会卸载,状态得以保留;
  • key 的作用:必须用 id 作为 key,避免 React 误判组件身份,导致状态丢失。

3.关键逻辑拆解

四、完整代码及效果演示 📸

1. 完整 KeepAlive 组件(src/components/KeepAlive.jsx

jsx

import { useState, useEffect } from 'react';

/**
 * KeepAlive 组件:缓存 React 组件,避免卸载,保持状态
 * @param {string} activeId - 当前激活的组件标识(唯一key)
 * @param {React.ReactNode} children - 需要缓存的组件实例
 * @returns {JSX.Element} 渲染所有缓存组件,控制显隐
 */
const KeepAlive = ({ activeId, children }) => {
  // 缓存容器:key 为 activeId,value 为对应的组件实例
  const [cache, setCache] = useState({});

  // 监听 activeId、children、cache 变化,更新缓存
  useEffect(() => {
    // 若当前 activeId 对应的组件未缓存,则添加到缓存
    if (!cache[activeId]) {
      // 函数式更新,确保拿到最新的缓存状态
      setCache((prevCache) => ({
        ...prevCache, // 保留已有缓存
        [activeId]: children // 新增当前组件到缓存
      }));
    }
  }, [activeId, children, cache]);

  // 遍历缓存,渲染所有组件,通过 display 控制显隐
  return (
    <>
      {Object.entries(cache).map(([id, component]) => (
        <div
          key={id}
          style={{
            display: id === activeId ? 'block' : 'none',
          }}
        >
          {component}
        </div>
      ))}
    </>
  );
};

export default KeepAlive;

2. 模拟 Tab 切换场景(src/App.jsx

jsx

import { useState, useEffect } from 'react';
import KeepAlive from './components/KeepAlive.jsx';

// 计数组件 A:演示状态保留
const Counter = ({ name }) => {
  const [count, setCount] = useState(0);

  // 模拟组件挂载/卸载生命周期
  useEffect(() => {
    console.log(`✨ 组件 ${name} 挂载完成`);
    return () => {
      console.log(`❌ 组件 ${name} 卸载完成`);
    };
  }, [name]);

  return (
    <div style={{ padding: '20px', border: '1px solid #646cff', borderRadius: '8px', margin: '10px 0' }}>
      <h3 style={{ color: '#646cff' }}>{name} 视图</h3>
      <p>当前计数:{count} 🎯</p>
      <button onClick={() => setCount(count + 1)} style={{ marginRight: '10px' }}>+1</button>
      <button onClick={() => setCount(0)}>重置</button>
    </div>
  );
};

// 计数组件 B:与 A 功能一致,用于模拟切换
const OtherCounter = ({ name }) => {
  const [count, setCount] = useState(0);

  useEffect(() => {
    console.log(`✨ 组件 ${name} 挂载完成`);
    return () => {
      console.log(`❌ 组件 ${name} 卸载完成`);
    };
  }, [name]);

  return (
    <div style={{ padding: '20px', border: '1px solid #535bf2', borderRadius: '8px', margin: '10px 0' }}>
      <h3 style={{ color: '#535bf2' }}>{name} 视图</h3>
      <p>当前计数:{count} 🎯</p>
      <button onClick={() => setCount(count + 1)} style={{ marginRight: '10px' }}>+1</button>
      <button onClick={() => setCount(0)}>重置</button>
    </div>
  );
};

const App = () => {
  // 控制当前激活的 Tab,默认激活 A 组件
  const [activeTab, setActiveTab] = useState('A');

  return (
    <div style={{ maxWidth: '800px', margin: '0 auto', padding: '2rem' }}>
      <h1 style={{ textAlign: 'center', marginBottom: '2rem', color: '#242424' }}>
        React KeepAlive 组件实战 🚀
      </h1>

      {/* Tab 切换按钮 */}
      <div style={{ textAlign: 'center', marginBottom: '2rem' }}>
        <button
          onClick={() => setActiveTab('A')}
          style={{
            marginRight: '1rem',
            padding: '0.8rem 1.5rem',
            backgroundColor: activeTab === 'A' ? '#646cff' : '#f9f9f9',
            color: activeTab === 'A' ? 'white' : '#242424'
          }}
        >
          显示 A 组件
        </button>
        <button
          onClick={() => setActiveTab('B')}
          style={{
            padding: '0.8rem 1.5rem',
            backgroundColor: activeTab === 'B' ? '#535bf2' : '#f9f9f9',
            color: activeTab === 'B' ? 'white' : '#242424'
          }}
        >
          显示 B 组件
        </button>
      </div>

      {/* 用 KeepAlive 包裹需要缓存的组件 */}
      <KeepAlive activeId={activeTab}>
        {activeTab === 'A' ? <Counter name="A" /> : <OtherCounter name="B" />}
      </KeepAlive>

      <div style={{ marginTop: '2rem', textAlign: 'center', color: '#888' }}>
        👉 切换 Tab 试试,组件状态不会丢失哦!
      </div>
    </div>
  );
};

export default App;

3. 效果展示

(1)功能效果
  • 首次进入页面:显示 A 组件,计数为 0;
  • 点击 A 组件 “+1” 按钮,计数变为 7;
  • 切换到 B 组件:B 组件计数为 0,A 组件隐藏(未卸载);
  • 点击 B 组件 “+1” 按钮,计数变为 5;
  • 切换回 A 组件:A 组件计数依然是 7,无需重新初始化;
  • 控制台日志:只有组件挂载日志,无卸载日志,证明组件始终存在。
(2)用户体验
  • 切换无延迟,状态无缝衔接;
  • 避免重复执行 useEffect 中的逻辑(如接口请求),提升性能;

QQ20260130-172541.gif

五、核心知识点梳理 📚

通过手写 KeepAlive 组件,我们掌握了这些关键知识点:

  1. React Hooks 实战useState 管理缓存状态,useEffect 监听依赖更新,函数式更新避免状态覆盖;
  2. 组件生命周期控制:通过 display 样式控制组件显隐,替代挂载 / 卸载,从而保留状态;
  3. 数据结构应用:对象作为缓存容器,Object.entries 实现对象遍历;
  4. Props 传递与复用children props 让 KeepAlive 组件通用化,支持任意子组件缓存;
  5. 状态管理思路:以唯一标识(activeId)关联组件,确保缓存的准确性和唯一性;
  6. 性能优化技巧:避免组件频繁挂载 / 卸载,减少 DOM 操作和资源消耗;
  7. 组件设计原则:通用、低侵入、易扩展,不修改子组件逻辑即可实现缓存功能。

补充: Map 与 JSON 的区别 ——Map 可以直接存储对象作为 key,而 JSON 只能存储字符串。如果需要缓存以对象为标识的组件,可将 cache 改为 Map 类型,优化如下:

jsx

// 用 Map 替代对象作为缓存容器
const [cache, setCache] = useState(new Map());

// 更新缓存
useEffect(() => {
  if (!cache.has(activeId)) {
    setCache((prev) => new Map(prev).set(activeId, children));
  }
}, [activeId, children, cache]);

// 遍历缓存
return (
  <>
    {Array.from(cache.entries()).map(([id, component]) => (
      <div key={id} style={{ display: id === activeId ? 'block' : 'none' }}>
        {component}
      </div>
    ))}
  </>
);

六、结语 🎉

手写 Keep-Alive 组件看似简单,却涵盖了 React 组件设计、状态管理、性能优化等多个核心知识点。它的核心思想是 “缓存 + 显隐控制”,通过巧妙的状态管理避免组件卸载,从而保留状态。

在实际开发中,我们可以基于这个基础版本扩展更多功能:比如设置缓存上限(避免内存溢出)、手动清除缓存、支持路由级缓存等。掌握了这个组件的实现逻辑,你不仅能解决实际开发中的状态保留问题,还能更深入理解 React 组件的渲染机制和生命周期。

希望这篇文章能带你吃透 Keep-Alive 组件的核心原理,下次遇到类似需求时,也能从容手写实现!如果觉得有收获,欢迎点赞收藏,一起探索 React 的更多实战技巧吧~ 🚀

React-Hooks逻辑复用艺术

前言

在 React 开发中,Hooks 的出现彻底改变了逻辑复用的方式。它让我们能够将复杂的、可复用的逻辑从 UI 组件中抽离,实现真正的“关注点分离”。本文将分享 Hooks 的核心原则,并提供 4 个在真实业务场景中封装的实战案例。

一、 Hooks 核心

1. 概念理解

Hooks 本质上是将组件间共享的逻辑抽离并封装成的特殊函数

2. 使用“红线”:规则与原理

  • 命名规范:必须以 use 开头(如 useChat),这不仅是约定,也是静态检查工具(ESLint)识别 Hook 的依据。
  • 调用位置严禁在循环、条件判断或嵌套函数中调用 Hook

底层原理: React 内部并不是通过“变量名”来记录 Hook 状态的,而是通过链表 。每次渲染时,React 严格依赖 Hook 的调用顺序来查找对应的状态。

注意: 如果在 if 语句中调用 Hook,一旦条件不成立导致某次渲染跳过了该 Hook,整个链表的指针就会错位,导致状态读取异常。

二、 实战:自定义 Hooks 封装

1. AI 场景:消息点赞/点踩逻辑 (useChatEvaluate)

在 AI 对话系统中,消息评价是通用功能。我们需要处理:状态切换(点赞 -> 取消点赞)、单选逻辑、以及异步接口调用。

import React, { useState } from 'react';

// 模拟接口
const public_evaluateMessage = async (params: any) => ({ data: true });

type EvaluateType = "GOOD" | "BAD" | "NONE";

export const useChatEvaluate = (initialType: EvaluateType = "NONE") => {
  const [ratingType, setRatingType] = useState<EvaluateType>(initialType);

  const evaluateMessage = async (contentId: number, type: "GOOD" | "BAD") => {
    let newEvaluateType: EvaluateType;

    // 逻辑:如果点击已选中的类型,则取消选中(NONE);否则切换到新类型
    if (type === "GOOD") {
      newEvaluateType = ratingType === "GOOD" ? "NONE" : "GOOD";
    } else {
      newEvaluateType = ratingType === "BAD" ? "NONE" : "BAD";
    }

    try {
      const res = await public_evaluateMessage({
        contentId,
        ratingType: newEvaluateType,
        content: "",
      });

      if (res.data === true) {
        setRatingType(newEvaluateType);
      }
    } catch (error) {
      console.error("评价失败:", error);
    }
  };

  return { ratingType, evaluateMessage };
};

// 使用示例
const ChatMessage: React.FC<{ id: number }> = ({ id }) => {
  const { ratingType, evaluateMessage } = useChatEvaluate();
  return (
    <button onClick={() => evaluateMessage(id, "GOOD")}>
      {ratingType === "GOOD" ? "👍 已点赞" : "👍 点赞"}
    </button>
  );
};

2. 响应式布局:屏幕尺寸监听 (useMediaSize)

在响应式系统中,封装一个能根据窗口宽度自动切换“设备类型”的 Hook,可以极大地简化响应式开发。

import { useState, useEffect, useMemo } from 'react';

export enum MediaType {
  mobile = 'mobile',
  tablet = 'tablet',
  pc = 'pc',
}

const useMediaSize = (): MediaType => {
  const [width, setWidth] = useState<number>(globalThis.innerWidth);

  useEffect(() => {
    const handleWindowResize = () => setWidth(window.innerWidth);
    window.addEventListener('resize', handleWindowResize);
    // 记得清理事件监听
    return () => window.removeEventListener('resize', handleWindowResize);
  }, []);

  // 使用 useMemo 避免每次渲染都重新运行计算逻辑
  const media = useMemo(() => {
    if (width <= 640) return MediaType.mobile;
    if (width <= 768) return MediaType.tablet;
    return MediaType.pc;
  }, [width]);

  return media;
};

export default useMediaSize;

3. 性能优化:防抖与节流 Hook

A. 防抖 Hook (useDebounce)

常用于搜索框,防止用户快速输入时频繁触发请求。

import { useState, useEffect } from 'react';

function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    // 关键:在下一次 useEffect 执行前清理上一次的定时器
    return () => clearTimeout(handler);
  }, [value, delay]);

  return debouncedValue;
}

export default useDebounce;

B. 节流 Hook (useThrottle)

常用于滚动加载、窗口缩放,确保在规定时间内只执行一次。

import { useState, useEffect, useRef } from 'react';

function useThrottle<T>(value: T, delay: number): T {
  const [throttledValue, setThrottledValue] = useState<T>(value);
  const lastExecuted = useRef<number>(Date.now());

  useEffect(() => {
    const now = Date.now();
    const remainingTime = delay - (now - lastExecuted.current);

    if (remainingTime <= 0) {
      // 立即执行
      setThrottledValue(value);
      lastExecuted.current = now;
    } else {
      // 设置定时器处理剩余时间
      const timer = setTimeout(() => {
        setThrottledValue(value);
        lastExecuted.current = Date.now();
      }, remainingTime);

      return () => clearTimeout(timer);
    }
  }, [value, delay]);

  return throttledValue;
}

export default useThrottle;

三、 总结:封装自定义 Hook 的心法

  1. 抽离状态而非仅逻辑:如果一段逻辑只涉及纯函数计算,不需要 Hook;只有涉及 useStateuseEffect 等状态管理时,才有必要封装 Hook。
  2. 保持纯净:自定义 Hook 应该只关心逻辑,而不应该直接操作 DOM。
  3. TS 类型保护:利用泛型 <T> 增强 Hook 的兼容性,让它能适配各种数据类型。

一个Vite插件实现PC到移动端项目的高效迁移方案

当PC端项目需要迁移到移动端时,你是否还在手动复制粘贴代码?今天分享一个我们团队自研的Vite插件,帮你实现跨仓库、跨技术栈的代码高效复用!

背景:从PC到移动端的迁移之痛

最近我们团队遇到了一个典型的企业级需求:将一个成熟的PC端医疗管理系统(MDM)迁移到移动端。听起来简单,但实际上却面临诸多挑战:

面临的挑战

  1. 技术栈差异:PC端使用Element Plus,移动端需要Vant
  2. 仓库隔离:PC端和移动端在不同的Git仓库
  3. 代码复用:希望复用80%的业务逻辑,但UI组件完全不同
  4. 维护同步:业务逻辑更新需要在两端同步

传统的解决方案要么是完全重写(成本高),要么是复制粘贴(维护噩梦),或者是Monorepo (代码和依赖放一起)。我们需要的是一种既能复用核心逻辑,代码在不同仓库维护,又能灵活定制UI的解决方案。

解决方案:vite-plugin-code-reuse

基于这个需求,我们开发了 vite-plugin-code-reuse 插件,它的核心思想是:多仓库代码复用、智能替换、无缝集成

插件核心能力

// 插件的核心配置结构
interface PluginConfig {
  repositories: RepositoryConfig[];     // 代码仓库配置
  repoImportMappings: RepoImportMappings[]; // 路径映射,主要是规避不同仓库路径别名冲突问题
  importReplacements: ImportReplacementConfig[]; // 导入替换
}

实战案例:医疗管理系统迁移

让我通过实际案例展示这个插件的效果。

项目背景

  • PC端项目xlian-web-mdm(Vue 3 + Element Plus + TypeScript)
  • 移动端项目:新建的H5项目(Vue 3 + Vant + TypeScript)
  • 目标:复用PC端80%的业务逻辑,100%替换UI组件

第一步:安装配置插件

npm install vite-plugin-code-reuse --save-dev
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import codeReusePlugin from 'vite-plugin-code-reuse'
import path from 'path'

export default defineConfig({
  plugins: [
    vue(),
    codeReusePlugin({
      // 1. 引入PC端代码仓库
      repositories: [
        {
          url: 'http://gitlab.xinglianhealth.com/web/mdm/xlian-web-mdm.git',
          branch: 'master',
          dir: 'mdm-pc'  // 本地存放目录
        }
      ],
      
      // 2. 修正路径别名映射,pc和移动都配置了“@”别名,需要各自引用正确的路径
      repoImportMappings: [
        {
          alias: '@',
          repoDir: 'mdm-pc',
          // PC端中的“@”别名还是引用pc端目录下的代码,但是需要排除路由、状态管理等路径,引用移动端的,因为路由和store不能存在两个
          ignorePatterns: ['src/router', 'src/store', 'src/axios']
        }
      ],
      
      // 3. 智能导入替换,pc端的部分组件无法复用时,可以做替换
      importReplacements: [
        // 场景1:组件替换(Element Plus → Vant)
        {
          pattern: /\/views\/MasterData\/components\/UploadFile\.vue$/,
          file: 'src/components/MbUpload.vue' // 移动端专用上传组件
        },
        {
          pattern: /\/views\/MasterData\/components\/TextInput\.vue$/,
          file: 'src/components/MbTextInput.vue' // 移动端输入框
        },
        
        // 场景2:复杂表单组件替换
        {
          pattern: /\/views\/MasterData\/components\/MasterForm\.vue$/,
          file: 'src/components/MbForm.vue' // 移动端表单封装
        },
        
        // 场景3:PC端特有功能在移动端隐藏
        {
          pattern: /\/views\/MasterData\/components\/HeaderFilter\/HeaderFilter\.vue$/,
          code: '<template></template>' // 移动端不需要复杂的表头筛选
        },
        
        // 场景4:UI库替换
        {
          pattern: /^@?element-plus/,
          resolve: path.resolve('src/components/ElementPlus.ts') // 重定向到兼容层
        }
      ]
    })
  ]
})

第二步:UI组件替换

// src/components/ElementPlus.ts - UI库兼容层
import { Button, Input, Select } from './ui-adaptor'

// 创建Element Plus到Vant的映射
export {
  ElButton: Button,
  ElInput: Input,
  ElSelect: Select,
  // ... 更多映射
}

// src/components/ui-adaptor.ts - UI库适配层,以Button组件为例

<template><van-button v-bind="$attrs" /></template>
<script>
const props = defineProps({
// 对element-plus Button Props做适配,比如size不支持"medium",可以处理成其他的,相同的属性不用处理
})
</script>

第三步:复用业务逻辑组件

<!-- src/views/MasterData/PatientList.vue -->
<template>
  <!-- 复用PC端的模板结构,但使用移动端组件 -->
  <div class="patient-list">
    <!-- 搜索框(PC端是ElInput,自动替换为Vant Field) -->
    <van-field 
      v-model="searchKey"
      placeholder="搜索患者"
      @input="handleSearch"
    />
    
    <!-- 患者列表 -->
    <van-list 
      v-model:loading="loading"
      :finished="finished"
      @load="loadPatients"
    >
      <patient-item 
        v-for="patient in patients"
        :key="patient.id"
        :patient="patient"
        @click="handlePatientClick"
      />
    </van-list>
  </div>
</template>

<script setup lang="ts">
// 这里直接复用PC端的业务逻辑!
import { usePatientList } from '@/mdm-pc/src/views/MasterData/composables/usePatientList'

// 完全复用PC端的逻辑,包括:
// 1. 数据获取逻辑
// 2. 搜索过滤逻辑  
// 3. 分页逻辑
// 4. 事件处理逻辑
const {
  patients,
  loading,
  finished,
  searchKey,
  loadPatients,
  handleSearch,
  handlePatientClick
} = usePatientList()
</script>

<style scoped>
/* 移动端特有的样式 */
.patient-list {
  padding: 12px;
}
</style>

插件的核心实现原理

1. 代码仓库管理

vite build start开始时,自动拉取PC端仓库代码,如无更新不会重复拉取,默认只拉取一个commit,速度极快。

{
  url: 'http://gitlab.xinglianhealth.com/web/mdm/xlian-web-mdm.git', //仓库地址
  branch: 'master', // 仓库分支
  dir: 'mdm-pc'  // 本地存放目录
}

image.png


### 2. 智能导入替换,支持三种替换方式,任意选择

```typescript
interface ImportReplacementConfig {
    /**
     * 匹配模式(正则表达式字符串)
     */
    pattern: RegExp;
    /**
     * 替换方式:代码字符串
     */
    code?: string;
    /**
     * 替换方式:文件路径
     */
    file?: string;
    /**
     * 替换方式:重定向路径
     */
    resolve?: string;
}

3. 别名路径冲突映射修正,将被引用的仓库内部别名指向仓库内部,规避和外层别名的冲突

interface RepoImportMappings {
    /**
     * 路径别名
     */
    alias: string;
    /**
     * 冲突的仓库目录
     */
    repoDir: string;
    /**
     * 忽略列表(路径匹配时跳过),使用外出仓库别名解析
     */
    ignorePatterns?: string[];
}

实际效果对比

迁移前(传统方式)

├── 移动端项目
│   ├── src
│   │   ├── views
│   │   │   ├── PatientList.vue    ← 需要重写
│   │   │   ├── DoctorList.vue     ← 需要重写
│   │   │   └── ... (20+个页面)
│   │   └── components
│   │       ├── MbForm.vue         ← 需要重写
│   │       └── ... (50+个组件)
└── 工时:3-4人月

迁移后(使用插件)

├── 移动端项目
│   ├── mdm-pc/                    ← 自动引入的PC端代码
│   ├── src
│   │   ├── views
│   │   │   ├── PatientList.vue    ← 直接引用PC端PatientList组件,只对样式做适配覆盖
│   │   │   ├── DoctorList.vue     ← 直接引用PC端DoctorList组件,只对样式做适配覆
│   │   │   └── ... (复用80%)
│   │   └── components
│   │       ├── MbUploader.vue     ← 无法复用的组件,用移动端专用文件组件做替换
│   │       └── ... (只需写30%的组件)
└── 工时:1-1.5人月(节省60%+)

高级应用场景

场景1:多项目共享工具库

// 多个项目共享工具函数
codeReusePlugin({
  repositories: [
    {
      url: 'git@github.com:company/shared-utils.git',
      branch: 'main',
      dir: 'shared-utils'
    },
    ...
  ],
  importReplacements: [
    {
      pattern: /^@shared\/utils/,
      resolve: path.resolve('shared-utils/src')
    },
    ...
  ]
})

场景2:主题系统切换

// 根据环境切换主题
codeReusePlugin({
  importReplacements: [
    {
      pattern: /\/themes\/default/,
      file: process.env.NODE_ENV === 'mobile' 
        ? 'src/themes/mobile.vue'
        : 'src/themes/pc.vue'
    }
  ]
})

场景3:A/B测试版本

// A/B测试不同版本的组件
codeReusePlugin({
  importReplacements: [
    {
      pattern: /\/components\/CheckoutButton\.vue$/,
      file: Math.random() > 0.5 
        ? 'src/components/CheckoutButtonVariantA.vue'
        : 'src/components/CheckoutButtonVariantB.vue'
    }
  ]
})

总结

vite-plugin-code-reuse 插件为我们解决了跨项目代码复用的核心痛点:

🎯 核心价值

  1. 大幅提升开发效率:节省60%+的开发时间
  2. 保证代码一致性:业务逻辑完全一致,减少BUG
  3. 降低维护成本:一处修改,多处生效
  4. 灵活定制:UI层完全可定制,不影响核心逻辑

🚀 适用场景

  • PC端到移动端的项目迁移
  • 多项目共享组件库
  • 微前端架构中的模块复用
  • A/B测试和实验性功能

如果你也面临类似的多项目代码复用问题,不妨试试这个插件。项目已在GitHub开源,欢迎Star和贡献代码!

GitHub地址vite-plugin-code-reuse

让代码复用变得简单,让开发效率飞起来! 🚀

《打造高效的前端工程师终端:一份可复制的 Zsh + Powerlevel10k 配置实践》

目标很简单:快、稳、爽

快:打开终端不拖泥带水; 稳:补全、历史、插件不互相打架; 爽:git commit 这种高频命令,肌肉记忆级体验。

这篇文章基于一份可直接使用的 .zshrc 配置,完整讲清楚每一段配置解决了什么问题、为什么要这样放、以及它带来的实际体验提升。

一、为什么要“认真配置”终端?

对于前端工程师来说,终端并不是偶尔用一下的工具,而是:

  • 高频 Git 操作(git commit / rebase / checkout
  • 包管理(pnpm / npm / yarn
  • 本地调试、构建、脚手架

如果终端具备下面这些能力:

  • ↑ / ↓ 只在“相关历史”里循环
  • 自动联想但不抢键
  • 补全稳定、无卡顿

每天节省的不是几秒,而是注意力和心智负担

二、整体结构设计原则

这份配置遵循几个明确的原则:

  1. 启动相关的配置尽量靠前(避免闪屏、卡顿)
  2. 功能性模块分区清晰(补全、历史、联想、高亮各司其职)
  3. 顺序严格(这是很多问题的根源)

下面按模块逐一拆解。

三、Powerlevel10k Instant Prompt:启动速度的关键

if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

这是 Powerlevel10k 官方推荐的 Instant Prompt 写法,作用是:

  • 在 Zsh 完全初始化之前,先渲染 Prompt
  • 避免终端启动时的“白屏等待”

四、NVM 与主题加载:稳定优先

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"

source /opt/homebrew/share/powerlevel10k/powerlevel10k.zsh-theme
[[ -f ~/.p10k.zsh ]] && source ~/.p10k.zsh

这里选择的是最稳妥、最不容易出坑的方式:

  • 不做过度魔改
  • 不提前优化启动时间

如果后续需要追求极致启动速度,再对 NVM 做 lazy load 即可。

五、PATH 管理:去重是隐藏的工程师细节

# 示例:将自定义工具加入 PATH(请按需修改或删除)
# export PATH="$HOME/.comate/bin:$PATH"

typeset -U PATH path

typeset -U PATH path 的作用是:

  • 自动去重 PATH
  • 保留第一次出现的顺序

这能避免:

  • PATH 无限增长
  • 同一个二进制被多次扫描

属于“看不见,但很专业”的配置。

六、补全系统:一切体验的地基

autoload -Uz compinit
compinit -d ~/.zcompdump

补全系统是很多插件的基础(包括自动联想)。

显式指定 .zcompdump 文件可以:

  • 避免偶发的补全重建
  • 提高稳定性

顺序要求

compinit 必须在 autosuggestions 之前。

七、历史行为优化:让“↑”变聪明

setopt HIST_IGNORE_ALL_DUPS
setopt HIST_REDUCE_BLANKS
setopt INC_APPEND_HISTORY
setopt SHARE_HISTORY

这些选项共同解决了几个痛点:

  • 同一条命令不会无限刷历史
  • 多余空格不会影响匹配
  • 多个终端窗口共享历史

结果是:

历史记录更干净,搜索更精准。

八、↑ / ↓ 前缀历史搜索(核心体验)

bindkey -M emacs '^[[A' history-beginning-search-backward
bindkey -M emacs '^[[B' history-beginning-search-forward

这是整份配置的灵魂部分

行为对比

历史中有:

git commit -m "init"
git commit --amend
git checkout main
pnpm install

当你输入:

git commit

按 ↑ / ↓:

  • ✅ 只会出现 git commit ...
  • ❌ 不会混入 checkout / pnpm

这是严格的前缀匹配,非常适合 Git 这类命令族。

九、自动联想:辅助而不是干扰

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'
source /opt/homebrew/share/zsh-autosuggestions/zsh-autosuggestions.zsh
  • 灰色提示足够克制
  • 只做“提示”,不抢控制权

并且通过 -M emacs 的 bindkey 写法,确保它不会和 ↑ / ↓ 行为冲突。

十、语法高亮:为什么必须放最后?

source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

这是官方和社区反复强调的一点:

zsh-syntax-highlighting 必须是最后加载的插件

否则会出现:

  • 高亮失效
  • 与其他插件冲突

十一、最终配置(可直接使用)

下面是一份完整、可直接复制使用的 .zshrc 最终配置

说明:

  • 已包含 Powerlevel10k Instant Prompt
  • 支持 git commit 等命令的 ↑ / ↓ 严格前缀历史搜索
  • 自动联想、高亮、补全顺序全部正确
  • 适合长期作为主力终端配置使用
########################################
# Powerlevel10k instant prompt(必须靠前)
########################################
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

########################################
# 基础环境
########################################
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"

# Powerlevel10k 主题
source /opt/homebrew/share/powerlevel10k/powerlevel10k.zsh-theme
[[ -f ~/.p10k.zsh ]] && source ~/.p10k.zsh

# PATH 去重
typeset -U PATH path

########################################
# Zsh 补全系统
########################################
autoload -Uz compinit
compinit -d ~/.zcompdump

########################################
# 历史行为优化
########################################
setopt HIST_IGNORE_ALL_DUPS
setopt HIST_REDUCE_BLANKS
setopt INC_APPEND_HISTORY
setopt SHARE_HISTORY

########################################
# 自动联想(灰色提示)
########################################
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'
source /opt/homebrew/share/zsh-autosuggestions/zsh-autosuggestions.zsh

########################################
# ↑ / ↓ 前缀历史搜索(git commit 友好)
########################################
bindkey -M emacs '^[[A' history-beginning-search-backward
bindkey -M emacs '^[[B' history-beginning-search-forward

########################################
# 语法高亮(必须放最后)
########################################
source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

十二、最终效果总结

使用这份配置,你会得到:

  • 启动快、不闪屏(Powerlevel10k Instant Prompt)
  • 补全稳定(compinit 顺序正确)
  • 历史搜索精准(前缀匹配)
  • 自动联想不干扰操作

这不是“炫技型配置”,而是:

适合长期使用的工程师终端基建。

结语

终端配置的价值,不在于你用了多少插件,而在于:

  • 是否减少了无意义的操作
  • 是否让高频行为变成肌肉记忆

如果你每天要敲几十次 git commit, 那么让 ↑ 键“只做正确的事”,本身就已经非常值得了。

后续可以继续进阶的方向:

  • NVM lazy load(秒开终端)
  • Git / pnpm 专用快捷键
  • ZLE Widget 深度定制

这些,都可以在这份配置之上自然演进。

React-Scheduler 调度器如何掌控主线程?

前言

在 React 18 的并发时代,Scheduler(调度器) 是实现非阻塞渲染的幕后英雄。它不只是 React 的一个模块,更是一个通用的、高性能的 JavaScript 任务调度库。它不仅让 React 任务可以“插队”,还让“长任务”不再阻塞浏览器 UI 渲染。

一、 核心概念:什么是 Scheduler?

Scheduler 是一个独立的包,它通过与 React 协调过程(Reconciliation)的紧密配合,实现了任务的可中断、可恢复、带优先级执行。

主要职责

  1. 优先级管理:根据任务紧急程度(如用户点击 vs 数据预取)安排执行顺序。
  2. 空闲时间利用:在浏览器每一帧的空闲时间处理不紧急的任务。
  3. 防止主线程阻塞:通过“时间片(Time Slicing)”机制,避免长任务导致页面假死。

二、 Scheduler 的完整调度链路

当一个 setState 触发后,Scheduler 内部会经历以下精密流程:

1. 任务创建与通知

当状态更新时,React 不会立即执行 Render。它首先会创建一个 Update对象来记录这次变更,这个对象中包含这次更新所需的全部信息,例如更新后的状态值,Lane车道模型分配的任务优先级.

2. 优先级排序与队列维护

  • 任务优先级排序: 创建更新后,react会调用scheduleUpdateOnFiber函数通知scheduler调度器有个一个新的任务需要调度,这时scheduler会对该任务确定一个优先级,以及过期时间(优先级越高,过期时间越短,表示越紧急)

  • 队列维护: 接着scheduler会将该任务放入到循环调度中,scheduler对于任务循环调度在内部维护着两个队列,一个是立即执行队列taskQueue和延迟任务队列timeQueue,新任务会根据优先级进入到相应对列

    • timerQueue(延时任务队列) :存放还未到开始时间的任务,按开始时间排序。
    • taskQueue(立即任务队列) :存放已经就绪的任务,按过期时间排序。优先级越高,过期时间越短。

3. 时间片的开启:MessageChannel

将任务放入队列后,scheduler会调用requetHostCallback函数去请求浏览器在合适的时机去执行调度,该函数通过 MessageChannel对象中的port.postMessage 方法创建一个宏任务,浏览器在下一个宏任务时机触发 port.onmessage,并在这宏任务回调中启动 workLoop函数。

补充:Scheduler 会调用 requestHostCallback 请求浏览器调度。它没有选择 setTimeout,而是选择了 MessageChannel

为什么选 MessageChannel? setTimeout(fn, 0) 在浏览器中通常有 4ms 的最小延迟,且属于宏任务中执行时机较晚的。MessageChannelport.postMessage 产生的宏任务执行时机更早,且能更精准地在浏览器渲染帧之间切入。

4. 工作循环:workLoop

  • 在宏任务回调中,调度器会进入 workLoop。它会调用performUnitOfWork函数循环地处理Fiber节点,对比新旧节点的props、state,并从队列中取出最紧急的任务交给 React 执行。

  • workLopp中会包含一个shouldYield函数中断检查函数,用于检查当前时间片是否耗尽以及是否有更高优先级的任务执行,如果有的话则会将主线程控制权交还给浏览器,以保证高优先级任务(如用户输入、动画)能及时响应。


5. 中断与恢复:shouldYield 的魔力

workLoop 执行过程中,每一项单元工作完成后,都会调用 shouldYield() 函数进行“路况检查”。

  • 中断条件:如果当前时间片(通常为 5ms)耗尽,或者检测到有更紧急的用户交互(高优任务插队),shouldYield 返回 true
  • 状态保存:此时 React 会记录当前 workInProgress 树的位置,将控制权交还给浏览器。
  • 任务恢复:Scheduler 会在下一个时间片通过 MessageChannel 再次触发,从记录的位置继续执行,从而实现可恢复。

6. 任务插队

如果在执行一个低优先级任务时,有高优先级任务加入(如用户突然点击按钮),Scheduler会中断当前的低优任务并记录该位置,先执行高优任务。等高优任务完成后,再重新执行或继续之前的低优任务


三、 补充

  1. 执行时机对比MessageChannel 确实在宏任务中非常快,但在某些极其特殊的情况下(如没有 MessageChannel 的旧环境),它会回退到 setTimeout
  2. 饥饿现象防止:如果一个低优先级任务一直被插队怎么办?Scheduler 通过过期时间解决。一旦任务过期,它会从 taskQueue 中被提升为同步任务,强制执行。

如何监控qiankun中子应用的内存使用情况

希望监控 qiankun 中子应用的内存使用情况(包括 JS 堆内存、DOM 占用、资源泄漏等),核心思路是「主应用统一监控 + 子应用自主上报 + 浏览器原生 API 采集 + 异常告警」,结合 qiankun 的生命周期和通信机制,实现对每个子应用内存的精准、可追溯监控

核心原理
  1. 浏览器原生 API:使用 window.performance.memory(Chrome 特有,最核心)获取 JS 堆内存,document.querySelectorAll('*').length 统计 DOM 节点数;
  2. qiankun 通信机制:主应用通过「全局状态 / 自定义事件」接收子应用上报的内存数据;
  3. 生命周期绑定:在子应用的 mount/unmount/「激活 / 失活」时机采集内存数据,确保数据和子应用状态关联;
  4. 数据汇总:主应用汇总所有子应用的内存数据,形成「子应用 - 内存 - 时间」的维度表,便于分析泄漏趋势。
步骤 1:搭建监控基础框架(主应用)

主应用负责「接收子应用数据、存储监控日志、阈值告警、可视化展示」,先定义监控数据结构和核心方法。

// 主应用 src/utils/memoryMonitor.ts
interface SubAppMemoryData {
  appName: string; // 子应用名称
  timestamp: number; // 采集时间戳
  // 核心内存指标(Chrome 特有)
  usedJSHeapSize: number; // 已使用 JS 堆内存(字节)
  totalJSHeapSize: number; // 总 JS 堆内存(字节)
  jsHeapSizeLimit: number; // JS 堆内存上限(字节)
  // 辅助指标(判断泄漏)
  domCount: number; // DOM 节点数
  timerCount: number; // 定时器数量
  listenerCount: number; // 全局事件监听数
  status: 'mounted' | 'active' | 'inactive' | 'unmounted'; // 子应用状态
}

// 存储所有子应用的内存监控日志
const memoryLogs: Record<string, SubAppMemoryData[]> = {};
// 内存阈值(超出则告警,单位:MB)
const MEMORY_THRESHOLD = 200;
// 告警回调(可对接企业微信/钉钉)
let alarmCallback: (data: SubAppMemoryData) => void = () => {};

/**
 * 初始化内存监控
 * @param callback 告警回调
 */
export function initMemoryMonitor(callback: typeof alarmCallback) {
  alarmCallback = callback;
  // 初始化每个子应用的日志容器
  ['sub-app-a', 'sub-app-b', 'sub-app-c'].forEach(appName => {
    memoryLogs[appName] = [];
  });
}

/**
 * 接收子应用上报的内存数据
 */
export function receiveSubAppMemoryData(data: SubAppMemoryData) {
  // 转换为 MB 便于阅读
  const usedMB = (data.usedJSHeapSize / 1024 / 1024).toFixed(2);
  // 存储日志
  memoryLogs[data.appName].push({ ...data, usedJSHeapSize: Number(usedMB) });
  // 保留最近 100 条日志,避免主应用内存溢出
  if (memoryLogs[data.appName].length > 100) {
    memoryLogs[data.appName].shift();
  }
  // 阈值告警
  if (Number(usedMB) > MEMORY_THRESHOLD) {
    alarmCallback({ ...data, usedJSHeapSize: Number(usedMB) });
  }
}

/**
 * 获取指定子应用的内存日志
 */
export function getSubAppMemoryLogs(appName: string) {
  return memoryLogs[appName] || [];
}

步骤 2:子应用内存采集 & 上报

子应用内部实现「内存数据采集函数」,并通过 qiankun 的「全局通信」上报给主应用

// 子应用 src/utils/reportMemory.ts
/**
 * 采集当前子应用的内存数据
 * @param appName 子应用名称
 * @param status 子应用状态
 */
export function collectMemoryData(appName: string, status: string) {
  // 1. 获取 JS 堆内存(Chrome 特有,需做兼容)
  const memory = window.performance.memory || {
    usedJSHeapSize: 0,
    totalJSHeapSize: 0,
    jsHeapSizeLimit: 0
  };

  // 2. 统计 DOM 节点数(当前子应用容器内的 DOM)
  const container = document.querySelector('#app') || document.body;
  const domCount = container.querySelectorAll('*').length;

  // 3. 统计定时器数量(检测未清理的定时器)
  const timerCount = countTimers();

  // 4. 统计全局事件监听数(检测未移除的监听)
  const listenerCount = countGlobalListeners();

  // 5. 构造上报数据
  return {
    appName,
    timestamp: Date.now(),
    usedJSHeapSize: memory.usedJSHeapSize,
    totalJSHeapSize: memory.totalJSHeapSize,
    jsHeapSizeLimit: memory.jsHeapSizeLimit,
    domCount,
    timerCount,
    listenerCount,
    status
  };
}

// 辅助:统计定时器数量(简化版,生产可扩展)
function countTimers() {
  const maxTimerId = setTimeout(() => {}, 0);
  let count = 0;
  // 遍历所有定时器 ID(仅作参考,精准统计需子应用手动记录)
  for (let i = 1; i <= maxTimerId; i++) {
    if (window.clearTimeout(i)) count++;
  }
  clearTimeout(maxTimerId);
  return count;
}

// 辅助:统计全局事件监听数(如 resize/scroll 等)
function countGlobalListeners() {
  const events = ['resize', 'scroll', 'click', 'mousemove'];
  return events.reduce((total, event) => {
    return total + (window.eventListenerCount?.(window, event) || 0);
  }, 0);
}

/**
 * 上报内存数据给主应用
 * @param appName 子应用名称
 * @param status 子应用状态
 */
export function reportMemoryToMain(appName: string, status: string) {
  const data = collectMemoryData(appName, status);
  // 方式1:通过 qiankun 全局状态通信(推荐)
  if (window.__POWERED_BY_QIANKUN__) {
    window.qiankunGlobalState?.setState({
      memoryReport: data
    });
  }
  // 方式2:兼容低版本 qiankun,用自定义事件
  window.parent.postMessage(
    { type: 'MEMORY_REPORT', data },
    '*' // 生产环境替换为主应用域名
  );
}

子应用生命周期绑定上报(以 Vue 子应用为例)

// 子应用A main.ts
import { reportMemoryToMain } from './utils/reportMemory';

const appName = 'sub-app-a';
let app: any = null;
let isFirstMount = true;

// 1. 初始化时监听主应用的「激活/失活」通知
function initGlobalListener() {
  if (window.__POWERED_BY_QIANKUN__) {
    // 监听主应用的全局状态变化
    window.qiankunGlobalState?.onGlobalStateChange((state) => {
      if (state.appStatus === appName) {
        // 子应用被激活:上报激活状态的内存
        reportMemoryToMain(appName, 'active');
      } else if (state.appStatus) {
        // 子应用被失活:上报失活状态的内存
        reportMemoryToMain(appName, 'inactive');
      }
    });
  }
}

function bootstrap() {
  console.log(`${appName} bootstrap`);
  initGlobalListener();
}

function mount(props: any) {
  if (isFirstMount) {
    // 首次挂载:初始化应用
    const { createApp } = window.Vue;
    const pinia = window.pinia;
    const container = props.container.querySelector('#app') || '#app';
    app = createApp((await import('./App.vue')).default);
    app.use(pinia);
    app.mount(container);
    isFirstMount = false;
  }
  // 挂载完成:上报内存
  reportMemoryToMain(appName, 'mounted');
}

function unmount(props: any) {
  if (!props.isKeepAlive) {
    app.unmount();
    app = null;
    isFirstMount = true;
  }
  // 卸载/保活失活:上报内存
  reportMemoryToMain(appName, props.isKeepAlive ? 'inactive' : 'unmounted');
}

export { bootstrap, mount, unmount };
步骤 3:主应用接收 & 处理上报数据

主应用在初始化时绑定「内存上报」的接收逻辑,结合 qiankun 的子应用生命周期触发监控。

// 主应用 main.ts
import { initMemoryMonitor, receiveSubAppMemoryData } from './utils/memoryMonitor';
import { registerMicroApps, start, initGlobalState } from 'qiankun';

// 1. 初始化 qiankun 全局状态(用于通信)
const qiankunGlobalState = initGlobalState({
  appStatus: '', // 当前激活的子应用
  memoryReport: null // 子应用内存上报数据
});
window.qiankunGlobalState = qiankunGlobalState;

// 2. 初始化内存监控,设置告警回调
initMemoryMonitor((data) => {
  // 告警逻辑:控制台提示 + 对接企业微信/钉钉
  console.error(`【内存告警】${data.appName} 内存占用 ${data.usedJSHeapSize}MB,超出阈值 ${MEMORY_THRESHOLD}MB`);
  // 示例:调用钉钉告警接口
  // fetch('https://oapi.dingtalk.com/robot/send', {
  //   method: 'POST',
  //   body: JSON.stringify({ msgtype: 'text', text: { content: `【内存告警】${data.appName} 内存占用 ${data.usedJSHeapSize}MB` } })
  // });
});

// 3. 监听子应用的内存上报
qiankunGlobalState.onGlobalStateChange((state) => {
  if (state.memoryReport) {
    receiveSubAppMemoryData(state.memoryReport);
    // 清空上报数据,避免重复处理
    qiankunGlobalState.setState({ memoryReport: null });
  }
});

// 4. 监听自定义事件(兼容低版本子应用)
window.addEventListener('message', (e) => {
  if (e.data.type === 'MEMORY_REPORT') {
    receiveSubAppMemoryData(e.data.data);
  }
});

// 5. 注册子应用 + 切换时通知状态
const apps = [/* 子应用配置 */];
registerMicroApps(apps);
start({
  singular: false,
  sandbox: { strictStyleIsolation: true }
});

// 6. 切换子应用时,更新全局状态(触发子应用上报)
function switchApp(appName: string) {
  qiankunGlobalState.setState({ appStatus: appName });
  // 原有切换逻辑...
}

步骤 4:可视化监控面板(主应用)

主应用可开发一个简易的监控面板,展示各子应用的内存趋势(用 ECharts 实现),便于运维 / 开发实时查看。

<!-- 主应用 src/components/MemoryMonitor.vue -->
<template>
  <div class="memory-monitor">
    <h3>子应用内存监控</h3>
    <select v-model="selectedApp" @change="renderChart">
      <option value="sub-app-a">子应用A</option>
      <option value="sub-app-b">子应用B</option>
    </select>
    <div id="memory-chart" style="width: 800px; height: 400px;"></div>
    <div class="data-table">
      <table>
        <thead>
          <tr>
            <th>时间</th>
            <th>内存占用(MB)</th>
            <th>DOM节点数</th>
            <th>状态</th>
          </tr>
        </thead>
        <tbody>
          <tr v-for="item in logs" :key="item.timestamp">
            <td>{{ new Date(item.timestamp).toLocaleString() }}</td>
            <td :style="{ color: item.usedJSHeapSize > 200 ? 'red' : 'black' }">
              {{ item.usedJSHeapSize }}
            </td>
            <td>{{ item.domCount }}</td>
            <td>{{ item.status }}</td>
          </tr>
        </tbody>
      </table>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import * as echarts from 'echarts';
import { getSubAppMemoryLogs } from '../utils/memoryMonitor';

const selectedApp = ref('sub-app-a');
const logs = ref([]);
let chart: echarts.ECharts | null = null;

// 渲染内存趋势图
const renderChart = () => {
  logs.value = getSubAppMemoryLogs(selectedApp.value);
  if (!chart) {
    chart = echarts.init(document.getElementById('memory-chart'));
  }
  chart.setOption({
    title: { text: `${selectedApp.value} 内存趋势` },
    xAxis: {
      type: 'category',
      data: logs.value.map(item => new Date(item.timestamp).toLocaleTimeString())
    },
    yAxis: { type: 'value', name: '内存(MB)' },
    series: [{
      name: 'JS堆内存',
      type: 'line',
      data: logs.value.map(item => item.usedJSHeapSize),
      markLine: { // 阈值线
        data: [{ type: 'line', yAxis: 200, name: '阈值' }]
      }
    }]
  });
};

onMounted(() => {
  renderChart();
  // 每30秒刷新一次
  setInterval(renderChart, 30 * 1000);
});
</script>

步骤 5:线下深度分析(定位内存泄漏)

线上监控发现异常后,需用 Chrome DevTools Memory 面板做内存泄漏分析,选择快照观察半个小时的内存变化,定位是否是误报内存泄漏,如果停留在页面一段时间内,内存依然持续增长,基本可以断定发生内存泄漏,然后快照分析对象引用链,分析内存泄漏的可能性

注意事项:

  • 子应用不要高频上报(如每秒上报),建议「挂载 / 卸载 / 激活 / 失活」时上报 + 每 5 分钟定时上报,避免主应用被大量上报数据阻塞;
  • 主应用保留的日志数量不宜过多(如最多 100 条),避免主应用自身内存溢出。
  • 子应用的定时器 / 事件监听统计是「简化版」,生产环境建议子应用手动维护「定时器列表 / 事件列表」(如 const timers = []; timers.push(setInterval(...))),卸载时统一清理并上报准确数量;
  • 沙箱隔离场景下,子应用的 window 是代理对象,统计 eventListenerCount 时需指向真实 windowwindow.parent

【配置化 CRUD 完结篇】新增编辑页 : 统一风格

一:前言

在前三篇文章中,已完成配置化 CRUD 体系的核心铺垫 —— 通过动态表单组件避免了重复编写表单模板,用搜索重置组件实现了列表筛选的统一封装,再借助 useTable Hooks 搞定了列表查询与分页的通用逻辑,三者联动让列表页实现了 “配置即开发” 的高效模式。不过,在完整的 CRUD 流程中,新增与编辑功能也是不可或缺的一部分,接下来,我们将结合前序动态表单组件,实现统一的新增编辑页,完成配置化CRUD开发的完美闭环。

文章指路(一起食用,味道更加):

1.动态表单深度实践: juejin.cn/post/757946… ;

2.搜索重置组件:juejin.cn/post/760056… ;

3.useTable Hooks: juejin.cn/post/760068… ;

二:新增编辑页实现

统一的新增编辑页,是为了保持新增与编辑页面的统一风格,同时将重复的按钮操作进行统一的封装及事件暴露处理。

其核心设计思路可概括为:封装统一的顶部展示区域、底部操作栏区域(支持显示 / 隐藏控制),暴露默认插槽(主体内容)与具名插槽(顶部展示区域、底部操作区域),让重复逻辑内聚、个性化需求通过插槽灵活实现,既保证一致性,又不丧失扩展性。

三:代码实现

3.1 顶部区域:展示相关路由名称

const route = useRoute()
const router = useRouter()
//找到页面指定的活跃路由
const findRouteByActiveMenuId = (
  routes: any,
  targetActiveMenuId: any
): any => {
  for (const route of routes) {
    if (route.meta?.menu_id === targetActiveMenuId) {
      return route
    }
    // 递归检查子路由
    if (route.children) {
      const found = findRouteByActiveMenuId(
        route.children,
        targetActiveMenuId
      )
      if (found) return found
    }
  }
  return {}
};

const loginStore = useLogin()
const activeMenuId = route?.meta?.activeMenuId || ''
//找到页面指定的路由
const activeMenuObj = findRouteByActiveMenuId(
  loginStore.Matchroute,
  activeMenuId
)
const match = [activeMenuObj, route];

<div class="top-title">
      <div class="bread-item">
        <el-breadcrumb separator="/">
          <el-breadcrumb-item
            v-for="(item, index) in match"
            :key="index"
            >{{ $t(item?.meta?.label) }}</el-breadcrumb-item
          >
        </el-breadcrumb>
      </div>
</div>

3.2 主体区域:暴露默认插槽

  <!-- 主体内容:默认插槽 -->
  <slot></slot>

3.3 底部操作栏区域 :默认操作栏 + 暴露默认插槽

type SearchPrams = {
  showConfirm?: boolean
  showCancel?: boolean
  confirmText: string
  cancelText?: string
}
const props = withDefaults(defineProps<SearchPrams>(), {
  showConfirm: true,
  showCancel: true,
  confirmText: 'Confirm',
  cancelText: 'Cancel',
})
const slots = useSlots()
const emits = defineEmits(['submit'])

<template v-if="slots.bottom">
       <!-- 外部自定义底部内容-->
       <slot name="bottom"> </slot>
</template>
<template v-else>
       <div class="btn-content">
            <ElButton
              v-if="showConfirm"
              :style="{ width: '100px' }"
              @click="() => router.back()"
              >{{ $t(cancelText) }}</ElButton
            >
            <ElButton
              v-if="showCancel"
              type="primary"
              :style="{ width: '100px' }"
              @click="() => emits('submit')"
              >{{ $t(confirmText) }}</ElButton
            >
       </div>
</template>

3.4 完整代码

<script lang="ts" setup>
import { ElButton } from 'element-plus'
import { useRoute, useRouter } from 'vue-router'
import useLogin from '@/stores/login'
import {useSlots } from 'vue'
type SearchPrams = {
  showConfirm?: boolean
  showCancel?: boolean
  confirmText: string
  cancelText?: string
}
const props = withDefaults(defineProps<SearchPrams>(), {
  showConfirm: true,
  showCancel: true,
  confirmText: 'Confirm',
  cancelText: 'Cancel',
})
const route = useRoute()
const router = useRouter()
const slots = useSlots()
const emits = defineEmits(['submit', 'cancel'])
const findRouteByActiveMenuId = (
  routes: any,
  targetActiveMenuId: any
): any => {
  for (const route of routes) {
    if (route.meta?.menu_id === targetActiveMenuId) {
      return route
    }
    // 递归检查子路由
    if (route.children) {
      const found = findRouteByActiveMenuId(
        route.children,
        targetActiveMenuId
      )
      if (found) return found
    }
  }
  return {}
}
const loginStore = useLogin()
const activeMenuId = route?.meta?.activeMenuId || ''
//找到页面指定的路由
const activeMenuObj = findRouteByActiveMenuId(
  loginStore.Matchroute,
  activeMenuId
)
const match = [activeMenuObj, route]
</script>
<template>
  <div class="addPage">
    <!-- 顶部区域展示 -->
    <div class="top-title">
      <div class="bread-item">
        <el-breadcrumb separator="/">
          <el-breadcrumb-item
            v-for="(item, index) in match"
            :key="index"
            >{{ $t(item?.meta?.label) }}</el-breadcrumb-item
          >
        </el-breadcrumb>
      </div>
    </div>
    <!-- // 内容区 -->
    <div class="main-content pt-3">
      <!-- 主体内容:默认插槽 -->
      <slot></slot>
      <!-- 底部操作栏:具名插槽 -->
      <div class="bottom">
        <el-divider />
         <template v-if="slots.bottom">
          <!-- 外部自定义底部内容-->
          <slot name="bottom"> </slot>
        </template>
        <template v-else>
          <div class="btn-content">
            <ElButton
              v-if="showConfirm"
              :style="{ width: '100px' }"
              @click="() => router.back()"
              >{{ $t(cancelText) }}</ElButton
            >
            <ElButton
              v-if="showCancel"
              type="primary"
              :style="{ width: '100px' }"
              @click="() => emits('submit')"
              >{{ $t(confirmText) }}</ElButton
            >
        </div>
        </template>
      </div>
    </div>
  </div>
</template>
<style scoped lang="less">
.addPage {
  height: 100vh;
  width: 100vw;
  position: relative;
  /* // 新增编辑页覆盖所有展示 */
  background-color: #f5f5f5;
  :deep(.el-breadcrumb__inner) {
    color: white !important;
  }
  :deep(.el-divider--horizontal) {
    margin-bottom: 0 !important;
  }
}
.bread-item {
  margin-top: 5px;
}
.top-title {
  padding: 10px;
  font-size: 18px;
  background-color: black;
  display: flex;
  align-items: center;
  gap: 10px;
}
.main-content {
  width: 56%;
  margin: 0 auto;
  background-color: white;
  height: calc(100% - 50px);
  position: relative;
  display: flex;
  flex-direction: column;
  overflow: hidden;
  
  > :first-child:not(.bottom) {
    flex: 1;
    overflow-y: auto;
    padding: 12px 12px 80px;
  }
  
  .bottom {
    position: sticky;
    bottom: 0;
    width: 100%;
    height: 80px;
    text-align: center;
    line-height: 50px;
    background: white;
    z-index: 1;
  }
  .btn-content {
    margin: 0 auto;
  }
}
.addPage ::-webkit-scrollbar {
  display: none !important;
}
</style>

四:实战使用

4.1 页面引入:

const codeFormRef: any = ref(null)
const schema = [
  {
    prop: 'age',
    label: '年龄',
    component: 'Input',
    componentProps: {
      type: 'number',
      }
    },
    rules: [
      {
        required: true,
        message: '请输入年龄',
        trigger: 'blur'
      }
    ]
  },
  {
    prop: 'csa',
    label: '阶段',
    component: 'Select',
    componentProps: {
      disabled: true,
      options: [
        {
          label: '儿童',
          value: 1
        },
        {
          label: '青年',
          value: 2
        },
        {
          label: '老年',
          value: 3
        }
      ]
    }
  },
]

// 确认函数
const submit = async () => {
  const isVaild = await codeFormRef.value.validate()
  if (isVaild) {
    const data = await codeFormRef.value.getData()
    console.log(data, '数据::')
    router.back()
  } else {
    console.log('表单验证失败')
  }
}
// 引入CommonAddPage组件
<template>
  <CommonAddPage @submit="submit">
    <CodeForm
      ref="codeFormRef"
      :schema="schema"
      :isCenter="true"
      :labelWidth="'100px'"
    >
    </CodeForm>
  </CommonAddPage>
</template>

4.2 运行截图:

进入页面:

image.png

触发表单校验:

image.png

以上就是新增编辑页的封装过程以及实战案例~

五:写在最后: 专栏总结 —— 配置化CRUD开发

经过四篇文章的逐步拆解与实战,已经完整搭建了一套 “配置化驱动、高复用” 的 CRUD 开发体系。从动态表单的基础铺垫,到搜索重置组件useTable Hooks 的核心封装,再到新增编辑页的闭环实现,每一步都围绕 “减少重复编码、统一开发规范、提升开发效率” 的核心目标,最终让后台管理系统的CRUD 转变为 “配置即开发”。

当然配置化的前提是:“高复用、少定制”!!

当前的配置化CRUD开发体系已覆盖 “列表 + 搜索 + 分页 + 新增 + 编辑” 核心流程,希望这套体系能为你提供实际的帮助,也欢迎根据自身业务场景进行调整与扩展。

专栏到此结束,感谢你的阅读!🚀

深度解析 React Router v6:构建企业级单页应用(SPA)的全栈式指南

在 Web 开发的演进史中,从早期的多页应用(MPA)到现代的单页应用(SPA),我们见证了前端工程师角色的巨大转变。曾几何时,前端开发被戏称为“切图仔”,路由和页面跳转的控制权完全掌握在后端手中。每一次页面的切换,都意味着浏览器需要向服务器发起一次全新的 HTTP 请求,重新下载 HTML、CSS 和 JavaScript。这种模式不仅由于网络延迟导致页面频繁出现“白屏”闪烁,更加重了服务器的渲染压力。

随着 React 等现代框架的崛起,前端路由应运而生。它将页面的跳转逻辑从后端剥离,移交至客户端处理。当路由发生改变时,浏览器不再刷新页面,而是通过 JavaScript 动态卸载旧组件、挂载新组件。这种“无刷新”的体验,让 Web 应用拥有了媲美原生桌面软件的流畅度。

本文将基于一套成熟的 React Router v6 实践方案,深入剖析如何构建一个高性能、安全且交互友好的路由系统。

第一章:路由模式的抉择与底层原理

在初始化路由系统时,我们面临的第一个架构决策就是:选择哪种路由模式?

1.1 HashRouter:传统的妥协

在早期的 SPA 开发中,HashRouter 是主流选择。它的 URL 特征非常明显,总是带着一个 # 号(例如 http://domain.com/#/user/123)。

  • 原理:它利用了浏览器 URL 中的 Hash 属性。Hash值的变化不会触发浏览器向服务器发送请求,但会触发 hashchange 事件,前端路由通过监听这个事件来切换组件。
  • 优势:即插即用。由于 # 后面的内容不被发送到服务器,因此无论如何刷新页面,服务器只接收到根路径请求,不会报 404 错误。
  • 适用场景:适合部署在 GitHub Pages 等无法配置服务器重定向规则的静态托管服务上,或者完全离线的本地文件系统应用(如 Electron 包裹的本地网页)。

1.2 BrowserRouter:现代的标准

我们在项目中采用了 BrowserRouter,并将其重命名为 Router 以保持代码的可读性。这是基于 HTML5 History API 构建的模式,它生成的 URL 干净、标准(例如 http://domain.com/user/123)。

  • 原理——一场精心的“骗局”

    所谓的 History 路由,本质上是前端与浏览器合谋的一场“欺骗”。

    1. 跳转时:当你点击链接,React Router 阻止了 <a> 标签的默认跳转行为,调用 history.pushState() 修改地址栏 URL,同时渲染新组件。浏览器认为 URL 变了,但实际上并没有发起网络请求。
    2. 后退时:当你点击浏览器后退按钮,Router 监听 popstate 事件,根据历史记录栈(Stack)中的状态,手动把旧组件渲染回来。
  • 部署的挑战

    这种模式的代价在于“刷新”。当你在 /user/123 页面按下 F5 刷新时,这场“骗局”就穿帮了。浏览器会真的拿着这个 URL 去请求服务器。如果服务器(Nginx/Apache)上只有 index.html 而没有 user/123 这个目录,服务器就会一脸茫然地返回 404 Not Found

    • 解决方案:这需要后端配合。在 Nginx 配置中,必须将所有找不到的路径重定向回 index.html,让前端接管路由渲染。

第二章:性能优化的核心——懒加载策略

随着应用规模的扩大,构建产物(Bundle)的体积会呈指数级增长。如果采用传统的 import 方式,所有页面的代码(首页、个人中心、支付页、后台管理)都会被打包进同一个 bundle.js 文件中。用户仅仅是为了看一眼首页,却被迫下载了整个应用的代码,导致首屏加载时间过长,用户体验极差。

2.1 代码分割(Code Splitting)

为了解决这个问题,我们在路由配置中全面引入了 React 的 lazy 函数。

// 静态引入(不推荐用于路由组件)
// import Product from './pages/Product';

// 动态引入(推荐)
const Product = lazy(() => import('../pages/Product'));
const UserProfile = lazy(() => import('../pages/UserProfile'));

这种写法的魔力在于,Webpack 等打包工具在识别到 import() 语法时,会自动将这部分代码分割成独立的 chunk 文件。只有当用户真正点击了“产品”或“用户资料”的链接时,浏览器才会去通过网络请求下载对应的 JS 文件。这大大减少了首屏的资源消耗。

2.2 优雅的加载过渡(Suspense & Fallback)

由于网络请求是异步的,从点击链接到组件代码下载完成之间,存在一个短暂的时间差。为了避免页面在这个空档期“开天窗”(一片空白),React 强制要求配合 Suspense 组件使用。

我们在路由配置的外层包裹了 Suspense,并提供了一个 fallback 属性:

<Suspense fallback={<LoadingFallback />}>
    <Routes>...</Routes>
</Suspense>

这里引入的 LoadingFallback 组件并非简单的文字提示,而是一个精心设计的 CSS 动画组件。

2.3 CSS 关键帧动画的艺术

为了缓解用户的等待焦虑,我们在 index.module.css 中实现一个双环旋转的加载动画。

  • 布局:使用 Flexbox 将加载器居中定位,背景设置为半透明白,遮罩住主要内容。

  • 动画原理:利用 CSS3 的 @keyframes 定义了 spin 动画,从 0 度旋转至 360 度。

    • 外层圆环:顺时针旋转,颜色为清新的蓝色(#3498db)。
    • 内层圆环:通过 animation-direction: reverse 属性实现逆时针旋转,颜色为活力的红色(#e74c3c),并调整了大小和位置。
  • 呼吸灯效果:下方的 "Loading..." 文字应用了 pulse 动画,通过透明度(opacity)在 0.6 到 1 之间循环变化,产生呼吸般的节奏感。

这种视觉上的微交互(Micro-interaction)能显著降低用户对加载时间的感知。

第三章:路由配置的立体化网络

路由不仅仅是 URL 到组件的映射,更是一个分层的立体网络。在我们的配置中,涵盖了普通路由、动态路由、嵌套路由和重定向路由等多种形态。

3.1 动态路由与参数捕获

在用户系统中,每个用户的个人主页结构相同,但数据不同。我们通过在路径中使用冒号(:)来定义参数,例如 /user/:id

在组件内部,我们不再需要解析复杂的 URL 字符串,而是通过 React Router 提供的 useParams Hook 直接获取参数对象:

const { id } = useParams();

这样,无论是访问 /user/123 还是 /user/admin,组件都能精准捕获 ID 并请求相应的数据。

3.2 嵌套路由(Nested Routes)

对于像“产品中心”这样复杂的板块,通常包含“列表”、“详情”和“新增”等子功能。我们采用了嵌套路由的设计:

<Route path='/products' element={<Product />}>
    <Route path=':productId' element={<ProductDetail />}></Route>
    <Route path='new' element={<NewProduct />}></Route>
</Route>

这种结构清晰地反映了 UI 的层级关系。父组件 Product 充当布局容器,子路由通过父组件中的 <Outlet />(虽未直接展示但在 React Router v6 中隐含)进行渲染。这使得代码结构与页面结构高度统一。

3.3 历史记录管理与重定向

在处理旧链接迁移时,我们使用了 <Navigate /> 组件。

例如,将 /old-path 重定向到 /new-path

<Route path='/old-path' element={<Navigate replace to='/new-path' />}></Route>

这里的 replace 属性至关重要。如果不加它,跳转是 push 行为,用户重定向后点击“后退”按钮,又会回到 /old-path,再次触发重定向,从而陷入死循环。加上 replace 后,新路径会替换掉历史栈中的当前记录,保证了导航历史的干净。

第四章:安全防线——高阶路由守卫

在企业级应用中,安全性是不可忽视的一环。对于“支付”、“订单管理”等敏感页面,必须确保用户已登录。我们没有在每个组件里重复写判断逻辑,而是封装了一个 ProtectRoute(路由守卫) 组件。

4.1 鉴权逻辑的封装

ProtectRoute 作为一个高阶组件(HOC),包裹在需要保护的子组件外层。

  1. 状态检查:它首先从持久化存储(如 localStorage)中读取登录标识(例如 isLogin)。

  2. 条件渲染

    • 未登录:直接返回 <Navigate to='/login' />。这会在渲染阶段立即拦截请求,并将用户“踢”回登录页。
    • 已登录:原样渲染 children(即被包裹的业务组件)。

4.2 路由层面的应用

在路由表中,我们这样使用守卫:

<Route path='/pay' element={
    <ProtectRoute>
        <Pay />
    </ProtectRoute>
}></Route>

这种声明式的写法让权限控制逻辑一目了然,且易于维护。

第五章:交互细节——导航反馈与 404 处理

一个优秀的应用不仅要功能强大,还要体贴入微。

5.1 智能导航高亮

在导航菜单中,用户需要知道自己当前处于哪个页面。我们编写了一个辅助函数 isActive,它利用 useLocation Hook 获取当前路径。

const isActive = (to) => {
    const location = useLocation();
    return location.pathname === to ? 'active' : '';
}

通过这个逻辑,当用户访问 /about 时,对应的导航链接会自动获得 active 类名,我们可以通过 CSS 为其添加高亮样式。这种即时的视觉反馈大大增强了用户的方位感。

5.2 友好的 404 页面

当用户迷路(访问了不存在的 URL)时,展示一个冷冰冰的错误页是不够的。我们配置了通配符路由 path='*' 来捕获所有未定义的路径,并渲染 NotFound 组件。

NotFound 组件中,我们不仅告知用户页面丢失,还实现了一个自动跳转机制:

useEffect(() => {
    setTimeout(() => {
        navigate('/');
    }, 6000)
}, [])

利用 useEffectsetTimeout,页面会在 6 秒后自动通过 useNavigate 导航回首页。这种设计既保留了错误提示,又无需用户手动操作,体现了产品的温度。

结语

通过 React Router v6,我们不仅仅是将几个页面简单地链接在一起。

  • 利用 History APIBrowserRouter,我们构建了符合现代 Web 标准的 URL 体系。
  • 通过 Lazy LoadingSuspense,我们兼顾了应用体积与首屏性能。
  • 借助 路由守卫Hooks,我们实现了严密的安全控制和灵活的数据交互。

这套路由架构方案,从底层的原理到上层的交互,构成了一个健壮、高效且用户体验优秀的单页应用骨架。对于任何致力于构建现代化 Web 应用的开发者来说,深入理解并掌握这些模式,是通往高级前端工程师的必经之路。

vite+vue3+antd4项目兼容低版本chrome86+ && chrome68+

兼容性问题解决方案汇总

一、兼容到chrome86+

1.antd4 向下兼容方案

1、文档流中的样式和位置问题,主入口app.vue添加如下内容, 解决方案:

App组件容易漏,会导致message提示无法显示,需要注意~

import { ConfigProvider, App } from 'ant-design-vue';
import { StyleProvider, legacyLogicalPropertiesTransformer } from 'ant-design-vue/es/_util/cssinjs';
        <StyleProvider
          hash-priority="high"
          :prefix="configProviderPrefixCls"
          :transformers="[legacyLogicalPropertiesTransformer]"
        >
          <a-style-provider
            hash-priority="high"
            :prefix="configProviderPrefixCls"
            :transformers="[legacyLogicalPropertiesTransformer]"
          >
            <App>              
            <RouterView />
            </App>
          </a-style-provider>
        </StyleProvider>

2、  全局弹出、全局提示等脱离文档流的位置问题。 解决方案:

import { App } from 'ant-design-vue';
使用 const { modal } = App.useApp(); 替换Modal.confirm等,message alert 同理
 

 

3、  前缀是antd,没有被prefix前缀处理到的组件位置问题(如画布节点) 解决方案:采用问题一的解决方案,把画布自定义节点包裹一次

4、  使用creatApp或者creatVnode创建的模块,脱离了vue的上下文文档流

解决方案:采用问题一的解决方案,把节点包裹一次

样式及js兼容修改

1.建议初始化配置时在vite.config中加上如下内容:

build:{
    ... 原来的内容,
    // js最低兼容的浏览器版本
    target: ['chrome86', 'edge88', 'firefox78', 'safari14'],
    // 禁用 CSS 代码压缩,防止 top/right/bottom/left 被转换成 inset
     cssMinify: false
 }
 

本地启动报错

1.集成unocss出现报错问题 image.png

 

注意⚠️:   如果使用了unocss或taiwindcss覆盖antd原有的样式会失效,兼容后antd的样式等级会提高。我采取的方法比较笨但可靠,在覆盖的css类名后面添加‘!’,编译后会给unocss或taiwindcss的css后面添加!important。这样能解决!

position导致的样式失效

360极速版position导致的样式失效 如果同时有top:0;left:0,bottom:0;right:0;vite会打包成一个insert:0,但是360极速版不支持该属性加上width:100%和height:100%

二、兼容到chrome68+

在兼容chrome86的基础上添加如下配置

全程基于项目根目录执行操作,核心依赖为 Vite5 官方兼容插件@vitejs/plugin-legacy+ API 补全库core-js@3,所有配置可直接复制使用,按步骤执行即可完成兼容。

前提:Chrome68 支持 ES2017,缺失 ES2018+ 新语法(?.、?? 等)和部分全局 API,兼容核心是语法转译 + 自动 polyfill 注入 + 适配构建目标

步骤 1:安装核心兼容依赖

# npm 安装
npm install @vitejs/plugin-legacy core-js @babel/core -D

步骤 2:配置 browserslist(统一所有工具的兼容目标)

在项目根目录的package.json新增browserslist字段,统一 Vite、Babel、PostCSS 的浏览器兼容规则,仅指定Chrome 68即可,修改后如下:

{
  "name": "your-vue-project", // 你的项目名
  "version": "0.0.0",
  "browserslist": ["Chrome 68"], // 新增这行,统一兼容目标
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  // 保留项目原有dependencies、devDependencies等配置...
}

步骤 3:修改 Vite 核心配置(vite.config.js/ts)

这是兼容的核心步骤,修改项目根目录的vite.config.js(ts 项目为vite.config.ts,配置完全一致),完成插件注册 + 构建目标降级 + CSS 适配,直接替换原有配置即可:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import legacy from '@vitejs/plugin-legacy' // 1. 引入legacy兼容插件

// Vite5 核心配置
export default defineConfig({
  plugins: [
    vue(), // Vue3 插件
    // 2. 配置legacy插件,自动转译语法+注入polyfill
    legacy({
      targets: 'Chrome 68', // 明确指定兼容Chrome68(也可读取browserslist)
      polyfills: true, // 开启自动polyfill注入(基于core-js@3)
      renderLegacyChunks: true, // 生成旧浏览器兼容产物
      modernPolyfills: true // 现代浏览器兜底polyfill
    })
  ],
  build: {
    target: 'es2017', // 3. 构建目标降级为Chrome68支持的ES2017(Vite5默认es2020)
    cssTarget: 'chrome68', // 4. CSS适配Chrome68,避免生成不兼容CSS语法
    minify: 'terser', // 可选:用terser压缩,避免新压缩特性导致兼容问题
    terserOptions: {
      compress: { drop_console: false } // 可选:保留console,方便调试
    }
  }
})

步骤 4:Vue3.3.0 兼容兜底(无额外配置,仅 2 个避坑点)

Vue3 本身已放弃 IE 但完全兼容 Chrome68,无需修改任何 Vue 相关配置,只需注意 2 个细节即可:

  1. 代码中避免使用 Vue3 的实验性特性(如defineModel高级用法、props解构的新特性),若使用,legacy 插件会自动转译;
  2. Vue3 模板编译产物为 ES5 级别,Chrome68 可直接解析,无需修改@vitejs/plugin-vue的编译配置。

步骤 5:执行生产构建(兼容逻辑仅对构建生效)

Vite 的 legacy 兼容处理仅在生产构建时生效(开发环境 Chrome68 已支持 ES 模块,可直接运行npm run dev开发,无需额外处理,本地还是无法访问的!!!!!),执行构建命令生成兼容包:

# 生成兼容Chrome68的生产包,输出到项目根目录的dist文件夹
npm run build

构建完成后,dist目录会自动生成 2 类产物,且index.html内置浏览器嗅探逻辑:Chrome68 会自动加载兼容产物 + polyfill,高版本浏览器加载现代产物,无需手动判断。

注意: 本地无法访问,看不到页面呈现,只有部署后才能打开!!!!!!!

步骤 6:Chrome68 兼容性测试(2 种便捷方法,无需安装旧浏览器)

方法 1:Chrome 开发者工具模拟(推荐,最快)

  1. 打开新版 Chrome 浏览器,运行npm run preview启动预览服务,打开项目预览地址;
  2. F12打开开发者工具 → 点击右上角「⋮」→ 更多工具 → 设备模拟;
  3. 左上角设备下拉框选择「自定义」→ 输入Chrome 68,刷新页面即可模拟运行。

方法 2:本地启静态服务测试

  1. 全局安装静态服务工具servenpm install serve -g
  2. 项目根目录执行:serve dist,会生成本地访问地址(如http://localhost:3000);
  3. 在模拟的 Chrome68 中访问该地址,验证页面渲染、按钮点击、接口请求等交互是否正常。

步骤 7:常见兼容问题解决(按需处理)

若测试时出现报错 / 样式错乱,按以下场景针对性解决,均为 Chrome68 兼容的高频问题:

问题 1:第三方依赖未被转译(如 Element Plus/axios 用了 ES2018 + 语法)

Vite5 默认不转译node_modules,需在vite.config.js强制指定转译的依赖,修改后如下:

export default defineConfig({
  // 保留原有配置...
  optimizeDeps: {
    include: ['element-plus', 'axios'] // 按需添加需要转译的第三方依赖
  },
  build: {
    // 保留原有配置...
    commonjsOptions: {
      include: [/element-plus/, /axios/, /node_modules/] // 强制转为CommonJS格式
    }
  }
})

问题 2:个别全局 API 未被 polyfill(如 URLSearchParams/fetch)

Chrome68 已支持大部分 API,若遇到缺失,在 src/main.js/ts 中手动引入即可:

// src/main.js(Vue入口文件)
import 'core-js/es/url-search-params' // 手动注入URLSearchParams polyfill
import 'core-js/es/fetch' // 按需注入fetch polyfill
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

问题 3:CSS 样式错乱(如高级 CSS 选择器 / 特性)

Chrome68 支持基础 CSS 变量 / Flex 布局,样式问题多为第三方 CSS 用了高级特性,安装postcss-preset-env兜底:

  1. 安装依赖:pnpm add postcss-preset-env -D
  2. 项目根目录新建postcss.config.js,添加配置:
module.exports = {
  plugins: [
    require('postcss-preset-env')({
      browsers: 'Chrome 68', // 适配Chrome68
      features: { 'custom-properties': { preserve: true } } // 保留CSS变量
    })
  ]
}

核心步骤总结

  1. 安装@vitejs/plugin-legacy@5.x + core-js@3 + @babel/core三大核心依赖;
  2. package.json中配置browserslist: ["Chrome 68"]统一兼容目标;
  3. Vite 配置中注册 legacy 插件,降级build.target为 es2017、cssTarget为 chrome68;
  4. 执行npm run build生成兼容包,通过 Chrome 开发者工具模拟 Chrome68 测试;
  5. 按需解决第三方依赖转译、手动 polyfill、CSS 适配等问题。

 

公司低代码框架-列表个性化开发最佳实践

一、引言

当前低代码组件的功能框架已趋于稳定,而业务侧的需求设计却持续迭代、不断涌现。要落地各类个性化需求,正需要我们秉持‘人有多大胆,地有多大产’的探索精神,勇于构思、大胆尝试。比如低代码列表中,针对字段内容过多的问题,就需要自己开发部分展示的功能。

二、使用场景

1、列表只展示前三行,剩余的放在查看按钮内,弹框展示

image.png

实现思路:借助列表字段的自定义内容-复杂模式,实现设计稿里的展示效果,在页面加载事件里监听点击事件,实现弹窗效果

image.pngimage.png


let pileList = rowData.row.AccountList || [];
let resStrShow = '';
let resStrHide = '';
    for (let id = 0; id < pileList.length; id++) {
        let itemShow = "";
       ...
        if (rowData.row.AutoChargeType == '2') {//企业总账户
            if (pileList.length > 1) {
                itemShow += `${pileList[id].BusUnitAttrCompanyName}:`;
            }
            let BusUnitOrGroupBalance = Funcs.FormatDecimal(pileList[id]?.BusUnitOrGroupBalance, 2, "", ".").replace(/,/g, '');
            itemShow += `企业现金余额${BusUnitOrGroupBalance}元`;

        }
       ...
        }
        if (id < 3) {
            if (resStrShow) {
                resStrShow += '</br>';
            }
            resStrShow += itemShow;
        }
        if (resStrHide) {
            resStrHide += '</br>';
        }
        resStrHide += itemShow;

    }
if (pileList.length > 3) {

    let tipQuestion = `<div style="opacity: 1;    margin-top: 2px;" instancecode=""tabindex="1">`
        + `<span>`
        + `<span class="qiestionIcon" style="position: relative;display: flex;justify-content:  flex-start;">`
        + `<i class="material-icons" style="display:none" aria-hidden="true" role="presentation">help_outline</i>`
        + `<div  class="viewAll"
  style="
  padding:0px 7px;
  border-radius:10px;
  border:1px solid #D9D9D9;
  font-family:AlibabaPuHuiTi;
  font-size:12px;
  cursor: pointer;
  color:#3656FF;"
  >查看全部(${pileList.length})</div>`
        + `<div style="visibility:hidden;position: absolute; width: 560px; height: auto; left: 0px; top: -8px; box-sizing: content-box; padding-top: 8px;margin-left:20px;">`
        + `<span style="" class="resStrHide">${resStrHide}</span>`

        + `</div>`
        + `</span>`
        + `</span>`
        + `</div>`;

    return `<div   style="position: relative; display: inline-flex;flex-direction: column;">
          <div>${resStrShow}</div>          
          ${tipQuestion}
</div>`;

} else {
    return resStrShow;
}

js代码,点击实现弹框效果:


    var content = document.querySelector(`.UIControl_VehicleSettingList_Ecms_New`);
    content.addEventListener('click', function (event) {
        if (event.target.className == "viewAll") {
            const nextSiblingElement = event.target.nextElementSibling;
            if (nextSiblingElement) {
                const targetSpan = nextSiblingElement.querySelector('span.resStrHide');
                if (targetSpan) {
                    LocalVars.Variable_viewAll = targetSpan.innerHTML//把全部内容赋值给弹窗变量
                    Widget.fasr_dialog_viewALLNew.showDialog()//展示弹框
                
                }
            }
        }   
    });

2、列表只展示前三个,剩余的放在悬浮气泡里展示

image.png
实现思路:借助列表字段的自定义内容-复杂模式,实现设计稿里的展示效果,在页面加载事件里监听mousemove事件,实现气泡效果

image.pngimage.png

let PileRangeDesc = rowData.row.PileRangeDesc || '';
let pileList = PileRangeDesc.split(',') || [];

let resStrShow = '';
let resStrHide = '';

for (let id = 0; id < pileList.length; id++) {
    if (id < 3) {
        if (resStrShow) {
            resStrShow += '、';
        }
        resStrShow += pileList[id];
    } else {
        if (resStrHide) {
            resStrHide += '、';
        }
        resStrHide += pileList[id]
    }
}

if (pileList.length > 3) {

    let tipQuestion = `<div style="opacity: 1;margin-left:7px" instancecode=""tabindex="1">`
        + `<span>`
        + `<span class="qiestionIcon" style="position: relative;display: flex;justify-content: center;">`
        + `<i class="material-icons" style="display:none" aria-hidden="true" role="presentation">help_outline</i>`
        + `<div 
  style="
  padding:0px 7px;
  border-radius:10px;
  border:1px solid #D9D9D9;
  font-family:AlibabaPuHuiTi;
  font-size:12px;
  color:#3656FF;"
  >+${pileList.length - 3}</div>`
        + `<div style="visibility:hidden;position: absolute; width: 560px; height: auto; left: 0px; top: -8px; box-sizing: content-box; padding-top: 8px;margin-left:20px;">`
        + `<div class="q-tooltip--style q-position-engine arrow-top question-tooltip" style="--q-transition-duration: 30oms; --left: 27px; --top: false; -px;width:auto;
    padding: 16px 20px;
    background:#fff;
    font-family: AlibabaPuHuiTi;
    font-weight: 400;
    font-size: 14px;
    line-height: 20px;
    border-radius: 12px;
    color: rgba(0,0,0,0.8);
    max-width: 560px;
    box-shadow: 0 0 20px rgba(0, 0, 0, 0.2);
    margin-bottom:0;">`
        + `<span style="width:100%;
  display: inline-block;
  white-space: pre-wrap;">${resStrHide}</span>`
        + `<div style="width:12px;
  position:absolute;
  visibility:visible;
  bottom:-12px;
  height:12px;
  left:calc(50% - 6px);
  background-color:#fff;
  margin-top:0;
  clip-path: polygon(0 0,100% 0, 50% 100%);"></div>`
        + `</div>`
        + `</div>`
        + `</span>`
        + `</span>`
        + `</div>`;

    return `<div   style="position: relative; display: inline-flex;align-items:center">
          <div>${resStrShow}</div>          
          ${tipQuestion}
</div>`;

} else {
    return resStrShow;
}

js代码,实现气泡效果:

    var content = document.querySelector(`.${LocalVars.InParam_UISign}`);
    content.addEventListener('mousemove', function (event) {
        let table = content.querySelector(".fasr_mixview");
        if (table) {
            let tipElems = table.getElementsByClassName("question-tooltip");
            if (tipElems.length > 0) {
                for (let id in tipElems) {
                    if (tipElems[id].style) {
                        let parentNode = tipElems[id].parentNode;
                        // 清除TD提示框 
                        let signParentNode = parentNode;
                        for (let i = 0; i < 10; i++) {
                            if (signParentNode && signParentNode.tagName === 'TD') {
                                signParentNode.title = '';
                                break;
                            }
                            signParentNode = signParentNode.parentNode;
                        }

                        let position = parentNode.getBoundingClientRect()
                        let pX = position.left;
                        let pY = position.top;
                        let height = tipElems[id].offsetHeight
                        let width = tipElems[id].offsetWidth
                        // tipElems[id].style.left = pX - width / 2 - 14.3 + 'px';
                        tipElems[id].style.left = pX - width / 2 - 4 + 'px';
                        tipElems[id].style.top = pY - height - 7 + 'px';
                    }
                }
            }
        }
    });

3、列表格式化时间/字段内容

如果后台给我们的数据未经格式化,需要前端再次处理,我们除了在action里的返回值自定义扩展里面进行修改外,也可以利用列表字段的自定义设置,更加方便

image.png

例如,格式化时间:

return Funcs.FormatDateTime(rowData.row.LastModifyTime, 'yyyy-MM-dd HH:mm:ss');

格式化字段,没有值时展示‘--’

return `<div id="div">${rowData.value?rowData.value:'--'}</div>`

4、列表字段不固定,根据某个值动态展示部分字段,隐藏部分字段

实现思路:设置pc查询方案延迟加载,在onLoaded中,根据当前的模式处理当前方案下需要展示的字段,手动触发查询

 setTimeout(() => {
        let Scheme = Widget.fasr_mixed_view.getScheme()
            let ListViewSet = JSON.parse(Scheme.ListViewSet);
            if( LocalVars.Variable_mdoe=="1"){
               ListViewSet.displayColumns = ListViewSet.displayColumns.filter(item => (item.value != "AccountDesc"&&item.value != "AutoChargeTypeName"))
            }
            if( LocalVars.Variable_mdoe=="2"|| LocalVars.Variable_mdoe=="3"|| LocalVars.Variable_mdoe=="4"){
               ListViewSet.displayColumns = ListViewSet.displayColumns.filter(item => (item.value != "CarUseCustMobile"))
            }
                 
            Scheme.ListViewSet = JSON.stringify(ListViewSet)
            Widget.fasr_mixed_view.setScheme(Scheme)
     
    }, 0)

5、列表的查询条件不固定,根据某个值动态展示隐藏

实现思路:我们可以利用js操作原始dom,对条件进行显示隐藏,简单实现这个需求(低代码提供了硬写的方案,但是很繁琐)

 if(LocalVars.Variable_PVMismatchSwitch == "0"){
   document.querySelector(".Page_DriverManageListALLForNew .el-col-6:last-of-type").style.display = "none";
   }else{
    document.querySelector(".Page_DriverManageListALLForNew .el-col-6:last-of-type").style.display = "block";
   }

6、列表某些场景下列表每页的条数不允许切换,始终保持每页10条

image.png

实现思路:通过修改元素的行内样式,让这个元素彻底无法响应任何鼠标 / 触摸交互事件

 document.querySelector(".t-prefab-pagination__perfective-page-size").style.pointerEvents='none';

7、列表按钮点击触发服务响应缓慢,超过3秒,为防止白屏手动弹出loading

低代码提供了Funcs.ShowLoading(),但是不生效,考虑使用原生dom实现

    let eload1 = window.top.document.getElementById('tff_page_loading');
   eload1 && (eload1.style.display = "block");//显示
   eload1 && (eload1.style.display = "none");//隐藏

8、列表按钮触发后端服务每次只能校验一个,批量操作下需等待所有检查完成后才能进行下一步

实现思路:Promise.all()

  const checkPromises = [];
                let hasBoundVehicle = false;
                let CarLicenseArr = [];

                // 1. 检查所有车辆是否被绑定
                selectedRowDatas.forEach(item => {
                    if (item.VehiclesID) {
                        checkPromises.push(
                            Action.Action_CheckVehicleIfBindMembers_Ecms({ VehicleID: item.VehiclesID })
                                .then(result => {
                                    const hasCarObj = JSON.parse(result.Record.Data);
                                    if (hasCarObj.data) {
                                        CarLicenseArr.push(item.CarLicense);
                                        hasBoundVehicle = true;
                                    }
                                })
                        );
                    }
                });
                // 2. 等待所有检查完成
                Promise.all(checkPromises).then(() => {
                    debugger
                    var loadingMask = document.querySelector("#mvcFrameDiv")?.querySelector(".web-loading_mask");
                    loadingMask && (loadingMask.style.display = "none");
                    console.log(CarLicenseArr)
                    let tipI = ""
                    if (CarLicenseArr.length) {
                        CarLicenseArr.map(item => {
                            tipI += item + "、"
                        });
                        tipI = "当前车辆" + tipI.substring(0, tipI.length - 1) + "已被司机绑定,删除后司机将无法使用企业账户为该车辆充电,确认要删除吗?";
                        Funcs.Confirm(confirm, tipI, function () {
                            VehicleInformationNewUnbind()
                        })
                    } else {
                        Funcs.Confirm(confirm, confirmInfo, function () {
                            VehicleInformationNewUnbind()

                        })
                    }
                });

9、移动端列表没有数据时‘暂无数据’不展示

image.png

后端接口返回的count值不对,低代码模版根据count值决定是否展示暂无数据

10、移动端app框架内页面修改表头标题

需写在onloading方法里

 if(TFF.common.ctx.CLIENT_TYPE.TeldApp == TFF.common.ctx.getClientType()){

 window.pageNameTerm = ''
window.pageTitle = '添加司机'

if(LocalVars.InParam_FormState ==1){
window.pageTitle  ='编辑司机'
}
  TFF.jsdk.ready({ url: '', sgUrlPrefix: '' }, () => {
     window.envApi.setTitle({
            "title" : window.pageTitle ,
            success : function (res) {
             
            }
        })
            });

}

css代码规范

css规范

使用属性简写

/* 使用属性简写 */
.container {
  margin: 10px 20px;
}

/* 不使用属性简写 */
.container {
  margin-top: 10px;
  margin-right: 20px;
  margin-bottom: 10px;
  margin-left: 20px;
}

统一样式格式

/* 统一使用双引号 */
.button {
  font-family: "Arial", sans-serif;
}

/* 统一使用分号结尾 */
.button {
  color: red;
}

避免使用全局样式

全局样式是指能够影响整个页面的样式,比如 body 元素或者 * 选择器。虽然在某些情况下使用全局样式会很方便,但是过度依赖全局样式会增加代码的复杂度,降低代码的可维护性。在编写 CSS 代码时,应该尽量避免使用全局样式,而是优先使用类名和 ID 来控制样式。

 !important

除公共样式之外,在业务代码中尽量不能使用 !important

z-index

建议将 z-index 进行分层,对文档流外绝对定位元素的视觉层级关系进行管理。

不要为 id、class 选择器添加类型选择器

/* good */
#error,.message {
  font-color: #c00;
}

/* bad */
input#error,p.message {
  font-color: #c00;
}

文字排版

  1. 字号 不要小于12px
  2. 字重使用数值
  3. 行高使用数字
 /* good */
h1 {
   font-weight: 700;
   line-height: 1.5;
   font-size: 12px
}

/* bad */
h1 {
   font-weight: bold;
   line-height: 15px;
   font-size: 10px
}

清楚浮动

.clearfix::before,
.clearfix::after {
  content: "";
  display: block;
  clear: both;
}

CSS代码命名规范

前端css代码规范:主要遵循BEM命名规范,BEM分别对应的是block,element和modifier,为的是结束混乱的命名方式,达到一个语义话的css命名方式

BEM命名规范

block

block 表示一个外层组件的意思,表示盒子的呈现的内容,如button,card,tabs等,在块被写为和class的名字一样 常见的block有:

布局类

.header      /* 页头 */
.footer      /* 页脚 */
.sidebar     /* 侧边栏 */
.container   /* 容器 */
.layout      /* 布局 */
.grid        /* 网格布局 */
.wrapper     /* 包装器 */
.frame       /* 框架 */
.holder      /* 容器 */
.box         /* 盒子 */
.panel       /* 面板 */
.segment     /* 分段 */
.section     /* 区块 */
.stack       /* 堆叠布局 */
.column      /* 列 */
.row         /* 行 */
.main        /* 主要内容区 */
.aside       /* 侧边内容 */

UI组件类

.button      /* 按钮 */
.modal       /* 模态框 */
.card        /* 卡片 */
.form        /* 表单 */
.input       /* 输入框 */
.select      /* 选择器 */
.checkbox    /* 复选框 */
.radio       /* 单选框 */
.toggle      /* 切换开关 */
.switch      /* 开关 */
.slider      /* 滑块 */
.range       /* 范围选择器 */
.stepper     /* 步进器 */
.rate        /* 评分组件 */

导航类

.menu          /* 菜单 */
.nav           /* 导航 */
.breadcrumb    /* 面包屑 */
.pagination    /* 分页 */
.tabs          /* 标签页 */
.dropdown      /* 下拉菜单 */
.pager         /* 分页器 */
.quick-nav     /* 快速导航 */
.action-sheet  /* 动作面板 */
.bottom-sheet  /* 底部面板 */
.drawer        /* 抽屉 */

表单控件

.search        /* 搜索框 */
.filter        /* 过滤器 */
.sort          /* 排序器 */
.upload        /* 上传组件 */
.date-picker   /* 日期选择器 */
.time-picker   /* 时间选择器 */
.color-picker  /* 颜色选择器 */
.uploader      /* 上传器 */
.search-bar    /* 搜索栏 */
.filter-bar    /* 筛选栏 */
.textarea      /* 文本域 */
.file-input    /* 文件输入 */

数据展示

.table         /* 表格 */
.list          /* 列表 */
.chart         /* 图表 */
.graph         /* 图形 */
.gauge         /* 仪表盘 */
.progress      /* 进度条 */
.timeline      /* 时间轴 */
.statistic     /* 统计数字 */
.counter       /* 计数器 */
.metric        /* 指标 */
.dashboard     /* 仪表板 */
.data-table    /* 数据表格 */
.pie-chart     /* 饼图 */
.bar-chart     /* 柱状图 */
.line-chart    /* 折线图 */

内容容器

.accordion     /* 手风琴 */
.carousel      /* 轮播图 */
.widget        /* 小部件 */
.tile          /* 磁贴 */
.collection    /* 集合 */
.feed          /* 信息流 */
.stream        /* 流 */
.grid-view     /* 网格视图 */
.list-view     /* 列表视图 */
.portfolio     /* 作品集 */
.gallery       /* 画廊 */

交互反馈

.alert         /* 警告提示 */
.toast         /* 轻量提示 */
.notification  /* 通知 */
.snackbar      /* 底部提示 */
.popover       /* 弹出框 */
.tooltip       /* 工具提示 */
.spinner       /* 加载器 */
.skeleton      /* 骨架屏 */
.placeholder   /* 占位符 */
.overlay       /* 遮罩层 */
.backdrop      /* 背景遮罩 */
.indicator     /* 指示器 */

多媒体

.player        /* 播放器 */
.audio-player  /* 音频播放器 */
.video-player  /* 视频播放器 */
.lightbox      /* 灯箱 */
.slideshow     /* 幻灯片 */
.image         /* 图片容器 */
.video         /* 视频容器 */
.audio         /* 音频容器 */

装饰元素

.avatar        /* 头像 */
.icon          /* 图标 */
.badge         /* 徽章 */
.label         /* 标签 */
.chip          /* 碎片标签 */
.tag           /* 标签 */
.mark          /* 标记 */
.highlight     /* 高亮 */
.divider       /* 分割线 */
.ornament      /* 装饰元素 */
.decoration    /* 装饰 */
.pattern       /* 图案 */

文本相关

.heading       /* 标题 */
.subheading    /* 副标题 */
.caption       /* 说明文字 */
.quote         /* 引用 */
.code-block    /* 代码块 */
.text          /* 文本容器 */
.article       /* 文章 */
.testimonial   /* 推荐语 */
.title         /* 标题 */
.subtitle      /* 副标题 */
.paragraph     /* 段落 */

功能模块

.wizard        /* 向导步骤 */
.tour          /* 引导漫游 */
.help          /* 帮助组件 */
.sorter        /* 排序器 */
.paginator     /* 分页器 */
.wishlist      /* 收藏夹 */
.cart          /* 购物车 */
.checkout      /* 结账流程 */
.settings      /* 设置面板 */
.profile       /* 个人资料 */
.account       /* 账户管理 */

移动端

.floating-action  /* 浮动按钮 */
.swipe            /* 滑动组件 */
.swipeable        /* 可滑动 */
.pull-to-refresh  /* 下拉刷新 */
.infinite-scroll  /* 无限滚动 */
.app-bar          /* 应用栏 */
.bottom-nav       /* 底部导航 */
.tab-bar          /* 标签栏 */

业务相关

.product-card     /* 商品卡片 */
.quick-view       /* 快速查看 */
.add-to-cart      /* 加入购物车 */
.review           /* 评论 */
.rating-stars     /* 星级评分 */
.price-display    /* 价格显示 */
.post             /* 帖子 */
.comment-thread   /* 评论线程 */
.like-button      /* 点赞按钮 */
.share-menu       /* 分享菜单 */
.notification-bell /* 通知铃 */
.profile-card     /* 个人资料卡片 */

营销展示

.banner       /* 横幅 */
.hero         /* 主视觉区 */
.feature      /* 特色区 */
.cta          /* 行动号召 */
.promo        /* 推广区块 */
.spotlight    /* 聚光灯区 */
.showcase     /* 展示区 */
.ad           /* 广告 */
.newsletter   /* 新闻订阅 */

形状组件

.circle       /* 圆形 */
.square       /* 方形 */
.triangle     /* 三角形 */
.diamond      /* 菱形 */
.hexagon      /* 六边形 */
.oval         /* 椭圆形 */
.polygon      /* 多边形 */

状态指示器

.status       /* 状态显示 */
.signal       /* 信号指示 */
.dot          /* 点状指示 */
.marker       /* 标记 */
.flag         /* 标志 */

链接相关

.link           /* 链接 */
.external-link  /* 外部链接 */
.internal-link  /* 内部链接 */
.nav-link       /* 导航链接 */
.button-link    /* 按钮样式链接 */

用户界面

.user-profile    /* 用户资料 */
.user-settings   /* 用户设置 */
.preferences     /* 偏好设置 */
.theme-switcher  /* 主题切换器 */

通知系统

.notification-center  /* 通知中心 */
.notification-bell    /* 通知铃 */
.message-center      /* 消息中心 */
.inbox              /* 收件箱 */

数据分析

.analytics       /* 分析 */
.report          /* 报告 */
.report-generator /* 报告生成器 */
.data-export     /* 数据导出 */
.statistics      /* 统计数据 */

系统管理

.admin-panel     /* 管理面板 */
.system-status   /* 系统状态 */
.backup          /* 备份 */
.restore         /* 恢复 */
.logs            /* 日志 */
.audit           /* 审计 */

时间相关

.timeline        /* 时间线 */
.schedule        /* 计划 */
.calendar        /* 日历 */
.time-range      /* 时间范围 */
.date-selector   /* 日期选择器 */

状态指示

.status-indicator /* 状态指示器 */
.health-status   /* 健康状态 */
.connection-status /* 连接状态 */
.battery-level   /* 电池电量 */

图表类型

.line-chart      /* 折线图 */
.bar-chart       /* 柱状图 */
.pie-chart       /* 饼图 */
.area-chart      /* 面积图 */
.scatter-plot    /* 散点图 */
.heatmap         /* 热力图 */
.gauge-chart     /* 仪表图 */

工具类组件

.toolbar         /* 工具栏 */
.context-menu    /* 上下文菜单 */
.shortcut        /* 快捷方式 */
.quick-action    /* 快速操作 */
.bulk-action     /* 批量操作 */
.wizard          /* 向导 */
.tour            /* 引导 */
.help-tooltip    /* 帮助提示 */

响应式组件

.mobile-view     /* 移动端视图 */
.tablet-view     /* 平板视图 */
.desktop-view    /* 桌面视图 */
.responsive-grid /* 响应式网格 */
.adaptive-layout /* 自适应布局 */

交互组件

.drag-drop       /* 拖放 */
.dropzone        /* 放置区域 */
.draggable       /* 可拖动 */
.sortable        /* 可排序 */
.resizable       /* 可调整大小 */
.collapsible     /* 可折叠 */
.accordion       /* 手风琴 */

存储相关

.storage         /* 存储 */
.storage-usage   /* 存储使用情况 */
.quota           /* 配额 */
.backup-status   /* 备份状态 */
.cloud-storage   /* 云存储 */
.local-storage   /* 本地存储 */

安全组件

.authentication  /* 身份验证 */
.login           /* 登录 */
.logout          /* 登出 */
.password        /* 密码 */
.two-factor      /* 双重认证 */
.encryption      /* 加密 */
.security-log    /* 安全日志 */

监控组件

.monitoring      /* 监控 */
.real-time       /* 实时 */
.historical      /* 历史 */
.trend-analysis  /* 趋势分析 */
.performance     /* 性能 */
.uptime          /* 运行时间 */
.downtime        /* 停机时间 */

同步组件

.sync            /* 同步 */
.sync-status     /* 同步状态 */
.offline         /* 离线 */
.online          /* 在线 */
.conflict        /* 冲突 */
.conflict-resolution /* 冲突解决 */

报告组件

.report          /* 报告 */
.report-builder  /* 报告构建器 */
.report-template /* 报告模板 */
.export-report   /* 导出报告 */
.print-report    /* 打印报告 */
.schedule-report /* 计划报告 */

Element

元素是块的子节点,元素表示的目的,而不是状态。块和元素之间用一个双下划线划开。

布局结构类

__header     /* 头部 */
__footer     /* 脚部 */
__body       /* 主体 */
__main       /* 主要区域 */
__aside      /* 侧边区域 */
__content    /* 内容区域 */
__container  /* 容器 */
__wrapper    /* 包装器 */
__inner      /* 内部容器 */
__section    /* 区块 */
__group      /* 分组 */
__panel      /* 面板 */
__frame      /* 框架 */

导航与交互

__item       /* 项目/项 */
__link       /* 链接 */
__button     /* 按钮 */
__icon       /* 图标 */
__toggle     /* 切换开关 */
__arrow      /* 箭头 */
__caret      /* 指示箭头 */
__handle     /* 手柄/把手 */
__drag       /* 拖拽手柄 */
__scroll     /* 滚动区域 */
__trigger    /* 触发器 */
__action     /* 操作按钮 */

内容显示

__title      /* 标题 */
__subtitle   /* 副标题 */
__heading    /* 标题(可细分 __heading-1, __heading-2) */
__text       /* 文本 */
__label      /* 标签文字 */
__caption    /* 说明文字 */
__description/* 描述 */
__summary    /* 摘要 */
__paragraph  /* 段落 */
__quote      /* 引用 */
__code       /* 代码 */
__image      /* 图片 */
__video      /* 视频 */
__audio      /* 音频 */
__media      /* 媒体内容 */

 表单元素

__input      /* 输入框 */
__textarea   /* 文本域 */
__select     /* 选择框 */
__option     /* 选项 */
__checkbox   /* 复选框 */
__radio      /* 单选按钮 */
__field      /* 表单字段 */
__label      /* 表单标签 */
__hint       /* 提示文字 */
__error      /* 错误信息 */
__success    /* 成功信息 */
__warning    /* 警告信息 */
__validation /* 验证信息 */

列表与集合

__list       /* 列表 */
__item       /* 列表项 */
__entry      /* 条目 */
__row        /* 行 */
__cell       /* 单元格 */
__col        /* 列 */
__grid       /* 网格项 */
__card       /* 卡片 */
__tile       /* 磁贴 */
__block      /* 块状项 */
__segment    /* 分段 */
__piece      /* 片段 */

信息与状态

__status     /* 状态显示 */
__badge      /* 徽章 */
__tag        /* 标签 */
__marker     /* 标记 */
__indicator  /* 指示器 */
__signal     /* 信号 */
__dot        /* 点状指示 */
__counter    /* 计数器 */
__number     /* 数字显示 */
__value      /* 数值 */
__percentage /* 百分比 */
__rating     /* 评分 */
__star       /* 星星 */

装饰与辅助

__icon       /* 图标 */
__avatar     /* 头像 */
__thumbnail  /* 缩略图 */
__preview    /* 预览图 */
__background /* 背景 */
__overlay    /* 遮罩层 */
__shadow     /* 阴影 */
__border     /* 边框 */
__divider    /* 分割线 */
__separator  /* 分隔符 */
__ornament   /* 装饰元素 */
__pattern    /* 图案 */
__gradient   /* 渐变 */

工具与控制

__toolbar    /* 工具栏 */
__tool       /* 工具按钮 */
__control    /* 控制元素 */
__settings   /* 设置按钮 */
__config     /* 配置 */
__option     /* 选项按钮 */
__switch     /* 开关 */
__slider     /* 滑块 */
__handle     /* 滑块手柄 */
__knob       /* 旋钮 */
__dial       /* 刻度盘 */

时间与进度

__time       /* 时间显示 */
__date       /* 日期显示 */
__timestamp  /* 时间戳 */
__duration   /* 时长 */
__progress   /* 进度条 */
__bar        /* 进度条条状部分 */
__track      /* 轨道 */
__step       /* 步骤 */
__milestone  /* 里程碑 */
__clock      /* 时钟 */
__calendar   /* 日历 */

交互反馈

__loading    /* 加载指示器 */
__spinner    /* 旋转器 */
__skeleton   /* 骨架屏元素 */
__placeholder/* 占位符 */
__hint       /* 提示 */
__tooltip    /* 工具提示内容 */
__popup      /* 弹出内容 */
__message    /* 消息内容 */
__alert      /* 警告内容 */
__toast      /* 轻提示内容 */
__notification /* 通知内容 */

导航组件 (Navigation)

/* .menu 的 Element */
__item       /* 菜单项 */
__link       /* 菜单链接 */
__icon       /* 菜单图标 */
__text       /* 菜单文字 */
__submenu    /* 子菜单 */
__dropdown   /* 下拉菜单 */

/* .tabs 的 Element */
__tab        /* 标签页 */
__content    /* 标签内容 */
__nav        /* 标签导航 */
__panel      /* 标签面板 */

/* .breadcrumb 的 Element */
__crumb      /* 面包屑项 */
__separator  /* 分隔符 */

表单组件 (Forms)

/* .form 的 Element */
__group      /* 表单组 */
__field      /* 表单字段 */
__label      /* 标签 */
__input      /* 输入框 */
__error      /* 错误信息 */
__help       /* 帮助文字 */
__submit     /* 提交按钮 */
__reset      /* 重置按钮 */

/* .input 的 Element */
__wrapper    /* 包装器 */
__field      /* 输入区域 */
__prefix     /* 前缀 */
__suffix     /* 后缀 */
__clear      /* 清除按钮 */

卡片组件 (Cards)

/* .card 的 Element */
__header     /* 卡片头部 */
__title      /* 卡片标题 */
__subtitle   /* 卡片副标题 */
__body       /* 卡片主体 */
__content    /* 卡片内容 */
__footer     /* 卡片脚部 */
__image      /* 卡片图片 */
__actions    /* 卡片操作区 */
__button     /* 卡片按钮 */

模态框 (Modals)

/* .modal 的 Element */
__overlay    /* 遮罩层 */
__dialog     /* 对话框 */
__header     /* 头部 */
__title      /* 标题 */
__close      /* 关闭按钮 */
__body       /* 主体 */
__content    /* 内容 */
__footer     /* 脚部 */
__actions    /* 操作区 */

数据表格 (Tables)

/* .table 的 Element */
__header     /* 表头 */
__head       /* 头部区域 */
__body       /* 表格主体 */
__footer     /* 表格脚部 */
__row        /* 行 */
__cell       /* 单元格 */
__col        /* 列 */
__sort       /* 排序按钮 */
__filter     /* 筛选按钮 */
__pagination /* 分页区域 */

工具栏 (Toolbars)

/* .toolbar 的 Element */
__left       /* 左侧区域 */
__center     /* 中间区域 */
__right      /* 右侧区域 */
__item       /* 工具项 */
__button     /* 工具按钮 */
__separator  /* 分隔符 */
__search     /* 搜索框 */
__filter     /* 筛选器 */
__sort       /* 排序器 */

轮播图 (Carousels)

/* .carousel 的 Element */
__slide      /* 幻灯片 */
__content    /* 幻灯片内容 */
__image      /* 幻灯片图片 */
__caption    /* 幻灯片说明 */
__prev       /* 上一个按钮 */
__next       /* 下一个按钮 */
__dots       /* 指示点区域 */
__dot        /* 单个指示点 */
__pagination /* 分页指示器 */

图表组件 (Charts)

/* .chart 的 Element */
__container  /* 容器 */
__canvas     /* 画布 */
__axis       /* 坐标轴 */
__axis-x     /* X轴 */
__axis-y     /* Y轴 */
__grid       /* 网格线 */
__legend     /* 图例 */
__tooltip    /* 工具提示 */
__data       /* 数据点 */
__bar        /* 柱状 */
__line       /* 线条 */
__area       /* 面积 */

通知组件 (Notifications)

/* .notification 的 Element */
__icon       /* 图标 */
__title      /* 标题 */
__message    /* 消息内容 */
__close      /* 关闭按钮 */
__actions    /* 操作按钮 */
__time       /* 时间显示 */
__progress   /* 进度条 */

位置关系

__top        /* 顶部 */
__bottom     /* 底部 */
__left       /* 左侧 */
__right      /* 右侧 */
__center     /* 中间 */
__side       /* 侧边 */
__edge       /* 边缘 */
__corner     /* 角落 */
__start      /* 起始端 */
__end        /* 结束端 */

 大小尺寸

__small      /* 小尺寸 */
__medium     /* 中尺寸 */
__large      /* 大尺寸 */
__mini       /* 迷你尺寸 */
__tiny       /* 超小尺寸 */
__compact    /* 紧凑型 */
__expanded   /* 展开型 */
__full       /* 全尺寸 */

状态指示

__active     /* 激活状态 */
__inactive   /* 非激活状态 */
__enabled    /* 启用状态 */
__disabled   /* 禁用状态 */
__selected   /* 选中状态 */
__checked    /* 勾选状态 */
__focused    /* 聚焦状态 */
__hover      /* 悬停状态 */
__pressed    /* 按下状态 */

数量关系

__single     /* 单个 */
__multiple   /* 多个 */
__first      /* 第一个 */
__last       /* 最后一个 */
__even       /* 偶数 */
__odd        /* 奇数 */
__nth        /* 第n个 */
__all        /* 所有 */
__none       /* 无 */

时间关系

__past       /* 过去 */
__present    /* 现在 */
__future     /* 未来 */
__old        /* 旧的 */
__new        /* 新的 */
__current    /* 当前的 */
__previous   /* 上一个 */
__next       /* 下一个 */

功能角色

__primary    /* 主要的 */
__secondary  /* 次要的 */
__tertiary   /* 第三级的 */
__auxiliary  /* 辅助的 */
__main       /* 主要的 */
__sub        /* 次要的 */
__support    /* 支持的 */
__detail     /* 详细的 */

Modifier

修饰符是改变某个块的外观的标志。要使用修饰符,用一个双短横线线隔开

通用状态

--active      /* 激活/活动状态 */
--inactive    /* 非激活状态 */
--enabled     /* 启用状态 */
--disabled    /* 禁用状态 */
--selected    /* 选中状态 */
--checked     /* 已勾选 */
--unchecked   /* 未勾选 */
--focused     /* 获得焦点 */
--blurred     /* 失去焦点 */
--hover       /* 悬停状态 */
--pressed     /* 按下状态 */
--dragging    /* 拖拽中 */
--loading     /* 加载中 */
--processing  /* 处理中 */
--waiting     /* 等待中 */

可见性状态

--visible     /* 可见 */
--hidden      /* 隐藏 */
--collapsed   /* 折叠 */
--expanded    /* 展开 */
--closed      /* 关闭 */
--open        /* 打开 */
--show        /* 显示 */
--hide        /* 隐藏 */

交互状态

--clickable   /* 可点击 */
--editable    /* 可编辑 */
--draggable   /* 可拖动 */
--droppable   /* 可放置 */
--sortable    /* 可排序 */
--resizable   /* 可调整大小 */
--selectable  /* 可选择 */

数据状态

--empty       /* 空状态 */
--filled      /* 已填充 */
--valid       /* 有效 */
--invalid     /* 无效 */
--verified    /* 已验证 */
--unverified  /* 未验证 */
--dirty       /* 已修改(表单) */
--clean       /* 未修改 */

文件/上传状态

--uploading   /* 上传中 */
--uploaded    /* 已上传 */
--failed      /* 失败 */
--success     /* 成功 */
--pending     /* 等待中 */
--completed   /* 已完成 */
--cancelled   /* 已取消 */

网络/连接状态

--online      /* 在线 */
--offline     /* 离线 */
--connected   /* 已连接 */
--disconnected /* 断开连接 */
--connecting  /* 连接中 */
--syncing     /* 同步中 */
--synced      /* 已同步 */

通用尺寸

/* 通用尺寸 */
--small       /* 小尺寸 */
--medium      /* 中等尺寸 */
--large       /* 大尺寸 */
--xl          /* 加大尺寸 */
--xxl         /* 特大尺寸 */
--tiny        /* 超小尺寸 */
--mini        /* 迷你尺寸 */
--compact     /* 紧凑型 */
/* 宽度尺寸 */
--narrow      /* 窄 */
--wide        /* 宽 */
--full        /* 全宽 */
--half        /* 半宽 */
--third       /* 三分之一宽 */
--quarter     /* 四分之一宽 */
--fluid       /* 流体宽度 */
--fixed       /* 固定宽度 */
/* 高度尺寸 */
--short       /* 矮 */
--tall        /* 高 */
--full-height /* 全高 */
--auto-height /* 自动高度 */
/* 间距尺寸 */
--dense       /* 密集间距 */
--loose       /* 宽松间距 */
--tight       /* 紧凑间距 */
--spacious    /* 宽敞间距 */

颜色主题

--primary     /* 主要颜色 */
--secondary   /* 次要颜色 */
--tertiary    /* 第三颜色 */
--accent      /* 强调色 */
--muted       /* 柔和色 */
--light       /* 浅色 */
--dark        /* 深色 */
--inverse     /* 反色 */

语义颜色

--success     /* 成功/绿色 */
--error       /* 错误/红色 */
--warning     /* 警告/黄色 */
--info        /* 信息/蓝色 */
--danger      /* 危险/红色 */
--safe        /* 安全/绿色 */
--critical    /* 严重/橙色 */

样式变体

--outline     /* 轮廓样式 */
--solid       /* 实心样式 */
--ghost       /* 幽灵样式(透明背景) */
--flat        /* 扁平样式 */
--raised      /* 凸起样式 */
--shadow      /* 有阴影 */
--borderless  /* 无边框 */
--rounded     /* 圆角 */
--square      /* 直角 */
--circle      /* 圆形 */

透明度

--transparent /* 透明 */
--semi-transparent /* 半透明 */
--opaque      /* 不透明 */
--translucent /* 半透明 */

布局方向

--vertical    /* 垂直排列 */
--horizontal  /* 水平排列 */
--row         /* 行方向 */
--column      /* 列方向 */

文本方向

--left        /* 左对齐 */
--center      /* 居中对齐 */
--right       /* 右对齐 */
--justify     /* 两端对齐 */
--start       /* 起始对齐 */
--end         /* 结束对齐 */

位置方向

--top         /* 顶部 */
--bottom      /* 底部 */
--left        /* 左侧 */
--right       /* 右侧 */
--middle      /* 中间 */
--center      /* 居中 */
--absolute    /* 绝对定位 */
--relative    /* 相对定位 */
--fixed       /* 固定定位 */
--sticky      /* 粘性定位 */

浮动方向

--float-left  /* 左浮动 */
--float-right /* 右浮动 */
--float-none  /* 不浮动 */

行为模式

--readonly    /* 只读 */
--editable    /* 可编辑 */
--required    /* 必填 */
--optional    /* 可选 */
--multiple    /* 多选 */
--single      /* 单选 */
--searchable  /* 可搜索 */
--filterable  /* 可筛选 */
--sortable    /* 可排序 */

交互模式

--interactive /* 可交互 */
--static      /* 静态 */
--dynamic     /* 动态 */
--animated    /* 有动画 */
--static      /* 静态 */
--fixed       /* 固定 */
--sticky      /* 粘性 */

数据模式

--empty       /* 空数据 */
--loading     /* 加载数据 */
--loaded      /* 数据已加载 */
--error       /* 数据错误 */
--no-data     /* 无数据 */
--has-data    /* 有数据 */

内容类型

--text        /* 文本类型 */
--number      /* 数字类型 */
--date        /* 日期类型 */
--file        /* 文件类型 */
--image       /* 图片类型 */
--video       /* 视频类型 */
--audio       /* 音频类型 */

文件类型

--pdf         /* PDF文件 */
--doc         /* Word文档 */
--xls         /* Excel文件 */
--ppt         /* PowerPoint文件 */
--image       /* 图片文件 */
--archive     /* 压缩文件 */
--code        /* 代码文件 */

设备类型

--mobile      /* 移动设备 */
--tablet      /* 平板设备 */
--desktop     /* 桌面设备 */
--phone       /* 手机 */
--watch       /* 手表 */
--tv          /* 电视 */

时间状态

--new         /* 新的 */
--old         /* 旧的 */
--recent      /* 最近的 */
--past        /* 过去的 */
--future      /* 未来的 */
--expired     /* 已过期 */
--upcoming    /* 即将到来 */

频率状态

--frequent    /* 频繁的 */
--rare        /* 罕见的 */
--once        /* 一次性的 */
--recurring   /* 重复的 */
--daily       /* 每日的 */
--weekly      /* 每周的 */
--monthly     /* 每月的 */

屏幕尺寸

--mobile      /* 移动端 */
--tablet      /* 平板端 */
--desktop     /* 桌面端 */
--sm          /* 小屏幕 */
--md          /* 中等屏幕 */
--lg          /* 大屏幕 */
--xl          /* 超大屏幕 */

设备方向

--portrait    /* 竖屏 */
--landscape   /* 横屏 */

断点相关

--below-md    /* 小于中等屏幕 */
--above-lg    /* 大于大屏幕 */
--only-mobile /* 仅移动端 */
--only-desktop /* 仅桌面端 */

数据质量

--valid       /* 数据有效 */
--invalid     /* 数据无效 */
--verified    /* 已验证 */
--pending     /* 待验证 */
--expired     /* 已过期 */
--fresh       /* 新鲜数据 */
--stale       /* 陈旧数据 */

数据量

--empty       /* 空数据 */
--few         /* 少量数据 */
--many        /* 大量数据 */
--full        /* 数据已满 */
--overflow    /* 数据溢出 */

安全状态 Modifier

--secured     /* 已保护 */
--unsecured   /* 未保护 */
--encrypted   /* 已加密 */
--decrypted   /* 已解密 */
--authenticated /* 已认证 */
--unauthenticated /* 未认证 */
--authorized  /* 已授权 */
--unauthorized /* 未授权 */

按钮 Button

--primary     /* 主要按钮 */
--secondary   /* 次要按钮 */
--danger      /* 危险操作按钮 */
--warning     /* 警告操作按钮 */
--success     /* 成功操作按钮 */
--link        /* 链接样式按钮 */
--icon        /* 图标按钮 */
--block       /* 块级按钮(宽度100%) */

输入框 Input

--filled      /* 已填充 */
--error       /* 错误状态 */
--success     /* 成功状态 */
--warning     /* 警告状态 */
--disabled    /* 禁用状态 */
--readonly    /* 只读状态 */
--search      /* 搜索框样式 */

表格 Table

--striped     /* 斑马纹 */
--bordered    /* 有边框 */
--hover       /* 悬停效果 */
--condensed   /* 紧凑型 */
--responsive  /* 响应式表格 */
--sortable    /* 可排序 */

卡片 Card

--shadow      /* 有阴影 */
--border      /* 有边框 */
--hoverable   /* 悬停效果 */
--selected    /* 选中状态 */
--clickable   /* 可点击 */
--draggable   /* 可拖动 */

模态框 Modal

--small       /* 小尺寸模态框 */
--medium      /* 中尺寸模态框 */
--large       /* 大尺寸模态框 */
--fullscreen  /* 全屏模态框 */
--centered    /* 居中显示 */

导航 Nav

--vertical    /* 垂直导航 */
--horizontal  /* 水平导航 */
--pills       /* 胶囊式导航 */
--tabs        /* 标签式导航 */
--underline   /* 下划线式导航 */

国际化 Modifier

--ltr         /* 从左到右 */
--rtl         /* 从右到左 */
--en          /* 英语 */
--zh          /* 中文 */
--ja          /* 日语 */
--ar          /* 阿拉伯语 */
--locale-en   /* 英语地区 */
--locale-zh   /* 中文地区 */

优先级 Modifier

--high        /* 高优先级 */
--medium      /* 中优先级 */
--low         /* 低优先级 */
--critical    /* 关键优先级 */
--normal      /* 普通优先级 */
--urgent      /* 紧急优先级 */

为什么在使用Vue的v-for时,一定要加上key字段?

假设我们要渲染一个简单的待办事项列表:

<div id="app">
  <div v-for="item in list">
    <input type="checkbox">
    <span>{{ item.text }}</span>
  </div>
</div>

当我们删除中间某个项目时,你可能会发现复选框的状态出现了错误。选中的项目被删除了,但其他项目的选中状态却乱了套。

问题的根源

Vue在更新DOM时,会尽量复用已有的元素。这是一种优化策略,可以减少DOM操作,提高性能。

但是,当数据顺序发生变化时,Vue需要知道哪些元素可以复用,哪些需要重新创建。如果没有key,Vue只能按照顺序进行对比。

没有key的情况:

  • • Vue按顺序对比新旧节点
  • • 删除第二个元素后,后面的元素会前移
  • • Vue认为这是同一个元素,只是内容变了
  • • 复用的元素保留了之前的状态

key的作用

key给每个节点一个唯一标识。Vue通过这个标识来跟踪每个节点的身份。

<!-- 正确的写法 -->
<div v-for="item in list" :key="item.id">
  <input type="checkbox">
  <span>{{ item.text }}</span>
</div>

加上key之后:

  • • Vue知道每个节点的唯一身份
  • • 删除某个节点时,其他节点身份不变
  • • 不会错误地复用其他节点的状态
  • • 列表更新更加准确

深入理解虚拟DOM

要理解key的重要性,我们需要了解Vue的虚拟DOM机制。

虚拟DOM是什么

虚拟DOM是真实DOM的JavaScript对象表示。Vue通过对比新旧虚拟DOM的差异,来决定如何更新真实DOM。

Diff算法

Vue使用Diff算法来比较虚拟DOM的差异。这个算法会找出最小的变更,然后应用到真实DOM上。

没有key的Diff过程:

  • • 按顺序逐个比较节点
  • • 发现长度变化,进行插入或删除
  • • 可能导致大量不必要的DOM操作

有key的Diff过程:

  • • 根据key建立映射关系
  • • 精确找到新增、删除、移动的节点
  • • 最小化DOM操作

key的选择

选择合适的key很重要。不合适的key可能带来问题。

好的key选择

  • • 数据中的唯一标识符
  • • 稳定的、不会改变的值
  • • 如:数据库ID、UUID等
// 好的例子
const list = [
  { id: 1, text: '学习Vue' },
  { id: 2, text: '写代码' },
  { id: 3, text: '阅读文档' }
]

不好的key选择

  • • 数组索引(在排序、过滤时会出问题)
  • • 随机数(每次渲染都会变化)
  • • 可能重复的值
// 不好的例子 - 使用索引作为key
<div v-for="(item, index) in list" :key="index">

// 不好的例子 - 使用随机数作为key  
<div v-for="item in list" :key="Math.random()">

实际开发中的场景

列表排序

当列表需要排序时,key的作用特别明显。

// 初始列表
[
  { id: 1, name: '苹果' },
  { id: 2, name: '香蕉' }, 
  { id: 3, name: '橙子' }
]

// 排序后
[
  { id: 3, name: '橙子' },
  { id: 1, name: '苹果' },
  { id: 2, name: '香蕉' }
]

有key时,Vue知道这是元素位置的移动,而不是内容的修改。

列表过滤

过滤列表时,key确保正确的元素被保留或移除。

动态组件

在动态组件中,key可以强制组件重新创建:

<component :is="currentComponent" :key="componentKey">

改变componentKey会触发组件的重新渲染。

性能考虑

什么时候可以不加key

在某些简单场景下,不加key可能不会立即发现问题:

  • • 静态列表,永远不会改变
  • • 列表项没有内部状态
  • • 列表项非常简单

但为了代码的健壮性,建议始终加上key。

错误的使用方式

有些开发者会这样使用key:

<!-- 错误:使用索引作为key -->
<div v-for="(item, index) in list" :key="index">

<!-- 错误:使用不稳定的值作为key -->
<div v-for="item in list" :key="Math.random()">

这些用法都会导致各种奇怪的问题。

常见问题解答

为什么不能用索引作为key?

当列表发生变化时,索引也会变化。原来索引为1的元素,在删除前面的元素后,可能变成索引0。这会导致Vue错误地复用元素。

key一定要全局唯一吗?

在同一个v-for中唯一即可,不需要全局唯一。

如果没有唯一标识怎么办?

如果数据源没有提供唯一标识,可以考虑:

    1. 在获取数据时生成唯一ID
    1. 使用多个字段组合作为key
    1. 使用第三方库生成UUID

记住:key是Vue跟踪节点身份的标识,不是普通的属性。

写在最后

理解key的作用,能帮助我们写出更稳定、性能更好的Vue应用。这个看似小的细节,在实际开发中却很重要。

下次使用v-for时,记得给它一个合适的key。

❌