npm包完整说明文档（中俄双语）

Пакет npm: Полное руководство (Двухязычный: русский и китайский)

一、项目介绍 / Описание проекта

中文：本npm包是一个轻量、高效、零依赖的JavaScript工具库，专注于解决前端开发中常见的工具类需求，简化开发流程、提升开发效率。包含防抖、节流、深拷贝等高频使用的工具函数，兼容Node.js和浏览器全平台，函数注释完善、类型清晰，可直接集成到各类JavaScript项目中，无需额外配置。 Русский：Данный пакет npm представляет собой легкую, эффективную JavaScript-библиотеку без зависимостей, предназначенную для решения распространенных задач в фронтенд-разработке, упрощения процесса разработки и повышения его эффективности. Он включает часто используемые утилитарные функции, такие как дебаунс, троттлинг, глубокое копирование и т.д., совместим с Node.js и всеми браузерами, имеет подробные комментарии к функциям и ясные типы, и может быть напрямую интегрирован в любые JavaScript-проекты без дополнительной конфигурации.

二、安装指南 / Инструкция по установке

2.1 前提条件 / Предварительные требования

中文：已安装Node.js（版本≥14.0.0）和npm（版本≥6.0.0），建议使用npm或yarn作为包管理工具。 Русский：Предварительно установлен Node.js (версия ≥14.0.0) и npm (версия ≥6.0.0), рекомендуется использовать npm или yarn в качестве менеджера пакетов.

2.2 安装命令 / Команды установки

中文：使用npm安装：

npm install wusheng000 --save

中文：使用yarn安装：

yarn add wusheng000

Русский：Установка с использованием npm：

npm install wusheng000 --save

Русский：Установка с использованием yarn：

yarn add wusheng000

中文：说明：--save参数会将包添加到package.json的dependencies中，确保项目依赖被正确记录，便于团队协作和项目部署。若使用npm 5.0.0及以上版本，--save可省略，npm会自动将依赖添加到dependencies中。 Русский：Примечание: Параметр --save добавляет пакет в dependencies файла package.json, гарантируя правильную запись зависимостей проекта для командной работы и развертывания проекта. Если используется версия npm 5.0.0 и выше, --save можно опустить, npm автоматически добавит зависимость в dependencies.

三、快速使用 / Быстрое использование

3.1 引入方式 / Способы импорта

中文：支持CommonJS（Node.js默认）和ES6模块两种引入方式，可根据项目环境灵活选择。按需引入可减少项目打包体积，推荐优先使用按需引入方式。 Русский：Поддерживает два способа импорта: CommonJS (по умолчанию в Node.js) и ES6-модули, которые можно гибко выбирать в зависимости от окружения проекта. Импорт по мере необходимости может уменьшить объем упаковки проекта, поэтому рекомендуется использовать этот способ в первую очередь.

中文：方式1：CommonJS引入（Node.js或未配置ES6模块的项目）

// 引入整个工具库
const utils = require('wusheng000');
// 或按需引入指定函数（推荐，减少体积）
const { debounce, throttle, deepClone } = require('wusheng000');

Русский：Способ 1: Импорт CommonJS (Node.js или проекты без конфигурации ES6-модулей)

// Импорт всей утилитарной библиотеки
const utils = require('wusheng000');
// Или импорт указанных функций по мере необходимости (рекомендуется для уменьшения объема)
const { debounce, throttle, deepClone } = require('wusheng000');

中文：方式2：ES6模块引入（已配置babel或支持ES6模块的项目，如Vue、React项目）

// 引入整个工具库
import utils from 'wusheng000';
// 或按需引入指定函数（推荐）
import { debounce, throttle, deepClone } from 'wusheng000';

Русский：Способ 2: Импорт ES6-модулей (проекты с настроенным babel или поддерживающие ES6-модули, например, проекты Vue, React)

// Импорт всей утилитарной библиотеки
import utils from 'wusheng000';
// Или импорт указанных функций по мере необходимости (рекомендуется)
import { debounce, throttle, deepClone } from 'wusheng000';

3.2 简单示例 / Простой пример

中文：以下是各核心函数的快速使用示例，可直接复制到项目中运行，帮助快速熟悉函数用法。所有示例均兼容Node.js和浏览器环境。 Русский：Ниже приведены быстрые примеры использования каждой основной функции, которые можно напрямую скопировать в проект для запуска, чтобы быстро ознакомиться с их использованием. Все примеры совместимы с окружениями Node.js и браузера.

// 1. 防抖函数使用示例
const search = debounce(() => {
  console.log('发起搜索请求，关键词：' + document.getElementById('search-input').value);
}, 500);
// 绑定到搜索框输入事件
document.getElementById('search-input').addEventListener('input', search);

// 2. 节流函数使用示例
const handleScroll = throttle(() => {
  console.log('页面滚动距离：' + window.scrollY);
}, 1000);
// 绑定到页面滚动事件
window.addEventListener('scroll', handleScroll);

// 3. 深拷贝函数使用示例
const originalObj = {
  name: '测试对象',
  age: 20,
  details: {
    address: '中国',
    hobbies: ['编程', '阅读']
  }
};
const clonedObj = deepClone(originalObj);
clonedObj.details.address = '俄罗斯';
console.log('原对象：', originalObj); // 原对象地址不变
console.log('拷贝对象：', clonedObj); // 拷贝对象地址已修改

四、函数API详细说明 / Подробное описание API функций

中文：本章节详细说明每个函数的功能、参数、返回值、使用场景及完整示例，确保开发者能精准理解并正确使用每个函数，避免使用误区。 Русский：В этом разделе подробно описываются функция, параметры, возвращаемое значение, сценарии использования и полные примеры каждой функции, чтобы разработчики могли точно понять и правильно использовать каждую функцию, избегая ошибок в использовании.

4.1 防抖函数 / Функция debounce (дебаунс)

中文：功能：高频事件（如输入、滚动、点击）触发后，延迟指定时间再执行回调函数；若在延迟期间再次触发该事件，则重新计算延迟时间，最终只执行最后一次触发后的回调。用于避免高频事件多次执行，减少性能消耗。 Русский：Функция: После запуска высокочастотного события (например, ввод, прокрутка, клик), выполняет функцию обратного вызова с задержкой указанного времени; если событие запускается снова в течение периода задержки, время задержки пересчитывается, и в итоге выполняется только функция обратного вызова после последнего запуска. Используется для предотвращения многократного выполнения высокочастотных событий и снижения затрат на производительность.

中文：语法：debounce(func, delay, immediate) Русский：Синтаксис: debounce(func, delay, immediate)

中文：参数说明：

• func (Function, 必选)：需要进行防抖处理的目标函数，即最终要执行的回调函数，可接收参数。
• delay (Number, 必选)：延迟时间，单位为毫秒（ms），表示事件触发后多久执行func。
• immediate (Boolean, 可选，默认false)：是否立即执行。true表示事件触发后立即执行func，之后延迟期间触发不执行；false表示事件触发后延迟delay毫秒执行func，延迟期间触发重新计时。

Русский：Описание параметров：

• func (Function, обязательный)：Целевая функция, для которой нужно обработать дебаунс, то есть функция обратного вызова, которая будет выполнена в итоге, может принимать параметры.
• delay (Number, обязательный)：Время задержки в миллисекундах (ms), указывает, через сколько времени после запуска события выполнить func.
• immediate (Boolean, опциональный, по умолчанию false)：Нужно ли выполнять немедленно. true означает, что func выполняется немедленно после запуска события, а последующие запуски в течение периода задержки не выполняются; false означает, что func выполняется через delay миллисекунд после запуска события, а запуски в течение периода задержки перезапускают таймер.

中文：返回值：(Function) 经过防抖处理后的函数，可直接绑定到事件上使用。 Русский：Возвращаемое значение: (Function) Функция после обработки дебаунса, которую можно напрямую привязать к событию.

中文：使用场景：搜索框输入联想、窗口大小调整（resize事件）、按钮频繁点击防止重复提交、文本框实时输入验证等。 Русский：Сценарии использования: Ассоциация ввода в поле поиска, изменение размера окна (событие resize), предотвращение повторной отправки при частых кликах по кнопке, реальное время проверка ввода в текстовом поле и т.д.

中文：完整示例：

// 示例1：默认immediate=false（延迟执行）
// 搜索框输入防抖，500ms内无输入再发起请求
const searchInput = document.getElementById('search');
const fetchSearchData = debounce((keyword) => {
  console.log('发起搜索请求，关键词：', keyword);
  // 实际开发中此处可调用接口请求数据
}, 500);
searchInput.addEventListener('input', (e) => {
  fetchSearchData(e.target.value); // 传递参数给防抖函数
});

// 示例2：immediate=true（立即执行）
// 按钮点击防抖，点击后立即执行，1000ms内再次点击不执行
const submitBtn = document.getElementById('submit');
const submitForm = debounce(() => {
  console.log('表单提交成功');
}, 1000, true);
submitBtn.addEventListener('click', submitForm);

Русский：Полный пример：

// Пример 1: По умолчанию immediate=false (отложенное выполнение)
// Дебаунс ввода в поле поиска, запрос отправляется только после 500мс без ввода
const searchInput = document.getElementById('search');
const fetchSearchData = debounce((keyword) => {
  console.log('Отправка запроса на поиск, ключевое слово：', keyword);
  // В реальной разработке здесь можно вызвать интерфейс для запроса данных
}, 500);
searchInput.addEventListener('input', (e) => {
  fetchSearchData(e.target.value); // Передача параметров в функцию дебаунса
});

// Пример 2: immediate=true (немедленное выполнение)
// Дебаунс клика по кнопке, выполняется немедленно после клика, повторные клики в течение 1000мс не выполняются
const submitBtn = document.getElementById('submit');
const submitForm = debounce(() => {
  console.log('Форма успешно отправлена');
}, 1000, true);
submitBtn.addEventListener('click', submitForm);

4.2 节流函数 / Функция throttle (троттлинг)

中文：功能：高频事件触发时，保证在指定的时间间隔内，只执行一次回调函数，无论事件触发多少次。用于控制事件执行的频率，避免频繁执行导致性能问题。 Русский：Функция: При запуске высокочастотного события гарантирует, что функция обратного вызова выполняется только один раз за указанный интервал времени, независимо от того, сколько раз запущено событие. Используется для контроля частоты выполнения событий и предотвращения проблем с производительностью из-за частого выполнения.

中文：语法：throttle(func, interval, leading, trailing) Русский：Синтаксис: throttle(func, interval, leading, trailing)

中文：参数说明：

• func (Function, 必选)：需要进行节流处理的目标函数，即最终要执行的回调函数，可接收参数。
• interval (Number, 必选)：执行间隔时间，单位为毫秒（ms），表示指定时间内最多执行一次func。
• leading (Boolean, 可选，默认true)：是否在事件触发的开始执行一次func。true表示事件触发时立即执行一次，之后按interval间隔执行；false表示事件触发后，等待interval毫秒再执行第一次。
• trailing (Boolean, 可选，默认true)：是否在事件停止触发后，再执行一次func。true表示事件停止触发后，等待interval毫秒执行最后一次；false表示事件停止触发后，不再执行。

Русский：Описание параметров：

• func (Function, обязательный)：Целевая функция, для которой нужно обработать троттлинг, то есть функция обратного вызова, которая будет выполнена в итоге, может принимать параметры.
• interval (Number, обязательный)：Интервал выполнения в миллисекундах (ms), указывает, что func выполняется не чаще одного раза за указанное время.
• leading (Boolean, опциональный, по умолчанию true)：Нужно ли выполнять func один раз в начале запуска события. true означает, что func выполняется немедленно при запуске события, а затем выполняется с интервалом interval; false означает, что после запуска события func выполняется впервые после ожидания interval миллисекунд.
• trailing (Boolean, опциональный, по умолчанию true)：Нужно ли выполнять func один раз после остановки запуска события. true означает, что после остановки запуска события func выполняется в последний раз после ожидания interval миллисекунд; false означает, что после остановки запуска события func не выполняется.

中文：返回值：(Function) 经过节流处理后的函数，可直接绑定到事件上使用。 Русский：Возвращаемое значение: (Function) Функция после обработки троттлинга, которую можно напрямую привязать к событию.

中文：使用场景：页面滚动监听、鼠标移动事件、高频点击事件、视频播放进度更新等。 Русский：Сценарии использования: Отслеживание прокрутки страницы, событие движения мыши, высокочастотные клики, обновление прогресса воспроизведения видео и т.д.

中文：完整示例：

// 示例1：默认leading=true、trailing=true（开始和结束都执行）
// 页面滚动节流，1000ms内只执行一次
const handleScroll = throttle(() => {
  console.log('页面滚动位置：', window.scrollY);
  // 实际开发中可用于监听滚动加载、导航栏样式变化等
}, 1000);
window.addEventListener('scroll', handleScroll);

// 示例2：leading=false、trailing=true（只在结束时执行）
// 鼠标移动节流，移动时不立即执行，停止移动后执行一次
const handleMouseMove = throttle((e) => {
  console.log('鼠标位置：', e.clientX, e.clientY);
}, 500, false);
document.addEventListener('mousemove', handleMouseMove);

// 示例3：leading=true、trailing=false（只在开始时执行）
// 按钮点击节流，1000ms内只执行第一次点击
const clickBtn = document.getElementById('click-btn');
const handleClick = throttle(() => {
  console.log('按钮被点击');
}, 1000, true, false);
clickBtn.addEventListener('click', handleClick);

Русский：Полный пример：

// Пример 1: По умолчанию leading=true、trailing=true (выполняется в начале и конце)
// Троттлинг прокрутки страницы, выполняется только один раз за 1000мс
const handleScroll = throttle(() => {
  console.log('Положение прокрутки страницы：', window.scrollY);
  // В реальной разработке может использоваться для отслеживания прокрутки загрузки, изменения стиля навигационной панели и т.д.
}, 1000);
window.addEventListener('scroll', handleScroll);

// Пример 2: leading=false、trailing=true (выполняется только в конце)
// Троттлинг движения мыши, не выполняется немедленно при движении, выполняется один раз после остановки
const handleMouseMove = throttle((e) => {
  console.log('Положение мыши：', e.clientX, e.clientY);
}, 500, false);
document.addEventListener('mousemove', handleMouseMove);

// Пример 3: leading=true、trailing=false (выполняется только в начале)
// Троттлинг клика по кнопке, выполняется только первый клик за 1000мс
const clickBtn = document.getElementById('click-btn');
const handleClick = throttle(() => {
  console.log('Кнопка нажата');
}, 1000, true, false);
clickBtn.addEventListener('click', handleClick);

4.3 深拷贝函数 / Функция deepClone (глубокое копирование)

中文：功能：递归拷贝对象、数组等引用类型数据，创建一个全新的副本，副本与原数据完全独立，修改副本不会影响原数据，解决JavaScript中引用类型赋值导致的“浅拷贝”问题。支持基本类型（字符串、数字、布尔值等）和引用类型（对象、数组、嵌套对象等）的拷贝。 Русский：Функция: Рекурсивно копирует данные ссылочных типов, таких как объекты, массивы, создавая полностью новый клон, который полностью независим от исходных данных. Изменение клона не влияет на исходные данные, решая проблему "многократного копирования" (shallow copy), возникающую при присваивании ссылочных типов в JavaScript. Поддерживает копирование базовых типов (строки, числа, булевы значения и т.д.) и ссылочных типов (объекты, массивы, вложенные объекты и т.д.).

中文：语法：deepClone(target) Русский：Синтаксис: deepClone(target)

中文：参数说明：

• target (any, 必选)：需要进行深拷贝的目标数据，可以是基本类型、对象、数组、嵌套对象、null、undefined等。

Русский：Описание параметров：

• target (any, обязательный)：Целевые данные для глубокого копирования, могут быть базовыми типами, объектами, массивами, вложенными объектами, null, undefined и т.д.

中文：返回值：(any) 深拷贝后的全新数据，与原数据类型一致，无任何引用关系。 Русский：Возвращаемое значение: (any) Новые данные после глубокого копирования, совпадающие по типу с исходными данными, без какой-либо связи по ссылке.

中文：使用场景：对象/数组的备份、状态管理（如Vuex、Redux中状态的拷贝）、避免修改原数据、数据格式化等。 Русский：Сценарии использования: Резервное копирование объектов/массивов, управление состоянием (например, копирование состояния в Vuex, Redux), предотвращение изменения исходных данных, форматирование данных и т.д.

中文：完整示例：

// 示例1：拷贝基本类型（字符串、数字、布尔值）
const str = 'hello world';
const clonedStr = deepClone(str);
console.log(clonedStr); // 'hello world'
console.log(clonedStr === str); // true（基本类型值相等）

const num = 123;
const clonedNum = deepClone(num);
console.log(clonedNum); // 123

// 示例2：拷贝数组（含嵌套数组）
const arr = [1, 2, [3, 4, [5, 6]]];
const clonedArr = deepClone(arr);
clonedArr[2][1] = 100;
console.log('原数组：', arr); // [1, 2, [3, 4, [5, 6]]]
console.log('拷贝数组：', clonedArr); // [1, 2, [3, 100, [5, 6]]]

// 示例3：拷贝对象（含嵌套对象）
const obj = {
  name: '张三',
  age: 25,
  info: {
    address: '北京',
    contact: {
      phone: '123456789',
      email: '[email protected]'
    }
  },
  hobbies: ['篮球', '编程']
};
const clonedObj = deepClone(obj);
clonedObj.info.address = '上海';
clonedObj.hobbies.push('阅读');
console.log('原对象：', obj); // 原对象地址、hobbies不变
console.log('拷贝对象：', clonedObj); // 拷贝对象地址、hobbies已修改

// 示例4：拷贝null和undefined
const nullVal = null;
const clonedNull = deepClone(nullVal);
console.log(clonedNull); // null

const undefinedVal = undefined;
const clonedUndefined = deepClone(undefinedVal);
console.log(clonedUndefined); // undefined

Русский：Полный пример：

// Пример 1: Копирование базовых типов (строка, число, булево значение)
const str = 'hello world';
const clonedStr = deepClone(str);
console.log(clonedStr); // 'hello world'
console.log(clonedStr === str); // true（значения базовых типов равны）

const num = 123;
const clonedNum = deepClone(num);
console.log(clonedNum); // 123

// Пример 2: Копирование массива (с вложенным массивом)
const arr = [1, 2, [3, 4, [5, 6]]];
const clonedArr = deepClone(arr);
clonedArr[2][1] = 100;
console.log('Исходный массив：', arr); // [1, 2, [3, 4, [5, 6]]]
console.log('Копированный массив：', clonedArr); // [1, 2, [3, 100, [5, 6]]]

// Пример 3: Копирование объекта (с вложенным объектом)
const obj = {
  name: 'Чжан Сан',
  age: 25,
  info: {
    address: 'Пекин',
    contact: {
      phone: '123456789',
      email: '[email protected]'
    }
  },
  hobbies: ['баскетбол', 'программирование']
};
const clonedObj = deepClone(obj);
clonedObj.info.address = 'Шанхай';
clonedObj.hobbies.push('чтение');
console.log('Исходный объект：', obj); // Исходный объект и hobbies не изменены
console.log('Копированный объект：', clonedObj); // Копированный объект и hobbies изменены

// Пример 4: Копирование null и undefined
const nullVal = null;
const clonedNull = deepClone(nullVal);
console.log(clonedNull); // null

const undefinedVal = undefined;
const clonedUndefined = deepClone(undefinedVal);
console.log(clonedUndefined); // undefined

五、常见问题 / Часто задаваемые вопросы (ЧЗВ)

5.1 安装失败怎么办？ / Что делать при сбое установки?

中文：1. 检查Node.js和npm版本是否满足要求（Node.js≥14.0.0，npm≥6.0.0）；2. 检查网络连接，确保能正常访问npm官方仓库；3. 若使用npm安装失败，可尝试切换为yarn安装；4. 清除npm缓存：npm cache clean --force，然后重新安装。 Русский：1. Проверьте, соответствуют ли версии Node.js и npm требованиям (Node.js≥14.0.0, npm≥6.0.0); 2. Проверьте интернет-соединение, убедитесь, что вы можете нормально обращаться к официальному репозиторию npm; 3. Если установка с использованием npm не удалась, попробуйте переключиться на установку с yarn; 4. Очистите кэш npm: npm cache clean --force, затем переустановите.

5.2 函数使用后没有效果？ / Функция не работает после использования?

中文：1. 检查函数引入方式是否正确，确保按需引入时函数名称拼写正确；2. 检查函数参数是否符合要求（如debounce的delay必须是数字）；3. 检查事件绑定是否正确，确保经过防抖/节流处理的函数绑定到了对应的事件上；4. 深拷贝函数若拷贝失败，检查目标数据是否为特殊类型（如Date、RegExp），本包暂不支持这类特殊类型的深拷贝。 Русский：1. Проверьте, правильен ли способ импорта функции, убедитесь, что имя функции написано правильно при импорте по мере необходимости; 2. Проверьте, соответствуют ли параметры функции требованиям (например, delay в debounce должен быть числом); 3. Проверьте, правильна ли привязка события, убедитесь, что функция после обработки дебаунса/троттлинга привязана к соответствующему событию; 4. Если функция глубокого копирования не копирует данные, проверьте, является ли целевые данные специальным типом (например, Date, RegExp), данный пакет пока не поддерживает глубокое копирование таких специальных типов.

5.3 包体积过大？ / Объем пакета слишком большой?

中文：本包为零依赖工具库，体积已做优化（压缩后≤5KB）。若需进一步减小体积，建议使用按需引入方式，只引入项目中需要的函数，避免引入整个工具库。 Русский：Данный пакет является утилитарной библиотекой без зависимостей, объем уже оптимизирован (≤5КБ после сжатия). Если нужно дополнительно уменьшить объем, рекомендуется использовать способ импорта по мере необходимости, импортируя только те функции, которые нужны в проекте, вместо всей утилитарной библиотеки.

六、许可证 / Лицензия

中文：本npm包基于MIT许可证开源，您可以自由使用、修改、复制和分发本包，无需经过作者许可，只需在复制或分发的副本中保留原版权声明和许可证说明。 Русский：Данный пакет npm распространяется под лицензией MIT, вы можете свободно использовать, модифицировать, копировать и распространять данный пакет без разрешения автора, необходимо только сохранить исходное уведомление о авторском праве и описание лицензии в копиях или распространяемых версиях.

MIT License

Copyright (c) 2026 你的名字（Ваше имя）

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

七、作者信息 / Информация об авторе

中文：作者：wusheng Русский：Автор: у шэн 中文：邮箱：[email protected] Русский：[email protected]