Apple UI Components

iOS 与 macOS 设计语言融合的完整 UI 组件库开发文档

安装指南

多种安装方式，快速开始使用 Apple UI 组件库

CDN 安装

最简单的安装方式，直接在 HTML 中引入 CSS 文件

<link rel="stylesheet" href="https://jianhancloud.cn/zjb522/appui.css">

适用于快速原型开发和简单项目

NPM 安装

通过 npm 包管理器安装，适合现代前端项目

npm install zjb522-apple-ui-mcp
import 'zjb522-apple-ui-mcp/dist/apple-ui.css';

适用于 React、Vue、Angular 等现代框架

直接下载

下载 CSS 文件到本地，完全离线使用

# 下载文件 curl -O https://jianhancloud.cn/zjb522/appui.css
<link rel="stylesheet" href="./apple-ui.css">

适用于需要离线部署的项目

MCP 集成指南

支持 Trae、VS Code、Cursor 等 AI IDE 的 Model Context Protocol 集成

什么是 MCP

Model Context Protocol (MCP) 是一个开放协议，允许 AI 助手直接访问工具和服务。Apple UI Components MCP 服务器让 AI 助手能够直接生成符合 Apple 设计规范的 UI 组件。

Trae 集成

在 Trae IDE 中配置 MCP 服务器

// 创建 .trae/mcp.json { "mcpServers": { "apple-ui-components": { "command": "npx", "args": ["-y", "zjb522-apple-ui-mcp"], "env": { "NODE_ENV": "production" }, "disabled": false, "autoApprove": [] } } }

配置后重启 Trae，AI 助手即可直接调用组件库

VS Code 集成

在 VS Code 中配置 MCP 服务器

// 创建 .vscode/mcp.json { "servers": { "apple-ui-components": { "type": "stdio", "command": "npx", "args": ["-y", "zjb522-apple-ui-mcp"], "env": { "NODE_ENV": "production" } } } }

需要安装 MCP 扩展插件

Cursor 集成

在 Cursor 编辑器中配置 MCP 服务器

// 创建 .cursor/mcp.json { "mcpServers": { "apple-ui-components": { "command": "npx", "args": ["-y", "zjb522-apple-ui-mcp"], "env": { "NODE_ENV": "production" } } } }

配置后重启 Cursor 即可使用

可用工具接口

MCP 服务器提供的 7 个工具接口

工具名称 描述 参数
get_component 获取特定 UI 组件 name (必填), variant (可选)
list_components 列出所有可用组件 category (可选), limit (可选)
get_design_tokens 获取 Apple 设计系统令牌 type (可选: colors, typography, spacing, all)
generate_html 生成组件 HTML 代码 component (必填), props (可选), includeStyles (可选)
get_cdn_link 获取 UI 库 CDN 链接 无
search_components 搜索组件 query (必填)
get_installation_guide 获取安装指南 platform (可选: html, react, vue, angular)

CLI 命令行工具

直接通过命令行使用 MCP 工具

# 查看版本 npx zjb522-apple-ui-mcp --version # 列出所有组件 npx zjb522-apple-ui-mcp components # 查看设计令牌 npx zjb522-apple-ui-mcp tokens --type colors # 获取安装指南 npx zjb522-apple-ui-mcp guide --platform react # 启动 MCP 服务器 npx zjb522-apple-ui-mcp start

API 参考

完整的 CSS 变量和类名 API 参考

CSS 变量列表

所有可用的 CSS 自定义属性

/* 颜色系统 */ --system-blue: #007AFF; --system-green: #34C759; --system-indigo: #5856D6; --system-orange: #FF9500; --system-pink: #FF2D55; --system-purple: #AF52DE; --system-red: #FF3B30; --system-teal: #5AC8FA; --system-yellow: #FFCC00; /* 灰色系统 */ --system-gray: #8E8E93; --system-gray2: #AEAEB2; --system-gray3: #C7C7CC; --system-gray4: #D1D1D6; --system-gray5: #E5E5EA; --system-gray6: #F2F2F7; /* 背景色 */ --bg-primary: #FFFFFF; --bg-secondary: #F5F5F7; --bg-tertiary: #E8E8ED; /* 文字色 */ --text-primary: #1D1D1F; --text-secondary: #86868B; --text-tertiary: #A1A1A6; --text-quaternary: #D2D2D7; /* 材质 */ --material-ultraThin: rgba(255, 255, 255, 0.7); --material-thin: rgba(255, 255, 255, 0.5); --material-regular: rgba(255, 255, 255, 0.3); --material-thick: rgba(255, 255, 255, 0.2); --material-chrome: rgba(255, 255, 255, 0.8); /* 阴影 */ --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.04); --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.04); --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.04); --shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.04); --shadow-glass: 0 8px 32px rgba(0, 0, 0, 0.08);

组件类名约定

BEM 命名规范

/* 命名结构 */ .ap-[组件名] .ap-[组件名]--[变体] .ap-[组件名]__[子元素] .ap-[组件名]__[子元素]--[状态] /* 示例 */ .ap-btn // 按钮基础类 .ap-btn--filled // 填充按钮变体 .ap-btn--secondary // 次要按钮变体 .ap-btn__icon // 按钮图标子元素 .ap-btn--disabled // 按钮禁用状态 .ap-card // 卡片基础类 .ap-card__header // 卡片头部 .ap-card__title // 卡片标题 .ap-card__content // 卡片内容 .ap-card__footer // 卡片底部 .ap-input // 输入框基础类 .ap-input--search // 搜索框变体 .ap-input--disabled // 禁用状态 .ap-input--error // 错误状态 .ap-modal // 模态框基础类 .ap-modal__overlay // 模态框遮罩 .ap-modal__content // 模态框内容 .ap-modal__header // 模态框头部 .ap-modal__body // 模态框主体 .ap-modal__footer // 模态框底部

更新日志

版本更新记录和功能迭代说明

v1.0.0 (2026-03-09)

  • 🎉 正式发布 1.0.0 版本

    包含完整的 1500+ 组件库

  • 🚀 支持 MCP 协议

    支持 Trae、VS Code、Cursor 等 AI IDE 集成

  • 🎨 Apple 设计系统

    iOS + macOS 设计语言融合

  • 📦 发布到 NPM

    包名: zjb522-apple-ui-mcp

组件更新

基础组件 (300+)
  • ✅ 按钮组件
  • ✅ 输入组件
  • ✅ 选择器
  • ✅ 开关
  • ✅ 滑块
  • ✅ 单选/复选
  • ✅ 标签/徽章
  • ✅ 头像
布局组件 (250+)
  • ✅ 网格系统
  • ✅ Flex 布局
  • ✅ 容器
  • ✅ 间距
  • ✅ 卡片
  • ✅ 分割线
  • ✅ 导航栏
  • ✅ 侧边栏
交互组件 (300+)
  • ✅ 模态框
  • ✅ 抽屉
  • ✅ 下拉菜单
  • ✅ 标签页
  • ✅ 手风琴
  • ✅ 提示框
  • ✅ Toast 通知
  • ✅ 日期选择器
工具类 (300+)
  • ✅ 字体工具
  • ✅ 间距工具
  • ✅ 颜色工具
  • ✅ 显示工具
  • ✅ 定位工具
  • ✅ 动画工具
  • ✅ 响应式工具
  • ✅ 无障碍工具

组件文档

1500+ 组件，涵盖所有 UI 需求

组件概览

Apple UI Components 提供了完整的组件库，分为六大类别

类别 组件数量 主要组件 状态
基础组件 300+ 按钮、输入框、开关、滑块、选择器 完整
布局组件 250+ 容器、网格、间距、定位、显示 完整
数据展示 200+ 表格、列表、卡片、进度条、标签 完整
媒体组件 150+ 图片、音频、视频、媒体卡片 完善
交互组件 300+ 模态框、抽屉、提示框、下拉菜单 完整
实用工具 300+ 工具栏、侧边栏、面板、导航 丰富

基础组件示例

按钮组件的使用方法

<button class="ap-btn ap-btn--filled">Click Me</button> <button class="ap-btn ap-btn--secondary">Cancel</button> <button class="ap-btn ap-btn--plain">Learn More</button>

输入组件示例

输入框组件的使用方法

<input type="text" class="ap-input" placeholder="Enter text..."> <input type="text" class="ap-input ap-input--search" placeholder="Search..."> <textarea class="ap-input ap-textarea" placeholder="Enter message..."></textarea>

卡片组件示例

卡片组件的使用方法

<div class="ap-card"> <div class="ap-card__header"> <div class="ap-card__title">Card Title</div> <div class="ap-card__subtitle">Subtitle</div> </div> <div class="ap-card__content"> Content goes here... </div> </div>

新增组件文档

最新扩展的20+种组件详细使用说明

滑块组件

用于选择数值范围的交互组件

<div class="ap-slider"> <div class="ap-slider__track"> <div class="ap-slider__progress" style="width: 60%;"></div> <div class="ap-slider__thumb" style="left: 60%;"></div> </div> </div> <div class="ap-slider ap-slider--range"> <div class="ap-slider__track"> <div class="ap-slider__progress" style="left: 20%; width: 40%;"></div> <div class="ap-slider__thumb" style="left: 20%;"></div> <div class="ap-slider__thumb" style="left: 60%;"></div> </div> </div>

评分组件

用于评分的星级组件

<div class="ap-rating"> <svg class="ap-rating__star ap-rating__star--filled" viewBox="0 0 24 24"> <path d="M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"/> </svg> </div> <div class="ap-rating ap-rating--small">...</div> <div class="ap-rating ap-rating--large">...</div>

标签组件

用于标签和分类展示的组件

<div class="ap-tag-cloud"> <span class="ap-tag">UI设计</span> <span class="ap-tag ap-tag--selected">前端开发</span> <span class="ap-tag ap-tag--outlined">Vue</span> <span class="ap-tag"> React <span class="ap-tag__close">×</span> </span> </div>

代码块组件

用于展示代码片段的组件

<div class="ap-code-block"> <div class="ap-code-block__header"> <span class="ap-code-block__language">HTML</span> <button class="ap-code-block__copy">复制</button> </div> <pre><code>你的代码内容</code></pre> </div>

进度环组件

环形进度指示器组件

<div class="ap-progress-ring"> <svg width="60" height="60"> <circle class="ap-progress-ring__background" cx="30" cy="30" r="24"></circle> <circle class="ap-progress-ring__progress" cx="30" cy="30" r="24" stroke-dasharray="150.72" stroke-dashoffset="60.29"></circle> </svg> <span class="ap-progress-ring__text">60%</span> </div>

通知组件

用于消息通知的组件

<div class="ap-notification ap-notification--info"> <div class="ap-notification__icon"> <!-- 图标 --> </div> <div class="ap-notification__content"> <div class="ap-notification__title">信息提示</div> <div class="ap-notification__message">这是一条通知消息</div> </div> <button class="ap-notification__close">×</button> </div> <!-- 状态变体 --> <div class="ap-notification ap-notification--success">...</div> <div class="ap-notification ap-notification--warning">...</div> <div class="ap-notification ap-notification--error">...</div>

徽章组件

用于状态标记和计数的组件

<div class="ap-badge-group"> <button class="ap-btn ap-btn--plain"> <!-- 图标 --> </button> <span class="ap-badge ap-badge--primary ap-badge--count ap-badge--top-right">5</span> </div> <!-- 变体 --> <span class="ap-badge ap-badge--dot ap-badge--success ap-badge--top-right"></span> <span class="ap-badge ap-badge--outline">默认</span>

步骤指示器

用于多步骤流程的指示器组件

<div class="ap-stepper"> <div class="ap-step ap-step--completed"> <div class="ap-step__number">✓</div> <div class="ap-step__title">填写信息</div> </div> <div class="ap-step ap-step--active"> <div class="ap-step__number">2</div> <div class="ap-step__title">确认信息</div> </div> <div class="ap-step"> <div class="ap-step__number">3</div> <div class="ap-step__title">支付完成</div> </div> </div>

头像组件

用于用户头像展示的组件

<div class="ap-avatar-group"> <div class="ap-avatar ap-avatar--online">JD</div> <div class="ap-avatar ap-avatar--away">LS</div> <div class="ap-avatar ap-avatar__count">+5</div> </div> <!-- 变体 --> <div class="ap-avatar ap-avatar--square ap-avatar--large">A</div> <div class="ap-avatar ap-avatar--small">X</div>

提示框组件

用于轻量级消息提示的组件

<div class="ap-toast ap-toast--success"> <div class="ap-toast__icon"> <!-- 图标 --> </div> <div class="ap-toast__content"> <div class="ap-toast__title">操作成功</div> <div class="ap-toast__message">文件已保存</div> </div> <button class="ap-toast__close">×</button> </div>

设计系统

完整的色彩、字体、间距设计规范

字体系统

强制性Apple系统字体优先，提供完美的跨平台字体体验

/* 字体优先级 (强制性) */ /* 无衬线字体 */ --font-sans: -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'SF Pro Text', 'Helvetica Neue', 'Arial', sans-serif !important; /* 等宽字体 */ --font-mono: 'SF Mono', SFMono-Regular, ui-monospace, 'Menlo', 'Monaco', 'Courier New', monospace !important; /* 标题字体 */ --font-display: -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Helvetica Neue', 'Arial', sans-serif !important; /* UI字体 */ --font-ui: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Helvetica Neue', 'Arial', sans-serif !important;

字体特性

  • • 强制优先级：所有元素强制使用Apple字体优先，使用 !important 确保最高优先级
  • • 分级字体系统：提供4种字体类别，适配不同使用场景
  • • 完美回退机制：在没有Apple字体的系统上自动回退到最佳替代字体
  • • 字体特性优化：开启字距调整、连字和上下文替代，提升排版质量
  • • 无障碍支持：支持动态字体调整和缩放，满足无障碍需求

系统色彩

Apple 生态系统标准色彩，支持深色模式自动适配

Blue
#007AFF
Green
#34C759
Red
#FF3B30
Orange
#FF9500
Pink
#FF2D55
Purple
#AF52DE
Indigo
#5856D6
Teal
#5AC8FA
Yellow
#FFCC00
Gray
#8E8E93

字体系统

SF Pro 字体家族，完美的字距和行高

/* 字体大小 */ --text-xs: 11px; --text-sm: 12px; --text-base: 14px; --text-lg: 16px; --text-xl: 17px; --text-2xl: 20px; --text-3xl: 22px; --text-4xl: 28px; --text-5xl: 34px;

间距系统

8pt 网格系统，一致的间距规范

/* 间距 (8pt Grid) */ --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-10: 40px; --space-12: 48px; --space-16: 64px;

圆角系统

iOS 风格的圆角规范

/* 圆角 */ --radius-sm: 6px; --radius-md: 10px; --radius-lg: 14px; --radius-xl: 18px; --radius-2xl: 24px; --radius-full: 9999px;

最佳实践

使用组件库的最佳实践和常见问题解决方案

核心特性

  • Apple Design Language fusion

    iOS 与 macOS 设计语言的完美融合

  • Human-centered interface

    以人为本的界面设计理念

  • Responsive design

    完全响应式设计，适配所有设备

  • Dark mode support

    内置深色模式支持

  • Glassmorphism effects

    现代玻璃拟态效果

  • Accessibility compliant

    完全符合无障碍访问标准

使用建议

  • 1. 从 CDN 开始

    对于新项目，建议先使用 CDN 快速体验

  • 2. 自定义主题

    通过 CSS 变量轻松自定义颜色和样式

  • 3. 按需引入

    根据项目需求选择需要的组件

  • 4. 浏览器兼容

    支持现代浏览器，包括 Safari、Chrome、Firefox

MCP 使用最佳实践

  • 1. 自动补全提示

    AI 助手会自动识别组件库，生成的代码直接可用

  • 2. 组件组合

    可以组合使用多个组件，构建复杂界面

  • 3. 主题自定义

    通过 CSS 变量轻松覆盖默认主题色

  • 4. 性能优化

    使用 CDN 版本，自动加载最新的组件库

常见问题

  • Q: 如何自定义颜色？

    A: 通过覆盖 CSS 变量，如 --system-blue: #your-color

  • Q: 支持哪些浏览器？

    A: 支持所有现代浏览器，IE11 不支持

  • Q: 文件大小是多少？

    A: 压缩后约 50KB，gzip 后约 15KB

  • Q: 如何获得支持？

    A: 查看 GitHub Issues 或联系技术支持

  • Q: MCP 服务器无法启动？

    A: 确保已安装 Node.js 16+，并检查配置文件格式是否正确

  • Q: AI 助手无法调用组件？

    A: 检查 MCP 配置是否正确，重启 IDE 并重试

  • Q: 如何更新组件库？

    A: CDN 版本自动更新，NPM 包使用 npm update zjb522-apple-ui-mcp

免责声明

此页面为用户自编文档生成。

“平台不承担责任”，“自行甄别风险”。