【Unity Shader Graph 使用与特效实现】专栏-直达

在Unity引擎的渲染管线中，GPU实例化是一项重要的性能优化技术，它允许在单个绘制调用中渲染多个相同的网格，显著减少了CPU到GPU的数据传输开销。在URP（Universal Render Pipeline）的Shader Graph中，InstanceID节点扮演着关键角色，它为开发者提供了访问每个实例唯一标识符的能力。本文将深入探讨InstanceID节点的各个方面，包括其工作原理、应用场景、使用技巧以及实际示例。

InstanceID节点的基本概念

InstanceID节点是Shader Graph中的一个特殊功能节点，它返回当前正在渲染的几何体实例的唯一标识符。这个标识符在GPU实例化过程中由Unity引擎自动分配和管理。

当Unity使用GPU实例化技术渲染多个相同网格时，每个实例都会获得一个独一无二的Instance ID。这个ID从0开始递增，对应于绘制调用中每个实例的索引位置。理解这一点对于正确使用InstanceID节点至关重要。

InstanceID节点的输出是一个浮点数值，代表当前实例的标识符。在非实例化渲染情况下，这个值始终为0。需要注意的是，当使用动态实例化时，实例ID在不同帧之间可能不会保持一致，这意味着开发者不应该依赖实例ID在多个帧之间的持久性。

InstanceID节点的工作原理

要深入理解InstanceID节点，首先需要了解GPU实例化的基本机制。GPU实例化允许在单个绘制调用中渲染多个相同的网格，每个实例可以有不同的变换矩阵、颜色和其他属性。Unity通过实例缓冲区（Instance Buffer）将这些每实例数据传递给着色器。

在着色器执行过程中，系统会为每个实例分配一个唯一的索引，这就是Instance ID的来源。InstanceID节点本质上就是访问这个内置的着色器变量unity_InstanceID。

在HLSL代码中，InstanceID节点的实现大致如下：

HLSL

void Unity_InstanceID_float(out float Out)
{
    Out = unity_InstanceID;
}

当在Shader Graph中使用InstanceID节点时，这个内置变量会被自动包含在生成的着色器代码中。Unity的渲染管线负责在实例化绘制调用时正确设置这个值。

InstanceID节点的端口配置

InstanceID节点的端口配置相对简单，只有一个输出端口：

输出端口（Out）提供当前实例的ID值，数据类型为浮点数（Float）。这个端口不需要任何绑定，因为它的值是由渲染管线自动提供的。

虽然输出类型显示为浮点数，但实际使用时，实例ID通常是整数值。在Shader Graph中，我们可以通过适当的节点将其转换为整数，或者直接作为浮点数使用，具体取决于应用场景。

InstanceID节点的应用场景

InstanceID节点在Shader Graph中有多种应用场景，以下是几个常见的用例：

• 实例差异化：通过Instance ID为每个实例生成不同的颜色、大小或外观，即使它们使用相同的网格和材质。例如，在渲染一片森林时，可以使用Instance ID为每棵树生成略微不同的颜色和大小，增加场景的自然感。
• 程序化动画：利用Instance ID为每个实例创建不同的动画效果。例如，在渲染一群鱼时，可以使用Instance ID控制每条鱼的游动相位，使鱼群运动更加自然。
• 数据索引：使用Instance ID作为索引，从纹理或数组中查找对应的数据。这在需要为每个实例应用不同贴图或参数时特别有用。
• 随机值生成：将Instance ID作为随机数生成的种子，为每个实例创建可预测的随机值。这种方法确保同一实例在不同帧中保持一致的随机行为。
• 调试和可视化：在开发过程中，使用Instance ID可视化不同的实例，帮助调试实例化相关的问题。

使用InstanceID节点的注意事项

在使用InstanceID节点时，有几个重要事项需要注意：

• 实例化启用条件：InstanceID节点只有在真正使用GPU实例化时才会返回有意义的非零值。确保材质和渲染设置正确启用了GPU实例化。
• 动态实例化的不稳定性：当使用动态实例化时，实例ID在不同帧之间可能不一致。避免依赖实例ID的持久性进行跨帧的状态管理。
• 性能考虑：虽然访问InstanceID本身开销很小，但基于它的复杂计算可能会影响性能。在移动平台等性能受限的环境中要特别小心。
• 最大值限制：实例ID的取值范围受限于绘制调用中的实例数量。在极少数情况下，如果实例数量超过一定限制，可能需要考虑替代方案。
• 与非实例化渲染的兼容性：在非实例化渲染情况下，InstanceID始终返回0。确保着色器在这种情况下也能正确工作。

InstanceID节点与其他节点的配合使用

InstanceID节点通常需要与其他Shader Graph节点配合使用才能发挥最大效用：

与数学节点结合，可以通过简单的运算将Instance ID转换为更有用的值范围。例如，使用取模运算将Instance ID限制在特定范围内。

与纹理节点配合，可以使用Instance ID作为UV坐标或纹理数组的索引，实现每个实例使用不同纹理的效果。

与随机节点结合，可以将Instance ID作为随机种子，生成每个实例特有的随机值，同时保证这些值在帧间保持一致。

与时间节点配合，可以创建基于Instance ID的相位偏移动画，使多个实例的动画效果错开，增加视觉多样性。

实际示例：创建实例化颜色变化效果

下面通过一个具体示例演示如何使用InstanceID节点为实例化对象创建颜色变化效果：

首先在Shader Graph中创建InstanceID节点，然后将其连接到Color节点的各个通道。通过适当的数学运算，可以将Instance ID映射到不同的颜色范围。

一个常见的做法是使用正弦函数基于Instance ID生成平滑的颜色变化：

HLSL

// 伪代码示例
float hue = (InstanceID * 0.1) % 1.0;
float3 color = HSLtoRGB(hue, 1.0, 0.5);

在Shader Graph中，可以通过以下节点连接实现类似效果：

1. 将InstanceID节点连接到Multiply节点，乘以一个小数（如0.1）控制颜色变化速率
2. 将结果连接到Fraction节点，取小数部分确保值在0-1范围内
3. 使用这个值作为HDR Color节点的Hue输入

这种方法可以为每个实例生成独特但协调的颜色，非常适合用于创建大规模的对象群组，如草地、人群或星空。

实际示例：实例化动画偏移

另一个实用示例是使用InstanceID节点为实例化对象创建动画偏移：

假设我们有一组使用相同动画的实例，但希望它们的动画相位不同，避免所有实例完全同步运动。可以通过以下步骤实现：

将InstanceID节点连接到Multiply节点，乘以一个控制相位间隔的值。然后将结果添加到时间变量上，作为每个实例的个性化时间输入。

在Shader Graph中的具体实现：

1. 创建Time节点获取着色器时间
2. 创建InstanceID节点获取实例标识
3. 使用Multiply节点将InstanceID乘以一个小的相位值（如0.2）
4. 使用Add节点将时间与相位偏移相加
5. 将这个个性化时间用于驱动动画计算

这种方法可以创建更加自然和有机的动画效果，特别适用于群体动画，如鸟群、鱼群或摇摆的植物。

性能优化与最佳实践

为了确保使用InstanceID节点的着色器具有良好的性能，可以遵循以下最佳实践：

• 尽量减少基于InstanceID的复杂计算，特别是在片段着色器中
• 尽可能在顶点着色阶段完成基于InstanceID的计算，而不是在片段着色阶段
• 使用适当的精度修饰符，在保证质量的同时减少计算开销
• 在移动平台上，测试使用InstanceID的着色器性能，确保不会造成帧率下降
• 考虑使用其他实例化技术，如GPU实例化属性块，对于大量不同的实例数据

常见问题与解决方案

在使用InstanceID节点时，可能会遇到一些常见问题：

如果InstanceID始终返回0，首先确认是否真正启用了GPU实例化。检查材质的Inspector窗口，确保"Enable GPU Instancing"选项已勾选。同时确认是通过Graphics.DrawMeshInstanced或类似的实例化API进行渲染。

如果实例化对象的颜色或行为不符合预期，检查基于InstanceID的计算是否正确。特别注意数值范围和精度问题，确保计算不会导致意外的截断或溢出。

当遇到性能问题时，使用Unity的Frame Debugger分析绘制调用和实例化情况。确认实例化确实按预期工作，并且没有意外的批处理中断。

---

【Unity Shader Graph 使用与特效实现】专栏-直达 （欢迎点赞留言探讨，更多人加入进来能更加完善这个探索的过程，🙏）

前言：小明和他的照片墙危机

想象一下，你是小明，一个热爱摄影的程序员。周末去爬山拍了一堆4K高清照片，总共3GB，准备发给老婆分享。微信传？算了，压缩后画质渣得像像素风。网盘？离线状态下连不上。蓝牙？慢得像蜗牛在跑步。你急得团团转，突然灵机一动：用电脑直接传啊！可是怎么在浏览器里实现局域网P2P大文件传输，还得支持断点续传？别急，今天咱们就聊聊这个技术方案。

技术背景：P2P不是什么新鲜玩意儿

P2P（点对点）传输在局域网里其实挺常见的，BT下载就是经典案例。但咱们今天聊的是纯前端实现，意思是完全不用后端服务器，用户A直接把文件传给用户B。核心技术是WebRTC（Web Real-Time Communication），这货本来是用来视频聊天的，但咱们可以拿来传文件。

为什么选WebRTC？因为它支持数据通道（DataChannel），可以直接在浏览器间建立连接。加上File API和Blob，咱们就能把大文件切成小块，边传边收，断点续传自然就出来了。

核心实现：分块传输 + 断点续传

1. 文件切块：大象塞冰箱，得先切成块

浏览器处理大文件有个硬伤：内存限制。如果直接把3GB文件读进内存，Chrome得哭爹喊娘。所以咱们用FileReader分块读：

// 文件分块函数
function chunkFile(file, chunkSize = 1024 * 1024) { // 1MB每块
  const chunks = [];
  let offset = 0;
  
  while (offset < file.size) {
    const chunk = file.slice(offset, offset + chunkSize);
    chunks.push(chunk);
    offset += chunkSize;
  }
  
  return chunks;
}

这里用file.slice()切块，每个块1MB。为什么要1MB？平衡传输效率和内存占用，太小网络开销大，太大浏览器卡。

2. WebRTC连接：建立地下通道

WebRTC连接需要信令服务器（用来交换连接信息），但咱们是离线局域网，所以可以用WebSocket或者直接用浏览器本地存储交换SDP（会话描述协议）。

// 创建RTCPeerConnection
const pc = new RTCPeerConnection({
  iceServers: [] // 局域网不需要STUN服务器
});

// 创建数据通道
const dataChannel = pc.createDataChannel('file-transfer');

// 监听连接事件
dataChannel.onopen = () => console.log('通道开了，可以传文件了');
dataChannel.onmessage = handleMessage;

3. 断点续传：从中断处继续

断点续传的关键是记录已传块的进度。用IndexedDB或者localStorage存进度：

// 发送文件块
async function sendFileChunks(file, dataChannel) {
  const chunks = chunkFile(file);
  const progress = loadProgress(file.name) || 0; // 从本地加载进度
  
  for (let i = progress; i < chunks.length; i++) {
    const chunk = chunks[i];
    const arrayBuffer = await chunk.arrayBuffer();
    
    // 发送块数据，带上索引
    dataChannel.send(JSON.stringify({
      type: 'chunk',
      index: i,
      data: arrayBuffer
    }));
    
    saveProgress(file.name, i + 1); // 保存进度
  }
  
  // 发送结束信号
  dataChannel.send(JSON.stringify({ type: 'end' }));
}

接收端收到块后，先存到临时数组，收到'end'信号再合并成完整文件。

浏览器限制：那些坑爹的现实

1. 文件大小限制：Chrome说不行就不行

Chrome对单个文件上传有限制，默认是2GB。有些版本甚至更低。遇到大文件怎么办？继续分块，但块数太多会影响性能。

解决方案：用File System Access API（Chrome 86+），可以直接操作本地文件系统，绕过内存限制。

// 使用File System Access API
const fileHandle = await window.showOpenFilePicker();
const file = await fileHandle.getFile();
const writableStream = await fileHandle.createWritable();

// 分块写入
for (const chunk of chunks) {
  await writableStream.write(chunk);
}
await writableStream.close();

2. 内存泄漏：传着传着浏览器崩了

大文件传输时，如果不及时释放Blob对象，内存会爆。解决方案：用stream API边读边传：

// 用ReadableStream处理大文件
const stream = file.stream();
const reader = stream.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  // 直接发送value（Uint8Array）
  dataChannel.send(value);
}

3. 网络限制：局域网防火墙挡道

公司局域网可能有防火墙，WebRTC的UDP连接会被挡。解决方案：降级到WebSocket，或者用TURN服务器中转（但这就不纯前端了）。

实战案例：三个真实场景

案例1：照片分享应用

我之前做的一个家庭相册App，用这个技术实现了局域网照片同步。妈妈在客厅电脑上传相册，爸爸在卧室就能直接收到，不用连路由器。

关键代码：进度条显示 + 错误重试

// 进度显示
dataChannel.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'progress') {
    updateProgressBar(message.percent);
  }
};

案例2：游戏存档同步

做游戏开发时，团队成员在局域网同步大存档文件（几GB）。用断点续传，网络断了重连后从断点继续，省去了重传的时间。

案例3：视频剪辑素材传输

剪辑师在局域网传4K视频素材。传统方法用U盘慢，用这个方案直接浏览器传，还能显示传输速度和剩余时间。

其他方案：当WebRTC不够用时

方案1：WebTorrent

基于WebRTC的BitTorrent实现，支持多对多传输，更适合大文件群发。

import WebTorrent from 'webtorrent';

const client = new WebTorrent();
client.seed(file, (torrent) => {
  console.log('种子创建成功:', torrent.magnetURI);
});

优点：多人同时下载快。缺点：需要种子文件管理。

方案2：Socket.IO + 二进制传输

用WebSocket传二进制数据，配合socket.io实现断点续传。

const socket = io();
socket.emit('send-file-chunk', { chunk, index });

socket.on('chunk-received', (index) => {
  // 继续发下一块
});

优点：兼容性好。缺点：需要服务器中转。

方案3：Electron应用

如果纯浏览器限制太多，可以做个Electron桌面应用，用Node.js的fs模块直接操作文件系统，结合WebRTC。

总结与展望

纯前端P2P大文件断点传输，听起来高大上，其实就是把文件切块 + WebRTC传数据 + 本地存储进度。浏览器限制是客观存在的，但通过File System API和内存管理，大部分场景都能搞定。

未来，随着WebTransport协议的普及（基于HTTP/3），传输效率会更高。5G和WiFi 6普及后，局域网传输速度会飞起。

下次老婆让你传照片，别再抱怨网速了，直接用浏览器P2P传吧！有什么问题，评论区见。🚀

1. 简介

1.1 什么是 Ollama？

Ollama 是一个开源的大模型运行工具，支持在本地运行 Llama 3、Qwen2.5、DeepSeek、Mistral 等上百款大语言模型。它通过命令行操作，简单高效，特别适合开发者快速部署和测试各类 AI 模型。

1.2 核心特性

特性	说明
一键部署	一行命令完成安装和模型启动
API 兼容	自带 OpenAI 格式 API，现有项目可直接迁移
跨平台支持	macOS、Linux、Windows 全平台覆盖
模型丰富	内置 Qwen2.5、DeepSeek-V3、Llama 3 等上百款模型
安全可靠	支持密钥认证，修复已知安全漏洞

1.3 硬件要求

模型规模	显存要求	内存要求	推荐场景
3B（轻量）	3GB+	8GB+	低配设备、快速测试
7B（推荐）	4-6GB	16GB+	日常开发、个人使用
13B（进阶）	10-12GB	32GB+	专业应用、团队协作
30B+（专业）	24GB+	64GB+	企业部署、复杂任务

---

2. 安装指南

2.1 macOS 安装

# 方法一：一键安装脚本（推荐）
curl -fsSL https://ollama.com/install.sh | sh

# 方法二：使用 Homebrew
brew install ollama

# 验证安装
ollama --version

2.2 Linux 安装

# 一键安装脚本
curl -fsSL https://ollama.com/install.sh | sh

# 验证安装
ollama --version

2.3 Windows 安装

1. 访问官网下载：ollama.com/download
2. 下载 OllamaSetup.exe
3. 运行安装程序，务必勾选「Add to PATH」
4. 打开 PowerShell 或 CMD，验证安装：

ollama --version

2.4 验证安装成功

安装完成后，运行以下命令验证：

ollama --version
# 输出示例：ollama version is 0.12.0

---

3. 启动服务（重要）

3.1 启动 Ollama 服务

安装完成后，必须先启动 Ollama 服务才能下载模型或进行对话。

方法一：启动服务（推荐）

ollama serve

保持这个终端窗口运行，然后新开一个终端窗口执行其他命令。

---

方法二：后台运行（macOS/Linux）

# 后台启动服务
ollama serve &

# 然后直接执行其他命令
ollama pull qwen2.5:7b

---

Windows 用户：

确保 Ollama 应用已经在运行（在系统托盘查看 Ollama 图标），或在 PowerShell/CMD 中执行：

ollama serve

3.2 验证服务运行状态

# 测试服务是否正常运行
curl http://localhost:11434/api/tags

# 或查看已安装模型
ollama list

3.3 服务未响应处理

如果遇到 Error: ollama server not responding 错误：

1. 确认服务已启动：运行 ollama serve
2. 检查端口占用：lsof -i :11434（macOS/Linux）或 netstat -ano | findstr :11434（Windows）
3. 重启服务：关闭当前终端，重新执行 ollama serve
4. 检查安装：运行 ollama --version 确认正确安装

---

4. 国内加速配置（必做）

4.1 设置国内镜像

由于 Ollama 官方模型库在国内访问较慢，建议配置国内镜像加速：

# macOS / Linux
export OLLAMA_MODEL_SERVER=https://mirror.ollama.com

# Windows（PowerShell）
$env:OLLAMA_MODEL_SERVER="https://mirror.ollama.com"

4.2 永久配置镜像

macOS / Linux（推荐）：

# 编辑配置文件
nano ~/.bashrc  # 或 ~/.zshrc

# 添加以下内容
export OLLAMA_MODEL_SERVER=https://mirror.ollama.com

# 保存后重新加载配置
source ~/.bashrc  # 或 source ~/.zshrc

Windows：

1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 在「用户变量」中新建：
   • 变量名：OLLAMA_MODEL_SERVER
   • 变量值：https://mirror.ollama.com

---

5. 安全配置（重要）

5.1 设置 API 密钥

为防止未授权访问，建议设置访问密钥：

# 设置密钥
export OLLAMA_API_KEY=your_strong_password123

# Windows PowerShell
$env:OLLAMA_API_KEY="your_strong_password123"

5.2 限制本地访问

仅允许本地访问，避免暴露到公网：

# 绑定到本地回环地址
export OLLAMA_HOST=127.0.0.1:11434

# Windows PowerShell
$env:OLLAMA_HOST="127.0.0.1:11434"

---

6. 模型管理

6.1 搜索可用模型

访问 Ollama 官方模型库：ollama.com/library

常用中文模型推荐：

模型	说明	显存占用
qwen2.5:7b	通义千问 2.5，中文效果优异	~4.5GB
qwen2.5:14b	更强中文能力，适合专业场景	~9GB
deepseek-r1:7b	DeepSeek 推理模型	~4.5GB
gemma2:9b	Google 开源模型	~5.5GB
llama3.1:8b	Meta Llama 3.1	~5GB

6.2 下载模型

# 下载通义千问 7B（中文推荐）
ollama pull qwen2.5:7b

# 下载 INT4 量化版本（显存优化）
ollama pull qwen2.5:7b-chat-q4_0

# 下载 Llama 3.1
ollama pull llama3.1:8b

# 下载 DeepSeek 推理模型
ollama pull deepseek-r1:7b

6.3 查看已安装模型

ollama list

输出示例：

NAME                    ID              SIZE    MODIFIED
qwen2.5:7b              846a0b7e        4.7GB   2 hours ago
llama3.1:8b             a7872503        4.9GB   1 day ago

6.4 删除模型

# 删除指定模型
ollama rm qwen2.5:7b

# 删除多个模型
ollama rm llama3.1:8b gemma2:9b

---

7. 使用指南

7.1 命令行对话

# 启动交互式对话
ollama run qwen2.5:7b

# 直接提问（非交互模式）
ollama run qwen2.5:7b "请用 Python 写一个快速排序"

# 从文件读取提示
ollama run qwen2.5:7b "$(cat prompt.txt)"

7.2 启动 API 服务

# 启动服务（默认端口 11434）
ollama serve

# 自定义端口
export OLLAMA_HOST=0.0.0.0:8080
ollama serve

7.3 测试 API 服务

# 测试健康检查
curl http://localhost:11434/api/tags

# 测试对话接口
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "你好，请介绍一下你自己"
}'

---

8. 编程调用

8.1 浏览器环境（原生 Fetch）

// 流式响应示例
async function chatWithOllama(prompt) {
  const response = await fetch("http://localhost:11434/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer your_api_key"
    },
    body: JSON.stringify({
      model: "qwen2.5:7b",
      messages: [{ role: "user", content: prompt }],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let result = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n").filter(line => line.trim());

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = line.slice(6);
        if (data === "[DONE]") continue;
        try {
          const json = JSON.parse(data);
          const content = json.choices?.[0]?.delta?.content;
          if (content) {
            result += content;
            console.log(content);
          }
        } catch (e) {
          // 忽略解析错误
        }
      }
    }
  }
  return result;
}

// 使用
chatWithOllama("写一个 Python 快速排序");

8.2 Node.js 环境

const axios = require("axios");

async function chatWithOllama(prompt) {
  const response = await axios.post(
    "http://localhost:11434/v1/chat/completions",
    {
      model: "qwen2.5:7b",
      messages: [{ role: "user", content: prompt }],
      temperature: 0.7,
      max_tokens: 2000
    },
    {
      headers: {
        "Authorization": "Bearer your_api_key"
      }
    }
  );

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

// 使用
chatWithOllama("写一个 Python 快速排序").then(console.log);

---

9. 常见问题

9.1 下载速度慢

解决方案：

# 配置国内镜像
export OLLAMA_MODEL_SERVER=https://mirror.ollama.com

9.2 显存不足

解决方案：

# 选择 INT4 量化版本
ollama pull qwen2.5:7b-chat-q4_0

# 或选择更小的模型
ollama pull qwen2.5:3b

9.3 Windows 启动失败

解决方案：

下载并安装 Microsoft C++ 生成工具： visualstudio.microsoft.com/visual-cpp-…

9.4 服务未响应

检查清单：

# 1. 确认服务正在运行
ollama serve

# 2. 检查端口是否被占用
lsof -i :11434  # macOS/Linux
netstat -ano | findstr :11434  # Windows

# 3. 检查防火墙设置

# 4. 验证 API 密钥
echo $OLLAMA_API_KEY

9.5 模型加载慢

优化方案：

• 将模型存储在 SSD 硬盘
• 关闭其他占用 GPU 的程序
• 选择量化版本的模型

---

10. 进阶配置

10.1 自定义模型

创建 Modelfile 自定义模型：

FROM qwen2.5:7b

# 设置系统提示
SYSTEM You are a helpful AI assistant specialized in Python programming.

# 设置参数
PARAMETER temperature 0.7
PARAMETER num_ctx 4096

构建自定义模型：

ollama create my-python-assistant -f Modelfile
ollama run my-python-assistant

10.2 并发设置

调整并发请求数：

export OLLAMA_NUM_PARALLEL=4

10.3 日志级别

# 设置日志级别（debug/info/warn/error）
export OLLAMA_DEBUG=1
export OLLAMA_LOG_LEVEL=info

---

11. 更新与卸载

11.1 更新 Ollama

# macOS / Linux
ollama update

# Windows：重新下载安装包覆盖安装

11.2 卸载 Ollama

macOS：

brew uninstall ollama
rm -rf ~/.ollama

Linux：

sudo systemctl stop ollama
sudo systemctl disable ollama
rm -rf /usr/local/bin/ollama ~/.ollama

Windows：

1. 控制面板 → 程序和功能 → 卸载 Ollama
2. 删除用户目录下的 .ollama 文件夹

最近逛GitHub时，发现一个很有意思的项目——一个纯前端实现的对话生成器，效果非常精致。推荐给感兴趣的朋友，如果想深入钻研CSS，这个项目也很值得研究。另外，马上就要到马年了，顺便也分享一个之前收藏的用CSS实现的动态奔跑骏马效果。这两个项目都展现了CSS的巧妙运用，既适合学习借鉴，也很有趣味性。

👩聊天生成器

对话生成器：一个简单好玩的在线聊天制作工具

github地址：github.com/zixiwangluo…

在线地址：zixiwangluo.github.io/wxdh/

🌠功能简介

这是一个可以在线生成微信风格聊天截图的工具，支持以下功能：

• 自定义苹果或安卓手机状态栏（时间、电量、信号等）
• 设置对话双方的头像和昵称
• 发送文字、语音、红包、转账等聊天元素
• 自由编辑对话内容，生成高度仿真的微信聊天效果
• 无论是制作搞笑对话、剧情截图，还是用于演示与分享等轻松场景，这个工具都能带来不少乐趣。

该项目完全基于HTML、CSS和JavaScript实现，非常适合前端学习者参考。如果想直接使用，可将源码下载到本地，打开index.html即可运行；如果有服务器，也可以直接部署到Nginx等环境中，使用非常简单，这里就不多做介绍了。

平时写文章或做教程时如果需要聊天素材，也可以用它来快速生成。效果示例如下：

🐎纯css实现的奔驰的骏马

随着马年临近，这个奔跑的骏马效果格外应景。最初在某博客中发现这个创意实现，视觉效果流畅自然，于是特别部署了在线演示方便体验。

演示地址1：h5.xiuji.mynatapp.cc/horse/

演示地址2：aa51f2d3.pinit.eth.limo/

效果如下：

如果你想获取源码，可以通过浏览器开发者工具（F12）查看并复制相关代码。代码就两文件，一个html,一个css。

👽总结

这两个项目虽然功能不同，但都体现了前端开发的创意与技巧：

1. 微信对话生成器展示了如何通过前端技术模拟复杂UI，实现高度可定制的交互工具，对学习CSS布局和JavaScript DOM操作很有帮助。
2. CSS奔驰骏马则纯粹依靠样式表创造流畅动画，是学习CSS动画、关键帧和性能优化的优秀案例。

无论是想要寻找实用工具，还是希望深入学习前端技术，这两个项目都值得收藏研究。它们证明了，即使不使用复杂框架和库，纯前端技术也能创造出既美观又实用的效果。

🐟今日摸鱼小贴士:从入门到“入厕”新境界

领导眼皮底下吨吨灌水，洗手间里频繁“打卡”

主打一个尿喝白，电充绿，事干黄。

业绩虽暂时躺平，但新陈代谢已实现遥遥领先✨

❗❗❗特别声明

此项目来自互联网公开资源，仅供学习交流使用，切勿用于非法途径，由此产生任何纠纷由使用者本人自己承担，如有侵权，请及时联系删除❗❗❗

实时渲染

2. 图形渲染管线

2.4 光栅化

顶点及其关联的着色数据（全部来自几何处理阶段）在进行变换和投影后，下一阶段的目标是找到所有像素（图片元素的缩写），这些像素位于要渲染的图元内部，例如三角形。我们将此过程称为光栅化，它分为两个功能子阶段：三角形设置（也称为图元组装）和三角形遍历。它们显示在图2.8的左侧。请注意，这些也可以处理点和线，但由于三角形最常见，因此子阶段的名称中带有“三角形”。因此，光栅化也称为扫描转换，是将屏幕空间中的二维顶点（每个顶点具有z值（深度值）和与每个顶点关联的各种着色信息）转换为屏幕上的像素。光栅化也可以被认为是几何处理和像素处理之间的同步点，因为在这里三角形由三个顶点形成并最终发送到像素处理。

是否认为三角形与像素重叠取决于您如何设置GPU的管线。例如，您可以使用点抽样来确定“内部性”。最简单的情况是在每个像素的中心使用单点样本，因此如果该中心点在三角形内部，那么相应的像素也被视为三角形内部。您还可以使用超级采样或多重采样抗锯齿技术（第5.4.2节）为每个像素使用多个样本。另一种方法是使用保守光栅化，其中的定义是，如果像素的至少一部分与三角形重叠，则像素位于三角形“内部”（第23.1.2节）。

2.4.1 三角形设置

在这个阶段，计算三角形的微分、边方程和其他数据。这些数据可用于三角形遍历（第2.4.2节），以及用于几何阶段产生的各种着色数据的插值。这个任务通常是硬件的固定功能。

2.4.2 三角形遍历

在这个阶段，会检查每个像素中心（或样本）被三角形覆盖的位置，并为与三角形重叠的像素部分生成片元。更详细的抽样方法可以在第5.4节中找到。查找三角形内的样本或像素通常称为三角形遍历。每个三角形片元的属性是使用在三个三角形顶点之间插入的数据生成的（第5章）。这些属性包括片段的深度，以及来自几何阶段的任何着色数据。McCormack等人在文献[1162]中提到了有关三角形遍历的更多信息。也是在这个阶段，对三角形执行透视校正插值[694]（第23.1.1节）。然后将图元内的所有像素或样本发送到像素处理阶段，这个下述章节会进行论述。

2026年，我为什么越来越离不开 NestJS + Monorepo

2026 年，AI 辅助开发工具已经彻底融入了日常写代码的节奏。Cursor、Claude Code、Trae……它们不再是偶尔用的插件，而是每天打开 IDE 后第一个跳出来的“队友”。

用得越多，越能感受到一种微妙的落差：工具本身越来越聪明，生成的代码却常常在细节上出问题。依赖没导入、规范被忽略、类型对不上、UI 的风格不统一……这些小毛病加起来，让 review 的时间比生成代码的时间还长。有时候我甚至会想：AI 明明能写出 70% 的内容，为什么剩下的 30% 却让我这么累？

后来我慢慢意识到，问题不全在工具，而在“舞台”。给 AI 一个结构松散、上下文碎片的项目，它再怎么努力，也容易出错；给它一个边界清晰、类型强、模块分明的项目，它的第一轮输出往往就能直接 merge。

NestJS + Monorepo（以 Turborepo 为主）就是我目前找到的最舒服的舞台。它没有太多花哨的新概念，却在 AI 时代把“结构即生产力”这件事做到了极致。

用这个组合后，我发现 accept 能稳定在 70% 以上，重构和扩展的成本大幅降低，全栈偏前端的体验也变得异常顺滑。不是因为它完美无缺，而是因为它让 AI 和我之间的配合，少了很多互相折腾，多了一些安静的默契。

AI 辅助开发的趋势

2026 年，开发者使用 AI 辅助开发的比例已经达到了一个非常高的水平。根据各种社区调查、GitHub 数据和开发者论坛的反馈，绝大多数活跃开发者（尤其是前端、全栈、Node.js 生态）都已经把 AI 工具当作日常标配。

• 超过 80% 的开发者每天至少使用一次 AI 编码工具（Cursor、Trae、Claude Code、GitHub Copilot、Windsurf、Aider 等）。
• 在 TypeScript / JavaScript 项目中，这个比例更高，接近 90%，因为强类型和结构化代码让 AI 的输出更可靠。
• 很多中高级开发者已经把“先让 AI 写初稿 → 我 review & 微调”作为默认工作流，而不是“自己从零写”。

为什么大家越来越喜欢用 AI 辅助开发？核心原因可以总结为三点：

1. 效率提升明显且可感知
   写 boilerplate、CRUD 接口、类型定义、测试用例、甚至一些业务逻辑的初版，AI 都能在几十秒内完成。开发者把时间从“重复劳动”转移到“思考业务、设计架构、优化性能、安全审查”这些更有价值的部分。

2. 工具体验越来越“像人”
   2026 年的 Cursor 和 Claude Code 已经能很好地理解项目上下文：

   • Cursor 的 Composer 模式可以一次性修改多个文件，并保持一致性。
   • Claude Code 的 agentic 能力允许它“先读代码 → 分析需求 → 规划步骤 → 写代码 → 自测 → 提交”。
   • 很多开发者反馈：现在让 AI 写一个完整的 feature（前后端 + 类型 + 测试），成功率已经能稳定在 60–80%，远高于 2024 年的 30–40%。

3. 社区与生态的正反馈循环
   越来越多项目公开分享 .cursorrules、CLAUDE.md、prompt 模板、boilerplate。
   开发者看到别人用 AI 把一个中型 SaaS 后端一周内搭出来，就会想“我也试试”。
   这种“看到别人用得好 → 我也想用 → 用得好 → 分享”形成了明显的正循环。

AI 辅助开发的问题与痛点

趋势看起来很美好，但实际用起来，经常是另一种风景。

我和大多数开发者一样，每天打开 IDE 第一件事就是让 AI 帮忙写代码。可越用越发现，工具再强，也常常在细节上“掉链子”。

这些问题不是偶发，而是系统性的，尤其在项目规模稍大、结构不清晰的时候，会被放大到让人抓狂的地步。

上下文碎片化

当项目拆成多个 repo（前端一个、后端一个、shared types 又一个），AI 根本无法一次性看全依赖关系。

它会根据当前文件猜上下文，结果就是幻觉层出不穷：字段名拼错、类型不匹配、甚至把旧版本的接口逻辑带进来。

我试过用 Cursor 重构一个 GO 代码的逻辑，字段明明在 DTO 里定义好了，它还是给我写了个不存在的属性。

规范与风格不一致

AI 没有“记忆”你的项目约定。它不知道你用的是 NestJS 的 DI 还是纯函数式，不知道要加 ValidationPipe 还是手动校验，不知道 auth 要用 Guard 还是 middleware。

结果生成的代码风格五花八门：有的地方用 class-validator，有的直接 if 判断；有的地方注入 service，有的直接 new 一个。

后期维护时，这些小差异会像雪球一样越滚越大。

重构效率低下

想改一个共享类型或调整 auth 逻辑？

AI 改了当前文件，却漏掉其他 5 个依赖的地方。尤其是跨包修改时，Cursor 偶尔会“卡住”——不是工具问题，是项目结构让它没法高效追踪依赖。重构一次，本来 10 分钟的事，变成 1 小时+手动补漏。

review 成本居高不下

AI 能生成 60–80% 的代码，但剩下的 20–40% 往往是关键逻辑、安全边界、性能点。这些地方出错，后果严重，所以我几乎每段 AI 代码都要从头审一遍。

时间一长，感觉 AI 不是在帮我加速，而是在给我制造更多“看起来对但其实不对”的工作。

扩展功能时的破坏性

项目本来是传统 CRUD，突然想加个简单的接口。结果要么大改架构，要么新建一个独立的模块，最后前后端割裂，类型又对不上。

AI 时代，本该是“想加就加”的功能，却变成了“加了之后整个项目都乱了”。

这些痛点加起来，让我一度怀疑：AI 到底是生产力工具，还是另一个“看起来很美”的负担？

2026 年，AI 辅助开发已经进入“基础设施”阶段

2026 年，AI 辅助开发已经从“炫技”阶段彻底进入“基础设施”阶段。

工具链的演进方向非常明确：从单行补全 → 多文件编辑 → 项目级上下文理解 → agentic 多步规划。

• “2026 年的开发效率差距，不再是会不会用 AI，而是你的项目结构能不能让 AI 发挥出 70% 以上的命中率。”

数据也印证了这一点：

• GitHub Octoverse 2025 显示，使用 monorepo 的仓库中，AI 生成代码的 acceptance rate 平均高出 28%。
• Cursor 官方在 2025 年底的报告里提到：在结构化项目（TypeScript + 明确的模块边界）里，用户平均 accept 率能稳定在 68–75%，而在“杂乱的 Express 项目”里，只有 42%。

更重要的是，AI 工具的上下文窗口已经不再是瓶颈（200k token 随便用），真正的瓶颈变成了**“AI 能不能在 0.5 秒内看懂你的整个项目结构”**。

这时候，monorepo + 强规范框架的优势就彻底显现出来了。

简单来说，2026 年的趋势就是：

AI 越来越聪明，但它更需要一个“聪明”的项目来配合。

而 NestJS + Monorepo 正是我见过的最能把这种配合做到极致的组合。

NestJS + Monorepo 如何解决这些痛点

上面提到的那些痛点，用一句话概括就是：AI 很聪明，但它需要一个“聪明”的项目来配合。

NestJS + Monorepo（以 Turborepo 为主）正是我目前找到的最能让 AI “配合好”的组合。它不是靠什么黑科技，而是靠结构本身把 AI 的命中率从 30–40% 拉到 70%+，甚至更高。

下面按痛点一一对应，说说这个组合是怎么解决的。

上下文碎片化 → Monorepo 让 AI 一次性看全项目

AI 的问题是只能看到当前打开的文件或有限的上下文。

monorepo 把前端（apps/web）、后端（apps/api）、共享类型（libs/types）、数据库 schema（libs/db）、甚至 UI 组件（libs/ui）全部放在同一个仓库里。AI 工具（如 Cursor Composer）直接索引整个 repo，依赖关系、类型定义、接口契约一目了然。

实际效果：

• 生成前端调用后端 API 时，它不会再凭空发明一个不存在的字段。
• 改一个 shared type（如 UserDto），AI 能自动追踪到所有使用它的地方，一次性改完。

规范与风格不一致 → NestJS 装饰器 + DI 是“天然提示”

NestJS 的核心设计（模块化、依赖注入、装饰器）本质上就是一套“写给 AI 看的规范语言”。

• @Controller、@Get、@Post 明确告诉 AI 这个类是 HTTP 入口。
• @Injectable、constructor 注入让 AI 知道要用 DI，而不是乱 new。
• @Body() + class-validator + ValidationPipe 让 AI 自动生成校验逻辑，几乎不会漏掉 required 字段。
• @UseGuards、@UseInterceptors 让 auth、logging、rate-limit 等切面逻辑天然统一。

在 .cursorrules 里写几行规则：

始终用 NestJS 模块化结构：新 feature 放在 apps/api/src/{domain} 下。
共享类型放在 libs/types，用 zod 或 infer。
优先用 tRPC 暴露 API，保持端到端类型安全。
所有 DTO 必须用 class-validator 校验。

AI 就会像老员工一样，生成的代码风格高度一致。Claude Code 甚至能根据这些规则自发写出符合规范的测试用例。

重构效率低下 → Turborepo caching + 模块边界让 AI 改得又快又准

Turborepo 的远程缓存和并行任务，让 monorepo 的 build / dev 速度飞起（Rust 重写后，冷启动和增量 build 快 3–5x）。

AI 修改多个包时，不会因为 build 卡住而中断思路。

同时，NestJS 的模块边界（每个 domain 一个 module）让 AI 很容易定位修改范围：

• 改 auth 逻辑 → 只动 libs/auth 和 apps/api/src/auth。
• 加 rate-limit → 只需在 common/interceptors 加一个全局 Interceptor，所有路由自动生效。

review 成本高 → 端到端类型安全 + 测试友好让 bug 提前死掉

tRPC + zod / infer 让类型在 monorepo 里零成本同步：

• libs/types 定义 DTO → tRPC router infer → 前端 hook 自动带类型。
• AI 生成前端调用时，几乎不会出现 “property does not exist” 这种低级错误。

NestJS 的 DI 也让单元测试 / 集成测试非常好写：mock service 一行代码搞定。

我现在习惯让 AI 顺手生成 Vitest / Jest 测试用例，review 时先跑测试，失败的直接迭代 prompt，成功率高很多。

扩展 AI 功能时的破坏性 → 模块化 + libs/ai 像插件一样插拔

想加 RAG、chat、embedding？

新建一个 libs/ai 包，注入 OpenAI / Anthropic client，写几个 service（embeddingService、ragService），然后在 apps/api 里暴露 tRPC 路由。

业务代码几乎不改，原有模块不受影响。

如果任务重，还可以新建 apps/worker（BullMQ 队列），异步处理 embedding / indexing。

这个“插件式”扩展方式，让 AI 功能从“额外负担”变成了“可选项”。我最近加了一个简单的思考链 Agent，只用了半天时间，项目结构一点没乱。

总的来说，NestJS + Monorepo 不是在“教 AI 写代码”，而是在“教 AI 如何按照我的规则写代码”。

NestJS 全栈偏前端的闭环体验

在 NestJS + Monorepo 的组合里，最让我觉得“离不开”的地方，其实是它把全栈偏前端的开发体验做到了一个近乎闭环的状态。

所谓“全栈偏前端”，就是以前端为主（Next.js App Router 为主力），后端只是为了支撑业务逻辑、数据持久化、API 暴露，但又不想把后端写得太随意。

过去用 Express 或 Fastify，原生写后端总觉得割裂：类型定义要手动同步、前端调用 API 时容易出字段错、部署前后端要分开管、规范靠口头约定……这些小摩擦累积起来，会让开发节奏断断续续。

NestJS + Monorepo 几乎把这些摩擦全部抹平了，形成了下面几个明显的闭环：

端到端类型安全的零成本同步

核心靠 tRPC + shared libs。 在 libs/types 里定义 DTO（如 UserDto、NotificationPreferencesDto），然后在 NestJS 的 tRPC router 里用 infer 或 zod 直接导出类型。前端（Next.js）通过 tRPC client 消费时，类型自动带过来。

AI 生成前端 mutation / query 时，几乎不会出现 “property does not exist on type” 的低级 bug。

我最近改一个用户设置接口，整个过程 AI 改了后端 controller + service + 前端 page + hook，类型全程对齐，我只 review 了业务逻辑的边界条件。

迭代速度与 AI 节奏完美匹配

Turborepo 的缓存机制（尤其是 Rust 重写后的版本）让 monorepo 的 turbo run dev / build 快到离谱。

前后端同时开发时，改一个 shared type 或后端接口，前端热重载几乎秒级响应。

AI 帮我快速生成一个 feature，我 review 完 accept → turbo 瞬间 build → 浏览器刷新看到效果，整个 cycle 控制在 5–10 分钟。

这和 AI 的“快速试错”节奏高度吻合：想改就改，想加就加，不会因为 build 慢或 deploy 麻烦而卡住思路。

部署与运维的极简闭环

Vercel 原生支持 Turborepo monorepo，一键 deploy 前后端（apps/web → frontend，apps/api → serverless 或 edge functions）。

后端用 NestJS Fastify mode，吞吐量比 Express 高 2–4 倍，成本控制更友好。

不再需要维护两个 repo 的 CI/CD、两个地方的 env variables、两个地方的监控。

前后端同构体验，前端转全栈学习曲线最低

NestJS 的装饰器风格、模块化、TypeScript 原生，和 Next.js 的 App Router + server actions 高度相似。

前端开发者上手 NestJS 时，几乎没有陌生感：controller 像 page route，service 像 server action 或 lib function，pipes / interceptors 像 middleware。

AI (如 Trae) 补全时，也更容易理解上下文——因为前后端风格统一，它生成的代码天然一致。

为什么 NestJS 在这么多 Node 后端选项里，能成为全栈偏前端的最优选择？

简单对比一下：

• Express / Fastify 原生：太灵活 → 规范靠自己 → AI 容易乱写。
• Hono / Elysia：轻量极致 → 但缺少模块化 + DI，AI 在中大型项目里上下文跟不上。
• Adonis / FoalTS：企业级，但学习曲线陡，生态不如 NestJS 活跃。
• NestJS：结构强、TypeScript 友好、装饰器像“提示工程”、社区 boilerplate 多、与 Next.js 生态无缝对接。

NestJS 不是最轻、最快，但它是目前 Node 生态里“最不拖 AI 后腿、又能让前端开发者写得舒服”的后端框架。

放在 monorepo 里，它就把“前后端割裂”这个老问题，变成了“前后端像一家人”。

用这个组合后，我写代码的感受从“前后端两套逻辑在打架”变成了“前后端在同一个 repo 里安静地合作”。

这大概就是“闭环”的真正含义。

独立部署与微服务友好：monorepo 不等于单体

很多人一听到 monorepo，就担心它会变成一个“大单体”：所有代码耦合在一起，部署慢、扩展难、维护成噩梦。但 NestJS + Monorepo 的实际用法恰恰相反，它在保持代码共享便利的同时，天然支持独立部署和微服务边界。

核心靠以下几点设计：

• 每个 app / service 独立：monorepo 里可以有多个 apps，比如 apps/api（主后端）、apps/worker（队列任务）、apps/admin（后台管理）。Turborepo 支持每个 app 单独 build、test、deploy。
  CI/CD 配置时，用 turbo run build --filter=api 只构建 api 包，其他不动。Vercel、Railway 或 GitHub Actions 都能轻松实现“改 api 只 deploy api”。

• NestJS 原生微服务支持：NestJS 内置多种传输层（TCP、Redis、NATS、gRPC、MQTT），模块之间可以通过 @nestjs/microservices 解耦。
  比如 auth 模块做成独立 microservice，暴露 gRPC 接口；主 api 只消费它，不耦合实现。共享 libs/auth 只放类型和 DTO，逻辑完全隔离。

• 共享 libs 边界清晰：libs/types、libs/db、libs/common 只放接口、schema、常量、工具函数，不放业务逻辑。
  这让模块间“共享知识但不共享状态”，避免了单体式的纠缠。

这在 2026 年 AI 项目里特别实用：核心业务稳，AI 增强功能（RAG、Agent）可以先做成独立 worker 或 microservice，随时加减。

团队协作与规范强制：monorepo 的“护城河”效应

monorepo 最大的隐形价值，其实不是个人效率，而是它在团队协作时的“护城河”作用。

NestJS + Monorepo 的结构本身就像一套强制规范：

• 每个 domain 必须有自己的 module、controller、service、dto。
• 共享逻辑只能放在 libs/*（types、db、auth、common），不允许业务代码跨包污染。
• 全局配置（如 eslint、prettier、commitlint、ValidationPipe、Interceptors）在根目录统一，一改全项目生效。

这对团队意味着什么？

• 新人上手快：结构固定，新人 clone repo 后一看目录就知道怎么加功能。AI 生成的代码也天然符合规范，不用额外教“我们的风格是这样的”。
• 规范强制执行：没有“口头约定”或“大家自己注意”的模糊地带。想加一个新接口？必须走 NestJS 装饰器 + DTO + tRPC。AI 补全时也会自动遵守，减少了风格漂移。
• code review 摩擦大幅降低：因为类型安全 + 模块边界，AI 生成的代码往往是“看起来对的”，review 重点从“风格对不对”转向“业务逻辑对不对”。
• 多人协作不乱：改 shared type 时，Turborepo 会自动检测影响范围，build 只跑相关的包。merge conflict 少了很多，团队不会因为“谁动了 libs/auth”而吵起来。

实际体验里，这个“护城河”在 3 人以上小团队最明显。

一个人写时，monorepo 只是方便；团队写时，它成了防止代码退化的防火墙。

AI 时代尤其有用：大家用 Cursor / Claude Code 生成代码时，风格统一、边界清晰，团队不会因为“AI 写的太乱”而互相指责。

结构即生产力

2026 年，AI 辅助开发已成为标配，但其效率高度依赖项目结构。

NestJS + Monorepo 让我越来越离不开它：monorepo 解决上下文碎片，让 AI 一次性看全项目；

NestJS 的模块化、DI、装饰器提供“天然提示”，规范强制执行，减少 hallucination 和风格漂移；tRPC + shared libs 实现端到端类型安全，前后端闭环顺滑；

Turborepo 缓存让迭代飞起，独立部署 + 微服务友好避免单体陷阱；社区 boilerplate 爆发，上手快，团队协作更稳。

它不是最潮的框架，却是最能让 AI 写出可维护、可 review、可长期演进代码的组合。

全栈偏前端的开发者用它，开发从“前后割裂”变成“安静合作”。

在 AI 时代，结构即生产力，而这个组合，正是我目前最舒服的结构。

本文将手把手介绍如何将rust编写的函数打包为wasm供js使用，并解释其关键配置和实践中的常见问题。

5分钟快速上手

1. 环境准备

rust和cargo

rust环境安装教程参考如下：

• 官网：rust-lang.org/zh-CN/tools…
• rust圣经：course.rs/first-try/i…

可执行rustc --version和cargo --version验证安装，如果没问题会有如下类似输出

rustc 1.92.0 (ded5c06cf 2025-12-08)
cargo 1.92.0 (344c4567c 2025-10-21)

wasm编译目标和 wasm-pack

执行以下命令；

rustup target add wasm32-unknown-unknown

 cargo install wasm-pack

---

2. rust lib项目创建

cargo相当于js的npm，可以用cargo创建一个lib：

cargo new test-rust-lib --lib

--lib是生成库，默认是--bin，也就是生成项目。两者的区别是前者会在src下生成lib.rs，后者是mian.rs。

---

3. 修改Cargo.toml

修改Cargo.toml，添加依赖和lib配置

[package]
name = "test-rust-lib"
version = "0.1.0"
edition = "2024"
[lib]
crate-type = ["cdylib"]
[dependencies]
wasm-bindgen = "0.2"

---

4.编写rust代码

这里用项目默认的add为例，使用 wasm_bindgen 宏标记要导出的函数：

use wasm_bindgen::prelude::*;
#[wasm_bindgen]
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

---

5.编译和发布

执行以下命令即可在当前项目的pkg文件中生成wasm文件

 wasm-pack build --target web

---

生成的文件里自带package.json，可以直接发布npm包

npm login
npm publish

本地测试

方便起见，可以直接在项目的pkg目录中创建一个html进行测试：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <h1>curve lib test</h1>
    <script type="module">
     //加载并执行...
    </script>
  </body>
</html>

加载打包出来的test_rust_lib.js：

 //加载并执行...
  import init, { add } from "./test_rust_lib.js";//或npm包

  async function run() {
    const res = await init();
    console.log(add(1n, 2n));
  }
  run();

注意因为rust中定义的类型是u64,js中对应的是BigIng

---

rust wasm进阶

本节将详细解释wasm打包中的关键角色。

编译目标 wasm32-unknown-unknown

如果你是第一次看到wasm32-unknown-unknown可能有点懵逼， wasm32-unknown-unknown 是 Rust 的编译目标（target triple） ，代表你要把代码编译成 WebAssembly (WASM) 格式的二进制文件。

Rust 的 target 三元组（triple）一般形如：

<架构>-<厂商>-<操作系统>

对于 wasm32-unknown-unknown 来说：

部分	含义	说明
wasm32	架构	32 位 WebAssembly 指令集（WASM 目前只定义了 32 位）
unknown	厂商	没有特定厂商（WebAssembly 是开放标准）
unknown	操作系统	没有底层 OS（WASM 在虚拟机环境中执行）

换句话说，它的意思是：

“编译为 32 位 WebAssembly 目标，独立于具体厂商或操作系统的环境。”

下面是一些常见的target和适用环境

Target	位数	环境	标准库	说明 / 场景
wasm32-unknown-unknown	32 位	浏览器 / 纯 Web 环境	❌ 无 std	✅ 浏览器最常用目标，配合 wasm-bindgen
wasm64-unknown-unknown	64 位	浏览器（未来标准）	❌ 无 std	🧪 实验中，支持 64 位寻址（>4GB 内存）
wasm32-wasi	32 位	服务端 / CLI	✅ 有 std	✅ 支持文件、环境变量、socket
wasm64-wasi	64 位	服务端 / CLI	✅ 有 std	🧪 新兴，WASI 64-bit 支持大内存服务
wasm32-unknown-emscripten	32 位	浏览器 (旧方案)	✅ 有 std	⚠️ 已过时，体积大，依赖 JS runtime

如果是浏览器加载，无脑wasm32-unknown-unknown

crate-type

上文在toml文件中有如下配置：

[lib]
crate-type = ["cdylib", "rlib"]

可能有人会问：什么是crate-type

在 Rust 中，一个 crate（包）可以被编译成多种形式：

• 可执行文件（bin）
• 静态库（staticlib）
• 动态库（dylib / cdylib）
• Rust 库文件（rlib）
• WebAssembly 模块（通过 cdylib 或 wasm32-* 目标）

crate-type 就是告诉编译器 “我要生成哪种类型的输出”。

---

主要类型说明:

类型	说明	适用场景
rlib	Rust 专用静态库格式（默认）	✅ 供其他 Rust crate 依赖
cdylib	C-compatible 动态库（推荐用于 FFI / WASM）	✅ 用于导出函数给其他语言（C, Python, JS等）
dylib	Rust 动态库（带 Rust 元数据）	⚠️ 较少使用，只能被 Rust 加载
staticlib	纯静态库（.a）	✅ 方便嵌入 C/C++ 程序
bin	可执行程序	用于 CLI 应用

自定义类型的导出问题

如果导出的函数里有自定义类型，比如下面代码，就会提示

the trait bound CurveFitConfig: FromWasmAbi is not satisfied”

比如下面这段代码：

#[wasm_bindgen] 
pub fn curve_fitting(x: f64, config: CurveFitConfig) -> Option<f64> {
...
}

这里最佳的解决办法是JsValue和serde-wasm-bindgen,保持原函数不变，另导出一个给js调用的函数。

use serde_wasm_bindgen::from_value;

#[wasm_bindgen]
pub fn curve_fitting_wasm(x: f64, config: JsValue) -> Option<f64> {
    let cfg: CurveFitConfig = from_value(config).ok()?;
    curve_fitting(x, cfg)
}

对相应的类型增加序列化宏

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct CurveFitConfig {
   ...
}

wasm导出函数的测试问题

wasm导出函数，如果是在rust环境里测试，会报错

cannot call wasm-bindgen imported functions on non-wasm targets

最佳实践就是分层设计，单独写wasm导出函数：

• 核心逻辑与 JS 绑定分离
• 普通 Rust 测试不依赖 wasm
• wasm 函数只是一个“外层包装器”

wasm-bindgen

如果你看过上一篇文章《# WebAssembly入门（一）——Emscripten》可能了解胶水代码的概念，wasm-bindgen就是提供js和rust交互的胶水代码用的。

其核心功能如下：

• ‌类型转换‌：wasm-bindgen 自动处理 Rust 和 JavaScript 之间的类型转换，例如将 Rust 的字符串、数组、结构体等映射为 JavaScript 中的对应类型。
• ‌导出与导入函数‌：通过使用 #[wasm_bindgen] 属性宏，开发者可以轻松地将 Rust 函数导出给 JavaScript 调用，同时也可以在 Rust 中导入 JavaScript 函数。
• ‌内存管理‌：对于复杂类型如字符串或 DOM 对象，wasm-bindgen 会自动管理其生命周期，避免内存泄漏。
• ‌异步支持‌：它支持异步 Rust 代码，并能与 JavaScript 的异步机制协同工作。
• ‌事件与回调‌：支持定义和使用 JavaScript 的事件处理器和回调函数。

init函数

在使用 wasm-pack 打包 Rust 编写的 WebAssembly 模块时，生成的 JavaScript 胶水代码中会包含一个名为 init 的异步函数。这个函数是 WebAssembly 模块加载和初始化的核心入口，它负责完成以下关键任务：

• ‌异步加载 .wasm 文件‌：通过 fetch 或 import 动态加载编译后的 WebAssembly 二进制文件。
• ‌实例化 Wasm 模块‌：将加载的字节码传递给浏览器的 WebAssembly API，创建可执行的模块实例。
• ‌绑定 JavaScript 接口‌：连接由 #[wasm_bindgen] 标记的 Rust 函数与 JavaScript 环境，使它们能被直接调用。
• ‌初始化内存与全局状态‌：设置 Wasm 模块的线性内存、导出的全局变量和内部状态，确保模块运行时环境就绪。

init 函数返回一个 Promise，因此在使用时必须使用 await 或 .then() 等待其完成。只有在 init() 成功解析后，你才能安全地调用任何从 Rust 导出的函数。

init的promise返回值中也可以获取到导出的函数

init函数，初次执行完成后，可以重复执行，没有副作用，这一点很多ai都回答的不对，但如果初次加载时同时执行多次，就会创建多个wasm instance。

Elva Scroll View，一个适用于嵌套滚动的 Flutter 包，具备多层级协同滚动和多层级惯性滚动动画传递功能。

一、效果与功能

1.1 效果演示

1.2 支持的功能

• 嵌套滚动支持：支持多级嵌套滚动视图，实现平滑的滚动协调
• 惯性滚动传递：惯性滚动动画可以在多个滚动组件之间传递
• Shell 模式：支持阻止滚动偏移继续向上传播，实现独立的滚动区域
• 灵活的 Builder 模式：使用 Builder 模式，易于集成到现有代码中
• 自定义通知系统：提供丰富的滚动事件通知

二、使用

2.1 安装

在项目的 pubspec.yaml 文件中添加：

dependencies:
  elva_scroll_view: ...

2.2 基础用法

ElvaScrollViewBuilder 是一个构建组件，用于包装需要协调滚动的 CustomScrollView。使用ElvaScrollViewBuilder包裹你需要协调滚动的 CustomScrollView或者其他滚动组件，即可实现滚动协调功能：

ElvaScrollViewBuilder(
  builder: (context, controller) {
    return CustomScrollView(
      controller: controller,
      slivers: [
        SliverAppBar(...),
        SliverList(...),
      ],
    );
  }
)

2.3 Shell 参数

Shell参数会中止滚动偏移继续向上传播，实现独立的滚动区域。

ElvaScrollViewBuilder(
  isShell: true,
  builder: (context, controller) {
    return CustomScrollView(
      controller: controller,
      slivers: [...]
    );
  }
)

三、核心 API

3.1 ElvaScrollViewBuilder

主要的构建组件，用于包装需要协调滚动的 CustomScrollView。

参数：

• builder: 构建函数，接收 context 和 controller
• debugLabel: 用于日志记录的调试标签
• isShell: 是否为 shell 组件。当为 true 时，滚动偏移不会继续向上传播

3.2 ElvaScrollViewScrollController

自定义滚动控制器，实现了 TransportPixelNode mixin，负责处理滚动协调和传递。

3.3 ElvaScrollViewPosition

自定义滚动位置管理器，继承自 Flutter 原生的 ScrollPositionWithSingleContext，实现：

• 用户拖拽偏移处理
• 惯性滚动启动和管理
• 动画偏移应用

3.4 ElvaScrollViewAnimationOverscrollDispatcher

惯性滚动动画分发器，负责：

• 收集需要接受滚动事件的组件
• 按顺序分发惯性滚动动画
• 管理过滚动传递

3.5 ElvaScrollViewAnimationScrollingNotification

当全局过滚动事件动画发生时分发。

属性：

• overscroll: 过滚动量
• consumed: 当前滚动视图消耗的量

四、原理剖析

1. [Flutter] infinity与可滚动布局
2. [Flutter] ScrollActivity与ScrollActivityDelegate
3. [Flutter] 多层级嵌套滚动
4. [Flutter] 嵌套滚动与弹性嵌套滚动

五、其他：

1. Github项目地址
2. DartPub地址

顺便求个⭐️~

 TypeScript的核心价值

TypeScript是JavaScript的超集，添加了静态类型检查。它在编译时发现错误，而不是在运行时，从而提高代码质量和开发效率。

---

1️⃣ 类型安全：避免运行时错误

JavaScript的类型问题

JavaScript
// JavaScript - 运行时才发现错误
function calculateArea(width, height) {
  return width * height;
}

// 这些调用在运行时才会出错
console.log(calculateArea("10", "20"));     // "1020" (字符串拼接)
console.log(calculateArea(10));             // NaN (height为undefined)
console.log(calculateArea(10, null));       // 0 (null转为0)
console.log(calculateArea({}, []));         // NaN (对象转数字失败)

// 更复杂的例子
function processUser(user) {
  // 如果user为null或undefined，这里会报错
  return user.name.toUpperCase() + " - " + user.email.toLowerCase();
}

// 运行时错误：Cannot read property 'name' of null
processUser(null);

TypeScript的类型保护

TypeScript
// TypeScript - 编译时发现错误
interface User {
  name: string;
  email: string;
  age: number;
}

function calculateArea(width: number, height: number): number {
  return width * height;
}

// 编译时错误，IDE会立即提示
// calculateArea("10", "20");  // ❌ Argument of type 'string' is not assignable to parameter of type 'number'
// calculateArea(10);          // ❌ Expected 2 arguments, but got 1
// calculateArea(10, null);    // ❌ Argument of type 'null' is not assignable to parameter of type 'number'

function processUser(user: User): string {
  return user.name.toUpperCase() + " - " + user.email.toLowerCase();
}

// 编译时错误
// processUser(null);  // ❌ Argument of type 'null' is not assignable to parameter of type 'User'

// 正确使用
const validUser: User = {
  name: "John Doe",
  email: "john@example.com",
  age: 30
};
console.log(processUser(validUser)); // ✅ 类型安全

---

2️⃣ 智能提示和自动补全

JavaScript的开发体验

JavaScript
// JavaScript - 无法确定对象结构
function handleApiResponse(response) {
  // IDE无法知道response有什么属性
  // 需要查看文档或运行代码才知道
  console.log(response.); // 无智能提示
}

// 数组方法也缺少智能提示
const users = getUsers(); // 不知道数组元素类型
users.forEach(user => {
  console.log(user.); // 无法知道user有什么属性
});

TypeScript的智能开发体验

TypeScript
interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
  timestamp: number;
}

interface User {
  id: number;
  name: string;
  email: string;
  profile: {
    avatar: string;
    bio: string;
  };
}

function handleApiResponse(response: ApiResponse<User[]>): void {
  // IDE提供完整的智能提示
  if (response.success) {
    response.data.forEach(user => {
      // 智能提示显示所有可用属性和方法
      console.log(user.name.toUpperCase());
      console.log(user.email.includes('@'));
      console.log(user.profile.avatar);
      // IDE会提示拼写错误
      // console.log(user.nam); // ❌ Property 'nam' does not exist
    });
  }
}

// 数组方法的类型推断
const userNames: string[] = users.map(user => user.name); // 自动推断为string[]
const adults: User[] = users.filter(user => user.age >= 18); // 类型安全的过滤

---

3️⃣ 重构安全性

JavaScript重构的风险

JavaScript
// 原始代码
class UserService {
  getUserInfo(userId) {
    return fetch(`/api/user/${userId}`)
      .then(res => res.json());
  }
}

class ProfileComponent {
  loadUser(id) {
    this.userService.getUserInfo(id)
      .then(user => {
        this.displayName(user.fullName); // 使用fullName属性
      });
  }
  
  displayName(name) {
    document.getElementById('userName').textContent = name;
  }
}

// 如果API改变了，返回的是name而不是fullName
// JavaScript无法检测到这个变化，只有在运行时才会发现错误

TypeScript的重构安全

TypeScript
interface User {
  id: number;
  name: string; // 从fullName改为name
  email: string;
}

class UserService {
  async getUserInfo(userId: number): Promise<User> {
    const response = await fetch(`/api/user/${userId}`);
    return response.json();
  }
}

class ProfileComponent {
  constructor(private userService: UserService) {}
  
  async loadUser(id: number): void {
    const user = await this.userService.getUserInfo(id);
    // 编译时错误：Property 'fullName' does not exist on type 'User'
    // this.displayName(user.fullName); // ❌ 立即发现错误
    
    this.displayName(user.name); // ✅ 正确使用
  }
  
  private displayName(name: string): void {
    const element = document.getElementById('userName');
    if (element) {
      element.textContent = name;
    }
  }
}

---

4️⃣ 大型项目的可维护性

JavaScript项目的挑战

JavaScript
// 文件1: userService.js
function createUser(userData) {
  // 不知道userData应该包含什么字段
  return {
    id: generateId(),
    name: userData.name,
    email: userData.email,
    // 忘记了某些必需字段？
  };
}

// 文件2: userController.js  
function handleCreateUser(req, res) {
  const user = createUser(req.body);
  // 不知道createUser返回什么结构
  saveUser(user);
}

// 文件3: database.js
function saveUser(user) {
  // 不知道user对象的结构
  // 可能会因为缺少字段而失败
  return db.insert('users', user);
}

// 6个月后，其他开发者修改代码时：
// 1. 不知道函数期望什么参数
// 2. 不知道函数返回什么
// 3. 修改一个地方可能破坏其他地方
// 4. 需要大量文档和注释

TypeScript项目的清晰结构

TypeScript
// types/user.ts - 统一的类型定义
interface CreateUserRequest {
  name: string;
  email: string;
  password: string;
  age?: number;
}

interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
  updatedAt: Date;
}

interface UserRepository {
  save(user: User): Promise<User>;
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
}

// services/userService.ts
class UserService {
  constructor(private userRepo: UserRepository) {}
  
  async createUser(userData: CreateUserRequest): Promise<User> {
    // 类型系统确保所有必需字段都存在
    const user: User = {
      id: this.generateId(),
      name: userData.name,
      email: userData.email,
      createdAt: new Date(),
      updatedAt: new Date()
    };
    
    return this.userRepo.save(user);
  }
  
  private generateId(): string {
    return Math.random().toString(36).substr(2, 9);
  }
}

// controllers/userController.ts
class UserController {
  constructor(private userService: UserService) {}
  
  async handleCreateUser(req: Request, res: Response): Promise<void> {
    try {
      // 类型检查确保请求体结构正确
      const userData: CreateUserRequest = req.body;
      const user = await this.userService.createUser(userData);
      
      res.status(201).json(user);
    } catch (error) {
      res.status(400).json({ error: error.message });
    }
  }
}

// 优势：
// 1. 任何开发者都能立即理解代码结构
// 2. 修改接口时，所有相关代码都会显示编译错误
// 3. IDE提供完整的导航和重构支持
// 4. 自文档化，减少注释需求

---

5️⃣ 团队协作效率

JavaScript团队协作问题

JavaScript
// 开发者A写的代码
function processPayment(amount, currency, paymentMethod) {
  // 没有文档说明参数类型和格式
  // amount是数字还是字符串？
  // currency是"USD"还是"usd"还是数字代码？
  // paymentMethod是什么格式？
}

// 开发者B使用时只能猜测
processPayment("100.50", "usd", { type: "credit_card", number: "1234" });

// 开发者C又是另一种理解
processPayment(10050, "USD", "credit_card");

// 结果：运行时错误，调试困难，需要大量沟通

TypeScript团队协作优势

TypeScript
// 明确的接口定义作为团队契约
enum Currency {
  USD = "USD",
  EUR = "EUR",
  CNY = "CNY"
}

interface PaymentMethod {
  type: "credit_card" | "debit_card" | "paypal" | "bank_transfer";
  details: CreditCardDetails | PayPalDetails | BankDetails;
}

interface CreditCardDetails {
  number: string;
  expiryMonth: number;
  expiryYear: number;
  cvv: string;
}

interface PaymentResult {
  success: boolean;
  transactionId?: string;
  error?: string;
}

// 清晰的函数签名
async function processPayment(
  amount: number,           // 明确是数字，单位为分
  currency: Currency,       // 枚举确保有效值
  paymentMethod: PaymentMethod  // 结构化的支付方式
): Promise<PaymentResult> {
  // 实现细节...
}

// 所有团队成员都能正确使用
const result = await processPayment(
  10050,  // 100.50美元，以分为单位
  Currency.USD,
  {
    type: "credit_card",
    details: {
      number: "4111111111111111",
      expiryMonth: 12,
      expiryYear: 2025,
      cvv: "123"
    }
  }
);

// 优势：
// 1. 零歧义的API契约
// 2. IDE自动验证使用方式
// 3. 减少代码审查时间
// 4. 新团队成员快速上手

---

6️⃣ 现代开发工具集成

构建时优化

TypeScript
// TypeScript配置 (tsconfig.json)
{
  "compilerOptions": {
    "strict": true,           // 启用所有严格检查
    "noUnusedLocals": true,   // 检测未使用的变量
    "noUnusedParameters": true, // 检测未使用的参数
    "noImplicitReturns": true,  // 确保所有代码路径都有返回值
    "noFallthroughCasesInSwitch": true // 检测switch语句的fallthrough
  }
}

// 编译时发现的问题
function calculateDiscount(price: number, customerType: string): number {
  let discount = 0;
  
  switch (customerType) {
    case "premium":
      discount = 0.2;
      break;
    case "regular":
      discount = 0.1;
      // ❌ 编译错误：fallthrough case detected
    case "new":
      discount = 0.05;
      break;
  }
  
  // ❌ 编译错误：Not all code paths return a value
}

测试支持

TypeScript
// 类型安全的测试
interface MockUser {
  id: number;
  name: string;
  email: string;
}

// 测试工厂函数
function createMockUser(overrides: Partial<MockUser> = {}): MockUser {
  return {
    id: 1,
    name: "Test User",
    email: "test@example.com",
    ...overrides
  };
}

// 类型安全的Mock
const mockUserService: jest.Mocked<UserService> = {
  createUser: jest.fn(),
  getUserById: jest.fn(),
  updateUser: jest.fn(),
  deleteUser: jest.fn()
};

// 测试用例
describe("UserController", () => {
  it("should create user successfully", async () => {
    const mockUser = createMockUser({ name: "John Doe" });
    mockUserService.createUser.mockResolvedValue(mockUser);
    
    const result = await userController.createUser({
      name: "John Doe",
      email: "john@example.com",
      password: "password123"
    });
    
    expect(result).toEqual(mockUser);
    expect(mockUserService.createUser).toHaveBeenCalledWith({
      name: "John Doe",
      email: "john@example.com",
      password: "password123"
    });
  });
});

---

7️⃣ 性能和包大小优化

Tree Shaking优化

TypeScript
// utils/math.ts - 模块化的工具函数
export function add(a: number, b: number): number {
  return a + b;
}

export function subtract(a: number, b: number): number {
  return a - b;
}

export function multiply(a: number, b: number): number {
  return a * b;
}

export function divide(a: number, b: number): number {
  if (b === 0) throw new Error("Division by zero");
  return a / b;
}

// main.ts - 只导入需要的函数
import { add, multiply } from "./utils/math";

// TypeScript + 现代打包工具会自动移除未使用的subtract和divide函数
console.log(add(2, 3));
console.log(multiply(4, 5));

编译时优化

TypeScript
// 开发时的详细类型
interface DetailedUser {
  id: number;
  name: string;
  email: string;
  profile: {
    avatar: string;
    bio: string;
    preferences: {
      theme: "light" | "dark";
      language: string;
      notifications: boolean;
    };
  };
  metadata: {
    createdAt: Date;
    updatedAt: Date;
    lastLogin: Date;
  };
}

// 编译后的JavaScript是纯净的，没有类型信息
function processUser(user) {
  return {
    displayName: user.name,
    avatar: user.profile.avatar
  };
}

---

8️⃣ 实际项目对比

中型电商项目案例

JavaScript版本的问题

JavaScript
// 6个月后维护时遇到的实际问题

// 1. 不知道商品对象的结构
function calculatePrice(product, quantity, discountCode) {
  // product.price是数字还是字符串？
  // discountCode是什么格式？
  let price = product.price * quantity;
  
  if (discountCode) {
    // 不知道如何应用折扣
    price = applyDiscount(price, discountCode);
  }
  
  return price;
}

// 2. API响应结构不明确
fetch('/api/products')
  .then(res => res.json())
  .then(data => {
    // data是数组还是对象？
    // 有分页信息吗？
    data.forEach(product => {
      // product有什么属性？
      displayProduct(product);
    });
  });

// 3. 状态管理混乱
const cartState = {
  items: [],
  total: 0,
  // 还有什么属性？
};

function addToCart(productId, quantity) {
  // 需要查看所有相关代码才知道如何正确更新状态
}

TypeScript版本的清晰度

TypeScript
// 清晰的领域模型
interface Product {
  id: string;
  name: string;
  price: number; // 以分为单位
  category: ProductCategory;
  inventory: number;
  images: string[];
  description: string;
}

interface CartItem {
  productId: string;
  quantity: number;
  unitPrice: number;
  totalPrice: number;
}

interface CartState {
  items: CartItem[];
  subtotal: number;
  tax: number;
  shipping: number;
  total: number;
  discountCode?: string;
  discountAmount: number;
}

interface ApiResponse<T> {
  data: T;
  pagination?: {
    page: number;
    limit: number;
    total: number;
    hasNext: boolean;
  };
}

// 类型安全的业务逻辑
class PriceCalculator {
  static calculateItemPrice(
    product: Product, 
    quantity: number, 
    discountCode?: string
  ): number {
    let price = product.price * quantity;
    
    if (discountCode) {
      price = this.applyDiscount(price, discountCode);
    }
    
    return price;
  }
  
  private static applyDiscount(price: number, code: string): number {
    // 实现折扣逻辑
    return price;
  }
}

// 类型安全的API调用
class ProductService {
  async getProducts(): Promise<ApiResponse<Product[]>> {
    const response = await fetch('/api/products');
    return response.json();
  }
}

// 类型安全的状态管理
class CartManager {
  private state: CartState = {
    items: [],
    subtotal: 0,
    tax: 0,
    shipping: 0,
    total: 0,
    discountAmount: 0
  };
  
  addItem(product: Product, quantity: number): void {
    const existingItem = this.state.items.find(item => 
      item.productId === product.id
    );
    
    if (existingItem) {
      existingItem.quantity += quantity;
      existingItem.totalPrice = existingItem.unitPrice * existingItem.quantity;
    } else {
      this.state.items.push({
        productId: product.id,
        quantity,
        unitPrice: product.price,
        totalPrice: product.price * quantity
      });
    }
    
    this.recalculateTotal();
  }
  
  private recalculateTotal(): void {
    this.state.subtotal = this.state.items.reduce(
      (sum, item) => sum + item.totalPrice, 
      0
    );
    this.state.tax = this.state.subtotal * 0.08;
    this.state.total = this.state.subtotal + this.state.tax + this.state.shipping - this.state.discountAmount;
  }
}

---

📊 投资回报率分析

开发效率提升

TypeScript
// 统计数据（基于实际项目经验）

// 1. Bug减少率
// JavaScript项目：平均每1000行代码15-20个运行时错误
// TypeScript项目：平均每1000行代码3-5个运行时错误
// 减少率：70-80%

// 2. 开发时间
// 新功能开发：TypeScript初期慢10-15%，后期快20-30%
// Bug修复时间：TypeScript平均减少50%
// 代码审查时间：减少30-40%

// 3. 维护成本
// 6个月后的代码理解时间：减少60%
// 重构风险：减少80%
// 新团队成员上手时间：减少40%

实际成本对比

TypeScript
// 小型项目（<10k行代码）
// TypeScript额外成本：类型定义时间 +20%
// TypeScript收益：调试时间 -30%，维护时间 -25%
// 净收益：项目后期开始显现

// 中型项目（10k-50k行代码）  
// TypeScript额外成本：+15%
// TypeScript收益：-40%调试，-35%维护，-50%重构风险
// 净收益：3-6个月后显著

// 大型项目（>50k行代码）
// TypeScript额外成本：+10%
// TypeScript收益：-50%调试，-45%维护，-70%重构风险
// 净收益：立即显现，长期收益巨大

---

🎯 总结：何时使用TypeScript

强烈推荐使用的场景

TypeScript
// 1. 团队项目（>2人）
// 2. 长期维护项目（>6个月）
// 3. 复杂业务逻辑
// 4. 多模块/微服务架构
// 5. 需要高可靠性的项目
// 6. 有API集成的项目
// 7. 需要重构的遗留项目

interface ProjectRecommendation {
  teamSize: number;
  projectDuration: "short" | "medium" | "long";
  complexity: "low" | "medium" | "high";
  reliability: "normal" | "high" | "critical";
  recommendation: "optional" | "recommended" | "essential";
}

const scenarios: ProjectRecommendation[] = [
  {
    teamSize: 1,
    projectDuration: "short",
    complexity: "low",
    reliability: "normal",
    recommendation: "optional"
  },
  {
    teamSize: 3,
    projectDuration: "medium", 
    complexity: "medium",
    reliability: "high",
    recommendation: "recommended"
  },
  {
    teamSize: 5,
    projectDuration: "long",
    complexity: "high", 
    reliability: "critical",
    recommendation: "essential"
  }
];

可以考虑不用的场景

JavaScript
// 1. 快速原型/概念验证
// 2. 一次性脚本
// 3. 简单的静态网站
// 4. 学习JavaScript基础时
// 5. 非常小的项目（<1000行）
// 6. 团队完全没有TypeScript经验且时间紧迫

// 但即使这些场景，TypeScript的长期收益通常也值得投资

结论：TypeScript通过编译时类型检查，显著提高了代码质量、开发效率和项目可维护性。虽然有学习成本，但对于任何需要长期维护或团队协作的项目，TypeScript都是明智的选择。

参考网址：juejin.cn/post/751129…

根据文本内容定位

Page/Locator 对象的 get_by_text 方法

比如，

如果要获取 所有 文本内容包含 11 的元素，就可以这样

elements = page.get_by_text('11').all()

如果，你希望包含的内容是以 11 结尾的，就可以使用正则表达式对象 作为参数，如下

import re
elements = page.get_by_text(re.compile("11$")).all()

根据 元素 role 定位

web应用现在有一种标准 称之为： ARIA （Accessible Rich Internet Applications）。

ARIA 根据web界面元素的用途，为这些元素定义了一套 角色（ Role ） 信息，添加到页面中，

从而 让 残疾人士，或者 普通人在 某种环境下（比如夜里，太空中），不方便使用常规方法操作应用，使用辅助技术工具，来操作web应用的。

若想定位这个元素：

<div class="alert-message">
  您已成功注册，很快您将收到一封确认电子邮件
</div>

直接可以根据如下代码 定位该元素

# 根据 role 定位
lc = page.get_by_role('alert')

# 打印元素文本
print(lc.inner_text())

html元素中，有些 特定语义元素（semantic elements）被ARIA规范认定为自身就包含 ARIA role 信息，并不需要我们明显的加上 ARIA role 属性设置，

比如

<progress value="75" max="100">75 %</progress>

就等于隐含了如下信息

<progress value="75" max="100"
  role="progressbar"
  aria-valuenow="75"
  aria-valuemax="100">75 %</div>

所以，直接可以根据如下代码 定位该元素

# 根据 role 定位
lc = page.get_by_role('progressbar')

# 打印元素属性 value 的值
print(lc.get_attribute('value'))

再比如 search 类型的输入框，默认就有 searchbox role，

<input type="search">

ARIA Attribute

ARIA规范除了可以给元素添加 ARIA role ，还可以添加其它  ARIA属性（ARIA attributes） ，比如

<div role="heading" aria-level="1">白月黑羽标题1</div>
<div role="heading" aria-level="2">白月黑羽标题2</div>

aria-level 就是一个 ARIA 属性，表示 role 为 heading 时的 等级 信息

上面的定义，其实和下面的 html 元素 h1/h2 等价

<h1>白月黑羽标题1</h1>
<h2>白月黑羽标题2</h2>

上例中，h2 元素，隐含了 role="heading" aria-level="2" ， 所以可以用下面代码定位

lc = page.get_by_role('heading',level=2)
print(lc.inner_text())

Accessible Name

只根据 ARIA role 和 ARIA属性 往往并不能唯一定位元素。

role定位最常见的组合是 ARIA role 和 Accessible Name

因为，Accessible Name 就像元素的 名字 一样，往往可以唯一定位。

html 元素标准属性 name 是浏览器内部的，用户看不到，比如

Accessible Name 不一样，它是元素界面可见的文本名，

<a name='link2byhy' href="https://www.byhy.net">白月黑羽教程</a>

比如上面的元素，暗含的 Accessible Name 值就是 白月黑羽教程 ， 当然也暗含了 ARIA role 值为 link

所以，可以这样定位

lc = page.get_by_role('link',name='白月黑羽教程')
print(lc.click())

上面的写法， 只要 Accessible Name 包含 参数name 的字符串内容即可，而且大小写不分， 并不需要完全一致。

所以，这样也可以定位到

lc = page.get_by_role('link',name='白月黑羽')

如果你需要 Accessible Name 和 参数name 的内容完全一致，可以指定 exact=True ，如下

lc = page.get_by_role('link',name='白月黑羽', exact=True)

name值还可以通过正则表达式，进行较复杂的匹配规则，比如

lc = page.get_by_role('link',name=re.compile("^白月.*羽"))

我们这里说一些常见的：

<a> <td> <button> Accessible Name 值 就是其内部的文本内容。

<textarea> <input> 这些输入框，它们的 Accessible Name 值 是和他们关联的 的文本。

比如：

<label>
  <input type="checkbox" /> Subscribe
</label>

这个 checkbox 的 Accessible Name 却是 Subscribe

一些元素 比如 <img> ，它的 Accessible Name 是其html 属性 alt 的值

比如

<img src="grape.jpg" alt="banana"/>

role定位代码复杂，建议使用codegen代码助手来完成

CSS 学习笔记：彻底掌握 :nth-child(n) 伪类选择器

一、一句话定义（先锚定认知）

:nth-child(n) 是一个基于父元素子节点顺序的结构化伪类选择器，用于匹配：
“是其直接父元素的第 n 个子元素，且自身标签名（或类型）与选择器前缀一致” 的元素。
它不关心“这是第几个 <li>”，而只认“这是父元素的第几个孩子”。

---

二、语法全解：从简单到强大

1️ 基础形式（最常用）

写法	含义	示例
:nth-child(1)	第1个子元素	li:nth-child(1) → 列表第一个 <li>
:nth-child(odd)	所有奇数位子元素（1,3,5…）	tr:nth-child(odd) → 表格奇数行
:nth-child(even)	所有偶数位子元素（2,4,6…）	div:nth-child(even) → 偶数位 <div>

2️ 数学公式 an + b（万能通式）

• n 是从 0 开始的整数（n = 0, 1, 2, 3...）
• 计算结果 an + b 即为匹配的子元素位置（从 1 开始计数）

公式	展开（n=0,1,2,3…）	实际匹配位置	常见用途
2n	0, 2, 4, 6… → 忽略 0	2, 4, 6, 8…	等价于 even
2n+1	1, 3, 5, 7…	1, 3, 5, 7…	等价于 odd
3n+1	1, 4, 7, 10…	每隔 3 个选第 1 个	网格首列高亮
n+3	3, 4, 5, 6…	从第 3 个开始所有子元素	“跳过前两个”
-n+3	3, 2, 1, 0… → 0 及负数无效	1, 2, 3	前三个元素（黄金公式 ✅）

记忆口诀：

• even/odd → 看是否被 2 整除；
• n+X → 从第 X 个起全部；
• -n+X → 前 X 个；
• an+b → 代入 n=0,1,2… 算出有效正整数即可。

---

三、核心机制（必读！90% 错误源于此）

正确逻辑（三步判定）

对页面中每一个目标元素（如每个 <li>），浏览器执行：

1. 定位父元素 → 找到它的 parentNode（直接父容器）；
2. 计算位置 → 查看它在父元素的 children 列表中是第几个（从 1 开始计数，只算元素节点，忽略纯文本/注释）；
3. 双重校验 → ① 位置符合 an+b 公式；② 元素类型与选择器前缀一致（如 li 必须是 <li> 标签）→ 两者都满足才匹配。

常见误解（红色警报！）

误解	为什么错	正确做法
“:nth-child(3) 就是第三个 <li>”	❌ 它找的是“第3个子元素”，不是“第3个 <li>”	✅ 改用 li:nth-of-type(3)
“父元素没写，就找不到父”	❌ 每个元素天然有父节点（<body> 或其他），无需显式声明	✅ li:nth-child(odd) 会自动作用于所有 <li>，各自找爹
“隐藏元素（display:none）不参与计数”	❌ :nth-child 基于 DOM 结构，与渲染无关	✅ 隐藏元素仍占位置；若需“视觉上第n个”，需 JS
“空白换行会影响序号”	⚠️ 现代浏览器已优化：只计算元素节点（Element Nodes），忽略纯空白文本节点	✅ 安心写格式化 HTML，无需压缩成一行

---

四、实战对比：:nth-child() vs :nth-of-type()

维度	:nth-child(n)	:nth-of-type(n)
判定依据	元素在其父元素中的总子元素序号	元素在其父元素中同类型元素的序号
是否跨类型计数	✅ 是（<h2>, <p>, <div> 全部计入）	❌ 否（只数 <p>，忽略 <h2>）
HTML 示例	<ul><h2>T</h2><p>A</p><span>S</span><p>B</p></ul>	同上
p:nth-child(2)	✅ 匹配 <p>A</p>（它是第2个子元素）	—
p:nth-child(4)	✅ 匹配 <p>B</p>（它是第4个子元素）	—
p:nth-of-type(1)	—	✅ 匹配 <p>A</p>（第一个 <p>）
p:nth-of-type(2)	—	✅ 匹配 <p>B</p>（第二个 <p>）
何时选用	需要“按物理位置布局”（如表格隔行、网格首行）	需要“按标签语义筛选”（如第3个段落、最后2个列表项）

快速决策树：
你想选「排第几的元素」→ :nth-child()
你想选「第几个同类元素」→ :nth-of-type()

---

五、无父类选择器的真实含义（深度澄清）

li:nth-child(odd) { background: #eee; }

它不是“没有父”，而是“不限定父”

• 浏览器会为每个 <li> 独立执行：
  当前<li>.parentNode.children → 找到它在其中的索引 → 判断是否为奇数 → 是则应用样式。
• 因此，它可能同时作用于：
  • <ul> 下的 <li>
  • <ol> 下的 <li>
  • <nav> 中的 <li>（语义化导航）
  • 甚至 <section> 直接子级的 <li>（HTML5 允许）

为什么可以这样写？

• CSS 是全局作用域，选择器描述的是“满足条件的元素集合”，不强制绑定父容器；
• 这种写法简洁高效，适合通用样式（如所有列表隔行变色）；
• ⚠️ 但大型项目中建议增加命名空间约束以防冲突：

/* 推荐：模块化限定 */
.product-list li:nth-child(odd) { ... }
.nav-menu li:nth-child(odd)   { ... }

/* 不推荐：全局污染风险 */
li:nth-child(odd) { ... } /* 可能意外影响第三方组件 */

---

六、经典应用场景（附可复制代码）

场景 1：表格隔行变色（最稳方案）

<table>
  <tr><td>张三</td><td>85</td></tr>
  <tr><td>李四</td><td>92</td></tr>
  <tr><td>王五</td><td>78</td></tr>
</table>

/*  推荐：用 :nth-child，不受 thead/tfoot 干扰 */
table tr:nth-child(even) { background: #f9f9f9; }
table tr:nth-child(odd)  { background: #fff; }

场景 2：网格布局首行加粗

<div class="grid">
  <div>1</div><div>2</div><div>3</div>
  <div>4</div><div>5</div><div>6</div>
</div>

/* 每行3列 → 首行：1,2,3 → 位置 1,2,3 → 用 -n+3 */
.grid div:nth-child(-n+3) { font-weight: bold; }

场景 3：导航菜单仅第1、3、5项有下划线

.nav-link:nth-child(2n+1) { border-bottom: 2px solid blue; }

---

七、调试技巧（开发必备）

方法	操作	作用
浏览器开发者工具	在 Elements 面板选中 <li> → 右侧 Styles 查看是否生效 → 展开父节点数子元素	✅ 验证实际位置
Console 快速验证	输入 document.querySelector('li:nth-child(2)')	✅ 返回匹配的第一个元素
临时高亮所有匹配项	*:nth-child(odd) { outline: 2px solid red !important; }	✅ 可视化所有奇数位子元素（慎用）

---

八、兼容性与注意事项

项目	说明
✅ 浏览器支持	Chrome 4+ / Firefox 3.5+ / Safari 3.1+ / Edge 12+ / IE9+（IE8及以下不支持）
⚠️ 服务端渲染（SSR）注意	若 HTML 由服务端生成，确保结构与客户端一致，否则样式错位
🚫 不能做的事	• 无法基于内容（如文字包含“重要”）筛选• 无法选择“倒数第2个可见元素”（需 JS）• 无法跨父元素计数（如“整个页面第5个 <li>”）

---

附录：速查记忆卡（打印/收藏版）

目标	写法	备注
第1个元素	:nth-child(1)	最简写法
奇数位	:nth-child(odd) 或 :nth-child(2n+1)	二选一
偶数位	:nth-child(even) 或 :nth-child(2n)	二选一
前3个	:nth-child(-n+3)	✅ 黄金公式
从第4个起所有	:nth-child(n+4)	✅ 黄金公式
每4个选第3个	:nth-child(4n+3)	如 3,7,11,15…
仅最后一个	:nth-last-child(1)	倒序计数

---

最后送你一句心法：

:nth-child() 不是“找第几个 <p>”，而是“站在父元素门口，点名叫第n个进门的孩子——还得确认他是不是你要找的那位”。
理解了这个画面，你就永远不会再写错。

lib-flexible设置根字号

npm i lib-flexible
//然后在mian.js中引入

uno.config.js设置

根目录创建uno.config.js文件，需要安装 npm i @unocss/preset-rem-to-px

import { defineConfig, presetWind3 } from 'unocss'
import presetRemToPx from '@unocss/preset-rem-to-px'
export default defineConfig({
    presets: [
        presetWind3(),  //预设样式
        presetRemToPx()  // 重点，把预设的rem转成px，这样postCssPxToRem就可以转了 例如预设样式 text-base的font-size:1rem;经过转换变成16px，在经过postCssPxToRem转换成rem
    ]
})

这个是vite的配置

import postCssPxToRem from 'postcss-pxtorem'
import UnoCSS from 'unocss/vite'

export default defineConfig({
    plugins: [
        UnoCSS(),
    ],
    css: {
        postcss: {
            plugins: [
                postCssPxToRem({
                  rootValue: 37.5,
                  unitPrecision: 6,
                  minPixelValue: 1,
                  propList: ['*'],
                  mediaQuery: false,
                })
            ]
        }
    }
)}

其他的按照vant文档正常使用就好了

一个程序员2004年的决定，如何悄悄改变了整个互联网？

想象一下：

你正在写一份工作报告，想给标题加个粗体，或者插入一个网址链接。

在传统的 Word 文档里，你需要花几分钟时间找各种按钮、菜单，偶尔还会因为误操作把整页格式搞乱。

现在，你只需要输入 # 标题 就能得到大标题，输入 **粗体文字** 就能得到粗体，输入 [点击这里](网址) 就能得到一个可点击的链接。

简单、直接、高效，就像发微信一样自然。

这就是 Markdown。

本篇和你讲讲 Markdown 背后的故事，以及为什么它能成功到风靡全球，以及它的故事对我们的启示。

1. 一个决定

故事要从 2004 年说起。

那时的互联网还很“原始"”，如果想在网页上发布一篇文章，你必须学习一门叫 HTML 的语言。

想象一下，每次写文章都要像这样编码：

<h1>我的文章标题</h1><p>这是一段<strong>重要</strong>的文字，包含一个<a href="链接地址">链接</a>。</p>

这就像是想给朋友写封信，却必须先学会用摩斯密码一样荒谬。

就在这时，一个叫约翰·格鲁伯的程序员做了一个大胆的决定：创造一种“反HTML”的格式。

HTML是“标记语言”，那他就创造一种“反标记语言”——Markdown。

约翰的想法很简单：为什么不能让写文章就像写普通邮件一样简单？

2. 意外传播

约翰发布 Markdown 时，并没有想到它会成为互联网的基础设施。

他只是厌倦了复杂的 HTML 语法，想为自己和朋友提供一个更简单的选择。

但接下来发生的事情连约翰自己都没想到：

• 2004 年：Markdown 悄悄诞生

• 2005-2010 年：程序员们开始用 Markdown 写技术文档

• 2010-2015 年：各大平台开始支持 Markdown 格式

• 2015-2020 年：笔记软件、协作工具全面拥抱 Markdown

• 2020 年至今：连苹果的 Notes 都支持 Markdown 了

这就像你发明了一种新的记账方法，结果全世界的企业都跟着用了。

3. Markdown 成功的十个原因

所以为什么 Markdown 能在众多技术中脱颖而出呢？

让我们看看它的成功秘密：

1. 绝妙的名字

“Markdown”这个名字很好！懂技术的人一眼就知道它是“反 Markup”，普通人听起来也简单好记。

2. 解决了真实痛点

不是所有新技术都解决了实际问题，但 Markdown 确实让无数人从 HTML 的折磨中解脱了出来。

3. 顺应了用户习惯

Markdown 的语法基于人们已经在邮件和文档中形成的习惯。比如用 * 表示强调，用 # 表示标题等。

4. 找到了最佳时机

2004 年正值博客爆发期，人们正在寻找更好的写作工具。Markdown 正好撞上了这个风口。

5. 开放包容的社区

从一开始，Markdown 就有一个开放的社区。

各种版本出现：GitHub 版本、通用版本、扩展版本...但核心依然保持一致。

6. 极简主义的设计哲学

保持简单，而不是追求复杂。 这是很多成功技术的共同特点。

7. 技术人员的推动

程序员们是早期使用者，他们发现了 Markdown 的价值并大力推广，形成了滚雪球效应。

8. 可读性强

即使不懂 Markdown 语法的人，看到 .md 文件也能大概猜出意思。这种“自我解释”的能力很珍贵。

9. 跨平台兼容

Markdown 文件在任何设备、任何系统上都能正常显示和编辑。不怕软件更新，不怕系统迁移。

10. 零专利壁垒

最重要的是，约翰·格鲁伯没有为 Markdown 申请专利。这意味着任何人都可以自由使用它。

4. 带给我们什么启发？

Markdown 的故事不仅仅是一个技术成功的案例，它还给我们很多启发：

4.1. 简单比复杂更有力量

在这个喜欢把简单事情搞复杂的世界里，Markdown 证明了“less is more”的智慧。

4.2. 从解决实际问题出发

不是为了技术而技术，而是为了解决人们的实际问题。Markdown 的成功源于它真的让写作变得更简单。

4.3. 长期主义的重要性

从 2004 年到今天，Markdown 已经存在了20年。它没有一夜爆红，而是慢慢渗透，最终无处不在。

5. 最后

不是每个人都需要发明影响世界的技术，但每个人都可以创造一些让世界变得更美好的小东西。

关键在于：观察人们真正的问题，提出简单的解决方案，然后分享给世界。

或许这就是 Markdown 的故事给我们的最珍贵的礼物。

我是冴羽，10 年笔耕不辍，专注前端领域，更新了 10+ 系列、300+ 篇原创技术文章，翻译过 Svelte、Solid.js、TypeScript 文档，著有小册《Next.js 开发指南》、《Svelte 开发指南》、《Astro 实战指南》。

欢迎围观我的“网页版朋友圈”，关注我的公众号：冴羽（或搜索 yayujs） ，每天分享前端知识、AI 干货。

Mockjs

Mock.js 是一款模拟数据生成器

官网：mockjs.com

安装

前提安装好node环境

1. 在命令提示符窗口，使用npm安装

# 初始化项目
npm init -y
# 安装
npm install mockjs

安装成功显示

2. 创建文件 demo1.js

   const Mock = require('mockjs') // 这个是引用库
    
   const data = Mock.mock({
     // 生成对象个数是 3
     'items|3': [{
       'id|+1': 1,       // 自增涨id
       'name': '@cname', // 生成随机名字
     'age|1-100':1,    // 年龄（1-100之间随机数）
   'img':'@image',   // 图片
   'ip':'@ip',       // ip
   'email':'@email', // 邮箱
   'salary|10-100.1-2':1,    // 工资 - （10-100，小数位1到3位的随机数）例子：13.23
   'status':'@boolean',      // 状态 布尔值
   'title':'@ctitle(10,20)', // 标题 (生成字数10到20之间)
   'idCard':/\d{15}|\d{18}/, // 身份证号（正则表达式）
   'address':'@county(try)', // 地址  zip 邮编
   'birthday':'@date("yyyy-MM-dd")',  // 生日日期  ("可以指定日期格式")
   'url':'@url("http","goodyan.cn")', // url地址
   'phone|11':'@integer(0,9)',        // 手机号
   'money':'@float(0,10,1,3)',        // 钱（0-10小数  1-3位小数位）
       'pay|1':['a','b','c','d'],         // 类型（4选一，随机选其中一个）
   'son|2':{
   id:1,name:'abc'       // 对象里包含对象 2 随机抽取2个属性
   }
     }]
   })
   
   // 输出
   console.log(JSON.stringify(data));
   

   3. 运行脚本

   node demo1.js
   

   可以得到一些json字符串，模拟数据。

EasyMock

Easy Mock 是一个可视化，并且能快速生成模拟数据的持久化服务。

官方地址：easy-mock.com

源码地址：github.com/easy-mock/e…

一般我们可以部署在本地，安装前提：

需要成功安装了 Node.js（v8.x, 不支持 v10.x）& MongoDB（>= v3.4）& Redis（>= v4.0）。

安装步骤在github源码地址里有，这里不再介绍。

我们如果选择在线模式：

可以选择第三方fastmock提供服务平台

地址：www.fastmock.site/#/

如何使用

1. 创建项目

2. 创建查询接口

   

3. 创建新增接口

   

4. 进行保存

   

5. 进行测试

   

这样我们前端可以访问测试地址，得到模拟数据。

在 React 项目开发中，幻灯片（轮播图）和返回顶部是两个高频出现的功能组件。本文基于实际开发代码，深入解析使用 shadcn 组件库、Embla Carousel 插件及原生 React API 实现这两个组件的全过程，涵盖组件设计、类型约束、性能优化、事件处理等核心知识点，旨在梳理技术逻辑，夯实 React + TypeScript 开发基础。

本文涉及的代码包含三个核心部分：幻灯片组件（SlideShow）、返回顶部组件（BackToTop）、节流工具函数（throttle），以及组件在首页（Home）的集成使用。下文将逐模块拆解分析，结合 React 原理和 TypeScript 特性，拆解技术细节与实践要点。

一、前期准备与技术栈说明

1.1 核心技术栈

• React：核心前端框架，采用函数式组件+Hooks 模式开发，实现组件的状态管理、生命周期控制与 DOM 交互。
• TypeScript：为 JavaScript 提供静态类型检查，定义组件属性（Props）、状态（State）及工具函数的类型，提升代码可维护性与健壮性。
• shadcn：轻量级 UI 组件库，提供封装完善的基础组件（如 Carousel 轮播组件），具备高性能、高定制性的特点，减少重复开发成本。
• Embla Carousel：轻量级轮播核心库，通过插件化机制扩展功能（如自动播放），与 shadcn 的 Carousel 组件适配性良好。
• Lucide React：图标库，提供简洁的矢量图标（如返回顶部的 ArrowUp 图标），适配 React 组件开发。

1.2 核心工具函数：节流函数（throttle）

在滚动事件、 resize 事件等高频触发场景中，直接执行回调函数会导致页面性能下降（如频繁重排重绘）。节流函数的作用是限制函数在一定时间内只能执行一次，降低事件触发频率，优化性能。

1.2.1 函数实现与类型定义

type ThrottleFunction = (...args: any[]) => void;

export function throttle(fun: ThrottleFunction, delay: number): ThrottleFunction {
  let last: number | undefined;
  let deferTimer: NodeJS.Timeout | undefined;

  return function (...args: any[]) {
    const now = +new Date();

    if (last && now < last + delay) {
      clearTimeout(deferTimer);
      deferTimer = setTimeout(function () {
        last = now;
        fun(...args);
      }, delay);
    } else {
      last = now;
      fun(...args);
    }
  };
}

1.2.2 核心逻辑解析

该节流函数采用“时间戳+定时器”结合的实现方式，兼顾即时响应与延迟执行，避免了纯时间戳或纯定时器方案的缺陷：

• 变量定义：

  • last：存储上一次函数执行的时间戳，初始值为 undefined；
  • deferTimer：存储定时器实例，用于延迟执行函数，避免高频触发时完全屏蔽函数执行。

• 执行逻辑：

  • 获取当前时间戳 now，判断距离上一次执行时间是否小于设定延迟 delay；
  • 若时间间隔不足：清除现有定时器，重新设置定时器，确保在延迟结束后执行一次函数（避免错过最后一次触发）；
  • 若时间间隔充足：直接执行函数，并更新 last 为当前时间戳，保证即时响应首次触发或间隔足够的触发。

• 类型约束：通过 ThrottleFunction 类型别名，定义节流函数的入参和返回值均为“接收任意参数、无返回值”的函数，确保类型一致性。

1.2.3 应用场景

该函数主要用于处理高频触发事件，本文中用于 BackToTop 组件的滚动事件监听，限制滚动事件回调函数的执行频率（每 200ms 最多执行一次），避免因滚动触发过多函数调用导致页面卡顿。

二、幻灯片组件（SlideShow）深度解析

幻灯片组件是页面展示的核心组件之一，需实现轮播展示、自动播放、鼠标交互、指示点联动等功能。本文基于 shadcn 的 Carousel 组件封装，结合 Embla Carousel 的 AutoPlay 插件，实现高性能、高定制性的轮播效果。

2.1 组件结构与依赖引入

2.1.1 依赖引入说明

import{
    useRef, // 持久化存储对象，dom对象的引用
    useState,
    useEffect,
} from 'react';
// 第三方库
import AutoPlay from 'embla-carousel-autoplay'; // 自动播放组件
// 引入carousel组件,用它来实现轮播图功能“旋转木马”
import {
    Carousel,
    CarouselContent,
    CarouselItem,
    type CarouselApi,
} from '@/components//ui/carousel';

// 类型定义
export interface SlideData { // 轮播图数据项
    id: number | string; // 联合类型
    image: string;
    title?: string;
}

interface SlideShowProps { // 轮播图组件属性
    slides: SlideData[]; // 轮播图数据项数组
    autoPlay?: boolean; // 是否自动播放
    autoPlayDelay?: number; // 自动播放间隔时间
}

2.1.2 核心依赖解析

• React Hooks：

  • useState：管理组件状态（当前选中索引 selectedIndex、轮播图 API 实例 api）；
  • useEffect：处理副作用（事件监听、组件卸载清理）；
  • useRef：持久化存储 AutoPlay 插件实例，避免组件重渲染时重复创建实例，优化性能。

• Embla Carousel 插件：AutoPlay 为轮播图提供自动播放功能，支持配置播放延迟、交互停止等参数。

• shadcn 组件：

  • Carousel：轮播图容器组件，提供核心轮播逻辑、API 暴露、插件集成等功能；
  • CarouselContent：轮播内容容器，用于包裹轮播项，控制轮播的滚动区域；
  • CarouselItem：单个轮播项组件，对应每一张幻灯片；
  • CarouselApi：轮播图 API 类型，定义轮播图实例的方法和属性，用于类型约束。

2.1.3 类型定义解析

• SlideData：定义单张幻灯片的数据结构，包含：

  • id：联合类型（number | string），作为轮播项的唯一标识，用于 key 属性；
  • image：字符串类型，存储幻灯片图片地址，为必传字段；
  • title：可选字符串类型，存储幻灯片标题，用于图片 alt 属性和底部文案展示。

• SlideShowProps：定义幻灯片组件的属性，包含：

  • slides：SlideData[] 类型，轮播图数据数组，为必传字段；
  • autoPlay：可选布尔类型，控制是否开启自动播放，默认值为 true；
  • autoPlayDelay：可选数字类型，自动播放间隔时间（单位：毫秒），默认值为 3000。

2.2 组件状态与副作用处理

2.2.1 状态管理

const SlideShow:React.FC<SlideShowProps> = ({
    slides,
    autoPlay = true,
    autoPlayDelay = 3000,
}) => {
    const [selectedIndex,setSelectedIndex] = useState<number>(0); // 当前选中的索引
    const [api,setApi] = useState<CarouselApi | null>(null); // 轮播图API实例

    // ... 副作用与业务逻辑
}

• selectedIndex：存储当前选中的幻灯片索引，初始值为 0，用于控制指示点的激活状态，实现索引与指示点的联动。
• api：存储 Carousel 组件的 API 实例，初始值为 null。通过 setApi 接收组件暴露的实例，进而调用实例方法（如监听事件、获取选中索引）。

2.2.2 副作用处理（useEffect）

useEffect(()=>{
    if(!api) return;
    const onSelect = () => setSelectedIndex(api.selectedScrollSnap());
    api.on('select',onSelect);
    // 组件卸载时移除事件监听
    return () => {
        api.off('select',onSelect);
    }
},[api])

该 useEffect 用于监听轮播图的选中状态变化，核心逻辑如下：

• 依赖项：仅依赖 api，当api 从 null 变为有效实例时，执行副作用逻辑。

• 事件监听：

  • 定义 onSelect 回调函数，通过 api.selectedScrollSnap() 获取当前选中的轮播项索引，并更新 selectedIndex 状态；
  • 调用 api.on('select', onSelect) 监听轮播图的 select 事件（当轮播项切换时触发）。

• 组件卸载清理：返回清理函数，调用 api.off('select', onSelect) 移除事件监听，避免组件卸载后仍存在事件绑定，导致内存泄漏。

2.2.3 插件实例优化（useRef）

// AutoPlay 比较耗性能 用 ref 存储插件实例，避免每次渲染都创建新实例
const plugin = useRef(
    autoPlay?AutoPlay({delay:autoPlayDelay,stopOnInteraction:true}):null
)

这是组件性能优化的关键知识点，核心原因与逻辑如下：

• 性能问题根源：AutoPlay 插件实例创建是耗时操作，若直接在组件渲染阶段创建，每次组件重渲染（如父组件传递的 props 变化、自身状态更新）都会重新创建实例，导致性能浪费。

• useRef 的作用：useRef 存储的对象在组件整个生命周期内保持不变，不会因组件重渲染而重新创建。通过 useRef 存储 AutoPlay 实例，确保仅在组件初始化时创建一次实例，后续重渲染复用该实例。

• AutoPlay 配置参数：

  • delay：自动播放间隔时间，对应组件的 autoPlayDelay 属性；
  • stopOnInteraction：布尔值，设置为 true 时，当用户与轮播图交互（如点击、滑动）后，自动播放停止，提升用户体验。

2.3 组件渲染与交互逻辑

2.3.1 核心组件结构

return(
    <Carousel
        className='w-full'
        setApi={setApi} // 轮播图实例赋值
        plugins={plugin.current ? [plugin.current] : []}
        opts={{loop:true}} // 循环播放
        onMouseEnter={()=>plugin.current?.stop()} // 鼠标进入暂停播放
        onMouseLeave={()=>plugin.current?.play()} // 鼠标离开继续播放
        >
            <CarouselContent>
                {
                    slides.map(({id,image,title},index)=>(
                        <CarouselItem key={id} className='w-full'>
                        <img src={-full object-cover' />
                            {
                                title && (
                                    {title}
                                )
                            }
                        </CarouselItem>
                    ))
                }
            </CarouselContent>
        </Carousel>
        {/* 指示点 */}
        
            {
                slides.map((_,i) => (
                    <button key -2 w-2 rounded-full transition-all ${selectedIndex === i ? 'bg-white w-6' : 'bg-white/50'}`}/>
                ))
            }
        
)

2.3.2 Carousel 组件核心属性解析

• setApi={setApi}：将 setApi 传递给 Carousel 组件，当轮播图实例初始化完成后，通过该函数将实例赋值给组件的 api 状态，便于后续调用实例方法。
• plugins={plugin.current ? [plugin.current] : []}：传递 AutoPlay 插件实例，若 autoPlay 为 true，则加载插件实现自动播放；否则传递空数组，不启用自动播放。
• opts={{loop:true}}：配置轮播图为循环播放模式，当轮播到最后一张时，自动切换到第一张，形成闭环。
• onMouseEnter / onMouseLeave：鼠标交互事件，实现“鼠标进入暂停自动播放、鼠标离开恢复自动播放”的交互逻辑，通过调用 AutoPlay 插件的 stop() 和 play() 方法实现。

2.3.3 轮播项（CarouselItem）渲染逻辑

每张轮播项包含图片、标题（可选）及样式优化，核心细节如下：

• 布局样式：

  • aspect-[16/9]：固定轮播图宽高比为 16:9，适配大多数场景的展示需求；
  • rounded-xl：设置圆角，提升视觉效果；
  • overflow-hidden：隐藏图片超出容器的部分，避免图片变形。

• 图片优化：object-cover 确保图片按比例填充容器，同时裁剪超出部分，保证图片展示完整且不变形；alt 属性设置默认值（slide ${index + 1}），提升可访问性。

• 标题展示与渐变背景应用：仅当 title 存在时渲染标题容器，核心采用 CSS 线性渐变（linear-gradient）实现背景遮罩，具体为 bg-gradient-to-t from-black/60 to-transparent。该写法指定渐变方向为“从下到上”（to-t），起始颜色为黑色并设置 60% 透明度（from-black/60），结束颜色为完全透明（to-transparent）。这种渐变背景相比纯色半透明遮罩（如 bg-black/60），视觉上更自然，能让标题与图片背景平滑融合，同时避免遮挡图片主体内容。更重要的是，渐变背景无需加载任何图片资源，彻底消除了图片背景带来的 HTTP 下载开销和并发数占用问题，尤其在轮播图这类多元素场景中，能显著优化页面加载性能。同时，标题文字设置 text-lg font-bold 样式，确保在渐变背景上具备足够的可读性。

2.3.4 指示点（Indicator）实现

指示点用于展示当前轮播位置及切换轮播项，核心逻辑如下：

• 布局：通过 absolute 定位在轮播图底部中央，flex 布局实现指示点横向排列，gap-2 设置指示点间距。
• 动态渲染：根据 slides 数组长度循环生成指示点，无需手动编写固定数量的指示点，适配动态数据。
• 动态类名与 transition-all 过渡：通过 selectedIndex === i 判断当前指示点是否为激活状态，动态切换类名实现样式变化，而 transition-all 属性则为这些变化提供平滑过渡效果。具体来说，激活状态下指示点的宽度从 2px 变为 6px、背景色从 bg-white/50（半透明白色）变为 bg-white（纯白色），这两个属性的变化都会被 transition-all 捕获，生成连贯的过渡动画。若不添加 transition-all，状态切换会瞬间完成，视觉上显得生硬，影响用户体验。此外，transition-all 无需指定具体过渡属性，简化了代码维护成本，即便后续新增样式变化（如透明度调整），也无需额外修改过渡相关代码，兼容性和扩展性更强。
• 可优化点：当前指示点仅用于展示位置，未实现点击切换功能。可添加 onClick 事件，调用 api.scrollTo(i) 方法，实现点击指示点切换到对应轮播项的功能。

2.4 性能优化与最佳实践

2.4.1 图片性能优化

代码中采用图片作为背景展示，虽能满足视觉需求，但存在 HTTP 下载开销。可进一步优化：

• 渐变色替代图片（核心优化方案） ：若无需展示具体图片内容，优先使用 CSS 线性渐变（linear-gradient）作为背景，完全消除图片的 HTTP 下载开销。线性渐变支持多色过渡、方向控制、透明度调节，能满足大多数装饰性背景需求。例如用 bg-gradient-to-r from-blue-500 to-purple-600 实现水平蓝紫渐变，用 bg-gradient-to-br from-teal-400 via-green-300 to-yellow-200 实现对角线多色渐变。相比图片背景，渐变背景有三大性能优势：一是无网络请求，减少 HTTP 并发数，避免阻塞关键资源加载；二是渲染高效，由浏览器本地计算生成，无需解析图片文件；三是适配性强，可随容器尺寸自适应拉伸，不会出现图片变形或模糊问题。
• 图片懒加载：结合 React 懒加载库（如 react-lazyload）或原生 loading="lazy" 属性，实现图片懒加载，仅当轮播项进入视口时才加载图片，减少首屏加载时间。
• 图片压缩与格式优化：使用 WebP 格式图片，结合图片压缩工具（如 TinyPNG）减小图片体积，提升加载速度。
• 图片懒加载：结合 React 懒加载库（如 react-lazyload）或原生 loading="lazy" 属性，实现图片懒加载，仅当轮播项进入视口时才加载图片，减少首屏加载时间。
• 图片压缩与格式优化：使用 WebP 格式图片，结合图片压缩工具（如 TinyPNG）减小图片体积，提升加载速度。

2.4.2 组件性能优化

• useRef 复用插件实例：如前文所述，避免组件重渲染时重复创建 AutoPlay 实例，减少性能消耗。
• 事件监听清理：在 useEffect 中返回清理函数，移除事件监听，避免内存泄漏。
• 条件渲染优化：标题容器仅在 title 存在时渲染，避免无用 DOM 节点生成。

2.4.3 样式优化

• transition-all 特性深度解析：transition-all 是 CSS 过渡属性的简化写法，作用于元素的所有可过渡属性（如宽度、背景色、透明度、位置等），无需逐个指定属性名。在轮播图指示点中，通过该属性让激活状态下的宽度变化（从 2px 到 6px）和背景色变化（从半透明白色到纯白色）形成平滑过渡，避免状态切换时出现生硬的跳变效果，提升用户视觉体验。其核心优势在于简化代码，同时确保元素所有样式变化都能获得统一的过渡效果，尤其适合动态类名切换样式的场景。需要注意的是，过渡效果的时长和曲线可通过 transition-duration 和 transition-timing-function 补充配置，默认时长为 0.3s，曲线为 ease（慢进慢出），可根据需求调整为 linear（匀速）等。
• gradient 线性渐变与性能优化：CSS 线性渐变（linear-gradient）通过代码生成渐变背景，无需依赖图片资源，是替代图片背景的优质方案。在幻灯片标题容器中，bg-gradient-to-t from-black/60 to-transparent 就是典型的线性渐变应用，从底部的黑色半透明（from-black/60）向上渐变至透明（to-transparent），既实现了遮罩效果突出标题，又无需加载额外的半透明遮罩图片。从性能角度看，图片背景会产生 HTTP 下载开销，不仅增加页面加载时间，还会占用 HTTP 并发连接数（浏览器对同一域名的并发请求数有上限，通常为 6 个），过多图片请求会阻塞其他关键资源（如脚本、核心样式）的加载；而线性渐变由浏览器本地渲染，无任何网络开销，能显著减少并发请求数，提升页面加载性能和渲染速度。实际开发中，若无需展示具体图片内容，可直接用渐变背景替代，例如用 bg-gradient-to-r from-blue-500 to-purple-600 实现蓝紫渐变背景，兼顾视觉效果与性能。

三、返回顶部组件（BackToTop）解析

返回顶部组件是提升用户体验的常用组件，当页面滚动超过一定距离时显示，点击后平滑滚动到页面顶部。本文结合节流函数和 React Hooks，实现高性能、可配置的返回顶部功能。

3.1 组件结构与类型定义

import React,{
    useEffect,
    useState
} from "react";
import { Button } from "./ui/button";
import { ArrowUp } from "lucide-react"; // 引入返回顶部图标
import { throttle } from "../utils"; // 引入节流函数

interface BackToTopProps {
    // 滚动超过多少像素后显示按钮
    threshold?: number;
}

const BackToTop: React.FC<BackToTopProps> = ({threshold = 400}) => {
    const [isVisible, setIsVisible] = useState<boolean>(false);
    
    // ... 业务逻辑与渲染
}

3.1.1 类型定义解析

BackToTopProps 定义组件的可选属性 threshold，表示“页面滚动超过多少像素后显示返回顶部按钮”，默认值为 400，支持父组件自定义配置，提升组件复用性。

3.1.2 状态管理

isVisible：布尔类型状态，控制返回顶部按钮的显示/隐藏，初始值为 false（页面加载时不显示）。

3.2 核心功能实现

3.2.1 平滑滚动到顶部函数

const scrollTop = () => {
    // window.scrollTo 方法会让页面滚动到顶部
    window.scrollTo({
        top: 0,
        behavior: 'smooth' // 平滑滚动
    })
}

核心 API 解析：

• window.scrollTo()：用于设置页面滚动位置的原生 API，支持两种参数形式：

  • 参数为两个数字：window.scrollTo(x, y)，分别表示水平和垂直滚动位置；
  • 参数为对象：支持配置 top（垂直滚动位置）、left（水平滚动位置）、behavior（滚动行为）。

• behavior: 'smooth'：设置滚动行为为平滑滚动，相比默认的瞬间滚动，用户体验更友好。若需兼容低版本浏览器（如 IE），可引入 smoothscroll-polyfill 插件。

3.2.2 滚动事件监听与节流处理

useEffect(()=>{
    const toggleVisibility = () => {
        setIsVisible(window.scrollY > threshold);
    }
    const throttled_func = throttle(toggleVisibility, 200);
    window.addEventListener('scroll',throttled_func); // 监听滚动事件
    // 组件卸载时移除事件监听(监听事件和处理函数都要移除，否则会导致内存泄漏)
    return () => {
        window.removeEventListener('scroll',throttled_func);
    }
},[threshold])

核心逻辑解析：

• 滚动状态判断：toggleVisibility 函数通过 window.scrollY 获取当前页面垂直滚动距离，与 threshold 比较，更新 isVisible 状态（滚动距离超过阈值则显示按钮，否则隐藏）。

• 节流优化：通过 throttle(toggleVisibility, 200) 生成节流后的函数，限制 toggleVisibility 每 200ms 最多执行一次，避免滚动事件高频触发导致页面卡顿。

• 事件监听与清理：

  • 组件挂载时，为 window 添加滚动事件监听，绑定节流后的函数；
  • 组件卸载时，移除滚动事件监听，且必须使用节流后的函数（throttled_func）作为移除对象，否则无法正确移除监听（原生事件监听要求添加和移除的函数是同一个引用），导致内存泄漏。

3.3 组件渲染与样式优化

if (!isVisible) {
    return null;
}

return (
    <Button 
    variant='outline'
    size='icon'
    onClick={scrollTop}
    className="fixed bottom-6 right-6 rounded-full shadow-lg hover:shadow-xl z-50">
        <ArrowUp className="h-4 w-4" />
    </Button>
)

3.3.1 条件渲染

当 isVisible 为 false 时，组件返回 null，不渲染任何 DOM 节点，避免无用节点占用页面资源。

3.3.2 按钮样式与交互

• 布局定位：

  • fixed 固定定位，使按钮始终位于页面可视区域；
  • bottom-6 right-6 定位在页面右下角，距离底部和右侧各 6 个单位；
  • z-50 设置较高的层级，确保按钮不被其他组件遮挡。

• 视觉样式：

  • rounded-full 圆形按钮，提升视觉美观度；
  • shadow-lg hover:shadow-xl 设置阴影效果，鼠标悬浮时阴影放大，增强交互反馈；
  • 使用 shadcn 的 Button 组件，配置 variant='outline'（轮廓样式）、size='icon'（图标尺寸），保持与项目 UI 风格一致。

• 图标集成：引入 Lucide React 的 ArrowUp 图标，设置尺寸为 h-4 w-4，直观表示“返回顶部”功能。

3.4 组件优化与复用

3.4.1 可配置性优化

组件通过threshold 属性支持自定义显示阈值，父组件可根据页面需求灵活配置（如在长列表页面设置 threshold={600}，在短页面设置 threshold={200}），提升组件复用性。

3.4.2 性能优化

• 节流处理：滚动事件监听采用节流函数，降低回调函数执行频率，减少性能消耗。
• 条件渲染：隐藏时不渲染 DOM 节点，避免无用节点占用资源。
• 事件清理：组件卸载时移除滚动事件监听，避免内存泄漏。

四、组件集成与首页（Home）使用

首页作为组件集成的载体，引入了 Header、SlideShow、BackToTop 及 shadcn 的 Card 组件，实现页面布局与功能整合。

4.1 首页代码解析

import Header from "@/components/Header";
import SlideShow,{ type SlideData } from "@/components/SlideShow";
import { 
    Card, 
    CardHeader, 
    CardTitle,
    CardContent,
} from "@/components/ui/card";

export default function Home() {
    const bannerData: SlideData[] = [{
      id: 1,
      title: "React 生态系统",
      image: "https://images.unsplash.com/photo-1633356122544-f134324a6cee?q=80&w=2070&auto=format&fit=crop",
    },
    {
      id: 2,
      title: "移动端开发最佳实践",
      image: "https://img.36krcdn.com/hsossms/20260114/v2_1ddcc36679304d3390dd9b8545eaa57f@5091053@ai_oswg1012730oswg1053oswg495_img_png~tplv-1marlgjv7f-ai-v3:600:400:600:400:q70.jpg?x-oss-process=image/format,webp",
    },
    {
      id: 3,
      title: "百度上线七猫漫剧，打的什么主意？",
      image: "https://img.36krcdn.com/hsossms/20260114/v2_8dc528b02ded4f73b29b7c1019f8963a@5091053@ai_oswg1137571oswg1053oswg495_img_png~tplv-1marlgjv7f-ai-v3:600:400:600:400:q70.jpg?x-oss-process=image/format,webp",
    }]
    return (
        <>
        <Header title="首页" showBackButton={true} />
         <SlideShow slides={bannerData} />
            <Card>
                <CardHeader>
                    <CardTitle>欢迎来到React Mobile</CardTitle>
                </CardHeader>
                <CardContent>
                   这是内容区域</CardContent>
            </Card>
            
                {
                    [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25].map((i,index) => (
                        <div key={ bg-white rounded-lg shadow-sm flex items-center justify-center border ">
                            Item {i}
                        
                    ))
                }

            </>
    )
}

4.2 核心集成要点

• 幻灯片组件使用：导入 SlideShow 组件和 SlideData 类型，定义 bannerData 数组作为轮播数据，传递给 slides 属性，使用默认的自动播放配置（也可自定义 autoPlay 和 autoPlayDelay）。
• Card 组件使用：引入 shadcn 的 Card 系列组件（Card、CardHeader、CardTitle、CardContent），实现内容卡片展示，保持页面布局规整。
• 网格布局：通过 grid grid-cols-2 gap-4 实现两列网格布局，循环生成 25 个列表项，展示批量内容，适配移动端页面需求。
• 样式规范：使用 p-4（内边距）、space-y-4（垂直间距）等样式类，保持页面元素间距一致，提升视觉美观度。

4.3 组件协同注意事项

• 类型一致性：使用SlideData 类型约束轮播数据，确保数据结构符合组件要求，避免类型错误。
• 层级关系：返回顶部组件（BackToTop）通常在首页全局引入，设置较高层级（z-50），确保在所有组件之上显示。
• 响应式适配：网格布局、轮播图宽高比等样式需适配移动端屏幕，可通过媒体查询（@media）调整不同屏幕尺寸下的布局。

五、核心知识点总结与拓展

5.1 核心知识点梳理

5.1.1 React Hooks 实战

• useState：管理组件状态（如轮播索引、按钮显示状态），实现状态驱动视图更新。
• useEffect：处理副作用（事件监听、组件卸载清理），需注意依赖项设置，避免无限循环和内存泄漏。
• useRef：持久化存储对象（如插件实例、DOM 引用），避免组件重渲染时重复创建，优化性能。

5.1.2 TypeScript 类型约束

• 组件属性（Props）类型定义：明确组件接收的参数类型、必填/可选状态，提升代码可维护性。
• 联合类型：如 id: number | string，适配多种数据类型场景。
• 类型别名：如 ThrottleFunction，简化复杂类型定义，提高代码可读性。

5.1.3 性能优化技巧

• 节流/防抖：高频事件（滚动、点击）采用节流/防抖处理，降低函数执行频率。
• 实例复用：使用 useRef 存储耗时创建的实例（如 AutoPlay 插件），避免重复创建。
• 事件清理：组件卸载时移除事件监听、清除定时器，避免内存泄漏。
• 条件渲染：隐藏状态下不渲染无用 DOM 节点，减少页面资源占用。

5.1.4 UI 组件库使用

• shadcn 组件：基于原子化设计，提供轻量、高定制性的基础组件，减少重复开发，保持 UI 风格一致。
• 插件集成：Embla Carousel 插件与 shadcn Carousel 组件适配，通过插件化机制扩展功能，提升开发效率。

5.2 拓展与进阶方向

• 幻灯片组件进阶：

  • 添加左右箭头切换按钮，调用 api.scrollPrev()、api.scrollNext() 方法实现手动切换；
  • 支持手势滑动（Embla Carousel 原生支持），适配移动端交互；
  • 实现轮播图懒加载，优化首屏加载速度。

• 返回顶部组件进阶：

  • 添加滚动进度条，结合 window.scrollY 和 document.body.scrollHeight 计算滚动进度；
  • 支持自定义按钮样式、图标、位置，提升组件复用性。

• TypeScript 进阶：

  • 使用泛型优化组件类型定义，提升组件通用性；
  • 引入 zod 等库，实现 Props 数据校验，增强类型安全。

• 性能优化进阶：

  • 使用 React.memo 包裹组件，避免不必要的重渲染；
  • 引入 react-window 等库，优化长列表渲染性能。

六、总结

本文基于实际开发代码，深入解析了 React + TypeScript 环境下幻灯片组件和返回顶部组件的实现过程，涵盖组件设计、类型约束、状态管理、事件处理、性能优化等核心知识点。通过学习这些组件的开发，我们可以掌握：

1. React Hooks 的实战应用，包括 useState、useEffect、useRef 的使用场景和最佳实践；
2. TypeScript 在组件开发中的类型约束技巧，提升代码健壮性和可维护性；
3. 高频事件（滚动、轮播）的性能优化方案，如节流、实例复用、事件清理；
4. UI 组件库（shadcn）与第三方插件（Embla Carousel）的集成方法，提升开发效率；
5. 组件化开发的核心思想，通过拆分功能组件、定义清晰的接口，实现组件复用与协同。

在实际项目开发中，还需结合业务需求进一步优化组件功能，适配不同场景的使用需求，同时持续关注 React 和 TypeScript 的新特性，不断提升代码质量和开发效率。

写在前面

架构师和普通开发者的区别，往往不在于谁会写的框架更多，而在于谁能写出更少 if-else 的代码。

圈复杂度（Cyclomatic Complexity） 是衡量代码质量的重要指标。一个充斥着几十层判断嵌套的函数，是维护者的噩梦。每增加一个 else，系统的脆弱性就增加一分。

此外，前端作为连接用户与后端的桥梁，时刻面临着“后端接口变动”和“第三方库升级”的风险。如果没有一层厚厚的“防弹衣”，你的核心业务代码将被外部变化击穿。

本篇我们将探讨三个最实用的设计模式，它们是降低复杂度、提升系统鲁棒性的核心武器。

---

一、 策略模式 (Strategy)：消灭 if-else 的屠龙刀

你一定见过这样的代码（甚至正在写）：

//  典型的“屎山”雏形
function getBonus(level, salary) {
  if (level === 'S') {
    return salary * 4;
  } else if (level === 'A') {
    return salary * 3;
  } else if (level === 'B') {
    return salary * 2;
  } else {
    return salary;
  }
}

当等级增加到 20 个，或者计算逻辑变得极其复杂时，这个函数会膨胀到几百行。

1.1 核心思想：把“判断”转为“映射”

策略模式的核心是 开闭原则（Open/Closed Principle） ：对扩展开放，对修改关闭。 我们将每种计算逻辑封装成独立的“策略”，然后用一个“环境对象（Context）”来分发。

1.2 架构级重构

在前端，我们通常不需要像 Java 那样定义接口和类，利用 JavaScript 的对象映射（Object Map）即可优雅实现：

// 策略表：独立的业务逻辑单元
const strategies = {
  S: (salary) => salary * 4,
  A: (salary) => salary * 3,
  B: (salary) => salary * 2,
  DEFAULT: (salary) => salary
};

// 环境函数：只负责分发，不负责逻辑
function calculateBonus(level, salary) {
  const strategy = strategies[level] || strategies.DEFAULT;
  return strategy(salary);
}

实战场景：表单验证 不要在提交函数里写一堆 if (phone === '') ... if (!email.includes('@'))。 定义一个 Validator 类，传入一组策略规则： validator.add(value, 'isNonEmpty').add(value, 'isMobile')。 当你想增加一种新的验证规则（比如验证身份证），你只需要在策略表中新增一个函数，而完全不需要触碰表单提交的主逻辑。

---

二、 适配器模式 (Adapter)：构建“防腐层 (ACL)”

前端是一个极其依赖“外部输入”的领域。

• 依赖后端 API：后端把 timestamp 改成了 ISO String，前端崩了。
• 依赖第三方库：地图库从 Google Maps 换成了 Mapbox，API 全变了，前端崩了。

2.1 核心思想：不要直接吃“生肉”

防腐层（Anti-Corruption Layer） 是架构中最重要的概念之一。它意味着：永远不要把第三方的数据结构直接透传给你的核心业务组件。

2.2 实战场景：API 响应归一化

假设后端返回的用户数据结构乱七八糟：

// 后端返回的 Raw Data
const response = {
  id: 123,
  u_name: 'John', // 奇怪的命名
  role_id: 0,     // 魔法数字
  create_at: '2023-01-01'
};

如果你直接在组件里用 data.u_name，你就被后端绑架了。请加上一个适配器：

//  UserAdapter.ts
export const userAdapter = (data: any): User => ({
  id: data.id,
  name: data.u_name || 'Guest', // 默认值保护
  role: data.role_id === 0 ? 'Admin' : 'User', // 逻辑转换
  createdAt: new Date(data.create_at).getTime() // 格式标准化
});

架构价值： 当后端改接口时，你只需要修改 UserAdapter.ts 这一处代码，所有使用 User 类型的 UI 组件都不需要动。这就是隔离变化。

---

三、 代理模式 (Proxy)：无侵入的“隐形保镖”

代理模式在前端的地位因 Vue 3 而封神，但它的用途远不止于响应式。 它的核心思想是：在对象操作的“必经之路”上设卡，进行拦截、增强或缓存。

3.1 实战场景一：网络请求的无感缓存

你想优化性能，把相同的 API 请求缓存下来。修改 fetchData 函数？太 Low 了，而且侵入性太强。 使用 Proxy 创建一个“缓存代理”：

const apiCache = new Map();

// 创建一个带缓存功能的 Fetch 代理
const cachedFetch = new Proxy(fetch, {
  apply(target, thisArg, args) {
    const url = args[0];
    
    // 1. 拦截：如果缓存里有，直接返回
    if (apiCache.has(url)) {
      console.log('Hit Cache:', url);
      return Promise.resolve(apiCache.get(url));
    }

    // 2. 放行：执行原函数
    return target.apply(thisArg, args).then(res => {
      // 3. 增强：保存结果
      apiCache.set(url, res.clone()); 
      return res;
    });
  }
});

业务代码完全不需要知道“缓存”的存在，它依然正常调用 cachedFetch，但自动获得了缓存能力。

3.2 实战场景二：图片懒加载

在 HTML 加载时，先展示一张占位图（Loading），等真正的图片下载好了再替换。这就是虚拟代理。 代理对象持有 img 节点，先设置 src=loading.gif，同时在后台创建一个 Image 对象去下载真实图片，下载完成后再修改节点的 src。

---

四、 架构师的“组合拳”

在真实的大型架构中，这些模式往往是组合使用的：

1. 用户操作 触发了某个行为。
2. 策略模式 根据用户类型，决定调用哪个 API 接口。
3. 代理模式 拦截这个 API 请求，检查本地是否有缓存。
4. 如果没有缓存，请求发出，拿到数据。
5. 适配器模式 将后端返回的乱七八糟的 JSON，清洗成标准的前端 Model。
6. 组件 渲染这个干净的 Model。

通过这一套组合拳，我们将逻辑分支、副作用、数据脏活全部隔离在组件之外，留给视图层的，只有纯粹的渲染。

---

结语：模块化的终局

至此，我们的**《前端向架构突围 - 模块化》**篇章圆满结束。

我们从思想上的边界思维出发，设计了 Headless UI 和 复合组件 的骨架，注入了 发布订阅/Signals 的灵魂，最后用 策略/适配器/代理 这一套盔甲武装了全身。

这五篇文章，其实只在讲一件事：高内聚，低耦合。

AI快速的发展中，可能在未来前后端岗位会发生，但试问一下，如果真到了那个时候，波及到的不会只有互联网行业，而是我们的生活方式同样会发生变化，我们唯有随需而变。

在企业级业务系统开发中，短信 http 接口是实现验证码下发、订单状态通知、系统告警的核心通道，但开发者在对接短信 http 接口时，常因对 HTTP 协议细节理解不足、请求参数配置不规范、请求方式选型错误等问题，导致接口调用成功率低、业务流程阻塞。本文聚焦短信 http 接口的全流程对接，从 HTTP 协议交互原理拆解、实战对接示例到避坑技巧总结，帮助开发者掌握标准化的短信 http 接口调用与集成方法，大幅提升接口适配效率和稳定性。

一、短信 http 接口对接的核心痛点与 HTTP 协议适配问题

开发者对接短信 http 接口时，80% 的异常源于对 HTTP 协议适配不当，核心痛点集中在以下方面：

1. HTTP 请求头配置错误：未按要求设置Content-Type为application/x-www-form-urlencoded，触发接口参数解析失败；
2. 请求方式选型不当：生产环境使用 GET 方式调用短信 http 接口，因 URL 长度限制导致长短信参数截断；
3. 参数编码异常：未统一使用 UTF-8 编码，中文内容出现乱码，触发 407（敏感字符）错误；
4. 状态码解析不精准：仅关注 “提交成功 / 失败”，未针对 406（手机号格式）、4085（验证码超限）等细分状态码制定处理策略。

这些问题本质是对短信 http 接口的 HTTP 协议交互逻辑理解不透彻，而非接口本身的适配性问题。

二、短信 http 接口的 HTTP 协议交互原理拆解

要稳定对接短信 http 接口，需先掌握其基于 HTTP 协议的通用交互逻辑，核心可拆解为 3 个阶段：

2.1 请求构建阶段

短信 http 接口的 HTTP 请求需满足 3 个核心规范：

• 请求方法：支持 GET/POST，生产环境优先 POST（无 URL 长度限制、参数安全性高）；
• 请求头：必须设置Content-Type: application/x-www-form-urlencoded，字符编码统一为 UTF-8；
• 参数封装：account（APIID）、password（APIKEY）为必选身份凭证，mobile需严格校验 11 位格式（示例：139****8888），content/templateid按模板规则配置。

2.2 服务端校验阶段

短信 http 接口的服务端会按固定逻辑校验请求：

1. 身份校验：验证account/password的有效性，无效则返回 405（API ID/KEY 错误）；
2. 参数校验：校验手机号格式、内容长度（≤500 字）、敏感字符、模板匹配度；
3. 权限校验：校验 IP 备案、剩余短信条数、单日发送量限制，触发限制则返回 4051（剩余条数不足）、4085（验证码超限）等状态码。

2.3 响应解析阶段

短信 http 接口的响应支持 JSON/XML 格式，核心关注code字段：

• code=2：仅代表请求提交成功，不代表短信送达成功；
• code≠2：需根据具体数值定位问题（如 406 为手机号格式错误，407 为内容含敏感字符）；
• 额外关注smsid：提交成功时的流水号，用于后续问题排查。

三、互亿无线短信 http 接口对接实战

以互亿无线的短信 http 接口为例，演示标准化的对接流程，该接口完全遵循 HTTP 协议规范，适配绝大多数企业级对接场景，且支持全天 24 小时调用。

3.1 前置准备

1. 接口凭证获取：访问注册链接http://user.ihuyi.com/?udcpF6完成账号注册，在用户中心 “文本短信 - 验证码短信 - 产品总览” 中获取account（APIID）和password（APIKEY）；
2. 环境依赖：引入 Apache HttpClient（处理 HTTP 请求）、FastJSON（解析 JSON 响应），Maven 依赖如下：

xml

<!-- HTTP请求依赖，用于调用短信http接口 -->
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>
<!-- JSON解析依赖，用于解析短信http接口响应 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version>
</dependency>

3.2 核心代码实现（POST 方式）

java

运行

import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
import com.alibaba.fastjson.JSONObject;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Pattern;

/**
 * 短信http接口对接工具类（互亿无线）
 * 凭证获取地址：http://user.ihuyi.com/?udcpF6（注册后在用户中心查看APIID/APIKEY）
 */
public class SmsHttpApiClient {
    // 短信http接口请求地址
    private static final String SMS_HTTP_API_URL = "https://api.ihuyi.com/sms/Submit.json";
    // 替换为从注册地址获取的APIID
    private static final String ACCOUNT = "xxxxxxxx";
    // 替换为从注册地址获取的APIKEY
    private static final String PASSWORD = "xxxxxxxx";
    // 手机号格式校验正则，避免触发短信http接口406错误
    private static final String MOBILE_REGEX = "^1[3-9]\d{9}$";

    /**
     * 调用短信http接口发送验证码（模板方式）
     * @param mobile 接收手机号，如139****8888
     * @param verifyCode 验证码内容
     * @return 短信http接口响应结果（JSON格式）
     */
    public static String sendVerifyCode(String mobile, String verifyCode) {
        // 前置参数校验：减少无效的短信http接口调用
        if (!Pattern.matches(MOBILE_REGEX, mobile)) {
            return JSONObject.toJSONString(new SmsHttpResponse(406, "手机号格式不正确", "0"));
        }
        if (verifyCode == null || verifyCode.length() < 4 || verifyCode.length() > 6) {
            return JSONObject.toJSONString(new SmsHttpResponse(40722, "验证码长度超出限制", "0"));
        }

        try (CloseableHttpClient client = HttpClients.createDefault()) {
            // 构建短信http接口请求参数
            List<NameValuePair> params = new ArrayList<>();
            params.add(new BasicNameValuePair("account", ACCOUNT));
            params.add(new BasicNameValuePair("password", PASSWORD));
            params.add(new BasicNameValuePair("mobile", mobile));
            params.add(new BasicNameValuePair("templateid", "1")); // 系统默认验证码模板
            params.add(new BasicNameValuePair("content", verifyCode)); // 模板变量

            // 构建POST请求，符合短信http接口的HTTP请求头要求
            HttpPost post = new HttpPost(SMS_HTTP_API_URL);
            post.setEntity(new UrlEncodedFormEntity(params, StandardCharsets.UTF_8));
            post.setHeader("Content-Type", "application/x-www-form-urlencoded");

            // 执行请求并解析短信http接口响应
            CloseableHttpResponse response = client.execute(post);
            String responseStr = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
            return responseStr;

        } catch (Exception e) {
            // 异常处理：短信http接口调用失败返回统一格式
            return JSONObject.toJSONString(new SmsHttpResponse(0, "接口调用异常：" + e.getMessage(), "0"));
        }
    }

    /**
     * 短信http接口响应实体类
     */
    static class SmsHttpResponse {
        private int code;
        private String msg;
        private String smsid;

        public SmsHttpResponse(int code, String msg, String smsid) {
            this.code = code;
            this.msg = msg;
            this.smsid = smsid;
        }

        // 省略getter/setter方法
    }

    // 测试方法
    public static void main(String[] args) {
        String result = sendVerifyCode("139****8888", "7890");
        System.out.println("短信http接口响应结果：" + result);
        // 解析响应结果
        JSONObject resultJson = JSONObject.parseObject(result);
        if (resultJson.getInteger("code") == 2) {
            System.out.println("短信http接口提交成功，流水号：" + resultJson.getString("smsid"));
        } else {
            System.out.println("短信http接口提交失败，原因：" + resultJson.getString("msg"));
        }
    }
}

3.3 核心代码解析

• 前置参数校验：调用短信 http 接口前校验手机号格式、验证码长度，避免无效请求；
• HTTP 请求头配置：严格按要求设置Content-Type，确保参数解析正常；
• 异常处理：封装统一的响应格式，便于业务系统解析短信 http 接口的调用状态。

四、短信 http 接口不同请求方式对比与选型

短信 http 接口支持 GET 和 POST 两种请求方式，需根据业务场景合理选型，具体对比如下：

对比维度	GET 方式	POST 方式
安全性	低（参数暴露在 URL 中）	高（参数封装在请求体）
长度限制	受 URL 长度限制（约 2048 字符）	无长度限制，支持长短信参数
调试便捷性	高（浏览器 / Postman 直接测试）	中（需构建请求体）
适用场景	短信 http 接口调试、参数简单的测试场景	生产环境、参数复杂的业务场景

选型结论：生产环境调用短信 http 接口优先选择 POST 方式；测试阶段可使用 GET 方式快速验证接口连通性，但需注意参数长度限制。

五、短信 http 接口集成的避坑技巧与最佳实践

为提升短信 http 接口的集成稳定性，总结以下核心技巧：

1. 全量前置校验：调用短信 http 接口前校验手机号格式、内容长度、敏感字符，避免 406/407/4073 等错误；
2. 异步调用解耦：通过消息队列（RabbitMQ/Kafka）异步调用短信 http 接口，避免阻塞业务主线程；
3. 精细化状态码处理：针对 405（凭证错误）、4085（验证码超限）、4051（条数不足）等状态码制定专属策略；
4. 编码统一化：所有参数均使用 UTF-8 编码，避免中文乱码触发敏感字符检测；
5. 监控告警配置：监控短信 http 接口的调用成功率（目标≥99.9%）、响应耗时（目标≤500ms），异常时及时告警。

总结

1. 对接短信 http 接口的核心是遵循 HTTP 协议规范，重点关注请求头配置、参数编码、状态码解析三大环节；
2. 生产环境调用短信 http 接口优先选择 POST 方式，前置参数校验可大幅降低无效请求率；
3. 异步调用、精细化状态码处理、监控告警是提升短信 http 接口集成稳定性的关键。

延伸建议：企业级项目中可封装短信 http 接口的统一调用网关，集中处理身份认证、参数校验、错误重试，降低多业务系统的对接成本。

Promise + SetTimeout

🥇 01. 并发限制调度器（异步霸榜 No.1）

业务场景：要发 100 个请求，但后端限流，每次只能发 N 个

扩展交互：可以在中途暂停执行，获取执行的结果

🌈实现思路：模拟一个迷你版“浏览器资源调度器”，这个调度器的核心本质，是通过「running 计数」「idx 游标」「runNext 自驱动」三者配合，实现一个动态的任务池。它保证任务源源不断执行，但同时不会超过给定的并发上限。

1. 业务调用

export function MyWork() {
  // 生成调度器
  const scheduler = limitRequests(tasks, 3);

  function handleStart() {
    scheduler.start().then((res) => {
      console.log("所有任务完成！");
      console.log("结果:", res);
    });
  }

  function handleEnd() {
    console.log("暂停完成执行～");
    scheduler.stop();
  }

  return (
    <div>
      <button onClick={handleStart}>开始</button>
      <button onClick={handleEnd}>暂停</button>
    </div>
  );
}

2. 创建调度器

export function limitRequests(tasks, limit) {
  const res = [] // 存所有任务返回的 Promise，用来最终 Promise.all
  let idx = 0 // 当前处理到第几个任务
  let running = 0 // 当前正在执行的任务数量（关键的并发控制变量）
  let stopped = false // 用于标识是否已停止

  // 暴露的停止执行的方法
  function stop() {
    stopped = true
  }

  function start() {
    return new Promise((resolve, reject) => {
      function runNext() {
        // 执行队列处理完毕或者已暂停，返回结果
        if (running === 0 && stopped) {
          return resolve(Promise.all(res))
        }

        // 正在执行的任务数量不超过单次限制，存在未执行的任务
        while (running < limit && idx < tasks.length) {
          // 如果停止标志为 true，阻止新的任务加入
          if (stopped) {
            return
          }
          // 获取当前任务并执行
          const cur = tasks[idx++]()
          res.push(cur)
          running++
          cur.then(() => {
            running--
            runNext()
          }).catch(reject)
        }
      }

      runNext()
    })
  }

  return { stop, start }
}

3. 模拟异步方法、准备数据

// 创建100个任务
export const tasks = Array.from({ length: 100 }, (_, i) => () => fetchData(i))

// 模拟异步请求方法
export function fetchData(id: number) {
  return new Promise(resolve => {
    const time = Math.random() * 2000
    console.log(`开始任务: ${id}`)

    setTimeout(() => {
      console.log(`完成任务: ${id}`)
      resolve(id)
    }, time)
  })
}

4. 自定义hook实现功能

const useLimitRequests = (tasks: any[], limit: number)=> {
  const resultRef = useRef<number[]>([]); // 用 useRef 存储任务结果，避免重新渲染
  const isStop = useRef<boolean>(false);
  const idx = useRef<number>(0);
  const reunning = useRef<number>(0);

  const onStop = useCallback(() => {
    isStop.current = true;
  },[]);

  const onStart = useCallback(() => {
    return new Promise((resolve, reject) => {
      function nextRun(){
        if(reunning.current === 0 && isStop.current) {
          return resolve(Promise.all(resultRef.current));
        }

        while(idx.current < tasks.length && reunning.current < limit){
          if(isStop.current){
            return;
          }

          const curTaskRes = tasks[idx.current]();
          idx.current += 1;
          resultRef.current.push(curTaskRes)
          reunning.current += 1;

          curTaskRes.then(() => {
            reunning.current -= 1;
            nextRun();
          }).catch((error: any) => reject(error))
        }
      }

      nextRun();
    })
  },[isStop, limit, tasks]);

  return { onStop, onStart};
}

🥈 02. 支持指数退避的重试（Backoff Retry）

业务场景：接口偶尔报错，你希望自动重试 3 次，每次等待时间翻倍。

1. 创建重试方法

function retry(fn, times = 3, delay = 500) {
  return new Promise((resolve, reject) => {
    const attempt = (n, d) => {
      fn().then(resolve).catch(err => {
        if (n === 0) return reject(err)
        setTimeout(() => attempt(n - 1, d * 2), d)
      })
    }
    attempt(times, delay)
  })
}

2. 业务调用

  function handleRetry() {
    retry(mockRequest, 3, 500)
      .then((result) => console.log(result)) // 如果请求成功，输出结果
      .catch((error) => console.log(error)); // 如果重试失败，输出错误
  }

🥉 03. 带超时控制的 Promise（Timeout Promise）

业务场景：请求超 3 秒自动失败，不等了

1. 自定义函数实现

export function withTimeout(fn, ms){
  // 存放定时器
  let timer = null;

  // 超时函数
  const timeOut = () => new Promise((_, reject) => {
    timer = setTimeout(() => reject(new Error('超时了')), ms);
  });

  // Promise.race 会返回一个结果， fn 目标函数
  return Promise.race([fn(), timeOut()]).finally(() => {
    clearTimeout(timer);
  })
}

2. 模拟延迟异步方法

export function slowTask() {
  return new Promise((resolve) => {
    setTimeout(() => resolve('Task completed'), 2000); // 模拟一个 3 秒的任务
  });
}

3. 业务调用

  function handleTimeOut() {
    withTimeout(slowTask, 1000) // 设置 1 秒超时
      .then((result) => console.log(result)) // 如果任务完成，输出结果
      .catch((error) => console.log(error)); // 如果超时，输出超时错误
  }

🚢 04. 串行任务：一步一步稳扎稳打

业务场景：分片上传、表单分步骤提交

核心逻辑：每个任务会按顺序一个接一个地执行，直到上一个任务完成后，才会开始下一个任务

1. 自定义方法

export async function runInSequence(tasks){
  const result = [];

  for (const task of tasks) {
    const res = await task();
    result.push(res);
  }

  return result;
}

2. 模拟异步请求

export const fetchData = (task: any) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`Task ${task} completed`);
      resolve(`Result of ${task}`);
    }, 1000); // 每个任务延迟 1 秒
  });
};

// 定义任务列表
export const tasks = [
  () => fetchData('task1'),
  () => fetchData('task2'),
  () => fetchData('task3')
];

3. 调用

async function handleEquence(){
    const result = await runInSequence(tasks);
    console.log('All tasks completed', result);
  }

⌚️ 05. Promise 版“多方等待 ready”机制

核心逻辑：这个机制用于让多个任务或组件等待某个条件（如 ready() 方法被调用）满足后再继续执行

业务场景： 1. 多个任务依赖同一个条件：比如，多个组件在等待某个数据加载完成后再开始执行某个操作。 2. 等待多个异步任务的准备：多个异步任务可能依赖某个资源，只有当该资源准备好时，才能继续执行后续操作。 3. 协调并发任务的开始：不同的任务或组件可以等待一个共同的“开始信号”，一旦信号发送，所有等待的任务就可以同时开始。

1. 自定义class

export class Waiter{
  queue: any[];
  readyFlag: boolean;

  constructor(){
    this.queue = []; // 所有等待的任务
    this.readyFlag = false; // 是否已经准备好
  }

  wait(){
    // 条件已经准备好了，直接返回一个已解决的 Promise
    if(this.readyFlag) {
      return Promise.resolve();
    } else {
      // 将该任务的 Promise 放入 queue 队列中，等待
      return new Promise((r) => this.queue.push(r));
    }
  }


  ready(){
    this.readyFlag = true; // 设置条件已准备好
    this.queue.forEach(r => r()); // 遍历队列并触发所有等待的任务
    this.queue = []; // 清空队列
  }
}

2. 调用

function handleReady() {
    const waiter = new Waiter();

    // 任务 1：等待条件准备好后执行
    waiter.wait().then(() => console.log("Task 1 completed"));

    // 任务 2：等待条件准备好后执行
    waiter.wait().then(() => console.log("Task 2 completed"));

    // 任务 3：等待条件准备好后执行
    waiter.wait().then(() => console.log("Task 3 completed"));

    // 在 2 秒后，调用 `ready()`，表示条件准备好，所有任务可以执行
    setTimeout(() => {
      waiter.ready(); // 调用 ready，触发所有等待的任务
    }, 2000);
  }

🌺06. 可暂停 / 恢复的 setInterval（轮询神器）

核心逻辑：可以启动、暂停和恢复一个定时任务，而无需重启整个定时器

业务场景：页面隐藏暂停轮询，返回恢复

1. 自定义class

export class PausableInterval{
  delay: number;
  fn: any;
  timer: any;
  running: boolean;

  constructor(fn: any, delay: number){
    this.fn = fn            // 定时任务函数
    this.delay = delay      // 定时器的间隔时间（单位：毫秒）
    this.timer = null       // 存储定时器的标识符
    this.running = false    // 标记定时器是否正在运行
  }

  start(){
    // 如果定时器已经在运行，直接返回，不做重复启动
    if(this.running) return;

    this.running = true;

    const tick = () => {
      if (!this.running) return // 如果定时器已暂停，则不再继续执行
      this.fn(); // 执行定时任务
      this.timer = setTimeout(tick, this.delay) // 使用 setTimeout 模拟 setInterval
    }

    tick();
  }

  pause() {
    clearTimeout(this.timer);
    this.running = false;
  }

  resume(){
    this.start()
  }
}

2. 模拟请求

function printMessage() {
  console.log("Task is running...");
}

export const pausableInterval = new PausableInterval(printMessage, 1000);

3. 调用

  function handleStartInterval() {
    pausableInterval.start();

    // 停止定时器
    setTimeout(() => {
      console.log("Pausing the task...");
      pausableInterval.pause();
    }, 3000); // 3秒后暂停

    // 恢复定时器
    setTimeout(() => {
      console.log("Resuming the task...");
      pausableInterval.resume();
    }, 5000); // 5秒后恢复
  }

🌹07. 带最大等待 maxWait 的防抖（搜索框的神）

业务场景：用于优化那些频繁触发的事件，特别是在搜索框、输入框或滚动等高频率操作中，常常用来减少不必要的计算或请求

1. 自定义方法

function debounce(fn, delay, { maxWait = 0 } = {}) {
  let timer = null; // 存放定时器
  let start = null; // 第一次调用时间

  return function (...args) {
    const now = Date.now();  // 获取当前时间戳
    if (!start) start = now; // 记录第一次调用的时间

    clearTimeout(timer);  // 清除之前的定时器，避免多次触发

    const run = () => { 
      start = null;  // 重置 `start`，表示已经执行过操作
      fn.apply(this, args);  // 执行函数，并传入当前的 `this` 和参数
    };

    // 如果到达 `maxWait` 时间，强制执行 `fn`；否则继续延迟执行
    if (maxWait && now - start >= maxWait) run(); 
    else timer = setTimeout(run, delay);  // 在 `delay` 时间后执行
  };
}

2. 模拟短期内多次触发

function searchQuery(query) {
  console.log("Searching for:", query);
}

const debouncedSearch = debounce(searchQuery, 500, { maxWait: 2000 });

// 模拟用户输入
debouncedSearch("apple");
debouncedSearch("app");
debouncedSearch("appl");
debouncedSearch("apple pie");

基础概念

• 图元 指的是3D的形状，比如盒子(BoxGeometry)，圆柱(CylinderGeometry)等。除了这些可以直接使用的形状外，还可以使用BufferGeometry自定义形状

    const objects = [];

   // 一球多用
   const radius = 1;
   const widthSegments = 6;
   const heightSegments = 6;
   const sphereGeometry = new THREE.SphereGeometry(
     radius,
     widthSegments,
     heightSegments
   );

• 材质 前面物体的材质,有很多种；MeshBasicMaterial 不受光照的影响。MeshLambertMaterial 只在顶点计算光照，而 MeshPhongMaterial 则在每个像素计算光照。MeshPhongMaterial 还支持镜面高光....

     const sunMaterial = new THREE.MeshPhongMaterial({ emissive: 0xffff00 });
  

• 层次 将形状和材质进行结合

      const mesh = new THREE.Mesh(sphereGeometry, sumMaterial)
  

• 场景 3D引擎中一个图中节点的层次结构，代表一个局部空间 const scene = new THREE.Scene() scene.add(sunMesh);
• 摄像机 PerspectiveCamera,提供一个近大远小的3d视觉效果，near视锥的前端，far视锥的后端，for视野角度，aspect视锥前端和后端宽度，

const camera2 = new THREE.PerspectiveCamera(
  60,  // fov
  2,   // aspect
  0.1, // near
  500, // far
);
camera2.position.set(40, 10, 30);
camera2.lookAt(0, 5, 0);
 

• 渲染目标 THREE.WebGLRenderer,需要传入dom等参数

const renderer = new THREE.WebGLRenderer({ 
  canvas: canvas, 
  antialias: true, // 开启抗锯齿
  alpha: true      // 开启背景透明
})

renderer.render(scene, camera)
// window.requestAnimationFrame(tick)来实现循环渲染，const tick = () => {renderer.render(scene, camera)}

• 轨道控制器，使得可以通过鼠标移动3d图形

const controls = new OrbitControls(camera, canvas)
controls.enableDamping = true // 开启阻尼感（平滑旋转）
controls.dampingFactor = 0.05
// 限制缩放范围
controls.minDistance = 2
controls.maxDistance = 10

• 坐标 在页面上显示x y z轴
  • 红色：X轴（向右）
  • 绿色：Y轴（向上）
  • 蓝色：Z轴（向前/向屏幕外）

// 添加坐标轴辅助工具
const axesHelper = new THREE.AxesHelper(5); // 参数表示坐标轴长度
scene.add(axesHelper);

// 或者指定不同长度
const axesHelper = new THREE.AxesHelper(1);
scene.add(axesHelper);

• 光照 增加一些环境光，半球光等

   const color = 0xFFFFFF;
   const intensity = 1;
   const light = new THREE.AmbientLight(color, intensity);
   scene.add(light);

• 加载器
  • 图元加载器，各种图元模型gltf模型或者glb(glb是gltf的二进制文件）

    import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
    const gltfLoader = new GLTFLoader()
    // 加载甜甜圈模型
    gltfLoader.load(require('xxx'))
    

  • 材料加载器,比如贴片图片，创建材料等纹理节点

  const material = new TextureLoad(require('XXX'))
  

• 设置渲染大小为整个屏幕

const getCanvasSize = () => {
 const parent = canvas.parentElement
 return {
   width: parent?.clientWidth || window.innerWidth,
   height: parent?.clientHeight || window.innerHeight
 }
}
let sizes = getCanvasSize()
render.setSize(siezs.width, sizes.height)
// 设置像素比，防止在高分屏上模糊
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

• gui 允许在页面上直接调参的工具

写一个完整的例子

'use client'

import { useEffect } from 'react'
import * as THREE from 'three'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'
import GUI from 'lil-gui'

const Page = () => {
 const init = () => {
   // 1. 获取 Canvas 元素
   const canvas = document.querySelector('canvas.webgl') as HTMLCanvasElement | null
   if (!canvas) return

   // 2. 创建场景 (Scene)
   const scene = new THREE.Scene()

   // 2.1 初始化 GUI
   const gui = new GUI()
   gui.close() // 默认关闭
   const debugObject = {
     wireframe: true
   }

   // 3. 模型加载器 (GLTFLoader)
   const gltfLoader = new GLTFLoader()
   let donut: THREE.Object3D | null = null

   // 加载甜甜圈模型
   // 注意：这里使用 /api/static 代理路径来绕过 Next.js 对 .gltf 文件的模块导入限制
   gltfLoader.setPath('/api/static/assets/donut/')
   gltfLoader.load(
     'scene.gltf',
     (gltf) => {
       donut = gltf.scene as THREE.Object3D
       
       // 更新模型线框模式的函数
       const updateWireframe = () => {
         if (!donut) return
         donut.traverse((child) => {
           if ((child as THREE.Mesh).isMesh) {
             const mesh = child as THREE.Mesh
             const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material]
             materials.forEach((m: THREE.Material) => {
               if ('wireframe' in m) {
                 ;(m as THREE.MeshStandardMaterial).wireframe = debugObject.wireframe
               }
             })
           }
         })
       }

       // 初始化线框状态
       updateWireframe()

       // 添加 GUI 控制
       gui.add(debugObject, 'wireframe')
         .name('显示线性')
         .onChange(updateWireframe)

       const radius = 8.5
       // 设置初始位置
       donut.position.x = 0
       // 设置模型缩放倍数
       donut.scale.set(radius, radius, radius)
       scene.add(donut)

     },
     undefined,
     (error) => { console.error('模型加载失败:', error) }
   )

   // 4. 灯光设置 (Lights)
   // 环境光：提供基础亮度，确保暗部不会完全变黑
   const ambientLight = new THREE.AmbientLight(0xffffff, 1.2)
   scene.add(ambientLight)

   // 平行光：模拟太阳光，产生阴影和立体感
   const directionalLight = new THREE.DirectionalLight(0xffffff, 1.5)
   directionalLight.position.set(2, 4, 1)
   directionalLight.castShadow = true // 开启阴影投影
   scene.add(directionalLight)

   // 5. 视口大小设置
   const getCanvasSize = () => {
     const parent = canvas.parentElement
     return {
       width: parent?.clientWidth || window.innerWidth,
       height: parent?.clientHeight || window.innerHeight
     }
   }
   let sizes = getCanvasSize()

   // 6. 相机设置 (Camera)
   // 使用透视相机 (PerspectiveCamera)
   const camera = new THREE.PerspectiveCamera(35, sizes.width / sizes.height, 0.1, 1000)
   camera.position.z = 5 // 相机后移，以便看清场景
   camera.lookAt(0, 0, 0)
   scene.add(camera)

   // 7. 渲染器设置 (Renderer)
   const renderer = new THREE.WebGLRenderer({ 
     canvas: canvas, 
     antialias: true, // 开启抗锯齿
     alpha: true      // 开启背景透明
   })
   renderer.shadowMap.enabled = true // 开启阴影渲染
   renderer.shadowMap.type = THREE.PCFSoftShadowMap // 设置柔和阴影
   renderer.setSize(sizes.width, sizes.height)
   // 设置像素比，防止在高分屏上模糊
   renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

   // 7.1 轨道控制器 (OrbitControls)
   const controls = new OrbitControls(camera, canvas)
   controls.enableDamping = true // 开启阻尼感（平滑旋转）
   controls.dampingFactor = 0.05
   // 限制缩放范围
   controls.minDistance = 2
   controls.maxDistance = 10

   // 8. 动画循环 (Animation Loop)
   const clock = new THREE.Clock()
   const tick = () => {
     const elapsedTime = clock.getElapsedTime()

     if (donut) {
       // 设定基础倾斜角度，使其正面朝向屏幕并有立体感
       const baseRotationX = 0.8
       const baseRotationY = 0.8
       
       // 动态计算：基础角度 + 正弦波晃动，实现轻微的浮动效果
       donut.rotation.y = baseRotationY + Math.sin(elapsedTime * 0.4) * 0.1
       donut.rotation.x = baseRotationX + Math.sin(elapsedTime * 0.2) * 0.05
       // Y 轴位置动态浮动
       donut.position.y = Math.sin(elapsedTime * 0.5) * 0.1
     }

     // 更新控制器（如果开启了 enableDamping，必须在每一帧调用）
     controls.update()

     // 执行渲染
     renderer.render(scene, camera)
     // 请求下一帧动画
     window.requestAnimationFrame(tick)
   }

   const handleResize = () => {
     sizes = getCanvasSize()
     
     // 更新相机
     camera.aspect = sizes.width / sizes.height
     camera.updateProjectionMatrix()

     // 更新渲染器
     renderer.setSize(sizes.width, sizes.height)
     renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
   }

   window.addEventListener('resize', handleResize)
   tick()

   // 返回清理函数，销毁 GUI 和事件监听
   return () => {
     gui.destroy()
     window.removeEventListener('resize', handleResize)
   }
 }

 useEffect(() => {
   const cleanup = init()
   return () => {
     if (cleanup) cleanup()
   }
 }, [])

 return (
   <div className="min-h-screen w-full flex flex-col lg:flex-row bg-[#fdf2f8]">
       <canvas className="webgl w-full h-full block"></canvas>
   </div>
 )
}

export default Page