[{"data":1,"prerenderedAt":170},["ShallowReactive",2],{"guide:how-to-implement-accessible-names":3},{"slug":4,"title":5,"description":8,"keywords":11,"updatedAt":14,"summary":15,"sections":24,"relatedPages":128},"how-to-implement-accessible-names",{"zh-Hant-TW":6,"en":7},"如何正確設定可及名稱？讓按鈕、連結與表單欄位被理解","How to Implement Accessible Names in HTML",{"zh-Hant-TW":9,"en":10},"可及名稱讓螢幕讀取器等輔助科技知道按鈕、連結與表單欄位的用途。這份指南說明如何優先使用原生 HTML 與可見文字，再視情況補上 aria-label 或 aria-labelledby。","Accessible names help assistive technologies identify the purpose of buttons, links, and form fields. This guide explains how to use native HTML and visible text first, then add aria-label or aria-labelledby when needed.",{"zh-Hant-TW":12,"en":13},"可及名稱, accessible name, aria-label, aria-labelledby, accessibility tree, 表單 label, 螢幕讀取器按鈕名稱","accessible name, aria-label, aria-labelledby, accessible name computation, accessibility tree, accessible name vs description, how to set accessible name in HTML","2026-07-02",{"zh-Hant-TW":16,"en":20},[17,18,19],"可及名稱回答「這個控制項叫什麼」或「它要做什麼」。","多數情況下，最穩定的做法是使用可見文字、label、alt 與語意 HTML。","aria-label 與 aria-labelledby 是補充工具，不應拿來掩蓋不清楚的畫面文字或錯誤結構。",[21,22,23],"An accessible name answers what a control is called or what it does.","In most cases, visible text, labels, alt text, and semantic HTML are the most stable source.","aria-label and aria-labelledby are supporting tools, not a way to hide unclear visible text or broken structure.",[25,36,60,71,95,117],{"title":26,"body":29},{"zh-Hant-TW":27,"en":28},"可及名稱解決的是理解問題","Accessible names solve a naming problem",{"zh-Hant-TW":30,"en":33},[31,32],"可及名稱是瀏覽器提供給輔助科技的名稱。當使用者遇到一個按鈕、連結、表單欄位或自訂控制項時，螢幕讀取器通常會把它的角色與名稱一起讀出來，例如「搜尋，按鈕」或「電子郵件，文字欄位」。","它不是額外的行銷文字，也不是把畫面上的所有內容重複一次。它的任務很單純：讓使用者知道目前這個元件是什麼、能做什麼、是否值得操作。",[34,35],"An accessible name is the name a browser exposes to assistive technologies. When someone reaches a button, link, form field, or custom control, a screen reader commonly announces both the role and the name, such as “Search, button” or “Email, text field.”","It is not marketing copy, and it should not repeat everything visible on the page. Its job is simple: help the user understand what the control is, what it does, and whether it is worth acting on.",{"title":37,"body":40,"items":47},{"zh-Hant-TW":38,"en":39},"先使用原生 HTML 與可見文字","Start with native HTML and visible text",{"zh-Hant-TW":41,"en":44},[42,43],"最穩定的可及名稱通常不是 ARIA 寫出來的，而是來自原生 HTML。可見的按鈕文字、清楚的連結文字、表單的 label、資訊圖片的 alt，都比隱藏在屬性裡的補救文字更容易被團隊理解與維護。","如果畫面文字本身清楚，輔助科技、語音控制、翻譯工具與一般使用者通常都能得到比較一致的資訊。",[45,46],"The most stable accessible names usually come from native HTML, not ARIA. Visible button text, clear link text, form labels, and alt text for meaningful images are easier for teams to understand and maintain than hidden fallback text in attributes.","When visible text is clear, assistive technologies, voice control tools, translation tools, and sighted users are more likely to receive consistent information.",{"zh-Hant-TW":48,"en":54},[49,50,51,52,53],"按鈕：優先讓按鈕內有清楚文字，例如「儲存草稿」比只有圖示更容易理解。","連結：避免只寫「更多」或「點這裡」，改成能說明目的地的文字。","表單欄位：使用 label 關聯欄位；placeholder 不能取代標籤。","圖片：有意義的圖片用 alt 傳達必要資訊；裝飾圖片則避免製造多餘朗讀。","群組：一組相關欄位可用 fieldset 與 legend 補上群組脈絡。",[55,56,57,58,59],"Buttons: prefer clear button text, such as “Save draft,” instead of an icon alone.","Links: avoid “more” or “click here” when the link text can describe the destination.","Form fields: associate fields with labels; placeholder text is not a replacement for a label.","Images: use alt text for meaningful images and avoid announcing purely decorative images.","Groups: use fieldset and legend when a group of fields needs shared context.",{"title":61,"body":64},{"zh-Hant-TW":62,"en":63},"什麼時候才需要 ARIA？","When ARIA is useful",{"zh-Hant-TW":65,"en":68},[66,67],"ARIA 適合補足原生 HTML 不容易表達的情況，但它不是第一選擇。如果畫面上已經有可見文字，通常優先用 aria-labelledby 指向那段文字；只有在沒有可見文字可用時，才考慮 aria-label。","常見情境包括只有圖示的按鈕、需要把標題當成複雜元件名稱、或同一頁有多個外觀相近但目的不同的控制項。",[69,70],"ARIA is useful when native HTML cannot express the needed relationship, but it should not be the first choice. If visible text already exists, aria-labelledby usually keeps the accessible name connected to that text. Use aria-label mainly when no suitable visible text is available.","Common cases include icon-only buttons, complex widgets named by a nearby heading, or repeated controls that look similar but perform different actions.",{"title":72,"body":75,"items":80},{"zh-Hant-TW":73,"en":74},"常見錯誤","Common mistakes",{"zh-Hant-TW":76,"en":78},[77],"可及名稱的問題常常不是「完全沒有」，而是名稱和實際用途不一致。自動化工具可以找出一部分缺漏，但最後仍需要人確認名稱是否真的符合使用情境。",[79],"Accessible name issues are not always about missing names. Often the name exists, but it does not match the real purpose. Automated tools can find some gaps, but people still need to confirm whether the name makes sense in context.",{"zh-Hant-TW":81,"en":88},[82,83,84,85,86,87],"只有圖示的按鈕沒有名稱，使用者只聽到「按鈕」。","同一頁多個連結都叫「更多」，但目的地不同。","用 placeholder 當作表單標籤，輸入後提示就消失。","aria-label 和畫面文字不一致，讓不同使用者得到不同資訊。","把補充說明放在 aria-describedby，卻誤以為它會變成控制項名稱。","狀態改變後名稱沒有更新，例如展開、收合、加入、移除。",[89,90,91,92,93,94],"An icon-only button has no name, so users only hear “button.”","Several links on the same page are all named “More” even though they go to different places.","Placeholder text is used as the only form label, then disappears after input.","aria-label conflicts with visible text, giving different users different information.","Supporting text is placed in aria-describedby and mistaken for the control name.","The name does not update when state changes, such as expand, collapse, add, or remove.",{"title":96,"body":99,"items":106},{"zh-Hant-TW":97,"en":98},"怎麼檢查可及名稱","How to test accessible names",{"zh-Hant-TW":100,"en":103},[101,102],"瀏覽器開發者工具通常可以檢查無障礙資訊樹，查看目前元素的角色、名稱與描述。這是理解輔助科技實際取得什麼資訊的好起點。","DevCheck 可以協助找出缺少可及名稱、ARIA 使用錯誤與部分表單標籤問題。不過，機器掃描只能指出可疑位置；名稱是否符合任務、是否夠清楚，仍然需要人工判斷。",[104,105],"Browser developer tools usually let you inspect the accessibility tree and review the current element’s role, name, and description. This is a useful starting point for understanding what assistive technologies receive.","DevCheck can help surface missing accessible names, ARIA mistakes, and some form-label issues. Still, machine checks only point to suspicious places; people need to decide whether the name fits the task and is clear enough.",{"zh-Hant-TW":107,"en":112},[108,109,110,111],"用鍵盤移動到控制項，確認焦點順序與畫面位置合理。","在開發者工具檢查無障礙資訊樹中的 name、role、description。","用自動化工具找缺少名稱、空白名稱或 ARIA 關係錯誤。","抽查螢幕讀取器或語音控制工具，確認名稱在實際操作時能被理解。",[113,114,115,116],"Move through controls with the keyboard and confirm the focus order matches the page.","Inspect name, role, and description in the accessibility tree.","Use automated checks to find missing names, empty names, and ARIA relationship errors.","Spot-check with a screen reader or voice control tool to confirm the name works in real use.",{"title":118,"body":121},{"zh-Hant-TW":119,"en":120},"把它放進團隊流程","Make it part of the workflow",{"zh-Hant-TW":122,"en":125},[123,124],"可及名稱不只屬於工程師。設計師可以在圖示按鈕旁標示用途，內容維護者可以寫清楚連結文字，QA 可以在主要流程中確認焦點與名稱，產品負責人也可以要求重要操作不要只靠圖示或視覺位置理解。","這類檢查不需要等到正式檢測才開始。越早把名稱說清楚，後面要補救的成本通常越低，也越容易讓團隊討論同一個具體問題。",[126,127],"Accessible names are not only an engineering task. Designers can document icon-button purpose, content teams can write clearer link text, QA can check focus and names in core flows, and product owners can avoid relying only on icons or visual placement for important actions.","This review does not need to wait for a formal audit. The earlier a name is made clear, the lower the repair cost tends to be, and the easier it is for the team to discuss one concrete issue.",[129,136,141,146,151,156,161,166],{"label":130,"path":132,"description":133},{"zh-Hant-TW":131,"en":131},"Accesserty DevCheck","\u002Fdevcheck",{"zh-Hant-TW":134,"en":135},"用瀏覽器內工具檢查本機、測試站、登入後頁面與互動狀態。","Run browser-based checks on local builds, staging pages, authenticated screens, and interactive states.",{"label":137,"path":140},{"zh-Hant-TW":138,"en":139},"可及名稱術語頁","Accessible name glossary page","\u002Fglossary\u002Faccessible-name",{"label":142,"path":145},{"zh-Hant-TW":143,"en":144},"語意 HTML 術語頁","Semantic HTML glossary page","\u002Fglossary\u002Fsemantic-html",{"label":147,"path":150},{"zh-Hant-TW":148,"en":149},"ARIA 術語頁","ARIA glossary page","\u002Fglossary\u002Faria",{"label":152,"path":155},{"zh-Hant-TW":153,"en":154},"ARIA Patterns 指南","ARIA patterns guide","\u002Fguides\u002Faria-patterns-for-developers",{"label":157,"path":160},{"zh-Hant-TW":158,"en":159},"自動化檢測限制指南","Automated accessibility checks limits guide","\u002Fguides\u002Fautomated-accessibility-checks-limits",{"label":162,"path":165},{"zh-Hant-TW":163,"en":164},"圖片替代文字指南","Image alt text guide","\u002Fguides\u002Fwriting-meaningful-alt-text",{"label":167,"path":169},{"zh-Hant-TW":168,"en":168},"W3C Accessible Name and Description Computation","https:\u002F\u002Fwww.w3.org\u002FTR\u002Faccname-1.2\u002F",1789828081498]