From 15e62010c2ec5d3155068e2e104b756eb4afcaca Mon Sep 17 00:00:00 2001
From: pengzhanbo <volodymyr@foxmail.com>
Date: Fri, 12 Dec 2025 20:41:30 +0800
Subject: [PATCH] feat(theme): add `cols` frontmatter support for `friends`
 page, close #781 (#792)

---
 docs/config/frontmatter/friend.md             | 10 ++++++++-
 docs/en/config/frontmatter/friend.md          |  8 +++++++
 docs/en/guide/features/friend-links.md        |  1 +
 docs/guide/features/friend-links.md           |  1 +
 theme/src/client/components/VPFriends.vue     | 22 ++++++++++++++++++-
 .../src/client/components/VPFriendsGroup.vue  |  6 +++++
 theme/src/client/components/VPFriendsItem.vue |  7 +++++-
 theme/src/client/styles/vars.css              |  2 +-
 theme/src/shared/frontmatter/friends.ts       |  6 +++++
 9 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/docs/config/frontmatter/friend.md b/docs/config/frontmatter/friend.md
index 9cf982e2..01ef416c 100644
--- a/docs/config/frontmatter/friend.md
+++ b/docs/config/frontmatter/friend.md
@@ -14,6 +14,7 @@ permalink: /config/frontmatter/friends/
 ---
 pageLayout: friends
 title: 友情链接
+cols: 2
 list:
   -
     name: pengzhanbo
@@ -62,13 +63,20 @@ list:
 
 友情链接页的描述
 
-### contentPosition <Badge text="新" />
+### contentPosition
 
 - 类型： `'before' | 'after'`
 - 默认值： `'after'`
 
 markdown 内容在友情链接列表之前还是之后，默认插入到列表之后。
 
+### cols <Badge text="新" />
+
+- 类型： `number`
+- 默认值： `2`
+
+友情链接列表每行最大显示的列数，一般设置为 `2` / `3` 时最佳。
+
 ### list
 
 - 类型： `FriendsItem[]`
diff --git a/docs/en/config/frontmatter/friend.md b/docs/en/config/frontmatter/friend.md
index 18dcc50f..cb5b730c 100644
--- a/docs/en/config/frontmatter/friend.md
+++ b/docs/en/config/frontmatter/friend.md
@@ -14,6 +14,7 @@ Example:
 ---
 pageLayout: friends
 title: Friends Links
+cols: 2
 list:
   -
     name: pengzhanbo
@@ -69,6 +70,13 @@ The description of the friends links page.
 
 Whether the markdown content is placed before or after the friends links list. By default, it is inserted after the list.
 
+### cols
+
+- Type: `number`
+- Default: `1`
+
+The maximum number of columns displayed per line in the friends link list is generally best set to `2` / `3`.
+
 ### list
 
 - Type: `FriendsItem[]`
diff --git a/docs/en/guide/features/friend-links.md b/docs/en/guide/features/friend-links.md
index b207466f..1de60b46 100644
--- a/docs/en/guide/features/friend-links.md
+++ b/docs/en/guide/features/friend-links.md
@@ -17,6 +17,7 @@ friends: true
 title: Friend Links
 description: Description text for friend links
 permalink: /friends/
+cols: 2
 contentPosition: after
 list:
   -
diff --git a/docs/guide/features/friend-links.md b/docs/guide/features/friend-links.md
index cba45b93..d973e51a 100644
--- a/docs/guide/features/friend-links.md
+++ b/docs/guide/features/friend-links.md
@@ -19,6 +19,7 @@ title: 友情链接
 description: 友情链接描述文本
 permalink: /friends/
 contentPosition: after
+cols: 2
 list:
   -
     name: pengzhanbo
diff --git a/theme/src/client/components/VPFriends.vue b/theme/src/client/components/VPFriends.vue
index e5c9223e..054d6ae7 100644
--- a/theme/src/client/components/VPFriends.vue
+++ b/theme/src/client/components/VPFriends.vue
@@ -12,10 +12,20 @@ const { frontmatter: matter, page } = useData<'friends'>()
 
 const list = computed(() => matter.value.list || [])
 const groups = computed(() => matter.value.groups || [])
+const cols = computed(() => {
+  const cols = matter.value.cols || 2
+  if (cols < 1)
+    return 1
+
+  return cols
+})
 </script>
 
 <template>
-  <div class="vp-friends">
+  <div
+    class="vp-friends" :class="{ 'cols-large': cols >= 3 }"
+    :style="{ '--vp-friends-cols': cols }"
+  >
     <VPEncrypt>
       <Content v-if="matter.contentPosition === 'before'" class="vp-doc plume-content before" vp-content />
 
@@ -131,6 +141,16 @@ const groups = computed(() => matter.value.groups || [])
   }
 }
 
+@media (min-width: 1280px) {
+  .vp-friends.cols-large {
+    max-width: 1152px;
+  }
+
+  .friends-list {
+    grid-template-columns: repeat(var(--vp-friends-cols), minmax(0, 1fr));
+  }
+}
+
 .edit-link-button {
   display: flex;
   align-items: center;
diff --git a/theme/src/client/components/VPFriendsGroup.vue b/theme/src/client/components/VPFriendsGroup.vue
index 6cbd57d6..cd81c2a0 100644
--- a/theme/src/client/components/VPFriendsGroup.vue
+++ b/theme/src/client/components/VPFriendsGroup.vue
@@ -74,4 +74,10 @@ const { group } = defineProps<{
     padding: 0;
   }
 }
+
+@media (min-width: 1280px) {
+  .friends-list {
+    grid-template-columns: repeat(var(--vp-friends-cols), minmax(0, 1fr));
+  }
+}
 </style>
diff --git a/theme/src/client/components/VPFriendsItem.vue b/theme/src/client/components/VPFriendsItem.vue
index 0a1f5ad4..47b6e22b 100644
--- a/theme/src/client/components/VPFriendsItem.vue
+++ b/theme/src/client/components/VPFriendsItem.vue
@@ -67,9 +67,14 @@ const friendStyle = computed(() => {
   margin-bottom: 8px;
   background-color: var(--vp-friends-bg-color);
   border-radius: 6px;
+  box-shadow: 0 0 0 transparent;
   transition: all var(--vp-t-color);
 }
 
+.vp-friend:hover {
+  box-shadow: var(--vp-shadow-2);
+}
+
 .avatar {
   width: 88px;
   height: 88px;
@@ -96,7 +101,7 @@ const friendStyle = computed(() => {
 
 .content .title {
   padding-bottom: 8px;
-  font-size: 24px;
+  font-size: 20px;
   font-weight: 700;
   color: var(--vp-friends-name-color);
   transition: color var(--vp-t-color), border-bottom var(--vp-t-color);
diff --git a/theme/src/client/styles/vars.css b/theme/src/client/styles/vars.css
index 7967a50a..8c95f68d 100644
--- a/theme/src/client/styles/vars.css
+++ b/theme/src/client/styles/vars.css
@@ -529,7 +529,7 @@
  * Component: Friends
  * -------------------------------------------------------------------------- */
 :root {
-  --vp-friends-text-color: var(--vp-c-text-1);
+  --vp-friends-text-color: var(--vp-c-text-2);
   --vp-friends-bg-color: var(--vp-c-bg-alt);
   --vp-friends-name-color: var(--vp-c-text-2);
 }
diff --git a/theme/src/shared/frontmatter/friends.ts b/theme/src/shared/frontmatter/friends.ts
index 6c59b974..22d11273 100644
--- a/theme/src/shared/frontmatter/friends.ts
+++ b/theme/src/shared/frontmatter/friends.ts
@@ -94,4 +94,10 @@ export interface ThemeFriendsFrontmatter extends ThemeNormalFrontmatter {
    * 友链分组
    */
   groups?: FriendGroup[]
+
+  /**
+   * 最大列数
+   * @default 2
+   */
+  cols?: number
 }