@rk911/store-ui

店长端业务的跨框架原生 Web 组件（Web Components）库。组件以 rk-* 自定义元素提供，运行时零第三方依赖；同一份源码同时提供标准 npm 包和页面生成平台可直接加载的浏览器预览包。

安装与使用

npm install @rk911/store-ui

在应用入口加载运行时和完整样式：

import '@rk911/store-ui'
import '@rk911/store-ui/style.css'

<rk-card>
  <rk-input placeholder="请输入订单号" clearable></rk-input>
  <rk-button variant="primary" block>查询</rk-button>
</rk-card>

• @rk911/store-ui/style.css：完整设计令牌与组件样式，推荐新项目使用。
• @rk911/store-ui/styles/tokens.css：仅设计令牌。
• @rk911/store-ui/styles/legacy.css：旧 .rk-* 类名页面的渐进迁移层；新页面优先使用 rk-* 元素。

框架接入

Vue 3 接入

将 rk-* 识别为原生自定义元素：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue({
    template: {
      compilerOptions: { isCustomElement: tag => tag.startsWith('rk-') },
    },
  })],
})

组件通过自定义事件（CustomEvent）通信，数据位于 event.detail：

<rk-input placeholder="搜索订单" @rk-input="event => console.log(event.detail.value)" />

Vue 2 接入

import Vue from 'vue'
Vue.config.ignoredElements = [/^rk-/]

React 接入

React 可渲染自定义元素。请通过 ref 监听自定义事件：

useEffect(() => {
  const onInput = event => console.log(event.detail.value)
  ref.current?.addEventListener('rk-input', onInput)
  return () => ref.current?.removeEventListener('rk-input', onInput)
}, [])

组件与页面组合

当前包含 35 个组件，覆盖输入、选择、反馈、导航、列表、数据展示和店长端业务组合。完整的属性、插槽、事件、方法与组合范式以以下文件为准：

• 组件契约
• 生成规则
• 在线组件文档

| 场景 | 推荐组合 | | --- | --- | | 筛选与搜索 | rk-select、rk-filter-tags、rk-search | | 要货/补货 | rk-card、rk-product-row、rk-segment、rk-stepper、rk-bottom-bar | | 订单摘要 | rk-card、rk-tag、rk-product-row、rk-status-text、rk-button | | 批量选择 | rk-checkbox、rk-list、rk-list-item、rk-button |

页面优先组合已有组件，而不是创建单页面专用组件。

智能页面生成与预览

页面生成平台读取 ai/catalog.json，并按以下顺序加载运行时：

1. preview.archive：npm tarball 或上传 ZIP 内的相对路径；平台提取后通过同源静态资源加载。
2. preview.fallback：预览产物不可用时的 HTTPS CDN 兜底。
3. preview.runtime / preview.styles：保留给旧平台的兼容字段，等同于当前 CDN 兜底。

preview/
├─ rk-store-ui.js      # 自包含 ESM，自动注册所有 rk-* 元素
└─ rk-store-ui.css     # 设计令牌与组件补充样式

浏览器预览不能直接执行 import '@rk911/store-ui'，因为浏览器不会解析裸 npm 包名。应加载平台同源托管的 preview/rk-store-ui.js。若 <rk-card> 仍是普通标签、没有影子 DOM（Shadow DOM），说明运行包未成功加载，而不只是 CSS 缺失。

构建与发布

npm run build       # 同时生成 dist/、preview/ 和 docs/
npm run check       # 校验构建结果、组件契约和预览运行包
npm run pack:check  # 查看 npm 实际会包含的文件

| 目录 | 用途 | | --- | --- | | dist/ | 对外 npm 包的 ESM 入口与完整样式 | | preview/ | 页面生成平台的浏览器直载运行包，无裸 npm import | | docs/ | 可部署到 OSS/CDN 的组件文档站点 |

发布新版本：

npm login --registry=https://registry.npmjs.org/
npm version patch
npm run check
npm publish --access public --registry=https://registry.npmjs.org/

npm 不允许覆盖已经发布的版本；每次发布前必须执行 npm version patch、minor 或 major。

兼容性

支持自定义元素（Custom Elements）、影子 DOM（Shadow DOM）、CSS 变量（CSS Variables）和 ES 模块（ES Modules）的现代浏览器：Chrome/Edge 90+、Firefox 90+、Safari/iOS 14.1+。服务端渲染可导入模块，但只应在浏览器端注册组件；IE 11 需由应用自行提供转译与 Web Components polyfill。