文水鱼文集外观库

水鱼文集 · 外观库

把界面,
调成你喜欢的样子。

水鱼文集是一个跑在自己 NAS 上的文集应用:书架、文章、标签、阅读进度,全在你自己手里。 它允许你上传一个 .js 换掉整套界面——内置五套,剩下的 21 套在这里, 都是别人写好的。下载、上传、生效,没有插件市场,不用登录。

21套外观
7个分类
64 KB单文件上限
0依赖与跟踪
灯下 · waterfish · 7ae29bc

这个窗口是真的在跑这套主题,不是截图。书架是假的,CSS 变量是真的。

01

先说清楚它是什么

水鱼文集(Waterfish Anthology)是一个自托管的个人文集应用,跑在你自己的 NAS 上。 你把书和文章放进去,它给你一个安静的书架:封面、作者、读到哪儿了,一屏看完。

它不联网同步、不做推荐、不统计你读了几分钟。数据就在自己机器的目录里, 备份就是拷一个文件夹,换机器就是搬过去。界面用什么字体、纸是什么颜色, 也由你决定——内置五套,不够就自己写一套。

主页在 waterfish.ren, 外观系统怎么写,作者在 这篇说明 里讲得很细。

  • 书架卡片式陈列,封面、作者、进度一眼看到
  • 阅读正文排版,衬线或圆体、字号大小都能调
  • 标签按标签翻,不用记文件名
  • 深浅色跟随系统或手动切,每套外观自带两套配色
  • 外观五套内置加自定义 .js,就是下面这些
  • 数据存在自己的 NAS 上,一个账号一份配置
03

三步,二十秒

不需要命令行,不需要改配置文件。

STEP 1

挑一套

每套都有独立页面,能当场切浅色深色、看它在卡片和列表上的样子。别看缩略图,看真的。

STEP 2

下载 .js

点「下载」,或者把代码复制走自己存成文件。文件名就是主题名,所以叫 湖心纸.js 比叫 theme1.js 好。

STEP 3

上传

设置 → 外观 → 自定义主题 → 选择文件。卡片出现就生效了,立即保存,不用确认。最多存 20 个。

想换回来?在抽屉里点「纸墨」就是内置外观。不想要了就悬停卡片,点右下角的 ✕,它带来的样式和图标会一起清干净。

04

它为什么不是一个配色表

一开始我也想只让人填几个颜色。但很快就不够了:有人希望卡片悬浮时抬起来一点, 有人想把图标换成自己画的那套,有人觉得标题字距太挤、正文行高太松。这些都不是「颜色」, 是样式和动效,用 JSON 填不出来。

所以主题就是一个 JS 文件。你可以只写三行键值对(主色: #1F6C9F), 也可以写一个 function theme(api),拿到 api 之后调 CSS 变量、注入样式、换图标。 两种写法在同一个文件里,客户端自己判断。

每次应用主题前,客户端会先把上一次的东西全部清掉——变量回退、样式移除、图标还原。 所以复杂主题每次都是从干净状态开始跑,不会越叠越乱;写错了也只是控制台报个错,界面退回内置外观,不会白屏。

主题只在你自己的浏览器里运行,跟着外观配置存在你的账号下。这点很重要, 下一页会说我们怎么保证没人借这个入口干别的。

  • api.setVar()改根元素上的 CSS 变量,比如 --accent、--r
  • api.css()注入一段 style,动效、字距、阴影都写在这里
  • api.icon()用 SVG path 覆盖内置图标,颜色跟随 currentColor
  • api.dark当前是不是深色,可以写两套配色
  • api.el根节点,想查哪个元素都行——也是风险所在
05

怎么防止有人动手脚

说难听点:主题代码在你浏览器里的权限,和页面本身一样大。

它跑在页面主世界(main world),能读 DOM、能发请求。所以这个库不能「谁都能直接 push」。 投稿走 GitHub issue,收进来之前过三道:

  1. 静态规则。一段代码里出现 eval、new Function、 网络请求、读写 cookie 或 localStorage、动态插 script、改 location、监听键盘—— 任意一条,直接拒,不看别的。
  2. 模型读一遍。规则只看关键词,看不出「把正文里的链接批量改掉」这种事。 所以再让一个语言模型把代码读一遍,判断它到底想干什么。模型也会看错,所以它只给建议。
  3. 我自己点。最后一步是人。我点「approved」再关 issue, 机器人这时才会把文件写进仓库、生成页面。

已经收录的也可能变坏——比如它引用了别人域名下的一张图,哪天那张图换成了别的东西。 发现了就下架,不会因为「已经收了」就留着。

  • 会拒eval / new Function / 动态 import / 任何网络请求
  • 会拒读写 cookie、localStorage、sessionStorage
  • 会拒改 location、开新窗口、postMessage、伪造表单
  • 会拒外链脚本、长期轮询、键盘监听
  • 会看非字体 CDN 的远程资源、超长 base64、不认识的键

完整规则在仓库的 scripts/lib/rules.mjs, 改了什么都能看到。

06

常被问到的

会不会拖慢打开速度?

一个主题最多 64 KB,绝大多数只有几十行 CSS 变量。真正让页面变慢的是背景图——如果你挂了一张 2 MB 的图,慢的是那张图,不是主题。

能改布局吗?

技术上能。api.el 给你根节点,你可以在里面查任何元素、加类名。但类名会随版本变,写得越深越容易坏。库里大部分主题只动变量和表面样式,就是为了少坏。

主题存在哪?换设备还在吗?

存在你账号下的外观配置里,跟着账号走,换设备登录还在。卸载应用会一起清掉,所以删之前记得把 .js 留一份。

为什么「推荐」不能投稿?

那几套是我自己天天在用的,颜色改了几十遍才定下来。开放投稿它就会变成投票榜,我不想那样。看到合适的,我会主动去要。

收录之后还能撤吗?

能。你开个 issue 说一声,或者我发现行为不对,直接下架。下架不会删历史——文件还在 git 里,只是不再出现在列表。

我能直接提 PR 吗?

可以,但目录名必须是内容哈希,手算容易错。建议还是走 issue,机器人会算好。PR 走的校验和 issue 是同一套。

手上正好有一套管用的配色?

交上来,写清楚它叫什么、你想要什么分类。审核完就是别人的一个下午。

去投稿