JavaScript事件监听器生成器

代码实现

/**
 * 专业事件监听器：表单提交（submit）
 * 需求：
 * - 阻止默认提交
 * - 校验邮箱格式与密码强度
 * - 逐项高亮错误并显示提示
 * - 提交时禁用表单与按钮
 * - 使用 fetch 异步提交
 * - 成功后清空并显示成功条
 * - 失败则聚焦首个错误
 */
(function initSignupForm(selector = 'form#signup') {
  const form = document.querySelector(selector);
  if (!form) {
    console.warn(`[signup] 未找到表单元素：${selector}`);
    return;
  }

  // 防止重复绑定同一个表单（避免内存泄漏/事件冲突）
  if (form.dataset.bound === 'true') return;
  form.dataset.bound = 'true';

  // 可配置：服务端接口（默认使用 form.action / form.method）
  const submitURL = form.action || '/api/signup';
  const submitMethod = (form.method || 'POST').toUpperCase();

  // 提升可访问性：禁用原生HTML5校验，由脚本接管
  form.noValidate = true;

  // 常用字段引用（可按需扩展）
  const fields = {
    email: form.querySelector('input[name="email"]'),
    password: form.querySelector('input[name="password"]'),
  };

  // 提交过程的中断控制（防止重复请求、支持取消）
  let currentAbortController = null;

  // 安全的 CSS 选择器转义（兼容性处理）
  const cssEscape = (name) =>
    window.CSS && typeof window.CSS.escape === 'function'
      ? window.CSS.escape(name)
      : String(name).replace(/([^\w-])/g, '\\$1');

  // 状态栏：用于展示成功/错误信息（无侵入，自动创建）
  function getStatusBar() {
    let bar = form.querySelector('.form-status');
    if (!bar) {
      bar = document.createElement('div');
      bar.className = 'form-status';
      bar.setAttribute('role', 'status');
      bar.setAttribute('aria-live', 'polite');
      bar.hidden = true;
      form.prepend(bar);
    }
    return bar;
  }

  function showStatus(type, message) {
    const bar = getStatusBar();
    bar.textContent = message; // 使用 textContent 防止 XSS
    bar.dataset.type = type;   // 可用于样式区分：success/error/info
    bar.hidden = false;
  }

  // 错误消息容器：优先使用同一字段附近的 .error-msg，没有则自动创建
  function getErrorContainer(input) {
    const inField = input.closest('.field');
    let msg = inField?.querySelector('.error-msg');
    if (!msg) {
      const next = input.nextElementSibling;
      if (next && next.classList && next.classList.contains('error-msg')) {
        msg = next;
      }
    }
    if (!msg) {
      msg = document.createElement('div');
      msg.className = 'error-msg';
      msg.hidden = true;
      input.after(msg);
    }
    return msg;
  }

  function setFieldError(input, message) {
    if (!input) return;
    const msg = getErrorContainer(input);
    input.classList.add('is-invalid');
    input.setAttribute('aria-invalid', 'true');

    // 确保错误消息有可被关联的ID
    if (!msg.id) {
      msg.id = `${input.name || input.id || 'field'}-error`;
    }
    input.setAttribute('aria-describedby', msg.id);

    // 显示错误文本
    msg.textContent = message;
    msg.hidden = false;
    msg.setAttribute('role', 'alert');
  }

  function clearFieldError(input) {
    if (!input) return;
    input.classList.remove('is-invalid');
    input.removeAttribute('aria-invalid');
    input.removeAttribute('aria-describedby');

    const msg = getErrorContainer(input);
    msg.textContent = '';
    msg.hidden = true;
    msg.removeAttribute('role');
  }

  // 基础校验：邮箱与密码
  function isValidEmail(email) {
    // 简洁实用的邮箱校验（避免过度严格导致合法邮箱无法通过）
    const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return re.test(email);
  }

  function assessPasswordStrength(pw) {
    const categories = [
      /[A-Z]/.test(pw),        // 大写
      /[a-z]/.test(pw),        // 小写
      /[0-9]/.test(pw),        // 数字
      /[^A-Za-z0-9]/.test(pw), // 特殊字符
    ];
    const count = categories.filter(Boolean).length;
    const strong = pw.length >= 8 && count >= 3; // 至少8位，四类中满足任意三类
    return { strong, count, length: pw.length };
  }

  function validateFields() {
    const errors = [];

    if (fields.email) {
      clearFieldError(fields.email);
      const val = fields.email.value.trim();
      if (!val) {
        setFieldError(fields.email, '邮箱不能为空');
        errors.push(fields.email);
      } else if (!isValidEmail(val)) {
        setFieldError(fields.email, '邮箱格式不正确');
        errors.push(fields.email);
      }
    }

    if (fields.password) {
      clearFieldError(fields.password);
      const val = fields.password.value;
      const res = assessPasswordStrength(val);
      if (!val) {
        setFieldError(fields.password, '密码不能为空');
        errors.push(fields.password);
      } else if (!res.strong) {
        setFieldError(
          fields.password,
          '密码需至少 8 位，并包含大小写、数字或特殊字符中的任意 3 类'
        );
        errors.push(fields.password);
      }
    }

    return errors;
  }

  // 禁用/启用表单控件（提交阶段防止重复操作）
  function setFormDisabled(disabled) {
    const controls = form.querySelectorAll('input, select, textarea, button');
    controls.forEach((el) => {
      // 不改变隐性不可用状态的元素（例如有 data-skip-disable 时）
      if (el.dataset.skipDisable === 'true') return;
      el.disabled = disabled;
    });
    form.setAttribute('aria-busy', String(disabled));
    form.dataset.disabled = String(disabled);
  }

  // 序列化表单为对象（FormData -> Object）
  function serializeFormToObject() {
    const fd = new FormData(form);
    const obj = Object.create(null);
    for (const [key, value] of fd.entries()) {
      // 处理同名字段为数组
      if (obj[key] !== undefined) {
        Array.isArray(obj[key]) ? obj[key].push(value) : (obj[key] = [obj[key], value]);
      } else {
        obj[key] = value;
      }
    }
    return obj;
  }

  // 提交到服务端（fetch）
  async function postJSON(url, data, signal) {
    const resp = await fetch(url, {
      method: submitMethod,
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      body: JSON.stringify(data),
      signal,
      credentials: 'same-origin',
    });

    const contentType = resp.headers.get('content-type') || '';
    let payload = null;
    if (contentType.includes('application/json')) {
      payload = await resp.json();
    } else {
      // 非JSON情况也尽量解析（并避免使用 innerHTML）
      payload = await resp.text();
    }

    if (!resp.ok) {
      const err = new Error('请求失败');
      err.status = resp.status;
      err.payload = payload;
      throw err;
    }
    return payload;
  }

  function focusFirstError(inputs) {
    const target = inputs.find((el) => el && typeof el.focus === 'function');
    if (target) target.focus();
  }

  function clearFormAndErrors() {
    form.reset();
    Object.values(fields).forEach(clearFieldError);
  }

  // 提交事件处理函数
  async function onSubmit(e) {
    e.preventDefault();

    // 若当前正在提交，忽略重复触发
    if (form.dataset.disabled === 'true') {
      return;
    }

    // 客户端校验
    const invalids = validateFields();
    if (invalids.length > 0) {
      showStatus('error', '请修正标注的错误后再提交');
      focusFirstError(invalids);
      return;
    }

    // 开始提交：禁用表单，显示状态
    setFormDisabled(true);
    showStatus('info', '正在提交...');

    // 确保只存在一个进行中的请求
    if (currentAbortController) currentAbortController.abort();
    currentAbortController = new AbortController();

    try {
      const data = serializeFormToObject();
      const result = await postJSON(submitURL, data, currentAbortController.signal);

      // 成功：清空表单，清理错误，显示成功条
      clearFormAndErrors();
      showStatus('success', '注册成功');
    } catch (err) {
      // 服务端返回字段级错误：尝试逐项显示
      let focused = false;
      if (err.payload && typeof err.payload === 'object' && err.payload.errors) {
        const serverErrors = err.payload.errors;
        const erroredInputs = [];
        Object.keys(serverErrors).forEach((name) => {
          const input = form.querySelector(`[name="${cssEscape(name)}"]`);
          if (input) {
            setFieldError(input, String(serverErrors[name]));
            erroredInputs.push(input);
          }
        });
        showStatus('error', err.payload.message || '提交失败，请检查表单内容');
        if (erroredInputs.length) {
          focusFirstError(erroredInputs);
          focused = true;
        }
      }

      // 其他错误：网络问题/非结构化错误
      if (!focused) {
        showStatus('error', '网络或服务器错误，请稍后重试');
        focusFirstError([fields.email, fields.password].filter(Boolean));
      }
    } finally {
      setFormDisabled(false);
    }
  }

  // 输入时即时反馈（事件委托，提升性能与可维护性）
  function onInput(e) {
    const t = e.target;
    if (!t || !t.name) return;

    // 只对表单控件处理
    if (!(t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement || t instanceof HTMLSelectElement)) {
      return;
    }

    // 即时清理错误并给出轻量校验提示
    if (t.name === 'email') {
      clearFieldError(t);
      const val = t.value.trim();
      if (val && !isValidEmail(val)) {
        setFieldError(t, '邮箱格式不正确');
      }
    } else if (t.name === 'password') {
      clearFieldError(t);
      const val = t.value;
      const res = assessPasswordStrength(val);
      if (val && !res.strong) {
        setFieldError(t, '密码强度不足（至少8位，含大小写/数字/特殊字符中的任意3类）');
      }
    }
  }

  // 绑定事件监听器（遵循现代标准，避免废弃API）
  form.addEventListener('submit', onSubmit, { capture: false });
  form.addEventListener('input', onInput, { capture: false });
})('form#signup');

技术说明

• 事件类型：submit
  • 在表单提交时触发，默认行为会刷新页面或跳转。通过 e.preventDefault() 阻止默认提交，改为自定义异步处理。
  • submit 事件会冒泡，可绑定在 form 元素上进行统一处理。
• 事件传播与委托
  • 对 input 事件采用委托，统一绑定到 form 上，减少对每个字段单独绑定，降低内存占用与维护成本。
• addEventListener 参数
  • 第三个参数使用对象形式 { capture: false }，明确在冒泡阶段监听，便于与其他监听器协作。
• 校验策略
  • 邮箱：使用实用型正则，避免过度限制。
  • 密码强度：长度至少 8，并在大写/小写/数字/特殊字符中满足任意 3 类。
• 可访问性
  • 使用 aria-invalid、aria-describedby、role="alert" 与 role="status"/aria-live 提升辅助技术支持。
• 提交安全与健壮性
  • 使用 fetch + JSON，避免不安全的 innerHTML，所有消息通过 textContent 设置，防止 XSS。
  • 使用 AbortController 防止重复提交和中断前一次请求。
  • 支持服务端返回字段级错误并逐项展示。

参数解析

• 元素选择器：'form#signup'
  • 用于定位目标表单。代码中支持传入自定义选择器。
• 事件类型：'submit'
  • 绑定在 form 上，统一处理提交逻辑。
• 回调逻辑：
  • 阻止默认提交：e.preventDefault()
  • 校验邮箱与密码：isValidEmail、assessPasswordStrength、validateFields
  • 高亮错误与提示：setFieldError/clearFieldError，对每个字段单独处理
  • 提交时禁用表单与按钮：setFormDisabled(true/false)
  • 异步提交：postJSON(fetch)，使用 JSON 格式
  • 成功：clearFormAndErrors() + showStatus('success', ...)
  • 失败：服务端字段错误映射 + 聚焦首个错误；网络错误展示通用提示并聚焦首字段

使用示例

• HTML 示例（可根据你的页面结构调整类名与样式）

<form id="signup" action="/api/signup" method="POST">
  <div class="field">
    <label for="email">邮箱</label>
    <input id="email" name="email" type="email" autocomplete="email" required />
    <div class="error-msg" hidden></div>
  </div>

  <div class="field">
    <label for="password">密码</label>
    <input id="password" name="password" type="password" autocomplete="new-password" required />
    <div class="error-msg" hidden></div>
  </div>

  <button type="submit">注册</button>

  <!-- 状态条会自动插入为 .form-status（如果不存在） -->
</form>

<script src="signup-listener.js"></script>

• 测试用例
  1. 留空邮箱/密码后点击“注册”：应在对应字段下显示错误提示，并聚焦到第一个错误。
  2. 填入不合法邮箱，例如 "abc@x": 显示“邮箱格式不正确”。
  3. 填入弱密码，例如 "abcd1234": 显示“密码强度不足”。
  4. 填入合法邮箱和强密码，提交：显示“正在提交...”，随后“注册成功”，并清空表单。
  5. 服务端返回字段错误（例如 { errors: { email: '该邮箱已注册' } }）：应在邮箱处显示服务端错误，并聚焦邮箱。

注意事项

• 兼容性
  • fetch 与 AbortController 在现代浏览器中支持良好；若需支持旧版浏览器（如 IE），请引入相应 polyfill。
  • CSS.escape 在部分旧环境不存在，代码已内置回退处理。
• 安全性
  • 所有文本展示使用 textContent，避免 XSS。
  • 建议在服务端开启 CSRF 防护；本示例使用 credentials: 'same-origin'。
• 性能与维护
  • 使用事件委托减少监听器数量。
  • 使用 dataset.bound 防止重复绑定导致的内存泄漏或事件冲突。
• 可访问性与用户体验
  • 对错误消息设置 aria-attributes，提升读屏器体验。
  • 在提交过程设置 aria-busy，并禁用控件防止重复操作。
• 样式建议
  • 为 .is-invalid、.error-msg、.form-status 配置适当样式，例如错误红色提示、状态条成功绿色/错误红色等。
• 服务端协议约定
  • 建议返回 JSON：
    • 成功：{ ok: true, ... }
    • 失败：{ ok: false, message: '...', errors: { fieldName: '错误文案' } }
  • 非 JSON 返回将以文本形式处理并给出通用错误提示。

代码实现

/**
 * 搜索输入框联想下拉（可取消请求 + 300ms 防抖 + ARIA 无障碍）
 * - 目标元素：#searchInput
 * - 事件类型：input
 * - 需求：
 *   1) 300ms 防抖
 *   2) 输入长度 >= 2 才发请求
 *   3) 调用候选接口获取结果
 *   4) 渲染下拉列表并使用 ARIA 属性
 *   5) 请求中显示 loading
 *   6) 支持取消上次请求
 *   7) 清空输入时移除结果
 */
(function initSearchAutocomplete() {
  const config = {
    selector: '#searchInput',
    minLength: 2,
    debounceMs: 300,
    // 建议替换为你的真实接口地址
    endpoint: '/api/suggest?q=',
    // 将接口返回的结果映射为 { id, label } 结构
    mapResultItem: (item) => ({
      id: item.id ?? String(item.value ?? item.id ?? item),
      label: item.label ?? item.name ?? String(item.label ?? item),
      raw: item
    }),
    // 可选：最多显示条数（前端裁剪）
    maxItems: 10
  };

  const input = document.querySelector(config.selector);
  if (!input) {
    console.error(`[autocomplete] element not found for selector: ${config.selector}`);
    return;
  }

  // ARIA & DOM 结构
  const listboxId = `${input.id || 'searchInput'}-listbox`;
  const listbox = document.createElement('ul');
  listbox.id = listboxId;
  listbox.role = 'listbox';
  listbox.className = 'autocomplete-listbox';
  listbox.hidden = true;
  // 让容器紧随输入框，便于定位
  input.insertAdjacentElement('afterend', listbox);

  // 输入框 ARIA 属性（简化 combobox 模式）
  input.setAttribute('role', 'combobox');
  input.setAttribute('aria-autocomplete', 'list');
  input.setAttribute('aria-expanded', 'false');
  input.setAttribute('aria-controls', listboxId);
  input.setAttribute('aria-haspopup', 'listbox');

  // SR（屏幕阅读器）状态区域，用于播报加载与结果数
  const srStatus = document.createElement('div');
  srStatus.setAttribute('aria-live', 'polite');
  srStatus.setAttribute('aria-atomic', 'true');
  srStatus.className = 'sr-only'; // 你可在 CSS 中设置 .sr-only 进行隐藏但可读
  input.insertAdjacentElement('afterend', srStatus);

  // 状态管理
  let debounceTimer = null;
  let abortController = null;
  let requestSeq = 0; // 防竞态
  let isComposing = false; // 输入法合成中（中文/日文等）

  // 工具函数
  const setExpanded = (expanded) => {
    input.setAttribute('aria-expanded', String(expanded));
    listbox.hidden = !expanded;
  };

  const clearList = () => {
    listbox.innerHTML = '';
    listbox.hidden = true;
    input.setAttribute('aria-expanded', 'false');
    input.setAttribute('aria-busy', 'false');
    srStatus.textContent = '';
  };

  const renderLoading = () => {
    listbox.innerHTML = '';
    const li = document.createElement('li');
    li.className = 'autocomplete-loading';
    li.setAttribute('role', 'presentation');
    li.textContent = 'Loading...';
    listbox.appendChild(li);
    input.setAttribute('aria-busy', 'true');
    setExpanded(true);
    srStatus.textContent = 'Loading';
  };

  const renderError = (message = 'Network error') => {
    listbox.innerHTML = '';
    const li = document.createElement('li');
    li.className = 'autocomplete-error';
    li.setAttribute('role', 'presentation');
    li.textContent = message;
    listbox.appendChild(li);
    input.setAttribute('aria-busy', 'false');
    setExpanded(true);
    srStatus.textContent = message;
  };

  const renderResults = (items) => {
    listbox.innerHTML = '';
    input.setAttribute('aria-busy', 'false');

    if (!items || items.length === 0) {
      setExpanded(false);
      srStatus.textContent = 'No results';
      return;
    }

    const frag = document.createDocumentFragment();
    items.slice(0, config.maxItems).forEach((item, idx) => {
      const li = document.createElement('li');
      li.role = 'option';
      li.tabIndex = -1;
      li.dataset.id = item.id;
      // 使用 textContent 防止 XSS
      li.textContent = item.label;
      // 唯一 id 便于 aria-activedescendant（如后续扩展键盘导航）
      li.id = `${listboxId}-opt-${idx}`;
      frag.appendChild(li);
    });
    listbox.appendChild(frag);
    setExpanded(true);

    const countText = `${items.length} result${items.length > 1 ? 's' : ''}`;
    srStatus.textContent = countText;
  };

  const cancelOngoing = () => {
    if (abortController) {
      abortController.abort();
      abortController = null;
    }
  };

  // 具体请求函数（支持取消）
  const fetchSuggestions = async (query, seq, signal) => {
    const url = `${config.endpoint}${encodeURIComponent(query)}`;
    const res = await fetch(url, { signal, headers: { 'Accept': 'application/json' } });
    if (!res.ok) {
      throw new Error(`HTTP ${res.status}`);
    }
    const data = await res.json();
    // 容错：允许 Array<string> 或 Array<object>
    const items = Array.isArray(data) ? data : (data.items || data.results || []);
    return items.map(config.mapResultItem);
  };

  // 输入处理（防抖调度）
  const scheduleSearch = (query) => {
    if (debounceTimer) clearTimeout(debounceTimer);
    debounceTimer = setTimeout(async () => {
      debounceTimer = null;

      const trimmed = query.trim();
      if (trimmed.length === 0) {
        cancelOngoing();
        clearList();
        return;
      }
      if (trimmed.length < config.minLength) {
        cancelOngoing();
        clearList();
        return;
      }

      // 取消上一次请求
      cancelOngoing();
      abortController = new AbortController();
      const signal = abortController.signal;
      const seq = ++requestSeq;

      renderLoading();

      try {
        const items = await fetchSuggestions(trimmed, seq, signal);
        // 如果期间又发起了新请求，丢弃旧结果
        if (seq !== requestSeq) return;
        renderResults(items);
      } catch (err) {
        if (err.name === 'AbortError') {
          // 被主动取消，忽略
          return;
        }
        renderError('Failed to load results');
        console.error('[autocomplete] request error:', err);
      }
    }, config.debounceMs);
  };

  // 事件处理
  const onInput = (e) => {
    if (isComposing) return; // 输入法合成中，不触发检索
    const value = e.target.value || '';
    scheduleSearch(value);
  };

  const onCompositionStart = () => { isComposing = true; };
  const onCompositionEnd = (e) => {
    isComposing = false;
    // 合成结束后再触发一次
    scheduleSearch(e.target.value || '');
  };

  const onListClick = (e) => {
    const option = e.target.closest('[role="option"]');
    if (!option) return;
    const label = option.textContent || '';
    const id = option.dataset.id;
    input.value = label;
    clearList();

    // 向外派发事件，携带选中项数据
    const detail = { id, label };
    input.dispatchEvent(new CustomEvent('autocomplete:select', { detail, bubbles: true }));
  };

  const onEscape = (e) => {
    if (e.key === 'Escape') {
      clearList();
    }
  };

  const onDocumentClick = (e) => {
    if (e.target === input) return;
    if (listbox.contains(e.target)) return;
    clearList();
  };

  // 绑定监听
  input.addEventListener('input', onInput, { passive: true });
  input.addEventListener('compositionstart', onCompositionStart);
  input.addEventListener('compositionend', onCompositionEnd);
  input.addEventListener('keydown', onEscape);
  listbox.addEventListener('click', onListClick);
  document.addEventListener('click', onDocumentClick);

  // 可选：暴露销毁函数（防止内存泄漏，若需要动态卸载）
  input.autocompleteDestroy = () => {
    cancelOngoing();
    if (debounceTimer) clearTimeout(debounceTimer);
    input.removeEventListener('input', onInput);
    input.removeEventListener('compositionstart', onCompositionStart);
    input.removeEventListener('compositionend', onCompositionEnd);
    input.removeEventListener('keydown', onEscape);
    listbox.removeEventListener('click', onListClick);
    document.removeEventListener('click', onDocumentClick);
    listbox.remove();
    srStatus.remove();
    input.removeAttribute('role');
    input.removeAttribute('aria-autocomplete');
    input.removeAttribute('aria-expanded');
    input.removeAttribute('aria-controls');
    input.removeAttribute('aria-haspopup');
    input.removeAttribute('aria-busy');
  };
})();

可选的最简样式建议（非必需）：

/* 建议样式（示意） */
.autocomplete-listbox {
  position: absolute;
  z-index: 1000;
  margin-top: 4px;
  width: 100%;
  max-height: 240px;
  overflow: auto;
  background: #fff;
  border: 1px solid #ddd;
  border-radius: 6px;
  box-shadow: 0 6px 18px rgba(0,0,0,0.08);
  padding: 4px 0;
}
.autocomplete-listbox li {
  padding: 8px 12px;
  cursor: pointer;
}
.autocomplete-listbox li:hover {
  background: #f5f5f5;
}
.autocomplete-loading,
.autocomplete-error {
  color: #666;
  cursor: default;
}
.sr-only {
  position: absolute !important;
  width: 1px; height: 1px;
  margin: -1px; padding: 0; overflow: hidden;
  clip: rect(0 0 0 0); border: 0;
}

技术说明

• 事件类型 input
  • 在用户每次输入（含粘贴、删除）都会触发，适合实时联想。
  • 配合 composition 事件，避免中文等输入法在合成中频繁请求。
• 防抖机制
  • 通过 setTimeout 实现 300ms 防抖，减少高频请求，提升性能与配额利用率。
• 取消请求
  • 使用 AbortController/AbortSignal，输入变化时取消上一次 fetch，避免无用的网络与竞态渲染。
• 竞态防护
  • 使用自增的 requestSeq 标记请求顺序，仅渲染最后一次有效请求的结果，消除响应乱序问题。
• ARIA 无障碍
  • 输入框设置 role=combobox、aria-controls、aria-expanded、aria-autocomplete、aria-haspopup。
  • 下拉列表使用 role=listbox，选项使用 role=option。
  • 使用 aria-live polite 播报“Loading”和结果数量。
• 事件委托
  • 仅在 listbox 容器绑定一次 click 事件，通过事件冒泡处理每个选项，减少监听器数量。

参数解析

• selector: 目标输入框选择器（本题为 #searchInput）。
• minLength: 触发请求的最小字符长度（默认 2）。
• debounceMs: 防抖等待时间，默认 300ms。
• endpoint: 候选接口基础地址，自动拼接 ?q=encodeURIComponent(query)。
• mapResultItem(item): 将接口原始数据统一映射为 { id, label, raw }，便于渲染和选择回传。
• maxItems: 前端显示的最大条数限制，避免一次渲染过多 DOM。

内部状态与函数：

• abortController: 管理可取消的 fetch。
• requestSeq: 防止竞态条件，确保只渲染最新请求。
• renderLoading/renderResults/renderError/clearList: 负责 UI 状态与 ARIA 标记。
• scheduleSearch: 结合防抖与最小长度校验进行请求调度。

使用示例

• 直接使用（替换为你的接口地址）：

<input id="searchInput" type="text" placeholder="Search..." autocomplete="off" />
<script src="/path/to/autocomplete.js"></script>
<script>
  // 如需监听选中事件
  document.getElementById('searchInput').addEventListener('autocomplete:select', (e) => {
    console.log('Selected:', e.detail); // { id, label }
  });
</script>

• 模拟接口（开发联调用）：

<input id="searchInput" type="text" placeholder="Search..." autocomplete="off" />
<script>
  // 替换示例中的 endpoint 和 fetch 函数（简单模拟）
  // 方案1：本地服务返回 /api/suggest?q=foo -> ["foo1","foo2",...]
  // 方案2：在 Service Worker 或 dev server 做 mock
</script>

• 自定义映射：

// 若接口返回 { items: [{id: 1, name: 'Apple'}, ...] }
 // 上面的 mapResultItem 已默认兼容 name/label。若字段更复杂可重写：
 // config.mapResultItem = item => ({ id: item.id, label: `${item.name} (${item.category})`, raw: item });

注意事项

• 兼容性
  • AbortController 在现代浏览器中已普遍支持。若需兼容旧浏览器，可在不支持时跳过取消逻辑（请求仍可完成）。
• 性能与可维护性
  • 使用事件委托避免对每个建议项单独绑定事件。
  • 使用 textContent 而非 innerHTML 防止 XSS 注入。
  • 尽量限制渲染数量（maxItems），大量结果应采用分页或虚拟列表。
• 无障碍与键盘交互
  • 当前实现包含基本 ARIA 标注与状态播报；若需要完整键盘导航（上下选中、回车确认、aria-activedescendant 同步），可在此基础上扩展 keydown 逻辑。
• 交互细节
  • 输入清空（长度为 0）时自动取消请求并清空列表。
  • Escape 键可关闭列表。
  • 点击列表项会派发 autocomplete:select 事件，便于上层逻辑处理（例如跳转或再次请求详情）。
• 错误处理
  • 网络错误或非 2xx 响应会显示通用错误消息并写入控制台，便于排查。
• 销毁与内存
  • 若组件需要在 SPA 中卸载，可调用 input.autocompleteDestroy() 解除所有监听并清理 DOM，避免内存泄漏。
• 安全
  • 严禁拼接 HTML 字符串插入，始终使用 DOM API 与 textContent 设置文本内容。