Skip to content

README.zh.md

Latest commit

 

History

History
236 lines (175 loc) · 7.96 KB

README.zh.md

File metadata and controls

236 lines (175 loc) · 7.96 KB
Raw

Magazine 主题说明

Magazine（杂志） 是面向摄影工作室的杂志风公开站点主题：大图叙事、强排版层次与偏编辑向的视觉语言，让访客像在翻阅纸质刊物一样浏览作品与内容。

English: Magazine Theme Guide

目录

目录结构

theme/src/themes/magazine/
├── index.tsx                 # 主题入口（路由、页面映射、Provider）
├── options.schema.json       # 主题可配置项 Schema（Studio「站点外观」）
├── components/               # 布局、卡片、UI、地图等
│   ├── cards/                # Album / Article / Exhibition / Activity / …
│   ├── layout/
│   ├── ui/
│   └── map/
├── context/                  # 主题选项 Context
├── hooks/
├── lib/                      # 图片 URL、API 辅助等
├── locales/                  # zh.ts / en.ts
├── node-network/             # Hub / Studio 节点网络公开数据与筛选
├── pages/                    # 各路由页面（见下表）
└── utils/                    # 如活动类型文案等

pages/ 一览

文件 用途
Home.tsx 首页
Studio.tsx 工作室介绍
Photographers.tsx / PhotographerDetail.tsx 摄影师列表与详情
Articles.tsx / ArticleDetail.tsx 文章列表与详情
Activities.tsx / ActivityDetail.tsx 活动列表与详情
Services.tsx / ServiceDetail.tsx 服务列表与详情
Videos.tsx / VideoDetail.tsx 视频列表与详情
Albums.tsx / Gallery.tsx 作品集与图库
HubNetwork.tsx / NodeNetwork.tsx 节点网络（Hub / 工作室索引）
Policies.tsx 政策条款
PublicStaticFallback.tsx 公开静态占位（无动态数据时）

设计特点

视觉

  • 杂志式 Hero：约 70vh–75vh 高度的封面级大图轮播，渐变遮罩 + 大号衬线标题。
  • 卡片遮罩：竖版比例（约 3:4），底部叠字，图像区可带渐变压暗。
  • 排版：标题 Playfair Display，正文 Inter。
  • 暗色基调：默认深背景（如 #0a0a0a）+ 高对比文字，偏高端刊物感。

交互

  • 卡片悬停轻微放大（如 scale(1.05)）。
  • 过渡统一使用 cubic-bezier(0.4, 0, 0.2, 1)。
  • 响应式断点覆盖手机到桌面；兼顾键盘与「减少动画」偏好。

预设与配置

预设：midnightEditorial（午夜编辑风）

深色杂志风，适合作品与品牌展示：

{
  "themeMode": "dark",
  "headingFont": "Playfair Display",
  "bodyFont": "Inter",
  "cornerStyle": "sharp",
  "palette": {
    "dark": {
      "background": "#0a0a0a",
      "surface": "#1a1a1a",
      "textPrimary": "#ffffff",
      "textSecondary": "rgba(255, 255, 255, 0.7)"
    }
  }
}

预设：paperMinimal（纸质极简）

浅色、偏纸质阅读体验：

{
  "themeMode": "light",
  "headingFont": "Playfair Display",
  "bodyFont": "Inter",
  "cornerStyle": "sharp",
  "palette": {
    "light": {
      "background": "#ffffff",
      "surface": "#f5f5f5",
      "textPrimary": "#000000",
      "textSecondary": "rgba(0, 0, 0, 0.6)"
    }
  }
}

核心配置项（options.schema.json）

配置项 类型 默认 说明
themeMode string 'dark' 'dark' | 'light'
heroLayout string 'stacked' Hero：stacked | split
typography.headingFont string 'Playfair Display' 标题字体
typography.bodyFont string 'Inter' 正文字体
cornerStyle string 'sharp' 'sharp' | 'rounded'
roundnessPrimary string '4px' 主圆角
roundnessSecondary string '8px' 次圆角
roundnessSmall string '4px' 小圆角

配色通过 palette.light.* / palette.dark.* 分模式覆盖。完整字段以 options.schema.json 为准。

组件与页面

卡片

统一杂志风；示例：

import { AlbumCard } from '../components/cards';

<AlbumCard album={album} index={0} photographers={photographers} animationEnabled={true} />;

常见卡片：AlbumCard、ArticleCard、ExhibitionCard、ActivityCard、PhotographerCard、ServiceCard、VideoCard 等（以 components/cards/ 为准）。

Hero Banner

import HeroBanner from '../components/HeroBanner';

<HeroBanner albums={albums} profile={profile} autoplay={true} interval={5000} />;

图片与国际化

图片服务

import { IMAGE_PRESETS, buildImageServiceUrl } from '../lib/image';

const url = buildImageServiceUrl(imagePath, IMAGE_PRESETS.medium);

const custom = buildImageServiceUrl(imagePath, {
  width: 800,
  quality: 80,
  format: 'webp',
  fit: 'cover',
});

常用预设：thumbnail（约 400px）、medium（约 800px）、banner（约 1920px）、original。

国际化

import { useThemeI18n } from '../locales';

const { t } = useThemeI18n();
const label = t('common.viewStory');

文案：locales/zh.ts、locales/en.ts。活动类型等可配合 utils/activityKindLabel.ts 使用。

开发与预览

在仓库 theme/ 包内：

pnpm dev              # 主题开发环境 + mock API
pnpm magazine         # 构建 magazine 主题产物
pnpm magazine:local   # 构建并复制到 Studio 本地目录联调
pnpm magazine:package # 构建并打包到 Hub 主题市场目录

未接真实 Studio 时，主题 dev 会使用 theme/api/mock-data/*.json 与 theme/api/src/routes/mock-theme.ts 提供相册、活动、服务、视频等数据；活动列表依赖 type=activity 且 isPublic=true 等参数与真实 API 对齐，便于本地预览列表与详情。

更多主题系统说明见仓库根目录文档：docs/tech/themes/system.md、docs/product/themes/。

新增页面（简流程）

  1. 在 pages/ 新增组件。
  2. 在 index.tsx 的页面映射中注册路由。
  3. 补齐 locales/zh.ts 与 locales/en.ts 中所需 key。
  4. 若需配置项，更新 options.schema.json 并在消费处读取 Context。

自定义样式

推荐使用 MUI sx 与主题 token，例如：

<Box
  sx={{
    fontSize: { xs: '1rem', md: '1.25rem', lg: '1.5rem' },
    p: { xs: 2, md: 4 },
  }}
/>

技术栈与兼容性

  • React 19、TypeScript、MUI v7、React Router、Vite 7
  • 与 Studio Blocklet 主题安装与公开路由兼容；数据形态与 Hub 侧公开接口约定对齐（详见产品/技术文档）。

截图与版本

预览图建议放在主题包内 screenshots/（若打包流程有要求则按其约定）：

  • hero.jpg — Hero，建议 1920×1080
  • cards.jpg — 卡片列表
  • detail.jpg — 详情页

更新日志

v1.0.0（2026-03-13）

  • 首版杂志风实现
  • 主要公开页面与卡片组件
  • 深/浅模式与响应式布局