NovelReader
novel-reader打开就进入正文,用底部抽屉调翻页、字号和纸色,进度按字符偏移记住
用法
基础用法
菜单默认收起,打开就是正文。章末的下一章留在正文里。点中间才唤出目录和阅读设置。
渡口的灯 · 沈晚
第 1 章 夜航
河面暗下来。沈晚把灯挂上桅杆。
本章完
100%
tsx
<NovelReader
className="h-[28rem]"
title="渡口的灯"
author="沈晚"
chapters={chapters}
/>何时用
网文、专栏、文稿这类「打开就要读」的正文。翻页、字号、行距、栏宽和纸色收在同一套阅读设置里;目录和设置走底部抽屉,不在左侧常驻一块挡字的面板。
正文编辑用 NovelEditor。渲染 Markdown 用 Markdown。
导入
ts
import { NovelReader } from "@hulianui/ui"Props
继承 HTMLAttributes<HTMLDivElement>(不含原生 title)。根节点必须有高度,例如 h-dvh 或 h-[28rem]。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| title | string | — | 书名。写在正文开头,并在唤出的顶栏里重复 |
| author | ReactNode | — | 作者 |
| chapters | NovelChapter[] | — | 章节。content 是 Markdown |
| chapterId | string | — | 受控当前章 |
| defaultChapterId | string | 第一章 | 非受控初始章。本地进度优先于它 |
| onChapterChange | (id: string) => void | — | 切章回调 |
| turn | "scroll" | "cover" | "simulation" | — | 受控翻页:滚动 / 覆盖 / 仿真。三者共用一套向前、向后 |
| defaultTurn | "scroll" | "cover" | "simulation" | "scroll" | 非受控翻页。默认滚动连读 |
| onTurnChange | (turn: NovelTurn) => void | — | 翻页方式变化 |
| mode | "scroll" | "paginated" | — | 旧入口。paginated 视为覆盖,scroll 视为滚动。与 turn 同时传时以 turn 为准 |
| fontSize | "sm" | "md" | "lg" | "xl" | — | 受控字号,对应 text-sm 到 text-xl |
| defaultFontSize | "sm" | "md" | "lg" | "xl" | "md" | 非受控字号 |
| onFontSizeChange | (size: NovelFontSize) => void | — | 字号变化 |
| lineHeight | "snug" | "normal" | "relaxed" | "loose" | — | 受控行距 |
| defaultLineHeight | "snug" | "normal" | "relaxed" | "loose" | "relaxed" | 非受控行距 |
| onLineHeightChange | (lineHeight: NovelLineHeight) => void | — | 行距变化 |
| measure | "narrow" | "normal" | "wide" | — | 受控栏宽,对应 max-w-xl / 2xl / 3xl |
| defaultMeasure | "narrow" | "normal" | "wide" | "normal" | 非受控栏宽 |
| onMeasureChange | (measure: NovelMeasure) => void | — | 栏宽变化 |
| paper | "default" | "day" | "eye" | "night" | "oled" | — | 受控纸色。只包住正文,菜单仍跟系统主题 |
| defaultPaper | "default" | "day" | "eye" | "night" | "oled" | "default" | 非受控纸色 |
| onPaperChange | (paper: NovelPaper) => void | — | 纸色变化 |
| persistKey | string | — | 把 { chapterId, charOffset } 写入 localStorage。不记页码 |
| onProgressChange | (progress: NovelProgress) => void | — | 进度变化。进度只有章节和字符偏移 |
| defaultChromeOpen | boolean | false | 首屏就展开顶栏/底栏。沉浸阅读默认收起(点正文中间三档唤出);做阅读产品落地页时默认展开,否则第一眼是一页没有返回、没有目录的白纸 |
| leading | ReactNode | — | 唤出菜单后放在顶栏左上角,例如返回和书架 |
| trailing | ReactNode | — | 唤出菜单后放在顶栏右侧 |
| articleClassName | string | — | 加在正文 <article> 上,用来换字族(例如宋体)。字号和行距仍由组件档位控制。不要在外面用 [&_article] 改内部节点 |
NovelChapter
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | string | — | 稳定章节 id |
| title | string | — | 章名,不含「第 N 章」前缀 |
| content | string | — | Markdown 正文 |
| wordCount | number | 按去空白字符数估算 | 展示用字数 |
NovelProgress
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| chapterId | string | — | 当前章 |
| charOffset | number | — | 相对本章已渲染正文的字符偏移 |
禁忌 / 坑
- 根节点不带高度。不写
h-dvh或h-[28rem]时,滚动区和翻页视口都量不到。 - 进度是
(chapterId, charOffset),不是页码。字号、行距、栏宽一变,页数会变,页码会对不上原来那一句。 - 不要在外面再套一条吸顶顶栏。菜单默认不占位,自己再加一条就会把正文顶下去。
- 纸色是「换一种纸」而不是换一个底色:
day偏暖(warning混 6%)、eye偏青(success混 11%)、night是暗底混 5% 暖色。四档都从语义色混出来 —— 换主题时纸色跟着换,不会出现「暗色页面里夹一张雪白纸」。oled才接近纯黑。纸色画在整块视口上,不是画在<article>上 —— 画在正文上会得到一张在正文末尾齐刷刷截断的半张纸;data-theme也跟着视口走,于是「菜单跟页面 token、纸色只包住正文」仍然成立。 - 组件不提供批注或本章说。不要在阅读器打开时叠开屏、下载、促销或任务弹层。
- 正中热区只负责唤出或收起菜单。返回、书架放在
leading/trailing,不要放在正文正中。 - 目录和阅读设置是底部抽屉。不要在左侧做一枚常驻齿轮。阅读设置的遮罩保持透明,面板用内联
color-mix(in srgb, var(--color-surface) 80%, transparent),不要backdrop-blur。只写bg-surface/80时,生产 CSS 会先落到实色var(--color-surface),不过color-mix(in lab)检测就变成不透明浅灰,当前句被盖死。 - 章内的「上一章 / 下一章」用按钮文案,不要拿 Pagination 的「上一页 / 下一页」来切章。
- 不要做整页常驻的顶栏和底栏来放上一章、下一章。上一章只留在章首,第一章不放;下一章只留在章末,最后一章不放。章末的下一章在菜单收起时也在。顶栏和底栏里的切章跟着菜单一起藏。
- 正文字族用
articleClassName。不要在外面写[&_article]去改组件内部。正文 Markdown 跟外层的字号和行距走。
相关
NovelEditor · Markdown · Drawer · Empty