valaxy-addon-girls

English | 简体中文

一个与主题解耦的 Valaxy 角色画廊插件。它支持内联数组和远程 JSON 数据源、三种响应式布局、访客自由切换布局、可配置备注与动效，以及完整的加载、失败、键盘导航和亮暗主题状态。

特性 ​

• 三种响应式布局：紧凑网格、圆球星团和轨道。
• 面向 100+ 条目的渐进渲染与浏览器原生图片懒加载。
• 继承主题 CSS 变量，支持暗色模式、减少动画和键盘导航。
• 不引入装饰图片：星团使用 CSS，轨道装饰使用内联 SVG。
• 支持远程 JSON 与内联数据，并提供加载、空状态、错误和重试界面。

安装 ​

pnpm add valaxy-addon-girls

import { defineValaxyConfig } from 'valaxy'
import { addonGirls } from 'valaxy-addon-girls'

export default defineValaxyConfig({
  addons: [
    addonGirls(),
  ],
})

插件会自动注册 ValaxyGirls 组件：

---
girls: https://example.com/girls.json
random: true
---

<ValaxyGirls :girls="frontmatter.girls" :random="frontmatter.random" layout="bubbles" switchable>
  <template #header="{ count, isLoading }">
    <header>
      <h2>喜欢的角色</h2>
      <p v-if="!isLoading">已收藏 {{ count }} 位</p>
    </header>
  </template>
</ValaxyGirls>

内联数据使用相同字段：

girls:
  - name: C.C.
    avatar: https://example.com/cc.png
    from: CODE GEASS
    reason: 冷静、神秘，又有自己的温柔
    url: https://example.com/cc

只有 name 为必填字段，其他未知元数据会被保留。

组件 Props ​

布局 ​

• grid：向后兼容的紧凑卡片网格，适合大量角色。
• bubbles：把完整名册按视觉权重聚合为单一圆球星团，不生成第二份溢出列表。
• orbit：最多 24 位角色进入星座轨道，其余角色随滚动继续展示。

旧的 cloud 和 wings 配置会在运行时兼容为 bubbles，但不再属于公开类型。

站点作者可以设置初始布局，并把同样的选择权交给访客：

<ValaxyGirls
  v-model:layout="layout"
  :girls="frontmatter.girls"
  switchable
/>

备注默认隐藏，以保持画廊紧凑：

<!-- 始终显示两行以内的备注，适合触屏端也需要阅读的场景。 -->
<ValaxyGirls :girls="frontmatter.girls" reason-mode="inline" />

<!-- 鼠标悬浮或键盘聚焦时显示浮层。 -->
<ValaxyGirls :girls="frontmatter.girls" reason-mode="hover" />

常规手机的网格最多使用两列，22rem 及以下自动切换为一列。圆球舞台会保留全部头像并随容器缩放，选中详情位于星团下方；悬浮或聚焦头像时，当前圆球会提升到相邻头像上方，并显示角色名与出自作品。

对于大量角色，网格默认创建 24 张卡片，在底部触发器接近视口时按 batchSize 自动追加；轨道会在 24 位舞台角色之后使用同样的触发器。圆球星团为了保持完整轮廓，会一次创建全部轻量圆球，因此 renderMode 只影响网格与溢出列表。触发器基于 IntersectionObserver，不支持时回退为按钮；也可以通过 :auto-load="false" 主动使用按钮。头像使用原生 loading="lazy" 与异步解码，约一百个角色不需要额外虚拟列表依赖。

需要完整 DOM 时可以显式使用 all：

<ValaxyGirls
  girls="https://wives.yunyoujun.cn/girls.json"
  layout="grid"
  render-mode="all"
/>

默认访问体验仍推荐渐进模式。对于 100+ 条目，可以同时调整首批与每批数量：

<ValaxyGirls
  girls="https://wives.yunyoujun.cn/girls.json"
  layout="grid"
  :initial-count="24"
  :batch-size="24"
  :auto-load="true"
/>

首批会渲染 24 位角色，滚动触发器接近视口后自动追加 24 位，无需点击。

Events ​

<ValaxyGirls
  v-model:layout="layout"
  :girls="frontmatter.girls"
  switchable
  @layout-change="onLayoutChange"
/>

Slots ​

<ValaxyGirls :girls="frontmatter.girls">
  <template #header="{ count, error, isLoading }">
    <p v-if="isLoading">正在加载角色…</p>
    <p v-else-if="error">角色名册暂时不可用</p>
    <p v-else>共 {{ count }} 位角色</p>
  </template>
</ValaxyGirls>

样式覆盖 ​

在 .valaxy-girls 上覆盖以下 CSS 变量即可适配主题：

• --valaxy-girls-soft
• --valaxy-girls-sky
• --valaxy-girls-sky-deep
• --valaxy-girls-blush
• --valaxy-girls-ink
• --valaxy-girls-muted
• --valaxy-girls-paper
• --valaxy-girls-line

Valaxy 用户也可以通过标准组件覆盖机制，在站点 components/ 目录替换 ValaxyGirls.vue。包还会导出 ValaxyGirlCard，便于组合自定义画廊外壳。

Client API ​

包会导出 useGirls、useProgressiveCount、确定性布局工具，以及 GirlEntry、GirlReasonMode、GirlsLayout、GirlsMotionMode、GirlsRenderMode、GirlsSource 和 GirlsHeaderSlotProps 类型。useGirls 会在挂载后发起远程请求、取消过期请求，并保持服务端与客户端标记一致。

文档与开发 ​

• English guide
• 简体中文文档
• 在线示例源码

在 Valaxy monorepo 根目录运行：

pnpm --filter valaxy-addon-girls test
pnpm lint
pnpm typecheck

License ​

MIT © YunYouJun

交互示例 ​

以下内容只属于文档站。上方的安装、配置和 API 说明均直接来自插件 README。

布局与备注模式 ​

完整 120 条角色数据 ​

在线示例默认把全部角色装入同一个圆球星团；切换到网格后，可以比较渐进渲染与完整渲染。