diff --git a/docs/api/ui/media-query-observer.md b/docs/api/ui/media-query-observer.md
new file mode 100644
index 0000000000000000000000000000000000000000..8a38859aa93446df86694059efe9723ee728b7e3
--- /dev/null
+++ b/docs/api/ui/media-query-observer.md
@@ -0,0 +1,105 @@
+MediaQueryObserver 对象,用于监听页面 media query 状态的变化,如界面的长宽是不是在某个指定的范围内。
+
+### uni.createMediaQueryObserver([this])
+创建并返回一个 ``MediaQueryObserver`` 对象实例。
+
+**this说明:**
+
+自定义组件实例。**支付宝小程序不支持此参数,传入仅为抹平写法差异**
+
+### MediaQueryObserver 对象的方法列表
+
+|方法|说明|
+|:-|:-|
+|MediaQueryObserver.observe(Object descriptor, function callback)|开始监听页面 media query 变化情况|
+|MediaQueryObserver.disconnect()|停止监听,回调函数将不再触发|
+
+**observe 回调函数包含一个参数**
+
+||类型|说明|
+|:-|:-|:-|
+|intersectionRatio|boolean|页面的当前状态是否满足所指定的 media query|
+
+### 代码示例
+
+```
+
+
+
+ matches: {{matches}}
+
+
+ landscape: {{landscape}}
+
+
+
+
+
+
+
+
+
+```