{"id":28412473,"url":"https://github.com/wswmsword/naviix","last_synced_at":"2025-06-24T12:31:09.421Z","repository":{"id":285104662,"uuid":"953061523","full_name":"wswmsword/naviix","owner":"wswmsword","description":"Spatial navigation. Arrow key navigation. 空间导航。键盘十字键导航。","archived":false,"fork":false,"pushed_at":"2025-06-05T14:14:48.000Z","size":2215,"stargazers_count":56,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-09T18:09:09.391Z","etag":null,"topics":["a11y","keyboard","spatial-navigation"],"latest_commit_sha":null,"homepage":"https://wswmsword.github.io/examples/navix-music/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wswmsword.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-22T13:36:10.000Z","updated_at":"2025-06-09T02:17:26.000Z","dependencies_parsed_at":"2025-03-29T15:25:11.689Z","dependency_job_id":"ce2952bf-443a-4775-89f5-214d80e210a5","html_url":"https://github.com/wswmsword/naviix","commit_stats":null,"previous_names":["wswmsword/focux","wswmsword/navix"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wswmsword/naviix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wswmsword%2Fnaviix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wswmsword%2Fnaviix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wswmsword%2Fnaviix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wswmsword%2Fnaviix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wswmsword","download_url":"https://codeload.github.com/wswmsword/naviix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wswmsword%2Fnaviix/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261675331,"owners_count":23192569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","keyboard","spatial-navigation"],"created_at":"2025-06-02T22:18:08.423Z","updated_at":"2025-06-24T12:31:09.404Z","avatar_url":"https://github.com/wswmsword.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# naviix\n\n\u003ca href=\"https://996.icu\"\u003e\u003cimg src=\"https://img.shields.io/badge/link-996.icu-red.svg\" alt=\"996.icu\" align=\"right\"\u003e\u003c/a\u003e\n\nnaviix 可以辅助实现键盘的空间导航（方向键聚焦导航）。输入元素的坐标和尺寸，输出每个元素的上、下、左、右方向上的相邻元素。具体效果请访问一个线上🎵音乐主题范例：[naviix music](https://wswmsword.github.io/examples/navix-music/)。\n\n\u003cdetails\u003e\n\u003csummary\u003e浏览器中，可以打开“短暂地突出显示焦点对象”无障碍功能，来可视化观察键盘导航的过程。\u003c/summary\u003e\n\nChrome 中，在地址栏输入 `chrome://settings/accessibility`，或者在“设置 -\u003e 无障碍”中，可以设置“短暂地突出显示焦点对象”。其它浏览器也许有类似的设定。\n\n![Chrome Outer Row](https://github.com/wswmsword/hanav/blob/main/images/chrome-outer-row.png)\n\n\u003c/details\u003e\n\n## 安装和使用\n\n使用 npm 安装最新版本（yarn 则是 `yarn add naviix`）：\n\n```bash\nnpm install naviix\n```\n\n使用格式：\n```javascript\nconst res = naviix(rectangles);\n```\n\n具体范例：\n```javascript\nimport navix from \"naviix\";\nconst r1 = [1, 1, 1, 1]; // 矩形 r1 的坐标尺寸\nconst r2 = [4, 1, 1, 1]; // 矩形 r2\nconst nxMap = navix([r1, r2]);\nconst r1Right = nxMap.get(r1).right; // r1 的右方元素\nconst r2Left = nxMap.get(r2).left; // r2 的左方元素\n```\n\n### 参数\n\n- `rectangles`，数组或对象，表示所有矩形的坐标尺寸信息，当所有矩形在同一平面中时选择数组格式，当存在例如可滚动区域的子区时选择对象格式。\n\n数组格式范例：\n```json\n[\n  { \"id\": \"s1\", \"loc\": [1, 1, 1, 1] },\n  { \"id\": \"s2\", \"loc\": [4, 1, 1, 1] }\n]\n```\n\n\u003e 简写形式为 `[[1, 1, 1, 1], [4, 1, 1, 1]]`。\n\n- `loc`，长度为 4 的数组，数组前两个数字表示矩形中心坐标，后两个数字表示中心距离竖边与横边的距离；\n- `id` 作为唯一值代表了某个矩形，可以是任何值，当忽略 `id` 时，naviix 会主动将 `loc` 填充为 `id`。\n\n\u003cdetails\u003e\n\u003csummary\u003e\n展开查看更长一些的对象格式范例。\n\u003c/summary\u003e\n\n```json\n{\n  \"locs\": [{ \"id\": \"s1\", \"loc\": [1, 5, 1, 1] }],\n  \"subs\": {\n    \"locs\": [\n      { \"id\": \"s2\", \"loc\": [5, 1, 1, 1] },\n      { \"id\": \"s3\", \"loc\": [5, 4, 1, 1] }\n    ],\n    \"wrap\": { \"id\": \"w\", \"loc\": [5, 3.5, 2, 3.5] }\n  }\n}\n```\n\n- 当包含 `subs` 子区时，`wrap` 是必须的，表示子区的包裹层的坐标尺寸信息。\n\n\u003e 对象格式中，同样支持简写形式。\n\n\u003c/details\u003e\n\n\n\n### 返回值\n\n返回值是一个 `Map`，`Map` 的键是输入参数中的 `id`，值是一个包含 `up/right/down/left` 四个属性的对象，属性值为 `undefined` 表示该方向没有相邻矩形，否则值是一个形如 `{ id: \"\", loc: [] }` 的对象。\n\n\u003cdetails\u003e\n\u003csummary\u003e\n输入参数中，可以将 id 设置为 DOM 对象，方便在返回值中操作。例如“resMap.get(btn).right?.id.focus()”。\n\u003c/summary\u003e\n\n```javascript\nconst r1 = document.getElementById(\"r1\");\nconst r2 = document.getElementById(\"r2\");\nconst nxMap = navix([{\n  id: r1,\n  loc: [1, 1, 1, 1]\n}, {\n  id: r2,\n  loc: [4, 1, 1, 1]\n}]);\nnxMap.get(r1).right.id.focus();\n```\n\n上面代码块中，返回值 `nxMap` 的结构如下：\n\n```\nMap(2) {\n  r1 =\u003e {\n    up: undefined,\n    right: { id: r2, loc: [4, 1, 1, 1] },\n    down: undefined,\n    left: undefined\n  },\n  r2 =\u003e {\n    up: undefined,\n    right: undefined,\n    down: undefined,\n    left: { id: r1, loc: [1, 1, 1, 1] }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\n## 单元测试与参与开发\n\n```bash\nnpm install\nnpm run test\n```\n\n参与开发，一起让程序的变量命名更合适、性能和功能更好。修改源码后，编写并执行相关[单元测试](./index.spec.js)，验证是否输出了预期的结果。项目中的原理文件（[how-it-works.md](./how-it-works.md)）也许能提供一定帮助。\n\n## 支持与赞助\n\n点亮星星、提出问题、请求合并来推动这个项目！\n\n\u003cdetails\u003e\n\u003csummary\u003e展开查看用于微信支付和支付宝支付的二维码。\u003c/summary\u003e\n\n您可以支付该项目，支付金额由您从该项目中获得的收益自行决定。\n\n\u003ctable\u003e\n  \u003ctr align=\"center\"\u003e\n    \u003ctd\u003e微信支付\u003c/td\u003e\n    \u003ctd\u003e支付宝支付\u003c/td\u003e\n  \u003c/tr\u003e\n\t\u003ctr\u003e\n\t\t\u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/wswmsword/postcss-mobile-forever/main/images/wechat-pay.png\" alt=\"Pay through WeChat\" /\u003e\u003c/td\u003e\n\t\t\u003ctd\u003e\u003cimg src=\"https://github.com/wswmsword/postcss-mobile-forever/raw/main/images/ali-pay.jpg\" alt=\"Pay through AliPay\" /\u003e\u003c/td\u003e\n\t\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/details\u003e\n\n## 日志、版本规则、协议和其它\n\n相关链接：\n- [CSS Spatial Navigation Level 1](https://drafts.csswg.org/css-nav-1/)，W3C 空间导航草案\n- [WICG/spatial-navigation](https://github.com/WICG/spatial-navigation)，WICG GitHub 仓库，提供在线范例和空间导航 polyfill\n- [TV Spatial Navigation](https://engineering.atspotify.com/2023/05/tv-spatial-navigation)，Spotify 的空间导航介绍\n\n---\n\n[Demo](https://wswmsword.github.io/examples/navix-music/) • [更新日志](./CHANGELOG.md) • [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) • [MPL-2.0 License](./LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwswmsword%2Fnaviix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwswmsword%2Fnaviix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwswmsword%2Fnaviix/lists"}