Extracting the metadata of Vue components more effectively.
This project is heavily inspired by vue-component-meta, and reuses a significant amount of its code.
pnpm i @dumijs/vue-meta
@dumijs/vue-meta
uses TypeScript's TypeChecker for metadata extraction.
[!NOTE] When configuring tsconfig.json, set strictNullCheck to false
{ "compilerOptions": { "strictNullChecks": false } }
import { createProject } from '@dumijs/vue-meta';
import * as path from 'path';
const projectRoot = '<project-root>';
const project = createProject({
rootPath: projectRoot,
// If tsconfigPath is not set, tsconfig will be <rootPath>/tsconfig.json
tsconfigPath: path.resolve(projectRoot, './tsconfig.json');
});
const entry = path.resolve(projectRoot, './src/index.ts');
const meta = project.service.getComponentLibraryMeta(entry);
meta.components['Button'];
// Reusable types, queried and referenced through `ref`
// (`ref` is the md5 value calculated from the name of the file where the type is located and its type name.)
meta.types;
After updating the file locally, use patchFiles
to update the file in memory, and TypeChecker will recheck.
project.patchFiles([
{
action: 'add',
fileName: '...',
text: '...',
},
{
update: 'add',
fileName: '....',
text: '....',
},
]);
// Then you can get the new type metadata
const meta = project.service.getComponentLibraryMeta(entry);
Create a meta checker for Vue project with rootPath
If no parameters are passed in, tsconfig.json in the current workspace will be read.
export declare function createProject(rootPath?: string): Project;
import { createProject } from '@dumijs/vue-meta';
createProject();
Returns Project
Create a meta checker for Vue project by options
export declare function createProject(options: CheckerProjectOptions): Project;
import { createProject } from '@dumijs/vue-meta';
// Manually pass in the tsconfig.json path
createProject({
// If neither rootPath nor tsconfigPath is set, rootPath will be process.cwd()
rootPath: '<project-root>',
// If tsconfigPath is not set, tsconfig will be <rootPath>/tsconfig.json
tsconfigPath: '<project-root>/tsconfig.json',
checkerOptions: {},
});
-
options
CheckerProjectOptions
Returns Project
Create component metadata checker through json configuration
export declare function createProjectByJson(
options: CheckerProjectJsonOptions,
): Project;
-
options
CheckerProjectJsonOptions
Returns Project
export interface MetaCheckerOptions extends MetaCheckerSchemaOptions
Extends: MetaCheckerSchemaOptions
-
disableGit
booleanProhibit obtaining git repo URL, git revision, and other information through git commands, the default is false
-
disableSources
booleanDisable production of source links, the default is false
-
filterExposed
booleanWhether to enable filtering for exposed attributes, the default is true.
If true, only methods or properties identified by release tags like
@public
will be exposed in jsx -
filterGlobalProps
booleanWhether to filter global props, the default is true
If it is true, global props in vue, such as key and ref, will be filtered out
-
forceUseTs
boolean -
gitRemote
stringDefault is "origin"
-
gitRevision
string -
printer
ts.PrinterOptions -
sourceLinkTemplate
stringsource link template, must be set when you set
disableGit
.A typical template looks like this:
https://github.com/umijs/dumi/{gitRevision}/{path}#L{line}
.The parser will replace the parts
{gitRevision|path|line}
export interface MetaCheckerSchemaOptions
-
disableExternalLinkAutoDectect
booleanBy default, this option is false, the resolver will automatically capture the MDN links contained in the comments of all declaration files under node_modules/typescript/lib. Users do not need to configure externalSymbolLinkMappings themselves.
Of course, you can also overwrite the captured links through externalSymbolLinkMappings
-
exclude
string | RegExp | (string | RegExp)[] | ((name: string) => boolean)By default, type resolution in node_module will be abandoned.
-
externalSymbolLinkMappings
Record<string, Record<string, string>>The types/interfaces mapping method is provided as follows:
{ typescript: { Promise: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise', }, },
For more complex mapping methods, please use
unknownSymbolResolvers
-
ignore
(string | ((name: string, type: ts.Type, typeChecker: ts.TypeChecker) => boolean | void | undefined | null))[]A list of type names to be ignored in expending in schema. Can be functions to ignore types dynamically.
-
ignoreTypeArgs
booleanIn addition to ignoring the type itself, whether to ignore the type parameters it carries. By default, the type parameters it carries will be parsed. For example,
Promise<{ a: string }>
, if you use optionexclude
orignore
to ignorePromise
,{ a: string }
will still be parsed by default. -
propertyResovlers
PropertySchemaResolver<PropertyMeta>[]Property schema resolvers for some special props definition methods, such as
vue-types
-
unknownSymbolResolvers
UnknownSymbolResolver[]unknownSymbol resolver
export type PropertySchemaResolver<T extends ComponentItemMeta> = (
originMeta: Partial<T>,
options: {
ts: typeof import('typescript/lib/tsserverlibrary');
typeChecker: ts.TypeChecker;
schemaOptions: MetaCheckerSchemaOptions;
symbolNode: ts.Expression;
prop: ts.Symbol;
targetNode?: ts.Declaration;
targetType?: ts.Type;
},
) => Partial<T>;
References: ComponentItemMeta, MetaCheckerSchemaOptions
export type UnknownSymbolResolver<
T extends PropertyMetaSchema = PropertyMetaSchema,
> = (options: {
ts: typeof import('typescript/lib/tsserverlibrary');
typeChecker: ts.TypeChecker;
targetSymbol: ts.Symbol;
schemaOptions: MetaCheckerSchemaOptions;
targetNode: ts.Declaration;
}) => Partial<T>;
References: PropertyMetaSchema, MetaCheckerSchemaOptions
Provide component metadata checker services
export declare class TypeCheckService
-
Constructs a new instance of the
TypeCheckService
class
-
Constructs a new instance of the
TypeCheckService
class -
Close the Type checker service
-
Get component metadata through the entry file, this method will automatically filter vue components
-
Get metadata of single component If the component to be obtained is not a vue component, an error will be thrown
-
Get the export
-
only get value export
[!NOTE] It is recommended to define events in props so that you can get complete JSDoc support
Description of the property.
When the prop option default
uses as function, default
will be ignored. In this case, you can use @default
to override it.
defineComponent({
props: {
/**
* @default {}
*/
foo: {
default() {
return {};
},
},
},
});
This is used to distinguish between ordinary functions and function components.
Currently, there are two situations that cannot be automatically recognized as components:
/**
* @component
*/
function InternalComponent(props: { a: string }) {
return h('div', props.a);
}
/**
* @component
*/
export const GenericComponent = defineComponent(
<T>(props: { item: T }) => {
return () => (<div>{item}</div>);
},
);
It needs to be annotated with @component, otherwise it will be recognized as a function
[!NOTE] These release tags cannot take effect in defineEmits
For methods on the component instance itself, use release tags like @public
to expose
defineExpose({
/**
* @public
*/
focus() {},
});
If you set filterExposed
in MetaCheckerOptions to false, those release tags will become invalid.
The component instance of vue will not only expose the properties and methods exposed through
expose
, but also expose the props passed in from the outside.
Properties marked with @ignore
or @internal
will not be checked.
- [x] externalSymbolLinkMap support
- [x] resolve Functional component
- [ ]
resolve Vue class component