局域网服务与 ZIP
ling.server 在本机开一个 HTTP 服务,让同一网络里的手机、电脑用浏览器访问,写法照搬 Node 的 http。ling.zip 压缩、解压和查看 ZIP 文件。
ling.server
需要 server 权限。
最小示例
ts
const { interfaces } = await window.ling.server.networkInfo()
const host = interfaces[0].address // 默认网卡在前
const server = window.ling.server.createServer(async (req, res) => {
const url = new URL(req.url, 'http://x')
if (url.pathname === '/') {
res.setHeader('content-type', 'text/html; charset=utf-8')
await res.end('<h1>你好,来自 lingtools</h1>')
} else if (url.pathname === '/upload' && req.method === 'POST') {
const saved = await req.saveTo(`${downloadsDir}/upload.bin`, { exists: 'rename' })
await res.end(JSON.stringify(saved))
} else {
res.statusCode = 404
await res.end('not found')
}
})
await server.listen(0, host)
const { port } = server.address()!
showQrCode(`http://${host}:${port}/`) // 让手机扫码访问网络与监听
| 方法 | 说明 |
|---|---|
server.networkInfo(): Promise<{ hostname, interfaces }> | 本机名和可监听的地址。每项 { name, type: 'wifi' | 'ethernet' | 'other', address, family, isDefault },默认网卡在前 |
server.createServer(listener?) | 创建服务(这时还没开端口) |
httpServer.listen(port, host) | 开始监听。host 必须是 networkInfo() 列出的地址或 127.0.0.1 / ::1,不接受 0.0.0.0;port 为 1024–65535,0 由系统分配。端口被占用时以 address_in_use 失败 |
httpServer.address() | 实际地址和端口 |
httpServer.close() | 停止监听并断开全部连接 |
httpServer.maxConnections | 同时连接数上限,默认 64,最大 256(在 listen 前设置) |
httpServer.setTimeout(ms) | 连接空闲超时 |
每个页面最多同时开 4 个服务。服务属于开它的页面,页面或插件关闭时自动关闭。第一次监听时系统可能弹出防火墙提示,用户拒绝后其他设备连不上,但 listen 仍然成功。
请求 req
| 成员 | 说明 |
|---|---|
method、url、httpVersion、headers、rawHeaders | 同 Node;url 是原样的路径加查询,用 new URL(req.url, 'http://x') 解析 |
socket.remoteAddress / remotePort / remoteFamily | 访客地址 |
text() / json() / bytes() | 读完整个请求体 |
for await (const chunk of req) | 流式读请求体 |
saveTo(path, { exists?, maxBytes? }) | 把请求体直接写成文件,不经过页面,适合上传大文件;exists 为 'error'(默认)、'overwrite'、'rename' |
响应 res
| 成员 | 说明 |
|---|---|
statusCode、setHeader、getHeader、removeHeader、writeHead、write、end | 同 Node,write / end 返回 Promise |
sendFile(path, { downloadName? }) | 发送文件,不经过页面:自动处理 Range(断点续传)、ETag、Content-Type 等。绝对路径是磁盘文件(按文件权限规则检查,出于安全一律带 CSP: sandbox,HTML / SVG 等作为下载);相对路径是插件自己的文件,适合给访客提供网页 |
eventStream() | 把响应变成 SSE 事件流:stream.send(event, data) 推消息、stream.close();每 25 秒自动保活 |
on('close', fn) | 响应结束或访客断开 |
httpServer.broadcast(event, data) 向这个服务的全部事件流推一条消息,适合「电脑上的变化实时推给所有手机」。
WebSocket
ts
const server = window.ling.server.createServer({ allowedOrigins: ['https://example.com'] })
server.on('websocket', (ws, req) => {
ws.on('message', (data) => void ws.send(`echo: ${data}`))
})
await server.listen(0, host)websocket 事件必须在 listen 之前注册。ws 的接口是 npm ws 包的子集:send(不超过 1 MiB)、close、on('message' | 'close' | 'error')。httpServer.clients() 返回当前的全部连接。
安全提示
服务对同一网络里的所有设备开放。不需要时及时 close();涉及用户文件时,用随机路径或一次性口令防止被同一网络里的其他人访问。
ZIP
ling.zip 不需要单独的权限,路径按文件权限规则检查(读插件目录外的文件需 fs.read,写需 fs)。只支持 ZIP 格式。
| 方法 | 说明 |
|---|---|
zip.compress(sources, dest, options?) | 把多个文件 / 文件夹打成一个 ZIP,每个来源以自己的名字放在包的根目录;返回 { path, files, size, originalSize } |
zip.extract(archive, destDir, options?) | 解压到目录(不存在时创建);返回 { files, skipped, size } |
zip.list(archive) | 不解压,列出条目 { name, directory, size, compressedSize, modified, encrypted }[] |
ts
const controller = new AbortController()
await window.ling.zip.compress([folder, file], `${desktop}/打包.zip`, {
level: 6,
signal: controller.signal,
onProgress: ({ files, totalFiles }) => (progress.value = files / totalFiles),
})| 选项 | 说明 |
|---|---|
level(压缩) | 0–9,默认 6;0 只存储不压缩(照片、视频本来就压不动,存储最快) |
overwrite(压缩) | 目标已存在时覆盖,默认 false |
onConflict(解压) | 目标里已有同名文件时:'error'(默认,什么也不写)、'skip'、'overwrite'、'rename' |
maxBytes(解压) | 解压总大小上限,默认 8 GiB |
signal、onProgress | 取消与进度 |
安全保护:解压前先检查全部条目,路径越出目标目录、条目超过 10 万个、解压后过大、压缩比异常(疑似压缩炸弹)时整体拒绝,什么也不写;加密的条目不支持。压缩和解压都先写临时文件,失败或取消不会留下半个结果。