Viewer

Maintenance mode (deprecated)

@ahoo-wang/fetcher-viewer is deprecated and in maintenance mode: existing functionality is maintained, with no new features. Further data-view development belongs to @ahoo-wang/fetcher-view-engine; use View Engine for new projects. This page remains a maintenance reference for existing consumers. The packages use different models and APIs, so migration requires adaptation.

Viewer supplies Ant Design filter, table and saved-view UI. Begin with the component matching who owns the rows and saved views. A local table does not require a Wow backend; FetcherViewer requires the defined remote protocol.

Choose an entry

Entry	Component owns	Application owns
View	One view's filter/table/page interaction	`dataSource: {list,total}`, data loading and persistence
Viewer	View collection, switching and editable active-view state	`definition`, initial views, `onLoadData`, create/update/delete persistence and success callbacks
FetcherViewer	Definition/view lookup, Wow commands and paged data requests	Compatible backend, default Fetcher/authentication, tenant/owner identity and authorization

View and Viewer do not filter or paginate an input array for you. Their callbacks request new data; the application supplies the resulting rows and total. A save callback acknowledges application persistence. FetcherViewer adds version confirmation for create/update; deletion and ordinary row queries have different boundaries.

Installation prerequisites

pnpm add @ahoo-wang/fetcher @ahoo-wang/fetcher-cosec @ahoo-wang/fetcher-decorator @ahoo-wang/fetcher-eventbus @ahoo-wang/fetcher-eventstream @ahoo-wang/fetcher-openapi @ahoo-wang/fetcher-react @ahoo-wang/fetcher-storage @ahoo-wang/fetcher-viewer @ahoo-wang/fetcher-wow @ant-design/icons antd dayjs react react-dom

This reference targets 5.0.0. The library package declares Node >=18.20.8; repository development requires Node >=20.20.2 and pnpm 10.34.5. The command includes all transitive internal peers, including packages reached through Wow/React/CoSec. Direct runtime dependencies are installed automatically. External peer ranges are React/ReactDOM ^19.2.8, antd ^6.6.3, @ant-design/icons ^6.3.4 and dayjs ^1.11.23. They are installation requirements even when a particular feature is unused. Consumers do not need to duplicate the repository React Compiler toolchain.

Runnable core example

For setup, fixtures and expected results follow the guide.

tsx

/*
 * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *      http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { useCallback, useState } from 'react';
import { App } from 'antd';
import { FullscreenProvider } from '@ahoo-wang/fetcher-react';
import { Viewer } from '@ahoo-wang/fetcher-viewer';
import type { ViewDefinition, ViewState } from '@ahoo-wang/fetcher-viewer';
import { all, Operator, SortDirection } from '@ahoo-wang/fetcher-wow';
import type { Condition, FieldSort, PagedList } from '@ahoo-wang/fetcher-wow';

const users = [
  { id: 'u-ada', name: 'Ada', active: true },
  { id: 'u-lin', name: 'Lin', active: false },
  { id: 'u-grace', name: 'Grace', active: true },
  { id: 'u-zoe', name: 'Zoe', active: false },
];
type User = (typeof users)[number];

const definition: ViewDefinition = {
  id: 'local-users',
  name: 'Local users',
  fields: [
    { name: 'id', label: 'ID', type: 'text', primaryKey: true },
    {
      name: 'name',
      label: 'Name',
      type: 'text',
      primaryKey: false,
      sorter: true,
    },
    {
      name: 'active',
      label: 'Active',
      type: 'text',
      primaryKey: false,
      render: value => (value ? 'Yes' : 'No'),
    },
  ],
  availableFilters: [
    {
      label: 'User',
      filters: [
        {
          key: 'active',
          field: { name: 'active', label: 'Active' },
          component: 'bool',
        },
      ],
    },
  ],
  // Required metadata; this local application does not fetch these URLs.
  dataUrl: '/local-users/paged',
  countUrl: '/local-users/count',
};
const initialView: ViewState = {
  id: 'all-users',
  name: 'All users',
  definitionId: definition.id,
  type: 'PERSONAL',
  source: 'SYSTEM',
  isDefault: true,
  filters: [
    { key: 'active', type: 'bool', field: { name: 'active', label: 'Active' } },
  ],
  columns: definition.fields.map(field => ({
    key: field.name,
    name: field.name,
    fixed: field.primaryKey,
    hidden: false,
  })),
  tableSize: 'middle',
  pageSize: 2,
  condition: all(),
  sorter: [],
};

function filterUsers(condition: Condition): User[] {
  if (condition.operator === Operator.ALL) return [...users];
  if (
    condition.field === 'active' &&
    (condition.operator === Operator.TRUE ||
      condition.operator === Operator.FALSE)
  ) {
    return users.filter(
      user => user.active === (condition.operator === Operator.TRUE),
    );
  }
  throw new Error('This example supports only the Active boolean filter.');
}

function queryUsers(
  condition: Condition,
  page: number,
  size: number,
  sorter: FieldSort[] = [],
): PagedList<User> {
  const rows = filterUsers(condition);
  if (
    sorter.length > 1 ||
    sorter.some(
      sort =>
        sort.field !== 'name' ||
        ![SortDirection.ASC, SortDirection.DESC].includes(sort.direction),
    )
  ) {
    throw new Error(
      'This example supports only ascending/descending Name sorting.',
    );
  }
  if (sorter.length) {
    const direction = sorter[0].direction === SortDirection.ASC ? 1 : -1;
    rows.sort(
      (left, right) => left.name.localeCompare(right.name, 'en') * direction,
    );
  }
  return {
    list: rows.slice((page - 1) * size, page * size),
    total: rows.length,
  };
}

export function LocalViewer() {
  const [savedViews, setSavedViews] = useState<ViewState[]>([initialView]);
  const [data, setData] = useState(() => queryUsers(all(), 1, 2));
  const [savedName, setSavedName] = useState('');
  const [error, setError] = useState('');
  const load = useCallback(
    (
      condition: Condition,
      page: number,
      size: number,
      sorter?: FieldSort[],
    ) => {
      try {
        setData(queryUsers(condition, page, size, sorter));
        setError('');
      } catch (failure) {
        setData({ list: [], total: 0 });
        setError(failure instanceof Error ? failure.message : String(failure));
      }
    },
    [],
  );
  return (
    <App>
      <FullscreenProvider>
        <Viewer<User>
          definition={definition}
          defaultViews={savedViews}
          defaultView={initialView}
          dataSource={data}
          enableRowSelection={false}
          pagination={{ showSizeChanger: false }}
          onLoadData={load}
          onSwitchView={view =>
            load(view.condition, 1, view.pageSize, view.sorter)
          }
          onGetRecordCount={async (_url, condition) =>
            filterUsers(condition).length
          }
          onCreateView={(view, onSuccess) => {
            const saved = { ...view, id: crypto.randomUUID() };
            setSavedViews(current => [...current, saved]);
            setSavedName(saved.name);
            onSuccess?.(saved);
          }}
          onUpdateView={(view, onSuccess) => {
            setSavedViews(current =>
              current.map(saved => (saved.id === view.id ? view : saved)),
            );
            setSavedName(view.name);
            onSuccess?.(view);
          }}
          onDeleteView={(view, onSuccess) => {
            setSavedViews(current =>
              current.filter(saved => saved.id !== view.id),
            );
            onSuccess?.(view);
          }}
        />
        {error && <p role="alert">{error}</p>}
        <output aria-live="polite">{savedName && `Saved: ${savedName}`}</output>
      </FullscreenProvider>
    </App>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197

Topics

State and resource ownership · Failure and cancellation boundaries

Viewer ​

Choose an entry ​

Installation prerequisites ​

Runnable core example ​

Topics ​

Viewer

Choose an entry

Installation prerequisites

Runnable core example

Topics