@tarojs/taro-h5 3.3.20 → 3.4.0-beta.3

package/dist/api/ui/animation/index.js

@@ -1,3 +1,7 @@
+/**
+ * H5 下的 styleSheet 操作
+ * @author leeenx
+ */
 class StyleSheet {
     constructor() {
         this.appendStyleSheet = () => {
@@ -10,9 +14,11 @@ class StyleSheet {
                 console.warn('当前浏览器不支持 stylesheet.insertRule 接口');
             }
         };
+        // 添加样式命令
         this.add = (cssText, index = 0) => {
             var _a;
             if (this.sheet === null) {
+                // $style 未插入到 DOM
                 this.appendStyleSheet();
             }
             (_a = this.sheet) === null || _a === void 0 ? void 0 : _a.insertRule(cssText, index);
@@ -21,55 +27,73 @@ class StyleSheet {
     }
 }
 const styleSheet = new StyleSheet();
+// 监听事件
 let TRANSITION_END = 'transitionend';
 let TRANSFORM = 'transform';
 const $detect = document.createElement('div');
 $detect.style.cssText = '-webkit-animation-name:webkit;-moz-animation-name:moz;-ms-animation-name:ms;animation-name:standard;';
 if ($detect.style['animation-name'] === 'standard') {
+    // 支持标准写法
     TRANSITION_END = 'transitionend';
     TRANSFORM = 'transform';
 }
 else if ($detect.style['-webkit-animation-name'] === 'webkit') {
+    // webkit 前缀
     TRANSITION_END = 'webkitTransitionEnd';
     TRANSFORM = '-webkit-transform';
 }
 else if ($detect.style['-moz-animation-name'] === 'moz') {
+    // moz 前缀
     TRANSITION_END = 'mozTransitionEnd';
     TRANSFORM = '-moz-transform';
 }
 else if ($detect.style['-ms-animation-name'] === 'ms') {
+    // ms 前缀
     TRANSITION_END = 'msTransitionEnd';
     TRANSFORM = '-ms-transform';
 }
 let animId = 0;
 class Animation {
     constructor({ duration = 400, delay = 0, timingFunction = 'linear', transformOrigin = '50% 50% 0', unit = 'px' } = {}) {
+        // 属性组合
         this.rules = [];
+        // transform 对象
         this.transform = [`${TRANSFORM}:`];
+        // 组合动画
         this.steps = [];
+        // 动画 map ----- 永久保留
         this.animationMap = {};
+        // animationMap 的长度
         this.animationMapCount = 0;
+        // 默认值
         this.setDefault(duration, delay, timingFunction, transformOrigin);
         this.unit = unit;
+        // atom 环境下，animation 属性不会显示，所以要改成 data-animation
         let animAttr = 'animation';
+        // 动画 id
         this.id = ++animId;
+        // 监听事件
         document.body.addEventListener(TRANSITION_END, (e) => {
             const target = e.target;
             if (target.getAttribute(animAttr) === null) {
                 animAttr = 'data-animation';
             }
             const animData = target.getAttribute(animAttr);
+            // 没有动画存在
             if (animData === null)
                 return;
             const [animName, animPath] = animData.split('__');
             if (animName === `taro-h5-poly-fill/${this.id}/create-animation`) {
                 const [animIndex, __stepIndex = 0] = animPath.split('--');
                 const stepIndex = Number(__stepIndex);
+                // 动画总的关键帧
                 const animStepsCount = this.animationMap[`${animName}__${animIndex}`];
                 const animStepsMaxIndex = animStepsCount - 1;
                 if (stepIndex < animStepsMaxIndex) {
+                    // 播放下一个关键帧（因为 nerv 和 react 有差异所以 animation & data-animation 都需要写）
                     target.setAttribute(animAttr, `${animName}__${animIndex}--${stepIndex + 1}`);
                     if (animAttr === 'animation') {
+                        // Nerv 环境，animation & data-animation 双重保险
                         target.setAttribute('data-animation', `${animName}__${animIndex}--${stepIndex + 1}`);
                     }
                 }
@@ -83,6 +107,7 @@ class Animation {
         });
         return ret;
     }
+    // 设置默认值
     setDefault(duration, delay, timingFunction, transformOrigin) {
         this.DEFAULT = { duration, delay, timingFunction, transformOrigin };
     }
@@ -214,9 +239,11 @@ class Animation {
         this.rules.push(`left: ${value}`);
         return this;
     }
+    // 关键帧载入
     step(arg = {}) {
         const { DEFAULT } = this;
         const { duration = DEFAULT.duration, delay = DEFAULT.delay, timingFunction = DEFAULT.timingFunction, transformOrigin = DEFAULT.transformOrigin } = arg;
+        // 生成一条 transition 动画
         this.steps.push([
             this.rules.map(rule => `${rule}!important`).join(';'),
             `${this.transform.join(' ')}!important`,
@@ -225,26 +252,33 @@ class Animation {
         ]
             .filter(item => item !== '' && item !== `${TRANSFORM}:`)
             .join(';'));
+        // 清空 rules 和 transform
         this.rules = [];
         this.transform = [`${TRANSFORM}:`];
         return this;
     }
+    // 创建底层数据
     createAnimationData() {
         const animIndex = `taro-h5-poly-fill/${this.id}/create-animation__${this.animationMapCount++}`;
+        // 记录动画分几个 step
         this.animationMap[animIndex] = this.steps.length;
+        // 吐出 step
         this.steps.forEach((step, index) => {
             const selector = index === 0
                 ? `[animation="${animIndex}"], [data-animation="${animIndex}"]`
                 : `[animation="${animIndex}--${index}"], [data-animation="${animIndex}--${index}"]`;
             styleSheet.add(`${selector} { ${step} }`);
         });
+        // 清空 steps
         this.steps = [];
         return animIndex;
     }
+    // 动画数据产出
     export() {
         return this.createAnimationData();
     }
 }
+// h5 的 createAnimation
 export const createAnimation = (option) => {
     return new Animation(option);
 };

package/dist/api/ui/background.js

@@ -1,3 +1,4 @@
 import { temporarilyNotSupport } from '../utils';
+// 背景
 export const setBackgroundTextStyle = temporarilyNotSupport('setBackgroundTextStyle');
 export const setBackgroundColor = temporarilyNotSupport('setBackgroundColor');

package/dist/api/ui/custom-component.js

@@ -1,2 +1,3 @@
 import Taro from '@tarojs/api';
+// 自定义组件
 export const nextTick = Taro.nextTick;

package/dist/api/ui/fonts.js

@@ -1,2 +1,3 @@
 import { temporarilyNotSupport } from '../utils';
+// 字体
 export const loadFontFace = temporarilyNotSupport('loadFontFace');

package/dist/api/ui/interaction/actionSheet.js

@@ -54,25 +54,32 @@ export default class ActionSheet {
     }
     create(options = {}) {
         return new Promise((resolve) => {
+            // style
             const { maskStyle, actionSheetStyle, menuStyle, cellStyle, cancelStyle } = this.style;
+            // configuration
             const config = {
                 ...this.options,
                 ...options
             };
             this.lastConfig = config;
+            // wrapper
             this.el = document.createElement('div');
             this.el.className = 'taro__actionSheet';
             this.el.style.opacity = '0';
             this.el.style.transition = 'opacity 0.2s linear';
+            // mask
             const mask = document.createElement('div');
             mask.setAttribute('style', inlineStyle(maskStyle));
+            // actionSheet
             this.actionSheet = document.createElement('div');
             this.actionSheet.setAttribute('style', inlineStyle(actionSheetStyle));
+            // menu
             this.menu = document.createElement('div');
             this.menu.setAttribute('style', inlineStyle({
                 ...menuStyle,
                 color: config.itemColor
             }));
+            // cells
             this.cells = config.itemList.map((item, index) => {
                 const cell = document.createElement('div');
                 cell.className = 'taro-actionsheet__cell';
@@ -87,20 +94,24 @@ export default class ActionSheet {
                 };
                 return cell;
             });
+            // cancel
             this.cancel = document.createElement('div');
             this.cancel.setAttribute('style', inlineStyle(cancelStyle));
             this.cancel.textContent = '取消';
+            // result
             this.cells.forEach(item => this.menu.appendChild(item));
             this.actionSheet.appendChild(this.menu);
             this.actionSheet.appendChild(this.cancel);
             this.el.appendChild(mask);
             this.el.appendChild(this.actionSheet);
+            // callbacks
             const cb = () => {
                 this.hide();
                 resolve('cancel');
             };
             mask.onclick = cb;
             this.cancel.onclick = cb;
+            // show immediately
             document.body.appendChild(this.el);
             setTimeout(() => {
                 this.el.style.opacity = '1';
@@ -119,15 +130,19 @@ export default class ActionSheet {
                 clearTimeout(this.hideOpacityTimer);
             if (this.hideDisplayTimer)
                 clearTimeout(this.hideDisplayTimer);
+            // itemColor
             if (config.itemColor)
                 this.menu.style.color = config.itemColor;
+            // cells
             const { cellStyle } = this.style;
             config.itemList.forEach((item, index) => {
                 let cell;
                 if (this.cells[index]) {
+                    // assign new content
                     cell = this.cells[index];
                 }
                 else {
+                    // create new cell
                     cell = document.createElement('div');
                     cell.className = 'taro-actionsheet__cell';
                     cell.setAttribute('style', inlineStyle(cellStyle));
@@ -151,6 +166,7 @@ export default class ActionSheet {
                 }
                 this.cells.splice(itemListLen);
             }
+            // show
             this.el.style.display = 'block';
             setTimeout(() => {
                 this.el.style.opacity = '1';

package/dist/api/ui/interaction/index.js

@@ -4,7 +4,9 @@ import { MethodHandler } from '../../utils/handler';
 import Toast from './toast';
 import Modal from './modal';
 import ActionSheet from './actionSheet';
+// 交互
 let status = 'default';
+// inject necessary style
 function init(doc) {
     if (status === 'ready')
         return;
@@ -182,14 +184,16 @@ const showModal = async (options = {}) => {
         });
     }
     options.showCancel = !!options.showCancel;
-    let errMsg = '';
+    let result = '';
     if (!modal.el) {
-        errMsg = await modal.create(options);
+        result = await modal.create(options);
     }
     else {
-        errMsg = await modal.show(options);
+        result = await modal.show(options);
     }
-    return handle.success({ errMsg });
+    const res = { cancel: !1, confirm: !1 };
+    res[result] = !0;
+    return handle.success(res);
 };
 function hideModal() {
     if (!modal.el)
@@ -204,6 +208,7 @@ const showActionSheet = async (options = { itemList: [] }) => {
     }, options);
     const { success, fail, complete } = options;
     const handle = new MethodHandler({ name: 'showActionSheet', success, fail, complete });
+    // list item String
     if (!Array.isArray(options.itemList)) {
         return handle.fail({
             errMsg: getParameterError({

package/dist/api/ui/interaction/modal.js

@@ -61,21 +61,27 @@ export default class Modal {
     }
     create(options = {}) {
         return new Promise((resolve) => {
+            // style
             const { maskStyle, modalStyle, titleStyle, textStyle, footStyle, btnStyle } = this.style;
+            // configuration
             const config = {
                 ...this.options,
                 ...options
             };
+            // wrapper
             this.el = document.createElement('div');
             this.el.className = 'taro__modal';
             this.el.style.opacity = '0';
             this.el.style.transition = 'opacity 0.2s linear';
+            // mask
             const mask = document.createElement('div');
             mask.className = 'taro-modal__mask';
             mask.setAttribute('style', inlineStyle(maskStyle));
+            // modal
             const modal = document.createElement('div');
             modal.className = 'taro-modal__content';
             modal.setAttribute('style', inlineStyle(modalStyle));
+            // title
             const titleCSS = config.title ? titleStyle : {
                 ...titleStyle,
                 display: 'none'
@@ -84,6 +90,7 @@ export default class Modal {
             this.title.className = 'taro-modal__title';
             this.title.setAttribute('style', inlineStyle(titleCSS));
             this.title.textContent = config.title;
+            // text
             const textCSS = config.title ? textStyle : {
                 ...textStyle,
                 padding: '40px 20px 26px',
@@ -93,9 +100,11 @@ export default class Modal {
             this.text.className = 'taro-modal__text';
             this.text.setAttribute('style', inlineStyle(textCSS));
             this.text.textContent = config.content;
+            // foot
             const foot = document.createElement('div');
             foot.className = 'taro-modal__foot';
             foot.setAttribute('style', inlineStyle(footStyle));
+            // cancel button
             const cancelCSS = {
                 ...btnStyle,
                 color: config.cancelColor,
@@ -109,6 +118,7 @@ export default class Modal {
                 this.hide();
                 resolve('cancel');
             };
+            // confirm button
             this.confirm = document.createElement('div');
             this.confirm.className = 'taro-model__btn taro-model__confirm';
             this.confirm.setAttribute('style', inlineStyle(btnStyle));
@@ -118,6 +128,7 @@ export default class Modal {
                 this.hide();
                 resolve('confirm');
             };
+            // result
             foot.appendChild(this.cancel);
             foot.appendChild(this.confirm);
             modal.appendChild(this.title);
@@ -125,6 +136,7 @@ export default class Modal {
             modal.appendChild(foot);
             this.el.appendChild(mask);
             this.el.appendChild(modal);
+            // show immediately
             document.body.appendChild(this.el);
             setTimeout(() => { this.el.style.opacity = '1'; }, 0);
         });
@@ -139,13 +151,16 @@ export default class Modal {
                 clearTimeout(this.hideOpacityTimer);
             if (this.hideDisplayTimer)
                 clearTimeout(this.hideDisplayTimer);
+            // title & text
             const { textStyle } = this.style;
             if (config.title) {
                 this.title.textContent = config.title;
+                // none => block
                 this.title.style.display = 'block';
                 this.text.setAttribute('style', inlineStyle(textStyle));
             }
             else {
+                // block => none
                 this.title.style.display = 'none';
                 const textCSS = {
                     ...textStyle,
@@ -155,11 +170,17 @@ export default class Modal {
                 this.text.setAttribute('style', inlineStyle(textCSS));
             }
             this.text.textContent = config.content || '';
+            // showCancel
             this.cancel.style.display = config.showCancel ? 'block' : 'none';
+            // cancelText
             this.cancel.textContent = config.cancelText || '';
+            // cancelColor
             this.cancel.style.color = config.cancelColor || '';
+            // confirmText
             this.confirm.textContent = config.confirmText || '';
+            // confirmColor
             this.confirm.style.color = config.confirmColor || '';
+            // cbs
             this.cancel.onclick = () => {
                 this.hide();
                 resolve('cancel');
@@ -168,6 +189,7 @@ export default class Modal {
                 this.hide();
                 resolve('confirm');
             };
+            // show
             this.el.style.display = 'block';
             setTimeout(() => { this.el.style.opacity = '1'; }, 0);
         });

package/dist/api/ui/interaction/toast.js

@@ -75,19 +75,24 @@ export default class Toast {
         };
     }
     create(options = {}, _type = 'toast') {
+        // style
         const { maskStyle, toastStyle, successStyle, errrorStyle, loadingStyle, imageStyle, textStyle } = this.style;
+        // configuration
         const config = {
             ...this.options,
             ...options,
             _type
         };
+        // wrapper
         this.el = document.createElement('div');
         this.el.className = 'taro__toast';
         this.el.style.opacity = '0';
         this.el.style.transition = 'opacity 0.1s linear';
+        // mask
         this.mask = document.createElement('div');
         this.mask.setAttribute('style', inlineStyle(maskStyle));
         this.mask.style.display = config.mask ? 'block' : 'none';
+        // icon
         this.icon = document.createElement('p');
         if (config.image) {
             this.icon.setAttribute('style', inlineStyle({
@@ -102,6 +107,7 @@ export default class Toast {
                 ...(config.icon === 'none' ? { display: 'none' } : {})
             }));
         }
+        // toast
         this.toast = document.createElement('div');
         this.toast.setAttribute('style', inlineStyle({
             ...toastStyle,
@@ -110,16 +116,20 @@ export default class Toast {
                 padding: '10px 15px'
             } : {})
         }));
+        // title
         this.title = document.createElement('p');
         this.title.setAttribute('style', inlineStyle(textStyle));
         this.title.textContent = config.title;
+        // result
         this.toast.appendChild(this.icon);
         this.toast.appendChild(this.title);
         this.el.appendChild(this.mask);
         this.el.appendChild(this.toast);
+        // show immediately
         document.body.appendChild(this.el);
         setTimeout(() => { this.el.style.opacity = '1'; }, 0);
         this.type = config._type;
+        // disappear after duration
         config.duration >= 0 && this.hide(config.duration, this.type);
         return '';
     }
@@ -133,8 +143,11 @@ export default class Toast {
             clearTimeout(this.hideOpacityTimer);
         if (this.hideDisplayTimer)
             clearTimeout(this.hideDisplayTimer);
+        // title
         this.title.textContent = config.title || '';
+        // mask
         this.mask.style.display = config.mask ? 'block' : 'none';
+        // image
         const { toastStyle, successStyle, errrorStyle, loadingStyle, imageStyle } = this.style;
         if (config.image) {
             this.icon.setAttribute('style', inlineStyle({
@@ -151,6 +164,7 @@ export default class Toast {
                 }));
             }
         }
+        // toast
         this.toast.setAttribute('style', inlineStyle({
             ...toastStyle,
             ...(config.icon === 'none' ? {
@@ -158,9 +172,11 @@ export default class Toast {
                 padding: '10px 15px'
             } : {})
         }));
+        // show
         this.el.style.display = 'block';
         setTimeout(() => { this.el.style.opacity = '1'; }, 0);
         this.type = config._type;
+        // disappear after duration
         config.duration >= 0 && this.hide(config.duration, this.type);
         return '';
     }

package/dist/api/ui/menu.js

@@ -1,2 +1,3 @@
 import { temporarilyNotSupport } from '../utils';
+// 菜单
 export const getMenuButtonBoundingClientRect = temporarilyNotSupport('getMenuButtonBoundingClientRect');

package/dist/api/ui/navigation-bar/index.js

@@ -1,7 +1,9 @@
 import { MethodHandler } from '../../utils/handler';
 import { getParameterError, shouldBeObject, temporarilyNotSupport } from '../../utils';
+// 导航栏
 export const showNavigationBarLoading = temporarilyNotSupport('showNavigationBarLoading');
 export function setNavigationBarTitle(options) {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `setNavigationBarTitle:fail ${isObject.msg}` };
@@ -24,6 +26,9 @@ export function setNavigationBarTitle(options) {
     }
     return handle.success();
 }
+/**
+ * 设置页面导航条颜色
+ */
 export const setNavigationBarColor = (options) => {
     const { backgroundColor, success, fail, complete } = options;
     const handle = new MethodHandler({ name: 'setNavigationBarColor', success, fail, complete });

package/dist/api/ui/pull-down-refresh.js

@@ -1,5 +1,8 @@
 import Taro from '@tarojs/api';
 import { MethodHandler } from '../utils/handler';
+/**
+ * 开始下拉刷新。调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。
+ */
 export const startPullDownRefresh = function ({ success, fail, complete } = {}) {
     const handle = new MethodHandler({ name: 'startPullDownRefresh', success, fail, complete });
     return new Promise((resolve, reject) => {
@@ -9,6 +12,9 @@ export const startPullDownRefresh = function ({ success, fail, complete } = {})
         });
     });
 };
+/**
+ * 停止当前页面下拉刷新。
+ */
 export const stopPullDownRefresh = function ({ success, fail, complete } = {}) {
     const handle = new MethodHandler({ name: 'stopPullDownRefresh', success, fail, complete });
     return new Promise((resolve, reject) => {

package/dist/api/ui/scroll/index.js

@@ -3,6 +3,9 @@ import { MethodHandler } from '../../utils/handler';
 import { getTimingFunc, easeInOut } from '../../utils';
 let timer;
 const FRAME_DURATION = 17;
+/**
+ * 将页面滚动到目标位置
+ */
 export const pageScrollTo = ({ scrollTop, selector = '', duration = 300, success, fail, complete }) => {
     let scrollFunc;
     const handle = new MethodHandler({ name: 'pageScrollTo', success, fail, complete });

package/dist/api/ui/sticky.js

@@ -1,2 +1,3 @@
 import { temporarilyNotSupport } from '../utils';
+// 置顶
 export const setTopBarText = temporarilyNotSupport('setTopBarText');

package/dist/api/ui/tab-bar.js

@@ -5,7 +5,11 @@ let tabConf;
 export function initTabBarApis(config = {}) {
     tabConf = config.tabBar;
 }
+/**
+ * 显示 tabBar 某一项的右上角的红点
+ */
 export const showTabBarRedDot = (options) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `showTabBarRedDot:fail ${isObject.msg}` };
@@ -31,7 +35,11 @@ export const showTabBarRedDot = (options) => {
         });
     });
 };
+/**
+ * 显示 tabBar
+ */
 export const showTabBar = (options = {}) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `showTabBar:fail ${isObject.msg}` };
@@ -57,7 +65,11 @@ export const showTabBar = (options = {}) => {
         });
     });
 };
+/**
+ * 动态设置 tabBar 的整体样式
+ */
 export const setTabBarStyle = (options = {}) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `setTabBarStyle:fail ${isObject.msg}` };
@@ -105,7 +117,11 @@ export const setTabBarStyle = (options = {}) => {
         });
     });
 };
+/**
+ * 动态设置 tabBar 某一项的内容
+ */
 export const setTabBarItem = (options) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `setTabBarItem:fail ${isObject.msg}` };
@@ -134,7 +150,11 @@ export const setTabBarItem = (options) => {
         });
     });
 };
+/**
+ * 为 tabBar 某一项的右上角添加文本
+ */
 export const setTabBarBadge = (options) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `setTabBarBadge:fail ${isObject.msg}` };
@@ -170,7 +190,11 @@ export const setTabBarBadge = (options) => {
         });
     });
 };
+/**
+ * 移除 tabBar 某一项右上角的文本
+ */
 export const removeTabBarBadge = (options) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `removeTabBarBadge:fail ${isObject.msg}` };
@@ -196,7 +220,11 @@ export const removeTabBarBadge = (options) => {
         });
     });
 };
+/**
+ * 隐藏 tabBar 某一项的右上角的红点
+ */
 export const hideTabBarRedDot = (options) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `hideTabBarRedDot:fail ${isObject.msg}` };
@@ -222,7 +250,11 @@ export const hideTabBarRedDot = (options) => {
         });
     });
 };
+/**
+ * 隐藏 tabBar
+ */
 export const hideTabBar = (options = {}) => {
+    // options must be an Object
     const isObject = shouldBeObject(options);
     if (!isObject.flag) {
         const res = { errMsg: `hideTabBar:fail ${isObject.msg}` };

package/dist/api/ui/window.js

@@ -7,13 +7,22 @@ const resizeListener = () => {
         windowHeight: window.screen.height
     });
 };
+/**
+ * 设置窗口大小，该接口仅适用于 PC 平台，使用细则请参见指南
+ */
 export const setWindowSize = temporarilyNotSupport('setWindowSize');
+/**
+ * 监听窗口尺寸变化事件
+ */
 export const onWindowResize = callback => {
     callbackManager.add(callback);
     if (callbackManager.count() === 1) {
         window.addEventListener('resize', resizeListener);
     }
 };
+/**
+ * 取消监听窗口尺寸变化事件
+ */
 export const offWindowResize = callback => {
     callbackManager.remove(callback);
     if (callbackManager.count() === 0) {