m8-framework-mcp 1.0.0 → 1.0.1

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

@@ -1,489 +0,0 @@
-# 优先级 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>