OMI

OMI — Web Components 小程序框架#

资源概述#

OMI 是腾讯开源的 Web Components 框架，核心理念是使用 Web 标准（Custom Elements）构建跨平台应用。OMI 提供了 Signal 驱动的响应式编程模型，支持 JSX/TSX 语法，内置 Function Components 和 Class Components 两种编写模式。通过 omip 适配包，OMI 组件可编译到微信小程序等平台运行。

OMI 生态完整覆盖了 Web 开发所需的各个层面：Router（单页路由）、Suspense（异步依赖处理）、Directive（指令系统）、omi-form（跨框架表单）、omiu（UI 组件库）、omi-elements（Tailwind 组件套件）以及 100+ 项目模板。同时支持面向对象编程（OOP）和数据导向编程（DOP）两种范式。

GitHub Stars: 13,259 · Forks: 1,254 · 语言: TypeScript · 许可证: Other

核心生态组件：

• omi：框架核心（Component / tag / render / signal / h）
• omip：小程序适配层
• omiu：Web Components UI 组件库
• omi-router：SPA 路由
• omi-form：跨框架表单方案
• omi-cli：Vite + TS/JS 脚手架
• omi-elements：Tailwind Element 套件
• omi-weui：Omi 版 WeUI 组件
• omi-suspense：异步依赖处理
• omi-transition / omi-ripple：动画指令
• lucide-omi：Lucide 图标集合
• reactive-signal：响应式信号核心

设计规范#

• Web Components 优先：一切皆 Custom Elements，通过 @tag('element-name') 定义组件
• JSX 渲染：使用 JSX/TSX 描述 UI 结构，编译为 DOM 操作
• Signal 响应式：使用 signal() / computed() 管理状态，自动追踪依赖
• Constructable Stylesheets：通过 static css 管理组件样式，支持样式共享和隔离
• Function Components：轻量函数组件，适合简单场景
• Class Components：继承 Component，使用 @tag 装饰器，适合复杂逻辑

审核规范#

通过 omip 编译为微信小程序后，审核流程与原生开发一致：

• 审核：1-7 个工作日
• 需遵守《微信小程序平台运营规范》和《微信小程序设计指南》
• 编译后包体不超过微信限制（主包 2MB，总包 20MB）

开发指南#

快速上手#

# 创建 Omi + Vite + TS 项目
npx omi-cli init my-app
cd my-app
npm start          # 开发模式
npm run build      # 构建生产包

# 创建 SPA 项目（Router + Signal + Suspense + Tailwind）
npx omi-cli init-spa my-app

Signal 响应式编程#

import { render, signal, computed, tag, Component, h } from 'omi'

const count = signal(0)
const double = computed(() => count.value * 2)

function increment() { count.value++ }

@tag('counter-demo')
export class CounterDemo extends Component {
  static css = 'span { color: red; }'
  render() {
    return (
      <>
        <button onClick={() => count.value--}>-</button>
        <span>{count.value} × 2 = {double.value}</span>
        <button onClick={increment}>+</button>
      </>
    )
  }
}

// 使用组件
import './counter-demo'
render(<counter-demo />, document.body)

Function Components（轻量写法）#

import { defineElement, h } from 'omi'

defineElement('my-counter', () => {
  const count = signal(0)
  return () => (
    <div>
      <button onClick={() => count.value--}>-</button>
      <span>{count.value}</span>
      <button onClick={() => count.value++}>+</button>
    </div>
  )
})

常见陷阱#

1. Tree Shaking 陷阱：如果从模块中导入组件类同时还导入其他东西，需确保使用组件标签名（如 <counter-demo />）而非仅导入类，否则可能被 tree shaking 移除
2. 小程序适配限制：omip 适配层有部分 Web API 不支持（如直接 DOM 操作），需使用小程序原生 API
3. 样式隔离：Constructable Stylesheets 在小程序中的支持有限，部分场景需降级为 wxss
4. Signal vs Class State：Signal 更轻量但需手动管理依赖；Class 的 data 属性自动 diff。两者可混用但需注意一致性

从原生小程序迁移#

1. 使用 omip 适配包创建新项目
2. 将原有 .wxml 逻辑改写为 JSX 语法
3. 将 setData 调用替换为 signal() 或 this.data 赋值
4. 使用 OMI 组件标签名注册替代 usingComponents

生态资源#

推荐框架#

• omip：小程序适配层（官方配套）
• omiu：Web Components UI 组件库
• omi-elements：Tailwind + OMI 组件套件

推荐 UI 库#

• omi-weui：Omi 版本的微信 WeUI 组件
• TDesign Web Components：基于 OMI 的 TDesign 实现
• lucide-omi：Lucide 图标库的 OMI 版本

社区资源#

• 官方文档（中文）：https://omi.cdn-go.cn/home/latest/zh/
• 官方教程 / Playground：https://omi.cdn-go.cn/tutorial/latest/
• 模板库（100+）：https://omi.cdn-go.cn/templates/latest/
• OMI Form 游乐场：https://omi.cdn-go.cn/form/latest/play/
• GitHub 仓库：https://github.com/Tencent/omi

版本更新#

• 最后代码推送：2026-03-27（活跃维护）
• Stars 增长：13,259（腾讯系高星框架）
• 近期重点：
  • reactive-signal 响应式核心持续优化
  • OMI Form 表单方案 + 跨框架支持
  • 100+ 模板生态持续扩展
  • Tailwind Element 套件（omi-elements）
  • Lucide OMI 图标库
• 维护状态：腾讯官方团队维护，持续迭代中