m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/002-/350/247/204/350/214/203/344/270/216/346/250/241/345/274/217/003.4-style-guide-d.md

@@ -0,0 +1,372 @@
+# 优先级 D 的规则：谨慎使用 (有潜在危险的模式)
+
+<div class="style-guide">
+
+## 环境判断不完整 <span class="priority-a">潜在危险</span>
+
+**移动设备 os 判断不完整，仅通过`if-else` 判断可能会导致错误的结果。**
+
+过去在判断`安卓`、`iOS`操作系统时，常见的做法是通过 `if` 语句判断其中一个操作系统，而 `else` 语句默认处理其他所有情况。
+
+但这种方式存在潜在风险，特别是在出现像鸿蒙（HarmonyOS）这样的新操作系统时。仅靠 `if-else` 结构判断可能会遗漏对新系统的支持，导致功能异常。
+
+因此在判断时，明确区分每个可能的操作系统，并为未来可能出现的新系统预留判断逻辑。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+if (ejs.os.ios) {
+    // xxx
+} else {
+    // xxx
+}
+```
+
+```js
+jsApiList: [
+    {
+        moduleName: ejs.os.android ? 'com.xxx.xxx' : 'ZDYxxx',
+    },
+];
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+if (ejs.os.ios) {
+    // xxx
+} else if (ejs.os.android) {
+    // xxx
+} else if (ejs.os.harmonyOs) {
+    // xxx
+} else {
+    // 处理未知操作系统
+}
+```
+
+```js
+jsApiList: [
+    {
+        moduleName: ejs.os.android ? 'com.xxx.xxx' : ejs.os.ios ? 'ZDYxxx' : ejs.os.harmonyOs ? 'xxx' : 'unknown',
+    },
+];
+```
+
+</div>
+
+<!-- 开始 -->
+
+## 判断 APP 版本号 <span class="priority-a">潜在危险</span>
+
+在产品开发过程，应该避免判断 APP 版本号进行功能的开关。项目 APP 版本号不一定与产品的版本号对应匹配的，容易造成潜在危险。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+ejs.runtime.getAppVersion({
+    success: function (result) {
+        let version = result.version || '';
+
+        if (version >= '4.4.2') {
+            jsApiLists = [
+                {
+                    moduleName: ejs.os.android ? 'MobileshieldNewApi' : 'ZDEJSApi',
+                },
+            ];
+        } else if (version > '3.1.1') {
+            jsApiLists = [
+                {
+                    moduleName: ejs.os.android ? 'com.epoint.app.plugin.MobileshieldNewApi' : 'ZDEJSApi',
+                },
+            ];
+        }
+    },
+});
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+// 根据具体的功能需求，使用更合适的判断 API
+if (ejs.os.miniH5) {
+    jsApiLists = [
+        {
+            moduleName: ejs.os.android ? 'MobileshieldNewApi' : ejs.os.ios ? 'ZDYxxx' : ejs.os.harmonyOs ? 'xxx' : 'unknown',
+        },
+    ];
+} else if (ejs.os.ejs) {
+    jsApiLists = [
+        {
+            moduleName: ejs.os.android ? 'com.xxx.xxx' : ejs.os.ios ? 'ZDYxxx' : ejs.os.harmonyOs ? 'xxx' : 'unknown',
+        },
+    ];
+}
+```
+
+</div>
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## 引入未使用的组件或文件 <span class="priority-a">潜在危险</span>
+
+引入未使用到的组件影响代码可读性，也可能产生未知的副作用，增大代码体积，建议只引入必需的组件或文件，以保持代码简洁。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<template>
+    <van-button basic>保存</van-button>
+</template>
+```
+
+```js
+import minirefresh from '@components/minirefresh';
+import vanButton from '@components/button';
+export default {
+    components: {
+        minirefresh, // 该组件并未用到
+        vanButton,
+    },
+};
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<template>
+    <van-button basic>保存</van-button>
+</template>
+```
+
+```js
+import vanButton from '@components/button';
+export default {
+    components: {
+        vanButton,
+    },
+};
+```
+
+</div>
+<!-- 结束 -->
+
+## 没有在 `v-if`/`v-else-if`/`v-else` 中使用 `key` <span class="priority-a">潜在危险</span>
+
+**如果一组 `v-if` + `v-else` 的元素类型相同，最好使用 `key` (比如两个 `<div>` 元素)。**
+
+默认情况下，Vue 会尽可能高效的更新 DOM。这意味着其在相同类型的元素之间切换时，会修补已存在的元素，而不是将旧的元素移除然后在同一位置添加一个新元素。如果本不相同的元素被识别为相同，则会出现[意料之外的结果](https://codesandbox.io/s/github/vuejs/v2.vuejs.org/tree/master/src/v2/examples/vue-20-priority-d-rules-unintended-consequences)。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<div v-if="error">错误：{{ error }}</div>
+<div v-else>{{ results }}</div>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<div v-if="error" key="search-status">错误：{{ error }}</div>
+<div v-else key="search-results">{{ results }}</div>
+```
+
+</div>
+
+## `scoped`中的元素选择器 <span class="priority-a">潜在危险</span>
+
+**元素选择器应该避免在 `scoped` 中出现。**
+
+在 `scoped` 样式中，类选择器比元素选择器更好，因为大量使用元素选择器是很慢的。
+
+<details>
+<summary>
+  <h4>详解</h4>
+</summary>
+
+为了给样式设置作用域，Vue 会为元素添加一个独一无二的 attribute，例如 `data-v-f3f3eg9`。然后修改选择器，使得在匹配选择器的元素中，只有带这个 attribute 才会真正生效 (比如 `button[data-v-f3f3eg9]`)。
+
+问题在于大量的元素和 attribute 组合的选择器 (比如 `button[data-v-f3f3eg9]`) 会比类和 attribute 组合的选择器 (比如 `.btn-close[data-v-f3f3eg9]`) 慢，所以应该尽可能选用类选择器。
+
+</details>
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<template>
+    <button>X</button>
+</template>
+
+<style scoped>
+    button {
+        background-color: red;
+    }
+</style>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<template>
+    <button class="btn btn-close">X</button>
+</template>
+
+<style scoped>
+    .btn-close {
+        background-color: red;
+    }
+</style>
+```
+
+</div>
+
+## 隐性的父子组件通信 <span class="priority-a">潜在危险</span>
+
+**应该优先通过 prop 和事件进行父子组件之间的通信，而不是 `this.$parent` 或变更 prop。**
+
+一个理想的 Vue 应用是 prop 向下传递，事件向上传递的。遵循这一约定会让你的组件更易于理解。然而，在一些边界情况下 prop 的变更或 `this.$parent` 能够简化两个深度耦合的组件。
+
+问题在于，这种做法在很多*简单*的场景下可能会更方便。但请当心，不要为了一时方便 (少写代码) 而牺牲数据流向的简洁性 (易于理解)。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+Vue.component('TodoItem', {
+    props: {
+        todo: {
+            type: Object,
+            required: true,
+        },
+    },
+    template: '<input v-model="todo.text">',
+});
+```
+
+```js
+Vue.component('TodoItem', {
+    props: {
+        todo: {
+            type: Object,
+            required: true,
+        },
+    },
+    methods: {
+        removeTodo() {
+            var vm = this;
+            vm.$parent.todos = vm.$parent.todos.filter(function (todo) {
+                return todo.id !== vm.todo.id;
+            });
+        },
+    },
+    template: `
+        <span>
+            {{ todo.text }}
+            <button @click="removeTodo">
+                X
+            </button>
+        </span>
+    `,
+});
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+Vue.component('TodoItem', {
+    props: {
+        todo: {
+            type: Object,
+            required: true,
+        },
+    },
+    template: `
+        <input
+            :value="todo.text"
+            @input="$emit('input', $event.target.value)"
+        >
+    `,
+});
+```
+
+```js
+Vue.component('TodoItem', {
+    props: {
+        todo: {
+            type: Object,
+            required: true,
+        },
+    },
+    template: `
+        <span>
+            {{ todo.text }}
+            <button @click="$emit('delete')">
+                X
+            </button>
+        </span>
+    `,
+});
+```
+
+</div>
+
+</div>
+<style>
+.priority-a {
+    color: #f44336;
+    font-size: 12px
+}
+.style-guide summary {
+    display: list-item;
+    cursor: pointer;
+    padding: 1.6em;
+    margin: -1.6em;
+    outline: none;
+}
+.style-guide details, .style-guide .style-enforcement {
+    background-color: #eee;
+}
+.style-guide details h4 {
+    display: inline-block;
+}
+.style-example, .style-guide details, .style-guide .style-enforcement {
+    border-radius: 2px;
+    margin: 1.6em 0;
+    padding: 12px;
+}
+.style-example.example-bad {
+        background: #f7e8e8;
+}
+.style-guide .style-example.example-good {
+    background: #eaedec;
+}
+</style>

package/docs/m8mpdoc-develop/003-/345/205/270/345/236/213/346/241/210/344/276/213/003-/345/210/227/350/241/250/350/257/246/346/203/205.md

@@ -0,0 +1,247 @@
+# 列表详情
+
+## 前言
+
+我们使用 `M8.3移动前端框架` 进行下拉刷新列表、详情页面的开发
+
+已根据 教程 章节了解 `M8` 开发的思路
+
+## 新建模块
+
+模块代码统一放在 `src/pages` 下，每个模块应用对应一个文件夹。
+
+我们在此路径下新建文件夹，例如 `m8demo`。
+
+在 `m8demo` 文件夹下新建 `router.js` 文件，如下：
+
+`src/pages/m8demo/router.js` :
+
+```js
+/**
+ * router.js无需import组件，需要path路径与vue组件名称保持匹配。
+ * routers数组下有效参数只有path与style。
+ * 构建时会自动将模块下的路由配置合并到pages.json内。
+ */
+
+// 定义路由规则，url匹配path时，加载component组件页面
+const routes = [
+    {
+        path: 'pages/m8demo/list',
+        style: {
+            navigationBarTitleText: '列表页面',
+        },
+    },
+    {
+        path: 'pages/m8demo/detail',
+        style: {
+            navigationBarTitleText: '详情页面',
+        },
+    },
+];
+
+// 导出路由文件
+export default routes;
+```
+
+## 列表页面
+
+接下来我们在 `m8demo` 下新建 `list.vue` 组件页面
+
+`list.vue` :
+
+```js
+<!-- template部分 -->
+<template>
+    <!-- template内只能有一个根节点 -->
+    <view class="container"></view>
+</template>
+
+<!-- js部分 -->
+<script></script>
+
+<!-- css部分 -->
+<style scoped></style>
+```
+
+`M8`的 `easycom` 机制，将组件引用进一步优化，开发者只管使用，无需在 `JS` 里额外导入和注册。
+
+```js
+<template>
+    <view class="container">
+        <em-minirefresh
+            ref="scrollPull"
+            :initPageIndex="initPageIndex"
+            :page-size="pageSize"
+            :url="url"
+            :request-data="dataRequest"
+            :change-data="dataChange"
+        >
+            <template v-slot:default="{ listData }">
+            <!-- 此处template内为列表list元素，listData为dataChange处理后的接口返回数据 -->
+                <em-cell v-for="(item, index) in listData" :key="index" :title="item.title" @click="itemClick(item)" />
+            </template>
+        </em-minirefresh>
+    </view>
+</template>
+
+<script>
+export default {
+    // 定义用到的数据，在template中使用{{ }}包裹，自动实现绑定
+    data() {
+        return {
+            // 请求的url
+            url: `${Config.serverUrl}/rest/list`,
+            // 接口请求的初始页面
+            initPageIndex: 0,
+            // 每次请求的分页大小
+            pageSize: 10
+        };
+    },
+    // 计算属性
+    computed: {
+
+    },
+    // 侦听属性
+    watch: {
+
+    },
+    // 实例数据创建完成后调用
+    created() {
+
+    },
+    // 实例DOM被挂载后调用
+    mounted() {
+
+    },
+    methods: {
+        // 请求参数函数
+        dataRequest(currPage, pageSize) {
+            const data = {
+                // 当前搜索的第几页，数字类型
+                currentpageindex: currPage,
+                // 每页显示记录条数，数字类型
+                pagesize: pageSize
+            };
+            const requestData = {
+                params: JSON.stringify(data)
+            };
+
+            return requestData;
+        },
+        // 修改数据返回参数
+        dataChange(res) {
+            let data;
+
+            if (res && res.status && res.status.code && res.status.code === 1) {
+                data = res.custom.infolist;
+            } else {
+                console.error('接口返回参数错误');
+            }
+
+            return data;
+        },
+        // 列表模板绑定的点击事件函数
+        itemClick(item) {
+              ejs.page.open({
+                    pageUrl: "./detail",
+                    pageStyle: 1,
+                    orientation: 1,
+                    data: {
+                        id: item.id,
+                    },
+                    success: function (result) {},
+                });
+        }
+    }
+};
+</script>
+
+<!-- css部分 -->
+<style lang="scss" scoped>
+.container {
+    height: 100vh;
+}
+</style>
+
+```
+
+## 详情页面
+
+接下来我们在 `m8demo` 下新建 `detail.vue` 组件页面
+
+`detail.vue` :
+
+```js
+<!-- html部分 -->
+<template>
+    <div class="container">
+        <h1>{{ title }}</h1>
+        <div v-html="content"></div>
+    </div>
+</template>
+
+<!-- js部分 -->
+<script>
+    export default {
+        name: "detail",
+        components: {},
+        // 定义用到的数据，在template中使用{{ }}包裹，自动实现绑定
+        data() {
+            return {
+                title: "",
+                content: "",
+            };
+        },
+        // 计算属性
+        computed: {
+
+        },
+        // 侦听属性
+        watch: {
+
+        },
+        // 实例数据创建完成后调用
+        created() {
+            const id = Util.getExtraDataByKey("id") || ""
+            this.getDetail(id);
+        },
+        // 实例DOM被挂载后调用
+        mounted() {
+
+        },
+        methods: {
+            getDetail(id) {
+                let _this = this;
+
+                Util.ajax({
+                    url: `${Config.serverUrl}/rest/detail`,
+                    data: {
+                        params: JSON.stringify({
+                            guid: id,
+                        }),
+                    },
+                })
+                    .then((result) => {
+                        if (
+                            result &&
+                            result.status &&
+                            result.status.code === 1
+                        ) {
+                            _this.title = result.custom.info.title;
+                            _this.content = result.custom.info.data;
+                        }
+                    })
+                    .catch((err) => {
+                        console.error(err);
+                    });
+            },
+        }
+    };
+</script>
+
+<!-- css部分 -->
+<style lang="scss" scoped></style>
+
+```
+
+一个简单的列表详情页面就完成了