文档：ariaNotify() 方法

可用性有限

此特性不是基线特性，因为它在一些最广泛使用的浏览器中不起作用。

实验性： 这是一项实验性技术
在生产中使用此技术之前，请仔细检查浏览器兼容性表格。

非标准：此特性未标准化。我们不建议在生产环境中使用非标准特性，因为它们浏览器支持有限，并且可能会更改或被移除。但是，在没有标准选项的特定情况下，它们可以是合适的替代方案。

Document 接口的 ariaNotify() 方法指定一段给定的文本字符串应由屏幕阅读器朗读（如果屏幕阅读器可用且已激活）。

语法

ariaNotify(announcement)
ariaNotify(announcement, options)

参数

通知

指定要朗读的文本字符串。

options 可选

一个包含以下属性的选项对象

优先级

一个枚举值，指定通知的优先级。可能的值为

normal: 该通知具有正常优先级。它将在屏幕阅读器当前进行的任何通知之后朗读。
high: 该通知具有高优先级。它将立即朗读，中断屏幕阅读器当前进行的任何通知。

描述

ariaNotify() 方法可用于以编程方式触发屏幕阅读器通知。此方法提供与ARIA 实时区域类似的功能，并具有一些优势：

实时区域只能在 DOM 更改后进行通知，而 ariaNotify() 通知可以随时进行。
实时区域通知涉及朗读已更改的 DOM 节点的更新内容，而 ariaNotify() 通知内容可以独立于 DOM 内容定义。

开发人员通常通过使用设置了实时区域的隐藏 DOM 节点来规避实时区域的限制，这些节点的内容会随着要通知的内容而更新。这效率低下且容易出错，而 ariaNotify() 提供了一种避免此类问题的方法。

一些屏幕阅读器会按顺序朗读多个 ariaNotify() 通知，但这不能在所有屏幕阅读器和平台上得到保证。通常，只朗读最新的通知。将多个通知合并为一个更可靠。

例如，以下调用

document.ariaNotify("Hello there.");
document.ariaNotify("The time is now 8 o'clock.");

最好合并

document.ariaNotify("Hello there. The time is now 8 o'clock.");

ariaNotify() 通知不需要瞬时激活；您应该注意不要用过多的通知来骚扰屏幕阅读器用户，因为这可能会造成糟糕的用户体验。

通知优先级

设置了 priority: high 的 ariaNotify() 通知会在设置了 priority: normal 的 ariaNotify() 通知之前朗读。

ariaNotify() 通知大致相当于 ARIA 实时区域通知，如下所示：

ariaNotify() priority: high：aria-live="assertive"。
ariaNotify() priority: normal：aria-live="polite"。

但是，aria-live 通知将优先于 ariaNotify() 通知。

语言选择

屏幕阅读器根据 <html> 元素的 lang 属性中指定的语言，或如果未设置 lang 属性，则根据用户代理的默认语言，选择合适的语音（在口音、发音等方面）来朗读 ariaNotify() 通知。

权限策略集成

文档或 <iframe> 中 ariaNotify() 的使用可以通过 aria-notify 权限策略进行控制。

具体来说，如果定义的策略阻止了使用，则任何使用 ariaNotify() 创建的公告都将静默失败（它们将不会被发送）。

示例

基本的 `ariaNotify()` 用法

此示例包含一个 <button>，单击时会触发屏幕阅读器通知。

html

<button>Press</button>

html,
body {
  height: 100%;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
}

document.querySelector("button").addEventListener("click", () => {
  document.ariaNotify("Hi there, I'm Ed Winchester.");
});

结果

输出如下：

尝试激活屏幕阅读器，然后按下按钮。您应该会听到屏幕阅读器朗读“你好，我是埃德·温彻斯特。”

无障碍购物清单示例

此示例是一个购物清单，您可以添加和删除商品，并跟踪所有商品的总成本。当添加或删除商品时，屏幕阅读器会朗读通知，告知添加/删除了什么商品，以及更新后的总价是多少。

HTML

我们的 HTML 包含一个 <form>，其中包含两个 <input> 元素——一个 text 输入用于输入商品名称，一个 number 输入用于输入价格。两个输入都是 required，并且 number 输入的 step 值为 0.01，以防止输入非价格值（如大小数）。

在表单下方，我们有一个无序列表用于渲染添加的商品，以及一个 <p> 元素用于显示总成本。

html

<h1><code>ariaNotify</code> demo: shopping list</h1>

<form>
  <div>
    <label for="item">Enter item name</label>
    <input type="text" name="item" id="item" required />
  </div>
  <div>
    <label for="price">Enter item price</label>
    <input type="number" name="price" id="price" step="0.01" required />
  </div>
  <div>
    <button>Submit</button>
  </div>
</form>

<hr />

<ul></ul>

<p>Total: £0.00</p>

html {
  box-sizing: border-box;
  font: 1.2em / 1.5 system-ui;
}

body {
  width: 600px;
  margin: 0 auto;
}

form {
  padding: 0 50px;
}

div {
  display: flex;
  margin-bottom: 20px;
}

label {
  flex: 2;
}

input {
  flex: 4;
  padding: 5px;
}

form button {
  padding: 5px 10px;
  font-size: 1em;
  border-radius: 10px;
  border: 1px solid gray;
}

li {
  margin-bottom: 10px;
}

li button {
  font-size: 0.6rem;
  margin-left: 10px;
}

JavaScript

我们的脚本从几个常量定义开始，用于存储对 <form>、我们的两个 <input> 元素以及我们的 <ul> 和 <p> 元素的引用。我们还包含一个 total 变量来存储所有商品的总价。

const form = document.querySelector("form");
const item = document.querySelector("input[type='text']");
const price = document.querySelector("input[type='number']");
const priceList = document.querySelector("ul");
const totalOutput = document.querySelector("p");

let total = 0;

在我们的下一个代码块中，我们定义了一个名为 updateTotal() 的函数，它只有一个作用——它更新 <p> 元素中显示的价格，使其等于 total 变量的当前值。

function updateTotal() {
  totalOutput.textContent = `Total: £${Number(total).toFixed(2)}`;
}

接下来，我们定义一个名为 addItemToList() 的函数。在函数体内部，我们首先创建一个 <li> 元素来存储新添加的商品。我们将商品名称和价格存储在元素上的 data-* 属性中，并将其文本内容设置为包含商品和价格的字符串。我们还创建一个 <button> 元素，文本为“Remove <item-name>”，然后将列表项附加到无序列表，并将按钮附加到列表项。

函数体的第二个主要部分是按钮上的 click 事件监听器定义。当按钮被点击时，我们首先获取按钮父节点（即它所在的列表项）的引用。然后，我们将列表项的 data-price 属性中包含的数字从 total 变量中减去，调用 updateTotal() 函数更新显示的总价，然后调用 ariaNotify() 宣布已删除的商品以及新的总价。最后，我们从 DOM 中删除列表项。

function addItemToList(item, price) {
  const listItem = document.createElement("li");
  listItem.setAttribute("data-item", item);
  listItem.setAttribute("data-price", price);
  listItem.textContent = `${item}: £${Number(price).toFixed(2)}`;
  const btn = document.createElement("button");
  btn.textContent = `Remove ${item}`;

  priceList.appendChild(listItem);
  listItem.appendChild(btn);

  btn.addEventListener("click", (e) => {
    const listItem = e.target.parentNode;
    total -= Number(listItem.getAttribute("data-price"));
    updateTotal();
    document.ariaNotify(
      `${listItem.getAttribute(
        "data-item",
      )} removed. Total is now £${total.toFixed(2)}.`,
      {
        priority: "high",
      },
    );
    listItem.remove();
  });
}

我们的最后一个代码块向 <form> 添加了一个 submit 事件监听器。在处理函数内部，我们首先在事件对象上调用 preventDefault() 以阻止表单提交。然后，我们调用 addItemToList() 在列表中显示新商品及其价格，将价格添加到 total 变量，调用 updateTotal() 更新显示的总价，然后调用 ariaNotify() 宣布已添加的商品以及新的总价。最后，我们清空当前输入字段值，以便添加下一个商品。

form.addEventListener("submit", (e) => {
  e.preventDefault();

  addItemToList(item.value, price.value);
  total += Number(price.value);
  updateTotal();

  document.ariaNotify(
    `Item ${item.value}, price £${
      price.value
    }, added to list. Total is now £${total.toFixed(2)}.`,
    {
      priority: "high",
    },
  );

  item.value = "";
  price.value = "";
});

结果

输出如下：

尝试激活屏幕阅读器，然后添加和删除一些项目。您应该会听到屏幕阅读器朗读它们。

帮助改进 MDN

了解如何贡献

本页面最后修改于 ⁨2025 年 10 月 1 日⁩，由 MDN 贡献者修改。

在 GitHub 上查看此页面 • 报告此内容的问题