[インデックス 14152] ファイルの概要

このコミットは、doc/godocs.js ファイルに対する変更です。このJavaScriptファイルは、Go言語の公式ドキュメントツールであるgodocのフロントエンドの挙動を制御しています。具体的には、キーボードナビゲーションの改善を目的とした修正が加えられています。

コミット

commit 6e0df254b0b2aed3840fc696f8c8f8fb16ad6c70
Author: Shenghou Ma <minux.ma@gmail.com>
Date:   Tue Oct 16 14:28:18 2012 +0800

    doc/godoc.js: put focus on div#page when necessary
    so that keyboard navigation events are sent to div#page.
    
            Fixes #4233.
    
    R=adg
    CC=golang-dev
    https://golang.org/cl/6652048

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/6e0df254b0b2aed3840fc696f8c8f8fb16ad6c70

元コミット内容

doc/godoc.js: put focus on div#page when necessary
so that keyboard navigation events are sent to div#page.

        Fixes #4233.

R=adg
CC=golang-dev
https://golang.org/cl/6652048

変更の背景

このコミットは、Go言語のドキュメント表示ツールであるgodocにおいて、キーボードによるナビゲーションが正しく機能しないという問題（Issue #4233）を修正するために行われました。

具体的な問題は、ユーザーがgodocで表示されたページを閲覧している際に、キーボードの矢印キー（上/下）、スペースキーなどを使ってスクロールしようとしても、期待通りに動作しない場合があるというものでした。これは、ページのコンテンツ領域（div#page）にフォーカスが当たっていないために、キーボードイベントが別の要素（例えば、固定位置にあるヘッダーバーなど）に送られてしまい、ページ全体のスクロールができないことが原因でした。

この修正は、ユーザーエクスペリエンスを向上させ、キーボードのみでのドキュメント閲覧をよりスムーズにすることを目的としています。

前提知識の解説

このコミットを理解するためには、以下のWeb技術と概念に関する知識が役立ちます。

HTMLのDOM (Document Object Model): WebページはHTML要素のツリー構造（DOM）として表現されます。JavaScriptはこのDOMを操作して、ページのコンテンツやスタイル、挙動を変更します。
JavaScriptとjQuery: このコミットで変更されているgodocs.jsはJavaScriptで書かれており、jQueryライブラリを使用しています。jQueryは、DOM操作、イベントハンドリング、アニメーションなどを簡素化するJavaScriptライブラリです。
- $(): jQueryのセレクタ関数で、HTML要素を選択するために使われます。例えば$('div#page')はIDがpageのdiv要素を選択します。
- .css(): 要素のCSSプロパティを設定または取得します。
- .attr(): 要素のHTML属性を設定または取得します。
- .ready(): DOMが完全にロードされた後に実行される関数を登録します。
- .resize(): ウィンドウのリサイズイベントをハンドリングします。
- .focus(): 要素にプログラム的にフォーカスを当てます。
CSSのposition: fixed: CSSのpositionプロパティの一つで、要素をビューポート（ブラウザの表示領域）に対して固定します。スクロールしてもその位置に留まります。godocのトップバー（div#topbar）がこれに該当します。
HTMLのtabindex属性: この属性は、要素がキーボードのTabキーによるナビゲーションでフォーカス可能かどうか、またその順序を制御します。
- tabindex="-1": 要素はTabキーではフォーカスされませんが、JavaScriptの.focus()メソッドなどプログラム的にフォーカスを当てることができます。これは、要素が通常はフォーカス可能ではないが、特定の状況下でフォーカスを必要とする場合に便利です。
キーボードイベントとフォーカス: Webページでは、キーボード入力は現在フォーカスが当たっている要素に送られます。例えば、テキスト入力フィールドにフォーカスが当たっていれば、入力した文字はそのフィールドに入力されます。ページ全体のスクロールなどのイベントは、通常、body要素や、ページコンテンツを保持する主要な要素にフォーカスが当たっている場合に処理されます。
godoc: Go言語のソースコードからドキュメントを生成し、Webブラウザで表示するためのツールです。Goの標準ライブラリやユーザーのGoパッケージのドキュメントを閲覧する際に利用されます。

技術的詳細

このコミットの技術的な核心は、JavaScriptを使用して、特定の条件下でページの主要コンテンツ領域（div#page）にプログラム的にフォーカスを当てることです。

fixFocus関数の導入: 新たにfixFocusというJavaScript関数が定義されました。この関数は、キーボードナビゲーションが正しく機能するように、div#page要素にフォーカスを当てることを目的としています。
div#pageのフォーカス可能化:
- page.css('outline', 0);: フォーカスが当たった際にブラウザがデフォルトで表示するアウトライン（枠線）を無効にしています。これにより、ユーザーインターフェースがすっきりします。
- page.attr('tabindex', -1);: div#page要素にtabindex="-1"属性を設定しています。これにより、このdiv要素はTabキーによるナビゲーションではスキップされますが、JavaScriptのfocus()メソッドを使ってプログラム的にフォーカスを当てることが可能になります。これは、ユーザーが明示的にクリックしなくても、特定の状況でページコンテンツにフォーカスを移したい場合に重要です。
ウィンドウリサイズイベントの監視:
- $(window).resize(function (evt) { ... }).resize();: ウィンドウのリサイズイベントを監視しています。イベントハンドラは、ページがロードされた直後にも一度実行されます（.resize()のチェイン）。
- 条件付きフォーカス: リサイズイベントハンドラ内で、topbar.css('position') == "fixed"という条件をチェックしています。これは、トップバー（div#topbar）が固定位置にあるかどうかを判断しています。
  - トップバーが固定位置にある場合、それは通常、ページのスクロール位置に関わらず画面上部に表示され続けることを意味します。この状況では、キーボードイベントが誤ってトップバーに送られてしまい、ページコンテンツのスクロールが妨げられる可能性があります。
  - この条件が真の場合にのみ、page.focus();が実行され、div#pageにフォーカスが当てられます。これにより、キーボードイベントが正しくページコンテンツにルーティングされ、矢印キーなどによるスクロールが可能になります。

このアプローチにより、godocのページがロードされた際や、ウィンドウサイズが変更された際に、必要に応じて自動的にページコンテンツにフォーカスが移るようになり、キーボードナビゲーションの問題が解決されます。

コアとなるコードの変更箇所

doc/godocs.js ファイルに以下の変更が加えられました。

--- a/doc/godocs.js
+++ b/doc/godocs.js
@@ -163,6 +163,22 @@ function setupDropdownPlayground() {
   $('#menu').css('min-width', '+=60');
 }
 
+// fixFocus tries to put focus to div#page so that keyboard navigation works.
+function fixFocus() {
+  var page = $('div#page');
+  var topbar = $('div#topbar');
+  page.css('outline', 0); // disable outline when focused
+  page.attr('tabindex', -1); // and set tabindex so that it is focusable
+  $(window).resize(function (evt) {
+    // only focus page when the topbar is at fixed position (that is, it's in
+    // front of page, and keyboard event will go to the former by default.)
+    // by focusing page, keyboard event will go to page so that up/down arrow,
+    // space, etc. will work as expected.
+    if (topbar.css('position') == "fixed")
+      page.focus();
+  }).resize();
+}
+
 $(document).ready(function() {
   bindSearchEvents();
   generateTOC();
@@ -173,6 +189,7 @@ $(document).ready(function() {
   bindToggleLinks(".examplesLink", "");
   bindToggleLinks(".indexLink", "");
   setupDropdownPlayground();
+  fixFocus();
 });
 
 })();

コアとなるコードの解説

fixFocus関数の追加:
- この関数は、godocページのキーボードナビゲーションを改善するために導入されました。
- var page = $('div#page'); と var topbar = $('div#topbar'); で、ページの主要コンテンツ領域とトップバーのjQueryオブジェクトを取得しています。
- page.css('outline', 0); は、div#pageにフォーカスが当たったときに表示されるブラウザのデフォルトのアウトラインを非表示にしています。これは視覚的なクリーンさを保つためです。
- page.attr('tabindex', -1); は、div#page要素をプログラム的にフォーカス可能にしています。tabindex="-1"は、Tabキーでのナビゲーションからは除外されますが、JavaScriptのfocus()メソッドでフォーカスを当てることができます。
- $(window).resize(function (evt) { ... }).resize(); は、ウィンドウのリサイズイベントが発生した際に実行される匿名関数を登録しています。.resize()をチェインすることで、ページロード時にも一度この関数が実行されます。
- 匿名関数内では、if (topbar.css('position') == "fixed") という条件で、トップバーが固定位置にあるかどうかをチェックしています。トップバーが固定されている場合、キーボードイベントがトップバーに奪われ、ページコンテンツのスクロールができない問題が発生する可能性があります。
- 条件が真の場合、page.focus(); が実行され、div#pageにフォーカスが強制的に当てられます。これにより、キーボードイベントが正しくページコンテンツに送られ、矢印キーやスペースキーでのスクロールが機能するようになります。
$(document).ready内でのfixFocus()の呼び出し:
- $(document).ready(function() { ... }); ブロックは、DOMが完全にロードされた後に実行されるコードを含んでいます。
- このブロックの最後に fixFocus(); が追加されました。これにより、ページがロードされた直後にfixFocus関数が実行され、初期状態でキーボードナビゲーションが正しく機能するように設定されます。

この変更により、godocのページが表示された際に、ユーザーが特別な操作をしなくても、キーボードによるスムーズなナビゲーションが可能になります。

参考にした情報源リンク

jQuery Documentation
MDN Web Docs - tabindex
MDN Web Docs - position
Go godoc command (現在のgodocコマンドのドキュメント)
Go Issue 4233: godoc: keyboard navigation doesn't work when topbar is fixed (このコミットが修正した具体的な問題の詳細)

comemo