Fluffy Contribution

EN: A Vue 3 component library for displaying GitHub contribution graphs in your Vue projects.

中文: 一款基于 Vue 3 的 GitHub 贡献度组件库，支持 Vue 组件和 Canvas 两种渲染模式。

Features / 特性

EN:

• Lightweight and easy to use
• Two rendering modes: Vue components (DOM) and Canvas (native drawing)
• Support for multiple time ranges (yearly, monthly, weekly)
• Customizable themes and styles
• Dark mode support
• Compatible with Vue 3 and TypeScript
• Personal access token authentication for GitHub API

中文:

• 轻量高效，开箱即用
• 两种渲染模式：Vue 组件模式（DOM）和 Canvas 模式（原生绘制）
• 支持多种时间范围（年 / 月 / 周）
• 可自定义主题和样式
• 暗黑模式支持
• 兼容 Vue 3 和 TypeScript
• 使用 GitHub Personal Access Token 认证

Installation / 安装

npm install fluffy-contribution-core
# or / 或者
yarn add fluffy-contribution-core
# or / 或者
pnpm add fluffy-contribution-core

Quick Start / 快速开始

Vue Component Mode / Vue 组件模式（默认）

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    renderer="vue"
    theme="primary"
    @select="handleSelect"
  />
</template>

<script setup lang="ts">
import { FluffyContribution } from 'fluffy-contribution-core'

const handleSelect = (item: { time: string; count: number }) => {
  console.log(`Selected: ${item.time} with ${item.count} contributions`)
}
</script>

Canvas Mode / Canvas 模式

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    renderer="canvas"
    theme="primary"
  />
</template>

<script setup lang="ts">
import { FluffyContribution } from 'fluffy-contribution-core'
</script>

Lite Mode / 精简模式

仅展示贡献图，不包含标题和设置项。适用于直接传入数据的场景。

<template>
  <FluffyContribution
    :contributions="myData"
    mode="lite"
    renderer="vue"
  />
</template>

API Reference / API 参考

FluffyContribution Props / 属性

| Property / 属性 | Type / 类型 | Default / 默认值 | Description / 说明 | |-----------------|-------------|-------------------|---------------------| | renderer | 'vue' \| 'canvas' | 'vue' | Rendering mode / 渲染模式 | | mode | 'lite' \| 'full' | 'full' | Display detail level / 显示模式 | | type | 'yearly' \| 'monthly' \| 'weekly' | 'yearly' | Time range / 时间范围 | | theme | 'primary' \| 'yellow' \| 'red' | 'primary' | Color theme / 主题色 | | shape | 'square' \| 'circle' | 'square' | Cell shape, Vue mode only / 单元格形状（仅 Vue 模式） | | username | string | '' | GitHub username / GitHub 用户名 | | personalToken | string | '' | GitHub personal access token / GitHub 访问令牌 | | contributions | ContributionDay[] | [] | Direct data injection / 直接传入数据 | | name | string | 'Fluffy Contribution' | Header title / 头部标题 | | notice | string | '' | Header notice text / 头部通知文字 | | showTimeSwitch | boolean | true | Show time range switcher / 显示时间切换器 | | border | boolean | true | Show border / 显示边框 | | borderColor | string | '#e5e5e5' | Border color / 边框颜色 | | backgroundColor | string | '#ffffff' | Background color / 背景颜色 | | darkMode | boolean | false | Enable dark mode / 启用暗黑模式 |

Events / 事件

| Event / 事件 | Payload / 载荷 | Description / 说明 | |-------------|----------------|---------------------| | select | { time: string, count: number } | Emitted when a contribution item is clicked / 点击贡献项时触发 |

Exposed Methods / 暴露方法

| Method / 方法 | Description / 说明 | |---------------|---------------------| | refresh() | Manually re-fetch contribution data / 手动重新获取数据 | | currentType | Current time range type (reactive) / 当前时间范围类型（响应式） |

Configuration Examples / 配置示例

Dark Mode / 暗黑模式

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    :dark-mode="true"
    background-color="#0d1117"
    border-color="#30363d"
  />
</template>

Custom Theme / 自定义主题

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    theme="yellow"
    renderer="canvas"
  />
</template>

With Direct Data / 直接传入数据

<script setup lang="ts">
import { FluffyContribution, type ContributionDay } from 'fluffy-contribution-core'

const myData: ContributionDay[] = [
  { date: '2025-01-01', count: 5 },
  { date: '2025-01-02', count: 3 },
  // ...
]
</script>

<template>
  <FluffyContribution
    :contributions="myData"
    mode="lite"
    renderer="canvas"
  />
</template>

GitHub Personal Access Token / 访问令牌配置

EN:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new token with public_repo scope
3. Use the token in the personalToken prop

中文:

1. 进入 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 生成一个新的 token，勾选 public_repo 权限
3. 将 token 传入 personalToken 属性

Legacy Components / 旧版组件

The original BaContribution, BaItem, BaTooltip, and BaTimeSwitch components remain available and functional. See the GitHub README for legacy API details.

旧版 BaContribution、BaItem、BaTooltip、BaTimeSwitch 组件仍然可用。旧版 API 详见 GitHub 仓库。

License / 许可证

MIT

Author / 作者

Fluffy_CX

Made with ❤️ for Vue 3 community