Skip to content

OpenCC compiled by Emscripten so that you can run it on browsers or nodejs without compiling.

License

Notifications You must be signed in to change notification settings

oyyd/wasm-opencc

Repository files navigation

wasm-opencc

npm-version travis-ribbon

wasm-opencc开放中文转换OpenCC的wasm版本。

这个项目对OpenCC进行了添加修改修改,并利用Emscripten进行编译,在OpenCC进行中文简繁体转换的能力上具有以下特性:

  • 可在浏览器环境中直接运行。(wasm)
  • 在node,eletron中运行不需要再进行addon编译,避免复杂的addon部署工作。理论上应该也可以在React Native和Web Worker中运行(未经测试)。(wasm)
  • 分离了字典数据的加载和文本转换功能,在浏览器中只加载必要的字典数据,并允许自定义数据加载方式,方便从CDN上加载数据。

安装

对于浏览器环境,请直接拷贝dist文件夹中的文件并在浏览器中加载,注意请一并拷贝dist文件夹下的.mem文件,该.mem文件为代码运行的必要文件。

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <script src="./opencc-asm.js"></script>
    <script>
      const { DictSource, Converter } = OpenCCWasm_
      OpenCCWasm_.ready().then(() => {
        // 获取s2t.json字典数据
        const dictSource = new DictSource('s2t.json');
        return dictSource.get();
      }).then((args) => {
        const converter = new Converter(...args)
        console.log(converter.convert('繁体'))
        // 注意当不再需要使用converter时,请调用delete方法以释放内存
        converter.delete()
      })
    </script>
  </body>
</html>

相关文件大小(不包含字典文件):

  • opencc-asm.js (655kB, gzip后164kB)
  • opencc-asm.js.mem (25kB, gzip后8kB)

当前项目中的wasm代码,实际上是asmjs版本,并非用于浏览器原生WebAssembly的版本。asmjs的版本兼容性更好,WebAssembly版本体积更小(约在在250kB左右)。

对于node环境,可以直接利用npm安装:

$ npm i -d wasm-opencc

安装后加载使用:

const { DictSource, Converter } = require('wasm-opencc')
const dictSource = new DictSource('s2t.json');

dictSource.get().then((args) => {
  const converter = new Converter(...args)
  console.log(converter.convert('繁体'))
  // 注意當不再需要使用converter時,請調用delete方法以釋放內存
  converter.delete()
})

注意OpenCC本身具有Node Addon版本,请根据自己的需要选择。

API

ready()

在浏览器上,请先调用ready函数,并在结束后再进行Converter的相关操作。在Node上不需要等待ready函数结束,直接使用即可。

class DictSource

new DictSource(string dictName)

DictSource用于获取字典数据,以初始化Converter。如果你熟悉OpenCC中Converter所需要的数据格式,和数据构成结构,你也可以完全避开DictSource,直接把字典数据的字符串传递给Converter。

dictName所接受的参数请参照:預設配置文件

DictSource.get()

DictSource.get()默认会根据运行环境不同,采用不同的方式获取数据。

DictSource.get()返回一个Promise,这个Promise在resolve时会返回构建Converter所需要的参数的数组,当获取字典数据失败时会reject。返回参数的意义请参照new Converter()

DictSource.setDictProxy(function proxy)

自定义获取数据的函数:

const dictSource = new DictSource('s2t.json')

dictSource.setDictProxy((dictName) => {
  // proxy需要返回一个promise
  return Promise.resolve('僞\t偽\n')
})

dictSource.get() // 会调用proxy函数

DictSource会给proxy函数传入所需要的字典名称,而proxy函数需要返回一个promise以告知DictSource请求结束或请求失败。成功的话需要resolve对应的字典数据内容,失败的话请reject一个Error对象。

class Conveter

new Converter(string semgentation, Array<Array|string> convertionChain)

Converter用来进行文本转换。

其中semgentation为分词用的数据;convertionChain按顺序定义了转换时所使用的一系列数据字典。

Converter.convert(string text)

Converter.convert进行文本转换操作,同步操作。

Converter.delete()

销毁该实例在wasm中对应对象的实例。请注意:在不需要使用converter以后,一定要手动调用delete方法销毁内存。

目前要求用户手动调用delete这点不可避免,这是Embind和目前wasm机制所决定的,可参照Embind -- Memory Management

已知问题

  • 暂不接受.ocd类型的字典数据
  • uglifyjs相关问题:在开发过程中发现,用uglifyjs处理wasm编译的代码后,会导致其在Chrome上无法正常运行(但在safari上可以正常运行)。个人猜测是Chrome引发的问题。
  • 因为上述原因,加之编译后代码本身的一些问题,作者对于在浏览器中运行的文件进行了一些自定义的处理并进行了bundle。如果你的项目要运行在浏览器环境上的话,不建议你对wasm-opencc自己进行bundle。

其他可能会实行的计划

  • 进行Benchmark,探究Cpp版本,Node Addon版本和wasm版本之间的性能差距。
  • 提供WebAssembly版本。
  • 用closure进行编译提高效率。

Contribute

请先安装Emscripten和OpenCC所需依赖,然后:

进行Emscripten编译代码:

make -f WasmMakefile

构建js相关代码:

cd wasm && npm run build

构建文档:

cd wasm && npm run docs

运行测试:

cd wasm && npm run test

License

这个项目在OpenCC的基础上添加了/src/wasm文件夹下的代码。原项目中多个文件夹下的CMakeLists.txt都被进行了一定程度上的修改。wasm相关的js代码主要放在/wasm文件夹下,为新增代码。/docs中的代码用于gh-pages展现文档。

Apache 2.0