@hxdhxd/harmony-flow-ui 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +187 -0
- package/dist/index.cjs +3361 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.css +6312 -0
- package/dist/index.css.map +1 -0
- package/dist/index.d.cts +1496 -0
- package/dist/index.d.ts +1496 -0
- package/dist/index.js +3200 -0
- package/dist/index.js.map +1 -0
- package/package.json +102 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 weathersun66
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# Harmony Flow UI
|
|
2
|
+
|
|
3
|
+
面向通用 React 场景的轻量组件库。默认视觉取意 HarmonyOS 7：清透白底、云水浅蓝、柔和层级与克制动效，同时通过 CSS Design Tokens 支持运行时定制。
|
|
4
|
+
|
|
5
|
+
## 项目概览
|
|
6
|
+
|
|
7
|
+
- 137 个可用组件，覆盖基础控件、表单、导航、数据展示、反馈、布局、协作、调度与 AI 交互场景
|
|
8
|
+
- React + TypeScript 实现，同时输出 ESM、CommonJS、类型声明和独立样式文件
|
|
9
|
+
- 内置组件展厅、成品场景、交互示例、Props 文档与无障碍说明
|
|
10
|
+
- 支持主题 Token、界面密度以及桌面、平板和移动视口预览
|
|
11
|
+
- 统一质量门覆盖类型检查、构建、144 项公开 API、142 条展示路由、浏览器交互和视觉回归
|
|
12
|
+
|
|
13
|
+
## 项目结构
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
src/ 组件实现、主题 Token 与样式
|
|
17
|
+
demo/ 组件展厅、文档和成品场景
|
|
18
|
+
scripts/ 构建、静态服务与维护脚本
|
|
19
|
+
test/ API、浏览器、文档、视觉及完整性测试
|
|
20
|
+
plan/ 批次计划与完成记录
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 本地运行
|
|
24
|
+
|
|
25
|
+
```powershell
|
|
26
|
+
npm install
|
|
27
|
+
npm run check
|
|
28
|
+
npm run build
|
|
29
|
+
npm run build:demo
|
|
30
|
+
npm run serve
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
默认静态服务地址为 `http://127.0.0.1:4173`。
|
|
34
|
+
|
|
35
|
+
`npm run test:quality` 是统一质量门，覆盖类型、正式构建、公共 API、浏览器路由、组件文档、视觉证据与完整性。
|
|
36
|
+
|
|
37
|
+
展示页由 esbuild 正式构建，并由项目内 Node 静态服务托管，不使用 Vite。
|
|
38
|
+
|
|
39
|
+
展示页提供“组件展厅”和“成品场景”两个入口：前者包含组件分类、搜索、真实交互预览、示例代码、Props 与无障碍说明，后者展示学习工作台、身份入口和运营洞察等跨组件组合。页面底部提供安装、样式引入与 ThemeProvider 的快速接入示例。
|
|
40
|
+
|
|
41
|
+
核心组件详情支持可复制 URL，例如 `/components/button`；成品页支持 `/templates/dashboard`、`/templates/onboarding` 与 `/templates/insights` 全屏预览。全屏预览可实时切换主题色、界面密度以及桌面、平板和移动视口。
|
|
42
|
+
|
|
43
|
+
## 发布状态与下一步
|
|
44
|
+
|
|
45
|
+
正式 npm 包名为 `@hxdhxd/harmony-flow-ui`，当前版本为 `0.1.0`。后续建议在每次发布前更新版本号、运行完整质量门，并在 GitHub 创建对应 Release 或维护变更日志。
|
|
46
|
+
|
|
47
|
+
本项目采用 [MIT License](./LICENSE)，允许免费用于个人和商业项目；再分发时须保留原许可证和版权声明。
|
|
48
|
+
|
|
49
|
+
## 在其他项目中使用
|
|
50
|
+
|
|
51
|
+
### 环境要求
|
|
52
|
+
|
|
53
|
+
- Node.js 18 或更高版本
|
|
54
|
+
- React 18 或更高版本
|
|
55
|
+
- React DOM 18 或更高版本
|
|
56
|
+
|
|
57
|
+
### npm 正式安装
|
|
58
|
+
|
|
59
|
+
在目标 React 项目中执行：
|
|
60
|
+
|
|
61
|
+
```powershell
|
|
62
|
+
npm install @hxdhxd/harmony-flow-ui
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
如果目标项目还没有 React：
|
|
66
|
+
|
|
67
|
+
```powershell
|
|
68
|
+
npm install react react-dom @hxdhxd/harmony-flow-ui
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
在应用入口导入一次全局样式，然后直接使用组件：
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
import { Button, ThemeProvider } from '@hxdhxd/harmony-flow-ui';
|
|
75
|
+
import '@hxdhxd/harmony-flow-ui/style.css';
|
|
76
|
+
|
|
77
|
+
export default function App() {
|
|
78
|
+
return (
|
|
79
|
+
<ThemeProvider tokens={{ colorPrimary: '#0a7cff' }}>
|
|
80
|
+
<Button onClick={() => console.log('saved')}>保存更改</Button>
|
|
81
|
+
</ThemeProvider>
|
|
82
|
+
);
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`ThemeProvider` 建议放在应用根部。主题覆盖支持 `colorPrimary`、`colorPrimaryHover`、`colorBackground`、`colorSurface`、`colorText`、`colorTextMuted`、`colorBorder`、`radiusMd`、`radiusLg`、`shadowElevated` 与 `motionDuration`。
|
|
87
|
+
|
|
88
|
+
### Next.js App Router
|
|
89
|
+
|
|
90
|
+
在 `app/layout.tsx` 中导入全局样式，并通过客户端组件挂载主题：
|
|
91
|
+
|
|
92
|
+
```tsx
|
|
93
|
+
// app/providers.tsx
|
|
94
|
+
'use client';
|
|
95
|
+
|
|
96
|
+
import { ThemeProvider } from '@hxdhxd/harmony-flow-ui';
|
|
97
|
+
|
|
98
|
+
export function Providers({ children }: { children: React.ReactNode }) {
|
|
99
|
+
return <ThemeProvider>{children}</ThemeProvider>;
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
// app/layout.tsx
|
|
105
|
+
import '@hxdhxd/harmony-flow-ui/style.css';
|
|
106
|
+
import { Providers } from './providers';
|
|
107
|
+
|
|
108
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
109
|
+
return (
|
|
110
|
+
<html lang="zh-CN">
|
|
111
|
+
<body><Providers>{children}</Providers></body>
|
|
112
|
+
</html>
|
|
113
|
+
);
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### 在其他项目中安装本地构建包
|
|
118
|
+
|
|
119
|
+
先在本仓库生成经过验证的 npm 压缩包：
|
|
120
|
+
|
|
121
|
+
```powershell
|
|
122
|
+
npm run test:package
|
|
123
|
+
npm pack
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
然后在目标项目中安装生成的 `.tgz` 文件（请替换为实际路径和文件名）：
|
|
127
|
+
|
|
128
|
+
```powershell
|
|
129
|
+
npm install "D:\path\to\harmony-flow-ui-0.1.0.tgz"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
安装后仍按正式 npm 包的方式从 `@hxdhxd/harmony-flow-ui` 导入。当前不建议直接通过 GitHub URL 安装，因为仓库不提交 `dist/`，Git 依赖安装流程无法保证生成完整发布产物。
|
|
133
|
+
|
|
134
|
+
### 更新版本
|
|
135
|
+
|
|
136
|
+
在目标项目中更新到最新版：
|
|
137
|
+
|
|
138
|
+
```powershell
|
|
139
|
+
npm install @hxdhxd/harmony-flow-ui@latest
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## 构建产物
|
|
143
|
+
|
|
144
|
+
执行 `npm run build` 后，`dist/` 将包含：
|
|
145
|
+
|
|
146
|
+
- `index.js`：ESM 入口
|
|
147
|
+
- `index.cjs`：CommonJS 入口
|
|
148
|
+
- `index.d.ts` / `index.d.cts`：类型声明
|
|
149
|
+
- `index.css`：组件样式
|
|
150
|
+
|
|
151
|
+
## 发布
|
|
152
|
+
|
|
153
|
+
包名使用当前 npm 账号的个人 scope `@hxdhxd`。发布账号必须拥有该 scope，并登录 npm 官方注册表：
|
|
154
|
+
|
|
155
|
+
```powershell
|
|
156
|
+
npm login --registry=https://registry.npmjs.org/
|
|
157
|
+
npm whoami --registry=https://registry.npmjs.org/
|
|
158
|
+
npm view @hxdhxd/harmony-flow-ui --registry=https://registry.npmjs.org/
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
发布前可在本地验证实际 tarball 内容：
|
|
162
|
+
|
|
163
|
+
```powershell
|
|
164
|
+
npm run build
|
|
165
|
+
npm run test:package
|
|
166
|
+
npm pack
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
正式发布：
|
|
170
|
+
|
|
171
|
+
```powershell
|
|
172
|
+
npm publish --access public --registry=https://registry.npmjs.org/
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
发布完成后验证注册表中的版本：
|
|
176
|
+
|
|
177
|
+
```powershell
|
|
178
|
+
npm view @hxdhxd/harmony-flow-ui version --registry=https://registry.npmjs.org/
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`npm publish` 会先执行完整质量门；`prepack` 会重新检查类型、构建 ESM/CJS/CSS/类型声明，并验证发布包只包含 README、LICENSE、package.json 和 `dist/`。
|
|
182
|
+
|
|
183
|
+
## 导航组件
|
|
184
|
+
|
|
185
|
+
导航模块包含 `FloatingNav`、`Sidebar`、`Breadcrumb`、`DropdownMenu`、`MegaMenu`、`MobileNavigation`、`Scrollspy` 与 `ShrinkNav`。`MobileNavigation` 通过 `mode="drawer | fullscreen"` 覆盖汉堡抽屉和全屏导航。
|
|
186
|
+
|
|
187
|
+
所有导航组件共享 `NavigationItem`，业务选择事件统一为 `onItemSelect(item)`；该命名刻意避开 React 原生 DOM 的 `onSelect` 事件。
|