跳到主要内容

基础概念

5 分钟搞懂 Omni 是怎么工作的。

一、小组件的三种"位置"​

iOS 上能放小组件的位置不一样,Omni 都支持:

类别类型出现在哪里
桌面小 / 中 / 大主屏幕
锁屏圆形 / 矩形 / 内联锁屏
控制中心按钮 / 开关下拉控制中心
灵动岛实时活动屏幕顶部胶囊区域

每种类型尺寸不一样、能用的能力也不一样(比如锁屏不能用彩色)。新建小组件时先选类型。

二、一个小组件由两部分组成​

1. 视图(看得见的部分)​

视图由组件搭出来,常见组件:

  • 文本 text、图片 image、SF 图标 icon、形状 shape
  • 按钮 button、日期/计时 date、仪表 gauge、间隔 spacer
  • 容器:横排 hstack、竖排 vstack、叠放 zstack、定时切换 tstack、网格 grid
  • 循环 loop(让一个组件重复 N 次,渲染数组数据)

详见 组件 一节。

2. 数据(动态的部分)​

如果你想让小组件显示"实时数据"(天气、邮箱未读、股价等),需要写一段 JavaScript 代码。

// 例:从接口拿数据
const req = new Request("https://2f0.cn/api/omni")
const obj = await req.fetchJSON()
this.title = obj.omni  // 把结果存进 this.xxx,组件就能用了

代码运行的结果会通过占位符绑定到组件上:

文本组件的"内容"字段写: {title}

最终小组件就会显示 obj.omni 的值。

关键规则

只有写到 this.xxx 或顶层 let/var/const xxx 的变量才能被组件使用。 Omni 在运行 JS 后会去抓这些变量,然后填到占位符里。

隐藏内部变量

顶层 let / var / const 默认都会被当作输出字段。不想暴露给组件(比如内部常量、模块级临时值),名字加 _ 前缀 就会被跳过。函数体内的局部变量会自动忽略,不用加。

let title = "你好"             // → 输出字段
const _PAGE_SIZE = 20          // _ 前缀,不输出
const _WEEK = ["日", "一", "二", "三", "四", "五", "六"]

function load() {
  const now = new Date()       // 函数内局部,自动忽略,不用加 _
}

三、JS 使用​

  • ✅ 标准 JS 语法、async/await、Promise、Date、JSON 都能用
  • ❌ 没有 window、document、fetch(用 Omni 的 Request 替代)
  • ❌ 没有 npm,只能用 Omni 内置的接口
  • ⚠️ 小组件运行环境内存有限(小于 30MB),别加载大文件

四、小组件什么时候会刷新?​

iOS 系统决定。一般是:

  • 你展示它的次数多 → 系统觉得你常看 → 刷新更勤
  • 一天内大约 40-70 次(不是想刷就能刷)
  • 你可以"建议":setUpdateFreq(30) 表示 30 分钟后再刷,系统参考这个值
注意

不要指望小组件能秒刷。需要"准实时"的场景,用实时活动(灵动岛)。

五、设置项(让别人用你的模板)​

如果你做了个小组件想分享给别人,但别人需要填自己的 token、城市等。 Omni 提供"设置项"——你预留几个空位,别人导入后在设置里填。详见 配置读写。

下一步:做出第一个小组件 →