JavaScript SDK 快速开始

@yomitone/javascript 当前是未发布的开发版本，需要从源码仓库使用。

Node.js：直接读取 SQLite

Node.js 服务、脚本和 Electron 主进程推荐使用 SQLite Data Pack：

import { createNodeYomiTone } from "@yomitone/javascript/node";

const yomitone = await createNodeYomiTone({
  dataPath: "./yomitone-local.db",
});

try {
  const result = await yomitone.lookupWord("食べました");
  console.log(result.entries[0]?.entry);
} finally {
  await yomitone.close();
}

需要 Node.js 22.13.0 或更高版本。SDK 默认查找数据库同目录的 yomitone-local.manifest.json，并在只读打开前校验 SHA-256、schema、最低 Engine 版本和 数据库 metadata；不需要启动 HTTP 服务，也不会把完整辞典加载成 JavaScript 对象。

浏览器：按需读取分片

import {
  ShardedDictionaryProvider,
  createYomiTone,
} from "@yomitone/javascript";

const provider = new ShardedDictionaryProvider({
  baseUrl: "/yomitone-data/",
});
const yomitone = await createYomiTone({ provider });

baseUrl 指向 Data Builder 生成的浏览器数据目录。Provider 先读取 manifest，再根据查询词 定位一个数据分片。

浏览器不能直接打开本地 SQLite 文件，因此使用 Data Builder 生成的分片数据。每次查询只 读取命中哈希对应的一个分片。

查询词条

const result = await yomitone.lookupWord("食べました");
const entry = result.entries[0]?.entry;

console.log(entry?.morphology);
console.log(entry?.furigana);
console.log(entry?.pitchAccents);        // 辞书形候选
console.log(entry?.surfacePitchAccents); // 当前活用形的表层候选

如果某个活用形可以还原、但当前规则还不能可靠确定表层重音，SDK 会保留 morphology，并返回 明确警告：

const result = await yomitone.lookupWord("食べられる");

result.entries[0]?.entry.surfacePitchAccentStatus; // "unsupported" 或未设置
result.warnings[0]?.code; // "unsupported_conjugation_accent"

查询没有命中时不会抛出“单词不存在”异常：

const result = await yomitone.lookupWord("存在しない語");

result.entries;          // []
result.warnings[0].code; // "unknown_word"

空白输入、数据损坏或版本不兼容仍会作为错误返回。

数据加载方式

完整辞典应使用 DictionaryProvider，不要把一个巨大 JSON 文件完整载入内存。

小型测试或应用自带的少量数据可以直接传入：

const client = await createYomiTone({ data: smallArtifact });

浏览器数据可以由宿主应用随安装包提供，或由用户主动保存到浏览器存储。离线能力的边界取决 于宿主是否已经保存应用代码和所需数据。

由用户安装浏览器数据

import {
  BrowserDataInstaller,
  createYomiTone,
} from "@yomitone/javascript";

const installer = new BrowserDataInstaller({
  baseUrl: "/yomitone-data/",
});

// 在“安装辞典”按钮的点击事件中调用。
await installer.install({
  onProgress(progress) {
    console.log(progress.completedBytes, progress.totalBytes);
  },
});

const provider = await installer.createInstalledProvider();
const yomitone = await createYomiTone({ provider });

安装器会先检查空间，再下载并校验全部分片。可以用 status() 显示安装版本、数据占用、 浏览器总用量与配额；用 remove() 删除已安装辞典。安装辞典不会自动缓存网站本身，完全 离线重新打开页面仍需要宿主提供 Service Worker 或等价的应用资源安装能力。