@mar7th/march7th-ui
v1.2.0
Published
框架无关的原生 Web Components UI 库，使用共享 March7th 主题系统 | Framework-agnostic Web Components powered by the March7th theme system
Maintainers
san-yue-qiReadme
March7th UI
一套基于原生 Web Components 的轻量 UI 库，为个人博客、作品集和展示型网站设计。颜色、明暗模式、动态 Hue 和状态色由 @mar7th/march7th-theme 统一提供，可与 Astro、Vue、React 或 Svelte 页面共享同一套主题状态。
官方网站：https://ui.march7th.online
✨ 特性
- 框架无关 — 纯原生 Web Components，无 UI 框架绑定
- 无需构建 —
<script src>直接加载，开箱即用 - 共享主题 — 与 March7th UI Vue 共用亮色/暗色、动态 Hue 和 OKLCH 状态色色阶
- 双重用法 — Web Components 和 CSS 类两种使用方式
- 定制构建 — 通过内置 Builder 页面按需选择组件
- 58 个组件 — 覆盖表单、数据、主题、交互、反馈、内容、工具七大类别
📦 安装
pnpm add @mar7th/march7th-ui主题包会作为正式依赖自动安装，不需要额外声明。通过包管理器使用时，引入组件、完整样式入口即可：
import "@mar7th/march7th-ui"
import "@mar7th/march7th-ui/theme.css"Astro 与 Vue 混用
全局 Layout 负责加载样式，浏览器脚本负责注册原生组件。Vue island 和原生组件会复用同一个主题控制器、localStorage 键和 CSS token。
---
import "@mar7th/march7th-ui-vue/style.css"
import "@mar7th/march7th-ui/theme.css"
import { createThemeInitScript } from "@mar7th/march7th-ui/theme"
const themeInitScript = createThemeInitScript()
---
<script is:inline set:html={themeInitScript} />
<script>
import "@mar7th/march7th-ui"
</script>
<m7-theme-switch />
<m7-button type="primary">原生组件</m7-button>
<slot />组件注册入口是浏览器代码，不要放在 Astro frontmatter 中执行。
🎯 推荐：自定义软件包
March7th UI 是轻量工具包，推荐只引入项目实际用到的组件。完整包包含 58 个组件，而典型博客通常只需其中 8–12 个，可通过 Builder 只保留实际使用的组件。
方式一：Builder 可视化构建（推荐）
打开 src/builder.html（或查看文档站自定义软件包页面），勾选所需组件，点击"下载定制包"，获得精简的 march7th-custom.js + march7th-custom.css，自托管后引入：
<link rel="stylesheet" href="/assets/march7th-tokens.css">
<link rel="stylesheet" href="/assets/march7th-custom.css">
<script src="/assets/march7th-theme.js"></script>
<script src="/assets/march7th-custom.js"></script>方式二：手动按需加载
直接在 HTML 中引入所需组件的单独文件，m7-core.js 必须最先加载：
<link rel="stylesheet" href="node_modules/@mar7th/march7th-ui/dist/march7th-theme.css">
<script src="node_modules/@mar7th/march7th-ui/dist/march7th-theme.js"></script>
<!-- 核心（必须最先） -->
<script src="node_modules/@mar7th/march7th-ui/src/components/m7-core.js" defer></script>
<!-- 按需引入 -->
<script src="node_modules/@mar7th/march7th-ui/src/components/m7-theme-switch.js" defer></script>
<script src="node_modules/@mar7th/march7th-ui/src/components/m7-post-card.js" defer></script>
<script src="node_modules/@mar7th/march7th-ui/src/components/m7-toc.js" defer></script>🚀 快速开始（完整加载）
如果只是快速体验或对包体积没有要求，可以直接加载全量 bundle：
<!-- 共享主题 Token + 组件样式 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mar7th/[email protected]/dist/march7th-theme.css">
<!-- 共享主题运行时 + 全部 58 个组件 -->
<script src="https://cdn.jsdelivr.net/npm/@mar7th/[email protected]/dist/march7th-ui.standalone.min.js"></script>
<!-- 使用组件 -->
<m7-theme-switch></m7-theme-switch>
<m7-button type="primary">保存</m7-button>
<m7-input label="邮箱" type="email" required></m7-input>📚 组件列表
主题组件（3 个）
m7-theme-switch- 亮色/暗色/跟随系统切换m7-hue-picker- 动态调整主题色调m7-camera- 网页截图，致敬三月七的拍拍拍风格（娱乐向）
表单组件（15 个）
m7-button- 操作按钮，支持类型、尺寸、图标、加载和链接模式m7-input- 文本输入框，支持前后缀图标、密码切换、清空、字符计数m7-textarea- 多行文本框，支持自适应高度、字符计数m7-switch- 开关切换m7-checkbox- 复选框，支持半选状态m7-radio- 单选框m7-radio-group- 单选框组，支持受控值和键盘导航m7-label- 可访问表单标签m7-native-select- 保留平台交互的原生选择器m7-slider- 水平或垂直单值滑块m7-toggle- 双态工具按钮m7-toggle-group- 单选或多选双态按钮组m7-badge- 语义状态徽章，6 种颜色m7-empty- 空状态占位m7-form-item- 表单项布局包装器
数据展示组件（7 个）
m7-alert- 默认或危险语义提示框m7-avatar- 带图片回退的头像m7-card- 组合式内容卡片m7-separator- 水平或垂直分隔线m7-aspect-ratio- 固定宽高比容器m7-table- 数据表格，支持排序、行选择、自定义列渲染m7-pagination- 分页导航
反馈与导航组件（5 个）
m7-skeleton- 骨架屏加载占位m7-breadcrumb- 面包屑导航m7-progress- 进度条，支持条形/环形/仪表盘m7-popconfirm- 确认气泡m7-steps- 步骤条
交互组件（15 个）
m7-tabs- 标签页切换m7-accordion- 折叠展开面板m7-drawer- 侧边抽屉m7-modal- 模态对话框m7-tooltip- 悬停提示m7-popover- 可交互浮层m7-select- 下拉选择m7-carousel- 图片轮播m7-marquee- 滚动跑马灯m7-typewriter-text- 打字机效果m7-affix- 固定定位m7-top- 回到顶部m7-spin- 加载动画m7-lightbox- 图片灯箱m7-video- 视频播放器
内容组件（9 个）
m7-post-card- 博客文章卡片m7-post-meta- 文章元信息m7-project-card- 作品集项目卡片m7-profile-card- 个人资料卡片m7-stat-card- 统计数据卡片m7-friend-link- 友情链接卡片m7-timeline- 时间轴m7-toc- 目录导航m7-tags- 标签云
工具组件（4 个）
m7-notice- 通知公告m7-toast- 轻提示m7-code-copy- 代码复制按钮m7-core- 基础工具函数
💡 使用示例
访问 官方文档 或打开 src/march7th-theme-preview.html 查看所有组件的实时演示。
🛠️ 定制构建
打开 src/builder.html 或访问文档站自定义软件包页面，选择需要的组件，生成精简包。
📄 License
MIT