更新记录

1.0.0（2025-12-29） 下载此版本

• 新增：System UI（沉浸式开关、状态栏/导航栏颜色、系统栏高度获取）
• 新增：相册选择（单图/多图/视频），兼容不同系统版本返回字段差异
• 新增：蓝牙 BLE（扫描、设备发现、连接/断开）
• 新增：权限检查/申请、跳转系统设置引导
• 新增：单次定位、网络能力、震动能力
• 优化：插件 ID 变更为 neo-harmony-native 以符合 DCloud 20 字符限制
• 优化：重构 README 文档，增加全模块 API 示例及真机测试说明
• 优化：为 Demo 示例代码添加详尽中文注释

平台兼容性

uni-app(4.86)

Neo Harmony Native

鸿蒙 NEXT 原生能力增强套件 (UTS)

Neo Harmony Native 是专为 HarmonyOS NEXT (纯血鸿蒙) 打造的高性能原生能力增强插件。它通过 UTS 技术深度封装了鸿蒙系统底层 API，为 uni-app / uni-app x 开发者提供了一套稳定、易用、专业的原生能力扩展方案。

🚀 核心特性

• 💎 系统 UI 适配：深度控制状态栏、导航栏颜色及沉浸式模式，完美适配鸿蒙视觉规范。
• 🛡️ 权限管理：标准化的权限检查与申请流程，内置跳转系统设置引导，提升用户体验。
• 📱 设备信息：获取详尽的硬件参数、电量状态、网络类型等，助力精细化运营。
• ⚡ 触感反馈：提供多种预设震动模式（Touch/Success/Warning/Error），增强交互质感。
• 📍 地理位置：支持高精度单次定位，无缝衔接鸿蒙位置服务。
• 🌐 网络能力：实时获取网络承载类型及连接状态。
• 🖼️ 媒体选择：专业级相册选择器，支持图片/视频单选与多选，兼容不同系统版本。
• 📡 蓝牙 BLE：完整的低功耗蓝牙扫描、发现、连接流程，性能稳定可靠。

📦 安装与配置

1. 导入插件

• 在 DCloud 插件市场 搜索并点击“使用 HBuilderX 导入”。
• 或手动下载解压至项目的 uni_modules/neo-harmony-native/ 目录。

2. 鸿蒙环境配置

本插件已内置必要的权限声明。若需自定义，请检查插件目录下的 utssdk/app-harmony/module.json5。

[!IMPORTANT] 纯血鸿蒙适配提醒：

1. 涉及用户隐私的权限（如定位、蓝牙扫描）必须在运行时动态申请。
2. 建议在真机环境下测试，模拟器可能无法模拟震动、蓝牙等硬件行为。
3. 本插件已在 Meta 70 Pro 真机测试通过，如有问题，请留言反馈。

🎮 快速体验 (内置 Demo)

我们为开发者准备了全功能的演示页面，您可以直接在项目中引用并运行：

Demo 路径：uni_modules/neo-harmony-native/demo/demo.vue

快速接入示例：

<template>
  <demo-component />
</template>

<script>
import DemoComponent from '@/uni_modules/neo-harmony-native/demo/demo.vue'
export default {
  components: { DemoComponent }
}
</script>

📖 API 文档概览

统一返回结构 Result<T>

为了保证代码的健壮性，插件大部分 API 遵循统一的返回规范：

type Result<T> = {
  errCode: number | string; // 0 为成功，其余为错误码
  errMsg: string;           // 错误描述
  data: T | null;           // 业务数据
  rawData?: any;            // 系统原始返回对象（用于排查底层问题）
}

模块示例

系统 UI (System UI)

import { setImmersive, setBarColor, getSystemBarHeights } from '@/uni_modules/neo-harmony-native'

// 开启沉浸式
setImmersive(true)

// 设置状态栏颜色
setBarColor({ 
  contentColor: 'dark', 
  backgroundColor: '#00000000' 
})

// 获取系统栏高度
const { statusBarHeight, navigationBarHeight } = getSystemBarHeights()

设备信息 (DeviceInfo)

import { getNativeDeviceInfo } from '@/uni_modules/neo-harmony-native'

const res = getNativeDeviceInfo()
if (res.errCode === 0) {
  console.log('系统版本：', res.data.osFullName)
  console.log('设备型号：', res.data.deviceModel)
  console.log('电量：', res.data.batteryLevel + '%')
}

权限管理 (Permissions)

import { checkPermission, requestPermission, gotoSystemSetting } from '@/uni_modules/neo-harmony-native'

// 检查相机权限
const checkRes = checkPermission('ohos.permission.CAMERA')
if (checkRes.data === false) {
  // 申请权限
  const reqRes = await requestPermission('ohos.permission.CAMERA')
  if (reqRes.errCode === 'PermissionDenied') {
    // 引导用户去设置页
    gotoSystemSetting()
  }
}

媒体选择 (Picker)

import { pickImage, pickImages, pickVideo } from '@/uni_modules/neo-harmony-native'

// 选择单张图片
const res = await pickImage()
if (res.errCode === 0) {
  console.log('图片路径：', res.data.uri)
}

地理位置 (Location)

import { getCurrentLocation } from '@/uni_modules/neo-harmony-native'

const res = await getCurrentLocation()
if (res.errCode === 0) {
  console.log('经纬度：', res.data.latitude, res.data.longitude)
}

网络能力 (Network)

import { getNetCapabilities } from '@/uni_modules/neo-harmony-native'

const res = getNetCapabilities()
if (res.errCode === 0) {
  console.log('网络类型：', res.data.networkType) // wifi/cellular/none
}

触感反馈 (Haptics)

import { triggerVibration } from '@/uni_modules/neo-harmony-native'

// 触发成功反馈震动
triggerVibration('success')

蓝牙 (BLE)

import { onDeviceFound, startBleScan, stopBleScan } from '@/uni_modules/neo-harmony-native'

// 监听设备发现
onDeviceFound((device) => {
  console.log('发现设备：', device.name, device.address)
})

// 开始扫描
await startBleScan()

❌ 常见错误码 (FAQ)

📄 开源协议

本项目遵循 MIT License 协议。

Neo Harmony 系列 —— 为鸿蒙生态提供最专业的 uni-app 解决方案。