{
  "_description": "本文件由 data/ 生成：请改动来源文件，不要改这里。各字段的证据边界见接入指南。",
  "schemaVersion": "1.0.0",
  "kind": "entry",
  "locale": "zh-CN",
  "id": "ripple-effect",
  "name": {
    "zh": "涟漪效果",
    "en": "Ripple Effect"
  },
  "page": "https://designvocabulary.com/zh/entries/ripple-effect/",
  "self": "https://designvocabulary.com/zh/entries/ripple-effect.json",
  "alternates": {
    "zh-CN": "https://designvocabulary.com/zh/entries/ripple-effect.json",
    "en": "https://designvocabulary.com/en/entries/ripple-effect.json"
  },
  "site": {
    "catalogSchemaVersion": "0.1.0",
    "entries": 158,
    "index": "https://designvocabulary.com/zh/entries/index.json",
    "query": "https://designvocabulary.com/api/query?lang=zh",
    "guide": "https://designvocabulary.com/zh/agents/",
    "llms": "https://designvocabulary.com/llms.txt"
  },
  "provenance": {
    "sourceBacked": [
      "entry.definition"
    ],
    "editorial": [
      "entry.boundary",
      "entry.signature",
      "entry.when",
      "entry.when_not",
      "entry.tradeoff",
      "entry.comparison",
      "entry.rules",
      "entry.relations",
      "entry.implementationNote",
      "entry.behavior"
    ],
    "scope": "定义参考以上来源；数字界面示例、选择建议、条件关系及配方由本样例编辑，尚未经用户研究验证。",
    "editorialStatus": "drafted",
    "specimenData": "fictional",
    "specimenNote": "示例为原创虚构界面；定义附来源，用法与配方为编辑建议。",
    "sources": [
      {
        "id": "ripple-material-web",
        "url": "https://github.com/material-components/material-web/blob/main/docs/components/ripple.md",
        "title": "Material Web · Ripple (docs/components/ripple.md)",
        "checkedAt": "2026-10-20",
        "archive": {
          "status": "unconfirmed",
          "confirmed": false,
          "url": null,
          "capturedAt": null,
          "lookupUrl": "https://web.archive.org/web/20261020*/https://github.com/material-components/material-web/blob/main/docs/components/ripple.md"
        }
      },
      {
        "id": "ripple-compose-material3",
        "url": "https://kotlinlang.org/api/compose-multiplatform/material3/androidx.compose.material3/ripple.html",
        "title": "Compose Multiplatform API · androidx.compose.material3 · ripple",
        "checkedAt": "2026-10-20",
        "archive": {
          "status": "unconfirmed",
          "confirmed": false,
          "url": null,
          "capturedAt": null,
          "lookupUrl": "https://web.archive.org/web/20261020*/https://kotlinlang.org/api/compose-multiplatform/material3/androidx.compose.material3/ripple.html"
        }
      }
    ],
    "lists": [],
    "ordered": false,
    "listDisclaimer": "席位号是编辑位置，不是评分、排名或人气统计；清单未收满时保持原样，不补足。"
  },
  "entry": {
    "id": "ripple-effect",
    "type": "micro",
    "name": {
      "zh": "涟漪效果",
      "en": "Ripple Effect"
    },
    "aliases": [
      "Ink Ripple",
      "Material Ripple",
      "水波纹",
      "点击涟漪"
    ],
    "granularity": "state",
    "intents": [
      "inform"
    ],
    "tags": [
      "涟漪",
      "按下",
      "触控反馈",
      "状态层",
      "Material"
    ],
    "definition": "用户按下控件时，从触点处向外扩散的一圈半透明圆形波纹，覆盖控件表面后淡出；它是 Material Design 用来表达按下状态的一种具体实现，属于叠在控件上的半透明“状态层”。",
    "boundary": "涟漪是按下状态反馈的一种实现方式，而不是按下状态本身：按下状态回答“按压被收到了吗”，涟漪只是用“从触点扩散的波纹”来回答它，同样的问题也可以用变色、内陷或阴影来回答。它带有明确的 Material 视觉血统，放进其他设计语言里会显得借来的；它也不是加载指示或操作结果——波纹播完不代表动作已完成。与悬停、焦点态不同，涟漪的扩散动画在 Material 的实现里专属于按下这一刻，悬停和焦点只显示静态的状态层。",
    "signature": [
      "波纹以手指或指针的按下位置为圆心向外扩散，而不是整块同时变色",
      "波纹是半透明的覆盖层，下方的标签与图标保持可读",
      "松开或移出后波纹淡出，控件恢复静止外观"
    ],
    "when": [
      "产品采用或接近 Material 设计语言，用户已经熟悉这种按压反馈",
      "列表行、卡片等大面积可点击区域需要让用户看清按在了哪里",
      "触控界面没有悬停态，需要一个比单纯变色更明显的按压确认"
    ],
    "when_not": [
      "产品的视觉语言与 Material 无关，借来的涟漪会显得像另一套系统",
      "把涟漪当成唯一反馈，而在减弱动态偏好下它被关闭后什么也不剩",
      "在波纹尚未播完时就跳转或刷新页面，用户看到的只是一闪而过的残影"
    ],
    "tradeoff": "涟漪把“按在哪里”和“按到了”一并表达出来，在大面积触控目标上比单纯变色更容易被注意到；代价是它带着鲜明的 Material 识别度，并且依赖动画——动画被关闭或在低端设备上掉帧时，它要么消失，要么显得拖沓。",
    "comparison": {
      "focus": "用一个从触点扩散的波纹确认按压，并指出按在了哪里",
      "mechanism": "按下时以触点为圆心播放半透明覆盖层的扩散动画，松开后淡出",
      "cost": "带有 Material 识别度，且依赖动画，需要为减弱动态准备静态替代"
    },
    "sources": [
      {
        "id": "ripple-material-web",
        "title": "Material Web · Ripple (docs/components/ripple.md)",
        "url": "https://github.com/material-components/material-web/blob/main/docs/components/ripple.md",
        "claim": "Material Design 官方 Web 组件库的文档把涟漪定义为一种“状态层”，用于传达组件或可交互元素的状态；状态层是覆盖在元素上的半透明层。文档说明涟漪在悬停与按下两种指针交互时显示，并指出涟漪是纯视觉组件、没有辅助技术方面的要求。本词条据此把涟漪归为按下反馈的一种视觉实现，并提醒不能用它承担可访问的状态信息。",
        "checkedAt": "2026-10-20",
        "archive": {
          "lookupUrl": "https://web.archive.org/web/20261020*/https://github.com/material-components/material-web/blob/main/docs/components/ripple.md",
          "status": "unconfirmed",
          "checkedAt": "2026-10-20T07:58:44.798Z",
          "error": "save-request-failed"
        }
      },
      {
        "id": "ripple-compose-material3",
        "title": "Compose Multiplatform API · androidx.compose.material3 · ripple",
        "url": "https://kotlinlang.org/api/compose-multiplatform/material3/androidx.compose.material3/ripple.html",
        "claim": "该 API 文档称 Ripple 是 Indication 的 Material 实现，通过绘制涟漪动画与状态层来表达不同的交互：对按下交互启动一段新的涟漪动画，对其他交互则显示透明度随交互类型变化的固定状态层。本词条据此区分涟漪的扩散动画（专属按下）与悬停、焦点时的静态状态层。",
        "checkedAt": "2026-10-20",
        "archive": {
          "lookupUrl": "https://web.archive.org/web/20261020*/https://kotlinlang.org/api/compose-multiplatform/material3/androidx.compose.material3/ripple.html",
          "status": "unconfirmed",
          "checkedAt": "2026-10-20T07:58:46.882Z",
          "error": "save-request-failed"
        }
      }
    ],
    "relations": [
      {
        "target": "pressed-state",
        "kind": "related",
        "condition": "需要为可按压控件设计按下反馈",
        "reason": "涟漪是按下状态反馈在 Material 语言中的一种具体实现；按下状态的要求（即时、可区分、松开才执行）同样约束涟漪，而涟漪只是其中一种答案。",
        "basis": "editorial"
      },
      {
        "target": "transition-animation",
        "kind": "related",
        "condition": "涟漪与页面或组件的转场在同一次点击中先后播放",
        "reason": "涟漪确认输入被接收，转场交代界面如何变化；二者叠在一起时要让涟漪先被看见，再开始转场。",
        "basis": "editorial"
      },
      {
        "target": "haptic-feedback",
        "kind": "composes_with",
        "condition": "触控设备上的按压需要更强的确认",
        "reason": "涟漪是视觉通道的按压确认，触觉反馈是另一个通道；在减弱动态偏好下关闭涟漪时，触觉与静态变色可以接替。",
        "basis": "editorial"
      },
      {
        "target": "focus-indicator",
        "kind": "related",
        "condition": "同一控件同时支持键盘和指针操作",
        "reason": "涟漪只在按下时扩散，不能代替键盘焦点的持久可见指示；两者须同时存在且互不遮蔽。",
        "basis": "editorial"
      }
    ],
    "rules": [
      {
        "when": "用涟漪表达按下状态",
        "instruction": "让波纹在按下的瞬间开始，并保证即使动画被关闭，控件仍有一个静态的颜色或状态层变化表示按下。",
        "strength": "recommend",
        "basis": "editorial"
      },
      {
        "when": "点击后会立即导航或替换内容",
        "instruction": "在开始转场前给涟漪留出可被看见的时间，或改用不依赖动画的按下反馈。",
        "strength": "recommend",
        "basis": "editorial"
      }
    ],
    "behavior": {
      "states": [
        "rest",
        "pressed",
        "spreading",
        "fading"
      ],
      "a11y": [
        "涟漪只是视觉反馈，控件的角色、名称和状态仍须通过可访问属性表达",
        "减弱动态偏好下不播放扩散动画，以静态状态层代替",
        "涟漪的半透明覆盖不能降低标签文字与背景的对比度"
      ],
      "motion": "按下即从触点开始扩散，覆盖控件后在松开时淡出；减弱动态偏好下省略扩散，仅保留静态的按下状态层"
    },
    "demo": null,
    "version": "0.1.0",
    "editorialStatus": "drafted",
    "requirements": [],
    "demoCapabilities": [],
    "implementationNote": "本词条尚无可操作示例；插画为编辑示意，用分帧方式表现波纹扩散，不代表已验证的实现。应用到产品前仍须在真实触控设备上确认波纹从触点开始、与悬停和焦点态可区分，并在系统减弱动态设置下复查静态替代。",
    "image": {
      "src": "/images/ripple-effect.webp",
      "alt": "一张分帧示意图：虚构的 FIELDNOTES 应用中同一条列表行出现三次，从左到右依次是指尖刚按下时触点处的一个小圆、半透明圆形波纹扩散到半行宽、波纹铺满整行后开始淡出；行内的文字以灰色占位条表示。"
    },
    "searchTerms": [
      "ripple",
      "press",
      "touch feedback",
      "state layer",
      "Material"
    ]
  }
}