v0.1.0 界面框架：抽屉骨架 + 13 个模块页面

对应服务端 FamilyBook（家书）的鸿蒙客户端首版。本轮只做**界面框架**，数据全部是演示数据 —— 服务端尚无客户端接口，所有增删改只做入口与样式，不落任何数据。 ## 骨架左侧抽屉 + 右侧内容。抽屉两套形态由窗口短边决定（≥600vp 为宽屏）：宽屏常驻侧栏、窄屏滑出层。判据取「短边」而非「宽度」，因为短边在旋转时不变，比例接近 1:1 的设备横竖屏布局天然一致。 ## 模块（与 Web 端 Module::LIST 一一对应，key 即路由名）首页、家谱、名册、观影、旅程、日程、资源、任务、纪念日、财务、读书、导航、笔记；另有通知消息、个人设置两个附加页。 ## 与 Web 端保持一致的几处 · 模块清单唯一来源在 model/Modules.ets，加模块只改那一处； · 模块主题色三档由主色按 HSL 压明度算出，预设色板与 Web 端逐值一致； · 术语沿用 Web 端固定下来的口径（旅程 ⊃ 行程；观影的「影院」不单独占抽屉位，从模块内设置进）； · 页面结构照 Web 端的信息层次（首页信息面板 / 财务概览在账目之前 / 纪念日「即将到来」在顶 / 任务按状态而非按看板）。 ## 编译验证 hvigorw assembleHap --mode module -p product=default → BUILD SUCCESSFUL，0 error / 0 warning（含一次删 build 后的干净重建）过程中修掉的编译期问题： · Circle().fill() 是 API 26 才有的重载（compatibleSdk 是 24） → 换「方块 + 圆角」画圆，零版本风险； · setWindowBackgroundColor 对 phone/tablet 不可用 → 去掉（页面已铺满同色）； · window.getLastWindow() 只有异步版 → 由 Ability 侧同步取窗存 AppStorage； · 颜色类 @Param 声明成 string 导致传 Resource 报错 → 统一改 ResourceColor； · 页面在 pages/<模块>/ 下，公共件 import 相对路径要多退一级。（首轮编译 95 error / 18 warn，逐条定位到 5 类根因后归零。）
2026-10-11 22:07:48 +08:00
commit 41e3aa3d95
80 changed files with 6985 additions and 0 deletions
@@ -0,0 +1,258 @@
+/**
+ * 家书 FamilyBook · 左侧抽屉（鸿蒙端）
+ *
+ * 形态对齐 Web 端顶栏 `.nav` 那一排模块入口，但**改成抽屉**（用户建议）：
+ * Web 端导航条最多放 12 个模块，手机宽度下必然溢出；抽屉竖向排列，
+ * 还能顺带放下「模块说明 + 主题色」这层信息，一眼看清每个模块是干什么的。
+ *
+ * 两条形态，同一个组件：
+ *   · **常驻侧栏**（宽屏：窗口短边 ≥ 600vp）—— 固定在左边，占 264vp；
+ *   · **滑出层**（手机竖屏）—— 覆盖在内容上，点遮罩或选中项即收起。
+ *
+ * ⚠️ 这里**不用 SideBarContainer**：它的控制按钮与「滑出」是内建的一套，
+ *    样式（图标、位置、宽度动画）很难与家书的视觉统一，且它只能有一层侧栏
+ *    内容 —— 而我们要在抽屉里放「品牌区 + 模块列表 + 底部账号区」三段。
+ *    自己用 Stack + 位移动画做，行为完全可控。
+ */
+
+import { FbColors, FbIcon, FbMetric } from '../common/Theme';
+import { FbAppState, fbAppState } from '../common/Store';
+import { FbModuleDef, FB_MODULES, fbDefaultNavModules, fbThemeVars } from '../model/Modules';
+import { FbAvatar } from './Widgets';
+
+@ComponentV2
+export struct FbDrawer {
+  /** 全局状态（父组件传入，保证与页面同一份实例） */
+  @Param app: FbAppState = fbAppState();
+  /** 抽屉宽度 */
+  @Param drawerW: number = FbMetric.drawerW;
+  /** 是否以「覆盖层」形态出现（宽屏时为 false = 常驻） */
+  @Param overlayMode: boolean = true;
+  /** 覆盖层形态下：点遮罩关闭 */
+  @Event onDismiss: () => void = () => {
+  };
+
+  /** 抽屉里列出的模块（接口接上后由 user_settings('nav_modules') 下发） */
+  @Local items: FbModuleDef[] = fbDefaultNavModules();
+
+  /** 品牌区：这里放阅文风格的书名（家书）+ 家庭名 */
+  @Builder
+  brandHeader() {
+    Row({ space: 10 }) {
+      Image($r('app.media.fb_logo'))
+        .width(34)
+        .height(34)
+        .borderRadius(9)
+      Column({ space: 1 }) {
+        Text('家书')
+          .fontSize(17)
+          .fontWeight(FontWeight.Medium)
+          .fontColor(FbColors.ink)
+          .letterSpacing(1)
+        Text(this.app.session.familyTitle)
+          .fontSize(FbMetric.fontTiny)
+          .fontColor(FbColors.muted)
+          .maxLines(1)
+      }
+      .alignItems(HorizontalAlign.Start)
+      .layoutWeight(1)
+    }
+    .width('100%')
+    .padding({ left: 18, right: 12, top: 18, bottom: 14 })
+  }
+
+  /** 一个模块行 */
+  @Builder
+  moduleRow(m: FbModuleDef) {
+    Row({ space: 12 }) {
+      // 图标底：选中时用模块色实底（白图标），未选中时用极浅染色底（彩色图标）
+      Stack() {
+        Image(FbIcon.module(m.key))
+          .width(18)
+          .height(18)
+          .renderMode(ImageRenderMode.Template)
+          .fillColor(this.isActive(m.key) ? Color.White : fbThemeVars(m.color).brand)
+      }
+      .width(34)
+      .height(34)
+      .borderRadius(10)
+      .backgroundColor(this.isActive(m.key) ? fbThemeVars(m.color).brand : this.washOf(m.color))
+
+      Column({ space: 1 }) {
+        Text(m.name)
+          .fontSize(FbMetric.fontBody)
+          .fontWeight(this.isActive(m.key) ? FontWeight.Medium : FontWeight.Normal)
+          .fontColor(FbColors.ink)
+        Text(m.desc)
+          .fontSize(FbMetric.fontTiny)
+          .fontColor(FbColors.faint)
+          .maxLines(1)
+          .textOverflow({ overflow: TextOverflow.Ellipsis })
+      }
+      .alignItems(HorizontalAlign.Start)
+      .layoutWeight(1)
+    }
+    .width('100%')
+    .padding({ left: 12, right: 12, top: 9, bottom: 9 })
+    .borderRadius(FbMetric.radiusS)
+    .backgroundColor(this.isActive(m.key) ? this.washOf(m.color) : Color.Transparent)
+    .onClick(() => {
+      this.app.switchModule(m.key);
+      this.onDismiss();
+    })
+  }
+
+  /** 底部账号区（对应 Web 端右上角头像菜单里的那几项） */
+  @Builder
+  accountFooter() {
+    Column({ space: 2 }) {
+      Divider()
+        .color(FbColors.line2)
+        .margin({ bottom: 6 })
+
+      this.footerRow('fb_ic_bell', '通知消息', this.app.unread > 0 ? this.app.unread.toString() : '')
+      this.footerRow('fb_ic_user', '个人设置', '')
+      this.footerRow('fb_ic_lock', '修改密码', '')
+      if (this.app.session.me.role === 'admin') {
+        this.footerRow('fb_ic_gear', '系统设置', '')
+      }
+    }
+    .width('100%')
+    .padding({ left: 12, right: 12, bottom: 10 })
+  }
+
+  /** 底部一行 */
+  @Builder
+  footerRow(iconName: string, label: string, badge: string) {
+    Row({ space: 12 }) {
+      Image(FbIcon.ui(iconName))
+        .width(17)
+        .height(17)
+        .renderMode(ImageRenderMode.Template)
+        .fillColor(FbColors.muted)
+      Text(label)
+        .fontSize(FbMetric.fontSmall)
+        .fontColor(FbColors.ink)
+        .layoutWeight(1)
+      if (badge.length > 0) {
+        Text(badge)
+          .fontSize(FbMetric.fontTiny)
+          .fontColor(Color.White)
+          .backgroundColor(FbColors.red)
+          .borderRadius(FbMetric.radiusPill)
+          .padding({ left: 6, right: 6, top: 1, bottom: 1 })
+      }
+    }
+    .width('100%')
+    .padding({ left: 10, right: 10, top: 9, bottom: 9 })
+    .borderRadius(FbMetric.radiusS)
+  }
+
+  /** 当前是否选中该模块 */
+  private isActive(key: string): boolean {
+    return this.app.activeModule === key;
+  }
+
+  /** 模块色的极浅染色底（选中行 / 图标底） */
+  private washOf(hex: string): string {
+    // 与 Theme.fbPalette 的 wash 同口径：压饱和、抬明度到 0.94
+    const t = fbThemeVars(hex);
+    return t.brand + '1A';
+  }
+
+  build() {
+    Column() {
+      this.brandHeader()
+
+      // 模块列表：可滚动，模块多时不会把底部账号区挤掉
+      List({ space: 1 }) {
+        ForEach(this.items, (m: FbModuleDef) => {
+          ListItem() {
+            this.moduleRow(m)
+          }
+        }, (m: FbModuleDef): string => 'nav_' + m.key)
+      }
+      .layoutWeight(1)
+      .width('100%')
+      .padding({ left: 6, right: 6 })
+      .scrollBar(BarState.Off)
+      .edgeEffect(EdgeEffect.Spring)
+
+      this.accountFooter()
+    }
+    .width(this.drawerW)
+    .height('100%')
+    .backgroundColor(FbColors.surface)
+    // ⚠️ 侧栏右侧的分隔线只在常驻形态下需要；覆盖层形态下它贴着屏幕边，加了反而怪
+    .border(this.overlayMode
+      ? { width: 0 }
+      : { width: { right: 1 }, color: FbColors.line2 })
+  }
+}
+
+/**
+ * 抽屉 + 内容 的整体骨架。
+ *
+ * 两种形态在这里分派：
+ *   · 宽屏 → Row（抽屉占位 + 内容区）；
+ *   · 窄屏 → Stack（内容铺满，抽屉带遮罩浮在上面）。
+ */
+@ComponentV2
+export struct FbDrawerShell {
+  @Param app: FbAppState = fbAppState();
+  /** 内容区（由父组件通过尾随 lambda 传入） */
+  @BuilderParam content: () => void;
+
+  build() {
+    Stack({ alignContent: Alignment.TopStart }) {
+      // ---- 宽屏：并排 ----
+      if (this.app.wideLayout) {
+        Row() {
+          FbDrawer({
+            app: this.app,
+            overlayMode: false
+          })
+          Column() {
+            this.content()
+          }
+          .layoutWeight(1)
+          .height('100%')
+        }
+        .width('100%')
+        .height('100%')
+      } else {
+        // ---- 窄屏：内容铺满 + 抽屉浮层 ----
+        Column() {
+          this.content()
+        }
+        .width('100%')
+        .height('100%')
+
+        if (this.app.drawerOpen) {
+          // 遮罩
+          Column()
+            .width('100%')
+            .height('100%')
+            .backgroundColor('#66000000')
+            .onClick(() => {
+              this.app.drawerOpen = false;
+            })
+            .transition(TransitionEffect.OPACITY.animation({ duration: 180 }))
+
+          FbDrawer({
+            app: this.app,
+            overlayMode: true,
+            onDismiss: (): void => {
+              this.app.drawerOpen = false;
+            }
+          })
+            .transition(TransitionEffect.translate({ x: -FbMetric.drawerW })
+              .animation({ duration: 220, curve: Curve.FastOutSlowIn }))
+        }
+      }
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(FbColors.paper)
+  }
+}