# ARIA

本章节内容主要包括如何快速运用 UIExtension 框架内置功能实现可访问性，以及相关的工具介绍。如果你想详细了解 ARIA 的技术规范以及最佳实践，可查阅这些地址：

# UIExtension 如何启用可访问性

初始化 PDFUI 时，我们需要加载 aria 附加组件:

new UIExtension.PDFUI({
    addons: [
        // .... 其它 Add-on
        'path/to/lib/uix-addons/aria/addon.info.json' // 必须确保 aria 在最后加载
    ]
    // ... another options
})

如果你的应用是通过 allInOne.js 加载插件 , 因为它已经包含 aria, 所以不需要额外单独加载：

new UIExtension.PDFUI({
    addons: 'path/to/lib/uix-addons/allInOne.js'
    // ... another options
})

更多关于如何加载 add-on 的信息可以参考这里

# UIExtension 内建组件

# `aria-label` 属性

这些内建组件指定 text 或 label 参数后会自动向生成的DOM节点上添加 aria-label 属性，可点击 run 按钮运行示例，然后使用屏幕阅读器查看效果：

<html>
    <template id="layout-template">
        <webpdf>
            <div>
                <div>
                    <gtab text="XButton" group="aria-tab" body="tab1-body" active></gtab>
                    <gtab text="Dropdown" group="aria-tab" body="tab2-body"></gtab>
                    <gtab text="Slider" group="aria-tab" body="tab3-body"></gtab>
                    <gtab text="Ribbon button" group="aria-tab" body="tab4-body"></gtab>
                </div>
                <div name="tab1-body">
                    <xbutton text="button"></xbutton>
                </div>
                <div name="tab2-body">
                    <dropdown text="Dropdown" style="width: 8em" separate="false">
                        <xbutton text="Dropdown item 1"></xbutton>
                        <xbutton text="Dropdown item 2"></xbutton>
                    </dropdown>
                </div>
                <div name="tab3-body">
                    <slider min="0" max="100" step="1" label="Slider label"></slider>
                </div>
                <div name="tab4-body">
                    <ribbon-button text="Ribbon button"></ribbon-button>
                </div>
            </div>
            <div class="fv__ui-body">
                <viewer></viewer>
            </div>
        </webpdf>
    </template>
</html>
<script>
    var CustomAppearance = UIExtension.appearances.Appearance.extend({
        getLayoutTemplate: function() {
            return document.getElementById('layout-template');
        },
        disableAll: function(){}
    });
    var libPath = window.top.location.origin + '/lib';
    var pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: CustomAppearance,
        addons: libPath + '/uix-addons/allInOne.js'
    });
</script>

{
    "iframeOptions": {
        "style": "height: 300px"
    }
}

# 视觉隐藏的内容

在有些场景下需要提供一些可供屏幕阅读器等辅助技术访问但视觉上隐藏的内容，我们可以添加.fv__ui-aria-sr-only类进行样式设置。这么做可以为视觉障碍用户提供有用的信息或提示，比如有时候我们用不同颜色表示危险、警告等不同类型的信息，这时候就需要添加额外文本内容告知视觉障碍用户这条信息的类型。

<p class="text-danger">
    <span class="fv__ui-aria-sr-only">Danger:</span>
    This action is not reversible.
</p>

# aria 指令

# `@aria:attr` 指令

这个指令用于设置 aria- 开头的属性，指令写法是 @aria:attr.${aria-property-name}, aria-property-name 可以参考这里 (opens new window), 其参数值是一个可执行的表达式：

# `@aria:label` 指令

这个指令用于设置 aria-label (opens new window) 属性，指令值为i18n词条。

<html>
    <template id="layout-template">
        <webpdf>
            <div>
                <group-list>
                    <group>
                        <input @aria:label="aria:labels.gotopage" placeholder="@aria:label=&quot;aria:labels.gotopage&quot;">
                        <!--Result:
                            <input aria-label="Set page" ...>
                        -->

                        <!-- It is equivalent to: -->
                        <input @aria:attr.label="'aria:labels.gotopage'|i18n" placeholder="@aria:attr.label=&quot;'aria:labels.gotopage'|i18n&quot;">
                        <!--Result:
                            <input aria-label="Set page" ...>
                        -->

                        <!-- source text -->
                        <input @aria:label="source text" placeholder="@aria:label=&quot;source text&quot;">
                        <!--Result:
                            <input aria-label="source text" ...>
                        -->
                        <!-- It is equivalent to: -->
                        <input @aria:attr.label="'source text'" placeholder="@aria:attr.label=&quot;'source text'&quot;">
                        <!--Result:
                            <input aria-label="source text" ...>
                        -->
                    </group>
                </group-list>
                <group-list>
                    <group>
                        <!-- 它可以在 dropdown 组件上指定的位置设置属性。 -->
                        <!-- 下拉箭头上设置 aria-label -->
                        <dropdown @aria:label.caret="Toggle Dropdown" text="@aria:label.caret"></dropdown>
                    </group>
                    <group>
                        <!-- 图标上设置 aria-label -->
                        <dropdown icon-class="fv__icon-toolbar-hand" @aria:label.icon="Click dropdown icon" text="@aria:label.icon"></dropdown>
                    </group>
                    <group>
                        <!-- 输入框上设置 aria-label -->
                        <dropdown
                            editable
                            @aria:label.editor="Click dropdown icon"
                            selected="1"
                            text="@aria:label.editor"
                        >
                            <dropdown-item>Item 2</dropdown-item>
                            <dropdown-item>Item 3</dropdown-item>
                            <dropdown-item>Item 1</dropdown-item>
                        </dropdown>
                    </group>
                    <group>
                        <!-- 设置列表的 aria-label -->
                        <dropdown @aria:label.list="Items" text="@aria:label.list" separate="false">
                            <dropdown-item>Item 1</dropdown-item>
                            <dropdown-item>Item 2</dropdown-item>
                            <dropdown-item>Item 3</dropdown-item>
                        </dropdown>
                    </group>
                </group-list>
            </div>
            <div class="fv__ui-body">
                <viewer></viewer>
            </div>
        </webpdf>
    </template>
</html>
<script>
    var CustomAppearance = UIExtension.appearances.Appearance.extend({
        getLayoutTemplate: function() {
            return document.getElementById('layout-template');
        },
        disableAll: function(){}
    });
    var libPath = window.top.location.origin + '/lib';
    var pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: CustomAppearance,
        addons: libPath + '/uix-addons/allInOne.js'
    });
</script>
<style>
    input {
        width: 20em;
    }
    .fv__ui-dropdown {
        width: auto;
    }
</style>

{
    "iframeOptions": {
        "style": "height: 300px"
    }
}

# `@aria:labelledby` 指令

@aria:labelledby 指令用于生成 aria-labelledby 属性，指令值用 UIExtension 的选择器语法，而不是元素的id。这是因为 aria-labelledby 属性需要通过id关联到另外一个元素, 由于id可能引起发的全局冲突问题，我们不建议手写id来索引元素，这个指令的选择器语法就可以避免这一问题。

关于更多 aria-labelledby 属性的信息，可以参考这里 (opens new window)

上述示例中，@aria:labelledby="::parent()::childAt(0),,a-colon" 指定了 <input> 前面两个 span 组件的id为标签。关于的选择器语法可以参考这里。

# `@aria:describedby` 指令

@aria:describedby 指令用法和原理和 @aria:labelledby 基本相同，这里不做过多赘述。

关于 aria-describedby 更多信息，可以参考这里 (opens new window)

# `@aria:rel` 指令

ARIA 规范中，除了 aria-labelledby 和 aria-describedby 以外还有很多需要关联其它元素的属性。@aria:rel 指令封装了这些常用的属性:

aria-activedescendant (opens new window)，指令写法：aria:rel.activedescendant="selecor,..."
aria-flowto (opens new window)，指令写法：aria:rel.flowto="selecor,..."
aria-owns (opens new window), 指令写法：aria:rel.owns="selecor,..."
aria-controls (opens new window)，指令写法：aria:rel.controls="selecor,..."

# `@aria:circular-focus` 指令

这个指令用来控制组件内元素焦点，实现循环跳转功能。通常用于弹窗, 或者一个独立的UI区域。

可参照下面的示例，点击 run 按钮运行。

# ARIA

# UIExtension 如何启用可访问性

# UIExtension 内建组件

# aria-label 属性

# 视觉隐藏的内容

# aria 指令

# @aria:attr 指令

# @aria:label 指令

# @aria:labelledby 指令

# @aria:describedby 指令

# @aria:rel 指令