市舶司 介绍

一、项目概述

市舶司是一个功能丰富、轻量化的聚合搜索工具页面，核心定位是集成多搜索引擎与实用辅助功能于一体，满足日常搜索、快速跳转、个性定制等多种需求。项目采用纯前端技术栈（HTML + CSS + JavaScript），无需后端服务与复杂部署，直接打开即可使用。内置指令系统（如 /go 快速跳转、/Email 打开邮箱）、自定义搜索引擎、搜索历史记录、天气面板、个性化背景与主题切换、常用应用管理、灯光走廊游戏、知乎热搜等特色功能，整体页面轻量美观，支持 PWA 安装为应用，适配 PC 与移动端。

二、核心功能实现

2.1 多引擎搜索功能

功能详情

内置必应、百度、搜狗、360、Yandex、抖音、哔哩哔哩、360AI、magi、腾讯下载、网易云音乐、QQ音乐、DuckDuckGo、GitHub、Google 等十余款常用搜索引擎，支持用户下拉选择目标引擎，输入关键词后触发搜索；空值输入时自动跳转对应搜索引擎主页。

核心优化

全程实现新标签页打开搜索结果，保留原页面不跳转；支持回车键快速触发搜索；保留原有代码标注，便于后期回溯与维护。

技术要点

通过 JavaScript 获取用户输入与引擎选择值，拼接对应搜索 URL，借助 window.open 实现新标签页跳转，对 URL 进行编码处理适配特殊字符，空值时拆分链接提取引擎主页。

2.2 自定义搜索引擎

功能详情

用户可自由添加自定义搜索引擎，填写标识（英文 id）、显示名称和搜索 URL（用 %s 表示关键词位置），支持编辑和删除已添加的引擎，保存后自动显示在引擎下拉列表中。

技术要点

通过 SearchEngineManager 管理自定义引擎列表，数据持久化存储在 localStorage 中，支持增删改查操作，编辑模式锁定标识符不可修改。

2.3 指令系统（/ 魔法棒）

功能详情

在搜索框输入 / 可触发指令面板，支持 /go 目标名 实现快速页面跳转、/Email 打开邮箱等快捷指令。点击指令芯片可自动填入搜索框，按 Enter 执行。

技术要点

通过 JavaScript 监听输入框内容变化，匹配指令前缀，调用对应处理函数实现跳转；/go 指令的目标列表从 commands.json 动态加载。

2.4 搜索历史记录

功能详情

自动保存用户的历史搜索记录，点击记录可重新搜索，支持一键清空全部记录。

技术要点

通过 SearchHistoryManager 管理搜索历史，数据持久化存储在 localStorage 中，支持新增、渲染、清空操作，页面加载与 bfcache 后退导航时自动恢复历史列表。

2.5 个性化背景切换功能

功能详情

提供多种背景模式：必应每日壁纸、随机动漫壁纸（新浪壁纸 API）、高清壁纸、Loveanimer壁纸（含动漫、风景、游戏分类）、360壁纸（含4K专区、美女模特、爱情美图、风景、小清新、动漫、明星、萌宠、游戏、汽车、炫酷、军事、劲爆、纹理、文字、限时等分类）、无背景（跟随主题颜色），同时支持上传自定义本地壁纸图片，并有独立开关控制是否启用背景图。

核心优化

通过 localStorage 本地缓存用户选择的背景模式，刷新页面后自动恢复上次设置；CSS 样式兜底，保证页面加载无空白，背景全屏居中展示且固定不随滚动偏移。

技术要点

通过 JavaScript 修改 body 行内样式切换背景图，搭配 localStorage 实现本地持久化存储；支持 FileReader 读取本地图片转为 base64 后存储，自定义壁纸开关通过复选框控制背景启用状态。

2.6 天气面板

功能详情

页面展示实时天气信息，数据来源 uapis.cn，自动获取并显示当前天气状况，支持实况、预报、空气质量、生活提示四个标签页。

技术要点

通过 fetch 请求天气 API，解析返回数据后渲染到天气卡片中，支持加载状态提示，图标懒加载优化性能。

2.7 主题切换功能

功能详情

支持浅色、深色、蓝主题、红主题、绿主题、跟随系统、跟随时间共七种主题模式，满足不同使用场景下的视觉需求。

技术要点

通过 JavaScript 动态切换 CSS 变量与 body class，搭配 localStorage 持久化主题选择；跟随系统模式使用 prefers-color-scheme 媒体查询，跟随时间模式根据当前小时自动切换。

2.8 常用应用管理

功能详情

用户可自定义添加常用网站应用，支持自动获取网页信息（标题、图标、描述），可编辑、删除应用，支持拖拽排序，默认提供示例应用（哔哩哔哩、GitHub、知乎）。

技术要点

通过 localStorage 存储应用数据，支持图标懒加载，使用代理 API 获取网页信息，支持颜色自动匹配主流网站品牌色。

2.9 灯光走廊游戏

功能详情

内置灯光走廊互动小游戏，提供休闲娱乐功能。

技术要点

独立的游戏模块，包含完整的游戏逻辑和样式文件。

2.10 知乎热搜

功能详情

实时展示知乎热榜内容，点击可跳转查看详情。

技术要点

通过 API 获取知乎热榜数据，动态渲染到页面。

2.11 浮动工具栏与卡片控制

功能详情

页面右下角提供浮动工具按钮，支持全屏显示切换、搜索框显隐切换、壁纸刷新、所有卡片显隐切换，以及天气、应用、灯光走廊、知乎热搜等卡片的独立显示控制。

技术要点

通过 Full Screen API 实现全屏切换，通过 JavaScript 控制元素显隐，使用 localStorage 持久化卡片显示状态，支持滚动到指定卡片并高亮闪烁效果。

三、代码模块拆分

3.1 CSS 样式模块

• primoUI.css — 核心 UI 组件样式，包括模态框、卡片、标签页、按钮组、主题切换、滑块开关等通用组件；
• style.css — 页面全局布局样式，包含导航栏、搜索区居中布局、下方卡片区、背景过渡效果、媒体查询等；
• search.css — 搜索框与搜索引擎选择面板样式，包含输入框、下拉选单、指令辅助网格、搜索记录列表等；
• float-tool.css — 浮动工具栏样式，包含悬浮按钮组、图标按钮与文字按钮布局；
• game-lights-out.css — 灯光走廊游戏样式；
• game/LightCorridor/LightCorridor.css — 灯光走廊游戏独立样式文件。

3.2 HTML 结构模块

• 导航栏 — 品牌标识、设置按钮、PWA 安装按钮；
• 搜索区 — 品牌标题、搜索输入框、引擎下拉选单、魔法棒按钮、搜索按钮；
• 下方卡片区 — 搜索引擎面板（含指令 / 自定义引擎 / 搜索记录三个子标签页）、天气面板、常用应用卡片、灯光走廊游戏、知乎热搜卡片；
• 浮动工具栏 — 全屏切换、搜索框显隐切换、壁纸刷新、卡片显隐控制按钮；
• 设置弹窗 — 颜色主题、背景选择、关于信息、帮助支持四个标签页；
• 应用管理弹窗 — 添加应用、管理应用两个弹窗。

3.3 JavaScript 功能模块

• primoUI.js — 核心 UI 控制，包括弹窗显隐、主题切换与持久化、标签页切换；
• search2.js — 搜索功能主模块，封装 redirectToSearch 函数，实现引擎匹配、关键词处理、URL 拼接与新标签页跳转，含空值跳转主页逻辑，卡片显隐控制；
• background.js — 背景切换模块，封装 setBg 函数实现多种背景模式切换，搭配 localStorage 缓存与页面加载自动读取，支持自定义壁纸上传与开关控制；
• pwa.js — PWA 安装功能，监听 beforeinstallprompt 事件并提供安装按钮交互；
• sw.js — Service Worker 注册，支持离线缓存与 PWA 功能；
• weather.js — 天气面板模块，通过 fetch 请求天气 API 并渲染到页面，支持多个标签页懒加载；
• FullScreen.js — 全屏功能模块，通过 Full Screen API 实现全屏切换；
• TextCopy.js — 文本复制功能，支持一键复制分享文案；
• IMGCopy.js — 图片复制功能，支持一键复制图片到剪贴板；
• lazyload.js — 图片懒加载功能，优化页面加载性能；
• utils.js — 工具函数模块；
• instruction/go.js — /go 指令模块，实现快速页面跳转，目标列表从 commands.json 动态加载，集成搜索引擎管理与搜索历史管理；
• instruction/Email.js — /Email 指令模块，一键打开邮箱页面；
• instruction/commands.json — /go 指令目标列表配置文件；
• game/LightCorridor/LightCorridor.js — 灯光走廊游戏逻辑；
• api/Portal/ZhihuHotSearch/HotSearch.js — 知乎热搜 API 模块；
• api/Portal/weibouHotSearch/HotSearch.js — 微博热搜 API 模块；
• index.html 内嵌脚本 — 应用管理（增删改查、拖拽排序）、表单交互、图标懒加载初始化等逻辑。

四、关键问题解决

原代码存在原标签跳转、新标签空白问题，通过优化 window.open 调用逻辑，摒弃原页面跳转代码，规范 URL 拼接与赋值方式，实现纯新标签页打开，无页面跳转冲突。

单纯 JS 设置样式会在刷新后失效，新增 localStorage 本地存储用户选择的背景类型，页面加载时自动读取缓存并赋值，实现背景持久化展示；同时新增自定义壁纸上传与开关控制，解决壁纸切换后的状态管理问题。

用户添加的自定义搜索引擎需要在页面刷新后保留，通过 SearchEngineManager 配合 localStorage 实现数据的增删改查与本地持久化存储，页面加载时自动恢复已有引擎列表。

搜索历史需要保留最近记录、避免重复、支持一键清空，通过 SearchHistoryManager 管理历史数组，利用 Set/Timestamp 去重排序，限制最大存储条数，实现高效的历史记录管理。

/ 指令需要在用户输入时实时匹配，同时不影响正常搜索功能，通过监听 input 事件判断输入内容前缀，匹配指令时拦截回车事件跳转到对应目标，不匹配时执行正常搜索。

用户从搜索结果页通过浏览器后退返回时，部分动态内容（搜索历史、自定义引擎列表）可能未恢复，通过监听 pageshow 事件重新渲染相关 UI，确保后退导航后的功能完整性。

摒弃复杂整合代码，拆分独立功能模块，保留用户原有标注内容，不随意删减备用代码，便于后期功能调整、bug 修复与功能拓展。

用户添加的应用需要在刷新后保留，通过 localStorage 存储应用数据，支持增删改查与拖拽排序，页面加载时自动恢复应用列表。

各功能卡片（天气、应用、游戏、热搜）支持独立显隐控制，状态通过 localStorage 持久化，页面加载时自动恢复用户偏好设置。

大量图标和背景图会影响页面加载性能，通过懒加载技术延迟加载非首屏图片，提升页面加载速度。

五、使用说明

将完整代码部署到任意静态托管服务（如 Cloudflare Pages），或用浏览器直接打开 HTML 文件即可运行，无需额外部署环境或安装依赖。

下拉选择搜索引擎，输入搜索关键词，点击搜索按钮或按下回车键，新标签页自动跳转搜索结果；无输入时点击搜索，跳转对应引擎主页。

在搜索框输入 / 可触发魔法棒功能，弹窗中可选择 /go 快速跳转（如 /go bilibili）或 /Email 打开邮箱；指令芯片点击即可自动填入搜索框，按 Enter 执行。

在搜索引擎面板的「自定义引擎」标签页中，填写标识（英文）、显示名称和搜索 URL（用 %s 表示关键词位置），点击添加即可生效；支持编辑和删除已有自定义引擎。

搜索结果自动保存至历史记录，点击任意记录可重新搜索，支持一键清空全部记录。

在设置弹窗的「背景」标签页中，可选择必应每日壁纸、随机动漫壁纸、高清壁纸、Loveanimer壁纸、360壁纸等多种壁纸源，也可上传本地图片作为自定义壁纸，通过开关控制背景图显隐。

在设置弹窗的「颜色主题」标签页中，可切换浅色、深色、蓝、红、绿五种色彩主题，以及跟随系统和跟随时间两种自动模式。

点击应用卡片的「添加」按钮，输入网址后自动获取网页信息（标题、图标、描述），也可手动编辑；点击「管理」按钮可编辑或删除已添加的应用，支持拖拽排序。

页面右下角浮动工具按钮支持一键全屏显示、隐藏/显示搜索框、刷新壁纸、隐藏所有卡片，以及单独控制天气、应用、灯光走廊、知乎热搜卡片的显隐状态。

打开灯光走廊卡片即可体验互动小游戏。

打开知乎热搜卡片即可查看实时热榜内容，点击热榜条目可跳转知乎查看详情。

点击导航栏的「安装」按钮可将本应用安装为桌面 PWA 应用，支持离线使用（需 Service Worker 支持）。

可直接修改引擎链接、背景 API、页面文字等内容，保留的标注代码可按需取消注释，恢复备用功能。

六、项目亮点

• 轻量化极简 纯前端实现，无后端依赖，单页面即可运行所有功能，加载速度极快，占用资源极少；
• 多引擎聚合 内置 15 款常用搜索引擎，覆盖综合搜索、视频、音乐、代码、AI 等各类场景，一键切换；
• 指令快捷操作 / 魔法棒指令系统，支持 /go 快速跳转、/Email 打开邮箱等快捷操作，提升使用效率；
• 高度可定制 支持自定义搜索引擎、自定义壁纸背景、多种主题模式、搜索框显隐、常用应用管理等，满足个性化需求；
• 数据持久化 主题、背景、自定义引擎、搜索历史、应用列表、卡片状态等用户配置均通过 localStorage 持久化存储，刷新不丢失；
• PWA 支持 支持安装为桌面渐进式应用，离线可使用基础功能，提供接近原生应用的体验；
• 易维护拓展 模块化设计 + 代码标注，后期可轻松增删搜索引擎、更换背景 API、优化页面样式；
• 兼容性强 适配主流浏览器（Chrome、Edge、Firefox 等），PC 与移动端均可正常使用；
• 功能丰富 集成天气、常用应用、游戏、热搜等多种实用功能，一站式满足日常需求；
• 性能优化 图片懒加载、代码模块化拆分，提升页面加载速度和运行性能。

七、关于你的隐私

本项目为纯静态网页，无后端服务、无数据上传、无用户信息收集，所有功能仅在本地浏览器运行，不会向任何第三方服务器发送您的个人数据（天气数据请求 uapis.cn 公开 API、知乎热搜 API、微博热搜 API 除外）。您的配置数据（主题、背景、自定义引擎、搜索历史、应用列表、卡片状态等）仅存储在您本地浏览器的 localStorage 中，不会上传至任何云端。搜索关键词仅通过您选择的搜索引擎进行查询，市舶司本身不会记录或分析您的搜索行为。

八、版本号

版本号规则

版本关系历史