@lark-base-open/base-database-app-sdk 0.3.1 → 0.3.2

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/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.2 - 2026-10-19
4
+
5
+ ### Added
6
+
7
+ - 新增当前访问者姓名与头像的可编译示例,包含加载、头像缺失占位和失败重试。
8
+
9
+ ### Changed
10
+
11
+ - `getCurrentUser()` 文档明确 `name` / `avatarUrl` 返回结构及其与成员选择器 `User` 类型的区别。
12
+
3
13
  ## 0.3.1 - 2026-10-19
4
14
 
5
15
  ### Fixed
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  用于开发以飞书多维表格为数据后端的 Base Database 应用,提供页面与服务端运行时、平台组件、版本化能力查询与测试工具。
4
4
 
5
- 安装:`npm install @lark-base-open/base-database-app-sdk@0.3.1`。从旧版本升级前请阅读 [变更与迁移说明](CHANGELOG.md)。
5
+ 安装:`npm install @lark-base-open/base-database-app-sdk@0.3.2`。从旧版本升级前请阅读 [变更与迁移说明](CHANGELOG.md)。
6
6
 
7
7
  运行环境需支持 ES2022;页面 API 需要 Base Database 页面宿主,服务端 API 用于 Node.js / FaaS。组件需要 React 与 React DOM 19.2,页面查询能力使用 @tanstack/react-query 5.104.1;npm 会安装声明的依赖与必需 peer。底层通信依赖 base-site-channel 0.1.6。
8
8
 
@@ -34,9 +34,9 @@ SDK 文档说明本版本 API、组件、兼容语义与可编译示例。业务
34
34
 
35
35
  ## npm 发布
36
36
 
37
- SDK 0.3.1 依赖已发布的 channel 0.1.6,锁文件必须解析到 `registry.npmjs.org` 的制品。AI Function 调用需要后端与宿主支持 `functions/:key/invoke`。
37
+ SDK 0.3.2 依赖已发布的 channel 0.1.6,锁文件必须解析到 `registry.npmjs.org` 的制品。AI Function 调用需要后端与宿主支持 `functions/:key/invoke`。
38
38
 
39
- 本版本拟发布到 `latest`。0.3.1 修复人员选择器在结构化多语言姓名中的语言选择与回退,不改变公开 API。契约生成使用工程安装的 SDK `./codegen` 入口;已安装旧 SDK 的工程不会因为单独升级 CLI 而自动切换到 0.3.1。0.3.0 将批量 Mutation 的 ID、输入和输出绑定到生成契约,收紧公开类型接口;0.2.0 对直接 Function 调用的返回泛型也有不兼容变化,跨版本升级见 [迁移说明](CHANGELOG.md)。
39
+ 本版本拟发布到 `latest`。0.3.2 补充当前访问者的返回结构、用户类型区别及姓名和头像展示示例,不改变公开 API。契约生成使用工程安装的 SDK `./codegen` 入口;已安装旧 SDK 的工程不会因为单独升级 CLI 而自动切换到 0.3.2。0.3.0 将批量 Mutation 的 ID、输入和输出绑定到生成契约,收紧公开类型接口;0.2.0 对直接 Function 调用的返回泛型也有不兼容变化,跨版本升级见 [迁移说明](CHANGELOG.md)。
40
40
 
41
41
  每个不兼容版本的 `CHANGELOG.md` 都必须包含 `### Migration`,并依次写出四个非空四级标题:**会坏什么 / 怎么在代码里找受影响处 / 修改步骤 / 验证命令**。0.x 按 minor、1.0 起按 major 判断兼容线;兼容版本若提供 Migration,也使用相同格式。版本条目、编号和四段内容由 `check:migrations` 检查,缺失时测试与发布预检失败。
42
42
 
@@ -59,7 +59,7 @@ SDK 0.3.1 依赖已发布的 channel 0.1.6,锁文件必须解析到 `registry.
59
59
 
60
60
  - `npm whoami --registry=https://registry.npmjs.org/`
61
61
  - `npm publish --tag latest --registry=https://registry.npmjs.org/`
62
- - `npm view @lark-base-open/base-database-app-sdk@0.3.1 version dist --json --registry=https://registry.npmjs.org/`
62
+ - `npm view @lark-base-open/base-database-app-sdk@0.3.2 version dist --json --registry=https://registry.npmjs.org/`
63
63
  - `npm view @lark-base-open/base-database-app-sdk dist-tags versions --json --registry=https://registry.npmjs.org/`
64
64
 
65
- 回读应确认 `latest` 为 `0.3.1`。
65
+ 回读应确认 `latest` 为 `0.3.2`。
package/capabilities.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "sdkVersion": "0.3.1",
3
+ "sdkVersion": "0.3.2",
4
4
  "capabilities": {
5
5
  "runtime.context": {
6
6
  "required": [
package/docs/page.md CHANGED
@@ -3,7 +3,63 @@
3
3
  从 `@lark-base-open/base-database-app-sdk/page` 导入。协议通信复用 channel/runtime;SDK 另提供能力感知链接拦截、老模板数据库/AI 兼容适配、启动管理与平台组件。[`siteRuntime`](exports.md#page) 是默认单例;单测可把模拟 channel 交给 [`createSiteRuntimeClient`](exports.md#page)。
4
4
 
5
5
  生命周期:首屏挂载后调用 `siteRuntime.ready()`,启动失败调用 `reportLoadFailed(code)`;不要等业务数据加载完成才上报 ready。`getRuntimeContext()` 返回 locale/colorScheme/mode/protocolVersion,可选 env/siteToken/capabilities;缺 env/token 的旧宿主由 SDK 的 getDatabaseContext/resolveDatabaseContext 保留路径兜底。
6
- [`getCurrentUser`](exports.md#page)、[`logout`](exports.md#page)、[`requestEdit`](exports.md#page)、`siteRuntime.subscribeModeChanged` 保持 channel 返回语义。
6
+ [`getCurrentUser()`](#当前访问者) 的返回字段和展示示例见下文;[`logout`](exports.md#page)、[`requestEdit`](exports.md#page)、`siteRuntime.subscribeModeChanged` 保持 channel 返回语义。
7
+
8
+ ## 当前访问者
9
+
10
+ [`getCurrentUser`](exports.md#page) 和 `siteRuntime.getCurrentUser()` 返回 `Promise<SiteRuntimeUserInfo>`,从宿主读取当前登录访问者。返回类型 [`SiteRuntimeUserInfo`](exports.md#page) 由 SDK `/page` 导出,定义来自已安装的 `@lark-base-open/base-site-channel/runtime-contract`;核对字段时沿该类型声明跳转,不用名称相近的用户类型代替。
11
+
12
+ | 字段 | 类型 | 用法 |
13
+ | --- | --- | --- |
14
+ | `name` | `string` | 访问者姓名 |
15
+ | `avatarUrl` | `string` | 头像地址;空字符串时显示占位内容 |
16
+
17
+ [成员选择器](components.md)的 [`User`](exports.md#components) 是另一种返回结构:头像位于 `avatar.avatar_72`、`avatar.avatar_240` 等字段。`getCurrentUser()` 使用顶层 `avatarUrl`。类型断言不会转换运行时数据;属性访问报错时,先核对实际 API 的返回声明。
18
+
19
+ 下面的组件展示姓名和头像,在读取失败后由用户点击重试;卸载后忽略迟到结果。它可以作为已通过 `startBaseApp` 启动的页面中的一个组件使用,[示例源文件](../examples/current-user.tsx)随包提供。
20
+
21
+ <!-- example: current-user.tsx -->
22
+ ```tsx
23
+ import { useEffect, useState } from 'react';
24
+ import { siteRuntime } from '@lark-base-open/base-database-app-sdk/page';
25
+
26
+ type Visitor = Awaited<ReturnType<typeof siteRuntime.getCurrentUser>>;
27
+ type VisitorState =
28
+ | { status: 'loading' }
29
+ | { status: 'error' }
30
+ | { status: 'ready'; user: Visitor };
31
+
32
+ export function CurrentUserCard() {
33
+ const [attempt, setAttempt] = useState(0);
34
+ const [state, setState] = useState<VisitorState>({ status: 'loading' });
35
+
36
+ useEffect(() => {
37
+ let active = true;
38
+ setState({ status: 'loading' });
39
+ void siteRuntime.getCurrentUser().then(
40
+ (user) => { if (active) setState({ status: 'ready', user }); },
41
+ () => { if (active) setState({ status: 'error' }); },
42
+ );
43
+ return () => { active = false; };
44
+ }, [attempt]);
45
+
46
+ if (state.status === 'loading') return <p role="status">正在读取访问者信息…</p>;
47
+ if (state.status === 'error') {
48
+ return <div role="alert">
49
+ <p>无法读取访问者信息,请重试。</p>
50
+ <button type="button" onClick={() => setAttempt(value => value + 1)}>重试</button>
51
+ </div>;
52
+ }
53
+
54
+ const { name, avatarUrl } = state.user;
55
+ return <section aria-label="当前访问者">
56
+ <p>{name}</p>
57
+ {avatarUrl
58
+ ? <img src={avatarUrl} alt={`${name}的头像`} width={48} height={48} />
59
+ : <span role="img" aria-label="暂无头像">?</span>}
60
+ </section>;
61
+ }
62
+ ```
7
63
 
8
64
  ## HTTP 代理
9
65
 
@@ -0,0 +1,39 @@
1
+ import { useEffect, useState } from 'react';
2
+ import { siteRuntime } from '@lark-base-open/base-database-app-sdk/page';
3
+
4
+ type Visitor = Awaited<ReturnType<typeof siteRuntime.getCurrentUser>>;
5
+ type VisitorState =
6
+ | { status: 'loading' }
7
+ | { status: 'error' }
8
+ | { status: 'ready'; user: Visitor };
9
+
10
+ export function CurrentUserCard() {
11
+ const [attempt, setAttempt] = useState(0);
12
+ const [state, setState] = useState<VisitorState>({ status: 'loading' });
13
+
14
+ useEffect(() => {
15
+ let active = true;
16
+ setState({ status: 'loading' });
17
+ void siteRuntime.getCurrentUser().then(
18
+ (user) => { if (active) setState({ status: 'ready', user }); },
19
+ () => { if (active) setState({ status: 'error' }); },
20
+ );
21
+ return () => { active = false; };
22
+ }, [attempt]);
23
+
24
+ if (state.status === 'loading') return <p role="status">正在读取访问者信息…</p>;
25
+ if (state.status === 'error') {
26
+ return <div role="alert">
27
+ <p>无法读取访问者信息,请重试。</p>
28
+ <button type="button" onClick={() => setAttempt(value => value + 1)}>重试</button>
29
+ </div>;
30
+ }
31
+
32
+ const { name, avatarUrl } = state.user;
33
+ return <section aria-label="当前访问者">
34
+ <p>{name}</p>
35
+ {avatarUrl
36
+ ? <img src={avatarUrl} alt={`${name}的头像`} width={48} height={48} />
37
+ : <span role="img" aria-label="暂无头像">?</span>}
38
+ </section>;
39
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lark-base-open/base-database-app-sdk",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "description": "Base Database 页面与服务端 SDK、平台组件及测试工具",
5
5
  "type": "module",
6
6
  "sideEffects": [