Hacker News Best

Show HN: Get your coding agent off ~2019 JavaScript, onto modern web primitives

6.9内容质量

TL;DR · AI 摘要

GitHub - GoogleChrome/modern-web-guidance: Keep your coding agent up to date with the latest web best practices · GitHub...

核心要点

  • 主题聚焦:Show HN: Get your coding agent off 2019 JavaScri
  • 来源:Hacker News Best,建议结合原文判断细节。
  • AI 分析暂不可用,本条为保底评分与摘要。
#AI#编程#前端#后端#安全
打开原文

GitHub - GoogleChrome/modern-web-guidance: 通过最新网络最佳实践保持你的编码代理更新 · GitHub

现代网络指南

现代网络指南是一套技能,将网络平台专业知识、最佳实践和浏览器兼容性数据直接嵌入到你的编码代理中。它帮助你的编码代理远离过时模式,转向能够充分利用现代网络平台功能和能力的解决方案。

由 Google Chrome、Microsoft Edge、Mozilla Firefox、MDN 团队以及网络开发社区共同维护。

文档 · 评估仪表板 · 源代码 · 报告问题

快速入门

code
npx modern-web-guidance@latest install

此命令运行交互式向导以安装现代网络指南。请参阅下方的其他安装方法。

#### 尝试使用(无需安装)

code
#
搜索相关指南
npx modern-web-guidance@latest search
"
animate a dialog modal backdrop
"
#
通过 ID 获取指南
npx modern-web-guidance@latest retrieve
"
animate-to-from-top-layer
"
#
扫描代码库以查找需要现代化的遗留模式
npx modern-web-guidance@latest legacy-scan
.

为什么需要它?

编码代理通常默认使用较旧的模式,因为大型语言模型训练数据包含大量遗留代码。这通常导致它们为现在已有原生高性能网络平台解决方案的任务生成臃肿的 JavaScript。

即使模型知道某个 API 存在,它通常也缺乏生成生产就绪代码所需的现代实现模式的密度。

现代网络指南弥补了这一差距。我们的 CLI 工具将针对性的专家精选指南直接返回到代理的上下文窗口中,重点关注:

  • 现代浏览器 API:帮助模型正确构建它们经常误用的 API 结构。
  • 性能与可访问性:优先使用可被浏览器优化且包含内置可访问性功能的平台级 API。
  • 负责的回退方案:指导模型使用合理轻量的回退方案,而不是沉重的 polyfill 或遗留库。

包含哪些内容?

我们涵盖过去几年网络平台的新功能,一直到最前沿的技术。指南设计为高效利用 token;我们运行评估以剔除模型已知的最低公分母内容。

核心领域

#### 🎨 用户体验

流畅的视觉状态(视图过渡、进入/退出动画、视差滚动、CSS 滚动条颜色)。

#### 📐 CSS 布局

现代布局系统(容器查询、子网格、现代颜色空间如 oklch、文本换行调整、行高裁剪)。

#### ⚡ 性能

速度优化(即时预加载、交互到下一帧绘制(INP)诊断、通过 scheduler.yield 安排任务)。

#### 📝 表单与 UI

原生组件(用于工具提示的锚点定位、Popover API、对话框、:user-invalid 验证、自动调整大小的字段)。

#### ♿ 可访问性

重要考虑因素(屏幕阅读器和键盘操作性、内容导航和可发现性)。

#### 🤖 内置 AI

本地客户端模型(原生翻译、摘要和语言检测 API)。

查看示例:导航抽屉指南。

#### 完整列表

250 项现代网络功能

CSS 与布局(140 项功能)

::backdrop

content-visibility

progress()

::details-content

contrast-color()

reading-flow

::file-selector-button

跨文档视图过渡

相对颜色

::placeholder

currentColor

rem

::selection

自定义高亮

resize(CSS 属性)

:dir()

自定义属性

revert

:focus-visible

显示动画

revert-rule

:focus-within

元素作用域视图过渡

安全区域内边距环境变量

:has()

em 单位

滚动标记目标伪类

:host-context()

字段尺寸

滚动方法承诺

:is()

滤镜

滚动对齐

:modal

flex-wrap: balance

滚动对齐事件

:not()

Flexbox

scroll-axis-lock

<选择器>的:nth-child()

字体大小

scroll-behavior

:placeholder-shown

字体大小调整

滚动驱动动画

:user-valid 和 :user-invalid

强制颜色

scroll-initial-target

:where()

渐变插值

scroll-target-group

@function

渐变

scrollbar-color

@scope

网格布局

scrollbar-gutter

@starting-style

网格轨道

scrollbar-width

@supports

断词

scrollend

abs() 和 sign()

image-set()

scrollIntoView()

强调色

独立变换属性

阴影部分

活动视图过渡

继承

sibling-count() 和 sibling-index()

生成内容的替代文本

初始值

粘性定位

锚点定位容器查询

交互媒体查询

子网格

锚点定位

interpolate-size

系统颜色

动画(CSS)

隔离

文本溢出

外观

Lab 和 LCH

文本描边和填充(兼容性前缀)

宽高比

light-dark()

文本框

at-rule()

行数限制

文本装饰

attr()

行高

文本装饰跳过墨迹

背景混合模式

线性(linear)缓动函数

文本装饰跳过墨迹:全部

背景裁剪:边框区域

逻辑属性

文本装饰跳过空格

圆角

遮罩

文本换行

box-shadow

min()、max() 和 clamp()

文本换行:平衡

calc-size()

混合混合模式

文本换行:美观

级联层

嵌套

transition-behavior

ch 单位

Oklab 和 OkLCh

过渡(CSS)

clip-path

溢出裁剪边距

三角函数(CSS)

color-mix()

溢出换行

重置

color-scheme

溢出:裁剪

用户选择

圆锥渐变

覆盖

视图过渡

容器查询(尺寸)

overscroll-behavior

view-transition-class

容器滚动状态查询

prefers-color-scheme 媒体查询

视口单位

容器样式查询

prefers-contrast 媒体查询

Web 动画

内容

prefers-reduced-motion 媒体查询

HTML & DOM(36 个特性)

:autofill

<slot>

HTML 流式设置器

:indeterminate

<video>

HTML 在画布中

<audio>

自主自定义元素

inert

<details>

blocking="render"

兴趣触发器

<dialog closedby>

可定制的 <select>

触发器命令

<dialog>

声明式阴影 DOM

延迟加载媒体

<input type="checkbox" switch>

电子邮件、电话和 URL <input> 类型

moveBefore()

<input type="range">

获取优先级

MutationObserver

<input>

focusgroup

互斥 <details> 元素

<link rel="expect">

表单关联自定义元素

弹出框

<link rel="preload">

hidden="until-found"

popover="hint"

<progress>

HTML 设置方法

阴影 DOM

JavaScript & APIs(74 个特性)

<install>

url() 的 integrity()

清理器 API

<meta name="text-scale">

交互内容丰富度绘制性能条目

调度器 API

<template for>

交叉观察器

小、大和动态视口单位

AbortController 和 AbortSignal

Intl.DurationFormat

软导航性能条目

ARIA 属性反射

键盘事件

推测规则

ariaNotify()

语言检测器

子资源完整性

异步剪贴板

LanguageModel

摘要生成器

自动更正

延迟加载图片和iframe

SVG

beforeinstallprompt

light-dark() 图像值

Temporal

border-shape

本地网络访问

text-decoration-inset

连接白名单

长动画帧性能条目

text-fit

corner-shape

long-animation-frames-style-layout

顶层 await

凭证管理

导航 API

touch-action

url() 的 cross-origin()

navigator.install()

翻译器

document.modelContext

源点

可信类型

电子邮件验证

页面可见性

用户代理客户端提示

enterkeyhint

页面可见性状态性能条目

Web 应用清单

事件时间性能条目

分区 Cookie

Web 应用源点迁移

联合凭证管理

密码凭证

Web 认证

Fetch

权限策略

Web 认证信号方法

fetchLater

指针事件

Web 加密

与表单关联的 WebMCP 属性

引用策略

WebAssembly

HTML 处理指令

url() 的 referrer-policy()

webcrypto-modern-algos

image()

注册的自定义属性

WebOTP

inputmode

Resize 观察器

203 个真实开发场景

可访问性

  • accessible-error-announcement:将程序化可访问性状态(如 aria-invalid)与视觉 :user-invalid 状态同步,确保屏幕阅读器用户仅在交互后收到错误反馈,与视觉体验一致。
  • accessible-generated-content:以可访问的方式使用 CSS 生成内容(::before / ::after),包括装饰性内容的替代文本。
  • respect-os-text-scale:遵循操作系统的文本缩放偏好,使字体大小、布局和基于 rem 的测量值符合用户的可访问性设置。

内置 AI

  • language-detection:检测用户生成内容或现有网站内容的语言。
  • language-model:使用 Prompt API 在浏览器中运行设备端自然语言推理,支持流式输出、结构化 JSON 响应和多轮会话管理。
  • summarizer:使用设备端 Summarizer API 对文本内容进行摘要。
  • translator:使用设备端 Translator API 在不同语言之间进行文本翻译。

CSS

  • animate-to-intrinsic-sizes:平滑地将交互组件(如手风琴、菜单和展开卡片)动画到其自然尺寸并返回。
  • atrule-support-conditionals:仅当浏览器支持特定 at-rule 时,有条件地应用某些 CSS 规则或声明。
  • calculate-with-intrinsic-sizes:基于元素的固有尺寸计算其大小,同时确保符合给定的设计约束。
  • child-state-based-styling:构建一个根据子元素状态改变样式的组件。例如,根据主题切换按钮是否被选中(或未被选中)来渲染浅色或深色模式的组件。
  • content-based-styling:构建一个根据是否包含特定子元素来改变布局的组件。例如,如果组件包含图片,则使用多列布局,否则默认使用单列布局。
  • css:面向现代 CSS 架构的操作指南,包括级联、选择器、作用域、嵌套和设计标记。在编写样式或管理设计系统时使用此指南。
  • css-layout : 现代 CSS 布局技术,如 flexbox、grid、subgrid、容器查询、锚点定位和内在尺寸。在构建响应式 UI 组件或页面布局时使用此技能。
  • design-token-reactivity : 定义高阶设计标记,如密度模式(紧凑、舒适、宽敞)或主题,并让子组件以组件适当的方式直接响应变化。
  • dynamic-sibling-styling : 创建动态视觉光谱或布局排列,使元素组能根据元素数量自动适应。
  • fluid-scaling : 基于父容器尺寸而非固定断点,平滑缩放字体大小、间距和媒体尺寸。
  • individual-transform-properties : 独立控制单个元素的 CSS 变换属性(如 translate、rotate、scale),与其他变换属性分离进行动画或覆盖。
  • overflow-clipping-control : 调整元素的可见裁剪边界,使其与内容边缘、内边距边缘或边框边缘对齐,或与这些边缘的指定偏移量对齐,提供更精细的内容裁剪控制。
  • reduce-style-repetition : 通过将复杂的动态样式逻辑封装到可重用函数中(如根据输入参数计算渐变的函数),减少样式重复。
  • responsive-design : 构建适应容器和视口尺寸的 UI,包括容器查询、动态视口单位、宽高比和响应式排版。
  • selector-atrule-combinations : 基于选择器与条件 @-规则的交集或并集定位元素,同时最小化重复。
  • size-aware-styling : 构建样式依赖于自身宽度或高度而非视口尺寸的组件。例如,卡片组件可根据自身尺寸切换布局,或根据宽度条件性显示辅助文本的按钮。
  • style-parent-with-has : 当表单字段无效时,为父元素(如标签或字段集)应用样式。
  • usage-aware-component-variations : 使用 CSS 容器样式查询构建能根据语义上下文调整视觉逻辑的组件。

forms

  • animated-select-picker : 创建自定义选择组件,其下拉菜单带有动画效果。例如,菜单淡入或滑入视图,选项在选中时动画显示。
  • autofill-address-form : 构建带有正确自动补全属性和自动填充支持的地址表单。
  • autofill-highlight-inputs : 自定义已自动填充但未被用户编辑的表单字段样式。
  • autofill-payment-form : 构建带有正确自动补全值和自动填充支持的支付表单,用于收集信用卡信息。
  • autofill-sign-in-form : 构建带有正确自动补全值和自动填充支持的登录表单。
  • autofill-sign-up-form : 构建带有正确自动补全值和自动填充支持的注册表单。
  • brand-consistent-forms : 在不替换为自定义组件的情况下,使复选框、单选按钮、范围滑块和进度条与网站的配色方案保持一致。
  • branded-select-styling : 创建自定义选择元素,其按钮、选择器、箭头图标和勾选标记无缝匹配品牌或设计系统的排版、颜色、间距和边框处理。
  • 自定义选择器布局:创建自定义选择器,使选项以独特或有趣的方式排列,而非传统的堆叠列表形式。
  • 表单字段自动适应内容:允许表单字段根据用户输入动态调整大小,例如用户输入时或选择不同选项时。通过设置最大和最小尺寸限制,创建与页面设计相适应的动态响应式表单字段。
  • 输入法安全的回车提交:在文本区域和单行输入框(如聊天、搜索、内联重命名)中安全实现回车提交功能,防止输入法用户提交不完整的文本。
  • 必填字段反馈:仅在用户交互后,为被跳过或留空的必填表单字段提供错误提示,避免预判性错误,确保反馈及时且与用户操作流程相关。
  • 丰富媒体选择器:创建自定义选择组件,其选项可包含复杂HTML格式(如图片、图标和其他富文本格式),而不仅仅是纯文本。
  • 选择菜单交互:仅在用户与控件交互后,验证选择菜单中是否选择了非默认选项。
  • 滑块:使用自定义轨道、滑块手柄、填充状态和焦点状态样式化原生范围滑块,同时保留原生功能和可访问性。
  • 短信OTP表单:通过自动提取代码和可访问的表单输入,验证用户手机号码和通过短信发送的一次性验证码。
  • 开关:使用原生HTML开关属性构建可访问的开关控件,在不支持时回退到样式化的复选框。
  • 交互后验证输入:仅在用户完成初始交互后显示表单字段验证反馈(如密码复杂度或电子邮件格式要求),避免页面加载时或用户输入过程中出现过早的错误提示。

html

  • 可访问的Web组件:通过ElementInternals ARIA混合功能默认设置角色和ARIA状态,使用delegatesFocus管理焦点,并在单一阴影根内保持ARIA关系,使自定义元素具备可访问性。
  • 自定义元素:定义、注册并管理自主自定义元素的生命周期,涵盖构造函数规则、生命周期回调、升级时机、属性/特性反射以及命名规范。
  • 与表单关联的自定义元素:通过formAssociated和ElementInternals使自定义控件原生参与表单,提交自身值,与约束验证集成,并响应重置、禁用和状态恢复操作。
  • 预渲染自定义元素:在服务器端渲染自定义元素,然后在原位置进行水合处理,无需重新渲染或出现未样式化内容的闪现。
  • 阴影DOM:使用阴影DOM封装组件的DOM和样式,通过HTML模板高效构建树结构,并使用插槽投影用户内容。
  • Web组件样式:通过:host选择器、继承和自定义属性实现主题化、::slotted和::part,以及组件内部的级联层和容器查询,跨阴影边界进行样式设置。
  • web-components : 编写和使用 Web Components 的方向和跨领域原则,涵盖自定义元素、Shadow DOM、模板和插槽、声明式 Shadow DOM、跨 Shadow 边界样式、表单关联自定义元素以及可访问性要求。在构建可复用的 UI 组件、设计系统或服务器端渲染的自定义元素时使用本指南。

js

  • calculate-event-differentials : 使用 Temporal.Duration 和 Intl.DurationFormat 计算日期和时间之间的经过或剩余时间,平衡持续时间单位,并格式化本地化的人类可读持续时间。
  • capture-location-agnostic-data : 使用 Temporal Plain 类型对不依赖位置的日历日期、挂钟时间、部分日期(如周期性生日、信用卡过期日期)和无时区漂移的周期性月度间隔进行建模。
  • coordinate-global-events : 通过明确绑定到 IANA 地理时区来安排未来的会议或事件,确保事件时间在夏令时(DST)转换、时钟调整期间的“跳过”或“重复”小时后仍保持准确。
  • sort-high-precision-timestamps : 使用 Temporal.Instant 解析、排序并测量亚毫秒或纳秒级 ISO 8601 时间戳之间的间隔,避免 Date 截断冲突。
  • support-global-calendar-systems : 准确显示和计算非格里高利历系统(如伊斯兰历、希伯来历或农历)中的日期,以满足国际用户需求。

performance

  • batch-analytics-events : 将多个分析、遥测和 Core Web Vitals 事件合并为单个信标发送,减少网络竞争并降低服务器负载,同时仍能提供实时更新。
  • break-up-long-tasks : 将繁重的同步处理(复杂计算和/或长循环)或 DOM 更新拆分,以提高交互到下一次绘制(INP)的响应速度,并让浏览器处理用户输入和屏幕重绘。
  • calculate-total-foreground-time : 计算用户实际查看页面的总时间,排除标签页处于后台的时段。
  • conditional-async-dependencies : 在无需对页面所有脚本依赖项进行复杂协调的情况下,有条件地加载或初始化异步依赖项(如导入缺失的 Web 特性 polyfill)。
  • defer-rendering-heavy-content : 通过延迟渲染非立即可见内容来减少内容密集型网页的渲染时间(如包含长列表、大量文章或复杂仪表板的页面)。
  • defer-work-until-scroll-ends : 将 DOM 更新、数据获取、分析跟踪或布局重新计算等昂贵操作延迟到滚动完成之后,以保持流畅的滚动性能。
  • deliver-optimized-decorative-images : 同时提供下一代图像格式(如 AVIF 或 WebP)和多种像素密度(如 1x 和 2x),以动态协商最适合用户设备性能的文件大小和视觉质量组合,从而交付优化后的装饰性图像(如背景、UI 图标或复杂蒙版)。
  • deprioritize-background-fetches : 对使用 Fetch API 进行的后台数据获取进行降级处理,以防止与用户发起的请求发生网络竞争。
  • detect-initial-visibility-state : 可靠地确定页面是否最初在后台加载,即使在脚本在用户将页面置于前台后异步加载的情况下也能准确判断。
  • efficient-background-processing : 当组件不在屏幕可视区域时暂停后台 JavaScript 执行(如 <canvas> 动画、WebGL 渲染或高频 WebSocket 数据轮询),以节省系统资源和电池寿命,并在内容滚动回视口时及时恢复执行。
  • faster-spa-view-transitions : 通过保留视图的结构化 DOM 状态而非在每次导航时销毁和重建,实现单页应用(SPA)中更快返回已访问视图的过渡效果。
  • flicker-free-client-side-ab-testing : 使用客户端 JavaScript 交付并渲染 A/B 测试、多变量测试或其他实验,通过修改或注入 HTML、CSS 和 JavaScript 实现无闪烁内容切换,避免原始内容先显示再闪烁切换至实验内容。
  • full-session-analytics : 可靠地跟踪用户整个页面访问过程中的分析数据、核心网页指标(Core Web Vitals)、错误和遥测数据,并在用户离开页面时延迟发送数据。
  • identify-heavy-scripts : 识别导致长时间动画帧的主要脚本
  • identify-inp-causes : 识别导致交互到下一帧渲染(Interaction to Next Paint, INP)响应性差的缓慢 JavaScript 执行及其他原因。
  • improve-next-page-load-performance : 通过预取或预渲染用户可能接下来访问的页面,提升页面加载性能。
  • interaction-paint-timing : 测量用户交互和客户端导航渲染新内容到屏幕所需的时间。
  • interactions-in-complex-layouts : 通过避免在复杂布局(如数据密集型仪表板或电子表格式网格)中触发布局重计算,使交互更流畅、响应更快(降低交互到下一帧渲染(INP)得分)。
  • lazy-load-video-and-audio : 延迟加载屏幕外的音视频资源(包括视频封面图片和预加载媒体数据),直到媒体播放器接近视口区域,以节省带宽并减少初始页面加载时的网络争用。
  • optimize-image-priority : 优化最大内容绘制(LCP)候选图片的加载优先级,降低非关键图片的优先级,以减少关键资源加载延迟。
  • optimize-preload-priority : 优化预加载内容的相对优先级,减少关键资源加载延迟。
  • optimize-script-priority : 通过提升关键异步脚本的加载优先级并降低非必要或位于页面底部的脚本优先级,优化脚本加载顺序以减少延迟。
  • out-of-order-html-streaming : 声明式更新页面内容,将后续流式传输到同一 HTML 文档或通过命令式 JavaScript API 注入的内容进行同步。
  • resolution-optimized-pseudo-elements : 在 CSS 伪元素(如 ::before 和 ::after)中使用分辨率优化图像,以减少 DOM 节点数量。
  • schedule-tasks-by-priority : 按优先级调度任务,确保关键任务优先执行,后台任务被延迟处理。

privacy

  • privacy : 为网页开发者提供以行动为导向的指南,用于实施隐私设计、数据最小化、第三方审计和安全数据处理。在设计应用程序、集成第三方服务、处理用户数据或配置安全标头时使用此技能。

pwa

  • install-web-app : 通过浏览器控制的同意用户界面,从页面安装网络应用程序。
  • migrate-web-app-origin : 在保留用户配置和操作系统级别快捷方式的同时,将已安装的网络应用迁移到新源。

security

  • client-side-encryption : 使用公钥封装或密钥协议(包括混合和抗量子保护)建立共享密钥,并通过认证加密在浏览器中加密敏感数据。
  • digital-signatures : 使用经典或抗量子(抗量子计算)非对称密钥在浏览器中对消息、令牌或工件进行签名和验证,以确保数据完整性和真实性。
  • local-network-access : 从公共网络应用访问用户本地网络或回环接口上的资源。
  • passkey-authentication : 使用通行证密钥对返回用户进行主要登录身份验证。
  • passkey-conditional-create : 在成功密码登录后,静默为现有用户注册通行证密钥。
  • passkey-management : 允许用户查看和管理注册到其账户的通行证密钥。
  • passkey-reauthentication : 在敏感操作前,使用用户现有的通行证密钥验证已登录用户的身份。
  • passkey-registration : 为现有用户账户注册通行证密钥。
  • passkeys : 实施WebAuthn和通行证密钥的网络应用的全面指南和跨领域原则。在处理通行证密钥注册、身份验证、管理或重新验证时使用此指南。
  • quick-sign-ins : 在导航到登录页面或中断工作流程前,使用已保存的通行证密钥或密码立即对返回用户进行身份验证。
  • restrict-outbound-connections : 限制页面或工作者仅与明确的网络端点白名单通信,以防止未经授权的第三方请求和客户端数据泄露。
  • sanitize-untrusted-html : 通过移除不安全元素和属性,安全地解析和显示来自用户输入的不可信HTML内容。
  • secure-external-subresources : 验证从第三方源加载的外部脚本、样式表、字体和图像的密码学完整性,并控制这些请求是否发送凭据或来源URL。
  • trusted-types : 通过定义可信类型策略来防止基于DOM的XSS攻击,使用该策略在向DOM sink(如innerHTML)写入时对不可信HTML进行清理,并通过内容安全策略强制执行可信类型。
  • validate-origins : 在跨文档消息和URL之间安全地比较和验证网络源和站点,而无需容易出错的字符串解析。
  • verify-email-ownership : 在账户创建、登录或恢复期间,无需发送一次性验证码或魔法链接电子邮件,即可验证用户是否拥有电子邮件地址。

ui-atoms

  • carousel-slide-effects : 创建包含图片或其他视觉元素的幻灯片轮播,每个幻灯片在进入、居中或退出滚动器时进行动画效果。例如,幻灯片可能淡入/淡出、旋转、放大或缩小等。
  • 组件特定的明暗主题 : 强制某些元素独立于页面颜色方案,始终以浅色模式或深色模式显示(例如代码块、媒体播放器等)。
  • 图标 : 显示和管理可通过 CSS 设置和参数化的图标,加载速度快,任何分辨率下都清晰锐利,并能正确暴露给(或隐藏于)辅助技术。
  • 位置感知提示框 : 构建带有方向箭头(或其他视觉样式)的提示框和弹出框,当元素切换到备用位置时,箭头会自动指向正确方向。
  • 下拉显示 : 构建下拉显示功能,允许用户通过下拉屏幕来揭示更多内容(例如搜索栏)。
  • 响应式表格 : 构建数据表格,以正确的标题语义呈现表格数据,并确保在小屏幕和辅助技术环境下仍可读且可导航。
  • 滚动位置感知元素 : 构建浮动按钮或控件(返回顶部、滚动到底部、聊天启动器等),根据用户是否滚动过屏幕来显示或隐藏。
  • 滚动进度指示器 : 创建滚动进度条、分步进度跟踪器或任何视觉提示,以显示用户在页面或页面部分中的滚动进度。
  • 滚动可操作性提示 : 构建滚动阴影或渐变边缘,仅在特定方向确实存在更多可滚动内容时才显示。
  • 滚动时头部收缩 : 在滚动过程中,通过预定义的滚动距离,平滑地动画化固定头部或全屏封面,使其动态收缩、添加阴影并变换布局。
  • 单行溢出处理 : 在空间不足时显示必须保持单行的文本(如标签、表格单元格、导航项或文件名),同时不破坏布局或丢失文本内容。
  • 状态感知粘性标题 : 构建粘性章节标题或导航栏,当它们实际“固定”在顶部时,通过改变颜色方案或添加阴影来视觉化变换。
  • 视口感知下拉菜单 : 将下拉菜单、弹出框或上下文操作面板与触发按钮绑定,当到达视口边缘时自动翻转轴向,避免被截断。

UI 行为

  • 二维平移 : 允许用户自由平移或滚动二维表面(如地图、缩放图像、无限画布或大型数据网格),在两个方向上(无论是对角线还是中途改变方向)进行操作,而不会将手势锁定在单一水平或垂直轴上。
  • 锚点定位标签下划线 : 在两个目标元素位置之间无缝过渡。例如,在先前选中的标签和当前选中标签之间移动选中标签的下划线。
  • 元素进入/退出动画 : 在元素添加/移除 DOM 或显示值切换时,平滑地隐藏/显示元素。
  • 从顶层进入/退出动画 : 对对话框、弹出框和提示框等元素在进入/退出顶层时进行动画处理。
  • 轮播对齐高亮 : 在滚动对齐的轮播图、画廊或全屏滑动体验中,视觉化突出当前对齐的非交互项。例如,对齐时放大卡片或揭示隐藏内容。
  • consistent-cross-document-transitions : 确保在发起跨文档视图转换之前,关键页面状态已加载并稳定。这意味着关键CSS样式已加载并应用,关键JavaScript已加载并执行,且用户首次查看页面时可见的HTML内容已解析完毕。
  • cross-document-transitions : 创建完整页面导航之间的平滑无缝过渡效果,如交叉淡入淡出、自定义揭示效果或从一页到下一页内容的形态变化。
  • custom-button-actions : 声明式地将按钮连接到任意元素,通过声明式按钮命令、调用者命令、按钮命令、自定义命令或声明式切换动作触发自定义的应用特定操作。
  • declarative-dialog-popover-control : 无需编写JavaScript即可通过按钮切换对话框或弹出框的可见性。
  • directional-navigation-transitions : 通过动画视觉状态变化反映用户导航流程的方向,例如向前导航时从右侧滑入新内容,返回上一屏幕时从左侧滑入。
  • drag : 支持拖动以在页面内移动浮动元素。
  • drag-and-drop : 支持拖动以沿一个轴(水平或垂直)重新排列容器的子元素,同时保持其状态和可访问顺序。
  • dynamic-sibling-animations : 在兄弟元素之间错开动画或过渡时间,使每个元素在兄弟列表中的位置基础上延迟启动。
  • dynamic-sort : 处理容器子元素(如列表项、表格行或卡片网格)动态用户触发的重新排序的最佳实践,包含可选的动画重新排序,尊重用户偏好、良好的屏幕阅读器体验和大型列表的性能优化。
  • group-element-transitions : 在添加、删除、洗牌或重新排序时,同时平滑地重新排列和动画化列表项、卡片或网格元素的新位置(例如从购物车中移除商品)。
  • highlight-text-ranges : 高亮页面上的任意文本范围,如搜索结果、拼写错误或协作编辑光标。
  • interactive-content-reveal : 创建交互式揭示效果,如跟随用户指针的聚光灯,以揭示图像或UI部分中的细节。
  • interest-triggered-action-previews : 当用户表示兴趣(如悬停、聚焦或长按)但尚未点击时,显示按钮效果的实时预览。
  • interest-triggered-tooltips : 当用户悬停、聚焦或长按交互元素时,显示工具提示或补充信息,无需点击。
  • light-dismiss-a-dialog : 创建可通过轻度 dismiss(即点击或轻触对话框外部)关闭的模态对话框。
  • motion : 使用CSS过渡、动画、滚动驱动动画和视图过渡来动画化UI,同时保持运动在合成器上并尊重减少运动偏好。
  • move-dom-element-without-losing-state : 移动或重新父级化DOM元素而不丢失重要元素状态,如交互状态(:focus/:active)、<iframe>加载状态、动画/过渡状态等。
  • parallax-scroll-effects : 创建基于滚动的效果(如视差),其中前景和背景层以不同速度移动,随着用户滚动产生深度感。
  • persistent-top-layer-ui : 当底层 DOM 节点在 DOM 中被移动或重新父级化时,保持模态对话框、全屏元素或原生弹出框在视觉上可见且功能保持活跃状态。
  • physics-based-easing : 创建基于物理特性的自定义动画和过渡效果(如弹跳和弹簧效果),相比传统缓动曲线,这些效果更自然且更具吸引力。
  • platform-controls-dismiss-dialog : 创建可通过标准平台特定用户操作(如在桌面平台按下 Esc 键,或在移动平台执行“返回”或“关闭”手势)关闭的模态对话框。
  • prevent-page-scroll-under-modal-dialog : 在模态对话框打开时,防止底层页面发生滚动。
  • same-document-transitions : 在单页应用(SPA)中,通过平滑地改变尺寸、位置或其他样式属性,视觉化连接不同页面状态或导航中持续存在的元素(例如将产品缩略图扩展为全屏横幅图像)。
  • scoped-component-transitions : 在单个组件(卡片、列表、面板或其他子树)内对状态变化进行动画处理,同时保持页面其余部分可交互,并与其他过渡效果并行运行。
  • scroll-completion-effects : 仅在平滑的程序化滚动到目标元素完成之后,才在目标元素上触发视觉效果、动画或焦点变化。
  • scroll-entry-exit-effects : 当用户滚动时,随着元素进入和离开滚动区域(或视口),创建淡入、缩放或其他复杂揭示效果。
  • scroll-snap-realtime-feedback : 在用户滚动对齐内容时,提供实时视觉反馈,即使滚动手势尚未完成,也同步更新相关 UI 元素。
  • scroll-snap-state-sync : 将导航指示器、关联内容面板和分析跟踪与可滚动容器中当前对齐的项目同步。
  • scroll-target-on-load : 构建一个可滚动的元素列表(例如图片轮播或聊天对话线程),在初始渲染时可显示特定元素已滚动到视图中。
  • scrollytelling : 通过完全独立元素的滚动区域位置驱动,对目标元素的视觉属性(如淡出背景、切换背景色等)进行动画处理,从而创建滚动叙事体验。
  • search-hidden-content : 使用折叠面板、标签页和“阅读更多”部分等模式隐藏内容,同时确保隐藏文本在原生“页面内查找”搜索中可见、支持搜索引擎索引、允许 URL 片段深度链接,并保持 ARIA 可访问性。
  • sortable-table : 通过点击列标题对行进行排序,逐步增强数据表格的功能。
  • spatial-navigation : 实现使用方向键的可访问空间导航,并确保在不同布局模式(如网格等)中正确工作。
  • swipe-to-remove : 允许用户通过水平滑动手势对列表中的项目执行操作(如删除、归档、标记为已读等),从而快速处理条目而无需点击单独的控件。
  • swipe-to-reveal : 允许用户在列表项或内容面板上水平滑动以显示上下文操作按钮或侧边菜单,而不会自动触发操作。

ui-components

  • accordion : 构建一个带有动画效果、可选独占(一次仅打开一个)行为以及符合品牌风格的可折叠面板组件。
  • 应用菜单:构建一个应用程序菜单栏,其中多个顶级菜单(如文件、编辑和查看)作为一个键盘停靠点,通过悬停或方向键在它们之间切换。
  • 面包屑导航:构建一个面包屑导航栏,显示用户在网站层级结构中的位置,并允许他们导航到祖先页面。
  • 卡片:构建一个卡片组件,使其呈现方式能根据可用空间和内容进行自适应调整。
  • 轮播图:构建一个轮播组件,以水平或垂直布局展示一组项目。
  • 复选框:对复选框进行样式设计,包括自定义图标、布局、颜色、勾选/取消勾选动画,同时保留原生功能和无障碍特性。
  • 复制按钮:构建一个复制按钮,可将任意元素中的文本复制到剪贴板。
  • 深色模式切换:构建一个深色模式切换组件,允许用户覆盖系统颜色方案偏好,为当前网站设置深色模式。
  • 对话框:构建一个模态或非模态对话框组件,确保可访问性、合理管理焦点,并能以用户在每个平台上预期的方式关闭。
  • 悬停卡片:构建一个悬停卡片组件,当鼠标悬停在特定类型的链接(如用户资料)上时,显示一个交互式结构预览。
  • 菜单:构建一个菜单组件,展示一组选项或操作,并支持嵌套子菜单。
  • 导航栏:构建一个适应不同屏幕尺寸的网站导航栏,并能指示当前页面。
  • 导航抽屉:创建一个导航抽屉组件,当从菜单按钮触发时,从侧边滑入并覆盖在现有页面内容上,关闭时(通过滑动、点击外部区域或按 ESC 键)滑出。
  • 持续应用引导:使用固定原生覆盖层创建持续的引导流程,确保在用户交互过程中始终保持打开状态。
  • 持续通知:创建非侵入式的Toast和覆盖通知,用于持续、可堆叠的消息传递和状态通信。
  • 进度条:构建一个样式化的进度条,用于在确定和不确定状态下传达任务或进程的完成情况。
  • 进度环:构建一个进度环组件,以视觉方式表示任务或进程的完成状态,并支持中心内容和品牌一致的样式。
  • 滚动监听:在导航菜单中突出显示当前可见的页面部分。
  • 加载指示器:构建一个加载指示器,向所有用户传达繁忙状态,尊重减少动画偏好,并高效地进行动画处理。
  • 分层导航:构建全屏分层导航,允许用户深入嵌套视图,并通过滑动或导航返回,同时保持浏览器历史记录同步。
  • 选项卡:构建一个响应式选项卡界面,即使屏幕空间不足时也能提供良好的用户体验。
  • 工具栏:构建一个工具栏组件,用于显示执行操作的一组控件。

用户体验

  • 以内容为先,减少干扰:通过移除阻塞弹窗、保持持久导航紧凑、将次要内容置于按需展开的后面,最大化内容并减少干扰。
  • 适配不同设备:使布局、控件和文本适应任何设备或容器,确保触摸目标始终可用、内容适合其空间,并且不会与系统 UI 发生冲突。
  • 自然交互 : 实现具有清晰悬停、聚焦和按下反馈的自然交互,包括从触发点展开的运动、可滑动内容以及可通过键盘操作的交互动作。

视觉设计

  • 适应滚动条对比偏好 : 提高高对比度界面用户使用的滚动条可见性
  • 应用WebGL着色器 : 使用WebGL着色器为HTML内容添加自定义视觉效果
  • 浏览器UI主题化 : 使用CSS而非自定义元素重新创建,对浏览器生成的UI(如文本选择、滚动条、表单控件和选择器)进行主题化
  • 颜色 : 网页颜色指导,包括对比度要求、明暗配色方案、强制颜色模式,以及从基础颜色生成色系和色调的方法
  • 复杂形状 : 使用任意自由形态(如符号、笔触或有机纹理)对元素及其内容进行裁剪,实现更具表现力的设计
  • 对比色 : 在动态背景色上选择具有足够对比度的可读文本颜色
  • 自定义文本装饰 : 添加下划线、上划线、删除线或完全自定义形状的文本装饰,支持揭示动画、自定义偏移量和端部内边距,以及灵活的墨水跳过效果
  • 自定义滚动条颜色和粗细 : 自定义滚动条的颜色或粗细
  • 深色模式 : 以尊重用户明暗主题偏好并适配浏览器UI(如滚动条、表单控件等)的方式实现深色模式支持
  • 等宽文本行 : 使多行标题或版面中的每一行都达到相同宽度,如海报风格或堆叠式标题排版。与对齐文本不同,文本本身会根据宽度调整尺寸而非拉伸间距
  • 从画布导出HTML媒体 : 在画布中捕获并导出动态HTML内容为图像或视频帧
  • 将画布内容暴露给浏览器功能 : 将画布中渲染的内容暴露给辅助技术、翻译或阅读模式等浏览器功能
  • 改进文本布局和可读性 : 通过启用浏览器在换行时应用均匀平衡的断行方式,改进短文本内容(如不超过几行的标题)的布局和可读性
  • 在3D场景中集成交互内容 : 将交互式HTML元素集成到3D场景中
  • 精确文本对齐 : 实现任意字体文本的精确垂直对齐。例如,文本上下完全相等的视觉内边距,或与相邻图标/图片完美对齐
  • 复合挖空效果 : 组合多个形状创建复杂挖空或"挖空"效果,如为元素添加缺口
  • 柔边内容渐变 : 对内容边缘应用透明度渐变,用于指示可滚动区域或遮挡付费墙文本
  • 排版 : 网页排版最佳实践,包括字体尺寸单位、行高、文本换行与平衡,以及随视口缩放的流体字体
  • 视觉效果 : 使用CSS实现的视觉效果,包括分层阴影、混合模式、具有可预测颜色插值的渐变,以及仅用渐变构建的条纹、棋盘格、点阵和饼图等图案
  • 视觉稳定字体回退 : 定义字体样式,确保在首选字体与备用字体(或相反)切换时,文本仍保持可读性和视觉一致性
  • 视觉稳定混合字体 : 定义字体样式,使文本在使用多种字体渲染同一段文本时仍保持可读性和视觉一致性。
  • 视觉纹理内容 : 通过应用逼真的风化和纹理图案,使元素呈现出有机、老化或物理材质的外观。

WebAssembly

  • 在Web上使用C/C++ : 使用Emscripten将C/C++编译为WebAssembly

WebMCP

  • 代理表单 : 通过用WebMCP属性注解标准HTML表单,将客户端功能暴露为AI代理的工具。
  • 代理JavaScript工具 : 使用WebMCP命令式API将客户端JavaScript函数编程式注册为AI代理的工具。
  • WebMCP : 使用本指南在浏览器应用中实现WebMCP,通过声明式或命令式API将客户端功能暴露为AI代理的工具。

现代功能的安全采用

  • 渐进增强与细致回退 : 我们区分纯粹的附加增强功能(如推测性预加载)这类可让旧浏览器静默忽略的安全功能,以及关键行为(如对话框控件或网络信标)这类需要编写高度考虑过的低开销回退方案的场景。
  • 负责任的回退方案 : 我们优先使用轻量级、特定场景的自定义回退方案(<50行代码)或条件加载的polyfill,而不是重型第三方库。
  • 隐含限制与特殊行为 : 我们记录隐藏的平台限制,例如fetchLater()的64KB有效载荷配额或macOS特定的滚动条行为。
  • 基线感知集成 : 我们利用Baseline项目提供的实时兼容性数据,使代理能动态适应当前浏览器支持情况。
  • 原点试验与易失特性门控 : 涵盖实验性原点试验API或易失特性(过去3个月内发布或仍在稳定化的单引擎特性)的指南可通过搜索发现,但需要通过检索门控,防止代理在没有显式开发者同意的情况下采用不稳定的API。

项目配置 ( .mwgrc )

通过在项目根目录(或用户级回退路径~/.mwgrc)中的可选.mwgrc JSON文件,为仓库配置原点试验和易失特性的启用选项,该文件可提交以在团队中共享:

CLI命令

code
.mwgrc

键

效果

code
npx modern-web-guidance@latest set-allow-origin-trials
code
"allowOriginTrials": true

解锁实验性原点试验API的指南。

code
npx modern-web-guidance@latest set-allow-volatile-features
code
"allowVolatileFeatures": true

解锁易失性单引擎特性的指南。

实现原理

  • 激活 : 当遇到相关任务时,编码代理会激活modern-web-guidance技能。代理被指示使用modern-web-guidance CLI进行网页平台查询。
  • 本地语义搜索 : 代理运行modern-web-guidance search "<query>"。该工具使用离线零依赖嵌入模型和BM25搜索引擎(无需网络调用,无需API密钥)将查询匹配到最佳指南。
  • 指南检索 : 代理通过modern-web-guidance retrieve <guide-id>获取指南,将针对性的代码模式、注意事项和回退方案直接插入到其上下文窗口中。

提示

注意:我们使用npx确保内容不会过时,但CLI可离线使用,完全私密且本地化。npm包是自包含的,没有额外依赖项,确保低延迟和供应链安全。

替代安装方法

Vercel Skills CLI

(也称为

code
npx skills

)

code
npx skills add GoogleChrome/modern-web-guidance

GitHub CLI

code
gh skill install GoogleChrome/modern-web-guidance

Google Antigravity

code
agy plugin install https://github.com/GoogleChrome/modern-web-guidance

GitHub Copilot CLI

code
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome

Claude Code Plugin

code
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/plugin
#
选择 GoogleChrome 市场,按回车,启用 AutoUpdate
/reload-plugins

Grok Build CLI

code
grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust

Kimi Code

code
/plugins install https://github.com/GoogleChrome/modern-web-guidance

OpenAI Codex

code
codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome

更新

如果你使用 npx modern-web-guidance@latest install 安装了该技能,可以通过 npx modern-web-guidance@latest update 进行更新。

否则,请查阅你所使用代理的文档以了解如何更新插件和技能。

实证评估验证有效性

我们构建了完善的评估框架,确保内容经过实证验证并持续校准,使AI代理能够编写更高质量的代码。通过闭环验证流水线运行自动化评估:

code
[ 专家撰写指南和演示 ]
            │
            ▼
  [ 目标生成 ] ──> 在真实Web应用上的任务,黄金解决方案,Playwright评分器
            │
            ▼
  [ 校准循环 ] ───> 在黄金解决方案上运行评分器(必须100%通过)
            │               在未修改的基础应用上运行评分器(必须100%失败)
            ▼
  [ E2E代理评估 ] ────> 在有指导和无指导模式下运行编码代理
                            对比启用和禁用技能时的通过率和可访问性
  • 模拟开发者任务:我们针对完整基础应用(daily-grind, devtools-times)定义现实的开发者提示,模拟真实请求(例如“让我的图片加载更快”)。提示避免命名API或功能,测试代理是否能自然发现并应用合适的指南。
  • 静态与浏览器断言:Playwright评分器验证每个实现要求是否被遵循——检查源码模式、计算样式、运行时DOM行为和可访问性状态。
  • 自修复校准:评分器针对多代理(Claude/Codex/AGY)黄金解决方案(100%通过目标)和未修改的基础应用(0%通过目标)进行校准。
  • E2E测试:我们在真实任务中测量编码代理在有无指导下的表现。机会值(100% - 无指导通过率)和提升值(有指导 - 无指导通过率)是关键指标:如果模型在无指导时已成功,我们会修剪冗余建议;在代理表现不佳时,我们会优化指南以最大化提升。

最新评估结果快照

在评估仪表板上查看完整的每代理和每指南分析。

日期

代理 + 模型

任务 / 断言

无指导 → 有指导(提升)

11月8日

antigravity_cli (gemini-4-argon)

214 / 1673

58% → 94% (

+36pp

codex_cli (gpt-6.1-sol)

215 / 1795

54% → 82% (

+28pp

claude_code (opus-5-5)

215 / 1801

57% → 88% (

+31pp

11月6日

212 / 1773

53% → 86% (

+33pp

56% → 90% (

+34pp

212 / 1722

60% → 96% (

11月4日

209 / 1743

52% → 85% (

57% → 90% (

207 / 1722

Nov 2

205 / 1729

55% → 82% (

+27pp

可用技能包

你可以使用 --choose 参数自定义安装哪些技能包:

code
npx modern-web-guidance@latest install --choose
  • modern-web-guidance (~205 tokens): 涵盖现代浏览器 API、布局和性能的全面指南。
  • chrome-extensions (~175 tokens): 关于 Manifest V3、后台工作线程、扩展 API 和 Chrome 网上应用店发布的指导。

数据收集与隐私

Google 会收集匿名使用信息以提升工具的可靠性、相关性和性能。收集的信息包括安装数量、调用代理名称、指南检索 ID 以及代理生成的 CLI 工具搜索查询(例如 "dark mode scrollbar color-scheme")。不会收集原始用户提示内容。你可以在 modern-web.ts 中查看具体收集内容。

如需退出数据收集:在 shell 配置文件(例如 .bashrc 或 .zshrc)中设置 DISABLE_TELEMETRY=1 环境变量:

code
export
DISABLE_TELEMETRY=1

Google 会根据 Google 隐私政策 处理这些数据。

贡献者

发现 bug、过时模式或缺失的网页平台功能?请在源代码仓库(GoogleChrome/modern-web-guidance-src)中提交 issue 或查看 CONTRIBUTING.md 文件。

感谢所有贡献者!

许可证

除非另有说明:

  • 本项目中的软件代码采用 Apache License 2.0 许可协议。
  • guides/ 目录下的文档和指南内容采用知识共享署名 4.0 国际许可协议(CC-BY 4.0)。

本项目部分文档内容源自 Mozilla 贡献者、W3C、WHATWG 和 IETF 的 MDN Web Docs 及规范。