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.3-style-guide-c.md

@@ -0,0 +1,489 @@
+# 优先级 C 的规则：推荐 (将选择和认知成本最小化)
+
+<div class="style-guide">
+
+<!-- 开始 -->
+
+## Props 类型与默认值 <span class="priority-a">推荐</span>
+
+**为每个 prop 显式声明类型并提供合理默认值，减少运行时类型错误。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+const props = defineProps(['name', 'count']);
+</script>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+const props = defineProps({
+    name: {
+        type: String,
+        default: ''
+    },
+    count: {
+        type: Number,
+        default: 0
+    }
+});
+</script>
+```
+
+</div>
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## 模板中保持简单表达式 <span class="priority-a">推荐</span>
+
+**模板只保留简单表达式，复杂逻辑重构到计算属性或方法中。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+{{
+  fullName.split(' ').map((word) => word[0].toUpperCase() + word.slice(1)).join(' ')
+}}
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<!-- 在模板中 -->
+{{ normalizedFullName }}
+```
+
+```js
+// 复杂表达式已经移入一个计算属性
+computed: {
+    normalizedFullName() {
+        return this.fullName.split(' ')
+            .map((word) => word[0].toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+}
+```
+
+</div>
+<!-- 结束 -->
+
+
+<!-- 开始 -->
+
+## 使用 `<script setup>` 语法糖 <span class="priority-a">推荐</span>
+
+**新组件优先使用 `<script setup>` 简化声明式写法，减少样板代码。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script>
+export default {
+    setup() {
+        const msg = 'hi';
+        return { msg };
+    }
+}
+</script>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+const msg = 'hi';
+</script>
+```
+
+</div>
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## 使用 ep- 前缀组件 <span class="priority-a">推荐</span>
+
+**PC 端基础能力优先使用框架提供的 `ep-` 前缀组件，避免直接使用组件库的 `e-` 前缀。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<e-form></e-form>
+<e-input></e-input>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<ep-form></ep-form>
+<ep-input></ep-input>
+```
+
+</div>
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## Web 工程仅作为启动入口 <span class="priority-a">推荐</span>
+
+**Web 工程保留启动和路由入口即可，业务代码在组件工程中实现。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+// web main.js
+import App from './App.vue';
+import UserCenter from './pages/user-center.vue';
+
+createApp(UserCenter).mount('#app'); // 直接写业务入口
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+// web main.js
+import App from './App.vue';
+
+createApp(App).mount('#app'); // 仅保留启动入口
+```
+
+</div>
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## 添加适当的错误处理 <span class="priority-a">推荐</span>
+
+总是需要考虑代码未按照预期运行的情况，为这种意外情况添加日志输出或其他适当处理是个良好习惯，方便遇到bug时高效的定位排查问题所在。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+ejs.device.getDeviceInfo({
+    success(result) {
+        self.statusBarHeight = parseInt(result.statusBarHeight);
+    }
+});
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+ejs.device.getDeviceInfo({
+    success(result) {
+        self.statusBarHeight = parseInt(result.statusBarHeight);
+    },
+    error: function (error) {
+        console.error(error);
+    }
+});
+```
+</div>
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## 使用全等或严格不相等 <span class="priority-a">推荐</span>
+
+双等号（`==`）将执行类型转换，三等号（`===`）做的比较与双等号相同但不进行类型转换。不建议使用宽松相等（`==`）。使用严格相等（`===`）进行比较的结果更容易预测，并且由于缺少类型强制转换可以更快地执行。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+self.tag == ''; // self.tag为0时仍为true
+self.tag != 1; // self.tag为字符串'1'时为 false
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+self.tag === ''; // self.tag为0时为false
+self.tag !== 1; // self.tag为字符串'1'时为 true
+```
+</div>
+<!-- 结束 -->
+<!-- 开始 -->
+
+## 组件/实例的选项的顺序 <span class="priority-a">推荐</span>
+
+**组件/实例的选项应该有统一的顺序。**
+
+这是我们推荐的组件选项默认顺序。它们被划分为几大类，所以你也能知道从插件里添加的新 property 应该放到哪里。
+
+1. **副作用** (触发组件外的影响)
+
+-   `el`
+
+2. **全局感知** (要求组件以外的知识)
+
+-   `name`
+-   `parent`
+
+3. **组件类型** (更改组件的类型)
+
+-   `functional`
+
+4. **模板修改器** (改变模板的编译方式)
+
+-   `delimiters`
+-   `comments`
+
+5. **模板依赖** (模板内使用的资源)
+
+-   `components`
+-   `directives`
+-   `filters`
+
+6. **组合** (向选项里合并 property)
+
+-   `extends`
+-   `mixins`
+
+7. **接口** (组件的接口)
+
+-   `inheritAttrs`
+-   `model`
+-   `props`/`propsData`
+
+8. **本地状态** (本地的响应式 property)
+
+-   `data`
+-   `computed`
+
+9. **事件** (通过响应式事件触发的回调)
+
+-   `watch`
+-   生命周期钩子 (按照它们被调用的顺序)
+    -   `beforeCreate`
+    -   `created`
+    -   `beforeMount`
+    -   `mounted`
+    -   `beforeUpdate`
+    -   `updated`
+    -   `activated`
+    -   `deactivated`
+    -   `beforeDestroy`
+    -   `destroyed`
+
+10. **非响应式的 property** (不依赖响应系统的实例 property)
+
+-   `methods`
+
+11. **渲染** (组件输出的声明式描述)
+
+-   `template`/`render`
+-   `renderError`
+<!-- 结束 -->
+
+<!-- 开始 -->
+
+## 元素 attribute 的顺序 <span class="priority-a">推荐</span>
+
+**元素 (包括组件) 的 attribute 应该有统一的顺序。**
+
+这是我们为组件选项推荐的默认顺序。它们被划分为几大类，所以你也能知道新添加的自定义 attribute 和指令应该放到哪里。
+
+1. **定义** (提供组件的选项)
+
+-   `is`
+
+2. **列表渲染** (创建多个变化的相同元素)
+
+-   `v-for`
+
+3. **条件渲染** (元素是否渲染/显示)
+
+-   `v-if`
+-   `v-else-if`
+-   `v-else`
+-   `v-show`
+-   `v-cloak`
+
+4. **渲染方式** (改变元素的渲染方式)
+
+-   `v-pre`
+-   `v-once`
+
+5. **全局感知** (需要超越组件的知识)
+
+-   `id`
+
+6. **唯一的 attribute** (需要唯一值的 attribute)
+
+-   `ref`
+-   `key`
+
+7. **双向绑定** (把绑定和事件结合起来)
+
+-   `v-model`
+
+8. **其它 attribute** (所有普通的绑定或未绑定的 attribute)
+
+9. **事件** (组件事件监听器)
+
+-   `v-on`
+
+10. **内容** (覆写元素的内容)
+
+-   `v-html`
+-   `v-text`
+<!-- 结束 --><!-- 开始 -->
+
+## 组件/实例选项中的空行 <span class="priority-a">推荐</span>
+
+**你可能想在多个 property 之间增加一个空行，特别是在这些选项一屏放不下，需要滚动才能都看到的时候。**
+
+当你的组件开始觉得密集或难以阅读时，在多个 property 之间添加空行可以让其变得容易。在一些诸如 Vim 的编辑器里，这样格式化后的选项还能通过键盘被快速导航。
+
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+props: {
+    value: {
+        type: String,
+        required: true
+    },
+
+    focused: {
+        type: Boolean,
+        default: false
+    },
+
+    label: String,
+    icon: String
+},
+
+computed: {
+    formattedValue: function () {
+        // ...
+    },
+
+    inputClasses: function () {
+        // ...
+    }
+}
+```
+
+</div>
+<!-- 结束 --><!-- 开始 -->
+
+##  单文件组件的顶级元素的顺序 <span class="priority-a">推荐</span>
+
+**`单文件组件`应该总是让 `<script>`、`<template>` 和 `<style>` 标签的顺序保持一致。且 `<style>` 要放在最后，因为另外两个标签至少要有一个。**
+
+
+<div class="style-example example-bad">
+
+### 反例：
+
+``` html
+<style>/* ... */</style>
+<script>/* ... */</script>
+<template>...</template>
+```
+
+``` html
+<!-- ComponentA.vue -->
+<script>/* ... */</script>
+<template>...</template>
+<style>/* ... */</style>
+
+<!-- ComponentB.vue -->
+<template>...</template>
+<script>/* ... */</script>
+<style>/* ... */</style>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+``` html
+<!-- ComponentA.vue -->
+<template>...</template>
+<script>/* ... */</script>
+<style>/* ... */</style>
+
+<!-- ComponentB.vue -->
+<template>...</template>
+<script>/* ... */</script>
+<style>/* ... */</style>
+```
+
+</div>
+<!-- 结束 -->
+
+</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>