Web Dev on Louis's blog

关于ClientWebAPI

Thu, 22 May 2025 02:48:59 +0000

看到了Hono.JS的介绍，其中有一个部分是它可以 run everywhere，因为其使用了Web API Standard。

正好自己之前对这些Web API一知半解，所以简单复习了一部分。

DOM / BOM Manipulation

主要是利用了document、window等对象来操作DOM和BOM。

document：提供操作文档的方法。例如querySelector、getElementById等。通过这种script可以让网页动态化等等。
window：表示浏览器窗口的对象，可以知道比如说窗口的dimension，也可以操作例如滚动窗口到哪些地方。一些event handler也是直接绑在window上。
- 也因此复习了一下可以监听的events，例如scroll。使用addEventListener可以绑定事件处理函数，removeEventListener可以解绑事件处理函数避免内存泄漏。
history：表示浏览器的历史记录，可以用来操作浏览器的前进后退等功能。

Fetch API

应该是后端接触最多的一种API了。 Request和Response是两个最重要的对象。

二者基本上都可以调用类似的方法来进行解析。

.formData()：将数据解析为FormData对象，文件也会被自动解析为File对象。
.json()：将JSON数据解析为JavaScript对象。
.text()：将文本数据解析为字符串。
.arrayBuffer()：将数据解析为ArrayBuffer对象。（可以用来直接处理二进制数据）

除此之外Response还有.ok、.status、.statusText等属性可以用来判断请求是否成功。

另外一般地，如果没有特殊需求的情况下，基本上API endpoint都是用json或multipart/form-data来传输数据，比较少直接传输二进制数据或者单纯的text。

Local Storage 和 Session Storage

存储在浏览器中的key-value pair，每一个origin都有自己的独立存储空间。不同的是：

localStorage：存储的数据在浏览器关闭后仍然存在，除非被purge。多个同origin的tab之间是共享的。
sessionStorage：存储的数据在浏览器关闭或标签页关闭后会被删除。按照标签页隔离。

关于html图片和相关css的随记

Mon, 19 May 2025 09:49:36 +0000

最近因为参加了一个hackathon重新捡起了前端，然后发现styling这方面需要和组友合作很多所以开始重新inspect一些css的细节。

今天想要谈一些关于前端中图片的使用。

1. 图片的宽高

图片是一个replacement element，自己有一个intrinsic size。但是其真实显示的大小是由CSS来决定的。

HTML best practice是务必给图片加上width,height和alt属性。这样网页会预留好空间来放这个图片，避免layout shift。与此同时也会知道图片的宽高比。这样css控制时就会知道图片原始的比例。

注意css中，width和height是可以是relative的。我以前的误解是这个东西必须是绝对数值，可以看看下面我为什么会产生这个误解（。

img {
  width: 50%; /* 相对于父元素 */
  height: auto; /* 让浏览器自动计算高度，保持宽高比 */
}

2. Next.JS中的Image

Next.JS中Image组件中必须用绝对数值specify的width和height是决定图片的intrinsic size。最终渲染的大小是css决定的。

这个就是我以为css中必须是绝对数值的原因。

另外一个就是Next.JS可以使用fill来让图片充满父元素，这个时候就不用width和height。

然而一个细节就是默认这个时候这个图片的position是absolute的。所以要记得设置父元素/祖先元素为非static的position。

3. 关于`<img>`的display

<img>的display是inline的。

因此其实可以通过styling来改变其display的方式使得它不必包裹在一个<div>中也能服从良好的布局。

之前有一篇文章说最好要用<div>包裹图片，现在想想也不一定。事实上object-fit和object-position都不必再来一个<div>来包裹图片，这些效果会直接作用于画框（<img>）上。

MDN object-fit

MDN object-position

4. 关于text-align

text-align其实不单单是用来控制文字的，任何inline的元素都可以用这个属性来控制。

所以理所当然地你可以用这个来居中图片（只要你还没有改变它的display，默认是inline）

img {
  text-align: center;
}

MDN text-align

5. 关于如何学习CSS的一个说法

看到一句话说CSS不能使用传统的程序员思维来学习，更多是随用随查，多用。但是底层的一些概念要搞懂。

有一个学习路线说的是搞懂四个概念：

选择器，样式，盒模型，定位

个人感觉总结的还是很不错的，事实上很多时候颠来倒去的奇妙bug和不优雅的实现也是因为这些概念没有扎实引起。

以后可以参考这个学习路线来再吃一遍css。

HTML/CSS/JS核心记忆索引

Mon, 17 Feb 2025 14:28:25 +0000

这篇文章提供一个个人的快速索引，旨在以后忘记 html,css,js 时能尽快恢复大部分的核心知识。

这篇文章的要求的知识范畴是：知道这些东西能让你更有自信地使用框架（例如 React）。

详细的语法大部分不会包括在内，大部分时候你可以直接查询。

这不是一篇教学笔记。

HTML

HTML 是一种 markup language，渲染时形成 DOM Tree.

HTML 提供块级元素和内联元素（虽然新标准提供更加详细而复杂的分类，但是可以这么来表现）。

HTML 可以展示文字，图片，视频，音频，画布，以及超链接。

HTML 可以表现不同的标题，强调，斜体，horizontal line，上下标。

HTML 的 tag 一些具有语义。对于一个页面其结构一般是header, nav, main, aside （侧边栏）, footer. 对于部分一般使用section。

只有在没有适合语义的时候（例如对一组元素做 styling 时）才使用无语义的块级元素<div> 和内联元素<span>。此外，<h1>一般一个页面只用一次，方便 SEO。

HTML 的 header 可以设置 title 标题，charset, favicon，description 描述，lang 语言等元信息。这些对于 SEO 非常重要。

元素参考

Header 相关的设置

CSS

层叠

CSS 层叠样式表的核心是层叠。

层叠体现在：顺序（后来的会覆盖前面的），优先级（一套优先级计算机制），继承（一些属性，例如颜色，会被子元素继承）。

层叠规则

选择器

CSS 通过选择器来进行元素的选定。你可以用 id，class，或者 type (html tag 的类型) 来选定。

CSS 也可以选择后代或者多个条件同时满足的元素。

选择器语法

伪类与伪元素

伪类可以选择一个元素在特定的状态下的样式，例如 hover。用单个冒号，形如:hover。

伪元素可以选择一个元素并且为其添加一个虚拟元素，这个虚拟元素如同其子元素，所以你可以通过relative, absolute来 style 它。用双冒号，形如::after。

伪类和伪元素

盒模型

在 CSS 中，一切都是盒。

盒模型

两个注意点：

用【替代盒模型】是现代最佳实践，其 width 和 height 描述的是 content + padding + border
Margin 可以为负并且产生 merge。

盒有三种外部表现：block, inline, inline-block。（块级/内联）

最大的区别就是：是否换行，width/height 设置是否有效，是否把周围元素推开。

内部表现包含flex和grid。

flex是弹性盒模型。它可以让元素在一维上对齐，并且可以让元素按照自己的内容伸缩（flex-1, etc.）

display属性定义了内部和外部的表现。

display

弹性盒模型 flexbox

字体样式与字体栈

在 font-family 中堆叠一系列字体，最后一个字体为系统默认字体的标识，以确保字体可用。这被称为字体栈。

p {
  font-family: "Trebuchet MS", Verdana, sans-serif;
}

保底字体为：serif（衬线），sans-serif（无衬线），monospace（等宽，一般用于代码）

字体

布局流与定位技术

默认地，文档将按照默认布局流进行排布。

CSS 利用position将元素移出默认布局流，并且用inset等来定位他们。以下改写自 mdn。

静态定位（static）：放在默认位置。
相对定位 (relative): 相对于原来其【应该在的默认位置】进行移动。
绝对定位 (absolute): 相对于其最近被定位祖先元素（比如被设置为relative的）。 如果祖先树不存在这样的元素，那么相对于<html>进行调整。 （所以你需要指定一个祖先元素为relative然后才能正常使用absolute）
固定定位（fixed）: 相对于视窗。
粘性定位（sticky）: 先保持和 static 一样的定位，当它的相对视口位置（offset from the viewport）达到某一个预设值时，它就会像 position: fixed 一样定位。

布局流

层叠层 (Cascading Layer)

用层级来调整 css 的优先度，使得一系列样式可以被定义在同一个@layer中，并定义覆盖顺序。

@layer theme，layout，utilities;

@layer layout {
  main {
    display: grid;
  }
}

在 tailwind 中是核心概念。（base, component, utilities）

注意。未分层的层外样式优先权比任何层内样式都高。

层叠层

Javascript

此处不涉及 js 基本语法，异步编程 etc.，只涉及浏览器中重要的模式和知识。

事件与事件冒泡

DOM node 可以触发事件，可以登记 callback 以响应事件。

在一个 dom node 触发的事件会默认冒泡至其父节点。

callback 中的event ((e) => {...})中包含了一些重要信息。

e.target：触发了这个事件的元素。
e.currentTarget：处理这个事件的元素（这个 callback 被 register 的元素。例如说，冒泡的时候，target 就会是这个子元素，currentTarget就是目前事件到达的父元素）。
e.preventDefault()：禁止默认行为（例如表单中按钮的默认行为是提交表单）

Web APIs

提供一些重要的 Web API。

客户端重要的 objects:

Window：可以得到窗口大小等信息。
Navigator：媒体流等信息。
Document：操作 DOM（增加 node 等等）

客户端存储 objects：

sessionStorage: 浏览器关闭时会消除的 kv pairs。
localStorage：会持续保存，浏览器重启也不会消除的 kv pairs。

获取数据：

fetch

客户端 Web API

mdn CSS 概要记录 - 选择器和盒子模型

Sun, 16 Feb 2025 15:37:49 +0000

学习 tailwind 之后想学习一下 CSS 的基础概念，所以去翻了 mdn CSS 基础。

有一些选择器感觉是非常适合原来的 vanilla CSS 而设计出来的，但是对于 tailwind 这种 utility-based 的 CSS framework 不太常用（一个例子是+这种兄弟 selector）。

所以记录一下比较核心的概念（相对经常用到的）。这篇文章主要写选择器和盒子模型。

1. 选择器

选择器选定 HTML DOM Tree 中的既定元素，并且增加对应的样式。

以下是一些很常用的选择器样式的格式。

/* 选择一种html tag类型 */
h1 {
}

/* 选择一个类 */
.class1 {
}

/* 选择一个id */
#id1 {
}

/* 有title属性的锚元素（anchor）*/
a[title] {
}

/* 有href, 并且href是"https://example.com"的元素 */
a[href="https://example.com"]
{
}

/* *****复合选择器***** */
/* 选择一个既有class1又有class2的h1 element */
h1.class1.class2 {
}

/* 后代选择器：选择为div的子元素的p (后代) */
div p {
}

/* *****伪类与伪元素***** */
/* 伪类 用:标记 */
a:hover {
}

/* 伪元素 用::标记 */
a::after {
  /* 必须设置content属性，即使是空字符串。 */
  content: "";
}

2. 伪类和伪元素

这个对我是一个比较新的概念。

伪类指的是在特定状态下才被 apply 的选择器。比如说：hover 的时候。

伪元素创造一个虚拟元素。它可以被视为目标元素的子元素。例如说，可以用::before或者::after在元素前后添加新内容。也可以精准选定第一行等等。

除了在元素前添加图标之外，由于可以被视为目标的子元素，因此理论上也可以对目标元素使用relative，然后子元素使用absolute来添加覆盖该元素的阴影或者动画效果。

这里有一个类似 Material design 的水波纹效果的例子。

button {
  position: relative; /* 让 ::after 绝对定位时相对这个按钮 */
  overflow: hidden; /* 防止水波超出按钮 */
  background: #3498db;
  color: white;
  border: none;
  padding: 12px 24px;
  cursor: pointer;
  font-size: 16px;
}

button::after {
  content: "";
  position: absolute;
  top: 50%;
  left: 50%;
  width: 200%;
  height: 200%;
  background: rgba(255, 255, 255, 0.3);
  transform: translate(-50%, -50%) scale(0);
  border-radius: 50%;
  transition: transform 0.4s ease-out, opacity 0.4s ease-out;
}

button:active::after {
  transform: translate(-50%, -50%) scale(1);
  opacity: 0;
}

感觉不少 css 特效的底层都用到了伪元素，算是解答了心中的一个疑惑。

3. 盒模型

我超！盒！

盒模型是 CSS 的基础之一，包含content, padding, border, margin。

盒子的参数可以被归纳为：外部显示类型和内部显示类型。

3.1 外部显示类型(outer display types)

block
- 产生换行。
- 高宽设置(width, height)有效。
- padding, border, margin 会将其他元素推开。
- 未指定宽度时，通常直接占到 100%父容器的宽度。
inline
- 不产生换行。
- 高宽设置无效。
- padding, border, margin 会被应用。水平的边距会把其他元素推开。但是，垂直边距不会把其他inline元素推开。也就是说，如果溢出的话，会和其他inline元素重叠。
inline-block
- 是inline和block的 mix。
- 不产生换行。
- 高宽设置(width, height)有效。
- padding, border, margin 会将其他元素推开。

3.2 内部显示类型(inner display types)

通常指的是flex, grid这种掌管内部元素排布的类型。

3.3 替代盒模型

Tailwind 默认使用的是替代盒模型。(事实上，替代盒模型也是现代 css 开发的最佳实践。)

.box {
  box-sizing: border-box;
}

原有的盒模型，width和height指的是盒子的内容大小，也就是实际大小应该加上padding和border。

替代盒模型中，width和height指的是盒子可见范围的大小，也就是算进了padding和border的大小。

3.4 细节：外边距折叠 Margin Collapsing

算是一个细节，这里引用原文。

外边距是盒子周围一圈看不到的空间。它会把其他元素退推离盒子。

外边距属性值可以为正也可以为负。在盒子一侧设置负值会导致盒子和页面上的其他内容重叠。

但是，当两个外边距重合的时候，有一套独特的计算方法。

简而言之就是“合并取最大”。

根据外边距相接触的两个元素是正边距还是负边距，结果会有所不同：

两个正外边距将合并为一个外边距。其大小等于最大的单个外边距。

两个负外边距会折叠，并使用最小（离零最远）的值。

如果其中一个外边距为负值，其值将从总值中减去。

以上。

Next.JS的ESLint + Prettier设置

Sun, 16 Feb 2025 11:03:44 +0000

简单记录一下在设置自己东拼西凑全栈的 ESLint + Prettier 的小 tips 和坑。

技术栈

首先贴一下自己最近接触 Web dev 之后选择/脑补出来的技术栈，设想的使用场景是个人的兴趣开发，PoC 或者是小规模应用。

Javascript / Typescript / React
Meta-framework: Next.JS
- 前后端可以同时开发，感觉还是很不错的。
CSS: TailwindCSS
组件调试: Storybook
UI 库: shadcn-ui，lucide-react（图标）
- 这个很看个人的爱好，我个人挺喜欢 shadcn 的设计语言。
认证系统: Auth.JS
- 懒人，开箱即用.jpg
ORM: Prisma
输入/输出验证: Zod
测试框架: Jest
Format/Linting：ESLint + Prettier
OpenAPI：next-swagger-doc
表单: react-hook-form

Email 方面目前还没有需求，目前看着 resend 不错。

关于 ESLint + Prettier 的设置

项目开始的时候自然要设置一下 Format 和 linting。虽然 ESLint 也有 formatting 的功能，但是 Prettier 胜在开箱即用，据 stackoverflow 而言速度也快。

这次的方法针对的是配合 tailwindcss 的设置。

设置完你的 next.js（利用create-next-app）。你的 tailwind 应该也在这个时候设置完毕了。
安装 prettier。

npm i -D prettier

为了防止 prettier 全局扫描时也扫描 node_modules 的全部文件，创建一个.prettierignore。

//.prettierignore
node_modules

prettier 存在一个配合 tailwindcss 的 plugin，可以按照 tailwind 推荐的方式来 rearrange classes。详见这里。

我们首先安装一个 plugin。

npm install -D prettier-plugin-tailwindcss

然后，准备一个prettier.config.mjs。（写这篇文章时 prettier config 对 ts 的支持仍在 beta，所以用 mjs 以求稳定性。）

const config = {
  plugins: ["prettier-plugin-tailwindcss"],
};

export default config;

由于 eslint 和 prettier 可能会在 formatting 上发生冲突，所以安装一个 prettier 的官方包 eslint-config-prettier，让 eslint 来处理 linting，prettier 来处理 formatting。由于具体 config 方法各异，请参考这个 repo 的 README，给出了非常详尽的步骤。
（可选）可以打开 vscode 的自动 formatting-on-save。
- 在 marketplace 安装 Prettier 的插件。
- 搜索default formatter。
- 设置 Default formatter 为 Prettier-code formatter。
- 搜索format on save并将其打开。

现在可以快乐地使用了！只要按 Ctrl+S 就会自动做好 formatting，让你的代码更加可读。

利用RadixUI的Overlay解决方案

Wed, 05 Feb 2025 08:59:05 +0000

shadcn-ui中有一个Dialog组件可以很快速地创建Dialog + Overlay。其基本功能就是会显示一个黑色覆盖层，并且覆盖层中间会弹出一个窗口作为Dialog。

但是shadcn-ui中的组件已经经过充分定制。有些时候自己已经设计好了一份弹窗，不想要shadcn的predefined style。一种方法是去修改shadcn源码，另一种方法是直接用shadcn底层的radix来写，客制化程度更高。

这里我们用一个例子，假设我们已经有了一个Component叫做MemberCard，我们想要：

使用一个占满全屏的Overlay
当click到卡片外部的区域时，关闭这张MemberCard
拥有Radix的各种功能，例如无障碍，Esc退出等等。

import * as Dialog from '@radix-ui/react-dialog';
import { motion } from 'framer-motion';
import { MemberInfo } from '@/types/MemberInfo';
import MemberCard from './MemberCard';
import { VisuallyHidden } from '@radix-ui/react-visually-hidden';

interface CardDialogProps {
  isOpen: boolean;
  onClose: () => void;
  member: MemberInfo;
}

const CardDialog: React.FC<CardDialogProps> = ({ isOpen, onClose, member }) => {
  return (
    <Dialog.Root open={isOpen} onOpenChange={onClose}>
      {/* Portal负责把这个组件送出dom，通常在body的下方。
      这样它就不会受到事件冒泡和父元素CSS（例如z-index）等的影响。 */ }
      <Dialog.Portal>
        {/* 透明的Overlay，记得设置覆盖全屏。 */ }
        <Dialog.Overlay className="fixed inset-0 bg-black/50 backdrop-blur-sm z-50"/>
        {/* 为了将Dialog Content居中，这里需要一个div来做flex styling。它的大小也是充满全屏的。 */ }
        <div className='fixed inset-0 z-50 flex items-center justify-center'>
          {/* 将组件包裹在这里。注意Content要和组件一样大。
          这样才能触发onPointerDownOutside，达到点击背景退出的效果。 */ }
          <Dialog.Content className="w-3/4 max-w-7xl outline-none" onPointerDownOutside={onClose}>
            {/* Radix的Dialog必须存在Title来触发无障碍。这里我们用VisuallyHidden隐藏。 */ }
            <Dialog.Title asChild>
              <VisuallyHidden>
                {member.name} personal information
              </VisuallyHidden>
            </Dialog.Title>
            
            {/* 卡片容器 */}
            <motion.div
              initial={{ scale: 0.3 }}
              animate={{ scale: 1 }}
            >
              <MemberCard {...member} />
            </motion.div>
          </Dialog.Content>
        </div>
      </Dialog.Portal>
    </Dialog.Root>
  );
};

export default CardDialog;

然后就可以快乐解决了！

另外，虽然这里用了workaround，但是其实非常多的东西都可以用shadcn-ui解决，感觉它覆盖了95%以上的日常开发需求。

前端学习：开发游戏公会的PR Page中学到的

Sat, 01 Feb 2025 07:30:04 +0000

最近找到工作之后心血来潮地想学一下前端，第一个想自己做一些漂亮的网页，第二个是作为后端了解前端在做什么可以更好地了解整体的landscape。

正好自己之前为所属的mmo公会(BP你死的好惨啊.jpg)做过一个网页，但是当时的网页是直接抄的模版，所以基本上就是填入想要的东西就可以，主要的学习点是用Cloudflare。所以这次就决定从零做起。

1. 技术选型

前端库: React with Typescript （后期转向了Next.JS框架）
框架: Next.JS
CSS: Tailwind
UI库: shadcn/ui
UI动画: motion
云服务: Cloudflare

考虑到这个app不需要任何的后端逻辑，只是一个展示用的app，而且想接触到稍微不太难的底层，所以使用了这个组合。虽然到后期熟悉了一些React之后，还是投入了Next.JS。

说起来，前段时间在学校的时候另一位同学和我猛猛吐槽tailwind，但是一把梭真的好爽啊尤其是对于没有学过前端的人而言。

此外，Cloudflare真的是拯救了穷穷的我。

2. Style component的基本思路

这是我第一次使用tailwind或者说正经地学习css，并且确实是我觉得最痛苦也最烦躁的一部分之一。还好我们有tailwind。

相应地，总结了一部分思路，个人觉得参照这些思路就可以决定自己需要哪些properties了。

2.1 定位方式

HTML的默认定位方式是static，也就是说元素会按照文档流正常排列，不受定位影响。

所以如果想改变位置，必须指定 relative? absolute? fixed? sticky?。这些决定了你定义component的坐标参考。值得一提的是absolute的参考是第一个**非static**的ancestor。

例如说，当你需要覆盖屏幕的overlay的时候就用fixed，它给出的坐标系就是整个视窗，随后再使用inset-0即可。

2.2 Flexbox, grid, container

决定你的容器类型。

flex和grid就不多赘述了，个人感觉要多加使用。例如想要调整唯一元素居中的时候，相比于自己硬写，用justify-center更加鲁棒。

container是tailwind提供的一种可以动态防止你的容器撑到屏幕两端的容器，一般在style全页级的容器的时候很好用。

2.3 位置与大小

接下来就是决定component的位置和大小。

值得注意的是，当设计component的时候不要规定component本身的大小，而应该设计component内部的响应式布局。至于component本身的大小，应当交给其父元素用围绕它的<div>块级元素来进行指定。 component本身使用w-full等适应其父元素，个人觉得会更好。

此外，在使用比例大小和基于vw，vh的大小时有些时候还是要善用max或者min的。它可以防止元素变得过小，也可以防止变得变得过宽盛满元素。这个确实是新的知识，人的视野其实只能集中在屏幕上的一部分，文字太宽的话，会变得难以阅读。

2.4 Padding和Margin

这个就不多赘述了。一般而言p-4(1rem)是一个不错的开始点。

2.5 背景颜色

简单的背景颜色调整不再赘述。

一个很不错的functionality是tailwind的bg-gradient-to-*，可以很愉快的构建出渐变色彩。

此外，透明度也可以很方便地调整。对于颜色是*-color-*/[alpha]，比如说from-gray-900/50。opacity-*也可以帮助调整。

2.6 阴影/圆角/边缘等装饰

Tailwind提供了非常好的rounded-*，border-*和shadow-[size], shadow-[color] 等utilities可以来美化元素。

2.7 图片等的处理

虽然严格上并不算是css相关，但是在处理用Next框架的图片的时候，有一些必要的东西需要知道。

把next/image的Image包在<div>中，再用块级元素去调整它的大小。内层的图片加上fill即可，fill会使得next将图片填满父容器。
object-position和object-fit决定了可替换元素(replaced elements) 在其所占据的box中的位置。可替换元素指的是像图片这种无法被css stylesheet影响到其本身的元素。所以对于图片，视频而言非常重要。

对于object-fit，常用的主要是object-cover（不变形覆盖，无黑边但是会被crop）和object-contain（不变形，完整展示，但是有可能产生黑边）。

需要立刻展示的图片不要忘记了priority
关于sizes，可以使用响应式，因为Next会自动调整fetch的图像的大小。一个栗子是：sizes="(min-width: 1080px) 100vw, 1080px。这样图片就会至少是1080p。

2.8 动画效果

复杂的动画效果建议使用motion库。但是简单的onhover，tailwind的hover:scale-105等等的utility很好用。具体你需要transition-transform duration-500 hover:scale-110的combo。 (transition-transform使得转换变得平滑。)

其他的就是少用的东西了，可以随时查询调整。

总结起来就是五大基础：位置，大小（包括padding/margin的大小），颜色，装饰，动画。图片需要多考虑一下可替换元素的特殊性质和图片的优化。

3.一些问题的解决方法

中途碰到了一些不熟悉的实现在这里也记录一下。

3.1 导入新字体并使用tailwind

下载新字体，并把woff2打包好放在public中。
去global css中设置好font face。
去tailwind.config.ts的theme中添加font family。别忘记加上default themes里面的sans。

3.2 预加载所有的图片后再展示

因为PR page是一系列的图片轮流播放，并且头图比较大，所以有些用户会看到一个碎裂的图像加载出来（网速烂的时候）。

自己想到的解决方法是preload完所有的hero image才开始展示。贴个代码。

    // ...之前的代码
    const [currentIndex, setCurrentIndex] = useState(0);
    const [isInitialLoadComplete, setIsInitialLoadComplete] = useState(false);

    // 在背景第一次进入DOM后预加载，并且通过isInitialLoadComplete来控制。
    useEffect(() => {
        const preloadAllImages = async () => {
            // 封装为Promise，将其加载到浏览器内存。
            const loadPromises = backgroundImagesPath.map((path) => {
                return new Promise<void>((resolve) => {
                    const img = new Image();
                    img.src = path;
                    img.onload = () => {
                        resolve();
                    };
                });
            });

            // 等待全部预加载完毕。
            await Promise.all(loadPromises);
            // 发送预加载信号。
            setIsInitialLoadComplete(true);
        };

        preloadAllImages();
    }, []);

    useEffect(() => {
        if (!isInitialLoadComplete) {
            return;
        }

        // 预加载之后才开始播放轮换动画。
        const interval = setInterval(() => {
            setCurrentIndex((prev) => (prev + 1) % backgroundImagesPath.length);
        }, backgroundShiftIntervalSeconds * 1000);

        return () => clearInterval(interval);
    }, [isInitialLoadComplete]);

3.3 渐变切换的做法以及注意点

轮播的时候图片需要渐变隐出，与此同时下一张图片渐变进入。

这个效果我们可以用framer motion来实现。motion.div可以指定退出的动画。

需要注意的点是，因为motion.div退出的时候，如果直接将其从DOM上移除，那么就不会有退出动画了，会直接消失。

motion的方法是将你要添加退出动画的元素一定要包在一个<AnimatePresence>中。观察DOM可以发现，当元素被卸载时，它会存在这个Presence中一小段时间，直到动画结束才会被卸载。

此外必须要提醒的是，在<AnimatePresence>中存在的元素，一定要一个key。 motion通过检测这个key知道哪些元素发生了变化，从而进行animate。

放一个代码！

useEffect(() => {
        // Wait for initial load to complete
        if (!isInitialLoadComplete) {
            return;
        }

        const interval = setInterval(() => {
            setCurrentIndex((prev) => (prev + 1) % backgroundImagesPath.length);
        }, backgroundShiftIntervalSeconds * 1000);

        return () => clearInterval(interval);
    }, [isInitialLoadComplete]);

    return (
        <div className="relative h-screen w-full overflow-hidden bg-[#190157]">
            <AnimatePresence initial={false}> {/* initial 控制一开始就有的元素是否播放动画 */}
                {isInitialLoadComplete && (
                    <Background
                        key={currentIndex}
                        backgroundImagePath={backgroundImagesPath[currentIndex]}
                        backgroundShiftTransitionDuration={backgroundShiftDurationSeconds} />
                )}
            </AnimatePresence>
        { /* 其他的代码 */ }
    )

3.4 Next的Server-side component与Motion的问题

因为知识不足，被这个坑了老大一把。

Next默认是用React Server Component，所以在使用Motion的时候无法完全兼容，Animate Presence的时候存在glitch。

原因是因为motion使用了effects，这些只有在client端才有。

解决方法是’use client’。

3.5 关于shadcn/ui

可以去globals.css中设置theme colors，非常适合决定好一套颜色之后在全网页通用使用，可以维持审美的一致性。

以上！

这个项目做了三四天，作为小白有不少的收获，记录一下。

关于java数据层的一些想法

Sun, 06 Oct 2024 10:05:57 +0000

今天看了一下java语言是如何访问数据库的，结果被内容和rather verbose的语法冲的头昏脑胀（？）

记录一下我自己对于java数据层结构的一些理解（希望以后不要被自己错误的理解打脸x）

（以及，我会感觉很多语言的数据层结构的philosophy是一样的，所以这个也有助于用来理解其他语言的数据层结构）

最底层：JDBC和HikariCP连接池

JDBC是java访问数据库的标准接口。JDBC提供了一套访问数据库的API，可以通过JDBC来访问数据库，执行SQL语句，获取查询结果等。

它的实现是通过JDBC驱动程序来实现的，不同的数据库有不同的驱动程序。

连接是一个昂贵的资源，所以我们需要有效率地复用连接。连接池解决了这个问题，当需要连接的时候，从连接池中获取连接，使用完毕后，将连接放回连接池。HikariCP是目前常用的一个高性能的连接池。

Hibernate和JPA

聊Hibernate之前得先聊聊JPA。

JPA规范定义了java的对象关系映射（ORM）的标准，将对象映射至数据库的表。它使用Entity Manager来向数据库中CRUD对象，而不需要亲自编写JDBC或者SQL语句。它也提供了查询语言。

（当然它也定义了不少其他的东西）

Hibernate是一个ORM框架，不仅实现了JPA规范，还提供了一些其他的功能。Hibernate可以通过注解来定义实体类和数据库表之间的映射关系。

DAO

DAO（Data Access Object）是一个数据访问对象，用于访问数据库。它提供了一些方法，用于CRUD数据库中的数据。

举一个简单的例子

public interface UserDao {
    User getUserById(int id);
    void insertUser(User user);
    void updateUser(User user);
    void deleteUser(int id);
}

这样用户就不用关心数据库的操作，只需要调用DAO的方法即可，有利于解耦。但是事实上在不少的情况下，service直接操作数据库也是可以的。

Spring的事务管理(Transaction Management)

虽然有点离题，但是spring通过实现一些Transaction Manager来实现事务管理，这样可以保证一组操作要么全部成功，要么全部失败（如果不熟悉事务，可以去看看ACID）。Spring在事务扔出RuntimeException的时候会自动回滚。

所以通常我们建议在处理事务时派生RuntimeException，这样就不用再去手动处理了。

举个栗子：

@Transactional
public void transfer(int from, int to, int amount) {
    User user1 = userDao.getUserById(from);
    User user2 = userDao.getUserById(to);
    user1.setBalance(user1.getBalance() - amount);
    user2.setBalance(user2.getBalance() + amount);
    userDao.updateUser(user1);
    userDao.updateUser(user2);
}

另外注意，在Spring中事务默认是具有传递性的。

也就是说在一个transactional的方法中调用另一个transactional的方法，那么这两个transaction会被合并成一个transaction来执行并共同commit或者rollback。

或者，引用一下廖雪峰老师的精确说明：

“Spring的声明式事务为事务传播定义了几个级别，默认传播级别就是REQUIRED，它的意思是，如果当前没有事务，就创建一个新事务，如果当前有事务，就加入到当前事务中执行。”

Small review on CSS

Sat, 07 Sep 2024 02:07:34 +0000

Though I am not currently proficient in frontend, I do sometimes have to get in touch with HTML/CSS when setting up static pages. Here is some personal note on my recent refresh on CSS (last time I touched it is during my undergrad🫠).

CSS box model

Important concepts include margin, border, padding, and content. Here is a nice illustration from Wikipedia:

Float

Float is a CSS property that specifies whether a box should float to the left, right, or not at all in its parent container. It is commonly used to wrap text around images. Understand it as putting the element “out of the normal flow”.

Psuedo-classes

Psuedo-classes are used to define the special state of an element. For example, :hover is used to define the style of an element when the mouse is placed over it.

a:link {
    color: blue;
}

a:hover {
    color: red;
}

CSS Animations

The @keyframes rule is used to create animations, where the percentage is the time during the animation. For example, the following code will change the background color of an element from red to yellow to blue to green.

@keyframes example {
    0% {background-color: red;}
    25% {background-color: yellow;}
    50% {background-color: blue;}
    100% {background-color: green;}
}

You can also alter the timing function of the animation using the animation-timing-function property, like ease, linear, ease-in, ease-out, cubic-bezier() family, etc.

Responsive layout

Media queries

Media queries are used to apply different styles for different devices, using different breakpoints. The following code will change the background color of an element to yellow when the screen width is less than 600px.

@media only screen and (max-width: 600px) {
    body {
        background-color: yellow;
    }
}

Relative units

In introductory courses px is usually used as the unit of length, but there are a bunch of other units out there that are more responsive. Those incl.:

vw and vh: 1% of the viewport width and height, respectively.
em: Relative to the font-size of the parent element.
rem: Relative to the font-size of the root element.
vmin and vmax: 1% of the viewport’s smaller and larger dimension, respectively.
%: Relative to the parent element.

Logical pixels

I have once thought that how can media handle tablet displays on iPad’s retina or other high-resolution tablets.

Logical pixels is an encapsulation of the physical px in CSS, where device-pixel-ratio is the ratio of physical pixels to logical pixels. This allows for high-resolution displays to display content at a higher resolution without changing the layout of the page.

Setting up Hugo static blog page

Fri, 23 Aug 2024 14:15:58 +0000

Problem setting

When I first tried to build up a blog, I have been thinking about renting a VPS and running a Wordpress instance on it. This is why you have seen the previous blog. But:

VPS costs you, sometimes payment is done annually in one installment.
In terms of a blog, dynamic nature of Wordpress is an overkill.
Have to setup TLS termination proxy, Wordpress and a MySQL instance. Heavy :(

I have seen some of my friends spinning up their blog using Hugo. With the static page hosting service (free!) by Cloudflare Pages, I have decided to give it a try.

In this blog, I’ll mainly talk about the subtle problems I have faced in these sessions besides trivial documentation.

How to setup a Hugo blog
Using the Stack hugo theme
Deploying to Cloudflare Pages
Setting up Front Matter CMS (Content Management System) for easy content creation in vscode

1. Setting up Hugo

Hugo is a static site generator written in Go that is blazingly fast. To start a new hugo project, simply follow the quickstart guide.

`archetypes` front matter template

Hugo uses front matter, a “preamble” in the markdown file to store metadata and control the behavior of the content. In fact here is the front matter of this blog:

---
title: Setting up Hugo static blog page
description: ""
date: 2024-08-23T14:15:58.493Z
preview: "" # This is for `Front Matter CMS`
draft: false
tags: []
categories: []
image: "" # This is for `Stack` theme, the header you have seen in this post.
slug: setting-up-hugo-static-blog-page
---

One (probably annoying thing) about Hugo is that it can use TOML, YAML or JSON for front matter. I like yaml but the default generated content with hugo new post/your-post.md is TOML. In addition, sometimes you do want the autogenerated files have different front matter according to the content type.

The solution is to open the archetypes folder and edit the default.md file, or create new ones such as post.md file. Hugo will match the templates according to the type, e.g. hugo new post/your-post.md will use the post.md template. Check the matching rules.

2. Using the `Stack` hugo theme

If I haven’t changed the theme after I have written this blog🤔, I am using the Stack theme. More than grateful for CaiJimmy for designing this elegant theme. It also has a nice documentation.

For those that would like to set up the frames quickly, here are some steps:

Go to the theme folder of the Stack theme (should be something like themes/hugo-theme-stack), find the config.yaml.
Find the params.sidebar section and fill in the details.

Stack provides menu items on the left and interesting widgets on the right side of the page. To setup those widgets you have to follow some steps:

Create those pages under the content/page folder. The theme relies on those pages to build the widgets.

content/page/archives/index.md

---
title: "Archives"
layout: "archives"
slug: "archives"
menu:
    main:
        params: 
            icon: archives
---

content/page/about/links.md

---
title: Links
links:
  <!-- This is a sample links page to Github. -->
  - title: GitHub
    description: GitHub is the world's largest software development platform.
    website: https://github.com
    image: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png
menu:
    main: 
        params:
            icon: link

comments: false
---

<!-- To use this feature, add `links` section to frontmatter.
`image` field accepts both local and external images. -->

content/page/about/search.md

---
title: "Search"
slug: "search"
layout: "search"
outputs:
    - html
    - json
menu:
    main:
        params: 
            icon: search
---

Notes

You can also add the weight parameter to menu.main.params to change the order of the main menu items.

The icon parameter refers to the SVGs in assets/icons folder in your theme folder. For example, icon: archives refers to assets/icons/archives.svg.

After the creation of those pages, go to the config.yaml file in your theme folder. We first customize the left menu:

# Custom menu configurations
# The `icon` refers to the SVGs in `assets/icons` folder.
# `Stack` uses icons from tabler.io (https://tabler.io/icons), 
# which you can download for customization.
menu:
    main:
        - identifier: home
          name: Home
          url: /
          weight: 1
          params:
            icon: home
            newTab: false
    # Social menu doesn't have text, just a list of icons.
    social:
        - identifier: github
          name: GitHub
          url: <your-github-link>
          params:
            icon: brand-github
            newTab: true

params:
    widgets:
        homepage: 
            - type: "search"
            - type: "archives"
              params:
                limit: 5
            - type: "categories"
              params:
                    limit: 10
        page:
            - type: "toc"

This enables the menu items and widgets.

Fix the code block glitch

A glitch in the current version (Stack v3.26.0) is that the code block has a mysterious black background. This should be a temporary issue but here is the (official) fix:

Go to hugo.yaml (or hugo.toml, if you haven’t changed the configuration file format) in the project root.
Add:

markup:
  highlight:
   noClasses: false

3. Deploying to Cloudflare Pages

In normal circumstances deploying this stack to Cloudflare should be a smooth process.

The Stack v3.26.0 however breaks the Cloudflare automatic page building process, which is probably caused by using an old image version of Hugo. To fix this, in your page build configuration, add the environment variable:

# Change to the newest or compatible Hugo version at your reading time.
HUGO_VERSION=v0.133.0

and it should fix the issue.

4. Setting up Front Matter CMS

Front matter is a vscode extension that runs locally and manages your contents and does SEO. It has high flexibility but setting it up was a nightmare for me (due to my lack of coding skills 😭). Anyways, I provide some key setups aside from the general guidance Front Matter CMS provides, which itself is nice👍.

Markdown front matter template and page bundle support

One thing that you have to notice is that Front Matter does not respect the settings you provided in the archetypes folder. It uses its own template located inside the frontmatter.json generated.

Here is the modification I provide, with three augmentations:

Enable page bundle support.
- Page bundle is a way to organize your resources and an index.md in one folder. If you do not know what a page bundle is, check the Hugo documentation.
Added the slug field. Slug is very important in Front Matter since it use it to open the preview (which I cover in later sections).
Added the image field, which is used by the Stack theme.

Note

I regard it as a very INELEGANT modification since I directly modify the default profile, which I should create a new post profile or somehow.

But I mainly use CMS for writing posts, so, lazy me 🤷.

"frontMatter.taxonomy.contentTypes": [
    {
      "name": "default",
      // When generating page content, use a page-bundle format.
      "pageBundle": true,
      "fields": [
        // ...
        // This is for the header post image in `Stack` theme.
        {
          "title": "Post image",
          "name": "image",
          "type": "image"
        },
        // This is for automatic slug generation.
        {
          "title": "Slug",
          "name": "slug",
          "type": "slug",
          "editable": true,
          "default": "{{slug}}"
        }
        // ...
      ]
    }
  ],

Preview setup

Front Matter CMS uses the slug of the pages to generate the preview. What it actually does is:

Spins up a local server (you have to click the Start server button.)
Generates a link to the page you are currently working on, using the rules here. In short, <preview host URL>/<frontMatter.preview.pathName>/<slug>.
Open a browser based on the link.

It’s important to know that you have to setup the frontmatter.json correctly to use the preview feature. Also, you have to make sure that the preview pathname is correctly set. If not, it will access <hostname>/<slug> rather than, for example, <hostname>/post/<slug> (let’s assume you host posts under the content/post folder).

The difficulty is really to recognize the aforementioned fact - once you understand it it is not hard at all and it is well documented.

Check the documentation here to modify the generated frontmatter.json by adding previewPath property according to the instructions.

5. Epilogue

Let’s shift away from the technical story and talk about something rather personal.

Sometimes I do think trying new thing is a hard time, but it still provides that dopamine surge that supports you to work until five in the morning. I have had a long chat with one of my friend, on the essence of software engineering (I probably will write a blog afterwards on this topic). What he essentially said is that SWE is an art for solving the problems, and it really depends on your experience to know what is the best solution.

He is right, in my opinion. There are so many awesome tools out there waiting to be explored, although during the exploration I do have to bang my head against the wall just to compensate for my lack of knowledge. Spending for like 12 hrs to just setup a page and spending another 3 hrs to write a blog recording my mistake is “not a good time management”. But I do think it is worth it to left some record here just to make myself setting up the next blog easier. And, if I am lucky enough to have a reader like you🤗, hope this helps.