@talknote/create-talknote-h5 0.0.2 → 0.0.3

package/README.md

@@ -1,54 +1,165 @@
-# create-talknote-h5
+<h1 align="center">Alita Pro</h1>
 
-用于创建 Talknote Alita H5 项目的脚手架。
+帮助你快速使用 alita，基于Umi.js 的移动端框架
 
-## 使用方式
+```
+yarn
+yarn dev
+```
 
-发布到 npm 后执行：
+### 首页
 
-```bash
-yarn create @talknote/talknote-h5 my-project
-```
+![image](https://user-images.githubusercontent.com/11746742/179654827-2ca22b45-0ec9-471e-8238-9bfa56d864a0.png)
 
-其中 `my-project` 是必填的项目名称。项目名称只允许小写字母、数字、点号、下划线和连字符，并且必须以小写字母或数字开头。
+### 列表页
 
-生成完成后执行：
+列表页支持滚动加载更多，固定头部，状态保持
 
-```bash
-cd my-project
-yarn
-yarn start
-```
+![image](https://user-images.githubusercontent.com/11746742/179654907-585061f1-02cc-464e-ac75-c6ae12b2c666.png)
+
+
+### 关于尺寸标注
+
+100% 宽为 750px，可在蓝湖等工具中将标准改为 750px，这样可以直接使用标注的尺寸用于 caa class 中的尺寸，最终运行会根据手机适配，将 px 自动转为对应的 rem 值。
+
+值得注意的是，写在内联样式 style 中的 px 值不会被转化，需要手动写明 rem 单位，直接将 px 值除于 100 即可，如 750px，在 style 中应该写为 7.5rem
+
+### 关于路由
 
-脚手架不会自动安装依赖，也不会初始化 Git 仓库。
+采用约定式路由，只有 `src/pages/**/index.tsx` 会被识别成路由，可使用 npx alita g pages name 来新增页面。
 
-## 本地验证
+> Q: 为什么仅 index.tsx 会被识别成路由？如果我想要嵌套的路由，如 hello/hero 我该怎么办？
+> A: 仅 index.tsx 被识别成路由，会让整个文件结构变得很干净，在移动端上不需要嵌套路由，一般短位链接优势更大
 
-在脚手架根目录执行：
+### 自带头部
 
-```bash
-npm test
+可在 `src/app.tsx#L24` 中配置
+
+```tsx
+const titleList: TitleListItem[] = [
+  {
+    pagePath: '/',
+    title: '首页',
+  },
+  {
+    pagePath: '/list',
+    title: '列表',
+  },
+];
 ```
+ 可全局配置隐藏
+```tsx
+const navBar: NavBarProps = {
+  navList,
+  fixed: false,
+  //默认导航栏显示
+  hideNavBar: false,
+  onLeftClick: () => {
+    // router.goBack();
+  },
+};
 
-也可以在脚手架根目录直接执行命令入口：
+```
+也可以在页面中独立配置
+
+```tsx
+import { setPageNavBar, useLocation } from 'alita';
+import { LeftOutline } from 'antd-mobile-icons';
+import { useEffect } from 'react';
+
+const location = useLocation();
+useEffect(() => {
+  setPageNavBar({
+    pagePath: location.pathname,
+    navBar: {
+      mode: 'dark',
+      pageTitle: '首页动态标题',
+      pageBackground: '#fff',
+      back: '返回',
+      icon: <LeftOutline />,
+      leftContent: <div>首页</div>,
+      rightContent: <div>详情</div>,
+      onLeftClick: (navigate) => {
+        navigate(-1);
+      },
+      hideNavBar: false,
+    },
+  });
+}, []);
+```
 
-```bash
-node bin/create-talknote-h5.js my-project
+> 关闭默认 NavBar 上述 hideNavBar 配置改为 hideNavBar: true
+
+### 底部 Tabs
+
+可在 `src/app.tsx#L42` 中配置
+
+```tsx
+const tabList: TabBarListItem[] = [
+  {
+    pagePath: '/',
+    text: '首页',
+    iconPath: HomeGary,
+    selectedIconPath: HomeBlue,
+    title: '首页',
+    iconSize: '',
+    badge: '',
+  },
+  {
+    pagePath: '/list',
+    text: '列表',
+    iconPath: ListGary,
+    selectedIconPath: ListBlue,
+    title: '列表',
+    iconSize: '',
+    badge: '',
+  },
+];
 ```
 
-## 模板维护
+也可以在页面中独立配置
+
+```tsx
+import { setTabBarList, useLocation } from 'alita';
+import { useEffect } from 'react';
+
+const location = useLocation();
+useEffect(() => {
+  setTabBarList({
+    pagePath: location.pathname,
+    text: '首页',
+    iconSize: '18px',
+    badge: '12',
+    onPress: () => {
+      navigate(location.pathname, { replace: true });
+      return '';
+    },
+    remove: false,
+  });
+}, []);
+```
 
-生成项目的全部内容位于 `template/`。修改模板时，不要把 `node_modules`、构建产物或 Git 数据放入该目录。
+> 关闭 app.ts 中已经配置好的 Tab ，上述 remove 配置改为 remove: true
 
-模板中的 `_gitignore` 和 `_npmrc` 会在生成项目时分别恢复为 `.gitignore` 和 `.npmrc`。
+### 格式化
 
-## 发布
+```
+yarn format
+```
 
-确认包名和版本后，由维护者自行登录 npm 并发布：
+### 构建
 
-```bash
-npm login
-npm publish
 ```
+yarn build
+```
+
+### 调试工具
 
-发布完成后即可使用 `yarn create talknote-h5 my-project`。
+在 `config/config.ts` 中增加配置
+
+```
+aconsole: {
+    console: {},
+    inspx: {},
+},
+```

package/package.json

@@ -4,7 +4,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Create a Talknote Alita H5 project.",
   "license": "MIT",
   "private": false,

package/template/config/config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'alita';
+import proxy from './proxy';
 
 export default defineConfig({
   appType: 'h5',
@@ -7,6 +8,7 @@ export default defineConfig({
     console: {},
     inspx: {},
   },
+  proxy,
   mobileLayout: 'mobile5',
   mfsu: {},
   hash: false,

package/template/config/proxy.ts

@@ -0,0 +1,39 @@
+const BASE_URL = 'http://172.21.72.205:10000/';
+
+const DEV_URL = process.env.BASE_URL || `${BASE_URL}`;
+
+export default {
+  '/portal': {
+    target: BASE_URL,
+    changeOrigin: true,
+  },
+  '/server': {
+    target: DEV_URL,
+    changeOrigin: true,
+    pathRewrite: { '^/server': '' },
+  },
+  '/app': {
+    target: DEV_URL,
+    changeOrigin: true,
+    // pathRewrite: { '^/app': '' },
+  },
+  '/login': {
+    target: DEV_URL,
+    changeOrigin: true,
+    // pathRewrite: { '^/login': '' },
+  },
+  '/lcdp': {
+    target: `${DEV_URL}`,
+    changeOrigin: true,
+  },
+  '/img': {
+    target: BASE_URL,
+    changeOrigin: true,
+    pathRewrite: { '^/img': '' },
+  },
+  '/engine': {
+    target: BASE_URL,
+    changeOrigin: true,
+    pathRewrite: { '^/engine': 'engine' },
+  },
+};

package/template/h5-bridge.md

@@ -0,0 +1,297 @@
+# @talknote/h5-bridge
+
+TalkNote App 内嵌 WebView 的第三方 H5 SDK。它把现有 `window.TalkNoteBridge` 消息协议封装为带类型、可测试的语义化 API。
+
+- TypeScript 源码与完整 `.d.ts`
+- ESM、CommonJS、CDN UMD 三种入口
+- 发布包运行时依赖为 0
+- Father 仅用于开发构建，不进入 H5 运行时
+- 兼容当前 iOS、Android 注入的 `window.TalkNoteBridge`
+
+## 安装
+
+```bash
+npm install @talknote/h5-bridge
+```
+
+```bash
+yarn add @talknote/h5-bridge
+```
+
+### 安装 AI Skill（可选）
+
+`npm install` 不会自动修改当前项目。需要让 Codex 获得 TalkNote H5 Bridge 专用工作流时，显式执行：
+
+```bash
+npx talknote-h5-bridge install-skill
+```
+
+Skill 会安装到 `.agents/skills/talknote-h5-bridge/`。如果同名 Skill 已存在，命令会直接覆盖，但不会修改其他 Skill。升级 npm 包后需重新执行该命令才能更新 Skill。
+
+## 使用
+
+### ES Module
+
+```ts
+import TalkNoteH5Bridge, { TalkNoteBridgeError } from '@talknote/h5-bridge';
+
+const userInfo = await TalkNoteH5Bridge.getUserInfo();
+renderUserProfile(userInfo);
+```
+
+### CommonJS
+
+```js
+const TalkNoteH5Bridge = require('@talknote/h5-bridge');
+
+TalkNoteH5Bridge.goBack();
+```
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@talknote/h5-bridge@0.1.0/dist/umd/talknote-h5-bridge.min.js"></script>
+<script>
+  if (window.TalkNoteH5Bridge.isAvailable()) {
+    window.TalkNoteH5Bridge.getLocaleInfo().then(updateLocaleUI);
+  }
+</script>
+```
+
+CDN 全局对象是 `window.TalkNoteH5Bridge`。SDK 不会覆盖客户端注入的 `window.TalkNoteBridge`。
+
+## 环境检测
+
+原生能力只在 TalkNote App 支持的内嵌 WebView 中可用。系统浏览器中应提供降级逻辑：
+
+```ts
+if (!TalkNoteH5Bridge.isAvailable()) {
+  showOpenInAppGuide();
+  return;
+}
+```
+
+`isAvailable()` 只表示存在 Bridge 传输通道。调用具体能力前使用 `supports()`；`getCapabilities()` 可用于诊断客户端协议版本和能力来源：
+
+```ts
+if (!TalkNoteH5Bridge.supports('downloadFile')) {
+  showUpgradeAppGuide();
+  return;
+}
+
+const capabilities = TalkNoteH5Bridge.getCapabilities();
+```
+
+新客户端以原生 `capabilities` 为准；旧客户端只回退历史能力，两个文件能力不会被推断为可用。协议机器可读事实源是 [`contract/bridge-contract.json`](./contract/bridge-contract.json)。
+
+## 常用能力
+
+### 导航
+
+```ts
+TalkNoteH5Bridge.navigateTo({
+  key: 'MembershipScreen',
+  mode: 'push',
+  props: { from: 'third-party-h5' },
+});
+
+TalkNoteH5Bridge.goBack();
+TalkNoteH5Bridge.goToRoot({ tab: 'home' });
+TalkNoteH5Bridge.setPopGestureEnabled(false);
+```
+
+### 获取请求基础信息
+
+```ts
+const { baseUrl, headers = {} } = await TalkNoteH5Bridge.getRequestBaseInfo();
+
+const response = await fetch(`${baseUrl}/your/api`, {
+  headers: {
+    ...headers,
+    'Content-Type': 'application/json',
+  },
+});
+```
+
+不要打印或持久化 `token`、`Authorization` 等敏感信息。
+
+### 图片选择
+
+```ts
+const result = await TalkNoteH5Bridge.pickImages({
+  mediaTypes: 'Images',
+  allowsMultipleSelection: true,
+  selectionLimit: 9,
+});
+
+if (!result.canceled) {
+  uploadSelectedAssets(result.assets ?? []);
+}
+```
+
+### 文档选择
+
+```ts
+const result = await TalkNoteH5Bridge.documentPicker({
+  type: ['application/pdf'],
+  copyToCacheDirectory: true,
+  multiple: false,
+});
+```
+
+### 下载并保存文件
+
+`downloadFile` 接收远程 `http/https` 地址，客户端下载完成后会立即打开系统保存面板：
+
+```ts
+if (!TalkNoteH5Bridge.supports('downloadFile')) {
+  showUpgradeAppGuide();
+  return;
+}
+
+const result = await TalkNoteH5Bridge.downloadFile({
+  url: 'https://example.com/report.pdf',
+  fileName: '报告.pdf',
+  mimeType: 'application/pdf',
+  headers: { Authorization: 'Bearer xxx' },
+});
+
+if (result.canceled) {
+  return;
+}
+
+if (!result.success) {
+  showError(result.error || '文件保存失败');
+}
+```
+
+SDK 不会自动注入 App token。只有下载地址确实需要鉴权时，才由 H5 显式传入 `headers`，并且不要记录这些请求头。
+
+### 将本地文件另存到系统目录
+
+`saveFileToSystem` 接收 App 已可读取的本地 URI，例如图片选择、文档选择或其他原生能力返回的 `file://` URI：
+
+```ts
+if (!TalkNoteH5Bridge.supports('saveFileToSystem')) {
+  showUpgradeAppGuide();
+  return;
+}
+
+const result = await TalkNoteH5Bridge.saveFileToSystem({
+  localUri: 'file:///path/to/report.pdf',
+  fileName: '报告.pdf',
+  mimeType: 'application/pdf',
+});
+```
+
+该方法不会下载网络文件；需要保存远程 URL 时使用 `downloadFile`。两种方法都会要求用户在 iOS“文件”App 或 Android 系统文件选择器中确认保存位置，取消时返回 `canceled: true`。
+
+文件操作不会受 SDK 通用 30 秒超时限制，会一直等待下载和系统保存面板完成。单次远程下载最大 200MB；超过限制时返回 `error: 'file_too_large'`。如果下载发生跨源重定向，SDK 传入的自定义请求头不会转发到新的源站。
+
+### 实名认证
+
+```ts
+const result = await TalkNoteH5Bridge.startRealNameAuth({ authUrl });
+if (!result.opened) {
+  showError(result.error || '无法打开支付宝');
+}
+```
+
+### 页面重新聚焦
+
+```ts
+const unsubscribe = TalkNoteH5Bridge.onWebViewScreenFocus(event => {
+  refreshPageData(event.data?.timestamp);
+});
+
+// 页面销毁时取消监听
+unsubscribe();
+```
+
+## 错误处理
+
+```ts
+import TalkNoteH5Bridge, { TalkNoteBridgeError } from '@talknote/h5-bridge';
+
+try {
+  await TalkNoteH5Bridge.getUserInfo();
+} catch (error) {
+  if (error instanceof TalkNoteBridgeError) {
+    switch (error.code) {
+      case 'UNSUPPORTED_CAPABILITY':
+        showUpgradeAppGuide();
+        break;
+      case 'BRIDGE_UNAVAILABLE':
+        showOpenInAppGuide();
+        break;
+      case 'BRIDGE_TIMEOUT':
+        showRetryMessage();
+        break;
+      case 'INVALID_ARGUMENT':
+      case 'BRIDGE_SEND_FAILED':
+        reportNonSensitiveError(error.code);
+        break;
+    }
+  }
+}
+```
+
+| 错误码                       | 含义                                   |
+| ---------------------------- | -------------------------------------- |
+| `UNSUPPORTED_CAPABILITY`     | 当前客户端未声明支持该具体能力         |
+| `BRIDGE_UNAVAILABLE`         | 当前环境不存在所需 Bridge 传输能力     |
+| `INVALID_ARGUMENT`           | SDK 入参不符合公开契约                 |
+| `BRIDGE_TIMEOUT`             | 异步调用超过等待时间                   |
+| `BRIDGE_SEND_FAILED`         | 序列化或底层 Bridge 调用失败           |
+
+原生返回的 `{ error }` 属于业务结果，仍会通过 Promise resolve 返回，不会自动转换为 reject。
+
+## 通用协议入口
+
+优先使用语义化方法。客户端将来新增指令而 SDK 尚未升级时，可使用：
+
+```ts
+TalkNoteH5Bridge.send('newOneWayCommand', { value: 1 });
+
+const result = await TalkNoteH5Bridge.invoke(
+  'newAsyncCommand',
+  { value: 1 },
+  {
+    timeout: 10_000,
+  }
+);
+```
+
+不要直接使用 `_callbacks`、`_callbackId` 或 `_onCallback`，它们属于客户端内部实现。
+
+## API 文档
+
+- [完整 API](./docs/API.md)
+- [AI Coding 上下文](./docs/AI-CODING.md)
+- [llms.txt](./llms.txt)
+
+## 客户端兼容
+
+SDK 不修改底层消息字段，仍发送：
+
+```json
+{
+  "type": "getUserInfo",
+  "data": {}
+}
+```
+
+异步回调继续由客户端现有的 `window.TalkNoteBridge.invoke()` 和 `_onCallback()` 完成。SDK 返回类型按当前客户端字段建模，客户端未来可以增加字段而不破坏现有调用。
+
+仓库级 AI Skill 会指导接入与扩展流程，但不替代 `contract/bridge-contract.json`、公开 `.d.ts` 和原生实现；发生冲突时以机器契约和类型声明为准。
+
+## 本地开发
+
+```bash
+cd packages/h5Bridge
+npm install
+npm run build
+npm test
+```
+
+构建工具固定为 `father@4.6.33`。Father 是开发依赖，其依赖树不进入发布包；Black Duck 是否包含开发依赖，应以项目实际扫描配置和报告为准。

package/template/src/app.tsx

@@ -10,6 +10,8 @@ import type {
   TabBarProps,
   TitleListItem,
 } from 'alita';
+import routeProps from './.umi/core/routeProps';
+import TalkNoteH5Bridge from '@talknote/h5-bridge';
 
 export const request = {
   prefix: '/api',
@@ -35,8 +37,15 @@ const navList: NavBarListItem[] = [];
 const navBar: NavBarProps = {
   navList,
   fixed: false,
+  //默认顶部导航栏隐藏
+  hideNavBar: true,
   onLeftClick: () => {
-    // router.goBack();
+    // 判断是否能够返回，如果不能返回调用 @talknote/h5-bridge goBack
+    if (window.history.length > 1) {
+      window.history.back();       // 有历史记录，浏览器返回
+    } else {
+      TalkNoteH5Bridge.goBack();   // 没有历史记录，交给原生端处理
+    }
   },
 };
 const tabList: TabBarListItem[] = [