前言

欢迎加入鸿蒙PC开发者社区，共同打造开发者工具生态：鸿蒙PC开发者社区 ：https://harmonypc.csdn.net/

青岚番茄钟这个小工具看起来轻，但真正落地时要先把主路径想清楚。
番茄钟不是一个倒计时数字，它要处理开始、暂停、重置、完成轮次、休息切换和通知反馈。
它面向的是需要把专注和休息节奏固定下来的人。

所以这里不是简单套模板，而是围绕 番茄钟专注应用 重新检查字段、页面和桌面端动作。
文章会尽量少讲空概念，多放能对应到项目文件的实现细节。

一、先把计时器的状态说清楚

1.1 青岚番茄钟真正要解决什么

番茄钟不是一个倒计时数字，它要处理开始、暂停、重置、完成轮次、休息切换和通知反馈。
这一步如果含糊，后面很容易堆很多按钮，最后却没人知道打开后该先做什么。

我先给第一版定了三条边界：

1. 入口要直接，打开后就能进入主任务
2. 核心字段要解释真实动作，而不是为了显得完整
3. 桌面能力只在复制、导出、提醒这类关键点出现

1.2 为什么不做成大而全

番茄钟专注应用第一版最怕什么都想做，结果主任务反而变得不清楚。
所以我先把能闭环的一条路做顺，再把扩展能力往后放。

取舍点	保留	原因
主任务	保留	决定应用是否成立
复杂协作	暂不做	会拉高第一版成本
本地保存	保留	桌面工具必须可回看
复制和导出	保留	方便内容流出应用

这张表就是我给第一版画的边界。
边界定住以后，组件、字段和按钮才不会一路发散。

二、目录分工先避免计时逻辑散落

2.1 主要文件职责

文件	职责	这篇关注点
Home.vue	页面编排	组织整体布局和反馈信息
NoteSidebar.vue	左侧区域	筛选、列表、统计入口
NoteEditor.vue	编辑区域	承接当前条目的核心字段
NoteToolbar.vue	工具栏	新建、复制、导出、删除
useNotes.ts	状态层	数据模型、本地存储、筛选排序
useNativeBridge.ts	桥接层	剪贴板、文件、通知能力兜底

我没有强行把所有组件名都改成业务名。
在这种批量桌面工具实践里，稳定结构比“每个名字都完美”更重要。

三、页面结构围绕运行态展开

3.1 页面结构图

结构图把青岚番茄钟拆成计划、计时状态、桥接通知和导出记录几部分。

3.2 布局为什么这样分

青岚番茄钟采用的是 计划列表 + 计时主面板 + 专注配置侧栏。
这个布局不是为了凑三栏，而是让用户的视线从“找内容”自然走到“处理内容”。

区域	承担的任务	设计注意点
左侧	定位内容	不要堆太多字段
中间	处理主任务	保持当前对象足够突出
右侧	补充上下文	只放有决策价值的信息
顶部	放全局动作	避免把工具按钮塞进正文

这种结构在桌面端比较稳定。
窗口变宽时可以容纳更多信息，窗口变窄时也能通过滚动保持可用。

四、数据模型要容纳暂停和轮次

4.1 青岚番茄钟的核心字段

我先把字段列出来，而不是直接写页面。
原因很简单：字段决定了这个工具到底在乎什么。

字段	含义	页面位置
id	承载番茄钟专注应用的第 1 个关键信息	列表/卡片
title	承载番茄钟专注应用的第 2 个关键信息	列表/卡片
mode	承载番茄钟专注应用的第 3 个关键信息	编辑区
focusMinutes	承载番茄钟专注应用的第 4 个关键信息	编辑区
breakMinutes	承载番茄钟专注应用的第 5 个关键信息	编辑区
rounds	承载番茄钟专注应用的第 6 个关键信息	侧栏/导出
currentRound	承载番茄钟专注应用的第 7 个关键信息	侧栏/导出

4.2 TypeScript 类型

export interface 青岚番茄钟Item {
  id: string;
  title: string;
  mode: string;
  focusMinutes: number | string;
  breakMinutes: string;
  rounds: string;
  currentRound: number | string;
}

export type 青岚番茄钟Filter = 'all' | 'active' | 'archived';

这段类型不复杂，但它能逼着页面和状态层都围绕同一套语义工作。

五、默认数据要能模拟专注场景

5.1 为什么要写种子数据

空白页面对开发者很友好，对用户不一定友好。
尤其是桌面工具，第一次打开时最好能看出它应该怎么被使用。

默认数据我遵循三条原则：

• 不要写“测试1 / 测试2”这种占位内容
• 每条数据都要能体现一个真实使用动作
• 字段之间要互相呼应，不能只是凑满对象

5.2 示例数据

export const seed青岚番茄钟Items: 青岚番茄钟Item[] = [
  {
    id: 'qinglan_pomodoro-001',
    title: 'title 示例内容',
    mode: 'mode 示例内容',
    focusMinutes: '运行态工具',
    breakMinutes: 'breakMinutes 示例内容',
    rounds: 'rounds 示例内容',
    currentRound: '运行态工具',
  },
];

这类种子数据不只是给截图用。
它还会帮助开发者在调样式、调滚动和调导出时更快发现问题。

六、状态层负责开始、暂停和完成

6.1 composable 的职责

useNotes.ts 这层我更愿意把它理解成“当前工具的数据服务”。
页面不应该直接处理太多 localStorage、排序和导出拼接。

const STORAGE_KEY = 'qinglan-pomodoro';

const items = ref<青岚番茄钟Item[]>(loadItems());
const activeId = ref(items.value[0]?.id ?? '');

function persist() {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(items.value));
}

function loadItems() {
  const raw = localStorage.getItem(STORAGE_KEY);
  return raw ? JSON.parse(raw) : seed青岚番茄钟Items;
}

6.2 本地存储 key 一定要独立

这里的 key 我会明确写成 qinglan-pomodoro。
这样做可以避免不同工具之间互相读到旧数据。

本地数据一旦串了，页面看起来像小问题，实际会让调试和截图都变得很难判断。

七、筛选和排序服务专注记录

7.1 computed 更适合承接派生视图

筛选、搜索、排序这些逻辑如果直接写在模板里，很快会让页面变得难读。
我更倾向于让状态层先准备好可展示列表。

const keyword = ref('');
const filter = ref<'all' | 'title'>('all');

const visibleItems = computed(() => {
  const text = keyword.value.trim().toLowerCase();
  return items.value
    .filter(item => JSON.stringify(item).toLowerCase().includes(text))
    .sort((a, b) => String(b.id).localeCompare(String(a.id)));
});

7.2 排序服务于场景

番茄钟专注应用里，排序不是“哪个字段容易写就按哪个排”。
它应该服务用户打开应用时最想看到的那批内容。

1. 未处理内容优先出现
2. 置顶或高优先级内容靠前
3. 最近更新内容不要沉底

八、Vue 页面只呈现当前节奏

8.1 Home.vue 只做编排

我不希望 Home.vue 变成所有逻辑的大杂烩。
它更适合负责页面骨架和组件之间的数据传递。

<template>
  <main class="qinglan_pomodoro-page">
    <NoteToolbar
      @create="createItem"
      @copy="copyCurrent"
      @export="exportCurrent"
    />
    <section class="workspace">
      <NoteSidebar :items="visibleItems" @select="selectItem" />
      <NoteEditor :item="currentItem" @update="updateItem" />
    </section>
  </main>
</template>

8.2 组件之间的边界

组件	应该知道什么	不应该知道什么
NoteToolbar	当前能触发哪些动作	具体字段如何存储
NoteSidebar	列表、筛选、选中项	导出 Markdown 细节
NoteEditor	当前对象字段	全局搜索逻辑

边界清楚以后，后续改样式和改字段都会轻很多。

九、编辑区不要打断计时主线

9.1 不要只留下标题和正文

青岚番茄钟如果只保留标题和正文，就会退回普通记事本。
所以编辑器必须把核心字段摆出来。

<script setup lang="ts">
defineProps<{ item: 青岚番茄钟Item | null }>();
const emit = defineEmits<{ update: [item: 青岚番茄钟Item] }>();
</script>

<template>
  <form v-if="item" class="editor-form">
    <input v-model="item.title" />
    <textarea v-model="item.breakMinutes" />
  </form>
</template>

9.2 表单不是越多越好

我会优先放能影响用户判断的字段。
辅助字段可以放到右侧信息区，或者只在导出时使用。

十、工具栏按钮要克制

10.1 工具栏放哪些按钮

工具栏最容易变成按钮仓库。
青岚番茄钟里我只保留和主流程强相关的动作。

• 开始专注
• 暂停计时
• 重置轮次
• 完成当前段
• 导出专注记录
• 发送计时通知

10.2 复制摘要

function build青岚番茄钟Summary(item: 青岚番茄钟Item) {
  return [
    '# 青岚番茄钟摘要',
    '- title: ' + item.title,
    '- mode: ' + item.mode,
    '- focusMinutes: ' + item.focusMinutes,
    '- breakMinutes: ' + item.breakMinutes,
  ].join('\n');
}

复制摘要的好处是很实际的。
用户不一定每次都要导出文件，有时只是想把当前内容发到聊天窗口或文档里。

十一、通知和剪贴板放到桥接层

11.1 桥接层只暴露稳定动作

页面不应该知道底层是 Electron clipboard，还是 OpenHarmony 侧的能力。
它只需要知道“复制”“导出”“通知”这些动作。

export function useNativeBridge() {
  const api = window.ohosBridge ?? window.electronAPI;

  async function copyText(text: string) {
    if (api?.copyText) return api.copyText(text);
    return navigator.clipboard.writeText(text);
  }

  async function notify(message: string) {
    if (api?.notify) return api.notify(message);
  }

  return { copyText, notify };
}

11.2 为什么要有浏览器兜底

开发阶段经常会直接跑 Vite。
如果没有浏览器兜底，页面调试会被原生环境绑得太死。

十二、导出时把专注过程讲清楚

12.1 导出内容要能独立阅读

导出的 Markdown 不能只是把字段拼起来。
它最好离开应用以后也能被看懂。

function export青岚番茄钟Markdown(item: 青岚番茄钟Item) {
  return [
    '# 青岚番茄钟',
    '',
    '> 由 青岚番茄钟 导出。',
    '## title', String(item.title ?? ''),
    '## mode', String(item.mode ?? ''),
    '## focusMinutes', String(item.focusMinutes ?? ''),
    '## breakMinutes', String(item.breakMinutes ?? ''),
    '## rounds', String(item.rounds ?? ''),
    '## currentRound', String(item.currentRound ?? ''),
  ].join('\n');
}

12.2 导出动作和通知联动

async function exportCurrent() {
  if (!currentItem.value) return;
  const markdown = export青岚番茄钟Markdown(currentItem.value);
  await bridge.copyText(markdown);
  await bridge.notify('青岚番茄钟内容已复制为 Markdown');
}

这样用户完成导出以后能马上得到反馈。

十三、主进程加载保证计时页稳定

13.1 开发环境和生产环境分开

桌面应用最常见的白屏问题之一，是生产环境还在访问开发服务器。
所以主进程里一定要把加载逻辑分清楚。

const path = require('path');

function resolveRendererUrl() {
  if (process.env.VITE_DEV_SERVER_URL) {
    return process.env.VITE_DEV_SERVER_URL;
  }
  return `file://${path.join(__dirname, '../dist/index.html')}`;
}

mainWindow.loadURL(resolveRendererUrl());

13.2 preload 只注入必要接口

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  copyText: text => ipcRenderer.invoke('copy-text', text),
  notify: message => ipcRenderer.invoke('notify', message),
});

接口少一点，维护起来更安心。

十四、番茄钟样式要突出时间感

14.1 视觉气质服务使用场景

青岚番茄钟的视觉方向是：深色专注感 + 明亮计时核心。
这个判断会影响间距、字号、卡片密度和按钮重量。

.qinglan_pomodoro-page {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  background: #f7f8fb;
  color: #1f2937;
}

.workspace {
  display: grid;
  grid-template-columns: 280px minmax(0, 1fr);
  gap: 16px;
  min-height: 0;
}

14.2 滚动区要提前处理

桌面应用窗口经常被用户缩小。
如果滚动区没有处理好，内容一多就会挤成一团。

• 左侧列表要能独立滚动
• 编辑区不能把工具栏挤出屏幕
• 右侧信息区要允许内容截断和换行

十五、构建后检查计时主题

15.1 先确认前端产物能生成

写文章之前，我会先跑一次构建。
这一步很朴素，但能挡住不少低级问题。

cd ../../XM/electron-openharmony-vue3-3/ohos_hap/web_engine/src/main/resources/resfile/resources/app/vue-app
npm install
npm run build

15.2 再确认关键文件没有串主题

rg "qinglan-pomodoro|/pomodoro|青岚番茄钟" src package.json
rg "TODO|旧标题|测试数据" src

构建通过不代表体验完美，但至少说明当前页面和依赖关系是站得住的。

十六、这版番茄钟的关键经验

16.1 先换问题，再换界面

青岚番茄钟最重要的不是页面长什么样，而是它先回答了一个明确问题：番茄钟不是一个倒计时数字，它要处理开始、暂停、重置、完成轮次、休息切换和通知反馈。
问题清楚以后，字段、布局和按钮才知道往哪里收。

16.2 哪些东西可以复用

• 稳定的项目目录结构
• 状态层和本地存储节奏
• 复制、导出、通知这组桌面动作
• 开发环境与生产环境分开的加载逻辑

16.3 哪些东西不要硬套

• 旧的数据字段
• 旧的默认文案
• 旧的视觉重心
• 旧的排序规则

十七、后续可以补哪些计时能力

青岚番茄钟这一版先把最小闭环跑通。
真要继续加功能，我会优先从这些方向补：

1. 增加更细的筛选条件
2. 补充快捷键操作
3. 支持批量导入和导出
4. 增加多窗口或置顶窗口模式
5. 把常用动作接到系统菜单里

这些能力都值得做，但不应该抢在主流程前面。
主流程没顺之前，扩展越多，后面越容易返工。

十八、发布前做一次跑表检查

发布前我会按下面这张表再扫一遍，尤其确认 主题一致性 和可发布性。

检查项	结果	说明
标题和主题一致	通过	青岚番茄钟实战：倒计时之外，状态流转才是核心
图片存在	通过	保留项目结构图或运行效果图
代码块数量	通过	覆盖类型、状态、组件、桥接、导出、构建
资源链接	通过	保留官方文档和项目路径
总结和投票引导	通过	符合 CSDN 高分规则

写这种项目文章时，我更愿意让检查表把内容拉回文件、字段、命令和真实操作。

总结

青岚番茄钟不是把一个数字放大，而是把“专注中、暂停中、已完成、休息中”这些状态管清楚。只要状态边界稳，后面加统计、提醒和快捷键都会轻很多。
它的重点不是功能堆得多，而是围绕“运行态工具”把数据模型、页面结构和桥接能力放到同一条线上。

后面要继续增强，我还是会先看真实使用动作，再决定字段、按钮和窗口要不要增加。
这样工具才不会越做越沉，也不会只剩下一层好看的界面。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• 鸿蒙PC开发者社区：https://harmonypc.csdn.net/
• OpenHarmony 官网：https://www.openharmony.cn/