ルビフルボタンV2について
ルビフルボタンV2 は、日本語テキストに含まれる 漢字 にだけ自動でふりがな(ルビ)を付与する軽量なブラウザ向け JavaScript ライブラリです。導入は 1 行の <script>
で完了し、動的に変化する DOM にも追従します。
特徴
- 自動ルビ : 文章中の漢字にのみルビを付与し、可読性を維持
- 手動ルビとの共存 : 既に
<ruby>
タグが存在する箇所はスキップ - MutationObserver 対応 : SPA やチャットなど、後から挿入されるテキストにも対応
- スタイルの完全カスタマイズ : トグルボタン・ルビ要素ともに自由にデザイン可能
- CDN 1 ファイル : 依存なし、コピー&ペーストですぐに使用可能
1. デモ
実際の動作は以下で確認できます:
▶️ オンラインデモ
2. クイックスタート(最小構成)
<!-- 1. スクリプトを読み込む(</body> 直前推奨) -->
<script src="https://rubyful-v2.s3.ap-northeast-1.amazonaws.com/v2/rubyful.js?t=20250507022654"></script>
<script>
window.addEventListener('load', () => {
RubyfulV2.init({
selector: '.content p', // ★ 親要素 .content 内の <p> を対象
defaultDisplay: true // ★ ページ読み込み時にルビを表示
});
});
</script>
<!-- 2. ルビを付与したい要素 -->
<div class="content">
<p>私は東京の下町で生まれました。</p>
<p>古い商店街には、昔ながらの風情が残っています。</p>
</div>
📌 結果 : 例)「東京」→「とうきょう」、「下町」→「したまち」のように自動でルビが付きます。
💡親要素の指定にお困りの場合
例として、汎用的な範囲指定のサンプルは以下となります。
導入したいサイトのHTMLに、以下ソースコードを追加してください。
<!-- 1. スクリプトを読み込む(</body> 直前推奨) -->
<script src="https://rubyful-v2.s3.ap-northeast-1.amazonaws.com/v2/rubyful.js?t=20250507022654"></script>
<script>
window.addEventListener('load', () => {
RubyfulV2.init({
selector: 'p, h1, h2, h3, h4, h5, h6, li, td, th, span',
defaultDisplay: true
});
});
</script>
3. API 概要
3.1 RubyfulV2.init(options)
オプション名 | 型 | 必須 | デフォルト | 説明 |
---|---|---|---|---|
selector | string | ✔︎ | ー | ルビを付与する要素の CSS セレクタ |
defaultDisplay | boolean | ✔︎ | ー | 初期表示時にルビを表示するか |
observeChanges | boolean | ✖︎ | false | DOM 変更を監視し、動的コンテンツにもルビを付与 |
styles | object | ✖︎ | {} | トグルボタンやルビ要素のクラス・テキストを上書き |
selector が空文字列の場合は初期化が中断され、以下のエラーが出力されます。 RubyfulV2: セレクタは必須で、空文字列は許可されません
3.2 RubyfulV2.processElement(element)
任意の単一要素に対して後からルビ処理を実行したい場合に使用します。init()
で指定した selector
とは独立して動作します。
const preview = document.getElementById('preview');
preview.textContent = '入力中のテキスト';
RubyfulV2.processElement(preview);
4. 手動ルビとの使い分け
Rubyful V2 は自動ルビを提供しますが、以下のケースでは手動ルビ( <ruby>
タグ)を推奨 します。
- 既に正しいルビが振られている箇所
- 固有名詞、人名、地名、商品名など 読みが一意に定まらない 場合
- 専門用語や業界用語
- 1〜2 文字だけの短いテキスト(例:
<span>生</span>
→ 「せい」「しょう」「なま」…)
<p>
私の名前は <ruby>山田太郎<rt>やまだたろう</rt></ruby> です。<br>
<ruby>東京<rt>とうきょう</rt></ruby> の <ruby>渋谷<rt>しぶや</rt></ruby> に住んでいます。
</p>
手動ルビが存在する要素は 自動ルビの対象外 になります。(優先順位は手動ルビが上)
5. 使用例
5.1 静的コンテンツ(基本)
上記「クイックスタート」を参照。
5.2 動的コンテンツ(SPA・チャットなど)
<script>
window.addEventListener('load', () => {
RubyfulV2.init({
selector: '.content p',
defaultDisplay: true,
observeChanges: true // DOM 変更を監視
});
});
</script>
5.3 テキストエディタのプレビューなど、特定要素のみ処理
<textarea id="editor" rows="4" cols="40"></textarea>
<p id="preview"></p>
<script>
const editor = document.getElementById('editor');
const preview = document.getElementById('preview');
editor.addEventListener('input', () => {
preview.textContent = editor.value.trim();
RubyfulV2.processElement(preview);
});
</script>
6. スタイルカスタマイズ
6.1 トグルボタン
RubyfulV2.init({
selector: '.content p',
defaultDisplay: true,
styles: {
toggleButtonClass: 'my-toggle',
toggleButtonText: {
on: 'ルビ ON',
off: 'ルビ OFF'
}
}
});
.my-toggle {
position: fixed;
bottom: 20px;
right: 20px;
padding: 10px 20px;
background: #2196F3;
color: #fff;
border: none;
border-radius: 4px;
cursor: pointer;
transition: 0.3s;
}
.my-toggle:hover { background: #1976D2; }
画像を使ったボタンにしたい場合は、background-image
を指定して toggleButtonText
を空にしてください。
6.2 ルビ要素(.rubyful-rt
)
.rubyful-rt {
font-size: 0.7em;
font-weight: bold;
color: #E91E63;
text-align: center;
}
/* ルビ非表示時 */
.rubyful-rt.hidden { display: none !important; }
レスポンシブ例
@media (max-width: 768px) {
.rubyful-rt { font-size: 0.6em; }
}
アクセシビリティ / 印刷
@media print {
.rubyful-rt { color: #000; font-weight: normal; }
}
7. FAQ(よくある質問)
Q. ルビの精度は完璧ですか?
A. 一般的な文章では高精度ですが、固有名詞や文脈依存の読みには誤りが生じる場合があります。そのような箇所は手動ルビを推奨します。
Q. パフォーマンスに影響はありますか?
A. 初期化時と DOM 変更検知時にテキストをバッチ処理しています。大量の要素を対象にする場合は処理が完了するまで時間がかかることがあります。
Q. 対応ブラウザは?
A. 原則として、モダンブラウザの最新バージョンで動作することを前提に開発しています。