README

此项目旨在创建一个可重用且可访问的主导航模块。有几个目标...

• 能够将此软件包作为独立项或在WordPress插件/主题中使用
• 允许快速实现可访问的菜单
• 菜单应允许开发人员进行定制，特别是关于样式
• 菜单功能应考虑到不同的用户输入模式（例如鼠标、键盘）

用法

通过NPM安装

此软件包可以通过npm使用npm install a11y-menu安装。这将提供对JS和sass文件的访问，但不包括WordPress菜单walker。目的是为javascript开发者提供以Webpack或其他打包器使用的方式访问JS菜单walker、导航脚本和样式的方法。

通过JS创建菜单

有两个函数和一个样式表可以一起使用来创建一个可访问的菜单。

• displayMenu
• 导航
• main.scss

displayMenu()接受一个json文件（见下面的/mock-data以获取格式）。它可以按如下方式导入和使用：

import { displayMenu } from 'a11y-menu';
// testData is an arbitrary json file.
import { menu } from './test-data.json';
const mainMenu = document.getElementById('main-menu');

displayMenu(mainMenu, menu); 

这可以与Navigation类结合使用，创建一个带有子菜单的工作菜单，子菜单在点击或悬停事件上显示。

// clickable menu
import Navigation, { displayMenu } from 'a11y-menu';
// testData is an arbitrary json file.
import { menu } from './test-data.json';
const mainMenu = document.getElementById('main-menu');

mainMenu.classList.add('am-click-menu');

displayMenu(mainMenu, menu);

const navigation = new Navigation({ click: true });

document.addEventListener('DOMContentLoaded', () => {
    navigation.init();
});

// hoverable menu
import Navigation, { displayMenu } from 'a11y-menu';
// testData is an arbitrary json file.
import { menu } from './test-data.json';

const mainMenu = document.getElementById('main-menu');

// if needed
mainMenu.classList.remove('am-click-menu');

displayMenu(mainMenu, menu);

const navigation = new Navigation();

document.addEventListener('DOMContentLoaded', () => {
    navigation.init();
});

main.scss可以使用Webpack或其他类似的工具进行引入。另一种选择是在项目中包含可找到于dist/main.css的转译css文件。

通过Composer安装。

此软件包可以作为依赖项通过Composer安装。要检查您是否已安装Composer，请在终端中运行composer命令。如果Composer不可用，请安装它。然后在您的项目中运行composer require ucomm/a11y-menu。

使用PHP创建菜单

对于非WordPress PHP项目，您可以使用aberkow/a11y-menu-php composer软件包。该软件包用于PHP项目中的javascript displayMenu函数。它可以通过composer require aberkow/a11y-menu-php安装，并公开一个单例静态方法，可以按如下方式使用：

<?php

require('vendor/autoload.php');
$data = file_get_contents('path/to/file.json');
$menu = json_decode($data)->menu;

?>
<nav id="am-navigation">
  <ul id="am-php-menu">
    <?php echo A11y\Menu_Generator::display_menu($menu); ?>
  </ul>
</nav>

在主题中创建WordPress菜单。

为了在您的主题中使用自定义Walker，您需要执行以下操作

// functions.php
require_once('vendor/autoload.php');

// register a menu location. 
// this is optional if you're using a child theme with pre-registered locations
function register_nav() {
  register_nav_menu('menu-name', __('Menu Name', 'text-domain'));
}
add_action('after_setup_theme', 'register_nav');


function load_scripts() {
  // enqueue the base nav styles
  wp_enqueue_style('a11y-menu', get_stylesheet_directory_uri() . '/vendor/ucomm/a11y-menu/dist/main.css');
  // register/enqueue the JS Navigation script
  wp_register_script('a11y-menu', get_stylesheet_directory_uri() . '/vendor/ucomm/a11y-menu/dist/Navigation.js', array(), false, true);

  wp_enqueue_script('a11y-menu');

  // the Navigation script is a dependency of the script where you wish to instantiate the class.
  wp_enqueue_script('theme-script', get_stylesheet_directory_uri() . '/index.js', array('a11y-menu', false, true));
}
add_action('wp_enqueue_scripts', 'load_scripts');

/**
 * header.php (or whichever file you want to use for displaying the menu)
 * 
 * container -> this should be set to 'nav' for better accessibility and to make sure the CSS works.
 * items_wrap -> ensures that you can use a custom ID for the <ul> element.
 * menu_id -> The ID should be prefixed with 'am-' to act as a namespace. 
 *  For instance, 'am-main-menu' is the default ID used by the Navigation JS class.
 *  However this can be overridden if you like
 * walker -> the instance of the walker class
 */
$args = array(
  'container' => 'nav',
  'items_wrap' => '<ul id="%1$s" class="nav navbar-nav %2$s">%3$s</ul>',
  'menu_id' => 'am-main-menu',
  'theme_location' => 'menu-name',
  'walker' => new A11y\Menu_Walker()
);
wp_nav_menu($args);

/**
* 
* the main index.js file or wherever you wish to instantiate the Navigation class.
* see below for overriding the constructor defaults.
*/

document.addEventListener('DOMContentLoaded', () => {
  const navigation = new Navigation();
  navigation.init();
})

JavaScript默认值

构造函数具有以下默认值。这些值可以根据需要进行覆盖

• menuId - 默认为'am-main-menu'
• click - 默认为false

最基本的情况

Navigation类设计得尽可能简单易用。为了使用它，创建一个新的Navigation构造函数并将其分配给一个变量。在事件监听器内部，使用实例上的init方法。此实现将创建一个hover菜单。

const navigation = new Navigation();
document.addEventListener('DOMContentLoaded', () => {
  navigation.init();
})

覆盖默认值

默认值可以单独或一起进行覆盖。

const menuOpts = {
  // assumes a <ul> with an id of 'am-my-navigation'
  menuId: 'am-my-navigation',
  click: true
}
const navigation = new Navigation(menuOpts);

这将创建一个具有id为main-nav的导航菜单，并且它将使用click功能而不是悬停。

Sass默认值

提供的样式表旨在提供一个骨架，可以在其上添加额外的样式（例如颜色、填充等）。在 src/scss/icon-styles.scss 中提供了添加图标示例。这些样式将覆盖基本文本图标，以便使用Font Awesome图标。

覆盖和更改菜单的样式非常简单，只需使选择器更具特定性或将自定义样式放在层叠中较低的级别。可以通过使用提供的 am- 类名来提高特定性。

开发

要开始开发

• npm install
• npm run develop

这将开始监视js和scss文件并将它们放入适当的目录。 Navigation.js 和 main.scss 将被转换并发送到 /dist。服务 /public/index.html 将从 /dist 目录读取这些文件。

生产

要创建新的生产版本，请运行 npm run build。

结构

/public

index.html

加载两个菜单示例以进行测试。第一个示例是通过javascript创建的。第二个直接硬编码到文件中。这是为了测试当javascript不可用时菜单的反应。

/build

从 /src 构建的资源将放置在这里并由 index.html 使用。

/css 和 /js

这些是针对基本css和/或js的覆盖/添加示例，可以在此处测试。这对于样式化尤其有用，因为创建的基本样式在很大程度上是中立的。

/src

/js/Navigation

该类处理事件监听器/处理程序

• 将图标分配给具有下拉菜单的菜单项
• 初始化菜单交互
• /js/utils

导出一个辅助函数，根据树状json文件创建菜单

/mock-data

json文件以创建菜单。测试文件中项目的结构需要是

sub 和 classes 键是可选的。

{
  "name": "Menu Item",
  "slug": "menu-item",
  "link": "/menu-item",
  "sub": null, // or array of menu item objects
  "classes": ["an", "array", "of", "class", "names"] 
}

/scss

菜单的基本样式。

gulp.js

监视并适当构建js/scss文件。

webpack.config.js

处理本地测试的捆绑。