doc and demo (#3)

rimeinn · Dec 22, 2024 · 15ccf53 · 15ccf53
1 parent a3087af
commit 15ccf53
Show file tree

Hide file tree

Showing 15 changed files with 183 additions and 3 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -56,4 +56,4 @@ jobs:
           prerelease: true
           title: "Nightly Build"
           files: |
-            fcitx5-rime.js-*.tgz
+            fcitx5-rime-*.tgz
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,4 @@ pnpm-lock.yaml
 *.bz2
 *.tgz
 *.zip
+.cache
diff --git a/README.md b/README.md
@@ -0,0 +1,56 @@
+# fcitx5-rime.js
+为你的网站添加 Rime 和任意方案
+
+## 使用
+本项目适用于方案发布者，不适用于普通用户。
+
+您不需要自行编译本仓库的代码，只需要下载编译好的 [fcitx5-rime](https://github.com/rimeinn/fcitx5-rime.js/releases) 包。
+
+## 准备方案
+出于性能考虑，您应该提供已构建的二进制方案，而不是原始方案。
+
+以雾凇拼音为例，在成功部署后进入用户目录，用 zip 命令将运行时所用的文件打包：
+
+```sh
+zip -r rime-ice.zip build lua opencc custom_phrase.txt
+```
+注意您的方案可能不含 lua、opencc 或是自定义词组，或者带有 rime.lua，或者带有模型文件或预测词库，需要您自行调整命令。
+
+不要添加任何 yaml 文件。
+
+将得到的 zip 文件放在网站的某个位置，记录 URL。
+
+## 手动引用
+适用于直接编辑 HTML 的原始前端项目。
+
+将 fcitx5-rime 的 tgz 包解压，将解压后的 package/dist 中的以下文件放在网站的同一个目录下：
+* Fcitx5.js
+* Fcitx5.wasm
+* libFcitx5Config.so
+* libFcitx5Core.so
+* libFcitx5Utils.so
+
+在 `<script type="module">` 中引用 Fcitx5.js 并导入方案 zip 文件，见 [index.html](./index.html)。
+
+当 `loadZip` 的 `Promise` 完成时，您的方案即可在网页的 `input` 和 `textarea` 正常工作（前提是系统的输入法处于英文状态）。
+
+## npm 引用
+适用于 npm 管理的现代前端项目。
+
+将 fcitx5-rime 的 tgz 包放在项目的某个位置，使用 `pnpm install /path/to/tgz` 直接从本地安装。
+
+安装完成后您的 package.json 应有如下一行
+```
+"fcitx5-rime": "file:*fcitx5-rime-*.tgz"
+```
+
+如果您配置了 CI，可以考虑将 tgz 排除在 git 外，并在 CI 中加入下载 tgz 的命令。
+
+为了使 wasm 在测试和部署时都能正确加载，您需要做一些额外配置。
+以 vite 为例，在 [vite.config.ts](./demo/vite.config.ts) 中加入
+```js
+optimizeDeps: {
+  exclude: ['fcitx5-rime'],
+},
+```
+后，`pnpm run dev` 可以正常加载 wasm。配合 [vite-plugin-static-copy](https://github.com/sapphi-red/vite-plugin-static-copy) 可以使 `pnpm run build` 正常打包 wasm。
diff --git a/demo/index.html b/demo/index.html
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>Fcitx5 Rime</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/main.ts"></script>
+  </body>
+</html>
diff --git a/demo/package.json b/demo/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "demo",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "@vue/tsconfig": "^0.7.0",
+    "fcitx5-rime": "file:../fcitx5-rime-0.1.0.tgz",
+    "typescript": "~5.6.2",
+    "vite": "^6.0.3",
+    "vite-plugin-static-copy": "^2.2.0",
+    "vue": "^3.5.13",
+    "vue-tsc": "^2.1.10"
+  }
+}
diff --git a/demo/src/App.vue b/demo/src/App.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { loadZip } from 'fcitx5-rime'
+
+loadZip('./rime-ice.zip')
+</script>
+
+<template>
+  <textarea></textarea>
+</template>
+
+<style scoped>
+textarea {
+  width: 400px;
+  height: 200px;
+}
+</style>
diff --git a/demo/src/main.ts b/demo/src/main.ts
@@ -0,0 +1,4 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')
diff --git a/demo/src/vite-env.d.ts b/demo/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/demo/tsconfig.app.json b/demo/tsconfig.app.json
@@ -0,0 +1,14 @@
+{
+  "extends": "@vue/tsconfig/tsconfig.dom.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
+}
diff --git a/demo/tsconfig.json b/demo/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
diff --git a/demo/tsconfig.node.json b/demo/tsconfig.node.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}
diff --git a/demo/vite.config.ts b/demo/vite.config.ts
@@ -0,0 +1,23 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+
+const wasmPath = 'node_modules/fcitx5-rime/dist/'
+
+// https://vite.dev/config/
+export default defineConfig({
+  base: '',
+  optimizeDeps: {
+    // Don't pre-bundle it to node_modules/.vite/deps as wasm won't be copied there.
+    exclude: ['fcitx5-rime'],
+  },
+  plugins: [
+    vue(),
+    viteStaticCopy({
+      targets: ['Fcitx5.js', 'Fcitx5.wasm', 'libFcitx5Config.so', 'libFcitx5Core.so', 'libFcitx5Utils.so'].map(file => ({
+        src: wasmPath + file,
+        dest: 'assets'
+      })),
+    })
+  ]
+})
diff --git a/package.json b/package.json
@@ -1,8 +1,9 @@
 {
-  "name": "fcitx5-rime.js",
+  "name": "fcitx5-rime",
   "version": "0.1.0",
   "description": "Fcitx5 Rime as a JavaScript library",
   "type": "module",
+  "main": "dist/Fcitx5.js",
   "files": [
     "dist"
   ],

diff --git a/scripts/prepack.sh b/scripts/prepack.sh
@@ -5,4 +5,4 @@ mkdir -p dist
 
 cp build/sysroot/usr/lib/libFcitx5* dist
 cp build/fcitx5-js/src/Fcitx5.* dist
-cp fcitx5-js/page/Fcitx5.d.ts dist
+cat fcitx5-js/page/Fcitx5.d.ts src/fcitx5-rime.d.ts > dist/Fcitx5.d.ts
diff --git a/src/fcitx5-rime.d.ts b/src/fcitx5-rime.d.ts
@@ -0,0 +1 @@
+export function loadZip(url: string): Promise<void>
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,3 +6,4 @@ pnpm-lock.yaml @@
     *.bz2
     *.tgz
     *.zip
+    .cache
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		export function loadZip(url: string): Promise<void>