@accede-web/tablist 中文文档教程
AcceDe Web - tablist
没有依赖项的 WAI-ARIA 选项卡插件。
Requirements
HTML
具有 tablist
、tab
和 tabpanel
角色的基本 HTML 结构。
HTML structure
<ul role="tablist">
<li role="tab" aria-controls="tab-1">Tab 1</li>
<li role="tab" aria-controls="tab-2">Tab 2</li>
<li role="tab" aria-disabled="true" aria-controls="tab-3">Tab 3</li>
<li role="tab" aria-controls="tab-4">Tab 4</li>
</ul>
<div role="tabpanel" id="tab-1">
<p>---</p>
</div>
<div role="tabpanel" id="tab-2">
<p>---</p>
</div>
<div role="tabpanel" id="tab-3">
<p>---</p>
</div>
<div role="tabpanel" id="tab-4">
<p>---</p>
</div>
在 tab
上将 aria-disabled
属性设置为 true
将禁用 tab
和关联的 tabpanel
使它们无法聚焦且无法选择。
如果您希望在脚本启动时打开一个特定的选项卡,只需在所需的 选项卡
上添加值为 true
的 data-open
属性:
<ul role="tablist">
<li role="tab" aria-controls="tab-1">Tab 1</li>
<li role="tab" aria-controls="tab-2" data-open="true">Tab 2</li>
<li role="tab" aria-controls="tab-3">Tab 3</li>
<li role="tab" aria-controls="tab-4">Tab 4</li>
</ul>
<!-- -->
CSS
至少一个 CSS 选择器,用于在未选择时隐藏面板:
[role=tabpanel][aria-hidden=true] {
display: none;
}
选择器可以是任何你想要的,比如类,因为脚本允许在打开或关闭时回调面板; 您可以使用回调添加自己的类。
JavaScript
脚本本身,来自 npm:
$ npm install @accede-web/tablist
和稍后在您的代码中:
var Tablist = require( '@accede-web/tablist' );
// or
import Tablist from @accede-web/tablist
或从 Github 下载并添加到页面(dist
文件夹中提供缩小和非缩小版本)
<script src="./js/tablist.min.js"></script>
使用后者,脚本将是在命名空间 Tablist
下的 window
上可用。
现在启动脚本:
// get the tablist element
var list = document.querySelector( '[role="tablist"]' );
// create the tablist instance
var tablist = new window.Tablist( list );
// optionnaly add callbacks to on show and hide a tab
tablist.on( 'show', function( tab, tabPanel ){
…
});
tablist.on( 'hide', function( tab, tabPanel ){
…
});
// start the plugin
tablist.mount();
Parameters
脚本采用一个参数:
- the
tablist
DOM element
由于脚本只采用一个 tablist
元素作为参数,因此您必须遍历每个 tablist
以启动脚本他们每个人。
var lists = document.querySelectorAll( '[role="tablist"]' );
Array.prototype.forEach.call( lists, function( list ) {
new window.Tablist( list ).mount();
});
Methods
Tablist
构造函数返回 4 个方法:
mount()
- bind all events and apply required attributesunmount()
- unbind keyboard and mouse eventson( event, callback )
- bind a callback to either theshow
orhide
event triggered when changing tab. Bothtab
andtabPanel
HTMLElement are passed on the callbackoff( event, callback )
- unbind a callback to either theshow
orhide
event triggered when changing tab
Properties
要知道哪个 tab
和 tabPanel
是打开的,请使用 tablist.current
。 它将返回一个包含 tab
和 tabPanel
的数组
// ES6 destructuring array
const { tab, tabPanel } = tablist.current;
tab; // return the `tab`
tabPanel; // return the `tabPanel`
// ES5
var elements = tablist.current;
elements.tab; // return the `tab`
elements.tabPanel; // return the `tabPanel`
Keyboard Interaction
。键盘交互基于 Atalan 的 AcceDe Web 指南(法语) 和 WAI-AIRA 1.0 创作实践
Tab
- only the active tab is in the tab order. The user reaches the tabbed panel component by pressing the tab key until the active tab title receives focus.Left Arrow
- with focus on a tab, pressing the left arrow will move focus to the previous tab in the tab list and activate that tab. Pressing the left arrow when the focus is on the first tab in the tab list will move focus and activate the last tab in the list.Right Arrow
- with focus on a tab, pressing the right arrow will move focus to the next tab in the tab list and activate that tab. Pressing the right arrow when the focus is on the last tab in the tab list will move focus to and activate the first tab in the list.Up arrow
- behaves the same as left arrow in order to support vertical tabs.Down arrow
- behaves the same as right arrow in order to support vertical tabs.Home
- with focus on a tab, pressing the Home key will move the focus to the first tabEnd
- with focus on a tab, pressing the End key will move the focus to the last tabControl+Up Arrow
- with focus anywhere within the tab panel, pressing Control+Up Arrow will move focus to the tab for that panel. This is not standard behavior.Control+PageUp
- When focus is inside of a tab panel, pressing Control+PageUp moves focus to the tab of the previous tab in the tab list and activates that tab. When focus is in the first tab panel in the tab list, pressing Control+PageUp will move focus to the last tab in the tab list and activate that tab.Control+PageDown
When focus is inside of a tab panel, pressing Control+PageDown moves focus to the tab of the next tab in the tab list and activates that tab. When focus is in the last tab panel in the tab list, pressing Control+PageUpwill move focus to the first tab in the tab list and activate that tab.
Compatibilty
此插件针对以下浏览器进行了测试:
- Internet Explorer 9 and higher
- Microsoft Edge
- Chrome
- Firefox
- Safari
Testing
安装项目依赖项:
$ npm install
运行自动化测试用例:
$ npm test
AcceDe Web - tablist
WAI-ARIA tab plugin without dependencies.
Requirements
HTML
Basic HTML structure with roles tablist
, tab
, and tabpanel
.
HTML structure
<ul role="tablist">
<li role="tab" aria-controls="tab-1">Tab 1</li>
<li role="tab" aria-controls="tab-2">Tab 2</li>
<li role="tab" aria-disabled="true" aria-controls="tab-3">Tab 3</li>
<li role="tab" aria-controls="tab-4">Tab 4</li>
</ul>
<div role="tabpanel" id="tab-1">
<p>---</p>
</div>
<div role="tabpanel" id="tab-2">
<p>---</p>
</div>
<div role="tabpanel" id="tab-3">
<p>---</p>
</div>
<div role="tabpanel" id="tab-4">
<p>---</p>
</div>
An aria-disabled
attribute set to true
on a tab
will disable the tab
and the associated tabpanel
making them unfocusable and unselectable.
If you wish to open one specific tab when the script starts, just add the data-open
attribute with the value of true
on the desired tab
:
<ul role="tablist">
<li role="tab" aria-controls="tab-1">Tab 1</li>
<li role="tab" aria-controls="tab-2" data-open="true">Tab 2</li>
<li role="tab" aria-controls="tab-3">Tab 3</li>
<li role="tab" aria-controls="tab-4">Tab 4</li>
</ul>
<!-- -->
CSS
At least a CSS selector for panels to be hidden when not selected:
[role=tabpanel][aria-hidden=true] {
display: none;
}
The selector can be anything you want, like a class, as the script allows callback when opening or closing a panel; you can add your own class using the callbacks.
JavaScript
The script itself, either from npm:
$ npm install @accede-web/tablist
and later in your code:
var Tablist = require( '@accede-web/tablist' );
// or
import Tablist from @accede-web/tablist
or downloaded from Github and added to the page (minified and non minified versions available in the dist
folder)
<script src="./js/tablist.min.js"></script>
Using the later, the script will be available on window
under the namespace Tablist
.
Now to kick off the script:
// get the tablist element
var list = document.querySelector( '[role="tablist"]' );
// create the tablist instance
var tablist = new window.Tablist( list );
// optionnaly add callbacks to on show and hide a tab
tablist.on( 'show', function( tab, tabPanel ){
…
});
tablist.on( 'hide', function( tab, tabPanel ){
…
});
// start the plugin
tablist.mount();
Parameters
The script takes one parameter:
- the
tablist
DOM element
As the script takes only one tablist
element as parameter you have to loop over each tablist
to kick off the script on each of them.
var lists = document.querySelectorAll( '[role="tablist"]' );
Array.prototype.forEach.call( lists, function( list ) {
new window.Tablist( list ).mount();
});
Methods
The Tablist
constructor returns 4 methods:
mount()
- bind all events and apply required attributesunmount()
- unbind keyboard and mouse eventson( event, callback )
- bind a callback to either theshow
orhide
event triggered when changing tab. Bothtab
andtabPanel
HTMLElement are passed on the callbackoff( event, callback )
- unbind a callback to either theshow
orhide
event triggered when changing tab
Properties
To know which tab
and tabPanel
is open use tablist.current
. It will return an array containing tab
and tabPanel
// ES6 destructuring array
const { tab, tabPanel } = tablist.current;
tab; // return the `tab`
tabPanel; // return the `tabPanel`
// ES5
var elements = tablist.current;
elements.tab; // return the `tab`
elements.tabPanel; // return the `tabPanel`
Keyboard Interaction
The keyboard interactions are based on Atalan's AcceDe Web guidelines (in French) and the WAI-AIRA 1.0 Authoring Practices
Tab
- only the active tab is in the tab order. The user reaches the tabbed panel component by pressing the tab key until the active tab title receives focus.Left Arrow
- with focus on a tab, pressing the left arrow will move focus to the previous tab in the tab list and activate that tab. Pressing the left arrow when the focus is on the first tab in the tab list will move focus and activate the last tab in the list.Right Arrow
- with focus on a tab, pressing the right arrow will move focus to the next tab in the tab list and activate that tab. Pressing the right arrow when the focus is on the last tab in the tab list will move focus to and activate the first tab in the list.Up arrow
- behaves the same as left arrow in order to support vertical tabs.Down arrow
- behaves the same as right arrow in order to support vertical tabs.Home
- with focus on a tab, pressing the Home key will move the focus to the first tabEnd
- with focus on a tab, pressing the End key will move the focus to the last tabControl+Up Arrow
- with focus anywhere within the tab panel, pressing Control+Up Arrow will move focus to the tab for that panel. This is not standard behavior.Control+PageUp
- When focus is inside of a tab panel, pressing Control+PageUp moves focus to the tab of the previous tab in the tab list and activates that tab. When focus is in the first tab panel in the tab list, pressing Control+PageUp will move focus to the last tab in the tab list and activate that tab.Control+PageDown
When focus is inside of a tab panel, pressing Control+PageDown moves focus to the tab of the next tab in the tab list and activates that tab. When focus is in the last tab panel in the tab list, pressing Control+PageUpwill move focus to the first tab in the tab list and activate that tab.
Compatibilty
This plugin is tested against the following browsers:
- Internet Explorer 9 and higher
- Microsoft Edge
- Chrome
- Firefox
- Safari
Testing
Install the project dependencies:
$ npm install
Run the automated test cases:
$ npm test