# @financial-times/o-overlay 中文文档 规范地址：https://npmcn.com/package/%40financial-times/o-overlay/ 版本：5\.0\.3 npm 元数据更新时间：2026-10-06T13:39:54.808Z 中文译文更新时间：2026-11-14T18:51:23.362Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40financial-times/o-overlay 原文对照：https://npmcn.com/package/%40financial-times/o-overlay/?lang=original 项目主页：https://registry.origami.ft.com/components/o-overlay ## 关键信息（来自 npm 元数据） - 包体积（解压后）：73.6 kB，25 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：2 个 - peer 依赖：@financial-times/o-brand ^4\.1\.0，@financial-times/o-viewport ^5\.1\.2，@financial-times/o-private-foundation ^1\.0\.0 - 首次发布：2019-02-12T16:54:51.954Z - 最新版本发布：2025-12-05T10:14:01.654Z - 近 30 天下载量：3943（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：55（近 12 个月 1 个） ## 中文简介 可配置的自定义覆盖框,用于显示覆盖窗口。 封面也可以切换到小屏幕上以不同方式显示 ## 安装 ```sh npm install @financial-times/o-overlay ``` 也可以使用：`pnpm add @financial-times/o-overlay`、`yarn add @financial-times/o-overlay`、`bun add @financial-times/o-overlay` ## README # o 覆盖 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40financial-times/o-overlay/#readme-licence) 可配置的自定义覆盖框,用于显示覆盖窗口。 封面也可以被切换到小屏幕上以不同方式显示. - [使用量](https://npmcn.com/package/%40financial-times/o-overlay/#readme-usage) - [标记](https://npmcn.com/package/%40financial-times/o-overlay/#readme-markup) - [萨斯](https://npmcn.com/package/%40financial-times/o-overlay/#readme-sass) - [Java 脚本](https://npmcn.com/package/%40financial-times/o-overlay/#readme-javascript) - [声明](https://npmcn.com/package/%40financial-times/o-overlay/#readme-declarative) - [强制性](https://npmcn.com/package/%40financial-times/o-overlay/#readme-imperative) - [选项参考](https://npmcn.com/package/%40financial-times/o-overlay/#readme-option-reference) - [API 概览](https://npmcn.com/package/%40financial-times/o-overlay/#readme-api-overview) - [活动](https://npmcn.com/package/%40financial-times/o-overlay/#readme-events) - [解决问题](https://npmcn.com/package/%40financial-times/o-overlay/#readme-troubleshooting) - [移徙指南](https://npmcn.com/package/%40financial-times/o-overlay/#readme-migration-guide) - [联系人](https://npmcn.com/package/%40financial-times/o-overlay/#readme-contact) - [许可证](https://npmcn.com/package/%40financial-times/o-overlay/#readme-licence) ## 使用量 检查出来 [如何将 Origami 组件纳入您的项目](https://origami.ft.com/documentation/components/#including-origami-components-in-your-project) 开始 `o-overlay`。 。 。 . ## 标记 可创建新的覆盖 [绝对](https://npmcn.com/package/%40financial-times/o-overlay/#readme-imperative) 与 JavaScript, 没有标记 。 或者,通过添加覆盖内容的模板和一个打开覆盖内容的按钮,对覆盖表进行声明定义. 要定义模板,请添加以下内容: `script` 标记包含您覆盖的内容。 请指定一个唯一的 `id` 用于模板 : ```html ``` 然后加一个触发器 `button` 与阶级 `o-overlay-trigger`,将单击打开覆盖。 通过指定模板将触发器连接到您的重叠 `id` 内 `data-o-overlay-src` 带有 `#` (以表格形式) [id 选择器](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors)) (中文(简体) ). 然后用一个独特的 ID 来命名您的覆盖 `data-o-overlay-id` 属性. ```html ``` 配置 [覆盖选项](https://npmcn.com/package/%40financial-times/o-overlay/#readme-option-reference) 作为数据属性添加到触发元素中, `data-o-overlay-[OPTION]`。例如添加 `data-o-overlay-compact="true"` 用于压缩叠加: ```html ``` ## 萨斯 包含 `oOverlay` 混合到全部输出样式 `o-overlay` 特性 : ```scss @include oOverlay(); ``` ```css .o-overlay { /* styles */ } .o-overlay--compact { /* styles */ } .o-overlay--full-screen { /* styles */ } /* etc. */ ``` 为通过选项指定输出样式的具体变体(见 [变体](https://npmcn.com/package/%40financial-times/o-overlay/#readme-variants) 供选择. 例如,只输出基底样式和 `compact` 变量,忽略其他变量: ```scss @include oOverlay( $opts: ( 'variants': ( 'compact', ), ) ); ``` ```css .o-overlay { /* styles */ } .o-overlay--compact { /* styles */ } ``` ### 备选案文 本表列出您可在 [`oOverlay` 混合](https://npmcn.com/package/%40financial-times/o-overlay/#readme-mixin-ooverlay)数字 : | 大小 | 页:1 | 品牌支持 | | :-: | :-: | :-: | | 紧凑 | 默认包含 | 核心、内部、白色标签 | | 全屏幕 | 默认包含 | 核心、内部、白色标签 | | 页眉阴影 | 默认包含 | 核心、内部、白色标签 | ## Java 脚本 ### 声明 Java 脚本已禁用 `o-overlay` 自动为 [折纸建筑服务](https://www.ft.com/__origami/service/build/) 用户。 如果你的项目是使用人工构建程序, [备忘 `o-overlay` 手动](https://origami.ft.com/documentation/components/initialising/)。 。 。 . 比如说叫 `init` 启用全部方法 `o-overlay` 文档中的实例 : ```js import oOverlay from 'o-overlay'; oOverlay.init(); ``` 或将元素传递到地址簿 `o-overlay` 实例: ```js import oOverlay from 'o-overlay'; const oOverlayElement = document.getElementById('#my-o-overlay-element'); oOverlay.init(oOverlayElement); ``` ### 强制性 您也可以构造一个新的覆盖 `o-overlay` 要素。 构造者接受两个论点: - id: 页面内覆盖的唯一标识字符串 - 选项:配置覆盖的 JSON 对象 ```js var myOverlay = new Overlay('myOverlay', { html: 'Hello world', trigger: '.blah', }); ``` ### 选项参考 - `heading`: 对象。 重叠头选项 - `.title`:弦乐. 你的封面标题 - `.visuallyhidetitle`:布尔. 如果您想要提供不同的标题样式, 此选项将防止标题跨度被添加到覆盖中 。 (在这种情况下,标题仅用于 `aria` 标签) _默认_:虚. - `.shaded`:布尔. 是否遮蔽标题的背景 。 注:为了适当运作 `heading-shaded` 变量必须包含在 CSS 中( 它是默认的) - `modal`:布尔. 重叠是否应该有模式行为 。 这将在页面和覆盖之间增加一个半透明阴影. Modal 覆盖也禁用基础文档上滚动. _默认_: 对. - `fullscreen`:布尔. 如果设置为真, 覆盖将显示全屏幕 。 此覆盖会禁用基础文档的滚动, 并用后键解析 。 注:为了适当运作 `full-screen` 变量必须包含在 CSS 中( 它是默认的) - `compact`:布尔. 如果真是这样的话 `.o-overlay--compact` 类将添加到覆盖中,从而减少内容中标题字体大小和平面。 注:为了适当运作 `compact` 变量必须包含在 CSS 中( 它是默认的) - `src`:弦乐. 无论是a _url 密码_ hTML 可以装入覆盖符,或者一个查询Selector字符串,以识别一个元素,从中提取文本 Content. - `html`: 字符串或 HTMLElement. Raw HTML( 无法声明设置) - `class`:弦乐. 用于覆盖的自定义类,例如:. `o-overlay--my-modifier`。 。 。 . - `trigger`: 字符串或 HTMLElement. 查询选择器表达式或 HTMLElement. 当出现触发设定时,会在其上添加一个点击事件处理器,以相应打开或关闭覆盖. (无法声明设置) - `zindex`:弦乐. 覆盖的 CSS z 索引属性值 . _通过 CSS 设置默认_:"10" (中文(简体) ) - `preventclosing`:布尔. 防止通过标准x按钮或出逃密钥关闭覆盖. 用于引导用户到其他地方时. 只有模式设置为真才有效 . - `customclose`:布尔. 如果您不使用标题, 但想要在 html / src 中提供关闭按钮( 包含以下类别 ) `o-overlay__close`),设置自定义与真将连接到该按钮上的 o-overlay 的近端处理器功能 . - `parentnode`:弦乐. 应该是 DOM 元素的查询选择器 。 如果设置了,则该覆盖表将作为这个文件机构或目标的孩子附上。 如果多个节点匹配,它将使用第一个节点. 如果没有匹配此选择器, 则 `body` 将被使用. - `nested`:布尔. 如果设置为真, 将不设置调整大小并逃出密钥的听众 。 这种布尔应结合 `parentnode` 设置允许在 DOM 元素内放置一个覆盖符,而不是在万事俱备上覆盖. _默认_:虚. - `nofocus`:布尔. 如果设置为真,则不将标签索引设置在包装元素上。 有用,结合 `nested` 财务报告和审定财务报表 `parentnode` 选项. _默认_:虚. - `layer`:布尔. 如果设定为真, 当创建了新的覆盖时, 覆盖会关闭 。 它会起火 `oOverlay.layerOpen` 财务报告和审定财务报表 `oOverlay.layerClose` 创建和破坏时的事件。 如果使用 `nested` 重叠. _默认_: 对. 必须设定的唯一选项是 `src` 或者说 `html`编辑 `html` 选项不能设置为 `data-` 属性,如果设置两者,则 `html` 一个会覆盖 `src`。 。 。 . 对于紧凑的叠加,标题不能被遮蔽,因为这看起来也很奇怪. 数据属性与JSON格式相同,但带有破折号. 这么说吧 `src` 这将是 `data-o-overlay-src` 联合国 `heading.title` 这将是 `data-o-overlay-heading-title`。 。 。 . _如果选项设置不正确, o- overlay 将会出错 ._ ### API 概览 #### 静态方法 - `getOverlays()`: 返回页面上所有覆盖的数组 - `init([el])`: 为所有人重叠 `o-overlay-trigger` 内部要素 `el` (或 `document.body` 如果未指明) - `destroy()`:从触发元素中销毁所有重叠对象并解封事件处理器. #### 对象方法 - `open`: 显示覆盖。 内容每次打开封面都会被加载. - `close`:收(收)上盖. - `realign`:调整上线. 当覆盖内容在打开时更改时有用 . ## 活动 - `oOverlay.layerOpen`:在覆盖物出现之前即已发出,并表明其他覆盖物应当关闭 `layer` 选项设置为对. - `oOverlay.layerClose`: 是在取消覆盖之后, 当 `layer` 选项设置为对. - `oOverlay.ready`:当覆盖被装入DOM时即发出. 准备就绪的活动包括: `detail.instance` 属性 `o-overlay` 举个例子. - `oOverlay.destroy`: 重叠从DOM中移除时发送. ## 解决问题 - IE8在关闭从第二次开始的重叠时会抛出一个错误. 尽管出了差错,它还是像预期的那样起作用. - Safari和Chrome移动 [别支持](http://caniuse.com/#feat=autofocus) 自动聚焦属性。 在Chrome手机中,您可以使用 `.focus()` 函数,当 `oOverlay.ready` 用于模拟行为. - 在iOS8上的Safari手机中,自动焦点是 [错误](http://stackoverflow.com/questions/26146252/in-ios8-using-focus-will-show-virtual-keyboard-and-scroll-page-after-touch) 然后在覆盖加载后被触发 _达阵_ 在此之后发送事件。 这意味着如果在页面加载后点击页面上的任何地方,键盘就会出现,这很可能会产生出乎意料的行为. 我们建议不要在iOS 8中使用自动焦点. 这些出人意料的行为 只有在第一次完成覆盖之后 自动焦点才会被激活. ## 移徙指南 | 状态 | 主要版本 | 最后一个小版本 | 移徙指南 | | :-: | :-: | :-: | :-: | | 维护 | 页:1 | 不详 | [迁移到 v5](https://npmcn.com/package/%40financial-times/o-overlay/MIGRATION.md#migrating-from-v4-to-v5) | | 已贬值 | 页:1 | 4.2 (中文(简体) ) | [迁移到 v4](https://npmcn.com/package/%40financial-times/o-overlay/MIGRATION.md#migrating-from-v3-to-v4) | | 已贬值 | 3个 | 3.1 国家 | [迁移到 v3](https://npmcn.com/package/%40financial-times/o-overlay/MIGRATION.md#migrating-from-v2-to-v3) | | 已贬值 | 2个 | 2.7 联合国 | [迁移到 v2](https://npmcn.com/package/%40financial-times/o-overlay/MIGRATION.md#migrating-from-v1-to-v2) | | 已贬值 | 1个 | 1.17 联合国 | \- 说吧 | ## 联系人 如果您对本部分有任何问题或评论,或需要帮助使用本部分,请 [提出问题](https://github.com/Financial-Times/o-overlay/issues)访问 [#origami - 支持](https://financialtimes.slack.com/messages/origami-support/) 或电子邮件 [折纸支持](mailto:origami-support@ft.com)。 。 。 . * * * ## 许可证 本软件由金融时报根据以下规定出版: [麻省理工学院许可证](http://opensource.org/licenses/MIT)。 。 。 . ## 常见问题 ### @financial-times/o-overlay 是什么？ 可配置的自定义覆盖框,用于显示覆盖窗口。 封面也可以切换到小屏幕上以不同方式显示 ### 如何安装 @financial-times/o-overlay？ 在项目目录运行 npm install @financial-times/o-overlay，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@financial-times/o-brand（^4\.1\.0）、@financial-times/o-viewport（^5\.1\.2）、@financial-times/o-private-foundation（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @financial-times/o-overlay 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/financial-times\_\_o-overlay 是否存在。 ### @financial-times/o-overlay 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @financial-times/o-overlay 可以商用吗？ @financial-times/o-overlay 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @financial-times/o-overlay 的下载量有多少？ 根据 npm 官方下载统计，@financial-times/o-overlay 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,943 次，日均约 131 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @financial-times/o-overlay 还在维护吗？ 最新版本 5\.0\.3 发布于 2025/12/05（11 个月前）；至今共发布 55 个版本，其中过去 12 个月发布了 1 个；首次发布于 2019/02/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。