组件API设计应以开发者体验为核心，优先暴露语义化属性（value、min、disabled）和事件/方法控制状态，避免过度暴露内部属性；attributeChangedCallback需防批量触发与死循环；对外方法统一返回Promise；slot与事件才是核心扩展点。
组件API设计要先想清楚「谁来调用」
HTML 自定义元素（Custom Elements）的 API 不是写给机器看的，是写给人用的。开发者看到 <date-picker>，第一反应应该是“传个 value 就能用”，而不是翻文档查 setInitialDate() 方法。可扩展性不等于功能堆砌，而是让常见操作零配置、特殊需求有出口。
- 常见错误：把内部状态全暴露为属性（
isFocused、isDisabled、hasError），导致使用者必须手动同步，反而更难维护 - 正确做法：只暴露语义化属性（
value、min、disabled），其余状态通过事件（change、focus）或方法（focus()、reset()）控制 - 兼容性注意：布尔属性如
disabled必须用hasAttribute('disabled')判断，不能依赖this.disabled === true（未设置时值为undefined）
attributeChangedCallback 里别直接更新 DOM
这个回调常被误当成“只要属性变了就立刻重绘”的钩子。但浏览器可能批量触发它（比如服务端渲染注入多个属性），频繁 DOM 操作会卡顿，且容易和初始化逻辑冲突。
- 使用
Promise.resolve().then(() => { /<em> 更新 </em>/ })或requestIdleCallback延迟执行，合并多次变更 - 对于字符串类属性（如
format），先做浅比较：if (oldValue === newValue) return，避免无意义重渲染 - 避免在回调里调用
this.setAttribute()，否则会再次触发自身，造成死循环（尤其当属性有默认值处理逻辑时）
对外暴露方法时，优先选 async + Promise
同步方法看似简单，但一旦组件内部涉及异步加载（比如图标字体、i18n 资源）、动画、或 Web Worker 通信，就会阻塞主线程或抛出意外错误。
- 所有可能异步的方法（
validate()、submit()、loadOptions()）统一返回Promise，哪怕当前是同步实现：“以后加校验逻辑不用改调用方” - 错误处理统一走
reject(new Error('...'))，不要用console.error+ 返回false这种混合模式 - 示例：
this.querySelector('form').addEventListener('submit', async (e) => { e.preventDefault(); try { await this.validate(); // 统一 Promise 接口 await this.submit(); } catch (err) { this.showError(err.message); } });
slot 和 event 的组合才是真正的扩展点
属性和方法解决的是“我怎么控制你”，而 <slot> 和自定义事件解决的是“你怎么融入我的结构”。很多所谓“可扩展”组件只开放了样式变量，却堵死了内容定制和流程介入。
立即学习“前端免费学习笔记（深入）”；
- 必须提供至少一个默认
<slot>，允许替换整个主体；对复杂区域（如表头、页脚）提供命名 slot（<slot name="header">） - 关键生命周期事件应可取消：比如
beforeSubmit事件带event.preventDefault()，让父组件能拦截提交逻辑 - 避免用
dispatchEvent(new CustomEvent('change', { detail: ... }))传递深层嵌套对象——JSON 序列化后丢失方法和原型，建议只传原始类型或扁平对象
真正难的不是写出能工作的 API，而是判断哪些不该暴露。留白比填满更需要经验。
