diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 574ad5b622..077c0a146a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -12,8 +12,8 @@ jobs: - uses: technote-space/get-diff-action@v4 with: PATTERNS: | - +(docs|docs-vuepress)/**/* - +(docs|docs-vuepress)/.*/**/* + +(docs|docs-vitepress)/**/* + +(docs|docs-vitepress)/.*/**/* # vuepress生成最终文档 - name: generate docs file if: env.GIT_DIFF @@ -30,6 +30,6 @@ jobs: username: ${{ secrets.DOCS_SERVER_USER }} key: ${{ secrets.DOCS_SERVER_KEY }} command_timeout: "20m" - source: "./docs-vuepress/.vuepress/dist/" + source: "./docs-vitepress/.vitepress/dist/" strip_components: 4 target: "${{ secrets.DOCS_SERVER_DIR }}" diff --git a/.gitignore b/.gitignore index 684ff00936..4680643a94 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,8 @@ package-lock.json pnpm-lock.yaml yarn.lock .DS_Store -docs-vuepress/.vuepress/dist elevate/ -packages/webpack-plugin/lib/runtime/components/react/dist/ \ No newline at end of file +docs-vitepress/.vitepress/dist +docs-vitepress/.vitepress/cache +dev-dist +packages/webpack-plugin/lib/runtime/components/react/dist/ diff --git a/docs-vitepress/.vitepress/config.ts b/docs-vitepress/.vitepress/config.ts new file mode 100644 index 0000000000..a3870bc392 --- /dev/null +++ b/docs-vitepress/.vitepress/config.ts @@ -0,0 +1,349 @@ +import { defineConfig } from "vitepress" +import { withPwa } from "@vite-pwa/vitepress" + +const sidebar = { + "/guide/": [ + { + text: "基础", + collapsable: false, + items: [ + { text: "快速开始", link: "/guide/basic/start" }, + { text: "介绍", link: "/guide/basic/intro" }, + { text: "单文件开发", link: "/guide/basic/single-file" }, + { text: "IDE 高亮配置", link: "/guide/basic/ide" }, + { text: "模板语法", link: "/guide/basic/template" }, + { text: "CSS 处理", link: "/guide/basic/css" }, + { text: "数据响应", link: "/guide/basic/reactive" }, + { + text: "类名样式绑定", + link: "/guide/basic/class-style-binding", + }, + { text: "条件渲染", link: "/guide/basic/conditional-render" }, + { text: "列表渲染", link: "/guide/basic/list-render" }, + { text: "事件处理", link: "/guide/basic/event" }, + { text: "双向绑定", link: "/guide/basic/two-way-binding" }, + { text: "自定义组件", link: "/guide/basic/component" }, + { text: "获取组件实例/节点信息", link: "/guide/basic/refs" }, + { + text: "模版内可选链表达式", + link: "/guide/basic/option-chain", + }, + ], + }, + { + text: "进阶", + collapsable: false, + items: [ + { text: "状态管理（store）", link: "/guide/advance/store" }, + { text: "状态管理（pinia）", link: "/guide/advance/pinia" }, + { text: "使用 mixin", link: "/guide/advance/mixin" }, + { text: "使用 npm", link: "/guide/advance/npm" }, + { text: "使用分包", link: "/guide/advance/subpackage" }, + { text: "分包异步化", link: "/guide/advance/async-subpackage" }, + { text: "跨平台", link: "/guide/advance/platform" }, + { text: "国际化 i18n", link: "/guide/advance/i18n" }, + { text: "包体积分析", link: "/guide/advance/size-report" }, + { text: "图像资源处理", link: "/guide/advance/image-process" }, + { text: "原生渐进迁移", link: "/guide/advance/progressive" }, + { + text: "原生能力兼容", + link: "/guide/advance/ability-compatible", + }, + { text: "小程序插件", link: "/guide/advance/plugin" }, + { + text: "自定义路径", + link: "/guide/advance/custom-output-path", + }, + { + text: "使用原子类", + link: "/guide/advance/utility-first-css", + }, + { text: "SSR", link: "/guide/advance/ssr" }, + { + text: "依赖注入（Provide/Inject）", + link: "/guide/advance/provide-inject", + }, + { text: "编译配置", link: "/guide/advance/build-config" }, + ], + }, + { + text: "跨端", + collapsable: false, + items: [ + { text: "跨端输出基础", link: "/guide/platform/basic" }, + { text: "跨端输出 RN", link: "/guide/platform/rn" }, + ], + }, + { + text: "组合式 API", + collapsable: false, + items: [ + { + text: "组合式 API", + link: "/guide/composition-api/composition-api", + }, + { + text: "响应式 API", + link: "/guide/composition-api/reactive-api", + }, + ], + }, + { + text: "工具", + collapsable: false, + items: [ + { text: "使用TypeScript开发小程序", link: "/guide/tool/ts" }, + { text: "单元测试", link: "/guide/tool/unit-test" }, + { text: "E2E自动化测试", link: "/guide/tool/e2e-test" }, + ], + }, + { + text: "拓展", + collapsable: false, + items: [ + { text: "网络请求", link: "/guide/extend/fetch" }, + { text: "API 转换", link: "/guide/extend/api-proxy" }, + { text: "数据 Mock", link: "/guide/extend/mock" }, + ], + }, + { + text: "理解", + collapsable: false, + items: [ + { + text: "Mpx运行时增强原理", + link: "/guide/understand/runtime", + }, + { text: "Mpx编译构建原理", link: "/guide/understand/compile" }, + ], + }, + { + text: "迁移", + collapsable: false, + items: [ + { text: "从 2.8 升级至 2.9", link: "/guide/migrate/2.9" }, + { text: "从 2.7 升级至 2.8", link: "/guide/migrate/2.8" }, + { text: "从旧版本迁移至 2.7", link: "/guide/migrate/2.7" }, + { + text: "mpx-cli v2 迁移到 v3", + link: "/guide/migrate/mpx-cli-3", + }, + ], + }, + ], + "/api/": [ + { + text: "API", + collapsable: false, + items: [ + { text: "API 参考", link: "/api/" }, + { text: "全局配置", link: "/api/app-config" }, + { text: "全局 API", link: "/api/global-api" }, + { text: "实例 API", link: "/api/instance-api" }, + { text: "Store API", link: "/api/store-api" }, + { text: "模板指令", link: "/api/directives" }, + { text: "编译构建", link: "/api/compile" }, + { text: "内建组件", link: "/api/builtIn" }, + { text: "响应式 API", link: "/api/reactivity-api" }, + { text: "组合式 API", link: "/api/composition-api" }, + { text: "选项式 API", link: "/api/optional-api" }, + { text: "周边拓展", link: "/api/extend" }, + ], + }, + ], + "/articles/": [ + { + text: "文章", + collapsable: false, + items: [ + { text: "滴滴开源小程序框架Mpx", link: "/articles/1.0" }, + { + text: "Mpx 发布2.0，完美支持跨平台开发", + link: "/articles/2.0", + }, + { + text: "小程序框架运行时性能大测评", + link: "/articles/performance", + }, + { + text: "小程序开发者，为什么你应该尝试下MPX", + link: "/articles/mpx1", + }, + { text: "Mpx 小程序框架技术揭秘", link: "/articles/mpx2" }, + { + text: "滴滴出行小程序体积优化实践", + link: "/articles/size-control", + }, + { + text: "使用Typescript新特性Template Literal Types完善链式key的类型推导", + link: "/articles/ts-derivation", + }, + { + text: "Mpx2.7 版本正式发布，大幅提升编译构建速度", + link: "/articles/2.7-release", + }, + { + text: "Mpx2.8 版本正式发布，使用组合式 API 开发小程序", + link: "/articles/2.8-release", + }, + { + text: "Mpx2.9 版本正式发布，支持原子类、SSR 和包体积优化", + link: "/articles/2.9-release", + }, + { + text: "小程序跨端组件库 Mpx-cube-ui 开源啦", + link: "/articles/mpx-cube-ui", + }, + { + text: "@mpxjs/cli 插件化改造", + link: "/articles/mpx-cli-next", + }, + { + text: "Mpx 小程序单元测试能力建设与实践", + link: "/articles/unit-test", + }, + ], + }, + ], +} + +const ogUrl = "https://mpxjs.cn/" +const ogImage = `${ogUrl}logo.png` +const title = "Mpx 框架" +const description = "深度性能优化的增强型小程序开发框架" + +export default withPwa( + defineConfig({ + base: "/", + head: [ + ["link", { rel: "icon", href: "/favicon.ico" }], + [ + "script", + { type: "text/javascript" }, + `(function(c,l,a,r,i,t,y){ + c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)}; + t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i; + y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y); + })(window, document, "clarity", "script", "jtvvy52wxy");`, + ], + ["meta", { name: "author", content: title }], + ["meta", { property: "og:type", content: "website" }], + ["meta", { name: "og:title", content: title }], + ["meta", { name: "og:description", content: description }], + ["meta", { property: "og:image", content: ogImage }], + ["meta", { property: "og:url", content: ogUrl }], + ], + title, + locales: { + // 如果有其他语言，也可以在这里添加 + // '/zh/': { + // prev: '上一页', + // }, + "/": { + label: "中文", + lang: "zh-CN", // 将会被设置为 的 lang 属性 + title, + description, + }, + }, + ignoreDeadLinks: true, + pwa: { + base: "/", + scope: "/", + includeAssets: ["favicon.ico", "logo.png"], + manifest: { + name: title, + short_name: "Mpx", + description, + theme_color: "#ffffff", + // icons: [ + // { + // src: 'pwa-192x192.png', + // sizes: '192x192', + // type: 'image/png', + // }, + // { + // src: 'pwa-512x512.png', + // sizes: '512x512', + // type: 'image/png', + // }, + // { + // src: 'pwa-512x512.png', + // sizes: '512x512', + // type: 'image/png', + // purpose: 'any maskable', + // }, + // ], + }, + workbox: { + globPatterns: ["**/*.{css,js,html,svg,png,ico,txt,woff2}"], + }, + devOptions: { + enabled: false, + suppressWarnings: true, + navigateFallback: "/", + }, + }, + themeConfig: { + // navbar: false, + algolia: { + // apiKey: '7849f511f78afc4383a81f0137a91c0f', + appId: "DZ8S6HN0MP", + apiKey: "a34809e24ae1eb13ca3afc255d0a0cef", + indexName: "mpxjs", + placeholder: "搜索文档", + translations: { + button: { + buttonText: "搜索", + }, + }, + }, + logo: "/favicon.ico", + docFooter: { + prev: "上一页", + next: "下一页", + }, + outline: { + level: [2, 3], + label: "本页目录", + }, + socialLinks: [ + { icon: "github", link: "https://github.com/didi/mpx" }, + ], + nav: [ + { + text: "指南", + activeMatch: "^/guide/", + link: "/guide/basic/start", + }, + // 未来热门的链接可以用下面的折叠标题 + // { + // text: "文档", + // activeMatch: "^/guide/(basic/start|platform/basic)/", + // items: [ + // { text: "快速开始", link: "/guide/basic/start" }, + // { text: "跨端输出", link: "/guide/platform/basic" }, + // ], + // }, + { text: "API", activeMatch: "^/api/", link: "/api/" }, + { + text: "文章", + activeMatch: "^/articles/", + link: "/articles/", + }, + { + text: "更新记录", + activeMatch: "^/releases/", + link: "https://github.com/didi/mpx/releases", + target: "_blank", + }, + ], + sidebar, + }, + // @ts-ignore + chainWebpack: (config) => { + // 添加node_modules避免resolve错误 + config.resolve.modules.add("node_modules") + }, + }) +) diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 new file mode 100644 index 0000000000..b6b603d596 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-cyrillic.By2_1cv3.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-cyrillic.By2_1cv3.woff2 new file mode 100644 index 0000000000..def40a4f65 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-cyrillic.By2_1cv3.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-greek-ext.1u6EdAuj.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-greek-ext.1u6EdAuj.woff2 new file mode 100644 index 0000000000..e070c3d309 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-greek-ext.1u6EdAuj.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-greek.DJ8dCoTZ.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-greek.DJ8dCoTZ.woff2 new file mode 100644 index 0000000000..a3c16ca40b Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-greek.DJ8dCoTZ.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-latin-ext.CN1xVJS-.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-latin-ext.CN1xVJS-.woff2 new file mode 100644 index 0000000000..2210a899ed Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-latin-ext.CN1xVJS-.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-latin.C2AdPX0b.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-latin.C2AdPX0b.woff2 new file mode 100644 index 0000000000..790d62dc7b Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-latin.C2AdPX0b.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-italic-vietnamese.BSbpV94h.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-italic-vietnamese.BSbpV94h.woff2 new file mode 100644 index 0000000000..1eec0775a6 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-italic-vietnamese.BSbpV94h.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 new file mode 100644 index 0000000000..2cfe61536e Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 new file mode 100644 index 0000000000..e3886dd141 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 new file mode 100644 index 0000000000..36d67487dc Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-greek.BBVDIX6e.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-greek.BBVDIX6e.woff2 new file mode 100644 index 0000000000..2bed1e85e8 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-greek.BBVDIX6e.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 new file mode 100644 index 0000000000..9a8d1e2b5e Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-latin.Di8DUHzh.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-latin.Di8DUHzh.woff2 new file mode 100644 index 0000000000..07d3c53aef Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-latin.Di8DUHzh.woff2 differ diff --git a/docs-vitepress/.vitepress/dist/assets/inter-roman-vietnamese.BjW4sHH5.woff2 b/docs-vitepress/.vitepress/dist/assets/inter-roman-vietnamese.BjW4sHH5.woff2 new file mode 100644 index 0000000000..57bdc22ae8 Binary files /dev/null and b/docs-vitepress/.vitepress/dist/assets/inter-roman-vietnamese.BjW4sHH5.woff2 differ diff --git a/docs-vuepress/assets/images/start-tips1.png b/docs-vitepress/.vitepress/dist/assets/start-tips1.B10pt_bp.png similarity index 100% rename from docs-vuepress/assets/images/start-tips1.png rename to docs-vitepress/.vitepress/dist/assets/start-tips1.B10pt_bp.png diff --git a/docs-vuepress/assets/images/start-tips2.png b/docs-vitepress/.vitepress/dist/assets/start-tips2.DL_IWEZM.png similarity index 100% rename from docs-vuepress/assets/images/start-tips2.png rename to docs-vitepress/.vitepress/dist/assets/start-tips2.DL_IWEZM.png diff --git a/docs-vuepress/.vuepress/theme/components/AlgoliaSearchBox.vue b/docs-vitepress/.vitepress/theme/components/AlgoliaSearchBox.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/AlgoliaSearchBox.vue rename to docs-vitepress/.vitepress/theme/components/AlgoliaSearchBox.vue diff --git a/docs-vuepress/.vuepress/theme/components/CodeList.vue b/docs-vitepress/.vitepress/theme/components/CodeList.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/CodeList.vue rename to docs-vitepress/.vitepress/theme/components/CodeList.vue diff --git a/docs-vuepress/.vuepress/theme/components/MobileSwiper.vue b/docs-vitepress/.vitepress/theme/components/MobileSwiper.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/MobileSwiper.vue rename to docs-vitepress/.vitepress/theme/components/MobileSwiper.vue diff --git a/docs-vuepress/.vuepress/theme/components/MobileView.vue b/docs-vitepress/.vitepress/theme/components/MobileView.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/MobileView.vue rename to docs-vitepress/.vitepress/theme/components/MobileView.vue diff --git a/docs-vuepress/.vuepress/theme/components/Navbar.vue b/docs-vitepress/.vitepress/theme/components/Navbar.vue similarity index 63% rename from docs-vuepress/.vuepress/theme/components/Navbar.vue rename to docs-vitepress/.vitepress/theme/components/Navbar.vue index 517d62686b..67e13ff6a3 100644 --- a/docs-vuepress/.vuepress/theme/components/Navbar.vue +++ b/docs-vitepress/.vitepress/theme/components/Navbar.vue @@ -36,71 +36,91 @@ @@ -235,7 +255,7 @@ a.router-link-active { height: 60px; line-height: 60px; padding: 0 16px; - display: flex + display: flex; align-items: center; justify-content: space-between; box-sizing: border-box; diff --git a/docs-vuepress/.vuepress/theme/components/Popover.vue b/docs-vitepress/.vitepress/theme/components/Popover.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/Popover.vue rename to docs-vitepress/.vitepress/theme/components/Popover.vue diff --git a/docs-vitepress/.vitepress/theme/components/RegisterSW.vue b/docs-vitepress/.vitepress/theme/components/RegisterSW.vue new file mode 100644 index 0000000000..705ced5dd9 --- /dev/null +++ b/docs-vitepress/.vitepress/theme/components/RegisterSW.vue @@ -0,0 +1,104 @@ + + + + + diff --git a/docs-vuepress/.vuepress/theme/components/SlideItem.vue b/docs-vitepress/.vitepress/theme/components/SlideItem.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/SlideItem.vue rename to docs-vitepress/.vitepress/theme/components/SlideItem.vue diff --git a/docs-vuepress/.vuepress/theme/components/Swiper.vue b/docs-vitepress/.vitepress/theme/components/Swiper.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/Swiper.vue rename to docs-vitepress/.vitepress/theme/components/Swiper.vue diff --git a/docs-vuepress/.vuepress/theme/components/SwiperImg.vue b/docs-vitepress/.vitepress/theme/components/SwiperImg.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/components/SwiperImg.vue rename to docs-vitepress/.vitepress/theme/components/SwiperImg.vue diff --git a/docs-vuepress/.vuepress/theme/global-components/Content.vue b/docs-vitepress/.vitepress/theme/global-components/Content.vue similarity index 85% rename from docs-vuepress/.vuepress/theme/global-components/Content.vue rename to docs-vitepress/.vitepress/theme/global-components/Content.vue index f204c5a218..d56897d0db 100644 --- a/docs-vuepress/.vuepress/theme/global-components/Content.vue +++ b/docs-vitepress/.vitepress/theme/global-components/Content.vue @@ -7,18 +7,18 @@
-

{{$page.frontmatter.heroText}}

+

{{$frontmatter.heroText}}

- {{$page.frontmatter.tagline}} + {{$frontmatter.tagline}}

@@ -29,7 +29,7 @@
    -
  • +
  • svg

    {{item.title}}

    {{item.details}}

    @@ -39,26 +39,26 @@
-
+
phone + width="410" + height="712" + src="https://dpubstatic.udache.com/static/dpubimg/Vx5n_3YCtP/anli_pic_phone.png" + alt="phone" + loading="lazy" />
@@ -66,7 +66,7 @@
-

{{$page.frontmatter.threeSection.title}}

+

{{$frontmatter.threeSection.title}}

扫码体验Mpx版本的 @@ -88,13 +88,13 @@

-
+
svg
@@ -102,14 +102,14 @@
-

{{$page.frontmatter.fourSection.title}}

+

{{$frontmatter.fourSection && $frontmatter.fourSection.title}}

- {{$page.frontmatter.fourSection.details}} + {{$frontmatter.fourSection.details}}

@@ -119,21 +119,21 @@
-
+
-

{{$page.frontmatter.fiveSection.title}}

+

{{$frontmatter.fiveSection.title}}

- {{$page.frontmatter.fiveSection.details}} + {{$frontmatter.fiveSection.details}}

@@ -141,7 +141,7 @@
svg
@@ -150,12 +150,12 @@
-
+
-

{{$page.frontmatter.sixSection.title}}

+

{{$frontmatter.sixSection.title}}

  • @@ -175,7 +175,7 @@
    -

    {{$page.frontmatter.sevenSection.title}}

    +

    {{$frontmatter.sevenSection.title}}

    @@ -184,7 +184,7 @@

    -
    +
    @@ -22,9 +22,9 @@
    • - {{$page.frontmatter.communityList.title}} + {{$frontmatter.communityList.title}}
      • -
    • +
    • {{item.title}} @@ -35,9 +35,9 @@
      • - {{$page.frontmatter.helpList.title}} + {{$frontmatter.helpList.title}}
        • -
      • +
      • {{item.title}}
      @@ -45,9 +45,9 @@
      • - {{$page.frontmatter.moreList.title}} + {{$frontmatter.moreList.title}}
        • -
      • +
      • {{item.title}}
      @@ -150,7 +150,7 @@ ul li @media (max-width: 750px) { .footer__list { - margin-bottom 16px + margin-bottom 16px } .footer__text { @@ -167,7 +167,7 @@ ul li } .footer-container { - background #606D7C + background #606D7C height auto margin-top 0 } diff --git a/docs-vuepress/.vuepress/theme/global-components/Header.vue b/docs-vitepress/.vitepress/theme/global-components/Header.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/global-components/Header.vue rename to docs-vitepress/.vitepress/theme/global-components/Header.vue diff --git a/docs-vitepress/.vitepress/theme/index.js b/docs-vitepress/.vitepress/theme/index.js new file mode 100644 index 0000000000..8c1acdd39b --- /dev/null +++ b/docs-vitepress/.vitepress/theme/index.js @@ -0,0 +1,24 @@ +import { h } from 'vue' +import DefaultTheme from 'vitepress/theme' +import Layout from './layouts/HomepageLayout.vue' +import RegisterSW from "./components/RegisterSW.vue" +import './styles/index.css' + +export default { + ...DefaultTheme, + Layout() { + return h(Layout, null, { + 'layout-bottom': () => h(RegisterSW) + }) + } +} +// export default { +// extend: '@vuepress/theme-default', +// plugins: [ +// ['@vuepress/search', { +// searchMaxSuggestions: 10 +// }], +// ['@vuepress/back-to-top'], +// formatHeaderSlugPlugin +// ] +// } diff --git a/docs-vuepress/.vuepress/theme/layouts/GlobalLayout.vue b/docs-vitepress/.vitepress/theme/layouts/GlobalLayout.vue similarity index 100% rename from docs-vuepress/.vuepress/theme/layouts/GlobalLayout.vue rename to docs-vitepress/.vitepress/theme/layouts/GlobalLayout.vue diff --git a/docs-vitepress/.vitepress/theme/layouts/HomepageLayout.vue b/docs-vitepress/.vitepress/theme/layouts/HomepageLayout.vue new file mode 100644 index 0000000000..0da28df5da --- /dev/null +++ b/docs-vitepress/.vitepress/theme/layouts/HomepageLayout.vue @@ -0,0 +1,89 @@ + + + + + diff --git a/docs-vuepress/.vuepress/theme/layouts/Layout.vue b/docs-vitepress/.vitepress/theme/layouts/Layout.vue similarity index 88% rename from docs-vuepress/.vuepress/theme/layouts/Layout.vue rename to docs-vitepress/.vitepress/theme/layouts/Layout.vue index a8fa6ef843..b6f7cc3e9f 100644 --- a/docs-vuepress/.vuepress/theme/layouts/Layout.vue +++ b/docs-vitepress/.vitepress/theme/layouts/Layout.vue @@ -1,6 +1,6 @@ @@ -21,4 +21,4 @@ export default { height: 200px; background: red; } - \ No newline at end of file + diff --git a/docs-vitepress/.vitepress/theme/styles/index.css b/docs-vitepress/.vitepress/theme/styles/index.css new file mode 100644 index 0000000000..5f94ccf351 --- /dev/null +++ b/docs-vitepress/.vitepress/theme/styles/index.css @@ -0,0 +1,126 @@ +:root { + --vt-c-green: #42b883; + --vt-c-text-code: #476582; + --vt-c-green-light: #42d392; + --vt-c-green-lighter: #35eb9a; + --vt-c-green-dark: #33a06f; + --vt-c-green-darker: #155f3e; + --vt-c-text-2: rgba(60, 60, 60, 0.7); + --vt-c-text-3: rgba(60, 60, 60, 0.33); + --vt-c-divider: rgba(60, 60, 60, 0.29); + --vt-c-divider-light: rgba(60, 60, 60, 0.12); + --vt-c-brand-highlight: var(--vt-c-brand-dark); + --vt-c-brand: var(--vt-c-green); + --vt-c-brand-dark: var(--vt-c-green-dark); + --vt-c-brand-light: var(--vt-c-green-light); + --vt-c-brand-dark: var(--vt-c-green-dark); +} + +.dark { + --vt-c-text-code: #aac8e4; + --vt-c-text-2: rgba(235, 235, 235, 0.6); + --vt-c-text-3: rgba(235, 235, 235, 0.38); + --vt-c-divider: rgba(84, 84, 84, 0.65); + --vt-c-divider-light: rgba(84, 84, 84, 0.48); + --vt-c-brand-highlight: var(--vt-c-brand-light); +} + +.vp-doc { + a { + text-decoration: none; + color: var(--vt-c-brand); + } + a:hover { + color: var(--vt-c-brand-highlight); + } +} + +.VPNavBarMenuLink:hover { + color: var(--vt-c-brand-highlight) !important; +} + +.VPNavBarMenuLink.active { + color: var(--vt-c-brand) !important; + border-bottom: 1px solid var(--vt-c-brand); +} + +.VPSidebarItem.is-link { + .item .link { + .text { + color: var(--vt-c-text-2); + font-weight: 500; + } + } + .item .link:hover { + .text { + color: var(--vt-c-text-1) !important; + } + } +} + +.VPSidebarItem.is-link.is-active { + .item .link .text { + color: var(--vt-c-brand) !important; + font-weight: 600; + } +} + +.VPDocAside { + .outline-marker { + height: 20px; + background-color: var(--vt-c-brand); + } +} + +.DocSearch-Button { + background-color: transparent; +} + +.DocSearch-Button:hover { + background-color: transparent; + border-color: var(--vt-c-brand-highlight); +} + +.DocSearch-Modal { + .DocSearch-Form { + border: 1px solid var(--vt-c-brand); + + .DocSearch-MagnifierLabel { + color: var(--vt-c-brand); + } + } + + .DocSearch-Hit-source { + color: var(--vt-c-brand); + } + + .DocSearch-Hit[aria-selected="true"] { + a { + background-color: var(--vt-c-brand); + } + + .DocSearch-Hit-title { + color: #fff; + } + } + + .DocSearch-Hits mark { + color: var(--vt-c-brand); + } + + .DocSearch-Prefill { + color: var(--vt-c-brand); + } +} + +.pager-link .title { + color: var(--vt-c-brand) !important; +} + +.pager-link:hover { + border: 1px solid var(--vt-c-brand) !important; + + .title { + color: var(--vt-c-brand-highlight) !important; + } +} diff --git a/docs-vuepress/.vuepress/theme/vuepress-format-header-slug-plugin.js b/docs-vitepress/.vitepress/theme/vuepress-format-header-slug-plugin.js similarity index 79% rename from docs-vuepress/.vuepress/theme/vuepress-format-header-slug-plugin.js rename to docs-vitepress/.vitepress/theme/vuepress-format-header-slug-plugin.js index 00794ef428..ed34cc1540 100644 --- a/docs-vuepress/.vuepress/theme/vuepress-format-header-slug-plugin.js +++ b/docs-vitepress/.vitepress/theme/vuepress-format-header-slug-plugin.js @@ -1,5 +1,6 @@ -const {deeplyParseHeader, slugify$1} = require('../headerMdPlugin') -module.exports = (options, ctx) => ({ +import { deeplyParseHeader, slugify$1 } from '../headerMdPlugin' + +export default (options, ctx) => ({ async ready () { const { pages } = ctx pages.forEach(page => { diff --git a/docs-vuepress/api/ApiIndex.vue b/docs-vitepress/api/ApiIndex.vue similarity index 95% rename from docs-vuepress/api/ApiIndex.vue rename to docs-vitepress/api/ApiIndex.vue index 5293ff8487..2a4c8b11b5 100644 --- a/docs-vuepress/api/ApiIndex.vue +++ b/docs-vitepress/api/ApiIndex.vue @@ -422,6 +422,14 @@ const data = [ { text: 'useFetch', anchor: '#useFetch' + }, + { + text: 'provide', + anchor: '#provide' + }, + { + text: 'inject', + anchor: '#inject' } ] } @@ -936,7 +944,7 @@ export default { @@ -976,48 +984,52 @@ export default { margin: 0px auto; padding: 64px 32px; } -a{ - text-decoration: none; -} -h1, -h2, -h3 { - font-weight: 600; - line-height: 1; -} +.vp-doc { + a{ + text-decoration: none; + } -h1, -h2 { - letter-spacing: -0.02em; -} + h1, + h2, + h3 { + font-weight: 600; + line-height: 1; + } -h1 { - font-size: 38px; -} + h1, + h2 { + letter-spacing: -0.02em; + } -ul { - list-style: none; - margin: 0; - padding: 0; -} + h1 { + font-size: 38px; + } -h2 { - font-size: 24px; - color: var(--vt-c-text-1); - margin: 36px 0; - transition: color 0.5s; - padding-top: 36px; - border-top: 1px solid var(--vt-c-divider-light); - border-bottom: none; -} + ul { + list-style: none; + margin: 0; + padding: 0; + } -h3 { - letter-spacing: -0.01em; - color: var(--vt-c-green); - font-size: 18px; - margin-bottom: 1em; - transition: color 0.5s; + h2 { + font-size: 24px; + color: var(--vp-c-text-1); + margin: 36px 0; + transition: color 0.5s; + padding-top: 36px; + border-top: 1px solid var(--vt-c-divider-light); + border-bottom: none; + } + + h3 { + letter-spacing: -0.01em; + color: var(--vt-c-brand); + font-size: 18px; + margin-top: 0; + margin-bottom: 1em; + transition: color 0.5s; + } } .api-section { @@ -1030,14 +1042,11 @@ h3 { line-height: 2; color: var(--vt-c-text-code); transition: color 0.5s; -} - -.dark api-groups a { - font-weight: 400; + text-decoration: none; } .api-groups a:hover { - color: var(--vt-c-green); + color: var(--vt-c-brand); transition: none; } @@ -1045,9 +1054,9 @@ h3 { break-inside: avoid; overflow: auto; margin-bottom: 20px; - background-color: var(--vt-c-bg-soft); + background-color: var(--vp-c-bg-soft); border-radius: 8px; - padding: 28px 26px; + padding: 24px 18px; transition: background-color 0.5s; } @@ -1070,8 +1079,8 @@ h3 { padding: 6px 12px; } -.api-filter:focus { - border-color: var(--vt-c-green-light); +#api-filter:focus { + box-shadow: 0 0 4pt #00d47499; } .no-match { diff --git a/docs-vuepress/api/app-config.md b/docs-vitepress/api/app-config.md similarity index 100% rename from docs-vuepress/api/app-config.md rename to docs-vitepress/api/app-config.md diff --git a/docs-vuepress/api/builtIn.md b/docs-vitepress/api/builtIn.md similarity index 100% rename from docs-vuepress/api/builtIn.md rename to docs-vitepress/api/builtIn.md diff --git a/docs-vuepress/api/compile.md b/docs-vitepress/api/compile.md similarity index 100% rename from docs-vuepress/api/compile.md rename to docs-vitepress/api/compile.md diff --git a/docs-vuepress/api/composition-api.md b/docs-vitepress/api/composition-api.md similarity index 97% rename from docs-vuepress/api/composition-api.md rename to docs-vitepress/api/composition-api.md index d35d912e4e..0e70e301dd 100644 --- a/docs-vuepress/api/composition-api.md +++ b/docs-vitepress/api/composition-api.md @@ -214,3 +214,9 @@ getCurrentInstance 只能在 setup 或生命周期钩子中调用。 ## useFetch 点击[查看详情](./extend.md#usefetch) + +## provide +点击[查看详情](../guide/advance/provide-inject.md#组合式语法) + +## inject +点击[查看详情](../guide/advance/provide-inject.md#组合式语法-1) diff --git a/docs-vuepress/api/directives.md b/docs-vitepress/api/directives.md similarity index 91% rename from docs-vuepress/api/directives.md rename to docs-vitepress/api/directives.md index 1814839ef3..efe15ab5d0 100644 --- a/docs-vuepress/api/directives.md +++ b/docs-vitepress/api/directives.md @@ -91,7 +91,8 @@ Page({ ``` ``` js -Page({ +import { createComponent } from '@mpxjs/core' +createComponent({ data: { array: [{ id: 1, text: 'foo' @@ -126,7 +127,8 @@ Page({ ``` ``` js -Page({ +import { createComponent } from '@mpxjs/core' +createComponent({ data: { array: [{ id: 1, text: 'foo' @@ -549,7 +551,8 @@ Mpx提供了 `wx:ref=xxx` 来更方便获取 WXML 节点信息的对象。在JS ``` ```js -Page({ +import {createPage} from '@mpxjs/core' +createPage({ data: { show: false } @@ -679,22 +682,28 @@ capture-catch中断捕获阶段和取消冒泡阶段 ## @mode -`type mode = 'wx' | 'ali' | 'qq' | 'swan' | 'tt' | 'web' | 'qa'` +`type mode = 'wx' | 'ali' | 'qq' | 'swan' | 'tt' | 'web' | 'qa' | 'ios' | 'android' | 'harmony'` +### 属性中使用 跨平台输出场景下，Mpx 框架允许用户在组件上使用 @ 和 | 符号来指定某个节点或属性只在某些平台下有效。 ```html ``` -在上方示例中，开发者可以便捷的设置在支付宝小程序与微信和百度小程序等平台分别生效的 open-type 属性， -以及事件绑定或其他属性。假设当前 srcMode 为 wx，目标平台为 ali，则输出产物为： +例如在上述示例中： +* 在支付宝小程序与微信和百度小程序等平台分别生效的 open-type 等属性 +* 在输出iOS或android平台时，enable-background 属性生效 +* 以及事件绑定或其他属性灵活的进行条件编译 + +假设当前 srcMode 为 wx，目标平台为 ali，则输出产物为： ```html +``` + +### 节点中使用 +同时，该指令也可以作用在单个节点上，来对节点进行跨平台条件判断。 + +但需要注意的是，该指令作用在单个节点时，节点仅在目标平台输出，同时节点自身属性不会进行跨平台语法转换，不过其子节点不受影响。 + ```html @@ -715,10 +740,17 @@ capture-catch中断捕获阶段和取消冒泡阶段 text ``` +::: danger +另外在跨端输出 React Native 和 H5 时，不要在基础组件节点上使用 @mode 指令，仅可在自定义组件节点使用 @mode 指令 +::: +```html + +测试数据 +``` ## @_mode -`type _mode = '_wx' | '_ali' | '_qq' | '_swan' | '_tt' | '_web' | '_qa'` +`type _mode = '_wx' | '_ali' | '_qq' | '_swan' | '_tt' | '_web' | '_qa' ｜ '_ios' | '_android' | '_harmony'` 有时开发者期望使用 @mode 这种方式仅控制节点的展示，保留节点属性的平台转换能力，为此 Mpx 实现了一个隐式属性条件编译能力。 ```html @@ -727,6 +759,8 @@ capture-catch中断捕获阶段和取消冒泡阶段 ``` 在对应的平台前加一个_，例如@_ali、@_swan、@_tt等，使用该隐式规则仅有条件编译能力，节点属性语法转换能力依旧。 +在跨端输出 React Native 和 H5 时，可以在节点上使用该属性。 + ## @env `string` diff --git a/docs-vuepress/api/extend.md b/docs-vitepress/api/extend.md similarity index 88% rename from docs-vuepress/api/extend.md rename to docs-vitepress/api/extend.md index 6eb54a6fd7..31f1440d27 100644 --- a/docs-vuepress/api/extend.md +++ b/docs-vitepress/api/extend.md @@ -459,6 +459,10 @@ useFetch().fetch({ | ------------- |:-----:| :-----:| :-----: | :-----: | | getSystemInfo|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | getSystemInfoSync|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| getDeviceInfo|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| getWindowInfo|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| getLaunchOptionsSync|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| getEnterOptionsSync|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | nextTick |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| | showToast |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| | hideToast |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| @@ -466,10 +470,47 @@ useFetch().fetch({ | showLoading |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| | hideLoading |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| | showActionSheet |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| createAnimation |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| onAppShow |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| onAppHide |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| offAppShow |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| offAppHide |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| onError |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| offError |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| onUnhandledRejection |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| offUnhandledRejection |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| createInnerAudioContext |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| closeBLEConnection |:white_check_mark:|:white_check_mark:|:x:|:x:| +| createBLEConnection |:white_check_mark:|:white_check_mark:|:x:|:x:| +| onBLEConnectionStateChange |:white_check_mark:|:white_check_mark:|:x:|:x:| +| createIntersectionObserver |:white_check_mark:|:white_check_mark:|:x:|:x:| +| createSelectorQuery |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| getExtConfig |:white_check_mark:|:white_check_mark:|:x:|:x:| +| getExtConfigSync |:white_check_mark:|:white_check_mark:|:x:|:x:| +| onKeyboardHeightChange |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| +| offKeyboardHeightChange |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| +| hideKeyboard |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| +| getLocation |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| openLocation |:white_check_mark:|:white_check_mark:|:x:|:x:| +| chooseLocation |:white_check_mark:|:white_check_mark:|:x:|:x:| +| pageScrollTo |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| stopPullDownRefresh |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| startPullDownRefresh |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| redirectTo |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| navigateTo |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| navigateBack |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| reLaunch |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| switchTab |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| setTabBarItem |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| setTabBarStyle |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| showTabBar |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| hideTabBar |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| vibrateShort |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| +| vibrateLong |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| | showNavigationBarLoading |:white_check_mark:|:white_check_mark:|:x:|:x:| | hideNavigationBarLoading |:white_check_mark:|:white_check_mark:|:x:|:x:| -| setNavigationBarTitle |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| -| setNavigationBarColor |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| +| setNavigationBarTitle |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| setNavigationBarColor |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | request |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | downloadFile |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:|:x:| | uploadFile |:white_check_mark:|:white_check_mark:|:x:|:x:| @@ -487,6 +528,7 @@ useFetch().fetch({ | previewImage |:white_check_mark:|:white_check_mark:|:x:|:x:| | compressImage |:white_check_mark:|:white_check_mark:|:x:|:x:| | chooseImage |:white_check_mark:|:white_check_mark:|:x:|:x:| +| getImageInfo |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | getLocation |:white_check_mark:|:white_check_mark:|:x:|:x:| | saveFile |:white_check_mark:|:white_check_mark:|:x:|:x:| | removeSavedFile |:white_check_mark:|:white_check_mark:|:x:|:x:| @@ -495,8 +537,8 @@ useFetch().fetch({ | addPhoneContact |:white_check_mark:|:white_check_mark:|:x:|:x:| | setClipboardData |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| | getClipboardData |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| -| setScreenBrightness |:white_check_mark:|:white_check_mark:|:x:|:x:| -| getScreenBrightness |:white_check_mark:|:white_check_mark:|:x:|:x:| +| setScreenBrightness |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| +| getScreenBrightness |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| | makePhoneCall |:white_check_mark:|:white_check_mark:|:x:|:white_check_mark:| | stopAccelerometer |:white_check_mark:|:white_check_mark:|:x:|:x:| | startAccelerometer |:white_check_mark:|:white_check_mark:|:x:|:x:| @@ -522,6 +564,7 @@ useFetch().fetch({ | getNetworkType |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | onNetworkStatusChange |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| | offNetworkStatusChange |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| +| createVideoContext |:white_check_mark:|:white_check_mark:|:white_check_mark:|:x:| ## webview-bridge Mpx 支持小程序跨平台后，多个平台的小程序里都提供了 webview 组件，webview 打开的 H5 页面可以通过小程序提供的 API 来与小程序通信以及调用一些小程序的能力，但是各家小程序对于 webview 提供的API是不一样的。 diff --git a/docs-vuepress/api/global-api.md b/docs-vitepress/api/global-api.md similarity index 100% rename from docs-vuepress/api/global-api.md rename to docs-vitepress/api/global-api.md diff --git a/docs-vuepress/api/index.md b/docs-vitepress/api/index.md similarity index 100% rename from docs-vuepress/api/index.md rename to docs-vitepress/api/index.md diff --git a/docs-vuepress/api/instance-api.md b/docs-vitepress/api/instance-api.md similarity index 100% rename from docs-vuepress/api/instance-api.md rename to docs-vitepress/api/instance-api.md diff --git a/docs-vuepress/api/optional-api.md b/docs-vitepress/api/optional-api.md similarity index 100% rename from docs-vuepress/api/optional-api.md rename to docs-vitepress/api/optional-api.md diff --git a/docs-vuepress/api/reactivity-api.md b/docs-vitepress/api/reactivity-api.md similarity index 100% rename from docs-vuepress/api/reactivity-api.md rename to docs-vitepress/api/reactivity-api.md diff --git a/docs-vuepress/api/store-api.md b/docs-vitepress/api/store-api.md similarity index 100% rename from docs-vuepress/api/store-api.md rename to docs-vitepress/api/store-api.md diff --git a/docs-vuepress/articles/1.0.md b/docs-vitepress/articles/1.0.md similarity index 99% rename from docs-vuepress/articles/1.0.md rename to docs-vitepress/articles/1.0.md index 60698afc74..4d42244dcf 100644 --- a/docs-vuepress/articles/1.0.md +++ b/docs-vitepress/articles/1.0.md @@ -11,7 +11,7 @@ Mpx是一款致力于提高小程序开发体验的增强型小程序框架， * 增强的模板语法(动态组件/样式绑定/类名绑定/内联事件函数/双向绑定等) * 深度性能优化(原生自定义组件/基于依赖收集和数据变化的setData) * Webpack编译(npm/循环依赖/Babel/ESLint/css预编译/代码优化等) -* 单文件组件开发 +* 单文件组件开发 testtest123 * 状态管理(Vuex规范/多实例/可合并) * 跨团队合作(packages) * 逻辑复用能力(mixins) diff --git a/docs-vuepress/articles/2.0.md b/docs-vitepress/articles/2.0.md similarity index 100% rename from docs-vuepress/articles/2.0.md rename to docs-vitepress/articles/2.0.md diff --git a/docs-vuepress/articles/2.7-release.md b/docs-vitepress/articles/2.7-release.md similarity index 100% rename from docs-vuepress/articles/2.7-release.md rename to docs-vitepress/articles/2.7-release.md diff --git a/docs-vuepress/articles/2.8-release-alter.md b/docs-vitepress/articles/2.8-release-alter.md similarity index 100% rename from docs-vuepress/articles/2.8-release-alter.md rename to docs-vitepress/articles/2.8-release-alter.md diff --git a/docs-vuepress/articles/2.8-release.md b/docs-vitepress/articles/2.8-release.md similarity index 100% rename from docs-vuepress/articles/2.8-release.md rename to docs-vitepress/articles/2.8-release.md diff --git a/docs-vuepress/articles/2.9-release-alter.md b/docs-vitepress/articles/2.9-release-alter.md similarity index 100% rename from docs-vuepress/articles/2.9-release-alter.md rename to docs-vitepress/articles/2.9-release-alter.md diff --git a/docs-vuepress/articles/2.9-release.md b/docs-vitepress/articles/2.9-release.md similarity index 100% rename from docs-vuepress/articles/2.9-release.md rename to docs-vitepress/articles/2.9-release.md diff --git a/docs-vuepress/articles/index.md b/docs-vitepress/articles/index.md similarity index 100% rename from docs-vuepress/articles/index.md rename to docs-vitepress/articles/index.md diff --git a/docs-vuepress/articles/mpx-cli-next.md b/docs-vitepress/articles/mpx-cli-next.md similarity index 100% rename from docs-vuepress/articles/mpx-cli-next.md rename to docs-vitepress/articles/mpx-cli-next.md diff --git a/docs-vuepress/articles/mpx-cube-ui.md b/docs-vitepress/articles/mpx-cube-ui.md similarity index 100% rename from docs-vuepress/articles/mpx-cube-ui.md rename to docs-vitepress/articles/mpx-cube-ui.md diff --git a/docs-vuepress/articles/mpx1.md b/docs-vitepress/articles/mpx1.md similarity index 100% rename from docs-vuepress/articles/mpx1.md rename to docs-vitepress/articles/mpx1.md diff --git a/docs-vuepress/articles/mpx2.md b/docs-vitepress/articles/mpx2.md similarity index 100% rename from docs-vuepress/articles/mpx2.md rename to docs-vitepress/articles/mpx2.md diff --git a/docs-vuepress/articles/performance.md b/docs-vitepress/articles/performance.md similarity index 100% rename from docs-vuepress/articles/performance.md rename to docs-vitepress/articles/performance.md diff --git a/docs-vuepress/articles/size-control.md b/docs-vitepress/articles/size-control.md similarity index 100% rename from docs-vuepress/articles/size-control.md rename to docs-vitepress/articles/size-control.md diff --git a/docs-vuepress/articles/ts-derivation.md b/docs-vitepress/articles/ts-derivation.md similarity index 100% rename from docs-vuepress/articles/ts-derivation.md rename to docs-vitepress/articles/ts-derivation.md diff --git a/docs-vuepress/articles/unit-test.md b/docs-vitepress/articles/unit-test.md similarity index 100% rename from docs-vuepress/articles/unit-test.md rename to docs-vitepress/articles/unit-test.md diff --git a/docs-vuepress/assets/images/1666074957603.jpg b/docs-vitepress/assets/images/1666074957603.jpg similarity index 100% rename from docs-vuepress/assets/images/1666074957603.jpg rename to docs-vitepress/assets/images/1666074957603.jpg diff --git a/docs-vuepress/assets/images/cloud.png b/docs-vitepress/assets/images/cloud.png similarity index 100% rename from docs-vuepress/assets/images/cloud.png rename to docs-vitepress/assets/images/cloud.png diff --git a/docs-vuepress/assets/images/select-ts-version.png b/docs-vitepress/assets/images/select-ts-version.png similarity index 100% rename from docs-vuepress/assets/images/select-ts-version.png rename to docs-vitepress/assets/images/select-ts-version.png diff --git a/docs/images/start-tips1.png b/docs-vitepress/assets/images/start-tips1.png similarity index 100% rename from docs/images/start-tips1.png rename to docs-vitepress/assets/images/start-tips1.png diff --git a/docs/images/start-tips2.png b/docs-vitepress/assets/images/start-tips2.png similarity index 100% rename from docs/images/start-tips2.png rename to docs-vitepress/assets/images/start-tips2.png diff --git a/docs-vuepress/desc.md b/docs-vitepress/desc.md similarity index 100% rename from docs-vuepress/desc.md rename to docs-vitepress/desc.md diff --git a/docs-vuepress/guide/advance/ability-compatible.md b/docs-vitepress/guide/advance/ability-compatible.md similarity index 100% rename from docs-vuepress/guide/advance/ability-compatible.md rename to docs-vitepress/guide/advance/ability-compatible.md diff --git a/docs-vuepress/guide/advance/async-subpackage.md b/docs-vitepress/guide/advance/async-subpackage.md similarity index 100% rename from docs-vuepress/guide/advance/async-subpackage.md rename to docs-vitepress/guide/advance/async-subpackage.md diff --git a/docs-vitepress/guide/advance/build-config.md b/docs-vitepress/guide/advance/build-config.md new file mode 100644 index 0000000000..550d3e70c9 --- /dev/null +++ b/docs-vitepress/guide/advance/build-config.md @@ -0,0 +1,114 @@ +# 编译配置 + +新版的 `@mpxjs/cli` 整体是基于 `@vue/cli` 的架构设计开发的。因此有关 `mpx` 编译构建相关的配置统一使用 `vue.config.js` 来进行管理。 + +### 编译构建配置 + +#### mpx 编译构建配置 + +有关 `mpx` 相关的 webpack 插件、loader 等在 `vue.config.js` 当中 `pluginOptions.mpx` 进行相关的配置： + +```javascript +// vue.config.js +module.exports = { + pluginOptions: { + mpx: { + // 传入 @mpxjs/webpack-plugin 当中的配置信息 + // 具体可参考文档：https://www.mpxjs.cn/api/compile.html#mpxwebpackplugin-options + plugin: { + srcMode: 'wx', + }, + // 传入 @mpxjs/webpack-plugin loader 当中的配置信息 + // 具体可参考文档：https://www.mpxjs.cn/api/compile.html#mpxwebpackplugin-loader + loader: {}, + // 提供图片资源处理简单操作 + // 具体配置参考 https://mpxjs.cn/guide/advance/image-process.html#%E5%9B%BE%E5%83%8F%E8%B5%84%E6%BA%90%E5%BC%95%E5%85%A5%E6%9C%89%E4%B8%89%E7%A7%8D%E6%96%B9%E5%BC%8F + urlLoader: { + name: 'img/[name][hash].[ext]', + publicPath: '', + publicPathScope: '', + limit: 10 + } + } + } +} +``` + +注：通过 `@mpxjs/cli` 初始化的项目提供了开箱即用的配置(在[插件内部](https://github.com/mpx-ecology/mpx-cli/blob/master/packages/vue-cli-plugin-mpx/utils/resolveMpxWebpackPluginConf.js#L6-L59)设置了默认的配置)，如果开发过程中有一些其他的配置需求，参见 [mpx 官方文档](https://www.mpxjs.cn/api/compile.html#mpxwebpackplugin-options)。 + +#### vue.config.js + +以下表格为 `vue.config.js` 当中 `web` 侧和 `小程序` 侧支持的字段一览表，具体每个字段的配置功能请参见 [@vue/cli 官方配置](https://cli.vuejs.org/config/#configuration-reference)： + +注：`yes` 表示在对应环境支持配置，`no` 表示在对应环境不支持配置。 + +| 字段 | web | 小程序 | 备注 | +| -------------------------- | --- | ------ | ------------------------------------------------------------- | +| publicPath | yes | no | - | +| outputDir | yes | yes | `dist/${process.env.MPX_CURRENT_TARGET_MODE}`目录作为输出目录 | +| assetsDir | yes | no | - | +| indexPath | yes | no | - | +| filenameHashing | yes | no | - | +| pages | yes | no | - | +| lintOnSave | yes | yes | - | +| runtimeCompiler | yes | no | - | +| transpileDependencies | yes | yes | - | +| productionSourceMap | yes | yes | | +| crossorigin | yes | no | - | +| integrity | yes | no | - | +| configureWebpack | yes | yes | - | +| chainWebpack | yes | yes | - | +| css.requireModuleExtension | yes | no | - | +| css.extract | yes | no | - | +| css.sourceMap | yes | no | 未来会支持 | +| css.loaderOptions | yes | no | 未来会支持 | +| devServer | yes | no | - | +| devServer.proxy | yes | no | - | +| parallel | yes | no | - | +| pwa | yes | no | - | +| pluginOptions | yes | yes | - | + +可通过 `vue.config.js` 中提供的 `chainWebpack` 或 `configureWebpack` 字段进行配置，具体使用规则请参见[@vue/cli](https://cli.vuejs.org/guide/webpack.html#simple-configuration)： + +```javascript +// vue.config.js +module.exports = { + configureWebpack: { + plugins: [new MyOwnWebpackPlugin()] + }, + chainWebpack: (config) => { + config + .rule('some-rule') + .test(/some-rule/) + .use('some-loader') + .loader('some-loader') + } +} +``` + +### 根据不同的构建目标配置 + +可根据构建平台和开发环境进行选择性的配置，在构建过程中暴露出来的环境变量包括： + +- `MPX_CLI_MODE`: 'mp' | 'web' | 'rn' +- `NODE_ENV`：'development' | 'production' +- `MPX_CURRENT_TARGET_MODE`: 'wx' | 'ali' | 'swan' | 'qq' | 'tt' | 'dd' | 'web' | 'ios' | 'android' | 'harmony' +- `MPX_CURRENT_TARGET_ENV` : 'development' | 'production' + +```javascript +// vue.config.js +module.exports = { + chainWebpack: (config) => { + if (process.env.MPX_CLI_MODE === 'mp') { + // do something + } + + if ( + process.env.MPX_CLI_MODE === 'web' && + process.env.NODE_ENV === 'development' + ) { + // do something + } + } +} +``` diff --git a/docs-vuepress/guide/advance/custom-output-path.md b/docs-vitepress/guide/advance/custom-output-path.md similarity index 100% rename from docs-vuepress/guide/advance/custom-output-path.md rename to docs-vitepress/guide/advance/custom-output-path.md diff --git a/docs-vuepress/guide/advance/dll-plugin.md b/docs-vitepress/guide/advance/dll-plugin.md similarity index 100% rename from docs-vuepress/guide/advance/dll-plugin.md rename to docs-vitepress/guide/advance/dll-plugin.md diff --git a/docs-vuepress/guide/advance/i18n.md b/docs-vitepress/guide/advance/i18n.md similarity index 100% rename from docs-vuepress/guide/advance/i18n.md rename to docs-vitepress/guide/advance/i18n.md diff --git a/docs-vuepress/guide/advance/image-process.md b/docs-vitepress/guide/advance/image-process.md similarity index 100% rename from docs-vuepress/guide/advance/image-process.md rename to docs-vitepress/guide/advance/image-process.md diff --git a/docs-vuepress/guide/advance/mixin.md b/docs-vitepress/guide/advance/mixin.md similarity index 100% rename from docs-vuepress/guide/advance/mixin.md rename to docs-vitepress/guide/advance/mixin.md diff --git a/docs-vuepress/guide/advance/npm.md b/docs-vitepress/guide/advance/npm.md similarity index 100% rename from docs-vuepress/guide/advance/npm.md rename to docs-vitepress/guide/advance/npm.md diff --git a/docs-vuepress/guide/advance/pinia.md b/docs-vitepress/guide/advance/pinia.md similarity index 100% rename from docs-vuepress/guide/advance/pinia.md rename to docs-vitepress/guide/advance/pinia.md diff --git a/docs-vuepress/guide/advance/platform.md b/docs-vitepress/guide/advance/platform.md similarity index 100% rename from docs-vuepress/guide/advance/platform.md rename to docs-vitepress/guide/advance/platform.md diff --git a/docs-vuepress/guide/advance/plugin.md b/docs-vitepress/guide/advance/plugin.md similarity index 100% rename from docs-vuepress/guide/advance/plugin.md rename to docs-vitepress/guide/advance/plugin.md diff --git a/docs-vuepress/guide/advance/progressive.md b/docs-vitepress/guide/advance/progressive.md similarity index 100% rename from docs-vuepress/guide/advance/progressive.md rename to docs-vitepress/guide/advance/progressive.md diff --git a/docs-vuepress/guide/advance/provide-inject.md b/docs-vitepress/guide/advance/provide-inject.md similarity index 100% rename from docs-vuepress/guide/advance/provide-inject.md rename to docs-vitepress/guide/advance/provide-inject.md diff --git a/docs-vuepress/guide/advance/resource-resolve.md b/docs-vitepress/guide/advance/resource-resolve.md similarity index 100% rename from docs-vuepress/guide/advance/resource-resolve.md rename to docs-vitepress/guide/advance/resource-resolve.md diff --git a/docs-vuepress/guide/advance/size-report.md b/docs-vitepress/guide/advance/size-report.md similarity index 100% rename from docs-vuepress/guide/advance/size-report.md rename to docs-vitepress/guide/advance/size-report.md diff --git a/docs-vuepress/guide/advance/ssr.md b/docs-vitepress/guide/advance/ssr.md similarity index 100% rename from docs-vuepress/guide/advance/ssr.md rename to docs-vitepress/guide/advance/ssr.md diff --git a/docs-vuepress/guide/advance/store.md b/docs-vitepress/guide/advance/store.md similarity index 100% rename from docs-vuepress/guide/advance/store.md rename to docs-vitepress/guide/advance/store.md diff --git a/docs-vuepress/guide/advance/subpackage.md b/docs-vitepress/guide/advance/subpackage.md similarity index 100% rename from docs-vuepress/guide/advance/subpackage.md rename to docs-vitepress/guide/advance/subpackage.md diff --git a/docs-vuepress/guide/advance/utility-first-css.md b/docs-vitepress/guide/advance/utility-first-css.md similarity index 100% rename from docs-vuepress/guide/advance/utility-first-css.md rename to docs-vitepress/guide/advance/utility-first-css.md diff --git a/docs-vuepress/guide/basic/class-style-binding.md b/docs-vitepress/guide/basic/class-style-binding.md similarity index 100% rename from docs-vuepress/guide/basic/class-style-binding.md rename to docs-vitepress/guide/basic/class-style-binding.md diff --git a/docs-vitepress/guide/basic/component.md b/docs-vitepress/guide/basic/component.md new file mode 100644 index 0000000000..c89a3fc33b --- /dev/null +++ b/docs-vitepress/guide/basic/component.md @@ -0,0 +1,758 @@ +# 自定义组件 + +在 Mpx 中也可以使用类似 Vue 中的单文件自定义组件，我们可以在每个组件内封装自定义内容和逻辑。 + +在Mpx中自定义组件，语法默认以微信小程序为基准，与此同时，Mpx 额外提供的数据响应和模版增强语法等一系列增强能力都可以在自定义组件中使用。 + +>作为参考，原生小程序自定义组件的规范详情查看[这里](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Component.html)，但在Mpx中自定义组件所支持的属性和功能还需以当前文档为准。 + +## 注册使用 + +```html + + + + + + + + +``` +使用 [createComponent](/api/global-api.html#createcomponent) 方法创建自定义组件，在父组件/页面中通过 usingComponents 注册使用。 + +## 组件属性 + +对于组件属性的讲解，下方暂时使用选项式 API 进行讲解。 + +### properties + +用于声明组件接收的外部属性。属性的类型可以为 String、Number、Boolean、Object、Array 其一，也可以为 null 表示不限制类型。 + +```ts + +type PropType = | StringConstructor // String + | NumberConstructor // Number + | BooleanConstructor // Boolean + | ObjectConstructor // Object + | ArrayConstructor // Array; + | null; // null + +interface ComponentOptions { + properties?: { + [key: string]: PropOptions | PropType + } +} + +interface PropOptions { + type: PropType // type 为必填项 + value?: any + optionalTypes?: PropType[] // 属性的类型（可以指定多个） + observer?: string | ((newVal: any, oldVal: any) => void) +} +``` + +properties 定义包含以下选项： +* **`type`**: 必填，属性的类型 +* **`optionalTypes`**: 可选，属性的类型（可以指定多个） +* **`value`**: 可选，属性的初始值 +* **`observer`**: 可选，属性值变化时的回调函数 + +> **注意：** +> 1. 属性名应避免以 data 开头，例如 data-xyz="" 会被作为节点 dataset 来处理 +> 2. 在组件定义和使用时，属性名和 data 字段相互间都不能冲突 + +```js +createComponent({ + properties: { + // 基础类型 + propA: { + type: String, + value: '' + }, + // 简化的定义方式 + propB: Number, + // 多种类型 + propC: { + type: Number, + optionalTypes: [String, Object], + value: 0 + }, + // 带有属性值变化回调 + propE: { + type: Object, + observer(newVal, oldVal) { + console.log('propE changed:', newVal, oldVal) + } + } + } +}) +``` +**参考**：[微信小程序properties定义](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Component.html#properties-%E5%AE%9A%E4%B9%89) + +### data + +组件的内部数据，和 properties 一同用于组件的模板渲染。 + +```ts +interface ComponentOptions { + data?: object | (() => object) +} +``` +data 可以是一个函数返回一个普通 JavaScript 对象，也可以是一个普通 JavaScript 对象。 + +在 Mpx 中，组件实例会代理 data 对象的所有属性并进行响应式处理，因此可以直接通过 `this.dataName` 访问这些数据, 同时修改这些数据也会触发视图更新。 + +```html + + + +``` +// TODO data 的注意项 + + +### computed + +用于声明基于现有数据的计算属性。 + +```ts +type ComputedGetter = () => T +type ComputedSetter = (value: T) => void + +interface WritableComputedOptions { + get: ComputedGetter + set: ComputedSetter +} + +// 计算属性可以是函数或对象 +type ComputedOption = ComputedGetter | WritableComputedOptions + +// 组件选项的接口 +interface ComponentOptions { + computed?: { + [K: string]: ComputedOption + } +} +``` + +该选项接收一个对象，其中键是计算属性的名称，值是一个计算属性 getter，或一个具有 get 和 set 方法的对象 (用于声明可写的计算属性)。 + +所有的 getters 和 setters 会将它们的 this 上下文自动绑定为组件实例。 + +computed 选项用于声明依赖于其他数据的计算属性。计算属性的结果会被缓存，只有在依赖发生变化时才会重新计算。 + +```js +import { createComponent } from '@mpxjs/core' +createComponent({ + data() { + return { + price: 100, + quantity: 2 + } + }, + computed: { + // 只读计算属性 + total() { + return this.price * this.quantity + }, + // 可读写计算属性 + discount: { + get() { + return this.price * 0.9 + }, + set(value) { + this.price = value / 0.9 + } + } + } +}) +``` +> 注意 +>* 选项式 API 中 computed 尽量不要使用箭头函数，否则无法访问组件实例 this + +### watch + +用于对响应性数据变化调用的侦听回调。 + +```ts +// flush 选项的可选值类型 +type FlushMode = 'sync' | 'post' | 'pre' + +interface ComponentOptions { + watch?: { + [key: string]: WatchOption | WatchCallback | string + } +} + +type WatchCallback = (newValue: any, oldValue: any) => void + +interface WatchOption { + handler: WatchCallback | string + immediate?: boolean // 是否立即执行 + deep?: boolean // 是否深度监听 + flush?: FlushMode // 回调的执行时机 +} +``` + +watch 选项用于监听数据的变化并执行相应的回调函数。支持以下功能： +* 监听单个数据源 +* 监听多个数据源 +* 深度监听（deep） +* 立即执行（immediate） +* 执行时机控制（flush） + * `'sync'`: 同步执行，立即触发回调 + * `'post'`: DOM 更新后执行（默认值） + * `'pre'`: DOM 更新前执行 + +```js +createComponent({ + data() { + return { + message: 'Hello', + user: { + name: 'John', + age: 20 + } + } + }, + watch: { + // 简单监听 + message(newVal, oldVal) { + console.log('message changed:', newVal, oldVal) + }, + + // 深度监听 + user: { + handler(newVal, oldVal) { + console.log('user changed:', newVal, oldVal) + }, + deep: true, + immediate: true + }, + + // 监听对象的属性 + 'user.name'(newVal, oldVal) { + console.log('user.name changed:', newVal, oldVal) + }, + + // 控制执行时机 + count: { + handler(newVal) { + console.log('count changed:', newVal) + }, + flush: 'post' // DOM 更新后执行 + } + } +}) +``` + +### observers + +用于监听数据变化，类似于 watch，最早由微信小程序官方提出，Mpx 框架支持了该能力并做了跨平台兼容。 + +```ts +interface ComponentOptions { + observers?: { + [path: string]: (newValue: any, ...args: any[]) => void + } +} +``` + +observers 选项支持以下功能： +* 监听单个数据 +* 监听多个数据 +* 使用通配符监听对象或数组的所有子数据 + +通配符说明： +* `**`：表示所有子数据 + + +```js +createComponent({ + + observers: { + observers: { + 'numberA, numberB': function(numberA, numberB) { + // 在 numberA 或者 numberB 被设置时，执行这个函数 + this.numberC = numberA + numberB + } + 'some.subfield': function(subfield) { + subfield === this.some.subfield + }, + 'arr[12]': function(arr12) { + // 使用 setData 设置 this.data.arr[12] 时触发 + // （除此以外，使用 setData 设置 this.data.arr 也会触发） + arr12 === this.arr[12] + }, + 'some.field.**': function(field) { + // field 下所有子数据变化都会触发回调 + field === this.some.field + } + } + } +}) +``` + +> **注意：** +> 1. 和 watch 不同，observers 监听多个数据时回调方法的参数为响应性数据最新值，并非数组 +> 2. 使用通配符与 watch deep 属性表现一致 +> 3. 建议尽量统一使用 watch + +**参考**：[微信小程序数据监听器](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Component.html#properties-%E5%AE%9A%E4%B9%89) + +### methods + +用于声明组件的方法。 + +```ts +interface ComponentOptions { + methods?: { + [key: string]: (...args: any[]) => any + } +} +``` + +methods 选项用于声明组件实例可以访问的方法。所有方法的 this 上下文会自动绑定为组件实例。 + +```js +createComponent({ + methods: { + handleClick() { + // 访问数据 + console.log(this.message) + // 调用其他方法 + this.otherMethod() + }, + otherMethod() { + // ... + } + } +}) +``` + +### mixins +一个包含组件选项对象的数组，这些选项都将被混入到当前组件的实例中。 + +具体请查看[Mpx-mixins](https://mpxjs.cn/guide/advance/mixin.html) + +### behaviors + +小程序平台提供的用于组件间代码共享的特性，类似于"mixins"。 + + +**参考**：[微信小程序behaviors](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Component.html#properties-%E5%AE%9A%E4%B9%89) + +在 Mpx 组件内如果使用 behaviors，在跨平台时会进行抹平处理，但建议直接使用 Mpx 提供的 mixins 能力。 + +> **注意：** +> * 使用内置 behaviors（如 wx://form-field），因为牵扯到小程序平台底层能力，无法做到完全跨平台抹平 + +### relations + +用于定义组件间的关系，支持父子、祖孙等关系，实现组件间的通信与控制。 + +该特性 base 微信小程序平台，在Mpx中使用该特性需要注意，输出微信小程序平台时能力完全支持，跨端输出其他平台时受制于平台底层能力，无法完全做抹平支持。 + +| 平台 | 支持情况 | 说明 | +|------|---------|------| +| 微信小程序 | 完全支持 | 完全支持 relations 能力 | +| 支付宝小程序 | 部分支持 | 部分支持，不支持 linkChanged 和 target 能力 | +| 百度小程序 | 不支持 | 不支持使用 relations | +| QQ小程序 | 完全支持 | 完全支持 relations 能力 | +| 字节小程序 | 部分支持 | 部分支持，不支持 linkChanged 能力 | +| Web | 部分支持 | 部分支持，不支持 linkChanged 和 target 能力 | +| RN | 不支持 | 不支持使用 relations | + +因此需要注意，在使用 realtions 能力跨平台时需要做好平台条件编译。 + +```ts +interface RelationOption { + type: 'parent' | 'child' | 'ancestor' | 'descendant' // 关系类型 + linked?: (target: any) => void // 关系建立时的回调 + linkChanged?: (target: any) => void // 关系变化时的回调 + unlinked?: (target: any) => void // 关系解除时的回调 + target?: string // 关联的 behavior +} + +interface ComponentOptions { + relations?: { + [componentPath: string]: RelationOption + } +} +``` + +relations 支持以下功能： +* 定义组件间的层级关系 +* 监听关系的生命周期 +* 获取关联的组件实例 +* 关联使用相同 behavior 的组件 + +详情可参考[微信小程序-relations](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/relations.html) + +```js +// custom-ul 组件 +import { createComponent } from '@mpxjs/core' +createComponent({ + relations: { + './custom-li': { + type: 'child', // 关联的目标节点应为子节点 + linked(target) { + // 每次有 custom-li 被插入时执行 + console.log('li linked', target) + }, + unlinked(target) { + // 每次有 custom-li 被移除时执行 + console.log('li unlinked', target) + } + } + } +}) + +// custom-li 组件 +import { createComponent } from '@mpxjs/core' +createComponent({ + relations: { + './custom-ul': { + type: 'parent', // 关联的目标节点应为父节点 + linked(target) { + // 每次被插入到 custom-ul 时执行 + console.log('ul linked', target) + } + } + } +}) +``` + +### externalClasses + +组件接受的外部样式类，常用于在开启组件样式隔离时，可以通过接收外部样式类来改变组件样式。 + +```ts +interface ComponentOptions { + externalClasses?: string[] +} +``` + +externalClasses 支持以下功能： +* 定义多个外部样式类 +* 在组件 template 中使用外部样式类，同时支持在同一个节点上使用多个外部样式类 + +```html + + +``` + +使用组件： + +```html + + + + + + + + + +``` + +```css +/* 页面 page style */ +.red-text { + color: red; +} + +.large-text { + font-size: 20px; +} + +.active { + background: #f0f0f0; +} +``` + +关于 externalclasses 的更多描述也可以查看[微信小程序-外部样式类](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E5%A4%96%E9%83%A8%E6%A0%B7%E5%BC%8F%E7%B1%BB) + +>**注意：** +>* 该功能默认在微信小程序可用，在跨平台输出时，需要在 @mpxjs/webpack-plugin 中配置相关的 externalClasses, 否则跨平台时该能力不生效，具体配置请[查看](https://mpxjs.cn/api/compile.html#externalclasses)。 + +### options + +开启组件的部分特性时需要设置的选项，例如 virtualHost 、 multipleSlots 之类特性。 + +```ts +interface ComponentOptions { + options?: { + virtualHost?: boolean // 设置组件是否为虚拟节点 + styleIsolation?: 'isolated' | 'apply-shared' | 'shared' | 'page-isolated' | 'page-apply-shared' | 'page-shared' // 设置样式隔离选项 + multipleSlots?: boolean // 启用多 slot 支持 + addGlobalClass?: boolean // 允许组件的样式影响到外部 + } +} +``` + +options 支持以下配置： +* **virtualHost**: 设置组件是否是虚拟的 +* **styleIsolation**: 设置组件样式隔离选项 +* **multipleSlots**: 是否启用多 slot 支持，仅微信和QQ需要配置 +* **addGlobalClass**: 是否允许组件的样式影响外部 + +但需要注意的是，此处的 options 配置为 base 微信小程序的语法特性，在跨端输出其他平台时，由于依赖平台底层能力支持与否，因此无法做到全部功能抹平。 + +| 选项 | 微信 | 支付宝 | 百度 | QQ | 字节 | Web | RN | 说明 | +|------|------|--------|------|-----|------|-----|-----|-----| +| virtualHost | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | Mpx 以微信为base，virtualHost 默认为 false，跨端输出Web、支付宝时默认会在自定义组件根节点包裹一层节点，开发者也可以通过[编译配置](https://mpxjs.cn/api/compile.html#autovirtualhostrules)进行控制 | +| styleIsolation | ✓ | 部分支持 | ✗ | ✓ | ✗ | ✗ | ✗ | 微信默认开启样式隔离，目前只有支付宝小程序平台没有样式隔离能力, 当组件 style 标签配置 scoped 时，Mpx 输出支付宝会默认抹平开启样式隔离，开发者也可通过[编译配置](https://mpxjs.cn/api/compile.html#autoscoperules)进行控制 | +| multipleSlots | ✓ | - | - | ✓ | - | - | - | 目前仅微信和QQ使用多个slot需要配置multipleSlots，其他平台默认支持使用多slot | +| addGlobalClass | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | - | + +>**注意：** +> * virtualHost 在支付宝平台默认为 false +>options 中的特性以微信小程序为 base，随着微信小程序的持续迭代，此处列出的特性可能会存在部分缺失。 +>同时对于上述各特性的具体使用，特别是各小程序平台，开发者也可以在对应小程序开发文档中查找参考。 + +### 组件生命周期 +在 Mpx 内组件生命周期可以使用[框架内置生命周期](框架内置生命周期)，也可以使用以微信原生base的生命周期，在使用微信原生base的生命周期时，在跨平台输出时，框架会对生命周期进行映射抹平，将不同小程序平台的生命周期转换映射为内置生命周期后再进行统一的驱动，以抹平不同小程序平台生命周期钩子的差异。 + +在选项式 API 中，可以使用微信 base 或者 Mpx 框架暴露的内置生命周期。 + +微信原生生命周期： + +| 生命周期 | 说明 | +|-----------------|------| +| created | 在组件实例初始化完成时调用 | +| attached | 在组件挂载开始之前调用 | +| ready | 在组件在视图层布局完成后调用 | +| detached | 在组件实例销毁时调用 | + +在组合式 API 中，需要使用框架暴露的统一的[生命周期钩子](https://mpxjs.cn/api/composition-api.html#%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E9%92%A9%E5%AD%90) + +### pageLifetimes +组件中访问页面生命周期 + +在选项式中可以直接使用 pageLifetimes.show 之类的配置： + +| 生命周期 | 说明 | +|-----------------|------| +| show | 组件所在页面显示 | +| hide | 组件所在页面隐藏 | +| resize | 组件所在页面尺寸发生变化 | + +在组合式 API 中，需要使用框架暴露的 onShow、onHide、onResize，详情可[查看](https://mpxjs.cn/api/composition-api.html#%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E9%92%A9%E5%AD%90) + + +## 组件实例方法 + +### setData + +更新视图数据，无论数据value是否改变，都会强制刷新视图。 + +```ts +interface Component { + setData( + data: Record, + callback?: () => void + ): void +} +``` + +setData 支持以下功能: +* 修改 data 数据 +* 支持设置回调函数，回掉函数在视图更新完成后执行 +* 支持批量更新多个数据 + +```js +import { createComponent } from '@mpxjs/core' +createComponent({ + data: { + text: 'init data', + }, + methods: { + changeData() { + // 修改数据 + this.setData({ + text: 'changed data' + }) + // 设置回调函数 + this.setData({ + text: 'changed data' + }, function() { + console.log('数据更新完成') + }) + } + } +}) +``` +在 Mpx 内请慎重使用 setData，建议直接使用组件实例修改数据 +```js +this.text = 'some data' +``` + +| API | 微信 | 支付宝 | 百度 | QQ | 字节 | Web | RN | 说明 | +|------|------|--------|------|-----|------|-----|-----|-----| +| setData | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | - | + +### triggerEvent + +### getPageId + +### selectComponent + +### createSelectorQuery + +### createIntersectionObserver + +### selectAllComponents + +### hasBehavior + +## 动态组件 + +Mpx中提供了使用方法类似于 Vue 的动态组件能力，这是一个基于 wx:if 实现的语法。通过对 `is` 属性进行动态绑定，可以实现在同一个挂载点切换多个组件，前提需要动态切换的组件已经在全局或者组件中完成注册。 + +使用示例如下： + +```html + + + + + + + + + +``` + +## slot + +在组件中使用slot（插槽）可以使我们封装的组件更具有可扩展性，Mpx完全支持原生插槽的使用。 + +### 基础用法 + +```html + + + + 这是组件模板 + + + +``` + +使用组件时： + +```html + + + + + + +``` + +> 注意：使用多个slot时，需要在组件选项中开启 `multipleSlots: true`。 + +更多关于插槽的使用细节可查看[微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html)。 diff --git a/docs-vuepress/guide/basic/conditional-render.md b/docs-vitepress/guide/basic/conditional-render.md similarity index 100% rename from docs-vuepress/guide/basic/conditional-render.md rename to docs-vitepress/guide/basic/conditional-render.md diff --git a/docs-vuepress/guide/basic/css.md b/docs-vitepress/guide/basic/css.md similarity index 100% rename from docs-vuepress/guide/basic/css.md rename to docs-vitepress/guide/basic/css.md diff --git a/docs-vuepress/guide/basic/event.md b/docs-vitepress/guide/basic/event.md similarity index 100% rename from docs-vuepress/guide/basic/event.md rename to docs-vitepress/guide/basic/event.md diff --git a/docs-vuepress/guide/basic/ide.md b/docs-vitepress/guide/basic/ide.md similarity index 100% rename from docs-vuepress/guide/basic/ide.md rename to docs-vitepress/guide/basic/ide.md diff --git a/docs-vuepress/guide/basic/intro.md b/docs-vitepress/guide/basic/intro.md similarity index 100% rename from docs-vuepress/guide/basic/intro.md rename to docs-vitepress/guide/basic/intro.md diff --git a/docs-vuepress/guide/basic/list-render.md b/docs-vitepress/guide/basic/list-render.md similarity index 100% rename from docs-vuepress/guide/basic/list-render.md rename to docs-vitepress/guide/basic/list-render.md diff --git a/docs-vuepress/guide/basic/option-chain.md b/docs-vitepress/guide/basic/option-chain.md similarity index 100% rename from docs-vuepress/guide/basic/option-chain.md rename to docs-vitepress/guide/basic/option-chain.md diff --git a/docs-vuepress/guide/basic/reactive.md b/docs-vitepress/guide/basic/reactive.md similarity index 100% rename from docs-vuepress/guide/basic/reactive.md rename to docs-vitepress/guide/basic/reactive.md diff --git a/docs-vuepress/guide/basic/refs.md b/docs-vitepress/guide/basic/refs.md similarity index 100% rename from docs-vuepress/guide/basic/refs.md rename to docs-vitepress/guide/basic/refs.md diff --git a/docs-vuepress/guide/basic/single-file.md b/docs-vitepress/guide/basic/single-file.md similarity index 100% rename from docs-vuepress/guide/basic/single-file.md rename to docs-vitepress/guide/basic/single-file.md diff --git a/docs-vuepress/guide/basic/start.md b/docs-vitepress/guide/basic/start.md similarity index 84% rename from docs-vuepress/guide/basic/start.md rename to docs-vitepress/guide/basic/start.md index 541a2b72e9..01541f4faa 100644 --- a/docs-vuepress/guide/basic/start.md +++ b/docs-vitepress/guide/basic/start.md @@ -31,12 +31,68 @@ npm install ## 编译构建 +相关命令 + +```json +{ + "serve": "mpx-cli-service serve", // 开发模式 + "build": "mpx-cli-service build" // 构建模式 +} +``` + 使用npm script执行mpx的编译构建，在开发模式下我们执行serve命令，将项目源码构建输出到`dist/${平台目录}`下，并且监听源码的改动进行重新编译。 ```shell npm run serve ``` +### CLI 命令 + +#### build + +```sh +用法：mpx-cli-service build [options] + +选项: + + --targets 编译目标(默认值: wx) + --mode 指定环境模式 development | production (默认值：production) + --env 自定义 __mpx_env__ + --watch 监听文件变化 + --report 生成包分析报告 +``` +```sh +# 构建小程序，默认微信 +mpx-cli-service build --targets=wx,ali +``` + +**目前支持的平台** + +| 平台 | target | +|-----|---------| +| 微信 | wx | +| 阿里 | ali | +| 百度 | swan | +| QQ | qq | +| 头条 | tt | +| 浏览器 | web | +| 安卓 | android | +| iOS | ios | +| 鸿蒙 | harmony | + + +#### serve + +```sh +用法：mpx-cli-service serve [options] + +选项: + + --targets 编译到小程序目标(默认值: wx) + --mode 指定环境模式 (默认值：production) + --env 自定义 __mpx_env__ +``` + ## 预览调试 使用小程序开发者工具打开dist下对应平台的目录，对你的小程序进行预览、调试，详情可参考[小程序开发指南](https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/getstart.html) @@ -165,6 +221,3 @@ npm run build:cross ``` 关于跨平台能力的更多详情请查看[这里](../advance/platform.md) - - - diff --git a/docs-vuepress/guide/basic/template.md b/docs-vitepress/guide/basic/template.md similarity index 100% rename from docs-vuepress/guide/basic/template.md rename to docs-vitepress/guide/basic/template.md diff --git a/docs-vuepress/guide/basic/two-way-binding.md b/docs-vitepress/guide/basic/two-way-binding.md similarity index 100% rename from docs-vuepress/guide/basic/two-way-binding.md rename to docs-vitepress/guide/basic/two-way-binding.md diff --git a/docs-vuepress/guide/composition-api/composition-api.md b/docs-vitepress/guide/composition-api/composition-api.md similarity index 100% rename from docs-vuepress/guide/composition-api/composition-api.md rename to docs-vitepress/guide/composition-api/composition-api.md diff --git a/docs-vuepress/guide/composition-api/reactive-api.md b/docs-vitepress/guide/composition-api/reactive-api.md similarity index 100% rename from docs-vuepress/guide/composition-api/reactive-api.md rename to docs-vitepress/guide/composition-api/reactive-api.md diff --git a/docs-vuepress/guide/extend/api-proxy.md b/docs-vitepress/guide/extend/api-proxy.md similarity index 84% rename from docs-vuepress/guide/extend/api-proxy.md rename to docs-vitepress/guide/extend/api-proxy.md index b7d13b7304..c964112de2 100644 --- a/docs-vuepress/guide/extend/api-proxy.md +++ b/docs-vitepress/guide/extend/api-proxy.md @@ -29,14 +29,14 @@ proxy.navigateTo({ ## Options -|参数名称|类型|含义|是否必填|默认值|备注| -|---|---|---|---|---|---| -|platform|Object|各平台之间的转换|否|{ from:'', to:'' }|使用 mpx 脚手架配置会自动进行转换，无需配置| +|参数名称|类型|含义|是否必填| 默认值 |备注| +|---|---|---|---|-------|---| +|platform|Object|各平台之间的转换|否| |使用 mpx 脚手架配置会自动进行转换，无需配置| |exclude|Array(String)|跨平台时不需要转换的 api|-| -|usePromise|Boolean|是否将 api 转化为 promise 格式使用|否|false|-| -|whiteList|Array(String)|强行转化为 promise 格式的 api|否|[]|需要 usePromise 设为 true| -|blackList|Array(String)|强制不变成 promise 格式的 api|否|[]|-| -|fallbackMap|Object|对于不支持的API，允许配置一个映射表，接管不存在的API|否|{}|-| +|usePromise|Boolean|是否将 api 转化为 promise 格式使用|否| false |-| +|whiteList|Array(String)|强行转化为 promise 格式的 api|否| [] |需要 usePromise 设为 true| +|blackList|Array(String)|强制不变成 promise 格式的 api|否| [] |-| +|fallbackMap|Object|对于不支持的API，允许配置一个映射表，接管不存在的API|否| {} |-| ## example diff --git a/docs-vuepress/guide/extend/fetch.md b/docs-vitepress/guide/extend/fetch.md similarity index 100% rename from docs-vuepress/guide/extend/fetch.md rename to docs-vitepress/guide/extend/fetch.md diff --git a/docs-vuepress/guide/extend/index.md b/docs-vitepress/guide/extend/index.md similarity index 100% rename from docs-vuepress/guide/extend/index.md rename to docs-vitepress/guide/extend/index.md diff --git a/docs-vuepress/guide/extend/mock.md b/docs-vitepress/guide/extend/mock.md similarity index 100% rename from docs-vuepress/guide/extend/mock.md rename to docs-vitepress/guide/extend/mock.md diff --git a/docs-vuepress/guide/migrate/2.7.md b/docs-vitepress/guide/migrate/2.7.md similarity index 100% rename from docs-vuepress/guide/migrate/2.7.md rename to docs-vitepress/guide/migrate/2.7.md diff --git a/docs-vuepress/guide/migrate/2.8.md b/docs-vitepress/guide/migrate/2.8.md similarity index 100% rename from docs-vuepress/guide/migrate/2.8.md rename to docs-vitepress/guide/migrate/2.8.md diff --git a/docs-vuepress/guide/migrate/2.9.md b/docs-vitepress/guide/migrate/2.9.md similarity index 100% rename from docs-vuepress/guide/migrate/2.9.md rename to docs-vitepress/guide/migrate/2.9.md diff --git a/docs-vuepress/guide/migrate/mpx-cli-3.md b/docs-vitepress/guide/migrate/mpx-cli-3.md similarity index 100% rename from docs-vuepress/guide/migrate/mpx-cli-3.md rename to docs-vitepress/guide/migrate/mpx-cli-3.md diff --git a/docs-vuepress/guide/platform/index.md b/docs-vitepress/guide/platform/basic.md similarity index 100% rename from docs-vuepress/guide/platform/index.md rename to docs-vitepress/guide/platform/basic.md diff --git a/docs-vitepress/guide/platform/miniprogram.md b/docs-vitepress/guide/platform/miniprogram.md new file mode 100644 index 0000000000..0390001e1b --- /dev/null +++ b/docs-vitepress/guide/platform/miniprogram.md @@ -0,0 +1 @@ +# 跨端输出小程序 diff --git a/docs-vitepress/guide/platform/rn.md b/docs-vitepress/guide/platform/rn.md new file mode 100644 index 0000000000..118cfe4aa9 --- /dev/null +++ b/docs-vitepress/guide/platform/rn.md @@ -0,0 +1,2550 @@ +# 跨端输出RN + +## 跨端样式定义 +RN 样式属性和 Web/小程序中 CSS 样式属性是相交关系，RN 有一小部分样式属性（比如 tintColor、writingDirection 等） CSS 不支持，CSS 也有少部分样式属性 RN 不支持（比如 clip-path、animation、transition 等）。 + +因此，一方面，在我们进行跨平台开发时，跨平台样式属性声明要尽量使用两边样式属性的交集；另一方面为了减少开发适配的成本，Mpx 内部也对 RN 的样式作了部分抹平。 + +Mpx 框架在样式处理部分的具体工作主要分为两大类有： + +**编译时的class类样式转化** +- 属性名转驼峰 +- 单位的校验和对齐 +- 过滤 RN 不支持的属性和属性值 +- 简写转换 +- 样式属性差异转换和拉齐 + +**运行时的style样式处理** +- 属性名转驼峰 +- 单位的计算和处理 +- 100% 计算 +- css func 处理，包括 env()、calc()、var() +### CSS选择器 +RN 环境下仅支持单个**类选择器**，不支持类名组合选择器，不过逗号组合的选择器本质上还是单类选择器，是可以支持的。 +``` css +/* 支持 */ +.classname { + color: red +} +.classA, .classB { + color: red +} +/* 不支持 */ +view, text { + color: red +} +.classA .classB { + color: red +} +``` +### 样式单位 +Mpx转RN, 支持以下单位，部分单位在部分情况下存在使用限制 +#### 数值类型单位说明 +| 单位 | 支持情况 | 特殊说明 | +| ---- | ---- | ---- | +| % | 支持 | 百分比单位参考下面说明| +| px | 支持 | 无 | +| rpx | 支持 | rpx会根据屏幕宽度动态计算成实际的px | +| vh | 支持 | 屏幕的高度，在使用非自定义导航时，页面初次渲染计算出来的vh是屏幕高度，后续更新渲染使用实际可视区域高度，推荐使用此单位的页面使用自定义导航 | +| vw | 支持 | 无 | +#### 百分比单位说明 +RN很多原生较多属性不支持百分比，比如font-size、translate等，但是这些属性在编写web、小程序代码的过程中使用较多，框架进行了抹平支持。以下这些属性在Mpx输出RN时专门进行了百分比单位的适配，部分属性存在编写的时候的特殊适配。 +##### 特殊的百分比计算规则 +###### font-size + +font-size 百分比计算依赖开发者传入的 parent-font-size 属性，框架将根据开发者传入 parent-font-size 的值来计算 font-size 的百分比大小 +> 备注：当 font-size 设置为百分比，未设置 parent-font-size 属性或者 parent-font-size 属性值非数值，会报错提示开发者且框架不计算 font-size 直接返回 + +###### line-height + +和 Web/小程序类似，当设置 line-height: 1.2; line-height: 120%; 这种 number 或百分比值时，实际都是按百分比来计算。line-height 的百分比计算基准是 font-size 的大小，所以在设置 line-height 为 number 或者百分比值时，要保证同时有设置 font-size 大小。 + +> 备注：设置 line-height 注意区分有无单位，line-height: 12 会按照 line-height: 1200% 来计算处理，line-height: 12px 会按照正常单位计算。 +##### 根据自身宽高计算百分比 +translateX/translateY/border-radius 的百分比都是根据自身宽高的来计算的。 +> 注意事项 +> - RN 0.76 版本 translateX/translateY 支持百分比 +> - translateX/border-radius 都是根据节点的 width 来计算百分比，而 translateY 是根据节点的 height 来计算的百分比 +> - border-radius-*(top/right/bottom/left) 百分比计算逻辑和 border-radius 一致 +> - 根据自身宽高计算百分比需要在完成渲染后在 onLayout 获取自身宽高计算并设置，故这些属性设置生效都在第一次 onLayout 后 +> - 因动画执行不会触发 onLayout，所以最好不要在动画中使用这些属性的百分比 +##### 根据父节点宽高计算百分比 +除了上述两中规则外，属性 width/left/right/height/top/bottom/margin/padding 等设置百分比时的计算基准都是父节点的宽高，且 RN 支持设置百分比，无需框架额外处理。 + +有一种情况例外，则是在上述属性值中设置为 calc 函数且表达式使用百分比，如 width: calc(100% - 10px)。 + +###### calc() 函数内的百分比使用方式 + +如有在 calc 函数表达式内使用百分比的场景，则需要开发者设置 parent-width 或 parent-height 属性，传入百分比计算的基准值。 + +以父节点高度为基准值计算百分比的属性如 height/top/bottom 则需要传入 parent-height 属性；以父节点宽度为基准值计算百分比的属性如 width/left/right 则需要传入 parent-width 属性。 + +> 备注：属性通过父节点宽度还是高度来计算基准，一般遵循纵向以高度为基准，横向以宽度为基准的大原则 +#### 色值 color 类型支持的值格式说明 +- hex-color(十六进制) +- rgb/rgba +- hsl/hsla +- hwb +- named color，具体参考[颜色枚举值](https://reactnative.dev/docs/colors#named-colors) +- Color ints(仅 RN 支持，如 0xff00ff00 ) + +```css +/* 值 */ +color: red; +color: orange; +color: tan; +color: rebeccapurple; + +/* 值 */ +color: #090; +color: #009900; +color: #090a; +color: #009900aa; + +/* 值 */ +color: rgb(34, 12, 64, 0.6); +color: rgba(34, 12, 64, 0.6); +color: rgb(34 12 64 / 0.6); +color: rgba(34 12 64 / 0.3); +color: rgb(34 12 64 / 60%); +color: rgba(34.6 12 64 / 30%); + +/* 值 */ +color: hsl(30, 100%, 50%, 0.6); +color: hsla(30, 100%, 50%, 0.6); +color: hsl(30 100% 50% / 0.6); +color: hsla(30 100% 50% / 0.6); +color: hsl(30 100% 50% / 60%); +color: hsla(30.2 100% 50% / 60%); + +/* 值 */ +color: hwb(90 10% 10%); +color: hwb(90 10% 10% / 0.5); +color: hwb(90deg 10% 10%); +color: hwb(1.5708rad 60% 0%); +color: hwb(0.25turn 0% 40% / 50%); +``` + +### 文本样式继承 +Web/小程序中，文本节点可以通过 div/view 节点进行直接包裹，在 div/view 节点上也可以直接设定对应文本样式。 +但是在RN中，必须通过 Text 来创建文本节点，[文本样式属性](https://reactnative.dev/docs/text-style-props)只有设置给 Text 节点才能生效。 +Mpx 框架抹平了这部分的差异，在使用 Mpx 转 RN 时，我们可以使用 view 节点直接包裹文本，也可以在 view 节点上设置文本样式作用到直接子 text 节点上。 +但仍因受限于[RN内 text 的样式继承原则的限制](https://reactnative.dev/docs/text#limited-style-inheritance)，只有 view 节点下的子 text 节点可以继承 view 节点上的文本样式，且 text 节点之间可以继承。 +具体参考以下代码： +#### 示例代码 +``` html + + + 文本1 + 文本2 + 文本3 + 文本4 + 文本5 + + +.wrapper { + font-size: 20px; +} +.content { + text-align: right; +} + +``` +> 备注 +> 1. 只有父级 view 节点的文本样式可以被子 text 节点继承； +> 2. view 节点直接包裹文本实际上等同于 view>text>文本，Mpx 框架在编译时若检测到 view 节点直接包裹文本会自动添加一层 text 节点； +> 3. 多级 text 节点可实现文本样式的继承，比如 text>text>文本 ； +> 4. 若不想使用 Mpx 内部实现的 view>text>文本 这种文本样式继承，可设置`disable-default-style=true` 来关闭该继承逻辑； +### 简写样式属性 +在 Mpx 内对于通过 class 类来定义的样式会按照 RN 的样式规则在编译处理一遍，其中最重要的一部分就是将 RN 不支持简写属性按约定的规则转换成 RN 能支持多属性结构。 + +现已支持的简写属性如下: +- [text-shadow](#text-shadow) +- [text-decoration](#text-decoration) +- [flex](#flex) +- [flex-flow](#flex-flow) +- [margin](#margin) +- [padding](#padding) +- [background](#background) +- [box-shadow](#box-shadow) +- [border-radius](#border-radius) +- [border-width](#border-width) +- [border-color](#border-color) +- [border](#border) +- [border-top|border-right|border-bottom|border-left](#border-topborder-rightborder-bottomborder-left) + +> **注意事项** +> +> - 考虑到运行时转化的性能开销问题，简写能力只在编译处理时转化，所以 class 类上设置时简写属性会处理转化的，而在 style 属性上使用了对应的简写是不会转化的，若对应的简写属性 RN 不支持，则在 RN style 属性上不能使用，需直接使用多个属性组合来实现。 +> - 简写属性不支持 单个 var() 函数，所以简写属性传入单个 var() 编译时会有错误提示，并且原样返回，这可能会导致 RN 运行时错误。 +> - 若是多个 var() 函数则会按顺序赋给各个属性 + +### CSS函数 +在介绍 CSS 函数前我们先来了解一下自定义属性的概念。 +#### 自定义属性（CSS 变量） +**自定义属性**（有时候也被称作 **CSS 变量**或者**级联变量**），带有前缀 -- 的属性名，表示的是带有值的自定义属性，比如 --example--name。 + +通常与 var() 一起使用，由自定义属性标记设定值（带有前缀 -- 的属性名，比如： --main-color: black;），由 var() 函数来获取值（比如： color: var(--main-color);） +> 备注 +> - 自定义属性受级联的约束，并从其父级继承其值 +> - 自定义属性名区分大小写 +#### var() +var() 函数可以插入一个自定义属性（有时也被称为“CSS 变量”）的值，用来代替属性值部分。 + +`var( , ? )`：函数的第一个参数是要替换的自定义属性的名称。函数的第二个参数是可选的，用作回退值。如果第一个参数引用的自定义属性无效，则该函数将使用第二个值。 + +> 备注 +> - 自定义属性的回退值允许使用逗号。例如，var(--foo, red, blue) 将 red, blue 同时指定为回退值（在第一个逗号之后到函数结尾前的值都会被认为是回退值） +> - var() 函数不能作为属性名、选择器或者其他除了属性值之外的值 +```vue + + + + + + + + +``` +#### calc() +calc() 函数允许在声明 CSS 属性值时执行一些计算。 + +calc() 函数用一个表达式作为它的参数，用这个表达式的结果作为值。 + +这个表达式采用标准操作符处理法则的简单表达式，支持加减乘除 ，乘法计算需要乘数中至少有一个是 number，除法计算要求除数（/右面的数）必须是 number。 +> 备注 +> - \+ 和 - 运算符的两边必须要有空白字符，\* 和 / 这两个运算符前后不需要空白字符，但如果考虑到统一性，仍然推荐加上空白符。 +> - 能数值化的单位都支持 calc() 函数 +> - 百分比的计算逻辑详见样式单位部分的[百分比单位说明](#百分比单位说明) +```css +/* 代码示意 */ + +/* property: calc(expression) */ +.test { + width: calc(100% - 80px); +} + +/* 使用 CSS 变量嵌套使用 calc() */ +.foo { + --widthA: 100px; + --widthB: calc(var(--widthA) / 2); + --widthC: calc(var(--widthB) / 2); + width: var(--widthC); +} + +.demo { + font-size: calc(1.5rem + 3vw); +} +``` +#### env() +env() 用于将定义的环境变量的值插入到 CSS 中。 + +第一个参数为系统环境变量，具体可选值有 safe-area-inset-top、safe-area-inset-right、safe-area-inset-bottom、safe-area-inset-left，分别定义了视口上右下左各边缘的安全距离。 + +第二个可选参数是环境变量不可用时的回退值。 + +env() 函数通过和 var() 函数类似形式， 区别在于：一是环境变量是系统定义的，而 var() 函数是开发者自定义；二是环境变量是全局生效，而 var() 函数的自定义属性不能在声明之外使用。 + +```css +/* 代码示意 */ +.demo { + padding: env(safe-area-inset-top, 20px) env(safe-area-inset-right, 20px) env(safe-area-inset-bottom, 20px) env(safe-area-inset-left, 20px); +} +``` +> 注意事项 +### 使用原子类 +后续支持。 + +## 混合编写RN代码 +在编写Mpx组件时，在特定情况下（处于性能考虑等因素），可能会涉及到混合开发(在Mpx项目内编写RN组件) + +### 使用RN组件 +在Mpx组件内引用RN组件，采用如下方式 +- **RN组件注册方式**：需在components属性下进行引用注册。 +- **RN组件的属性与事件**：属性与事件参考RN原生支持的属性与事件名，对应赋值方式按照Mpx语法进行双括号包裹，组件使用的值需要通过 REACTHOOKSEXEC方法的返回值的方式进行声明。 +- **RN组件的样式定义**: 组件支持样式属性的透传，通过在RN组件上定义styles即可透传样式 +- **其他功能**: 支持在RN组件内使用slot +```javascript + + +``` +### 使用React hooks +Mpx提供了hooks的执行机制，通过在Mpx组件内注册REACTHOOKSEXEC方法，保障RN组件的初始化执行。hooks的返回值支持数据与方法 +- 模板上RN组件/Mpx组件的数据渲染 +- 模板上的Props传递 +- 模板上的样式定义 +- 模板上的事件的绑定与透传 + +```javascript + + +``` +## 能力支持范围 + +### 模版语法 + +#### 模版指令 +Mpx 输出 React Native 支持以下模版指令。 + +**wx:if** + +输出React Native已支持，[详情查看 - wx:if](/api/directives.html#wx-if) + +**wx:else** + +输出React Native已支持，[详情查看 - wx:else](/api/directives.html#wx-else) + + +**wx:elif** + +输出React Native已支持，[详情查看 - wx:elif](/api/directives.html#wx-elif) + +**wx:show** + +输出React Native已支持，[详情查看 - wx:show](/api/directives.html#wx-show) + +**wx:for** + +输出React Native已支持，[详情查看 - wx:for](/api/directives.html#wx-for) + +**wx:for-item** + +输出React Native已支持，[详情查看 - wx:for-item](/api/directives.html#wx-for-item) + +**wx:for-index** + +输出React Native已支持，[详情查看 - wx:for-index](/api/directives.html#wx-for-index) + +**wx:class** + +输出React Native已支持，[详情查看 - wx:class](/api/directives.html#wx-class) + +**wx:style** + +输出React Native已支持，[详情查看 - wx:style](/api/directives.html#wx-style) + +**wx:model** + +输出React Native已支持，[详情查看 - wx:model](/api/directives.html#wx-model) + +**wx:model-prop** + +输出React Native已支持，[详情查看 - wx:model-prop](/api/directives.html#wx-model-prop) + +**wx:model-event** + +输出React Native已支持，[详情查看 - wx:model-event](/api/directives.html#wx-model-event) + +**wx:model-value-path** + +输出React Native已支持，[详情查看 - wx:model-value-path](/api/directives.html#wx-model-value-path) + +**wx:model-filter** + +输出React Native已支持，[详情查看 - wx:model-filter](/api/directives.html#wx-model-filter) + +**wx:ref** + +使用wx:ref可以更方便获取基础节点及自定义组件实例。 + +* 如果获取的是基础节点（nodeRef），那么可以通过基础节点暴露的相应 api 获取基础节点的样式属性等内容； +* 如果是获取的自定义组件实例，那么可以直接调用组件实例上的方法或属性； + +```html + + + + +``` + +**@mode** + +跨端输出 React Native 时，对模版中节点或属性进行平台纬度的条件编译。[详情查看](/api/directives.html#mode) + +**@_mode** + +跨端输出 React Native 时，对节点或属性进行平台纬度的条件编译并保留跨平台转换能力。[详情查看](/api/directives.html#mode) + +**@env** + +跨端输出场景下，除了 mode 平台场景值，Mpx 框架还提供自定义 env 目标应用，来实现在不同应用下编译产出不同的代码。 + +**参考：** +* [通过 env 实现自定义目标环境的条件编译](/guide/advance/platform.html#use-env) +* [@env 指令](/api/directives.html#env) + +**mpxTagName** + +支持跨平台输出时针对节点标签名进行条件编译，可以配合属性维度条件编译使用, +例如在 iOS 环境下希望将某个 view 标签替换为 cover-view，可以使用该功能： + +```html +will be cover-view in iOS +``` + +#### 事件处理 +目前 Mpx 输出 React Native 的事件编写遵循小程序的事件编写规范，支持事件的冒泡及捕获 + +普通事件绑定 +```js + + Click here! + +``` + +绑定并阻止事件冒泡 +```js + + Click here! + +``` + +事件捕获 + +```js + + outer view + + inner view + + +``` + +中断捕获阶段和取消冒泡阶段 + +```js + + outer view + + +``` + +在此基础上也新增了事件处理内联传参的增强机制。 + +```html + + +``` + +除此之外，Mpx 也支持了动态事件绑定 + +```html + + +``` + +注意事项 + +1. 当同一个元素上同时绑定了 catchtap 和 bindtap 事件时，两个事件都会被触发执行。但是是否阻止事件冒泡的行为,会以模板上第一个绑定的事件标识符为准。 +如果第一个绑定的是 catchtap，那么不管后面绑定的是什么,都会阻止事件冒泡。如果第一个绑定的是 bindtap，则不会阻止事件冒泡。 +2. 当同一个元素上绑定了 capture-bind:tap 和 bindtap 事件时，事件的执行时机会根据模板上第一个绑定事件的标识符来决定。如果第一个绑定的是 capture-bind:tap，则事件会在捕获阶段触发，如果第一个绑定的是 bindtap，则事件会在冒泡阶段触发。 +3. 当使用了事件委托想获取 e.target.dataset 时，只有点击到文本节点才能获取到，点击其他区域无效。建议直接将事件绑定到事件触发的元素上，使用 e.currentTarget 来获取 dataset 等数据。 +4. 由于 tap 事件是由 touchend 事件模拟实现，所以如果子组件绑定了 catchtap，那么父组件的 touchend 事件将不会响应。同理如果子组件绑定了 catchtouchend，那么父组件的 tap 事件将不会响应。 +5. 如果元素上设置了 opacity: 0 的样式，会导致 ios 事件无法响应。 + +### 基础组件 +目前 Mpx 输出 React Native 仅支持以下组件，文档中未提及的组件以及组件属性即为不支持，具体使用范围可参考如下文档 + +RN环境基础组件通用属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| enable-offset | Boolean | false | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| +| enable-var | Boolean | true | 默认支持使用 css variable，若想关闭该功能可设置为 false | +| parent-font-size | Number | | 父组件字体大小，主要用于百分比计算的场景，如 font-size: 100%| +| parent-width | Number | | 父组件宽度，主要用于百分比计算的场景，如 width: calc(100% - 20px)，需要在外部传递父组件的宽度| +| parent-height | Number | | 父组件高度，主要用于百分比计算的场景，如 height: calc(100% - 20px),需要在外部传递父组件的高度| + +#### view +视图容器。 +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| hover-class | string | | 指定按下去的样式类。 | +| hover-start-time | number | 50 | 按住后多久出现点击态，单位毫秒| +| hover-stay-time | number | 400 | 手指松开后点击态保留时间，单位毫秒 | +| enable-offset | Number | false | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| + +事件 + +| 事件名 | 说明 | +| ----------------| --------------------------------------------------- | +| bindtap | 点击的时候触发 | + + +#### scroll-view +可滚动视图区域。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | --------- | -------------------------------------------------- | +| scroll-x | Boolean | `false` | 允许横向滚动动 | +| scroll-y | Boolean | `false` | 允许纵向滚动 | +| upper-threshold | Number | `50` | 距顶部/左边多远时(单位 px),触发 scrolltoupper 事件 | +| lower-threshold | Number | `50` | 距底部/右边多远时(单位 px),触发 scrolltolower 事件 | +| scroll-top | Number | `0` | 设置纵向滚动条位置 | +| scroll-left | Number | `0` | 设置横向滚动条位置 | +| scroll-with-animation | Boolean | `false` | 在设置滚动条位置时使用动画过渡 | +| enable-back-to-top | Boolean | `false` | 点击状态栏的时候视图会滚动到顶部 | +| enhanced | Boolean | `false` | scroll-view 组件功能增强 | +| refresher-enabled | Boolean | `false` | 开启自定义下拉刷新 | +| scroll-anchoring | Boolean | `false` | 开启滚动区域滚动锚点 | +| scroll-into-view | Boolean | `false` | 值应为某子元素id（id不能以数字开头） | +| refresher-default-style | String | `'black'` | 设置下拉刷新默认样式,支持 `black`、`white`、`none`，仅安卓支持 | +| refresher-background | String | `'#fff'` | 设置自定义下拉刷新背景颜色，仅安卓支持 | +| refresher-triggered | Boolean | `false` | 设置当前下拉刷新状态,true 表示已触发 | +| paging-enabled | Number | `false` | 分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置 | +| show-scrollbar | Number | `true` | 滚动条显隐控制 (同时开启 enhanced 属性后生效)| +| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| +| enable-trigger-intersection-observer | Boolean | [] | 是否开启intersection-observer | +| simultaneous-handlers | `Array` | [] | 主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 | +| wait-for | `Array` | [] | 主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 | + + +事件 + +| 事件名 | 说明 | +| ----------------| ------------------ | +| binddragstart| 滑动开始事件，同时开启 enhanced 属性后生效| +| binddragging| 滑动事件，同时开启 enhanced 属性后生效 | +| binddragend| 滑动结束事件，同时开启 enhanced 属性后生效 | +| bindscrolltoupper | 滚动到顶部/左边触发 | +| bindscrolltolower | 滚动到底部/右边触发 | +| bindscroll | 滚动时触发 | +| bindrefresherrefresh| 自定义下拉刷新被触发 | + +注意事项 + +1. 目前不支持自定义下拉刷新节点，使用 slot="refresher" 声明无效，在 React Native 环境中还是会被当作普通节点渲染出来 +2. 若使用 scroll-into-view 属性，需要 id 对应的组件节点添加 wx:ref 标记，否则无法正常滚动 +3. simultaneous-handlers 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture) +4. wait-for 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail) + + +#### swiper +滑块视图容器。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------------ | ------------------------------------| +| indicator-dots | Boolean | `false` | 是否显示面板指示点 | +| indicator-color | color | `rgba(0, 0, 0, .3)` | 指示点颜色 | +| indicator-active-color | color | `#000000` | 当前选中的指示点颜色 | +| autoplay | Boolean | `false` | 是否自动切换 | +| current | Number | `0` | 当前所在滑块的 index | +| interval | Number | `5000` | 自动切换时间间隔 | +| duration | Number | `500` | 滑动动画时长 | +| circular | Boolean | `false` | 是否采用衔接滑动 | +| vertical | Boolean | `false` | 滑动方向是否为纵向 | +| previous-margin | String | `0` | 前边距，可用于露出前一项的一小部分，接受px | +| next-margin | String | `0` | 后边距，可用于露出后一项的一小部分，接受px | +| scale | Boolean | `false` | 滑动时是否开启前后元素缩小,默认是缩放0.7倍, 暂不支持自定义 | +| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| +| easing-function | String | `linear` | 支持 linear、easeInCubic、easeOutCubic、easeInOutCubic| +| bindchange | eventhandle| 无 | current 改变时会触发 change 事件，`event.detail = {current, source}`| + + + + +事件 + +| 事件名 | 说明 | +| ----------------| ------------------ | +| bindchange| current 改变时会触发 change 事件，`event.detail = {current, source}`| + +#### swiper-item +仅可放置在swiper组件中，宽高自动设置为100%。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------------ | ------------------------------------| +| item-id | string | `无` | 该 swiper-item 的标识符 | + +#### movable-area +movable-view的可移动区域。 + +注意事项 + +1. movable-area不支持设置 scale-area，缩放手势生效区域仅在 movable-view 内 + +#### movable-view +可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。 + + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ------ | ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | +| direction | String | none | 目前支持 all、vertical、horizontal、none｜ +| inertia | boolean | false | movable-view是否带有惯性｜ +| out-of-bounds | boolean | false | 超过可移动区域后，movable-view是否还可以移动｜ +| x | Number | | 定义x轴方向的偏移 | +| y | Number | | 定义y轴方向的偏移 | +| friction | Number | 7 | 摩擦系数 | +| disabled | boolean | false | 是否禁用 | +| animation | boolean | true | 是否使用动画 | +| simultaneous-handlers | `Array` | [] | 主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 | +| wait-for | `Array` | [] | 主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 | + +事件 + +| 事件名 | 说明 | +| -------------------- | ------------------------------------------ | +| bindchange | 拖动过程中触发的事件，`event.detail = {x, y, source}` | +| bindscale | 缩放过程中触发的事件，`event.detail = {x, y, scale}` | +| htouchmove | 初次手指触摸后移动为横向的移动时触发 | +| vtouchmove | 初次手指触摸后移动为纵向的移动时触发 | + + +注意事项 + +1. simultaneous-handlers 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture) +2. wait-for 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail) + +#### root-portal +使整个子树从页面中脱离出来，类似于在 CSS 中使用 fixed position 的效果。主要用于制作弹窗、弹出层等。 +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| enable | boolean | true | 是否从页面中脱离出来 + +注意事项 + +1. style 样式不支持中使用百分比计算、css variable + +#### cover-view +视图容器。 +功能同 view 组件 + +#### cover-image +视图容器。 +功能同 image 组件 + +#### icon +图标组件 + + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| type | String | | icon 的类型，有效值：success、success_no_circle、info、warn、waiting、cancel、download、search、clear | +| size | String \| Number | 23 | icon 的大小 | +| color | String | | icon 的颜色，同 css 的 color | + + +#### text +文本。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| user-select | boolean | `false` | 文本是否可选。 | +| disable-default-style | boolean | `false` | 会内置默认样式，比如fontSize为16。设置`true`可以禁止默认的内置样式。 | +| enable-offset | Number | false | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| + + +事件 + + +| 事件名 | 说明 | +| ----------------| --------------------------------------------------- | +| bindtap | 点击的时候触发 | + +注意事项 + +1. 未包裹 text 标签的文本，会自动包裹 text 标签。 +2. text 组件开启 enable-offset 后，offsetLeft、offsetWidth 获取时机仅为组件首次渲染阶段 + + +#### button +按钮。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | --------------------------------------------------------- | +| size | String | `default` | 按钮的大小，`default`：默认大小，`mini`：小尺寸 | +| type | String | `default` | 按钮的样式类型，`primary`：绿色，`default`：白色，`warn`：红色 | +| plain | Boolean | `false` | 按钮是否镂空，背景色透明 | +| disabled | Boolean | `false` | 是否禁用 | +| loading | Boolean | `false` | 名称前是否带 loading 图标 | +| open-type | String | | 微信开放能力，当前仅支持 `share` | +| hover-class | String | | 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果 | +| hover-start-time | Number | `20` | 按住后多久出现点击态，单位毫秒 | +| hover-stay-time | Number | `70` | 手指松开后点击态保留时间，单位毫秒 | +| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| + + +#### label +用来改进表单组件的可用性 + + +注意事项 + +1. 当前不支持使用 for 属性找到对应 id，仅支持将控件放在该标签内，目前可以绑定的空间有：checkbox、radio、switch。 + +#### checkbox +多选项目 + + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| value | String | | checkbox 标识，选中时触发 checkbox-group 的 change 事件，并携带 checkbox 的 value | +| disabled | Boolean | false | 是否禁用 | +| checked | Boolean | false | 当前是否选中，可用来设置默认选中 | +| color | String | #09BB07 | checkbox的颜色，同css的color | + + +#### checkbox-group +多项选择器，内部由多个checkbox组成。 + + +事件 + +| 事件名 | 说明 | +| ----------------| ------------------ | +| bindchange | checkbox-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 checkbox 的 value 的数组 ] } `| + + +#### radio +单选项目 + + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| value | String | | radio 标识，当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value | +| disabled | Boolean | false | 是否禁用 | +| checked | Boolean | false | 当前是否选中，可用来设置默认选中 | +| color | String | #09BB07 | checkbox 的颜色，同 css 的 color | + + +#### radio-group +单项选择器，内部由多个 radio 组成 + + +事件 + +| 事件名 | 说明 | +| ----------------| ------------------ | +| bindchange | radio-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 radio 的 value 的数组 ] }` | + + +#### form +表单。 + +当点击 form 表单中 form-type 为 submit 的 button 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。 + +事件 + +| 事件名 | 说明 | +| ---------- | --------------------------------------------------- | +| bindsubmit | 携带 form 中的数据触发 submit 事件，`event.detail = {value : {'name': 'value'} }` | +| bindreset | 表单重置时会触发 reset 事件 | + + +#### input +输入框。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| value | String | | 输入框的初始内容 | +| type | String | `text` | input 的类型，可选值为 `text`、`number`、`idcard`、`digit`，不支持 `safe-password`、`nickname` | +| password | Boolean | `false` | 是否是密码类型 | +| placeholder | String | | 输入框为空时占位符 | +| placeholder-class | String | | 指定 placeholder 的样式类，仅支持 color 属性 | +| placeholder-style | String | | 指定 placeholder 的样式，仅支持 color 属性 | +| disabled | Boolean | `false` | 是否禁用 | +| maxlength | Number | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 | +| auto-focus | Boolean | `false` | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘 | +| focus | Boolean | `false` | 获取焦点 | +| confirm-type | String | `done` | 设置键盘右下角按钮的文字，仅在 type='text' 时生效，可选值为 `send`、`search`、`next`、`go`、`done` | +| confirm-hold | Boolean | `false` | 点击键盘右下角按钮时是否保持键盘不收起 | +| cursor | Number | | 指定 focus 时的光标位置 | +| cursor-color | String | | 光标颜色 | +| selection-start | Number | `-1` | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用 | +| selection-end | Number | `-1` | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用 | +| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| + +事件 + +| 事件名 | 说明 | +| ---------------------| ---------------------------------------------------------------------------------- | +| bindinput | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode` | +| bindfocus | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height` | +| bindblur | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` | +| bindconfirm | 点击完成按钮时触发，`event.detail = { value }` | +| bind:selectionchange | 选区改变事件, `event.detail = { selectionStart, selectionEnd }` | + +方法 + +可通过 `ref` 方式调用以下组件实例方法 + +| 方法名 | 说明 | +| ---------------------| ----------------------------------- | +| focus | 使输入框得到焦点 | +| blur | 使输入框失去焦点 | +| clear | 清空输入框的内容 | +| isFocused | 返回值表明当前输入框是否获得了焦点 | + + +#### textarea +多行输入框。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| value | String | | 输入框内容 | +| type | String | `text` | input 的类型，不支持 `safe-password`、`nickname` | +| placeholder | String | | 输入框为空时占位符 | +| placeholder-class | String | | 指定 placeholder 的样式类，仅支持 color 属性 | +| placeholder-style | String | | 指定 placeholder 的样式，仅支持 color 属性 | +| disabled | Boolean | `false` | 是否禁用 | +| maxlength | Number | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 | +| auto-focus | Boolean | `false` | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘 | +| focus | Boolean | `false` | 获取焦点 | +| auto-height | Boolean | `false` | 是否自动增高，设置 auto-height 时，style.height不生效 | +| confirm-type | String | `done` | 设置键盘右下角按钮的文字，可选值为 `send`、`search`、`next`、`go`、`done`，不支持 `return` | +| confirm-hold | Boolean | `false` | 点击键盘右下角按钮时是否保持键盘不收起 | +| cursor | Number | | 指定 focus 时的光标位置 | +| cursor-color | String | | 光标颜色 | +| selection-start | Number | `-1` | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用 | +| selection-end | Number | `-1` | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用 | +| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| + +事件 + +| 事件名 | 说明 | +| ---------------------| ---------------------------------------------------------------------------------- | +| bindinput | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode` | +| bindfocus | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height` | +| bindblur | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` | +| bindconfirm | 点击完成按钮时触发，`event.detail = { value }` | +| bindlinechange | 输入框行数变化时调用，`event.detail = { height: 0, lineCount: 0 }`，不支持 `heightRpx` | +| bind:selectionchange | 选区改变事件, `event.detail = {selectionStart, selectionEnd}` | + +方法 + +可通过 `ref` 方式调用以下组件实例方法 + +| 方法名 | 说明 | +| ---------------------| ----------------------------------- | +| focus | 使输入框得到焦点 | +| blur | 使输入框失去焦点 | +| clear | 清空输入框的内容 | +| isFocused | 返回值表明当前输入框是否获得了焦点 | + +#### picker-view + +嵌入页面的滚动选择器。其中只可放置 [*picker-view-column*](#picker-view-column) 组件，其它节点不会显示 + +- 属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------------------| ------------------ | ------------------------------------| +| value | Array\ | `[]` | 数组中的数字依次表示 *picker-view* 内的 [*picker-view-column*](#picker-view-column) 选择的第几项（下标从 0 开始），数字大于 [*picker-view-column*](#picker-view-column) 可选项长度时，选择最后一项。| +| indicator-style | String | | 设置选择器中间选中框的样式 | +| indicator-class | String | | 设置选择器中间选中框的类名 | +| mask-style | String | | 设置蒙层的样式 | +| mask-class | String | | 设置蒙层的类名 | + +- 事件 + +| 事件名 | 说明 | +| ----------------| ------------------ | +| bindchange | 滚动选择时触发 change 事件，`event.detail = {value}`，其中 `value` 为数组，表示 *picker-view* 内的 [*picker-view-column*](#picker-view-column) 当前选择的是第几项（下标从 0 开始） | + +- 触感反馈回调方法 + +通过在全局注册 `mpx.config.rnConfig.pickerVibrate` 方法，在每次滚动选择时会调用该方法。 + +| 注册触感方法名 | 类型 | 说明 | +| ----------------------| --------------| ------------------- | +| pickerVibrate | Function | 注册自定义触感反馈方法。调用时机：在每次滚动选择时会调用该方法。可以在方法内自定义实现类似 iOS 端原生表盘的振动触感。 | + +#### picker-view-column + +滚动选择器子项。仅可放置于 [*picker-view*](#picker-view) 中，其孩子节点的高度会自动设置成与 [*picker-view*](#picker-view) 的选中框的高度一致 + +#### picker + +从底部弹起的滚动选择器。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| -----------------------| ------------| ------------------ | -----------------------------| +| mode | string | `selector` | 选择器类型，合法值如下表所示 | +| disabled | boolean | `false` | 是否禁用 | + +- `mode` 合法值 + + | 合法值 | 说明 | + | --------------| ------------| + | selector | 普通选择器 | + | multiSelector | 多列选择器 | + | time | 时间选择器 | + | date | 日期选择器 | + | region | 省市区选择器 | + +公共事件 + +| 事件名 | 说明 | +| ----------------| ----------------------------------------------------| +| bindcancel | 取消选择时触发 | +| bindchange | value 改变时触发 change 事件，`event.detail = {value}` | + +##### 普通选择器：mode = selector + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| -----------------------| ------------------------| ------------- | -----------------------------| +| range | array[object]/array | `[]` | mode 为 selector 或 multiSelector 时，range 有效 | +| range-key | string | `false` | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 | +| value | number | 0 | 表示选择了 range 中的第几个（下标从 0 开始）| + +##### 多列选择器：mode = multiSelector +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| -----------------------| ------------------------| ------------- | -----------------------------| +| range | array[object]/array | `[]` | mode 为 selector 或 multiSelector 时，range 有效 | +| range-key | string | `false` | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 | +| value | array | `[]` | 表示选择了 range 中的第几个（下标从 0 开始）| +| bindcolumnchange | | | 列改变时触发| + +##### 多列选择器：时间选择器：mode = time +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| -----------------------| ------------------------| ------------- | -----------------------------| +| value | string | `[]` | 表示选中的时间，格式为"hh:mm" | +| start | string | `false` | 表示有效时间范围的开始，字符串格式为"hh:mm" | +| end | string | `[]` | 表示有效时间范围的结束，字符串格式为"hh:mm"| + +##### 多列选择器：时间选择器：mode = date +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| -----------------------| ------------------------| ------------- | ------------------------------------------| +| value | string | `当天` | 表示选中的日期，格式为"YYYY-MM-DD" | +| start | string | `false` | 表示有效日期范围的开始，字符串格式为"YYYY-MM-DD" | +| end | string | `[]` | 表示有效日期范围的结束，字符串格式为"YYYY-MM-DD" | +| fields | string | `day` | 有效值 year,month,day，表示选择器的粒度 | + +##### fields 有效值： +| 属性名 | 说明 | +| -----------------------| ------------------------ | +| year | 选择器粒度为年 | +| month | 选择器粒度为月份 | +| day | 选择器粒度为天 | + +##### 省市区选择器：mode = region +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| -----------------------| ------------------------| ------------- | ------------------------------------------| +| value | array | `[]` | 表示选中的省市区，默认选中每一列的第一个值 | +| custom-item | string | | 可为每一列的顶部添加一个自定义的项 | +| level | string | `region` | 选择器层级 | + +##### level 有效值： +| 属性名 | 说明 | +| -----------------------| ------------------------ | +| province | 选省级选择器 | +| city | 市级选择器 | +| region | 区级选择器 | + +#### image +图片。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| src | String | `false` | 图片资源地址及 base64 格式数据 | +| mode | String | `scaleToFill` | 图片裁剪、缩放的模式，可选值为 `scaleToFill`、`aspectFit`、`aspectFill`、`widthFix`、`heightFix`、`top`、`bottom`、`center`、`left`、`right`、`top left`、`top right`、`bottom left`、`bottom right` | +| enable-offset | Boolean | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| +| enable-fast-image | Boolean | `false` | 开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 | + +事件 + +| 事件名 | 说明 | +| ----------------| --------------------------------------------------- | +| binderror | 当错误发生时触发，`event.detail = { errMsg }` | +| bindload | 当图片载入完毕时触发，`event.detail = { height, width }` | + +注意事项 + +1. image 组件默认宽度320px、高度240px +2. image 组件进行缩放时，计算出来的宽高可能带有小数，在不同webview内核下渲染可能会被抹去小数部分 + + +#### switch +开关选择器。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| checked | boolean | | 是否选中 | +| disabled | boolean | false | 是否禁用 | +| type | string | `switch` | 样式，有效值：switch, checkbox | +| color | string | `#04BE02` | switch 的颜色，同 css 的 color| + + +事件 + +| 事件名 | 说明 | +| ----------------| --------------------------------------------------- | +| bindchange | 点击的时候触发 | + +#### navigator +页面链接。 + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| hover-class | string | false | 指定按下去的样式类。 | +| hover-start-time | number | 50 | 按住后多久出现点击态，单位毫秒| +| hover-stay-time | number | 400 | 手指松开后点击态保留时间，单位毫秒 | +| open-type | String | `navigate` | 可支持`navigateBack`、`redirect`、`switchTab`、`reLaunch`、`navigateTo`| +| url | String | `` | 当前Navite内的跳转链接 | + + +事件 + +| 事件名 | 说明 | +| ----------------| --------------------------------------------------- | +| bindtap | 点击的时候触发 | + + + +#### rich-text +富文本。 + + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| nodes | array/string | [] | 节点列表/HTML String | + + + + +#### canvas +画布。 + +事件 + +| 属性名 | 类型 | 说明 | +| ----------------------- | ------- | ---------------------------------------------------------- | +| bindtouchstart | eventhandle | 手指触摸动作开始 | +| bindtouchmove | eventhandle | 手指触摸后移动 | +| bindtouchend | eventhandle | 手指触摸动作结束 | +| bindtouchcancel | eventhandle | 手指触摸动作被打断 | +| bindlongpress | eventhandle | 手指长按 350ms 之后触发 | +| binderror | eventhandle | 当发生错误时触发 error 事件， `detail = {errMsg}` | + +API + + 方法名 | 说明 | +| ----------------------- | ------- | +| createImage | 创建一个图片对象。 仅支持在 2D Canvas 中使用 | +| createImageData | 创建一个 ImageData 对象。仅支持在 2D Canvas 中使用 | +| getContext | 该方法返回 Canvas 的绘图上下文。仅支持在 2D Canvas 中使用 | +| toDataURL | 返回一个包含图片展示的 data URI | + +注意事项 + +1. canvas 组件目前仅支持 2D 类型，不支持 webgl +2. 通过 Canvas.getContext('2d') 接口可以获取 CanvasRenderingContext2D 对象，具体接口可以参考 (HTML Canvas 2D Context)[https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D] 定义的属性、方法 +3. canvas 的实现主要借助于 PostMessage 方式与 webview 容器通信进行绘制，所以对于严格依赖方法执行时机的场景，如调用 drawImage 绘图，再通过 getImageData 获取图片数据的场景，调用时需要使用 await 等方式来保证方法的执行时机 +4. 通过 Canvas.createImage 画图，图片的链接不能有特殊字符，安卓手机可能会 load 失败 + +#### web-view +承载网页的容器。会自动铺满整个RN页面 + + +属性 + +| 属性名 | 类型 | 默认值 | 说明 | +| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | +| src | String | | webview 指向网页的链接，如果需要对跳转的URL设定白名单可跳转，需要在业务跳转之前出来该逻辑 +| bindmessage | EventHandler | | 网页向RN通过 postMessage 传递数据 +| bindload | EventHandler | | 网页加载成功时候触发此事件 +| binderror | EventHandler | | 网页加载失败的时候触发此事件 + + +注意事项 + +1. web-view网页中可使用@mpxjs/webview-bridge@2.9.68版本提供的接口返回RN页面或与RN页面通信，具体使用细节可以参见[Webview API](#WebviewAPI) + +#### 自定义组件 +创建自定义组件在 RN 环境下部分实例方法、属性存在兼容性问题不支持， +文档此部分会详细列出各方法、属性的支持度。 + +##### **组件属性** + +| 属性 | RN | 描述 | +|------------|---|------------------------------------------------------------------------------| +| properties | ✓ | 用于声明组件接收的外部属性，详情可[查看](/guide/basic/component.html#properties) | +| data | ✓ | 组件的内部数据，和 `properties` 一同用于组件的模板渲染，详情可[查看](/guide/basic/component.html#data) | +| observers | ✓ | 组件数据字段监听器，详情可[查看](/guide/basic/component.html#observers) | +| methods | ✓ | 组件方法定义，详情可[查看](/guide/basic/component.html#methods) | +| behaviors | ✗ | 输出 RN 不支持 | +| created | ✓ | 组件生命周期函数-详情可[查看](/guide/basic/component.html#created) | +| attached | ✓ | 组件生命周期函数-详情可[查看](/guide/basic/component.html#attached) | +| ready | ✓ | 组件生命周期函数-详情可[查看](/guide/basic/component.html#ready) | +| detached | ✓ | 组件生命周期函数-详情可[查看](/guide/basic/component.html#detached) | +| externalClasses | ✓ | 输出 RN 需要配置[构建配置](/api/compile.html#externalclasses) | +| options | ✗ | 输出 RN 不支持，一些选项，诸如 multipleSlots、virtualHost、pureDataPattern，这些功能输出 RN 不支持 | +| lifetimes | ✓ | 组件生命周期声明对象-详情可[查看](/guide/basic/component.html#lifetimes) | +| pageLifetimes | ✓ | 组件所在页面的生命周期声明对象-详情可[查看](/guide/basic/component.html#pagelifetimes) | + +##### **组件实例属性和方法** + +生成的组件实例可以在组件的方法、生命周期函数中通过 this 访问。组件包含一些通用属性和方法。 + +未在本文档中列出的实例属性和方法则在 RN 中不支持。 + +| 属性名 | 类型 | RN 是否支持 | 描述 | +|--------|----------|------|--------------------------| +| is | String | ✗ | 输出 RN 暂不支持，未来支持, 组件的文件路径 | +| id | String | ✓ | 节点id | +| dataset| String | ✓ | 节点dataset | + + +| 方法名 | RN是否支持 | 描述 | +|---------------------|--|--------------------------| +| setData | ✓ | 设置data并执行视图层渲染 | +| triggerEvent | ✓ | 触发事件 | +| createSelectorQuery| ✗ | 输出 RN 暂不支持，未来支持，建议使用 ref | +| selectComponent | ✗ | 输出 RN 暂不支持，未来支持，建议使用 ref | +| selectAllComponents| ✗ | 输出 RN 暂不支持，未来支持，建议使用 ref | +| $set | ✓ | 向响应式对象中添加一个 property，并确保这个新 property 同样是响应式的，且触发视图更新 | +| $watch | ✓ | 观察 Mpx 实例上的一个表达式或者一个函数计算结果的变化 | +| $delete | ✓ | 删除对象属性，如果该对象是响应式的，那么该方法可以触发观察器更新（视图更新 | watch回调） | +| $refs | ✓ | 一个对象，持有注册过 ref的所有 DOM 元素和组件实例，调用响应的组件方法或者获取视图节点信息。 | +| $forceUpdate | ✓ | 用于强制刷新视图，不常用，通常建议使用响应式数据驱动视图更新 | +| $nextTick | ✓ | 在下次 DOM 更新循环结束之后执行延迟回调函数，用于等待 Mpx 完成状态更新和 DOM 更新后再执行某些操作 | +| $i18n | ✗ | 输出 RN 暂不支持，国际化功能访问器，用于获取多语言字符串资源 | +| $rawOptions | ✓ | 访问组件原始选项对象 | + + +### 样式规则 +#### position +设置元素的定位样式 +##### 值类型 +enum: absolute, relative， 默认relative。 +> 备注：RN 不支持 fixed 定位 +##### 代码示例 +``` css +position: absolute; +top: 10px +``` +#### top|right|left|bottom +设置元素的不同方向的偏移量 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +position: relative; +top: 10%; +``` +#### z-index +控制元素的堆叠覆盖顺序。 +##### 值类型 +number，纯数值，无单位 +##### 代码示例 +``` css +position: absolute; +top: 0; +z-index: 1; +``` +#### display +设置元素的布局方式。 +##### 值类型 +enum: flex/none +> 备注 +> - RN display 仅支持 flex 布局，其他在 Web/小程序常用的布局如 block、inline-block、inline、inline-flex、grid、table 等 RN 不支持，为了保证代码有更好的跨端适配，最好使用 flex 布局。 +> - 和 Web/小程序一致，RN 下 Text 节点默认为行内 inline 布局 +##### 代码示例 +``` css +/* 默认 */ +display:flex +/* 隐藏 */ +display:none +``` +#### justify-content +用来设置元素列之间的间隔大小，默认值 flex-start +##### 值类型 +enum: flex-start/flex-end/center/space-between/space-around/space-evenly +##### 代码示例 +``` css +justify-content: center; /* 居中排列 */ +justify-content: flex-start; /* 从行首起始位置开始排列 */ +justify-content: flex-end; /* 从行尾位置开始排列 */ +``` +#### align-content +设置单根轴线上的子元素的对齐方式。 +##### 值类型 +enum: flex-start/flex-end/center/stretch/space-between/space-around/space-evenly +##### 代码示例 +``` css +/** 支持 **/ +align-content: flex-start; +align-content: flex-end; +align-content: center; +align-content: stretch; +align-content: space-between; +align-content: space-around; +align-content: space-evenly; + +/** 不支持 **/ +align-content: safe center; +align-content: unsafe center; +``` +#### align-items +设置单根轴线上的子元素的对齐方式。默认会是交叉轴上的。 +##### 值类型 +enum: flex-start/flex-end/center/stretch/baseline +##### 代码示例 +``` css +/** 支持 **/ +align-items: flex-start; +align-items: flex-end; +align-items: center; +align-items: stretch; +align-items: baseline; + +/** 不支持 **/ +align-items: first baseline; +align-items: last baseline; +``` +#### align-self +设置单个子元素在单根轴线上的对齐方式 +##### 值类型 +enum: auto/flex-start/flex-end/center/stretch/baseline +##### 代码示例 +``` css +/** 支持 **/ +align-self: auto; +align-self: flex-start; +align-self: flex-end; +align-self: center; +align-self: stretch; +align-self: baseline; + +/** 不支持 **/ +align-self: first baseline; +align-self: last baseline; +``` +#### flex-grow +设置 flex 元素的增长系数，默认值为0，不支持放大 +##### 值类型 +number，纯数值无单位，>= 0 +##### 代码示例 +```css +flex-grow: 3; +``` +#### flex-shrink +设置 flex 元素的收缩规则。 + +flex 元素仅在默认宽度之和大于容器的时候才会发生收缩，其收缩的大小是依据 flex-shrink 的值，flex-shrink 默认为0，不支持收缩 +##### 值类型 +number，纯数值无单位，>= 0 +##### 代码示例 +```css +flex-shrink: 2; +``` +#### flex-basis +设置指定了 flex 元素在主轴方向上的初始大小，默认值 auto。 +##### 值类型 +enum: auto + +number，单位参考[数值类型单位说明](#数值类型单位说明) +> 备注 +> +> 当一个元素同时被设置了 flex-basis (除值为 auto 外) 和 width (或者在 flex-direction: column 情况下设置了height) , flex-basis 具有更高的优先级。 +##### 代码示例 +``` css +flex-basis: 10px; +flex-basis: 10rpx; +flex-basis: 20%; +flex-basis: auto; +flex-basis: 0; +``` +#### flex +flex-grow flex-shrink flex-basis 的简写，和所有简写属性一致，仅支持定义在类上 +##### 简写规则 +可以使用一个，两个或三个值来指定 flex 属性。 + +**单值语法**，值必须是以下之一： +- 一个 `` 的有效值：此时简写会扩展为 `flex: 1 0`。 +- 一个 `` 的有效值：此时简写会扩展为 `flex: 1 1 `。 +- 关键字 none/initial 。 + +**双值语法**，第一个值必须是一个 flex-grow 的有效值，第二个值必须是以下之一： +- 一个 flex-shrink 的有效值：此时简写会扩展为 flex: ` 0`。 +- 一个 flex-basis 的有效值：此时简写会扩展为 flex: ` 1 `。 + +**三值语法**，值必须按照以下顺序指定： +- 一个 flex-grow 的有效值。 +- 一个 flex-shrink 的有效值。 +- 一个 flex-basis 的有效值。 + +**几种情况**： +- initial 相当于将属性设置为 flex: 0 1 auto +- auto 相当于将属性设置为 flex: 1 1 auto +- none 相当于将属性设置为 flex: 0 0 auto +- flex-grow/flex-shrink 负值无效，省略时默认值为 1；flex-basis 若值为0，则必须加上单位，省略时默认值为 0 +##### 代码示例 +``` css +/** 单值，flex-grow 有效值 **/ +flex: 1; +/* 等同于 */ +flex: 0 1 1; + +/** 单值，flex-basis 有效值 **/ +flex 30px +/* 等同于 */ +flex: 1 1 30px + +/* 双值：flex-grow + flex-basis 有效值 */ +flex: 1 30px +/* 等同于 */ +flex: 1 1 30px + +/* 双值：flex-grow + flex-shrink 有效值 */ +flex: 2 2 +/* 等同于 */ +flex: 2 2 0 +``` +#### flex-direction +设置主轴的方向。 +##### 值类型 +enum: row/row-reverse/column/column-reverse +##### 代码示例 +``` css +flex-direction: row; +flex-direction: row-reverse; +flex-direction: column; +flex-direction: column-reverse; +``` +#### flex-wrap +设置元素是否换行。当值为wrap时，alignItems：center不生效。 +##### 值类型 +enum: wrap, nowrap, wrap-reverse +##### 代码示例 +``` css +flex-wrap: wrap; +flex-wrap: nowrap; +flex-wrap: wrap-reverse; +``` +#### flex-flow +flex-direction flex-wrap 的简写形式，值按固定顺序分别赋值给 flex-direction flex-wrap，若值个数不够则后置位属性不设置；和所有简写属性一致，仅支持定义在类上 +##### 代码示例 +```css +/* flex-direction flex-wrap 缺省则不设置 */ +flex-flow: row; +/* flex-direction | flex-wrap */ +flex-flow: row nowrap; +``` +#### direction +用来设置元素列之间的间隔大小 +##### 值类型 +enum: inherit/ltr/rtl +##### 代码示例 +``` css +/* 支持 */ +direction: ltr; +direction: rtl; +direction: inherit; +``` +#### column-gap +用来设置元素列之间的间隔大小 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +column-gap: 3px; +column-gap: 25rpx; +column-gap: 3%; +``` +#### row-gap +用来设置元素行之间的间隙大小 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +row-gap: 20px; +row-gap: 10%; +``` +#### gap +用于设置行、列的间隙，该属性用来表示 row-gap 和可选的 column-gap 的值。如果缺失 column-gap，则其会被设置成跟 row-gap 一样的值。 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 一个值 */ +gap: 16%; +/* 两个值 */ +gap: 20px 10px; +gap: 21px 82%; +/* calc() 值 */ +gap: calc(10% + 20px); +gap: calc(20px + 10%) calc(10% - 5px); +``` +#### height +设置元素高度 +##### 值类型 +enum: auto + +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +height: 120px; +height: 130rpx; +height: auto; +``` +#### max-height +设置元素最大高度 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +max-height: 120px; +max-height: 75%; +``` +#### min-height +设置元素最小高度 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +min-height: 120px; +min-height: 130rpx; +``` +#### width +设置元素宽度 +##### 值类型 +enum: auto + +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +width: auto; +width: 10%; +``` +#### max-width +设置元素最大宽度 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +max-width: 75%; +max-width: 75px; +``` +#### min-width +设置元素最小宽度 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* 支持 */ +min-width: 10%; +min-width: 120px; +``` +#### margin-top|margin-bottom|margin-right|margin-left +上下左右外边距 +##### 值类型 +enum: auto + +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +margin-top: 2px; +margin-top: 2rpx; +margin-top: 10%; +``` +#### margin +设置外边距 + +RN margin 属性仅支持单值的，设置多值时是由框架按简写逻辑在编译时处理的，和所有简写属性一致，多值的简写形式仅在class类上支持。 +##### 值类型 +enum: auto + +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* all */ +margin: 2px; + +/* top and bottom | left and right */ +margin: 5% auto; + +/* top | left and right | bottom */ +margin: 1rpx auto 2rpx; + +/* top | right | bottom | left */ +margin: 1rpx 2rpx 2rpx ; +``` +#### padding-top|padding-bottom|padding-left|padding-right +上下左右内边距 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/** padding-top **/ +padding-top: 2px; +padding-top: 2rpx; +padding-top: 10%; +``` +#### padding +设置内边距 + +RN padding 属性仅支持单值的，设置多值时是由框架按简写逻辑在编译时处理的，和所有简写属性一致，多值的简写形式仅在class类上支持。 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* all */ +padding: 2px; + +/* top and bottom | left and right */ +padding: 5% 10%; + +/* top | left and right | bottom */ +padding: 1rpx 0 2rpx; + +/* top | right | bottom | left */ +padding: 1rpx 2rpx 2rpx ; +``` +#### border-top-width|border-bottom-width|border-left-width|border-right-width +设置上下左右各边框的宽度 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +border-top-width: 2px; +``` +#### border-width +设置边框的宽度 + +RN border-width 属性仅支持单值的，设置多值时是由框架按简写逻辑在编译时处理的，和所有简写属性一致，多值的简写形式仅在class类上支持。 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* all border */ +border-width: 2px; + +/* 顶部和底部 | 左侧和右侧 */ +border-width: 2px 1.5em; + +/* 顶部 | 左侧和右侧 | 底部 */ +border-width: 1px 2em 1.5cm; + +/* 顶部 | 右侧 | 底部 | 左侧 */ +border-width: 1px 2em 0 4rem; +``` +#### border-top-color|border-bottom-color|border-left-color|border-right-color +设置上下左右各边框的颜色 +##### 值类型 +color: 参考[Color](#色值-color-类型支持的值格式说明) +##### 代码示例 +``` css +border-top-color: red; +``` +#### border-color +设置边框的颜色 + +RN border-color 属性仅支持单值的，设置多值时是由框架按简写逻辑在编译时处理的，和所有简写属性一致，多值的简写形式仅在class类上支持。 +##### 值类型 +color: 参考[Color](#色值-color-类型支持的值格式说明) +##### 代码示例 +``` css +/* border-color: color; 单值语法 */ +border-color: red; + +/* border-color: vertical horizontal; 双值语法*/ +border-color: red #f015ca; + +/* border-color: top horizontal bottom; 三值语法 */ +border-color: red yellow green; + +/* border-color: top right bottom left; 四值语法 */ +border-color: red yellow green blue; +``` +#### border-style +设置边框的样式 +##### 值类型 +enum: solid|dotted|dashed +> 注意事项：RN 不支持分开设置各边框线的形态，所以 RN 上 border-style 不支持简写形式 +##### 代码示例 +``` css +/** 支持 **/ +/* all border */ +border-color: solid; +border-color: dotted; +border-color: dashed; + +/** 不支持 **/ +border-style: double; +border-style: groove; +border-style: ridge; +border-style: dotted solid; +border-style: hidden double dashed; +border-style: none solid dotted dashed; + +/** 不支持 **/ +/* horizontal | vertical */ +border-style: dotted solid; +/* top | horizontal | bottom */ +border-style: hidden double dashed; +/* top | right | bottom | left */ +border-style: none solid dotted dashed; +``` +#### border +border-width border-style border-color 的简写模式, 值按固定顺序分别赋值给 border-width border-style border-color，若值个数不够则后置位属性不设置；和所有简写属性一致，仅支持定义在类上 +##### 代码示例 +```css +/* border-width | border-style | border-color */ +border: 1px solid red; +/* border-width */ +border: 1px; +/* border-width | border-style */ +border: 1px solid; +/* border-width | border-style | border-color */ +border: 1px double pink; +``` +#### border-top|border-right|border-bottom|border-left +border-(top|right|bottom|left)-width border-(top|right|bottom|left)-style border-(top|right|bottom|left)-color 的简写模式, 值按固定顺序分别赋值给 border-*-width border-*-style border-*-color，若值个数不够则后置位属性不设置；和所有简写属性一致，仅支持定义在类上 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +```css +border-top: 1px; +border-top: 2px dotted; +border-top: medium dashed green; +``` +#### border-bottom-left-radius|border-bottom-right-radius|border-top-left-radius|border-top-right-radius +上下左圆角大小 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +border-bottom-left-radius: 2px; +``` +#### border-radius +圆角大小 + +RN border-radius 属性仅支持单值的，设置多值时是由框架按简写逻辑在编译时处理的，和所有简写属性一致，多值的简写形式仅在class类上支持。 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +##### 代码示例 +``` css +/* all */ +border-radius: 2px; +/* top-left | top-right | bottom-right | bottom-left */ +border-radius: 10px 10px 10px 0; +``` +#### background-color +设置背景色 +##### 值类型 +color: 参考[Color](#色值-color-类型支持的值格式说明) +##### 代码示例 +``` css +background-color: red; +``` +#### background-image +设置背景图 + +##### 值类型 +string: url / linear-gradient +> 注意事项 +> - 背景图和背景色仅支持 view 节点 +> - 开发者可通过 enable-background 属性来控制是否开启背景图片和渐变色的支持 +> - 渐变不支持turn、px单位，只支持渐变距离百分比。 + +##### 代码示例 +``` css +/* 支持 */ +background-image: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg"); +background-image linear-gradient(270deg, rgba(255,255,255,0.40), rgba(255,255,255,0.00)) +background-image: linear-gradient(to top, blue, red) +background-image: linear-gradient(to right bottom, blue, red) +background-image: linear-gradient(45deg, blue, red) +background-image: linear-gradient(45deg, blue 0%, orange 40%, red) +background-image: linear-gradient(to left top, blue, red) + + + +/* 不支持 */ +background-image: linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)); +background-image: linear-gradient(.25turn, red, blue) // turn单位不支持 +background-image: linear-gradient(45deg, red 100px, blue) //px单位不支持 +background-image: linear-gradient(red 0%, orange 10% 30%, yellow 50% 70%, green 90% 100%); + +``` +#### background-size +设置背景图大小 +##### 值类型 +enum: contain/cover/auto + +number，单位参考[数值类型单位说明](#数值类型单位说明) +> 注意事项 +> - 仅支持 view 节点 +> - 支持一个值，这个值指定图片的宽度，图片的高度隐式的为 auto；支持两个值，第一个值指定图片的宽度，第二个值指定图片的高度；不支持逗号分隔的多个值 +##### 代码示例 +``` css +/* 支持 */ +background-size: 50%; +background-size: 50% 25%; +background-size: contain; +background-size: cover; +background-size: auto; +background-size: 20px auto; + +/* 不支持 */ +background-size: 50%, 25%, 25%; +``` +#### background-repeat +设置是否重复背景图 +##### 值类型 +enum: no-repeat +> 备注：仅支持 view 节点 +##### 代码示例 +``` css +background-repeat: no-repeat; + +/* 不支持 */ +background-repeat: repeat; +``` + + +#### background-postion +设置背景图大小 +##### 值类型 +enum: center/left/right/top/bottom + +number，单位参考[数值类型单位说明](#数值类型单位说明) + +> 注意事项 +> - 仅支持 view 节点 +##### 代码示例 +``` css +/* 支持 */ +background-position: center; +background-position: 10%; +background-position: 10px; +background-position: 10px 20px; +background-position: 10px center; +background-position: right 10px center; +background-position: right 10px bottom 10px; + +/* 不支持 */ +background-position: 1cm 2cm; +background-position: 10ch 8em; +background-position: right 3em bottom 10px; + +``` + + +#### background +背景的简写属性，只能在view上使用 +##### 值类型 +仅支持 background-image|background-color|background-size|background-repeat|background-position，具体每个属性的支持情况详见各属性的介绍文档 +> 备注：仅支持 view 节点 +##### 代码示例 +```css +/* 支持 */ +background: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg") pink no-repeat; +background: #000; +background: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg") pink; +background: linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)); +``` +#### box-shadow +设置阴影颜色、阴影偏移量、阴影模糊半径，因 RN 不支持 box-shadow 属性，实际是由 mpx 按 RN 支持的 shadowOffset: \{ width?: number, height?: number \}; shadowRadius: number; shadowColor: number; 属性和顺序转换成对应的属性。 +##### 值类型 +offset-x|offset-y|blur-radius 值为 number，单位参考[数值类型单位说明](#数值类型单位说明)，shadow-color 为 color 类型，参考[Color](#色值-color-类型支持的值格式说明) +##### 简写规则 +- 按 offset-x|offset-y|blur-radius|spread-radius|color 顺序赋值 +- 赋值过程中，如遇到不支持的属性会忽略该属性；若属性值校验不合法，则忽略该值，继续校验下一个值是否合法，合法则赋值，不合法则继续校验下一个值 +- android 下仅支持 shadowColor，故框架在 android 模式下不会添加 shadowOffset/shadowRadius +- 在设置 box-shadow 有效值的情况下，ios 下会新增 shadowOpacity: 1 来展示阴影 +##### 代码示例 +```css +/* offset-x | offset-y | blur-radius | color */ +box-shadow: 0 1px 3px rgba(139,0,0,0.32); +/* x 偏移量 | y 偏移量 | 阴影模糊半径 | 阴影扩散半径 | 阴影颜色 */ +/* 因第四个值 spread-radius 阴影扩散半径 不支持，故 1px 在框架处理时会被忽略 */ +box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2); +``` +> 注意事项 +> - android 仅支持 shadowColor，ios 也支持 shadowOffset/shadowRadius/shadowColor/shadowOpacity, 不支持设置 spread-radius 阴影扩散半径 +> - 在节点有设置 overflow:hidden; 同时设置 box-shadow，Web/小程序能正常展示阴影，RN 不能正常展示阴影，需单独新增一级节点来添加阴影 +> - RN 0.76 新架构支持 [boxShadow 属性](https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture#box-shadow-and-filter-style-props) +#### backface-visibility +指定当 image 背面朝向观察者时是否可见，仅 image 支持 +##### 值类型 +enum: visible/hidden +> 备注：仅支持 view 节点 +##### 代码示例 +```css +backface-visibility: visible; +``` +#### object-fit +确定当元素 image 与原始图像尺寸不匹配时如何调整图像大小 +##### 值类型 +enum: cover/contain/fill/scale-down +> 备注：仅支持 view 节点 +##### 代码示例 +```css +object-fit: contain; +``` +#### transform +设置旋转、缩放、倾斜或平移 +##### 值类型 +array of objects (only rn): `[{matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}]` + +string +##### 代码示例 +```css +/* rn & css */ +transform: 'rotateX(45deg) rotateZ(0.785398rad)'; +/* 仅rn支持 */ +transform: [{rotateX: '45deg'}, {rotateZ: '0.785398rad'}] +``` +#### transform-origin +设置视图变换的原点，默认情况下，变换的原点是中心。 +##### 值类型 +- 单值时，该值必须是 px、百分比或关键字 left、center、right、top 和 bottom 之一； +- 双值时，第一个值代表 X 偏移， 必须是 px、百分比或关键字 left、center 和 right 之一， 第二个值代表 Y 偏移，必须是 px、百分比或关键字 top、center 和 bottom 之一； +- 三值时，前两个值与双值语法相同，第三个值代表 Z 偏移，必须是 px。 +##### 代码示例 +```css +transform-origin: bottom; +transform-origin: 10px 2px; +transform-origin: right bottom 20px; +``` +#### opacity +设置节点的不透明度 +##### 值类型 +number +- 0 元素完全透明 (即元素不可见). +- 任何一个位于 0.0-1.0 之间的 `` 元素半透明 (即元素后面的背景可见). +- 1 元素完全不透明 (即元素后面的背景不可见). +> 注意事项：在 RN 上设置节点 opacity: 0; 时该节点不会触发事件响应 +##### 代码示例 +``` css +/* 完全不透明 */ +opacity: 1; + +/* 半透明 */ +opacity: 0.6; + +/* 完全透明 */ +opacity: 0; +``` +#### pointer-events +控制视图是否可以成为触摸事件的目标 +##### 值类型 +enum +- auto/none +- box-none 仅 RN 支持，表示当前视图不会成为触摸事件的目标，但其子视图可以 +- box-only 仅 RN 支持，表示当前视图可以成为触摸事件的目标，但其子视图不能 +##### 代码示例 +``` css +pointer-events: auto; +pointer-events: none; +``` +#### overflow +控制元素溢出时所需的行为 +##### 值类型 +enum: visible/hidden/scroll +##### 代码示例 +``` css +/* 支持 */ +overflow: visible; +overflow: hidden; +overflow: scroll; + +/* 不支持 */ +overflow: clip; +overflow: auto; +overflow: hidden visible; +``` +#### aspect-ratio +规定盒子首选纵横比 +##### 值类型 +number, string +##### 代码示例 +``` css +/* 支持 */ +aspect-ratio: 1 / 1; +aspect-ratio: 1; +aspect-ratio: 0.5; +aspect-ratio: auto; +``` +#### color +##### 值类型 +color 参考 [Color](https://reactnative.dev/docs/colors) +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +color: orange; +color: #fff; +color: #fafafa; +color: rgb(255, 255, 255); +color: rgba(255, 99, 71, 0.2) +``` +#### font-family +可设置系统字体，引入字体文件，暂时不支持。 +##### 值类型 +string +> 注意事项 +> - [文本样式继承规则](#文本样式继承) +> - 仅支持设置一种字体 +##### 代码示例 +``` css +/* 支持 */ +font-family: PingFangSC-Regular + +/* 不支持 */ +font-family: "Gill Sans", sans-serif; +``` +#### font-size +可设置字体的大小 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +> 备注： +> - [文本样式继承规则](#文本样式继承) +> - [font-size 的百分比计算](#特殊的百分比计算规则) +##### 代码示例 +``` css +font-size: 12px; +font-size: 12rpx; +``` +#### font-style +设置文本的字体样式。 +##### 值类型 +enum: normal，italic +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +font-style: italic; +font-style: normal; +``` +#### font-weight +设置文字的权重。 +##### 值类型 +enum: 100，200，300，400，500，600，800，900,normal,bold +> 备注： +> - [文本样式继承规则](#文本样式继承) +> - 若在自定义字体图标上加 font-weight，可能会导致在某些安卓上不展示图标或者图标展示异常 +> - 100，200，300，400，500，600，800，900 在 RN 上是字符串类型而非数值类型，非字符串类型可能会导致某些安卓机型异常 +##### 代码示例 +``` css +font-weight: 100; +font-weight: 200; +font-weight: 300; +font-weight: 400; +font-weight: 500; +font-weight: 600; +font-weight: 700; +font-weight: 800; +font-weight: 900; + +font-weight: normal; +font-weight: bold; +``` +#### font-variant +设置文本的字体变体 +##### 值类型 +enum: small-caps/oldstyle-nums/lining-nums/tabular-nums/proportional-nums +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +font-variant: small-caps; +font-variant: oldstyle-nums; +font-variant: lining-nums; +font-variant: tabular-nums; +font-variant: lining-nums; +font-variant: proportional-nums; +``` +#### letter-spacing +定义字符之间的间距 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +letter-spacing: 2px; +letter-spacing: 2rpx; +``` +#### line-height +设置行高。 +##### 值类型 +number，单位参考[数值类型单位说明](#数值类型单位说明) +> 备注： +> - [文本样式继承规则](#文本样式继承) +> - [font-size 的百分比计算](#特殊的百分比计算规则) +##### 代码示例 +``` css +line-height: 16px +line-height: 16rpx +line-height: 100% +line-height: 1 +``` +#### text-align +设置文本的水平对齐方式。 +##### 值类型 +enum: left, right, center, justify +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +/** 支持 **/ +text-align: left; +text-align: right; +text-align: center; +text-align: justify; + +/** 不支持 **/ +text-align: match-parent; +text-align: auto; +text-align: justify-all; +``` +#### text-decoration-line +设置文本的装饰线样式。 +##### 值类型 +enum: none, underline, line-through, underline line-through +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +/** 支持 **/ +text-decoration-line: none; +text-decoration-line: underline; +text-decoration-line: line-through; +text-decoration-line: underline line-through; + +/** 不支持 **/ +text-decoration-line: overline; +``` +#### text-decoration-style +设置文本的装饰线样式 +##### 值类型 +enum: solid/double/dotted/dashed +> 备注 +> - [文本样式继承规则](#文本样式继承) +> - 仅 ios 支持 +##### 代码示例 +``` css +text-decoration-style: double; +``` +#### text-decoration-color +设置文本的装饰线颜色 +##### 值类型 +color 参考 [Color](https://reactnative.dev/docs/colors) +> 备注 +> - [文本样式继承规则](#文本样式继承) +> - 仅 ios 支持 +##### 代码示例 +``` css +text-decoration-color: #21ff21; +``` +#### text-decoration +text-decoration-line text-decoration-style text-decoration-color 的简写格式 +##### 简写规则 +- 按 text-decoration-line text-decoration-style text-decoration-color 顺序赋值 +- 赋值过程中，如遇到不支持的属性会忽略该属性；若属性值校验不合法，则忽略该值，继续校验下一个值是否合法，合法则赋值，不合法则继续校验下一个值 +- android 下仅转换 text-decoration-line，text-decoration-style/text-decoration-color 因不支持不会添加 +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +text-decoration: underline; +text-decoration: underline dotted; +text-decoration: underline dotted red; + +``` +#### text-transform +设置文本的大小写转换。 +##### 值类型 +enum: none, uppercase, lowercase, capitalize +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +``` css +/** 支持 **/ +text-transform: none; +text-transform: uppercase; +text-transform: lowercase; +text-transform: capitalize; + +/** 不支持 **/ +text-transform: full-width; +text-transform: full-size-kana; +text-transform: math-auto; +``` +#### vertical-align +用来指定行内文本的对齐方式 +##### 值类型 +enum: auto/top/bottom/middle +> 备注 +> - [文本样式继承规则](#文本样式继承) +> - 仅 android 支持 +##### 代码示例 +```css +/* 支持 */ +vertical-align: auto; +vertical-align: middle; +vertical-align: top; +vertical-align: bottom; + +/* 不支持 */ +vertical-align: baseline; +vertical-align: sub; +vertical-align: super; +vertical-align: text-top; +vertical-align: text-bottom; +``` +#### user-select +用于控制用户是否可以选择文本 +##### 值类型 +enum: auto/text/none/contain/all +> 备注: [文本样式继承规则](#文本样式继承) +##### 代码示例 +```css +/* 关键字值 */ +user-select: none; +user-select: auto; +user-select: text; +user-select: contain; +user-select: all; +``` +#### text-shadow +设置文本阴影，因 RN 不支持 text-shadow 属性，实际是由 mpx 按 RN 支持的 textShadowOffset: \{ width?: number, height?: number \}; textShadowRadius: number; textShadowColor: number; 属性和顺序转换成对应的属性。 +##### 值类型 +offset-x|offset-y|blur-radius 值为 number，单位参考[数值类型单位说明](#数值类型单位说明)，textShadowColor 为 color 类型，参考[Color](#色值-color-类型支持的值格式说明) +##### 简写规则 +- 按 offset-x|offset-y|blur-radius|color 顺序赋值 +- 赋值过程中，如遇到不支持的属性会忽略该属性；若属性值校验不合法，则忽略该值，继续校验下一个值是否合法，合法则赋值，不合法则继续校验下一个值 +> 备注：[文本样式继承规则](#文本样式继承) +##### 代码示例 +```css +/* offset-x | offset-y | blur-radius | color */ +text-shadow: 1rpx 3rpx 0 #2E0C02; + +/* offset-x | offset-y */ +text-shadow: 5px 10px; + +/* offset-x | offset-y | color */ +/* 因为第三个值是 color 类型，赋值给 textShadowRadius 检验不合法，继续赋值给下一个属性 textShadowColor 校验合法 */ +text-shadow: 5px 5px #558abb; +``` +### 应用能力 +#### app配置 +对标参考[微信app配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html), 以下仅标注支持项或者特殊关注项，未标注的均未支持 + +| 配置项 | 支持情况 | 特殊说明 | +| ---- | ---- | ---- | +| entryPagePath | 支持 | 无| +| pages | 支持 | 无 | +| window | 子属性部分支持 | 参考下面window配置部分 | +| tabbar | 暂未支持 | 无 | +| networkTimeout | 支持 | 无 | +| subpackages | 支持 | 分包在RN下暂未进行拆包处理，仅能正常打包在一起，分包能力待后续支持 | +| usingComponents | 支持 | | +| vw | 支持 | 无 | + +##### window配置 +app里面的window配置，参考[微信内window配置说明](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#window) + +| 配置项 | 支持情况 | 特殊说明 | +| ---- | ---- | ---- | +| navigationBarBackgroundColor | 支持 | 无| +| navigationBarTextStyle | 支持 | 无 | +| navigationStyle | 支持 | 无 | +| backgroundColor | 支持 | 无 | + +#### 页面配置 +页面配置内可配置页面级别的属性，参考[微信页面配置说明](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/page.html) + +| 配置项 | 支持情况 | 特殊说明 | +| ---- | ---- | ---- | +| navigationBarBackgroundColor | 支持 | 无| +| navigationBarTextStyle | 支持 | 无 | +| navigationStyle | 支持 | 无 | +| backgroundColor | 支持 | 无 | +| usingComponents | 支持 | 无 | +| disableScroll | 不支持 | RN下默认页面不支持滚动，如需滚动需要使用可滚动的元素包裹 | + +#### 状态管理 +##### pinia +暂未支持 +##### store +已支持 +#### i18n +支持 +#### 原子类能力 +开发中，暂未支持 +#### 依赖注入（Provide/Inject） +开发中，暂未支持 + +#### 环境API +在RN环境中也提供了一部分常用api能力，方法名与使用方式与小程序相同，个别api提供的能力或者返回值(返回值部分如果不支持，会在调用是有warn提醒)会比微信小程序提供的能力少一些，以下是使用说明： +##### 使用说明 +如果全量引入api-proxy这种情况下，需要如下配置 +```javascript +// 全量引入api-proxy +import mpx from '@mpxjs/core' +import apiProxy from '@didi/mpxjs-api-proxy' +mpx.use(apiProxy, { usePromise: true }) +``` +需要在mpx项目中需要配置externals +```bash +externals: { + ... + '@react-native-async-storage/async-storage': '@react-native-async-storage/async-storage', + '@react-native-clipboard/clipboard': '@react-native-clipboard/clipboard', + '@react-native-community/netinfo': '@react-native-community/netinfo', + 'react-native-device-info': 'react-native-device-info', + 'react-native-safe-area-context': 'react-native-safe-area-context', + 'react-native-reanimated': 'react-native-reanimated', + 'react-native-get-location': 'react-native-get-location', + 'react-native-haptic-feedback': 'react-native-haptic-feedback' +}, +``` +如果引用单独的api-proxy方法这种情况，需要根据下表说明是否用到以下方法，来确定是否需要配置externals，配置参考上面示例 + +| api方法 | 依赖的react-native三方库 | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| +| showActionSheet | react-native-reanimated | +| getNetworkType、
      offNetworkStatusChange、
      onNetworkStatusChange | @react-native-community/netinfo | +| getLocation、
      openLocation、
      chooseLocation | react-native-get-location | +| setStorage、
      setStorageSync、
      getStorage、
      getStorageSync、
      getStorageInfo、
      getStorageInfoSync、
      removeStorage，
      removeStorageSync，
      clearStorage，
      clearStorageSync | @react-native-async-storage/async-storage | +| getSystemInfo、
      getSystemInfoSync、
      getDeviceInfo、
      getWindowInfo、
      getLaunchOptionsSync、
      getEnterOptionsSync | react-native-device-info | +| getWindowInfo、
      getLaunchOptionsSync、
      getEnterOptionsSync | react-native-safe-area-context | +| vibrateShort、
      vibrateLong | react-native-haptic-feedback | + +在RN 项目中，如果是以全量引入api-proxy的方法需要在RN环境中执行以下所有的命令，如果只是使用单个api的能力，可以参考上表来判断安装对应的包 +```bash +// 安装api-proxy下所用到的依赖 如果 +npm i @react-native-async-storage/async-storage +npm i @react-native-clipboard/clipboard +npm i @react-native-community/netinfo +npm i react-native-safe-area-context +npm i react-native-device-info +npm i react-native-reanimated +npm i react-native-haptic-feedback +ios项目需要执行如下命令 +cd ios +pod install + +npm i react-native-get-location +``` + +android下需要做如下配置： +安装react-native-get-location包后，需要在AndroidManifest.xml中定义位置权限，[参考文档](https://www.npmjs.com/package/react-native-get-location) +```html + + + + + + +``` +安装react-native-haptic-feedback包后需要在安卓中配置，[配置参考文档](https://github.com/mkuczera/react-native-haptic-feedback) +打开 android/app/src/main/java/[...]/MainApplication.java. 在文件的顶部添加以下导入下面的代码片段 +``` +import com.mkuczera.RNReactNativeHapticFeedbackPackage; +``` + + +修改设置,将下面的配置添加到android/settings.gradle文件中 + +```js +include ':react-native-haptic-feedback' +project(':react-native-haptic-feedback').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-haptic-feedback/android') +``` +react-native-reanimated在mpx和RN项目都要安装，安装好包后需要在babel.config.json文件中做如下配置，并且RN环境中使用的react-native-reanimated与mpx项目中安装的react-native-reanimated版本要一致： +[配置参考文档](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) +```javascript +module.exports = { + presets: [ + ... // don't add it here :) + ], + plugins: [ + ... + 'react-native-reanimated/plugin', + ], +}; +``` + +注意事项： + +1. 调用 `@mpxjs/api-proxy` 当中抹平跨端环境的 `createSelectorQuery` 方法创建的 `SelectorQuery` 实例，在使用过程中需要手动调用实例上的 `in` 方法来指定组件上下文。示例： + +```javascript +import { createComponent } from '@mpxjs/core' + +createComponent({ + attached () { + const query = wx.createSelectorQuery() + query.select('#the-id').boundingClientRect() + query.selectViewport().scrollOffset() + query.exec(function(res){ + res[0].top // #the-id节点的上边界坐标 + res[1].scrollTop // 显示区域的竖直滚动位置 + }).in(this) // this 为组件实例 + } +}) +```` + +2. `SelectorQuery.select/SelectorQuery.selectAll` 方法目前仅支持2种选择器写法 + * id 选择器：`#id` + * class 选择器（可连续指定多个）：`.a-class` 或 `.a-class.b-class.c-class` + + + +#### Webview API +对于web-view组件打开的网页，想要跟RN通信，或者跳转到RN页面，提供了以下能力 + +| 方法名 | 说明 | +|---------------|---------------------------------------------| +| navigateTo | 保留当前webview页面，跳转RN页面 | +| navigateBack | 关闭当前页面，返回上一页或多级RN页面 | +| switchTab | 跳转到RN的 tabBar 页面 | +| reLaunch | 关闭所有页面，打开到应用内的某个RN页面 | +| redirectTo | 关闭当前页面，跳转到应用内的某个RN页面 | +| getEnv | 获取当前环境 | +| postMessage | 向RN发送消息，实时触发组件的message事件 | +| invoke | 开放一个webview页面和web页面互通消息的能力 | + +##### webview-bridge示例代码 +```javascript +import webviewBridge from '@mpxjs/webview-bridge' +webviewBridge.navigateTo({ + url: 'RN地址', + success: () => { + console.log('跳转成功') + } +}) +``` + +##### invoke示例代码 +对于业务中一些特殊的方法，需要有web与RN进行交互的这种情况，基于这种情况在mpx框架内部提供了挂在方法的能力，在webview-bridge提供了invoke通信的能力，具体使用方法如下： + +RN环境中挂载getTime的逻辑 +```javascript +import mpx from '@mpxjs/core' +... +// 普通方法 +mpx.config.webviewConfig = { + apiImplementations: { + getTime: (options = {}) => { + const { params = {} } = options + return { + text: params.text, + time: '2024-12-24' + } + } + } +} +// 或者promise +mpx.config.webviewConfig = { + apiImplementations: { + getTime: (options = {}) => { + return new Promise((resolve, reject) => { + const { params = {} } = options + if (params.text) { + resolve({ + text: params.text, + time: '2024-12-24' + }) + } else { + reject(new Error('没有传text参数')) + } + }) + } + } +} +... +``` +web中通信的逻辑 +```javascript +import webviewBridge from '@mpxjs/webview-bridge' +webviewBridge.invoke('getTime', { + params: { + text: '我是入参' + }, + success: (res) => { + console.log('接收到的消息：', res.time) + } +}) +``` + + +### 其他使用限制 +如事件的target等 diff --git a/docs-vitepress/guide/platform/web.md b/docs-vitepress/guide/platform/web.md new file mode 100644 index 0000000000..e2ee6ceaa5 --- /dev/null +++ b/docs-vitepress/guide/platform/web.md @@ -0,0 +1 @@ +# 跨端输出Web diff --git a/docs-vuepress/guide/tool/e2e-test.md b/docs-vitepress/guide/tool/e2e-test.md similarity index 100% rename from docs-vuepress/guide/tool/e2e-test.md rename to docs-vitepress/guide/tool/e2e-test.md diff --git a/docs-vuepress/guide/tool/ts.md b/docs-vitepress/guide/tool/ts.md similarity index 100% rename from docs-vuepress/guide/tool/ts.md rename to docs-vitepress/guide/tool/ts.md diff --git a/docs-vuepress/guide/tool/unit-test.md b/docs-vitepress/guide/tool/unit-test.md similarity index 100% rename from docs-vuepress/guide/tool/unit-test.md rename to docs-vitepress/guide/tool/unit-test.md diff --git a/docs-vuepress/guide/understand/compile.md b/docs-vitepress/guide/understand/compile.md similarity index 100% rename from docs-vuepress/guide/understand/compile.md rename to docs-vitepress/guide/understand/compile.md diff --git a/docs-vuepress/guide/understand/runtime.md b/docs-vitepress/guide/understand/runtime.md similarity index 100% rename from docs-vuepress/guide/understand/runtime.md rename to docs-vitepress/guide/understand/runtime.md diff --git a/docs-vuepress/README.md b/docs-vitepress/index.md similarity index 100% rename from docs-vuepress/README.md rename to docs-vitepress/index.md diff --git a/docs-vitepress/package.json b/docs-vitepress/package.json new file mode 100644 index 0000000000..2504083cc2 --- /dev/null +++ b/docs-vitepress/package.json @@ -0,0 +1,18 @@ +{ + "name": "docs-vuepress", + "version": "1.0.0", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + "description": "", + "type": "module", + "dependencies": { + "vue": "^3.4.37" + }, + "devDependencies": { + "workbox-window": "^7.1.0" + } +} diff --git a/docs-vuepress/.vuepress/public/favicon.ico b/docs-vitepress/public/favicon.ico similarity index 100% rename from docs-vuepress/.vuepress/public/favicon.ico rename to docs-vitepress/public/favicon.ico diff --git a/docs-vuepress/.vuepress/public/logo.png b/docs-vitepress/public/logo.png similarity index 100% rename from docs-vuepress/.vuepress/public/logo.png rename to docs-vitepress/public/logo.png diff --git a/docs-vuepress/.vuepress/config.js b/docs-vuepress/.vuepress/config.js deleted file mode 100644 index 796588e020..0000000000 --- a/docs-vuepress/.vuepress/config.js +++ /dev/null @@ -1,189 +0,0 @@ -const { headerPlugin } = require('./headerMdPlugin') - -const sidebar = { - '/guide/': [ - { - title: '基础', - collapsable: false, - children: [ - 'basic/start', - 'basic/intro', - 'basic/single-file', - 'basic/ide', - 'basic/template', - 'basic/css', - 'basic/reactive', - 'basic/class-style-binding', - 'basic/conditional-render', - 'basic/list-render', - 'basic/event', - 'basic/two-way-binding', - 'basic/component', - 'basic/refs', - 'basic/option-chain' - ] - }, - { - title: '进阶', - collapsable: false, - children: [ - 'advance/store', - 'advance/pinia', - 'advance/mixin', - 'advance/npm', - 'advance/subpackage', - 'advance/async-subpackage', - 'advance/platform', - 'advance/i18n', - 'advance/size-report', - 'advance/image-process', - 'advance/progressive', - 'advance/ability-compatible', - 'advance/plugin', - 'advance/custom-output-path', - 'advance/utility-first-css', - 'advance/ssr', - 'advance/provide-inject' - ] - }, - { - title: '组合式 API', - collapsable: false, - children: [ - 'composition-api/composition-api', - 'composition-api/reactive-api' - ] - }, - { - title: '工具', - collapsable: false, - children: [ - 'tool/ts', - 'tool/unit-test', - 'tool/e2e-test' - ] - }, - { - title: '拓展', - collapsable: false, - path: '/guide/extend', - children: [ - 'extend/fetch', - 'extend/api-proxy', - 'extend/mock' - ] - }, - { - title: '理解', - collapsable: false, - children: [ - 'understand/runtime', - 'understand/compile' - ] - }, - { - title: '迁移', - collapsable: false, - children: [ - 'migrate/2.9', - 'migrate/2.8', - 'migrate/2.7', - 'migrate/mpx-cli-3' - ] - } - ], - '/api/': [ - 'app-config', - 'global-api', - 'instance-api', - 'store-api', - 'directives', - 'compile', - 'builtIn', - 'reactivity-api', - 'composition-api', - 'optional-api', - 'extend' - ], - '/articles/': [ - { title: '滴滴开源小程序框架Mpx', path: '1.0' }, - { title: 'Mpx发布2.0，完美支持跨平台开发', path: '2.0' }, - { title: '小程序框架运行时性能大测评', path: 'performance' }, - { title: 'Mpx框架初体验', path: 'mpx1' }, - { title: 'Mpx框架技术揭秘', path: 'mpx2' }, - { title: '基于Mpx的小程序体积优化', path: 'size-control' }, - { title: 'Mpx中基于 Typescript Template Literal Types 实现链式key的类型推导', path: 'ts-derivation' }, - { title: 'Mpx2.7 版本正式发布，大幅提升编译构建速度', path: '2.7-release' }, - { title: 'Mpx2.8 版本正式发布，使用组合式 API 开发小程序', path: '2.8-release' }, - { title: 'Mpx2.9 版本正式发布，支持原子类、SSR 和包体积优化', path: '2.9-release' }, - { title: '小程序跨端组件库 Mpx-cube-ui 开源啦', path: 'mpx-cube-ui' }, - { title: 'Mpx-cli 插件化改造', path: 'mpx-cli-next' }, - { title: 'Mpx 小程序单元测试能力建设与实践', path: 'unit-test'} - ] -} - -const nav = [ - { text: '指南', link: '/guide/basic/start' }, - { text: 'API', link: '/api/index' }, - { text: '文章', link: '/articles/index' }, - { text: '更新记录', link: 'https://github.com/didi/mpx/releases', target:'_blank'}, - { text: 'Github', link: 'https://github.com/didi/mpx', target:'_blank'} -] - -module.exports = { - base: '/', - head: [ - ['link', { rel: 'icon', href: '/favicon.ico' }], - // 插入一段 clarity 的数据分析的代码 - ['script', { type: 'text/javascript' }, `(function(c,l,a,r,i,t,y){ - c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)}; - t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i; - y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y); - })(window, document, "clarity", "script", "jtvvy52wxy");`] - ], - title: 'Mpx框架', - locales: { - '/': { - lang: 'zh-CN', // 将会被设置为 的 lang 属性 - title: 'Mpx框架', - description: 'Mpxjs 是滴滴开源的支持跨端开发、深度性能优化的增强型小程序开发框架。使用 Mpxjs 帮助你更好开发小程序，拥有类似 VueJS 的数据响应能力，在降低研发心智负担的同时比原生小程序性能更好，完全基于原生小程序语法保障了最少的坑，一次开发多端生效同时支持微信小程序、支付宝小程序、抖音小程序、百度小程序、Web H5。' - }, - }, - shouldPrefetch: () => false, - plugins: { - '@vuepress/pwa': { - serviceWorker: true, - updatePopup: { - message: '文档有更新啦！', - buttonText: '刷新' - } - }, - '@vuepress/active-header-links': { - sidebarLinkSelector: '.header-anchor', - headerAnchorSelector: '.header-anchor' - } - }, - themeConfig: { - // navbar: false, - algolia: { - apiKey: '7849f511f78afc4383a81f0137a91c0f', - indexName: 'mpxjs', - }, - sidebarDepth: 1, - logo: '/logo.png', - displayAllHeaders: false, - sidebar, - nav - }, - chainWebpack: (config, isServer) => { - // 添加node_modules避免resolve错误 - config.resolve.modules.add('node_modules') - }, - markdown: { - // markdown-it-toc 的选项 - extendMarkdown: md => { - // 使用更多的 markdown-it 插件! - md.use(headerPlugin) - } - } -} diff --git a/docs-vuepress/.vuepress/enhanceApp.js b/docs-vuepress/.vuepress/enhanceApp.js deleted file mode 100644 index 878e2134de..0000000000 --- a/docs-vuepress/.vuepress/enhanceApp.js +++ /dev/null @@ -1,18 +0,0 @@ -export default ({ router }) => { - if (typeof process === 'undefined' || process.env.VUE_ENV !== 'server') { - router.onReady(() => { - const { app } = router - - app.$once('hook:mounted', () => { - setTimeout(() => { - const { hash } = document.location - if (hash.length > 1) { - const id = decodeURIComponent(hash.substring(1)) - const element = document.getElementById(id) - if (element) element.scrollIntoView() - } - }, 500) - }) - }) - } -} diff --git a/docs-vuepress/.vuepress/headerMdPlugin.js b/docs-vuepress/.vuepress/headerMdPlugin.js deleted file mode 100644 index d78b29b20a..0000000000 --- a/docs-vuepress/.vuepress/headerMdPlugin.js +++ /dev/null @@ -1,84 +0,0 @@ - -const rControl = /[\u0000-\u001f]/g; -const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'<>,.?/]+/g; -const anchorReg = /\{#([a-z0-9\-_]+?)\}\s*$/ -const slugify$1 = (content) => { - let str = content - if (anchorReg.test(content)) { - str = anchorReg.exec(content)[1] - } - return str.replace(rControl, "").replace(rSpecial, "-").replace(/\-{2,}/g, "-").replace(/^\-+|\-+$/g, "").replace(/^(\d)/, "_$1").toLowerCase(); -}; - -const removeSlug$1 = (content) => { - let str = content - if (anchorReg.test(content)) { - str = str.split('{#')[0] - } - return str -} -const parseEmojis = (str) => { - return str.replace(/:(.+?):/g, (placeholder, key) => require$$0$3[key] || placeholder); -}; -const unescapeHtml = (html) => html.replace(/"/g, '"').replace(/'/g, "'").replace(/:/g, ":").replace(/</g, "<").replace(/>/g, ">"); -const removeMarkdownTokens = (str) => str.replace(/(\[(.[^\]]+)\]\((.[^)]+)\))/g, "$2").replace(/(`|\*{1,3}|_)(.*?[^\\])\1/g, "$2").replace(/(\\)(\*|_|`|\!|<|\$)/g, "$2"); -const remvoeCustomAnchor = (str) => str.replace(/\{#([a-z0-9\-_]+?)\}\s*$/, ""); -const trim = (str) => str.trim(); -const removeNonCodeWrappedHTML = (str) => { - return String(str) -}; -const compose = (...processors) => { - if (processors.length === 0) - return (input) => input; - if (processors.length === 1) - return processors[0]; - return processors.reduce((prev, next) => { - return (str) => next(prev(str)); - }); -}; -const parseHeader = compose(unescapeHtml, parseEmojis, remvoeCustomAnchor, removeMarkdownTokens, trim); -const deeplyParseHeader = compose(removeNonCodeWrappedHTML, parseHeader); - -const headerPlugin = (md, include = ["h2", "h3"]) => { - md.renderer.rules.heading_open = (tokens, i, options, env, self) => { - const token = tokens[i]; - if (include.includes(token.tag)) { - const title = tokens[i + 1].content; - const slug = slugify$1(title) - const parseTitle = deeplyParseHeader(title) - tokens[i + 1].content = parseTitle - token.attrs.forEach((item) => { - if (item[0] === 'id') { - item[1] = slug - } - }) - const nextToken = tokens[i + 1] - if (nextToken.type === 'inline') { - const inlineTokenChild = nextToken.children - inlineTokenChild.forEach((child, index) => { - if (child.type === 'link_open') { - child.attrs = child.attrs.map((item) => { - if (item[0] === 'href') { - item[1] = '#' + slug - } - return item - }) - } - if (child.type === 'text' && child.content && child.content.trim()) { - if (child.content.includes('{#')) { - child.content = removeSlug$1(child.content) - } - } - }) - } - } - return self.renderToken(tokens, i, options); - }; -}; - - -module.exports = { - headerPlugin, - deeplyParseHeader, - slugify$1 -} diff --git a/docs-vuepress/.vuepress/public/baidu_verify_codeva-GYcT5ujCTB.html b/docs-vuepress/.vuepress/public/baidu_verify_codeva-GYcT5ujCTB.html deleted file mode 100644 index d4526e039c..0000000000 --- a/docs-vuepress/.vuepress/public/baidu_verify_codeva-GYcT5ujCTB.html +++ /dev/null @@ -1 +0,0 @@ -e197dca3487ecef730bbb3a05e79d985 \ No newline at end of file diff --git a/docs-vuepress/.vuepress/public/manifest.webmanifest b/docs-vuepress/.vuepress/public/manifest.webmanifest deleted file mode 100644 index dcc89dfc8b..0000000000 --- a/docs-vuepress/.vuepress/public/manifest.webmanifest +++ /dev/null @@ -1,15 +0,0 @@ -{ - "name": "Mpx", - "short_name": "Mpx", - "icons": [ - { - "src": "https://dpubstatic.udache.com/static/dpubimg/1ESVodfAED/logo.png", - "sizes": "192x192", - "type": "image/png" - } - ], - "start_url": "/index.html", - "theme_color": "#ffffff", - "background_color": "#ffffff", - "display": "standalone" -} \ No newline at end of file diff --git a/docs-vuepress/.vuepress/styles/index.styl b/docs-vuepress/.vuepress/styles/index.styl deleted file mode 100644 index f0516b9218..0000000000 --- a/docs-vuepress/.vuepress/styles/index.styl +++ /dev/null @@ -1,151 +0,0 @@ -.navbar .site-name - display none!important - -// .sidebar .page -// top 3.5rem !important - -aside.sidebar - // top 4rem !important - -main.page - // margin-top 3.5rem !important - -a - word-break: break-all - -:root { - --vt-c-white: #ffffff; - --vt-c-white-soft: #f9f9f9; - --vt-c-white-mute: #f1f1f1; - - --vt-c-black: #1a1a1a; - --vt-c-black-pure: #000000; - --vt-c-black-soft: #242424; - --vt-c-black-mute: #2f2f2f; - - --vt-c-indigo: #213547; - --vt-c-indigo-soft: #476582; - --vt-c-indigo-light: #aac8e4; - - --vt-c-gray: #8e8e8e; - --vt-c-gray-light-1: #aeaeae; - --vt-c-gray-light-2: #c7c7c7; - --vt-c-gray-light-3: #d1d1d1; - --vt-c-gray-light-4: #e5e5e5; - --vt-c-gray-light-5: #f2f2f2; - --vt-c-gray-dark-1: #636363; - --vt-c-gray-dark-2: #484848; - --vt-c-gray-dark-3: #3a3a3a; - --vt-c-gray-dark-4: #282828; - --vt-c-gray-dark-5: #202020; - - --vt-c-divider-light-1: rgba(60, 60, 60, 0.29); - --vt-c-divider-light-2: rgba(60, 60, 60, 0.12); - --vt-c-divider-dark-1: rgba(84, 84, 84, 0.65); - --vt-c-divider-dark-2: rgba(84, 84, 84, 0.48); - - --vt-c-text-light-1: var(--vt-c-indigo); - --vt-c-text-light-2: rgba(60, 60, 60, 0.70); - --vt-c-text-light-3: rgba(60, 60, 60, 0.33); - --vt-c-text-light-4: rgba(60, 60, 60, 0.18); - --vt-c-text-light-code: var(--vt-c-indigo-soft); - - --vt-c-text-dark-1: rgba(255, 255, 255, 0.87); - --vt-c-text-dark-2: rgba(235, 235, 235, 0.60); - --vt-c-text-dark-3: rgba(235, 235, 235, 0.38); - --vt-c-text-dark-4: rgba(235, 235, 235, 0.18); - --vt-c-text-dark-code: var(--vt-c-indigo-light); - - --vt-c-green: #42b883; - --vt-c-green-light: #42d392; - --vt-c-green-lighter: #35eb9a; - --vt-c-green-dark: #33a06f; - --vt-c-green-darker: #155f3e; - - --vt-c-blue: #3b8eed; - --vt-c-blue-light: #549ced; - --vt-c-blue-lighter: #50a2ff; - --vt-c-blue-dark: #3468a3; - --vt-c-blue-darker: #255489; - - --vt-c-yellow: #ffc517; - --vt-c-yellow-light: #ffe417; - --vt-c-yellow-lighter: #ffff17; - --vt-c-yellow-dark: #e0ad15; - --vt-c-yellow-darker: #bc9112; - - --vt-c-red: #ed3c50; - --vt-c-red-light: #f43771; - --vt-c-red-lighter: #fd1d7c; - --vt-c-red-dark: #cd2d3f; - --vt-c-red-darker: #ab2131; - - --vt-c-purple: #de41e0; - --vt-c-purple-light: #e936eb; - --vt-c-purple-lighter: #f616f8; - --vt-c-purple-dark: #823c83; - --vt-c-purple-darker: #602960; -} - -:root { - --c-brand: #3eaf7c; - - --c-bg: #ffffff; - --c-bg-light: #f3f4f5; - --c-bg-lighter: #eeeeee; - - --c-text: #2c3e50; - --c-text-light: #3a5169; - --c-text-quote: #999999; - - --c-border-dark: #dfe2e5; - - --vt-c-bg: var(--vt-c-white); - --vt-c-bg-soft: var(--vt-c-white-soft); - --vt-c-bg-mute: var(--vt-c-white-mute); - - --vt-c-divider: var(--vt-c-divider-light-1); - --vt-c-divider-light: var(--vt-c-divider-light-2); - - --vt-c-divider-inverse: var(--vt-c-divider-dark-1); - --vt-c-divider-inverse-light: var(--vt-c-divider-dark-2); - - --vt-c-text-1: var(--vt-c-text-light-1); - --vt-c-text-2: var(--vt-c-text-light-2); - --vt-c-text-3: var(--vt-c-text-light-3); - --vt-c-text-4: var(--vt-c-text-light-4); - --vt-c-text-code: var(--vt-c-text-light-code); - - --vt-c-text-inverse-1: var(--vt-c-text-dark-1); - --vt-c-text-inverse-2: var(--vt-c-text-dark-2); - --vt-c-text-inverse-3: var(--vt-c-text-dark-3); - --vt-c-text-inverse-4: var(--vt-c-text-dark-4); - - --vt-c-brand: var(--vt-c-green); - --vt-c-brand-light: var(--vt-c-green-light); - --vt-c-brand-dark: var(--vt-c-green-dark); - --vt-c-brand-highlight: var(--vt-c-brand-dark); - - .DocSearch { - --docsearch-primary-color: var(--c-brand); - --docsearch-text-color: var(--c-text); - --docsearch-highlight-color: var(--c-brand); - --docsearch-muted-color: var(--c-text-quote); - --docsearch-container-background: rgba(9, 10, 17, 0.8); - --docsearch-modal-background: var(--c-bg-light); - --docsearch-searchbox-background: var(--c-bg-lighter); - --docsearch-searchbox-focus-background: var(--c-bg); - --docsearch-searchbox-shadow: inset 0 0 0 2px var(--c-brand); - --docsearch-hit-color: var(--c-text-light); - --docsearch-hit-active-color: var(--c-bg); - --docsearch-hit-background: var(--c-bg); - --docsearch-hit-shadow: 0 1px 3px 0 var(--c-border-dark); - --docsearch-footer-background: var(--c-bg); -} -} - -@media (max-width: 719px) { - :root { - --c-bg-lighter: none; - } -} diff --git a/docs-vuepress/.vuepress/styles/pallete.styl b/docs-vuepress/.vuepress/styles/pallete.styl deleted file mode 100644 index bccbde797e..0000000000 --- a/docs-vuepress/.vuepress/styles/pallete.styl +++ /dev/null @@ -1,4 +0,0 @@ -// responsive breakpoints -$MQNarrow = 959px -$MQMobile = 719px -$MQMobileNarrow = 419px \ No newline at end of file diff --git a/docs-vuepress/.vuepress/theme/enhanceApp.js b/docs-vuepress/.vuepress/theme/enhanceApp.js deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs-vuepress/.vuepress/theme/index.js b/docs-vuepress/.vuepress/theme/index.js deleted file mode 100644 index 93bb9bd1c1..0000000000 --- a/docs-vuepress/.vuepress/theme/index.js +++ /dev/null @@ -1,12 +0,0 @@ -const formatHeaderSlugPlugin = require('./vuepress-format-header-slug-plugin') - -module.exports = { - extend: '@vuepress/theme-default', - plugins: [ - ['@vuepress/search', { - searchMaxSuggestions: 10 - }], - ['@vuepress/back-to-top'], - formatHeaderSlugPlugin - ] -} diff --git a/docs-vuepress/.vuepress/theme/layouts/HomepageLayout.vue b/docs-vuepress/.vuepress/theme/layouts/HomepageLayout.vue deleted file mode 100644 index 7d48fac332..0000000000 --- a/docs-vuepress/.vuepress/theme/layouts/HomepageLayout.vue +++ /dev/null @@ -1,51 +0,0 @@ - - - - - \ No newline at end of file diff --git a/docs-vuepress/guide/basic/component.md b/docs-vuepress/guide/basic/component.md deleted file mode 100644 index 75f0038b2a..0000000000 --- a/docs-vuepress/guide/basic/component.md +++ /dev/null @@ -1,94 +0,0 @@ -# 自定义组件 - -Mpx中的自定义组件完全基于小程序原生的自定义组件支持，与此同时，Mpx提供的数据响应和模板增强等一系列增强能力都能在自定义组件中使用。 - -原生自定义组件的规范详情查看[这里](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Component.html) - -## 动态组件 - -Mpx中提供了使用方法类似于 Vue 的动态组件能力，这是一个基于 wx:if 实现的语法。通过对 `is` 属性进行动态绑定，可以实现在同一个挂载点切换多个组件，前提需要动态切换的组件已经在全局或者组件中完成注册。 -使用示例如下： - -```html - - - - - - - - - -``` - -## slot - -在组件中使用slot（插槽）可以使我们封装的组件更具有可扩展性，Mpx完全支持原生插槽的使用。 - -简单示例如下： - -```html - - - - - 这是组件模板 - - - -``` - -下面是引入 `mySlot` 组件的页面 - -```html - - - - - - - -``` - -更多详情可查看[这里](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html) diff --git a/docs-vuepress/guide/platform/miniprogram.md b/docs-vuepress/guide/platform/miniprogram.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs-vuepress/guide/platform/rn.md b/docs-vuepress/guide/platform/rn.md deleted file mode 100644 index bd9158a499..0000000000 --- a/docs-vuepress/guide/platform/rn.md +++ /dev/null @@ -1,40 +0,0 @@ -# 跨端输出RN -大致介绍 - -## 跨端样式定义 - -### CSS选择器 - -### 样式单位 - -### 文本样式继承 - -### 简写样式属性 - -### CSS函数 - -### 使用原子类 - -## 混合编写RN代码 - -### 使用RN组件 - -### 使用React hooks - -## 能力支持范围 - -### 模版语法 - -### 基础组件 - -### 自定义组件 - -### 样式规则 - -### 应用能力 - -### 环境API - -### Webview API - -### 其他使用注意事项 diff --git a/docs-vuepress/guide/platform/web.md b/docs-vuepress/guide/platform/web.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs-vuepress/rn-api.md b/docs-vuepress/rn-api.md deleted file mode 100644 index 6a71b084e3..0000000000 --- a/docs-vuepress/rn-api.md +++ /dev/null @@ -1,152 +0,0 @@ -# API支持列表 - -mpx转RN的对标微信api目前支持及部分的api转换，目前支持的能力可以参考下表： - -| 支持方法 | -|------------------------| -| getSystemInfo | -| getSystemInfoSync | -| getDeviceInfo | -| getWindowInfo | -| request | -| setStorage | -| removeStorage | -| removeStorageSync | -| getStorage | -| getStorageInfo | -| clearStorage | -| clearStorageSync | -| setClipboardData | -| getClipboardData | -| makePhoneCall | -| onWindowResize | -| offWindowResize | -| arrayBufferToBase64 | -| base64ToArrayBuffer | -| connectSocket | -| getNetworkType | -| onNetworkStatusChange | -| offNetworkStatusChange | - -# 使用说明 - -对于一些api-proxy中没有提供的能力，用户可以搭配mpx对象方式传入custom使用即可示例如下： - -```js -import mpx from '@mpxjs/core' -import apiProxy from '@mpxjs/api-proxy' -import { showModal } from '@test/showModal' - -mpx.use(apiProxy, { - custom: { - ios: { - showModal - }, - android: { - showModal - } - } -}) - -mpx.showModal({ - title: '标题', - content: '这是一个弹窗', - success (res) { - console.log('弹框展示成功') - } -}) -``` - -# API抹平差异详情 - -对于一些微信独有的返回结果，或者RN目前不能支持的入参/返回结果，在下面会有详细说明： - -### getSystemInfo/getSystemInfoSync - -| 不支持返回值 | -|------------------------| -| language | -| version | -| SDKVersion | -| benchmarkLevel | -| albumAuthorized | -| cameraAuthorized | -| locationAuthorized | -| microphoneAuthorized | -| notificationAuthorized | -| phoneCalendarAuthorized | -| host | -| enableDebug | -| notificationAlertAuthorized | -| notificationBadgeAuthorized | -| notificationSoundAuthorized | -| bluetoothEnabled | -| locationEnabled | -| wifiEnabled | -| locationReducedAccuracy | -| theme | - -### getDeviceInfo - -| 不支持返回值 | -|------------------------| -| benchmarkLevel | -| abi | -| cpuType | - -### getWindowInfo - -| 不支持返回值 | -|------------------------| -| screenTop | - -### request - -| 不支持入参 | -|-----------| -| useHighPerformanceMode | -| enableHttp2 | -| enableProfile | -| enableQuic | -| enableCache | -| enableHttpDNS | -| httpDNSServiceId | -| enableChunked | -| forceCellularNetwork | -| redirect | - - -| 不支持返回值 | -|------------------------| -| cookies | -| profile | -| exception | - -### setStorage/getStorage - -| 不支持入参 | -|-----------| -| encrypt | - -### getStorageInfo - -| 不支持返回值 | -|-----------| -| currentSize | -| limitSize | - -### connectSocket - -| 不支持入参 | -|-----------| -| tcpNoDelay | -| perMessageDeflate | -| timeout | -| forceCellularNetwork | - -### getNetworkType - -| 不支持返回值 | -|----------------------| -| signalStrength | -| hasSystemProxy | diff --git a/docs-vuepress/rn-component.md b/docs-vuepress/rn-component.md deleted file mode 100644 index f0d2e378b9..0000000000 --- a/docs-vuepress/rn-component.md +++ /dev/null @@ -1,73 +0,0 @@ -# RN 自定义组件支持 -创建自定义组件在 RN 环境下部分实例方法、属性存在兼容性问题不支持， -此文档以微信小程序为参照，会详细列出各方法、属性的支持度。 - -## 参数 - - -### 组件定义属性说明 - -| 属性 | 类型 | RN 是否支持 | 描述 | -|------------|------------------|---------|---------------------------------------------------------------------------| -| properties | Object Map | 是 | 组件的对外属性，是属性名到属性设置的映射表 | -| data | Object | 是 | 组件的内部数据，和 `properties` 一同用于组件的模板渲染 | -| observers | Object | 是 | 组件数据字段监听器，用于监听 `properties` 和 `data` 的变化 | -| methods | Object | 是 | 组件的方法，包括事件响应函数和任意的自定义方法，关于事件响应函数的使用 | -| behaviors | String Array | 否 | 输出 RN 不支持 | -| created | Function | 是 | 组件生命周期函数-在组件实例刚刚被创建时执行，注意此时不能调用 `setData` | -| attached | Function | 是 | 组件生命周期函数-在组件实例进入页面节点树时执行 | -| ready | Function | 是 | 组件生命周期函数-在组件布局完成后执行 | -| moved | Function | 否 | RN 不支持，组件生命周期函数-在组件实例被移动到节点树另一个位置时执行 | -| detached | Function | 是 | 组件生命周期函数-在组件实例被从页面节点树移除时执行 | -| relations | Object | 否 | 输出 RN 不支持 | -| externalClasses | String Array | 否 | 输出 RN 不支持 | -| options | Object Map | 否 | 输出 RN 不支持，一些选项，诸如 multipleSlots、virtualHost、pureDataPattern，这些功能输出 RN 不支持 | -| lifetimes | Object | 是 | 组件生命周期声明对象 | -| pageLifetimes | Object | 是 | 组件所在页面的生命周期声明对象 | - -### 组件实例属性与方法 -生成的组件实例可以在组件的方法、生命周期函数中通过 this 访问。组件包含一些通用属性和方法。 - -| 属性名 | 类型 | RN 是否支持 | 描述 | -|--------|----------|---------|--------------------------| -| is | String | 否 | 输出 RN 暂不支持，未来支持, 组件的文件路径 | -| id | String | 是 | 节点id | -| dataset| String | 是 | 节点dataset | -| data | Object | 否 | 组件数据，通过 this 直接访问 | -| properties | Object | 否 | 组件props，通过 this 直接访问 | -| router | Object | 否 | 输出 RN 暂不支持 | -| pageRouter | Object | 否 | 输出 RN 暂不支持 | -| renderer | string | 否 | 输出 RN 暂不支持 | - -微信小程序原生方法 - -| 方法名 | RN是否支持 | 参数 | 描述 | -|---------------------|--------|-------------------------------------------|--------------------------| -| setData | 是 | Object newData | 设置data并执行视图层渲染 | -| hasBehavior | 否 | Object behavior | 检查组件是否具有 behavior | -| triggerEvent | 是 | String name, Object detail, Object options| 触发事件 | -| createSelectorQuery| 否 | | 输出 RN 暂不支持，未来支持，建议使用 ref | -| createIntersectionObserver| 否 | | 输出 RN 暂不支持 | -| selectComponent | 否 | String selector | 输出 RN 暂不支持，未来支持，建议使用 ref | -| selectAllComponents| 否 | String selector | 输出 RN 暂不支持，未来支持，建议使用 ref | -| selectOwnerComponent| 否 | | 输出 RN 不支持 | -| getRelationNodes | 否 | String relationKey | 输出 RN 不支持 | -| groupSetData | 否 | Function callback | 输出 RN 不支持 | -| getTabBar | 否 | | 输出 RN 不支持 | -| getPageId | 否 | | 输出 RN 不支持 | -| animate | 否 | String selector, Array keyframes, ... | 输出 RN 不支持 | -| clearAnimation | 否 | String selector, Object options, ... | 输出 RN 不支持 | - -Mpx 框架增强实例方法 - -| 方法名 | RN是否支持 | 描述 | -|---------------------|--------|-----------------------------------------------------| -| $set | 是 | 向响应式对象中添加一个 property，并确保这个新 property 同样是响应式的，且触发视图更新 | -| $watch | 是 | 观察 Mpx 实例上的一个表达式或者一个函数计算结果的变化 | -| $delete | 是 | 删除对象属性，如果该对象是响应式的，那么该方法可以触发观察器更新（视图更新 | watch回调） | -| $refs | 是 | 一个对象，持有注册过 ref的所有 DOM 元素和组件实例，调用响应的组件方法或者获取视图节点信息。 | -| $asyncRefs | 否 | 输出 RN 不支持 | -| $forceUpdate | 是 | 用于强制刷新视图，不常用，通常建议使用响应式数据驱动视图更新 | -| $nextTick | 是 | 在下次 DOM 更新循环结束之后执行延迟回调函数，用于等待 Mpx 完成状态更新和 DOM 更新后再执行某些操作 | -| $i18n | 否 | 输出 RN 暂不支持，国际化功能访问器，用于获取多语言字符串资源 | -| $rawOptions | 是 | 访问组件原始选项对象 | diff --git a/docs-vuepress/rn-style.md b/docs-vuepress/rn-style.md deleted file mode 100644 index e9a5c5ffbd..0000000000 --- a/docs-vuepress/rn-style.md +++ /dev/null @@ -1,706 +0,0 @@ -# Mpx转RN样式使用指南 -RN 的样式的支持基本为 web 样式的一个子集，同时还有一些属性并未与 web 对齐，因此跨平台输出 RN 时，为了保障多端输出样式一致，可参考本文针对样式在RN上的支持情况来进行样式编写。 - -## 样式编写限制 - -### 选择器 -RN 环境下仅支持以下类名选择器，不支持逗号之外的组合选择器。 -``` css -/* 支持 */ -.classname { - color: red -} -.classA, .classB { - color: red -} -``` - -### 布局 -在 RN 中布局方式有限制，像 block inline inline-block 和 fixed 等都不支持，支持的布局方式如下： -#### flex -在RN中，常规的组件元素可以用过 flex 布局来实现，[参考文档](https://reactnative.dev/docs/layout-props#flex)。 - -**注**：RN中view标签的主轴是column，和css不一致，使用mpx开发设置`dispay:flex`时，会默认的主轴方向是row。 - -#### relative/absolute -在 RN 中 position 仅支持 relative（默认）和 absolute，可[参考文档](https://reactnative.dev/docs/layout-props#position)。 - -### 样式单位 -#### number 类型值 -RN 环境中，number 数值型单位支持 px rpx % 三种，web 下的 vw em rem 等不支持。 -#### color 类型值 -RN 环境支持大部分 css 中 color 定义方式，仅少量不支持，详情参考 RN 文档 https://reactnative.dev/docs/colors - -## 组件样式规则 -在web和RN下组件的渲染会存在一些差异的地方，比如默认样式不一致、继承的关系不一致等。框架针对这些不一致进行了抹平工作，但是仍旧存在一些使用限制，具体参考以下组件节点的介绍。 - -### text -RN中，文本节点需要通过Text组件来创建文本节点。文本节点需要给Text组件来设定[属性](https://reactnative.dev/docs/text-style-props)来调整文本的外观。 - -Web/小程序中，文本节点可以通过div/view节点进行直接包裹，在div/view标签上设定对应文本样式即可。不需单独包裹text节点。 - -框架抹平了此部分的差异，但仍因受限于RN内text的样式[继承原则的限制](https://reactnative.dev/docs/text#limited-style-inheritance)，通过在祖先节点来设置文本节点的样式仍旧无法生效。具体例子说明如下 - -``` html - - 我是文本 - - -.wrapper { - font-size: 20px; -} -.content { - text-align: right; -} -/** 以上例子中 -web渲染效果: 字体的大小为20px，文字居右 -转RN之后渲染效果: 字体大小为默认大小，文字居右 -*/ - -``` -**限制与使用说明** -1. 无法通过设置祖先节点的样式来修改文本节点的样式，只可通过修改直接包裹文本的节点来修改文本的样式。 -2. 框架处理将文本节点样式的默认值与web进行了对齐，如果需要按照RN的默认值来进行渲染，可设置`disable-default-style`为`true` - -### view - -background、background-image、background-size、background-repeat仅在view标签下支持，background-color在其他标签上也支持。 - -**各属性支持的类型** - -* background - 仅支持 background-image | background-color | background-size | background-repeat，每个属性支持情况，可参考下面的介绍。 -* background-image - 仅支持 。 -* background-size - 支持px|rpx|%，也支持枚举值 contain|cover|auto； 不支持两个以上的值进行设置。 -* backgroundno-repeat - 仅支持值为no-repeat。 -* backfround-color - 参考[Color](https://reactnative.dev/docs/colors) - - -**支持的语法** - -``` css - -/** 1. background **/ -/* 支持 */ -background: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg") pink contain no-repeat; -background: #000; -background: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg") pink; - -/* 不支持 */ -background: linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)); - - -/** 2. background-image **/ -/* 支持 */ -background-image: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg"); -/* 不支持 */ -background-image: linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)); - - -/** 3. background-size **/ -/* 支持 */ -background-size: 50%; -background-size: 50% 25%; -background-size: contain; -background-size: cover; -background-size: auto; -background-size: 20px auto; - -/ * 不支持 * / -background-size: 50%, 25%, 25%; - - -/** 4. background-repeat **/ -/* 支持 */ -background-repeat: no-repeat; - -/* 不支持 */ -background-repeat: repeat; - - -/** 5. background-color **/ -background-repeat: red; -``` - -## 样式参考 -### Layout Style -#### position -设置元素的定位样式 -**值支持类型** -enum: absolute, relative， 默认relative。 -##### 语法 -``` css -position: absolute; -position: relative; - -``` -#### top|right|left|bottom -设置元素的不同方向的偏移量 -##### 值支持类型 -number: px,rpx,% -##### 语法 -``` css -top: 10px; -top: 10rpx; -top: 10%; -``` -#### z-index -控制着元素的堆叠覆盖顺序。 -##### 值支持类型 -number -##### 语法 -``` css -z-index: 1; -``` -#### display -设置元素的布局方式。 -##### 值支持类型 -flex/none -##### 语法 -``` css -/* 默认 */ -display:flex -/* 隐藏 */ -display:none -``` -#### align-content -设置多根轴线的对齐方式。 -##### 值支持类型 -enum: flex-start, flex-end, center, stretch, space-between, space-around, space-evenly -##### 语法 -``` css -/** 支持 **/ -align-content: flex-start; -align-content: flex-end; -align-content: center; -align-content: stretch; -align-content: space-between; -align-content: space-around; -align-content: space-evenly; - -/** 不支持 **/ -align-content: safe center; -align-content: unsafe center; -``` -#### align-items -设置单根轴线上的子元素的对齐方式。默认会是交叉轴上的。 -##### 值支持类型 -enum: flex-start, flex-end, center, stretch, baseline -##### 语法 -``` css -/** 支持 **/ -align-items: flex-start; -align-items: flex-end; -align-items: center; -align-items: stretch; -align-items: baseline; - -/** 不支持 **/ -align-items: first baseline; -align-items: last baseline; -``` -#### align-self -设置单个子元素在单根轴线上的对齐方式 -##### 值支持类型 -enum: auto, flex-start, flex-end, center, stretch, baseline -##### 语法 -``` css -/** 支持 **/ -align-self: auto; -align-self: flex-start; -align-self: flex-end; -align-self: center; -align-self: stretch; -align-self: baseline; - -/** 不支持 **/ -align-self: first baseline; -align-self: last baseline; -``` -#### flex -仅支持 flex-grow | flex-shrink | flex-basis 这种顺序，值以空格分隔按顺序赋值 -##### 值支持类型 -flex: number number px/rpx -##### 语法 -``` css -/** 简写 **/ -flex: 1; -/* flex-grow | flex-shrink | flex-basis */ -flex: 0 1 1; -``` -#### flex-grow -设置子盒子的放大比例 -##### 值支持类型 -number -##### 语法 -```css -flex-grow: 1; -``` -#### flex-shrink -设置子盒子的缩放比例。 -##### 值支持类型 -number -##### 语法 -```css -flex-shrink: 1; -``` -#### flex-basis -设置在分配多余空间之前，子盒子的初始主轴尺寸。 -##### 值支持类型 -number px|rpx|% -##### 语法 -``` css -flex-shrink: 10px; -flex-shrink: 10rpx; -flex-shrink: 20%; -``` -#### flex-direction -设置主轴的方向。 -##### 值支持类型 -enum: row, row-reverse, column, column-reverse -##### 语法 -``` css -flex-direction: row; -flex-direction: row-reverse; -flex-direction: column; -flex-direction: column-reverse; - -``` -#### flex-wrap -设置元素是否换行。当值为wrap时，alignItems：center不生效。 -##### 值支持类型 -enum: wrap, nowrap, wrap-reverse -##### 语法 -``` css -flex-wrap: wrap; -flex-wrap: nowrap; -flex-wrap: wrap-reverse; -``` -#### flex-flow -是flex-direction flex-wrap 缩写，仅支持 flex-flow: flex-direction flex-wrap 这种顺序，值以空格分隔按顺序赋值 -```css -/* flex-direction */ -flex-flow: row; -/* flex-direction| flex-wrap*/ -flex-flow: row nowrap; -``` - -### View Style -#### margin -margin 是 margin-top|margin-right|margin-left|margin-bottom 的缩写模式, 目前仅支持四种缩写模式。 -##### 值支持类型 -string: 'auto' -number: rpx，px, % -##### 语法 -``` css -/* all */ -margin: 2px; - -/* top and bottom | left and right */ -margin: 5% auto; - -/* top | left and right | bottom */ -margin: 1rpx auto 2rpx; - -/* top | right | bottom | left */ -margin: 1rpx 2rpx 2rpx ; -``` -#### margin-top|margin-bottom|margin-right|margin-left -##### 值支持类型 -number: rpx，px, % -##### 语法 -``` css -margin-top: 2px; -margin-top: 2rpx; -margin-top: 10%; -``` -#### padding -padding是padding-left、padding-right、padding-left、padding-bottom的缩写模式, 目前仅支持四种缩写模式。 -##### 值支持类型 -string: 'auto' -number: rpx，px, % -##### 语法 -``` css -/* all */ -padding: 2px; - -/* top and bottom | left and right */ -padding: 5% 10%; - -/* top | left and right | bottom */ -padding: 1rpx 0 2rpx; - -/* top | right | bottom | left */ -padding: 1rpx 2rpx 2rpx ; -``` -#### padding-top|padding-bottom|padding-left|padding-right -##### 值支持类型 -number: rpx，px, % -##### 语法 -``` css -/** padding-top **/ -padding-top: 2px; -padding-top: 2rpx; -padding-top: 10%; -``` -#### border -border 是 border-width|border-style|border-color 的缩写模式, 目前仅支持 width | style | color 这种排序，值以空格分隔按顺序赋值 -```css -/* width | style | color */ -border: 1px solid red; -border: 1px; -border: 1px solid; -border: 1px double pink; -``` -#### border-color -设置边框的颜色, 目前只支持统一设置，不支持缩写。 -##### 值支持类型 -color: 参考[Color](https://reactnative.dev/docs/colors) -##### 语法 -``` css -/* all border */ -/** 支持 **/ -border-color: red; -``` -#### border-style -设置边框的样式, 目前只支持统一设置，不支持缩写。 -##### 值支持类型 -enum: solid|dotted|dashed -##### 语法 -``` css -/** 支持 **/ -/* all border */ -border-color: 'solid'; -border-color: 'dotted'; -border-color: 'dashed'; - -/** 不支持 **/ -border-style: double; -border-style: groove; -border-style: ridge; -border-style: dotted solid; -border-style: hidden double dashed; -border-style: none solid dotted dashed; -``` -#### border-width -设置边框的宽度，目前只支持统一设置，不支持缩写。 -##### 值支持类型 -number: px rpx % -##### 语法 -``` css -/* all border */ -border-width: 2px; -``` -#### border-top-color|border-bottom-color|border-left-color|border-right-color -设置各边框的颜色 -##### 值支持类型 -color: 参考[Color](https://reactnative.dev/docs/colors) -##### 语法 -``` css -border-top-color: red; -``` -#### border-top-width|border-bottom-width|border-left-width|border-right-width -设置各边框的宽度 -##### 值支持类型 -number: px rpx -##### 语法 -``` css -border-top-width: 2px; -``` -#### border-radius -设置border的圆角格式，支持一种缩写方式 -##### 值支持类型 -仅支持 border-radius 0px|border-radius 0px 0px 0px 0px（值以空格分隔按顺序赋值） -number: px rpx % -##### 语法 -``` css -/* all */ -border-radius: 2px; -/* top-left | top-right | bottom-right | bottom-left */ -border-radius: 10px 10px 10px 0; -``` -#### border-bottom-left-radius|border-bottom-right-radius|border-top-left-radius|border-top-right-radius -##### 值支持类型 -number: px rpx % -##### 语法 -``` css -border-bottom-left-radius: 2px; -``` - -### Text Style -#### color -##### 值支持类型 -color: 参考[Color](https://reactnative.dev/docs/colors) -##### 语法 -``` css -color: orange; -color: #fff; -color: #fafafa; -color: rgb(255, 255, 255); -color: rgba(255, 99, 71, 0.2) -``` -#### font-family -可设置系统字体，引入字体文件，暂时不支持。 -##### 值支持类型 -string -##### 语法 -``` css -font-family: "PingFangSC-Regular" -``` -#### font-size -可设置字体的大小 -##### 值支持类型 -number: px,rpx -##### 语法 -``` css -font-size: 12px; -font-size: 12rpx; -``` -#### font-style -设置文本的字体样式。 -##### 值支持类型 -enum: normal，italic -##### 语法 -``` css -font-style: italic; -font-style: normal; -``` -#### font-weight -设置文字的权重。 -##### 值支持类型 -enum: 100，200，300，400，500，600，800，900,normal,bold -##### 语法 -``` css -font-weight: 100; -font-weight: 200; -font-weight: 300; -font-weight: 400; -font-weight: 500; -font-weight: 600; -font-weight: 700; -font-weight: 800; -font-weight: 900; - -font-weight: normal; -font-weight: bold; -``` -#### font-variant -设置文本的字体变体 -##### 值支持类型 -enum: small-caps, oldstyle-nums, lining-nums, tabular-nums, proportional-nums -##### 语法 -``` css -font-variant: small-caps; -font-variant: oldstyle-nums; -font-variant: lining-nums; -font-variant: tabular-nums; -font-variant: lining-nums; -font-variant: proportional-nums; -``` -#### letter-spacing -定义字符之间的间距 -##### 值支持类型 -px,rpx -##### 语法 -``` css -letter-spacing: 2px; -letter-spacing: 2rpx; -``` -#### line-height -设置行高。 -##### 值支持类型 -px,rpx,% -##### 语法 -``` css -line-height: 16px -line-height: 16rpx -line-height: 100% -line-height: 1 -``` -#### text-align -设置文本的水平对齐方式。 -##### 值支持类型 -enum: left, right, center, justify -##### 语法 -``` css -/** 支持 **/ -text-align: left; -text-align: right; -text-align: center; -text-align: justify; - -/** 不支持 **/ -text-align: match-parent; -text-align: auto; -text-align: justify-all; -``` -#### text-decoration-line -设置文本的装饰线样式。 -##### 值支持类型 -enum: none, underline, line-through, underline line-through -##### 语法 -``` css -/** 支持 **/ -text-decoration-line: none; -text-decoration-line: underline; -text-decoration-line: line-through; -text-decoration-line: underline line-through; - -/** 不支持 **/ -text-decoration-line: overline; -``` -#### text-transform -设置文本的大小写转换。 -##### 值支持类型 - enum: none, uppercase, lowercase, capitalize -##### 语法 -``` css -/** 支持 **/ -text-transform: none; -text-transform: uppercase; -text-transform: lowercase; -text-transform: capitalize; - -/** 不支持 **/ -text-transform: none; -text-transform: uppercase; -text-transform: lowercase; -text-transform: capitalize; -``` -#### text-shadow -设置文本阴影 -##### 值支持类型 -仅支持 offset-x | offset-y | blur-radius | color 排序，值以空格分隔按顺序赋值 -##### 语法 -```css -text-shadow: 1rpx 3rpx 0 #2E0C02; -``` - -### Background Style -背景相关的属性 -#### background-color -表示背景色，可以在任何标签上使用。 -##### 值支持类型 -color: 参考[Color](https://reactnative.dev/docs/colors) -##### 语法 -``` css -/* all border */ -background-color: red; -``` -#### background-image -表示背景图，只能在view上使用 -##### 值支持类型 -仅支持 -##### 语法 -``` css -background-image: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg"); - -/* 不支持 */ -background-image: linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)); -``` -#### background-size -表示背景大小，只能在view上使用 -##### 值支持类型 -number 支持 px|rpx|%，枚举值支持 contain|cover|auto； -支持一个值:这个值指定图片的宽度，图片的高度隐式的为 auto； -支持两个值:第一个值指定图片的宽度，第二个值指定图片的高度； -不支持逗号分隔的多个值：设置多重背景!!! -##### 语法 -``` css -/* 支持 */ -background-size: 50%; -background-size: 50% 25%; -background-size: contain; -background-size: cover; -background-size: auto; -background-size: 20px auto; - -/ * 不支持 * / -background-size: 50%, 25%, 25%; -``` -#### background-repeat -表示背景图是否重复，只能在view上使用 -##### 值支持类型 -enum: no-repeat -##### 语法 -``` css -background-repeat: no-repeat; - -/* 不支持 */ -background-repeat: repeat; -``` -#### background -表示背景的组合属性，只能在view上使用 -##### 值支持类型 -仅支持 background-image | background-color | background-size | background-repeat，具体每个属性的支持情况参见上面具体属性支持的文档 -##### 语法 -```css -/* 支持 */ -background: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg") pink no-repeat; -background: #000; -background: url("https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg") pink; - -/* 不支持 */ -background: linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)); -``` - -### Shadow Style -#### box-shadow -此属性是阴影颜色、阴影的偏移量 -##### 值支持类型 -仅支持 offset-x | offset-y | blur-radius | color 排序，值以空格分隔按顺序赋值 -##### 语法 -```css -/* offset-x | offset-y | blur-radius | color */ -box-shadow: 0 1px 3px rgba(139,0,0,0.32); -``` - -## 附录 -### RN 不支持的属性 -若设置以下不支持的属性会被 mpx 编译处理时丢弃，有编译 error 提示 - -| 描述 | 不支持的属性 | -| -------------- | --------------------------------------------------------------------------------------| -| 双端都不支持 | box-sizing white-space text-overflow animation transition | -| ios 不支持 | vertical-align | -| android 不支持 | text-decoration-style text-decoration-color shadow-offset shadow-opacity shadow-radius | - - -### RN 支持的枚举值 -RN 支持的枚举值映射如下表，其他不支持的枚举值会被 mpx 编译处理时丢弃，设置无效 - -|prop|value 枚举| -| --- | --- | -|overflow|visible hidden scroll| -|border-style|solid dotted dashed| -|display|flex none| -|pointer-events|auto none| -|position|relative absolute| -|vertical-align|auto top bottom center| -|font-variant|small-caps oldstyle-nums lining-nums tabular-nums proportional-nums -|text-align|left right center justify| -|font-style|normal italic| -|font-weight|normal bold 100-900| -|text-decoration-line|none underline line-through 'underline line-through'| -|text-transform|none uppercase lowercase capitalize| -|user-select|auto text none contain all| -|align-content|flex-start flex-end none center stretch space-between space-around| -|align-items|flex-start flex-end center stretch baseline| -|align-self|auto flex-start flex-end center stretch baseline| -|justify-content|flex-start flex-end center space-between space-around space-evenly none| -|background-repeat|no-repeat| - -### 缩写支持 -RN 仅支持部分常用的缩写形式，具体参加下表： - -|缩写属性|支持的缩写格式|备注| -| --- | --- | --- | -|text-decoration|仅支持 text-decoration-line text-decoration-style text-decoration-color|顺序固定，值以空格分隔后按按顺序赋值| -|margin|margin: 0;margin: 0 auto;margin: 0 auto 10px;margin: 0 10px 10px 20px;|-| -|padding|padding: 0;padding: 0 auto;padding: 0 auto 10px;padding: 0 10px 10px 20px;|-| -|text-shadow|仅支持 offset-x offset-y blur-radius color 排序|顺序固定，值以空格分隔后按按顺序赋值| -|border|仅支持 border-width border-style border-color|顺序固定，值以空格分隔后按按顺序赋值| -|box-shadow|仅支持 offset-x offset-y blur-radius color|顺序固定，值以空格分隔后按按顺序赋值| -|flex|仅支持 flex-grow flex-shrink flex-basis|顺序固定，值以空格分隔后按按顺序赋值| -|flex-flow|仅支持 flex-direction flex-wrap|顺序固定，值以空格分隔后按按顺序赋值| -|border-radius|支持 border-top-left-radius border-top-right-radius border-bottom-right-radius border-bottom-left-radius|顺序固定，值以空格分隔后按按顺序赋值；当设置 border-radius: 0 相当于同时设置了4个方向| -|background|仅支持 background-image background-color background-repeat|顺序不固定，具体每个属性的支持情况参见上面具体属性支持的文档； diff --git a/docs-vuepress/rn-template.md b/docs-vuepress/rn-template.md deleted file mode 100644 index 0994f39b68..0000000000 --- a/docs-vuepress/rn-template.md +++ /dev/null @@ -1,617 +0,0 @@ -# Mpx转RN模版使用指南 - -## 模版指令 -目前 Mpx 输出 React Native 仅支持以下指令，具体使用范围可参考如下文档 - -| 指令名 | 说明 | -| --------- | ---------------------------------- | -| wx:if | 根据表达式的值的来有条件地渲染元素 | -| wx:elif | 根据表达式的值的来有条件地渲染元素，前一兄弟元素必须有 wx:if 或 wx:elif | -| wx:else | 不需要表达式，前一兄弟元素必须有 wx:if 或 wx:elif | -| wx:show | 根据表达式的值的来有条件地渲染元素，与 wx:if 所不同的是不会移除节点，而是设置节点的 style 为 display: none | -| wx:style | 动态绑定 style 样式 | -| wx:class | 动态绑定 class 样式 | -| wx:for | 在组件上使用 wx:for 绑定一个数组，即可使数组中各项的数据重复渲染该组件 | -| wx:for-item | 指定数组当前元素的变量名 | -| wx:for-index | 指定数组当前下标的变量名 | -| wx:key | 指定列表中项目的唯一的标识符 | -| wx:ref | 获取节点信息 | -| mpxTagName | 动态转换标签 | -| component | 使用 component is 动态切换组件 | -| @mode | 使用 @ 符号来指定某个节点或属性只在某些平台下有效 | -| @_mode | 隐式属性条件编译，仅控制节点的展示，保留节点属性的平台转换能力 | -| @env | 自定义 env 目标应用，来实现在不同应用下编译产出不同的代码 | - -## 事件编写 -目前 Mpx 输出 React Native 的事件编写遵循小程序的事件编写规范，支持事件的冒泡及捕获 - -普通事件绑定 -```js - - Click here! - -``` - -绑定并阻止事件冒泡 -```js - - Click here! - -``` - -事件捕获 - -```js - - outer view - - inner view - - -``` - -中断捕获阶段和取消冒泡阶段 - -```js - - outer view - - -``` - -在此基础上也新增了事件处理内联传参的增强机制。 - -```html - - -``` - -除此之外，Mpx 也支持了动态事件绑定 - -```html - - -``` -注意事项： - -当同一个元素上同时绑定了 catchtap 和 bindtap 事件时: - -两个事件都会被触发执行。 -但是是否阻止事件冒泡的行为,会以模板上第一个绑定的事件标识符为准。 -如果第一个绑定的是 catchtap，那么不管后面绑定的是什么,都会阻止事件冒泡。 -如果第一个绑定的是 bindtap，则不会阻止事件冒泡。 - -同理,如果同一个元素上绑定了 capture-bind:tap 和 bindtap: - -事件的执行时机会根据模板上第一个绑定事件的标识符来决定: -如果第一个绑定的是 capture-bind:tap，则事件会在捕获阶段触发。 -如果第一个绑定的是 bindtap，则事件会在冒泡阶段触发。 - -## 基础组件 - -目前 Mpx 输出 React Native 仅支持以下组件，具体使用范围可参考如下文档 - -### view -视图容器。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| hover-class | string | | 指定按下去的样式类。 | -| hover-start-time | number | 50 | 按住后多久出现点击态，单位毫秒| -| hover-stay-time | number | 400 | 手指松开后点击态保留时间，单位毫秒 | -| enable-offset | Number | false | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - -事件 - -| 事件名 | 说明 | -| ----------------| --------------------------------------------------- | -| bindtap | 点击的时候触发 | - - -### text -文本。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| user-select | boolean | `false` | 文本是否可选。 | -| disable-default-style | boolean | `false` | 会内置默认样式，比如fontSize为16。设置`true`可以禁止默认的内置样式。 | -| enable-offset | Number | false | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - - -事件 - - -| 事件名 | 说明 | -| ----------------| --------------------------------------------------- | -| bindtap | 点击的时候触发 | - -注意事项 -1. 未包裹 text 标签的文本，会自动包裹 text 标签。 -2. text 组件开启 enable-offset 后，offsetLeft、offsetWidth 获取时机仅为组件首次渲染阶段 - -### image -图片。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| src | String | `false` | 图片资源地址，支持本地图片资源及 base64 格式数据，暂不支持 svg 格式 | -| mode | String | `scaleToFill` | 图片裁剪、缩放的模式，适配微信 image 所有 mode 格式 | -| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - -事件 - -| 事件名 | 说明 | -| ----------------| --------------------------------------------------- | -| binderror | 当错误发生时触发，event.detail = { errMsg } | -| bindload | 当图片载入完毕时触发，event.detail = { height, width } | - -注意事项 - -1. image 组件默认宽度320px、高度240px -2. image 组件进行缩放时，计算出来的宽高可能带有小数，在不同webview内核下渲染可能会被抹去小数部分 - -### input -输入框。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| value | String | | 输入框的初始内容 | -| type | String | `text` | input 的类型，不支持 `safe-password`、`nickname` | -| password | Boolean | `false` | 是否是密码类型 | -| placeholder | String | | 输入框为空时占位符 | -| placeholder-class | String | | 指定 placeholder 的样式类，仅支持 color 属性 | -| placeholder-style | String | | 指定 placeholder 的样式，仅支持 color 属性 | -| disabled | Boolean | `false` | 是否禁用 | -| maxlength | Number | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 | -| auto-focus | Boolean | `false` | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘 | -| focus | Boolean | `false` | 获取焦点 | -| confirm-type | String | `done` | 设置键盘右下角按钮的文字，仅在 type='text' 时生效 | -| confirm-hold | Boolean | `false` | 点击键盘右下角按钮时是否保持键盘不收起 | -| cursor | Number | | 指定 focus 时的光标位置 | -| cursor-color | String | | 光标颜色 | -| selection-start | Number | `-1` | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用 | -| selection-end | Number | `-1` | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用 | -| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - -事件 - -| 事件名 | 说明 | -| ---------------------| ---------------------------------------------------------------------------------- | -| bindinput | 键盘输入时触发，event.detail = { value, cursor }，不支持 `keyCode` | -| bindfocus | 输入框聚焦时触发，event.detail = { value }，不支持 `height` | -| bindblur | 输入框失去焦点时触发，event.detail = { value }，不支持 `encryptedValue`、`encryptError` | -| bindconfirm | 点击完成按钮时触发，event.detail = { value } | -| bind:selectionchange | 选区改变事件, event.detail = { selectionStart, selectionEnd } | - -方法 - -可通过 `ref` 方式调用以下组件实例方法 - -| 方法名 | 说明 | -| ---------------------| ----------------------------------- | -| focus | 使输入框得到焦点 | -| blur | 使输入框失去焦点 | -| clear | 清空输入框的内容 | -| isFocused | 返回值表明当前输入框是否获得了焦点 | - - -### textarea -多行输入框。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| value | String | | 输入框内容 | -| type | String | `text` | input 的类型，不支持 `safe-password`、`nickname` | -| placeholder | String | | 输入框为空时占位符 | -| placeholder-class | String | | 指定 placeholder 的样式类，仅支持 color 属性 | -| placeholder-style | String | | 指定 placeholder 的样式，仅支持 color 属性 | -| disabled | Boolean | `false` | 是否禁用 | -| maxlength | Number | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 | -| auto-focus | Boolean | `false` | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘 | -| focus | Boolean | `false` | 获取焦点 | -| auto-height | Boolean | `false` | 是否自动增高，设置 auto-height 时，style.height不生效 | -| confirm-type | String | `done` | 设置键盘右下角按钮的文字，不支持 `return` | -| confirm-hold | Boolean | `false` | 点击键盘右下角按钮时是否保持键盘不收起 | -| cursor | Number | | 指定 focus 时的光标位置 | -| cursor-color | String | | 光标颜色 | -| selection-start | Number | `-1` | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用 | -| selection-end | Number | `-1` | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用 | -| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - -事件 - -| 事件名 | 说明 | -| ---------------------| ---------------------------------------------------------------------------------- | -| bindinput | 键盘输入时触发，event.detail = { value, cursor }，不支持 `keyCode` | -| bindfocus | 输入框聚焦时触发，event.detail = { value }，不支持 `height` | -| bindblur | 输入框失去焦点时触发，event.detail = { value }，不支持 `encryptedValue`、`encryptError` | -| bindconfirm | 点击完成按钮时触发，event.detail = { value } | -| bindlinechange | 输入框行数变化时调用，event.detail = { height: 0, lineCount: 0 }，不支持 `heightRpx` | -| bind:selectionchange | 选区改变事件, {selectionStart, selectionEnd} | - -方法 - -可通过 `ref` 方式调用以下组件实例方法 - -| 方法名 | 说明 | -| ---------------------| ----------------------------------- | -| focus | 使输入框得到焦点 | -| blur | 使输入框失去焦点 | -| clear | 清空输入框的内容 | -| isFocused | 返回值表明当前输入框是否获得了焦点 | - - -### button -按钮。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | --------------------------------------------------------- | -| size | String | `default` | 按钮的大小 | -| type | String | `default` | 按钮的样式类型 | -| plain | Boolean | `false` | 按钮是否镂空，背景色透明 | -| disabled | Boolean | `false` | 是否禁用 | -| loading | Boolean | `false` | 名称前是否带 loading 图标 | -| open-type | String | | 微信开放能力，当前仅支持 `share` | -| hover-class | String | | 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果 | -| hover-start-time | Number | `20` | 按住后多久出现点击态，单位毫秒 | -| hover-stay-time | Number | `70` | 手指松开后点击态保留时间，单位毫秒 | -| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - - -### scroll-view -可滚动视图区域。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | --------- | -------------------------------------------------- | -| scroll-x | Boolean | `false` | 允许横向滚动动 | -| scroll-y | Boolean | `false` | 允许纵向滚动 | -| upper-threshold | Number | `50` | 距顶部/左边多远时(单位 px),触发 scrolltoupper 事件 | -| lower-threshold | Number | `50` | 距底部/右边多远时(单位 px),触发 scrolltolower 事件 | -| scroll-top | Number | `0` | 设置纵向滚动条位置 | -| scroll-left | Number | `0` | 设置横向滚动条位置 | -| scroll-with-animation | Boolean | `false` | 在设置滚动条位置时使用动画过渡 | -| enable-back-to-top | Boolean | `false` | 点击状态栏的时候视图会滚动到顶部 | -| enhanced | Boolean | `false` | scroll-view 组件功能增强 | -| refresher-enabled | Boolean | `false` | 开启自定义下拉刷新 | -| scroll-anchoring | Boolean | `false` | 开启滚动区域滚动锚点 | -| refresher-default-style | String | `'black'` | 设置下拉刷新默认样式,支持 `black`、`white`、`none`，仅安卓支持 | -| refresher-background | String | `'#fff'` | 设置自定义下拉刷新背景颜色，仅安卓支持 | -| refresher-triggered | Boolean | `false` | 设置当前下拉刷新状态,true 表示已触发 | -| paging-enabled | Number | `false` | 分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置 | -| show-scrollbar | Number | `true` | 滚动条显隐控制 (同时开启 enhanced 属性后生效)| -| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - - -事件 - -| 事件名 | 说明 | -| ----------------| ------------------ | -| binddragstart| 滑动开始事件，同时开启 enhanced 属性后生效| -| binddragging| 滑动事件，同时开启 enhanced 属性后生效 | -| binddragend| 滑动结束事件，同时开启 enhanced 属性后生效 | -| bindscrolltoupper | 滚动到顶部/左边触发 | -| bindscrolltolower | 滚动到底部/右边触发 | -| bindscroll | 滚动时触发 | -| bindrefresherrefresh| 自定义下拉刷新被触发 | - -注意事项 - -1. 目前不支持自定义下拉刷新节点，使用 slot="refresher" 声明无效，在 React Native 环境中还是会被当作普通节点渲染出来 - -### swiper -滑块视图容器。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------------ | ------------------------------------| -| indicator-dots | Boolean | `false` | 是否显示面板指示点 | -| indicator-color | color | `rgba(0, 0, 0, .3)` | 指示点颜色 | -| indicator-active-color | color | `#000000` | 当前选中的指示点颜色 | -| autoplay | Boolean | `false` | 是否自动切换 | -| current | Number | `0` | 当前所在滑块的 index | -| interval | Number | `5000` | 自动切换时间间隔 | -| duration | Number | `500` | 滑动动画时长 | -| circular | Boolean | `false` | 是否采用衔接滑动 | -| vertical | Boolean | `false` | 滑动方向是否为纵向 | -| previous-margin | String | `0` | 前边距，可用于露出前一项的一小部分，接受px | -| next-margin | String | `0` | 后边距，可用于露出后一项的一小部分，接受px | -| enable-offset | Number | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息| - - -事件 - -| 事件名 | 说明 | -| ----------------| ------------------ | -| bindchange| current 改变时会触发 change 事件，event.detail = {current, source}| - -### swiper-item -1. 仅可放置在swiper组件中，宽高自动设置为100%。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------------ | ------------------------------------| -| item-id | string | `无` | 该 swiper-item 的标识符 | - - -### checkbox -多选项目 - - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| value | String | | checkbox 标识，选中时触发 checkbox-group 的 change 事件，并携带 checkbox 的 value | -| disabled | Boolean | false | 是否禁用 | -| checked | Boolean | false | 当前是否选中，可用来设置默认选中 | -| color | String | #09BB07 | checkbox的颜色，同css的color | - - -### checkbox-group -多项选择器，内部由多个checkbox组成。 - - -事件 - -| 事件名 | 说明 | -| ----------------| ------------------ | -| bindchange | checkbox-group 中选中项发生改变时触发 change 事件，detail = { value: [ 选中的 checkbox 的 value 的数组 ] } | - - -### radio -单选项目 - - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| value | String | | radio 标识，当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value | -| disabled | Boolean | false | 是否禁用 | -| checked | Boolean | false | 当前是否选中，可用来设置默认选中 | -| color | String | #09BB07 | checkbox 的颜色，同 css 的 color | - - -### radio-group -单项选择器，内部由多个 radio 组成 - - -事件 - -| 事件名 | 说明 | -| ----------------| ------------------ | -| bindchange | radio-group 中选中项发生改变时触发 change 事件，detail = { value: [ 选中的 radio 的 value 的数组 ] } | - - -### label -用来改进表单组件的可用性 - - -注意事项 - -1. 当前不支持使用 for 属性找到对应 id，仅支持将控件放在该标签内，目前可以绑定的空间有：checkbox、radio、switch。 - - -### icon -图标组件 - - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------- | ------------- | ---------------------------------------------------------- | -| type | String | | icon 的类型，有效值：success、success_no_circle、info、warn、waiting、cancel、download、search、clear | -| size | String \| Number | 23 | icon 的大小 | -| color | String | | icon 的颜色，同 css 的 color | - - -### movable-area -movable-view的可移动区域。 - -注意事项 - -1. movable-area不支持设置 scale-area，缩放手势生效区域仅在 movable-view 内 - -### movable-view -可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。 - - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ------ | ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | -| direction | String | none | 目前支持 all、vertical、horizontal、none｜ -| x | Number | | 定义x轴方向的偏移 | -| y | Number | | 定义y轴方向的偏移 | -|friction | Number | 7 | 摩擦系数 | -|disabled | boolean | false | 是否禁用 | -|scale | boolean | false | 是否支持双指缩放 | -|scale-min | Number | 0.1 | 定义缩放倍数最小值 | -|scale-max | Number | 10 | 定义缩放倍数最大值 | -|scale-value | Number | 1 | 定义缩放倍数，取值范围为 0.1 - 10 | - -事件 - -| 事件名 | 说明 | -| -------------------- | ------------------------------------------ | -| bindchange | 拖动过程中触发的事件，event.detail = {x, y, source} | -| bindscale | 缩放过程中触发的事件，event.detail = {x, y, scale} | -| htouchmove | 初次手指触摸后移动为横向的移动时触发 | -| vtouchmove | 初次手指触摸后移动为纵向的移动时触发 | - -### form -表单。将组件内的用户输入的switch input checkbox slider radio picker 提交。 - -当点击 form 表单中 form-type 为 submit 的 button 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。 - -事件 - -| 事件名 | 说明 | -| ---------- | --------------------------------------------------- | -| bindsubmit | 携带 form 中的数据触发 submit 事件，event.detail = {value : {'name': 'value'} } | -| bindreset | 表单重置时会触发 reset 事件 | - -### cover-view -视图容器。 -功能同 view 组件 - -### cover-image -视图容器。 -功能同 image 组件 -| bindchange | 滚动选择时触发change事件，event.detail = {value}；value为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）| - - -### picker-view -嵌入页面的滚动选择器。其中只可放置 picker-view-column组件，其它节点不会显示 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| ----------------------- | ------------------| ------------------ | ------------------------------------| -| value | Array[number] | `false` | 数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项（下标从 0 开始），数字大于 picker-view-column 可选项长度时，选择最后一项。 | - - -事件 - -| 事件名 | 说明 | -| ----------------| ------------------ | -| bindchange | checkbox-group 中选中项发生改变时触发 change 事件，detail = { value: [ 选中的 checkbox 的 value 的数组 ] } | - -### picker-view-column -滚动选择器子项。仅可放置于picker-view中，其孩子节点的高度会自动设置成与picker-view的选中框的高度一致 - - -### picker -从底部弹起的滚动选择器。 - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| -----------------------| ------------| ------------------ | -----------------------------| -| mode | string | `selector` | 选择器类型 | -| disabled | boolean | `false` | 是否禁用 | - -公共事件 - -| 事件名 | 说明 | -| ----------------| ------------------ | -| bindcancel | 取消选择时触发 | -| bindchange | 滚动选择时触发change事件，event.detail = {value}；value为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）| - -#### 普通选择器：mode = selector - -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| -----------------------| ------------------------| ------------- | -----------------------------| -| range | array[object]/array | `[]` | mode 为 selector 或 multiSelector 时，range 有效 | -| range-key | string | `false` | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 | -| value | number | 0 | 表示选择了 range 中的第几个（下标从 0 开始）| - -#### 多列选择器：mode = multiSelector -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| -----------------------| ------------------------| ------------- | -----------------------------| -| range | array[object]/array | `[]` | mode 为 selector 或 multiSelector 时，range 有效 | -| range-key | string | `false` | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 | -| value | array | `[]` | 表示选择了 range 中的第几个（下标从 0 开始）| -| bindcolumnchange | | | 列改变时触发| - -#### 多列选择器：时间选择器：mode = time -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| -----------------------| ------------------------| ------------- | -----------------------------| -| value | string | `[]` | 表示选中的时间，格式为"hh:mm" | -| start | string | `false` | 表示有效时间范围的开始，字符串格式为"hh:mm" | -| end | string | `[]` | 表示有效时间范围的结束，字符串格式为"hh:mm"| - -#### 多列选择器：时间选择器：mode = date -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| -----------------------| ------------------------| ------------- | ------------------------------------------| -| value | string | `当天` | 表示选中的日期，格式为"YYYY-MM-DD" | -| start | string | `false` | 表示有效日期范围的开始，字符串格式为"YYYY-MM-DD" | -| end | string | `[]` | 表示有效日期范围的结束，字符串格式为"YYYY-MM-DD" | -| fields | string | `day` | 有效值 year,month,day，表示选择器的粒度 | - -#### fields 有效值： -| 属性名 | 说明 | -| -----------------------| ------------------------ | -| year | 选择器粒度为年 | -| month | 选择器粒度为月份 | -| day | 选择器粒度为天 | - -### 省市区选择器：mode = region -属性 - -| 属性名 | 类型 | 默认值 | 说明 | -| -----------------------| ------------------------| ------------- | ------------------------------------------| -| value | array | `[]` | 表示选中的省市区，默认选中每一列的第一个值 | -| custom-item | string | | 可为每一列的顶部添加一个自定义的项 | -| level | string | `region` | 选择器层级 | - -#### level 有效值： -| 属性名 | 说明 | -| -----------------------| ------------------------ | -| province | 选省级选择器 | -| city | 市级选择器 | -| region | 区级选择器 | - - - - - - - diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 5936879785..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# mpx文档 - -该仓库为mpx文档仓库，使用gitbook搭建文档网站。 - -修改文档可直接修改md文件，提交后会自动部署到[github pages](https://didi.github.io/mpx) - -若有较复杂的改动，需本地预览效果需先安装gitbook： `npm i -g gitbook-cli` -安装gitbook插件 `gitbook install` -然后在本目录下 `gitbook serve` diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index 0eb76a928e..0000000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,78 +0,0 @@ -# Summary - -* [Introduction](intro.md) -* [开始](start.md) -* [单文件](single/what-is-single-file.md#单文件) - * [什么是单文件](single/what-is-single-file.md#介绍) - * [编辑器/IDE配置](single/what-is-single-file.md#编辑器ide高亮、提示) -* [template增强特性](single/template-enhance.md#template增强特性) - * [class与style绑定](single/template-enhance.md#class与style绑定) - * [内联事件绑定](single/template-enhance.md#内联事件绑定) - * [动态组件](single/template-enhance.md#动态组件) - * [双向绑定](single/template-enhance.md#双向绑定) - * [获取节点](single/template-enhance.md#refs) -* [script增强特性](single/script-enhance.md#script增强特性) - * [computed](single/script-enhance.md#computed) - * [watch](single/script-enhance.md#watch) - * [mixins](single/script-enhance.md#mixins) - * [lifeCycle](single/script-enhance.md#页面生命周期) -* [style增强特性](single/style-enhance.md#style增强特性) - * [预处理支持](single/style-enhance.md#css预处理器) - * [样式引用](single/style-enhance.md#样式引用) - * [rpx转换](single/style-enhance.md#rpx转换) -* [JSON增强特性](single/json-enhance.md#JSON增强特性) - * [packages](single/json-enhance.md#packages) - * [分包](single/json-enhance.md#分包) - * [自定义tabbar](single/json-enhance.md#自定义tabbar) -* [数据管理](store/index.md#数据管理) - * [开始](store/index.md#开始) - * [state](store/index.md#state) - * [getter](store/index.md#getter) - * [mutation](store/index.md#mutation) - * [action](store/index.md#action) - * [子模块](store/index.md#module) - * [多实例store](store/index.md#多实例) -* [构建配置](compilationEnhance/index.md) - * [自动配置](compilationEnhance/index.md#自动配置) - * [手动配置](compilationEnhance/index.md#手动配置) - * [@mpxjs/webpack-plugin](compilationEnhance/index.md#mpxjswebpack-plugin) - * [MpxWebpackPlugin.loader](compilationEnhance/index.md#mpxwebpackpluginloader) - * [@mpxjs/url-loader](compilationEnhance/index.md#mpxjsurl-loader) - * [output.filename](compilationEnhance/index.md#outputfilename) - * [optimization](compilationEnhance/index.md#optimization) -* [多平台支持](platform.md) - * [多平台支持](platform.md#多平台支持) - * [跨平台编译](platform.md#跨平台编译) - * [跨平台输出web](platform.md#跨平台输出web) -* [TS支持](ts.md) -* [国际化i18n](i18n.md) -* [渐进接入](progressive.md) - - [原生组件支持](progressive.md#原生自定义组件支持) - - [原生page支持](progressive.md#原生page支持) - - [导出原生](progressive.md#导出原生) -* [API参考](api.md) - - [createApp](api.md#createapp) - - [createPage](api.md#createpage) - - [createComponent](api.md#createcomponent) - - [createStore](api.md#createstore) - - [toPureObject](api.md#topureobject) - - [observable](api.md#observable) - - [extendObservable](api.md#extendobservable) - - [watch](api.md#watchcontext-expr-handler) - - [use](api.md#mpxuse) - - [mixin](api.md#mpxmixin) - - [实例API](instance-api.md) -* [拓展能力](extend/index.md) - * [fetch](extend/index.md#fetch) - * [api-proxy](extend/index.md#api-proxy) - * [mock](extend/index.md#mock) -* [mpx运行机制](understanding/understanding.md) - * [数据响应与性能优化](understanding/understanding.md#数据响应与性能优化) - * [编译构建](understanding/understanding.md#编译构建) - * [图像资源处理](understanding/resource.md#图像资源处理) -* [更新记录](https://github.com/didi/mpx/releases) -* [2.0迁移指南](migrate.md) -* [相关文章](articles/index.md) - * [1.0](articles/1.0.md) - * [2.0](articles/2.0.md) - * [mpx使用](articles/mpx1.md) diff --git a/docs/Version2.0.md b/docs/Version2.0.md deleted file mode 100644 index b93c87f79c..0000000000 --- a/docs/Version2.0.md +++ /dev/null @@ -1,16 +0,0 @@ -历时4个多月迭代开发，mpx正式成长为2.0版本，在专注提高小程序开发体验的道路上又前进了一大步，感谢相关同学的努力与付出，@pkingwa，@sky-admin，@httpsxiao，@xuehebinglan - -## Features - -* 完整支持了目前业内已发布的所有小程序平台（微信，支付宝，百度，qq，头条） -* mpx小程序跨平台编译，目前已支持将微信mpx源码编译输出为其余已支持小程序平台目标代码，[点击查看详情](https://didi.github.io/mpx/platform.html#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E7%BC%96%E8%AF%91) -* 小程序原生组件跨平台编译，目前已支持将微信原生组件编译输出为其余已支持小程序平台组件 -* api调用跨平台差异抹平`@mpxjs/api-proxy` -* webview bridge跨平台差异抹平`@mpxjs/webview-bridge` -* 深度分包优化，编译过程中进行精准分包资源判断，所有分包only的资源(页面，组件，js module，wxs，template，媒体资源等)都会精确输出到分包目录中 -* render函数中完整支持wxs模块，[关于render函数点击查看详情](https://didi.github.io/mpx/understanding/understanding.html#%E6%95%B0%E6%8D%AE%E5%93%8D%E5%BA%94%E4%B8%8E%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96) -* 支持模板引入，内联wxs，自定义tabbar，workers，云开发等原生能力，进一步完善原生兼容性 -* 新增this.$nextTick替换this.updated -* 增强watch能力，支持`a,b`表达式同时监听a和b的变化，回调函数支持方法名字符串 -* 优化多实例store中mapStore使用体验 -* 新增增强指令`wx:show`，用于处理hidden样式优先级过低及跨平台兼容性问题 diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 4b024ded1c..0000000000 --- a/docs/api.md +++ /dev/null @@ -1,321 +0,0 @@ -# API参考 - -mpx和mpx-webpack-plugin中暴露出的api文档 - -### createApp - -``` js -import mpx, {createApp} from '@mpxjs/core' -mpx.createApp(object) -createApp(object) -``` - -### createPage - -> 类微信小程序（微信、百度、头条等）内部使用[Component的方式创建页面](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/component.html)，所以除了支持页面的生命周期之外还同时`支持组件的一切特性`。当使用Component创建页面时，`页面生命周期`需要写在`methods内部`（微信小程序原生规则），mpx进行了统一封装转换，`页面生命周期都写在最外层`即可 - -> options的具体形式，除了computed、watch这类mpx扩展特性之外，其他的属性都参照原生小程序的官方文档即可。 - -用法：`createPage(options, config?)` - -config是一个可选参数，应为一个对象。 -如果希望标识一个组件是最纯粹的原生组件，不用数据响应等能力，可通过config.isNative传true声明。 -如果有需要复写/改写最终调用的创建页面的构造器，可以通过config对象的customCtor提供。`注意：mpx本身是用component来创建页面的，如果传page可能在初始化时候生命周期不正常导致取props有一点问题` - -``` js -import mpx, {createPage} from '@mpxjs/core' -mpx.createPage({ - data: {test: 1}, - computed: { - test2 () { - return this.test + 1 - } - }, - watch: { - test (val, old) { - console.log(val, old) - } - }, - onShow () { - this.test++ - } -}) -createPage(object) -``` - -### createComponent - -> options的具体形式，除了computed、watch这类mpx扩展特性之外，其他的属性都参照原生小程序的官方文档即可。 - -用法：`createComponent(options, config?)` - -config是一个可选参数，应为一个对象。 -如果希望标识一个组件是最纯粹的原生组件，不用数据响应等能力，可通过config.isNative传true声明。 -如果有需要复写/改写最终调用的创建组件的构造器，可以通过config对象的customCtor提供。 - -``` js -import mpx, {createComponent} from '@mpxjs/core' -mpx.createComponent({ - properties: { - prop: { - type: Number, - value: 10 - } - }, - data: {test: 1}, - computed: { - test2 () { - return this.test + this.prop - } - }, - watch: { - test (val, old) { - console.log(val, old) - }, - prop: { - handler (val, old) { - console.log(val, old) - }, - immediate: true // 是否首次执行一次 - } - } -}) -createComponent(object) -``` - -### createStore - -``` js -import mpx, {createStore} from '@mpxjs/core' -const store1 = mpx.createStore({ ...options }) -const store2 = createStore({ ...options }) -``` - -##### options选项 - -- **state** - - - 类型: `Object` - - store的根 state 对象。[详细介绍](store/index.md#state) - -- **mutations** - - - 类型: `{ [type: string]: Function }` - - 在 store 上注册 mutation，处理函数总是接受 `state` 作为第一个参数（如果定义在模块中，则为模块的局部状态），`payload` 作为第二个参数（可选）。 - - [详细介绍](store/index.md#mutation) - -- **actions** - - - 类型: `{ [type: string]: Function }` - - 在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数，`payload` 作为第二个参数（可选）。 - - `context` 对象包含以下属性： - - ``` js - { - state, // 等同于 `store.state` - commit, // 等同于 `store.commit` - dispatch, // 等同于 `store.dispatch` - getters // 等同于 `store.getters` - } - ``` - - 同时如果有第二个参数 `payload` 的话也能够接收。 - - [详细介绍](store/index.md#action) - -- **getters** - - - 类型: `{ [key: string]: Function }` - - 在 store 上注册 getter，getter 方法接受以下参数： - - ``` - state, // 如果在模块中定义则为模块的局部状态 - getters, // 等同于 store.getters - ``` - - 注册的 getter 暴露为 `store.getters`。 - - [详细介绍](store/index.md#getters) - -- **modules** - - - 类型: `Object` - - 包含了子模块的对象，会被合并到 store，大概长这样： - - ``` js - { - key: { - state, - mutations, - actions?, - getters?, - modules? - }, - ... - } - ``` - - 与根模块的选项一样，每个模块也包含 `state` 和 `mutations` 选项。模块的状态使用 key 关联到 store 的根状态。模块的 mutation 和 getter 只会接收 module 的局部状态作为第一个参数，而不是根状态，并且模块 action 的 `context.state` 同样指向局部状态。 - - [详细介绍](store/index.md#module) - -- **deps** - - - 类型: `Object` - - 包含了当前store依赖的第三方store： - - ``` js - { - store1: storeA, - store2: storeB - } - ``` - - [详细介绍](store/index.md#多实例) - - -### Store 实例属性 - -- **state** - - - 类型: `Object` - - 根状态。 - -- **getters** - - - 类型: `Object` - - 暴露出注册的 getter。 - -### Store 实例方法 - -- **`commit(type: string, payload?: any, options?: Object) | commit(mutation: Object, options?: Object)`** - - 提交 mutation。[详细介绍](store/index.md#mutation) - -- **`dispatch(type: string, payload?: any, options?: Object) | dispatch(action: Object, options?: Object)`** - - 分发 action。返回一个Promise。[详细介绍](store/index.md#action) - -- **`mapState(map: Array | Object): Object`** - - 为组件创建计算属性以返回 store 中的状态。[详细介绍](store/index.md#mapstate-辅助函数) - -- **`mapGetters(map: Array | Object): Object`** - - 为组件创建计算属性以返回 getter 的返回值。[详细介绍](store/index.md#mapgetters-辅助函数) - -- **`mapActions(map: Array | Object): Object`** - - 创建组件方法分发 action。[详细介绍](store/index.md#在组件中分发-action) - -- **`mapMutations(map: Array | Object): Object`** - - 创建组件方法提交 mutation。[详细介绍](store/index.md#在组件中提交-mutation) - - -### toPureObject - -由于使用的mobx的响应式数据，所以业务拿到的数据可能是mobx响应式数据实例（包含了些其他属性），使用toPureObject可以将响应式的数据转化成纯js对象 - -```js -import {toPureObject} from '@mpxjs/core' -const pureObject = toPureObject(object) -``` - -### observable - -用于创建响应式数据，属于mobx提供的能力 - -```js -import {observable} from '@mpxjs/core' -// mpx.observable(...) -const a = observable(object) -``` - -~~### extendObservable~~ - -~~（已废弃）用于扩展响应式数据，属于mobx提供的能力, 主要用于添加新的可观察数据, `并不会触发订阅者更新`~~ - -```js~~ -import {observable, extendObservable} from '@mpxjs/core' -const a = observable(object) -// mpx.extendObservable(...) -const b = extendObservable(a, {newProp: 10}) -``` - -### watch(context, expr, handler) - -用于观察数据从而触发相应操作 - -- context 回调执行的上下文 -- expr 观察的表达式[String | Function]。可以是path字符串（取值将在context上进行查找），也可以是函数 -- handler 响应函数[Function | Object]。如果是对象，则handler.handler为回调函数，其他参数作为options，与组件的watch一致 - -```js -import mpx, {watch} from '@mpxjs/core' -// mpx.watch(...) -const a = observable({name: 1}) -watch(null, () => { - console.log(a.name) - return a.name -}, (val) => { - console.log('update a.name', val) -}) -a.name = 10 -``` - -### mpx.set & mpx.remove - -用于对一个响应式对象新增或删除属性，会`触发订阅者更新操作` - -```js -import mpx, {observable} from '@mpxjs/core' -const a = observable({name: 1}) -mpx.set(a, 'age', 'test') -mpx.remove(a, 'age') -``` - -### mpx.use - -mpx.use用于安装外部扩展, 支持多参数，如果第二个参数是一个包含（prefix or postfix）的option， -那么将会对插件扩展的属性添加前缀或后缀（主要考虑插件开发者直接导出的属性可能存在同名问题，use时指定 -前缀或后缀能在业务角度去处理这种情况） - -```js -import mpx from '@mpxjs/core' -import test from './test' -mpx.use(test) -mpx.use(test, {prefix: 'mpx'}, 'otherparams') -``` - -[具体例子](extend/index.md) - -### mpx.mixin - -用于注入mixin - -```js -import mpx from '@mpxjs/core' -mpx.mixin({ - methods: { - $fetch: function(){} - } -}, types) -``` -##### types选项 -types决定了mixin会注入到哪种实例上，app | page | component - -- String, 'app' | 'page' | 'component' -- Array, ['app', 'page', 'component'] -- 如果不传，默认为['app', 'page', 'component'] - diff --git a/docs/articles/1.0.md b/docs/articles/1.0.md deleted file mode 100644 index 2ef323f449..0000000000 --- a/docs/articles/1.0.md +++ /dev/null @@ -1,89 +0,0 @@ -# 滴滴开源小程序框架Mpx - -> 作者：董宏平 (hiyuki) - -Mpx是一款致力于提高小程序开发体验的增强型小程序框架，通过Mpx，我们能够以最先进的web开发体验(Vue + Webpack)来开发生产性能深度优化的小程序，Mpx具有以下一些优秀特性： -* 数据响应特性(watch/computed) -* 增强的模板语法(动态组件/样式绑定/类名绑定/内联事件函数/双向绑定等) -* 深度性能优化(原生自定义组件/基于依赖收集和数据变化的setData) -* Webpack编译(npm/循环依赖/Babel/ESLint/css预编译/代码优化等) -* 单文件组件开发 -* 状态管理(Vuex规范/多实例/可合并) -* 跨团队合作(packages) -* 逻辑复用能力(mixins) -* 脚手架支持 -* 小程序自身规范的完全支持 -* 支付宝小程序的支持 - -## 设计思路 - -目前业界主流的小程序框架主要有WePY，mpvue和Taro，这三者都是将其他的语法规范转译为小程序语法规范，我们称其为转译型框架。不同于上述三者，Mpx是一款基于小程序语法规范的增强型框架，我们使用Vue中优秀的语法特性增强了小程序，而不是让用户直接使用vue语法来开发小程序，之所以采用这种设计主要是基于如下考虑： -* 转译型框架无法支持源框架的所有语法特性(如Vue模板中的动态特性或React中动态生成的jsx)，用户在使用源框架语法进行开发时可能会遇到不可预期的错误，具有不确定性 -* 小程序本身的技术规范在不断地更新进步，许多新的技术规范在转译型框架中无法支持或需要很高的支持成本，而对于增强型框架来说只要新的技术规范不与增强特性冲突，就能够直接支持 - -## 技术实现 -小程序刚推出时不支持自定义组件，无法进行组件化开发，当时最早的小程序框架WePY做的核心工作就是支持了小程序的组件化开发，后来的mpvue也基于Vue做了类似的工作。由于当时的小程序本身不支持自定义组件，WePY和mpvue的组件化支持都是基于编译做的组件化封装，用户编写的组件模板会被编译为Page中模板的一部分，在组件中定义的数据会被编译为Page中的数据，对组件进行数据更新也会基于路径映射调用Page.setData。这个方案在当时的技术条件下确实是一个唯一解，但该方案在复杂的小程序应用中会存在明显性能问题，原因在于该方案中页面的数据量会很大，而且每个组件的局部更新实际上都会成为页面级别的全局更新，在组件较多的页面中容易引发性能问题。在小程序自定义组件推出后，我们通过性能测试确认了该方案解决了上述组件封装方案中的性能问题。由于自定义组件在当时是一个最新的技术标准，业内的小程序框架都未支持，而我们本身的业务又有复杂小程序的开发需求，于是我们就基于小程序自定义组件规范启动了Mpx框架的设计与开发 - -*Page与Component setData性能对照* - -| |Component|Page| -|---|----------|----- | -|局部更新|1975ms|7186ms| -|全局更新|6210ms|24612ms| -> 性能衡量标准说明： -局部更新：文档中存在1000个节点，其中一个节点更新1000次的耗时； -全局更新：文档中存在5个节点，5个节点独立更新1000次的耗时 -以上数据在iphone7微信小程序环境下测试得出 - -### 数据响应与性能优化 -数据响应作为Vue最核心的特性，在我们的日常开发中被大量使用，能够极大地提高前端开发体验和效率，我们在框架设计初期最早考虑的就是如何将数据响应特性加入到小程序开发中。在数据响应的实现上，我们引入了MobX，一个实现了纯粹数据响应能力的知名开源项目。借助MobX和mixins，我们在小程序组件创建初期建立了一个响应式数据管理系统，该系统观察着小程序组件中的所有数据(data/props/computed)并基于数据的变更驱动视图的渲染(setData)及用户注册的watch回调，实现了Vue中的数据响应编程体验。与此同时，我们基于MobX封装实现了一个Vuex规范的数据管理store，能够方便地注入组件进行全局数据管理。为了提高跨团队开发的体验，我们对store添加了多实例可合并的特性，不同团队维护自己的store，在需要时能够合并他人或者公共的store生成新的store实例，我们认为这是一种比Vuex中modules更加灵活便捷的跨团队数据管理模式 - -作为一个接管了小程序setData的数据响应开发框架，我们高度重视Mpx的渲染性能，通过小程序官方文档中提到的性能优化建议可以得知，setData对于小程序性能来说是重中之重，setData优化的方向主要有两个： -1. 尽可能减少setData调用的频次 -2. 尽可能减少单次setData传输的数据 - -为了实现以上两个优化方向，我们做了以下几项工作： -* 将组件的静态模板编译为可执行的render函数，通过render函数收集模板数据依赖，只有当render函数中的依赖数据发生变化时才会触发小程序组件的setData，同时通过一个异步队列确保一个tick中最多只会进行一次setData，这个机制和Vue中的render机制非常类似，大大降低了setData的调用频次； -* 将模板编译render函数的过程中，我们还记录输出了模板中使用的数据路径，在每次需要setData时会根据这些数据路径与上一次的数据进行diff，仅将发生变化的数据通过数据路径的方式进行setData，这样确保了每次setData传输的数据量最低，同时避免了不必要的setData操作，进一步降低了setData的频次。 -基于以上优化，我们大大减少了小程序setData的调用频次和传递数据量，与初版Mpx中track全量数据的方案相比提示显著。 - -*Mpx setData优化效果* - -| |旧版mpx|新版mpx| -|---|----|-----| -|setData次数 |164 |88 | -|setData数据量 |370kB |38kB| -> 以上数据由较复杂小程序在固定交互流程后统计得出 - -![Mpx数据响应机制流程示意图](https://dpubstatic.udache.com/static/dpubimg/4cb54489-b99d-4560-97aa-68f756730131.jpeg) -*Mpx数据响应机制流程示意图* - -### 编译构建 -我们希望使用目前设计最强大、生态最完善的编译构建工具Webpack来实现小程序的编译构建，让用户得到web开发中先进强大的工程化开发体验。使用过Webpack的同学都知道，通常来说Webpack都是将项目中使用到的一系列碎片化模块打包为一个或几个bundle，而小程序所需要的文件结构是非常离散化的，如何调解这两者的矛盾成为了我们最大的难题。一种非常直观简单的思路在于遍历整个src目录，将其中的每一个.mpx文件都作为一个entry加入到Webpack中进行处理，这样做的问题主要有两个： -1. src目录中用不到的.mpx文件也会被编译输出，最终也会被小程序打包进项目包中，无意义地增加了包体积； -2. 对于node_modules下的.mpx文件，我们不认为遍历node_modules是一个好的选择。 - -最终我们采用了一种基于依赖分析和动态添加entry的方式来进行实现，用户在Webpack配置中只需要配置一个入口文件app.mpx，loader在解析到json时会解析json中pages域和usingComponents域中声明的路径，通过动态添加entry的方式将这些文件添加到Webpack的构建系统当中（注意这里是添加entry而不是添加依赖，因为只有entry能生成独立的文件，满足小程序的离散化文件结构），并递归执行这个过程，直到整个项目中所有用到的.mpx文件都加入进来，在输出前，我们借助了CommonsChunkPlugin/SplitChunksPlugin的能力将复用的模块抽取到一个外部的bundle中，确保最终生成的包中不包含重复模块。我们提供了一个Webpack插件和一个.mpx文件对应的loader来实现上述操作，用户只需要将其添加到Webpack配置中就可以以打包web项目的方式正常打包小程序，没有任何的前置和后置操作，支持Webpack本身的完整生态。 - -![Mpx编译构建机制流程示意图](https://dpubstatic.udache.com/static/dpubimg/ce6d470c-0a4c-486e-a2f5-ad225c289832.jpeg) -*Mpx编译构建机制流程示意图* - -# 现状和未来 -目前Mpx框架已经在滴滴内部大量使用，支撑了滴滴出行、青桔单车、街兔电单车、营销、车服等业务在小程序上的实现，线上运行稳定，收到了大量的好评反馈。未来我们在对框架进行持续迭代优化的同时会持续跟进微信和支付宝最新的技术标准，同时也会将在更多的小程序平台上进行适配。由于我们的设计初衷和专注点在于增强小程序开发体验，Mpx并没有进行跨H5甚至是跨Native的支持，但现实业务当中确实存在这样的诉求，未来我们会在Mpx的基础上对跨端进行一定的尝试，与此同时我们依然会持续维护升级Mpx，原因在于跨端意味着灵活性受限及能力的缺失，我们希望能给用户提供第二种选择。 - -*Mpx与业内主流小程序框架异同对比* - -| |WePY|mpvue|Taro|Mpx| -|---|----|-----|----|---| -|代码规范 |自定义| Vue |React |小程序+| -|组件化实现 |Page封装 |Page封装| Component| Component| -|数据响应| 脏值检查| Vue| 无 |Mobx| -|状态管理| Redux| Vuex| Redux|类Vuex| - -## 结语 -如果你注重开发体验和产品性能，专注于小程序开发，那Mpx会是一个很好的选择。最后感谢开源社区源源不断涌现出的优秀项目，给我们提供了无限的启发和巨大的技术帮助。 - -Github: [https://github.com/didi/mpx](https://github.com/didi/mpx) -使用文档: [https://didi.github.io/mpx/](https://didi.github.io/mpx/) -用户交流群: -![微信](https://dpubstatic.udache.com/static/dpubimg/at_XEnlFb0/WechatIMG1.jpeg) diff --git a/docs/articles/2.0.md b/docs/articles/2.0.md deleted file mode 100644 index f182cf9cd4..0000000000 --- a/docs/articles/2.0.md +++ /dev/null @@ -1,156 +0,0 @@ -# 滴滴小程序框架Mpx发布2.0，支持小程序跨平台开发，可直接转换已有微信小程序 - -> 作者：董宏平 (hiyuki) - -Mpx是一款致力于提高小程序开发体验和效率的增强型小程序框架，目前在滴滴公司内部支撑了包括滴滴出行小程序，滴滴出行广场小程序，青桔单车，黑马电单车，小桔养车，小桔加油在内的小程序生态；自去年11月开源以来，Mpx也吸纳了众多外部开发者的加入，基于Mpx开发了开走吧，好免街，花忆等小程序。 - -长期以来，Mpx优秀的开发体验和强大的稳定性得到了内外开发者的一致认可和好评，这非常符合Mpx的设计初衷。但是在各大厂商陆续推出自己的小程序平台，且各家的技术标准都不统一的今天，单纯地提高某一个平台的开发体验已经不能满足广大小程序开发者们的诉求，`一套代码在多小程序平台运行`已经成为一个现实上的刚需。为了解决这个小程序开发的痛点，Mpx发布了2.0版本，适配了目前业内已经发布的所有小程序平台(微信、支付宝、百度、头条、qq)，并且提供了直接将现有微信小程序编译输出到其他平台运行的能力。 - -Mpx2.0版本新增的主要特性主要包含： -* 完整支持了目前业内已发布的所有小程序平台(微信，支付宝，百度，qq，头条)； -* Mpx小程序跨平台开发，支持将已有的Mpx微信项目编译输出到其他已支持的小程序平台中运行，[点击查看详情](https://didi.github.io/mpx/platform.html#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E7%BC%96%E8%AF%91)； -* 小程序原生组件跨平台编译，支持将已有的微信原生组件编译输出到其他已支持的小程序平台中运行； -* 深度分包优化，编译过程中进行精准分包资源判断，所有分包only的资源(组件、js、外部样式、外部模板、wxs，图像媒体等)都会精确输出到分包目录中； -* render函数中完整支持wxs模块，[关于render函数点击查看详情](https://didi.github.io/mpx/understanding/understanding.html#%E6%95%B0%E6%8D%AE%E5%93%8D%E5%BA%94%E4%B8%8E%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96)； -* 支持了模板引入，内联wxs，自定义tabbar，workers，云开发等原生能力，进一步完善原生兼容性。 - -同业内主流的小程序跨端框架相比，Mpx更专注于小程序开发本身，在小程序开发中具备以下优势： -* 基于小程序自身的技术标准进行增强，没有进行过重的DSL转换，开发时遇到的坑会更少； -* 完全兼容原生小程序技术规范，0成本迁移原生小程序项目; -* 跨平台开发以跨小程序平台为目标，大部分差异抹平工作在编译阶段进行，大大减少运行时适配层增加的包体积； -* 支持业内微信小程序组件库(如vant、iView等)直接转换到其他小程序平台运行; -* 非常重视小程序性能，提供了深度的setData和包体积优化。 - -关于Mpx更详细的介绍可以查看[官方文档](https://didi.github.io/mpx/)和[这篇文章](https://didi.github.io/mpx/articles/1.0.html)。 - -Github：[https://github.com/didi/mpx](https://github.com/didi/mpx) - -## 跨平台开发 - -作为2.0版本的核心能力，Mpx的跨平台开发能力允许用户直接将已有小程序项目编译输出到其他已支持的小程序平台中运行。微信小程序作为小程序概念的提出者，有着最广泛的生态覆盖，因此我们优先支持了将微信小程序编译为其他平台小程序的能力。基于这个能力，用户不仅能跨平台编译微信Mpx项目，甚至能够将微信的原生自定义组件也编译到其他小程序平台进行运行，这意味着我们的跨平台项目能够直接使用一些社区内已有的UI组件库生态(如vant、iView等)，极大地提高了跨平台开发的适用范围。 - -### 设计理念 - -Mpx框架的核心设计理念在于增强，增强是指在小程序已有的原生能力基础上做加法，拓展小程序的开发能力，提高小程序的开发体验和效率。这个设计理念使Mpx给开发者带来了更强的确定性和可预期性，更低的学习上手和调试成本。基于这个理念，Mpx在不同的小程序平台中进行了差异性的增强适配，并参考各个平台的模板指令风格提供了不同的增强模板指令集，让用户在各小程序平台中都可以以增强的方式去最大限度地使用平台自有的原生能力。 - -我们在对Mpx提供跨平台能力的支持时也遵循了增强的核心设计理念。简单来讲，Mpx的跨平台能力是在多平台能力的基础上，在编译和运行时增加了一层转换层，将源平台的代码转换为目标平台的代码之后，再按照既有的目标平台的处理逻辑进行增强，同时我们也提供了一套完善的条件编译机制，让用户自行实现少数框架无法转换的部分。 - -![Mpx跨平台开发流程示意图](https://dpubstatic.udache.com/static/dpubimg/38652040-2fbf-435b-aeff-563666c4021c.png) - -*Mpx跨平台开发流程示意图* - -Mpx跨平台能力设计思路明显区别于业内已有的其他小程序跨平台框架，主要差异在于： -* Mpx以小程序本身的DSL作为基准，而没有使用web框架(React,Vue)的DSL； -* Mpx主要通过编译和运行时转换的方式处理平台差异，没有提供额外的差异抹平层(基础组件库等)。 - -之所以采用这种设计，主要基于以下原因： -* Mpx主要以跨小程序平台为目标，目前各大小程序平台的技术规范具有一定相似性，绝大部分平台差异能够通过编译和运行时手段抹平，同时省去的差异抹平层也能够进一步减少框架运行时体积； -* 使用小程序本身的DSL作为基准允许用户直接在已有项目中使用跨平台能力，对于原生小程序项目或组件也能够使用该能力进行跨平台输出； -* 结合完善的条件编译支持，该方案能够在满足用户跨平台需求的同时仍然允许用户最大限度地使用各个小程序平台提供的能力，完全延续了Mpx增强的核心设计理念。 - -### 使用方法 - -Mpx跨平台开发的使用方式非常简单，用户只需在MpxWebpackPlugin创建时传入mode和srcMode参数指定源平台和目标平台，当srcMode和mode不一致时，框架会读取相应的配置对项目进行编译和运行时转换。 - -```js -// 微信转支付宝 -new MpxWebpackPlugin({ - // mode指定目标平台，可选值有(wx|ali|swan|qq|tt) - mode: 'ali', - // srcMode指定源码平台，默认值同目标平台一致 - srcMode: 'wx' -}) -``` - -### 差异抹平 - -目前各大厂商的小程序技术规范在宏观层面上大致保持一致，但是技术细节方面存在很多差异，大致划分为以下几个部分： -* 模板语法/基础组件差异 -* json配置差异 -* wxs语法差异 -* 页面/组件对象差异 -* api调用差异 -* webview bridge差异 - -其中，对于模板语法/基础组件、json配置和wxs中的静态差异，我们主要通过编译手段进行转换处理，对于这部分差异中无法转换的部分会在编译阶段报错指出；而对于页面/组件对象、api调用和webview bridge中js运行时的差异，我们主要通过运行时手段进行处理，对应的无法转换部分也会在运行时中报错指出。 - -值得注意的是，我们在跨平台转换中做的工作不仅是对可转换的技术标准进行转换映射，对于一些目标平台中不存在的能力，我们也尽可能地通过编译和运行时手段提供了模拟和支持，最大限度地减少用户在跨平台开发中需要付出的额外工作量。以差异性最大但现实场景也最多的微信转支付宝为例，Mpx模拟提供了许多微信中支持但支付宝中未支持的能力： -* 组件自定义事件 -* 组件间关系 -* 获取子组件实例 -* observers/property observer -* 内联wxs -* 外部样式类 - -对于原生自定义组件的跨平台转换，我们会对其进行简单的运行时注入，使其能够使用Mpx框架提供的运行时转换能力。 - -### 条件编译 - -对于框架无法抹平的差异部分，会在编译和运行时报错指出，对于这部分错误，我们提供了完善的条件编译机制让用户能够自行编写目标平台的patch进行修复，该能力也能用于实现具有平台差异性的业务逻辑。 - -上文中提到Mpx通过读取用户传入的mode和srcMode来决定是否以及如何对项目进行转换，mode和srcMode分别代表整个项目构建的目标平台和源平台，条件编译能够让用户在项目中创建声明了自身平台属性(localSrcMode)的文件和代码块。在项目构建中，框架会优先加载带有localSrcMode声明且localSrcMode与项目目标平台匹配(localSrcMode===mode)的文件和代码块，这部分文件和代码块需要完全依照自身声明的平台标准进行编写，Mpx不会对其进行任何编译和运行时的跨平台转换。 - -Mpx提供了三种维度的条件编译，分别是文件维度，区块维度和代码维度，用户可以根据平台差异的覆盖范围灵活选择使用。 - -## 性能优化 - -Mpx框架专注于小程序开发，在性能优化方面我们做过很多尝试和努力，主要集中在两个方面： -* 运行时的setData优化 -* 编译构建时的包体积优化 - -### setData优化 - -数据响应是Mpx运行时增强的核心能力，该能力让用户在小程序开发中能够像Vue中一样使用watch和computed特性，并且用直接赋值的方式操作数据驱动视图更新，而不需要手动调用setData方法，换言之框架接管了小程序中的setData调用。 - -通过各大小程序平台的设计原理和性能优化建议可以得知，setData对于小程序的性能表现非常重要，而setData优化的两大方向在于： -* 尽可能减少setData调用的频次 -* 尽可能减少单次setData传输的数据 - -为了实现setData的优化，我们在模板编译过程中对于每个组件的模板都生成了一个渲染函数(render function)，该函数模拟模板的渲染逻辑，在每次执行时访问当次渲染所需的数据，并将当次访问过的数据路径记录下来作为函数返回值返回。 - -在运行时，框架会在每个组件创建时创建一个render watcher，该watcher追踪渲染函数，当渲染依赖数据发生变更时异步执行渲染函数，在render watcher回调中得到渲染函数返回的数据路径，基于这些路径与上一次的缓存数据进行diff比对，过滤掉未发生变化的数据后得到最小必要数据，最后调用setData将最小必要数据发送到真实的小程序渲染层更新视图。 - -基于这个机制，当数据发生变更时，只有当前渲染依赖的那部分数据发生变更才会异步地触发render watcher的执行，而每次执行后也只有实际发生变更的那部分数据会被setData发送到渲染层。这样用户就能自由地根据业务需求来操作数据，无需关注setData的调用优化，框架能够自动进行程序上最优的setData调用，在提升用户开发体验的同时也提升了程序性能。 - -在1.x版本中，渲染函数内无法执行wxs的逻辑，对于含有wxs的组件有可能降级到全量设置数据的模式，在2.0版本中，我们将wxs模块转译处理为js可执行的代码后注入到js bundle中，含有wxs的渲染函数也能够正常访问并执行wxs逻辑。 - -![setData优化示意图](https://dpubstatic.udache.com/static/dpubimg/9ead35f1-693f-44f4-beb3-f98555ab6861.png) - -*setData优化示意图* - -### 包体积优化 - -类似于运行时对于setData的接管，Mpx在编译阶段接管了项目的资源管理。得益于webpack强大的插件机制，Mpx开发了一个深度定制的webpack插件，基于webpack完成小程序的打包构建工作。用户在使用Mpx开发小程序时可以不受限制地使用npm依赖、最新的es特性和css预处理器等现代web开发能力。与此同时，Mpx在包体积优化上也做了很多工作，让用户专注于业务开发而无需花费过多精力进行包体积管理，我们所做的优化工作如下： -* 打包构建工作完全基于依赖分析，任何没有被引用的资源都不会出现在dist当中； -* 对于npm组件和页面的构建也完全基于依赖分析按需打包，不会copy整个miniprogram_dist目录，也不需要执行构建npm，使用体验和包体积均优于微信小程序自身的npm支持方案； -* 基于webpack提供的能力进行公共模块抽取和代码压缩等优化工作； -* 完善的分包支持，对所有资源进行从属分析，将所有分包only的资源都输出到分包目录中。 - -分包作为微信小程序中优化包体积的核心手段(类似于异步按需加载)，Mpx对其进行了完善的支持。为了精确地标记出分包only的资源，我们在构建时将主包和分包的依赖收集步骤拆分开来串行处理，先处理主包，再处理分包。在主包的处理过程中，将主包页面中引用的所有非js资源(组件、外部样式、外部模板、wxs，图像媒体等)都记录下来，在处理分包时，对分包内引用的非js资源都进行检查，如果被主包引用过则输出到主包中，否则标记为分包only的资源输出到分包目录下。 - -对于js模块资源，我们在脚手架中生成的构建配置中提供了辅助函数，便于用户进行分包bundle的配置，经过该配置后，分包only的公用模块会被打入分包bundle输出到分包目录下，其余的公共模块会正常打入主bundle中。 - -在跨平台开发中，我们建议用户使用Mpx提供的[packages](https://didi.github.io/mpx/single/json-enhance.html#packages)来定义分包，这样在转换到不支持分包的小程序平台时会自动降级为同步包进行处理。 - -![分包构建示意图](https://dpubstatic.udache.com/static/dpubimg/3121ca4e-1b47-43bc-992a-b351c4a03da4.png) - -*分包构建示意图* - -## 渐进迁移 - -Mpx提供了良好的渐进迁移支持，对于使用原生或其他小程序框架的开发者来说，采用渐进迁移的方式逐步引入Mpx进行开发成本并不大。 - -在2.0版本中我们进一步完善了Mpx的原生兼容性，跟进支持了各个小程序平台最新的技术能力，如自定义tabbar，分包预加载，workers，云开发等能力，同时补齐了一些1.x版本遗漏的支持。得益于此，对于使用原生小程序开发的开发者来说，迁移Mpx的成本几乎为0，用户只需将对应页面组件的构造函数替换为Mpx提供的createPage/createCompnent，即可使用Mpx提供的各种增强能力。 - -对于使用其他框架的开发者，Mpx也提供了局部构建的机制，允许用户将特定的页面和组件单独构建输出为原生组件，用户只需手动或者编写脚本输出的原生组件整合进原有项目中即可。 - -## 未来规划 - -作为滴滴公司内部小程序生态的基础设施，我们会对Mpx框架进行长期的维护更新，确保能在第一时间支持各个小程序平台最新的技术特性。与此同时，我们也会进一步完善框架的基础能力，目前已排上日程待支持能力包括： -* i18n -* ts支持 -* 单元测试支持 - -在跨平台能力方面，我们也会根据社区的反馈和建议，以及小程序的标准化进程，对其进行持续的完善与更新。 - -最后，如果你专注小程序开发，关注开发体验和产品性能，那Mpx会是你最好的选择。 diff --git a/docs/articles/2.0inner.md b/docs/articles/2.0inner.md deleted file mode 100644 index eff8cb4022..0000000000 --- a/docs/articles/2.0inner.md +++ /dev/null @@ -1,161 +0,0 @@ -# 滴滴小程序框架Mpx发布2.0，支持小程序跨平台开发，可直接转换已有微信小程序 - -> 作者：董宏平 (hiyuki) - -Mpx是一款致力于提高小程序开发体验和效率的增强型小程序框架，目前在滴滴公司内部支撑了包括滴滴出行小程序，滴滴出行广场小程序，青桔单车，黑马电单车，小桔养车，小桔加油在内的小程序生态；自去年11月开源以来，Mpx也吸纳了众多外部开发者的加入，基于Mpx开发了开走吧，好免街，花忆等小程序。 - -长期以来，Mpx优秀的开发体验和强大的稳定性得到了内外开发者的一致认可和好评，这非常符合Mpx的设计初衷。基于Mpx实现的滴滴出行小程序、滴滴营销小程序等也给业务带来了很大收益。但是随着各大厂商陆续推出自己的小程序平台，各家的技术标准都不统一，而业务又需要在这些小程序平台上进行推广使用，为了快速响应需求，`将现有的小程序尽量小成本的迁移至多小程序平台运行`已经成为一个现实上的刚需。为了解决这个问题，Mpx发布了2.0版本，适配了目前业内已经发布的所有小程序平台(微信、支付宝、百度、头条、qq)，并且提供了直接将现有微信小程序编译输出到其他平台运行的能力。 - -Mpx2.0版本新增的主要特性主要包含： -* 完整支持了目前业内已发布的所有小程序平台(微信，支付宝，百度，qq，头条)； -* Mpx小程序跨平台开发，支持将已有的Mpx微信项目编译输出到其他已支持的小程序平台中运行，[点击查看详情](https://didi.github.io/mpx/platform.html#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E7%BC%96%E8%AF%91)； -* 小程序原生组件跨平台编译，支持将已有的微信原生组件编译输出到其他已支持的小程序平台中运行； -* 深度分包优化，编译过程中进行精准分包资源判断，所有分包only的资源(组件、js、外部样式、外部模板、wxs，图像媒体等)都会精确输出到分包目录中； -* render函数中完整支持wxs模块，[关于render函数点击查看详情](https://didi.github.io/mpx/understanding/understanding.html#%E6%95%B0%E6%8D%AE%E5%93%8D%E5%BA%94%E4%B8%8E%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96)； -* 支持了模板引入，内联wxs，自定义tabbar，workers，云开发等原生能力，进一步完善原生兼容性。 - -同业内主流的小程序跨端框架相比，Mpx更专注于小程序开发本身，在小程序开发中具备以下优势： -* 基于小程序自身的技术标准进行增强，没有进行过重的DSL转换，开发时遇到的坑会更少； -* 完全兼容原生小程序技术规范，0成本迁移原生小程序项目; -* 跨平台开发以跨小程序平台为目标，大部分差异抹平工作在编译阶段进行，大大减少运行时适配层增加的包体积； -* 支持业内微信小程序组件库(如vant、iView等)直接转换到其他小程序平台运行; -* 非常重视小程序性能，提供了深度的setData和包体积优化。 - -关于Mpx更详细的介绍可以查看[官方文档](https://didi.github.io/mpx/)和[这篇文章](https://didi.github.io/mpx/articles/1.0.html)。 - -Github：[https://github.com/didi/mpx](https://github.com/didi/mpx) - -## 跨平台开发 - -作为2.0版本的核心能力，Mpx的跨平台开发能力允许用户直接将已有小程序项目编译输出到其他已支持的小程序平台中运行。微信小程序作为小程序概念的提出者，有着最广泛的生态覆盖，因此我们优先支持了将微信小程序编译为其他平台小程序的能力。基于这个能力，用户不仅能跨平台编译微信Mpx项目，甚至能够将微信的原生自定义组件也编译到其他小程序平台进行运行，这意味着我们的跨平台项目能够直接使用一些社区内已有的UI组件库生态(如vant、iView等)，极大地提高了跨平台开发的适用范围。 - -### 设计理念 - -Mpx框架的核心设计理念在于增强，增强是指在小程序已有的原生能力基础上做加法，拓展小程序的开发能力，提高小程序的开发体验和效率。这个设计理念使Mpx给开发者带来了更强的确定性和可预期性，更低的学习上手和调试成本。基于这个理念，Mpx在不同的小程序平台中进行了差异性的增强适配，并参考各个平台的模板指令风格提供了不同的增强模板指令集，让用户在各小程序平台中都可以以增强的方式去最大限度地使用平台自有的原生能力。 - -我们在对Mpx提供跨平台能力的支持时也遵循了增强的核心设计理念。简单来讲，Mpx的跨平台能力是在多平台能力的基础上，在编译和运行时增加了一层转换层，将源平台的代码转换为目标平台的代码之后，再按照既有的目标平台的处理逻辑进行增强，同时我们也提供了一套完善的条件编译机制，让用户自行实现少数框架无法转换的部分。 - -![Mpx跨平台开发流程示意图](https://dpubstatic.udache.com/static/dpubimg/38652040-2fbf-435b-aeff-563666c4021c.png) - -*Mpx跨平台开发流程示意图* - -Mpx跨平台能力设计思路明显区别于业内已有的其他小程序跨平台框架，主要差异在于： -* Mpx以小程序本身的DSL作为基准，而没有使用web框架(React,Vue)的DSL； -* Mpx主要通过编译和运行时转换的方式处理平台差异，没有提供额外的差异抹平层(基础组件库等)。 - -之所以采用这种设计，主要基于以下原因： -* Mpx主要以跨小程序平台为目标，目前各大小程序平台的技术规范具有一定相似性，绝大部分平台差异能够通过编译和运行时手段抹平，同时省去的差异抹平层也能够进一步减少框架运行时体积； -* 使用小程序本身的DSL作为基准允许用户直接在已有项目中使用跨平台能力，对于原生小程序项目或组件也能够使用该能力进行跨平台输出； -* 结合完善的条件编译支持，该方案能够在满足用户跨平台需求的同时仍然允许用户最大限度地使用各个小程序平台提供的能力，完全延续了Mpx增强的核心设计理念。 - -### 使用方法 - -Mpx跨平台开发的使用方式非常简单，用户只需在MpxWebpackPlugin创建时传入mode和srcMode参数指定源平台和目标平台，当srcMode和mode不一致时，框架会读取相应的配置对项目进行编译和运行时转换。 - -```js -// 微信转支付宝 -new MpxWebpackPlugin({ - // mode指定目标平台，可选值有(wx|ali|swan|qq|tt) - mode: 'ali', - // srcMode指定源码平台，默认值同目标平台一致 - srcMode: 'wx' -}) -``` - -### 差异抹平 - -目前各大厂商的小程序技术规范在宏观层面上大致保持一致，但是技术细节方面存在很多差异，大致划分为以下几个部分： -* 模板语法/基础组件差异 -* json配置差异 -* wxs语法差异 -* 页面/组件对象差异 -* api调用差异 -* webview bridge差异 -* 外部样式类 - -其中，对于模板语法/基础组件、json配置和wxs中的静态差异，我们主要通过编译手段进行转换处理，对于这部分差异中无法转换的部分会在编译阶段报错指出；而对于页面/组件对象、api调用和webview bridge中js运行时的差异，我们主要通过运行时手段进行处理，对应的无法转换部分也会在运行时中报错指出。 - -值得注意的是，我们在跨平台转换中做的工作不仅是对可转换的技术标准进行转换映射，对于一些目标平台中不存在的能力，我们也尽可能地通过编译和运行时手段提供了模拟和支持，最大限度地减少用户在跨平台开发中需要付出的额外工作量。以差异性最大但现实场景也最多的微信转支付宝为例，Mpx模拟提供了许多微信中支持但支付宝中未支持的能力： -* 组件自定义事件 -* 组件间关系 -* 获取子组件实例 -* observers/property observer -* 内联wxs - -对于原生自定义组件的跨平台转换，我们会对其进行简单的运行时注入，使其能够使用Mpx框架提供的运行时转换能力。 - -### 条件编译 - -对于框架无法抹平的差异部分，会在编译和运行时报错指出，对于这部分错误，我们提供了完善的条件编译机制让用户能够自行编写目标平台的patch进行修复，该能力也能用于实现具有平台差异性的业务逻辑。 - -上文中提到Mpx通过读取用户传入的mode和srcMode来决定是否以及如何对项目进行转换，mode和srcMode分别代表整个项目构建的目标平台和源平台，条件编译能够让用户在项目中创建声明了自身平台属性(localSrcMode)的文件和代码块。在项目构建中，框架会优先加载带有localSrcMode声明且localSrcMode与项目目标平台匹配(localSrcMode===mode)的文件和代码块，这部分文件和代码块需要完全依照自身声明的平台标准进行编写，Mpx不会对其进行任何编译和运行时的跨平台转换。 - -Mpx提供了三种维度的条件编译，分别是文件维度，区块维度和代码维度，用户可以根据平台差异的覆盖范围灵活选择使用。 - -## 性能优化 - -Mpx框架专注于小程序开发，在性能优化方面我们做过很多尝试和努力，主要集中在两个方面： -* 运行时的setData优化 -* 编译构建时的包体积优化 - -### setData优化 - -数据响应是Mpx运行时增强的核心能力，该能力让用户在小程序开发中能够像Vue中一样使用watch和computed特性，并且用直接赋值的方式操作数据驱动视图更新，而不需要手动调用setData方法，换言之框架接管了小程序中的setData调用。 - -通过各大小程序平台的设计原理和性能优化建议可以得知，setData对于小程序的性能表现非常重要，而setData优化的两大方向在于： -* 尽可能减少setData调用的频次 -* 尽可能减少单次setData传输的数据 - -为了实现setData的优化，我们在模板编译过程中对于每个组件的模板都生成了一个渲染函数(render function)，该函数模拟模板的渲染逻辑，在每次执行时访问当次渲染所需的数据，并将当次访问过的数据路径记录下来作为函数返回值返回。 - -在运行时，框架会在每个组件创建时创建一个render watcher，该watcher追踪渲染函数，当渲染依赖数据发生变更时异步执行渲染函数，在render watcher回调中得到渲染函数返回的数据路径，基于这些路径与上一次的缓存数据进行diff比对，过滤掉未发生变化的数据后得到最小必要数据，最后调用setData将最小必要数据发送到真实的小程序渲染层更新视图。 - -基于这个机制，当数据发生变更时，只有当前渲染依赖的那部分数据发生变更才会异步地触发render watcher的执行，而每次执行后也只有实际发生变更的那部分数据会被setData发送到渲染层。这样用户就能自由地根据业务需求来操作数据，无需关注setData的调用优化，框架能够自动进行程序上最优的setData调用，在提升用户开发体验的同时也提升了程序性能。 - -在1.x版本中，渲染函数内无法执行wxs的逻辑，对于含有wxs的组件有可能降级到全量设置数据的模式，在2.0版本中，我们将wxs模块转译处理为js可执行的代码后注入到js bundle中，含有wxs的渲染函数也能够正常访问并执行wxs逻辑。 - -![setData优化示意图](https://dpubstatic.udache.com/static/dpubimg/9ead35f1-693f-44f4-beb3-f98555ab6861.png) - -*setData优化示意图* - -### 包体积优化 - -类似于运行时对于setData的接管，Mpx在编译阶段接管了项目的资源管理。得益于webpack强大的插件机制，Mpx开发了一个深度定制的webpack插件，基于webpack完成小程序的打包构建工作。用户在使用Mpx开发小程序时可以不受限制地使用npm依赖、最新的es特性和css预处理器等现代web开发能力。与此同时，Mpx在包体积优化上也做了很多工作，让用户专注于业务开发而无需花费过多精力进行包体积管理，我们所做的优化工作如下： -* 打包构建工作完全基于依赖分析，任何没有被引用的资源都不会出现在dist当中； -* 对于npm组件和页面的构建也完全基于依赖分析按需打包，不会copy整个miniprogram_dist目录，也不需要执行构建npm，使用体验和包体积均优于微信小程序自身的npm支持方案； -* 基于webpack提供的能力进行公共模块抽取和代码压缩等优化工作； -* 完善的分包支持，对所有资源进行从属分析，将所有分包only的资源都输出到分包目录中。 - -分包作为微信小程序中优化包体积的核心手段(类似于异步按需加载)，Mpx对其进行了完善的支持。为了精确地标记出分包only的资源，我们在构建时将主包和分包的依赖收集步骤拆分开来串行处理，先处理主包，再处理分包。在主包的处理过程中，将主包页面中引用的所有非js资源(组件、外部样式、外部模板、wxs，图像媒体等)都记录下来，在处理分包时，对分包内引用的非js资源都进行检查，如果被主包引用过则输出到主包中，否则标记为分包only的资源输出到分包目录下。 - -对于js模块资源，我们在脚手架中生成的构建配置中提供了辅助函数，便于用户进行分包bundle的配置，经过该配置后，分包only的公用模块会被打入分包bundle输出到分包目录下，其余的公共模块会正常打入主bundle中。 - -在跨平台开发中，我们建议用户使用Mpx提供的[packages](https://didi.github.io/mpx/single/json-enhance.html#packages)来定义分包，这样在转换到不支持分包的小程序平台时会自动降级为同步包进行处理。 - -![分包构建示意图](https://dpubstatic.udache.com/static/dpubimg/3121ca4e-1b47-43bc-992a-b351c4a03da4.png) - -*分包构建示意图* - -## 渐进迁移 - -Mpx提供了良好的渐进迁移支持，对于使用原生或其他小程序框架的开发者来说，采用渐进迁移的方式逐步引入Mpx进行开发成本并不大。 - -在2.0版本中我们进一步完善了Mpx的原生兼容性，跟进支持了各个小程序平台最新的技术能力，如自定义tabbar，分包预加载，workers，云开发等能力，同时补齐了一些1.x版本遗漏的支持。得益于此，对于使用原生小程序开发的开发者来说，迁移Mpx的成本几乎为0，用户只需将对应页面组件的构造函数替换为Mpx提供的createPage/createCompnent，即可使用Mpx提供的各种增强能力。 - -对于使用其他框架的开发者，Mpx也提供了局部构建的机制，允许用户将特定的页面和组件单独构建输出为原生组件，用户只需手动或者编写脚本输出的原生组件整合进原有项目中即可。 - -## 使用现状 - -众所周知，Mpx自诞生以来在公司内部得到了广泛使用，建立起了完善的生态，开源后也支撑了数个外部小程序的迭代开发。目前WebApp团队正在对滴滴出行微信小程序进行功能升级，进行产品功能拉齐及界面与体验优化。升级后的版本预计会在6月中旬上线，届时微信钱包内的滴滴出行会逐步切换到小程序版本上。与此同时，我们也在使用Mpx2.0的跨平台能力同步产出支付宝小程序，目前进展顺利。登录sdk，收银sdk，地图sdk等公共组件目前也已经基于2.0的跨平台能力产出了支付宝版本，支付宝版本小程序也会随微信小程序一起发布生效。 - -## 未来规划 - -作为公司内部小程序生态的基础设施，我们会对Mpx框架进行长期的维护更新，确保能在第一时间支持各个小程序平台最新的技术特性。与此同时，我们也会进一步完善框架的基础能力，目前已排上日程待支持能力包括： -* i18n -* ts支持 -* 单元测试支持 - -在跨平台能力方面，我们也会根据社区的反馈和建议，以及小程序的标准化进程，对其进行持续的完善与更新。 - -最后，如果你专注小程序开发，关注开发体验和产品性能，那Mpx会是你最好的选择。 - diff --git a/docs/articles/details.md b/docs/articles/details.md deleted file mode 100644 index 53a65ca7df..0000000000 --- a/docs/articles/details.md +++ /dev/null @@ -1,55 +0,0 @@ -#### 文件维度条件编译 - -文件维度条件编译让用户能够以文件为维度进行跨平台差异代码的编写，例如在微信转支付宝的项目中存在框架无法转换的组件map.mpx，用户可以在相同的目录下创建map.ali.mpx文件作为patch，在该文件中使用支付宝的技术标准来源组件map.mpx中必要的功能，在项目mode为ali时Mpx会加载map.ali.mpx来代替原有map.mpx文件。 - -文件维度条件编译能够与webpack alias结合使用，对于npm包中的无法转换的文件，我们不方便在包目录中创建patch文件(npm i等操作会重写整个包目录)，此时我们可以通过webpack alias在包目录中创建一个`虚拟的`patch文件，并将其指向项目的源码目录中。 - -```js - // 对于npm包中的文件依赖 - import map from 'npmPackage/lib/map' - - // 配置以下alias后，当mode为ali时，会加载项目目录中的projectRoot/src/patch/map文件以代替原有的npmPackage/lib/map文件 - const webpackConf = { - resolve: { - alias: { - 'npmPackage/lib/map.ali': 'projectRoot/src/patch/map' - } - } - } -``` - -#### 区块维度条件编译 - -在.mpx单文件中一般存在template、js、style、json四个区块，Mpx支持以区块为维度进行条件编译，只需在区块标签中添加`mode`属性定义该区块的平台属性即可，其余规则与文件维度条件编译一致，可以将区块理解为.mpx单文件中的局部文件。 - -```html - - - - - -``` - -#### 代码维度条件编译 - -对于局部平台差异，mpx支持在template插值和js代码中访问`__mpx_mode__`获取当前项目的目标平台，结合条件语句if/else进行局部条件编译，如果条件表达式结果可在编译中推断得出，例如`__mpx_mode__ === 'ali'`，框架会在优化阶段删除不可到达的无用代码。 - -js代码中使用 -```js -if(__mpx_mode__ === 'ali') { - // 执行支付宝环境相关逻辑 -} else { - // 执行其他环境相关逻辑 -} -``` -template插值中使用 -```html - -支付宝环境 -其他环境 -``` diff --git a/docs/articles/index.md b/docs/articles/index.md deleted file mode 100644 index 770b5b9d3a..0000000000 --- a/docs/articles/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Mpx框架相关介绍文章 - -* [滴滴开源小程序框架Mpx](1.0.md) -* [滴滴开源小程序框架Mpx发布2.0，完善支持小程序跨平台开发](2.0.md) diff --git a/docs/articles/mpx1.md b/docs/articles/mpx1.md deleted file mode 100644 index d10705c735..0000000000 --- a/docs/articles/mpx1.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: 小程序开发者，为什么你应该尝试下MPX -date: 2019-05-26 17:45:56 -tags: MPX -categories: 前端 ---- - -> MPX框架是滴滴出行推出的一款专注小程序开发的增强型框架。本篇文章将从使用角度谈谈MPX的优势与好处。如果嫌内容太长，优势部分每个小节都有简单的一句话总结，可以快速阅读。如果想了解更多设计细节，可以阅读 [前一篇文章 - MPX2.0发布](https://didi.github.io/mpx/articles/2.0.html)。 - -## 背景 - -在小程序逐渐火热的今天，越来越多的开发者需要进行小程序的开发。原生小程序的开发有诸多不便，开发者又需要在众多的小程序框架中做出抉择。 - -那么今天，我们要给大家安利一款小程序框架：MPX - -## 优势 - -之所以建议开发者们考虑使用MPX框架来开发小程序，是因为MPX框架具有一些别的框架所没有的优点。 - -MPX立足原生小程序，在保证坑少的同时做了很多能力增强，提供了数据响应、模板增强、性能优化、跨平台开发等能力，以提升用户的开发体验及效率。 - -接下来会从 原生兼容 -> 第三方组件支持 -> 按需构建 -> 跨平台编译 -> 能力增强 -> 独特性能优势 六个点来逐一讲述。 - -### 原生兼容 - -> MPX完全兼容原生，坑少。渐进接入简单。 - -从语法风格上，我们可以看到目前市面上流行的小程序框架基本是基于web框架（taro/nanachi - react，uniapp/megalo/mpvue - vue）或者是一套全新（chameleon）/ 半全新（wepy）的标准。 - -使用了这些框架，你所写的代码，并不是小程序代码。而是react/vue或者另一套代码。而这些代码源码到小程序代码，需要经过一次全面的转换，这个转换可能会引入一些未知的问题，产生一些坑。 - -同时随着时间，小程序自身会逐步迭代，做出更多的功能特性，提供更好的组件、方法。而一些框架可能会受限于精力或框架节奏，没有办法第一时间跟进，甚至框架慢慢疏于维护而无法使用。 - -而MPX选择的是，**全面拥抱原生**。 - -口说无凭，我们来看个典型的MPX组件长什么样。 - -![mpx组件示例](https://dpubstatic.udache.com/static/dpubimg/3877c653-d180-4fe7-8661-457b9de1bd82.png) - -乍一看好像和vue没什么区别，也就多了个json块，template里写的是小程序的标签。 - -由于这一块全是符合微信小程序原生语法，我们是不会做任何转换的，所以你写什么就是什么。（如果使用了MPX的增强特性，还是会进行一些必要的转换的，后续我们也会出文章详细解释MPX的增强是如何实现的，相对来说，我们的转换比较轻量、透明、易理解） - -当微信出了新的能力、新的标签、新的生命周期钩子，使用MPX框架来编写的小程序只需要直接用起来就行。 - -所以，使用MPX框架，你可以轻易地使用 **[自定义组件的relations](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/relations.html)** 来搞定组件间关系，使用 **[wxs](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxs/)** 来更好地构建页面。 - -MPX几乎支持原生的每一个特性，在 .mpx 文件里，模板部分写的是原生小程序的模板语法，脚本部分写的是原生小程序的脚本语法，json部分写的是原生小程序的配置信息。用MPX，你才是真的在开发小程序。 - -目前很多原生小程序开发者可能想尝试下框架，老项目接入框架，选MPX肯定是最简单的了。口说无凭，我们搞了个demo来给大家打个样：在我们GitHub项目中有examples文件夹，里面的 [原生项目渐进接入MPX示例](https://github.com/didi/mpx/tree/master/examples/mpx-progressive) 。 - -### 第三方组件库 - -> MPX提供了完备的第三方组件库支持 - -上面说了MPX对原生的极致兼容，能让你想到什么？对，就是对第三方组件库的完美支持。 - -支持第三方组件库的重要性大家都知道，所以这个能力大部分框架都支持了。但是支持和完美支持还是有区别的。据简单观察，taro/mpvue/uniapp对于第三方组件库的支持都是以复制的形式进行的，也就是和微信小程序本来的行为很像。 - -那么MPX是怎么支持第三方组件库的呢，这里有个demo：也在我们的GitHub里的examples文件夹下，[MPX使用第三方组件库示例](https://github.com/didi/mpx/tree/master/examples/mpx-useuilib) ，核心代码见下图： - -![MPX使用第三方组件库代码示例](https://dpubstatic.udache.com/static/dpubimg/9ecdd898-f7e5-48cc-89c2-bfc7ce3a03f9.png) - -乍一眼看不太出来有什么特别的？没用过别的框架引第三方组件，简单找了找其他框架好像也没提供相应的demo，用过的朋友可以自行对比下。 - -在MPX里使用第三方组件库，仅需要***像web项目一样npm安装即可，并不需要复制文件***。然后在json里直接写包名就会去node_modules下面查找了。再配合webpack alias可以做到更简单、更语义化。 - -然而这还没有结束~ - -细心的朋友会发现，这段示例代码中既有vant的组件，也有iview的组件，如果按照微信的规范，这些组件库会通过miniprogram字段指定自己的构建文件生成目录，开发者工具会把这个目录完全拷贝到最终发布的代码里去，我们就会有两个巨大的组件库占据宝贵的空间。 - -我们当然是希望用多少引多少，而不是一股脑全引进去，对，于是MPX提供了按需引用的能力，在下一章[按需引用](#按需引用)细讲。 - -以及，组件库目前很少有跨小程序平台的组件库啊，如果我用了vant，支付宝、QQ里没有vant怎么办？也许这是别的框架不怎么推荐使用第三方库的原因，而MPX里，我们帮你把别人的组件库也转了，细节看下下章[跨小程序平台](#跨小程序平台) - -### 按需引用 - -> 通过webpack依赖分析收集，使用第三方组件库或者拆分开发大型项目时MPX能保证构建的代码全是要用到的代码 - -原生小程序本身的编译是遍历项目文件夹里所有的JS，包装成一个AMD包，也就是说项目文件夹里所有的文件，不论是否被使用，都会占用包体积并上传。 - -同时，原生微信小程序的npm支持是基于文件夹复制的，第三方包通过声明miniprogram字段指定要拷贝的文件夹，不论使用还是未使用的资源（模板/js/样式/图片），全会被复制到项目文件夹中。 - -而我们提供了@mpxjs/webpack-plugin插件，借助webpack生态，解析.mpx文件的json部分或原生的json文件将依赖作为新的入口添加子编译。基于依赖收集，而不是文件遍历。 - -带来的好处就是：如果你喜欢vant的按钮，iview的输入框，wux的布局，欢迎尝试MPX，让你能同时使用多个UI框架的同时不用担心应用的体积爆炸。 - -同理，面对一个大型项目，我们可以拆成不同的部分，由不同的团队完成后发npm包，在一个主项目中引入即可，具体内容可以看文档[JSON增强 - packages](https://didi.github.io/mpx/single/json-enhance.html#packages)一节。 - -收集依赖的细节可以查阅文档[编译构建](https://didi.github.io/mpx/understanding/understanding.html#%E7%BC%96%E8%AF%91%E6%9E%84%E5%BB%BA)一节。 - -### 跨小程序平台 - -> MPX的跨平台方法能带着第三方组件库一起跨小程序平台，同时提供了充足完善的条件编译能力。 - -在 MPX 1.0 时代，MPX框架是专注提升微信小程序的开发体验，虽然也提供了支付宝版，但代码完全要另写。 - -而随着越来越多的 super app 提供了小程序能力，目前至少有5种体系的小程序（微信、支付宝系列、百度系列、头条系列、QQ），如果每一个平台都需要维护一份代码，工程师人数明显不够用了，所以跨小程序平台的能力也是 MPX 2.0 的主打特性。 - -我们的跨平台的方法就是转换。都是小程序，语法基本一样，配置、钩子的差异在MPX运行时里提供了抹平。 - -而除此之外最大的区别也就是模板上的标签和指令。所以我们实现了一套转换的架子，再编写一份转换规则，即可完成微信小程序到支付宝、百度、头条小程序的转换。 - -采用这种转换的模式，非常方便用户理解我们是如何把微信小程序转换成支付宝、百度等小程序平台的。而且只要用户有需求，可以补齐任一套小程序转换其他平台的规则，就可以完成以某个小程序为标准为基础来编写小程序代码以及进一步转换成别的平台的能力。 - - -再结合前面一直在说的我们对原生小程序的支持，就可以撞出一点不一样的东西，比如，前文提到的第三方组件库跨小程序平台。 - -对，我们能帮你把针对微信编写的ui组件库在支付宝、百度上运行起来，带着组件库一起跨小程序平台。 - -那么一定会有这样一个问题，就算MPX对原生的支持再怎么牛逼，有的基础能力只有微信平台有，别的平台没有，MPX的转换还能无中生有吗？ - -当然不能，其实这个问题对于所有的跨端框架都是一个问题，所以跨端最核心的问题是，如何搞定差异化部分。 - -MPX提供了丰富的条件编译能力，可以以文件为维度差别构建，可以以代码块为维度，也可以以代码维度进行差别构建。 - -而且MPX的差异化构建能力也是完全基于webpack实现的，所以上面提到的第三方组件库如果确实存在转换不了的地方，比如vant的picker组件使用内联wxs写了一个小方法叫isSimple在模板里调用了，但是这个方法的写法在百度小程序的filter脚本（filter可以理解为百度小程序的wxs）里不支持，因为百度的filter要求必须导出一个对象包裹方法。 - -最好的解决办法当然是给vant-weapp提pr帮他们解决一下这个问题，但时间可能会比较慢，所以在MPX里，可以利用webpack的alias能力： - -![通过alias解决第三方组件的跨平台问题](https://dpubstatic.udache.com/static/dpubimg/7f90593b-65b4-40d0-bd93-6396e8a18e64.png) - -当尝试构建百度小程序时，会优先去查找pick/index.swan.wxml，再被alias到一个src下的文件，自己修改一下第三方包里有一些小问题的部分即可。 - -关于跨平台的条件编译，更多具体信息可以[查阅我们的官方文档 - 跨平台条件编译](https://didi.github.io/mpx/platform.html#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E7%BC%96%E8%AF%91) - -### 能力增强 - -> 通过数据响应、编译时预处理提供了computed/watch，完备的样式类型绑定，双向数据绑定，动态组件等一系列方便开发者更好开发小程序的能力增强 - -能力增强应该是一个框架提供的最核心最重要的能力了，而MPX也确实在这里下了很大的力气，提供了多且好用的能力增强，不过受限于此处的篇幅，就只简单介绍，细节大家还是[查阅我们的文档](https://didi.github.io/mpx/single/template-enhance.html#template%E5%A2%9E%E5%BC%BA%E7%89%B9%E6%80%A7)的好。 - -别的框架由于往往基于react/vue的，会给个列表写明不支持哪些能力，用户写的时候习惯使然，往往用了后可能才反应过来哦这个不支持。MPX则是原生的小程序语法写着难受时候突然想起MPX有这个能力。 - -列一下MPX增强的能力： - -- 模板上的增强 - - 样式类名绑定 - - 内联事件传参 - - 动态组件 - - 双向绑定 - - 节点获取ref -- JS里的增强 - - 数据响应 - - setData优化 - - ES6+ -- 样式上的增强 - - 预处理支持 - - rpx转换 -- JSON里的增强 - - packages - - 分包资源优化 - -MPX最显著的能力是数据响应，它衍生出computed/watch，以及双向数据绑定等。这个能力和Vue比较像，不同的是在MPX里是由mobx提供的数据响应能力。 - -而同样是数据响应，我们做了一些不一样的优化。 - -### 性能优势 - -> 通过对模板的解析抽象出访问的数据以保证在提供了数据响应能力的同时不至于劣化性能。 - -mpvue/wepy/megalo等框架也提供了数据响应的能力，但是数据响应在小程序领域有个较大的问题，微信开发指南里明确提到要注意setData的调用频次和数据量的大小。 - -而数据响应最基本的做法就是数据变了就去set数据，这会极大劣化小程序的性能表现。 - -而MPX通过对模板进行解析，抽象出对应的render函数，在调用setData发送数据前执行render函数找到真正需要发送的数据。 - -效果如图： - -![小程序性能分析](https://dpubstatic.udache.com/static/dpubimg/9399b75c-5c81-4584-89b6-5e7f2c2ba7ba.png) - -小程序开发者工具的audits面板能辅助用户分析出可能需要优化的点。正如前文所说，MPX在红框部分，尤其是红框里的第三条，不将模板上未使用的数据发送到渲染层上做了极大的优化。 - -只要不出现渲染函数执行失败（会有warning在console里提示，同时兜底逻辑会进行全量setData以保证程序仍可正常运行），使用MPX开发的小程序就永远不用担心发送了模板未使用的数据。 - -虽然只是一个小小的TODO MVC示例，但是这个优化和应用的规模没关系，而且同时大家可以尝试别家的小demo对比看看。 - -这个优化的细节可以看[前一篇文章](https://didi.github.io/mpx/articles/2.0.html)，或者我们的文档[MPX运行机制 - 数据响应与性能优化](https://didi.github.io/mpx/understanding/understanding.html#%E6%95%B0%E6%8D%AE%E5%93%8D%E5%BA%94%E4%B8%8E%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96) - -## 总结 - -与目前市面上的诸多框架相比，MPX希望以原生小程序为基础，全面拥抱原生小程序，在原生小程序的基础上做增强，通过尽可能少的转换实现尽可能多的能力增强，在提升小程序开发体验的同时，保证不因转换或框架的问题产生过多的坑。 - -MPX框架的目标用户是对小程序质量有较高要求的开发者，如果你是原生小程序开发者，或者厌倦了解决某些以web框架DSL语法为基础的转换框架造成的坑，欢迎尝试MPX框架。 diff --git a/docs/assets/dingding.jpg b/docs/assets/dingding.jpg deleted file mode 100644 index bef5e0299a..0000000000 Binary files a/docs/assets/dingding.jpg and /dev/null differ diff --git a/docs/book.json b/docs/book.json deleted file mode 100644 index 67876c5996..0000000000 --- a/docs/book.json +++ /dev/null @@ -1,38 +0,0 @@ -{ - "title": "mpx文档", - "author": "滴滴出行webapp团队", - "description": "mpx是一款增强型小程序框架，极致性能优化，提供双向数据绑定，样式绑定，方法内联传参等方便开发者使用的特性。", - "structure": { - "readme": "intro" - }, - "plugins": ["github", "edit-link", "anchors", "copy-code-button", "github-buttons", "expandable-chapters-small", "insert-logo", "custom-favicon"], - "pluginsConfig": { - "favicon": "favicon.ico", - "github": { - "url": "https://github.com/didi/mpx" - }, - "edit-link": { - "base": "https://github.com/didi/mpx/tree/master/docs", - "label": "完善文档" - }, - "github-buttons": { - "buttons": [{ - "user" : "didi", - "repo" : "mpx", - "type" : "star", - "size" : "small", - "count": true - }, { - "user" : "didi", - "repo" : "mpx", - "type" : "fork", - "size" : "small", - "count": true - }] - }, - "insert-logo": { - "url": "https://dpubstatic.udache.com/static/dpubimg/cd8de8e4-e4f4-4f0a-9c53-f833bc30ba69.png", - "style": "background: none; width: 200px" - } - } -} diff --git a/docs/compilationEnhance/index.md b/docs/compilationEnhance/index.md deleted file mode 100644 index a01c4ac1a3..0000000000 --- a/docs/compilationEnhance/index.md +++ /dev/null @@ -1,184 +0,0 @@ -# 构建配置 - -mpx深度定制开发了一个webpack插件`@mpxjs/webpack-plugin`，基于该插件使用webpack进行小程序的编译构建工作。 - -## 自动配置 -如果你不熟悉webpack，可以通过脚手架进行[快速配置](../start.md)。 - ----- - -## 手动配置 - -**webpack.config.js** -```js -var MpxWebpackPlugin = require('@mpxjs/webpack-plugin') - -var webpackConfig = { - module: { - rules: [ - // mpx文件必须设置正确的loader，参考下文详细的loader设置options - // 注意，在最新的脚手架生成的模板中，这个loader的配置在build/build.js中 - { - test: /\.mpx$/, - use: MpxWebpackPlugin.loader({ - transRpx: [ - // 可以是对象也可以是数组，数组可以通过include/exclude对不同资源配置不同的转换 - { - // `only`模式下，样式前加上注释/* use rpx */可将该段样式中所有的px转换为rpx - mode: 'only', - comment: 'use rpx', - include: resolve('src') - }, - { - // 对某些第三方组件库另设转换规则 - mode: 'all', - designWidth: 375, - include: resolve('node_modules/vant-weapp') - } - ] - }) - }, - // 对本地图片资源提供增强，编译成小程序支持的格式 - // 参考下文详细的设置 - { - test: /\.(png|jpe?g|gif|svg)(\?.*)?$/, - loader: MpxWebpackPlugin.urlLoader({ - name: 'img/[name][hash].[ext]' - }) - } - ] - }, - // mpx主插件，必须设置，参考下文详细的插件设置options - plugins: [ - new MpxWebpackPlugin({ - // 微信模式下设置为`wx`，支付宝模式下设置为`ali` - mode: 'wx' - }) - ], - // sourceMap: 小程序不支持eval，因此不要设置为eval相关的sourceMap类型。 - // 注意：webpack4新增的mode属性设置为development的时候，会将devtool默认设置为eval， - // 必须手动设置devtool为非eval相关类型来覆盖默认配置 - devtool: false, - output: { - // filename设置不能更改 - filename: '[name].js' - }, - // 通过webpack分包能力减少小程序体积，参考下文的详细介绍 - optimization: { - runtimeChunk: { - name: 'bundle' - }, - splitChunks: { - chunks: 'all', - name: 'bundle', - minChunks: 2 - } - } -} -``` ----- -### @mpxjs/webpack-plugin - -**webpack.config.js** -```js -var MpxWebpackPlugin = require('@mpxjs/webpack-plugin') - -webpackconfig = { - plugins: [ - // 在脚手架生成的项目中，mpx-webpack-plugin是在在build/build.js里插入的，但是配置项可以在build/mpx.plugin.conf.js中填写，有简单的注释说明 - new MpxWebpackPlugin(options) - ], -} -``` -#### options - -- **mode** `String` 目前支持的有微信小程序(wx)\支付宝小程序(ali)\百度小程序(swan)\头条小程序(tt)\QQ小程序(qq)\H5页面(web) -- **srcMode** `String` 跨平台编译场景下使用，详情请看 [跨平台编译](../platform.md#跨平台编译) 一节 -- **resolveMode** `String` 默认值为webpack，可选值有webpack/native，这是解析依赖路径时为了解决小程序特色绝对路径所添加的，推荐使用webpack模式，更舒服一些，json中的pages/usingComponents等需要写相对路径，但是可以直接写npm包路径。如果希望使用类似小程序原始那种"绝对路径"，就可以声明为native，但是npm路径就需要在前面加一个~，类似webpack的样式引入规范，同时必须配合projectRoot参数提供项目根目录地址。 -- **projectRoot** `String` 如果指定resolveMode为native，则必须提供此项配置为项目根目录地址。 -- **writeMode** `String` 小程序开发者工具检测到文件'变化'就会重新编译，并不会关系文件内容是否真正变化，而webpack每次输出都是全量的，会导致项目大了后每次重编译都较慢，为了解决这个问题，在输出前在内存中对比一次剔除未变化的文件，仅输出变化的文件以提升小程序开发者工具的编译速度。建议开启。 -- **modeRules** `Object` mpx在应用条件编译时，可能会遇到这种场景，假设同时开发微信/支付宝两个平台，用户是以微信小程序为基准来编写代码的，但是又有一个平台差异较大的地方，在支付宝平台上期望用一份支付宝原生代码来实现，这份支付宝原生代码可能在一个npm包内或者在某个文件夹下，依照mpx默认的识别方式，需要对这些文件都加中缀.ali才可以正确识别，而通过modeRules我们可以直接声明某个路径下的文件全是某种mode。 -- **enableAutoScope** `Boolean` 支付宝小程序没有微信小程序类似的组件样式隔离机制，如果遇到样式问题，将本选项置为true将自动为支付宝添加scope，会带来略微的体积上涨 -- **defs** `Object` 给模板和json中定义一些全局环境变量，区别于webpack.DefinePlugin的是仅支持普通扁平对象，但支持小程序的4个文件。这样根据平台注入全局变量时能为4个文件都注入，而不仅仅是JS，以此来实现编译时去除多余的其他平台的代码。 -- **i18n** `Object` 多语言能力，提供多语言包，在编译时生成对应的wxs方法，以完善小程序的国际化能力。 - -示例： - -```js -new MpxWebpackPlugin({ - mode: 'ali', // 可选值 wx/ali/swan/qq/tt/web - srcMode: 'wx', // 暂时只支持微信为源mode做跨平台，为其他时mode必须和srcMode一致 - writeMode: 'changed', // 可选值changed / full，不建议修改 - resolveMode: 'webpack', // 可选值 native / webpack - projectRoot: resolve('src'), // 若resolveMode为native才需要传这个以指定项目的“绝对路径”绝对于谁的 - enableAutoScope: false, // 是否开启支付宝样式scope，会带来略微的体积上涨 - defs: { - // 常量 仅支持扁平对象，内嵌的环境变量有__mpx_mode__和__mpx_src_mode__ - apiHost: 'apitest.com' // 可以准备多个对象，在build.js里根据参数决定塞哪个以实现开发时用某一套，上线时用哪一套 - }, - i18n: {}, // 多语言 参考 https://didi.github.io/mpx/i18n.html - modeRules: { - // 批量指定文件mode，和webpack的rules相同 - ali: { - include: [resolve('vant-aliapp')] - } - } -}) -``` - ----- - -### MpxWebpackPlugin.loader - -`@mpxjs/webpack-plugin`暴露了一个静态方法`MpxWebpackPlugin.loader`作为`.mpx`文件的loader - -**webpack.config.js** -```js -var MpxWebpackPlugin = require('@mpxjs/webpack-plugin') - -webpackconfig = { - module: { - rules: [ - { - test: /\.mpx$/, - use: MpxWebpackPlugin.loader({ - transRpx: {} - }) - } - ] - } -} -``` - -- **transRpx** - `Object | Array | boolean | string` - - `false`关闭转换rpx - - `'all'`普通样式中的px全部转换为rpx，`rpx注释样式`不转换 - - `'only'`普通样式中的px全部**不转换**为rpx，`rpx注释样式`转换 - - Object包含属性：mode/comment/designWidth/include/exclude - > include/exclude属性的用法和webpack对module.rules里的规则是一样的，参考[webpack文档-exclude](https://webpack.js.org/configuration/module/#rule-exclude) - -该loader用于处理.mpx单文件，并可以通过options控制mpx框架提供的rpx转换能力。详情见 [rpx转换](/single/style-enhance.md#rpx转换) - -### @mpxjs/url-loader - -已废弃，功能全部收集到 @mpxjs/webpack-plugin 中。 - -> 想深入的了解mpx框架对小程序对图片资源的支持，查看[mpx图像资源处理](/understanding/resource.md)了解更多细节 - -### output.filename - -小程序限定[描述页面的文件具有相同的路径和文件名](https://developers.weixin.qq.com/miniprogram/dev/framework/structure.html)，仅以后缀名进行区分。 - -因此`output.filename`中必须写为 **`[name].js`**，基于chunk id或者hash name的filename都会导致编译后的文件无法被小程序识别 - -**webpack.config.js** -```js -webpackconfig = { - output: { - filename: '[name].js', // 正确 - filename: '[id].js', // 错误。chunk id name - filename: '[name].[chunkhash].js' // 错误。hash name - } -} -``` diff --git a/docs/extend/index.md b/docs/extend/index.md deleted file mode 100644 index d63098b001..0000000000 --- a/docs/extend/index.md +++ /dev/null @@ -1,281 +0,0 @@ -# 扩展mpx - -## 目前已有插件 - -- 网络请求库fetch: @mpxjs/fetch [详细介绍](#fetch) [源码地址](https://github.com/didi/mpx/tree/master/packages/fetch) - -- ~~小程序api promisify：@mpxjs/promisify~~ (已废弃，推荐使用新的[api-proxy](#使用promise形式)) - -- 小程序API转换及promisify：@mpxjs/api-proxy [详细介绍](#api-proxy) [源码地址](https://github.com/didi/mpx/tree/master/packages/api-proxy) - -- mock数据：@mpxjs/mock [详细介绍](#mock) [源码地址](https://github.com/didi/mpx/tree/master/packages/mock) - -- 小程序中的webview的API抹平：webview-bridge [详细介绍](#webviewbridge) [源码地址](https://github.com/didi/mpx/tree/master/packages/webview-bridge) - -## 开发插件 - -mpx支持使用mpx.use使用插件来进行扩展。插件本身需要提供一个install方法或本身是一个function，该函数接收一个proxyMPX。插件将采用直接在proxyMPX挂载新api属性或在prototype上挂属性。需要注意的是，一定要在app创建之前进行mpx.use - -### 基础例子 - -扩展: test.js - -```js -export default function install(proxyMPX) { - proxyMPX.newApi = () => console.log('is new api') - proxyMPX - .mixin({ - onLaunch() { - console.log('app onLaunch') - } - }, 'app') - .mixin({ - onShow() { - console.log('page onShow') - } - }, 'page') // proxyMPX.injectMixins === proxyMPX.mixin - - // 注意：proxyMPX.prototype上挂载的属性都将挂载到组件实例（page实例、app实例上，可以直接通过this访问）, 可以看mixin中的case - proxyMPX.prototype.testHello = function() { - console.log('hello') - } -} -``` - -在app.js内使用插件 - -```js -import mpx from '@mpxjs/core' -import test from './test' -mpx.use(test) -mpx.createApp({ - onLaunch() { - mpx.newApi() // out put: "is new api" - this.testHello() // output: 'hello' - } -}) -``` - -## Fetch - -小程序request存在不限域名的并发限制，因此封装一个fetch来处理这种缺陷，能支持请求优先级，同时fetch还支持拦截器，请求取消等等 - - -### 使用说明 - -```js -import mpx from '@mpxjs/core' -import mpxFetch from '@mpxjs/fetch' -mpx.use(mpxFetch) -// 第一种访问形式 -mpx.xfetch.fetch({ - url: 'http://xxx.com' -}).then(res => { - console.log(res.data) -}) - -mpx.createApp({ - onLaunch() { - // 第二种访问形式 - this.$xfetch.fetch({url: 'http://test.com'}) - } -}) -``` - -### 导入api说明 - -mpx-fetch提供了一个实例 **xfetch** ，该实例包含以下api - -- fetch(config, priority)， 正常的promisify风格的请求方法, priority表示请求优先级（normal，low），默认为normal -- addLowPriorityWhiteList(rules)， 按域名规则设置低优先级请求的白名单，接收一个参数，可以是字符串，也可以是正则表达式，也可以是数组 (如果fetch传入了第二个参数，那么无视这个白名单) -- CancelToken，实例属性，用于创建一个取消请求的凭证。 -- create()， 用于创建一个新的mpx-fetch实例 -- interceptors，实例属性，用于添加拦截器，包含两个属性，request & response - -### 请求优先级 - -```js -mpx.xfetch.fetch({ - url: 'http://xxx.com', - data: { - name: 'test' - } -}, 'low') - -// or addSignWhiteList -mpx.xfetch.addLowPriorityWhiteList('http://xxx.com') -``` - -### 请求拦截器 - -```js -mpx.xfetch.interceptors.request.use(function(config) { - console.log(config) - // 也可以返回promise - return config -}) -mpx.xfetch.interceptors.response.use(function(res) { - console.log(res) - // 也可以返回promise - return res -}) -``` - -### 请求中断 - -```js -const cancelToken = new mpx.xfetch.CancelToken() -mpx.xfetch.fetch({ - url: 'http://xxx.com', - data: { - name: 'test' - }, - cancelToken: cancelToken.token -}) -cancelToken.exec('手动取消请求') // 执行后请求中断，返回abort fail -``` -### 支持 emulateJSON - -```js -mpx.xfetch.fetch({ - url: 'http://xxx.com', - method: 'POST', - data: { - name: 'test' - }, - emulateJSON: true // 等价于header = {'content-type': 'application/x-www-form-urlencoded'} -}) -``` - -### 支持 params -```js -mpx.xfetch.fetch({ - url: 'http://xxx.com', - params: { - name: 'test' - } -}) - -mpx.xfetch.fetch({ - url: 'http://xxx.com', - method: 'POST', - params: { - age: 10 - }, - data: { - name: 'test' - }, - emulateJSON: true // 等价于header = {'content-type': 'application/x-www-form-urlencoded'} -}) -``` - - -## API-PROXY - -> convert API at each end 各个平台之间 api 进行转换 - -## Usage - -```js -// 使用 mpx 生态 - -import mpx from '@mpxjs/core' -import apiProxy from '@mpxjs/api-proxy' - -mpx.use(apiProxy, options) -``` - -```js -// 单独使用 -import apiProxy from '@mpxjs/api-proxy' - -apiProxy(target, options) // target 为要抹平的对象 -``` - -## Options - -|参数名称|类型|含义|是否必填|默认值|备注| -|---|---|---|---|---|---| -|platform|Object|各平台之间的转换|否|{ from:'', to:'' }|使用 mpx 脚手架配置会自动进行转换，无需配置| -|exclude|Array(String)|跨平台时不需要转换的 api|-| -|usePromise|Boolean|是否将 api 转化为 promise 格式使用|否|false|-| -|whiteList|Array(String)|强行转化为 promise 格式的 api|否|[]|需要 usePromise 设为 true| - -## example - -#### 普通形式 - -```js -import mpx from '@mpxjs/core' -import apiProxy from '@mpxjs/api-proxy' - -mpx.use(apiProxy, { - exclude: ['showToast'] // showToast 将不会被转换为目标平台 -}) - -mpx.showModal({ - title: '标题', - content: '这是一个弹窗', - success (res) { - if (res.cancel) { - console.log('用户点击取消') - } - } -}) -``` - -#### 使用promise形式 - -```js -import mpx from '@mpxjs/core' -import apiProxy from '@mpxjs/api-proxy' - -mpx.use(apiProxy, { - usePromise: true -}) - -mpx.showActionSheet({ - itemList: ['A', 'B', 'C'] -}) -.then(res => { - console.log(res.tapIndex) -}) -.catch(err => { - console.log(err) -}) -``` - -## Mock - -mock数据生成规则同[mockjs](https://github.com/nuysoft/Mock/wiki) - -### 使用说明 - -```js -import mock from '@mpxjs/mock' -// rule 为字符串或正则表达式 -mock([{ - url: 'http://api.example.com', - rule: { - 'list|1-10': [{ - 'id|+1': 1 - }] - } -}]) -``` - -## webview-bridge - -Mpx支持小程序跨平台后，多个平台的小程序里都有webview组件，webview打开的页面和小程序可以通过API来通信以及调用一些小程序能力，但是各方webview提供的API是不一样的。 - -比如微信是用 wx.miniProgram.navigateTo 来跳转到别的小程序页面，而支付宝里是 my.navigateTo ，那么我们开发H5时候为了让H5能适应各家小程序平台就需要写多份对应逻辑。 - -为解决这个问题，Mpx提供了用于运行在小程序的webview里的H5抹平平台差异的bridge库：@mpxjs/webview-bridge - -使用方式很简单，不过注意这个库是给H5用的，不是给小程序用的。在H5项目中引入。 - -[使用示例](https://github.com/didi/mpx/tree/master/examples/mpx-webview) - -支持script标签引入和npm引入，标签引入的话，全局实例是mpx（npm模块使用下也鼓励import mpx from '@mpxjs/webview-birdge'），使用就例如 mpx.navigateTo ，能保持整个项目风格完全一致。 - -提供的API如下：`navigateTo, navigateBack, switchTab, reLaunch, redirectTo, getEnv, postMessage, getLoadError` diff --git a/docs/favicon.ico b/docs/favicon.ico deleted file mode 100644 index 891c2ce010..0000000000 Binary files a/docs/favicon.ico and /dev/null differ diff --git a/docs/i18n.md b/docs/i18n.md deleted file mode 100644 index fb6aa45318..0000000000 --- a/docs/i18n.md +++ /dev/null @@ -1,85 +0,0 @@ -# 国际化i18n - -Mpx支持国际化i18n，使用方式及支持能力与vue-i18n非常接近 - -## 使用方法 - -Mpx自带i18n能力，无需额外安装插件。由于小程序模板中的i18n函数是通过wxs编译注入进行实现，我们需要将i18n配置传入到MpxWebpackPlugin中来使i18n生效，这是与vue-i18n最大的区别 - -### 配置方法 - -i18n配置传入到MpxWebpackPlugin选项中即可生效，额外支持messagesPath/dateTimeFormatsPath/numberFormatsPath配置，其余配置参考vue-i18n - -```js -new MpxWebpackPlugin({ - i18n: { - locale: 'en-US', - // messages既可以通过对象字面量传入，也可以通过messagesPath指定一个js模块路径，在该模块中定义配置并导出，dateTimeFormats/dateTimeFormatsPath和numberFormats/numberFormatsPath同理 - messages: { - 'en-US': { - message: { - hello: '{msg} world' - } - }, - 'zh-CN': { - message: { - hello: '{msg} 世界' - } - } - }, - // messagesPath: path.resolve(__dirname, '../src/i18n.js') - } -}) -``` - -### 在js中使用 - -同vue-i18n，在组件中直接调用翻译函数使用，目前js中支持了vue-i18n中全部的翻译函数，包括$t/$tc/$te/$d/$n，详细使用方法参考vue-i18n - -```js -createComponent({ - ready () { - console.log(this.$t('message.hello', { msg: 'hello' })) - }, - computed: { - formatedDatetime () { - return this.$d(new Date(), 'long') - } - } -}) -``` - -### 在模板中使用 - -类似于vue-i18n，在模板的Mustache插值中直接调用翻译函数，目前由于wxs执行环境的限制，模板上可直接使用的翻译函数包括$t/$tc/$te，如果需要格式化数字或日期可以使用对应的js翻译函数和Mpx提供的计算属性结合实现 - -```html - - {{ $t('message.hello', { msg: 'hello' }) }} - - {{formatedDatetime}} - -``` - -### 动态变更locale -类似于vue-i18n，可实现全局local变更及局部local变更，并自动更新视图，使用方式如下 -```js -import mpx, { createComponent } from '@mpxjs/core' - -createComponent({ - ready () { - // 局部locale变更，生效范围为当前组件内 - this.$i18n.locale = 'en-US' - setTimeout(() => { - // 全局locale变更，生效范围为项目全局 - mpx.i18n.locale = 'ja-JP' - }, 1000) - } -}) -``` - -### 平台支持 - -由于Mpx中i18n实现依赖类wxs能力，目前支持除头条之外的所有小程序平台(微信/支付宝/qq/百度)，在输出web时，构建会自动引入vue-i18n并进行安装配置，无需修改任何代码即可按照预期正常工作。 - - diff --git a/docs/images/start-install.png b/docs/images/start-install.png deleted file mode 100644 index 4b9ee1922f..0000000000 Binary files a/docs/images/start-install.png and /dev/null differ diff --git a/docs/images/start-start.png b/docs/images/start-start.png deleted file mode 100644 index 33d11fcdcc..0000000000 Binary files a/docs/images/start-start.png and /dev/null differ diff --git a/docs/instance-api.md b/docs/instance-api.md deleted file mode 100644 index beb5bb60aa..0000000000 --- a/docs/instance-api.md +++ /dev/null @@ -1,134 +0,0 @@ -## Page & Component 新增的实例方法 - -### this.$watch - -用于动态添加watch，返回值是一个destroy函数，执行返回函数用于销毁watch - -##### 参数选项 - -- **`this.$watch(expr | function, callback, options?: Object) : function`** - -``` js -import {createComponent} from '@mpxjs/core' -createComponent({ - data: { - info: { - name: 1 - } - }, - attached () { - // 微信小程序生命周期 - // 第一个参数为变量表达式 - const unwatch1 = this.$watch('info.name', (val, old) => { - console.log(val, old) - }, { - // deep: true, - // sync: true, - immediate: true // watch options - }) - unwatch1() // 销毁watch，不再观察 - - // 第一个参数也可以为函数 - this.$watch(function() { - return this.info.name - }, (val, old) => { - console.log(val, old) - }, { - // deep: true, - // sync: true, - immediate: true // watch options - }) - } -}) -``` - -### $nextTick - -接收一个函数，保证在小程序渲染更新之后执行回调 - -``` js -import {createComponent} from '@mpxjs/core' -createComponent({ - data: { - info: { - name: 1 - } - }, - attached () { - this.info.name = 2 - this.$nextTick(() => { - console.log('会在由name变化引起的视图更新之后执行') - }) - } -}) -``` - -### $updated - -已被废弃，请使用this.$nextTick代替 - -### $forceUpdate - -##### 参数选项 - -- **`this.$forceUpdate(data: Object, callback?: function)`** - -用于强制刷新视图，正常情况下```只有发生了变化的数据```才会被发送到视图层进行渲染。强制更新时，会将某些数据强制发送到视图层渲染，无论是否发生了变化 - -``` js -import {createComponent} from '@mpxjs/core' -createComponent({ - data: { - info: { - name: 'a' - }, - age: 100 - }, - attached () { - // 虽然不会修改age的值，但仍会触发重新渲染，并且会将age发送到视图层 - this.$forceUpdate({ - age: 100 - }, () => { - console.log('视图更新后执行') - }) - - // 也可用于正常的数据修改，key支持path - this.$forceUpdate({ - 'info.name': 'b' - }, () => { - console.log('视图更新后执行') - }) - } -}) -``` - -### $set、$remove - -正常情况下，对一个响应式数据的新增属性或者删除数据操作是没法感知的，通过 `this.$set、this.$remove` 可以动态添加或删除属性，并且会触发观察器更新（视图更新 | watch回调） - -``` js -import {createComponent} from '@mpxjs/core' -createComponent({ - data: { - info: { - name: 'a' - } - }, - watch: { - 'info.age' (val) { - // 当新增age属性之后执行 - console.log(val) - }, - 'info' (val) { - // 当新增或删除属性之后都会执行 - console.log(val) - } - }, - attached () { - // 新增age属性 - this.$set(this.info, 'age', 100) - // 删除name属性 - this.$remove(this.info, 'name') - } -}) -``` diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index 6ddb7fa81c..0000000000 --- a/docs/intro.md +++ /dev/null @@ -1,224 +0,0 @@ -

      - - MPX - -

      - -

      - 一款具有优秀开发体验和深度性能优化的增强型小程序开发框架。 -

      - - -## 简介 - -Mpx是一款致力于提高小程序开发体验和开发效率的增强型小程序框架，通过Mpx，我们能够高效优雅地开发出具有极致性能的优质小程序应用，并将其输出到各大小程序平台和web平台中运行。 - -Mpx具有以下功能特性： -* 数据响应 (赋值响应 / [watch](https://didi.github.io/mpx/single/script-enhance.html#watch) / [computed](https://didi.github.io/mpx/single/script-enhance.html#computed)) -* 增强模板语法 ([动态组件](https://didi.github.io/mpx/single/template-enhance.html#%E5%8A%A8%E6%80%81%E7%BB%84%E4%BB%B6) / [样式绑定 / 类名绑定 ](https://didi.github.io/mpx/single/template-enhance.html#class%E4%B8%8Estyle%E7%BB%91%E5%AE%9A) / [内联事件函数](https://didi.github.io/mpx/single/template-enhance.html#%E5%86%85%E8%81%94%E4%BA%8B%E4%BB%B6%E7%BB%91%E5%AE%9A) / [双向绑定](https://didi.github.io/mpx/single/template-enhance.html#%E5%8F%8C%E5%90%91%E7%BB%91%E5%AE%9A) / [refs](https://didi.github.io/mpx/single/template-enhance.html#refs)) -* 极致性能 ([运行时性能优化](https://didi.github.io/mpx/understanding/understanding.html#%E6%95%B0%E6%8D%AE%E5%93%8D%E5%BA%94%E4%B8%8E%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96) / [包体积优化](https://didi.github.io/mpx/understanding/understanding.html#%E5%88%86%E5%8C%85%E5%A4%84%E7%90%86%E7%BB%86%E8%8A%82) / 框架运行时体积14KB) -* [高效强大的编译构建](https://didi.github.io/mpx/understanding/understanding.html#%E7%BC%96%E8%AF%91%E6%9E%84%E5%BB%BA) (基于webpack / 兼容webpack生态 / 兼容原生小程序 / 完善支持npm场景下的分包输出 / 高效调试) -* [单文件组件开发](https://didi.github.io/mpx/single/what-is-single-file.html#%E5%8D%95%E6%96%87%E4%BB%B6) -* [渐进接入 / 原生组件支持](https://didi.github.io/mpx/progressive.html) -* [状态管理](https://didi.github.io/mpx/store/#%E5%A4%9A%E5%AE%9E%E4%BE%8B) (Vuex规范 / 支持多实例Store) -* 跨团队开发 ([packages](https://didi.github.io/mpx/single/json-enhance.html#packages)) -* 逻辑复用 ([mixins](https://didi.github.io/mpx/single/script-enhance.html#mixins)) -* [周边能力支持](https://didi.github.io/mpx/extend/) (fetch / api增强 / mock / webview-bridge) -* 脚手架支持 -* [多平台增强](https://didi.github.io/mpx/platform.html#%E5%A4%9A%E5%B9%B3%E5%8F%B0%E6%94%AF%E6%8C%81) (支持在微信、支付宝、百度、qq、头条小程序平台中进行增强开发) -* [跨平台编译](https://didi.github.io/mpx/platform.html#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E7%BC%96%E8%AF%91) (支持以微信为base，将一套代码转换输出到支付宝、百度、qq、头条小程序平台和[web平台](https://didi.github.io/mpx/platform.html#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E8%BE%93%E5%87%BAweb)中运行) -* [TypeScript支持](https://didi.github.io/mpx/ts.html) (基于ThisType实现了完善的类型推导) -* [I18n国际化](https://didi.github.io/mpx/i18n.html) -* 单元测试支持 (即将到来) -* 快应用输出 (即将到来) - -## 安装使用 - -```bash -# 安装mpx脚手架工具 -npm i -g @mpxjs/cli - -# 初始化项目 -mpx create mpx-project - -# 进入项目目录 -cd mpx-project - -# 安装依赖 -npm i - -# development -npm run serve - -# production -npm run build -``` - -使用小程序开发者工具打开项目文件夹下dist中对应平台的文件夹即可预览效果。 - -## 简单示例 - -```html - - - - - - - -``` - -更多示例请查看[官方示例项目](https://github.com/didi/mpx/tree/master/examples) - -## 设计思路 - -Mpx的核心设计思路为增强，不同于业内大部分小程序框架将web MVVM框架迁移到小程序中运行的做法，Mpx以小程序原生的语法和技术能力为基础，借鉴参考了主流的web技术设计对其进行了扩展与增强，并在此技术上实现了以微信增强语法为base的同构跨平台输出，该设计带来的好处如下： -* 良好的开发体验：在方便使用框架提供的便捷特性的同时，也能享受到媲美原生开发的确定性和稳定性，完全没有`框架太多坑，不如用原生`的顾虑；不管是增强输出还是跨平台输出，最终的dist代码可读性极强，便于调试排查； -* 极致的性能：得益于增强的设计思路，Mpx框架在运行时不需要做太多封装抹平转换的工作，框架的运行时部分极为轻量简洁，压缩+gzip后仅占用14KB；配合编译构建进行的包体积优化和基于模板渲染函数进行的数据依赖跟踪，Mpx框架在性能方面做到了业内最优([小程序框架运行时性能评测报告](https://github.com/hiyuki/mp-framework-benchmark/blob/master/README.md))； -* 完整的原生兼容：同样得益于增强的设计思路，Mpx框架能够完整地兼容小程序原生技术规范，并且做到实时跟进。在Mpx项目中开发者可以方便地使用业内已有的小程序生态，如组件库、统计工具等；原生开发者们可以方便地进行渐进迁移；甚至可以将框架的跨平台编译能力应用在微信的原生小程序组件当中进行跨平台输出。 - - -## 生态周边 - -|包名|版本|描述| -|-----|----|----| -|@mpxjs/core|[![npm version](https://badge.fury.io/js/%40mpxjs%2Fcore.svg)](https://badge.fury.io/js/%40mpxjs%2Fcore)|mpx运行时核心| -|@mpxjs/webpack-plugin|[![npm version](https://badge.fury.io/js/%40mpxjs%2Fwebpack-plugin.svg)](https://badge.fury.io/js/%40mpxjs%2Fwebpack-plugin)|mpx编译核心| -|@mpxjs/cli|[![npm version](https://badge.fury.io/js/%40mpxjs%2Fcli.svg)](https://badge.fury.io/js/%40mpxjs%2Fcli)|mpx脚手架命令行工具| -|@mpxjs/fetch|[![npm version](https://badge.fury.io/js/%40mpxjs%2Ffetch.svg)](https://badge.fury.io/js/%40mpxjs%2Ffetch)|mpx网络请求库，处理wx并发请求限制| -|@mpxjs/webview-bridge|[![npm version](https://badge.fury.io/js/%40mpxjs%2Fwebview-bridge.svg)](https://badge.fury.io/js/%40mpxjs%2Fwebview-bridge)|为跨小程序平台的H5项目提供通用的webview-bridge| -|@mpxjs/api-proxy|[![npm version](https://badge.fury.io/js/%40mpxjs%2Fapi-proxy.svg)](https://badge.fury.io/js/%40mpxjs%2Fapi-proxy)|将各个平台的 api 进行转换，也可以将 api 转为 promise 格式| -|@mpxjs/mock|[![npm version](https://badge.fury.io/js/%40mpxjs%2Fmock.svg)](https://badge.fury.io/js/%40mpxjs%2Fmock)|结合mockjs提供数据mock能力| - -## 成功案例 - -
      - - - - - - - - - - - -
      - -[更多案例](https://github.com/didi/mpx/issues/385)，若你也在使用Mpx框架开发小程序，并想分享给大家，请填在此issue中。 - -## 交流 - -提供 微信群 / QQ群 两种交流方式 - -#### 添加MPX入群客服等待受邀入群 - -Mpx-wx客服 - -#### 扫码进入QQ群 - -Mpx-QQ群 - -图片因github网络问题导致不可见的朋友可以点击该链接：https://s.didi.cn/rod - -## 招聘 - -滴滴出行小程序团队绝赞招人中，欢迎各位前端同学加入我们，开发日活过千万的头部小程序应用滴滴出行，并参与Mpx框架技术建设。 - -感兴趣的同学请将简历投递至[donghongping@didiglobal.com](donghongping@didiglobal.com)，社招校招均可~ diff --git a/docs/migrate.md b/docs/migrate.md deleted file mode 100644 index 21fee26f08..0000000000 --- a/docs/migrate.md +++ /dev/null @@ -1,100 +0,0 @@ -# 2.0迁移指南 - -mpx2.0是完全兼容1.0版本的，显著的区别是支持了跨小程序平台的支持， - -新创建的项目不用关心迁移问题，直接开发即可，使用1.0时期的包等都不受影响。 - -需要注意的一点是对小程序提供的API调用，我们使用了@mpxjs/api-proxy来抹平差异，同时之前的promisify被整合到了这个包里，所以1.x升级2.x需要替换@mpxjs/promisify为@mpxjs/api-proxy，使用方式为 `mpx.use(apiProxy, {usePromise: true})` ，同时，所有的api调用应从wx.xxx变更为mpx.xxx，比如wx.navigateTo写为mpx.navigateTo，**参数保持和微信一致，平台差异方面api-proxy做了抹平**。 - -老项目可以有两种升级方式： - -## 拷贝升级 - -如果你的项目是在1.0时期利用脚手架生成的，希望体验2.0的新特性，最简单的方式是升级cli工具后新创建一个项目，删掉src部分，复制老项目的src即可。 - -一个有所变化的地方在于，新项目的打开项目方式发生了一些变化，原本用微信开发者工具打开项目目录变为了用开发者工具打开构建结果目录（dist或dist/wx，取决于是否用跨平台构建），变化的原因详情见下方 [附录-文件结构区别](#文件结构区别) 部分。 - -## 手工升级 - -如果你的项目之前就是手工配置的或者被个性化再次修改过或者对webpack配置非常熟练了解，也可以按照以下内容参考自行手工升级。 - -### 依赖升级 - -* `@mpxjs/core`由1.x升级至2.0 -* `@mpxjs/webpack-plugin`由1.x升级至2.0 - -### 依赖变更 - -* `@mpxjs/promisify`废弃，使用`@mpxjs/api-proxy`代替 -* `@mpxjs/url-loader`废弃，合入到`@mpxjs/webpack-plugin`中维护 - -### webpack配置变更 - -在2.0版本中，为了更好地处理小程序中template和wxs的引用，我们重写了url-loader和file-loader，并且调整了原有的wxs-loader的工作机制，这会导致项目的build/webpack.base.conf.js中的module.rules配置发生一定的变化，调整规则如下： - -```js -const webpackConf = { - module: { - rules: [ - { - test: /\.mpx$/, - use: MpxWebpackPlugin.loader({ - transRpx: { - mode: 'only', - comment: 'use rpx', - include: resolve('src') - } - }) - }, - { - test: /\.js$/, - loader: 'babel-loader', - include: [resolve('src'), resolve('test'), resolve('node_modules/@mpxjs')] - }, - { - test: /\.json$/, - resourceQuery: /__component/, - type: 'javascript/auto' - }, - // 1.x版本中的配置 - // { - // test: /(\.wxs|\.sjs|\.filter\.js)$/, - // use: MpxWebpackPlugin.wxsLoader(), - // type: 'javascript/auto', - // issuer: /(\.wxml|\.axml|\.swan|\.mpx|\.th)$/ - // }, - // { - // test: /\.(png|jpe?g|gif|svg)$/, - // loader: '@mpxjs/url-loader', - // options: { - // name: 'img/[name].[ext]', - // limit: 10000 - // } - // }, - - // 2.0版本后的配置 - { - test: /\.(wxs|sjs|filter\.js)$/, - loader: MpxWebpackPlugin.wxsPreLoader(), - enforce: 'pre' - }, - { - test: /\.(png|jpe?g|gif|svg)$/, - loader: MpxWebpackPlugin.urlLoader({ - name: 'img/[name].[ext]' - }) - } - ] - } -} -``` - -## 附录 - -#### 文件结构区别 - -使用@mpxjs/cli脚手架生成的项目在1.0版本时期和2.0版本时期有些区别。 - -早先因社区同学的建议使用了在项目根目录下的project.config.json文件中通过指定miniprogramRoot字段为dist，好处是不用复制，在微信小程序开发工具里可以用编辑器直接修改保存project.config.json文件。但跨小程序平台支持下，我们可能会在dist文件夹下再深一个层级区分不同小程序比如会有/dist/wx，/dist/ali，/dist/swan这样，出于打开项目体验的一致性等方面考量，决定这个微信特有的文件还是复制进构建结果里，不通过miniprogramRoot指定。 - -因此对于微信小程序的开发，1.0时期项目直接拷贝src到迁移2.0生成的新项目需要注意打开方式由打开项目目录改为打开项目构建生成的dist目录，如果是要用到跨平台特性（npm run build:cross），则要打开/dist/wx目录。 diff --git a/docs/platform.md b/docs/platform.md deleted file mode 100644 index 306ba2181a..0000000000 --- a/docs/platform.md +++ /dev/null @@ -1,434 +0,0 @@ -# 多平台支持 - -目前mpx支持了微信、支付宝、百度、qq、头条小程序平台。 - -## template增强特性 - -不同平台上的模板增强指令按照平台的指令风格进行设计，文档和代码示例为了方便统一采用微信小程序下的书写方式。 - -模板增强指令对应表： - -增强指令|微信|支付宝|百度|qq|头条 -----|----|----|----|----|---- -双向绑定|wx:model|a:model|s-model|qq:model|tt:model -双向绑定辅助属性|wx:model-prop|a:model-prop|s-model-prop|qq:model-prop|tt:model-prop -双向绑定辅助属性|wx:model-event|a:model-event|s-model-event|qq:model-event|tt:model-event -双向绑定辅助属性|wx:model-value-path|a:model-value-path|s-model-value-path|qq:model-value-path|tt:model-value-path -动态样式绑定|wx:class|a:class|s-class|qq:class|暂不支持 -动态样式绑定|wx:style|a:style|s-style|qq:style|暂不支持 -获取节点/组件实例|wx:ref|a:ref|s-ref|qq:ref|tt:ref -显示/隐藏|wx:show|a:show|s-show|qq:show|tt:show - -## script增强特性 - -增强字段|微信|支付宝|百度|qq|头条 -----|----|----|----|----|---- -computed|支持|支持|支持|支持|部分支持，无法作为props传递(待头条修复生命周期执行顺序可完整支持) -watch|支持|支持|支持|支持|支持 -mixins|支持|支持|支持|支持|支持 - -## style增强特性 - -无平台差异 - -## json增强特性 - -增强字段|微信|支付宝|百度|qq|头条 -----|----|----|----|----|---- -packages|支持|支持|支持|支持|部分支持，无法分包 - - -# 跨平台编译 - -自2.0版本开始，mpx开始支持跨小程序平台编译，不同于常规跨平台框架重新定义一套DSL的方式，mpx支持基于现有平台的源码编译为其他已支持平台的目标代码。跨平台编译能力依赖于mpx的多平台支持，目前mpx已经支持将微信小程序跨平台编译为支付宝、百度、qq和头条小程序。 - -## 使用方法 - -如果你是使用`mpx init xxx`新生成的项目，package.json里script部分有`npm run build:cross`，直接执行`npm run build:cross`（watch同理），如果仅需构建某几个平台的，可以修改该script，按已有的格式删除或增添某些某些平台 - -如果你是自行搭建的mpx项目，你只需要进行简单的配置修改，打开项目的webpack配置，找到@mpxjs/webpack-plugin的声明位置，传入mode和srcMode参数即可，示例如下 - -```js -// 下面的示例配置能够将mpx微信小程序源码编译为支付宝小程序 -new MpxwebpackPlugin({ - // mode为mpx编译的目标平台，可选值有(wx|ali|swan|qq|tt) - mode: 'ali', - // srcMode为mpx编译的源码平台，目前仅支持wx - srcMode: 'wx' -}) -``` - -## 跨平台差异抹平 - -为了实现小程序的跨平台编译，我们在编译和运行时做了很多工作以抹平小程序开发中各个方面的跨平台差异 - -### 模板语法差异抹平 - -对于通用指令/事件处理的差异，mpx提供了统一的编译转换抹平操作；而对于平台组件和组件属性的差异，我们也在力所能及的范围内进行了转换抹平，对于平台差异性过大无法转换的部分会在编译阶段报错指出。 - -### 组件/页面对象差异抹平 - -不同平台间组件/页面对象的差异主要体现在生命周期上，我们在支持多平台能力时已经将不同平台的生命周期映射到mpx框架的一套内部生命周期中，基于这个统一的映射，不同平台的生命周期差异也得到了抹平。 - -此外，我们还进行了一系列运行时增强来模拟微信平台中提供而其他平台中未提供的能力，例如： -* 在支付宝组件实例中提供了this.triggerEvent方法模拟微信中的自定义组件事件； -* 提供了this.selectComponent/this.selectAllComponents方法模拟微信中获取子组件实例的能力； -* 重写了createSelectorQuery方法抹平了微信/支付宝平台间的使用差异； -* 转换抹平了微信/支付宝中properties定义的差异； -* 利用mpx本身的数据响应能力模拟了微信中的observers/property observer能力等; -* 提供了this.getRelationNodes方法并支持了微信中组件间关系relations的能力 - -对于原生小程序组件的转换，还会进行一些额外的抹平，已兼容一些已有的原生组件库，例如： -* 将支付宝组件中的props数据挂载到this.data中以模拟微信平台中的表现； -* 利用mpx本身的mixins能力模拟微信中的behaviors能力。 - -对于一些无法进行模拟的跨平台差异，会在运行时进行检测并报错指出，例如微信转支付宝时使用moved生命周期等。 - -### json配置差异抹平 - -类似于模板语法，会在编译阶段进行转换抹平，无法转换的部分会在编译阶段报错指出。 - -### api调用差异抹平 - -对于api调用，mpx提供了一个api调用代理插件来抹平跨平台api调用的差异，使用时需要在项目中安装使用`@mpxjs/api-proxy`，并且在调用小程序api时统一使用mpx对象进行调用，示例如下： - -```js -// 请在app.mpx中安装mpx插件 -import mpx, { createApp } from '@mpxjs/core' -import apiProxy from '@mpxjs/api-proxy' - -mpx.use(apiProxy, { - // 开启api promisify - usePromise: true -}) - -createApp({ - onLaunch() { - // 调用小程序api时使用mpx.xxx，而不要使用wx.xxx或者my.xxx - mpx.request({url: 'xxx'}) - } -}) -``` - -对于无法转换抹平的api调用会在运行时阶段报错指出。 - -### webview bridge差异抹平 - -对于不同平台中webview bridge的调用，我们封装了一个`@mpxjs/webview-bridge`包，用于抹平不同小程序平台中webview bridge的差异，简单使用示例如下： - -```js -import mpx from '@mpxjs/webview-bridge' - -mpx.navigateBack() -``` - -对于无法转换抹平的bridge调用会在运行时阶段报错指出，详细使用指南请查看[webview-bridge](/extend/index.md#webview-bridge) - -## 跨平台条件编译 - -Mpx跨平台编译的原则在于，`能转则转，转不了则报错提示`，对于无法抹平差异的部分，我们提供了完善的跨平台条件编译机制便于用户处理因平台差异而无法相互转换的部分，也能够用于实现具有平台差异性的业务逻辑。 - -mpx中我们支持了三种维度的条件编译，分别是文件维度，区块维度和代码维度，其中，文件维度和区块维度主要用于处理一些大块的平台差异性逻辑，而代码维度主要用于处理一些局部简单的平台差异。 - -### 文件维度条件编译 - -文件维度条件编译简单的来说就是文件为维度进行跨平台差异代码的编写，例如在微信->支付宝的项目中存在一个业务地图组件map.mpx，由于微信和支付宝中的原生地图组件标准差异非常大，无法通过框架转译方式直接进行跨平台输出，这时你可以在相同的位置新建一个map.ali.mpx，在其中使用支付宝的技术标准进行开发，编译系统会根据当前编译的mode来加载对应模块，当mode为ali时，会优先加载map.ali.mpx，反之则会加载map.mpx。 - -文件维度条件编译能够与webpack alias结合使用，对于npm包的文件我们并不方便在原本的文件位置创建.ali的条件编译文件，但我们可以通过webpack alias在相同位置创建一个`虚拟的`.ali文件，并将其指向项目中的其他文件位置。 - -```js - // 对于npm包中的文件依赖 - import npmModule from 'somePackage/lib/index' - - // 配置以下alias后，当mode为ali时，会优先加载项目目录中定义的projectRoot/somePackage/lib/index文件 - const webpackConf = { - resolve: { - alias: { - 'somePackage/lib/index.ali': 'projectRoot/somePackage/lib/index' - } - } - } -``` - -### 区块维度条件编译 - -在.mpx单文件中一般存在template、js、stlye、json四个区块，mpx的编译系统支持以区块为维度进行条件编译，只需在区块标签中添加`mode`属性定义该区块的目标平台即可，示例如下： - -```html - - - - - -``` - -### 代码维度条件编译 - -如果只有局部的代码存在跨平台差异，mpx同样支持在代码内使用if/else进行局部条件编译，用户可以在js代码和template插值中访问`__mpx_mode__`获取当前编译mode，进行平台差异逻辑编写，js代码中使用示例如下。 - -除了 `__mpx_mode__` 这个默认插值以外，有别的环境变量需要的话可以在mpx.plugin.conf.js里通过defs进行配置。 - -```js -if(__mpx_mode__ === 'ali') { - // 执行支付宝环境相关逻辑 -} else { - // 执行其他环境相关逻辑 -} -``` -template代码中使用示例如下 - -```html - -支付宝环境 -其他环境 -``` - -JSON中的条件编译（注意，这个依赖JSON的动态方案，得通过name="json"这种方式来编写，其实写的是js代码，最终module.exports导出一个可json化的对象即可）： -```html - -``` - -样式的条件编译： -```css -/* - @mpx-if ( - __mpx_mode__ === 'wx' || - __mpx_mode__ === 'qq' - ) -*/ - /* @mpx-if (__mpx_mode__ === 'wx') */ - wx { - background: green; - } - /* - @mpx-elif (__mpx_mode__ === 'qq') - */ - qq { - background: black; - } - /* @mpx-endif */ - - /* @mpx-if (__mpx_mode__ === 'swan') */ - swan { - background: cyan; - } - /* @mpx-endif */ - always { - background: white; - } -/* - @mpx-else -*/ -other { - /* @mpx-if (__mpx_mode__ === 'swan') */ - background: blue; - /* @mpx-else */ - background: red; - /* @mpx-endif */ -} -/* - @mpx-endif -*/ -``` - -## 其他注意事项 - -* 当目标平台为支付宝时，需要启用支付宝最新的component2编译才能保障框架正常工作，关于component2[点此查看详情](https://docs.alipay.com/mini/framework/custom-component-overview)； -* 跨平台源码中自定义组件的标签名不能使用驼峰形式`myComponent`，请使用横杠形式`my-component`来书写； -* 生成的目标代码中文件名和文件夹名不能带有`@`符号，目前媒体文件和原生自定义组件在编译时不会修改文件名，需要重点关注。 - -# 跨平台输出web - -从2.3.0版本开始，Mpx开始支持将已有项目跨平台输出web平台中运行的能力，由于该能力目前还处于持续开发阶段，目前仅支持将一些简单的运营类的小程序输出为web项目，无法直接转换大型复杂项目，我们会持续对输出web的能力进行完善和补全，以提高其适用范围和开发体验。 - -## 技术实现 - -与小程序平台间的差异相比，web平台和小程序平台间的差异要大很多，小程序相当于是基于web技术的上层封装，所以不同于我们跨平台输出其他小程序平台时以编译转换为主的思路，在输出web时，我们更多地采用了封装的方式来抹平组件/Api和底层环境的差异，与当前大部分的跨平台框架相仿。但与当前大部分跨平台框架以web MVVM框架为base输出到小程序上运行的思路不同，我们是以Mpx小程序增强语法为基础输出到web中运行，前面说过小程序本身是基于web技术进行的实现，小程序->web的转换在可行性和兼容性上会好一些。 - -在具体实现上，Mpx项目输出到web中运行时在组件化和路由层面都是基于Vue生态实现，所以可以将Mpx的跨端输出产物整合到既有的Vue项目中，或者在条件编译中直接使用Vue语法进行web端的实现。 - -## 使用方法 - -使用@mpxjs/cli创建新项目时选择跨平台并选择输出web后，即可生成可输出web的示例项目，运行`npm run serve:web`，就会在dist/web下输出构建后的web项目，并启动静态服务预览运行。 - -## 支持范围 -目前输出web的能力仍处于持续开发阶段，现阶段支持的小程序技术能力范围有限，下列表格中显示了当前版本中已支持的能力范围 - -### 模板指令 -指令名称|是否支持 -:----|---- -Mustache数据绑定|是 -wx:for|是 -wx:for-item|是 -wx:for-index|是 -wx:key|是 -wx:if|是 -wx:elif|是 -wx:else|是 -wx:model|是 -wx:model-prop|是 -wx:model-event|是 -wx:model-value-path|是 -wx:model-filter|是 -wx:class|是 -wx:style|是 -wx:ref|是 -wx:show|是 - -### 事件绑定方式 - -绑定方式|是否支持 -:----|---- -bind|是 -catch|是 -capture-bind|是 -capture-catch|是 - -### 事件名称 - -事件名称|是否支持 -:----|---- -tap|是 -longpress|是 -longtap|是 - -web同名事件默认全部支持，已支持组件的特殊事件默认为支持，不支持的情况下会在编译时抛出异常 - -### 基础组件 - -组件名称|是否支持 -:----|---- -view|是 -cover-view|是 -scroll-view|是 -progress|是 -navigator|是 -swiper|是 -swiper-item|是 -text|是 -image|是 -block|是 -form|是 -input|是 -textarea|是 -button|是 -checkbox|是 -checkbox-group|是 -radio|是 -radio-group|是 -picker|是 - -### 生命周期 - -声明周期名称|是否支持 -:----|---- -onLaunch|是 -onLoad|是 -onReady|是 -onShow|是 -onHide|是 -onUnload|是 -onError|是 -created|是 -attached|是 -ready|是 -detached|是 -updated|是 - -### 组件配置 - - -配置项|支持度 -:----|---- -properties|部分支持，observer不支持，请使用watch代替 -data|支持 -watch|支持 -computed|支持 -methods|支持 -mixins|支持 -observers|不支持，请使用watch代替 -behaviors|不支持，请使用mixins代替 -relations|部分支持，linkChanged、target不支持 - -### 组件API - -api名称|支持度 -:----|---- -triggerEvent|支持 -$nextTick|支持 -createSelectorQuery/selectComponent|支持 - - -### 全局API - -api名称|支持度 -:----|---- -navigateTo|支持 -navigateBack|支持 -redirectTo|支持 -request|支持 -connectSocket|支持 -SocketTask|支持 -EventChannel|支持 -createSelectorQuery|支持 -base64ToArrayBuffer|支持 -arrayBufferToBase64|支持 -nextTick|支持 -set|支持 -setNavigationBarTitle|支持 -setNavigationBarColor|支持 -setStorage|支持 -setStorageSync|支持 -getStorage|支持 -getStorageSync|支持 -getStorageInfo|支持 -getStorageInfoSync|支持 -removeStorage|支持 -removeStorageSync|支持 -clearStorage|支持 -clearStorageSync|支持 -getSystemInfo|支持 -getSystemInfoSync|支持 -showModal|支持 -showToast|支持 -hideToast|支持 -showLoading|支持 -hideLoading|支持 -onWindowResize|支持 -offWindowResize|支持 - -### JSON配置 -配置项|是否支持 -:----|---- -pages|是 -usingComponents|是 -packages|是 -subpackages|是 -navigationBarTitleText|是 - -### 拓展能力 -能力|是否支持 -:---|--- -fetch|是 -i18n|是 - - - - diff --git a/docs/plugin.md b/docs/plugin.md deleted file mode 100644 index 35ab974f81..0000000000 --- a/docs/plugin.md +++ /dev/null @@ -1,3 +0,0 @@ -# 插件模式 - -介绍小程序插件及插件模式创建项目的流程 diff --git a/docs/progressive.md b/docs/progressive.md deleted file mode 100644 index 566307e21e..0000000000 --- a/docs/progressive.md +++ /dev/null @@ -1,181 +0,0 @@ -# 渐进接入 - -可参考此demo：[mpx渐进接入demo](https://github.com/didi/mpx/tree/master/examples/mpx-progressive) - -mpx并不一定要求用户一定要一次性用上框架的所有东西。 - -若是 **已有项目** 期望接入mpx，**`不需要对原有代码做全局重写`**。 - -可以保持原有代码不变，新的组件、页面期望使用mpx的某些特性才引入mpx。 - -甚至我们允许用户用mpx框架编写新的页面/组件再局部导出相应的页面/组件反用到现有的小程序项目中。见[导出原生](#导出原生)一节。（当然还是建议大家优先考虑老项目渐进改为mpx，而不是这种反过来的模式） - -## 原生自定义组件支持 - -有些时候，我们需要在`mpx`工程中使用原生小程序组件: - -- 通过`npm`引用安装第三包 -- 将第三方包源码拷贝到本地`src`目录下 - -> 注：mpx并不限制第三方包的格式。开发者可以自己参考小程序官方的[开发第三方自定义组件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/trdparty.html) - -### 原理 - -根据`unsingComponents`中设定的路径，`mpx`会去查找包的入口js文件。然后提取入口文件所在的**目录**中的`js` `json` `wxss` `wxml`进行编译 - -编译带来的好处是，常规的拷贝操作，会造成组件内部的依赖缺失，以及冗余代码被打包。而执行了编译，使得`mpx`可以精确的收集依赖，这表现在： - -- `js`文件中的依赖也会被打包，没有被加载的依赖库不会打包，减小体积 -- `json`文件的`usingComponents`会被解析，因此原生组件内部可以再引用其他原生组件，甚至是mpx组件 -- `wxss`中引用外部样式 -- `wxml`中的图片资源会被打包 - -> 例如使用第三方组件库时，很多组件可能并未使用，如果按照组件库官方给出的使用方式，其实会将整个组件库放进你的项目。 -而采用mpx这种方式则只会引入你使用了的组件，所以如果你喜欢vant的按钮，iview的输入框，ColorUI的布局，欢迎尝试mpx。 -（本段内容具有时效性，未来微信可能会有优化，毕竟一开始微信连npm都不支持） - -### 例子 - -**文件目录** - ``` - node_modules - |-- npm-a-wx-component // npm安装 - | --package.json - | --src - | --index.js - | --index.json - | --index.wxss - | --index.wxml - |-- npm-b-wx-component // npm安装 - | --package.json - | --src - | --index.js - | --index.json - | --index.wxss - | --index.wxml - component - │-- container.mpx - │-- com-a.mpx - |-- src-wx-component // 手动拷贝 - | --index.js - | --index.json - | --index.wxss - | --index.wxml - - ``` - -**container.mpx** -```html - - - -``` - -**node_modules/npm-a-wx-component/src/index.wxml** -```html - -``` - -**node_modules/npm-a-wx-component/src/index.json** -```json -{ - "usingComponents": { - "npm-b-wx-component": "npm-b-wx-component" - } -} -``` - -## 原生page支持 - -原生自定义组件的支持已经基本能保证第三方UI库和mpx的完美结合，但如果是用户存在已经开发好的小程序，在后续的迭代中发现了mpx想使用，就需要用户手工将4个文件变成mpx文件，这不够友好。 - -于是我们提供了对原生页面的支持，允许项目中存在原生小程序文件（wxml,js,json,wxss）和mpx文件，两者可以混合使用，通过webpack的构建将两者完美混合在一起生成最终的dist。 - -使用方式和组件相似。 - -## 导出原生 - -通过导出原生能力，你可以将一个mpx项目融回到原生项目中。有两种做法：一是局部导出部分页面/组件，二是完整导出一个mpx项目。 - -### 导出部分页面/组件 - -使用mpx开发的页面/组件也可以局部导出为纯粹的普通的原生小程序页面/组件，整合到已有的原生小程序中。 - -仅需修改webpack config中entry一项，将app改为对应的页面/组件即可。 - -请参考下面的例子，`注意resolve时候最后的query不可以省略，一定要按正确的类型声明这是一个组件or页面。` - -例子： - -```js -// -module.exports = merge(baseWebpackConfig, { - name: 'main-compile', - // entry point of our application - entry: { - // 此处以mpx脚手架生成的项目为例 - - // before - // app: resolveSrc('app.mpx') - - // after - 'pages/dindex': resolveSrc('./pages/index.mpx?page'), - 'components/dlist': resolveSrc('./components/list.mpx?component') - } -}) -``` - -拷贝dist里所有文件到原生微信小程序项目根目录即可正常工作。 - -### 完整导出 - -我们也可以使用mpx完成一整个项目的开发，这个项目可能包含多个页面，这些页面将合作完成某一项完整的功能，一般可能是公共需求，比如登录/用户中心等公共模块。 - -如果接入方也是Mpx框架开发的项目，那么皆大欢喜，会非常easy。但若对方是原生开发的，这时我们就希望能将整个项目完整导出成原生，并让接入方顺利使用。 - -其实观察下mpx项目的打包结构，结构是非常简单的，页面/组件都很规矩地放在对应文件夹里的，所以删掉app.json/app.js/app.wxss/project.config.json几个文件后直接整个拷贝即可。 - -所以完整导出整个项目的做法可以是这样： - -1. 确认页面路径不要冲突，一般这种公共模块项目，路径上就不要占据`/pages/index/index`，页面路径Mpx是不会修改的，所以定一个`/pages/{模块名}/{页面名}`就好。 - -2. app.*的内容都要删掉的，所以全局样式都应该写在独立的文件中（wxss），全局配置有什么特殊的要告知接入方（json），因为App.js会被舍弃，所以入口js要抽出来(js)。 - -3. 如果有要导出的入口文件，需要给output增加配置： -```js -// webpack.conf -module.exports = { - entry: { - app: resolveSrc('app.mpx'), - index: resolveSrc('index.js') // 导出的入口文件，若没有可不写 - }, - output: { - libraryTarget: 'commonjs2', - libraryExport: 'default' // 若export default导出需要写这个,module.exports可省略 - }, - // ... 略 -} -``` - -4. 整个复制进接入方的项目里，注册对应的页面，然后就可以正常使用了！ diff --git a/docs/single/json-enhance.md b/docs/single/json-enhance.md deleted file mode 100644 index ab48c25fe7..0000000000 --- a/docs/single/json-enhance.md +++ /dev/null @@ -1,255 +0,0 @@ -# JSON增强特性 - -## 动态与注释 - -作为配置文件，json最大的缺陷是不支持注释，然后是不够灵活。此处感谢社区同学贡献的解决方案：支持js。 - -json块我们除了可以写``，还可以这样： - -```html - -``` - -## packages - -### 背景 - -小程序原生的app.json中定义了pages域，用于注册app中所有用到的pages， -这个设计能够cover绝大部分个人开发的场景，但是当我们在开发一个团队协作的大型项目时，某个开发者可能会依赖其他开发者提供的单个或几个页面/组件来进行开发。 - -为此，我们引入了packages的概念来解决依赖问题。 - -后来微信原生增加了 [分包加载](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages.html) 能力，因此我们也在package机制中增加了对原生分包加载的支持。 - -我们提供的包能力本质是对业务的拆分合并，即开发时候可以各自开发，打包时候合为一个，和微信的分包不相同，推荐在此基础上进一步使用平台原生分包能力，可以更好地控制小程序体积。 - -### 使用方法 - -我们拓展了app.json的语法，新增了packages域，用来声明依赖的packages，packages可嵌套依赖。 - -```html -// @file src/app.mpx - - -// @file src/packages/index.mpx - -``` - -打包结果：dist/app.json -```json -{ - "pages": [ - "pages/index/index", - "pages/other/other", - "pages/other/other2" - ] -} -``` - -由上可见，经过我们的编译过程，packages中注册的页面按照原始的路径形状被合并到主app中， -这样依赖的开发者可以不用考虑自己在被依赖时页面路径是怎么样的，也可以直接将调试用的app.mpx作为依赖入口直接暴露出去， -对于主app的开发者来说也不需要了解依赖内部的细节，只需要在packages中声明自己所需的依赖即可 - -#### 注意事项 - -- 依赖的开发者在自己的入口app.mpx中注册页面时对于本地页面一定要使用相对路径进行注册，否则在主app中进行编译时会找不到对应的页面 -- 不管是用json还是mpx格式定义package入口，编译时永远只会解析json且只会关注json中的pages和packages域，其余所有东西在主app编译时都会被忽略 -- 由于我们是将packages中注册的页面按照原始的路径合并到主app当中，有可能会出现路径名冲突。 -这种情况下编译会报出响应错误提示用户解决冲突，为了避免这种情况的发生，依赖的提供者最好将自己内部的页面放置在能够描述依赖特性的子文件夹下。 - -例如一个包叫login，建议包内页面文件目录为： - -``` -project -│ app.mpx -└───pages - └───login - │ page1.mpx - │ page2.mpx - │ ... -``` - -## 分包 - -作为一个对performance极度重视的框架，分包作为提升小程序体验的重要能力，是必须支持的。 - -微信文档中有以下三种分包，mpx对这些能力都做了较好的支持。 - -> 分包是小程序平台提供的原生能力，mpx是对该能力做了部分加强，目前微信的分包机制是最全面的，百度其次，支付宝暂时无此能力，请根据平台决定如何使用。 - -- [普通分包](#普通分包) -- [分包预下载](#分包预下载) - -#### 普通分包 - -mpx中会将 app.mpx（入口文件，也不一定非要叫app.mpx） 中packages域下的路径带root为key的query则被解析认为是使用分包加载。 - -> 使用分包一定要记得阅读下面的[分包注意事项](#分包注意事项) - -```html -// @file src/app.mpx - - -// @file src/packages/index.mpx (子包的入口文件) - -``` - -打包结果：dist/app.json -```json -{ - "pages": [ - "pages/index/index" - ], - "subPackages": [ - { - "root": "test", - "pages": [ - "pages/other/other", - "pages/other/other2" - ] - } - ] -} -``` - -分包加载的好处详见微信的文档。路径冲突的概率也大大降低，只需要保证root不同即可。 - -#### 分包预下载 - -> 仅微信小程序提供该部分能力 - -分包预下载是在json中新增一个 preloadRule 字段，mpx打包时候会原封不动把这个部分放到app.json中，所以只需要按照 [微信小程序官方文档 - 分包预下载](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/preload.html) 配置即可。 - -前面的普通分包中提到了subpackages是根据用户在package中通过增加query，key为root来指定分包名。我们进一步扩展了这个能力，允许用户传递更多的query。 - -比如： - -```html -// @file src/app.mpx - - -// @file src/packages/index.mpx (子包的入口文件) - -``` - -打包结果：dist/app.json -```json -{ - "pages": [ - "pages/index/index" - ], - "subPackages": [ - { - "name": "subpack1", - "root": "xxx", - "pages": [ - "pages/other/other", - "pages/other/other2" - ] - } - ] -} -``` - -#### 分包注意事项 - -当我们使用分包加载时，依赖包内的跳转路径需注意，比如要跳转到other2页面 -不用分包时会是：wx.jump/pages/other/other2 -使用分包后应为：/test/pages/other/other2 -即前面会多?root={rootKey}的rootKey这一层 - -为了解决这个问题，有三种方案： - -- import的时候在最后加'?resolve', 例如: `import testPagePath from '../pages/testPage.mpx?resolve'` , 编译时就会把它处理成正确的完整的绝对路径。 - -- 使用相对路径跳转。 - -- 定死使用的分包路径名，直接写/{rootKey}/pages/xxx （极度不推荐，尤其在分包可能被多方引用的情况时） - -建议使用第一种。 - -## 自定义tabbar - -什么是自定义tabbar参见微信文档。https://developers.weixin.qq.com/miniprogram/dev/framework/ability/custom-tabbar.html - -app.mpx的json部分的tabBar里custom一项为true时，需要在 src 目录下存在 custom-tab-bar 目录且里面有index.mpx，这个index.mpx里就编写自定义tabbar的模板、js、样式和json部分即可。 - -**注意事项**：使用该feature时候要认真阅读官方例子，在页面的show钩子上要再手工设置一遍tabbar的selected值。 - -## 体积优化指南 - -由于微信小程序限制主包体积为2M，较复杂的应用可能需要尽可能进行体积优化。 - -分包是微信小程序中优化包体积的核心手段(类似于异步按需加载)，Mpx对其进行了完善的支持，可以精确地标记出分包only的资源。此外还可以从按需构建及分析构建结果等方面下手。 - -1. 尽量让纯分包用的代码和主包用的代码分离（即让资源成为分包only的） - - - 比如分包页面中需要使用一个叫 utilA 的体积很大的方法，主包页面中需要使用一个叫 utilB 的方法，如果你将这两个方法写在同一个 util.js 文件中，util模块最终会被打包到主bundle中，造成没必要的主包体积增大。[更多参考](understanding/understanding.md#分包处理细节) - -2. 在json里做最小声明，mpx本身提供了按需打包的能力，但按需是指按用户的声明，无法做到根据一个page是否被使用来打包 - - - 比如分包单独开发再以npm包形式发布这种开发模式中，可能会出现npm包开发者方为了调试组件编写了多份page引用对应组件仅为调试方便，最终集成时就会让这些调试页面占用空间。可以另提供一份json文件和app.mpx同级，比如叫index.json，开发包时候以app.mpx为入口，集成时候以index.json为入口。 - -3. 使用analysis工具分析体积大的原因 - - - 构建时加上 `--report` 参数，会生成构建图，即可查看整个项目的体积构成来源了，进而分析是哪些模块占据了体积。webpack生态，webpack-bundle-analyzer插件提供的。 diff --git a/docs/single/script-enhance.md b/docs/single/script-enhance.md deleted file mode 100644 index 6db7b27904..0000000000 --- a/docs/single/script-enhance.md +++ /dev/null @@ -1,238 +0,0 @@ -# script增强特性 - -在原生自定义组件config的基础上，`mpx`新增支持了watch、computed、mixins、pageShow & pageHide等字段提高开发体验，同时`mpx`提供一个深度优化的机制来接管小程序的`setData`调用，用户在组件/页面当中可以使用`this.someData = 'abc'`的方式来设置数据，永远不应该直接调用`setData`去设置数据，这有可能导致数据不一致的问题。 - -## computed - -计算属性是一个函数/带setter和getter的对象，利用组合其它数据的方式返回一个新的数据，你可以像绑定普通数据一样在模板中绑定计算属性。 -> 类型：{ [key: string]: Function | { get: Function, set: Function } } -> 适用于【页面 | 组件】 - -示例： - -```html - - - -``` - -## watch - -`mpx`为小程序原生组件提供了观察和响应上的数据变动的能力。虽然计算属性在大多数情况下已满足需求，但有时也需要一个自定义的侦听器。当需要在数据变化时执行异步或开销较大的操作时，这个方式是最有用的。 - -> 适用于【页面 | 组件】 - -例如： - -```html - - - -``` - -除了 watch 选项之外，您还可以使用命令式的 `this.$watch` API。 - -## mixins - -`mixins` 选项接受一个混合对象的数组。这些混合实例对象可以像正常的实例对象一样包含选项，他们将使用相同的选项合并逻辑合并。举例：如果你混合包含一个钩子而创建组件本身也有一个，两个函数将被调用。 -Mixin 钩子按照传入顺序依次调用，并在调用组件自身的钩子之前被调用。 - -> 适用于【APP | 页面 | 组件】 - -示例： - -```js -// mixin.js -export default { - data: { - list: { - 'phone': '手机', - 'tv': '电视', - 'computer': '电脑' - } - }, - ready () { - console.log('mixins ready:', this.list.phone) - } -} -``` - -```html - - - -``` - -输出结果为 -``` -mixins ready: 手机 -component ready: 电视 -``` - - -## 页面生命周期转换 - -除了类支付宝小程序之外，其他平台都能以组件的方式创建页面，因此mpx内部默认是以Component来创建页面的（微信小程序、百度小程序、头条小程序等类微信小程序）。[按官方标准](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/component.html)，以Component创建页面时，页面特有的生命周期（onLoad、onReady、onShow等等）都必须`定义在methods内部`。为了进行统一处理，使用`mpx.createPage创建页面`时，可以统一使用标准页面的格式，`所有生命周期都定义在最外层即可`，mpx内部会根据普通进行`自动转换`到methods里面 - -```html - -``` - -## 组件生命周期扩展 - -> 2.5.x 起不建议使用 -> 2.6.x 将废弃 -> 早期小程序本身缺乏组件感应所在页面的状态的能力做的增强，在小程序本身提供了 pageLifetimes 后失去意义且有不必要的性能开销，2.5.x为了避免业务异常，换手段hack实现了这两个方法，但同时有在控制台提示不要再使用，2.6.x将彻底去掉。 - -除了小程序自定义组件本身的生命周期外，`mpx`为组件本身提供了两个生命周期钩子，`pageShow`和`pageHide`，用于监听当前组件所属页面的显示或隐藏状态。 - -```html - - - -``` diff --git a/docs/single/style-enhance.md b/docs/single/style-enhance.md deleted file mode 100644 index 98a784fa7c..0000000000 --- a/docs/single/style-enhance.md +++ /dev/null @@ -1,190 +0,0 @@ -# style增强特性 - -## css预处理器 - -`mpx`支持所有主流的`css预编译处理`，只需要在` - ``` - -## 样式引用 - -两种方式引用： -- style内使用@import语法引入 -- 在style标签上通过src引入 - -前者会被内联打入 组件/页面 对应的wxss文件，后者则是会将src对应的文件收集到wxss文件夹里，再在 组件/页面 对应的wxss文件中通过@import引入。 - -在一个mpx文件中，两者可以同时使用，例如： - -```vue - - - - - - - - - - -``` - -**建议对于多个 页面/组件 公用的样式，使用src形式引入，避免一份样式被内联打成多份。** - -## rpx转换 - -为了处理某些ide中不支持`rpx`单位的问题，`mpx`提供了一个将px转换为rpx的功能。 - -支持通过注释控制行级、块级的是否转换，支持局部使用，支持不同依赖分别使用不用的转换规则等灵活的能力。 - -通过transRpx参数来进行配置，配置项是这样 **一个对象** ，也可以是 **多个这样的对象组成的数组** 。 - -```js -const transRpx = { - mode: 'all', // 可选值有none/only/all 分别是不启用，只对注释内容启用，只不对注释内容启用 - comment: 'use px', // rpx注释，建议使用 'use px' / 'use rpx'，当mode为all时默认值为use px，mode为only时默认值为use rpx - include: resolve('src'), // 同webpack的include规则 - exclude: resolve('lib'), // 同webpack的exclude规则 - designWidth: 750 // 设计稿宽度，默认值就是750 -} -``` - -配置在 build.js / webpack.conf.js 中的 MpxWebpackPlugin.loader 的参数中（找已经存在的，勿新加）。关于如何配置详情请查看[mpx-loader选项](/compilationEnhance/index.md#mpxwebpackpluginloader) - -#### 应用场景及相应配置 - -接下来我们来看下一些应用场景及如何配置。如果是用脚手架生成的项目，在webpack.conf.js里找到MpxWebpackPlugin.loader，应该已经有预设的transRpx选项，按例修改即可。本处示例中为了代码合规，声明了新变量表示来这个选项，项目中应该直接为option对象的子属性。 - -三种场景分别是 [普通使用，因设计稿是px的二倍/三倍图](#场景一) ， [只对某些特殊样式转换](#场景二) ， [不同路径分别配置规则](#场景三) - -#### 场景一 -设计师给的稿是2倍图，分辨率750px。或者更高倍图。 - -```js -const transRpx = { - mode: 'all', - designWidth: 750 // 如果是其他倍，修改此值为设计稿的宽度即可 -} -``` - -#### 场景二 - -大部分样式都用px下，某些元素期望用rpx。或者反过来。 - -```js -const transRpx = { - mode: 'only', - comment: 'use rpx', - designWidth: 750 // 设计稿宽度 -} -``` -mpx的rpx注释能帮助你仅为部分类或者部分样式启用rpx转换，细节请看下面附录。 - -#### 场景三 -使用了第三方组件，它的设计宽度和主项目不一致，期望能设置不同的转换规则 - -```js - { - test: /\.mpx$/, - use: MpxWebpackPlugin.loader({ - transRpx: [ - { - mode: 'only', - designWidth: 750, - comment: 'use rpx', - include: resolve('src') - }, - { - mode: 'all', - designWidth: 1280, // 对iview单独使用一个不同的designWidth - include: resolve('node_modules/iview-weapp') - } - ] - }) - } -``` - -> 注意事项：转换规则是不可以对一个文件做多次转换的，会出错，所以一旦被一个规则命中后就不会再次命中另一个规则，include和exclude的编写需要注意先后顺序，就比如上面这个配置，如果第一个规则include的是'/'即整个项目，iview-weapp里的样式就无法命中第二条规则了。 - -#### transRpx附录 - -designWidth - -设计稿宽度，单位为`px`。默认值为`750px`。 - -`mpx`会基于小程序标准的屏幕宽度`baseWidth 750rpx`，与`option.designWidth`计算出一个转换比例`transRatio` - -转换比例的计算方式为`transRatio = (baseWidth / designWidth)`。精度为小数点后2位四舍五入 - -所有生效的`rpx注释样式`中的px会乘上`transRatio`得出最终的rpx值 - -例如： - -```css -/* 转换前：designWidth = 1280 */ -.btn { - width: 200px; - height: 100px; -} - -/* 转换后: transRatio = 0.59 */ -.btn { - width: 118rpx; - height: 59rpx; -} -``` ---- - -comment: rpx注释样式 - -根据`rpx注释`的位置，`mpx`会将`一段css规则`或者`一条css声明`视为`rpx注释样式` - -开发者可以声明一段rpx注释样式，提示编译器是否转换这段css中的px - -例如： -```html - -``` -> 第一个注释位于一个`选择器`前，是一个`css规则注释`，整个规则都会被视为`rpx注释样式` - -> 第二个注释位于一个`css声明`前，是一个`css声明注释`，只有`font-size: 100px`会被视为`rpx注释样式` - -> `transRpx = all`模式下，除了这两条rpx注释样式之外，其他都会转rpx diff --git a/docs/single/template-enhance.md b/docs/single/template-enhance.md deleted file mode 100644 index 199ee2e607..0000000000 --- a/docs/single/template-enhance.md +++ /dev/null @@ -1,248 +0,0 @@ -# template增强特性 - -对于模板部分，我们提供了class与style的绑定，`wx:model`指令，动态组件等特性 - -## class与style绑定 - -#### 绑定HTML Class - -类似vue的class绑定 - -例子： -```html - - - - - -``` - -当该组件接受一个参数isActive为true时，就会为view加上class:active。 - -> 注意：由于微信的限制，wx:class 中的 key 值不能使用引号（如: { 'my-class-name': xx }）。 - -#### 绑定内联样式 - -例子： -```html - - - -``` - -## 内联事件绑定 - -对于事件处理在模板上的绑定，原生小程序只能通过事件信息结合手工拿取data里的信息，我们希望能和vue的事件绑定一样更灵活地传参 - -例子： -```html - - - -``` - -> 注意：由于微信的限制，如果事件名使用横线链接分割（如: 'value-change'），将不可以使用该feature。以及在wx:for中，若遍历的是对象数组，内联传入的item并非是对象的引用，若想修改对象，请用index到原数组中获取。 - -## 动态组件 - -通过使用保留的 `` 组件，并对其 is 特性进行动态绑定，你可以在同一个挂载点动态切换多个组件： - -```html - - - - - -``` - -## 双向绑定 - -除了小程序原生指令之外，mpx 基于`input`事件提供了一个指令 `wx:model`, 用于双向绑定。 - -例子： -```html - - - -``` - -wx:model并不会影响相关的事件处理函数，比如像下面这样： - -```html - -``` - -#### wx:model对应的属性和事件 - -wx:model默认监听`input`事件使用`value`属性传值，如果我们希望改变默认行为，可以使用`wx:model-prop`和`wx:model-event`来定义wx:model对应的属性和事件： - -父组件 -```html - - - -``` - -子组件（customCheck） -```html - - - -``` - -如示例，当子组件被点击时，父组件的checked数据会发生变化 - -> 注意：由于微信的限制，如果事件名使用横线链接分割（如: 'checked-change'），将不可以使用该feature。 - -以及并不是所有的组件都会按微信的标准格式event.detail.value来传值，比如vant的input组件，值的抛出是用event.detail本身来传递的，这时我们可以使用 `wx:model-value-path` 来指定双向绑定时的取值路径。 - -例如： -```html - -``` - -## Refs - -提供了 `wx:ref="xxx"` 来更方便获取 WXML 节点信息的对象。在JS里只需要通过this.$refs.xxx 即可获取节点。 - -示例： -```html - - - -``` diff --git a/docs/single/what-is-single-file.md b/docs/single/what-is-single-file.md deleted file mode 100644 index e95ae09c34..0000000000 --- a/docs/single/what-is-single-file.md +++ /dev/null @@ -1,184 +0,0 @@ -# 单文件 - -介绍单文件编译开发特性，包括单文件中有哪些部分以及如何进行ide配置等 - -## 介绍 - -按照小程序的文件规范，app & page & component 的组成部分都是四个文件，js, wxss, wxml, json; 多文件的形式在开发上体验并不是特别友好，使用过`vue`的同学都知道，单文件的开发模式更内聚，更可维护。因此mpx也提供了单文件开发模式，文件扩展名为 `.mpx` - -通过 `webpack` 构建工具和 `mpx-loader` 可以将文件扩展名为 .mpx 的 `single file component` 转换成小程序所需要的四个文件。 - -这四个文件对应于单文件中的四个区域 - -### 基础例子 - -```html - - - - - - - - -``` - -## 编辑器/IDE高亮、提示 - -- [IntelliJ](what-is-single-file.md#IntelliJ) -- [vscode](what-is-single-file.md#vscode) - -#### IntelliJ - -如果使用IntelliJ系IDE开发，可将mpx后缀文件关联到vue类型，按vue解析。 -![关联文件类型](../images/start-tips2.png) -但会报一个warning提示有重复的script标签，关闭该警告即可。 -![关闭警告](../images/start-tips1.png) - - -#### vscode - -在Visual Studio Marketplace中获取[Mpx语法高亮插件](https://marketplace.visualstudio.com/items?itemName=pagnkelly.mpx) - -> 下方的方案为社区同学贡献，通过更多的插件使用，可能在某些功能上有所增强，但也可能遇到一些其他问题，请个人判断是否需要 - -##### vscode插件 - -因为`.mpx`采用类似于`.vue`的单文件语法风格，可以使用Vue的插件通过[配置vscode扩展语言](https://code.visualstudio.com/docs/languages/overview#_adding-a-file-extension-to-a-language) -，将`.mpx`绑定到`.vue`语法的支持。 - -此外还有minapp插件可以配合使用。 - -**更新**: `minapp`最新版已经支持了mpx，所以对`minapp`的使用加以修改 - -1. `minapp`此插件主要功能是给`template`加上`wxml`的`snippet`功能，只要在 template 标签中添加属性`minapp='mpx' xlang='wxml'`就可以使用 -2. `wechat-snippet`，主要是使用里面的`wx.xxx`的snippet -3. `vetur`主要使用其高亮和格式化功能，配套安装有`prettier`，新版配置为 - -``` - "vetur.format.defaultFormatterOptions": { - "prettyhtml": { - "printWidth": 100, // No line exceeds 100 characters - "singleQuote": false // Prefer double quotes over single quotes - }, - "prettier": { - // Prettier option here - "semi": false, - "singleQuote": true, - "eslintIntegration": true - } - } -``` - -**注意**: -1. 当添加了`xlang="wxml"`后，可以使用`vetur`配置的`template`的格式化，但是会存在vue插件的`snippet` -2. **在改成`xlang="wxml"`后，虽然能格式化了，但是`image`和`input`标签的格式化会出问题，所以最好在最后完成的时候，改回`lang="wxml"`关闭格式化** -3. 注意使用vscode的工作区功能，最好把`vue`插件相关提示先关闭了 -4. 因为`mpx`单文件具有两个script标签，直接格式化会出问题，需要 -``` - -``` -如上，需要在json的script中，加上`lang="json"`这样就不会对这个标签进行格式化 - -##### vscode代码片段 - -此功能主要是为了新建文件后快速生成一些代码，只要在设置里，选择`用户代码片段`，在选择`vue.json`，将以下代码复制进去。之后只要输出写好的`prefix`，就能自动提示生成。 -如此你也可以对`javascript.json`做一些自定义的代码片段 -``` -"Print to weapp page": { - "prefix": "page", - "body": [ - "\n", - "\n", - "", - "\n", - "$2" - ], - "description": "weapp page" -}, -"Print to weapp components": { - "prefix": "components", - "body": [ - "\n", - "\n", - "", - "\n", - "$2" - ], - "description": "weapp components" -} -``` diff --git a/docs/start.md b/docs/start.md deleted file mode 100644 index ff6ae39249..0000000000 --- a/docs/start.md +++ /dev/null @@ -1,229 +0,0 @@ -# 开始 - -使用脚手架`mpx-cli`，快速开始开发mpx小程序 -## 安装mpx-cli -```shell -npm i -g @mpxjs/cli -``` - -## 创建工程 - -* 在当前目录中创建工程目录 - -```shell -mpx create -``` - -`插件项目`由于微信限制必须填写插件的`AppID`，`普通项目`无强制要求。 - -## mpx编译 - -启动服务，mpx会将源码编译成小程序识别的代码，并监听文件变化进行重编译 - -```shell -npm install -npm run serve -``` - -## 小程序编译 -mpx编译完成后，会将小程序代码放置在dist目录 - -参考小程序官方的[开发指南](https://developers.weixin.qq.com/miniprogram/dev/)进行预览、调试 - -## 创建App/Page/Component - -我们通过createApp、createPage、createComponent（分别对应小程序原生的App、Page、Component方法）来创建小程序、页面、组件。 - -下面看一个例子： - -## 例子 - -开始一个demo项目的流程。 - -初始化项目： -![安装项目](images/start-install.png) - -接下来： -```bash -# 进入project -cd mpx-demo - -# 安装依赖 -npm i - -# 进行开发 -npm run serve -``` - -![开启服务](images/start-start.png) - -用微信开发者工具打开目录 `~/testproject/mpx-test/dist` - -在src/app.mpx创建一个App - -```html - - - - - - -``` - -在src/pages创建Page - -```html - - - - - - - - - -``` - -修改src/component/list/list.mpx的代码： - -```html - - - - - - - - -``` - -更多用法可以看这个todoMVC示例：https://github.com/didi/mpx/tree/master/examples/mpx-todoMVC diff --git a/docs/store/index.md b/docs/store/index.md deleted file mode 100644 index f9cbe75ba7..0000000000 --- a/docs/store/index.md +++ /dev/null @@ -1,802 +0,0 @@ -# 数据管理 - -我们对比了redux和vuex的设计，觉得vuex的设计更加地简单易用，最终参考了vuex的设计提供了一套数据管理方案，与vuex不同的是，我们提供了完善多实例store模式管理方案，以方便更加复杂的业务场景进行使用。 - -这是一个简单的例子： - -* [开始](#开始) - -和Vuex类似，我们的mpx内置store主要有以下核心概念： - -* [state](#state) -* [getters](#getter) -* [mutation](#mutation) -* [action](#action) -* [子模块](#module) -* [多实例store](#多实例) - -一些示例： -- [todoMVC示例](https://github.com/didi/mpx/tree/master/examples/mpx-todoMVC) - -# 开始 - -“store”基本上就是一个容器，它包含着你的应用中大部分的状态 (state)。store 和单纯的全局对象有以下两点不同： - -1. store 的状态存储是响应式的。当 mpx 组件从 store 中读取状态的时候，若 store 中的状态发生变化，那么相应的组件也会相应地得到高效更新。 - -2. 你不能直接改变 store 中的状态。改变 store 中的状态的唯一途径就是显式地提交 (commit) mutation。这样使得我们可以方便地跟踪每一个状态的变化。 - -### 最简单的store - -让我们来创建一个 store。创建过程直截了当——仅需要提供一个初始 state 对象和一些 mutation： - -```js -import {createStore} from '@mpxjs/core' - -const store = createStore({ - state: { - count: 0 - }, - mutations: { - increment (state) { - state.count++ - } - } -}) - -export default store -``` - -现在，你可以通过 store.state 来获取状态对象，以及通过 store.commit 方法触发状态变更： - -```js -store.commit('increment') - -console.log(store.state.count) // -> 1 -``` - -再次强调，我们通过提交 mutation 的方式，而非直接改变 store.state.count，是因为我们想要更明确地追踪到状态的变化。 - -接下来，我们将会更深入地探讨一些核心概念。让我们先从 [State](#state) 概念开始。 - -# State - -### 在 mpx 组件中获得 store 状态 - -那么我们如何在 mpx 组件中展示状态呢？由于 mpx内置的store 的状态存储是响应式的，从 store 实例中读取状态最简单的方法就是在计算属性中返回某个状态： - -```js -// store.js -import {createStore} from '@mpxjs/core' - -const store = createStore({ - state: { - count: 0 - }, - mutations: { - increment (state) { - state.count++ - } - } -}) - -export default store -``` - -``` js -import store from '../store' -import {createComponent} from '@mpxjs/core' - -createComponent({ - computed: { - count () { - return store.state.count - } - } -}) -``` - -每当 `store.state.count` 变化的时候, 都会重新求取计算属性，并且触发更新相关联的 DOM。 - -因为小程序原生组件的限制，无法实现自动向上查找父组件挂载的store，所以mpx的store无法像vuex一样提供vue类似的注入机制将其注入到每一个子组件中，所以需要在每个要用到store的地方手工地显式引入。 - -### `mapState` 辅助函数 - -当一个组件需要获取多个状态时候，将这些状态都声明为计算属性会有些重复和冗余。为了解决这个问题，我们可以使用 `store.mapState` 辅助函数帮助我们生成计算属性 - -``` js -// 在单独构建的版本中辅助函数为 mpx内置的store.mapState -import store from '../store' -import {createComponent} from '@mpxjs/core' - -createComponent({ - // ... - computed: store.mapState({ - // 箭头函数可使代码更简练 - count: state => state.count, - - // 传字符串参数 'count' 等同于 `state => state.count` - countAlias: 'count', - - // 为了能够使用 `this` 获取局部状态，必须使用常规函数 - countPlusLocalState (state) { - return state.count + this.localCount - } - }) -}) -``` - -当映射的计算属性的名称与 state 的子节点名称相同时，我们也可以给 `store.mapState` 传一个字符串数组。 - -``` js -import store from '../store' -import {createComponent} from '@mpxjs/core' - -createComponent({ - computed: store.mapState([ - // 映射 this.count 为 store.state.count - 'count' - ]) -}) -``` - -### 对象展开运算符 - -`store.mapState` 函数返回的是一个对象。我们如何将它与局部计算属性混合使用呢？通常，我们需要使用一个工具函数将多个对象合并为一个，以使我们可以将最终对象传给 `computed` 属性。但是自从有了[对象展开运算符](https://github.com/sebmarkbage/ecmascript-rest-spread)（现处于 ECMASCript 提案 stage-3 阶段），我们可以极大地简化写法： - -``` js -import store from '../store' -import {createComponent} from '@mpxjs/core' - -createComponent({ - computed: { - localComputed () { /* ... */ }, - // 使用对象展开运算符将此对象混入到外部对象中 - ...store.mapState({ - // ... - }) - } -}) -``` - -### 组件仍然保有局部状态 - -使用 mpx内置的store 并不意味着你需要将**所有的**状态放入`store`。如果有些状态严格属于单个组件，最好还是作为组件的`局部状态data` - -# Getter - -有时候我们需要从 store 中的 state 中派生出一些状态，例如对列表进行过滤并计数： - -```js -computed: { - doneTodosCount () { - return store.state.todos.filter(todo => todo.done).length - } -} -``` - -如果有多个组件需要用到此属性，我们要么复制这个函数，或者抽取到一个共享函数然后在多处导入它——无论哪种方式都不是很理想。 - -mpx内置store 允许我们在 store 中定义“getter”（可以认为是 store 的计算属性）。就像计算属性一样，getter 的返回值会根据它的依赖被缓存起来，且只有当它的依赖值发生了改变才会被重新计算。 - -Getter 接受 state 作为其第一个参数： - -```js -import {createStore} from '@mpxjs/core' - -const store = createStore({ - state: { - todos: [ - { id: 1, text: '...', done: true }, - { id: 2, text: '...', done: false } - ] - }, - getters: { - doneTodos: state => { - return state.todos.filter(todo => todo.done) - } - } -}) - -export default store -``` - -Getter 会暴露为 `store.getters` 对象： - -``` js -store.getters.doneTodos // -> [{ id: 1, text: '...', done: true }] -``` - -Getter 也可以接受其他 getters 作为第二个参数, rootState作为第三个参数： - -```js -getters: { - // ... - doneTodosCount: (state, getters, rootState) => { - return getters.doneTodos.length - } -} -``` - -```js -store.getters.doneTodosCount // -> 1 -``` - -我们可以很容易地在任何组件中使用它： - -``` js -computed: { - doneTodosCount () { - return store.getters.doneTodosCount - } -} -``` - -你也可以通过让 getter 返回一个函数，来实现给 getter 传参。在你对 store 里的数组进行查询时非常有用。 - -```js -getters: { - // ... - getTodoById: (state) => (id) => { - return state.todos.find(todo => todo.id === id) - } -} -``` - -```js -store.getters.getTodoById(2) // -> { id: 2, text: '...', done: false } -``` - -### `store.mapGetters` 辅助函数 - -`store.mapGetters` 辅助函数仅仅是将 store 中的 getter 映射到局部计算属性`computed`里面： - -``` js -import store from 'path to store' - -export default { - // ... - computed: { - // 使用对象展开运算符将 getter 混入 computed 对象中 - ...store.mapGetters([ - 'doneTodosCount', - 'anotherGetter', - // ... - ]) - } -} -``` - -如果你想将一个 getter 属性另取一个名字，使用对象形式： - -``` js -store.mapGetters({ - // 映射 `this.doneCount` 为 `store.getters.doneTodosCount` - doneCount: 'doneTodosCount' -}) -``` - -# Mutation - -更改 mpx内置store 的 store 中的状态的唯一方法是提交 mutation。mpx内置store 中的 mutation 非常类似于事件：每个 mutation 都有一个字符串的 **事件类型 (type)** 和 一个 **回调函数 (handler)**。这个回调函数就是我们实际进行状态更改的地方，并且它会接受 state 作为第一个参数： - -``` js -import {createStore} from '@mpxjs/core' - -const store = createStore({ - state: { - count: 1 - }, - mutations: { - increment (state) { - // 变更状态 - state.count++ - } - } -}) - -export default store -``` - -你不能直接调用一个 mutation handler。这个选项更像是事件注册：“当触发一个类型为 `increment` 的 mutation 时，调用此函数。”要唤醒一个 mutation handler，你需要以相应的 type 调用 **store.commit** 方法： - -``` js -store.commit('increment') -``` - -### 提交载荷（Payload） - -你可以向 `store.commit` 传入额外的参数，即 mutation 的 **载荷（payload）**： - -``` js -// ... -mutations: { - increment (state, n) { - state.count += n - } -} -``` -``` js -store.commit('increment', 10) -``` - -在大多数情况下，载荷应该是一个对象，这样可以包含多个字段并且记录的 mutation 会更易读： - -``` js -// ... -mutations: { - increment (state, payload) { - state.count += payload.amount - } -} -``` - -``` js -store.commit('increment', { - amount: 10 -}) -``` - -### Mutation 需遵守的响应规则 - -mpx内置store 中的状态是响应式的，那么当我们变更状态时，监视状态的 mpx页面或组件也会自动更新。这也意味着 mpx内置store 中的 mutation需要遵守一些注意事项： - -1. 无法感知属性的添加或删除，所以最好提前在你的 store 中初始化好所有所需属性。 - -2. 当需要在对象上添加新属性时，你可以 - ``` js - state.obj = { ...state.obj, newProp: 123 } - ``` - -### Mutation 必须是同步函数 - -一条重要的原则就是要记住 **mutation 必须是同步函数** - - -### 在组件中提交 Mutation - -你可以在组件中使用 `store.commit('xxx')` 提交 mutation，或者使用 `store.mapMutations` 辅助函数将组件中的 `methods` 映射为 `store.commit` 调用。 - -``` js -import { createComponent } from '@mpxjs/core' -import store from '../store' - -createComponent({ - // ... - methods: { - ...store.mapMutations([ - 'increment', // 将 `this.increment()` 映射为 `store.commit('increment')` - - // `mapMutations` 也支持载荷： - 'incrementBy' // 将 `this.incrementBy(amount)` 映射为 `store.commit('incrementBy', amount)` - ]), - ...store.mapMutations({ - add: 'increment' // 将 `this.add()` 映射为 `store.commit('increment')` - }) - } -}) -``` - -# Action - -Action 类似于 mutation，不同在于： - -- Action 提交的是 mutation，而不是直接变更状态。 -- Action 可以包含任意异步操作。 - -让我们来注册一个简单的 action： - -``` js -import {createStore} from '@mpxjs/core' - -const store = createStore({ - state: { - count: 0 - }, - mutations: { - increment (state) { - state.count++ - } - }, - actions: { - increment (context) { - context.commit('increment') - }, - increment2({rootState, state, getters, dispatch, commit}) { - } - } -}) - -export default store -``` - -Action 函数接受一个 context 对象，因此你可以调用 `context.commit` 提交一个 mutation，或者通过 `context.rootState`、`context.state` 和 `context.getters` 来获取全局state、局部state 和 全局 getters。 - -实践中，我们会经常用到 ES2015 的 [参数解构](https://github.com/lukehoban/es6features#destructuring) 来简化代码（特别是我们需要调用 `commit` 很多次的时候）： - -``` js -actions: { - increment ({ commit }) { - commit('increment') - } -} -``` - -### 分发 Action - -Action 通过 `store.dispatch` 方法触发： - -``` js -store.dispatch('increment') -``` - -乍一眼看上去感觉多此一举，我们直接分发 mutation 岂不更方便？实际上并非如此，还记得 **mutation 必须同步执行**这个限制么？Action 就不受约束！我们可以在 action 内部执行**异步**操作： - -``` js -actions: { - incrementAsync ({ commit }) { - setTimeout(() => { - commit('increment') - }, 1000) - } -} -``` - -Actions 支持同样的载荷方式进行分发： - -``` js -// 以载荷形式分发 -store.dispatch('incrementAsync', { - amount: 10 -}) -``` - -来看一个更加实际的购物车示例，涉及到**调用异步 API** 和**分发多重 mutation**： - -``` js -actions: { - checkout ({ commit, state }, products) { - // 把当前购物车的物品备份起来 - const savedCartItems = [...state.cart.added] - // 发出结账请求，然后乐观地清空购物车 - commit(types.CHECKOUT_REQUEST) - // 购物 API 接受一个成功回调和一个失败回调 - shop.buyProducts( - products, - // 成功操作 - () => commit(types.CHECKOUT_SUCCESS), - // 失败操作 - () => commit(types.CHECKOUT_FAILURE, savedCartItems) - ) - } -} -``` - -注意我们正在进行一系列的异步操作，并且通过提交 mutation 来记录 action 产生的副作用（即状态变更）。 - -### 在组件中分发 Action - -你在组件中使用 `store.dispatch('xxx')` 分发 action，或者使用 `store.mapActions` 辅助函数将组件的 `methods` 映射为 `store.dispatch` 调用： - -``` js -import { createComponent } from '@mpxjs/core' -import store from '../store' - -createComponent({ - // ... - methods: { - ...store.mapActions([ - 'increment', // 将 `this.increment()` 映射为 `store.dispatch('increment')` - - // `mapActions` 也支持载荷： - 'incrementBy' // 将 `this.incrementBy(amount)` 映射为 `store.dispatch('incrementBy', amount)` - ]), - ...store.mapActions({ - add: 'increment' // 将 `this.add()` 映射为 `store.dispatch('increment')` - }) - } -}) -``` - -### 组合 Action - -Action 通常是异步的，那么如何知道 action 什么时候结束呢？更重要的是，我们如何才能组合多个 action，以处理更加复杂的异步流程？ - -首先，你需要明白 `store.dispatch` 可以处理被触发的 action 的处理函数返回的 Promise，并且 `store.dispatch` 仍旧返回 Promise： - -``` js -actions: { - actionA ({ commit }) { - return new Promise((resolve, reject) => { - setTimeout(() => { - commit('someMutation') - resolve() - }, 1000) - }) - } -} -``` - -现在你可以： - -``` js -store.dispatch('actionA').then(() => { - // ... -}) -``` - -在另外一个 action 中也可以： - -``` js -actions: { - // ... - actionB ({ dispatch, commit }) { - return dispatch('actionA').then(() => { - commit('someOtherMutation') - }) - } -} -``` - -最后，如果我们利用 [async / await](https://tc39.github.io/ecmascript-asyncawait/)，我们可以如下组合 action： - -``` js -// 假设 getData() 和 getOtherData() 返回的是 Promise - -actions: { - async actionA ({ commit }) { - commit('gotData', await getData()) - }, - async actionB ({ dispatch, commit }) { - await dispatch('actionA') // 等待 actionA 完成 - commit('gotOtherData', await getOtherData()) - } -} -``` - -# Module - -> PS：虽然支持module，但不支持namespace。在MPX里，我们更推荐使用[多实例模式](#多实例) - -当应用变得非常复杂时，store 对象就有可能变得相当臃肿。 - -为了解决以上问题，mpx内置store 允许我们将 store 分割成**模块（module）**。每个模块拥有自己的 state、mutation、action、getter、甚至是嵌套子模块——从上至下进行同样方式的分割： - -``` js -import {createStore} from '@mpxjs/core' - -const moduleA = { - state: { ... }, - mutations: { ... }, - actions: { ... }, - getters: { ... } -} - -const moduleB = { - state: { ... }, - mutations: { ... }, - actions: { ... } -} - -const store = createStore({ - modules: { - a: moduleA, - b: moduleB - } -}) - -store.state.a // -> moduleA 的状态 -store.state.b // -> moduleB 的状态 - -export default store -``` - -### 模块的局部状态 - -对于模块内部的 mutation 和 getter，接收的第一个参数是**模块的局部状态对象**。 - -``` js -const moduleA = { - state: { count: 0 }, - mutations: { - increment (state) { - // 这里的 `state` 对象是模块的局部状态 - state.count++ - } - }, - - getters: { - doubleCount (state) { - return state.count * 2 - } - } -} -``` - -同样，对于模块内部的 action，局部状态通过 `context.state` 暴露出来，根节点状态则为 `context.rootState`： - -``` js -const moduleA = { - // ... - actions: { - incrementIfOddOnRootSum ({ state, commit, rootState }) { - if ((state.count + rootState.count) % 2 === 1) { - commit('increment') - } - } - } -} -``` - -对于模块内部的 getter，根节点状态会作为第三个参数暴露出来： - -``` js -const moduleA = { - // ... - getters: { - sumWithRootCount (state, getters, rootState) { - return state.count + rootState.count - } - } -} -``` - -### 模块在组件中的引入方式 - -``` js -const store = createStore({ - modules: { - a: { - state: { - name: 1 - }, - getters: { - getName: s => s.name - } - }, - b: moduleB - } -}) - -createComponent({ - computed: { - // mapState引入module方式有两种 - ...store.mapState({ - test: 'a.name' - }), - ...store.mapState('a', ['name']), - ...store.mapGetters('getName') // 由于没有提供namespace概念，所以getters都是全局的，类似的还有mutations & actions - } -}) -``` - -# 多实例 - -允许创建多实例，各store实例彼此互相独立，状态互不干扰，不需要考虑命名空间的问题，而且可以随时动态创建一个新的store，更灵活且移植性更高。相对较于[modules](#module)，更推荐多实例模式 - -### 联合多个store实例 - -如果需要使用外部store的数据，`mpx` 也提供的createStore支持传入`deps`参数，表示注入的外部store。在store内部访问外部store的资源使用如下方式（都是加namespace形式的`path访问`模式）。由于注入store的各部分（state, getters, mutations, actions）是 **以key作为namespace** merge在options对应属性内部的，所以deps的key要防止冲突 - -### 基础例子 - -例子： - -```js -import {createStore} from '@mpxjs/core' - -const store1 = createStore({ - state: { - a: 1 - }, - getters: { - getA(state) { - return state.a - } - }, - mutations: { - setA(state, payload) { - state.a = payload - } - }, - actions: { - actionA({commit}, payload) { - commit('setA', payload) - } - } -}) -const store2 = createStore({ - state: { - b: 1 - }, - getters: { - getB(state, getters) { - // 访问外部store1的数据，按路径访问 - return state.b + state.store1.a + getters.store1.getA - } - }, - mutations: { - setB(state, payload) { - state.b = payload - } - }, - actions: { - actionB({dispatch, commit}, payload) { - // 同理，mutations、actions访问外部store1的方法时，也是按路径访问 - commit('store1.setA', payload) - dispatch('store1.actionA', payload) - commit('setB', payload) - } - }, - deps: { - store1 - } -}) - -export {store1, store2} -``` - -### 多store注入下的'store.mapGetters、store.mapMuations、store.mapActions' - -```js - -import {createStore, createComponent} from '@mpxjs/core' -const store1 = createStore({ - state: { - a: 1 - }, - getters: { - getA(state, getters) { - return state.b + state.store1.a + getters.store1.getA - } - }, - mutations: { - setA(state, payload) { - state.a = payload - } - }, - actions: { - actionA({commit}, payload) { - commit('setA', payload) - } - } -}) -const store2 = createStore({ - state: { - b: 1 - }, - getters: { - getB(state) { - return state.b + state.store1.a - } - }, - mutations: { - setB(state, payload) { - state.b = payload - } - }, - actions: { - actionB({dispatch, commit}, payload) { - commit('store1.setA', payload) - dispatch('store1.actionA', payload) - commit('setB', payload) - } - }, - deps: { - // xx: store1 - store1 - } -}) - -// 组件内部使用store -createComponent({ - computed: { - ...store2.mapGetters(['getB']), - // 对于依赖store1的引入，可以使用以下两种方式，类似的mapMutations、mapActions, mapState - ...store2.mapgetters({ - getA: 'store1.getA' - }), - ...store2.mapGetters('store1', ['getA']) - } -}) -``` diff --git a/docs/ts.md b/docs/ts.md deleted file mode 100644 index c0f44d7d45..0000000000 --- a/docs/ts.md +++ /dev/null @@ -1,188 +0,0 @@ -# Typescript支持 - -### 为什么要使用Typescript - -> `TypeScript` 是 `JavaScript` 的强类型版本，就然后在编译期去掉类型和特有语法，生成纯粹的 `JavaScript` 代码。由于最终在浏览器中运行的仍然是 `JavaScript`，所以 `TypeScript` 并不依赖于浏览器的支持，也并不会带来兼容性问题。 - -> `TypeScript` 是 `JavaScript` 的超集，这意味着他支持所有的 `JavaScript` 语法。并在此之上对 `JavaScript` 添加了一些扩展，如 `class` / `interface` / `module` 等。这样会大大提升代码的可阅读性。 - -### 总体上好处可以归纳成下面4点： - -1. 静态类型检查 - - 静态类型检查可以避免很多不必要类型的错误，不用在调试的时候才发现问题。 - -2. IDE 智能提示 - 在 `TypeScript` 这一类语言之前， `JavaScript` 的智能提示基本完全依赖 IDE 提供的猜测。局限性就是，这种猜测可能并不正确。并且也缺乏更多的辅助信息, 所以要正确使用一个类库, 得不断地在文档和 IDE 之间切换，影响心情和效率， 而 `TypeScript` 不仅自己写的类库有丰富的类型信息。 - -3. 代码重构 - - 有时候的确需要修改一些变量/属性/方法名，牵涉到属性和方法的时候，很多改动是跨文件的，不像普通变量可以简单定位 `scope` ， 属性方法名的重命名对于 `JavaScript`来说异常痛苦， 一方面是修改本身就不方便, 另一方面是改了还不确定该改的是不是改了，不该改的是不是也改了。而 TypeScript 的静态类型系统就可以较为完美的解决这个问题。 - -4. 可读性 - - 对于阅读代码的人来讲，各种便利的类型一目了然，更容易明白作者的意图。 - -## 使用方式 - -### .mpx中编写ts - -.mpx文件中script标签声明lang为ts，在编译时会自动这部分script中的内容进行ts类型检查 - -```html - -``` - -由于大部分IDE对ts的语法提示支持都只对.ts和.d.ts文件生效，上述在.mpx文件中编写ts代码虽然能在编译时进行ts类型检查，但是无法享受IDE中编写ts时的代码提示和实时报错等优秀体验，所以，我们更建议大家创建一个.ts文件进行ts代码编写，通过src的方式引入到.mpx当中 - -```html - -``` - -### 为.ts文件添加loader - -在webpack配置中添加如下rules以配置ts-loader - -```js -{ - test: /\.ts$/, - use: [ - 'babel-loader', - 'ts-loader' - ] -} -``` - -### 编写tsconfig.json文件 - -对相关配置不熟悉的同学可以直接采用下面配置，能够最大限度发挥mpx中强大的ts类型推导能力 - -```json -{ - "compilerOptions": { - "target": "es6", - "allowJs": true, - "noImplicitThis": true, - "noImplicitAny": true, - "strictNullChecks": true, - "moduleResolution": "node", - "lib": [ - "dom", - "es6", - "dom.iterable" - ] - } -} -``` - -### 增强类型 - -如果需要增加 Mpx 的属性和选项，可以自定义声明 TypeScript 补充现有的类型。 - -例如，首先创建一个 types.d.ts 文件 - -```ts -// types.d.ts - -import { Mpx } from '@mpxjs/core' - -declare module '@mpxjs/core' { - // 声明为 Mpx 补充的属性 - interface Mpx { - $myProperty: string - } -} -``` - -之后在任意文件只需引用一次 types.d.ts 声明文件即可，例如在 app.mpx 中引用 - -```ts -// app.mpx - -/// -import mpx from '@mpxjs/core' - -mpx.$myProperty = 'my-property' -``` - -## 类型推导及注意事项 - -Mpx基于泛型函数提供了非常方便用户使用的反向类型推导能力，简单来说，就是用户可以用非常接近于js的方式调用Mpx提供的api，就能够获得大量基于用户输入参数反向推导得到的类型提示及检查。但是由于ts本身的能力限制，我们在mpx的运行时中添加了少量辅助函数和变种api，便于用户最大程度地享受反向类型推导带来的便利性，具体的注意事项和使用方法如下述demo - -```typescript -import {createComponent, getMixin, createStoreWithThis} from '@mpxjs/core' - -// createStoreWithThis作为createStore的变种方法，主要变化在于定义getters，mutations和actions时， -// 获取自身的state，getters等属性不再通过参数传入，而是通过this.state或者this.getters等属性进行访问， -// 由于TS的能力限制，getters/mutations/actions只有使用对象字面量的方式直接传入createStoreWithThis时 -// 才能正确推导出this的类型，当需要将getters/mutations/actions拆解为对象编写时， -// 需要用户显式地声明this类型，无法直接推导得出。 - -const store = createStoreWithThis({ - state: { - aa: 1, - bb: 2 - }, - getters: { - cc() { - return this.state.aa + this.state.bb - } - }, - actions: { - doSth3() { - console.log(this.getters.cc) - return false - } - } -}) - - -createComponent({ - data: { - a: 1, - b: '2' - }, - computed: { - c() { - return this.b - }, - d() { - // data, mixin, computed中定义的数据能够被推导到this中 - return this.a + this.aaa + this.c - }, - // 从store上map过来的计算属性或者方法同样能够被推导到this中 - ...store.mapState(['aa']) - }, - mixins: [ - // 使用mixins，需要对每一个mixin子项进行getMixin辅助函数包裹，支持嵌套mixin - getMixin({ - computed: { - aaa() { - return 123 - } - }, - methods: { - doSth() { - console.log(this.aaa) - return false - } - } - }) - ], - methods: { - doSth2() { - this.a++ - console.log(this.d) - console.log(this.aa) - this.doSth3() - }, - ...store.mapActions(['doSth3']) - } -}) -``` - -更加具体的使用方法和实现原理我们会在后面的文档和文章中补充完整 - - diff --git a/docs/understanding/resource.md b/docs/understanding/resource.md deleted file mode 100644 index 5e2a0d842f..0000000000 --- a/docs/understanding/resource.md +++ /dev/null @@ -1,157 +0,0 @@ -# 图像资源处理 - -小程序对于图片资源存在一些限制，使得习惯开发web应用的开发者面对小程序时无法理解差异性 - -~~mpx提供了[@mpxjs/url-loader](/compilationEnhance/index.md#mpxjsurl-loader)对小程序中各种资源加载方式进行处理。~~ (该loader已被默认整合进 MpxWebpackPlugin.loader) - -本文会从使用的角度出发，介绍小程序既有的对图像资源的限制，以及 MpxWebpackPlugin.loader 是如何解决这些问题。 - ----- -## 引用线上资源 - -小程序原生支持在`wxss`和`wxml`中使用线上资源，这点和开发web应用没有太多区别。 - -无需任何配置，就可以直接在`.mpx`中引用线上资源。 - -**webpack.config.js** -```js -webpackconfig = { - // 不需要配置 -} -``` - -**index.mpx** -```html - - -``` - ----- -## 引用本地资源 - -* 在` - ``` - > 编译后变成base64 - -* ` / `组件src属性使用本地资源，@mpxjs/webpack-plugin提供了urlLoader来处理本地图片资源。 - - **webpack.config.js** - ```js - webpackconfig = { - module: { - rules: [ - { - test: /\.(png|jpe?g|gif|svg)(\?.*)?$/, - loader: MpxWebpackPlugin.urlLoader({ - name: 'img/[name].[ext]' - }) - } - ] - } - } - ``` - - **index.mpx** - ```html - - ``` - -## 动态引用本地资源 -利用`@mpxjs/url-loader`，配合mpx提供的`计算属性`，实现在运行阶段动态设置图片 - -**文件目录** - ``` - component - │-- index.mpx - │-- dark.png - │-- light.png - ``` - -**webpack.config.js** -```js -webpackconfig = { - module: { - rules: [ - { - test: /\.(png|jpe?g|gif|svg)(\?.*)?$/, - loader: MpxWebpackPlugin.urlLoader({ - name: 'img/[name].[ext]' - }) - } - ] - } -} -``` - -**index.mpx** -```html - - - - - -``` - -> 通过点击button，两个元素的图片会动态变化 diff --git a/docs/understanding/understanding.md b/docs/understanding/understanding.md deleted file mode 100644 index c3705f8c39..0000000000 --- a/docs/understanding/understanding.md +++ /dev/null @@ -1,60 +0,0 @@ -# mpx运行机制 - -下面我们分别从运行时和编译两个方面介绍mpx的实现机制 - -## 数据响应与性能优化 -数据响应作为Vue最核心的特性，在我们的日常开发中被大量使用，能够极大地提高前端开发体验和效率，我们在框架设计初期最早考虑的就是如何将数据响应特性加入到小程序开发中。在数据响应的实现上，我们引入了MobX，一个实现了纯粹数据响应能力的知名开源项目。借助MobX和mixins，我们在小程序组件创建初期建立了一个响应式数据管理系统，该系统观察着小程序组件中的所有数据(data/props/computed)并基于数据的变更驱动视图的渲染(setData)及用户注册的watch回调，实现了Vue中的数据响应编程体验。与此同时，我们基于MobX封装实现了一个Vuex规范的数据管理store，能够方便地注入组件进行全局数据管理。为了提高跨团队开发的体验，我们对store添加了多实例可合并的特性，不同团队维护自己的store，在需要时能够合并他人或者公共的store生成新的store实例，我们认为这是一种比Vuex中modules更加灵活便捷的跨团队数据管理模式 - -作为一个接管了小程序setData的数据响应开发框架，我们高度重视Mpx的渲染性能，通过小程序官方文档中提到的性能优化建议可以得知，setData对于小程序性能来说是重中之重，setData优化的方向主要有两个： -1. 尽可能减少setData调用的频次 -2. 尽可能减少单次setData传输的数据 - -为了实现以上两个优化方向，我们做了以下几项工作： -* 将组件的静态模板编译为可执行的render函数，通过render函数收集模板数据依赖，只有当render函数中的依赖数据发生变化时才会触发小程序组件的setData，同时通过一个异步队列确保一个tick中最多只会进行一次setData，这个机制和Vue中的render机制非常类似，大大降低了setData的调用频次； -* 将模板编译render函数的过程中，我们还记录输出了模板中使用的数据路径，在每次需要setData时会根据这些数据路径与上一次的数据进行diff，仅将发生变化的数据通过数据路径的方式进行setData，这样确保了每次setData传输的数据量最低，同时避免了不必要的setData操作，进一步降低了setData的频次。 - -![Mpx数据响应机制流程示意图](https://dpubstatic.udache.com/static/dpubimg/4cb54489-b99d-4560-97aa-68f756730131.jpeg) - -*Mpx数据响应机制流程示意图* - -## 编译构建 -我们希望使用目前设计最强大、生态最完善的编译构建工具Webpack来实现小程序的编译构建，让用户得到web开发中先进强大的工程化开发体验。使用过Webpack的同学都知道，通常来说Webpack都是将项目中使用到的一系列碎片化模块打包为一个或几个bundle，而小程序所需要的文件结构是非常离散化的，如何调解这两者的矛盾成为了我们最大的难题。一种非常直观简单的思路在于遍历整个src目录，将其中的每一个.mpx文件都作为一个entry加入到Webpack中进行处理，这样做的问题主要有两个： -1. src目录中用不到的.mpx文件也会被编译输出，最终也会被小程序打包进项目包中，无意义地增加了包体积； -2. 对于node_modules下的.mpx文件，我们不认为遍历node_modules是一个好的选择。 - -最终我们采用了一种基于依赖分析和动态添加entry的方式来进行实现，用户在Webpack配置中只需要配置一个入口文件app.mpx，loader在解析到json时会解析json中pages域和usingComponents域中声明的路径，通过动态添加entry的方式将这些文件添加到Webpack的构建系统当中（注意这里是添加entry而不是添加依赖，因为只有entry能生成独立的文件，满足小程序的离散化文件结构），并递归执行这个过程，直到整个项目中所有用到的.mpx文件都加入进来，在输出前，我们借助了CommonsChunkPlugin/SplitChunksPlugin的能力将复用的模块抽取到一个外部的bundle中，确保最终生成的包中不包含重复模块。我们提供了一个Webpack插件和一个.mpx文件对应的loader来实现上述操作，用户只需要将其添加到Webpack配置中就可以以打包web项目的方式正常打包小程序，没有任何的前置和后置操作，支持Webpack本身的完整生态。 - -![Mpx编译构建机制流程示意图](https://dpubstatic.udache.com/static/dpubimg/ce6d470c-0a4c-486e-a2f5-ad225c289832.jpeg) - -*Mpx编译构建机制流程示意图* - -### 分包处理细节 - -构建时对于非JS资源，是所有的包串行处理，资源map会精确记录每个包中引用了哪些资源。 - -在主包的处理过程中，将主包页面中引用的所有非js资源(组件、外部样式、外部模板、wxs，图像媒体等)都记录下来，在处理分包时，对分包内引用的非js资源都进行检查，如果被主包引用过则输出到主包中，否则标记为分包only的资源输出到分包目录下。 - -由于主包和分包限制相同，一般情况下分包体积远小于主包体积 -，而微信小程序的体积限制策略主要卡主包体积不得超过2M，因此，Mpx设定的是主包体积优先策略，即尽可能减小主包体积，为此，会将分包资源尽可能打到分包去。 - -组件和静态资源的输出规则如下： - -1. 主包引用的资源输出至主包 -2. 分包引用且主包引用过的资源输出至主包，不在当前分包重复输出 -3. 分包引用且无其他包引用的资源输出至当前分包 -4. 分包引用且其他分包也引用过的资源，重复输出至当前分包 -5. 当用户通过packageName query显式指定了资源的所属包时，输出至指定的包 - -如此复杂的分包策略也完全是为了尽可能良好地支持处理分包引用npm资源，因此不管在主包还是分包中，使用Mpx框架开发小程序，可以享受最舒适最自然最好用的npm机制。 - -而小程序原生的分包是不具备这个能力，只能引用自己分包下的资源，同时大部分基于web技术而来的转译型框架应该也都是不会考虑这个部分的。 - -甚至如果出现这种场景：同一个组件在A分包和B分包中都有使用，但未在主包使用，会将这个组件分别放入A分包和B分包而不是主包。（是否需要这样可自行斟酌，如果不希望出现这种情况，可在主包中引入一次该组件就会被收到主包去，全局就这一份了） - -总结一下： - -对于组件，若同时被多个分包引用，主包未引用，会有多份分包存在于各分包中。一旦被主包使用，就仅有一份存在于主包中。 - -对于资源（例如纯JS模块），若被主包使用，会被收集到主包里。若被多个分包使用，会被收集进主包的bundle里。若仅被某分包使用，就会在分包的bundle.js里（视模块大小及引用次数也可能被内联到某个组件JS里）。 - -进阶用户有更花式的需求可通过packageName query来显示指定输出。 diff --git a/lerna.json b/lerna.json index edc1456c92..c52f6f75d0 100644 --- a/lerna.json +++ b/lerna.json @@ -1,3 +1,3 @@ { - "version": "2.9.70" + "version": "2.9.71" } \ No newline at end of file diff --git a/package.json b/package.json index d57ad55a53..4ac0b77d83 100644 --- a/package.json +++ b/package.json @@ -9,8 +9,9 @@ "lint:js": "eslint --ext .js packages/", "test": "jest", "release": "npm run lint && npm run test && npx lerna version", - "docs:dev": "vuepress dev docs-vuepress", - "docs:build": "vuepress build docs-vuepress", + "docs:dev": "vitepress dev docs-vitepress", + "docs:build": "vitepress build docs-vitepress", + "docs:preview": "vitepress preview docs-vitepress", "tsc:build": "npm --workspace=./packages/webpack-plugin run build" }, "devDependencies": { @@ -23,8 +24,7 @@ "@types/jest": "^27.0.1", "@typescript-eslint/eslint-plugin": "^5.2.0", "@typescript-eslint/parser": "^5.2.0", - "@vuepress/plugin-back-to-top": "^1.8.2", - "@vuepress/plugin-pwa": "^1.8.0", + "@vite-pwa/vitepress": "^0.5.3", "eslint": "^7.32.0", "eslint-config-standard": "^16.0.3", "eslint-plugin-html": "^6.2.0", @@ -36,10 +36,12 @@ "identity-obj-proxy": "^3.0.0", "jest": "^27.2.0", "lerna": "^8.1.8", + "stylus": "^0.63.0", "typescript": "^4.1.3", - "vuepress": "^1.9.7" + "vitepress": "^1.5.0" }, "workspaces": [ - "packages/*" + "packages/*", + "docs-vitepress" ] } diff --git a/packages/api-proxy/package.json b/packages/api-proxy/package.json index 780291bace..70011a35e0 100644 --- a/packages/api-proxy/package.json +++ b/packages/api-proxy/package.json @@ -1,6 +1,6 @@ { "name": "@mpxjs/api-proxy", - "version": "2.9.70", + "version": "2.9.71", "description": "convert miniprogram API at each end", "module": "src/index.js", "types": "@types/index.d.ts", diff --git a/packages/api-proxy/src/platform/api/system/index.web.js b/packages/api-proxy/src/platform/api/system/index.web.js index 2614aa2562..0e756b73d9 100644 --- a/packages/api-proxy/src/platform/api/system/index.web.js +++ b/packages/api-proxy/src/platform/api/system/index.web.js @@ -139,7 +139,7 @@ const getLaunchOptionsSync = function () { throwSSRWarning('getLaunchOptionsSync API is running in non browser environments') return } - return global.__mpxEnterOptions || {} + return global.__mpxLaunchOptions || {} } export { diff --git a/packages/api-proxy/src/platform/api/system/rnSystem.js b/packages/api-proxy/src/platform/api/system/rnSystem.js index acf3965ed9..abc0501466 100644 --- a/packages/api-proxy/src/platform/api/system/rnSystem.js +++ b/packages/api-proxy/src/platform/api/system/rnSystem.js @@ -41,18 +41,11 @@ const getWindowInfo = function () { } const getLaunchOptionsSync = function () { - const options = global.__mpxEnterOptions || {} - const { path, scene, query } = options - return { - path, - scene, - query - } + return global.__mpxLaunchOptions || {} } const getEnterOptionsSync = function () { - const result = getLaunchOptionsSync() - return result + return global.__mpxEnterOptions || {} } export { diff --git a/packages/core/package.json b/packages/core/package.json index 4c7dea508a..a600669839 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@mpxjs/core", - "version": "2.9.70", + "version": "2.9.71", "description": "mpx runtime core", "keywords": [ "miniprogram", diff --git a/packages/core/src/core/mergeOptions.js b/packages/core/src/core/mergeOptions.js index dab3f17421..8b7eaebb3a 100644 --- a/packages/core/src/core/mergeOptions.js +++ b/packages/core/src/core/mergeOptions.js @@ -169,11 +169,7 @@ function extractObservers (options) { cb = this[cb] } if (typeof cb === 'function') { - if (keyPathArr.length < 2) { - val = [val] - old = [old] - } - cb.call(this, ...val, ...old) + Array.isArray(val) ? cb.call(this, ...val) : cb.call(this, val) } }, deep, diff --git a/packages/core/src/platform/builtInMixins/proxyEventMixin.web.js b/packages/core/src/platform/builtInMixins/proxyEventMixin.web.js index 019c74b158..1938d8e349 100644 --- a/packages/core/src/platform/builtInMixins/proxyEventMixin.web.js +++ b/packages/core/src/platform/builtInMixins/proxyEventMixin.web.js @@ -1,4 +1,5 @@ -import { setByPath } from '@mpxjs/utils' +import { setByPath, error, parseDataset } from '@mpxjs/utils' +import Mpx from '../../index' export default function proxyEventMixin () { return { @@ -19,11 +20,58 @@ export default function proxyEventMixin () { const value = filterMethod ? (innerFilter[filterMethod] ? innerFilter[filterMethod](originValue) : typeof this[filterMethod] === 'function' && this[filterMethod]) : originValue setByPath(this, expr, value) }, - __invokeHandler (eventName, $event) { - const handler = this[eventName] - if (handler && typeof handler === 'function') { - handler.call(this, $event) + __invoke (rawEvent, eventConfig = []) { + if (typeof Mpx.config.proxyEventHandler === 'function') { + try { + Mpx.config.proxyEventHandler(rawEvent) + } catch (e) {} } + const location = this.__mpxProxy.options.mpxFileResource + + if (rawEvent.target && !rawEvent.target._datasetProcessed) { + const originalDataset = rawEvent.target.dataset + Object.defineProperty(rawEvent.target, 'dataset', { + get: () => parseDataset(originalDataset), + configurable: true, + enumerable: true + }) + rawEvent.target._datasetProcessed = true + } + if (rawEvent.currentTarget && !rawEvent.currentTarget._datasetProcessed) { + const originalDataset = rawEvent.currentTarget.dataset + Object.defineProperty(rawEvent.currentTarget, 'dataset', { + get: () => parseDataset(originalDataset), + configurable: true, + enumerable: true + }) + rawEvent.currentTarget._datasetProcessed = true + } + + let returnedValue + eventConfig.forEach((item) => { + const callbackName = item[0] + if (callbackName) { + const params = + item.length > 1 + ? item.slice(1).map((item) => { + if (item === '__mpx_event__') { + return rawEvent + } else { + return item + } + }) + : [rawEvent] + if (typeof this[callbackName] === 'function') { + returnedValue = this[callbackName].apply(this, params) + } else { + error( + `Instance property [${callbackName}] is not function, please check.`, + location + ) + } + } + }) + return returnedValue } } } diff --git a/packages/core/src/platform/createApp.ios.js b/packages/core/src/platform/createApp.ios.js index b3ef722394..b74e67c5e4 100644 --- a/packages/core/src/platform/createApp.ios.js +++ b/packages/core/src/platform/createApp.ios.js @@ -1,13 +1,12 @@ import transferOptions from '../core/transferOptions' import builtInKeysMap from './patch/builtInKeysMap' -import { makeMap, spreadProp, getFocusedNavigation, hasOwn, extend } from '@mpxjs/utils' +import { makeMap, spreadProp, getFocusedNavigation, hasOwn } from '@mpxjs/utils' import { mergeLifecycle } from '../convertor/mergeLifecycle' import { LIFECYCLE } from '../platform/patch/lifecycle/index' import Mpx from '../index' import { createElement, memo, useRef, useEffect } from 'react' import * as ReactNative from 'react-native' import { Image } from 'react-native' -import { ref } from '../observer/ref' const appHooksMap = makeMap(mergeLifecycle(LIFECYCLE).app) @@ -30,22 +29,27 @@ function filterOptions (options, appData) { return newOptions } -function createAppInstance (appData) { - return extend({}, Mpx.prototype, appData) -} - -export default function createApp (option, config = {}) { +export default function createApp (options) { const appData = {} const { NavigationContainer, createStackNavigator, SafeAreaProvider } = global.__navigationHelper // app选项目前不需要进行转换 - const { rawOptions, currentInject } = transferOptions(option, 'app', false) + const { rawOptions, currentInject } = transferOptions(options, 'app', false) const defaultOptions = filterOptions(spreadProp(rawOptions, 'methods'), appData) - defaultOptions.onAppInit && defaultOptions.onAppInit() // 在页面script执行前填充getApp() global.getApp = function () { return appData } + + // 模拟小程序appInstance在热启动时不会重新创建的行为，在外部创建跟随js context的appInstance + const appInstance = Object.assign({}, appData, Mpx.prototype) + + defaultOptions.onShow && global.__mpxAppCbs.show.push(defaultOptions.onShow.bind(appInstance)) + defaultOptions.onHide && global.__mpxAppCbs.hide.push(defaultOptions.onHide.bind(appInstance)) + defaultOptions.onError && global.__mpxAppCbs.error.push(defaultOptions.onError.bind(appInstance)) + defaultOptions.onUnhandledRejection && global.__mpxAppCbs.rejection.push(defaultOptions.onUnhandledRejection.bind(appInstance)) + defaultOptions.onAppInit && defaultOptions.onAppInit() + const pages = currentInject.getPages() || {} const firstPage = currentInject.firstPage const Stack = createStackNavigator() @@ -82,55 +86,50 @@ export default function createApp (option, config = {}) { } global.__mpxAppLaunched = false - - global.__mpxAppFocusedState = ref('show') global.__mpxOptionsMap[currentInject.moduleId] = memo((props) => { - const instanceRef = useRef(null) - if (!instanceRef.current) { - instanceRef.current = createAppInstance(appData) - } - const instance = instanceRef.current + const firstRef = useRef(true) const initialRouteRef = useRef({ initialRouteName: firstPage, initialParams: {} }) - - if (!global.__mpxAppLaunched) { + if (firstRef.current) { + // 热启动情况下，app会被销毁重建，将__mpxAppHotLaunched重置保障路由等初始化逻辑正确执行 + global.__mpxAppHotLaunched = false + // 热启动情况下重置__mpxPagesMap避免页面销毁函数未及时执行时错误地引用到之前的navigation + global.__mpxPagesMap = {} + firstRef.current = false + } + if (!global.__mpxAppHotLaunched) { const { initialRouteName, initialParams } = Mpx.config.rnConfig.parseAppProps?.(props) || {} initialRouteRef.current.initialRouteName = initialRouteName || initialRouteRef.current.initialRouteName initialRouteRef.current.initialParams = initialParams || initialRouteRef.current.initialParams global.__mpxAppOnLaunch = (navigation) => { - global.__mpxAppLaunched = true const state = navigation.getState() Mpx.config.rnConfig.onStateChange?.(state) const current = state.routes[state.index] - global.__mpxEnterOptions = { + const options = { path: current.name, query: current.params, scene: 0, shareTicket: '', - referrerInfo: {} + referrerInfo: {}, + isLaunch: true + } + global.__mpxEnterOptions = options + if (!global.__mpxAppLaunched) { + global.__mpxLaunchOptions = options + defaultOptions.onLaunch && defaultOptions.onLaunch.call(appInstance, options) } - defaultOptions.onLaunch && defaultOptions.onLaunch.call(instance, global.__mpxEnterOptions) - defaultOptions.onShow && defaultOptions.onShow.call(instance, global.__mpxEnterOptions) + global.__mpxAppCbs.show.forEach((cb) => { + cb(options) + }) + global.__mpxAppLaunched = true + global.__mpxAppHotLaunched = true } } useEffect(() => { - if (defaultOptions.onShow) { - global.__mpxAppCbs.show.push(defaultOptions.onShow.bind(instance)) - } - if (defaultOptions.onHide) { - global.__mpxAppCbs.hide.push(defaultOptions.onHide.bind(instance)) - } - if (defaultOptions.onError) { - global.__mpxAppCbs.error.push(defaultOptions.onError.bind(instance)) - } - if (defaultOptions.onUnhandledRejection) { - global.__mpxAppCbs.rejection.push(defaultOptions.onUnhandledRejection.bind(instance)) - } - const changeSubscription = ReactNative.AppState.addEventListener('change', (currentState) => { if (currentState === 'active') { let options = global.__mpxEnterOptions diff --git a/packages/core/src/platform/createApp.js b/packages/core/src/platform/createApp.js index 0f35cf97e5..f00d670b56 100644 --- a/packages/core/src/platform/createApp.js +++ b/packages/core/src/platform/createApp.js @@ -24,19 +24,29 @@ function filterOptions (options, appData) { return newOptions } -export default function createApp (option, config = {}) { - // 在App中挂载mpx对象供周边工具访问，如e2e测试 +export default function createApp (options, config = {}) { + const appData = {} + // app选项目前不需要进行转换 + const { rawOptions, currentInject } = transferOptions(options, 'app', false) const builtInMixins = [{ + // 在App中挂载mpx对象供周边工具访问，如e2e测试 getMpx () { return Mpx } }] - const appData = {} if (__mpx_mode__ === 'web') { builtInMixins.push({ + beforeCreate () { + // for vue provide vm access + Object.assign(this, appData, Mpx.prototype) + if (isBrowser) { + rawOptions.onShow && global.__mpxAppCbs.show.push(rawOptions.onShow.bind(this)) + rawOptions.onHide && global.__mpxAppCbs.hide.push(rawOptions.onHide.bind(this)) + rawOptions.onError && global.__mpxAppCbs.error.push(rawOptions.onError.bind(this)) + rawOptions.onUnhandledRejection && global.__mpxAppCbs.rejection.push(rawOptions.onUnhandledRejection.bind(this)) + } + }, created () { - Object.assign(this, Mpx.prototype) - Object.assign(this, appData) const current = this.$root.$options?.router?.currentRoute || {} const options = { path: current.path && current.path.replace(/^\//, ''), @@ -45,48 +55,36 @@ export default function createApp (option, config = {}) { shareTicket: '', referrerInfo: {} } + // web不分冷启动和热启动 global.__mpxEnterOptions = options - this.$options.onLaunch && this.$options.onLaunch.call(this, options) - if (isBrowser) { - if (this.$options.onShow) { - this.$options.onShow.call(this, options) - global.__mpxAppCbs.show.push(this.$options.onShow.bind(this)) - } - if (this.$options.onHide) { - global.__mpxAppCbs.hide.push(this.$options.onHide.bind(this)) - } - if (this.$options.onError) { - global.__mpxAppCbs.error.push(this.$options.onError.bind(this)) - } - if (this.$options.onUnhandledRejection) { - global.__mpxAppCbs.rejection.push(this.$options.onUnhandledRejection.bind(this)) - } - } + global.__mpxLaunchOptions = options + rawOptions.onLaunch && rawOptions.onLaunch.call(this, options) + global.__mpxAppCbs.show.forEach((cb) => { + cb(options) + }) } }) } else { builtInMixins.push({ onLaunch () { Object.assign(this, Mpx.prototype) + initAppProvides(rawOptions.provide, this) } }) } - // app选项目前不需要进行转换 - const { rawOptions, currentInject } = transferOptions(option, 'app', false) rawOptions.mixins = builtInMixins const defaultOptions = filterOptions(spreadProp(mergeOptions(rawOptions, 'app', false), 'methods'), appData) if (__mpx_mode__ === 'web') { - global.__mpxOptionsMap = global.__mpxOptionsMap || {} - global.__mpxOptionsMap[currentInject.moduleId] = defaultOptions global.getApp = function () { if (!isBrowser) { console.error('[Mpx runtime error]: Dangerous API! global.getApp method is running in non browser environments') } return appData } + global.__mpxOptionsMap = global.__mpxOptionsMap || {} + global.__mpxOptionsMap[currentInject.moduleId] = defaultOptions } else { - initAppProvides(rawOptions) defaultOptions.onAppInit && defaultOptions.onAppInit() const ctor = config.customCtor || global.currentCtor || App ctor(defaultOptions) diff --git a/packages/core/src/platform/env/event.js b/packages/core/src/platform/env/event.js index 82cb7bf77a..d6fdb09b66 100644 --- a/packages/core/src/platform/env/event.js +++ b/packages/core/src/platform/env/event.js @@ -11,57 +11,60 @@ function extendEvent (e, extendObj = {}) { }) } -function MpxEvent (layer) { - this.targetElement = null - this.touches = [] - this.touchStartX = 0 - this.touchStartY = 0 - this.startTimer = null - this.needTap = true - this.isTouchDevice = document && ('ontouchstart' in document.documentElement) +function createMpxEvent (layer) { + let startTimer = null + let needTap = true + let touchStartX = 0 + let touchStartY = 0 + let targetElement = null + const isTouchDevice = document && 'ontouchstart' in document.documentElement - this.onTouchStart = (event) => { + const onTouchStart = (event) => { if (event.targetTouches?.length > 1) { return true } - this.touches = event.targetTouches - this.targetElement = event.target - this.needTap = true - this.startTimer = null - this.touchStartX = this.touches[0].pageX - this.touchStartY = this.touches[0].pageY - this.startTimer = setTimeout(() => { - this.needTap = false - this.sendEvent(this.targetElement, 'longpress', event) - this.sendEvent(this.targetElement, 'longtap', event) + const touches = event.targetTouches + targetElement = event.target + needTap = true + startTimer = null + touchStartX = touches[0].pageX + touchStartY = touches[0].pageY + startTimer = setTimeout(() => { + needTap = false + sendEvent(targetElement, 'longpress', event) + sendEvent(targetElement, 'longtap', event) }, 350) } - this.onTouchMove = (event) => { + const onTouchMove = (event) => { const touch = event.changedTouches[0] - if (Math.abs(touch.pageX - this.touchStartX) > 1 || Math.abs(touch.pageY - this.touchStartY) > 1) { - this.needTap = false - this.startTimer && clearTimeout(this.startTimer) - this.startTimer = null + if ( + Math.abs(touch.pageX - touchStartX) > 1 || + Math.abs(touch.pageY - touchStartY) > 1 + ) { + needTap = false + startTimer && clearTimeout(startTimer) + startTimer = null } } - this.onTouchEnd = (event) => { + const onTouchEnd = (event) => { if (event.targetTouches?.length > 1) { return true } - this.startTimer && clearTimeout(this.startTimer) - this.startTimer = null - if (this.needTap) { - this.sendEvent(this.targetElement, 'tap', event) + startTimer && clearTimeout(startTimer) + startTimer = null + if (needTap) { + sendEvent(targetElement, 'tap', event) } } - this.onClick = (event) => { - this.targetElement = event.target - this.sendEvent(this.targetElement, 'tap', event) + const onClick = (event) => { + targetElement = event.target + sendEvent(targetElement, 'tap', event) } - this.sendEvent = (targetElement, type, event) => { + + const sendEvent = (targetElement, type, event) => { const touchEvent = new CustomEvent(type, { bubbles: true, cancelable: true @@ -72,7 +75,6 @@ function MpxEvent (layer) { changedTouches, touches: changedTouches, detail: { - // pc端点击事件可能没有changedTouches，所以直接从 event中取 x: changedTouches[0]?.pageX || event.pageX || 0, y: changedTouches[0]?.pageY || event.pageY || 0 } @@ -80,28 +82,23 @@ function MpxEvent (layer) { targetElement && targetElement.dispatchEvent(touchEvent) } - this.addListener = () => { - if (this.isTouchDevice) { - layer.addEventListener('touchstart', this.onTouchStart, true) - layer.addEventListener('touchmove', this.onTouchMove, true) - layer.addEventListener('touchend', this.onTouchEnd, true) - } else { - layer.addEventListener('click', this.onClick, true) - } + if (isTouchDevice) { + layer.addEventListener('touchstart', onTouchStart, true) + layer.addEventListener('touchmove', onTouchMove, true) + layer.addEventListener('touchend', onTouchEnd, true) + } else { + layer.addEventListener('click', onClick, true) } - this.addListener() } export function initEvent () { if (isBrowser && !global.__mpxCreatedEvent) { global.__mpxCreatedEvent = true if (document.readyState === 'complete' || document.readyState === 'interactive') { - // eslint-disable-next-line no-new - new MpxEvent(document.body) + createMpxEvent(document.body) } else { document.addEventListener('DOMContentLoaded', function () { - // eslint-disable-next-line no-new - new MpxEvent(document.body) + createMpxEvent(document.body) }, false) } } diff --git a/packages/core/src/platform/env/vuePlugin.js b/packages/core/src/platform/env/vuePlugin.js index 4ed365d986..69d0944ea9 100644 --- a/packages/core/src/platform/env/vuePlugin.js +++ b/packages/core/src/platform/env/vuePlugin.js @@ -60,17 +60,23 @@ export default function install (Vue) { data: { get () { return Object.assign({}, this.$props, this.$data) - } + }, + enumerable: true, + configurable: true }, dataset: { get () { return collectDataset(this.$attrs, true) - } + }, + enumerable: true, + configurable: true }, id: { get () { return this.$attrs.id || '' - } + }, + enumerable: true, + configurable: true } }) diff --git a/packages/core/src/platform/export/inject.js b/packages/core/src/platform/export/inject.js index ea73092074..bc387994d0 100644 --- a/packages/core/src/platform/export/inject.js +++ b/packages/core/src/platform/export/inject.js @@ -11,11 +11,10 @@ const providesMap = { global.__mpxProvidesMap = providesMap /** @internal createApp() 初始化应用层 scope provide */ -export function initAppProvides (appOptions) { - const provideOpt = appOptions.provide +export function initAppProvides (provideOpt, instance) { if (provideOpt) { const provided = isFunction(provideOpt) - ? callWithErrorHandling(provideOpt.bind(appOptions), appOptions, 'createApp provide function') + ? callWithErrorHandling(provideOpt.bind(instance), instance, 'createApp provide function') : provideOpt if (isObject(provided)) { providesMap.__app = provided diff --git a/packages/core/src/platform/patch/getDefaultOptions.ios.js b/packages/core/src/platform/patch/getDefaultOptions.ios.js index ac4c5c7561..c98e3ea19b 100644 --- a/packages/core/src/platform/patch/getDefaultOptions.ios.js +++ b/packages/core/src/platform/patch/getDefaultOptions.ios.js @@ -365,14 +365,10 @@ function usePageStatus (navigation, pageId) { const blurSubscription = navigation.addListener('blur', () => { pageStatusMap[pageId] = 'hide' }) - const unWatchAppFocusedState = watch(global.__mpxAppFocusedState, (value) => { - pageStatusMap[pageId] = value - }) return () => { focusSubscription() blurSubscription() - unWatchAppFocusedState() del(pageStatusMap, pageId) } }, [navigation]) @@ -442,10 +438,17 @@ export function getDefaultOptions ({ type, rawOptions = {}, currentInject }) { useEffect(() => { if (type === 'page') { - if (!global.__mpxAppLaunched && global.__mpxAppOnLaunch) { + if (!global.__mpxAppHotLaunched && global.__mpxAppOnLaunch) { global.__mpxAppOnLaunch(props.navigation) } - proxy.callHook(ONLOAD, [props.route.params || {}]) + const loadParams = {} + // 此处拿到的props.route.params内属性的value被进行过了一次decode, 不符合预期，此处额外进行一次encode来与微信对齐 + if (isObject(props.route.params)) { + for (const key in props.route.params) { + loadParams[key] = encodeURIComponent(props.route.params[key]) + } + } + proxy.callHook(ONLOAD, [loadParams]) } proxy.mounted() return () => { diff --git a/packages/fetch/package.json b/packages/fetch/package.json index 9cccf50069..2c5a66fd54 100644 --- a/packages/fetch/package.json +++ b/packages/fetch/package.json @@ -1,6 +1,6 @@ { "name": "@mpxjs/fetch", - "version": "2.9.70", + "version": "2.9.71", "description": "mpx fetch lib", "author": "donghongping", "license": "Apache-2.0", @@ -29,7 +29,7 @@ "test": "echo \"Error: run tests from root\" && exit 1" }, "dependencies": { - "@mpxjs/api-proxy": "^2.9.70", + "@mpxjs/api-proxy": "^2.9.71", "@mpxjs/utils": "^2.9.70", "path-to-regexp": "^6.2.0" }, diff --git a/packages/unocss-plugin/lib/index.js b/packages/unocss-plugin/lib/index.js index ef5ef64412..74054bbad2 100644 --- a/packages/unocss-plugin/lib/index.js +++ b/packages/unocss-plugin/lib/index.js @@ -267,7 +267,7 @@ class MpxUnocssPlugin { // const warn = (msg) => { // compilation.warnings.push(new Error(msg)) // } - const { mode, dynamicEntryInfo, appInfo, assetsModulesMap } = mpx + const { mode, dynamicEntryInfo, appInfo, assetsModulesMap, independentSubpackagesMap } = mpx const uno = await this.createContext(compilation, mode) const config = uno.config @@ -403,7 +403,15 @@ class MpxUnocssPlugin { return Promise.resolve() })) delete packageClassesMaps.main - const commonClassesMap = getCommonClassesMap(Object.values(packageClassesMaps), this.options.minCount) + // const commonClassesMap = getCommonClassesMap(Object.values(packageClassesMaps), this.options.minCount) + const commonClassesMap = getCommonClassesMap(Object.entries(packageClassesMaps) + .filter(([packageRoot, _]) => { + // 独立分包中的classes不需要抽取到主包 + return !independentSubpackagesMap[packageRoot] + }) + .map(([_, classesMap]) => { + return classesMap + }), this.options.minCount) Object.assign(mainClassesMap, commonClassesMap) // 生成主包uno.css let mainUnoFile @@ -458,7 +466,11 @@ class MpxUnocssPlugin { await Promise.all(Object.entries(packageClassesMaps).map(async ([packageRoot, classesMap]) => { let unoFile const classes = Object.keys(classesMap) - const unoFileContent = await this.generateStyle(uno, classes, generateOptions) + const unoFileContent = await this.generateStyle(uno, classes, { + ...generateOptions, + // 独立分包中的unocss文件生成preflights + ...independentSubpackagesMap[packageRoot] ? { preflights: true } : null + }) if (unoFileContent) { unoFile = toPosix(path.join(packageRoot, this.options.unoFile + styleExt)) if (assets[unoFile]) { @@ -479,7 +491,8 @@ class MpxUnocssPlugin { if (filterFile(resourcePath, this.options.scan)) { const entryStyleFile = filename + styleExt const entryStyleSource = getConcatSource('') - if (mainUnoFile) { + // 独立分包中的页面和组件无需引入mainUnoFile + if (mainUnoFile && !independentSubpackagesMap[packageRoot]) { const mainRelativePath = fixRelative(toPosix(path.relative(path.dirname(entryStyleFile), mainUnoFile)), mode) entryStyleSource.add(`@import ${JSON.stringify(mainRelativePath)};\n`) } @@ -505,7 +518,8 @@ class MpxUnocssPlugin { if (styleIsolation === 'isolated' && entryType === 'component') { const componentStyleFile = filename + styleExt const componentStyleSource = getConcatSource('') - if (mainUnoFile) { + // 独立分包中的页面和组件无需引入mainUnoFile + if (mainUnoFile && !independentSubpackagesMap[packageRoot]) { const mainRelativePath = fixRelative(toPosix(path.relative(path.dirname(componentStyleFile), mainUnoFile)), mode) componentStyleSource.add(`@import ${JSON.stringify(mainRelativePath)};\n`) } diff --git a/packages/unocss-plugin/package.json b/packages/unocss-plugin/package.json index 18dd7e550b..8d5051109e 100644 --- a/packages/unocss-plugin/package.json +++ b/packages/unocss-plugin/package.json @@ -1,6 +1,6 @@ { "name": "@mpxjs/unocss-plugin", - "version": "2.9.69", + "version": "2.9.71", "description": "mpx unocss webpack plugin", "main": "lib/index.js", "scripts": { diff --git a/packages/webpack-plugin/lib/platform/template/wx/component-config/movable-view.js b/packages/webpack-plugin/lib/platform/template/wx/component-config/movable-view.js index 77d53b44ed..f24b45bf8a 100644 --- a/packages/webpack-plugin/lib/platform/template/wx/component-config/movable-view.js +++ b/packages/webpack-plugin/lib/platform/template/wx/component-config/movable-view.js @@ -2,6 +2,8 @@ const TAG_NAME = 'movable-view' module.exports = function ({ print }) { const aliEventLog = print({ platform: 'ali', tag: TAG_NAME, isError: false, type: 'event' }) + const androidEventLog = print({ platform: 'android', tag: TAG_NAME, isError: false, type: 'event' }) + const iosEventLog = print({ platform: 'ios', tag: TAG_NAME, isError: false, type: 'event' }) const qaPropLog = print({ platform: 'qa', tag: TAG_NAME, isError: false }) const androidPropLog = print({ platform: 'android', tag: TAG_NAME, isError: false }) const iosPropLog = print({ platform: 'ios', tag: TAG_NAME, isError: false }) @@ -27,7 +29,7 @@ module.exports = function ({ print }) { android: androidPropLog }, { - test: /^(inertia|damping|animation)$/, + test: /^(damping|friction|scale|scale-min|scale-max|scale-value)$/, ios: iosPropLog, android: androidPropLog } @@ -36,6 +38,11 @@ module.exports = function ({ print }) { { test: /^(htouchmove|vtouchmove)$/, ali: aliEventLog + }, + { + test: /^(bindscale)$/, + ios: iosEventLog, + android: androidEventLog } ] } diff --git a/packages/webpack-plugin/lib/platform/template/wx/component-config/picker-view.js b/packages/webpack-plugin/lib/platform/template/wx/component-config/picker-view.js index d18e4ae2d7..7ac0bce94c 100644 --- a/packages/webpack-plugin/lib/platform/template/wx/component-config/picker-view.js +++ b/packages/webpack-plugin/lib/platform/template/wx/component-config/picker-view.js @@ -6,9 +6,7 @@ module.exports = function ({ print }) { const ttPropLog = print({ platform: 'bytedance', tag: TAG_NAME, isError: false }) const ttEventLog = print({ platform: 'bytedance', tag: TAG_NAME, isError: false, type: 'event' }) const jdEventLog = print({ platform: 'jd', tag: TAG_NAME, isError: false, type: 'event' }) - const iosPropLog = print({ platform: 'ios', tag: TAG_NAME, isError: false }) const iosEventLog = print({ platform: 'ios', tag: TAG_NAME, isError: false, type: 'event' }) - const androidPropLog = print({ platform: 'android', tag: TAG_NAME, isError: false }) const androidEventLog = print({ platform: 'android', tag: TAG_NAME, isError: false, type: 'event' }) return { @@ -28,9 +26,7 @@ module.exports = function ({ print }) { props: [ { test: /^(indicator-class|mask-class)$/, - tt: ttPropLog, - ios: iosPropLog, - android: androidPropLog + tt: ttPropLog } ], event: [ diff --git a/packages/webpack-plugin/lib/platform/template/wx/component-config/scroll-view.js b/packages/webpack-plugin/lib/platform/template/wx/component-config/scroll-view.js index a5e426e398..0987235c64 100644 --- a/packages/webpack-plugin/lib/platform/template/wx/component-config/scroll-view.js +++ b/packages/webpack-plugin/lib/platform/template/wx/component-config/scroll-view.js @@ -53,7 +53,7 @@ module.exports = function ({ print }) { qa: qaPropLog }, { - test: /^(scroll-into-view|refresher-threshold|enable-passive|scroll-anchoring|using-sticky|fast-deceleration|enable-flex)$/, + test: /^(refresher-threshold|enable-passive|scroll-anchoring|using-sticky|fast-deceleration|enable-flex)$/, android: androidPropLog, ios: iosPropLog }, diff --git a/packages/webpack-plugin/lib/platform/template/wx/index.js b/packages/webpack-plugin/lib/platform/template/wx/index.js index cc6335c642..1da86356b1 100644 --- a/packages/webpack-plugin/lib/platform/template/wx/index.js +++ b/packages/webpack-plugin/lib/platform/template/wx/index.js @@ -384,10 +384,6 @@ module.exports = function getSpec ({ warn, error }) { } }, web ({ name, value }, { eventRules, el, usingComponents }) { - const parsed = parseMustacheWithContext(value) - if (parsed.hasBinding) { - value = '__invokeHandler(' + parsed.result + ', $event)' - } const match = this.test.exec(name) const prefix = match[1] const eventName = match[2] diff --git a/packages/webpack-plugin/lib/runtime/components/react/context.ts b/packages/webpack-plugin/lib/runtime/components/react/context.ts index 5bb14fc15d..2930ce52e8 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/context.ts +++ b/packages/webpack-plugin/lib/runtime/components/react/context.ts @@ -33,6 +33,10 @@ export interface IntersectionObserver { } } +export interface ScrollViewContextValue { + gestureRef: React.RefObject | null +} + export const MovableAreaContext = createContext({ width: 0, height: 0 }) export const FormContext = createContext(null) @@ -51,4 +55,8 @@ export const IntersectionObserverContext = createContext(null) +export const SwiperContext = createContext({}) + export const KeyboardAvoidContext = createContext(null) + +export const ScrollViewContext = createContext({ gestureRef: null }) diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-button.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-button.tsx index 004afef42c..56881b4a39 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-button.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-button.tsx @@ -34,7 +34,7 @@ * ✘ bindagreeprivacyauthorization * ✔ bindtap */ -import { createElement, useEffect, useRef, useState, ReactNode, forwardRef, useContext, JSX } from 'react' +import { createElement, useEffect, useRef, ReactNode, forwardRef, useContext, JSX } from 'react' import { View, StyleSheet, @@ -45,10 +45,12 @@ import { NativeSyntheticEvent } from 'react-native' import { warn } from '@mpxjs/utils' -import { getCurrentPage, splitProps, splitStyle, useLayout, useTransformStyle, wrapChildren, extendObject } from './utils' +import { GestureDetector, PanGesture } from 'react-native-gesture-handler' +import { getCurrentPage, splitProps, splitStyle, useLayout, useTransformStyle, wrapChildren, extendObject, useHover } from './utils' import useInnerProps, { getCustomEvent } from './getInnerListeners' import useNodesRef, { HandlerRef } from './useNodesRef' import { RouteContext, FormContext } from './context' +import type { ExtendedViewStyle } from './types/common' export type Type = 'default' | 'primary' | 'warn' @@ -68,7 +70,7 @@ export interface ButtonProps { disabled?: boolean loading?: boolean 'hover-class'?: string - 'hover-style'?: ViewStyle & TextStyle & Record + 'hover-style'?: ExtendedViewStyle 'hover-start-time'?: number 'hover-stay-time'?: number 'open-type'?: OpenType @@ -83,8 +85,6 @@ export interface ButtonProps { children: ReactNode bindgetuserinfo?: (userInfo: any) => void bindtap?: (evt: NativeSyntheticEvent | unknown) => void - bindtouchstart?: (evt: NativeSyntheticEvent | unknown) => void - bindtouchend?: (evt: NativeSyntheticEvent | unknown) => void } const LOADING_IMAGE_URI = @@ -216,15 +216,16 @@ const Button = forwardRef, ButtonProps>((buttonPro style = {}, children, bindgetuserinfo, - bindtap, - bindtouchstart, - bindtouchend + bindtap } = props const pageId = useContext(RouteContext) const formContext = useContext(FormContext) + const enableHover = hoverClass !== 'none' + const { isHover, gesture } = useHover({ enableHover, hoverStartTime, hoverStayTime, disabled }) + let submitFn: () => void | undefined let resetFn: () => void | undefined @@ -233,27 +234,15 @@ const Button = forwardRef, ButtonProps>((buttonPro resetFn = formContext.reset } - const refs = useRef<{ - hoverStartTimer: ReturnType | undefined - hoverStayTimer: ReturnType | undefined - }>({ - hoverStartTimer: undefined, - hoverStayTimer: undefined - }) - - const [isHover, setIsHover] = useState(false) - const isMiniSize = size === 'mini' - const applyHoverEffect = isHover && hoverClass !== 'none' - const [color, hoverColor, plainColor, disabledColor] = TypeColorMap[type] - const normalBackgroundColor = disabled ? disabledColor : applyHoverEffect || loading ? hoverColor : color + const normalBackgroundColor = disabled ? disabledColor : isHover || loading ? hoverColor : color const plainBorderColor = disabled ? 'rgba(0, 0, 0, .2)' - : applyHoverEffect + : isHover ? `rgba(${plainColor},.6)` : `rgb(${plainColor})` @@ -261,14 +250,14 @@ const Button = forwardRef, ButtonProps>((buttonPro const plainTextColor = disabled ? 'rgba(0, 0, 0, .2)' - : applyHoverEffect + : isHover ? `rgba(${plainColor}, .6)` : `rgb(${plainColor})` const normalTextColor = type === 'default' - ? `rgba(0, 0, 0, ${disabled ? 0.3 : applyHoverEffect || loading ? 0.6 : 1})` - : `rgba(255 ,255 ,255 , ${disabled || applyHoverEffect || loading ? 0.6 : 1})` + ? `rgba(0, 0, 0, ${disabled ? 0.3 : isHover || loading ? 0.6 : 1})` + : `rgba(255 ,255 ,255 , ${disabled || isHover || loading ? 0.6 : 1})` const viewStyle = { borderWidth: 1, @@ -297,7 +286,7 @@ const Button = forwardRef, ButtonProps>((buttonPro {}, defaultStyle, style, - applyHoverEffect ? hoverStyle : {} + isHover ? hoverStyle : {} ) const { @@ -366,34 +355,6 @@ const Button = forwardRef, ButtonProps>((buttonPro } } - const setStayTimer = () => { - clearTimeout(refs.current.hoverStayTimer) - refs.current.hoverStayTimer = setTimeout(() => { - setIsHover(false) - clearTimeout(refs.current.hoverStayTimer) - }, hoverStayTime) - } - - const setStartTimer = () => { - clearTimeout(refs.current.hoverStartTimer) - refs.current.hoverStartTimer = setTimeout(() => { - setIsHover(true) - clearTimeout(refs.current.hoverStartTimer) - }, hoverStartTime) - } - - const onTouchStart = (evt: NativeSyntheticEvent) => { - bindtouchstart && bindtouchstart(evt) - if (disabled) return - setStartTimer() - } - - const onTouchEnd = (evt: NativeSyntheticEvent) => { - bindtouchend && bindtouchend(evt) - if (disabled) return - setStayTimer() - } - const handleFormTypeFn = () => { if (formType === 'submit') { submitFn && submitFn() @@ -418,8 +379,6 @@ const Button = forwardRef, ButtonProps>((buttonPro }, layoutProps, { - bindtouchstart: (bindtouchstart || !disabled) && onTouchStart, - bindtouchend: (bindtouchend || !disabled) && onTouchEnd, bindtap: !disabled && onTap } ), @@ -442,7 +401,7 @@ const Button = forwardRef, ButtonProps>((buttonPro } ) - return createElement(View, innerProps, loading && createElement(Loading, { alone: !children }), + const baseButton = createElement(View, innerProps, loading && createElement(Loading, { alone: !children }), wrapChildren( props, { @@ -453,6 +412,10 @@ const Button = forwardRef, ButtonProps>((buttonPro } ) ) + + return enableHover + ? createElement(GestureDetector, { gesture: gesture as PanGesture }, baseButton) + : baseButton }) Button.displayName = 'MpxButton' diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-movable-view.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-movable-view.tsx index b6410e9034..905385b43e 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-movable-view.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-movable-view.tsx @@ -11,7 +11,7 @@ * ✘ scale-min * ✘ scale-max * ✘ scale-value - * ✘ animation + * ✔ animation * ✔ bindchange * ✘ bindscale * ✔ htouchmove diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-navigator.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-navigator.tsx index 3de5cfd553..0ea09d353c 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-navigator.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-navigator.tsx @@ -24,7 +24,7 @@ const _Navigator = forwardRef((props, ref): JSX.Element = const { children, 'open-type': openType, - url, + url = '', delta } = props diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column-item.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column-item.tsx new file mode 100644 index 0000000000..7b242689d6 --- /dev/null +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column-item.tsx @@ -0,0 +1,76 @@ +import React, { useEffect } from 'react' +import { LayoutChangeEvent } from 'react-native' +import Reanimated, { Extrapolation, interpolate, useAnimatedStyle, useSharedValue } from 'react-native-reanimated' +import { wrapChildren, extendObject } from './utils' +import { createFaces } from './pickerFaces' +import { usePickerViewColumnAnimationContext, usePickerViewStyleContext } from './pickerVIewContext' + +interface PickerColumnItemProps { + item: React.ReactElement + index: number + itemHeight: number + itemWidth?: number | '100%' + textStyle: Record + visibleCount: number + textProps?: any + onItemLayout?: (e: LayoutChangeEvent) => void +} + +const PickerViewColumnItem: React.FC = ({ + item, + index, + itemHeight, + itemWidth = '100%', + textStyle, + textProps, + visibleCount, + onItemLayout +}) => { + const textStyleFromAncestor = usePickerViewStyleContext() + const offsetYShared = usePickerViewColumnAnimationContext() + const facesShared = useSharedValue(createFaces(itemHeight, visibleCount)) + + useEffect(() => { + facesShared.value = createFaces(itemHeight, visibleCount) + }, [itemHeight]) + + const animatedStyles = useAnimatedStyle(() => { + const inputRange = facesShared.value.map((f) => itemHeight * (index + f.index)) + return { + opacity: interpolate(offsetYShared.value, inputRange, facesShared.value.map((x) => x.opacity), Extrapolation.CLAMP), + transform: [ + { translateY: interpolate(offsetYShared.value, inputRange, facesShared.value.map((x) => x.offsetY), Extrapolation.EXTEND) }, + { rotateX: interpolate(offsetYShared.value, inputRange, facesShared.value.map((x) => x.deg), Extrapolation.CLAMP) + 'deg' }, + { scale: interpolate(offsetYShared.value, inputRange, facesShared.value.map((x) => x.scale), Extrapolation.EXTEND) } + ] + } + }) + + const strKey = `picker-column-item-${index}` + const restProps = index === 0 ? { onLayout: onItemLayout } : {} + const itemProps = extendObject( + { + style: extendObject( + { height: itemHeight, width: '100%' }, + textStyleFromAncestor, + textStyle, + item.props.style + ) + }, + textProps, + restProps + ) + const realItem = React.cloneElement(item, itemProps) + + return ( + + {realItem} + + ) +} + +PickerViewColumnItem.displayName = 'MpxPickerViewColumnItem' +export default PickerViewColumnItem diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column.tsx index a7ce4324d7..e465dd3655 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view-column.tsx @@ -1,17 +1,17 @@ - -import { View, Animated, SafeAreaView, NativeScrollEvent, NativeSyntheticEvent, LayoutChangeEvent, ScrollView } from 'react-native' -import React, { forwardRef, useRef, useState, useMemo, useCallback, useEffect } from 'react' -import { useTransformStyle, splitStyle, splitProps, wrapChildren, useLayout, usePrevious } from './utils' +import React, { forwardRef, useRef, useState, useMemo, useEffect, useCallback } from 'react' +import { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, ScrollView, StyleSheet, View } from 'react-native' +import Reanimated, { AnimatedRef, useAnimatedRef, useScrollViewOffset } from 'react-native-reanimated' +import { useTransformStyle, splitStyle, splitProps, useLayout, usePrevious, isAndroid, isIOS } from './utils' import useNodesRef, { HandlerRef } from './useNodesRef' -import { createFaces } from './pickerFaces' -import PickerOverlay from './pickerOverlay' +import PickerIndicator from './pickerViewIndicator' +import PickerMask from './pickerViewMask' +import MpxPickerVIewColumnItem from './mpx-picker-view-column-item' +import { PickerViewColumnAnimationContext } from './pickerVIewContext' interface ColumnProps { children?: React.ReactNode columnData: React.ReactNode[] initialIndex: number - onColumnItemRawHChange: Function - getInnerLayout: Function onSelectChange: Function style: { [key: string]: any @@ -22,13 +22,11 @@ interface ColumnProps { height: number itemHeight: number } - pickerOverlayStyle: Record + pickerMaskStyle: Record + pickerIndicatorStyle: Record columnIndex: number } -// 默认的单个选项高度 -const DefaultPickerItemH = 36 -// 默认一屏可见选项个数 const visibleCount = 5 const _PickerViewColumn = forwardRef, ColumnProps>((props: ColumnProps, ref) => { @@ -37,57 +35,90 @@ const _PickerViewColumn = forwardRef, columnIndex, initialIndex, onSelectChange, - onColumnItemRawHChange, - getInnerLayout, style, wrapperStyle, - pickerOverlayStyle, + pickerMaskStyle, + pickerIndicatorStyle, 'enable-var': enableVar, 'external-var-context': externalVarContext } = props const { normalStyle, - hasVarDec, - varContextRef, hasSelfPercent, setWidth, setHeight } = useTransformStyle(style, { enableVar, externalVarContext }) - const { textStyle } = splitStyle(normalStyle) - const { textProps } = splitProps(props) - const scrollViewRef = useRef(null) + const { textStyle = {} } = splitStyle(normalStyle) + const { textProps = {} } = splitProps(props) + const scrollViewRef = useAnimatedRef() + const offsetYShared = useScrollViewOffset(scrollViewRef as AnimatedRef) - useNodesRef(props, ref, scrollViewRef, { + useNodesRef(props, ref, scrollViewRef as AnimatedRef, { style: normalStyle }) - const { height: pickerH, itemHeight = DefaultPickerItemH } = wrapperStyle - const [itemRawH, setItemRawH] = useState(0) // 单个选项真实渲染高度 + const { height: pickerH, itemHeight } = wrapperStyle + const [itemRawH, setItemRawH] = useState(itemHeight) const maxIndex = useMemo(() => columnData.length - 1, [columnData]) + const prevScrollingInfo = useRef({ index: initialIndex, y: 0 }) const touching = useRef(false) const scrolling = useRef(false) + const timerResetPosition = useRef(null) + const timerScrollTo = useRef(null) const activeIndex = useRef(initialIndex) const prevIndex = usePrevious(initialIndex) const prevMaxIndex = usePrevious(maxIndex) - const initialOffset = useMemo(() => ({ - x: 0, - y: itemRawH * initialIndex - }), [itemRawH]) + const { + layoutProps + } = useLayout({ + props, + hasSelfPercent, + setWidth, + setHeight, + nodeRef: scrollViewRef + }) + + const paddingHeight = useMemo( + () => Math.round((pickerH - itemHeight) / 2), + [pickerH, itemHeight] + ) const snapToOffsets = useMemo( - () => columnData.map((_, i) => i * itemRawH), - [columnData, itemRawH] + () => Array.from({ length: maxIndex + 1 }, (_, i) => i * itemRawH), + [maxIndex, itemRawH] ) const contentContainerStyle = useMemo(() => { - return [ - { - paddingVertical: Math.round(pickerH - itemRawH) / 2 - } - ] - }, [pickerH, itemRawH]) + return [{ paddingVertical: paddingHeight }] + }, [paddingHeight]) + + const getIndex = useCallback((y: number) => { + const calc = Math.round(y / itemRawH) + return Math.max(0, Math.min(calc, maxIndex)) + }, [itemRawH, maxIndex]) + + const clearTimerResetPosition = useCallback(() => { + if (timerResetPosition.current) { + clearTimeout(timerResetPosition.current) + timerResetPosition.current = null + } + }, []) + + const clearTimerScrollTo = useCallback(() => { + if (timerScrollTo.current) { + clearTimeout(timerScrollTo.current) + timerScrollTo.current = null + } + }, []) + + useEffect(() => { + return () => { + clearTimerResetPosition() + clearTimerScrollTo() + } + }, []) useEffect(() => { if ( @@ -102,188 +133,180 @@ const _PickerViewColumn = forwardRef, ) { return } - + clearTimerScrollTo() + timerScrollTo.current = setTimeout(() => { + scrollViewRef.current?.scrollTo({ + x: 0, + y: initialIndex * itemRawH, + animated: false + }) + }, isAndroid ? 200 : 0) activeIndex.current = initialIndex - scrollViewRef.current.scrollTo({ - x: 0, - y: itemRawH * initialIndex, - animated: false - }) - }, [itemRawH, initialIndex]) - - const onScrollViewLayout = () => { - getInnerLayout && getInnerLayout(layoutRef) - } - - const { - layoutRef, - layoutProps - } = useLayout({ - props, - hasSelfPercent, - setWidth, - setHeight, - nodeRef: scrollViewRef, - onLayout: onScrollViewLayout - }) + }, [itemRawH, maxIndex, initialIndex]) - const onContentSizeChange = (w: number, h: number) => { - scrollViewRef.current?.scrollTo({ - x: 0, - y: itemRawH * initialIndex, - animated: false - }) - } + const onContentSizeChange = useCallback((_w: number, h: number) => { + const y = initialIndex * itemRawH + if (y <= h) { + clearTimerScrollTo() + timerScrollTo.current = setTimeout(() => { + scrollViewRef.current?.scrollTo({ x: 0, y, animated: false }) + }, 0) + } + }, [itemRawH, initialIndex]) - const onItemLayout = (e: LayoutChangeEvent) => { + const onItemLayout = useCallback((e: LayoutChangeEvent) => { const { height: rawH } = e.nativeEvent.layout - if (rawH && itemRawH !== rawH) { - setItemRawH(rawH) - onColumnItemRawHChange(rawH) + const roundedH = Math.round(rawH) + if (roundedH && roundedH !== itemRawH) { + setItemRawH(roundedH) } - } - - const onTouchStart = () => { - touching.current = true - } - - const onTouchEnd = () => { - touching.current = false - } + }, [itemRawH]) - const onTouchCancel = () => { - touching.current = false - } + const resetScrollPosition = useCallback((y: number) => { + if (touching.current || scrolling.current) { + return + } + scrolling.current = true + const targetIndex = getIndex(y) + scrollViewRef.current?.scrollTo({ x: 0, y: targetIndex * itemRawH, animated: false }) + }, [itemRawH, getIndex]) - const onMomentumScrollBegin = () => { + const onMomentumScrollBegin = useCallback(() => { + isIOS && clearTimerResetPosition() scrolling.current = true - } + }, []) - const onMomentumScrollEnd = (e: NativeSyntheticEvent) => { + const onMomentumScrollEnd = useCallback((e: NativeSyntheticEvent | { nativeEvent: { contentOffset: { y: number } } }) => { scrolling.current = false - if (!itemRawH) { - return - } const { y: scrollY } = e.nativeEvent.contentOffset - let calcIndex = Math.round(scrollY / itemRawH) - activeIndex.current = calcIndex - if (calcIndex !== initialIndex) { - calcIndex = Math.max(0, Math.min(calcIndex, maxIndex)) || 0 + if (isIOS && scrollY % itemRawH !== 0) { + return resetScrollPosition(scrollY) + } + const calcIndex = getIndex(scrollY) + if (calcIndex !== activeIndex.current) { + activeIndex.current = calcIndex onSelectChange(calcIndex) } - } - - const offsetY = useRef(new Animated.Value(0)).current + }, [itemRawH, getIndex, onSelectChange, resetScrollPosition]) - const onScroll = useMemo( - () => - Animated.event([{ nativeEvent: { contentOffset: { y: offsetY } } }], { - useNativeDriver: true - }), - [offsetY] - ) + const onScrollBeginDrag = useCallback(() => { + isIOS && clearTimerResetPosition() + touching.current = true + prevScrollingInfo.current = { + index: activeIndex.current, + y: activeIndex.current * itemRawH + } + }, [itemRawH]) - const faces = useMemo(() => createFaces(itemRawH, visibleCount), [itemRawH]) + const onScrollEndDrag = useCallback((e: NativeSyntheticEvent) => { + touching.current = false + if (isIOS) { + const { y } = e.nativeEvent.contentOffset + if (y % itemRawH === 0) { + onMomentumScrollEnd({ nativeEvent: { contentOffset: { y } } }) + } else if (y > 0 && y < snapToOffsets[maxIndex]) { + timerResetPosition.current = setTimeout(() => { + resetScrollPosition(y) + }, 10) + } + } + }, [itemRawH, maxIndex, snapToOffsets, onMomentumScrollEnd, resetScrollPosition]) - const getTransform = useCallback( - (index: number) => { - const inputRange = faces.map((f) => itemRawH * (index + f.index)) - return { - opacity: offsetY.interpolate({ - inputRange: inputRange, - outputRange: faces.map((x) => x.opacity), - extrapolate: 'clamp' - }), - rotateX: offsetY.interpolate({ - inputRange: inputRange, - outputRange: faces.map((x) => `${x.deg}deg`), - extrapolate: 'extend' - }), - translateY: offsetY.interpolate({ - inputRange: inputRange, - outputRange: faces.map((x) => x.offsetY), - extrapolate: 'extend' - }) + const onScroll = useCallback((e: NativeSyntheticEvent) => { + // 全局注册的振动触感 hook + const pickerVibrate = global.__mpx?.config?.rnConfig?.pickerVibrate + if (typeof pickerVibrate !== 'function') { + return + } + const { y } = e.nativeEvent.contentOffset + const { index: prevIndex, y: _y } = prevScrollingInfo.current + if (touching.current || scrolling.current) { + if (Math.abs(y - _y) >= itemRawH) { + const currentId = getIndex(y) + if (currentId !== prevIndex) { + prevScrollingInfo.current = { + index: currentId, + y: currentId * itemRawH + } + // vibrateShort({ type: 'selection' }) + pickerVibrate() + } } - }, - [offsetY, faces, itemRawH] - ) + } + }, [itemRawH, getIndex]) const renderInnerchild = () => - columnData.map((item: React.ReactNode, index: number) => { - const InnerProps = index === 0 ? { onLayout: onItemLayout } : {} - const strKey = `picker-column-${columnIndex}-${index}` - const { opacity, rotateX, translateY } = getTransform(index) + columnData.map((item: React.ReactElement, index: number) => { return ( - - {wrapChildren( - { children: item }, - { - hasVarDec, - varContext: varContextRef.current, - textStyle, - textProps - } - )} - + ) }) const renderScollView = () => { return ( - - {renderInnerchild()} - + + + {renderInnerchild()} + + ) } - const renderOverlay = () => ( - + const renderIndicator = () => ( + + ) + + const renderMask = () => ( + ) return ( - + {renderScollView()} - {renderOverlay()} - + {renderMask()} + {renderIndicator()} + ) }) +const styles = StyleSheet.create({ + wrapper: { display: 'flex', flex: 1 } +}) + _PickerViewColumn.displayName = 'MpxPickerViewColumn' export default _PickerViewColumn diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view.tsx index 282bf1a394..3ef2249c6a 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-picker-view.tsx @@ -1,5 +1,5 @@ import { View } from 'react-native' -import React, { forwardRef, useState, useRef } from 'react' +import React, { forwardRef, useRef } from 'react' import useInnerProps, { getCustomEvent } from './getInnerListeners' import useNodesRef, { HandlerRef } from './useNodesRef' import { @@ -7,35 +7,33 @@ import { splitProps, splitStyle, wrapChildren, - parseInlineStyle, useTransformStyle, - useDebounceCallback, - useStableCallback, extendObject } from './utils' +import { PickerViewStyleContext } from './pickerVIewContext' import type { AnyFunc } from './types/common' /** * ✔ value * ✔ bindchange * ✘ bindpickstart * ✘ bindpickend - * ✘ mask-class + * ✔ mask-class * ✔ indicator-style: 优先级indicator-style.height > pick-view-column中的子元素设置的height - * ✘ indicator-class - * ✘ mask-style + * WebView Only: + * ✔ indicator-class + * ✔ mask-style * ✘ immediate-change */ interface PickerViewProps { children: React.ReactNode - // 初始的defaultValue数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项（下标从 0 开始）， - // 数字大于 picker-view-column 可选项长度时，选择最后一项。 value?: Array bindchange?: AnyFunc style: { [key: string]: any } - 'indicator-style'?: string + 'indicator-style'?: Record, + 'mask-style'?: Record, 'enable-var': boolean 'external-var-context'?: Record, 'enable-offset': boolean @@ -62,25 +60,25 @@ const styles: { [key: string]: Object } = { } } +const DefaultPickerItemH = 36 + const _PickerView = forwardRef, PickerViewProps>((props: PickerViewProps, ref) => { const { children, value = [], bindchange, style, + 'indicator-style': indicatorStyle = {}, + 'mask-style': pickerMaskStyle = {}, 'enable-var': enableVar, 'external-var-context': externalVarContext } = props - - // indicatorStyle 需要转换为rn的style - // 微信设置到pick-view上上设置的normalStyle如border等需要转换成RN的style然后进行透传 - const indicatorStyle = parseInlineStyle(props['indicator-style']) - const { height: indicatorH, ...pickerOverlayStyle } = indicatorStyle - const [pickMaxH, setPickMaxH] = useState(0) + const { height: indicatorH, ...pickerIndicatorStyle } = indicatorStyle const nodeRef = useRef(null) const cloneRef = useRef(null) const activeValueRef = useRef(value) activeValueRef.current = value.slice() + const snapActiveValueRef = useRef(null) const { normalStyle, @@ -96,7 +94,6 @@ const _PickerView = forwardRef, PickerViewProp }) const { - // 存储layout布局信息 layoutRef, layoutProps, layoutStyle @@ -104,33 +101,32 @@ const _PickerView = forwardRef, PickerViewProp const { textProps } = splitProps(props) const { textStyle } = splitStyle(normalStyle) - const onColumnItemRawHChange = (height: number) => { - if (height > pickMaxH) { - setPickMaxH(height) - } - } - - const bindchangeDebounce = useDebounceCallback(useStableCallback(bindchange), 300) - const onSelectChange = (columnIndex: number, selectedIndex: number) => { - bindchangeDebounce.clear() const activeValue = activeValueRef.current activeValue[columnIndex] = selectedIndex const eventData = getCustomEvent( 'change', {}, - { detail: { value: activeValue, source: 'change' }, layoutRef } + { detail: { value: activeValue.slice(), source: 'change' }, layoutRef } ) - bindchangeDebounce(eventData) + bindchange?.(eventData) + snapActiveValueRef.current = activeValueRef.current } - const onInitialChange = (value: number[]) => { - const eventData = getCustomEvent( - 'change', - {}, - { detail: { value, source: 'change' }, layoutRef } - ) - bindchange?.(eventData) // immediate + const hasDiff = (a: number[] = [], b: number[]) => { + return a.some((v, i) => v !== b[i]) + } + + const onInitialChange = (isInvalid: boolean, value: number[]) => { + if (isInvalid || !snapActiveValueRef.current || hasDiff(snapActiveValueRef.current, value)) { + const eventData = getCustomEvent( + 'change', + {}, + { detail: { value: value.slice(), source: 'change' }, layoutRef } + ) + bindchange?.(eventData) + snapActiveValueRef.current = value.slice() + } } const innerProps = useInnerProps( @@ -148,12 +144,17 @@ const _PickerView = forwardRef, PickerViewProp ), layoutProps }), - ['enable-offset'], + [ + 'enable-offset', + 'indicator-style', + 'indicator-class', + 'mask-style', + 'mask-class' + ], { layoutRef } ) const renderColumn = (child: React.ReactElement, index: number, columnData: React.ReactNode[], initialIndex: number) => { - const extraProps = {} const childProps = child?.props || {} const wrappedProps = extendObject( {}, @@ -164,15 +165,14 @@ const _PickerView = forwardRef, PickerViewProp columnIndex: index, key: `pick-view-${index}`, wrapperStyle: { - height: normalStyle?.height || 0, - itemHeight: indicatorH || 0 + height: normalStyle?.height || DefaultPickerItemH, + itemHeight: indicatorH || DefaultPickerItemH }, - onColumnItemRawHChange, onSelectChange: onSelectChange.bind(null, index), initialIndex, - pickerOverlayStyle - }, - extraProps + pickerIndicatorStyle, + pickerMaskStyle + } ) const realElement = React.cloneElement(child, wrappedProps) return wrapChildren( @@ -215,17 +215,18 @@ const _PickerView = forwardRef, PickerViewProp validValue.push(validIndex) renderColumns.push(renderColumn(item, index, columnData, validIndex)) }) - isInvalid && onInitialChange(validValue) + onInitialChange(isInvalid, validValue) return renderColumns } return ( - - {renderPickerColumns()} - + + + {renderPickerColumns()} + + ) }) _PickerView.displayName = 'MpxPickerView' - export default _PickerView diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-rich-text/index.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-rich-text/index.tsx index db6097df5d..7e43b48c4b 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-rich-text/index.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-rich-text/index.tsx @@ -3,10 +3,10 @@ * ✔ nodes */ import { View, ViewProps, ViewStyle } from 'react-native' -import { useRef, forwardRef, JSX, useState } from 'react' +import { useRef, forwardRef, JSX, useState, createElement } from 'react' import useInnerProps from '../getInnerListeners' import useNodesRef, { HandlerRef } from '../useNodesRef' // 引入辅助函数 -import { useTransformStyle, useLayout } from '../utils' +import { useTransformStyle, useLayout, extendObject } from '../utils' import { WebView, WebViewMessageEvent } from 'react-native-webview' import { generateHTML } from './html' @@ -91,28 +91,22 @@ const _RichText = forwardRef, _RichTextProps>(( layoutRef }) - const innerProps = useInnerProps(props, { + const innerProps = useInnerProps(props, extendObject({ ref: nodeRef, - style: { ...normalStyle, ...layoutStyle }, - ...layoutProps - }, [], { + style: extendObject(normalStyle, layoutStyle) + }, layoutProps), [], { layoutRef }) const html: string = typeof nodes === 'string' ? nodes : jsonToHtmlStr(nodes) - return ( - - { - setWebViewHeight(+event.nativeEvent.data) - }} - > - - + return createElement(View, innerProps, + createElement(WebView, { + source: { html: generateHTML(html) }, + onMessage: (event: WebViewMessageEvent) => { + setWebViewHeight(+event.nativeEvent.data) + } + }) ) }) diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-scroll-view.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-scroll-view.tsx index b058e622dc..6a7ab2e997 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-scroll-view.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-scroll-view.tsx @@ -33,13 +33,13 @@ */ import { ScrollView } from 'react-native-gesture-handler' import { View, RefreshControl, NativeSyntheticEvent, NativeScrollEvent, LayoutChangeEvent, ViewStyle } from 'react-native' -import { JSX, ReactNode, RefObject, useRef, useState, useEffect, forwardRef, useContext, createElement } from 'react' +import { JSX, ReactNode, RefObject, useRef, useState, useEffect, forwardRef, useContext, createElement, useMemo } from 'react' import { useAnimatedRef } from 'react-native-reanimated' import { warn } from '@mpxjs/utils' import useInnerProps, { getCustomEvent } from './getInnerListeners' import useNodesRef, { HandlerRef } from './useNodesRef' import { splitProps, splitStyle, useTransformStyle, useLayout, wrapChildren, extendObject, flatGesture, GestureHandler } from './utils' -import { IntersectionObserverContext } from './context' +import { IntersectionObserverContext, ScrollViewContext } from './context' interface ScrollViewProps { children?: ReactNode; @@ -194,6 +194,12 @@ const _ScrollView = forwardRef, S gestureRef: scrollViewRef }) + const contextValue = useMemo(() => { + return { + gestureRef: scrollViewRef + } + }, []) + const { layoutRef, layoutStyle, layoutProps } = useLayout({ props, hasSelfPercent, setWidth, setHeight, nodeRef: scrollViewRef, onLayout }) if (scrollX && scrollY) { @@ -332,6 +338,8 @@ const _ScrollView = forwardRef, S }, props) ) updateScrollOptions(e, { scrollLeft, scrollTop }) + onStartReached(e) + onEndReached(e) if (enableTriggerIntersectionObserver && intersectionObservers) { for (const key in intersectionObservers) { intersectionObservers[key].throttleMeasure() @@ -507,14 +515,17 @@ const _ScrollView = forwardRef, S }, (refresherDefaultStyle && refresherDefaultStyle !== 'none' ? { colors: refreshColor[refresherDefaultStyle] } : null))) : undefined }), - wrapChildren( - props, - { - hasVarDec, - varContext: varContextRef.current, - textStyle, - textProps - } + createElement(ScrollViewContext.Provider, + { value: contextValue }, + wrapChildren( + props, + { + hasVarDec, + varContext: varContextRef.current, + textStyle, + textProps + } + ) ) ) }) diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper-item.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper-item.tsx index 2c9771f001..161e3307ff 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper-item.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper-item.tsx @@ -1,8 +1,10 @@ -import { View, LayoutChangeEvent } from 'react-native' -import { ReactNode, forwardRef, useRef } from 'react' +import { View } from 'react-native' +import Animated, { useAnimatedStyle, interpolate, SharedValue } from 'react-native-reanimated' +import { ReactNode, forwardRef, useRef, useContext } from 'react' import useInnerProps from './getInnerListeners' import useNodesRef, { HandlerRef } from './useNodesRef' // 引入辅助函数 import { useTransformStyle, splitStyle, splitProps, wrapChildren, useLayout } from './utils' +import { SwiperContext } from './context' interface SwiperItemProps { 'item-id'?: string; @@ -14,15 +16,31 @@ interface SwiperItemProps { 'parent-height'?: number; children?: ReactNode; style?: Object; + customStyle: Object; + itemIndex: number; +} + +interface ContextType { + offset: SharedValue; + step: SharedValue; + scale: boolean; + dir: string; } const _SwiperItem = forwardRef, SwiperItemProps>((props: SwiperItemProps, ref) => { const { 'enable-var': enableVar, 'external-var-context': externalVarContext, - style + style, + customStyle, + itemIndex } = props + const contextValue = useContext(SwiperContext) as ContextType + const offset = contextValue.offset || 0 + const step = contextValue.step || 0 + const scale = contextValue.scale || false + const dir = contextValue.dir || 'x' const { textProps } = splitProps(props) const nodeRef = useRef(null) @@ -47,19 +65,35 @@ const _SwiperItem = forwardRef, SwiperItemProp } = useLayout({ props, hasSelfPercent, setWidth, setHeight, nodeRef: nodeRef }) const innerProps = useInnerProps(props, { - style: { ...innerStyle, ...layoutStyle }, ref: nodeRef, ...layoutProps }, [ 'children', - 'enable-offset' + 'enable-offset', + 'style' ], { layoutRef }) - + const itemAnimatedStyle = useAnimatedStyle(() => { + if (!step.value) return {} + const inputRange = [step.value, 0] + const outputRange = [0.7, 1] + // 实现元素的宽度跟随step从0到真实宽度，且不能触发重新渲染整个组件，通过AnimatedStyle的方式实现 + const outerLayoutStyle = dir === 'x' ? { width: step.value, height: '100%' } : { width: '100%', height: step.value } + const transformStyle = [] + if (scale) { + transformStyle.push({ + scale: interpolate(Math.abs(Math.abs(offset.value) - itemIndex * step.value), inputRange, outputRange) + }) + } + return Object.assign(outerLayoutStyle, { + transform: transformStyle + }) + }) return ( - - { + + { wrapChildren( props, { @@ -70,7 +104,7 @@ const _SwiperItem = forwardRef, SwiperItemProp } ) } - + ) }) diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper.tsx new file mode 100644 index 0000000000..081a2734da --- /dev/null +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper.tsx @@ -0,0 +1,742 @@ +import { View, NativeSyntheticEvent, LayoutChangeEvent } from 'react-native' +import { GestureDetector, Gesture } from 'react-native-gesture-handler' +import Animated, { useAnimatedStyle, useSharedValue, withTiming, Easing, runOnJS, useAnimatedReaction, cancelAnimation } from 'react-native-reanimated' + +import React, { JSX, forwardRef, useRef, useEffect, ReactNode, ReactElement, useMemo } from 'react' +import useInnerProps, { getCustomEvent } from './getInnerListeners' +import useNodesRef, { HandlerRef } from './useNodesRef' // 引入辅助函数 +import { useTransformStyle, splitStyle, splitProps, useLayout, wrapChildren } from './utils' +import { SwiperContext } from './context' +/** + * ✔ indicator-dots + * ✔ indicator-color + * ✔ indicator-active-color + * ✔ autoplay + * ✔ current + * ✔ interval + * ✔ duration + * ✔ circular + * ✔ vertical + * ✔ previous-margin + * ✔ next-margin + * ✔ easing-function ="easeOutCubic" + * ✘ display-multiple-items + * ✘ snap-to-edge + */ +type EaseType = 'default' | 'linear' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' +type StrAbsoType = 'absoluteX' | 'absoluteY' +type EventDataType = { + translation: number +} + +interface SwiperProps { + children?: ReactNode; + circular?: boolean; + current?: number; + interval?: number; + autoplay?: boolean; + // scrollView 只有安卓可以设 + duration?: number; + // 滑动过程中元素是否scale变化 + scale?: boolean; + 'indicator-dots'?: boolean; + 'indicator-color'?: string; + 'indicator-active-color'?: string; + vertical?: boolean; + style: { + [key: string]: any + }; + 'easing-function'?: EaseType; + 'previous-margin'?: string; + 'next-margin'?: string; + 'enable-offset'?: boolean; + 'enable-var': boolean; + 'parent-font-size'?: number; + 'parent-width'?: number; + 'parent-height'?: number; + 'external-var-context'?: Record; + bindchange?: (event: NativeSyntheticEvent | unknown) => void; +} + +/** + * 默认的Style类型 + */ +const styles: { [key: string]: Object } = { + pagination_x: { + position: 'absolute', + bottom: 25, + left: 0, + right: 0, + flexDirection: 'row', + flex: 1, + justifyContent: 'center', + alignItems: 'center' + }, + pagination_y: { + position: 'absolute', + right: 15, + top: 0, + bottom: 0, + flexDirection: 'column', + flex: 1, + justifyContent: 'center', + alignItems: 'center' + }, + pagerWrapperx: { + position: 'absolute', + flexDirection: 'row', + justifyContent: 'center', + alignItems: 'center' + }, + pagerWrappery: { + position: 'absolute', + flexDirection: 'column', + justifyContent: 'center', + alignItems: 'center' + }, + swiper: { + overflow: 'scroll', + display: 'flex', + justifyContent: 'flex-start' + } +} + +const dotCommonStyle = { + width: 8, + height: 8, + borderRadius: 4, + marginLeft: 3, + marginRight: 3, + marginTop: 3, + marginBottom: 3, + zIndex: 98 +} +const activeDotStyle = { + zIndex: 99 +} +const longPressRatio = 100 + +const easeMap = { + default: Easing.linear, + linear: Easing.linear, + easeInCubic: Easing.in(Easing.cubic), + easeOutCubic: Easing.out(Easing.cubic), + easeInOutCubic: Easing.inOut(Easing.cubic) +} + +const SwiperWrapper = forwardRef, SwiperProps>((props: SwiperProps, ref): JSX.Element => { + const { + 'indicator-dots': showsPagination, + 'indicator-color': dotColor = 'rgba(0, 0, 0, .3)', + 'indicator-active-color': activeDotColor = '#000000', + 'enable-var': enableVar = false, + 'parent-font-size': parentFontSize, + 'parent-width': parentWidth, + 'parent-height': parentHeight, + 'external-var-context': externalVarContext, + style = {}, + autoplay = false, + circular = false + } = props + const easeingFunc = props['easing-function'] || 'default' + const easeDuration = props.duration || 500 + const horizontal = props.vertical !== undefined ? !props.vertical : true + const nodeRef = useRef(null) + useNodesRef(props, ref, nodeRef, {}) + // 计算transfrom之类的 + const { + normalStyle, + hasVarDec, + varContextRef, + hasSelfPercent, + setWidth, + setHeight + } = useTransformStyle(style, { + enableVar, + externalVarContext, + parentFontSize, + parentWidth, + parentHeight + }) + const { textStyle } = splitStyle(normalStyle) + const { textProps } = splitProps(props) + const preMargin = props['previous-margin'] ? global.__formatValue(props['previous-margin']) as number : 0 + const nextMargin = props['next-margin'] ? global.__formatValue(props['next-margin']) as number : 0 + const preMarginShared = useSharedValue(preMargin) + const nextMarginShared = useSharedValue(nextMargin) + const autoplayShared = useSharedValue(autoplay) + // 默认前后补位的元素个数 + const patchElmNum = circular ? (preMargin ? 2 : 1) : 0 + const patchElmNumShared = useSharedValue(patchElmNum) + const circularShared = useSharedValue(circular) + const children = Array.isArray(props.children) ? props.children.filter(child => child) : (props.children ? [props.children] : []) + // 对有变化的变量，在worklet中只能使用sharedValue变量，useRef不能更新 + const childrenLength = useSharedValue(children.length) + const initWidth = typeof normalStyle?.width === 'number' ? normalStyle.width - preMargin - nextMargin : normalStyle.width + const initHeight = typeof normalStyle?.height === 'number' ? normalStyle.height - preMargin - nextMargin : normalStyle.height + const dir = horizontal === false ? 'y' : 'x' + const pstep = dir === 'x' ? initWidth : initHeight + const initStep: number = isNaN(pstep) ? 0 : pstep + // 每个元素的宽度 or 高度，有固定值直接初始化无则0 + const step = useSharedValue(initStep) + // 记录选中元素的索引值 + const currentIndex = useSharedValue(props.current || 0) + // const initOffset = getOffset(props.current || 0, initStep) + // 记录元素的偏移量 + const offset = useSharedValue(getOffset(props.current || 0, initStep)) + const strAbso = 'absolute' + dir.toUpperCase() as StrAbsoType + // 标识手指触摸和抬起, 起点在onBegin + const touchfinish = useSharedValue(true) + // 记录上一帧的绝对定位坐标 + const preAbsolutePos = useSharedValue(0) + // 记录从onBegin 到 onTouchesUp 时移动的距离 + const moveTranstion = useSharedValue(0) + // 记录从onBegin 到 onTouchesUp 的时间 + const moveTime = useSharedValue(0) + const timerId = useRef(0 as number | ReturnType) + const intervalTimer = props.interval || 500 + const { + // 存储layout布局信息 + layoutRef, + layoutProps, + layoutStyle + } = useLayout({ props, hasSelfPercent, setWidth, setHeight, nodeRef, onLayout: onWrapperLayout }) + const innerProps = useInnerProps(props, { + ref: nodeRef + }, [ + 'style', + 'indicator-dots', + 'indicator-color', + 'indicator-active-color', + 'previous-margin', + 'vertical', + 'previous-margin', + 'next-margin', + 'easing-function', + 'autoplay', + 'circular', + 'interval', + 'easing-function' + ], { layoutRef: layoutRef }) + + function onWrapperLayout (e: LayoutChangeEvent) { + const { width, height } = e.nativeEvent.layout + const realWidth = dir === 'x' ? width - preMargin - nextMargin : width + const realHeight = dir === 'y' ? height - preMargin - nextMargin : height + const iStep = dir === 'x' ? realWidth : realHeight + if (iStep !== step.value) { + step.value = iStep + updateCurrent(props.current || 0, iStep) + updateAutoplay() + } + } + + const dotAnimatedStyle = useAnimatedStyle(() => { + if (!step.value) return {} + const dotStep = dotCommonStyle.width + dotCommonStyle.marginRight + dotCommonStyle.marginLeft + if (dir === 'x') { + return { transform: [{ translateX: currentIndex.value * dotStep }] } + } else { + return { transform: [{ translateY: currentIndex.value * dotStep }] } + } + }) + + function renderPagination () { + if (children.length <= 1) return null + const activeColor = activeDotColor || '#007aff' + const unActionColor = dotColor || 'rgba(0,0,0,.2)' + // 正常渲染所有dots + const dots: Array = [] + for (let i = 0; i < children.length; i++) { + dots.push() + } + return ( + + + + {dots} + + ) + } + + function renderItems () { + const intLen = children.length + let renderChild = children.slice() + if (circular && intLen > 1) { + // 最前面加最后一个元素 + const lastChild = React.cloneElement(children[intLen - 1] as ReactElement, { key: 'clone0' }) + // 最后面加第一个元素 + const firstChild = React.cloneElement(children[0] as ReactElement, { key: 'clone1' }) + if (preMargin) { + const lastChild1 = React.cloneElement(children[intLen - 2] as ReactElement, { key: 'clone2' }) + const firstChild1 = React.cloneElement(children[1] as ReactElement, { key: 'clone3' }) + renderChild = [lastChild1, lastChild].concat(renderChild).concat([firstChild, firstChild1]) + } else { + renderChild = [lastChild].concat(renderChild).concat([firstChild]) + } + } + const arrChildren = renderChild.map((child, index) => { + const extraStyle = {} as { [key: string]: any } + if (index === 0 && !circular) { + preMargin && dir === 'x' && (extraStyle.marginLeft = preMargin) + preMargin && dir === 'y' && (extraStyle.marginTop = preMargin) + } + if (index === intLen - 1 && !circular) { + nextMargin && dir === 'x' && (extraStyle.marginRight = nextMargin) + nextMargin && dir === 'y' && (extraStyle.marginBottom = nextMargin) + } + // 业务swiper-item自己生成key，内部添加的元素自定义key + const newChild = React.cloneElement(child, { + itemIndex: index, + customStyle: extraStyle + }) + return newChild + }) + const contextValue = { + offset, + step, + scale: props.scale, + dir + } + return ({arrChildren}) + } + + const { loop, pauseLoop, resumeLoop } = useMemo(() => { + function createAutoPlay () { + if (!step.value) return + let targetOffset = 0 + let nextIndex = currentIndex.value + if (!circularShared.value) { + // 获取下一个位置的坐标, 循环到最后一个元素,直接停止, 取消定时器 + if (currentIndex.value === childrenLength.value - 1) { + pauseLoop() + return + } + nextIndex += 1 + // targetOffset = -nextIndex * step.value - preMarginShared.value + targetOffset = -nextIndex * step.value + offset.value = withTiming(targetOffset, { + duration: easeDuration, + easing: easeMap[easeingFunc] + }, () => { + currentIndex.value = nextIndex + runOnJS(loop)() + }) + } else { + // 默认向右, 向下 + if (nextIndex === childrenLength.value - 1) { + nextIndex = 0 + targetOffset = -(childrenLength.value + patchElmNumShared.value) * step.value + preMarginShared.value + // 执行动画到下一帧 + offset.value = withTiming(targetOffset, { + duration: easeDuration + }, () => { + const initOffset = -step.value * patchElmNumShared.value + preMarginShared.value + // 将开始位置设置为真正的位置 + offset.value = initOffset + currentIndex.value = nextIndex + runOnJS(loop)() + }) + } else { + nextIndex = currentIndex.value + 1 + targetOffset = -(nextIndex + patchElmNumShared.value) * step.value + preMarginShared.value + // 执行动画到下一帧 + offset.value = withTiming(targetOffset, { + duration: easeDuration, + easing: easeMap[easeingFunc] + }, () => { + currentIndex.value = nextIndex + runOnJS(loop)() + }) + } + } + } + + // loop在JS线程中调用，createAutoPlay + useEffect中 + function loop () { + timerId.current && clearTimeout(timerId.current) + timerId.current = setTimeout(createAutoPlay, intervalTimer) + } + + function pauseLoop () { + timerId.current && clearTimeout(timerId.current) + } + // resumeLoop在worklet中调用 + function resumeLoop () { + if (autoplayShared.value && childrenLength.value > 1) { + loop() + } + } + return { + loop, + pauseLoop, + resumeLoop + } + }, []) + + function handleSwiperChange (current: number) { + if (props.current !== currentIndex.value) { + const eventData = getCustomEvent('change', {}, { detail: { current, source: 'touch' }, layoutRef: layoutRef }) + props.bindchange && props.bindchange(eventData) + } + } + + function getOffset (index:number, stepValue: number) { + if (!stepValue) return 0 + let targetOffset = 0 + if (circular && children.length > 1) { + const targetIndex = index + patchElmNum + targetOffset = -(stepValue * targetIndex - preMargin) + } else { + targetOffset = -index * stepValue + } + return targetOffset + } + + function updateCurrent (index:number, stepValue: number) { + const targetOffset = getOffset(index || 0, stepValue) + if (targetOffset !== offset.value) { + // 内部基于props.current!==currentIndex.value决定是否使用动画及更新currentIndex.value + if (props.current !== undefined && props.current !== currentIndex.value) { + offset.value = withTiming(targetOffset, { + duration: easeDuration, + easing: easeMap[easeingFunc] + }, () => { + currentIndex.value = props.current || 0 + }) + } else { + offset.value = targetOffset + } + } + } + function updateAutoplay () { + if (autoplay && children.length > 1) { + loop() + } else { + pauseLoop() + } + } + // 1. 用户在当前页切换选中项，动画；用户携带选中index打开到swiper页直接选中不走动画 + useAnimatedReaction(() => currentIndex.value, (newIndex: number, preIndex: number) => { + // 这里必须传递函数名, 直接写()=> {}形式会报 访问了未sharedValue信息 + if (newIndex !== preIndex && props.bindchange) { + runOnJS(handleSwiperChange)(newIndex) + } + }) + + useEffect(() => { + let patchStep = 0 + if (preMargin !== preMarginShared.value) { + patchStep += preMargin - preMarginShared.value + } + if (nextMargin !== nextMarginShared.value) { + patchStep += nextMargin - nextMarginShared.value + } + preMarginShared.value = preMargin + nextMarginShared.value = nextMargin + const newStep = step.value - patchStep + if (step.value !== newStep) { + step.value = newStep + offset.value = getOffset(currentIndex.value, newStep) + } + }, [preMargin, nextMargin]) + + useEffect(() => { + childrenLength.value = children.length + if (children.length - 1 < currentIndex.value) { + pauseLoop() + currentIndex.value = 0 + offset.value = getOffset(0, step.value) + if (autoplay && children.length > 1) { + loop() + } + } + }, [children.length]) + + useEffect(() => { + updateCurrent(props.current || 0, step.value) + }, [props.current]) + + useEffect(() => { + autoplayShared.value = autoplay + updateAutoplay() + return () => { + if (autoplay) { + pauseLoop() + } + } + }, [autoplay]) + + useEffect(() => { + if (circular !== circularShared.value) { + circularShared.value = circular + patchElmNumShared.value = circular ? (preMargin ? 2 : 1) : 0 + offset.value = getOffset(currentIndex.value, step.value) + } + }, [circular, preMargin]) + + const { gestureHandler } = useMemo(() => { + function getTargetPosition (eventData: EventDataType) { + 'worklet' + // 移动的距离 + const { translation } = eventData + let resetOffsetPos = 0 + let selectedIndex = currentIndex.value + // 是否临界点 + let isCriticalItem = false + // 真实滚动到的偏移量坐标 + let moveToTargetPos = 0 + const currentOffset = translation < 0 ? offset.value - preMarginShared.value : offset.value + preMarginShared.value + const computedIndex = Math.abs(currentOffset) / step.value + const moveToIndex = translation < 0 ? Math.ceil(computedIndex) : Math.floor(computedIndex) + // 实际应该定位的索引值 + if (!circularShared.value) { + selectedIndex = moveToIndex + moveToTargetPos = selectedIndex * step.value + } else { + if (moveToIndex >= childrenLength.value + patchElmNumShared.value) { + selectedIndex = moveToIndex - (childrenLength.value + patchElmNumShared.value) + resetOffsetPos = (selectedIndex + patchElmNumShared.value) * step.value - preMarginShared.value + moveToTargetPos = moveToIndex * step.value - preMarginShared.value + isCriticalItem = true + } else if (moveToIndex <= patchElmNumShared.value - 1) { + selectedIndex = moveToIndex === 0 ? childrenLength.value - patchElmNumShared.value : childrenLength.value - 1 + resetOffsetPos = (selectedIndex + patchElmNumShared.value) * step.value - preMarginShared.value + moveToTargetPos = moveToIndex * step.value - preMarginShared.value + isCriticalItem = true + } else { + selectedIndex = moveToIndex - patchElmNumShared.value + moveToTargetPos = moveToIndex * step.value - preMarginShared.value + } + } + return { + selectedIndex, + isCriticalItem, + resetOffset: -resetOffsetPos, + targetOffset: -moveToTargetPos + } + } + function canMove (eventData: EventDataType) { + 'worklet' + const { translation } = eventData + const currentOffset = Math.abs(offset.value) + if (!circularShared.value) { + if (translation < 0) { + return currentOffset < step.value * (childrenLength.value - 1) + } else { + return currentOffset > 0 + } + } else { + return true + } + } + function handleEnd (eventData: EventDataType) { + 'worklet' + const { isCriticalItem, targetOffset, resetOffset, selectedIndex } = getTargetPosition(eventData) + if (isCriticalItem) { + offset.value = withTiming(targetOffset, { + duration: easeDuration, + easing: easeMap[easeingFunc] + }, () => { + if (touchfinish.value !== false) { + currentIndex.value = selectedIndex + offset.value = resetOffset + runOnJS(resumeLoop)() + } + }) + } else { + offset.value = withTiming(targetOffset, { + duration: easeDuration, + easing: easeMap[easeingFunc] + }, () => { + if (touchfinish.value !== false) { + currentIndex.value = selectedIndex + runOnJS(resumeLoop)() + } + }) + } + } + function handleBack (eventData: EventDataType) { + 'worklet' + const { translation } = eventData + // 向右滑动的back:trans < 0， 向左滑动的back: trans < 0 + let currentOffset = Math.abs(offset.value) + if (circularShared.value) { + currentOffset += translation < 0 ? preMarginShared.value : -preMarginShared.value + } + const curIndex = currentOffset / step.value + const moveToIndex = (translation < 0 ? Math.floor(curIndex) : Math.ceil(curIndex)) - patchElmNumShared.value + const targetOffset = -(moveToIndex + patchElmNumShared.value) * step.value + (circularShared.value ? preMarginShared.value : 0) + offset.value = withTiming(targetOffset, { + duration: easeDuration, + easing: easeMap[easeingFunc] + }, () => { + if (touchfinish.value !== false) { + currentIndex.value = moveToIndex + runOnJS(resumeLoop)() + } + }) + } + function handleLongPress () { + 'worklet' + const currentOffset = Math.abs(offset.value) + let preOffset = (currentIndex.value + patchElmNumShared.value) * step.value + if (circularShared.value) { + preOffset -= preMarginShared.value + } + // 正常事件中拿到的transition值(正向滑动<0，倒着滑>0) + const diffOffset = preOffset - currentOffset + const half = Math.abs(diffOffset) > step.value / 2 + if (+diffOffset === 0) { + runOnJS(resumeLoop)() + } else if (half) { + handleEnd({ translation: diffOffset }) + } else { + handleBack({ translation: diffOffset }) + } + } + function reachBoundary (eventData: EventDataType) { + 'worklet' + // 移动的距离 + const { translation } = eventData + const elementsLength = step.value * childrenLength.value + let isBoundary = false + let resetOffset = 0 + // Y轴向下滚动, transDistance > 0, 向上滚动 < 0 X轴向左滚动, transDistance > 0 + const currentOffset = offset.value + const moveStep = Math.ceil(translation / elementsLength) + if (translation < 0) { + const posEnd = (childrenLength.value + patchElmNumShared.value + 1) * step.value + const posReverseEnd = (patchElmNumShared.value - 1) * step.value + if (currentOffset < -posEnd + step.value) { + isBoundary = true + resetOffset = Math.abs(moveStep) === 0 ? patchElmNumShared.value * step.value + translation : moveStep * elementsLength + } + if (currentOffset > -posReverseEnd) { + isBoundary = true + resetOffset = moveStep * elementsLength + } + } else if (translation > 0) { + const posEnd = (patchElmNumShared.value - 1) * step.value + const posReverseEnd = (patchElmNumShared.value + childrenLength.value) * step.value + if (currentOffset > -posEnd) { + isBoundary = true + resetOffset = moveStep * elementsLength + step.value + (moveStep === 1 ? translation : 0) + } + if (currentOffset < -posReverseEnd) { + isBoundary = true + resetOffset = moveStep * elementsLength + patchElmNumShared.value * step.value + } + } + return { + isBoundary, + resetOffset: -resetOffset + } + } + const gesturePan = Gesture.Pan() + .onBegin((e) => { + 'worklet' + if (!step.value) return + touchfinish.value = false + cancelAnimation(offset) + runOnJS(pauseLoop)() + preAbsolutePos.value = e[strAbso] + moveTranstion.value = e[strAbso] + moveTime.value = new Date().getTime() + }) + .onTouchesMove((e) => { + 'worklet' + if (touchfinish.value) return + const touchEventData = e.changedTouches[0] + const moveDistance = touchEventData[strAbso] - preAbsolutePos.value + const eventData = { + translation: moveDistance + } + // 处理用户一直拖拽到临界点的场景, 不会执行onEnd + if (!circularShared.value && !canMove(eventData)) { + return + } + const { isBoundary, resetOffset } = reachBoundary(eventData) + if (isBoundary && circularShared.value) { + offset.value = resetOffset + } else { + offset.value = moveDistance + offset.value + } + preAbsolutePos.value = touchEventData[strAbso] + }) + .onTouchesUp((e) => { + 'worklet' + if (touchfinish.value) return + const touchEventData = e.changedTouches[0] + const moveDistance = touchEventData[strAbso] - moveTranstion.value + touchfinish.value = true + const eventData = { + translation: moveDistance + } + // 用户手指按下起来, 需要计算正确的位置, 比如在滑动过程中突然按下然后起来,需要计算到正确的位置 + if (!circularShared.value && !canMove(eventData)) { + return + } + const strVelocity = moveDistance / (new Date().getTime() - moveTime.value) * 1000 + if (Math.abs(strVelocity) < longPressRatio) { + handleLongPress() + } else { + handleEnd(eventData) + } + }) + return { + gestureHandler: gesturePan + } + }, []) + + const animatedStyles = useAnimatedStyle(() => { + if (dir === 'x') { + return { transform: [{ translateX: offset.value }], opacity: step.value > 0 ? 1 : 0 } + } else { + return { transform: [{ translateY: offset.value }], opacity: step.value > 0 ? 1 : 0 } + } + }) + + function renderSwiper () { + const arrPages: Array | ReactNode = renderItems() + return ( + + {wrapChildren({ + children: arrPages + }, { + hasVarDec, + varContext: varContextRef.current, + textStyle, + textProps + })} + + {showsPagination && renderPagination()} + ) + } + + if (children.length === 1) { + return renderSwiper() + } else { + return ( + {renderSwiper()} + ) + } +}) +SwiperWrapper.displayName = 'MpxSwiperWrapper' + +export default SwiperWrapper diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/carouse.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/carouse.tsx deleted file mode 100644 index 6d00d236b6..0000000000 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/carouse.tsx +++ /dev/null @@ -1,527 +0,0 @@ -/** - * swiper 实现 - */ -import { Animated, View, ScrollView, Dimensions, NativeSyntheticEvent, NativeScrollEvent, NativeScrollPoint, Platform, LayoutChangeEvent } from 'react-native' -import { JSX, forwardRef, useState, useRef, useEffect, ReactNode } from 'react' -import { CarouseProps, CarouseState } from './type' -import { getCustomEvent } from '../getInnerListeners' -import useNodesRef, { HandlerRef } from '../useNodesRef' // 引入辅助函数 -import { useTransformStyle, splitStyle, splitProps, useLayout, wrapChildren } from '../utils' - -/** - * 默认的Style类型 - */ -const styles: { [key: string]: Object } = { - slide: { - backgroundColor: 'transparent' - }, - container_x: { - position: 'relative' - }, - container_y: { - position: 'relative' - }, - pagination_x: { - position: 'absolute', - bottom: 25, - left: 0, - right: 0, - flexDirection: 'row', - flex: 1, - justifyContent: 'center', - alignItems: 'center' - }, - - pagination_y: { - position: 'absolute', - right: 15, - top: 0, - bottom: 0, - flexDirection: 'column', - flex: 1, - justifyContent: 'center', - alignItems: 'center' - } -} - -const _Carouse = forwardRef, CarouseProps>((props, ref): JSX.Element => { - // 默认取水平方向的width - const { width } = Dimensions.get('window') - const { - style, - previousMargin = 0, - nextMargin = 0, - enableVar, - externalVarContext, - parentFontSize, - parentWidth, - parentHeight - } = props - // 计算transform之类的 - const { - normalStyle, - hasVarDec, - varContextRef, - hasSelfPercent, - setWidth, - setHeight - } = useTransformStyle(style, { - enableVar, - externalVarContext, - parentFontSize, - parentWidth, - parentHeight - }) - const { textStyle, innerStyle } = splitStyle(normalStyle) - const { textProps } = splitProps(props) - const newChild = Array.isArray(props.children) ? props.children.filter(child => child) : props.children - const totalElements = Array.isArray(newChild) ? newChild.length : (newChild ? 1 : 0) - const defaultHeight = (normalStyle?.height || 150) - const defaultWidth = (normalStyle?.width || width || 375) - const dir = props.horizontal === false ? 'y' : 'x' - // state的offset默认值 - // const initIndex = props.circular ? props.current + 1: (props.current || 0) - // 记录真正的下标索引, 不包括循环前后加入的索引, 游标 - const initIndex = props.current || 0 - // 这里要排除超过元素个数的设置 - const initOffsetIndex = initIndex + (props.circular && totalElements > 1 ? 1 : 0) - const defaultX = (defaultWidth * initOffsetIndex) || 0 - const defaultY = (defaultHeight * initOffsetIndex) || 0 - // 主动scorllTo时是否要出发onScrollEnd - const needTriggerScrollEnd = useRef(true) - // 内部存储上一次的offset值 - const autoplayTimerRef = useRef | null>(null) - const scrollViewRef = useRef(null) - useNodesRef(props, ref, scrollViewRef, { - style: normalStyle - }) - const { - // 存储layout布局信息 - layoutRef, - layoutProps, - layoutStyle - } = useLayout({ props, hasSelfPercent, setWidth, setHeight, nodeRef: scrollViewRef, onLayout: onWrapperLayout }) - // 内部存储上一次的偏移量 - const internalsRef = useRef({ - offset: { - x: 0, - y: 0 - }, - isScrolling: false - }) - const isDragRef = useRef(false) - const [state, setState] = useState({ - width: dir === 'x' && typeof defaultWidth === 'number' ? defaultWidth - previousMargin - nextMargin : defaultWidth, - height: dir === 'y' && typeof defaultHeight === 'number' ? defaultHeight - previousMargin - nextMargin : defaultHeight, - // 真正的游标索引, 从0开始 - index: initIndex, - total: totalElements, - offset: { - x: 0, - y: 0 - }, - dir - } as CarouseState) - /** - * @desc: 开启下一次自动轮播 - */ - function createAutoPlay () { - autoplayTimerRef.current && clearTimeout(autoplayTimerRef.current) - autoplayTimerRef.current = setTimeout(() => { - startAutoPlay() - }, props.interval || 500) - } - - useEffect(() => { - // 确认这个是变化的props变化的时候才执行，还是初始化的时候就执行 - if (props.autoplay) { - createAutoPlay() - } - }, [props.autoplay, props.current, state.index, state.width, state.height]) - - useEffect(() => { - // 确认这个是变化的props变化的时候才执行，还是初始化的时候就执行 - if (!props.autoplay && props.current !== undefined && props.current !== state.index) { - const initIndex = props.current || 0 - // 这里要排除超过元素个数的设置 - const { nextIndex, nextOffset } = getMultiNextConfig(props.current) - // 1. 安卓需要主动更新下内部状态, 2. IOS不能触发完wcrollTo之后立即updateState, 会造成滑动两次 - // 2. setTimeout 是fix 当再渲染过程中触发scrollTo失败的问题 - if (Platform.OS === 'ios') { - needTriggerScrollEnd.current = false - setTimeout(() => { - scrollViewRef.current?.scrollTo({ - ...nextOffset, - animated: true - }) - }, 50) - } else { - updateState(nextIndex, nextOffset) - } - } - }, [props.current, state.width, state.height]) - - function getMultiNextConfig (target: number) { - const step = state.dir === 'x' ? state.width : state.height - const targetPos = step * props.current - const targetOffset = { - x: dir === 'x' ? targetPos : 0, - y: dir === 'y' ? targetPos : 0 - } - return { - nextIndex: target, - nextOffset: targetOffset - } - } - /** - * @desc: 更新状态: index和offset, 并响应索引变化的事件 - * scrollViewOffset: 移动到的目标位置 - */ - function updateIndex (scrollViewOffset: NativeScrollPoint, useIndex = false) { - const { nextIndex, nextOffset } = getNextConfig(scrollViewOffset) - updateState(nextIndex, nextOffset) - // 更新完状态之后, 开启新的loop - } - - /** - * 更新索引状态 - */ - function updateState (index: number, offset: { x: number, y: number}) { - internalsRef.current.offset = offset - setState((preState) => { - const newState = { - ...preState, - index: index, - // offset用来指示当前scrollView的偏移量 - offset: offset - } - return newState - }) - internalsRef.current.isScrolling = false - // getCustomEvent - const eventData = getCustomEvent('change', {}, { detail: { current: index, source: 'touch' }, layoutRef: layoutRef }) - props.bindchange && props.bindchange(eventData) - } - - /** - * @desc: 获取下一个位置的索引、scrollView的contentOffset、scrollTo到的offset - * @desc: 包括正循环、反向循环、不循环 - * 其中循环模式为了实现无缝链接, 会将结合contentOffset, 和 scrollTo的offset, - * 先scrollTo一个位置的坐标, 然后通过updateIndex设置真正的index和内容的offset,视觉上是无缝 - */ - function getNextConfig (scrollViewOffset: NativeScrollPoint) { - const step = state.dir === 'x' ? state.width : state.height - const currentOffset = state.offset - let nextIndex = state.index + 1 - let nextOffset = currentOffset - // autoMoveOffset scrollView 滚动到前后增加的位置 - let autoMoveOffset = currentOffset - let isBack = false - let isAutoEnd = false - // 如果是循环反向的 - if (scrollViewOffset?.[state.dir] < currentOffset[state.dir]) { - isBack = true - nextIndex = isBack ? nextIndex - 2 : nextIndex - } - if (!props.circular) { - nextOffset = Object.assign({}, currentOffset, { [state.dir]: step * nextIndex }) - } else { - if (isBack) { - if (nextIndex < 0) { - // 反向: scollView 滚动到虚拟的位置 - autoMoveOffset = Object.assign({}, currentOffset, { [state.dir]: 0 }) - nextIndex = state.total - 1 - // 反向: 数组最后一个index - nextOffset = Object.assign({}, currentOffset, { [state.dir]: step * state.total }) - isAutoEnd = true - } else { - // 反向非最后一个 - nextOffset = Object.assign({}, currentOffset, { [state.dir]: (nextIndex + 1) * step }) - } - } else { - if (nextIndex > state.total - 1) { - autoMoveOffset = Object.assign({}, currentOffset, { [state.dir]: step * (nextIndex + 1) }) - nextIndex = 0 - nextOffset = Object.assign({}, currentOffset, { [state.dir]: step }) - isAutoEnd = true - } else { - // nextIndex = nextIndex, - nextOffset = Object.assign({}, currentOffset, { [state.dir]: (nextIndex + 1) * step }) - } - } - } - return { - // 下一个要滚动到的实际元素的索引 - nextIndex, - // 下一个要滚动到实际元素的offset - nextOffset, - // scrollTo一个位置的坐标, 虚拟元素的位置 - autoMoveOffset, - isAutoEnd - } - } - - /** - * @desc: 开启自动轮播 - */ - function startAutoPlay () { - if (state.width && isNaN(+state.width)) { - createAutoPlay() - return - } - if (!Array.isArray(props.children)) { - return - } - const step = state.dir === 'x' ? state.width : state.height - const { nextOffset, autoMoveOffset, isAutoEnd } = getNextConfig(state.offset) - // 这里可以scroll到下一个元素, 但是把scrollView的偏移量在设置为content,视觉效果就没了吧 - if (Platform.OS === 'ios') { - if (!isAutoEnd) { - scrollViewRef.current?.scrollTo({ x: nextOffset.x, y: nextOffset.y, animated: true }) - } else { - if (state.dir === 'x') { - scrollViewRef.current?.scrollTo({ x: autoMoveOffset.x, y: autoMoveOffset.x, animated: true }) - } else { - scrollViewRef.current?.scrollTo({ x: autoMoveOffset.y, y: autoMoveOffset.y, animated: true }) - } - } - } else { - if (!isAutoEnd) { - scrollViewRef.current?.scrollTo({ x: nextOffset.x, y: nextOffset.y, animated: true }) - onScrollEnd({ - nativeEvent: { - contentOffset: { - x: +nextOffset.x, - y: +nextOffset.y - } - } - } as NativeSyntheticEvent) - } else { - // 安卓无法实现视觉的无缝连接, 只能回到真正的位置, 且安卓调用scrollTo不能触发onMomentumScrollEnd,还未找到为啥 - if (state.dir === 'x') { - scrollViewRef.current?.scrollTo({ x: step, y: step, animated: true }) - } else { - scrollViewRef.current?.scrollTo({ x: autoMoveOffset.x, y: step, animated: true }) - } - updateState(0, nextOffset) - } - } - } - - /** - * 当用户开始拖动此视图时调用此函数, 更新当前在滚动态 - */ - function onScrollBegin () { - internalsRef.current.isScrolling = true - } - - /** - * 当用户开始拖动结束 - * 注意: 当手动调用scrollTo的时候, 安卓不会触发onMomentumScrollEnd, IOS会触发onMomentumScrollEnd - */ - function onScrollEnd (event: NativeSyntheticEvent) { - if (Platform.OS === 'ios' && !needTriggerScrollEnd.current) { - const { nextIndex, nextOffset } = getMultiNextConfig(props.current) - updateState(nextIndex, nextOffset) - needTriggerScrollEnd.current = true - return - } - if (totalElements === 1) { - return - } - internalsRef.current.isScrolling = false - // 用户手动滑动更新索引后，如果开启了自动轮播等重新开始 - updateIndex(event.nativeEvent.contentOffset, true) - } - - /** - * 当拖拽结束时，检测是否可滚动 - */ - function onScrollEndDrag (event: NativeSyntheticEvent) { - const { contentOffset } = event.nativeEvent - const { index, total } = state - isDragRef.current = true - const internalOffset = internalsRef.current.offset - const previousOffset = props.horizontal ? internalOffset.x : internalOffset.y - const moveOffset = props.horizontal ? contentOffset.x : contentOffset.y - if (previousOffset === moveOffset && (index === 0 || index === total - 1)) { - internalsRef.current.isScrolling = false - } - } - - /** - * @desc: 水平方向时，获取元素的布局，更新, 其中如果传递100%时需要依赖measure计算元算的宽高 - */ - function onWrapperLayout (e: LayoutChangeEvent) { - scrollViewRef.current?.measure((x: number, y: number, width: number, height: number, offsetLeft: number, offsetTop: number) => { - layoutRef.current = { x, y, width, height, offsetLeft, offsetTop } - const isWDiff = state.width !== width - const isHDiff = state.height !== height - if (isWDiff || isHDiff) { - const changeState = { - width: isWDiff ? width : state.width, - height: isHDiff ? height : state.height - } - const attr = state.dir === 'x' ? 'width' : 'height' - changeState[attr] = changeState[attr] - previousMargin - nextMargin - const correctOffset = Object.assign({}, state.offset, { - [state.dir]: initOffsetIndex * (state.dir === 'x' ? changeState.width : changeState.height) - }) - state.width = changeState.width - state.height = changeState.height - // 这里setState之后,会再触发重新渲染, renderScrollView会再次触发onScrollEnd, - setState((preState) => { - return { - ...preState, - width: changeState.width, - height: changeState.height - } - }) - } - props.getInnerLayout && props.getInnerLayout(layoutRef) - }) - } - - function getOffset (): Array { - const step = state.dir === 'x' ? state.width : state.height - if (!step || Number.isNaN(+step)) return [] - const offsetArray = [] - for (let i = 0; i < totalElements; i++) { - offsetArray.push(i * step) - } - return offsetArray - } - - function renderScrollView (pages: ReactNode) { - const offsetsArray = getOffset() - const scrollElementProps = { - ref: scrollViewRef, - horizontal: props.horizontal, - pagingEnabled: true, - snapToOffsets: offsetsArray, - decelerationRate: 0.99, // 'fast' - showsHorizontalScrollIndicator: false, - showsVerticalScrollIndicator: false, - bounces: false, - scrollsToTop: false, - removeClippedSubviews: true, - automaticallyAdjustContentInsets: false - } - const layoutStyle = dir === 'x' ? { width: defaultWidth, height: defaultHeight } : { width: defaultWidth } - return ( - - {pages} - - ) - } - - function renderPagination () { - if (state.total <= 1) return null - const dots: Array = [] - const activeDotStyle = [{ - backgroundColor: props.activeDotColor || '#007aff', - width: 8, - height: 8, - borderRadius: 4, - marginLeft: 3, - marginRight: 3, - marginTop: 3, - marginBottom: 3 - }] - const dotStyle = [{ - backgroundColor: props.dotColor || 'rgba(0,0,0,.2)', - width: 8, - height: 8, - borderRadius: 4, - marginLeft: 3, - marginRight: 3, - marginTop: 3, - marginBottom: 3 - }] - for (let i = 0; i < state.total; i++) { - if (i === state.index) { - dots.push() - } else { - dots.push() - } - } - return ( - - {dots} - - ) - } - - function renderPages () { - const { width, height } = state - const { children } = props - const { circular } = props - const pageStyle = { width: width, height: height } - // 设置了previousMargin或者nextMargin, - // 1. 元素的宽度是减去这两个数目之和 - // 2. previousMargin设置marginLeft正值, nextmargin设置marginRight负值 - // 3. 第一个元素设置previousMargin 和 nextMargin, 最后一个元素 - if (totalElements > 1 && Array.isArray(children)) { - let arrElements: (Array) = [] - // pages = ["2", "0", "1", "2", "0"] - const pages = Array.isArray(children) ? Object.keys(children) : [] - /* 无限循环的时候 */ - if (circular) { - pages.unshift(totalElements - 1 + '') - pages.push('0') - } - arrElements = pages.map((page, i) => { - const extraStyle = {} as { - [key: string]: any - } - if (i === 0 && dir === 'x' && typeof width === 'number') { - previousMargin && (extraStyle.marginLeft = previousMargin) - } else if (i === pages.length - 1 && typeof width === 'number') { - nextMargin && (extraStyle.marginRight = nextMargin) - } - return ( - {wrapChildren( - { - children: children[+page] - }, - { - hasVarDec, - varContext: varContextRef.current, - textStyle, - textProps - } - )} - ) - }) - return arrElements - } else { - const realElement = ( - - {children} - - ) - return realElement - } - } - - const pages: Array | ReactNode = renderPages() - return ( - {renderScrollView(pages)} - {props.showsPagination && renderPagination()} - ) -}) - -_Carouse.displayName = 'MpxCarouse' - -export default _Carouse diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/index.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/index.tsx deleted file mode 100644 index 46f6d8daeb..0000000000 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/index.tsx +++ /dev/null @@ -1,80 +0,0 @@ -import { ScrollView } from 'react-native' -import { JSX, MutableRefObject, forwardRef, useRef } from 'react' -import Carouse from './carouse' -import { SwiperProps } from './type' -import useInnerProps from '../getInnerListeners' -import useNodesRef, { HandlerRef } from '../useNodesRef' // 引入辅助函数 -/** - * ✔ indicator-dots - * ✔ indicator-color - * ✔ indicator-active-color - * ✔ autoplay - * ✔ current - * ✔ interval - * ✔ duration - * ✔ circular - * ✔ vertical - * ✘ display-multiple-items - * ✘ previous-margin - * ✘ next-margin - * ✔ easing-function ="easeOutCubic" - * ✘ snap-to-edge - */ -const _SwiperWrapper = forwardRef, SwiperProps>((props: SwiperProps, ref): JSX.Element => { - const { children } = props - const innerLayout = useRef({}) - const swiperProp = { - circular: props.circular || false, - current: props.current || 0, - autoplay: props.autoplay || false, - duration: props.duration || 500, - interval: props.interval || 5000, - showsPagination: props['indicator-dots'], - dotColor: props['indicator-color'] || 'rgba(0, 0, 0, .3)', - activeDotColor: props['indicator-active-color'] || '#000000', - horizontal: props.vertical !== undefined ? !props.vertical : true, - previousMargin: props['previous-margin'] ? parseInt(props['previous-margin']) : 0, - nextMargin: props['next-margin'] ? parseInt(props['next-margin']) : 0, - enableOffset: props['enable-offset'] || true, - enableVar: props['enable-var'] || false, - parentFontSize: props['parent-font-size'], - parentWidth: props['parent-width'], - parentHeight: props['parent-height'], - style: props.style || {}, - externalVarContext: props['external-var-context'], - bindchange: props.bindchange, - easingFunction: props['easing-function'] || 'default' - } - - const nodeRef = useRef(null) - useNodesRef(props, ref, nodeRef, {}) - - const innerProps = useInnerProps(props, { - ref: nodeRef - }, [ - 'indicator-dots', - 'indicator-color', - 'indicator-active-color', - 'previous-margin', - 'vertical', - 'previous-margin', - 'next-margin', - 'easing-function' - ], { layoutRef: innerLayout }) - - const getInnerLayout = (layout: MutableRefObject<{}>) => { - innerLayout.current = layout.current - } - - return - {children} - -}) - -_SwiperWrapper.displayName = 'MpxSwiper' - -export default _SwiperWrapper diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/type.ts b/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/type.ts deleted file mode 100644 index 2815f9acc7..0000000000 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-swiper/type.ts +++ /dev/null @@ -1,87 +0,0 @@ -import { ReactNode } from 'react' -import { NativeSyntheticEvent } from 'react-native' - -export type EaseType = 'default' | 'linear' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' - -export interface SwiperProps { - children?: ReactNode; - circular?: boolean; - current?: number; - interval?: number; - autoplay?: boolean; - duration?: number; - 'indicator-dots'?: boolean; - 'indicator-color'?: string; - 'indicator-active-color'?: string; - vertical?: boolean; - style: { - [key: string]: any - }; - 'easing-function'?: EaseType; - 'previous-margin'?: string; - 'next-margin'?: string; - 'enable-offset'?: boolean; - 'enable-var': boolean; - 'parent-font-size'?: number; - 'parent-width'?: number; - 'parent-height'?: number; - 'external-var-context'?: Record; - bindchange?: (event: NativeSyntheticEvent | unknown) => void; -} - -export interface CarouseProps { - children?: ReactNode; - circular?: boolean; - current: number; - autoplay?: boolean; - duration?: number; - interval?: number; - showsPagination?: boolean; - dotColor?: string; - activeDotColor?: string; - horizontal?: boolean; - easingFunction?: EaseType; - previousMargin?: number; - nextMargin?: number; - enableOffset?: boolean; - parentFontSize?: number; - parentWidth?: number; - parentHeight?: number; - bindchange?: (event: NativeSyntheticEvent | unknown) => void; - getInnerLayout: Function; - innerProps: Object; - style: { - [key: string]: any - }; - enableVar: boolean; - externalVarContext?: Record; -} - -export interface CarouseState { - children: Array | ReactNode, - width: number; - height: number; - index: number; - total: number; - // 设置scrollView初始的滚动坐标，contentOffset - offset: { - x: number, - y: number - }; - // 是否结束自动轮播，手动设置滚动到具体位置时结束 - autoplayEnd: boolean; - loopJump: boolean; - dir: 'x' | 'y'; - isScrollEnd: boolean -} - -export interface ScrollElementProps { - pagingEnabled: boolean, - showsHorizontalScrollIndicator: boolean, - showsVerticalScrollIndicator: boolean, - bounces: boolean, - scrollsToTop: boolean, - removeClippedSubviews: boolean, - automaticallyAdjustContentInsets: boolean, - horizontal: boolean -} diff --git a/packages/webpack-plugin/lib/runtime/components/react/mpx-view.tsx b/packages/webpack-plugin/lib/runtime/components/react/mpx-view.tsx index 9939bff0a1..7d8cdbc94b 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/mpx-view.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/mpx-view.tsx @@ -12,9 +12,10 @@ import useAnimationHooks from './useAnimationHooks' import type { AnimationProp } from './useAnimationHooks' import { ExtendedViewStyle } from './types/common' import useNodesRef, { HandlerRef } from './useNodesRef' -import { parseUrl, PERCENT_REGEX, splitStyle, splitProps, useTransformStyle, wrapChildren, useLayout, renderImage, pickStyle, extendObject } from './utils' +import { parseUrl, PERCENT_REGEX, splitStyle, splitProps, useTransformStyle, wrapChildren, useLayout, renderImage, pickStyle, extendObject, useHover } from './utils' import { error } from '@mpxjs/utils' import LinearGradient from 'react-native-linear-gradient' +import { GestureDetector, PanGesture } from 'react-native-gesture-handler' export interface _ViewProps extends ViewProps { style?: ExtendedViewStyle @@ -642,7 +643,7 @@ function useWrapImage (imageStyle?: ExtendedViewStyle, innerStyle?: Record @@ -684,8 +685,6 @@ const _View = forwardRef, _ViewProps>((viewProps, r animation } = props - const [isHover, setIsHover] = useState(false) - // 默认样式 const defaultStyle: ExtendedViewStyle = style.display === 'flex' ? { @@ -696,6 +695,9 @@ const _View = forwardRef, _ViewProps>((viewProps, r } : {} + const enableHover = !!hoverStyle + const { isHover, gesture } = useHover({ enableHover, hoverStartTime, hoverStayTime }) + const styleObj: ExtendedViewStyle = extendObject({}, defaultStyle, style, isHover ? hoverStyle as ExtendedViewStyle : {}) const { @@ -726,45 +728,6 @@ const _View = forwardRef, _ViewProps>((viewProps, r style: normalStyle }) - const dataRef = useRef<{ - startTimer?: ReturnType - stayTimer?: ReturnType - }>({}) - - useEffect(() => { - return () => { - dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer) - dataRef.current.stayTimer && clearTimeout(dataRef.current.stayTimer) - } - }, []) - - const setStartTimer = () => { - dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer) - dataRef.current.startTimer = setTimeout(() => { - setIsHover(true) - }, +hoverStartTime) - } - - const setStayTimer = () => { - dataRef.current.stayTimer && clearTimeout(dataRef.current.stayTimer) - dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer) - dataRef.current.stayTimer = setTimeout(() => { - setIsHover(false) - }, +hoverStayTime) - } - - function onTouchStart (e: NativeSyntheticEvent) { - const { bindtouchstart } = props - bindtouchstart && bindtouchstart(e) - setStartTimer() - } - - function onTouchEnd (e: NativeSyntheticEvent) { - const { bindtouchend } = props - bindtouchend && bindtouchend(e) - setStayTimer() - } - const { layoutRef, layoutStyle, @@ -773,33 +736,19 @@ const _View = forwardRef, _ViewProps>((viewProps, r const viewStyle = extendObject({}, innerStyle, layoutStyle) - enableAnimation = enableAnimation || !!animation - const enableAnimationRef = useRef(enableAnimation) - if (enableAnimationRef.current !== enableAnimation) { - error('[Mpx runtime error]: animation use should be stable in the component lifecycle, or you can set [enable-animation] with true.') - } + const { enableStyleAnimation, animationStyle } = useAnimationHooks({ + enableAnimation, + animation, + style: viewStyle + }) - const finalStyle = enableAnimationRef.current - ? [viewStyle, - // eslint-disable-next-line react-hooks/rules-of-hooks - useAnimationHooks({ - animation, - style: viewStyle - })] - : viewStyle const innerProps = useInnerProps( props, extendObject({ ref: nodeRef, - style: finalStyle + style: enableStyleAnimation ? [viewStyle, animationStyle] : viewStyle }, - layoutProps, - hoverStyle - ? { - bindtouchstart: onTouchStart, - bindtouchend: onTouchEnd - } - : {} + layoutProps ), [ 'hover-start-time', 'hover-stay-time', @@ -820,9 +769,13 @@ const _View = forwardRef, _ViewProps>((viewProps, r enableFastImage }) - return enableAnimation + const BaseComponent = enableStyleAnimation ? createElement(Animated.View, innerProps, childNode) : createElement(View, innerProps, childNode) + + return enableHover + ? createElement(GestureDetector, { gesture: gesture as PanGesture }, BaseComponent) + : BaseComponent }) _View.displayName = 'MpxView' diff --git a/packages/webpack-plugin/lib/runtime/components/react/pickerFaces.ts b/packages/webpack-plugin/lib/runtime/components/react/pickerFaces.ts index f25dc0313f..329d6adbcd 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/pickerFaces.ts +++ b/packages/webpack-plugin/lib/runtime/components/react/pickerFaces.ts @@ -8,6 +8,7 @@ export type Faces = { deg: number offsetY: number opacity: number + scale: number screenHeight: number } @@ -33,7 +34,7 @@ export const createFaces = ( const maxStep = Math.trunc((visibleCount + 2) / 2) // + 2 because there are 2 more faces at 90 degrees const stepDegree = 90 / maxStep - const result = [] + const result: number[] = [] for (let i = 1; i <= maxStep; i++) { result.push(i * stepDegree) } @@ -62,17 +63,17 @@ export const createFaces = ( const getOpacity = (index: number) => { const map: Record = { 0: 0, - 1: 0.2, - 2: 0.35, - 3: 0.45, - 4: 0.5 + 1: 0.8, + 2: 0.9 } - return map[index] ?? Math.min(1, map[4] + index * 0.5) + return map[index] ?? Math.min(1, map[2] + index * 0.05) } const degrees = getDegreesRelativeCenter() const [screenHeight, offsets] = getScreenHeightsAndOffsets(degrees) + const scales = [0.973, 0.9, 0.8] + return [ // top items ...degrees @@ -82,13 +83,14 @@ export const createFaces = ( deg: degree, opacity: getOpacity(degrees.length - 1 - index), offsetY: -1 * offsets[index], + scale: scales[index], screenHeight: screenHeight[index] } }) .reverse(), // center item - { index: 0, deg: 0, opacity: 1, offsetY: 0, screenHeight: itemHeight }, + { index: 0, deg: 0, opacity: 1, offsetY: 0, scale: 1, screenHeight: itemHeight }, // bottom items ...degrees.map((degree, index) => { @@ -97,6 +99,7 @@ export const createFaces = ( deg: -1 * degree, opacity: getOpacity(degrees.length - 1 - index), offsetY: offsets[index], + scale: scales[index], screenHeight: screenHeight[index] } }) diff --git a/packages/webpack-plugin/lib/runtime/components/react/pickerOverlay.tsx b/packages/webpack-plugin/lib/runtime/components/react/pickerOverlay.tsx deleted file mode 100644 index 4a11903d6e..0000000000 --- a/packages/webpack-plugin/lib/runtime/components/react/pickerOverlay.tsx +++ /dev/null @@ -1,32 +0,0 @@ -import React from 'react' -import { StyleProp, StyleSheet, View, ViewStyle } from 'react-native' - -type OverlayProps = { - itemHeight: number - overlayItemStyle?: StyleProp - overlayContainerStyle?: StyleProp -} - -const Overlay = ({ itemHeight, overlayItemStyle, overlayContainerStyle }: OverlayProps) => { - return ( - - - - ) -} - -const styles = StyleSheet.create({ - overlayContainer: { - ...StyleSheet.absoluteFillObject, - justifyContent: 'center', - alignItems: 'center' - }, - selection: { - borderTopWidth: 1, - borderBottomWidth: 1, - borderColor: 'rgba(0, 0, 0, 0.05)', - alignSelf: 'stretch' - } -}) - -export default React.memo(Overlay) diff --git a/packages/webpack-plugin/lib/runtime/components/react/pickerVIewContext.ts b/packages/webpack-plugin/lib/runtime/components/react/pickerVIewContext.ts new file mode 100644 index 0000000000..8ab8e588e9 --- /dev/null +++ b/packages/webpack-plugin/lib/runtime/components/react/pickerVIewContext.ts @@ -0,0 +1,27 @@ +import { createContext, useContext } from 'react' +import { SharedValue } from 'react-native-reanimated' + +type ContextValue = SharedValue + +export const PickerViewColumnAnimationContext = createContext< + ContextValue | undefined +>(undefined) + +export const usePickerViewColumnAnimationContext = () => { + const value = useContext(PickerViewColumnAnimationContext) + if (value === undefined) { + throw new Error( + 'usePickerViewColumnAnimationContext must be called from within PickerViewColumnAnimationContext.Provider!' + ) + } + return value +} + +export const PickerViewStyleContext = createContext< + Record | undefined +>(undefined) + +export const usePickerViewStyleContext = () => { + const value = useContext(PickerViewStyleContext) + return value +} diff --git a/packages/webpack-plugin/lib/runtime/components/react/pickerViewIndicator.tsx b/packages/webpack-plugin/lib/runtime/components/react/pickerViewIndicator.tsx new file mode 100644 index 0000000000..3c745b059d --- /dev/null +++ b/packages/webpack-plugin/lib/runtime/components/react/pickerViewIndicator.tsx @@ -0,0 +1,34 @@ +import React from 'react' +import { StyleProp, StyleSheet, View, ViewStyle } from 'react-native' + +type IndicatorProps = { + itemHeight: number + indicatorItemStyle?: StyleProp + indicatorContainerStyle?: StyleProp +} + +const _PickerViewIndicator = ({ itemHeight, indicatorItemStyle, indicatorContainerStyle }: IndicatorProps) => { + return ( + + + + ) +} + +const styles = StyleSheet.create({ + indicatorContainer: { + ...StyleSheet.absoluteFillObject, + justifyContent: 'center', + alignItems: 'center', + zIndex: 200 + }, + selection: { + borderTopWidth: 1, + borderBottomWidth: 1, + borderColor: 'rgba(0, 0, 0, 0.05)', + alignSelf: 'stretch' + } +}) + +_PickerViewIndicator.displayName = 'MpxPickerViewIndicator' +export default _PickerViewIndicator diff --git a/packages/webpack-plugin/lib/runtime/components/react/pickerViewMask.tsx b/packages/webpack-plugin/lib/runtime/components/react/pickerViewMask.tsx new file mode 100644 index 0000000000..a0858122ba --- /dev/null +++ b/packages/webpack-plugin/lib/runtime/components/react/pickerViewMask.tsx @@ -0,0 +1,30 @@ +import React from 'react' +import { StyleProp, StyleSheet, View, ViewStyle } from 'react-native' +import LinearGradient from 'react-native-linear-gradient' + +type MaskProps = { + itemHeight: number + maskContainerStyle?: StyleProp +} + +const _PickerViewMask = ({ + itemHeight, + maskContainerStyle +}: MaskProps) => { + return ( + + + + + + ) +} +const styles = StyleSheet.create({ + maskContainer: { + ...StyleSheet.absoluteFillObject, + zIndex: 100 + } +}) + +_PickerViewMask.displayName = 'MpxPickerViewMask' +export default _PickerViewMask diff --git a/packages/webpack-plugin/lib/runtime/components/react/useAnimationHooks.ts b/packages/webpack-plugin/lib/runtime/components/react/useAnimationHooks.ts index 71a41f5379..620dea764a 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/useAnimationHooks.ts +++ b/packages/webpack-plugin/lib/runtime/components/react/useAnimationHooks.ts @@ -13,6 +13,7 @@ import { WithTimingConfig, AnimationCallback } from 'react-native-reanimated' +import { error } from '@mpxjs/utils' import { ExtendedViewStyle } from './types/common' import type { _ViewProps } from './mpx-view' @@ -166,20 +167,32 @@ const formatStyle = (style: ExtendedViewStyle): ExtendedViewStyle => { }) } -export default function useAnimationHooks (props: _ViewProps) { - const { style = {}, animation } = props +export default function useAnimationHooks (props: _ViewProps & { enableAnimation?: boolean }) { + const { style = {}, animation, enableAnimation } = props + + const enableStyleAnimation = enableAnimation || !!animation + const enableAnimationRef = useRef(enableStyleAnimation) + if (enableAnimationRef.current !== enableStyleAnimation) { + error('[Mpx runtime error]: animation use should be stable in the component lifecycle, or you can set [enable-animation] with true.') + } + + if (!enableAnimationRef.current) return { enableStyleAnimation: false } + const originalStyle = formatStyle(style) // id 标识 const id = animation?.id || -1 // 有动画样式的 style key + // eslint-disable-next-line react-hooks/rules-of-hooks const animatedStyleKeys = useSharedValue([] as (string|string[])[]) // 记录动画key的style样式值 没有的话设置为false + // eslint-disable-next-line react-hooks/rules-of-hooks const animatedKeys = useRef({} as {[propName: keyof ExtendedViewStyle]: boolean}) // const animatedKeys = useRef({} as {[propName: keyof ExtendedViewStyle]: boolean|number|string}) // ** 全量 style prop sharedValue // 不能做增量的原因： // 1 尝试用 useRef，但 useAnimatedStyle 访问后的 ref 不能在增加新的值，被冻结 // 2 尝试用 useSharedValue，因为实际触发的 style prop 需要是 sharedValue 才能驱动动画，若外层 shareValMap 也是 sharedValue，动画无法驱动。 + // eslint-disable-next-line react-hooks/rules-of-hooks const shareValMap = useMemo(() => { return Object.keys(InitialValue).reduce((valMap, key) => { const defaultVal = getInitialVal(key, isTransform(key)) @@ -188,6 +201,7 @@ export default function useAnimationHooks (props: _ViewProps) { }, {} as { [propName: keyof ExtendedViewStyle]: SharedValue }) }, []) // ** 获取动画样式prop & 驱动动画 + // eslint-disable-next-line react-hooks/rules-of-hooks useEffect(() => { if (id === -1) return // 更新动画样式 key map @@ -208,6 +222,7 @@ export default function useAnimationHooks (props: _ViewProps) { // }) // }, [style]) // ** 清空动画 + // eslint-disable-next-line react-hooks/rules-of-hooks useEffect(() => { return () => { Object.values(shareValMap).forEach((value) => { @@ -335,7 +350,8 @@ export default function useAnimationHooks (props: _ViewProps) { }, {} as { [propName: string]: string | number }) } // ** 生成动画样式 - return useAnimatedStyle(() => { + // eslint-disable-next-line react-hooks/rules-of-hooks + const animationStyle = useAnimatedStyle(() => { // console.info(`useAnimatedStyle styles=`, originalStyle) return animatedStyleKeys.value.reduce((styles, key) => { // console.info('getAnimationStyles', key, shareValMap[key].value) @@ -353,4 +369,9 @@ export default function useAnimationHooks (props: _ViewProps) { return styles }, {} as ExtendedViewStyle) }) + + return { + enableStyleAnimation: enableAnimationRef.current, + animationStyle + } } diff --git a/packages/webpack-plugin/lib/runtime/components/react/utils.tsx b/packages/webpack-plugin/lib/runtime/components/react/utils.tsx index 08fac95572..6a9b685adb 100644 --- a/packages/webpack-plugin/lib/runtime/components/react/utils.tsx +++ b/packages/webpack-plugin/lib/runtime/components/react/utils.tsx @@ -1,12 +1,14 @@ import { useEffect, useCallback, useMemo, useRef, ReactNode, ReactElement, isValidElement, useContext, useState, Dispatch, SetStateAction, Children, cloneElement } from 'react' -import { LayoutChangeEvent, TextStyle, ImageProps, Image } from 'react-native' +import { LayoutChangeEvent, TextStyle, ImageProps, Image, Platform } from 'react-native' import { isObject, isFunction, isNumber, hasOwn, diffAndCloneA, error, warn } from '@mpxjs/utils' -import { VarContext } from './context' +import { VarContext, ScrollViewContext } from './context' import { ExpressionParser, parseFunc, ReplaceSource } from './parser' import { initialWindowMetrics } from 'react-native-safe-area-context' import { useNavigation } from '@react-navigation/native' import FastImage, { FastImageProps } from '@d11/react-native-fast-image' -import type { AnyFunc, ExtendedFunctionComponent } from './types/common' +import type { AnyFunc, ExtendedFunctionComponent, ExtendedViewStyle } from './types/common' +import { runOnJS } from 'react-native-reanimated' +import { Gesture } from 'react-native-gesture-handler' export const TEXT_STYLE_REGEX = /color|font.*|text.*|letterSpacing|lineHeight|includeFontPadding|writingDirection/ export const PERCENT_REGEX = /^\s*-?\d+(\.\d+)?%\s*$/ @@ -19,6 +21,11 @@ export const HIDDEN_STYLE = { opacity: 0 } +declare const __mpx_mode__: 'ios' | 'android' + +export const isIOS = __mpx_mode__ === 'ios' +export const isAndroid = __mpx_mode__ === 'android' + const varDecRegExp = /^--/ const varUseRegExp = /var\(/ const unoVarDecRegExp = /^--un-/ @@ -566,13 +573,14 @@ export const debounce = ( ): ((...args: Parameters) => void) & { clear: () => void } => { let timer: any const wrapper = (...args: ReadonlyArray) => { - clearTimeout(timer) + timer && clearTimeout(timer) timer = setTimeout(() => { func(...args) }, delay) } wrapper.clear = () => { - clearTimeout(timer) + timer && clearTimeout(timer) + timer = null } return wrapper } @@ -642,3 +650,67 @@ export function pickStyle (styleObj: Record = {}, pickedKeys: Array return acc }, {}) } + +export function useHover ({ enableHover, hoverStartTime, hoverStayTime, disabled } : { enableHover: boolean, hoverStartTime: number, hoverStayTime: number, disabled?: boolean }) { + const enableHoverRef = useRef(enableHover) + if (enableHoverRef.current !== enableHover) { + error('[Mpx runtime error]: hover-class use should be stable in the component lifecycle.') + } + + if (!enableHoverRef.current) return { isHover: false } + // eslint-disable-next-line react-hooks/rules-of-hooks + const gestureRef = useContext(ScrollViewContext).gestureRef + // eslint-disable-next-line react-hooks/rules-of-hooks + const [isHover, setIsHover] = useState(false) + // eslint-disable-next-line react-hooks/rules-of-hooks + const dataRef = useRef<{ + startTimer?: ReturnType + stayTimer?: ReturnType + }>({}) + + // eslint-disable-next-line react-hooks/rules-of-hooks + useEffect(() => { + return () => { + dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer) + dataRef.current.stayTimer && clearTimeout(dataRef.current.stayTimer) + } + }, []) + + const setStartTimer = () => { + if (disabled) return + dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer) + dataRef.current.startTimer = setTimeout(() => { + setIsHover(true) + }, +hoverStartTime) + } + + const setStayTimer = () => { + if (disabled) return + dataRef.current.stayTimer && clearTimeout(dataRef.current.stayTimer) + dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer) + dataRef.current.stayTimer = setTimeout(() => { + setIsHover(false) + }, +hoverStayTime) + } + // eslint-disable-next-line react-hooks/rules-of-hooks + const gesture = useMemo(() => { + return Gesture.Pan() + .onTouchesDown(() => { + 'worklet' + runOnJS(setStartTimer)() + }) + .onTouchesUp(() => { + 'worklet' + runOnJS(setStayTimer)() + }) + }, []) + + if (gestureRef) { + gesture.simultaneousWithExternalGesture(gestureRef) + } + + return { + isHover, + gesture + } +} diff --git a/packages/webpack-plugin/lib/runtime/components/web/mpx-checkbox.vue b/packages/webpack-plugin/lib/runtime/components/web/mpx-checkbox.vue index 74f7d222cc..f9112000ce 100644 --- a/packages/webpack-plugin/lib/runtime/components/web/mpx-checkbox.vue +++ b/packages/webpack-plugin/lib/runtime/components/web/mpx-checkbox.vue @@ -30,10 +30,10 @@ if (this.disabled) { return } + this.isChecked = !this.isChecked if (this.group) { this.group.notifyChange() } - this.isChecked = !this.isChecked } }, force: true diff --git a/packages/webpack-plugin/lib/runtime/components/web/mpx-picker-view-column.vue b/packages/webpack-plugin/lib/runtime/components/web/mpx-picker-view-column.vue index effe1317f0..b8bcfd7d4d 100644 --- a/packages/webpack-plugin/lib/runtime/components/web/mpx-picker-view-column.vue +++ b/packages/webpack-plugin/lib/runtime/components/web/mpx-picker-view-column.vue @@ -40,14 +40,14 @@ export default { this.wheels[0].wheelTo(newVal[0]) }) } - } + }, }, mounted () { this.wheels = [] this.refresh() - for (let i = 0; i < this.$refs.wheelScroll.children.length; i++) { - this.$refs.wheelScroll.children[i].style.height = `${this.$parent.$refs.indicatorMask.offsetHeight}px` - } + }, + updated () { + this.refresh() }, beforeDestroy () { this.wheels.forEach((wheel) => { @@ -58,11 +58,16 @@ export default { methods: { refresh () { if (this.refreshing) return + this.refreshing = true + for (let i = 0; i < this.$refs.wheelScroll.children.length; i++) { + this.$refs.wheelScroll.children[i].style.height = `${this.$parent.$refs.indicatorMask.offsetHeight}px` + } this.$nextTick(() => { const wheelWrapper = this.$refs.wheelWrapper if (this.wheels[0]) { this.wheels[0].refresh() + this.refreshing = false return } this.wheels[0] = new BScroll(wheelWrapper, extend({ diff --git a/packages/webpack-plugin/lib/template-compiler/compiler.js b/packages/webpack-plugin/lib/template-compiler/compiler.js index 2c565454b5..2781eee4be 100644 --- a/packages/webpack-plugin/lib/template-compiler/compiler.js +++ b/packages/webpack-plugin/lib/template-compiler/compiler.js @@ -38,7 +38,7 @@ const endTag = new RegExp(('^<\\/' + qnameCapture + '[^>]*>')) const doctype = /^]+>/i const comment = /^