鸿蒙——实操开发自定义Hivigor插件并发布插件

hvigor主要提供了两种方式来实现插件

（1）基于hvigorfile脚本开发插件。

（2）基于typescript项目开发。

一、基于hvigorfile脚本开发

基于hvigorfile.ts脚本开发的方式，其优点是可实现快速开发，直接编辑工程或者模块下hvigorfile.ts即可编写插件代码，不足之处是在多个项目中，无法方便的进行插件代码的复用和共享开发。

1、导入模块依赖，更多接口参考扩展构建API。

// 导入接口
import { HvigorPlugin, HvigorNode } from '@ohos/hvigor';

2、编写插件代码。

在hvigorfile.ts中定义插件方法，实现HvigorPlugin接口。

// 实现自定义插件
function customPlugin(): HvigorPlugin {
    return {
        pluginId: 'customPlugin',
        apply(node: HvigorNode) {
            // 插件主体
            console.log('hello customPlugin!');
        }
    }
}

3、在导出声明中使用插件

export default {
    system: appTasks,
    plugins:[
        customPlugin()  // 应用自定义Plugin
    ]
}

4、执行hvigor命令。

执行hvigor命令时，在hvigor生命周期配置阶段执行插件中的apply方法。

下面咱们按照上面的步骤操作一下：

二、实操（基于hvigorfile脚本开发）

1、创建一个新的工程，比如命名ProjectName为 MyPluginProject

2、在新的项目工程的工程目录下找到hvigorfile.ts文件，打开该文件按上述步骤进行编辑

3、在Terminal中执行hvigorw --sync命令

可以在控制台看到我们在自定义插件customPlugin中通过console打印的log："hello customPlugin!"，这样自定义插件就完成，是不是so easy。如果想实现你自己的逻辑，你可以在自定义插件的 apply里面编写。

弊端：第一种方法到这里就介绍完了，看起来很简单，不过我们在实际开发中，如果所有的自定义插件都是以这种方式编写在hvigorfile.ts文件中，会导致hvigorfile.ts中代码量很大，易读性差，而且有多个工程项目想用同一个插件，还得把代码拷贝来拷贝去，很繁琐，所以咱们下面介绍第二种方法。

三、基于typescript项目开发

基于typescript项目开发较好地弥补了上一小节中使用hvigorfile脚本方式编写插件代码不易复用和共享分发的问题。因此通常情况下推荐此方式开发。

1、初始化typescript项目

（1）创建一个空目录。

在命令行工具中使用cd命令进入空目录下。

（2）安装typescript模块。

// 全局安装TypeScript
npm install typescript -g

（3）初始化npm项目

执行如下命令，根据命令行指示配置项目。

// 初始化一个npm项目
npm init

（4）生成typescript配置文件。

执行如下命令生成tsconfig.json文件。

// 初始化TypeScript配置文件
tsc --init

（5）typescript项目初始化完成。

2、开发插件

（1）配置npm镜像仓库地址。

在用户目录下创建或打开.npmrc文件，配置如下信息：

registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/

（2）添加依赖声明。

打开package.json 添加devDependencies配置。

"devDependencies": {
    "@ohos/hvigor": "5.2.2"
}

（3）安装依赖

执行如下命令安装依赖。

npm install

（4）编写插件代码。

创建 custom-plugin.ts文件，编写插件代码。

import { HvigorNode, HvigorPlugin } from '@ohos/hvigor';

export function customPlugin(): HvigorPlugin {
    return {
        pluginId: 'customPlugin',
        apply(node: HvigorNode) {
            console.log('hello customPlugin!');
        }
    }
}

（5）创建index.ts文件，并在该文件中声明插件方法的导出。

export { customPlugin } from './src/plugin/custom-plugin';

3、发布插件

typescript项目本质上是一种npm项目，插件发布流程遵循npm发布规范。

发布npm包流程：

（1）配置registry。

在用户目录下创建.npmrc文件，配置您需要发布的镜像仓库。

registry=[npm镜像仓库地址]

（2）生成AccessToken。

执行如下命令，注册并登录npm仓库，在用户目录下.npmrc文件中自动生成token信息。

npm login

（3）发布nmp包

执行如下命令，将npm项目打包并发布至镜像仓库。

npm publish

4、使用插件

（1）添加依赖。

在工程下hvigor/hvigor-config.json5中添加自定义插件依赖，依赖项支持离线插件配置。

 "dependencies": {
    "custom-plugin": "1.0.0"   // 添加自定义插件依赖
  }

（2）安装依赖

方式1：执行编辑区右上角Install Now 或执行菜单File->Sync and Refresh Project进行工程Sync后，DevEco Studio将会根据hvigor-config.json5中的依赖配置自动安装。
方式2：使用hvigorw命令行工具执行任一命令，命令行工具会自动执行安装构建依赖。
```
hvigorw --sync
```

（3）导入插件。

根据插件编写时基于的node节点，确定导入的节点所在的hvigorfile.ts文件，在hvigorfile.ts中导入插件。

import { customPlugin } from 'custom-plugin';

（4）使用插件

将自定义插件添加到export default的plugins中。

export default {
    system: appTasks,
    plugins:[
        customPlugin()  // 应用自定义插件
    ]
}

四、实操（基于typescript项目开发）

1、按照以上步骤，我们首先要创建一个空目录，这里我们以「修改产物的artifictName」插件为例，我们创建一个名称为：renameAppNamePlugin的文件夹，在命令行使用cd命令进入空目录下

2、安装typescript模块，执行以下命令：

// 全局安装TypeScript
npm install typescript -g

3、初始化npm项目。

// 初始化一个npm项目
npm init

初始化完后，控制台输出了这些。第一次看到这里有点懵，不知道该怎么办?后来百度了下：

看官网的描述：

说是「根据命令行指示配置项目」。后来实操了下才知道，这里可以一路按回车：

继续一路按回车，直到出现「Is this OK？（yes）」，这时候，输入yes，继续按一下回车：

根据控制台的描述，应该是在renameAppNamePlugin文件夹下创建了个package.json，其中package.json的内容已经给创建好了，就是刚才咱们一路回车那堆东西：

这时候看下工程下是不是在renameAppNamePlugin文件夹下多了个package.json文件：

果然是这样。

4、生成typescript配置文件
执行如下命令生成tsconfig.json文件。

// 初始化TypeScript配置文件
tsc --init

执行完后，在 renameAppNamePlugin文件夹下又多了一个tsconfig.json文件：

5、开发插件

（1）配置npm镜像仓库地址。

在用户目录下创建或打开.npmrc文件，配置如下信息：

registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/

我是在工程目录下直接创建了.npmrc文件

（2）添加依赖声明

打开package.json添加devDependencies配置。

"devDependencies": {
    "@ohos/hvigor": "5.2.2"
}

（3）安装依赖

执行如下命令安装依赖。

npm install

（4）编写插件代码

创建 renameApp-plugin.ts文件，编写插件代码：

import { HvigorNode, HvigorPlugin } from '@ohos/hvigor';

export function renameAppPlugin(): HvigorPlugin {
    return {
        pluginId: 'renameAppPlugin',
        apply(node: HvigorNode) {
            console.log('hello renameAppPlugin!');
        }
    }
}

（5）导出插件

创建index.ts文件，并在该文件中声明插件方法的导出

export { renameAppPlugin } from './renameApp-plugin';

6、发布插件

（1）配置registry

在用户目录下创建.npmrc文件，配置您需要发布的镜像仓库

registry=[npm镜像仓库地址]

该步骤上面已经弄过了，直接忽略即可。

（2）生成AccessToken

执行如下命令，注册并登录npm仓库，在用户目录下.npmrc文件中自动生成token信息。

npm login

这个时候摁下回车，会自动用浏览器打开npm仓库的网址。我们摁下回车：
因为我已经注册过了，所以弹出这个输入一次性密码的页面（密码会发送到你注册时候填写的邮箱中）。没注册过的同学可以先注册一个账号。

登录成功。

我们点「Go to home page」按钮，就跳转进入了npm仓库的主页了，如下：

这里有很多别人发布的插件，怎样看下我自己发布的插件？，点击这个：

然后就可以看到我自己之前发布的插件了：

现在我们要执行命令，把刚才的renameAppPlugin也发布到这里。

（3）发布npm包

执行如下命令，将npm项目打包并发布至镜像仓库。

npm publish

执行npm publish 命令成功后，我们就可以在nmp仓库中看到自己上传的插件了

看着名称不太友好，是吧，好的换个名字：
需要把这里改动一下。

注意：这里名字命名不让大写，如果大写会用红色波浪线提示，但是可以用下划线。

我们换成：@shetianjian/rename_app

好了，我们重新执行 npm publish命令

这个时候报错了：

于是赶紧用DeepSeek查了下，这是DeepSeek给出的解释：

这就解释了之前没改名字时能发布成功，改完名字后再发布就报这个错了，原来之前的名字不是@your-username/package-name,npm不会认为是私有包，所以可以发布成功。改为@shetianjian/rename_app后，会被认为是私有包。

只能说DeepSeek真的太强了👍🏻

再看下DeepSeek给出的解决方案：

最后，我们按这个来一下试试：

改完后，接着重新执行npm publish命令，果然成功了：

每次发布成功，邮箱都会给你发邮件通知：

其他npm publish报错：

npm publish 报错：npm notice Publishing to https://registry.npmjs.org/ with tag latest and default access
npm error code E403
npm error 403 403 Forbidden - PUT https://registry.npmjs.org/plugin - You do not have permission to publish "plugin". Are you logged in as the correct user?
npm error 403 In most cases, you or one of your dependencies are requesting
npm error 403 a package version that is forbidden by your security policy, or
npm error 403 on a server you do not have access to.
npm error A complete log of this run can be found in: /Users/she/.npm/_logs/2025-03-05T08_16_36_217Z-debug-0.log

好了，上述发布插件流程说完了。接下来是怎样使用发布的插件。

7、使用插件

（1）添加依赖