Skip to content

Commit 1618848

Browse files
ren1244ren1244
authored
ES Module and new feature (#23)
* Add es6 module * Fix: script src * Downward compatibility es6 in node * Bundle for es6 import * Update README * update build and test * Fix: Build and Test * Fix: build and test * Update: Suggested change
1 parent 5b4f49d commit 1618848

19 files changed

+1476
-159
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
node_modules
2+
dist
23

34
/data*.js
45
/full.js

‎README-zh-CN.md‎

Lines changed: 85 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,22 @@
66

77
**在 HTML 中加载**
88

9-
依次加载以下四个 `script` 标签：
9+
加载以下 `script` 标签（择一即可）：
1010

1111
```html
12-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.min.js"></script> <!-- 必须加载 -->
13-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.cn2t.min.js"></script> <!-- 需要简转繁时 -->
14-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.t2cn.min.js"></script> <!-- 需要繁转简时 -->
15-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/bundle-browser.min.js"></script><!-- 必须加载 -->
12+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/full.js"></script> <!-- 完全版 -->
13+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/cn2t.js"></script> <!-- 只需要简转繁时 -->
14+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/t2cn.js"></script> <!-- 只需要繁转简时 -->
15+
```
16+
17+
自行托管的话，除了使用原先的 umd，也可以使用 es module
18+
19+
```html
20+
<script type="module">
21+
import * as OpenCC from './dist/esm/full.js'; // 完全版
22+
import * as OpenCC from './dist/esm/cn2t.js'; // 只需要简转繁
23+
import * as OpenCC from './dist/esm/t2cn.js'; // 只需要繁转简
24+
</script>
1625
```
1726

1827
**在 Node.js 中加载**
@@ -21,10 +30,18 @@
2130
npm install opencc-js
2231
```
2332

33+
CommonJS
34+
2435
```javascript
2536
const OpenCC = require('opencc-js');
2637
```
2738

39+
ES Modules
40+
41+
```javascript
42+
import * as OpenCC from 'opencc-js';
43+
```
44+
2845
## 使用
2946

3047
**基本用法**
@@ -53,6 +70,51 @@ const converter = OpenCC.CustomConverter([
5370
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear
5471
```
5572

73+
或以「空白」及「|」当作分隔符号
74+
75+
```javascript
76+
const converter = OpenCC.CustomConverter('香蕉 banana|蘋果 apple|梨 pear');
77+
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear
78+
```
79+
80+
**添加字词**
81+
82+
* `ConverterFactory` 是比较底层的函数，`Converter` 及 `CustomConverter` 都是这个函数的再包装。
83+
* 透过 `Locale` 属性可以得到原本的字典，进而添加字词。
84+
85+
```javascript
86+
const customDict = [
87+
['“', '「'],
88+
['”', '」'],
89+
['‘', '『'],
90+
['’', '』'],
91+
];
92+
const converter = OpenCC.ConverterFactory(
93+
OpenCC.Locale.from.cn, // 中国大陆 => OpenCC 标准
94+
OpenCC.Locale.to.tw.concat([customDict]) // OpenCC 标准 => 台湾+自订
95+
);
96+
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
97+
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
98+
```
99+
100+
下面的写法也会得到相同的结果，只是内部会多做一次转换
101+
102+
```javascript
103+
const customDict = [
104+
['“', '「'],
105+
['”', '」'],
106+
['‘', '『'],
107+
['’', '』'],
108+
];
109+
const converter = OpenCC.ConverterFactory(
110+
OpenCC.Locale.from.cn, // 中国大陆 => OpenCC 标准
111+
OpenCC.Locale.to.tw, // OpenCC 标准 => 台湾
112+
[customDict] // 台湾 => 自订
113+
);
114+
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
115+
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
116+
```
117+
56118
**DOM 操作**
57119

58120
HTML 属性 `lang='*'` 定义了目标。
@@ -68,8 +130,25 @@ const converter = OpenCC.Converter({ from: 'hk', to: 'cn' });
68130
const rootNode = document.documentElement;
69131
// 将所有 zh-HK 标签转为 zh-CN 标签
70132
const HTMLConvertHandler = OpenCC.HTMLConverter(converter, rootNode, 'zh-HK', 'zh-CN');
71-
HTMLConvertHandler.convert(); // 开始转换 -> 汉语
133+
HTMLConvertHandler.convert(); // 开始转换 -> 汉语
72134
HTMLConvertHandler.restore(); // 复原 -> 漢語
73135
```
74136

75137
class list 包含 `ignore-opencc` 的标签不会被转换（包括该标签的所有子节点）。
138+
139+
## 打包优化
140+
141+
如果使用 rollup 等工具打包程式码，以下方式能让打包工具自动移除用不到的部分，减少档案大小。
142+
143+
```javascript
144+
import * as OpenCC from 'opencc-js/core'; // 核心程式码
145+
import * as Locale from 'opencc-js/preset'; // 字典资料
146+
147+
const converter = OpenCC.ConverterFactory(Locale.from.hk, Locale.to.cn);
148+
console.log(converter('漢語'));
149+
```
150+
151+
备注：
152+
153+
* 由于这是利用 Tree Shaking，所以必须使用 ES Modules
154+
* 在这个模式之下，没有 `Converter` 函式，必须直接使用 `ConverterFactory`

‎README-zh-TW.md‎

Lines changed: 86 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,22 @@
66

77
**在 HTML 中載入**
88

9-
依次載入以下四個 `script` 標籤：
9+
載入以下 `script` 標籤（擇一即可）：
1010

1111
```html
12-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.min.js"></script> <!-- 必須載入 -->
13-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.cn2t.min.js"></script> <!-- 需要簡轉繁時 -->
14-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.t2cn.min.js"></script> <!-- 需要繁轉簡時 -->
15-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/bundle-browser.min.js"></script><!-- 必須載入 -->
12+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/full.js"></script> <!-- 完全版 -->
13+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/cn2t.js"></script> <!-- 只需要簡轉繁時 -->
14+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/t2cn.js"></script> <!-- 只需要繁轉簡時 -->
15+
```
16+
17+
自行託管的話，除了使用原先的 umd，也可以使用 es module
18+
19+
```html
20+
<script type="module">
21+
import * as OpenCC from './dist/esm/full.js'; // 完全版
22+
import * as OpenCC from './dist/esm/cn2t.js'; // 只需要簡轉繁
23+
import * as OpenCC from './dist/esm/t2cn.js'; // 只需要繁轉簡
24+
</script>
1625
```
1726

1827
**在 Node.js 中載入**
@@ -21,10 +30,18 @@
2130
npm install opencc-js
2231
```
2332

33+
CommonJS
34+
2435
```javascript
2536
const OpenCC = require('opencc-js');
2637
```
2738

39+
ES Modules
40+
41+
```javascript
42+
import * as OpenCC from 'opencc-js';
43+
```
44+
2845
## 使用
2946

3047
**基本用法**
@@ -53,9 +70,54 @@ const converter = OpenCC.CustomConverter([
5370
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear
5471
```
5572

73+
或以「空白」及「|」當作分隔符號
74+
75+
```javascript
76+
const converter = OpenCC.CustomConverter('香蕉 banana|蘋果 apple|梨 pear');
77+
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear
78+
```
79+
80+
**添加字詞**
81+
82+
* `ConverterFactory` 是比較底層的函數，`Converter` 及 `CustomConverter` 都是這個函數的再包裝。
83+
* 透過 `Locale` 屬性可以得到原本的字典，進而添加字詞。
84+
85+
```javascript
86+
const customDict = [
87+
['“', '「'],
88+
['”', '」'],
89+
['‘', '『'],
90+
['’', '』'],
91+
];
92+
const converter = OpenCC.ConverterFactory(
93+
OpenCC.Locale.from.cn, // 中國大陸 => OpenCC 標準
94+
OpenCC.Locale.to.tw.concat([customDict]) // OpenCC 標準 => 臺灣+自訂
95+
);
96+
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
97+
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
98+
```
99+
100+
下面的寫法也會得到相同的結果，只是內部會多做一次轉換
101+
102+
```javascript
103+
const customDict = [
104+
['“', '「'],
105+
['”', '」'],
106+
['‘', '『'],
107+
['’', '』'],
108+
];
109+
const converter = OpenCC.ConverterFactory(
110+
OpenCC.Locale.from.cn, // 中國大陸 => OpenCC 標準
111+
OpenCC.Locale.to.tw, // OpenCC 標準 => 臺灣
112+
[customDict] // 臺灣 => 自訂
113+
);
114+
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
115+
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
116+
```
117+
56118
**DOM 操作**
57119

58-
HTML 屬性 `lang='*'` 定義了目標。
120+
HTML 屬性 `lang='*'` 定義了目標。
59121

60122
```html
61123
<span lang="zh-HK">漢語</span>
@@ -68,8 +130,25 @@ const converter = OpenCC.Converter({ from: 'hk', to: 'cn' });
68130
const rootNode = document.documentElement;
69131
// 將所有 zh-HK 標籤轉為 zh-CN 標籤
70132
const HTMLConvertHandler = OpenCC.HTMLConverter(converter, rootNode, 'zh-HK', 'zh-CN');
71-
HTMLConvertHandler.convert(); // 開始轉換 -> 汉语
133+
HTMLConvertHandler.convert(); // 開始轉換 -> 汉语
72134
HTMLConvertHandler.restore(); // 復原 -> 漢語
73135
```
74136

75137
class list 包含 `ignore-opencc` 的標籤不會被轉換（包括該標籤的所有子節點）。
138+
139+
## 打包優化
140+
141+
如果使用 rollup 等工具打包程式碼，以下方式能讓打包工具自動移除用不到的部分，減少檔案大小。
142+
143+
```javascript
144+
import * as OpenCC from 'opencc-js/core'; // 核心程式碼
145+
import * as Locale from 'opencc-js/preset'; // 字典資料
146+
147+
const converter = OpenCC.ConverterFactory(Locale.from.hk, Locale.to.cn);
148+
console.log(converter('漢語'));
149+
```
150+
151+
備註：
152+
153+
* 由於這是利用 Tree Shaking，所以必須使用 ES Modules
154+
* 在這個模式之下，沒有 `Converter` 函式，必須直接使用 `ConverterFactory`

‎README.md‎

Lines changed: 81 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,19 @@ The JavaScript version of Open Chinese Convert (OpenCC)
1111
Import in HTML pages:
1212

1313
```html
14-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.min.js"></script> <!-- Required -->
15-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.cn2t.min.js"></script> <!-- For Simplified to Traditional -->
16-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/data.t2cn.min.js"></script> <!-- For Traditional Chinese to Simplified Chinese -->
17-
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/bundle-browser.min.js"></script><!-- Required -->
14+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/full.js"></script> <!-- Full version -->
15+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/cn2t.js"></script> <!-- For Simplified to Traditional -->
16+
<script src="https://cdn.jsdelivr.net/npm/opencc-js@1.0.4/dist/umd/t2cn.js"></script> <!-- For Traditional Chinese to Simplified Chinese -->
17+
```
18+
19+
ES6 import
20+
21+
```html
22+
<script type="module">
23+
import * as OpenCC from './dist/esm/full.js'; // Full version
24+
import * as OpenCC from './dist/esm/cn2t.js'; // For Simplified to Traditional
25+
import * as OpenCC from './dist/esm/t2cn.js'; // For Traditional Chinese to Simplified Chinese
26+
</script>
1827
```
1928

2029
**Import opencc-js in Node.js script**
@@ -23,10 +32,18 @@ Import in HTML pages:
2332
npm install opencc-js
2433
```
2534

35+
CommonJS
36+
2637
```javascript
2738
const OpenCC = require('opencc-js');
2839
```
2940

41+
ES Modules
42+
43+
```javascript
44+
import * as OpenCC from 'opencc-js';
45+
```
46+
3047
## Usage
3148

3249
**Basic usage**
@@ -48,6 +65,51 @@ const converter = OpenCC.CustomConverter([
4865
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear
4966
```
5067

68+
Or using space and vertical bar as delimiter.
69+
70+
```javascript
71+
const converter = OpenCC.CustomConverter('香蕉 banana|蘋果 apple|梨 pear');
72+
console.log(converter('香蕉 蘋果 梨')); // output: banana apple pear
73+
```
74+
75+
**Add words**
76+
77+
* Use low-level function `ConverterFactory` to create converter.
78+
* Get dictionary from the property `Locale`.
79+
80+
```javascript
81+
const customDict = [
82+
['“', '「'],
83+
['”', '」'],
84+
['‘', '『'],
85+
['’', '』'],
86+
];
87+
const converter = OpenCC.ConverterFactory(
88+
OpenCC.Locale.from.cn, // Simplified Chinese (Mainland China) => OpenCC standard
89+
OpenCC.Locale.to.tw.concat([customDict]) // OpenCC standard => Traditional Chinese (Taiwan) with custom words
90+
);
91+
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
92+
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
93+
```
94+
95+
This will get the same result with an extra convertion.
96+
97+
```javascript
98+
const customDict = [
99+
['“', '「'],
100+
['”', '」'],
101+
['‘', '『'],
102+
['’', '』'],
103+
];
104+
const converter = OpenCC.ConverterFactory(
105+
OpenCC.Locale.from.cn, // Simplified Chinese (Mainland China) => OpenCC standard
106+
OpenCC.Locale.to.tw, // OpenCC standard => Traditional Chinese (Taiwan)
107+
[customDict] // Traditional Chinese (Taiwan) => custom words
108+
);
109+
console.log(converter('悟空道：“师父又来了。怎么叫做‘水中捞月’？”'));
110+
// output: 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
111+
```
112+
51113
**DOM operations**
52114

53115
HTML attribute `lang='*'` defines the targets.
@@ -82,6 +144,19 @@ HTMLConvertHandler.restore(); // Restore -> 漢語
82144
* default: `[]`
83145
* syntax : `[ ['item1','replacement1'], ['item2','replacement2'], … ]`
84146
* `.HTMLConverter(converter, rootNode, langAttrInitial, langAttrNew )` : uses previously defined converter() to converts all HTML elements text content from a starting root node and down, into the target local. Also converts all attributes `lang` from existing `langAttrInitial` to `langAttrNew` values.
85-
* `lang` attributes : html attribute defines the languages of the text content to the browser, at start (`langAttrInitial`) and after conversion (`langAttrNew`).
147+
* `lang` attributes : html attribute defines the languages of the text content to the browser, at start (`langAttrInitial`) and after conversion (`langAttrNew`).
86148
* syntax convention: [IETF languages codes](https://www.w3.org/International/articles/bcp47/#macro), mainly `zh-TW`, `zh-HK`, `zh-CN`, `zh-SG`,…
87-
* `ignore-opencc` : html class signaling an element and its sub-nodes will not be converted.
149+
* `ignore-opencc` : html class signaling an element and its sub-nodes will not be converted.
150+
151+
## Bundle optimization
152+
153+
* Tree Shaking (ES Modules Only) may result less size of bundle file.
154+
* Using `ConverterFactory` instead of `Converter`.
155+
156+
```javascript
157+
import * as OpenCC from 'opencc-js/core'; // primary code
158+
import * as Locale from 'opencc-js/preset'; // dictionary
159+
160+
const converter = OpenCC.ConverterFactory(Locale.from.hk, Locale.to.cn);
161+
console.log(converter('漢語'));
162+
```

0 commit comments

Comments
 (0)