Widget
Class: Widget
Defined in: src/modules/widgets/index.d.ts:74
Link
https://tiddlywiki.com/dev/#Widgets
Create a widget object for a parse tree node
- parseTreeNode: reference to the parse tree node to be rendered
- options: see below
Options include:
- wiki: mandatory reference to wiki associated with this render tree
- parentWidget: optional reference to a parent renderer node for the context chain
- document: optional document object to use instead of global document
Extended by
Constructors
Constructor
new Widget(
parseTreeNode,options?):Widget
Defined in: src/modules/widgets/index.d.ts:116
Parameters
parseTreeNode
options?
Returns
Widget
Properties
ancestorCount?
optionalancestorCount:number
Defined in: src/modules/widgets/index.d.ts:105
attributes
attributes:
Record<string,string>
Defined in: src/modules/widgets/index.d.ts:83
children
children:
Widget[]
Defined in: src/modules/widgets/index.d.ts:101
document
document:
IFakeDocument
Defined in: src/modules/widgets/index.d.ts:79
domNodes
domNodes:
Element[]
Defined in: src/modules/widgets/index.d.ts:85
eventListeners
eventListeners:
Record<string, (event) =>undefined|Promise<void> |boolean[]>
Defined in: src/modules/widgets/index.d.ts:89
parentDomNode?
optionalparentDomNode:Element
Defined in: src/modules/widgets/index.d.ts:87
parentWidget?
optionalparentWidget:Widget
Defined in: src/modules/widgets/index.d.ts:81
parseTreeNode
parseTreeNode:
IParseTreeNode
Defined in: src/modules/widgets/index.d.ts:75
qualifiers?
optionalqualifiers:Record<string,string>
Defined in: src/modules/widgets/index.d.ts:103
variables
variables:
Record<string,IWidgetVariable>
Defined in: src/modules/widgets/index.d.ts:114
Set the value of a context variable
- name: name of the variable
- value: value of the variable
- params: array of
{name: string, default: string}for each parameter - isMacroDefinition: true if the variable is set via a \define macro pragma (and hence should have variable substitution performed)
widgetClasses
widgetClasses:
Record<string, typeofWidget>
Defined in: src/modules/widgets/index.d.ts:99
we can use $tw.rootWidget.widgetClasses.xxx to new a widget
This is a set of all widgets defined in tiddlywiki.
wiki
wiki:
Wiki
Defined in: src/modules/widgets/index.d.ts:77
Methods
addEventListener()
addEventListener(
type,handler):void
Defined in: src/modules/widgets/index.d.ts:415
Add an event listener.
If the handler is sync, then should return a boolean, false means the event is handled and don't propagate, and true will be dispatched to the parent widget.
If the handler is async, then it is always propagate to the parent widget.
Parameters
type
string
handler
(event) => boolean | Promise<void>
Returns
void
should propagate to parent widget
addEventListeners()
addEventListeners(
listeners):void
Defined in: src/modules/widgets/index.d.ts:402
Add a list of event listeners from an array [{type:,handler:},...]
See also addEventListener.
Parameters
listeners
object[]
Returns
void
allowActionPropagation()
allowActionPropagation():
boolean
Defined in: src/modules/widgets/index.d.ts:482
Returns
boolean
En
invokeActions will invoke the action widgets that are descendents of the current action widget, if this returns true (by default is true, invocation will propagate through through the child).
Override this method and return false to stop the propagation down, and handle the invocation of child widgets by yourself.
assignAttributes()
assignAttributes(
domNode,options?):any
Defined in: src/modules/widgets/index.d.ts:336
Parameters
domNode
Element
options?
changedAttributes?
Record<string, string>
destPrefix?
string
excludeEventAttributes?
boolean
sourcePrefix?
string
Returns
any
En
Assign the computed attributes of the widget to a domNode options include:
excludeEventAttributes: ignores attributes whose name begins with "on"sourcePrefix: prefix of attributes that are to be directly assigned (defaults to the empty string)destPrefix: prefix to be applied to attribute names that are to be directly assigned (defaults to the empty string)changedAttributes: hashmap by attribute name of attributes to process (if missing, process all attributes)
Zh
将微件的计算属性分配给一个 domNode, 选项包括:
excludeEventAttributes: 忽略名称以 "on "开头的属性sourcePrefix: 要直接分配的属性的前缀（默认为空字符串）destPrefix: 要应用到直接分配的属性名称的前缀（默认为空字符串）changedAttributes: 按属性名称的哈希图，要处理的属性（如果缺失，处理所有属性） 一些特殊的属性：xlink:<xlink-name>style.<css-style-name>
Memberof
Widget
computeAttribute()
computeAttribute(
attribute):string
Defined in: src/modules/widgets/index.d.ts:276
Parameters
attribute
string
Returns
string
computeAttributes()
computeAttributes(
options?):Record<string,true>
Defined in: src/modules/widgets/index.d.ts:272
Parameters
options?
Options
filterFn?
(name) => boolean
only include attributes where filterFn(name) returns true
Returns
Record<string, true>
Object with keys of the names of the attributes that have changed
En
Compute the current values of the attributes of the widget. Returns a hashmap of the names of the attributes that have changed
Zh
计算微件的属性的当前值。返回一个已经改变的属性名称的哈希图
Memberof
Widget
dispatchEvent()
dispatchEvent(
widgetEvent):void
Defined in: src/modules/widgets/index.d.ts:432
Dispatch an event to a widget. If the widget doesn't handle the event then it is also dispatched to the parent widget
Events added via addEventListener, like tm-notify, can be invoked by this.
Parameters
widgetEvent
Omit<IWidgetEvent, "widget"> & object
Returns
void
evaluateMacroModule()
evaluateMacroModule(
name,actualParameters,defaultValue):string
Defined in: src/modules/widgets/index.d.ts:232
Parameters
name
string
actualParameters
defaultValue
string
Returns
string
execute()
execute():
void
Defined in: src/modules/widgets/index.d.ts:159
Compute the internal state of the widget.
This will be automatically called in the render method.
For example, getAttribute and set them to class members.
Returns
void
findChildrenDataWidgets()
findChildrenDataWidgets(
children,tag,callback):void
Defined in: src/modules/widgets/index.d.ts:543
Parameters
children
Widget[]
The children widgets to search
tag
string
The tag name to search for (e.g., "$data")
callback
(widget) => void
Callback function called for each found widget
Returns
void
En
Find child <$data> widgets recursively. The tag name allows aliased versions of the widget to be found too
Zh
递归查找子 <$data> widgets。标签名称允许查找该 widget 的别名版本
Memberof
Widget
findFirstDomNode()
findFirstDomNode():
Element
Defined in: src/modules/widgets/index.d.ts:454
Find the first DOM node generated by a widget or its children
Returns
Element
findNextSiblingDomNode()
findNextSiblingDomNode(
startIndex?):Element
Defined in: src/modules/widgets/index.d.ts:449
Find the next sibling in the DOM to this widget. This is done by scanning the widget tree through all next siblings and their descendents that share the same parent DOM node
Parameters
startIndex?
number
Refer to this widget by its index within its parents children
Returns
Element
getAncestorCount()
getAncestorCount():
number
Defined in: src/modules/widgets/index.d.ts:355
Returns
number
number of ancestor widgets for this widget
En
Get the number of ancestor widgets for this widget
Zh
获取这个微件的祖先微件的数量
Memberof
Widget
getAttribute()
Call Signature
getAttribute(
name):string
Defined in: src/modules/widgets/index.d.ts:311
Parameters
name
string
attribute name, for example, actions in the button widget
Returns
string
parameters
En
Get parameters that user set in the widget
Zh
获取用户在小组件中设置的参数
Memberof
Widget
Call Signature
getAttribute(
name,fallbackText):string
Defined in: src/modules/widgets/index.d.ts:312
Parameters
name
string
attribute name, for example, actions in the button widget
fallbackText
string
default value if the attribute is not set
Returns
string
parameters
En
Get parameters that user set in the widget
Zh
获取用户在小组件中设置的参数
Memberof
Widget
getStateQualifier()
getStateQualifier(
name):string
Defined in: src/modules/widgets/index.d.ts:259
Parameters
name
string
Returns
string
En
Construct a qualifying string based on a hash of concatenating the values of a given variable in the parent chain
Zh
在连接父链中给定变量值的哈希基础上构建一个限定字符串
Memberof
Widget
getVariable()
getVariable(
name,options?):string
Defined in: src/modules/widgets/index.d.ts:220
Simplified version of getVariableInfo() that just returns the text
Parameters
name
string
options?
Returns
string
getVariableInfo()
getVariableInfo(
name,options?):object
Defined in: src/modules/widgets/index.d.ts:207
Get the prevailing value of a context variable
Parameters
name
string
variable name, for example, currentTiddler in the widget context
options?
options for getVariableInfo()
Options include
- params: array of
{name: string, default: string}for each parameter - defaultValue: default value if the variable is not defined
- source: optional source iterator for evaluating function invocations
- allowSelfAssigned: if true, includes the current widget in the context chain instead of just the parent
Returns an object with the following fields:
- params: array of
{name:,value:}of parameters passed to wikitext variables - text: text of variable, with parameters properly substituted
- resultList: result of variable evaluation as an array
- srcVariable: reference to the object defining the variable
Returns
object
isCacheable?
optionalisCacheable:boolean
params?
optionalparams:IWidgetVariableParameter[]
srcVariable?
optionalsrcVariable:IWidgetVariable
text
text:
string
hasAttribute()
hasAttribute(
attribute):boolean
Defined in: src/modules/widgets/index.d.ts:287
Parameters
attribute
string
Returns
boolean
En
Check for the presence of an evaluated attribute on the widget. Note that attributes set to a missing variable (ie attr=<<missing>>) will be treated as missing
Zh
检查微件上是否存在一个已评估的属性。请注意，设置为缺失变量的属性（即attr=<<missing>>）将被视为缺失。
Memberof
Widget
hasParseTreeNodeAttribute()
hasParseTreeNodeAttribute(
attribute):boolean
Defined in: src/modules/widgets/index.d.ts:298
Parameters
attribute
string
Returns
boolean
En
Check for the presence of a raw attribute on the widget parse tree node. Note that attributes set to a missing variable (ie attr=<<missing>>) will NOT be treated as missing
Zh
检查微件解析树节点上是否存在原始属性。注意，设置为缺失变量的属性（即ttr=<<missing>>）不会被视为缺失。
Memberof
Widget
hasVariable()
hasVariable(
name,value):boolean
Defined in: src/modules/widgets/index.d.ts:248
Parameters
name
string
value
string
Returns
boolean
En
Check whether a given context variable value exists in the parent chain
Zh
检查一个给定的上下文变量值是否存在于父链中
Memberof
Widget
initialise()
initialise(
parseTreeNode,options?):void
Defined in: src/modules/widgets/index.d.ts:127
Parameters
parseTreeNode
options?
Returns
void
En
Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses
Zh
初始化 widget 属性。这些步骤被拉出构造函数，以便我们可以在子类中重复使用它们
invokeAction()?
optionalinvokeAction(triggeringWidget,event):boolean
Defined in: src/modules/widgets/index.d.ts:472
Invoke the action associated with this widget
No every widget has this method, but some do, like action-xxx widget, e.g., action-sendmessage
Parameters
triggeringWidget
Widget
event
Returns
boolean
handled
invokeActions()
invokeActions(
triggeringWidget,event):boolean
Defined in: src/modules/widgets/index.d.ts:493
Parameters
triggeringWidget
Widget
event
Returns
boolean
handled, means some action is invoked.
En
Invoke the action widgets that are descendents of the current widget. The invocation will propagate through the child, unless some widget on the middle have allowActionPropagation to return false.
Memberof
Widget
invokeActionsByTag()
invokeActionsByTag(
tag,event?,variables?):void
Defined in: src/modules/widgets/index.d.ts:526
Parameters
tag
string
The tag to filter action tiddlers
event?
The widget event
variables?
Record<string, string>
Optional variables to pass to the action string
Returns
void
En
Execute action tiddlers by tag
Zh
按标签执行 action tiddlers
Memberof
Widget
invokeActionString()
invokeActionString(
actions,triggeringWidget?,event?,variables?):boolean
Defined in: src/modules/widgets/index.d.ts:508
Parameters
actions
string
triggeringWidget?
Widget
(this is unused, passing undefined is OK)
event?
variables?
Record<string, string>
Returns
boolean
handled, the return of invokeActions, means some action is invoked.
En
Invoke the action widgets defined in a string
This calls invokeActions under the hood
Memberof
Widget
makeChildWidget()
makeChildWidget(
parseTreeNode,options?):Widget
Defined in: src/modules/widgets/index.d.ts:372
Construct the widget object for a parse tree node, and return the new widget options include: variables: optional hashmap of variables to wrap around the widget
Parameters
parseTreeNode
options?
variables?
unknown
Returns
Widget
makeChildWidgets()
makeChildWidgets(
parseTreeNodes?,options?):void
Defined in: src/modules/widgets/index.d.ts:362
Make child widgets correspondng to specified parseTreeNodes
And push them to this.children
Parameters
parseTreeNodes?
default to this.parseTreeNode.children, can be undefined
options?
variables?
unknown
Returns
void
makeFakeWidgetWithVariables()
makeFakeWidgetWithVariables(
variables):Widget
Defined in: src/modules/widgets/index.d.ts:554
Make a fake widget with specified variables, suitable for variable lookup in filters
Parameters
variables
Record<string, string>
Returns
Widget
nextSibling()
nextSibling():
Widget
Defined in: src/modules/widgets/index.d.ts:383
Returns
Widget
En
Get the next sibling of this widget
Memberof
Widget
previousSibling()
previousSibling():
Widget
Defined in: src/modules/widgets/index.d.ts:391
Returns
Widget
En
Get the previous sibling of this widget
Memberof
Widget
refresh()
refresh(
changedTiddlers):boolean
Defined in: src/modules/widgets/index.d.ts:151
Parameters
changedTiddlers
Object key is tiddler title, value is metadata about the change
Returns
boolean
En
Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering. You can do some cleanup or buildup before return true.
Zh
如果需要的话，有选择地刷新该微件。如果该微件或其任何子项需要重新渲染，则返回 true。 你可以在返回 true 之前做一些清理或构建工作。
Link
https://tiddlywiki.com/dev/#Selective%20Update
refreshChildren()
refreshChildren(
changedTiddlers?):boolean
Defined in: src/modules/widgets/index.d.ts:443
Refresh all the children of a widget, will call this.render.
Need to call this after setVariable
Parameters
changedTiddlers?
Returns
boolean
refreshSelf()
refreshSelf():
void
Defined in: src/modules/widgets/index.d.ts:437
Rebuild a previously rendered widget
Returns
void
removeChildDomNodes()
removeChildDomNodes():
void
Defined in: src/modules/widgets/index.d.ts:462
Remove any DOM nodes created by this widget or its children
If this widget has directly created DOM nodes, delete them and exit. This assumes that any child widgets are contained within the created DOM nodes, which would normally be the case. Otherwise, ask the child widgets to delete their DOM nodes
Returns
void
removeEventListener()
removeEventListener(
type,handler):void
Defined in: src/modules/widgets/index.d.ts:423
Remove an event listener
Parameters
type
string
handler
(event) => boolean | Promise<void>
Returns
void
removeLocalDomNodes()
removeLocalDomNodes():
void
Defined in: src/modules/widgets/index.d.ts:549
Returns
void
render()
render(
parent,nextSibling):void
Defined in: src/modules/widgets/index.d.ts:139
Parameters
parent
Element
nextSibling
Element
Returns
void
En
Lifecycle method: Render this widget into the DOM
Zh
生命周期方法：将这个微件渲染到 DOM 中; 只会在首次渲染、销毁后重新渲染时自动调用，或者通过 refreshSelf 等方法主动调用
renderChildren()
renderChildren(
parent,nextSibling):void
Defined in: src/modules/widgets/index.d.ts:396
Render the children of this widget into the DOM
Parameters
parent
Element
nextSibling
Element
Returns
void
resolveVariableParameters()
resolveVariableParameters(
formalParameters?,actualParameters?):IWidgetVariableParameter[]
Defined in: src/modules/widgets/index.d.ts:222
Parameters
formalParameters?
actualParameters?
Returns
setVariable()
setVariable(
name,value,parameters?,isMacroDefinition?,options?):void
Defined in: src/modules/widgets/index.d.ts:177
Parameters
name
string
name of the variable
value
string
value of the variable
parameters?
isMacroDefinition?
boolean
true if the variable is set via a \define macro pragma (and hence should have variable substitution performed)
options?
Additional options
configTrimWhiteSpace?
boolean
whether to trim whitespace
isFunctionDefinition?
boolean
true if the variable is set via a \function pragma
isProcedureDefinition?
boolean
true if the variable is set via a \procedure pragma
isWidgetDefinition?
boolean
true if the variable is set via a \widget pragma
Returns
void
En
Set the value of a context variable
Zh
设置一个上下文变量的值
substituteVariableReferences()
substituteVariableReferences(
text,options):string
Defined in: src/modules/widgets/index.d.ts:227
Parameters
text
string
options
variables
Record<string, string>
Returns
string
evaluateVariable()
staticevaluateVariable(widget,name,options?):string[]
Defined in: src/modules/widgets/index.d.ts:569
Parameters
widget
Widget
The widget context for variable lookup
name
string
The variable name to evaluate
options?
Options for variable evaluation
Returns
string[]
Array of result strings
En
Evaluate a variable with parameters. This is a static convenience method that attempts to evaluate a variable as a function, returning an array of strings
Zh
使用参数评估变量。这是一个静态便捷方法，尝试将变量作为函数评估，返回字符串数组
Static
Memberof
Widget