npm package: @gdkf/tw-terminal
Description: > > 本节将介绍如何在项目中使用 @gdkf/tw-terminal 。 > 本章节主要介绍为 `beta` 版本新增的web键盘的使用方式，`0.1.6` 及之前版本文档内容请查阅： [http://hldev.kamfu.com.cn/kfui/2.6/tw.html#/@gdkf/tw-termina](http://hldev.kamfu.com.cn/kfui/2.6/tw.html#/@gdkf/tw-terminal)。
Latest version: 3.0.0-beta.5

# web输入法开发使用手册

## 开发指南
>
> 本节将介绍如何在项目中使用 @gdkf/tw-terminal 。
> 本章节主要介绍为 `beta` 版本新增的web键盘的使用方式，`0.1.6` 及之前版本文档内容请查阅： [http://hldev.kamfu.com.cn/kfui/2.6/tw.html#/@gdkf/tw-termina](http://hldev.kamfu.com.cn/kfui/2.6/tw.html#/@gdkf/tw-terminal)。

### 安装

推荐使用 npm 的方式安装，它能更好地和 webpack 打包工具配合使用。

```
// 设置npm源
npm config set registry https://registry.npmjs.org

// 下载beta版本（请集成最新web输入法beta版本）
npm install  @gdkf/tw-terminal@beta -S
```

### 引入 TwTerminal

#### 初始化
>
> 初始化配置请查阅【Options Attributes】章节

```js
//  main.js

import kfTw from '@gdkf/tw-terminal'
import '@gdkf/tw-terminal/lib/tw.css'

/**
 * 初始化 Web输入法·新 
 * @param {string} opts.type  类型，指定声明的输入法类型 指定输入法服务（默认值：http://ai.kffami.com:8880）
 **/
Vue.use(kfTw, {
  type: 2, // 声明类型： 0-多文 1-字库 2-web输入法（新发布版本）
  // 字典配置
  dictConfig: {
    // 拼音字典
    pinyin: {
        gd: ['广东', '广东省'] // [关键词]:[匹配项数组]
    }
  }
})

```

注意：

1. 输入法类型一经声明不可修改；
2. 金赋组件库支持版本： kfui-terminal(2.5.14) 及以上；
3. 新版输入法目前仅在beta版上发布，安装依赖需要带上@beta标识下载指定版本，该版本稳定运行后会更替lasets版本；

### 方法调用
>
> 输入法初始化后，会在Vue上挂载一个全局变量$tw，通过`this.$tw`可以访问到输入法实例。

示例：

```html
<template>
    <!--
        文本框支持的参数请查阅【Input Attributes】章节
        mode: 键盘支持的模式【必填】，具体支持的请查阅【Mode Attributes】章节
        title: 显示在键盘上方的标题【可选】，不传将默认不显示标题
    -->
    <input type="text" @click="show" mode="en" title="全部输入法">
</template>
<script>
export default {
    methods: {
        show(e) {
            // 触发显示输入法的目标元素（仅单行文本/多行文本框可以打开输入法）
            // 目标元素必须包含mode属性，标识输入框需要打开的输入模式，不传则视为无效输入框。
            const el = e.target
            this.$tw.show(el).then(res => {
                // 显示输入法 成功
                
            }).catch(err => {
                // 显示输入法 异常
            })
        }
    }
}
</script>
```

## Attributes & Methods

### Options Attributes
>
> web初始化时需要声明的属性

#### 通用配置

| 参数 | 说明 | 类型 | 可选值 | 默认值 | 版本支持 | 备注 |
|------|------|-----|--------|-------|---------|---------|
| type | 指定键盘类型 | number | 0,1,2 | 2 | * | 0-多闻键盘 <br/> 1-字库键盘 <br/> 2-web键盘·新<br/> |

#### web键盘配置
> >
> > 以下配置仅对于**字库键盘**、**web键盘**生效，从v3.0.0-beta.2开始支持

| 参数 | 说明 | 类型 | 可选值 | 默认值 | 版本支持 | 备注 |
|------|------|-----|--------|-------|---------|---------|
| service | 服务端地址 | string | — | <http://ai.kffami.com:8880> | * | 手写识别服务 |
| dictCover | 字典覆盖 | boolean | — | false | 3.0.0-beta.3 | true-覆盖字典 <br/> false-追加字典 |
| dictConfig | 字典配置 | Object | — | — | 3.0.0-beta.3 | 详阅【[字典配置](#字典配置)】章节 |

##### 字典配置
>
> 支持配置的字典如下

| 参数 | 说明 | 类型 | 可选值 | 默认值 | 版本支持 |
|------|------|-----|--------|-------|---------|
| pinyin | 拼音字典 | Object | — | — | * |

格式如下

```js
Vue.use(kfTw, {
  type: 2, // 声明类型： 0-多文 1-字库 2-web输入法（新发布版本）
  // 是否进行字典覆盖，
  // 为true时，新增的拼音字典会覆盖旧的字典，
  // 为false时，则在原本的字典中追加新增的匹配项
  dictCover: false,
  // 字典配置
  dictConfig: {
    // 拼音字典
    pinyin: {
        // [关键词]:[匹配项数组]，输入gd，会出现广东、广东省的匹配项
        gd: ['广东', '广东省']
    }
  }
})
```

#### 多闻键盘配置
>
> 以下配置仅对于**多闻键盘**生效

| 参数 | 说明 | 类型 | 可选值 | 默认值 | 版本支持 | 备注 |
|------|------|-----|--------|-------|---------|---------|
| url | 服务端地址 | string | — | ws://127.0.0.1:10086 | * | — |
| exePath | 应用路径 | string | — | C:\\DWIme\\dwCmd.exe | * | — |
| width | 窗口宽度 | number | — | 浏览器可视区域宽度 | * | — |
| height | 窗口高度 | number | — | 浏览器可视区域高度 | * | — |
| twWidth | 输入法宽度 | number | — | — | * | 不小于650 |
| twHeight | 输入法高度 | number | — | 400 | * | 不小于300 |
| animation | 是否启用动画效果 | number | 0,1 | 1 | * | 0-否 <br/> 1-是 |
| direction | 弹出动画方向 | number | 0,1,2 | 0 | * | 0-从下到上  <br/> 1-从左到右 <br/> 2-从右到左 |
| processName | 挤压应用名称 | string | — | — | * | — |

### Input Attributes
>
> 调用web输入法，文本框需要指定的配置

| 参数 | 说明 | 类型 | 可选值 | 默认值 | 版本支持 |
|------|------|-----|--------|-------|---------|
| mode | 输入模式（必填） | string | 请查阅【Mode Attributes】章节  | all | * |

### Mode Attributes
>
> 输入法支持的输入模式

| 参数 | 说明 | 版本支持 |
|------|------|------|
| all | 全部 | 3.0.0-beta.2 |
| cn | 汉字简体（包括拼音26键、手写输入法） | 同上 |
| en | 英文 | 同上 |
| symb | 特殊符号 | 同上 |

### Type Attributes
>
> 输入法支持的键盘类型

| 参数 | 说明 | 版本支持 |
|------|------|------|
| 0 | 多闻键盘 | * |
| 1 | 字库键盘 | 0.1.6 |
| 2 | web键盘 | 3.0.0-beta.2 |

### 方法

> 输入法初始化后，会在Vue上挂载一个全局变量$tw，通过`this.$tw`可以访问到输入法实例。

下面将会以element-ui作为demo，展示如何调用各个api

#### show
>
> 显示输入键盘

```js
this.$tw.show(el) 
```

```html
<template>
    <!--
        mode: 键盘支持的模式【必填】，具体支持的请查阅上文（web输入法支持的模式）
        title: 显示在键盘上方的标题【可选】，不传将默认不显示标题
    -->
    <input type="text" @click="show" mode="en" title="全部输入法">
</template>
<script>
export default {
    methods: {
        show(e) {
            // 触发显示输入法的目标元素（仅单行文本/多行文本框可以打开输入法）
            // 目标元素必须包含mode属性，标识输入框需要打开的输入模式，不传则视为无效输入框。
            const el = e.target
            this.$tw.show(el).then(res => {
                // 成功
                
            }).catch(err => {
                // 异常
            })
        }
    }
}
</script>
```

#### 关闭输入法
>
> 点击空白位置或者确定，即可关闭输入键盘。

#### getType
>
> 检测当前输入法类型  

```js
const type = this.$tw.getType()
console.log('当前输入法类型为：' + type) // 当前输入法类型为：2
```

#### init

```js
// type为需要重新初始化的输入法类型【必填】
this.$tw.init(type)
```

**<span style="color: red;">【慎用】</span> 仅建议在多闻输入法服务断开后，无法重新连接，需要重新初始化时使用；**  
**<span style="color: red;">【注意】</span> 除type外，其他配置将使用原配置项进行配置。**

```js
// 重新初始化为web输入法
this.$tw.init(2).then(res => {
    // 已成功初始化为web输入法
}).catch(err => {
    // 初始化失败
})
```

### 其他

- 当前版本，初始化多闻输入法（即 type:0）失败时，默认重连 5次（尝试失败后间隔5秒重新尝试） 如果无法连上，默认转为初始化新版web输入法（type:2）；
- 类型参数异常时，默认转为初始化新版web输入法；