清水河畔

基于 TypeScript、React 进行重构，用户界面基于 MUI 框架，编辑器选用 Vditor 并针对河畔需求定制开发。

开发环境

• Node.js（pnpm 要求 Node.js v18.12 或更高版本）
• pnpm 10.x（npm install -g pnpm@latest-10）

编译运行

• 安装依赖项

pnpm install

• 本地开发测试（请通过环境变量指定后端服务器地址，参考下文）

pnpm run bbs:dev

• 编译生产版本

pnpm run bbs:build

本地开发测试的高级配置

• 环境变量：

  • UESTC_BBS_BACKEND_SERVER=http://127.0.0.1:81

    指定自定义的后端服务器地址，方便前后端同时开发测试。

  • UESTC_BBS_DEVELOPER_KEY=xxx

    后端服务器使用测试服务器上的 API 入口，该入口需配置开发者密钥后才能访问，具体取值请咨询 @fangjue 。

• 常用参数：

  • --host=0.0.0.0 HTTP 服务器监听地址
  • --port=1234 HTTP 服务器监听端口

帖子格式化与编辑器

Vditor

新版河畔使用 Vditor 作为主要的帖子格式化编辑器，在原版基础上作了一些定制开发，具体参见 fangjue/vditor（选择 fj 分支）。Vditor 中所使用的 Lute 引擎也有本地修改。

目前 Vditor 编辑器仍有很大改进空间，例如移动端使用体验、部分格式化功能（颜色、字体等），此外还存在打包尺寸过大的问题。

bbcode

旧版河畔使用 bbcode，新版河畔中支持旧版帖子的渲染与 bbcode 源代码级编辑，还支持旧版到新版的一键格式转换；编辑与格式转换功能需进一步优化完善，零星的旧版帖子渲染问题以及部分历史遗留问题发现一例修复一例。目前暂无计划支持所见即所得形式的编辑。

站内信正文、用户签名、版块公告、发帖提醒等富文本内容也使用 bbcode 的一个子集。

关于链接与路由的一些问题

1. 不使用 location.href 在页面之间跳转。在用户界面中应使用 <Link>（@/components/Link，非 MUI 或 react-router-dom 中的 <Link>）组件，在程序逻辑中应中使用 useNavigate。

   在菜单（<MenuItem>）与按钮（<Button>）中通过 component 属性使渲染的元素成为链接，例如：

   import Link, { MenuItemLink } from '@/components/Link'
   
   <Button component={Link} to={pages.post()}>发帖</Button>
   <MenuItem component={MenuItemLink} to={pages.post()}>发帖</MenuItem>
   {/* 注意 <MenuItem> 的 component 属性设置为 MenuItemLink*/}
   

   需要在程序逻辑中跳转到其他页面时，请使用 useNavigate。 用户界面中点击后直接产生的页面跳转应当使用 <Link>。

2. 不要硬编码链接。需要链接地址时，内部链接调用 @/utils/routes.ts 中的 pages.xxx 函数生成，旧版河畔链接使用 @/utils/siteRoot 作为起始位置。

   例如：

   // 不要硬编码链接
   `/thread/${tid}`
   'https://bbs.uestc.edu.cn/forum.php'
   
   // 使用 pages.xxx 函数与 siteRoot
   pages.thread(tid)
   `${siteRoot}/forum.php`
   

3. 判断当前页面时，使用 @/utils/routes.ts 中的 useActiveRoute，而不要解析 location.href 值。

   例如：

   import { useActiveRoute } from '@/utils/routes'
   
   const activeRoute = useActiveRoute()
   if (activeRoute?.id == 'thread') {
     // 当前页面为帖子内容页。
   }
   

4. 不在路由范围内但仍在河畔域名下的 URL，须在 <Link> 组件中指定 external 属性。

   例如：

   <Link external to={`${siteRoot}/forum.php`}>
   

   注意：external 属性仅仅表示该链接不经过 React Router 解析，并不会在新窗口中打开。如需新窗口打开，请另外设置 target="_blank"。

5. 添加新页面时，请在 routes/index.tsx 中设置好 id 属性，并在 @/utils/routes.ts 中添加 pages.xxx 函数，在 components/Breadcumbs/index.tsx 中添加 Breadcumb（面包屑）导航。

其他说明

由于历史原因，代码库中存在一些风格不统一、目录结构不一致的情况。尽可能与现有代码中最常见的风格保持一致，如有疑问或重构思路，请咨询 @fangjue 。

第三方依赖项的引入、更新请务必提前联系 @fangjue 。

CSS 编写

React 中使用 Emotion（MUI 元素使用 sx 属性，普通 HTML 元素使用 css 属性；动态变化的 CSS 应直接使用 style 属性），新代码不再使用 Tailwind CSS。

疑难解答

运行 vite 时报错

Error: Cannot find module '.../qshp-fe/node_modules/.pnpm/vite@xxx/...'
...
  code: 'MODULE_NOT_FOUND',

在 Vite 版本发生变化时可能会遇到，删除 bbs/node_bodules/.bin/vite 后重新运行即可。