@darkchest/wck 0.0.1

package/readme.md

@@ -0,0 +1,774 @@
+# @darkchest/wck
+
+## 🌉 Vue 单文件组件 (SFC) 转web-component组件桥接器
+
+`@darkchest/wck` (全称@darkchest/WebComponentKit)是一个通过包装Vue单文件组件 (SFC) 并将它转换为通用的web-component组件的解决方案。
+
+## 前言
+
+  总会有一些场景, 我们无法使用现代化的框架系统.
+
+  在习惯了现代化数据驱动的开发模式下再次回到操作dom来更新UI的模式(没有了事件, scss, 模板, 数据监听等), 的确让人感到非常不便. 并且因为全局作用域的关系, 我们很容易碰上变量, 样式的冲突导致的预期之外的bug. 更不幸的是由于没有固定的模板结构, 导致我们的代码有更大概率出现面条化的风险.
+  
+  所以, 如果能够以vue2的options格式去写web-component, 在开发阶段借助vue的ide插件帮助我们进行代码提示及错误警告, 避免代码面条化. 在使用时又以web-component的方式去使用, 将组件内部的逻辑封装在shadowDOM中, 对象只暴露出必要的props和methods, 以及一些events, 这就足够应用大部分的需求了. 这不就是应对困境的最好方案了吗?
+
+  这也是我开发@darkchest/wck的初衷!
+
+  实际上在这之前我开发过几个版本的解决方案:
+    1. 通过vue3官方提供的方案构建web-component组件, 最终打包了vue3的代码到组件中导致整个组件体积巨形膨胀(一个小组件体积上涨到90kb+), 并且回头考虑到既然都直接上了vue3, 那么再写web-component的组件好像没什么意义, 此方案废弃.
+
+    2. 通过lit来封装web-component组件, 整体来说是很顺利的. 但是在开发过程中, 由于要使用装饰器(不太熟悉ts), 且要自行实现render, 整个开发过程不太舒适并且没有代码提示, 最终打包后体积大约为30kb+, 此方案搁置.
+
+    3. 通过官方提供的@vue/compiler-sfc解析vue单文件组件 (SFC), 并将其script部分进行转换标准的web-component组件的逻辑部分(已完成), 但在解析template部分时出现重大问题, 由于template部分解析出来属于vue特有的抽象语法树, 手上又没有详尽的资料又不想去啃源码, 导致template部分无法转换方案被废弃.
+
+    4. 最终, 我找到了[petite-vue](https://github.com/vuejs/petite-vue), 根据网络描述, 它是由 Vue.js 团队推出的重量仅约6KB的小型Vue版本，专为网页上的渐进式增强设计。 它保留了Vue的核心模板语法与响应式机制，但特别优化用于在已有的HTML页面上增添少量交互效果. 经过测试它无需经过编译即可直接支持template语法(v-for, v-if, v-model, v-html, @click等), 允许直接在dom上应用template语法且直接生效. 于是, 将方案3中的script转换与petite-vue的模板解析合并, 并抹平与标准web-component的差异后的最终方案终于完成(与标准版vue仍有差距, 但是核心功能已实现, 用于开发web组件应该是足够了), 并且最小体积降至16kb(未进行gzip压缩).
+
+  祝好!~
+
+## ✨ 核心特性
+
+  - ✅ 支持props属性(注意vue中允许使用大驼峰和小驼峰定义属性, 但是web组件中只允许小写, 所以vue中定义的属性在编译时会转成小写和中划线连字符形式)
+  - ✅ 支持$el, $parent, $children, $root属性
+  - ✅ 支持$emit事件
+  - ✅ 支持methods方法
+  - ✅ 支持compputed属性
+  - ✅ 支持watch属性
+  - ✅ 支持slot匿名和具名插槽
+  - ✅ 支持mounted/onMounted, destroyed/unmounted/onUnmounted生命周期
+
+### 关于props大小写问题
+  由于vue中定义props是允许大小写字母的.而web组件只允许小写字母(包含中划线), 所以当我们在vue组件中定义一个带有大写字母的属性时(例如appTitle), 那么我们将它转成web组件后, 插件会在web组件中将appTitle声明为apptitle和app-title两种形式, 所以这俩种写法最后都有效: <todo-list apptitle="*我的清单*"></todo-list>和<todo-list app-title="*我的清单*"></todo-list>.
+
+### 关于属性, 方法, 事件, 生命周期钩子
+  我们通过props, methods, 定义的属性和方法, 都会直接通过web组件暴露出去. 页面上可以直接操作调用并实现双向同步的逻辑.
+  如果我们需要对外透出自定义事件, 也可以在组件内通过$emit(name, data)来触发事件, 这样在页面上可以使用on/off/once方法来监听该事件.
+  所有组件都会默认触发mounted/unmounted两个生命周期事件方便监听并进行某些初始化操作.
+  可以定义onMounted/onUnmounted生命周期钩子来监听组件的初始化与销毁事件.
+
+## 🛠️ 安装与配置
+
+### 1. 安装依赖
+
+```bash
+npm install @darkchest/wck
+```
+
+### 2. 使用示例(重要: 请参考TodoList.vue文件示例, 该文件中已包含所有核心功能)
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import path from 'path';
+import wck from '@darkchest/wck';
+
+export default defineConfig({
+  plugins: [
+    wck(), // 设置转换插件
+  ],
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, 'src/index.js'),
+      name: 'MyLib', // 在iife和umd模式下必填
+      formats: ['es', 'iife', 'umd'],
+      fileName: (format, name) => `${name}.${format}.min.js`
+    },
+  },
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'), // 配置别名
+    }
+  }
+})
+```
+
+```javascript
+// src/index.js
+import TodoList from './src/components/TodoList.vue';
+
+lit.component('todo-list', TodoList);
+// 注意: web-component的标签名必须为中划线命名(有且至少一个中划线), 否则无法成功注册.
+```
+
+```vue
+// src/components/TodoList.vue
+
+<template>
+  <div id="app">
+    <div class="todo-container">
+      <!-- Header Slot -->
+      <header>
+        <slot name="header">
+          <h1 class="app-title">{{ appTitle }}</h1>
+          <p class="app-description">使用 Vue2 实现的 Todo List 应用</p>
+        </slot>
+      </header>
+
+      <!-- Add Todo Form -->
+      <div class="add-todo">
+        <input
+          type="text"
+          v-model="newTodo"
+          placeholder="请输入待办事项..."
+          @keyup.enter="addTodo"
+          class="todo-input"
+        />
+        <button @click="addTodo" class="add-btn">添加</button>
+        <button @click="clearCompleted" class="clear-btn">清除已完成</button>
+      </div>
+
+      <!-- Filter Controls -->
+      <div class="filter-controls">
+        <button 
+          @click="filter = 'all'"
+          :class="{ active: filter === 'all' }"
+          class="filter-btn"
+        >
+          全部 ({{ totalTodos }})
+        </button>
+        <button 
+          @click="filter = 'active'"
+          :class="{ active: filter === 'active' }"
+          class="filter-btn"
+        >
+          未完成 ({{ activeTodosCount }})
+        </button>
+        <button 
+          @click="filter = 'completed'"
+          :class="{ active: filter === 'completed' }"
+          class="filter-btn"
+        >
+          已完成 ({{ completedTodosCount }})
+        </button>
+      </div>
+
+      <!-- Todo List -->
+      <div class="todo-list">
+        <div v-if="filteredTodos.length === 0" class="empty-state">
+          <p v-if="todos.length === 0">暂无待办事项，请添加一个吧！</p>
+          <p v-else>没有{{ filter === 'active' ? '未完成' : '已完成' }}的事项</p>
+        </div>
+        
+        <div 
+          v-for="todo in filteredTodos" 
+          :key="todo.id"
+          class="todo-item"
+          :class="{ completed: todo.completed }"
+        >
+          <div class="todo-content">
+            <input 
+              type="checkbox" 
+              v-model="todo.completed"
+              class="todo-checkbox"
+              :id="'todo-' + todo.id"
+            />
+            <label :for="'todo-' + todo.id" class="todo-text">
+              <span>{{ todo.text }}</span>
+              <span class="todo-date">{{ formatDate(todo.createdAt) }}</span>
+            </label>
+          </div>
+          <div class="todo-actions">
+            <button @click="editTodo(todo)" class="edit-btn">编辑</button>
+            <button @click="deleteTodo(todo.id)" class="delete-btn">删除</button>
+          </div>
+        </div>
+      </div>
+
+      <!-- Stats -->
+      <div class="stats">
+        <p v-if="todos.length > 0">
+          已完成 {{ completedTodosCount }} / 总共 {{ totalTodos }} 个待办事项
+          <span v-if="hasCompletedTodos" class="completion-rate">
+            (完成率: {{ completionRate }}%)
+          </span>
+        </p>
+        
+        <!-- Progress Bar Slot -->
+        <slot name="progress">
+          <div class="progress-container">
+            <div class="progress-bar" :style="{ width: completionRate + '%' }"></div>
+          </div>
+        </slot>
+      </div>
+
+      <!-- Footer Slot -->
+      <footer>
+        <slot name="footer">
+          <p class="footer-text">双击事项可标记为完成/未完成</p>
+          <p class="footer-text">使用 Vue2 实现 - 包含 Props, Data, Methods, Slots, Watch, Computed, 生命周期</p>
+        </slot>
+      </footer>
+    </div>
+
+    <!-- Edit Modal -->
+    <div v-if="editingTodo" class="modal-overlay" @click="cancelEdit">
+      <div class="modal" @click.stop>
+        <h3>编辑待办事项</h3>
+        <input 
+          type="text" 
+          v-model="editingTodo.text" 
+          @keyup.enter="saveEdit"
+          class="edit-input"
+        />
+        <div class="modal-actions">
+          <button @click="saveEdit" class="save-btn">保存</button>
+          <button @click="cancelEdit" class="cancel-btn">取消</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'TodoApp',
+  
+  // Props 示例
+  props: {
+    initialTodos: {
+      type: [Array, Object],
+      default: () => []
+    },
+    appTitle: {
+      type: String,
+      default: '我的待办清单'
+    },
+    enableLocalStorage: {
+      type: Boolean,
+      default: true
+    }
+  },
+  
+  // Data 示例
+  data() {
+    return {
+      newTodo: '',
+      todos: [],
+      filter: 'all',
+      editingTodo: null,
+      lastTodoId: 0
+    };
+  },
+  
+  // Computed 示例
+  computed: {
+    // 计算过滤后的待办事项
+    filteredTodos() {
+      switch (this.filter) {
+        case 'active':
+          return this.todos.filter(todo => !todo.completed);
+        case 'completed':
+          return this.todos.filter(todo => todo.completed);
+        default:
+          return this.todos;
+      }
+    },
+    
+    // 计算未完成事项数量
+    activeTodosCount() {
+      return this.todos.filter(todo => !todo.completed).length;
+    },
+    
+    // 计算已完成事项数量
+    completedTodosCount() {
+      return this.todos.filter(todo => todo.completed).length;
+    },
+    
+    // 计算总事项数量
+    totalTodos() {
+      return this.todos.length;
+    },
+    
+    // 计算完成率
+    completionRate() {
+      if (this.totalTodos === 0) return 0;
+      return Math.round((this.completedTodosCount / this.totalTodos) * 100);
+    },
+    
+    // 检查是否有已完成事项
+    hasCompletedTodos() {
+      return this.completedTodosCount > 0;
+    }
+  },
+  
+  // Watch 示例
+  watch: {
+    // 监听 todos 变化并保存到 localStorage
+    todos: {
+      handler(newTodos, oldTodos) {
+        if (this.enableLocalStorage) {
+          localStorage.setItem('vue-todos', JSON.stringify(newTodos));
+        }
+        
+        // 发送事件给父组件（如果需要）
+        this.$emit('todos-updated', newTodos);
+      },
+      deep: true
+    },
+    
+    // 监听 filter 变化
+    filter(newFilter, oldFilter) {
+      console.log('过滤器已更改为: '+newFilter);
+    }
+  },
+  
+  // Methods 示例
+  methods: {
+    // 添加新的待办事项
+    addTodo() {
+      if (this.newTodo.trim() === '') return;
+      
+      this.todos.push({
+        id: ++this.lastTodoId,
+        text: this.newTodo.trim(),
+        completed: false,
+        createdAt: new Date()
+      });
+      
+      this.newTodo = '';
+      console.log('已添加新的待办事项');
+    },
+    
+    // 删除待办事项
+    deleteTodo(id) {
+      const index = this.todos.findIndex(todo => todo.id === id);
+      if (index !== -1) {
+        this.todos.splice(index, 1);
+        console.log('已删除待办事项 ID: '+id);
+      }
+    },
+    
+    // 编辑待办事项
+    editTodo(todo) {
+      this.editingTodo = { ...todo };
+    },
+    
+    // 保存编辑
+    saveEdit() {
+      if (this.editingTodo && this.editingTodo.text.trim() !== '') {
+        const index = this.todos.findIndex(todo => todo.id === this.editingTodo.id);
+        if (index !== -1) {
+          this.$set(this.todos, index, { ...this.editingTodo });
+          console.log('已更新待办事项 ID: '+this.editingTodo.id);
+        }
+      }
+      this.editingTodo = null;
+      // 已知这里会报错, 这是petite-vue内部的bug, 因为并不影响使用, 所以我不打算修复(没有petite-vue源码).
+      // 感觉这是因为v-if的优先级没有v-model高导致的, 所以我们可以通过额外设置一个开关变量来绕开这个报错, 只要不设置对象为null就行.
+    },
+    
+    // 取消编辑
+    cancelEdit() {
+      this.editingTodo = null;
+      // 已知这里会报错, 这是petite-vue内部的bug, 因为并不影响使用, 所以我不打算修复(没有petite-vue源码).
+      // 感觉这是因为v-if的优先级没有v-model高导致的, 所以我们可以通过额外设置一个开关变量来绕开这个报错, 只要不设置对象为null就行.
+    },
+    
+    // 清除已完成事项
+    clearCompleted() {
+      const originalLength = this.todos.length;
+      this.todos = this.todos.filter(todo => !todo.completed);
+      const clearedCount = originalLength - this.todos.length;
+      console.log('已清除 '+clearedCount+' 个已完成事项');
+    },
+    
+    // 格式化日期
+    formatDate(date) {
+      return new Date(date).toLocaleDateString('zh-CN', {
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit'
+      });
+    }
+  },
+  
+  // 生命周期钩子示例
+  created() {
+    console.log('TodoApp 组件已创建');
+    
+    // 从 props 或 localStorage 初始化 todos
+    if (this.initialTodos && this.initialTodos.length > 0) {
+      this.todos = [...this.initialTodos];
+      this.lastTodoId = Math.max(...this.initialTodos.map(todo => todo.id), 0);
+    } else if (this.enableLocalStorage) {
+      const savedTodos = localStorage.getItem('vue-todos');
+      if (savedTodos) {
+        try {
+          this.todos = JSON.parse(savedTodos);
+          this.lastTodoId = Math.max(...this.todos.map(todo => todo.id), 0);
+          console.log('从 localStorage 加载待办事项');
+        } catch (e) {
+          console.error('解析保存的待办事项失败:', e);
+        }
+      }
+    }
+  },
+  
+  mounted() {
+    console.log('TodoApp 组件已挂载到 DOM');
+    
+    // 为每个待办事项添加双击切换完成状态的功能
+    this.$nextTick(() => {
+      const todoItems = document.querySelectorAll('.todo-item');
+      todoItems.forEach(item => {
+        item.addEventListener('dblclick', () => {
+          const todoId = parseInt(item.dataset.id);
+          const todoIndex = this.todos.findIndex(todo => todo.id === todoId);
+          if (todoIndex !== -1) {
+            this.todos[todoIndex].completed = !this.todos[todoIndex].completed;
+            console.log('双击切换待办事项状态 ID: '+todoId);
+          }
+        });
+      });
+    });
+  },
+  
+  beforeUpdate() {
+    console.log('TodoApp 组件即将更新');
+  },
+  
+  updated() {
+    console.log('TodoApp 组件已更新');
+  },
+  
+  beforeDestroy() {
+    console.log('TodoApp 组件即将销毁');
+  },
+  
+  destroyed() {
+    console.log('TodoApp 组件已销毁');
+  }
+};
+</script>
+
+<style lang="scss" scoped>
+#app {
+  font-family: 'Avenir', Helvetica, Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  color: #2c3e50;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+.todo-container {
+  background: white;
+  border-radius: 10px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
+  padding: 30px;
+}
+
+header {
+  text-align: center;
+  margin-bottom: 30px;
+  border-bottom: 1px solid #eee;
+  padding-bottom: 20px;
+}
+
+.app-title {
+  color: #42b983;
+  font-size: 2.5rem;
+  margin-bottom: 10px;
+}
+
+.app-description {
+  color: #7f8c8d;
+  font-size: 1rem;
+}
+
+.add-todo {
+  display: flex;
+  gap: 10px;
+  margin-bottom: 20px;
+}
+
+.todo-input {
+  flex: 1;
+  padding: 12px 15px;
+  border: 2px solid #e0e0e0;
+  border-radius: 6px;
+  font-size: 16px;
+  transition: border-color 0.3s;
+}
+
+.todo-input:focus {
+  border-color: #42b983;
+  outline: none;
+}
+
+.add-btn, .clear-btn {
+  padding: 12px 20px;
+  border: none;
+  border-radius: 6px;
+  font-weight: bold;
+  cursor: pointer;
+  transition: all 0.3s;
+}
+
+.add-btn {
+  background-color: #42b983;
+  color: white;
+}
+
+.add-btn:hover {
+  background-color: #3aa876;
+}
+
+.clear-btn {
+  background-color: #f0f0f0;
+  color: #333;
+}
+
+.clear-btn:hover {
+  background-color: #e0e0e0;
+}
+
+.filter-controls {
+  display: flex;
+  gap: 10px;
+  margin-bottom: 25px;
+}
+
+.filter-btn {
+  flex: 1;
+  padding: 10px;
+  background-color: #f8f9fa;
+  border: 1px solid #dee2e6;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: all 0.3s;
+}
+
+.filter-btn.active {
+  background-color: #42b983;
+  color: white;
+  border-color: #42b983;
+}
+
+.filter-btn:hover:not(.active) {
+  background-color: #e9ecef;
+}
+
+.todo-list {
+  margin-bottom: 25px;
+}
+
+.empty-state {
+  text-align: center;
+  padding: 40px 20px;
+  color: #95a5a6;
+  font-style: italic;
+}
+
+.todo-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 15px;
+  border-bottom: 1px solid #f0f0f0;
+  transition: all 0.3s;
+  border-radius: 6px;
+  margin-bottom: 8px;
+  background-color: #f9f9f9;
+}
+
+.todo-item:hover {
+  background-color: #f0f0f0;
+  transform: translateY(-2px);
+}
+
+.todo-item.completed {
+  opacity: 0.8;
+  background-color: #f0f9f0;
+}
+
+.todo-content {
+  display: flex;
+  align-items: center;
+  gap: 15px;
+  flex: 1;
+}
+
+.todo-checkbox {
+  width: 20px;
+  height: 20px;
+  cursor: pointer;
+}
+
+.todo-text {
+  flex: 1;
+  cursor: pointer;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.todo-item.completed .todo-text span:first-child {
+  text-decoration: line-through;
+  color: #95a5a6;
+}
+
+.todo-date {
+  font-size: 0.8rem;
+  color: #95a5a6;
+}
+
+.todo-actions {
+  display: flex;
+  gap: 8px;
+}
+
+.edit-btn, .delete-btn {
+  padding: 6px 12px;
+  border: none;
+  border-radius: 4px;
+  font-size: 0.9rem;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.edit-btn {
+  background-color: #f0f0f0;
+  color: #333;
+}
+
+.edit-btn:hover {
+  background-color: #e0e0e0;
+}
+
+.delete-btn {
+  background-color: #ff6b6b;
+  color: white;
+}
+
+.delete-btn:hover {
+  background-color: #ff5252;
+}
+
+.stats {
+  margin-top: 25px;
+  padding-top: 20px;
+  border-top: 1px solid #eee;
+  color: #7f8c8d;
+}
+
+.completion-rate {
+  color: #42b983;
+  font-weight: bold;
+}
+
+.progress-container {
+  height: 10px;
+  background-color: #f0f0f0;
+  border-radius: 5px;
+  margin-top: 10px;
+  overflow: hidden;
+}
+
+.progress-bar {
+  height: 100%;
+  background-color: #42b983;
+  border-radius: 5px;
+  transition: width 0.5s ease;
+}
+
+footer {
+  margin-top: 30px;
+  padding-top: 20px;
+  border-top: 1px solid #eee;
+  text-align: center;
+  color: #95a5a6;
+  font-size: 0.9rem;
+}
+
+.footer-text {
+  margin: 5px 0;
+}
+
+/* 编辑模态框样式 */
+.modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: rgba(0, 0, 0, 0.5);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  z-index: 1000;
+}
+
+.modal {
+  background-color: white;
+  padding: 30px;
+  border-radius: 10px;
+  width: 90%;
+  max-width: 500px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.2);
+}
+
+.modal h3 {
+  margin-top: 0;
+  margin-bottom: 20px;
+  color: #2c3e50;
+}
+
+.edit-input {
+  width: 100%;
+  padding: 12px 15px;
+  border: 2px solid #42b983;
+  border-radius: 6px;
+  font-size: 16px;
+  margin-bottom: 20px;
+}
+
+.modal-actions {
+  display: flex;
+  gap: 10px;
+  justify-content: flex-end;
+}
+
+.save-btn, .cancel-btn {
+  padding: 10px 20px;
+  border: none;
+  border-radius: 6px;
+  font-weight: bold;
+  cursor: pointer;
+}
+
+.save-btn {
+  background-color: #42b983;
+  color: white;
+}
+
+.save-btn:hover {
+  background-color: #3aa876;
+}
+
+.cancel-btn {
+  background-color: #f0f0f0;
+  color: #333;
+}
+
+.cancel-btn:hover {
+  background-color: #e0e0e0;
+}
+</style>
+
+```
+
+```html
+// index.html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>my web components</title>
+    <script type="module" src="./dist/index.iife.min.js"></script>
+  </head>
+  <body>
+    <todo-list app-title="*待办清单*"></todo-list>
+  </body>
+</html>
+```