在 HarmonyOS 生态中，原子化服务是区别于传统 APP 的全新形态 —— 无需安装、即搜即用、轻量化部署，用户可通过鸿蒙桌面、负一屏、搜索栏等多个入口快速调用核心功能（如 “扫码支付”“天气查询”“文件转换”）。本文将以 “PDF 转 Word 工具” 为例，拆解原子化服务的开发逻辑、工程配置、功能实现与部署流程，帮助开发者快速入局鸿蒙原子化服务生态。

一、原子化服务核心认知：3 个关键特性与适用场景

1. 核心特性：与传统 APP 的本质区别

2. 适用场景：哪些功能适合做成原子化服务？

原子化服务的核心是 “高频、轻量化、单一功能”，典型场景包括：

• 工具类：PDF 转换、二维码生成 / 识别、单位换算、计算器；
• 服务类：外卖点单、电影订票、打车叫车、快递查询；
• 内容类：新闻快讯、天气查询、股票行情、赛事直播。
• 本文案例：选择 “PDF 转 Word 工具” 作为开发目标，满足 “单一功能、高频使用、轻量化” 特点，适合原子化服务形态。

二、开发前准备：环境配置与工程创建

1. 环境要求

• DevEco Studio：4.1 及以上版本（支持原子化服务工程模板）；
• HarmonyOS SDK：API 9 及以上（包含原子化服务核心模块@ohos.ability.featureAbility）；
• 测试设备：HarmonyOS 3.0 及以上版本的手机 / 平板（支持原子化服务运行）。

2. 创建原子化服务工程

1. 打开 DevEco Studio，点击 “Create Project”，选择 “Atomic Service” 模板（原子化服务专用模板）；
2. 配置项目信息：
3. 点击 “Finish”，等待工程构建完成（原子化服务工程默认包含 “免安装配置”“入口配置” 等核心文件）。

3. 核心工程结构说明

原子化服务工程与传统 APP 工程的核心区别在于module.json5配置和入口能力，关键文件结构如下：

plaintext

PDFToWordService/
├─ src/main/ets/
│  ├─ abilities/
│  │  └─ PDFToWordAbility.ets  // 原子化服务入口能力（替代传统APP的EntryAbility）
│  ├─ pages/
│  │  └─ Index.ets             // 核心功能页面（PDF上传+转换+下载）
│  └─ utils/
│     └─ PDFConverter.ets      // PDF转Word核心工具类
└─ src/main/module.json5       // 原子化服务配置（关键：免安装、入口类型）

三、实战开发：PDF 转 Word 原子化服务完整实现

本次开发的原子化服务包含 3 个核心功能：

1. 本地 PDF 文件选择（调用系统文件选择器）；
2. PDF 转 Word（基于鸿蒙原生文件解析 API）；
3. 转换结果下载（保存到本地文件目录）。

第一步：配置原子化服务核心参数（module.json5）

原子化服务需在module.json5中配置 “免安装”“入口类型”“权限” 等关键参数，否则无法正常运行：

json

{
  "app": {
    "bundleName": "com.example.pdf2wordservice",
    "versionName": "1.0.0",
    "versionCode": 1000000,
    "minAPIVersion": 9
  },
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntry": "./ets/abilities/PDFToWordAbility.ets",
    "description": "$string:module_description",
    "mainElement": "com.example.pdf2wordservice.PDFToWordAbility",
    "deviceTypes": ["phone"],
    "abilities": [
      {
        "name": ".PDFToWordAbility",
        "type": "feature", // 原子化服务核心类型：功能型能力
        "visible": true, // 对外可见（允许系统/其他应用调用）
        "exported": true, // 可导出（支持免安装调用）
        "skills": [
          {
            "entities": ["entity.system.home"], // 支持桌面入口（可添加到桌面）
            "actions": ["action.system.home"]
          },
          {
            "entities": ["entity.system.search"], // 支持搜索入口（可通过系统搜索找到）
            "actions": ["action.system.search"]
          }
        ],
        "orientation": "portrait" // 竖屏显示
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_USER_STORAGE", // 读取本地文件权限
        "reason": "需要读取本地PDF文件",
        "usedScene": { "when": "inuse" }
      },
      {
        "name": "ohos.permission.WRITE_USER_STORAGE", // 写入本地文件权限
        "reason": "需要保存转换后的Word文件",
        "usedScene": { "when": "inuse" }
      }
    ],
    "deliveryWithInstall": false, // 关键：免安装（无需安装即可运行）
    "installationFree": true // 声明为原子化服务（系统识别标记）
  }
}

第二步：实现 PDF 转 Word 核心工具类（PDFConverter.ets）

基于鸿蒙原生文件解析 API，封装 PDF 转 Word 逻辑（简化实现，核心演示流程）：

typescript

运行

import fileio from '@ohos.fileio';
import fs from '@ohos.file.fs';

export class PDFConverter {
  /**
   * PDF转Word核心方法
   * @param pdfPath 本地PDF文件路径
   * @param outputPath Word文件输出路径
   * @returns 转换结果（成功/失败）
   */
  static async convertPDFToWord(pdfPath: string, outputPath: string): Promise<boolean> {
    try {
      // 1. 读取PDF文件（简化：实际需解析PDF格式，此处模拟转换过程）
      const pdfFile = await fs.open(pdfPath, fs.OpenMode.READ_ONLY);
      const pdfContent = await fs.read(pdfFile.fd, { offset: 0, length: 1024 * 1024 }); // 读取1MB内容（模拟）
      await fs.close(pdfFile);

      // 2. 模拟PDF转Word（实际项目需集成PDF解析库，如iText、Apache PDFBox的鸿蒙适配版）
      const wordContent = `PDF转换结果：\n${new TextDecoder().decode(pdfContent.buffer)}`;

      // 3. 写入Word文件（.docx格式，简化实现）
      const wordFile = await fs.open(outputPath, fs.OpenMode.WRITE_ONLY | fs.OpenMode.CREATE);
      await fs.write(wordFile.fd, new TextEncoder().encode(wordContent));
      await fs.close(wordFile);

      return true;
    } catch (error) {
      console.error("PDF转Word失败：", error);
      return false;
    }
  }

  /**
   * 生成Word文件输出路径（保存在用户文档目录）
   * @param pdfName PDF文件名（不含后缀）
   * @returns Word文件完整路径
   */
  static async generateOutputPath(pdfName: string): Promise<string> {
    // 获取用户文档目录（鸿蒙沙箱路径，无需权限申请）
    const docDir = await fs.getOrCreateDistributedDir(fs.UserDir.DOCUMENTS);
    return `${docDir}/${pdfName}_converted.docx`;
  }
}

第三步：开发核心功能页面（Index.ets）

实现 “文件选择→转换→下载” 的完整交互流程，UI 采用轻量化设计（符合原子化服务 “简洁高效” 原则）：

typescript

运行

import router from '@ohos.router';
import promptAction from '@ohos.promptAction';
import featureAbility from '@ohos.ability.featureAbility';
import { PDFConverter } from '../utils/PDFConverter';
import fs from '@ohos.file.fs';

@Entry
@Component
struct PDFToWordPage {
  @State pdfPath: string = ""; // 选中的PDF文件路径
  @State isConverting: boolean = false; // 转换中状态
  @State convertResult: string = ""; // 转换结果提示

  build() {
    Column({ space: 30 }) {
      // 标题
      Text("PDF转Word工具")
        .fontSize(26)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 50 })

      // 文件选择区域
      Column({ space: 15 }) {
        Button(this.pdfPath ? `已选择：${this.getFileName(this.pdfPath)}` : "选择本地PDF文件")
          .width('80%')
          .height(55)
          .backgroundColor(this.pdfPath ? "#00C853" : "#007AFF")
          .fontSize(18)
          .onClick(() => this.selectPDFFile())

        // 转换按钮（仅选中文件后可点击）
        Button("开始转换")
          .width('80%')
          .height(55)
          .backgroundColor("#FF9800")
          .fontSize(18)
          .enabled(this.pdfPath !== "" && !this.isConverting)
          .onClick(() => this.startConversion())

        // 转换结果提示
        Text(this.convertResult)
          .fontSize(14)
          .color(this.convertResult.includes("成功") ? Color.Green : Color.Red)
      }

      // 下载按钮（转换成功后显示）
      if (this.convertResult.includes("成功")) {
        Button("下载Word文件")
          .width('80%')
          .height(55)
          .backgroundColor("#2196F3")
          .fontSize(18)
          .onClick(() => this.downloadWordFile())
      }
    }
    .width('100%')
    .height('100%')
    .backgroundColor("#F5F7FA")
  }

  /**
   * 调用系统文件选择器，选择PDF文件
   */
  async selectPDFFile() {
    try {
      // 配置文件选择器：仅允许选择PDF格式
      const selectOptions = {
        type: featureAbility.FileSelectType.FILE,
        suffix: [".pdf"],
        title: "选择PDF文件"
      };

      // 调用系统文件选择器
      const result = await featureAbility.selectFile(selectOptions);
      if (result && result.uri) {
        // 转换URI为本地文件路径（鸿蒙文件URI格式：file:///xxx）
        this.pdfPath = result.uri.replace("file://", "");
        this.convertResult = ""; // 重置转换结果
      }
    } catch (error) {
      console.error("选择文件失败：", error);
      promptAction.showToast({ message: "选择文件失败，请重试" });
    }
  }

  /**
   * 开始PDF转Word
   */
  async startConversion() {
    if (!this.pdfPath) return;

    this.isConverting = true;
    this.convertResult = "转换中...";

    try {
      // 获取PDF文件名（不含后缀）
      const pdfName = this.getFileName(this.pdfPath).replace(".pdf", "");
      // 生成Word输出路径
      const outputPath = await PDFConverter.generateOutputPath(pdfName);
      // 执行转换
      const success = await PDFConverter.convertPDFToWord(this.pdfPath, outputPath);

      if (success) {
        this.convertResult = `转换成功！文件路径：${outputPath}`;
        promptAction.showToast({ message: "转换成功！" });
      } else {
        this.convertResult = "转换失败，请检查PDF文件是否有效";
      }
    } catch (error) {
      this.convertResult = "转换失败：" + error.message;
      promptAction.showToast({ message: "转换失败，请重试" });
    } finally {
      this.isConverting = false;
    }
  }

  /**
   * 下载Word文件（打开文件预览/分享）
   */
  async downloadWordFile() {
    try {
      const pdfName = this.getFileName(this.pdfPath).replace(".pdf", "");
      const outputPath = await PDFConverter.generateOutputPath(pdfName);

      // 调用系统文件预览能力，让用户选择保存/分享
      await featureAbility.startAbility({
        want: {
          action: "action.system.view",
          uri: `file://${outputPath}`,
          type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }
      });
    } catch (error) {
      console.error("下载文件失败：", error);
      promptAction.showToast({ message: "下载文件失败，请重试" });
    }
  }

  /**
   * 辅助方法：从文件路径中提取文件名
   */
  private getFileName(path: string): string {
    return path.split("/").pop() || "";
  }
}

第四步：实现原子化服务入口能力（PDFToWordAbility.ets）

原子化服务的入口能力负责 “启动服务”“处理生命周期”，替代传统 APP 的EntryAbility：

typescript

运行

import FeatureAbility from '@ohos.ability.featureAbility';
import window from '@ohos.window';

export default class PDFToWordAbility extends FeatureAbility {
  /**
   * 原子化服务启动时触发：加载核心页面
   */
  async onWindowStageCreate(windowStage: window.WindowStage) {
    console.log("PDF转Word原子化服务启动");

    // 加载核心页面（Index.ets）
    windowStage.loadContent('pages/Index', (err) => {
      if (err) {
        console.error("加载页面失败：", err);
        return;
      }

      // 设置窗口属性（原子化服务窗口默认轻量化，无标题栏）
      const window = windowStage.getMainWindow();
      window.setWindowLayoutFullScreen(true);
      window.show();
    });
  }

  /**
   * 原子化服务销毁时触发：释放资源
   */
  onDestroy() {
    console.log("PDF转Word原子化服务销毁");
    // 释放文件资源、清除临时数据（原子化服务“用完即走”原则）
  }
}

四、调试与部署：原子化服务的运行与发布

1. 本地调试

1. 连接测试设备（HarmonyOS 3.0 + 手机），选择设备后点击 “Run” 按钮；
2. 设备会自动启动原子化服务（无需安装），展示核心功能页面；
3. 测试流程：选择 PDF 文件→点击 “开始转换”→转换成功后点击 “下载”，验证功能是否正常。

2. 发布准备：生成原子化服务安装包（HAP）

1. 点击 DevEco Studio 顶部 “Build → Build HAP (s)/APP (s) → Build HAP (s)”；
2. 选择打包类型（Debug/Release），Release 类型需配置签名（与传统 APP 签名流程一致）；
3. 打包完成后，在项目目录 “build/outputs/hap/release” 中获取 HAP 文件（原子化服务安装包，体积通常＜10MB）。

3. 发布渠道

原子化服务的发布渠道与传统 APP 不同，主要通过鸿蒙生态渠道分发：

• 鸿蒙应用市场：提交 HAP 包，审核通过后用户可通过 “原子化服务专区” 搜索下载；
• 分享传播：生成服务卡片，用户可通过微信、短信等方式分享，点击即可免安装启动；
• 系统入口：通过鸿蒙系统的 “负一屏服务中心”“全局搜索” 推荐，提升曝光率。

五、进阶优化：原子化服务的体验提升技巧

1. 轻量化优化：减少资源占用

• 移除冗余依赖：仅保留核心功能所需的库（如 PDF 解析库），避免引入全量框架；
• 压缩资源文件：图片、图标等资源采用 WebP 格式，减少 HAP 包体积；
• 延迟加载非核心功能：如 “文件预览”“历史记录” 等功能，仅在用户需要时加载。

2. 多入口适配：提升可访问性

在module.json5的skills中添加更多入口，支持用户通过不同方式调用：

json

"skills": [
  {
    "entities": ["entity.system.home"], // 桌面入口
    "actions": ["action.system.home"]
  },
  {
    "entities": ["entity.system.search"], // 搜索入口
    "actions": ["action.system.search"]
  },
  {
    "entities": ["entity.system.servicecenter"], // 服务中心入口（负一屏）
    "actions": ["action.system.servicecenter"]
  }
]

3. 离线能力：支持无网络场景

原子化服务默认 “免安装、轻量化”，但部分场景需支持离线使用：

• 缓存核心解析库：将 PDF 转 Word 的核心逻辑缓存到本地，无网络时也能使用；
• 离线文件处理：所有文件操作均在本地完成，无需依赖云端服务（提升隐私安全性）。

总结：原子化服务开发的核心逻辑

原子化服务开发的本质是 “聚焦单一功能、优化用户体验、降低使用门槛”—— 无需安装的特性让用户 “即用即走”，多入口调用提升了服务的可访问性，轻量化设计确保了运行效率。

对于开发者而言，原子化服务是切入鸿蒙生态的重要契机：

1. 开发成本低：仅需实现单一核心功能，无需考虑复杂的 APP 架构；
2. 分发效率高：免安装特性降低了用户尝试门槛，分享传播更便捷；
3. 生态红利大：鸿蒙系统对原子化服务的扶持（如搜索推荐、服务中心曝光），有助于快速获取用户。
5. 后续可进一步探索原子化服务的高级能力，如 “服务卡片交互”“跨设备调用”“与传统 APP 联动” 等，打造更丰富的鸿蒙生态应用。