v5.0.6


omi


Omi - 下一代 Web 框架，去万物糟粕，合精华为一


让 JSX, Web Components, Proxy, Store, Path Updating 在一起

特性

  • 小巧的尺寸(gzip压缩后仅4kb)
  • 真正的 MVVM, 拥有 mappingjs 强力支持
  • 支持 TypeScript
  • 响应式数据绑定
  • 增强了 CSS, 支持 rpx 单位，基于 750 屏幕宽度
  • 基于 Shadow Dom 设计
  • 利用Chrome 开发工具扩展 轻松调试，从 Chrome 应用商店安装
  • 符合浏览器的发展趋势以及API设计理念
  • Web Components + JSX 相互融合为一个框架 Omi
  • 内置 observe 制作响应式视图(免去 this.update)
  • Web Components 也可以数据驱动视图, UI = fn(data)
  • JSX 是开发体验最棒(智能提示)、语法噪音最少、图灵完备的 UI 表达式，模板引擎不完备，模板字符串完备但是语法噪音太大
  • 独创的 Path Updating 机制，基于 Proxy 全自动化的精准更新，功耗低，自由度高，性能卓越，方便集成 requestIdleCallback
  • 对 this.update 说再见吧！只要使用 store 系统，它就会自动化按需更新局部视图
  • 看看Facebook React 和 Web Components对比优势，Omi 融合了各自的优点，而且给开发者自由的选择喜爱的方式
  • Shadow DOM 与 Virtual DOM 融合，Omi 既使用了虚拟 DOM，也是使用真实 Shadow DOM，让视图更新更准确更迅速
  • 99.9% 的项目不需要什么时间旅行，也不需要时间旅行调试(Time travel debugging),而且也不仅仅 redux 能时间旅行,请不要上来就 redux，Omi store 系统可以满足所有项目。
  • 局部 CSS 最佳解决方案(Shadow DOM)，社区为局部 CSS 折腾了不少框架和库(使用js或json写样式，如:Radium，jsxstyle，react-style；与webpack绑定使用生成独特的className文件名—类名—hash值，如：CSS Modules，Vue)，还有运行时注入scoped atrr 的方式，都是 hack 技术；Shadow DOM Style 是最完美的方案

对比同样开发 TodoApp， Omi 和 React 渲染完的 DOM 结构，Omi 使用 Shadow DOM 隔离样式和语义化结构:

Omi React
Omi React

Omi 生态

项目 描述
omi-docs Omi 官方文档
omi-mvvmREADME - 图4 MVVM 王者归来, mappingjs 强力加持。
omi-htmlREADME - 图5 Using htm in omi.
omi-30-secondsREADME - 图6 30 秒理解一段有用的 Omi 代码片段.
omi-canvas Web Components, JSX 和 Canvas 的完美融合
omi-mpREADME - 图7 通过微信小程序开发和生成 Web 单页应用(H5 SPA)
omi-router Omi 官方路由。→ DEMO
omi-devtools 谷歌浏览器开发工具扩展
omi-cli 项目脚手架工具，支持 Javascript 和 Typescript
omi-transform Omi 和 css3transform 完美结合. 让 css3 transform 在你的 Omi项目中变得超级简单.
omi-tap2 Omi 原生支持 tap 事件（omi v4.0.24+）
omi-tap 让 Omi 项目轻松支持 tap 事件
omi-finger Omi 官方手势库
omi-touch 丝般顺滑的触摸运动
omi-mobx Omi Mobx 适配器
omi-use 跟 React hooks 类似的方式定义纯组件
omi-native 把 web components 渲染到 native，比如 IOS 、Android
westore 小程序解决方案 westore，与 Omi 互相启发
omi-weui Weui for Omi by @132yse.
omi-i18n Omi 国际化解决方案
omi-page 基于 page.js 的 Omi 路由

omi-mp

通过微信小程序开发和一键生成 Web 的 H5 SPA (基于 omi + omi-router)

看下官方模板的转换例子：

Index Logs
README - 图8 README - 图9

因为 Web 里拉取不到用户登录态，更换了用户头像和名称。

必须收藏的资源

目录

一个 HTML 完全上手

下面这个页面不需要任何构建工具就可以执行

  1. <!DOCTYPE html>
  2. <html>
  4. <head>
  5.   <meta charset="UTF-8" />
  6.   <title>Add Omi in One Minute</title>
  7. </head>
  9. <body>
  10.   <script src="https://unpkg.com/omi"></script>
  11.   <script>
  12.     const { WeElement, h, render, define } = Omi
  14.     define('like-button',
  15.       class extends WeElement {
  16.         install() {
  17.           this.data = { liked: false }
  18.         }
  20.         render() {
  21.           if (this.data.liked) {
  22.             return 'You liked this.'
  23.           }
  25.           return h(
  26.             'button',
  27.             {
  28.               onClick: () => {
  29.                 this.data.liked = true
  30.                 this.update()
  31.               }
  32.             },
  33.             'Like'
  34.           )
  35.         }
  36.       })
  38.     render(h('like-button'), 'body')
  39.   </script>
  40. </body>
  42. </html>

通过上面脚本的执行，你已经定义好了一个自定义标签，可以不使用 render 方法，直接使用 like-button 标签：

  1. <body>
  2.     <like-button></like-button>
  3. </body>

再花 30 秒完全上手

你也可以使用现代化的 JS 语法，快速构建 Omi 项目:

  1. import { render, WeElement, tag, observe } from "omi"
  3. @observe
  4. @tag("my-counter")
  5. class MyCounter extends WeElement {
  7.   data = {
  8.     count: 0
  9.   }
  11.   sub = () => {
  12.     this.data.count--
  13.   }
  15.   add = () => {
  16.     this.data.count++
  17.   }
  19.   render() {
  20.     return (
  21.       <div>
  22.         <button onClick={this.sub}>-</button>
  23.         <span>{this.data.count}</span>
  24.         <button onClick={this.add}>+</button>
  25.       </div>
  26.     )
  27.   }
  28. }
  30. render(<my-counter />, "body")

→ counter demo

你会发现 MyCounter 从未使用过，所以你可以使用下面代码达到同样效果并且避免 Eslint 提示错误:

  1. import { render, WeElement, define } from 'omi'
  3. define('my-counter', class extends WeElement {
  4.     static observe = true
  6.     data = {
  7.       count: 1
  8.     }
  10.     sub = () => {
  11.       this.data.count--
  12.     }
  14.     add = () => {
  15.       this.data.count++
  16.     }
  18.     render() {
  19.       return (
  20.         <div>
  21.           <button onClick={this.sub}>-</button>
  22.           <span>{this.data.count}</span>
  23.           <button onClick={this.add}>+</button>
  24.         </div>
  25.       )
  26.     }
  27.   })
  29. render(<my-counter />, 'body')

你也可以定义成纯函数的形式:

  1. import { define, render } from 'omi'
  3. define('my-counter', function() {
  4.   const [count, setCount] = this.use({
  5.     data: 0,
  6.     effect: function() {
  7.       document.title = `The num is ${this.data}.`
  8.     }
  9.   })
  11.   this.useCss(`button{ color: red; }`)
  13.   return (
  14.     <div>
  15.       <button onClick={() => setCount(count - 1)}>-</button>
  16.       <span>{count}</span>
  17.       <button onClick={() => setCount(count + 1)}>+</button>
  18.     </div>
  19.   )
  20. })
  22. render(<my-counter />, 'body')

如果你不需要 effect 方法, 可以直接使用 useData:

  1. const [count, setCount] = this.useData(0)

快速入门

安装

  1. $ npm i omi-cli -g               # install cli
  2. $ omi init my-app     # init project, you can also exec 'omi init' in an empty folder
  3. $ cd my-app           # please ignore this command if you executed 'omi init' in an empty folder
  4. $ npm start                      # develop
  5. $ npm run build                  # release

npx omi-cli init my-app 也支持(要求 npm v5.2.0+)

目录说明:

  1. ├─ config
  2. ├─ public
  3. ├─ scripts
  4. ├─ src
  5. │  ├─ assets
  6. │  ├─ elements    //存放所有 custom elements
  7. │  ├─ store       //存放所有页面的 store
  8. │  ├─ admin.js    //入口文件，会 build 成  admin.html
  9. │  └─ index.js    //入口文件，会 build 成  index.html

关于编译网站的 url 前缀的设置，可以参考两个地址：

比如在 windows 下:

  1. "scripts": {
  2.   "start": "node scripts/start.js",
  3.   "_build": "node scripts/build.js",
  4.   "build":"set PUBLIC_URL=https://fe.wxpay.oa.com/dv&& npm run _build"
  5. }

在 mac os 中:

  1. "scripts": {
  2.     "start": "node scripts/start.js",
  3.     "_build": "node scripts/build.js",
  4.     "build":"PUBLIC_URL=https://fe.wxpay.oa.com/dv npm run _build",
  5.     "fix": "eslint src --fix"
  6.   },

项目模板

Template Type Command Describe
Base Template omi init my-app 基础模板
TypeScript Template(omi-cli v3.0.5+) omi init-ts my-app 使用 TypeScript 的模板
SPA Template(omi-cli v3.0.10+) omi init-spa my-app 使用 omi-router 单页应用的模板
omi-mp Template(omi-cli v3.0.13+) omi init-mp my-app 小程序开发 Web 的模板
MVVM Template(omi-cli v3.0.22+) omi init-mvvm my-app MVVM 模板

Cli 自动创建的项目脚手架是基于单页的 create-react-app 改造成多页的，有配置方面的问题可以查看 create-react-app 用户指南。

Hello Element

先创建一个自定义元素:

  1. import { define, WeElement } from 'omi'
  3. define('hello-element', class extends WeElement {
  4.   onClick = evt => {
  5.     // trigger CustomEvent
  6.     this.fire('abc', { name: 'dntzhang', age: 12 })
  7.     evt.stopPropagation()
  8.   }
  10.   css() {
  11.     return `
  12.         div {
  13.           color: red;
  14.           cursor: pointer;
  15.         }`
  16.   }
  18.   render(props) {
  19.     return (
  20.       <div onClick={this.onClick}>
  21.         Hello {props.msg} {props.propFromParent}
  22.         <div>Click Me!</div>
  23.       </div>
  24.     )
  25.   }
  26. })

使用该元素:

  1. import { define, render, WeElement } from 'omi'
  2. import './hello-element'
  4. define('my-app', class extends WeElement {
  5.   data = { abc: 'abc', passToChild: 123 }
  7.   // define CustomEvent Handler
  8.   onAbc = evt => {
  9.     // get evt data by evt.detail
  10.     this.data.abc = ' by ' + evt.detail.name
  11.     this.data.passToChild = 1234
  12.     this.update()
  13.   }
  15.   css() {
  16.     return `
  17.          div{
  18.              color: green;
  19.          }`
  20.   }
  22.   render(props, data) {
  23.     return (
  24.       <div>
  25.         Hello {props.name} {data.abc}
  26.         <hello-element
  27.           onAbc={this.onAbc}
  28.           prop-from-parent={data.passToChild}
  29.           msg="WeElement"
  30.         />
  31.       </div>
  32.     )
  33.   }
  34. })
  36. render(<my-app name="Omi v4.0" />, 'body')

告诉 Babel 把 JSX 转化成 Omi.h() 的调用:

  1. {
  2.     "presets": ["env", "omi"]
  3. }

需要安装下面两个 npm 包支持上面的配置:

  1. "babel-preset-env": "^1.6.0",
  2. "babel-preset-omi": "^0.1.1",

如果你使用 babel7，也可以使用如下包和配置：

  1. npm install --save-dev @babel/preset-env
  2. npm install --save-dev @babel/preset-react
  1. {
  2.   "presets": [
  3.     "@babel/preset-env",
  4.     [
  5.       "@babel/preset-react",
  6.       {
  7.         "pragma": "Omi.h", 
  8.       }
  9.     ]
  10.   ]
  11. }

如果不想把 css 写在 js 里，你可以使用 webpack to-string-loader, 比如下面配置:

  1. {
  2.     test: /[\\|\/]_[\S]*\.css$/,
  3.     use: [
  4.         'to-string-loader',
  5.         'css-loader'
  6.     ]
  7. }

如果你的 css 文件以 _ 开头, css 会使用 to-string-loader. 如：

  1. import { tag, WeElement render } from 'omi'
  2. //typeof cssStr is string
  3. import cssStr from './_index.css'
  5. @tag('my-app')
  6. class MyApp extends WeElement {
  8.   css() {
  9.     return cssStr
  10.   }
  11.   ...
  12.   ...
  13.   ...

你也可以忘掉这一对繁琐的配置直接使用 omi-cli，不需要你配置任何东西。

TodoApp

下面列举一个相对完整的 TodoApp 的例子:

  1. import { define, render, WeElement } from 'omi'
  3. define('todo-list', function(props) {
  4.   return (
  5.     <ul>
  6.       {props.items.map(item => (
  7.         <li key={item.id}>{item.text}</li>
  8.       ))}
  9.     </ul>
  10.   )
  11. })
  13. define('todo-app', class extends WeElement {
  14.   static observe = true
  16.   data = { items: [], text: '' }
  18.   render() {
  19.     return (
  20.       <div>
  21.         <h3>TODO</h3>
  22.         <todo-list items={this.data.items} />
  23.         <form onSubmit={this.handleSubmit}>
  24.           <input
  25.             id="new-todo"
  26.             onChange={this.handleChange}
  27.             value={this.data.text}
  28.           />
  29.           <button>Add #{this.data.items.length + 1}</button>
  30.         </form>
  31.       </div>
  32.     )
  33.   }
  35.   handleChange = e => {
  36.     this.data.text = e.target.value
  37.   }
  39.   handleSubmit = e => {
  40.     e.preventDefault()
  41.     if (!this.data.text.trim().length) {
  42.       return
  43.     }
  44.     this.data.items.push({
  45.       text: this.data.text,
  46.       id: Date.now()
  47.     })
  48.     this.data.text = ''
  49.   }
  50. })
  52. render(<todo-app />, 'body')

Store

使用 Store 体系可以告别 update 方法，基于 Proxy 的全自动属性追踪和更新机制。强大的 Store 体系是高性能的原因，除了靠 props 决定组件状态的组件，其余组件所有 data 都挂载在 store 上,

  1. export default {
  2.   data: {
  3.     items: [],
  4.     text: '',
  5.     firstName: 'dnt',
  6.     lastName: 'zhang',
  7.     fullName: function () {
  8.       return this.firstName + this.lastName
  9.     },
  10.     globalPropTest: 'abc', //更改我会刷新所有页面,不需要再组件和页面声明data依赖
  11.     ccc: { ddd: 1 } //更改我会刷新所有页面,不需要再组件和页面声明data依赖
  12.   },
  13.   globalData: ['globalPropTest', 'ccc.ddd'],
  14.   add: function () {
  15.     if (!this.data.text.trim().length) {
  16.         return;
  17.     }
  18.     this.data.items.push({
  19.       text: this.data.text,
  20.       id: Date.now()
  21.     })
  22.     this.data.text = ''
  23.   }
  24.   //默认 false，为 true 会无脑更新所有实例
  25.   //updateAll: true
  26. }

自定义 Element 需要声明依赖的 data，这样 Omi store 根据自定义组件上声明的 data 计算依赖 path 并会按需局部更新。如:

  1. define('todo-app', class extends WeElement {
  2.     static get data() {
  3.         //如果你用了 store，这个只是用来声明依赖，按需 Path Updating
  4.         return { items: [], text: '' }
  5.     }
  6.     ...
  7.     ...
  8.     ...
  9.     handleChange = (e) => {
  10.         this.store.data.text = e.target.value
  11.     }
  13.     handleSubmit = (e) => {
  14.         e.preventDefault()
  15.         this.store.add()
  16.     }
  17. })
  • 数据的逻辑都封装在了 store 定义的方法里 (如 store.add)
  • 视图只负责传递数据给 store （如上面调用 store.add 或设置 store.data.text）

需要在 render 的时候从根节点注入 store 才能在所有自定义 Element 里使用 this.store:

  1. render(<todo-app></todo-app>, 'body', store)

→ Store 完整的代码

总结一下:

  • store.data 用来列出所有属性和默认值(除去 props 决定的视图的组件)
  • 组件和页面的 data 用来列出依赖的 store.data 的属性 (omi会记录path)，按需更新
  • 如果页面简单组件很少，可以 updateAll 设置成 true，并且组件和页面不需要声明 data，也就不会按需更新
  • globalData 里声明的 path，只要修改了对应 path 的值，就会刷新所有页面和组件，globalData 可以用来列出所有页面或大部分公共的属性 Path

Mitt

如果不想使用 store 的 data 体系，也可以使用发布订阅模式。比如在 Omi 中使用 mitt 跨组件通讯:

Observe

Omi Observe

你可以为那些不需要 store 的自定义元素使用 observe 创建响应式视图，比如:

  1. import { define, WeElement } from "omi"
  3. define("my-app", class extends WeElement {
  4.   static observe = true
  6.   install() {
  7.     this.data.name = "omi"
  8.   }
  10.   onClick = () => {
  11.     this.data.name = "Omi V4.0"
  12.   }
  14.   render(props, data) {
  15.     return (
  16.       <div onClick={this.onClick}>
  17.         <h1>Welcome to {data.name}</h1>
  18.       </div>
  19.     )
  20.   }
  21. })

如果你想要兼容 IE11,请使用 omi-mobx 代替 omi 自带的 observe，往下看..

Omi Mobx

  1. import { tag, WeElement } from "omi"
  2. import { observe } from "omi-mobx"
  4. @observe
  5. @tag("my-app")
  6. class MyApp extends WeElement {
  7.   install() {
  8.     this.data.name = "omi"
  9.   }
  11.   onClick = () => {
  12.     this.data.name = "Omi V4.0"
  13.   }
  15.   render(props, data) {
  16.     return (
  17.       <div onClick={this.onClick}>
  18.         <h1>Welcome to {data.name}</h1>
  19.       </div>
  20.     )
  21.   }
  22. }

生命周期

Lifecycle method When it gets called
install before the component gets mounted to the DOM
installed after the component gets mounted to the DOM
uninstall prior to removal from the DOM
beforeUpdate before update
afterUpdate after update (deprecated)
updated after update
beforeRender before render()
receiveProps parent element re-render will trigger it

调试工具

使用 Omi 开发工具 可以非常简单地调试和管理你的 UI。不需要任何配置，你只要安装然后就能调试。

既然 Omi 使用了 Web Components 和 Shadow-DOM, 所以不需要像 React 和 Vue 一样安装其他元素面板，只需要使用 Chrome 自带的 Elements’ sidebar 便可，它和 React and Vue 开发者工具一样强大。

Omi DevTools

React 组件转成 Omi

举个例子，下面是吧 weui react 的 button 转成 weui omi 的 button 的例子 :

react to omi

浏览器兼容

Omi 4.0+ works in the latest two versions of all major browsers: Safari 10+, IE 11+, and the evergreen Chrome, Firefox, and Edge.

→ Browsers Support

→ polyfills

如果你想兼容IE11,使用→ 这个项目的 Omi 文件,这个项目使用 JSON Diff 和 定时器 代替 Proxy。

你可以在 IE9 的环境动态加载这个项目的 js，其他环境依旧使用 proxy 版本。

你也可以放弃 store 体系，使用 omi-mobx 来兼容IE11

贡献者们


README - 图13README - 图14README - 图15README - 图16README - 图17
README - 图18README - 图19README - 图20README - 图21README - 图22
README - 图23README - 图24README - 图25README - 图26README - 图27
README - 图28README - 图29README - 图30README - 图31README - 图32
README - 图33README - 图34README - 图35README - 图36README - 图37
README - 图38README - 图39README - 图40README - 图41README - 图42
README - 图43README - 图44README - 图45README - 图46

问答

任何 Omi 相关问题欢迎联系我们。也可以加入 Omi QQ 群进行讨论交流。

感谢

License

MIT © Tencent