pin_drop当前位置:知识文库 ❯ 图文
元信息：HTML manifest - 完整教程与代码示例
教程简介
Web App Manifest（Web应用清单）是一个JSON文件，用于定义渐进式Web应用（PWA）的名称、图标、启动URL、显示模式等核心属性。通过manifest，Web应用可以像原生应用一样安装到用户的主屏幕、拥有独立的启动画面和窗口。本教程将全面讲解manifest的配置方法、PWA相关技术及最佳实践。
核心概念
什么是 Web App Manifest
Web App Manifest 是一个遵循W3C规范的JSON文件，它提供了关于Web应用的元数据，使浏览器能够将网站作为原生应用安装到用户的设备上。
PWA 的核心技术
Manifest 的作用
-
使网站可以被"安装"到主屏幕
-
控制应用的启动画面（Splash Screen）
-
定义应用的显示模式（全屏、独立窗口等）
-
指定应用的主题色和背景色
-
定义应用的图标集合
语法与用法
基本引入方式
代码示例
<link rel="manifest" href="/manifest.json">Manifest 完整属性
代码示例
{
"name": "应用完整名称",
"short_name": "短名称",
"description": "应用描述",
"start_url": "/",
"scope": "/",
"display": "standalone",
"orientation": "any",
"theme_color": "#1a73e8",
"background_color": "#ffffff",
"dir": "ltr",
"lang": "zh-CN",
"icons": [],
"screenshots": [],
"categories": [],
"shortcuts": [],
"related_applications": [],
"prefer_related_applications": false
}属性详解
name 与 short_name
代码示例
{
"name": "前端学习网 - 从入门到精通的前端开发教程",
"short_name": "前端学习"
}start_url 与 scope
代码示例
{
"start_url": "/?source=pwa",
"scope": "/"
}提示：
start_url可以包含追踪参数，用于分析PWA安装来源。
display 显示模式
代码示例
{
"display": "standalone"
}orientation 屏幕方向
代码示例
{
"orientation": "any"
}icons 图标
代码示例
{
"icons": [
{
"src": "icons/icon-72x72.png",
"sizes": "72x72",
"type": "image/png",
"purpose": "any"
},
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "icons/maskable-192x192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "maskable"
},
{
"src": "icons/maskable-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]
}purpose 属性说明：
Maskable Icon 规范：
代码示例
+------------------+
| 安全区域外 | ← 可能被裁切
| +------------+ |
| | | |
| | 安全区域 | | ← 核心内容放在这里
| | (80%区域) | |
| | | |
| +------------+ |
| |
+------------------+关键规则：Maskable图标的核心内容必须放在中心80%的安全区域内，外围20%可能被系统遮罩裁切。
shortcuts 快捷方式
代码示例
{
"shortcuts": [
{
"name": "新建文章",
"short_name": "新建",
"description": "创建一篇新文章",
"url": "/editor/new",
"icons": [
{
"src": "/icons/new-article.png",
"sizes": "96x96"
}
]
},
{
"name": "搜索教程",
"short_name": "搜索",
"url": "/search",
"icons": [
{
"src": "/icons/search.png",
"sizes": "96x96"
}
]
}
]
}screenshots 截图
代码示例
{
"screenshots": [
{
"src": "screenshots/home.png",
"sizes": "1080x1920",
"type": "image/png",
"form_factor": "narrow",
"label": "首页截图"
},
{
"src": "screenshots/desktop.png",
"sizes": "1920x1080",
"type": "image/png",
"form_factor": "wide",
"label": "桌面端截图"
}
]
}related_applications 关联应用
代码示例
{
"related_applications": [
{
"platform": "play",
"url": "https://play.google.com/store/apps/details?id=com.example.app",
"id": "com.example.app"
},
{
"platform": "itunes",
"url": "https://apps.apple.com/app/example/id123456789"
}
],
"prefer_related_applications": false
}categories 分类
代码示例
{
"categories": ["education", "productivity", "utilities"]
}
常用分类值： books、business、education、entertainment、finance、food、games、health、lifestyle、music、navigation、news、photo、productivity、shopping、social、sports、travel、utilities、weather
代码示例
示例1：完整的 PWA 配置
代码示例
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="theme-color" content="#1a73e8">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<meta name="apple-mobile-web-app-title" content="前端学习">
<title>前端学习网</title>
<!-- Manifest -->
<link rel="manifest" href="/manifest.json">
<!-- Favicon -->
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
</head>
<body>
<!-- 页面内容 -->
</body>
</html>示例2：完整的 manifest.json 文件
代码示例
{
"name": "前端学习网 - 从入门到精通的前端开发教程",
"short_name": "前端学习",
"description": "提供专业的HTML、CSS、JavaScript前端开发教程，适合初学者和进阶开发者。",
"start_url": "/?source=pwa",
"scope": "/",
"display": "standalone",
"orientation": "any",
"theme_color": "#1a73e8",
"background_color": "#ffffff",
"dir": "ltr",
"lang": "zh-CN",
"categories": ["education", "productivity"],
"icons": [
{
"src": "/icons/icon-72x72.png",
"sizes": "72x72",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-96x96.png",
"sizes": "96x96",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-128x128.png",
"sizes": "128x128",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-144x144.png",
"sizes": "144x144",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-152x152.png",
"sizes": "152x152",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-384x384.png",
"sizes": "384x384",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/maskable-192x192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "maskable"
},
{
"src": "/icons/maskable-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
],
"screenshots": [
{
"src": "/screenshots/mobile-home.png",
"sizes": "750x1334",
"type": "image/png",
"form_factor": "narrow",
"label": "移动端首页"
},
{
"src": "/screenshots/desktop-home.png",
"sizes": "1920x1080",
"type": "image/png",
"form_factor": "wide",
"label": "桌面端首页"
}
],
"shortcuts": [
{
"name": "搜索教程",
"short_name": "搜索",
"description": "搜索前端开发教程",
"url": "/search/?source=shortcut",
"icons": [
{
"src": "/icons/shortcut-search.png",
"sizes": "96x96",
"type": "image/png"
}
]
},
{
"name": "最新文章",
"short_name": "最新",
"description": "查看最新发布的文章",
"url": "/latest/?source=shortcut",
"icons": [
{
"src": "/icons/shortcut-latest.png",
"sizes": "96x96",
"type": "image/png"
}
]
}
],
"related_applications": [
{
"platform": "play",
"url": "https://play.google.com/store/apps/details?id=com.example.frontend",
"id": "com.example.frontend"
}
],
"prefer_related_applications": false
}浏览器兼容性
注意：Safari/iOS 对manifest的支持有限，需要同时配置
apple-mobile-web-app-*系列meta标签。
注意事项与最佳实践
1. 必需属性
代码示例
{
"name": "必需",
"short_name": "必需",
"start_url": "必需",
"display": "必需",
"icons": "必需（至少192和512）"
}2. iOS 兼容配置
代码示例
<!-- iOS不支持manifest，需要额外配置 -->
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<meta name="apple-mobile-web-app-title" content="前端学习">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">3. 启动画面颜色
代码示例
{
"theme_color": "#1a73e8",
"background_color": "#ffffff"
}注意：
background_color用于启动画面背景色，应与页面的首屏背景色一致，避免启动时的闪烁。
4. Maskable Icon 设计
代码示例
{
"icons": [
{
"src": "/icons/maskable-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]
}关键：Maskable图标的核心内容必须在中心80%的安全区域内（即内圆半径40%的区域），外围20%可能被裁切。
5. Service Worker 注册
代码示例
// manifest.json 需要配合 Service Worker 才能实现PWA
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/sw.js')
.then(function(registration) {
console.log('Service Worker 注册成功');
})
.catch(function(error) {
console.log('Service Worker 注册失败:', error);
});
}6. 安装体验优化
代码示例
// 监听安装提示事件
var deferredPrompt;
window.addEventListener('beforeinstallprompt', function(e) {
// 阻止默认安装提示
e.preventDefault();
// 保存事件，稍后触发
deferredPrompt = e;
// 显示自定义安装按钮
showInstallButton();
});
// 用户点击安装按钮时
function installApp() {
if (deferredPrompt) {
deferredPrompt.prompt();
deferredPrompt.userChoice.then(function(result) {
if (result.outcome === 'accepted') {
console.log('用户安装了应用');
}
deferredPrompt = null;
});
}
}代码规范示例
标准项目 PWA 配置
代码示例
<head>
<!-- ========== PWA 核心配置 ========== -->
<link rel="manifest" href="/manifest.json">
<meta name="theme-color" content="#1a73e8">
<!-- ========== iOS 兼容 ========== -->
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<meta name="apple-mobile-web-app-title" content="应用名称">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<!-- ========== Favicon ========== -->
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
</head>manifest.json 最小配置
代码示例
{
"name": "应用名称",
"short_name": "短名称",
"start_url": "/",
"display": "standalone",
"theme_color": "#1a73e8",
"background_color": "#ffffff",
"icons": [
{
"src": "/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}常见问题与解决方案
常见问题
PWA安装条件是什么？
Chrome要求以下条件同时满足：使用HTTPS协议；有有效的manifest.json；manifest包含name/short_name、icons（192+512）、start_url、display；注册了Service Worker；Service Worker有fetch事件处理器。
manifest.json 放在哪个位置？
可以放在任何位置，但推荐放在网站根目录。scope 属性决定了manifest的作用范围，如果manifest在子目录中，scope默认为该子目录。
如何调试manifest？
Chrome DevTools > Application > Manifest 面板；Lighthouse审计检查PWA配置；Manifest Validator 在线验证。
iOS上manifest不生效怎么办？
iOS Safari对manifest的支持有限。必须同时配置 apple-mobile-web-app-* 系列meta标签和 apple-touch-icon。iOS不支持 display: standalone，需要通过 apple-mobile-web-app-capable 实现。
如何检测应用是否已安装？
方法1：检查display-mode：window.matchMedia('(display-mode: standalone)').matches；方法2：检查navigator.standalone（iOS）；方法3：通过start_url参数检测。
总结
Web App Manifest 是将网站升级为PWA的核心配置文件，它定义了应用的安装体验、启动画面、显示模式等关键属性。配合Service Worker和HTTPS，可以为用户提供接近原生应用的使用体验。
核心要点回顾：
-
必需属性：name、short_name、start_url、display、icons（192+512）
-
显示模式：standalone是最常用的PWA显示模式
-
图标配置：提供any和maskable两种purpose的图标
-
iOS兼容：必须同时配置apple-mobile-web-app系列标签
-
启动画面：theme_color和background_color决定启动画面颜色
-
快捷方式：shortcuts提供长按图标的快速操作入口
-
安装提示：使用beforeinstallprompt事件实现自定义安装体验
-
Service Worker：manifest需要配合Service Worker才能实现完整PWA功能
合理配置manifest，是构建高质量PWA的第一步，也是提升Web应用用户体验的关键环节。
本文涉及AI创作
内容由AI创作，请仔细甄别
