@kkopite/mi

集成一些开发米家拓展程序时的一些操作

@kkopite/mi

米家开发中一些常见操作命令行工具

安装

npm install -g @kkopite/mi

word转化为markdown

你需要先了解下markdown的基础语法

一般来说，客户提供的隐私、用户协议均为word文档，我们需要转化为markdown文件，才能上传到后台。

我们可以使用该工具来解决：

# 首先进入到隐私、用户协议的word文档所在的文件夹内
cd ./path/to/word/dircotry

# 执行该命令，会将该目录下所有的word文档转化为markdown文件
mi -c

这里的word转化为markdown文件实际上用到了mammoth这个库，可以参考文档看看该工具的使用场景和局限性。

• :warning: 该工具并不能完美地进行转化，转化后的文件会有一些小问题，因此你需要手动编辑微调生成的markdown文件，预览效果看是否正常(可以使用vscode自带的浏览功能查看markdown文件渲染后的显示效果)
• 提供的word文档必须是.docx格式的，否则无法进行转化
• 你需要注意英文文档中，是否有中文内容（如编号一、二、三等等）
• 你需要手动给生成的文档中的邮件、电话号码加上相应标签、使其有超链接功能，如下：

- 电子邮件：123456789@qq\.com
+ 电子邮件：<a href="mailto:[email protected]">123456789@qq\.com</a>

- 电话：13912345678
+ 电话：<a href="tel:13912345678">13912345678</a>

打包

正常我们使用米家sdk提供的打包命令：

npm run publish com.xiaomi.demo

需要我们手动去敲打com.xiaomi.demo等项目的目录，就比较麻烦。这里我们提供一个命令来封装如上的打包：

cd /path/to/miot-plugin-sdk-10074

mi -p

该命令会输出该项目所有的插件列表，然后你可以通过上下移动选择要打包的插件，点击回车即可执行打包命令。这样就避免手动拼写输入插件包名

配置

由于米家插件的一些规范，例如设置页面的“智能场景”需要根据实际情况进行显示，而往往开发时会忽略这点，因此这里提供一个功能，允许编写一些配置文件在打包前进行检查，一一确认后才会进行打包。

你需要再根目录上创建mi.config.js文件，然后配置你的检查规则即可：

/**
 * @typedef ValidError
 * @type {object}
 * @property include {string[]} - 需要检查的项目，空数组即全部检查
 * @property excluce {string[]} - 排除检查的项目
 * @property text {string|string[]|((name: string, projectPath: string) => string|string[])} - 错误提示
 * @property [valid] {(name: string, projectPath: string) => boolean}
 */

/**
 * @type {ValidError[]}
 */
export default [

]

规则如下：

interface ValidError {
  /**
   * 默认或者返回true表示需要提示文案确认
   */
  valid?: (name: string, projectPath: string) => boolean
  /**
   * 提示文案
   */
  text: string | string[] | ((name: string, projectPath: string) => string | string[])
  /**
   * 默认为空数组，表示所有项目都需要检查，写项目名即可
   */
  include?: string[]
  /**
   * 表示排除在外的项目，写项目名
   */
  exclude?: string[]
}

多语言文本输出

该功能假设你使用模板提供的i18n框架来开发，如果不是的话，请不要使用该功能

对于开发者来说，改动json文档不会有太大的心智负担，但对于其他人来说就不一定了。特别的我们将中文文案提供给客户或第三方翻译，让他们编写提供一份英文的或其他语言的json文本，就有可能给他们造成比较大的心智负担。

通过该功能，可以将所有的语言json文件整合，生成一个excel文件，这样他们编辑起来就很容易了。

例如你有两份语言的json文件：

::: code-group

// en.json
{
  "hello": "hello"
}

// zh.json
{
  "hello": "你好",
  "name": "卡卡普特"
}

:::

执行如下指令

# --src 指定json文件所在的文件目录
# --dst 指定生成的excel文件的路径，./表示在当前目录
mi -t --src=./path/to/i18n --dst=./

会生成如下内容的excel表格文件

|key|zh|en| |:--:|:--:|:--:| |hello|你好|hello| |name|卡卡普特||

如果你的目录中还有其他语言的json文件，如ko.json，则生成的表格中会增加ko一列，表示韩语

将生成后的excel文件交给翻译人员，他们经过翻译了后，变成如下内容：

|key|zh|en| |:--:|:--:|:--:| |hello|你好|hello| |name|卡卡普特|kkopite|

增加了name的英文翻译

然后我们执行如下命令：

# 这里的src为翻译人员编辑后的excel表格路径
# dst为上面指定json所在的目录
mi -t --src=./path/to/translate.xlsx --dst=./path/to/i18n

该命令会将excel表格的内容同步转为对应的json文本，避免我们手动从excel表格中复制粘贴文案到json文件：

::: code-group

// en.json
{
  "hello": "hello",
  "name": "kkopite" // [!code ++]
}

// zh.json
{
  "hello": "你好",
  "name": "卡卡普特"
}

::: warning 警告

• 注意不要改动生成的excel表格的结构(只要在对应词条对应语言上填写翻译就行)，否则可能导致编辑后无法同步会json文本
• 为了避免同步json文本的时候发生不可预知的错误，请在执行同步命令前先提交项目的代码到svn或git仓库，以免代码丢失 :::

License

MIT License © 2021 kkopite