GitcodeLayoutLib

GitcodeLayoutLib 是 GitCode 前端项目的基础布局组件库，提供 GitCode 通用布局组件，供各项目调用，保持各站点功能和视觉效果的一致性，目前提供的布局模块有：

• Header：全站头部导航
• Aside： 全站侧边栏
• ToolsFloat：全站右下角工具条

具体的场景模块划分，见 BaseLayout业务组件抽离 - GitCode - 文档中心@CSDN

布局组件模块文档

Header 导航栏组件

导航栏头部组件

使用方式

传入场景值以及在该场景下所需的必要参数。 使用方式功能较多示例见 Home.vue

Props

参数说明

常规参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | isLogin | boolean | 是 | - | 是否登录 | | sceneValue | SceneValue | 是 | SceneValue.home | 场景值 | | request | Function | 是 | () => Promise.resolve({ data: null }) | 请求实例 | | globalStore | Object | 否 | {} | 用来上报当前界面状态 只需要其中的httpStatus | | headerBorder | boolean | 否 | false | header是否需要边框 |

登录相关参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | loginSuccess | Function | 是 | - | 登录成功之后的回调函数 | | openHarmonyGuide | boolean | 否 | - | 是否开启该功能 | | loginOutFinish | Function | 是 | - | 退出接口调用结束以后得回调函数 | | userInfo | UserInfo | 否 | {} | 用户数据，有了就传入，没登录功能的就不用传 |

项目相关参数

需要使用到项目命名空间的需要传 例如：场景值 repo

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | repoInfo | repoInfoType | 是 | - | 项目信息 | | headerCustomProps | HeaderPropsForCustom | 是 | - | 自定义custom所需信息 | | headerCustomProps.errorCode | number | 是 | - | 错误码，正常传null或者0 错误情况传具体错误码 | | headerCustomProps.repoProps | object | 是 | - | 见：HeaderPropsForCustom中仓库场景相关属性 |

组织相关参数

需要使用到项目命名空间的需要传 例如：场景值 org

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | orgInfo | OrgInfo | 是 | - | 组织信息 | | headerCustomProps | HeaderPropsForCustom | 是 | - | 自定义custom所需信息 | | headerCustomProps.errorCode | number | 是 | - | 错误码，正常传null或者0 错误情况传具体错误码 | | headerFunctions.orgProps | object | 是 | - | { isOrgFollow?: boolean } 组织的命名空间旁关注按钮 |

用户相关参数

需要使用到项目命名空间的需要传 例如：场景值 user

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | otherUserInfo | UserInfo | 否 | - | 其他用户信息，看他人个人首页的场景 | | headerCustomProps | HeaderPropsForCustom | 是 | - | 自定义custom所需信息 | | headerCustomProps.errorCode | number | 是 | - | 错误码，正常传null或者0 错误情况传具体错误码 | | headerFunctions.userProps | object | 是 | - | { isOtherUser?: boolean } 是否为其他用户 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | followDevCommunity | - | 关注组织 | | followUser | - | 关注用户 |

插槽 保留了原本header中的头部中的底部插槽和search的插槽

| 插槽名 | 说明 | |--------|------| | bodyHeader | 头部底下第一行的位置一般用户放tab 例如：项目/组织的tab | | info | bodyHeader的子插槽 细分 | | menu | bodyHeader的子插槽 细分 | | headerBottom | bodyHeader再往下 |

// SceneValue 枚举值
enum SceneValue {
  home = 'home',
  repo = 'repo',
  org = 'org',
  aiHome = 'aiHome',
  aiRepo = 'aiRepo',
  aiGuide = 'aiGuide',
  blog = 'blog',
  news = 'news',
  active = 'active',
}

interface HeaderPropsForCustom {
  /** 根据权限及是否允许显示设置错误页面 */
  errorCode?: number;
  /** 组织场景相关属性 */
  orgProps?: {
    /** 是否关注组织 */
    isOrgFollow?: boolean;
  };
  /** 仓库场景相关属性 */
  repoProps?: {
    /** 项目名称加载状态 */
    repoNameLoading?: boolean;
    /** 是否是 gh_mirrors 项目 */
    isGhMirrors?: boolean;
    /** 是否是私有项目 */
    isPrivate?: boolean;
    /** 是否为 space 项目 */
    isSpaces?: boolean;
  };
  /** 用户场景相关属性 */
  userProps?: {
    /** 是否为其他用户 */
    isOtherUser?: boolean;
  };
}


// 用户数据类型
interface UserInfo {
  domain_id?: string;
  email?: string;
  id?: string;
  arts_id?: string;
  mobile?: string;
  avatar?: string;
  nickname?: string;
  username?: string;
  access_token?: string;
  refresh_token?: string;
  xauth_token?: string;
  isFollow?: boolean;
  atomgit_username?: string;
  [x: string]: any;
}

// 项目数据类型
interface repoInfoType {
  id?: number;
  name?: string;
  path?: string;
  path_with_namespace?: string;
  created_at?: string;
  star_count?: number;
  starred?: boolean;
  default_branch?: string; // 默认分支
  creator?: {
    id: number;
    iam_id: string;
    username: string;
    nick_name: string;
    avatar_url: string;
  };
  description?: string;
  module_setting?: {
    repo_id: string;
    modules: {
      key: string;
      type: string;
      value: string;
    }[];
  };
  web_url?: string;
  repo_type?: `${RepoType}`;
  /* 是否由安全漏洞派生 */
  forked_by_secure_issue: Record<string, any> | null
  enterprise?: any;
  audit_fields?: IAuditInfo[];
  [propName: string]: any;
}

// 组织数据类型
interface OrgInfo {
  create_ai?: boolean;
  id?: number;
  full_path?: string;
  avatar?: string;
  name?: string;
  description?: string;
  path?: string;
  email?: string;
  location?: string;
  orgId?: string;
  repoId?: string;
  visibility?: string;
  web_url?: string;
  mode?: string | number;
  readme_repo?: string;
  readme_branch?: string;
  readme_file_path?: string;
  item_type?: string;
  module_setting?: {
    group_id: string;
    modules: {
      key: string;
      type: string;
      value: string;
    }[];
  };
  my_role?: {
    access_level: number;
  };
  orgModule?: OrgModuleType[];
  audit_fields?: IAuditInfo[];
  [proName: string]: any;
}

使用示例

Aside

Aside 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | isLogin | boolean | 是 | - | 是否登录 | | sceneValue | SceneValue | 否 | SceneValue.home | 传入侧边栏使用的场景值 | | request | Function | 否 | () => Promise.resolve({ data: null }) | 请求实例 | | globalStore | Object | 否 | {} | 全局状态存储对象，用于组件内部状态管理 | | userInfo | AccountInfo | 否 | {} | 用户信息 | | showPreferencesSetting | boolean|undefined | 否 | undefined | 显式设置-是否展示偏好设置 | | showThemeSetting | boolean|undefined | 否 | undefined | 显式设置-是否展示偏好设置-多主题设置，需与showPreferencesSetting 一起使用 | | showLangSetting | boolean|undefined | 否 | undefined | 显式设置-是否展示偏好设置-多语言设置，需与showPreferencesSetting 一起使用 |

Aside 事件

无

Aside 插槽

无

使用示例

ToolsFloat

ToolsFloat 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | isLogin | boolean | 是 | - | 是否登录 | | sceneValue | SceneValue | 否 | SceneValue.home | 传入右侧工具栏使用的场景值 | | request | Function | 否 | () => Promise.resolve({ data: null }) | 请求实例 | | globalStore | Object | 否 | {} | 全局状态存储对象，用于组件内部状态管理 |

ToolsFloat 事件

| 事件名 | 参数 | 说明 | |--------|------|------| | toggle-growth-center | - | 切换成长中心的显示状态 |

ToolsFloat 插槽

无

使用示例

GitCode 前端各项目接入示例

gitcode-fe

• 安装

npm install vue-layout-gitcode

• 注入环境变量

各项目的测试、预发、生产环境变量，通过组件提供的 setLayoutConfig 方法进行注入，方便测试验证。

main.ts 中注入：

import { setLayoutConfig } from 'vue-layout-gitcode';

// 将 import.meta.env 中的所有环境变量转换为一个普通对象，传递给 vue-layout-gitcode
const layoutConfig = Object.fromEntries(
  Object.entries(import.meta.env).map(([key, value]) => [key, value])
);

setLayoutConfig(layoutConfig);

• 代理特定事件，如 'login', 'logout'，登录弹窗这块的功能已经迁移到了 vue-layout-gitcode 组件中，外部项目触发相关事件的 mitt emit 时，需代理到 vue-layout-gitcode 中处理：

src/utils/eventBus.ts

import { GitCodeLayoutEmitter } from 'vue-layout-gitcode';

// 转发 - 由 GitCode layout 组件库处理的事件
const GitCodeLayoutProxyEvents = ['login', 'logout', 'updateNotice', 'updateNoticeCount'];

const getEmitter = (evtName: keyof EventBus): Emitter<EventBus> =>
  GitCodeLayoutProxyEvents.includes(evtName) ? (GitCodeLayoutEmitter as unknown as Emitter<EventBus>) : emitter;

export const addEventListener = (evtName: keyof EventBus, callback: (payload: any) => void) => emitter.on(evtName, callback);

export const emitEvent = (evtName: keyof EventBus, payload?: any) => getEmitter(evtName).emit(evtName, payload);

export const offEvent = (evtName: keyof EventBus, handler?: any) => getEmitter(evtName).off(evtName, handler || undefined);

• 多主题相关

组件导出 currentTheme 和 setTheme, 外部项目原 theme/index.js 中, 使用组件导出的 currentTheme 和 setTheme

gitcode/src/themes/index.js

import { currentTheme as layoutCurrentTheme, setTheme as layoutSetTheme } from 'vue-gitcode-layout';

export const currentTheme = layoutCurrentTheme;

export const setTheme = (theme) => {
  layoutSetTheme(theme);
};

• 在 layout 组件中引入布局模块

BaseLayout/index.vue 中引入，并使用：

import { ToolsFloat, GitCodeAside as Aside } from 'vue-layout-gitcode'
import 'vue-layout-gitcode/style.css';

本地开发

node 16及以上版本

安装及启动

# 安装依赖
npm install

# 启动开发服务器
npm run dev

Cannot find module 的处理

碰到引入 Vue 组件时，IDE 提示报错：Cannot find module '@/components/Icon/index.vue' or its corresponding，可以检查下 VSCode 或者 Cursor 的插件，建议使用 Volar 来处理 Vue 组件，在“设置”中，把 vue.server.hybridMode 的值改为 false。

本地构建、引入调试

• 构建

npm run build

• 关联

在当前项目根目录下执行 npm link，在目标项目（如 gitcode-fe）根目录下执行 npm link gitcode-layout-lib 进行关联；

有改动后，可以重新打包：npm run build，也可以运行 npm run build:watch 命令，监听文件改变实时构建；

• 引入

gitcode-fe 中引入 Demo 组件示例：

import { Demo, HelloWorld } from 'gitcode-layout-lib'
import "gitcode-layout-lib/style.css";

然后就可以在 template 中使用了：

<Demo></Demo>

npm 发布

• 在 package.json 中，更新版本号，在 CHANGELOG.md 中，更新发布记录

• npm run build 构建

• 构建完成后，执行 npm publish，进行发布；

目前是发布到 npm 官方源，需将 npm 源先切换成官方源：

npm config set registry https://registry.npmjs.org

如果命令行提示登录的话，执行 npm adduser，按提示，跳转到浏览器中，打开相应登录页面，登录验证后，会继续 publish 流程

特性

• 基于 Vue 3 开发
• 提供完整的 TypeScript 类型支持
• 高度优化的打包体积
• ES 模块格式，支持现代构建工具

构建优化

该库使用了多种优化技术以确保最小的包体积：

• 代码压缩和混淆
• 移除控制台输出和调试代码
• CSS 最小化
• 代码空白和注释的移除

许可证

MIT